* Conventional lists in mdoc(7) sections.
@ 2011-11-28 20:40 Kristaps Dzonsons
2011-11-29 0:21 ` Ingo Schwarze
0 siblings, 1 reply; 3+ messages in thread
From: Kristaps Dzonsons @ 2011-11-28 20:40 UTC (permalink / raw)
To: tech
[-- 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
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: Conventional lists in mdoc(7) sections.
2011-11-28 20:40 Conventional lists in mdoc(7) sections Kristaps Dzonsons
@ 2011-11-29 0:21 ` Ingo Schwarze
2011-11-29 15:08 ` Kristaps Dzonsons
0 siblings, 1 reply; 3+ messages in thread
From: Ingo Schwarze @ 2011-11-29 0:21 UTC (permalink / raw)
To: tech
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
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: Conventional lists in mdoc(7) sections.
2011-11-29 0:21 ` Ingo Schwarze
@ 2011-11-29 15:08 ` Kristaps Dzonsons
0 siblings, 0 replies; 3+ messages in thread
From: Kristaps Dzonsons @ 2011-11-29 15:08 UTC (permalink / raw)
To: tech; +Cc: Jason McIntyre
[-- 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
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2011-11-29 15:08 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2011-11-28 20:40 Conventional lists in mdoc(7) sections Kristaps Dzonsons
2011-11-29 0:21 ` Ingo Schwarze
2011-11-29 15:08 ` Kristaps Dzonsons
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).