path: root/systems/doc/dvipdfmx/dvipdfmx-special.tex

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