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