-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathptex-guide-en.tex
1236 lines (1085 loc) · 47.6 KB
/
ptex-guide-en.tex
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
%#!make ptex-guide-en.pdf
\documentclass[a4paper,11pt,dvipdfmx]{article}
\usepackage[textwidth=42zw,lines=40,truedimen,centering]{geometry}
%%%%%%%%%%%%%%%%
% additional packages
\usepackage{amsmath}
\usepackage{array}
\usepackage[all]{xy}
\SelectTips{cm}{}
\usepackage[T1]{fontenc}
\usepackage{booktabs,enumitem,multicol}
\usepackage[defaultsups]{newpxtext}
\usepackage[zerostyle=c,straightquotes]{newtxtt}
\usepackage{newpxmath}
\usepackage{color}
\usepackage[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]{%
itemsep=0pt, listparindent=1zw, itemindent=10pt,
font=\normalfont\mdseries, leftmargin=2zw,
before=\advance\@listdepth\@ne,
after=\advance\@listdepth\m@ne
}
\makeatother
%%%%%%%%%%%%%%%%
\makeatletter
\setlist{leftmargin=2zw}
\setlist[description]{labelwidth=2zw,labelindent=1zw,topsep=\medskipamount}
\usepackage{shortvrb}
\MakeShortVerb*{|}
%%%%%%%%%%%%%%%%
% foreign text -> italic
\def\Foreign#1{\textit{#1}}
\def\_{\leavevmode\vrule width .45em height -.2ex depth .3ex\relax}
\frenchspacing
\begin{document}
\catcode`\<=13
\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}
\maketitle
\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 \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.
%%% Target readers of this document: 日本語機能でないパッケージ作者に絞る
\section*{Purpose of this document}
This document is written for developers of \TeX/\LaTeX, who aim to
support \pTeX/\pLaTeX\ and its variants \upTeX/\upLaTeX.
Knowledge of the followings are assumed:
\begin{itemize}
\item Basic knowledge of Western \TeX\ (Knuthian \TeX, \eTeX\ and \pdfTeX),
\item ... and its programming conventions.
\end{itemize}
%%% 日本語（の組版・文字コード）の知識は要らない。その話はできる限り避ける
Any knowledge of Japanese (characters, encodings, typesetting conventions etc.)
is not assumed; some explanations are provided in this document when needed.
We hope that this document helps authors of packages or classes
to proceed with supporting \pTeX\ family smoothly.
\begin{quotation}
Note: This English guide (\file{\jobname.pdf}) is \emph{not} meant
to be a complete translation of Japanese manual (\file{ptex-manual.pdf}).
For example, this document does not cover issues regarding Japanese typesettings.
If you are interested in typesetting conventions of Japanese text, please also
refer to \file{japanese.pdf} distributed with \Pkg{babel-japanese}.
\end{quotation}
This document is maintained at:
\url{https://github.com/texjporg/ptex-manual/}
\tableofcontents
\newpage
%%%%%
\part{Brief introduction}% 概論
%%% pTeX とその仲間
\section{\pTeX\ and its variants}
The figure below shows the relationship between engines.
\[
\xymatrix@ur{
\text{\TeX} \ar[r]\ar[d] & \text{\eTeX} \ar[r]\ar[d]
& \text{\fbox{\pdfTeX}} \\
\text{\pTeX} \ar[r]\ar[d] & \text{\fbox{\epTeX}} \ar[d] &\\
\text{\upTeX} \ar[r] & \text{\fbox{\eupTeX}} &
}
\]
\pTeX\ is an old Japanese-specific extension of \TeX82,
which aims to support proper typesetting of Japanese text
but only supports a limited character set, JIS~X~0208 (6879 characters).
\upTeX\ is developed as an extension of \pTeX\ to support full Unicode
characters. It also includes modifications and extensions to overcome
the difficulties of \pTeX\ in processing 8-bit Latin characters
due to conflicts with legacy multibyte Japanese encodings.
\epTeX\ and \eupTeX\ are \eTeX\ extensions of \pTeX\ and \upTeX\ respectively.
In the current release, some extensions derived from \pdfTeX\ and \OMEGA\ are
also available.
%%% 際立った pTeX 系列の特徴
\section{Eminent characteristics of \pTeX\ family}
The most important characteristics of \pTeX\ family can be
summarized as follows:
%%% 欧文と和文が別個に存在する・縦組がある
\begin{itemize}
\item Japanese characters are interpreted and handled completely apart from
Western characters. If a pair of two or more 8-bit codes in the input
matches the pattern of Japanese character codes, it is regarded as one
Japanese character and given a different \.{catcode} (\.{kcatcode}) value.
\item There are two text directions; horizontal (\Foreign{yoko-gumi}; 横組)
and vertical (\Foreign{tate-gumi}; 縦組).
Two directions can be mixed even within a single document.
\end{itemize}
%%% 欧文 TeX との互換性
\section{Compatibility with Western \TeX}\label{compat}
%%% pTeX/upTeX は Knuthian TeX に対してほぼ上位互換
\pTeX/\upTeX\ are almost upward compatible with Knuthian \TeX,
however, they do not pass the TRIP test.
%%% 入力の8bitの扱いが異なる。フォントの8bitはそのまま
The most important difference lies in the handling of 8-bit code inputs;
some 8-bit Latin characters may be subject to the encoding conversion.
There is no difference in handling 8-bit TFM font.
%%% e-pTeX/e-upTeX は e-TeX に対してほぼ上位互換
\epTeX/\eupTeX\ are almost upward compatible with \eTeX,
however, input handling is similar to \pTeX/\upTeX.
It does not pass the e-TRIP test.
%%% だけど e-TeX はもうなく，pdfTeX の DVI モードがあるだけ
That said, please note that ``raw \eTeX'' is unavailable anymore
in \TL and derived distributions;
they provide a command |etex| only as ``DVI mode of \pdfTeX.''
%%% e-pTeX/e-upTeX は pdfTeX の DVI モードに対して上位互換ではない
You should note that
\epTeX/\eupTeX\ are \emph{not} upward compatible with DVI mode of \pdfTeX,
which will be discussed later in Section \ref{dvi-pdftex}.
%%% e-(u)pTeX の話がメイン
There is no advantage to choose \pTeX/\upTeX\ over \epTeX/\eupTeX,
so we focus mainly on \epTeX/\eupTeX.
% [TODO] 既に pTeX/upTeX が暗に e-pTeX/e-upTeX を指す場合もある
%%% LaTeX ムニャムニャ
\section{\LaTeX\ on \pTeX/\upTeX\ --- \pLaTeX/\upLaTeX}
%%% pLaTeX と upLaTeX ムニャムニャ
Format based on \LaTeX\ is called \pLaTeX\ when running on \pTeX,
and called \upLaTeX\ when running on \upTeX.
%%% カーネルが拡張されている
When building the format, |platex.ltx| (\pLaTeX) or
|uplatex.ltx| (\upLaTeX) loads |latex.ltx| first
and adds some additional commands related to the followings:
\begin{itemize}
\item Selection of Japanese fonts,
\item Crop marks (called \Foreign{tombow}; トンボ) for printings,
\item Adjustment for mixing horizontal and vertical texts.
\end{itemize}
%%% author レベルでは LaTeX とほぼ互換，ただし例外あり
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,
<bottom float> is placed above <footnote>.
That is, the complete order is
<top float> $\rightarrow$ <body text> $\rightarrow$
<bottom float> $\rightarrow$ <footnote>.
% [TODO] 他にもあるか？
\end{itemize}
%%% developer レベルでは pdfTeX 拡張や pLaTeX カーネルでムニャムニャ
For developers, additional care may be needed,
for changes in the kernel macros and/or the engine difference
(Japanese handling, absence of \pdfTeX\ features, etc).
In recent versions of \TL and its derivatives,
the default engines of \pLaTeX\ and \upLaTeX\ are as follows:
\begin{center}
\begin{tabular}{lll}
Date & \pLaTeX & \upLaTeX \\ \hline
\TL2010 & \pTeX & --- \\
\TL2011 & \epTeX & --- \\
\TL2012--2022, 2023 initial & \epTeX & \eupTeX \\
Since 2023-06-01 & \eupTeX\ in legacy (see below) & \eupTeX \\
\end{tabular}
\end{center}
The command |platex| started \epTeX\ (not \pTeX) with preloaded format
|platex.fmt| in \TL2022.
Since 2023-06-01, \pLaTeX\ has switched its engine from \epTeX\ to
\eupTeX\ in ``legacy-encoding-compatibility mode.'' It means that
additional primitives of (\eTeXpre)\upTeX\ is available also on \pLaTeX,
but the internal code of Japanese characters is still non-Unicode
to keep the backward compatibility.
Further information can be found in Section \ref{detecting-uptex}.
\newpage
%%%%%
\part{Details}% 各論
%%% 出力フォーマット
\section{Output format --- DVI}
%%% DVI だけ
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\footnote{%
Since \LaTeXe~2020-02-02, this warning is effectively gone. This is due
to preloading of \Pkg{expl3} into the format, and the driver-dependent
code of \Pkg{expl3} interprets the global driver option.}:
\begin{verbatim}
LaTeX Warning: Unused global option(s):
[dvipdfmx].
\end{verbatim}
\end{itemize}
\subsection{Extensions of DVI format in \pTeX\ family}
%%% pTeX の DVI は欧文の横組みだけなら普通。和文が入ると特殊，縦組ならIDも変化
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}
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) seems to be unused
Used to typeset a Japanese character with 2-byte code
(both \pTeX\ and \upTeX).
\item |set3| (130): % |put3| (135) seems to be unused
Used to typeset a Japanese character with 3-byte code
(\upTeX\ only).
\end{itemize}
When \pTeX\ is going to typeset a Japanese character into DVI,
it is encoded in JIS, which is always a 2-byte code.
For this purpose, |set2| or |put2| are used.
When \upTeX\ is going to output a Japanese character into DVI,
it is encoded in UTF-32.
If the code is equal to or less than |U+FFFF|,
the lower 16-bit is used with |set2| or |put2|.
If the code is equal to or greater than |U+10000|,
the lower 24-bit is used with |set3| or |put3|.
In addition, \pTeX/\upTeX\ defines one additional DVI command.
\begin{itemize}
\item |dir| (255):
Used to change directions of text alignment.
\end{itemize}
The DVI format in the preamble is always set to 2, as with \TeX82.
On the other hand, the DVI ID in the postamble can be special.
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$.
\subsection{DVI drivers with Japanese support}
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 \emph{dvipdfmx}}
A DVI file which is output by \pTeX\ can be converted directly to a PDF file
using dvipdfmx.
For Japanese fonts to be used in the output PDF, dvipdfmx refers to
|kanjix.map| generated by the command |updmap|.
You can use the script |kanji-config-updmap| to change font settings;
please refer to its help message or documentation.
\subsubsection{Using \emph{dvips}}
A DVI file which is output by \pTeX\ can be converted to a PostScript file
using dvips.
For Japanese fonts to be used in the output PostScript, dvips refers to
\code{psfonts.map} generated by the command \code{updmap}.
You can use the script |kanji-config-updmap| to change font settings;
please refer to its help message or documentation.
The resulting PostScript file can then be converted to
a PDF file using Ghostscript (ps2pdf) or Adobe Distiller.
When using Ghostscript, a proper setup of Japanese font must be done
before converting PostScript into PDF.
An easy solution for the setup is to run a script |cjk-gs-integrate|
developed by Japanese \TeX\ Development Community.
\section{Programming on \pTeX\ family}
We focus on programming aspects of \pTeX\ and its variants.
%%% レジスタの数
\subsection{Number of registers and marks}
\pTeX\ and \upTeX\ have exactly the same number ($=256$) of registers
(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.
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 and keywords}
% -- as of r62095
% tex -ini: 322 multiletter control sequences
% ptex -ini: 374 multiletter control sequences (= 322 + p:48 + TL:3 + SyncTeX: 1)
% uptex -ini: 381 multiletter control sequences (= 374 + up:7)
% eptex -ini: 388 multiletter control sequences
% eptex -ini -etex: 486 multiletter control sequences (= 374 + e:66 + ep:45 + TL:1)
% euptex -ini: 395 multiletter control sequences
% euptex -ini -etex: 494 multiletter control sequences (= 381 + e:66 + ep:46 + eup:1 + TL:1)
% etex (pdftex) -ini: 477 multiletter control sequences
% etex (pdftex) -ini -etex: 546 multiletter control sequences
Here we provide only complete lists of additional primitives
of \pTeX\ family in alphabetical order.
The features of each primitive can be found in Japanese edition.
% [TODO] 抜けがないか？
% [TODO] アルファベット順に正しく並んでいるか？
% [TODO] 追加されたバージョン情報は正しいか？
\def\New#1{--- New primitive since #1}
\def\NewKey#1{--- New keyword since #1}
\def\NewMoved#1#2{--- Imported from #1, since #2}
%%% pTeX のやつ
\subsubsection{\pTeX\ additions (available in \pTeX, \upTeX, \epTeX, \eupTeX)}
\begin{simplelist}
\csitem[\.{autospacing}]
\csitem[\.{autoxspacing}]
\csitem[\.{disinhibitglue} \New{p3.8.2 (\TL2019)}]
\csitem[\.{dtou}]
\csitem[\.{euc}]
\csitem[\.{ifdbox} \New{p3.2 (\TL2011)}]
\csitem[\.{ifddir} \New{p3.2 (\TL2011)}]
\csitem[\.{ifjfont} \New{p3.8.3 (\TL2020)}]
\csitem[\.{ifmbox} \New{p3.7.1 (\TL2017)}]
\csitem[\.{ifmdir}]
\csitem[\.{iftbox}]
\csitem[\.{iftdir}]
\csitem[\.{iftfont} \New{p3.8.3 (\TL2020)}]
\csitem[\.{ifybox}]
\csitem[\.{ifydir}]
\csitem[\.{inhibitglue}]
\csitem[\.{inhibitxspcode}]
\csitem[\.{jcharwidowpenalty}]
\csitem[\.{jfam}]
\csitem[\.{jfont}]
\csitem[\.{jis}]
\csitem[\.{kanjiskip}]
\csitem[\.{kansuji}]
\csitem[\.{kansujichar}]
\csitem[\.{kcatcode}]
\csitem[\.{kuten}]
\csitem[\.{noautospacing}]
\csitem[\.{noautoxspacing}]
\csitem[\.{postbreakpenalty}]
\csitem[\.{prebreakpenalty}]
\csitem[\.{ptexfontname} \New{p4.1.0 (\TL2023)}]
\csitem[\.{ptexlineendmode} \New{p4.0.0 (\TL2022)}]
\csitem[\.{ptexminorversion} \New{p3.8.0 (\TL2018)}]
\csitem[\.{ptexrevision} \New{p3.8.0 (\TL2018)}]
\csitem[\.{ptextracingfonts} \New{p4.1.0 (\TL2023)}]
\csitem[\.{ptexversion} \New{p3.8.0 (\TL2018)}]
\csitem[\.{scriptbaselineshiftfactor} \New{p3.7 (\TL2016)}]
\csitem[\.{scriptscriptbaselineshiftfactor} \New{p3.7 (\TL2016)}]
\csitem[\.{showmode}]
\csitem[\.{sjis}]
\csitem[\.{tate}]
\csitem[\.{tbaselineshift}]
\csitem[\.{textbaselineshiftfactor} \New{p3.7 (\TL2016)}]
\csitem[\.{tfont}]
\csitem[\.{tojis} \New{p4.1.0 (\TL2023)}]
\csitem[\.{toucs} \New{p3.10.0 (\TL2022)}]
\csitem[\.{ucs} \NewMoved{\upTeX}{p3.10.0 (\TL2022)}\footnotemark]
\csitem[\.{xkanjiskip}]
\csitem[\.{xspcode}]
\csitem[\.{ybaselineshift}]
\csitem[\.{yoko}]
\csitem[\texttt{H}\index{H=\texttt{H}}]
\csitem[\texttt{Q}\index{Q=\texttt{Q}}]
\csitem[\texttt{zh}\index{zh=\texttt{zh}}]
\csitem[\texttt{zw}\index{zw=\texttt{zw}}]
\end{simplelist}
\footnotetext{The primitive \.{ucs} was part of ``\upTeX\ additions'' until \TL2021.}
%%% upTeX のやつ
\subsubsection{\upTeX\ additions (available in \upTeX, \eupTeX)}
\begin{simplelist}
\csitem[\.{disablecjktoken}]
\csitem[\.{enablecjktoken}]
\csitem[\.{forcecjktoken}]
\csitem[\.{kchar}]
\csitem[\.{kchardef}]
%\csitem[\.{ucs}] % moved to pTeX 3.10.0
\csitem[\.{uptexrevision} \New{u1.23 (\TL2018)}]
\csitem[\.{uptexversion} \New{u1.23 (\TL2018)}]
\end{simplelist}
%%% e-pTeX/e-upTeX の pdfTeX 由来
%%% e-pTeX/e-upTeX の Omega 由来
%%% e-pTeX/e-upTeX の XeTeX/LuaTeX 由来
%%% その他の独自拡張
\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)}]
\csitem[\.{hfi}]
\csitem[\.{ifincsname} \New{190709 (\TL2020)}]
\csitem[\.{ifpdfprimitive} \New{150805 (\TL2016)}]
\csitem[\.{lastnodechar} \New{141108 (\TL2015)}]
\csitem[\.{lastnodefont} \New{220214 (\TL2022)}]
\csitem[\.{lastnodesubtype} \New{180226 (\TL2018)}]
\csitem[\.{odelcode}]
\csitem[\.{odelimiter}]
\csitem[\.{omathaccent}]
\csitem[\.{omathchar}]
\csitem[\.{omathchardef}]
\csitem[\.{omathcode}]
\csitem[\.{oradical}]
\csitem[\.{pagefistretch}]
\csitem[\.{pdfcreationdate} \New{130605 (\TL2014)}]
\csitem[\.{pdfelapsedtime} \New{161114 (\TL2017)}]
\csitem[\.{pdffiledump} \New{140506 (\TL2015)}]
\csitem[\.{pdffilemoddate} \New{130605 (\TL2014)}]
\csitem[\.{pdffilesize} \New{130605 (\TL2014)}]
\csitem[\.{pdflastxpos}]
\csitem[\.{pdflastypos}]
\csitem[\.{pdfmdfivesum} \New{150702 (\TL2016)}]
\csitem[\.{pdfnormaldeviate} \New{161114 (\TL2017)}]
\csitem[\.{pdfpageheight}]
\csitem[\.{pdfpagewidth}]
\csitem[\.{pdfprimitive} \New{150805 (\TL2016)}]
\csitem[\.{pdfrandomseed} \New{161114 (\TL2017)}]
\csitem[\.{pdfresettimer} \New{161114 (\TL2017)}]
\csitem[\.{pdfsavepos}]
\csitem[\.{pdfsetrandomseed} \New{161114 (\TL2017)}]
\csitem[\.{pdfshellescape} \New{141108 (\TL2015)}]
\csitem[\.{pdfstrcmp}]
\csitem[\.{pdfuniformdeviate} \New{161114 (\TL2017)}]
\csitem[\.{readpapersizespecial} \New{180901 (\TL2019)}]
\csitem[\.{suppresslongerror} \New{211207 (\TL2022)}]
\csitem[\.{suppressmathparerror} \New{211207 (\TL2022)}]
\csitem[\.{suppressoutererror} \New{211207 (\TL2022)}]
\csitem[\.{Uchar} \New{191112 (\TL2020)}]
\csitem[\.{Ucharcat} \New{191112 (\TL2020)}]
\csitem[\.{vadjust} \texttt{pre} \NewKey{210701 (\TL2022)}]
\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}
%%% ほか
\subsubsection{Other cross-engine additions}
% In the standard build of \TL, Sync\TeX\ extension is unavailable in
% Knuthian \TeX; however, it is enabled in \pTeX\ family.
Sync\TeX\ extension (available in \pTeX, \upTeX, \epTeX, \eupTeX):
\begin{simplelist}
\csitem[\.{synctex}]
\end{simplelist}
\noindent
\TL additions (available in \pTeX, \upTeX, \epTeX, \eupTeX):
\begin{simplelist}
\csitem[\.{partokencontext} \New{\TL2022}]
\csitem[\.{partokenname} \New{\TL2022}]
\csitem[\.{showstream} \New{\TL2022}] % only e-(u)pTeX, not (u)pTeX
\csitem[\.{special} \texttt{shipout} \NewKey{230214 (\TL2023)}] % only e-(u)pTeX, not (u)pTeX
\csitem[\.{tracingstacklevels} \New{\TL2021}]
\end{simplelist}
% [TODO] 引数は何で返り値は何か，expandable?
%%% (e-)TeX にあるが (e-)upTeX にないもの
%%% encTeX 拡張など
\subsection{Omitted primitives and unsupported features}
Compared to Knuthian \TeX\ and \eTeX, some primitives and extensions are
omitted due to conflict with Japanese handling.
\begin{itemize}
\item The enc\TeX\ extension, including the primitives |\mubyte| etc.,
is unavailable.
\item The ML\TeX\ extension, such as |\charsubdef|, is not enabled
by default. It becomes available with the command-line option |-mltex|,
but not well-tested.
\end{itemize}
%%% コマンドラインオプションの話
% [TODO] Please also refer to ptex.man1.pdf
\subsection{Behavior of Western \TeX\ primitives}
Here we provide some notes on behavior of Knuthian \TeX\ and \eTeX\ primitives
when used within \pTeX\ family.
\subsubsection{Primitives with limitations in handling Japanese}
Each of the following primitives allows only character codes 0--255;
other codes will give an error ``! Bad character code.''
\begin{quote}
|\catcode|,
|\sfcode|,
|\mathcode|,
|\delcode|,
|\lccode|,
|\uccode|.
\end{quote}
Each of the following primivies has |\...char| in its name,
however, the effective values are restricted to 0--255.
\begin{quote}
|\endlinechar|,
|\newlinechar|,
|\escapechar|,
|\defaulthyphenchar|,
|\defaultskewchar|.
\end{quote}
\subsubsection{Primitives capable of handling Japanese}
The following primitives are extended to support Japanese characters:
\begin{cslist}
\csitem[\.{char} <character code>,
\.{chardef} <control sequence>=<character code>]
In addition to 0--255, internal codes of Japanese characters
(see \ref{kanji-internal}) are allowed.
For putting Japanese characters, a Japanese font
(see \ref{japanese-fonts}) is chosen.
Further information can be found in \ref{chardef}.
\csitem[\.{font}, \.{fontname}, \.{fontdimen}]
% [TODO]
\csitem[\.{accent} <character code>=<character>]
% [TODO]
\csitem[\.{if} <token$_1$> <token$_2$>, \.{ifcat} <token$_1$> <token$_2$>]
Japanese character token is also allowed.
In that case,
\begin{itemize}
\item |\if| tests the internal character code of the Japanese character.
\item |\ifcat| tests the |\kcatcode| of the Japanese character.
\end{itemize}
\end{cslist}
\begin{dangerous}
\TeX book describes the behavior of |\if| and |\ifcat| as follows;
\begin{quote}
If either token is a control sequence,
\TeX\ considers it to have character code 256 and category code 16,
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 \code{tex.web},
a control sequence is considered to have a category code 0.
\end{dangerous}
\subsection{Case study}
Here we provide some code examples
which may be useful for package developers.
% [TODO] 本当は Based on the above knowledge としたいところだが
% 説明が圧倒的に不足しているので天下り的なコード解説…
%%% pTeX かどうかの判定
\subsubsection{Detecting \pTeX}
Since the primitive |\ptexversion| is rather new (added in 2018),
the safer solution for detecting \pTeX\ is
to test if a primitive |\kanjiskip| is defined.
\begin{verbatim}
\ifx\kanjiskip\undefined
\else
% pTeX / upTeX / e-pTeX / e-upTeX
\fi
\end{verbatim}
%%% upTeX かどうかの判定
\subsubsection{Detecting \upTeX}\label{detecting-uptex}
\upTeX\ is almost upward compatible with \pTeX, 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 Japanese encoding
(see \ref{kanji-internal}),
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}
This can be called ``engine detection'' of \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}
This can be called ``encoding detection'' of \upTeX.
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.
This can be called ``legacy-encoding-compatibility mode''
of \upTeX, where the \.{kcatcode} difference remains
but the internal encoding difference disappears.
This method is used in building |platex.fmt| on \eupTeX,
since 2023-06-01. Therefore, to distinguish \upLaTeX\ from \pLaTeX,
``engine detection'' is not enough; you should use ``encoding detection.''
%%% 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
\end{itemize}
%%% 指定のコードの和文トークンを得る方法
\subsubsection{Creating a Japanese character token with a specified code}\label{jtoken-tricks}
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 \Foreign{kanji} notation
called \Foreign{kansuji} (漢数字). The important point here is that
the number-\Foreign{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 includes an assignment of \.{kansujichar}
which is unexpandable.
\epTeX~191112 or later (\TL2020) provides expandable primitives
\.{Uchar} and \.{Ucharcat}, which are derived from \hologo{XeTeX}.
Regardless of their names, and unlike \hologo{XeTeX} or \hologo{LuaTeX},
these primitives do \emph{not} necessarily take
a Unicode value as an argument.
These primitives in \epTeX\ and \eupTeX\ take a valid character code
(see \ref{kanji-internal}) based on the internal Japanese encoding.
\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 in Section \ref{compat}, \epTeX/\eupTeX\ are
\emph{not} upward compatible with DVI mode of \pdfTeX,
which is available as the |etex| command in \TL.
Here we list some important differences:
%%% pdfTeX の DVI モードにあって e-(u)pTeX にないプリミティブ
First, some \pdfTeX-specific primitives are absent. Examples:
\begin{itemize}
\item All primitives specific to PDF output:
\.{pdfoutput}, \.{pdfinfo}, \.{pdfobj} etc.\footnote{%
\epTeX/\eupTeX\ has primitives \.{pdfpagewidth} and \.{pdfpageheight};
this is just because they were convenient for implementing \.{pdfsavepos},
and their behavior is somewhat different from that of \pdfTeX.
Also note that \epTeX/\eupTeX\ does not have \.{pdfhorigin}
and \.{pdfvorigin}.}
\item All primitives related to micro-typography:
\.{pdffontexpand}, \.{pdfprotrudechars}, etc.
\item Some primitives related to handling of strings:
\.{pdfescapestring}, \.{pdfescapehex} etc.
\end{itemize}
%%% その他ムニャムニャ
%%% ファイルの文字コードはどうするか
\subsection{Recommendation for file encoding}\label{file-enc}
Due to historical reasons,
multiple encodings are commonly used for Japanese text.
Sometimes user documents and distribution files (classes, packages)
may have different encodings.
Among those, the universal UTF-8 and
three major legacy encodings (ISO-2022-JP, EUC-JP, Shift-JIS)
are accepted as input to \pTeX\ family,
depending on the configuration and runtime options.
To make this possible,
\pTeX\ family does code conversion in input and output.
The details are too complicated, so here we propose
the optimum solution for Japanese file encoding
for package/class developers who aim to support \pTeX\ family:
%%% 全部アスキーにしてしまえ
%%% UTF-8 にしたい場合はムニャムニャ
%%% \epTeXinputencoding を使う話
\begin{itemize}
\item \underline{If you want to distribute files on CTAN/\TL, please use UTF-8.}
\par
UTF-8 files are \emph{almost always} safe enough
for recent \pTeX/\upTeX\ (2018--),
and the same files will have no problem when read by Western \TeX.
To secure this ``\emph{almost always}'' to ``\emph{always}'', please add
below at the beginning of your individual UTF-8 files:\par\quad
\verb+\ifx\epTeXinputencoding\undefined \else \epTeXinputencoding utf8 \fi+\par
it will help \pTeX\ family to read forcibly in UTF-8,
so it becomes \emph{always} safe for 2016--.
\item \underline{If you aim to support broader legacy environment of \pTeX\ specifically, ...}
\par
Extra care is required for missing features and
different configurations which can lead to failure of reading UTF-8.
There is no such thing as a perfect solution; instead,
you should choose between encoding in ISO-2022-JP
or writing in ASCII characters.
\begin{itemize}
\item Encoding in ISO-2022-JP:\par