LaTeX Inverse PDF Search with Emacs

Latex is such a time hog that I’m always in search of ways to improve my efficiency. My editor of choice is emacs. I’ve tried other editors but it usually turns out that there is some “tail” feature that I can’t find in any other editor. By “tail” feature I mean a feature that is used either very rarely or by very few people.

I’ve tried LyX, which is described as a WYSIWYM (What You See Is What You Mean) editor. It’s actually quite brilliant, and I do use it for simple MS Word-style documents. I’d use it in conjunction with emacs, switching back and forth between LyX and LaTeX source code editing, if it were not for the fact that it messes up LaTeX source code big time (all source code formatting is lost, making it pretty unreadable).

So I stick to emacs. One of the problems with a non-WYSIWYG editor for a language like LaTeX is it is hard to spot what you’re looking at. If you’re looking at a PDF file, it’s really hard to find the tex code that corresponds to what you’re seeing in the PDF. This is where Inverse PDF Search comes in.

What inverse PDF search does is allow you to click on a location in the PDF file and be transported to the corresponding spot in the LaTeX source. I find this tremendously useful.

Under Ubuntu 10.04 “Lucid Lynx”, this works almost out of the box, with a little bit of work. Here are the steps.

1. First, install Okular, the KDE PDF viewer. This may require a huge number of KDE libraries. Evince is nice but doesn’t support inverse PDF search yet.
2. In okular, go to Settings > Configure Okular > Editor and change the editor to “emacs client”, and the command to “emacsclient -a emacs –no-wait +%l %f“.
3. Make sure you have Emacs 23. This is the default in Ubuntu 10.04.
4. We have to start emacs in server mode so that okular can talk to it. Add this line somewhere in your .emacs file: (server-start) The next time emacs is started, it will be in server mode.
5. When emacs compiles using latex, it has to include “source specials”. Roughly, this is an index connecting every position in the PDF file to a line number in the source file. To create the index, a latex package called synctex must be installed. Under Ubuntu 10.04 this is included in the package texlive-extra-utils, so make sure that’s installed.
6. To tell emacs to always use PDF (i.e. compile with pdflatex instead of latex) insert the line (add-hook ‘LaTeX-mode-hook ‘TeX-PDF-mode) into your .emacs.  This step is optional if you don’t want to automatically pick PDF each time, but everything in this post pertains to PDF.
7. Tell emacs to compile using source specials by adding the following line to your .emacs: ‘(LaTeX-command “latex -synctex=1”) Alternatively, when editing a tex file, go to the menu LaTeX > Customize AUCTeX > Extend this menu; then LaTeX > Customize AUCTeX > TeX Command > LaTeX Command, then change “latex” to “latex -synctex=1” and click “Save for future sessions”.
8. To tell emacs/AUCTeX to use okular rather than evince, add the following to .emacs: ‘(TeX-output-view-style ‘((“^pdf$” “.” “okular %s.pdf”))).  Alternatively, this can be done through the customization menu LaTeX > Customize AUCTeX > Extend this menu; then LaTeX > Customize AUCTeX > TeX Command > TeX Output View Style and change evince %o %(outpage) to okular %o %(outpage).  Click “Save for future sessions”.

When you restart emacs and use AUCTeX to compile under PDF (using C-c C-c), it should compile with source specials.  (You can manually compile with source specials using the command pdflatex -synctex=1 filename.tex at the command line, but it’s easier to use AUCTeX from emacs.) After compilation is done, the AUCTeX view command (also using C-c C-c) should start up okular. To use inverse search, Shift+Left Click on a position in the PDF file in okular. The cursor should jump to the corresponding line in emacs.

Note. It’s possible to omit step 7 and instead insert \usepackage{pdfsync} in the preamble of the TeX file.  This uses pdfsync, which is older than synctex.  But this has two drawbacks.  First, your LaTeX source file is now less portable (if you send it to someone without the pdfsync style file).  Second, the accuracy of the source specials generated using this method is atrocious: Shift+Left Click only places you in the general vicinity of the point you’re looking for, may be 15 or 20 lines above or below, and worst of all, is not even monotone (you click a later spot on the PDF, you might jump to an earlier spot in the source).  Using step 7 is much better.