\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 <<pgsr8a.pfb
\end{verbatim}
\noindent  Include font partly without reencoding ---
\begin{verbatim}
 pgsr8r GillSans 34 <pgsr8a.pfb
\end{verbatim}
\noindent  Do not include font, or reencode it, but extract parameters
from font file ---
\begin{verbatim}
 pgsr8r GillSans 34 pgsr8a.pfb
\end{verbatim}
\noindent  Include font entirely and reencode ---
\begin{verbatim}
 pgsr8r GillSans 34 <<pgsr8a.pfb 8r.enc
\end{verbatim}
\noindent  Partially include font and reencode ---
\begin{verbatim}
 pgsr8r GillSans 34 <pgsr8a.pfb 8r.enc
\end{verbatim}
\noindent  Do not include font but extract parameters from font file and
  reencode ---
\begin{verbatim}
 pgsr8r GillSans 34 pgsr8a.pfb 8r.enc
\end{verbatim}
\noindent  A TrueType font can be used in the same way as a Type 1
font ---
\begin{verbatim}
 Cxr10 Cxr10 34 <Cxr10.ttf Cxtext.enc
\end{verbatim}
\noindent  A base font can also be reencoded; 
the name of the font file is simply
  ignored ---
\begin{verbatim}
 phvr8r Helvetica 32 <Helvetica.pfb 8r.enc
\end{verbatim}

%---------------------------------------------------------------
\endmulticols
\hrule

\section{New primitives}
Here is a short description of new primitives added by \pdftex:

\BDefCx{pdfoutput}{=n} Integer parameter specifying whether the output
format should be DVI or PDF. Positive value means PDF output,
otherwise DVI output.  This parameter cannot be specified \emph{after}
shipping out the first page.


\BDefCx{pdfcompresslevel}{=n}
Integer parameter specifying the level of text
compression via \texttt{zlib}. 
Zero means no compression, 1~means fastest, 9~means 
best, 2..8 means something in between.

\BDefCx{pdfpagewidth}{=dimen}
\BDefCx{pdfpageheight}{=dimen}
Dimension parameters specifying the
page width and page height of PDF output.
If not specified then they are calculated as $\Lcs{hsize} \mbox{ or }
\Lcs{vsize}  + 2 \times (1in + \Lcs{hoffset}\mbox{ or }\Lcs{voffset})$,
when \pdftex{} writes the first page. 


\BDefCm{pdfliteral}{pdf text} Like \Lcs{special} in normal \TeX, this
can be used to insert raw PDF code into the output. This allows
support of color, and text transformation.

\BDefCx{pdfinfo}{ \parkey{author}{author name}
\parkey{title}{title}
\parkey{subject}{subject text}
\parkey{keywords}{keywords}}
Specify document information. All keys are optional; if this
information is provided, it can be seen in Acrobat Reader with the
menu option \textsf{Document Information $\leadsto$ General}

\BDefCx{pdfcatalog}{ \parkey{pagemode}{mode} \parkey{uri}{URI}}
Document display information.  Both keys are optional.
\emph{URI} provides the base URL of the document, and
\emph{pagemode} determines how Acrobat displays the document on startup.
The possibilities are:
\begin{flushleft}
\begin{tabular}{>{\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}

