Zsh Mailing List Archive
Messages sorted by: Reverse Date, Date, Thread, Author

Re: Modernizing Documentation format?


On 8/22/2025 3:49 PM, Marc Chantreux wrote:

On Fri, Aug 22, 2025 at 11:54:35AM -0500, Clinton Bunch wrote:

Neither has strong support for generating documentation in the other
format.  Sphinx treats both as first-class "citizens".

https://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#Output-Formats

plain text and epub are pretty cool! the missing one is zeal docset
(https://zealdocs.org/). I see this usage growing and have to admit
it's pleasant to use when you are a GUI person.
But strikingly missing is man or mdoc.  As I said, while I think it struggles with as complicated a program as a shell, man is far too integral to the platform to abandon as a first-class form of documentation.  But I also think a modern HTML format documentation is important.  texi2any might give us that with a better crafted stylesheet than the default, but the default looks decidedly dated. 


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

good take: I sometimes have the problem with some of the zsh manuals, never with
the perl ones. I think it's due to the way information is dispatched:

apropos \^zsh

zsh (1)              - the Z shell
zshall (1)           - the Z shell meta-man page
zshbuiltins (1)      - zsh built-in commands
zshcalsys (1)        - zsh calendar system
zshcompctl (1)       - zsh programmable completion
zshcompsys (1)       - zsh completion system
zshcompwid (1)       - zsh completion widgets
zshcontrib (1)       - user contributions to zsh
zshexpn (1)          - zsh expansion and substitution
zshmisc (1)          - everything and then some
zshmodules (1)       - zsh loadable modules
zshoptions (1)       - zsh options
zshparam (1)         - zsh parameters
zshroadmap (1)       - informal introduction to the zsh manual The Zsh Manual
zshtcpsys (1)        - zsh tcp system
zshzftpsys (1)       - zftp function front-end
zshzle (1)           - zsh command line editor

the weird ones are:

* zsh and zshroadmap should be zsh (a unique entry point)
* sometimes I don't know if's zshbuiltins, zshmisc and zshcontrib

I really think this problem will not be fixed with the info system
as the structure remains the same.

I would like to make some proposals here. I tried once but realize
I'm not fluent enough in english to write tech doc.


Man is good for reference on small single use programs.

please take a look at man perl to see the way they organized the
documentation. the tutorial section is awesome.

the whole thing is writen in POD and those pages are actually available
on the CPAN site: https://metacpan.org/dist/perl/view/pod/perlootut.pod
I've been writing perl since perl 4.  I'm well aware of the perl man page and it's a perfect example of my assertion that man struggles with large, complex things.  The Camel book is much better at teaching it, and about half the time google is better reference material. 





* it's here for bad reasons (mostly active lobbying at the time when
    the unix culture was mostly ignored)

Python was one of the early adopters of micro-service architecture and has …

sorry I bring this on the list. I shouldn't. If we meet at a conference,
it's the perfect topic to share around a beer.


* it can be defeated.

Eventually it will go the way of perl and eventually COBOL, but until then,
it has its purpose.  Right now it is a highly marketable skill.

So you think Perl is gone? that's cute :)

Perl had some adoption problems when people came to the IT as windows
users with java background. unix idioms and FP style were unusual and
unconfortable for people stuck in procedural style and filled of OOP
bigotery.

but

* lot of hackers stuck on perl for lot of good reasons
* perl and its ecosystem never stopped to evolve
* young generations of programmers have no fear of unix and lambdas
   anymore so they are receptive to perl idioms and expressivity

So perl is definetely not dead.
Dead, no.  But fading, yes.  I see few new projects written in perl. It doesn't make the top 10 of languages on github.  I'm sorry to see it go, but yes, perl is drastically losing popularity from where it was 15 years ago.
I've been looking for a new job as a Unix/Linux admin for more than a year.  I don't think I've seen a single job posting that listed perl without listing python, bash, and usually Java as well and plenty that don't list perl at all as an example of an automation language.
None of this discussion of programming languages is really pertinent to a discussion of a new documentation system for zsh to replace YODL, which I think we can all agree is surviving by the CPR we're performing on it.
I believe the man pages should look like they were written as man pages.  I think the texinfo should feel like it was written in texinfo.  I think the HTML should feel like it was written in modern HTML/CSS (sensing light/dark preferences and handling mobile screens) but still usable on tty-based browsers.
I haven't seen an example of mandoc that doesn't look like a man page presented in a web browser.  Texinfo at best requires two converters to get documentation in the end goal formats.
I want to see zsh thrive and part of that is attracting new users and if our documentation looks like it's stuck in the last century, that is a lot harder. 



regards.
Messages sorted by: Reverse Date, Date, Thread, Author