version 1.258, 2016/10/11 17:30:33 |
version 1.273, 2018/12/23 16:55:34 |
|
|
.\" $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-2018 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 449 in the alphabetical |
|
Line 449 in the alphabetical |
|
.It Sx \&Ss Ta subsection header (one line) |
.It Sx \&Ss Ta subsection header (one line) |
.It Sx \&Sx Ta internal cross reference to a section or subsection |
.It Sx \&Sx Ta internal cross reference to a section or subsection |
.It Sx \&Xr Ta cross reference to another manual page: Ar name section |
.It Sx \&Xr Ta cross reference to another manual page: Ar name section |
.It Sx \&Pp , \&Lp Ta start a text paragraph (no arguments) |
.It Sx \&Pp Ta start a text paragraph (no arguments) |
.El |
.El |
.Ss Displays and lists |
.Ss Displays and lists |
.Bl -column "Brq, Bro, Brc" description |
.Bl -column "Brq, Bro, Brc" description |
Line 476 in the alphabetical |
|
Line 476 in the alphabetical |
|
.It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments) |
.It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments) |
.It Sx \&Sm Ta switch horizontal spacing mode: Op Cm on | off |
.It Sx \&Sm Ta switch horizontal spacing mode: Op Cm on | off |
.It Sx \&Bk , \&Ek Ta keep block: Fl words |
.It Sx \&Bk , \&Ek Ta keep block: Fl words |
.It Sx \&br Ta force output line break in text mode (no arguments) |
|
.It Sx \&sp Ta force vertical space: Op Ar height |
|
.El |
.El |
.Ss Semantic markup for command line utilities: |
.Ss Semantic markup for command line utilities |
.Bl -column "Brq, Bro, Brc" description |
.Bl -column "Brq, Bro, Brc" description |
.It Sx \&Nm Ta start a SYNOPSIS block with the name of a utility |
.It Sx \&Nm Ta start a SYNOPSIS block with the name of a utility |
.It Sx \&Fl Ta command line options (flags) (>=0 arguments) |
.It Sx \&Fl Ta command line options (flags) (>=0 arguments) |
Line 490 in the alphabetical |
|
Line 488 in the alphabetical |
|
.It Sx \&Ev Ta environmental variable (>0 arguments) |
.It Sx \&Ev Ta environmental variable (>0 arguments) |
.It Sx \&Pa Ta file system path (>=0 arguments) |
.It Sx \&Pa Ta file system path (>=0 arguments) |
.El |
.El |
.Ss Semantic markup for function libraries: |
.Ss Semantic markup for function libraries |
.Bl -column "Brq, Bro, Brc" description |
.Bl -column "Brq, Bro, Brc" description |
.It Sx \&Lb Ta function library (one argument) |
.It Sx \&Lb Ta function library (one argument) |
.It Sx \&In Ta include file (one argument) |
.It Sx \&In Ta include file (one argument) |
Line 511 in the alphabetical |
|
Line 509 in the alphabetical |
|
.It Sx \&Er Ta error constant (>0 arguments) |
.It Sx \&Er Ta error constant (>0 arguments) |
.It Sx \&Ev Ta environmental variable (>0 arguments) |
.It Sx \&Ev Ta environmental variable (>0 arguments) |
.El |
.El |
.Ss Various semantic markup: |
.Ss Various semantic markup |
.Bl -column "Brq, Bro, Brc" description |
.Bl -column "Brq, Bro, Brc" description |
.It Sx \&An Ta author name (>0 arguments) |
.It Sx \&An Ta author name (>0 arguments) |
.It Sx \&Lk Ta hyperlink: Ar uri Op Ar name |
.It Sx \&Lk Ta hyperlink: Ar uri Op Ar name |
Line 524 in the alphabetical |
|
Line 522 in the alphabetical |
|
.Bl -column "Brq, Bro, Brc" description |
.Bl -column "Brq, Bro, Brc" description |
.It Sx \&Em Ta italic font or underline (emphasis) (>0 arguments) |
.It Sx \&Em Ta italic font or underline (emphasis) (>0 arguments) |
.It Sx \&Sy Ta boldface font (symbolic) (>0 arguments) |
.It Sx \&Sy Ta boldface font (symbolic) (>0 arguments) |
.It Sx \&Li Ta typewriter font (literal) (>0 arguments) |
|
.It Sx \&No Ta return to roman font (normal) (no arguments) |
.It Sx \&No Ta return to roman font (normal) (no arguments) |
.It Sx \&Bf , \&Ef Ta font block: |
.It Sx \&Bf , \&Ef Ta font block: |
.Op Fl Ar type | Cm \&Em | \&Li | \&Sy |
.Op Fl Ar type | Cm \&Em | \&Li | \&Sy |
|
|
.Ss \&Ao |
.Ss \&Ao |
Begin a block enclosed by angle brackets. |
Begin a block enclosed by angle brackets. |
Does not have any head arguments. |
Does not have any head arguments. |
.Pp |
This macro is almost never useful. |
Examples: |
See |
.Dl \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac |
.Sx \&Aq |
.Pp |
for more details. |
See also |
|
.Sx \&Aq . |
|
.Ss \&Ap |
.Ss \&Ap |
Inserts an apostrophe without any surrounding whitespace. |
Inserts an apostrophe without any surrounding whitespace. |
This is generally used as a grammatical device when referring to the verb |
This is generally used as a grammatical device when referring to the verb |
|
|
.Dl \&.Fn execve \&Ap d |
.Dl \&.Fn execve \&Ap d |
.Ss \&Aq |
.Ss \&Aq |
Encloses its arguments in angle brackets. |
Encloses its arguments in angle brackets. |
|
The only important use case is for email addresses. |
|
See |
|
.Sx \&Mt |
|
for an example. |
.Pp |
.Pp |
Examples: |
Occasionally, it is used for names of characters and keys, for example: |
.Dl \&.Fl -key= \&Ns \&Aq \&Ar val |
.Bd -literal -offset indent |
|
Press the |
|
\&.Aq escape |
|
key to ... |
|
.Ed |
.Pp |
.Pp |
.Em Remarks : |
For URIs, use |
this macro is often abused for rendering URIs, which should instead use |
|
.Sx \&Lk |
.Sx \&Lk |
|
instead, and |
|
.Sx \&In |
|
for |
|
.Dq #include |
|
directives. |
|
Never wrap |
|
.Sx \&Ar |
|
in |
|
.Sx \&Aq . |
|
.Pp |
|
Since |
|
.Sx \&Aq |
|
usually renders with non-ASCII characters in non-ASCII output modes, |
|
do not use it where the ASCII characters |
|
.Sq < |
|
and |
|
.Sq > |
|
are required as syntax elements. |
|
Instead, use these characters directly in such cases, combining them |
|
with the macros |
|
.Sx \&Pf , |
|
.Sx \&Ns , |
or |
or |
.Sx \&Mt , |
.Sx \&Eo |
or to note pre-processor |
as needed. |
.Dq Li #include |
|
statements, which should use |
|
.Sx \&In . |
|
.Pp |
.Pp |
See also |
See also |
.Sx \&Ao . |
.Sx \&Ao . |
|
|
.At . |
.At . |
.It Cm III |
.It Cm III |
.At III . |
.At III . |
.It Cm V[.[1-4]]? |
.It Cm V | V.[1-4] |
A version of |
A version of |
.At V . |
.At V . |
.El |
.El |
|
|
A columnated list. |
A columnated list. |
The |
The |
.Fl width |
.Fl width |
argument has no effect; instead, each argument specifies the width |
argument has no effect; instead, the string length of each argument |
of one column, using either the scaling width syntax described in |
specifies the width of one column. |
.Xr roff 7 |
|
or the string length of the argument. |
|
If the first line of the body of a |
If the first line of the body of a |
.Fl column |
.Fl column |
list is not an |
list is not an |
|
|
.Ar month |
.Ar month |
is the full English month name, the |
is the full English month name, the |
.Ar day |
.Ar day |
is an optionally zero-padded numeral, and the |
is an integer number, and the |
.Ar year |
.Ar year |
is the full four-digit year. |
is the full four-digit year. |
.Pp |
.Pp |
Line 1244 If no date string is given, the current date is used. |
|
Line 1263 If no date string is given, the current date is used. |
|
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Dd $\&Mdocdate$ |
.Dl \&.Dd $\&Mdocdate$ |
.Dl \&.Dd $\&Mdocdate: July 21 2007$ |
.Dl \&.Dd $\&Mdocdate: July 2 2018$ |
.Dl \&.Dd July 21, 2007 |
.Dl \&.Dd July 2, 2018 |
.Pp |
.Pp |
See also |
See also |
.Sx \&Dt |
.Sx \&Dt |
Line 1454 to save the pattern space for subsequent retrieval. |
|
Line 1473 to save the pattern space for subsequent retrieval. |
|
.Ed |
.Ed |
.Pp |
.Pp |
See also |
See also |
.Sx \&Bf , |
|
.Sx \&Li , |
|
.Sx \&No , |
.Sx \&No , |
|
.Sx \&Ql , |
and |
and |
.Sx \&Sy . |
.Sx \&Sy . |
.Ss \&En |
.Ss \&En |
|
|
.Dl \&.Ic alias |
.Dl \&.Ic alias |
.Pp |
.Pp |
Note that using |
Note that using |
.Sx \&Bd Fl literal |
.Sx \&Ql , |
|
.Sx \&Dl , |
or |
or |
.Sx \&D1 |
.Sx \&Bd Fl literal |
is preferred for displaying code; the |
is preferred for displaying code samples; the |
.Sx \&Ic |
.Sx \&Ic |
macro is used when referring to specific instructions. |
macro is used when referring to an individual command name. |
.Ss \&In |
.Ss \&In |
The name of an include file. |
The name of an include file. |
This macro is most often used in section 2, 3, and 9 manual pages. |
This macro is most often used in section 2, 3, and 9 manual pages. |
|
|
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 |
.Sx \&Ta |
.Sx \&Ta |
macro can be used to delimit cells, and |
macro can be used to delimit cells, and portability requires that |
.Sx \&Ta |
.Sx \&Ta |
is only recognised as a macro when called by other macros, |
is called by other macros: some parsers do not recognize it when |
not as the first macro on a line. |
it appears as the first macro on a line. |
.Pp |
.Pp |
Note that quoted strings may span tab-delimited cells on an |
Note that quoted strings may span tab-delimited cells on an |
.Sx \&It |
.Sx \&It |
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 \&.Lb libz |
.Dl \&.Lb libz |
.Dl \&.Lb libmandoc |
.Dl \&.Lb libmandoc |
.Ss \&Li |
.Ss \&Li |
Denotes text that should be in a |
Request a typewriter (literal) font. |
.Li literal |
Deprecated because on terminal output devices, this is usually |
font mode. |
indistinguishable from normal text. |
Note that this is a presentation term and should not be used for |
For literal displays, use |
stylistically decorating technical terms. |
.Sx \&Ql Pq in-line , |
.Pp |
.Sx \&Dl Pq single line , |
On terminal output devices, this is often indistinguishable from |
or |
normal text. |
.Sx \&Bd Fl literal Pq multi-line |
.Pp |
instead. |
See also |
|
.Sx \&Bf , |
|
.Sx \&Em , |
|
.Sx \&No , |
|
and |
|
.Sx \&Sy . |
|
.Ss \&Lk |
.Ss \&Lk |
Format a hyperlink. |
Format a hyperlink. |
Its syntax is as follows: |
Its syntax is as follows: |
|
|
See also |
See also |
.Sx \&Mt . |
.Sx \&Mt . |
.Ss \&Lp |
.Ss \&Lp |
Synonym for |
Deprecated synonym for |
.Sx \&Pp . |
.Sx \&Pp . |
.Ss \&Ms |
.Ss \&Ms |
Display a mathematical symbol. |
Display a mathematical symbol. |
|
|
.Pp |
.Pp |
See also |
See also |
.Sx \&Em , |
.Sx \&Em , |
.Sx \&Li , |
.Sx \&Ql , |
and |
and |
.Sx \&Sy . |
.Sx \&Sy . |
.Ss \&Ns |
.Ss \&Ns |
Line 2212 Close quoted context opened by |
|
Line 2237 Close quoted context opened by |
|
.Sx \&Qo . |
.Sx \&Qo . |
.Ss \&Ql |
.Ss \&Ql |
In-line literal display. |
In-line literal display. |
This can for example be used for complete command invocations and |
This can be used for complete command invocations and for multi-word |
for multi-word code fragments when more specific markup is not |
code examples when an indented display is not desired. |
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 |
.Pp |
See also |
See also |
.Sx \&Dl |
.Sx \&Dl |
Line 2567 The second and last Technical Corrigendum. |
|
Line 2586 The second and last Technical Corrigendum. |
|
.br |
.br |
This standard is also called |
This standard is also called |
X/Open Portability Guide version 7. |
X/Open Portability Guide version 7. |
.Pp |
|
.It \-p1003.1-2013 |
|
.St -p1003.1-2013 |
|
.br |
|
This is the first Technical Corrigendum. |
|
.El |
.El |
.It Other standards |
.It Other standards |
.Pp |
.Pp |
|
|
.Ed |
.Ed |
.Pp |
.Pp |
See also |
See also |
.Sx \&Bf , |
|
.Sx \&Em , |
.Sx \&Em , |
.Sx \&Li , |
.Sx \&No , |
and |
and |
.Sx \&No . |
.Sx \&Ql . |
.Ss \&Ta |
.Ss \&Ta |
Table cell separator in |
Table cell separator in |
.Sx \&Bl Fl column |
.Sx \&Bl Fl column |
Line 2714 Link to another manual |
|
Line 2727 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 |
.Dl \&.Xr mandoc 1 \&; |
.Dl \&.Xr mandoc 1 \&; |
.Dl \&.Xr mandoc 1 \&Ns s behaviour |
.Dl \&.Xr mandoc 1 \&Ns s behaviour |
.Ss \&br |
|
Emits a line-break. |
|
This macro should not be used; it is implemented for compatibility with |
|
historical manuals. |
|
.Pp |
|
Consider using |
|
.Sx \&Pp |
|
in the event of natural paragraph breaks. |
|
.Ss \&sp |
|
Emits vertical space. |
|
This macro should not be used; it is implemented for compatibility with |
|
historical manuals. |
|
Its syntax is as follows: |
|
.Pp |
|
.D1 Pf \. Sx \&sp Op Ar height |
|
.Pp |
|
The |
|
.Ar height |
|
argument is a scaling width as described in |
|
.Xr roff 7 . |
|
If unspecified, |
|
.Sx \&sp |
|
asserts a single vertical space. |
|
.Sh MACRO SYNTAX |
.Sh MACRO SYNTAX |
The syntax of a macro depends on its classification. |
The syntax of a macro depends on its classification. |
In this section, |
In this section, |
Line 3033 then the macro accepts an arbitrary number of argument |
|
Line 3022 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 \&sp Ta \&No Ta \&No Ta 1 |
|
.El |
.El |
.Ss Delimiters |
.Ss Delimiters |
When a macro argument consists of one single input character |
When a macro argument consists of one single input character |
Line 3053 For many macros, when the leading arguments are openin |
|
Line 3040 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 3219 but produces large indentations. |
|
Line 3208 but produces large indentations. |
|
.Xr tbl 7 |
.Xr tbl 7 |
.Pp |
.Pp |
The web page |
The web page |
.Lk http://mdocml.bsd.lv/mdoc/ "extended documentation for the mdoc language" |
.Lk http://mandoc.bsd.lv/mdoc/ "extended documentation for the mdoc language" |
provides a few tutorial-style pages for beginners, an extensive style |
provides a few tutorial-style pages for beginners, an extensive style |
guide for advanced authors, and an alphabetic index helping to choose |
guide for advanced authors, and an alphabetic index helping to choose |
the best macros for various kinds of content. |
the best macros for various kinds of content. |