Почему я считаю man-ы плохим форматом документации?

Мне казалось что об этом писал в блоге, но что-то с ходу не нашёл.

man-ы мне в первую очередь не нравятся тем, что в них нет ссылок и
возможности перехода по ним. Напишут "смотрите EXAMPLES", и вводи
"/EXAMPLES", а ещё лучше с не забывать "/^EXAMPLES". Напишут смотреть
другой man, и снова делать это всё руками. А как открыть man сразу на
нужной секции? Штатного способа не предлагают. Хотя можно и сделать хак
в виде: man -P "less +/^EXAMPLES" ...

Другое дело info! То самое, что является единственным и основным
форматом документации в GNU. Оно уже структурировано, имеет ссылки. По
сути это уже гипертекстовый документ/формат, куда раньше появившийся чем
HTML. Можно одним вызовом (-n опция) прыгнуть на нужные ссылки/ноды.

man для простых и коротких команд, чисто классических по идеологии Unix,
ещё терпимо, так как зачем им ссылаться на что-то, ведь команда
выполняет свою чётко заданную работу. Но огромных программ тоже не мало.
Один GnuPG чего стоит (но у него и info есть (собственно, man-ы в нём из
него делаются)). А вот когда речь про документацию на библиотеку (C), то
без ссылок жизнь не мила. Один man perl содержит *только* ссылки на
несколько десятков других man-ов, как и man zsh содержит ссылки или иди
в zshall.

info ещё приятен тем, что он сам по себе human-readable формат, который
можно и без дополнительного ПО прочитать. man не читабельный, но его
формат всё же достаточно прост для простых утилит -- да и кто когда-либо
жаловался на то, что он не может прочитать man? Идеология вызова
каких-нибудь eqn и tbl процессоров (в дополнении к troff) мне нравится
даже больше чем жёстко отрендеренный info. Но, так как на практике это
всё равно всё смотрится в терминале, то желания перерендерить не
возникает -- is good enough.

Как альтернатива info мог бы выступать HTML, который тоже из терминала
можно смотреть текстовыми броузерами. Но, если каждую ноду выносить в
отдельный .html, то нельзя будет искать по всей документации к
программе/библиотеке! А в .info можно по всей. Делать одну большую
.html-ку решает проблему, но её будет неудобно читать, но это уж можно и
потерпеть.

А если документация просто огромна? .info позволяет разделять её на
отдельные файлы:

      6942 gnupg.info
    300360 gnupg.info-1
    271959 gnupg.info-2

где в головном .info есть ссылки на -[12], динамически подгружаемые
файлы по мере надобности. С .html такой возможности нет (если только не
терять возможность поиска). .info же делает это просто автоматически.

В общем случае .info позволяет и картинки встраивать (точнее ссылаться
на них, в отдельных файлах), но я видел работоспособность этого только в
Emacs графическом.

По мне так это прям чуть ли не идеальный формат для документации. Ok, на
самом деле Microsoft CHM тоже выглядит как в теории хорошая
альтернатива, если бы конечно не была проприетарной. Это и HTML, который
может быть перерендерен как надо (или в терминале смотришь, или в GUI на
4k мониторе), и ещё и сжат в одном bundle-е, и ещё и поиск по нему
возможен. С обычным .html, в принципе, тоже никто не запрещает
использовать grep по файлам, но удобно ли это? Но готовых решений для
.chm просмотра (с поиском) мне не известно чтобы написали, тогда как
.info существует уже больше тридцати лет (судя по Wikipedia, ссылающейся
на ITS Emacs, почти 40 лет).

          ------------------------ >8 ------------------------

Но .info ещё нужно и чем-то создать. Штатно предлагаемый GNU Texinfo это
отдельный формат мне так нравящийся!

* Писать руками .man -- небольшого размера ещё терпимо, но в целом
  увольте этим заниматься!
* Писать HTML от руки можно, хотя и не очень удобно читать его исходный
  код. Но терпимо, но всё же не даром не многие на нём пишут напрямую.
* Markdown -- полностью не признаю этот формат. Ибо НЕТ такого формата!
  Есть только с десяток (больше?) разрозненных малосовместимых между
  собой диалектов. И я уже десятки раз видел как кто-то даёт "markdown",
  но именно моим процессором оно не обрабатывается. ОЧЕНЬ небольшое
  подмножество будет работать гарантированно везде. Настолько небольшое,
  что мне в принципе оно не интересно, ибо это несерьёзно. А писать на
  "github markdown", "XXX markdown", "whatever markdown"... серьёзно?
* reStructured Text -- так как его реализаций не много (не одна ли
  docutils?), то он будет работать, в отличии от Markdown, везде. Именно
  reST, а не Sphinx надмножество. Мне он нравился и хоть он и зависит от
  Python, но я на reST/Sphinx писал всё на свете. Даже web-сайты были
  когда-то все на нём сделаны, ибо HTML выхлоп у него вполне себе
  хороший. Но... его возможностей форматирования мне не хватало
  частенько. Сделать жирную ссылку -- проблема (собственно, я даже не
  помню можно ли это в принципе сделать). Делать сложные структуры с
  многоуровневыми списками и табличками внутри -- ± можно, но уже очень
  сложно читается и требует большой аккуратности из-за отступов.
  Генерировать reST тоже становится проблематично
* AsciiDoc -- использовал его на первой работе (не мой выбор). Мало чего
  по нему помню, но, хотя бы, это вроде бы действительно отдельный
  нормальный формат, а не куча диалектов под одним именем (ненавижу
  сраный Markdown!). git документация написана на нём. Выглядит как
  хорошая альтернатива reST, но всё равно зависит от Python, в котором
  де-факто reST
* Texinfo -- на этот формат я возможно не смотрел потому что он ещё с
  80-х годов. Возможно потому что есть "tex" и кажется что имеется связь
  с TeX. Но это лучший формат что я видел для создания .html (и конечно
  же .info)! Некая золотая середина между гибкостью и свободой
  самовыражения HTML и лёгкостью чтения/написания reST! Плюс написал на
  C/Perl, поэтому работает очень быстро, не требует тяжёлых Python-ов.
  Удобен для машинного генерирования. Удобен для работы в редакторе.
  Имеет множество плюшек и сахара для создания документации по исходному
  коду (reST не имеет, но Sphinx через директивы поддерживает).

Texinfo явно сильно заточен для создания доки по программам. Может
мешать местами его древовидная работа с нодами, однако такая же
древовидная требуется и в Sphinx например. Всё же Texinfo/Sphinx это не
general purpose средства, а для определённых задач. Но это всё равно
перекрывается простотой, гибкостью, удобством работы с ним. Вообще
Texinfo создавался сразу же и для того, чтобы из доки можно было сделать
.tex файлы и сразу из них отрендерить печатный вариант (книгу). Это
никогда не проверял как работает и априори полагаю что с кириллицей
возникнут проблемы. Sphinx тоже умеет генерировать .tex (LaTeX? не помню
уже), который с кириллицей не работал из коробки. .info файлы вроде
Sphinx-ом плохо генерировались.

А ещё, что скорее является anti-feature, но Texinfo это единственное
через что я смог сделать максимально работоспособный Word-compatible
выхлоп. Texinfo создаёт Docbook, который можно открыть в LibreOffice и
он его отлично отрендерит, даже со всеми таблицами и *почти* не
потерянным форматированием (насколько помню, только заголовки почему-то
были не нужного размера -- но они были всё же заголовками). Сделать
что-то из Sphinx-а, чтобы было так же похоже на ожидание, что через
*Office-ы можно было бы сконвертировать -- не выходило.

Когда я восхищаюсь огромному количеству документации в man-ах
OpenBSD/FreeBSD, то я восхищаюсь и аплодирую именно наличию
документацию, а не её формату. Но GNU выбор Texinfo/Info я считаю лучшим
что есть.

комментарий 0:

From: Алексей
Date: 2020-11-06 09:19:20Z

В интерфейсе info/pinfo я люто, бешено ненавижу их абсолютно невменяемую систему прокрутки. Когда внутри секции прокрутка идёт на одну строчку, но после завершения секции сразу перелистывается целая страница.
И вот например оглавление любого туториала приходится выкручивать аккуратными нажатиями клавиши "вниз", потому что сразу после последней строчки страница перелистнётся к первой секции.
Какой идиот вообще такое придумал?

комментарий 1:

From: Sergey Matveev
Date: 2020-11-06 09:41:11Z

*** Алексей [2020-11-06 12:19]:
>В интерфейсе info/pinfo я люто, бешено ненавижу их абсолютно невменяемую систему прокрутки.

Солидарен! Тоже бесит. И только сейчас я решил посмотреть есть ли
настройки для этого. Оказалось что есть: scroll-behavior=Page Only
как-раз оставит тебя на текущей странице, никуда не переходя.

>Какой идиот вообще такое придумал?

Emacs-еры :-). Но вообще в доке они это преподносят как фичу:

     [...]
     If you are at the end of a node, <SPC> takes you to the
     "next" node, so that you can read an entire manual from start to
     finish by repeating <SPC>.

А вот pinfo я быстро отбросил потому что он не отображал кириллицу. Но
сейчас, поискав есть ли решение проблемы, наткнулся на
https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=240553 который год
назад вроде бы как исправляет её. Надо будет попробовать. Визуально
pinfo помилее выглядит, хотя вот все клавиши что я использовал в info
уже в нём не работают.

комментарий 2:

From: Sergey Matveev
Date: 2020-11-06 09:58:52Z

*** Sergey Matveev [2020-11-06 12:41]:
>https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=240553

Да, кириллица с этим патчем видна. Оказывается просто нужно использовать
cursesnw. Но пока я заметил что pinfo только ссылки подсвечивает цветом,
а обычный info так не может. А во всём остальном не увидел плюсов (чисто
для .info) и наверное не буду использовать. А то в GNU info у меня и
scroll через мышку работает (у меня на трэкболе крутящееся колесо есть,
часто использую) и на следующую ноду не прыгает при этом (теперь). Плюс
GNU info умеет делать split окон, хотя я забыл про эту фичу, но какие-то
keybinding-и делал для этого.