Debian Codegraph @

texmf-dist/doc/dvipdfmx/dvipdfmx.tex

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