path: root/macros/generic/fixjfm/fixjfm-doc.tex

% 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}