summaryrefslogtreecommitdiff
path: root/macros/xetex/latex/interchar/interchar.tex
blob: 641d9f0c6085ca07c97f9816a716dbf1ef00e7ac (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
% -*- coding: utf-8 -*-
% Package interchar: managing character class schemes of XeTeX
% Copyright (C) 2015 Zou Hu <zohooo@yeah.net>
%
% Please report bugs, problems, and suggestions via
%     https://github.com/zohooo/interchar
%
% This file may be distributed and/or modified under the conditions
% of the LaTeX Project Public License, either version 1.3 of this
% license or (at your option) any later version. The latest version
% of this license is in
%     http://www.latex-project.org/lppl.txt
\documentclass{article}
\usepackage[b5paper,margin=17mm]{geometry}
\usepackage{xcolor,hyperref,float,makedoc,niceverb,interchar}
\hypersetup{
   colorlinks,
   citecolor = teal,
   linkcolor = blue,
   urlcolor = purple,
   pdfstartview = {FitH},
   bookmarksnumbered
}
\begin{document}

\title{Documentation for package \texttt{interchar}
\footnote{Version 0.2. Please report bugs via \url{https://github.com/zohooo/interchar}.}}
\author{Zou Hu (zohooo@yeah.net)}
\maketitle
\tableofcontents

\section{Introduction}

With XeTeX\rq s character class mechanism, we could put characters into different classes,
and insert some tokens to the input stream between characters in one class and those in
another class. This mechanism is originally used for switching fonts and adjusting spaces.
But it has many other useful applications.

By default, all characters are of class 0, except CJK ideographs are of class 1, CJK left
punctuation of class 2, CJK right punctuation of class 3, text boundaries (glues, kerns,
maths, boxes, etc.) of class 255, and several characters of class 256 (this class is ignored).

\MakeNormal\`
\newintercharclass{\myclass}
\intercharclass{`\o}{\myclass}
\interchartoks{0}{\myclass}{\bgroup\color{red}}
\interchartoks{255}{\myclass}{\bgroup\color{red}}
\interchartoks{\myclass}{0}{\egroup}
\interchartoks{\myclass}{255}{\egroup}
\intercharstate{1}
\MakeActive\`
Package 'interchar' is written for making character class mechanism more easy to use. For example,
after loading the package with `\usepackage{interchar}', you may change the color of every
occurrences of character \texttt{o}:
\intercharstate[foo]{0}
\begin{verbatim}
\newintercharclass{\myclass}
\intercharclass{`\o}{\myclass}
\interchartoks{0}{\myclass}{\bgroup\color{red}}
\interchartoks{255}{\myclass}{\bgroup\color{red}}
\interchartoks{\myclass}{0}{\egroup}
\interchartoks{\myclass}{255}{\egroup}
\intercharstate{1}
\end{verbatim}

There are some existing packages using this mechanism, such as 'polyglossia', 'xeCJK' and
'xesearch'. But since one character could only be put into one single class, when loading two
or more of these packages simultaneously, it would be very likely that some conflicts occur.

Package 'interchar' also provides some migration commands for these packages. With minor changes
these packages should be compatible with 'interchar', and users could switch between different
character class schemes when loading these packages at the same time.

\section{Commands for normal users}

\begin{itemize}
  \item |\newintercharscheme{<scheme>}| creates a new char class scheme. For example,
        \begin{verbatim}\newintercharscheme{foo}\end{verbatim}
        There is a prebuilt `default' scheme which you need not to create it.
        The first argument of the other commands in this section is optional;
        its default value is `default'.
  \item |\intercharstate[<scheme>]{<state-code>}| changes current scheme.
        If '<state-code>' is positive, changes current scheme to `<scheme>';
        otherwise, changes current scheme to `default'. For example,
        \begin{verbatim}\intercharstate[foo]{1}\end{verbatim}
  \item |\getintercharstate[<scheme>]{\cs}| gets current state of the specified scheme
        and store the state code in `\cs'. For example,
        \begin{verbatim}\getintercharstate[foo]{\mystate}\end{verbatim}
  \item |\newintercharclass[<scheme>]{\cs}| creates a new char class in the specified scheme
        and stores the class number in `\cs'. For example,
        \begin{verbatim}\newintercharclass[foo]{\myclass}\end{verbatim}
  \item |\intercharclass[<scheme>]{<char-range>}{<char-class>}| moves all characters within
        `<char-range>' to the class `<char-class>' in the specified scheme. For example,
\begin{verbatim}
\intercharclass[foo]{`\@}{255}
\intercharclass[foo]{`\a-`\z}{\myclass}
\end{verbatim}
  \item |\getintercharclass[<scheme>]{<char-code>}{\cs}| gets the class number of the specified
        character in the specified scheme, and stores the result in `\cs'. For example,
        \begin{verbatim}\getintercharclass[foo]{`\@}{\result}\end{verbatim}
  \item |\interchartoks[<scheme>]{<char-class-1>}{<char-class-2>}{<tokens>}| defines tokens to be
        inserted between `<char-class-1>' and `<char-class-2>' (in that order) in the specified
        scheme. For example,
\begin{verbatim}
\interchartoks[foo]{0}{\myclass}{\bgroup\color{red}}
\interchartoks[foo]{\myclass}{0}{\egroup}
\end{verbatim}
  \item |\getinterchartoks[<scheme>]{<char-class-1>}{<char-class-2>}{\cs}| gets the tokens to be
        inserted between `<char-class-1>' and `<char-class-2>' in the specified scheme, and stores
        the result in `\cs'. For example,
        \begin{verbatim}\getinterchartoks[foo]{0}{\myclass}{\mytoks}\end{verbatim}
\end{itemize}

\section{Commands for macro writers}

For macro writers, we provide |\NewIntercharScheme| command which is an alias of user command `\newintercharscheme'. When you write `\NewIntercharScheme{foo}', 'interchar' package also 
creates the following migration commands for you:

\begin{table}[H]
\MakeNormal\& \MakeNormal\` \MakeNormal\| \catcode`\?=13 \let?=| \MakeActive\` \MakeActive\|
\renewcommand{\arraystretch}{1.4}
\begin{tabular}{?l?l?}
  \hline
  \textbf{Migration Command} & \textbf{Analogous to Commands} \\ \hline
  |\FooIntercharState = <state-code>| & `\XeTeXinterchartokenstate' \\
  |\GetFooIntercharState| & `\the\XeTeXinterchartokenstate' \\
  |\NewFooIntercharClass <control-sequence>| & `\newXeTeXintercharclass' \\
  |\FooIntercharClass <char-code> = <char-class>| & `\XeTeXcharclass' \\
  |\GetFooIntercharClass <char-code>| & `\the\XeTeXcharclass'. \\
  |\FooIntercharToks <class1> <class2> = {<toks>}| & `\XeTeXinterchartoks' \\
  |\GetFooIntercharToks <class1> <class2>| & `\the\XeTeXinterchartoks' \\
  \hline
\end{tabular}
\end{table}

Within the command specifications in the above table, all of the equal signs `='
and most of the spaces are optional.

If you are the author of package 'foo' which use XeTeX\rq s char class mechanism,
with some minor changes you could make your package compatible with other packages.

\begin{enumerate}
  \item Add the following lines to the beginning of your package file:
\begin{verbatim}
\ifdefined\NewIntercharScheme
    \NewIntercharScheme{foo}%
\else
    \let \FooIntercharState = \XeTeXinterchartokenstate
    \def \GetFooIntercharState {\the\XeTeXinterchartokenstate}%
    \let \NewFooIntercharClass = \newXeTeXintercharclass
    \let \FooIntercharClass = \XeTeXcharclass
    \def \GetFooIntercharClass {\the\XeTeXcharclass}%
    \let \FooIntercharToks = \XeTeXinterchartoks
    \def \GetFooIntercharToks {\the\XeTeXinterchartoks}%
\fi
\end{verbatim}
  \item Rename every occurrence of XeTeX\rq s commands in your package file with the new name
        according to the above table.
\end{enumerate}

After these modifications, when users doesn\rq t load 'interchar', your package should
behave as before, but when users load 'interchar' package \textbf{before} your package,
'interchar' will takes over XeTeX\rq s char class mechanism, therefore users could switch
among different char class schemes at will.

Note that `\GetFooIntercharState' is \textbf{fully expandable}, which means you could write
the following conditional test:
\begin{verbatim}\ifnum \GetFooIntercharState > 0 doA \else doB \fi\end{verbatim}
However `\GetFooIntercharClass' and `\GetFooIntercharToks' are
\textbf{not fully expandable} for the time being.

\section{Implementation}

%\AutoCmdSyntaxVerb
\NoEmptyCodeLines
\MakeInputJobDoc[sty][ltx]{0}{\ProcessInputWith{PScomment}}

\end{document}