You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

119 lines
4.1 KiB

4 years ago
////
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]
====