diff options
author | Akira Kakuto <kakuto@fuk.kindai.ac.jp> | 2020-06-21 02:09:16 +0000 |
---|---|---|
committer | Akira Kakuto <kakuto@fuk.kindai.ac.jp> | 2020-06-21 02:09:16 +0000 |
commit | 98de3c8419e0e42f940773ac798df9ae69ef237d (patch) | |
tree | b474e6c75a69198a5d5306bd61ced5c9edc9c981 | |
parent | b8e5e4054f7c199ca4e0bd350e62159017d9749d (diff) |
update dvipdfmx manual (S. Hirata)
git-svn-id: svn://tug.org/texlive/trunk@55614 c570f23f-e606-0410-a88d-b1316a301751
-rw-r--r-- | Master/texmf-dist/doc/dvipdfmx/dvipdfmx.pdf | bin | 261192 -> 267377 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/dvipdfmx/dvipdfmx.tex | 232 |
2 files changed, 122 insertions, 110 deletions
diff --git a/Master/texmf-dist/doc/dvipdfmx/dvipdfmx.pdf b/Master/texmf-dist/doc/dvipdfmx/dvipdfmx.pdf Binary files differindex c3f78cec082..b90f89cc973 100644 --- a/Master/texmf-dist/doc/dvipdfmx/dvipdfmx.pdf +++ b/Master/texmf-dist/doc/dvipdfmx/dvipdfmx.pdf diff --git a/Master/texmf-dist/doc/dvipdfmx/dvipdfmx.tex b/Master/texmf-dist/doc/dvipdfmx/dvipdfmx.tex index b346ef1315b..bc74c79c025 100644 --- a/Master/texmf-dist/doc/dvipdfmx/dvipdfmx.tex +++ b/Master/texmf-dist/doc/dvipdfmx/dvipdfmx.tex @@ -102,7 +102,7 @@ \begin{raggedleft} {\Huge\bfseries The Dvipdfmx User's Manual}\\[\baselineskip] \Large The Dvipdfmx Project Team\\ - December 23, 2018\par + June 7, 2020\par \end{raggedleft} \end{titlepage} @@ -116,14 +116,14 @@ 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. +and large character sets such as those 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 the OpenType Layout for finding glyph variants and vertical writing. + \item Support for OpenType and TrueType fonts, including partial support + for OpenType Layout features for glyph variants and for 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. @@ -136,7 +136,7 @@ Extensions to \dvipdfm\ include, 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. + \item Basic PDF password security support. (only for output) \end{itemize} Some important features are still missing: \begin{itemize} @@ -157,7 +157,7 @@ development sources for \TeX\ Live, see,\medskip This document, ``The \dvipdfmx\ User's Manual'', was originally prepared for \TeX\ Live 2017. Current maintainer of this document is Shunsaku Hirata. -Latest version and contact information can be found at:\medskip +The latest version and contact information can be found at:\medskip \url{http://github.com/shirat74/dvipdfm-x-doc} \medskip @@ -214,11 +214,12 @@ 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}. In addition to this, the \code{-V} option for specifying -the output PDF version now accepts the version specification of a form \code{2.0}. Try +the output PDF version now accepts the version specification of a form \code{2.0}. +Please try \begin{lstlisting} dvipdfmx --help \end{lstlisting} -for the list of command line options and their explanations. +for a (complete) list of command line options and their explanations. \begin{table} \centering @@ -235,10 +236,16 @@ for the list of command line options and their explanations. 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{-I} \textit{number} & Life of image cache in hours, relevant only when + an image not directly supported by \dvipdfmx\ is used thus an external + program is invoked to convert it to a PDF format intermediate file. + This option basically specifies how long such intermediate files are preserved + and reused. (to avoid an external program is invoked again and again whenever + \dvipdfmx\ tries to include images) + By specifying a value of \code{0}, \dvipdfmx\ erases existing cached images, + and the value \code{-1} tells \dvipdfmx\ to erase all cached images and not to + leave newly generated one. And \code{-2} indicates ``ignore image cache``. + The default value is \code{-2}.\\ \code{-M} & Process \MP\ generated PostScript file.\\ \code{-E} & Always try to embed fonts \emph{regardless of licensing}.\\ @@ -252,10 +259,12 @@ for the list of command line options and their explanations. \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. +As the primary goal of \dvipdfmx\ is to support multi-byte character encodings +and large character sets, its primary users are expected to be users of +\LaTeX\ packages for typesetting CJK languages such as H\LaTeX\ and CJK-\LaTeX, +and users of extended \TeX\ variants which is capable of handling those +languages, like \XeTeX, p\TeX, and up\TeX. +This section provides a ``Quick Guide'' for those users. \subsection{\texorpdfstring{\XeTeX}{XeTeX}} @@ -366,15 +375,88 @@ To use TrueType Arphic fonts provided by the \package{arphic-ttf} package: \end{lstlisting} Here, \code{pdf:mapline} special is used to setup a font-mapping. -\section{Auxiliary Files}\label{SEC:auxfiles} +\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 are mainly for CJK languages. However, those features are implemented in a +more generic way and hence they can be also beneficial to users who are not +involved in CJK languages. + +\subsubsection{Legacy Multi-byte Encodings} + +\dvipdfmx\ has an extensible support for multi-byte encodings by means of PostScript +CMap Resources. Just like various 8-bit encodings can be supported via \code{enc} file, +various multi-byte encodings (including custom one) can be supported by preparing +CMap files. +See, Adobe's technical notes\cite{ADOBE} for details on PostScript CMap Resources. -This section is mostly for supporting legacy encodings and legacy font format -such as PostScript Type1 font. \XeTeX\ users may skip this section. +\subsubsection{Vertical Writing} -\dvipdfmx\ has a capacity 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. +\dvipdfmx\ supports the vertical writing extension used by p\TeX\ and up\TeX. +A DVI instruction to set the writing mode is supported. The 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 an input +encoding and making output PDF files ``Unicode aware'' (``ToUnicode CMap Support''). + +\subsubsection{Unicode as Input Encoding} + +\dvipdfmx\ recognizes an additional keyword \code{unicode} in the encoding entry of +fontmap file, which declares that character code used in input DVI files for fonts +with this keyword specified should be regarded as Unicode values. Unicode support is +basically limited to the Basic Multilingual Plane (BMP) since there are no +support for code ranges that requires more than two 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 as text information. +The ToUnicode CMap is a bridge between PDF text string encodings and Unicode +encodings, and makes it possible to extract text in PDF files as +Unicode encoded strings. It is important to make resulting PDF search-able and +copy-and-past-able. Dvipdfmx supports 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 password-based authentication, and +public-key based authentication is not supported. The 256-bit AES encryption is +also supported for PDF version 1.7 and 2.0 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 \lnum{PDF-1.5} are also supported. + +\chapter{Auxiliary Files}\label{SEC:auxfiles} + +This chapter describes various auxiliary files required for supporting legacy encodings +and legacy font format such as PostScript Type1 font. +\XeTeX\ users may skip this chapter. + +\dvipdfmx\ can 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 utilize those +features. This chapter shortly describes about those auxiliary files. \subsection{PostScript CMap Resources} @@ -446,77 +528,6 @@ They should be found in the same directory as ordinary CMap files. ToUnicode Mapping files are included in the \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\cite{ADOBE} for details on PostScript CMap Resources. - -\subsubsection{Vertical Writing} - -\dvipdfmx\ supports the vertical writing extension used by p\TeX\ and up\TeX. -A DVI instruction to set the writing mode is supported. The 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 an input -encoding 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 the input DVI file. 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 as text information. -The ToUnicode CMap is a bridge between PDF text string encodings and Unicode -encodings, and makes it possible to extract text in PDF files as -Unicode encoded strings. It is important to make resulting PDF search-able and -copy-and-past-able. Dvipdfmx supports 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 password-based authentication, and -public-key based authentication is not supported. The 256-bit AES encryption is -also supported for PDF version 1.7 and 2.0 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 \lnum{PDF-1.5} are also supported. - - \chapter{Graphics}\label{SEC:graphics} \section{Image Inclusion} @@ -643,21 +654,19 @@ 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. -As there are no clear way to determine the natural extent of the graphics content -to be clipped, \dvipdfmx\ preferably try to find the \emph{crop box} to decide -image size. If there are no crop box \emph{explicitly} specified,% -\footnote{There are some accusations by Japanese \TeX\ users as -''violating the PDF spec.'' regarding this point. However, what we are -talking about is how to guess the \emph{natural} or \emph{intended} size of -images but not the default value of the PDF crop box itself.} then it -tries to refer other boundary boxes such as the \emph{art box}. If there are no -possible boundaries of the graphics content explicitly specified, the \emph{media box}, -which is the boundaries of the physical medium on which the page is to be printed, -is used as the last resort. +As there is no clear way to determine the natural extent of a graphics contents +to be clipped, \dvipdfmx\ first try to find if there is any \emph{crop box} +explicitly specified, to determine image size. If not, then it tries to refer +other boundary boxes such as the \emph{art box} which can be used for defining +the extent of the page's meaningful content as suggested by the PDF Reference.\cite{ADOBE} +If there is no such page boundaries explicitly specified, useful for estimating +the intended size of the graphics contents, the \emph{media box}, which is the +boundaries of the physical medium on which the page is to be printed, is used as +the last resort. The \code{pdf:image} special supports additional keys, ``\code{page}'' and ``\code{pagebox}''. The \code{page} key takes an integer value representing -the page number of PDF page to be included, and the \code{pagebox} takes one +the page number of the PDF page to be included, and the \code{pagebox} takes one of the keywords \code{mediabox}, \code{cropbox}, \code{artbox}, \code{bleedbox}, or \code{trimbox} for selecting page's boundary box to be used. For example, \begin{lstlisting} @@ -1049,10 +1058,13 @@ otherwise it will be ignored. A custom file identifier (the \code{ID} entry in the trailer dictionary) can be specified via \code{pdf:trailerid} special as \begin{lstlisting} -pdf:trailerid [(0123456789abcdef) (0123456789abcdef)] +pdf:trailerid [ + <00112233445566778899aabbccddeeff> + <00112233445566778899aabbccddeeff> +] \end{lstlisting} -An array of two 16-byte PDF string objects must be supplied as -a file identifier. This special command must appear on the first page. +An array of two 16-byte PDF string objects (hexadecimal notion is used in the above example) +must be supplied as a file identifier. This special command must appear on the first page. \subsubsection{Encryption} @@ -1855,7 +1867,7 @@ use of it is deprecated. \subsection{Specifying Unicode Plane} -As there are no existing TFM formats supporting 3-byte or 4-byte character +As there is no existing TFM format supporting 3-byte or 4-byte character encodings, the only way to use Unicode characters other than the BMP is to map the code range 0-65535 to different planes via (e.g., to plane 1) the \option{-p 1} fontmap option. This option is |