From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp-1.sys.kth.se (smtp-1.sys.kth.se [130.237.32.175]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id pASKefbw010409 for ; Mon, 28 Nov 2011 15:40:42 -0500 (EST) Received: from mailscan-1.sys.kth.se (mailscan-1.sys.kth.se [130.237.32.91]) by smtp-1.sys.kth.se (Postfix) with ESMTP id BDC1A155920 for ; Mon, 28 Nov 2011 21:40:36 +0100 (CET) X-Virus-Scanned: by amavisd-new at kth.se Received: from smtp-1.sys.kth.se ([130.237.32.175]) by mailscan-1.sys.kth.se (mailscan-1.sys.kth.se [130.237.32.91]) (amavisd-new, port 10024) with LMTP id nHvdcuU7fwHq for ; Mon, 28 Nov 2011 21:40:36 +0100 (CET) X-KTH-Auth: kristaps [83.250.6.251] X-KTH-mail-from: kristaps@bsd.lv X-KTH-rcpt-to: tech@mdocml.bsd.lv Received: from macky.local (c83-250-6-251.bredband.comhem.se [83.250.6.251]) by smtp-1.sys.kth.se (Postfix) with ESMTP id E20891558ED for ; Mon, 28 Nov 2011 21:40:35 +0100 (CET) Message-ID: <4ED3F1C3.3070509@bsd.lv> Date: Mon, 28 Nov 2011 21:40:35 +0100 From: Kristaps Dzonsons User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:8.0) Gecko/20111105 Thunderbird/8.0 X-Mailinglist: mdocml-tech Reply-To: tech@mdocml.bsd.lv MIME-Version: 1.0 To: tech@mdocml.bsd.lv Subject: Conventional lists in mdoc(7) sections. Content-Type: multipart/mixed; boundary="------------010806070800020803010409" This is a multi-part message in MIME format. --------------010806070800020803010409 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit 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 --------------010806070800020803010409 Content-Type: text/plain; name="patch.txt" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="patch.txt" 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 --------------010806070800020803010409-- -- To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv