Doka avatar

Журнал Эмбеддед-Инженера

О микроэлектронике, радиотехнике и хобби

Dmitry Murzinov

3 минут чтения

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

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

  1. Прописать в конфиг-файле соответствие шрифта и файла, в котором он содержится
  2. При вызове 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)

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

Последние записи

Разделы