From b04c2e1a42573e9735547702356c7b9a769a6855 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 7 Apr 2013 18:26:53 +0000 Subject: texmf -> texmf-dist: doc git-svn-id: svn://tug.org/texlive/trunk@29714 c570f23f-e606-0410-a88d-b1316a301751 --- .../texmf-dist/doc/dvipdfmx/dvipdfmx-special.pdf | Bin 0 -> 179950 bytes .../texmf-dist/doc/dvipdfmx/dvipdfmx-special.tex | 608 +++++++++++++++++++++ 2 files changed, 608 insertions(+) create mode 100644 Master/texmf-dist/doc/dvipdfmx/dvipdfmx-special.pdf create mode 100644 Master/texmf-dist/doc/dvipdfmx/dvipdfmx-special.tex (limited to 'Master/texmf-dist/doc/dvipdfmx') diff --git a/Master/texmf-dist/doc/dvipdfmx/dvipdfmx-special.pdf b/Master/texmf-dist/doc/dvipdfmx/dvipdfmx-special.pdf new file mode 100644 index 00000000000..5b64978c1a5 Binary files /dev/null and b/Master/texmf-dist/doc/dvipdfmx/dvipdfmx-special.pdf differ diff --git a/Master/texmf-dist/doc/dvipdfmx/dvipdfmx-special.tex b/Master/texmf-dist/doc/dvipdfmx/dvipdfmx-special.tex new file mode 100644 index 00000000000..64dbf22bd60 --- /dev/null +++ b/Master/texmf-dist/doc/dvipdfmx/dvipdfmx-special.tex @@ -0,0 +1,608 @@ +%% tb94cho.ltx +%% Copyright 2010 Jin-Hwan CHO +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% This work has the LPPL maintenance status `maintained'. +% +% The Current Maintainer of this work is Jin-Hwan CHO. + +\documentclass[final]{ltugboat} + +\usepackage{graphicx} +\usepackage{url} +%\usepackage{picins} +\usepackage{microtype} + +\def\CFF{\acro{CFF}} +\def\CID{\acro{CID}} +\def\CJK{\acro{CJK}} +\def\DTL{\acro{DTL}} +\def\DVIasm{\acro{DVI}asm} +\def\DVItype{\acro{DVI}type} +\def\DPS{\acro{DVIPS}} +\def\DPM{\acro{DVI\-PDFM}} +\def\DPMx{\acro{DVI\-PDFM}($x$)} +\let\DPX\DVIPDFMx +\def\pdfmark{pdfmark} +\def\GS{Ghostscript} +\def\EPS{\acro{EPS}} +\def\pdfTeX{pdf\/\TeX} +\def\LuaTeX{Lua\TeX} +\def\pTeX{p\kern-0.05em\TeX} +\def\XObject{\acro{XO}bject} +\def\fafter{1.5pt} + +\let\note=\footnote +\def\ctanloc#1{\url{http://mirror.ctan.org/#1}} +\setlength{\fboxsep}{1.5pt} + +%\divide\abovecaptionskip by 2 + +% don't go to a float page so soon: +%\renewcommand{\dbltopfraction}{.99} +%\renewcommand{\dblfloatpagefraction}{.8} + +\title{\DVI\ specials for \PDF\ generation} +\author{Jin-Hwan Cho} +\address{Department of Mathematics \\ The University of Suwon \\ Republic of Korea} +\netaddress{chofchof (at) ktug dot or dot kr} + +\begin{document} +\sectitle{Software \& Tools} +\maketitle + +\begin{abstract}% +\acro{DVIPDFM}($x$) manages various \PDF\ effects by means of \DVI\ specials. +Appropriate documentation of \DVI\ specials, however, is not easy to find, and exact functionality is not simple to catch without reading the source code of \DVI\ drivers. +This paper deals with the \DVI\ specials defined in \acro{DVIPDFM}($x$) that are mainly used for \PDF\ generation. +We discuss the features of those specials with some examples, many of which are not documented elsewhere. +\end{abstract} + +\section{Introduction} + +\DVI, the output file format of D.~E.~Knuth's \TeX, is not widely used at present compared with \PDF, the output format of \pdfTeX. +It is rather old\note{\DVI\ was designed by David R.~Fuchs in 1979.} and obsolete, but it has powerful aspects nonetheless: \emph{simplicity} and \emph{compactness}. + +These aspects make it possible to manipulate \DVI\ files in an easy and fast way. +Many \DVI\ utilities were developed to convert the \DVI\ format to other file formats including \PS\ and \PDF. +It is also possible to edit \DVI\ files directly by the use of \DVIasm~\cite{Cho07,Cho08,DVIasm}. + +Twenty years ago, at the time \PS\ dominated the printing world, nobody expected a new format would replace \PS. +\PDF\ is not eternal either. +In future, when a new format surpassing \PDF\ appears, \DVI\ will be the first format in the \TeX\ world that can be converted to the new format. +Notice that \LuaTeX, considered to be the next generation of \pdfTeX, still supports the \DVI\ format. + +There are two popular ways to convert \DVI\ to \PDF. +The first one is a two-way conversion, from \DVI\ to \PS\ with \DPS, and then from \PS\ to \PDF\ with a distiller. +Adobe Acrobat Distiller is the oldest commercial program, and \GS\ is the most popular distiller in the \TeX\ world. \MacOSX\ also has its own distiller. + +Adobe designed the \pdfmark\ operator~\cite{pdfmark} for its distiller to support \PDF\ features that are not expressible using the standard \PS\ operators. +The \pdfmark\ operator is given in the \TeX\ source by means of a \DVI\ special command. +Note that it is not \DPS\ but a distiller that processes the \pdfmark\ operator. + +Mark A.~Wicks' \DPM~\cite{DVIPDFM} introduced the other way of converting \DVI\ directly to \PDF. +He also designed new \DVI\ specials based on the \pdfmark\ operator to support various \PDF\ features. +The new specials, however, lacked some functionality in practical use so that not many \PDF\ features could be obtained compared with \pdfTeX. + +One of the main goal of \DPX, an extension of \DPM\ that grew out of the \CJK\note{Chinese, Japanese, and Korean.} support, was to provide as many \PDF\ features as \pdfTeX~\cite{Cho03}. +\DPX\ extended the functionality of some special commands of \DPM, and designed new special commands having a similar functionality of \pdfTeX's own primitives. +Furthermore, \DPX\ has several powerful features not available in \DPM. + \begin{itemize} + \item Support 16-bit character sets (\CJK\ encodings and Unicode) with \CID-keyed font technology. + \item Support various font formats including OpenType, TrueType, etc. + \item Use \CFF\ font format for embedded Type1 \PS\ fonts so that the size of the \PDF\ output is quite small compared with \pdfTeX's output. + \item Support extended \TeX\ engines, e.g., Omega, Japanese \pTeX, \XeTeX\ (via \acro{XDVIPDFMX}).\note{Upcoming version of \DPX\ will support the \DVI\ output generated by \LuaTeX.} + \end{itemize} + +The \acro{TODO} list of \DPX\ had contained one outstanding item for a long time: supporting Till Tantau's beamer package~\cite{beamer}, that is widely used for \PDF\ presentation. +In fact, this package does not handle \DVI\ specials in a direct way. +Instead, the graphics part comes from the same author's \PGF\ package~\cite{PGF}, and the other \PDF\ effects come from the hyperref package~\cite{hyperref}. + +\DPX\ has supported full functionality of the \PGF\ package since June 2008.\note{The \DPX\ driver that works with the \PGF\ package included in \TeX\ Live 2008 can be downloaded from \url{http://project.ktug.or.kr/dvipdfmx/contrib/generic/}.} +Nonetheless, the navigation buttons usually shown in the lower right corner of the presentation still did not work, although they were displayed correctly. +The source code\note{\raggedright \ctanloc{macros/latex/contrib/beamer/base/beamerbasenavigation.sty}} implementing the buttons was + +\begin{verbatim}[\small] +\def\beamer@linkspace#1{\vbox to7.5pt{}\kern#1} +\end{verbatim} + +The code above generates an \emph{empty} box that will be surrounded by the two special commands, `\texttt{pdf:bann}' (before) and `\texttt{pdf:eann}' (after). +Unfortunately, neither \DPM\ nor \DPX\ construct any annotation in the case of an empty box. +Another special command `\texttt{pdf:ann}' must be used instead for this purpose. +That was the exact reason why the navigation buttons did not work. + +Why did the author of the beamer package make such a mistake? +As a matter of fact, it was not his fault because no statement could be found about that functionality in the manual of \DPM~\cite{DVIPDFM}. +This unhappy story led to this paper. + +The author gave a presentation~\cite{Cho05} at \tug\ 2005, in which the different behaviors of \DVI\ specials of \DPS, \DPM, and \DPX\ were discussed. +\DVI\ specials for \PDF\ generation, however, were not fully discussed at that time. +The main objective of this paper is to bridge this gap. + +We will discuss in the following sections the features of \DVI\ specials defined in \DPM\ for \PDF\ generation, and the extended features given by \DPX. +The author hopes this paper would be useful for package writers who are finding appropriate information on \DVI\ specials. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Named PDF objects} + +There are two kinds of named objects, built-in and user-defined \PDF\ objects. + +\subsection{Built-in named objects} + +Built-in objects defined in \DPMx{} are listed in Table~\ref{Table1}. We refer to~\cite[p.~12]{pdfmark} and~\cite[p.~5]{DVIPDFM} for \pdfmark\ and \DPM\ built-in objects, respectively. +Notice that it is not allowed to modify the contents of the last five built-in objects in Table~\ref{Table1}. + +\begin{table}[h] +\begin{tabular}{|l|p{1.95in}|} \hline +\texttt{@catalog} & catalog dictionary~\cite[p.~139]{PDFReference} \\ +\texttt{@docinfo} & (\DPX\ only) document\newline information dictionary \cite[p.~844]{PDFReference} \\ +\texttt{@names} & name dictionary~\cite[p.~150]{PDFReference} \\ +\texttt{@pages} & root page tree node \cite[p.~143]{PDFReference} \\ +\texttt{@resources} & resource dictionary of current\newline page \cite[p.~154]{PDFReference} \\ +\texttt{@thispage} & current page object \cite[p.~145]{PDFReference} \\\hline +\texttt{@prevpage} & reference only \\ +\texttt{@nextpage} & reference only \\ +\texttt{@page$n$} & reference only \\ +\texttt{@xpos} & reference only \\ +\texttt{@ypos} & reference only \\ +\hline +\end{tabular} +\caption{Built-in objects defined in \DPMx{}} +\label{Table1} +\end{table} + + +\subsection{User-defined named objects} + +Two special commands are provided by \DPMx{} for user-defined objects. +One is to define a named object, and the other is to add content to the previously defined object. + +\begin{itemize} +\item\fbox{\ttfamily pdf:obj @name PDFobject} \ creates a named object that can be referenced later by `\texttt{@name}'. +\end{itemize} + +\noindent +All possible object types for `\texttt{PDFobject}' are listed in Table~\ref{Table2}. +In the case of indirect objects, the object number must be given explicitly, so that this feature is rarely used, especially to specify the objects in a different \PDF\ file. + +\begin{table}[h] +\begin{tabular}{|l|p{2.1in}|} \hline +boolean & \texttt{true}, \texttt{false} \\ +numeric & \texttt{123}, \texttt{34.5}, \texttt{-.002} \\ +string & \texttt{(This is a string)}, \texttt{<901FA3>} \\ +name & \texttt{/Name1}, \texttt{/.notdef} \\ +array & \texttt{[3.14 false (Ralph) /Name1]} \\ +dictionary & \texttt{<>} \\ +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) <>} \\[\fafter] +constructs a stream object the source of which comes from the string object `\texttt{(string)}'. +The stream dictionary `\texttt{<>}' 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) + <>} +\end{verbatim} + +\begin{itemize} +\item\fbox{\ttfamily pdf:fstream @name (filename) <>} \\[\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 <>} \ merges the dictionary object `\texttt{<>}' 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{<>}'. +\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 <>} \ \ merges the dictionary object `\texttt{<>}' into the stream dictionary of `\texttt{@streamobj}'. The dictionary entries, `\texttt{/Length}' and `\texttt{/Filter}', in the object `\texttt{<>}' 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] <>}} +\par\vspace{\fafter}\noindent +The annotation dictionary is given by `\texttt{<>}' 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{<>}' 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] <>}} +\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 <>} \ 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$ <>} \ adds an outline item to the document. The integer parameter $n$ represents the level of the outline entry (beginning with 1), and `\texttt{<>}' 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$ <>} \ 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 <>} \ merges the dictionary object `\texttt{<>}' 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 <> /ca0.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} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -- cgit v1.2.3