[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [groff] Asynchronous events
From: |
Ingo Schwarze |
Subject: |
Re: [groff] Asynchronous events |
Date: |
Wed, 12 Dec 2018 03:32:11 +0100 |
User-agent: |
Mutt/1.8.0 (2017-02-23) |
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
- Re: [groff] gratitude for man pages (was: mom manpage), (continued)
- [groff] man page structure and philosophy (was: mom manpage), G. Branden Robinson, 2018/12/11
- Re: [groff] man page structure and philosophy (was: mom manpage), Ingo Schwarze, 2018/12/11
- [groff] Asynchronous events (was: man page structure and philosophy (was: mom manpage)), G. Branden Robinson, 2018/12/11
- Re: [groff] Asynchronous events,
Ingo Schwarze <=
- Re: [groff] Asynchronous events, James K. Lowden, 2018/12/12
- Re: [groff] Asynchronous events, Ralph Corderoy, 2018/12/28
Re: [groff] mom manpage, James K. Lowden, 2018/12/05
Re: [groff] mom manpage, Bertrand Garrigues, 2018/12/05
- Re: [groff] mom manpage, Peter Schaffter, 2018/12/06
- Re: [groff] mom manpage, Colin Watson, 2018/12/07
- Re: [groff] mom manpage, Peter Schaffter, 2018/12/07
- Re: [groff] mom manpage, Ingo Schwarze, 2018/12/07
- Re: [groff] mom manpage, Bertrand Garrigues, 2018/12/08