Math recommendations

Status: PUBLISHED

Context

<disp-formula> or <inline-formula> and elements contained therein.

Description

These recommendations contain best practices for tagging math. Inline equations are those in the flow of the text, usually within a sentence. Displayed equations are block-level (i.e., on their own line, as a block quote would be).

Remark on using images to represent math

The use of images to represent mathematical expressions is strongly discouraged. Math should be marked up within <inline-formula> and <disp-formula> using either <tex-math> or <mml:math>. If a graphical version of a mathematical expression is needed because of display requirements, <alternatives> should be used. See recommendation No. 1.

The only instance in which the graphic representation of a mathematical expression should be used outside of <alternatives> and without the equivalent mark-up is where that expression is so complicated that it cannot be represented in mark-up at all.</>

Recommendations

  1. <alternatives>. This element may contain any combination of representations (<graphic>, <mml:math>, <tex-math>), but at most one of each. And, where used, each representation should be correct, complete and logically equivalent with every other representation present. There is no explicit or implied preferred representation within <alternatives>. <alternatives> should placed within <inline-formula> or <disp-formula> and should contain the graphical version within <inline-graphic> (for an <inline-formula>) or <graphic> (for a <disp-formula>) alongside the equivalent <mml:math> or <tex-math> mark-up. See example 1.
  2. <tex-math>. Use this element to contain math-mode LaTeX, without the delimiters that are normally used to switch into and out of math mode (\\[...\\], \\(...\\), $$...$$, etc.).
    1. Rationale: the TeX enclosed in the <tex-math> element is only used within JATS articles to produce mathematics, so specifying that the content is in math-mode precludes ambiguities that could arise if more general-purpose TeX structures were included (such as, for example, commands to produce tables of contents).
    2. Exception: The only exception to this recommendation is that a subset of the LaTeX environments can be used to wrap the entire contents. (These are normally not permitted in math-mode.) These are typically used to specify alignment for multi-line equations. These are of the form \begin{XXX} ... \end{XXX}. Those environments that are permitted by MathJax are also allowed within the <tex-math> element; see MathJax TeX and LaTeX Support – Environments for a list.
    3. Note: XML CDATA sections can be used to aid in embedding TeX markup within the XML of a JATS document. This obviates the need to use escape sequences such as &amp; for an ampersand.
    4. TeX Macros: TeX macros can be defined in a <custom-meta> element, with the <meta-name> element value set to “tex-math-definitions”. The macros defined within this element could then be used in any TeX equation within the article.

Examples

Example 1: A single equation in three alternative, equivalent forms (TeX, mathML, and graphic)

<p>This was calculated as follows:
    <inline-formula id="M1">
      <alternatives>
          <tex-math>a=b</tex-math>
          <mml:math>
             <mml:mi>a</mml:mi>
             <mml:mo>=</mml:mo>
             <mml:mi>b</mml:mi>
          </mml:math>
          <inline-graphic xlink:href="equation_M1.gif"/>
      </alternatives>
 </inline-formula> 
...
</p>

Example 2: TeX 

2a. In almost all cases, use math-mode LaTeX without the delimiters that are normally used to switch into and out of math mode (\\[...\\], \\(...\\), $$...$$, etc.).

 <disp-formula>
    <tex-math id='M1'>a = b</tex-math>
 </disp-formula>

2b. Exception: using a subset of the LaTeX environments to wrap the entire contents.

 <disp-formula>
    <tex-math id='M1'>
       \begin{align*}
       x^2 + y^2 &amp; = 1\\
       x &amp; = \sqrt{1-y^2}
       \end{align*}
    </tex-math>
</disp-formula>

2c. XML CDATA section used to aid in embedding TeX markup.

<disp-formula>
<tex-math id='M1'>
<![CDATA[
\begin{align*}
x^2 + y^2 & = 1\\
x & = \sqrt{1-y^2}
\end{align*}
]]>
</tex-math>
</disp-formula>

2d. TeX macro defined in a <custom-meta> element.

<article-meta>
  ...
  <custom-meta>
     <meta-name>tex-math-definitions</meta-name>
     <meta-value>
        \def\rmi{\rm i}
        \def\rme{\rm e}
     </meta-value>
  </custom-meta>
</article-meta>