summaryrefslogtreecommitdiff
path: root/Master/texmf/doc/dvipdfm/dvipdfm.tex
blob: 8ebfc3011a7fd7a8d922d78312cd03d8057b5c6c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
% $Header$
% \special{ pdf: pagesize width 8.5truein height 11.0truein}
\special{  pdf:  docview <</PageMode /UseOutlines>>}%
\catcode`\ =11\def\space{ }\catcode`\ =10
% Page layout
\tolerance=2000
\magnification\magstephalf
\advance\hoffset by 0.5truein
\advance\voffset by 0.5truein
\advance\hsize by -1.0truein
\advance\vsize by -1.0truein
\def\makefootline{\baselineskip=40pt\line{\the\footline}}
%
%  Some helpful symbols
\def\rtm{{\font\r=cmss10 at 4pt
\font\c=cmsy5
\setbox0\hbox{\c\char13}\skip0\wd0\box0\setbox0\hbox{\r R}\advance\skip0 by
\wd0\kern-0.5\skip0\box0}}
\def\tm{{\font\r=cmss10 at 4pt \hbox{\r TM}}}%
%
% Verbatim mode borrowed from manmac macros
%
\outer\def\begindisplay{\obeylines\startdisplay}
{\obeylines\gdef\startdisplay#1
  {\catcode`\^^M=5$$#1\halign\bgroup\indent##\hfil&&\qquad##\hfil\cr}}
\outer\def\enddisplay{\crcr\egroup$$}
\chardef\other=12
\def\ttverbatim{\begingroup \catcode`\\=\other \catcode`\{=\other
 \catcode`\}=\other \catcode`\$=\other \catcode `\&=\other
 \catcode`\#=\other \catcode`\%=\other \catcode `\~=\other
 \catcode`\_=\other \catcode`\^=\other
  \obeyspaces \obeylines \tt}
{\obeyspaces\gdef {\ }}
\outer\def\begintt{$$\let\par=\endgraf\ttverbatim \parskip=0pt
 \catcode`\|=0 \rightskip=-5pc \ttfinish}
{\catcode`\|=0 |catcode`|\=\other
 |obeylines % end of line is now active
 |gdef|ttfinish#1^^M#2\endtt{#1|vbox{#2}|endgroup$$}}
\catcode`\|=\active
{\obeylines\gdef|{\ttverbatim\spaceskip=\ttglue\let^^M=\ \let|=\endgroup}}
\newskip\ttglue
\ttglue=0.5em plus 0.25em minus 0.15em
%
%
% Some color definitions
% 
\def\begincolor#1{\special{pdf:bc #1}}%
\def\endcolor{\special{pdf:ec}}%
\def\colored#1#2{%
  \begincolor{#1}#2\endcolor}
\def\red{[0.8 0.5 0]}%
\def\green{[0 1 0]}%
\def\blue{[0 0.4 0.8]}%
\def\yellow{[0.8 0.9 0.1]}%
\def\linkcolor{[0.5 0.0 0.7]}%
%
% Small help for images
\def\reserve#1#2#3{\setbox0\hbox{}\wd0=#1
                   \ht0=#2\special{#3}\box0}
\def\nreserve#1#2#3{\setbox0\hbox{}\wd0=#1
                   \ht0=#2{#3}\box0}
%
% Some font definitions
%
\font\maintitlefont=cmti12 at 20.74pt
\font\headingfont=cmss12 at 14.4pt
\font\subheadingfont=cmss12 at 12pt
%
%
% Miscellaneous token lists
%
\newtoks\title\newtoks\author\newtoks\version
\newtoks\date
%
% Bibliography counters
\newcount\biblioitems\biblioitems=0
\def\bibitem{\medskip\advance\biblioitems by 1\item{[\the\biblioitems]}}
%
% Counters for section levels
%
\newcount\sectioncount\newcount\ssectioncount\newcount\sssectioncount
\sectioncount0\ssectioncount0\sssectioncount0
%
\newskip\indentlevel\indentlevel=\parindent
\newskip\secskip\secskip=24pt plus 1pt minus 2pt
\newskip\subsecskip\subsecskip=16pt plus 1pt minus 2pt
\def\beginlist{\par\nobreak\advance\leftskip by \indentlevel\advance\rightskip by
\indentlevel\medskip\nobreak}
\def\endlist{\par\advance\leftskip by -\indentlevel\advance\rightskip by
-\indentlevel\medskip}
%
%
\def\settitle{%
  {\maintitlefont\colored{\blue}{\the\title}}%
  \special {pdf:  docinfo << /Title (\expandafter\the\title) >>}}
%
\def\setauthor{%
  {\headingfont\colored{\blue}{\the\author}}%
  \special {pdf:  docinfo << /Author (\the\author) >>}}%
%
\def\setversion{%
  {\subheadingfont{\the\version}}%
}%
\def\setdate{%
  {\subheadingfont{\the\date}}%
}%
\def\setlink#1{\colored{\linkcolor}{#1}}%
%  
\def\setheading#1{%
  {\headingfont\colored{\blue}{#1}}\raise\baselineskip
  \hbox{\special{pdf: outline 1 << /Title (#1) /Dest [
@thispage /FitH @ypos ]  >> }}}%
%
\def\setsubheading#1{%
  {\subheadingfont\colored{\blue}{#1}}\raise\baselineskip
  \hbox{\special{pdf: outline 2 << /Title (#1) /Dest [
@thispage /FitH @ypos ]  >> }}}%
%
% \def\link#1#2{\setbox0\hbox{\setlink{#1}}%
%    \leavevmode\special{pdf: ann width \the\wd0\space height \the\ht0\space depth \the\dp0
%      << /Type /Annot /Subtype /Link /Border [ 0 0 0 ] /A << /S /GoTo
%      /D (#2) >> >>}\box0\relax}%
\def\link#1#2{%
  \leavevmode\special{pdf: bann 
    << /Type /Annot /Subtype /Link /Border [ 0 0 0 ] /A << /S /GoTo /D (#2)
>>
>>}\setlink{#1}\special{pdf: eann}\relax}
%
\def\dest#1{\hbox{\raise14pt\hbox{\special{pdf:dest (#1) [ @thispage /FitH
@ypos ]}}}}%
%
\def\maketitle{\noindent\settitle\hfill\setauthor\par
          \hrule height 1.0pt\medskip
          \noindent\setversion\hfill\setdate\vskip0.3in}%
%
\def\section#1{\advance\sectioncount by 1\ssectioncount0
\vskip-\lastskip\vskip\secskip\goodbreak
\noindent\setheading{\the\sectioncount. #1}\medskip\nobreak}%
\def\subsection#1{\vskip-\lastskip\advance\ssectioncount by 1%
\vskip\subsecskip\noindent
\setsubheading{\the\sectioncount.\the\ssectioncount\
          #1}\par\nobreak\smallskip}%
%
\def\display#1{\medskip\line{\quad #1\hfil}\medskip}
\def\example{\medskip\noindent{\it Example:\quad}\nobreak}
\def\note{\medskip\noindent{\it Note:\quad\nobreak}}
\def\syntax{\medskip\noindent{\it Syntax:\quad}\nobreak}
\def\description{\medskip\noindent{\it Description:\quad}\nobreak}
%
\def\newpage{\vfill\eject}
%
\def\dvipdfm{{\tt dvipdfm}}%
%
\title{Dvipdfm User's Manual}
\author{Mark A. Wicks}
\version{Version 0.12.4b}
\date{September 19, 1999}
\maketitle
\section{Introduction}
This package is a DVI (\TeX) to PDF conversion utility,
having the following features:

\beginlist
\item{$\bullet$} {\it Support for outline entries (also called bookmarks), named destinations,
and \link{annotations}{Annotate} (including hyperlinks, forms and widgets).}  Nearly
every Acrobat Distiller pdfmark is approximated.

\item{$\bullet$} {\it Support for ``standard'' DVI specials such
as Hyper\TeX\ (HTML), TPIC, color specials, |PSfile|, and other PostScript specials.}

\item{$\bullet$} {\it Native support for inclusion of
\link{MetaPost}{postscript} output and
inclusion of arbitrary \link{PostScript}{postscript} files with help from an external program.}

\item{$\bullet$} {\it Support for thumbnails with a little help from GhostScript to
generate the thumbnails.}

\item{$\bullet$} {\it Support for arbitrary, nested linear transformations
of typeset material.}  Any material on the page, including
\TeX\ text, may be \link{scaled and rotated}{textxform}.

\item{$\bullet$} {\it Ability to include the first page of a \link{PDF file}{pdfimage} as
an encapsulated object along with its embedded resources such as fonts.}
Included PDF images may be cropped by supplying a bounding box.
Note:  Currently, this doesn't work if the contents stream
has multiple segments. 

\item{$\bullet$} {\it Ability to include \link{JPEG}{jpegimage} and
PNG bitmapped images as encapsulated objects.}

\item{$\bullet$} {\it An internal color stack.} A color stack allows you to change the current color, pushing the
current color onto a stack.  At any time, the original color
can be popped from the stack.  This is useful, for example, in
headlines, that may have a different color from the current text.
The headline macro can restore the current color without knowing
what it is.

\item{$\bullet$} {\it Support for partial font embedding and Flate compression
to reduce file size}

\item{$\bullet$} {\it Support for font reencoding to work around encodings
that aren't fully supported by the Acrobat suite of products.}

\item{$\bullet$} {\it Balanced page and destination trees.} Balancing
these trees improves reader access speed 
on very large documents.

\endlist

The electronic version of the document exercises
some of the hypertext features and serves as
a sample input file for |dvipdfm|.
It assumes the reader has some familiarity with the basic features
of the Portable Document Format.  The PDF specification
is distributed by Adobe Systems\link{[1]}{pdfmanual}.
An excellent source for information about PDF documents
in general is \link{[2]}{pdfprimer}.  Information about
using \TeX\ to construct PDF documents (mainly using Distiller) is the
AcroTeX home page\link{[3]}{acrotex}.

Currently, the widely accepted method to generate PDF file from \TeX\
is to use Adobe's Acrobat Distiller on a PostScript
file produced by {\tt dvips}.
The hyperlink features are accessed by using \TeX\ |special| primitives
to embed pdfmarks in the PostScript produced by |dvips|.
H\`an Th\'e Th\`an's PDF\TeX\ project is an alternative method
of generating PDF from \TeX\ source.
Although quite good and fairly mature, the PDF\TeX\ project
modified \TeX\ itself to add primitives that support the PDF features.
I prefer to work with \TeX\ unmodified, as released by Donald Knuth
(call me a purist).
There is an existing DVI to PDF driver called
|dvipdf| written by Sergey Lesenko.  At present, it's not widely
available, so I haven't used it.  I wrote |dvipdfm|
mainly as an exercise to get at the features
of PDF I was trying to use.  This |dvipdfm| project demonstrates that many features
of PDF can be accessed by using a DVI driver.
The PDF features are activated in the driver via
\TeX\ |special| primitives.

Even though Distiller is the best method of generating PDF (and
probably will remain so for some time) I have several reasons for
seeking alternatives to Distiller.
First, Distiller isn't available for my principle operating
system---Linux.

My second objection is philosophical.
\TeX\ is a programming language.
A DVI file is a page description consisting of very
simple program instructions that have no branching or
decision instructions.
Similarly PostScript is a complete programming language,
while PDF is a page description language consisting
of simple program instructions
without any branching or decision capabilities.
\TeX\ is like PostScript (without the graphics)
while DVI is like PDF (without the graphics or the hyperlinks).
Creating PDF from DVI using Distiller requires converting a page description to a program,
and converting that program back to a page description.
To continue this analogy,
Pdfmarks are PostScript ``escapes'' and are meant for the Distiller.
\TeX\ |\special| primitives are \TeX\ ``escapes'' and are meant for the DVI driver.
It seems natural to go directly from DVI to PDF, where \TeX\ replaces
PostScript, the DVI driver replaces Distiller,
and \TeX\ |\special| primitives replace the pdfmarks.

Unfortunately, until graphics software
begins to produce PDF content streams or encapsulated
PDF objects, PostScript will remain the easiest
way to include graphics in \TeX\ documents.
I would hope that in the future, graphics programs
will begin to produce PDF content streams or PDF objects that
may be included using a DVI to PDF translator.  Either
of these may be easily embedded using \dvipdfm\ or a similar driver.

\section{Command Line Options}
\link{Table~1}{commandline} lists the options
that are available on the command line.
\par\noindent
Note: Several flags may be specified at once:
\example
\begintt
dvipdfm -ecz 9 test.dvi
\endtt

\topinsert
{\dest{commandline}}
\centerline{\colored{\blue}{\subheadingfont Table~1---Command line options
recognized by |dvipdfm|}}
\bigskip\nobreak
\centerline{\vbox{\halign{{\tt #}\hskip
1em\strut&\vtop{\leftskip0pt\rightskip0pt\hsize=3.5in\noindent #}\cr
\omit\hfil\it Option\hfil&\omit\hfil \it Description \hfil\cr
\noalign{\smallskip\begincolor\red\hrule\endcolor\smallskip}
-c&{\it Disable color specials}  Specifying this option
forces all color commands to be ignored.  This is useful for printing a color document
on a black and white printer.\cr
\noalign{\smallskip}
-e&{\it Disable partial font embedding.}  This may be useful
for forms which need complete fonts, or if you run accross a PFB
file that \dvipdfm\ cannot correctly parse.\cr
\noalign{\smallskip}
-f&{\it Set font map file name}.  See
the \link{Font Mapping}{fontmap} section for additional information.\cr
\noalign{\smallskip}
-m {\it number}&{\it Specify an additional magnification for
the document}.\cr
\noalign{\smallskip}
-o {\it filename}&{\it Set the output PDF file name}.\cr
\noalign{\smallskip}
-p {\it papersize}&{\it Specify the output papersize.}
Valid paper sizes are |letter|, |legal|, |ledger|, |tabloid|,
|a4|, or |a3|.  The default is |letter|.  Arbitrary paper
sizes can be specified via \TeX\ special commands,
which is the recommended method.\cr
\noalign{\smallskip}
-l&{\it Landscape the document.}  This is only
meaningful for paper sizes specified on the command line.\cr
\noalign{\smallskip}
-s {\it page\_ranges}&{\it Select a subset of pages from the DVI file.}
The {\it page\_ranges} specifier is a set of comma-separated page
ranges---e.g., |dvipdfm -s 10-12,10-20|.  If the first
page in a range is empty (e.g., |dvipdfm -s -10|), it represents
the beginning of the document.  If
the last page in a range is empty (e.g., |dvipdfm -s 10-|), it selects the end of the document.\cr
\noalign{\smallskip}
-t&{\it Embed thumbnail images.} The thumbnails must be generated by a
separate program. Details are discussed \link{later}{thumbnails} in this document\cr
\noalign{\smallskip}
-d&{\it Delete thumbnail images after embedding.}\cr
\noalign{\smallskip}
-x {\it number}&{\it Specify the horizontal offset
for the document.}  The default is 1.0in.\cr
\noalign{\smallskip}
-y {\it number}&{\it Specify the vertical offset
for the document.}  The default is 1.0in.\cr
\noalign{\smallskip}
-z {\it number}&{\it Specify the compression level.}
Valid compression levels range from 0 to 9, with 0 indicating
no compression.  A compression level of 9 is the default.\cr
\noalign{\smallskip}
-v&{\it Be verbose.}  Among other things, dvipdfm
will display complete file names as various files are opened.\cr
\noalign{\smallskip}
-vv&{\it Be more verbose.}\cr}}}
\endinsert

\section{General Concepts and Syntax for TeX Specials}
Each \TeX\ |\special|
represents a separate command to the \dvipdfm\ 
driver.  Each |special| must begin with ``|pdf:|''
to identify that ||special|| as a command for the \dvipdfm\ driver.
A |\special| beginning with any other characters is ignored
by the driver.  Leading spaces are ignored.  The characters ``|pdf:|''
are immediately followed by a \dvipdfm\ command.  These commands
are documented in \hbox{Sections~3--6}.

\subsection{PDF Object Syntax and Variable Expansion}
With one exception, the syntax used for PDF objects
within each |\special| specials follows
the PDF specification.
The one exception is variable expansion.
In the syntax specifications that follow, {\it PDF\_Object}
means that an arbitary PDF object is expected.  Similarly
{\it PDF\_Array} indicates that a PDF array is expected, {\it PDF\_Dict}
inciates that a PDF dictionary is expected, etc.
See the \link{reference manual}{pdfmanual}\
for a complete list of PDF object types.

The single extension implemented in this driver
allows a symbol name of the
form |@|{\it name} whereever any PDF object is expected.
The {\it name} may contain any characters allowed
in a PDF name.
A user-defined symbol beginning with |@| expands to an indirect
reference to the user-defined PDF object.  This feature replaces
the |{|{\it name}|}| syntax used with pdfmarks.
In addition to the user-defined names, some names
are defined by the driver.
The driver defined variables are for
referencing objects such as the current page, future pages,
or the current location on the current page.
The driver defined variables appear in \link{Table~2}{drivervariables}.
\topinsert
{\dest{drivervariables}}
\centerline{\colored{\blue}{\subheadingfont Table~2---List of driver
defined variables}}
\bigskip\nobreak
\centerline{\vbox{\halign{{\tt #}\hskip
1em&\vtop{\leftskip0pt\rightskip0pt\hsize=3.0in\noindent #}\cr
\omit\hfil\it Variable\hfil&\omit\hfil \it Description \hfil\cr
\noalign{\smallskip\begincolor\red\hrule\endcolor\smallskip}
@catalog&A reference to the document's catalog.\cr
\noalign{\smallskip}
@names&A reference to the document's /Names dictionary.\cr
\noalign{\smallskip}
@pages&A reference to the root of the document's /Pages tree.\cr
\noalign{\smallskip}
@resources&A reference to the current page resource dictionary.\cr
\noalign{\smallskip}
@thispage&A reference to the current page.\cr
\noalign{\smallskip}
@page{\it n}&A reference to page {\it n}.\cr
\noalign{\smallskip}
@nextpage&A reference to the page following |@thispage|.\cr
\noalign{\smallskip}
@prevpage&A reference to the page preceding |@thispage|.\cr
\noalign{\smallskip}
@ypos&A {\it number} representing the current vertical position in units of PDF points.\cr
\noalign{\smallskip}
@xpos&A {\it number} representing the current horizontal position in units of PDF points.\cr
}}}
\endinsert

In the syntax specifications that follow, several
standard conventions are followed.  Terminal
characters that appear in the command 
are typeset in the |\tt| font, e.g., |object|.
Nonterminal symbols are typeset in italics.
Optional parameters are surrounded by brackets, e.g.,
[{\it optional\_argument}].  An item followed
by~``{*}'' represents an item that may appear
zero or more times.  An item followed by~``{+}''
represents a required item that may appear multiple times.

\subsection{Dimensions and transformations}
Interaction with the |dvipdfm| driver consists
of short commands with a few arguments delimited by white space.
Typically the arguments are PDF objects.
Two exceptions are dimension specifications and transformations.

In the \TeX\ style, a dimension specification consists of one of the keywords
|width|, |height|, or |depth| followed by a dimension
consisting of a numerical value, followed by a unit for the dimension.  The
unit will typically be |pt| (which represents a \TeX\ point, not a
PDf point) but |mm|, |cm| and |in| are also allowed.
If the document is magnified, the ``true'' dimensions |truept|,
|truemm|, |truecm|, and |truein| may be used.  The notation
{\it dimension\/} in a syntax description means a dimension is expected.

A transformation consists of one of the keywords |scale|, |xscale|,
|yscale|, or |rotate| followed by a numerical value.  In the
case of |rotate| the value is the rotation angle in degrees.
The notation
{\it transformation} means a transformation is expected.
In the case of included images originating from
PDF/PostScript files, a clipping or bounding box may be specified
as part of the ``transformation.''  The bounding
box specification consists of the keyword |bbox|
followed by four numerical values, which are 
the standard PostScript |llx|, |lly|, |urx|, and |ury|
coordinates of the bounding box.

\section{Document Construction Commands}
All commands are executed via \TeX\ |\special| primitives
prefixed with the characters ``|pdf:|''.
\example
\begintt
\special{ pdf: out 1 << /Title (Introduction)
                        /Dest [ 1 0 R /FitH 234 ] >>
\endtt

\dest{Annotate}
\subsection{Annotate}
\hbox to 0pt{\hskip-1.0in\special{pdf: ann width 3.0in height 36pt << /Type /Annot /Subtype /Text
/Contents (This is a /Text Annotation that looks like a sticky note.) >>}\hss}
\syntax
{\tt annotate} [{\tt @}{\it name}] {\it dimension}+ {\it PDF\_dictionary}
\description
The |annotate| (|annot| or |ann|) command defines an annotation.
Annotations are typically used for
notes, hyperlinks, forms, or widgets.
The parameter {\it name} is an optional alphanumeric identifier
and {\it PDF\_dictionary} is a valid PDF dictionary after variable expansion.
If {\tt @}{\it name} is specified, it may be used in
other PDF objects to refer to this annotation.
One or more {\it dimension} parameters are required
and each consists of the keyword
{\tt height}, {\tt width}, or {\tt depth} followed
by an appropriate length, specified as per \TeX\null.
The |width| must be nonzero and either the |height| or |depth|
must be nonzero.
Each length is a number followed by a unit, such as {\tt pt},
{\tt in}, or {\tt cm}.  Since these values
would typically be entered by \TeX, a {\tt pt}
is a \TeX\ point, not a PDF point.

\example The annotation in this subsection
was typeset with
\begintt
\special{pdf: ann width 3.0in height 36pt
     << /Type /Annot /Subtype /Text
        /Contents (This is a /Text Annotation 
        that looks like a sticky note.) >>}
\endtt

\subsection{Begin Annotation}
\syntax
{\tt beginann} {\it PDF\_dictionary}
\description
The |beginann| (|bann| or |bannot|) command begins a breakable annotation.
Dvipdfm tries to determine the boundaries of the annotation automatically.
Such an annotation may be broken over several lines (or even several pages).
Unlike |annot|, the annotation may be not be referred to by name later,
since there may be more than once instances of the annotation.
The |beginann| command needs not dimension because |dvipdfm|
computes the correct bounding box on the fly.

Note:  Link breaking is easily fooled at page breaks.  If you have problems
with the header or footer wanting to become part of the link, you can
insert a |nolink| command at the beginning of the footer and a |link|
command at the end of the footer.

\subsection{End Annotation}
\syntax
{\tt endann}
\description
The |endann| (|eann| or |eannot|) terminates a breakable annotation.

\subsection{Link}
{\tt link}
\description
The |link| command instructs the link breaking algorithm to resume its
operation after a |nolink| command.

\subsection{Nolink}
{\tt nolink}
\description
The |nolink| command instructs the link breaking algorithm to suspend
it operation.  This is only required if there is material inserted
on the page in the {\it middle} of a link.  For example, when a link
is broken at the end of a page, the header and footer are inserted
in the middle of the link, but are not part of the link.  Material
that is inserted between a |nolink| and |link| will not become
part of the link.  The |nolink| and |link| escapes are not necessary
with the standard LaTeX header and footer lines, but may become necessary
if these are changed.

\subsection{Dest}
\syntax
{\tt dest} {\it PDF\_String} {\it PDF\_Dest}
\description
The |dest| command defines a named destination.
The {\it PDF\_String} is a PDF string naming
the destination.  This string may be used in the destination
fields of annotations and outline entries to refer to
this destination.  {\it PDF\_Dest} is a PDF
destination object (typically an array).
\example
\begintt
\special{pdf: dest (listofreferences) [ @thispage /FitH @ypos ]}
\endtt

\subsection{Docinfo}
\syntax
{\tt docinfo} {\it PDF\_dictionary}
\description
The |docinfo| command adds the keys in the specified dictionary to the
document's |/Info| dictionary.  All keys are optional, but may include
the keys |/Author|, |/Title|, |/Keywords|, |/Subject|,
and |/Creator|.
\example
\begintt
\special{pdf: docinfo << /Author (Mark A. Wicks)
                         /Title (This Document) >>}
\endtt

\subsection{Docview}
\syntax
{\tt docview} {\it PDF\_dictionary}
\description
The |docview| command adds the keys in the specified dictionary to the
document's |/Catalog| dictionary.  All keys are optional, but may include
the keys |/PageMode|,
|/URI|, |/OpenAction|, |/AA|
and |/ViewerPreferences|.  See the PDF Reference Manual
for documentation of these keys and additional keys.
\example
\begintt
\special{pdf: docview << /PageMode /UseThumbs >> }
\endtt


\subsection{Object}
\syntax
{\tt object} [@{\it name}] {\it PDF\_Object}
\description
The |object| (also |obj|) command creates a
PDF object.  The parameter {\it PDF\_Object} is any valid PDF object.  The
parameter {\it name} may be used to provide an indirect reference
to this object within other
objects. It will be expanded anywhere within
a {\tt special} where a PDF object is
expected. Typically {\it object} is an array
or dictionary.  It may be an empty array or
dictionary that can be constructed dynamically via
the {\tt put} command.
\example
\begintt
\special{pdf: object @mydict << /Firstpage @thispage >>}
\endtt

\subsection{Out}
\syntax
{\tt out} {\it number} {\it PDF\_dictionary}

\description
The |out| (also |outline|) command adds an outline (also called a ``bookmark'') entry
to the document.
The parameter {\it level\/} is an integer representing the
level of the outline entry (beginning with 1) and
{\it  PDF\_dictionary\/} must contain
the two keys {\tt /Title} and either {\tt /Dest} or {\tt /A}.
It may also contain the {\tt /AA} key.  These keys are documented
in the PDF Reference Manual.
\example
\begintt
out 1 << /Title (Section 1) /Dest [ @thispage /FitH @ypos ] >>
\endtt
which may be followed by
\begintt
out 2 << /Title (Section 1.1) /Dest [ @thispage /FitH @ypos ] >>
\endtt
\note
You may not skip levels.  A level~2 outline entry
must follow a level~1 outline
entry.  A level~3 outline entry must follow a level~2 outline
and cannot immediately follow a level 1 outline entry.

\subsection{Pagesize}
\syntax
{\tt pagesize} {\it dimension}+
\description
The |pagesize| command specifies the document's physical
paper size.  The |pagesize| command must be specified on
the first page and must precede the first annotation
or background color specification on the page.
In other words, it should occur as close to the
beginning of the document as possible.
\example
\begintt
pagesize width 11.0truein height 8.5truein
\endtt

\subsection{Put}
\syntax
\beginlist
{\tt put} @{\it name} {\it PDF\_Object}+
\endlist
or 
\beginlist
{\tt put} @{\it name} {\it PDF\_Dictionary}
\endlist
\description
The |put| command modifies an existing PDF object created with |obj|,
or one of the following internally defined objects: |@catalog|,
|@names|, |@pages|, |@thispage|, or |@resources|.
The first form is used when @{\it name} is an array.  The second
form is used when @{\tt name} is a dictionary.  More than
one object may be added to an array at once.
All keys in {\it PDF\_Dictionary}
are added to the dictionary represented by @{\it name}.
\example
\begintt
\special{pdf: put @mydict << /Nextpage @thispage >>}
\endtt

\subsection{Thread}
\syntax
{\tt thread} {\tt @}{\it name} {\it dimension}+ [ {\it PDF\_dictionary} ]

\description
The |thread| (or |art|) command adds a bead to an article.
An article is a collection of boxed regions in the document that should be
read consecutively.
Each bead using the same {\it name} belongs to the same article.
The {\it name} parameter is required.  The {\it dimension} parameter
defined the rectangular area belonging to the bead in
the same manner as for |annot|.
The optional PDF dictionary 
should supplied on one of the beads.  Its keys are
similar to the |/Info| dictionary accessed via the |docinfo| command
and would typically include the |/Title| and |/Author| keys.
Keys in the dictionary may be overwritten by subsequent {\tt thread} commands.
\example
\begintt
\special {pdf: thread @somearticle << /Title (Some title)
                                       /Author (Me) >>}
\endtt

\subsection{Close}
\syntax
{\tt close} @{\it name}
\description
The |close| writes the named PDF object created with |obj| to the PDF file.
No further |put| commands may be executed for this object.
The object may continue to be referenced using @{\it name}
indefinitely.  If the object is never closed, it will
be closed when |dvipdfm| finishes processing the document.

\section{Form XObjects}
The PDF specification allows an object to be stored once
and displayed at multiple locations throughout the document.
The following commands give access to this facility.

\subsection{Beginxobj}
\syntax
{\tt beginxobj} @{\it name} {\it dimension}+
\description
The |beginxobj| (or |bxobj|) command begins the definition of
a Form XObject.  All material typeset between the
|beginxobj| and |endxobj| commands will be captured
into the XObject.  The material can be displayed later
at an arbitrary location with the |usexobj| command.
The {\it name} may be used to refer to the object later,
either via the |usexobj| command or as an indirect
reference to the XObject if {\it name} is
used within the context of a {\it PDF\_Object}..
The required {\it dimension} identifies the extent
(i.e., bounding box) of the area to be captured.
It is specified in the same way as for |annot|.

The material will not display during the object definition.
In other words, if you are typsetting with \TeX\ you
should place the XObject in a box of dimension 0 so
you don't leave a white space hole where the object was
defined.
\example
\begintt
bxobj @myform width 2.0in height 24pt
\endtt

\subsection{Endxobj}
\syntax
{\tt endxobj}
\description
The |endxobj| (or |exobj|) command ends the previous
|beginxobj| definition.  Note that XObject definitions
may not be nested.  XObjects can be {\it used} within
other XObjects, however.
\example
\begintt
exobj
\endtt

\subsection{Usexobj}
\syntax
{\tt usexobj} @{\it name}
\description
The |usexobj| (or |uxobj|) command displays the 
form XObject previously defined and
associated with {\it name}.
\example
\begintt
uxobj @myform
\endtt

\section{Text Transformation Commands}
The commands in this section deal with transformation
of arbitrary material, which may include
material typeset by \TeX.  These
may also be used on included graphics images
if the commands in Section~8 won't do the job.

\subsection{BeginTransform}
\syntax
{\tt begintransform} {\it transformation}+

\description
The |begintransform| (|btrans| or |bt|) applies
the specified transformation to all subsequent text.
The scaling is applied first, followed by the rotation.
The reference point of a box following
the |\special| remains fixed.  Such transformations
may be nested to perform rotations within rotated text, for exmaple.

\example
\begintt
\special{pdf: bt rotate 90 xscale 2.0 }
\endtt

\subsection{BeginTransform}
\syntax
{\tt endtransform}
\description
The |endtransform| (|etrans| or |et|) concludes
the action of the immediately preceding |begintransform|
command.  All transformations must be closed
on the same page.  The driver will close
any pending unclosed transformations at the
end of the page and issue a warning message.
All material to be transformed
should probably be enclosed in a single box
to prevent any break.
\example
\begintt
\special{pdf: et}
\endtt


\section{Color Commands}
The commands in this section deal with manipulation of the color
stack.

\subsection{Setcolor}
\syntax
{\tt setcolor} {\it PDF\_Number$\vert$\it PDF\_Array}
\description
The |setcolor| (|scolor| or |sc|) command uses its
argument to set the default color for future marking operators.
The current color is replaced and may be retrieved
only by a subsequent |setcolor| command.  The argument
may be a single number, which is interpreted as a grayscale
value; a three element array, which is interpreted as an RGB
color space coordinate; or a four element array, which
is interpreted as a CMYK color space coordinate.
\example
\begintt
\special{ pdf: sc [ 1 0 0 ] }
\endtt

\subsection{Begincolor}
\syntax
{\tt begincolor} {\it PDF\_Number$\vert$\it PDF\_Array}
\description
The |begincolor| (|bcolor| or |bc|) command uses its
argument to set the default color for future marking operators.
The current color is pushed on the color stack.  The argument
may be a single number, which is interpreted as a grayscale
value; a three element array, which is interpreted as an RGB
color space coordinate; or a four element array, which
is interpreted as a CMYK color space coordinate.
\example
\begintt
\special{ pdf: bc [ 1 0 0 ] }
\endtt

\subsection{Endcolor}
\syntax
{\tt endcolor}
\description
The |endcolor| (|ecolor| or |ec|)
changes the default color to
match the color on the top
of the stack.  It removes
the color from the stack.
\example
\begintt
\special{ pdf: ec }
\endtt

\subsection{Bgcolor}
\syntax
{\tt bgcolor} {\it PDF\_Number$\vert$\it PDF\_Array}
\description
The |bgcolor| (|bbc| or |bgc|) command uses the value
of its argument to set the default color for the page
background.  The interpretation
fo the argument is the same as for the |begincolor| command.
The stack is not involved here.  There is no way
to go back to the previous background color.
\example
\begintt
\special{ pdf: bc [ 1 0 0 ] }
\endtt

\section{Image Commands}
The commands in this section deal with embedding
graphics into your PDF document.  The present
driver supports PDF, PNG, and JPEG graphics inclusion.

\subsection{Epdf}
\syntax
{\tt epdf} [|@|{\it name}] [{\it dimension}$\vert${\it transformation}]*  {\it PDF\_String}

\description
The {\tt epdf} command ``encapsulates'' the first page of a PDF
file named by {\it PDF\_String}
into a PDF XObject.  The resulting XObject is drawn
with the lower left corner at the current location of the page.
The optional @{\it name} parameter may be used
to reference this object within other objects.  If a
{\it dimension} is supplied, the object will be scaled to fit
that dimension.  A {\it transformation} consists of one of the keywords
|scale|, |xscale|, |yscale|, or |rotate|
followed by a number representing
the scaling factor or rotation angle in degrees.  Both {\it transformation} and {\it dimension}
parameters can be supplied as long as they are not logically
inconsistent.

Note: The object is stored as an XObject and can be redisplayed later by using the
|usexobj| function and specifying {\it name}.

\example
\begintt
\special{pdf:epdf yscale 0.50 width 4.0in
                              rotate 45 (circuit.pdf)}
\endtt

\subsection{Image}
\syntax
{\tt image} [@{\it name}] [{\it dimension} $\vert$ {\it transformation}]*  {\it PDF\_String}

\description
The {\tt image} command ``encapsulates'' an image
taken from the file named by {\it PDF\_String}.
This command functions just like |epdf|.  Value
image types may be PDF, JPEG, or PNG images.
This special will eventually replace the |epdf| special.

Note: The object is stored as an XObject and can be redisplayed later by using the
|usexobj| function and specifying {\it name}.

\section{Raw Page Marking Commands}
The commands in this section deal with embedding
raw PDF graphics operators into your PDF document.

\subsection{Bop}
\syntax
{\tt bop} {\it stream}
\description
The |bop| command specifies a marking
stream to be generated at the top of each page.
The parameter {\it stream} is any sequence
of marking operators and is added to the page's content stream.  
The stream is applied {\it to all pages} regardless
of where it appears in the document.
\example  The two horizontal lines appearing
at the top of each page in this document
were set with
\begintt
\special {pdf: bop  q 0 w 0.8 0.5 0 RG
               54 740 m 504 740 l 504 740.25 l 54 740.25 l b
               36 760 m 504 760 l 504 760.25 l 36 760.25 l b Q }
\endtt
\special {pdf: bop  q 0 w 0.8 0.5 0 RG
                           54 740 m 504 740 l 504 740.25 l 54 740.25 l b  
                           36 760 m 504 760 l 504 760.25 l 36 760.25 l b Q }

\subsection{Content}
\syntax
{\tt content} {\it stream}
\description
The |content| command specifies a marking
stream to be added to the current page at
the current location.  While it
is possible to change the color
state, etc., with this command, it is
not advised.  Use the color management
commands to change colors.


\subsection{Eop}
\syntax
\beginlist
{\tt eop} {\it stream}
\endlist
\description
The {\tt eop} specifies a marking stream to be generated at the end
of each page. The parameter {\it stream} is any sequence
of marking operators and is added to the page's content stream.  
The stream is applied {\it to all pages} regardless
of where it appears in the document.

\section{Graphics Examples}

The examples in this section illustrate some of the transformation
and image inclusion capabilities of \dvipdfm.

\dest{textxform}
\subsection{Text Transformation}
Tables with slanted entries are possible as shown
in \link{Table~3}{rotatedtable}.  This table was achieved using
various ``|bt rotate 35|'' commands.

The following line of text was done with nested
combinations of ``|bt rotate 10|'' and ``|bt rotate -10|''.

\def\up#1{\special{pdf:bt rotate 10}\hbox{#1}}
\def\down#1{\special{pdf:bt rotate -10}\hbox{#1}}
You \down{can} nest \down{the} \up{text}
trans\up{form}ation \up{capa}\down{bili}ties \down{to}
achieve \down{effects} \down{like}
{this}.
\special{pdf:et}\special{pdf:et}\special{pdf:et}\special{pdf:et}
\special{pdf:et}\special{pdf:et}\special{pdf:et}\special{pdf:et}
\special{pdf:et}
\vskip 0.5in


\def\rvr{\colored{\red}{\vrule}}\def\entry#1{\special{pdf:bt rotate 35}%
{\vbox to 0pt{\vss\hbox{\quad\colored{\blue}{#1}\quad}\vskip 1pt\colored{\red}{\hrule}}\special{pdf:et}}}
\topinsert
\dest{rotatedtable}
\bigskip
\centerline{\colored{\blue}{\subheadingfont Table 3---Example of rotated
text set in Computer Modern Roman}}
\bigskip
\centerline{\vbox to 0.45in{\vss\offinterlineskip\halign{#&#&#&#&#&#\cr
\entry{1994}&
\entry{1995}&
\entry{1996}&
\entry{1997}&
\entry{1998}&
\entry{1999}\cr
\noalign{\colored{\red}{\hrule}}
\strut\rvr&\rvr&\rvr&\rvr&\rvr&\rvr\crcr}}}
\bigskip
\endinsert

\dest{imageinclude}
\subsection{Image Inclusion}
 
The image in \link{Figure~1}{jpegimage} was included from a JPEG file.
The image shown in \link{Figure~2}{rotatedimage} comes from the same file,
but is loaded at a 50\% scale and a 45$^\circ$ rotation.

\topinsert
\dest{jpegimage}
\bigskip
\centerline{\reserve{1.50in}{2.05in}{pdf: image (mwicks.jpeg)}}
\medskip
\centerline{\subheadingfont
\begincolor{\blue}Figure~1---A JPEG image of the author.\endcolor}
\bigskip
\endinsert

\topinsert
\dest{rotatedimage}
\bigskip
\centerline{\reserve{0.75in}{1.25in}{pdf: image rotate 45 scale 0.50 (mwicks.jpeg)}}
\medskip
\centerline{\subheadingfont
\begincolor{\blue}Figure~2---Image of the author scaled by 0.5 and rotated
by 45$^\circ$.%
\endcolor}
\bigskip
\endinsert

By default, JPEG files are included
at a resolution of 100dpi so if you know the pixel size
of the image, you know how much space to reserve.
Any \TeX\ magnification is applied to the image
in addition to any scaling defined in the |\special|.
For example, this document sets |\magnification=\magstephalf|,
so the images are actually scaled by 1.095.  The first
image in this section has a printed width of 1.643in
even though 1.50in was specified in the |\special|.

Several command line utilities exist that read
the pixel dimensions of a JPEG file.  For PDF files,
you can |grep| on |/MediaBox| to get an indication
of the image size.  The |/MediaBox| dimensions are
in PDF points.

The image in \link{Figure~3}{pdfimage} was produced by embedding a PDF file
using |epdf|.

\topinsert
\dest{pdfimage}
\centerline{\reserve{2.41in}{2.6in}{pdf: epdf width 2.41in (transistor.pdf)}}
\medskip\centerline{\subheadingfont
\begincolor{\blue}Figure~3---An embedded PDF object.
\endcolor}
\endinsert
Notice that any resources required for the object
are also embedded.  In this case, the Times Roman font
resource was embedded along with the content stream.

\dest{thumbnails}\section{Thumbnails}
Thumbnails can be inserted automatically by |dvipdfm|
using the |-t| command line option.  However, |dvipdfm|
is unable to generate the thumbnails by itself.  This
must be done by some other program such as GhostScript.
The typical two-pass process to include thumbnails would be
\item{1.}
Run |dvipdfm| without the |-t| option (probably
using command line options optimized for speed and not space)
\item{2.}
Run GhostScript to generate the thumbnail images of
each page.
\item{3.}
Run |dvipdfm| with the |-t| or |-dt| option.

The |dvipdfm| distribution includes a sample
shell script called |dvipdft| which is a wrapper
for |dvipdfm| that generates thumbnails.

|Dvipdfm| searches for the thumbnail images
in the directory specified by the TMP or TEMP
environment variables, or in the current directory.
The thumbnails must have the same base name as the PDF output
file with an extension indicating the number of the page.
For example, to create a thumbnailed document named |foo.pdf|
you would need to generate thumbnail images in files named
|foo.1|, |foo.2|, etc.

\dest{fontmap}\section{Font Mapping}
\TeX\ font names can be
mapped into arbitrary physical (PostScript) font names via
the map file named |t1fonts.map|.  The file is
similar to the |psfonts.map| file used by |dvips|
and other drivers.  Each line in the
file consists of one to three fields delimited
by white space, followed by options that apply to that font.
The complete list of recognized options
appears in \link{Table~4}{options}.

Sample map file lines are\nobreak
\begintt
cmr10 ot1 -r
ptmro8r 8r Times-Roman -s 0.167
pncbo8r 8r pncb8a -s 0.167
\endtt

The first field of each line
is the \TeX\ font name.  The second
field, which is optional, is the encoding name (|.enc| will
be appended to this name, if necessary
to locate an encoding file).  The
encoding files have the same format
as those used for |dvips|.
The third optional field is {\it either} the PostScript font
name (if one of the standard PostScript fonts) {\it or}
the file name of a Type~1 binary font file (PFB file).
The {}.pfb extension is assumed by the program.
three fields. If the encoding field is unspecified,
|dvipdfm| used the default encoding supplied with
the Type~1 font.  If the name field is unspecified,
|dvipdfm| looks for a Type~1 binary font file
having the same name as the \TeX\ font name.
If there is {\it no} line in the map file,
the behavior is as if a line was specified
without the second or third field.
The keywords |default| or |none| are
recognized in the encoding field so that
a third field may be specified while still
having default behavior in the second field.

Currently, three options may be specified for each font
as shown in \link{Table~4}{options}.
\topinsert
{\dest{options}}
\centerline{\colored{\blue}{\subheadingfont Table~4---Font options
recognized by |dvipdfm| in the font map file}}
\bigskip\nobreak
\centerline{\vbox{\halign{{\tt #}\hskip
1em\strut&\vtop{\leftskip0pt\rightskip0pt\hsize=3.5in\noindent #}\cr
\omit\hfil\it Option\hfil&\omit\hfil \it Description \hfil\cr
\noalign{\smallskip\begincolor\red\hrule\endcolor\smallskip}
-r&{\it Remap the font to eliminate control characters.}  This
option attempts to work around bugs in Acrobat reader that seem
to be triggered by characters that are encoded in certain positions.
Unfortunately, standard \TeX encodings normally use these positions.\cr
\noalign{\smallskip}
-e {\it number}&{\it Extend the font horizontally, multiplying the natural
width of the font by the specified number.}  This is useful
for generating new fonts by widening existing fonts.\cr
\noalign{\smallskip}
-s {\it number}&{\it Slant the font using the specified number}.
This option is useful for building a slanted fonts from a font
for which there is no slanted font.\cr}}}
\endinsert

\section{Configuration file}
{\dest{configuration}}Dvipdfm reads default command line options, such
as paper size, from a configuration
file contained in the |dvipdfm| directory of the TeX tree.
The format of this file is similar to the |dvips| file configuration
file format.  Each line consists of a single command line switch
followed by any arguments.  See the configuration file supplied
with the |dvipdfm| distribution for examples.

\section{Including PostScript graphics images}
{\dest{postscript}}Dvipdfm provides support for illustrations
contained in external PostScript files. 
It recognizes two distinct kinds of PostScript files---those
created by MetaPost and everything else.

MetaPost
files output only a subset of PostScript and
are interpreted {\it natively} by |dvipdfm|
with its own internal minimal PostScript interpreter.
Also, MetaPost output files contain \TeX\ font information in their header
comments, so that they can be easily integrated with \TeX\ by DVI
drivers. Dvipdfm recognizes this font information and uses the \TeX\
fonts defined in the MetaPost header.


All other PostScript files require an external
program to convert the image to PDF format before
|dvipdfm| can include the image.
The freely available GhostScript is capabable of performing this conversion
for most images.

The user must specify the command line required
to invoke an external program to perform this conversion.
The command line required to invoke the conversion
program is specified using the |-D| command
line (or configuration file) option.  The string passed to the |-D| command
line option is a C-style string that is parsed by |dvipdfm|.  Within the string,
expansions are performed as described in \link{Table~5}{expansion}.
For example, to use GhostScript, one might use the
command line

\bigskip

{\tt -D "cat \%i \vrule\ gs -q -sDEVICE=pdfwrite -sOutputFile=\%o - -c quit" }


\topinsert
{\dest{expansion}}
\centerline{\colored{\blue}{\subheadingfont Table~5---Expansions
performed in the -D string.}}
\bigskip\nobreak
\centerline{\vbox{\halign{{\hfil\tt #\hfil}\hskip
1em\strut&\vtop{\leftskip0pt\rightskip0pt\hsize=3.5in\noindent #}\cr
\omit\hfil\it Variable\hfil&\omit\hfil \it Description \hfil\cr
\noalign{\smallskip\begincolor\red\hrule\endcolor\smallskip}
\%i&{\it Expanded to the full path of the EPS file to be included}\cr
\noalign{\smallskip}
\%o&{\it Expanded to the full path name of the PDF file to be
generated}.  The command line must be able to create a file
with the name supplied by dvipdfm.\cr
\noalign{\smallskip}
\%b&{\it Expanded to the  ``basename'' of the EPS file that is being included.}
The ``basename'' is the full path of the EPS file with the 
last ``.'' and any trailing name extension removed.\cr
}}}
\endinsert

\section{Compatibility with other DVI drivers}
Compatibility with other DVI drivers is achieved
by support for the following ``standard'' special calls.
Many legacy DVI files can be processed by |dvipdfm|,
so long as they use fairly standard special commands.
For example, |dvipdfm| can process DVI files generated
that use the
|\color|, |\rotatebox|, and |\includegraphics| macros
from the standard La\TeX\ Graphics bundle even if |dvips| was the target DVI driver,
e.g.,

\begintt
\usepackage[dvips]{graphics}
\usepackage[dvips]{color}
\endtt

Specifically, |dvipdfm| understands the following standard special commands:

\beginlist
\item{$\bullet$} The TPIC specials.

\item{$\bullet$} The HyperTeX (HTML) hyperlink specials.

\item{$\bullet$} The ``color'' specials supported by |dvips| and
other drivers.

\item{$\bullet$} The ``PSfile'' and ``plotfile'' specials for PS/EPS file inclusion
supported by |dvips| and other drivers.  Dvipdfm uses a user-specified
external program to convert the PostScript file to PDF format
before including it.

\item{$\bullet$} The raw PostScript ``ps:'' special supported by |dvips| and
other drivers.  Only a few PostScript operators are supported;
|dvipdfm| does not include a complete PostScript interpreter.
Complex PostScript code, such as that embedded by the PSTricks
package, is not supported.
\endlist

\section{LaTeX Support and Ebb}
Support for the La\TeX\ graphics bundle and |hyperref|
are available.  A driver file named |dvipdfm.def|
is distributed with the standard La\TeX
graphics bundle.  The latest version
of the |dvipdfm.def| file is supplied
with the |dvipdfm| distribution.
The file required for |hyperref|
support is called |hdvipdfm.def|.  

To facilitate La\TeX\ support, I distribute a companion program
called |ebb|, which extracts bounding boxes from graphics files.  If
you want to include JPEG, PNG, or PDF files in your document, you can run
|ebb| on the JPEG, PNG, or PDF file to create the |.bb| files.
The bounding box file will be similarly named with an extension of |.bb|.
For DOS 8+3 compatibility, an original file name extension 
of |.jpg|, |.png|, or |.pdf| is removed before creating the name of
the |.bb| file.  An extension of |.jpeg| is also recognized and similarly removed.

\newpage
\section{References}
\tolerance=1000\hbadness=1000
\bibitem\dest{pdfmanual}{\it Portable Document
Format Reference Manual}, Version 1.2, Adobe Systems Incorporated, 1996.
Available at the following URL:  {\tt http://www.adobe.com}. 

\bibitem\dest{pdfprimer}Thomas Merz,
{\it Web Publishing with Acrobat/PDF},
Springer-Verlag, 1997, ISBN 3-540-63762-1.  Chapter~6 of this book is available
at the URL:  |http://http://www.ifconnection.de/~tm|.

\bibitem\dest{acrotex}D. P. Story, {\it AcroTeX},  The AcroTeX home page
is located at the URL:  |http://www.math.uakron.edu/~dpstory/acrotex.html|.

\bye