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