summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/enctex/encdoc-e.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2006-01-09 00:56:57 +0000
committerKarl Berry <karl@freefriends.org>2006-01-09 00:56:57 +0000
commitf07bb53970ee2ecc53f81a206a3d3a67ef665e4a (patch)
tree6f57a1d62971db79e5ff023bdfd83b22cb971dc9 /Master/texmf-dist/doc/generic/enctex/encdoc-e.tex
parent007f67a693e4d031fd3d792df8e4d5f43e2cb2e7 (diff)
doc 6
git-svn-id: svn://tug.org/texlive/trunk@85 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/generic/enctex/encdoc-e.tex')
-rw-r--r--Master/texmf-dist/doc/generic/enctex/encdoc-e.tex947
1 files changed, 947 insertions, 0 deletions
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
+
+
+
+
+
+
+
+
+
+