diff options
| -rw-r--r-- | mdoc.7 | 209 |
1 files changed, 178 insertions, 31 deletions
@@ -363,38 +363,185 @@ The sections in a .Nm document are conventionally ordered as they appear above. Sections should be composed as follows: -.Bl -tag -width Ds -offset Ds -.It NAME -Must contain at least one +.Bl -ohang -offset Ds +.It Em NAME +The name(s) and a short description of the documented material. The +syntax for this as follows: +.Bd -literal -offset indent +\&.Nm name0 +\&.Nm name1 +\&.Nm name2 +\&.Nd a short description +.Ed +.Pp +The .Sx \&Nm -followed by -.Sx \&Nd . -The name needs re-stating since one -.Nm -documents can be used for more than one utility or function, such as -.Xr grep 1 -also being referenced as -.Xr egrep 1 -and -.Xr fgrep 1 . -.It LIBRARY -.It SYNOPSIS -.It DESCRIPTION -.It IMPLEMENTATION NOTES -.It EXIT STATUS -.It RETURN VALUES -.It ENVIRONMENT -.It FILES -.It EXAMPLES -.It DIAGNOSTICS -.It ERRORS -.It SEE ALSO -.It STANDARDS -.It HISTORY -.It AUTHORS -.It CAVEATS -.It BUGS -.It SECURITY CONSIDERATIONS +macro(s) must precede the +.Sx \&Nd +macro. +. +.It Em LIBRARY +The name of the library containing the documented material, which is +assumed to be a function in a section 2 or 3 manual. The syntax for +this is as follows: +.Bd -literal -offset indent +\&.Lb libarm +.Ed +.Pp +See +.Sx \&Lb +for details. +. +.It Em SYNOPSIS +Documents the utility invocation syntax, function call syntax, or device +configuration. +.Pp +For the first, utilities (sections 1, 6, and 8), this is +generally structured as follows: +.Bd -literal -offset indent +\&.Nm foo +\&.Op Fl v +\&.Op Fl o Ar file +\&.Op Ar +\&.Nm bar +\&.Op Fl v +\&.Op Fl o Ar file +\&.Op Ar +.Ed +.Pp +For the second, function calls (sections 2, 3, 9): +.Bd -literal -offset indent +\&.Vt extern const char *global; +\&.In header.h +\&.Ft "char *" +\&.Fn foo "const char *src" +\&.Ft "char *" +\&.Fn bar "const char *src" +.Ed +.Pp +And for the third, configurations (section 4): +.Bd -literal -offset indent +\&.Cd \*qit* at isa? port 0x2e\*q +\&.Cd \*qit* at isa? port 0x4e\*q +.Ed +.Pp +Manuals not in these sections generally don't need a +.Em SYNOPSIS . +. +.It Em DESCRIPTION +This expands upon the brief, one-line description in +.Em NAME . +It usually contains a break-down of the options (if documenting a +command), such as: +.Bd -literal -offset indent +The arguments are as follows: +\&.Bl \-tag \-width Ds +\&.It Fl v +Print verbose information. +\&.El +.Ed +Manuals not documenting a command won't include the above fragment. +. +.It Em IMPLEMENTATION NOTES +Implementation-specific notes should be kept here. This is useful when +implementing standard functions that may have side effects or notable +algorithmic implications. +. +.It Em EXIT STATUS +Command exit status for section 1, 6, and 8 manuals. This section is +the dual of +.Em RETURN VALUES , +which is used for functions. Historically, this information was +described in +.Em DIAGNOSTICS , +a practise that is now discouraged. +.Pp +See +.Sx \&Ex . +. +.It Em RETURN VALUES +This section is the dual of +.Em EXIT STATUS , +which is used for commands. It documents the return values of functions +in sections 2, 3, and 9. +.Pp +See +.Sx \&Rv . +. +.It Em ENVIRONMENT +Documents any usages of environment variables, e.g., +.Xr environ 7 . +.Pp +See +.Sx \&Ev . +. +.It Em FILES +Documents files used. It's helpful to document both the file and a +short description of how the file is used (created, modified, etc.). +.Pp +See +.Sx \&Pa . +. +.It Em EXAMPLES +Example usages. This often contains snippets of well-formed, +well-tested invocations. Make doubly sure that your examples work +properly! +. +.It Em DIAGNOSTICS +Documents error conditions. This is most useful in section 4 manuals. +Historically, this section was used in place of +.Em EXIT STATUS +for manuals in sections 1, 6, and 8; however, this practise is +discouraged. +.Pp +See +.Sx \&Bl No \-diag . +. +.It Em ERRORS +Documents error handling in sections 2, 3, and 9. +.Pp +See +.Sx \&Er . +. +.It Em SEE ALSO +References other manuals with related topics. This section should exist +for most manuals. Cross-references should conventionally be ordered +first by section, then alphabetically. +.Pp +See +.Sx \&Xr . +. +.It Em STANDARDS +References any standards implemented or used. If not adhering to any +standards, the +.Em HISTORY +section should be used instead. +.Pp +See +.Sx \&St . +. +.It Em HISTORY +The history of any manual without a +.Em STANDARDS +section should be described in this section. +. +.It Em AUTHORS +Credits to authors, if applicable, should appear in this section. +Authors should generally be noted by both name and an e-mail address. +.Pp +See +.Sx \&An . +. +.It Em CAVEATS +Explanations of common misuses and misunderstandings should be explained +in this section. +. +.It Em BUGS +Extant bugs should be described in this section. +. +.It Em SECURITY CONSIDERATIONS +Documents any security precautions that operators should consider. +. .El . . |