Hi Branden,
G. Branden Robinson wrote on Thu, Jan 23, 2025 at 01:04:29PM -0600:
> 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.
This is usually mitigated by concisely describing what the default
behaviour is *before* the options section, typically in one or two
paragraphs. If the task at hand really needs the definition of
domain-specific terms, they can often be introduced in these introductory
paragraphs in a natural way, though that need is not particularly
common except in relatively complicated manual pages.
The option description then usually flows well by simply specifying
how exactly the option modifies the default behaviour.
[...]
> 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).
Some of that belongs in CAVEATS by convention.
Some of it, if part of the API, belong to the basic DESCRPTION of the
respective feature ("the *c* argument is a non-negative number not
larger than 255..." which is really important to say right away
for a function like isalpha(3)) or are obvious from the SYNPOSIS and
if the API uses the proper type (no need to say that if the argument
is "unsigned char c"). Some such caveats would be out of place in
any manual page because no manual page should re-document basic
language features of the C language ("be careful, the 'int c'
argument might only be 32 bit long, so it may not be able to
accept numbers larger than 2147483647").
The very last sentence in a DESCRIPTION can easily be: "the foo, bar
and baz functions are implemented as macros" or "... may be implemented
as macros". No need to say more than that. Even for a reader
unfamiliar with basic rules of the C language, it is obvious that
makes taking an address impossible, because macros are not even a C
feature, but a cpp(1) feature.
So this description of NOTES is an eclectic heap of vague and
mutually unrelated, overly specific examples that forms no overall
pictuare what the section is about - a very nice illustration of
what i mean by disorganized.
> This section also describes implementation details of
> significance to the programmer
That's an oxymoron. The definition of "implementation detail" is
"a property that is not part of the API", hence by definition it
is not of significance to the programmer and cannot be relied on.
> but which are not standardized.
By definition, implementation details are never 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.
In my experience, that way lies madness.
Write:
DESCRIPTION
foo mogrifies bar.
-a Mogrify in the following alternate way: ...
-x In addition, also mogrify in the following extended way: ...
STANDARDS
Conforms to the MOGRIX specificication.
The -x option is an extension to that standard.
That way, the user sees right away what the program can do, in an
organized way, with all options in the right place.
Do not add an EXTENSIONS section. That scatters the options
all over the place and makes it easy to miss some. It becomes
even worse when the extensions are semantic rather than syntactic.
That would cause the DESCRIPTION to describe something the program
does not really do, only correcting the mistake much later below
EXTENSIONS.
> • “PORTABILITY” discusses matters (beyond the exercise of
> extensions) that should be considered when writing to a curses
> standard, or for multiple implementations.
That might occasionally make sense, though it's not very frequent.
When the amount of text needed is small, it can be included in the
more conventional CAVEATS.
> • “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).
Sure, nothing wrong with that, though it's more common to merely
say when programs, options, or functions first appeared, given
that design missteps hopefully aren't all that common.
Yours,
Ingo
