Manual Pages  — ROFF

Input lines beginning with the control character 'amp;.' are parsed for requests and macros. Such lines are called "request lines" or "macro lines", respectively. Requests change the processing state and manipulate the formatting; some macros also define the document structure and produce formatted output. The single quote ("aq") is accepted as an alternative control character, treated by mandoc(1) just like ‘amp;.’

Lines not beginning with control characters are called "text lines". They provide free-form text to be printed; the formatting of the text depends on the respective processing context.

See mandoc_char(7) for a complete list.

The following fonts are supported:

B	Bold font.
BI	A font that is both bold and italic.
CB	Bold constant width font. Same as B in terminal output.
CI	Italic constant width font. Same as I in terminal output.
CR	Regular constant width font. Same as R in terminal output.
CW	An alias for CR.
I	Italic font.
P	Return to the previous font. If a macro caused a font change since the last \f eascape sequence or amp;ft request, this returns to the font before the last font change in the macro rather than to the font before the last manual font change.
R	Roman font. This is the default font.
1	An alias for R.
2	An alias for I.
3	An alias for B.
4	An alias for BI.

Examples:

\fBbold\fR	Write in bold, then switch to regular font mode.
\fIitalic\fP
	Write in italic, then return to previous font mode.
\f(BIbold italic\fP
	Write in bold italic, then return to previous font mode.

To be recognised as the beginning of a quoted argument, the opening quote character must be preceded by a space character. A quoted argument extends to the next double quote character that is not part of a pair, or to the end of the input line, whichever comes earlier. Leaving out the terminating double quote character at the end of the line is discouraged. For clarity, if more arguments follow on the same input line, it is recommended to follow the terminating double quote character by a space character; in case the next character after the terminating double quote character is anything else, it is regarded as the beginning of the next, unquoted argument.

Both in quoted and unquoted arguments, pairs of backslashes ('\\') resolve to single backslashes. In unquoted arguments, space characters can alternatively be included by preceding them with a backslash ('\ '), but quoting is usually better for clarity.

Examples:

.Fn strlen dqconst char *sdq
	Group arguments "const char *s" into one function argument. If unspecified, "const", "char", and "*s" would be considered separate arguments.
.Op dqFl adq
	Consider "amp;Fl a" as literal text instead of a flag macro.

A backslash followed by any character not listed here simply prints that character itself.

\<newline>
	A backslash at the end of an input line can be used to continue the logical input line on the next physical input line, joining the text on both lines together as if it were on a single input line.
\<space>
	The escape sequence backslash-space ('\ amp;') is an unpaddable space-sized non-breaking space character; see Whitespace and mandoc_char(7).
\!	Embed text up to and including the end of the input line into the current diversion or into intermediate output without interpreting requests, macros, and escapes. Currently unsupported.
\dq	The rest of the input line is treated as Comments.
\#	Line continuation with comment. Discard the rest of the physical input line and continue the logical input line on the next physical input line, joining the text on both lines together as if it were on a single input line. This is a groff extension.
\$arg	Macro argument expansion, see amp;de.
\%	Hyphenation allowed at this point of the word; ignored by mandoc(1).
\&	Non-printing zero-width character, often used for various kinds of escaping; see Whitespace, mandoc_char(7), and the "MACRO SYNTAX" and "Delimiters" sections in mdoc(7).
\aq	Acute accent special character; use \(aa instead.
\(cc	Special Characters with two-letter names, see mandoc_char(7).
\)	Zero-width space transparent to end-of-sentence detection; ignored by mandoc(1).
\*[name amp;]
	Interpolate the string with the name. For short names, there are variants \*c and \*(cc. One string is predefined on the roff language level: \*(.T expands to the name of the output device, for example ascii, utf8, ps, pdf, html, or markdown. Macro sets traditionally predefine additional strings which are not portable and differ across implementations. Those supported by mandoc(1) are listed in mandoc_char(7). Strings can be defined, changed, and deleted with the amp;ds, amp;as, and amp;rm requests.
\,	Left italic correction (groff extension); ignored by mandoc(1).
\-	Special character "mathematical minus sign"; see mandoc_char(7) for details.
\/	Right italic correction (groff extension); ignored by mandoc(1).
\:	Breaking the line is allowed at this point of the word without inserting a hyphen.
\?	Embed the text up to the next \? into the current diversion without interpreting requests, macros, and escapes. This is a groff extension and currently unsupported.
\[name amp;]
	Special Characters with names of arbitrary length, see mandoc_char(7).
\^	One-twelfth em half-narrow space character, effectively zero-width in mandoc(1).
\_	Underline special character; use \(ul instead.
\`	Grave accent special character; use \(ga instead.
\{	Begin conditional input; see amp;if.
\&#175;
	One-sixth em narrow space character, effectively zero-width in mandoc(1).
\}	End conditional input; see amp;if.
\~	Paddable non-breaking space character.
\0	Digit width space character.
\Aaqstring aq
	Anchor definition; ignored by mandoc(1).
\a	Leader character; ignored by mandoc(1).
\Baqstring aq
	Interpolate '1' if string conforms to the syntax of Numerical expressions explained above or '0' otherwise.
\baqstring aq
	Bracket building function; ignored by mandoc(1).
\Caqname aq
	Special Characters with names of arbitrary length.
\c	When encountered at the end of an input text line, the next input text line is considered to continue that line, even if there are request or macro lines in between. No whitespace is inserted.
\Daqstring aq
	Draw graphics function; ignored by mandoc(1).
\d	Move down by half a line; ignored by mandoc(1).
\E	Escape character intended to not be interpreted in copy mode. In mandoc(1), it currently does the same as \ itself.
\e	Backslash special character.
\F[name amp;]
	Switch font family (groff extension); ignored by mandoc(1). For short names, there are variants \Fc and \F(cc.
\f[name amp;]
	Switch to the font name, see Font Selection. For short names, there are variants \fc and \f(cc. An empty name \f[] defaults to \fP.
\g[name amp;]
	Interpolate the format of a number register; ignored by mandoc(1). For short names, there are variants \gc and \g(cc.
\Haq[+|- ]number aq
	Set the height of the current font; ignored by mandoc(1).
\haq[ amp;| ]width aq
	Horizontal motion. If the vertical bar is given, the motion is relative to the current indentation. Otherwise, it is relative to the current position. The default scaling unit is m.
\k[name amp;]
	Mark horizontal input place in register; ignored by mandoc(1). For short names, there are variants \kc and \k(cc.
\Laqnumber[c ] aq
	Vertical line drawing function; ignored by mandoc(1).
\laqwidth[c ] aq
	Draw a horizontal line of width using the glyph c.
\M[name amp;]
	Set fill (background) color (groff extension); ignored by mandoc(1). For short names, there are variants \Mc and \M(cc.
\m[name amp;]
	Set glyph drawing color (groff extension); ignored by mandoc(1). For short names, there are variants \mc and \m(cc.
\Naqnumber aq
	Character number on the current font.
\n[+|- ] amp;[name amp;]
	Interpolate the number register name. For short names, there are variants \nc and \n(cc. If the optional sign is specified, the register is first incremented or decremented by the stepsize that was specified in the relevant amp;nr request, and the changed value is interpolated.
\Odigit , \O[5arguments amp;]
	Suppress output. This is a groff extension and currently unsupported. With an argument of 1, 2, 3, or 4, it is ignored.
\oaqstring aq
	Overstrike, writing all the characters contained in the string to the same output position. In terminal and HTML output modes, only the last one of the characters is visible.
\p	Break the output line at the end of the current word.
\Raqname [+|- ]number aq
	Set number register; ignored by mandoc(1).
\r	Move up by one line; ignored by mandoc(1).
\Saqnumber aq
	Slant output; ignored by mandoc(1).
\saq[+|- ]number aq
	Change point size; ignored by mandoc(1). Alternative forms \s[+|- ]n, \s[+|- ] aqnumber aq, \s[[+|- ]number amp;], and \s[+|- ] amp;[number amp;] are also parsed and ignored.
\t	Horizontal tab; ignored by mandoc(1).
\u	Move up by half a line; ignored by mandoc(1).
\V[name amp;]
	Interpolate an environment variable; ignored by mandoc(1). For short names, there are variants \Vc and \V(cc.
\vaqnumber aq
	Vertical motion; ignored by mandoc(1).
\waqstring aq
	Interpolate the width of the string. The mandoc(1) implementation assumes that after expansion of user-defined strings, the string only contains normal characters, no escape sequences, and that each character has a width of 24 basic units.
\Xaqstring aq
	Output string as device control function; ignored in nroff mode and by mandoc(1).
\xaqnumber aq
	Extra line space function; ignored by mandoc(1).
\Y[name amp;]
	Output a string as a device control function; ignored in nroff mode and by mandoc(1). For short names, there are variants \Yc and \Y(cc.
\Zaqstring aq
	Print string with zero width and height; ignored by mandoc(1).
\z	Output the next character without advancing the cursor position.

	For security reasons, mandoc(1) never reads or writes external files except via amp;so requests with safe relative paths.
	There is no automatic hyphenation, no adjustment to the right margin, and very limited support for centering; the output is always set flush-left.
	Support for setting tabulator and leader characters is missing, and support for manually changing indentation is limited.
	The 'u' scaling unit is the default terminal unit. In traditional troff systems, this unit changes depending on the output media.
	Width measurements are implemented in a crude way and often yield wrong results. Support for explicit movement requests and escapes is limited.
	There is no concept of output pages, no support for floats, graphics drawing, and picture inclusion; terminal output is always continuous.
	Requests regarding color, font families, font sizes, and glyph manipulation are ignored. Font support is very limited. Kerning is not implemented, and no ligatures are produced.
	The "aq" macro control character does not suppress output line breaks.
	Diversions and environments are not implemented, and support for traps is very incomplete.
	Use of macros is not supported inside tbl(7) code.

The special semantics of the nS number register is an idiosyncrasy of OpenBSD manuals and not supported by other mdoc(7) implementations.

Joseph F. Ossanna, Brian W. Kernighan, 54, AT&T Bell Laboratories, Computing Science Technical Report, Troff User's Manual, 1976 and 1992.

Joseph F. Ossanna, Brian W. Kernighan, Gunnar Ritter, Heirloom Documentation Tools Nroff/Troff User's Manual, September 17, 2007.