SwarmLab-HowTos/labs/Howtos/asciidoc/_includes/stem.adoc

////
Used in:

User manual: Equations and Formulas
////

// tag::intro[]

If you need to get technical in your writing, Asciidoctor integrates with {uri-mathjax}[MathJax].
MathJax is the standard library for displaying Science, Technology, Engineering and Math (STEM) expressions in the browser.

Thanks to {uri-mathjax}[MathJax JavaScript library], Asciidoctor supports both {uri-asciimath}[AsciiMathML] and {uri-latexmath}[TeX and LaTeX] math notation in the same document.

== 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::ex-stem.adoc[tag=base-co]
----
<1> The default interpreter value, `asciimath`, is assigned implicitly.

By default, Asciidoctor's stem support assumes all equations are AsciiMath if not specified explicitly.
If you want to use the LaTeX interpreter by default, assign `latexmath` to the stem attribute.

The html backend will just use mathjax client-side to render math notation, whereas the docbook backend will use it to convert math to mathml.

.Assigning an alternative interpreter to the stem attribute
[source]
----
include::ex-stem.adoc[tag=base-alt]
----

TIP: You can still use both interpreters in the same document.
The value of the `stem` attribute merely sets the default interpreter.
To set the interpreter explicitly for a given block or inline span, just use `asciimath` or `latexmath` in place of `stem` as explained in <<Using Multiple Stem Interpreters>>.

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.

// end::intro[]

=== Inline stem content

// tag::in[]
The best way to mark up an inline formula is to use the `stem` macro.

.Inline stem macro syntax
[source]
----
include::ex-stem.adoc[tag=in-co]
----
<1> The inline stem macro contains only one colon (`:`).
<2> Place the content you want interpreted within the square brackets (`[]`) of the macro.

.Rendered inline stem content
====
include::ex-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]
----
include::ex-stem.adoc[tag=in-sb]
----

.Rendered inline stem macro with a right square bracket
====
include::ex-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.
// end::in[]

=== Block stem content

// tag::bl[]
Block formulas are marked up by assigning the `stem` style to a delimited passthrough block.

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

The result is rendered beautifully in the browser thanks to MathJax!

.Rendered delimited stem block
====
include::ex-stem.adoc[tag=bl]
====

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

// end::bl[]

=== Using multiple stem interpreters

// tag::inter[]
You can use multiple interpreters for stem content within the same document by using the interpreter's name instead of the default `stem` name.

For example, if you want LaTeXMath to interpret an inline equation, name the macro `latexmath`.

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

.Rendered latexmath content
====
include::ex-stem.adoc[tag=multi-l]
====

The name that maps to the interpreter you want to use can also be applied to block stem content.

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

// end::inter[]

=== Enabling STEM expressions in the DocBook Toolchain

// tag::docbook[]
When converting to HTML, Asciidoctor relies on MathJax to parse and render the STEM expressions in the browser.
We can't rely on MathJax when converting to DocBook, so Asciidoctor must explicitly convert the expressions into something the DocBook toolchain can understand.
Enter the asciimath gem.

The asciimath gem converts AsciiMath expressions to MathML.
The DocBook converter uses this functionality if the gem is available.
Thus, to enable AsciiMath support when converting to DocBook, you need to install the asciimath gem:

 $ gem install asciimath

For full functionality, you'll also need at least Asciidoctor version 1.5.4.

The asciimath gem converts AsciiMath to MathML.
If you're generating a PDF from the DocBook, the MathML needs to be interpreted and drawn into the PDF.
In the DocBook FOP pipeline, this is handled by JEuclid.

Fortunately, {uri-org}/asciidoctor-fopub[fopub] is already configured to use the JEuclid integration.
When fopub generates the PDF, the JEuclid FOP plugin processes any MathML found in the DocBook file, including the expressions transformed from AsciiMath to MathML by the asciimath gem.
As a result, AsciiMath stem expressions in the AsciiDoc file will render as expected in the generated PDF.

There's no equivalent gem for converting STEM expressions written in LaTeX to MathML.
Instead, you can convert the DocBook to PDF using the dblatex pipeline, which obviously supports LaTeX expressions.
// end::docbook[]

////
Since it's just a pass through block wrapped in a dedicated template (HTML and DocBook) and a JavaScript library in HTML, it shouldn't be too hard to implement.

* [LaTeXMathML](https://www.maths.nottingham.ac.uk/personal/drw/lm.html)
* [AsciiMathML](https://www1.chapman.edu/~jipsen/mathml/asciimath.html)
* [MathJax](https://www.mathjax.org)


Inline delimited (implemented)

```
$$`sqrt(4) = 2`$$
```


I decided to use `\$` as the delimiter for AsciiMath. That way, we can be confident it isn't going to match where it shouldn't. While this introduces some complexity in the raw form:

```
\$sqrt(4) = 2\$

or

$$\$Cu^(2+)\$$$
```

Alternatively, you can use an inline delimiter.


\$sqrt(4) = 2\$
<3> The asciimath inline delimiter is a backslash and a dollar sign (`\$`).
<4> Place the formula between a set of the asciimath inline delimiters.
<5> The latexmath inline delimiter is a backslash and a dollar sign (`\$`).
////