[self-follow-up] I forgot to type out one of the numbered points I had in mind.
At 2025-01-22T20:47:25-0600, G. Branden Robinson wrote:
> > Maybe what you have in mind is that i abhor a few specific sections
> > that are occasionally seen in the wild, most notably OPTIONS
> > and NOTES. Those are indeed always terrible style and deserve
> > to be shot on sight, with no warning. OPTIONS is usually the most
> > important part of the DESCRIPTION and splitting it out is at best
> > pointless, but usually causes disorganization.
>
> I see your point but disagree. I think I've made these points before
> but I'll recapitulate.
>
> 1. GNU and Linux programs have a tendency to efflorescence in the
> option department. There often way too damned many. Given that
> bloat, as you might put it, a structured document _must_ respond,
> just as historical macro packages listed rosters of symbols
> (registers, strings, macros) at the end of the man page (if they
> did so at all). Similarly, even a troff of 1976 dimensions needed
> lists of requests and escape sequences. Maybe OpenBSD doesn't
> have this problem, though that must depend a lot on whether you'll
> reject a program from the ports collection on that basis alone.
>
> Getting the authors of every executable command that any GNU/Linux
> or POSIX system user can run to rëengineer their tools around a
> principle of slimming down the option list seems a hopeless task.
> Knowing I'll die long before I get people to fix any of the other
> problems I notice with their man pages is enough futility for me.
Permit me to add:
2. Command-line option descriptions frequently need to make mention of
application features. If those haven't been presented yet, an
option description can be mystifying. Employment of terms that
haven't been defined is frustrating in nearly all forms of writing.
I don't think uttering the lazy man page author's mantra, "it's a
reference, not a tutorial" relieves one of responsibility to
organize material in a way that coheres well and builds the reader's
understanding if they choose to absorb the document linearly.
I grant that, with complex systems, a strictly incremental
development of material is impractical. Sometimes there are cycles
in our graph of conceptual dependencies. But we should try to
minimize those.
I acknowledge that some people want to see the option list on the first
screenful of the man page, no matter what. I think they are better
served by (1) a help message and/or (2) using simpler tools.
> > NOTES is almost always the hallmark of a totally disorganized page.
Heh. I've been adding, or further populating, a lot of these in the
ncurses man pages over the past 15-16 months. If it's any consolation,
I've also undertaken to explain what ncurses uses its less common
sections for.
ncurses(3X):
ncurses man pages employ several sections to clarify matters of
usage and interoperability with other curses implementations.
• “NOTES” describes issues and caveats of which any user of the
ncurses API should be aware, such as limitations on the size of
an underlying integral type or the availability of a
preprocessor macro exclusive of a function definition (which
prevents its address from being taken). This section also
describes implementation details of significance to the
programmer but which are not standardized.
• “EXTENSIONS” presents ncurses innovations beyond the X/Open
Curses standard and/or the SVr4 curses implementation. They
are termed extensions to indicate that they cannot be
implemented solely by using the library API, but require access
to the library’s internal state.
• “PORTABILITY” discusses matters (beyond the exercise of
extensions) that should be considered when writing to a curses
standard, or for multiple implementations.
• “HISTORY” examines points of detail in ncurses and other curses
implementations over the decades of their development,
particularly where precedent or inertia have frustrated better
design (and, in a few cases, where such inertia has been
overcome).
The foregoing language is (substantially) present in the ncurses 6.5
release, made last April.
I may need eventually to revise the description of the "HISTORY"
section; over the past year I've found myself populating pages with a
chronological record of API development. The System V developers added
many good and useful features to curses, but design discipline was
lacking and foresight frequently poor. I surmise the absence of
architectural guidance over the approximately 11 years of System V
curses's active life.
BSD curses, by contrast, was born with a few warts but was stable to the
point of stagnation for nearly the entire remaining lifetime of the
CSRG. (Keith Bostic swooped in at the end and cleaned a lot stuff up.)
Anyway, I have managed to digress yet again.
Regards,
Branden
signature.asc
Description: PGP signature
