1 %#! lualatex -shell-escape manual.ins && lualatex man-en && lualatex man-ja
4 \documentclass[a4paper,titlepage]{article}
5 \usepackage[margin=20mm]{geometry}
8 \documentclass[a4paper,titlepage]{bxjsarticle}
9 \setpagelayout*{margin=20mm}
10 \def\headfont{\normalfont\bfseries}
11 % \def\headfont{\sffamily\gtfamily} is needed in ordinal documents
14 \usepackage{amsmath,amssymb,xcolor,pict2e}
15 \usepackage{booktabs,listings,lltjlisting,showexpl}
17 \usepackage[unicode=true]{hyperref}
20 \title{The Lua\TeX-ja package}
21 \author{The Lua\TeX-ja project team}
24 \title{Lua\TeX-jaパッケージ}
25 \author{Lua\TeX-jaプロジェクトチーム}
29 basicstyle=\ttfamily\small, pos=o, breaklines=true,
30 numbers=none, rframe={}
34 \def<#1>{{\normalfont\itshape$\langle$#1$\rangle$}}
35 \parskip=\smallskipamount
43 {\Large\bf This documentation is far from complete. It may have many
44 grammatical (and contextual) errors.}
47 \textbf{\large 本ドキュメントはまだまだ未完成です.
48 また,英語版と日本語版をdocstripプログラムを用いることで一緒に生成している都合上,
55 \section{Introduction}
58 The Lua\TeX-ja package is a macro package for typesetting high-quality
59 Japanese documents in Lua\TeX.
62 Lua\TeX-jaパッケージは,次世代標準\TeX であるLua\TeX の上で,p\TeX と同等
63 /それ以上の品質の日本語組版を実現させようとするマクロパッケージである.
66 \subsection{Backgrounds}
67 Traditionally, ASCII p\TeX, an extension of \TeX, and its derivatives
68 are used to typeset Japanese documents in \TeX. p\TeX\ is an engine
69 extension of \TeX: so it can produce high-quality Japanese documents
70 without using very complicated macros. But this point is a mixed
71 blessing: p\TeX\ is left behind from other extensions of \TeX,
72 especially $\varepsilon$-\TeX\ and pdf\TeX, and from changes about
73 Japanese processing in computers (\textit{e.g.}, the UTF-8 encoding).
75 Recently extensions of p\TeX, namely up\TeX\ (Unicode-implementation
76 of p\TeX) and $\varepsilon$-p\TeX\ (merging of p\TeX and
77 $\varepsilon$-\TeX\ extension), have developed to fill those gaps to some
78 extent, but gaps are still exist.
80 However, the appearance of Lua\TeX\ changed the whole situation. With
81 using Lua `callbacks', users can customize the internal processing of
82 Lua\TeX. So there is no need to modify sources of engines to
83 support Japanese typesetting: to do this, we only have to write Lua
84 scripts for appropriate callbacks.
87 \subsection{Major Changes from p\TeX}
88 The Lua\TeX-ja package is under much influence of p\TeX\ engine. The initial
89 target of development was to implement features of p\TeX. However,
90 \emph{Lua\TeX-ja is not a just porting of p\TeX; unnatural
91 specifications/behaviors of p\TeX\ were not adopted}.
93 The followings are major changes from p\TeX:
95 \item A Japanese font is a tuple of a `real' font, a Japanese font
96 metric (\textbf{JFM}, for short), and an optional string called
99 \item In p\TeX, a linebreak after Japanese character is ignored (and
100 doesn't yield a space), since linebreaks (in source files) are
101 permitted almost everywhere in Japanese texts. However, Lua\TeX-ja
102 doesn't have this function completely, because of a specification
104 \item The insertion process of glues/kerns between two Japanese
105 characters and between a Japanese character and other characters
106 (we refer these glues/kerns as \textbf{JAglue}) is rewritten from
110 \item As Lua\TeX's internal character handling is `node-based'
111 (\textit{e.g.}, \verb+of{}fice+ doesn't prevent ligatures), the
112 insertion process of \textbf{JAglue} is now `node-based'.
113 \item Furthermore, nodes between two characters which have no effects in
114 linebreak (\textit{e.g.}, \verb+\special+ node) are ignored in the
116 \item In the process, two Japanese fonts which differ in their `real'
117 fonts only are identified.
119 \item At the present, vertical typesetting (\emph{tategaki}), is not
120 supported in Lua\TeX-ja.
123 For detailed information, see Part~\ref{part-imp}.
125 \subsection{Notations}
126 In this document, the following terms and notations are used:
128 \item Characters are divided into two types:
130 \item \textbf{JAchar}: standing for Japanese characters such as
131 Hiragana, Katakana, Kanji and other punctuation marks for
133 \item \textbf{ALchar}: standing for all other characters like alphabets.
135 We say `alphabetic fonts' for fonts used in \textbf{ALchar}, and `Japanese fonts' for fonts used in \textbf{JAchar}.
137 \item A word in a sans-serif font (like \textsf{prebreakpenalty})
138 represents an internal parameter for Japanese typesetting, and it
139 is used as a key in \verb+\ltjsetparameter+ command.
140 \item The word `primitive' is used not only for primitives in Lua\TeX,
141 but also for control sequences that defined in the core module of
143 \item In this document, natural numbers start from~0.
146 \subsection{About the project}
147 \paragraph{Project Wiki} \url{http://sourceforge.jp/projects/luatex-ja/wiki/FrontPage%28en%29}
149 This project is hosted by SourceForge.JP.
161 \section{Getting Started}
162 \subsection{Installation}
163 To install the Lua\TeX-ja\ package, you will need:
165 \item Lua\TeX\ (version 0.65.0-beta or later) and its supporting packages.\\
166 If you are using \TeX~Live\ 2011 or W32\TeX, you don't have to worry.
167 \item The source archive of Lua\TeX-ja, of course{\tt:)}
170 The installation methods are as follows:
172 \item Download the source archive.
174 At the present, Lua\TeX-ja has no official release, so you have to retrieve
175 the archive from the repository.
176 You can retrieve the Git repository via
178 $ git clone git://git.sourceforge.jp/gitroot/luatex-ja/luatexja.git
180 or download the archive of HEAD in \texttt{master} branch from
182 \url{http://git.sourceforge.jp/view?p=luatex-ja/luatexja.git;a=snapshot;h=HEAD;sf=tgz}.
184 \item Extract the archive. You will see {\tt src/} and several other sub-directories.
185 \item Copy all the contents of {\tt src/} into one of your \texttt{TEXMF} tree.
186 \item If {\tt mktexlsr} is needed to update the filename database, make it so.
189 \subsection{Cautions}
191 \item The encoding of your source file must be UTF-8.
192 \item Not well-tested. In particular, the default setting of the range
193 of \textbf{JAchar} in the present version does not coexist with
194 other packages which use Unicode fonts.
197 \subsection{Using in plain \TeX}\label{ssec-plain}
198 To use Lua\TeX-ja in plain \TeX, simply put the following at the beginning of the document:
203 This does minimal settings (like {\tt ptex.tex}) for typesetting Japanese documents:
205 \item The following 6~Japanese fonts are preloaded:
207 \begin{tabular}{ccccc}
209 \textbf{classification}&\textbf{font name}&\textbf{13.5\,Q}&\textbf{9.5\,Q}&\textbf{7\,Q}\\\midrule
210 \emph{mincho}&Ryumin-Light &\verb+\tenmin+&\verb+\sevenmin+&\verb+\fivemin+\\
211 \emph{gothic}&GothicBBB-Medium&\verb+\tengt+ &\verb+\sevengt+ &\verb+\fivegt+\\
216 \item The `Q' is a unit used in Japanese phototypesetting, and
217 $1\,\textrm{Q}=0.25\,\textrm{mm}$. This length is stored in a
218 dimension \verb+\jQ+.
220 \item It is widely accepted that the font `Ryumin-Light' and
221 `GothicBBB-Medium' aren't embedded into PDF files, and PDF reader
222 substitute them by some external Japanese fonts (\textit{e.g.},
223 Kozuka Mincho is used in Adobe Reader). We adopt this custom to
225 \item You may notice that size of above fonts is slightly smaller than
226 their alphabetic counterparts: for example, the size
227 \verb+\texmin+ is $13.5\,\textrm{Q}\simeq 9.60444\,\textrm{pt}$. This is intensional: ...
229 \item A character in Unicode is treated as \textbf{JAchar} if and only
230 if its code-point has more than or equal to U+0100.
231 \item The amount of glue that are inserted between a \textbf{JAchar} and
232 an \textbf{ALchar} (the parameter \textsf{xkanjiskip}) is set to
234 0.25\,\hbox{\verb+\zw+}^{+1\,\text{pt}}_{-1\,\text{pt}} = \frac{27}{32}\,\mathrm{mm}^{+1\,\text{pt}}_{-1\,\text{pt}}.
236 Here \verb+\zw+ is the counterpart of \texttt{em} for Japanese fonts, that is, the length of `full-width' in current Japanese font.
239 \subsection{Using in \LaTeX}
241 Using in \LaTeXe\ is basically same. To set up the minimal environment
242 for Japanese, you only have to load {\tt luatexja.sty}:
244 \usepackage{luatexja}
246 It also does minimal settings (counterparts in p\LaTeX\ are {\tt
247 plfonts.dtx} and {\tt pldefs.ltx}):
250 \item {\tt JY3} is the font encoding for Japanese fonts (in horizontal direction).\\
251 When vertical typesetting is supported by Lua\TeX-ja in the future, {\tt JT3} will be used for vertical fonts.
252 \item Two font families {\tt mc} and {\tt gt} are defined:
254 \begin{tabular}{ccccc}
256 \textbf{classification}&\textbf{family}&\verb+\mdseries+&\verb+\bfseries+&\textbf{scale}\\\midrule
257 \emph{mincho}&\tt mc&Ryumin-Light &GothicBBB-Medium&0.960444\\
258 \emph{gothic}&\tt gt&GothicBBB-Medium&GothicBBB-Medium&0.960444\\
262 \textbf{Note on fonts in bold series}
264 \item Japanese characters in math mode are typeset by the font family {\tt mc}.
267 However, above settings are not sufficient for Japanese-based
268 documents. To typeset Japanese-based documents, You are better to use
269 class files other than {\tt article.cls}, {\tt book.cls}, ... At the
270 present, BXjscls (\texttt{bxjsarticle.cls} and \texttt{bxjsbook.cls}, by
271 Takayuki Yato) are better alternative. It is not determined whether
272 Lua\TeX-ja will develop and contain counterparts of major classes used
273 in p\TeX\ (including jsclasses by Haruhiko Okumura).
275 \subsection{Changing Fonts}
276 \paragraph{Remark: Japanese Characters in Math Mode}
277 Since p\TeX\ supports Japanese characters in math mode, there are
278 sources like the following:
281 $f_{高温}$~($f_{\text{high temperature}}$).
282 \[ y=(x-1)^2+2\quad{}よって\quad y>0 \]
283 $5\in{}素:=\{\,p\in\mathbb N:\text{$p$ is a prime}\,\}$.
286 We (the project members of Lua\TeX-ja) think that using
287 Japanese characters in math mode are allowed if and only if these are used as identifiers.
288 In this point of view,
290 \item The lines 1~and~2 above are not correct, since `高温' in above is used as a textual label, and
291 `よって' is used as a conjunction.
292 \item However, the line~3 is correct, since `素' is used as an identifier.
294 Hence, in our opinion, the above input should be corrected as:
297 ($f_{\text{high temperature}}$).
299 \mathrel{\text{よって}}\quad y>0 \]
300 $5\in{}素:=\{\,p\in\mathbb N:\text{$p$ is a prime}\,\}$.
302 %BUG?: \{\}がなければ「素」がでない.上の段落の「よって」もでてない.
303 We also believe that using Japanese characters as identifiers is rare,
304 hence we don't describe how to change Japanese fonts in math mode in
305 this chapter. For the method, please see Part~\ref{part-ref}.
308 \paragraph{plain \TeX}
309 To change Japanese fonts in plain \TeX, you must use the primitive
310 \verb+\jfont+. So please see Part~\ref{part-ref}.
314 For \LaTeXe, Lua\TeX-ja simply adopted the font selection system from that
315 of p\LaTeXe\ (in {\tt plfonts.dtx}).
317 \item Two control sequences \verb+\mcdefault+ and \verb+\gtdefault+ are
318 used to specify the default font families for \emph{mincho} and
319 \emph{gothic}, respectively. Default values: \texttt{mc} for
320 \verb+\mcdefault+ and \texttt{gt} for \verb+\gtdefault+.
321 \item Commands \verb+\fontfamily+, \verb+\fontseries+,
322 \verb+\fontshape+ and \verb+\selectfont+ can be used to change
323 attributes of Japanese fonts.
325 \begin{tabular}{ccccc}
327 &\textbf{encoding}&\textbf{family}&\textbf{series}&\textbf{shape}\\\midrule
329 &\verb+\romanencoding+&\verb+\romanfamily+&\verb+\romanseries+&\verb+\romanshape+\\
331 &\verb+\kanjiencoding+&\verb+\kanjifamily+&\verb+\kanjiseries+&\verb+\kanjishape+\\
332 both&---&--&\verb+\fontseries+&\verb+\fontshape+\\
333 auto select&\verb+\fontencoding+&\verb+\fontfamily+&---&---\\
337 \item For defining a Japanese font family, use \verb+\DeclareKanjiFamily+
338 instead of \verb+\DeclareFontFamily+.
342 To coexist with \texttt{fontspec} package, it is needed to load
343 \texttt{luatexja-fontspec} package in the preamble. This additional
344 package automatically loads \texttt{luatexja} and \texttt{fontspec}
347 In \texttt{luatexja-fontspec} package, the following 7~commands are defined as
348 counterparts of original commands in \texttt{fontspec}:
350 \begin{tabular}{ccccc}
353 &\verb+\jfontspec+&\verb+\setmainjfont+&\verb+\setsansjfont+&\verb+\newjfontfamily+\\
355 &\verb+\fontspec+&\verb+\setmainfont+&\verb+\setsansfont+&\verb+\newfontfamily+\\
358 &\verb+\newjfontface+&\verb+\defaultjfontfeatures+&\verb+\addjfontfeatures+\\
360 &\verb+\newfontface+&\verb+\defaultfontfeatures+&\verb+\addfontfeatures+\\
367 Note that there is no command named \verb+\setmonojfont+, since it is
368 popular for Japanese fonts that nearly all Japanese glyphs have same widths.
371 \section{Changing Parameters}
372 There are many parameters in Lua\TeX-ja. And due to the behavior of Lua\TeX,
373 most of them are not stored as internal register of \TeX, but as an
374 original storage system in Lua\TeX-ja. Hence, to assign or acquire those
375 parameters, you have to use commands \verb+\ltjsetparameter+ and
376 \verb+\ltjgetparameter+.
378 \subsection{Editing the range of \textbf{JAchar}}
379 As noted before, the default setting is:
381 A character in Unicode is treated as \textbf{JAchar},\\
383 code-point has more than or equal to U+0100.
385 $\uparrow$ TODO: CHANGE THIS!
391 \subsection{\textsf{kanjiskip} and \textsf{xkanjiskip}}\label{subs-kskip}
392 \textbf{JAglue} is divided into the following three categories:
394 \item Glues/kerns specified in JFM. If \verb+\inhibitglue+ is issued around a Japanese character,
395 this glue will be not inserted at the place.
396 \item The default glue which inserted between two \textbf{JAchar}s ({\sf
398 \item The default glue which inserted between a \textbf{JAchar} and an
399 \textbf{ALchar} (\textsf{xkanjiskip}).
401 The value (a skip) of \textsf{kanjiskip} or \textsf{xkanjiskip} can be
402 changed as the following.
404 \ltjsetparameter{kanjiskip={0pt plus 0.4pt minus 0.4pt},
405 xkanjiskip={0.25\zw plus 1pt minus 1pt}}
409 It may occur that JFM contains the data of `ideal width of {\sf
410 kanjiskip}' and/or `ideal width of \textsf{xkanjiskip}'.
411 To use these data from JFM, set the value of \textsf{kanjiskip} or
412 \textsf{xkanjiskip} to \verb+\maxdimen+.
414 \subsection{Insertion Setting of \textsf{xkanjiskip}}
415 It is not desirable that \textsf{xkanjiskip} is inserted between every
416 boundary between \textbf{JAchar}s and \textbf{ALchar}s. For example,
417 \textsf{xkanjiskip} should not be inserted after opening parenthesis
418 (\textit{e.g.}, compare `(あ' and `(\hskip\ltjgetparameter{xkanjiskip}あ').
420 Lua\TeX-ja can control whether \textsf{xkanjiskip} can be inserted
421 before/after a character, by changing \textsf{jaxspmode} for \textbf{JAchar}s and
422 \textsf{alxspmode} parameters \textbf{ALchar}s respectively.
424 \ltjsetparameter{jaxspmode={`あ,preonly}, alxspmode={`\!,postonly}}
428 The second argument {\tt preonly} means `the insertion of
429 \textsf{xkanjiskip} is allowed before this character, but not after'.
430 the other possible values are {\tt postonly}, {\tt allow} and {\tt
431 inhibit}. For the compatibility with p\TeX, natural numbers between
432 0~and~3 are also allowed as the second argument\footnote{But we don't
433 recommend this: since numbers 1~and~2 have opposite meanings in
434 \textsf{jaxspmode} and \textsf{alxspmode}.}.
436 If you want to enable/disable all insertions of \textsf{kanjiskip} and
437 \textsf{xkanjiskip}, set \textsf{autospacing} and \textsf{autoxspacing}
438 parameters to {\tt false}, respectively.
441 \subsection{Shifting Baseline}
442 To make a match between a Japanese font and an alphabetic font, sometimes
443 shifting of the baseline of one of the pair is needed. In p\TeX, this is achieved
444 by setting \verb+\ybaselineshift+ to a non-zero length (the
445 baseline of alphabetic fonts is shifted below). However, for documents
446 whose main language is not Japanese, it is good to shift the baseline of
447 Japanese fonts, but not that of alphabetic fonts.
448 Because of this, Lua\TeX-ja can independently set the shifting amount
449 of the baseline of alphabetic fonts (\textsf{yalbaselineshift}
450 parameter) and that of Japanese fonts (\textsf{yjabaselineshift}
454 \vrule width 150pt height 0.4pt depth 0pt\hskip-120pt
455 \ltjsetparameter{yjabaselineshift=0pt, yalbaselineshift=0pt}abcあいう
456 \ltjsetparameter{yjabaselineshift=5pt, yalbaselineshift=2pt}abcあいう
458 Here the horizontal line in above is the baseline of a line.
460 There is an interesting side-effect: characters in different size can be
461 vertically aligned center in a line, by setting two parameters appropriately.
462 The following is an example (beware the value is not well tuned):
466 \ltjsetparameter{yjabaselineshift=-1pt,
467 yalbaselineshift=-1pt}
473 \subsection{`tombow'}
474 `tombow' is a mark for indicating 4~corners and horizontal/vertical
475 center of the paper. p\LaTeX and this Lua\TeX-ja support `tombow' by
476 their kernel. The following steps are needed to typeset tombow:
479 \item First, define the banner which will be printed at the upper left
480 of the paper. This is done by assigning a token list to
481 \verb+\@bannertoken+.
483 For example, the following sets banner as `{\tt filename (2012-01-01 17:01)}':
487 \hour\time \divide\hour by 60 \@tempcnta\hour \multiply\@tempcnta 60\relax
488 \minute\time \advance\minute-\@tempcnta
490 \jobname\space(\number\year-\two@digits\month-\two@digits\day
491 \space\two@digits\hour:\two@digits\minute)}%
498 \part{Reference}\label{part-ref}
499 \section{Font Metric and Japanese Font}
500 \subsection{\texttt{\char92jfont} primitive}
501 To load a font as a Japanese font, you must use the
502 \verb+\jfont+ primitive instead of~\verb+\font+, while
503 \verb+\jfont+ admits the same syntax used in~\verb+\font+.
504 Lua\TeX-ja automatically loads \texttt{luaotfload} package,
505 so TrueType/OpenType fonts with features can be used for Japanese fonts:
507 \jfont\tradgt={file:ipaexg.ttf:script=latn;%
508 +trad;jfm=ujis} at 14pt
512 Note that the defined control sequence
513 (\verb+\tradgt+ in the example above) using \verb+\jfont+ is not a
514 \textit{font\_def} token, hence the input like
515 \verb+\fontname\tradgt+ causes a error. We denote control sequences which are defined in \verb+\jfont+
519 Besides \texttt{file:}\ and \texttt{name:}\ prefixes, \texttt{psft:}\ can
520 be used a prefix in \verb+\jfont+ (and~\verb+\font+) primitive. Using
521 this prefix, you can specify a font that has its name only and is not
522 related to any real font.
524 Mainly, use of this \texttt{psft:}\ prefix is for using non-embedding `standard' Japanese fonts (Ryumin-Light and GothicBBB-Medium).
532 \subsection{Structure of JFM file}
533 A JFM file is a Lua script which has only one function call:
535 luatexja.jfont.define_jfm { ... }
537 Real data are stored in the table which indicated above by
538 \verb+{ ... }+. So, the rest of this subsection are devoted to describe the
539 structure of this table. Note that all lengths in a JFM file are
540 floating-point numbers in design-size unit.
542 \begin{list}{}{\def\makelabel{\ttfamily}\def\{{\char`\{}\def\}{\char`\}}}
543 \item[dir=<direction>] (required)
545 The direction of JFM. At the present, only \texttt{'yoko'} is supported.
547 \item[zw=<length>] (required)
549 The amount of the length of the `full-width'.
551 \item[zh=<length>] (required)
553 \item[kanjiskip=\{<natural>, <stretch>, <shrink>\}] (optional)
555 This field specifies the `ideal' amount of \textsf{kanjiskip}. As noted
556 in Subsection~\ref{subs-kskip}, if the parameter
557 \textsf{kanjiskip} is \verb+\maxdimen+, the value specified
558 in this field is actually used (if this field is not specified in
559 JFM, it is regarded as 0\,pt). Note that <stretch> and <shrink>
560 fields are in design-size unit too.
563 \item[xkanjiskip=\{<natural>, <stretch>, <shrink>\}] (optional)
565 Like the \texttt{kanjiskip} field, this field specifies the `ideal'
566 amount of \textsf{xkanjiskip}.
570 Besides from above fields, a JFM file have several sub-tables those
571 indices are natural numbers. The table indexed by~$i\in\omega$ stores
572 informations of `character class'~$i$. At least, the character class~0 is
573 always present, so each JFM file must have a sub-table whose index is
574 \texttt{[0]}. Each sub-table (its numerical index is denoted by $i$) has
575 the following fields:
577 \begin{list}{}{\def\makelabel{\ttfamily}\def\{{\char`\{}\def\}{\char`\}}}
578 \item[chars=\{<character>, ...\}] (required except character class~0)
580 This field is a list of characters which are in this character
581 type~$i$. This field is not required if $i=0$, since all
582 \textbf{JAchar} which are not in any character class other
583 than 0 (hence, the character class~0 contains most of
584 \textbf{JAchar}s). In the list, a character can be
585 specified by its code number, or by the character itself
586 (as a string of length~1).
588 In addition to those `real' characters, the following `imaginary
589 characters' can be specified in the list:
591 \item[width=<length>, height=<length>, depth=<length>, italic=<length>]\ (required)
593 Specify width of characters in character class~$i$, height, depth and
594 the amount of italic correction. All characters in character class~$i$ are regarded that its width, height and depth are
595 as values of these fields.
596 But there is one exception: if \texttt{'prop'} is specified in \texttt{width} field, width of a character becomes that of its `real' glyph
598 \item[left=<length>, down=<length>, align=<align>]\
600 These fields are for adjusting the position of the `real' glyph. Legal
601 values of \texttt{align} field are \texttt{'left'},
602 \texttt{'middle'} and \texttt{'right'}. If one of these
603 3~fields are omitted, \texttt{left} and \texttt{down} are
604 treated as~0, and \texttt{align} field is treated as
606 The effects of these 3~fields are indicated in Figure~\ref{fig-pos}.
608 In most cases, \texttt{left} and \texttt{down} fields are~0, while
609 it is not uncommon that the \texttt{align} field is \texttt{'middle'} or \texttt{'right'}.
610 For example, setting the \texttt{align} field to \texttt{'right'} is practically needed
611 when the current character class is the class for opening delimiters'.
613 \begin{minipage}{0.4\textwidth}%
614 \begin{center}\unitlength=10pt\small
615 \begin{picture}(15,12)(-1,-4)
616 \color{black!10!white}% real glyph :step1
617 \put(0,0){\vrule width 12\unitlength height 8\unitlength depth 3\unitlength}
619 \color{red!20!white}% real glyph :step1
620 \put(-1,-1.5){\vrule width 6\unitlength height 7\unitlength depth 2.5\unitlength}
622 \color{red}% real glyph
624 \put(-1,-1.5){\vector(0,1){7}\vector(0,-1){2.5}\vector(1,0){6}}
625 \put(5,-1.5){\line(0,1){7}\line(0,-1){2.5}}
626 \put(-1,5.5){\line(1,0){6}}
627 \put(-1,-4){\line(1,0){6}}
629 \color{green!20!white}% real glyph :step1
630 \put(3,0){\vrule width 6\unitlength height 7\unitlength depth 2.5\unitlength}
632 \color{black}% real glyph :step1
634 \put(0,0){\vector(0,1){8}\line(0,-1){3}\vector(1,0){12}}
635 \put(12,0){\line(0,1){8}\vector(0,-1){3}}
636 \put(0,8){\line(1,0){12}}
637 \put(0,-3){\line(1,0){12}}
638 \put(0.2,4){\makebox(0,0)[l]{\texttt{height}}}
639 \put(12.2,-1.5){\makebox(0,0)[l]{\texttt{depth}}}
640 \put(6,0.2){\makebox(0,0)[b]{\texttt{width}}}
642 \color{green!50!black}% real glyph :step1
644 \put(3,0){\vector(0,1){7}\vector(0,-1){2.5}\vector(1,0){6}}
645 \put(9,0){\line(0,1){7}\line(0,-1){2.5}}
646 \put(3,7){\line(1,0){6}}
647 \put(3,-2.5){\line(1,0){6}}
649 \savebox{\eqdist}(0,0)[b]{%
651 \put(-0.08,0.2){\line(0,-1){0.4}}%
652 \put(0.08,0.2){\line(0,-1){0.4}}}
653 \put(1.5,0){\usebox{\eqdist}}
654 \put(10.5,0){\usebox{\eqdist}}
656 \color{blue}% shifted
658 \put(3,-1.5){\vector(-1,0){4}}
659 \put(1,-1.7){\makebox(0,0)[t]{\texttt{left}}}
660 \put(3,0){\vector(0,-1){1.5}}
661 \put(3.2,-0.75){\makebox(0,0)[l]{\texttt{down}}}
665 \begin{minipage}{0.6\textwidth}%
666 Consider a node containing Japanese character whose value of the \texttt{align}
667 field is \texttt{'middle'}.
669 \item The black rectangle is a frame of the node.
670 Its width, height and depth are specified by JFM.
671 \item Since the \texttt{align} field is \texttt{'middle'},
672 the `real' glyph is centered horizontally (the green rectangle).
673 \item Furthermore, the glyph is shifted according to values of fields
674 \texttt{left} and \texttt{down}. The ultimate position of the real
675 glyph is indicated by the red rectangle.
678 \caption{The position of the `real' glyph}
683 \item[kern={\{[$j$]=<kern>, ...\}}]
685 \item[glue={\{[$j$]=\{<width>, <stretch>, <shrink>\}, ...\}}]
688 \subsection{Math Font Family}
690 \begin{center}\def\{{\char`\{}\def\}{\char`\}}
693 &Japanese fonts&alphabetic fonts\\
694 font family&\verb+\jfam+&\verb+\fam+\\
695 text size&\tt\textsf{jatextfont}\,=\{<jfam>,<jfont\_cs>\}&\tt\verb+\textfont+<fam>=<font\_cs>\\
696 script size&\tt\textsf{jascriptfont}\,=\{<jfam>,<jfont\_cs>\}&\tt\verb+\scriptfont+<fam>=<font\_cs>\\
697 scriptscript size&\tt\textsf{jascriptscriptfont}\,=\{<jfam>,<jfont\_cs>\}&\tt\verb+\scriptscriptfont+<fam>=<font\_cs>\\
704 \subsection{{\tt\char92 ltjsetparameter} primitive}
705 As noted before, \verb+\ltjsetparameter+ and \verb+\ltjgetparameter+ are
706 primitives for accessing most parameters of Lua\TeX-ja. One of the main
707 reason that Lua\TeX-ja didn't adopted the syntax similar to that of p\TeX\
708 (\textit{e.g.},~\verb+\prebreakpenalty`)=10000+)
709 is the position of \verb+hpack_filter+ callback in the source
710 of Lua\TeX, see Section~\ref{sec-para}.
712 \verb+\ltjsetparameter+ and \verb+\ltjglobalsetparameter+ are primitives
713 for assigning parameters. These take one argument which is a
714 \texttt{<key>=<value>} list. Allowed keys are described in the next
716 The difference between
717 \verb+\ltjsetparameter+ and \verb+\ltjglobalsetparameter+ is only the
719 \verb+\ltjsetparameter+ does a local assignment and
720 \verb+\ltjglobalsetparameter+ does a global one.
721 They also obey the value of \verb+\globaldefs+,
722 like other assignment.
724 \verb+\ltjgetparameter+ is the primitive for acquiring parameters. It
725 always takes a parameter name as first argument, and also takes the
726 additional argument---a character code, for example---in some cases.
728 \ltjgetparameter{differentjfm},
729 \ltjgetparameter{autospacing},
730 \ltjgetparameter{prebreakpenalty}{`)}.
732 \emph{The return value of\/ {\normalfont\tt\char92ltjgetparameter} is
733 always a string}. This is outputted by \texttt{tex.write()}, so any
734 character other than space~` '~(U+0020) has the category code
735 12~(other), while the space has 10~(space).
737 \subsection{List of Parameters}
738 In the following list of parameters, [\verb+\cs+] indicates the counterpart in p\TeX, and each symbol has the following meaning:
741 \item `\dagger' always global
742 \item No mark: the last of paragraph
745 \begin{list}{}{\def\makelabel{\ttfamily}\def\{{\char`\{}\def\}{\char`\}}}
746 \item[\textsf{jcharwidowpenalty}\,=<penalty>] [\verb+\jcharwidowpenalty+]
748 Penalty value for supressing orphans. This penalty is inserted just
749 after the last \textbf{JAchar} which is not regarded as a
750 (Japanese) punctuation mark.
752 \item[\textsf{kcatcode}\,=\{<chr\_code>,<natural number>\}]\
754 An additional attributes having each character whose character code is <chr\_code>.
755 At the present version, the lowermost bit of <natural number> indicates
756 whether the character is considered as a punctuation mark
757 (see the description of \textsf{jcharwidowpenalty} above).
760 \item[\textsf{prebreakpenalty}\,=\{<chr\_code>,<penalty>\}] [\verb+\prebreakpenalty+]
761 \item[\textsf{postbreakpenalty}\,=\{<chr\_code>,<penalty>\}] [\verb+\postbreakpenalty+]
762 \item[\textsf{jatextfont}\,=\{<jfam>,<jfont\_cs>\}] [\verb+\textfont+ in \TeX]
763 \item[\textsf{jascriptfont}\,=\{<jfam>,<jfont\_cs>\}] [\verb+\scriptfont+ in \TeX]
764 \item[\textsf{jascriptscriptfont}\,=\{<jfam>,<jfont\_cs>\}] [\verb+\scriptscriptfont+ in \TeX]
765 \item[\textsf{yjabaselineshift}\,=<dimen>$^\ast$]\
766 \item[\textsf{yalbaselineshift}\,=<dimen>$^\ast$] [\verb+\ybaselineshift+]
768 \item[\textsf{jaxspmode}\,=\{<chr\_code>,<mode>\}] [\verb+\inhibitxspcode+]
770 Setting whether inserting \textsf{xkanjiskip} is allowed before/after a \textbf{JAchar} whose character code is <chr\_code>.
771 The followings are allowed for <mode>:
773 \item[0, \texttt{inhibit}] Insertion of \textsf{xkanjiskip} is inhibited before the charater, nor after the charater.
774 \item[2, \texttt{preonly}] Insertion of \textsf{xkanjiskip} is allowed before the charater, but not after.
775 \item[1, \texttt{postonly}] Insertion of \textsf{xkanjiskip} is allowed after the charater, but not before.
776 \item[3, \texttt{allow}] Insertion of \textsf{xkanjiskip} is allowed before the charater and after the charater.
777 This is the default value.
780 \item[\textsf{alxspmode}\,=\{<chr\_code>,<mode>\}] [\verb+\xspcode+]
782 Setting whether inserting \textsf{xkanjiskip} is allowed before/after a \textbf{ALchar} whose character code is <chr\_code>.
783 The followings are allowed for <mode>:
785 \item[0, \texttt{inhibit}] Insertion of \textsf{xkanjiskip} is inhibited before the charater, nor after the charater.
786 \item[1 \texttt{preonly}] Insertion of \textsf{xkanjiskip} is allowed before the charater, but not after.
787 \item[2 \texttt{postonly}] Insertion of \textsf{xkanjiskip} is allowed after the charater, but not before.
788 \item[3, \texttt{allow}] Insertion of \textsf{xkanjiskip} is allowed before the charater and after the charater.
789 This is the default value.
791 Note that parameters \textsf{jaxspmode} and \textsf{alxspmode} use a common table.
793 \item[\textsf{autospacing}\,=<bool>$^\ast$] [\verb+\autospacing+]
794 \item[\textsf{autoxspacing}\,=<bool>$^\ast$] [\verb+\autoxspacing+]
795 \item[\textsf{kanjiskip}\,=<skip>] [\verb+\kanjiskip+]
796 \item[\textsf{xkanjiskip}\,=<skip>] [\verb+\xkanjiskip+]
797 \item[\textsf{differentjfm}\,=<mode>$^\dagger$]
798 \item[\textsf{jacharrange}\,=<ranges>$^\ast$]
799 \item[\textsf{kansujichar}\,=\{<digit>, <chr\_code>\}] [\verb+\kansujichar+]
803 \section{Other Primitives}
804 \subsection{Compatibility with p\TeX}
805 \begin{list}{}{\def\makelabel{\ttfamily\char92 }}
813 \section{Control Sequences for \LaTeXe}
814 \part{Implementations}\label{part-imp}
815 \section{Storing Parameters}\label{sec-para}
816 \subsection{Used Dimensions and Attributes}
817 Here the following is the list of dimension and attributes which are used in Lua\TeX-ja.
819 \def\makelabel{\ttfamily}
820 \def\dim#1{\item[\char92 #1\ \textrm{(dimension)}]}
821 \def\attr#1{\item[\char92 #1\ \textrm{(attribute)}]}
825 As explained in Subsection~\ref{ssec-plain}, \verb+\jQ+ is equal to
826 $1\,\textrm{Q}=0.25\,\textrm{mm}$, where `Q'~(also called `級') is
827 a unit used in Japanese phototypesetting. So one should not change the value of this dimension.
829 There is also a unit called `歯' which equals to $0.25\,\textrm{mm}$ and
830 used in Japanese phototypesetting. The dimension
831 \verb+\jH+ stores this length, similar to \verb+\jQ+.
832 \dim{ltj@zw} A temporal register for the `full-width' of current Japanese font.
833 \dim{ltj@zh} A temporal register for the `full-height' (usually the sum of height of imaginary body and its depth) of current Japanese font.
835 \attr{ltj@curjfnt} The font index of current Japanese font.
836 \attr{ltj@charclass} The character class of Japanese \textit{glyph\_node}.
837 \attr{ltj@yablshift} The amount of shifting the baseline of alphabetic
838 fonts in scaled point ($2^{-16}\,\textrm{pt}$).
839 \attr{ltj@ykblshift} The amount of shifting the baseline of Japanese
840 fonts in scaled point ($2^{-16}\,\textrm{pt}$).
841 \attr{ltj@autospc} Whether the auto insertion of \textsf{kanjiskip} is allowed at the node.
842 \attr{ltj@autoxspc} Whether the auto insertion of \textsf{xkanjiskip} is allowed at the node.
843 \attr{ltj@icflag} For distinguishing `kinds' of the node. To this
844 attribute, one of the following value is
847 \item[ITALIC (1)] Glues from an itaric correction
848 (\verb+\/+). This distinction of origins of glues (from explicit \verb+\kern+, or from \verb+\/+)
849 is needed in the insertion process of \textsf{xkanjiskip}.
851 \item[KINSOKU (3)] Penalties inserted for the word-wrapping process of Japanese characters (\emph{kinsoku}).
852 \item[FROM\_JFM (4)] Glues/kerns from JFM.
853 \item[LINE\_END (5)] Kerns
854 \item[KANJI\_SKIP (6)] Glues for \textsf{kanjiskip}.
855 \item[XKANJI\_SKIP (7)] Glues for \textsf{xkanjiskip}.
856 \item[PROCESSED (8)] Nodes which is already processed by ...
857 \item[IC\_PROCESSED (9)] Glues from an itaric correction
858 \item[BOXBDD (15)] Glues/kerns that inserted just the beginning or the ending of an hbox or a paragraph.
860 \attr{ltj@kcat$i$} Where $i$~is a natural number which is less than~7.
861 These 7~attributes store bit~vectors indicating which character block is regarded as a block of \textbf{JAchar}s.
864 \subsection{Stack System of Lua\TeX-ja}
865 \paragraph{Background}
866 Lua\TeX-ja has its own stack system, and most parameters of Lua\TeX-ja
867 are stored in it. To clarify the reason, imagine the parameter
868 \textsf{kanjiskip} is stored by a skip, and consider the following
871 \ltjsetparameter{kanjiskip=0pt}ふがふが.%
872 \setbox0=\hbox{\ltjsetparameter{kanjiskip=5pt}ほげほげ}
876 As described in Part~\ref{part-ref}, the only effective value of
877 \textsf{kanjiskip} in an hbox is the latest value, so the value of
878 \textsf{kanjiskip} which applied in the entire hbox should be 5\,pt.
879 However, by the implementation method of Lua\TeX, this `5\,pt' cannot be
880 known from any callbacks. In the \texttt{tex/packaging.w} (which is a
881 file in the source of Lua\TeX), there are the following codes:
885 scaled h; /* height of box */
886 halfword p; /* first node in a box */
887 scaled d; /* max depth */
893 if (cur_list.mode_field == -hmode) {
894 cur_box = filtered_hpack(cur_list.head_field,
895 cur_list.tail_field, saved_value(1),
896 saved_level(1), grp, saved_level(2));
897 subtype(cur_box) = HLIST_SUBTYPE_HBOX;
899 Notice that \verb+unsave+ is executed \emph{before}
900 \verb+filtered_hpack+ (this is where \verb+hpack_filter+ callback is
901 executed): so `5\,pt' in the above source is orphaned at
902 \texttt+unsave+, and hence it can't be accessed from \verb+hpack_filter+
905 \paragraph{The method}
906 The code of stack system is based on that in a post of Dev-luatex mailing list\footnote{%
907 \texttt{[Dev-luatex] tex.currentgrouplevel}, a post at 2008/8/19 by Jonathan Sauer.}.
909 These are two \TeX\ count registers for maintaining informations:
910 \verb+\ltj@@stack+ for the stack level, and \verb+\ltj@@group@level+ for
911 the \TeX's group level when the last assignment was done. Parameters
912 are stored in one big table named \texttt{charprop\_stack\_table}, where
913 \texttt{charprop\_stack\_table[$i$]} stores data of stack level~$i$. If
914 a new stack level is created by \verb+\ltjsetparameter+, all data of the
915 previous level is copied.
917 To resolve the problem mentioned in `Background' above, Lua\TeX-ja uses
918 another thing: When a new stack level is about to be created, a whatsit
919 node whose type, subtype and value are 44~(\textit{user\_defined}),
920 30112, and current group level respectively is appended to the current
921 list (we refer this node by \textit{stack\_flag}). This enables us to
922 know whether assignment is done just inside a hbox. Suppose that the
923 stack level is~$s$ and the \TeX's group level is~$t$ just after the hbox
926 \item If there is no \textit{stack\_flag} node in the list of hbox, then
927 no assignment was occurred inside the hbox. Hence values of
928 parameters at the end of the hbox are stored in the stack
930 \item If there is a \textit{stack\_flag} node whose value is~$t+1$, then
931 an assignment was occurred just inside the hbox group. Hence
932 values of parameters at the end of the hbox are stored in the
934 \item If there are \textit{stack\_flag} nodes but all of their values
935 are more than~$t+1$, then an assignment was occurred in the box,
936 but it is done is `more internal' group. Hence values of
937 parameters at the end of the hbox are stored in the stack
941 Note that to work this trick correctly, assignments to
942 \verb+\ltj@@stack+ and \verb+\ltj@@group@level+ have to be local always,
943 regardless the value of \verb+\globaldefs+.
944 This problem is resolved by using
945 \hbox{\verb+\directlua{tex.globaldefs=0}+} (this assignment is local).