summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/dvipdfmx/dvipdfmx.tex
blob: df6c7cabe9e95f6d7657dee98d31a99e4c3e72b2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
\documentclass[a4paper,xetex]{article}
\usepackage{xltxtra}
\usepackage{fontspec}
\usepackage{microtype}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% PLATFORM DEPENDENT INSTRUCTION HERE
%% Font setup for body text.
\setmainfont{Constantia}
\setsansfont{Cambria}
\setmonofont[Scale=0.92]{Consolas}% Adjust xheight difference
%% The following section is for showing some fancy examples.
%% Some fonts used here may not be availabel on your system.
%% Please modify this. Just replacing with empty macros is OK.
\newcommand{\jpzerofourexamples}{{%
\setmainfont[Scale=5,RawFeature=+jp04]{SourceHanSerifJP-Light.otf}葛祇逢}}
\newcommand{\jpninezeroexamples}{{%
\setmainfont[Scale=5,RawFeature=+jp90]{SourceHanSerifJP-Light.otf}葛祇逢}}
%% We use PostScript raw code here to test dvipdfmx's capability.
%% TFM files `rml' and `rmlv' are distributed with ASCII pTeX.
%% TrueType font `yumindb.ttf' is bundled with Windows 10.
\newcommand{\jphoritext}{%
\makebox[112bp][l]{%
\raisebox{88bp}[112bp][0bp]{%
\special{pdf:mapline rml UniJIS-UTF8-H yumindb.ttf}
\special{ps: rml findfont 16 scalefont setfont
  currentpoint moveto (「こんにちは」) show}%
}}}
\newcommand{\jpverttext}{%
\makebox[16bp][l]{%
\raisebox{112bp}[112bp][0bp]{%
\special{pdf:mapline rmlv UniJIS-UTF8-V yumindb.ttf}
\special{ps: rmlv findfont 16 scalefont setfont
  currentpoint moveto (「こんにちは」) show}%
}}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage{xcolor,hyperref,hyperxmp}
\hypersetup{%
    bookmarksnumbered=true,%
    colorlinks=true,%
    urlcolor=[rgb]{0.2,0.2,0.4},
    linkcolor=[rgb]{0.2,0.2,0.4},
    pdftitle={The Dvipdfmx User's Manual},%
    pdfauthor={The dvipdfmx project team},%
    pdfsubject={A User's Manual for Dvipdfmx and Xdvipdfmx.},%
    pdfkeywords={dvipdfmx, XeTeX, TeX, LaTeX},
    pdflang=en,
    pdfcopyright={Copyright © The dvipdfmx project team.
    Permission is granted to copy, distribute and/or modify this document
    under the terms of the GNU Free Documentation License, Version 1.3
    or any later version published by the Free Software Foundation;
    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
    A copy of the license is included in the section entitled "GNU
    Free Documentation License".},
    pdflicenseurl={http://www.gnu.org/licenses/fdl.html}
}
\usepackage{listings}
\lstset{
    keepspaces=true,
    basicstyle={\ttfamily},
    frame={tb},
    breaklines=true,
    columns=[l]{fullflexible},
    numbers=none,
    xrightmargin=2em,
    xleftmargin=2em,
    aboveskip=2em,
    belowskip=2em
}
\usepackage{mflogo}
\usepackage{marginnote}
\renewcommand*{\marginfont}{\footnotesize\itshape}
\usepackage[noorphans,font=itshape]{quoting}
\newcommand{\package}[1]{{\itshape #1}}
\newcommand{\code}[1]{\texttt{#1}}
\newcommand{\option}[1]{`\texttt{#1}'}
\newcommand{\dvipdfm}{\texttt{dvipdfm}}
\newcommand{\dvipdfmx}{\texttt{dvipdfmx}}
\newcommand{\xdvipdfmx}{\texttt{xdvipdfmx}}
\newcommand{\deprecated}[1]{\marginnote{\addfontfeatures{Color=CC3333}#1}}
\newcommand{\lnum}[1]{{\addfontfeatures{RawFeature=+lnum}#1}}
\usepackage{fancyhdr}
\pagestyle{fancy}
%\lhead{}
\title{The \dvipdfmx\ User's Manual}
\author{The \dvipdfmx\ project team\footnote{Jin-Hwan Cho, Matthias Franz,
and \href{mailto:shunsaku.hirata74@gmail.com}{Shunsaku Hirata}}}
\date{May 6, 2017}
\begin{document}

\maketitle
%\tableofcontents

\section{Introduction}

The \dvipdfmx\ (formerly \dvipdfm-cjk) project
provides an extended version of the \dvipdfm, a DVI to PDF translator developed
by Mark~A.~Wicks.

The primary goal of this project is to support multi-byte character encodings
and large character sets such as for East Asian languages.
This project started as a combined work of the \dvipdfm-jpn project by
Shunsaku Hirata and its modified one, \dvipdfm-kor, by Jin-Hwan Cho.

Extensions to \dvipdfm\ include,
\begin{itemize}
    \item Support for OpenType and TrueType font, including partial support
    for OpenType Layout for finding glyphs and vertical writing.
    \item Support for CJK-\LaTeX\ and H\LaTeX\ with Subfont Definition Files.
    \item Support for various legacy multi-byte encodings via PostScript CMap
     Resources.
    \item Unicode related features: Unicode as an input encoding and
    auto-creation of ToUnicode CMaps.
    \item Support for p\TeX\ (a Japanese localized variant of \TeX) including
    vertical writing extension.
    \item Some extended DVI specials.
    \item Reduction of output files size with on-the-fly Type1 to CFF (Type1C)
    conversion and PDF object stream.
    \item Advanced raster image support including alpha channels, embedded
    ICC profiles, 16-bit bit-depth colors, and so on.
    \item Basic PDF password security support for PDF output.
\end{itemize}
Some important features are still missing:
\begin{itemize}
    \item Linearization.
    \item Color Management.
    \item Resampling of images.
    \item Selection of compression filters.
    \item Variable font and OpenType 1.8.
    \item and many more...
\end{itemize}

\dvipdfmx\ is now maintained as part of \TeX\ Live. Latest source code can
be found at \TeX\ Live SVN repository. For an instruction on accessing the
development sources for TeX Live, see,\medskip

\url{http://www.tug.org/texlive/svn/}
\medskip

This manual, ``The \dvipdfmx\ User's Manual'', is originally prepared for
\TeX\ Live 2017. Current maintainer of this manual is Shunsaku Hirata.
Latest version and contact information can be found at:\medskip

\url{http://github.com/shirat74/dvipdfm-x-doc/}
\medskip

\noindent{}Please send quenstions or suggestions.

\subsection{\xdvipdfmx}

\xdvipdfmx\ is an extended version of \dvipdfmx, and is now incorporated into
\dvipdfmx.

The \xdvipdfmx\ extensions provides support for the Extended DVI (.xdv) format
generated by \XeTeX which includes support for platform-native fonts and the
\XeTeX\ graphics primitives, as well as Unicode text and OpenType font.

\XeTeX\ originally used a Mac-specific program called \code{xdv2pdf} as a
backend program instead of \xdvipdfmx. The \code{xdv2pdf} program supported
a couple of special effects that are not yet available through \xdvipdfmx:
The Quartz graphics-based shadow support, AAT ``variation'' fonts such as Skia,
transparency as an attribute of font, and so on.
It would be nice if they continue to be supported. Suggestions and help are
welcomed.


\subsection{Legal Notice}

Copyright © The dvipdfmx project team.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled
``\hyperref[SEC:FDL]{GNU Free Documentation License}''.

\section{Installation and Usage}

Typical usage and installation steps are not different from the original
\dvipdfm. Please refer documents from \dvipdfm\ distribution for detailed
instruction on how to install and how to use \dvipdfm. The \dvipdfm\ manual is
available from its CTAN site:\medskip

\url{http://www.ctan.org/tex-archive/dviware/dvipdfm}
\medskip

The minimal requirements for building \dvipdfmx\ is the \code{kpathsea} library.
\code{zlib} for compression and \code{libpng} for PNG inclusion are highly
recommended. Optionally, the libpaper library may be used to handle paper sizes.

This document only describes additions and modifications to \dvipdfm.
Please refer the
``\href{http://mirrors.ctan.org/dviware/dvipdfm/dvipdfm.pdf}{Dvipdfm User's Manual}''
available from the CTAN site mentioned above for basic usage.

Some additional command line options recognized by \dvipdfmx\ are listed in
Table~\ref{TABLE:options}. Try
\begin{lstlisting}
dvipdfmx --help
\end{lstlisting}
for the list of command line options and thier explanations.

\begin{table}
    \centering
    \begin{tabular}{lp{8cm}}\hline
        Option & Description \\ \hline\hline
        \code{-C} \textit{number} & Specify miscellaneous option flags. See,
        section of ``\hyperref[SEC:compatibility]{Incompatible Changes}'' for
        details. \\
        \code{-S} & Enable PDF encryption. \\
        \code{-K} \textit{number} & Set encryption key length. The default value
        is 40.\\
        \code{-P} \textit{number} & Set permission flags for PDF encryption.
        The \textit{number} is a 32-bit unsigned integer representing permission
        flags.
        See, section of ``\hyperref[SEC:encryption]{Encryption Support}''.
        The default value is \code{0x003C}.\\
        \code{-I} \textit{number} & Life of image cache in hours. By specifying
        value \code{0} \dvipdfmx\ erases cached images, and value \code{-1}
        erases all cached images and does not leave newly generated one. The
        default value is \code{-2}. (ignore image cache) \\
        \code{-M} & Process \MP\ generated PostScript file.\\
        \code{-E} & Always try to embed fonts \emph{regardless of
        liscensing}.\\
        \hline
    \end{tabular}
    \caption{Additional command line options recognized by \dvipdfmx.}%
    \label{TABLE:options}
\end{table}


\section{Quick Guide}

\dvipdfmx\ is supposed to be used by users of \LaTeX\ packages for typesetting
CJK languages like H\LaTeX\ and CJK-\LaTeX, and \TeX\ variants such as \XeTeX,
p\TeX, and up\TeX.
This section is intended to be a quick guide for each users.

\subsection{\texorpdfstring{\XeTeX}{XeTeX}}
For \XeTeX\ users, most part of this document is irrelevant except section of
``\hyperref[SEC:graphics]{Graphics and Image Formats}'' and
``\hyperref[SEC:specials]{DVI Specials}''.

\subsection{p\TeX}
p\TeX\ users are at least required to install several auxilially files
mentioned in the section of ``\hyperref[SEC:auxfiles]{Auxilially Files}''
and to setup fontmappings. Just install the \package{adobemappings} and
\package{glyphlist} for auxilially files. (As \TeX\ Live basic intallation
requires them, they are probably already installed for \TeX\ Live users.)

Setting up fontmaps can be done easily with help of the \package{ptex-fontmaps}
package. For examples, to use with IPA fonts (contained
in the \package{ipaex} package), run,
\begin{lstlisting}
updmap ipaex
\end{lstlisting}
Alternatively, just for a quick test of installation, try the following:
\begin{lstlisting}
\documentclass{article}
\begin{document}
\special{pdf:mapline rml H KozMinProVI-Regular}
...Some Japanese text goes here...
\end{document}
\end{lstlisting}
In this example, PDF viewer which can handle substitute font is required since
\dvipdfmx\ does not embed fonts.

For using Japanese text in PDF document information and annotations, put
the following \code{special} command,
\begin{lstlisting}
\AtBeginDocument{\special{pdf:tounicode 90ms-RKSJ-UCS2}}
\end{lstlisting}
in the preamble.
The above \code{special} command instructs \dvipdfmx\ to convert text encoded
in Shift-JIS to Unicode. For EUC-JP, replace 90ms-RKJK-UCS2 with EUC-UCS2.

\subsection{up\TeX}
up\TeX\ users are basically the same as p\TeX\ users but there are two choices
for setting fontmaps. Setup fontmaps as mentioned in the above for p\TeX, or use
keyword \code{unicode} in the encoding field of fontmap files.

The former case might be easier as auto-creation of fontmap files can be done
with the \code{updmap} program and the \package{ptex-fontmaps} package. But in
this method there are some difficulties when using fonts which employ character
collection (glyph repertoire) other than Adobe-Japan1 in the case of PostScript
flvavored OpenType fonts.
In the later case, the \package{adobemappings} package is not reuiqred
and newer PostScript flavored OpenType fonts which do not employ Adobe-Japan1
can be used too.

Using \code{unicode} is more simpler and intuitive thus it is recommended to
use this method.\footnote{For \TeX\ Live 2017. Earlier versions have buggy
support.}
Typical example fontmap entries for using Adobe's SouceHan fonts look like:
\begin{lstlisting}
urml    unicode  SourceHanSerifJP-Light.otf
urmlv   unicode  SourceHanSerifJP-Light.otf  -w 1
ugbm    unicode  SourceHanSansJP-Medium.otf
ugbmv   unicode  SourceHanSansJP-Medium.otf  -w 1
\end{lstlisting}

As in p\TeX, the following \code{special} instruction is necessary to PDF
document information and annotations to  be shown correctly:
\begin{lstlisting}
\AtBeginDocument{\special{pdf:tounicode UTF8-UCS2}}
\end{lstlisting}
Here, input encodig is assumed to be UTF-8.

\subsection{CJK-\LaTeX}

CJK-\LaTeX users are required to have Subfont Definition Files to be installed.
They are available as part of the \package{ttfutils} package.

To use TrueType Ariphic fonts provided by the \package{arphic-ttf} package:
\begin{lstlisting}
\documentclass{article}
\usepackage{CJKutf8}
...Other packages loaded here...
\AtBeginDocument{%
  \special{pdf:tounicode UTF8-USC2}%
  \special{pdf:mapline bsmiu@Unicode@ unicode bsmi00lp.ttf}%
 }
\begin{document}
\begin{CJK}{UTF8}{bsmi}
...some Chinese text goes here...
\end{CJK}
\end{document}
\end{lstlisting}
Here, \code{pdf:mapline} special is used to setup fontmappings.

\section{Auxiliary Files}\label{SEC:auxfiles}

This section is mostly for supporting legacy encodings and legacy font format
such as PostScript Type1 font. \XeTeX\ users may skip this section.

\dvipdfmx\ has a capability to handle various input encodings from 7-bit
encodings to variable-width multi-byte encodings. It also has some sort of
Unicode support. Several auxiliary files which are not common to \TeX\ users
are needed to enable those features. This section shortly describes about them.

\subsection{PostScript CMap Resources}

PostScript CMap Resources\footnote{See, ``\href{http://www.adobe.com/content/dam/Adobe/en/devnet/font/pdfs/5014.CIDFont\_Spec.pdf}{Adobe CMap and CIDFont Files Specification}''}
are required for supporting lagacy encodings such as Shift-JIS, EUC-JP, Big5,
and other East Asian encodings. \dvipdfmx\ internally identifies glyphs with
identifiers (CIDs\footnote{PostScript terminology ``Character IDentifier''.})
represented as an integer ranging from 0 to 65535 in the CID-based glyph access.
PostScript CMap Resources describes the mapping between sequences of input
character codes and CIDs. \dvipdfmx\ has an extensible support for multi-byte
encodings via PostScript CMap Resources.

CMap files for standard East Asian encodings, for use with Adobe's character
collections, are included in the \package{adobemapping} package.
The latest version of those CMap files maintained by Adobe can be found at
Adobe's GitHub Project page:\medskip

\url{http://github.com/adobe-type-tools/cmap-resources}
\medskip

Those files are mandatory for supporting p\TeX. up\TeX\ users may also
want to install them but they are not required.

\subsection{Subfont Definition Files}

CJK fonts usually contain several thousands of glyphs. For using such fonts
with (original) \TeX, which can only handle 8-bit encodings, it is necessary to
split fonts into several ``subfonts''. Subfont Definition File (SFD)
specify the way how those fonts are split into subfonts. \dvipdfmx\ uses SFD
files to convert subfonts back to a single font.

SFD files are not required for use with \TeX\ variants which can handle
multi-byte character encodings and large character sets such as p\TeX,
up\TeX,\XeTeX, and Omega.
H\LaTeX\ and CJK-\LaTeX\ users are required to have those files to be
installed. SFD files are available as a part of the \package{ttfutils} package
for \TeX\ Live users.

\subsection{The Adobe Glyph List and ToUnicode Mappings}

The Adobe Glyph List\footnote{See, ``\href{http://github.com/adobe-type-tools/agl-specification}{Adobe Glyph List Specification}''} (AGL)
describes correspondence between PostScript glyph names (e.g., \code{AE},
\code{Aacute},...) and Unicode character sequences representing them.
Some features described in the section ``Unicode Support'' requires AGL file.

\dvipdfmx\ looks for the file \code{glyphlist.txt} when conversion from
PostScript glyph names to Unicode sequences is necessary.
This conversion is done in various situations; when creating ToUnicode CMaps
for 8-bit encoding fonts, finding glyph descriptions from TrueType and OpenType
fonts when the font itself does not provide a mapping from PostScript glyph
names to glyph indices (version 2.0 ``post'' table), and when the encoding
\code{unicode} is specified for Type1 font.

AGL file is included in the \package{glyphlist} package. The latest version
can be found at Adobe's GitHub site:\medskip

\url{http://github.com/adobe-type-tools/agl-aglfn}
\medskip

ToUnicode Mappings are similar to AGL but they describe correspondence
between CID numbers (instead of glyph names) and Unicode values.
The content of those files are the same as CMap Resources.
They are required when using TrueType fonts emulated as CID-keyed fonts.
They should be found in the same directory as ordinary CMap files.

ToUnicode Mapping files are included in \package{adobemapping} package.
Those files are not required for \XeTeX\ users.

\section{Overview of Extensions}

This section gives a quick overview of \dvipdfmx's extended capabilities.

\subsection{CJK Support}

There are many extensions made for supporting CJK languages. Features described
here is mainly for CJK languages but their use is actually not limited to it.
Those features are implemented in a generic way so that it can be beneficial to
users who are not involved in CJK languages.

\subsubsection{Legacy Multi-byte Encodings}

\dvipdfmx\ has an extensible support for encodings by means of
PostScript CMap Resources. Just like \code{enc} files are written for 8-bit
encodings, one can write their own CMap files to support custom encodings.
See, Adobe's technical notes for details on PostScript CMap Resources.

\subsubsection{Vertical Writing}

\dvipdfmx\ supports vertical writing extension used by p\TeX\ and up\TeX.
A DVI instruction to set writing mode is supported. OpenType Layout
GSUB Feature is supported for selecting vertical version of glyphs.

\begin{figure}
\centering
\jphoritext\hspace{24pt}\jpverttext%
\caption{An example of horizontal and vertical text;
left and right corner brackets are replaced with their vertical counterparts.}%
\label{FIG:verttext}
\end{figure}

\subsection{Unicode Support}

Unicode support here consists of two parts: Supporting Unicode as input
encodings and making output PDF files ``Unicode aware''.

\subsubsection{Unicode as Input Encoding}

\dvipdfmx\ recognizes an additional keyword \code{unicode} in fontmap files
to declare that Unicode values are used in input DVI files. Unicode support is
basically limited to the Basic Multilingual Plane (BMP) since there are no
support for code ranges that requires more than three bytes in TFM and extended
TFM formats.

\subsubsection{ToUnicode CMap Support}

In PDF,it is often the case that text is not encoded in Unicode.
However, modern applications usually want them represented in Unicode to make
it usable. ToUnicode CMaps are a bridge between PDF text string encodings
and Unicode encodings, and they makes it possible to extract text in PDF as
Unicode encoded strings. It is important to make resulting PDF search-able and
copy-and-past-able. Dvipdfmx supports the auto-creation of ToUnicode CMaps.

It will not work properly for multiply encoded glyphs due to fundamental
limitations of Unicode conversion mechanism with ToUnicode CMaps.

\subsection{Other Extensions}

\dvipdfmx\ can generate encrypted PDF documents to protect its contents from
unauthorized access. It is limited to passorwd-based authentication, and
public-key based authentication is not supported. The 256-bit AES encryption is
also supported for PDF version 1.7 setting although it may not be supported
by PDF viewers.

There are various other improvements over \dvipdfm. The most notable one is
more improved PDF input and output support: The cross-reference stream and
object stream introduced in PDF-1.5 are also supported.


\section{Graphics and Image Format}\label{SEC:graphics}

Graphics support was mostly rewritten. Support for BMP and JPEG\lnum{2000} is
added. An effort to preserve more information originally found in included
images, e.g., embedded ICC Profiles and XMP Metadata, was made.

However, \dvipdfmx\ does not support various features common to graphics
manipulation programs such as resampling, color conversion, and selection of
compression filters. Thus, it is recommended to use other programs specialized
in image manipulation for preparation of images.

\subsection{Supported Graphics File Formats}

Supported formats are, PNG, JPEG, \lnum{JPEG2000}, BMP, PDF, and \MP\ generated
EPS. All other format images, such as SVG and PostScript, must be converted to
other format supported by \dvipdfmx\ before inclusion.
The \option{-D} option, as in \dvipdfm, can be used for filtering images.

\subsection{PNG and JPEG}

PNG and JPEG are supported as in \dvipdfm\ but it is mostly rewritten.

PNG support includes most of important features of PNG such as color palette,
transparency, 16bit bit-depth color, embedded ICC Profiles, and calibrated
colors specified by \code{gAMA} and \code{cHRM} chunks. XMP Metadata is also
supported. Predictor filter may be applied for Flate compression which result in
better compression for larger images. Application of the predictor filter
sometimes makes compression speed very slow. Please try \option{-C 0x20}
(disable predictor filters) command line option to check if slowness is due to
the predictor filter.

JPEG is relatively well supported. \dvipdfmx\ supports embedded ICC Profiles
and CMYK color. Embedded XMP metadata is also supported.
\dvipdfmx\ uses JFIF or Exif data to determin image's physical size.

\subsection{PDF and ``MPS''}

PDF inclusion is supported as in \dvipdfm, with various important enhancement
over \dvipdfm\ for robust inclusion. \dvipdfmx\ can handle cross-reference
streams and object streams introduced in \lnum{PDF-1.5}.
\dvipdfmx\ also supports inclusion of PDF pages other than the first page.
However, tagged PDF may cause problems and annotations are not kept.

For \MP\ generated EPS files, multi-byte encoding support is added.
\dvipdfmx\ also supports ``\MP\ mode'': When \dvipdfmx\ is invoked with
\option{-M} option, it enters in \MP\ mode and processes a \MP\
generated EPS file as input.%
\footnote{\code{prologue} must be set to \code{2}.}

\subsection{Additional Supported Formats}

BMP is supported but limited to uncompressed or RLE-compressed raster
images. Extensions are not (won't be) supported.

\lnum{JPEG2000} is also supported. It is restricted to JP2 and JPX baseline
subset as required by PDF spec. It is not well supported and still in
an experimental stage. J2C format and transparency are not supported.


\subsection{Image Cache}

Chaching of images generated via filtering command specified with \option{-D}
option is supported. It solves the problems that image inclusion becomes very
slow when external filtering program such as GhostScript is invoked each time
images are included.

Use \option{-I} option to enable this feature:
\begin{lstlisting}
-I 24
\end{lstlisting}
where the integer represents the life of cache files, 24 hours in this example.


\section{DVI Specials}\label{SEC:specials}

\dvipdfmx\ is mostly compatible to \dvipdfm.
Several DVI \code{special} commnads are added for more flexible PDF generation:
Creation of arbitrary stream object, controlling \dvipdfmx\ behavior, and some
specials which might be useful for graphics drawing packages.


\subsection{Additions to \dvipdfm's \code{pdf:} Special}

The \code{pdf:fstream} special is added, which enables creation of PDF stream
object from an existing file.
\begin{lstlisting}
pdf:fstream @identifier (filename) <<dictionary>>
\end{lstlisting}
where identifier and filename (specified as a PDF string object) are
mandatory and a dictionary object which is to be added to the stream
dictionary following the filename is optional.

For examples, to incorporate a XMP Metadata,
\begin{lstlisting}
\special{pdf:fstream @xmp (test.xmp) <<
    /Type /Metadata
    /Subtype /XML
>>}
\special{pdf:put @catalog << /Metadata @xmp >>}
\end{lstlisting}

Similary, \code{pdf:stream} special can be used to create a PDF stream
object from a PDF string instead of a file:
\begin{lstlisting}
\special{pdf:stream @MyPattern
    (0.16 0 0 0.16 0 0 cm 4 w
     50 0 m 50 28 28 50 0 50 c S 100 50
     m 72 50 50 28 50 0 c S
     50 100 m 50 72 72 50 100 50 c S
     0 50 m 28 50 50 72 50 100 c S
     100 50 m 100 78 78 100 50 100 c 22 100 0 78 0 50 c
     0 22 22 0 50 0 c 78 0 100 22 100 50 c S
     0 0 m 20 10 25 5 25 0 c f 0 0 m 10 20 5 25 0 25 c f
     100 0 m 80 10 75 5 75 0 c f
     100 0 m 90 20 95 25 100 25 c f
     100 100 m 80 90 75 95 75 100 c f
     100 100 m 90 80 95 75 100 75 c f
     0 100 m 20 90 25 95 25 100 c f
     0 100 m 10 80 5 75 0 75 c f
     50 50 m 70 60 75 55 75 50 c 75 45 70 40 50 50 c f
     50 50 m 60 70 55 75 50 75 c 45 75 40 70 50 50 c f
     50 50 m 30 60 25 55 25 50 c
     25 45 30 40 50 50 c f
     50 50 m 60 30 55 25 50 25 c 45 25 40 30 50 50 c f)
    <<
        /BBox [0 0 16 16]
        /PaintType 2
        /PatternType 1
        /Resources <<
            /ProcSet [/PDF]
        >>
        /TilingType 3
        /Type /Pattern
        /XStep 16
        /YStep 16
    >>
}
\end{lstlisting}
The above example defines a tiling pattern. With the following code:
\begin{lstlisting}
\special{pdf:put @resources
    <<
        /ColorSpace << /CS01 [/Pattern /DeviceRGB] >>
        /Pattern << /PT01 @MyPattern >>
    >>
}
\special{pdf:content
    q 0.8 0.3 0.3 RG /CS01 cs 0.8 0.3 0.3 /PT01 scn
    0 0 240 80 re f
}
\end{lstlisting}
it draws a box filled with a tiling pattern as shown in
Figure~\ref{FIG:pattern}.

\special{pdf:stream @MyPattern
    (0.16 0 0 0.16 0 0 cm 4 w
     50 0 m 50 28 28 50 0 50 c S 100 50
     m 72 50 50 28 50 0 c S
     50 100 m 50 72 72 50 100 50 c S
     0 50 m 28 50 50 72 50 100 c S
     100 50 m 100 78 78 100 50 100 c 22 100 0 78 0 50 c
     0 22 22 0 50 0 c 78 0 100 22 100 50 c S
     0 0 m 20 10 25 5 25 0 c f 0 0 m 10 20 5 25 0 25 c f
     100 0 m 80 10 75 5 75 0 c f
     100 0 m 90 20 95 25 100 25 c f
     100 100 m 80 90 75 95 75 100 c f
     100 100 m 90 80 95 75 100 75 c f
     0 100 m 20 90 25 95 25 100 c f
     0 100 m 10 80 5 75 0 75 c f
     50 50 m 70 60 75 55 75 50 c 75 45 70 40 50 50 c f
     50 50 m 60 70 55 75 50 75 c 45 75 40 70 50 50 c f
     50 50 m 30 60 25 55 25 50 c
     25 45 30 40 50 50 c f
     50 50 m 60 30 55 25 50 25 c 45 25 40 30 50 50 c f)
    <<
        /BBox [0 0 16 16]
        /PaintType 2
        /PatternType 1
        /Resources <<
            /ProcSet [/PDF]
        >>
        /TilingType 3
        /Type /Pattern
        /XStep 16
        /YStep 16
    >>
}%
\begin{figure}
\centering
\raisebox{-80bp}[0bp][80bp]{\makebox[240bp][l]{\special{pdf:put @resources
    <<
        /ColorSpace << /CS01 [/Pattern /DeviceRGB] >>
        /Pattern << /PT01 @MyPattern >>
    >>
}%
\special{pdf:content
    0.8 0.3 0.3 RG /CS01 cs 0.8 0.3 0.3 /PT01 scn
    0 0 240 80 re f
}}}%
\caption{An example of tiling pattern.}\label{FIG:pattern}
\end{figure}

\code{pdf:mapline} and \code{pdf:mapfile} specials can be used to append a
fontmap entry or to load a fontmap file:
\begin{lstlisting}
pdf:mapline foo unicode bar
pdf:mapfile foo.map
\end{lstlisting}

\code{pdf:majorversion} and \code{pdf:minorversion} specials can be used to
specify major and minor version of output PDF.
\begin{lstlisting}
pdf:minorversion 3
\end{lstlisting}

To protect output PDF with encryption, use \code{pdf:encrypt} special
\begin{lstlisting}
pdf:encrypt userpw (foo) ownerpw (bar) length 128 perm 20
\end{lstlisting}
where user-password and owner-password must be specified as PDF string objects.
(which can be empty) Numbers specifying key-length and permission flags here
must be decimal numbers. See, section of ``\hyperref[SEC:encryption]{Encryption
Support}'' for a brief description of permission flags.

Other notable extensions are \code{code}, \code{bcontent}, and
\code{econtent}. The \code{code} special can be used to insert raw PDF graphics
instructions into output page content stream. It is different from \dvipdfm's
\code{content} special in that it does not enclose contents with a \code{q}
and \code{Q} (save-restore of graphics state) pair.
A typical usage of this special is:
\begin{lstlisting}
\special{pdf:code q 1 Tr}
text goes here...
\special{pdf:code Q}
\end{lstlisting}
which changes text rendering mode to 1, as shown in Figure~\ref{FIG:trmode} for
example.

\begin{figure}
\centering
\mbox{\special{pdf:code q 1 w 1 Tr}%
{\fontsize{200pt}{200pt}\selectfont\textchi}%
\special{pdf:code Q}}%
\caption{A character drawn in the PDF text rendering mode 1.}%
\label{FIG:trmode}
\end{figure}

Be careful on using this special as it is very easy to generate
broken PDF files. The \code{bcontent} and \code{econtent} pair is fragile and
often incompatible to other groups of special commands. It is not
always guaranteed to work as `expected'.

\subsection{Dvipdfmx Extensions}

A new special \code{dvipdfmx:config} was introduced in \TeX Live 2016 which
makes it possible to invoke a command line option. Most single letter command
line options except \option{D} are supported. For examples,
\begin{lstlisting}
dvipdfmx:config C 0x10
\end{lstlisting}
sets the \dvipdfmx's compatibility flag.

\subsection{DVI Special Examples}

The following code reads \TeX\ source file and creates a stream object named
as \code{@SourceFile}, then creates a file attachment annotation.
\marginnote{%
\special{pdf:fstream @SourceFile (\jobname.tex)}%
\special{pdf:ann width 10bp height 20bp
   << /Type /Annot
      /Subtype /FileAttachment
      /FS <<
            /Type /Filespec
            /F    (\jobname.tex)
            /EF   << /F @SourceFile >>
          >>
      /Name     /PushPin
      /C        [0.8 0.2 0.2]
      /T        (The dvipdfmx project team)
      /Subj     (The Dvipdmfx User's Manual)
      /Contents (XeLaTeX source file of this manual.)
   >>
}}%
\begin{lstlisting}
\special{pdf:fstream @SourceFile (\jobname.tex)}%
\special{pdf:ann width 10bp height 20bp
   << /Type /Annot
      /Subtype /FileAttachment
      /FS <<
            /Type /Filespec
            /F    (\jobname.tex)
            /EF   << /F @SourceFile >>
          >>
      /Name     /PushPin
      /C        [0.8 0.2 0.2]
      /T        (The dvipdfmx project team)
      /Subj     (The Dvipdfmx User's Manual)
      /Contents (XeLaTeX source file of the manual.)
   >>
}
\end{lstlisting}
An Example of separation color space:
\special{pdf:stream @TintTransform1
  ({0 exch dup 0.62 mul exch 0})
  <<  /FunctionType 4
      /Domain [ 0.0 1.0 ]
      /Range  [ 0.0 1.0 0.0 1.0 0.0 1.0 0.0 1.0 ]
  >>
}%
\special{pdf:stream @TintTransform2
  ({dup 0.78 mul exch dup 0.05 mul exch 0.71 mul 0})
  <<  /FunctionType 4
      /Domain [ 0.0 1.0 ]
      /Range  [ 0.0 1.0 0.0 1.0 0.0 1.0 0.0 1.0 ]
  >>
}%
\special{pdf:obj @Orange [
    /Separation /Orange /DeviceCMYK @TintTransform1
  ]
}%
\special{pdf:obj @Green [
    /Separation /Green /DeviceCMYK @TintTransform2
  ]
}%
\begin{center}
\mbox{%
\special{pdf:put @resources <<
    /ColorSpace << /CS01 @Orange /CS02 @Green >>
  >>
}%
\fontsize{40pt}{40pt}\selectfont
\special{pdf:code q /CS01 cs 1.0 scn}Orange\special{pdf:code Q} and
\special{pdf:code q /CS02 cs 1.0 scn}Green\special{pdf:code Q}
}
\end{center}
\begin{lstlisting}
\special{pdf:stream @TintTransform1
  ({0 exch dup 0.62 mul exch 0})
  <<  /FunctionType 4
      /Domain [ 0.0 1.0 ]
      /Range  [ 0.0 1.0 0.0 1.0 0.0 1.0 0.0 1.0 ]
  >>
}
\special{pdf:stream @TintTransform2
  ({dup 0.78 mul exch dup 0.05 mul exch 0.71 mul 0})
  <<  /FunctionType 4
      /Domain [ 0.0 1.0 ]
      /Range  [ 0.0 1.0 0.0 1.0 0.0 1.0 0.0 1.0 ]
  >>
}
\special{pdf:obj @Orange [
    /Separation /Orange /DeviceCMYK @TintTransform1
  ]
}
\special{pdf:obj @Green [
    /Separation /Green /DeviceCMYK @TintTransform2
  ]
}
\mbox{%
  \special{pdf:put @resources <<
      /ColorSpace << /CS01 @Orange /CS02 @Green >>
    >>
  }%
  \special{pdf:code q /CS01 cs 1.0 scn}
  Orange
  \special{pdf:code Q}
  and
  \special{pdf:code q /CS02 cs 1.0 scn}
  Green
  \special{pdf:code Q}
}
\end{lstlisting}
Transparency example:
\special{pdf:obj @gs01 <<
  /Type /ExtGState /CA 0.6 /ca 0.6 /AIS false
>>}%
\begin{center}
\mbox{%
  \special{pdf:put @resources <<
    /ExtGState << /GS01 @gs01 >>
  >>}%
  \fontsize{200pt}{200pt}\selectfont
  \special{pdf:code q 1.0 0.8 0.2 rg}
  \textalpha%
  \special{pdf:code /GS01 gs 0.4 0.8 0.4 rg}%
  \hspace{-0.3em}\textbeta%
  \hspace{-0.3em}\raisebox{0.5ex}{%
    \special{pdf:code 0.4 0.4 0.8 rg}%
    \textpi%
  }
  \special{pdf:code Q}%
}
\end{center}
\begin{lstlisting}
\special{pdf:obj @GS01 <<
  /Type /ExtGState /CA 0.6 /ca 0.6 /AIS false
>>}%
\mbox{%
  \special{pdf:put @resources <<
    /ExtGState << /GS01 @GS01 >>
  >>}%
  \special{pdf:code q 1.0 0.8 0.2 rg}%
  \textalpha%
  \special{pdf:code /GS01 gs 0.4 0.8 0.4 rg}%
  \hspace{-0.3em}\textbeta%
  \hspace{-0.3em}\raisebox{0.5ex}{%
    \special{pdf:code 0.4 0.4 0.8 rg}%
    \textpi%
  }%
  \special{pdf:code Q}%
}
\end{lstlisting}
where \code{CA} and \code{ca} represent opacity of stroke and fill color
individually.

\section{Font Mapping}

Syntax of fontmap file is basically the same as \dvipdfm. There are few
extensions in \dvipdfmx. In addition to 8-bit \code{enc} files and
keyword \code{builtin} and \code{none}, \dvipdfmx\ accepts CMap name and
the keyword \code{unicode} in the encoding field.

This section is completely irrevant to \XeTeX\ users.

\subsection{Extended Syntax and Options}

Few options are available in \dvipdfmx\ in addition to the original
dvipdfm's one. All options that makes \dvipdfmx\ to use unembedded
fonts are deprecated as by using them makes \dvipdfmx\ to create PDF
files which can be not compliant to the ISO standards.

\subsubsection{SFD Specification}

For bundling up fonts split into multiple subfonts via SFD back into
a single font, dvipdfmx supports an extended sytax of the form
\begin{lstlisting}
tfm_name@SFD@  encoding  filename  options
\end{lstlisting}

A typical example looks like:
\begin{lstlisting}
gbsn@EUC@  GB-EUC-H  gbsn00lp
\end{lstlisting}

where TFMs \code{gbsn00}, \code{gbsn01}, \code{gbsn02}... are mapped into a
single font named \code{gbsn00lp} via the rule described in the SFD file
\code{EUC}.

\subsubsection{TrueType Collection Index}

TrueType Collection index number can be specified with \code{:n:}
in front of TrueType font name:
\begin{lstlisting}
min10  H  :1:mincho
\end{lstlisting}

In this example, the option \code{:1:} tells \dvipdfmx\ to select first
TrueType font from the TTC font \code{mincho.ttc}. Alternatively, the
\option{-i} option can be used in the option field to specify TTC index:
\begin{lstlisting}
min10  H  mincho  -i 1
\end{lstlisting}

\subsubsection{Non-embedding Switch}

\deprecated{Use of this option is deprecated.}
\noindent{}The character \code{!} in front of the font name can be used to
indicate that the font shall not be embedded. This feature greatly reduces the
size of the final PDF output, but the PDF file may not be viewed exactly in
other systems on which appropriate fonts are not installed.
\bigskip

\noindent{}NOTE: \dvipdfmx\ always converts input encodings to CIDs and then
uses Identity CMaps\footnote{Predefined CMaps \code{Identity-H} and
\code{Identity-V} for the identity mapping.}
in the output PDF. However, \lnum{ISO~32000-1:2008} describes as
\begin{quoting}
The Identity-H and Identity-V CMaps shall not be used with a non-embedded font.
Only standardized character sets may be used.
\end{quoting}
which had never appeared in Adobe's PDF References. This makes all PDF files
generated by \dvipdfmx\ with non-embedded CID-keyed fonts non-compliant to
the ISO standards.

\subsubsection{`Standard' CJK Fonts}

\deprecated{This feature is deprecated.}
\noindent{}Use of this feature shall be avoided for new documents. It is
described here since it might still be useful for some situations.

\dvipdfmx\ recognizes several `Standard' CJK fonts although there are no such
notion in PDF. In older days where there were not so many freely available CJK
fonts, it was sometimes useful to create PDF files without embedded fonts and
let PDF viewers or printers to use substitute fonts (tend to be higher quality)
installed in their systems. \dvipdfmx\ `knows' several fonts which might be
available in PostScript printers and PDF applications such as Acrobat Reader,
and uses them without actually having it.
See, Table~\ref{TABLE:StdCJKFont}, for the list of available `Standard' CJK
fonts.

\begin{table}
    \centering
    \begin{tabular}{lll}\hline
    Character Collection & Font Family & Description \\ \hline\hline
    Adobe-Japan1 & Ryumin-Light & PS printers \\
        & GothicBBB-Medium & \\
    Adobe-CNS1 & MHei-Medium-Acro & Acrobat Reader 4 \\
        & MSung-Light-Acro & \\
    Adobe-GB1 & STSong-Light-Acro & \\
        & STHeiti-Regular-Acro & \\
    Adobe-Japan1 & HeiseiMin-W3-Acro & \\
        & HeiseiKakuGO-W5-Acro & \\
    Adobe-Korea1 & HYGoThic-Medium-Acro & \\
        & HYSMyeongJo-Medium-Acro & \\
    Adobe-CNS1 & MSungStd-Light-Acro & Acrobat Reader 5 \\
    Adobe-GB1 & STSongStd-Light-Acro & \\
    Adobe-Korea1 & HYSMyeongJoStd-Medium-Acro \\
    Adobe-CNS1 & AdobeMingStd-Light-Acro & Adobe Reader 6 \\
    Adobe-GB1 & AdobeSongStd-Light-Acro & \\
    Adobe-Japan1 & KozMinPro-Regular-Acro & \\
        & KozGoPro-Medium-Acro & \\
    Adobe-Korea1 & AdobeMyungjoStd-Medium-Acro & \\
    Adobe-CNS1 & AdobeHeitiStd-Regular & Adobe Reader 7 \\
    Adobe-Japan1 & KozMinProVI-Regular & Adobe Reader 8\\
    \hline
    \end{tabular}
    \caption{List of available `Standard' CJK font. Most of them are
    available as a part of Adobe Asian Font Packs for each versions of
    Adobe or Acrobat Reader.}\label{TABLE:StdCJKFont}
\end{table}

Only fixed-pitch glyphs (i.e., quarter, third, half, and full widths) are
supported for those fonts.

\subsubsection{Stylistic Variants}

\deprecated{Use of this option is deprecated.}
\noindent{}Keywords \code{,Bold}, \code{,Italic}, and \code{,BoldItalic} can be
used to create synthetic bold, italic, and bolditalic style variants from other
font using PDF viewer's (or OS's) function.
\begin{lstlisting}
jbtmo@UKS@      UniKSCms-UCS2-H :0:!batang,Italic
\end{lstlisting}

Availability of this feature highly depends on the implementation of PDF
viewers. This feature is usually not supported for embedded fonts.
Notice that this option automatically disables font embedding thus
use of it is deprecated.

\subsection{Specifying Unicode Plane}

As there are no existing 3-bytes or 4-bytes TFM formats, the only way to use
Unicode characters other than the BMP is to map code range 0-65535 to different
planes via (e.g., to plane 1) \option{-p 1} fontmap option. This option is
available only when \code{unicode} is specified in the encoding field.

\subsection{OpentType Layout Feature}

OpenType Layout Feature fontmap options mentioned below are only meaningful
when \code{unicode} is specified in the encoding field.

With the \option{-w} option, writing mode can be specified.
\option{-w 1} denotes the font is for vertical writing. It automatically
enables an OpentType Layout Feature related to vertical writing, namely,
\code{vert} or \code{vrt2}, to choose proper glyphs for vertical text.

The \option{-l} option can be used to enable various OpenType Layout GSUB
Features. For examples, \option{-l jp04}
enables \code{jp04} feature to select \lnum{JIS2004} forms for Kanjis.
Features can be specified as a ``:'' separated list of OpenType Layout
Feature tags like \option{-l vkna:jp04}.
Script and language may be additionally specified as
\option{-l kana.JAN.ruby}.

An example can be
\begin{lstlisting}
uprml-v  unicode  SourceHanSerifJP-Light.otf  -w 1 -l jp90
\end{lstlisting}
which declares that font should be treated as for vertical writing and
use \lnum{JIS1990} form for Kanjis. (See, Figure~\ref{FIG:jp90} for an example)

\begin{figure}
\centering
\jpzerofourexamples\hspace{30pt}\jpninezeroexamples%
\caption{\lnum{JIS2004} vs. \lnum{JIS1990} form.}\label{FIG:jp90}
\end{figure}

This feature is limited to the single substitution, there are no way to select
a glyph from multiple candidates, such as in \code{aalt}, and specifying
general many-to-many glyph substitutions does not take effect.

\section{Encryption Support}\label{SEC:encryption}

\dvipdfmx\ offers basic PDF password security support including
256-bits AES encryption. Only ``Standard'' security handler is supported and
public-key security handlers are currently not supported.
Encryption is enabled by \option{-S} command line option.

When encrypting the document, up to two passwords can be specified:
an owner password and a user password. If a user attempts to open an encrypted
document that has a user password, PDF applications prompt for a password.
Correctly supplying either password enables the user to open the document to
display or to access to the contents.
Depending on which password (user or owner) was supplied, additional operations
allowed for an opened document is determined; full access for users who opened
the document with the correct owner password or additional operations
controlled by permission flags supplied by the owner of the document for users
who opened the document with the correct user password.

Access permision flags can be specified via the \option{-P} option. Each bits
of the (unsigned) integer number given to this option represents user access
permissions;
e.g., bit position 3 for allowing ``print'', 4 for ``modify the contents'',
5 for ``copy or extract text'', and so on.
\begin{table}[b]
    \centering
    \begin{tabular}{lp{8.3cm}}\hline
        Bit Position & Meaning \\ \hline\hline
        3 & Print the document. \\
        4 & Modify the contents of the document. \\
        5 & Copy or extract text and graphics from the document. \\
        6 & Add or modify text annotations, fill in interactive form fields.
            Creation and modification of interactive form field is also
            allowed if bit 4 is set.\\
        \hline
    \end{tabular}
    \caption{Flag bits and their short explaination for the Revision 2
     Standard Security Handler.}
\end{table}
For examples,
\begin{lstlisting}
dvipdfmx -S -P 0x34 foo.dvi
\end{lstlisting}
allows printing, copying and extraction of text, and adding and modifying
text annotation and filling in interactive form fields (but disallows
modification of the contents of the document).

The \option{-K} option can be used to specify the encryption key length.
The key length must be multiple of 8 in the range 40 to 128, or 256 (for PDF
version 1.7 plus Adobe Extension or forthcoming PDF version 2.0).

Password will be asked when encryption is enabled. It may not work well on
Windows platforms. Use the \code{pdf:encrypt} special instead of command line
options in this case.

The default values for \option{K} is 40 and for \option{-P} is \code{0x003C0}.

\section{Other Improvements}

This section briefly describes other improvements made for \dvipdfmx.

\subsection{Extended Glyph Name Syntax}

\dvipdfmx\ accepts the following syntax for glyph names in \code{enc} files:
\code{uni0130}, \code{zero.onum} and \code{T\_h.liga}.
Each represents a glyph accessed with Unicode value \code{U+0130},
oldstyle number for zero and ``Th'' ligature accessed via OpenType
Layout GSUB Feature \code{onum} and \code{liga} respectively.
Note that \dvipdfmx\ does not understand glyph names which directly
use glyph indices such as \code{index0102} or \code{gid2104}, since those
indices are private to each font.

When \dvipdfmx\ encounters a glyph name, e.g., \code{T\_h.liga}, it first looks
for OpenType \code{post} table if such glyph exists; if it exists, then
\dvipdfmx\ simply uses \code{post} talbe for mapping glyph name to glyph index;
if not, \dvipdfmx\ tries to convert \code{T\_h} to Unicode sequence (U+0054
U+0068 in this example) via the AGL mapping; then, OpenType cmap table is used
to further converting resulting Unicode sequence to a sequence of glyph indices;
finally, OpenType Layout Feature \code{liga} is applied to get desired glyph.


\section{Incompatible Changes}\label{SEC:compatibility}

There are various minor incompatible changes to \dvipdfm.

The \option{-C} command line option  may be used for compatibility to
\dvipdfm\ or older versions of \dvipdfmx. The \option{-C} option takes flags
meaning
\begin{itemize}
    \item bit position 2: Use semi-transparent filling for tpic shading
    command, instead of opaque gray color. (requires PDF 1.4)
    \item bit position 3: Treat all CID-keyed font as fixed-pitch font. This is
    only for compatibility.
    \item bit position 4: Do not replace duplicate fontmap entries.
    \dvipdfm\ behavior.
    \item bit position 5: Do not optimize PDF destinations. Use this if you
    want to refer from other files to destinations in the current file.
    \item bit position 6: Do not use predictor filter for Flate compression.
    \item bit position 7: Do not use object stream.
\end{itemize}

The remap option \option{-r} in fontmaps is no longer supported and is
silently ignored. The command line option \option{-e} to disable partial
(subset) font embedding is not supported.

\section{Font Licensing and Embedding}

In OpenType format, information regarding how a font should be treated
when creating documents can be recorded.%
\footnote{See, `` \href{http://www.microsoft.com/typography/otspec/os2.htm}{OpenType Sepcification: OS/2 -- OS/2 and Windows Metrics Table}''.}
\dvipdfmx\ uses this information to decide whether embedding font is permitted.

This font embedding information is indicated by a flag called
\code{fsType}; each bit representing different restrictions on font
embedding.
If multiple flag bits are set in \code{fsType}, the least restrictive
license granted takes precedence in \dvipdfmx.
The \code{fsType} flag bits recognized by \dvipdfmx\ is as follows:
\begin{itemize}
    \item Installable embedding
    \item Editable embedding
    \item Embedding for Preview \& Print only
\end{itemize}
\dvipdfmx\ give the following warning message for fonts with `Preview \&
Print only' setting:
\begin{verbatim}
  This document contains 'Preview & Print' only licensed font
\end{verbatim}

For fonts with this type of licensing, font embedding is allowed solely for the
purpose of (on-screen) viewing and/or printing; further editing of the document
or extracting embedded font data for other purposes are not allowed.
One way to ensure this condition is to protect your document with a non-empty
password.

All other flags are treated as more restrictive license than any of
the above flags and treated as ``No embedding allowed''; e.g., if both
of the editable-embedding flag and unrecognized license flag is set,
the font is treated as editable-embedding allowed, however, if only
unrecognized flags are set, the font is not embedded.

Embedding flags are preserved in embedded font if the font is embedded
as a TrueType font or a CIDFontType2 CID-keyed font.
For all font embedded as a PostScript font (Type1C and CIDFontType0
CID-keyed font), they are not preserved.
Only \code{Copyright} and \code{Notice} in the FontInfo dictionary are
preserved in this case.

Some font vendors put different embedding restrictions for different
condition; e.g., font embedding might be not permitted for commercial
materials unless you acquire ``commercial license'' separately.
Please read EULA carefully before making decision on font usage.

See, for examples,
\href{http://www.adobe.com/products/type/font-licensing/font-embedding-permissions.html}{Adobe's site on font embedding permissions}
for fonts in the Adobe Type Library.
Microsoft also has a
\href{http://www.microsoft.com/typography/RedistributionFAQ.mspx}{FAQ page on Font Redistribution}.

For Japanese font in general, embedding permission tend to be somewhat
restrictive. Japanese users should read the statement regarding font
embedding from Japan Typography Association (in Japanese):\medskip

\url{http://www.typography.or.jp/act/morals/moral4.html}
\medskip

\dvipdfmx\ does not support full embedding. Only subset embedding is supported.

\renewcommand{\refname}{Further Reading}
\begin{thebibliography}{99}
\bibitem{ADOBE} Adobe's PDF References and a free copy of
\lnum{ISO 32000-1:2008} standard are available from
``\href{http://www.adobe.com/devnet/pdf.html}{PDF Technology Center}''
on \href{http://www.adobe.com/devnet.html}{Adobe Developer Connection}.
\bibitem{MICROSOFT} The OpenType Specification is available from Microsoft's
site:
``\href{http://www.microsoft.com/en-us/Typography/OpenTypeSpecification.aspx}%
{OpenType Specification}''.
\bibitem{CHOF} An article regarding DVI specials: Jin-Hwan Cho,
``\href{http://www.tug.org/TUGboat/tb30-1/tb94cho.pdf}{DVI specials for PDF generation}'',
TUGboat, 30(1):6-11, 2009.
\end{thebibliography}

\section*{GNU Free Documentation License}\label{SEC:FDL}

This document is distributed under the term of the GNU Free Documentation
License. See, the attached file for copying conditions.%
\marginnote{%
\special{pdf:fstream @fileobj (fdl-1.3.txt)}%
\special{pdf:ann width 10bp height 20bp
   << /Type /Annot
      /Subtype /FileAttachment
      /FS <<
            /Type /Filespec
            /F    (fdl-1.3.txt)
            /EF   << /F @fileobj >>
          >>
      /Name /PushPin
      /C [0.8 0.2 0.2]
      /T (Free Software Foundation, Inc.)
      /Subj (GNU Free Documentation License)
      /Contents (Plain text version of the GNU Free Documentation License.)
   >>
}}%

Or, in case that PDF viewers can not extract attached files, please visit the
following site:
\medskip

\url{http://www.gnu.org/licenses/fdl.html}


\end{document}