version 1.40, 2009/10/24 05:45:04 |
version 1.43, 2009/11/02 06:22:45 |
Line 119 from input. These are later re-added, if applicable, |
|
Line 119 from input. These are later re-added, if applicable, |
|
utility such as |
utility such as |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
. |
. |
|
.Ss Dates |
|
The |
|
.Sx \&TH |
|
macro is the only |
|
.Nm |
|
macro that requires a date. The form for this date is the ISO-8601 |
|
standard |
|
.Cm YYYY-MM-DD . |
|
. |
.Ss Scaling Widths |
.Ss Scaling Widths |
Many macros support scaled widths for their arguments, such as |
Many macros support scaled widths for their arguments, such as |
|
stipulating a two-inch list indentation with the following: |
|
.Bd -literal -offset indent |
|
\&.Bl -tag -width 2i |
|
.Ed |
|
. |
|
. |
|
.Ss Scaling Widths |
|
Many macros support scaled widths for their arguments, such as |
stipulating a two-inch paragraph indentation with the following: |
stipulating a two-inch paragraph indentation with the following: |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.HP 2i |
\&.HP 2i |
|
|
at least one macro or text node must appear in the document. Documents |
at least one macro or text node must appear in the document. Documents |
are generally structured as follows: |
are generally structured as follows: |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.TH FOO 1 "13 Aug 2009" |
\&.TH FOO 1 2009-10-10 |
\&. |
\&. |
\&.SH NAME |
\&.SH NAME |
\efBfoo\efR \e(en a description goes here |
\efBfoo\efR \e(en a description goes here |
Line 229 The \efBfoo\efR utility processes files... |
|
Line 246 The \efBfoo\efR utility processes files... |
|
\&.\e\*q The next is for sections 2, 3, & 9 only. |
\&.\e\*q The next is for sections 2, 3, & 9 only. |
\&.\e\*q .SH ERRORS |
\&.\e\*q .SH ERRORS |
\&.\e\*q .SH SEE ALSO |
\&.\e\*q .SH SEE ALSO |
\&.\e\*q \efBbar\efR(1) |
\&.\e\*q .BR foo ( 1 ) |
\&.\e\*q .SH STANDARDS |
\&.\e\*q .SH STANDARDS |
\&.\e\*q .SH HISTORY |
\&.\e\*q .SH HISTORY |
\&.\e\*q .SH AUTHORS |
\&.\e\*q .SH AUTHORS |
Line 237 The \efBfoo\efR utility processes files... |
|
Line 254 The \efBfoo\efR utility processes files... |
|
\&.\e\*q .SH BUGS |
\&.\e\*q .SH BUGS |
\&.\e\*q .SH SECURITY CONSIDERATIONS |
\&.\e\*q .SH SECURITY CONSIDERATIONS |
.Ed |
.Ed |
|
.Pp |
|
The sections in a |
|
.Nm |
|
document are conventionally ordered as they appear above. Sections |
|
should be composed as follows: |
|
.Bl -ohang -offset indent |
|
.It Em NAME |
|
The name(s) and a short description of the documented material. The |
|
syntax for this is generally as follows: |
|
.Pp |
|
.D1 \efBname\efR \e(en description |
|
.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. For functions in |
|
the C library, this may be as follows: |
|
.Pp |
|
.D1 Standard C Library (libc, -lc) |
|
.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: |
|
.Pp |
|
.D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR... |
|
.Pp |
|
For the second, function calls (sections 2, 3, 9): |
|
.Pp |
|
.D1 \. Ns Sx \&B No char *name(char *\efIarg\efR); |
|
.Pp |
|
And for the third, configurations (section 4): |
|
.Pp |
|
.D1 \. Ns Sx \&B No name* at cardbus ? function ? |
|
.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). |
|
.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. |
. |
. |
|
.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. |
. |
. |
|
.It Em ENVIRONMENT |
|
Documents any usages of environment variables, e.g., |
|
.Xr environ 7 . |
|
. |
|
.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.). |
|
. |
|
.It Em EXAMPLES |
|
Example usages. This often contains snippets of well-formed, |
|
well-tested invocations. Make doubly sure that your examples work |
|
properly! Assume that users will skip to this section and use your |
|
example verbatim. |
|
. |
|
.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. |
|
. |
|
.It Em ERRORS |
|
Documents error handling in sections 2, 3, and 9. |
|
. |
|
.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 |
|
.D1 \. Ns Sx \&BR No bar \&( 1 \&), |
|
.D1 \. Ns Sx \&BR No foo \&( 1 \&), |
|
.D1 \. Ns Sx \&BR No baz \&( 2 \&). |
|
. |
|
.It Em STANDARDS |
|
References any standards implemented or used, such as |
|
.Pp |
|
.D1 IEEE Std 1003.2 (\e(lqPOSIX.2\e(rq) |
|
.Pp |
|
If not adhering to any standards, the |
|
.Em HISTORY |
|
section should be used. |
|
. |
|
.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. |
|
. |
|
.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 |
|
. |
|
. |
.Sh MACRO SYNTAX |
.Sh MACRO SYNTAX |
Macros are one to three three characters in length and begin with a |
Macros are one to three three characters in length and begin with a |
control character , |
control character , |
Line 492 subsequent sub-section, section, or end of file. The |
|
Line 631 subsequent sub-section, section, or end of file. The |
|
left-margin width is re-set to the default. |
left-margin width is re-set to the default. |
.Ss \&TH |
.Ss \&TH |
Sets the title of the manual page with the following syntax: |
Sets the title of the manual page with the following syntax: |
.Bd -literal -offset indent |
|
\&.TH title section [date [source [volume]]] |
|
.Ed |
|
. |
|
.Pp |
.Pp |
At least the |
.D1 \. Ns Sx \&TH No Cm title msec Op Cm date Op Cm src Op Cm vol |
.Va title |
.Pp |
and |
At least the upper-case document title |
.Va section |
.Cm title |
|
and numeric manual section |
|
.Cm msec |
arguments must be provided. The |
arguments must be provided. The |
.Va date |
.Cm date |
argument should be formatted as |
argument should be formatted as described in |
.Qq %b [%d] %Y |
.Sx Dates : |
format, described in |
if it does not conform, the current date is used instead. The |
.Xr strptime 3 . |
.Cm src |
The |
|
.Va source |
|
string specifies the organisation providing the utility. The |
string specifies the organisation providing the utility. The |
.Va volume |
.Cm vol |
replaces the default rendered volume as dictated by the manual section. |
string replaces the default rendered volume, which is dictated by the |
|
manual section. |
|
.Pp |
|
Examples: |
|
.Bd -literal -offset indent |
|
\&.TH CVS 5 "1992-02-12" GNU |
|
.Ed |
|
. |
.Ss \&TP |
.Ss \&TP |
Begin a paragraph where the head, if exceeding the indentation width, is |
Begin a paragraph where the head, if exceeding the indentation width, is |
followed by a newline; if not, the body follows on the same line after a |
followed by a newline; if not, the body follows on the same line after a |