RE: Re: Modernizing Documentation format?

[zeurkous@xxxxxxxxxxxxxxx]

On Thu, 21 Aug 2025 08:33:01 -0500, Clinton Bunch <cdbunch@xxxxxxxxxxx> wrote:
> All documentation formats are horrible, because writing documentation is=20
> horrible. :)

Sorry? Writing documentation is one of the most noble, satisfying
efforts me's ever engaged in. If the code is clear, the documentation
basically writes itself.

> roff produces horrible HTML with no styling capability.=C2=A0 It's a=20
> typesetter not a documentation format.=C2=A0 It is meant for printed page=
> s.

Please do enlighten me: what would be unstyled about e.g. [0] :?

> No.=C2=A0 Because typesetting is about presentation, not documentation.

Nonsense. Ever heard of mdoc(7)?

> RST has much richer semantics than roff.

We need frugal semantics; rich ones just distract from the content.

> We need a lot more than flags, subcommands, and parameters.

Oh reallly? Or are those extra requirements perhaps just artifacts
of the existing documentation system?

> Not all documentation is a man page.

Such as 'Doc/intro.ms', you mean? Certainly not roff! (Cough, cough.)

> I've been reading man pages for more than three decades,=C2=A0 they lack=20
> internal cross referencing

*BZZT*

There's '.Sx', '.Tg', and whatnot.

> and indexes,

*BZZT*

apropos(1), or more classically, 'man -k', perhaps?

> it's hard to find the specific=20
> information you need quickly.=C2=A0 Especially in a large man page like a=
>  shell.

Yes, navigating zsh's near-monstrous[1] complexity using texinfo is much
much easier!

(If you consider crushed glass easier to eat than pizza, that is.[2])

Also, '.Tg'.

In all: please try not to make such ill-informed comments.

        --zeurkous.

[0] https://man.OpenBSD.org./sh.1
[1] That's how it is, no offense intended.
[2] Personal opinion.

-- 
Friggin' Machines!