| 1 |
% $Id$ |
| 2 |
% dvipdfmx manual. GFDL 1.3 or later. |
| 3 |
% https://ctan.org/pkg/dvipdfmx |
| 4 |
\documentclass[a4paper,xetex,11pt]{report} |
| 5 |
\hyphenation{Ja-pa-nese} |
| 6 |
\usepackage{fullpage} |
| 7 |
\usepackage{xltxtra} |
| 8 |
\usepackage{fontspec} |
| 9 |
\usepackage{microtype} |
| 10 |
\usepackage{xunicode} |
| 11 |
\usepackage{unicode-math} |
| 12 |
|
| 13 |
% cm fonts suffice for the text. |
| 14 |
\usepackage[olddefault]{fontsetup} |
| 15 |
|
| 16 |
%% The following section is for showing some fancy examples. |
| 17 |
%% Some fonts used here may not be availabel on your system. |
| 18 |
%% Please modify this. Just replacing with empty macros is OK. |
| 19 |
\newcommand{\jpzerofourexamples}{{% |
| 20 |
\setmainfont[Scale=5,RawFeature=+jp04]{HaranoAjiMincho-Light.otf}葛祇逢}} |
| 21 |
\newcommand{\jpninezeroexamples}{{% |
| 22 |
\setmainfont[Scale=5,RawFeature=+jp90]{HaranoAjiMincho-Light.otf}葛祇逢}} |
| 23 |
%% We use PostScript raw code here to test dvipdfmx's capability. |
| 24 |
%% TFM files `urml' and `urmlv' are distributed with upTeX. |
| 25 |
%% TrueType font `ipaexm.ttf' is bundled with TeX Live. |
| 26 |
\newcommand{\jphoritext}{% |
| 27 |
\makebox[112bp][l]{% |
| 28 |
\raisebox{88bp}[112bp][0bp]{% |
| 29 |
\special{pdf:mapline urml UniJIS-UTF8-H ipaexm.ttf} |
| 30 |
\special{ps: urml findfont 16 scalefont setfont |
| 31 |
currentpoint moveto (「こんにちは」) show}% |
| 32 |
}}} |
| 33 |
% |
| 34 |
\newcommand{\jpverttext}{% |
| 35 |
\makebox[16bp][l]{% |
| 36 |
\raisebox{112bp}[112bp][0bp]{% |
| 37 |
\special{pdf:mapline urmlv UniJIS-UTF8-V ipaexm.ttf} |
| 38 |
\special{ps: urmlv findfont 16 scalefont setfont |
| 39 |
currentpoint moveto (「こんにちは」) show}% |
| 40 |
}}} |
| 41 |
|
| 42 |
\usepackage{listings} |
| 43 |
\lstset{ |
| 44 |
keepspaces=true, |
| 45 |
basicstyle={\ttfamily}, |
| 46 |
frame={tb}, |
| 47 |
breaklines=true, |
| 48 |
columns=[l]{fullflexible}, |
| 49 |
numbers=none, |
| 50 |
xrightmargin=2em, |
| 51 |
xleftmargin=2em, |
| 52 |
aboveskip=2em, |
| 53 |
belowskip=2em |
| 54 |
} |
| 55 |
|
| 56 |
\usepackage{mflogo} |
| 57 |
\usepackage{lipsum} |
| 58 |
\usepackage{array} |
| 59 |
\usepackage{marginnote} |
| 60 |
\renewcommand*{\marginfont}{\footnotesize\itshape} |
| 61 |
\usepackage[noorphans,font=itshape]{quoting} |
| 62 |
\newcommand{\package}[1]{\textit{#1}} |
| 63 |
\newcommand{\code}[1]{\mbox{\texttt{#1}}} |
| 64 |
\newcommand{\keyword}[1]{\textit{#1}} |
| 65 |
\newcommand{\option}[1]{\mbox{`\texttt{#1}'}} |
| 66 |
\newcommand{\dvipdfm}{\texttt{dvipdfm}} |
| 67 |
\newcommand{\dvipdfmx}{\texttt{dvipdfmx}} |
| 68 |
\newcommand{\xdvipdfmx}{\texttt{xdvipdfmx}} |
| 69 |
\newcommand{\deprecated}[1]{\marginnote{\addfontfeatures{Color=CC3333}#1}} |
| 70 |
\newcommand{\newfeature}[1]{\marginnote{\addfontfeatures{Color=3366CC}#1}} |
| 71 |
\newcommand{\lnum}[1]{{\addfontfeatures{RawFeature=+lnum}#1}} |
| 72 |
% For placeing drawings via \special |
| 73 |
\newcommand{\specialbox}[3]{% |
| 74 |
\makebox[#1][l]{\raisebox{-#2}[0bp][#2]{\special{#3}}}} |
| 75 |
|
| 76 |
\usepackage{xcolor,hyperref,hyperxmp} |
| 77 |
\hypersetup{% |
| 78 |
bookmarksnumbered=true,% |
| 79 |
linktocpage=true, |
| 80 |
hidelinks, |
| 81 |
%colorlinks=true,% |
| 82 |
%urlcolor=[rgb]{0.2,0.2,0.4}, |
| 83 |
%linkcolor=[rgb]{0.2,0.2,0.4}, |
| 84 |
%citecolor=[rgb]{0.2,0.2,0.4}, |
| 85 |
pdftitle={The Dvipdfmx User Manual},% |
| 86 |
pdfauthor={The Dvipdfmx project team},% |
| 87 |
pdfsubject={A User's Manual for Dvipdfmx and Xdvipdfmx.},% |
| 88 |
pdfkeywords={dvipdfmx, XeTeX, TeX, LaTeX}, |
| 89 |
pdflang=en, |
| 90 |
pdfcopyright={Copyright © The dvipdfmx project team. |
| 91 |
Permission is granted to copy, distribute and/or modify this document |
| 92 |
under the terms of the GNU Free Documentation License, Version 1.3 |
| 93 |
or any later version published by the Free Software Foundation; |
| 94 |
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. |
| 95 |
A copy of the license is included in the section entitled "GNU |
| 96 |
Free Documentation License".}, |
| 97 |
pdflicenseurl={https://www.gnu.org/licenses/fdl.html} |
| 98 |
} |
| 99 |
|
| 100 |
%\pagestyle{headings} |
| 101 |
\usepackage{fancyhdr} |
| 102 |
\pagestyle{fancy} |
| 103 |
% |
| 104 |
\setlength{\headheight}{14pt} |
| 105 |
\setlength{\headsep}{18pt} |
| 106 |
\addtolength{\topmargin}{-6pt} |
| 107 |
|
| 108 |
%%DVIPDFMX SETTINGS |
| 109 |
\AtBeginDocument{% |
| 110 |
\special{dvipdfmx:config O 1}% |
| 111 |
\special{dvipdfmx:config V 7} |
| 112 |
} |
| 113 |
|
| 114 |
\title{The Dvipdfmx user manual} |
| 115 |
\author{The Dvipdfmx project team} |
| 116 |
\date{% |
| 117 |
\hspace*{1em}\\ \today\\ |
| 118 |
\hspace*{1em}\\ \url{https://ctan.org/pkg/dvipdfmx} |
| 119 |
} |
| 120 |
|
| 121 |
|
| 122 |
\begin{document} |
| 123 |
\maketitle |
| 124 |
|
| 125 |
%\begin{titlepage} |
| 126 |
% \begin{raggedleft} |
| 127 |
% {\Huge\bfseries Dvipdfmx User Manual}\\[\baselineskip] |
| 128 |
% \Large \advance |
| 129 |
% Dvipdfmx Project Team\\ |
| 130 |
% \url{https://ctan.org/pkg/dvipdfmx}\\ |
| 131 |
% \today\par |
| 132 |
% \end{raggedleft} |
| 133 |
%\end{titlepage} |
| 134 |
|
| 135 |
\tableofcontents |
| 136 |
|
| 137 |
\chapter{Getting Started} |
| 138 |
|
| 139 |
\section{Introduction} |
| 140 |
|
| 141 |
The \dvipdfmx\ (formerly \dvipdfm-cjk) project provides an extended version of |
| 142 |
the \dvipdfm, a DVI to PDF translator developed by Mark~A.~Wicks. |
| 143 |
|
| 144 |
The primary goal of this project is to support multi-byte character encodings |
| 145 |
and large character sets such as those for East Asian languages. |
| 146 |
This project started as a combined work of the \dvipdfm-jpn project by |
| 147 |
Shunsaku Hirata and its modified one, \dvipdfm-kor, by Jin-Hwan Cho. |
| 148 |
|
| 149 |
Extensions to \dvipdfm\ include, |
| 150 |
\begin{itemize} |
| 151 |
\item Support for OpenType and TrueType fonts, including partial support |
| 152 |
for OpenType Layout features for glyph variants and for vertical writing. |
| 153 |
\item Support for CJK-\LaTeX\ and H\LaTeX\ with Subfont Definition Files. |
| 154 |
\item Support for various legacy multi-byte encodings via PostScript CMap |
| 155 |
Resources. |
| 156 |
\item Unicode related features: Unicode as an input encoding and |
| 157 |
auto-creation of ToUnicode CMaps. |
| 158 |
\item Support for p\TeX\ (a Japanese localized variant of \TeX) including |
| 159 |
vertical writing extension. |
| 160 |
\item Some extended DVI specials. |
| 161 |
\item Reduction of output files size with on-the-fly Type1 to CFF (Type1C) |
| 162 |
conversion and PDF object stream. |
| 163 |
\item Advanced raster image support including alpha channels, embedded |
| 164 |
ICC profiles, 16-bit bit-depth colors, and so on. |
| 165 |
\item Basic PDF password security support. (only for output) |
| 166 |
\end{itemize} |
| 167 |
Some important features are still missing: |
| 168 |
\begin{itemize} |
| 169 |
\item Linearization. |
| 170 |
\item Color Management. |
| 171 |
\item Resampling of images. |
| 172 |
\item Selection of compression filters. |
| 173 |
\item Variable font and OpenType 1.8. |
| 174 |
\item and plenty more... |
| 175 |
\end{itemize} |
| 176 |
|
| 177 |
\dvipdfmx\ is now maintained as part of \TeX\ Live. Latest source code can |
| 178 |
be found at the \TeX\ Live SVN repository. For an instruction on accessing the |
| 179 |
development sources for \TeX\ Live, see,\medskip |
| 180 |
|
| 181 |
\url{https://tug.org/texlive/svn/} |
| 182 |
\medskip |
| 183 |
|
| 184 |
\noindent Please send bug reports, questions, or suggestions to |
| 185 |
the public mailing list, \texttt{[email protected]}. For more information, |
| 186 |
see \url{https://ctan.org/pkg/dvipdmx}. |
| 187 |
|
| 188 |
\subsection{\xdvipdfmx} |
| 189 |
|
| 190 |
\xdvipdfmx\ is an extended version of \dvipdfmx, and is now incorporated into |
| 191 |
\dvipdfmx. |
| 192 |
|
| 193 |
The \xdvipdfmx\ extensions provides support for the Extended DVI (.xdv) format |
| 194 |
generated by \XeTeX\ which includes support for platform-native fonts and the |
| 195 |
\XeTeX\ graphics primitives, as well as Unicode text and OpenType font. |
| 196 |
|
| 197 |
\XeTeX\ originally used a Mac-specific program called \code{xdv2pdf} as |
| 198 |
a backend program instead of \xdvipdfmx. The \code{xdv2pdf} program |
| 199 |
supported some special effects that are not yet available through |
| 200 |
\xdvipdfmx: Quartz graphics-based shadow support, AAT ``variation'' |
| 201 |
fonts such as Skia, transparency as a font attribute, and so on. |
| 202 |
|
| 203 |
|
| 204 |
\subsection{Legal Notice} |
| 205 |
|
| 206 |
Copyright © The Dvipdfmx project team. |
| 207 |
Permission is granted to copy, distribute and/or modify this document |
| 208 |
under the terms of the GNU Free Documentation License, Version 1.3 |
| 209 |
or any later version published by the Free Software Foundation; |
| 210 |
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. |
| 211 |
A copy of the license is included in the section entitled |
| 212 |
``\hyperref[SEC:FDL]{GNU Free Documentation License}''. |
| 213 |
|
| 214 |
\section{Installation and Usage} |
| 215 |
|
| 216 |
\dvipdfmx\ is included in the \TeX\ distributions, so usually you don't |
| 217 |
have to install it separately. |
| 218 |
|
| 219 |
If you do wish to install it separately, typical usage and installation |
| 220 |
steps are not different from the original \dvipdfm. Please refer |
| 221 |
documents from \dvipdfm\ distribution for detailed instruction on how to |
| 222 |
install and how to use \dvipdfm. The \dvipdfm\ manual is available from |
| 223 |
its CTAN site:\medskip |
| 224 |
|
| 225 |
\url{https://ctan.org/tex-archive/dviware/dvipdfm} |
| 226 |
\medskip |
| 227 |
|
| 228 |
The minimal requirements for building \dvipdfmx\ is the \keyword{kpathsea} library. |
| 229 |
the \keyword{zlib} library for compression and the \keyword{libpng} library for PNG |
| 230 |
inclusion are highly recommended. |
| 231 |
Optionally, the \keyword{libpaper} library might be used to handle paper size. |
| 232 |
|
| 233 |
This document mainly focuses on the additions and modifications to \dvipdfm. |
| 234 |
Please refer the |
| 235 |
``\href{https://mirrors.ctan.org/dviware/dvipdfm/dvipdfm.pdf}{Dvipdfm User's Manual}'' |
| 236 |
available from the CTAN site mentioned above for basic usage. |
| 237 |
|
| 238 |
Some additional command line options recognized by \dvipdfmx\ are listed in |
| 239 |
Table~\ref{TABLE:options}. In addition to this, the \code{-V} option for specifying |
| 240 |
the output PDF version now accepts the version specification of a form \code{2.0}. |
| 241 |
Please try |
| 242 |
\begin{lstlisting} |
| 243 |
dvipdfmx --help |
| 244 |
\end{lstlisting} |
| 245 |
for a complete list of command line options and their explanations. |
| 246 |
|
| 247 |
\begin{table} |
| 248 |
\centering |
| 249 |
\begin{tabular}{lp{8cm}}\hline |
| 250 |
Option & Description \\ \hline\hline |
| 251 |
\code{-C} \textit{number} & Specify miscellaneous option flags. See, |
| 252 |
section of ``\hyperref[SEC:compatibility]{Incompatible Changes}'' for |
| 253 |
details. \\ |
| 254 |
\code{-S} & Enable PDF encryption. \\ |
| 255 |
\code{-K} \textit{number} & Set encryption key length. The default value |
| 256 |
is 40.\\ |
| 257 |
\code{-P} \textit{number} & Set permission flags for PDF encryption. |
| 258 |
The \textit{number} is a 32-bit unsigned integer representing permission |
| 259 |
flags. |
| 260 |
See, section of ``\hyperref[SEC:encryption]{Encryption Support}''. |
| 261 |
The default value is \code{0x003C}.\\ |
| 262 |
\code{-I} \textit{number} & Life of image cache in hours, relevant only when |
| 263 |
an image not directly supported by \dvipdfmx\ is used thus an external |
| 264 |
program is invoked to convert it to a PDF format intermediate file. |
| 265 |
This option basically specifies how long such intermediate files are preserved |
| 266 |
and reused. (to avoid an external program is invoked again and again whenever |
| 267 |
\dvipdfmx\ tries to include images) |
| 268 |
By specifying a value of \code{0}, \dvipdfmx\ erases existing cached images, |
| 269 |
and the value \code{-1} tells \dvipdfmx\ to erase all cached images and not to |
| 270 |
leave newly generated one. And \code{-2} indicates ``ignore image cache``. |
| 271 |
The default value is \code{-2}.\\ |
| 272 |
\code{-M} & Process \MP\ generated PostScript file.\\ |
| 273 |
\code{-E} & Always try to embed fonts \emph{regardless of |
| 274 |
licensing}.\\ |
| 275 |
\code{-O} \textit{number} & Set maximum depth of open bookmark item.\\ |
| 276 |
\hline |
| 277 |
\end{tabular} |
| 278 |
\caption{Additional command line options recognized by \dvipdfmx.}% |
| 279 |
\label{TABLE:options} |
| 280 |
\end{table} |
| 281 |
|
| 282 |
|
| 283 |
\section{Quick Guide} |
| 284 |
|
| 285 |
As the primary goal of \dvipdfmx\ is to support multi-byte character encodings |
| 286 |
and large character sets, its primary users are expected to be users of |
| 287 |
\LaTeX\ packages for typesetting CJK languages such as H\LaTeX\ and CJK-\LaTeX, |
| 288 |
and users of extended \TeX\ variants which are capable of handling those |
| 289 |
languages, like \XeTeX, p\TeX, and up\TeX. |
| 290 |
This section provides a ``Quick Guide'' for those users. |
| 291 |
|
| 292 |
\subsection{\texorpdfstring{\XeTeX}{XeTeX}} |
| 293 |
|
| 294 |
\XeTeX\ users |
| 295 |
normally do not invoke the \dvipdfmx\ command directly. To control the |
| 296 |
behavior of \dvipdfmx, please consider using the \code{dvipdfmx:config} |
| 297 |
special explained in the section of ``\hyperref[SEC:specials]{Specials}''. |
| 298 |
Some part of this document is irrelevant for \XeTeX\ users. |
| 299 |
|
| 300 |
\subsection{p\TeX} |
| 301 |
p\TeX\ users are at least required to install several auxiliary files |
| 302 |
mentioned in the section of ``\hyperref[SEC:auxfiles]{Auxiliary Files}'' |
| 303 |
and to setup font-mappings. Just install the \package{adobemappings} and |
| 304 |
\package{glyphlist} for auxiliary files. (As \TeX\ Live basic installation |
| 305 |
requires them, they are probably already installed for \TeX\ Live users.) |
| 306 |
|
| 307 |
For \TeX\ Live users, setting up fontmaps can be easily done with the help |
| 308 |
of the \package{ptex-fontmaps} package and the \keyword{updmap} program. |
| 309 |
To use with the IPAex fonts (contained in the \package{ipaex} package), for |
| 310 |
example, run, |
| 311 |
\begin{lstlisting} |
| 312 |
kanji-config-updmap --sys ipaex |
| 313 |
\end{lstlisting} |
| 314 |
where the \option{--sys} option indicates the system-wide configuration. |
| 315 |
After successful invocation of the above command, the IPAex fonts will |
| 316 |
be used by default. The current setting can be checked via, |
| 317 |
\begin{lstlisting} |
| 318 |
kanji-config-updmap --sys status |
| 319 |
\end{lstlisting} |
| 320 |
For more information on the updmap program, try, |
| 321 |
\begin{lstlisting} |
| 322 |
kanji-config-updmap --help |
| 323 |
\end{lstlisting} |
| 324 |
or refer the documentation of the updmap program. |
| 325 |
|
| 326 |
Alternatively, just for a quick test of installation, try the following: |
| 327 |
\begin{lstlisting} |
| 328 |
\documentclass{article} |
| 329 |
\begin{document} |
| 330 |
\special{pdf:mapline rml H KozMinProVI-Regular} |
| 331 |
...Some Japanese text goes here... |
| 332 |
\end{document} |
| 333 |
\end{lstlisting} |
| 334 |
In this example, PDF viewer which can handle substitute font is required since |
| 335 |
\dvipdfmx\ does not embed fonts. |
| 336 |
|
| 337 |
For using Japanese text in PDF document information and annotations, put |
| 338 |
the following \code{special} command, |
| 339 |
\begin{lstlisting} |
| 340 |
\AtBeginDocument{\special{pdf:tounicode 90ms-RKSJ-UCS2}} |
| 341 |
\end{lstlisting} |
| 342 |
in the preamble. |
| 343 |
The above \code{special} command instructs \dvipdfmx\ to convert text encoded |
| 344 |
in Shift-JIS to Unicode. For EUC-JP, replace 90ms-RKJK-UCS2 with EUC-UCS2. |
| 345 |
|
| 346 |
\subsection{up\TeX} |
| 347 |
up\TeX\ users are basically the same as p\TeX\ users but there are two choices |
| 348 |
for setting fontmaps. Setup fontmaps as mentioned above for p\TeX, or use |
| 349 |
keyword \code{unicode} in the encoding field of the fontmap file. |
| 350 |
|
| 351 |
The former might be easier as the auto-creation of fontmap files can be done |
| 352 |
with the updmap program and the \package{ptex-fontmaps} package. But in |
| 353 |
this method there are some difficulties when using fonts which employ character |
| 354 |
collections (glyph repertoire) other than Adobe-Japan\lnum{1} in the case of PostScript |
| 355 |
flavored OpenType fonts. |
| 356 |
In the later case, the \package{adobemappings} package is not required |
| 357 |
and newer PostScript flavored OpenType fonts which do not employ Adobe-Japan\lnum{1} |
| 358 |
can be easily used too. |
| 359 |
|
| 360 |
Using \code{unicode} is more simpler and intuitive thus it is recommended to |
| 361 |
use this method.\footnote{For \TeX\ Live 2017. Earlier versions have buggy |
| 362 |
support.} |
| 363 |
A typical example fontmap entries for using Adobe's SouceHan series |
| 364 |
might look like: |
| 365 |
\begin{lstlisting} |
| 366 |
urml unicode SourceHanSerifJP-Light.otf |
| 367 |
urmlv unicode SourceHanSerifJP-Light.otf -w 1 |
| 368 |
ugbm unicode SourceHanSansJP-Medium.otf |
| 369 |
ugbmv unicode SourceHanSansJP-Medium.otf -w 1 |
| 370 |
\end{lstlisting} |
| 371 |
|
| 372 |
As in p\TeX, the following \code{special} instruction might be necessary for PDF |
| 373 |
document information and annotations to be shown correctly: |
| 374 |
\begin{lstlisting} |
| 375 |
\AtBeginDocument{\special{pdf:tounicode UTF8-UCS2}} |
| 376 |
\end{lstlisting} |
| 377 |
Here, input encoding is assumed to be UTF-8. |
| 378 |
|
| 379 |
\subsection{CJK-\LaTeX} |
| 380 |
|
| 381 |
CJK-\LaTeX\ users are required to have \keyword{Subfont Definition Files} |
| 382 |
to be installed. They are available as part of the \package{ttfutils} package. |
| 383 |
|
| 384 |
To use TrueType Arphic fonts provided by the \package{arphic-ttf} package: |
| 385 |
\begin{lstlisting} |
| 386 |
\documentclass{article} |
| 387 |
\usepackage{CJKutf8} |
| 388 |
...Other packages loaded here... |
| 389 |
\AtBeginDocument{% |
| 390 |
\special{pdf:tounicode UTF8-UCS2}% |
| 391 |
\special{pdf:mapline bsmiu@Unicode@ unicode bsmi00lp.ttf}% |
| 392 |
} |
| 393 |
\begin{document} |
| 394 |
\begin{CJK}{UTF8}{bsmi} |
| 395 |
...some Chinese text goes here... |
| 396 |
\end{CJK} |
| 397 |
\end{document} |
| 398 |
\end{lstlisting} |
| 399 |
Here, \code{pdf:mapline} special is used to setup a font-mapping. |
| 400 |
|
| 401 |
\section{Overview of Extensions} |
| 402 |
|
| 403 |
This section gives a quick overview of \dvipdfmx's extended capabilities. |
| 404 |
|
| 405 |
\subsection{CJK Support} |
| 406 |
|
| 407 |
There are many extensions made for supporting CJK languages. Features described |
| 408 |
here are mainly for CJK languages. However, those features are implemented in a |
| 409 |
more generic way and hence they can be also beneficial to users who are not |
| 410 |
involved in CJK languages. |
| 411 |
|
| 412 |
\subsubsection{Legacy Multi-byte Encodings} |
| 413 |
|
| 414 |
\dvipdfmx\ has an extensible support for multi-byte encodings by means of PostScript |
| 415 |
CMap Resources. Just like various 8-bit encodings can be supported via \code{enc} file, |
| 416 |
various multi-byte encodings (including custom one) can be supported by preparing |
| 417 |
CMap files. |
| 418 |
See, Adobe's technical notes\cite{ADOBE} for details on PostScript CMap Resources. |
| 419 |
|
| 420 |
\subsubsection{Vertical Writing} |
| 421 |
|
| 422 |
\dvipdfmx\ supports the vertical writing extension used by p\TeX\ and up\TeX. |
| 423 |
A DVI instruction to set the writing mode is supported. The OpenType Layout |
| 424 |
GSUB Feature is supported for selecting vertical version of glyphs. |
| 425 |
|
| 426 |
\begin{figure} |
| 427 |
\centering |
| 428 |
\jphoritext\hspace{24pt}\jpverttext% |
| 429 |
\caption{An example of horizontal and vertical text; |
| 430 |
left and right corner brackets are replaced with their vertical counterparts.}% |
| 431 |
\label{FIG:verttext} |
| 432 |
\end{figure} |
| 433 |
|
| 434 |
\subsection{Unicode Support} |
| 435 |
|
| 436 |
Unicode support here consists of two parts: Supporting Unicode as an input |
| 437 |
encoding and making output PDF files ``Unicode aware'' (``ToUnicode CMap Support''). |
| 438 |
|
| 439 |
\subsubsection{Unicode as Input Encoding} |
| 440 |
|
| 441 |
\dvipdfmx\ recognizes an additional keyword \code{unicode} in the encoding entry of |
| 442 |
fontmap file, which declares that character code used in input DVI files for fonts |
| 443 |
with this keyword specified should be regarded as Unicode values. Unicode support is |
| 444 |
basically limited to the Basic Multilingual Plane (BMP) since there are no |
| 445 |
support for code ranges that requires more than two bytes in TFM and extended |
| 446 |
TFM formats. |
| 447 |
|
| 448 |
\subsubsection{ToUnicode CMap Support} |
| 449 |
|
| 450 |
In PDF, it is often the case that text is not encoded in Unicode. |
| 451 |
However, modern applications usually want them represented in Unicode to make |
| 452 |
it usable as text information. |
| 453 |
The ToUnicode CMap is a bridge between PDF text string encodings and Unicode |
| 454 |
encodings, and makes it possible to extract text in PDF files as |
| 455 |
Unicode encoded strings. It is important to make resulting PDF search-able and |
| 456 |
copy-and-past-able. Dvipdfmx supports auto-creation of ToUnicode CMaps. |
| 457 |
|
| 458 |
It will not work properly for multiply encoded glyphs due to fundamental |
| 459 |
limitations of Unicode conversion mechanism with ToUnicode CMaps. |
| 460 |
|
| 461 |
\subsection{Other Extensions} |
| 462 |
|
| 463 |
\dvipdfmx\ can generate encrypted PDF documents to protect its contents from |
| 464 |
unauthorized access. It is limited to password-based authentication, and |
| 465 |
public-key based authentication is not supported. The 256-bit AES encryption is |
| 466 |
also supported for PDF version 1.7 and 2.0 setting although it may not be supported |
| 467 |
by PDF viewers. |
| 468 |
|
| 469 |
There are various other improvements over \dvipdfm. The most notable one is |
| 470 |
more improved PDF input and output support: The cross-reference stream and |
| 471 |
object stream introduced in \lnum{PDF-1.5} are also supported. |
| 472 |
|
| 473 |
\chapter{Auxiliary Files}\label{SEC:auxfiles} |
| 474 |
|
| 475 |
This chapter describes various auxiliary files required for supporting legacy encodings |
| 476 |
and legacy font format such as PostScript Type1 font. |
| 477 |
\XeTeX\ users may skip this chapter. |
| 478 |
|
| 479 |
\dvipdfmx\ can handle various input encodings, from 7-bit encodings to variable-width |
| 480 |
multi-byte encodings. It also has some sort of Unicode support. |
| 481 |
Several auxiliary files which are not common to \TeX\ users are needed to utilize those |
| 482 |
features. This chapter shortly describes about those auxiliary files. |
| 483 |
|
| 484 |
\section{PostScript CMap Resources} |
| 485 |
|
| 486 |
\keyword{PostScript CMap Resources}\footnote{See, |
| 487 |
``\href{https://www.adobe.com/content/dam/Adobe/en/devnet/font/pdfs/5014.CIDFont\_Spec.pdf}% |
| 488 |
{Adobe CMap and CIDFont Files Specification}''} |
| 489 |
are required for supporting legacy encodings such as Shift-JIS, EUC-JP, \lnum{Big5}, |
| 490 |
and other East Asian encodings. \dvipdfmx\ internally identifies glyphs with |
| 491 |
identifiers (CIDs\footnote{PostScript terminology ``Character IDentifier''.}) |
| 492 |
represented as an integer ranging from 0 to 65535 in the CID-based glyph access. |
| 493 |
PostScript CMap Resources describes the mapping between sequences of input |
| 494 |
character codes and CIDs. \dvipdfmx\ has an extensible support for multi-byte |
| 495 |
encodings via PostScript CMap Resources. |
| 496 |
|
| 497 |
CMap files for standard East Asian encodings, for use with Adobe's character |
| 498 |
collections, are included in the \package{adobemapping} package. |
| 499 |
The latest version of those CMap files maintained by Adobe can be found at |
| 500 |
Adobe's GitHub Project page:\medskip |
| 501 |
|
| 502 |
\url{https://github.com/adobe-type-tools/cmap-resources} |
| 503 |
\medskip |
| 504 |
|
| 505 |
Those files are mandatory for supporting p\TeX. up\TeX\ users may also |
| 506 |
want to install them but they are not required. |
| 507 |
|
| 508 |
\subsection{Subfont Definition Files} |
| 509 |
|
| 510 |
CJK fonts usually contain several thousands of glyphs. For using such fonts |
| 511 |
with (original) \TeX, which can only handle 8-bit encodings, it is necessary to |
| 512 |
split a font into several \keyword{subfonts}. The Subfont Definition File (SFD) |
| 513 |
specify the way how those fonts are split into subfonts. \dvipdfmx\ uses SFD |
| 514 |
files to convert a set of subfonts back to a single font. |
| 515 |
|
| 516 |
SFD files are not required for use with \TeX\ variants which can handle |
| 517 |
multi-byte character encodings and large character sets such as p\TeX, |
| 518 |
up\TeX,\XeTeX, and Omega. |
| 519 |
H\LaTeX\ and CJK-\LaTeX\ users are required to have those files to be |
| 520 |
installed. SFD files are available as a part of the \package{ttfutils} package |
| 521 |
for \TeX\ Live users. |
| 522 |
|
| 523 |
\subsection{The Adobe Glyph List and ToUnicode Mappings} |
| 524 |
|
| 525 |
The Adobe Glyph List\footnote{See, |
| 526 |
``\href{https://github.com/adobe-type-tools/agl-specification}{Adobe Glyph List Specification}''} |
| 527 |
(AGL) describes correspondence between PostScript glyph names (e.g., \code{AE}, |
| 528 |
\code{Aacute},...) and Unicode character sequences representing them. |
| 529 |
Some features described in the section ``Unicode Support'' requires AGL file. |
| 530 |
|
| 531 |
\dvipdfmx\ looks for the file \code{glyphlist.txt} when conversion from |
| 532 |
PostScript glyph names to Unicode sequences is necessary. |
| 533 |
This conversion is done in various situations; when creating ToUnicode CMaps |
| 534 |
for 8-bit encoding fonts, finding glyph descriptions from TrueType and OpenType |
| 535 |
fonts when the font itself does not provide a mapping from PostScript glyph |
| 536 |
names to glyph indices (version 2.0 ``post'' table), and when the encoding |
| 537 |
\code{unicode} is specified for Type1 font. |
| 538 |
|
| 539 |
The AGL file is included in the \package{glyphlist} package. The latest version |
| 540 |
can be found at Adobe's GitHub site:\medskip |
| 541 |
|
| 542 |
\url{https://github.com/adobe-type-tools/agl-aglfn} |
| 543 |
\medskip |
| 544 |
|
| 545 |
ToUnicode Mappings are similar to AGL but they describe correspondence |
| 546 |
between CID numbers (instead of glyph names) and Unicode values. |
| 547 |
The content of those files are the same as CMap Resources. |
| 548 |
They are required when using TrueType fonts emulated as a CID-keyed font. |
| 549 |
They should be found in the same directory as ordinary CMap files. |
| 550 |
|
| 551 |
ToUnicode Mapping files are included in the \package{adobemapping} package. |
| 552 |
Those files are not required for \XeTeX\ users. |
| 553 |
|
| 554 |
\chapter{Graphics}\label{SEC:graphics} |
| 555 |
|
| 556 |
\section{Image Inclusion} |
| 557 |
|
| 558 |
The basics of incorporating images into output PDF is the same as in \dvipdfm. |
| 559 |
To do this, \LaTeX\ users can simply use the \package{graphicx} package. |
| 560 |
(possibly with the driver option \code{dvipdfmx}) |
| 561 |
This section is \emph{not} for providing a how-to guide to include images but |
| 562 |
just for supported graphics and image formats along with supported features. |
| 563 |
|
| 564 |
Graphics support was mostly rewritten in \dvipdfmx. |
| 565 |
Support for BMP and JPEG\lnum{2000} was added. An effort to preserve more |
| 566 |
information originally found in included images, e.g., embedded ICC Profiles |
| 567 |
and XMP Metadata, was made. |
| 568 |
|
| 569 |
However, \dvipdfmx\ does not support various features common to graphics |
| 570 |
manipulation programs such as resampling, color conversion, and selection of |
| 571 |
compression filters. Thus, it is recommended to use other programs specialized |
| 572 |
in image manipulation for preparation of images. |
| 573 |
|
| 574 |
\subsection{Supported Graphics File Formats} |
| 575 |
|
| 576 |
Supported formats are, PNG, JPEG, \lnum{JPEG2000}, BMP, PDF, and \MP\ generated |
| 577 |
EPS. All other format images, such as SVG and PostScript, must be converted to |
| 578 |
PDF before inclusion. The \option{-D} option, as in \dvipdfm, can be used for |
| 579 |
filtering images. |
| 580 |
|
| 581 |
\subsubsection{Notes on PNG Support} |
| 582 |
|
| 583 |
PNG is supported as in \dvipdfm\ with many improvements. |
| 584 |
|
| 585 |
PNG support includes most of important features of PNG format such as color |
| 586 |
palette, transparency, 16-bit bit-depth color, embedded ICC Profiles, |
| 587 |
calibrated color, and embedded XMP Metadata. |
| 588 |
|
| 589 |
In including PNG images, \dvipdfmx\ first decompresses image data and then |
| 590 |
compresses (if requested) it again. |
| 591 |
For better compression ratio, a preprocessing filter (Predictor filter) might |
| 592 |
be applied before compression. |
| 593 |
\dvipdfmx\ supports the TIFF Predictor 2 and the PNG optimum filter. |
| 594 |
However, there is yet no way to specify which predictor function is to be used |
| 595 |
and currently PNG optimum filter is always employed. |
| 596 |
|
| 597 |
Predictor filter is a preprocessing filter to image data for improving compression. |
| 598 |
Using a predictor filter usually gives better compression |
| 599 |
but in many cases compression speed becomes significantly slower. |
| 600 |
Try \option{-C 0x20} command line option to disable predictor filters and to |
| 601 |
check if slowness is due to filtering. |
| 602 |
|
| 603 |
For the PNG optimum filter, a heuristic approach, ``minimum sum of absolute |
| 604 |
differences'', is employed for finding the most optimal filter to be used. |
| 605 |
See, discussion in the PNG Specification ''Filter selection'':\medskip |
| 606 |
|
| 607 |
\url{https://www.w3.org/TR/2003/REC-PNG-20031110/\#12Filter-selection} |
| 608 |
\medskip |
| 609 |
|
| 610 |
As built-in support for the sRGB color space is absent in PDF, |
| 611 |
the sRGB color can only be represented precisely by means of the sRGB ICC Profile. |
| 612 |
However, for sRGB color PNG images, \dvipdfmx\ uses an approximate calibrated |
| 613 |
RGB color space instead. |
| 614 |
For approximating the sRGB color, the gamma and CIE \lnum{1931} chromaticity values |
| 615 |
mentioned in the PNG Specification is used. |
| 616 |
See, the following page for more information:\medskip |
| 617 |
|
| 618 |
\url{https://www.w3.org/TR/2003/REC-PNG-20031110/\#11sRGB} |
| 619 |
\medskip |
| 620 |
|
| 621 |
\dvipdfmx\ also supports calibrated color with the \code{gAMA} and the \code{cHRM} chunk. |
| 622 |
These chunks carry information on more accurate color representation. |
| 623 |
Some software programs, however, write only \code{cHRM} but do not record the gamma value |
| 624 |
although the PNG specification recommends to do so. Gamma value 2.2 is assumed if only |
| 625 |
\code{cHRM} is present but \code{gAMA} is not. |
| 626 |
|
| 627 |
Some PNG features are unavailable depending on output PDF version setting. Please refer |
| 628 |
Table~\ref{TABLE:PNGfeat} for more details. |
| 629 |
|
| 630 |
\begin{table} |
| 631 |
\centering |
| 632 |
\begin{tabular}{lp{8cm}}\hline |
| 633 |
Feature & PDF Version Required \\ \hline\hline |
| 634 |
16-bit Color Depth & Version 1.5 \\ |
| 635 |
Transparency & Full support for alpha channel requires PDF version 1.4. |
| 636 |
Color key masking (a specific color is treated as fully transparent) |
| 637 |
requires 1.3.\\ |
| 638 |
XMP Metadata & Version 1.4 \\ |
| 639 |
ICC Profile & Version 1.3 \\ |
| 640 |
\hline |
| 641 |
\end{tabular} |
| 642 |
\caption{PNG features and corresponding PDF versions required.}% |
| 643 |
\label{TABLE:PNGfeat} |
| 644 |
\end{table} |
| 645 |
|
| 646 |
\subsubsection{JPEG and \lnum{JPEG2000}} |
| 647 |
|
| 648 |
JPEG format is supported as in \dvipdfm. In addition to this, \lnum{JPEG2000} |
| 649 |
is also supported. |
| 650 |
|
| 651 |
JPEG and \lnum{JPEG2000} image inclusion is basically done as ''pass-through'', |
| 652 |
that is, image data is not decompressed before inclusion. So, although these |
| 653 |
formats are basically lossy, there should be no quality loss when including |
| 654 |
images. |
| 655 |
|
| 656 |
JPEG is relatively well supported. \dvipdfmx\ supports embedded ICC Profiles |
| 657 |
and CMYK color. Embedded XMP metadata is also preserved in the output PDF. |
| 658 |
JFIF or Exif data might be used to determine image's physical size. |
| 659 |
|
| 660 |
As the PDF specification does not require information irrelevant to |
| 661 |
displaying images to be embedded, \dvipdfmx\ does not embed whole data. |
| 662 |
Especially, not all application specific data is retained. Application |
| 663 |
specific data such as JFIF, Exif, and \code{APP14} Adobe marker are |
| 664 |
preserved. |
| 665 |
Please note that XMP and Exif data which may contain location information |
| 666 |
where the photo was taken is always preserved in the output PDF file. |
| 667 |
|
| 668 |
\lnum{JPEG2000} is also supported. It is restricted to JP2 and JPX baseline |
| 669 |
subset as required by the PDF specification. It is not well supported and still in |
| 670 |
an experimental stage. J2C format and transparency are not supported. |
| 671 |
|
| 672 |
\subsubsection{PDF Support} |
| 673 |
|
| 674 |
PDF inclusion is supported as in \dvipdfm, with various important enhancement |
| 675 |
over \dvipdfm\ for more robust inclusion. \dvipdfmx\ can handle cross-reference |
| 676 |
streams and object streams introduced in \lnum{PDF-1.5}. |
| 677 |
\dvipdfmx\ also supports inclusion of PDF pages other than the first page. |
| 678 |
However, tagged PDF may cause problems and annotations are not kept. |
| 679 |
|
| 680 |
As there is no clear way to determine the natural extent of a graphics contents |
| 681 |
to be clipped, \dvipdfmx\ first try to find if there is any \emph{crop box} |
| 682 |
explicitly specified, to determine image size. If not, then it tries to refer |
| 683 |
other boundary boxes such as the \emph{art box} which can be used for defining |
| 684 |
the extent of the page's meaningful content as suggested by the PDF Reference.\cite{ADOBE} |
| 685 |
If there is no such page boundaries explicitly specified, useful for estimating |
| 686 |
the intended size of the graphics contents, the \emph{media box}, which is the |
| 687 |
boundaries of the physical medium on which the page is to be printed, is used as |
| 688 |
the last resort. |
| 689 |
|
| 690 |
The \code{pdf:image} special supports additional keys, ``\code{page}'' and |
| 691 |
``\code{pagebox}''. The \code{page} key takes an integer value representing |
| 692 |
the page number of the PDF page to be included, and the \code{pagebox} takes one |
| 693 |
of the keywords \code{mediabox}, \code{cropbox}, \code{artbox}, \code{bleedbox}, |
| 694 |
or \code{trimbox} for selecting page's boundary box to be used. For example, |
| 695 |
\begin{lstlisting} |
| 696 |
\special{pdf:image pagebox artbox page 3 (foo.pdf)} |
| 697 |
\end{lstlisting} |
| 698 |
includes 3rd page of `foo.pdf' with the boundary box set to the art box. |
| 699 |
|
| 700 |
\subsubsection{Other Image Formats} |
| 701 |
|
| 702 |
For \MP\ generated Encapsulated PostScript (EPS) files, multi-byte encoding |
| 703 |
support is added. |
| 704 |
\dvipdfmx\ also supports ``\MP\ mode''. When \dvipdfmx\ is invoked with |
| 705 |
\option{-M} option, it enters in \MP\ mode and processes a \MP\ |
| 706 |
generated EPS file as an input.% |
| 707 |
\footnote{\code{prologue} should be set to \code{2}.} |
| 708 |
|
| 709 |
BMP support is also added. It is limited to uncompressed or RLE-compressed |
| 710 |
raster images. Extensions are not (won't be) supported. |
| 711 |
|
| 712 |
For image formats not natively supported, the \code{-D} option can be |
| 713 |
used to convert images to PDF format before inclusion, as in \dvipdfm. |
| 714 |
In \dvipdfmx, the letter \code{v} in the \code{-D} option argument is expanded |
| 715 |
to the output PDF version. |
| 716 |
|
| 717 |
\subsection{Image Cache} |
| 718 |
|
| 719 |
Caching of images generated via filtering command specified with \option{-D} |
| 720 |
option is supported. It solves the problems that image inclusion becomes very |
| 721 |
slow when external filtering program such as GhostScript is invoked each time |
| 722 |
images are included. |
| 723 |
|
| 724 |
Use \option{-I} option to enable this feature: |
| 725 |
\begin{lstlisting} |
| 726 |
-I 24 |
| 727 |
\end{lstlisting} |
| 728 |
where the integer represents the life of cache files, 24 hours in this |
| 729 |
example. Zero and negative values have a special meaning. Value $0$ for |
| 730 |
``erase old cached images while leaving newly created one'', $-1$ for |
| 731 |
``erase all cached images'', and $-2$ for ``ignore image cache''. |
| 732 |
The default is $-2$. |
| 733 |
|
| 734 |
\subsection{Custom Stream Dictionary Entries} |
| 735 |
|
| 736 |
For all supported image formats, you can insert custom entries into the image's |
| 737 |
XObject stream dictionary by enclosing the entries inside of a pair of doubled |
| 738 |
angle brackets immediately after the filename: |
| 739 |
\begin{lstlisting} |
| 740 |
\special{pdf:image (foo.pdf) << /TestKey (TestValue) >>} |
| 741 |
\end{lstlisting} |
| 742 |
|
| 743 |
\section{Graphics Drawing} |
| 744 |
|
| 745 |
\dvipdfmx\ does not offer a high level interface to draw graphics objects. |
| 746 |
A possible way to draw graphics is to write raw PDF graphics drawing codes and |
| 747 |
then to insert them into the output via \code{special} commands. |
| 748 |
|
| 749 |
To show an example, the following code: |
| 750 |
\begin{lstlisting} |
| 751 |
\special{pdf:content |
| 752 |
1 0 0 1 0 0 cm |
| 753 |
0 100 m |
| 754 |
80 100 120 80 120 0 c |
| 755 |
S |
| 756 |
} |
| 757 |
\end{lstlisting} |
| 758 |
draws a Bézier curve, |
| 759 |
\begin{center} |
| 760 |
\specialbox{120bp}{100bp}{pdf:content 1 0 0 1 0 0 cm 0 100 m 80 100 120 80 120 0 c S} |
| 761 |
\end{center} |
| 762 |
The \code{pdf:content} special is used here which is useful for inserting an |
| 763 |
isolated graphics object. |
| 764 |
|
| 765 |
The above example illustrates a typical example of PDF graphics drawing. |
| 766 |
It consists of three parts; setting graphics state, constructing a path, and painting |
| 767 |
a path. A Graphic object are specified as a sequence of operators and their operands |
| 768 |
using \emph{postfix notation}. \keyword{Graphics state operators} comes first, |
| 769 |
\code{cm} in this example sets the current transformation matrix (CTM). Then, |
| 770 |
\keyword{path construction} operators follow; move to position $(0, 100)$, |
| 771 |
append a Bézier curve from current point to $(120, 0)$ with control points |
| 772 |
$(80, 100)$ and $(120, 80)$. Finally, a \keyword{path painting} operator |
| 773 |
comes to draw the constructed path. |
| 774 |
In this example the stroking operator \code{S} |
| 775 |
is used. |
| 776 |
|
| 777 |
\subsection{The \code{pdf:content} Special} |
| 778 |
|
| 779 |
The \code{pdf:content} special can be used for drawing an \emph{isolated} |
| 780 |
graphics object. It sets the origin of graphics drawing operators supplied to |
| 781 |
this command to the position where it is inserted. |
| 782 |
The whole content is enclosed by a pair of graphics state save-restore |
| 783 |
operators. So for example, a color change made within a \code{pdf:content} |
| 784 |
command takes an effect only within the content of this special. |
| 785 |
|
| 786 |
\subsection{Guide to PDF Graphics Operators} |
| 787 |
|
| 788 |
PDF employs essentially the same imaging model as PostScript. |
| 789 |
So, it is easy to learn about PDF graphics drawing for people who are |
| 790 |
well accustomed to PostScript. This section is intended to be a short guide |
| 791 |
for PDF graphics operators. |
| 792 |
|
| 793 |
\subsubsection{Graphics State Operators} |
| 794 |
|
| 795 |
The \code{cm} operator modifies CTM by concatenating the specified matrix. |
| 796 |
Operands given to this operators are six numbers each representing |
| 797 |
transformation matrix elements: |
| 798 |
translation represented as $[1, 0, 0, 1, t_x, t_y]$, |
| 799 |
scaling $[s_x, 0, 0, s_y, 0, 0]$, |
| 800 |
rotation $[\cos\theta, \sin\theta, -\sin\theta, \cos\theta, 0, 0]$. |
| 801 |
|
| 802 |
To uniformly scale the object, just use |
| 803 |
\begin{lstlisting} |
| 804 |
2.0 0 0 2.0 0 0 cm |
| 805 |
\end{lstlisting} |
| 806 |
|
| 807 |
The \code{w} operator sets the line width, e.g., `\code{2 w}' sets the line |
| 808 |
width to 2. Here is an example of drawing a rotated rectangle: |
| 809 |
\begin{lstlisting} |
| 810 |
0.866 0.5 -0.5 0.866 30 2 cm 5 w 0 0 100 50 re S |
| 811 |
\end{lstlisting} |
| 812 |
\begin{center} |
| 813 |
\specialbox{120bp}{96bp}{pdf:content 0.866 0.5 -0.5 0.866 30 2 cm 5 w 0 0 100 50 re S}% |
| 814 |
\end{center} |
| 815 |
|
| 816 |
Transformations can be sequentially applied; for the above example, |
| 817 |
\begin{lstlisting} |
| 818 |
1 0 0 1 30 2 cm 0.866 0.5 -0.5 0.866 0 0 cm |
| 819 |
5 w 0 0 100 50 re S |
| 820 |
\end{lstlisting} |
| 821 |
gives the same result. |
| 822 |
|
| 823 |
To specify colors, use \code{RG}, \code{rg}, \code{K}, and \code{k} operators, |
| 824 |
for RGB or CMYK color for stroking (upper-case) and nonstroking (lower-case). |
| 825 |
\begin{lstlisting} |
| 826 |
0.866 0.5 -0.5 0.866 30 2 cm 5 w |
| 827 |
1 0.4 0 0 K 1 0 0 0 k |
| 828 |
0 0 100 50 re B |
| 829 |
\end{lstlisting} |
| 830 |
where the \code{B} operator fill and then stroke the path. |
| 831 |
\begin{center} |
| 832 |
\specialbox{120bp}{96bp}{pdf:content 0.866 0.5 -0.5 0.866 30 2 cm 5 w |
| 833 |
1 0.4 0 0 K 1 0 0 0 k 0 0 100 50 re B} |
| 834 |
\end{center} |
| 835 |
|
| 836 |
A dash pattern can be specified with the \code{d} operator. |
| 837 |
Operands for this operator are the \keyword{dash array} and |
| 838 |
the \keyword{dash phase}. |
| 839 |
For example, to specify a dash pattern with 6-on 4-off starting with phase 0: |
| 840 |
\begin{lstlisting} |
| 841 |
[6 4] 0 d 2 w 0 0 m 320 0 l S |
| 842 |
\end{lstlisting} |
| 843 |
draws the following dashed line: |
| 844 |
\begin{center} |
| 845 |
\specialbox{320bp}{30bp}{pdf:content |
| 846 |
1 0 0 1 0 20 cm [6 4] 0 d 2 w 0 0 m 320 0 l S} |
| 847 |
\end{center} |
| 848 |
|
| 849 |
Other important operators are \code{q} and \code{Q}, which saves and restores |
| 850 |
the graphics state. |
| 851 |
\begin{lstlisting} |
| 852 |
1 0 0 1 30 2 cm |
| 853 |
q |
| 854 |
0.866 0.5 -0.5 0.866 0 0 cm |
| 855 |
[6 4] 0 d 2 w 0 0 100 50 re S |
| 856 |
Q |
| 857 |
-30 0 m 90 0 l S |
| 858 |
0 -2 m 0 96 l S |
| 859 |
\end{lstlisting} |
| 860 |
In the above example, \code{d}, \code{w}, and rotation only take effect within |
| 861 |
the \code{q}-\code{Q} block. The portion drawing two straight lines is unaffected |
| 862 |
by these graphics state change. |
| 863 |
\begin{center} |
| 864 |
\specialbox{120bp}{96bp}{pdf:content |
| 865 |
1 0 0 1 30 2 cm |
| 866 |
q |
| 867 |
0.866 0.5 -0.5 0.866 0 0 cm |
| 868 |
[6 4] 0 d 2 w 0 0 100 50 re S |
| 869 |
Q |
| 870 |
-30 0 m 90 0 l S |
| 871 |
0 -2 m 0 96 l S |
| 872 |
} |
| 873 |
\end{center} |
| 874 |
|
| 875 |
For a (incomplete) list of graphics state operators, see |
| 876 |
Talbe~\ref{TAB:operatorsGS}. |
| 877 |
|
| 878 |
\begin{table} |
| 879 |
\centering |
| 880 |
\begin{tabular}{llp{7.6cm}}\hline |
| 881 |
Operands & Operator & Description\\ \hline\hline |
| 882 |
--- & \code{q} & Save the current graphics state.\\ |
| 883 |
--- & \code{Q} & Restore the previously saved graphics state.\\ |
| 884 |
$a$ $b$ $c$ $d$ $e$ $f$ & \code{cm} & Modify the current transformation matrix |
| 885 |
by concatenating the specified matrix.\\ |
| 886 |
\textit{width} & \code{w} & Set the line width.\\ |
| 887 |
\textit{array} \textit{phase} & \code{d} & Set the line dash pattern.\\ |
| 888 |
$r$ $g$ $b$ & \code{RG} & Set the stroking color space to RGB and |
| 889 |
set the stroking color as specified.\\ |
| 890 |
$r$ $g$ $b$ & \code{rg} & Set the nonstroking color space to RGB and |
| 891 |
set the nonstroking color as specified.\\ |
| 892 |
$c$ $m$ $y$ $k$ & \code{K} & Set the stroking color space to CMYK and |
| 893 |
set the stroking color as specified.\\ |
| 894 |
$c$ $m$ $y$ $k$ & \code{k} & Set the nonstroking color space to CMYK and |
| 895 |
set the nonstroking color as specified.\\ |
| 896 |
\hline |
| 897 |
\end{tabular} |
| 898 |
\caption{A few examples of graphics state operators and color operators.}% |
| 899 |
\label{TAB:operatorsGS} |
| 900 |
\end{table} |
| 901 |
|
| 902 |
\subsubsection{Path Construction Operators} |
| 903 |
|
| 904 |
A path construction normally starts with a \code{m} operator which moves the |
| 905 |
current point to the specified position and then sequences of other path |
| 906 |
construction operators follow. The path currently under construction is |
| 907 |
called the \keyword{current path}. A sequence of path construction operators |
| 908 |
appends segments of path to the current path and then move the |
| 909 |
\keyword{current point} to the end point of appended path. |
| 910 |
A typical sequence of path construction looks like, |
| 911 |
\begin{lstlisting} |
| 912 |
100 50 m |
| 913 |
100 78 78 100 50 100 c |
| 914 |
22 100 0 78 0 50 c |
| 915 |
0 22 22 0 50 0 c |
| 916 |
78 0 100 22 100 50 c |
| 917 |
S |
| 918 |
\end{lstlisting} |
| 919 |
\begin{center} |
| 920 |
\specialbox{120bp}{80bp}{pdf:content |
| 921 |
100 50 m |
| 922 |
100 78 78 100 50 100 c |
| 923 |
22 100 0 78 0 50 c |
| 924 |
0 22 22 0 50 0 c |
| 925 |
78 0 100 22 100 50 c |
| 926 |
S} |
| 927 |
\end{center} |
| 928 |
This example is an approximated circle drawn by four Bézier curves. |
| 929 |
|
| 930 |
Table~\ref{TAB:operators} shows a list of path construction operators. |
| 931 |
Those who are accustomed to the PostScript language should note that in PDF |
| 932 |
the current path is not a part of the graphics state, |
| 933 |
and hence is \emph{not} saved and restored along with the other graphics state |
| 934 |
parameters. |
| 935 |
|
| 936 |
\begin{table} |
| 937 |
\centering |
| 938 |
\begin{tabular}{llp{6.9cm}}\hline |
| 939 |
Operands & Operator & Description \\ \hline\hline |
| 940 |
$x$ $y$ & \code{m} & Begin a new path by moving the current point specified by given operands.\\ |
| 941 |
$x$ $y$ & \code{l} & Append a line segment from the current point to the point specified.\\ |
| 942 |
$x_1$ $y_1$ $x_2$ $y_2$ $x_3$ $y_3$ & \code{c} & Append a Bézier curve to the current path. |
| 943 |
Two Control points and the end point given as operands.\\ |
| 944 |
$x_2$ $y_2$ $x_3$ $y_3$ & \code{v} & Append a Bézier curve to the current path. Using the current |
| 945 |
point and first two operand as the Bézier control points.\\ |
| 946 |
$x_1$ $y_1$ $x_3$ $y_3$ & \code{y} & Append a Bézier curve to the current path. The second |
| 947 |
control point coincides with the end point.\\ |
| 948 |
--- & \code{h} & Close the current path by appending a straight line segment from the current point |
| 949 |
to the starting point of the path.\\ |
| 950 |
$x$ $y$ \textit{width} \textit{height} & \code{re} & Append a rectangle. First two operands for the |
| 951 |
position of lower-left corner, third and forth operand representing width and |
| 952 |
height.\\ |
| 953 |
\hline |
| 954 |
\end{tabular} |
| 955 |
\caption{List of path construction operators. All operators move the current point to the end |
| 956 |
point of appended path.}\label{TAB:operators} |
| 957 |
\end{table} |
| 958 |
|
| 959 |
\subsubsection{Path Painting Operators} |
| 960 |
|
| 961 |
There are basically four kind of path painting operators: \code{S}, \code{f}, |
| 962 |
\code{B}, and \code{n}. The first three for ``stroke'', ``fill'', and |
| 963 |
``fill then stroke'' operators respectively, and the last one \code{n} |
| 964 |
paints nothing but end the path object. For filling operators, there are |
| 965 |
two kind of operators depending on how ``insideness'' of points are determined: |
| 966 |
the \keyword{non-zero winding number rule} and the \keyword{even-odd rule}. |
| 967 |
The even-odd rule operators are \code{f*} and \code{B*}. |
| 968 |
|
| 969 |
The following example illustrates the difference: |
| 970 |
\begin{lstlisting} |
| 971 |
0 0 100 100 re 20 20 60 60 re f |
| 972 |
1 0 0 1 120 0 cm |
| 973 |
0 0 100 100 re 20 20 60 60 re f* |
| 974 |
\end{lstlisting} |
| 975 |
\begin{center} |
| 976 |
\specialbox{220bp}{100bp}{pdf:content |
| 977 |
0 0 100 100 re 20 20 60 60 re f |
| 978 |
1 0 0 1 120 0 cm |
| 979 |
0 0 100 100 re 20 20 60 60 re f*} |
| 980 |
\end{center} |
| 981 |
The ``interior'' of the ``inner'' square has a non-zero even winding number. |
| 982 |
(In this example, counter-clockwise direction is assumed for both of |
| 983 |
two \code{re} operators.) |
| 984 |
|
| 985 |
\chapter{Specials} |
| 986 |
|
| 987 |
\section{PDF Specials}\label{SEC:specials} |
| 988 |
|
| 989 |
\dvipdfmx\ recognizes various special commands originally introduced in |
| 990 |
\dvipdfm. Please refer to the ``Dvipdfm User's Manual''\cite{DVIPDFM} for detailed |
| 991 |
information on PDF specials. |
| 992 |
|
| 993 |
\subsection{Additions to PDF Specials} |
| 994 |
|
| 995 |
Several \code{special} commands are added for more flexible PDF generation: |
| 996 |
creation of arbitrary stream objects, controlling \dvipdfmx\ behavior, and some |
| 997 |
specials which might be useful for graphics drawing. |
| 998 |
|
| 999 |
\subsubsection{PDF Object Manipulation} |
| 1000 |
|
| 1001 |
PDF object manipulation is a key feature of PDF specials. |
| 1002 |
The \code{pdf:fstream} special is added in \dvipdfmx\ which enables creation of |
| 1003 |
PDF stream object from an existing file. The syntax of this special is, |
| 1004 |
\begin{lstlisting} |
| 1005 |
pdf:fstream @identifier (filename) <<dictionary>> |
| 1006 |
\end{lstlisting} |
| 1007 |
where identifier and filename (specified as a PDF string object) are |
| 1008 |
mandatory and a dictionary object, following the filename, which is to be added |
| 1009 |
to the stream dictionary is optional. |
| 1010 |
|
| 1011 |
For example, to incorporate XMP Metadata from a file \code{test.xmp}, |
| 1012 |
\begin{lstlisting} |
| 1013 |
\special{pdf:fstream @xmp (test.xmp) << |
| 1014 |
/Type /Metadata |
| 1015 |
/Subtype /XML |
| 1016 |
>>} |
| 1017 |
\special{pdf:put @catalog << /Metadata @xmp >>} |
| 1018 |
\end{lstlisting} |
| 1019 |
|
| 1020 |
Similarly, \code{pdf:stream} special can be used to create a PDF stream |
| 1021 |
object from a PDF string instead of a file. |
| 1022 |
\begin{lstlisting} |
| 1023 |
pdf:stream @identifier (stream contents) <<dictionary>> |
| 1024 |
\end{lstlisting} |
| 1025 |
|
| 1026 |
This special might be useful for creating a simple image inline. |
| 1027 |
\begin{lstlisting} |
| 1028 |
\special{pdf:stream @myim01 |
| 1029 |
<5500AAC05500AAC05500AAC05500AAC05500> |
| 1030 |
<< |
| 1031 |
/Type /XObject |
| 1032 |
/Subtype /Image |
| 1033 |
/BitsPerComponent 1 |
| 1034 |
/ColorSpace /DeviceGray |
| 1035 |
/Width 9 |
| 1036 |
/Height 9 |
| 1037 |
>> |
| 1038 |
} |
| 1039 |
\special{pdf:put @resources << |
| 1040 |
/XObject << /MyIM01 @myim01 >> |
| 1041 |
>>} |
| 1042 |
\special{pdf:content 81 0 0 81 0 0 cm /MyIM01 Do} |
| 1043 |
\end{lstlisting} |
| 1044 |
The above example draws an image like Figure~\ref{FIG:stream}. |
| 1045 |
\begin{figure} |
| 1046 |
\centering |
| 1047 |
\makebox[81bp][l]{\raisebox{-81bp}[0bp][81bp]{% |
| 1048 |
\special{pdf:stream @myim01 <5500AAC05500AAC05500AAC05500AAC05500> |
| 1049 |
<< |
| 1050 |
/Type /XObject |
| 1051 |
/Subtype /Image |
| 1052 |
/BitsPerComponent 1 |
| 1053 |
/ColorSpace /DeviceGray |
| 1054 |
/Width 9 |
| 1055 |
/Height 9 |
| 1056 |
>>} |
| 1057 |
\special{pdf:put @resources << |
| 1058 |
/XObject << /MyIM01 @myim01 >> |
| 1059 |
>>} |
| 1060 |
\special{pdf:content 81 0 0 81 0 0 cm /MyIM01 Do} |
| 1061 |
}} |
| 1062 |
\caption{An image created by \code{pdf:stream} special.}% |
| 1063 |
\label{FIG:stream} |
| 1064 |
\end{figure} |
| 1065 |
|
| 1066 |
\subsubsection{Controlling Font Mappings} |
| 1067 |
|
| 1068 |
\code{pdf:mapline} and \code{pdf:mapfile} specials can be used to append a |
| 1069 |
fontmap entry or to load a fontmap file: |
| 1070 |
\begin{lstlisting} |
| 1071 |
pdf:mapline foo unicode bar |
| 1072 |
pdf:mapfile foo.map |
| 1073 |
\end{lstlisting} |
| 1074 |
|
| 1075 |
\subsubsection{Specifying Output PDF Version} |
| 1076 |
|
| 1077 |
\code{pdf:majorversion} and \code{pdf:minorversion} specials can be used to |
| 1078 |
specify major and minor version of output PDF. |
| 1079 |
\begin{lstlisting} |
| 1080 |
pdf:minorversion 3 |
| 1081 |
\end{lstlisting} |
| 1082 |
|
| 1083 |
Please note that this command must appear on the first page, |
| 1084 |
otherwise it will be ignored. |
| 1085 |
|
| 1086 |
\subsubsection{Custom File Identifiers} |
| 1087 |
|
| 1088 |
\newfeature{Addition in \TeX\ Live 2019} |
| 1089 |
|
| 1090 |
A custom file identifier (the \code{ID} entry in the trailer dictionary) |
| 1091 |
can be specified via the special \code{pdf:trailerid}. For example: |
| 1092 |
\begin{lstlisting} |
| 1093 |
pdf:trailerid [ |
| 1094 |
<00112233445566778899aabbccddeeff> |
| 1095 |
<00112233445566778899aabbccddeeff> |
| 1096 |
] |
| 1097 |
\end{lstlisting} |
| 1098 |
An array of two 16-byte PDF string objects (hexadecimal notion is used in the above example) |
| 1099 |
must be supplied as a file identifier. This special command must appear on the first page. |
| 1100 |
|
| 1101 |
\subsubsection{Encryption} |
| 1102 |
|
| 1103 |
To protect output PDF with encryption, use \code{pdf:encrypt} special |
| 1104 |
\begin{lstlisting} |
| 1105 |
pdf:encrypt userpw (foo) ownerpw (bar) length 128 perm 20 |
| 1106 |
\end{lstlisting} |
| 1107 |
where user-password (\code{userpw}) and owner-password (\code{ownerpw}) must be |
| 1108 |
specified as PDF string objects. (which can be empty) |
| 1109 |
Numbers specifying key-length and permission flags here are decimal numbers. |
| 1110 |
See, section ``\hyperref[SEC:encryption]{Encryption Support}'' for a brief |
| 1111 |
description of permission flags. |
| 1112 |
|
| 1113 |
\subsubsection{PDF Document Creation} |
| 1114 |
|
| 1115 |
\newfeature{Addition in \TeX\ Live 2019} |
| 1116 |
|
| 1117 |
As a convenience, the \code{pageresources} special is added, which puts given page |
| 1118 |
resources into subsequent page's \keyword{Resource Dictionary}. For example, |
| 1119 |
\begin{lstlisting} |
| 1120 |
\special{pdf:pageresources << |
| 1121 |
/ExtGState << /MyGS01 << /ca 0.5 /CA 0.5 >> >> |
| 1122 |
>>} |
| 1123 |
\end{lstlisting} |
| 1124 |
puts an ExtGState resource named \code{MyGS01} into the current page's and all |
| 1125 |
subsequent pages' resource dictionary. |
| 1126 |
|
| 1127 |
Other notable extensions are \code{code}, \code{bcontent}, and |
| 1128 |
\code{econtent}. The \code{code} special can be used to insert raw PDF graphics |
| 1129 |
instructions into the output. It is different from \dvipdfm's |
| 1130 |
\code{content} special in that it does not enclose contents with a \code{q} |
| 1131 |
and \code{Q} (save-restore of graphics state) pair. |
| 1132 |
A typical usage of this special is: |
| 1133 |
\begin{lstlisting} |
| 1134 |
\special{pdf:code q 1 Tr} |
| 1135 |
...some text goes here... |
| 1136 |
\special{pdf:code Q} |
| 1137 |
\end{lstlisting} |
| 1138 |
which changes text rendering mode to 1, as shown in Figure~\ref{FIG:trmode}. |
| 1139 |
|
| 1140 |
\begin{figure} |
| 1141 |
\centering |
| 1142 |
\mbox{\special{pdf:code q 1 w 1 Tr}% |
| 1143 |
{\fontsize{200pt}{200pt}\selectfont\textchi}% |
| 1144 |
\special{pdf:code Q}}% |
| 1145 |
\caption{A character drawn in the PDF text rendering mode 1.}% |
| 1146 |
\label{FIG:trmode} |
| 1147 |
\end{figure} |
| 1148 |
|
| 1149 |
Be careful on using this special as it is very easy to generate |
| 1150 |
broken PDF files. The \code{bcontent} and \code{econtent} pair is somewhat |
| 1151 |
fragile and might be incompatible to other groups of special commands. |
| 1152 |
It may not always be guaranteed to work as `expected'. |
| 1153 |
|
| 1154 |
\subsection{ToUnicode Special} |
| 1155 |
|
| 1156 |
PDF allows users to attach various additional information such as document information, |
| 1157 |
annotation, and navigation information (like bookmarks) to their document. |
| 1158 |
All human-readable text, \keyword{text string}, contained in such information must |
| 1159 |
be encoded either in \keyword{PDFDocEncoding} or UTF-16BE with Unicode byte order |
| 1160 |
marker. However, as many users can't prepare their document with text strings |
| 1161 |
properly encoded, there is a special kind of special command, \code{pdf:tounicode}, |
| 1162 |
which can be used to convert text strings into the appropriate Unicode form. |
| 1163 |
Note that this feature is provided just as a remedy for users incapable of encoding |
| 1164 |
text strings properly. |
| 1165 |
|
| 1166 |
For example, |
| 1167 |
\begin{lstlisting} |
| 1168 |
\special{pdf:tounicode 90ms-RKSJ-UCS2} |
| 1169 |
\end{lstlisting} |
| 1170 |
declares that \emph{some} of text strings should be re-encoded according to specified |
| 1171 |
conversion CMap \code{90ms-RKSJ-UCS2}. |
| 1172 |
|
| 1173 |
Conversion is done only for arguments to several PDF special commands such as |
| 1174 |
\code{docinfo}, \code{ann}, and \code{out} but not for that of general object creation |
| 1175 |
specials. Note that not all PDF string objects are subject to this conversion. |
| 1176 |
By default, only dictionary entries listed below are converted. |
| 1177 |
\begin{lstlisting} |
| 1178 |
Title Author Subject Keywords Creator Producer Contents Subj |
| 1179 |
TU T TM |
| 1180 |
\end{lstlisting} |
| 1181 |
|
| 1182 |
\newfeature{Addition in \TeX\ Live 2019} |
| 1183 |
|
| 1184 |
The list of dictionary entries subject to conversion can be extended by supplying |
| 1185 |
additional dictionary keys as an array object: |
| 1186 |
\begin{lstlisting} |
| 1187 |
\special{pdf:tounicode 90ms-RKSJ-UCS2 [/RC /DS]} |
| 1188 |
\end{lstlisting} |
| 1189 |
|
| 1190 |
If the name of conversion CMap contains one of the keywords RKSJ, \lnum{B5}, GBK, and KSC, |
| 1191 |
PDF string objects are treated specially when they are parsed. A two byte sequence |
| 1192 |
starting with the first byte's high bit set is treated ``as is'' so that |
| 1193 |
the \code{0x5c} byte appears in the second byte is not treated as an escape sequence. |
| 1194 |
This behavior is not compliant to the PDF specification. |
| 1195 |
|
| 1196 |
\subsection{PDF Special Examples} |
| 1197 |
|
| 1198 |
This section shows several examples of special command usage. |
| 1199 |
It is intended to be a hint for advanced users, so uninterested users can safely skip |
| 1200 |
this section. In many cases, using \dvipdfmx\ PDF specials requires knowledge on PDF. |
| 1201 |
Please refer to Adobe's ``PDF Reference''\cite{ADOBE}. |
| 1202 |
|
| 1203 |
\subsubsection{Annotations} |
| 1204 |
|
| 1205 |
In this section, some useful special commands for creating \keyword{annotations} |
| 1206 |
are explained. Note that viewer support is required for annotations to be |
| 1207 |
displayed correctly. |
| 1208 |
|
| 1209 |
First start with a very simple \keyword{Text Annotation} for attaching a comment. |
| 1210 |
This feature is supported by many PDF viewer applications. |
| 1211 |
\marginnote{\special{pdf:ann width 20bp height 20bp |
| 1212 |
<< |
| 1213 |
/Type /Annot |
| 1214 |
/Subtype /Text |
| 1215 |
/Name /Comment |
| 1216 |
/T (Text Annotation Example) |
| 1217 |
/Subj (An Example of Text Annotations) |
| 1218 |
/Contents (A Quick Brown Fox Jumped Over The Lazy Dog.) |
| 1219 |
>> |
| 1220 |
}} |
| 1221 |
|
| 1222 |
\begin{lstlisting} |
| 1223 |
\special{pdf:ann width 20bp height 20bp |
| 1224 |
<< |
| 1225 |
/Type /Annot |
| 1226 |
/Subtype /Text |
| 1227 |
/Name /Comment |
| 1228 |
/T (Text Annotation Example) |
| 1229 |
/Subj (An Example of Text Annotations) |
| 1230 |
/Contents (A Quick Brown Fox Jumped Over The Lazy Dog.) |
| 1231 |
>> |
| 1232 |
} |
| 1233 |
\end{lstlisting} |
| 1234 |
\code{pdf:ann} special is used to create an annotation. A small icon shall |
| 1235 |
be shown on the side margin. Here, dictionary entry \code{T} is for the tilte, |
| 1236 |
\code{Subj} for the subject of this annotation, and \code{Contents} for |
| 1237 |
the text string to be shown in the body of this annotation. |
| 1238 |
|
| 1239 |
Likewise, \keyword{Rubber Stamp Annotation}, which places a rubber stamp |
| 1240 |
like figure, |
| 1241 |
\begin{center} |
| 1242 |
\specialbox{150bp}{50bp}{pdf:ann width 150bp height 50bp |
| 1243 |
<< |
| 1244 |
/Type /Annot |
| 1245 |
/Subtype /Stamp |
| 1246 |
/Name /Approved |
| 1247 |
>> |
| 1248 |
} |
| 1249 |
\end{center} |
| 1250 |
|
| 1251 |
\begin{lstlisting} |
| 1252 |
\special{pdf:ann width 150bp height 50bp |
| 1253 |
<< |
| 1254 |
/Type /Annot |
| 1255 |
/Subtype /Stamp |
| 1256 |
/Name /Approved |
| 1257 |
>> |
| 1258 |
} |
| 1259 |
\end{lstlisting} |
| 1260 |
Other keywords such as \code{Expired}, \code{Final}, \code{Draft}, and so on, |
| 1261 |
can be used in place of \code{Approved}. |
| 1262 |
|
| 1263 |
One can create stamps of their own style. For this purpose, other specials |
| 1264 |
\code{pdf:bxobj} and \code{pdf:exobj} can be used for designing stamps. |
| 1265 |
Those specials ``capture'' all typeset material enclosed by them into a PDF |
| 1266 |
\keyword{Form XObject}, which is a reusable graphics object like included images. |
| 1267 |
|
| 1268 |
For a simple example, |
| 1269 |
\begin{lstlisting} |
| 1270 |
\special{pdf:bxobj @MyStamp |
| 1271 |
width 280pt height 0pt depth 40pt} |
| 1272 |
\addfontfeature{Scale=3,Color=FF9933}My Own Stamp% |
| 1273 |
\special{pdf:exobj} |
| 1274 |
\end{lstlisting} |
| 1275 |
It captures typeset material ``My Own Stamp'' (this example uses \code{fontspec} |
| 1276 |
package's command for changing font size and text color) into the object labeled as |
| 1277 |
\code{MyStamp} for later reuse. |
| 1278 |
Then, \code{AP} (\keyword{appearance dictionary}) entry for controlling the appearance |
| 1279 |
of annotations is used as, |
| 1280 |
\begin{lstlisting} |
| 1281 |
\special{pdf:ann width 280pt height 40pt |
| 1282 |
<< |
| 1283 |
/Type /Annot |
| 1284 |
/Subtype /Stamp |
| 1285 |
/AP << /N @MyStamp >> |
| 1286 |
>> |
| 1287 |
} |
| 1288 |
\end{lstlisting} |
| 1289 |
The image captured into the object \code{MyStamp} is used as ``Normal'' |
| 1290 |
(\code{AP} dictionary entry \code{N}) appearance. |
| 1291 |
(\code{R} for ``Rollover'' and \code{D} for ``Down'' can be used.) |
| 1292 |
|
| 1293 |
{\hbadness=10000 % intentionally underfull it seems |
| 1294 |
\parbox[t][0pt][c]{280pt}{% |
| 1295 |
\special{pdf:bxobj @MyStamp width 280pt height 0pt depth 40pt}% |
| 1296 |
\addfontfeature{Scale=3,Color=FF9933}My Own Stamp% the "Stamp" is lost |
| 1297 |
\special{pdf:exobj}% |
| 1298 |
}}% |
| 1299 |
|
| 1300 |
The result is: |
| 1301 |
\begin{center} |
| 1302 |
\specialbox{280bp}{40bp}{pdf:ann width 280pt height 40pt |
| 1303 |
<< |
| 1304 |
/Type /Annot |
| 1305 |
/Subtype /Stamp |
| 1306 |
/AP << /N @MyStamp >> |
| 1307 |
>> |
| 1308 |
} |
| 1309 |
\end{center} |
| 1310 |
|
| 1311 |
With the following code, \dvipdfmx\ reads the source file and creates a stream |
| 1312 |
object named \code{SourceFile}, and then creates file attachment annotation. |
| 1313 |
\marginnote{% |
| 1314 |
\special{pdf:fstream @SourceFile (\jobname.tex)}% |
| 1315 |
\special{pdf:ann width 10bp height 20bp |
| 1316 |
<< |
| 1317 |
/Type /Annot |
| 1318 |
/Subtype /FileAttachment |
| 1319 |
/FS << |
| 1320 |
/Type /Filespec |
| 1321 |
/F (\jobname.tex) |
| 1322 |
/EF << /F @SourceFile >> |
| 1323 |
>> |
| 1324 |
/Name /PushPin |
| 1325 |
/C [0.8 0.2 0.2] |
| 1326 |
/T (The Dvipdfmx User's Manual) |
| 1327 |
/Subj (The Dvipdmfx User's Manual) |
| 1328 |
/Contents (XeLaTeX source file of this manual.) |
| 1329 |
>> |
| 1330 |
}}% |
| 1331 |
\begin{lstlisting} |
| 1332 |
\special{pdf:fstream @SourceFile (\jobname.tex)}% |
| 1333 |
\special{pdf:ann width 10bp height 20bp |
| 1334 |
<< |
| 1335 |
/Type /Annot |
| 1336 |
/Subtype /FileAttachment |
| 1337 |
/FS << |
| 1338 |
/Type /Filespec |
| 1339 |
/F (\jobname.tex) |
| 1340 |
/EF << /F @SourceFile >> |
| 1341 |
>> |
| 1342 |
/Name /PushPin |
| 1343 |
/C [0.8 0.2 0.2] |
| 1344 |
/T (The Dvipdfmx User's Manual) |
| 1345 |
/Subj (The Dvipdfmx User's Manual) |
| 1346 |
/Contents (XeLaTeX source file of the manual.) |
| 1347 |
>> |
| 1348 |
} |
| 1349 |
\end{lstlisting} |
| 1350 |
A push-pin image must be shown on the margin if viewer supports this kind of |
| 1351 |
annotation. |
| 1352 |
PDF viewer applications are required to provide predefined icon appearances |
| 1353 |
at least for the following standard icons: \code{Graph}, \code{PushPin}, |
| 1354 |
\code{PaperClip}, and \code{Tag}. |
| 1355 |
|
| 1356 |
\subsubsection{Special Color Space} |
| 1357 |
|
| 1358 |
This section shows various examples of using \keyword{Special color spaces}. |
| 1359 |
Examples in this section have a common structure. They consist of essentially |
| 1360 |
three parts. The first part is for defining color space itself. |
| 1361 |
PDF object creation commands like \code{pdf:obj} and \code{pdf:stream} are used |
| 1362 |
for this purpose. Next is for registering color space resources in the page's |
| 1363 |
\keyword{Resource Dictionary}. It can be done via \code{pdf:put} command as, |
| 1364 |
\begin{lstlisting} |
| 1365 |
\special{pdf:put @resource << |
| 1366 |
/Category << ...key-value pairs... >> |
| 1367 |
>>} |
| 1368 |
\end{lstlisting} |
| 1369 |
where \code{@resource} is a special keyword representing current page's |
| 1370 |
Resource Dictionary and \code{Category} (to be replaced by actual category |
| 1371 |
name) is a category name such as \code{ColorSpace}. |
| 1372 |
Finally, graphics objects are placed, with or with a combination of |
| 1373 |
text and, PDF drawing operators inserted by the \code{pdf:code} or the |
| 1374 |
\code{pdf:contents} special. |
| 1375 |
|
| 1376 |
%%EXAMPLE: Separation Color Space |
| 1377 |
The first example is the \keyword{Separation} color space: |
| 1378 |
\special{pdf:stream @TintTransform1 |
| 1379 |
({0 exch dup 0.62 mul exch 0}) |
| 1380 |
<< /FunctionType 4 |
| 1381 |
/Domain [0.0 1.0] |
| 1382 |
/Range [0.0 1.0 0.0 1.0 0.0 1.0 0.0 1.0] |
| 1383 |
>> |
| 1384 |
}% |
| 1385 |
\special{pdf:stream @TintTransform2 |
| 1386 |
({dup 0.78 mul exch dup 0.05 mul exch 0.71 mul 0}) |
| 1387 |
<< /FunctionType 4 |
| 1388 |
/Domain [0.0 1.0] |
| 1389 |
/Range [0.0 1.0 0.0 1.0 0.0 1.0 0.0 1.0] |
| 1390 |
>> |
| 1391 |
}% |
| 1392 |
\special{pdf:obj @Orange [ |
| 1393 |
/Separation /Orange /DeviceCMYK @TintTransform1 |
| 1394 |
] |
| 1395 |
}% |
| 1396 |
\special{pdf:obj @Green [ |
| 1397 |
/Separation /Green /DeviceCMYK @TintTransform2 |
| 1398 |
] |
| 1399 |
}% |
| 1400 |
\begin{center} |
| 1401 |
\mbox{% |
| 1402 |
\special{pdf:put @resources << |
| 1403 |
/ColorSpace << /CS01 @Orange /CS02 @Green >> |
| 1404 |
>> |
| 1405 |
}% |
| 1406 |
\fontsize{40pt}{40pt}\selectfont |
| 1407 |
\special{pdf:code q /CS01 cs 1.0 scn}Orange\special{pdf:code Q} and |
| 1408 |
\special{pdf:code q /CS02 cs 1.0 scn}Green\special{pdf:code Q} |
| 1409 |
} |
| 1410 |
\end{center} |
| 1411 |
\begin{lstlisting} |
| 1412 |
\special{pdf:stream @TintTransform1 |
| 1413 |
({0 exch dup 0.62 mul exch 0}) |
| 1414 |
<< /FunctionType 4 |
| 1415 |
/Domain [ 0.0 1.0 ] |
| 1416 |
/Range [ 0.0 1.0 0.0 1.0 0.0 1.0 0.0 1.0 ] |
| 1417 |
>> |
| 1418 |
} |
| 1419 |
\special{pdf:stream @TintTransform2 |
| 1420 |
({dup 0.78 mul exch dup 0.05 mul exch 0.71 mul 0}) |
| 1421 |
<< /FunctionType 4 |
| 1422 |
/Domain [ 0.0 1.0 ] |
| 1423 |
/Range [ 0.0 1.0 0.0 1.0 0.0 1.0 0.0 1.0 ] |
| 1424 |
>> |
| 1425 |
} |
| 1426 |
\special{pdf:obj @Orange [ |
| 1427 |
/Separation /Orange /DeviceCMYK @TintTransform1 |
| 1428 |
] |
| 1429 |
} |
| 1430 |
\special{pdf:obj @Green [ |
| 1431 |
/Separation /Green /DeviceCMYK @TintTransform2 |
| 1432 |
] |
| 1433 |
} |
| 1434 |
\mbox{% |
| 1435 |
\special{pdf:put @resources << |
| 1436 |
/ColorSpace << /CS01 @Orange /CS02 @Green >> |
| 1437 |
>> |
| 1438 |
}% |
| 1439 |
\special{pdf:code q /CS01 cs 1.0 scn} |
| 1440 |
Orange |
| 1441 |
\special{pdf:code Q} |
| 1442 |
and |
| 1443 |
\special{pdf:code q /CS02 cs 1.0 scn} |
| 1444 |
Green |
| 1445 |
\special{pdf:code Q} |
| 1446 |
} |
| 1447 |
\end{lstlisting} |
| 1448 |
|
| 1449 |
\code{TintTransform}'s defined here are functions for transforming |
| 1450 |
\keyword{tint} values into approximate colors in the |
| 1451 |
\keyword{alternate color space} |
| 1452 |
(\code{DeviceCMYK} in this example). PostScript calculator functions are used |
| 1453 |
for converting a single component value representing ``Orange'' or ``Green'' |
| 1454 |
into four component CMYK values to approximate those colors. The ``Orange'' |
| 1455 |
color $v$ is approximated as $(0, 0.62v, v, 0)$ in CMYK color space for |
| 1456 |
alternate display here. |
| 1457 |
|
| 1458 |
The \code{cs} operator for selecting color space and the \code{scn} operator |
| 1459 |
for color values are used in the \code{pdf:code} special. |
| 1460 |
Be sure that the \code{pdf:put} command, which puts color space resources |
| 1461 |
into the current page's Resource Dictionary, goes into the same page as |
| 1462 |
subsequent drawing commands. |
| 1463 |
|
| 1464 |
\dvipdfmx\ currently does not have an easy interface for using various color |
| 1465 |
space families such as CIE-Based color spaces (e.g., calibrated colors and |
| 1466 |
color space with an ICC profile) and Special color spaces (e.g., indexed, |
| 1467 |
separation, shading and patterns). |
| 1468 |
|
| 1469 |
%%EXAMPLE: Shading |
| 1470 |
Another example is a \keyword{shading pattern}: |
| 1471 |
\begin{lstlisting} |
| 1472 |
\special{pdf:put @resources << |
| 1473 |
/Shading << |
| 1474 |
/SH01 << |
| 1475 |
/ShadingType 2 |
| 1476 |
/ColorSpace @Orange |
| 1477 |
/Coords [0 0 320 20] |
| 1478 |
/Extend [true true] |
| 1479 |
/Function << /FunctionType 2 /Domain [0 1] /N 1.0 >> |
| 1480 |
>> |
| 1481 |
>> |
| 1482 |
>>} |
| 1483 |
\special{pdf:content 0 0 320 20 re W n /SH01 sh} |
| 1484 |
\end{lstlisting} |
| 1485 |
where the ``Orange'' separation color space defined before is used again. |
| 1486 |
This example shows an axial shading (\code{ShadingType} 2) pattern. |
| 1487 |
\begin{center} |
| 1488 |
\makebox[320pt][l]{ |
| 1489 |
\special{pdf:put @resources << |
| 1490 |
/Shading << |
| 1491 |
/SH01 << |
| 1492 |
/ShadingType 2 |
| 1493 |
/ColorSpace @Orange |
| 1494 |
/Coords [0 0 320 20] |
| 1495 |
/Extend [true true] |
| 1496 |
/Function << /FunctionType 2 /Domain [0 1] /N 1.0 >> |
| 1497 |
>> |
| 1498 |
>> |
| 1499 |
>>} |
| 1500 |
\raisebox{-20pt}[0pt][20pt]{\special{pdf:content 0 0 320 20 re W n /SH01 sh}} |
| 1501 |
} |
| 1502 |
\end{center} |
| 1503 |
|
| 1504 |
The shading pattern requires coordinate values to be mapped into color values. |
| 1505 |
Type 2 (Exponential Interpolation) \keyword{Function} is used for defining how |
| 1506 |
this mapping should occur here. |
| 1507 |
The above example, with the exponent $N=1$, is just a simple linear-gradient. |
| 1508 |
|
| 1509 |
The final examples is a \keyword{tiling pattern}. |
| 1510 |
\begin{lstlisting} |
| 1511 |
\special{pdf:stream @MyPattern |
| 1512 |
(0.16 0 0 0.16 0 0 cm 4 w |
| 1513 |
50 0 m 50 28 28 50 0 50 c S 100 50 |
| 1514 |
m 72 50 50 28 50 0 c S |
| 1515 |
50 100 m 50 72 72 50 100 50 c S |
| 1516 |
0 50 m 28 50 50 72 50 100 c S |
| 1517 |
100 50 m 100 78 78 100 50 100 c 22 100 0 78 0 50 c |
| 1518 |
0 22 22 0 50 0 c 78 0 100 22 100 50 c S |
| 1519 |
0 0 m 20 10 25 5 25 0 c f 0 0 m 10 20 5 25 0 25 c f |
| 1520 |
100 0 m 80 10 75 5 75 0 c f |
| 1521 |
100 0 m 90 20 95 25 100 25 c f |
| 1522 |
100 100 m 80 90 75 95 75 100 c f |
| 1523 |
100 100 m 90 80 95 75 100 75 c f |
| 1524 |
0 100 m 20 90 25 95 25 100 c f |
| 1525 |
0 100 m 10 80 5 75 0 75 c f |
| 1526 |
50 50 m 70 60 75 55 75 50 c 75 45 70 40 50 50 c f |
| 1527 |
50 50 m 60 70 55 75 50 75 c 45 75 40 70 50 50 c f |
| 1528 |
50 50 m 30 60 25 55 25 50 c |
| 1529 |
25 45 30 40 50 50 c f |
| 1530 |
50 50 m 60 30 55 25 50 25 c 45 25 40 30 50 50 c f) |
| 1531 |
<< |
| 1532 |
/BBox [0 0 16 16] |
| 1533 |
/PaintType 2 |
| 1534 |
/PatternType 1 |
| 1535 |
/Resources << |
| 1536 |
/ProcSet [/PDF] |
| 1537 |
>> |
| 1538 |
/TilingType 3 |
| 1539 |
/Type /Pattern |
| 1540 |
/XStep 16 |
| 1541 |
/YStep 16 |
| 1542 |
>> |
| 1543 |
} |
| 1544 |
\end{lstlisting} |
| 1545 |
|
| 1546 |
The above example defines a tiling pattern. The content stream containing |
| 1547 |
painting operators, \code{m} for ``move-to'', \code{c} for ``curve-to'', |
| 1548 |
\code{f} for ``fill'', and \code{S} for ``stroke'', defines the appearance of |
| 1549 |
the \keyword{pattern cell} for this tiling pattern. With the following code, |
| 1550 |
\begin{lstlisting} |
| 1551 |
\special{pdf:put @resources |
| 1552 |
<< |
| 1553 |
/ColorSpace << /CS01 [/Pattern /DeviceRGB] >> |
| 1554 |
/Pattern << /PT01 @MyPattern >> |
| 1555 |
>> |
| 1556 |
} |
| 1557 |
\special{pdf:content |
| 1558 |
q 0.8 0.3 0.3 RG /CS01 cs 0.8 0.3 0.3 /PT01 scn |
| 1559 |
0 0 320 100 re f |
| 1560 |
} |
| 1561 |
\end{lstlisting} |
| 1562 |
a box filled with the tiling pattern defined above is drawn. |
| 1563 |
\special{pdf:stream @MyPattern |
| 1564 |
(0.16 0 0 0.16 0 0 cm 4 w |
| 1565 |
50 0 m 50 28 28 50 0 50 c S 100 50 |
| 1566 |
m 72 50 50 28 50 0 c S |
| 1567 |
50 100 m 50 72 72 50 100 50 c S |
| 1568 |
0 50 m 28 50 50 72 50 100 c S |
| 1569 |
100 50 m 100 78 78 100 50 100 c 22 100 0 78 0 50 c |
| 1570 |
0 22 22 0 50 0 c 78 0 100 22 100 50 c S |
| 1571 |
0 0 m 20 10 25 5 25 0 c f 0 0 m 10 20 5 25 0 25 c f |
| 1572 |
100 0 m 80 10 75 5 75 0 c f |
| 1573 |
100 0 m 90 20 95 25 100 25 c f |
| 1574 |
100 100 m 80 90 75 95 75 100 c f |
| 1575 |
100 100 m 90 80 95 75 100 75 c f |
| 1576 |
0 100 m 20 90 25 95 25 100 c f |
| 1577 |
0 100 m 10 80 5 75 0 75 c f |
| 1578 |
50 50 m 70 60 75 55 75 50 c 75 45 70 40 50 50 c f |
| 1579 |
50 50 m 60 70 55 75 50 75 c 45 75 40 70 50 50 c f |
| 1580 |
50 50 m 30 60 25 55 25 50 c |
| 1581 |
25 45 30 40 50 50 c f |
| 1582 |
50 50 m 60 30 55 25 50 25 c 45 25 40 30 50 50 c f) |
| 1583 |
<< |
| 1584 |
/BBox [0 0 16 16] |
| 1585 |
/PaintType 2 |
| 1586 |
/PatternType 1 |
| 1587 |
/Resources << |
| 1588 |
/ProcSet [/PDF] |
| 1589 |
>> |
| 1590 |
/TilingType 3 |
| 1591 |
/Type /Pattern |
| 1592 |
/XStep 16 |
| 1593 |
/YStep 16 |
| 1594 |
>> |
| 1595 |
}% |
| 1596 |
\begin{center} |
| 1597 |
\raisebox{-100bp}[0bp][100bp]{\makebox[320bp][l]{\special{pdf:put @resources |
| 1598 |
<< |
| 1599 |
/ColorSpace << /CS01 [/Pattern /DeviceRGB] >> |
| 1600 |
/Pattern << /PT01 @MyPattern >> |
| 1601 |
>> |
| 1602 |
}% |
| 1603 |
\special{pdf:content |
| 1604 |
0.8 0.3 0.3 RG /CS01 cs 0.8 0.3 0.3 /PT01 scn |
| 1605 |
0 0 320 100 re f |
| 1606 |
}}}% |
| 1607 |
\end{center} |
| 1608 |
|
| 1609 |
\subsubsection{Transparency} |
| 1610 |
|
| 1611 |
%%EXAMPLE: Transparency |
| 1612 |
\XeTeX's transparency feature is currently lost in \xdvipdfmx, but the same |
| 1613 |
effect can be achieved by setting graphics state parameters with |
| 1614 |
\code{ExtGState} resources and \code{gs} operator. Here is a simple |
| 1615 |
transparency example: |
| 1616 |
\special{pdf:obj @gs01 << |
| 1617 |
/Type /ExtGState /CA 0.5 /ca 0.5 /AIS false |
| 1618 |
>>}% |
| 1619 |
\begin{figure}[ht] |
| 1620 |
\centering |
| 1621 |
\mbox{% |
| 1622 |
%\raisebox{120pt}{\parbox[t]{0.8\textwidth}{% |
| 1623 |
% \addfontfeature{Color=444444}\lipsum[1]}% |
| 1624 |
%}% |
| 1625 |
%\hspace{-0.8\textwidth}% |
| 1626 |
\special{pdf:put @resources << |
| 1627 |
/ExtGState << /GS01 @gs01 >> |
| 1628 |
>>}% |
| 1629 |
\fontsize{220pt}{220pt}\selectfont |
| 1630 |
\special{pdf:code q /GS01 gs 1.0 0.8 0.2 rg}% |
| 1631 |
α% |
| 1632 |
\special{pdf:code 0.4 0.8 0.4 rg}% |
| 1633 |
\hspace{-0.3em}% |
| 1634 |
β% |
| 1635 |
\hspace{-0.3em}\raisebox{0.5ex}{% |
| 1636 |
\special{pdf:code 0.4 0.4 0.8 rg}% |
| 1637 |
π% |
| 1638 |
}% |
| 1639 |
\special{pdf:code 0.6 0.2 0.8 rg}% |
| 1640 |
\hspace{-0.2em}% |
| 1641 |
γ% |
| 1642 |
\special{pdf:code Q}% |
| 1643 |
} |
| 1644 |
\end{figure} |
| 1645 |
\begin{lstlisting} |
| 1646 |
\special{pdf:obj @GS01 << |
| 1647 |
/Type /ExtGState /CA 0.5 /ca 0.5 /AIS false |
| 1648 |
>>}% |
| 1649 |
\mbox{% |
| 1650 |
\special{pdf:put @resources << |
| 1651 |
/ExtGState << /GS01 @GS01 >> |
| 1652 |
>>}% |
| 1653 |
\special{pdf:code q /GS01 gs 1.0 0.8 0.2 rg}% |
| 1654 |
α% |
| 1655 |
\special{pdf:code 0.4 0.8 0.4 rg}% |
| 1656 |
\hspace{-0.3em}% |
| 1657 |
β% |
| 1658 |
\hspace{-0.3em}\raisebox{0.5ex}{% |
| 1659 |
\special{pdf:code 0.4 0.4 0.8 rg}% |
| 1660 |
π% |
| 1661 |
}% |
| 1662 |
\special{pdf:code 1.0 0.2 0.4 rg}% |
| 1663 |
\hspace{-0.2em}% |
| 1664 |
γ% |
| 1665 |
\special{pdf:code Q}% |
| 1666 |
} |
| 1667 |
\end{lstlisting} |
| 1668 |
where values for \code{CA} and \code{ca} represent opacity of stroke and |
| 1669 |
fill color respectively. Again, \code{pdf:put} command must go into the same |
| 1670 |
page as subsequent graphics and text drawing operators. |
| 1671 |
|
| 1672 |
\section{Dvipdfmx Extensions} |
| 1673 |
|
| 1674 |
\newfeature{Addition in \TeX\ Live 2016} |
| 1675 |
|
| 1676 |
\noindent{}A new special \code{dvipdfmx:config} was introduced in |
| 1677 |
\TeX Live 2016 which makes it possible to invoke a command line option. |
| 1678 |
Several single letter command line options except \option{D} are supported. |
| 1679 |
For example, |
| 1680 |
\begin{lstlisting} |
| 1681 |
dvipdfmx:config C 0x10 |
| 1682 |
\end{lstlisting} |
| 1683 |
sets the \dvipdfmx's compatibility flags. See, the section |
| 1684 |
``\hyperref[SEC:compatibility]{Incompatible Changes}'' for an explanation of |
| 1685 |
compatibility flags. |
| 1686 |
|
| 1687 |
\section{PS Specials} |
| 1688 |
|
| 1689 |
PS (PostScript) specials can be used to insert a raw PostScript code for drawing |
| 1690 |
graphics objects and transforming subsequent text and graphics. |
| 1691 |
Please note that support for PostScript operators in \dvipdfmx\ is very |
| 1692 |
limited. It is just enough for interpreting PostScript figures output by \MP. |
| 1693 |
Only a basic set of operators for arithmetic and math, stack operation and manipulation, |
| 1694 |
graphics state, path construction and painting, glyph and font, are supported. |
| 1695 |
See, Table~\ref{TABLE:PS} for the list of |
| 1696 |
recognized PostScript operators. |
| 1697 |
|
| 1698 |
\begin{table} |
| 1699 |
\centering |
| 1700 |
\hbadness=10000 |
| 1701 |
\begin{tabular}{p{.25\hsize}>{\raggedright\arraybackslash}p{.6\hsize}}\hline |
| 1702 |
Classification & Operators \\ \hline\hline |
| 1703 |
Arithmetic \& Math & \code{add} \code{sub} \code{mul} \code{div} \code{neg} \code{truncate}\\ |
| 1704 |
Stack Operation & \code{clear} \code{pop} \code{exch}\\ |
| 1705 |
Graphis State & \code{gsave} \code{grestore} |
| 1706 |
\code{setlinewidth} \code{setdash} \code{setlinecap} \code{setlinejoin} \code{setmiterlimit} \code{setgray} \code{setrgbcolor} \code{setcmykcolor} \\ |
| 1707 |
Coordinate System & \code{concat} \code{scale} \code{translate} \code{rotate} \code{idtransform} \code{dtransform}\\ |
| 1708 |
Path Construction & \code{currentpoint} \code{newpath} \code{closepath} \code{moveto} \code{rmoveto} \code{lineto} \code{rlineto} \code{curveto} \code{rcurveto} \code{arc} \code{arcn} \code{clip} \code{eoclip} \\ |
| 1709 |
Painting & \code{stroke} \code{fill} \\ |
| 1710 |
Glyph \& Font & \code{show} \code{findfont} \code{scalefont} \code{setfont} \code{currentfont} \code{stringwidth}\\ |
| 1711 |
\hline |
| 1712 |
\end{tabular} |
| 1713 |
\caption{List of PostScript operators recognized by \dvipdfmx.}% |
| 1714 |
\label{TABLE:PS} |
| 1715 |
\end{table} |
| 1716 |
|
| 1717 |
It might be enough for the purpose of basic graphics drawings but as there are |
| 1718 |
no support for conditionals and controls it is not enough for complicated tasks, |
| 1719 |
especially, the PSTricks package is not supported. |
| 1720 |
|
| 1721 |
In \dvipdfmx, text handling is extended to support CJK text. |
| 1722 |
The following code draws Japanese text like shown in Figure~\ref{FIG:verttext}: |
| 1723 |
\begin{lstlisting} |
| 1724 |
\special{pdf:mapline urml UniJIS-UTF8-H ipaexm.ttf} |
| 1725 |
\special{ps: urml findfont 16 scalefont setfont |
| 1726 |
currentpoint moveto |
| 1727 |
(...some Japanese text goes here...) show |
| 1728 |
} |
| 1729 |
\end{lstlisting} |
| 1730 |
|
| 1731 |
\chapter{Fonts and Encodings} |
| 1732 |
|
| 1733 |
\section{Fonts and Encodings Support} |
| 1734 |
|
| 1735 |
In \dvipdfmx, all font formats supported by \dvipdfm\ are also supported with |
| 1736 |
many improvements: The CFF conversion for PostScript Type1 fonts\footnote{PostScript |
| 1737 |
Type1 font support is restricted to the binary format as in \dvipdfm.} is |
| 1738 |
implemented which greatly reduces the output file size. Embedded TrueType fonts are |
| 1739 |
now subsetted. The OpenType font format is also supported.\footnote{Its |
| 1740 |
implementation is based on the OpenType specification version 1.4. |
| 1741 |
Newly added features such as color fonts and variable fonts are not supported yet.} |
| 1742 |
|
| 1743 |
There are various enhancements made for supporting Unicode and legacy multi-byte |
| 1744 |
character encodings for East Asian languages. |
| 1745 |
|
| 1746 |
|
| 1747 |
\section{Font Mappings} |
| 1748 |
|
| 1749 |
The Syntax of font-mapping (fontmap) files is basically the same as in \dvipdfm. |
| 1750 |
There are few extensions available in \dvipdfmx. In addition to the 8-bit \code{enc} |
| 1751 |
file and keywords \code{builtin} and \code{none}, \dvipdfmx\ accepts a PostScript CMap |
| 1752 |
Resource name and the keyword \code{unicode} in the encoding field. |
| 1753 |
|
| 1754 |
When the keyword \code{unicode} is specified in the encoding field of fontmap |
| 1755 |
files, it is assumed that Unicode values are used in the input DVI file. |
| 1756 |
|
| 1757 |
\begin{lstlisting} |
| 1758 |
urml unicode SourceHanSerifJP-Light.otf |
| 1759 |
\end{lstlisting} |
| 1760 |
|
| 1761 |
Although the DVI format allows 3-byte and 4-byte character codes to be used, |
| 1762 |
\dvipdfmx\ only supports up to 2-byte range since there is no TFM format supporting |
| 1763 |
3-byte or 4-byte codes. |
| 1764 |
|
| 1765 |
For PostScript Type1 fonts which do not support Unicode natively, an auxiliary file, |
| 1766 |
the Adobe Glyph List, is required to make it possible to use fonts with Unicode access. |
| 1767 |
|
| 1768 |
As a general framework for supporting legacy multi-byte encodings, \dvipdfmx\ employs |
| 1769 |
PostScript CMap Resources for handling input strings encoded in various |
| 1770 |
character encodings. A CMap name can be specified in the encoding field just like |
| 1771 |
the encoding name for 8-bit encodings. For example, to specify the CMap ``UniJIS-UCS2-H'', |
| 1772 |
|
| 1773 |
\begin{lstlisting} |
| 1774 |
urml UniJIS-UCS2-H HiraMinPro-W3.otf |
| 1775 |
\end{lstlisting} |
| 1776 |
|
| 1777 |
For information on the Adobe Glyph List and PostScript CMap Resources, see, |
| 1778 |
the section \ref{SEC:auxfiles}, ``Auxiliary Files''. |
| 1779 |
|
| 1780 |
\subsection{Extended Syntax and Options} |
| 1781 |
|
| 1782 |
Few options are available in \dvipdfmx\ in addition to the original dvipdfm's |
| 1783 |
one. Please note that all features which makes \dvipdfmx\ to use |
| 1784 |
non-embedded fonts are deprecated, as by doing so it makes \dvipdfmx\ to create |
| 1785 |
PDF files which can be non-compliant to the ISO standards. |
| 1786 |
|
| 1787 |
\subsubsection{SFD Specification} |
| 1788 |
|
| 1789 |
For bundling up a font split into multiple subfonts via SFD back into |
| 1790 |
a single font, dvipdfmx supports extended syntax of the form |
| 1791 |
\begin{lstlisting} |
| 1792 |
tfm_name@SFD@ encoding filename options |
| 1793 |
\end{lstlisting} |
| 1794 |
A typical example looks like: |
| 1795 |
\begin{lstlisting} |
| 1796 |
gbsn@EUC@ GB-EUC-H gbsn00lp |
| 1797 |
\end{lstlisting} |
| 1798 |
where TFMs \code{gbsn00}, \code{gbsn01}, \code{gbsn02}... are mapped into a |
| 1799 |
single font named \code{gbsn00lp} via the rule described in the SFD file |
| 1800 |
\code{EUC}. |
| 1801 |
|
| 1802 |
\subsubsection{TrueType Collection Index} |
| 1803 |
|
| 1804 |
TrueType Collection index number can be specified with \code{:n:} |
| 1805 |
in front of the TrueType font name: |
| 1806 |
\begin{lstlisting} |
| 1807 |
min10 H :1:mincho |
| 1808 |
\end{lstlisting} |
| 1809 |
In this example, the option \code{:1:} tells \dvipdfmx\ to select first |
| 1810 |
TrueType font from the TTC font \code{mincho.ttc}. Alternatively, the |
| 1811 |
\option{-i} option can be used in the option field to specify TTC index: |
| 1812 |
\begin{lstlisting} |
| 1813 |
min10 H mincho -i 1 |
| 1814 |
\end{lstlisting} |
| 1815 |
|
| 1816 |
\subsubsection{Non-embedding Switch} |
| 1817 |
|
| 1818 |
\deprecated{Use of this option is deprecated.} |
| 1819 |
\noindent{}The character \option{!} in front of the font name can be used to |
| 1820 |
indicate that the font shall not be embedded. This feature greatly reduces the |
| 1821 |
size of the final PDF output, but the PDF file may not be viewed exactly the same |
| 1822 |
in other systems on which appropriate fonts are not installed. |
| 1823 |
\bigskip |
| 1824 |
|
| 1825 |
\noindent{}NOTE: \dvipdfmx\ always converts input encodings to CIDs and then |
| 1826 |
uses Identity CMaps\footnote{Predefined CMaps \code{Identity-H} and |
| 1827 |
\code{Identity-V} for the identity mapping.} |
| 1828 |
in the output PDF. However, \lnum{ISO~32000-1:2008} describes as |
| 1829 |
\begin{quoting} |
| 1830 |
The Identity-H and Identity-V CMaps shall not be used with a non-embedded font. |
| 1831 |
Only standardized character sets may be used. |
| 1832 |
\end{quoting} |
| 1833 |
which had never appeared in Adobe's PDF References. This makes all PDF files |
| 1834 |
generated by \dvipdfmx\ with non-embedded CID-keyed fonts non-compliant to |
| 1835 |
the ISO standards. |
| 1836 |
|
| 1837 |
\subsubsection{`Standard' CJK Fonts} |
| 1838 |
|
| 1839 |
\deprecated{This feature is deprecated.} |
| 1840 |
\noindent{}Use of this feature shall be avoided for new documents. It is |
| 1841 |
described here since it might still be useful for some situations. |
| 1842 |
|
| 1843 |
\dvipdfmx\ recognizes several `Standard' CJK fonts although there are no such |
| 1844 |
notion in PDF. In older days where there were not so many freely available CJK |
| 1845 |
fonts, it was sometimes useful to create PDF files without embedding fonts and |
| 1846 |
let PDF viewers or printers to use substitute fonts (tend to be higher quality) |
| 1847 |
installed in their systems. \dvipdfmx\ `knows' several fonts which might be |
| 1848 |
available in PostScript printers and PDF applications such as Acrobat Reader, |
| 1849 |
and uses them without actually having it. |
| 1850 |
See, Table~\ref{TABLE:StdCJKFont}, for the list of available `Standard' CJK |
| 1851 |
fonts. |
| 1852 |
|
| 1853 |
\begin{table} |
| 1854 |
\centering |
| 1855 |
\begin{tabular}{lll}\hline |
| 1856 |
Character Collection & Font Family & Description \\ \hline\hline |
| 1857 |
Adobe-Japan1 & Ryumin-Light & PS printers \\ |
| 1858 |
& GothicBBB-Medium & \\ |
| 1859 |
Adobe-CNS1 & MHei-Medium-Acro & Acrobat Reader 4 \\ |
| 1860 |
& MSung-Light-Acro & \\ |
| 1861 |
Adobe-GB1 & STSong-Light-Acro & \\ |
| 1862 |
& STHeiti-Regular-Acro & \\ |
| 1863 |
Adobe-Japan1 & HeiseiMin-W3-Acro & \\ |
| 1864 |
& HeiseiKakuGO-W5-Acro & \\ |
| 1865 |
Adobe-Korea1 & HYGoThic-Medium-Acro & \\ |
| 1866 |
& HYSMyeongJo-Medium-Acro & \\ |
| 1867 |
Adobe-CNS1 & MSungStd-Light-Acro & Acrobat Reader 5 \\ |
| 1868 |
Adobe-GB1 & STSongStd-Light-Acro & \\ |
| 1869 |
Adobe-Korea1 & HYSMyeongJoStd-Medium-Acro \\ |
| 1870 |
Adobe-CNS1 & AdobeMingStd-Light-Acro & Adobe Reader 6 \\ |
| 1871 |
Adobe-GB1 & AdobeSongStd-Light-Acro & \\ |
| 1872 |
Adobe-Japan1 & KozMinPro-Regular-Acro & \\ |
| 1873 |
& KozGoPro-Medium-Acro & \\ |
| 1874 |
Adobe-Korea1 & AdobeMyungjoStd-Medium-Acro & \\ |
| 1875 |
Adobe-CNS1 & AdobeHeitiStd-Regular & Adobe Reader 7 \\ |
| 1876 |
Adobe-Japan1 & KozMinProVI-Regular & Adobe Reader 8\\ |
| 1877 |
\hline |
| 1878 |
\end{tabular} |
| 1879 |
\caption{List of available `Standard' CJK font. Most of them are |
| 1880 |
available as a part of Adobe Asian Font Packs for each versions of |
| 1881 |
Adobe or Acrobat Reader.}\label{TABLE:StdCJKFont} |
| 1882 |
\end{table} |
| 1883 |
|
| 1884 |
Only fixed-pitch glyphs (i.e., quarter, third, half, and full widths) are |
| 1885 |
supported for those fonts. |
| 1886 |
|
| 1887 |
\subsubsection{Stylistic Variants} |
| 1888 |
|
| 1889 |
\deprecated{Use of this option is deprecated.} |
| 1890 |
\noindent{}Keywords \code{,Bold}, \code{,Italic}, and \code{,BoldItalic} can be |
| 1891 |
used to create synthetic bold, italic, and bolditalic style variants from other |
| 1892 |
font using PDF viewer's (or OS's) function. |
| 1893 |
\begin{lstlisting} |
| 1894 |
jbtmo@UKS@ UniKSCms-UCS2-H :0:!batang,Italic |
| 1895 |
\end{lstlisting} |
| 1896 |
|
| 1897 |
Availability of this feature highly depends on the implementation of PDF |
| 1898 |
viewers. This feature is usually not supported for embedded fonts. |
| 1899 |
Notice that this option automatically disables font embedding thus |
| 1900 |
use of it is deprecated. |
| 1901 |
|
| 1902 |
\subsection{Specifying Unicode Plane} |
| 1903 |
|
| 1904 |
As there is no existing TFM format supporting 3-byte or 4-byte character |
| 1905 |
encodings, the only way to use Unicode characters other than the BMP is to |
| 1906 |
map the code range 0-65535 to different planes via (e.g., to plane 1) |
| 1907 |
the \option{-p 1} fontmap option. This option is |
| 1908 |
available only when \code{unicode} is specified in the encoding field. |
| 1909 |
|
| 1910 |
\subsection{OpenType Layout Feature} |
| 1911 |
|
| 1912 |
The OpenType Layout Feature fontmap options mentioned below are only meaningful |
| 1913 |
when \code{unicode} is specified in the encoding field. |
| 1914 |
|
| 1915 |
With the \option{-w} option, writing mode can be specified. |
| 1916 |
\option{-w 1} denotes the font is for vertical writing. It automatically |
| 1917 |
enables an OpenType Layout Feature related to vertical writing, namely, |
| 1918 |
\code{vert} or \code{vrt2}, to choose proper glyphs for vertical text. |
| 1919 |
|
| 1920 |
\newfeature{Addition in \TeX\ Live 2017.} |
| 1921 |
|
| 1922 |
The \option{-l} (lower case el) option can be used to enable various |
| 1923 |
OpenType Layout GSUB Features. For example, \option{-l jp04} enables |
| 1924 |
\code{jp04} feature to select \lnum{JIS2004} forms for Kanjis. |
| 1925 |
Features can be specified as a ``:'' separated list of OpenType Layout |
| 1926 |
Feature tags like \option{-l vkna:jp04}. Script and language may be |
| 1927 |
additionally specified as |
| 1928 |
\option{-l kana.JAN.ruby}. |
| 1929 |
|
| 1930 |
An example can be |
| 1931 |
\begin{lstlisting} |
| 1932 |
uprml-v unicode SourceHanSerifJP-Light.otf -w 1 -l jp90 |
| 1933 |
\end{lstlisting} |
| 1934 |
which declares that font should be treated as for vertical writing and |
| 1935 |
use \lnum{JIS1990} form for Kanjis. |
| 1936 |
|
| 1937 |
\begin{figure} |
| 1938 |
\centering |
| 1939 |
\jpzerofourexamples\hspace{30pt}\jpninezeroexamples% |
| 1940 |
\caption{\lnum{JIS2004} vs. \lnum{JIS1990} form.}\label{FIG:jp90} |
| 1941 |
\end{figure} |
| 1942 |
|
| 1943 |
This feature is limited to the single substitution, there are no way to select |
| 1944 |
a glyph from multiple candidates, such as in the \code{aalt} feature, and specifying |
| 1945 |
general many-to-many glyph substitutions does not take effect. |
| 1946 |
|
| 1947 |
\section{Other Improvements} |
| 1948 |
|
| 1949 |
This section briefly describes other improvements made for \dvipdfmx. |
| 1950 |
There is an extension to glyph name handling in the \code{enc} file for |
| 1951 |
seamless support of both PostScript Type1 and TrueType fonts. |
| 1952 |
PostScript Type1 font support is enhanced although this format might be |
| 1953 |
considered obsolete. |
| 1954 |
|
| 1955 |
\subsection{Extended Glyph Name Syntax} |
| 1956 |
|
| 1957 |
\dvipdfmx\ accepts the following syntax for glyph names in the \code{enc} file: |
| 1958 |
\code{uni0130}, \code{zero.onum} and \code{T\_h.liga}. |
| 1959 |
Each represents a glyph accessed with Unicode value \code{U+0130}, |
| 1960 |
oldstyle number for zero and ``Th'' ligature accessed via the OpenType |
| 1961 |
Layout GSUB Feature \code{onum} and \code{liga}, respectively. |
| 1962 |
Note that \dvipdfmx\ does not understand glyph names which directly |
| 1963 |
use a glyph index such as \code{index0102} or \code{gid2104}. |
| 1964 |
|
| 1965 |
When \dvipdfmx\ encounters a glyph name, e.g., \code{T\_h.liga}, it first looks |
| 1966 |
for OpenType \code{post} table if such glyph name exists; if it exists, then |
| 1967 |
\dvipdfmx\ simply uses \code{post} table and maps the glyph name to the glyph index; |
| 1968 |
if not, \dvipdfmx\ tries to convert \code{T\_h} to a Unicode sequence (U+0054 |
| 1969 |
U+0068 in this example) via the AGL mapping; then, OpenType \code{cmap} table is used |
| 1970 |
to further convert the resulting Unicode sequence to the sequence of glyph indices; |
| 1971 |
finally, the OpenType Layout Feature \code{liga} is applied to get the desired glyph. |
| 1972 |
|
| 1973 |
A glyph name of a form \code{a.swsh2} can be specified to denote the 2nd swash |
| 1974 |
variant form of the letter `a'. |
| 1975 |
|
| 1976 |
\subsection{CFF Conversion} |
| 1977 |
|
| 1978 |
\dvipdfmx\ supports on-the-fly PostScript Type1 to CFF (Type1C) conversion |
| 1979 |
which greatly reduces size of the resulting PDF file when using Type1 fonts. |
| 1980 |
Conversion is essentially `lossless' and there should not be any quality loss. |
| 1981 |
However, due to differences in the ability of rasterizers, there might be |
| 1982 |
noticeable differences on rendering result. |
| 1983 |
|
| 1984 |
When an older Type1 font is used, \dvipdfmx\ may give the following warning |
| 1985 |
message: |
| 1986 |
\begin{lstlisting} |
| 1987 |
Obsolete four arguments of "endchar" will be used for Type1 |
| 1988 |
"seac" operator. |
| 1989 |
\end{lstlisting} |
| 1990 |
It happens when there is an accented character made as a composite glyph using |
| 1991 |
the ``seac'' operator. |
| 1992 |
This warning is issued as conversion can't be done without relying on the |
| 1993 |
\emph{deprecated} usage of the \code{endchar} operator. However, as mentioned in |
| 1994 |
``Appendix C Compatibility and Deprecated Operators'' of Adobe Technical |
| 1995 |
Note \#5177, |
| 1996 |
``\href{https://wwwimages.adobe.com/content/dam/Adobe/en/devnet/font/pdfs/5177.Type2.pdf}{Type 2 Charstring Format}'', |
| 1997 |
PDF applications should support this operator and hence this warning |
| 1998 |
message can be ignored. |
| 1999 |
|
| 2000 |
Use of Type1 font should be avoided as much as possible. |
| 2001 |
Please consider using OpenType version instead. |
| 2002 |
|
| 2003 |
\section{Font Licensing} |
| 2004 |
|
| 2005 |
In OpenType font format, information regarding how a font should be treated |
| 2006 |
when creating a document can be recorded.% |
| 2007 |
\footnote{See, |
| 2008 |
``\href{https://www.microsoft.com/typography/otspec/os2.htm}{OpenType Specification: |
| 2009 |
OS/2 -- OS/2 and Windows Metrics Table}''}. |
| 2010 |
\dvipdfmx\ uses this information to decide whether font embedding is permitted. |
| 2011 |
|
| 2012 |
This font licensing information is indicated by the flag called \code{fsType} |
| 2013 |
recorded in OpenType font files; each bits representing different restrictions on |
| 2014 |
font embedding. If multiple flag bits are set in \code{fsType}, the least restrictive |
| 2015 |
license granted takes precedence in \dvipdfmx. |
| 2016 |
The \code{fsType} flag bit recognized by \dvipdfmx\ is as follows: |
| 2017 |
\begin{itemize} |
| 2018 |
\item Installable embedding |
| 2019 |
\item Editable embedding |
| 2020 |
\item Embedding for Preview \& Print only |
| 2021 |
\end{itemize} |
| 2022 |
\dvipdfmx\ issues the following warning message for fonts with `Preview \& Print only' |
| 2023 |
setting: |
| 2024 |
\begin{verbatim} |
| 2025 |
This document contains 'Preview & Print' only licensed font |
| 2026 |
\end{verbatim} |
| 2027 |
|
| 2028 |
For a font with this type of licensing, font embedding is allowed solely for the |
| 2029 |
purpose of (on-screen) viewing and/or printing; further editing of the document |
| 2030 |
or extracting embedded font data for other purposes are not allowed. |
| 2031 |
One way to ensure this condition is to protect your document with a non-empty |
| 2032 |
password. |
| 2033 |
|
| 2034 |
All other flags are treated as more restrictive license than any of |
| 2035 |
the above flags and treated as ``No embedding allowed''; e.g., if both |
| 2036 |
of the editable-embedding flag and unrecognized license flag is set, |
| 2037 |
the font is treated as editable-embedding allowed, however, if only |
| 2038 |
unrecognized flags are set, the font is not embedded. |
| 2039 |
|
| 2040 |
Font Embedding flags are preserved in the embedded font if they are embedded |
| 2041 |
as a TrueType font or a CIDFontType2 CID-keyed font. |
| 2042 |
For all fonts embedded as a PostScript font (Type1C and CIDFontType0 |
| 2043 |
CID-keyed font), they are not preserved. |
| 2044 |
Only \code{Copyright} and \code{Notice} in the \keyword{FontInfo} dictionary |
| 2045 |
are preserved in this case. |
| 2046 |
|
| 2047 |
Some font vendors put different embedding restrictions for different |
| 2048 |
condition; e.g., font embedding might not be permitted for the commercial |
| 2049 |
use unless you acquire the ``commercial license'' separately. |
| 2050 |
Please read EULA carefully before making decision on the font usage. |
| 2051 |
|
| 2052 |
See, for example, |
| 2053 |
\href{https://www.adobe.com/products/type/font-licensing/font-embedding-permissions.html}{Adobe's site on font embedding permissions} |
| 2054 |
for the font in the Adobe Type Library. |
| 2055 |
Microsoft also has a |
| 2056 |
\href{https://www.microsoft.com/typography/RedistributionFAQ.mspx}{FAQ page on Font Redistribution}. |
| 2057 |
|
| 2058 |
For Japanese fonts in general, embedding permission tend to be somewhat |
| 2059 |
restrictive. Japanese users should read the statement regarding font |
| 2060 |
embedding from Japan Typography Association (in Japanese):\medskip |
| 2061 |
|
| 2062 |
\url{https://www.typography.or.jp/act/morals/moral4.html} |
| 2063 |
\medskip |
| 2064 |
|
| 2065 |
\dvipdfmx\ does not support full embedding. Only subset embedding is supported. |
| 2066 |
|
| 2067 |
\chapter{Encryption} |
| 2068 |
|
| 2069 |
\section{Encryption Support}\label{SEC:encryption} |
| 2070 |
|
| 2071 |
\dvipdfmx\ offers basic PDF password security support including the 256-bit AES encryption. |
| 2072 |
Only the ``Standard'' security handler is supported and the Public-key security handler is not |
| 2073 |
supported. |
| 2074 |
|
| 2075 |
Encryption is enabled by \option{-S} command line option. |
| 2076 |
\begin{lstlisting} |
| 2077 |
dvipdfmx -S -K 128 -P 0x14 |
| 2078 |
\end{lstlisting} |
| 2079 |
where \code{-K} and \code{-P} options are used to specify encryption key length and |
| 2080 |
permission flags respectively, and are briefly explained in Table~\ref{TABLE:enc-options}. |
| 2081 |
|
| 2082 |
\begin{table} |
| 2083 |
\centering |
| 2084 |
\begin{tabular}{lp{8cm}}\hline |
| 2085 |
Option & Description \\ \hline\hline |
| 2086 |
\code{-S} & Enable PDF encryption. \\ |
| 2087 |
\code{-K} \textit{number} & Set encryption key length. The default value |
| 2088 |
is 40.\\ |
| 2089 |
\code{-P} \textit{number} & Set permission flags for PDF encryption. |
| 2090 |
The \textit{number} is a 32-bit unsigned integer representing permission |
| 2091 |
flags. |
| 2092 |
See, Table~\ref{TABLE:flags}. The default value is \code{0x003C}.\\ |
| 2093 |
\hline |
| 2094 |
\end{tabular} |
| 2095 |
\caption{Command line options for encryption.}% |
| 2096 |
\label{TABLE:enc-options} |
| 2097 |
\end{table} |
| 2098 |
|
| 2099 |
When \dvipdfmx\ is invoked with encryption via the \code{-S} option, |
| 2100 |
passwords will be asked. |
| 2101 |
However, in some circumstances, it might be desirable to avoid being prompted for |
| 2102 |
passwords. In that case, use the \code{pdf:encrypt} special to supply passwords in |
| 2103 |
the \TeX\ file, as, |
| 2104 |
\begin{lstlisting} |
| 2105 |
\special{pdf:encrypt userpw (foo) ownerpw (bar) length 128 perm 20} |
| 2106 |
\end{lstlisting} |
| 2107 |
Here, user and owner passwords are supplied as PDF string objects (\code{foo} and \code{bar} |
| 2108 |
in the example above) which can be empty. |
| 2109 |
|
| 2110 |
Up to two passwords can be specified for a document -- an owner password and a user password. |
| 2111 |
If a user attempts to open an encrypted document with user password being set, PDF application |
| 2112 |
should prompt for a password. Users are allowed to access the contents of the document only when |
| 2113 |
either password is correctly supplied. |
| 2114 |
Depending on which password (user or owner) was supplied, additional operations |
| 2115 |
allowed for the opened document is determined; full access for users who opened |
| 2116 |
with the correct owner password or additional operations |
| 2117 |
controlled by permission flags for users who opened with the correct user password. |
| 2118 |
|
| 2119 |
Although PDF specification allows various character encodings other than \code{US-ASCII} |
| 2120 |
for entering password, \dvipdfmx\ is unable to handle it properly. |
| 2121 |
Thus it must be assumed that \code{US-ASCII} is used for password strings. |
| 2122 |
|
| 2123 |
Access permission flags can be specified via \option{-P} command-line option. |
| 2124 |
Each bits of (32-bit unsigned) integer number given to this option represents user |
| 2125 |
access permissions; e.g., bit position 3 for allowing ``print'', 4 for |
| 2126 |
``modify'', 5 for ``copy or extract'', and so on. See, Table~\ref{TABLE:flags}. |
| 2127 |
For example, \code{-P 0x34} allows printing, copying and extraction of text, and adding and |
| 2128 |
modifying text annotation and filling in interactive form fields (but disallows |
| 2129 |
modification of the contents of the document). |
| 2130 |
\begin{table} |
| 2131 |
\centering |
| 2132 |
\begin{tabular}{lp{.7\hsize}}\hline |
| 2133 |
Bit Position & Meaning \\ \hline\hline |
| 2134 |
3 & (Revision 2) Print the document. \\ |
| 2135 |
& (Revision 3 or greater) Print the document. Print quality depending on bit 12.\\ |
| 2136 |
4 & Modify the contents of the document by operations other than those controlled |
| 2137 |
by bits 6, 9, and 11. \\ |
| 2138 |
5 & Copy or extract text and graphics from the document. \\ |
| 2139 |
6 & Add or modify text annotations, fill in interactive form fields. |
| 2140 |
Creation and modification of interactive form field is also |
| 2141 |
allowed if bit 4 is set.\\ |
| 2142 |
9 & (Revision 3 or greater) Fill in existing interactive form fields |
| 2143 |
(including signature fields), even if bit 6 is clear.\\ |
| 2144 |
10 & \em{Deprecated in PDF 2.0} \\ |
| 2145 |
& (Revision 3 or greater) Extract text and graphics (in support of accessibility to |
| 2146 |
users with disabilities or for other purposes).\\ |
| 2147 |
11 & (Revision 3 or greater) Assemble the document |
| 2148 |
(insert, rotate, or delete pages and create document outline items or thumbnail |
| 2149 |
images), even if bit 4 is clear.\\ |
| 2150 |
12 & (Revision 3 or greater) High-quality printing. |
| 2151 |
When this bit is clear (and bit 3 is set), printing shall be limited to a low-level, |
| 2152 |
possibly of degraded quality.\\ |
| 2153 |
\hline |
| 2154 |
\end{tabular} |
| 2155 |
\caption{Flag bits and brief explanations. |
| 2156 |
Revision~2 is used when the encryption key length is 40 bits |
| 2157 |
or when PDF output version is less than 1.5. Otherwise, |
| 2158 |
Revision~3 or greater is used.}\label{TABLE:flags} |
| 2159 |
\end{table} |
| 2160 |
|
| 2161 |
The \option{-K} option can be used to specify the encryption key length. |
| 2162 |
The key length must be multiple of 8 in the range 40 to 128, or 256 (for PDF |
| 2163 |
version 1.7 plus Adobe Extension or PDF version 2.0). Please note |
| 2164 |
that when key length 256 is specified for PDF version 1.7 output, it requires |
| 2165 |
Adobe's Extension to \lnum{PDF-1.7} and hence PDF applications may not support it. |
| 2166 |
PDF version 1.4 is required for key length more than 40 bits. AES encryption algorithm requires |
| 2167 |
PDF version 1.6. |
| 2168 |
|
| 2169 |
To show some examples:\\ |
| 2170 |
128-bit AES encryption with print-only (high-quality) setting, |
| 2171 |
\begin{lstlisting} |
| 2172 |
dvipdfmx -V 5 -S -K 128 -P 0x804 input.dvi |
| 2173 |
\end{lstlisting} |
| 2174 |
256-bit AES encryption with print (low-quality), adding and modifying text annotations |
| 2175 |
allowed, |
| 2176 |
\begin{lstlisting} |
| 2177 |
dvipdfmx -V 2.0 -S -K 256 -P 0x24 input.dvi |
| 2178 |
\end{lstlisting} |
| 2179 |
|
| 2180 |
The default value for \option{-K} is 40 and for \option{-P} is \code{0x003C0} |
| 2181 |
(all bits from bit-position 3 to 6 set). |
| 2182 |
|
| 2183 |
\chapter{Compatibility} |
| 2184 |
|
| 2185 |
\section{Incompatible Changes}\label{SEC:compatibility} |
| 2186 |
|
| 2187 |
There are various minor incompatible changes to \dvipdfm. |
| 2188 |
|
| 2189 |
The \option{-C} command line option may be used for compatibility to |
| 2190 |
\dvipdfm\ or older versions of \dvipdfmx. The \option{-C} option takes flags |
| 2191 |
meaning |
| 2192 |
\begin{itemize} |
| 2193 |
\item bit position 2: Use semi-transparent filling for tpic shading |
| 2194 |
command, instead of opaque gray color. (requires PDF 1.4) |
| 2195 |
\item bit position 3: Treat all CID-keyed font as fixed-pitch font. This is |
| 2196 |
only for compatibility. |
| 2197 |
\item bit position 4: Do not replace duplicate fontmap entries. |
| 2198 |
\dvipdfm\ behavior. |
| 2199 |
\item bit position 5: Do not optimize PDF destinations. Use this if you |
| 2200 |
want to refer from other files to destinations in the current file. |
| 2201 |
\item bit position 6: Do not use predictor filter for Flate compression. |
| 2202 |
\item bit position 7: Do not use object stream. |
| 2203 |
\end{itemize} |
| 2204 |
|
| 2205 |
The remap option \option{-r} in fontmaps is no longer supported and is |
| 2206 |
silently ignored. The command line option \option{-e} to disable partial |
| 2207 |
(subset) font embedding is not supported. |
| 2208 |
|
| 2209 |
\section{Important Changes} |
| 2210 |
|
| 2211 |
Here is a list of important changes since the \TeX\ Live 2016 release: |
| 2212 |
\begin{itemize} |
| 2213 |
\item Changes to make PDF/A creation easier: Always write CIDSet and CharSet |
| 2214 |
for embedded fonts. Do not compress XMP metadata. |
| 2215 |
\item Merge from libdpx for p\TeX-ng by Clerk Ma. |
| 2216 |
\item Addition of \code{STHeiti-Regular-Acro} for CJK `Standard' fonts. |
| 2217 |
\item Command line option \option{-p} takes precedence over \code{papersize} |
| 2218 |
and \code{pagesize} specials. |
| 2219 |
\item Fixed serious bugs in supporting `\code{unicode}' encoding: |
| 2220 |
OpenType Layout Feature \code{vert} and \code{vrt2} was not enabled. |
| 2221 |
Support for format 2 CFF charsets was broken. |
| 2222 |
\item Added simplified version of OpenType Layout support: The `\option{-l}' |
| 2223 |
option in fontmaps. |
| 2224 |
\end{itemize} |
| 2225 |
The full \code{ChangeLog} entries can be viewed via the web interface of the |
| 2226 |
\TeX\ Live SVN repository: |
| 2227 |
\medskip |
| 2228 |
|
| 2229 |
\url{https://tug.org/svn/texlive/trunk/Build/source/texk/dvipdfm-x} |
| 2230 |
\medskip |
| 2231 |
|
| 2232 |
There was an undocumented feature for supporting OpenType Layout but it was |
| 2233 |
dropped. Simplified support for the OpenType Layout was introduced instead. |
| 2234 |
|
| 2235 |
|
| 2236 |
%\renewcommand{\refname}{Further Reading} |
| 2237 |
\renewcommand{\bibname}{Further Reading} |
| 2238 |
\begin{thebibliography}{99} |
| 2239 |
\bibitem{DVIPDFM} ``\href{https://mirrors.ctan.org/dviware/dvipdfm/dvipdfm.pdf}% |
| 2240 |
{Dvipdfm User's Manual}'' written by Mark~A.~Wicks. |
| 2241 |
\bibitem{ADOBE} Adobe's PDF References and a free copy of |
| 2242 |
\lnum{ISO 32000-1:2008} standard are available from |
| 2243 |
``\href{https://www.adobe.com/devnet/pdf.html}{PDF Technology Center}'' |
| 2244 |
on \href{https://www.adobe.com/devnet.html}{Adobe Developer Connection}. |
| 2245 |
\bibitem{MICROSOFT} The OpenType Specification is available from Microsoft's |
| 2246 |
site: |
| 2247 |
``\href{https://www.microsoft.com/en-us/Typography/OpenTypeSpecification.aspx}% |
| 2248 |
{OpenType Specification}''. |
| 2249 |
\bibitem{PNGSPEC} ``\href{https://www.w3.org/TR/2003/REC-PNG-20031110/}% |
| 2250 |
{Portable Network Graphics (PNG) Specification (Second Edition)}''. |
| 2251 |
\bibitem{CHOF} An article regarding DVI specials: Jin-Hwan Cho, |
| 2252 |
``\href{https://tug.org/TUGboat/tb30-1/tb94cho.pdf}{DVI specials for PDF generation}'', |
| 2253 |
TUGboat 30(1):6--11, 2009. |
| 2254 |
\end{thebibliography} |
| 2255 |
|
| 2256 |
\appendix |
| 2257 |
|
| 2258 |
\twocolumn |
| 2259 |
{\footnotesize |
| 2260 |
\emergencystretch=1.5em \hbadness=2000 \hfuzz=.25pt |
| 2261 |
\chapter{GNU Free Documentation License v1.3} |
| 2262 |
\label{SEC:FDL} |
| 2263 |
\input{fdl-1.3.tex} |
| 2264 |
} |
| 2265 |
\end{document} |