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.
118 lines
4.1 KiB
118 lines
4.1 KiB
////
|
|
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]
|
|
====
|
|
|