Простой способ вёрстки документации

[vak]

Я давно мечтал найти простой способ делать документацию. Word и LibreOffice не устраивают: слишком трудоёмко, LaTeX - слишком сложно. Наконец нашёл приемлемый вариант. Процесс укладывается в четыре шага.

(1) Текст готовится в формате MarkDown. Это по сути простое текстовое представление с самоочевидными правилами разметки, вставки рисунков и подготовки таблиц.

(2) Рисунки делаются в формате SVG в редакторе Inkscape или из скрипта на Питоне. Затем рисунки конвертируются в формат EPS для вставки в документ.

(3) Исходный текст преобразуется в формат OpenDocument (он же ODT или *.odt) утилитой Pandoc. При этом стили форматирования подставляются из заранее заготовленного файла-шаблона. Формат ODT понимают LibreOffice, Word и многие другие wysiwyg-редакторы.

(4) Файл ODT преобразуется в PDF посредством LibreOffice.

Весь процесс легко автоматизируется посредством Makefile. Последовательность выглядит примерно так:

inkscape -z picture.svg -E picture.eps
pandoc -f markdown -t odt --reference-odt=my-style.odt input.md -o output.odt
soffice --convert-to pdf output.odt --headless

Comments

[nms]

Ты забыл про библиографию. Или не употребляешь по утрам? (-:

А так да, я такую технологию "открыл" полгода назад.

Осталось дождаться когда спецы по библиографии сделают российские ГОСТы. )-:

[vak]

Вроде у pandoc есть флажок --bibliography=FILE. Но я не пользую, нет. Прочие фишки типа индекса можно в принципе добавлять уже на этапе ODT.

[spamsink]

Зачем через ODT, если можно с тем же успехом через HTML, заодно порождая и документ, хорошо читаемый онлайн?

[vak]

Можно и в HTML, и в EPUB, и Wiki-странички для Github генерить, всё это pandoc умеет. Но отправная точка всё же PDF.

[spamsink]

Я про то, что при рендеринге страницы в HTML не нужно делать из SVG никаких EPS, а прилады командной строки к вебкиту для генерации PDF из HTML существуют.

[vak]

Вместо EPS придётся делать PNG, а значит качество рисунков пострадает. Потом, при генерации PDF из HTML возникает проблема настройки стилей, а здесб она элегантно решена через документ-шаблон.

[spamsink]

SVG уже сто лет как рендерится нативно. И если pandoc достаточно умный, то он должен порождать HTML того же качества, что и ODT, приписывая соответствующие стили.

[vak]

Я просто не вижу преимуществ HTML перед MarkDown. Зачем конвертировать в HTML, если можно прямо так вывесить? А для печати PDF всяко удобнее.

[fenikso]

Еще и в source control можно нормально положить :)

[vak]

Именно! И видеть всю историю изменений документа.

[vit_r]

Не знаю для кого Латех сложен. Настраивается шаблон, а потом всё просто гонится с минмальными усилиями в стандартном процессе.

[vak]

Pandoc умеет и LaTeX генерить, просто заменяем -t odt на -t latex.

[juan_gandhi]

Опа! Все мои проблемы решены! Спасибо.

[vak]

Рад поделиться находкой. Спасибо разработчикам проекта Pandoc, классную штуку сваяли.

[cross_join]

Год назад я подобную технологию, только из Textile вместо MarkDown, предложил одному коллеге. Потому что он к тому времени уже начал в своем углу херачить прямо в HTML. В итоге был обвинен в том, что инженер. Я, соответственно, год с ним не разговариваю, пусть трахается дальше.
Если эта технология у вас пойдет на работе, кинь мне ссылочку, пожалуйста, "порадую" директора.

[vak]

На работе вряд ли. Тут у нас есть группа технических писателей, у них своя налаженная технология.

[cross_join]

А нельзя ли концептуально-тезисно описать "ихнюю" технологию? Что используется для "сырья", какие цепочки?

[quark_p]

Что то не получается каменный цветок. Начал ваять заметку, перевожу в PDF а оно зараза плюется. Скриншот: https://ibb.co/c2O7Q5
UPD Разобрался, в тексте было пару слешей, надо экранировать апострофами. Теперь нужно разобраться как форматировать\настраивать PDF (поля, ориентация-формат листа)

[vak]

Если форматировать не через LaTeX, а через ODT, то формат документа настраивается в файле-шаблоне (--reference-odt=my-style.odt).