options/input/tex.rst
.. _tex-options:
########################### TeX Input Processor Options ###########################
The options below control the operation of the :ref:TeX input processor <tex-input> that is run when you include 'input/tex' or
'input/tex-base' in the :data:load array of the :data:loader
block of your MathJax configuration, or if you load a combined
component that includes the TeX input jax. They are listed with their
default values. To set any of these options, include a :data:tex
section in your :data:MathJax global object.
.. code-block:: javascript
MathJax = {
tex: {
packages: ['base'], // extensions to use
inlineMath: [ // start/end delimiter pairs for in-line math
['\\(', '\\)']
],
displayMath: [ // start/end delimiter pairs for display math
['$$', '$$'],
['\\[', '\\]']
],
processEscapes: true, // use \$ to produce a literal dollar sign
processEnvironments: true, // process \begin{xxx}...\end{xxx} outside math mode
processRefs: true, // process \ref{...} outside of math mode
numberPattern: // pattern for recognizing numbers
/^(?:[0-9]+(?:\{,\}[0-9]{3})*(?:\.[0-9]*)?|\.[0-9]+)/,
initialDigit: /[0-9.,]/, // pattern for initial digit or decimal point for a number
identifierPattern: /^[a-zA-Z]+/, // pattern for multiLetterIdentifiers in \mathrm, etc.
initialLetter: /[a-zA-Z]/, // pattern for initial letter in identifiers
tags: 'none', // or 'ams' or 'all'
tagSide: 'right', // side for \tag macros
tagIndent: '0.8em', // amount to indent tags
tagAlign: 'baseline', // The rowalign value to use for tag cells
useLabelIds: true, // use label name rather than tag for ids
ignoreDuplicateLabels: false, // prevent error messages for duplicate label ids?
mathStyle: 'TeX', // one of TeX, ISO, French, or upright
maxBuffer: 5 * 1024, // maximum size for the internal TeX string (5K)
maxTemplateSubtitutions: 10000, // maximum number of array template substitutions
baseURL: // URL for use with links to tags (when there is a <base> tag in effect)
(document.getElementsByTagName('base').length === 0) ?
'' : String(document.location).replace(/#.*$/, ''),
formatError: // function called when TeX syntax errors occur
(jax, err) => jax.formatError(err),
preFilters: [], // A list of pre-filters to add to the TeX input jax
postFilters: [], // A list of post-filters to add to the TeX input jax
}
};
Note that some extensions make additional options available. See the
:ref:tex-extension-options section below for details.
.. note::
The default for :data:processEscapes has changed from
false in version 2 to true in version 3 and above.
.. note::
Prior to version 3.2, the :data:multlineWidth option used to be
in the main :data:tex block, but it is now in the :data:ams
sub-block of the :data:tex block. Version 3.2 includes code to
move the configuration from its old location to its new one, but
that backward-compatibility code has been removed in version 4.
.. note::
The :data:digits option has been renamed :data:numberPattern in version 4.
Additional options are described in the :ref:input-common-options
section.
.. _tex-packages: .. describe:: packages: ['base']
This array lists the names of the packages that should be
initialized by the TeX input processor. The :ref:input/tex <tex-input> and :ref:input/tex-base <tex-input> components
automatically add to this list the packages that they load. If you
explicitly load additional tex extensions, you should add them to
this list. For example:
.. code-block:: javascript
MathJax = {
loader: {load: ['[tex]/enclose']},
tex: {
packages: {'[+]': ['enclose']}
}
};
This loads the :ref:tex-enclose extension and activates it by
including it in the package list.
You can remove packages from the default list using '[-]'
rather than [+], as in the following example:
.. code-block:: javascript
MathJax = {
tex: {
packages: {'[-]': ['noundefined']}
}
};
This would disable the :ref:tex-noundefined extension, so that
unknown macro names would cause error messages rather than be
displayed in red.
If you need to both remove some default packages and add new ones, you can do so by including both within the braces:
.. code-block:: javascript
MathJax = {
loader: {load: ['[tex]/enclose']},
tex: {
packages: {'[-]': ['noundefined', 'autoload'], '[+]': ['enclose']}
}
};
This disables the :ref:tex-noundefined and :ref:tex-autoload
extensions, and adds in the :ref:tex-enclose extension.
.. _tex-inlineMath: .. describe:: inlineMath: [['\(','\)']]
This is an array of pairs of strings that are to be used as
in-line math delimiters. The first in each pair is the initial
delimiter and the second is the terminal delimiter. You can have
as many pairs as you want. For example,
.. code-block:: javascript
inlineMath: {'[+]': [['$','$']]}
would add dollar sign delimiters to the default list, causing
MathJax to look for ``$...$`` and ``\(...\)`` as delimiters for
in-line mathematics. Note that the single dollar signs are not
enabled by default because they are used too frequently in normal
text, so if you want to use them for math delimiters, you must
specify them explicitly.
.. warning::
The delimiters can't look like HTML tags (i.e., can't include
the less-than sign), as these would be turned into tags by the
browser before MathJax has the chance to run. You can only
include text, not tags, as your math delimiters. It is
possible, however, to use a custom render action to look for
such tags. The :ref:`v2-api-changes` section includes an
example of how to do this for the v2-style ``<script
type="math/tex">`` tags.
.. _tex-displayMath: .. describe:: displayMath: [ ['$$','$$'], ['\[','\]'] ]
This is an array of pairs of strings that are to be used as
delimiters for displayed equations. The first in each pair is the
initial delimiter and the second is the terminal delimiter. You
can have as many pairs as you want.
.. warning::
The delimiters can't look like HTML tags (i.e., can't include
the less-than sign), as these would be turned into tags by the
browser before MathJax has the chance to run. You can only
include text, not tags, as your math delimiters. It is
possible, however, to use a custom render action to look for
such tags. The :ref:`v2-api-changes` section includes an
example of how to do this for the v2-style ``<script
type="math/tex">`` tags.
.. _tex-processEscapes: .. describe:: processEscapes: true
When set to ``true``, you may use ``\$`` to represent a literal
dollar sign, rather than using it as a math delimiter, and ``\\``
to represent a literal backslash (so that you can use ``\\\$`` to
get a literal ``\$`` or ``\\$...$`` to get a backslash just before
in-line math). When ``false``, ``\$`` will not be altered, and
its dollar sign may be considered part of a math delimiter.
Typically this is set to ``true`` if you enable the ``$ ... $``
in-line delimiters, so you can type ``\$`` and MathJax will
convert it to a regular dollar sign in the rendered document.
.. _tex-processRefs: .. describe:: processRefs: true
When set to ``true``, MathJax will process ``\ref{...}`` and
``\eqref{}`` macros outside of math mode.
.. _tex-processEnvironments: .. describe:: processEnvironments: true
When ``true``, MathJax looks not only for the in-line and display
math delimiters, but also for LaTeX environments
(``\begin{something}...\end{something}``) and marks them for
processing by the TeX input jax. When ``false``, LaTeX
environments will not be processed outside of math mode. Note
that *any* environment will be picked up this way, and initiates
display-style mathematics, not just those that would do so in
LaTeX.
.. _tex-digits: .. _tex-numberPattern: .. describe:: numberPattern: /^(?:[0-9]+(?:{,}[0-9]{3})(?:.[0-9])?|.[0-9]+)/
This gives a regular expression that is used to identify numbers
during the parsing of your TeX expressions. By default, the
decimal point is . and you can use {,} between every three
digits before that. If you want to use {,} as the decimal
indicator, use
.. code-block:: javascript
MathJax = {
tex: {
digits: /^(?:[0-9]+(?:\{,\}[0-9]*)?|\{,\}[0-9]+)/
}
};
.. _tex-initialDigit: .. describe:: initialDigit: /[0-9.,]/
This gives a regular expression that tells what characters can
appear as the first character in a number. Once one of these
characters has been found, the :data:numberPattern above is
applied to the input string to see if a number is found.
.. _tex-identifierPattern: .. describe:: identifierPattern: /^[a-zA-Z]+/
This gives a regular expression that determines what constitutes a
single identifier within one of the macros that specifies a font
style, like \mathrm{} or \mathcal{}, or within
\operatorname{}. A string that matches this pattern will
produce a single <mi> element in the internal MathML
representation of your formula. Thus, \operatorname{max} will
produce <mi>max</mi> rather than three separate <mi>, one
for each letter.
.. _tex-initialLetter: .. describe:: initialLetter: /[a-zA-Z]/
This gives a regular expression that specifies what letters can
initiate a multi-letter identifier inside macros like
\\mathrm{} or \operatorname(). Once one of these
characters has been found, the :data:identifierPattern above ks
applied to the input string to see if a multi-letter identifier is
found.
.. _tex-tags: .. describe:: tags: 'none'
This controls whether equations are numbered and how. By default
it is set to 'none' to be compatible with earlier versions of
MathJax where auto-numbering was not performed (so pages will not
change their appearance). You can change this to 'ams' for
equations numbered as the AMSmath package would do, or 'all'
to get an equation number for every displayed equation.
.. _tex-tagSide: .. describe:: tagSide: 'right'
This specifies the side on which \tag{} macros will place the
tags, and on which automatic equation numbers will appear. Set it
to 'left' to place the tags on the left-hand side.
.. _tex-tagIndent: .. describe:: tagIndent: "0.8em"
This is the amount of indentation (from the right or left) for the
tags produced by the \tag{} macro or by automatic equation
numbers.
.. _tex-tagAlign: .. describe:: tagAlign: 'baseline'
This specifies how equation tags should be vertically aligned with
equations that include line breaks. Its value can be
'baseline', 'top', 'center', or 'bottom'. The
default is baseline, which is usually the baseline of the top
line of the equation.
.. _tex-useLabelIds: .. describe:: useLabelIds: true
This controls whether element :attr:id attributes for tags use
the \label name or the equation number. When true, use the
label, when false, use the equation number.
.. _tex-ignoreDuplicateLabels: .. describe:: ignoreDuplicateLabels: false
Normally, if MathJax typesets two expressions that have the same
\label, that will generate an error for the second equation
indicating the duplicate label. Setting this to true, however,
will prevent the error message from occurring. That can be useful
in a setting where you have removed the previous equation, such as
in an editor where you are retypesetting the same equation when the
content is edited.
.. _tex-mathStyle: .. describe:: mathStyle: 'TeX'
This determines how single-letter upper- and lower-case Latin and
Greek variable names are typeset. The value can be 'TeX',
'ISO', 'French', or 'upright', and the result is as
describe in the following table:
+-----------+---------+---------+---------+---------+ | mathStyle | latin | Latin | greek | Greek | +===========+=========+=========+=========+=========+ | TeX | italic | italic | italic | upright | +-----------+---------+---------+---------+---------+ | ISO | italic | italic | italic | italic | +-----------+---------+---------+---------+---------+ | French | italic | upright | upright | upright | +-----------+---------+---------+---------+---------+ | upright | upright | upright | upright | upright | +-----------+---------+---------+---------+---------+
.. _tex-maxBuffer: .. describe:: maxBuffer: 5 * 1024
Because a definition of the form \def\x{\x aaa} \x would loop
infinitely, and at the same time stack up lots of a's in MathJax's
equation buffer, the maxBuffer constant is used to limit the
size of the string being processed by MathJax. It is set to 5KB,
which should be sufficient for any reasonable equation.
.. _tex-maxTemplateSubstitutions: .. describe:: maxTemplateSubstitutions: 10000
In an array environment preamble, it is possible to make a column
declaration that loops infinitely. For example,
\begin{array}{c@{\\}c} a&b \end{array}
would cause MathJax to loop. This value prevents this from looping
infinitely by limiting the number of template substitutions that
can be applied to an array.
.. _tex-baseURL: .. describe:: baseURL: URL
This is the base URL to use when creating links to tagged equations
(via \ref{} or \eqref{}) when there is a <base> element
in the document that would affect those links. You can set this
value by hand if MathJax doesn't produce the correct link. By
default, it is either the URL for the current document if there is
a <base> element, or an empty string if not.
.. _tex-formatError: .. describe:: formatError: (jax, err) => jax.formatError(err)
This is a function that is called when the TeX input jax identifies
a syntax or other error in the TeX that it is processing. The
default is to generate an <merror> MathML element with the
message indicating the error that occurred. You can override the
function to perform other tasks, like recording the message,
replacing the message with an alternative message, or throwing the
error so that MathJax will stop at that point (you can catch the
error using promises or a try/catch block). Your function
should return the MathML tree that is used for the error, in
MathJax's internal format. The :meth:jax.mmlFactory.create()
function can be used to create such trees. For example,
.. code-block:: javascript
jax.mmlFactory.create('mtext', {mathvariant: 'bold'}, [
jax.mmlFactory.text('An error occurred!')
]);
would create the internal representation for
.. code-block:: xml
<mtext mathvariant="bold">
An error occurred!
</merror>
.. _tex-preFilters: .. describe:: preFilters: []
This specifies a list of functions to run as pre-filters for the
TeX input jax. Each entry is either a function, or an array
consisting of a function followed by a number, which is the
priority of the pre-filter (lower priorities run first). The
functions are passed an object with three properties: :data:math,
giving the :data:MathItem being processed, :data:document
giving the :data:MathDocument for the math item, and :data:data
giving the :data:ParseOptions object that holds the details of
the input jax configuration. The pre-filters are executed when the
TeX input jax is asked to parse a TeX expression, and before the
TeX string is processed, so you can use a pre-filter to adjust the
TeX string prior to it being parsed. The math item's :data:math
property is the original TeX string.
See the :ref:sync-filters section for examples of pre-filters.
.. _tex-postFilters: .. describe:: postFilters: []
This specifies a list of functions to run as post-filters for the
TeX input jax. Each entry is either a function, or an array
consisting of a function followed by a number, which is the
priority of the pre-filter (lower priorities run first). The
functions are passed an object with three properties: :data:math,
giving the :data:MathItem being processed, :data:document
giving the :data:MathDocument for the math item, and :data:data
giving the :data:ParseOptions object that holds the details of
the input jax configuration. The post-filters are executed when
the TeX input jax has finished parsing the TeX expression and has
converted it to the internal MathML format. The math item's
:data:root property holds the root of the parsed MathML tree (the
internal representation of the <math> element).
See the :ref:sync-filters section for examples of post-filters.
In addition to the options listed above, low-level options intended for developers include the following:
.. _tex-FindTeX: .. describe:: FindTeX: null
The FindTeX object instance that will override the default one.
This allows you to create a subclass of the FindTeX class,
create an instance of it, and pass that to the TeX input jax to use
instead of the usual one. A null value means use the default
FindTeX class and make a new instance of that.
.. _tex-extension-options:
Several of the TeX extensions make additional options available in the
tex block of your MathJax configuration. These are described
below. Note that the :ref:input/tex <tex-input> component, and the
combined components that load the TeX input jax, include a number of
these extensions automatically, so some these options will be
available by default.
For example, the :ref:tex-configmacros package adds a macros
block to the tex configuration block that allows you to pre-define
macros for use in TeX expressions:
.. code-block:: javascript
MathJax = { tex: { macros: { R: '\mathbf{R}' } } }
The options for the various TeX packages (that have options) are described in the links below:
|btight|
tex-ams-optionstex-amscd-optionstex-autoload-optionstex-bbm-optionstex-bboldx-optionstex-begingroup-optionstex-color-optionstex-configmacros-optionstex-dsfont-optionstex-mathtools-optionstex-noundefined-optionstex-physics-optionstex-require-optionstex-setoptions-optionstex-tagformat-optionstexhtml Options <tex-texhtml-options>tex-units-options|etight|
It is sometimes convenient to be able to change the value of a TeX or
TeX extension option from within a TeX expression. For example, you
might want to change the tag side for an individual expression. The
:ref:tex-setoptions extension allows you to do just that. It
defines a \setOptions macro that allows you to change the values
of options for the TeX parser, or the options for a given TeX package.
Because this functionality can have potential adverse consequences on
a page that allows community members to enter TeX notation, this
extension is not loaded by default, and can't be loaded by
\require{}. You must load it and add it to the tex package list
explicitly in order to allow the options to be set. The extension has
configuration parameters that allow you to control which packages and
options can be modified from within a TeX expression, and you may wish
to adjust those if you are using this macro in a community setting.
|-----|