Pandoc and Manual Pages
Итак, надоело мне рисовать мануальные страницы через nroff. Как в asn1c, например:
Проблемы с подготовкой документации в nroff такие:
...не, ну вы всерьёз подумали, что я тут копролитофагские проблемы буду поднимать?
Ну, реально :) Итак, маны будем писать в Markdown, а потом через pandoc конвертировать непосредственно в tcpkali.1.
Казалось бы, ничто не предвещало беды. И даже как-то вроде получилось, в целом:
но перед этим пришлось преодолеть несколько препятствий.
tcpkali.1: tcpkali.man.md
${PANDOC} --from markdown --to man -o $@ \
--template templates/default.man \
--variable header="Version ${VERSION}" \
--variable adjusting:l \
$<
В итоге, сам мануал получился довольно прилично. Если его читать через команду man, а не в исходниках.
К сожалению, тот набор твиков, которые пришлось приложить к маркдаун-исходнику, таков, что этот маркдаун теперь нельзя использовать для генерации, скажем, HTML или PDF. Вот вам и один исходник - много таргетов. Не работает это с маркдауном... Более того, его нельзя использовать самостоятельно: очень уж нелепо выглядит.
https://github.com/machinezone/tcpkali/blob/master/doc/tcpkali.man.md
Проблемы с подготовкой документации в nroff такие:
...не, ну вы всерьёз подумали, что я тут копролитофагские проблемы буду поднимать?
Ну, реально :) Итак, маны будем писать в Markdown, а потом через pandoc конвертировать непосредственно в tcpkali.1.
Казалось бы, ничто не предвещало беды. И даже как-то вроде получилось, в целом:
но перед этим пришлось преодолеть несколько препятствий.
- Дефолтный пандоковский темплейт для man-документов не содержит способа сделать выравнивание по левому краю. Обновил до последнего из https://github.com/jgm/pandoc-templates.
- Даже новый пандоковский темплейт неправильно выключает переносы. Так выключает, что выключение не работает. В итоге опции --foo-bar часто переносятся сразу перед bar. Пофиксил, сделал пулл-реквест.
- Таблицы в ман-странице порождают лишнюю пустую строку над собой, если не указывать табличный заголовок (title).
- Нельзя надёжно форсировать перенос строки внутри таблицы.
- До сих пор не понимаю, как отключить двойные пробелы в предложениях...
tcpkali.1: tcpkali.man.md
${PANDOC} --from markdown --to man -o $@ \
--template templates/default.man \
--variable header="Version ${VERSION}" \
--variable adjusting:l \
$<
В итоге, сам мануал получился довольно прилично. Если его читать через команду man, а не в исходниках.
К сожалению, тот набор твиков, которые пришлось приложить к маркдаун-исходнику, таков, что этот маркдаун теперь нельзя использовать для генерации, скажем, HTML или PDF. Вот вам и один исходник - много таргетов. Не работает это с маркдауном... Более того, его нельзя использовать самостоятельно: очень уж нелепо выглядит.
https://github.com/machinezone/tcpkali/blob/master/doc/tcpkali.man.md