% $Header$ % \special{ pdf: pagesize width 8.5truein height 11.0truein} \special{ pdf: docview <>}% \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