Manufacturology

Automatically creating an index in LaTeX

When I wrote my doc­toral the­sis I decided that I wanted an index. I even­tu­ally man­aged to cre­ate one with the help of a Tcl script that I wrote. You can see the final result in the pic­ture below.

Exam­ple of index cre­ated with my script lixtcl.tcl.

Why write my own script?

Although I’d known for a long time that I wanted an index, I decided not to start with the index­ing until my text was fin­ished. Once I got work­ing on the actual index, I realised that the task of man­u­ally insert­ing \index tags would be over­whelm­ing. Some sort of auto­mated solu­tion was needed. I wanted to index all occur­rences of 350 words and phrases in about 100 pages of text.  After search­ing around for a while, I found some scripts and pro­grams to do the job, but none served my needs completely.

What I really would have wanted is a script that inte­grates with my edi­tor Texnic­cen­ter. But in the end I decided to write a Tcl script to do the job. I’m now mak­ing the script avail­able under the GPL license in the hope that other peo­ple may find it useful.

Please note that I only improved the script to the level that it served my pur­pose with a min­i­mum amount of pro­gram­ming work. If you make fur­ther improve­ments, please post the code back to me so that I can pub­lish an updated ver­sion here.

How to use the script

In order to use the script you must:

1. List the LaTeX files you want to index in a file called indexfiles.txt.
2. Pre­pare a file called indexwords.txt that con­tain all the words you want to include in the index.
3. Make sure you make back­ups of all your source files before you exe­cute the script.
4. Run the script.
5. Copy the indexed files from the out­put direc­tory to the orig­i­nal location.
6. Re–compile your LaTeX doc­u­ment with makein­dex enabled.

I’ll describe these steps in more detail below.

1. List­ing the files to index

Cre­ate a file named indexfiles.txt in the work­ing direc­tory. It should con­tain a list of all files to be indexed, like this:

Ch1_Intro.tex
Ch2_Steel_production.tex
Ch3_Strategy.tex
Ch4_Framework.tex
Ch5_Models.tex
Ch6_Results.tex
Ch7_Discussion.tex
App_Reheating.tex

2. List­ing the words to index

Then cre­ate another file called indexwords.txt. This is where you should list the words that you want to go into your index.

List one index entry per line.  Lixtcl.tcl sup­ports three dif­fer­ent types of entries:

Sim­ple entries, typ­i­cally a word or a phrase to include in the index.

Sub–entries, where an occur­rence of a com­pos­ite word is listed under a root entry.

Cross–references, where the occur­rence of an index entry refers to another entry with­out list­ing any page numbers.

Here’s an example:

backlog adjustment -> backlog!adjustment
desired backlog -> backlog!desired
realised strategy -> strategy!realised
charging rate
charging temperature
cluster
TPS | Toyota production system

3. Backup your files

Remem­ber to backup your LaTeX source files before run­ning the script. I can­not stress this enough! If you don’t, don’t blame me If some­thing goes wrong. Don’t blame me any­way by the way, there are no guarantees.

4. Run­ning the script

Note that I’m run­ning on Win­dows. If you use another OS, you may have to fig­ure out how to use the script your­self. It shouldn’t be any prob­lem though, the script is writ­ten in Tcl which is a cross plat­form script­ing language.

If you don’t already have Tcl installed, down­load and install ActiveTcl from Active State [here]. You may also want to con­sult the Tcl home page at www.tcl.tk.

Next, run the script. On win­dows, the best way is to do this from a com­mand prompt as shown in the pic­ture below. Run­ning the script may take a minute or two (I didn’t make any opti­mi­sa­tions, ok). You’ll see a mes­sage each time the script starts to process another file included in indexfiles.txt.

Run­ning the script from a com­mand prompt.

The script is fin­ished when con­trol is returned to the com­mand prompt.

5. Copy files

The orig­i­nal files should be unal­tered, and the result­ing indexed files should be found in a sub­di­rec­tory named ./out. Enter the out­put direc­tory and take a look to make sure that there is a copy of each file in there.

You can now copy the processed files from the out­put direc­tory to your orig­i­nal LaTeX project direc­tory. Keep your back­ups until you’ve seen that your project recom­piles as it should.

6. Recom­pile your LaTeX project

Recom­pile your project (with makein­dex). You will prob­a­bly have to do this sev­eral times due to how makein­dex works. Hope­fully every­thing com­piles as it should. You will then want to review your out­put DVI, PS or PDF, depend­ing on your con­fig­u­ra­tion, to make sure every­thing looks fine. If things worked as they should, you will now have an indexed document.

Clean­ing up your files

After you’ve exe­cuted the script, your files may be so clut­tered with \index entries that you find it dif­fi­cult to con­tinue to read and edit your doc­u­ment source. Instead of work­ing in the indexed files, I sug­gest that you clean out all \index entreis with the script lixtclean.tcl below.

Just like when you gen­er­ated the index, the cleaned up files will be cre­ated in the out­put direc­tory called ./out. I don’t need to remind you to make sure to keep a backup of all files, do I?

Down­loads

The source scripts are saved with a .txt file type since my server side secu­rity set­tings do not allow me to upload .tcl files. Down­load and change the file end­ing from .txt to .tcl.

• lixtcl.txt : The main script. Save as lixtcl.tcl.
• lixtclean.txt : The clean up script. Save as lixtclean.tcl.

Feed­back?

Did you try my script? Please use the com­ment field below and tell me how it went.

Be Socia­ble, Share!

•