 The listofsymbols.sty package (v0.1)

Stefan Spreng

March 2003

Abstract

listofsymbols provides commands to (a) automatically create a list of symbols (also called notation or nomenclature) and (b) handle symbols logically, i.e. use a command that is expanded to the desired output rather than ‘hardcoding’ the output into the text.

This helps to ensure consistency throughout the text, especially if there is a chance that symbols will be changed at some stage.

This package is more or less a combination of what the packages nomencl.sty and formula.sty do. The concept of creating the list of symbols, though, is different from the way nomencl.sty does it.

Contents

1 User Interface 2

1.1 Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.2 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2 Examples 6

2.1 Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2.2 Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.3 Example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3 Contact 8

4 The Code 8

1 User Interface

1.1 Options

draft Default.

final Removes the macronames from the lists.

Final Similar to final. The difference is that the .sym and .sub files are not changed any more. Use this mode when your document is ready and you have sorted the .sym and .sub files manually.

nomencl Typesetting the list of symbols with the package nomencl (symbols and subscripts are in one list). With this option, the macros described in this documentation call the appropriate commands that nomencl.sty provides. See the documentation of nomencl.sty for details of the layout.

nopageno Default.

pageno Inserts the number of the page on which a symbol or subscript is defined.

usexspace Default. Uses the package xspace to insert an ‘intelligent’ space after the commands.

noxspace Do not load package xspace. In this case a command must by followed by a backslash and a space if you want a space in the output (This is the LaTeX standard).

You can use only one of the options draft, final, Final or nomencl and only one of the options nopageno or pageno.

1.2 Macros

\opensymdef All \newsym and \newsub commands must be between the commands

\closeymdef  \opensymdef and \closesymdef. A \listofsymbols or a \listofsubscripts

must be outside the region enclosed by these commands. Otherwise you will get errors. See section 2 for examples.

\newsym The macro \newsym assigns the desired output of a symbol or variable to a macro which can thereafter be used like any other macro. \newsym takes one optional argument and two mandatory arguments.

\newsym[ description ]{ macroname }{ output }

Figure 1: Example

\opensymdef
\newsym[Energy]{symE}{E}
\newsym[Mass]{symm}{m}
\newsym[Speed of light]{symc}{c}
\closesymdef
\[\symE=\symm \symc^2\]
where \symE is the energy \ldots

Output:

E = m c^{2}

where E is the energy …

The optional argument is the description that will appear in the list of symbols. The first mandatory argument is the name of the macro and the second mandatory argument is the desired output. Note that the definition of \newsym includes output in a \ensuremath{} command. If there is no description then the symbol is included in the list of symbols in draft mode, but not in final mode.

The description of a macro can be accessed with doc appended to the macroname. A string that can be used inside a tabular environment can be obtained by appending tabdoc to the command. If tabdoc is appended, then the macro expands to output & description

Example:

\newsym[Energy]{symE}{E}
The symbol \symE means \symEdoc
\begin{tabular}{ll}
Symbol&Description\\
\symEtabdoc\\
\end{tabular}

Figure 1 shows an example. You will probably notice that all the macros start with sym. That’s because I think that this makes it easier to distinguish between symbols and other macros you define in a document.

Personally, I use a y and an s as the first characters to indicate that a command is a symbol or a subscript, it’s shorter …

All this may appear a bit cumbersome at first glance. Why not just write \[E=m c^2\]? Well, suppose you are happily typing a document—say a theory of relativity or something—intending to state the formula as E = m a^{2}. Now somebody tells that the a in the formula looks really ugly and that you are going to have a hard time with the marketing if you don’t change the a to a c. So you decide to change your formula into E = m c^{2}. Imagine how much time you would spend checking all the a’s in your document and change them into c’s if they are symbols in a formula. And now comes the big surprise: With the listofsymbols package, you just change the output term in the \newsym command. Nice, isn’t it?

\newsub The macro \newsub creates a subscript much in the same way as \newsym creates a symbol. The syntax is

\newsub[ description ]{ subscriptname }{ output }

\subsep The macro \subsep separates two subscripts and thus avoids a LaTeX error. Its syntax is

     \subsep[ separator ]

By default, the separator is empty, i.e. the second subscript simply follows the first one.

If you want to use a subscript after a symbol that does not have a subscript yet, simply put if after the symbol, e.g. \symx\suby. If the symbol already has a subscript, you have to put a \subsep in front of the subscript. In regular text, you should enclose such a construct with $’s to avoid space between the symbol and the subscript.

Example:

\newsym{symx}{x}
\newsym{syma}{a_b}
\newsub{suby}{y}
\newsub{subz}{z}
Usage: $\symx\suby$
Or: $\symx\suby\subsep\subz$
Finally: $\symx\suby\subsep[,]\subz$
In an equation:
\[ \symx\suby = \syma\subsep[,]\suby \]

\listofsymbols The command \listofsymbols generates a list of the symbols, that were created with \newsym. The symbols are not sorted. You have to do that manually by sorting the lines in the .sym and .sub files, for example with an editor or a spreadsheet. Once you have sorted the symbols and do not want to have the files changed any more, use the Final mode. Before using the Final mode, you must compile the document at least once in final mode to get the proper .sym and .sub files.

A typical sequence would be

• Compile in draft mode (as often as you want)

• Compile in final mode (at least once)

• Sort and edit the .sym and .sub files

• Compile in Final mode (as often as you want). If you add new symbol or subscript definitions now, they will not appear in the list of symbols or subscripts. If you use draft or final mode now, the edited version of the .sym and .sub files will be overwritten.

Note that the command \listofsymbols must be outside the region that is enclosed by the \opensymdef and \closesymdef commands.

In draft mode, which is the default, the names of the macros are inlcuded in the lists. That makes it easier to keept track of the macro names and the corresponding output. Symbols that do not have a description are included in the list as well.

In final mode, the macro-names disappear and symbols without a description (or an empty description) are not included in the list.

The Final mode is similar to final. The difference is that the .sym and .sub files are not changed. Use this mode when your document is ready and you have sorted the .sym and .sub files manually. The first pair of braces after the \printsymline in a line of the .sym and .sub files is not used by listofsymbols. You can use it for example to help the sorting process.

Example: It is valid to change the line

\printsymline{\ell }{\ensuremath{\ell }}{\texttt{syml}}{Length}{1}

manually into

\printsymline{l}{\ensuremath{\ell }}{\texttt{syml}}{Length}{1}

In nomencl mode the glossary has to be generated manually, for example by entering

   makeindex filename.glo -s nomencl.ist -o filename.gls

at the command line. Read the documentation of the nomencl package for more information.

\symlength The length \symlength is the space reserved for the symbol on the left side of each line and is by default set to 2.5 cm. If you have long symbols you may have to change that, for example with

   \setlength{\symlength}{3cm}.

\listofsubscripts Similar to \listofsymbols, but for the subscripts obviously.

\listofboth Creates both a list of symbols and a list of subscripts with the heading ‘Notation’ above them.

\symheadingname The headings of the lists are stored in \symheadingname and \subheadingname
\subheadingname
\bothheadingname

and \bothheadingname. In order to change it you can use for example

   \renewcommand{\symheadingname}{ New Heading }

2 Examples

These examples are supposed to illustrate the implications of opensymdef

and closesymdef.

2.1 Example 1

Here, the definitions are in the preamble

\documentclass{article}
\usepackage{listofsymbols}
\opensymdef
   \newsym[Energy]{symE}{E}
   \newsym[Mass]{symm}{m}
   \newsym[Speed of light]{symc}{c}
\closesymdef
\begin{document}
  \[\symE=\symm \symc^2\]
  where \symE is the energy \ldots
  \listofsymbols
\end{document}

Output:

E = m c^{2}

where E is the energy …

List of Symbols (draft)

Symbol Description E \symE – Energy m \symm – Mass c \symc – Speed of light

2.2 Example 2

Here, the list of symbols is at the end of the document and the definitions are in the body.

\documentclass{article}
\usepackage{listofsymbols}
\begin{document}
  \opensymdef
     \newsym[Energy]{symE}{E}
     \newsym[Mass]{symm}{m}
     \newsym[Speed of light]{symc}{c}
  \[\symE=\symm \symc^2\]
  where \symE is the energy \ldots
  \closesymdef
  \listofsymbols
\end{document}

2.3 Example 3

Now, the list of symbols is before the definitions.

\documentclass{article}
\usepackage{listofsymbols}

\begin{document}
  \listofsymbols
  \opensymdef
     \newsym[Energy]{symE}{E}
     \newsym[Mass]{symm}{m}
     \newsym[Speed of light]{symc}{c}
  \[\symE=\symm \symc^2\]
  where \symE is the energy \ldots
  \closesymdef
\end{document}

3 Contact

If you have suggestions how this package can be improved, let me know:

e-mail: listofsymbols@gmx.de

4 The Code

 1 \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{listofsymbols}
 2 \RequirePackage{ifthen} \RequirePackage{calc} \newboolean{b@nomencl}
 3 \newboolean{b@final} \newboolean{b@Final} \newboolean{b@pageno}
 4 \newboolean{b@xspace}
 5 \DeclareOption{nomencl}{\setboolean{b@nomencl}{true}}
 6 \DeclareOption{draft}{\setboolean{b@nomencl}{false}
 7 \setboolean{b@final}{false}\setboolean{b@Final}{false}}
 8 \DeclareOption{final}{\setboolean{b@nomencl}{false}
 9 \setboolean{b@final}{true}\setboolean{b@Final}{false}}
10 \DeclareOption{Final}{\setboolean{b@nomencl}{false}
11 \setboolean{b@final}{true}\setboolean{b@Final}{true}}
12 \DeclareOption{pageno}{\setboolean{b@pageno}{true}}
13 \DeclareOption{nopageno}{\setboolean{b@pageno}{false}}
14 \DeclareOption{usexspace}{\setboolean{b@xspace}{true}}
15 \DeclareOption{noxspace}{\setboolean{b@xspace}{false}}

16

17 \ExecuteOptions{draft,nopageno,usexspace}
18 \ProcessOptions

19

20 \newlength{\symwidth}
21 \setlength{\symwidth}{2.5cm}
22 \newlength{\sympagenowidth}

23

24 \ifthenelse{\boolean{b@nomencl}}

25 {\RequirePackage{nomencl}}{}
26 \ifthenelse{\boolean{b@xspace}}
27 {\RequirePackage{xspace}
28 \newcommand{\spaceaftersym}{\xspace}}
29 {\newcommand{\spaceaftersym}{}}
30 \ifthenelse{\boolean{b@pageno}}
31 {\settowidth{\sympagenowidth}{9999}}
32 {\setlength{\sympagenowidth}{0cm}}

33

34 %#1: sortkey
35 %#2: symbol
36 %#3: macroname
37 %#4: description
38 %#5: page number
39 \newcommand{\printsymline}[5]
40 {\makebox[2.5cm][l]{#2}
41 \parbox[t]{\textwidth-\symwidth-\sympagenowidth}
42 {\begin{raggedright}\strut%
43 \ifthenelse{\boolean{b@final}}{#4}{$\backslash$#3 --- #4}%
44 \strut\end{raggedright}}%
45 \ifthenelse{\boolean{b@pageno}}{\hfill #5}{}%
46 \newline}

47

48 %#1: sortkey
49 %#2: symbol
50 %#3: macroname
51 %#4: description
52 %#5: filehandle
53 \ifthenelse{\boolean{b@Final}}
54 {\newcommand{\addsymline}[5]{}
55 \newcommand{\opensymdef}{}
56 \newcommand{\closesymdef}{}}
57 {\newcommand{\opensymdef}
58 {\newwrite\@sym \immediate\openout\@sym=\jobname.sym
59 \newwrite\@sub \immediate\openout\@sub=\jobname.sub}
60 \newcommand{\closesymdef}
61 {\immediate\closeout\@sym
62 \immediate\closeout\@sub}
63 \ifthenelse{\boolean{b@final}}
64 {\newcommand{\addsymline}[5]
65 {\ifthenelse{\equal{#4}{}}{}
66 {\immediate\write#5{\string\printsymline {#1}%
67 {\string\ensuremath{#2}}%
68 {\string\texttt{#3}}{#4}%
69 {\thepage}}}}}
70 {\newcommand{\addsymline}[5]
71 {\immediate\write#5{\string\printsymline {#1}%
72 {\string\ensuremath{#2}}%
73 {\string\texttt{#3}}{#4}%

74 {\thepage}}}}}

75

76 %#1: description
77 %#2: macroname
78 %#3: symbol
79 \newcommand{\@createsym}[3]
80 {\expandafter\newcommand\expandafter{\csname#2\endcsname}
81 {\relax\ensuremath{#3}\spaceaftersym} %similar to formula.sty
82 \expandafter\newcommand\expandafter{\csname#2doc\endcsname}{#1}
83 \expandafter\newcommand\expandafter{\csname#2tabdoc\endcsname}
84 {\ensuremath{#3} & #1}}

85

86 %#1: description
87 %#2: macroname
88 %#3: symbol
89 \ifthenelse{\boolean{b@nomencl}}
90 {\newcommand{\newsym}[3][]
91 {\@createsym{#1}{#2}{#3}
92 \ifthenelse{\equal{#1}{}}{}{\nomenclature{\ensuremath{#3}}{#1}}}}
93 {\newcommand{\newsym}[3][]
94 {\@createsym{#1}{#2}{#3}
95 \addsymline{#3}{#3}{#2}{#1}{\@sym}}}

96

97 %#1: description
98 %#2: macroname
99 %#3: symbol
100 \newcommand{\@createsub}[3]
101 {\expandafter\newcommand\expandafter{\csname#2\endcsname}
102 {\relax\ensuremath{_{#3}}\spaceaftersym}
103 \expandafter\newcommand\expandafter{\csname#2doc\endcsname}{#1}
104 \expandafter\newcommand\expandafter{\csname#2tabdoc\endcsname}
105 {\ensuremath{#3} & #1}}

106

107 %#1: description
108 %#2: macroname
109 %#3: symbol
110 \ifthenelse{\boolean{b@nomencl}}
111 {\newcommand{\newsub}[3][]
112 {\@createsub{#1}{#2}{#3}
113 \ifthenelse{\equal{#1}{}}{}{\nomenclature{\ensuremath{#3}}{#1}}}}
114 {\newcommand{\newsub}[3][]
115 {\@createsub{#1}{#2}{#3}
116 \addsymline{}{#3}{#2}{#1}{\@sub}}}

117

118 \newcommand{\subsep}[1][]{{}_{#1}{}}

119

120 \newcommand{\symheadingname}{List of Symbols}
121 \newcommand{\subheadingname}{List of Subscripts}
122 \newcommand{\bothheadingname}{Notation}

124 \ifthenelse{\boolean{b@final}}
125 {\newcommand{\symheading}
126 {\section*{\symheadingname}}
127 \newcommand{\subheading}
128 {\section*{\subheadingname}}}
129 {\newcommand{\symheading}
130 {\section*{\symheadingname\ (draft)}
131 \makebox[\symwidth][l]{\bf Symbol}{\bf Description}
132 \ifthenelse{\boolean{b@pageno}}{\hfill{\bf Defined on page}}{}}
133 \newcommand{\subheading}
134 {\section*{\subheadingname\ (draft)}
135 \makebox[\symwidth][l]{\bf Subscript}{\bf Description}
136 \ifthenelse{\boolean{b@pageno}}{\hfill{\bf Defined on page}}{}}}

137

138 \ifthenelse{\boolean{b@nomencl}}
139 {\makeglossary
140 \renewcommand{\nomname}{\symheadingname}
141 \setlength{\nomitemsep}{-1\parsep}
142 \newcommand{\listofsymbols}{\printglossary}
143 \newcommand{\listofsubscripts}{}}
144 {\newlength{\old@parskip}
145 \newlength{\old@parindent}
146 \newcommand{\listofsymbols}{
147 \setlength{\old@parskip}{\parskip}
148 \setlength{\parskip}{0pt}
149 \setlength{\old@parindent}{\parindent}
150 \setlength{\parindent}{0pt}
151 \symheading\par
152 \IfFileExists{\jobname.sym}{\@input@{\jobname.sym}}{}
153 \setlength{\parskip}{\old@parskip}
154 \setlength{\parindent}{\old@parindent}}
155 \newcommand{\listofsubscripts}{
156 \setlength{\old@parskip}{\parskip}
157 \setlength{\parskip}{0pt}
158 \setlength{\old@parindent}{\parindent}
159 \setlength{\parindent}{0pt}
160 \subheading\par
161 \IfFileExists{\jobname.sub}{\@input@{\jobname.sub}}{}
162 \setlength{\parskip}{\old@parskip}
163 \setlength{\parindent}{\old@parindent}}}

164

165 \ifthenelse{\boolean{b@nomencl}}
166 {\newcommand{\listofboth}{\listofsymbols}}
167 {\newcommand{\listofboth}
168 {\renewcommand{\symheading}{\subsection*{\symheadingname}}
169 \renewcommand{\subheading}{\subsection*{\subheadingname}}
170 \section*{\bothheadingname\ifthenelse{\boolean{b@final}}{}{ (draft)}}
171 \listofsymbols\listofsubscripts}}

173 \endinput