Abstract

This article discusses best practices for web-based, expository mathematics.

Publication Data

• Published May, 2006
• Revised February, 2007

Many of the words that have been used for decades to describe expository publications in mathematics no longer make sense in the digital age:

• Authors are no longer just those whose works are printed in books and paper journals by commercial or institutional publishers. Increasingly, ordinary teachers and students create, re-use, and post expository mathematics on school web sites.
• One posted, these works are published in the sense that they are immediately accessible to persons throughout the world. In principle, any school web site has the same reach as JOMA or the MAA. Professional journals and societies are no longer the gatekeepers of scholarship.
• Web-based expository documents are no longer papers consisting of text (and the occasional figure) printed on paper. Increasingly, these documents combine expository text, rich graphics, audio and video clips, interactive mathlets, worksheets, source files, and other elements--elaborately hyperlinked to each other and to myriad other resources on the web.
• Writers must do much more than just write. They must also program (often in several languages), compile, link, and design.
• Readers do much more than just read. They also listen, watch, compute, and interact. In fact, the users of web documents are not just persons. At an intermediate level, web documents must be processed by hardware and software agents of all sorts: standard computers, hand-held devices, printers, search engines, mathematical software, and devices to help disabled persons.

Writing expository, web-based mathematics is difficult. As already noted, an author not only needs to have a deep understanding of the underlying mathematical topic and good general writing skills, but also programming skills, technical expertise, design skills, and an appreciation for the new possibilities that web technologies afford.

In the pages that follow, we will discuss "best practices" for expository mathematics in the digital age. Our hope is that this discussion will be helpful, not only for potential JOMA authors, but for ordinary teachers and students as well. Again, whether we publish in journals or not, many of us are authors and users of web-based materials.

For general web document, some basic "best practices" are now widely accepted by experts, although still largely unknown by average authors. Naturally, these general practices apply to mathematical exposition as well. By and large, they are based on two core principles: access and reuse.

Accessibility refers to the extent to which a web document can be processed by a variety of devices (hardware and software), depending on the user and the purpose, and with particular attention to persons with disabilities. To elaborate on our previous list, such devices include

• ordinary computers with different platforms (hardware, operating systems, browsers).
• hand-held devices such as PDAs, small tablet PCs, iPods
• printers
• readers for visually impaired persons
• audio-to-text devices for hearing impaired persons.
• search engines
• computer algebra systems that could process the mathematics in the document

Reuseability refers to the ease of breaking a web document into separate parts that have value on their own, and can be reused by the author and by others. For mathematical articles, such components might include

• fragments of expository text
• mathematical expressions
• mathlets
• graphics
• audio and video clips
• worksheets in Mathematica, Maple and similar programs
• source files for programming languages

For mathematical exposition, "best practices" are still evolving. JOMA hopes to encourage the discussion and to play a significant role in the formulation of these practices.

One of the most important principles in writing web documents is the separation of content and presentation. Content refers to the mathematical and expository information that the author wants to convey to her readers. Presentation by contrast refers to the style in which the information will be conveyed. Content is of paramount importance, presentation much less so. The separation of the two is valuable for a number of reasons. First, it allows the author to concentrate on what's most important, the content, and to worry about matters of style later, and separately. Second, the separation leads to documents that are much more accessible. Keep in mind that a web document might be rendered on a standard computer screen, or on a small screen in a hand-held device (a PDA or a small tablet PC), or printed, or rendered aurally for someone with impaired vision. Thus, how a document is presented depends very much on the presentation device.

In the case of articles for JOMA (or other online journals), many issues involving presentation will be decided by the editorial staff (as is the case with print journals). Thus, work by an author on issues that are purely matters of style is wasted effort. Finally, regardless of what the author or editors think is best, a reader (or processing software) may well override style issues at the point that the article is actually rendered. (A user can easily change font sizes in her browser, for example).

On the other hand, it is not always easy to decide whether an issue involves content or presentation. At JOMA, we believe that matters of document structure--the organization of the document into web "pages", whether pages are rendered in full windows or pop-up windows--fall more into the content category, and should be left primarily to the judgement of the author. As we have noted before, one of the goals of JOMA is to promote expository articles with innovative and effective document structures.

HTML Tags

I have already argued that HTML should be the basic language for the expository part of an article. So, how does one separate presentation from content? First, to the extent possible, use mark-up tags that give information about content and structure of the document rather than simply specifying style. For example, the tag for a definition, the tag (for a citation), the tag (for a variable), and the tag for emphasis all have italics as the default rendering. But these tags give useful information about the words that they enclose, unlike the tag for italics.

Conversely, avoid using tags, such as (for italics), (for bold), (for a font specification) that only specify style. Rather than putting a phrase in italics or boldface or a particular font or a particular color, ask yourself why you want to do so, and then use the appropriate content tag: Is the phrase a definition? Is it a citation? Is it to be emphasized?

The presentation of any HTML tag (including style tags) can be specified with an external style sheet. For example, a style sheet might specify that phrases within the tag actually be rendered bold and red. Style sheets for HTML documents are ordinarily written in the Cascading Style Sheet (CSS) language, another standard, text-based, open-source markup language.

Finally, do not use content tags to achieve presentation effects. For example, the default rendering of a phrase in the

The Chebyshev polynomials are everywhere dense in numerical analysis.

But this tag is intended for a quotation, not for indention. It's wrong to mark-up a phrase that is not a quotation with this tag, just so that the phrase will be indented.A program that processes the source file (a reader for the blind, for example) will expect a phrase marked-up by this tag to be quotation.

For more information, see Mathematics with Structure and Style.

Proprietary Formats

It's interesting to note that in proprietary formats (Word and PDF, for example), the separation of content and presentation is difficult, if not impossible. The two are inextricably linked, often by design--it's one of the ways that users are often forced into using proprietary tools. This is another reason to avoid using such tools for basic exposition.

Many many web-based, expository mathematics articles will contain worksheets or source files for mathematical software such as Mathematica, Maple, Matlab, or Excel, to name just a few. For maximum accessibility, an author should use text-based, open-source formats when this can be done without harming the mathematical exposition. When open source formats are not sufficient, the author may be able to provide a generic description of the source file so that a reader can convert the worksheet to the format of her choice.

For example, a simple data set (with variables and cases) should not be given in Excel format (which is proprietary), but should be given as a simple tab-separated text file. This standard format encodes all of the essential information of the data set, and can be used with any statistical software (including, of course, Excel). If an article has a more complicated spreadsheet file (with data and embedded formulas, for example), the author could still provide the file in the open document format (text-based, XML files, compressed into a ZIP file). An article with Mathematica worksheets could give HTML versions of the worksheets that a reader could convert to other computer algebra systems.

Here's a good way to think of this issue: the author should be free to use the tools of his choice in creating documents, but these should provided in open-source formats if possible, so that the reader can use the tools of her choice in processing the documents.

Mathematical notation has always presented a special problem for authors of web-based expository articles. There are several possible solutions.

HTML Markup

HTML provides only limited mark-up for mathematics--mainly the tag for a variable, and the and tags for subscripts and superscripts, respectively. Here is a sample mathematical expression rendered with basic HTML:

y = a₀ + a₁x + a₂x²

For an article with relatively simple mathematical notation, these basic HTML tags may be sufficient.

Graphics

A common approach is to convert mathematical expressions into small graphics (typically in the PNG or GIF format). The graphics can be created with special tools (such as MathType) or with special converters (such as TeX to HTML). There are several drawbacks, however. First, the article is junked-up with possibly hundreds of images. A mathematical expression cannot be edited, without replacing the entire image. Style attributes that are applied to surrounding text (font type, weight, color, size) would not work on the images. Finally, the mathematical structure, the information contained in a mathematical expression, is completely lost and cannot be processed by software or hardware agents. In fact, "best practices" would require alternate text-based descriptions of the mathematical expressions (in TeX or MathML, for example), attached via the alt or title attributes of the tag.

Proprietary Formats

Another common solution is to use proprietary formats (Word or PDF) for the basic exposition. We have already argued against this approach. To repeat the arguments, the user is locked into using proprietary tools to view the materials, and much of the inherent interactivity of the web, derived from HTML, is lost. The article suffers greatly in terms of the two core principles--access and reuse.

MathML

In my opinion, the best solution is MathML, the Mathematics Markup Language. MathML is essentially an extension to HTML that provides a very complete specification of mathematical notation. MathML is an open source, W3C standard and is now supported by the Mozilla Firefox browser and by the latest versions of Internet Explorer on the Windows platform via the free MathPlayer plug-in. Moreover, in keeping with the best practices discussed previously, MathML encodes the structure of the mathematics much more completely than previous mark-up languages (such as TeX). Because of this, mathematical expressions in MathML can be imported from one MathML-aware program (an HTML document, for example) to another (Maple, for example). On the downside, MathML is difficult to author without special editing tools (precisely because so much information is encoded), and MathML is not supported on older browsers.

MathML is the future of mathematics on the web. In spite of the difficulties, a major goal of JOMA is to promote and encourage its use. For more information, see Mathematics with Structure and Style.

Authors of web-based, expository mathematics should use technology appropriately. An author may be able to create a document that uses JavaScript or Java for navigation with fancy buttons, for example, but this is bad practice. Navigation is a basic feature of HTML. Using Java or some other sophisticated technology for this purpose limits the accessibility of the article and makes the article more fragile in terms of bugs or crashes. These costs come with no real benefit. On the other hand, Java is perfectly appropriate for an interactive mathlet that illustrates a mathematical concept in ways that are impossible with static text. To give another common example, it's bad practice to use a graphic image to simply display text; the information in the text is lost to processing software. In short, use the simplest technology appropriate for a given purpose.

Best practices related to mathlet design are also motivated by the core principles of access abd resue. The suggestions below are adopted from IBM Guidelines for Accessible Applications.. These guidlines are intended for applets generally, not just mathlets.

Make your mathlet keyboard accessible. A good exercise is to see how well the mathlet works with the mouse unplugged.

• Provide keyboard equivalents for all actions.
• Observe operating system keyboard conventions (copy, paste, slow keys, sticky keys)
• Set mnemonics on components (Alt-F for file, Cntl-C for copy)
• Use accelerators for common functions (Cntl-P for print, Escape for cancel).
• Provide a logical keyboard tabbing order (so that the user can shift the focus to the control of her choice).
• Provide electronic access to keyboard navigational documentation.

Provide alternatives to significant audio and video.

• Provide a visual indication of sound and audio cues.
• Provide text captioning of the voice track in video content.
• Provide descriptive graphics for significant audio.
• Provide descriptive text for significant video.

Provide accessibility relationships

• Label Components
• Name Logical Groups
• Provide Semantic Relationships

What are other best practices for mathematical exposition? Here there are more questions than answers, but again, one of the goals of JOMA is to encourage the discussion.

In particular,

• What are best practices specific for mathlet design, as opposed to other applets?
• What are the best practices for "non-linear" document structures? What are the best designs for mathematical exposition that has multiple, branching paths?

Resources from the W3C

The World Wide Web Consortium (W3C) is the official standards body for the web.

1. Hypertext Markup Languagne (HTML)
2. Cascading Style Sheets (CSS)
3. Mathematics Markup Language (MathML)
4. HTML Validator
5. CSS Validator
6. Core Techniques for Web Content Accessibility Guidelines.
7. Quality Assurance

Other Resources

8. IBM Guidelines for Accessible Applications.
9. US Government Section 508 Site