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. Смотрите полный текст лицензии:
- на этом сайте;
- либо на сайте XMLMind.
Загрузите редактор для своей платформы:
- c этого сайта (прямая ссылка (zip, 124 MB));
- или со страницы разработчика.
Установите редактор стандартными средствами ОС, запустив файл xxe-perso-7_6_0-setup.exe и следуя инструкциям программы установки.
После завершения установки найдите значок редактора в главном меню или на рабочем столе и запустите его.
В результате на экране у вас должно отобразится главное окно XXE (на рисунке - оформление GUI в стиле GTK+):

Если вы хотите изменить внешнее оформление, то выберите требуемый стиль в 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 доступен для загрузки с этого сайта:
- 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).
Вы также можете загрузить дистрибутив 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
Добавьте путь к каталогу FOP 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 или консольный. Главное, чтобы он позволял решать обозначенные выше задачи.
Автор использует для:
Эта часть была посвящена конфигурированию инструментария под 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 произошла смена наименований файлов дистрибутивов стилей:
|