% \iffalse meta-comment
%
% Copyright (C) 2008 by Kevin W. Hamlen
% -------------------------------------
%
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either
% version 1.3a of this license or (at your option) any later
% version. The latest version of this license is in:
%
%    http://www.latex-project.org/lppl.txt
%
% and version 1.3a or later is part of all distributions of
% LaTeX version 2004/10/01 or later.
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{symlist.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{symlist}
%<*package>
  [2008/03/11 v1.1 Symbol List package]
%</package>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{hyperref}
\usepackage{symlist}
{\makeatletter\catcode`/=0 \catcode`\\=11
  /gdef/DescMacro#1{%
    /@ifundefined{pdfbookmark}{}{/pdfbookmark[2]{\\#1}{macdef-#1}}%
    /expandafter/DescribeMacro/expandafter{/csname #1/endcsname}%
    /@ifundefined{hyperdef}{}{/hyperdef{macro}{#1}{}/kern0pt}%
  }
}
\newcommand\eat[1]{}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{symlist.dtx}
\end{document}
%</driver>
% \fi
%
% \CheckSum{161}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
% \changes{v1.0}{2006/08/14}{Initial version}
% \changes{v1.1}{2008/03/11}{Fix for no hyperref package}
%
% \GetFileInfo{symlist.sty}
%
% \DoNotIndex{\advance,\csname,\else,\endcsname,\fi,\global}
%
%
% \title{The \textsf{symlist} package\thanks{This document corresponds to
%    \textsf{symlist}~\fileversion, dated~\filedate.}}
% \author{Kevin W. Hamlen}
%
% \maketitle
%
% \begin{abstract}
% The |symlist| package allows easy creation of a list of symbols in a manner
% similar to \LaTeX's built-in support for lists of figures and tables.
% Like those other lists, the generated list of symbols is sorted in the
% order that the symbols are introduced in the document text.
% \end{abstract}
%
% \section{Introduction}
% Large mathematical texts, such as dissertations, often introduce a copious
% body of symbols and notation.
% Readers of such texts will benefit from a list of symbols that includes a
% brief description of each symbol and the page number where each symbol is
% first used or defined.
% Since symbols usually have no particularly natural ordering, the list of
% symbols is best sorted by order of introduction, so that the reader can
% narrow the search for a definition by searching backward from any given
% usage.
%
% This package allows \LaTeX\ authors to create a list of symbols for their
% documents using a fairly intuitive interface.
% When a symbol is first used, instead of just writing the \meta{symbol}
% directly,
% the author writes |\newsym{|\meta{desc}|}{|\meta{symbol}|}|, where
% \meta{desc} is a short textual description of the symbol's meaning.
% The list of all introduced symbols, their descriptions, and their page
% numbers is generated using the |\listofsymbols| macro.
%
% \section{Usage}
%
% Each \LaTeX\ document that uses the |symlist| package should include a
% line like the following in its preamble:
%
% \medskip
% {\narrower |\usepackage{symlist}| }
% \medskip
%
% \noindent
% There are currently no supported options for the package.
%
% \DescMacro{newsym}
% To introduce a new symbol to the list of symbols, use the |\newsym| macro
% with syntax
%
% \medskip
% {\narrower |\newsym{|\meta{description}|}{|\meta{symbol}|}|}
% \medskip
%
% \noindent
% This inserts \meta{symbol} into your list of symbols with the description
% \meta{description}, along with inserting \meta{symbol} into the text where
% the |\newsym| macro appears.
% You can use |\newsym| in equations or regular text;
% \meta{description} will always be processed in horizontal text mode, but
% the \meta{symbol} part will be processed in whatever mode is active when
% the |\newsym| macro appears.
%
% For example, suppose you want to include the
% $\newsym{addition}{+}$ symbol in your list of
% symbols with the description ``addition'', and the first place the $+$
% symbol appears in the document is a display equation like:
%
% \medskip
% {\narrower |\[ 7 + 3 + 12 = 22 \]|}
% \medskip
%
% \noindent
% In that case, you should replace the line above with:
%
% \medskip
% {\narrower |\[ 7 \newsym{addition}{+} 3 + 12 = 22 \]|}
% \medskip
%
% \noindent
% This only needs to be done for the first use of $+$ (or whichever instance
% you want to be referenced by the symbol list).
%
% In some cases you might want to put a different symbol in the
% symbol list than the one that appears in the text.
% For this, you can use the optional syntax:
%
% \medskip
% {\narrower |\newsym[|\meta{listed symbol}|]{|\meta{description}|}{|\meta{symbol}|}|}
% \medskip
%
% \noindent
% For example, you might write the following in a paragraph:
%
% \medskip
% {\narrower |denoted by \newsym[$*$]{finite repetition}{Kleene star}.|}
% \medskip
%
% \noindent
% to associate the symbol $\newsym{finite repetition}{*}$
% with the text ``Kleene star''.
% Since the \meta{listed symbol} is processed by default in whichever mode
% is active when the |\newsym| macro appears,
% in this case it needs to be surrounded by math-begin/end tokens (|$|)\eat$
% in order to force it to be displayed in math mode in the index.
%
% \DescMacro{listofsymbols}
% \DescMacro{listsymbolname}
% The |\listofsymbols| macro generates the list of symbols, their
% descriptions, and the page numbers where the instance defined with
% |\newsym| appears.
% The list is formatted with the title defined by
% |\listsymbolname| or ``\listsymbolname'' by default.
% An example list of symbols is shown below.
%
% \listofsymbols
%
% \StopEventually{\PrintIndex}
%
% \newpage
%
% \section{Implementation}
%
% The following provides the verbatim implementation of the |symlist|
% \LaTeX\ package, along with some brief commentary on how it works.
% In general, macro names that contain a |@| symbol are not intended
% to be directly accessible by the outside world; they are
% for purely internal use.
% All other macros are intended to be used or redefined by document
% authors.
% To find the implementation of any particular macro, the index at the
% end of this document should prove helpful.
%
% \medskip
%
% The first line of the |symlist| package ``processes'' any options that
% were specified in the |\usepackage| line.
% (Since there are no options presently supported, it yields
% an error if any were specified.)
%    \begin{macrocode}
\ProcessOptions\relax
%    \end{macrocode}
%
% \begin{macro}{\LOS@symline}
% Format a line of the list of symbols.
%    \begin{macrocode}
\newcommand\LOS@symline[4]{%
  \ifx\hyper@anchor\@undefined%
    \contentsline{symbol}{\numberline{#2}{#3}}{#4}\relax%
  \else%
    \contentsline{symbol}{\numberline{#2}{#3}}{#4}{symbol.#1}%
  \fi%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\listsymbolname}
% Define the title for the list of symbols (can be redefined by
% document authors).
%    \begin{macrocode}
\newcommand\listsymbolname{List of Symbols}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\LOS@cnt}
% Define a counter to assign a unique integer to each |\newsym| instance.
%    \begin{macrocode}
\newcount\LOS@cnt
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\LOS@wd}
% Define a dimen register to keep track of the largest width symbol
% introduced so far.
%    \begin{macrocode}
\newdimen\LOS@wd
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\LOS@ext}
% Define the file extension for the symbol list auxiliary file.
%    \begin{macrocode}
\newcommand\LOS@ext{los}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\LOS@init}
% Initialize the list of symbols by setting the widths of the columns.
%    \begin{macrocode}
\newcommand\LOS@init[1]{%
  \long\gdef\l@symbol{\@dottedtocline{1}{1.5em}{#1}}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\newsym}
% \begin{macro}{\LOS@newsym}
% \begin{macro}{\LOS@@newsym}
% Introduce a new symbol.
% The first step is to update the |\LOS@cnt| and |\LOS@wd| registers.
% Next, we define a new macro named |\LOS@sym@n|, where |n|
% is a unique roman numeral.
% When executed, this macro will write a new entry to the |.los| auxiliary
% file to produce a line in the symbol list the next time the document is
% compiled.
% However, we can't execute this macro right away because the box we're
% currently building might not make it into the final document here or at
% all.
% For example, material in floats is often processed multiple times as
% \LaTeX\ tries to find a suitable place for it.
% So instead, we embed a call to the new macro in a non-immediate |\write|
% to the |.aux| auxiliary file.
% If this |\newsym| instance actually makes it into the final document, then
% the macro will be written to the |.aux| file, and will then be executed at
% the end of the current round of processing.
%    \begin{macrocode}
\newcommand\newsym{\@ifnextchar[\LOS@@newsym\LOS@newsym}
\newcommand\LOS@newsym[2]{\LOS@@newsym[#2]{#1}{#2}}
\newcommand\LOS@@newsym{}
\def\LOS@@newsym[#1]#2#3{%
  \global\advance\LOS@cnt\@ne%
  \ifmmode%
    \settowidth\dimen@{$#1$\kern1em}%
    \expandafter\gdef%
      \csname LOS@sym@\romannumeral\LOS@cnt\endcsname##1##2{%
      \@writefile\LOS@ext{\LOS@symline{##1}{$#1$}{#2}{##2}}}%
  \else%
    \settowidth\dimen@{#1\kern1em}%
    \expandafter\gdef%
      \csname LOS@sym@\romannumeral\LOS@cnt\endcsname##1##2{%
      \@writefile\LOS@ext{\LOS@symline{##1}{#1}{#2}{##2}}}%
  \fi%
  \ifdim\dimen@>\LOS@wd\global\LOS@wd\dimen@\fi%
  \if@filesw%
    \write\expandafter\@auxout\expandafter{%
      \expandafter\noexpand\expandafter\LOS@sym\expandafter{%
      \romannumeral\LOS@cnt}{\thepage}}%
  \fi%
  \@ifundefined{hyperdef}{}%
    {\hyperdef{symbol}{\romannumeral\LOS@cnt}}%
  {#3}%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\LOS@sym}
% The |.aux| file is processed twice during a typical
% \LaTeX\ session---once at the beginning of the document body and once at
% the end.
% Since our |\LOS@sym@n| macros (described above) are defined within the
% document body, we only want the material inserted into the |.aux| file
% to evaluate during the second of these two rounds.
% Thus, we define |\LOS@sym| to be empty at first and then expanded to
% |\LOS@sym@n| after the document body begins.
%    \begin{macrocode}
\newcommand\LOS@sym[2]{}
\AtBeginDocument{%
  \gdef\LOS@sym#1{\csname LOS@sym@#1\endcsname{#1}}%
  \if@filesw%
    \@temptokena{\expandafter\@writefile\expandafter\LOS@ext%
      \expandafter{\expandafter\LOS@init\expandafter{\the\LOS@wd}}}%
    \immediate\write\@auxout{\the\@temptokena}%
  \fi%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\listofsymbols}
% Produce the list of symbols.
%    \begin{macrocode}
\ifx\chapter\undefined
  \newcommand\listofsymbols{%
    \section*{\listsymbolname}%
    \@mkboth{\MakeUppercase\listsymbolname}%
            {\MakeUppercase\listsymbolname}%
    \addvspace{10\p@}%
    \@starttoc\LOS@ext%
  }
\else
  \newcommand\listofsymbols{%
    \if@twocolumn\@restonecoltrue\onecolumn\else\@restonecolfalse\fi%
    \chapter*{\listsymbolname}%
    \@mkboth{\MakeUppercase\listsymbolname}%
            {\MakeUppercase\listsymbolname}%
    \addvspace{10\p@}%
    \@starttoc\LOS@ext%
    \if@restonecol\twocolumn\fi%
  }
\fi
%    \end{macrocode}
% \end{macro}
%
% \Finale
\endinput