Revised Equation Domain Proposal

[Eliot Kimber <ekimber@contrext.com>]

After consulting with Design Science we have agreed that the following are
requirements for equation markup:

1. It must be possible to have block equations within paragraphs. In STEM
writing equations often function grammatically as part of a sentence, even
when they are block equations.

2. It must be possible for authors to signal that an equation is or is not
numbered. Further, it must be possible for authors to specify the number
when automatic numbering is not appropriate. We determined based on
standard practice, published writing guides, and general common sense,
that it would never be appropriate to number an inline equation.

Requirement (1) means that it must be easy to change an equation
originally markup up as inline to being marked up as block and visa versa.
Given that we cannot provide an attribute to do that, the easiest solution
is to have two different element types that can both occur in contexts
where block equations would be appropriate (note that there are places
where you'd only ever want inline equations, such as titles and title-like
contexts, so there is not a requirement for block equations to be allowed
everywhere inline equations are allowed).

Given this agreement, I would like to propose the following revisions to
the equation domain proposal:

1. Continue to have <equation-inline> specialized from <ph>

2. Continue to have <equation-figure> specialized from <fig>

3. Change the specialization base of <equation-block> from <p> to <div>.
This allows <equation-block> to occur both within <p> and as a peer to
<p>. By being allowed within <p> it means authors can easily change
<equation-inline> to <equation-block> while still having the option to
have block equations as peers to <p> elements (just as <image> may occur
within <p> or as a peer to <p> in many contexts).

4. Add a new element type <equation-number> as an optional first child of
<equation-block>, which should allow basic phrase content (in case you
need to apply some highlighting to part of the number or something) and
have the following meaning:

- When present with empty content, indicates that the equation should be
numbered with a generated number. The rules for generating equation
numbers, as for all numbered things in DITA, are processor-specific.

- When present with non-empty content, the content is used as the number
and presented with the equation, typically to the right side of the
equation within parentheses, vertically centered within the vertical
extent of the equation.

I have verified that <div> both may occur within all required contexts (in
particular, within <fig> so it can be used within <equation-figure>) and
allows the same elements as allowed by <equation-inline>.

I believe this is the smallest change we can make to the original proposal
and continue to satisfy the requirements for equations as we currently
understand them.

Cheers,

E.
—————
Eliot Kimber, Owner
Contrext, LLC
http://contrext.com