• No results found

Index of /CTAN/macros/latex/contrib/imakeidx


Academic year: 2022

Share "Index of /CTAN/macros/latex/contrib/imakeidx"


Full text


The package imakeidx

Enrico Gregorio


1 Introduction 1

2 Package usage 2

3 Specific package commands 4 4 If something goes wrong 7

5 Hints 9

5.1 Conflicts. . . 10 5.2 Two columm typesetting

and index prologue . . . . 10

5.2.1 Classmemoir . . . 11 5.2.2 Packageshowidx . 12 5.2.3 Packagefancyhdr . 12 5.2.4 Packagecombine . 12 5.2.5 Packageledmac . . 12 5.3 Index layout customization 13 5.4 Index page customization 13 5.5 Index location cus-

tomization. . . 15 5.6 Using theshowidxpackage 15 5.7 Index List sectioning cus-

tomization. . . 15

6 Implementation 16


This package exploits the\write18facility of modern TEX system distri- butions that allows to run system commands while typesetting a document written with the LATEX mark up. By so doing, the index or indices, that are usually typeset at the very end of the document, are possibly split and sorted so as to include them in the document itself. This process has some minor limitations: it’s impossible to start an index before all other pages have been ejected and to have the automatic run of the index sorting program.

1 Introduction

This package wouldn’t exist without the essential contribution of Claudio Beccari, who withdrawn from authorship some years ago.

It’s been some years now that the typesetting engine of the TEX system is just pdftex; the original Knuthian tex is still corrected by D. E. Knuth himself, but is frozen, according to his will; it is still distributed by every TEX distribution, but in practice onlypdftex,xetex orluatex are used as the interpreter of every macro package and the true typesetter engine.

Version number v1.3e; last revision 2016/10/15.


This programpdftex was originally born with the facility of producing either a pdf output file, as its name suggests, or a dvi file. Since then it has been enriched with many upgrades, also with regard to the evolution of the PDF language itself.

It also incorporates the extensions ofε-TEX and has the ability to open a shell so as to call system commands with their arguments. The same is true forxetex and luatex.

This facility, since the TEX Live 2010 distribution, is official, but is sort of restricted, in the sense that the TEX system configuration file contains a list of

“safe” system commands that can be run bypdftex; presently the only program relevant for this package ismakeindex. This precaution is necessary in order to avoid running malicious code. Other programs can be run, though, but it’s necessary to expressly tellpdftex that it 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 themakeindex orxindy 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 restrictedwrite18 facility is enabled; if the TEX distribution in use does not enable this restricted fea- ture 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-shell-escape (or --enable-write18 for MiKTEX) to the command with which the typesetting program is launched, possibly through the shell editor. This applies to all threepdftex,xetex, andluatex typesetting engines.

If LuaLATEX is used andluatexis version 0.42 to 0.66, it’s impossible to distinguish whether the restricted shell escape is active or not, so the automatic procedure will be tried anyway, unless disabled with thenoautomaticpackage option. With version 0.68 or later, the behavior is the same as with the other engines. Note that, starting from version 1.3b of this package, the automatic call of MakeIndex is done throughos.executewhich might not work with older versions of LuaTEX. It has been tested with TEX Live from the 2012 release.

2 Package usage

This package is invoked as usual by means of a\usepackagecommand:


The availablehoptionsiconsist in a comma separated list of the following op- tions:

makeindex in order to use themakeindexsorting an formatting engine; this option is the default and is mutually exclusive with the next option.


xindy in order to use thexindy sorting and formatting engine;texindyis an alias forxindyand actually it’s the scripttexindywhich is called by this package.

Nevertheless if the realxindy is desired, in order to avoid the settings made up by texindy, so as to add xindy the command line specific settings, it is possible to specify the optiontruexindy; the user is then responsible to set up thexindy engine with the suitable command line options.

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.

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 article (except possibly for package documentations, which usually provide a macro index and a list of changes).

quiet suppresses all messages about manual index processing.

original uses the class-provided theindex environment for typesetting the in- dices; it is implicitly set if the document class option twocolumnhas been specified.

splitindex calls thesplitindexscript 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 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.

The last described option deserves an explanation. LATEX can write on a limited number of files during a run, and some of theseoutput streamsare 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 normallyimakeidx reserves an output stream for each index. So the splitindex option comes to rescue: with it only one raw index file is written.

At the first\printindex command, the programsplitindex is called; it splits the large index file into as many parts as the number of requested indices; after this, makeindex (orxindy) can do its job. In this way only one output stream is needed during the LATEX run.

When should you apply this option, then? With one index it’s useless, you should begin to consider it for two or more indices and definitely use it if you get the error

! No room for a new \write


Apart from this case, with or without it, the results are the same. See section 4 to see what files are written during the LATEX run with or without the option.

3 Specific package commands

As it is customary when just one index is produced, the standard LATEX facilities, i.e. the commands \makeindex, \index, and \printindex must be used. This package redefines them so as to produce multiple indices and defines some others.

The first three of the following commands may be used only in the preamble.

\makeindex with the syntax:


wherehkey-valuesiis a comma separated list of key-value assignments of the form:key=value; the available keys are the following:

name is the symbolic name for an index; if this key is not specified, it de- faults to the value of the\jobnamecontrol sequence, in other words the name of the current main .tex file, i.e., the file that \inputs and/or

\includes all the files of the complete document. This symbolic name is necessary only when doing multiple indices and is used with the\index command to point to the right index.


title is the title that is typeset at the beginning of the specific index; if not specified, the\indexnamevalue is used.

Example:title=Index of names.

program is the name of the system program that is used to sort and format an index; valid choices aremakeindex,xindy, ortexindy, plustruexindy. If not specified the program specified among the package options is used.

If no option is specified,makeindex is used. In order to usexindy, it’s necessary to call(pdf)latex with the shell escape command line option.


options is the list of options to be passed to the sorting and formatting pro- gram; this list is a balanced text of program options, separated with the syntax required by the sorting and formatting program. For ex- ample, in order to use a different makeindex sorting and formatting stylemystyle.ist and avoiding any message in the screen output, write options=-s mystyle.

noautomatic is a boolean key that defaults tofalse; you can set it totrueby simply listing its key in the key-value list, without necessarily specifying the=truepart. If specified the index sorting program won’t be called during the typesetting run for this particular index.

intoc is a boolean variable that defaults tofalse; if you want to set ittrue you must simply list this key in the key-value list, with no need of


specifying the=truepart. By setting this key totruean entry for this particular index is put in the table of contents.

columns accepts an integer representing the number of columns in the index;

this is silently ignored if the original or the twocolumn options are set; the number can even be1.


columnsep accepts a dimension representing the separation between index columns; the default is35pt as in the standard classes.


columnseprule is boolean; if it is set, a rule will appear between the index columns.

\indexsetup with the syntax:


where again hkey-valuesi is a comma separated list of key=value assign- ments; the available keys are:

level which takes as value a sectioning command such as \chapter or

\chapter*. Actually any command with an argument will do and will receive the index title as its argument. The default is\chapter*or, if the class doesn’t provide chapters,\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 theintocoption.

toclevel which takes as value a sectioning commandname such assection to indicate the level at which we want the indices appear in the table of contents.

noclearpage is a boolean option; when set, no \clearpage will be issued between indices. You might want to set it in order to have a ‘chapter of indices’; in this case you are responsible for setting the right value of the above keys. For example







See more on this subject in section5

firstpagestyle which takes as value a page style, default plain. You might want to set it toempty or some other page style defined by the class or by yourselves. This keyword is disabled when the package fancyhdr is loaded; any definition or choice of page styles must be done before typesetting the indices.


headers which takes two values: the left and right marks. You might want to use this for disabling automatic uppercasing, by 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 usefancyhdr.

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 \parskip.

\splitindexoptions must have as its argument the command line option to splitindex; this might be necessary on some systems. The default is -m "", because we want it only for splitting the large index file into its components which are later processed by this package.

\index with the syntax:


insertshentryiinto the raw index file(s); upon splitting it in different files, this particular entry is listed in the specific index file with namehnamei; if no name is specified, this hentryiis added to the default index with name

\jobname. Thehentryishould be written according to the particular syntax of the sorting and formatting program.

\indexprologue with the syntax:


is used to define some text to go between the index header and the entries;

thehspacingishould be a vertical space command such as \vspace{36pt}

(default is \bigskip), controlling the spacing between the prologue and the index proper. The command affects only the next index produced by

\printindexand is best placed just before this command. Please read ahead for further information on the use of tho command.

\printindex with the syntax:


is used to typeset the particular index named hnamei; if no optional ar- gument is specified, the default index with name \jobname.indis typeset.

Actually this command activates all the mechanism of closing the output to the raw index file, shelling out, possibly calling thesplitindexscript in order to divide the single raw file generated by the typesetting engine into dis- tinct raw files according to the default or specifiedhnameis for each index, calling the sorting and formatting program on each of these split raw files (unless inhibited by anoautomatic option; in which case a warning is issued in order to remember the typesetter that this particular index has not been processed), producing the sorted and formatted .ind files, and eventually inputs and typesets these formatted files. Deep breath.


Let’s see an example. The sequence of commands ...



\makeindex[title=Concept index]

\makeindex[name=persons,title=Index of names,columns=3]






... Einstein\index[persons]{Einstein, Albert}...


And this is the end of the story.


\indexprologue{\small In this index you’ll find only famous people’s names}



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 original option is set, maybe implicitly because of twocolumn,

\indexsetupand the keyscolumns,columnsepandcolumnseprulefor\makeindex have no effect. Please read more on this matter further on.

4 If something goes wrong

Sinceimakeidxrelies on good cooperation between package options and command line options for the LATEX run, in some cases it may happen that the indices are not correctly built or built at all.

If you use onlymakeindex and TEX Live 2010 or later, then you shouldn’t need anything special, sincemakeindex is among the safe programs allowed to be called during a LATEX run, be it latex, pdflatex, xelatex, or lualatex. When the options splitindex, xindy, texindy or truexindy are specified (globally or locally), the LATEX run should be called with the unrestricted -shell-escape (which is –enable-write18for MiKTEX) typesetting program option or thenoautomatic option should be specified when loadingimakeidx.

Let’s look at a couple of examples. In both we suppose that the document mybook.texdefines two indices through




where...denotes possible options excluding name.

First of all we examine the case whenimakeidx is calledwithout splitindex. Two files called mybook.idx and secondary.idx will be written during the LATEX run. At the corresponding \printindex command, makeindex will act on each of them producing the files mybook.ind, mybook.ilg, secondary.ind and secondary.ilg. The.indfiles contain the relevanttheindexenvironments with alphabetized entries, while in the.ilg filesmakeindex will write its log. You can check inmybook.logwhether the makeindex run has been executed by searching for a line

runsystem(makeindex <...>)...executed

where <...> stands for the rest of the command line in the particular case. If this line is not present, then makeindex has not been called; this happens when you didn’t specify the shell escape command line option for the LATEX run or the restricted shell escape is not active; also, of course, if you set the noautomatic option for the index.

When using splitindex, the situation is different. During the LATEX run, only a large index file called mybook.idx file gets written; the first \printindex command will call splitindex (unrestricted shell escape must be active), which will produce the two partial index files mybook-mybook.idx and mybook-secondary.idx. These two files will be processed bymakeindexproducing the four filesmybook-mybook.ind,mybook-mybook.ilg,mybook-secondary.ind andmybook-secondary.ilg. The line

runsystem(splitindex <...>)...executed

inmybook.logwill tell that the splitting has been done (see later on if this doesn’t seem true). In table1you can see what files are produced when the first two lines are in the preamble.

Everything is the same when using texindy for alphabetizing, except that, by default, it doesn’t write.ilgfiles. If you want them, addoptions=-thnamei.ilg to the relevant\makeindexcommand, in our example it should be

\makeindex[...,options=-t mybook.ilg]

\makeindex[name=secondary,...,options=-t secondary.ilg]

The name of the.ilgfilemust be specified. Remember, though, thatxindy .ilg files may turn out to be very large.

When something different from expected appears to take place, check also the time stamps of the produced files; if they are older thanmybook.log, it means that they have not been written in the last run. The most common case is that you forgot to activate the shell escape feature (which is not necessary with TEX Live 2010 or later, provided you use onlymakeindex).

Another cause of malfunction might be a wrong option passed to makeindex, texindy orsplitindex. For example, if you specify a style option formakeindex such asoptions=-s mystyle.istand the style file is missing or its name is mistyped, the run of makeindex will result in mybook.log, but it will be aborted and the




withoutsplitindex withsplitindex (at\begin{document})

mybook.idx mybook.idx secondary.idx


mybook.ind mybook-mybook.idx mybook.ilg mybook-secondary.idx secondary.ind mybook-mybook.ind secondary.ilg mybook-mybook.ilg

mybook-secondary.ind mybook-secondary.ilg Table 1: Files written during a LATEX run

TEX program has no control over this process. In this case the.ilgand.indfiles will not be produced and you can spot the problem by checking the time stamps.

On some systems a message such as Index file mystyle.ist not found

Usage: makeindex [-ilqrcgLT] [-s sty] [-o ind] [-t log] [-p num]

may appear on the screen, but often this window gets closed before you realize you have a problem. The time stamp is the best clue to detect such problems.

Shell hackers may be able to redirect the stderr stream to a file, but this requires skills that can’t be explained here, because they require tens of different tricks, depending on what method is used to start a LATEX run. From the command line, assumingbash, it would be something like

pdflatex -shell-escape mybook.tex 2>latex-errors

If shell hackers know a way to access the exit status of the called program, we’d be glad to implement a supplementary check.

5 Hints

Actually this package reaches two goals: (a) it typesets the indices of a specific document in just one run, and (b) it lets the author/typesetter produce documents with multiple indices.


5.1 Conflicts

5.2 Two columm typesetting and index prologue

As it has been already mentioned, it is possible to use the command\indexprologue to write some text before the index proper gets typeset; an optional space may be used in place of the default one-line spacing between the index title, the prologue and the index body.

This facility relies on a particular feature of themulticolsenvironment, that imakeidx uses to instruct the typesetting program to typeset the index with a specified number of balanced columns. The choice ofmulticolshas been made because it balances the columns in the last page; the declaration\twocolumdoes not perform the same way, and, if used, it makes\printindex typeset the index in two-column mode with an unbalanced last column.

In the previous sections it has been clearly stated that any configuration of the way imakeidx typesets the indices is bypassed if the option original has been specified either explicitly or implicitly. It is implicitly specified if the option twocolumnis specified in the class declaration statement. Why? Because if two column typesetting is desired for the whole document, it is not clear if the index has to be typeset in one column within each column of the document, or if it should be typeset in two column mode after a \onecolumn command is being issued; the results are not the same: with the former method the columns remain unbalanced, while the latter has balanced columns. Furthermore the\onecolum command forces a page break; without the\onecolumn command if the index is treated as a chapter, there is a page break, while if it is configured to be typeset as a section there is no forced page brake. With this plethora of combinations we decided to avoid any configuration of the index typesetting and left the decision to the user. This requires the user to practice some ingenuity in order to obtain what he expects.

First of all the user shall not specify thetwocolumn option to the class. Sec- ondly the user asks for the use of imakeidx and sets up the single or multiple

\makindexcommands. thirdly he loads all other packages required for his docu- ment; possibly he uses alsogeometryin order to specify a specific page layout. He shall specify the\twocolumn declaration after the above has been completed, in any case after the imakeidx package has been loaded and the single or multiple

\makeindexcommands are configured.

A good example might be this one:




\makeindex[title=Index of places,columns=1]












\indexprologue{This index lists all the residences where Lady Esther lived during the time span described in the book.}



In this way the index is typeset as a “section”, not as a “chapter”, in one column mode within the two column document style; the indicated prologue is typeset between the index title “Index of places” and the start of the index proper.

On the opposite the following code:



\makeindex[title=Index of places,columns=2]












\indexprologue{This index lists all the residences where Lady Esther lived during the time span described in the book.}



produces an index typeset as a “chapter”, starting on a new page; it is typeset in two balanced columns. The prologue is typeset where it should. The ingenious reader can experiment mixing the various settings used in these two examples in order to find out what benefits or disadvantages one can obtain with settings that are not physically impossible, but that may be aesthetically conflicting with one another.

5.2.1 Class memoir

The first public version of this package was not compatible with thememoirclass.

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, andnotwithmemoir’s; however the syntax used is the same and there should be no problem. There is an interaction betweenmemoirandshowidxthat required special attention. See below about using showidx.


5.2.2 Packageshowidx

Up to version 1.1 this package did not allow to use it together with theshowidx package; now it is, provided thatshowidxis loadedbeforeimakeidx. See below more information on usingshowidx.

5.2.3 Packagefancyhdr

When using package fancyhdrsome inconveniences did show up; now we believe we have detected the causes and we implemented the necessary corrections1.

5.2.4 Packagecombine

Apparently there might be some conflicts with packagecombine, because this pack- age redefines the contents of\jobname; we tried to control this behavior, and made the necessary patches, but it is still necessary to load this packageimakeidxbefore packagecombine.

5.2.5 Packageledmac

Some users reported some conflicts with package 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 packageetoolboxand its command\pretocmd; actually it is not necessary to loadetoolbox, because thisimakeidxprovides for it:
















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.

1Thanks to Mạeul Rouquette, who spotted the problems and also suggested some patches.


5.3 Index layout customization

If you redefine yourself thetheindexenvironment, please remember not to number the chapter or section that introduces the index if you ask for theintoc option;

either use the commands \chapter* or the \section*respectively and the in- tocoption or don’t use this option and redefine your theindexenvironment with numbered chapter or section commands, that will put the index titles directly into the table of contents. See below the effect of the\backmatter declaration.

You may use theidxlayoutpackage by Thomas Titz, which offers many functions for index typesetting customization and is compatible with our package; remem- ber to load idxlayoutafter imakeidx. This package has a similar function to our

\indexprologue, called \setindexprenote; howeveridxlayout doesn’t reset the index prologue, which must be declared anew or disabled with\noindexprenote before the next\printindexcommand. In any case take into serious consideration what is being said hereafter about customizations.

5.4 Index page customization

The same, more or less, holds true if you customize your headings;imakeidx can deal with standard settings, but it generally cannot deal with personal stylings and customizations. This is why if you load fancyhdr, some of the \indexsetup settings may be disabled.

When you make any kind of customization, remember that there are several classes, or personal settings, or features that may render your customization very difficult to handle. Typically:

• There are classes where the normal usable highest sectioning command, dis- regarding\part, is not\chapter, but\section; for example classesarticle, scrartcl.

• Sectioning commands come in two varieties: starred and unstarred; the for- mer 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 item.

• There are some classes (for example book, scrbook, menoir,. . . ) that have the special “sectioning” declarations \frontmatter, \mainmatter, and

\backmatter modify how the unstarred sectioning commands behave for what concerns the heading and the table of contents entries.

For what concerns indices, these are generally typeset at the document end.

This means that the\backmatterdeclaration may be in force; in this case unstarred sectioning commands are not numbered but they produce normal headings and table of contents entries.

• 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 \rightmark; these are the two commands that extract the correct part from the suitable marks. But when you use the headersoption value, you specify two brace balanced strings that are loaded through\markbothas the left and right part of the current mark.

• 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 strings that may be used in different ways by the selected page style and by the page style definitions of the macros\chaptermarks,\sectionmarks, and\subsectionmarksthat may interfere with personal customizations.

• Remember also that things change in an obvious way when one side typeset- ting is chosen; all pages are treated as if they were odd ones; therefore any customization must take into account also this aspect.

The above list has not been written down for discouraging customizations of any kind: simply it recalls what must 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 keysheadingsandfirstpagestylewhen packagefancydris being used; you may even set up these keys, but if thefancyhdr package has been loaded, we disable their action; this implies that any fancy customization must be done before starting to print any index.

Theintocoption must also be used with care, as well as the starred or unstarred sectioning commands for thelevel andtocleveloption values. They must be chosen according to what the possible\backmatterdeclaration sets up, in order to avoid double entries in the table of contents; the\backmattersettings 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, elimi- nate theintocoption from your calls; your class, packages, and settings are already taking care of it.

The packagetocbibindshould be loaded with thenoindex option, otherwise it would interfere with our redefinition of theindex.

If you redefine your theindexenvironment by means of other packages, pay attention that these redefine a realtheindex environment with this very name;

if they create an environment with a different name,imakeidx can’t take care of the indices production (in particular the TEX system programmakeindexcreates a sorted and formatted.indfile that refers explicitly to thetheindexenvironment), and it can’t take care of the table of contents entry and of the position of the hyper link anchors needed to navigate your document by means of hyper links.


5.5 Index location customization

Some packages might want to use the facilities of imakeidx to offer customized index commands, where the entry location is not expressed by a page number, but by an other reference value (for example: line number, entry number, etc.).

These packages may use the low-level command\imki@wrindexentry which takes three arguments:

1. The index name.

2. The entry.

3. The location number.

For example \imki@wrindexentry{names}{Charles}{26} adds to the index namesthe valueCharleswith the location reference26.

In simpler words, the new command\imki@wrindexentryis of interest mainly to package and class authors; it is not to be used by the “normal” user, who, on the opposite, if interested in referencing the index entries on some location counter different from the page one, is urged to refer to the classes and packages that implement this facility; eledmac should be one of these packages. Matter of fact this addition to the imakeidx package was contributed by Mạeul Roquette, the author and maintainer of eledmac, and we thank him very much,

5.6 Using the showidx package

If you want to make use of theshowidxfacilities, remember to load that package beforeimakeidx; remember also to disable or comment out the call toshowidxwhen you typeset the final version of your document. This constraint is due to the fact thatshowidx redefines several internal commands, some of which have to receive theimakeidx definition in order to perform as described in this documentation.

At the same time if the memoirclass is being used, remember that this class simulates theshowidxpackage and has its own commands to enable or disable the printing of the index entries into the margin of the document; the default setting is with the\hideindexmarkscommand in force; but if the user wants to write his index entries in the margin he has to issue the declaration\showindexmarksjust after begin document, in any case before the part of the source file(s) he wants to be marked with the index entries in the margin.

5.7 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 example, if you use a titled style for the index, where the index sections are distinguished with a bold face title or alphabetic letter, you have to set up a.istfile, such asmyindexstyle.ist, made up like this:

headings_flag 1


heading_prefix "\\par\\penalty-50\\textbf{"

heading_suffix "}\\\\\*\~\\\\\*"

symhead_positive "Symbols"

symhead_negative "symbols"

numhead_positive "Numbers"

numhead_negative "numbers"

delim_0 ",\~"

where the numeric and non alphabetic entries have different titles. But, say, you are making also an index where the entries are 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 such as

“Extensions”; therefore you have to prepare a different index style file, such as this one:

headings_flag 1

heading_prefix "\\par\\penalty-50\\textbf{"

heading_suffix "}\\\\\*\~\\\\\*"

symhead_positive "Extensions"

symhead_negative "extensions"

numhead_positive "Numbers"

numhead_negative "numbers"

delim_0 ",\~"

This done, besides requiring the use of this package, you have to declare the

\makeindex command with the necessary options; pay a particular attention to the options that involve the index symbolic name, the index title, the index style, the fact that the index 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. 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 with a consistent mark-up.

Define yourself appropriate macros so that, for example, personal names are con- sistently typeset, say, in caps and small caps and are entered into a specific index;

you may even create one command to typeset the name in the document and replicate the same name in the index.

Of course there is no program that can decide at your place what and where to index each piece of information; this is a task for humans. Soooooo. . .


6 Implementation

The heading to the file is in common with the documentation file, and has already been taken care of. But we require the xkeyval package, in order to handle the key-value lists.


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 stringimki@.


We define the various options and their defaults. After \ProcessOptions, we set anyway the original option if the document class has been given the twocolumnoption, which is incompatible withmulticol. 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 tosplitindex.









10 \imki@nonewpagetrue\imki@disableautomatictrue







17 \let\imki@finalmessage\@gobble

18 \let\imki@splitindexmessage\relax}}









27\ifluatex % luatex doesn’t have \(pdf)shellescape

28 \def\imki@engine{lualatex}

29 \ifnum\luatexversion<68

30 \chardef\imki@shellescape\@ne % no way to know the value

31 \else

32 \chardef\imki@shellescape\directlua{tex.write(os.execute())}

33 \def\imki@exec#1{\directlua{os.execute("\luaescapestring{#1}")}}

34 \fi


36\edef\imki@splitindexoptions{-m \string"\string"}

37\def\splitindexoptions#1{\g@addto@macro\imki@splitindexoptions{ #1}}


While experimenting we found out that some classes or packages are either incompatible with this one, or must be faked in order to pretend they have been



There is a serious incompatibility with thememoirclass. In factsmemoirputs all index entries in the main.auxfile and extracts them to the various raw index files at\end{document}time. This means that no raw index file output stream has been defined, and therefore this package can’t close it; moreover it can’t typeset the indices before\end{document}because they are not yet available. Therefore ifmemoiris the active class, we will hijack its index mechanism replacing it with ours.

On the opposite we pretend that packagemakeidxor packagemultindhave been loaded, so thathyperref can play with their commands, that are substantially the same as those used here. By so doing those packages are inhibited from being loaded after this one.

39\@namedef{[email protected]}{3000/12/31}


41 {\PackageError{imakeidx}{Incompatible package ‘multind’ loaded}

42 {This package is incompatible with multind, don’t load both.%

43 \MessageBreak\@ehc}}

44 {\@namedef{[email protected]}{3000/12/31}}

At the same time we redefine some commands defined by makeidx and we de- fine the default English names for the \see and \seealso commands. We use

\providecommandso that, if makeidxhas already been loaded, we do not redefine things that have already been defined.

45\providecommand*\see[2]{\emph{\seename} #1}

46\providecommand*\seealso[2]{\emph{\alsoname} #1}


48\providecommand*\alsoname{see also}

From here on, some commands are duplicated; this depends on the fact that the behavior must be different when usingsplitindexor not. The memory occupied by the useless commands will be cleared at the end of package.

49\providecommand*\makeindex{} % to use \renewcommand safely


51% \@onlypreamble\makeindex % Already in latex.ltx

This package implementation of\makeindexsets default values for the keys, then evaluates its argument (which is the optional argument to\makeindex) and calls two other macros. After that we have to reset the defaults.


53 \edef\imki@name{\jobname}%

54 \edef\imki@jobname{\jobname}%

55 \def\imki@title{\indexname}%

56 \edef\imki@program{\imki@progdefault}%

57 \let\imki@options\space

58 \KV@imki@noautomaticfalse\KV@imki@intocfalse

59 \setkeys{imki}{#1}%

60 \ifimki@splitindex\KV@imki@noautomaticfalse\fi

61 \imki@build\imki@name

62 \imki@startidx\imki@name


63 \imki@resetdefaults


Here are the keys. As usual, theimki@ prefix is used to distinguish anything that is being defined in this package, even the keys.




68 {makeindex,xindy,texindy,truexindy}{%

69 \ifcase\imki@nr\relax

70 \def\imki@program{makeindex}%

71 \or

72 \def\imki@program{texindy}%

73 \or

74 \def\imki@program{texindy}%

75 \or

76 \def\imki@program{xindy}%

77 \fi}

78\define@key{imki}{options}{\def\imki@options{ #1 }}







85 \def\imki@options{ }%

86 \def\imki@columns{2}\def\imki@columnsep{35\p@}%

87 \KV@imki@columnseprulefalse

88 \KV@imki@intocfalse\KV@imki@noautomaticfalse}


The control sequence\imki@builddefines a control sequence to hold the setup for an index to be used when the index is sorted and printed


91 \toks@{}%

92 \imki@dokey\imki@title

93 \imki@dokey\imki@program

94 \imki@dokey\imki@options

95 \imki@dokey\imki@columns

96 \imki@dokey\imki@columnsep

97 \ifKV@imki@noautomatic

98 \addto@hook\toks@{\KV@imki@noautomatictrue}%

99 \else

100 \addto@hook\toks@{\KV@imki@noautomaticfalse}%

101 \fi

102 \ifKV@imki@intoc

103 \addto@hook\toks@{\KV@imki@intoctrue}%

104 \else

105 \addto@hook\toks@{\KV@imki@intocfalse}%

106 \fi


107 \ifKV@imki@columnseprule

108 \addto@hook\toks@{\KV@imki@columnsepruletrue}%

109 \else

110 \addto@hook\toks@{\KV@imki@columnseprulefalse}%

111 \fi

112 \expandafter\edef\csname imki@set@#1\endcsname{\the\toks@}%


Comand \imki@dokey receives as argument the text of the values assigned to certain keys, and adds them to the options token list.


115 \expandafter\addto@hook\expandafter\toks@\expandafter{%

116 \expandafter\def\expandafter#1\expandafter{#1}}}

Command\imki@startidxdefines the output stream(s); the macro with suffix splitis used when splitindex is not enabled, the one with suffix unique is used otherwise. In the case of many indices, the symbolic name for an index named

‘pippo’ is\pippo@idxfilecorresponding to the filepippo.idx. When splitindex is enabled, the only output stream is called \@indexfile as in standard LATEX, corresponding to\jobname.idx.


118 \if@filesw

119 \def\index{\@bsphack

120 \@ifnextchar [{\@index}{\@index[\imki@jobname]}}

121 \expandafter\newwrite\csname #1@idxfile\endcsname

122 \immediate\openout \csname #1@idxfile\endcsname #1.idx\relax

123 \typeout{Writing index file #1.idx}%

124 \fi}

We define a switch which is set to true when a \makeindex command is given:

withsplitindexwe open only one stream.



127 \if@filesw

128 \ifimki@startedidx\else

129 \newwrite\@indexfile

130 \immediate\openout\@indexfile\[email protected]%

131 \global\imki@startedidxtrue

132 \fi

133 \def\index{\@bsphack

134 \@ifnextchar [{\@index}{\@index[\imki@jobname]}}

135 \expandafter\let\csname #1@idxfile\endcsname\@empty

136 \typeout{Started index file #1}%

137 \fi}

Provide a default definition for\index; when a\makeindexcommand is given and LATEX is writing on auxiliary files,\index will be redefined, as seen before.

When index files are written,\indexalways calls\@index. Some code is borrowed frommemoir.cls, but heavily modified. We want\@wrindexto be defined with two arguments, so that hyperref can hook into it just like it does with the similar commands defined by the old packagesmultindandindex.




140 \@ifundefined{#1@idxfile}%

141 {\PackageWarning{imakeidx}{Undefined index file ‘#1’}%

142 \begingroup

143 \@sanitize

144 \imki@nowrindex}%

145 {\edef\@idxfile{#1}%

146 \begingroup

147 \@sanitize

148 \@wrindex\@idxfile}}


Command\@wrindexmust be duplicated; we have to call it the same as usual in order to support hyperref. But the real name will be given at the end. We have to define a switch to allow the use of the 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 index 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 the control sequence is a primitive command, its value cannot be directly compared in the\ifxsense to the current macro represented by argument#1. Therefore we need a further helper control sequence\imki@jobnamethat contains the value assigned to\jobname. We must also take care of the case where the user wants to print the index entries in the margin while working on the document. This implies testing for the package showidxbeing already loaded; but this is not sufficient, because thememoirclass simulates theshowidxpackage and the test would result to be true even if the user did not load thet package, but uses thememoirclass. Therefore we use the same boolean used by memoir, testing in advance so as not defining it twice; then we use it to let theshowidxtrue or simulated macros do their job, but we also take care of resetting the switch default value to false at begin document time if the memoirclass is being used.




153 \ifshowindexmark

154 \@showidx{\ifdefequal{\imki@jobname}{#1}{}{[#1]\space}#2}%

155 \fi}


157 \expandafter\protected@write\csname#1@idxfile\endcsname{}%

158 {\string\indexentry{#2}{#3}}%



161 \protected@write\@indexfile{}%

162 {\string\indexentry[#1]{#2}{#3}}%






167 \@esphack%





172 \@esphack%

173 }

Compilation of the indices is disabled if -shell-escape has not been given or the restricted mode is not active; in this case we emit a warning. X E TEX has \shellescape instead of \pdfshellescape, so we take care of this (hop- ing that users or packages don’t define a \shellescape command). In any case we define an internal version of this command. In the case of luatex we can’t emit the proper messages if luatex is not version 0.68 or later. The conditional

\ifKV@imki@noautomaticis defined by \define@boolkeyabove.


175\ifdefined\imki@shellescape % luatex


177 \ifdefined\shellescape

178 \let\imki@shellescape\shellescape % xetex

179 \else

180 \let\imki@shellescape\pdfshellescape % pdftex

181 \fi



184 \let\KV@imki@noautomaticfalse\KV@imki@noautomatictrue

185 \KV@imki@noautomatictrue

186 \def\imki@shellwarn{\MessageBreak or call \imki@engine\space with

187 -shell-escape}


Do the same ifnoautomatic has been given as an option.


190 \let\KV@imki@noautomaticfalse\KV@imki@noautomatictrue

191 \KV@imki@noautomatictrue


Now we set up thetheindex environment. If theoriginal option is set, we simply patch the class definition in order to call the macro that does the work related to the table of contents. Otherwise we define a newtheindexenvironment, based on the standard, but using, if the number of columns is greater than one, the multicolsenvironment. Users needing a different setup can use the\indexsetup command.


194 \expandafter\def\expandafter\theindex\expandafter{\expandafter

195 \imki@maybeaddtotoc\theindex}


197 \global\let\imki@idxprologue\relax


198 \RequirePackage{multicol}

199 \renewenvironment{theindex}

200 {\imki@maybeaddtotoc

201 \imki@indexlevel{\indexname}\imki@indexheaders

202 \thispagestyle{\imki@firstpagestyle}%

203 \ifnum\imki@columns>\@ne

204 \columnsep \imki@columnsep

205 \ifx\imki@idxprologue\relax

206 \begin{multicols}{\imki@columns}

207 \else

208 \begin{multicols}{\imki@columns}[\imki@idxprologue]

209 \fi

210 \else

211 \imki@idxprologue

212 \fi

213 \global\let\imki@idxprologue\relax

214 \parindent\z@

215 \parskip\z@ \@plus .3\p@\relax

216 \columnseprule \ifKV@[email protected]\p@\else\z@\fi

217 \raggedright

218 \let\item\@idxitem

219 \imki@othercode}

220 {\ifnum\imki@columns>\@ne\end{multicols}\fi



The command\indexsetup may be used to customize some aspects of index formatting.


224 \@ifundefined{chapter}{\section}{\chapter}*}



227 \@ifundefined{chapter}{section}{chapter}}




231 \@mkboth{\MakeUppercase\indexname}{\MakeUppercase\indexname}}







238 \ifimki@original\else\setkeys{imkiindex}{#1}\fi}


The command\indexprologuesets the internal version which is always\let to\relaxduring\begin{theindex}.


241 \long\gdef\imki@idxprologue{{#2\par}#1}}


Now we provide the relevant\printindexmacros by transferring the real job to a secondary macro\imki@putindexafter due checks and messages.



244 \@ifundefined{#1@idxfile}{\imki@error{#1}}{\imki@putindex{#1}}}



247 \def\@tempa{#1}\def\@tempb{\imki@jobname}%

248 \ifx\@tempa\@tempb

249 \let\imki@optarg\@empty

250 \else

251 \def\imki@optarg{[#1]}%

252 \fi

253 \PackageError{imakeidx}

254 {Misplaced \protect\printindex\imki@optarg}

255 {You are not making this index, as no appropriate

256 \protect\makeindex\MessageBreak

257 command has been issued in the preamble.}}

We define a command to do a \cleardoublepage if the optionopenright is active (in classes where twoside is meaningful). In case \chapter is defined but not\if@openright, we assume that the class wants “open right”.


259 \@ifundefined{chapter}

260 {\clearpage} % article and similar classes

261 {\@ifundefined{if@openright}

262 {\cleardoublepage}

263 {\if@openright

264 \cleardoublepage

265 \else

266 \clearpage

267 \fi}

268 }}

We need a helper macro to do a check in order to avoid a loop and the hook where to insert the table of contents related stuff.



Two helper macros for preparing the final messages to the user.


272 \expandafter\edef\csname imki@message#1\endcsname

273 {\imki@program\imki@options#1.idx}

274 \AtEndDocument{\PackageWarning{imakeidx}{%

275 Remember to run \imki@engine\space again after calling\MessageBreak

276 ‘\@nameuse{imki@message#1}’\imki@shellwarn\@gobble}}}


278 \AtEndDocument{\PackageWarningNoLine{imakeidx}{%

279 Remember to run \imki@engine\space again after calling\MessageBreak

280 ‘splitindex’ and processing the indices\imki@shellwarn}}}


Here is a helper macro for deciding whether to call the external utility or to issue a final message. In \imki@makeindexnamewe put the name of the only program allowed by default (makeindex). If the list is updated, we can supplement the list here, maybe defining a list macro; for now this is sufficient. The temporary switch\if@tempswais set to true if automatic processing is possible, so that the main macro can take the appropriate action.



283 \@tempswafalse

284 \ifimki@splitindex % splitindex is not "safe"

285 \ifnum\imki@shellescape=\@ne\@tempswatrue\fi

286 \else

287 \ifx\imki@program\imki@makeindexname % nor is texindy

288 \ifnum\imki@shellescape=\tw@\@tempswatrue\fi

289 \fi

290 \ifnum\imki@shellescape=\@ne\@tempswatrue\fi

291 \fi

292 \ifKV@imki@noautomatic

293 \@tempswafalse

294 \fi}

We now define the main macro that puts the specified index file into the document and possibly orders to add the index title to the table of contents. It is duplicated as usual. The argument #1 is the specific symbolic name of the index. In par- ticular if theintoc option has been specified, the hook \imki@maybeaddtotoc is defined in such a way that the relevant information is added to thetocfile. The

\phantomsectioncommand is necessary when usinghyperref; here it is hidden as argument to\@nameuse, so it is equivalent to\relaxand does nothing ifhyperref has not been loaded.


296 \ifimki@nonewpage\else

297 \imki@clearpage

298 \ifimki@disableautomatic\else

299 \immediate\closeout\csname #1@idxfile\endcsname

300 \fi

301 \fi

302 \let\imki@indexname\indexname % keep \indexname

303 \@nameuse{imki@set@#1}\imki@decide

304 \if@tempswa % we can call the external program

305 \imki@exec{\imki@program\imki@options#1.idx}%

306 \else

307 \imki@finalmessage{#1}%

308 \fi

309 \ifKV@imki@intoc

310 \def\imki@maybeaddtotoc{\@nameuse{phantomsection}%

311 \addcontentsline{toc}{\imki@toclevel}{\imki@title}}%

312 \else

313 \def\imki@maybeaddtotoc{}%

314 \fi


315 \ifx\imki@title\imki@check@indexname\else

316 \def\indexname{\imki@title}%

317 \fi

318 \@input@{#1.ind}

319 \let\indexname\imki@indexname % restore \indexname





324 \ifimki@nonewpage\else

325 \imki@clearpage

326 \fi

327 \let\imki@indexname\indexname % keep \indexname

328 \@nameuse{imki@set@#1}\imki@decide

329 \if@tempswa % we can call the external program

330 \ifimki@splitdone\else

331 \ifimki@disableautomatic\else

332 \immediate\closeout\@indexfile

333 \fi

334 \imki@exec{splitindex \imki@splitindexoptions\space\[email protected]}%

335 \global\imki@splitdonetrue

336 \fi

337 \else

338 \ifimki@splitdone\else

339 \imki@splitindexmessage\global\imki@splitdonetrue

340 \fi

341 \fi

342 \if@tempswa % we can call the external program

343 \imki@exec{\imki@program\imki@options\imki@jobname-#1.idx}%

344 \fi

345 \ifKV@imki@intoc

346 \def\imki@maybeaddtotoc{\@nameuse{phantomsection}%

347 \addcontentsline{toc}{\imki@toclevel}{\imki@title}}%

348 \else

349 \def\imki@maybeaddtotoc{}%

350 \fi

351 \ifx\imki@title\imki@check@indexname\else

352 \def\indexname{\imki@title}%

353 \fi

354 \@input@{\imki@jobname-#1.ind}

355 \let\indexname\imki@indexname % restore \indexname


At this point, we choose the meaning of the relevant commands, reclaiming the space occupied by the discarded ones


358 \let\imki@startidx\imki@startidxunique

359 \let\@wrindex\imki@wrindexunique

360 \let\imki@putindex\imki@putindexunique

361 \let\imki@wrindexentry\imki@wrindexentryunique


362 \let\imki@startidxsplit\@undefined

363 \let\imki@wrindexsplit\@undefined

364 \let\imki@putindexsplit\@undefined


366 \let\imki@startidx\imki@startidxsplit

367 \let\@wrindex\imki@wrindexsplit

368 \let\imki@putindex\imki@putindexsplit

369 \let\imki@wrindexentry\imki@wrindexentrysplit

370 \let\imki@startidxunique\@undefined

371 \let\imki@wrindexunique\@undefined

372 \let\imki@putindexunique\@undefined


To end the code, we deal withmemoir:


375 \AtBeginDocument{\hideindexmarks}}{}

The end.

Change History


General: First public version . . . . 1 v1.0a

General: Small bug correction . . . 1 v1.1

General: Fixed compatibility with memoir . . . 1 Modified interaction with

LuaTEX . . . 1 v1.1a

General: Fixed bug with possibly defined\directlua . . . 1 Fixed bug with possibly defined

\directlua; now we leave the check toifluatex; using also ifxetexfor symmetry. . . 17 v1.2

General: added index processing engine option truexindy . . . 1 made package compatible with

fancyhdr . . . 1 made package compatible with

showidx . . . 1 v1.2c

General: Fixed regression . . . 1 v1.2d

General: Fixed bugs with index internal names . . . 1 v1.2e

General: Fixed bug with showidx simulated by memoir . . . 1 v1.3

General: Added internal so as to cooperate in a better way with eledmac (by Maieul Roquette . 1 v1.3b

General: Fixed untimely closing of the files with the ‘nonewpage’

option and the ‘noautomatic’

option . . . 1 LuaTeX 0.90 doesn’t support

\write18 . . . 1 v1.3c

General:xpatchis not loaded any more . . . 1, 17 v1.3d

General: No change, bumped

version number . . . 1 v1.3e

General: Don’t leave\shellescape defined . . . 1, 22


Related documents

The majority of private land in the MRA is peri-urban land located outside of rural villages.. The primary determinant of the market value of peri-urban lands is likely to

It is integral to reassessments, ozone layer protection, managing the environmental effects of activities in the ocean, considering new organisms and hazardous

In addition to its approval under the Local Government Act, Council may require certain dischargers, including those who wish to discharge liquid trade waste in large volumes

This Major Development Plan (MDP) outlines the proposed construction of a 4-4.5 star hotel of between 150 and 200 rooms with meeting/conference facilities located within the

The total ABC contribution to Australian screen drama, combined with approximately $125 million in external funding, delivered up to $244 million in production value to

traditionally been carried out by the Agency. Is consideration being given to outsource, contract-out or privatise in financial year 2021/22? If so, provide details. As part of

This is based on the revenue of economic activities in 14 marine industry sub-sectors, including water-based transport, domestic and international tourism, marinas

Sessional Com m ittee on the Environm ent 79.. A strong research and development effort, particularly into the integration of control methods, is essential to the

This activity will show you how computers sort random numbers into order using a thing called a sorting network?. Organise yourselves into groups

The Statement of Registrable Interests Form, the Notification of Alteration of Interests since Dissolution or date of election Form and the Explanatory Notes as provided to Members

Finally, the \printindex command is used in your L A TEX document to indicate where the file foo.idx should be inserted, i.e., where the index should appear in your document.. The

Actually this command activates all the mechanism of closing the output to the raw index file, shelling out, possibly calling the splitindex script in order to divide the single

• Additional High Conservation Value Vegetation (AHCVV) means areas of vegetation which were found during ground-truthing which would otherwise meet the definition of Existing

Vessel biofouling is a major pathway for the introduction of non-indigenous marine organisms into New Zealand territorial waters, some of which may be harmful

In my opinion the financial report gives a true and fair view of the financial position of the Surveyors Board of the Northern Territory of Australia as at 30 June 2016, and of

Benzene (ppb) change in annual max 1-hour (MDA1) ground level concentrations from Scenario 2 due to future industry (S3-S2) for a subset of the CAMx 1.33 km domain centred over

The processing of the 2007 claim for compensation under MRCA 8 The processing of a subsequent claim in 2010 under MRCA 8 The raising of debts in 2015 in relation to the

The PSG includes principles to guide engagement with participants, service standards and timeframes designed to improve the timeliness and quality of the National Disability

5.15 At the time of Mr C’s requests for access to the NDIS, the NDIA did not have any policy or guideline dealing specifically with incarcerated individuals and access to the NDIS.

existence. In making such an estimate, the Government Printer was requested to take as understood that each author body would have its report printed by the

disadvantage have special resonance for the Australian Aboriginal community, where the construct, the best interests of the child, has been applied and has resulted in an

Perhaps love in the context of professional relationships within the social work process is at the heart of a 21st century emancipation and liberation of Māori and other

The Swedish school authorities have drawn attention to this work and designated the school ‘the best school in Sweden working for equal value 2008’. Student empowerment, child’s