Re: Conventional lists in mdoc(7) sections.

[Kristaps Dzonsons <kristaps@bsd.lv>]

[-- Attachment #1: Type: text/plain, Size: 2292 bytes --]

>> Enclosed is a patch mentioned some time ago that adds some examples
>> to mdoc(7) regarding the structure of sections.  It basically adds
>> an quick example for DIAGNOSTICS, ERRORS, ENVIRONMENT, FILES, and
>> EXAMPLES.
>
> I like the patch, but you should also try to learns Jason's
> opinion.  A few comments are inline.

Now including jmc@ in the discussion.  Jason, the talk is of augmenting 
mdoc(7) to have some examples of conventional form for the above 
sections.  Thoughts?  Enclosed is the original patch; below are Ingo's 
suggestions.


>> Index: mdoc.7
>> ===================================================================
>> RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc.7,v
>> retrieving revision 1.213
>> diff -u -r1.213 mdoc.7
>> --- mdoc.7	1 Nov 2011 14:59:27 -0000	1.213
>> +++ mdoc.7	28 Nov 2011 20:39:29 -0000
>> @@ -194,11 +194,9 @@
>>   assumed to be a function in a section 2, 3, or 9 manual.
>>   The syntax for this is as follows:
>>   .Bd -literal -offset indent
>> +\&.Sh LIBRARY
>>   \&.Lb libarm
>>   .Ed
>> -.Pp
>> -See
>> -.Sx \&Lb .
>
> I agree with removing the Sx here.
> The trailing "See Nm and Nd" is even more redundant in the preceding
> paragraph, both macros are Sx'ed right above.
>
>>   .It Em SYNOPSIS
>>   Documents the utility invocation syntax, function call syntax, or device
>>   configuration.
>> @@ -325,38 +323,65 @@
>>   .It Em RETURN VALUES
>>   This section documents the
>>   return values of functions in sections 2, 3, and 9.
>> -.Pp
>>   See
>>   .Sx \&Rv .
>>   .It Em ENVIRONMENT
>>   Lists the environment variables used by the utility,
>>   and explains the syntax and semantics of their values.
>> -The
>> -.Xr environ 7
>> -manual provides examples of typical content and formatting.
>> -.Pp
>> -See
>> -.Sx \&Ev .
>> +Fxample:
>
>    For example:
>
>> +.Bd -literal -offset indent
>> +\&.Sh ENVIRONMENT
>> +\&.Bl -tag -width Ds
>> +\&.It Ev MANPATH
>> +Colon-separated paths overriding the default list of
>> +paths searched for manual databases.
>> +\&.El
>> +.Ed
>>   .It Em FILES
>>   Documents files used.
>>   It's helpful to document both the file name and a short description of how
>>   the file is used (created, modified, etc.).
>> -.Pp
>> -See
>> -.Sx \&Pa .
>> +Fxample:
>
> Again:
>
>    For example:

[-- Attachment #2: patch.txt --]
[-- Type: text/plain, Size: 3736 bytes --]

Index: mdoc.7
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc.7,v
retrieving revision 1.213
diff -u -r1.213 mdoc.7
--- mdoc.7	1 Nov 2011 14:59:27 -0000	1.213
+++ mdoc.7	28 Nov 2011 20:39:29 -0000
@@ -194,11 +194,9 @@
 assumed to be a function in a section 2, 3, or 9 manual.
 The syntax for this is as follows:
 .Bd -literal -offset indent
+\&.Sh LIBRARY
 \&.Lb libarm
 .Ed
-.Pp
-See
-.Sx \&Lb .
 .It Em SYNOPSIS
 Documents the utility invocation syntax, function call syntax, or device
 configuration.
@@ -325,38 +323,65 @@
 .It Em RETURN VALUES
 This section documents the
 return values of functions in sections 2, 3, and 9.
-.Pp
 See
 .Sx \&Rv .
 .It Em ENVIRONMENT
 Lists the environment variables used by the utility,
 and explains the syntax and semantics of their values.
-The
-.Xr environ 7
-manual provides examples of typical content and formatting.
-.Pp
-See
-.Sx \&Ev .
+Fxample:
+.Bd -literal -offset indent
+\&.Sh ENVIRONMENT
+\&.Bl -tag -width Ds
+\&.It Ev MANPATH
+Colon-separated paths overriding the default list of 
+paths searched for manual databases.
+\&.El
+.Ed
 .It Em FILES
 Documents files used.
 It's helpful to document both the file name and a short description of how
 the file is used (created, modified, etc.).
-.Pp
-See
-.Sx \&Pa .
+Fxample:
+.Bd -literal -offset indent
+\&.Sh FILES
+\&.Bl -tag -width Ds
+\&.It Pa ~/.profile
+User's login profile.
+\&.El
+.Ed
 .It Em EXIT STATUS
 This section documents 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.
-.Pp
 See
 .Sx \&Ex .
 .It Em EXAMPLES
 Example usages.
 This often contains snippets of well-formed, well-tested invocations.
 Make sure that examples work properly!
+.Pp
+Utilities should show command-line usage:
+.Bd -literal -offset indent
+\&.Sh EXAMPLES
+Print out a list of all core files on local file systems:
+\&.Pp
+\&.Dl $ find / \e! -fstype local -prune -or -name \(aq*.core\(aq
+.Ed
+.Pp
+Functions should show function calls.
+Be terse in your syntax and listed instructions.
+.Bd -literal -offset indent
+\&.Bd -literal -offset indent
+#include <err.h>
+#include <unistd.h>
+
+if (chroot(newroot) != 0 || chdir("/") != 0)
+        err(1, "%s", newroot);
+setresuid(getuid(), getuid(), getuid());
+\&.Ed
+.Ed
 .It Em DIAGNOSTICS
 Documents error conditions.
 This is most useful in section 4 manuals.
@@ -364,15 +389,29 @@
 .Em EXIT STATUS
 for manuals in sections 1, 6, and 8; however, this practise is
 discouraged.
-.Pp
-See
-.Sx \&Bl
-.Fl diag .
+Example:
+.Bd -literal -offset indent
+\&.Sh DIAGNOSTICS
+\&.Bl -diag
+\&.It \(dqne0: where did the card go?\(dq
+The driver found the card, but was unable to make the card respond
+to complete the configuration sequence.
+\&.El
+.Ed
 .It Em ERRORS
 Documents error handling in sections 2, 3, and 9.
-.Pp
-See
-.Sx \&Er .
+Example:
+.Bd -literal -offset indent
+\&.Sh ERRORS
+\&.Fn fork
+will fail and no child process will be created if:
+\&.Bl -tag -width Ds
+\&.It Er EAGAIN
+The system-imposed limit on the total
+number of processes under execution would be exceeded.
+This limit is configuration-dependent.
+\&.El
+.Ed
 .It Em SEE ALSO
 References other manuals with related topics.
 This section should exist for most manuals.
@@ -392,7 +431,6 @@
 If not adhering to any standards, the
 .Em HISTORY
 section should be used instead.
-.Pp
 See
 .Sx \&St .
 .It Em HISTORY
@@ -401,7 +439,6 @@
 .It Em AUTHORS
 Credits to the person or persons who wrote the code and/or documentation.
 Authors should generally be noted by both name and email address.
-.Pp
 See
 .Sx \&An .
 .It Em CAVEATS