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

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

[Alejandro Colomar]

CAVEATS is an interesting section from OpenBSD.  There's a slight
difference between CAVEATS and BUGS.  We usually have a hard time
fitting what would go into CAVEATS into other sections (usually
BUGS and NOTES); it would be easier if we had the section.  Let's
add it.

Reported-by: Ingo Schwarze <schwarze@usta.de>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man7/man-pages.7 | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/man7/man-pages.7 b/man7/man-pages.7
index 99bfa400f..e88b98ddb 100644
--- a/man7/man-pages.7
+++ b/man7/man-pages.7
@@ -174,6 +174,7 @@ VERSIONS	[Normally only in Sections 2, 3]
 ATTRIBUTES	[Normally only in Sections 2, 3]
 CONFORMING TO
 NOTES
+CAVEATS
 BUGS
 EXAMPLES
 .\" AUTHORS sections are discouraged
@@ -421,6 +422,10 @@ to mark off notes that describe the differences (if any) between
 the C library wrapper function for a system call and
 the raw system call interface provided by the kernel.
 .TP
+.B CAVEATS
+Warnings about typical user misuse of an API,
+that don't constitute an API bug or design defect.
+.TP
 .B BUGS
 A list of limitations, known defects or inconveniences,
 and other questionable activities.
-- 
2.36.1

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

[Ingo Schwarze]

Hi Alejandro,

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;  state: Exp;  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.

Yours,
  Ingo

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

[Alejandro Colomar]

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

Hi Ingo,

On 7/26/22 15:54, Ingo Schwarze wrote:
> Hi Alejandro,
> 
> 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;  state: Exp;  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.

Would it be correct to say "... section from the BSDs"?

Cheers,

Alex

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

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

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

[Ingo Schwarze]

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.

Yours,
  Ingo

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

[Alejandro Colomar]

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

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

[Ingo Schwarze]

Hi Alejandro,

Alejandro Colomar wrote on Tue, Jul 26, 2022 at 09:02:40PM +0200:

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

Your commit cb828372 looks good, thanks!

The following is certainly not a big deal, just mentioning it because
chances are this may not have been the last time i contributed
something to your project.

In commit histories, release notes and the like, i prefer being
credited as Ingo Schwarze <schwarze@openbsd.org> rathen than
<schwarze@usta.de>.  The reason is that in a hundred years from
now, i expect people will still know what openbsd.org is, but it
seems rather unlikely they would still know what usta.de was.

You may wonder why i rarely use @openbsd.org in my From: headers.
The reason is that i want to avoid the wrong impression that all my
mails were official statements of the OpenBSD project.  While many
opinions i voice might also be shared by some other OpenBSD developers,
some clearly are not.  And disclaimers in a signature are annoying.
There is less risk that people think i'm speaking for the UStA of
the University of Karlsruhe.  :-)

Probably i should try to remember saying "if you credit me,
please use this address: ..." when a commit is obviously imminent.
I often forget because the vast majority of messages that credit me
are inside OpenBSD, and there it goes without saying.

Yours,
  Ingo

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

[Alejandro Colomar (man-pages)]

Hi Ingo,

On 7/27/22 11:14, Ingo Schwarze wrote:
> Hi Alejandro,
> 
> Alejandro Colomar wrote on Tue, Jul 26, 2022 at 09:02:40PM +0200:
> 
>> 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).
> 
> Your commit cb828372 looks good, thanks!
> 
> The following is certainly not a big deal, just mentioning it because
> chances are this may not have been the last time i contributed
> something to your project.

I hope it's not the last :)

> 
> In commit histories, release notes and the like, i prefer being
> credited as Ingo Schwarze <schwarze@openbsd.org> rathen than
> <schwarze@usta.de>.  The reason is that in a hundred years from
> now, i expect people will still know what openbsd.org is, but it
> seems rather unlikely they would still know what usta.de was.
> 
> You may wonder why i rarely use @openbsd.org in my From: headers.
> The reason is that i want to avoid the wrong impression that all my
> mails were official statements of the OpenBSD project.  While many
> opinions i voice might also be shared by some other OpenBSD developers,
> some clearly are not.  And disclaimers in a signature are annoying.
> There is less risk that people think i'm speaking for the UStA of
> the University of Karlsruhe.  :-)
> 
> Probably i should try to remember saying "if you credit me,
> please use this address: ..." when a commit is obviously imminent.
> I often forget because the vast majority of messages that credit me
> are inside OpenBSD, and there it goes without saying.

Sure, I'll try to remember.

Cheers,

Alex

> 
> Yours,
>    Ingo

-- 
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/