//// Included in: - user-manual: Text Substitutions: Replacements //// The replacements substitution processes textual characters such as marks, arrows and dashes and replaces them with the decimal format of their Unicode code point, i.e. their <>. // Table of Textual symbol replacements is inserted below include::subs-symbol-repl.adoc[] WARNING: The `replacements` element depends on the substitutions completed by the `specialcharacters` element. This is important to keep in mind when applying custom substitutions to a block. See the section about <> for more information. The replacements substitution also recognizes {uri-xml}[HTML and XML character references] as well as {uri-unicode}[decimal and hexadecimal Unicode code points] and substitutes them for their corresponding decimal form Unicode code point. For example, to produce the `§` symbol you could write `\§`, `\§`, or `\§`. When the document is processed, `replacements` will replace the section symbol reference, regardless of whether it is a named character reference or a numeric character reference, with `\§`. In turn, `\§` will display as `§`. [#char-ref-sidebar] .Anatomy of a character reference **** A character reference is a standard sequence of characters that is substituted for a single character when Asciidoctor processes a document. There are two types of character references: named character references and numeric character references. A named character reference (often called a _character entity reference_) is a short name that refers to a character (i.e., glyph). To make the reference, the name must be prefixed with an ampersand (`&`) and end with a semicolon (`;`). For example: * `\†` displays as † * `\€` displays as € * `\◊` displays as ◊ Numeric character references are the decimal or hexadecimal Universal Character Set/Unicode code points which refer to a character. * The decimal code point references are prefixed with an ampersand (`&`), followed by a hash (`#`), and end with a semicolon (`;`). * Hexadecimal code point references are prefixed with an ampersand (`&`), followed by a hash (`#`), followed by a lowercase `x`, and end with a semicolon (`;`). For example: * `\†` or `\†` displays as † * `\€` or `\€` displays as € * `\◊` or `\◊` displays as ◊ Developers may be more familiar with using *Unicode escape sequences* to perform text substitutions. For example, to produce an `@` sign using a Unicode escape sequence, you would prefix the hexadecimal Unicode code point with a backslash (`\`) and an uppercase or lowercase `u`, i.e. `u0040`. However, Asciidoctor doesn't process and replace Unicode escape sequences at this time. **** TIP: Asciidoctor also provides numerous built-in attributes for representing characters and symbols. These attributes and their corresponding output are listed in <>. The replacements substitution occurs within title, paragraph, example, quote, sidebar, and verse blocks. .Elements subject to replacements text substitution [width="40%", cols="3,^2"] |=== |Element | `replacements` substitution |Attribute Entry Value |{n} |Comment |{n} |Example |{y} |Fenced |{n} |Header |{n} |Literal |{n} |Listing |{n} |Macro |{y} |Open |Varies |Paragraph |{y} |Passthrough |{n} |Quote |{y} |Sidebar |{y} |Source |{n} |Special sections |{y} |Table |Varies |Title |{y} |Verse |{y} |===