List of Projects ESaaS Textbook Adding index entries to a LaTeX document

Adding index entries to a LaTeX document

Updated almost 6 years ago by Pete Boucher
We discovered at the last minute that there is a README.index file in the repo with Armando's instructions to indexers (not sure how we missed this).

LaTeX commands begin with a backslash followed by a keyword and optionally a block in curly braces: 
\title{LaTeX Indices}

So to add an item to the index for 'Cyclomatic Complexity' for example, you will need do put an index command into the text where this is mentioned:
\index{Cyclomatic Complexity}
If your reference text makes more sense under a sub-heading you add a '!' separator with the heading first:
\index{Design reviews!plan-and-document}
\index{Code reviews!plan-and-document}
TeX will add a this item followed by a comma and page number in the index at the end of the generated output:
Code reviews
    necessity, 335
    plan-and-document, 348 

We are working from a professionally produced index, so these index hierarchy decisions have been made already.

Figure and sidebar blocks

When an index item refers to a sidebar or figure we prefer to put the index command outside the figure block to avoid problems with 'make pdf':
\index{Adobe ActionScript|textit}
\begin{sidebar}[-1.25in]{}%
    \js, Microsoft JScript, and Adobe ActionScript are dialects of,
    the 1997 standard that codifies the language.  We
    follow standard usage and use ``\js'' to refer to the language
    generically.
  \end{sidebar}
Styling page numbers
Index items that refer to figures are usually styled with the page number in italics and items that refer tot tables with bold text. the '|texit' and 'textbf' keywords can be appended to an index entry using a pipe '|' as above.

A good reference on the LaTeX index command can be found in the open textbooks wiki.

Newlines in TeX source

Be careful about adding newlines to the source .tex file as these may be preserved into the compiled pdf. If you want to add an \index{} command on it's own line (to preserve the readability of the source) you can follow it with a % comment character:
\index{Pair Programming!GitHub pong|textbf}%
if in doubt, run 'make pdf' and compare your output to the original version 0.10.2 pdf textbook from the branch 'content/0.10.2'.

We're still working out a style guide that fits with our content, so use your best judgement for now on whether to insert index commands inline with the text or on a newline on their own. 
We now know that having every index entry on it's own line makes life a lot easier when merging the indexed source with updated content.
Try to be consistent in whatever you do so that others will be able to maintain the source later. Feel free to add comments explaining your styling decisions to the source of the chapter you're working on.

Special characters

Underscore _

Underscores are special characters in LaTeX and must be escaped when index tags contain Ruby method names such as 'alias_method_chain'. You can escape special characters with the backslash:
\index{alias\_method\_chain!decoration}%

Ampersand &

Our parser for the XML version of the handcrafted index does not convert the HTML entities used there to LaTeX  so watch out for generated entries like '\index{Façade pattern, DIP}' that have a special character that must be converted to its LaTeX equivalent:
\index{Fa\c{c}ade pattern, DIP} 

'make pdf' hangs with '?' prompt

A situation can arise where the 'make pdf' command hangs at a '?' prompt. To resolve this we've found that cancelling the make process in the terminal with shift-X and then running 'make cleanish' or 'make clean' will allow 'make pdf' to complete the next time you run it.
Entering 'H' at the '?' prompt may give useful information.
 
Also check that none of your index tags are nested within other LaTeX blocks, as above.

If 'make cleanish' does not work and you suspect that your last commit has caused 'make pdf' to fail, try the following procedure to undo your last commit:
git reset HEAD^
git stash
git reset --hard
make cleaninsh
make pdf
If 'make pdf' works now you can do 'git stash pop' to restore your suspect changes to the working directory and root out the offending LaTeX command. Otherwise you may be missing some LaTeX components on your system.
Revisions

comments powered by Disqus