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

[Vitaly Ostanin]

On Thu, 16 Jan 2003 16:47:03 +0300
"Anton V. Boyarshinov" <boyarsh на ru.echo.fr> wrote:

Здравствуйте!

> Добрый день
> 
> У меня есть несколько идей по ограницации документации на
> будущее.
> 
> 1. Все документы создаются как section. Возможно кроме
> некоторых, но исключения должны осбкждаться каждый раз
> отдельно. Перед сборкой они обрабатываются дополнительным
> стилем (в дополнение к существующему tuning.xsl) для создания
> корректной структуры.

То есть уровень вложенности документа в резальтирующем наборе
будет определяться глубиной вложенности в каталогах? Как будут
создаваться собирающие документы, например, пустая part для
нескольких chapter ?

В DocBook TC есть особенность, которая мне очень нравится - перед
принятием решения они тщательно его продумывают, описывают
content model и возможные последствия. Предлагаю по возможности
делать так же :)

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

> Стиль должен допускать конфигурирование в широких пределах, для
> того, чтобы можно было указать корневой тэг (book, article ...)
> а также управлять внутренней структурой (например делать ли
> части или за book должны следовать сразу главы, выделять ли
> первый раздел в preface и т. п.). Таким образом, мы получаем
> гибкость в объединении материалов и нам не придётся менять
> вручную doctype при изменении положения метериала.

Я пока плохо представляю, как это может выглядеть. Можно
объяснить подробнее для тех, кто в танке? :)

> 2. Следует определить entety &DISTR; (имя дискутабельно, но не
> стоит делать его слишком длиным) и продумать механизм лёгкого
> измененмия его значения. Все ссылки на текущий дистрибутив
> должны делаться только через него.

Можно указать его в public entities, и при сборке менять его
значение в дистрибивной ветке.

<skipped/>

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