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 +#include + +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