RE: Re: Modernizing Documentation format?

[zeurkous@xxxxxxxxxxxxxxx]

On Fri, 22 Aug 2025 17:41:46 -0500, Clinton Bunch <cdbunch@xxxxxxxxxxx> wrote:
> but the default looks decidedly dated.

Who cares if it looks dated, as long as it's usable?

> perl. It=20
> doesn't make the top 10 of languages on github.=C2=A0

Me's not seen one well-maintained project, in any language, exclusively
hosted on github.

Not a single one.

> year.=C2=A0 I don't think I've seen a single job posting that listed perl=
> =20
> without listing python, bash, and usually Java as well and plenty that=20
> don't list perl at all as an example of an automation language.

Many of us are weird folk, we don't do things 'cause we get paid, we do
things 'cause they're interesting (and hopefully make things better).

(But if we get paid for it anyway: all the better!)

> None of this discussion of programming languages is really pertinent to=20
> a discussion of a new documentation system for zsh to replace YODL,=20
> which I think we can all agree is surviving by the CPR we're performing=20
> on it.

As long as we don't leave the patient with irrepairable brain damage.

> I believe the man pages should look like they were written as man=20
> pages.=C2=A0 I think the texinfo should feel like it was written in texin=
> fo.=C2=A0=20

That's something we can agree on :)

> I think the HTML should feel like it was written in modern HTML/CSS=20
> (sensing light/dark preferences and handling mobile screens) but still=20
> usable on tty-based browsers.

The HTML world is a free-for-all, both the man and info approaches would
be equally valid, as long as things are properly linked. Let's make sure
we don't have to choose between the two.

> I haven't seen an example of mandoc that doesn't look like a man page=20
> presented in a web browser.=C2=A0

Me'd argue that's not a bad thing at all.

> I want to see zsh thrive and part of that is attracting new users and if=20
> our documentation looks like it's stuck in the last century, that is a=20
> lot harder.

A life lesson, one that me's learned long ago: things can be very
contemporary and yet anything but modern. Beware of that.

        --zeurkous.

-- 
Friggin' Machines!