Elements in the DITA Math Domain

This page contains a list of the elements supplied to implement a DITA math domain.

Body elements

These elements are generally available for use wherever text is allowed.

Note that <math> and <mathph> are essentially identical because they both inherit from <foreign> and have the same content model.  They therefore become available in exactly the same places.  Ideally, we would like <math> to be legal wherever <p> is legal, and <mathph> to be legal wherever <ph> is legal, I think.  

math

Inherits from <foreign>.

Attributes:

Note that one has a choice:

1. Include MathML directly and do not specify href, format, or conref.
2. Do not include child elements, specify the conref attribute but not href and format.
3. Do not include child elements, specify the href and format attributes but not conref.

If the expression is to be included directly, one and only one child element is allowed.

This element will render at the same level as paragraph content. It is intended to be used for stand-alone expressions.

mathph

Inherits from <foreign>

Attributes:

Note that one has a choice:

1. Include MathML directly and do not specify href, format, or conref.
2. Do not include child elements, specify the conref attribute but not href and format.
3. Do not include child elements, specify the href and format attributes but not conref.

If the expression is to be included directly, one and only one child element is allowed.

This element will render at the sentence level. It is intended to be used for inline expressions.

equation

Inherits from <fig>.

This is a container for a mathematical expression which includes an optional title and which serves as a target for an xref element with type="eq". It contains a <math> element followed by an optional <eqsymbols> element. If it is copied into the current context with conref=, then the copy retains all of the properties described by the children of the source, except for those which are overridden by explicitly specifying them in this context.

Equation specific elements

An equation element may contain a list of symbol definitions which explain the terms used in the formula. These symbol definitions are symbol/text pairs.  Each symbol may have one terse and one verbose description.  Elements in this section inherit from the family of elements which define a definition list.

These elements should always be suppressed (generate no output).  They exist to capture information and bind it to the source.  Presentation of this information may occur in (at least) two different forms, and the option to combine the presentation of symbols from multiple equations into a single list should be offered to the author.  See <eqdefstbl> and <eqdefsph>.

eqsymbols

Inherits from <dl>.

This element contains all of the symbols which the author chooses to define. If the containing equation element is not in a mathexpression reference page, then these are the only symbols defined for the associated expression. If it is within a mathexpression reference page, then all of the symbols defined for the page are inherited unless they are overridden here.

eqsymbol

Inherits from <dlentry>.

Contains a name/description pair.

symname

Inherits from <dt>.

Contains the symbol name.   The content model is identical to <dt> (the element it inherits from) to allow authors to type simple symbol names (i.e. x) directly.  However, it is expected that in most cases this element will contain a <mathph> element with type="symbol", and the referenced expression should refer only to the desired symbol.  The symbol may be defined using any of the expression languages to which <mathph> may be applied.

To discuss the symbol in the text, it is expected that authors will use <mathph conref=.. /> where the conref= attribute specifies the child of <symname>  This practice encourages good document maintenance habits and gives authors the ability to change the symbol everywhere it is used merely by changing it once, when it is defined.  To make this same feature available to those who would type simple symbol names directly, authors are encouraged to declare the symbol name inside a child <ph> element.

symdesc

Inherits from <dd>.

Contains a symbol description. This will appear in the tabular presentation of symbols, so it should be at least a complete sentence and may be a short paragraph.

symdescph

Inherits from <dd>.

Contains a brief symbol description. This will appear in an inline presentation of symbols, so it should be brief, a sentence fragment. It should be written to fit the pattern "symname is symdescph".

Symbol list Elements

The elements in this section present the defined symbols to the reader. The presentation may be tabular or inline. In addition, one may present the list of symbols for a single equation or may choose to consolidate the symbol list from many equations.

eqdefsph

Inherits from <unknown>.

An inline phrase which presents a list of all the symbols and definitions. Contains one or more xref elements, each of which specifies a single equation from which to display symbols. The final result should be deterministic: e.g., "symbol1 is descriptive phrase1, symbol2 is descriptive phrase2 and symbol3 is descriptive phrase 3". May contain an optional eqsymbols element which overrides particular symbols and adds to the list of symbols discovered by the xref mechanism. The default is to define all symbols for all equations included by any topic referenced in the top-level map.

eqdefstbl

Inherits from <unknown>.

A tabular presentation of the symbols and corresponding definitions. Each symbol/description pair occurs in a single row of the table. The description here is intended to be more complete than the descriptive phrase. Contains one or more xref elements, each of which specifies a single equation from which to display symbols. The result here can be less deterministic, as it is not intended to be integrated into a sentence. May contain an optional eqsymbols element which overrides particular symbols and adds to the list of symbols discovered by the xref mechanism. The default is to define all symbols for all equations included by any topic referenced in the top-level map.

Math Topic Elements

This topic type, which specializes a standard DITA reference topic, allows users to associate content and presentation expressions with an OpenMath symbol. It also allows users to declare content and presentation expressions (along with their symbol definitions) which they can later reuse.

We should specialize the properties family of elements so that the author can define the symbols used in this topic's equations only once. Or perhaps use the eqsymbols family of elements in their stead. Can we do that?

mathexpression

Inherits from reference. May contain shortdesc, desc, prolog, and everything else a reference element contains.

mathbody

Inherits from refbody. May contain expressions.

expression

Inherits from section. May contain only one equation, but otherwise may contain any combination of text, tables, figures, etc. The type attribute of the equation declares whether this expression is a content or presentation expression.