Equations

[fred-atherden]

Description

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 a separate ticket (yet to be raised).
• 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).

Mock ups

This is not required, but if you have mock ups of what you would like to see please provide them here.

Proposal

This will be added by the Texture team after the feature request is discussed and agreed.