//// Included in: - user-manual: Text Substitutions: Applying substitutions //// Specific substitution elements can be applied to any block or paragraph by setting the `subs` attribute. The `subs` attribute can be assigned a comma separated list of the following substitution elements and groups. // tag::group[] [horizontal] `none`:: Disables substitutions `normal`:: Performs all substitutions except for callouts `verbatim`:: Replaces special characters and processes callouts `specialchars`, `specialcharacters`:: Replaces `<`, `>`, and `&` with their corresponding entities `quotes`:: Applies text formatting `attributes`:: Replaces attribute references `replacements`:: Substitutes textual and character reference replacements `macros`:: Processes macros `post_replacements`:: Replaces the line break character (`{plus}`) // end::group[] Let's look at an example where you only want to process special characters, formatting markup, and callouts in a literal block. By default, literal blocks are only subject to special characters substitution. But you can change this behavior by setting the `subs` attribute in the block's attribute list. .... include::ex-subs.adoc[tag=subs-in] .... <1> The subs attribute is set in the attribute list and assigned the `verbatim` and `quotes` values. <2> The formatting markup in this line will be replaced when the quotes substitution runs. ==== include::ex-subs.adoc[tag=subs-out] ==== <1> The `verbatim` value enables the callouts to be processed. <2> The `quotes` value enables the text formatting to be processed. [TIP] ==== If you are applying the same set of substitutions to numerous blocks, you should consider making them an attribute entry to ensure consistency. [source] .... include::ex-subs.adoc[tag=subs-attr] .... Another way to ensure consistency and keep your documents clean and simple is to use the <>. ==== === Incremental Substitutions When you set the subs attribute on a block, you automatically remove all of its default substitutions. For example, if you set subs on a literal block, and assign it a value of `attributes`, only attributes are substituted. The verbatim substitution will not be applied. To remedy this situation, Asciidoctor provides a syntax to append or remove substitutions instead of replacing them outright. You can add or remove a substitution from the default substitution list using the plus (`+`) and minus (`-`) modifiers. These are known as [.term]_incremental substitutions_. [horizontal] `+`:: Prepends the substitution to the default list. `+`:: Appends the substitution to the default list. `-`:: Removes the substitution from the default list. For example, you can add the `attributes` substitution to a listing block's default substitution list. .Add attributes substitution to a default substitution list [source] .... include::ex-subs.adoc[tag=subs-add] .... Similarly, you can remove the `callouts` substitution. .Remove callouts substitution from a default substitution list [source,subs=-callouts] .... include::ex-subs.adoc[tag=subs-sub] .... You can also specify whether the substitution is placed at the beginning or end of the substitution list. If a `+` comes before the name of the substitution, then it's added to the end of the existing list, and if a `+` comes after the name, it's added to the beginning of the list. [source,subs=-callouts] .... include::ex-subs.adoc[tag=subs-multi] .... In the above example, the quotes, then the special characters, and then the attributes substitutions will be applied to the listing block. // NOTE: More examples are pending. Information about the callouts substitution also needs to be included here. ==== Applying Substitutions to Inline Elements Custom substitutions can also be applied to some inline elements, such as the <>. For example, the quotes text substitution value is assigned in the inline pass macro below. [source] ---- include::ex-pass.adoc[tag=s-macro] ---- ==== include::ex-pass.adoc[tag=s-macro] ====