Conventional lists in mdoc(7) sections.

Conventional lists in mdoc(7) sections.

[Kristaps Dzonsons]

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

Hi,

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.

Thoughts?

Kristaps

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

Re: Conventional lists in mdoc(7) sections.

[Ingo Schwarze]

Hi Kristaps,

Kristaps Dzonsons wrote on Mon, Nov 28, 2011 at 09:40:35PM +0100:

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

Yours,
  Ingo


> 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:
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: Conventional lists in mdoc(7) sections.

[Kristaps Dzonsons]

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