NAME

intro/escaping —

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.