Debian Codegraph @

texmf-dist/doc/dvipdfm/dvipdfm.tex

raw
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