Re: [groff] Asynchronous events

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Tue, Dec 11, 2018 at 07:31:35PM -0500:
> At 2018-12-11T18:44:50+0100, Ingo Schwarze wrote:

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

> I think your argument has merit, but my concern is that without an
> "ASYNCHRONOUS EVENTS" or "SIGNALS" section dangling over their heads,
> people will neglect to document their signal handling at all.

All kinds of relevant information can be forgotten when writing
a manual page.  Here are a few examples of topics often forgotten:

 * The exact format of expected input, where applicable, if it
   goes beyond command line options and arguments.

 * What error handling does, precisely.

 * The precise format of intermediate files used, and sometimes
   even the output format of the program itself.

 * Which conditions are logged to syslog, what the messages mean,
   and the facility and priority used, which is relevant if users
   want to set up syslog.conf(5).

 * ...

I guess more examples could be found, and i don't really see how
signals are more important or might require more text than some of
the above topics.

Also, examples exist of information that is almost never correct and
complete even though standard sections are defined and often used:

 * DIAGNOSTICS.
   With the exception of device driver manuals, very few pages
   list possible messages that the program can emit, and even
   fewer explain clearly what they mean and what to do about them.
   Even device driver manuals are often extremely terse here.

 * ERRORS.
   Most system call pages and many library function pages have
   this section, but the information being complete is the
   exception rather than the norm.  Even in OpenBSD.

So i think it's a normal matter of diligence and documentation review
rather than of defining a new section, which won't magically make
new text appear.  If you want to help, cd /usr/src/usr.sbin/;
grep -RF sigaction *; look at the manual pages whether the signal
handling is documented; if not, look at the code whether it is
non-trivial; if it is, submit patches!  ;-D

Yours,
  Ingo