Proposed Enhancement to The Equation Domain

[Eliot Kimber <ekimber@rsicms.com>]

I've been communicating with Dr Patrick Leevers, a professor of
engineering at Imperial College London, about the new MathML and equation
domains. Dr. Leevers is working on using DITA as the source for STEM
course materials, so of course mathematics is extremely important.

The feedback I got from Dr. Leevers is that in mathematical writing the
decision to display an equation that is within prose as block or inline
and, for block equations, whether or not to number an equation, is a
per-equation-instance decision made by the author. He pointed me to these
dicsussions:

> This discussion about equations and punctuation is good, especially the
> first and last responses:
> 
>http://english.stackexchange.com/questions/31124/should-there-be-a-period-
> after-an-equation
> The question of equation numbering enters here:
> 
>http://english.stackexchange.com/questions/22535/do-mathematical-equations
>-require-punctuation
> and it takes us to the ultimate authority Knuth (who invented TeX) at
> http://tex.loria.fr/typographie/mathwriting.pdf
> who on p4, p7 etc. does punctuation-and-numbers stuff.


Dr. Leevers' feedback is also consistent with work I've been doing
recently for a client that is using DITA to represent scientific journal
articles, some with many equations--we ran into just these same issues
around equation flow within paragraphs, capturing and rendering text
around block equations, and capturing and rendering equation numbers.

The challenge revolves around how to display and whether to number
equations that are part of a larger sentence.

For example, say I have this sentence:

"The amount of energy in a given unit of mass can be determined by the
equation E = mc^^2, where E is the energy, m is the mass, and c is the
speed of light in a vacuum."


The equation "E = mc^^2" is part of the sentence grammatically and
rhetorically. However, the author could choose to render the sentence like
this:

"The amount of energy in a given unit of mass can be determined by the
equation 

    E = mc^^2, 

where E is the energy, m is the mass, and c is the speed of light in a
vacuum."


Note the "," after the equation--this reflects that the sentence is still
a single sentence despite the block display of the equation.

If the author needs to refer to that equation they may decide to add an
equation number:

"The amount of energy in a given unit of mass can be determined by the
equation 

    E = mc^^2,    (1)

where E is the energy, m is the mass, and c is the speed of light in a
vacuum."

This way of using equations has several implications for the current
design of the equation domain:

1. The block/inline distinction intended by the <equation-block> and
<equation-inline> elements is not useful in this context: in all three of
the cases above, the only correct element type is <equation-inline> (a
specialization of <ph>) because in all three cases the content is a
sentence within a paragraph, e.g.:

<p>"The amount of energy in a given unit of mass can be determined by the
equation
<equation-inline>E = mc^^2</equation-inline>, where E is the energy, m is
the mass, 
and c is the speed of light in a vacuum.</p>


2. Because numbering can be on a per-instance basis, and because those
numbers may be completely arbitrary, there needs to be an element
specifically for specifying the equation number that can be put inside the
equation container, e.g. <equation-number>.

3. Because numbering is on a per-instance basis, using <equation-figure>
in place of <equation-inline> simply to trigger numbering is not really
realistic. For one reason, while <fig> is allowed in <p>, it's not allowed
in all contexts where <ph> is also allowed (for obvious reasons), so
equation-figure and equation-inline can't be used interchangeably in the
general case.

This all leads me to suggest the following refinements to the current
equation domain design:

1. Define the following values to be used in @outputclass on
<equation-inline>:

- block/inline: Indicates whether the equation should be rendered as block
or inline, with inline being the default rendering if no value is
specified.

- block-numbered: Indicates that the equation should be rendered as a
numbered block equation with the number to be generated if not specified
explicitly (the normal case).

- inline-numbered: Indicates that the equation should be rendered as a
numbered inline equation with the number to be generated if not specified
explicitly (the normal case). This may be a rare case but is included for
symmetry at least.

I'm using "compound" values here rather than multiple keywords to make
authoring easier: tools that support using subjectScheme to define
attribute values don't always support setting multiple keywords (and such
support requires a more complicated user interface than just a simple
dropdown list).

2. Define the new element <equation-number>, specialized from <ph> and
allowed within <equation-block>, <equation-inline>, and <equation-figure>
. The content of the equation number is the equation number and is used in
place of any number that might be generated.

Cheers,

Eliot

-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
www.reallysi.com
www.rsuitecms.com