-The \efBfoo\efR utility does...
-\&.
-\&.\e\*q .SH RETURN VALUES
-\&.\e\*q .SH ENVIRONMENT
-\&.\e\*q .SH FILES
-\&.\e\*q .SH EXAMPLES
-\&.\e\*q .SH DIAGNOSTICS
-\&.\e\*q .SH ERRORS
-\&.\e\*q .SH SEE ALSO
-\&.\e\*q \efBbar\efR(1)
-\&.\e\*q .SH STANDARDS
-\&.\e\*q .SH HISTORY
-\&.\e\*q .SH AUTHORS
-\&.\e\*q .SH CAVEATS
-\&.\e\*q .SH BUGS
-. Ed
-.
-.
-.Sh MACRO SYNTAX
-Macros are one to three three characters in length and begin with a
-control character ,
-. Sq \&. ,
-at the beginning of the line. An arbitrary amount of whitespace may
-sit between the control character and the macro name. Thus,
-. Sq \&.PP
-and
-. Sq \&.\ \ \ \&PP
-are equivalent.
-. Pp
-The
-. Nm
-macros are classified by scope: line scope or block scope. Line-scoped
-macros are only scoped to the current line (and, in some situations,
-the subsequent line). Block macros are scoped to the current line and
-subsequent lines until closed by another block macro.
-.
-.
-. Ss Line Macros
-Line-macros are scoped to the current line, with the body consisting of
-zero or more arguments. If a macro is next-line scoped and the line
-arguments are empty, the next line is used instead. Thus:
-. Bd -literal -offset indent
-\&.RI
-foo
-. Ed
-. Pp
-is equivalent to
-. Sq \&.RI foo .
-.\" PARAGRAPH
-Consecutive next-line invocations are disallowed.
-. Bd -literal -offset indent
-\&.YO \(lBbody...\(rB
-\(lBbody...\(rB
-. Ed
-. Pp
-. Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX"
-. It Em Macro Ta Em Arguments Ta Em Scope
-. It \&B Ta n Ta next-line
-. It \&BI Ta n Ta current
-. It \&BR Ta n Ta current
-. It \&I Ta n Ta next-line
-. It \&IB Ta n Ta current
-. It \&IR Ta n Ta current
-. It \&R Ta n Ta next-line
-. It \&RB Ta n Ta current
-. It \&RI Ta n Ta current
-. It \&SB Ta n Ta next-line
-. It \&SM Ta n Ta next-line
-. It \&TH Ta >1, <6 Ta current
-. It \&br Ta 0 Ta current
-. It \&fi Ta 0 Ta current
-. It \&i Ta n Ta current
-. It \&na Ta 0 Ta current
-. It \&nf Ta 0 Ta current
-. It \&r Ta 0 Ta current
-. It \&sp Ta 1 Ta current
-. El
-. Pp
-The lower-case
-. Sq \&br ,
-. Sq \&fi ,
-. Sq \&i ,
-. Sq \&na ,
-. Sq \&nf ,
-. Sq \&r ,
-and
-. Sq \&sp
-macros aren't historically part of
-. Nm
-and should not be used. They're included for compatibility.
-.
-.
-. Ss Block Macros
-Block macros are comprised of a head and body. The head is scoped to
-the current line and, in one circumstance, the next line; the body is
-scoped to subsequent lines and is closed out by a subsequent block macro
-invocation.
-. Bd -literal -offset indent
-\&.YO \(lBhead...\(rB
-\(lBhead...\(rB
-\(lBbody...\(rB
-. Ed
-. Pp
-If a block macro is next-line scoped, it may only be followed by in-line
-macros (excluding
-. Sq br ,
-. Sq na ,
-. Sq sp ,
-. Sq nf ,
-. Sq fi ,
-and
-. Sq TH ) .
-. Pp
-. Bl -column "MacroX" "Arguments" "ScopeXXXX" -compact -offset indent
-. It Em Macro Ta Em Arguments Ta Em Scope
-. It \&HP Ta <2 Ta current
-. It \&IP Ta <3 Ta current
-. It \&LP Ta 0 Ta current
-. It \&P Ta 0 Ta current
-. It \&PP Ta 0 Ta current
-. It \&SH Ta >0 Ta current
-. It \&SS Ta >0 Ta current
-. It \&TP Ta n Ta next-line
-. El
-.
-.
-.Sh REFERENCE
+The \efBfoo\efR utility processes files ...
+\&.\e\(dq .Sh CONTEXT
+\&.\e\(dq For section 9 functions only.
+\&.\e\(dq .SH IMPLEMENTATION NOTES
+\&.\e\(dq Not used in OpenBSD.
+\&.\e\(dq .SH RETURN VALUES
+\&.\e\(dq For sections 2, 3, and 9 function return values only.
+\&.\e\(dq .SH ENVIRONMENT
+\&.\e\(dq For sections 1, 6, 7, and 8 only.
+\&.\e\(dq .SH FILES
+\&.\e\(dq .SH EXIT STATUS
+\&.\e\(dq For sections 1, 6, and 8 only.
+\&.\e\(dq .SH EXAMPLES
+\&.\e\(dq .SH DIAGNOSTICS
+\&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
+\&.\e\(dq .SH ERRORS
+\&.\e\(dq For sections 2, 3, 4, and 9 errno settings only.
+\&.\e\(dq .SH SEE ALSO
+\&.\e\(dq .BR foobar ( 1 )
+\&.\e\(dq .SH STANDARDS
+\&.\e\(dq .SH HISTORY
+\&.\e\(dq .SH AUTHORS
+\&.\e\(dq .SH CAVEATS
+\&.\e\(dq .SH BUGS
+\&.\e\(dq .SH SECURITY CONSIDERATIONS
+\&.\e\(dq Not used in OpenBSD.
+.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 \&.B char *name(char *\efIarg\efR);
+.Pp
+And for the third, configurations (section 4):
+.Pp
+.D1 \&.B 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 CONTEXT
+This section lists the contexts in which functions can be called in section 9.
+The contexts are autoconf, process, or interrupt.
+.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 RETURN VALUES
+This section 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 name and a short description of how
+the file is used (created, modified, etc.).
+.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.
+.It Em EXAMPLES
+Example usages.
+This often contains snippets of well-formed,
+well-tested invocations.
+Make sure that examples work properly!
+.It Em DIAGNOSTICS
+Documents error conditions.
+In section 4 and 9 manuals, these are usually messages
+printed by the kernel to the console and to the kernel log.
+In section 1, 6, 7, and 8, these are usually messages
+printed by userland programs to the standard error output.
+.Pp
+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
+.Xr errno 2
+settings in sections 2, 3, 4, and 9.
+.It Em SEE ALSO
+References other manuals with related topics.
+This section should exist for most manuals.
+.Pp
+.D1 \&.BR bar \&( 1 \&),
+.Pp
+Cross-references should conventionally be ordered
+first by section, then alphabetically.
+.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
+A brief history of the subject, including where support first appeared.
+.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.
+.It Em CAVEATS
+Common misuses and misunderstandings should be explained
+in this section.
+.It Em BUGS
+Known bugs, limitations, and work-arounds should be described
+in this section.
+.It Em SECURITY CONSIDERATIONS
+Documents any security precautions that operators should consider.
+.El
+.Sh MACRO OVERVIEW
+This overview is sorted such that macros of similar purpose are listed
+together, to help find the best macro for any given purpose.
+Deprecated macros are not included in the overview, but can be found
+in the alphabetical reference below.
+.Ss Page header and footer meta-data
+.Bl -column "PP, LP, P" description
+.It Sx TH Ta set the title: Ar title section date Op Ar source Op Ar volume
+.It Sx AT Ta display AT&T UNIX version in the page footer (<= 1 argument)
+.It Sx UC Ta display BSD version in the page footer (<= 1 argument)
+.El
+.Ss Sections and paragraphs
+.Bl -column "PP, LP, P" description
+.It Sx SH Ta section header (one line)
+.It Sx SS Ta subsection header (one line)
+.It Sx PP , LP , P Ta start an undecorated paragraph (no arguments)
+.It Sx RS , RE Ta reset the left margin: Op Ar width
+.It Sx IP Ta indented paragraph: Op Ar head Op Ar width
+.It Sx TP Ta tagged paragraph: Op Ar width
+.It Sx HP Ta hanged paragraph: Op Ar width
+.It Sx PD Ta set vertical paragraph distance: Op Ar height
+.It Sx \&br Ta force output line break in text mode (no arguments)
+.It Sx \&sp Ta force vertical space: Op Ar height
+.It Sx fi , nf Ta fill mode and no-fill mode (no arguments)
+.It Sx in Ta additional indent: Op Ar width
+.El
+.Ss Physical markup
+.Bl -column "PP, LP, P" description
+.It Sx B Ta boldface font
+.It Sx I Ta italic font
+.It Sx R Ta roman (default) font
+.It Sx SB Ta small boldface font
+.It Sx SM Ta small roman font
+.It Sx BI Ta alternate between boldface and italic fonts
+.It Sx BR Ta alternate between boldface and roman fonts
+.It Sx IB Ta alternate between italic and boldface fonts
+.It Sx IR Ta alternate between italic and roman fonts
+.It Sx RB Ta alternate between roman and boldface fonts
+.It Sx RI Ta alternate between roman and italic fonts
+.El
+.Sh MACRO REFERENCE
git.ckatri.com / mandoc.git / blobdiff