TUGboat, Volume 23 (2002), No. 3/4 329 Tutorials ∗ Introduction to pdfTEX Thomas Feuerstack Abstract The following article is aimed at beginners and/or those interested in quickly creating PDF documents using pdfTEX, without having to work intensively to gain background knowledge. We will point out problems that frequently oc- cur while creating PDF documents, as well as their solutions — of course, we don't claim to solve every- thing. 1 Introduction If you look around in TEX newsgroups or discussion lists, you will quickly see that a large number of the questions posed deal with bringing together TEX and Adobe's Portable Document Format (PDF). Beginners in particular seem to get caught on the same rough edges with amazing regularity. Of- ten the first problem is just how, for example, you can convert a TEX document into PDF. Once this hurdle is jumped, there is likely to be difficulties with using graphics, and fonts in particular. ∗ This article originally appeared in Die TEXnische Ko- mödie 2/2001, in German, with the title “Einführung in pdfTEX”; it was translated by Steve Peter, and is published here with permission. 330 TUGboat, Volume 23 (2002), No. 3/4 Source File TEX/LATEX ? ? pdfTEX DVI File PDF Document dvips ? PS File dvipdfm ps2pdf/ Figure 2: The result of the hyperref package. Distiller ? PDF Document but an error message on your screen: Undefined control sequence..., then you've tried to run (as Figure 1: Even if not all roads lead to PDF, at you previously did) latex instead of pdflatex. You least there are several. should change this right away. Just by adding \pdfoutput=1 you got the de- sired effect; you can find the whole set of specific In brief: most of these “rough edges” are easy pdfTEX sequences in [6]. With just a little more ef- to master with simple techniques — as long as you fort (29 characters to be exact) you can drastically know what to do. This article is for those who aren't increase the effectiveness of your PDF output. (yet) in the know. Including \usepackage[pdftex]{hyperref} 2 From TEX/LATEX to PDF as the last package in the preamble of your TEX file not only causes PDF output, but also gives you the It is well-known that all roads lead to Rome, nothing following functionality for free: is impossible, and only you can make yourself happy. It therefore shouldn't be surprising that there isn't • All tables, such as table of contents, table of figures, etc., will automatically be linked to the just one way to put your TEX file on the road to PDF, but more than a half dozen ways, given a bit text. Clickable text is shown surrounded by a of creativity; Figure 1 gives a roadmap. colored frame. In principle, we can differentiate roughly the • A list of PDF bookmarks is created from the two following ways. structure of the table of contents. Using these The classic way: The document is TEXed as usual bookmarks in a manner similar to the table of and converted to PDF with the aid of a special contents itself, you can quickly navigate to var- driver (e.g., dvipdfm) or via PostScript (dvips ious parts of the text. followed by ps2pdf or Distiller). • Cross references within the text, like footnotes, The elegant way: pdfTEX creates the PDF format indices, etc., are hyperlinked to the text. you want directly from your document — and If you now load your freshly-made PDF docu- without further detours. ment into Adobe Reader (or any other PDF reader, Since the second alternative is usually not only for that matter), it might already look like Figure 2. faster to describe, but also in fact faster to use, let's concentrate on it. 4 Of course hyperref can do much more By using a selective set of hyperref options you can 3 12 characters to make your document tweak the appearance of your PDF document to al- “portable” most the smallest detail. The options, as is usual in Simply put \pdfoutput=1 in the preamble of your declaring LATEX packages, are given in square brack- document, and instead of the usual DVI file, you'll ets before the actual package name. We can distin- get PDF. If however, you get neither PDF nor DVI, guish between parameters that are simply passed TUGboat, Volume 23 (2002), No. 3/4 331 in (as in the example above with the parameter nails in the left frame; None and FullScreen (syn- pdftex), and those where the parameter requires onyms), to show the document without menubar, a value, such as pdfstartview=Fit. bookmarks, thumbnails, or a left frame in general. Thus, a typical declaration of hyperref might The zoom factor of the document can further- look like the following. more be configured by the following: pdfstartview sets the size of the page first dis- \documentclass{article} played (normally page 1, but that can be changed ... with pdfstartpage). Possible values are Fit, to \usepackage[pdftex,a5paper,% show the whole page; FitH, to fit the width of the pdftitle={The Ducks},% page in the window; or FitB, to fit the width of the pdfauthor={Mother Goose},% contents to the window. colorlinks=true,% pdfview determines the viewing size of a page linkcolor=blue% that is opened via hyperlink. The possible values ]{hyperref} are the same as those for pdfstartview; by default ... it is the same viewing size as the previous page. \begin{document} The additional information about the docu- ... ment, accessed in Acrobat Reader with the menu The complete range of all specifiable options command File – Document Properties – Summary, can be found in the documentation by Sebastian typically includes the document title, the author's Rahtz [5], with a somewhat more complete descrip- name, as well as keywords to enable automated tion in [4]. The possibilities described in the manu- searches. als may seem to be impossibly many, and often just You can set these values with options such as as hard to understand. Therefore, let's now look at pdftitle, pdfauthor, pdfkeywords, . Our list of a few commonly used options more closely. options is getting slowly but surely longer. 4.1 General options The `backend driver', in our case pdftex, informs the hyperref package how you want to create your PDF document. If, in spite of this article, you choose \documentclass{article} some other way to create PDFs (cf. Figure 1), you ... will need to change this option correspondingly. \usepackage[pdftex,a5paper,% Since there may be other LATEX packages in the pdftitle={The Ducks},% document that depend on a backend driver, for ex- pdfauthor={Mother Goose},% ample the graphicx package, you can specify the pdfkeywords={Ducks Fowl},% driver as an option to \documentclass; the option is pdfpagemode=FullScreen,% then passed to all packages that need it, and doesn't pdfstartview=FitB% have to be given each time you call \usepackage. ]{hyperref} The paper size is set to a4paper by default, ... but you can change it to a5paper, b5paper, letter- \begin{document} paper, legalpaper or executivepaper. ... The two options draft and debug play a spe- cial role. While draft turns off all hyperref func- 4.3 Configuring bookmarks tionality, debug places into your log file additional You can turn off automatic creation of bookmarks diagnostic information. with bookmarks=false, which (as you learned in the last section) means that the option pdfpagemode is 4.2 Screen display and document set to None. information Only top level bookmarks are typically shown; Normally your document will be displayed by Acro- to see lower bookmarks, you have to manually “ex- bat Reader as in Figure 2. You can change this with pand” the hierarchy. You can change that with the the help of the following options: bookmarksopen=true option, which will cause the pdfpagemode determines how Acrobat Reader entire bookmark tree to be displayed. is opened. Possible values are UseOutlines (de- If the bookmarks become a bit too prominent fault), to show the bookmarks in the left frame; when you do that, you can reach a usable compro- UseThumbs, to show the individual pages as thumb- mise with the bookmarksopenlevel option. 332 TUGboat, Volume 23 (2002), No. 3/4 4.4 Colors Then the list of options for the hyperref pack- As you will quickly see, links created by hyperref age can be reduced to only those needed just for this are colored. Links are colored differently depend- document. ing on the type of reference — for example, internal \documentclass{article} links (like in the table of contents) are red, blue for ... web links or email addresses, green for links to the \usepackage[pdftex,a5paper,% bibliography, and so forth. pdftitle={The Ducks},% The options citebordercolor (bibliography), pdfauthor={Mother Goose},% linkbordercolor (“normal” links), urlborderco- pdfkeywords={Ducks Fowl}% lor (web links and email), etc., override the default ]{hyperref} color values. You enter the color you want as three ... RGB values, which must be 0 ≤ RGB ≤ 1. For ex- \begin{document} ample, linkbordercolor={0 0 1} will change the ... standard red of “normal” links to blue. Options passed in the \usepackage declaration The width and style of the link box can be con- override options from the hyperref.cfg file that figured via pdfborder, which also requires a numeric have the same name. triplet. pdfborder={0 0 5} changes the line from 1 point to 5 points, with the result that you can 5 Your own links hardly see the text. Although the hyperref package already automati- Especially interesting effects can be achieved cally links for you almost everything in a TEX docu- by adding an optional parameter to the numeric ment that ought to be, you may actually want to add triplet.