NAME
appendix/markup
—
choosing the right macro
DESCRIPTION
For the following purposes, the following macros are recommended:
- address:
-
- email address:
Mt
- memory address:
Ad
- postal address:
Bd
-unfilled
- email address:
- angle brackets:
-
- for an email address:
Aq Mt
- for an include file:
In
- otherwise:
Aq
orAo
- for an email address:
- apostrophe:
-
- normally just: ' (ASCII 0x27)
- spacing control:
Ap
- architecture:
-
- machine architecture this manual page applies to:
Dt
- machine architecture this manual page applies to:
- argument:
-
- command line argument or parameter (placeholder):
Ar
- command line argument (to be given verbatim):
Cm
- function argument (optionally including type):
Fa
- command line argument or parameter (placeholder):
- article title:
%T
- AT&T UNIX version:
At
- author name:
-
- outside any
Rs
block:An
- in an
Rs
block:%A
- institutional author (school, government, etc.) in an
Rs
block:%Q
- outside any
- backslash character:
- \e, see “Backslashes” in mandoc_char(7)
- bar character:
- see “Delimiters” in mdoc(7)
- bibliographic block:
Rs
- blank line:
-
- paragraph break:
Pp
- before a display:
Bd
-compact
- before list items:
Bl
-compact
- paragraph break:
- boldface font:
Sy
- book title:
%B
- braces:
-
- curly:
Brq
orBro
- see also: brackets
- curly:
- brackets:
-
- angle brackets:
Aq
orAo
- curly braces:
Brq
orBro
- parentheses:
Pq
orPo
- square brackets (for optional syntax elements):
Op
orOo
- square brackets (otherwise):
Bq
orBo
- input handling on macro lines: see “Delimiters” in mdoc.7
- angle brackets:
- BSD:
-
- BSD CSRG version:
Bx
- BSD/OS version:
Bsx
- DragonFly BSD version:
Dx
- FreeBSD version:
Fx
- NetBSD version:
Nx
- OpenBSD version:
Ox
- BSD CSRG version:
- bullet:
-
- bullet list:
Bl
-bullet
or-dash
- bullet (next item) in a list:
It
- bullet list:
- cell:
-
- next cell in a columnated list:
Ta
- next cell in a table: tbl(7)
- next cell in a columnated list:
- center text:
Bd
-centered
- character:
-
- display a single character:
Sq
- encode special characters in the input file: mandoc_char(7)
- display a single character:
- city:
-
- in an
Rs
block:%C
- otherwise: no markup
- in an
- column:
-
- columnated list:
Bl
-column
- next column in a columnated list:
Ta
- next row in a columnated list:
It
- column in a table: tbl(7)
- columnated list:
- command line:
-
- argument (to be given verbatim):
Cm
(unlessFl
applies) - argument placeholder:
Ar
- example (in-line display):
Ql
- example (indented one-line display):
Dl
- examples (display a block of multiple lines):
Bd -literal
- option (flag):
Fl
- argument (to be given verbatim):
- command name:
-
- documented in this manual page:
Nm
- documented in another manual page:
Xr
- not documented in any manual page:
Sy
- internal to a program or configuration file:
Ic
- documented in this manual page:
- configuration instruction:
-
- in a kernel configuration file:
Cd
- in another configuration file:
Ic
- in a kernel configuration file:
- constant symbol:
-
- error constant:
Er
- otherwise:
Dv
- error constant:
- cross reference:
-
- to a section or subsection of this manual page:
Sx
- to another manual page:
Xr
- to a section or subsection of this manual page:
- curly braces:
Brq
orBro
- dash:
-
- bullet list:
Bl
-dash
- \(en and \(em, see “Dashes and Hyphens” in mandoc_char(7)
- bullet list:
- date:
-
- last update of this manual page:
Dd
- publication date in an
Rs
block:%D
- otherwise: no markup
- last update of this manual page:
- declaration:
-
- of a function:
Ft
and (Fo
orFn
) - of a variable (including type and name):
Va
- in a kernel configuration file:
Cd
- of a function:
- #define (preprocessor):
-
- error constant:
Er
- macro name:
Dv
- complete line (cited in the SYNOPSIS):
Fd
- error constant:
- definition list (tagged list):
Bl
-tag
- delimiters:
-
- see “Delimiters” in mdoc(7)
- see also brackets, quotes, period, and punctuation
- description (topic of this manual page):
Nd
- device name:
-
- absolute or relative path:
Pa
- kernel configuration directive:
Cd
- absolute or relative path:
- diagnostic messages:
-
- list:
Bl
-diag
- list:
- directory name (absolute or relative path):
Pa
- display:
-
- very short, for example a single character:
Sq
- in-line display, default font:
Dq
- in-line display, literal font:
Ql
- single indented line, default font:
D1
- single indented line, literal font:
Dl
- multiple lines:
Bd
- very short, for example a single character:
- DragonFly BSD version:
Dx
- email address:
Mt
- emphasis (contrastive stress in the linguistic sense):
Em
- enclosure:
-
- with arbitrary head and tail:
Eo
- see also brackets and quotes
- with arbitrary head and tail:
- enumeration:
-
- enumeration value (C language):
Dv
- numbered list:
Bl
-enum
- enumeration value (C language):
- environment variable name:
Ev
- equations:
- eqn(7)
- error number (errno) constant:
Er
- escape sequence (e.g. in the roff(7) language):
-
- escape sequence name:
Ic
- escape sequence punctuation (parenthesis or brackets): no markup or
Bq
- escape sequence argument keyword:
Cm
- escape sequence argument placeholder:
Ar
- examples: “.Ic \ef Ns Bq Ar fontname”, “.Ic \ef Ns Cm ( BI”
- escape sequence name:
- escaping:
- example:
-
- in-line display:
Ql
- single indented line (for example a command line):
Dl
- multiple lines (for example of source code):
Bd
-literal
- in-line display:
- exit status
-
- of a command line utility (if following standard conventions):
Ex
-std
- of a library function (if following standard conventions):
Rv
-std
- of a command line utility (if following standard conventions):
- extended item head in a list:
It Xo
- file name (absolute or relative path):
Pa
- fixed width font (typewriter):
-
- for a block of text:
Bd -literal
- for a single line (indented):
Dl
- for an in-line display:
Ql
- for a block of text:
- flag:
-
- command line option:
Fl
- named bit in a bit field:
Dv
- command line option:
- font selection:
-
- boldface:
Sy
- italic:
Em
- back to default (normal, roman) font:
No
- typewriter (fixed width):
Ql
- for a block of text:
Bf
- boldface:
- footer line:
-
- of this manual page:
Dd
,Os
- of this manual page:
- FreeBSD version:
Fx
- function:
-
- argument (optionally including type):
Fa
- declaration:
Ft
and (Fo
orFn
) - library name:
Lb
- name (of a function documented in another manualpage):
Xr
- name (of a function documented in this manual page, only in the NAME
section):
Nm
- name (anywhere else):
Fn
- return type:
Ft
- standard return value:
Rv
-std
- argument (optionally including type):
- header line:
-
- of this manual page:
Dt
- of a section of this manual page:
Sh
- of a subsection of this manual page:
Ss
- of this manual page:
- hyperlink (URI):
-
- in an
Rs
block:%U
- otherwise:
Lk
- in an
- hyphen:
-
- bullet list:
Bl
-hyphen
- see “Dashes and Hyphens” in mandoc_char(7)
- bullet list:
- #include directive:
In
- importance:
-
- important word or sentence (without stress emphasis, no other macro
fits):
Sy
- important word or sentence (without stress emphasis, no other macro
fits):
- indentation:
-
- of displays:
Bd
-offset
- of lists:
Bl
-offset
- of list items:
Bl
-width
- of a single line (default font):
D1
- of a single line (literal font):
Dl
- otherwise:
Bd
-ragged
-offset
- of displays:
- institutional author:
-
- in an
Rs
block:%Q
- otherwise: no markup
- in an
- interactive command name (in a program):
Ic
- internal command name (in a program or configuration file):
Ic
- issue number:
-
- in an
Rs
block (usually for journals):%N
- in an
- italic font:
Em
- item (in a list):
-
- start the next item (item head on one input line):
It
- start the next item (item head spanning more than one input line):
It Xo
- start the next item (item head on one input line):
- journal name:
-
- in an
Rs
block:%J
- otherwise: no markup
- in an
- kernel configuration declaration:
Cd
- library name:
Lb
- line break control:
-
- before author names:
An
- between macros on the same input line:
Bk
-words
- otherwise:
Bd
- manual, physical line break:
br
- before author names:
- line spacing:
-
- before a display:
Bd
-compact
- before list items:
Bl
-compact
- before a display:
- link (to a web page, URI):
Lk
- list:
-
- bullet list:
Bl
-bullet
or-dash
- columnated:
Bl
-column
- numbered:
Bl
-enum
- of diagnostic messages:
Bl
-diag
- other tagged list:
Bl
-tag
,-hang
,-ohang
or-inset
- otherwise:
Bl
-item
- bullet list:
- list item:
-
- header is empty or on a single input line:
It
- header spans multiple input lines:
It Xo
- header is empty or on a single input line:
- literal display:
-
- multiple lines (for example of source code):
Bd
-literal
- single indented line (for example a command line):
Dl
- in-line display:
Ql
- multiple lines (for example of source code):
- machine architecture:
-
- machine architecture this manual page applies to:
Dt
- machine architecture this manual page applies to:
- macro name:
-
- preprocessor #define:
Dv
- used like a library function:
Fn
- in a scripting language or configuration file:
Ic
- preprocessor #define:
- mail address:
-
- electronic:
Mt
- postal:
Bd
-unfilled
- electronic:
- mathematical symbol:
Ms
- messages:
-
- list of diagnostic messages:
Bl
-diag
- list of diagnostic messages:
- minus sign:
- \-, see “Dashes and Hyphens” in mandoc_char(7)
- NetBSD version:
Nx
- normal font (default font, roman font):
No
- null:
-
- null character: NUL, NUL-terminated (without any markup)
- null pointer:
Dv
NULL
- the integer zero: 0 (without any markup)
- numbered list:
Bl
-enum
- OpenBSD version:
Ox
- operating system version:
-
- for the manual page footer:
Os
- to reference another system: see AT&T and BSD
- for the manual page footer:
- option (flag to be given on the command line):
Fl
- optional syntax element:
Op
- page number:
-
- in an
Rs
block:%P
- otherwise: no markup
- in an
- paragraph break:
Pp
- parameter:
-
- command line argument (placeholder):
Ar
- function argument or parameter:
Fa
- command line argument (placeholder):
- parentheses:
-
- enclosing output in parentheses:
Pq
orPo
- input handling on macro lines: see “Delimiters” in mdoc.7
- enclosing output in parentheses:
- path name (of a file or directory):
Pa
- period:
-
- showing periods in the output: see “Periods” in mandoc_char(7)
- to mark request and macro lines: see the DESCRIPTION section in mdoc(7) and roff(7)
- input handling on macro lines: see “Delimiters” in mdoc.7
- placeholder:
-
- for a syntax element:
Ar
- for something that is not a syntax element:
Em
- for a syntax element:
- prefix:
-
- dash for command line options:
Fl
- otherwise, for spacing control:
Pf
- dash for command line options:
- preprocessor:
-
- error constant:
Er
- other macro name (#define'd constant):
Dv
- file inclusion directive (#include):
In
- complete preprocessor directive line (not for #include):
Fd
- error constant:
- program name:
-
- documented in this manual page:
Nm
- documented in another manual page:
Xr
- not documented in any manual page:
Sy
- documented in this manual page:
- publisher:
-
- in an
Rs
block:%I
- otherwise: no markup
- in an
- punctuation:
-
- input: see “Delimiters” in mdoc.7
- output: see the DESCRIPTION section in mandoc_char(7)
- quotes:
-
- enclose string in double quotes:
Dq
orDo
- enclose string in typewriter-style double quotes:
Qq
orQo
- enclose string in single quotes:
Sq
orSo
- quoting of macro arguments: see the MACRO SYNTAX section in roff(7)
- see also “Quotes” in mandoc_char(7)
- enclose string in double quotes:
- reference:
-
- to a section or subsection of this manual page:
Sx
- to another manual page:
Xr
- to a standard document or specification:
St
- to a book or journal:
Rs
- to a URI (hyperlink):
Lk
- to a section or subsection of this manual page:
- report name:
-
- in an
Rs
block:%R
- otherwise: no markup
- in an
- return:
-
- return type (of a function):
Ft
- standard return value (of a function):
Rv
-std
- exit status (of a command line utility):
Ex
-std
- return type (of a function):
- roman font (default font, normal font):
No
- row:
-
- in a columnated list:
It
- in a table: tbl(7)
- in a columnated list:
- section:
-
- section number of this manual page:
Dt
- main section header of this manual page:
Sh
- subsection header of this manual page:
Ss
- cross reference to a section or subsection of this manual page:
Sx
- section number in a cross reference to another manual page:
Xr
- section number of this manual page:
- source code example:
-
- multiple lines:
Bd
-literal
- single line indented display:
Dl
- in-line display:
Ql
- multiple lines:
- spacing control:
-
- on text lines (horizontal): see “Spaces” in mandoc_char(7)
- at the end of a sentence: see “Sentence Spacing” in roff(7)
- near an apostrophe on a macro line (horizontal):
Ap
- otherwise on a macro line (horizontal):
Ns
,Sm
,Pf
- before a display (vertical):
Bd
-compact
- before list items (vertical):
Bl
-compact
- paragraph break (vertical):
Pp
- square brackets:
-
- for optional syntax elements:
Op
orOo
- otherwise:
Bq
orBo
- input handling on macro lines: see “Delimiters” in mdoc.7
- for optional syntax elements:
- standard:
-
- reference to a standard document or specification:
St
- exit status of a command line utility:
Ex
- return value of a library function:
Rv
- reference to a standard document or specification:
- stress (in the linguistic sense, emphasis):
Em
- struct:
-
- struct name (as a function argument type):
Fa
- struct name (as a function return type):
Ft
- struct name (otherwise):
Vt
- struct field name:
Fa
- struct name (as a function argument type):
- subsection:
-
- header:
Ss
- cross reference to a section or subsection:
Sx
- header:
- symbol (mathematical):
Ms
- syntax element to be used verbatim (no semantic macro fits):
Sy
- sysctl variable name:
Va
- tables:
-
- simple, more portable representation:
Bl -column
- more powerful, less portable representation: tbl(7)
- simple, more portable representation:
- tag:
-
- tagged list (definition list):
Bl
-tag
- tag (next item) in a list (head on one input line):
It
- tag (next item) in a list (head spanning more than one input line):
It Xo
- tagged list (definition list):
- technical report name:
-
- in an
Rs
block:%R
- otherwise: no markup
- in an
- technical term:
-
- syntax element, no semantic macro fits:
Sy
- not a syntax element:
Em
- syntax element, no semantic macro fits:
- title:
-
- of this manual page:
Dt
,Nd
- of a section of this manual page:
Sh
- of a subsection of this manual page:
Ss
- of a book:
%B
- of an article (for example in a journal):
%T
- of this manual page:
- topic (one-line description of this manual page):
Nd
- type:
-
- function return type:
Ft
- variable type:
Vt
- function return type:
- typewriter font (fixed width):
-
- for a block of text:
Bd -literal
- for a single line (indented):
Dl
- for an in-line display:
Ql
- for a block of text:
- underline:
Em
- unicode:
-
- input: see the UNICODE CHARACTERS section in mandoc_char(7)
- output: see “Output Formats” in mandoc(1)
- uniform resource identifier (URI, hyperlink):
-
- in an
Rs
block:%U
- otherwise:
Lk
- in an
- UNIX version:
-
- AT&T:
At
- Berkeley:
Bx
- AT&T:
- utility name:
-
- documented in this manual page:
Nm
- documented in another manual page:
Xr
- not documented in any manual page:
Sy
- documented in this manual page:
- variable:
-
- declaration (type and name):
Va
- function argument:
Fa
- name (environment variable):
Ev
- name (other variable):
Va
- type (without name):
Vt
- declaration (type and name):
- version:
-
- of the operating system for the page footer:
Os
- to reference another system: see AT&T and BSD
- of the operating system for the page footer:
- vertical bar character:
- see “Delimiters” in mdoc(7)
- volume number:
-
- in an
Rs
block:%V
- otherwise: no markup
- in an
- web page (hyperlink, URI):
Lk
SEE ALSO
The MACRO OVERVIEW and MACRO REFERENCE sections in the mdoc(7) manual.