Русский перевод Михаил Сгибнев
Содержание
- C.1. Что такое XML/DocBook
- C.2. Установка необходимых инструментов
- C.3. Использование утилит
- C.4. Языковая специфика
- C.5. Ссылки
В этом разделе описывается установка инструментария, необходимого для форматирования руководства NetBSD. Помимо этого, здесь содержатся инструкции по написанию руководства. Эта глава предполагает знание системы pkgsrc, дополнительную информацию по которой содержит Глава 30, Коллекция пакетов.
C.1. Что такое XML/DocBook
XML (eXtensible Markup Language) является языком для определения других языков, основанных на разметке, то есть с помощью XML вы можете определить грамматику (допустимые конструкции) языка разметки. Например, с помощью XML можно определить HTML. Если вы — программист, то думайте о XML подобно BNF (Backus-Naur Form): это инструмент, предназначенный для определения грамматики.
DocBook представляет собой шаблон разметки, определенный с помощью XML; DocBook содержит список допустимых тегов, которые могут использоваться в документах формата DocBook, и описание их возможных комбинаций. Например, если встречается тег:
<para> ... </para>
то определяется параграф, при этом <para> может быть внутри <sect1>, но <sect1> не может находится внутри <para>.
Поэтому, когда вы пишете документ, вы пишете документ в DocBook а не в XML: в этом отношении DocBook похож на HTML (хотя имеет более обширные возможности и отличается некоторыми понятиями).
Спецификация DocBook (то есть список тегов и правил) называется DTD (Document Type Definition).
Если говорить кратко, то в DTD определяется вид вашего документа, но ни слова не говорится о формате конечного документа. В последующем требуется конвертация исходных текстов DocBook в, например, HTML или PDF. Этот этап выполняется инструментами типа Jade, с помощью которых в зависимости от DSSSL указаний происходят преобразования исходного документа. DSSSL (Document Style Semantics and Specification Language) представляет собой спецификацию языка, используемого для определения таблиц стилей, необходимых для преобразования DocBook в другие форматы. Инфраструктура сборки руководства также поддерживает таблицу стилей языка XSL (Extensible Stylesheet Language). Утилита xsltproc используется для XML преобразований, используя таблицы стилей XSL.
C.2. Установка необходимых инструментов
Все инструменты, необходимые для сборки руководства в различных форматах, могут быть легко установлены, как мета-пакеты netbsd-www, netbsd-doc и netbsd-doc-print. Совместно установленные пакеты netbsd-doc и netbsd-www обеспечивают сборку HTML-версии руководства. Для того, чтобы получить руководство в формате, пригодном для печати (Postscript и PDF), установите мета-пакет netbsd-doc-print.
$cd /usr/pkgsrc/meta-pkgs/netbsd-www$make install$cd /usr/pkgsrc/meta-pkgs/netbsd-doc$make install$cd /usr/pkgsrc/meta-pkgs/netbsd-doc-print$make install
C.3. Использование утилит
Сейчас мы рассмотрим методику компиляции руководства из XML в другие форматы: html, html-split, ascii, ps и pdf. Для указания результирующего формата запустите команду make с указанием формата в качестве аргумента.
Давайте рассмотрим несколько примеров.
Перед тем как мы увидим вывод в любом из вышеприведенных форматах, необходимо обеспечить целостность структуры XML. Это делается с помощью команды make lint:
$cd htdocs/guide/en$make lint
Исправьте все обнаруженные ошибки. При работе с содержанием руководства вы можете сделать HTML-версию для того, чтобы выполнить корректуру.
$cd htdocs/guide/en$make html-split
После этого, пожалуйста, обновите PostScript и PDF версии руководства. Для этого выполните команду:
$cd htdocs/guide/en$make pdf
Прежде, чем вы выгрузите в репозиторий сгенерированные файлы, удостоверьтесь, что вы уже выгрузили файлы в формате XML. В общем случае, это будет выглядеть приблизительно так:
$cd htdocs/guide/en$cvs commit *.xml$$make lint$make$make install-doc$$cd ..$cvs commit en download
Когда make выполняется без аргументов, будут сгенерированы все форматы. Этот вариант по умолчанию используется для сборки руководства на сайте NetBSD.org
C.4. Языковая специфика
C.4.1. Возможность переноса слов в Итальянском варианте
Руководство для NetBSD в настоящий момент доступно на трех языках: английский, французский и итальянский. Но автоматический перенос слов в TeX реализован только для английского и французского языков. Для включения переноса слов итальянского языка необходимо выполнить несколько простых шагов:
Отредактировать файл /usr/pkg/share/texmf/tex/generic/config/language.dat и удалить признак комментария (%) из строки с итальянским языком. То есть:
%italian ithyph.tex
будет выглядеть как:
italian ithyph.tex
Замечание
По мере появления переводов руководства на другие языки, вам, возможно, понадобится включить поддержку переносов и для них.
Теперь необходимо пересоздать форматы latex и pdflatex:
#cd /usr/pkg/share/texmf/web2c#fmtutil --byfmt latex#fmtutil --byfmt pdflatex
Если вы проверите, для примера, latex.log, вы там увидите строку типа:
Babel <v3.6Z> and hyphenation patterns for american, french, german, ngerman, italian, nohyphenation, loaded.
Обратите внимание, что в зависимости от ваших знаний системы TeX (мои очень низкие), эта задача может быть решена массой других способов. Например, вы можете использовать интерактивную программу «texconfig» или же обновить форматы вручную, используя программу tex.
Если вам известен лучший способ корректной настройки переносов (или других вещей, описанных в этом приложении), пожалуйста, сообщите мне.
C.5. Ссылки
На официальной странице проекта DocBook вы можете найти исчерпывающую документацию по DocBook. Книга Нормана Уолша (Norman Walsh) и Леонарда Мюльнера (Leonard Muellner) DocBook: The Definitive Guide доступна как для загрузки, так и для интерактивного чтения.
Хорошим начальным источником информации о DSSSL выступает сайт http://nwalsh.com.
Описание XSL находится по адресу http://www.w3.org/Style/XSL/.
Исходные тексты и документация по Jade/OpenJade может быть найдена на домашней странице проекта OpenJade.
Если у вас есть желание подготавливать документацию в форматах PostScript или PDF из текстов DocBook, посетите страницу JadeTex.
На домашней странице Маркуса Хоенички (Markus Hoenicka) содержится информация по работе с SGML/DocBook на платформе Windows NT.