Skip to main content

Section 4.20 Notation

We continue the introduction at Section 3.22. A notation list, like an index, is a specialized collection of cross-references. So some of the philosophy here applies equally well to the <idx> and <index-list> elements, and vice-versa. (See Section 4.19.)

To generate a list of notation employed in a book or article, use the <notation-list/> element. This empty element belongs in an <appendix>. Likely it is the only content, or you might include some preliminary material. The title of the <appendix> is up to you and is not automatic.

Some authors like to make definitions inside of paragraphs, ideally using a <term> element. This is a natural place for a <notation> element. So this approach gives an author a lot of flexibility in location.

Other authors like to make definitions using the <definition> element, since it creates a heading and number, allows a <title>, and can easily serve as the target of a cross-reference. So this is another good place for a <notation> element. But now, associate it clearly with the <defintion> by placing it in the metadata, early on, after the <title>. And not in some subsequent paragraph. The reason will be clear in just a bit.

How is a <notation> element constructed? It has two elements. The <usage> should be a sample piece of mathematics using the necessary symbols, and wrapped in a single <m> element. The second element is <description> and should be a short phrase, or sentence-like material, decoding the sample usage, and may include <m> elements. The reader sees nothing in the output at the location of the <notation> element.

The automatically-generated notation list is then a three-column table, in the order of appearance, with the sample usage, the description, and a locator. For output derived from , such as print or PDF, the locator will be the page number of wherever you placed the <notation> element. For HTML the locator is much better—it is a knowl, for either a paragraph or for an entire definition. The latter possibility explains why it is better to place the <notation> element inside a <definition>, if possible, rather than in a paragraph that is a constituent of a <definition>.