From: Sergey Matveev <stargrave@stargrave.org>
Date: Sat, 30 Aug 2025 07:03:39 +0000 (+0300)
Subject: В zsh обсуждают смену формата документации
X-Git-Url: http://www.git.stargrave.org/?a=commitdiff_plain;h=7d11856584768c1fb0bf941cd754898ef7d73909;p=stargrave-blog.git

В zsh обсуждают смену формата документации

Хотя бы не сраный Markdown предлагают. Всё обсуждение сводится либо к
reStructured Text, либо AsciiDoc. А также к тому, что люди критикуют тот
же info, банально просто в нём не разобравшись. Полностью солидарен с
одним из писем:

    IMO, and especially with zsh's manual where it's of exceptional
    quality, "info" is orders of magnitude better than man or HTML
    (and I don't even use half its features).

    The killer feature is definitely the index (i), with completion
    and searchable (I) and available on command line (like in "info
    zsh typeset"; and with (perfectible as discussed not so long ago
    here) completion in zsh). The day I discovered that, there was
    no turning back.

    Compared to HTML:
    - can be used from a terminal (like zsh, a terminal application,
      more than anything else).
    - quicker to bring up: info zsh; even info zsh <Tab> for
      completion on nodes vs x-www-browser
      /usr/share/doc/zsh-doc/html/index.html
    - can be searched as a whole (/) or current tree (ESC /) and s,
      ^S... alternatives for those used to emacs.
    - regexp support in search
    - index jump one key away (i, next with ,)
    - index with completion
    - index search one key away (I)
    - node navigation (prev, next, up...) with single keys
    - node search with completion
    - easier hyperlink navigation than in most browsers
    - no need for a mouse

Учитывая сложности в установке зависимостей для Python, reST так
себе вариант. С ним я провёл бОльшую часть жизни и не хотел бы
возвращаться к нему. Впрочем для многих мест я и Texinfo перестал
использовать в пользу своего SWG, который тоже умеет генерировать info.

Вообще заметил что опытные разработчики никогда не выбирают Markdown,
приводя, как минимум, один и тот же аргумент о том, что нет такого
формата (о котором бы все договорились) и он отнюдь не прост для парсинга.
---