| Учебник по Проекту Документирования FreeBSD для новых участников | ||
|---|---|---|
| Пред. | Глава 6. Структурирование документов в doc/ | След. |
Этот раздел содержит специфичные замечания о конкретных документах, управляемых FDP.
Руководство написано в соответствии с расширенным во FreeBSD DocBook DTD.
Руководство организовано в виде <book> (книги) DocBook. Затем она делится на части (<part>), каждая из которых может содержать несколько глав (<chapter>). Главы, в свою очередь, делятся на разделы (<sect1>) и подразделы (<sect2>, <sect3>) и так далее.
В каталоге handbook расположено некоторое количество файлов и подкаталогов.
Замечание: С течением времени организация Руководства может меняться, и этот документ может отставать в описании организационных изменений. Если у вас есть вопросы по организации Руководства, пожалуйста, обратитесь в Список рассылки Проекта Документации FreeBSD.
Makefile задает некоторые переменные, которые влияют на преобразование исходных текстов SGML в другие форматы, и в нем перечисляются различные исходные файлы, которые составляют Руководство. Затем в него включается стандартный файл doc.project.mk, содержащий остальной код, отвечающий собственно за преобразование одного формата в другой.
Для Руководства это документ самого верхнего уровня. Он содержит декларацию DOCTYPE для Руководства, а также элементы, описывающие его структуру.
book.sgml использует параметризованные сущности для загрузки файлов с расширением .ent. Эти файлы (описываемые далее), в свою очередь, определяют сущности общего назначения, используемые в дальнейшем во всем Руководстве.
Каждая глава Руководства хранится в файле с именем chapter.sgml в отдельном каталоге. Каждый каталог именуется в соответствии с атрибутом id элемента <chapter>.
Например, если файл с текстом главы содержит:
<chapter id="kernelconfiguration"> ... </chapter>
то он будет называться chapter.sgml и располагаться в каталоге kernelconfiguration. В общем случае в этом файле будет содержаться полный текст главы.
При генерации версии Руководства в формате HTML получится файл kernelconfiguration.html. Это имя соответствует значению id, и не связано с названием каталога.
В ранних версиях Руководства файлы хранились в том же самом каталоге, что и book.sgml, и именовались в соответствии с атрибутом id элемента <chapter> из этого файла. Перемещение их в отдельные каталоги связано с дальнейшими планами по развитию Руководства. В частности, вскоре будет возможно включать рисунки в каждую главу. Более правильно хранить каждый рисунок в каталоге с текстом главы, чем пытаться хранить и текст, и рисунки для всех глав в одном большом каталоге. Можно будет избежать совпадений имен, и гораздо легче работать с несколькими каталогами с небольшим количеством файлов в них, чем с одним каталогом со многими файлами.
Если посмотреть, то здесь много каталогов с отдельными файлами chapter.sgml в них, включая basics/chapter.sgml, introduction/chapter.sgml и printing/chapter.sgml.
Важно: Главы и/или каталоги каталоги не обязательно должны именоваться образом, отражающим их следование в Руководстве. Их порядок может измениться при организационных изменениях внутри Руководства; такой тип реорганизации не должен (обычно) включать необходимость в переименовании файлов (если только главы не были удалены или перемещены по иерархии).
Каждый файл chapter.sgml не будет являться полным документом SGML. В частности, в них нет собственных строк DOCTYPE в начале файла.
Это не так уж хорошо, так как с ними невозможно будет работать как обычными файлами SGML и просто преобразовать их в HTML, RTF, PS и другие форматы так же, как это делается с Руководством. Это заставляет вас перестраивать Руководство каждый раз, когда вы хотите видеть результат изменений только в одной главе.
| Пред. | Начало | След. |
| Каталоги lang.encoding/ | Уровень выше | Процесс построения документации |
Этот, и другие документы, могут быть скачаны с ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.
По вопросам, связанным с FreeBSD, прочитайте документацию прежде чем писать в <questions@FreeBSD.org>.
По вопросам, связанным с этой документацией, пишите <doc@FreeBSD.org>.
По вопросам, связанным с русским переводом документации, пишите в рассылку <frdp@FreeBSD.org.ua>.
Информация по подписке на эту рассылку находится на сайте проекта перевода.