Asciidoc для подготовки сложной документации

В заголовке использовано слово сложной, под которым можно понимать все, что угодно. Утверждение о том, что 2 * 2 = 4, если вдуматься, тоже очень не просто. Но в данном случае всё банальнее. Речь идёт о ЕСКД, ГОСТ, ОСТ и тому подобных скучных терминах, отягчаемых бюрократической процедурой согласования.

Года полтора назад мы втянулись в проект по разработке небольшой отраслевой информационной системы. По этой небольшой системе необходимо было разработать с полсотни взаимоувязанных документов и согласовать их не меньше, чем с сотней человек.

Сразу решили, что попробуем сделать документацию актуальной, т.е. обойтись без покраски травы в зелёный цвет. И сразу решили, что это будет Asciidoc. Почему? Потому что из текстовых языков разметки для подготовки документации он наиболее функциональный, а разворачивать неповоротливые DITA и Docbook не хотелось.

Пройдя определённую боль, мы с коллегами решили ей поделиться.

Но сначала о хорошем.

• Получилось.
• Переиспользование содержания (а его было много) позволило обеспечить согласованность документов. Функции Asciidoc в части переиспользования абсолютно не уступают DITA. Это важно, когда разные документы согласуют более ста специалистов и изменения должны отражаться в большом количестве документов.
• Текстовый поиск позволил быстро ориентироваться в массиве исходных текстовых данных.
• Условная компиляция включать/не включать данные ДСП (для служебного пользования) позволяет упросить согласование документов в рабочем порядке.
• Asciidoc мы активно используем для генерации документации. Например, для генерации отчётных форм внутри решения мы используем тот же Asciidoc. Таким образом, эти отчётные формы мы можем автоматически помещать в документацию. Также прекрасно работает генерация документации на API (REST, SOAP), СУБД, процессы согласования (с помощью PlantUML) и т.п. Автоматически создавать документацию из тестов еще не получилось, но вот здесь получилось, большое спасибо авторам за данную статью.

Так в чём же боль? Их всего две:

• внешний вид получаемых печатных форм документов;
• процесс согласования.

Сначала о внешнем виде печатных форм документов. Asciidoc поддерживает несколько вариантов генерации печатных документов.

• Нативный https://github.com/asciidoctor/asciidoctor-pdf. Проект недостаточно гибкий, чтобы чувствовать себя свободно.
• Почти нативный https://github.com/Mogztter/asciidoctor-web-pdf – лучшее решение, если выходной документ должен иметь сложную верстку. Но с точки зрения создания документов есть проблемы. Например, с переносом таблиц со страницы на страницу.
• Использование Pandoc для экспорта в docx, или odt (через Docbook, т.к. напрямую из asciidoc работает вообще никак). Поддержка docx и odt – это здорово. Но вопрос в ее качестве. Писать костыли и настраивать документ с помощью макросов или sdk – крайне сложно и ненадёжно. И всё равно надо помнить, какие возможности Asciidoc можно использовать, какие нельзя. А какие можно, но в конкретном случае всё же нельзя.
• Старый способ через Docbook – docbook-xsl. Да, docbook-xsl – это тяжело. Но мы его как-то настроили. Результат здесь. Именно этот способ мы и выбрали.
• Вариант Docbook – TeX, для бесстрашных и неограниченных по ресурсам.

Также нужно отметить, что Asciidoc не поддерживает заголовок таблиц из нескольких строк и стили для ячеек, что в некоторых случаях непреодолимо. Поэтому нам помогли вот с таким проектом (спасибо, Гийом).

Вторая проблема – согласование документов. Согласуем мы не репозиторий, а конкретные документы. И тут выяснилось, что заказчик привык к MS Word для работы с текстовыми документами и знать не хочет о внесении правок в pdf. Более того, все правки заказчик требует в виде изменений в MS Word в режиме рецензирования.

Как-то удалось всё же упросить работать с pdf. А сравнение версий мы решили сделать с помощью вот этого проекта. Если применить следующее преобразование в ImageMagick, на выходе получаем красивый pdf.

pdf-diff before.pdf after.pdf -t 7 -b 92| docker run -i dpokidov/imagemagick png:- -crop 294:207 -border 1x% +repage pdf:- > comparison_output.pdf

Всё это не очень хорошо работает на таблицах с заголовками, поскольку повторяющиеся заголовки на каждой странице pdf-diff воспринимает как изменения, если таблица просто сместилась. Также при сравнении альбомных страниц результат получается неудобочитаемым. И вишенка на торте. После подготовки документов всё равно пришлось вручную переводить некоторые из них в MS Word. Для этого мы конвертировали Asciidoc в html и немного доформатировали. Так себе развлечение.

Выводы

• Asciidoc подходит для проектов, где требования к документации высоко формализованы. Можно даже сказать, что использование специальных систем подготовки документации на основе открытых форматов типа Asciidoc, DITA, Docbook, reStructuredText, Markdown для таких проектов безальтернативно.
• Пока не будет создан нативный конвертер в docx (Open XML) или, что правильнее, в odt (Open Document) описанная технология будет оставаться уделом энтузиастов.