2 \documentclass[a4paper,titlepage]{article}
3 \usepackage{amsmath,amssymb,xcolor,pict2e}
4 \usepackage{booktabs,listings,lltjlisting,showexpl}
6 %\usepackage{luatexja-fontspec}
7 \usepackage[margin=20mm]{geometry}
8 \usepackage[unicode=true]{hyperref}
10 \title{The Lua\TeX-ja package}
11 \author{The Lua\TeX-ja project team}
15 basicstyle=\ttfamily\small, pos=o, breaklines=true,
16 numbers=none, rframe={}
20 \def<#1>{{\normalfont\itshape$\langle$#1$\rangle$}}
21 \parskip=\smallskipamount
27 {\Large\bf This documentation is far from complete. It may have many
28 grammatical (and contextual) errors.}
33 \section{Introduction}
35 The Lua\TeX-ja package is a macro package for typesetting high-quality
36 Japanese documents in Lua\TeX.
38 \subsection{Backgrounds}
39 Traditionally, ASCII p\TeX, an extension of \TeX, and its derivatives
40 are used to typeset Japanese documents in \TeX. p\TeX is an engine
41 extension of \TeX: so it can produce high-quality Japanese documents
42 without using very complicated macros. But this point is a mixed
43 blessing: p\TeX\ is left behind from other extensions of \TeX,
44 especially $\varepsilon$-\TeX\ and pdf\TeX, and from changes about
45 Japanese processing in computers (\textit{e.g.}, the UTF-8 encoding).
47 Recently extensions of p\TeX, namely up\TeX\ (Unicode-implementation
48 of p\TeX) and $\varepsilon$-p\TeX\ (merging of p\TeX and
49 $\varepsilon$-\TeX\ extension), have developed to fill those gaps to some
50 extent, but gaps are still exist.
52 However, the appearance of Lua\TeX\ changed the whole situation. With
53 using Lua `callbacks', users can customize the internal processing of
54 Lua\TeX. So there is no need to modify sources of engines to
55 support Japanese typesetting: to do this, we only have to write Lua
56 scripts for appropriate callbacks.
59 \subsection{Major Changes from p\TeX}
60 The Lua\TeX-ja package is under much influence of p\TeX\ engine. The initial
61 target of development was to implement features of p\TeX. However,
62 \emph{Lua\TeX-ja is not a just porting of p\TeX; unnatural
63 specifications/behaviors of p\TeX\ were not adopted}.
65 The followings are major changes from p\TeX:
67 \item A Japanese font is a tuple of a `real' font, a Japanese font
68 metric (\textbf{JFM}, for short), and an optional string called
71 \item In p\TeX, a linebreak after Japanese character is ignored (and
72 doesn't yield a space), since linebreaks (in source files) are
73 permitted almost everywhere in Japanese texts. However, Lua\TeX-ja
74 doesn't have this function completely, because of a specification
76 \item The insertion process of glues/kerns between two Japanese
77 characters and between a Japanese character and other characters
78 (we refer these glues/kerns as \textbf{JAglue}) is rewritten from
82 \item As Lua\TeX's internal character handling is `node-based'
83 (\textit{e.g.}, \verb+of{}fice+ doesn't prevent ligatures), the
84 insertion process of \textbf{JAglue} is now `node-based'.
85 \item Furthermore, nodes between two characters which have no effects in
86 linebreak (\textit{e.g.}, \verb+\special+ node) are ignored in the
88 \item In the process, two Japanese fonts which differ in their `real'
89 fonts only are identified.
91 \item At the present, vertical typesetting (\emph{tategaki}), is not
92 supported in Lua\TeX-ja.
95 For detailed information, see Part~\ref{part-imp}.
97 \subsection{Notations}
98 In this document, the following terms and notations are used:
100 \item Characters are divided into two types:
102 \item \textbf{JAchar}: standing for Japanese characters such as
103 Hiragana, Katakana, Kanji and other punctuation marks for
105 \item \textbf{ALchar}: standing for all other characters like alphabets.
107 We say `alphabetic fonts' for fonts used in \textbf{ALchar}, and `Japanese fonts' for fonts used in \textbf{JAchar}.
109 \item A word in a sans-serif font (like \textsf{prebreakpenalty})
110 represents an internal parameter for Japanese typesetting, and it
111 is used as a key in \verb+\ltjsetparameter+ command.
112 \item The word `primitive' is used not only for primitives in Lua\TeX,
113 but also for control sequences that defined in the core module of
117 \subsection{About the project}
118 \paragraph{Project Wiki} \url{http://sourceforge.jp/projects/luatex-ja/wiki/FrontPage%28en%29}
120 This project is hosted by SourceForge.JP.
132 \section{Getting Started}
133 \subsection{Installation}
134 To install the Lua\TeX-ja\ package, you will need:
136 \item Lua\TeX\ (version 0.65.0-beta or later) and its supporting packages.\\
137 If you are using \TeX~Live\ 2011 or W32\TeX, you don't have to worry.
138 \item The source archive of Lua\TeX-ja, of course{\tt:)}
141 The installation methods are as follows:
143 \item Download the source archive.
145 At the present, Lua\TeX-ja has no official release, so you have to retrieve
146 the archive from the repository.
147 You can retrieve the Git repository via
149 $ git clone git://git.sourceforge.jp/gitroot/luatex-ja/luatexja.git
151 or download the archive of HEAD in \texttt{master} branch from
153 \url{http://git.sourceforge.jp/view?p=luatex-ja/luatexja.git;a=snapshot;h=HEAD;sf=tgz}.
155 \item Extract the archive. You will see {\tt src/} and several other sub-directories.
156 \item Copy all the contents of {\tt src/} into one of your \texttt{TEXMF} tree.
157 \item If {\tt mktexlsr} is needed to update the filename database, make it so.
160 \subsection{Cautions}
162 \item The encoding of your source file must be UTF-8.
163 \item Not well-tested. In particular, the default setting of the range
164 of \textbf{JAchar} in the present version does not coexist with
165 other packages which use Unicode fonts.
168 \subsection{Using in plain \TeX}
169 To use Lua\TeX-ja in plain \TeX, simply put the following at the beginning of the document:
174 This does minimal settings (like {\tt ptex.tex}) for typesetting Japanese documents:
176 \item The following 6~Japanese fonts are preloaded:
178 \begin{tabular}{ccccc}
180 \textbf{classification}&\textbf{font name}&\textbf{13.5\,Q}&\textbf{9.5\,Q}&\textbf{7\,Q}\\\midrule
181 \emph{mincho}&Ryumin-Light &\verb+\tenmin+&\verb+\sevenmin+&\verb+\fivemin+\\
182 \emph{gothic}&GothicBBB-Medium&\verb+\tengt+ &\verb+\sevengt+ &\verb+\fivegt+\\
187 \item The `Q' is an unit used in Japanese phototypesetting, and
188 $1\,\textrm{Q}=0.25\,\textrm{mm}$. This length is stored in a
189 dimension \verb+\jQ+.
191 \item It is widely accepted that the font `Ryumin-Light' and
192 `GothicBBB-Medium' aren't embedded into PDF files, and PDF reader
193 substitute them by some external Japanese fonts (\textit{e.g.},
194 Kozuka Mincho is used in Adobe Reader). We adopt this custom to
196 \item You may notice that size of above fonts is slightly smaller than
197 their alphabetic counterparts: for example, the size
198 \verb+\texmin+ is $13.5\,\textrm{Q}\simeq 9.60444\,\textrm{pt}$. This is intensional: ...
200 \item A character in Unicode is treated as \textbf{JAchar} if and only
201 if its code-point has more than or equal to U+0100.
202 \item The amount of glue that are inserted between a \textbf{JAchar} and
203 an \textbf{ALchar} (the parameter \textsf{xkanjiskip}) is set to
205 0.25\,\hbox{\verb+\zw+}^{+1\,\text{pt}}_{-1\,\text{pt}} = \frac{27}{32}\,\mathrm{mm}^{+1\,\text{pt}}_{-1\,\text{pt}}.
207 Here \verb+\zw+ is the counterpart of \texttt{em} for Japanese fonts, that is, the length of `full-width' in current Japanese font.
210 \subsection{Using in \LaTeX}
212 Using in \LaTeXe\ is basically same. To set up the minimal environment
213 for Japanese, you only have to load {\tt luatexja.sty}:
215 \usepackage{luatexja}
217 It also does minimal settings (counterparts in p\LaTeX\ are {\tt
218 plfonts.dtx} and {\tt pldefs.ltx}):
221 \item {\tt JY3} is the font encoding for Japanese fonts (in horizontal direction).\\
222 When vertical typesetting is supported by Lua\TeX-ja in the future, {\tt JT3} will be used for vertical fonts.
223 \item Two font families {\tt mc} and {\tt gt} are defined:
225 \begin{tabular}{ccccc}
227 \textbf{classification}&\textbf{family}&\verb+\mdseries+&\verb+\bfseries+&\textbf{scale}\\\midrule
228 \emph{mincho}&\tt mc&Ryumin-Light &GothicBBB-Medium&0.960444\\
229 \emph{gothic}&\tt gt&GothicBBB-Medium&GothicBBB-Medium&0.960444\\
233 \textbf{Note on fonts in bold series}
235 \item Japanese characters in math mode are typeset by the font family {\tt mc}.
238 However, above settings are not sufficient for Japanese-based
239 documents. To typeset Japanese-based documents, You are better to use
240 class files other than {\tt article.cls}, {\tt book.cls}, ... At the
241 present, BXjscls (\texttt{bxjsarticle.cls} and \texttt{bxjsbook.cls}, by
242 Takayuki Yato) are better alternative. It is not determined whether
243 Lua\TeX-ja will develop and contain counterparts of major classes used
244 in p\TeX\ (including jsclasses by Haruhiko Okumura).
246 \subsection{Changing Fonts}
247 \paragraph{Remark: Japanese Characters in Math Mode}
248 Since p\TeX\ supports Japanese characters in math mode, there are
249 sources like the following:
252 $f_{高温}$~($f_{\text{high temperature}}$).
253 \[ y=(x-1)^2+2\quad{}よって\quad y>0 \]
254 $5\in{}素:=\{\,p\in\mathbb N:\text{$p$ is a prime}\,\}$.
257 We (the project members of Lua\TeX-ja) think that using
258 Japanese characters in math mode are allowed if and only if these are used as identifiers.
259 In this point of view,
261 \item The lines 1~and~2 above are not correct, since `高温' in above is used as a textual label, and
262 `よって' is used as a conjunction.
263 \item However, the line~3 is correct, since `素' is used as an identifier.
265 Hence, in our opinion, the above input should be corrected as:
268 ($f_{\text{high temperature}}$).
270 \mathrel{\text{よって}}\quad y>0 \]
271 $5\in{}素:=\{\,p\in\mathbb N:\text{$p$ is a prime}\,\}$.
273 %BUG?: \{\}がなければ「素」がでない.上の段落の「よって」もでてない.
274 We also believe that using Japanese characters as identifiers is rare,
275 hence we don't describe how to change Japanese fonts in math mode in
276 this chapter. For the method, please see Part~\ref{part-ref}.
279 \paragraph{plain \TeX}
280 To change Japanese fonts in plain \TeX, you must use the primitive
281 \verb+\jfont+. So please see Part~\ref{part-ref}.
285 For \LaTeXe, Lua\TeX-ja simply adopted the font selection system from that
286 of p\LaTeXe\ (in {\tt plfonts.dtx}).
288 \item Two control sequences \verb+\mcdefault+ and \verb+\gtdefault+ are
289 used to specify the default font families for \emph{mincho} and
290 \emph{gothic}, respectively. Default values: \texttt{mc} for
291 \verb+\mcdefault+ and \texttt{gt} for \verb+\gtdefault+.
292 \item Commands \verb+\fontfamily+, \verb+\fontseries+,
293 \verb+\fontshape+ and \verb+\selectfont+ can be used to change
294 attributes of Japanese fonts.
296 \begin{tabular}{ccccc}
298 &\textbf{encoding}&\textbf{family}&\textbf{series}&\textbf{shape}\\\midrule
300 &\verb+\romanencoding+&\verb+\romanfamily+&\verb+\romanseries+&\verb+\romanshape+\\
302 &\verb+\kanjiencoding+&\verb+\kanjifamily+&\verb+\kanjiseries+&\verb+\kanjishape+\\
303 both&---&--&\verb+\fontseries+&\verb+\fontshape+\\
304 auto select&\verb+\fontencoding+&\verb+\fontfamily+&---&---\\
308 \item For defining a Japanese font family, use \verb+\DeclareKanjiFamily+
309 instead of \verb+\DeclareFontFamily+.
313 To coexist with \texttt{fontspec} package, it is needed to load
314 \texttt{luatexja-fontspec} package in the preamble. This additional
315 package automatically loads \texttt{luatexja} and \texttt{fontspec}
318 In \texttt{luatexja-fontspec} package, the following 7~commands are defined as
319 counterparts of original commands in \texttt{fontspec}:
321 \begin{tabular}{ccccc}
324 &\verb+\jfontspec+&\verb+\setmainjfont+&\verb+\setsansjfont+&\verb+\newjfontfamily+\\
326 &\verb+\fontspec+&\verb+\setmainfont+&\verb+\setsansfont+&\verb+\newfontfamily+\\
329 &\verb+\newjfontface+&\verb+\defaultjfontfeatures+&\verb+\addjfontfeatures+\\
331 &\verb+\newfontface+&\verb+\defaultfontfeatures+&\verb+\addfontfeatures+\\
338 Note that there is no command named \verb+\setmonojfont+, since it is
339 popular for Japanese fonts that nearly all Japanese glyphs have same widths.
342 \section{Changing Parameters}
343 There are many parameters in Lua\TeX-ja. And due to the behavior of Lua\TeX,
344 most of them are not stored as internal register of \TeX, but as an
345 original storage system in Lua\TeX-ja. Hence, to assign or acquire those
346 parameters, you have to use commands \verb+\ltjsetparameter+ and
347 \verb+\ltjgetparameter+.
349 \subsection{Editing the range of \textbf{JAchar}}
350 As noted before, the default setting is:
352 A character in Unicode is treated as \textbf{JAchar},\\
354 code-point has more than or equal to U+0100.
356 $\uparrow$ TODO: CHANGE THIS!
362 \subsection{\textsf{kanjiskip} and \textsf{xkanjiskip}}\label{subs-kskip}
363 \textbf{JAglue} is divided into the following three categories:
365 \item Glues/kerns specified in JFM. If \verb+\inhibitglue+ is issued around a Japanese character,
366 this glue will be not inserted at the place.
367 \item The default glue which inserted between two \textbf{JAchar}s ({\sf
369 \item The default glue which inserted between a \textbf{JAchar} and an
370 \textbf{ALchar} (\textsf{xkanjiskip}).
372 The value (a skip) of \textsf{kanjiskip} or \textsf{xkanjiskip} can be
373 changed as the following.
375 \ltjsetparameter{kanjiskip={0pt plus 0.4pt minus 0.4pt},
376 xkanjiskip={0.25\zw plus 1pt minus 1pt}}
380 It may occur that JFM contains the data of `ideal width of {\sf
381 kanjiskip}' and/or `ideal width of \textsf{xkanjiskip}'.
382 To use these data from JFM, set the value of \textsf{kanjiskip} or
383 \textsf{xkanjiskip} to \verb+\maxdimen+.
385 \subsection{Insertion Setting of \textsf{xkanjiskip}}
386 It is not desirable that \textsf{xkanjiskip} is inserted between every
387 boundary between \textbf{JAchar}s and \textbf{ALchar}s. For example,
388 \textsf{xkanjiskip} should not be inserted after opening parenthesis
389 (\textit{e.g.}, compare `(あ' and `(\hskip\ltjgetparameter{xkanjiskip}あ').
391 Lua\TeX-ja can control whether \textsf{xkanjiskip} can be inserted
392 before/after a character, by changing \textsf{jaxspmode} for \textbf{JAchar}s and
393 \textsf{alxspmode} parameters \textbf{ALchar}s respectively.
395 \ltjsetparameter{jaxspmode={`あ,preonly}, alxspmode={`\!,postonly}}
399 The second argument {\tt preonly} means `the insertion of
400 \textsf{xkanjiskip} is allowed before this character, but not after'.
401 the other possible values are {\tt postonly}, {\tt allow} and {\tt
402 inhibit}. For the compatibility with p\TeX, natural numbers between
403 0~and~3 are also allowed as the second argument\footnote{But we don't
404 recommend this: since numbers 1~and~2 have opposite meanings in
405 \textsf{jaxspmode} and \textsf{alxspmode}.}.
407 If you want to enable/disable all insertions of \textsf{kanjiskip} and
408 \textsf{xkanjiskip}, set \textsf{autospacing} and \textsf{autoxspacing}
409 parameters to {\tt false}, respectively.
412 \subsection{Shifting Baseline}
413 To make a match between a Japanese font and an alphabetic font, sometimes
414 shifting of the baseline of one of the pair is needed. In p\TeX, this is achieved
415 by setting \verb+\ybaselineshift+ to a non-zero length (the
416 baseline of alphabetic fonts is shifted below). However, for documents
417 whose main language is not Japanese, it is good to shift the baseline of
418 Japanese fonts, but not that of alphabetic fonts.
419 Because of this, Lua\TeX-ja can independently set the shifting amount
420 of the baseline of alphabetic fonts (\textsf{yalbaselineshift}
421 parameter) and that of Japanese fonts (\textsf{yjabaselineshift}
425 \vrule width 150pt height 0.4pt depth 0pt\hskip-120pt
426 \ltjsetparameter{yjabaselineshift=0pt, yalbaselineshift=0pt}abcあいう
427 \ltjsetparameter{yjabaselineshift=5pt, yalbaselineshift=2pt}abcあいう
429 Here the horizontal line in above is the baseline of a line.
431 There is an interesting side-effect: characters in different size can be
432 vertically aligned center in a line, by setting two parameters appropriately.
433 The following is an example (beware the value is not well tuned):
437 \ltjsetparameter{yjabaselineshift=-1pt,
438 yalbaselineshift=-1pt}
444 \subsection{`tombow'}
445 `tombow' is a mark for indicating 4~corners and horizontal/vertical
446 center of the paper. p\LaTeX and this Lua\TeX-ja support `tombow' by
447 their kernel. The following steps are needed to typeset tombow:
450 \item First, define the banner which will be printed at the upper left
451 of the paper. This is done by assigning a token list to
452 \verb+\@bannertoken+.
454 For example, the following sets banner as `{\tt filename (2012-01-01 17:01)}':
458 \hour\time \divide\hour by 60 \@tempcnta\hour \multiply\@tempcnta 60\relax
459 \minute\time \advance\minute-\@tempcnta
461 \jobname\space(\number\year-\two@digits\month-\two@digits\day
462 \space\two@digits\hour:\two@digits\minute)}%
469 \part{Reference}\label{part-ref}
470 \section{Font Metric and Japanese Font}
471 \subsection{\texttt{\char92jfont} primitive}
472 To load a font as a Japanese font, you must use the
473 \verb+\jfont+ primitive instead of~\verb+\font+, while
474 \verb+\jfont+ admits the same syntax used in~\verb+\font+.
475 Lua\TeX-ja automatically loads \texttt{luaotfload} package,
476 so TrueType/OpenType fonts with features can be used for Japanese fonts:
478 \jfont\tradgt={file:ipaexg.ttf:script=latn;%
479 +trad;jfm=ujis} at 14pt
483 Note that the defined control sequence
484 (\verb+\tradgt+ in the example above) using \verb+\jfont+ is not a
485 \textit{font\_def} token, hence the input like
486 \verb+\fontname\tradgt+ causes a error. We denote control sequences which are defined in \verb+\jfont+
490 Besides \texttt{file:}\ and \texttt{name:}\ prefixes, \texttt{psft:}\ can
491 be used a prefix in \verb+\jfont+ (and~\verb+\font+) primitive. Using
492 this prefix, you can specify a font that has its name only and is not
493 related to any real font.
495 Mainly, use of this \texttt{psft:}\ prefix is for using non-embedding `standard' Japanese fonts (Ryumin-Light and GothicBBB-Medium).
503 \subsection{Structure of JFM file}
504 A JFM file is a Lua script which has only one function call:
506 luatexja.jfont.define_jfm { ... }
508 Real data are stored in the table which indicated above by
509 \verb+{ ... }+. So, the rest of this subsection are devoted to describe the
510 structure of this table. Note that all lengths in a JFM file are
511 floating-point numbers in design-size unit.
513 \begin{list}{}{\def\makelabel{\ttfamily}\def\{{\char`\{}\def\}{\char`\}}}
514 \item[dir=<direction>] (required)
516 The direction of JFM. At the present, only \texttt{'yoko'} is supported.
518 \item[zw=<length>] (required)
520 The amount of the length of the `full-width'.
522 \item[zh=<length>] (required)
524 \item[kanjiskip=\{<natural>, <stretch>, <shrink>\}] (optional)
526 This field specifies the `ideal' amount of \textsf{kanjiskip}. As noted
527 in Subsection~\ref{subs-kskip}, if the parameter
528 \textsf{kanjiskip} is \verb+\maxdimen+, the value specified
529 in this field is actually used (if this field is not specified in
530 JFM, it is regarded as 0\,pt). Note that <stretch> and <shrink>
531 fields are in design-size unit too.
534 \item[xkanjiskip=\{<natural>, <stretch>, <shrink>\}] (optional)
536 Like the \texttt{kanjiskip} field, this field specifies the `ideal'
537 amount of \textsf{xkanjiskip}.
541 Besides from above fields, a JFM file have several sub-tables those
542 indices are natural numbers. The table indexed by~$i\in\omega$ stores
543 informations of `character class'~$i$. At least, the character class~0 is
544 always present, so each JFM file must have a sub-table whose index is
545 \texttt{[0]}. Each sub-table (its numerical index is denoted by $i$) has
546 the following fields:
548 \begin{list}{}{\def\makelabel{\ttfamily}\def\{{\char`\{}\def\}{\char`\}}}
549 \item[chars=\{<character>, ...\}] (required except character class~0)
551 This field is a list of characters which are in this character
552 type~$i$. This field is not required if $i=0$, since all
553 \textbf{JAchar} which are not in any character class other
554 than 0 (hence, the character class~0 contains most of
555 \textbf{JAchar}s). In the list, a character can be
556 specified by its code number, or by the character itself
557 (as a string of length~1).
559 In addition to those `real' characters, the following `imaginary
560 characters' can be specified in the list:
562 \item[width=<length>, height=<length>, depth=<length>, italic=<length>]\ (required)
564 Specify width of characters in character class~$i$, height, depth and
565 the amount of italic correction. All characters in character class~$i$ are regarded that its width, height and depth are
566 as values of these fields.
567 But there is one exception: if \texttt{'prop'} is specified in \texttt{width} field, width of a character becomes that of its `real' glyph
569 \item[left=<length>, down=<length>, align=<align>]\
571 These fields are for adjusting the position of the `real' glyph. Legal
572 values of \texttt{align} field are \texttt{'left'},
573 \texttt{'middle'} and \texttt{'right'}. If one of these
574 3~fields are omitted, \texttt{left} and \texttt{down} are
575 treated as~0, and \texttt{align} field is treated as
577 The effects of these 3~fields are indicated in Figure~\ref{fig-pos}.
579 In most cases, \texttt{left} and \texttt{down} fields are~0, while
580 it is not uncommon that the \texttt{align} field is \texttt{'middle'} or \texttt{'right'}.
581 For example, setting the \texttt{align} field to \texttt{'right'} is practically needed
582 when the current character class is the class for opening delimiters'.
584 \begin{minipage}{0.4\textwidth}%
585 \begin{center}\unitlength=10pt\small
586 \begin{picture}(15,12)(-1,-4)
587 \color{black!10!white}% real glyph :step1
588 \put(0,0){\vrule width 12\unitlength height 8\unitlength depth 3\unitlength}
590 \color{red!20!white}% real glyph :step1
591 \put(-1,-1.5){\vrule width 6\unitlength height 7\unitlength depth 2.5\unitlength}
593 \color{red}% real glyph
595 \put(-1,-1.5){\vector(0,1){7}\vector(0,-1){2.5}\vector(1,0){6}}
596 \put(5,-1.5){\line(0,1){7}\line(0,-1){2.5}}
597 \put(-1,5.5){\line(1,0){6}}
598 \put(-1,-4){\line(1,0){6}}
600 \color{green!20!white}% real glyph :step1
601 \put(3,0){\vrule width 6\unitlength height 7\unitlength depth 2.5\unitlength}
603 \color{black}% real glyph :step1
605 \put(0,0){\vector(0,1){8}\line(0,-1){3}\vector(1,0){12}}
606 \put(12,0){\line(0,1){8}\vector(0,-1){3}}
607 \put(0,8){\line(1,0){12}}
608 \put(0,-3){\line(1,0){12}}
609 \put(0.2,4){\makebox(0,0)[l]{\texttt{height}}}
610 \put(12.2,-1.5){\makebox(0,0)[l]{\texttt{depth}}}
611 \put(6,0.2){\makebox(0,0)[b]{\texttt{width}}}
613 \color{green!50!black}% real glyph :step1
615 \put(3,0){\vector(0,1){7}\vector(0,-1){2.5}\vector(1,0){6}}
616 \put(9,0){\line(0,1){7}\line(0,-1){2.5}}
617 \put(3,7){\line(1,0){6}}
618 \put(3,-2.5){\line(1,0){6}}
620 \savebox{\eqdist}(0,0)[b]{%
622 \put(-0.08,0.2){\line(0,-1){0.4}}%
623 \put(0.08,0.2){\line(0,-1){0.4}}}
624 \put(1.5,0){\usebox{\eqdist}}
625 \put(10.5,0){\usebox{\eqdist}}
627 \color{blue}% shifted
629 \put(3,-1.5){\vector(-1,0){4}}
630 \put(1,-1.7){\makebox(0,0)[t]{\texttt{left}}}
631 \put(3,0){\vector(0,-1){1.5}}
632 \put(3.2,-0.75){\makebox(0,0)[l]{\texttt{down}}}
636 \begin{minipage}{0.6\textwidth}%
637 Consider a node containing Japanese character whose value of the \texttt{align}
638 field is \texttt{'middle'}.
640 \item The black rectangle is a frame of the node.
641 Its width, height and depth are specified by JFM.
642 \item Since the \texttt{align} field is \texttt{'middle'},
643 the `real' glyph is centered horizontally (the green rectangle).
644 \item Furthermore, the glyph is shifted according to values of fields
645 \texttt{left} and \texttt{down}. The ultimate position of the real
646 glyph is indicated by the red rectangle.
649 \caption{The position of the `real' glyph}
654 \item[kern={\{[$j$]=<kern>, ...\}}]
656 \item[glue={\{[$j$]=\{<width>, <stretch>, <shrink>\}, ...\}}]
659 \subsection{Math Font Family}
661 \begin{center}\def\{{\char`\{}\def\}{\char`\}}
664 &Japanese fonts&alphabetic fonts\\
665 font family&\verb+\jfam+&\verb+\fam+\\
666 text size&\tt\textsf{jatextfont}\,=\{<jfam>,<jfont\_cs>\}&\tt\verb+\textfont+<fam>=<font\_cs>\\
667 script size&\tt\textsf{jascriptfont}\,=\{<jfam>,<jfont\_cs>\}&\tt\verb+\scriptfont+<fam>=<font\_cs>\\
668 scriptscript size&\tt\textsf{jascriptscriptfont}\,=\{<jfam>,<jfont\_cs>\}&\tt\verb+\scriptscriptfont+<fam>=<font\_cs>\\
675 \subsection{{\tt\char92 ltjsetparameter} primitive}
676 As noted before, \verb+\ltjsetparameter+ and \verb+\ltjgetparameter+ are
677 primitives for accessing most parameters of Lua\TeX-ja. One of the main
678 reason that Lua\TeX-ja didn't adopted the syntax similar to that of p\TeX\
679 (\textit{e.g.},~\verb+\prebreakpenalty`)=10000+)
680 is the position of \verb+hpack_filter+ callback in the source
681 of Lua\TeX, see Section~\ref{sec-para}.
683 \verb+\ltjsetparameter+ and \verb+\ltjglobalsetparameter+ are primitives
684 for assigning parameters. These take one argument which is a
685 \texttt{<key>=<value>} list. Allowed keys are described in the next
687 The difference between
688 \verb+\ltjsetparameter+ and \verb+\ltjglobalsetparameter+ is only the
690 \verb+\ltjsetparameter+ does a local assignment and
691 \verb+\ltjglobalsetparameter+ does a global one.
692 They also obey the value of \verb+\globaldefs+,
693 like other assignment.
695 \verb+\ltjgetparameter+ is the primitive for acquiring parameters. It
696 always takes a parameter name as first argument, and also takes the
697 additional argument---a character code, for example---in some cases.
699 \ltjgetparameter{differentjfm},
700 \ltjgetparameter{autospacing},
701 \ltjgetparameter{prebreakpenalty}{`)}.
703 \emph{The return value of\/ {\normalfont\tt\char92ltjgetparameter} is
704 always a string}. This is outputted by \texttt{tex.write()}, so any
705 character other than space~` '~(U+0020) has the category code
706 12~(other), while the space has 10~(space).
708 \subsection{List of Parameters}
709 In the following list of parameters,
712 \item `\dagger' always global
713 \item No mark: the last of paragraph
716 \begin{list}{}{\def\makelabel{\ttfamily}\def\{{\char`\{}\def\}{\char`\}}}
717 \item[\textsf{kcatcode}\,=\{<chr\_code>,<value>\}]
718 \item[\textsf{prebreakpenalty}\,=\{<chr\_code>,<penalty>\}]
719 \item[\textsf{postbreakpenalty}\,=\{<chr\_code>,<penalty>\}]
720 \item[\textsf{jatextfont}\,=\{<jfam>,<jfont\_cs>\}]
721 \item[\textsf{jascriptfont}\,=\{<jfam>,<jfont\_cs>\}]
722 \item[\textsf{jascriptscriptfont}\,=\{<jfam>,<jfont\_cs>\}]
723 \item[\textsf{yjabaselineshift}\,=<dimen>$^\ast$]
724 \item[\textsf{yalbaselineshift}\,=<dimen>$^\ast$]
725 \item[\textsf{jaxspmode}\,=\{<chr\_code>,<mode>\}]
726 \item[\textsf{alxspmode}\,=\{<chr\_code>,<mode>\}]
727 \item[\textsf{autospacing}\,=<bool>$^\ast$]
728 \item[\textsf{autoxspacing}\,=<bool>$^\ast$]
729 \item[\textsf{kanjiskip}\,=<skip>]
730 \item[\textsf{xkanjiskip}\,=<skip>]
731 \item[\textsf{jcharwidowpenalty}\,=<penalty>]
732 \item[\textsf{differentjfm}\,=<mode>$^\dagger$]
733 \item[\textsf{jacharrange}\,=<ranges>$^\ast$]
735 \section{Other Primitives}
736 \section{Control Sequences for \LaTeXe}
737 \part{Implementations}\label{part-imp}
738 \section{Storing Parameters}\label{sec-para}
739 \subsection{Used Dimensions and Attributes}
740 Here the following is the list of dimension and attributes which are used in Lua\TeX-ja.
742 \def\makelabel{\ttfamily}
743 \def\dim#1{\item[\char92 #1\ \textrm{(dimension)}]}
744 \def\attr#1{\item[\char92 #1\ \textrm{(attribute)}]}
752 \attr{ltj@curjfnt} The font index of current Japanese font.
753 \attr{ltj@charclass} The character class of Japanese \textit{glyph\_node}.
754 \attr{ltj@yablshift} The amount of shifting the baseline of alphabetic
755 fonts in scaled point ($2^{-16}\,\textrm{pt}$).
756 \attr{ltj@ykblshift} The amount of shifting the baseline of Japanese
757 fonts in scaled point ($2^{-16}\,\textrm{pt}$).
758 \attr{ltj@autospc} Whether the auto insertion of \textsf{kanjiskip} is allowed at the node.
759 \attr{ltj@autoxspc} Whether the auto insertion of \textsf{xkanjiskip} is allowed at the node.
760 \attr{ltj@icflag} For distinguishing `kinds' of the node. To this
761 attribute, one of the following value is
769 \item[KANJI\_SKIP (6)]
770 \item[XKANJI\_SKIP (7)]
772 \item[IC\_PROCESSED (9)]
775 \attr{ltj@kcat$i$} Where $i$~is a natural number which is less than~8.
776 These 8~attributes store bit~vectors indicating ...
779 \subsection{Stack System of Lua\TeX-ja}
780 \paragraph{Background}
781 Lua\TeX-ja has its own stack system, and most parameters of Lua\TeX-ja
782 are stored in it. To clarify the reason, imagine the parameter
783 \textsf{kanjiskip} is stored by a skip, and consider the following
786 \ltjsetparameter{kanjiskip=0pt}ふがふが.%
787 \setbox0=\hbox{\ltjsetparameter{kanjiskip=5pt}ほげほげ}
791 As described in Part~\ref{part-ref}, the only effective value of
792 \textsf{kanjiskip} in an hbox is the latest value, so the value of
793 \textsf{kanjiskip} which applied in the entire hbox should be 5\,pt.
794 However, by the implementation method of Lua\TeX, this `5\,pt' cannot be
795 known from any callbacks. In the \texttt{tex/packaging.w} (which is a
796 file in the source of Lua\TeX), there are the following codes:
800 scaled h; /* height of box */
801 halfword p; /* first node in a box */
802 scaled d; /* max depth */
808 if (cur_list.mode_field == -hmode) {
809 cur_box = filtered_hpack(cur_list.head_field,
810 cur_list.tail_field, saved_value(1),
811 saved_level(1), grp, saved_level(2));
812 subtype(cur_box) = HLIST_SUBTYPE_HBOX;
814 Notice that \verb+unsave+ is executed \emph{before}
815 \verb+filtered_hpack+ (this is where \verb+hpack_filter+ callback is
816 executed): so `5\,pt' in the above source is orphaned at
817 \texttt+unsave+, and hence it can't be accessed from \verb+hpack_filter+
820 \paragraph{The method}
821 The code of stack system is based on that in a post of Dev-luatex mailing list\footnote{%
822 \texttt{[Dev-luatex] tex.currentgrouplevel}, a post at 2008/8/19 by Jonathan Sauer.}.
824 These are two \TeX\ count registers for maintaining informations:
825 \verb+\ltj@@stack+ for the stack level, and \verb+\ltj@@group@level+ for
826 the \TeX's group level when the last assignment was done. Parameters
827 are stored in one big table named \texttt{charprop\_stack\_table}, where
828 \texttt{charprop\_stack\_table[$i$]} stores data of stack level~$i$. If
829 a new stack level is created by \verb+\ltjsetparameter+, all data of the
830 previous level is copied.
832 To resolve the problem mentioned in `Background' above, Lua\TeX-ja uses
833 another thing: When a new stack level is about to be created, a whatsit
834 node whose type, subtype and value are 44~(\textit{user\_defined}),
835 30112, and current group level respectively is appended to the current
836 list (we refer this node by \textit{stack\_flag}). This enables us to
837 know whether assignment is done just inside a hbox. Suppose that the
838 stack level is~$s$ and the \TeX's group level is~$t$ just after the hbox
841 \item If there is no \textit{stack\_flag} node in the list of hbox, then
842 no assignment was occurred inside the hbox. Hence values of
843 parameters at the end of the hbox are stored in the stack
845 \item If there is a \textit{stack\_flag} node whose value is~$t+1$, then
846 an assignment was occurred just inside the hbox group. Hence
847 values of parameters at the end of the hbox are stored in the
849 \item If there are \textit{stack\_flag} nodes but all of their values
850 are more than~$t+1$, then an assignment was occurred in the box,
851 but it is done is `more internal' group. Hence values of
852 parameters at the end of the hbox are stored in the stack
856 Note that to work this trick correctly, assignments to \verb+\ltj@@stack+ and \verb+\ltj@@group@level+ have to be local always.