summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/imakeidx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2012-09-23 22:56:44 +0000
committerKarl Berry <karl@freefriends.org>2012-09-23 22:56:44 +0000
commitadc80d7a3ef83b1dff3402eaeaf362a65874c3c9 (patch)
tree4b9e48e0f408a65c6486a708ea865140d4a9a37c /Master/texmf-dist/source/latex/imakeidx
parent1a3d2a5725fcd461d05af13d1fa1390d483c9dc2 (diff)
imakeidx (23sep12)
git-svn-id: svn://tug.org/texlive/trunk@27784 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/imakeidx')
-rw-r--r--Master/texmf-dist/source/latex/imakeidx/imakeidx.dtx410
1 files changed, 300 insertions, 110 deletions
diff --git a/Master/texmf-dist/source/latex/imakeidx/imakeidx.dtx b/Master/texmf-dist/source/latex/imakeidx/imakeidx.dtx
index 9e2b1b62529..ce0dee8f868 100644
--- a/Master/texmf-dist/source/latex/imakeidx/imakeidx.dtx
+++ b/Master/texmf-dist/source/latex/imakeidx/imakeidx.dtx
@@ -1,4 +1,5 @@
% \iffalse
+% !TEX encoding = UTF-8 Unicode
%<*internal>
\begingroup
\input docstrip.tex
@@ -43,7 +44,7 @@ and the derived files imakeidx.sty and imakeidx.pdf.
%<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
%<package>\ProvidesPackage{imakeidx}%
%<*package>
- [2012/09/07 v1.1a Package for typesetting indices in a synchronous mode]
+ [2012/09/22 v1.2b Package for typesetting indices in a synchronous mode]
%</package>
%<*driver>
\documentclass{ltxdoc}
@@ -52,12 +53,14 @@ and the derived files imakeidx.sty and imakeidx.pdf.
\def\eTeX{\mbox{$\varepsilon$-\TeX}}
\def\Kvalue#1{\textsf{\textsl{#1}}}
\def\pack#1{\textsf{#1}}
+\def\class#1{\textsf{\itshape#1}}
\usepackage{multicol}
\usepackage[T1]{fontenc}
-\usepackage[latin1]{inputenc}
+\usepackage[utf8]{inputenc}
\usepackage[english]{babel}
\usepackage{textcomp,metalogo,booktabs}
\begin{document}
+\frenchspacing
\makeatletter
\GetFileInfo{imakeidx.dtx}% dtx extension required
\title{The package \pack{imakeidx}\thanks{Version number \fileversion; last
@@ -75,13 +78,15 @@ and the derived files imakeidx.sty and imakeidx.pdf.
\end{document}
%</driver>
% \fi
-% \CheckSum{742}
+% \CheckSum{783}
%
% \changes{v1.0}{2010/07/10}{First public version}
% \changes{v1.0a}{2010/07/12}{Small bug correction}
% \changes{v1.1}{2012/05/09}{Fixed compatibility with \pack{memoir}}
% \changes{v1.1}{2012/05/09}{Modified interaction with Lua\TeX}
-% \changes{v1.1a}{2012/09/07}{Fixed bug with possibly defined \cs{directlua}}
+% \changes{v1.2}{2012/0831}{made package compatible with showidx}
+% \changes{v1.2}{2012/0831}{made package compatible with fancyhdr}
+% \changes{v1.2}{2012/0831}{added index processing engine option truexindy}
%
% \begin{abstract}
% This package exploits the |\write18| facility of modern \TeX\ system
@@ -118,27 +123,29 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% this package is \prog{makeindex}. This precaution is necessary in
% order to avoid running malicious code. Other programs can be run,
% though, but it's necessary to expressly tell \prog{pdftex} that it
-% can do so; this authorisation is given by means of a suitable
+% can do so; this authorization is given by means of a suitable
% program option, as explained below.
%
% This package will exploit this facility in order to run a perl
% script that is capable of splitting a raw index file into different
-% chunks and to run the \prog{makeindex} \TeX\ system program so as to
-% sort and format the index entries according to a specified index
-% style file. Once the shell is terminated, the \prog{pdftex} program
-% resumes its work and possibly prints the various formatted indices
-% produced in previous step. In this way the document indices are
-% always synchronous with their document and no further \prog{pdftex}
-% runs are necessary.
-%
-% In order to reach this goal, it necessary to enable the
-% \prog{pdftex} engine to run the so-called |\write18| facility;
+% chunks and to run the \prog{makeindex} or \prog{xindy} \TeX\ system
+% programs so as to sort and format the index entries according to a
+% specified index style file. Once the shell is terminated, the
+% typesetting program resumes its work and possibly prints the various
+% formatted indices produced in previous steps. In this way the document
+% indices are always synchronous with their document and no further
+% typesetting runs are necessary.
+%
+% In order to reach this goal, it is necessary that at least the
+% restricted |write18| facility is enabled; if the \TeX\ distribution
+% in use does not enable this restricted feature by default, it
+% is necessary to enable the typesetting engine to run such facility;
% depending on the distribution and the shell editor that is being
% used to work on a specific document, it is necessary to add
% \texttt{-shell-escape} (or \texttt{-\/-enable-write18} for MiK\TeX)
-% to the command with which \prog{pdftex} is launched, possibly by the
-% shell editor. What's been said for \prog{pdftex} goes without change
-% for the \prog{xetex} and \prog{luatex} typesetting engines.
+% to the command with which the typesetting program is launched,
+% possibly through the shell editor. This applies to all three
+% \prog{pdftex}, \prog{xetex}, and \prog{luatex} typesetting engines.
%
% {\medskip\footnotesize If Lua\LaTeX{} is used and \prog{luatex} is
% version 0.42 to 0.66, it's impossible to distinguish whether the
@@ -147,13 +154,6 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% package option. With version 0.68 or later, the behavior is the same
% as with the other engines.\par}
%
-% \subsection*{Note}
-%
-% The first public version of this package was not compatible with the
-% \pack{memoir} class. Since version 1.1 it is; however, one has to
-% keep in mind that all index processing is done with the methods of
-% the present package, and \emph{not} with \pack{memoir}'s; however
-% the syntax used is the same and there should be no problem.
%
%\section{Package usage}
% This package is invoked as usual by means of a \cs{usepackage} command:
@@ -170,12 +170,18 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% \Item[xindy] in order to use the \prog{xindy} sorting and formatting
% engine; \texttt{texindy} is an alias for \texttt{xindy} and actually
% it's the script \prog{texindy} which is called by this package.
-% \Item[noautomatic] disables the automatic splitting and running of
-% the system programs; this option might be used to save time when one
-% knows for sure that the index files are already OK and do not need
-% to be refreshed. Actually the time spent in splitting, sorting and
-% formatting is so short that this option might be useful only when
-% very lengthy indices are being processed.
+% Nevertheless if the real \prog{xindy} is desired, in order to avoid
+% the settings made up by \prog{texindy}, so as to add \prog{xindy}
+% the command line specific settings, it is possible to specify the
+% option \texttt{truexindy}; the user is then responsible to set up
+% the \prog{xindy} engine with the suitable command line options.
+% \Item[noautomatic] disables the automatic splitting of the raw
+% index files and running of the system programs; this option might
+% be used to save time when one knows for sure that the index files
+% are already OK and do not need to be refreshed. Actually the time
+% spent in splitting, sorting and formatting is so short that this
+% option might be useful only when very lengthy indices are being
+% processed.
% \Item[nonewpage] inhibits the new page command to be issued when
% using an article type document class and multiple indices are being
% typeset. We don't see why someone would use multiple indices in an
@@ -183,25 +189,25 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% provide a macro index and a list of changes).
% \Item[quiet] suppresses all messages about manual index
% processing.
-% \Item[original] uses the class provided \texttt{theindex}
+% \Item[original] uses the class-provided \texttt{theindex}
% environment for typesetting the indices; it is implicitly set if the
% document class option \texttt{twocolumn} has been specified.
% \Item[splitindex] calls the \prog{splitindex} script by Markus Kohm,
% which is included in every \TeX~Live distribution since 2009. With
-% this option all index entries, which are written in one raw file,
-% are successively split into all the requested index files; in this
-% way there is virtually no limit on the number of indices that is
-% possible to create for a particular document.
+% this option all index entries, which are written in one raw index
+% file, are successively split into all the requested index files;
+% in this way there is virtually no limit on the number of indices
+% that is possible to create for a particular document.
% \end{description}
%
% The last described option deserves an explanation. \LaTeX{} can
% write on a limited number of files during a run, and some of these
-% \emph{output streams} are already reserved (among these: aux file,
-% table of contents, list of figures, list of tables). When more than
+% \emph{output streams} are already reserved (among these: aux files,
+% toc files, lof files, lot files, plus several other ones). When more than
% one index is produced, there's the risk to run off the number of
% writable files, because normally \pack{imakeidx} reserves an output
% stream for each index. So the \texttt{splitindex} option comes to
-% rescue: with it only \emph{one} index file is written. At the
+% rescue: with it only \emph{one} raw index file is written. At the
% first \cs{printindex} command, the program \prog{splitindex} is
% called; it splits the large index file into as many parts as the
% number of requested indices; after this, \prog{makeindex} (or
@@ -214,7 +220,7 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% \begin{verbatim}
% ! No room for a new \write
% \end{verbatim}
-% Apart from this case, with or without it the results are the
+% Apart from this case, with or without it, the results are the
% same. See section~\ref{sec:wrong} to see what files are written
% during the \LaTeX{} run with or without the option.
%
@@ -242,26 +248,26 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% Example: \texttt{name=nameidx}
% \Item[title] is the title that is typeset at the beginning of the
% specific index; if not specified, the \cs{indexname} value is
-% used.\\* Example: \texttt{title=Index of names}
+% used.\\* Example: \texttt{title=Index of names}.
% \Item[program] is the name of the system program that is used to
% sort and format an index; valid choices are \prog{makeindex},
-% \prog{xindy}, or \prog{texindy}. If not specified the program
-% specified among the package options is used. If no option is
-% specified, \prog{makeindex} is used. In order to use \prog{xindy},
-% it's necessary to call \progpdflatex{} with the shell escape
-% command line option.\\* Example: \texttt{program=xindy}
+% \prog{xindy}, or \prog{texindy}, plus \prog{truexindy}. If not
+% specified the program specified among the package options is used.
+% If no option is specified, \prog{makeindex} is used. In order to
+% use \prog{xindy}, it's necessary to call \progpdflatex{} with
+% the shell escape command line option.\\* Example: \texttt{program=xindy}.
% \Item[options] is the list of options to be passed to the sorting
% and formatting program; this list is a balanced text of program
% options, separated with the syntax required by the sorting and
% formatting program. For example, in order to use a different
% \prog{makeindex} sorting and formatting style \pack{mystyle.ist} and
-% avoiding any message in the screen output write \texttt{options=-s
-% mystyle}
+% avoiding any message in the screen output, write \texttt{options=-s
+% mystyle}.
% \Item[noautomatic] is a boolean key that defaults to \texttt{false};
% you can set it to \texttt{true} by simply listing its key in the
% key-value list, without necessarily specifying the \texttt{=true}
% part. If specified the index sorting program won't be called during
-% the \prog{pdftex} run for this particular index.
+% the typesetting run for this particular index.
% \Item[intoc] is a boolean variable that defaults to \texttt{false};
% if you want to set it \texttt{true} you must simply list this key in
% the key-value list, with no need of specifying the \texttt{=true}
@@ -278,15 +284,17 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% between the index columns.
% \end{description}
% \Item[indexsetup] with the syntax:\\[1ex]
-% \cs{indexsetup}\oarg{key-values}\\[1ex]
-% where again \meta{key-values} is a comma separated list of key-value
+% \cs{indexsetup}\marg{key-values}\\[1ex]
+% where again \meta{key-values} is a comma separated list of \texttt{key=value}
% assignments; the available keys are:
% \begin{description}\def\Item[#1]{\item[\normalfont\sffamily\textsl{#1}]}
% \Item[level] which takes as value a sectioning command such as
% \cs{chapter} or \cs{chapter*}. Actually any command with an argument
% will do and will receive the index title as its argument. The
% default is \cs{chapter*} or, if the class doesn't provide chapters,
-% \cs{section*}.
+% \cs{section*}. If you specify |\caption| so as to override the default
+% |\chapter*|, the index title goes directly to the table of contents;
+% in this case do not specify the \texttt{intoc} option.
% \Item[toclevel] which takes as value a sectioning command
% \emph{name} such as \texttt{section} to indicate the level at which
% we want the indices appear in the table of contents.
@@ -302,13 +310,17 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% \printindex[names]
% \printindex[objects]
%\end{verbatim}
+% See more on this subject in section~\ref{sec:hints}
% \Item[firstpagestyle] which takes as value a page style, default
% \texttt{plain}. You might want to set it to \texttt{empty} or some
-% other page style defined by the class or by yourselves.
-% \Item[headers] which takes as value the left and right marks. You
+% other page style defined by the class or by yourselves. This keyword
+% is disabled when the package \pack{fancyhdr} is loaded; any definition
+% or choice of page styles must be done before typesetting the indices.
+% \Item[headers] which takes two values: the left and right marks. You
% might want to use this for disabling automatic uppercasing, by
-% saying |headers={\indexname}{\indexname}|; notice that this value
-% should always be a pair of braced texts.
+% saying, for example, |headers={\indexname}{\indexname}|; notice that
+% these values should always be a pair of balanced braced texts.
+% Don't use these keys if you use \pack{fancyhdr}.
% \Item[othercode] which takes as value arbitrary \TeX{} code that
% will be executed at the beginning of index entries typesetting. For
% example you might want to change here the setting of \cs{parskip}.
@@ -320,7 +332,7 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% processed by this package.
% \Item[index] with the syntax:\\[1ex]
% \cs{index}\oarg{name}\marg{entry}\\[1ex]
-% inserts \meta{entry} into the raw index file; upon splitting it in
+% inserts \meta{entry} into the raw index file(s); upon splitting it in
% different files, this particular entry is listed in the specific
% index file with name \meta{name}; if no name is specified, this
% \meta{entry} is added to the default index with name
@@ -362,6 +374,10 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% ...
% \begin{document}
% ...
+% ...relativity\index{relativity}...
+% ...
+% ... Einstein\index[persons]{Einstein, Albert}...
+% ...
% And this is the end of the story.
%
% \printindex
@@ -371,11 +387,9 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% \printindex[persons]
% \end{document}
%\end{verbatim}
-% will produce two indices. Entries for the first one must be typed as
-% |\index{gnu}|, while entries for the second are of the form
-% |\index[persons]{Lamport, Leslie}|. The prologue will be printed
-% (full line) only in the ``Index of names'', which will be typeset in
-% three columns.
+% will produce two indices. Entries for either index must be typed as
+% shown above. The prologue will be printed (full text width) only
+% in the ``Index of names'', which will be typeset in three columns.
%
% When the \texttt{original} option is set, maybe implicitly because
% of \texttt{twocolumn}, \cs{indexsetup} and the keys
@@ -392,10 +406,11 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% you shouldn't need anything special, since \prog{makeindex} is among
% the safe programs allowed to be called during a \LaTeX{} run, be it
% \prog{latex}, \prog{pdflatex}, \prog{xelatex}, or \prog{lualatex}.
-% When the options \texttt{splitindex}, \texttt{xindy} or
-% \texttt{texindy} are specified (globally or locally), the \LaTeX{}
-% run should be called with \texttt{-shell-escape} (which is
-% \texttt{--enable-write18} for MiK\TeX) or the \texttt{noautomatic}
+% When the options \texttt{splitindex}, \texttt{xindy},
+% \texttt{texindy} or \texttt{truexindy} are specified (globally or
+% locally), the \LaTeX{} run should be called with the unrestricted
+% \texttt{-shell-escape} (which is \texttt{--enable-write18} for
+% MiK\TeX) typesetting program option or the \texttt{noautomatic}
% option should be specified when loading \pack{imakeidx}.
%
% Let's look at a couple of examples. In both we suppose that the
@@ -413,7 +428,7 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% command, \prog{makeindex} will act on each of them producing the files
% \texttt{mybook.ind}, \texttt{mybook.ilg}, \texttt{secondary.ind} and
% \texttt{secondary.ilg}. The \texttt{.ind} files contain the relevant
-% \texttt{theindex} environment with alphabetized entries, while in
+% \texttt{theindex} environments with alphabetized entries, while in
% the \texttt{.ilg} files \prog{makeindex} will write its log. You can
% check in \texttt{mybook.log} whether the \prog{makeindex} run has
% been executed by searching for a line
@@ -427,15 +442,16 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% shell escape is not active; also, of course, if you set the
% \texttt{noautomatic} option for the index.
%
+% {\tolerance=9999
% When using \prog{splitindex}, the situation is different. During the
% \LaTeX{} run, only a large index file called \texttt{mybook.idx} file
% gets written; the first \cs{printindex} command will call
-% \prog{splitindex} (shell escape \emph{must} be active), which will
-% produce the two partial index files \texttt{mybook-mybook.idx} and
-% \texttt{mybook-secondary.idx}. These two files will be processed by
-% \prog{makeindex} producing the four files
-% \texttt{mybook-mybook.ind}, \texttt{mybook-mybook.ilg},
-% \texttt{mybook-secondary.ind} and \texttt{mybook-secondary.ilg}.
+% \prog{splitindex} (unrestricted shell escape \emph{must} be active),
+% which will produce the two partial index files \texttt{mybook-mybook.idx}
+% and \texttt{mybook-secondary.idx}. These two files will be processed by
+% \prog{makeindex} producing the four files \texttt{mybook-mybook.ind},
+% \texttt{mybook-mybook.ilg}, \texttt{mybook-secondary.ind} and
+% \texttt{mybook-secondary.ilg}.
% The line
%\begin{verbatim}
% runsystem(splitindex <...>)...executed
@@ -443,7 +459,8 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% in \texttt{mybook.log} will tell that the splitting has been done
% (see later on if this doesn't seem true). In table~\ref{tab:files} you
% can see what files are produced when the first two lines are in the
-% preamble.
+% preamble.\par}
+%
% \begin{table}[tp]
% \centering\begingroup\ttfamily
% \begin{tabular}{rll}
@@ -521,12 +538,71 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% If shell hackers know a way to access the exit status of the called
% program, we'd be glad to implement a supplementary check.
%
-% \section{Hints}
+% ^^A G
+% \section{Hints}\label{sec:hints}
% Actually this package reaches two goals: (\textit{a})~it typesets
% the indices of a specific document in just one run, and
% (\textit{b})~it lets the author\slash typesetter produce
% documents with multiple indices.
%
+% \subsection{Conflicts}
+% \subsubsection{Class \class{memoir}}
+%
+% The first public version of this package was not compatible with the
+% \pack{memoir} class. Since version 1.1 it is; however, one has to
+% keep in mind that all index processing is done with the methods of
+% the present package, and \emph{not} with \pack{memoir}'s; however
+% the syntax used is the same and there should be no problem.
+%
+% \subsubsection{Package \pack{showidx}}
+%
+% Up to version 1.1 this package did not allow to use it together with the \pack{showidx}
+% package; now it is, provided that \pack{showidx} is loaded \emph{before} \pack{imakeidx}.
+% See below more information on using \pack{showidx}.
+%
+% \subsubsection{Package \pack{fancyhdr}}
+%
+% When using package \pack{fancyhdr} some inconveniences did show up; now we believe
+% we have detected the causes and we implemented the necessary corrections\footnote{Thanks
+% to Maïeul Rouquette, who spotted the problems and also suggested some patches.}.
+%
+% \subsubsection{Package \pack{combine}}
+%
+% Apparently there might be some conflicts with package \pack{combine}, because this
+% package redefines the contents of |\jobname|; we tried to control this behavior,
+% and made the necessary patches, but it is still necessary to load this
+% package \pack{imakeidx} \emph{before} package \pack{combine}.
+%
+% \subsubsection{Package \pack{ledmac}}
+%
+% Some users reported some conflicts with package \pack{ledmac}; in order to mark
+% with an italic `n' the pages where the reference was made in one of the footnotes,
+% it is necessary to use the package \pack{etoolbox} and its command |\pretocmd|;
+% actually it is not necessary to load \pack{etoolbox}, because this \pack{imakeidx}
+% provides for it:
+%\begin{verbatim}
+%...
+%\usepackage{letltxmacro}
+%\usepackage{imakeidx}
+%...
+%\makeatletter
+%\LetLtxMacro\orig@@index\index
+%\let\orig@@index\index
+%\newcommand\nindex[1]{\orig@@index{#1|innote}}
+%\newcommand\innote[1]{#1\textit{n}}
+%...
+%\makeindex[...]
+%...
+%\AtBeginDocument{%
+% \pretocommand{\@footnotetext}{\let\index\nindex}{}{}
+%}
+%\end{verbatim}
+% We did not apply this patch directly because we tried to avoid possible conflicts
+% that might show up when loading other packages. Therefore we simply show what
+% to do in case it might be necessary.
+
+%
+%\subsection{Index layout customization}
% If you redefine yourself the \texttt{theindex} environment, please
% remember not to number the chapter or section that introduces the
% index if you ask for the \Kvalue{intoc} option; either use the
@@ -534,20 +610,96 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% \Kvalue{intoc} option or don't use this option and redefine your
% \texttt{theindex} environment with numbered chapter or section
% commands, that will put the index titles directly into the table of
-% contents. You may use the \pack{idxlayout} package by Thomas Titz,
+% contents. See below the effect of the |\backmatter| declaration.
+% You may use the \pack{idxlayout} package by Thomas Titz,
% which offers many functions for index typesetting customization and
% is compatible with our package; remember to load \pack{idxlayout}
% after \pack{imakeidx}. This package has a similar function to our
% \cs{indexprologue}, called \cs{setindexprenote}; however
% \pack{idxlayout} doesn't reset the index prologue, which must be
% declared anew or disabled with \cs{noindexprenote} before the next
-% \cs{printindex} command.
+% \cs{printindex} command. In any case take into serious consideration
+% what is being said hereafter about customizations.
+%
+% \subsection{Index page customization}
+% The same, more or less, holds true if you customize your headings;
+% \pack{imakeidx} can deal with standard settings, but it generally
+% cannot deal with personal stylings and customizations. This is why
+% if you load \pack{fancyhdr}, some of the |\indexsetup| settings may be
+% disabled.
+
+% When you make any kind of customization, remember that there are
+% several class or personal settings or features that may render your
+% customization very difficult to handle.
+%
+% Remember that:
+%\begin{itemize}
+% \item There are classes where the normal usable highest sectioning
+% command, disregarding |\part|, is not |\chapter|, but |\section|; for
+% example class \class{article}, \class{scrartcl}.
+%\item Sectioning commands come in two varieties: starred and unstarred;
+% the former ones are not numbered and do not produce any entry in the
+% headings and in the table of contents; the latter ones may behave
+% differently according to the next list entry.
+% \item There are some classes (for example \class{book},
+% \class{scrapbook}, \class{menoir},\dots) that have the special
+% ``sectioning'' declarations |\fontmatter|, |\mainmatter|, and
+% |\backmatter| modify how the unstarred sectioning commands behave for
+% what concerns the heading and the table of contents entries.
%
-% If by chance you get double entries into the table of contents,
-% eliminate the \Kvalue{intoc} option from your calls; your class and
-% packages are already taking care of it. The package \pack{tocbibind}
-% should be loaded with the \texttt{noindex} option, otherwise it
-% would interfere with our redefinition of \texttt{theindex}.
+% For what concerns indices, these are generally typeset at the document
+% end. This means that the |\backmatter| declaration may be in force;
+% in this case unstarred sectioning commands are not numbered but they
+% produce normal headings and table of contents entries.
+%\item Heading entries are used by the output routine paging algorithm
+% in such a way as to extract the left or the right part from suitable
+% ``marks''; for the even (left) pages the required information is
+% extracted from the |\topmark| or |\firstmark|, while for the odd (right)
+% pages they are extracted from the |\botmark|. Generally speaking,
+% the even page heading refers to |\leftmark| and odd page headings
+% refer to |\rightmarkk|; there are the two commands that extract the
+% correct part from the suitable marks. But when you use the
+% \Kvalue{headers} value you specify two brace balanced strings that
+% are loaded through |\markboth| as the left and right part of the
+% current mark.
+% \item The contents of the marks may be very varied; they are generally
+% made up of two brace balanced strings, which in turn may contain other
+% brace balanced stings that may be used in different ways by the selected page
+% style and by the page style definitions of the macros |\chaptermarks|,
+% |\sectionmarks|, and |\subsectionmarks| that may interfere with personal
+% customizations.
+% \item Remember also that things change in an obvious way when one side
+% typesetting is chosen; all a pages are treated as if they were odd ones;
+% therefore any customization must take into account also this aspect.
+%\end{itemize}
+%
+% The above list has not been written down for discouraging customizations
+% of any kind: simply it recall what mast be taken care of in order to
+% create one's customization in a proper way.
+%
+% The above list explains why we disabled the commands tied to the
+% |\indexsetup| keys \Kvalue{headings} and \Kvalue{firstpagestyle} when
+% package \pack{fancydr} is being used; you may even set up these keys,
+% but if the \pack{fancyhdr} package has been load, we disable their
+% action; this implies that any fancy customization must be done before
+% starting to print any index.
+%
+% The \Kvalue{intoc} must also be used with care, as well as the starred
+% or unstarred sectioning commands for the \Kvalue{level} and
+% \Kvalue{toclevel} values. They must be chosen according to what the
+% possible |\backmatter| declaration sets up, in order to avoid double
+% entries in the table of contents; the |\backmatter| settings may also
+% influence the way heading information is being used, and this makes it
+% even more stringent to set up any index page style customization
+% before starting to print any index.
+%
+% Therefore if by chance you get double entries into the table of contents,
+% eliminate the \Kvalue{intoc} option from your calls; your class,
+% packages, and settings are already taking care of it.
+
+% The package \pack{tocbibind} should be loaded with the \texttt{noindex}
+% option, otherwise it would interfere with our redefinition of
+% \texttt{theindex}.
%
% If you redefine your \texttt{theindex} environment by means of other
% packages, pay attention that these redefine a real \texttt{theindex}
@@ -557,9 +709,19 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% creates a sorted and formatted \texttt{.ind} file that refers
% explicitly to the \texttt{theindex} environment), and it can't take
% care of the table of contents entry and of the position of the hyper
-% link anchor needed to navigate your document by means of hyper
+% link anchors needed to navigate your document by means of hyper
% links.
%
+% \subsection{Using the \textsf{showidx} package}
+% If you want to make use of the \pack{showidx} facilities, remember
+% to load that package \emph{before} \pack{imakeidx}; remember also
+% to disable or comment out the call to \pack{showidx} when you
+% typeset the final version of your document. This constraint is due
+% to the fact that \pack{showidx} redefines several internal commands,
+% some of which have to receive the \pack{imakeidx} definition in order
+% to perform as described in this documentation.
+%
+% \subsection{Index List sectioning customization}
% Use freely the options and the key values in order to reach the
% desired results, but you are advised to prepare in advance the
% styles for composing the various indices in a proper way; for
@@ -582,8 +744,7 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% file names, and for some names only the extension is entered; the
% extensions start with a dot, so the sorting program will sort these
% names at the beginning of the sorted index file, but you won't like
-% to have
-% a title such as ``Symbols''; you probably prefer to have a title
+% to have a title such as ``Symbols''; you probably prefer to have a title
% such as ``Extensions''; therefore you have to prepare a different
% index style file, such as this one:
%\begin{verbatim}
@@ -604,8 +765,8 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% titles shall appear in the table of contents, and if you are
% preparing an e-book, you probably would like to hyper link both the
% page numbers and the index titles to the proper locations.
-% \prog{pdflatex} will do everything for you but be careful not to
-% confuse it with illogical index entries.
+% The typesetting program will do everything for you but be careful
+% not to confuse it with illogical index entries.
%
% Especially with multiple indices it is important that you are
% consistent in putting the right information in the right index and
@@ -629,6 +790,9 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% Notice that in order to create a specific name space so as to avoid
% possible conflicts with other packages, all the commands defined in
% this package are prefixed with the string \texttt{imki@}.
+%\iffalse
+%<*package>
+%\fi
% \begin{macrocode}
\RequirePackage{xkeyval}
% \end{macrocode}
@@ -639,13 +803,15 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% which is incompatible with \pack{multicol}. We define also an
% internal alias for |\immediate\write18|, a rudimentary check for the
% typesetting engine and a macro for modifying the command line call
-% to \prog{splitindex}.
-% \changes{v1.1a}{2012/09/07}{Fixed bug with possibly defined
-% \cs{directlua}; now we leave the check to \pack{ifluatex}; using
-% also \pack{ifxetex} for symmetry.}
+% to \prog{splitindex}. The \pack{xpatch} is requested; at the moment
+% none if its features are used, but it calls \pack{etoolbox}, whose
+% facilities are used here; while future extensions will benefit from
+% the extended patched commands, that strongly enrich the performances
+% of the main package \pack{etoolbox}.
% \begin{macrocode}
\DeclareOption{xindy}{\def\imki@progdefault{texindy}}
\DeclareOption{texindy}{\def\imki@progdefault{texindy}}
+\DeclareOption{truexindy}{\def\imki@progdefault{truexindy}}
\DeclareOption{makeindex}{\def\imki@progdefault{makeindex}}
\newif\ifimki@disableautomatic
\DeclareOption{noautomatic}{\imki@disableautomatictrue}
@@ -666,9 +832,8 @@ and the derived files imakeidx.sty and imakeidx.pdf.
\if@twocolumn\imki@originaltrue\fi
\def\imki@exec{\immediate\write18}
\def\imki@engine{(pdf)latex}
-\RequirePackage{ifxetex,ifluatex}
-\ifxetex\def\imki@engine{xelatex}\fi
-\ifluatex % luatex doesn't have \(pdf)shellescape
+\ifdefined\XeTeXversion\def\imki@engine{xelatex}\fi
+\ifdefined\directlua % luatex doesn't have \(pdf)shellescape
\def\imki@engine{lualatex}
\ifnum\luatexversion<68
\chardef\imki@shellescape\@ne % no way to know the value
@@ -678,6 +843,7 @@ and the derived files imakeidx.sty and imakeidx.pdf.
\fi
\let\imki@exec\pdf@system
\fi
+\RequirePackage{xpatch}
\edef\imki@splitindexoptions{-m \string"\string"}
\def\splitindexoptions#1{\g@addto@macro\imki@splitindexoptions{ #1}}
\@onlypreamble\splitindexoptions
@@ -741,7 +907,7 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% we have to reset the defaults.
% \begin{macrocode}
\def\imki@makeindex#1{%
- \def\imki@name{\jobname}%
+ \edef\imki@name{\jobname}%
\def\imki@title{\indexname}%
\edef\imki@program{\imki@progdefault}%
\let\imki@options\space
@@ -761,13 +927,15 @@ and the derived files imakeidx.sty and imakeidx.pdf.
\define@key{imki}{name}{\def\imki@name{#1}}
\define@key{imki}{title}{\def\imki@title{#1}}
\define@choicekey{imki}{program}[\imki@val\imki@nr]
- {makeindex,xindy,texindy}{%
+ {makeindex,xindy,texindy,truexindy}{%
\ifcase\imki@nr\relax
\def\imki@program{makeindex}%
\or
\def\imki@program{texindy}%
\or
\def\imki@program{texindy}%
+ \or
+ \def\imki@program{xindy}%
\fi}
\define@key{imki}{options}{\def\imki@options{ #1 }}
\define@boolkey{imki}{noautomatic}[true]{}
@@ -832,7 +1000,7 @@ and the derived files imakeidx.sty and imakeidx.pdf.
\def\imki@startidxsplit#1{%
\if@filesw
\def\index{\@bsphack
- \@ifnextchar [{\@index}{\@index[\jobname]}}
+ \@ifnextchar [{\@index}{\@index[\imki@name]}}
\expandafter\newwrite\csname #1@idxfile\endcsname
\immediate\openout \csname #1@idxfile\endcsname #1.idx\relax
\typeout{Writing index file #1.idx}%
@@ -846,11 +1014,11 @@ and the derived files imakeidx.sty and imakeidx.pdf.
\if@filesw
\ifimki@startedidx\else
\newwrite\@indexfile
- \immediate\openout\@indexfile\jobname.idx%
+ \immediate\openout\@indexfile\imki@name.idx%
\global\imki@startedidxtrue
\fi
\def\index{\@bsphack
- \@ifnextchar [{\@index}{\@index[\jobname]}}
+ \@ifnextchar [{\@index}{\@index[\imki@name]}}
\expandafter\let\csname #1@idxfile\endcsname\@empty
\typeout{Started index file #1}%
\fi}
@@ -883,17 +1051,23 @@ and the derived files imakeidx.sty and imakeidx.pdf.
%
% Command \cs{@wrindex} must be duplicated; we have to call it the
% same as usual in order to support \pack{hyperref}. But the real name
-% will be given at the end.
+% will be given at the end. We have to define a switch to allow the use of the \pack{showidx} facilities. We define also a helper macro so as to do the right thing so as to show the index file name to which a certain index entry is going to be written; the idea is to prefix the induex entry with the actual name of the specific index, except in the case or the default index, where the name is set to |\jobname|. Since they control sequence is a primitive command, its value cannot be directly compared in the |\ifx| sense to the current macro represented by argument |#1|. therefore we need a further helper control sequence |\imki@jobname| that contains the value assigned to |\jobname|.
% \begin{macrocode}
+\newif\ifimki@showidx
+\@ifpackageloaded{showidx}{\imki@showidxtrue}{\imki@showidxfalse}
+\edef\imki@jobname{\jobname}
+\newcommand\imki@showidxentry[2]{\ifimki@showidx
+\@showidx{\ifdefequal{\imki@jobname}{#1}{}{[#1]\space}#2}%
+\fi}
\def\imki@wrindexsplit#1#2{%
\expandafter\protected@write\csname#1@idxfile\endcsname{}%
{\string\indexentry{#2}{\thepage}}%
- \endgroup
+ \endgroup\imki@showidxentry{#1}{#2}%
\@esphack}
\def\imki@wrindexunique#1#2{%
\protected@write\@indexfile{}%
{\string\indexentry[#1]{#2}{\thepage}}%
- \endgroup
+ \endgroup\imki@showidxentry{#1}{#2}%
\@esphack}
% \end{macrocode}
%
@@ -939,7 +1113,22 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% environment, based on the standard, but using, if the number of
% columns is greater than one, the \texttt{multicols} environment.
% Users needing a different setup can use the \cs{indexsetup} command.
+% Before doing so, though, we need to disable certain features if the
+% package \pack{fancyhdr} is loaded sometimes before the
+% |\begin{document| statement, be it before or after loading
+% \pack{imakeidx}. If that package is loaded we have to patch the
+% definition of the environment |theindex|, because its default
+% commands interfere with those defined here that work perfectly
+% when \pack{fancyhdr} is not loaded. This patching could be defined
+% further on, but if it stay close to what has to be patched, it's
+% easier to understand it's operation.
% \begin{macrocode}
+\newif\ifimki@fancyhdr
+\AtBeginDocument{\@ifpackageloaded{fancyhdr}{\imki@fancyhdrtrue}{\imki@fancyhdrfalse}%
+\ifimki@fancyhdr
+ \patchcmd{\theindex}{\imki@indexheaders}{\relax}{}{}%
+ \patchcmd{\theindex}{\thispagestyle}{\@gobble}{}{}\fi}
+%
\ifimki@original
\expandafter\def\expandafter\theindex\expandafter{\expandafter
\imki@maybeaddtotoc\theindex}
@@ -968,7 +1157,6 @@ and the derived files imakeidx.sty and imakeidx.pdf.
\let\item\@idxitem
\imki@othercode}
{\ifnum\imki@columns>\@ne\end{multicols}\fi
-% \clearpage
}
\fi
% \end{macrocode}
@@ -1007,11 +1195,11 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% checks and messages.
% \begin{macrocode}
\providecommand*{\printindex}{}
-\renewcommand*{\printindex}[1][\jobname]{%
+\renewcommand*{\printindex}[1][\imki@name]{%
\@ifundefined{#1@idxfile}{\imki@error{#1}}{\imki@putindex{#1}}}
\def\imki@error#1{%
- \def\@tempa{#1}\def\@tempb{\jobname}%
+ \def\@tempa{#1}\def\@tempb{\imki@name}%
\ifx\@tempa\@tempb
\let\imki@optarg\@empty
\else
@@ -1025,7 +1213,7 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% \end{macrocode}
%
% We define a command to do a \cs{cleardoublepage} if the option
-% \Kvalue{openright} holds (in classes where \Kvalue{twoside} is
+% \Kvalue{openright} is active (in classes where \Kvalue{twoside} is
% meaningful). In case \cs{chapter} is defined but not
% \cs{if@openright}, we assume that the class wants ``open right''.
% \begin{macrocode}
@@ -1133,7 +1321,7 @@ and the derived files imakeidx.sty and imakeidx.pdf.
\if@tempswa % we can call the external program
\ifimki@splitdone\else
\immediate\closeout\@indexfile
- \imki@exec{splitindex \imki@splitindexoptions\space\jobname.idx}%
+ \imki@exec{splitindex \imki@splitindexoptions\space\imki@name.idx}%
\global\imki@splitdonetrue
\fi
\else
@@ -1142,7 +1330,7 @@ and the derived files imakeidx.sty and imakeidx.pdf.
\fi
\fi
\if@tempswa % we can call the external program
- \imki@exec{\imki@program\imki@options\jobname-#1.idx}%
+ \imki@exec{\imki@program\imki@options\imki@name-#1.idx}%
\fi
\ifKV@imki@intoc
\def\imki@maybeaddtotoc{\@nameuse{phantomsection}%
@@ -1153,7 +1341,7 @@ and the derived files imakeidx.sty and imakeidx.pdf.
\ifx\imki@title\imki@check@indexname\else
\def\indexname{\imki@title}%
\fi
- \@input@{\jobname-#1.ind}
+ \@input@{\imki@name-#1.ind}
\let\indexname\imki@indexname % restore \indexname
}
% \end{macrocode}
@@ -1183,6 +1371,8 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% \begin{macrocode}
\@ifclassloaded{memoir}{\let\@wrindexm@m\@wrindex}{}
% \end{macrocode}
-
+%\iffalse
+%</package>
+%\fi
% The end.
% \Finale