Special Character Substitutions

The special characters substitution step searches for three characters (<, >, &) and replaces them with their named character references.

  • The less than symbol, <, is replaced with the named character reference &lt;.

  • The greater than symbol, >, is replaced with the named character reference &gt;.

  • An ampersand, &, is replaced with the named character reference &amp;.

Default special characters substitution

Table 1 lists the specific blocks and inline elements the special characters substitution step applies to automatically.

Table 1. Blocks and inline elements subject to the special characters substitution
Blocks and elements Substitution step applied by default

Attribute entry values

Yes

Comments

No

Examples

Yes

Headers

Yes

Literal, listings, and source

Yes

Macros

Yes
(except triple plus and inline pass macros)

Open

Yes

Paragraphs

Yes

Passthrough blocks

No

Quotes and verses

Yes

Sidebars

Yes

Tables

Yes

Titles

Yes

specialchars substitution value

The special characters substitution step can be modified on blocks and inline elements. For blocks, the step’s name, specialchars, can be assigned to the subs attribute. For inline elements, the built-in values c or specialchars can be applied to inline text to add the special characters substitution step.

Special character substitution precedes attribute substitution, so you need to manually escape any attributes containing special characters that you set in the CLI or API. For example, on the command line, type -a toc-title="Sections, Tables \&amp; Figures" instead of -a toc-title="Sections, Tables & Figures".