Section What You, the Author, Must Do
Two areas require deliberate effort: images and interactives. Everything else is a byproduct of writing clean semantic markup.
Subsection Images Need Alt Text
Every informative image needs a
<shortdescription>. This becomes the alt attribute in HTML and the described content in EPUB and Braille.
<image source="figs/graph.png" width="60%">
<shortdescription>
A graph of f(x) = x squared on the interval [-2, 2],
showing a parabola opening upward with vertex at the origin.
</shortdescription>
</image>
For images that carry substantial information (complex diagrams, data tables presented as images, and geometric constructions), add a longer
<description> element as well. It appears in the HTML as an expandable region that sighted readers can ignore and screen-reader users can access.
<image source="figs/venn.png" width="60%">
<shortdescription>
Venn diagram of sets A, B, and A intersect B.
</shortdescription>
<description>
<p>
Two overlapping circles. The left circle is labeled A
and contains the elements 1, 2, 3. The right circle is
labeled B and contains 3, 4, 5. The overlapping region
contains 3, representing A intersect B.
</p>
</description>
</image>
A natural question: why can’t PreTeXt generate alt text automatically? Because image descriptions depend on context and intent. The same graph might need one description in a section about asymptotes and a different one in a section about symmetry. No tool can reliably make that call.
A second principle: don’t rely on color alone. If you ask students to compare the red and green curves, also distinguish them by dashing, thickness, or labels. A quick test is to view the figure in grayscale and check that it still makes sense.
Subsection Interactive Elements Need a Prose Fallback
GeoGebra, Desmos, and similar embedded applets are visual by design and not reliably screen-reader accessible. When you include one in a document you intend to be fully accessible, surround it with a paragraph that describes what the interactive shows and what a student is meant to observe. That way the conceptual content is available even to a reader who cannot run the applet.
PreTeXt’s native exercise types (multiple choice, true/false, fill-in-the-blank, and matching) are keyboard-accessible and screen-reader friendly.
Subsection A Short Pre-Publication Checklist
- Every informative image has a
<shortdescription> -
Purely decorative images should carry an empty
<shortdescription/>. - Complex images have a
<description> -
Diagrams, graphs, and data figures need the longer form.
- Interactive applets have a surrounding prose description
-
Students who can’t run the applet can still learn from the text around it.
- Figures don’t rely on color alone
-
Use dashing, thickness, or labels as secondary distinctions.
- Cross-references use
<xref>, not bare URLs -
Semantic cross-references produce meaningful link text (“Definition 3.2”) rather than raw URLs.
- The document builds without errors
-
A build error may render correctly for sighted readers but produce broken ARIA or heading structure underneath.
