\def\BibTeX{{\rm B\kern-.05em{\sc i\kern-.025em b}\kern-.08em T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}} % \BibTeX command above has been stolen form \cite{Patashnik88a} \documentclass{article} \usepackage[T1]{fontenc} \newcommand{\authorindex}{\textsf{authorindex}} \newcommand{\mkindex}{\textsf{makeindex}} \newcommand{\aisty}{\texttt{authorindex.sty}} \newcommand{\aiperl}{\texttt{authorindex}} \newcommand{\perl}{\textsf{perl}} \newcommand{\Unix}{\textsc{Unix}} \newcommand{\Linux}{\textsc{Linux}} \newcommand{\solaris}{\textsc{solaris}} \newcommand{\fnext}[1]{\texttt{.#1}} \newcommand{\file}[1]{\texttt{#1}} \newcommand{\option}[1]{\texttt{#1}} \newcommand{\ltxinp}[1]{\texttt{\string#1}} \renewcommand\descriptionlabel[1]{\hspace\labelsep\normalfont\texttt{#1}} \title{The \authorindex\ Package} \author{Andreas Wettstein} \date{January 1998} \begin{document} \maketitle \begin{abstract} The \authorindex\ Package is intended to generate a list of all authors cited in a work along with a list of pages where these citations occur. Alternatively, the labels of the works that appear in the references can be listed instead of the pages. The package needs \perl\ to run. The use of \BibTeX\ is mandatory. The package can be used stand alone or as a preprocessor for \mkindex. \end{abstract} \section{Installation} The \authorindex-Package consists of the \LaTeX\ style file \aisty\ and the \perl\ script \aiperl. It needs \LaTeXe, \BibTeX\ \cite{Patashnik88a} and \perl\ to run. To install the package, move \aisty\ to a place where \LaTeX\ looks for its style files. The \perl\ script \aiperl\ must be moved to a place in your executable path and be given execution permission. You might also have to modify the path to the \perl\ binary that appears in the first line of the script \aiperl, replacing \file{/usr/bin/perl} by the correct path. \section{Using the package} \subsection{Modifications in your Text} \label{sec:ModText} \subsubsection{Preamble} To use the \authorindex-Package, in the preamble say \begin{verbatim} \usepackage{authorindex} \end{verbatim} The package accepts several options. \begin{itemize} \item Concerning the appearance of the author index: \begin{description} \item[small] will cause the author index to be set in small size. \item[normal] will cause the author index to be set in the normal text size. This is the default. \end{description} \item To control which names make it into the index: \begin{description} \item[editors] will cause the editor names to be included in the author index. \item[onlyauthors] will restrict the author index to the author names. This is, of course, the default. \item[onlyfirst] will include only the leading author (or editor) of each publication in the index. \item[all] will include all authors (or editors) of each work in the index (default). \end{description} \item To control how the names are formatted: \begin{description} \item[lastname] will only include the last name of the authors (and titles like ``von'', if present). \item[firstabbrev] will also include the abbreviated first name(s) (and eventually also a ``jr.''), following the last name. \item[fullname] finally will spell out the names in full (as complete as the names are present in the database). This is the default. \end{description} \item To choose what kind of references appear in the index: \begin{description} \item[withbib] will (apart from the pages where citations occur) also list the page of the bibliography entry where an author appears in the index. \item[biblabels] will include the label of the works (as it appears in the references) the author has written into the authorindex \item[pages] the pages of citations occur in the references (default) \end{description} \end{itemize} Optionally, you can use \ltxinp{\authorindexstyle}\verb|{|\textsl{somestyle\/}\verb|}| in the preamble, which causes the file \file{somestyle.bst} to be used to format the author names. This can be useful if the options described above still are not enough for you to get the format of the author names the way you like. To generate own formatter files, see Sec.~\ref{sec:CustNameFormat} below. Also optionally, \ltxinp{\aipagetypeorder}\verb|{|\textsl{order\/}\verb|}| determines the relative order of different types of page numbers. \textsl{order\/} is a string that consists of one of the characters \ltxinp{rRnAa}, which stand for lowercase roman, uppercase roman, arabic, uppercase alphabetic and lowercase alphabetic page numbers. The relative order of the page numbers is given by the order of the letters in the string. \ltxinp{rn}, for example, will sort all lowercase roman pages before the arabic pages. If you want to use lowercase alphabetic numbers, you have to use \ltxinp{\aipagetypeorder} and must not put \ltxinp{r} in the string, that is, you can't use lowercase roman numbers and lowercase alphabetic numbers at the same time (but you can use uppercase roman and alphabetical page numbers together). Composite page numbers (like ``4-17'') are split into their components (using any character that cannot be interpreted as a digit as field separator) and sorted with priority of components decreasing from left to right. \subsubsection{In the text} If you use the \ltxinp{biblabels} option, any citation will generate an entry in the author index. If you don't use the \ltxinp{biblabels} option, within the text, wherever you make a citation the author of which should go into the index, instead if using \ltxinp{\cite}, you must use \ltxinp{\aicite}.\footnote{If you put \ltxinp{\let}\ltxinp{\cite}\ltxinp{=}\ltxinp{\aicite} in the preamble after the loading of the package, you can make \ltxinp{\cite} behave like \ltxinp{\aicite}.} This command has exactly the same syntax as \ltxinp{\cite}. As an additional possibility you can use the command \ltxinp{\aimention}. Its single argument is an author name in \BibTeX\ name format (or more of them, separated \BibTeX-like by \ltxinp{and}. I don't recommend giving more than one author here, however, because when using the option \ltxinp{onlyfirst}, you probably won't get what you want.) At the place where you want the author index to appear, put \begin{verbatim} \printauthorindex \end{verbatim} in your source. This will later simply include the list the authors and the pages on which they are cited. Note that no chapter (or section) is started and the page layout is unchanged. It is up to you to do that according to your needs, either by explicitly putting necessary stuff in front or by customizing according to Sec.~\ref{sec:CustAppear}. Note also that you won't use \ltxinp{\printauthorindex} when using \aiperl\ as a preprocessor for \mkindex\ (see Sec.~\ref{sec:Runai}). \subsection{Running \aiperl} \label{sec:Runai} After having run \LaTeX\ on the properly prepared \LaTeX-source, you have to process the generated \fnext{aux}-files to generate the author index file (extension \fnext{ain}). This is done by the \perl\ script \aiperl. The script can be called with any number of arguments. With zero arguments, \aiperl\ reads from the standard input. With several arguments, \aiperl\ appends \fnext{aux} extensions wherever necessary and processes these files. The output is written to the file whose name is extracted from the \fnext{aux}-file where \ltxinp{\printauthorindex} was given. It is necessary to give the \fnext{aux}-file containing \verb|\begin{document}| to \aiperl, as via this file information regarding style and content of the index is passed to the script. If you give no arguments at all, standard input is read. If you use \ltxinp{\include} in your \LaTeX-source, it is sufficient to give the master \fnext{aux}-file to \aiperl; the \fnext{aux}-files of included files are processed then automatically. \aiperl\ recognizes the following options: \begin{description} \item[-d] (``draft'') Add additional information to the \fnext{ain} file: For each author, the labels of all her works and the page numbers where they are cited are included as comments. This is meant to help you when manually editing the generated author index. Also, a little bit of statistics is included at the bottom of the \fnext{ain} file. This does not work together with the \option{-i} option. \item[-h] (``help'') Print out small help. \item[-i] (``index'') Create a file suitable for further processing with \mkindex; for example, you could use that to make a common author and subject index. Note the extension of the generated file still will be \fnext{ain}. (Use the \option{-p} option and redirection to send the stuff anywhere else.) \item[-k] (``keep'') The temporarily generated \fnext{bst}-file is not deleted after \aiperl\ finishes. This is intended to give you a good start point for advanced customization of the author index (see Sec.~\ref{sec:CustNameFormat}). \item[-p] (``print'') Print the result to standard output instead of writing it to the \fnext{ain}-file. \item[-r] (``(don't) recurse'') Do not automatically process \fnext{aux}-files produced by included files. \end{description} \section{Customization} \subsection{Customizing the appearance} \label{sec:CustAppear} The author index is implemented via a special environment \ltxinp{theauthorindex}. For example, the file created by \aiperl\ will create a file with the following content: \begin{verbatim} \begin{theauthorindex} \item[Muster, Heinz] \aipages{7, 9, 23, \aibibpage{77}} \item[M\"uller, Fritz] \aipages{iv, 2, \aibibpage{77}} \indexspace \item[Schmitt, August] \aipages{33, \aibibpage{78}} \end{theauthorindex} \end{verbatim} You can now change the appearance of the author index by \begin{itemize} \item Using \ltxinp{\renewenvironment} to redefine the entire environment. This is useful to include titles, switching to multi column mode, and redefining \ltxinp{\indexspace}; \item Redefining \ltxinp{\aipages} by \ltxinp{\renewcommand} to change the appearance of the page numbers; \item Redefining \ltxinp{\aibibpage} by \ltxinp{\renewcommand} to change the appearance of the page number of the bibliography entry (only used in connection with the \option{withbib} package option); \item Redefining \ltxinp{\ainame}, which is used by \ltxinp{\item} to format the names of the authors (one argument); \item Redefining \ltxinp{\aisize}, which switches to the font size in which the author index is printed. \end{itemize} \subsection{Customizing the formatting of the names} \label{sec:CustNameFormat} If you want to do that, you have to know a little about \fnext{bst} file hacking, e.~g.\ by reading \cite{Patashnik88b}. Your \BibTeX\ style file has to generate a \fnext{bbl} that contains two lines for each author. The first line is the name formatted according to your taste. The second line contains the label of the citation. The default \fnext{bst} file used to format the names is embedded in the \perl\ script \aiperl. You probably can use this as template. To use your own style, use \ltxinp{\authorindexstyle} described in Sec.~\ref{sec:ModText}. To get a staring point for developing your own \fnext{bst} file, use \option{-k} for \aiperl\ (see Sec.~\ref{sec:Runai}). \section{If you have problems\ldots} \ldots it is probably my fault. I have tried out the package just on \Linux\ and \solaris\ and I don't know much about problems you might have on other systems, especially non-\Unix. Apart from that, I am aware of the following problems and restrictions: \begin{itemize} \item If you use \ltxinp{\aicite} with multiple arguments and a page break occurs within the list of generated references, one part of the citations will be associated with the wrong page. \item The package will fail for very long author names above 79 characters long (including spaces, commas, etc) or very long citation labels (at that point they force a line break in \BibTeX\ output). \item You can not use the package when you explicitly type in your bibliography in your \LaTeX\ file instead of using \BibTeX. \end{itemize} \begin{thebibliography}{1} \bibitem{Patashnik88a} Oren Patashnik. \newblock {{\BibTeX ing}}, 8~February 1988. \newblock Documentation for general {\BibTeX} users. \bibitem{Patashnik88b} Oren Patashnik. \newblock Designing {\BibTeX} styles, 8~February 1988. \newblock The part of \BibTeX's documentation that's not meant for general users. \end{thebibliography} \end{document}