version 1.194, 2011/08/01 07:45:11 |
version 1.197, 2011/08/10 14:07:23 |
Line 65 A macro line with only a control character and comment |
|
Line 65 A macro line with only a control character and comment |
|
is also ignored. |
is also ignored. |
Macro lines with only a control character and optional whitespace are |
Macro lines with only a control character and optional whitespace are |
stripped from input. |
stripped from input. |
.Ss Reserved Terms |
|
Within a macro line, the following terms are reserved: |
|
.Pp |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It \&. |
|
.Pq period |
|
.It \e. |
|
.Pq escaped period |
|
.It \&, |
|
.Pq comma |
|
.It \&: |
|
.Pq colon |
|
.It \&; |
|
.Pq semicolon |
|
.It \&( |
|
.Pq left-parenthesis |
|
.It \&) |
|
.Pq right-parenthesis |
|
.It \&[ |
|
.Pq left-bracket |
|
.It \&] |
|
.Pq right-bracket |
|
.It \&? |
|
.Pq question |
|
.It \&! |
|
.Pq exclamation |
|
.It \&| |
|
.Pq vertical bar |
|
.It \e*(Ba |
|
.Pq reserved-word vertical bar |
|
.El |
|
.Pp |
|
For general use in macro lines, these can be escaped with a non-breaking |
|
space |
|
.Pq Sq \e& . |
|
In text lines, these may be used as normal punctuation. |
|
.Ss Special Characters |
.Ss Special Characters |
Special characters may occur in both macro and text lines. |
Special characters may occur in both macro and text lines. |
Sequences begin with the escape character |
Sequences begin with the escape character |
|
|
produces |
produces |
.Sq Op Fl O Ar file . |
.Sq Op Fl O Ar file . |
To prevent a macro call and render the macro name literally, |
To prevent a macro call and render the macro name literally, |
escape it by prepending a non-breaking space, |
escape it by prepending a zero-width space, |
.Sq \e& . |
.Sq \e& . |
For example, |
For example, |
.Sq \&Op \e&Fl O |
.Sq \&Op \e&Fl O |
Line 700 has multiple heads. |
|
Line 664 has multiple heads. |
|
.Pp |
.Pp |
.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" |
.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" |
.It Em Macro Ta Em Callable Ta Em Parsed 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 |
.It Sx \&Sh Ta \&No Ta \&No Ta closed by Sx \&Sh |
.It Sx \&Sh Ta \&No Ta Yes Ta closed by Sx \&Sh |
.It Sx \&Ss Ta \&No Ta \&No Ta closed by Sx \&Sh , Sx \&Ss |
.It Sx \&Ss Ta \&No Ta Yes Ta closed by Sx \&Sh , Sx \&Ss |
.El |
.El |
.Pp |
.Pp |
Note that the |
Note that the |
|
|
.It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc |
.It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc |
.El |
.El |
.Ss Block partial-implicit |
.Ss Block partial-implicit |
Like block full-implicit, but with single-line scope closed by |
Like block full-implicit, but with single-line scope closed by the |
.Sx Reserved Terms |
end of the line. |
or end of line. |
|
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB |
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB |
.Ed |
.Ed |
Line 810 these blocks have bodies, but no heads. |
|
Line 773 these blocks have bodies, but no heads. |
|
.It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It |
.It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It |
.El |
.El |
.Ss In-line |
.Ss In-line |
Closed by |
Closed by the end of the line, fixed argument lengths, |
.Sx Reserved Terms , |
and/or subsequent macros. |
end of line, fixed argument lengths, and/or subsequent macros. |
|
In-line macros have only text children. |
In-line macros have only text children. |
If a number (or inequality) of arguments is |
If a number (or inequality) of arguments is |
.Pq n , |
.Pq n , |
Line 902 then the macro accepts an arbitrary number of argument |
|
Line 864 then the macro accepts an arbitrary number of argument |
|
.It Sx \&br Ta \&No Ta \&No Ta 0 |
.It Sx \&br Ta \&No Ta \&No Ta 0 |
.It Sx \&sp Ta \&No Ta \&No Ta 1 |
.It Sx \&sp Ta \&No Ta \&No Ta 1 |
.El |
.El |
|
.Ss Delimiters |
|
When a macro argument consists of one single input character |
|
considered as a delimiter, the argument gets special handling. |
|
This does not apply when delimiters appear in arguments containing |
|
more than one character. |
|
Consequently, to prevent special handling and just handle it |
|
like any other argument, a delimiter can be escaped by prepending |
|
a zero-width space |
|
.Pq Sq \e& . |
|
In text lines, delimiters never need escaping, but may be used |
|
as normal punctuation. |
|
.Pp |
|
For many macros, when the leading arguments are opening delimiters, |
|
these delimiters are put before the macro scope, |
|
and when the trailing arguments are closing delimiters, |
|
these delimiters are put after the macro scope. |
|
For example, |
|
.Pp |
|
.D1 Pf \. \&Aq "( [ word ] ) ." |
|
.Pp |
|
renders as: |
|
.Pp |
|
.D1 Aq ( [ word ] ) . |
|
.Pp |
|
Opening delimiters are: |
|
.Pp |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It \&( |
|
left parenthesis |
|
.It \&[ |
|
left bracket |
|
.El |
|
.Pp |
|
Closing delimiters are: |
|
.Pp |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It \&. |
|
period |
|
.It \&, |
|
comma |
|
.It \&: |
|
colon |
|
.It \&; |
|
semicolon |
|
.It \&) |
|
right parenthesis |
|
.It \&] |
|
right bracket |
|
.It \&? |
|
question mark |
|
.It \&! |
|
exclamation mark |
|
.El |
|
.Pp |
|
Note that even a period preceded by a backslash |
|
.Pq Sq \e.\& |
|
gets this special handling; use |
|
.Sq \e&. |
|
to prevent that. |
|
.Pp |
|
Many in-line macros interrupt their scope when they encounter |
|
delimiters, and resume their scope when more arguments follow that |
|
are not delimiters. |
|
For example, |
|
.Pp |
|
.D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e" |
|
.Pp |
|
renders as: |
|
.Pp |
|
.D1 Fl a ( b | c \*(Ba d ) e |
|
.Pp |
|
This applies to both opening and closing delimiters, |
|
and also to the middle delimiter: |
|
.Pp |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It \&| |
|
vertical bar |
|
.El |
|
.Pp |
|
As a special case, the predefined string \e*(Ba is handled and rendered |
|
in the same way as a plain |
|
.Sq \&| |
|
character. |
|
Using this predefined string is not recommended in new manuals. |
.Sh REFERENCE |
.Sh REFERENCE |
This section is a canonical reference of all macros, arranged |
This section is a canonical reference of all macros, arranged |
alphabetically. |
alphabetically. |
|
|
.Dl \&.Ad 0x00000000 |
.Dl \&.Ad 0x00000000 |
.Ss \&An |
.Ss \&An |
Author name. |
Author name. |
|
Can be used both for the authors of the program, function, or driver |
|
documented in the manual, or for the authors of the manual itself. |
Requires either the name of an author or one of the following arguments: |
Requires either the name of an author or one of the following arguments: |
.Pp |
.Pp |
.Bl -tag -width "-nosplitX" -offset indent -compact |
.Bl -tag -width "-nosplitX" -offset indent -compact |
Line 1061 If an argument is not provided, the string |
|
Line 1109 If an argument is not provided, the string |
|
is used as a default. |
is used as a default. |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Fl o \&Ns \&Ar file1 |
.Dl ".Fl o Ar file" |
.Dl \&.Ar |
.Dl ".Ar" |
.Dl \&.Ar arg1 , arg2 . |
.Dl ".Ar arg1 , arg2 ." |
|
.Pp |
|
The arguments to the |
|
.Sx \&Ar |
|
macro are names and placeholders for command arguments; |
|
for fixed strings to be passed verbatim as arguments, use |
|
.Sx \&Fl |
|
or |
|
.Sx \&Cm . |
.Ss \&At |
.Ss \&At |
Formats an AT&T version. |
Formats an AT&T version. |
Accepts one optional argument: |
Accepts one optional argument: |
|
|
Kernel configuration declaration. |
Kernel configuration declaration. |
This denotes strings accepted by |
This denotes strings accepted by |
.Xr config 8 . |
.Xr config 8 . |
|
It is most often used in section 4 manual pages. |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Cd device le0 at scode? |
.Dl \&.Cd device le0 at scode? |
|
|
This practise is discouraged. |
This practise is discouraged. |
.Ss \&Cm |
.Ss \&Cm |
Command modifiers. |
Command modifiers. |
Useful when specifying configuration options or keys. |
Typically used for fixed strings passed as arguments, unless |
|
.Sx \&Fl |
|
is more appropriate. |
|
Also useful when specifying configuration options or keys. |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Cm ControlPath |
.Dl ".Nm mt Fl f Ar device Cm rewind" |
.Dl \&.Cm ControlMaster |
.Dl ".Nm ps Fl o Cm pid , Ns Cm command" |
.Pp |
.Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2" |
See also |
.Dl ".Cm IdentityFile Pa ~/.ssh/id_rsa" |
.Sx \&Fl . |
.Dl ".Cm LogLevel Dv DEBUG" |
.Ss \&D1 |
.Ss \&D1 |
One-line indented display. |
One-line indented display. |
This is formatted by the default rules and is useful for simple indented |
This is formatted by the default rules and is useful for simple indented |
|
|
Error constants for definitions of the |
Error constants for definitions of the |
.Va errno |
.Va errno |
libc global variable. |
libc global variable. |
|
This is most often used in section 2 and 3 manual pages. |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Er EPERM |
.Dl \&.Er EPERM |
Line 1860 for general constants. |
|
Line 1921 for general constants. |
|
.Ss \&Ex |
.Ss \&Ex |
Insert a standard sentence regarding command exit values of 0 on success |
Insert a standard sentence regarding command exit values of 0 on success |
and >0 on failure. |
and >0 on failure. |
|
This is most often used in section 1, 6, and 8 manual pages. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&Ex Fl std Op Ar utility ... |
.D1 Pf \. Sx \&Ex Fl std Op Ar utility ... |
|
|
and |
and |
.Sx \&In . |
.Sx \&In . |
.Ss \&Fl |
.Ss \&Fl |
Command-line flag. |
Command-line flag or option. |
Used when listing arguments to command-line utilities. |
Used when listing arguments to command-line utilities. |
Prints a fixed-width hyphen |
Prints a fixed-width hyphen |
.Sq \- |
.Sq \- |
Line 1930 If the argument is a macro, a hyphen is prefixed to th |
|
Line 1992 If the argument is a macro, a hyphen is prefixed to th |
|
output. |
output. |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Fl a b c |
.Dl ".Nm cat Fl v No considered harmful" |
.Dl \&.Fl \&Pf a b |
.Dl ".Nm cp Fl pR Ar source ... directory" |
.Dl \&.Fl |
.Dl ".Nm find Ar dir Fl type Cm d Fl name Pa CVS |
.Dl \&.Op \&Fl o \&Ns \&Ar file |
.Dl ".Nm kill Fl Ar signal_number pid" |
|
.Dl ".Nm su Fl" |
.Pp |
.Pp |
See also |
See also |
.Sx \&Cm . |
.Sx \&Cm . |
Line 1950 Its syntax is as follows: |
|
Line 2013 Its syntax is as follows: |
|
Function arguments are surrounded in parenthesis and |
Function arguments are surrounded in parenthesis and |
are delimited by commas. |
are delimited by commas. |
If no arguments are specified, blank parenthesis are output. |
If no arguments are specified, blank parenthesis are output. |
|
In the |
|
.Em SYNOPSIS |
|
section, this macro starts a new output line, |
|
and a blank line is automatically inserted between function definitions. |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Fn \*qint funcname\*q \*qint arg0\*q \*qint arg1\*q |
.Dl \&.Fn \*qint funcname\*q \*qint arg0\*q \*qint arg1\*q |
.Dl \&.Fn funcname \*qint arg0\*q |
.Dl \&.Fn funcname \*qint arg0\*q |
.Dl \&.Fn funcname arg0 |
.Dl \&.Fn funcname arg0 |
|
.Pp |
.Bd -literal -offset indent -compact |
.Bd -literal -offset indent -compact |
\&.Ft functype |
\&.Ft functype |
\&.Fn funcname |
\&.Fn funcname |
Line 1964 When referring to a function documented in another man |
|
Line 2032 When referring to a function documented in another man |
|
.Sx \&Xr |
.Sx \&Xr |
instead. |
instead. |
See also |
See also |
.Sx MANUAL STRUCTURE |
.Sx MANUAL STRUCTURE , |
|
.Sx \&Fo , |
and |
and |
.Sx \&Ft . |
.Sx \&Ft . |
.Ss \&Fo |
.Ss \&Fo |
Line 1991 Invocations usually occur in the following context: |
|
Line 2060 Invocations usually occur in the following context: |
|
A |
A |
.Sx \&Fo |
.Sx \&Fo |
scope is closed by |
scope is closed by |
|
.Sx \&Fc . |
.Pp |
.Pp |
See also |
See also |
.Sx MANUAL STRUCTURE , |
.Sx MANUAL STRUCTURE , |
Line 2006 Its syntax is as follows: |
|
Line 2076 Its syntax is as follows: |
|
.Pp |
.Pp |
.D1 Pf \. Sx \&Ft Ar functype |
.D1 Pf \. Sx \&Ft Ar functype |
.Pp |
.Pp |
|
In the |
|
.Em SYNOPSIS |
|
section, a new output line is started after this macro. |
|
.Pp |
Examples: |
Examples: |
.Dl \&.Ft int |
.Dl \&.Ft int |
.Bd -literal -offset indent -compact |
.Bd -literal -offset indent -compact |
Line 2046 This is similar to |
|
Line 2120 This is similar to |
|
but used for instructions rather than values. |
but used for instructions rather than values. |
.Pp |
.Pp |
Examples: |
Examples: |
|
.Dl \&.Ic :wq |
.Dl \&.Ic hash |
.Dl \&.Ic hash |
.Dl \&.Ic alias |
.Dl \&.Ic alias |
.Pp |
.Pp |
Line 2060 macro is used when referring to specific instructions. |
|
Line 2135 macro is used when referring to specific instructions. |
|
An |
An |
.Dq include |
.Dq include |
file. |
file. |
In the |
When invoked as the first macro on an input line in the |
.Em SYNOPSIS |
.Em SYNOPSIS |
section (only if invoked as the line macro), the first argument is |
section, the argument is displayed in angle brackets |
preceded by |
and preceded by |
.Dq #include , |
.Dq #include , |
the arguments is enclosed in angle brackets. |
and a blank line is inserted in front if there is a preceding |
|
function declaration. |
|
This is most often used in section 2, 3, and 9 manual pages. |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.In sys/types |
.Dl \&.In sys/types.h |
.Pp |
.Pp |
See also |
See also |
.Sx MANUAL STRUCTURE . |
.Sx MANUAL STRUCTURE . |
|
|
\&.Oc |
\&.Oc |
.Ed |
.Ed |
.Ss \&Op |
.Ss \&Op |
Command-line option. |
Optional part of a command line. |
Used when listing options to command-line utilities. |
|
Prints the argument(s) in brackets. |
Prints the argument(s) in brackets. |
|
This is most often used in the |
|
.Em SYNOPSIS |
|
section of section 1 and 8 manual pages. |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Op \&Fl a \&Ar b |
.Dl \&.Op \&Fl a \&Ar b |
|
|
and |
and |
.Sx \&Ux . |
.Sx \&Ux . |
.Ss \&Pa |
.Ss \&Pa |
A file-system path. |
An absolute or relative file system path, or a file or directory name. |
If an argument is not provided, the string |
If an argument is not provided, the character |
.Dq \(ti |
.Sq \(ti |
is used as a default. |
is used as a default. |
.Pp |
.Pp |
Examples: |
Examples: |
Line 2534 custom sections be used. |
|
Line 2613 custom sections be used. |
|
.Pp |
.Pp |
Section names should be unique so that they may be keyed by |
Section names should be unique so that they may be keyed by |
.Sx \&Sx . |
.Sx \&Sx . |
|
Although this macro is parsed, it should not consist of child node or it |
|
may not be linked with |
|
.Sx \&Sx . |
.Pp |
.Pp |
See also |
See also |
.Sx \&Pp , |
.Sx \&Pp , |
Line 2577 rarely have sub-sections. |
|
Line 2659 rarely have sub-sections. |
|
.Pp |
.Pp |
Sub-section names should be unique so that they may be keyed by |
Sub-section names should be unique so that they may be keyed by |
.Sx \&Sx . |
.Sx \&Sx . |
|
Although this macro is parsed, it should not consist of child node or it |
|
may not be linked with |
|
.Sx \&Sx . |
.Pp |
.Pp |
See also |
See also |
.Sx \&Pp , |
.Sx \&Pp , |
Line 2658 The following standards are recognised: |
|
Line 2743 The following standards are recognised: |
|
.St -xpg4 |
.St -xpg4 |
.It \-xpg4.2 |
.It \-xpg4.2 |
.St -xpg4.2 |
.St -xpg4.2 |
|
.It \-xpg4.3 |
.St -xpg4.3 |
.St -xpg4.3 |
.It \-xbd5 |
.It \-xbd5 |
.St -xbd5 |
.St -xbd5 |
Line 2745 This is also used for indicating global variables in t |
|
Line 2831 This is also used for indicating global variables in t |
|
section, in which case a variable name is also specified. |
section, in which case a variable name is also specified. |
Note that it accepts |
Note that it accepts |
.Sx Block partial-implicit |
.Sx Block partial-implicit |
syntax when invoked as the first macro in the |
syntax when invoked as the first macro on an input line in the |
.Em SYNOPSIS |
.Em SYNOPSIS |
section, else it accepts ordinary |
section, else it accepts ordinary |
.Sx In-line |
.Sx In-line |
syntax. |
syntax. |
|
In the former case, this macro starts a new output line, |
|
and a blank line is inserted in front if there is a preceding |
|
function definition or include directive. |
.Pp |
.Pp |
Note that this should not be confused with |
Note that this should not be confused with |
.Sx \&Ft , |
.Sx \&Ft , |
Line 2917 In new groff and mandoc, any list may be nested by def |
|
Line 3006 In new groff and mandoc, any list may be nested by def |
|
lists will restart the sequence only for the sub-list. |
lists will restart the sequence only for the sub-list. |
.It |
.It |
.Sx \&Li |
.Sx \&Li |
followed by a reserved character is incorrectly used in some manuals |
followed by a delimiter is incorrectly used in some manuals |
instead of properly quoting that character, which sometimes works with |
instead of properly quoting that character, which sometimes works with |
historic groff. |
historic groff. |
.It |
.It |