MARKUP(MDOC)

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

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:

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

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

enumeration:

enumeration value (C language): Dv
numbered list: Bl -enum

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”

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 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
for an in-line display: Ql

flag:

command line option: Fl
named bit in a bit field: Dv

font selection:

boldface: Sy
italic: Em
back to default (normal, roman) font: No
typewriter (fixed width): Ql
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 display: Ql

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:

input: see “Delimiters” in mdoc.7
output: see the DESCRIPTION section in mandoc_char(7)

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
for an in-line display: Ql

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

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

NAME

DESCRIPTION

SEE ALSO