ESCAPING(MDOC) MDOC ESCAPING(MDOC)

NAME

intro/escapingescaping characters in mdoc source files

DESCRIPTION

In mdoc(7) source files, characters need to be escaped in the following situations:
backslashes
To output a backslash, use the escape sequence ‘\e’. Never use the escape sequence ‘\\’ in any context.
dots and apostrophes at the beginning of text lines
If a text input line needs to begin with a dot (‘.’) or apostrophe (‘'’), prepend a zero-width space (‘\&’) to prevent the line from being mistaken for a macro line. Never use the escape sequence ‘\.’ in any context.
blank characters at the beginning of text lines
If a text input line needs to begin with a blank character (‘ ’) and no line break is desired before that line, prepend a zero-width space (‘\&’).
non-breaking spaces
To prevent an output line break between two particular words on a text input line, prepend the blank character between the two words with a backslash, forming the escape sequence ‘’ (unpaddable non-breaking space). See the “Spaces” subsection of the mandoc_char(7) manual for details.
macro names as macro arguments
If the name of another mdoc(7) macro occurs as an argument on an mdoc(7) macro line, the former macro is called, and any remaining arguments are passed to it. To prevent this call and instead render the name of the former macro literally, prepend the name with a zero-width space (‘\&’). See the MACRO SYNTAX section of the mdoc(7) manual for details.
blanks in macro arguments
If a macro argument needs to contain a blank character, enclose the whole argument in double quotes. For example, this often occurs with Fa macros. See the MACRO SYNTAX in the roff(7) manual for details.
double quotes in macro arguments
If a macro argument needs to contain a double quote character, write it as “\(dq”. No escaping is needed on text input lines.
isolated delimiters on macro lines
In the rare case that a macro argument consists of one single character that is a delimiter but should not be treated as a delimiter, escape it by prepending a zero-width space (‘\&’). This is not needed if the argument already contains more than just one single character. See the “Delimiters” subsection of the mdoc(7) manual for details.
It is important to not escape the following characters by prepending a backslash because that would prevent them from being printed properly:
exclamation mark
The escape sequence ‘\!’ is intended for preventing interpretation of requests, macros, and escapes when read into a diversion. It is not implemented in mandoc(1), and some formatters don't print the exclamation mark.
double quote
Regardless of context, the escape sequence ‘\"’ introduces a comment. No quote is printed, and the rest of the input line is discarded.
percent
The escape sequence ‘\%’ indicates that hyphenation is allowed at this place; no percent sign is printed.
ampersand
The escape sequence ‘\&’ inserts a zero-width space; no ampersand is printed.
comma
The escape sequence ‘\,’ inserts a left italic correction and is ignored by mandoc(1); no comma is printed.
slash
The escape sequence ‘\/’ inserts a right italic correction and is ignored by mandoc(1); no slash is printed.
caret
The escape sequence ‘\^’ inserts a one-twelfth em half-narrow space character, effectively zero-width in mandoc(1). No caret is printed.
vertical bar
The escape sequence ‘\|’ inserts a one-sixth em narrow space character, effectively zero-width in mandoc(1). No vertical bar is printed.
tilda
The escape sequence ‘\~’ inserts a paddable non-breaking space character; no tilda is printed.
September 4, 2015 bsd.lv