Directory macros/latex209/contrib/genindex

If you examine the code in latex.tex (LATEX VERSION 2.09 <25 March 1992>)
that defines the index- and glossary-making macros, you will see that
\makeindex and \makeglossary are nearly identical, and that the definitions
of \index and \glossary are nearly identical, "mutatis mutandis".
That is, the index-making macros write an .idx file, and the
glossary-making macros write a .glo file, but they do it in almost
exactly the same way.  Reading the comments in the file leads one
to believe that the \index feature was defined earlier, and the \glossary
feature was added later as an adaptation of \index.

I recently needed to create a third kind of file that I wanted to
be handled similarly to the .idx and .glo files, so I abstracted
the definitions of the index and glossary macros into a separate
style file.  Since I think of these as "generalized" index macros,
I call it "genindex.sty".  I'm rather surprised that this wasn't
done at the time the \glossary feature was added, since it seems like
a natural extension.  It takes fewer lines of code to define a
generalized structure and invoke it twice than it does to give
separate definitions of \index and \glossary!

As indicated in the comments in genindex.sty, the index and glossary
macros of latex.tex could be specified as follows:

	   \newindex{index}{\@indexfile}{idx}{\indexentry}
	   \newindex{glossary}{\@glossaryfile}{glo}{\glossaryentry}

Actually, there is one discrepancy: the definition of \glossary
in latex.tex does not include the definition of \protect, which
means that a \glossary entry in a moving argument (such as a footnote)
can get you into trouble.  Again, examining the comments in latex.tex
suggests that \index was defined first, then \glossary was cloned from
\index, and at a later date the \protect definition was added to \index
as a bug fix but the fixer did not make the corresponding change
to \glossary.  In any case, all index-like structures defined by \newindex
define \protect the way the standard \index macro does, so they are safe
to use wherever \index may be used.

(Incidentally, the eight # marks in a row in the body of \newindex are
a record for me.  \newindex defines macros like \makeindex, which
define macros like \index, which define the macro \protect.
This is the deepest nesting of macros defining macros I've ever
had occasion to use.)

The particular application that moved me to do this was the ability to
make memos to myself in the source files for a book.  I'm working with
a co-author, and we both want to be able to place little notes in
the source that will remind us of issues to consider as we develop the
book, but we don't want theses notes to be visible in the typeset pages.
We used to use comments, but it's easy to overlook comments in the source
files.  We each are especially prone to overlook the other's comments
since we don't know where to expect them.  By using the \memo macro we
get all the memos written to a separate file, with each memo keyed to
the page to which it applies.  We can run the book and then read the .mem
file to see the reminders we've made.  Note that unlike the .idx and .glo
files, the .mem file is not processed by makeindex or other utility and
read back into LaTeX (although I've considered making a *separate* driver
file that would read another document's .mem file and make a nice list
of the memos).  With the generalized index macros above it is easy to
define the \memo macro:

=============================================================================

Note that I go ahead and execute \makememo within memo.sty, since I
always want the \memo command to be active.  Now I can place \memo{ENTRY}
in the source and have \memoentry{ENTRY}{PAGENUM} in the .mem file with
no effect on the typeset pages.  (Well, no more effect than \index
would have.)

I offer this in hopes it will be useful to others.
Comments and suggestions for improvement are welcome.

By the way, if the \index and \glossary functions are to retain
anything like their present form in the new, improved LaTeX descendants
that are going to appear Real Soon Now, then I strongly suggest that
this generalized approach be used.  I think the fact that the original
\index functionality has been adapted twice (\glossary and \memo)
is evidence that a generalized capability would be useful.
I'm sure that other LaTeX users will think (or have already thought) of
additional uses for this idea.

--Cameron Smith
  cameron@symcom.math.uiuc.edu

P.S. Archivists, please feel free to put the above in an archive in
	whatever form you deem suitable.