Re: mdoc EXIT STATUS (Was: pending open issues)

[Ingo Schwarze <schwarze@usta.de>]

Hi,

the exchange of information and opinions where to best put exit status
documentation for section 1, 6, and 8 manuals seems unfinished to me;
if i understand correctly, what FreeBSD and DragonFly want and do is
plain enough (EXIT STATUS), but in NetBSD and OpenBSD, i find such
information sometimes in DESCRIPTION, sometimes in DIAGNOSTICS.

However, i'm not trying to settle that question today, right in the
middle of the OpenBSD release process.  Right now, i'm just proposing
a preliminary patch documenting the status quo, which will hopefully
not remain the last word on this matter.

I think it is a bad idea to tell people without any reservation
they should use EXIT STATUS when actually, two systems do not
use that section - no matter whether that is "at all" or "not yet".

OK to commit this for now?

Yours,
  Ingo


Index: mdoc.7
===================================================================
RCS file: /cvs/src/share/man/man7/mdoc.7,v
retrieving revision 1.46
diff -u -p -r1.46 mdoc.7
--- mdoc.7	3 Aug 2010 00:07:57 -0000	1.46
+++ mdoc.7	3 Aug 2010 20:57:39 -0000
@@ -347,7 +347,7 @@ utility processes files ...
 \&.\e\*q The next is for sections 1, 6, 7, & 8 only.
 \&.\e\*q .Sh ENVIRONMENT
 \&.\e\*q .Sh FILES
-\&.\e\*q The next is for sections 1 & 8 only.
+\&.\e\*q The next is for sections 1, 6 & 8 only.
 \&.\e\*q .Sh EXIT STATUS
 \&.\e\*q .Sh EXAMPLES
 \&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
@@ -514,11 +514,20 @@ the file is used (created, modified, etc
 See
 .Sx \&Pa .
 .It Em EXIT STATUS
-This section documents the
+Some operating systems, for example
+.Fx
+and
+.Dx ,
+use this section to document the
 command exit status for section 1, 6, and 8 utilities.
-Historically, this information was described in
-.Em DIAGNOSTICS ,
-a practise that is now discouraged.
+Others, for example
+.Nx
+and
+.Ox ,
+show the same information in the
+.Em DIAGNOSTICS
+section or near the end of the
+.Em DESCRIPTION .
 .Pp
 See
 .Sx \&Ex .
@@ -528,11 +537,8 @@ This often contains snippets of well-for
 Make sure that examples work properly!
 .It Em DIAGNOSTICS
 Documents error conditions.
-This is most useful in section 4 manuals.
-Historically, this section was used in place of
-.Em EXIT STATUS
-for manuals in sections 1, 6, and 8; however, this practise is
-discouraged.
+This is most useful in section 4 manuals,
+but sometimes also used for section 1, 6, and 8 utilities.
 .Pp
 See
 .Sx \&Bl
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv