| 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 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |