Math

Status: Published
Version: 1.0
License: this recommendation document is licensed under CC BY-ND 2.0 UK

Context

<disp-formula>, <inline-formula>, <tex-math>, <mml:math>, <alternatives>, <graphic>, <custom-meta>

Description

This document contains best-practice recommendations for capturing math within an article using JATS XML. 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).

Recommendation

1. 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 2.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.
   
   [[Validator tool result: If descendant <graphic> or <inline-graphic> and not descendant <mml:math> or <tex-math> WARNING]]
2. <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.
   
   [[Validator tool result: If more than one of any combination of <graphic>, <inline-graphic>, <mml:math>, <tex-math> ERROR]]
   
   [[Validator tool result: If <alternatives> contain only one of any of the following: <graphic>, <inline-graphic>, <mml:math>, <tex-math> ERROR]]
3. <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.).
   • 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).
   • 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.
   • 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&for an ampersand.
   • 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.
     
     [[Validator tool result: If <mml:math> or <tex-math> is not a descendant of <inline-formula> or <disp-formula> ERROR]]

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 & = 1\\
       x & = \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>