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
