DocBook: быстрый старт (часть 2.1). Конфигурирование DocBook-инструментария под Linux

раздел DocBook: краткий курс

В этом посте будет описан тот инструментарий, которые необходим для работы с DocBook-документами.

Обратите внимание: в текущем посте речь пойдет именно о конфигурировании инструментария. Рассмотрение логических цепочек работы с документами, описание каждого шага, запуск компонентов для выполнения основных функций будут описаны в следующих постах

На текущий момент будем рассматривать инструментарий, исходя их следующих предусловий:

  1. Редактирование происходит локально с помощью offline редактора на Java.
  2. Файлы хранятся локально на файловой системе.
  3. Для хранения файлов НЕ используется система контроля версий (VCS).
  4. Результирующие файлы генерируются в командной строке БЕЗ использования скриптов.
  5. Системы непрерывной сборки (CI) в процессе работы НЕ используются.
  6. В случае необходимости 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. Смотрите полный текст лицензии:

Загрузите редактор для своей платформы 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+):

Окно редактора XXE сразу после запуска

Если вы хотите изменить внешнее оформление, то выберите требуемый стиль в 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 доступен для загрузки с этого сайта:

Для загрузки прямо из консоли:

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 или консольный. Главное, чтобы он позволял решать обозначенные выше задачи.

Автор использует для:

  • для основной работы - JEdit
  • мелких правок (в консоли, на сервере) - vim

Эта часть была посвящена конфигурированию инструментария под 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 произошла смена наименований файлов дистрибутивов стилей:

  • для формата 4.5: docbook-xsl-VERSION.tar.bz2 по 1.79.1 включительно, docbook-xsl-nons-VERSION.tar.bz2 начиная с 1.79.2;
  • для формата 5.0, 5.1: docbook-xsl-ns-VERSION.tar.bz2 по 1.79.1 включительно, docbook-xsl-VERSION.tar.bz2 начиная с 1.79.2;