doc/man-en.tex

   1 %#!lualatex
   2 \documentclass[a4paper,titlepage]{article}
   3 \usepackage{booktabs,amsmath}
   4 \usepackage{luatexja}
   5 %\usepackage{luatexja-fontspec}
   6 \usepackage[margin=20mm]{geometry}
   7 \usepackage[unicode=true]{hyperref}
   8
   9 \title{The Lua\TeX-ja package}
  10 \author{The Lua\TeX-ja project team}
  11 \begin{document}
  12 \maketitle
  13 \part{User's manual}
  14 {\Large\bf This documentation is far from complete. It may have many grammatical errors.}
  15
  16 \section{Introduction}
  17
  18 The Lua\TeX-ja package is a macro package for typesetting high-quality Japanese documents in Lua\TeX.
  19
  20 \subsection{Backgrounds}
  21 Traditionally, ASCII p\TeX, an extension of \TeX, and its derivatives are used to typeset Japanese documents in \TeX.
  22 p\TeX is an engine extension of \TeX: so it can produce high-quality Japanese documents without using very complicated macros.
  23 But this point is a mixed blessing: p\TeX\ is left behind from other extensions of \TeX, especially $\varepsilon$-\TeX\ and pdf\TeX,
  24 and from changes about Japanese processing in computers (\textit{e.g.}, the UTF-8 encoding).
  25 Recently the extensions of p\TeX, namely up\TeX\ (Unicode-implementation of p\TeX) and
  26 $\varepsilon$-p\TeX\ (Merging of p\TeX and $\varepsilon$-\TeX\ extension), have developed to fill those gap to some extent,
  27 but gaps are still exist.
  28
  29 However, the appearance of Lua\TeX\ changed the whole situation. With using Lua ``callbacks'',
  30 users can customize the internal processing of Lua\TeX. So there is no need to modify sources of the \TeX\ engine to
  31 support Japanese typesetting: to do this, we only have to write Lua script for appropriate callbacks.
  32
  33 \subsection{Functionality relation with p\TeX}
  34 The Lua\TeX-ja package is much influenced by p\TeX\ engine. The initial target of development was to implement features of p\TeX.
  35 However, \emph{Lua\TeX-ja is not a just porting of p\TeX: Unnatural specifications/behaviors of p\TeX\ were not adopted}.
  36 The followings are major changes from p\TeX:
  37 \begin{itemize}
  38 \item At the present, vertical typesetting, or \textit{tategaki}, is not supported in Lua\TeX-ja.
  39 \end{itemize}
  40 For detailed information, see Part~\ref{part-imp}.
  41
  42 \subsection{Notations}
  43 In this document, the following terms and notations are used:
  44 \begin{itemize}
  45 \item Characters are divided into two types:
  46 \begin{itemize}
  47 \item \textbf{JAchar}: standing for Japanese characters such as Hiragana, Katakana, Kanji and other punctuation marks for Japanese.
  48 \item \textbf{ALchar}: standing for all other characters like alphabets.
  49 \end{itemize}
  50 \item A word in sans-serif font (like \textsf{prebreakpenalty}) represents an internal parameter for Japanese typesetting, and
  51 it is used as a key in \verb+\ltjsetparameter+ command.
  52 \item The word ``primitive'' is used not only for primitives in Lua\TeX, but also for control sequences that defined
  53 in the core module of Lua\TeX-ja.
  54 \end{itemize}
  55
  56 \newpage
  57 \section{Getting Started}
  58 \subsection{Installation}
  59 To install the Lua\TeX-ja\ package, you will need:
  60 \begin{itemize}
  61 \item Lua\TeX, version 0.65.0-beta or later.\\
  62 If you are using \TeX~Live\ 2011 or W32\TeX, you don't have to worry.
  63 \item The source archive or Lua\TeX-ja, of course{\tt:)}
  64 \end{itemize}
  65
  66 The installation methods are as follows:
  67 \begin{enumerate}
  68 \item Download the source archive.
  69
  70 At the present, Lua\TeX-ja has no official release, so you have to retrieve
  71 the archive from the repository.
  72 You can retrieve the Git repository via
  73 \begin{verbatim}
  74 $ git clone git://git.sourceforge.jp/gitroot/luatex-ja/luatexja.git
  75 \end{verbatim}
  76 or download the archive of HEAD in the master branch from
  77 \begin{flushleft}
  78 \url{http://git.sourceforge.jp/view?p=luatex-ja/luatexja.git;a=snapshot;h=HEAD;sf=tgz}.
  79 \end{flushleft}
  80 \item Extract the archive. You will see {\tt src/} and several other sub-directories.
  81 \item Copy all the contents of {\tt src/} into your TEXMF trees.
  82 \item If {\tt mktexlsr} is needed to update the filename database, make it so.
  83 \end{enumerate}
  84
  85 \subsection{Cautions}
  86 \begin{itemize}
  87 \item UTF-8
  88 \item conflicts with unicode-math
  89 \end{itemize}
  90
  91 \subsection{Using in plain \TeX}
  92 To use Lua\TeX-ja in plain \TeX, simply put the following  at the beginning of the document:
  93 \begin{verbatim}
  94 \input luatexja.sty
  95 \end{verbatim}
  96
  97 This does the minimal setting (like {\tt ptex.tex}) for typesetting Japanese documents:
  98 \begin{itemize}
  99 \item The following 6 Japanese fonts are preloaded.
 100 \begin{center}
 101 \begin{tabular}{ccccc}
 102 \toprule
 103 \textbf{classification}&\textbf{font name}&\textbf{13.5\,Q}&\textbf{9.5\,Q}&\textbf{7\,Q}\\\midrule
 104 \textit{mincho}&Ryumin-Light    &\verb+\tenmin+&\verb+\sevenmin+&\verb+\fivemin+\\
 105 \textit{gothic}&GothicBBB-Medium&\verb+\tengt+ &\verb+\sevengt+ &\verb+\fivegt+\\
 106 \bottomrule
 107 \end{tabular}
 108 \end{center}
 109 \begin{itemize}
 110 \item The `Q' is an unit used in Japanese phototypesetting, and $1\,\textrm{Q}=0.25\,\textrm{mm}$.
 111 \item It is widely accepted that the font `Ryumin-Light' and `GothicBBB-Medium' aren't embedded into PDF files, and
 112 the PDF reader substitutes them by some external Japanese font. We adopt this custom to the default setting.
 113 \item size
 114 \end{itemize}
 115 \item A character in Unicode is treated as \textbf{JAchar} if and only if its code-point has more than or equal to U+0100.
 116 \item The amount of glue that are inserted between \textbf{JAchar} and \textbf{ALchar} (the parameter {\sf xkanjiskip}) is
 117 set to
 118 \[
 119  0.25\,\hbox{\verb+\zw+}^{+1\,\text{pt}}_{-1\,\text{pt}} = \frac{27}{32}\,\mathrm{mm}^{+1\,\text{pt}}_{-1\,\text{pt}}.
 120 \]
 121 Here \verb+\zw+ is the virtual width of `current' Japanese font.
 122 \end{itemize}
 123
 124
 125 \subsection{Using in \LaTeX}
 126 \paragraph{\LaTeXe}
 127 Using in \LaTeXe\ is basically same. To set up the minimal environment for Japanese, you only have to load {\tt luatexja.sty}:
 128 \begin{verbatim}
 129 \usepackage{luatexja}
 130 \end{verbatim}
 131 It also does the minimal setting (the counterpart in p\LaTeX\ is  {\tt plfonts.dtx} and {\tt pldefs.ltx}):
 132
 133 \begin{itemize}
 134 \item {\tt JY3} is used as the font encoding for Japanese fonts (in horizontal direction).\\
 135 If vertical typesetting is supported by Lua\TeX-ja, {\tt JT3} will be used for vertical fonts.
 136 \item Two font families {\tt mc} and {\tt gt} are defined:
 137 \begin{center}
 138 \begin{tabular}{ccccc}
 139 \toprule
 140 \textbf{classification}&\textbf{family}&\verb+\mdseries+&\verb+\bfseries+&\textbf{scale}\\\midrule
 141 \textit{mincho}&\tt mc&Ryumin-Light    &GothicBBB-Medium&0.960444\\
 142 \textit{gothic}&\tt gt&GothicBBB-Medium&GothicBBB-Medium&0.960444\\
 143 \bottomrule
 144 \end{tabular}
 145 \end{center}
 146 \item Japanese characters in math mode are typeset by font family {\tt mc}.
 147 \end{itemize}
 148
 149 However, the above setting is not sufficient for Japanese-based documents. To do this,
 150 You are better to use class files other than {\tt article.cls}, {\tt book.cls}, ...
 151 The better alternatives are:
 152 \begin{itemize}
 153 \item BXjscls
 154 \item ltjarticle, ltjbook?
 155 \item ltjsarticle, ltjsbook?
 156 \end{itemize}
 157
 158 \subsection{Changing Fonts}
 159 \paragraph{Remark: Japanese Characters in Math Mode}
 160
 161
 162 \paragraph{plain \TeX}
 163 \paragraph{NFSS2}
 164 \paragraph{fontspec}
 165
 166 \subsection{Changing parameters}
 167
 168
 169 \part{Reference}
 170 \section{Font Metric and Japanese Font}
 171 \section{Parameters}
 172 \section{Other Primitives}
 173 \part{Implementations}\label{part-imp}
 174 \end{document}