Для тех кто хотел попробовать подход единого источника при написании технической документации, но кого смущала монстроузность настройки AsciiDoctor‘a (все эти DocBook, xslt, fopub и прочие прелести) есть альтернатива, которая позволит пощупать все прелести аскидока с легким стартом.
Преимущества документации в asciidoc
Для тех, кто забыл или не в теме, напомню основные пункты:
- Текстовый формат мета-языка разметки (тут же такие wiki-форматы как Markdown, reStructuredText, DokuWiki, etc)
- Контроль изменений (версионирование в отличие от бинарных форматов документов, позволяющее делать простой diff между ревизиями
- WYSIWIG-превью в лайв-режиме
- Возможность накрутки своего корпиративного стиля при генерации различных выходных форматов: pdf, epub,mobi, fb2, html
asciidoctor-pdf
Основное отличие от AsciiDoctor’a - использование вместо апачевского FO-процессора FOP (java) движка Prawn (Ruby). Также используется значительно облегченная (по сравнению с AsciiDoctor) система конфигов на основе микроразметки YAML.
Установка
Несмотря на то, что asciidoctor-pdf требует наличия ruby >= 2.0.0, по факту его можно установить без ошибок и эксплуатировать лишь на более свежих версиях, к несчастью в CentOS7 установлена 2.0.0:
$ ruby --version
ruby 2.0.0p598 (2014-11-13) [x86_64-linux]
Чтож, методом проб, ошибок и гугленья устанавливаем 2.3.1:
curl -sSL https://rvm.io/mpapis.asc | sudo gpg --import -
curl -L get.rvm.io | sudo bash -s stable
source /etc/profile.d/rvm.sh
rvm reload
rvm requirements run
rvm install 2.3.1
rvm use 2.3.1 --default
ruby --version
Ставим зависимости для asciidoctor-pdf:
gem install prawn --version 1.3.0
gem install addressable --version 2.4.0
gem install prawn-svg --version 0.21.0
gem install prawn-templates --version 0.0.3
gem install prawn-table --version 0.2.2
gem install prawn-icon --version 1.3.0
gem install treetop
gem install thread_safe
gem install safe_yaml
gem install asciidoctor
Ставим сам asciidoctor-pdf:
gem install asciidoctor-pdf --pre
либо последнюю версию в разработке:
git clone --depth=1 https://github.com/asciidoctor/asciidoctor-pdf
cd asciidoctor-pdf/bin
Опционально, для подсветки синтаксиса можно доустановить один из движков на выбор (рекомендуют Rouge как предпочтительный):
gem install rouge
gem install pygments.rb
gem install coderay
Настройка
Конфиг можно иметь по-проектно, либо вынести основные настройки в глобальный конфиг (в нём полезно например хранить настройки шрифтов):
gems/asciidoctor-pdf-v.v.v/data/themes/default-theme.yml
Примеры конфигов для оформления, которые можно использовать как базу для оформления собственных стилей:
Тестовый запуск примера из репозитория asciidoctor-pdf:
asciidoctor-pdf -a pdf-style=../data/themes/base-theme.yml ../examples/basic-example.adoc
Кириллизация
Шрифты
Из-за подхода к набору символов в шрифтах по умолчанию на кириллических документах вылезает неприятное сообщение:
The following text could not be fully converted to the Windows-1252 character set: …
И кирилические символы не отображаются в выходном документе. Эту проблему можно решить, если подключить внешние шрифты, для этого надо сделать две вещи:
- Прописать в конфиг-файле соответствие шрифта и файла, в котором он содержится
- При вызове asciidoctor-pdf указать путь к папке, в которой хранятся шрифты (к сожалению, на текущий момент можно передать только один путь)
В конфиге пишем что-то вроде:
font:
catalog:
Consolas:
normal: consola.ttf
bold: consolab.ttf
italic: consolai.ttf
bold_italic: consolaz.ttf
Verdana:
normal: verdana.ttf
bold: verdanab.ttf
italic: verdanai.ttf
bold_italic: verdanaz.ttf
Далее указываем где будут использоваться в документе эти шрифты:
base_font_family: Verdana
...
literal_font_family: Consolas
...
code_font_family: Consolas
Теперь вызываем с указанием, в которой хранятся шрифты (в RHEL/CentOS это, например, /usr/share/fonts):
asciidoctor-pdf -a pdf-style=theme.yml -a pdf-fontsdir=/usr/share/fonts/msttcore example.adoc
Метазаголовки
Для корректной локализации различных служебных маркеров, в самом файле документа adoc в самом начале переопределяем переменные (на свой корпоративный вкус):
:listing-caption: Код
:chapter-label: Глава
:toc-title: Оглавление
:version-label: Версия
Дополнительные утилиты
Также в комплекте идёт шелл-скрипт optimize-pdf, который использует Ghostscript для сжатия и минификации выходного pdf.
$ ./optimize-pdf basic-example.pdf
В системе должен быть установлен Ghostscript >= 9.10, поэтому Cent OS7 в пролете:
$ gs -v
GPL Ghostscript 9.07 (2013-02-14)
Ссылки по теме
- asciidoctor-pdf/docs/theming-guide.adoc - руководство по созданию собственных стилей для asciidoctor-pdf
