# Rendering Content Elements

## Rendering Agent at Work

A rendering agent is a processor that, on behalf of a user, for
example through an HTTP request, converts
content-mathematical-expressions to presentation. We call this
conversion, the delivery of the rendering agent. Typically, the
delivery is happening within a user-interaction which lives within
a context: information about this context can be multiple, it
includes the preferred languages of the user, the preferred
notational styles of the user or of the surrounding content. A
rendering agent should be able to process arbitrary content
expressions and should be able to do so even dynamically,
encountering a fully new `csymbol`

element, or being instructed to
render a complex expression in a different way.

For this purpose, MathML-3 introduces four??? elements which allow
to associate content-expressions (the *prototype*) to
presentation-expressions (the *rendering*) together defining a
*mathematical notation*. The notations are packaged in
exchangeable files and can be dynamically discovered and
incorporated.

A notation’s prototype is an arbitrary content-MathML expression, which is said to match a content-MathML-expression if values can be assigned to the variables of the prototype so that, when replaced with these values, the prototype becomes equal to the expression. Within a notation, variables of the prototype that are not used in the rendering should be matched explicitly, with a variable of the same name. Below, we shall extend once more this definition of matching when explaining about support for arbitrary number of arguments.

## Context Information and Inheritance

Information about a context that should discriminate the choice of
a notation is encoded in `context`

elements which encode the
following suggested attributes:

style-class | is a space separated list of style class-names |

xml:lang | encodes a language for which this notation applies |

format | encodes the mime-type of a target rendering |

deliveryPath | encodes part of the URL under which the current expression is being rendered |

A context element may inherit from a parent context by simply accepting the attribute values of its parent for the attributes it does not have.

A context element is said to match for a rendering process if all
of the attributes above are considered valid by the agent, i.e. if
the language is deemed understandable by the user, if the format
is supported, if the deliveryPath is a substring of the current
delivery’s address (if defined) or if a name within the style
attributed is encoded as part of the current rendering styles
(e.g. using `class`

attributes in a parent element of the
expression to be rendered).

## Notation Elements and Processing

Notations are bundled in XML documents under
`notation-document`

element.

cdbase | a URI specifying the base-URI on top of which all `symbol` references will be written |

Notations are grouped within a `notations`

element which groups a
set of notation and is assigned a *target*, that is, the URI of a
symbol that all notations mainly address.

The elements `notations`

may contain one or more prototypes, in
which case all *notation* elements contained there are alternate
renderings of this prototype. If the `notations`

element does not
contain a prototype, its children `notation`

elements should each
have at least one. The `notation-document`

, `notations`

, and
`notation`

elements all accept a `context`

child as defined above.

Conforming rendering-agents use a series of notation-documents to render arbitrary content-MathML-expressions within a given rendering context as follows:

- starting from the root of the expression, identify the set of notations that have the most specialized prototypes and still match the root element among them choose the one whose context matches the rendering context under consideration
- if two notations are still eligible, the one in the furthest notation-document in the list should be used
- a notation is used by assigning to variables of the prototype the necessary sub-terms, by outputting the rendering of the notation with
`mi`

elements replaced with the rendering of the content-MathML-expressions of the variables of the same name.

A simple example is provided below, it describes the notations for the open real interval in English and other languages:

```
<notations target="basic_content_elements#interval-oo">
<math>
<apply>
<csymbol uri="basic_content_elements#interval-oo"/>
<ci>a</ci>
<ci>b</ci>
</apply>
</math>
<notation>
<context xml:lang="en"/>
<math>
<mrow>
<mo>(</mo>
<mi>a</mi>
<mo>,</mo>
<mi>b</mi>
<mo>)</mo>
</mrow>
</math>
</notation>
<notation>
<context/>
<math>
<mrow>
<mo>]</mo>
<mi>a</mi>
<mo>,</mo>
<mi>b</mi>
<mo>[</mo>
</mrow>
</math>
</notation>
</notations>
```

Supposing a renderer would be working in an environment in French, had to render the following expression:

```
<math><apply>
<interval type="open"/>
<apply><minus/><ci>a</ci><ci>ε</ci></apply>
<apply><plus/><ci>a</ci><ci>ε</ci></apply>
</apply></math>
```

It would be first converting this expression to canonical
MathML, replacing, interval, plus, and minus, to the
corresponding `csymbol`

elements. Then it would choose the
second notation above, since the english-language context does
not match, would output:

```
<math>
<mrow>
<mo>]</mo>
*
<mo>,</mo>
*
<mo>[</mo>
</mrow>
</math>
```

then would replace the * with the rendering of

```
<math>
<mrow>
<mo>]</mo>
<mrow>a-ε</mrow>
<mo>,</mo>
<mrow>a+ε</mrow>
<mo>[</mo>
</mrow>
</math>
```

## Precedence Rules and Bracket Output

In the process described above, no brackets have been necessary to disambiguate the expression. There are many cases, however, where brackets really appear to be needed in a presented formula and such a decision depends, not only, on the notation of an operation but on the relation between this notation and its child arguments.

MathML-3 adds `precedence`

attributes to the `notation`

elements
(the *parent precedence* and to the `mi`

elements (the *child
precedence*), both of which are expected to be numbers between 0
and 1000. This allows rendering agents, rendering using a notation
and starting to render a child term, represented by an `mi`

element, to decide on fencing the term output if the two following
conditions hold:

- the
`mi`

element in the notation is child of row-like MathML-presentation element (see section 3.1.3, about inferred mrow) - the term is an application of an operation whose parent precedence is smaller than the child-precedence of the variable we are currently rendering

Terms that are not applications, for example `ci`

or `csymbol`

elements never require a bracket, and as such can be considered to
have the highest precedence, 1000. `mi`

elements that have no
precedence element within a notation attribute

For example, the following `notation`

element could be used for
the factorial (algebra-logic#factorial) operation:

```
<notation target="algebra-logic#factorial" precedence="500">
<math>
<apply>
<csymbol uri="algebra-logic#factorial"/>
<ci>x</ci>
</apply>
</math>
<math>
<mrow><mi precedence="500">x</mi><mo>!</mo></mrow>
</math>
</notation>
```

rendering:

```
<apply><factorial/><apply><plus><ci>x</ci><ci>y</ci></apply></apply>
```

would thus yield the application of the above notation composed with the application of the plus notation, of precedence 50, thus should output a bracket. But rendering:

```
<apply><factorial/><apply><ci>x</ci></apply>
```

would apply the notation above but would not need to output a bracket to output the rendering of the x variable.

#### Support for Functions with Arbitrary Number of Arguments

Many operations take an arbitrary number of arguments. A special matching symbol is introduced as well as a special presentation element to iterate over such ranges.

The `nary`

symbol, of the content-dictionary `ntn`

is used with an
application to match any number of elements where the `apply`

element appears. It accepts an arbitrary number of arguments: if
only one argument is provided, it should be a variable, a `ci`

element, the name of the nary-matcher; if several arguments, are
provided, they should all be applications of the `nary-alt`

symbol
to arbitrary expressions.

Variable-names within a `notation`

element are expected to be
distinct for each `nary`

symbol application.

The `nary`

symbol is best used in conjunction with the `nary`

presentation element. The latter accepts two children, the first
is a rendering of the argument and the second is a separator, a
node that is copied between each of the multiple occurrences.

Rendering agents are expected to process `nary`

presentation
elements by finding the corresponding `nary`

symbol application,
i.e. that with the same variable name, and iterating over the
matching terms, rendering them, interleaved with the separator.

A complex example is the `plus`

symbol which, in many occidental
languages, could have the following notation:

```
<notation precedence="100">
<math>
<apply>
<plus/>
<apply>
<csymbol uri="ntn#nary"/>
<ci>term</ci>
</apply>
</apply>
</math>
<math>
<nary>
<mi>a</mi>
<mo>+</mo>
</nary>
</math>
</notation>
```

This method can be combined with extension matchers, for example matching single positive real-numbers in order to provide such notations as the rendering of a polynomial where the ⋅ operator is not visible between the coefficient and the monomial. Such extensions are out of scope of this specification, thus far.