Skip to main content

The PreTeXt Guide

Robert A. Beezer, David Farmer, Alex Jordan, Mitchel T. Keller

Section 4.37 Accessibility

Continuing our discussion from Section 3.28 we begin by listing features of our conversion to HTML which happen automatically. These come in part from the recommendations at the Web Content Accessibility Guidelines 35  of the Web Accessibility Initiative.
HTML
Wherever possible we supply HTML elements and attributes that will be interpreted sensibly by a screen reader in the absence of the visual styling provided by CSS. This means we are very careful about the role of headings (h1 through h6) for screenreaders, both for divisions and the block elements they contain. We provide HTML that passes validation checks. And so on. Employing attributes from the Accessible Rich Internet Applications 36  suite of web standards (ARIA) will go a long way to improving accessibility. This work is on-going, as of 2021-11-03.
Mathematics
MathJax (mathjax.org) is the JavaScript library we use to render mathematics within the HTML output. It provides extensive capabilities for screen readers to render the mathematics audibly, and by default your project’s output is configured to take advantage of these features. We refer the reader to the MathJax documentation of Accessibility Features 37  for details. But here is a simple experiment you can do yourself right now to simulate how a blind reader could experience mathematics with the combination of PreTeXt, MathJax, and a screen reader.
  1. Find some moderately complicated mathematics, such as in the “Mathematics” section of the sample article, or your own project, or the sample from MathJax copied below.
  2. Bring up the context menu on that display (a mouse right-click for most).
  3. Turn on the Accessibility > Explorer > Activate menu item. The page will reload, and the Explorer menu item will earn many more menu items. This setting is reasonably sticky, so you should not have to do this repeatedly. Having this on will incur some processing time as part of each page load, so you may want to turn it off later.
  4. Turn on the Accessibility > Explorer > Speech Output menu item.
  5. Turn on the Accessibility > Explorer > Subtitles menu item. (If Subtitles is “greyed out”, try toggling Speech Output.)
  6. TAB until some mathematics is given focus (a discrete border appears).
  7. SHIFT-SPACE will activate exploration of the mathematics with the Explorer. A subtitle, with an aural rendering of the mathematics, will appear below the display.
  8. You can navigate (explore) the expression tree with the up, down, left, and right arrow keys. The subtitles will change as you do this.
From the MathJax demonstration page, Maxwell’s equations for practice:
\begin{align*} \nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} & = \frac{4\pi}{c}\vec{\boldsymbol{\jmath}}\\ \nabla \cdot \vec{\mathbf{E}} & = 4 \pi \rho\\ \nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} & = \vec{\mathbf{0}}\\ \nabla \cdot \vec{\mathbf{B}} & = 0 \end{align*}
3D Images
Asymptote is a language for describing 2D and 3D images, which we support as much as possible. The 3D images produced are rotatable for exploration via a mouse or finger. For those with motor limitations, the images may also be manipulated with keyboard controls. (Many assistive technologies rely on, or emulate, keyboards.)
Skip to Main Content
Repeatedly pressing the Tab key will move a reader from one location to the next in a web document. Since your Table of Contents in the left sidebar is a series of many links, a reader will need to tab through all of these to eventually reach the interesting content on a page.
However, we support a common device. The first link on every page is hidden from all readers, but an initial Tab will present a link labeled Skip to Main Content which when executed will take the reader past the Table of Contents and to the start of the content at the top of the page.
Links
Hyperlinks have colors, styles (such as underlining), and effects (such as mouse hover) which are consistent with WCAG recommendations. Rather than being underlined by default, we instead use high-contrast color choices.
Colors
We are sensitive to the fact that some readers have difficulty distinguishing between certain colors. So we do our best to distinguish text, or other elements, without relying exclusively on color. For example, the <delete> and <insert> elements may render text with strike-through and underlining (respectively) to show the distinction.
But you can help as you author. For example, see Subsection 4.9.6.
Justified Text
Right-justified text (an even right margin) can sometimes lead to spaced-out text that is difficult for some readers. For print, our use of as an intermediate format, leads to PDF output where right-justified text can be superior to the alternative, ragged right text. For more see Section 30.3 and Section 41.10.
Watermarks
If a document has a watermark (Section 26.5), then a screen reader will announce its presence at the beginning of each page of HTML content.
Here are features which are provided, but require your participation as the author.
Image Description
Images you author or supply will be invisible to some readers. Within every <image> element you can use a <description> element. The content here will migrate to places like the HTML @alt attribute to be picked up by screen readers.
Make the content very expressive and detailed, but not overly verbose. Also, do not use any markup whatsoever, just simple characters, and avoid quotation marks. You can learn more at sites such as the one provided by the Web Accessibility Initiative (WAI) at Text alternatives for non-text content 38 .
We cannot do this one for you, this is for the author only. But we can give you the tools do it as easily and as correctly as possible.
Image Formats
University offices that provide services for students with disabilities are often interested in the images themselves from a text, as standalone files. For example, they might be able to manufacture tactile versions. You could use the pretext script to produce a variety of different formats and bundle these up in a single archive file for distribution at your book’s website. Or you can make each image available through adjacent links placed automatically. We call these “image archives.” See Subsection 4.14.5.
Futhermore, as described above, a 3D image authored with Asymptote code can be superior for those with motor disabilities. So this functionality begins with an author’s choice to employ Asymptote.
Cross-References
Section 4.5 describes a variety of ways to customize the look and content of a cross-reference. You can create a larger target for clickable items by making the text as long as possible. So for example an <xref> authored as
<xref ref="theorem-FTC" text="type-global" />
would cause the clickable portion to be something like “Theorem 5.16”, whereas
<xref ref="theorem-FTC" text="global" />
would then cause the clickable portion to be simply the much shorter “5.16”. Of course, you can set a default style for your entire document, so it is not necessary to continually provide the @text attribute.
Link Text
Default link text, such as “Theorem 4.15” has been chosen to be informative. But for internal links (<xref>) or external links (<url>) you can choose alternative content for the clickable portion of the text. Think carefully about your choices here and try to avoid text like “here” or “click here.” For a <url>, the default content is the @href, which can always be improved by providing content.
Here is a device which we now use more frequently. Despite our aversion to footnotes, create a <url> element and provide meaningful content, such as the title of the web page you are referencing. Then immediately afterwards add a footnote (<fn>) which contains only the actual URL, perhaps wrapped in a <c> element. Since this is mostly meant for print, it is safe to drop things like the https:// protocol specification and therefore not make it active (for a second time). This is in use within this section.
Commutative Diagrams
Whenever possible, author commutative diagrams using the syntax of the amscd package. Then online and braille output will be more accessible. See Subsection 4.9.9 for more.
Punctuation after Mathematics
Periods, commas, and semi-colons that follow directly after mathematics are handled differently by PreTeXt for visual formats versus non-visual ones (e.g. braille, audio). But this only happens if you author the punctuation in the logically correct location and let PreTeXt do the rest for you. See Best Practice 4.9.14.2 and Subsection 4.9.14 for details.
Watching a blind reader navigate a web page can be a very enlightening experience. Or you might even undertake learning one yourself. Here are some suggestions for getting started (current on 2018-05-31).
Much of the technical work for accessibility is accomplished by PreTeXt developers. But authors have responsibilities, too. So testing can be part of your workflow. One free tool is axe 39  from Deque Systems 40 .
We have concentrated on making HTML output accessible, since that seems the most natural and best supported. But we are aware of efforts for other formats.
PDF/
A PDF may not lend itself naturally to providing an accessible format. But there have been efforts. The Users Group on PDF Accessibility and PDF Standards 41  is an excellent resource to start with. There is also a PreTeXt issue #1046 42 .
EPUB
The International Digital Publishing Forum has information on EPUB Accessibility 43 .
You have attempted of activities on this page.
www.w3.org/WAI/standards-guidelines/wcag/
www.w3.org/WAI/standards-guidelines/aria/
docs.mathjax.org/en/latest/misc/accessibility-features.html
www.w3.org/WAI/fundamentals/accessibility-principles/#alternatives
www.deque.com/axe
www.deque.com
tug.org/twg/accessibility/
github.com/PreTeXtBook/pretext/issues/1046
idpf.org/a11y
PrevTopNext