summaryrefslogtreecommitdiff
path: root/macros/latex209/contrib/genindex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex209/contrib/genindex
Initial commit
Diffstat (limited to 'macros/latex209/contrib/genindex')
-rw-r--r--macros/latex209/contrib/genindex/genindex.sty45
-rw-r--r--macros/latex209/contrib/genindex/memo.sty3
-rw-r--r--macros/latex209/contrib/genindex/readme87
3 files changed, 135 insertions, 0 deletions
diff --git a/macros/latex209/contrib/genindex/genindex.sty b/macros/latex209/contrib/genindex/genindex.sty
new file mode 100644
index 0000000000..ed43f831fe
--- /dev/null
+++ b/macros/latex209/contrib/genindex/genindex.sty
@@ -0,0 +1,45 @@
+% GENINDEX.STY -- version 1.0 -- 5 August 1993 -- Cameron Smith
+
+% \newindex{NAME}{\FILEIDENTIFIER}{EXTENSION}{\CONSTRUCTOR}
+% defines two macros, \makeNAME and \NAME. If \makeNAME is
+% executed in the preamble of a document, executing \NAME{ENTRY} writes
+% the line \CONSTRUCTOR{ENTRY}{PAGENUM} to the file \jobname.EXTENSION,
+% where PAGENUM is the number of the page on which the \NAME command was
+% given. If \makeNAME is not executed, then calls to \NAME are no-ops.
+% \FILEIDENTIFIER is a control sequence used internally to
+% identify the output channel allocated to the file.
+
+% \FILEIDENTIFIER and \CONSTRUCTOR should be control sequences;
+% NAME and EXTENSION should not. EXTENSION should not include a period.
+
+% Example: \newindex{index}{\@indexfile}{idx}{\indexentry}
+% defines the macros \makeindex and \index. If \makeindex is
+% executed in the preamble of a document, then \index{ENTRY} causes
+% the line \indexentry{ENTRY}{PAGENUM} to be written to the file
+% \jobname.idx, which is identified internally as channel \@indexfile.
+% If \makeindex is not executed, \index{ENTRY} is a no-op.
+
+% The effect of \newindex{glossary}{\@glossaryfile}{glo}{\glossaryentry}
+% is similar.
+
+\def\newindex#1#2#3#4{%
+ \@namedef{make#1}{%
+ \if@filesw
+ \newwrite#2%
+ \immediate\openout#2=\jobname.#3
+ \@namedef{#1}{\@bsphack\begingroup
+ \def\protect########1{\string########1\space}\@sanitize
+ \@@wrindex#2#4}%
+ \typeout{Writing #1 file \jobname.#3 }%
+ \fi
+ }%
+ \@namedef{#1}{\@bsphack\begingroup \@sanitize\@index}%
+}
+
+\def\@@wrindex#1#2#3{\let\thepage\relax
+ \edef\@tempa{\write#1{\string#2{#3}{\thepage}}}%
+ \expandafter\endgroup\@tempa
+ \if@nobreak\ifvmode\nobreak\fi\fi\@esphack
+}
+
+\def\@index#1{\endgroup\@esphack}
diff --git a/macros/latex209/contrib/genindex/memo.sty b/macros/latex209/contrib/genindex/memo.sty
new file mode 100644
index 0000000000..ae14daa53f
--- /dev/null
+++ b/macros/latex209/contrib/genindex/memo.sty
@@ -0,0 +1,3 @@
+\@input{genindex.sty}
+\newindex{memo}{\@memofile}{mem}{\memoentry}
+\makememo
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.
+
+