summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/xelatex/interchar/interchar.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/xelatex/interchar/interchar.tex')
-rw-r--r--Master/texmf-dist/doc/xelatex/interchar/interchar.tex178
1 files changed, 178 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/xelatex/interchar/interchar.tex b/Master/texmf-dist/doc/xelatex/interchar/interchar.tex
new file mode 100644
index 00000000000..641d9f0c608
--- /dev/null
+++ b/Master/texmf-dist/doc/xelatex/interchar/interchar.tex
@@ -0,0 +1,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}