[docs] Возможная организация документации

Anatoly Yakushin doc_jaa на mail.ru
Пт Янв 17 00:51:20 MSK 2003


Anton V. Boyarshinov пишет:
> Добрый день
> 
> У меня есть несколько идей по ограницации документации на
> будущее.
> 
> 1. Все документы создаются как section. Возможно кроме некоторых,
> но исключения должны осбкждаться каждый раз отдельно. Перед
> сборкой они обрабатываются дополнительным стилем (в дополнение к
> существующему tuning.xsl) для создания корректной структуры.
> Стиль должен допускать конфигурирование в широких пределах, для
> того, чтобы можно было указать корневой тэг (book, article ...) а
> также управлять внутренней структурой (например делать ли части
> или за book должны следовать сразу главы, выделять ли первый
> раздел в preface и т. п.). Таким образом, мы получаем гибкость в
> объединении материалов и нам не придётся менять вручную doctype
> при изменении положения метериала.
> 
> 2. Следует определить entety &DISTR; (имя дискутабельно, но не
> стоит делать его слишком длиным) и продумать механизм лёгкого
> измененмия его значения. Все ссылки на текущий дистрибутив должны
> делаться только через него.
> 
> Антон
Антон, а можно еще одно предложение. :)
Может быть стоит размечать документы в docbook после литературной 
правки, но никак не раньше.
А вычитывать plain text.
В принципе, насколько я помню издательское дело, там так и происходит.
Набор - корректура - верстка.
А то, как показал опыт, правка уже размеченного документа - дело очень 
непростое.

-- 
Rgrds,
Anatoly A. Yakushin aka DOC
Orthopaedic departmen
Veteran's Hospital # 3
Moscow





Подробная информация о списке рассылки docs