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

Эта часть будет посвящена конфигурированию инструментария под Windows. Вы также можете ознакомиться с конфигурированием под Linux или MacOS (скоро).

Перед ознакомлением c этим постом, пожалуйста, прочтите вводную часть к предыдущему разделу.

Замечание: т.к. автор использует в своей работе Debian GNU/Linux, описание конфигуирования для Windows может содержать небольшие неточности. Если вы используете Windows и нашли неточность в описании, большая просьба сообщить автору (см. страницу Контакты )

1.   Основные компоненты для работы

Ниже представлен список компонентов, которые необходимы для работы с документами (полный цикл - от создания для получения выходного результата):

  • виртуальная машина Java (JVM);
  • редактор исходных DocBook-документов;
  • (*) процессор XSLT;
  • (*) fo-процессор и кириллические шрифты (для документов на русском языке);
  • (*) набор стилевых файлов DocBook XSL Stylesheets;
  • любой plain-text текстовый редактор (лучше с подсветкой синтаксиса) [1].

(*) Обозначенные этим символом компоненты могут быть загружены как по отдельности (см. описания каждого компонента в соответствующем разделе), так и сразу одним zip файлом с этого сайта - прямая ссылка (zip, 62 MB).

2.   Установка и конфигурование компонентов под Windows

2.1.   Подготовка к установке

Перед установкой проверьте, что:

  • у вас есть права Администратора на ОС;
  • на компьютере установлен архиватор, поддерживающий форматы .zip, .tar.gz и .tar.bz2. В качестве архиватора вы можете использовать 7-zip.

Создайте на диске рабочий каталог для компонентов, например, C:\docbook-tools

Создайте на диске рабочий каталог для xslt-процессоров, например, C:\docbook-tools\xslt

2.2.   Установка и редактора виртуальной машины Java (JVM)

Если у вас не установлена Java (JRE или JDK) загрузите виртуальную машину Java (JVM) 1.8 для своей архитектуры:

Хотя Java JRE должно полностью хватить запуска компонентов, автор предпочитает использовать полный набор - Java JDK.

Установите Java стандартными средствами Windows.

Проверьте, что java установлена корректно, выполнив в командной строке команду:

C:\>java -version

На экране должна отобразится установленная версия Java.

java version "1.8.0_151"
Java(TM) SE Runtime Environment (build 1.8.0_151-b12)
Java HotSpot(TM) Client VM (build 25.151-b12, mixed mode)

2.3.   Установка и конфигурирование редактора DocBook-документов

В рамках данного курсе будет использоваться редактор XMLMind XML Editor (далее по тексту XXE). Особенность состоит в том, что его персональную версию (Personal Edition) можно бесплатно использовать для обучения и создания некоммерческих документов c лицензиями вида open source и creative commons. Смотрите полный текст лицензии:

Загрузите редактор для своей платформы:

Установите редактор стандартными средствами ОС, запустив файл xxe-perso-7_6_0-setup.exe и следуя инструкциям программы установки.

После завершения установки найдите значок редактора в главном меню или на рабочем столе и запустите его.

В результате на экране у вас должно отобразится главное окно XXE (на рисунке - оформление GUI в стиле GTK+):

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

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

Если вы хотите работать с русским интерфейсом, то установите русскую локализацию: Options > Install Addons > Install Addons > Translation - Russian (русский) translation.

Выбор русского языка для локализации интерфейса

Если вы работает с русскоязычными документами и хотите проверять орфографию в них, установите русский словарь - выберите в окне Install Addons > Dictionary - Russian (русский) dictionary.

Выбор русского словаря для проверки орфографии

Нажмите на кнопку OK для загрузки дополнений и вступления настроек в силу. После этого перезапустите редактор.

2.4.   Установка и конфигурирование XSLT-процессора

Основные стили (DocBook XSL Stylesheets, о них далее по тексту) написаны на xsl 1.0, поэтому в качестве xslt-процессора (осуществляющего преобразования документов) можно использовать один из следующих:

  • xsltproc (libxslt) - процессор написан на С и входит практически во все дистрибутивы Linux по умолчанию;
  • Saxon - процессор написан на Java, устанавливается дополнительно;
  • Xalan - процессор написан на Java, устанавливается дополнительно.

Автор рекомендует для начала поставить каждый из этих процессоров. В процессе работы вы сможете выбрать для себя оптимальный.

2.4.1.   Установка и конфигурирование xsltproc

Дистрибутив xsltproc (порт под Windows) доступен для загрузки:

  • c этого сайта - прямая ссылка (zip, 1.3 Mb) - в этом наборе собраны все компоненты, необходимые для запуска;
  • c сайта разработчика. При загрузке с сайта разработчика вам необходимо не только загрузить по отдельности компоненты: iconv-1.9.2.win32.zip libxml2-2.7.8.win32.zip libxslt-1.1.26.win32.zip zlib-1.2.5.win32.zip, но и собрать файлы из каталога bin каждого архива в единый каталог (или добавить каждый каталог bin в системный PATH)

Распакуйте архив xsltproc-win-package.zip в рабочий каталог, например, в C:\docbook-tools\xslt\xsltproc

Добавьте путь к каталогу xsltproc C:\docbook-tools\xslt\xsltproc в системный PATH. На некоторых версиях Windows добавление каталога в системный PATH требует перезапуска ОС.

Убедитесь, что xsltproc установлен корректно, выполнив команду:

C:\>xsltproc -version

На экране должна отобразится установленная версия xsltproc

Using libxml 20708, libxslt 10126 and libexslt 815
xsltproc was compiled against libxml 20706, libxslt 10126 and libexslt 815
libxslt 10126 was compiled against libxml 20706
libexslt 815 was compiled against libxml 20706

2.4.2.   Установка и конфигурирование Saxon

В настоящий момент процессор Saxon выпускается нескольких модификациях и лишь модификация HE - Home Edition - бесплатна. Но мы будем работать с предыдущими версиями Saxon по следующим причинам:

  • новые версии Saxon нужны, в первую очередь, для поддержки XSLT 3.0, что в рамках работы с DocBook неактуально.
  • предыдущие версии Saxon достаточно хорошо себя зарекомендовали в работе.

Дистрибутив Saxon доступен для загрузки с этого сайта:

Вы также можете загрузить дистрибутив co страницы разработчика на sf.net, раздел “Older Products”.

Распакуйте дистрибутив в рабочий каталог:

  • для Saxon 6.5.5: C:\docbook-tools\xslt\saxon6-5-5
  • для Saxon 9.1.0.8: C:\docbook-tools\xslt\saxonb9-1-0-8

Проверьте работу обоих процессоров (в результате на экране отобразится сообщение со списком параметров):

C:\>java -jar C:\docbook-tools\xslt\saxon6-5-5\saxon.jar -t
C:\>java -jar C:\docbook-tools\xslt\saxonb9-1-0-8\saxon9.jar -?

2.4.3.   Установка и конфигурирование Xalan

Дистрибутив Xalan 2.7.2 доступен для загрузки с этого сайта - прямая ссылка (.tar.gz, 13.5 Mb)

Вы также можете загрузить дистрибутив co страницы разработчика на sf.net, раздел “Downloading the latest release”.

Распакуйте дистрибутив в рабочий каталог: C:\docbook-tools\xslt\xalan-j_2_7_2

Проверьте работу процессора (в результате на экране отобразится сообщение со списком параметров):

C:\>java -jar C:\docbook-tools\xslt\xalan-j_2_7_2\xalan.jar

2.5.   Установка и конфигурирование FO-процессора

В качестве FO-процессора (осуществляющего преобразование FO-описания в страничный документ печати или pdf файла) будем использовать Apache FOP, написанный на Java.

Загрузите Apache FOP 2.2 по прямой ссылке c этого сайта (zip, 20.5 Mb)

Вы также можете загрузить дистрибутив co страницы разработчика, раздел “Binary Download”.

Распакуйте дистрибутив в рабочий каталог: C:\docbook-tools\fop-2.2

Добавьте путь к каталогу xsltproc C:\docbook-tools\fop-2.2\fop в системный PATH. На некоторых версиях Windows добавление каталога в системный PATH требует перезапуска ОС.

Убедитесь, что FOP установлен корректно, выполнив команду:

C:\>fop -version

В результате на экране отобразится сообщение с номером версии FOP:

FOP Version 2.2

Загрузите русскоязычные шрифты по прямой ссылке (tar.bz2, 3.8 Mb)

Создайте каталог C:\docbook-tools\fop-fonts и распакуйте туда содержимое архива.

Откройте файл C:\docbook-tools\fop-fonts\fop-conf.xml и исправьте полный путь к шрифтам в строке:

<font-base>http://www.singlesourcing.ru/pub/fop-fonts/glyphs/latest/</font-base>

на актуальный на вашем компьютере (в примере - используется каталог C:\docbook-tools)

<font-base>file:///C:/docbook-tools/fop-fonts/glyphs/latest/</font-base>

Обратите внимание: в абсолютном пути используется прямой слэш / , как в обычном URL!

2.6.   Установка и конфигурирование стилей DocBook XSL Stylesheets

Стили DocBook XSL предназначены для преобразования исходного XML документа в разные целевые форматы. Подробно цепочки преобразований будут рассмотрены в следующих частях. Сейчас же речь пойдет только об установке компонентов.

Загрузите DocBook XML stylesheets версии 1.79.1 [2] - по прямой ссылке (tar.gz, 20 Mb)

Обратите внимание, что в данном курсе работа будет идти с исходными файлами DocBook/XML версии 5.1 (т.н. NS-aware, также и 5.0).Если же вы вы работаете с предыдущей версией (DocBook/XML 4.5), то то необходимо загрузить вот эти стили (tar.gz, 20 Mb)

Обратите внимание на важное примечание относительно именований файлов дистрибутивов [3]

Вы также можете загрузить дистрибутив co страницы разработчика на sf.net.

Распакуйте дистрибутив в рабочий каталог: C:\docbook-tools\docbook-xsl-ns-1.79.1

2.7.   Установка и конфигурирование редактора текстовых документов

Установите и сконфигурируйте любой редактор тестовых документов, который:

  • позволяет отображать внутреннюю структуру XML-файлов;
  • имеет возможность замены текста (в т.ч. массовую);
  • имеет подсветку синтаксиса.

Вы можете выбрать любой редактор: имеющий GUI или консольный. Главное, чтобы он позволял решать обозначенные выше задачи.

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

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

Эта часть была посвящена конфигурированию инструментария под Windows. Вы также можете ознакомиться с конфигурированием под Linux или MacOS (скоро).

2.8.   Благодарности

Автор хочет выразить отдельную благодарность Андрею Серикову (andrej.serikov [at] gmail.com) за помощь в корректировке текущего поста, связанного со спецификой работы c Windows.

[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;