?

Log in

No account? Create an account

Previous Entry | Next Entry

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

Comments

( 22 comments — Leave a comment )
maxim
Dec. 2nd, 2015 11:01 am (UTC)
А я после того, как ты мне показал HeVeA, так и остался на ней.
lionet
Dec. 2nd, 2015 11:04 am (UTC)
Из хевеи манов не сваришь.
oleyka
Dec. 2nd, 2015 11:07 am (UTC)
// До сих пор не понимаю, как отключить двойные пробелы в предложениях...

Я уж было подумала, ты сдался и так теперь и надо ;)
tzirechnoy
Dec. 2nd, 2015 11:36 am (UTC)
>что я тут копролитофагские проблемы

Фига заявочки. Запахло каким-то хипстерством.
lionet
Dec. 2nd, 2015 11:44 am (UTC)
Вот один из первых моих манов: http://lionet.info/ipcad/man-ipcad.html (сконвертированный в html, разумеется).

За пятнадцать-то лет можно было что-то более удобноее придумать в плане ауторинга? Ну вот и пробую хипстерские технологии. Pandoc на Хаскеле написан, если что.
tzirechnoy
Dec. 2nd, 2015 11:52 am (UTC)
Я, если чо, совсем не про pandoc, а тем более не про markdown.

Я про то, что ты по непонятной причине наезжаешь на вполне рабочую, более того, во многих аспектах превосходящую всех конкурентов технологию. Притом единственным аргументом наезда -- то, что её придумали 45 лет назад.
lionet
Dec. 2nd, 2015 12:17 pm (UTC)
Причина понятна: nroff — это барьер на создание манов. Их же не каждый день пишешь, детали забываются. Я даже макросы писал на нём время от времени. Но сейчас этот барьер не нужен, потому что уже есть технологии, которые покрывают 99% современной нужды в nroff. (Мы же на тайпсеттеры не выводим вывод от nroff, правда? Только маны и пишем.) Покрывают так, что тебе не приходится напрягаться каждый раз, когда нужно что-то добавить ли поправить. Nroff как первичный формат уже является impeding фактором для создания приличного софта, а не enabling. Я год назад начал писать tcpkali, и вот только-только руки до манов дошли. А всё почему? Потому что лениво восстанавливать контекст того, как это делается, если не делать это каждый день.

А между тем, маркдауном народ реально пользуется каждый день, ну или по крайней мере в десятки, сотни раз чаще, чем nroff'ом. Через вики его знают, через гитхаб, через джиру. Поэтому меньшего когнитивного барьера для создания приличных манов, чем конверт из маркдауна, на мой взгляд, не найти.

И это я полностью скипнул такие ответвтления, как создания манов из XML, что было популярно в начале двухтысячных. Скипнул поколение технологии, не повёлся на XML-запах. А ты говоришь "хипстерство". Никакое не хипстерство, а очень даже рациональное поведение.

Edited at 2015-12-02 12:18 pm (UTC)
tzirechnoy
Dec. 2nd, 2015 12:34 pm (UTC)
>Причина понятна: nroff — это барьер на создание манов.

Это хипстерские отговорки. Барьер на создание манов -- нежэлание настоящего программиста писать всякую очевидную мутотень, когда можно херачить код. Сам по себе nroff к этому никакого отношэния не имеет, тем более, что заметная часть манов пишэтся безо всякого nroff...

>И это я полностью скипнул такие ответвтления,

Ещё раз -- я не про знакомый тебе маркдаун (кстати, вот я его не знаю. groff, tex, latex, BBcode, mediawiki, html -- кое-как знаю, да. А markdown просто не случился), и не про твоё решэние писать маны в каком-либо формате. Хотя от XML попахивало бы, да. Я про твой беспричинный и бездоказательный наезд на nroff.
lionet
Dec. 2nd, 2015 12:37 pm (UTC)
> Барьер на создание манов -- нежэлание настоящего программиста писать всякую очевидную мутотень, когда можно херачить код.

Покажи последний ман, который ты написал?
tzirechnoy
Dec. 2nd, 2015 12:47 pm (UTC)
Нет.
lionet
Dec. 2nd, 2015 12:54 pm (UTC)
Ну то есть ты просто языком поводить сюда пришёл, по всей видимости.

1. Если ты давно не писал манов, хотя надо бы — то это элемент воздействия барьера, о котором я сказал ранее.
2. Если ты давно не писал манов, и нафиг не надо — то это подтверждает мои слова о копролитичности технологии. Как nroff в частности, так и манов вообще. Документацию-то ты как-то создаёшь ведь. И то, что документацией являются не маны, кое о чём говорит.
3. Если тебе вообще в принципе не нужно писать маны, поэтому ты не писал — ну так не мешай людям, которым надо писать маны, и которые пишут маны, облегчать себе задачу.
4. Если ты писал раньше и проблем раньше не видел — подожди, пока в очередной раз придётся писать ман, тогда и поговорим.
5. Если ты сейчас пишешь маны пачками, и не показываешь их — это говорит о том, что либо они все жутко секретные, либо мнимые.

Короче, я пока не вижу способа тебе с успехом доказать свою правоту в этой ветке.

Edited at 2015-12-02 12:54 pm (UTC)
nealar
Dec. 2nd, 2015 01:12 pm (UTC)
о копролитичности технологии манов вообще
Вот тут поддержу.
В бизибоксы маны не кладут, а на десктопах команду "man mycoolprog" я вбиваю в строку поиска гугла.
max630
Dec. 4th, 2015 07:57 am (UTC)
Как правило если для продукта не существует оффлайновых док (не обазятельно в виде манов, это могут быть html файлики или что-нибудь своё), то в гугле тоже искать бесполезно - максимум что найдётся это решения чьих-то конкретных проблем.

Edited at 2015-12-04 07:57 am (UTC)
tzirechnoy
Dec. 2nd, 2015 01:49 pm (UTC)
>Ну то есть ты просто языком поводить сюда пришёл, по всей видимости.

Ну, а что ты думал, я тебе через ЖЖ пирожэнку сооружу или в репу дам? Конечно, языком поводить, это ведь ЖЖ!

>то это элемент воздействия барьера, о котором я сказал ранее.

С чего ты взял, что это элемент воздействия этого барьера? По факту, конечно, нет, оба барьера совсем другие.

>Документацию-то ты как-то создаёшь ведь.

Обычно -- нет. Обычно это делают другие люди. Почему-то.

Но это не важно. Я совершэнно непонимаю, как из того, что я редко пользуюсь технологией X или там вообще не пользуюсь (кстати, я правда непомню, из-за чего в своё время трахался с этими .TH и .EX) как-то следует, что технология X плоха. Ещё хужэ я понимаю, почему из этого следует, что ты не можэшь мне объяснить, чем она плоха, и вынужден срываться в FUD.


PS Проблем я, конечно, видел. Тогда. Нет ни одной технологии писания записок, с которой я не видел бы проблем -- включая все те, которые я перечислил в предыдущем моём комменте, а такжэ MS Word и Perl POD. Впрочем, ты с маркдауном и пандоком вот ровно в этом посте показал, что и с ним проблем есть.
angry_elf
Dec. 2nd, 2015 12:26 pm (UTC)
Лучше юзать commonmark.
lionet
Dec. 2nd, 2015 12:36 pm (UTC)
Для чего?
angry_elf
Dec. 2nd, 2015 01:55 pm (UTC)
Ну, CommonMark вроде как наследник Markdown, чётко специфицированный, в отличии от.
lionet
Dec. 2nd, 2015 02:57 pm (UTC)
Отличаешь формат (markdown) от тулзы (pandoc) и воркфлоу?
vitus_wagner
Dec. 2nd, 2015 12:56 pm (UTC)
У commonmark как-то хреновато с выходными форматами. Что-то ни *roff, ни TeX, ни FB2 я там не вижу.

А в данном случае требуется *roff в качестве выходного формата.

sheremetyev
Dec. 2nd, 2015 08:12 pm (UTC)
Следующий этап - писать мануальные страницы в визивиг-редакторе. Попробовал поредактировать tcpkali.man.md в Texts (бессовестная реклама :) и перегенерировать tcpkali.1. Вроде даже не сильно портится — только ширина столбцов в таблицах немного меняется и емайл в авторе перестаёт быть ссылкой.
max630
Dec. 4th, 2015 07:53 am (UTC)
А смысле, с nroff _ещё_ больше проблем, чем перечисленные?

Похоже, гитхаб не поддерживает : в начале строки, а больше ничего странного не заметно. Вообще markdown существует как стандарт?

Edited at 2015-12-04 07:58 am (UTC)
lionet
Dec. 4th, 2015 09:18 am (UTC)
Что значит "ещё" больше? Проблем-то только две осталось:

  • Таблицы в ман-странице порождают лишнюю пустую строку над собой, если не указывать табличный заголовок (title).
  • Нельзя надёжно форсировать перенос строки внутри таблицы.


  • Остальное или пофикшено (мой патч применили уже), или то же самое в nroff (двойные пробелы).

    По поводу странного:

  • не выделяются жирным опции
  • "Use the **--source-ip** to override this behavior" (звёздочки)
  • "EXPRESSION % int Remainder" сделалось заголовком
  • Двоеточия в начале строки
  • Бэкслеши: "\ MBps\ (for\ bytes\ per\ second)."
  • "Time ms, s, m, h, d" сделалось заголовком
  • ". Throw 42 requests per second" сделалось заголовком
  • "On TIME-WAIT state and its reuse:\ " <- бэкслеш.
  • ( 22 comments — Leave a comment )

    Profile

    lionet
    Lev Walkin
    Website

    Latest Month

    December 2016
    S M T W T F S
        123
    45678910
    11121314151617
    18192021222324
    25262728293031
    Powered by LiveJournal.com
    Designed by yoksel