Makesymbolindex: A Program for Making a List of Symbols for L^{A}TEX Documents

Andrew D. Lewis andrew@mast.queensu.ca

17 March 1998

1 What is Makesymbolindex?

This program will generate a list of symbols for a L^{A}TEX document. To use it you must have the L^{A}TEX package makesdx. This package is written for use with L^{A}TEX 2ε, but with slight modifications to the package it is possible to use Makesymbolindex with old L^{A}TEX. But why not be current?

We shall briefly explain how to install and use Makesymbolindex in this documentation. The Makesymbolindex setup should come with directories doc, which contains the TEX source for this documentation, and sty, which contains the file self-documenting code for makesdx.sty.

2 Installing Makesymbolindex^{1}

Edit the Makefile to set the location of Perl, the executable installation directory, the man page directory, the location of the L^{A}TEX documentation, and the location of the L^{A}TEX style file. Then type make to set up the scripts and the man pages. make install will install the scripts, and make man will install the man pages.

If you do not have sed you will have to edit the files by hand. See

00install.txt.

3 Using Makesymbolindex

It is fairly straightforward to use Makesymbolindex if you follow the instructions. If you have used Makeindex, you will observe some parallels.

1This set up procedure has been performed with SunOS 5.4 and is not guaranteed to work on any other operating system.

3.1 The File Processed by Makesymbolindex

Makesymbolindex will read a file whose lines are of the form

\symbolindex{sort-string}{symbol}{description}{page}{page-format}

Here sort-string is a string which is used to sort the entries, symbol is the TEX form of the symbol, description is the symbol’s description, page is the page where the symbol appeared, and page-format is a formatting command for the page number (e.g., \textbf or \textit). The page entry may be left blank as may the page formatting string.

Makesymbolindex expects files to have the suffix .sdx. So to run Makesymbolindex type

    makesymbolindex filename[.sdx]

This will produce a file filename.los. If no filename is given to Makesymbolindex as an argument, then the file is read from standard input and piped to standard output.

3.2 The L^{A}TEX “Front End” to Makesymbolindex

Most often you will use a L^{A}TEX file to produce the file to be processed by Makesymbolindex. To enable your L^{A}TEX file to produce a list of symbols, make the following additions to your file.

1. Load the makesdx package with the \usepackage command. This package has the following options:

colon place a colon before the symbol description

nocolon don’t place a colon before the symbol description

The colon mentioned will appear below when we give a sample symbol list.

2. In the document preamble (i.e., between the \documentclass command

     and the \begin{document} command), add the line \makesymbolindex.

This will enable the user commands.

3. Where you want the list of symbols to appear in the document add the

     line \listofsymbols.

To make the list of symbols first L^{A}TEX the document. This will produce a file filename.sdx which has the format indicated above. Now run Makesymbolindex on this file to produce filename.los. When you L^{A}TEX the file the next time, this file will be read in and a list of symbols will be created.

I guess you need to know how to get L^{A}TEX to write the file filename.sdx. This is done by using the \sindex command. The syntax for this command is:

\sindex*[page-format]{sort-string}{symbol}{description}.

Here page-format, sort-string, symbol, and description have the same function as described above. The * is optional as is the page-format argument (making four possible permutations of the command). If the * version is used, no page number will be given to the symbol when the list is created (this is useful for things which fall into the category of “notation”). If you use the * version, using the optional page-format argument has no effect (thus reducing to three the permutations of \sindex). A warning will be printed to the log file, filename.slg, if you use the same (according to the sorting routine; see the Usage Notes below) string for two different entries.

An example is illustrative. The following sequence of commands:

\sindex{x,y}{$(x,y)$}{a coordinate pair}
\sindex*{beta}{$\beta$}{the Greek letter following $\alpha$}
\sindex{alpha}{$\alpha$}{the first letter in Greek alphabet}
\sindex{zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz}%
{$zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz$}%
{a stupid symbol with a description long enough to make its
own box to run over the next line.}

will produce a list of symbols looking like α : the first letter in Greek alphabet, 2 β : the Greek letter following α (x, y) : a coordinate pair, 2

zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz : a stupid symbol with a description long enough to make

its own box to run over the next line.

Note the ordering according to sort-string. Also note the difference between \sindex and \sindex*. If you don’t like the colons before the description, load the package makesdx with the option nocolon.

3.3 How Makesymbolindex Handles Symbols With More Than One Page Reference

You can use \sindex more than once for the same symbol. The result will be a list of page numbers for the symbol rather than just one. The program detects your desire to have a multiple page reference by looking for symbols in the filename.sdx file which have identical sort-string and symbol specifications. If there is any difference in either of these, Makesymbolindex won’t recognise them as the same (and you wouldn’t want it to, I think). If it turns out that two calls to \sindex produce an symbol list item with the same page, only one will be printed. Thus the same page number won’t appear more than once for the same symbol. The exception to this is if the page-format specifications differ. In this case the unique page formats will all be displayed, regardless of whether or not they occur on the same numerical page. However, a warning will be printed in filename.slg in this case. For this reason, you should pay attention to the screen diagnostics produced by Makesymbolindex. They might display something relevant.

If the same symbol (i.e., one that has the same sort-string and symbol) is indexed on three or more consecutive pages without page formatting, then the pages are written as, for example 12–23.

In all cases the first description of a symbol indexed multiple times will be the active one. All the others will be ignored.

4 Usage Notes

The following points are worth noting:

1. Makesymbolindex has command line options:

-h gives a header at the top of the symbol list which looks something like

Symbol Description and page(s) when applicable

-i does case insensitive sorting (thus the default is case sensitive sorting)

-p gives a clear page after the end of the symbol list

2. If the document class you are using defines the \chapter command (as does, for example, book), then when you type \listofsymbols a new chapter will be started with title specified by \listsymbolname. The idea is that this will then work just like listoffigures and \listoftables. If \chapter is not supported, then the list of symbols is just placed where you type \listofsymbols with no hoopla (this is just like \tableofcontents, for example).

3. The command \listofsymbols accepts an optional argument contained in square brackets ([…]) in the usual L^{A}TEX manner. The contents of this optional argument will be printed immediately before the list of symbols.

4. The width of the box containing the symbol is given by the dimension \symbolwidth. The default is 0.25\columnwidth. If the symbol is wider than this, the description will start on a new line. See the example above.

5. It would be wise to run Makesymbolindex after you get the crossreferencing straight with L^{A}TEX. If you do not do this, there is a possibility that there will be an incorrect page number in your symbol list.

6. The symbols are fed to the \item command like you were using the L^{A}TEX description environment. Therefore you should exercise the same care with the arguments. See the L^{A}TEX manual for reference.

Please send any comments and errors to: andrew@mast.queensu.ca.