|
| 1 | +.. _AsciiMath-support: |
| 2 | + |
| 3 | +************************* |
| 4 | +MathJax AsciiMath Support |
| 5 | +************************* |
| 6 | + |
| 7 | +The support for :term:`AsciiMath` in MathJax consists of two parts: |
| 8 | +the `asciimath2jax` preprocessor, and the `AsciiMath` input processor. |
| 9 | +The first of these looks for mathematics within your web page |
| 10 | +(indicated by delimiters like ```...```) and marks the mathematics for |
| 11 | +later processing by MathJax. The AsciiMath input processor is what |
| 12 | +converts the AsciiMath notation into MathJax's internal format, where |
| 13 | +one of MathJax's output processors then displays it in the web page. |
| 14 | + |
| 15 | +The AsciiMath input jax actually includes a copy of Peter Jipsen's |
| 16 | +``ASCIIMathML.js`` file (see the `AsciiMath home page |
| 17 | +<http://www1.chapman.edu/~jipsen/mathml/asciimath.html>`_ for |
| 18 | +details), and is included by permission of the author. This means |
| 19 | +that the results of MathJax's AsciiMath processing should be the same |
| 20 | +as using the actual ``ASCIIMathML.js`` package (at least as far as the |
| 21 | +MathML that it generates is concerned). Thanks go to David Lippman |
| 22 | +for writing the initial version of the AsciiMath preprocessor and |
| 23 | +input jax. |
| 24 | + |
| 25 | +The `asciimath2jax` preprocessor can be configured to look for whatever |
| 26 | +markers you want to use for your math delimiters. See the |
| 27 | +:ref:`asciimath2jax configuration options <configure-asciimath2jax>` section for |
| 28 | +details on how to customize the action of `asciimath2jax`. |
| 29 | + |
| 30 | +The AsciiMath input processor handles conversion of your mathematical |
| 31 | +notation into MathJax's internal format (which is essentially MathML). |
| 32 | +The AsciiMath input processor has few configuration options (see the |
| 33 | +:ref:`AsciiMath options <configure-AsciiMath>` section for details). |
| 34 | + |
| 35 | +The AsciiMath input jax handles only the original ASCIIMathML notation |
| 36 | +(from ASCIIMathML v1.4.7), not the extened LaTeXMathML notation added |
| 37 | +in version 2.0 of ASCIIMathML, though the AsciiMath input jax does |
| 38 | +expose the tables that define the symbols that AsciiMath processes, |
| 39 | +and so it would be possible to extend them to include additional |
| 40 | +symbols. In general, it is probably better to use MathJax's :ref:`TeX |
| 41 | +input jax <TeX-support>` to handle LaTeX notation instead. |
| 42 | + |
| 43 | + |
| 44 | +AsciiMath delimiters |
| 45 | +==================== |
| 46 | + |
| 47 | +By default, the `asciimath2jax` preprocessor defines the back-tick |
| 48 | +(`````) as the delimiters for mathematics in AsciiMath format. It |
| 49 | +does **not** define ``$...$`` as math delimiters. That is because |
| 50 | +dollar signs appear too often in non-mathematical settings, which |
| 51 | +could cause some text to be treated as mathematics unexpectedly. For |
| 52 | +example, with single-dollar delimiters, "... the cost is $2.50 for the |
| 53 | +first one, and $2.00 for each additional one ..." would cause the |
| 54 | +phrase "2.50 for the first one, and" to be treated as mathematics |
| 55 | +since it falls between dollar signs. For this reason, if you want to |
| 56 | +use single-dollars for AsciiMath notation, you must enable that |
| 57 | +explicitly in your configuration: |
| 58 | + |
| 59 | +.. code-block:: javascript |
| 60 | + |
| 61 | + MathJax.Hub.Config({ |
| 62 | + asciimath2jax: { |
| 63 | + delimiters: [['$','$'], ['`','`']] |
| 64 | + } |
| 65 | + }); |
| 66 | + |
| 67 | +Note that the dollar signs are frequently used as a delimiter for |
| 68 | +mathematics in the :term:`TeX` format, and you can not enable the |
| 69 | +dollar-sign delimiter for both. It is probably best to leave dollar |
| 70 | +signs for TeX notation. |
| 71 | + |
| 72 | +See the ``config/default.js`` file, or the :ref:`asiimath2jax |
| 73 | +configuration options <configure-asciimath2jax>` page, for additional |
| 74 | +configuration parameters that you can specify for the `asciimath2jax` |
| 75 | +preprocessor, which is the component of MathJax that identifies |
| 76 | +AsciiMath notation within the page. |
| 77 | + |
| 78 | + |
| 79 | +AsciiMath in HTML documents |
| 80 | +=============================== |
| 81 | + |
| 82 | +The AsciiMath syntax is descibed in the `ASCIIMathML syntax page |
| 83 | +<http://www1.chapman.edu/~jipsen/mathml/asciimathsyntax.html>`_. |
| 84 | + |
| 85 | +Keep in mind that your mathematics is part of an HTML document, so you |
| 86 | +need to be aware of the special characters used by HTML as part of its |
| 87 | +markup. There cannot be HTML tags within the math delimiters (other |
| 88 | +than ``<BR>``) as AsciiMath-formatted math does not include HTML tags. |
| 89 | +Also, since the mathematics is initially given as text on the page, |
| 90 | +you need to be careful that your mathematics doesn't look like HTML |
| 91 | +tags to the browser (which parses the page before MathJax gets to see |
| 92 | +it). In particular, that means that you have to be careful about |
| 93 | +things like less-than and greater-than signs (``<`` and ``>``), and |
| 94 | +ampersands (``&``), which have special meaning to the browsers. For |
| 95 | +example, |
| 96 | + |
| 97 | +.. code-block:: html |
| 98 | + |
| 99 | + ... when `x<y` we have ... |
| 100 | + |
| 101 | +will cause a problem, because the brower will think ``<y`` is the |
| 102 | +beginning of a tag named ``y`` (even though there is no such tag in |
| 103 | +HTML). When this happens, the browser will think the tag continues up |
| 104 | +to the next ``>`` in the document (typically the end of the next |
| 105 | +actual tag in the HTML file), and you may notice that you are missing |
| 106 | +part of the text of the document. In the example above, the "``we |
| 107 | +have ...``" will not be displayed because the browser thinks it is |
| 108 | +part of the tag starting at ``<y``. This is one indication you can |
| 109 | +use to spot this problem; it is a common error and should be avoided. |
| 110 | + |
| 111 | +Usually, it is sufficient to simply put spaces around these symbols to |
| 112 | +cause the browser to avoid them, so |
| 113 | + |
| 114 | +.. code-block:: html |
| 115 | + |
| 116 | + ... when `x < y` we have ... |
| 117 | + |
| 118 | +should work. Alternatively, you can use the HTML entities ``<``, |
| 119 | +``>`` and ``&`` to encode these characters so that the browser |
| 120 | +will not interpret them, but MathJax will. E.g., |
| 121 | + |
| 122 | +.. code-block:: html |
| 123 | + |
| 124 | + ... when `x < y` we have ... |
| 125 | + |
| 126 | +Keep in mind that the browser interprets your text before MathJax |
| 127 | +does. |
0 commit comments