On 9/25/25 09:04, Arsen Arsenović wrote:
Unfortunately, it is. A collection of linear mostly-unrelated pages in
predetermined shape simply cannot document complex software, a
hierarchical approach is non-negotiable.
libc, (most of) the syscall API and coreutils are a lucky case in that
they are, fundamentally, large collections of *very* simple bits
(functions and programs),
It wasn't "lucky". "Do one thing and do it well" was an explicit design
decision the Bell Labs guys made in 1971. Doug McIlroy wrote about it in
1978 in the Forward to the article on "The Unix TimeSharing System" in
the Bell System Technical Journal in 1978: "do one thing and do it well"
and then compose more complicated things from simple parts. Peter Salus
reiterated it in "a quarter century of unix" (a book about the
anniversary), and Mike Gancarz' book "the unix philosophy" went into
this in some detail.
That's why they could get away with a flat namespace and simple man
pages and so on for decades.
Gnu's Not Unix in quite a number of ways.
but the fact that manpages are insufficient is
visible in everything about Linux other than the syscall API. Finding
documentation for Linux cmdline parameters, pseudo-FSes and various
components is a Herculean task.
The utility command line parameters are on the web at
https://man7.org/linux/man-pages/man1/intro.1.html which seemed
reasonably straightforward to me. (Over the years it's accumulated a lot
of extra crap from optional packages, but as failure modes go it could
be worse...)
The kernel command line arguments are at
https://kernel.org/doc/Documentation/admin-guide/kernel-parameters.txt
and filesystems are at
https://kernel.org/doc/Documentation/filesystems/squashfs.txt (first
I've heard pseudo, it's usually called "synthetic", ala
https://landley.net/toybox/doc/mount.html unless you have a reference I
don't?)
But then I was briefly the linux kernel's Documentation maintainer in a
previous life so I may be biased. (Jonathan Corbet of lwn.net has that
position now, I believe.) I did a certain amount of analysis back when
it was my job, ala https://kernel.org/doc/ols/2008/ols2008v2-pages-7-18.pdf
The man pages present simple text output created from text input. The
source is in a legacy typesetting format from 1971 (created for the AT&T
patent and licensing department and aimed at a brand of daisy-wheel
printer that no longer exists), but even
http://www.catb.org/~esr/doclifter/doclifter.html back in 2003 could
already migrate that to something else and people decided "nah, qwerty
ain't so bad, better the devil you know...".
No, it's both. The 'man' macro package is imperative and unstructured
rather than declarative and structured,
People were offered docbook 20 years ago. It was worse. (There's no
docbook gui editor because it's TOO structured, in ways that are not
easily visually represented. It's an ivory tower academic solution.)
and 'roff' is quite cumbersome
to use. The BSDs (I think?) have attempted to solve this partially with
mdoc. I've found authoring with it slightly better. Unfortunately,
however, it is still 'roff'.
But, indeed, pagers are inadequate viewers also.
The man package's build scripts have produced html output for many
years, you can do it on your laptop from a git clone.
OpenBSD, IIRC,
provided slight improvement in this regard by letting 'less' read some
type of list of tags that it produces out of the manual page, or
somesuch, to facilitate jumping. This is a significant move in the
right direction, but it doesn't manage to address the fact that manpages
are non-hierarchical.
If I want "man insmod" I don't have to know it's in section 8. Making it
more granular turns out to be less useful.
You're complaining about 40 year old design decisions that have
persisted for good reason. People have been free to change it all along.
This addresses half of the issue (what if the pages are old?), and still
leaves the fact its a separate software distribution unsolved.
Either people updated the docs or they didn't. Having an active
well-known place to go look and complain at is useful. Requiring
somebody to read the source code and provide a copyright assignment to
tweak documentation... well you've tried that since 1983, how did it go?
There may be some selection bias in the people who constantly read and
edit this source code finding this source code to be the best place to
put the docs. Learn to cook at the oven factory.
Rob
