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

[Anton V. Boyarshinov]

On Fri, 17 Jan 2003 15:00:13 +0300 Vitaly Ostanin
 wrote:

> On Thu, 16 Jan 2003 16:47:03 +0300
> "Anton V. Boyarshinov" <boyarsh на ru.echo.fr> wrote:
> 
> Здравствуйте!
> 
> > Добрый день
> > 
> > У меня есть несколько идей по ограницации документации на
> > будущее.
> > 
> > 1. Все документы создаются как section. Возможно кроме
> > некоторых, но исключения должны осбкждаться каждый раз
> > отдельно. Перед сборкой они обрабатываются дополнительным
> > стилем (в дополнение к существующему tuning.xsl) для создания
> > корректной структуры.
> 
> То есть уровень вложенности документа в резальтирующем наборе
> будет определяться глубиной вложенности в каталогах?

Не в каталогах, а в собираемом документе. То есть, корневой
section превращается в book, вложенные в него в part (или
chapter), вложенные в них в chapter (или остаются section).

Каталоги исползуются для удобного структурирования при
разработке, но итоговый документ не обязан следовать их иерархии.
Для разных документов роль файла может быть разной.

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

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

Вот мы и продумываем. 

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

Глубокого смыслового различия между глваой и чатью я не вижу. Всё
зависит от собираемого документа. Напомниаю: мы собираем из одних
и тех же исходников РАЗНЫЕ документы, отличающиеся в том числе и
структурой.
 
> > Стиль должен допускать конфигурирование в широких пределах,
> > для того, чтобы можно было указать корневой тэг (book,
> > article ...) а также управлять внутренней структурой
> > (например делать ли части или за book должны следовать сразу
> > главы, выделять ли первый раздел в preface и т. п.). Таким
> > образом, мы получаем гибкость в объединении материалов и нам
> > не придётся менять вручную doctype при изменении положения
> > метериала.
> 
> Я пока плохо представляю, как это может выглядеть. Можно
> объяснить подробнее для тех, кто в танке? :)

Как должно выглядеть конфигурирование я ещё не до конца продумал.
Подробнее о сути преобразования я написал выше.

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

Да, именно так, важно лишь, что бы файл с entities брался с диска
из этого же рабочего каталога (в терминах cvs), а не из сети и не
из соседнего рабочего каталога, который может оказаться прописан
в XML catalog.

Антон
-- 
mailto:boyarsh на mail.ru
mailto:boyarsh на ru.echo.fr
  3:00pm  up 52 days, 21:07,  9 users,  load average: 0.13, 0.07,
0.02