LoweyPages - The Next Inevitable Step

Indexes

Introduction

Indexes are often found at the end of large documents. They have lists of words and the page or pages on which that word are used. LaTeX can help maintain this for you. It isn't intelligent enough to decide which words should be in the index for you, but it can maintain the page numbers for words you choose.

Getting Started

To start using indexes you first need to tell LaTeX that you plan on having an index. In the document pre-amble you will need to include the command

\usepackage{makeidx}

Then, again in the pre-amble, you need to have the command

\makeindex

As far as I can tell this command tells LaTeX to output the .idx file, which is used by the makeindex program, which I will explain in a moment. Once you have this command in place, you then need to enter the command

\printindex

This command actually puts the index into the document, so you should place this wherever you want the index to appear. I suggest putting it at the end of your document somewhere.

Once you've got these 3 commands into your document, you are ready to start building an index.

Running makeindex

In order to build the index in your document you must follow this procedure:

1. Run LaTeX
2. Run 'makeindex'
3. Run LaTeX
4. Re-run LaTeX if necessary to rebuild references.

e.g.

$ pdflatex myfile.tex $ makeindex myfile.idx $ pdflatex myfile.tex $ pdflatex myfile.tex

Indexing Words

You can tell LaTeX that you want something to appear in the index with the \index command. Say you have this text:

\section{Introduction} This document is about cars. The end.

In the index you might decide that you want "cars" to link to this particular piece of text. So you would change the text to:

\section{Introduction} This document is about cars. \index{Cars} The end.

In the end index page you will see

Cars, 1

Sub-Indexing

As if indexing isn't enough, you can also create sub-indexes. Perhaps you extend the above text to:

\section{Introduction} This document is about cars. \index{Cars} Cars come in many models such as Audi, Bentley and Citreon. The end.

And you decide that you want Audi, Bentley and Citreon to appear as sub-indexes of "Cars", then you can use \index{index!subindex!subsubindex} to create suitable sub-indexes:

\section{Introduction} This document is about cars. \index{Cars} Cars come in many models such as Audi,\index{Cars!Audi} Bentley\index{Cars!Bentley} and Citreon.\index{Cars!Citreon} The end.

The output will be along the lines of:

Cars, 1
Audi, 1
Bentley, 1
Citreon, 1

Deciding What To Index

The index of a document should, really, be created AFTER you have written the document. This is no simple task. Remember that people who use the index will be using it to find references to something that is of interest to them.

A good starting point is to use a list of the most commonly-used words in your document (with any filler words etc removed). You can do this with my imaginatively named Perl script: "wordcounter". The best way to do this is to use either ps2ascii or pdftotext on the output file you created (I always create PDF files, so I use pdftotext to convert the file to text). Then redirect the outputted file into word_counter.pl:

$ pdflatex myfile.tex $ pdftotext myfile.pdf $ word_counter.pl cars 2 document 1 models 1 audi 1 bentley 1 citroen 1 end 1 $

From this list it should be possible to find the important words in your document. With a short document like this it doesn't work too well, but in a large document it should be much better. The next problem is finding the correct places to insert the \index commands:

Grep is Your Friend

Say you need to find all 23 instances of the word "Updating" in a 20,000 word document spread across 20 chapters where each chapter is in its own .tex file. Nightmare, right? Enter, stage left, Grep:

grep [options] PATTERN [FILE...]

Grep can find a given search string in any number of files. Typing

$ grep "Updating" *.tex

will display the contents of all files containing the word "Updating". But, that's messy. What if all 20 chapters contain the word? Then you're no better off than before you started. Luckily grep comes with some handy options.

-A NUM, --after-context=NUM Print NUM lines of trailing context after matching lines. Places a line containing -- between contiguous groups of matches. -B NUM, --before-context=NUM Print NUM lines of leading context before matching lines. Places a line containing -- between contiguous groups of matches. -C NUM, --context=NUM Print NUM lines of output context. Places a line containing -- between contiguous groups of matches. --colour[=WHEN], --color[=WHEN] Surround the matching string with the marker find in GREP_COLOR environment variable. WHEN may be `never', `always', or `auto' -c, --count Suppress normal output; instead print a count of matching lines for each input file. With the -v, --invert-match option (see below), count non-matching lines. -i, --ignore-case Ignore case distinctions in both the PATTERN and the input files.

-l Suppress normal output; instead print the name of each input file from which output would normally have been printed. The scanning will stop on the first match.

It does a lot more too, but that should be enough to get you started and give you enough power to do what you need. Using the above options it would be possible to do something like:

$ grep -c -i "updating" *.tex

file1.tex:3 file2.tex:2 file3.tex:5 file4.tex:0 file5.tex:5 file6.tex:1 ... ...

Then it's just a case of using your editor to change the relevant files.

Last updated 14th of March 2005 at 00:25

For web design go to Shoestring Websites!

LoweyPages - The Next Inevitable Step
Indexes Introduction Indexes are often found at the end of large documents. They have lists of words and the page or pages on which that word are used. LaTeX can help maintain this for you. It isn't intelligent enough to decide which words should be in the index for you, but it can maintain the page numbers for words you choose. Getting Started To start using indexes you first need to tell LaTeX that you plan on having an index. In the document pre-amble you will need to include the command `\usepackage{makeidx}` Then, again in the pre-amble, you need to have the command `\makeindex` As far as I can tell this command tells LaTeX to output the .idx file, which is used by the makeindex program, which I will explain in a moment. Once you have this command in place, you then need to enter the command `\printindex` This command actually puts the index into the document, so you should place this wherever you want the index to appear. I suggest putting it at the end of your document somewhere. Once you've got these 3 commands into your document, you are ready to start building an index. Running makeindex In order to build the index in your document you must follow this procedure: 1. Run LaTeX 2. Run 'makeindex' 3. Run LaTeX 4. Re-run LaTeX if necessary to rebuild references. e.g. `$ pdflatex myfile.tex $ makeindex myfile.idx $ pdflatex myfile.tex $ pdflatex myfile.tex` Indexing Words You can tell LaTeX that you want something to appear in the index with the \index command. Say you have this text: `\section{Introduction} This document is about cars. The end.` In the index you might decide that you want "cars" to link to this particular piece of text. So you would change the text to: `\section{Introduction} This document is about cars. \index{Cars} The end.` In the end index page you will see Cars, 1 Sub-Indexing As if indexing isn't enough, you can also create sub-indexes. Perhaps you extend the above text to: `\section{Introduction} This document is about cars. \index{Cars} Cars come in many models such as Audi, Bentley and Citreon. The end.` And you decide that you want Audi, Bentley and Citreon to appear as sub-indexes of "Cars", then you can use \index{index!subindex!subsubindex} to create suitable sub-indexes: `\section{Introduction} This document is about cars. \index{Cars} Cars come in many models such as Audi,\index{Cars!Audi} Bentley\index{Cars!Bentley} and Citreon.\index{Cars!Citreon} The end.` The output will be along the lines of: Cars, 1 Audi, 1 Bentley, 1 Citreon, 1 Deciding What To Index The index of a document should, really, be created AFTER you have written the document. This is no simple task. Remember that people who use the index will be using it to find references to something that is of interest to them. A good starting point is to use a list of the most commonly-used words in your document (with any filler words etc removed). You can do this with my imaginatively named Perl script: "wordcounter". The best way to do this is to use either ps2ascii or pdftotext on the output file you created (I always create PDF files, so I use pdftotext to convert the file to text). Then redirect the outputted file into word_counter.pl: `$ pdflatex myfile.tex $ pdftotext myfile.pdf $ word_counter.pl cars 2 document 1 models 1 audi 1 bentley 1 citroen 1 end 1 $` From this list it should be possible to find the important words in your document. With a short document like this it doesn't work too well, but in a large document it should be much better. The next problem is finding the correct places to insert the \index commands: Grep is Your Friend Say you need to find all 23 instances of the word "Updating" in a 20,000 word document spread across 20 chapters where each chapter is in its own .tex file. Nightmare, right? Enter, stage left, Grep: `grep [options] PATTERN [FILE...]` Grep can find a given search string in any number of files. Typing `$ grep "Updating" .tex` will display the contents of all files containing the word "Updating". But, that's messy. What if all 20 chapters contain the word? Then you're no better off than before you started. Luckily grep comes with some handy options. -A NUM, --after-context=NUM Print NUM lines of trailing context after matching lines. Places a line containing -- between contiguous groups of matches. -B NUM, --before-context=NUM Print NUM lines of leading context before matching lines. Places a line containing -- between contiguous groups of matches. -C NUM, --context=NUM Print NUM lines of output context. Places a line containing -- between contiguous groups of matches. --colour[=WHEN], --color[=WHEN] Surround the matching string with the marker find in GREP_COLOR environment variable. WHEN may be `never', `always', or `auto' -c, --count Suppress normal output; instead print a count of matching lines for each input file. With the -v, --invert-match option (see below), count non-matching lines. -i, --ignore-case Ignore case distinctions in both the PATTERN and the input files. `-l Suppress normal output; instead print the name of each input file from which output would normally have been printed. The scanning will stop on the first match.` It does a lot more too, but that should be enough to get you started and give you enough power to do what you need. Using the above options it would be possible to do something like: `$ grep -c -i "updating" .tex` `file1.tex:3 file2.tex:2 file3.tex:5 file4.tex:0 file5.tex:5 file6.tex:1 ... ...` Then it's just a case of using your editor to change the relevant files. Last updated 14th of March 2005 at 00:25 For web design go to Shoestring Websites!	\| Home \| --- \| Blog \| \| Serious \| \| Software \| \| Linux \| \| Humour \| \| Tunes \| --- \| Disclaimer \|