From f07bb53970ee2ecc53f81a206a3d3a67ef665e4a Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Mon, 9 Jan 2006 00:56:57 +0000
Subject: doc 6

git-svn-id: svn://tug.org/texlive/trunk@85 c570f23f-e606-0410-a88d-b1316a301751
---
 Master/texmf-dist/doc/generic/enctex/encdoc-e.tex | 947 ++++++++++++++++++++++
 1 file changed, 947 insertions(+)
 create mode 100644 Master/texmf-dist/doc/generic/enctex/encdoc-e.tex

(limited to 'Master/texmf-dist/doc/generic/enctex/encdoc-e.tex')

diff --git a/Master/texmf-dist/doc/generic/enctex/encdoc-e.tex b/Master/texmf-dist/doc/generic/enctex/encdoc-e.tex
new file mode 100644
index 00000000000..32a06241727
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/enctex/encdoc-e.tex
@@ -0,0 +1,947 @@
+% EncTeX documentation
+%%%%%%%%%%%%%%%%%%%%%%
+%           Petr Olsak
+
+% see encdoce.tex for Czech version of this documentation
+
+
+{\nopagenumbers} % use the plain format (the command: "tex encdoc-e")
+
+\def\Red{}
+\def\Black{}
+\def\Blue{}
+\def\Green{}
+\def\beglink#1{}
+\def\endlink{}
+\def\aimlink#1{}
+\def\urllink#1{{\tt#1}}
+\def\urllinkk#1#2{{\tt#1}}
+
+\ifx\pdfoutput\undefined\else   %%%% pdfTeX is used %%%%%%%%%%
+\ifnum\pdfoutput>0    
+
+\ifx\pdfannotlink\undefined  % Verze pdfTeXu >= 14
+   \let\pdfannotlink=\pdfstartlink
+\fi
+
+\def\beglink#1{% 
+    \Green \pdfstartlink height9pt depth3pt 
+     attr{/Border[0 0 0]} goto name{#1}\relax}
+\def\endlink{\pdfendlink\Black}  
+
+\def\aimlink#1{% 
+   \expandafter\ifx \csname aim:#1\endcsname \relax
+      \expandafter\gdef \csname aim:#1\endcsname {}%
+      \vbox to0pt{\vss\hbox{\pdfdest name{#1} fith}\kern15pt}%
+   \fi
+}
+\def\urllinkk#1#2{\pdfannotlink height 10pt depth 3pt 
+   user{/Border[0 0 0]/Subtype/Link/A << /Type/Action/S/URI/URI(#2)>>}\relax
+   \Green{\tt #1}\Black\pdfendlink}
+\def\urllink#1{\urllinkk{#1}{#1}}
+
+\def\pdfsetcmykcolor#1{\special{PDF:#1 k}}
+\def\Red{\leavevmode\pdfsetcmykcolor{0.1 0.9 0.9 0}}
+\def\Black{\leavevmode\pdfsetcmykcolor{0 0 0 1}}
+\def\Green{\leavevmode\pdfsetcmykcolor{0.9 0.1 0.9 .3}}
+\def\Blue{\leavevmode\pdfsetcmykcolor{0.9 0.9 0.1 0}}
+
+\pdfcompresslevel=9
+\pdfinfo{/Author (Petr Olsak)
+         /CreationDate (Feb. 2003) 
+         /ModDate (Jun. 2004)
+         /Creator (TeX)
+         /Producer (pdfTeX)
+         /Title (encTeX)
+         /Subject (Documentation)
+         /Keywords (TeX, fonts)
+}
+
+\fi\fi %%%%%%%%%%%%%%%%%%%%%%%%%%%% End of pdfTeX macros %%%%%
+
+
+\font\titulfont=\fontname\tenbf\space scaled\magstep4
+\font\bigbf=\fontname\tenbf\space scaled\magstep1
+
+\parindent=12pt
+
+\newcount\secnum  \newcount\subsecnum
+
+\def\kap #1\par{\ifnum\secnum>0 \goodbreak\fi\removelastskip
+   \vskip2\baselineskip
+   \subsecnum=0 \advance\secnum by1
+   \noindent{\bigbf\llap{\the\secnum.\quad}#1}\par\nobreak\medskip}
+\def\sec #1\par{\removelastskip\bigskip
+   \advance\subsecnum by1   
+   \noindent{\bf \llap{\aimlink{\the\secnum.\the\subsecnum}%
+      \the\secnum.\the\subsecnum.\quad}#1}\par\nobreak\medskip}
+\def\title #1\par{\vglue2\baselineskip 
+   \centerline{\titulfont #1}\vskip2\baselineskip}
+\def\date #1\par{\bigskip#1\par}
+\def\author #1\par{\bigskip#1\par}
+
+\catcode`<=13
+\def<{\hbox\bgroup\catcode`_=\active\relax\skoba}
+\def\skoba #1>{$\langle$\it#1\/$\rangle$\egroup}
+\def\,{\thinspace}
+{\catcode`_=\active \gdef_{\_}}
+
+{\obeyspaces \gdef\activespace{\obeyspaces\let =\ }}
+\def\setverb{\def\do##1{\catcode`##1=12}\dospecials}
+\def\begtt{\medskip\bgroup \setverb \activespace
+   \catcode`\"=12 \catcode`_=13
+   \def\par##1{\endgraf\ifx##1\par\leavevmode\fi ##1}
+   \obeylines \startverb}
+{\catcode`\|=0 \catcode`\\=12
+|gdef|startverb#1\endtt{|tt#1|egroup|medskip|testpar}}
+\long\def\testpar#1{\ifx\par#1\else\noindent\fi#1}
+
+\catcode`"=13
+\def"{\leavevmode\hbox\bgroup\setverb\activespace\tt\readverb}
+\def\readverb #1"{#1\egroup}
+
+\def\begitems{\medskip\bgroup \catcode`*=13 }
+{\catcode`*=13 \gdef*{\item{$\bullet$}}}
+\def\enditems{\medskip\egroup}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+{\nopagenumbers
+
+\vglue 4cm
+
+\centerline {\titulfont Enc\TeX}
+\vskip2cm
+\centerline {\titulfont The Extension of \TeX{}} 
+\medskip
+\centerline {\titulfont For Input Re-encoding}
+
+\vskip3cm
+
+\centerline{\bigbf Petr Ol\v s\'ak}
+
+\vskip2cm
+
+\centerline{\urllinkk{www.olsak.net/enctex.html}{http://www.olsak.net/enctex.html}}
+
+\vfil
+
+\centerline {\bigbf This text documents the version Feb. 2003 and Jun. 2004}
+
+\vskip 4cm 
+\break
+
+\null \vfil
+
+This package is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This package is available on
+\urllink{ftp://math.feld.cvut.cz/pub/olsak/enctex/}.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+
+\bigskip 
+\copyright\quad  1997, 2002, 2003, 2004\enspace RNDr. Petr Ol\v s\'ak
+
+\bigskip
+\TeX{} is trademark of the American Mathematical Society.
+
+\bigskip
+The author of the \TeX{} is professor Donald Knuth. The \TeX{}
+is a free software with the specific license. See the documentation
+of~\TeX.
+
+\bigskip
+The original version of the enc\TeX{} documentation (in Czech language) is in 
+"encdoc.tex" file.
+
+P\accent23uvodn\'\i{} \v cesk\'a dokumentace je v souboru "encdoc.tex".
+
+\break
+}
+
+\kap The basic information
+     %%%%%%%%%%%%%%%%%%%%%
+
+
+The enc\TeX{} package is a little extension of \TeX{}. You can install
+it from source files of \TeX{} by changing the "tex.ch" file in your
+distribution. The patch to "tex.ch" file for "web2c" distribution is
+supported. 
+
+The enc\TeX{} is backward compatible with the original \TeX{}. It adds
+ten new primitives by which you can set or read the conversion
+tables used by input processor of \TeX{} or used during output to the
+terminal, log and "\write" files. These tables are stored to the
+format files thus, they are reinitialized to the same state as in time
+of "\dump" command when the format file is read.
+
+This extension is fully tested and it passes the TRIP test with only
+two differences:
+
+\begitems
+* The banner is different
+* The number of ``multiletter control sequences'' is
+  greater by ten.
+\enditems
+
+
+\sec The installation
+%    ----------------
+
+For install instructions of enc\TeX{} -- read the "INSTALL.eng" file.
+
+\sec Versions
+%    --------
+
+I released the first version of enc\TeX{} in 1997. This version
+was able to do the byte to byte conversion only by xord and xchr
+vector and to assign the characters as ``printable'' (the "\xordcode",
+"\xchrcode" and "\xprncode" primitives).
+
+The TCX tables were renoved in 1998. These tables do the same work as
+enc\TeX{} 1997 thus I closed my support of enc\TeX{}. The problem
+with the missing support of UTF-8 encoding on input processor caused
+the reinterpretation of my old decision: I implemented the UTF-8
+support to the enc\TeX{} in December 2002 and I propagate enc\TeX{} again.
+
+The new version 
+``Feb.~2003'' adds seven new primitives: "\mubyte",
+"\endmubyte", "\mubytein", "\mubyteout", "\mubytelog", "\specialout"
+and "\noconvert". 
+They give a possibility to set the conversion from UTF-8 encoded files.
+
+The version ``Jun.~2004'' fixes a little bugs only. 
+No new features are added. 
+See "enctex.patch-jun2004" file for more information
+about these bugs.
+
+Of course, the new version is backward compatible with the old one
+from 1997. I don't plan any new big changes. If a little change will
+be done then {\it the backward compatibility with the previous version
+of enc\TeX{} is guaranteed by me}.
+
+\sec Enc\TeX{} in web2c distribution, TCX tables
+%    -------------------------------------------
+
+If your web2c distribution implements enc\TeX{} then you can
+initialize it by the "-enc" option in command line.
+You have to use this option during ini\TeX{} because enc\TeX{} stores
+its primitives and its data to the format file. When the format is
+used, the enc\TeX{} is initialized from format file automatically and
+you need not use the "-enc" option again. If you are using a format
+without enc\TeX{} initialized in it and you write "-enc" option then
+the warning is printed and this option is ignored.
+
+The TCX tables ("-translate-file" option) are working with the same
+xord and xchr vector as enc\TeX{} in web2c distribution. This implies
+the following little conflicts: If enc\TeX{} is used together with TCX
+table then TCX table may re-write the initial values of "\xordcode",
+"\xchrcode" and "\xprncode". These initial values are documented in
+section~2.2. If these values are stored in format by enc\TeX{} and TCX
+table is used together with such format then the values from format
+can be re-written by TCX table too. On the other hand, you can use the
+"\xordcode", "\xchrcode" and "\xprncode" primitives for reading or
+saving of these values after TCX table initialization without
+problems.
+
+\sec The \TeX{} license
+%    -------------------- 
+
+The enc\TeX{} adds the new primitives into \TeX{} so, we cannot call
+the resulting program by name \TeX. On the other hand D.~Knuth assumed
+that \TeX{} internals are filtered always from system dependences. 
+This was a reason why he implemented xord/xchr vectors in \TeX.
+D.~Knuth assumed that the parameters of filter from system
+dependences is set at source code level. Enc\TeX{} only moves this
+setting from source code level to the runtime level. This is nothing
+new: the \TeX{} memory parameters are possible to set at runtime in
+modern \TeX{} distributions too. You can set the conversion tables
+depend on your system. Then you can say "\let\xordcode=\undefined" 
+etc.~(the same for other enc\TeX{} primitives) and you can do "\dump".
+The format has the conversion tables stored by the system
+specifications and the user cannot do any more changes. The using of
+this format acts the same as the using of the original \TeX{}.
+
+I think that the second line on the terminal and log file is
+sufficient information about the fact that the program is
+a modified version of \TeX. I think that if the UTF-8 encoding will be
+used more common then there is no another way than to modify the input
+processor of \TeX{} otherwise the 8bit \TeX{} will dead in short time. 
+
+It is important to say that enc\TeX{} has the same default behavior as
+the original \TeX{} if the new primitives are never used.
+
+IMHO, the new web2c \TeX{} is not exactly the \TeX{} too because you can
+change its behavior by writing "%&" at the first line of the document.
+This feature is not documented in {\it Computers \& Typesetting\/}
+series. 
+
+
+\kap The byte per byte conversion
+     %%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\sec The xord and xchr vectors
+%    -------------------------
+
+All text inputs into \TeX{} are mapped by xord vector in input
+preprocessor (the eyes in \TeX{}book terminology). If the character
+has the code $x$ in your system, the same character has the code 
+$y$ = xord[x] in \TeX.
+
+All text outputs from \TeX{} to terminal, log file and files managed
+by "\write" primitive are filtered by xchr vector and by
+``printability'' feature of the character. If the character with code 
+$y$ is not ``printable'', then it outputs by "^^code" notation 
+(documented in \TeX{}book, page 45). If the character with code 
+$y$ is ``printable'' then the output code of this character on 
+terminal and text files is $z$ = xchr[$y$].
+
+\sec The new primitives with the access to the xord and xchr vectors
+%    --------------------------------------------------------------
+
+The enc\TeX{} extension introduces three new primitives with the same
+syntax as "\lccode":
+
+\begitems
+* "\xordcode" $i$ ... is xord[$i$]
+* "\xchrcode" $i$ ... is xchr[$i$]
+* the character with the code $i$ is ``printable'' 
+  (not "^notation" on terminal and the log is used) 
+  iff \hfil\break 
+  \hbox{("\xprncode" $i > 0$ )}  or  \hbox{( $i\in \{32,...,126\}$ )}.
+\enditems
+
+All setting to "\xordcode", "\xchrcode" and "\xprncode" are possible
+in 0...255 range and are {\it global} every time. It means 
+that the setting inside group are global and it is irrelevant 
+if you write "\global" prefix or you do not.
+
+The initial values at ini\TeX{} state of the mentioned vectors are:
+
+\begitems
+* "\xordcode" $i = i $  for $ i \in \{128...255\}$,
+* "\xchrcode" $i = i $  for $ i \in \{128...255\}$,
+* "\xprncode" $i = 0 $  for $ i \in \{0...31, 127...255\}$,
+* "\xprncode" $i = 1 $  for $ i \in \{32...126\}$.
+\enditems
+
+The "\xordcode" $i$ and "\xchrcode" $i$ for $i \in \{0...127\}$ are 
+system dependent, but on systems with ASCII encoding holds: 
+"\xordcode"~$i = i$, "\xchrcode"~$i = i$.
+
+
+\kap The multi-byte conversion
+     %%%%%%%%%%%%%%%%%%%%%%%%
+
+Since version Dec 2002, the enc\TeX{} is able to convert more bytes to
+one byte or control sequence on input processor level. This ``one byte''
+is converted back to the original ``more bytes'' when "\write" is
+processed or \TeX{} outputs to the terminal or log file.
+The main reason of this extension of \TeX{} is to serve to work with the
+UTF-8 encoded input files: we need to assign the "\catcode"s,
+"\uccode"s etc.~to the letters in our alphabet but some letters are
+encoded in two bytes in UTF-8. The enc\TeX{} is able to map other codes
+from UTF-8 to control sequences thus, the number of UTF-8 codes
+from input file examined by \TeX{} is unlimited.
+
+There are five new primitives to manage the conversion:
+"\mubytein", "\mubyteout", "\mubytelog", "\mubyte", "\endmubyte".
+The "\mubytein", "\mubyteout" and "\mubytelog" are integer registers with
+zero value by default: it means that no conversion is processed even
+if the conversion table (created by "\mubyte", "\endmubyte") is non 
+empty. If "\mubytein" is positive then the conversion on input processor
+level is performed by the conversion table. If "\mubyteout"
+is positive then the conversion for output to the "\write" files 
+is activated by the same conversion table. If "\mubytelog" is positive
+then the output conversion is activated for log file and terminal
+output.
+
+The conversion table is empty by default and you can add the
+new line into this table by the couple of "\mubyte", "\endmubyte" 
+primitives:
+
+\begtt
+\mubyte <first_token><one_optional_space><optional_prefix><byte_sequence>\endmubyte
+\endtt
+
+Each <byte_sequence> will be converted to the <first_token> at input
+processor level. There are two possibilities for <first_token>: it may
+be a character or a control sequence. If the <first_token> is a
+character then the catcode of it is ignored and the <first_token> is
+interpreted as a <byte>. This <byte> is converted back to the
+<byte_sequence> in "\write" files, log file and terminal.
+
+If the <first_token> is a control sequence then the <byte_sequence>
+will be converted to this control sequence of the ``one token'' 
+form at input processor level. It means that the 
+token processor never changes this control sequence. 
+The token processor stays in
+middle line state after this control sequence is scanned.
+If {\catcode`\<=12 "\mubyteout<2"} then the output to the "\write"
+files is not converted back to the <byte_sequence> and
+the control sequence is expanded as usual.
+If "\mubyteout>=2" then the control sequence declared by "\mubyte" is
+converted back to the <byte_sequence> in "\write" parameters. 
+This works only if the control sequence is not expanded. 
+It means that the control sequence have to be non expandable or 
+it have to be marked by "\noexpand". If "\mubyteout>=3" then 
+enc\TeX{} suppresses the expansion of control
+sequences declared by "\mubyte" automatically. See section~3.7 for
+more details.
+
+The control sequences are never converted back to <byte_sequence>
+in log file and on the terminal output.
+
+The syntax and the meaning of <optional_prefix> will be explained in
+section~3.4.
+
+\sec The conversion table manipulation
+%    ---------------------------------
+
+The data are stored into conversion table as a global assignment. On
+the other hand the assignment to "\mubytein", "\mubyteout" and
+"\mubytelog" registers are local as usually.
+
+The "\mubyte", "\endmubyte" primitives work very similar as a
+well known "\csname", "\endcsname" pair. The difference is that
+the <first_token> is not expanded and that this token can be followed
+by <one_optional_space> (after expansion). The <byte_sequence> is
+scanned with the full expansion. If the other non expandable control
+sequence than "\endmubyte" occurs during this process then the error
+message is printed:
+
+\begtt
+! Missing \endmubyte inserted.
+\begtt
+
+The "\mubyte" is not performed on the expand processor level: it is a
+assign primitive. If you write
+
+\begtt
+\edef\a{\mubyte X ABC\endmubyte}
+\endtt
+%
+then the macro "\a" includes the "\mubyte X ABC\endmubyte" tokens.
+
+Examples:
+
+\begtt
+\mubyte  ^^c1      ^^c3^^81\endmubyte % \'A
+\mubyte  ^^e1      ^^c3^^a1\endmubyte % \'a
+% etc. -- the UTF8 implementation
+
+\mubyte  \endash   ^^c4^^f6\endmubyte % the mapping to the control sequence
+\mubyte  \integral  INT\endmubyte     % the illustrative example, see below
+
+\mubytein=1  \mubyteout=1  % conversions are activated here
+
+\def\endash {--} % this is good definition for \write files too
+\def\integral {\ifmmode \int\else $\int$\fi}
+\endtt
+
+We have written more spaces (or tabs) in <one optional space> in 
+this example because these characters have the catcode of the space
+and the token processor converts them to right <one optional space>.
+
+The word ``"INTEGRAL"'' is converted to the token "\integral" followed
+by the letters ``"EGRAL"'' if the example code is used. 
+The text ``"INT something"'' is converted to the token "\integral" 
+followed by space and the word ``"something"''. You can write the
+following constructions: "\defINT{something}", "\let INT=\foo", etc.
+After "\show INT" we get:
+
+\begtt
+> \integral=macro:
+->\ifmmode \int \else $\int $\fi .
+l.18 \show INT
+\endtt
+%
+and "\string INT" expands to the text: "\integral".
+
+Assume the "INT" declaration from the previous example and assume that
+you write "\INT". What happens? Strictly speaking, the empty control
+sequence ("\csname\endcsname") followed by "\integral" control
+sequence would be the output from the token processor. But there is an
+exception in enc\TeX{} because to avoid the confusion with the empty control
+sequences. The "\INT" produces only the control sequence "\integral",
+the backslash is ignored in this situation. The token processor stays
+in middle state after "\INT" is scanned, the letter can follow
+immediately.
+
+\sec The features of the conversion process
+%    --------------------------------------
+
+The input is converted immediately after "\mubytein" is set to the
+positive value; it means the conversion may start at the same line
+where the "\mubytein" setting occurs.
+
+The <byte_sequence> is converted only if the whole <byte_sequence> is
+included in the one line. The "\endlinechar" character can be the last
+part of the <byte_sequence>.
+
+The sequence "^^c3^^81" is not converted to the letter \'A even if the
+code from the example was used. The reason is that the "^^" conversion
+is done in token processor after the "\mubyte" conversion.
+
+The "\xordcode" conversion is performed before "\mubyte" conversion 
+in input side and the "\xchrcode" conversion is done after "\mubyte"
+conversion during output to the files or to the terminal. The
+following diagram shows the sequence of the conversions:
+
+\begtt
+input text -> \xordcode -> \endlinechar appended ->
+              \mubyte -> token processor -> expand processor ...
+\write argument -> expand processor -> \mubyte -> \xchrcode -> output
+\endtt
+
+The <byte_sequence> is not converted to the "^^" form during
+output to the file even if the "\xprncode" of the bytes from
+<byte_sequence> is zero. The <byte_sequence> is not converted again
+even if there exist a character in it which is normally
+converted by another rule in conversion table.
+
+Let exist two or more <byte_sequences> in the conversion table which are
+equal or which have the same begin part and one sequence is a
+subsequence of the second. Then the conversion in input processor is
+done by maximal possible <byte_sequence>. This feature was implemented
+in version Feb.~2003. Example:
+
+\begtt
+\mubyte X A\endmubyte
+\mubyte Y ABC\endmubyte
+\mubyte \foo ABCD\endmubyte
+\endtt
+
+The letter A is normally converted to X in this example, but if the
+BC letters immediately follow then ABC is converted to Y with the
+exception ABCD which is converted to "\foo".
+
+The order of "\mubyte" settings in this example has no significance.
+
+If the same <byte_sequences> are used by "\mubyte" records then the 
+last one has a precedence and the previous records are cleared.
+
+
+\sec The conversion to log file and to the terminal
+%    ----------------------------------------------
+
+The output to terminal and to log file is not converted if
+"\mubytelog" is zero. If the "\xprncode" of the character is zero then
+the character is printed in "^^A" or "^^bc" form. If the "\mubytelog"
+is positive then the characters stored in conversion table are
+converted to the <byte_sequence> and the bytes from these
+<byte_sequence> are never converted to "^^" form.
+On the other hand, control sequences are keept unchanged 
+in log and in terminal even if the "\mubytelog" is positive.
+
+The conversion is switched on or off by "\mubytelog" value for both:
+terminal and log file. You cannot separate these outputs. It means that
+(for example) the conversion to log and no conversion to terminal 
+is not possible.
+
+There exists a special part of terminal and log output: if the complete
+line from input is reprinted (for example when the context of an error is
+shown). We call this situation as ``line-reprinting'' for the purpose
+of the following text.
+
+If the "\mubytein" is zero then line-reprinting works as usual in
+standard \TeX{}. If "\mubytein" is positive and "\mubytelog" is zero
+then line-reprinting includes the output from the input processor of
+enc\TeX{}. It means that control sequences generated by input
+processor can be shown here even if they don't actually present in the
+input line. If both "\mubytein" and "\mubytlog" are positive then
+line-reprinting works without any multi-byte conversion, only xord is
+used immediately followed by xchr. No "^^A" form is used in this
+situation. Note that the error messages can be somewhat peculiar when
+"\mubytein" and "\mubytlog" are positive:
+
+\begtt
+\mubyte \cmd ABC\endmubyte  \let\cmd=\undefined
+\mubytein=1 \mubytelog=1
+This is test of ABC and another text.
+\endtt
+%
+We get the following message:
+
+\begtt
+! Undefined control sequence.
+l.3 This is test of ABC
+                        and another text.
+?
+\endtt
+%
+The "\show ABC" can say you more information:
+
+\begtt
+> \cmd=undefined.
+l.3 \show ABC
+\endtt
+
+
+\sec Clearing records from the conversion table
+%    ------------------------------------------
+
+There exists only the chance to clear all records which begin with
+the same first byte of <byte_sequence>. This is done by the command
+"\mubyte <char> <char>\endmubyte". For example
+
+\begtt
+\mubyte A A\endmubyte
+\endtt
+%
+clears all <byte_sequences> from conversion table which begin with the
+character A. The following code clears all conversion table:
+
+\catcode`<=12
+\begtt
+{\catcode`\^^@=12
+\gdef\clearmubytes{\bgroup \count255=1
+   \loop \uccode`X=\count255
+       \uppercase{\mubyte XX\endmubyte}%
+       \advance\count255 by1
+       \ifnum\count255<256 \repeat
+   \mubyte ^^@^^@\endmubyte
+   \egroup}
+}
+\clearmubytes
+\endtt
+\catcode`<=13
+
+
+
+\sec Input and output sides of the conversion table
+%    ----------------------------------------------
+
+The conversion table consists from two independent parts: input side
+used by input processor and output side used during "\write" or
+printing to the log and terminal. You can save the record only to one
+of this parts by using the nonempty <optional_prefix>.
+If the <optional_prefix> is empty then the same record is stored
+twice: into input and output sides. If <optional_prefix> is a token of
+catcode~8 (usually the "_" character) then the record is stored only
+into input side . If <optional_prefix> is a pair of tokens catcode~8
+(usually "__") then the record is stored only into output side.
+
+If the optional prefix has a form of "__" then the following
+<byte_sequence> can be empty. Enc\TeX{} removes the record
+corresponding to the <first_token> from output side in such situation.
+
+The macro code for clearing the conversion table from previous section
+clears all records from input side but only the records concerned to
+the <first_token> in ``one byte form'' from output side.  You can 
+remove the record concerned to control sequence from output side 
+only by "\mubyte \foo __\endmubyte".
+
+\sec Inserted control sequences
+%    --------------------------
+
+If the <first_token> is the control sequence and the <optional_prefix>
+is one token of catcode~6 (usually the "#" character) 
+followed by <number>
+then the <number> bytes are kept by input
+processor (it means they are no converted again) 
+and the declared control sequence is inserted before
+<byte_sequence>. The example:
+
+\begtt
+\def\abc{ABC}
+\mubyte X BC\endmubyte \mubytein=1  
+\mubyte \foo #3 \abc\endmubyte  ABC is converted to \foo ABC
+\mubyte \foo #1 \abc\endmubyte  ABC is converted to \foo AX
+\endtt  
+
+The <number> has the same syntax as <number> from \TeX{}book.
+It means that ``one optional space'' can work as a separator of
+digit(s). See the previous example.
+
+If <number> is zero then the control sequence is inserted and the
+whole <byte_sequence> is unchanged. This has the same effect as if the
+<number> equals to the length of the <byte_sequence>.
+
+The <number> is accepted only in the range 0 to 50. The negative
+<numbers> are silently interpreted as zero and the numbers greater
+than 50 mean that the rest of the converted line will be unchanged
+by input processor.
+
+More practical example follows. Note, that the <number> is greater
+than the length of the <byte_sequence> here.
+
+\begtt
+\mubyte \warntwobytes  #2^^c3\endmubyte
+\mubyte \warntwobytes  #2^^c4\endmubyte
+\mubyte \warntwobytes  #2^^c5\endmubyte
+% atd...
+\def\warntwobytes #1#2{\message{WARNING: the UTF8 code: 
+   \noconvert#1\noconvert#2 is not defined i my macros.}}
+\endtt
+
+The new primitive "\noconvert" is used in this example 
+(see chapter~5). The similar code is used in the file
+"utf8unkn.tex".
+
+
+\sec The virtual mark of line begin
+%    ------------------------------
+
+If "\mubytein>0" and if the first byte in <byte_sequence> is equal to
+"\endlinechar" (it means <byte_sequence> has a format
+<endlinechar><rest>) 
+then input processor checks the matching of the
+<rest> with the begin of every line. If it matches then the given
+conversion is done. The example:
+
+\begtt
+\bgroup \uccode`X=\endlinechar \uppercase{\gdef\echar{X}}\egroup
+\mubyte \fooB \echar ABC\endmubyte % ABC matches at begin of line
+\mubyte \fooE ABC\echar \endmubyte % ABC matches at end of line 
+\mubyte \fooW \spce\space ABC\space \endmubyte
+     % ABC matches as a word with spaces before and after
+\mubyte \foo #\echar XYZ\endmubyte % 
+     % if XYZ is at begin of line the \foo is inserted before them
+\endtt
+
+\sec The suppression of the expansion in write parameters
+%    ----------------------------------------------------
+
+If you need to convert the control sequences back to its
+<byte_sequences> then the expansion of such control sequences is not
+welcome. You can suppress the expansion by "\let\macro=\relax" before
+"\write" starts the expansion of its parameter. But "\write" works
+asynchronously in most situations and you can manipulate with hundreds
+or thousands control sequences declared as UTF-8 codes. The enc\TeX{}
+serves a simple tool to solve this problem: If "\mubyteout>=3" then
+enc\TeX{} gives the "\relax" meaning to each control sequence declared
+in output side of the conversion table before the "\write" starts its
+expansion and it returns back these control sequences to their original
+meaning immediately after "\write" finish its work.
+Example:
+
+\begtt
+\mubyte \foo ABC\endmubyte  \def\foo{macro body}
+\mubyteout=2
+\immediate\write16{testwrite: \foo}  % prints "testwrite: macro body"
+\immediate\write16{testwrite: \noexpand\foo} % prints "testwrite: ABC"
+\mubyteout=3
+\immediate\write16{testwrite: \foo}  % prints "testwrite: ABC"
+\message{testmessage: \foo}          % prints "testmessage: macro body"
+\message{testmessage: \noexpand\foo} % prints "testmessage: \foo"
+\edef\a{testedef: \foo}              % expands to macro body
+\foo                                 % expands to macro body
+\immediate\write16{\meaning\foo}     % prints "\relax"
+\message{\meaning\foo}               % prints "macro:->macro body"
+\endtt
+
+Note the difference between "\message" and "\immediate\write16".
+The control sequences in "\message" parameter are always expanded and
+never converted to the <byte_sequence>. 
+
+You can set the ``noexpand'' flag (for "\write" parameters only)
+to any <control_sequence> and you need not declare the <byte_sequence>
+for it. Write "\mubyte <control_sequence> \relax \endmubyte" for this
+purposes. This has the same effect as
+"\mubyte" <control_sequence>" __\string" <control_sequence>"\space\endmubyte",
+but this second solution is more memory consuming because \TeX{} has
+to store the <byte_sequence> as a string to the pool.
+
+You can write your own macros which expand to one code in normal
+situation and to different code in write parameters. The declaration
+of "\writeparameter" control sequence is recommended:
+
+\begtt
+\mubyte \writeparameter \relax \endmubyte \def\writeparameter{}
+\def\mymacro{\ifx\writeparameter\relax THIS CODE IS USED IN WRITE.
+             \else THIS CODE IS USED IN NORMAL EXPANSION.\fi}
+\endtt
+
+
+
+\sec The asynchronous write command and the mubyteout value
+%    ------------------------------------------------------
+
+If you don't use "\immediate" then the "\write" command first gets its
+parameter but it expands and prints this parameter at another
+time. The "\write" command stores the actual value of the "\mubyteout"
+register when it gets its parameter. This value is used late when
+parameter is expanded and written to the file.
+
+This feature gives the possibility to write to more files, first (for
+table of contents, for example) is written with conversion to UTF-8
+and another files are written without this conversion, because (for
+example) this file is an input for a program which cannot read the 
+UTF-8 encoding. You can try:
+
+\begtt
+\newwrite\tocfile \newwrite\indexfile
+\immediate\openout\tocfile=\jobname.toc
+\immediate\openout\indexfile=\jobname.idx
+\mubyteout=3
+\write\tocfile{this parameter will be converted to UTF-8}
+{\mubyteout=0 \write\indexfile{this parameter stay unchanged}}
+\write\tocfile{this parameter will be converted to UTF-8}
+\end % now, all three writes are actually done
+\endtt
+
+\sec Summary of the mubyteout values
+%    -------------------------------
+
+Apart from the values 0, 1, 2 and 3, you can set the "\mubyteout"
+register to the value $-1$ or $-2$. The summary table of meanings of
+these values follows:
+
+\vbox{
+\begtt
+\mubyteout  <byte>-><byte_sequence>  <cs_name>-><byte_sequence>  noexpanding
+----------------------------------------------------------------------------
+   0             off                     off                 off
+   1             on                      off                 off
+   2             on                      on                  off
+   3             on                      on                  on
+  -1             on                      off                 on
+  -2             off                     off                 on
+\endtt
+\par}
+
+If the <byte>"->"<byte_sequence> conversion is on then all texts
+written to the "\write" files, log file and to the terminal are converted.
+On the other hand, the <cs_name>"->"<byte_sequence> conversion and the
+noexpanding are related only to the "\write" arguments (and the 
+"\special" arguments, see the following chapter).
+
+
+
+\kap The arguments of the special primitive
+     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+The plain texts in non-english languages can occur in 
+"\special" arguments. The PDF-outlines are a good
+example of this situation. May be,
+you need to save these arguments in UTF-8 encoding. 
+The enc\TeX{} gives the possibility to do it.
+
+The argument of "\special" is processed by the value of the integer
+primitive register "\specialout". This register is introduced by
+enc\TeX{} and its default value is zero.
+
+\begitems
+* "\specialout=0" -- no conversion, the same as in the original \TeX.
+* "\specialout=1" -- only the xchr conversion.
+* "\specialout=2" -- only the "\mubyteout" conversion.
+* "\specialout=3" -- the "\mubyteout" conversion followed by 
+                    the xchr conversion.
+\enditems
+
+The "\special" primitive expands its argument immediately. If
+"\specialout" is 2 or 3 then the expansion is done by "\mubyteout"
+value in the same manner as during the "\write" expansion.
+Moreover, "\special" saves the current values of "\specialout" and
+"\mubyteout" registers to its memory and use them at the time of the
+output to the "dvi" file.
+
+
+\kap The noconvert primitive
+     %%%%%%%%%%%%%%%%%%%%%%%
+
+The "\noconvert" primitive is introduced by enc\TeX. This primitive
+suppress the possible conversion of the following character or the
+control sequence. More exactly: the "\noconvert" is non expandable
+primitive and does nothing in typesetting output 
+(the same as "\relax"). If this primitive is used in "\message" or
+"\errmessage" argument then the control sequence of this primitive is
+never printed and the following character is not converted to
+<byte_sequence> even if the "\mubytelog" is positive and the character
+is recorded in output side of conversion table.
+
+The primitive "\noconvert" does the same in "\write" and "\special"
+parameters. Moreover, if a control sequence follows then this
+control sequence is normally printed even if the "\mubyteout" is positive
+and this control sequence is recorded in output side of conversion
+table.
+
+The "\noconvert\noconvert" yields to one "\noconvert" in the output.
+
+The "\noconvert" primitive is normally printed to the log and to the
+terminal in the another situation than "\message" and "\errmessage"
+parameters. For example when "\tracing..." is used.
+
+
+\kap Summary of the enc\TeX{}'s primitives
+     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begitems
+* "\mubyte"    --- new record to the conversion table, see chapter~3.
+* "\endmubyte" --- the "\mubyte" separator.
+* "\mubytein" --- integer register. 0: multi-byte input conversion
+                  suppressed, 1 and more: multi-byte input conversion 
+                  activated. 
+* "\mubyteout" --- integer register, the level of the output conversion
+                  in "\write" and "\special" parameters, see~3.10.
+* "\mubytelog" --- integer register, 0: multi-byte output conversion
+                  to log and terminal suppressed, 1 and more:  
+                  multi-byte output conversion activated.
+* "\specialout" --- integer register, the mode of the "\special"
+                   parameter conversion, see chapter~4.
+* "\noconvert" --- similar as "\noexpand", but for conversion process. 
+                  See~chapter~5.
+* "\xordcode" --- access to xord vector, see 2.1.
+* "\xchrcode" --- access to xchr vector, see 2.1.
+* "\xprncode" --- access to ``printability'' vector, see 2.2.
+\enditems
+
+The summary of <optional_prefixes> in "\mubyte" primitive follows. The
+character ``"#"'' means the token of category~6 and ``"_"'' means the token of
+category~7 here.
+
+\begitems
+* no prefix --- records to the input and output side of the conversion
+                table.
+* "_" --- records only to the input side of the conversion table.
+* "__" --- records only to the output side of the conversion table.
+* "#<number>" --- records to the input side of the conversion table, 
+                  the control sequence will be inserted and <number>
+                  bytes will be kept without conversion again.
+* "\relax" --- the control sequence will be not expand in "\write" 
+              parameters.
+\enditems
+
+More prefixes may be implemented in next versions of enc\TeX.  The
+prefix has its first character different from catcode 10, 11 or 12.
+This rule will be kept in next versions thus it is sufficient to use
+the first character of <byte_sequence> with this category if no prefix
+is needed.
+
+
+
+\kap The macro files
+     %%%%%%%%%%%%%%%
+
+The enc\TeX{} package includes some encoding tables inputted by
+"\input" during format generation. These tables support encodings
+widely used in Czech texts. The more information about these macro
+files are in comments of these files and in the Czech version of the
+documentation.
+
+
+
+\end
+
+
+
+
+
+
+
+
+
+
-- 
cgit v1.2.3

