RE: Re: Modernizing Documentation format?

[zeurkous@xxxxxxxxxxxxxxx]

On Fri, 22 Aug 2025 20:40:06 -0500, dana <dana@xxxxxxx> wrote:
> 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

On the contrary, it makes a world of difference when actually writing
the documentation. Once again: {cumbersome,unintuitive} syntax distracts
a writer from the content to be written, diminishing quality.

> 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,

Anyone?

> or it's trivial to get if somehow it's not, so i think it's fine

You think it's fine to essentially stuff such an inherently problematic
dependency down people's throats?

> 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.

UNIX is a legacy project? (Okay, a bunch of people agree that it
should've had a viable successor long ago, but that's a diff
discussion.)

> the syntax is disgusting and it's
> full of weird rules that even people who are familiar with it always
> forget.

Uhm, no, at least not when writing mdoc(7) pages. Are you thinking of
the old man(7) macro package?

        --zeurkous.

-- 
Friggin' Machines!