RE: Re: Modernizing Documentation format?

[zeurkous@xxxxxxxxxxxxxxx]

On Fri, 22 Aug 2025 10:01:31 +0200, Marc Chantreux <mc@xxxxxxxxxx> wrote:
> Well =E2=80=A6 if textinfo is important, then why not just write in textinfo
> which is also a rich documentation format?
>
>[snip]
>
> Both mandoc and texinfo are capable here. Maybe texinfo can be
> interesting because man pages becomes sections of a whole
> "zsh documentation" entity so there will be no more zshall.

Me'll skip many of the unkind things me has to say about texinfo, and
get straight to the point: texinfo is not really compatible with the
UNIX way, and trying to have one format generate both texinfo and man
outputs is akin to trying to have one's cake and eat it too.

If texinfo is really that desired: me proposes that a separate texinfo
copy of the documentation be maintained in the same tree. After all,
otherwise, the next bone of contention will just be which of the two the
{HTML,PostScript,...} output is to be based on. They're fundamentally
unalike.

> I really love the way perl and zsh handle things (the main man is
> the index of more thematic mans) and AFAIS(aw)

Me, on the other hand, has little love for it. It's a necessary
compromise. It could easily be argued that the shell should've had its
own manual section all along.

> * lot of people just don't use info
>   * most just don't know it exists
>   * the ergonomy of the info command is terrible
> * info is pleasant just for people who installed emacs or vim plugins.

AOL. But me's not against an info version of the documentation being
maintained in-tree.

        --zeurkous.

-- 
Friggin' Machines!