DocBook: быстрый старт (часть 2.1). Конфигурирование DocBook-инструментария под Linux
В этом посте будет описан тот инструментарий, которые необходим для работы с DocBook-документами.
Обратите внимание: в текущем посте речь пойдет именно о конфигурировании инструментария. Рассмотрение логических цепочек работы с документами, описание каждого шага, запуск компонентов для выполнения основных функций будут описаны в следующих постах
На текущий момент будем рассматривать инструментарий, исходя их следующих предусловий:
- Редактирование происходит локально с помощью offline редактора на Java.
- Файлы хранятся локально на файловой системе.
- Для хранения файлов НЕ используется система контроля версий (VCS).
- Результирующие файлы генерируются в командной строке БЕЗ использования скриптов.
- Системы непрерывной сборки (CI) в процессе работы НЕ используются.
- В случае необходимости xml-документы могут быть изменены в обычном plain-text редакторе (желательно с подсветкой синтаксиса).
Такая схема является наиболее простейшей схемой работы, но при этом она позволяет одновременно:
- сразу же начать работать с DocBook-документами без потери существенного времени на установку и настройку расширенных компонентов (VCS, CI, написания скриптов);
- ощутить все преимущества работы с DocBook.
В дальнейшем инструментарий и схема работы будет постепенно усложняться. Мы будем вводить в схему новые компоненты, которые:
- с одной стороны, потребуют дополнительного времени на конфигурирование;
- с другой стороны, позволят приблизить схему работы с документацией в настоящем “боевом” режиме IT-компании.
Автор покажет конфигурирование инструментария для трех базовых платформ: Windows, Linux (i386,amd64), MacOS.
Эта часть будет посвящена конфигурированию инструментария под Linux. Вы также можете ознакомиться с конфигурированием под Windows или MacOS (Скоро).
Замечание: т.к. автор использует в своей работе Debian GNU/Linux, описание конфигуирования для других платформ (Windows, MacOS) может содержать небольшие неточности. Если вы используете эти системы и нашли неточность в описании, большая просьба сообщить автору (см. страницу Контакты )
1. Основные компоненты для работы
Ниже представлен список компонентов, которые необходимы для работы с документами (полный цикл - от создания для получения выходного результата):
- виртуальная машина Java (JVM);
- редактор исходных DocBook-документов;
- процессор XSLT;
- fo-процессор и шрифтов (для документов с кириллицей);
- набор стилевых файлов DocBook XSL Stylesheets;
- любой plain-text текстовый редактор (лучше с подсветкой синтаксиса) [1].
2. Установка и конфигурование компонентов под Linux
2.1. Установка и редактора виртуальной машины Java (JVM)
Если у вас не установлена Java (JRE или JDK) загрузите виртуальную машину Java (JVM) 1.8 для своей архитектуры:
Хотя Java JRE должно полностью хватить запуска компонентов, автор предпочитает использовать полный набор - Java JDK.
Установите Java, распаковав файлы в рабочий каталог Java. Например: /opt/<java_version_dir>/
Настройте путь к java в в системе. В частности, для Debian-based систем выполните команду:
user@sandbox:~$ sudo update-alternatives --install /usr/bin/java java /opt/<java_version_dir>/bin/java 1065
Если у вас уже установлена другая версия Java, то выберите установленную версию в качестве версии по умолчанию с помощью команды и выбора требуемого пункта:
user@sandbox:~$ sudo update-alternatives --config java
There are 8 choices for the alternative java (providing /usr/bin/java).
Selection Path Priority Status
0 /usr/lib/jvm/java-8-openjdk-amd64/jre/bin/java 1081 auto mode
1 /opt/jdk1.6.0_45/bin/java 1065 manual mode
2 /opt/jdk1.7.0_51/bin/java 1061 manual mode
3 /opt/jdk1.7.0_80/bin/java 1067 manual mode
* 4 /opt/jdk1.8.0_51/bin/java 1068 manual mode
5 /usr/bin/gij-4.7 1047 manual mode
6 /usr/bin/gij-4.9 1049 manual mode
7 /usr/bin/gij-6 1060 manual mode
8 /usr/lib/jvm/java-8-openjdk-amd64/jre/bin/java 1081 manual mode
Проверьте, что java установлена корректно, выполнив в командной строке команду:
user@sandbox:~$ java -version
На экране должна отобразится установленная версия Java.
java version "1.8.0_51"
Java(TM) SE Runtime Environment (build 1.8.0_51-b16)
Java HotSpot(TM) 64-Bit Server VM (build 25.51-b03, mixed mode)
2.2. Установка и конфигурирование редактора DocBook-документов
В рамках данного курсе будет использоваться редактор XMLMind XML Editor (далее по тексту XXE). Особенность состоит в том, что его персональную версию (Personal Edition) можно бесплатно использовать для обучения и создания некоммерческих документов c лицензиями вида open source и creative commons. Смотрите полный текст лицензии:
- на этом сайте;
- либо на сайте XMLMind.
Загрузите редактор для своей платформы c этого сайта (прямая ссылка (zip, 81MB)):
user@sandbox:~$ wget http://www.singlesourcing.ru/pub/dist/xxe/xxe-perso-7_6_0.zip
Вы также можете загрузить дистрибутив co страницы разработчика.
Распакуйте архив в рабочий каталог, например:
user@sandbox:~$ sudo unzip xxe-perso-7_6_0.zip -d /opt/
Создайте softlink на исполняемый скрипт:
user@sandbox:~$ sudo ln -s /opt/xxe-perso-7_6_0/bin/xxe /usr/local/bin/xxe
Проверьте, что редактор запускается из командной строки:
user@sandbox:~$ xxe
В результате на экране у вас должно отобразится главное окно XXE (на рисунке - оформление GUI в стиле GTK+):

Если вы хотите изменить внешнее оформление, то выберите требуемый стиль в Options > General > Style (каждое изменение требует перезапуска редактора).
Если вы хотите работать с русским интерфейсом, то установите русскую локализацию: Options > Install Addons

Если вы работает с русскоязычными документами и хотите проверять орфографию в них, установите русский словарь - выберите окне Install Addons Dictionary (Russian).
Нажмите на кнопку OK для загрузки дополнений и вступления настроек в силу. После этого перезапустите редактор.
2.3. Установка и конфигурирование XSLT-процессора
Основные стили (DocBook XSL Stylesheets, о них далее по тексту) написаны на xsl 1.0, поэтому в качестве xslt-процессора (осуществляющего преобразования документов) можно использовать один из следующих:
- xsltproc (libxslt) - процессор написан на С и входит практически во все дистрибутивы Linux по умолчанию;
- Saxon - процессор написан на Java, устанавливается дополнительно;
- Xalan - процессор написан на Java, устанавливается дополнительно.
Автор рекомендует для начала поставить каждый из этих процессоров. В процессе работы вы сможете выбрать для себя оптимальный.
2.3.1. Установка и конфигурирование xsltproc
Процессор xsltproc входит в большинство Linux-дистрибутивов по умолчанию - установка производится стандартым менеджером пакетов.
Например, в debian-based системах для установки достаточно выполнить команду:
user@sandbox:~$ sudo apt-get install xsltproc
2.3.2. Установка и конфигурирование Saxon
В настоящий момент процессор Saxon выпускается нескольких модификациях и лишь модификация HE - Home Edition - бесплатна. Но мы будем работать с предыдущими версиями Saxon по следующим причинам:
- новые версии Saxon нужны, в первую очередь, для поддержки XSLT 3.0, что в рамках работы с DocBook неактуально.
- предыдущие версии Saxon достаточно хорошо себя зарекомендовали в работе.
Дистрибутив Saxon доступен для загрузки с этого сайта:
- Saxon 6.5.5 (поддерживает только XSLT 1.0) - прямая ссылка (zip, 3.3 Mb);
- Saxon 9.1.0.8 (поддерживает XSLT 1.0/2.0) - может потребоваться для работы с экспериментальными стилями DocBook XSL Stylesheets 2.x.x - прямая ссылка (zip, 2 Mb).
Для загрузки прямо из консоли:
user@sandbox:~$ wget http://www.singlesourcing.ru/pub/dist/xslt/saxon6-5-5.zip
user@sandbox:~$ wget http://www.singlesourcing.ru/pub/dist/xslt/saxonb9-1-0-8j.zip
Вы также можете загрузить дистрибутив co страницы разработчика на sf.net, раздел “Older Products”.
Создайте рабочий каталог, в котором будут располагаться xslt-процессоры на java:
user@sandbox:~$ sudo mkdir /opt/xslt/
Распакуйте дистрибутив во временный каталог и переместите его в рабочий.
Для Saxon 6.5.5:
user@sandbox:~$ unzip saxon6-5-5.zip -d /tmp/saxon6-5-5/
user@sandbox:~$ sudo mv /tmp/saxon6-5-5/ /opt/xslt/
Для Saxon 9.1.0.8:
user@sandbox:~$ unzip saxonb9-1-0-8j.zip -d /tmp/saxonb9-1-0-8/
user@sandbox:~$ sudo mv /tmp/saxonb9-1-0-8/ /opt/xslt/
Проверьте работу обоих процессоров (в результате на экране отобразится сообщение со списком параметров):
user@sandbox:~$ java -jar /opt/xslt/saxon6-5-5/saxon.jar -t
user@sandbox:~$ java -jar /opt/xslt/saxonb9-1-0-8/saxon9.jar -?
2.3.3. Установка и конфигурирование Xalan
Дистрибутив Xalan 2.7.2 доступен для загрузки с этого сайта - прямая ссылка (.tar.gz, 13.5 Mb)
Для загрузки прямо из консоли:
user@sandbox:~$ wget http://www.singlesourcing.ru/pub/dist/xslt/xalan-j_2_7_2-bin.tar.gz
Вы также можете загрузить дистрибутив co страницы разработчика на sf.net, раздел “Downloading the latest release”.
Распакуйте дистрибутив во временный каталог и переместите его в рабочий:
user@sandbox:~$ tar -xzf xalan-j_2_7_2-bin.tar.gz -C /tmp/
user@sandbox:~$ sudo mv /tmp/xalan-j_2_7_2/ /opt/xslt/
Проверьте работу процессора (в результате на экране отобразится сообщение со списком параметров):
user@sandbox:~$ java -jar /opt/xslt/xalan-j_2_7_2/xalan.jar
2.4. Установка и конфигурирование FO-процессора
В качестве FO-процессора (осуществляющего преобразование FO-описания в страничный документ печати или pdf файла) будем использовать Apache FOP, написанный на Java.
Загрузите Apache FOP 2.2 по прямой ссылке (zip, 20.5 Mb)
Для загрузки прямо из консоли:
user@sandbox:~$ wget http://singlesourcing.ru/pub/dist/fop/fop-2.2-bin.tar.gz
Вы также можете загрузить дистрибутив co страницы разработчика, раздел “Binary Download”.
Распакуйте дистрибутив во временный каталог и переместите его в рабочий:
user@sandbox:~$ tar -xzf fop-2.2-bin.tar.gz -C /tmp/
user@sandbox:~$ sudo mv /tmp/fop-2.2/ /opt/
Создайте softlink на исполняемый скрипт:
user@sandbox:~$ sudo ln -s /opt/fop-2.2/bin/fop /usr/local/bin/fop
Проверьте работу процессора (в результате на экране отобразится сообщение с номером версии FOP):
user@sandbox:~$ fop -version
Загрузите русскоязычные шрифты по прямой ссылке (tar.bz2, 3.8 Mb)
Для загрузки прямо из консоли:
user@sandbox:~$ wget http://www.singlesourcing.ru/pub/dist/fop-fonts/fop-fonts-cyr.tar.bz2
Создайте временный каталог, распакуйте архив со шрифтами во временный каталог и переместите его в рабочий:
user@sandbox:~$ mkdir /tmp/fop-fonts
user@sandbox:~$ tar -xjf fop-fonts-cyr.tar.bz2 -C /tmp/fop-fonts
Откройте файл /tmp/fop-fonts/fop-conf.xml в любом текстовом редакторе и исправьте полный путь к шрифтам в строке:
<font-base>http://www.singlesourcing.ru/pub/fop-fonts/glyphs/latest/</font-base>
на актуальный рабочий каталог на вашем компьютере (в примере - используется каталог /opt/)
<font-base>/opt/fop-fonts/glyphs/latest/</font-base>
Переместите файлы в рабочий каталог:
user@sandbox:~$ sudo mv /tmp/fop-fonts/ /opt/
2.5. Установка и конфигурирование стилей DocBook XSL Stylesheets
Стили DocBook XSL предназначены для преобразования исходного XML документа в разные целевые форматы. Подробно цепочки преобразований будут рассмотрены в следующих частях. Сейчас же речь пойдет только об установке компонентов.
Загрузите DocBook XML stylesheets версии 1.79.1 [2] по прямой ссылке (tar.gz, 20 Mb)
Для загрузки прямо из консоли:
user@sandbox:~$ wget http://www.singlesourcing.ru/pub/dist/docbook/docbook-xsl-ns-1.79.1.tar.bz2
Обратите внимание, что в данном курсе работа будет идти с исходными файлами DocBook/XML версии 5.1 (т.н. NS-aware, также и 5.0).Если же вы вы работаете с предыдущей версией (DocBook/XML 4.5), то то необходимо загрузить вот эти стили (tar.gz, 20 Mb)
Обратите внимание на важное примечание относительно именований файлов дистрибутивов [3]
Вы также можете загрузить дистрибутив co страницы разработчика на sf.net.
Распакуйте дистрибутив во временный каталог и переместите его в рабочий:
user@sandbox:~$ tar -xjf docbook-xsl-ns-1.79.1.tar.bz2 -C /tmp/
user@sandbox:~$ sudo mv /tmp/docbook-xsl-ns-1.79.1/ /opt/
2.6. Установка и конфигурирование редактора текстовых документов
Установите и сконфигурируйте любой редактор тестовых документов, который:
- позволяет отображать внутреннюю структуру XML-файлов;
- имеет возможность замены текста (в т.ч. массовую);
- имеет подсветку синтаксиса.
Вы можете выбрать любой редактор: имеющий GUI или консольный. Главное, чтобы он позволял решать обозначенные выше задачи.
Автор использует для:
Эта часть была посвящена конфигурированию инструментария под Linux. Вы также можете ознакомиться с конфигурированием под Windows или MacOS (Скоро).
[1] | Под любым plain-text тестовым редактором понимается любой, который предназначен для работы с простым текстом без стилевого оформления безотносительно к платформе и наличию/отсутствию GUI (например, Notepad, Notepad++, Mousepad, SublimeText, vim, nano, emacs и т.п.). В данном случае НЕ подходят стилевые редакторы - т.н. word processors - MS Word, OpenOffice, LibreOffice, StarOffice, WordPad, Abiword и т.п. |
[2] | Мы будем использовать версию 1.79.1, хотя самая последняя версия - 1.79.2. Отличия в переменных, которые были изменены при переезде с репозитория c sourceforge.net на github.com. К сожалению, многие детали остались пропущенными (например, недоступен файл библиографии на CDN и т.п.), поэтому разумнее использовать предыдущую версию релиза. |
[3] | При смене версии с 1.79.1 на 1.79.2 произошла смена наименований файлов дистрибутивов стилей:
|