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. For instance, pdfborder={0 0 1 [3]} cre- your own links to it. Links to URLs (i.e., to Web or ates a box with a 1 point border that is broken — email addresses) and document-internal links should the higher the value of the optional parameter, the be differentiated. longer the breaks in the line. Links to URLs can be made quite simply with colorlinks=true removes the box around the the command \href. link (which pdfborder={0 0 0} will also do), but A new day dawns in the text of the link is now colored. The color scheme \href{http://www.fburg.com}{Featherburg}, for boxes is also valid for colored text links, and can home of the richest be changed with the options linkcolor, citecolor, \href{mailto:[email protected]}{duck} urlcolor, etc. in the world. What’s good about this is that for changing col- In the example above, the words Featherburg ors used for text, you can use the color names in the and duck are colored according to the setting given color package; in other words, a declaration such by colorlinks. By clicking on Featherburg we as linkcolor=blue works just fine. will probably land on the home page of the city; by What’s not so nice about this is that when you clicking on duck you can send D. Duck an email — print, colored text is of course printed in color, which but don’t bother asking for money! means the table of contents is red, or gray on a black- For hyperlinks within a document you need to and-white printer. specify both the \hypertarget and \hyperlink. 4.5 Global settings With \hypertarget you define a jump location (also known as an anchor), which \hyperlink will then Settings that are the same for several documents target. need not be entered each time via the \usepackage declaration. They can instead be placed into a sys- In order to protect his financial temwide hyperref.cfg file. interests D. Duck has lived in a For example, if all of our documents use color- \hypertarget{trove}{safe}for decades. links and the “normal” link color should be blue, ... the following will accomplish it: ‘‘Let’s go’’, the safecrackers shouted, ‘‘Today it’s the %% hyperref.cfg: Global Settings \hyperlink{trove}{tightwad}’s turn!". \hypersetup{colorlinks=true,% In this example, the word tightwad is made linkcolor=blue,% clickable — using the mouse button will send us di- pdfproducer={Birds-of-a-Feather},% rectly to the safe. The connection between link and pdfstartview=FitB} target is made by the freely-chosen word trove. TUGboat, Volume 23 (2002), No. 3/4 333
6 Inclusion of graphics 7 Fonts and typefaces Conventional wisdom has it that a picture is worth Finally! You’re using the hyperref package, and a thousand words — which has lead many an author you’ve got it all configured just as you like it, all to the conclusion that the value of their work would your graphics are cleanly converted for pdfTEX, and increase according to the number of graphics it con- your document doesn’t have any errors when you tained. TEX it. We’re almost to the holy grail. The most complicated graphic that a pdfTEX All too often though, you’re coming down the user puts into their document is generally the first home stretch, and then Acrobat Reader offers some- one. So let’s start at the beginning. thing frightful: the typeface looks as if instead of If you have aready put graphics into your “nor- the usual TEX fonts, the font Horror is being used. mal” LATEX documents, ideally you should find there If you didn’t really choose Horror as your base the following constructs: font (thereby being quite happy with the typeface), then the cause is probably the following: \documentclass{article} ... TEX normally uses the so-called packed or bit- cmr10.pk \usepackage{graphicx} map fonts (e.g., ), which cause Acrobat no ... small amount of difficulty for screen display. pdfTEX \begin{document} automatically avoids this issue, in that instead of bitmaps, it uses outline-based PostScript varieties ... If we want to use examples from the world of Computer Modern (fonts are the principal case PDF of comics, we can include pictures. where the needs the PostScript construct). You can recognize this in the log file near the end of a \begin{figure} pdfTEX run when you see messages like: ...
• If that’s a bit too rich for you (like one of the Come to the next meeting of Dante and ask frequently-occurring characters in this article), Walter Schmidt, or better yet: come to one of Wal- get the (free) ae package and include that in ter Schmidt’s talks. your document. With ae you get a modern font The only thing I have left now is the → encoding, but the actual glyphs come from the Computer Modern PostScript fonts. 9 Conclusion ← that will close this overly-long article. If this in- • Use the freely available Latin Modern or CM- troduction to pdfT X still seems complicated, don’t super font collections now available from CTAN. E worry, just jump right in. 8 Additional PostScript fonts When creating new documents, using pdfTEX directly causes no problems in general, since you Even if using the standard PostScript fonts is quite don’t have to do anything extra aside from calling problem-free, including other, more exotic fonts can the hyperref package. Instead of the usual pre- present a very labor-intensive task. This may be viewer or print driver, Acrobat Reader can be used necessary since many firms and institutions, thanks without difficulty for both tasks. to corporate design, insist on typefaces such as Frut- It can be somewhat more complicated to re- iger, Futura, Garamond, etc. purpose existing T X files for pdfT X. Especially in Including such Type 1 fonts, for the most part E E cases where many (EPS) graphics need to be con- commercially-sold, is certainly not trivial. However, verted, it is frequently more efficient to choose the as is well-known, with T X almost nothing is impos- E traditional way and use tools like pstopdf for PDF sible; consider the following: creation. • If you’ve purchased a PostScript font, its distri- bution should include files with the extensions References .pfb, .afm, and/or .pfm. [1] D.P. Carlisle. Packages in the graphics bun- dle, Jan. 1999. http://www.ctan.org/ • For use with pdfT X you now still need the ac- E tex-archive/macros/latex/required/ companying files with the extensions .vf, .tfm, graphics/grfguide%.ps. .map, and .fd, and it is quite useful to have a style file to use the whole lot as a package in [2] Peter Flynn. “Installing PostScript fonts” in For- your document. matting Information. http://www.ctan.org/ tex-archive/documentation/beginlatex/ As a rule, these files are not on the disk when html/chapter8.%html#instfonts. you buy fonts! With a bit of luck, you might find them on CTAN in the fonts/psfonts di- [3] Philipp Lehman. The font installation guide. rectory. http://www.ctan.org/tex-archive/info/ Type1fonts/fontinstallationguide.p%df. • Look in the directory structure of your TEX in- [4] Heiko Oberdiek. PDF information and stallation, and try to find out where other font navigation elements with hyperref, pdfTEX packages place files with the above-named ex- and thumbpdf. In EuroTEX’99 Proceedings, tensions. Play around with putting the new 1999. http://www.tug.org/applications/ font files in the same places. hyperref/ftp/doc/paper.pdf. • Look for the pdftex.cfg configuration file and [5] Sebastian Rahtz. Hypertext marks in LATEX: the add your .map file to it. For example, for a hyperref package, Jun. 1998. http://www.tug. map file named newfont.map, you would add org/applications/hyperref/. the line map +newfont.map. [6] Hàn Th´ê Thánh, Sebastian Rahtz, and Hans If you did everything correctly, the new fonts Hagen. The pdfTEX user manual, Jan. 2000. http://www.tug.org/applications/ should now be usable with pdfTEX. If you have dif- ficulties, you might consult [2] and/or [3] for detailed pdftex/pdftex-a.pdf. information. If you want to know a bit more about what Thomas Feuerstack you’ve just actually done, and what those files with FernUniversität in Hagen 58084 Hagen the weird extension names are good for, I have a tip Germany for you. Thomas.Feuerstack@ fernuni-hagen.de