Authoring Web-accessible Mathematical Diagrams

The basic diagram vocabulary, designed to mirror mathematical vocabulary, drives the SVG generation and can roughly be divided into five functional groups: (1) definitions, control, and grouping, (2) basic grids and axes, (3) one-dimensional objects, such as graphs and lines, (4) two-dimensional objects, such as areas and polygons, and (5) labels.

The XML description for the left-most diagram in Figure 1.1 is given in Listing 2.1. The graphics element specifies the basic dimension of a the output graphics. Note that since we are constructing a scalalable vector graphics this dimension only serves to give the aspect ratio of the resulting diagram. It is however relevant for PreTeXt to compile the graphics for inclusion in PDF output.

<graphics
id=
"figure"
width=
"300"
height=
"300"
margins=
"5"
>
<boundingbox
mbox=
"[-4,-4,4,4]"
/>
<grid-axes
xlabel=
"x"
ylabel=
"y"
/>
<variable
name=
"a"
value=
"1"
/>
<function
expr=
"f(x) = exp(x/3)*cos(x)"
/>
<group
id=
"graph-tangent"
>
<graph
id=
"graph"
function=
"f"
stroke=
"blue"
/>
<tangent-line
id=
"tangent"
function=
"f"
point=
"a"
stroke=
"red"
/>
<point
id=
"point"
p=
"(a, f(a))"
fill=
"red"
label=
"(a, f(a))"
/>
</group>
</graphics>

The boundingbox and grid-axes elements then specify the basic grid layout. In our case we use a grid with labeled \(x\)-axis and \(y\)-axis which are bounded to the range from \(-4\) to \(4\) each. The following two elements are definitions for a variable and the basic function \(f(x)\text{.}\) Alone they have no graphical output, but are only referenced in later drawing commands. More precisely, graph command draws the function \(f\text{,}\) while the tangent-line element draws the tangent at the point \(f(1)\) as we have previously defined \(a=1\text{.}\) Finally we explicitly draw this tangent point with the point element, giving it a mathematical label of \((a, f(a))\text{.}\) Note, that this label is given in LaTeX code and can be of any complexity as it will later be processed and typeset by MathJax.

Here the graph and the tangent line commands are grouped together with a group element. This works similar to its SVG counter part g and ensures that semantically related elements are grouped together in the resulting SVG diagram and that they can be annotated as a single, abstract element. In addition, each element can contain an id which allows the author to provide a individual, manual annotation as we discuss next.

The vocabulary currently supports the creation of mathematical diagrams that could appear in algebra and calculus textbooks. Some capabilities exist to create diagrams in other mathematical disciplines, such as linear algebra and discrete mathematics, and we plan to expand these capabilities and allow for the creation of three-dimensional content.

Annotations are included separately from the graphical descriptions since the order in which elements are drawn may differ from how they are traversed in a screen reader. The set of annotations forms a hierarchical structure that begins with a global description of the diagram and proceeds inward by nesting annotations to examine graphical elements in greater detail. This provides the basic interaction model that we use to allow readers to explore the diagram in detail, as we will discuss in the next section. Many common elements are annotated automatically, leading to a standardised user experience for VI learners—or authors inspecting the diagram during the creation process—when screen reading, exploring or sonifying a diagram. Nevertheless authors can also provide bespoke manual annotations directly.

The annotations that accompany our example diagram are given in Listing 2.2. Note how the ids of the annotations either refer to element ids in the diagram specification or to standard names of elements such as grid and axes. The annotations define the layers of detail for the diagram, which can be arbitrarily deep. In the example we have a nesting depth of three: The top-most annotation provides a summary of the figure, followed by the description of the tangent graph. The latter is again broken down into the three component of graph, tangent line and tangent point, which reflect the drawn elements in the diagram as specified in Listing 2.1. We see that description for the other the main components, the axes and the grid are not explicitly given. Those will be programmatically generated and included automatically. They could, however, be overwritten manually.

<annotations>
<annotation
id=
"figure"
text=
"The graph of a function and its tangent line at the point a equals 1"
>
<annotation
id=
"graph-tangent"
text=
"The graph and its tangent line"
>
<annotation
id=
"graph"
text=
"The graph of the function f"
sonify=
"yes"
/>
<annotation
id=
"point"
text=
"The point a comma f of a"
/>
<annotation
id=
"tangent"
text=
"The tangent line to the graph of f at the point"
/>
</annotation>
</annotation>
</annotations>

In addition to the single text attributes, anotation elements can also have a secondary speech attribute that allows the author to provide more details on a particular element. Other attributes allowed are a flag to indicate that a graph should be sonified or that the children of an annotation should form a circular structure. The latter can, for example, be used in graphics like the unit circle or the network graph in Figure 1.1 to allow for circular navigation of the points of the circle or cycles in the graph.

A Python script processes the XML input into SVG graphical elements and creates the annotation hierarchy in accompanying XML. Additional graphical elements are included by default to improve the diagrams' accessibility. For example, a clear rectangle is included behind a label so that background features do not interfere with the label's legibility. Mathematical labels are processed using MathJax and placed automatically relative to a specified anchor. Braille labels created by MathJax are carefully positioned for accurate rendering on an embosser.