Equations

[fred-atherden]

Maths in articles can be captured within 'inline equations' that run on with the surrounding text in a paragraph and 'display equations', which are shown on a new line and can be labelled (e.g. (1), (2), etc).

User Stories

Author

1. As an author, I want to be able to edit an equation in the manuscript so that I can correct/update the information.
2. As an author, I want to be able to delete an equation in the manuscript process, so that I can remove any erroneous equations.
3. As an author, I want to be able to add an equation in the manuscript so that I can ensure the content is correct.
4. As an author, I want to be able to set the display style for an equation, so that I can ensure that the content is presented correctly.
5. As an author, I want to be able to label a display equation so that I can refer to it with a citation in the text.
6. As an author, I want to be able to remove a label from a display equation so that I can correct any errors in labelling.

Production staff

-

SciELO/Érudit

7. As production staff, I want to be able to upload an image as an alternative to an equation so that this will be available for publication.
8. As production staff, I want to be able to replace the alternative image for an equation so that I can correct errors.

But what if . . . ?

Considerations

• Groups of display equations collected using disp-formula-group are covered in ticket #90.
• eLife currently uses MathML markup for maths - it is horrible and unwieldy so we’re happy to switch over to TexMath markup.
• There are a lot of conventions around the way in which maths is displayed in an article. For example, a display equation may appear in the middle of a paragraph, as if it were halfway through a sentence even though it will display on a new line, or at the end of a paragraph. So functionally, they work exactly the same as inline equations, it’s just that they are displayed in a different manner. We cannot get around this requirement if we want to support maths-heavy articles.
• We can’t just assume every display equation will have a label. Often, authors will only designate certain display equations to be labelled - the rest will be considered merely as steps from one main equation to the next and will not be labelled. Again, this is a standard convention so we will have to accommodate it.
• Similarly, the authors may want to do different things with the labelling, e.g. having (1), (2), (3), (4) . . . in the main text and (A.1), (A.2), (A.3), (A.4) . . . in their appendix. This is less common, however, and we could rule against it if need be.
• There are some cases where a paragraph will be broken up by a display equation. We are not sure how best to handle this, since in terms of the reader, the text before and after the equation will be the same paragraph, even to the extent of the equation reading as part of the sentence that follows it.

XML requirements

Equations can be captured as disp-formula or inline-formula. Both inline-formula and disp-formulashould be treated as inline content (i.e. not block content), and therefore should always be a child of content container elements, such as p, title, td or th.

Display formulae are semantically inline formulae which have been pulled out for extended display (and possibly labelled), therefore it does not make any sense to treat them as block content (i.e. to be captured as a child of sec or similar).

For example, for this content, the display formula is placed in the middle of a paragraph. Some renderers output indents for new paragraphs, so this is why it is necessary to capture display formulae inside content containers (so that those renderers do not erroneously output indents).

<p>... (probability of remembering the target), with some variation in precision: 
    <disp-formula id="equ1">
        <tex-math>p(\hat{\theta})=(1-\gamma) \phi_{k}(\hat{\theta}-\theta)+\gamma \frac{1}{2 \pi}</tex-math>
    </disp-formula>
where, <inline-formula><tex-math>\hat{\theta}</tex-math></inline-formula> represents the reported feature value (in radians) ... </p>

As shown above, the element tex-math (rather than mml:math) should be used for formulae.

The element alternatives should be used in the event that there are two renditions of the same equation (say image as well as tex):

<p>
    <disp-formula id="e10">
        <label>(1)</label>
        <alternatives>
            <tex-math id="tx1">
                \documentclass {article}
                \usepackage{wasysym}
                \usepackage[substack]{amsmath}
                \usepackage{amsfonts}
                \usepackage{amssymb}
                \usepackage{amsbsy}
                \usepackage[mathscr]{eucal}
                \usepackage{mathrsfs}
                \usepackage{pmc}
                \usepackage[Euler]{upgreek}
                \pagestyle{empty}
                \oddsidemargin -1.0in
                \begin{document}
                \[E_it=α_i+Z_it γ+W_it δ+C_it θ+∑_i^n EFind_i+∑_t^n EFtemp_t+ ε_it\]
                \end{document}
            </tex-math>
            <graphic xlink:href="0103-507X-rbti-26-02-0089-ee10.svg"/>
        </alternatives>
    </disp-formula>
    ...
</p>

We also need to account for cases where the equation content is only represented with an image. For inline-formula these could be treated simply as inline-graphic (if necessary), however for disp-formula these need to be captured as a formula since these can have labels:

<p>
    <disp-formula id="e10">
        <label>(1)</label>
            <graphic xlink:href="0103-507X-rbti-26-02-0089-ee10.svg"/>
    </disp-formula>
    ...
</p>

The following elements should be allowed as children of inline-formula:

• alternatives
• tex-math

The following elements should be allowed as children of disp-formula:

• label
• alternatives
• tex-math

eLife allows disp-formula in the following elements:

• p
• td
• th

eLife allows inline-formula as a child of following elements:

• p
• td
• th
• title
• article-title

Note that both disp-formula and inline-formula should be allowed as a descendant of lists (i.e. in a list-item/p element).

Taken from: https://github.com/elifesciences/TextureRequirements/issues/44

[NickDuf]

• This functionality is already present in Texture but would need additional work to meet the following requirements
  • We need the ability to remove auto-generated numbering on some equations which would take them out of the flow of the numbering system
  • We need to be able to control math labelling to some extent. The production team does not have a clear definition of this
  • We would like to be able to switch an equation from to math and vice-versa
  • We need to be able to add an image to represent the equation. Could this be configurable at the article/journal level?
  • Potential texture bug. If an equation is added it is not possible to navigate the cursor past it

[fred-atherden]

@NickDuf, as discussed earlier, we presumably also need an interface with which authors can add/edit certain parts of an equation - it would be unreasonable to expect them to know LaTeX (which is what Texture currently assumes).

@joelsummerfield, also noting that mathpix is an interesting tool which we could make use of - but it's not (completely) open source - there might be some open source equivalents out there.