MARKUP(MDOC) MDOC MARKUP(MDOC)

NAME

appendix/markupchoosing the right macro

DESCRIPTION

For the following purposes, the following macros are recommended:
address:
  • email address: Mt
  • memory address: Ad
  • postal address: Bd -unfilled
angle brackets:
  • for an email address: Aq Mt
  • for an include file: In
  • otherwise: Aq or Ao
apostrophe:
  • normally just: ' (ASCII 0x27)
  • spacing control: Ap
architecture:
  • machine architecture this manual page applies to: Dt
argument:
  • command line argument or parameter (placeholder): Ar
  • command line argument (to be given verbatim): Cm
  • function argument (optionally including type): Fa
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
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
boldface font:
Sy
book title:
%B
braces:
  • curly: Brq or Bro
  • see also: brackets
brackets:
  • angle brackets: Aq or Ao
  • curly braces: Brq or Bro
  • parentheses: Pq or Po
  • square brackets (for optional syntax elements): Op or Oo
  • square brackets (otherwise): Bq or Bo
  • input handling on macro lines: see “Delimiters” in mdoc.7
BSD:
  • BSD CSRG version: Bx
  • BSD/OS version: Bsx
  • DragonFly BSD version: Dx
  • FreeBSD version: Fx
  • NetBSD version: Nx
  • OpenBSD version: Ox
bullet:
  • bullet list: Bl -bullet or -dash
  • bullet (next item) in a list: It
cell:
  • next cell in a columnated list: Ta
  • next cell in a table: tbl(7)
center text:
Bd -centered
character:
  • display a single character: Sq
  • encode special characters in the input file: mandoc_char(7)
city:
  • in an Rs block: %C
  • otherwise: no markup
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)
command line:
  • argument (to be given verbatim): Cm (unless Fl 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
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
configuration instruction:
  • in a kernel configuration file: Cd
  • in another configuration file: Ic
constant symbol:
  • error constant: Er
  • otherwise: Dv
cross reference:
  • to a section or subsection of this manual page: Sx
  • to another manual page: Xr
curly braces:
Brq or Bro
dash:
  • bullet list: Bl -dash
  • \(en and \(em, see “Dashes and Hyphens” in mandoc_char(7)
date:
  • last update of this manual page: Dd
  • publication date in an Rs block: %D
  • otherwise: no markup
declaration:
  • of a function: Ft and (Fo or Fn)
  • of a variable (including type and name): Va
  • in a kernel configuration file: Cd
#define (preprocessor):
  • error constant: Er
  • macro name: Dv
  • complete line (cited in the SYNOPSIS): Fd
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
diagnostic messages:
  • list: Bl -diag
directory name (absolute or relative path):
Pa
display:
  • single character: Sq
  • in-line literal display: Ql
  • single indented line, default font: D1
  • single indented line, literal font: Dl
  • multiple lines: Bd
DragonFly BSD version:
Dx
email address:
Mt
emphasis (contrastive stess in the linguistic sense):
Em
enclosure:
  • with arbitrary head and tail: Eo
  • see also brackets and quotes
enumeration:
  • enumeration value (C language): Dv
  • numbered list: Bl -enum
environment variable name:
Ev
equations:
eqn(7)
error number (errno) constant:
Er
escaping:
  • of callable macros: see “MACRO SYNTAX” in mdoc(7)
  • of delimiters: see “Delimiters” in mdoc(7)
  • of space characters in macro arguments: see “Whitespace” in roff(7)
example:
  • in-line literal display: Ql
  • single indented line (for example a command line): Dl
  • multiple lines (for example of source code): Bd -literal
exit status
  • of a command line utility (if following standard conventions): Ex -std
  • of a library function (if following standard conventions): Rv -std
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
  • in-line literal display: Ql
  • otherwise (purely physical markup): Li
flag:
  • command line option: Fl
  • named bit in a bit field: Dv
font selection:
  • boldface: Sy
  • italic: Em
  • typewriter (fixed width): Li
  • back to default (normal, roman) font: No
  • for a block of text: Bf
footer line:
  • of this manual page: Dd, Os
FreeBSD version:
Fx
function:
  • argument (optionally including type): Fa
  • declaration: Ft and (Fo or Fn)
  • 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
header line:
  • of this manual page: Dt
  • of a section of this manual page: Sh
  • of a subsection of this manual page: Ss
hyperlink (URI):
  • in an Rs block: %U
  • otherwise: Lk
hyphen:
  • bullet list: Bl -hyphen
  • see “Dashes and Hyphens” in mandoc_char(7)
#include directive:
In
importance:
  • important word or sentence (without stress emphasis, no other macro fits): Sy
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
institutional author:
  • in an Rs block: %Q
  • otherwise: no markup
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
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
journal name:
  • in an Rs block: %J
  • otherwise: no markup
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
line spacing:
  • before a display: Bd -compact
  • before list items: Bl -compact
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
list item:
  • header is empty or on a single input line: It
  • header spans multiple input lines: It Xo
literal display:
  • multiple lines (for example of source code): Bd -literal
  • single indented line (for example a command line): Dl
  • in-line literal display: Ql
  • literal font (physical markup): Li
machine architecture:
  • machine architecture this manual page applies to: Dt
macro name:
  • preprocessor #define: Dv
  • used like a library function: Fn
  • in a scripting language or configuration file: Ic
mail address:
  • electronic: Mt
  • postal: Bd -unfilled
mathematical symbol:
Ms
messages:
  • list of diagnostic messages: Bl -diag
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
option (flag to be given on the command line):
Fl
optional syntax element:
Op
page number:
  • in an Rs block: %P
  • otherwise: no markup
paragraph break:
Pp
parameter:
  • command line argument (placeholder): Ar
  • function argument or parameter: Fa
parentheses:
  • enclosing output in parentheses: Pq or Po
  • input handling on macro lines: see “Delimiters” in mdoc.7
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
prefix:
  • dash for command line options: Fl
  • otherwise, for spacing control: Pf
preprocessor:
  • error constant: Er
  • other macro name (#define'd constant): Dv
  • file inclusion directive (#include): In
  • complete preprocessor directive line (not for #include): Fd
program name:
  • documented in this manual page: Nm
  • documented in another manual page: Xr
  • not documented in any manual page: Sy
publisher:
  • in an Rs block: %I
  • otherwise: no markup
punctuation:
quotes:
  • enclose string in double quotes: Dq or Do
  • enclose string in typewriter-style double quotes: Qq or Qo
  • enclose string in single quotes: Sq or So
  • quoting of macro arguments: see the MACRO SYNTAX section in roff(7)
  • see also “Quotes” in mandoc_char(7)
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
report name:
  • in an Rs block: %R
  • otherwise: no markup
return:
  • return type (of a function): Ft
  • standard return value (of a function): Rv -std
  • exit status (of a command line utility): Ex -std
roman font (default font, normal font):
No
row:
  • in a columnated list: It
  • in a table: tbl(7)
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
source code example:
  • multiple lines: Bd -literal
  • single line indented display: Dl
  • in-line display: Ql
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 or Oo
  • otherwise: Bq or Bo
  • input handling on macro lines: see “Delimiters” in mdoc.7
standard:
  • reference to a standard document or specification: St
  • exit status of a command line utility: Ex
  • return value of a library function: Rv
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
subsection:
  • header: Ss
  • cross reference to a section or subsection: Sx
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)
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
technical report name:
  • in an Rs block: %R
  • otherwise: no markup
technical term:
  • syntax element, no semantic macro fits: Sy
  • not a syntax element: Em
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
topic (one-line description of this manual page):
Nd
type:
  • function return type: Ft
  • variable type: Vt
typewriter font (fixed width):
  • for a block of text: Bd -literal
  • for a single line (indented): Dl
  • in-line literal display: Ql
  • otherwise (purely physical markup): Li
underline:
Em
unicode:
uniform resource identifier (URI, hyperlink):
  • in an Rs block: %U
  • otherwise: Lk
UNIX version:
  • AT&T: At
  • Berkeley: Bx
utility name:
  • documented in this manual page: Nm
  • documented in another manual page: Xr
  • not documented in any manual page: Sy
variable:
  • declaration (type and name): Va
  • function argument: Fa
  • name (environment variable): Ev
  • name (other variable): Va
  • type (without name): Vt
version:
  • of the operating system for the page footer: Os
  • to reference another system: see AT&T and BSD
vertical bar character:
see “Delimiters” in mdoc(7)
volume number:
  • in an Rs block: %V
  • otherwise: no markup
web page (hyperlink, URI):
Lk

SEE ALSO

The MACRO OVERVIEW and MACRO REFERENCE sections in the mdoc(7) manual.
January 2, 2015 bsd.lv