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

Alejandro Colomar
2022-07-26T19:02:54Z

[-- 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 --]