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