\makeatletter \def\Program#1{\textsf{#1}} \def\bs{{\protect\normalfont\ttfamily\char'134}} \def\Lcs#1{\mbox{\normalfont\ttfamily\bs#1}} \def\Lfile#1{\mbox{\normalfont\ttfamily#1}} \def\Lmcs#1{\mbox{\normalfont\ttfamily\bs#1}} \def\Lpack#1{\textsf{#1}} \def\arraybackslash{\let\\=\@arraycr} \newcolumntype{P}[1]{>{\raggedright\arraybackslash}p{#1}} \newcolumntype{C}[1]{>{\centering\arraybackslash}p{#1}} \newcolumntype{H}[1]{>{\raggedright\hangindent=.5em\arraybackslash}p{#1}} \newcolumntype{M}[1]{>{\raggedright\arraybackslash}m{#1}} \def\Email#1{(\url{mailto:#1})} % \def\parkey#1#2{{\normalsize\ttfamily#1}\lcb#1\rcb} \def\xparkey#1#2{{\normalsize\ttfamily#1} #1} \def\lcb{{\protect\normalfont\ttfamily\char'173}} \def\rcb{{\protect\normalfont\ttfamily\char'175}} \def\lsb{{\protect\normalfont\ttfamily\char'133}} \def\rsb{{\protect\normalfont\ttfamily\char'135}} \def\lab{{\protect\normalfont\ttfamily\char'074}} \def\rab{{\protect\normalfont\ttfamily\char'076}} \newsavebox{\boxdef} \newenvironment{BDef}{\begin{lrbox}{\boxdef}\def\arraystretch{1.0}% \begin{tabular}{@{}l@{}l@{}l@{}}}% {\end{tabular}\end{lrbox}% \BCmd\fbox{\usebox\boxdef}\endBCmd} \newcommand{\Larg}[1]{{\normalfont\itshape\fontsize{11}{10pt}\selectfont#1\/}} \newcommand{\Largb}[1]{\lcb{\normalfont\itshape\fontsize{11}{10pt}\selectfont#1\/}\rcb} \newcommand{\Largs}[1]{\lsb{\normalfont\itshape\fontsize{11}{10pt}\selectfont#1\/}\rsb} \newcommand{\Largr}[1]{({\normalfont\itshape\fontsize{11}{10pt}\selectfont#1\/})} \newenvironment{BCmd}{\fboxsep=3pt\flushleft\vskip8pt} {\endflushleft} \def\DefC#1{\Lmcs{#1}} \newcommand{\DefCmmmm}[5]{\Lmcs{#1}\Largb{#2}\Largb{#3}\Largb{#4}\Largb{#5}} \newcommand{\DefCmm}[3]{\Lmcs{#1}\Largb{#2}\Largb{#3}} \newcommand{\DefCm}[2]{\Lmcs{#1}\Largb{#2}} \newcommand{\DefCx}[2]{\Lmcs{#1}\Larg{#2}} \newcommand{\BDefCmmmm}[5]{\begin{BCmd}\fbox{\DefCmmmm{#1}{#2}{#3}{#4}{#5}}\end{BCmd}} \newcommand{\BDefCmm}[3]{\begin{BCmd}\fbox{\DefCmm{#1}{#2}{#3}}\end{BCmd}} \newcommand{\BDefCm}[2]{\begin{BCmd}\fbox{\DefCm{#1}{#2}}\end{BCmd}} \newcommand{\BDefCx}[2]{\begin{BCmd}\fbox{\DefCx{#1}{#2}}\end{BCmd}} \def\pdftex{pdf\TeX} \makeatother \author[Han The Thanh] {Han The Thanh\\ Faculty of Informatics,\\ Masaryk University, \\Brno,\\ Czech Republic\\ \texttt{thanh@informatics.muni.cz}} \title{The \pdftex{} user manual} \date{January 1998} \begin{Article} \section{Introduction} The \pdftex{} project started in 1996 at the Faculty of Informatics, Masaryk University, Brno, Czech Republic. It forms a primary part of the MSc and PhD research of Han The Thanh, under the supervision of Ji\v r\'\i{} Zlatu\v ska and Petr Sojka. The main purpose of the project was to create an extension of \TeX{} that could create PDF directly from \TeX\ source files and improve/enhance the result of \TeX\ typesetting with the help of PDF. \pdftex{} contains \TeX\ as a subset. When PDF output is not set, it produces normal DVI output; when PDF output is selected, \pdftex{} produces PDF output that looks identical to the DVI output. The next stage of the project, apart from fixing any errors in the program, is to investigate alternative justification algorithms, possibly making use of multiple master fonts. \pdftex{} is based on the original \TeX\ sources and \Program{web2c}, and has been successfully compiled on Unix, Amiga, Win32 and DOS systems. It is still under beta development and all features are liable to change. This manual was compiled by Sebastian Rahtz from notes and examples by Han The Thanh. Many thanks are due to members of the pdf\TeX{} mailing list (most notably Hans Hagen), whose questions and answers have contributed much to this manual. \section{Implementation details} The implementation of \pdftex{} consists of two parts: the changes to \TeX, and the addition of `driver' features. The \TeX-specific part is written as a change file to the original source of \TeX\ and contains: \begin{itemize} \item a part that generates PDF code visually equivalent to DVI commands; \item virtual font processing; \item implementation of new primitives for PDF control. \end{itemize} The `driver' part is written as several source files in C, and implements \begin{itemize} \item font mapping, \item font inclusion and partial downloading, \item font re-encoding, \item PNG picture insertion (using the public domain \texttt{libpng} code), \item text compression (using the public domain \texttt{zlib} code). \end{itemize} \subsection{Compilation} \pdftex{} is supplied as a set of additions to the standard Unix \Program{Web2c} setup, and is a standard part of \Program{Web2c} 7.2 (from January 1998); compilation should present no problems on most Unix systems. Porting it to other setups will require a little work, because of the requirement to combine the normal \TeX{} Web output, and the parts written in C. For Win32 systems (Windows 95, Windows NT) there are two packages that contain \pdftex, both in \url{CTAN:systems/win32}. \Program{Web2c} for Win32 is maintained by Fabrice Popineau \Email{popineau@ese-metz.fr}, and \Program{MikTeX} by Christian Schenk \Email{cschenk@berlin.snafu.de}. A binary version of \pdftex{} for Amiga is made available (\url{CTAN:systems/pdftex/bin/Amiga}) by Andreas Scherer \Email{Scherer@Physik.RWTH-Aachen.De}. To make the situation more complicated, a Win32 binary version of \pdftex{} compiled with Cygnus tools will also be made available in \url{CTAN:systems/pdftex/bin/Win32}. This version will be compiled in the same way as Unix systems. \subsection{Search paths} When runing \pdftex, some extra search paths need to be set up beyond those normally requested by \TeX{} itself; in \Program{web2c} these are: \begin{description} \item{VFFONTS} the path where \pdftex{} looks for virtual fonts. \item{T1FONTS} the path where \pdftex{} looks for Type1 and TrueType fonts. \item{TEXPSHEADERS} the path where \pdftex{} looks for the font mapping file (\texttt{pdftex.map}), PNG pictures and encoding files (\texttt{*.enc}). \end{description} %--------------------------------------------------------------- \section{Fonts} \pdftex{} can only work with Type~1 and TrueType fonts at present, and a source must be available for all fonts used in the document, except for the 14 base fonts supplied by Acrobat Reader (Times, Helvetica, Courier, Symbol and Dingbats). It is \emph{not} possible to use \MF-generated fonts in \pdftex---apart from the technical reasons, the resulting Type~3 fonts render very poorly in Acrobat Reader. Given the free availability of Type~1 versions of all the Computer Modern fonts, and the ability to use standard PostScript fonts without further ado, most existing \TeX{} users should be able to experiment with \pdftex. \pdftex{} reads a map file called \texttt{pdftex.map}. Reencoding and partial downloading for each font is specified in this file. Every font must be listed in this file, each on a separate line. The syntax of each line is similiar to \Program{dvips}' map files (but may be changed later). Each line contains the following fields (some of them are optional): {\ttfamily\small\flushleft\begin{tabular}{lllll} texname&basename&fontflags&fontfile&encoding\\ \end{tabular} \endflushleft} \begin{description} \item{\texttt{texname}}: the name of the TFM file \item{\texttt{basename}}: the base font name (PostScript font name) \item{\texttt{fontflags}}: an integer number specifying the most important characteristics of the font. This number is significant only in the case that the font file is \emph{not} included, and Acrobat Reader is asked to simulate missing font using its multiple master defaults. It is a PDF font descriptor (see PDF manual, section 7.9.2) which is a 32-bit integer containing a collection of Boolean attributes, with bit 1 being the least significant. Attributes are true if the corresponding bit is set to 1 in the integer. The meanings of the bits is as follows: \begin{tabular}{ll} 1 &Fixed-width font\\ 2 &Serif font\\ 3 &Symbolic font\\ 4 &Script font\\ 5 &(reserved)\\ 6 &Uses the Adobe Standard Roman Character Set\\ 7 &Italic\\ 8--16 &(reserved)\\ 17 &All-cap font\\ 18 &Small-cap font\\ 19 &Force bold at small text sizes\\ 20--32 &(reserved)\\ \end{tabular} Bit 6 indicates that the font's character set is the Adobe Standard Roman Character Set, or a subset of that, and that it uses the standard names for those characters. About bit 19, the PDF specification says \begin{quote} \ldots used to determine whether or not bold characters are drawn with extra pixels even at very small text sizes. Typically, when characters are drawn at small sizes on very low resolution devices such as display screens, features of bold characters may appear only one pixel wide. Because this is the minimum feature width on a pixel-based device, ordinary non-bold characters also appear with one-pixel wide features, and cannot be distinguished from bold characters. If bit 19 is set, features of bold characters may be thickened at small text sizes. \end{quote} It should be stressed that the font flags provided for many fonts in the currently distributed \Lfile{pdftex.map} are not correctly derived. \item{\texttt{fontfile}}: the name of the font source file. This must be a Type~1 or TrueType font file. If it is preceded by a \texttt{<} then the font file will be partly downloaded; if it preceded by a double \verb|<<| then the font file will be included entirely. Otherwise the font is not included, and only the font parameters are extracted. Note that the font file \emph{must} always be available at runtime, even if it not downloaded. \item{\texttt{encoding}}: the encoding vector used for the font. It may be preceded by a \texttt{<}, but the effect is the same. The format is identical to that used by \Program{dvips}. \end{description} Here are some sample lines from \texttt{pdftex.map}: \noindent Include font entirely without reencoding --- \begin{verbatim} pgsr8r GillSans 34 <{\ttfamily}lP{.75\textwidth}} /UseNone & Open document with neither outline nor thumbnails visible.\\ /UseOutlines& Open document with outline visible.\\ /UseThumbs& Open document with thumbnails visible.\\ /FullScreen& Open document in full-screen mode. In full-screen mode, there is no menu bar, window controls, nor any other window present.\\ \end{tabular} \end{flushleft} The default is \texttt{/UseNone}. \BDefCx{pdfimage}{ \xparkey{height}{dimen} \xparkey{width}{dimen} filename} Insert a bitmap image in PNG format, optionally changing width, height or both. Dimensions which are not specified will be treated as zero. If both height and width are zero then the box takes the natural size of the image. If one of them (width or height) is zero and the second is not, then the first one (the zero one) will be set to a value proportional to the second one so as to make the box have the same proportion of width and height as the image natural size. If both width and height are positive then the image will be scaled to fit these dimensions. \BDefCx{pdfform}{ num} Write out the \TeX{} box \emph{num} as a Form object to the PDF file. \BDefCx{pdflastform}{} Returns the object number of the last Form written to the PDF file \BDefCx{pdfrefform}{ \Lcs{name}} Put in a reference to the PDF Form called \Lcs{name}. These macros support a feature called ``object reuse'' in \pdftex. The idea is to create a Form object in PDF. The content of the Form object corresponds to the content of a \TeX\ box, which can also contain pictures and references to other Form objects as well. After that the Form can be used by simply referring to its object number. This feature can be useful for large document with a lot of similiar elements, as it can reduce the duplication of identical objects. \BDefCx{pdfannottext}{ \xparkey{width}{dimen} \xparkey{height}{dimen} \xparkey{depth}{dimen} \parkey{attr}{attributes} \Largb{text}} Attach a text annotation at the current point in the text. The attributes can be used to specify the default appearance of the annotation (e.g., \texttt{/Open true} or \texttt{/Open false}), as well as many other features (see Table 6.8 of the PDF manual). \BDefCx{pdfdest}{ \xparkey{num}{n} \parkey{name}{refname} appearance} Establish a destination for links and bookmark outlines; the link must be identified by either a number or a symbolic name, and the way Acrobat is to display the page must be specified; \emph{appearance} must be one of \begin{flushleft} \begin{tabular}{>{\ttfamily}ll} fit & fit whole page in window\\ fith & fit whole width of page \\ fitv & fit whole height of page \\ fitb & fit whole `Bounding Box' page \\ fitbh & fit whole width of `Bounding Box' of page \\ fitbv & fit whole height of `Bounding Box; of page \\ \end{tabular} \end{flushleft} \BDefCx{pdfannotlink}{ % \xparkey{height}{dimen} \xparkey{depth}{dimen} \parkey{attr}{attributes} action } Start a hypertext link; if the optional dimensions are not specified, they will be calculated from the box containing the link. The \emph{attributes} (explained in great detail in section 6.6 of the PDF manual) determine the appearance of the link. Typically, this is used to specify the color and thickness of any border around the link. Thus \texttt{/C [0.9 0 0] /Border [0 0 2]} specifies a color (in RGB) of dark red, and a border thickness of 2 points. The \emph{action} can do many things; some possibilities are \begin{flushleft} \begin{tabular}{lP{.7\textwidth}} goto num \emph{n} & \\ goto name \Largb{refname} & Jump to a point established as \emph{name} with \Lcs{pdfdest}\\ goto file \Largb{filename} & Open a local file; this can be used \emph{with} a \emph{name} or \emph{num} specification, to point to a specific location on the file. Thus \verb|goto file{foo.pdf} name{intro}|\\ thread num \Largb{n} & \\ thread name \Largb{refname} & Jump to thread identified by \emph{n} or \emph{refname}\\ user \Largb{spec} & Perform user-specified action. Section 6.9 of the PDF manual explains the possibilities. A typical use of this is to specify a URL, e.g.\ \texttt{/S /URI /URI (http://www.tug.org/)}. \end{tabular} \end{flushleft} \BDefCx{pdfendlink}{} Ends link; all text between \Lcs{pdfannotlink} and \Lcs{pdfendlink} will be treated as part of this link. \pdftex{} may break the result across lines (or pages), in which case it will make several links with the same content. \BDefCx{pdfoutline}{ action \xparkey{count}{n} \Largb{text} } Create a outline (or bookmark) entry. The first parameter specificies the action to be taken, and is the same as that allowed for \Lcs{pdfannotlink} (see above, though note that the \texttt{Page} key does not work properly at present). The \emph{count} specifies the number of direct subentries under this entry, 0 if this entry has no subentries (in this case it may be omitted). If the number is negative, then all subentries will be closed and the absolute value of this number specifies the number of subentries. The \emph{text} is what will be shown in the outline window (note that this is limited to characters in the PDFEncoding vector). \BDefCx{pdfthread}{ \xparkey{num}{n} \parkey{name}{refname} } Start an article thread; the corresponding \Lcs{pdfendthread} must be in the box in the same depth as the box containing \Lcs{pdfthread}. All boxes in this depth level will be treated as part of this thread. An identifier (\emph{n} or \emph{refname}) must be specified; threads with same identifier will be joined together. \BDefCx{pdfendthread}{} Finish the current thread. \BDefCx{pdfthreadhoffset}{=dimen} \BDefCx{pdfthreadvoffset}{=dimen} Specify thread margins. One way to learn more about how to use these primitives is to have a look at the file \Lfile{example.tex} in the \pdftex{} distribution. \hrule \multicols{2} \section{Graphics and color} Probably the biggest single usage problem with \pdftex{} at the present time is the inclusion of graphics. The program only directly supports graphic inclusion in one bitmap format, PNG (Portable Network Graphics). Two commonly-used techniques are not available --- the inclusion of Encapsulated PostScript figures, and the inclusion of raw PostScript commands (the techique utilized by the \Lpack{pstricks} package). Although PDF is a direct descendant of PostScript, it lacks any programming language commands, and cannot deal with arbitrary PostScript. There are two ways to proceed with existing EPS files: firstly, convert them to PNG (using programs like Image Magick, Image Alchemy, or Ghostscript); or secondly, try converting them to simple PDF. If the picture has no special fonts, the chances are quite good that Ghostscript's pdf writer will produce a file containing a single PDF object, which can be included using \Lcs{pdfliteral} commands (this is managed by the standard \LaTeX{} graphics package). Other alternatives for graphics in \pdftex{} are: \begin{enumerate} \item \protect\LaTeX{} picture mode: since this is implemented simply in terms of font characters, it works in exactly the same way as usual; \item Xy-pic: If the PostScript backend is not requested, Xy-pic uses its own Type~1 fonts, and needs no special attention; \item tpic: The `tpic' \Lcs{special} commands (used in some macro packages) can be redefined to produce literal PDF, using macros by Hans Hagen; \item MetaPost: although the output of MetaPost is PostScript, it is in a highly simplified form, and a MetaPost to PDF conversion (written by Hans Hagen and Tanmoy Bhattacharya) is implemented as a set of macros which read MetaPost output and support all of its features; \item It is possible to insert a ``pure'' PDF file (PDF that has only one page without fonts, bitmaps or other resources) using a macro package that reads the external PDF file line by line. \end{enumerate} The two latter macro packages are part of CON\TeX{T} (\Lfile{supp-pdf.tex} and \Lfile{supp-mis.tex}), but also work with \LaTeX{} and are distributed separately. For new work, the MetaPost route is highly recommended. For the future, Adobe have announced that they will define a specification for `encapsulated PDF', and this should solve some of the present difficulties. \section{Macro packages supporting \pdftex} \begin{itemize} \item For \LaTeX{} users, Sebastian Rahtz' \Lpack{hyperref} package has substantial support for \pdftex, and provides access to most of its features. In the simplest case, the user merely needs to load \Lpack{hyperref} with a `pdftex' option, and all cross-references will be converted to PDF hypertext links. PDF output is automatically selected, text compression turned on, and the page size is set up correctly. Bookmarks are created to match the table of contents. \item The standard \LaTeX{} \Lpack{graphics} and \Lpack{color} packages have \texttt{pdftex} options, which allow use of normal color, text rotation, and graphics inclusion commands. Only PNG and MetaPost files can be included. \item The Con\TeX{}T macro package by Hans Hagen \Email{pragma@pi.net} has very full support for \pdftex{} in its generalized hypertext features. \item Hypertexted PDF from \texttt{texinfo} documents can be created with \texttt{pdftexinfo.tex}, which is a slight modification of the standard \texttt{texinfo} macros. This is part of the \pdftex{} distribution. \item A similiar modification of the \texttt{webmac}, called \texttt{pdfwebmac.tex}, allows production of hypertexted PDF versions of program written in WEB. This is part of the \pdftex{} distribution. \end{itemize} Some nice samples of \pdftex{} output can be found on the TUG Web server, at \url{http://www.tug.org/applications/pdftex/}. \end{Article}