version 1.140, 2010/07/19 21:59:48 |
version 1.143, 2010/08/06 17:07:11 |
Line 93 Within a macro line, the following characters are rese |
|
Line 93 Within a macro line, the following characters are rese |
|
.Pp |
.Pp |
Use of reserved characters is described in |
Use of reserved characters is described in |
.Sx MACRO SYNTAX . |
.Sx MACRO SYNTAX . |
For general use in macro lines, these characters must either be escaped |
For general use in macro lines, these characters can either be escaped |
with a non-breaking space |
with a non-breaking space |
.Pq Sq \e& |
.Pq Sq \e& |
or, if applicable, an appropriate escape sequence used. |
or, if applicable, an appropriate escape sequence can be used. |
.Ss Special Characters |
.Ss Special Characters |
Special characters may occur in both macro and free-form lines. |
Special characters may occur in both macro and free-form lines. |
Sequences begin with the escape character |
Sequences begin with the escape character |
Line 180 within literal contexts. |
|
Line 180 within literal contexts. |
|
In macro lines, whitespace delimits arguments and is discarded. |
In macro lines, whitespace delimits arguments and is discarded. |
If arguments are quoted, whitespace within the quotes is retained. |
If arguments are quoted, whitespace within the quotes is retained. |
.Ss Quotation |
.Ss Quotation |
Macro arguments may be quoted with a double-quote to group |
Macro arguments may be quoted with double-quotes to group |
space-delimited terms or to retain blocks of whitespace. |
space-delimited terms or to retain blocks of whitespace. |
A quoted argument begins with a double-quote preceded by whitespace. |
A quoted argument begins with a double-quote preceded by whitespace. |
The next double-quote not pair-wise adjacent to another double-quote |
The next double-quote not pair-wise adjacent to another double-quote |
terminates the literal, regardless of surrounding whitespace. |
terminates the literal, regardless of surrounding whitespace. |
.Pp |
.Pp |
This produces tokens |
Note that any quoted text, even if it would cause a macro invocation |
.Sq a" , |
when unquoted, is considered literal text. |
.Sq b c , |
|
.Sq de , |
|
and |
|
.Sq fg" . |
|
Note that any quoted term, be it argument or macro, is indiscriminately |
|
considered literal text. |
|
Thus, the following produces |
Thus, the following produces |
.Sq \&Em a : |
.Sq Op "Fl a" : |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.Em "Em a" |
\&.Op "Fl a" |
.Ed |
.Ed |
.Pp |
.Pp |
In free-form mode, quotes are regarded as opaque text. |
In free-form mode, quotes are regarded as opaque text. |
|
|
document consists of a document prologue followed by one or more |
document consists of a document prologue followed by one or more |
sections. |
sections. |
.Pp |
.Pp |
The prologue, which consists of (in order) the |
The prologue, which consists of the |
.Sx \&Dd , |
.Sx \&Dd , |
.Sx \&Dt , |
.Sx \&Dt , |
and |
and |
.Sx \&Os |
.Sx \&Os |
macros, is required for every document. |
macros in that order, is required for every document. |
.Pp |
.Pp |
The first section (sections are denoted by |
The first section (sections are denoted by |
.Sx \&Sh ) |
.Sx \&Sh ) |
Line 373 document are conventionally ordered as they appear abo |
|
Line 367 document are conventionally ordered as they appear abo |
|
Sections should be composed as follows: |
Sections should be composed as follows: |
.Bl -ohang -offset Ds |
.Bl -ohang -offset Ds |
.It Em NAME |
.It Em NAME |
The name(s) and a short description of the documented material. |
The name(s) and a one-line description of the documented material. |
The syntax for this as follows: |
The syntax for this as follows: |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.Nm name0 |
\&.Nm name0 |
\&.Nm name1 |
\&.Nm name1 |
\&.Nm name2 |
\&.Nm name2 |
\&.Nd a short description |
\&.Nd a one-line description |
.Ed |
.Ed |
.Pp |
.Pp |
The |
The |
Line 472 with the text immediately following the |
|
Line 466 with the text immediately following the |
|
.Sx \&Nm |
.Sx \&Nm |
macro, up to the next |
macro, up to the next |
.Sx \&Nm , |
.Sx \&Nm , |
.Sx \&Sx , |
.Sx \&Sh , |
or |
or |
.Sx \&Ss |
.Sx \&Ss |
macro or the end of an enclosing block, whichever comes first. |
macro or the end of an enclosing block, whichever comes first. |
Line 503 It documents the return values of functions in section |
|
Line 497 It documents the return values of functions in section |
|
See |
See |
.Sx \&Rv . |
.Sx \&Rv . |
.It Em ENVIRONMENT |
.It Em ENVIRONMENT |
Documents any usages of environment variables, e.g., |
Lists the environment variables used by the utility, |
.Xr environ 7 . |
and explains the syntax and semantics of their values. |
|
The |
|
.Xr environ 7 |
|
manual provides examples of typical content and formatting. |
.Pp |
.Pp |
See |
See |
.Sx \&Ev . |
.Sx \&Ev . |
.It Em FILES |
.It Em FILES |
Documents files used. |
Documents files used. |
It's helpful to document both the file and a short description of how |
It's helpful to document both the file name and a short description of how |
the file is used (created, modified, etc.). |
the file is used (created, modified, etc.). |
.Pp |
.Pp |
See |
See |
Line 563 section should be used instead. |
|
Line 560 section should be used instead. |
|
See |
See |
.Sx \&St . |
.Sx \&St . |
.It Em HISTORY |
.It Em HISTORY |
The history of any manual without a |
A brief history of the subject, including where support first appeared. |
.Em STANDARDS |
|
section should be described in this section. |
|
.It Em AUTHORS |
.It Em AUTHORS |
Credits to authors, if applicable, should appear in this section. |
Credits to the person or persons who wrote the code and/or documentation. |
Authors should generally be noted by both name and an e-mail address. |
Authors should generally be noted by both name and email address. |
.Pp |
.Pp |
See |
See |
.Sx \&An . |
.Sx \&An . |
.It Em CAVEATS |
.It Em CAVEATS |
Explanations of common misuses and misunderstandings should be explained |
Common misuses and misunderstandings should be explained |
in this section. |
in this section. |
.It Em BUGS |
.It Em BUGS |
Extant bugs should be described in this section. |
Known bugs, limitations and work-arounds should be described |
|
in this section. |
.It Em SECURITY CONSIDERATIONS |
.It Em SECURITY CONSIDERATIONS |
Documents any security precautions that operators should consider. |
Documents any security precautions that operators should consider. |
.El |
.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, |
.Sq \&. , |
.Sq \&. , |
at the beginning of the line. |
at the beginning of the line. |
An arbitrary amount of whitespace may sit between the control character |
An arbitrary amount of whitespace may sit between the control character |
|
|
.Sq Fl \&Sh . |
.Sq Fl \&Sh . |
.Pp |
.Pp |
The |
The |
.Em Parsable |
.Em Parsed |
column indicates whether the macro may be followed by further |
column indicates whether the macro may be followed by further |
(ostensibly callable) macros. |
(ostensibly callable) macros. |
If a macro is not parsable, subsequent macro invocations on the line |
If a macro is not parsed, subsequent macro invocations on the line |
will be interpreted as opaque text. |
will be interpreted as opaque text. |
.Pp |
.Pp |
The |
The |
Line 635 contains a head. |
|
Line 631 contains a head. |
|
\&.Yc |
\&.Yc |
.Ed |
.Ed |
.Pp |
.Pp |
.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX" |
.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXX" |
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope |
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope |
.It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed |
.It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed |
.It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef |
.It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef |
.It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek |
.It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek |
Line 658 All macros have bodies; some |
|
Line 654 All macros have bodies; some |
|
.Pc |
.Pc |
don't have heads; only one |
don't have heads; only one |
.Po |
.Po |
.Sx \&It Fl column |
.Sx \&It |
|
in |
|
.Sx \&Bl Fl column |
.Pc |
.Pc |
has multiple heads. |
has multiple heads. |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
Line 666 has multiple heads. |
|
Line 664 has multiple heads. |
|
\(lBbody...\(rB |
\(lBbody...\(rB |
.Ed |
.Ed |
.Pp |
.Pp |
.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX" |
.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" |
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope |
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope |
.It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El |
.It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El |
.It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh |
.It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh |
.It Sx \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss |
.It Sx \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss |
|
|
\(lBbody...\(rB \&Yc \(lBtail...\(rB |
\(lBbody...\(rB \&Yc \(lBtail...\(rB |
.Ed |
.Ed |
.Pp |
.Pp |
.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent |
.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -compact -offset indent |
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope |
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope |
.It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao |
.It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao |
.It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac |
.It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac |
.It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo |
.It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo |
|
|
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB |
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB |
.Ed |
.Ed |
.Pp |
.Pp |
.Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent |
.Bl -column "MacroX" "CallableX" "ParsedX" -compact -offset indent |
.It Em Macro Ta Em Callable Ta Em Parsable |
.It Em Macro Ta Em Callable Ta Em Parsed |
.It Sx \&Aq Ta Yes Ta Yes |
.It Sx \&Aq Ta Yes Ta Yes |
.It Sx \&Bq Ta Yes Ta Yes |
.It Sx \&Bq Ta Yes Ta Yes |
.It Sx \&Brq Ta Yes Ta Yes |
.It Sx \&Brq Ta Yes Ta Yes |
Line 778 then the macro accepts an arbitrary number of argument |
|
Line 776 then the macro accepts an arbitrary number of argument |
|
\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN |
\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN |
.Ed |
.Ed |
.Pp |
.Pp |
.Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent |
.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -compact -offset indent |
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments |
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments |
.It Sx \&%A Ta \&No Ta \&No Ta >0 |
.It Sx \&%A Ta \&No Ta \&No Ta >0 |
.It Sx \&%B Ta \&No Ta \&No Ta >0 |
.It Sx \&%B Ta \&No Ta \&No Ta >0 |
.It Sx \&%C Ta \&No Ta \&No Ta >0 |
.It Sx \&%C Ta \&No Ta \&No Ta >0 |
Line 805 then the macro accepts an arbitrary number of argument |
|
Line 803 then the macro accepts an arbitrary number of argument |
|
.It Sx \&Cd Ta Yes Ta Yes Ta >0 |
.It Sx \&Cd Ta Yes Ta Yes Ta >0 |
.It Sx \&Cm Ta Yes Ta Yes Ta n |
.It Sx \&Cm Ta Yes Ta Yes Ta n |
.It Sx \&Db Ta \&No Ta \&No Ta 1 |
.It Sx \&Db Ta \&No Ta \&No Ta 1 |
.It Sx \&Dd Ta \&No Ta \&No Ta >0 |
.It Sx \&Dd Ta \&No Ta \&No Ta n |
.It Sx \&Dt Ta \&No Ta \&No Ta n |
.It Sx \&Dt Ta \&No Ta \&No Ta n |
.It Sx \&Dv Ta Yes Ta Yes Ta n |
.It Sx \&Dv Ta Yes Ta Yes Ta n |
.It Sx \&Dx Ta Yes Ta Yes Ta n |
.It Sx \&Dx Ta Yes Ta Yes Ta n |
Line 933 Volume number of an |
|
Line 931 Volume number of an |
|
.Sx \&Rs |
.Sx \&Rs |
block. |
block. |
.Ss \&Ac |
.Ss \&Ac |
Closes an |
Close an |
.Sx \&Ao |
.Sx \&Ao |
block. |
block. |
Does not have any tail arguments. |
Does not have any tail arguments. |
.Ss \&Ad |
.Ss \&Ad |
Address construct: usually in the context of an computational address in |
Memory address. |
memory, not a physical (post) address. |
Do not use this for postal addresses. |
.Pp |
.Pp |
Examples: |
Examples: |
.D1 \&.Ad [0,$] |
.D1 \&.Ad [0,$] |
.D1 \&.Ad 0x00000000 |
.D1 \&.Ad 0x00000000 |
.Ss \&An |
.Ss \&An |
Author name. |
Author name. |
This macro may alternatively accepts the following arguments, although |
Requires either the name of an author or one of the following arguments: |
these may not be specified along with a parameter: |
|
.Pp |
.Pp |
.Bl -tag -width "-nosplitX" -offset indent -compact |
.Bl -tag -width "-nosplitX" -offset indent -compact |
.It Fl split |
.It Fl split |
Renders a line break before each author listing. |
Start a new output line before each subsequent invocation of |
|
.Sx \&An . |
.It Fl nosplit |
.It Fl nosplit |
The opposite of |
The opposite of |
.Fl split . |
.Fl split . |
.El |
.El |
.Pp |
.Pp |
|
The default is |
|
.Fl nosplit . |
|
The effect of selecting either of the |
|
.Fl split |
|
modes ends at the beginning of the |
|
.Em AUTHORS |
|
section. |
In the |
In the |
.Em AUTHORS |
.Em AUTHORS |
section, the default is not to split the first author |
section, the default is |
listing, but all subsequent author listings, whether or not they're |
.Fl nosplit |
interspersed by other macros or text, are split. |
for the first author listing and |
Thus, specifying |
|
.Fl split |
.Fl split |
will cause the first listing also to be split. |
for all other author listings. |
If not in the |
|
.Em AUTHORS |
|
section, the default is not to split. |
|
.Pp |
.Pp |
Examples: |
Examples: |
.D1 \&.An -nosplit |
.D1 \&.An -nosplit |
.D1 \&.An J. D. Ullman . |
.D1 \&.An Kristaps Dzonsons \&Aq kristaps@bsd.lv |
.Pp |
|
.Em Remarks : |
|
the effects of |
|
.Fl split |
|
or |
|
.Fl nosplit |
|
are re-set when entering the |
|
.Em AUTHORS |
|
section, so if one specifies |
|
.Sx \&An Fl nosplit |
|
in the general document body, it must be re-specified in the |
|
.Em AUTHORS |
|
section. |
|
.Ss \&Ao |
.Ss \&Ao |
Begins a block enclosed by angled brackets. |
Begin a block enclosed by angle brackets. |
Does not have any head arguments. |
Does not have any head arguments. |
.Pp |
.Pp |
Examples: |
Examples: |
Line 1002 form of a function. |
|
Line 990 form of a function. |
|
Examples: |
Examples: |
.D1 \&.Fn execve \&Ap d |
.D1 \&.Fn execve \&Ap d |
.Ss \&Aq |
.Ss \&Aq |
Encloses its arguments in angled brackets. |
Encloses its arguments in angle brackets. |
.Pp |
.Pp |
Examples: |
Examples: |
.D1 \&.Fl -key= \&Ns \&Aq \&Ar val |
.D1 \&.Fl -key= \&Ns \&Aq \&Ar val |
|
|
.Ss \&Ar |
.Ss \&Ar |
Command arguments. |
Command arguments. |
If an argument is not provided, the string |
If an argument is not provided, the string |
.Dq file ... |
.Dq file ...\& |
is used as a default. |
is used as a default. |
.Pp |
.Pp |
Examples: |
Examples: |
|
|
.D1 \&.Ar arg1 , arg2 . |
.D1 \&.Ar arg1 , arg2 . |
.Ss \&At |
.Ss \&At |
Formats an AT&T version. |
Formats an AT&T version. |
Accepts at most one parameter: |
Accepts one optional argument: |
.Pp |
.Pp |
.Bl -tag -width "v[1-7] | 32vX" -offset indent -compact |
.Bl -tag -width "v[1-7] | 32vX" -offset indent -compact |
.It Cm v[1-7] | 32v |
.It Cm v[1-7] | 32v |
A version of |
A version of |
.At . |
.At . |
.It Cm V[.[1-4]]? |
.It Cm V[.[1-4]]? |
A system version of |
A version of |
.At . |
.At V . |
.El |
.El |
.Pp |
.Pp |
Note that these parameters do not begin with a hyphen. |
Note that these arguments do not begin with a hyphen. |
.Pp |
.Pp |
Examples: |
Examples: |
.D1 \&.At |
.D1 \&.At |
|
|
and |
and |
.Sx \&Ux . |
.Sx \&Ux . |
.Ss \&Bc |
.Ss \&Bc |
Closes a |
Close a |
.Sx \&Bo |
.Sx \&Bo |
block. |
block. |
Does not have any tail arguments. |
Does not have any tail arguments. |
.Ss \&Bd |
.Ss \&Bd |
Begins a display block. |
Begin a display block. |
Its syntax is as follows: |
Its syntax is as follows: |
.Bd -ragged -offset indent |
.Bd -ragged -offset indent |
.Pf \. Sx \&Bd |
.Pf \. Sx \&Bd |
.Fl type |
.Fl Ns Ar type |
.Op Fl offset Ar width |
.Op Fl offset Ar width |
.Op Fl compact |
.Op Fl compact |
.Ed |
.Ed |
.Pp |
.Pp |
A display is collection of macros or text which may be collectively |
Display blocks are used to select a different indentation and |
offset or justified in a manner different from that |
justification than the one used by the surrounding text. |
of the enclosing context. |
They may contain both macro lines and free-form text lines. |
By default, the block is preceded by a vertical space. |
By default, a display block is preceded by a vertical space. |
.Pp |
.Pp |
Each display is associated with a type, which must be one of the |
The |
following arguments: |
.Ar type |
.Bl -tag -width 12n -offset indent |
must be one of the following: |
.It Fl ragged |
.Bl -tag -width 13n -offset indent |
Only left-justify the block. |
.It Fl centered |
.It Fl unfilled |
Centre-justify each line. |
Do not justify the block at all. |
Using this display type is not recommended; many |
|
.Nm |
|
implementations render it poorly. |
.It Fl filled |
.It Fl filled |
Left- and right-justify the block. |
Left- and right-justify the block. |
.It Fl literal |
.It Fl literal |
Alias for |
Do not justify the block at all. |
.Fl unfilled . |
Preserve white space as it appears in the input. |
.It Fl centered |
.It Fl ragged |
Centre-justify each line. |
Only left-justify the block. |
|
.It Fl unfilled |
|
An alias for |
|
.Fl literal . |
.El |
.El |
.Pp |
.Pp |
The type must be provided first. |
The |
Secondary arguments are as follows: |
.Ar type |
.Bl -tag -width 12n -offset indent |
must be provided first. |
.It Fl offset Ar val |
Additional arguments may follow: |
Offset by the value of |
.Bl -tag -width 13n -offset indent |
.Ar val , |
.It Fl offset Ar width |
which is interpreted as one of the following, specified in order: |
Indent the display by the |
|
.Ar width , |
|
which may be one of the following: |
.Bl -item |
.Bl -item |
.It |
.It |
As one of the pre-defined strings |
One of the pre-defined strings |
.Ar indent , |
.Cm indent , |
the width of standard indentation; |
the width of standard indentation; |
.Ar indent-two , |
.Cm indent-two , |
twice |
twice |
.Ar indent ; |
.Cm indent ; |
.Ar left , |
.Cm left , |
which has no effect; |
which has no effect; |
.Ar right , |
.Cm right , |
which justifies to the right margin; and |
which justifies to the right margin; or |
.Ar center , |
.Cm center , |
which aligns around an imagined centre axis. |
which aligns around an imagined centre axis. |
.It |
.It |
As a precalculated width for a named macro. |
A macro invocation, which selects a predefined width |
|
associated with that macro. |
The most popular is the imaginary macro |
The most popular is the imaginary macro |
.Ar \&Ds , |
.Ar \&Ds , |
which resolves to |
which resolves to |
.Ar 6n . |
.Sy 6n . |
.It |
.It |
As a scaling unit following the syntax described in |
A width using the syntax described in |
.Sx Scaling Widths . |
.Sx Scaling Widths . |
.It |
.It |
As the calculated string length of the opaque string. |
An arbitrary string, which indents by the length of this string. |
.El |
.El |
.Pp |
.Pp |
If not provided an argument, it will be ignored. |
When the argument is missing, |
|
.Fl offset |
|
is ignored. |
.It Fl compact |
.It Fl compact |
Do not assert a vertical space before the block. |
Do not assert vertical space before the display. |
.El |
.El |
.Pp |
.Pp |
Examples: |
Examples: |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.Bd \-unfilled \-offset two-indent \-compact |
\&.Bd \-literal \-offset indent \-compact |
Hello world. |
Hello world. |
\&.Ed |
\&.Ed |
.Ed |
.Ed |
Line 1175 is encountered. |
|
Line 1173 is encountered. |
|
See also |
See also |
.Sx \&Li , |
.Sx \&Li , |
.Sx \&Ef , |
.Sx \&Ef , |
|
.Sx \&Em , |
and |
and |
.Sx \&Sy . |
.Sx \&Sy . |
.Ss \&Bk |
.Ss \&Bk |
Begins a collection of macros or text not breaking the line. |
Keep the output generated from each macro input line together |
Its syntax is as follows: |
on one single output line. |
|
Line breaks in free-form text lines are unaffected. |
|
The syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&Bk Fl words |
.D1 Pf \. Sx \&Bk Fl words |
.Pp |
.Pp |
Subsequent arguments are ignored. |
|
The |
The |
.Fl words |
.Fl words |
argument is required. |
argument is required; additional arguments are ignored. |
.Pp |
.Pp |
Each line within a keep block is kept intact, so the following example |
The following example will not break within each |
will not break within each |
|
.Sx \&Op |
.Sx \&Op |
macro line: |
macro line: |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
|
|
Be careful in using over-long lines within a keep block! |
Be careful in using over-long lines within a keep block! |
Doing so will clobber the right margin. |
Doing so will clobber the right margin. |
.Ss \&Bl |
.Ss \&Bl |
Begins a list composed of one or more list entries. |
Begin a list. |
Its syntax is as follows: |
Lists consist of items started by the |
|
.Sx \&It |
|
macro, containing a head or a body or both. |
|
The list syntax is as follows: |
.Bd -ragged -offset indent |
.Bd -ragged -offset indent |
.Pf \. Sx \&Bl |
.Pf \. Sx \&Bl |
.Fl type |
.Fl Ns Ar type |
.Op Fl width Ar val |
.Op Fl width Ar val |
.Op Fl offset Ar val |
.Op Fl offset Ar val |
.Op Fl compact |
.Op Fl compact |
.Op HEAD ... |
.Op HEAD ... |
.Ed |
.Ed |
.Pp |
.Pp |
A list is associated with a type, which is a required argument. |
The list |
Other arguments are |
.Ar type |
.Fl width , |
is mandatory and must be specified first. |
defined per-type as accepting a literal or |
The |
|
.Fl width |
|
and |
|
.Fl offset |
|
arguments accept |
.Sx Scaling Widths |
.Sx Scaling Widths |
value; |
or use the length of the given string. |
.Fl offset , |
The |
also accepting a literal or |
.Fl offset |
.Sx Scaling Widths |
is a global indentation for the whole list, affecting both item heads |
value setting the list's global offset; and |
and bodies. |
.Fl compact , |
For those list types supporting it, the |
suppressing the default vertical space printed before each list entry. |
.Fl width |
A list entry is specified by the |
argument requests an additional indentation of item bodies, |
.Sx \&It |
to be added to the |
macro, which consists of a head and optional body (depending on the list |
.Fl offset . |
type). |
Unless the |
|
.Fl compact |
|
argument is specified, list entries are separated by vertical space. |
|
.Pp |
A list must specify one of the following list types: |
A list must specify one of the following list types: |
.Bl -tag -width 12n -offset indent |
.Bl -tag -width 12n -offset indent |
.It Fl bullet |
.It Fl bullet |
A list offset by a bullet. |
No item heads can be specified, but a bullet will be printed at the head |
The head of list entries must be empty. |
of each item. |
List entry bodies are positioned after the bullet. |
Item bodies start on the same output line as the bullet |
The |
and are indented according to the |
.Fl width |
.Fl width |
argument varies the width of list bodies' left-margins. |
argument. |
.It Fl column |
.It Fl column |
A columnated list. |
A columnated list. |
The |
The |
.Fl width |
.Fl width |
argument has no effect. |
argument has no effect; instead, each argument specifies the width |
The number of columns is specified as parameters to the |
of one column, using either the |
.Sx \&Bl |
|
macro. |
|
These dictate the width of columns either as |
|
.Sx Scaling Widths |
.Sx Scaling Widths |
or literal text. |
syntax or the string length of the argument. |
If the initial macro of a |
If the first line of the body of a |
.Fl column |
.Fl column |
list is not an |
list is not an |
.Sx \&It , |
|
an |
|
.Sx \&It |
.Sx \&It |
context spanning each line is implied until an |
macro line, |
.Sx \&It |
.Sx \&It |
line macro is encountered, at which point list bodies are interpreted as |
contexts spanning one input line each are implied until an |
|
.Sx \&It |
|
macro line is encountered, at which point items start being interpreted as |
described in the |
described in the |
.Sx \&It |
.Sx \&It |
documentation. |
documentation. |
.It Fl dash |
.It Fl dash |
A list offset by a dash (hyphen). |
Like |
The head of list entries must be empty. |
.Fl bullet , |
List entry bodies are positioned past the dash. |
except that dashes are used in place of bullets. |
The |
|
.Fl width |
|
argument varies the width of list bodies' left-margins. |
|
.It Fl diag |
.It Fl diag |
Like |
Like |
.Fl inset , |
.Fl inset , |
but with additional formatting to the head. |
except that item heads are not parsed for macro invocations. |
The |
.\" but with additional formatting to the head. |
.Fl width |
|
argument varies the width of list bodies' left-margins. |
|
.It Fl enum |
.It Fl enum |
An enumerated list offset by the enumeration from 1. |
A numbered list. |
The head of list entries must be empty. |
Formatted like |
List entry bodies are positioned after the enumeration. |
.Fl bullet , |
The |
except that cardinal numbers are used in place of bullets, |
.Fl width |
starting at 1. |
argument varies the width of list bodies' left-margins. |
|
.It Fl hang |
.It Fl hang |
Like |
Like |
.Fl tag , |
.Fl tag , |
but instead of list bodies positioned after the head, they trail the |
except that the first lines of item bodies are not indented, but follow |
head text. |
the item heads like in |
The |
.Fl inset |
.Fl width |
lists. |
argument varies the width of list bodies' left-margins. |
|
.It Fl hyphen |
.It Fl hyphen |
Synonym for |
Synonym for |
.Fl dash . |
.Fl dash . |
.It Fl inset |
.It Fl inset |
List bodies follow the list head. |
Item bodies follow items heads on the same line, using normal inter-word |
The |
spacing. |
|
Bodies are not indented, and the |
.Fl width |
.Fl width |
argument is ignored. |
argument is ignored. |
.It Fl item |
.It Fl item |
This produces blocks of text. |
No item heads can be specified, and none are printed. |
The head of list entries must be empty. |
Bodies are not indented, and the |
The |
|
.Fl width |
.Fl width |
argument is ignored. |
argument is ignored. |
.It Fl ohang |
.It Fl ohang |
List bodies are positioned on the line following the head. |
Item bodies start on the line following item heads and are not indented. |
The |
The |
.Fl width |
.Fl width |
argument is ignored. |
argument is ignored. |
.It Fl tag |
.It Fl tag |
A list offset by list entry heads. |
Item bodies are indented according to the |
List entry bodies are positioned after the head as specified by the |
|
.Fl width |
.Fl width |
argument. |
argument. |
|
When an item head fits inside the indentation, the item body follows |
|
this head on the same output line. |
|
Otherwise, the body starts on the output line following the head. |
.El |
.El |
.Pp |
.Pp |
See also |
See also |
|
.Sx \&El |
|
and |
.Sx \&It . |
.Sx \&It . |
.Ss \&Bo |
.Ss \&Bo |
Begins a block enclosed by square brackets. |
Begin a block enclosed by square brackets. |
Does not have any head arguments. |
Does not have any head arguments. |
.Pp |
.Pp |
Examples: |
Examples: |
|
|
See also |
See also |
.Sx \&Bo . |
.Sx \&Bo . |
.Ss \&Brc |
.Ss \&Brc |
Closes a |
Close a |
.Sx \&Bro |
.Sx \&Bro |
block. |
block. |
Does not have any tail arguments. |
Does not have any tail arguments. |
.Ss \&Bro |
.Ss \&Bro |
Begins a block enclosed by curly braces. |
Begin a block enclosed by curly braces. |
Does not have any head arguments. |
Does not have any head arguments. |
.Pp |
.Pp |
Examples: |
Examples: |
|
|
and |
and |
.Sx \&Ux . |
.Sx \&Ux . |
.Ss \&Cd |
.Ss \&Cd |
Configuration declaration. |
Kernel configuration declaration. |
This denotes strings accepted by |
This denotes strings accepted by |
.Xr config 8 . |
.Xr config 8 . |
.Pp |
.Pp |
|
|
and |
and |
.Sx \&Dl . |
.Sx \&Dl . |
.Ss \&Db |
.Ss \&Db |
Start a debugging context. |
Switch debugging mode. |
This macro is parsed, but generally ignored. |
|
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&Db Cm on | off |
.D1 Pf \. Sx \&Db Cm on | off |
|
.Pp |
|
This macro is ignored by |
|
.Xr mandoc 1 . |
.Ss \&Dc |
.Ss \&Dc |
Closes a |
Close a |
.Sx \&Do |
.Sx \&Do |
block. |
block. |
Does not have any tail arguments. |
Does not have any tail arguments. |
Line 1463 This is the mandatory first macro of any |
|
Line 1468 This is the mandatory first macro of any |
|
manual. |
manual. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&Dd Cm date |
.D1 Pf \. Sx \&Dd Op Ar date |
.Pp |
.Pp |
The |
The |
.Cm date |
.Ar date |
field may be either |
may be either |
.Ar $\&Mdocdate$ , |
.Ar $\&Mdocdate$ , |
which signifies the current manual revision date dictated by |
which signifies the current manual revision date dictated by |
.Xr cvs 1 , |
.Xr cvs 1 , |
or instead a valid canonical date as specified by |
or instead a valid canonical date as specified by |
.Sx Dates . |
.Sx Dates . |
If a date does not conform, the current date is used instead. |
If a date does not conform or is empty, the current date is used. |
.Pp |
.Pp |
Examples: |
Examples: |
.D1 \&.Dd $\&Mdocdate$ |
.D1 \&.Dd $\&Mdocdate$ |
|
|
and |
and |
.Sx \&D1 . |
.Sx \&D1 . |
.Ss \&Do |
.Ss \&Do |
Begins a block enclosed by double quotes. |
Begin a block enclosed by double quotes. |
Does not have any head arguments. |
Does not have any head arguments. |
.Pp |
.Pp |
Examples: |
Examples: |
Line 1536 Its syntax is as follows: |
|
Line 1541 Its syntax is as follows: |
|
.Bd -ragged -offset indent |
.Bd -ragged -offset indent |
.Pf \. Sx \&Dt |
.Pf \. Sx \&Dt |
.Oo |
.Oo |
.Cm title |
.Ar title |
.Oo |
.Oo |
.Cm section |
.Ar section |
.Op Cm volume | arch |
.Op Ar volume | arch |
.Oc |
.Oc |
.Oc |
.Oc |
.Ed |
.Ed |
.Pp |
.Pp |
Its arguments are as follows: |
Its arguments are as follows: |
.Bl -tag -width Ds -offset Ds |
.Bl -tag -width Ds -offset Ds |
.It Cm title |
.It Ar title |
The document's title (name), defaulting to |
The document's title (name), defaulting to |
.Dq UNKNOWN |
.Dq UNKNOWN |
if unspecified. |
if unspecified. |
It should be capitalised. |
It should be capitalised. |
.It Cm section |
.It Ar section |
The manual section. |
The manual section. |
This may be one of |
This may be one of |
.Ar 1 |
.Ar 1 |
|
|
It should correspond to the manual's filename suffix and defaults to |
It should correspond to the manual's filename suffix and defaults to |
.Dq 1 |
.Dq 1 |
if unspecified. |
if unspecified. |
.It Cm volume |
.It Ar volume |
This overrides the volume inferred from |
This overrides the volume inferred from |
.Ar section . |
.Ar section . |
This field is optional, and if specified, must be one of |
This field is optional, and if specified, must be one of |
Line 1619 This field is optional, and if specified, must be one |
|
Line 1624 This field is optional, and if specified, must be one |
|
or |
or |
.Ar CON |
.Ar CON |
.Pq contributed manuals . |
.Pq contributed manuals . |
.It Cm arch |
.It Ar arch |
This specifies a specific relevant architecture. |
This specifies a specific relevant architecture. |
If |
If |
.Cm volume |
.Ar volume |
is not provided, it may be used in its place, else it may be used |
is not provided, it may be used in its place, else it may be used |
subsequent that. |
subsequent that. |
It, too, is optional. |
It, too, is optional. |
Line 1697 Close a scope started by |
|
Line 1702 Close a scope started by |
|
.Sx \&Eo . |
.Sx \&Eo . |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&Ec Op Cm TERM |
.D1 Pf \. Sx \&Ec Op Ar TERM |
.Pp |
.Pp |
The |
The |
.Cm TERM |
.Ar TERM |
argument is used as the enclosure tail, for example, specifying \e(rq |
argument is used as the enclosure tail, for example, specifying \e(rq |
will emulate |
will emulate |
.Sx \&Dc . |
.Sx \&Dc . |
|
|
End a display context started by |
End a display context started by |
.Sx \&Bd . |
.Sx \&Bd . |
.Ss \&Ef |
.Ss \&Ef |
Ends a font mode context started by |
End a font mode context started by |
.Sx \&Bf . |
.Sx \&Bf . |
.Ss \&Ek |
.Ss \&Ek |
Ends a keep context started by |
End a keep context started by |
.Sx \&Bk . |
.Sx \&Bk . |
.Ss \&El |
.Ss \&El |
Ends a list context started by |
End a list context started by |
.Sx \&Bl . |
.Sx \&Bl . |
.Pp |
.Pp |
See also |
See also |
|
|
and |
and |
.Sx \&Li . |
.Sx \&Li . |
.Ss \&En |
.Ss \&En |
This macro is obsolete and not implemented. |
This macro is obsolete and not implemented in |
|
.Xr mandoc 1 . |
.Ss \&Eo |
.Ss \&Eo |
An arbitrary enclosure. |
An arbitrary enclosure. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&Eo Op Cm TERM |
.D1 Pf \. Sx \&Eo Op Ar TERM |
.Pp |
.Pp |
The |
The |
.Cm TERM |
.Ar TERM |
argument is used as the enclosure head, for example, specifying \e(lq |
argument is used as the enclosure head, for example, specifying \e(lq |
will emulate |
will emulate |
.Sx \&Do . |
.Sx \&Do . |
|
|
.D1 \&.Ev DISPLAY |
.D1 \&.Ev DISPLAY |
.D1 \&.Ev PATH |
.D1 \&.Ev PATH |
.Ss \&Ex |
.Ss \&Ex |
Inserts text regarding a utility's exit value. |
Insert a standard sentence regarding exit values. |
This macro must consist of the |
Its syntax is as follows: |
.Fl std |
.Pp |
argument followed by an optional |
.D1 Pf \. Sx \&Ex Fl std Op Ar utility |
.Ar utility . |
.Pp |
If |
When |
.Ar utility |
.Ar utility |
is not provided, the document's name as stipulated in |
is not specified, the document's name set by |
.Sx \&Nm |
.Sx \&Nm |
is provided. |
is used. |
.Pp |
.Pp |
See also |
See also |
.Sx \&Rv . |
.Sx \&Rv . |
|
|
See also |
See also |
.Sx \&Fo . |
.Sx \&Fo . |
.Ss \&Fc |
.Ss \&Fc |
Ends a function context started by |
End a function context started by |
.Sx \&Fo . |
.Sx \&Fo . |
.Ss \&Fd |
.Ss \&Fd |
Historically used to document include files. |
Historically used to document include files. |
|
|
section (only if invoked as the line macro), the first argument is |
section (only if invoked as the line macro), the first argument is |
preceded by |
preceded by |
.Dq #include , |
.Dq #include , |
the arguments is enclosed in angled braces. |
the arguments is enclosed in angle brackets. |
.Pp |
.Pp |
Examples: |
Examples: |
.D1 \&.In sys/types |
.D1 \&.In sys/types |
|
|
and |
and |
.Sx \&Ux . |
.Sx \&Ux . |
.Ss \&Oc |
.Ss \&Oc |
Closes multi-line |
Close multi-line |
.Sx \&Oo |
.Sx \&Oo |
context. |
context. |
.Ss \&Oo |
.Ss \&Oo |
|
|
file. |
file. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&Os Op Cm system |
.D1 Pf \. Sx \&Os Op Cm system Op Cm version |
.Pp |
.Pp |
The optional |
The optional |
.Cm system |
.Cm system |
|
|
and |
and |
.Sx \&Qo . |
.Sx \&Qo . |
.Ss \&Re |
.Ss \&Re |
Closes a |
Close an |
.Sx \&Rs |
.Sx \&Rs |
block. |
block. |
Does not have any tail arguments. |
Does not have any tail arguments. |
.Ss \&Rs |
.Ss \&Rs |
Begins a bibliographic |
Begin a bibliographic |
.Pq Dq reference |
.Pq Dq reference |
block. |
block. |
Does not have any head arguments. |
Does not have any head arguments. |
Line 2709 Heirloom troff, the other significant troff implementa |
|
Line 2715 Heirloom troff, the other significant troff implementa |
|
\-mdoc, is similar to historic groff. |
\-mdoc, is similar to historic groff. |
.Pp |
.Pp |
.Bl -dash -compact |
.Bl -dash -compact |
|
.It |
|
An empty |
|
.Sq \&Dd |
|
macro in groff prints |
|
.Dq Epoch . |
|
In mandoc, it resolves to the current date. |
.It |
.It |
The \es (font size), \em (font colour), and \eM (font filling colour) |
The \es (font size), \em (font colour), and \eM (font filling colour) |
font decoration escapes are all discarded in mandoc. |
font decoration escapes are all discarded in mandoc. |