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
