PDFs

I find myself increasingly wishing to have PDF versions of my documents. If I wish to distribute my document electronically, then PDF has become the de-facto choice due to the ubiquity of PDF viewers and the greatly reduced filesizes that the PDF standard permits (compared to PS). This tutorial aims to ensure you know how to create PDFs from your LaTeX source, and how to utilise other features like hyperlinking.

Generating PDFs with pdflatex

There are many ways to create PDFs (I described one approach in the first tutorial) but I will be focussing only on the pdflatex approach. pdflatex, is a tool which ships with most LaTeX distributions that will read your LaTeX source and generate a PDF directly. There is no intermediate DVI or PS files. It's therefore extremely quick and easy to create a PDF, which is the reason I choose to only look at this tool.

To use, you just simply substitute 'pdflatex' where you would have normally used 'latex'. A typical pass for a document with figures, cross-references and a bibliography would be:

% pdflatex mydoc

% bibtex mydoc
% pdflatex mydoc
% pdflatex mydoc

You will notice that there is a new PDF file in the working directory called mydoc.pdf. Simple :)

Dealing with images

Generally speaking, pdflatex and latex can be used interchangably with the only difference being that the former generates PDF files and the latter generates DVI files. However, there is some additional issues regarding the importing of images that causes incompatability problems. As you may recall from the Importing Graphics tutorial, latex expects images to be in EPS (or PS) format exclusively. pdflatex on the other hand is a little more flexible, as it can import JPG, PNG and PDF formats.

latex	pdflatex
EPS PS	JPEG PNG PDF

Notice, however, that the two sets are mutally exclusive. So, if you have a latex document with EPS images and you wish to process with pdflatex then you must convert the EPS files to one of the supported formats. There are tools like epstopdf that come with the Ghostscipt package for Windows and Linux, or utilities like convert that is part of the ImageMagick package (again, availble for Windows/UNIX-based systems). There are of course a myriad of freeware and commercial applications that can achieve the same results, but I won't go it this any further.

Creating latex/pdflatex compatible documents

Providing you followed the instructions in the Importing Graphics tutorial then there's little to do. To recap, here's how to import an image:

\includegraphics{chick}

Now, with latex it would have expected an image file to exist called 'chick.eps' - the file extension is inferred by the LaTeX processor, so you don't need to write 'chick.eps' as the argument to the includegraphics{} command. The same is also true for pdflatex, in that if you have the above command, it will search for an image file called 'chick.pdf', 'chick.jpg' or 'chick.png' (I'm not sure of the exact order).

Therefore, in this instance, there is no code to actually change, it's merely about existance of the appropriate image files. So, if I have a LaTeX document called, image_example.tex that loads a image with the basename 'chick', here are the necessary files:

image_example.tex
chick.eps (for processing with 'latex')
chick.png (for processing with 'pdflatex' - it could have been in jpg of pdf format too)

hyperref - Hyperlinks and bookmarks

Just generating a PDF version of your LaTeX document will be adequate for most users. However, it's worth noting that the PDF standard allows you add additional features, such as providing document meta-data, or the ability to place links within a PDF. Most of these enhancements are for the benefit of those reading the document electronically using a PDF viewer.

The hyperref package is designed to enhance documents that are to be output as HTML and PDF, although it's especially useful for the latter. It provides all the facilities you require to take advantage of all the additional features the PDF standard has to offer. This package does in fact offer a bewildering number of options - too many to cover here. I will therefore give you a snapshot of the most useful/common settings to customise. The full list is discussed in the package manual.

hyperref is included by default with most mainstream TeX distributions, and to use it you simply do as you would with any other package:

\usepackage{hyperref}

Although it's beneficial if you specify a driver argument that tells hyperref which method is being used to generate the final output.

\usepackage[driver]{hyperref}

If you are using the pdflatex command discussed earlier, the driver you use is pdftex. The possible drivers (although most are unlikely to be relevant to the vast majority of users) are:

• hypertex - default driver if one is not specified.
• dvips
• dvipsone
• ps2pdf
• text4ht
• latex2html
• pdftex
• dvipdf
• dvipdfm
• dviwindo
• vtex
• vtexpdfmark
• textures

As there are so many routes to get to a PDF or HTML output, hyperref needs to know your expected route because the tools used during the conversion work differently and thus need to be catered for individually. It's an unfortunate consequence of the sheer flexibility of LaTeX. I recommend reading the introduction of the manual for more detail on this topic.

Once enabled, hyperref will load up its default configuration that specify all the properties of the forthcoming PDF. Most of the defaults are pretty sensible, and typically the main changes people make are to the document meta-data, and customising the link colours.

Before introducing the available options, it's worth addressing how you actually specify your preferred settings. By far the most common is by passing arguments to the \usepackage{hyperref} command:

\usepackage[pdftex,
	pdfauthor={Andrew Roberts},
	pdftitle={Hyperref demonstration},
	colorlinks
]
{hyperref}

Alternatively, there is the \hypersetup{} command that is not dissimilar:

\usepackage[pdftex]{hyperref}
\hypersetup{
	pdfauthor={Andrew Roberts},
	pdftitle={Hyperref demonstration},
	colorlinks}

If you opt for the \hypersetup{} command, then you should use it within the document preamble.

PDF document information

Option	Data type	Default	Description
pdftitle	text		Sets the title field.
pdfauthor	text		Sets the author field.
pdfkeywords	text		Sets the keywords field.
pdfsubject	text		Sets the subject field.
pdfcreator	text		Sets the creator field.
pdfproducer	text		Sets the producer field.

Link options

Option	Data type	Default	Description
colorlinks	boolean	false	Links will be printed in colour.
linkcolor	colour	red	Colour of standard internal links.
anchorcolor	colour	black	Colour of anchor text.
citecolor	colour	green	Colour of citation links.
filecolor	colour	magenta	Colour of links to local files.
pagecolor	colour	red	Colour of links to other pages.
urlcolor	colour	cyan	Colour of external URL links.
frenchlinks	boolean	false	Use small caps rather than colours for links.

Display options

Option	Data type	Default	Description
bookmarks	boolean	false	Specifies whether to generate Acrobat bookmarks.
bookmarksopen	boolean	false	Displays the bookmarks fully expanded.
pdfstartview	text	FitB	Specifies the page view for when the PDF is opened within the viewer, e.g, fit to page-width/page-height, etc.. (See below for possible values)
pdfpagelayout	text	empty	The page layout of the displayed PDF, e.g., single-column, double-coloumn, etc. See below for all possible values.
pdfpagemode	text	UseOutlines	Gives direction to the viewer about how the PDF should be displayed when opened. Possible values are: None, UseThumbs (show thumbnails), UseOutlines (show bookmarks), and FullScreen.

pdfstartview parameters

• Fit - Fits the page to the window.
• FitH - Fits the width of the page to the window.
• FitV - Fits the height of the page to the window.
• FitR - Fits the rectangle specified by the four coordinates to the window.
• FitB - Fits the page bounding box to the window. This basically reduces the amount of whitespace (margins) that is displayed and thus focussing more on the text content.
• FitBH - Fits the width of the page bounding box to the window.
• FitBV - Fits the height of the page bounding box to the window.

pdfpagelayout parameters

• SinglePage - Displays a single page; advancing flips the page.
• OneColumn - Displays the document in one column; continuous scrolling.
• TwoColumnLeft - Displays the document in two columns, odd-numbered pages to the left.
• TwoColumnRight - Displays the document in two columns, odd-numbered pages to the right.

Summary

From this tutorial I hope you can see that it's not difficult to take LaTeX to the next step and produce proper PDF files. Additionally, the hyperref package also allows you to exploit features within the PDF standard that can make the user experience a little bit better - mainly through enabling links and bookmarks. Of course, the hyperref package offers even more flexibility than discussed in this tutorial. I just covered the most useful functions, and once you get familiar with them, you can then look at the hyperref manual to learn more about the finer points of the package.

Beyond this, there isn't really a great deal more to know about PDF and LaTeX.