The Journal of Online Mathematics and Its Applications

Volume 7. February 2007. Article ID 1431

Mathematics with Structure and Style

Kyle Siegrist

Abstract

This article discusses how to use HTML, CSS style sheets, and JavaScript to produce mathematical documents that are well-structured, conform to best practices, and look good. We also provide a number of basic tools to help authors: a basic style sheet and script file, HTML and XHTML templates, and GIF images of mathematical symbols.

Keywords

Subject classification

  1. 00 general
  2. 00A miscellaneous
  3. 00A20 reference works

Main Contents

  1. Introduction
    1. Mathematical Documents in the Digital Age
    2. Best Practices
  2. Basic Languages
    1. HTML
    2. CSS
    3. JavaScript
  3. Basic Guidelines
    1. Head Information
    2. Content and Presentation
  4. Large Structures
    1. Front Matter
    2. Mathematical Structures
  5. Links and Navigation
    1. Links
    2. Directional Issues
    3. Navigation
    4. Reference Lists

Sample Documents

Ancillary Materials

1. Introduction

The purpose of this article is to help authors prepare mathematical documents for the web--authors generally, not just JOMA authors. We go beyond the issue of mathematical notation and discuss the structure of mathematical documents.

1.1 Mathematical Documents in the Digital Age

Mathematical documents, even expository ones, are typically more formal than most documents on the web. In addition to standard document structures such as sections and subsections, many will have the well-defined and somewhat specialized elements that are traditional in mathematics. These include

In addition, web-based mathematical documents should (and often do) have elements that go beyond what is possible with printed documents. Some of these are

1.2 Best Practices

We do not presume, in this article at least, to tell you how to write mathematical content, either for research or expository articles. However, from a technical point of view, many "best practices" are widely accepted by experts, even if little known in the mathematical community. Most of these best practices deal with the interrelated issues of access and re-use.

We want you to keep an important point in mind. Although ultimately you are writing mathematical documents for your colleagues or students, at an intermediate level you are writing for various software and hardware processing agents:

No one will see or use your documents unless these processing agents work correctly first. So what are the best practices?

Separate content from presentation

Content refers to the basic information and data that you are providing your readers. Presentation refers to the how that content is rendered. Separating the two allows you (the author) to concentrate on what's most important (the mathematical and expository content) and worry about matters of style later, and separately. Your source documents are clean and uncluttered. Besides, you may well need different types or presentation for different devices. The best way to display the document on a computer screen may be very different than the best way to print the document.

Use metadata

Metadata are bits of information about your document, usually invisible to the reader, but often essential to those agents that are processing the document (readers, search engines, etc.). At the very least, you should provide the following metadata for your documents:

Write good code and validate it

Yes, if you are going to write good mathematical documents for the web, then you need to think of yourself as a programmer, at least in a broad sense, and regardless of the authoring tools that you use. The languages that we will discuss in this article (HTML, CSS, JavaScript) are all computer languages, each with a precise syntax. But that's not new. Mathematicians have used TeX (and its higher order variant LaTeX) for decades to write mathematical documents for print and electronic journals. Moreover, TeX is a compiled language that must be syntactically correct before any output can be produced. By contrast, the languages we will discuss are interpreted languages. Modern browsers are amazingly forgiving, often producing useable output from even the most horribly butchered code. So why bother to write good code? You should want to produce good code for the same reason that you want to write correct proofs--mathematicians often value correctness and clarity above all things. Also, you don't want to leave it up to the browser to guess what you mean. Finally, those other processing agents (readers, search engines) may not be nearly as tolerant as browsers. Finally, XML-based compound documents with MathML and other embedded languages (the future of mathematics on the web) are required to be syntactically correct.

Provide alternative descriptions

Presumably, you want your document to be as accessible as possible, to users with disabilities, and to users with various hardware and software configurations. Here are some simple things you can do.

Here are a couple of good exercises that you can use to judge the accessibility of your document.

Use the simplest technology appropriate and use open, standard formats when possible

You want your document to "degrade gracefully" if some of the technologies fail or are inaccessible to a user. Here are some basic "do's and don'ts"

2. Basic Languages

It's well beyond the scope of this article to discuss HTML, CSS, and JavaScript in detail. However, if you are going to write web documents, and in particular, mathematical web documents, there are a few basic concepts that you must understand, regardless of the authoring tools that you use.

2.1 HTML

HTML (the HyperText Markup Language) is the lingua-franca of the web. You should not think of it as simply a language for producing formatted text. It does that, of course, but the real power and value of HTML derive from the fact that all sorts of other elements can be embedded in it (graphics, mathlets, other markup languages), and because rich, semantic information can be included. Think of HTML as the basic expository glue of a mathematics document on the web.

HTML is basically an object-oriented language. The language has tags that create document objects such as headings, paragraphs, tables, lists, images, links, horizontal lines, and so forth. The tags are of two basic types: binary tags have opening and closing parts that enclose text.

<p>This markup creates a short paragraph.</p>

Unary tags do not enclose text: the following markup inserts an image with filename "myGraph.png".

<img src="myGraph.png" />.

Each tag has a number of attributes that can be set, depending on the type of object. Typical examples are border (for a table or image), color (for a font or a line), src (the source reference for an image), and href (the protocol and URL for a link).

Every object (tag) has two attributes that are fundamentally important: class and id. The class attribute allows us to create sub-classes of objects. These sub-classes help refine the structure of our document, and as we will see, allow different presentation. The id attribute allows us to give a unique name to an object, so that we can link to the object, or even find and manipulate the object programmatically (with JavaScript, for example).

Exercise 1

Look at the source code of this page (available from your browser's View menu). Note the general syntax of the HTML tags and their attributes.

Obviously, HTML, as a general purpose markup language, cannot include tags for specialized disciplines, such as mathematics. There is no theorem tag, for example. However, there are two general purpose tags that allow us to create our own objects, in a sense; these are the <span></span> and the <div></div> tags. Roughly, the <span></span> allows us to encapsulate small bits of text (an inline mathematical expression, for example), while the <div></div> allows us to encapsulate block level chunks (a theorem, for example).

An HTML document is technically a rooted (and therefore ordered), labeled tree. (What mathematician can't appreciate that?). The root of the tree is the html tag, and immediately below are head and body tags. The children of the body node are typically headings, paragraphs, lists, tables, and so forth. A list has list items as children while a table has table rows as children which in turn have table data as children. Well, you get the idea. The structure of this tree is referred to as the Document Object Model (DOM).

Exercise 2

If you are using the Firefox browser, explore the document object model of this page using the DOM Inspector, available from the Tools menu. If you are not using Firefox, please consider using it instead of, or in addition to, your regular browser. Because of its support for MathML, CSS, SVG and other standard technologies, Firefox is unparalleled as a browser for mathematical web documents. In the meantime, you may view a screen shot of the DOM Inspector.

2.2 CSS

CSS (Cascading Style Sheet) is a style language that is used to control the presentation of HTML documents. Essentially, statements in CSS assign style conditions to HTML elements. Different style conditions can be applied to subclasses of an element or to elements with a particular id attribute. This is the reason for the term cascading in the title, and one of the reasons that the class and id attributes are so important in our HTML markup.

To give you an example of CSS syntax, here are the style attributes, in our style sheet, for the <var></var> tag and for the vector subclass of the <var></var> tag:

var {
    font-style: italic;
    font-weight: normal;
}
var.vector {
    font-weight: bold;
}

As you can probably guess, text enclosed in the <var></var> tag is rendered in italic style with normal font weight. However, for text enclosed in the <var class="vector"></var> tag, the normal font weight specification is overridden in favor of the bold font weight specification. However, the italic style is still in effect (it's inherited, in language of Object Oriented Programming).

Exercise 3

If you are using the Firefox browser, open the DOM inspector. In the left pane, select Stylesheets. In the upper right pane, the various HTML objects are displayed. If you select one of these, the style attributes appear in the lower right pane. Explore the style attributes of some of the HTML objects in this way. If you are not using the Firefox browser then--well, why aren't you? In the meantime, you may view a screen shot of the DOM Inspector

Exercise 4

Open the CSS style sheet for this web page. Note the general syntax.

2.3 JavaScript

JavaScript is a powerful scripting language that can be used to extend the basic capabilities of HTML and to manipulate objects in the DOM. JavaScript is a web standard; the actual standards name is ECMAScript, named for the standards organization ECMA International

One of the most basic uses of JavaScript for a typical document is to open an ancillary page in a small pop-up window without the usual menu bar, navigation tools, and address field (sometimes referred to as a window without chrome). Here is the function in our script file that does that:

function openWindow(address, windowName, w, h){
    newWindow = window.open(address,windowName,
        "toolbar=0,location=0,directories=0,status=1,menubar=0,scrollbars=2,resizable=1,
        width=300,height=200,top=20,left=20");
    newWindow.resizeTo(w,h);
    newWindow.focus();
}

If you are familiar with Java or similar programming languages, you can probably guess what this code does: it opens a new window and loads a page with the URL given in the address variable. The window is not given a toolbar or menu bar, but is given scrollbars and can be resized. The window is initially sized to the width and height given by the w and h variables, and finally given the focus so that it appears on top.

Our script file also includes a function that can extract any element in the DOM with an id attribute, and display this element in a popup window. This is not a particularly useful function, but it illustrates the interaction between JavaScript and the DOM. For example, please view Exercise 2

Exercise 5

Open the DOM Inspector. Select DOM Nodes in the left pane and JavaScript Object in the right pane. Select various nodes on the left and note the bewildering collection of JavaScript functions and attributes that correspond to that object. By now, we're assuming that you're using the Firefox browser, but if not, you may view a screen shot of the DOM Inspector

JavaScript is also a very powerful tool for creating interactive mathlets, particularly in combination with images and HTML form elements (buttons, list boxes, input fields, etc.). It's well beyond the scope of this article to explore this in detail. However, for an example, try the Venn Diagram mathlet.

3. Basic Guidelines

The very first part of an HTML document (up to and including the <html> tag) contains declarations about the type of HTML, the language encoding, and similar information. These declarations vary depending on whether other languages (such as MathML or SVG) are embedded, so we treat this topic in the individual sample articles (see the table of contents).

The <head></head> part of the HTML document contains basic information about your document, including the <title /> tag for the title of the document, the <meta /> tags for metadata, <link /> tags used to link the document to other documents (particularly the style sheet), and <script></script> tags, used for JavaScript.

We recommend that you have metadata for authors, keywords, a brief description, and date, at a very minimum. You will also need references to the style sheet and script file. Thus, the head information might have the following form:

<head>
<title>Document title</title>
<meta name="author" content="Authors of document" />
<meta name="Keywords" content="keyword list" />
<meta name="Description" content="Brief description" />
<link rel="stylesheet" href="stylesheetURL" type="text/css" />
<script src="scriptFileURL" type="text/javascript"></script>
</head>

3.2 Content and Presentation

Remember that style and presentation issues are to be handled with the style sheet. Thus, avoid HTML tags that deal only with presentation. For example, there are no good reasons to use any of the following:

Similarly, do not use tag attributes that deal only with style (since, again, this should be handled by the style sheet). There are no good reasons to use any of the following attributes for example:

On the other hand, you should use content tags that give appropriate information about the enclosed text:

Remember that if you don't like the default style associated with these elements, then you can easily change them with the style sheet.

Of course, you will inevitably use block-level tags, such as headings, paragraphs, lists, and tables, to structure your document. In particular, HTML provides a rich collection of list types (unordered lists, ordered lists, and definition lists) and lists can be nested.

Moreover, you can sub-class any HTML element to refine the structure of your document, or to use special styles. For example, you might have subclasses of the <code></code> tag for Maple code, Java code, etc.

But do not use content tags to achieve presentation effects:

4. Large Structures

We use the term large structure to refer to any well-defined structure within your document that consists of more than one block-level element. Typically, general document structures such as sections and subsections fall into this category, as do special mathematical structures such as theorems, proofs, examples, exercises, etc. As a rule of thumb, you should encapsulate any large structure in your document with a <div class="objectClass" id="idName"></div> tag. As always, we gain two important benefits from this approach:

4.1 Front Matter

Front matter refers to the special document elements that occur before the main body of the document, such as the abstract, keyword list, table of contents, etc. You may or may not have such elements, but if you do, they should be marked as objects. Then, the entire front matter could be enclosed in <div class="front"></div>, like any large structure should be.

Except for the title and author information, the front matter is rendered by our style sheet in a slightly smaller font and with slightly larger margins. But of course, you could change any of this.

Title and Author Information

Title and author information might be marked using special classes of headings as follows:

<h1 class="title">Article Title</h1>
<h2 class="author">Name of author</h2>
<h3 class="department">Author's department</h2>
<h3 class="institution">Author's institution</h3>
<h3 class="date">Date</h3>

This can be modified in a straightforward way to include additional information, to delete information, or for multiple authors. For example, you might want to include address or date information.

Abstract

The abstract might be marked as follows:

<div class="abstract" id="Abstract">
<h4>Abstract</h4>
···
</div>

The body of the abstract might consist of several paragraphs or even other block level elements such as lists. Remember to give the abstract an id attribute if you want to refer back to it.

Keywords

The list of keywords might be marked as follows:

<div class="keywords" id="Keywords">
<h4>Keywords</h4>

<ul class="keywords">
    <li class="keyword>Keyword 1</li>
    <li class="keyword>Keyword 2</li>
    <li class="keyword>Keyword 3</li>
</ul>
</div>

Note that the list of keywords is marked in this example as an unordered list (because that's what it is), even thought our style sheet renders the list as a single row, without bullets or other embellishments.

Subject classification

Typically, an article will have a subject classification relative to some given taxonomy. This could be marked as follows:

<div class="subjects" id="Subjects">>
<h4>Subject classification<</h4>

<ol class="subjects" id="Subjects">
    <li class="subject>Subject 1</li>
    <li class="subject>Subject 2</li>
    <li class="subject>Subject 3</li>
</ol>
</div>

Note that the subject classification is marked as an ordered list, even thought our style sheet renders the list as a single row, without numbers or other embellishments.

Table of Contents

A typical table of contents might be marked as follows:

<div class="contents" id="Contents">
<h4>Main Contents<</h4>

<ol>
    <li>Section 1</li>
    <li>Section 2</li>
    <li>Section 3</li>
</ol>

<h4>Ancillary Topics</h4>

<ul>
    <li>Topic 1</li>
    <li>Topic 2</li>
    <li>Topic 3</li>
</ul>
</div>

This is intended as an example only. Web article can have very complicated, "nonlinear" structures, with multiple threads and various types of ancillary materials. Your table of contents might involve nested lists or several different lists. Remember to give the table of contents an id attribute so that you can link back to it.

4.2. Mathematical Structures

Special mathematical structures such as definitions, theorems, etc. typically involve several block-level HTML objects, and hence are created as subclasses of the generic <div></div> tag. For example, the first theorem in the article might be marked as follows;

<div class="theorem" id="Theorem1">
<h4>Theorem 1</h4>
···
</div>

The body of the theorem can have several paragraphs or other elements such as lists, displayed mathematical expressions, etc. Note that the theorem belongs to the general class of theorems, so that all theorems can be styled in a special way, and the theorem has a unique id attribute so that you can link back to it.

The following subclasses of <div></div> are defined in our style sheet, and all work in roughly the same way.

As always, you could add other classes and you could change the style attributes.

5. Links and Navigation

Linking is a tricky issue in web documents. As we noted early, a mathematics article might have several "threads" of discussion, usually would have ancillary material (inessential notes, media clips, mathlets, proof details), and almost always would have links to external sites on the web. The author should give the user clues about the various types of material. Typically, the author wants an external page to open in a separate browser window or tab, so that the user understands that the page is not part of the article (or at least is not under the control of the author). Similarly, the author might want an ancillary page to open in a separate browser window or tab, so that the user is not distracted from a main discussion thread. On the other hand, the user might still get lost if there are too many browser windows (or tabs) open, and no sense of hierarchy among these windows. As an alternative, the author might want an ancillary page to open in a small pop-up browser window without the usual menu bar, toolbar, and address bar (sometimes referred to as a window without chrome). Launching such a window cannot be done with simple HTML, but is very easy with JavaScript.

Our stylesheet defines three classes of the <a></a> tag, with class names "internal", "external", and "ancillary". The target="_blank" attribute assignment should be used for a link that should be opened in a separate window, and the title attribute can give the reader a tool-tip that the link is to an external site. You can use our JavaScript file to open an ancillary page in a pop-up window without chrome. Use the following syntax:

<a href="JavaScript:openWindow('URL', 'windowName', w, h)" class="ancillary">link material</a>

where URL is the address of the ancillary page, windowName is the name that you want to given the window, in case you need to refer to it in other JavaScript commands, w and h are the width and height (in pixels) that you want for the pop-up window, and where link material is the material to be linked to the ancillary page (this could be text or images).

Exercise 6

Please see the table of mathematical symbols. Note that this page opens in a pop-window without chrome.

Ordinarily, you should not have links in an ancillary page that is displayed in a pop-up window, except perhaps to other ancillary pages of the same type. Recall that the pop-up window lacks basic navigational tools (forward and backward buttons, address toolbar, etc.), and by definition, the page is not part of a main discussion thread.

5.2 Directional Issues

A web page displayed in a browser window has well-defined top and left sides, but not bottom and right sides. Western text, at least, is read from top to bottom and from left to right. Much of the time, some of the material in the page will be hidden below the bottom of the browser window. Less frequently, but still often, material will also be hidden beyond the right of the browser window. (Of course, the user scrolls down and to the right to get to this material.) A web "page" (file) may actually be many printed pages, perhaps dozens. These facts imply several good practices, obvious on reflection but often overlooked:

Of course, you should use an id attribute for any labeled object, including mathematical expressions, graphics, and tables, so that you can link to these objects.

Navigating users through your article is also a complicated issue, particularly if your document has multiple threads and ancillary material. One commonly accepted practice is to provide a "you are here" sequence of links that explains the location of a page in the overall article. This sequence is typically located at the top of the page. At the bottom of the page, you probably want to give links to where the user should go next (possibly several different places) and links to where the user has come from (again, possibly several different places).

Our style sheet provides basic "header" and "footer" subclasses of the generic <div></div> tag for navigational information. Navigational text is rendered in a sans-serif font with a slightly smaller font size.

5.4 Reference Lists

It's a good practice to have a complete list of references for your document, including both links to external web sites and printed works. When referencing an external site in the body of the article, some authors link to the reference list (which then links to the external site), rather than linking directly to the site. However, this is not the behavior that most readers would expect, requires an extra click, and takes the reader away from the main document. A better practice is to have two links--one directly to the external site (opening in a new window or tab, of course), and one to the reference list. Here's an example: please see the W3C Math site [references] for more information about MathML, the Mathematics Markup Language.

Beyond this basic recommendation, we offer no prescriptions for reference lists. Like the table of contents, the collection of references may be very complex and the best structure may depend on the type of document, perhaps involving multiple lists or nested lists, ordered and unordered.