Для тех кто хотел попробовать подход единого источника при написании технической документации, но кого смущала монстроузность настройки 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:
1 2 | $ ruby --version ruby 2.0.0p598 (2014-11-13) [x86_64-linux] |
Чтож, методом проб, ошибок и гугленья устанавливаем 2.3.1:
1 2 3 4 5 6 7 8 | 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:
1 2 3 4 5 6 7 8 9 10 | $ 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:
1 | $ gem install asciidoctor-pdf --pre |
либо последнюю версию в разработке:
1 2 | git clone --depth=1 https://github.com/asciidoctor/asciidoctor-pdf cd asciidoctor-pdf/bin |
Опционально, для подсветки синтаксиса можно доустановить один из движков на выбор (рекомендуют Rouge как предпочтительный):
1 2 3 | $ gem install rouge $ gem install pygments.rb $ gem install coderay |
Настройка
Конфиг можно иметь по-проектно, либо вынести основные настройки в глобальный конфиг (в нём полезно например хранить настройки шрифтов):
1 | gems/asciidoctor-pdf-v.v.v/data/themes/default-theme.yml |
Примеры конфигов для оформления, которые можно использовать как базу для оформления собственных стилей:
Тестовый запуск примера из репозитория asciidoctor-pdf:
1 | asciidoctor-pdf -a pdf-style=../data/themes/base-theme.yml ../examples/basic-example.adoc |
Кириллизация
Шрифты
Из-за подхода к набору символов в шрифтах по умолчанию на кириллических документах вылезает неприятное сообщение:
1 | The following text could not be fully converted to the Windows-1252 character set: ... |
И кирилические символы не отображаются в выходном документе. Эту проблему можно решить, если подключить внешние шрифты, для этого надо сделать две вещи:
- Прописать в конфиг-файле соответствие шрифта и файла, в котором он содержится
- При вызове asciidoctor-pdf указать путь к папке, в которой хранятся шрифты (к сожалению, на текущий момент можно передать только один путь)
В конфиге пишем что-то вроде:
1 2 3 4 5 6 7 8 9 10 11 12 | 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 |
Далее указываем где будут использоваться в документе эти шрифты:
1 2 3 4 5 | base_font_family: Verdana ... literal_font_family: Consolas ... code_font_family: Consolas |
Теперь вызываем с указанием, в которой хранятся шрифты (в RHEL/CentOS это, например, /usr/share/fonts):
1 | asciidoctor-pdf -a pdf-style=theme.yml -a pdf-fontsdir=/usr/share/fonts/msttcore example.adoc |
Метазаголовки
Для корректной локализации различных служебных маркеров, в самом файле документа adoc в самом начале переопределяем переменные (на свой корпоративный вкус):
1 2 3 4 | :listing-caption: Код :chapter-label: Глава :toc-title: Оглавление :version-label: Версия |
Дополнительные утилиты
Также в комплекте идёт шелл-скрипт optimize-pdf, который использует Ghostscript для сжатия и минификации выходного pdf.
1 | $ ./optimize-pdf basic-example.pdf |
В системе должен быть установлен Ghostscript >= 9.10, поэтому Cent OS7 в пролете:
1 2 | $ gs -v GPL Ghostscript 9.07 (2013-02-14) |
Ссылки по теме
- asciidoctor-pdf/docs/theming-guide.adoc — руководство по созданию собственных стилей для asciidoctor-pdf