## Wednesday, July 2, 2014

### 2014-07-02 LaTeX References, and how to control them

With just a little abuse:

"Which way did they go?
How many were there?
I must find my references;
For I am their master."

LaTeX references are wonderful things.  In this short epistle, we will explore some
 A sample page with reference problems.
of the interesting things that you can do with them, problems that can arise from misusing them, problems that can arise from not using them, and finally how to spice them up just a little.

First we will set up a conceptual model using based on the LaTeX file (Listing 1), the make file (Listing 2), and some auxiliary files that LaTeX creates.  Firstly, copy the LaTeX file and the make file to a convenient directory.  Create references.pdf from the command line, by executing make.  You want to get a sample PDF like in the image.  Now that we have something to look at, we can construct the conceptual model.

Opening the references.aux and searching for the lines that begin with the \newlabel token, and comparing that to the references.tex file shows that the label tbl:twice is declared twice.  It is first declared on page 3 and then again on page 4.  So, a major piece in our model, is that the label is actually a token used to find data associated with the token.  In effect, it is a key into a database of labels.  Using the label, you can get the sequential number of the type of object the label is associated with, the label's page number, and the title associated with the label.

It is but a little leap to realize that we are dealing with two related types of entities and that they can behave in many interesting ways.  The entities are the labels and how they are referred to (references). Just to keep things simple, well look at just the \label and \ref commands and see how they interact.

1. If a label is never declared and it isn't referenced then nothing happens.  This the nill case.
2. If a label is never declared and it is referenced then a LaTeX warning such as "Reference tbl:nonExistent' on page 1 undefined on input line 37" is recorded in the log file and ?? marks are written to the PDF.
3. If a label is declared once and it is referenced then this is the ideal case.  The appropriate sequential number will be written to the PDF.
4. If a label is declared more than once then a LaTeX warning such as "Label tbl:twice' multiply defined." is recorded in the log and the sequence number of the last declaration will be used in the PDF.  This condition could happen if a file is included more than once, or if label creation is not well disciplined, or if there is a typo.
5. If a label is declared and is never referenced, is this an error??  This could happen if all references to the label were lost during editing.

The references.tex file contains all these types of conditions.

How do we address these conditions?? Lets look at each individually:

 Sample page after refcheck processing.
1. Not an error, so nothing to do.
2. Examining the log file will show all the undeclared labels.  Now you have to root around in the tex files to see where the label should be.  Depending on how the tex files are linked, this can be easy or hard.
3. Not an error, so nothing to do.
4. Multiple label declarations can come from including the same LaTeX file more than once, so you'll have to figure when and how that could occur.  Also, the labels may have originated from different source files that were never meant to be in the same document, but now are.  Or it could be as simple as a typo.
5. This one is interesting in its own right, for a couple of reasons.  Firstly, how do you find unused labels, and then secondly what do you do about them.  Like so many other things in LaTeX, the secret is finding the right package.  Uncommenting the \usepackage{refcheck} line in references.tex will add reference related information into the log file and the PDF.  In the left margin of the PDF, each label will be printed where it is declared with declarations indicating whether or not the label is used.  Similar information is written to the log file.  Now, you can identify labels (for tables, sections, figures, equations, etc.) that were deserving of a label at one time, but now aren't referenced in the text.  If it is no longer of interest, you could ignore the condition, but it does raise the question about why the label is no longer necessary.  This is particularly true if a table or figure is not referenced anywhere in the document.  If it is no longer referenced, is there a reason for its existence in the current PDF??

By this point, we resolved all our label referencing.  We've got unique labels for all the things deserving of being labeled, and we're referencing all the labels using things like \ref or \pageref.  Lets spice things up a little bit.

Uncommenting:

%% \renewcommand{\MyRef}[1]{\vref{#1}}

will cause all occurrences of \MyRef to be replaced by \vref (part of the varioref package).  \ref returns the sequence number associated with the label, \vref does that and a little more.  \vref looks at where the reference is relative to the thing that is being referenced, and changes the text that it returns.  \vref returns:

1. Sequence number only - if label and reference are on the same page
2. Sequence number on the previous page - if the label is one page prior to the reference
3. Sequence number on the next page - if the label is one page after the reference
4. Sequence number on page number - if the label is more than one page away from the reference

Remake the sample LaTeX file and see how the table references change.
 Sample page after \vref processing.

Because \vref changes the text in the document, it is possible that LaTeX can get in a situation where the software can't figure out what to do.  So use \vref only near the very end of the editing and document creation process.  \vref is especially useful when your publisher requires that a table or figure be within 1.5 pages of the reference.

Now you are the master of your table, figure, and section references.  You know what they are conceptually used for, what types of logical conundrums can arise from when declaring and using references, and how to spice up the reference's readability.

And so we can say:
"I know which way they went.
I know how many there are.
I control my references;
For I am their master."

-- Chuck Cartledge