summaryrefslogtreecommitdiff
path: root/macros/generic/fixjfm/fixjfm-doc.tex
blob: d52f836721267edd92d7587d3435117d7c4cf0eb (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


% fixjfm-doc.tex

% !TeX encoding = UTF-8
% !TeX program  = pdfLaTeX

\RequirePackage{fix-cm}

\documentclass[a4paper]{article}

\usepackage{amsfonts}
\usepackage[OT1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage[UKenglish]{babel}
\usepackage[babel]{microtype}
\usepackage{etoolbox}
\usepackage{booktabs}

\AtBeginEnvironment{verbatim}{\microtypesetup{activate=false}}

\abovetopsep=\medskipamount

\newcommand\NormalSans{\normalfont\sffamily}
\newcommand\pkg[1]{{\protect\NormalSans#1}}

\newcommand\pTeX{p\kern-0.15em\TeX}
\newcommand\e{\ensuremath{\varepsilon}}
\newcommand\epTeX{\e-\pTeX}
\newcommand\ApTeX{A\kern-0.1em\pTeX}
\newcommand\pLaTeX{p\LaTeX}

\newcommand\FwBox{\ensuremath{\square}\hskip0em plus 0.05em\relax}

\newbox\fwbox
\setbox\fwbox=\hbox{\FwBox}

\newcommand\TwoFwBoxes{\FwBox\FwBox}
\newcommand\FourFwBoxes{\TwoFwBoxes\TwoFwBoxes}

\newcommand\DemoText{%
  \FourFwBoxes\FourFwBoxes\FourFwBoxes\FourFwBoxes
  \FourFwBoxes\FourFwBoxes\ensuremath{\square}}

\newcommand\demotext[1]{%
  \begin{minipage}{20\wd\fwbox}\centering
    \fbox{\begin{minipage}{16\wd\fwbox}%
      \hskip2\wd\fwbox\relax\DemoText\par
      \leavevmode\hbox to#1\wd\fwbox{\hss``}\DemoText''\par
      \hskip2\wd\fwbox\relax\DemoText\par
    \end{minipage}}%
  \end{minipage}}

\newcommand\yes{yes}
\newcommand\no{no}

\newcommand\eclmvtt{test}

\font\eclmvtt=ec-lmvtt10 at 10pt

\newcommand\demoinput[2]{\TwoFwBoxes
  \hbox to 1\wd\fwbox{\texttt{,}\hss}#1%
  \hbox to 1\wd\fwbox{\hss{\eclmvtt``}}\TwoFwBoxes
  \hbox to 1\wd\fwbox{{\eclmvtt''}\hss}#2}

\newcommand\demooutput[2]{%
  \TwoFwBoxes\hbox to#1\wd\fwbox{,\hss{#2``}}\TwoFwBoxes{#2''}}

\newcommand\sans{test}

\font\sans=SourceSansPro-Semibold-tlf-ot1 at 10pt

\newenvironment{history}[1]%
  {\noindent\textbf{#1}\nopagebreak\relax\begin{itemize}}%
  {\end{itemize}}

\begin{document}

\title{The \pkg{fixjfm} package%
  \thanks{CTAN Homepage: \texttt{https://ctan.org/pkg/fixjfm}}
  \thanks{Repository: \texttt{https://github.com/Man-Ting-Fang/fixjfm}}}
\author{Yue \textsc{Zhang}}
\date{2018-03-24\quad v0.8}

\maketitle

\begin{abstract}
This package fixes several bugs in the JFM format. Both \LaTeX\ and plain \TeX\
are supported.
\end{abstract}

\section{Introduction}

The JFM format is an extension of the TFM format and is used for typesetting CJK
characters with *\pTeX. It works perfectly under almost all circumstances, but
there are still at least two bugs:
\begin{itemize}
\item Bug 1: the indentation is incorrect if the first character of a paragraph
  is an opening fullwidth punctuation mark, see Figure \ref{fig:ind};
\item Bug 2: the spacing between two consecutive fullwidth punctuation marks
  cannot be adjusted if the font is changed there, see Table \ref{tab:adj}.
\end{itemize}
\begin{figure}[!ht]\centering
\demotext{3}\demotext{2.5}
\caption{Comparison of the indentation produced without this package (left) and
  with this package (right)}
\label{fig:ind}
\end{figure}
\vskip-20pt\relax
\begin{table}[!ht]\centering
\caption{Comparison of the adjustment of the spacing between two consecutive
  fullwidth punctuation marks}
\label{tab:adj}
\begin{tabular}{ccll}
\toprule
Font change & This package        & Input          & Output                  \\
\midrule
\no         & either \no\ or \yes & \demoinput{}{} & \demooutput{1.5}{}      \\
\yes        & \no                 & \demoinput{\texttt{\char"5C textgt%
                                      \char"7B}}{\texttt{\char"7D}}
                                                   & \demooutput{2}{\sans}   \\
\yes        & \yes                & \demoinput{\texttt{\char"5C textgt%
                                      \char"7B}}{\texttt{\char"7D}}
                                                   & \demooutput{1.5}{\sans} \\
\bottomrule
\end{tabular}
\end{table}
It seems that macro is the easiest solution to these problems. However, the
second bug can only be fixed when using \e-(u)\pTeX\ or \ApTeX\ (under most, but
not all circumstances), because the primitive \verb|\lastnodechar| which is
introduced by \epTeX\ is required. Anyhow, using this package with \pTeX\ or any
one of its derivatives does not hurt. Please also keep in mind that owing to
technical limitations, this package is not a panacea.

There is also another improvement: \verb|\leavevmode| is redefined as
\verb|\quitvmode| if the latter is available as a primitive (among all *\pTeX\
engines to date, only \ApTeX\ has \verb|\quitvmode|). So after loading this
package, you can always use \verb|\leavevmode| and need not worry about
\verb|\quitvmode|. If you are wondering about what the difference between them
is, please see \textit{The pdf\TeX\ user manual}.

\section{Basic usage}

This package has no options. It is recommended that this package should be
loaded before any other packages. If you are using \LaTeX, load this package at
the beginning of your preamble:
\begin{verbatim}
    \documentclass...
    \usepackage{fixjfm}
\end{verbatim}
or even before \verb|\documentclass| (use \verb|\RequirePackage| instead):
\begin{verbatim}
    \RequirePackage{fixjfm}
    \documentclass...
\end{verbatim}
If you are using plain \TeX, put the following line near the beginning of your
\verb|.tex| file:
\begin{verbatim}
    \input fixjfm.sty
\end{verbatim}

After loading this package, the first bug mentioned above can be automatically
fixed under most (but not all) circumstances. If you find that it cannot be
fixed somewhere, you can add \verb|\<| manually before the opening fullwidth
punctuation mark which begins the paragraph.

In the case of the second bug mentioned above, the situation is different. If
you are using \LaTeX, \verb|\textmc| and \verb|\textgt| are redefined by default
so that the bug can be automatically fixed (again, under most, but not all
circumstances). However, \verb|\mcfamily| and \verb|\gtfamily| remain unchanged.
The difference here is similar to that between, say, \verb|\textit| and
\verb|\itshape|: \verb|\textit| automatically takes care of any necessary italic
correction on either side of the argument, while \verb|\itshape| does nothing
about that. Just like \verb|\itshape| and \verb|\/|, you should add
\begin{verbatim}
    \fixjfmspacing
\end{verbatim}
by yourself after the font change that appears between two consecutive fullwidth
punctuation marks. For example:
\begin{trivlist}\item\relax{\ttfamily\hskip2em}\TwoFwBoxes
\hbox to 1\wd\fwbox{\texttt{,}\hss}\verb|{\gtfamily\fixjfmspacing|%
\hbox to 1\wd\fwbox{\hss{\eclmvtt``}}\TwoFwBoxes
\hbox to 1\wd\fwbox{{\eclmvtt''}\hss}\verb|}\fixjfmspacing|%
\hbox to 1\wd\fwbox{\hss{\eclmvtt``}}\TwoFwBoxes
\hbox to 1\wd\fwbox{{\eclmvtt''}\hss}%
\end{trivlist}
If you are using plain \TeX, you should always add \verb|\fixjfmspacing| by
yourself, because plain (*p)\TeX\ does not have \verb|\textmc|, \verb|\textgt|,
or the like.

If you are using \LaTeX\ and prefer the standard version\footnote{Since v0.3,
the ``standard version'' is similar to \pkg{jsclasses} and \pkg{bxjscls} rather
than (u)\pLaTeX.} of \verb|\textmc| and \verb|\textgt|, you can declare
\begin{verbatim}
    \UseStandardCJKTextFontCommands
\end{verbatim}
In contrast,
\begin{verbatim}
    \UseFixJFMCJKTextFontCommands
\end{verbatim}
redefines \verb|\textmc| and \verb|\textgt| and is declared by default. These
two commands are important. Consider the following example:
\begin{trivlist}
\item\relax{\ttfamily\hskip2em}\verb|\textgt{\Large |\TwoFwBoxes\verb|}|
\end{trivlist}
It causes a fatal error when the \pkg{fixjfm} version of \verb|\textgt| is used.
The solution is to change \verb|\textgt| back to the standard version, either
globally or locally:
\begin{trivlist}\itemsep=0pt\relax\parsep=0pt\relax
\item\relax{\ttfamily\hskip2em}%
\verb|\UseFixJFMCJKTextFontCommands   \textgt{|\TwoFwBoxes\verb|}|
\item\relax{\ttfamily\hskip2em}%
\verb|\UseStandardCJKTextFontCommands \textgt{\Large |\TwoFwBoxes\verb|}|
\item\relax{\ttfamily\hskip2em}%
\verb|\UseFixJFMCJKTextFontCommands   \textgt{|\TwoFwBoxes\verb|}|
\item\relax{\ttfamily\hskip1.5em}%
\verb|{\UseStandardCJKTextFontCommands \textgt{\Large |\TwoFwBoxes\verb|}}|
\end{trivlist}

\section{Advanced usage}

The spacing between two consecutive fullwidth punctuation marks is produced by
a glue item specified in the corresponding JFM file. However, if the font is
changed there, the JFM format cannot work correctly, so this package puts
another glue item there to adjust the spacing. The natural width of the new glue
item is calculated according to the corresponding JFM file, so you need not
worry about it. However, the stretch and shrink components cannot be extracted
from JFM, so the following two commands are provided:
\begin{verbatim}
    \SetFixJFMSpacingStretch
    \SetFixJFMSpacingShrink
\end{verbatim}
They expect an argument specifying how much space to stretch and shrink
respectively. This package sets both of them to \verb|0.05zw| by default.

Macro writers may want to (re)define commands like the \pkg{fixjfm} version of
\verb|\textmc| and \verb|\textgt| for CJK text fonts, thus the following command
is provided:
\begin{verbatim}
    \DeclareFixJFMCJKTextFontCommand
\end{verbatim}
It is similar to \LaTeX's \verb|\DeclareTextFontCommand|. For example,
\verb|\textmc| is redefined by this package as follows:
\begin{verbatim}
    \DeclareFixJFMCJKTextFontCommand\textmc{\mcfamily}
\end{verbatim}
and \verb|\textgt| is similar. In contrast,
\begin{verbatim}
    \DeclareStandardCJKTextFontCommand
\end{verbatim}
(re)defines a CJK text font command like the standard version of \verb|\textmc|
and \verb|\textgt|. But there is a more convenient way: Suppose that you have a
new CJK text font command \verb|\xyfamily|, then
\begin{verbatim}
    \AppendToUseXCJKTextFontCommands{\textxy}{\xyfamily}
\end{verbatim}
will do all you need and makes \verb|\Use...CJKTextFontCommands| also apply to
\verb|\textxy|. This command and \verb|\Use...CJKTextFontCommands| can be given
in any order, so you do not need to redeclare
\verb|\UseFixJFMCJKTextFontCommands| (which is the default behaviour) if that is
what you want.

Finally, there are several macros that may be useful for \TeX nicians:
\begin{verbatim}
    \FixJFMSpacing
    \fixjfmparindent
    \FixJFMParindent
    \EveryparPreHook
    \EveryparPostHook
    \ifUseFixJFMCJKTextFontCommands
    \ifUseStandardCJKTextFontCommands
\end{verbatim}
They are worthless for ordinary use. If you are interested in them, please have
a look at the source code.

\section{Compatibility}

The \LaTeX-only package \pkg{bxjaprnind} also focuses on the first bug mentioned
above. It provides some additional functionalities and also supports some other
\TeX\ engines. This package can be used together with \pkg{bxjaprnind}, but
please note that if you prefer \pkg{bxjaprnind}, you have to load it before this
package, and vice versa, in case both of them are loaded.

\section{Acknowledgements}

The source code of this package is mostly taken from\footnote{This package also
improves the code slightly.} (in alphabetical order):
\epTeX\ Wiki (Hironori Kitagawa):
\begin{verbatim}
    https://ja.osdn.net/projects/eptex/wiki/lastnodechar
\end{verbatim}
\pkg{everyhook} (Stephen Checkoway):
\begin{verbatim}
    https://ctan.org/pkg/everyhook
\end{verbatim}
\pkg{jsclasses} (Haruhiko Okumura et al.):
\begin{verbatim}
    https://ctan.org/pkg/jsclasses
\end{verbatim}
and \pkg{platex} (Kazuki Maeda \& Japanese \TeX\ Development Community):
\begin{verbatim}
    https://ctan.org/pkg/platex
\end{verbatim}
Many thanks to the authors of these packages. I would also like to thank
Hironobu Yamashita, who helped me a lot.

\section{History}

\begin{history}{2017-09-02 v0.2}
\item First public version.
\end{history}

\begin{history}{2017-09-04 v0.3}
\item Fixes.
\item Make \verb|\UseFixJFMCJKTextFontCommands| and
  \verb|\UseStandardCJKTextFontCommands| also available after
  \verb|\begin{document}|.
\item Add \verb|\DeclareStandardCJKTextFontCommand| and use it for redefining
  the standard version of \verb|\textmc| and \verb|\textgt|.
\end{history}
Thanks to Hironobu Yamashita for suggesting all these changes:
\begin{verbatim}
    https://github.com/Man-Ting-Fang/fixjfm/pull/1
\end{verbatim}

\begin{history}{2017-09-04 v0.4}
\item Bug fix, thanks to Hironobu Yamashita:
\end{history}
\begin{verbatim}
    https://github.com/Man-Ting-Fang/fixjfm/pull/2
\end{verbatim}

\begin{history}{2017-09-12 v0.5}
\item Bug fix, thanks to Hironobu Yamashita:
\end{history}
\begin{verbatim}
    https://github.com/Man-Ting-Fang/fixjfm/issues/3
\end{verbatim}

\begin{history}{2017-09-21 v0.6}
\item Bug fix and improvement, thanks to Hironobu Yamashita:
\end{history}
\begin{verbatim}
    https://github.com/Man-Ting-Fang/fixjfm/pull/4
\end{verbatim}

\begin{history}{2017-12-27 v0.7}
\item Add \verb|\ifUseFixJFMCJKTextFontCommands| and
  \verb|\ifUseStandardCJKTextFontCommands|.
\end{history}

\begin{history}{2018-03-24 v0.8}
\item Add \verb|\AppendToUseXCJKTextFontCommands|.
\end{history}

\end{document}