summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/dvipdfm/dvipdfm.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/dvipdfm/dvipdfm.tex')
-rw-r--r--Master/texmf-dist/doc/dvipdfm/dvipdfm.tex1304
1 files changed, 1304 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/dvipdfm/dvipdfm.tex b/Master/texmf-dist/doc/dvipdfm/dvipdfm.tex
new file mode 100644
index 00000000000..8ebfc3011a7
--- /dev/null
+++ b/Master/texmf-dist/doc/dvipdfm/dvipdfm.tex
@@ -0,0 +1,1304 @@
+% $Header$
+% \special{ pdf: pagesize width 8.5truein height 11.0truein}
+\special{ pdf: docview <</PageMode /UseOutlines>>}%
+\catcode`\ =11\def\space{ }\catcode`\ =10
+% Page layout
+\tolerance=2000
+\magnification\magstephalf
+\advance\hoffset by 0.5truein
+\advance\voffset by 0.5truein
+\advance\hsize by -1.0truein
+\advance\vsize by -1.0truein
+\def\makefootline{\baselineskip=40pt\line{\the\footline}}
+%
+% Some helpful symbols
+\def\rtm{{\font\r=cmss10 at 4pt
+\font\c=cmsy5
+\setbox0\hbox{\c\char13}\skip0\wd0\box0\setbox0\hbox{\r R}\advance\skip0 by
+\wd0\kern-0.5\skip0\box0}}
+\def\tm{{\font\r=cmss10 at 4pt \hbox{\r TM}}}%
+%
+% Verbatim mode borrowed from manmac macros
+%
+\outer\def\begindisplay{\obeylines\startdisplay}
+{\obeylines\gdef\startdisplay#1
+ {\catcode`\^^M=5$$#1\halign\bgroup\indent##\hfil&&\qquad##\hfil\cr}}
+\outer\def\enddisplay{\crcr\egroup$$}
+\chardef\other=12
+\def\ttverbatim{\begingroup \catcode`\\=\other \catcode`\{=\other
+ \catcode`\}=\other \catcode`\$=\other \catcode `\&=\other
+ \catcode`\#=\other \catcode`\%=\other \catcode `\~=\other
+ \catcode`\_=\other \catcode`\^=\other
+ \obeyspaces \obeylines \tt}
+{\obeyspaces\gdef {\ }}
+\outer\def\begintt{$$\let\par=\endgraf\ttverbatim \parskip=0pt
+ \catcode`\|=0 \rightskip=-5pc \ttfinish}
+{\catcode`\|=0 |catcode`|\=\other
+ |obeylines % end of line is now active
+ |gdef|ttfinish#1^^M#2\endtt{#1|vbox{#2}|endgroup$$}}
+\catcode`\|=\active
+{\obeylines\gdef|{\ttverbatim\spaceskip=\ttglue\let^^M=\ \let|=\endgroup}}
+\newskip\ttglue
+\ttglue=0.5em plus 0.25em minus 0.15em
+%
+%
+% Some color definitions
+%
+\def\begincolor#1{\special{pdf:bc #1}}%
+\def\endcolor{\special{pdf:ec}}%
+\def\colored#1#2{%
+ \begincolor{#1}#2\endcolor}
+\def\red{[0.8 0.5 0]}%
+\def\green{[0 1 0]}%
+\def\blue{[0 0.4 0.8]}%
+\def\yellow{[0.8 0.9 0.1]}%
+\def\linkcolor{[0.5 0.0 0.7]}%
+%
+% Small help for images
+\def\reserve#1#2#3{\setbox0\hbox{}\wd0=#1
+ \ht0=#2\special{#3}\box0}
+\def\nreserve#1#2#3{\setbox0\hbox{}\wd0=#1
+ \ht0=#2{#3}\box0}
+%
+% Some font definitions
+%
+\font\maintitlefont=cmti12 at 20.74pt
+\font\headingfont=cmss12 at 14.4pt
+\font\subheadingfont=cmss12 at 12pt
+%
+%
+% Miscellaneous token lists
+%
+\newtoks\title\newtoks\author\newtoks\version
+\newtoks\date
+%
+% Bibliography counters
+\newcount\biblioitems\biblioitems=0
+\def\bibitem{\medskip\advance\biblioitems by 1\item{[\the\biblioitems]}}
+%
+% Counters for section levels
+%
+\newcount\sectioncount\newcount\ssectioncount\newcount\sssectioncount
+\sectioncount0\ssectioncount0\sssectioncount0
+%
+\newskip\indentlevel\indentlevel=\parindent
+\newskip\secskip\secskip=24pt plus 1pt minus 2pt
+\newskip\subsecskip\subsecskip=16pt plus 1pt minus 2pt
+\def\beginlist{\par\nobreak\advance\leftskip by \indentlevel\advance\rightskip by
+\indentlevel\medskip\nobreak}
+\def\endlist{\par\advance\leftskip by -\indentlevel\advance\rightskip by
+-\indentlevel\medskip}
+%
+%
+\def\settitle{%
+ {\maintitlefont\colored{\blue}{\the\title}}%
+ \special {pdf: docinfo << /Title (\expandafter\the\title) >>}}
+%
+\def\setauthor{%
+ {\headingfont\colored{\blue}{\the\author}}%
+ \special {pdf: docinfo << /Author (\the\author) >>}}%
+%
+\def\setversion{%
+ {\subheadingfont{\the\version}}%
+}%
+\def\setdate{%
+ {\subheadingfont{\the\date}}%
+}%
+\def\setlink#1{\colored{\linkcolor}{#1}}%
+%
+\def\setheading#1{%
+ {\headingfont\colored{\blue}{#1}}\raise\baselineskip
+ \hbox{\special{pdf: outline 1 << /Title (#1) /Dest [
+@thispage /FitH @ypos ] >> }}}%
+%
+\def\setsubheading#1{%
+ {\subheadingfont\colored{\blue}{#1}}\raise\baselineskip
+ \hbox{\special{pdf: outline 2 << /Title (#1) /Dest [
+@thispage /FitH @ypos ] >> }}}%
+%
+% \def\link#1#2{\setbox0\hbox{\setlink{#1}}%
+% \leavevmode\special{pdf: ann width \the\wd0\space height \the\ht0\space depth \the\dp0
+% << /Type /Annot /Subtype /Link /Border [ 0 0 0 ] /A << /S /GoTo
+% /D (#2) >> >>}\box0\relax}%
+\def\link#1#2{%
+ \leavevmode\special{pdf: bann
+ << /Type /Annot /Subtype /Link /Border [ 0 0 0 ] /A << /S /GoTo /D (#2)
+>>
+>>}\setlink{#1}\special{pdf: eann}\relax}
+%
+\def\dest#1{\hbox{\raise14pt\hbox{\special{pdf:dest (#1) [ @thispage /FitH
+@ypos ]}}}}%
+%
+\def\maketitle{\noindent\settitle\hfill\setauthor\par
+ \hrule height 1.0pt\medskip
+ \noindent\setversion\hfill\setdate\vskip0.3in}%
+%
+\def\section#1{\advance\sectioncount by 1\ssectioncount0
+\vskip-\lastskip\vskip\secskip\goodbreak
+\noindent\setheading{\the\sectioncount. #1}\medskip\nobreak}%
+\def\subsection#1{\vskip-\lastskip\advance\ssectioncount by 1%
+\vskip\subsecskip\noindent
+\setsubheading{\the\sectioncount.\the\ssectioncount\
+ #1}\par\nobreak\smallskip}%
+%
+\def\display#1{\medskip\line{\quad #1\hfil}\medskip}
+\def\example{\medskip\noindent{\it Example:\quad}\nobreak}
+\def\note{\medskip\noindent{\it Note:\quad\nobreak}}
+\def\syntax{\medskip\noindent{\it Syntax:\quad}\nobreak}
+\def\description{\medskip\noindent{\it Description:\quad}\nobreak}
+%
+\def\newpage{\vfill\eject}
+%
+\def\dvipdfm{{\tt dvipdfm}}%
+%
+\title{Dvipdfm User's Manual}
+\author{Mark A. Wicks}
+\version{Version 0.12.4b}
+\date{September 19, 1999}
+\maketitle
+\section{Introduction}
+This package is a DVI (\TeX) to PDF conversion utility,
+having the following features:
+
+\beginlist
+\item{$\bullet$} {\it Support for outline entries (also called bookmarks), named destinations,
+and \link{annotations}{Annotate} (including hyperlinks, forms and widgets).} Nearly
+every Acrobat Distiller pdfmark is approximated.
+
+\item{$\bullet$} {\it Support for ``standard'' DVI specials such
+as Hyper\TeX\ (HTML), TPIC, color specials, |PSfile|, and other PostScript specials.}
+
+\item{$\bullet$} {\it Native support for inclusion of
+\link{MetaPost}{postscript} output and
+inclusion of arbitrary \link{PostScript}{postscript} files with help from an external program.}
+
+\item{$\bullet$} {\it Support for thumbnails with a little help from GhostScript to
+generate the thumbnails.}
+
+\item{$\bullet$} {\it Support for arbitrary, nested linear transformations
+of typeset material.} Any material on the page, including
+\TeX\ text, may be \link{scaled and rotated}{textxform}.
+
+\item{$\bullet$} {\it Ability to include the first page of a \link{PDF file}{pdfimage} as
+an encapsulated object along with its embedded resources such as fonts.}
+Included PDF images may be cropped by supplying a bounding box.
+Note: Currently, this doesn't work if the contents stream
+has multiple segments.
+
+\item{$\bullet$} {\it Ability to include \link{JPEG}{jpegimage} and
+PNG bitmapped images as encapsulated objects.}
+
+\item{$\bullet$} {\it An internal color stack.} A color stack allows you to change the current color, pushing the
+current color onto a stack. At any time, the original color
+can be popped from the stack. This is useful, for example, in
+headlines, that may have a different color from the current text.
+The headline macro can restore the current color without knowing
+what it is.
+
+\item{$\bullet$} {\it Support for partial font embedding and Flate compression
+to reduce file size}
+
+\item{$\bullet$} {\it Support for font reencoding to work around encodings
+that aren't fully supported by the Acrobat suite of products.}
+
+\item{$\bullet$} {\it Balanced page and destination trees.} Balancing
+these trees improves reader access speed
+on very large documents.
+
+\endlist
+
+The electronic version of the document exercises
+some of the hypertext features and serves as
+a sample input file for |dvipdfm|.
+It assumes the reader has some familiarity with the basic features
+of the Portable Document Format. The PDF specification
+is distributed by Adobe Systems\link{[1]}{pdfmanual}.
+An excellent source for information about PDF documents
+in general is \link{[2]}{pdfprimer}. Information about
+using \TeX\ to construct PDF documents (mainly using Distiller) is the
+AcroTeX home page\link{[3]}{acrotex}.
+
+Currently, the widely accepted method to generate PDF file from \TeX\
+is to use Adobe's Acrobat Distiller on a PostScript
+file produced by {\tt dvips}.
+The hyperlink features are accessed by using \TeX\ |special| primitives
+to embed pdfmarks in the PostScript produced by |dvips|.
+H\`an Th\'e Th\`an's PDF\TeX\ project is an alternative method
+of generating PDF from \TeX\ source.
+Although quite good and fairly mature, the PDF\TeX\ project
+modified \TeX\ itself to add primitives that support the PDF features.
+I prefer to work with \TeX\ unmodified, as released by Donald Knuth
+(call me a purist).
+There is an existing DVI to PDF driver called
+|dvipdf| written by Sergey Lesenko. At present, it's not widely
+available, so I haven't used it. I wrote |dvipdfm|
+mainly as an exercise to get at the features
+of PDF I was trying to use. This |dvipdfm| project demonstrates that many features
+of PDF can be accessed by using a DVI driver.
+The PDF features are activated in the driver via
+\TeX\ |special| primitives.
+
+Even though Distiller is the best method of generating PDF (and
+probably will remain so for some time) I have several reasons for
+seeking alternatives to Distiller.
+First, Distiller isn't available for my principle operating
+system---Linux.
+
+My second objection is philosophical.
+\TeX\ is a programming language.
+A DVI file is a page description consisting of very
+simple program instructions that have no branching or
+decision instructions.
+Similarly PostScript is a complete programming language,
+while PDF is a page description language consisting
+of simple program instructions
+without any branching or decision capabilities.
+\TeX\ is like PostScript (without the graphics)
+while DVI is like PDF (without the graphics or the hyperlinks).
+Creating PDF from DVI using Distiller requires converting a page description to a program,
+and converting that program back to a page description.
+To continue this analogy,
+Pdfmarks are PostScript ``escapes'' and are meant for the Distiller.
+\TeX\ |\special| primitives are \TeX\ ``escapes'' and are meant for the DVI driver.
+It seems natural to go directly from DVI to PDF, where \TeX\ replaces
+PostScript, the DVI driver replaces Distiller,
+and \TeX\ |\special| primitives replace the pdfmarks.
+
+Unfortunately, until graphics software
+begins to produce PDF content streams or encapsulated
+PDF objects, PostScript will remain the easiest
+way to include graphics in \TeX\ documents.
+I would hope that in the future, graphics programs
+will begin to produce PDF content streams or PDF objects that
+may be included using a DVI to PDF translator. Either
+of these may be easily embedded using \dvipdfm\ or a similar driver.
+
+\section{Command Line Options}
+\link{Table~1}{commandline} lists the options
+that are available on the command line.
+\par\noindent
+Note: Several flags may be specified at once:
+\example
+\begintt
+dvipdfm -ecz 9 test.dvi
+\endtt
+
+\topinsert
+{\dest{commandline}}
+\centerline{\colored{\blue}{\subheadingfont Table~1---Command line options
+recognized by |dvipdfm|}}
+\bigskip\nobreak
+\centerline{\vbox{\halign{{\tt #}\hskip
+1em\strut&\vtop{\leftskip0pt\rightskip0pt\hsize=3.5in\noindent #}\cr
+\omit\hfil\it Option\hfil&\omit\hfil \it Description \hfil\cr
+\noalign{\smallskip\begincolor\red\hrule\endcolor\smallskip}
+-c&{\it Disable color specials} Specifying this option
+forces all color commands to be ignored. This is useful for printing a color document
+on a black and white printer.\cr
+\noalign{\smallskip}
+-e&{\it Disable partial font embedding.} This may be useful
+for forms which need complete fonts, or if you run accross a PFB
+file that \dvipdfm\ cannot correctly parse.\cr
+\noalign{\smallskip}
+-f&{\it Set font map file name}. See
+the \link{Font Mapping}{fontmap} section for additional information.\cr
+\noalign{\smallskip}
+-m {\it number}&{\it Specify an additional magnification for
+the document}.\cr
+\noalign{\smallskip}
+-o {\it filename}&{\it Set the output PDF file name}.\cr
+\noalign{\smallskip}
+-p {\it papersize}&{\it Specify the output papersize.}
+Valid paper sizes are |letter|, |legal|, |ledger|, |tabloid|,
+|a4|, or |a3|. The default is |letter|. Arbitrary paper
+sizes can be specified via \TeX\ special commands,
+which is the recommended method.\cr
+\noalign{\smallskip}
+-l&{\it Landscape the document.} This is only
+meaningful for paper sizes specified on the command line.\cr
+\noalign{\smallskip}
+-s {\it page\_ranges}&{\it Select a subset of pages from the DVI file.}
+The {\it page\_ranges} specifier is a set of comma-separated page
+ranges---e.g., |dvipdfm -s 10-12,10-20|. If the first
+page in a range is empty (e.g., |dvipdfm -s -10|), it represents
+the beginning of the document. If
+the last page in a range is empty (e.g., |dvipdfm -s 10-|), it selects the end of the document.\cr
+\noalign{\smallskip}
+-t&{\it Embed thumbnail images.} The thumbnails must be generated by a
+separate program. Details are discussed \link{later}{thumbnails} in this document\cr
+\noalign{\smallskip}
+-d&{\it Delete thumbnail images after embedding.}\cr
+\noalign{\smallskip}
+-x {\it number}&{\it Specify the horizontal offset
+for the document.} The default is 1.0in.\cr
+\noalign{\smallskip}
+-y {\it number}&{\it Specify the vertical offset
+for the document.} The default is 1.0in.\cr
+\noalign{\smallskip}
+-z {\it number}&{\it Specify the compression level.}
+Valid compression levels range from 0 to 9, with 0 indicating
+no compression. A compression level of 9 is the default.\cr
+\noalign{\smallskip}
+-v&{\it Be verbose.} Among other things, dvipdfm
+will display complete file names as various files are opened.\cr
+\noalign{\smallskip}
+-vv&{\it Be more verbose.}\cr}}}
+\endinsert
+
+\section{General Concepts and Syntax for TeX Specials}
+Each \TeX\ |\special|
+represents a separate command to the \dvipdfm\
+driver. Each |special| must begin with ``|pdf:|''
+to identify that ||special|| as a command for the \dvipdfm\ driver.
+A |\special| beginning with any other characters is ignored
+by the driver. Leading spaces are ignored. The characters ``|pdf:|''
+are immediately followed by a \dvipdfm\ command. These commands
+are documented in \hbox{Sections~3--6}.
+
+\subsection{PDF Object Syntax and Variable Expansion}
+With one exception, the syntax used for PDF objects
+within each |\special| specials follows
+the PDF specification.
+The one exception is variable expansion.
+In the syntax specifications that follow, {\it PDF\_Object}
+means that an arbitary PDF object is expected. Similarly
+{\it PDF\_Array} indicates that a PDF array is expected, {\it PDF\_Dict}
+inciates that a PDF dictionary is expected, etc.
+See the \link{reference manual}{pdfmanual}\
+for a complete list of PDF object types.
+
+The single extension implemented in this driver
+allows a symbol name of the
+form |@|{\it name} whereever any PDF object is expected.
+The {\it name} may contain any characters allowed
+in a PDF name.
+A user-defined symbol beginning with |@| expands to an indirect
+reference to the user-defined PDF object. This feature replaces
+the |{|{\it name}|}| syntax used with pdfmarks.
+In addition to the user-defined names, some names
+are defined by the driver.
+The driver defined variables are for
+referencing objects such as the current page, future pages,
+or the current location on the current page.
+The driver defined variables appear in \link{Table~2}{drivervariables}.
+\topinsert
+{\dest{drivervariables}}
+\centerline{\colored{\blue}{\subheadingfont Table~2---List of driver
+defined variables}}
+\bigskip\nobreak
+\centerline{\vbox{\halign{{\tt #}\hskip
+1em&\vtop{\leftskip0pt\rightskip0pt\hsize=3.0in\noindent #}\cr
+\omit\hfil\it Variable\hfil&\omit\hfil \it Description \hfil\cr
+\noalign{\smallskip\begincolor\red\hrule\endcolor\smallskip}
+@catalog&A reference to the document's catalog.\cr
+\noalign{\smallskip}
+@names&A reference to the document's /Names dictionary.\cr
+\noalign{\smallskip}
+@pages&A reference to the root of the document's /Pages tree.\cr
+\noalign{\smallskip}
+@resources&A reference to the current page resource dictionary.\cr
+\noalign{\smallskip}
+@thispage&A reference to the current page.\cr
+\noalign{\smallskip}
+@page{\it n}&A reference to page {\it n}.\cr
+\noalign{\smallskip}
+@nextpage&A reference to the page following |@thispage|.\cr
+\noalign{\smallskip}
+@prevpage&A reference to the page preceding |@thispage|.\cr
+\noalign{\smallskip}
+@ypos&A {\it number} representing the current vertical position in units of PDF points.\cr
+\noalign{\smallskip}
+@xpos&A {\it number} representing the current horizontal position in units of PDF points.\cr
+}}}
+\endinsert
+
+In the syntax specifications that follow, several
+standard conventions are followed. Terminal
+characters that appear in the command
+are typeset in the |\tt| font, e.g., |object|.
+Nonterminal symbols are typeset in italics.
+Optional parameters are surrounded by brackets, e.g.,
+[{\it optional\_argument}]. An item followed
+by~``{*}'' represents an item that may appear
+zero or more times. An item followed by~``{+}''
+represents a required item that may appear multiple times.
+
+\subsection{Dimensions and transformations}
+Interaction with the |dvipdfm| driver consists
+of short commands with a few arguments delimited by white space.
+Typically the arguments are PDF objects.
+Two exceptions are dimension specifications and transformations.
+
+In the \TeX\ style, a dimension specification consists of one of the keywords
+|width|, |height|, or |depth| followed by a dimension
+consisting of a numerical value, followed by a unit for the dimension. The
+unit will typically be |pt| (which represents a \TeX\ point, not a
+PDf point) but |mm|, |cm| and |in| are also allowed.
+If the document is magnified, the ``true'' dimensions |truept|,
+|truemm|, |truecm|, and |truein| may be used. The notation
+{\it dimension\/} in a syntax description means a dimension is expected.
+
+A transformation consists of one of the keywords |scale|, |xscale|,
+|yscale|, or |rotate| followed by a numerical value. In the
+case of |rotate| the value is the rotation angle in degrees.
+The notation
+{\it transformation} means a transformation is expected.
+In the case of included images originating from
+PDF/PostScript files, a clipping or bounding box may be specified
+as part of the ``transformation.'' The bounding
+box specification consists of the keyword |bbox|
+followed by four numerical values, which are
+the standard PostScript |llx|, |lly|, |urx|, and |ury|
+coordinates of the bounding box.
+
+\section{Document Construction Commands}
+All commands are executed via \TeX\ |\special| primitives
+prefixed with the characters ``|pdf:|''.
+\example
+\begintt
+\special{ pdf: out 1 << /Title (Introduction)
+ /Dest [ 1 0 R /FitH 234 ] >>
+\endtt
+
+\dest{Annotate}
+\subsection{Annotate}
+\hbox to 0pt{\hskip-1.0in\special{pdf: ann width 3.0in height 36pt << /Type /Annot /Subtype /Text
+/Contents (This is a /Text Annotation that looks like a sticky note.) >>}\hss}
+\syntax
+{\tt annotate} [{\tt @}{\it name}] {\it dimension}+ {\it PDF\_dictionary}
+\description
+The |annotate| (|annot| or |ann|) command defines an annotation.
+Annotations are typically used for
+notes, hyperlinks, forms, or widgets.
+The parameter {\it name} is an optional alphanumeric identifier
+and {\it PDF\_dictionary} is a valid PDF dictionary after variable expansion.
+If {\tt @}{\it name} is specified, it may be used in
+other PDF objects to refer to this annotation.
+One or more {\it dimension} parameters are required
+and each consists of the keyword
+{\tt height}, {\tt width}, or {\tt depth} followed
+by an appropriate length, specified as per \TeX\null.
+The |width| must be nonzero and either the |height| or |depth|
+must be nonzero.
+Each length is a number followed by a unit, such as {\tt pt},
+{\tt in}, or {\tt cm}. Since these values
+would typically be entered by \TeX, a {\tt pt}
+is a \TeX\ point, not a PDF point.
+
+\example The annotation in this subsection
+was typeset with
+\begintt
+\special{pdf: ann width 3.0in height 36pt
+ << /Type /Annot /Subtype /Text
+ /Contents (This is a /Text Annotation
+ that looks like a sticky note.) >>}
+\endtt
+
+\subsection{Begin Annotation}
+\syntax
+{\tt beginann} {\it PDF\_dictionary}
+\description
+The |beginann| (|bann| or |bannot|) command begins a breakable annotation.
+Dvipdfm tries to determine the boundaries of the annotation automatically.
+Such an annotation may be broken over several lines (or even several pages).
+Unlike |annot|, the annotation may be not be referred to by name later,
+since there may be more than once instances of the annotation.
+The |beginann| command needs not dimension because |dvipdfm|
+computes the correct bounding box on the fly.
+
+Note: Link breaking is easily fooled at page breaks. If you have problems
+with the header or footer wanting to become part of the link, you can
+insert a |nolink| command at the beginning of the footer and a |link|
+command at the end of the footer.
+
+\subsection{End Annotation}
+\syntax
+{\tt endann}
+\description
+The |endann| (|eann| or |eannot|) terminates a breakable annotation.
+
+\subsection{Link}
+{\tt link}
+\description
+The |link| command instructs the link breaking algorithm to resume its
+operation after a |nolink| command.
+
+\subsection{Nolink}
+{\tt nolink}
+\description
+The |nolink| command instructs the link breaking algorithm to suspend
+it operation. This is only required if there is material inserted
+on the page in the {\it middle} of a link. For example, when a link
+is broken at the end of a page, the header and footer are inserted
+in the middle of the link, but are not part of the link. Material
+that is inserted between a |nolink| and |link| will not become
+part of the link. The |nolink| and |link| escapes are not necessary
+with the standard LaTeX header and footer lines, but may become necessary
+if these are changed.
+
+\subsection{Dest}
+\syntax
+{\tt dest} {\it PDF\_String} {\it PDF\_Dest}
+\description
+The |dest| command defines a named destination.
+The {\it PDF\_String} is a PDF string naming
+the destination. This string may be used in the destination
+fields of annotations and outline entries to refer to
+this destination. {\it PDF\_Dest} is a PDF
+destination object (typically an array).
+\example
+\begintt
+\special{pdf: dest (listofreferences) [ @thispage /FitH @ypos ]}
+\endtt
+
+\subsection{Docinfo}
+\syntax
+{\tt docinfo} {\it PDF\_dictionary}
+\description
+The |docinfo| command adds the keys in the specified dictionary to the
+document's |/Info| dictionary. All keys are optional, but may include
+the keys |/Author|, |/Title|, |/Keywords|, |/Subject|,
+and |/Creator|.
+\example
+\begintt
+\special{pdf: docinfo << /Author (Mark A. Wicks)
+ /Title (This Document) >>}
+\endtt
+
+\subsection{Docview}
+\syntax
+{\tt docview} {\it PDF\_dictionary}
+\description
+The |docview| command adds the keys in the specified dictionary to the
+document's |/Catalog| dictionary. All keys are optional, but may include
+the keys |/PageMode|,
+|/URI|, |/OpenAction|, |/AA|
+and |/ViewerPreferences|. See the PDF Reference Manual
+for documentation of these keys and additional keys.
+\example
+\begintt
+\special{pdf: docview << /PageMode /UseThumbs >> }
+\endtt
+
+
+\subsection{Object}
+\syntax
+{\tt object} [@{\it name}] {\it PDF\_Object}
+\description
+The |object| (also |obj|) command creates a
+PDF object. The parameter {\it PDF\_Object} is any valid PDF object. The
+parameter {\it name} may be used to provide an indirect reference
+to this object within other
+objects. It will be expanded anywhere within
+a {\tt special} where a PDF object is
+expected. Typically {\it object} is an array
+or dictionary. It may be an empty array or
+dictionary that can be constructed dynamically via
+the {\tt put} command.
+\example
+\begintt
+\special{pdf: object @mydict << /Firstpage @thispage >>}
+\endtt
+
+\subsection{Out}
+\syntax
+{\tt out} {\it number} {\it PDF\_dictionary}
+
+\description
+The |out| (also |outline|) command adds an outline (also called a ``bookmark'') entry
+to the document.
+The parameter {\it level\/} is an integer representing the
+level of the outline entry (beginning with 1) and
+{\it PDF\_dictionary\/} must contain
+the two keys {\tt /Title} and either {\tt /Dest} or {\tt /A}.
+It may also contain the {\tt /AA} key. These keys are documented
+in the PDF Reference Manual.
+\example
+\begintt
+out 1 << /Title (Section 1) /Dest [ @thispage /FitH @ypos ] >>
+\endtt
+which may be followed by
+\begintt
+out 2 << /Title (Section 1.1) /Dest [ @thispage /FitH @ypos ] >>
+\endtt
+\note
+You may not skip levels. A level~2 outline entry
+must follow a level~1 outline
+entry. A level~3 outline entry must follow a level~2 outline
+and cannot immediately follow a level 1 outline entry.
+
+\subsection{Pagesize}
+\syntax
+{\tt pagesize} {\it dimension}+
+\description
+The |pagesize| command specifies the document's physical
+paper size. The |pagesize| command must be specified on
+the first page and must precede the first annotation
+or background color specification on the page.
+In other words, it should occur as close to the
+beginning of the document as possible.
+\example
+\begintt
+pagesize width 11.0truein height 8.5truein
+\endtt
+
+\subsection{Put}
+\syntax
+\beginlist
+{\tt put} @{\it name} {\it PDF\_Object}+
+\endlist
+or
+\beginlist
+{\tt put} @{\it name} {\it PDF\_Dictionary}
+\endlist
+\description
+The |put| command modifies an existing PDF object created with |obj|,
+or one of the following internally defined objects: |@catalog|,
+|@names|, |@pages|, |@thispage|, or |@resources|.
+The first form is used when @{\it name} is an array. The second
+form is used when @{\tt name} is a dictionary. More than
+one object may be added to an array at once.
+All keys in {\it PDF\_Dictionary}
+are added to the dictionary represented by @{\it name}.
+\example
+\begintt
+\special{pdf: put @mydict << /Nextpage @thispage >>}
+\endtt
+
+\subsection{Thread}
+\syntax
+{\tt thread} {\tt @}{\it name} {\it dimension}+ [ {\it PDF\_dictionary} ]
+
+\description
+The |thread| (or |art|) command adds a bead to an article.
+An article is a collection of boxed regions in the document that should be
+read consecutively.
+Each bead using the same {\it name} belongs to the same article.
+The {\it name} parameter is required. The {\it dimension} parameter
+defined the rectangular area belonging to the bead in
+the same manner as for |annot|.
+The optional PDF dictionary
+should supplied on one of the beads. Its keys are
+similar to the |/Info| dictionary accessed via the |docinfo| command
+and would typically include the |/Title| and |/Author| keys.
+Keys in the dictionary may be overwritten by subsequent {\tt thread} commands.
+\example
+\begintt
+\special {pdf: thread @somearticle << /Title (Some title)
+ /Author (Me) >>}
+\endtt
+
+\subsection{Close}
+\syntax
+{\tt close} @{\it name}
+\description
+The |close| writes the named PDF object created with |obj| to the PDF file.
+No further |put| commands may be executed for this object.
+The object may continue to be referenced using @{\it name}
+indefinitely. If the object is never closed, it will
+be closed when |dvipdfm| finishes processing the document.
+
+\section{Form XObjects}
+The PDF specification allows an object to be stored once
+and displayed at multiple locations throughout the document.
+The following commands give access to this facility.
+
+\subsection{Beginxobj}
+\syntax
+{\tt beginxobj} @{\it name} {\it dimension}+
+\description
+The |beginxobj| (or |bxobj|) command begins the definition of
+a Form XObject. All material typeset between the
+|beginxobj| and |endxobj| commands will be captured
+into the XObject. The material can be displayed later
+at an arbitrary location with the |usexobj| command.
+The {\it name} may be used to refer to the object later,
+either via the |usexobj| command or as an indirect
+reference to the XObject if {\it name} is
+used within the context of a {\it PDF\_Object}..
+The required {\it dimension} identifies the extent
+(i.e., bounding box) of the area to be captured.
+It is specified in the same way as for |annot|.
+
+The material will not display during the object definition.
+In other words, if you are typsetting with \TeX\ you
+should place the XObject in a box of dimension 0 so
+you don't leave a white space hole where the object was
+defined.
+\example
+\begintt
+bxobj @myform width 2.0in height 24pt
+\endtt
+
+\subsection{Endxobj}
+\syntax
+{\tt endxobj}
+\description
+The |endxobj| (or |exobj|) command ends the previous
+|beginxobj| definition. Note that XObject definitions
+may not be nested. XObjects can be {\it used} within
+other XObjects, however.
+\example
+\begintt
+exobj
+\endtt
+
+\subsection{Usexobj}
+\syntax
+{\tt usexobj} @{\it name}
+\description
+The |usexobj| (or |uxobj|) command displays the
+form XObject previously defined and
+associated with {\it name}.
+\example
+\begintt
+uxobj @myform
+\endtt
+
+\section{Text Transformation Commands}
+The commands in this section deal with transformation
+of arbitrary material, which may include
+material typeset by \TeX. These
+may also be used on included graphics images
+if the commands in Section~8 won't do the job.
+
+\subsection{BeginTransform}
+\syntax
+{\tt begintransform} {\it transformation}+
+
+\description
+The |begintransform| (|btrans| or |bt|) applies
+the specified transformation to all subsequent text.
+The scaling is applied first, followed by the rotation.
+The reference point of a box following
+the |\special| remains fixed. Such transformations
+may be nested to perform rotations within rotated text, for exmaple.
+
+\example
+\begintt
+\special{pdf: bt rotate 90 xscale 2.0 }
+\endtt
+
+\subsection{BeginTransform}
+\syntax
+{\tt endtransform}
+\description
+The |endtransform| (|etrans| or |et|) concludes
+the action of the immediately preceding |begintransform|
+command. All transformations must be closed
+on the same page. The driver will close
+any pending unclosed transformations at the
+end of the page and issue a warning message.
+All material to be transformed
+should probably be enclosed in a single box
+to prevent any break.
+\example
+\begintt
+\special{pdf: et}
+\endtt
+
+
+\section{Color Commands}
+The commands in this section deal with manipulation of the color
+stack.
+
+\subsection{Setcolor}
+\syntax
+{\tt setcolor} {\it PDF\_Number$\vert$\it PDF\_Array}
+\description
+The |setcolor| (|scolor| or |sc|) command uses its
+argument to set the default color for future marking operators.
+The current color is replaced and may be retrieved
+only by a subsequent |setcolor| command. The argument
+may be a single number, which is interpreted as a grayscale
+value; a three element array, which is interpreted as an RGB
+color space coordinate; or a four element array, which
+is interpreted as a CMYK color space coordinate.
+\example
+\begintt
+\special{ pdf: sc [ 1 0 0 ] }
+\endtt
+
+\subsection{Begincolor}
+\syntax
+{\tt begincolor} {\it PDF\_Number$\vert$\it PDF\_Array}
+\description
+The |begincolor| (|bcolor| or |bc|) command uses its
+argument to set the default color for future marking operators.
+The current color is pushed on the color stack. The argument
+may be a single number, which is interpreted as a grayscale
+value; a three element array, which is interpreted as an RGB
+color space coordinate; or a four element array, which
+is interpreted as a CMYK color space coordinate.
+\example
+\begintt
+\special{ pdf: bc [ 1 0 0 ] }
+\endtt
+
+\subsection{Endcolor}
+\syntax
+{\tt endcolor}
+\description
+The |endcolor| (|ecolor| or |ec|)
+changes the default color to
+match the color on the top
+of the stack. It removes
+the color from the stack.
+\example
+\begintt
+\special{ pdf: ec }
+\endtt
+
+\subsection{Bgcolor}
+\syntax
+{\tt bgcolor} {\it PDF\_Number$\vert$\it PDF\_Array}
+\description
+The |bgcolor| (|bbc| or |bgc|) command uses the value
+of its argument to set the default color for the page
+background. The interpretation
+fo the argument is the same as for the |begincolor| command.
+The stack is not involved here. There is no way
+to go back to the previous background color.
+\example
+\begintt
+\special{ pdf: bc [ 1 0 0 ] }
+\endtt
+
+\section{Image Commands}
+The commands in this section deal with embedding
+graphics into your PDF document. The present
+driver supports PDF, PNG, and JPEG graphics inclusion.
+
+\subsection{Epdf}
+\syntax
+{\tt epdf} [|@|{\it name}] [{\it dimension}$\vert${\it transformation}]* {\it PDF\_String}
+
+\description
+The {\tt epdf} command ``encapsulates'' the first page of a PDF
+file named by {\it PDF\_String}
+into a PDF XObject. The resulting XObject is drawn
+with the lower left corner at the current location of the page.
+The optional @{\it name} parameter may be used
+to reference this object within other objects. If a
+{\it dimension} is supplied, the object will be scaled to fit
+that dimension. A {\it transformation} consists of one of the keywords
+|scale|, |xscale|, |yscale|, or |rotate|
+followed by a number representing
+the scaling factor or rotation angle in degrees. Both {\it transformation} and {\it dimension}
+parameters can be supplied as long as they are not logically
+inconsistent.
+
+Note: The object is stored as an XObject and can be redisplayed later by using the
+|usexobj| function and specifying {\it name}.
+
+\example
+\begintt
+\special{pdf:epdf yscale 0.50 width 4.0in
+ rotate 45 (circuit.pdf)}
+\endtt
+
+\subsection{Image}
+\syntax
+{\tt image} [@{\it name}] [{\it dimension} $\vert$ {\it transformation}]* {\it PDF\_String}
+
+\description
+The {\tt image} command ``encapsulates'' an image
+taken from the file named by {\it PDF\_String}.
+This command functions just like |epdf|. Value
+image types may be PDF, JPEG, or PNG images.
+This special will eventually replace the |epdf| special.
+
+Note: The object is stored as an XObject and can be redisplayed later by using the
+|usexobj| function and specifying {\it name}.
+
+\section{Raw Page Marking Commands}
+The commands in this section deal with embedding
+raw PDF graphics operators into your PDF document.
+
+\subsection{Bop}
+\syntax
+{\tt bop} {\it stream}
+\description
+The |bop| command specifies a marking
+stream to be generated at the top of each page.
+The parameter {\it stream} is any sequence
+of marking operators and is added to the page's content stream.
+The stream is applied {\it to all pages} regardless
+of where it appears in the document.
+\example The two horizontal lines appearing
+at the top of each page in this document
+were set with
+\begintt
+\special {pdf: bop q 0 w 0.8 0.5 0 RG
+ 54 740 m 504 740 l 504 740.25 l 54 740.25 l b
+ 36 760 m 504 760 l 504 760.25 l 36 760.25 l b Q }
+\endtt
+\special {pdf: bop q 0 w 0.8 0.5 0 RG
+ 54 740 m 504 740 l 504 740.25 l 54 740.25 l b
+ 36 760 m 504 760 l 504 760.25 l 36 760.25 l b Q }
+
+\subsection{Content}
+\syntax
+{\tt content} {\it stream}
+\description
+The |content| command specifies a marking
+stream to be added to the current page at
+the current location. While it
+is possible to change the color
+state, etc., with this command, it is
+not advised. Use the color management
+commands to change colors.
+
+
+\subsection{Eop}
+\syntax
+\beginlist
+{\tt eop} {\it stream}
+\endlist
+\description
+The {\tt eop} specifies a marking stream to be generated at the end
+of each page. The parameter {\it stream} is any sequence
+of marking operators and is added to the page's content stream.
+The stream is applied {\it to all pages} regardless
+of where it appears in the document.
+
+\section{Graphics Examples}
+
+The examples in this section illustrate some of the transformation
+and image inclusion capabilities of \dvipdfm.
+
+\dest{textxform}
+\subsection{Text Transformation}
+Tables with slanted entries are possible as shown
+in \link{Table~3}{rotatedtable}. This table was achieved using
+various ``|bt rotate 35|'' commands.
+
+The following line of text was done with nested
+combinations of ``|bt rotate 10|'' and ``|bt rotate -10|''.
+
+\def\up#1{\special{pdf:bt rotate 10}\hbox{#1}}
+\def\down#1{\special{pdf:bt rotate -10}\hbox{#1}}
+You \down{can} nest \down{the} \up{text}
+trans\up{form}ation \up{capa}\down{bili}ties \down{to}
+achieve \down{effects} \down{like}
+{this}.
+\special{pdf:et}\special{pdf:et}\special{pdf:et}\special{pdf:et}
+\special{pdf:et}\special{pdf:et}\special{pdf:et}\special{pdf:et}
+\special{pdf:et}
+\vskip 0.5in
+
+
+\def\rvr{\colored{\red}{\vrule}}\def\entry#1{\special{pdf:bt rotate 35}%
+{\vbox to 0pt{\vss\hbox{\quad\colored{\blue}{#1}\quad}\vskip 1pt\colored{\red}{\hrule}}\special{pdf:et}}}
+\topinsert
+\dest{rotatedtable}
+\bigskip
+\centerline{\colored{\blue}{\subheadingfont Table 3---Example of rotated
+text set in Computer Modern Roman}}
+\bigskip
+\centerline{\vbox to 0.45in{\vss\offinterlineskip\halign{#&#&#&#&#&#\cr
+\entry{1994}&
+\entry{1995}&
+\entry{1996}&
+\entry{1997}&
+\entry{1998}&
+\entry{1999}\cr
+\noalign{\colored{\red}{\hrule}}
+\strut\rvr&\rvr&\rvr&\rvr&\rvr&\rvr\crcr}}}
+\bigskip
+\endinsert
+
+\dest{imageinclude}
+\subsection{Image Inclusion}
+
+The image in \link{Figure~1}{jpegimage} was included from a JPEG file.
+The image shown in \link{Figure~2}{rotatedimage} comes from the same file,
+but is loaded at a 50\% scale and a 45$^\circ$ rotation.
+
+\topinsert
+\dest{jpegimage}
+\bigskip
+\centerline{\reserve{1.50in}{2.05in}{pdf: image (mwicks.jpeg)}}
+\medskip
+\centerline{\subheadingfont
+\begincolor{\blue}Figure~1---A JPEG image of the author.\endcolor}
+\bigskip
+\endinsert
+
+\topinsert
+\dest{rotatedimage}
+\bigskip
+\centerline{\reserve{0.75in}{1.25in}{pdf: image rotate 45 scale 0.50 (mwicks.jpeg)}}
+\medskip
+\centerline{\subheadingfont
+\begincolor{\blue}Figure~2---Image of the author scaled by 0.5 and rotated
+by 45$^\circ$.%
+\endcolor}
+\bigskip
+\endinsert
+
+By default, JPEG files are included
+at a resolution of 100dpi so if you know the pixel size
+of the image, you know how much space to reserve.
+Any \TeX\ magnification is applied to the image
+in addition to any scaling defined in the |\special|.
+For example, this document sets |\magnification=\magstephalf|,
+so the images are actually scaled by 1.095. The first
+image in this section has a printed width of 1.643in
+even though 1.50in was specified in the |\special|.
+
+Several command line utilities exist that read
+the pixel dimensions of a JPEG file. For PDF files,
+you can |grep| on |/MediaBox| to get an indication
+of the image size. The |/MediaBox| dimensions are
+in PDF points.
+
+The image in \link{Figure~3}{pdfimage} was produced by embedding a PDF file
+using |epdf|.
+
+\topinsert
+\dest{pdfimage}
+\centerline{\reserve{2.41in}{2.6in}{pdf: epdf width 2.41in (transistor.pdf)}}
+\medskip\centerline{\subheadingfont
+\begincolor{\blue}Figure~3---An embedded PDF object.
+\endcolor}
+\endinsert
+Notice that any resources required for the object
+are also embedded. In this case, the Times Roman font
+resource was embedded along with the content stream.
+
+\dest{thumbnails}\section{Thumbnails}
+Thumbnails can be inserted automatically by |dvipdfm|
+using the |-t| command line option. However, |dvipdfm|
+is unable to generate the thumbnails by itself. This
+must be done by some other program such as GhostScript.
+The typical two-pass process to include thumbnails would be
+\item{1.}
+Run |dvipdfm| without the |-t| option (probably
+using command line options optimized for speed and not space)
+\item{2.}
+Run GhostScript to generate the thumbnail images of
+each page.
+\item{3.}
+Run |dvipdfm| with the |-t| or |-dt| option.
+
+The |dvipdfm| distribution includes a sample
+shell script called |dvipdft| which is a wrapper
+for |dvipdfm| that generates thumbnails.
+
+|Dvipdfm| searches for the thumbnail images
+in the directory specified by the TMP or TEMP
+environment variables, or in the current directory.
+The thumbnails must have the same base name as the PDF output
+file with an extension indicating the number of the page.
+For example, to create a thumbnailed document named |foo.pdf|
+you would need to generate thumbnail images in files named
+|foo.1|, |foo.2|, etc.
+
+\dest{fontmap}\section{Font Mapping}
+\TeX\ font names can be
+mapped into arbitrary physical (PostScript) font names via
+the map file named |t1fonts.map|. The file is
+similar to the |psfonts.map| file used by |dvips|
+and other drivers. Each line in the
+file consists of one to three fields delimited
+by white space, followed by options that apply to that font.
+The complete list of recognized options
+appears in \link{Table~4}{options}.
+
+Sample map file lines are\nobreak
+\begintt
+cmr10 ot1 -r
+ptmro8r 8r Times-Roman -s 0.167
+pncbo8r 8r pncb8a -s 0.167
+\endtt
+
+The first field of each line
+is the \TeX\ font name. The second
+field, which is optional, is the encoding name (|.enc| will
+be appended to this name, if necessary
+to locate an encoding file). The
+encoding files have the same format
+as those used for |dvips|.
+The third optional field is {\it either} the PostScript font
+name (if one of the standard PostScript fonts) {\it or}
+the file name of a Type~1 binary font file (PFB file).
+The {}.pfb extension is assumed by the program.
+three fields. If the encoding field is unspecified,
+|dvipdfm| used the default encoding supplied with
+the Type~1 font. If the name field is unspecified,
+|dvipdfm| looks for a Type~1 binary font file
+having the same name as the \TeX\ font name.
+If there is {\it no} line in the map file,
+the behavior is as if a line was specified
+without the second or third field.
+The keywords |default| or |none| are
+recognized in the encoding field so that
+a third field may be specified while still
+having default behavior in the second field.
+
+Currently, three options may be specified for each font
+as shown in \link{Table~4}{options}.
+\topinsert
+{\dest{options}}
+\centerline{\colored{\blue}{\subheadingfont Table~4---Font options
+recognized by |dvipdfm| in the font map file}}
+\bigskip\nobreak
+\centerline{\vbox{\halign{{\tt #}\hskip
+1em\strut&\vtop{\leftskip0pt\rightskip0pt\hsize=3.5in\noindent #}\cr
+\omit\hfil\it Option\hfil&\omit\hfil \it Description \hfil\cr
+\noalign{\smallskip\begincolor\red\hrule\endcolor\smallskip}
+-r&{\it Remap the font to eliminate control characters.} This
+option attempts to work around bugs in Acrobat reader that seem
+to be triggered by characters that are encoded in certain positions.
+Unfortunately, standard \TeX encodings normally use these positions.\cr
+\noalign{\smallskip}
+-e {\it number}&{\it Extend the font horizontally, multiplying the natural
+width of the font by the specified number.} This is useful
+for generating new fonts by widening existing fonts.\cr
+\noalign{\smallskip}
+-s {\it number}&{\it Slant the font using the specified number}.
+This option is useful for building a slanted fonts from a font
+for which there is no slanted font.\cr}}}
+\endinsert
+
+\section{Configuration file}
+{\dest{configuration}}Dvipdfm reads default command line options, such
+as paper size, from a configuration
+file contained in the |dvipdfm| directory of the TeX tree.
+The format of this file is similar to the |dvips| file configuration
+file format. Each line consists of a single command line switch
+followed by any arguments. See the configuration file supplied
+with the |dvipdfm| distribution for examples.
+
+\section{Including PostScript graphics images}
+{\dest{postscript}}Dvipdfm provides support for illustrations
+contained in external PostScript files.
+It recognizes two distinct kinds of PostScript files---those
+created by MetaPost and everything else.
+
+MetaPost
+files output only a subset of PostScript and
+are interpreted {\it natively} by |dvipdfm|
+with its own internal minimal PostScript interpreter.
+Also, MetaPost output files contain \TeX\ font information in their header
+comments, so that they can be easily integrated with \TeX\ by DVI
+drivers. Dvipdfm recognizes this font information and uses the \TeX\
+fonts defined in the MetaPost header.
+
+
+All other PostScript files require an external
+program to convert the image to PDF format before
+|dvipdfm| can include the image.
+The freely available GhostScript is capabable of performing this conversion
+for most images.
+
+The user must specify the command line required
+to invoke an external program to perform this conversion.
+The command line required to invoke the conversion
+program is specified using the |-D| command
+line (or configuration file) option. The string passed to the |-D| command
+line option is a C-style string that is parsed by |dvipdfm|. Within the string,
+expansions are performed as described in \link{Table~5}{expansion}.
+For example, to use GhostScript, one might use the
+command line
+
+\bigskip
+
+{\tt -D "cat \%i \vrule\ gs -q -sDEVICE=pdfwrite -sOutputFile=\%o - -c quit" }
+
+
+\topinsert
+{\dest{expansion}}
+\centerline{\colored{\blue}{\subheadingfont Table~5---Expansions
+performed in the -D string.}}
+\bigskip\nobreak
+\centerline{\vbox{\halign{{\hfil\tt #\hfil}\hskip
+1em\strut&\vtop{\leftskip0pt\rightskip0pt\hsize=3.5in\noindent #}\cr
+\omit\hfil\it Variable\hfil&\omit\hfil \it Description \hfil\cr
+\noalign{\smallskip\begincolor\red\hrule\endcolor\smallskip}
+\%i&{\it Expanded to the full path of the EPS file to be included}\cr
+\noalign{\smallskip}
+\%o&{\it Expanded to the full path name of the PDF file to be
+generated}. The command line must be able to create a file
+with the name supplied by dvipdfm.\cr
+\noalign{\smallskip}
+\%b&{\it Expanded to the ``basename'' of the EPS file that is being included.}
+The ``basename'' is the full path of the EPS file with the
+last ``.'' and any trailing name extension removed.\cr
+}}}
+\endinsert
+
+\section{Compatibility with other DVI drivers}
+Compatibility with other DVI drivers is achieved
+by support for the following ``standard'' special calls.
+Many legacy DVI files can be processed by |dvipdfm|,
+so long as they use fairly standard special commands.
+For example, |dvipdfm| can process DVI files generated
+that use the
+|\color|, |\rotatebox|, and |\includegraphics| macros
+from the standard La\TeX\ Graphics bundle even if |dvips| was the target DVI driver,
+e.g.,
+
+\begintt
+\usepackage[dvips]{graphics}
+\usepackage[dvips]{color}
+\endtt
+
+Specifically, |dvipdfm| understands the following standard special commands:
+
+\beginlist
+\item{$\bullet$} The TPIC specials.
+
+\item{$\bullet$} The HyperTeX (HTML) hyperlink specials.
+
+\item{$\bullet$} The ``color'' specials supported by |dvips| and
+other drivers.
+
+\item{$\bullet$} The ``PSfile'' and ``plotfile'' specials for PS/EPS file inclusion
+supported by |dvips| and other drivers. Dvipdfm uses a user-specified
+external program to convert the PostScript file to PDF format
+before including it.
+
+\item{$\bullet$} The raw PostScript ``ps:'' special supported by |dvips| and
+other drivers. Only a few PostScript operators are supported;
+|dvipdfm| does not include a complete PostScript interpreter.
+Complex PostScript code, such as that embedded by the PSTricks
+package, is not supported.
+\endlist
+
+\section{LaTeX Support and Ebb}
+Support for the La\TeX\ graphics bundle and |hyperref|
+are available. A driver file named |dvipdfm.def|
+is distributed with the standard La\TeX
+graphics bundle. The latest version
+of the |dvipdfm.def| file is supplied
+with the |dvipdfm| distribution.
+The file required for |hyperref|
+support is called |hdvipdfm.def|.
+
+To facilitate La\TeX\ support, I distribute a companion program
+called |ebb|, which extracts bounding boxes from graphics files. If
+you want to include JPEG, PNG, or PDF files in your document, you can run
+|ebb| on the JPEG, PNG, or PDF file to create the |.bb| files.
+The bounding box file will be similarly named with an extension of |.bb|.
+For DOS 8+3 compatibility, an original file name extension
+of |.jpg|, |.png|, or |.pdf| is removed before creating the name of
+the |.bb| file. An extension of |.jpeg| is also recognized and similarly removed.
+
+\newpage
+\section{References}
+\tolerance=1000\hbadness=1000
+\bibitem\dest{pdfmanual}{\it Portable Document
+Format Reference Manual}, Version 1.2, Adobe Systems Incorporated, 1996.
+Available at the following URL: {\tt http://www.adobe.com}.
+
+\bibitem\dest{pdfprimer}Thomas Merz,
+{\it Web Publishing with Acrobat/PDF},
+Springer-Verlag, 1997, ISBN 3-540-63762-1. Chapter~6 of this book is available
+at the URL: |http://http://www.ifconnection.de/~tm|.
+
+\bibitem\dest{acrotex}D. P. Story, {\it AcroTeX}, The AcroTeX home page
+is located at the URL: |http://www.math.uakron.edu/~dpstory/acrotex.html|.
+
+\bye