@import ../template.nml
%<make_doc({"External Tools"}, "LaTeX", "LaTeX")>%

@LaTeX = $|[kind=inline, caption=LaTeX]\LaTeX|$

#+LAYOUT_BEGIN Centered
*Bring some %LaTeX% unto your document!*
#+LAYOUT_END

# Requirements

In order to use LaTeX processing, you need to have a %LaTeX% distribution installed. We recommend the [TeX Live](https://en.wikipedia.org/wiki/TeX_Live) distribution.
You'll also need to install the [latex2svg](https://github.com/ef3d0c3e/nml/blob/master/third/latex2svg) python script provided with NML. You'll have to follow the installation instructions from the [original latex2svg repository](https://github.com/Moonbase59/latex2svg). If you don't want to add the script to your `\$PATH`, you can set the executable path in the §{tex_env}[caption=LaTeX environment].

# Inline Math

You can add inline math by enclosing %LaTeX% between two ``$``:
 * ``$\lim_{n \to \infty} \Big(1 + \frac{1}{n}\Big)^n = e$`` → $\lim_{n \to \infty} \Big(1 + \frac{1}{n}\Big)^n = e$
 * ``$\pi = \sqrt{\sum_{n=1}^\infty \frac{1}{n^2}}$`` → $\pi = \sqrt{\sum_{n=1}^\infty \frac{1}{n^2}}$

You can make the %LaTeX% non inline by specifying `kind=block` in it's property: ``$[kind=block] 1+1=2$`` → $[kind=block] 1+1=2$
*(notice how it's not inside a paragraph)*

# Non Math LaTeX

You can write %LaTeX% outside of %LaTeX%'s math environment, by enclosing your code between ``$|...|$``:
``LaTeX,
$|\begin{tikzpicture}
	\begin{axis}
	\addplot3[patch,patch refines=3,
		shader=faceted interp,
		patch type=biquadratic] 
	table[z expr=x^2-y^2]
	{
		x  y
		-2 -2
		2  -2
		2  2
		-2 2
		0  -2
		2  0
		0  2
		-2 0
		0  0
	};
	\end{axis}
\end{tikzpicture}|$
``
Gives the following:

#+LAYOUT_BEGIN Centered
$|\begin{tikzpicture}
	\begin{axis}
	\addplot3[patch,patch refines=3,
		shader=faceted interp,
		patch type=biquadratic]
	table[z expr=x^2-y^2]
	{
		x  y
		-2 -2
		2  -2
		2  2
		-2 2
		0  -2
		2  0
		0  2
		-2 0
		0  0
	};
	\end{axis}
\end{tikzpicture}|$
#+LAYOUT_END

#{tex_env} LaTeX environment

You can define multiple %LaTeX% environment, the default being `main`
 * ``@tex.env.fontsize`` The fontsize (in pt) specified to `latex2svg` (default: `12`).
 * ``@tex.env.preamble`` The preamble prepended to every %LaTeX% code.
 * ``@tex.env.block_prepend`` Text to prepend to every non math %LaTeX% code.
 * ``@tex.env.exec`` The `latex2svg` executable path, defaults to `latex2svg` (need to be in your `\$PATH`)
Replace ``env`` with the name of the custom environment you wish to define.

Here's a preamble to render %LaTeX% gray:
``
@tex.main.fontsize = 9
@tex.main.preamble = \usepackage{xcolor} \\
\usepgfplotslibrary{patchplots} \\
\definecolor{__color1}{HTML}{d5d5d5} \\
\everymath{\color{__color1}}
@tex.main.block_prepend = \color{__color1}
``

To set the environment you wish to use for a particular %LaTeX% element, set the `env` property:
 * ``$[env=main] 1+1 = 2$`` → $[env=main] 1+1 = 2$
 * ``$[env=other] 1+1 = 2$`` → $[env=other] 1+1 = 2$

# Properties
 * ``env`` The %LaTeX% environment to use, defaults to `main`.
 * ``kind`` The display kind of the rendered element:
 *- `inline` (default for math mode) displays %LaTeX% as part of the current paragraph.
 *- `block` (default for non math mode) display %LaTeX% on it's own line.
 * ``caption`` Caption for accessibility, defaults to `none`.

# LaTeX cache

%LaTeX% elements that have been successfully rendered to **svg** are stored in the cache database, to avoid processing them a second time.
Note that this cache is shared between documents, so you don't need to reprocess them if they share the same environment.
They are stored under the table named ``Plain Text,cached_tex``, if you modify the `env` all elements will be reprocessed which may take a while...

# Bindings

 * ``Lua, nml.tex.push_math(kind, tex [, env [, caption]])``
 inserts a math mode %LaTeX% element.
 ** ``kind`` *(string)* the element kind (inline or block)
 ** ``tex`` *(string)* the %LaTeX% code
 ** ``env`` *(string)* the %LaTeX% environment (defaults to `main`)
 ** ``caption`` *(string)* the accessibility caption

 * ``Lua, nml.tex.push(kind, tex [, env [, caption]])``
 inserts a non-math %LaTeX% element.
 ** ``kind`` *(string)* the element kind (inline or block)
 ** ``tex`` *(string)* the %LaTeX% code
 ** ``env`` *(string)* the %LaTeX% environment (defaults to `main`)
 ** ``caption`` *(string)* the accessibility caption