version 1.236, 2014/08/28 03:51:56 |
version 1.261, 2017/02/05 22:30:29 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze <schwarze@openbsd.org> |
.\" Copyright (c) 2010, 2011, 2013-2017 Ingo Schwarze <schwarze@openbsd.org> |
.\" |
.\" |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" purpose with or without fee is hereby granted, provided that the above |
.\" purpose with or without fee is hereby granted, provided that the above |
Line 304 Print verbose information. |
|
Line 304 Print verbose information. |
|
\&.El |
\&.El |
.Ed |
.Ed |
.Pp |
.Pp |
|
List the options in alphabetical order, |
|
uppercase before lowercase for each letter and |
|
with no regard to whether an option takes an argument. |
|
Put digits in ascending order before all letter options. |
|
.Pp |
Manuals not documenting a command won't include the above fragment. |
Manuals not documenting a command won't include the above fragment. |
.Pp |
.Pp |
Since the |
Since the |
|
|
References other manuals with related topics. |
References other manuals with related topics. |
This section should exist for most manuals. |
This section should exist for most manuals. |
Cross-references should conventionally be ordered first by section, then |
Cross-references should conventionally be ordered first by section, then |
alphabetically. |
alphabetically (ignoring case). |
.Pp |
.Pp |
References to other documentation concerning the topic of the manual page, |
References to other documentation concerning the topic of the manual page, |
for example authoritative books or journal articles, may also be |
for example authoritative books or journal articles, may also be |
Line 433 in the alphabetical |
|
Line 438 in the alphabetical |
|
.Ss Document preamble and NAME section macros |
.Ss Document preamble and NAME section macros |
.Bl -column "Brq, Bro, Brc" description |
.Bl -column "Brq, Bro, Brc" description |
.It Sx \&Dd Ta document date: Cm $\&Mdocdate$ | Ar month day , year |
.It Sx \&Dd Ta document date: Cm $\&Mdocdate$ | Ar month day , year |
.It Sx \&Dt Ta document title: Ar TITLE section Op Ar volume | arch |
.It Sx \&Dt Ta document title: Ar TITLE section Op Ar arch |
.It Sx \&Os Ta operating system version: Op Ar system Op Ar version |
.It Sx \&Os Ta operating system version: Op Ar system Op Ar version |
.It Sx \&Nm Ta document name (one argument) |
.It Sx \&Nm Ta document name (one argument) |
.It Sx \&Nd Ta document description (one line) |
.It Sx \&Nd Ta document description (one line) |
Line 454 in the alphabetical |
|
Line 459 in the alphabetical |
|
.Op Fl compact |
.Op Fl compact |
.It Sx \&D1 Ta indented display (one line) |
.It Sx \&D1 Ta indented display (one line) |
.It Sx \&Dl Ta indented literal display (one line) |
.It Sx \&Dl Ta indented literal display (one line) |
|
.It Sx \&Ql Ta in-line literal display: Ql text |
.It Sx \&Bl , \&El Ta list block: |
.It Sx \&Bl , \&El Ta list block: |
.Fl Ar type |
.Fl Ar type |
.Op Fl width Ar val |
.Op Fl width Ar val |
Line 528 in the alphabetical |
|
Line 534 in the alphabetical |
|
.It Sx \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text |
.It Sx \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text |
.It Sx \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text |
.It Sx \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text |
.It Sx \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text |
.It Sx \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text |
.It Sx \&Ql Ta single-quoted literal text: Ql text |
|
.It Sx \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text |
.It Sx \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text |
.It Sx \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text |
.It Sx \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text |
.It Sx \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text |
.It Sx \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text |
|
|
must be one of the following: |
must be one of the following: |
.Bl -tag -width 13n -offset indent |
.Bl -tag -width 13n -offset indent |
.It Fl centered |
.It Fl centered |
Produce one output line from each input line, and centre-justify each line. |
Produce one output line from each input line, and center-justify each line. |
Using this display type is not recommended; many |
Using this display type is not recommended; many |
.Nm |
.Nm |
implementations render it poorly. |
implementations render it poorly. |
Line 822 which has no effect; |
|
Line 827 which has no effect; |
|
.Cm right , |
.Cm right , |
which justifies to the right margin; or |
which justifies to the right margin; or |
.Cm center , |
.Cm center , |
which aligns around an imagined centre axis. |
which aligns around an imagined center axis. |
.It |
.It |
A macro invocation, which selects a predefined width |
A macro invocation, which selects a predefined width |
associated with that macro. |
associated with that macro. |
|
|
.Fl width |
.Fl width |
and |
and |
.Fl offset |
.Fl offset |
arguments accept scaling widths as described in |
arguments accept macro names as described for |
.Xr roff 7 |
.Sx \&Bd |
|
.Fl offset , |
|
scaling widths as described in |
|
.Xr roff 7 , |
or use the length of the given string. |
or use the length of the given string. |
The |
The |
.Fl offset |
.Fl offset |
|
|
and |
and |
.Sx \&Dl . |
.Sx \&Dl . |
.Ss \&Db |
.Ss \&Db |
Switch debugging mode. |
This macro is obsolete. |
Its syntax is as follows: |
No replacement is needed. |
.Pp |
It is ignored by |
.D1 Pf \. Sx \&Db Cm on | off |
.Xr mandoc 1 |
.Pp |
and groff including its arguments. |
This macro is ignored by |
It was formerly used to toggle a debugging mode. |
.Xr mandoc 1 . |
|
.Ss \&Dc |
.Ss \&Dc |
Close a |
Close a |
.Sx \&Do |
.Sx \&Do |
|
|
and |
and |
.Sx \&Os . |
.Sx \&Os . |
.Ss \&Dl |
.Ss \&Dl |
One-line intended display. |
One-line indented display. |
This is formatted as literal text and is useful for commands and |
This is formatted as literal text and is useful for commands and |
invocations. |
invocations. |
It is followed by a newline. |
It is followed by a newline. |
|
|
.Dl \&.Dl % mandoc mdoc.7 \e(ba less |
.Dl \&.Dl % mandoc mdoc.7 \e(ba less |
.Pp |
.Pp |
See also |
See also |
|
.Sx \&Ql , |
.Sx \&Bd |
.Sx \&Bd |
|
.Fl literal , |
and |
and |
.Sx \&D1 . |
.Sx \&D1 . |
.Ss \&Do |
.Ss \&Do |
Line 1297 Its syntax is as follows: |
|
Line 1306 Its syntax is as follows: |
|
.Pf \. Sx \&Dt |
.Pf \. Sx \&Dt |
.Ar TITLE |
.Ar TITLE |
.Ar section |
.Ar section |
.Op Ar volume | arch |
.Op Ar arch |
.Ed |
.Ed |
.Pp |
.Pp |
Its arguments are as follows: |
Its arguments are as follows: |
Line 1312 it should by convention be all caps. |
|
Line 1321 it should by convention be all caps. |
|
The manual section. |
The manual section. |
This may be one of |
This may be one of |
.Cm 1 |
.Cm 1 |
.Pq utilities , |
.Pq General Commands , |
.Cm 2 |
.Cm 2 |
.Pq system calls , |
.Pq System Calls , |
.Cm 3 |
.Cm 3 |
.Pq libraries , |
.Pq Library Functions , |
.Cm 3p |
.Cm 3p |
.Pq Perl libraries , |
.Pq Perl Library , |
.Cm 4 |
.Cm 4 |
.Pq devices , |
.Pq Device Drivers , |
.Cm 5 |
.Cm 5 |
.Pq file formats , |
.Pq File Formats , |
.Cm 6 |
.Cm 6 |
.Pq games , |
.Pq Games , |
.Cm 7 |
.Cm 7 |
.Pq miscellaneous , |
.Pq Miscellaneous Information , |
.Cm 8 |
.Cm 8 |
.Pq system utilities , |
.Pq System Manager's Manual , |
.Cm 9 |
|
.Pq kernel functions , |
|
.Cm X11 |
|
.Pq X Window System , |
|
.Cm X11R6 |
|
.Pq X Window System , |
|
.Cm unass |
|
.Pq unassociated , |
|
.Cm local |
|
.Pq local system , |
|
.Cm draft |
|
.Pq draft manual , |
|
or |
or |
.Cm paper |
.Cm 9 |
.Pq paper . |
.Pq Kernel Developer's Manual . |
It should correspond to the manual's filename suffix and defaults to |
It should correspond to the manual's filename suffix and defaults to |
the empty string if unspecified. |
the empty string if unspecified. |
.It Ar volume |
|
This overrides the volume inferred from |
|
.Ar section . |
|
This field is optional, and if specified, must be one of |
|
.Cm USD |
|
.Pq users' supplementary documents , |
|
.Cm PS1 |
|
.Pq programmers' supplementary documents , |
|
.Cm AMD |
|
.Pq administrators' supplementary documents , |
|
.Cm SMM |
|
.Pq system managers' manuals , |
|
.Cm URM |
|
.Pq users' reference manuals , |
|
.Cm PRM |
|
.Pq programmers' reference manuals , |
|
.Cm KM |
|
.Pq kernel manuals , |
|
.Cm IND |
|
.Pq master index , |
|
.Cm MMI |
|
.Pq master index , |
|
.Cm LOCAL |
|
.Pq local manuals , |
|
.Cm LOC |
|
.Pq local manuals , |
|
or |
|
.Cm CON |
|
.Pq contributed manuals . |
|
.It Ar arch |
.It Ar arch |
This specifies the machine architecture a manual page applies to, |
This specifies the machine architecture a manual page applies to, |
where relevant, for example |
where relevant, for example |
Line 1383 where relevant, for example |
|
Line 1351 where relevant, for example |
|
.Cm i386 , |
.Cm i386 , |
or |
or |
.Cm sparc64 . |
.Cm sparc64 . |
The list of supported architectures varies by operating system. |
The list of valid architectures varies by operating system. |
For the full list of all architectures recognized by |
|
.Xr mandoc 1 , |
|
see the file |
|
.Pa arch.in |
|
in the source distribution. |
|
.El |
.El |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Dt FOO 1 |
.Dl \&.Dt FOO 1 |
.Dl \&.Dt FOO 4 KM |
|
.Dl \&.Dt FOO 9 i386 |
.Dl \&.Dt FOO 9 i386 |
.Pp |
.Pp |
See also |
See also |
Line 1570 arguments are treated as separate utilities. |
|
Line 1532 arguments are treated as separate utilities. |
|
See also |
See also |
.Sx \&Rv . |
.Sx \&Rv . |
.Ss \&Fa |
.Ss \&Fa |
Function argument. |
Function argument or parameter. |
Its syntax is as follows: |
Its syntax is as follows: |
.Bd -ragged -offset indent |
.Bd -ragged -offset indent |
.Pf \. Sx \&Fa |
.Pf \. Sx \&Fa |
|
|
A function name. |
A function name. |
Its syntax is as follows: |
Its syntax is as follows: |
.Bd -ragged -offset indent |
.Bd -ragged -offset indent |
.Pf \. Ns Sx \&Fn |
.Pf . Sx \&Fn |
.Op Ar functype |
.Op Ar functype |
.Ar funcname |
.Ar funcname |
.Op Oo Ar argtype Oc Ar argname |
.Op Oo Ar argtype Oc Ar argname |
Line 1801 is preferred for displaying code; the |
|
Line 1763 is preferred for displaying code; the |
|
.Sx \&Ic |
.Sx \&Ic |
macro is used when referring to specific instructions. |
macro is used when referring to specific instructions. |
.Ss \&In |
.Ss \&In |
An |
The name of an include file. |
.Dq include |
This macro is most often used in section 2, 3, and 9 manual pages. |
file. |
.Pp |
When invoked as the first macro on an input line in the |
When invoked as the first macro on an input line in the |
.Em SYNOPSIS |
.Em SYNOPSIS |
section, the argument is displayed in angle brackets |
section, the argument is displayed in angle brackets |
and preceded by |
and preceded by |
.Dq #include , |
.Qq #include , |
and a blank line is inserted in front if there is a preceding |
and a blank line is inserted in front if there is a preceding |
function declaration. |
function declaration. |
This is most often used in section 2, 3, and 9 manual pages. |
In other sections, it only encloses its argument in angle brackets |
|
and causes no line break. |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.In sys/types.h |
.Dl \&.In sys/types.h |
|
|
list is the most complicated. |
list is the most complicated. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ... |
|
.D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ... |
.D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ... |
|
.D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ... |
.Pp |
.Pp |
The arguments consist of one or more lines of text and macros |
The arguments consist of one or more lines of text and macros |
representing a complete table line. |
representing a complete table line. |
Cells within the line are delimited by tabs or by the special |
Cells within the line are delimited by the special |
.Sx \&Ta |
.Sx \&Ta |
block macro. |
block macro or by literal tab characters. |
|
.Pp |
|
Using literal tabs is strongly discouraged because they are very |
|
hard to use correctly and |
|
.Nm |
|
code using them is very hard to read. |
|
In particular, a blank character is syntactically significant |
|
before and after the literal tab character. |
|
If a word precedes or follows the tab without an intervening blank, |
|
that word is never interpreted as a macro call, but always output |
|
literally. |
|
.Pp |
The tab cell delimiter may only be used within the |
The tab cell delimiter may only be used within the |
.Sx \&It |
.Sx \&It |
line itself; on following lines, only the |
line itself; on following lines, only the |
Line 1890 Note that quoted strings may span tab-delimited cells |
|
Line 1864 Note that quoted strings may span tab-delimited cells |
|
line. |
line. |
For example, |
For example, |
.Pp |
.Pp |
.Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&; |
.Dl .It \(dqcol1 ,\& <TAB> col2 ,\(dq \&; |
.Pp |
.Pp |
will preserve the semicolon whitespace except for the last. |
will preserve the whitespace before both commas, |
|
but not the whitespace before the semicolon. |
.Pp |
.Pp |
See also |
See also |
.Sx \&Bl . |
.Sx \&Bl . |
|
|
.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv |
.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv |
.Ss \&Nd |
.Ss \&Nd |
A one line description of the manual's content. |
A one line description of the manual's content. |
This may only be invoked in the |
This is the mandatory last macro of the |
.Em SYNOPSIS |
.Em NAME |
section subsequent the |
section and not appropriate for other sections. |
.Sx \&Nm |
|
macro. |
|
.Pp |
.Pp |
Examples: |
Examples: |
.Dl Pf . Sx \&Nd mdoc language reference |
.Dl Pf . Sx \&Nd mdoc language reference |
Line 2133 Its syntax is as follows: |
|
Line 2106 Its syntax is as follows: |
|
The optional |
The optional |
.Ar system |
.Ar system |
parameter specifies the relevant operating system or environment. |
parameter specifies the relevant operating system or environment. |
Left unspecified, it defaults to the local operating system version. |
It is suggested to leave it unspecified, in which case |
This is the suggested form. |
.Xr mandoc 1 |
|
uses its |
|
.Fl Ios |
|
argument or, if that isn't specified either, |
|
.Fa sysname |
|
and |
|
.Fa release |
|
as returned by |
|
.Xr uname 3 . |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Os |
.Dl \&.Os |
|
|
Close parenthesised context opened by |
Close parenthesised context opened by |
.Sx \&Po . |
.Sx \&Po . |
.Ss \&Pf |
.Ss \&Pf |
Removes the space between its argument |
Removes the space between its argument and the following macro. |
.Pq Dq prefix |
|
and the following macro. |
|
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 .Pf Ar prefix macro arguments ... |
.D1 .Pf Ar prefix macro arguments ... |
.Pp |
.Pp |
This is equivalent to: |
This is equivalent to: |
.Pp |
.Pp |
.D1 .No Ar prefix No \&Ns Ar macro arguments ... |
.D1 .No \e& Ns Ar prefix No \&Ns Ar macro arguments ... |
.Pp |
.Pp |
|
The |
|
.Ar prefix |
|
argument is not parsed for macro names or delimiters, |
|
but used verbatim as if it were escaped. |
|
.Pp |
Examples: |
Examples: |
.Dl ".Pf $ Ar variable_name" |
.Dl ".Pf $ Ar variable_name" |
|
.Dl ".Pf . Ar macro_name" |
.Dl ".Pf 0x Ar hex_digits" |
.Dl ".Pf 0x Ar hex_digits" |
.Pp |
.Pp |
See also |
See also |
|
|
Close quoted context opened by |
Close quoted context opened by |
.Sx \&Qo . |
.Sx \&Qo . |
.Ss \&Ql |
.Ss \&Ql |
Format a single-quoted literal. |
In-line literal display. |
|
This can for example be used for complete command invocations and |
|
for multi-word code fragments when more specific markup is not |
|
appropriate and an indented display is not desired. |
|
While |
|
.Xr mandoc 1 |
|
always encloses the arguments in single quotes, other formatters |
|
usually omit the quotes on non-terminal output devices when the |
|
arguments have three or more characters. |
|
.Pp |
See also |
See also |
.Sx \&Qq |
.Sx \&Dl |
and |
and |
.Sx \&Sq . |
.Sx \&Bd |
|
.Fl literal . |
.Ss \&Qo |
.Ss \&Qo |
Multi-line version of |
Multi-line version of |
.Sx \&Qq . |
.Sx \&Qq . |
|
|
\&.%A J. D. Ullman |
\&.%A J. D. Ullman |
\&.%B Introduction to Automata Theory, Languages, and Computation |
\&.%B Introduction to Automata Theory, Languages, and Computation |
\&.%I Addison-Wesley |
\&.%I Addison-Wesley |
\&.%C Reading, Massachusettes |
\&.%C Reading, Massachusetts |
\&.%D 1979 |
\&.%D 1979 |
\&.Re |
\&.Re |
.Ed |
.Ed |
Line 2429 The original C standard. |
|
Line 2424 The original C standard. |
|
.Pp |
.Pp |
.It \-isoC-99 |
.It \-isoC-99 |
.St -isoC-99 |
.St -isoC-99 |
.It \-ansiC-99 |
|
.St -ansiC-99 |
|
.br |
.br |
The second major version of the C language standard. |
The second major version of the C language standard. |
.Pp |
.Pp |
Line 2530 The following three refer to parts of it. |
|
Line 2523 The following three refer to parts of it. |
|
.br |
.br |
Networking APIs, including sockets. |
Networking APIs, including sockets. |
.Pp |
.Pp |
.It \-xpg4.3 |
|
.St -xpg4.3 |
|
.Pp |
|
.It \-svid4 |
.It \-svid4 |
.St -svid4 , |
.St -svid4 , |
.br |
.br |
Line 2559 The following refer to parts of it. |
|
Line 2549 The following refer to parts of it. |
|
.Pp |
.Pp |
.It \-xns5 |
.It \-xns5 |
.St -xns5 |
.St -xns5 |
.It \-xns5.2d2.0 |
|
.St -xns5.2d2.0 |
|
.It \-xns5.2 |
.It \-xns5.2 |
.St -xns5.2 |
.St -xns5.2 |
.Pp |
|
.It \-p1387.2 |
|
.St -p1387.2 |
|
.It \-p1387.2-95 |
|
.St -p1387.2-95 |
|
.br |
|
POSIX software administration. |
|
.El |
.El |
.It Single UNIX Specification version 3 and related standards |
.It Single UNIX Specification version 3 |
.Pp |
.Pp |
.Bl -tag -width "-p1003.1g-2000X" -compact |
.Bl -tag -width "-p1003.1-2001" -compact |
.It \-p1003.1d-99 |
|
.St -p1003.1d-99 |
|
.br |
|
Additional real-time extensions. |
|
.Pp |
|
.It \-p1003.1j-2000 |
|
.St -p1003.1j-2000 |
|
.br |
|
Advanced real-time extensions. |
|
.Pp |
|
.It \-p1003.1q-2000 |
|
.St -p1003.1q-2000 |
|
.br |
|
Amendment 7: Tracing [C Language]. |
|
.Pp |
|
.It \-p1003.1-2001 |
.It \-p1003.1-2001 |
.St -p1003.1-2001 |
.St -p1003.1-2001 |
.It \-susv3 |
.It \-susv3 |
Line 2704 A variable name. |
|
Line 2670 A variable name. |
|
Examples: |
Examples: |
.Dl \&.Va foo |
.Dl \&.Va foo |
.Dl \&.Va const char *bar ; |
.Dl \&.Va const char *bar ; |
|
.Pp |
|
For function arguments and parameters, use |
|
.Sx \&Fa |
|
instead. |
|
For declarations of global variables in the |
|
.Em SYNOPSIS |
|
section, use |
|
.Sx \&Vt . |
.Ss \&Vt |
.Ss \&Vt |
A variable type. |
A variable type. |
|
.Pp |
This is also used for indicating global variables in the |
This is also used for indicating global variables in the |
.Em SYNOPSIS |
.Em SYNOPSIS |
section, in which case a variable name is also specified. |
section, in which case a variable name is also specified. |
Line 2720 In the former case, this macro starts a new output lin |
|
Line 2695 In the former case, this macro starts a new output lin |
|
and a blank line is inserted in front if there is a preceding |
and a blank line is inserted in front if there is a preceding |
function definition or include directive. |
function definition or include directive. |
.Pp |
.Pp |
Note that this should not be confused with |
|
.Sx \&Ft , |
|
which is used for function return types. |
|
.Pp |
|
Examples: |
Examples: |
.Dl \&.Vt unsigned char |
.Dl \&.Vt unsigned char |
.Dl \&.Vt extern const char * const sys_signame[] \&; |
.Dl \&.Vt extern const char * const sys_signame[] \&; |
.Pp |
.Pp |
|
For parameters in function prototypes, use |
|
.Sx \&Fa |
|
instead, for function return types |
|
.Sx \&Ft , |
|
and for variable names outside the |
|
.Em SYNOPSIS |
|
section |
|
.Sx \&Va , |
|
even when including a type with the name. |
See also |
See also |
.Sx MANUAL STRUCTURE |
.Sx MANUAL STRUCTURE . |
and |
|
.Sx \&Va . |
|
.Ss \&Xc |
.Ss \&Xc |
Close a scope opened by |
Close a scope opened by |
.Sx \&Xo . |
.Sx \&Xo . |
Line 2748 Link to another manual |
|
Line 2726 Link to another manual |
|
.Pq Qq cross-reference . |
.Pq Qq cross-reference . |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&Xr Ar name Op section |
.D1 Pf \. Sx \&Xr Ar name section |
.Pp |
.Pp |
Cross reference the |
Cross reference the |
.Ar name |
.Ar name |
and |
and |
.Ar section |
.Ar section |
number of another man page; |
number of another man page. |
omitting the section number is rarely useful. |
|
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Xr mandoc 1 |
.Dl \&.Xr mandoc 1 |
Line 3067 then the macro accepts an arbitrary number of argument |
|
Line 3044 then the macro accepts an arbitrary number of argument |
|
.It Sx \&Ux Ta Yes Ta Yes Ta n |
.It Sx \&Ux Ta Yes Ta Yes Ta n |
.It Sx \&Va Ta Yes Ta Yes Ta n |
.It Sx \&Va Ta Yes Ta Yes Ta n |
.It Sx \&Vt Ta Yes Ta Yes Ta >0 |
.It Sx \&Vt Ta Yes Ta Yes Ta >0 |
.It Sx \&Xr Ta Yes Ta Yes Ta >0 |
.It Sx \&Xr Ta Yes Ta Yes Ta 2 |
.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 |
Line 3087 For many macros, when the leading arguments are openin |
|
Line 3064 For many macros, when the leading arguments are openin |
|
these delimiters are put before the macro scope, |
these delimiters are put before the macro scope, |
and when the trailing arguments are closing delimiters, |
and when the trailing arguments are closing delimiters, |
these delimiters are put after the macro scope. |
these delimiters are put after the macro scope. |
|
Spacing is suppressed after opening delimiters |
|
and before closing delimiters. |
For example, |
For example, |
.Pp |
.Pp |
.D1 Pf \. \&Aq "( [ word ] ) ." |
.D1 Pf \. \&Aq "( [ word ] ) ." |
|
|
.D1 Fl a ( b | c \*(Ba d ) e |
.D1 Fl a ( b | c \*(Ba d ) e |
.Pp |
.Pp |
This applies to both opening and closing delimiters, |
This applies to both opening and closing delimiters, |
and also to the middle delimiter: |
and also to the middle delimiter, which does not suppress spacing: |
.Pp |
.Pp |
.Bl -tag -width Ds -offset indent -compact |
.Bl -tag -width Ds -offset indent -compact |
.It \&| |
.It \&| |
Line 3175 Manually switching the font using the |
|
Line 3154 Manually switching the font using the |
|
font escape sequences is never required. |
font escape sequences is never required. |
.Sh COMPATIBILITY |
.Sh COMPATIBILITY |
This section provides an incomplete list of compatibility issues |
This section provides an incomplete list of compatibility issues |
between mandoc and other troff implementations, at this time limited |
between mandoc and GNU troff |
to GNU troff |
|
.Pq Qq groff . |
.Pq Qq groff . |
The term |
|
.Qq historic groff |
|
refers to groff versions before 1.17, |
|
which featured a significant update of the |
|
.Pa doc.tmac |
|
file. |
|
.Pp |
.Pp |
Heirloom troff, the other significant troff implementation accepting |
|
\-mdoc, is similar to historic groff. |
|
.Pp |
|
The following problematic behaviour is found in groff: |
The following problematic behaviour is found in groff: |
.ds hist (Historic groff only.) |
|
.Pp |
.Pp |
.Bl -dash -compact |
.Bl -dash -compact |
.It |
.It |
Display macros |
|
.Po |
|
.Sx \&Bd , |
|
.Sx \&Dl , |
|
and |
|
.Sx \&D1 |
|
.Pc |
|
may not be nested. |
|
\*[hist] |
|
.It |
|
.Sx \&At |
|
with unknown arguments produces no output at all. |
|
\*[hist] |
|
Newer groff and mandoc print |
|
.Qq AT&T UNIX |
|
and the arguments. |
|
.It |
|
.Sx \&Bl Fl column |
|
does not recognise trailing punctuation characters when they immediately |
|
precede tabulator characters, but treats them as normal text and |
|
outputs a space before them. |
|
.It |
|
.Sx \&Bd Fl ragged compact |
|
does not start a new line. |
|
\*[hist] |
|
.It |
|
.Sx \&Dd |
.Sx \&Dd |
with non-standard arguments behaves very strangely. |
with non-standard arguments behaves very strangely. |
When there are three arguments, they are printed verbatim. |
When there are three arguments, they are printed verbatim. |
Line 3227 but without any arguments the string |
|
Line 3169 but without any arguments the string |
|
.Dq Epoch |
.Dq Epoch |
is printed. |
is printed. |
.It |
.It |
.Sx \&Fl |
|
does not print a dash for an empty argument. |
|
\*[hist] |
|
.It |
|
.Sx \&Fn |
|
does not start a new line unless invoked as the line macro in the |
|
.Em SYNOPSIS |
|
section. |
|
\*[hist] |
|
.It |
|
.Sx \&Fo |
|
with |
|
.Pf non- Sx \&Fa |
|
children causes inconsistent spacing between arguments. |
|
In mandoc, a single space is always inserted between arguments. |
|
.It |
|
.Sx \&Ft |
|
in the |
|
.Em SYNOPSIS |
|
causes inconsistent vertical spacing, depending on whether a prior |
|
.Sx \&Fn |
|
has been invoked. |
|
See |
|
.Sx \&Ft |
|
and |
|
.Sx \&Fn |
|
for the normalised behaviour in mandoc. |
|
.It |
|
.Sx \&In |
|
ignores additional arguments and is not treated specially in the |
|
.Em SYNOPSIS . |
|
\*[hist] |
|
.It |
|
.Sx \&It |
|
sometimes requires a |
|
.Fl nested |
|
flag. |
|
\*[hist] |
|
In new groff and mandoc, any list may be nested by default and |
|
.Fl enum |
|
lists will restart the sequence only for the sub-list. |
|
.It |
|
.Sx \&Li |
|
followed by a delimiter is incorrectly used in some manuals |
|
instead of properly quoting that character, which sometimes works with |
|
historic groff. |
|
.It |
|
.Sx \&Lk |
.Sx \&Lk |
only accepts a single link-name argument; the remainder is misformatted. |
only accepts a single link-name argument; the remainder is misformatted. |
.It |
.It |
Line 3287 can only be called by other macros, but not at the beg |
|
Line 3182 can only be called by other macros, but not at the beg |
|
.Sx \&%C |
.Sx \&%C |
is not implemented (up to and including groff-1.22.2). |
is not implemented (up to and including groff-1.22.2). |
.It |
.It |
Historic groff only allows up to eight or nine arguments per macro input |
|
line, depending on the exact situation. |
|
Providing more arguments causes garbled output. |
|
The number of arguments on one input line is not limited with mandoc. |
|
.It |
|
Historic groff has many un-callable macros. |
|
Most of these (excluding some block-level macros) are callable |
|
in new groff and mandoc. |
|
.It |
|
.Sq \(ba |
|
(vertical bar) is not fully supported as a delimiter. |
|
\*[hist] |
|
.It |
|
.Sq \ef |
.Sq \ef |
.Pq font face |
.Pq font face |
and |
and |
Line 3317 The following features are unimplemented in mandoc: |
|
Line 3199 The following features are unimplemented in mandoc: |
|
.Bl -dash -compact |
.Bl -dash -compact |
.It |
.It |
.Sx \&Bd |
.Sx \&Bd |
.Fl file Ar file . |
.Fl file Ar file |
|
is unsupported for security reasons. |
.It |
.It |
.Sx \&Bd |
.Sx \&Bd |
|
.Fl filled |
|
does not adjust the right margin, but is an alias for |
|
.Sx \&Bd |
|
.Fl ragged . |
|
.It |
|
.Sx \&Bd |
|
.Fl literal |
|
does not use a literal font, but is an alias for |
|
.Sx \&Bd |
|
.Fl unfilled . |
|
.It |
|
.Sx \&Bd |
.Fl offset Cm center |
.Fl offset Cm center |
and |
and |
.Fl offset Cm right . |
.Fl offset Cm right |
Groff does not implement centred and flush-right rendering either, |
don't work. |
|
Groff does not implement centered and flush-right rendering either, |
but produces large indentations. |
but produces large indentations. |
.El |
.El |
.Sh SEE ALSO |
.Sh SEE ALSO |
Line 3334 but produces large indentations. |
|
Line 3230 but produces large indentations. |
|
.Xr mandoc_char 7 , |
.Xr mandoc_char 7 , |
.Xr roff 7 , |
.Xr roff 7 , |
.Xr tbl 7 |
.Xr tbl 7 |
|
.Pp |
|
The web page |
|
.Lk http://mdocml.bsd.lv/mdoc/ "extended documentation for the mdoc language" |
|
provides a few tutorial-style pages for beginners, an extensive style |
|
guide for advanced authors, and an alphabetic index helping to choose |
|
the best macros for various kinds of content. |
.Sh HISTORY |
.Sh HISTORY |
The |
The |
.Nm |
.Nm |