[docs] Re: Форматирование имён авторов

[Vitaly Ostanin]

On Thu, 24 Oct 2002 10:08:47 +0400
"Anton V. Boyarshinov" <boyarsh на ru.echo.fr> wrote:

> Добрый день
> 
> On Wed, 23 Oct 2002 18:18:17 +0400
> Vitaly Ostanin <vyt на vzljot.ru> wrote:
> 
> > > Насколько я понимаю, для html версии не является проблемой,
> > > если авторы будут в соответствующих section, а не в начале
> > > документа.
> > 
> > Для любого выходного формата можно написать стиль, собирающий
> > авторов и помещающий список в начало объединяющего документа.
> Да. Более того, эта часть стиля будет одинакова для всех
> форматов(как одинакова она и в оригинальных стилях). Просто моё
> время ограничего и я сейчас занимаюсь преимущественно стилем
> для печати.

В очередной раз видна потребность в планах и исполнителях...
Есть желающие вести такие данные?

> > Осталось решить, что указывать авторам - нужно ли отчество и
> > на каком языке.
> Я думаю, стоит указывать, так как оторвать его стилями не
> сложно, а вот добавить... Язык, я полагаю, должен совпадать с
> языком документа. С другой стороны -- если кто-то хочет
> подписаться псевдонимом -- это его право.

Псевдоним не придаст доке солидности. А анонимных авторов у нас
вроде бы нету :) Кстати, с псевдонимом и логика сбора будет
сложнее.

Есть подозрение, что придётся делать модификацию DTD с занесением
туда части требований.

<skipped/>

> > Например, доки пересобираются и
> > выкладываются с корректным указанием кодировки. Это очень
> > похоже на переиздания и нужно это отразить в revhostiry.
> 
> Сложный вопрос. Таким образом у нас получается как минимум 2
> истории переиздания: в online и в печатной форме. Как это можно
> совместить -- неясно.

Можно при выпуске печатной версии одновременно обновить
online-версию. Печатная версия будет просто реже издаваться.

Мысль понятна - в исходном документе не должно быть информации о
конечных изданиях.

Ок, давайте тогда сделаем публикации более "официальными" и будем
требовать от авторов обязательного увеличения revision перед
публикацией.

Если автор публикует документ в другом месте (например, на
домашней странице) - он также должен увеличить номер ревизии.

Тогда во время разработки документа автор может заполнять
revremark (описание изменений) в пределах одной ревизии, как
сочтёт нужным.

Технические или небольшие изменения пусть будут в cvs log.

> > Конечно, про
> > "обновления DTD до версии 4.2" и тех. детали можно и не
> > писать- это моё занудство :) 
> 
> Я думаю тут ключевое слово: изменения, которые могут
> заинтересовать читателя.

Понял.

> > Свежесть документа для читателя иногда определяется номером
> > издания (ревизии). Странно издавать разные версии документа с
> > одним и тем же номером.
> 
> Не совсем понял эту мысль....

Публикации документа могут быть разными, те же печатные и
online-версии.

Если revhistory отражает версию публикации, то это странно, так
как в исходном документе не должна храниться информация о
выходных форматах и публикациях.

Если revhistory отражает версию самого документа, то нельзя
публиковать документ, изменять, и публиковать с той же версией.

То есть увидев одну и ту же доку напечатанной или в сети, и
захотев узнать, какая из них последняя (актуальная), можно
посмотреть на номер ревизии. Для этого нужно этот номер
увеличивать при изменениях документа. 

Чтобы не увеличивать его по мелочам и оставить их на долю cvs,
нужно не публиковать документ после "мелочей" и сделать
публикации "официальными".

> > По поводу 2-го <imho/>:
> > revhistory является неплохим способом описания
> > изменений в теле документа, поскольку документ может
> > разрабатываться и публиковаться без доступа к cvs.
> 
> Для этого можно генерировать changelog из cvs.

Ok.

> > Мне, например,
> > не хватает TODO в теле документа :)
> 
> Хотел съязвить, но не придумал, чего бы мне ещё захотеть в теле
> документа;-)

:)) Например, адрес разработки оригинала - чтобы при публикациях
ссылаться на него ("последняя версия находится на...").

> Можно держать TODO в комментарии.

В docs-howto я так и делаю. Может понадобиться собирать TODO из
всех док и показывать в ответ на "чем можно помочь?". Это так,
теория :)

> > Насчёт вывода изменений в начале документа - вот это
> > напрягает, но никто не мешает поправить стили на эту тему.
> > Например, оформлять изменения, как appendix, или вообще
> > выбрасывать.
> 
> В печатной версии -- скорее выбрасывать. Для экономии
> бумаги->денег.

Ок.

PS На стили я пока не смотрел, но есть большая просьба -
комментируйте свои стили, хотя бы логику в общих чертах.
Удобного инструмента отладки XSLT я не нашёл, а самому всё читать
запарно. Пожалуйста :)

<skipped/>

-- 
Regards, Vyt
mailto:  vyt на vzljot.ru
JID:     vyt на vzljot.ru
----------- следущая часть -----------
Было удалено вложение не в текстовом формате...
Имя     : отсутствует
Тип     : application/pgp-signature
Размер  : 189 байтов
Описание: отсутствует
Url     : /pipermail/docs/attachments/20021024/4413b5c6/attachment.bin