Русифицируем asciidoctor-pdf

Очередной раз поднялся вопрос в чем писать документацию, чтобы:
1) была простая разметка, которую можно было редактировать в простом текстовом редакторе
2) можно было получить diff в версиях, как следствие текстового представления сырца
3) была генерация html
4) была генерация pdf без всяких docbook, latex и прочего

Если под первые три пункта подходит тот же markdown, то по последнему мною было обнаружено только одно хоть как-то работающее решение - https://github.com/asciidoctor/asciidoctor-pdf. И то в состоянии альфы.
Вообще, конечно, странно в 2014 году не иметь нормальных прямых решений генерации pdf из разметки. Видимо, это никому особо не надо - взяли ворд и вперед вместе с pdf-принтерами.

В asciidoctor-pdf тоже вылезла проблема - с русским языком. По крайней мере у меня на Mac OS X. Причина, как ожидаемо, в шрифтах.
Для лечения в Mac OS X нужно закачать правильные шрифты в папку /Library/Ruby/Gems/2.0.0/gems/asciidoctor-pdf-1.5.0.alpha.4/data/fonts, которые позаимствовать из папки системных шрифтов /Library/Fonts/
Затем решить как прописываем установки шрифтов - глобально или локально. Если глобально - работаем с файлом конфигурации asciidoctor-pdf /Library/Ruby/Gems/2.0.0/gems/asciidoctor-pdf-1.5.0.alpha.4/data/themes/default-theme.yml. Если локально - переписываем эту конфигурацию в папку со своим документом.
В конфигурации добавляем еще одну секцию font:catalog:
и указываем новый шрифт в секции base:font_family:

Будет выглядеть как-то так:

font:
  catalog:
    Arial:
      normal: Arial.ttf
      bold: Arial Bold.ttf
      italic: Arial Italic.ttf
      bold_italic: Arial Bold Italic.ttf
base:
  font_family: Arial

если используете русский язык в коде, которые вставляется директивой source, не забудьте в секции code/font_family указать шрифт, поддерживающий кириллицу:
code:
     font_family: Arial

Далее, русификация наименования секций Chapter -> Глава
https://github.com/asciidoctor/asciidoctor-pdf/commit/43584be1cae1853c6e8479c76c6d7ba561782b34
после этого можно писать в заголовке
:chapter-label: Глава
 и все получится

Для переименования Table of context -> Оглавление
можно просто переопределить переменную toc-title.
Для этого прямо в документе пишем
:toc-title: Оглавление

Для перевода Version -> Версия добавь
:version-label: Версия

При формировании нумерованных списков может потребоваться настройка размера отступа текста от номера, что можно сделать через переменную outline_list indent в конфигурации темы:
outline_list:
  indent: $horizontal_rhythm * 2.25

Как верно подсказали в комментариях - не стоит портить дефолтную тему, имеет смысл закачать в папку /Library/Ruby/Gems/2.0.0/gems/asciidoctor-pdf-1.5.0.alpha.4/data/fonts нужны шрифты, а определения стилей хранить прямо около документа, запуская генерацию командой
asciidoctor-pdf -a pdf-style=path/to/*-theme.yml *.adoc