I want to include the documentation for one of my programming projects in my
thesis. The documentation is generated by Sphinx, which can generate LaTeX
output. I compiled that output to PDF, which is relatively easy to include in a
separate LaTeX file with the pdfpages package. Unfortunately, including a
separate PDF file in this manner breaks all the internal and external clickable
links in the included PDF. The solution is an experimental Java program called
pax. Pax reads the PDF file before it is included and generates a .pax
file. pdfTeX reads the .pax file when it includes the PDF and re-generates
all of the links.
Unfortunately, installing Pax is kind of a bear. The first thing to do is
download Java and Perl. Java is easy to download and install
on Windows; I used Strawberry Perl as my Perl interpreter. Strawberry Perl
gets installed in a directory in the root of the C:\ drive to avoid any
permissions issues with the Program Files directory. Next is to download PDFBox,
which is a Java library for operating on PDF files. Only version 0.7.2 and 0.7.3
will work, which are available from SourceForge. Extract the zip file into
a directory with write permissions, like C:\PDFBox.
Pax itself can now be installed from the MikTeX package installer. If you use
the admin version, the scripts you need will be installed in ...\MikTeX
2.9\scripts\pax. Otherwise, note where MikTeX installed the scripts for Pax.
Then, we need to create a local texmf directory. I followed the instructions
here and created the directories C:\localtexmf\latex,
C:\localtexmf\tex, and C:\localtexmf\bin. Then, in the Settings window for
MikTeX, in the Roots tab, add this the root directory (i.e. C:\localtexmf) and
on the General tab, click Update FNDB.
Now create a file in the bin directory called pax.bat and put into it
@echo off
SETLOCAL
set CLASSPATH=C:\PDFBox\lib\PDFBox-0.7.3.jar;%CLASSPATH%
perl "C:\Program Files\MiKTeX 2.9\scripts\pax\pdfannotextractor.pl" %*
Finally, make sure the C:\StrawberryPerl, C:\localtexmf\bin and Java
directories are on your path. Then you can run
pax FileWithLinksToBeIncluded.pdf
This will generate the .pax file. Credit for this solution goes to the
wonderful TeX.SX. Then, in the main TeX document, write
...
\usepackage{pdfpages}
\usepackage{pax}
...
\begin{document}
\includepdf[pages={-}]{FileWithLinksToBeIncluded}
\end{document}
and compile with pdf(La)TeX. Note that Pax only works with pdf(La)TeX. It cannot
work with XeTeX (or XeLaTeX) according to this post. However, LuaLaTeX
supports nearly all of the fontspec options that XeTeX does, and LuaLaTeX can
be hacked to work with Pax. If you would like to use LuaLaTeX, add the following
to your preamble instead of \usepackage{pax} credit:
\usepackage{pdftexcmds}
\makeatletter
\let\pdfescapename=\pdf@escapename
\let\pdfstrcmp=\pdf@strcmp
\makeatother
\usepackage{pax}