When I wrote my doctoral thesis I decided that I wanted an index. I eventually managed to create one with the help of a Tcl script that I wrote. You can see the final result in the picture below.
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 indexing until my text was finished. Once I got working on the actual index, I realised that the task of manually inserting \index tags would be overwhelming. Some sort of automated solution was needed. I wanted to index all occurrences of 350 words and phrases in about 100 pages of text. After searching around for a while, I found some scripts and programs to do the job, but none served my needs completely.
What I really would have wanted is a script that integrates with my editor Texniccenter. But in the end I decided to write a Tcl script to do the job. I’m now making the script available under the GPL license in the hope that other people may find it useful.
Please note that I only improved the script to the level that it served my purpose with a minimum amount of programming work. If you make further improvements, please post the code back to me so that I can publish an updated version here.
How to use the script
In order to use the script you must:
- List the LaTeX files you want to index in a file called indexfiles.txt.
- Prepare a file called indexwords.txt that contain all the words you want to include in the index.
- Make sure you make backups of all your source files before you execute the script.
- Run the script.
- Copy the indexed files from the output directory to the original location.
- Re–compile your LaTeX document with makeindex enabled.
I’ll describe these steps in more detail below.
1. Listing the files to index
Create a file named indexfiles.txt in the working directory. It should contain 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. Listing the words to index
Then create 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 supports three different types of entries:
Simple entries, typically a word or a phrase to include in the index.
Sub–entries, where an occurrence of a composite word is listed under a root entry.
Cross–references, where the occurrence of an index entry refers to another entry without listing 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
Remember to backup your LaTeX source files before running the script. I cannot stress this enough! If you don’t, don’t blame me If something goes wrong. Don’t blame me anyway by the way, there are no guarantees.
4. Running the script
Note that I’m running on Windows. If you use another OS, you may have to figure out how to use the script yourself. It shouldn’t be any problem though, the script is written in Tcl which is a cross platform scripting language.
Next, run the script. On windows, the best way is to do this from a command prompt as shown in the picture below. Running the script may take a minute or two (I didn’t make any optimisations, ok). You’ll see a message each time the script starts to process another file included in indexfiles.txt.
The script is finished when control is returned to the command prompt.
5. Copy files
The original files should be unaltered, and the resulting indexed files should be found in a subdirectory named ./out. Enter the output directory 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 output directory to your original LaTeX project directory. Keep your backups until you’ve seen that your project recompiles as it should.
6. Recompile your LaTeX project
Recompile your project (with makeindex). You will probably have to do this several times due to how makeindex works. Hopefully everything compiles as it should. You will then want to review your output DVI, PS or PDF, depending on your configuration, to make sure everything looks fine. If things worked as they should, you will now have an indexed document.
Cleaning up your files
After you’ve executed the script, your files may be so cluttered with \index entries that you find it difficult to continue to read and edit your document source. Instead of working in the indexed files, I suggest that you clean out all \index entreis with the script lixtclean.tcl below.
Just like when you generated the index, the cleaned up files will be created in the output directory called ./out. I don’t need to remind you to make sure to keep a backup of all files, do I?
The source scripts are saved with a .txt file type since my server side security settings do not allow me to upload .tcl files. Download and change the file ending from .txt to .tcl.
- lixtcl.txt : The main script. Save as lixtcl.tcl.
- lixtclean.txt : The clean up script. Save as lixtclean.tcl.
Did you try my script? Please use the comment field below and tell me how it went.