| 1 |
% $Header$ |
| 2 |
% \special{ pdf: pagesize width 8.5truein height 11.0truein} |
| 3 |
\special{ pdf: docview <</PageMode /UseOutlines>>}% |
| 4 |
\catcode`\ =11\def\space{ }\catcode`\ =10 |
| 5 |
% Page layout |
| 6 |
\tolerance=2000 |
| 7 |
\magnification\magstephalf |
| 8 |
\advance\hoffset by 0.5truein |
| 9 |
\advance\voffset by 0.5truein |
| 10 |
\advance\hsize by -1.0truein |
| 11 |
\advance\vsize by -1.0truein |
| 12 |
\def\makefootline{\baselineskip=40pt\line{\the\footline}} |
| 13 |
% |
| 14 |
% Some helpful symbols |
| 15 |
\def\rtm{{\font\r=cmss10 at 4pt |
| 16 |
\font\c=cmsy5 |
| 17 |
\setbox0\hbox{\c\char13}\skip0\wd0\box0\setbox0\hbox{\r R}\advance\skip0 by |
| 18 |
\wd0\kern-0.5\skip0\box0}} |
| 19 |
\def\tm{{\font\r=cmss10 at 4pt \hbox{\r TM}}}% |
| 20 |
% |
| 21 |
% Verbatim mode borrowed from manmac macros |
| 22 |
% |
| 23 |
\outer\def\begindisplay{\obeylines\startdisplay} |
| 24 |
{\obeylines\gdef\startdisplay#1 |
| 25 |
{\catcode`\^^M=5$$#1\halign\bgroup\indent##\hfil&&\qquad##\hfil\cr}} |
| 26 |
\outer\def\enddisplay{\crcr\egroup$$} |
| 27 |
\chardef\other=12 |
| 28 |
\def\ttverbatim{\begingroup \catcode`\\=\other \catcode`\{=\other |
| 29 |
\catcode`\}=\other \catcode`\$=\other \catcode `\&=\other |
| 30 |
\catcode`\#=\other \catcode`\%=\other \catcode `\~=\other |
| 31 |
\catcode`\_=\other \catcode`\^=\other |
| 32 |
\obeyspaces \obeylines \tt} |
| 33 |
{\obeyspaces\gdef {\ }} |
| 34 |
\outer\def\begintt{$$\let\par=\endgraf\ttverbatim \parskip=0pt |
| 35 |
\catcode`\|=0 \rightskip=-5pc \ttfinish} |
| 36 |
{\catcode`\|=0 |catcode`|\=\other |
| 37 |
|obeylines % end of line is now active |
| 38 |
|gdef|ttfinish#1^^M#2\endtt{#1|vbox{#2}|endgroup$$}} |
| 39 |
\catcode`\|=\active |
| 40 |
{\obeylines\gdef|{\ttverbatim\spaceskip=\ttglue\let^^M=\ \let|=\endgroup}} |
| 41 |
\newskip\ttglue |
| 42 |
\ttglue=0.5em plus 0.25em minus 0.15em |
| 43 |
% |
| 44 |
% |
| 45 |
% Some color definitions |
| 46 |
% |
| 47 |
\def\begincolor#1{\special{pdf:bc #1}}% |
| 48 |
\def\endcolor{\special{pdf:ec}}% |
| 49 |
\def\colored#1#2{% |
| 50 |
\begincolor{#1}#2\endcolor} |
| 51 |
\def\red{[0.8 0.5 0]}% |
| 52 |
\def\green{[0 1 0]}% |
| 53 |
\def\blue{[0 0.4 0.8]}% |
| 54 |
\def\yellow{[0.8 0.9 0.1]}% |
| 55 |
\def\linkcolor{[0.5 0.0 0.7]}% |
| 56 |
% |
| 57 |
% Small help for images |
| 58 |
\def\reserve#1#2#3{\setbox0\hbox{}\wd0=#1 |
| 59 |
\ht0=#2\special{#3}\box0} |
| 60 |
\def\nreserve#1#2#3{\setbox0\hbox{}\wd0=#1 |
| 61 |
\ht0=#2{#3}\box0} |
| 62 |
% |
| 63 |
% Some font definitions |
| 64 |
% |
| 65 |
\font\maintitlefont=cmti12 at 20.74pt |
| 66 |
\font\headingfont=cmss12 at 14.4pt |
| 67 |
\font\subheadingfont=cmss12 at 12pt |
| 68 |
% |
| 69 |
% |
| 70 |
% Miscellaneous token lists |
| 71 |
% |
| 72 |
\newtoks\title\newtoks\author\newtoks\version |
| 73 |
\newtoks\date |
| 74 |
% |
| 75 |
% Bibliography counters |
| 76 |
\newcount\biblioitems\biblioitems=0 |
| 77 |
\def\bibitem{\medskip\advance\biblioitems by 1\item{[\the\biblioitems]}} |
| 78 |
% |
| 79 |
% Counters for section levels |
| 80 |
% |
| 81 |
\newcount\sectioncount\newcount\ssectioncount\newcount\sssectioncount |
| 82 |
\sectioncount0\ssectioncount0\sssectioncount0 |
| 83 |
% |
| 84 |
\newskip\indentlevel\indentlevel=\parindent |
| 85 |
\newskip\secskip\secskip=24pt plus 1pt minus 2pt |
| 86 |
\newskip\subsecskip\subsecskip=16pt plus 1pt minus 2pt |
| 87 |
\def\beginlist{\par\nobreak\advance\leftskip by \indentlevel\advance\rightskip by |
| 88 |
\indentlevel\medskip\nobreak} |
| 89 |
\def\endlist{\par\advance\leftskip by -\indentlevel\advance\rightskip by |
| 90 |
-\indentlevel\medskip} |
| 91 |
% |
| 92 |
% |
| 93 |
\def\settitle{% |
| 94 |
{\maintitlefont\colored{\blue}{\the\title}}% |
| 95 |
\special {pdf: docinfo << /Title (\expandafter\the\title) >>}} |
| 96 |
% |
| 97 |
\def\setauthor{% |
| 98 |
{\headingfont\colored{\blue}{\the\author}}% |
| 99 |
\special {pdf: docinfo << /Author (\the\author) >>}}% |
| 100 |
% |
| 101 |
\def\setversion{% |
| 102 |
{\subheadingfont{\the\version}}% |
| 103 |
}% |
| 104 |
\def\setdate{% |
| 105 |
{\subheadingfont{\the\date}}% |
| 106 |
}% |
| 107 |
\def\setlink#1{\colored{\linkcolor}{#1}}% |
| 108 |
% |
| 109 |
\def\setheading#1{% |
| 110 |
{\headingfont\colored{\blue}{#1}}\raise\baselineskip |
| 111 |
\hbox{\special{pdf: outline 1 << /Title (#1) /Dest [ |
| 112 |
@thispage /FitH @ypos ] >> }}}% |
| 113 |
% |
| 114 |
\def\setsubheading#1{% |
| 115 |
{\subheadingfont\colored{\blue}{#1}}\raise\baselineskip |
| 116 |
\hbox{\special{pdf: outline 2 << /Title (#1) /Dest [ |
| 117 |
@thispage /FitH @ypos ] >> }}}% |
| 118 |
% |
| 119 |
% \def\link#1#2{\setbox0\hbox{\setlink{#1}}% |
| 120 |
% \leavevmode\special{pdf: ann width \the\wd0\space height \the\ht0\space depth \the\dp0 |
| 121 |
% << /Type /Annot /Subtype /Link /Border [ 0 0 0 ] /A << /S /GoTo |
| 122 |
% /D (#2) >> >>}\box0\relax}% |
| 123 |
\def\link#1#2{% |
| 124 |
\leavevmode\special{pdf: bann |
| 125 |
<< /Type /Annot /Subtype /Link /Border [ 0 0 0 ] /A << /S /GoTo /D (#2) |
| 126 |
>> |
| 127 |
>>}\setlink{#1}\special{pdf: eann}\relax} |
| 128 |
% |
| 129 |
\def\dest#1{\hbox{\raise14pt\hbox{\special{pdf:dest (#1) [ @thispage /FitH |
| 130 |
@ypos ]}}}}% |
| 131 |
% |
| 132 |
\def\maketitle{\noindent\settitle\hfill\setauthor\par |
| 133 |
\hrule height 1.0pt\medskip |
| 134 |
\noindent\setversion\hfill\setdate\vskip0.3in}% |
| 135 |
% |
| 136 |
\def\section#1{\advance\sectioncount by 1\ssectioncount0 |
| 137 |
\vskip-\lastskip\vskip\secskip\goodbreak |
| 138 |
\noindent\setheading{\the\sectioncount. #1}\medskip\nobreak}% |
| 139 |
\def\subsection#1{\vskip-\lastskip\advance\ssectioncount by 1% |
| 140 |
\vskip\subsecskip\noindent |
| 141 |
\setsubheading{\the\sectioncount.\the\ssectioncount\ |
| 142 |
#1}\par\nobreak\smallskip}% |
| 143 |
% |
| 144 |
\def\display#1{\medskip\line{\quad #1\hfil}\medskip} |
| 145 |
\def\example{\medskip\noindent{\it Example:\quad}\nobreak} |
| 146 |
\def\note{\medskip\noindent{\it Note:\quad\nobreak}} |
| 147 |
\def\syntax{\medskip\noindent{\it Syntax:\quad}\nobreak} |
| 148 |
\def\description{\medskip\noindent{\it Description:\quad}\nobreak} |
| 149 |
% |
| 150 |
\def\newpage{\vfill\eject} |
| 151 |
% |
| 152 |
\def\dvipdfm{{\tt dvipdfm}}% |
| 153 |
% |
| 154 |
\title{Dvipdfm User's Manual} |
| 155 |
\author{Mark A. Wicks} |
| 156 |
\version{Version 0.12.4b} |
| 157 |
\date{September 19, 1999} |
| 158 |
\maketitle |
| 159 |
\section{Introduction} |
| 160 |
This package is a DVI (\TeX) to PDF conversion utility, |
| 161 |
having the following features: |
| 162 |
|
| 163 |
\beginlist |
| 164 |
\item{$\bullet$} {\it Support for outline entries (also called bookmarks), named destinations, |
| 165 |
and \link{annotations}{Annotate} (including hyperlinks, forms and widgets).} Nearly |
| 166 |
every Acrobat Distiller pdfmark is approximated. |
| 167 |
|
| 168 |
\item{$\bullet$} {\it Support for ``standard'' DVI specials such |
| 169 |
as Hyper\TeX\ (HTML), TPIC, color specials, |PSfile|, and other PostScript specials.} |
| 170 |
|
| 171 |
\item{$\bullet$} {\it Native support for inclusion of |
| 172 |
\link{MetaPost}{postscript} output and |
| 173 |
inclusion of arbitrary \link{PostScript}{postscript} files with help from an external program.} |
| 174 |
|
| 175 |
\item{$\bullet$} {\it Support for thumbnails with a little help from GhostScript to |
| 176 |
generate the thumbnails.} |
| 177 |
|
| 178 |
\item{$\bullet$} {\it Support for arbitrary, nested linear transformations |
| 179 |
of typeset material.} Any material on the page, including |
| 180 |
\TeX\ text, may be \link{scaled and rotated}{textxform}. |
| 181 |
|
| 182 |
\item{$\bullet$} {\it Ability to include the first page of a \link{PDF file}{pdfimage} as |
| 183 |
an encapsulated object along with its embedded resources such as fonts.} |
| 184 |
Included PDF images may be cropped by supplying a bounding box. |
| 185 |
Note: Currently, this doesn't work if the contents stream |
| 186 |
has multiple segments. |
| 187 |
|
| 188 |
\item{$\bullet$} {\it Ability to include \link{JPEG}{jpegimage} and |
| 189 |
PNG bitmapped images as encapsulated objects.} |
| 190 |
|
| 191 |
\item{$\bullet$} {\it An internal color stack.} A color stack allows you to change the current color, pushing the |
| 192 |
current color onto a stack. At any time, the original color |
| 193 |
can be popped from the stack. This is useful, for example, in |
| 194 |
headlines, that may have a different color from the current text. |
| 195 |
The headline macro can restore the current color without knowing |
| 196 |
what it is. |
| 197 |
|
| 198 |
\item{$\bullet$} {\it Support for partial font embedding and Flate compression |
| 199 |
to reduce file size} |
| 200 |
|
| 201 |
\item{$\bullet$} {\it Support for font reencoding to work around encodings |
| 202 |
that aren't fully supported by the Acrobat suite of products.} |
| 203 |
|
| 204 |
\item{$\bullet$} {\it Balanced page and destination trees.} Balancing |
| 205 |
these trees improves reader access speed |
| 206 |
on very large documents. |
| 207 |
|
| 208 |
\endlist |
| 209 |
|
| 210 |
The electronic version of the document exercises |
| 211 |
some of the hypertext features and serves as |
| 212 |
a sample input file for |dvipdfm|. |
| 213 |
It assumes the reader has some familiarity with the basic features |
| 214 |
of the Portable Document Format. The PDF specification |
| 215 |
is distributed by Adobe Systems\link{[1]}{pdfmanual}. |
| 216 |
An excellent source for information about PDF documents |
| 217 |
in general is \link{[2]}{pdfprimer}. Information about |
| 218 |
using \TeX\ to construct PDF documents (mainly using Distiller) is the |
| 219 |
AcroTeX home page\link{[3]}{acrotex}. |
| 220 |
|
| 221 |
Currently, the widely accepted method to generate PDF file from \TeX\ |
| 222 |
is to use Adobe's Acrobat Distiller on a PostScript |
| 223 |
file produced by {\tt dvips}. |
| 224 |
The hyperlink features are accessed by using \TeX\ |special| primitives |
| 225 |
to embed pdfmarks in the PostScript produced by |dvips|. |
| 226 |
H\`an Th\'e Th\`an's PDF\TeX\ project is an alternative method |
| 227 |
of generating PDF from \TeX\ source. |
| 228 |
Although quite good and fairly mature, the PDF\TeX\ project |
| 229 |
modified \TeX\ itself to add primitives that support the PDF features. |
| 230 |
I prefer to work with \TeX\ unmodified, as released by Donald Knuth |
| 231 |
(call me a purist). |
| 232 |
There is an existing DVI to PDF driver called |
| 233 |
|dvipdf| written by Sergey Lesenko. At present, it's not widely |
| 234 |
available, so I haven't used it. I wrote |dvipdfm| |
| 235 |
mainly as an exercise to get at the features |
| 236 |
of PDF I was trying to use. This |dvipdfm| project demonstrates that many features |
| 237 |
of PDF can be accessed by using a DVI driver. |
| 238 |
The PDF features are activated in the driver via |
| 239 |
\TeX\ |special| primitives. |
| 240 |
|
| 241 |
Even though Distiller is the best method of generating PDF (and |
| 242 |
probably will remain so for some time) I have several reasons for |
| 243 |
seeking alternatives to Distiller. |
| 244 |
First, Distiller isn't available for my principle operating |
| 245 |
system---Linux. |
| 246 |
|
| 247 |
My second objection is philosophical. |
| 248 |
\TeX\ is a programming language. |
| 249 |
A DVI file is a page description consisting of very |
| 250 |
simple program instructions that have no branching or |
| 251 |
decision instructions. |
| 252 |
Similarly PostScript is a complete programming language, |
| 253 |
while PDF is a page description language consisting |
| 254 |
of simple program instructions |
| 255 |
without any branching or decision capabilities. |
| 256 |
\TeX\ is like PostScript (without the graphics) |
| 257 |
while DVI is like PDF (without the graphics or the hyperlinks). |
| 258 |
Creating PDF from DVI using Distiller requires converting a page description to a program, |
| 259 |
and converting that program back to a page description. |
| 260 |
To continue this analogy, |
| 261 |
Pdfmarks are PostScript ``escapes'' and are meant for the Distiller. |
| 262 |
\TeX\ |\special| primitives are \TeX\ ``escapes'' and are meant for the DVI driver. |
| 263 |
It seems natural to go directly from DVI to PDF, where \TeX\ replaces |
| 264 |
PostScript, the DVI driver replaces Distiller, |
| 265 |
and \TeX\ |\special| primitives replace the pdfmarks. |
| 266 |
|
| 267 |
Unfortunately, until graphics software |
| 268 |
begins to produce PDF content streams or encapsulated |
| 269 |
PDF objects, PostScript will remain the easiest |
| 270 |
way to include graphics in \TeX\ documents. |
| 271 |
I would hope that in the future, graphics programs |
| 272 |
will begin to produce PDF content streams or PDF objects that |
| 273 |
may be included using a DVI to PDF translator. Either |
| 274 |
of these may be easily embedded using \dvipdfm\ or a similar driver. |
| 275 |
|
| 276 |
\section{Command Line Options} |
| 277 |
\link{Table~1}{commandline} lists the options |
| 278 |
that are available on the command line. |
| 279 |
\par\noindent |
| 280 |
Note: Several flags may be specified at once: |
| 281 |
\example |
| 282 |
\begintt |
| 283 |
dvipdfm -ecz 9 test.dvi |
| 284 |
\endtt |
| 285 |
|
| 286 |
\topinsert |
| 287 |
{\dest{commandline}} |
| 288 |
\centerline{\colored{\blue}{\subheadingfont Table~1---Command line options |
| 289 |
recognized by |dvipdfm|}} |
| 290 |
\bigskip\nobreak |
| 291 |
\centerline{\vbox{\halign{{\tt #}\hskip |
| 292 |
1em\strut&\vtop{\leftskip0pt\rightskip0pt\hsize=3.5in\noindent #}\cr |
| 293 |
\omit\hfil\it Option\hfil&\omit\hfil \it Description \hfil\cr |
| 294 |
\noalign{\smallskip\begincolor\red\hrule\endcolor\smallskip} |
| 295 |
-c&{\it Disable color specials} Specifying this option |
| 296 |
forces all color commands to be ignored. This is useful for printing a color document |
| 297 |
on a black and white printer.\cr |
| 298 |
\noalign{\smallskip} |
| 299 |
-e&{\it Disable partial font embedding.} This may be useful |
| 300 |
for forms which need complete fonts, or if you run accross a PFB |
| 301 |
file that \dvipdfm\ cannot correctly parse.\cr |
| 302 |
\noalign{\smallskip} |
| 303 |
-f&{\it Set font map file name}. See |
| 304 |
the \link{Font Mapping}{fontmap} section for additional information.\cr |
| 305 |
\noalign{\smallskip} |
| 306 |
-m {\it number}&{\it Specify an additional magnification for |
| 307 |
the document}.\cr |
| 308 |
\noalign{\smallskip} |
| 309 |
-o {\it filename}&{\it Set the output PDF file name}.\cr |
| 310 |
\noalign{\smallskip} |
| 311 |
-p {\it papersize}&{\it Specify the output papersize.} |
| 312 |
Valid paper sizes are |letter|, |legal|, |ledger|, |tabloid|, |
| 313 |
|a4|, or |a3|. The default is |letter|. Arbitrary paper |
| 314 |
sizes can be specified via \TeX\ special commands, |
| 315 |
which is the recommended method.\cr |
| 316 |
\noalign{\smallskip} |
| 317 |
-l&{\it Landscape the document.} This is only |
| 318 |
meaningful for paper sizes specified on the command line.\cr |
| 319 |
\noalign{\smallskip} |
| 320 |
-s {\it page\_ranges}&{\it Select a subset of pages from the DVI file.} |
| 321 |
The {\it page\_ranges} specifier is a set of comma-separated page |
| 322 |
ranges---e.g., |dvipdfm -s 10-12,10-20|. If the first |
| 323 |
page in a range is empty (e.g., |dvipdfm -s -10|), it represents |
| 324 |
the beginning of the document. If |
| 325 |
the last page in a range is empty (e.g., |dvipdfm -s 10-|), it selects the end of the document.\cr |
| 326 |
\noalign{\smallskip} |
| 327 |
-t&{\it Embed thumbnail images.} The thumbnails must be generated by a |
| 328 |
separate program. Details are discussed \link{later}{thumbnails} in this document\cr |
| 329 |
\noalign{\smallskip} |
| 330 |
-d&{\it Delete thumbnail images after embedding.}\cr |
| 331 |
\noalign{\smallskip} |
| 332 |
-x {\it number}&{\it Specify the horizontal offset |
| 333 |
for the document.} The default is 1.0in.\cr |
| 334 |
\noalign{\smallskip} |
| 335 |
-y {\it number}&{\it Specify the vertical offset |
| 336 |
for the document.} The default is 1.0in.\cr |
| 337 |
\noalign{\smallskip} |
| 338 |
-z {\it number}&{\it Specify the compression level.} |
| 339 |
Valid compression levels range from 0 to 9, with 0 indicating |
| 340 |
no compression. A compression level of 9 is the default.\cr |
| 341 |
\noalign{\smallskip} |
| 342 |
-v&{\it Be verbose.} Among other things, dvipdfm |
| 343 |
will display complete file names as various files are opened.\cr |
| 344 |
\noalign{\smallskip} |
| 345 |
-vv&{\it Be more verbose.}\cr}}} |
| 346 |
\endinsert |
| 347 |
|
| 348 |
\section{General Concepts and Syntax for TeX Specials} |
| 349 |
Each \TeX\ |\special| |
| 350 |
represents a separate command to the \dvipdfm\ |
| 351 |
driver. Each |special| must begin with ``|pdf:|'' |
| 352 |
to identify that ||special|| as a command for the \dvipdfm\ driver. |
| 353 |
A |\special| beginning with any other characters is ignored |
| 354 |
by the driver. Leading spaces are ignored. The characters ``|pdf:|'' |
| 355 |
are immediately followed by a \dvipdfm\ command. These commands |
| 356 |
are documented in \hbox{Sections~3--6}. |
| 357 |
|
| 358 |
\subsection{PDF Object Syntax and Variable Expansion} |
| 359 |
With one exception, the syntax used for PDF objects |
| 360 |
within each |\special| specials follows |
| 361 |
the PDF specification. |
| 362 |
The one exception is variable expansion. |
| 363 |
In the syntax specifications that follow, {\it PDF\_Object} |
| 364 |
means that an arbitary PDF object is expected. Similarly |
| 365 |
{\it PDF\_Array} indicates that a PDF array is expected, {\it PDF\_Dict} |
| 366 |
inciates that a PDF dictionary is expected, etc. |
| 367 |
See the \link{reference manual}{pdfmanual}\ |
| 368 |
for a complete list of PDF object types. |
| 369 |
|
| 370 |
The single extension implemented in this driver |
| 371 |
allows a symbol name of the |
| 372 |
form |@|{\it name} whereever any PDF object is expected. |
| 373 |
The {\it name} may contain any characters allowed |
| 374 |
in a PDF name. |
| 375 |
A user-defined symbol beginning with |@| expands to an indirect |
| 376 |
reference to the user-defined PDF object. This feature replaces |
| 377 |
the |{|{\it name}|}| syntax used with pdfmarks. |
| 378 |
In addition to the user-defined names, some names |
| 379 |
are defined by the driver. |
| 380 |
The driver defined variables are for |
| 381 |
referencing objects such as the current page, future pages, |
| 382 |
or the current location on the current page. |
| 383 |
The driver defined variables appear in \link{Table~2}{drivervariables}. |
| 384 |
\topinsert |
| 385 |
{\dest{drivervariables}} |
| 386 |
\centerline{\colored{\blue}{\subheadingfont Table~2---List of driver |
| 387 |
defined variables}} |
| 388 |
\bigskip\nobreak |
| 389 |
\centerline{\vbox{\halign{{\tt #}\hskip |
| 390 |
1em&\vtop{\leftskip0pt\rightskip0pt\hsize=3.0in\noindent #}\cr |
| 391 |
\omit\hfil\it Variable\hfil&\omit\hfil \it Description \hfil\cr |
| 392 |
\noalign{\smallskip\begincolor\red\hrule\endcolor\smallskip} |
| 393 |
@catalog&A reference to the document's catalog.\cr |
| 394 |
\noalign{\smallskip} |
| 395 |
@names&A reference to the document's /Names dictionary.\cr |
| 396 |
\noalign{\smallskip} |
| 397 |
@pages&A reference to the root of the document's /Pages tree.\cr |
| 398 |
\noalign{\smallskip} |
| 399 |
@resources&A reference to the current page resource dictionary.\cr |
| 400 |
\noalign{\smallskip} |
| 401 |
@thispage&A reference to the current page.\cr |
| 402 |
\noalign{\smallskip} |
| 403 |
@page{\it n}&A reference to page {\it n}.\cr |
| 404 |
\noalign{\smallskip} |
| 405 |
@nextpage&A reference to the page following |@thispage|.\cr |
| 406 |
\noalign{\smallskip} |
| 407 |
@prevpage&A reference to the page preceding |@thispage|.\cr |
| 408 |
\noalign{\smallskip} |
| 409 |
@ypos&A {\it number} representing the current vertical position in units of PDF points.\cr |
| 410 |
\noalign{\smallskip} |
| 411 |
@xpos&A {\it number} representing the current horizontal position in units of PDF points.\cr |
| 412 |
}}} |
| 413 |
\endinsert |
| 414 |
|
| 415 |
In the syntax specifications that follow, several |
| 416 |
standard conventions are followed. Terminal |
| 417 |
characters that appear in the command |
| 418 |
are typeset in the |\tt| font, e.g., |object|. |
| 419 |
Nonterminal symbols are typeset in italics. |
| 420 |
Optional parameters are surrounded by brackets, e.g., |
| 421 |
[{\it optional\_argument}]. An item followed |
| 422 |
by~``{*}'' represents an item that may appear |
| 423 |
zero or more times. An item followed by~``{+}'' |
| 424 |
represents a required item that may appear multiple times. |
| 425 |
|
| 426 |
\subsection{Dimensions and transformations} |
| 427 |
Interaction with the |dvipdfm| driver consists |
| 428 |
of short commands with a few arguments delimited by white space. |
| 429 |
Typically the arguments are PDF objects. |
| 430 |
Two exceptions are dimension specifications and transformations. |
| 431 |
|
| 432 |
In the \TeX\ style, a dimension specification consists of one of the keywords |
| 433 |
|width|, |height|, or |depth| followed by a dimension |
| 434 |
consisting of a numerical value, followed by a unit for the dimension. The |
| 435 |
unit will typically be |pt| (which represents a \TeX\ point, not a |
| 436 |
PDf point) but |mm|, |cm| and |in| are also allowed. |
| 437 |
If the document is magnified, the ``true'' dimensions |truept|, |
| 438 |
|truemm|, |truecm|, and |truein| may be used. The notation |
| 439 |
{\it dimension\/} in a syntax description means a dimension is expected. |
| 440 |
|
| 441 |
A transformation consists of one of the keywords |scale|, |xscale|, |
| 442 |
|yscale|, or |rotate| followed by a numerical value. In the |
| 443 |
case of |rotate| the value is the rotation angle in degrees. |
| 444 |
The notation |
| 445 |
{\it transformation} means a transformation is expected. |
| 446 |
In the case of included images originating from |
| 447 |
PDF/PostScript files, a clipping or bounding box may be specified |
| 448 |
as part of the ``transformation.'' The bounding |
| 449 |
box specification consists of the keyword |bbox| |
| 450 |
followed by four numerical values, which are |
| 451 |
the standard PostScript |llx|, |lly|, |urx|, and |ury| |
| 452 |
coordinates of the bounding box. |
| 453 |
|
| 454 |
\section{Document Construction Commands} |
| 455 |
All commands are executed via \TeX\ |\special| primitives |
| 456 |
prefixed with the characters ``|pdf:|''. |
| 457 |
\example |
| 458 |
\begintt |
| 459 |
\special{ pdf: out 1 << /Title (Introduction) |
| 460 |
/Dest [ 1 0 R /FitH 234 ] >> |
| 461 |
\endtt |
| 462 |
|
| 463 |
\dest{Annotate} |
| 464 |
\subsection{Annotate} |
| 465 |
\hbox to 0pt{\hskip-1.0in\special{pdf: ann width 3.0in height 36pt << /Type /Annot /Subtype /Text |
| 466 |
/Contents (This is a /Text Annotation that looks like a sticky note.) >>}\hss} |
| 467 |
\syntax |
| 468 |
{\tt annotate} [{\tt @}{\it name}] {\it dimension}+ {\it PDF\_dictionary} |
| 469 |
\description |
| 470 |
The |annotate| (|annot| or |ann|) command defines an annotation. |
| 471 |
Annotations are typically used for |
| 472 |
notes, hyperlinks, forms, or widgets. |
| 473 |
The parameter {\it name} is an optional alphanumeric identifier |
| 474 |
and {\it PDF\_dictionary} is a valid PDF dictionary after variable expansion. |
| 475 |
If {\tt @}{\it name} is specified, it may be used in |
| 476 |
other PDF objects to refer to this annotation. |
| 477 |
One or more {\it dimension} parameters are required |
| 478 |
and each consists of the keyword |
| 479 |
{\tt height}, {\tt width}, or {\tt depth} followed |
| 480 |
by an appropriate length, specified as per \TeX\null. |
| 481 |
The |width| must be nonzero and either the |height| or |depth| |
| 482 |
must be nonzero. |
| 483 |
Each length is a number followed by a unit, such as {\tt pt}, |
| 484 |
{\tt in}, or {\tt cm}. Since these values |
| 485 |
would typically be entered by \TeX, a {\tt pt} |
| 486 |
is a \TeX\ point, not a PDF point. |
| 487 |
|
| 488 |
\example The annotation in this subsection |
| 489 |
was typeset with |
| 490 |
\begintt |
| 491 |
\special{pdf: ann width 3.0in height 36pt |
| 492 |
<< /Type /Annot /Subtype /Text |
| 493 |
/Contents (This is a /Text Annotation |
| 494 |
that looks like a sticky note.) >>} |
| 495 |
\endtt |
| 496 |
|
| 497 |
\subsection{Begin Annotation} |
| 498 |
\syntax |
| 499 |
{\tt beginann} {\it PDF\_dictionary} |
| 500 |
\description |
| 501 |
The |beginann| (|bann| or |bannot|) command begins a breakable annotation. |
| 502 |
Dvipdfm tries to determine the boundaries of the annotation automatically. |
| 503 |
Such an annotation may be broken over several lines (or even several pages). |
| 504 |
Unlike |annot|, the annotation may be not be referred to by name later, |
| 505 |
since there may be more than once instances of the annotation. |
| 506 |
The |beginann| command needs not dimension because |dvipdfm| |
| 507 |
computes the correct bounding box on the fly. |
| 508 |
|
| 509 |
Note: Link breaking is easily fooled at page breaks. If you have problems |
| 510 |
with the header or footer wanting to become part of the link, you can |
| 511 |
insert a |nolink| command at the beginning of the footer and a |link| |
| 512 |
command at the end of the footer. |
| 513 |
|
| 514 |
\subsection{End Annotation} |
| 515 |
\syntax |
| 516 |
{\tt endann} |
| 517 |
\description |
| 518 |
The |endann| (|eann| or |eannot|) terminates a breakable annotation. |
| 519 |
|
| 520 |
\subsection{Link} |
| 521 |
{\tt link} |
| 522 |
\description |
| 523 |
The |link| command instructs the link breaking algorithm to resume its |
| 524 |
operation after a |nolink| command. |
| 525 |
|
| 526 |
\subsection{Nolink} |
| 527 |
{\tt nolink} |
| 528 |
\description |
| 529 |
The |nolink| command instructs the link breaking algorithm to suspend |
| 530 |
it operation. This is only required if there is material inserted |
| 531 |
on the page in the {\it middle} of a link. For example, when a link |
| 532 |
is broken at the end of a page, the header and footer are inserted |
| 533 |
in the middle of the link, but are not part of the link. Material |
| 534 |
that is inserted between a |nolink| and |link| will not become |
| 535 |
part of the link. The |nolink| and |link| escapes are not necessary |
| 536 |
with the standard LaTeX header and footer lines, but may become necessary |
| 537 |
if these are changed. |
| 538 |
|
| 539 |
\subsection{Dest} |
| 540 |
\syntax |
| 541 |
{\tt dest} {\it PDF\_String} {\it PDF\_Dest} |
| 542 |
\description |
| 543 |
The |dest| command defines a named destination. |
| 544 |
The {\it PDF\_String} is a PDF string naming |
| 545 |
the destination. This string may be used in the destination |
| 546 |
fields of annotations and outline entries to refer to |
| 547 |
this destination. {\it PDF\_Dest} is a PDF |
| 548 |
destination object (typically an array). |
| 549 |
\example |
| 550 |
\begintt |
| 551 |
\special{pdf: dest (listofreferences) [ @thispage /FitH @ypos ]} |
| 552 |
\endtt |
| 553 |
|
| 554 |
\subsection{Docinfo} |
| 555 |
\syntax |
| 556 |
{\tt docinfo} {\it PDF\_dictionary} |
| 557 |
\description |
| 558 |
The |docinfo| command adds the keys in the specified dictionary to the |
| 559 |
document's |/Info| dictionary. All keys are optional, but may include |
| 560 |
the keys |/Author|, |/Title|, |/Keywords|, |/Subject|, |
| 561 |
and |/Creator|. |
| 562 |
\example |
| 563 |
\begintt |
| 564 |
\special{pdf: docinfo << /Author (Mark A. Wicks) |
| 565 |
/Title (This Document) >>} |
| 566 |
\endtt |
| 567 |
|
| 568 |
\subsection{Docview} |
| 569 |
\syntax |
| 570 |
{\tt docview} {\it PDF\_dictionary} |
| 571 |
\description |
| 572 |
The |docview| command adds the keys in the specified dictionary to the |
| 573 |
document's |/Catalog| dictionary. All keys are optional, but may include |
| 574 |
the keys |/PageMode|, |
| 575 |
|/URI|, |/OpenAction|, |/AA| |
| 576 |
and |/ViewerPreferences|. See the PDF Reference Manual |
| 577 |
for documentation of these keys and additional keys. |
| 578 |
\example |
| 579 |
\begintt |
| 580 |
\special{pdf: docview << /PageMode /UseThumbs >> } |
| 581 |
\endtt |
| 582 |
|
| 583 |
|
| 584 |
\subsection{Object} |
| 585 |
\syntax |
| 586 |
{\tt object} [@{\it name}] {\it PDF\_Object} |
| 587 |
\description |
| 588 |
The |object| (also |obj|) command creates a |
| 589 |
PDF object. The parameter {\it PDF\_Object} is any valid PDF object. The |
| 590 |
parameter {\it name} may be used to provide an indirect reference |
| 591 |
to this object within other |
| 592 |
objects. It will be expanded anywhere within |
| 593 |
a {\tt special} where a PDF object is |
| 594 |
expected. Typically {\it object} is an array |
| 595 |
or dictionary. It may be an empty array or |
| 596 |
dictionary that can be constructed dynamically via |
| 597 |
the {\tt put} command. |
| 598 |
\example |
| 599 |
\begintt |
| 600 |
\special{pdf: object @mydict << /Firstpage @thispage >>} |
| 601 |
\endtt |
| 602 |
|
| 603 |
\subsection{Out} |
| 604 |
\syntax |
| 605 |
{\tt out} {\it number} {\it PDF\_dictionary} |
| 606 |
|
| 607 |
\description |
| 608 |
The |out| (also |outline|) command adds an outline (also called a ``bookmark'') entry |
| 609 |
to the document. |
| 610 |
The parameter {\it level\/} is an integer representing the |
| 611 |
level of the outline entry (beginning with 1) and |
| 612 |
{\it PDF\_dictionary\/} must contain |
| 613 |
the two keys {\tt /Title} and either {\tt /Dest} or {\tt /A}. |
| 614 |
It may also contain the {\tt /AA} key. These keys are documented |
| 615 |
in the PDF Reference Manual. |
| 616 |
\example |
| 617 |
\begintt |
| 618 |
out 1 << /Title (Section 1) /Dest [ @thispage /FitH @ypos ] >> |
| 619 |
\endtt |
| 620 |
which may be followed by |
| 621 |
\begintt |
| 622 |
out 2 << /Title (Section 1.1) /Dest [ @thispage /FitH @ypos ] >> |
| 623 |
\endtt |
| 624 |
\note |
| 625 |
You may not skip levels. A level~2 outline entry |
| 626 |
must follow a level~1 outline |
| 627 |
entry. A level~3 outline entry must follow a level~2 outline |
| 628 |
and cannot immediately follow a level 1 outline entry. |
| 629 |
|
| 630 |
\subsection{Pagesize} |
| 631 |
\syntax |
| 632 |
{\tt pagesize} {\it dimension}+ |
| 633 |
\description |
| 634 |
The |pagesize| command specifies the document's physical |
| 635 |
paper size. The |pagesize| command must be specified on |
| 636 |
the first page and must precede the first annotation |
| 637 |
or background color specification on the page. |
| 638 |
In other words, it should occur as close to the |
| 639 |
beginning of the document as possible. |
| 640 |
\example |
| 641 |
\begintt |
| 642 |
pagesize width 11.0truein height 8.5truein |
| 643 |
\endtt |
| 644 |
|
| 645 |
\subsection{Put} |
| 646 |
\syntax |
| 647 |
\beginlist |
| 648 |
{\tt put} @{\it name} {\it PDF\_Object}+ |
| 649 |
\endlist |
| 650 |
or |
| 651 |
\beginlist |
| 652 |
{\tt put} @{\it name} {\it PDF\_Dictionary} |
| 653 |
\endlist |
| 654 |
\description |
| 655 |
The |put| command modifies an existing PDF object created with |obj|, |
| 656 |
or one of the following internally defined objects: |@catalog|, |
| 657 |
|@names|, |@pages|, |@thispage|, or |@resources|. |
| 658 |
The first form is used when @{\it name} is an array. The second |
| 659 |
form is used when @{\tt name} is a dictionary. More than |
| 660 |
one object may be added to an array at once. |
| 661 |
All keys in {\it PDF\_Dictionary} |
| 662 |
are added to the dictionary represented by @{\it name}. |
| 663 |
\example |
| 664 |
\begintt |
| 665 |
\special{pdf: put @mydict << /Nextpage @thispage >>} |
| 666 |
\endtt |
| 667 |
|
| 668 |
\subsection{Thread} |
| 669 |
\syntax |
| 670 |
{\tt thread} {\tt @}{\it name} {\it dimension}+ [ {\it PDF\_dictionary} ] |
| 671 |
|
| 672 |
\description |
| 673 |
The |thread| (or |art|) command adds a bead to an article. |
| 674 |
An article is a collection of boxed regions in the document that should be |
| 675 |
read consecutively. |
| 676 |
Each bead using the same {\it name} belongs to the same article. |
| 677 |
The {\it name} parameter is required. The {\it dimension} parameter |
| 678 |
defined the rectangular area belonging to the bead in |
| 679 |
the same manner as for |annot|. |
| 680 |
The optional PDF dictionary |
| 681 |
should supplied on one of the beads. Its keys are |
| 682 |
similar to the |/Info| dictionary accessed via the |docinfo| command |
| 683 |
and would typically include the |/Title| and |/Author| keys. |
| 684 |
Keys in the dictionary may be overwritten by subsequent {\tt thread} commands. |
| 685 |
\example |
| 686 |
\begintt |
| 687 |
\special {pdf: thread @somearticle << /Title (Some title) |
| 688 |
/Author (Me) >>} |
| 689 |
\endtt |
| 690 |
|
| 691 |
\subsection{Close} |
| 692 |
\syntax |
| 693 |
{\tt close} @{\it name} |
| 694 |
\description |
| 695 |
The |close| writes the named PDF object created with |obj| to the PDF file. |
| 696 |
No further |put| commands may be executed for this object. |
| 697 |
The object may continue to be referenced using @{\it name} |
| 698 |
indefinitely. If the object is never closed, it will |
| 699 |
be closed when |dvipdfm| finishes processing the document. |
| 700 |
|
| 701 |
\section{Form XObjects} |
| 702 |
The PDF specification allows an object to be stored once |
| 703 |
and displayed at multiple locations throughout the document. |
| 704 |
The following commands give access to this facility. |
| 705 |
|
| 706 |
\subsection{Beginxobj} |
| 707 |
\syntax |
| 708 |
{\tt beginxobj} @{\it name} {\it dimension}+ |
| 709 |
\description |
| 710 |
The |beginxobj| (or |bxobj|) command begins the definition of |
| 711 |
a Form XObject. All material typeset between the |
| 712 |
|beginxobj| and |endxobj| commands will be captured |
| 713 |
into the XObject. The material can be displayed later |
| 714 |
at an arbitrary location with the |usexobj| command. |
| 715 |
The {\it name} may be used to refer to the object later, |
| 716 |
either via the |usexobj| command or as an indirect |
| 717 |
reference to the XObject if {\it name} is |
| 718 |
used within the context of a {\it PDF\_Object}.. |
| 719 |
The required {\it dimension} identifies the extent |
| 720 |
(i.e., bounding box) of the area to be captured. |
| 721 |
It is specified in the same way as for |annot|. |
| 722 |
|
| 723 |
The material will not display during the object definition. |
| 724 |
In other words, if you are typsetting with \TeX\ you |
| 725 |
should place the XObject in a box of dimension 0 so |
| 726 |
you don't leave a white space hole where the object was |
| 727 |
defined. |
| 728 |
\example |
| 729 |
\begintt |
| 730 |
bxobj @myform width 2.0in height 24pt |
| 731 |
\endtt |
| 732 |
|
| 733 |
\subsection{Endxobj} |
| 734 |
\syntax |
| 735 |
{\tt endxobj} |
| 736 |
\description |
| 737 |
The |endxobj| (or |exobj|) command ends the previous |
| 738 |
|beginxobj| definition. Note that XObject definitions |
| 739 |
may not be nested. XObjects can be {\it used} within |
| 740 |
other XObjects, however. |
| 741 |
\example |
| 742 |
\begintt |
| 743 |
exobj |
| 744 |
\endtt |
| 745 |
|
| 746 |
\subsection{Usexobj} |
| 747 |
\syntax |
| 748 |
{\tt usexobj} @{\it name} |
| 749 |
\description |
| 750 |
The |usexobj| (or |uxobj|) command displays the |
| 751 |
form XObject previously defined and |
| 752 |
associated with {\it name}. |
| 753 |
\example |
| 754 |
\begintt |
| 755 |
uxobj @myform |
| 756 |
\endtt |
| 757 |
|
| 758 |
\section{Text Transformation Commands} |
| 759 |
The commands in this section deal with transformation |
| 760 |
of arbitrary material, which may include |
| 761 |
material typeset by \TeX. These |
| 762 |
may also be used on included graphics images |
| 763 |
if the commands in Section~8 won't do the job. |
| 764 |
|
| 765 |
\subsection{BeginTransform} |
| 766 |
\syntax |
| 767 |
{\tt begintransform} {\it transformation}+ |
| 768 |
|
| 769 |
\description |
| 770 |
The |begintransform| (|btrans| or |bt|) applies |
| 771 |
the specified transformation to all subsequent text. |
| 772 |
The scaling is applied first, followed by the rotation. |
| 773 |
The reference point of a box following |
| 774 |
the |\special| remains fixed. Such transformations |
| 775 |
may be nested to perform rotations within rotated text, for exmaple. |
| 776 |
|
| 777 |
\example |
| 778 |
\begintt |
| 779 |
\special{pdf: bt rotate 90 xscale 2.0 } |
| 780 |
\endtt |
| 781 |
|
| 782 |
\subsection{BeginTransform} |
| 783 |
\syntax |
| 784 |
{\tt endtransform} |
| 785 |
\description |
| 786 |
The |endtransform| (|etrans| or |et|) concludes |
| 787 |
the action of the immediately preceding |begintransform| |
| 788 |
command. All transformations must be closed |
| 789 |
on the same page. The driver will close |
| 790 |
any pending unclosed transformations at the |
| 791 |
end of the page and issue a warning message. |
| 792 |
All material to be transformed |
| 793 |
should probably be enclosed in a single box |
| 794 |
to prevent any break. |
| 795 |
\example |
| 796 |
\begintt |
| 797 |
\special{pdf: et} |
| 798 |
\endtt |
| 799 |
|
| 800 |
|
| 801 |
\section{Color Commands} |
| 802 |
The commands in this section deal with manipulation of the color |
| 803 |
stack. |
| 804 |
|
| 805 |
\subsection{Setcolor} |
| 806 |
\syntax |
| 807 |
{\tt setcolor} {\it PDF\_Number$\vert$\it PDF\_Array} |
| 808 |
\description |
| 809 |
The |setcolor| (|scolor| or |sc|) command uses its |
| 810 |
argument to set the default color for future marking operators. |
| 811 |
The current color is replaced and may be retrieved |
| 812 |
only by a subsequent |setcolor| command. The argument |
| 813 |
may be a single number, which is interpreted as a grayscale |
| 814 |
value; a three element array, which is interpreted as an RGB |
| 815 |
color space coordinate; or a four element array, which |
| 816 |
is interpreted as a CMYK color space coordinate. |
| 817 |
\example |
| 818 |
\begintt |
| 819 |
\special{ pdf: sc [ 1 0 0 ] } |
| 820 |
\endtt |
| 821 |
|
| 822 |
\subsection{Begincolor} |
| 823 |
\syntax |
| 824 |
{\tt begincolor} {\it PDF\_Number$\vert$\it PDF\_Array} |
| 825 |
\description |
| 826 |
The |begincolor| (|bcolor| or |bc|) command uses its |
| 827 |
argument to set the default color for future marking operators. |
| 828 |
The current color is pushed on the color stack. The argument |
| 829 |
may be a single number, which is interpreted as a grayscale |
| 830 |
value; a three element array, which is interpreted as an RGB |
| 831 |
color space coordinate; or a four element array, which |
| 832 |
is interpreted as a CMYK color space coordinate. |
| 833 |
\example |
| 834 |
\begintt |
| 835 |
\special{ pdf: bc [ 1 0 0 ] } |
| 836 |
\endtt |
| 837 |
|
| 838 |
\subsection{Endcolor} |
| 839 |
\syntax |
| 840 |
{\tt endcolor} |
| 841 |
\description |
| 842 |
The |endcolor| (|ecolor| or |ec|) |
| 843 |
changes the default color to |
| 844 |
match the color on the top |
| 845 |
of the stack. It removes |
| 846 |
the color from the stack. |
| 847 |
\example |
| 848 |
\begintt |
| 849 |
\special{ pdf: ec } |
| 850 |
\endtt |
| 851 |
|
| 852 |
\subsection{Bgcolor} |
| 853 |
\syntax |
| 854 |
{\tt bgcolor} {\it PDF\_Number$\vert$\it PDF\_Array} |
| 855 |
\description |
| 856 |
The |bgcolor| (|bbc| or |bgc|) command uses the value |
| 857 |
of its argument to set the default color for the page |
| 858 |
background. The interpretation |
| 859 |
fo the argument is the same as for the |begincolor| command. |
| 860 |
The stack is not involved here. There is no way |
| 861 |
to go back to the previous background color. |
| 862 |
\example |
| 863 |
\begintt |
| 864 |
\special{ pdf: bc [ 1 0 0 ] } |
| 865 |
\endtt |
| 866 |
|
| 867 |
\section{Image Commands} |
| 868 |
The commands in this section deal with embedding |
| 869 |
graphics into your PDF document. The present |
| 870 |
driver supports PDF, PNG, and JPEG graphics inclusion. |
| 871 |
|
| 872 |
\subsection{Epdf} |
| 873 |
\syntax |
| 874 |
{\tt epdf} [|@|{\it name}] [{\it dimension}$\vert${\it transformation}]* {\it PDF\_String} |
| 875 |
|
| 876 |
\description |
| 877 |
The {\tt epdf} command ``encapsulates'' the first page of a PDF |
| 878 |
file named by {\it PDF\_String} |
| 879 |
into a PDF XObject. The resulting XObject is drawn |
| 880 |
with the lower left corner at the current location of the page. |
| 881 |
The optional @{\it name} parameter may be used |
| 882 |
to reference this object within other objects. If a |
| 883 |
{\it dimension} is supplied, the object will be scaled to fit |
| 884 |
that dimension. A {\it transformation} consists of one of the keywords |
| 885 |
|scale|, |xscale|, |yscale|, or |rotate| |
| 886 |
followed by a number representing |
| 887 |
the scaling factor or rotation angle in degrees. Both {\it transformation} and {\it dimension} |
| 888 |
parameters can be supplied as long as they are not logically |
| 889 |
inconsistent. |
| 890 |
|
| 891 |
Note: The object is stored as an XObject and can be redisplayed later by using the |
| 892 |
|usexobj| function and specifying {\it name}. |
| 893 |
|
| 894 |
\example |
| 895 |
\begintt |
| 896 |
\special{pdf:epdf yscale 0.50 width 4.0in |
| 897 |
rotate 45 (circuit.pdf)} |
| 898 |
\endtt |
| 899 |
|
| 900 |
\subsection{Image} |
| 901 |
\syntax |
| 902 |
{\tt image} [@{\it name}] [{\it dimension} $\vert$ {\it transformation}]* {\it PDF\_String} |
| 903 |
|
| 904 |
\description |
| 905 |
The {\tt image} command ``encapsulates'' an image |
| 906 |
taken from the file named by {\it PDF\_String}. |
| 907 |
This command functions just like |epdf|. Value |
| 908 |
image types may be PDF, JPEG, or PNG images. |
| 909 |
This special will eventually replace the |epdf| special. |
| 910 |
|
| 911 |
Note: The object is stored as an XObject and can be redisplayed later by using the |
| 912 |
|usexobj| function and specifying {\it name}. |
| 913 |
|
| 914 |
\section{Raw Page Marking Commands} |
| 915 |
The commands in this section deal with embedding |
| 916 |
raw PDF graphics operators into your PDF document. |
| 917 |
|
| 918 |
\subsection{Bop} |
| 919 |
\syntax |
| 920 |
{\tt bop} {\it stream} |
| 921 |
\description |
| 922 |
The |bop| command specifies a marking |
| 923 |
stream to be generated at the top of each page. |
| 924 |
The parameter {\it stream} is any sequence |
| 925 |
of marking operators and is added to the page's content stream. |
| 926 |
The stream is applied {\it to all pages} regardless |
| 927 |
of where it appears in the document. |
| 928 |
\example The two horizontal lines appearing |
| 929 |
at the top of each page in this document |
| 930 |
were set with |
| 931 |
\begintt |
| 932 |
\special {pdf: bop q 0 w 0.8 0.5 0 RG |
| 933 |
54 740 m 504 740 l 504 740.25 l 54 740.25 l b |
| 934 |
36 760 m 504 760 l 504 760.25 l 36 760.25 l b Q } |
| 935 |
\endtt |
| 936 |
\special {pdf: bop q 0 w 0.8 0.5 0 RG |
| 937 |
54 740 m 504 740 l 504 740.25 l 54 740.25 l b |
| 938 |
36 760 m 504 760 l 504 760.25 l 36 760.25 l b Q } |
| 939 |
|
| 940 |
\subsection{Content} |
| 941 |
\syntax |
| 942 |
{\tt content} {\it stream} |
| 943 |
\description |
| 944 |
The |content| command specifies a marking |
| 945 |
stream to be added to the current page at |
| 946 |
the current location. While it |
| 947 |
is possible to change the color |
| 948 |
state, etc., with this command, it is |
| 949 |
not advised. Use the color management |
| 950 |
commands to change colors. |
| 951 |
|
| 952 |
|
| 953 |
\subsection{Eop} |
| 954 |
\syntax |
| 955 |
\beginlist |
| 956 |
{\tt eop} {\it stream} |
| 957 |
\endlist |
| 958 |
\description |
| 959 |
The {\tt eop} specifies a marking stream to be generated at the end |
| 960 |
of each page. The parameter {\it stream} is any sequence |
| 961 |
of marking operators and is added to the page's content stream. |
| 962 |
The stream is applied {\it to all pages} regardless |
| 963 |
of where it appears in the document. |
| 964 |
|
| 965 |
\section{Graphics Examples} |
| 966 |
|
| 967 |
The examples in this section illustrate some of the transformation |
| 968 |
and image inclusion capabilities of \dvipdfm. |
| 969 |
|
| 970 |
\dest{textxform} |
| 971 |
\subsection{Text Transformation} |
| 972 |
Tables with slanted entries are possible as shown |
| 973 |
in \link{Table~3}{rotatedtable}. This table was achieved using |
| 974 |
various ``|bt rotate 35|'' commands. |
| 975 |
|
| 976 |
The following line of text was done with nested |
| 977 |
combinations of ``|bt rotate 10|'' and ``|bt rotate -10|''. |
| 978 |
|
| 979 |
\def\up#1{\special{pdf:bt rotate 10}\hbox{#1}} |
| 980 |
\def\down#1{\special{pdf:bt rotate -10}\hbox{#1}} |
| 981 |
You \down{can} nest \down{the} \up{text} |
| 982 |
trans\up{form}ation \up{capa}\down{bili}ties \down{to} |
| 983 |
achieve \down{effects} \down{like} |
| 984 |
{this}. |
| 985 |
\special{pdf:et}\special{pdf:et}\special{pdf:et}\special{pdf:et} |
| 986 |
\special{pdf:et}\special{pdf:et}\special{pdf:et}\special{pdf:et} |
| 987 |
\special{pdf:et} |
| 988 |
\vskip 0.5in |
| 989 |
|
| 990 |
|
| 991 |
\def\rvr{\colored{\red}{\vrule}}\def\entry#1{\special{pdf:bt rotate 35}% |
| 992 |
{\vbox to 0pt{\vss\hbox{\quad\colored{\blue}{#1}\quad}\vskip 1pt\colored{\red}{\hrule}}\special{pdf:et}}} |
| 993 |
\topinsert |
| 994 |
\dest{rotatedtable} |
| 995 |
\bigskip |
| 996 |
\centerline{\colored{\blue}{\subheadingfont Table 3---Example of rotated |
| 997 |
text set in Computer Modern Roman}} |
| 998 |
\bigskip |
| 999 |
\centerline{\vbox to 0.45in{\vss\offinterlineskip\halign{#&#&#&#&#&#\cr |
| 1000 |
\entry{1994}& |
| 1001 |
\entry{1995}& |
| 1002 |
\entry{1996}& |
| 1003 |
\entry{1997}& |
| 1004 |
\entry{1998}& |
| 1005 |
\entry{1999}\cr |
| 1006 |
\noalign{\colored{\red}{\hrule}} |
| 1007 |
\strut\rvr&\rvr&\rvr&\rvr&\rvr&\rvr\crcr}}} |
| 1008 |
\bigskip |
| 1009 |
\endinsert |
| 1010 |
|
| 1011 |
\dest{imageinclude} |
| 1012 |
\subsection{Image Inclusion} |
| 1013 |
|
| 1014 |
The image in \link{Figure~1}{jpegimage} was included from a JPEG file. |
| 1015 |
The image shown in \link{Figure~2}{rotatedimage} comes from the same file, |
| 1016 |
but is loaded at a 50\% scale and a 45$^\circ$ rotation. |
| 1017 |
|
| 1018 |
\topinsert |
| 1019 |
\dest{jpegimage} |
| 1020 |
\bigskip |
| 1021 |
\centerline{\reserve{1.50in}{2.05in}{pdf: image (mwicks.jpeg)}} |
| 1022 |
\medskip |
| 1023 |
\centerline{\subheadingfont |
| 1024 |
\begincolor{\blue}Figure~1---A JPEG image of the author.\endcolor} |
| 1025 |
\bigskip |
| 1026 |
\endinsert |
| 1027 |
|
| 1028 |
\topinsert |
| 1029 |
\dest{rotatedimage} |
| 1030 |
\bigskip |
| 1031 |
\centerline{\reserve{0.75in}{1.25in}{pdf: image rotate 45 scale 0.50 (mwicks.jpeg)}} |
| 1032 |
\medskip |
| 1033 |
\centerline{\subheadingfont |
| 1034 |
\begincolor{\blue}Figure~2---Image of the author scaled by 0.5 and rotated |
| 1035 |
by 45$^\circ$.% |
| 1036 |
\endcolor} |
| 1037 |
\bigskip |
| 1038 |
\endinsert |
| 1039 |
|
| 1040 |
By default, JPEG files are included |
| 1041 |
at a resolution of 100dpi so if you know the pixel size |
| 1042 |
of the image, you know how much space to reserve. |
| 1043 |
Any \TeX\ magnification is applied to the image |
| 1044 |
in addition to any scaling defined in the |\special|. |
| 1045 |
For example, this document sets |\magnification=\magstephalf|, |
| 1046 |
so the images are actually scaled by 1.095. The first |
| 1047 |
image in this section has a printed width of 1.643in |
| 1048 |
even though 1.50in was specified in the |\special|. |
| 1049 |
|
| 1050 |
Several command line utilities exist that read |
| 1051 |
the pixel dimensions of a JPEG file. For PDF files, |
| 1052 |
you can |grep| on |/MediaBox| to get an indication |
| 1053 |
of the image size. The |/MediaBox| dimensions are |
| 1054 |
in PDF points. |
| 1055 |
|
| 1056 |
The image in \link{Figure~3}{pdfimage} was produced by embedding a PDF file |
| 1057 |
using |epdf|. |
| 1058 |
|
| 1059 |
\topinsert |
| 1060 |
\dest{pdfimage} |
| 1061 |
\centerline{\reserve{2.41in}{2.6in}{pdf: epdf width 2.41in (transistor.pdf)}} |
| 1062 |
\medskip\centerline{\subheadingfont |
| 1063 |
\begincolor{\blue}Figure~3---An embedded PDF object. |
| 1064 |
\endcolor} |
| 1065 |
\endinsert |
| 1066 |
Notice that any resources required for the object |
| 1067 |
are also embedded. In this case, the Times Roman font |
| 1068 |
resource was embedded along with the content stream. |
| 1069 |
|
| 1070 |
\dest{thumbnails}\section{Thumbnails} |
| 1071 |
Thumbnails can be inserted automatically by |dvipdfm| |
| 1072 |
using the |-t| command line option. However, |dvipdfm| |
| 1073 |
is unable to generate the thumbnails by itself. This |
| 1074 |
must be done by some other program such as GhostScript. |
| 1075 |
The typical two-pass process to include thumbnails would be |
| 1076 |
\item{1.} |
| 1077 |
Run |dvipdfm| without the |-t| option (probably |
| 1078 |
using command line options optimized for speed and not space) |
| 1079 |
\item{2.} |
| 1080 |
Run GhostScript to generate the thumbnail images of |
| 1081 |
each page. |
| 1082 |
\item{3.} |
| 1083 |
Run |dvipdfm| with the |-t| or |-dt| option. |
| 1084 |
|
| 1085 |
The |dvipdfm| distribution includes a sample |
| 1086 |
shell script called |dvipdft| which is a wrapper |
| 1087 |
for |dvipdfm| that generates thumbnails. |
| 1088 |
|
| 1089 |
|Dvipdfm| searches for the thumbnail images |
| 1090 |
in the directory specified by the TMP or TEMP |
| 1091 |
environment variables, or in the current directory. |
| 1092 |
The thumbnails must have the same base name as the PDF output |
| 1093 |
file with an extension indicating the number of the page. |
| 1094 |
For example, to create a thumbnailed document named |foo.pdf| |
| 1095 |
you would need to generate thumbnail images in files named |
| 1096 |
|foo.1|, |foo.2|, etc. |
| 1097 |
|
| 1098 |
\dest{fontmap}\section{Font Mapping} |
| 1099 |
\TeX\ font names can be |
| 1100 |
mapped into arbitrary physical (PostScript) font names via |
| 1101 |
the map file named |t1fonts.map|. The file is |
| 1102 |
similar to the |psfonts.map| file used by |dvips| |
| 1103 |
and other drivers. Each line in the |
| 1104 |
file consists of one to three fields delimited |
| 1105 |
by white space, followed by options that apply to that font. |
| 1106 |
The complete list of recognized options |
| 1107 |
appears in \link{Table~4}{options}. |
| 1108 |
|
| 1109 |
Sample map file lines are\nobreak |
| 1110 |
\begintt |
| 1111 |
cmr10 ot1 -r |
| 1112 |
ptmro8r 8r Times-Roman -s 0.167 |
| 1113 |
pncbo8r 8r pncb8a -s 0.167 |
| 1114 |
\endtt |
| 1115 |
|
| 1116 |
The first field of each line |
| 1117 |
is the \TeX\ font name. The second |
| 1118 |
field, which is optional, is the encoding name (|.enc| will |
| 1119 |
be appended to this name, if necessary |
| 1120 |
to locate an encoding file). The |
| 1121 |
encoding files have the same format |
| 1122 |
as those used for |dvips|. |
| 1123 |
The third optional field is {\it either} the PostScript font |
| 1124 |
name (if one of the standard PostScript fonts) {\it or} |
| 1125 |
the file name of a Type~1 binary font file (PFB file). |
| 1126 |
The {}.pfb extension is assumed by the program. |
| 1127 |
three fields. If the encoding field is unspecified, |
| 1128 |
|dvipdfm| used the default encoding supplied with |
| 1129 |
the Type~1 font. If the name field is unspecified, |
| 1130 |
|dvipdfm| looks for a Type~1 binary font file |
| 1131 |
having the same name as the \TeX\ font name. |
| 1132 |
If there is {\it no} line in the map file, |
| 1133 |
the behavior is as if a line was specified |
| 1134 |
without the second or third field. |
| 1135 |
The keywords |default| or |none| are |
| 1136 |
recognized in the encoding field so that |
| 1137 |
a third field may be specified while still |
| 1138 |
having default behavior in the second field. |
| 1139 |
|
| 1140 |
Currently, three options may be specified for each font |
| 1141 |
as shown in \link{Table~4}{options}. |
| 1142 |
\topinsert |
| 1143 |
{\dest{options}} |
| 1144 |
\centerline{\colored{\blue}{\subheadingfont Table~4---Font options |
| 1145 |
recognized by |dvipdfm| in the font map file}} |
| 1146 |
\bigskip\nobreak |
| 1147 |
\centerline{\vbox{\halign{{\tt #}\hskip |
| 1148 |
1em\strut&\vtop{\leftskip0pt\rightskip0pt\hsize=3.5in\noindent #}\cr |
| 1149 |
\omit\hfil\it Option\hfil&\omit\hfil \it Description \hfil\cr |
| 1150 |
\noalign{\smallskip\begincolor\red\hrule\endcolor\smallskip} |
| 1151 |
-r&{\it Remap the font to eliminate control characters.} This |
| 1152 |
option attempts to work around bugs in Acrobat reader that seem |
| 1153 |
to be triggered by characters that are encoded in certain positions. |
| 1154 |
Unfortunately, standard \TeX encodings normally use these positions.\cr |
| 1155 |
\noalign{\smallskip} |
| 1156 |
-e {\it number}&{\it Extend the font horizontally, multiplying the natural |
| 1157 |
width of the font by the specified number.} This is useful |
| 1158 |
for generating new fonts by widening existing fonts.\cr |
| 1159 |
\noalign{\smallskip} |
| 1160 |
-s {\it number}&{\it Slant the font using the specified number}. |
| 1161 |
This option is useful for building a slanted fonts from a font |
| 1162 |
for which there is no slanted font.\cr}}} |
| 1163 |
\endinsert |
| 1164 |
|
| 1165 |
\section{Configuration file} |
| 1166 |
{\dest{configuration}}Dvipdfm reads default command line options, such |
| 1167 |
as paper size, from a configuration |
| 1168 |
file contained in the |dvipdfm| directory of the TeX tree. |
| 1169 |
The format of this file is similar to the |dvips| file configuration |
| 1170 |
file format. Each line consists of a single command line switch |
| 1171 |
followed by any arguments. See the configuration file supplied |
| 1172 |
with the |dvipdfm| distribution for examples. |
| 1173 |
|
| 1174 |
\section{Including PostScript graphics images} |
| 1175 |
{\dest{postscript}}Dvipdfm provides support for illustrations |
| 1176 |
contained in external PostScript files. |
| 1177 |
It recognizes two distinct kinds of PostScript files---those |
| 1178 |
created by MetaPost and everything else. |
| 1179 |
|
| 1180 |
MetaPost |
| 1181 |
files output only a subset of PostScript and |
| 1182 |
are interpreted {\it natively} by |dvipdfm| |
| 1183 |
with its own internal minimal PostScript interpreter. |
| 1184 |
Also, MetaPost output files contain \TeX\ font information in their header |
| 1185 |
comments, so that they can be easily integrated with \TeX\ by DVI |
| 1186 |
drivers. Dvipdfm recognizes this font information and uses the \TeX\ |
| 1187 |
fonts defined in the MetaPost header. |
| 1188 |
|
| 1189 |
|
| 1190 |
All other PostScript files require an external |
| 1191 |
program to convert the image to PDF format before |
| 1192 |
|dvipdfm| can include the image. |
| 1193 |
The freely available GhostScript is capabable of performing this conversion |
| 1194 |
for most images. |
| 1195 |
|
| 1196 |
The user must specify the command line required |
| 1197 |
to invoke an external program to perform this conversion. |
| 1198 |
The command line required to invoke the conversion |
| 1199 |
program is specified using the |-D| command |
| 1200 |
line (or configuration file) option. The string passed to the |-D| command |
| 1201 |
line option is a C-style string that is parsed by |dvipdfm|. Within the string, |
| 1202 |
expansions are performed as described in \link{Table~5}{expansion}. |
| 1203 |
For example, to use GhostScript, one might use the |
| 1204 |
command line |
| 1205 |
|
| 1206 |
\bigskip |
| 1207 |
|
| 1208 |
{\tt -D "cat \%i \vrule\ gs -q -sDEVICE=pdfwrite -sOutputFile=\%o - -c quit" } |
| 1209 |
|
| 1210 |
|
| 1211 |
\topinsert |
| 1212 |
{\dest{expansion}} |
| 1213 |
\centerline{\colored{\blue}{\subheadingfont Table~5---Expansions |
| 1214 |
performed in the -D string.}} |
| 1215 |
\bigskip\nobreak |
| 1216 |
\centerline{\vbox{\halign{{\hfil\tt #\hfil}\hskip |
| 1217 |
1em\strut&\vtop{\leftskip0pt\rightskip0pt\hsize=3.5in\noindent #}\cr |
| 1218 |
\omit\hfil\it Variable\hfil&\omit\hfil \it Description \hfil\cr |
| 1219 |
\noalign{\smallskip\begincolor\red\hrule\endcolor\smallskip} |
| 1220 |
\%i&{\it Expanded to the full path of the EPS file to be included}\cr |
| 1221 |
\noalign{\smallskip} |
| 1222 |
\%o&{\it Expanded to the full path name of the PDF file to be |
| 1223 |
generated}. The command line must be able to create a file |
| 1224 |
with the name supplied by dvipdfm.\cr |
| 1225 |
\noalign{\smallskip} |
| 1226 |
\%b&{\it Expanded to the ``basename'' of the EPS file that is being included.} |
| 1227 |
The ``basename'' is the full path of the EPS file with the |
| 1228 |
last ``.'' and any trailing name extension removed.\cr |
| 1229 |
}}} |
| 1230 |
\endinsert |
| 1231 |
|
| 1232 |
\section{Compatibility with other DVI drivers} |
| 1233 |
Compatibility with other DVI drivers is achieved |
| 1234 |
by support for the following ``standard'' special calls. |
| 1235 |
Many legacy DVI files can be processed by |dvipdfm|, |
| 1236 |
so long as they use fairly standard special commands. |
| 1237 |
For example, |dvipdfm| can process DVI files generated |
| 1238 |
that use the |
| 1239 |
|\color|, |\rotatebox|, and |\includegraphics| macros |
| 1240 |
from the standard La\TeX\ Graphics bundle even if |dvips| was the target DVI driver, |
| 1241 |
e.g., |
| 1242 |
|
| 1243 |
\begintt |
| 1244 |
\usepackage[dvips]{graphics} |
| 1245 |
\usepackage[dvips]{color} |
| 1246 |
\endtt |
| 1247 |
|
| 1248 |
Specifically, |dvipdfm| understands the following standard special commands: |
| 1249 |
|
| 1250 |
\beginlist |
| 1251 |
\item{$\bullet$} The TPIC specials. |
| 1252 |
|
| 1253 |
\item{$\bullet$} The HyperTeX (HTML) hyperlink specials. |
| 1254 |
|
| 1255 |
\item{$\bullet$} The ``color'' specials supported by |dvips| and |
| 1256 |
other drivers. |
| 1257 |
|
| 1258 |
\item{$\bullet$} The ``PSfile'' and ``plotfile'' specials for PS/EPS file inclusion |
| 1259 |
supported by |dvips| and other drivers. Dvipdfm uses a user-specified |
| 1260 |
external program to convert the PostScript file to PDF format |
| 1261 |
before including it. |
| 1262 |
|
| 1263 |
\item{$\bullet$} The raw PostScript ``ps:'' special supported by |dvips| and |
| 1264 |
other drivers. Only a few PostScript operators are supported; |
| 1265 |
|dvipdfm| does not include a complete PostScript interpreter. |
| 1266 |
Complex PostScript code, such as that embedded by the PSTricks |
| 1267 |
package, is not supported. |
| 1268 |
\endlist |
| 1269 |
|
| 1270 |
\section{LaTeX Support and Ebb} |
| 1271 |
Support for the La\TeX\ graphics bundle and |hyperref| |
| 1272 |
are available. A driver file named |dvipdfm.def| |
| 1273 |
is distributed with the standard La\TeX |
| 1274 |
graphics bundle. The latest version |
| 1275 |
of the |dvipdfm.def| file is supplied |
| 1276 |
with the |dvipdfm| distribution. |
| 1277 |
The file required for |hyperref| |
| 1278 |
support is called |hdvipdfm.def|. |
| 1279 |
|
| 1280 |
To facilitate La\TeX\ support, I distribute a companion program |
| 1281 |
called |ebb|, which extracts bounding boxes from graphics files. If |
| 1282 |
you want to include JPEG, PNG, or PDF files in your document, you can run |
| 1283 |
|ebb| on the JPEG, PNG, or PDF file to create the |.bb| files. |
| 1284 |
The bounding box file will be similarly named with an extension of |.bb|. |
| 1285 |
For DOS 8+3 compatibility, an original file name extension |
| 1286 |
of |.jpg|, |.png|, or |.pdf| is removed before creating the name of |
| 1287 |
the |.bb| file. An extension of |.jpeg| is also recognized and similarly removed. |
| 1288 |
|
| 1289 |
\newpage |
| 1290 |
\section{References} |
| 1291 |
\tolerance=1000\hbadness=1000 |
| 1292 |
\bibitem\dest{pdfmanual}{\it Portable Document |
| 1293 |
Format Reference Manual}, Version 1.2, Adobe Systems Incorporated, 1996. |
| 1294 |
Available at the following URL: {\tt http://www.adobe.com}. |
| 1295 |
|
| 1296 |
\bibitem\dest{pdfprimer}Thomas Merz, |
| 1297 |
{\it Web Publishing with Acrobat/PDF}, |
| 1298 |
Springer-Verlag, 1997, ISBN 3-540-63762-1. Chapter~6 of this book is available |
| 1299 |
at the URL: |http://http://www.ifconnection.de/~tm|. |
| 1300 |
|
| 1301 |
\bibitem\dest{acrotex}D. P. Story, {\it AcroTeX}, The AcroTeX home page |
| 1302 |
is located at the URL: |http://www.math.uakron.edu/~dpstory/acrotex.html|. |
| 1303 |
|
| 1304 |
\bye |