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.
133 lines
3.8 KiB
133 lines
3.8 KiB
////
|
|
Included in:
|
|
|
|
- user-manual: Passthroughs Macros
|
|
- writers-guide: preventing subs
|
|
////
|
|
|
|
Asciidoctor supports several forms of the passthrough macro.
|
|
|
|
inline pass macro:: An inline macro named `pass` that can be used to passthrough content.
|
|
Supports an optional set of substitutions.
|
|
+
|
|
[source]
|
|
----
|
|
pass:[content like #{variable} passed directly to the output] followed by normal content.
|
|
|
|
content with only select substitutions applied: pass:c,a[__<{email}>__]
|
|
----
|
|
|
|
single and double plus:: A special syntax for preventing text from being formatted.
|
|
Only escapes special characters for compliance with the output format and doesn't support explicit substitutions.
|
|
|
|
triple plus:: A special syntax for designating passthrough content.
|
|
Does not apply any substitutions (equivalent to the inline pass macro) and doesn't support explicit substitutions.
|
|
|
|
double dollar (deprecated):: A deprecated special syntax for designating passthrough content.
|
|
Like the triple plus, does not apply any substitutions and doesn't support explicit substitutions.
|
|
|
|
CAUTION: Asciidoctor does not implement the block pass macro.
|
|
Instead, you should use a <<pass-blocks,pass block>>.
|
|
|
|
==== Inline pass macro and explicit substitutions
|
|
|
|
To exclude a phrase from substitutions and disable escaping of special characters, enclose it in the inline pass macro.
|
|
For example, here's one way to format text as underline when generating HTML from AsciiDoc:
|
|
|
|
[source]
|
|
----
|
|
include::ex-pass.adoc[tag=in-macro]
|
|
----
|
|
|
|
====
|
|
include::ex-pass.adoc[tag=in-macro]
|
|
====
|
|
|
|
If you want to enable ad-hoc `quotes` substitution, then assign the `macros` value to `subs` and use the inline pass macro.
|
|
|
|
....
|
|
include::ex-pass.adoc[tag=sub-in]
|
|
....
|
|
<1> `macros` is assigned to `subs`, which allows any macros within the block to be processed.
|
|
<2> The pass macro is assigned the `quotes` value. Text within the square brackets will be formatted.
|
|
|
|
The inline pass macro does introduce additional markup into the source code that could make it invalid in raw form.
|
|
However, the output it produces will be valid when viewed in a viewer (HTML, PDF, etc.).
|
|
|
|
====
|
|
include::ex-pass.adoc[tag=sub-out]
|
|
====
|
|
|
|
The inline pass macro also accepts shorthand values for specifying substitutions.
|
|
|
|
* `c` = special characters
|
|
* `q` = quotes
|
|
* `a` = attributes
|
|
* `r` = replacements
|
|
* `m` = macros
|
|
* `p` = post replacements
|
|
|
|
For example, the quotes text substitution value is assigned in the inline passthrough macro below:
|
|
|
|
[source]
|
|
----
|
|
include::ex-pass.adoc[tag=s-macro]
|
|
----
|
|
|
|
====
|
|
include::ex-pass.adoc[tag=s-macro]
|
|
====
|
|
|
|
==== Triple plus passthrough
|
|
|
|
The triple-plus passthrough works much the same way as the pass macro.
|
|
To exclude content from substitutions, enclose it in triple pluses (pass:[+++]).
|
|
|
|
+++content passed directly to the output+++ followed by normal content.
|
|
|
|
The triple-plus macro is often used to output custom HTML or XML.
|
|
|
|
[source]
|
|
----
|
|
include::ex-pass.adoc[tag=3p]
|
|
----
|
|
|
|
====
|
|
include::ex-pass.adoc[tag=3p]
|
|
====
|
|
|
|
////
|
|
.Double-dollar passthrough
|
|
|
|
The double-dollar passthrough behaves like the triple-plus passthrough, but it allows <<user-manual#special-characters,special characters>> in its content to be replaced.
|
|
Passthrough content is enclosed by double dollar signs (+$$+).
|
|
|
|
$$Content passed directly to the output$$ followed by normal content.
|
|
|
|
[source]
|
|
----
|
|
include::ex-pass.adoc[tag=dollar]
|
|
----
|
|
|
|
====
|
|
include::ex-pass.adoc[tag=dollar]
|
|
====
|
|
|
|
[#back-pass]
|
|
.Backtick passthrough
|
|
|
|
Content enclosed in a backtick passthrough is subject to <<user-manual#special-characters,special characters>> substition and displayed as monospace text.
|
|
|
|
`Content in a line that is passed directly to the output` followed by normal content.
|
|
|
|
Backticks (+`+) are commonly used around inline code containing markup.
|
|
|
|
[source]
|
|
----
|
|
include::ex-pass.adoc[tag=tick]
|
|
----
|
|
|
|
====
|
|
include::ex-pass.adoc[tag=tick]
|
|
====
|
|
////
|
|
|