Re: [PATCH] man-pages.7: Document CAVEATS section

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 4322 bytes --]

Hi Ingo,

On 7/26/22 17:37, Ingo Schwarze wrote:
> Hi Alejandro,
> 
> Alejandro Colomar wrote on Tue, Jul 26, 2022 at 04:29:49PM +0200:
>> On 7/26/22 15:54, Ingo Schwarze wrote:
>>> Alejandro Colomar wrote on Tue, Jul 26, 2022 at 02:08:18PM +0200:
> 
>>>> CAVEATS is an interesting section from OpenBSD.
> 
>>> It is no doubt nice when credit is given to OpenBSD,
>>> but in this case, it happens to be undeserved.  ;-)
>>>
>>> I see the following early uses of ".SH CAVEATS":
>>>
>>>    * 4.2BSD execve(2), released September 1983, author unknown
>>>    * 4.3BSD-Tahoe patch(1), released June 1988, author: Larry Wall
>>>    * 4.3BSD-Reno amd(8), released June 1990, author: Jan-Simon Pendry
>>>    * 4.4BSD strftime(3), released June 1993, author: Arnold Robbins
>>>    * 4.4BSD gzip(1), released June 1993, author (unsure) Jean-loup Gailly ?
>>>    * 4.4BSD mount_kernfs(8), released June 1993, author: Jan-Simon Pendry
>>>
>>> The first instance of ".Sh CAVEATS" i found is:
>>>
>>>    * 4.4BSD-Lite1 realpath(3), released April 1994, author Keith Bostic
>>>
>>> It doesn't look as if the UC CSRG used CAVEATS in additional files.
>>>
>>> Standardization was decided in NetBSD during a discussion
>>> on <tech-userlevel@netbsd.org> leading to this commit:
>>>
>>>     /src/share/misc/mdoc.template revision 1.6
>>>     date: 2002-07-10 09:45:18 +0000;  author: yamt;  lines: +2 -1;
>>>     add CAVEATS section. discussed on tech-userlevel.
>>>
>>> The login name "yamt" belongs to YAMAMOTO Takashi.
>>>
>>> It was then quickly picked up in OpenBSD by Jason McIntyre.
>>>
>>> So the section has a tradition of almost 40 years and has been
>>> standardized in *BSD for about two decades, even though it was
>>> not originally a BSD invention.
> 
>> Wasn't it a BSD invention?  The sources you mentioned seem to say it is.
> 
> Well, i looked through BSD history first because that's easiest for me,
> but it is striking that the authors listed above are not really BSD
> people:
> 
>   * Larry Wall is the author of perl(1) and not associated with USB or BSD.
> 
>   * Jan-Simon Pendry eventually got an account (pendry@) and ultimately
>     scored slightly above 1000 commits to BSD, but he was an outside
>     contributor and not a member of the CSRG as far as i know.
> 
>   * Arnold Robbins joined the GNU awk(1) project in 1988 and eventually
>     to over maintenance from Paul Rubin, Jay Fenlason, and RMS.
>     Later on, he also contributed to GNU coreutils.
>     In fact, the reason his strftime(3) manual page was included
>     in 4.4BSD is because it was part of his gawk(1) distribution
>     which was included into BSD back then.
> 
>   * gzip(1) was also included into BSD as outside code, below contrib/.
> 
> The only unambiguous CSRG person in the above list is Keith Bostic,
> and by the time he used CAVEATS, the section had already been in use
> for more than a decade.
> 
>> Would it be correct to say "... section from the BSDs"?
> 
> Some might misunderstand even that.  The final CSRG BSD release
> only contained about seven instances, all but about two coming
> from outside sources, which is not quite what most would expect
> hearing "from the BSDs".  Besides, Version 10 AT&T UNIX preceded
> 4.4BSD-Lite1 by about five years and contained more instances
> of CAVEATS.
> 
> I dug up some more instances:
> 
>   * AT&T System III UNIX man(7), released 1982
>   * AT&T UNIX, Eighth Edition ksh(1), released February 1985
>   * AT&T UNIX, Tenth Edition about seven addition pages, released 1989
> 
> So you could say something like this:
> 
>    This section has been used in pages written in the man(7) language
>    by authors from a wide range of projects including AT&T, Korn shell,
>    Perl, GNU and BSD since the early 1980s.
>    Using the section was first officially recommended in 2002
>    by the file /usr/share/misc/mdoc.template in NetBSD and OpenBSD.
> 
> According to my knowledge, that would be accurate.

Thanks for the investigation.  Committed, with a similar commit message 
(changing references to man(7) by "manual pages", since I consider 
mdoc(7) pages as relevant in this regard).

Thanks,

Alex


-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]