Every so often there's something I want to do with LaTeX for which I can't find a solution in the usual sources.  This page is to record the answers to such problems for my own future reference and to help others who might be searching the Web for them.  You might also find my Postscript and PDF tricks page useful.

## Including files as verbatim

The problem:  I have a file of program code that I want to include in a LaTeX document as if it were typed inside a verbatim environment.  The solution:  the alltt environment, documented on page 187 of the LaTeX book, 2nd edition.  It's like verbatim but allows backslash commands to have their usual meaning, so you can use an \input command inside it.  There are many other, more complicated, ways to do similar things with more sophisticated features

## Random percent signs in bibliography entry URLs

Suppose you use the url package to put URLs into your bibliography entries.  If the URLs are long, BibTeX will add random % symbols to them because it doesn't realize that the url package will wrap those apparently-long lines.  So, according to the url package documentation, you insert whitespace to fool BibTeX. The whitespace is supposed to be ignored by the url package.  But if you're also using hyperref to create hyperlinks in a PDF file, the whitespace will *not* be ignored when it creates the URL to link to.  Click on the link, and your Web browser will attempt to go to a URL that contains the whitespace you inserted, and it will fail.  The solution is to escape the inserted whitespace with percent signs of your own, like this:

   note =        "ISBN 0-662-33122-2.  Online
{\url{http://www.pch.gc.ca/progs/ac-ca/progs/pda-cpb/pubs/%
protection/index_e.cfm}}",


I think doing this may break some rules for how the url package and/or BibTeX are supposed to work; but it works on my installation, and nothing else I tried did.

## Screwy vertical margins when you use hyperref

People hate the standard LaTeX margin-setting commands, but I honestly don't find them to be all that bad.  However, after carefully setting up my margins with the standard commands, I then loaded the hyperref package and found that everything got shifted about an inch downward on the page from where it was supposed to be.  I think I've also seen this happen with pdflatex regardless of hyperref, though I haven't been able to reliably duplicate that.

Note:  the Web is full of explanations of how pdflatex defaults to A4 paper and you have to set it to letter size if you want letter size.  That issue is often described as a "margin" problem even though it is not.  Paper size is not the problem I am describing here - my paper was already the right size - even though setting the paper size seems to be what all the "helpful" sources will tell you you're dealing with.

The actual solution:  use the geometry package instead of the standard commands to set your margins.  Merely loading the geometry package appears to also screw up the margins in the same way that hyperref does; you cannot easily set the margins with the standard commands and have it work when you're loading geometry.  At first I thought hyperref was loading geometry internally, explaining hyperref's misbehaviour, but it doesn't seem to do that and I haven't been able to figure out what it's actually doing.  What matters, though, is that if you abandon the standard margin commands and actually use the geometry package to set your margins, then hyperref will not screw them up.

## hyperref and ntheorem's \thref

If you use hyperref, you can't use \thref and have it work, and That's Just The Way It Is, at least with the current versions of hyperref and ntheorem.  I'm noting this because it isn't well-documented, and I spent a lot of trial and error on the attempt before I found documentation (in the hyperref changelog) saying that there's no way to do it.  However, see below about cleveref.

## Building LaTeX documents with GNU Make, including smart dependencies

It's tricky because LaTeX does a lot of things that screw up make - for instance, files like .aux depend on themselves.  You're supposed to run LaTeX once (to find all the things like bibliographic cites and index entries), then run BibTeX if you're using it, then run makeindex if you're using that, then run LaTeX (at least) twice more to resolve references.  The real dependencies that trigger these runs are hidden inside files that also get created in other passes, and it's generally a big mess.  Then you've also got to deal with things like graphics files that may be included in your document and also may have to be generated by other software.

At the moment I'm working on a multi-hundred-page doctoral thesis in computer science, and it uses dozens of figures which need to be automatically translated from .fig to .eps to .pdf before being included, plots generated by Gnuplot from .gp files, two bibliographic databases, a custom font, an index, and so on.  I started out with a manually-written Makefile that contained all the appropriate commands in the right order (the "thesis.pdf" rule included all three runs of pdflatex), but that got to be too much to maintain.  So here's a slightly simplified version of the Makefile I've switched to, which does automatic dependency tracking with the help of a Perl script.  (Also available as as a separate file for convenient downloading.)

default: all

TEXFILES=thesis.tex otherdoc.tex anotherdoc.tex

all: $(TEXFILES:.tex=.pdf) -include$(TEXFILES:.tex=.d)

%.pdf: %.p2
pdflatex -interaction nonstopmode $* %.pdf: %.p1 pdflatex -interaction nonstopmode$*

%.p2: %.p1
pdflatex -interaction nonstopmode $* touch$@

%.p1: %.tex
pdflatex -interaction nonstopmode $* ./mkltxdep$* < $*.log >$*.d
touch $@ %.bbl: %.p1 bibtex$*

%.ind: %.p1
makeindex $*.idx %.pdf: %.eps epstopdf$<

%.eps: %.fig
fig2dev -L eps $<$@

%.eps: %.gp
gnuplot \$<


How this works:  I'm creating extra files with the extensions .p1, .p2, and .d.  The .p1 ("pass one") file gets touched after the first run of pdflatex.  The .p2 ("pass two") file similarly gets touched after the second run - but the second run is supposed to happen after bibtex and makindex, if applicable, so we'll be adding extra dependencies to make it wait.  Those go in the .d file, which is created as a side effect in pass one.

The .d ("dependencies") file is generated by the mkltxdep utility I'll describe in more detail in a moment.  It includes rules saying that the .pdf file depends on either .p1 or .p2 depending on whether bibtex and/or makeindex will run (because we need a total of two passes without those, three passes with).  Also, the .p1 file depends on all the dependencies we can find in the .log file from pass one, the .p2 file depends on the bibliography and index if they're being used, the index depends on the bibliography (because you could conceivably put index markers in the bibliography, but probably not vice versa), and the bibliography depends on the .bib database file(s).  So for a file that requires both bibliography and index, you get the correct "pdflatex, bibtex, makeindex, pdflatex, pdflatex" sequence.

So pass one generates the dependencies and also depends on the dependencies.  This bit of self-reference is based on the technique described by Paul Smith and credited to Tom Tromey in this article.  The practical consequence is that the first time you run make, with no .d files, you don't get the full set of dependencies, but if you run make again, it should have the correct dependencies and re-build if appropriate.  Note the "-include" directive which causes make to silently skip over any dependency files it tries to include that don't exist.  LaTeX seems to be quite resilient to extra runs and overwriting failed runs with good data from new runs.  One little gotcha is that make's error handling doesn't necessarily work all that well with these rules; often if you re-run make after it has failed once, it will apparently succeed but not actually produce good output.  In that spirit, I've specified "nonstopmode" for all the pdflatex runs, so that a bad .tex file will cause TeX to just quit and let you debug it outside of Make, instead of hanging up waiting for user interaction.

A few other wrinkles:  I've included rules to convert .eps graphics to .pdf format so pdflatex can include them.  In actual use I have a hacked version of epstopdf that forces embedding of all fonts as described on my tips and tricks page.  Many of my .eps files actually come from .fig sources drawn with Xfig, so there's a fig2dev rule to generate those.  A few are generated by Gnuplot, so there's a rule for that as well.

Now, the mkltxdep utility (click to download it):  this works in conjunction with the \listfiles command, which should go in the preamble of every document that will be managed by this Makefile.  That command causes LaTeX to spit a list of most of the file's dependencies into the .log file, where mkltxdep can read it.  Unfortunately, the list includes a lot of things like LaTeX's own internal macro files, and fails to include the bibliography databases (.bib) files because those are, technically, read by BibTeX instead of by LaTeX. So the mkltxdep utility does a bit of hackish klugery to come up with a more reasonable list of dependencies.

In particular, see the %handling array at the start of the program.  File extensions with a zero value in that array (also the default for extensions not listed) will never be counted as dependencies.  File extensions with a one will be counted as dependencies if and only if they exist in the current directory - so for instance, I have a custom font-related file called mdbch.cfg, and that'll be counted, but my log file also names a file called color.cfg, which is internal to LaTeX, lives in some other directory somewhere else, and won't be counted.  File extensions with a two will always be counted as dependencies - this is used for .pdf file, which are probably graphics to be included and should be generated by the Makefile if they don't exist.

The utility also detects whether the document has a bibliography or an index, and generates additional dependencies to trigger creation of those and an additional pass of pdflatex if needed.  Finally, it scans the .aux file (because this information isn't in the .log file) to figure out the names of the .bib files, if there's to be a bibliography, and adds those as dependencies to the bibtex run.

If a framed theorem created by the "framed" option to ntheorem starts near the bottom of a page, it may be moved box and all to the next page.  In that case, the label for the theorem is declared on the previous page instead of the page that actually contains the theorem start, and so hypertext links to it will point at the wrong page.

My fix:  swap the order of the \theorem@prework and \refstepcounter{#2}% lines in the definition of \@thm, which are lines 782 and 783 in my copy of ntheorem.sty.  The label gets declared by \refstepcounter, so that should happen after the frame is opened by \theorem@prework.  In my case, I merge this patch into the "cleverer references" patch below.

As of 26 October 2007, I've reported this as a bug to the authors of ntheorem.  They declined to use my quick fix described above because \theorem@prework calls the user-visible hook \theoremprework, and moving it before the \refstepcounter call would break any existing code that depends on having the correct value in the counter during the callback.  However, some future version of ntheorem may fix the problem in some more complicated way (for instance, by having a different call guaranteed to happen before the number is assigned).  In my own document where this was an issue, I don't have anything that hooks to \theoremprework, so the correct-counter point isn't important.

## Real typewriter quotes, sffms, and hyperref

I've writing fiction using the sffms document class, and I want my manuscript to mimic standard typewriter output as closely as possible. That means using the "courier" option for Courier instead of Times font, and the "dumb" option for typewriter-style quotation marks (left and right both vertical instead of slanting in opposite directions from each other). However, even those settings don't really give typewriter-like output: in particular, the "dumb" option only affects double quotation marks, leaving left and right single quotation marks slanted and different from each other. I want them, and the apostrophe, to all be the same vertical mark, such as a real typewriter produces.

Solving this required digging into the sffms class and its associated packages fairly deeply, because sffms already overrides LaTeX's own quote handling in a complicated way and I wanted to override that. I ended up getting the behaviour I wanted for single quotes by adding these lines to the preamble of my document:

\def\rquote{{\fontencoding{TS1}\selectfont\char39}}
\def\lquote{{\fontencoding{TS1}\selectfont\char39}}


The sffms class loads a style file called sffdumb, which invokes the macros \rquote and \lquote for right and left single quotation marks. It defines those to be the  and ' characters in the current font, so we just redefine them to the typewriter quote/apostrophe character. There's a little more complication because in whatever the heck encoding sffms ends up using, that character isn't available; so it's necessary to switch to the TS1 encoding just to get access to the character, and then select it explicitly by number because it doesn't seem to be in the input encoding either.

When I tried to use hyperref to create PDF navigation, everything broke again. First of all, because hyperref and sffms do unsupported and conflicting things with LaTeX's label-definition mechanism, the document would fail to compile with a message about undefined "color link" macros. It appears that what's happening is hyperref defines those macros before it thinks it needs them, in the \begin{document}, but because sffms prints canned text of its own during \begin{document} before hyperref has finished initializing, it ends up making hyperref attempt to call its internals before those are defined (in particular, while printing the word count). This is probably why other document classes use a separate \maketitle command to print their title pages instead of doing it in the \begin{document}. Noting that I don't want my word count to be a coloured link anyway, I fixed this by defining the relevant macros to as nearly empty as seemed safe.

Then I then got garbage in the text part of the word count on my title page. I never did find a good pure-TeX way of fixing that for the automatic count; but since I'm generating my word count with an external utility and specifying it in a \wordcount command anyway, it wasn't a high priority to fix, and I just made the external utility remove the garbage.

Quotation marks were the next issue. Oddly, loading hyperref (even though hyperref should have nothing to do with quotation marks) caused left quotation marks, both single and double but only left and not right, to go back to their "smart" (non-typewriter) form. This one took a lot of debugging, but I eventually traced it to catcodes. The sffdumb.sty file makes the  (open quote) character active so it can call the macro that calls \lquote; and then hyperref does a lot of changing of catcodes, finally "restoring" them - to LaTeX's default values, not the overridden values from sffdumb. I simply made the character active again in my preamble and that seemed to fix the problem; though I'm not entirely confident it won't make something else break, because I don't understand what hyperref is trying to do with all those catcode changes anyway.

The stuff inserted in my preable, then, with fixes for both sffms's broken typewriter quotes and most of the incompatibilities between sffms and hyperref, looks like this:

\def\rquote{{\fontencoding{TS1}\selectfont\char39}}
\def\lquote{{\fontencoding{TS1}\selectfont\char39}}

\makeatletter
\catcode=\active\relax