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

[G. Branden Robinson]

At 2018-12-11T18:44:50+0100, Ingo Schwarze wrote:
> 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.

This is true, and yet I feel I perceive more parallels than you do.
However, I'm not prepared at this point with a comparison/contrast list
to support my intuition.  When I'm ready to show, and not just tell, I
will.  :)

> > 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.

Oh, but what a fun off-topic discussion.  My vague recollection is that
Bell Labs discarded signals altogether in Plan 9 in favor of "notes",
but that even those proved to have frustrating concurrency properties so
those were ditched too for Inferno (or perhaps only a later edition of
Inferno).

A Plan 9/Inferno post-mortem, one focused on issues besides "Why didn't
this beat Unix?"--the very least interesting question--would be a very
valuable thing to have.  I recklessly speculate that we never got it
because (1) the band was breaking up (Bell Labs veterans were retiring
or going elsewhere) and (2) Alcatel/Lucent needed a "business case" for
producing such literature that would make a difference to the bottom
line within two quarters, and one could not be contrived.

Austrian School economists love to justify their laissez-faire
capitalist intuitions using the thought experiment of Robinson Crusoe
trapped on a desert island with his manservant, Friday.  They call this
getting down to fundamental principles; to me, it seems more like a
reflection of their preferred social organization and a tacit admission
of what level of technological and scientific development their
economics will admit.

> 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.

When I was first learning signals, I was admonished that signal handlers
should be very simple.  Have a main loop that checks flags which only
signal handlers set.  In each handler, set the flag for the relevant
event, and get the hell out.  The actual event handling takes place only
within ordinary synchronous logic dispatched from the main loop, where
you don't have to worry about which libc functions you should be
avoiding because you're in a signal handler, _because you're not_.

I have not yet found reason to question this wisdom, but I would not
claim to be an expert.

> 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.

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.

On the other hand, maybe I am worrying about the cool kids who can't be
reached anyway--they don't stoop to the level of documenting their code.
The poor saps who actually write the man pages might not need to be
clubbed over the head.

But I wonder...

Regards,
Branden

signature.asc
Description: PGP signature