doc 4

git-svn-id: svn://tug.org/texlive/trunk@80 c570f23f-e606-0410-a88d-b1316a301751

13 files changed, 553 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/index/README b/Master/texmf-dist/doc/latex/index/README
new file mode 100644
index 00000000000..d43617b5f55
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/index/README
@@ -0,0 +1,14 @@
+HOW TO INSTALL THIS FILE:
+
+Run tex on index.ins to unpack the files index.sty and sample.tex.
+Then install index.sty wherever style files belong on your system and
+read the comments at the beginning of sample.tex to see how to run the
+test.  Finally, format the documentation by executing the following
+three commands:
+
+   latex index.dtx
+   makeindex -s gind.ist index
+   latex index.dtx
+
+David M. Jones
+dmjones@theory.lcs.mit.edu
diff --git a/Master/texmf-dist/doc/latex/index/TODO b/Master/texmf-dist/doc/latex/index/TODO
new file mode 100644
index 00000000000..1ac41a2e07f
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/index/TODO
@@ -0,0 +1,107 @@
+Last updated: September 29, 1995
+
+Possible things to do:
+
+1) Allow two different 'indexes' to write to a single file, so we can
+do things like mix entries using different counters, a la doc.sty, and
+add in any other features from doc.sty that seem useful.
+
+2) integrate the scheme descripted in autind.sty into the package.
+
+3) merge bibref files into index.dtx and properly document it
+
+
+a) Implement the scheme mentioned at the end of section 3 of the
+documentation to remove the limit on the number of indexes possible in
+a single document.
+
+b) Add an enhancement to draft mode that allows the words and phrases
+that are being indexed to be typeset in color or greyscale in the main
+text (for copy-editing purposes only).  Since currently the actual
+pieces of text that are typeset are not included in the markup, this
+will require a major overhaul of the semantics of the \index command.
+So, I'm thinking of having a package option that does something like
+this:
+
+First, the \newindex command would be changed to the following:
+
+    \newindex[counter]\CS{TITLE}
+
+where \CS is the command used to put entries into the index titled
+'TITLE', whose entries are labeled with the value of 'counter'.  E.g.,
+after
+
+    \newindex\aindex{Name Index}
+
+\aindex would put entries into the author index, much as would be done
+with '\index[aut]' in the current scheme.  This frees up the optional
+argument to be used for something else.  (Note that '\index' would
+remain undefined by default, and so would have to be defined with
+\newindex, just as a 'default' index has to be declared currently.)
+
+Note that the user no longer has to supply an explicit extension for
+the raw and processed files (i.e., the '.idx' and '.ind' files).
+Instead, each index will be be assigned an integer, and the associated
+output and input files will have extensions of the form '.oHH' and
+'.iHH', where HH is the hexadecimal representation of the index's
+number.  This will allow up to 256 indexes without violating the
+length 3 limit on extensions.  (As a special case, the first index
+declared could use '.idx' and '.ind' instead of '.o00' and '.i00'.)
+
+[Maybe better would be something 'indNNN.idx' and 'indNNN.ind', which
+would make makeindex marginally happier, but would prohibit keeping
+multiple documents using this feature in the same directory.  Or maybe
+'XXXXXXHH.idx' and 'XXXXXXHH.ind', where 'XXXXXX' is the first 6
+characters of \jobname (for a suitable definition of 'first 6
+characters').  Alternatively, prepend the number on to the front
+(HHfilename.ind), and let the operating system worry about what
+happens to long file names.]
+
+\printindex would be redefined to take one of the \CS's defined above
+as its (mandatory) argument.
+
+Then the syntax of the \index-like commands would be changed to the
+following:
+
+    \index{foo}           : typesets "foo" in the text and puts it in
+                            the index
+
+    \index[bar]{foo}      : typesets "foo" in the text and puts
+                            "bar@foo" in the index.  Useful for things
+                            like \index[alpha]{$\alpha$}.  I believe
+                            this case is common enough to warrant a
+                            shortcut.
+
+    \index*{foo}          : Can't think of anything useful for this to
+                            do, but see next:
+
+    \index*[bar]{foo}     : typesets "foo" in the text and puts "bar"
+                            in the index.
+
+A note about these last two forms: At first blush, it might seem
+reasonable to have \index*{foo} put 'foo' in the index and typeset
+nothing, thus allowing allow arbitrary text to be put into the index.
+However, not only would it then be unclear what \index*[bar]{foo}
+should do, but there would be no way of putting arbitrary text in the
+index while simultaneously associating it with some specific text in
+the document (consider, for example, \index*[animal!cat]{cat} or
+\index*[cat|see{goddess}]{cat}).  So, the proposed syntax seems
+better, although it still leaves \index*{foo} without any obvious
+function.
+
+Note that in all of this, the short forms ^ and _ have disappeared
+entirely.  C'est la vie.
+
+In this scheme, \disableindex\foo would make \foo an \index-like
+command that would gobble up it's arguments -- \disableindex\foo used
+instead of \newindex\foo{TITLE}, or is it possible to disable an
+\index command that's already been declared with \newindex?  Latter is
+obviously more desirable.
+
+c) Implement some sort of scheme for per-chapter indices.
+
+d) Have index.sty add sufficient information to the .log file that a
+simple script can parse it and automatically run makeindex the proper
+number of times with the proper arguments.
+
+e) Write such a script.
diff --git a/Master/texmf-dist/doc/latex/index/agsmtst.adx b/Master/texmf-dist/doc/latex/index/agsmtst.adx
new file mode 100644
index 00000000000..2d3bdbdff0a
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/index/agsmtst.adx
@@ -0,0 +1,27 @@
+\indexentry {Cantone D@Cantone, D.|hyperpage}{1}
+\indexentry {Cutello V@Cutello, V.|hyperpage}{1}
+\indexentry {Policrito A@Policrito, A.|hyperpage}{1}
+\indexentry {Adamowicz Zofia@Adamowicz, Zofia|hyperpage}{1}
+\indexentry {Adleman Leonard@Adleman, Leonard|hyperpage}{1}
+\indexentry {Manders Kenneth@Manders, Kenneth|hyperpage}{1}
+\indexentry {Calude Cristian@Calude, Cristian|hyperpage}{1}
+\indexentry {Paun Gheorghe@P{\u {a}}un, Gheorghe|hyperpage}{1}
+\indexentry {Baker A@Baker, A.|hyperpage}{1}
+\indexentry {Adamowicz Zofia@Adamowicz, Zofia|hyperpage}{2}
+\indexentry {Adleman Leonard@Adleman, Leonard|hyperpage}{2}
+\indexentry {Manders Kenneth@Manders, Kenneth|hyperpage}{2}
+\indexentry {Allouche Jean Paul@Allouche, Jean-Paul|hyperpage}{2}
+\indexentry {Shallit Jeffrey@Shallit, Jeffrey|hyperpage}{2}
+\indexentry {Azra Jean Pierre@Azra, {Jean-Pierre}|hyperpage}{2}
+\indexentry {Baker A@Baker, A.|hyperpage}{2}
+\indexentry {Barton D@Barton, D.|hyperpage}{2}
+\indexentry {Fitch J P@Fitch, J.~P.|hyperpage}{2}
+\indexentry {Calude Cristian@Calude, Cristian|hyperpage}{2}
+\indexentry {Paun Gheorghe@P{\u {a}}un, Gheorghe|hyperpage}{2}
+\indexentry {Cantone D@Cantone, D.|hyperpage}{2}
+\indexentry {Cutello V@Cutello, V.|hyperpage}{2}
+\indexentry {Policrito A@Policrito, A.|hyperpage}{2}
+\indexentry {von Braunmuhl Burchard@von Braunm{\"u}hl, Burchard|hyperpage}{2}
+\indexentry {Cook Stephen@Cook, Stephen|hyperpage}{2}
+\indexentry {Mehlhorn Kurt@Mehlhorn, Kurt|hyperpage}{2}
+\indexentry {Verbeek Rutger@Verbeek, Rutger|hyperpage}{2}
diff --git a/Master/texmf-dist/doc/latex/index/agsmtst.tex b/Master/texmf-dist/doc/latex/index/agsmtst.tex
new file mode 100644
index 00000000000..b30888df577
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/index/agsmtst.tex
@@ -0,0 +1,41 @@
+%%  For format this file, run the following commands:
+%%  
+%%  latex agsmtst.tex
+%%  bibtex agsmtst.tex
+%%  latex agsmtst.tex
+%%  latex agsmtst.tex
+%%  makeindex -o agsmtst.and agsmtst.adx
+%%  latex agsmtst.tex
+
+\documentstyle[index,autind,harvard]{article}
+
+\newindex{aut}{adx}{and}{Name Index}
+
+\begin{document}
+
+\adjustcitation\cite
+
+\adjustcitation{\citeasnoun}
+
+%{\tt\meaning\cite}
+
+%{\tt\meaning\citeasnoun}
+
+\nocite*
+
+\cite{CantoneCP90,Adamowicz92}
+
+\cite[page 21]{AdlemanMa76}
+
+\citeasnoun{CaludeP83}
+
+\citeasnoun[foo]{Baker68}
+
+\newpage
+
+\bibliographystyle{xagsm}
+\bibliography{test}
+
+\printindex[aut]
+
+\end{document}
diff --git a/Master/texmf-dist/doc/latex/index/autind.tex b/Master/texmf-dist/doc/latex/index/autind.tex
new file mode 100644
index 00000000000..0eac606f39e
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/index/autind.tex
@@ -0,0 +1,131 @@
+\documentclass{article}
+
+\newcommand*{\email}[1]{$\langle$\texttt{#1}$\rangle$}
+
+\newcommand{\BibTeX}{\textsc{Bib}\TeX}
+
+\begin{document}
+
+\title{Preliminary thoughts on automatic author indexing with \BibTeX\
+and \texttt{index.sty}}
+
+\author{David M. Jones}
+
+\date{September 28, 1995}
+
+\maketitle
+
+\begin{abstract}
+
+A method for automically indexing the names of authors in a
+bibliography is described.  The ideas presented here were developed in
+conjunction with Berwin A. Turlach \email{berwin@core.ucl.ac.be} in
+Spring 1994, but he has not seen the current writeup and is not
+responsible for its contents.
+
+\end{abstract}
+
+When producing a name index, one typically wants to include entries
+for all authors mentioned in the bibliography, as well entries for
+each point in the text where an item of the bibliography is cited.  It
+would obviously be useful if this stage of the index compilation could
+be automated.  This note sketches a procedure for doing this using
+\BibTeX\ and \texttt{index.sty}.  There are essentially two parts:
+modifying the BST file to produce appopriate indexing information in
+the BBL file, and modifying the \verb+\cite+ command to make use of
+this information.
+
+The BST file should produce something like
+\begin{verbatim}
+    \bibitem{Adamowicz92}
+    \authorindexentries{Adamowicz92}{\do{Adamowicz, Zofia}}
+    Zofia Adamowicz.
+\end{verbatim}
+
+Then \verb+\authorindexentries+ could both execute its argument to
+produce index entries for the bibliography and also store the index
+entries for later retrieval by the \verb+\cite+ command.  This
+requires two new functions and a slight modification of one old
+function (\verb+output.bibitem+):
+\begin{verbatim}
+    FUNCTION {format.name.index.entry}
+    {
+        "\do{"
+        s nameptr "{vv~}{ll}{, jj}{, ff}" format.name$
+        duplicate$ purify$ swap$ "@" swap$ * *
+        "}" * *
+    }
+
+    FUNCTION {format.author.index.entries}
+    {
+        author empty$
+            'skip$
+            { 
+                author 's :=
+                #1 'nameptr :=
+                s num.names$ 'numnames :=
+                "\authorindexentries{"
+                cite$ * 
+                "}{" *
+                numnames 'namesleft :=
+                { namesleft #0 > }
+                { format.name.index.entry *
+                    nameptr #1 + 'nameptr :=
+                    namesleft #1 - 'namesleft :=
+                }
+                while$
+                "}" * write$
+                newline$
+            }
+        if$
+    }
+
+    FUNCTION {output.bibitem}
+    { newline$
+      "\bibitem{" write$
+      cite$ write$
+      "}" write$
+      newline$
+      format.author.index.entries % modification
+      ""
+      before.all 'output.state :=
+    }
+\end{verbatim}
+These can be inserted into the bst file after the definition of
+\verb+format.names+.  (\verb+output.bibitem+ has to be moved from it's
+position earlier in the file.)
+
+A minimal definition of \verb+\authorindexentries+ can be found in the
+accompanying file \texttt{autind.sty}.
+
+The fun part is trying to modify the \verb+\cite+ command without
+assuming too much about how it is defined.  It would be nice if we
+could just type something like
+\begin{verbatim}
+    \adjustcitation\cite
+    \adjustcitation\citeasnoun
+\end{verbatim}
+and then have \verb+\cite+ and \verb+\citeasnoun+ automatically add
+the appropriate author index entries.  Assuming that the commands
+behave like the standard \LaTeX\ \verb+\cite+ command (i.e., they take
+one optional argument and one required argument, which is a list of
+citekeys), the \verb+\adjustcitation+ macro in \texttt{autind.sty} more
+or less does the job.
+
+The only other macro needed is \verb+\authorindex@cite+, which pulls
+in the author index entries from the appropriate
+\verb+\authorindexentries+ command.  This macro is also found in \texttt{autind.sty}.
+
+I've tried this approach on \texttt{plain.bst} and the standard
+\LaTeX\ \verb+\cite+ command and also on the \verb+\cite+ and
+\verb+\citeasnoun+ commands in \texttt{harvard.sty}, and it seems to
+work.  The accompanying files \texttt{plaintst.tex},
+\texttt{agsmtst.tex}, \texttt{test.bib}, \texttt{xplain.bst}, and
+\texttt{xagsm.bst} demonstrate the procedure.
+
+More testing is needed, but unless there's some major flaw that I'm
+overlooking, this should work with any citation commands that aren't
+too different from the standard \verb+\cite+ command and with any
+bibliography files that aren't too different from the standard styles.
+
+\end{document}
diff --git a/Master/texmf-dist/doc/latex/index/index.pdf b/Master/texmf-dist/doc/latex/index/index.pdf
new file mode 100644
index 00000000000..34c89278856
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/index/index.pdf
diff --git a/Master/texmf-dist/doc/latex/index/plaintst.adx b/Master/texmf-dist/doc/latex/index/plaintst.adx
new file mode 100644
index 00000000000..57d8a04dceb
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/index/plaintst.adx
@@ -0,0 +1,29 @@
+\indexentry {Cantone D@Cantone, D.}{1}
+\indexentry {Cutello V@Cutello, V.}{1}
+\indexentry {Policrito A@Policrito, A.}{1}
+\indexentry {Adamowicz Zofia@Adamowicz, Zofia}{1}
+\indexentry {Adleman Leonard@Adleman, Leonard}{1}
+\indexentry {Manders Kenneth@Manders, Kenneth}{1}
+\indexentry {Calude Cristian@Calude, Cristian}{1}
+\indexentry {Paun Gheorghe@P{\u {a}}un, Gheorghe}{1}
+\indexentry {Adamowicz Zofia@Adamowicz, Zofia}{2}
+\indexentry {Baker A@Baker, A.}{2}
+\indexentry {Adamowicz Zofia@Adamowicz, Zofia}{3}
+\indexentry {Adamowicz Zofia@Adamowicz, Zofia}{4}
+\indexentry {Adleman Leonard@Adleman, Leonard}{4}
+\indexentry {Manders Kenneth@Manders, Kenneth}{4}
+\indexentry {Allouche Jean Paul@Allouche, Jean-Paul}{4}
+\indexentry {Shallit Jeffrey@Shallit, Jeffrey}{4}
+\indexentry {Azra Jean Pierre@Azra, {Jean-Pierre}}{4}
+\indexentry {Baker A@Baker, A.}{4}
+\indexentry {Barton D@Barton, D.}{4}
+\indexentry {Fitch J P@Fitch, J.~P.}{4}
+\indexentry {Calude Cristian@Calude, Cristian}{4}
+\indexentry {Paun Gheorghe@P{\u {a}}un, Gheorghe}{4}
+\indexentry {Cantone D@Cantone, D.}{4}
+\indexentry {Cutello V@Cutello, V.}{4}
+\indexentry {Policrito A@Policrito, A.}{4}
+\indexentry {von Braunmuhl Burchard@von Braunm{\"u}hl, Burchard}{4}
+\indexentry {Cook Stephen@Cook, Stephen}{4}
+\indexentry {Mehlhorn Kurt@Mehlhorn, Kurt}{4}
+\indexentry {Verbeek Rutger@Verbeek, Rutger}{4}
diff --git a/Master/texmf-dist/doc/latex/index/plaintst.bdx b/Master/texmf-dist/doc/latex/index/plaintst.bdx
new file mode 100644
index 00000000000..49abcec304f
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/index/plaintst.bdx
@@ -0,0 +1,8 @@
+\indexentry {CantoneCP90}{1}
+\indexentry {Adamowicz92}{1}
+\indexentry {AdlemanMa76}{1}
+\indexentry {CaludeP83}{1}
+\indexentry {Adamowicz92}{2}
+\indexentry {Baker68}{2}
+\indexentry {Adamowicz92}{3}
+\indexentry {FOCS17}{4}
diff --git a/Master/texmf-dist/doc/latex/index/plaintst.tex b/Master/texmf-dist/doc/latex/index/plaintst.tex
new file mode 100644
index 00000000000..0dd9f6e56d4
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/index/plaintst.tex
@@ -0,0 +1,52 @@
+%%  For format this file, run the following commands:
+%%  
+%%  latex plaintst.tex
+%%  bibtex plaintst.tex
+%%  latex plaintst.tex
+%%  latex plaintst.tex
+%%  makeindex -o plaintst.and plaintst.adx
+%%  makeindex -s bibref.ist -o plaintst.bnd plaintst.bdx
+%%  latex plaintst.tex
+
+\documentclass{article}
+
+\errorcontextlines10
+
+\usepackage{bibref,autind}
+
+\newindex{aut}{adx}{and}{Name Index}
+
+\begin{document}
+
+\adjustcitation\cite
+
+\nocite*
+
+\cite{CantoneCP90,Adamowicz92}
+
+\cite[page 21]{AdlemanMa76}
+
+\cite{CaludeP83}
+
+\newpage
+
+Second page.
+
+\cite{Adamowicz92}
+
+\cite[foo]{Baker68}
+
+\newpage
+
+Third page.
+
+\cite{Adamowicz92}
+
+\newpage
+
+\bibliographystyle{xplain}
+\bibliography{test}
+
+\printindex[aut]
+
+\end{document}
diff --git a/Master/texmf-dist/doc/latex/index/sample.adx b/Master/texmf-dist/doc/latex/index/sample.adx
new file mode 100644
index 00000000000..ebd8f9f720d
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/index/sample.adx
@@ -0,0 +1,6 @@
+\indexentry {chapter}{3}
+\indexentry {section}{3}
+\indexentry {text}{4}
+\indexentry {section2}{4}
+\indexentry {index}{4}
+\indexentry {entry}{4}
diff --git a/Master/texmf-dist/doc/latex/index/sample.ldx b/Master/texmf-dist/doc/latex/index/sample.ldx
new file mode 100644
index 00000000000..ba90596980b
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/index/sample.ldx
@@ -0,0 +1,2 @@
+\indexentry {second item}{2}
+\indexentry {fifth item}{5}
diff --git a/Master/texmf-dist/doc/latex/index/sample.ndx b/Master/texmf-dist/doc/latex/index/sample.ndx
new file mode 100644
index 00000000000..6af68772ed2
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/index/sample.ndx
@@ -0,0 +1,4 @@
+\indexentry {notation}{3}
+\indexentry {sin@$\sin $}{3}
+\indexentry {notation}{4}
+\indexentry {min@$\min $}{4}
diff --git a/Master/texmf-dist/doc/latex/index/sample.tex b/Master/texmf-dist/doc/latex/index/sample.tex
new file mode 100644
index 00000000000..f468cd9acf8
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/index/sample.tex
@@ -0,0 +1,132 @@
+%%
+%% This is file `sample.tex',
+%% generated with the docstrip utility.
+%%
+%% The original source files were:
+%%
+%% index.dtx  (with options: `sample')
+%% 
+%% IMPORTANT NOTICE:
+%% 
+%% For the copyright see the source file.
+%% 
+%% Any modified versions of this file must be renamed
+%% with new filenames distinct from sample.tex.
+%% 
+%% For distribution of the original source see the terms
+%% for copying and modification in the file index.dtx.
+%% 
+%% This generated file may be distributed as long as the
+%% original source files, as listed above, are part of the
+%% same distribution. (The sources need not necessarily be
+%% in the same archive or directory.)
+%% \CheckSum{755}
+%% \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         \~}
+%% latex sample.tex
+%% makeindex sample
+%% makeindex -o sample.and sample.adx
+%% makeindex -o sample.nnd sample.ndx
+%% makeindex -o sample.lnd sample.ldx
+%% latex sample.tex
+
+\documentclass{book}
+\usepackage{index}
+
+\listfiles
+
+\makeindex
+\newindex{aut}{adx}{and}{Name Index}
+\newindex{not}{ndx}{nnd}{List of Notation}
+
+\newindex[theenumi]{list}{ldx}{lnd}{Items}
+
+\shortindexingon
+
+\proofmodetrue
+
+\def\aindex{\index*[aut]}
+
+\begin{document}
+
+\tableofcontents
+
+\newpage
+
+\chapter{Here is a ^[aut]{chapter} title}
+
+\section{Section header\index[aut]{section}}
+
+Here is some text.\index{subject}
+
+Here is \index[not]{notation}some more \index[not]{sin@$\sin$}
+text.
+
+\newpage
+
+Here is some ^{more} _[not]{notation} text.
+
+Here is yet more \aindex{text}.
+
+\section{Another Section header _[aut]{section2}}
+
+And here is some math: $x^1_b$.
+
+Here is an ^[aut]{index} entry \fbox{inside an
+\index[not]{min@$\min$}fbox}
+
+\fbox{Here is an ^[aut]{entry} in a box.}
+
+\section{An indexed list environment}
+
+\begin{enumerate}
+
+\item
+First item
+
+\item
+Second item\index[list]{second item}
+
+\item
+Third item
+
+\newpage
+
+\item
+Fourth item
+
+\item
+Fifth item\index[list]{fifth item}
+
+\item
+Sixth item
+
+\end{enumerate}
+
+\printindex[not]
+
+\printindex[aut][Here is a prologue for the author index.
+Note that it is set in a single column at the top of the
+first page of the index.]
+
+\printindex[list]
+
+\printindex
+
+\end{document}
+\endinput
+%%
+%% End of file `sample.tex'.