<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">
% cnv.tex -- macro for string conversion
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% April 2005                                         Petr Olsak


% \cnvin {&lt;input text&gt;} converts &lt;input text&gt; to &lt;output text&gt;.
% This output is stored in \cnvout macro.

% For more information see the end of this file.
% The comments after %% (double percent sign) are intended for macro 
% programmers. See "simple" documentation at the end of this file first.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%% we cannot read this macro twice:

\ifx\cnvin\undefined \else \endinput \fi  

%% \predef &lt;token&gt; defines macro \E:&lt;token&gt;:&lt;table&gt;
%% \findef &lt;token&gt; defines macro \T:&lt;token&gt;:&lt;table&gt;

\def\predef #1{\expandafter \predefmethod \csname E:\string#1:\cnvtable\endcsname}
\def\findef #1#2{\expandafter \findefmethod \csname T:\string#1:\cnvtable\endcsname {#2}}

%% \cnvaccent &lt;command&gt; &lt;char&gt; {&lt;output&gt;} does following:
%% 1. it defines \E:&lt;command&gt;:&lt;table&gt; #1 as {\runcnvaccent \A:&lt;command&gt;:#1:&lt;table&gt;}
%%    (\runcnvaccent implements the test if accented letter is undeclared, see below)
%% 2. it defines \A:&lt;command&gt;:&lt;char&gt;:&lt;table&gt; as {&lt;output&gt;}
%% 3. if "&lt;command&gt; &lt;char&gt;" is one &lt;token&gt; after expansion, then 
%%    it defines \T:&lt;token&gt;:&lt;table&gt; as {&lt;output&gt;}
       
\def\cnvaccent #1#2#3{\expandafter \cnvaccentmethod \csname E:\string#1:\cnvtable\endcsname ##1%
       {\cnvexpand \expandafter \runcnvaccent \csname A:\string#1:\string##1:\cnvtable\endcsname}%
   \expandafter \findefmethod \csname A:\string#1:\string#2:\cnvtable\endcsname {#3}%
   \edef \tmp{#1{#2}}%
   \expandafter \cnvtestaccent \tmp \cnvtestaccent
   \ifx\nextchar\empty \expandafter \findefmethod \csname T:\tmp:\cnvtable\endcsname {#3}\fi
}
\def\cnvtestaccent {\futurelet \nextchar \docnvtestaccent}
\def\docnvtestaccent #1#2\cnvtestaccent{\ifx\nextchar \bgroup
   \else \def\nextchar{#2}\fi}

%% main macro:

\long\def\cnvin #1{\def\cnvout{}\cnvnext #1\cnvend}

%% \cnvnext: we test the next token by \futurelet because it may be a space
%% or a brace:

\def\cnvnext {\futurelet \nextchar \docnvnext}
\def\docnvnext {\let\next=\cnvtoken
   \ifx \nextchar\cnvend        \let\next=\relax \fi
   \ifx \nextchar\spacetoken    \let\next=\cnvspace \fi   
   \ifx \nextchar\cnvbgroup     \let\next=\cnvopenbrace \fi
   \ifx \nextchar\cnvegroup     \let\next=\cnvclosebrace \fi
   \ifx \nextchar\runcnvaccent  \let\next=\relax \fi
   \ifx \nextchar\cnvexec       \let\next=\relax \fi
   \ifx \nextchar\cnvexpand     \let\next=\relax \fi
   \ifx \nextchar\cnvexpandtext \let\next=\relax \fi
   \next}

%% \cnvend: end of conversion. We define it as \outer because
%% the parameter of user macros cannot scan this token.

\outer\def\cnvend{\let\nextchar=\relax}

%% \cnvbgroup, \cnvegroup: We suppose that these sequences will have
%% the constant meaning (user may change the \bgroup, \egroup meaning).

\let\cnvbgroup={  \let\BGROUP={  \let\EGROUP=}  \let\cnvegroup=}

%% \spacetoken is the control sequence equal to space token (catcode 10):

{\def\\{\global\let\spacetoken= }\\ }

%% \cnvtoken: next &lt;token&gt; is scannable in #1 parameter
%% It expands to \E:&lt;token&gt;:&lt;table&gt; (if defined) else
%% it stores contents of \T:&lt;token&gt;:&lt;table&gt; to \cnvout (if defined) else
%% it stores &lt;token&gt; to \cnvout using \cnvdefault macro.

\def\cnvtoken #1{\def\tmpc{#1}\docnvtoken}
\def\docnvtoken{%   
   \expandafter \ifx \csname E:\expandafter\string\tmpc:\cnvtable\endcsname \relax 
      \expandafter \ifx \csname T:\expandafter\string\tmpc:\cnvtable\endcsname \relax 
         \ifx\tmpc\space \cnvstoree{\expandafter \cnvout \tmpc}%
         \else \cnvstoreee {\expandafter \expandafter \expandafter \cnvout
                            \expandafter \cnvdefault \tmpc}%
         \fi
      \else
         \cnvstoreee {\expandafter \expandafter \expandafter 
             \cnvout \csname T:\expandafter\string\tmpc:\cnvtable\endcsname}%
      \fi
      \expandafter \cnvnext
   \else
      \expandafter \expandafter \expandafter \cnvnext 
      \csname E:\expandafter\string\tmpc:\cnvtable\expandafter \endcsname
   \fi}

%% \cnvspace, \cnvopenbrace, \cnvclosebrace: the next token is unreadable
%% by #1 macro parameter. We define \tmpc, remove the next token
%% and run \docnvtoken macro.

\def\cnvspace      {\def\tmpc{ }\afterassignment       \docnvtoken \let\next= }
\def\cnvopenbrace  {\def\tmpc{\BGROUP}\afterassignment \docnvtoken \let\next= }
\def\cnvclosebrace {\def\tmpc{\EGROUP}\afterassignment \docnvtoken \let\next= }

%% \runcnvaccent: next token #1 is \A:&lt;command&gt;:&lt;char&gt;:&lt;table&gt;.
%% It stores the contents of \A:&lt;command&gt;:&lt;char&gt;:&lt;table&gt; to \cnvout
%% (if defined) else it stores \cnvadefault to \cnvout.

\def\runcnvaccent #1{\ifx #1\relax 
      \cnvstoree {\expandafter \cnvout \cnvadefault}%
   \else 
      \cnvstoree {\expandafter \cnvout #1}%
   \fi \cnvnext}

%% \cnvexec: we switch off the conversion until \cnvnext
%% The contents of this macro means: do nothing, but we need
%% somewhat special contents in order to distinguish it by \ifx.

\long\def\cnvexec {\empty\relax\relax}

%% \cnvexpand, \cnvexpandtext: see the documentation at the end of this file

\def\cnvexpand {\expandafter \cnvnext}
\def\cnvexpandtext #1{\edef\tmp{#1}\expandafter \cnvnext \tmp}

%% \cnvstoreee: macro appends the desired contens to \cnvout.
%% We cannot expand the \cnvout by \edef because the expandable tokens can be
%% included here. So we need to do some \expandafter gymnastics.

\def\cnvstore   {\expandafter \def \expandafter \cnvout \expandafter}
\def\cnvstoree  {\expandafter \cnvstore  \expandafter}
\def\cnvstoreee {\expandafter \cnvstoree \expandafter}

%% Implicit values:

\def\cnvcopy{}
\let\cnvdefault=\cnvcopy
\def\cnvadefault{?}
\def\cnvtable{}

\let\predefmethod=\gdef
\let\findefmethod=\gdef
\let\cnvaccentmethod=\gdef

\endinput

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

---&gt; english documentation: see the end of this file

Po provedenĂ­ pĹ™Ă­kazu \cnvin {&lt;seznam tokenĹŻ&gt;}
je v makru \cnvout ukryt konvertovanĂ˝ seznam tokenĹŻ.

Konverze se provĂˇdĂ­ bez obvyklĂ© expanze &lt;seznamu tokenĹŻ&gt; a je jedno, jakĂ©
kategorie jednotlivĂ© tokeny majĂ­. Konverze probĂ­hĂˇ ve dvou prĹŻchodech:

1. KontrolovanĂˇ ÄŤĂˇsteÄŤnĂˇ expanze jednotlivĂ˝ch tokenĹŻ. Po jejĂ­m
   provedenĂ­ se konverze vracĂ­ k vĂ˝sledku expanze a konvertuje jej
   znovu. Tokeny, kterĂ© takto expandujĂ­, se v konverznĂ­ tabulce
   deklarujĂ­ pomocĂ­ \predef. Tokeny, kterĂ© nejsou takto deklarovĂˇny,
   pĹ™i konverzi neexpandujĂ­ (aÄŤkoli pĹ™i bÄ›ĹľnĂ© expanzi tĹ™eba expandujĂ­).
2. FinĂˇlnĂ­ konverze tokenu: token je konvertovĂˇn podle deklarace
   makrem \findef na vĂ˝stupnĂ­ posloupnost tokenĹŻ, ke kterĂ˝m se uĹľ
   konverze nevracĂ­.

Tokeny, kterĂ© podlĂ©hajĂ­ konverzi, mohou mĂ­t libovolnou kategorii. NenĂ­
tedy nutnĂ©, aby se jednalo o kontrolnĂ­ sekvence.

Deklarace tokenĹŻ pomocĂ­ \predef a \findef jsou zcela nezĂˇvislĂ© na
"skuteÄŤnĂ©m vĂ˝znamu" tokenu. JednĂˇ-li se o kontrolnĂ­ sekvenci, bude
se tato kontrolnĂ­ sekvence pĹ™i bÄ›ĹľnĂ©m zpracovĂˇnĂ­ \TeX{}em chovat
bÄ›ĹľnĂ˝m zpĹŻsobem aÄŤkoli mĂˇ pro konverzi deklarovĂˇn pomocĂ­ \predef nebo
\findef odliĹˇnĂ˝ vĂ˝znam.

Deklarace pomocĂ­ \predef mĹŻĹľe mĂ­t bÄ›ĹľnĂ© parametry a separĂˇtory (#1#2 atd.)

KaĹľdĂ˝ token mĹŻĹľe mĂ­t jen jeden vĂ˝znam deklarovanĂ˝ pomocĂ­ \predef nebo
\findef. Je-li token deklarovĂˇn obojĂ­m zpĹŻsobem, mĂˇ pĹ™i konverzi pĹ™ednost
\predef. Je-li token deklarovĂˇn opakovanÄ› stejnĂ˝m deklarĂˇtorem, platĂ­ 
poslednĂ­ deklarace.

Pokud se mĂˇ konvertovat token, kterĂ˝ nemĂˇ ĹľĂˇdnou deklaraci, pak je
vĂ˝sledek zĂˇvislĂ˝ na hodnotÄ› makra s jednĂ­m parametrem \cnvdefault.  
ImplicitnÄ› je \cnvdefault definovĂˇno tak, Ĺľe se nedeklarovanĂ˝ token
kopĂ­ruje beze zmÄ›ny do vĂ˝stupu. UĹľivatel mĂˇ tyto dalĹˇĂ­ moĹľnosti:

\def\cnvdefault #1{&lt;out&gt;} % kaĹľdĂ˝ nedeklarovanĂ˝ token se konvertuje
   			  % na spoleÄŤnĂ˝ &lt;out&gt;
\def\cnvdefault #1{}      % nedeklarovanĂ˝ token tiĹˇe zmizĂ­

PĹ™Ă­klad hypotetickĂ© konverznĂ­ tabulky:

\predef  \TeX  {TeX}
\predef  \uv #1{\leva #1\prava}
\predef  X{AB}
\findef A {:XX:\TeX:}
\cnvin{Tady je \uv{\TeX}}

V \cnvout mĂˇme text: "Tady je \leva Te:XX:\TeX:B\prava". Obsah \cnvout
mĹŻĹľeme zkontrolovat pomocĂ­ \message{\meaning\cnvout}. 

Jak probĂ­hala konverze:

\uv{\TeX} =&gt; \leva \TeX \prava
\TeX =&gt; TeX
        TeX =&gt; TeAB
               TeAB =&gt; Te:XX:\TeX:B  ... a toto uĹľ se nekonvertuje.

ProtoĹľe pĹ™i \predef je moĹľnĂ© deklarovat parametry makra, nesmĂ­ za
deklarovanĂ˝m tokenem bĂ˝t mezera (viz \predef X{AB} v ukĂˇzce).
Na druhĂ© stranÄ› pĹ™i deklaraci pomocĂ­ \findef je moĹľnĂ© mezi tokenem a
tÄ›lem makra vloĹľit nepovinnou mezeru.

PĹ™i konverzi tokenu deklarovanĂ©ho pomocĂ­ \predef provede \TeX{}
expanzi tokenu jako by to bylo makro. Provede ale jen prvnĂ­ ĂşrovneĹ
expanze  (tj. jako pĹ™i \expandafter, nikoli jako pĹ™i \edef).

Tokeny kategorie 10, 1 a 2 (mezera a svorky) se zpracovĂˇvajĂ­ mĂ­rnÄ›
odliĹˇnĂ˝m zpĹŻsobem, neĹľ ostatnĂ­ tokeny. To znamenĂˇ, Ĺľe jsem trochu
kecal, kdyĹľ jsem dĹ™Ă­ve ujistil ÄŤtenĂˇĹ™e, Ĺľe konverze je na kategoriĂ­ch
zcela nezĂˇvislĂˇ. Pokud je konverze mezery nedeklarovanĂˇ, pak se mezera
nemÄ›nĂ­ bez zĂˇvislosti na hodnotÄ› makra \cnvdefault. Konverzi mezery
mĹŻĹľeme deklarovat napĹ™Ă­klad takto:

\findef { } {&lt;vĂ˝stup pro mezeru&gt;}
nebo
\predef { }{&lt;makro pro mezeru&gt;}

OtevĂ­racĂ­ svorka, kterĂˇ ma kategorii 1, se internÄ› promÄ›nĂ­ v sekvenci 
\BGROUP a pokud nenĂ­ pro nĂ­ deklarovĂˇna konverze, je zpracovĂˇna pomocĂ­
\cnvdefault jako kaĹľdĂ˝ jinĂ˝ nedeklarovanĂ˝ token. PodobnÄ› zavĂ­racĂ­
svorka, kterĂˇ mĂˇ kategorii 2, se promÄ›nĂ­ v \EGROUP. Konverzi pro tyto
tokeny mĹŻĹľeme deklarovat jednoduĹˇe napĹ™Ă­klad:

\findef \BGROUP {&lt;vĂ˝stup pro otevĂ­racĂ­ svorku&gt;}
\findef \EGROUP {&lt;vĂ˝stup pro zavĂ­racĂ­ svorku&gt;}
nebo
\predef \BGROUP {&lt;makro pro otevĂ­racĂ­ svorku&gt;}
\predef \EGROUP {&lt;makro pro zavĂ­racĂ­ svorku&gt;}

BohuĹľel, makro \cnvin nenĂ­ implicitnÄ› schopno rozliĹˇit mezi skuteÄŤnou
svorkou (kategorie 1 nebo 2) a zĂˇstupnou kontrolnĂ­ sekvencĂ­ \bgroup,
\egroup. ObĂ© je internÄ› pĹ™evedeno na \BGROUP, \EGROUP a nĂˇslednÄ›
zpracovĂˇno. Chceme-li mezi svorkami a zĂˇstupnĂ˝mi kontrolnĂ­mi
sekvencemi rozliĹˇovat, musĂ­me pĹ™ed konverzĂ­ zmÄ›nit (aspoĹ pĹ™echodnÄ›)
vĂ˝znam \bgroup, \egroup:

{\let\bgroup=\relax \let\egroup=\relax \cnvin{...} ...}

Pro moĹľnost deklarace konverze akcentovanĂ˝ch znakĹŻ zapsanĂ˝ch 
v \TeX{}ovĂ© notaci je k dispozici jeĹˇtÄ› dalĹˇĂ­ deklaraÄŤnĂ­ makro:

\cnvaccent &lt;sekvence&gt; &lt;znak&gt;  {&lt;vĂ˝stup&gt;}.

Toto makro zaĹ™Ă­dĂ­, aby se akcentovanĂ© Ĺ™Ă­dicĂ­ sekvence ve tvaru
&lt;sekvence&gt; &lt;znak&gt; i ve tvaru &lt;sekvence&gt; {&lt;znak&gt;} konvertovaly na
odpovĂ­dajĂ­cĂ­ &lt;vĂ˝stup&gt;. NavĂ­c se makro \cnvaccent pĹ™i uklĂˇdĂˇnĂ­
informacĂ­ do konverznĂ­ tabulky pokusĂ­ expandovat "&lt;sekvence&gt; &lt;znak&gt;" a
je-li vĂ˝sledkem jedinĂ˝ &lt;token&gt;, provede jeĹˇtÄ› \findef &lt;token&gt; {&lt;vĂ˝stup&gt;}. 
TĂ­m je zaruÄŤeno, Ĺľe na stejnĂ˝ &lt;vĂ˝stup&gt; se konvertuje i akcentovanĂ˝ 
znak, pokud je zapsĂˇn na vstupu "pĹ™Ă­mo" bez pouĹľitĂ­ \TeX{}ovĂ© notace.

Jakmile \cnvaccent deklaruje &lt;sekvenci&gt; jako sekvenci pro akcent, pak
je sledovĂˇn i vĂ˝skyt neexistujĂ­cĂ­ho akcentu vytvoĹ™enĂ©ho touto
&lt;sekvencĂ­&gt;. TakovĂ˝ vĂ˝skyt se konvertuje na obsah makra bez parametru 
\cnvadefault. NechĹĄ napĹ™Ă­klad:

\cnvaccent \v c {&lt;vĂ˝stup pro ÄŤ&gt;}

a nechĹĄ chybĂ­ deklarace \v u. V takovĂ©m pĹ™Ă­padÄ› se \v c konvertuje na
odpovĂ­dajĂ­cĂ­ vĂ˝styp zatĂ­mco \v u se konvertuje na obsah makra
\cnvadefault. ImplicitnÄ› je \def\cnvadefault{?}.

PĹ™Ă­kazy \predef, \findef a \cnvaccent internÄ› definujĂ­ vĂ˝sledek
konverze pomocĂ­ \gdef. Pokud chceme pouĹľĂ­t jinou metodu, mĹŻĹľeme pĹ™ed
jejich pouĹľitĂ­m psĂˇt napĹ™Ă­klad \let\findefmethod=\xdef.
TĂ­m dosĂˇhneme, Ĺľe makra ve \findef se pĹ™ed zapamatovĂˇnĂ­m expandujĂ­.
Nebo tĹ™eba \let\predefmethod=\def zpĹŻsobĂ­, Ĺľe deklarace \predef
budou lokĂˇlnĂ­ vrĂˇmci skupiny.

ExistujĂ­ tĹ™i pĹ™Ă­kazy, kterĂ© majĂ­ pĹ™i konverzi speciĂˇlnĂ­ vĂ˝znam:
\cnvexec, \cnvexpandtext a \cnvexpand.

PĹ™Ă­kaz \cnvexec zpĹŻsobĂ­ provedenĂ­ nĂˇsledujĂ­cĂ­ch pĹ™Ă­kazĹŻ expand procesorem i 
hlavnĂ­m procesorem \TeX{}u. Zbytek vstupu pro konverzi je pĹ™ipraven ve
vstupnĂ­ frontÄ›. Konverze pokraÄŤuje aĹľ v okamĹľiku, kdy je
zpracovĂˇn pĹ™Ă­kaz \cnvnext. NĂˇsledujĂ­cĂ­ token za tĂ­mto pĹ™Ă­kazem podlĂ©hĂˇ
konverzi.

PĹ™Ă­kaz \cnvexpand &lt;token&gt; zpĹŻsobĂ­, Ĺľe &lt;token&gt; bude expandovĂˇn bÄ›ĹľnĂ˝m
zpĹŻsobem do prvnĂ­ ĂşrovnÄ› expanze a vĂ˝sledek tĂ©to expanze bude dĂˇle
konvertovĂˇn. PĹ™Ă­kaz je implementovĂˇn jako \cnvexec\expandafter\cnvnext.

PĹ™Ă­kaz \cnvexpandtext {&lt;text&gt;} zpĹŻsobĂ­, Ĺľe se &lt;text&gt; zcela expanduje bÄ›ĹľnĂ˝m
zpĹŻsobem (jako pĹ™i \edef) a pak se na takto expandovanĂ˝ &lt;text&gt; provede
konverze.

PĹ™i naÄŤĂ­tĂˇnĂ­ konverznĂ­ tabulky musĂ­ bĂ˝t obsah makra \cnvtable stejnĂ˝
jako pĹ™i jejĂ­m pouĹľitĂ­ v dobÄ› konverze pĹ™Ă­kazem \cnvin. ZmÄ›nou makra
\cnvtable mĹŻĹľeme deklarovat vĂ­ce nezĂˇvislĂ˝ch tabulek a pak mezi nimi 
v dobÄ› konverze pĹ™epĂ­nat. ImplicitnĂ­ hodnota makra \cnvtable je prĂˇzdnĂ©
makro. 


PĹĂŤKLADY
--------

V souboru cnv-pu.tex je deklarovĂˇna konverznĂ­ tabulka, pomocĂ­ nĂ­Ĺľ je
moĹľnĂ© konvertovat texty do PDF zĂˇloĹľek v UNICODE. VĂ˝hodou tohoto
Ĺ™eĹˇenĂ­ je, Ĺľe nedochĂˇzĂ­ k expanzi textu a Ĺľe je moĹľno nastavit pro
konverzi jakĂ˝koli znak, aÄŤkoli tyto znaky nejsou aktivnĂ­.

V rĂˇmci konverzĂ­ zdrojovĂ©ho textu TeXu mĹŻĹľeme narazit na problĂ©m
obvyklĂ© TeXovĂ© ligatury -- a ---, kterou bychom chtÄ›li konvertovat na
odpovĂ­dajĂ­cĂ­ vĂ˝stup. Toto mĹŻĹľeme provĂ©st nĂˇsledujĂ­cĂ­m makrem:

\predef -{\cnvexec \futurelet \nextchar \testtwodash}
\def\testtwodash {\ifx-\nextchar \expandafter \twodash
   \else \expandafter \cnvnext \expandafter \onedash \fi}
\def\twodash #1{\futurelet \nextchar \testthreedash}
\def\testthreedash {\ifx-\nextchar \expandafter \threedash
   \else \expandafter \cnvnext \expandafter \twodash \fi}
\def\threedash #1{\cnvnext \threedash}
\findef\onedash   {&lt;simple minus&gt;}
\findef\twodash   {&lt;en-dash&gt;}
\findef\threedash {&lt;em-dash&gt;}

SofistikovanÄ›jĹˇĂ­ pĹ™Ă­klad na konverzi celĂ˝ch ĂşsekĹŻ slov na jinĂ˝ vĂ˝stup
(tj. nejen jednotlivĂ˝ch znakĹŻ) je uveden v souboru cnv-word.tex.
Za pouĹľitĂ­ maker z tohoto pĹ™Ă­kladu pak problĂ©m ligatur -- a ---
lze deklarovat jednoduĹˇe:

\stringdef  {---} {&lt;em-dash&gt;}
\stringdef  {--}  {&lt;en-dash&gt;}
\stringdef  {-}   {&lt;simple minus&gt;}

=======================================================================
English documentation:


After applying \cnvin{&lt;list of tokens&gt;} the converted list of tokens is
saved in \cnvout macro.

The conversion is done without the standard expansion of &lt;list of tokens&gt; 
and is independet of catcodes of converted tokens.
The conversion process is done in two steps:

1. Controlled partial expansion of tokens. The conversion process is
   returned back to the result of this expansion and converts it once
   more.  Only tokens declared by \predef in the conversion table are
   expanded this way, other tokens not defined this way are not
   expanded (even if these tokens are expandable in the normal \TeX{}
   meaning).
2. Final conversion of token: token is converted to the output string
   of tokens following to the declaration by \findef macro. The
   conversion process does not return to this output anymore.

The tokens subject to conversion can have an arbitrary catcode. Not only control
sequences can be converted.

The declarations of tokens by \predef and \findef are quite
independent of the normal meaning of these tokens. It means that in case of
control sequences these sequences will behave during the usual processing
by \TeX{} in a usual way although for the purpose of conversion their meaning
can be changed using \predef or \findef.

You can use normal parameters and separators (#1#2 etc.) when \predef
is used. 

Each token can have only one meaning declared by \predef or \postdef.
It the token is declared by boths declarators, then \predef is
preferred. If the token is declared by the same declarator twice (or
more times), then the last declaration is valid.

If a token is to be converted which is not declared (by \predef nor
\findef), then the conversion process does the default conversion
which is determined by \cnvdefault macro (with one parameter: it is
the coverted token).  By default the token is simply copied to the
oputput but you can redefine the \cnvdefault macro in the following
way:

\def\cnvdefault #1{&lt;out&gt;} % each undeclared token is converted to the
                          % common &lt;out&gt; 
\def\cnvdefault #1{}      % undeclared token is silently ignored

Now, the simple hypothetic example follows:

\predef  \TeX  {TeX}
\predef  \uv #1{\leva #1\prava}
\predef  X{AB}
\findef A {:XX:\TeX:}
\cnvin{This is \uv{\TeX}}

The text "This is \leva Te:XX:\TeX:B\prava" is stored in \cnvout after
\cnvin command is processed.  The contents of \cnvout can be checked
with \message{\meaning\cnvout}.

The explanation of the conversion in this example:

\uv{\TeX} =&gt; \leva \TeX \prava
\TeX =&gt; TeX
        TeX =&gt; TeAB
               TeAB =&gt; Te:XX:\TeX:B  ... and this is kept untouched.

As parameters can be used with \predef declaration you must not
write redundant space after the declared token (see \predef X{AB}).
On the other hand, the optional space is allowed between the token
and the body of the macro in \findef declaration. 

During conversion process \TeX{} treats the token declared with
\predef as a real macro. Only first level of expansion is done before
conversion process returns back to expanded material (similar to
\expandafter primitive, not \edef).

The tokens of catcode 10, 1 and 2 (space and braces) are processed in
a slightly different way. It means that a small lie was told when the
catcode independency of the conversion process mentioned above had
been declared. If space conversion is not declared, then it is copied
without conversion and without dependency on \cnvdefault macro. You
can declare the conversion of the space e.g. as follows:

\findef { } {&lt;output for space&gt;}
or
\predef { }{&lt;macro for space&gt;}

Opening brace with catcode 1 is changed to a control sequence \BGROUP
internally. If this control sequence is not declared, then it is
processed by \cnvdefault as any other undeclared token. Similarly,
closing brace with catcode 2 is changed by \EGROUP during conversion
process. We can declare the conversion rules for these tokens by:

\findef \BGROUP {&lt;output for open brace&gt;}
\findef \EGROUP {&lt;output for close brace&gt;}
or
\predef \BGROUP {&lt;macro for open brace&gt;}
\predef \EGROUP {&lt;makcro for close brace&gt;}

Unfortunately, macro \cnvin cannot implicitely distinguish between a
real brace of catcode 1 or 2 and an alternate control sequence \bgroup
or \egroup.  Both are converted internally to \BGROUP, \EGROUP and
processed in the same way. If you need to distinguish between them,
then you need to set (locally) another meaning to \bgroup, \egroup
before \cnvin is invoked:

{\let\bgroup=\relax \let\egroup=\relax \cnvin{...} ...}

You can declare the conversion of accented letters written by standard
\TeX{} sequences. To do this, you can use the declaration macro:

\cnvaccent &lt;sequence&gt; &lt;char&gt;  {&lt;output&gt;}.

This macro arranges that the accented control sequences in the form
&lt;sequence&gt; &lt;char&gt; or &lt;sequence&gt; {&lt;char&gt;} will be converted to
&lt;output&gt;.  Moreover, when storing an information to a conversion table
the \cnvaccent macro tries to expand the "&lt;sequence&gt; &lt;char&gt;" by normal
\TeX{} rules. If the output of this expansion is one &lt;token&gt;, then
\cnvaccent does internally more work: \findef &lt;token&gt; {&lt;output&gt;}.
This guarantees that even an accented character will be converted
to the same &lt;output&gt; if it is written in the input "directly" without 
\TeX{} notation.

When \cnvaccent declares &lt;sequence&gt; as a sequnce for an accent, then the
occurence of a non-existing accent created with this &lt;sequence&gt; is watched.
Such an occurence is converted to the contents of the macro \cnvadefault
without parameters.
For example:

\cnvaccent \v c {&lt;output for ccaron&gt;}

and suppose that \v u is not declared. In such a case the \v c is
converted to the corresponding output, but \v u is converted to the contents of
\cnvadefault macro. By default there is \def\cnvadefault{?}.

The commands  \predef, \findef and \cnvaccent define internally the result
of the conversion using \gdef primitive If we want to use another method,
we can put e.g. \let\findefmethod=\xdef before the use of macros.
This causes that all bodies of \predef will be expanded before saving them
to the conversion table. Similarly \let\predefmethod=\def results in \predef
will work only locally.

There are three commands with special meaning in conversion process:
\cnvexec, \cnvexpandtext and \cnvexpand.

The \cnvexec command causes the following command is processed both by
\TeX{} expand processor and main processor.
The rest of an unconverted input is ready in the input stream.
The conversion process continues at the moment the \cnvnext command is processed.
The following token behind this command is submitted to conversion.

The \cnvexpand &lt;token&gt; command expands &lt;token&gt; at first level of
expansion and the expanded result is converted again. The \cnvexpand
is implemented by \cnvexec\expandafter\cnvnext.

The \cnvexpandtext {&lt;text&gt;} expands &lt;text&gt; totally in a usual way
(like by \edef) and the result of this expansion is converted again.

The contents of \cnvtable macro has to be the same both during the declaration
of the conversion table (by \predef, etc.) and during the conversion process
itself (by \cnvin). You can change the contents of \cnvtable macro if
you need to declare more independent conversion tables. Then you can
switch among these tables before using \cnvin command.
By default there is \def\cnvtable{}.


EXAMPLES
--------

There is an example in cnv-pu.tex file. The conversion table which
declares the conversion from TeX text to UNICODE text used in PDF
outlines is declared here. The advantage of this solution is that we
need not to expand the converted text and we can declare the
conversion for each character, not only for active characters. 

There is a common problem with the conversion of TeX ligatures -- and
--- to the desired output. This task can be solved by the following
macro:

\predef -{\cnvexec \futurelet \nextchar \testtwodash}
\def\testtwodash {\ifx-\nextchar \expandafter \twodash
   \else \expandafter \cnvnext \expandafter \onedash \fi}
\def\twodash #1{\futurelet \nextchar \testthreedash}
\def\testthreedash {\ifx-\nextchar \expandafter \threedash
   \else \expandafter \cnvnext \expandafter \twodash \fi}
\def\threedash #1{\cnvnext \threedash}
\findef\onedash   {&lt;simple minus&gt;}
\findef\twodash   {&lt;en-dash&gt;}
\findef\threedash {&lt;em-dash&gt;}

A more sophisticated example of word to word conversion (not only
single letters) is presented in cnv-word.tex file. If you use macros
from this example, then you can solve the problem of -- and ---
ligatures simply:

\stringdef  {---} {&lt;em-dash&gt;}
\stringdef  {--}  {&lt;en-dash&gt;}
\stringdef  {-}   {&lt;simple minus&gt;}

=======================================================
</pre></body></html>