texlive[55614] Master/texmf-dist/doc/dvipdfmx: update dvipdfmx manual
commits+kakuto at tug.org
commits+kakuto at tug.org
Sun Jun 21 04:09:16 CEST 2020
Revision: 55614
http://tug.org/svn/texlive?view=revision&revision=55614
Author: kakuto
Date: 2020-06-21 04:09:16 +0200 (Sun, 21 Jun 2020)
Log Message:
-----------
update dvipdfmx manual (S. Hirata)
Modified Paths:
--------------
trunk/Master/texmf-dist/doc/dvipdfmx/dvipdfmx.pdf
trunk/Master/texmf-dist/doc/dvipdfmx/dvipdfmx.tex
Modified: trunk/Master/texmf-dist/doc/dvipdfmx/dvipdfmx.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/dvipdfmx/dvipdfmx.tex
===================================================================
--- trunk/Master/texmf-dist/doc/dvipdfmx/dvipdfmx.tex 2020-06-20 23:54:04 UTC (rev 55613)
+++ trunk/Master/texmf-dist/doc/dvipdfmx/dvipdfmx.tex 2020-06-21 02:09:16 UTC (rev 55614)
@@ -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 \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 @@
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 @@
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 @@
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 @@
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 @@
\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,16 +375,89 @@
\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 is mostly for supporting legacy encodings and legacy font format
-such as PostScript Type1 font. \XeTeX\ users may skip this section.
+This section gives a quick overview of \dvipdfmx's extended capabilities.
-\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.
+\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.
+
+\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'' (``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}
\keyword{PostScript CMap Resources}\footnote{See,
@@ -446,77 +528,6 @@
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 @@
\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 @@
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 @@
\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
More information about the tex-live-commits
mailing list.