Lev Walkin (lionet) wrote,
Lev Walkin
lionet

Category:

Pandoc and Manual Pages

Итак, надоело мне рисовать мануальные страницы через nroff. Как в asn1c, например:



Проблемы с подготовкой документации в 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
Subscribe
  • Post a new comment

    Error

    Anonymous comments are disabled in this journal

    default userpic

    Your reply will be screened

    Your IP address will be recorded 

  • 22 comments