summaryrefslogtreecommitdiff
path: root/info/ptex-manual/ptex-guide-en.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-11-27 03:01:12 +0000
committerNorbert Preining <norbert@preining.info>2019-11-27 03:01:12 +0000
commit5142daa13e19b32afa064863e039da3afaf06e83 (patch)
treed8299dbf426b9b0e6cafacc4cbe5a6a762bf28a9 /info/ptex-manual/ptex-guide-en.tex
parentbd1c54bb99e58d8c140acb0b0a536037f96349b4 (diff)
CTAN sync 201911270301
Diffstat (limited to 'info/ptex-manual/ptex-guide-en.tex')
-rw-r--r--info/ptex-manual/ptex-guide-en.tex506
1 files changed, 443 insertions, 63 deletions
diff --git a/info/ptex-manual/ptex-guide-en.tex b/info/ptex-manual/ptex-guide-en.tex
index bbf6918839..7e7eab90ba 100644
--- a/info/ptex-manual/ptex-guide-en.tex
+++ b/info/ptex-manual/ptex-guide-en.tex
@@ -16,11 +16,12 @@
\usepackage[dvipdfmx,hyperfootnotes=false]{hyperref}
\usepackage{pxjahyper}
\usepackage{hologo}
+\usepackage{xspace}
\usepackage{makeidx}\makeindex
% common
\usepackage{ptex-manual}
-
+\let\emph=\origemph
\makeatletter
\newlist{simplelist}{description}1
\setlist[simplelist]{%
@@ -55,14 +56,14 @@
\def\pLaTeX{p\LaTeX}\def\upLaTeX{u\pLaTeX}
\def\pdfTeX{pdf\TeX}
\def\OMEGA{$\Omega$}
-\def\TL{\TeX\ Live\ }
+\def\TL{\TeX\ Live\xspace}
\def\_{\leavevmode\vrule width .45em height -.2ex depth .3ex\relax}
\frenchspacing
\begin{document}
\catcode`\<=13
-\title{\emph{Guide of \pTeX\ for developers not interested in Japanese}}
+\title{\textsf{\textbf{Guide to \pTeX\ for developers unfamiliar with Japanese}}}
\author{Japanese \TeX\ Development Community\null
\thanks{\url{https://texjp.org},\ e-mail: \texttt{issue(at)texjp.org}}}
\date{version p\the\ptexversion.\the\ptexminorversion\ptexrevision, \today}
@@ -71,7 +72,7 @@
\pTeX\ and its variants, \upTeX, \epTeX\ and \eupTeX, are all \TeX\ engines
with native Japanese support.
Its output is always a DVI file, which can be processed by several
-DVI drivers with Japanese support including {\em dvips} and {\em dvipdfmx}.
+DVI drivers with Japanese support including \emph{dvips} and \emph{dvipdfmx}.
Formats based on \LaTeX\ is called \pLaTeX\ when running on \pTeX/\epTeX,
and called \upLaTeX\ when running on \upTeX/\eupTeX.
@@ -93,7 +94,7 @@ We hope that this document helps authors of packages or classes
to proceed with supporting \pTeX\ family smoothly.
\begin{quotation}
-Note: This English edition (\jobname.pdf) is {\em not} meant
+Note: This English edition (\jobname.pdf) is \emph{not} meant
to be a complete translation of Japanese edition (ptex-manual.pdf).
For example, this document does not cover the following aspects of \pTeX:
\begin{itemize}
@@ -129,8 +130,8 @@ so we focus mainly on \epTeX/\eupTeX.
\section{Compatibility with Western \TeX}
%%% pTeX/upTeX は Knuthian TeX に対してほぼ上位互換
-\pTeX/\upTeX\ are almost uppercompatible with Knuthian \TeX,
-however, they do not pass TRIP test.
+\pTeX/\upTeX\ are almost upward compatible with Knuthian \TeX,
+however, they do not pass the TRIP test.
%%% 入力の8bitの扱いが異なる。フォントの8bitはそのまま
In \pTeX/\upTeX, input handling is different from Knuthian \TeX;
if a pair of two or more 8-bit codes matches Japanese character code,
@@ -138,16 +139,16 @@ it is regarded as one Japanese character.
There is no difference in handling 8-bit TFM font.
%%% e-pTeX/e-upTeX は e-TeX に対してほぼ上位互換
-\epTeX/\eupTeX\ are almost uppercompatible with \eTeX,
+\epTeX/\eupTeX\ are almost upward compatible with \eTeX,
however, input handling is similar to \pTeX/\upTeX.
-It does not pass e-TRIP test.
+It does not pass the e-TRIP test.
%%% だけど e-TeX はもうなく,pdfTeX の DVI モードがあるだけ
That said, please note that ``raw \eTeX'' is unavailable anymore
in \TeX\ Live and derived distributions;
they provide a command |etex| only as ``DVI mode of \pdfTeX.''
%%% e-pTeX/e-upTeX は pdfTeX の DVI モードに対して上位互換ではない
We should note that
-\epTeX/\eupTeX\ are {\em not} uppercompatible with DVI mode of \pdfTeX,
+\epTeX/\eupTeX\ are \emph{not} upward compatible with DVI mode of \pdfTeX,
which will be discussed later in section \ref{dvi-pdftex}.
%%% LaTeX ムニャムニャ
@@ -171,7 +172,7 @@ related to the followings:
\item Adjustment for mixing horizontal and vertical texts
\end{itemize}
%%% author レベルでは LaTeX とほぼ互換,ただし例外あり
-For authors, \pLaTeX/\upLaTeX\ is almost uppercompatible with
+For authors, \pLaTeX/\upLaTeX\ are almost upward compatible with
original \LaTeX, except for the followings:
\begin{itemize}
\item Order of float objects; in \pLaTeX/\upLaTeX,
@@ -182,7 +183,7 @@ original \LaTeX, except for the followings:
% [TODO] 他にもあるか?
\end{itemize}
%%% developer レベルでは pdfTeX 拡張や pLaTeX カーネルでムニャムニャ
-For developers, additional cares may be needed,
+For developers, additional care may be needed,
for changes in the kernel macros and/or absence of \pdfTeX\ features.
%%% 際立った pTeX 系列の特徴
@@ -192,7 +193,7 @@ The most important characteristics of \pTeX/\upTeX\ can be
summarized as follows:
%%% 欧文と和文が別個に存在する・縦組がある
\begin{itemize}
- \item Japanese characters are interpret and handled completely apart from
+ \item Japanese characters are interpreted and handled completely apart from
Western characters.
\item Texts can be aligned vertically, called ``tate-gumi'' (縦組).
The horizontal alignment of texts is called ``yoko-gumi'' (横組),
@@ -211,20 +212,83 @@ summarized as follows:
\section{Output format --- DVI}
%%% DVI だけ
-The output of \pTeX/\upTeX\ is always a DVI file.
+The output of \pTeX\ family is always a DVI file.
+This is in contrast to the mainstream of \pdfTeX\ in the Western \TeX\ world.
+
+In case you are not familiar with DVI output processing,
+first we give some general notice on how to get a ``correct'' output
+using \LaTeX\ in DVI mode.
+
+\begin{itemize}
+ \item The DVI format is, as its name suggests, inherently driver-independent.
+ However, some \LaTeX\ packages (\Pkg{graphicx}, \Pkg{color}, \Pkg{hyperref} etc.)
+ embed some \.{special} commands into the DVI, which can be interpreted later
+ by some specific DVI driver.
+ Such a DVI is no longer driver-independent, thus those are called
+ driver-dependent packages.
+ \item In almost all major \TeX\ distributions (of course including \TL),
+ the default DVI driver is set to |dvips|.
+ When you choose to process the resulting DVI file with a driver
+ other than dvips (e.g. dvipdfmx) after running \LaTeX,
+ you need to pass a proper driver option (e.g. |[dvipdfmx]|) to
+ all driver-dependent packages.
+\end{itemize}
+
+%%% 日本の DVI ドライバの状況
+Now, let's move on to the situation in Japan,
+which is slightly complicated due to historical reasons
+but may also apply to other countries:
+\begin{itemize}
+ \item There are two major conventions to pass a proper driver option
+ to all driver-dependent packages:
+ \begin{enumerate}
+ \item To give a driver option to each driver-dependent package:
+\begin{verbatim}
+\documentclass{article}
+\usepackage[dvipdfmx]{graphicx}
+\usepackage[dvipdfmx]{color}
+\end{verbatim}
+ \item To have a driver option as global:
+\begin{verbatim}
+\documentclass[dvipdfmx]{article}
+\usepackage{graphicx}
+\usepackage{color}
+\end{verbatim}
+ \end{enumerate}
+ The former convention has been used for many years since 1990s
+ when the number of driver-dependent packages was limited.
+ But in recent years (around 2010--), there are much more
+ driver-dependent packages available. Thus
+ we (Japanese \TeX\ experts) advise a global driver option
+ rather than individual package options for simplicity,
+ but not yet fully widespread.\footnote{The fact that
+ there had been a mismatch in option names
+ (\code{[dvipdfm]} vs. \code{[dvipdfmx]})
+ between packages may also have been part of it;
+ \Pkg{geometry} did not understand \code{[dvipdfmx]} option until 2018!}
+ \item Many people still see driver options as ``optional'';
+ they do without driver options unless really needed.
+ For example, the convention of having a global driver option
+ does no harm even when no driver-dependent package is used, but
+ some users choose to omit a driver option to avoid a warning:
+\begin{verbatim}
+LaTeX Warning: Unused global option(s):
+ [dvipdfmx].
+\end{verbatim}
+\end{itemize}
+
+\subsection{Extensions of DVI format in \pTeX\ family}
+
%%% pTeX の DVI は欧文の横組みだけなら普通。和文が入ると特殊,縦組ならIDも変化
-Its DVI format is completely compatible with Knuthian \TeX,
-as long as the following conditions are met:
+The DVI format output by \pTeX\ family is fully compatible with
+Knuthian \TeX, as long as the following conditions are met:
\begin{itemize}
\item No Japanese characters are typeset.
\item There is no portion of vertical text alignment.
\end{itemize}
-\subsection{Extensions of DVI format}
-
-In \pTeX/\upTeX,
-some additional DVI commands, which are defined in the
-standard \cite{dvistd0} but never used in \TeX82, are used.
+However, some additional DVI commands, which are defined in the
+standard \cite{dvistd0} but never used in \TeX82, can come out.
\begin{itemize}
\item |set2| (129), |put2| (134):
Appears in both \pTeX\ and \upTeX\ DVI.
@@ -254,37 +318,23 @@ Normally it is set to 2, as with \TeX82; however,
when |dir| (255) appears at least once in a single \pTeX/\upTeX\ DVI,
the |post_post| table of postamble contains $\mathrm{ID} = 3$.
-%%% 日本の DVI ドライバの状況
\subsection{DVI drivers with Japanese support}
-There is some DVI drivers with Japanese support.
-The most eminent drivers are {\em dvips} and {\em dvipdfmx}.
-Nowadays most of casual Japanese users are using {\em dvipdfmx} as a DVI driver.
-On the other hand, users of {\em dvips} are unignorable, especially those
+There are some DVI drivers with Japanese support.
+The most eminent drivers are \emph{dvips} and \emph{dvipdfmx}.
+Nowadays most of casual Japanese users are using \emph{dvipdfmx} as a DVI driver.
+On the other hand, users of \emph{dvips} are unignorable, especially those
working in publishing industry.
+In recent years, most of major driver-dependent packages support
+both two drivers.
-\subsubsection{Using {\em dvipdfmx}}
+\subsubsection{Using \emph{dvipdfmx}}
A DVI file which is output by \pTeX\ can be converted directly to a PDF file
using dvipdfmx.
% [TODO] Mention kanji-config-updmap for font setup
-{\em Note for casual \LaTeX\ users} ---
-when you choose to process the resulting DVI file with dvipdfmx
-after running \LaTeX\ (command |platex| or |uplatex|),
-you need to pass a proper driver option |[dvipdfmx]| for
-all driver-dependent packages, such as |graphicx| and |color|.
-This is because the default for such packages is set to |dvips| mode
-as with the original \LaTeX\ in DVI mode (command |latex|).
-For simplicity, we recommend a global driver option |[dvipdfmx]|
-as in the following example:
-\begin{verbatim}
- \documentclass[dvipdfmx,...]{article}
- \usepackage{graphicx}
- \usepackage{color}
-\end{verbatim}
-
-\subsubsection{Using {\em dvips}}
+\subsubsection{Using \emph{dvips}}
A DVI file which is output by \pTeX\ can be converted to a PostScript file
using dvips.
@@ -302,17 +352,65 @@ developed by Japanese \TeX\ Development Community.
We focus on programming aspects of \pTeX\ and its variants.
%%% レジスタの数
-\subsection{Number of registers}
+\subsection{Number of registers and marks}
\pTeX\ and \upTeX\ have exactly the same number ($=256$) of registers
-as Knuthian \TeX.
+(count, dimen, skip, muskip, box, and token) as Knuthian \TeX.
\epTeX\ and \eupTeX\ in extended mode have more registers;
there are 65536, which is twice as many as 32768 of \eTeX.
+Similarly \epTeX\ and \eupTeX\ have 65536 mark classes,
+which is twice as many as 32768 of \eTeX.
-% [TODO] まとめて 65536 個と書いて良い? レジスタの種類毎に書くべき?
+The following code presents an example of detecting the number of
+regsiters and mark classes available:
+\begin{verbatim}
+ \ifx\eTeXversion\undefined
+ % Knuthian TeX, pTeX, upTeX:
+ % 256 registers, 1 mark
+ \else
+ \ifx\omathchar\undefined
+ % e-TeX, pdfTeX (in extended mode):
+ % 32768 registers, 32768 mark classes
+ \else
+ % e-pTeX, e-upTeX (in extended mode):
+ % 65536 registers, 65536 mark classes
+ \fi
+ \fi
+\end{verbatim}
+Here a primitive \.{omathchar}, which is derived from \OMEGA, is used
+as a marker of a change file \code{fam256.ch}.\footnote{%
+There is another \pTeX-derived engine named \pTeX-ng (or Asiatic \pTeX)
+\url{https://github.com/clerkma/ptex-ng}; it is based on
+\eTeX\ and \upTeX, but currently does not adopt \code{fam256.ch}
+so it has the same number of registers and mark classes as \eTeX.}
+
+%%% 数式ファミリの数
+\subsection{Number of math families}
+
+In \pTeX\ and \upTeX,
+the number of math fonts is restricted to 16,
+each of which can contain 256 characters (same as Knuthian \TeX).
+In \epTeX\ and \eupTeX, a change file \code{fam256.ch},
+which is derived from \OMEGA, extends the upper limit to 256.
+As a consequence, \epTeX\ and \eupTeX\ allows 256 math fonts,
+each of which can contain 256 characters.\footnote{\OMEGA\ allows
+256 math fonts, each of which can contain 65536 characters.}
+
+For \pLaTeX/\upLaTeX\ users to use more than 16 math fonts,
+it is necessary to use macros which exploit \OMEGA-derived primitives
+such as \.{omathchar}.
+Recent (u)\pLaTeX\ (since 2016/11/29) partially supports this,
+and the maximum number of math alphabets that can be defined by
+|\DeclareMathAlphabet| is extended to 256 (|\e@mathgroup@top|)
+without needing any extension package.
+However, symbol fonts are restricted to 16 as
+|\DeclareMathSymbol| etc still use the standard \.{mathchar} etc.
+A simple solution to use more symbol fonts as well as math alphabets
+is to load a package \Pkg{mathfam256}\footnote{%
+\url{https://www.ctan.org/pkg/mathfam256}} though it's still preliminary.
%%% 拡張プリミティブ
-\subsection{Additional primitives}
+\subsection{Additional primitives and keywords}
% tex -ini: 322 multiletter control sequences
% ptex -ini: 366 multiletter control sequences
% uptex -ini: 374 multiletter control sequences
@@ -325,7 +423,7 @@ there are 65536, which is twice as many as 32768 of \eTeX.
Here we provide only complete lists of additional primitives
of \pTeX\ family in alphabetical order.
-Feature of each primitive can be found in Japanese edition.
+The features of each primitive can be found in Japanese edition.
% [TODO] 抜けがないか?
% [TODO] アルファベット順に正しく並んでいるか?
@@ -410,6 +508,8 @@ Knuthian \TeX; however, it is enabled in \pTeX\ family.
%%% その他の独自拡張
\subsubsection{\epTeX\ additions (available in \epTeX, \eupTeX)}
\begin{simplelist}
+ \csitem[\.{currentspacingmode} \New{191112 (\TL2020)}]
+ \csitem[\.{currentxspacingmode} \New{191112 (\TL2020)}]
\csitem[\.{epTeXinputencoding} \New{160201 (\TL2016)}]
\csitem[\.{epTeXversion} \New{180121 (\TL2018)}]
\csitem[\.{expanded} \New{180518 (\TL2019)}]
@@ -446,10 +546,18 @@ Knuthian \TeX; however, it is enabled in \pTeX\ family.
\csitem[\.{pdfstrcmp}]
\csitem[\.{pdfuniformdeviate} \New{161114 (\TL2017)}]
\csitem[\.{readpapersizespecial} \New{180901 (\TL2019)}]
+ \csitem[\.{Uchar} \New{191112 (\TL2020)}]
+ \csitem[\.{Ucharcat} \New{191112 (\TL2020)}]
\csitem[\.{vfi}]
\csitem[\texttt{fi}\index{fi=\texttt{fi}}]
\end{simplelist}
+%%% e-upTeX の独自拡張
+\subsubsection{\eupTeX\ additions (available in \eupTeX)}
+\begin{simplelist}
+ \csitem[\.{currentcjktoken} \New{191112 (\TL2020)}]
+\end{simplelist}
+
% [TODO] 引数は何で返り値は何か,expandable?
%%% (e-)TeX にあるが (e-)upTeX にないもの
@@ -462,7 +570,7 @@ One is enc\TeX\ extension, such as |\mubyte|.
The ML\TeX\ extension, such as |\charsubdef|, is included but not well-tested.
%%% コマンドラインオプションの話
-% [TODO] ptex.man1.pdf も参照
+% [TODO] Please also refer to ptex.man1.pdf
\subsection{Behavior of Western \TeX\ primitives}
@@ -478,7 +586,6 @@ other codes will give an error ``! Bad character code.''
|\sfcode|,
|\mathcode|,
|\delcode|,
- |\mathchardef|,
|\lccode|,
|\uccode|.
\end{quote}
@@ -501,6 +608,7 @@ The following primitives are extended to support Japanese characters:
\.{chardef} <control sequence>=<character code>]
In addition to 0--255, internal codes of Japanese characters are allowed.
For putting Japanese characters, a Japanese font is chosen.
+ More information can be found in \ref{chardef}.
\csitem[\.{font}, \.{fontname}, \.{fontdimen}]
% [TODO]
@@ -525,14 +633,16 @@ If either token is a control sequence,
unless the current equivalent of that control sequence
has been |\let| equal to a non-active character token.
\end{quote}
-However, this includes a lie; in the real implementation of tex.web,
+However, this includes a lie; in the real implementation of \code{tex.web},
a control sequence is considered to have a category code 0.
\end{dangerous}
\subsection{Case study}
-Based on the above knowledge, we provide some code examples
+Here we provide some code examples
which may be useful for package developers.
+% [TODO] 本当は Based on the above knowledge としたいところだが
+% 説明が圧倒的に不足しているので天下り的なコード解説…
%%% pTeX かどうかの判定
\subsubsection{Detecting \pTeX}
@@ -542,23 +652,210 @@ the safer solution for detecting \pTeX\ is
to test if a primitive |\kanjiskip| is defined.
\begin{verbatim}
\ifx\kanjiskip\undefined
- % not pTeX, upTeX, e-pTeX and e-upTeX
\else
- % pTeX, upTeX, e-pTeX and e-upTeX
+ % pTeX / upTeX / e-pTeX / e-upTeX
+ \fi
+\end{verbatim}
+
+%%% upTeX かどうかの判定
+\subsubsection{Detecting \upTeX}
+
+\upTeX/\eupTeX\ are almost upward compatible
+with \pTeX/\epTeX\ respectively, however,
+there are two major differences:
+\begin{enumerate}
+ \item Improvements in the \.{kcatcode} business,
+ mainly for better handling of Latin-1 characters and CJK tokens.
+ \item Unicode as the default internal kanji encoding,
+ for direct use of its huge character set.
+\end{enumerate}
+
+The first difference can be detected by checking if
+\.{...cjktoken} primitive is defined.
+\begin{verbatim}
+ \ifx\enablecjktoken\undefined
+ \else
+ % upTeX/e-upTeX
\fi
\end{verbatim}
-% [TODO] upTeX 系列は \enablecjktoken か \ucs か?
-% [TODO] \forcecjktoken は比較的新しい?
-% [TODO] 内部コードが uptex かどうかの判定
+The second difference can be detected by checking if
+the character \code{0x2121} (fullwidth space in JIS encoding)
+is stored as \hex{3000} internally.
+\begin{verbatim}
+ \ifx\kanjiskip\undefined
+ \else
+ \ifnum\jis"2121="3000
+ % upTeX/e-upTeX with internal Unicode
+ \else
+ % pTeX/e-pTeX
+ % or, upTeX/e-upTeX with internal EUC-JP or Shift-JIS
+ \fi
+ \fi
+\end{verbatim}
+Please note that
+the format-build setting of \verb+-kanji-internal=(sjis|euc)+ with
+\upTeX\ makes it effectively \pTeX\ regarding the character set,
+which means that only JIS~X~0208 character set is supported.
%%% pTeX のバージョン判定
+% [TODO] 何が有用?
+
+%%% 大きな定数を定義する話
+\subsubsection{Defining large integer constants}
+\label{chardef}
+
+According to \cite{topic} (Section 3.3),
+\begin{quote}
+A control sequence that has been defined with a \.{chardef} command
+can also be used as a <number>.
+This fact is used in allocation commands such as |\newbox|.
+Tokens defined with \.{mathchardef} can also be used this way.
+\end{quote}
+Here is the list of primitives which can be used for this purpose
+in \pTeX\ family:
+\begin{simplelist}
+ \csitem[\.{chardef} <control sequence>=<character code>]
+ Defines a control sequence to be a synonym for
+ \.{char} <character code>.
+
+ \csitem[\.{kchardef} <control sequence>=<character code> (for \upTeX/\eupTeX)]
+ Defines a control sequence to be a synonym for
+ \.{kchar} <character code>.
+
+ \csitem[\.{mathchardef} <control sequence>=<15-bit number>]
+ Defines a control sequence to be a synonym for
+ \.{mathchar} <15-bit number>.
+
+ \csitem[\.{omathchardef} <control sequence>=<27-bit number> (for \epTeX/\eupTeX)]
+ Defines a control sequence to be a synonym for
+ \.{omathchar} <27-bit number>.
+\end{simplelist}
+
+The first two (\.{chardef} and \.{kchardef}) are usable only when
+the integer being defined is in the range of valid character codes,
+which is not necessarily continuous (see \ref{kanji-internal}).
+The most efficient and convenient way of defining integer constants
+is as follows:
+\begin{itemize}
+ \item 0--255: \.{chardef}
+ % "FF = 255
+ \item 256--32767: \.{mathchardef}
+ % "7FFF = 32767
+ \item 32768--134217727: \.{omathchardef} (only for \epTeX/\eupTeX)
+ % "7FFFFFF = 134217727
+ \item (optional) 256--2147483647: \.{chardef} (only for \upTeX/\eupTeX)
+ % "7FFFFFFF = 2147483647 (+1 => ! Number too big.)
+\end{itemize}
+
+%%% 指定のコードの和文トークンを得る方法
+\subsubsection{Creating a Japanese character token with a specified code}
+
+Short version:
+\begin{itemize}
+ \item With \epTeX~191112 or later (\TL2020),
+ you can use expandable primitives \.{Uchar} and \.{Ucharcat}
+ \item Otherwise, use the ``\.{kansuji} trick''.
+\end{itemize}
+
+\paragraph{The ``\.{kansuji} trick''}
+This is a modified version of the ``\.{lowercase} trick''
+available in \pTeX\ family.
+
+\begin{dangerous}
+Short note on the ``\.{lowercase} trick'':
+to create a character token with a specified code value between 0--255
+with Knuthian \TeX, the ``\.{lowercase} trick'' can be used; for example,
+\begin{verbatim}
+ \begingroup
+ \lccode`\?=\mycount
+ \lowercase{\endgroup \def\X{?}}
+\end{verbatim}
+defines |\X| which expands to a character number |\mycount|
+while the \.{catcode} of |?| (\the\catcode`\?) is preserved.
+However, the trick cannot be applied to Japanese characters,
+since \pTeX\ family does not support \.{lccode} outside 0--255.
+\end{dangerous}
+
+\.{kansuji} is an expandable primitive like \.{number} or \.{romannumeral},
+and it converts an integer into its corresponding kanji notation
+called ``kansuji'' (漢数字). The important point here is that
+the number-kanji mapping can be altered by \.{kansujichar}.
+
+Example 1: equivalent to |\def\X{あ}| (JIS code \code{0x2422} is ``あ''):
+\begin{verbatim}
+ \begingroup
+ \kansujichar1=\jis"2422 \xdef\X{\kansuji1}
+ \endgroup
+\end{verbatim}
+
+Example 2: equivalent to |\def\日本{Japan}|.
+\begin{verbatim}
+ \begingroup
+ \kansujichar5=\jis"467C\relax
+ \kansujichar6=\jis"4B5C\relax
+ \expandafter\gdef\csname\kansuji56\endcsname{Japan}
+ \endgroup
+\end{verbatim}
+
+Since \.{kansujichar} accepts only Japanese character code,
+the ``\.{kansuji} trick'' and the ``\.{lowercase} trick'' should be
+used complementarily.
+
+\paragraph{\.{Uchar}, \.{Ucharcat}}
+The ``\.{kansuji} trick'' above include an assignment of \.{kansujichar}
+which is unexpandable.
+\epTeX~191112 or later (\TL2020) provides expandable primitives
+\.{Uchar} and \.{Ucharcat}, which are derived from \hologo{XeTeX}.
+
+\begin{simplelist}
+ \csitem[\.{Uchar} <character code>]
+ Expands to a character token with specified slot <character code>.
+ \begin{itemize}
+ \item When an 8-bit number (0--255) is given,
+ it expands to a Latin character token with category code 12,
+ except for a space character (32) which has category code 10.
+ \item When a Japanese character code greater than 255 is given,
+ it expands to a Japanese character token with its current category code;
+ 16--18 for \epTeX, 16--19 for \eupTeX.
+ % [TODO] 本当は pTeX では和文文字トークン自体は \kcatcode を
+ % 持たないが,簡単のためまあいっか.
+ \end{itemize}
+
+ \csitem[\.{Ucharcat} <character code> <category code>]
+ Expands to a character token with slot <character code> and
+ <category code> specified.
+ \begin{itemize}
+ \item With \epTeX:
+ \begin{itemize}
+ \item Only 8-bit number (0--255) are allowed for <character code>;
+ that is, only Latin characters can be generated.
+ \item The values allowed for <category code> are 1--4, 6--8, 10--13.
+ \end{itemize}
+ \item With \eupTeX:
+ \begin{itemize}
+ \item When <character code> is between 0--127,
+ only Latin characters can be generated.
+ Thus, the values allowed for <category code> are
+ 1--4, 6--8, 10--13.
+ \item When <character code> is between 128--255,
+ both Latin and Japanese characters can be generated
+ depending on the specified <category code>;
+ 1--4, 6--8, 10--13: Latin character,
+ 16--19: Japanese character.
+ \item When <character code> is greater than 255,
+ only Japanese characters can be generated.
+ Thus, the values allowed for <category code> are
+ 16--19.
+ \end{itemize}
+ \end{itemize}
+\end{simplelist}
%%% pdfTeX と違うところ
\subsection{Difference from \pdfTeX\ in DVI mode}\label{dvi-pdftex}
As stated above,
-\epTeX/\eupTeX\ are {\em not} uppercompatible with DVI mode of \pdfTeX.
+\epTeX/\eupTeX\ are \emph{not} upward compatible with DVI mode of \pdfTeX.
%%% pdfTeX の DVI モードにあって e-(u)pTeX にないプリミティブ
%%% その他ムニャムニャ
@@ -591,29 +888,112 @@ This section does not aim to explain Japanese typesetting completely;
here we provide a minimum requirement for ``getting away'' with Japanese.
%%% 空白・ペナルティ挿入:勝手に入ってくる!
-\subsection{Automatic insertion of glues and penalties}
+\subsection{Automatic insertion of glue and penalties}
-Sometimes \pTeX\ family automatically inserts glues and penalties
+Sometimes \pTeX\ family automatically inserts glue and penalties
between characters.
% [TODO] もう少しだけ詳しく
%%% 和文フォント
\subsection{Japanese fonts}
-For typesetting Japanese characters, a JFM (Japanese \TeX\ font metric)
-format is used. It is a modified version of \TeX\ TFM.
-
%%% 欧文とは別個
+\pTeX\ family can have 3 different ``current'' fonts at the same time;
+a Latin font, a Japanese font for horizontal writing (``yoko-gumi''),
+and a Japanese font for vertical writing (``tate-gumi'').
+The first one is the same as in the Knuthian \TeX,
+which is defined in a standard TFM format.
+The latter two are specific to \pTeX\ family, which are defined
+in a JFM (Japanese \TeX\ font metric) format.\footnote{%
+A JFM is a modified version of the standard TFM.
+It can be created by (u)pPLtoTF, and decoded by (u)pTFtoPL.
+Please also refer to the man pages of these programs
+(\code{ppltotf.man1.pdf} and \code{ptftopl.man1.pdf}).}
+
+While typesetting, \pTeX\ family automatically switches between
+these 3 fonts, depending on the character code and the writing direction:
+\begin{itemize}
+ \item For typesetting Latin characters,
+ the current Latin font shown by |\the\font| is selected.
+ \item For typesetting Japanese characters,
+ the current Japanese font suitable for the current writing direction
+ is selected. It is shown by |\the\jfont| for horizontal writing
+ and |\the\tfont| for vertical writing.
+\end{itemize}
+
%%% \nullfont しても全部消えない
+%%% 「和文 \nullfont」は和文フォントが一回もグローバルに
+%%% 設定されていないとき = iniTeX 時しかない
+In Knuthian \TeX, the primitive \.{nullfont} refers to an ``empty font''
+in which all characters are undefined.
+However in \pTeX\ family, this is regarded as a Latin font
+and there is no equivalent to ``Japanese \.{nullfont}'' by design.
+To elaborate, it is possible \emph{only} when no Japanese font is
+set globally, i.e. in ini\TeX\ mode.
+Once a valid Japanese font is selected, there is no way of
+selecting ``Japanese \.{nullfont}'' to discard all characters.
+
+Moreover, \pTeX\ and friends assume that each Japanese font
+(except ``Japanese \.{nullfont}'' in ini\TeX\ mode)
+contains all valid Japanese character code.
+In other words, all Japanese fonts share the same character set
+corresponding to the whole valid Japanese character code range.\label{jfont}
+
+\section{Other strange beasts}
%%% 縦組は諦めよう
+% [TODO] どこに書くか困ったので最後に:内部コードのアレな話
+\subsection{Internal kanji encodings}\label{kanji-internal}
+
+The <character code> is a union of the following two:
+\begin{itemize}
+ \item Range of numbers between 0--255, and
+ \item Numbers allowed for internal code of Japanese characters.
+\end{itemize}
+The former is the same as Knuthian \TeX, but the latter is a problem.
+In \upTeX/\eupTeX\ with \code{-kanji-internal=uptex} (default on),
+the range is very simple:
+\[ c \ge 0 \]
+However in \pTeX/\epTeX, only legacy encodings (EUC-JP as |euc|,
+or Shift-JIS as |sjis|) are available for \code{-kanji-internal}.
+In this case, the range can be represented as follows:
+\[
+ c = 256c_1+c_2 \; (c_i\in C_i)
+\]
+where
+\[
+ \begin{cases}
+ C_1=C_2=\{\hex{a1},\dots,\hex{fe}\} & (\mathtt{euc}), \\
+ C_1=\{\hex{81},\dots,\hex{9f}\}\cup\{\hex{e0},\dots,\hex{fc}\},
+ C_2=\{\hex{40},\dots,\hex{7e}\}\cup\{\hex{80},\dots,\hex{fc}\} & (\mathtt{sjis}).
+ \end{cases}
+\]
+Therefore, the overall range of <character code> is \emph{not} continuous.
+
+To check whether an integer is a valid Japanese character code or not,
+you can use \.{iffontchar} with \epTeX~190709 or later (\TL2020).
+Suppose a count register |\mycount| stores an integer, you can do it as follows:
+\begin{verbatim}
+ \iffontchar\jfont\mycount
+ % \mycount is a valid Japanese character code
+ \fi
+\end{verbatim}
+Here the primitive \.{jfont} is used merely as
+a representative non-empty\footnote{This assumption is always safe after
+one of the standard \pTeX\ formats (e.g. plain \pTeX, \pLaTeX) is loaded.}
+Japanese font containing all valid Japanese character code (see \ref{jfont}).
+
+
\newpage
\begin{thebibliography}{99}
\bibitem{dvistd0} TUG DVI Standards Working Group,
\textit{The DVI Driver Standard, Level 0}.\\
\url{https://ctan.org/pkg/dvistd}
+ \bibitem{topic} Victor Eijkhout, \textit{\TeX\ by Topic, A \TeX nician's Reference},
+ Addison-Wesley, 1992.\\
+ \url{https://www.eijkhout.net/texbytopic/texbytopic.html}
\end{thebibliography}
\newpage