////
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 <<user-manual#tree-processor-example,TreeProcessor extension>>.
====

=== 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]
`<substitution>+`::
Prepends the substitution to the default list.
`+<substitution>`::
Appends the substitution to the default list.
`-<substitution>`::
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 <<user-manual#pass-macros,pass macro>>.

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]
====
