Re: Modernizing Documentation format?

[dana <dana@xxxxxxx>]

On Fri 22 Aug 2025, at 11:54, Clinton Bunch wrote:
> Man is good for reference on small single use programs.  It struggles
> with large programs or languages.

that's how i feel also. if it's a language, compiler, etc, i prefer
html. and ours does the job but it could be a lot better

On Fri 22 Aug 2025, at 17:41, Clinton Bunch wrote:
> None of this discussion of programming languages is really pertinent to
> a discussion of a new documentation system for zsh to replace YODL,

yes, 99% of documentation changes are going to be in the documentation
language, so how anyone feels about the syntax or 'culture' of whatever
it's implemented in doesn't seem that important

the main thing is how annoying of a dependency it is. python is
pre-installed on almost every system anyone would be developing zsh on,
or it's trivial to get if somehow it's not, so i think it's fine

On Fri 22 Aug 2025, at 17:41, Clinton Bunch wrote:
> I haven't seen an example of mandoc that doesn't look like a man page
> presented in a web browser.

afaik that's deliberate. mandoc is designed exclusively for producing
traditional-style man pages and its feature set and rendering output
reflect that

even if that wasn't the case i think maintaining a large body of
documentation in any roff-derived language is a nightmare. i can't think
of any non-legacy projects that do it. the syntax is disgusting and it's
full of weird rules that even people who are familiar with it always
forget. imo it would be a downgrade from yodl

idk about texinfo. i have managed to avoid it my entire life. it doesn't
seem popular outside of gnu projects in any case

the obvious competitor to rst is adoc, but the dependency on ruby is
probably more objectionable than the python one, and i don't think the
syntax or functionality is any better than rst's

some projects still use docbook but many that previously did (linux,
gnome, bind, nixos, rsync) have switched away

straight markdown is almost ideal to me syntax-wise but we'd need tonnes
of boiler-plate to get the functionality we want

the myst extension for sphinx semi addresses that by taking rst's
functionality and making it a superset of commonmark. but it seems like
it's still not used much outside of the python eco-system. maybe that
would make people nervous

dana