stem.adoc 4.07 KB
Newer Older
1
2
= Equations and Formulas
:stem: asciimath
3
4
5
6
7
:url-mathjax: https://www.mathjax.org
:url-asciimath: https://docs.mathjax.org/en/latest/input/asciimath.html
:url-latexmath: https://docs.mathjax.org/en/latest/input/tex/index.html
:url-mathjax-docs: https://meta.math.stackexchange.com/questions/5020/mathjax-basic-tutorial-and-quick-reference

8
If you need to display Science, Technology, Engineering and Math (STEM) expressions in your output, the HTML backend integrates with xref:asciidoctor:stem:mathjax.adoc[MathJax] and Docbook backend integrates with the xref:asciidoctor:stem:asciimath-gem.adoc[AsciiMath RubyGem].
9
10
11
12
13
14
15
16
17
18

== Activating STEM support

To activate equation and formula support, simply set the `stem` attribute in the document's header (or by passing the attribute to the command line or API).

.Setting the stem attribute
[source]
----
include::example$stem.adoc[tag=base-co]
----
19
<.> The default notation value, `asciimath`, is assigned implicitly.
20
21

By default, Asciidoctor's stem support assumes all equations are AsciiMath if not specified explicitly.
22
The HTML backend supports STEM content written in {url-asciimath}[Asciimath^] and {url-latexmath}[TeX and LaTeX^] math notation.
23
The DocBook backend only supports AsciiMath notation.
24

25
If you want to use the LaTeX notation by default, assign `latexmath` to the stem attribute.
26

27
.Assigning an alternative notation to the stem attribute
28
29
30
31
32
[source]
----
include::example$stem.adoc[tag=base-alt]
----

33
34
35
TIP: You can use both notations in the same document.
The value of the `stem` attribute merely sets the default notation.
To set the notation explicitly for a given block or inline span, just use `asciimath` or `latexmath` in place of `stem` as explained in <<mixing-notations>>.
36
37
38
39

Stem content can be displayed inline with other content or as discrete blocks.
No substitutions are applied to the content within a stem macro or block.

40
[#inline]
41
== Inline STEM content
42
43
44
45
46
47
48
49
50

The best way to mark up an inline formula is to use the `stem` macro.

.Inline stem macro syntax
[source#ex-inline]
----
include::example$stem.adoc[tag=in-co]
----
<.> The inline stem macro contains only one colon (`:`).
51
<.> Place the expression within the square brackets (`[ ]`) of the macro.
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

The result of <<ex-inline>> is displayed below.

====
include::example$stem.adoc[tag=in]
====

If the inline stem equation contains a right square bracket, you must escape this character using a backslash.

.Inline stem macro with a right square bracket
[source#ex-square-bracket]
----
include::example$stem.adoc[tag=in-sb]
----

The result of <<ex-square-bracket>> is displayed below.

====
include::example$stem.adoc[tag=in-sb]
====

A stem macro is an implicit passthrough macro.
That's why, despite the fact that the x expression matches the syntax of an attribute reference, you don't have to escape it.

76
[#block]
77
== Block STEM content
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

Block formulas are marked up by assigning the `stem` style to a delimited passthrough block.

.Delimited stem block syntax
[source#ex-block]
----
include::example$stem.adoc[tag=bl-co]
----
<.> Assign the stem style to the passthrough block.
<.> A passthrough block is delimited by a line of four consecutive plus signs (`pass:[++++]`).

The result <<ex-block>> is rendered beautifully in the browser thanks to MathJax!

include::example$stem.adoc[tag=bl]

TIP: You don't need to add special delimiters around the expression as the {url-mathjax-docs}[MathJax documentation^] suggests.
Asciidoctor handles that for you automatically!

96
97
[#mixing-notations]
== Mixing STEM notations
98

99
You can use multiple notations for STEM content within the same document by using the notation's name instead of the keyword `stem`.
100

101
For example, if you want to write an inline equation using the LaTeX notation, name the macro `latexmath`.
102
103
104
105
106
107
108
109
110
111
112

.Inline latexmath macro syntax
[source#ex-latexmath]
----
include::example$stem.adoc[tag=multi-l]
----

The result of <<ex-latexmath>> is displayed below.

include::example$stem.adoc[tag=multi-l]

113
The name that maps to the notation you want to use can also be applied to block STEM content.
114
115
116
117
118
119

.Delimited asciimath block syntax
[source]
----
include::example$stem.adoc[tag=multi-a]
----