В этом разделе перечислены правила, которых следует придерживаться при написании статей для включения в Cyrillic-HOWTO-russian.
По большей части эта информация предназначена для мантейнера, так как документ довольно сильно разросся и приведении всех его частей к единому стилю становится значительной проблемой
В качестве основного формата документа выбран XML. Причиной данного выбора обуславливается историческими причинами. Изначально документ был написан в формате linuxdoc. Для преобразования в другие форматы для публикации приходилось пользоваться пакетом sgml-tools. Развитие этого пакета полностью заморожено. Для работы с кириллическими символами требовался напильник. Для корректной работы с XML уже почти есть всё необходимое, но опять же пока существует масса трудностей и на текущей стадии возможно корректное преобразование только в HTML.
Документ разбит на несколько файлов. Головном файле подключаются главы, каждая из которых лежит в своей директории. Для определения формата в начале каждого файла пишется заголовок
<?xml version="1.0" encoding="koi8-r"?>
<!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 от Norman'а Wolsh'а (требует установки пакетов xml-common, xml-utils и libxml). Конвертация происходит с помощью утилиты xsltproc из одноимённого пакета (требует пакет libxslt). На текущий момент я умею получать только html версию документа. Если вы имеете опыт получения кириллической документации в другом формате, то я буду чрезвычайно благодарен за полученную информацию.
Перечисленные пакеты взяты из репозитория ,,Sisyphus'' от Alt Linux.
Сборка осуществляется через 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 должен начинаться с большой буквы, все последующие с маленькой.