Re: [groff] man page structure and philosophy (was: mom manpage)

[Ingo Schwarze]

Hi,

G. Branden Robinson wrote on Tue, Dec 11, 2018 at 08:58:28AM -0500:
> At 2018-12-05T12:35:12+0100, Ulrich Lauther wrote:

>> In my opinion, a man page should contain (at most) NAME, SYNOPSIS,
>> COPYRIGHT, DESCRIPTION, OPTIONS, ARGUMENTS, INVOCATION, but not
>> LANGUAGE.

> I'm going to have come out against this.

It was obvious Ulrich's list wan't meant seriously because more
than half of it was non-standard and more than half of the standard
sections (see groff_mdoc(7)) weren't included, so it isn't really
worth arguing about.  But of course i agree with most of your
answers, Branden.

[...]
> * any non-default responses to signals (ASYNCHRONOUS EVENTS)
> 
> The last is, admittedly, particularly rare; I tend to see it mainly in
> POSIX man pages (which Ingo insists, with some justification, are
> counter-examples of good man page writing),

POSIX provides a technical standard, not documentation; only some
parts of the form happens to be similar to manual pages, but not
the purpose, structure, or conventions.

> but this is also because
> many tool writers tend not to install signal handlers (even when they
> should), and also tend not to document them at all when they do, causing
> much merriment.

I tend to think that minimizing the use of signals is wise because
the concept is relatively fragile and error-prone, in particular
compared to other concepts of inter-process communication like pipes
and sockets.  But those questions are off-topic on this list.

What matters here is where to document signals, when handling them is
implemented.

Typically, and in particular when signals are used well, programs
only handle a small number of signals in non-trivial ways that
warrant documentation, often only one or two signals, and the bare
statement what the signal does rarely requires more than a single
sentence, which means that the section ASYNCHRONOUS EVENTS would
typically be extremely short.

Even worse, the effect of the signal is often intricately intertwined
with other aspects of program behaviour, which are typically explained
in the DESCRIPTION.  Here is a typical example from the syslogd(8)
manual page:

  When starting up, syslogd reads its configuration file, syslog.conf(5),
  and opens the configured logfiles and TCP and TLS connections.
  The logfiles already have to exist with the correct permissions.
  When receiving a SIGHUP signal, it closes all open logfiles and
  outgoing TCP and TLS connections and re-runs this initialization
  sequence.  Sending this signal is required both after editing the
  configuration file and after log rotation.

Setting up a separate ASYNCHRONOUS EVENTS section would totally
destroy the logical coherence of this paragraph and likely result
in duplicate information, with both copies remaining logically
incomplete.

As another example, consider this paragraph from ping(8):

  When the specified number of packets have been sent (and received),
  or if the program is terminated with a SIGINT, a brief summary
  is displayed.  The summary information can also be displayed while
  ping is running by sending it a SIGINFO signal (see the status
  argument of stty(1) for more information).

So i think there are good reasons for avoiding ASYNCHRONOUS EVENTS.
It certainly isn't a standard section in manual pages.

Yours,
  Ingo