Debian Codegraph @

texmf-dist/doc/xelatex/interchar/interchar.tex

raw
1 % -*- coding: utf-8 -*-
2 % Package interchar: managing character class schemes of XeTeX
3 % Copyright (C) 2015 Zou Hu <[email protected]>
4 %
5 % Please report bugs, problems, and suggestions via
6 % https://github.com/zohooo/interchar
7 %
8 % This file may be distributed and/or modified under the conditions
9 % of the LaTeX Project Public License, either version 1.3 of this
10 % license or (at your option) any later version. The latest version
11 % of this license is in
12 % http://www.latex-project.org/lppl.txt
13 \documentclass{article}
14 \usepackage[b5paper,margin=17mm]{geometry}
15 \usepackage{xcolor,hyperref,float,makedoc,niceverb,interchar}
16 \hypersetup{
17 colorlinks,
18 citecolor = teal,
19 linkcolor = blue,
20 urlcolor = purple,
21 pdfstartview = {FitH},
22 bookmarksnumbered
23 }
24 \begin{document}
25
26 \title{Documentation for package \texttt{interchar}
27 \footnote{Version 0.2. Please report bugs via \url{https://github.com/zohooo/interchar}.}}
28 \author{Zou Hu ([email protected])}
29 \maketitle
30 \tableofcontents
31
32 \section{Introduction}
33
34 With XeTeX\rq s character class mechanism, we could put characters into different classes,
35 and insert some tokens to the input stream between characters in one class and those in
36 another class. This mechanism is originally used for switching fonts and adjusting spaces.
37 But it has many other useful applications.
38
39 By default, all characters are of class 0, except CJK ideographs are of class 1, CJK left
40 punctuation of class 2, CJK right punctuation of class 3, text boundaries (glues, kerns,
41 maths, boxes, etc.) of class 255, and several characters of class 256 (this class is ignored).
42
43 \MakeNormal\`
44 \newintercharclass{\myclass}
45 \intercharclass{`\o}{\myclass}
46 \interchartoks{0}{\myclass}{\bgroup\color{red}}
47 \interchartoks{255}{\myclass}{\bgroup\color{red}}
48 \interchartoks{\myclass}{0}{\egroup}
49 \interchartoks{\myclass}{255}{\egroup}
50 \intercharstate{1}
51 \MakeActive\`
52 Package 'interchar' is written for making character class mechanism more easy to use. For example,
53 after loading the package with `\usepackage{interchar}', you may change the color of every
54 occurrences of character \texttt{o}:
55 \intercharstate[foo]{0}
56 \begin{verbatim}
57 \newintercharclass{\myclass}
58 \intercharclass{`\o}{\myclass}
59 \interchartoks{0}{\myclass}{\bgroup\color{red}}
60 \interchartoks{255}{\myclass}{\bgroup\color{red}}
61 \interchartoks{\myclass}{0}{\egroup}
62 \interchartoks{\myclass}{255}{\egroup}
63 \intercharstate{1}
64 \end{verbatim}
65
66 There are some existing packages using this mechanism, such as 'polyglossia', 'xeCJK' and
67 'xesearch'. But since one character could only be put into one single class, when loading two
68 or more of these packages simultaneously, it would be very likely that some conflicts occur.
69
70 Package 'interchar' also provides some migration commands for these packages. With minor changes
71 these packages should be compatible with 'interchar', and users could switch between different
72 character class schemes when loading these packages at the same time.
73
74 \section{Commands for normal users}
75
76 \begin{itemize}
77 \item |\newintercharscheme{<scheme>}| creates a new char class scheme. For example,
78 \begin{verbatim}\newintercharscheme{foo}\end{verbatim}
79 There is a prebuilt `default' scheme which you need not to create it.
80 The first argument of the other commands in this section is optional;
81 its default value is `default'.
82 \item |\intercharstate[<scheme>]{<state-code>}| changes current scheme.
83 If '<state-code>' is positive, changes current scheme to `<scheme>';
84 otherwise, changes current scheme to `default'. For example,
85 \begin{verbatim}\intercharstate[foo]{1}\end{verbatim}
86 \item |\getintercharstate[<scheme>]{\cs}| gets current state of the specified scheme
87 and store the state code in `\cs'. For example,
88 \begin{verbatim}\getintercharstate[foo]{\mystate}\end{verbatim}
89 \item |\newintercharclass[<scheme>]{\cs}| creates a new char class in the specified scheme
90 and stores the class number in `\cs'. For example,
91 \begin{verbatim}\newintercharclass[foo]{\myclass}\end{verbatim}
92 \item |\intercharclass[<scheme>]{<char-range>}{<char-class>}| moves all characters within
93 `<char-range>' to the class `<char-class>' in the specified scheme. For example,
94 \begin{verbatim}
95 \intercharclass[foo]{`\@}{255}
96 \intercharclass[foo]{`\a-`\z}{\myclass}
97 \end{verbatim}
98 \item |\getintercharclass[<scheme>]{<char-code>}{\cs}| gets the class number of the specified
99 character in the specified scheme, and stores the result in `\cs'. For example,
100 \begin{verbatim}\getintercharclass[foo]{`\@}{\result}\end{verbatim}
101 \item |\interchartoks[<scheme>]{<char-class-1>}{<char-class-2>}{<tokens>}| defines tokens to be
102 inserted between `<char-class-1>' and `<char-class-2>' (in that order) in the specified
103 scheme. For example,
104 \begin{verbatim}
105 \interchartoks[foo]{0}{\myclass}{\bgroup\color{red}}
106 \interchartoks[foo]{\myclass}{0}{\egroup}
107 \end{verbatim}
108 \item |\getinterchartoks[<scheme>]{<char-class-1>}{<char-class-2>}{\cs}| gets the tokens to be
109 inserted between `<char-class-1>' and `<char-class-2>' in the specified scheme, and stores
110 the result in `\cs'. For example,
111 \begin{verbatim}\getinterchartoks[foo]{0}{\myclass}{\mytoks}\end{verbatim}
112 \end{itemize}
113
114 \section{Commands for macro writers}
115
116 For macro writers, we provide |\NewIntercharScheme| command which is an alias of user command `\newintercharscheme'. When you write `\NewIntercharScheme{foo}', 'interchar' package also
117 creates the following migration commands for you:
118
119 \begin{table}[H]
120 \MakeNormal\& \MakeNormal\` \MakeNormal\| \catcode`\?=13 \let?=| \MakeActive\` \MakeActive\|
121 \renewcommand{\arraystretch}{1.4}
122 \begin{tabular}{?l?l?}
123 \hline
124 \textbf{Migration Command} & \textbf{Analogous to Commands} \\ \hline
125 |\FooIntercharState = <state-code>| & `\XeTeXinterchartokenstate' \\
126 |\GetFooIntercharState| & `\the\XeTeXinterchartokenstate' \\
127 |\NewFooIntercharClass <control-sequence>| & `\newXeTeXintercharclass' \\
128 |\FooIntercharClass <char-code> = <char-class>| & `\XeTeXcharclass' \\
129 |\GetFooIntercharClass <char-code>| & `\the\XeTeXcharclass'. \\
130 |\FooIntercharToks <class1> <class2> = {<toks>}| & `\XeTeXinterchartoks' \\
131 |\GetFooIntercharToks <class1> <class2>| & `\the\XeTeXinterchartoks' \\
132 \hline
133 \end{tabular}
134 \end{table}
135
136 Within the command specifications in the above table, all of the equal signs `='
137 and most of the spaces are optional.
138
139 If you are the author of package 'foo' which use XeTeX\rq s char class mechanism,
140 with some minor changes you could make your package compatible with other packages.
141
142 \begin{enumerate}
143 \item Add the following lines to the beginning of your package file:
144 \begin{verbatim}
145 \ifdefined\NewIntercharScheme
146 \NewIntercharScheme{foo}%
147 \else
148 \let \FooIntercharState = \XeTeXinterchartokenstate
149 \def \GetFooIntercharState {\the\XeTeXinterchartokenstate}%
150 \let \NewFooIntercharClass = \newXeTeXintercharclass
151 \let \FooIntercharClass = \XeTeXcharclass
152 \def \GetFooIntercharClass {\the\XeTeXcharclass}%
153 \let \FooIntercharToks = \XeTeXinterchartoks
154 \def \GetFooIntercharToks {\the\XeTeXinterchartoks}%
155 \fi
156 \end{verbatim}
157 \item Rename every occurrence of XeTeX\rq s commands in your package file with the new name
158 according to the above table.
159 \end{enumerate}
160
161 After these modifications, when users doesn\rq t load 'interchar', your package should
162 behave as before, but when users load 'interchar' package \textbf{before} your package,
163 'interchar' will takes over XeTeX\rq s char class mechanism, therefore users could switch
164 among different char class schemes at will.
165
166 Note that `\GetFooIntercharState' is \textbf{fully expandable}, which means you could write
167 the following conditional test:
168 \begin{verbatim}\ifnum \GetFooIntercharState > 0 doA \else doB \fi\end{verbatim}
169 However `\GetFooIntercharClass' and `\GetFooIntercharToks' are
170 \textbf{not fully expandable} for the time being.
171
172 \section{Implementation}
173
174 %\AutoCmdSyntaxVerb
175 \NoEmptyCodeLines
176 \MakeInputJobDoc[sty][ltx]{0}{\ProcessInputWith{PScomment}}
177
178 \end{document}