|
Bog BOS: DocBook - язык форматирования |
|
Последние изменения: |
Последнее изменение файла: 2010.10.22
Скопировано с www.bog.pp.ru: 2024.04.19
DocBook - язык форматирования (разметки) текстов для издания больших произведений (книги, справочники, техническая документация). Описывается как приложение SGML (старая школа IBM) или XML (новая школа MS). Позволяет отделить содержимое (текст) от структуры (теги) и оформления (стили преобразования). Особенно полезен при коллективной работе (авторы, редактор, дизайнер) с использованием системы управления версиями (например, subversion) над документами большого объёма, которые необходимо представлять в различных интерактивных и печатных форматах (single source) и с разным уровнем подробности (профилирование) с жёсткими требованиями к соблюдению стиля оформления. Требует значительных усилий для освоения.
Является стандартом OASIS (Organization for the Advancement of Structured Information Standards) с версии 4.5 (W3C XML Schema, Schematron и DTD - Document Type Definition). Текущая версия - 5.0 (RELAX NG schema и Schematron; и кто на неё перешёл?). Документы версий 4 и 5 несовместимы (документ версии 4 можно конвертировать в документ версии 5 с помощью XSLT.
Документация в формате DocBook представляет собой набор текстовых файлов, размеченных тегами SGML или XML (тег - именованные скобки, 400 видов). Для редактирования документов SGML и XML можно использовать редактор DocBook, редактор XML или текстовый редактор (не текстовый процессор!). Для преобразования SGML или XML файлов в конечный продукт в одном из форматов визуального представления (HTML одним файлом, HTML из многих частей, PS, XSL-FO - XSL Formatting Objects, PDF, XHTML, EPUB, man) необходимо использовать специальные утилиты и набор стилей преобразования: DSSSL для SGML, XSLT (DocBook XSL) для XML.
Большой документ может состоять из базового файла, в котором описываются общие атрибуты документа, история изменений и даются ссылки на дополнительные внешние файлы с главами и рисунками. Заголовок:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
Корневой элемент должен иметь атрибут xmlns равным "http://docbook.org/ns/docbook" и атрибуты version и xml:id
<book lang="ru">
<title>Название книги</title>
<bookinfo lang="ru" id="bookinfo">
<author>
<firstname>Имя</firstname>
<surname>Фамилия</surname>
<email>почтовый адрес</email>
</author>
<date>2010.10.21</date>
</bookinfo>
...
<xi:include href="имя-файла1.xml" xmlns:xi="http://www.w3.org/2001/XInclude" xpointer="element(/1)" />
...
<xi:include href="имя-файлаZ.xml" xmlns:xi="http://www.w3.org/2001/XInclude" xpointer="element(/1)" />
</book>
Дополнительный файл имя-файла1.xml:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"file:///usr/share/sgml/docbook/xml-dtd-4.5-1.0-41.fc10/docbookx.dtd">
<chapter lang="ru">
<title>Заголовок главы</title>
<sect1>
<title>Заголовок секции</title>
<para>Параграф 1 ...</para>
<para>Параграф 2 ...</para>
</sect1>
</chapter>
Типы тегов:
Документация в формате DocBook представляет собой набор текстовых файлов, размеченных тегами XML из комплекта DTD (Document Type Definition) DocBook (пакет docbook-dtds). Для редактирования XML текстов можно использовать редактор DocBook, редактор XML или текстовый редактор (не текстовый процессор!). Для преобразования этих файлов в конечный продукт в одном из форматов визуального представления (HTML, PS, XSL-FO, PDF, XHTML, EPUB, man) необходимо использовать специальные утилиты и набор стилей преобразования XSLT (DocBook XSL, пакет docbook-style-xsl). Для получения сложных визуальных представлений может использоваться преобразование в 2 этапа: на первом этапе полуачется документ в формате XSL-FO или TeX или LaTeX, а на втором этапе требуемых выходной формат (PDF, DVI).
XSL-FO (XSL Formatting Objects) используется как промежуточный формат из XML с помощью XSLT перед дальнейшим преобразованием в визуальное представление (PDF, PS, RTF, окно экрана) с помощью FOP (FO Processor). FO описывает список форматов страниц (размеры, направление потока заполнения, поля, последовательность страниц, колонки) и содержимое документа с разметкой (последовательность потоков, состоящих из блоков; списки, связанные блоки, сноски, таблицы, ориентация блоков, метки страниц и ссылки на них, поля блоков, цвет фона и изображения, управление шрифтами), а FOP размещает содержимое по страницам и окнам. В версии 1.1 добавлены возможность определять области на странице, закладки, построение индекса, управление маштабированием изображений. Документ XSL-FO является XML текстом, но не имеет DTD или схемы.
Редакторы XML:
Для проверки на XML-валидность (правильность структуры тегов) можно использовать браузер.
Для проверки на соответствие DTD можно использовать "xmllint --valid --xinclude --noout имя-файла".
Для просмотра можно использовать утилиту yelp (даже локальный файл необходимо указывать в формате URI (file:///имя-файла)).
Поддержка DocBook в OpenOffice не работает (но смотреть можно, если без вложений) - пустая страница или ошибка:
Error at xsl:key on line 79 of file:///usr/lib64/openoffice.org/basis3.0/share/xslt/docbook/sofftodocbookheadings.xsl: The expressions in xsl:key may not contain references to variables
Преобразователи из XML в визуальное представление:
FOP (преобразователь из FO-XSL в PDF)
Преобразователь из DocBook - db2latex, преобразователь из LaTeX в PDF - pdflatex.
xsltproc (пакет libxslt) можно использовать для получения визуального представления из исходного документа DocBook.
Для получения HTML представления в одном файле достаточно преобразовать документ DocBook (в результате charset=ISO-8859-1 и русские буквы в десятичном эквиваленте - в виде 'р'):
xsltproc --nonet --encoding utf8 --xinclude html/docbook.xsl имя-файла > результат
Для получения HTML представления в одном файле index.html с нормальными буквами
xsltproc --nonet --encoding utf8 --stringparam chunker.output.encoding utf-8 --xinclude html/onechunk.xsl имя-файла
Для получения отдельных HTML страниц для каждой главы (создаются index.html, ch01.html и т.д.):
xsltproc --nonet --xinclude --encoding utf8 --stringparam chunker.output.encoding utf-8 html/chunk.xsl имя-файла
Для получения отдельных HTML страниц для последующего преобразования в Microsoft HTML Help (hhc.exe):
xsltproc --nonet --xinclude --encoding utf8 --stringparam htmlhelp.encoding windows-1251 htmlhelp/htmlhelp.xsl имя-файла
Можно получать выходные документы с разным содержанием, помечая фрагменты текста атрибутами и используя profile-docbook.xsl или profile-chunk.xsl.
docbook-style-xsl имеет изрядное количество параметров. Значение текстового параметра задаётся ключом "--stringparam имя-параметра значение", значение параметра целового типа - "--param имя-параметра значение". В частности, можно задать свою таблицу стилей с помощью параметра "html.stylesheet". Часто используемый набор параметров можно сохранить в файле mydocbook.xsl и использовать при преобразовании, например:
<?xml version="1.0" encoding="utf-8"?> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:import href="onechunk.xsl"/> <xsl:param name="chunker.output.encoding">utf-8</xsl:param> <xsl:param name="root.filename">print</xsl:param> <xsl:param name="html.stylesheet">print.css</xsl:param> </xsl:stylesheet>
Получение промежуточного файла в формате XSL-FO:
xsltproc --nonet --xinclude --stringparam paper.type A4 fo/docbook.xsl имя-файла > имя-файла.fo
Преобразование DocBook в визуальное представление с помощью xmlto и xmlto-tex. Преобразование производится в несколько шагов: в промежуточный формат (XML-FO), затем FO процесоор (FOP) в конечный формат. Сам по себе в PDF конвертировать отказался:
xmlto --extensions pdf svnbook-read-only/src/en/book/book.xml sh: /usr/share/xmlto/format/docbook/../fo/pdf: No such file or directory
FOP от Apache не заработал:
LANG= xmlto --extensions --with-fop pdf book.xml SEVERE: javax.xml.transform.TransformerException:
dblatex в качестве FOP имеет проблемы с русскими буквами:
LANG= xmlto --extensions --with-dblatex pdf book.xml book_tmp.tex:68: Undefined control sequence \cyrchar. Error: pdflatex compilation failed
Не помогли установка пакетов texlive-cm-super-fonts, texlive-afm, texlive-texmf-afm, texlive-texmf-errata-afm, texlive-dviutils, texlive-east-asian, texlive-texmf-east-asian, ключи "-p -8bit".
DocBook в стиле SGML (преобразователь Jade). Набор стилей в пакете docbook-style-dsssl.
|
Bog BOS: DocBook - язык форматирования |
|
Последние изменения: |