Debian Codegraph @

texmf-dist/source/latex/rtkinenc/rtkinenc.dtx

raw
1 % \CheckSum{407}
2 %
3 % \iffalse
4 %
5 %<*driver>
6 \documentclass{ltxdoc}
7 \DeclareRobustCommand\package[1]{\textsf{#1}}
8 \title{The \package{rtkinenc} package}
9 \author{Lars Hellstr\"om%
10 \thanks{E-mail: \texttt{[email protected]}}}
11 \begin{document}
12 \maketitle
13 \DocInput{rtkinenc.dtx}
14 \end{document}
15 %</driver>
16 %
17 % \fi
18 %
19 % \begin{abstract}
20 % The \package{rtkinenc} package is functionally similar to the
21 % standard \LaTeX\ package \package{inputenc}---both set up active
22 % characters so that input character outside 7-bit ASCII are
23 % converted to the corresponding \LaTeX\ commands. Names of commands
24 % in \package{rtkinenc} have been selected so that it can read
25 % \package{inputenc} encoding definition files, and the aim is that
26 % \package{rtkinenc} should be backwards compatible with
27 % \package{inputenc}. \package{rtkinenc} is not a new version of
28 % \package{inputenc} though, nor is it part of standard \LaTeX.
29 %
30 % The main difference between the two packages lies in the view on the
31 % input. With \package{inputenc}, the non-ASCII characters in the
32 % input are considered as shorthand representations of the ``true''
33 % document contents (usually one or several commands), and the
34 % conversion is therefore irreversible. With \package{rtkinenc} the
35 % input file itself is considered the true document, and the
36 % conversion of non-ASCII characters to \LaTeX\ commands is merely
37 % done becuase it is the first step on the preferred route to typeset
38 % output. If the command is for an unavailable text symbol, then it is
39 % possible to return to the raw input and try some fallback method of
40 % typesetting the character.
41 %
42 % The \package{inputenc} approach is natural for normal \LaTeX\
43 % documents, but the \package{rtkinenc} approach is advantageous for
44 % program source code, where the \emph{true} meaning of a file is not
45 % defined by \TeX, but by the compiler, interpreter, or whatever.
46 % \end{abstract}
47 %
48 %
49 %
50 % \StopEventually{}
51 %
52 % \section{Implementation}
53 %
54 % \begin{macrocode}
55 %<*pkg>
56 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
57 \ProvidesPackage{rtkinenc}
58 [2000/01/24 v1.0 Rethinking input encoding package]
59 % \end{macrocode}
60 %
61 %
62 % \subsection{Basic machanisms}
63 %
64 %
65 % \begin{macro}{\RIE@last@char}
66 % |\RIE@last@char| is a |\count| register for storing the code
67 % of the raw character currently being typeset. It is minus one
68 % if no raw character is being typeset. This register should always
69 % be set globally.
70 % \begin{macrocode}
71 \newcount\RIE@last@char
72 \global\RIE@last@char=\m@ne
73 % \end{macrocode}
74 % \end{macro}
75 %
76 % \begin{macro}{\RieC}
77 % \begin{macro}{\RIE@char}
78 % \begin{macro}{\RIE@text@char}
79 % \begin{macro}{\RIE@code@char}
80 % The syntax for the |\RieC| command is
81 % \begin{quote}
82 % |\RieC|\marg{code}\marg{definition}
83 % \end{quote}
84 % Here \meta{code} is assumed to be a sequence of digits giving some
85 % raw character code, and \meta{definition} is assumed to be robust
86 % \LaTeX\ code for typesetting (some representation of) that raw
87 % character. |\RieC| is used as \package{inputenc}'s |\IeC|
88 % command---an |\RieC| with arguments form the definition of an
89 % active character---but it carries extra information in the
90 % \meta{code} argument.
91 %
92 % Depending on what the control sequences |\protect| and |\RIE@char|
93 % are there are three different things this can do.
94 % \begin{itemize}
95 % \item It can execute the \meta{definition} straight off. This
96 % happens when |\protect| is |\@typeset@protect| and |\RIE@char|
97 % is |\RIE@text@char|.
98 % \item It can set |\RIE@last@char| to \meta{code}, then execute
99 % the \meta{definition}, and finally set |\RIE@last@char| to minus
100 % one. This happens when |\protect| is |\@typeset@protect| and
101 % |\RIE@char| is |\RIE@code@char|.
102 %
103 % Setting |\RIE@last@char| like that has the side-effect of
104 % prohibiting kerns and ligatures between the \meta{defintion}
105 % and what surrounds it. Therefore it is inapproriate to have
106 % |\RIE@char| equal to |\RIE@code@char| in many types of text, and
107 % by default it will not be.
108 % \item It can expand to itself.\footnote{Unless some command in the
109 % \meta{definition} was defined using \cs{DeclareRobustCommand}, in
110 % which case it is the one level expansion of that command that
111 % will expand to itself. It all works out right in the end anyway.}
112 % This happens when |\protect| is not |\@typeset@protect|, e.g.\
113 % when writing to a file.
114 % \end{itemize}
115 %
116 % |\RieC| cannot be defined using |\Declare|\-|Robust|\-|Command|,
117 % since that would insert |\protect|s that would prohibit normal
118 % kerning and ligaturing. Therefore the command robustness is
119 % maintained through an ad hoc definition (the |\def|). The reason for
120 % starting with an |\@ifundefined| is that the user shouldn't get
121 % less info about a redefinition than he\slash she would with a
122 % |\Declare|\-|Robust|\-|Command|.
123 % \begin{macrocode}
124 \@ifundefined{RieC}{}{%
125 \PackageError{rtkinenc}{Redefining \protect\RieC}{%
126 I had expected \protect\RieC\space to be undefined.\MessageBreak
127 Since it wasn't, there's a chance I have\MessageBreak
128 broken something.\MessageBreak\@ehc
129 }
130 }
131 \def\RieC{%
132 \ifx \protect\@typeset@protect
133 \expandafter\RIE@char
134 \else
135 \noexpand\RieC
136 \fi
137 }
138 % \end{macrocode}
139 % \begin{macrocode}
140 \let\RIE@text@char=\@secondoftwo
141 \let\RIE@char=\RIE@text@char
142 % \end{macrocode}
143 % \begin{macrocode}
144 \def\RIE@code@char#1#2{%
145 \global\RIE@last@char=#1
146 #2%
147 \global\RIE@last@char=\m@ne
148 }
149 % \end{macrocode}
150 % \end{macro}\end{macro}\end{macro}\end{macro}
151 %
152 % \begin{macro}{RieBC}
153 % \begin{macro}{RIE@both@char}
154 % The syntax for the |\RieBC| command is
155 % \begin{quote}
156 % |\RieBC|\marg{code}\marg{text definition}\marg{math definition}
157 % \end{quote}
158 % Here \meta{code} is assumed to be a sequence of digits giving some
159 % raw character code, whereas \meta{text definition} and
160 % \meta{math definition} are assumed to be robust \LaTeX\ code for
161 % typesetting (some representation of) that raw character in text and
162 % math mode, respectively. |\RieBC| is used like |\RieC|, but offers
163 % the possibility of alternative definitions for increased
164 % typesetting quality.
165 %
166 % \begin{macrocode}
167 \@ifundefined{RieBC}{}{%
168 \PackageError{rtkinenc}{Redefining \protect\RieBC}{%
169 I had expected \protect\RieBC\space to be undefined.\MessageBreak
170 Since it wasn't, there's a chance I have\MessageBreak
171 broken something.\MessageBreak\@ehc
172 }
173 }
174 \def\RieBC{%
175 \ifx \protect\@typeset@protect
176 \expandafter\RIE@both@char
177 \else
178 \noexpand\RieBC
179 \fi
180 }
181 % \end{macrocode}
182 % \begin{macrocode}
183 \def\RIE@both@char#1#2#3{%
184 \ifx \RIE@char\RIE@code@char
185 \global\RIE@last@char=#1
186 \fi
187 \ifmmode #3\else #2\fi
188 \ifx \RIE@char\RIE@code@char
189 \global\RIE@last@char=\m@ne
190 \fi
191 }
192 % \end{macrocode}
193 % \end{macro}\end{macro}
194 %
195 %
196 % \begin{macro}{\TextSymbolUnavailable}
197 % \begin{macro}{\@@TextSymbolUnavailable}
198 % \begin{macro}{\SetUnavailableAction}
199 % \begin{macro}{\RIE@symbol@unavailable}
200 % The only way to know whether a particular text command could be
201 % rendered as intended or not is to seize control of the standard
202 % \LaTeX\ command |\Text|\-|Symbol|\-|Unavailable|. This command will
203 % then be given a new definition which selects whether some raw
204 % character fallback macro or the standard \LaTeX\ error message
205 % should be given. The raw character fallback macro can be set using
206 % the |\Set|\-|Unavailable|\-|Action| command.
207 %
208 % Before seizing control of |\Text|\-|Symbol|\-|Unavailable|, one must
209 % make sure that it does not have its autoload definition. Then the
210 % \LaTeX\ definition is saved away in |\@@Text|\-|Symbol|\-^^A
211 % |Unavailable|.
212 % \begin{macrocode}
213 \def\@tempa{\@autoerr\TextSymbolUnavailable}
214 \ifx \@tempa\TextSymbolUnavailable
215 \@autoerr\relax
216 \fi
217 \let\@@TextSymbolUnavailable=\TextSymbolUnavailable
218 % \end{macrocode}
219 %
220 % Then the new definition is given. It is pretty straightforward.
221 % \begin{macrocode}
222 \def\TextSymbolUnavailable{%
223 \ifnum \m@ne<\RIE@last@char
224 \expandafter\RIE@symbol@unavailable \expandafter\RIE@last@char
225 \else
226 \expandafter\@@TextSymbolUnavailable
227 \fi
228 }
229 \PackageInfo{rtkinenc}{Redefining \protect\TextSymbolUnavailable}
230 % \end{macrocode}
231 %
232 % The |\SetUnavailableAction| command locally defines the |\RIE@|\-^^A
233 % |symbol@|\-|unavailable| macro, which is executed instead of the
234 % standard \LaTeX\ |\Text|\-|Symbol|\-|Unavailable| when the text
235 % symbol in case was the representation of a raw input character.
236 % |\Set|\-|Unavailable|\-|Action| is used as
237 % \begin{quote}
238 % |\SetUnavailableAction|\marg{definition}
239 % \end{quote}
240 % where \meta{definition} is like the last argument of |\newcommand|.
241 % The \meta{definition} may contain |#1| and |#2|, where |#1| will
242 % contain the current raw character number and |#2| will contain the
243 % text command for which no definition could be found.
244 % \begin{macrocode}
245 \newcommand\SetUnavailableAction{\def\RIE@symbol@unavailable##1##2}
246 % \end{macrocode}
247 % The default fallback action is to call |\@@Text|\-|Symbol|\-^^A
248 % |Unavailable|, but most of the definition deals with recognizing
249 % and handling the case that the input character hasn't been
250 % declared, rather than that its definition is not available.
251 % Normally, this shouldn't be used at all; instead the user should
252 % have installed another fallback.
253 % \begin{macrocode}
254 \SetUnavailableAction{%
255 \ifx #2\relax
256 \begingroup
257 \let\RIE@char=\RIE@text@char
258 \RIE@undefined{#1}%
259 \endgroup
260 \else
261 \@@TextSymbolUnavailable{#2}%
262 \fi
263 }
264 % \end{macrocode}
265 % \end{macro}\end{macro}\end{macro}\end{macro}
266 %
267 %
268 % \begin{macro}{\RIE@undefined}
269 % The |\RIE@undefined| macro is used in the definition of input
270 % characters which are not defined in the current input encoding. It
271 % takes one argument, namely the code for the character in question.
272 % In text mode, this is an error. In code mode, it is passed on to
273 % the unavailable-action macro |\RIE@|\-|symbol@|\-|unavailable|. The
274 % default value of |\RIE@|\-|symbol@|\-|unavailable| recognizes the
275 % |\relax| passed as second argument below as a flag that in reality
276 % it's the input character that hasn't been defined.
277 % \begin{macrocode}
278 \def\RIE@undefined#1{%
279 \ifx \RIE@char\RIE@text@char
280 \PackageError{rtkinenc}{%
281 Input character #1 is undefined\MessageBreak
282 in inputencoding \RIE@encoding}\@eha
283 \else
284 \RIE@symbol@unavailable{#1}\relax
285 \fi
286 }
287 % \end{macrocode}
288 % \end{macro}
289 %
290 %
291 % \begin{macro}{\InputModeCode}
292 % \begin{macro}{\InputModeText}
293 % \begin{macro}{\IfInputModeCode}
294 % The |\InputModeCode| and |\InputModeText| commands switch to the
295 % `code' and `text' respectively modes for the \package{rtkinenc}
296 % package. They both act locally, since it is often convenient to have
297 % the previous mode restored at the end of an environment.
298 %
299 % The |\IfInputModeCode| command can be used to test which mode the
300 % \package{rtkinenc} package currently is in. Is is used as
301 % \begin{quote}
302 % |\IfInputModeCode|\marg{code}\marg{text}
303 % \end{quote}
304 % This will expand to \meta{code} or \meta{text} when the current mode
305 % is code mode or text mode, respectively.
306 % \begin{macrocode}
307 \newcommand\InputModeCode{\let\RIE@char=\RIE@code@char}
308 \newcommand\InputModeText{\let\RIE@char=\RIE@text@char}
309 \newcommand\IfInputModeCode{%
310 \ifx \RIE@char\RIE@code@char
311 \expandafter\@firstoftwo
312 \else
313 \expandafter\@secondoftwo
314 \fi
315 }
316 % \end{macrocode}
317 % \end{macro}\end{macro}\end{macro}
318 %
319 %
320 % \subsection{Setting the input encoding}
321 %
322 % The first two commands are identical; the duplication is only for
323 % being compabile with \package{inputenc}. The reason that there are two
324 % different commands in \package{inputenc} is that |\Declare|\-|Input|^^A
325 % \-|Math| saves a little memory by not taking special measures to see
326 % to that a space (if there is any) that follows the input character is
327 % not gobbled in case it is written to a temporary file and subsequently
328 % read back. Saving that small amount of memory is not the aim for
329 % \package{rtkinenc}, which is instead using up even more memory by
330 % including the character code in the definition.
331 %
332 % \begin{macro}{\DeclareInputText}
333 % \begin{macro}{\DeclareInputMath}
334 % These two commands are used as
335 % \begin{quote}
336 % |\DeclareInputText|\marg{slot}\marg{definition}\\
337 % |\DeclareInputMath|\marg{slot}\marg{definition}
338 % \end{quote}
339 % This makes the active character whose character code is
340 % \meta{slot} a parameterless macro whose expansion is
341 % \begin{quote}
342 % |\RieC|\marg{slot (sanitized)}\marg{definition}
343 % \end{quote}
344 % \meta{slot (sanitized)} has the same numerical value as
345 % \meta{slot}, but consists only of decimal digits. \meta{definition}
346 % is the same in both cases.
347 %
348 % \begin{macrocode}
349 \expandafter\ifx \csname DeclareInputText\endcsname\relax
350 \begingroup
351 \catcode\z@=13
352 \gdef\DeclareInputText#1#2{%
353 \@inpenc@test
354 \begingroup
355 \uccode\z@=#1%
356 \uppercase{%
357 \endgroup
358 \expandafter\def \expandafter^^@%
359 }\expandafter{\expandafter\RieC \expandafter{\number#1}{#2}}%
360 }%
361 \endgroup
362 \else
363 \PackageError{rtkinenc}{\protect\DeclareInputText\space
364 already defined}{\@ehd\MessageBreak
365 Likely cause: you are already using the inputenc package.}
366 \fi
367 % \end{macrocode}
368 % \begin{macrocode}
369 \@ifundefined{DeclareInputMath}{%
370 \let\DeclareInputMath=\DeclareInputText
371 }{%
372 \PackageError{rtkinenc}{\protect\DeclareInputMath\space
373 already defined}{\@ehd\MessageBreak
374 Likely cause: you are already using the inputenc package.}
375 }
376 % \end{macrocode}
377 % \end{macro}\end{macro}
378 %
379 % \begin{macro}{\DeclareInputBoth}
380 % The |\DeclareInputBoth| command is similar to |\Declare|\-^^A
381 % |Input|\-|Text| and |\Declare|\-|Input|\-|Math| commands, but it
382 % offers an extra feature---the text and math definitions of a
383 % character can be different. |\Declare|\-|Input|\-|Both| is used as
384 % \begin{quote}
385 % |\DeclareInputBoth|\marg{slot}\marg{text}\marg{math}
386 % \end{quote}
387 % where \meta{text} and \meta{math} are the text and math mode
388 % definitions respectively.
389 % \begin{macrocode}
390 \expandafter\ifx \csname DeclareInputBoth\endcsname\relax
391 \begingroup
392 \catcode\z@=13
393 \gdef\DeclareInputBoth#1#2#3{%
394 \@inpenc@test
395 \begingroup
396 \uccode\z@=#1%
397 \uppercase{%
398 \endgroup
399 \expandafter\def \expandafter^^@%
400 }\expandafter{\expandafter\RieBC \expandafter{\number#1}%
401 {#2}{#3}%
402 }%
403 }%
404 \endgroup
405 \else
406 \PackageError{rtkinenc}{\protect\DeclareInputBoth\space
407 already defined}\@ehd
408 \fi
409 % \end{macrocode}
410 % \end{macro}
411 %
412 %
413 % \begin{macro}{\inputencoding}
414 % \begin{macro}{\@inpenc@test}
415 % \begin{macro}{\RIE@encoding}
416 % The |\inputencoding| command sets the current input encoding to be
417 % the one specified in its only argument. First all characters are
418 % set to be active and defined as |\RIE@undefined|\marg{slot}, except
419 % for Null (|^^@|), tab (|^^I|), line feed (|^^J|), form feed (|^^L|),
420 % carriage return (|^^M|), and space--|~| which are left as they were.
421 % Then |#1.def| is inputed; this file is expected to contain all the
422 % |\DeclareInput|\textellipsis\ commands that are needed for the
423 % wanted input encoding.
424 %
425 % Besides that, |\inputencoding| also does a check to see that the
426 % file |#1.def| actually did execute some |\DeclareInput|^^A
427 % \textellipsis\ command. Since it wouldn't at all surprise me if
428 % someone likes to tinker with this test, it is done exactly as in
429 % \package{inputenc}.
430 %
431 % |\inputencoding| should not be used in horizontal mode since space
432 % tokens within the file inputed will produce unwanted spaces in the
433 % output.
434 %
435 % |\RIE@encoding| stores the name of the current input encoding. It is
436 % used in an error message by |\RIE@undefined|.
437 %
438 % \begin{macrocode}
439 \def\inputencoding#1{%
440 \gdef\@inpenc@test{\global\let\@inpenc@test\relax}%
441 \protected@edef\RIE@encoding{#1}%
442 \ifvmode
443 \RIE@loop\^^A\^^H%
444 \RIE@loop\^^K\^^K%
445 \RIE@loop\^^N\^^_%
446 \RIE@loop\^^?\^^ff%
447 \input{#1.def}%
448 \fi
449 \ifx \@inpenc@test\relax \else
450 \PackageWarning{rtkinenc}%
451 {No characters defined\MessageBreak
452 by input encoding change to `#1'}%
453 \fi
454 }
455 % \end{macrocode}
456 % \end{macro}\end{macro}\end{macro}
457 %
458 % \begin{macro}{\RIE@loop}
459 % The |\RIE@loop| command makes characters |#1| to |#2| inclusive
460 % active and undefined.
461 % \begin{macrocode}
462 \begingroup
463 \catcode\z@=\active
464 \gdef\RIE@loop#1#2{%
465 \@tempcnta=`#1\relax
466 \count@=\uccode\z@
467 \loop
468 \catcode\@tempcnta\active
469 \uccode\z@=\@tempcnta
470 \uppercase{%
471 \expandafter\def \expandafter^^@\expandafter{%
472 \expandafter\RIE@undefined\expandafter{\the\@tempcnta}%
473 }%
474 }%
475 \ifnum `#2>\@tempcnta
476 \advance \@tempcnta \@ne
477 \repeat
478 \uccode\z@=\count@
479 }
480 \endgroup
481 % \end{macrocode}
482 % \end{macro}
483 %
484 %
485 % \subsection{Miscellanea}
486 %
487 % \begin{macro}{\TypesetHexNumber}
488 % \begin{macro}{\TypesetOctalNumber}
489 % In many computer languages, special character escape sequences based
490 % on character codes must be written with the character code in
491 % hexadecimal or octal notation. These commands take a \TeX\ number
492 % in the interval 0--255 as argument and typesets it using the
493 % hexadecimal (figures |0|--|9| and |a|--|f|) or octal (figures
494 % |0|--|7|) notation. No font changes or \TeX\ mode changes are made.
495 % |\TypesetHexNumber| always typesets two characters,
496 % |\TypesetOctalNumber| always typesets three characters.
497 %
498 % Care has been taken to see to that every count register can be used
499 % as the argument of these two macros, and they only make local
500 % assignments. They do not check that the argument is in range, though.
501 % \begin{macrocode}
502 \newcommand\TypesetHexNumber[1]{%
503 \begingroup
504 \count@=#1\relax
505 \chardef\@tempa=\count@
506 \divide \count@ \sixt@@n
507 \ifcase\count@
508 0\or 1\or 2\or 3\or 4\or 5\or 6\or 7\or 8\or 9\or a\or b\or
509 c\or d\or e\else f%
510 \fi
511 \multiply \count@ -\sixt@@n
512 \advance \count@ \@tempa
513 \ifcase\count@
514 0\or 1\or 2\or 3\or 4\or 5\or 6\or 7\or 8\or 9\or a\or b\or
515 c\or d\or e\else f%
516 \fi
517 \endgroup
518 }
519 % \end{macrocode}
520 % \begin{macrocode}
521 \newcommand\TypesetOctalNumber[1]{%
522 \begingroup
523 \count@=#1\relax
524 \chardef\@tempa=\count@
525 \divide \count@ 64\relax
526 \the\count@
527 \multiply \count@ -64%
528 \advance \count@ \@tempa
529 \chardef\@tempa=\count@
530 \divide \count@ 8\relax
531 \the\count@
532 \multiply \count@ -8%
533 \advance \count@ \@tempa
534 \the\count@
535 \endgroup
536 }
537 % \end{macrocode}
538 % \end{macro}\end{macro}
539 %
540 % \begin{macro}{\verifycharcode}
541 % The |\verifycharcode| command is used as
542 % \begin{quote}
543 % |\verifycharcode|\marg{character}\marg{code}
544 % \end{quote}
545 % Here \meta{character} can be any \meta{character token} (as defined
546 % in \emph{The \TeX book}); e.g.\ a control sequence whose name
547 % consists of one charater. \meta{code} can be any valid \meta{number}.
548 % If \meta{code} is not the character code of the \meta{character},
549 % then |\verifycharcode| makes a warning about this.
550 %
551 % The purpose of this command is to detect when the code of some
552 % character used in a document is changed. Today these things happen
553 % mainly when transferring a document between two systems which use
554 % different encodings, and it is usually the right thing do. Some
555 % computer programs (and now I mean the source) do however rely on the
556 % exact character codes used in them, and documents containing such
557 % programs may use the |\verifycharcode| to test that none of the
558 % critical characters have been altered.
559 % \begin{macrocode}
560 \newcommand\verifycharcode[2]{%
561 \ifnum `#1=#2 \else
562 \PackageWarning{rtkinenc}{%
563 Input character with code \number#2\MessageBreak
564 should be the character with code \number`#1}%
565 \fi
566 }
567 % \end{macrocode}
568 % \end{macro}
569 %
570 %
571 % \subsection{Option processing}
572 %
573 % Each option is interpreted as the name of an input encoding. That
574 % input encoding definition file is inputed.
575 %
576 % \begin{macrocode}
577 \DeclareOption*{\inputencoding{\CurrentOption}}
578 \ProcessOptions
579 %</pkg>
580 % \end{macrocode}
581 %
582 % \Finale
583 \endinput