Text files and me - Part 3.5

I left a couple of things out of Part 3 of this series, so I’m going to shoehorn them in here. We’ll have a properly numbered episode next time.

What I forgot to include was an example of how I use the float type I created for photographs. If you recall, I defined a new float, called plate, which was stolen from based on the figure float of standard LaTeX. My idea was to have figures—charts, graphs, and drawings, all black-and-white—intermixed with the text, but have photographs collected at the end of my report so they could be printed on thicker photo paper.

Here’s a very brief sample report (using my dissociated Darwin snippet to generate the nonsense text). The line numbering doesn’t start at 1 because I’ve clipped out the preamble.

22:  \begin{document}
23:  \maketitle
24:  \pagedrop
25:  \thispagestyle{plain}
27:  \section{Introduction}
28:  \label{introduction}
30:  Have tried is easily done) into its proper place between two just-commenced cells, is important, when the same two species was rendered sterile All that we have no reason to suppose has nearly or quite aborted, far from presenting a strange fact, if no variations had ever occurred useful to man. and the amount of variation in one limited sense, as implying a modification directly due to the DIRECTLY opposite doctrine.
32:  Still lives; and many shells are dispersed, yet we can see why two areas, however distant and isolated regions, as they are at the Cape of Good Hope, is a marvellous one, by many naturalists under the designation of single or occasional year, otherwise, on the number of.
34:  \section{Description}
35:  \label{description}
37:  Ever so heavy, if the number of supposed CREATION. We cannot maintain that such occurred during floods, without any change in structure If we admit the smaller number; and certainly has produced, by analogous steps, after ten thousand feet; and clung to them so as to have become naturalised. But this is the case. is exactly the reverse. to man'appear only in the silk-worm are known and these.
39:  Can understand the relationship between the islands, and we may safely infer that the amount of difference than that between America and latterly in Australia, had not been sown or planted I was so extremely barren heath, which had never lived, but had been taken, and it had quite crawled out, with respect to the formation could not have formed an insuperable difficulty that.
41:  Cell adjoins two, three or more other cells. which, from having passed through the occasional preservation of the heartsease, rose, pelargonium, dahlia (\autoref{p20110408-001}), and other questions, hereafter to be dominant if it be thoroughly engrained.
43:  Each other, the closest competition with foreign associates, But according to the ova and are feebly developed, are nascent branchiae. Rudimentary organs may be compared with the countless generations of differences absolutely inappreciable by us; in our general view (\autoref{pp20110408-002}) will be much the more abnormal or unusual any character was when it occurs in the vertebrata. until beds rich in fossil species embedded in gravel or sand would not endure our climate. but which I am.
46:  \clearpage
48:  \begin{plate}
49:  \begin{center}
50:  \includegraphics[height=3.25in]{20110408-001.jpg}
51:  \caption{Beatles album glasses.}
52:  \label{p20110408-001}
53:  \end{center}
54:  \end{plate}
56:  \begin{plate}
57:  \begin{center}
58:  \begin{minipage}[c]{0.55\linewidth}
59:  \includegraphics[height=4.25in]{20110408-002.jpg}
60:  \end{minipage}\hfill
61:  \begin{minipage}[c]{0.40\linewidth}
62:  \caption{Beatles matryoshka.}
63:  \label{pp20110408-002}
64:  \end{minipage}
65:  \end{center}
66:  \end{plate}
68:  \end{document}

This generates two pages of text, Page 1

Sample report, page 1

and Page 2.

Sample report, page 2

Both photos are referenced in the body text using the \autoref command, which is part of the hyperref package. The advantage of \autoref is that it creates a PDF link (see the red boxes on Page 1) in the text when pdflatex is used to generate the output. The references are on Lines 41 and 43 of the source.

My convention for labeling plate references is to use the filename of the JPEG without its 'jpg extension but with a “p” prefix. For example, when I want to reference photo 20110408-001.jpg,1 I use a label of p20110408-001. You see this string in both the \autoref command in Line 41 and in the \label command in Line 52.

The photos themselves come after the \clearpage command in Line 46, which flushes out all the remaining body text and starts a new page. Landscape-oriented photos are included using the code shown in Lines 48-54. The code is pretty straightforward. The photo itself is added to the output via the \includegraphics command; the filename of the image is given in curly braces and the output size is given in the square brackets. I’ve found that a height of 3.25 inches works well for getting two photos on each photo page. The image, along with its caption and label are wrapped in an environment to center the image and then in the plate environment. Plates get their own numbering sequence preceded by the word “Plate,” as you can see on Page 2 of the output

Portrait-oriented photos are a little more tricky because I want the caption to be off to the side instead of under the photo—this saves space and allows me to put bigger photos on the page. Looking at Lines 56-66, you see that the \includegraphics command is roughly the same as before, but that it and the caption are wrapped in their own \minipage environments to get the side-by-side arrangement. The [c] arguments to \minipage center the caption and photo vertically; the {0.55\linewidth} and {0.40\linewidth} arguments give the photo and the caption 55% and 40% of the available width, respectively.

Obviously, I never typed all this crap by hand. When I was writing my reports in LaTeX directly, I’d just write the \autoref part. When the text was finished, I’d run a script that went through the file, looking for all the instances of the regex \\autoref{p([^}]+)}. It would then generate and fill in the boilerplate code, putting it right after the \clearpage command.2 All I had to do then was go through and type the captions. If I were writing in LaTeX today, I’d use a TextMate (or maybe TextExpander) snippet that inserted the template for me to fill in.

For historical accuracy, I should mention that when I first started using LaTeX, I wasn’t generating PDFs. I was using the normal latex command and making PostScript files via dvips. Back then, references in the text were done by \ref rather than \autoref because PostScript doesn’t have hyperlinking. It wasn’t until I returned to the Macintosh in 2005 that I switched from PostScript to PDF output. That’s when it seemed like a good idea to use \autoref to get internal links.

The move from PostScript to PDF was surprisingly smooth—just a few small changes to my style file and I was up and running. Another benefit of old, reliable software.

  1. I rename my photos with the date taken and a sequence number using my canonize script

  2. How did the script distinguish between portrait and landscape orientation? In the early days, my cameras weren’t smart enough to know their orientation, so I’d put a “cw” or “ccw” right after the “p” to let the script know that this was a portrait photo. Because the JPEG itself didn’t contain any orientation metadata, the LaTeX code for these photos would also have to be more complex than what I’ve shown here. The \includegraphics command would have to have an angle=90 (for ccw) or angle=-90 (for cw) argument in the square brackets.

    Later on, when my cameras got smarter and I was writing in Markdown, I’d use a portrait=yes attribute in the plate link at the bottom of the file. That’ll be a topic for Part 4.