RE: Re: Modernizing Documentation format?

[zeurkous@xxxxxxxxxxxxxxx]

On Fri, 22 Aug 2025 11:54:35 -0500, Clinton Bunch <cdb_zsh@xxxxxxxxxxx> wrote:
> Neither has strong support for generating documentation in the other=20
> format.=C2=A0 Sphinx treats both as first-class "citizens".

They happen to be citizens of very different nations.

> I frequently find it hard to use and default to zshall. "What was the=20
> name of that sub man page again?"=C2=A0 "Which of these two sub man pages=
> =20
> would have the information I'm looking for?"

Yes. It's far from ideal.

> Man is good for reference on small single use programs.=C2=A0 It struggle=
> s=20
> with large programs or languages.

No, it doesn't, as long as major subsystems like that get their own
sections.

> Not that I'm saying we should abandon=20
> it for zsh, it's too integral to the environment, but it's not really=20
> the ideal documentation format for the program.

Nothing is ideal for a big, bloated project w/ lots of surprising
interdependencies.

> Python was one of the early adopters of micro-service architecture and=20
> has object-oriented programming as a primary paradigm.=C2=A0

Help help, my buzzword detector is on fire!!!111!

> Both of thos=
> e=20
> are very much in the spirit of Unix.=C2=A0

No, Python could not be further from UNIX. Apart from the fact that its
integration in the shell environment is laughable (last time metried it,
it kept insisting on opening any tty it could get its hands on, when me
was trying to pipe things!), its fascist, "we know what's best for you"
architecture directly opposes UNIX' "here's some tools, enjoy your new
workshop" attitude.

> Do one thing and do it well.=C2=

python does not do one thing, and all those things it does, it does not
do particularly well. It mainly excels in making code monkeys feel like
geniuses. Like in modern colleges this is instant genius: just follow
the (idiotically strict) rules, and you'll be treated as Wunderkinder
forever.

Me digresses.

> =A0 It=20
> also appears to be the language of choice for implementing modern AI=20
> techniques.

AS, you surely mean? (Okay, okay: it's ML.)

> I hate that it has whitespace syntactically significant, I find the lack=20
> of block delimiters to make an otherwise easy to follow language a=20
> little more difficult to read, and I wish it had a native compiled=20
> format, but every language has its drawbacks.

Certainly.

> I took a long time to warm up to python because it was different in may=20
> ways from the languages that came before, but I eventually accepted it=20
> wasn't going away.=C2=A0 And if I wanted to stay competitive in the job=20
> market, I needed to get familiar with it. My many years of perl=20
> experience was not going to get me a job.

That's called "surrender". Me can't believe this, our esteemed French
colleague blazes into a defence of sanity and you're the one waving
the white flag before the battle has even begun.

> Eventually it will go the way of perl and eventually COBOL, but until=20
> then, it has its purpose.=C2=A0

Yes, but purely as a scarecrow: it shows how to empathically *not* to
do things.

> Right now it is a highly marketable skill=
                    ^^^^^^^^^^^^^^^^^

There's a shorter word for that: bullshit.

Sorry.

        --zeurkous.

-- 
Friggin' Machines!