path: root/Master/texmf-dist/source/latex/rtkinenc/rtkinenc.dtx

% \CheckSum{407}
%
% \iffalse
%
%<*driver>
\documentclass{ltxdoc}
\DeclareRobustCommand\package[1]{\textsf{#1}}
\title{The \package{rtkinenc} package}
\author{Lars Hellstr\"om%
   \thanks{E-mail: \texttt{Lars.Hellstrom@math.umu.se}}}
\begin{document}
\maketitle
\DocInput{rtkinenc.dtx}
\end{document}
%</driver>
% 
% \fi
% 
% \begin{abstract}
%   The \package{rtkinenc} package is functionally similar to the 
%   standard \LaTeX\ package \package{inputenc}---both set up active 
%   characters so that input character outside 7-bit ASCII are 
%   converted to the corresponding \LaTeX\ commands. Names of commands 
%   in \package{rtkinenc} have been selected so that it can read 
%   \package{inputenc} encoding definition files, and the aim is that 
%   \package{rtkinenc} should be backwards compatible with 
%   \package{inputenc}. \package{rtkinenc} is not a new version of 
%   \package{inputenc} though, nor is it part of standard \LaTeX.
%   
%   The main difference between the two packages lies in the view on the 
%   input. With \package{inputenc}, the non-ASCII characters in the 
%   input are considered as shorthand representations of the ``true'' 
%   document contents (usually one or several commands), and the 
%   conversion is therefore irreversible. With \package{rtkinenc} the 
%   input file itself is considered the true document, and the 
%   conversion of non-ASCII characters to \LaTeX\ commands is merely 
%   done becuase it is the first step on the preferred route to typeset 
%   output. If the command is for an unavailable text symbol, then it is 
%   possible to return to the raw input and try some fallback method of 
%   typesetting the character.
%   
%   The \package{inputenc} approach is natural for normal \LaTeX\ 
%   documents, but the \package{rtkinenc} approach is advantageous for 
%   program source code, where the \emph{true} meaning of a file is not 
%   defined by \TeX, but by the compiler, interpreter, or whatever.
% \end{abstract}
% 
% 
% 
% \StopEventually{}
% 
% \section{Implementation}
% 
%    \begin{macrocode}
%<*pkg>
\NeedsTeXFormat{LaTeX2e}[1995/12/01]
\ProvidesPackage{rtkinenc}
   [2000/01/24 v1.0 Rethinking input encoding package]
%    \end{macrocode}
% 
% 
% \subsection{Basic machanisms}
% 
% 
% \begin{macro}{\RIE@last@char}
%   |\RIE@last@char| is a |\count| register for storing the code 
%   of the raw character currently being typeset. It is minus one 
%   if no raw character is being typeset. This register should always 
%   be set globally.
%    \begin{macrocode}
\newcount\RIE@last@char
\global\RIE@last@char=\m@ne
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\RieC}
% \begin{macro}{\RIE@char}
% \begin{macro}{\RIE@text@char}
% \begin{macro}{\RIE@code@char}
%   The syntax for the |\RieC| command is
%   \begin{quote}
%     |\RieC|\marg{code}\marg{definition}
%   \end{quote}
%   Here \meta{code} is assumed to be a sequence of digits giving some 
%   raw character code, and \meta{definition} is assumed to be robust 
%   \LaTeX\ code for typesetting (some representation of) that raw 
%   character. |\RieC| is used as \package{inputenc}'s |\IeC| 
%   command---an |\RieC| with arguments form the definition of an 
%   active character---but it carries extra information in the 
%   \meta{code} argument.
%   
%   Depending on what the control sequences |\protect| and |\RIE@char| 
%   are there are three different things this can do.
%   \begin{itemize}
%     \item It can execute the \meta{definition} straight off. This 
%       happens when |\protect| is |\@typeset@protect| and |\RIE@char| 
%       is |\RIE@text@char|.
%     \item It can set |\RIE@last@char| to \meta{code}, then execute 
%       the \meta{definition}, and finally set |\RIE@last@char| to minus 
%       one. This happens when |\protect| is |\@typeset@protect| and 
%       |\RIE@char| is |\RIE@code@char|.
%       
%       Setting |\RIE@last@char| like that has the side-effect of 
%       prohibiting kerns and ligatures between the \meta{defintion} 
%       and what surrounds it. Therefore it is inapproriate to have 
%       |\RIE@char| equal to |\RIE@code@char| in many types of text, and 
%       by default it will not be.
%     \item It can expand to itself.\footnote{Unless some command in the 
%       \meta{definition} was defined using \cs{DeclareRobustCommand}, in 
%       which case it is the one level expansion of that command that 
%       will expand to itself. It all works out right in the end anyway.}
%       This happens when |\protect| is not |\@typeset@protect|, e.g.\ 
%       when writing to a file.
%   \end{itemize}
%   
%   |\RieC| cannot be defined using |\Declare|\-|Robust|\-|Command|, 
%   since that would insert |\protect|s that would prohibit normal 
%   kerning and ligaturing. Therefore the command robustness is 
%   maintained through an ad hoc definition (the |\def|). The reason for 
%   starting with an |\@ifundefined| is that the user shouldn't get 
%   less info about a redefinition than he\slash she would with a 
%   |\Declare|\-|Robust|\-|Command|.
%    \begin{macrocode}
\@ifundefined{RieC}{}{%
   \PackageError{rtkinenc}{Redefining \protect\RieC}{%
      I had expected \protect\RieC\space to be undefined.\MessageBreak
      Since it wasn't, there's a chance I have\MessageBreak
      broken something.\MessageBreak\@ehc
   }
}
\def\RieC{%
   \ifx \protect\@typeset@protect
      \expandafter\RIE@char
   \else
      \noexpand\RieC
   \fi
}
%    \end{macrocode}
%    \begin{macrocode}
\let\RIE@text@char=\@secondoftwo
\let\RIE@char=\RIE@text@char
%    \end{macrocode}
%    \begin{macrocode}
\def\RIE@code@char#1#2{%
   \global\RIE@last@char=#1
   #2%
   \global\RIE@last@char=\m@ne
}
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}\end{macro}
% 
% \begin{macro}{RieBC}
% \begin{macro}{RIE@both@char}
%   The syntax for the |\RieBC| command is
%   \begin{quote}
%     |\RieBC|\marg{code}\marg{text definition}\marg{math definition}
%   \end{quote}
%   Here \meta{code} is assumed to be a sequence of digits giving some 
%   raw character code, whereas \meta{text definition} and 
%   \meta{math definition} are assumed to be robust \LaTeX\ code for 
%   typesetting (some representation of) that raw character in text and 
%   math mode, respectively. |\RieBC| is used like |\RieC|, but offers 
%   the possibility of alternative definitions for increased 
%   typesetting quality.
%   
%    \begin{macrocode}
\@ifundefined{RieBC}{}{%
   \PackageError{rtkinenc}{Redefining \protect\RieBC}{%
      I had expected \protect\RieBC\space to be undefined.\MessageBreak
      Since it wasn't, there's a chance I have\MessageBreak
      broken something.\MessageBreak\@ehc
   }
}
\def\RieBC{%
   \ifx \protect\@typeset@protect
      \expandafter\RIE@both@char
   \else
      \noexpand\RieBC
   \fi
}
%    \end{macrocode}
%    \begin{macrocode}
\def\RIE@both@char#1#2#3{%
   \ifx \RIE@char\RIE@code@char
      \global\RIE@last@char=#1
   \fi
   \ifmmode #3\else #2\fi
   \ifx \RIE@char\RIE@code@char
      \global\RIE@last@char=\m@ne
   \fi
}
%    \end{macrocode}
% \end{macro}\end{macro}
% 
% 
% \begin{macro}{\TextSymbolUnavailable}
% \begin{macro}{\@@TextSymbolUnavailable}
% \begin{macro}{\SetUnavailableAction}
% \begin{macro}{\RIE@symbol@unavailable}
%   The only way to know whether a particular text command could be 
%   rendered as intended or not is to seize control of the standard 
%   \LaTeX\ command |\Text|\-|Symbol|\-|Unavailable|. This command will 
%   then be given a new definition which selects whether some raw 
%   character fallback macro or the standard \LaTeX\ error message 
%   should be given. The raw character fallback macro can be set using 
%   the |\Set|\-|Unavailable|\-|Action| command.
%   
%   Before seizing control of |\Text|\-|Symbol|\-|Unavailable|, one must 
%   make sure that it does not have its autoload definition. Then the 
%   \LaTeX\ definition is saved away in |\@@Text|\-|Symbol|\-^^A
%   |Unavailable|.
%    \begin{macrocode}
\def\@tempa{\@autoerr\TextSymbolUnavailable}
\ifx \@tempa\TextSymbolUnavailable
   \@autoerr\relax
\fi
\let\@@TextSymbolUnavailable=\TextSymbolUnavailable
%    \end{macrocode}
%   
%   Then the new definition is given. It is pretty straightforward.
%    \begin{macrocode}
\def\TextSymbolUnavailable{%
   \ifnum \m@ne<\RIE@last@char
      \expandafter\RIE@symbol@unavailable \expandafter\RIE@last@char
   \else
      \expandafter\@@TextSymbolUnavailable
   \fi
}
\PackageInfo{rtkinenc}{Redefining \protect\TextSymbolUnavailable}
%    \end{macrocode}
%   
%   The |\SetUnavailableAction| command locally defines the |\RIE@|\-^^A
%   |symbol@|\-|unavailable| macro, which is executed instead of the 
%   standard \LaTeX\ |\Text|\-|Symbol|\-|Unavailable| when the text 
%   symbol in case was the representation of a raw input character. 
%   |\Set|\-|Unavailable|\-|Action| is used as
%   \begin{quote}
%     |\SetUnavailableAction|\marg{definition}
%   \end{quote}
%   where \meta{definition} is like the last argument of |\newcommand|. 
%   The \meta{definition} may contain |#1| and |#2|, where |#1| will 
%   contain the current raw character number and |#2| will contain the 
%   text command for which no definition could be found.
%    \begin{macrocode}
\newcommand\SetUnavailableAction{\def\RIE@symbol@unavailable##1##2}
%    \end{macrocode}
%   The default fallback action is to call |\@@Text|\-|Symbol|\-^^A
%   |Unavailable|, but most of the definition deals with recognizing 
%   and handling the case that the input character hasn't been 
%   declared, rather than that its definition is not available. 
%   Normally, this shouldn't be used at all; instead the user should 
%   have installed another fallback.
%    \begin{macrocode}
\SetUnavailableAction{%
   \ifx #2\relax
      \begingroup
         \let\RIE@char=\RIE@text@char
         \RIE@undefined{#1}%
      \endgroup
   \else
      \@@TextSymbolUnavailable{#2}%
   \fi
}
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}\end{macro}
%
% 
% \begin{macro}{\RIE@undefined}
%   The |\RIE@undefined| macro is used in the definition of input 
%   characters which are not defined in the current input encoding. It 
%   takes one argument, namely the code for the character in question. 
%   In text mode, this is an error. In code mode, it is passed on to 
%   the unavailable-action macro |\RIE@|\-|symbol@|\-|unavailable|. The 
%   default value of |\RIE@|\-|symbol@|\-|unavailable| recognizes the 
%   |\relax| passed as second argument below as a flag that in reality 
%   it's the input character that hasn't been defined.
%    \begin{macrocode}
\def\RIE@undefined#1{%
   \ifx \RIE@char\RIE@text@char
      \PackageError{rtkinenc}{%
         Input character #1 is undefined\MessageBreak
         in inputencoding \RIE@encoding}\@eha
   \else
      \RIE@symbol@unavailable{#1}\relax
   \fi
}
%    \end{macrocode}
% \end{macro}
%  
% 
% \begin{macro}{\InputModeCode}
% \begin{macro}{\InputModeText}
% \begin{macro}{\IfInputModeCode}
%   The |\InputModeCode| and |\InputModeText| commands switch to the 
%   `code' and `text' respectively modes for the \package{rtkinenc} 
%   package. They both act locally, since it is often convenient to have 
%   the previous mode restored at the end of an environment.
%   
%   The |\IfInputModeCode| command can be used to test which mode the 
%   \package{rtkinenc} package currently is in. Is is used as
%   \begin{quote}
%     |\IfInputModeCode|\marg{code}\marg{text}
%   \end{quote}
%   This will expand to \meta{code} or \meta{text} when the current mode 
%   is code mode or text mode, respectively.
%    \begin{macrocode}
\newcommand\InputModeCode{\let\RIE@char=\RIE@code@char}
\newcommand\InputModeText{\let\RIE@char=\RIE@text@char}
\newcommand\IfInputModeCode{%
   \ifx \RIE@char\RIE@code@char
      \expandafter\@firstoftwo
   \else
      \expandafter\@secondoftwo
   \fi
}
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}
% 
% 
% \subsection{Setting the input encoding}
% 
% The first two commands are identical; the duplication is only for 
% being compabile with \package{inputenc}. The reason that there are two 
% different commands in \package{inputenc} is that |\Declare|\-|Input|^^A
% \-|Math| saves a little memory by not taking special measures to see 
% to that a space (if there is any) that follows the input character is 
% not gobbled in case it is written to a temporary file and subsequently 
% read back. Saving that small amount of memory is not the aim for 
% \package{rtkinenc}, which is instead using up even more memory by 
% including the character code in the definition.
% 
% \begin{macro}{\DeclareInputText}
% \begin{macro}{\DeclareInputMath}
%   These two commands are used as
%   \begin{quote}
%     |\DeclareInputText|\marg{slot}\marg{definition}\\
%     |\DeclareInputMath|\marg{slot}\marg{definition}
%   \end{quote}
%   This makes the active character whose character code is 
%   \meta{slot} a parameterless macro whose expansion is
%   \begin{quote}
%     |\RieC|\marg{slot (sanitized)}\marg{definition}
%   \end{quote}
%   \meta{slot (sanitized)} has the same numerical value as 
%   \meta{slot}, but consists only of decimal digits. \meta{definition} 
%   is the same in both cases.
%   
%    \begin{macrocode}
\expandafter\ifx \csname DeclareInputText\endcsname\relax
   \begingroup
      \catcode\z@=13
      \gdef\DeclareInputText#1#2{%
         \@inpenc@test
         \begingroup
            \uccode\z@=#1%
            \uppercase{%
         \endgroup
            \expandafter\def \expandafter^^@%
         }\expandafter{\expandafter\RieC \expandafter{\number#1}{#2}}%
      }%
   \endgroup
\else
   \PackageError{rtkinenc}{\protect\DeclareInputText\space
      already defined}{\@ehd\MessageBreak 
      Likely cause: you are already using the inputenc package.}
\fi
%    \end{macrocode}
%    \begin{macrocode}
\@ifundefined{DeclareInputMath}{%
   \let\DeclareInputMath=\DeclareInputText
}{%
   \PackageError{rtkinenc}{\protect\DeclareInputMath\space
      already defined}{\@ehd\MessageBreak 
      Likely cause: you are already using the inputenc package.}
}
%    \end{macrocode}
% \end{macro}\end{macro}
% 
% \begin{macro}{\DeclareInputBoth}
%   The |\DeclareInputBoth| command is similar to |\Declare|\-^^A
%   |Input|\-|Text| and |\Declare|\-|Input|\-|Math| commands, but it 
%   offers an extra feature---the text and math definitions of a 
%   character can be different. |\Declare|\-|Input|\-|Both| is used as
%   \begin{quote}
%     |\DeclareInputBoth|\marg{slot}\marg{text}\marg{math}
%   \end{quote}
%   where \meta{text} and \meta{math} are the text and math mode 
%   definitions respectively.
%    \begin{macrocode}
\expandafter\ifx \csname DeclareInputBoth\endcsname\relax
   \begingroup
      \catcode\z@=13
      \gdef\DeclareInputBoth#1#2#3{%
         \@inpenc@test
         \begingroup
            \uccode\z@=#1%
            \uppercase{%
         \endgroup
            \expandafter\def \expandafter^^@%
         }\expandafter{\expandafter\RieBC \expandafter{\number#1}%
            {#2}{#3}%
         }%
      }%
   \endgroup
\else
   \PackageError{rtkinenc}{\protect\DeclareInputBoth\space
      already defined}\@ehd
\fi
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\inputencoding}
% \begin{macro}{\@inpenc@test}
% \begin{macro}{\RIE@encoding}
%   The |\inputencoding| command sets the current input encoding to be 
%   the one specified in its only argument. First all characters are 
%   set to be active and defined as |\RIE@undefined|\marg{slot}, except 
%   for Null (|^^@|), tab (|^^I|), line feed (|^^J|), form feed (|^^L|), 
%   carriage return (|^^M|), and space--|~| which are left as they were. 
%   Then |#1.def| is inputed; this file is expected to contain all the 
%   |\DeclareInput|\textellipsis\ commands that are needed for the 
%   wanted input encoding.
%   
%   Besides that, |\inputencoding| also does a check to see that the 
%   file |#1.def| actually did execute some |\DeclareInput|^^A
%   \textellipsis\ command. Since it wouldn't at all surprise me if 
%   someone likes to tinker with this test, it is done exactly as in 
%   \package{inputenc}.
%   
%   |\inputencoding| should not be used in horizontal mode since space 
%   tokens within the file inputed will produce unwanted spaces in the 
%   output.
%   
%   |\RIE@encoding| stores the name of the current input encoding. It is 
%   used in an error message by |\RIE@undefined|.
%   
%    \begin{macrocode}
\def\inputencoding#1{%
   \gdef\@inpenc@test{\global\let\@inpenc@test\relax}%
   \protected@edef\RIE@encoding{#1}%
   \ifvmode
      \RIE@loop\^^A\^^H%
      \RIE@loop\^^K\^^K%
      \RIE@loop\^^N\^^_%
      \RIE@loop\^^?\^^ff%
      \input{#1.def}%
   \fi
   \ifx \@inpenc@test\relax \else
      \PackageWarning{rtkinenc}%
              {No characters defined\MessageBreak
               by input encoding change to `#1'}%
   \fi
}  
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}
%
% \begin{macro}{\RIE@loop}
%   The |\RIE@loop| command makes characters |#1| to |#2| inclusive 
%   active and undefined.
%    \begin{macrocode}
\begingroup
   \catcode\z@=\active
   \gdef\RIE@loop#1#2{%
      \@tempcnta=`#1\relax
      \count@=\uccode\z@
      \loop
         \catcode\@tempcnta\active
         \uccode\z@=\@tempcnta
         \uppercase{%
            \expandafter\def \expandafter^^@\expandafter{%
               \expandafter\RIE@undefined\expandafter{\the\@tempcnta}%
            }%
         }%
      \ifnum `#2>\@tempcnta
         \advance \@tempcnta \@ne
      \repeat
      \uccode\z@=\count@
   }
\endgroup
%    \end{macrocode}
% \end{macro}
% 
% 
% \subsection{Miscellanea}
% 
% \begin{macro}{\TypesetHexNumber}
% \begin{macro}{\TypesetOctalNumber}
%   In many computer languages, special character escape sequences based 
%   on character codes must be written with the character code in 
%   hexadecimal or octal notation. These commands take a \TeX\ number 
%   in the interval 0--255 as argument and typesets it using the 
%   hexadecimal (figures |0|--|9| and |a|--|f|) or octal (figures 
%   |0|--|7|) notation. No font changes or \TeX\ mode changes are made. 
%   |\TypesetHexNumber| always typesets two characters, 
%   |\TypesetOctalNumber| always typesets three characters. 
%   
%   Care has been taken to see to that every count register can be used 
%   as the argument of these two macros, and they only make local 
%   assignments. They do not check that the argument is in range, though.
%    \begin{macrocode}
\newcommand\TypesetHexNumber[1]{%
   \begingroup
      \count@=#1\relax
      \chardef\@tempa=\count@
      \divide \count@ \sixt@@n
      \ifcase\count@
         0\or 1\or 2\or 3\or 4\or 5\or 6\or 7\or 8\or 9\or a\or b\or
         c\or d\or e\else f%
      \fi
      \multiply \count@ -\sixt@@n
      \advance \count@ \@tempa
      \ifcase\count@
         0\or 1\or 2\or 3\or 4\or 5\or 6\or 7\or 8\or 9\or a\or b\or
         c\or d\or e\else f%
      \fi
   \endgroup
}
%    \end{macrocode}
%    \begin{macrocode}
\newcommand\TypesetOctalNumber[1]{%
   \begingroup
      \count@=#1\relax
      \chardef\@tempa=\count@
      \divide \count@ 64\relax
      \the\count@
      \multiply \count@ -64%
      \advance \count@ \@tempa
      \chardef\@tempa=\count@
      \divide \count@ 8\relax
      \the\count@
      \multiply \count@ -8%
      \advance \count@ \@tempa
      \the\count@
   \endgroup
}
%    \end{macrocode}
% \end{macro}\end{macro}
% 
% \begin{macro}{\verifycharcode}
%   The |\verifycharcode| command is used as
%   \begin{quote}
%     |\verifycharcode|\marg{character}\marg{code}
%   \end{quote}
%   Here \meta{character} can be any \meta{character token} (as defined 
%   in \emph{The \TeX book}); e.g.\ a control sequence whose name 
%   consists of one charater. \meta{code} can be any valid \meta{number}. 
%   If \meta{code} is not the character code of the \meta{character}, 
%   then |\verifycharcode| makes a warning about this.
%   
%   The purpose of this command is to detect when the code of some 
%   character used in a document is changed. Today these things happen 
%   mainly when transferring a document between two systems which use
%   different encodings, and it is usually the right thing do. Some 
%   computer programs (and now I mean the source) do however rely on the 
%   exact character codes used in them, and documents containing such 
%   programs may use the |\verifycharcode| to test that none of the 
%   critical characters have been altered.
%    \begin{macrocode}
\newcommand\verifycharcode[2]{%
   \ifnum `#1=#2 \else
      \PackageWarning{rtkinenc}{%
         Input character with code \number#2\MessageBreak
         should be the character with code \number`#1}%
   \fi
}
%    \end{macrocode}
% \end{macro}
% 
% 
% \subsection{Option processing}
% 
% Each option is interpreted as the name of an input encoding. That 
% input encoding definition file is inputed.
% 
%    \begin{macrocode}
\DeclareOption*{\inputencoding{\CurrentOption}}
\ProcessOptions
%</pkg>
%    \end{macrocode}
% 
% \Finale
\endinput