summaryrefslogtreecommitdiff
path: root/language/japanese/BX/bxcjkjatype/bxcjkjatype.tex
blob: 2b153fd64871020c6735cf11dc69e4eb6c32d6ea (plain)
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
% pdfLaTeX document; UTF-8
\documentclass[a4paper]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{lmodern,textcomp}
\usepackage{geometry}
\usepackage{xcolor}
\usepackage[unicode,colorlinks]{hyperref}
\hypersetup{linkcolor=blue!75!black,urlcolor=green!45!black}
\usepackage{shortvrb}
\MakeShortVerb{\|}
\usepackage{verbatim}
\newenvironment{myverbatim}
  {\begin{quote}\small\verbatim}
  {\endverbatim\end{quote}}
\newcommand*{\Cs}[1]{\texttt{\textbackslash #1}}
\newcommand{\PkgVersion}{0.5}
\newcommand{\PkgDate}{2023/07/23}
\newcommand{\Pkg}[1]{\textsf{#1}}
\newcommand{\Meta}[1]{$\langle$\textit{#1}$\rangle$}
\newcommand{\Note}{\par\noindent \emph{Note:}\quad}
\newcommand{\Means}{:\hspace{1em plus 1em}}
\newcommand{\wbr}{\linebreak[0]}
\providecommand{\pTeX}{p\TeX}
\providecommand{\pLaTeX}{p\LaTeX}
\providecommand{\pdfTeX}{pdf\/\TeX}
%-----------------------------------------------------------
\begin{document}
\title{The \Pkg{bxcjkjatype} Package}
\author{Takayuki YATO (aka.~``ZR'')}
\date{v\PkgVersion\quad[\PkgDate]}
\maketitle

\begin{abstract}
This package provides working configuration of the \Pkg{CJK} package
suitable for Japanese typesetting of moderate quality.
Moreover, it facilitates use of the \Pkg{CJK} package for {\pLaTeX}
users, by providing commands that are similar to those used by the
{\pLaTeX} kernel and some other packages used with it.
\end{abstract}

\tableofcontents

%===========================================================
\section{Package Loading}
\label{sec:loading}

\begin{verbatim}
\usepackage[<option>,...]{bxcjkjatype}
\end{verbatim}

The available options are described hereafter.

%-------------------
\subsection{Options for auto-wrapping by CJK environments}

These options wrap the document body with a |CJK(*)|
environment automatically and safely.
They are suitable
when CJK needs to be effective in the whole document,
or some ``moving arguments'' hold CJK text.

\begin{itemize}
\item |whole|, |wholeCJK*|\Means
  Wraps the whole document body with a |CJK*| environment.
  \Note Precisely speaking,
  it wraps with |\begin{uCJK*}|\ldots\wbr|\end{uCJK*}|.
\item |wholeCJK|\Means
  Wraps the whole document body with a |CJK| environment.
  \Note Precisely speaking,
  it wraps with |\begin{uCJK}|\ldots\wbr|\end{uCJK}|.
\item |nowhole| (default)\Means
  Negation of |wholeCJK*| or |wholeCJK|.
\end{itemize}

%-------------------
\subsection{Options for ``auto-tilde''}

The \Pkg{CJK} package does not support auto-insertion of ``shibuaki''
(a thin space between alphabetic and ideographic letters)
and thus authors must manually insert ``shibuaki''.
To help them \Pkg{CJK} package provides a mechanism
to switch the meaning of the tilde character ``|~|''
between a non-breaking space (the original meaning)
and ``shibuaki''.
The |\autotilde| command changes ``|~|'' to ``shibuaki''%
\footnote{\Cs{standardtilde} cancels the effect of \Cs{CJKtilde}
  and changes ``\texttt{\textasciitilde}'' back to non-breaking space.
  \Cs{nbs} always inserts non-breaking space,
  which is useful in CJK environemtns.}.

The option |autotilde| triggers automatic invocation of |\CJKtilde|,
which makes ``|~|'' in CJK environments insert ``shibuaki''
by default.

\begin{itemize}
\item |autotilde|\Means
  Makes |\CJKtilde| invoked at the beginning of every |CJK(*)|
  environment.
\item |noautotilde| (default)\Means
  Negation of |autotilde|.
\end{itemize}

%-------------------
\subsection{Options for configuring ``shibuaki'' in PDF strings}

As explained above,
in {\LaTeX} grammar ``|~|'' represents a non-breaking space.
Accordingly, when the \Pkg{hyperref} package generates PDF strings,
``|~|'' in {\LaTeX} text will be converted to a space character.

However, when |\CJKtilde| is effective
the meaning of ``|~|'' changes to ``shibuaki''.
The ``shibuaki'' is device on typesetting
and is not a space as text data,
and thus the behavior of \Pkg{hyperref} is undesirable.
When this package is loaded, ``|~|'' with |\CJKtilde| effective
is tailored to be deleted at conversion to PDF strings.

Moreover this behavior can be configured by options.

\begin{itemize}
\item |noCJKtildeasspace| (default)\Means
  When |\CJKtilde| is effective,
  ``|~|'' will be deleted in PDF strings.
\item |CJKtildeasspace|\Means
  When |\CJKtilde| is effective,
  ``|~|'' will be converted to a space character in PDF strings.
  \Note This is the original behavior of \Pkg{hyperref}.
\end{itemize}

%-------------------
\subsection{Options for font-mapping}

You can use preset font mappings in the same way as in the
\href{http://www.ctan.org/pkg/pxchfon}{\Pkg{pxchfon} package}.
Please refer to the manual of that package for detailed explanation
of this feature.

\begin{itemize}
\item |oneweight|, |nooneweight|\Means
  The same as in \Pkg{pxchfon}.
\item You can use font preset options (such as |ms|) which are available
  in \Pkg{pxchfon} (except obsolete ones).
\item |ttfname=|\Meta{pattern}\Means
  Specifies the pattern of the TTF font names which are used when TTC
  substitution (Section~\ref{ssec:ttfname}) is employed.

\item |ipaex-type1|\Means
  Disables the font management of this package and directly uses the
  families provided by the \Pkg{ipaex-type1} package,
  namely |ipxm| and |ipxg|.
  In this setting the value of |\mcdefault| is |ipxm| and the value of
  |\gtdefault| and |\mgdefault| is |ipxg|, so that the higher level
  commands (such as |\sffamily| and |\gtfamily|) can work correctly.
\end{itemize}

%-------------------
\subsection{Options for CJK font scaling}

\begin{itemize}
\item |scale=|\Meta{real}\Means
  Sets the scaling factor for CJK fonts.
\end{itemize}

\Note When using version 0.3 or later,
one can employ the scaling even with the
|ipaex-type1| option.

%-------------------
\subsection{Other options}

\begin{itemize}
\item |everypage|\Means
  Outputs the font mapping information on every page of the resulted
  DVI document.
  Available only with |dvipdfmx| driver.
\item |noeverypage| (default)\Means
  Negation of |everypage|.
\item Driver options\Means
  |pdftex|, |dvipdfmx|, |dvips| and |none| are available.
  The driver setting is relevant only when using font mappings other
  than the default one (ipaex-type1 fonts), so you need not care of
  drivers in using default fonts.
  Moreover, non-default font mappings are supported only by |pdftex|
  and |dvipdfmx|, and these two values are auto-detected
  (|pdftex| is default in PDF mode and |dvipdfmx| in DVI mode).
  Thus you will never need to specify the driver.
\item |substmingoth|\Means
  Applies the substituion of families |min|, |goth| and |maru|
  (used conventionally for Japanese) with families |mc|, |gt| and |mg|
  (standard in this package).
\item |nosubstmingoth| (default)\Means
  Negation of |substmingoth|.
\item |boldbyembolden| (default)\Means
  Changes the implementation of |\CJKbold| (pseudo-bold) from
  ``overstriking'' to ``synthetic emboldening''.
\item |noboldbyembolden|\Means
  Negation of |boldbyembolden|.
\end{itemize}

%-------------------
\subsection{TTC substitution}
\label{ssec:ttfname}

The {\pdfTeX} engine does not support fonts in TTC format.
Thus when you want to use TTC fonts for this package,
all you can do is to decompose a TTC font
into several TTF fonts.

Moreover there is another problem when you use this package.
The decomposed TTF files have names
different from the original TTC font,
which means that
the preset settings (options such as |moba-moga|) no longer work.
The |ttfname| option is a workaround for this problem.

The |ttfname| option key must have a file name pattern,
which is a string containing (exactly) one occurrence of ``|*|''
and one occurrence of a numeral string,
such as ``|*_1|'' and ``|TEMP-*-00.TTF|''.
(If the pattern does not have an extension, ``|.ttf|'' is appended.)

For example, when the option |ttfname=*_1| is given, the font
``index 0 of mogam.ttc'' will map to ``mogam\_1.ttf'', and similarly,
``index 1'' to ``mogam\_2.ttf''
(the numeral part is incremented) and so on.


%===========================================================
\section{Usage}
\label{sec:usage}

%-------------------
\subsection{Selecting CJK fonts}

The present package provides three ``generic'' CJK font familie 
in the same way as {\pLaTeX} plus the
\href{http://www.ctan.org/pkg/japanese-otf}{\Pkg{japanese-otf} package}:
Mincho family (|\mcfamily|), Gothic family (|\gtfamily|), and
Maru-gothic family (|\mgfamily|).
In default setting, the font set from the \Pkg{ipaex-type1} package
is allocated;
Mincho family uses IPAex Mincho font, and Gothic and Maru-gothic
families use IPAex Gothic font.
This allocation can be altered by users.

\begin{itemize}
\item |\mcfamily|\Means
  Changes the CJK family to Mincho family.
  \Note Equivalent to |\CJKfamily{\mcdefault}|.
\item |\gtfamily|\Means
  Changes the CJK family to Gothic family.
  \Note Equivalent to |\CJKfamily{\gtdefault}|.
\item |\mgfamily|\Means
  Changes the CJK family to Maru-gothic family.
  \Note Equivalent to |\CJKfamily{\mgdefault}|.
\end{itemize}

More advanced commands:

\begin{itemize}
\item |\mcdefault|/|\gtdefault|/|\mgdefault|\Means
  The names of CJK families corresponding to the three generic families.
  In the standard allocation their values are
  |mc|/\wbr|gt|/\wbr|mg| respectively
  and the allocation is used as default.
\item
  |\setCJKfamilydefault{|\Meta{CJK-family}|}|\Means
  Declares the default CJK family.
  This default value is used when family names are missing in some
  commands, such as |\CJKfamily{}| and
  |\begin{CJK}{UTF8}{}|.
  The (redefined) |\normalfont| also switches the CJK family to the
  family specified by this command.

  The default value of this default family is
  the ``counterpart'' (Section~\ref{ssec:sync-families}) of the
  alphabetic font family which is in effect at the beginning of the
  document body.
\end{itemize}

%-------------------
\subsection{Synchronization of CJK and non-CJK families}
\label{ssec:sync-families}

The \Pkg{CJK} package (and {\pTeX} engine) manages separate
``current families'' for CJK and alphabetic (non-CJK) families.
While this treatment has its merit, synchronization of the two
``current families'' is convenient in many cases.
Accordingly, the present package redefines some of the {\LaTeX}
commands that switches current alphabetic font families so that
the CJK family will be switched to the counterpart of the current
alphabetic family, where the ``counterpart'' is defined as follows:

\begin{itemize}
\item |\rmfamily| (Serif) → |\mcfamily| (Mincho)
\item |\sffamily| (Sans-serif) → |\gtfamily| (Gothic)
\item |\ttfamily| (Monospace) → |\gtfamily| (Gothic)
\item The counterpart of the other families is |\mcfamily|.
\end{itemize}

Redefined commands:

\begin{itemize}
\item |\rmfamily|/|\sffamily|/|\ttfamily|\Means
  Changes the CJK family to the counterpart of the alphabetic font
  family after executing the original function.
\item |\normalfont|\Means
  Changes the CJK family to the default CJK family that is specified
  by the |\setCJKfamilydefault| command.
\end{itemize}

There are shorthand forms of |CJK|/\wbr|CJK*| environments:

\begin{itemize}
\item |\begin{uCJK*}|\ldots|\end{uCJK*}|\Means
  Equivalent to:
\begin{verbatim}
\begin{CJK*}{UTF8}{<counterpart>}...\end{CJK*}
\end{verbatim}
  where |<counterpart>| means the counterpart of the current alphabetic
  font family.

  Note that this is \emph{not} equivalent to
\begin{verbatim}
\begin{CJK*}{UTF8}{}...\end{CJK*}
\end{verbatim}
  structure, which uses the default CJK family.
\item |\begin{uCJK}|\ldots|\end{uCJK}|\Means
  Equivalent to:
\begin{verbatim}
\begin{CJK}{UTF8}{counterpart}...\end{CJK}
\end{verbatim}
\end{itemize}

%-------------------
\subsection{Font mapping}

The usage of these commands are the same as in the \Pkg{pxchfon}
package.
Please refer to the manual of that package for detail.

\begin{itemize}
\item |\setminchofont{|\Meta{id}|]{|\Meta{font-file}|}|
\item |\setgothicfont{|\Meta{id}|]{|\Meta{font-file}|}|
\item |\setmarugothicfont{|\Meta{id}|]{|\Meta{font-file}|}|
\item |\setmediumminchofont{|\Meta{id}|]{|\Meta{font-file}|}|
\item |\setboldminchofont{|\Meta{id}|]{|\Meta{font-file}|}|
\item |\setmediumgothicfont{|\Meta{id}|]{|\Meta{font-file}|}|
\item |\setboldgothicfont{|\Meta{id}|]{|\Meta{font-file}|}|
\item |\setxboldgothicfont{|\Meta{id}|]{|\Meta{font-file}|}|
\end{itemize}

However there is a major limitation as to the use of font mapping with
the {\pdfTeX} engine.
You can use only TrueType fonts and moreover TTC format is not allowed.
(You can use any flavor of OpenType fonts when using dvipdfmx.)

\Note The present package does not support the light-weight Mincho
font, and thus the |\setlightminchofont| command does nothing useful.

%-------------------
\subsection{Other commands}

\begin{itemize}
\item |\UTF{|\Meta{hexadecimal-number}|}|\Means
  Inputs a CJK character through Unicode codepoint value.
  |\UTF{5B57}| is equivalent to |\Unicode{"5B}{"57}|.
\item |\CJKforce{|\Meta{character}\ldots|}|\Means
  Afterwards treats the characters given in the argument as CJK
  characters (printed using CJK fonts).
\item |\CJKunforce{|\Meta{character}\ldots|}|\Means
  Cancels the effect of the |\CJKforce| command.
\item |\@|\Meta{character}\Means
  Treats the next character (only that occurrence) as a CJK character,
  when the character is outside the ASCII range; othersize the
  standard meaning of |\@| is retained.
\item |\CJKecglue|\Means
  Inserts a ``shibuaki'' space.
  This will be invoked by |~| when |\CJKtilde| is in effect.
  This command can be redefined by users to adjust the value of
  shibuaki space, just as |\CJKglue| can be redefined to adjust
  inter-ideographic space.

  For example, you can write:
\begin{verbatim}
\renewcommand{\CJKecglue}{\hspace{0.125em minus 0.125em}}
\end{verbatim}
\end{itemize}

%===========================================================
\section{Remarks}
\label{sec:remarks}

\begin{itemize}
\item The standard font families provided by this package does
  \emph{not} support vertical writing, even when using default
  ipaex-type1 font set.
  However, the families provided by \Pkg{ipaex-type1}
  (|ipxm| and |ipxg|) do support vertical writing, and you can
  utilize these families directly by specifying |ipaex-type1| option.
\end{itemize}

%===========================================================
\end{document}