summaryrefslogtreecommitdiff
path: root/macros/latex209/contrib/genindex/readme
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex209/contrib/genindex/readme')
-rw-r--r--macros/latex209/contrib/genindex/readme87
1 files changed, 87 insertions, 0 deletions
diff --git a/macros/latex209/contrib/genindex/readme b/macros/latex209/contrib/genindex/readme
new file mode 100644
index 0000000000..4e40436195
--- /dev/null
+++ b/macros/latex209/contrib/genindex/readme
@@ -0,0 +1,87 @@
+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.
+
+