Debian Codegraph @

texmf-dist/doc/dvipdfmx/dvipdfmx-special.tex

raw
1 %% tb94cho.ltx
2 %% Copyright 2010 Jin-Hwan CHO
3 %
4 % This work may be distributed and/or modified under the
5 % conditions of the LaTeX Project Public License, either version 1.3
6 % of this license or (at your option) any later version.
7 % The latest version of this license is in
8 % http://www.latex-project.org/lppl.txt
9 % and version 1.3 or later is part of all distributions of LaTeX
10 % version 2005/12/01 or later.
11 %
12 % This work has the LPPL maintenance status `maintained'.
13 %
14 % The Current Maintainer of this work is Jin-Hwan CHO.
15
16 \documentclass[final]{ltugboat}
17
18 \usepackage{graphicx}
19 \usepackage{url}
20 %\usepackage{picins}
21 \usepackage{microtype}
22
23 \def\CFF{\acro{CFF}}
24 \def\CID{\acro{CID}}
25 \def\CJK{\acro{CJK}}
26 \def\DTL{\acro{DTL}}
27 \def\DVIasm{\acro{DVI}asm}
28 \def\DVItype{\acro{DVI}type}
29 \def\DPS{\acro{DVIPS}}
30 \def\DPM{\acro{DVI\-PDFM}}
31 \def\DPMx{\acro{DVI\-PDFM}($x$)}
32 \let\DPX\DVIPDFMx
33 \def\pdfmark{pdfmark}
34 \def\GS{Ghostscript}
35 \def\EPS{\acro{EPS}}
36 \def\pdfTeX{pdf\/\TeX}
37 \def\LuaTeX{Lua\TeX}
38 \def\pTeX{p\kern-0.05em\TeX}
39 \def\XObject{\acro{XO}bject}
40 \def\fafter{1.5pt}
41
42 \let\note=\footnote
43 \def\ctanloc#1{\url{http://mirror.ctan.org/#1}}
44 \setlength{\fboxsep}{1.5pt}
45
46 %\divide\abovecaptionskip by 2
47
48 % don't go to a float page so soon:
49 %\renewcommand{\dbltopfraction}{.99}
50 %\renewcommand{\dblfloatpagefraction}{.8}
51
52 \title{\DVI\ specials for \PDF\ generation}
53 \author{Jin-Hwan Cho}
54 \address{Department of Mathematics \\ The University of Suwon \\ Republic of Korea}
55 \netaddress{chofchof (at) ktug dot or dot kr}
56
57 \begin{document}
58 \sectitle{Software \& Tools}
59 \maketitle
60
61 \begin{abstract}%
62 \acro{DVIPDFM}($x$) manages various \PDF\ effects by means of \DVI\ specials.
63 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.
64 This paper deals with the \DVI\ specials defined in \acro{DVIPDFM}($x$) that are mainly used for \PDF\ generation.
65 We discuss the features of those specials with some examples, many of which are not documented elsewhere.
66 \end{abstract}
67
68 \section{Introduction}
69
70 \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.
71 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}.
72
73 These aspects make it possible to manipulate \DVI\ files in an easy and fast way.
74 Many \DVI\ utilities were developed to convert the \DVI\ format to other file formats including \PS\ and \PDF.
75 It is also possible to edit \DVI\ files directly by the use of \DVIasm~\cite{Cho07,Cho08,DVIasm}.
76
77 Twenty years ago, at the time \PS\ dominated the printing world, nobody expected a new format would replace \PS.
78 \PDF\ is not eternal either.
79 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.
80 Notice that \LuaTeX, considered to be the next generation of \pdfTeX, still supports the \DVI\ format.
81
82 There are two popular ways to convert \DVI\ to \PDF.
83 The first one is a two-way conversion, from \DVI\ to \PS\ with \DPS, and then from \PS\ to \PDF\ with a distiller.
84 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.
85
86 Adobe designed the \pdfmark\ operator~\cite{pdfmark} for its distiller to support \PDF\ features that are not expressible using the standard \PS\ operators.
87 The \pdfmark\ operator is given in the \TeX\ source by means of a \DVI\ special command.
88 Note that it is not \DPS\ but a distiller that processes the \pdfmark\ operator.
89
90 Mark A.~Wicks' \DPM~\cite{DVIPDFM} introduced the other way of converting \DVI\ directly to \PDF.
91 He also designed new \DVI\ specials based on the \pdfmark\ operator to support various \PDF\ features.
92 The new specials, however, lacked some functionality in practical use so that not many \PDF\ features could be obtained compared with \pdfTeX.
93
94 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}.
95 \DPX\ extended the functionality of some special commands of \DPM, and designed new special commands having a similar functionality of \pdfTeX's own primitives.
96 Furthermore, \DPX\ has several powerful features not available in \DPM.
97 \begin{itemize}
98 \item Support 16-bit character sets (\CJK\ encodings and Unicode) with \CID-keyed font technology.
99 \item Support various font formats including OpenType, TrueType, etc.
100 \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.
101 \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.}
102 \end{itemize}
103
104 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.
105 In fact, this package does not handle \DVI\ specials in a direct way.
106 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}.
107
108 \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/}.}
109 Nonetheless, the navigation buttons usually shown in the lower right corner of the presentation still did not work, although they were displayed correctly.
110 The source code\note{\raggedright \ctanloc{macros/latex/contrib/beamer/base/beamerbasenavigation.sty}} implementing the buttons was
111
112 \begin{verbatim}[\small]
113 \def\beamer@linkspace#1{\vbox to7.5pt{}\kern#1}
114 \end{verbatim}
115
116 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).
117 Unfortunately, neither \DPM\ nor \DPX\ construct any annotation in the case of an empty box.
118 Another special command `\texttt{pdf:ann}' must be used instead for this purpose.
119 That was the exact reason why the navigation buttons did not work.
120
121 Why did the author of the beamer package make such a mistake?
122 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}.
123 This unhappy story led to this paper.
124
125 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.
126 \DVI\ specials for \PDF\ generation, however, were not fully discussed at that time.
127 The main objective of this paper is to bridge this gap.
128
129 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.
130 The author hopes this paper would be useful for package writers who are finding appropriate information on \DVI\ specials.
131
132
133 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
134 \section{Named PDF objects}
135
136 There are two kinds of named objects, built-in and user-defined \PDF\ objects.
137
138 \subsection{Built-in named objects}
139
140 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.
141 Notice that it is not allowed to modify the contents of the last five built-in objects in Table~\ref{Table1}.
142
143 \begin{table}[h]
144 \begin{tabular}{|l|p{1.95in}|} \hline
145 \texttt{@catalog} & catalog dictionary~\cite[p.~139]{PDFReference} \\
146 \texttt{@docinfo} & (\DPX\ only) document\newline information dictionary \cite[p.~844]{PDFReference} \\
147 \texttt{@names} & name dictionary~\cite[p.~150]{PDFReference} \\
148 \texttt{@pages} & root page tree node \cite[p.~143]{PDFReference} \\
149 \texttt{@resources} & resource dictionary of current\newline page \cite[p.~154]{PDFReference} \\
150 \texttt{@thispage} & current page object \cite[p.~145]{PDFReference} \\\hline
151 \texttt{@prevpage} & reference only \\
152 \texttt{@nextpage} & reference only \\
153 \texttt{@page$n$} & reference only \\
154 \texttt{@xpos} & reference only \\
155 \texttt{@ypos} & reference only \\
156 \hline
157 \end{tabular}
158 \caption{Built-in objects defined in \DPMx{}}
159 \label{Table1}
160 \end{table}
161
162
163 \subsection{User-defined named objects}
164
165 Two special commands are provided by \DPMx{} for user-defined objects.
166 One is to define a named object, and the other is to add content to the previously defined object.
167
168 \begin{itemize}
169 \item\fbox{\ttfamily pdf:obj @name PDFobject} \ creates a named object that can be referenced later by `\texttt{@name}'.
170 \end{itemize}
171
172 \noindent
173 All possible object types for `\texttt{PDFobject}' are listed in Table~\ref{Table2}.
174 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.
175
176 \begin{table}[h]
177 \begin{tabular}{|l|p{2.1in}|} \hline
178 boolean & \texttt{true}, \texttt{false} \\
179 numeric & \texttt{123}, \texttt{34.5}, \texttt{-.002} \\
180 string & \texttt{(This is a string)}, \texttt{<901FA3>} \\
181 name & \texttt{/Name1}, \texttt{/.notdef} \\
182 array & \texttt{[3.14 false (Ralph) /Name1]} \\
183 dictionary & \texttt{<</Key1 (Value) /Key2 3.14>>} \\
184 null & \texttt{null} \\\hline
185 indirect & \texttt{12 0 R} \\
186 stream & \texttt{stream ... endstream} \\
187 \hline
188 \end{tabular}
189 \caption{\PDF\ object types~\cite[p.~51]{PDFReference}}
190 \label{Table2}
191 \end{table}
192
193 It is not simple to construct a stream object with the special command `\texttt{pdf:obj}' because
194 the length of the stream object must be specified explicitly, which is quite bothersome.
195 Imagine that you are trying to construct a stream object whose source comes from a file.
196 Is it possible with this special command?
197 Moreover, any stream object requires the keyword `\texttt{stream}' followed by an end-of-line marker.\note{%
198 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}.}
199
200 \DPX, therefore, provides new special commands for stream objects.
201
202 \begin{itemize}
203 \item\fbox{\ttfamily pdf:stream @name (string) <<dict>>} \\[\fafter]
204 constructs a stream object the source of which comes from the string object `\texttt{(string)}'.
205 The stream dictionary `\texttt{<<dict>>}' is optional, and the dictionary entry `\texttt{/Length}' is created automatically.
206 \end{itemize}
207
208 \noindent
209 The following two special commands, for instance, construct the same stream object.
210 The stream data of the second object is represented in the \ASCII\ base-85 encoding.~\cite[p.~70]{PDFReference}
211
212 \begin{verbatim}[\small]
213 \special{pdf:stream @name (xxxxxxxx)}
214 \special{pdf:stream @name (G^+IXG^+IX)
215 <</Filter/ASCII85Decode>>}
216 \end{verbatim}
217
218 \begin{itemize}
219 \item\fbox{\ttfamily pdf:fstream @name (filename) <<dict>>} \\[\fafter]
220 constructs a stream object in the same way as `\texttt{pdf:stream}', but the source of stream data comes from a file `\texttt{filename}'.
221 \end{itemize}
222
223 \noindent
224 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.)
225
226 \begin{verbatim}[\small]
227 \special{pdf:fstream @myfile (mytest.tex)}
228 \special{pdf:ann bbox 0 0 10 10 <<
229 /Subtype /FileAttachment /FS <<
230 /Type /Filespec /F (mytest.tex)
231 /EF << /F @myfile >> >>
232 /Name /PushPin >>}
233 \end{verbatim}
234
235
236 \subsection{Adding content to named objects}
237
238 We describe the special command for adding content to named objects. The type of the named object must be either array or dictionary.
239
240 \begin{itemize}
241 \item\fbox{\ttfamily pdf:put @arrayobj object$_1$ $\ldots$ object$_n$} \\[\fafter]
242 appends the $n$ objects at the end of the array object `\texttt{@arrayobj}'.
243 \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>>}'.
244 \end{itemize}
245
246 \noindent
247 In the following example, the value of the key `\texttt{/X}' in the dictionary object `\texttt{@name}' is `\texttt{@Moon2}'.
248 (See~\cite[p.~15]{pdfmark} for corresponding \pdfmark\ operators.)
249
250 \begin{verbatim}[\small]
251 \special{pdf:put @Moon1
252 [ (Earth to Moon) 238855 /mies ]}
253 \special{pdf:obj @Moon2 []}
254 \special{pdf:put @Moon2 (Moon to Earth)}
255 \special{pdf:put @Moon2 238855}
256 \special{pdf:put @Moon2 /miles}
257 \special{pdf:obj @name <<>>}
258 \special{pdf:put @name << /X @Moon1 >>}
259 \special{pdf:put @name << /X @Moon2 >>}
260 \end{verbatim}
261
262 Note that \DPM\ does not allow adding content to a stream dictionary object, but \DPX\ does.
263
264 \begin{itemize}
265 \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.
266 \end{itemize}
267
268 Finally, \DPMx{} provides the special command
269 \fbox{\ttfamily pdf:close @name} to prevent further modifying the content of `\texttt{@name}'. After closing the named object, it can only be referenced.
270
271
272 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
273 \section{Annotations}
274
275 An annotation is considered as an object with a location on a page.
276 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.
277 (See~\cite[p.~615]{PDFReference} for the list of all annotation types.)
278 The location is given by an array object associated to the key `\texttt{/Rect}'.
279 \DPMx{} provides the following special command for annotations.
280
281 \begin{itemize}
282 \item\fbox{\hbadness=10000
283 \parbox{.43\textwidth}{\ttfamily pdf:ann @name width [length] height [length] depth [length] <<dict>>}}
284 \par\vspace{\fafter}\noindent
285 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}'.
286 \end{itemize}
287
288 \noindent
289 It is not possible to specify the location in an absolute way.
290 Any value of the key `\texttt{/Rect}' in the annotation dictionary `\texttt{<<dict>>}' will be ignored if found.
291 It is not allowed to modify the annotation dictionary with `\texttt{pdf:put}' command, so `\texttt{@name}' must be used as a reference.
292
293 Note that \DPX\ allows the `\texttt{bp}' unit in the dimension parameters, but \DPM\ does not.
294 Moreover, \DPX\ supports the following form.
295
296 \begin{itemize}
297 \item\fbox{\hbadness=10000
298 \parbox{.425\textwidth}{\ttfamily pdf:ann @name bbox [ulx] [uly] [lrx] [lry] <<dict>>}}
299 \par\vspace{\fafter}\noindent
300 The relative location is given by the bounding box consisting of four numbers in `\texttt{bp}' units.
301 \end{itemize}
302
303 \noindent
304 The following example shows a movie annotation that enables us to run the movie file `\texttt{mymovie.avi}' inside a \PDF\ viewer program.
305
306 \begin{verbatim}
307 \special{pdf:ann bbox 0 0 360 180 <<
308 /Subtype /Movie /Border [1 0 0]
309 /T (My Movie) /Movie <<
310 /F (mymovie.avi) /Aspect [720 360]
311 /Poster true >>
312 /A << /ShowControls false >> >>}
313 \end{verbatim}
314
315 \DPMx{} provides other special commands for \emph{breakable} annotations, e.g., an annotation broken over several lines or several pages.
316
317 \begin{itemize}
318 \item\fbox{\ttfamily pdf:bann <<dict>>} \ begins a breakable annotation.
319 Object name is not allowed for this command.
320 \item\fbox{\ttfamily pdf:eann} \ terminates the previous breakable annotation.
321 \end{itemize}
322
323 \noindent
324 These specials are mainly used for `\texttt{/Link}' annotation as the following example shows.
325
326 \begin{verbatim}[\small]
327 \special{pdf:bann << /Subtype /Link
328 /BS << /Type /Border /W 0.5 /S /S >>
329 /A << /S /URI
330 /URI (http://www.tug.org) >> >>}%
331 http://www.tug.org%
332 \special{pdf:eann}
333 \end{verbatim}
334
335 \noindent
336 \emph{Warning:} No annotation will be constructed if the content between `\texttt{pdf:bann}' and `\texttt{pdf:eann}' is an empty box. For example:
337
338 \begin{verbatim}[\small]
339 \special{pdf:bann << /Subtype /Link ... >>}
340 \vbox to 7.5pt{}\kern 10pt
341 \sepcial{pdf:eann}
342 \end{verbatim}
343
344 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{}.
345
346
347 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
348 \section{Outlines (or bookmarks)}
349
350 The document outline consists of a tree-structured hierarchy of outline items (sometimes called bookmarks) for which \DPMx{} provides the following special command.
351
352 \begin{itemize}
353 \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}.
354 \end{itemize}
355
356 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}}
357 The `\texttt{bookmarksopen=true}' option of the hyperref package does not work if the \PDF\ output is generated by \DPM.
358
359 \begin{verbatim}[\small]
360 \usepackage[
361 dvipdfm,bookmarks=true,bookmarksopen=true
362 ]{hyperref}
363 \end{verbatim}
364
365 \DPX\ provides two solutions for this problem.
366 The first one is to specify the option `\texttt{-O $n$}' when running \DPX.
367 Up to level $n$, the outline entries will be open. The second, and complete, solution is to use this extended special command:
368
369 \begin{itemize}
370 \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.
371 \end{itemize}
372
373 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}'.
374
375 \begin{verbatim}[\small]
376 \usepackage[%
377 dvipdfmx,bookmarks=true,
378 bookmarksopen=true,
379 bookmarksopenlevel=1,
380 dvipdfmx-outline-open
381 ]{hyperref}
382 \end{verbatim}
383
384
385 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
386 \section{External objects (or XObjects)}
387
388 \DPMx{} supports two types of \emph{external objects},\note{%
389 ``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}
390 } an image \XObject{} and a form \XObject.
391
392 \begin{itemize}
393 \item\fbox{\hbadness=10000
394 \parbox{.42\textwidth}{\ttfamily pdf:image @name width [length] height [length] depth [length] (imagefile)}}
395 \par\vspace{\fafter}\noindent
396 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.
397 \item\fbox{\hbadness=10000
398 \parbox{.42\textwidth}{\ttfamily pdf:bxobj @name width [length] height [length] depth [length]}}
399 \par\vspace{\fafter}\noindent
400 begins the definition of a form \XObject.
401 As with the command `\texttt{pdf:add}', \DPX\ allows bounding box `\texttt{bbox [ulx] [uly] [lrx] [lry]}' for dimension parameters.
402 \item\fbox{\ttfamily pdf:exobj} \ ends the previous form \XObject\ definition.
403 \item\fbox{\ttfamily pdf:uxobj @name} \ displays the image \XObject\ or the form \XObject\ previously defined and associated with `\texttt{@name}'.
404 \DPM$x$ allows dimension parameters (same as `\texttt{pdf:image}') after `\texttt{@name}'.
405 \end{itemize}
406
407 \noindent
408 Typical examples showing how to use image \XObject{}s and form \XObject{}s can be found in~\cite[pp.~15--16]{Cho05}.
409
410 \begin{figure}[h]
411 \centering\includegraphics{transparencygroup.pdf}
412 \caption{Two form \XObject{}s with opacity 0.5; the right one is a group \XObject.}
413 \label{Figure1}
414 \end{figure}
415
416 \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}}
417 Figure~\ref{Figure1} shows the difference between a normal \XObject\ and a group \XObject.
418
419 \begin{itemize}
420 \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.
421 \end{itemize}
422
423 \noindent
424 The following code draws the right image in Figure~\ref{Figure1}.
425
426 \begin{verbatim}[\small]
427 \special{pdf:bxobj @group bbox 0 0 50 50}
428 \special{pdf:code
429 15 w 0 0 m 50 50 l S 50 0 m 0 50 l S}
430 \special{pdf:exobj << /Group
431 << /S /Transparency >> >>}
432 \special{pdf:obj @extgstate
433 << /CA0.5 <</CA 0.5>> /ca0.5 <</ca 0.5>> >>}
434 \special{pdf:put @resources
435 << /ExtGState @extgstate >>}
436 \special{pdf:code /CA0.5 gs /ca0.5 gs}
437 \special{pdf:uxobj @group}
438 \end{verbatim}
439
440 \noindent We get the left image if \verb+\special{pdf:exobj}+ is used instead of the 4th and the 5th line.
441
442
443 \section{Raw PDF Operators}
444
445 This final section deals with writing raw \PDF\ operators in the output.
446 \DPM\ provides a special command for this feature.
447
448 \begin{itemize}
449 \item\fbox{\ttfamily pdf:content Operators} \vadjust{\vskip2pt} adds the list of operators ``\texttt{Operators}'' to the current page at the current location.
450 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.
451 \end{itemize}
452
453 For instance, the special command
454
455 \begin{verbatim}
456 \special{pdf:content 10 w 0 0 m 50 50 l S}
457 \end{verbatim}
458
459 \noindent
460 inserts the following list of operators in the output.
461
462 \smallskip\noindent
463 {\fontsize{9pt}{11pt}\selectfont
464 %\begin{verbatim}
465 \ttfamily\ldots\,%
466 \fbox{\strut q}\,\fbox{\strut 1 0 0 1 $x$ $y$ cm}\,%
467 10 w 0 0 m 50 50 l S
468 \fbox{\strut Q}\,%
469 \ldots
470 %\end{verbatim}
471 }
472
473 We sometimes need to insert \PDF\ operators without additional graphics state operators.
474 The author of the \PGF\ package devised a trick:
475
476 {\hfuzz=5pt
477 \begin{verbatim}
478 \special{pdf:content Q ... Operators ... q}
479 \end{verbatim}
480 }
481
482 \noindent
483 The first operator `\texttt{Q}' and the last operator `\texttt{q}' nullify the effects of graphics state operators that are attached.
484
485 \DPX\ provides a new special command instead of the trick above.
486
487 \begin{itemize}
488 \item\fbox{\ttfamily pdf:literal direct Operators}\note{%
489 The idea of `\texttt{pdf:literal direct}' came from the primitive `\cs{pdfliteral direct}' of \pdfTeX.} \ or simply\\[\fafter]
490 \fbox{\ttfamily pdf:code Operators} \ plays the same role as\\[\fafter]
491 `\texttt{pdf:content}, but no graphics state operator and no
492 transformation matrix will be added.
493 \end{itemize}
494
495 \begin{figure}[h]
496 \centering\includegraphics{bcontent.pdf}
497 \caption{The location of `23' in the left image varies according to the location of 1 in the current page.}
498 \label{Figure2}
499 \end{figure}
500
501 Consider the following code, labelled Listing~\ref{Code1}. Which image in Figure~\ref{Figure2} does this code generate?
502
503 \renewcommand{\tablename}{Listing}
504 \setcounter{table}{0}
505 \begin{table}[h]
506 %{
507 \hfuzz=5pt
508 \fontsize{9pt}{11pt}\selectfont
509 \begin{verbatim}
510 \def\bpic{\special{pdf:content q}}
511 \def\epic{\special{pdf:content Q}}
512 \def\myop#1{\special{pdf:content Q #1 q}}
513 1\bpic2\myop{.5 G 10 w 0 0 m 100 100 l S}3\epic4
514 \end{verbatim}
515 %}
516 \caption{Which image in Figure~\ref{Figure2} is the result of this code, produced by \DPM($x$)?}
517 \label{Code1}
518 \end{table}
519
520 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}'.
521
522 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.
523 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}.
524
525 To produce the right-hand image, \DPX\ provides the following new special commands.
526
527 \begin{itemize}
528 \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.
529 \item\fbox{\ttfamily pdf:econtent} \ ends the current block.
530 \end{itemize}
531
532 \noindent
533 Moreover, `\texttt{pdf:bcontent}' and `\texttt{pdf:econtent}' can be nested.
534
535 Finally, we can get the right-hand image in Figure~\ref{Figure2} as the result of Listing~\ref{Code2} following, produced by \DPX.
536
537 \begin{table}[h]
538 %{
539 \hfuzz=5pt
540 \fontsize{9pt}{11pt}\selectfont
541 \begin{verbatim}
542 \def\bpic{\special{pdf:bcontent}}
543 \def\epic{\special{pdf:econtent}}
544 \def\myop#1{\special{pdf:code #1}}
545 1\bpic2\myop{.5 G 10 w 0 0 m 100 100 l S}3\epic4
546 \end{verbatim}
547 %}
548 \caption{The right-hand image in Figure~\ref{Figure2} is the result of this example produced by \DPX.}
549 \label{Code2}
550 \end{table}
551
552 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
553 \SetBibJustification\raggedright
554 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
555 \begin{thebibliography}{99}
556
557 \bibitem{PDFReference} Adobe Systems, Inc., \emph{\PDF\ Reference}, \nth{6} edition (Version 1.7, November 2006).
558 \url{http://www.adobe.com/devnet/acrobat/pdfs/pdf_reference_1-7.pdf}.
559
560 \bibitem{pdfmark} Adobe Systems, Inc., \emph{\pdfmark\ Reference}
561 (Version 8.0, November 2006).
562 \url{http://www.adobe.com/devnet/acrobat/pdfs/pdfmark_reference.pdf}.
563
564 \bibitem{Cho03}
565 Jin-Hwan Cho, \emph{\DPX, an extension of \DPM},
566 \tug\ 2003. Hawaii, United States.
567 \url{http://project.ktug.or.kr/dvipdfmx/doc/tug2003.pdf}.
568
569 \bibitem{Cho05}
570 Jin-Hwan Cho, \emph{Practical Use of Special Commands in \DPX},
571 \tug\ 2005, International Typesetting Conference. Wuhan, China.
572 \url{http://project.ktug.or.kr/dvipdfmx/doc/tug2005.pdf}.
573
574 \bibitem{Cho07}
575 Jin-Hwan Cho, \emph{Hacking \DVI\ files: Birth of \DVIasm}, The Prac\TeX\ Journal (2007), no.~1, and TUGboat 28:2, 2007, 210--217.
576 \url{http://tug.org/TUGboat/Articles/tb28-2/tb89cho.pdf}.
577
578 \bibitem{Cho08}
579 Jin-Hwan Cho, \emph{Handling Two-Byte Characters with \DVIasm}, The Asian Journal of \TeX\ \textbf{2} (2008), no.~1, 63--68.
580 \url{http://ajt.ktug.kr/assets/2008/5/1/0201cho.pdf}.
581
582 \bibitem{DVIasm}
583 Jin-Hwan Cho, \emph{The \DVIasm\ Python script}.
584 \ctanloc{dviware/dviasm/}.
585
586 \bibitem{hyperref}
587 Heiko Oberdiek, \emph{The hyperref package} (Version 6.78f, August 2008).
588 \ctanloc{macros/latex/contrib/hyperref/}
589
590 \bibitem{beamer}
591 Till Tantau, \emph{The beamer package} (Version 3.07, March 2007).
592 \ctanloc{macros/latex/contrib/beamer/}.
593
594 \newpage
595 \bibitem{PGF}
596 Till Tantau, \emph{\PGF, A Portable Graphics Format for \TeX} (Version 2.00, February 2008).
597 \ctanloc{graphics/pgf/}.
598
599 \bibitem{DVIPDFM} Mark A. Wicks, \emph{\DPM\ User's Manual}
600 (Version 0.12.4, September 1999).
601 \url{http://gaspra.kettering.edu/dvipdfm/dvipdfm-0.12.4.pdf}.
602
603 \end{thebibliography}
604 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
605 \medskip
606 \makesignature
607 \end{document}
608 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%