Правила оформления документа
В этом разделе перечислены правила, которых следует придерживаться при написании статей для включения в Cyrillic-HOWTO-russian.
По большей части эта информация предназначена для мантейнера, так как документ довольно сильно разросся и приведении всех его частей к единому стилю становится значительной проблемой
В качестве основного формата документа выбран XML. Причиной данного выбора обуславливается историческими причинами. Изначально документ был написан в формате linuxdoc. Для преобразования в другие форматы для публикации приходилось пользоваться пакетом sgml-tools. Развитие этого пакета полностью заморожено. Для работы с кириллическими символами требовался напильник. Для корректной работы с XML уже почти есть всё необходимое, но опять же пока существует масса трудностей и на текущей стадии возможно корректное преобразование только в HTML.
Документ разбит на несколько файлов. Головном файле подключаются главы, каждая из которых лежит в своей директории. Для определения формата в начале каждого файла пишется заголовок
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
В качестве базового дистрибутива используется ALT Linux Master. Для конвертации XML в форматы публикации используется docbook-style-xsl из ,,Сизифуса'' от AltLinux.
Сборка осуществляется через Makefile. По команде make dist выполняется сборка дистрибутива для дальнейшего распространения. Makefile написан в предположении, что стили находятся в директории /usr/share/xml/docbook/xsl-stylesheets.
Файл редактируется с помощью редактора emacs (раздел “Emacs и XEmacs”). Для облегчения редактирования используется пакет psgml. Для быстрого разбора DTD используется compiled DTD— Cyrillic-HOWTO-russian.ced, который получается с помощью команды M^x sgml-save-dtd. Для того чтобы указать emacs, чтобы использовать этот файл, вместо разбора стандартного DTD, в конце каждого файла следует добавить
<!-- Keep this comment at the end of the file Local variables: mode: xml sgml-omittag:nil sgml-shorttag:nil sgml-namecase-general:nil sgml-general-insert-case:lower sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:2 sgml-indent-data:nil sgml-parent-document:nil sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil sgml-default-dtd-file:"../Cyrillic-HOWTO-russian.ced" sgml-recompile-out-of-date-cdtd:t End: -->
Переменная sgml-default-dtd-file указывает на сохранённый DTD, отличная от nil переменная sgml-recompile-out-of-date-cdtd показывает, что в случае несоответствия DTD установленному в системе его следует пересобрать.
Для проверки валидности документа можно воспользоваться встроенной командой emacs: C^c C^v. XML обязан пройти эту проверку прежде чем его можно преобразовывать в какой-либо другой формат.
Первый уровень primary должен начинаться с большой буквы, все последующие с маленькой.