From adc80d7a3ef83b1dff3402eaeaf362a65874c3c9 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 23 Sep 2012 22:56:44 +0000 Subject: imakeidx (23sep12) git-svn-id: svn://tug.org/texlive/trunk@27784 c570f23f-e606-0410-a88d-b1316a301751 --- .../texmf-dist/source/latex/imakeidx/imakeidx.dtx | 410 +++++++++++++++------ 1 file changed, 300 insertions(+), 110 deletions(-) (limited to 'Master/texmf-dist/source') 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. %\NeedsTeXFormat{LaTeX2e}[2005/12/01] %\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] % %<*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} % % \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 +% +%\fi % The end. % \Finale -- cgit v1.2.3