LaTeX hyperref and emulateapj

Jonathan Foster is a YCAA Prize Fellow at Yale University. He studies how stars form, both through large-scale surveys of the galaxy and in detailed studies of nearby regions. He is also interested in how visualizations of large astronomy datasets can aid discovery.

If you want your paper on the arxiv/astro-ph to be read by everyone, it’s worth your time to use emulateapj to format it. The emulateapj version will be shorter, look nicer, and have figures closer to the relevant part of the text.

You can improve the experience of reading your article on the screen by adding hyperlinks in the article with the hyperref package, which is probably already part of your LaTeX distribution. The basic idea of hyperref is to include links inside your document, so that a reader can quickly jump to a reference or to a figure/table/equation/section within the paper. I hope you’re already using

\ref{sec:mysec}

commands and labels to let LaTeX automatically take care of referencing your figures and tables. If you aren’t, you should do so; hyperref is useless without such links.

With the settings I show here, your paper will look like the example below, where all the colored text is active links. As a bonus, you get nice formatting and active links to any web links that appear in your article simply by wrapping them in

\url{http:www.mylink.com}

You can see how it all works in this example paper.

emulateapj1

To use hyperref (with the options I show here), just put this line in your document header.

\usepackage[backref,breaklinks,colorlinks,citecolor=blue]{hyperref}

Unfortunately, there are a few extra hoops to jump through to get everything working perfectly. The major problem you will notice is that the hyperref package links to the captions of figures. This isn’t useful. If you click on a link to Figure 7 you want to see Figure 7, not just the caption. You want clicking on the link to give you this:

emulateapj2

and not this (which is what hyperref gives you by default):

emulateapj3

There are at least two options to deal with this problem. The caption package and the hypcap package. Unfortunately, neither works right out of the box with emulateapj! The caption package throws an error because both it and emulateapj are redefining the longtable environment. The hypcap package fails to work because the deluxetable environment (which makes nice tables) does not actually have a caption associated with the table. There is an easy workaround for hypcap though. Just add this to your document header

\usepackage[all]{hypcap}

and wrap your deluxetables (and any other environment that causes problems) with

\capstartfalse
\begin{deluxetable}\end{deluxetable}
\capstarttrue

Now your links from the text to Figures/Tables go the right place.

What about getting back? Typically if you’re reading and want to reference a figure on another page, you’ll immediately want to go back to where you were reading. This isn’t something that hyperref enables, but your PDF browser might support this. There are “back”/”forward” actions/buttons in many PDF readers. See this discussion for information about your viewer. On a Mac, the command is cmd-[ (left square bracked) in Preview and cmd-left-arrow in Adobe Reader. Unfortunately, many of the PDF-viewers built into web browsers don’t support this.

Now everything works and you can tweak to make things look they way you like. I like the following options:

\usepackage[backref,breaklinks,colorlinks,citecolor=blue]{hyperref}        
\usepackage[all]{hypcap}
\renewcommand*{\backref}[1]{[#1]}

Note that you have to load hypcap after hyperref. The backref option and the extra

\renewcommand

combine to give you nicely-formatted links back from references back into your article like so:

emulateapj4

Unfortunately these links go back to the section in which the reference is cited, not directly to the citation. This can be a little annoying if you have long sections in your article, but it’s not so bad.

One final tweak is nice. I typically reference a figure with LaTeX that looks like this:

see Figure~\ref{fig:myfig}

With hyperref, this will make the figure number a clickable link, but not the word “Figure”. The easy fix is to replace all your

\ref

commands with the hyperref command

\autoref

and remove your hand-typed “Figure”/”Table”/etc. This step is more work, since it involves some find-and-replace.

In conclusion:

  1. Add the following lines to the top of your document
    \usepackage[backref,breaklinks,colorlinks,citecolor=blue]{hyperref} 
    \usepackage[all]{hypcap} %Links go to figures;breaks on deluxetables       
    \renewcommand*{\backref}[1]{[#1]}
  2. Wrap any float environments that break hypcap (like deluxetable) in
    \capstartfalse 
    \capstarttrue
  3. Wrap any external urls in
    \url
  4. (Optional) Replace all your
    Something~\ref{}

    commands with

    \autoref{}
  5. Remember that your PDF browser might have a back button to make using these links much nicer.
9 comments… add one
  • Nathan Goldbaum Sep 29, 2014 @ 13:20

    Wow, LaTeX mastery. Thanks for the tips!

    • Jonathan Foster Oct 2, 2014 @ 19:45

      You’re welcome. And just so everything is in one place:

      Sometimes you need to refer to Figure 1b, where the sub-panels of the figure aren’t separate logical entities. If you just use \autoref, the “b” part won’t be part of the link. So you have to do it manually, like this:

      \hyperref[fig:myfig]{Figure~\ref*{fig:myfig}b}

    • Leo Fang Feb 3, 2015 @ 14:57

      @ Jonathan, thanks a lot! Precisely what I am looking for!

  • Chris Ramos Oct 7, 2014 @ 17:16

    Thanks for the great tips. Backref is a super cool option.

  • Jonathan Gagné Oct 12, 2014 @ 5:31

    This post was extremely useful, thanks !

    Small note : I did not like the fact that \autoref does not capitalize the first letter in “Figure” or “Section”, etc.; I found a workaround by doing :

    \hyperref[fig:myfig]{Figure~\ref*{fig:myfig}}

    instead of

    \autoref{fig:myfig}

    The same goes with sections ;

    \hyperref[sec:mysec]{Section~\ref*{sec:mysec}}

    • Max Katz Jul 28, 2015 @ 17:13

      I had the same reaction to this. A workaround I found was to follow the advice found here: https://en.wikibooks.org/wiki/LaTeX/Labels_and_Cross-referencing#autoref

      Specifically, I added this to the preamble:

      % Override choices in \autoref
      \def\sectionautorefname{Section}
      \def\subsectionautorefname{Section}
      \def\subsubsectionautorefname{Section}

      My installation of hyperref already capitalized Figure in autoref’s, but you could do \def\figureautorefname for that too.

  • Cristóbal Sifón Oct 23, 2014 @ 5:54

    I second Jonathan. In trying to solve this, I came across cleveref which is a much improved version of autoref. Basically, options are:

    \usepackage{cleveref}
    \cref{fig1}
    will show “figure 1”, all linked to the figure (this is always true)

    \usepackage{cleveref}
    \Cref{fig1}
    will show “Figure 1”

    \usepackage[capitalize]{cleveref}
    \cref{fig1}
    will show “Figure 1”.

    also, something like \Cref{fig1,fig3,fig5,fig4} will render “Figures 1 and 3 to 5” with all numbers and the word Figure linked.

    Be sure to check it out, http://www.ctan.org/pkg/cleveref

  • Matt Giguere Nov 18, 2014 @ 18:09

    Great post, thanks! When I implemented autoref I encountered a problem with table numbers. Clicking on references to Tables worked fine (and brought me to the relevant table), but every table number in the document was to Table 1. If anyone else has similar issues, commenting out the \tabelnum{} commands solved this problem for me.

  • Rob Rutten Mar 6, 2015 @ 9:06

    Hi hyperreffers. In my pdf’s I make clicking on an in-text citation not jump to the reference list entry but instead open a browser and in that open the ADS abstract page for that paper. So that a reader can read that abstract (or full ADS-downloaded paper) side-by-side with your paper on her/his screen. A&A recommends this practice, but I am not sure whether it survives IOP processing for ApJ.

    A more recent trick is to have popups for any acronym giving its meaning when moused over. This isn’t robust yet and many pdf readers don’t support it (acroread does, evince not, okular sometimes, Preview doesn’t and was a problem in generating ugly boxes).

    The ways to do this are shown in my latex+bibtex instruction example.tex at
    http://www.staff.science.uu.nl/~rutte101/Report_recipe.html

    Cheers, Rob

Leave a Reply

Your email address will not be published. Required fields are marked *