Skip to main content

asciidoctor-pdf: asciidoc для самых маленьких

Для тех кто хотел попробовать подход единого источника при написании технической документации, но кого смущала монстроузность настройки 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:

Чтож, методом проб, ошибок и гугленья устанавливаем 2.3.1:

Ставим зависимости для asciidoctor-pdf:

Ставим сам asciidoctor-pdf:

либо последнюю версию в разработке:

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

Настройка

Конфиг можно иметь по-проектно, либо вынести основные настройки в глобальный конфиг (в нём полезно например хранить настройки шрифтов):

Примеры конфигов для оформления, которые можно использовать как базу  для оформления собственных стилей:

Тестовый запуск примера из репозитория asciidoctor-pdf:

Кириллизация

Шрифты

Из-за подхода к набору символов в шрифтах по умолчанию на кириллических документах вылезает неприятное сообщение:

И кирилические символы не отображаются в выходном документе. Эту проблему можно решить, если подключить внешние шрифты, для этого надо сделать две вещи:

  1. Прописать в конфиг-файле соответствие шрифта и файла, в котором он содержится
  2. При вызове asciidoctor-pdf указать путь к папке, в которой хранятся шрифты (к сожалению, на текущий момент можно передать только один путь)

В конфиге пишем что-то вроде:

Далее указываем где будут использоваться в документе эти шрифты:

Теперь вызываем с указанием, в которой хранятся шрифты (в RHEL/CentOS это, например, /usr/share/fonts):

Метазаголовки

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

Дополнительные утилиты

Также в комплекте идёт шелл-скрипт optimize-pdf, который использует Ghostscript для сжатия и минификации выходного pdf.

В системе должен быть установлен Ghostscript >= 9.10, поэтому Cent OS7  в пролете:

 

Ссылки по теме

Читать далее