Принципы создания документов для ALT Linux Team Documentation

Vitaly Ostanin

<vyt@vzljot.ru> JID: vyt@vzljot.ru

История переиздания
Издание 0.917 Jul 2002
Исправлены ссылки на "profiling".
Издание 0.808 Jul 2002
Изменены примеры для проверки документов, убрана информация про цель "dropdtd", которая больше не используется, это описано в разделе "Помещение документов в CVS".
Издание 0.704 Jul 2002
Добавлены примеры в раздел "Добро пожаловать".
Издание 0.602 Jul 2002
Использование буквы 'ё' вместо замены на 'е'. Короткие тире заменены на длинные. Изменён раздел "Помещение документов в CVS", убрана клевета на xmllint про отсутствие сущностей при "dropdtd". В инструментах для работы с XML itemizedlist заменён на glosslist. Обновлён раздел "Добро пожаловать".
Издание 0.512 Jun 2002
Изменён раздел "Помещение документов в CVS", убрано требование с префиксами в именах документов.
Издание 0.402 Jun 2002
Изменён раздел "Помещение документов в CVS", добавлен раздел "Информация о DocBook/XML 4.1.2", дополнены разделы "Инструменты для создания документов" и "Добро пожаловать". Исправление опечаток.
Издание 0.328 May 2002
Добавлено указание на alt-doc-template, изменены требования к названиям документов в CVS, добавлен контактный адрес для участия в создании документации. Изменён раздел "Оформление документов".
Издание 0.221 May 2002
Добавлено внешнее подключение определений, описание этого в разделе "Оформление документов", добавлены ссылки в тексте. Убраны абсолютные имена в Makefile, указание charset в README и TODO.
Издание 0.121 May 2002
Начальный вариант, наброски для ALT Linux Team Documentation

Обоснование выбора DocBook/XML 4.1.2

После очередного ответа на повторяющиеся вопросы стало, наконец, ясно, что информация есть — её нужно упорядочить и сделать доступной. Для упорядочивания и структурирования информации хорошо подходит формат DocBook/XML 4.1.2. XML — это подмножество SGML и Docbook — тип документа (DTD), разработанный для написания документации. Существуют DTD Docbook для XML и SGML, но выбран именно XML, как более прогрессивный.

Этот формат для документации является аналогом исходных кодов для программ, однажды созданный документ можно преобразовывать в другие форматы, например, html, pdf, rtf, tex, man, dvi, ps и другие. Инструменты обработки DocBook/XML 4.1.2 автоматизируют создание индексов, оглавлений, перекрёстных ссылок, включение внешних документов, изменения сущностей средствами языков преобразований (DSSSL и XSL) и многое другое — более детальную информацию можно найти в разделе Информация о DocBook/XML 4.1.2.

Другие предлагавшиеся форматы, например, LaTeX, являются ориентированными на определённое использование и поэтому не подходят для создания универсальной документации. DocBook/XML 4.1.2 используется для смысловой разметки текста, поэтому конвертация в него из других форматов недопустима.

Замечание

Документация должна быть корректно написана и структурирована, и НЕ должна ориентироваться на способ публикации, печатный или сетевой.

Существуют гибкие средства преобразования документов в формате DocBook/XML 4.1.2, позволяющие из одного и того же документа получать результаты для разных целей. Например, можно помечать часть текста как общую, часть — как специфичную для ALT Linux Team, и получать как универсальный, так и специфичный для ALT результат. Такой приём называется Profiling. В DocBook/XML 4.1.2 стоит создавать только структурированные, продуманные документы, которые будут развиваться и использоваться длительное время, для простых текстов, например, электронных писем, он слишком трудоёмок.



Наш баннер
Вы можете установить наш баннер на своем сайте или блоге, скопировав этот код:
RSS новости