summaryrefslogtreecommitdiff
path: root/systems/doc/dvipdfmx/dvipdfmx-special.tex
blob: 64dbf22bd60f731d6a5b1050f8795e895f21aa46 (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
%% tb94cho.ltx
%% Copyright 2010 Jin-Hwan CHO
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
% 
% The Current Maintainer of this work is Jin-Hwan CHO.

\documentclass[final]{ltugboat}

\usepackage{graphicx}
\usepackage{url}
%\usepackage{picins}
\usepackage{microtype}

\def\CFF{\acro{CFF}}
\def\CID{\acro{CID}}
\def\CJK{\acro{CJK}}
\def\DTL{\acro{DTL}}
\def\DVIasm{\acro{DVI}asm}
\def\DVItype{\acro{DVI}type}
\def\DPS{\acro{DVIPS}}
\def\DPM{\acro{DVI\-PDFM}}
\def\DPMx{\acro{DVI\-PDFM}($x$)}
\let\DPX\DVIPDFMx
\def\pdfmark{pdfmark}
\def\GS{Ghostscript}
\def\EPS{\acro{EPS}}
\def\pdfTeX{pdf\/\TeX}
\def\LuaTeX{Lua\TeX}
\def\pTeX{p\kern-0.05em\TeX}
\def\XObject{\acro{XO}bject}
\def\fafter{1.5pt}

\let\note=\footnote
\def\ctanloc#1{\url{http://mirror.ctan.org/#1}}
\setlength{\fboxsep}{1.5pt}

%\divide\abovecaptionskip by 2

% don't go to a float page so soon:
%\renewcommand{\dbltopfraction}{.99}
%\renewcommand{\dblfloatpagefraction}{.8}

\title{\DVI\ specials for \PDF\ generation}
\author{Jin-Hwan Cho}
\address{Department of Mathematics \\ The University of Suwon \\ Republic of Korea}
\netaddress{chofchof (at) ktug dot or dot kr}

\begin{document}
\sectitle{Software \& Tools}
\maketitle

\begin{abstract}%
\acro{DVIPDFM}($x$) manages various \PDF\ effects by means of \DVI\ specials.
Appropriate documentation of \DVI\ specials, however, is not easy to find, and exact functionality is not simple to catch without reading the source code of \DVI\ drivers.
This paper deals with the \DVI\ specials defined in \acro{DVIPDFM}($x$) that are mainly used for \PDF\ generation.
We discuss the features of those specials with some examples, many of which are not documented elsewhere.
\end{abstract}

\section{Introduction}

\DVI, the output file format of D.~E.~Knuth's \TeX, is not widely used at present compared with \PDF, the output format of \pdfTeX.
It is rather old\note{\DVI\ was designed by David R.~Fuchs in 1979.} and obsolete, but it has powerful aspects nonetheless: \emph{simplicity} and \emph{compactness}.

These aspects make it possible to manipulate \DVI\ files in an easy and fast way.
Many \DVI\ utilities were developed to convert the \DVI\ format to other file formats including \PS\ and \PDF.
It is also possible to edit \DVI\ files directly by the use of \DVIasm~\cite{Cho07,Cho08,DVIasm}.

Twenty years ago, at the time \PS\ dominated the printing world, nobody expected a new format would replace \PS.
\PDF\ is not eternal either.
In future, when a new format surpassing \PDF\ appears, \DVI\ will be the first format in the \TeX\ world that can be converted to the new format.
Notice that \LuaTeX, considered to be the next generation of \pdfTeX, still supports the \DVI\ format.

There are two popular ways to convert \DVI\ to \PDF.
The first one is a two-way conversion, from \DVI\ to \PS\ with \DPS, and then from \PS\ to \PDF\ with a distiller.
Adobe Acrobat Distiller is the oldest commercial program, and \GS\ is the most popular distiller in the \TeX\ world. \MacOSX\ also has its own distiller.

Adobe designed the \pdfmark\ operator~\cite{pdfmark} for its distiller to support \PDF\ features that are not expressible using the standard \PS\ operators.
The \pdfmark\ operator is given in the \TeX\ source by means of a \DVI\ special command.
Note that it is not \DPS\ but a distiller that processes the \pdfmark\ operator.

Mark A.~Wicks' \DPM~\cite{DVIPDFM} introduced the other way of converting \DVI\ directly to \PDF.
He also designed new \DVI\ specials based on the \pdfmark\ operator to support various \PDF\ features.
The new specials, however, lacked some functionality in practical use so that not many \PDF\ features could be obtained compared with \pdfTeX.

One of the main goal of \DPX, an extension of \DPM\ that grew out of the \CJK\note{Chinese, Japanese, and Korean.} support, was to provide as many \PDF\ features as \pdfTeX~\cite{Cho03}.
\DPX\ extended the functionality of some special commands of \DPM, and designed new special commands having a similar functionality of \pdfTeX's own primitives.
Furthermore, \DPX\ has several powerful features not available in \DPM.
	\begin{itemize}
	\item Support 16-bit character sets (\CJK\ encodings and Unicode) with \CID-keyed font technology.
	\item Support various font formats including OpenType, TrueType, etc.
	\item Use \CFF\ font format for embedded Type1 \PS\ fonts so that the size of the \PDF\ output is quite small compared with \pdfTeX's output.
	\item Support extended \TeX\ engines, e.g., Omega, Japanese \pTeX, \XeTeX\ (via \acro{XDVIPDFMX}).\note{Upcoming version of \DPX\ will support the \DVI\ output generated by \LuaTeX.}
	\end{itemize}

The \acro{TODO} list of \DPX\ had contained one outstanding item for a long time: supporting Till Tantau's beamer package~\cite{beamer}, that is widely used for \PDF\ presentation.
In fact, this package does not handle \DVI\ specials in a direct way.
Instead, the graphics part comes from the same author's \PGF\ package~\cite{PGF}, and the other \PDF\ effects come from the hyperref package~\cite{hyperref}.

\DPX\ has supported full functionality of the \PGF\ package since June 2008.\note{The \DPX\ driver that works with the \PGF\ package included in \TeX\ Live 2008 can be downloaded from \url{http://project.ktug.or.kr/dvipdfmx/contrib/generic/}.}
Nonetheless, the navigation buttons usually shown in the lower right corner of the presentation still did not work, although they were displayed correctly.
The source code\note{\raggedright \ctanloc{macros/latex/contrib/beamer/base/beamerbasenavigation.sty}} implementing the buttons was

\begin{verbatim}[\small]
\def\beamer@linkspace#1{\vbox to7.5pt{}\kern#1}
\end{verbatim}

The code above generates an \emph{empty} box that will be surrounded by the two special commands, `\texttt{pdf:bann}' (before) and `\texttt{pdf:eann}' (after).
Unfortunately, neither \DPM\ nor \DPX\ construct any annotation in the case of an empty box.
Another special command `\texttt{pdf:ann}' must be used instead for this purpose.
That was the exact reason why the navigation buttons did not work.

Why did the author of the beamer package make such a mistake?
As a matter of fact, it was not his fault because no statement could be found about that functionality in the manual of \DPM~\cite{DVIPDFM}.
This unhappy story led to this paper.

The author gave a presentation~\cite{Cho05} at \tug\ 2005, in which the different behaviors of \DVI\ specials of \DPS, \DPM, and \DPX\ were discussed.
\DVI\ specials for \PDF\ generation, however, were not fully discussed at that time.
The main objective of this paper is to bridge this gap.

We will discuss in the following sections the features of \DVI\ specials defined in \DPM\ for \PDF\ generation, and the extended features given by \DPX.
The author hopes this paper would be useful for package writers who are finding appropriate information on \DVI\ specials.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Named PDF objects}

There are two kinds of named objects, built-in and user-defined \PDF\ objects.

\subsection{Built-in named objects}

Built-in objects defined in \DPMx{} are listed in Table~\ref{Table1}. We refer to~\cite[p.~12]{pdfmark} and~\cite[p.~5]{DVIPDFM} for \pdfmark\ and \DPM\ built-in objects, respectively.
Notice that it is not allowed to modify the contents of the last five built-in objects in Table~\ref{Table1}.

\begin{table}[h]
\begin{tabular}{|l|p{1.95in}|} \hline
\texttt{@catalog} & catalog dictionary~\cite[p.~139]{PDFReference} \\
\texttt{@docinfo} & (\DPX\ only) document\newline information dictionary \cite[p.~844]{PDFReference} \\
\texttt{@names} & name dictionary~\cite[p.~150]{PDFReference} \\
\texttt{@pages} & root page tree node \cite[p.~143]{PDFReference} \\
\texttt{@resources} & resource dictionary of current\newline page \cite[p.~154]{PDFReference} \\
\texttt{@thispage} & current page object \cite[p.~145]{PDFReference} \\\hline
\texttt{@prevpage} & reference only \\
\texttt{@nextpage} & reference only \\
\texttt{@page$n$} & reference only \\
\texttt{@xpos} & reference only \\
\texttt{@ypos} & reference only \\
\hline
\end{tabular}
\caption{Built-in objects defined in \DPMx{}}
\label{Table1}
\end{table}


\subsection{User-defined named objects}

Two special commands are provided by \DPMx{} for user-defined objects.
One is to define a named object, and the other is to add content to the previously defined object.

\begin{itemize}
\item\fbox{\ttfamily pdf:obj @name PDFobject} \ creates a named object that can be referenced later by `\texttt{@name}'.
\end{itemize}

\noindent
All possible object types for `\texttt{PDFobject}' are listed in Table~\ref{Table2}.
In the case of indirect objects, the object number must be given explicitly, so that this feature is rarely used, especially to specify the objects in a different \PDF\ file.

\begin{table}[h]
\begin{tabular}{|l|p{2.1in}|} \hline
boolean & \texttt{true}, \texttt{false} \\
numeric & \texttt{123}, \texttt{34.5}, \texttt{-.002} \\
string & \texttt{(This is a string)}, \texttt{<901FA3>} \\
name & \texttt{/Name1}, \texttt{/.notdef} \\
array & \texttt{[3.14 false (Ralph) /Name1]} \\
dictionary & \texttt{<</Key1 (Value) /Key2 3.14>>} \\
null & \texttt{null} \\\hline
indirect & \texttt{12 0 R} \\
stream & \texttt{stream ... endstream} \\
\hline
\end{tabular}
\caption{\PDF\ object types~\cite[p.~51]{PDFReference}}
\label{Table2}
\end{table}

It is not simple to construct a stream object with the special command `\texttt{pdf:obj}' because
the length of the stream object must be specified explicitly, which is quite bothersome.
Imagine that you are trying to construct a stream object whose source comes from a file.
Is it possible with this special command?
Moreover, any stream object requires the keyword `\texttt{stream}' followed by an end-of-line marker.\note{%
An end-of-line marker consists of either a carriage return (\texttt{0x0d}) and a line feed (\texttt{0x0a}) or just a line feed, and not by a carriage return alone~\cite[pp.~60--61]{PDFReference}.}

\DPX, therefore, provides new special commands for stream objects.

\begin{itemize}
\item\fbox{\ttfamily pdf:stream @name (string) <<dict>>} \\[\fafter]
constructs a stream object the source of which comes from the string object `\texttt{(string)}'.
The stream dictionary `\texttt{<<dict>>}' is optional, and the dictionary entry `\texttt{/Length}' is created automatically.
\end{itemize}

\noindent
The following two special commands, for instance, construct the same stream object.
The stream data of the second object is represented in the \ASCII\ base-85 encoding.~\cite[p.~70]{PDFReference}

\begin{verbatim}[\small]
\special{pdf:stream @name (xxxxxxxx)}
\special{pdf:stream @name (G^+IXG^+IX)
         <</Filter/ASCII85Decode>>}
\end{verbatim}

\begin{itemize}
\item\fbox{\ttfamily pdf:fstream @name (filename) <<dict>>} \\[\fafter]
constructs a stream object in the same way as `\texttt{pdf:stream}', but the source of stream data comes from a file `\texttt{filename}'.
\end{itemize}

\noindent
The following example shows how to include a source \TeX\ file inside the output \PDF\ file. (See~\cite[p.~637]{PDFReference} for more details on the file attachment annotation.)

\begin{verbatim}[\small]
\special{pdf:fstream @myfile (mytest.tex)}
\special{pdf:ann bbox 0 0 10 10 <<
  /Subtype /FileAttachment /FS <<
    /Type /Filespec /F (mytest.tex)
       /EF << /F @myfile >> >>
  /Name /PushPin >>}
\end{verbatim}


\subsection{Adding content to named objects}

We describe the special command for adding content to named objects. The type of the named object must be either array or dictionary.

\begin{itemize}
\item\fbox{\ttfamily pdf:put @arrayobj object$_1$ $\ldots$ object$_n$} \\[\fafter]
appends the $n$ objects at the end of the array object `\texttt{@arrayobj}'.
\item\fbox{\ttfamily pdf:put @dictobj <<dict>>} \ merges the dictionary object `\texttt{<<dict>>}' into `\texttt{@dictobj}'. If both the dictionaries have a common key, the old value in `\texttt{@dictobj}' will be replaced by the new value in `\texttt{<<dict>>}'.
\end{itemize}

\noindent
In the following example, the value of the key `\texttt{/X}' in the dictionary object `\texttt{@name}' is `\texttt{@Moon2}'.
(See~\cite[p.~15]{pdfmark} for corresponding \pdfmark\ operators.)

\begin{verbatim}[\small]
\special{pdf:put @Moon1
         [ (Earth to Moon) 238855 /mies ]}
\special{pdf:obj @Moon2 []}
\special{pdf:put @Moon2 (Moon to Earth)}
\special{pdf:put @Moon2 238855}
\special{pdf:put @Moon2 /miles}
\special{pdf:obj @name <<>>}
\special{pdf:put @name << /X @Moon1 >>}
\special{pdf:put @name << /X @Moon2 >>}
\end{verbatim}

Note that \DPM\ does not allow adding content to a stream dictionary object, but \DPX\ does.

\begin{itemize}
\item\fbox{\ttfamily pdf:put @streamobj <<dict>>} \ \ merges the dictionary object `\texttt{<<dict>>}' into the stream dictionary of `\texttt{@streamobj}'. The dictionary entries, `\texttt{/Length}' and `\texttt{/Filter}', in the object `\texttt{<<dict>>}' will be ignored.
\end{itemize}

Finally, \DPMx{} provides the special command
\fbox{\ttfamily pdf:close @name} to prevent further modifying the content of `\texttt{@name}'. After closing the named object, it can only be referenced.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Annotations}

An annotation is considered as an object with a location on a page.
The type of the object is given by the value of the key `\texttt{/Subtype}', for instance, `\texttt{/Text}', `\texttt{/Link}', `\texttt{/Sound}', `\texttt{/Movie}', etc.
(See~\cite[p.~615]{PDFReference} for the list of all annotation types.)
The location is given by an array object associated to the key `\texttt{/Rect}'.
\DPMx{} provides the following special command for annotations.

\begin{itemize}
\item\fbox{\hbadness=10000
\parbox{.43\textwidth}{\ttfamily pdf:ann @name width [length] height [length] depth [length] <<dict>>}}
\par\vspace{\fafter}\noindent
The annotation dictionary is given by `\texttt{<<dict>>}' and the location relative to the current position is given by the three dimension parameters, `\texttt{width}', `\texttt{height}', and `\texttt{depth}'.
\end{itemize}

\noindent
It is not possible to specify the location in an absolute way.
Any value of the key `\texttt{/Rect}' in the annotation dictionary `\texttt{<<dict>>}' will be ignored if found.
It is not allowed to modify the annotation dictionary with `\texttt{pdf:put}' command, so `\texttt{@name}' must be used as a reference.

Note that \DPX\ allows the `\texttt{bp}' unit in the dimension parameters, but \DPM\ does not.
Moreover, \DPX\ supports the following form.

\begin{itemize}
\item\fbox{\hbadness=10000
\parbox{.425\textwidth}{\ttfamily pdf:ann @name bbox [ulx] [uly] [lrx] [lry] <<dict>>}}
\par\vspace{\fafter}\noindent
The relative location is given by the bounding box consisting of four numbers in `\texttt{bp}' units.
\end{itemize}

\noindent
The following example shows a movie annotation that enables us to run the movie file `\texttt{mymovie.avi}' inside a \PDF\ viewer program.

\begin{verbatim}
\special{pdf:ann bbox 0 0 360 180 <<
  /Subtype /Movie /Border [1 0 0]
  /T (My Movie) /Movie <<
    /F (mymovie.avi) /Aspect [720 360]
    /Poster true >>
  /A << /ShowControls false >> >>}
\end{verbatim}

\DPMx{} provides other special commands for \emph{breakable} annotations, e.g., an annotation broken over several lines or several pages.

\begin{itemize}
\item\fbox{\ttfamily pdf:bann <<dict>>} \ begins a breakable annotation.
Object name is not allowed for this command.
\item\fbox{\ttfamily pdf:eann} \ terminates the previous breakable annotation.
\end{itemize}

\noindent
These specials are mainly used for `\texttt{/Link}' annotation as the following example shows.

\begin{verbatim}[\small]
\special{pdf:bann << /Subtype /Link
  /BS << /Type /Border /W 0.5 /S /S >>
  /A << /S /URI
    /URI (http://www.tug.org) >> >>}%
http://www.tug.org%
\special{pdf:eann}
\end{verbatim}

\noindent
\emph{Warning:} No annotation will be constructed if the content between `\texttt{pdf:bann}' and `\texttt{pdf:eann}' is an empty box.  For example:

\begin{verbatim}[\small]
\special{pdf:bann << /Subtype /Link ... >>}
\vbox to 7.5pt{}\kern 10pt
\sepcial{pdf:eann}
\end{verbatim}

Annotations constructed by \DPMx{} may happen to be slightly bigger than the expected size. This occurs when the annotation grow size is positive; this value is specified in the configuration file. To avoid this effect, either modify the configuration file or give `\texttt{-g 0}' on the command line when running \DPMx{}.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Outlines (or bookmarks)}

The document outline consists of a tree-structured hierarchy of outline items (sometimes called bookmarks) for which \DPMx{} provides the following special command.

\begin{itemize}
\item\fbox{\ttfamily pdf:out $n$ <<dict>>} \ adds an outline item to the document. The integer parameter $n$ represents the level of the outline entry (beginning with 1), and `\texttt{<<dict>>}' represents the outline item dictionary~\cite[p.~585]{PDFReference}.
\end{itemize}

Note that all the outline items generated by \DPM\ are closed.\note{The sign of the value of the key `\texttt{/Count}' in the outline item dictionary determines whether the item is open or closed.~\cite[p.~586]{PDFReference}}
The `\texttt{bookmarksopen=true}' option of the hyperref package does not work if the \PDF\ output is generated by \DPM.

\begin{verbatim}[\small]
\usepackage[
  dvipdfm,bookmarks=true,bookmarksopen=true
]{hyperref}
\end{verbatim}

\DPX\ provides two solutions for this problem.
The first one is to specify the option `\texttt{-O $n$}' when running \DPX.
Up to level $n$, the outline entries will be open. The second, and complete, solution is to use this extended special command:

\begin{itemize}
\item\fbox{\ttfamily pdf:out [-] $n$ <<dict>>} \ The symbol `\texttt{[-]}' indicates that the outline item will be closed. On the other hand, `\texttt{[]}' without the minus sign indicates that the outline item will be open.
\end{itemize}

The hyperref package provides a new option `\texttt{dvipdfmx-outline-open}' that uses the extended command above. This option enables us to control the open level given by `\texttt{bookmarksopenlevel}'.

\begin{verbatim}[\small]
\usepackage[%
  dvipdfmx,bookmarks=true,
  bookmarksopen=true,
  bookmarksopenlevel=1,
  dvipdfmx-outline-open
]{hyperref}
\end{verbatim}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{External objects (or XObjects)}

\DPMx{} supports two types of \emph{external objects},\note{%
``A graphics object whose contents are defined by a self-contained content stream, separate from the content stream in which it is used.''~\cite[p.~332]{PDFReference}
} an image \XObject{} and a form \XObject.
 
\begin{itemize}
\item\fbox{\hbadness=10000
\parbox{.42\textwidth}{\ttfamily pdf:image @name width [length] height [length] depth [length] (imagefile)}}
\par\vspace{\fafter}\noindent
defines an image \XObject\ the source of which comes from the file `\texttt{imagefile}'. See~\cite[p.~216]{Cho07} for complete syntax provided by \DPX.
\item\fbox{\hbadness=10000
\parbox{.42\textwidth}{\ttfamily pdf:bxobj @name width [length] height [length] depth [length]}}
\par\vspace{\fafter}\noindent
begins the definition of a form \XObject.
As with the command `\texttt{pdf:add}', \DPX\ allows bounding box `\texttt{bbox [ulx] [uly] [lrx] [lry]}' for dimension parameters.
\item\fbox{\ttfamily pdf:exobj} \ ends the previous form \XObject\ definition.
\item\fbox{\ttfamily pdf:uxobj @name} \ displays the image \XObject\ or the form \XObject\ previously defined and associated with `\texttt{@name}'.
\DPM$x$ allows dimension parameters (same as `\texttt{pdf:image}') after `\texttt{@name}'.
\end{itemize}

\noindent
Typical examples showing how to use image \XObject{}s and form \XObject{}s can be found in~\cite[pp.~15--16]{Cho05}.

\begin{figure}[h]
\centering\includegraphics{transparencygroup.pdf}
\caption{Two form \XObject{}s with opacity 0.5; the right one is a group \XObject.}
\label{Figure1}
\end{figure}

\DPX\ extended the command `\texttt{pdf:eann}' to support a group \XObject.\note{``A special type of form \XObject\ that can be used to group graphical elements together as a unit for various purposes.'' \cite[p.~360]{PDFReference}}
Figure~\ref{Figure1} shows the difference between a normal \XObject\ and a group \XObject.

\begin{itemize}
\item\fbox{\ttfamily pdf:exobj <<dict>>} \ merges the dictionary object `\texttt{<<dict>>}' into the type1 form dictionary~\cite[p.~358]{PDFReference} of the previous form \XObject\ and then close the \XObject.
\end{itemize}

\noindent
The following code draws the right image in Figure~\ref{Figure1}.

\begin{verbatim}[\small]
\special{pdf:bxobj @group bbox 0 0 50 50}
\special{pdf:code
    15 w 0 0 m 50 50 l S 50 0 m 0 50 l S}
\special{pdf:exobj << /Group
   << /S /Transparency >> >>}
\special{pdf:obj @extgstate
   << /CA0.5 <</CA 0.5>> /ca0.5 <</ca 0.5>> >>}
\special{pdf:put @resources
   << /ExtGState @extgstate >>}
\special{pdf:code /CA0.5 gs /ca0.5 gs}
\special{pdf:uxobj @group}
\end{verbatim}

\noindent We get the left image if \verb+\special{pdf:exobj}+ is used instead of the 4th and the 5th line.


\section{Raw PDF Operators}

This final section deals with writing raw \PDF\ operators in the output.
\DPM\ provides a special command for this feature.

\begin{itemize}
\item\fbox{\ttfamily pdf:content Operators} \vadjust{\vskip2pt} adds the list of operators ``\texttt{Operators}'' to the current page at the current location.
The operator `\texttt{q}', saving the current graphics state, followed by a transformation matrix moving to the current location will be attached to the beginning of the list, and the operator `\texttt{Q}' restoring the saved graphics state at the end of the list.
\end{itemize}

For instance, the special command

\begin{verbatim}
\special{pdf:content 10 w 0 0 m 50 50 l S}
\end{verbatim}

\noindent
inserts the following list of operators in the output.

\smallskip\noindent
{\fontsize{9pt}{11pt}\selectfont
%\begin{verbatim}
\ttfamily\ldots\,%
\fbox{\strut q}\,\fbox{\strut 1 0 0 1 $x$ $y$ cm}\,%
10 w 0 0 m 50 50 l S
\fbox{\strut Q}\,%
\ldots
%\end{verbatim}
}

We sometimes need to insert \PDF\ operators without additional graphics state operators.
The author of the \PGF\ package devised a trick:

{\hfuzz=5pt
\begin{verbatim}
\special{pdf:content Q ... Operators ... q}
\end{verbatim}
}

\noindent
The first operator `\texttt{Q}' and the last operator `\texttt{q}' nullify the effects of graphics state operators that are attached.

\DPX\ provides a new special command instead of the trick above.

\begin{itemize}
\item\fbox{\ttfamily pdf:literal direct Operators}\note{%
The idea of `\texttt{pdf:literal direct}' came from the primitive `\cs{pdfliteral direct}' of \pdfTeX.} \ or simply\\[\fafter]
\fbox{\ttfamily pdf:code Operators} \ plays the same role as\\[\fafter]
`\texttt{pdf:content}, but no graphics state operator and no
transformation matrix will be added.
\end{itemize}

\begin{figure}[h]
\centering\includegraphics{bcontent.pdf}
\caption{The location of `23' in the left image varies according to the location of 1 in the current page.}
\label{Figure2}
\end{figure}

Consider the following code, labelled Listing~\ref{Code1}. Which image in Figure~\ref{Figure2} does this code generate?

\renewcommand{\tablename}{Listing}
\setcounter{table}{0}
\begin{table}[h] 
%{
\hfuzz=5pt
\fontsize{9pt}{11pt}\selectfont
\begin{verbatim}
\def\bpic{\special{pdf:content q}}
\def\epic{\special{pdf:content Q}}
\def\myop#1{\special{pdf:content Q #1 q}}
1\bpic2\myop{.5 G 10 w 0 0 m 100 100 l S}3\epic4
\end{verbatim}
%}
\caption{Which image in Figure~\ref{Figure2} is the result of this code, produced by \DPM($x$)?}
\label{Code1}
\end{table}

The macro \cs{bpic} in Listing~\ref{Code1} nullifies the effect of the operator `\texttt{Q}' that will be attached after `\texttt{q}', and the macro \cs{epic} nullifies the effect of the list `\texttt{q 1 0 0 1 $x$ $y$ cm}' that will be attached before `\texttt{Q}'.

Most people may choose the right-hand image in Figure~\ref{Figure2} as the result of Listing~\ref{Code1}, if they remember the fact that special commands are considered nothing by \TeX. However, the answer is the left-hand image.
The reason is that the transformation matrix in the macro \cs{bpic} still has an effect on the characters `2' and `3'. The effect will be nullified by the macro \cs{epic}.

To produce the right-hand image, \DPX\ provides the following new special commands.

\begin{itemize}
\item\fbox{\ttfamily pdf:bcontent} \ starts a block that works in the same way as `\texttt{pdf:content}' except that all text between this command and `\texttt{pdf:econtent}' will be placed in the right position.
\item\fbox{\ttfamily pdf:econtent} \ ends the current block.
\end{itemize}

\noindent
Moreover, `\texttt{pdf:bcontent}' and `\texttt{pdf:econtent}' can be nested.

Finally, we can get the right-hand image in Figure~\ref{Figure2} as the result of Listing~\ref{Code2} following, produced by \DPX.

\begin{table}[h] 
%{
\hfuzz=5pt
\fontsize{9pt}{11pt}\selectfont
\begin{verbatim}
\def\bpic{\special{pdf:bcontent}}
\def\epic{\special{pdf:econtent}}
\def\myop#1{\special{pdf:code #1}}
1\bpic2\myop{.5 G 10 w 0 0 m 100 100 l S}3\epic4
\end{verbatim}
%}
\caption{The right-hand image in Figure~\ref{Figure2} is the result of this example produced by \DPX.}
\label{Code2}
\end{table}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\SetBibJustification\raggedright
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{thebibliography}{99}

\bibitem{PDFReference} Adobe Systems, Inc., \emph{\PDF\ Reference}, \nth{6} edition (Version 1.7, November 2006).
  \url{http://www.adobe.com/devnet/acrobat/pdfs/pdf_reference_1-7.pdf}.

\bibitem{pdfmark} Adobe Systems, Inc., \emph{\pdfmark\ Reference}
(Version 8.0, November 2006).
  \url{http://www.adobe.com/devnet/acrobat/pdfs/pdfmark_reference.pdf}.

\bibitem{Cho03}
Jin-Hwan Cho, \emph{\DPX, an extension of \DPM},
  \tug\ 2003. Hawaii, United States.
  \url{http://project.ktug.or.kr/dvipdfmx/doc/tug2003.pdf}.

\bibitem{Cho05}
Jin-Hwan Cho, \emph{Practical Use of Special Commands in \DPX},
  \tug\ 2005, International Typesetting Conference. Wuhan, China.
  \url{http://project.ktug.or.kr/dvipdfmx/doc/tug2005.pdf}.

\bibitem{Cho07}
Jin-Hwan Cho, \emph{Hacking \DVI\ files: Birth of \DVIasm}, The Prac\TeX\ Journal (2007), no.~1, and TUGboat 28:2, 2007, 210--217.
  \url{http://tug.org/TUGboat/Articles/tb28-2/tb89cho.pdf}.

\bibitem{Cho08}
Jin-Hwan Cho, \emph{Handling Two-Byte Characters with \DVIasm}, The Asian Journal of \TeX\ \textbf{2} (2008), no.~1, 63--68.
  \url{http://ajt.ktug.kr/assets/2008/5/1/0201cho.pdf}.

\bibitem{DVIasm}
Jin-Hwan Cho, \emph{The \DVIasm\ Python script}.
  \ctanloc{dviware/dviasm/}.

\bibitem{hyperref}
Heiko Oberdiek, \emph{The hyperref package} (Version 6.78f, August 2008).
  \ctanloc{macros/latex/contrib/hyperref/}

\bibitem{beamer}
Till Tantau, \emph{The beamer package} (Version 3.07, March 2007).
  \ctanloc{macros/latex/contrib/beamer/}.

\newpage
\bibitem{PGF}
Till Tantau, \emph{\PGF, A Portable Graphics Format for \TeX} (Version 2.00, February 2008).
  \ctanloc{graphics/pgf/}.

\bibitem{DVIPDFM} Mark A. Wicks, \emph{\DPM\ User's Manual}
(Version 0.12.4, September 1999).
  \url{http://gaspra.kettering.edu/dvipdfm/dvipdfm-0.12.4.pdf}.

\end{thebibliography}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\medskip
\makesignature
\end{document}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%