Debian Codegraph @

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

raw
1 %% \CheckSum{724}
2 % \iffalse (Comment)
3 % This is the code for the relenc package, with doc style comments.
4 % \fi
5 %
6 % \iffalse (Driver code)
7 % (The driver is enclosed in a macrocode environment, even though the
8 % iffalse will make \TeX\ skip past it, just in case.)
9 % \begin{macrocode}
10 %<*driver>
11 \documentclass{ltxdoc}
12 \usepackage{2sidedoc}
13 \newcommand\B{\penalty300\relax}
14 \newcommand\package[1]{\textsf{#1}}
15 \title{\texttt{relenc.dtx}}
16 \author{Lars Hellstr\"om%
17 \thanks{E-mail: \texttt{[email protected]}}%
18 }
19 \date{1999/01/23}
20 \begin{document}
21 \maketitle
22 \DocInput{relenc.dtx}
23 \begin{thebibliography}{99}
24 %
25 \bibitem{ltoutenc}
26 Johannes Braams, David Carlisle, Alan Jeffrey, Frank Mittelbach,
27 Chris Rowley, Rainer Sch\"opf: \texttt{ltoutenc.dtx} (part of the
28 \LaTeXe\ base distribution).
29 %
30 \bibitem{fontinst}
31 Alan Jeffrey, Rowland McDonnell (manual), Sebastian Rahtz,
32 Ulrik Vieth: \emph{The fontinst utility} (v\,1.8),
33 \texttt{fontinst.dtx}, in CTAN at \texttt{ftp:/\slash
34 ftp.tex.ac.uk\slash tex-archive\slash fonts\slash utilities\slash
35 fontinst\slash}\textellipsis
36 %
37 \bibitem{fntguide}
38 \LaTeX3 Project Team: \emph{\LaTeXe\ font selection},
39 \texttt{fntguide.tex} (part of the \LaTeXe\ base distribution).
40 %
41 \bibitem{encguide}
42 Frank Mittelbach [et al. ?]: \texttt{encguide.tex}. To appear as
43 part of the \LaTeXe\ base distribution. Sometime. Or at least, that
44 is the intention.
45 %
46 \end{thebibliography}
47 \end{document}
48 %</driver>
49 % \end{macrocode}
50 % \fi
51 %
52 % \StopEventually{}
53 %
54 % \section{Implementation}
55 % \label{Implementation}
56 %
57 % \iffalse (Comment)
58 % The following code really belong in the preamble, but since there
59 % are two documents which contain the text in this file, I prefer to
60 % put the code in one place instead.
61 % \fi
62 % \makeatletter
63 % \def\gobble@zeroX#10X{}
64 % \newcommand\St@rtShowGeneric[1]{^^A
65 % \begin{list}{}{^^A
66 % \@beginparpenalty=\predisplaypenalty
67 % \@endparpenalty=\postdisplaypenalty
68 % \@itempenalty=100\relax
69 % \setlength\leftmargin\z@
70 % \setlength\rightmargin\z@
71 % \setlength\listparindent\z@
72 % \setlength\parsep\z@skip
73 % \setlength\itemsep\z@skip
74 % \MacroFont
75 % \frenchspacing
76 % }^^A
77 % \ifnum#1<\@ne\else
78 % \item[]\leavevmode
79 % \rlap{
80 % \count@=\z@
81 % \loop
82 % \ \advance\count@\@ne
83 % \if \expandafter\gobble@zeroX \the\count@ X0XXX^^A
84 % ^^A \the\count@ does not end with 0.
85 % \else
86 % \hb@xt@\z@{{\hss\normalfont\tiny\the\count@\hss}}^^A
87 % \fi
88 % \ifnum\count@<#1\relax\repeat
89 % \llap{\strut\vrule}^^A
90 % }^^A
91 % \fi
92 % \def\mynewline{\unskip\hfil\penalty-\@M\vadjust{}}
93 % \set@display@protect
94 % }
95 % \newcommand\ShowGenericError[5][0]{^^A
96 % \St@rtShowGeneric{#1}^^A
97 % \item[]^^A
98 % \def\MessageBreak{\mynewline#2}^^A
99 % ! #3.\mynewline\mynewline
100 % #4\mynewline
101 % Type H <return> for immediate help\mynewline
102 % \ ...\mynewline\mynewline
103 % I.100\mynewline\mynewline
104 % \item[]^^A
105 % \def\MessageBreak{\mynewline}^^A
106 % ? h\mynewline
107 % #5\mynewline
108 % \end{list}^^A
109 % }
110 % \newcommand{\ShowGenericWarningOrInfo}[3][0]{^^A
111 % \St@rtShowGeneric{#1}^^A
112 % \item[]^^A
113 % \def\MessageBreak{\mynewline#2}^^A
114 % #3.\par
115 % \end{list}
116 % }
117 % \newcommand{\ShowPackageError}[4][0]{^^A
118 % \ShowGenericError[#1]{^^A
119 % (#2)\@spaces\@spaces\@spaces\@spaces
120 % }{^^A
121 % Package #2 Error: #3^^A
122 % }{^^A
123 % See the #2 package documentation for explanation.^^A
124 % }{#4}^^A
125 % }
126 % \newcommand\ShowPackageWarning[3][0]{^^A
127 % \ShowGenericWarningOrInfo[#1]{^^A
128 % (#2)\@spaces\@spaces\@spaces\@spaces
129 % }{^^A
130 % Package #2 Warning: #3^^A
131 % }^^A
132 % }
133 % \newcommand\ShowPackageInfo[3][0]{^^A
134 % \ShowGenericWarningOrInfo[#1]{^^A
135 % (#2) \@spaces\@spaces\@spaces
136 % }{^^A
137 % Package #2 Info: #3^^A
138 % }^^A
139 % }
140 % \makeatother
141 %
142 %
143 % \subsection{Initial stuff}
144 % The obligatory header code for a \LaTeXe\ package.
145 % \begin{macrocode}
146 %<*package>
147 \NeedsTeXFormat{LaTeX2e}[1994/06/01]
148 \ProvidesPackage{relenc}[1999/01/23]
149 % \end{macrocode}
150 % \bigskip
151 %
152 % At the moment, there are no options for the \package{relenc} package.
153 %
154 %
155 % \subsection{Variables and similar things}
156 %
157 % \begin{macro}{\RE@temptoks}
158 % |\RE@temptoks| is used by the basic search mechaism to store
159 % the part of the search path that has not yet been used.
160 % \begin{macrocode}
161 \newtoks\RE@temptoks
162 % \end{macrocode}
163 % \end{macro}
164 % \begin{macro}{\RE@garbage}
165 % The |\RE@garbage| macro is used as a target for some assignments that
166 % really shouldn't be made, but where a mechanism for detecting this
167 % would not be worth the cost. It is also used as a temporary storage
168 % by some definition commands.
169 % \end{macro}
170 % \begin{macro}{\RE@first@search@item}
171 % During a search, the |\RE@first@search@item| macro will expand the
172 % first item in the search path. This is needed for the define first
173 % mechanism to work.
174 % \end{macro}
175 % \begin{macro}{\RE@define@first}
176 % The |\RE@define@first| macro works like a switch. If it is
177 % |\RE@active@define|\B|@first| then the define first mechanism is
178 % active: If the search does not find anything on the first try but
179 % finds something later then the first command in the search path gets
180 % |\let| to whatever the search finds. If |\RE@define@first| is
181 % |\@gobbletwo| then the define first mechanism is inactive and nothing
182 % happens. This construction allows for other possibilities as well.
183 %
184 % The initial setting is |\@gobbletwo|, i.e., off.
185 % \begin{macrocode}
186 \let\RE@define@first\@gobbletwo
187 % \end{macrocode}
188 % \end{macro}
189 %
190 %
191 % \subsection{Search mechanisms for variable commands}
192 %
193 % Variable commands are intended to be used as definitions of
194 % encoding-specific commands or compositions of such. Thus variable
195 % commands are actually instances of some user level command, which is
196 % not the same \TeX\ control sequence as the variable command itself.
197 %
198 % A variable command is defined to be a parameterless macro whose
199 % expansion consists of two tokens. The first is |\RE@text@variable| if
200 % the command is not a composition and it is |\RE@text@comp@variable| if
201 % the command is a composition. The second token is the user level
202 % command itself; this command will not be expanded, its name is merely
203 % used as a word-stem from which names of possible variants are formed.
204 % Thus if the definition of the user level command |\foo| in the
205 % \texttt{T1R} encoding (which would be stored in the control sequence
206 % |\T1R\foo|) would be a variable command, that definition would be
207 % \begin{quote}
208 % |\RE@text@variable|\,|\foo|
209 % \end{quote}
210 %
211 %
212 % \subsubsection{Identifying the search path and initiating the search}
213 % \begin{macro}{\RE@text@variable}
214 % \begin{macro}{\RE@text@comp@variable}
215 % \begin{macro}{\RE@spath@unavailable}
216 % \begin{macro}{\RE@spath@available}
217 % The first thing |\RE@text@variable| must do is to find the
218 % search path to use. It might be either a family-specific search
219 % path, in which case it is stored in the macro
220 % |\|\meta{encoding}|/|\meta{family}\texttt{-path},
221 % or the general search path for the entire encoding, in which case
222 % it is stored in the macro |\|\meta{encoding}\texttt{-path}.
223 % If the family-specific search path exists, it is chosen. If neither
224 % exists, this is an error which is reported.
225 %
226 % The second thing |\RE@text@variable| does is setting up the
227 % search along the search path. This is by expanding to
228 % \begin{quote}
229 % |\RE@first@read@spath|\,\meta{search path}\,^^A
230 % |\RE@read@spath|
231 % \end{quote}
232 % which starts the next phase of the search.
233 %
234 % \begin{macrocode}
235 \def\RE@text@variable{%
236 \expandafter\ifx \csname\cf@encoding/\f@family-path\endcsname \relax
237 \expandafter\ifx \csname\cf@encoding-path\endcsname \relax
238 \RE@spath@unavailable
239 \else
240 \RE@spath@available\RE@first@read@spath\RE@read@spath
241 \fi
242 \else
243 \expandafter\expandafter \expandafter\RE@first@read@spath
244 \csname\cf@encoding/\f@family-path\expandafter\endcsname
245 \expandafter\RE@read@spath
246 \fi
247 }
248 % \end{macrocode}
249 % Hackers may find a few things in the definition a little strange.
250 % To begin with, I use |\cf@encoding|\label{Why cf@encoding}
251 % for the name of the current
252 % encoding, although \cite{fntguide} says that |\f@encoding|
253 % is defined as precisely that. I too find this a little odd, but the
254 % corresponding routines in the \LaTeXe\ kernel use |\cf@encoding|
255 % (see~\cite{ltoutenc}) so I suppose that is safer, for some
256 % reason. I believe the only time at which |\cf@encoding| and
257 % |\f@encoding| are different is during a font change, but I might
258 % be mistaken about that.
259 %
260 % The usage of |\RE@spath@unavailable| and |\RE@spath@available|
261 % might also be confusing, but the alternative to this is heavily
262 % nested |\expandafter| sequences, and those things are not easy to
263 % read. Besides, |\RE@spath@unavailable| must do something with the
264 % initial command token anyway, because |\RE@text|\B|@variable| does
265 % not move it.
266 %
267 % |\RE@spath@available| have two real arguments: The initial search
268 % command header (which can be |\RE@first@read@spath| or
269 % |\RE@first@comp@read|\B|@spath|) and the initial search command tail
270 % (which can be |\RE@read@spath| or |\RE@comp@read@spath|). The other
271 % arguments are ``dummys'' used to remove unvanted tokens.
272 %
273 % All arguments of |\RE@spath@unavailable| are such dummys.
274 %
275 % \begin{macrocode}
276 \def\RE@spath@available#1#2#3\fi#4\fi{\fi\fi
277 \expandafter\expandafter \expandafter#1%
278 \csname\cf@encoding-path\endcsname#2%
279 }
280 % \end{macrocode}
281 % \begin{macrocode}
282 \def\RE@spath@unavailable#1\fi#2\fi#3{%
283 \fi\fi
284 \PackageError{relenc}{%
285 There is no search path for relaxed encoding \cf@encoding%
286 }\@eha
287 }
288 % \end{macrocode}
289 %
290 % Example error message:
291 % \ShowPackageError{relenc}{There is no search path for relaxed
292 % encoding XX}{\csname @eha\endcsname}
293 %
294 % The reason that |\RE@text@comp@variable| and |\RE@text@variable|
295 % exist as separate macros is that there are separate commands
296 % |\RE@first@comp|\B|@read|\B|@spath| and |\RE@first@read@spath| at
297 % the next stage of the search process.
298 %
299 % \begin{macrocode}
300 \def\RE@text@comp@variable{%
301 \expandafter\ifx \csname\cf@encoding/\f@family-path\endcsname \relax
302 \expandafter\ifx \csname\cf@encoding-path\endcsname \relax
303 \RE@spath@unavailable
304 \else
305 \RE@spath@available\RE@first@comp@read@spath\RE@comp@read@spath
306 \fi
307 \else
308 \expandafter\expandafter \expandafter\RE@first@comp@read@spath
309 \csname\cf@encoding/\f@family-path\expandafter\endcsname
310 \expandafter\RE@comp@read@spath
311 \fi
312 }
313 % \end{macrocode}
314 % \end{macro}
315 % \end{macro}
316 % \end{macro}
317 % \end{macro}
318 %
319 %
320 %
321 % \subsubsection{Performing the search}
322 %
323 % Between the steps of the second stage of the search, the initial
324 % font-dependent command (|\foo| say) will have expanded to
325 % \begin{quote}
326 % \meta{search header}\,\meta{remaining search path}\,^^A
327 % \meta{search tail}\,|\foo|
328 % \end{quote}
329 % The \meta{search header} can be one of |\RE@read@spath|,
330 % |\RE@first@read@spath|, |\RE@comp@read@spath|, and
331 % |\RE@first@comp@read@spath|. The \meta{search tail} can be either
332 % |\RE@read@spath| or |\RE@comp@read@spath|.
333 %
334 % The \meta{search path} consists mainly of a sequence of blocks that
335 % looks as follows
336 % \begin{quote}
337 % |{| \meta{character tokens, macros} |}|
338 % \end{quote}
339 % The macros should also expand to character tokens. At each step, the
340 % first of these blocks is extracted as the |#1| argument of the search
341 % header. The remaining blocks are put in the |#2| argument and if no
342 % definition is found then these will be the \meta{remaining search path}
343 % to use when setting up for the next step. For the moment, it is put
344 % away in the token list register |\RE@temptoks|.
345 %
346 % Argument |#1| is first checked for whether the
347 % control sequence formed by expanding
348 % \begin{quote}
349 % |\csname|\,|#1|\,|\string|\,|#3|\,|\endcsname|
350 % \end{quote}
351 % (|#3| is the control sequence named |\foo| above) exists. If it does,
352 % it is assumed to be the definition of |\foo| for the current font,
353 % otherwise everything is set up for the next step using the
354 % \meta{remaining search path} as search path.
355 %
356 % There is no check to see if |#2| is empty, so if the entire search path
357 % consisted of blocks like the one above, using a font-dependent command
358 % for which no definition has been given would cause an infinite loop.
359 % There is however a hack which prevents this: When a search path is set
360 % using the proper command, the control sequence |\RE@var@not@found| is
361 % appended to the search path. Primarily, this macro is a hack that
362 % prevents the search loop from going haywire, but it also has the
363 % advantage of stopping the expansion of the search header from stripping
364 % off the braces around the last group prematurely (when
365 % \begin{quote}
366 % |\RE@read@spath|\,|{a}|\,|{b}|\,|{cd}|\,|\RE@read@spath|\,|\foo|
367 % \end{quote}
368 % is expanded |#1| will be |a| and |#2| will be |{b}|\,|{cd}|, but when
369 % \begin{quote}
370 % |\RE@read@spath|\,|{b}|\,|{cd}|\,|\RE@read@spath|\,|\foo|
371 % \end{quote}
372 % is expanded |#1| will be |b| and |#2| will be |cd|, so the next time
373 % round, |#1| will be |c| and |#2| will be |d|---the last group has been
374 % split---but if the last item in the search path is not a group, but a
375 % single token, there is no group to split).
376 %
377 % \begin{macro}{\RE@read@spath}
378 % \begin{macro}{\RE@first@read@spath}
379 % \begin{macro}{\RE@comp@read@spath}
380 % \begin{macro}{\RE@first@comp@read@spath}
381 % Considering their usage only, the difference between |\RE@read@spath|
382 % and |\RE@comp|\B|@read|\B|@spath| is that |\RE@read@spath| is used
383 % for actual font-dependent commands while |\RE@comp@read@spath| is
384 % used for compositions of a font-dependent command and its argument.
385 % In that case, the third argument will not be |\foo| but rather
386 % something like |\\foo-a| (a single control sequence, the first
387 % backslash is the escape character and the second is part of the
388 % actual name); this particular case occurs when the user has written
389 % |\foo|\,|{a}|).
390 %
391 % If, on the other hand, their definitions are looked at, the
392 % difference is that while |\RE@read@spath| checks if the expansion of
393 % \begin{quote}
394 % |\csname|\,|#1|\,|\string|\,|#3|\,|\endcsname|
395 % \end{quote}
396 % is defined, |\RE@comp@read@spath| checks if the expansion of
397 % \begin{quote}
398 % |\csname|\,|#1|\,|\@empty\|\,|string|\,|#3|\,|\endcsname|
399 % \end{quote}
400 % is defined. In most cases, these expand to the same thing (since
401 % |\@empty| is a parameterless macro which expands to nothing), but
402 % sometimes one needs to write a |#1| which gives somewhat different
403 % results depending on whether |#3| is a command or a composition.
404 % These blocks in the search path can now simply test whether the token
405 % after the parameter is |\@empty| or |\string|. The two macros that
406 % currently do this are |\RE@var@not@found| and |\RE@convert@nfss|.
407 %
408 % The difference between |\RE@read@spath| and |\RE@first@read@spath|
409 % is that the latter is used in the first step, while the former is
410 % used in all the other steps. This difference exists because of the
411 % define first mechanism: If |\RE@first|\B|@read|\B|@spath| finds a
412 % definition in the first step, there is no need to call the mechanism
413 % no matter what the value of |\RE@define@first| is, but if
414 % |\RE@first@read@spath| does not find a definition then it must store
415 % the first block of the search path for a possible future use by
416 % |\RE@active@define@first|. |\RE@read@spath|, on the other hand,
417 % should never store a search path block, but if it finds a
418 % definition then it should call |\RE@define@first| since the define
419 % first mechanism might be active.
420 %
421 % Quite naturally, |\RE@comp@read@spath| relates to
422 % |\RE@first@comp@read@spath| as |\RE@read@spath| to
423 % |\RE@first@read@spath| and |\RE@first@comp@read@spath| relates to
424 % |\RE@first@read@spath| as |\RE@comp@read@spath| to |\RE@read@spath|
425 % [phew!].
426 %
427 % \begin{macrocode}
428 \def\RE@read@spath#1#2\RE@read@spath#3{%
429 \RE@temptoks={#2}%
430 \expandafter\ifx \csname#1\string#3\endcsname \relax
431 \expandafter\RE@read@spath \the\expandafter\RE@temptoks
432 \expandafter\RE@read@spath \expandafter#3%
433 \else
434 \RE@define@first{#1}{#3}%
435 \csname#1\string#3\expandafter\endcsname
436 \fi
437 }
438 % \end{macrocode}
439 % \begin{macrocode}
440 \def\RE@first@read@spath#1#2\RE@read@spath#3{%
441 \RE@temptoks={#2}%
442 \expandafter\ifx \csname#1\string#3\endcsname \relax
443 \def\RE@first@search@item{#1}%
444 \expandafter\RE@read@spath \the\expandafter\RE@temptoks
445 \expandafter\RE@read@spath \expandafter#3%
446 \else
447 \csname#1\string#3\expandafter\endcsname
448 \fi
449 }
450 % \end{macrocode}
451 % \begin{macrocode}
452 \def\RE@comp@read@spath#1#2\RE@comp@read@spath#3{%
453 \RE@temptoks={#2}%
454 \expandafter\ifx \csname#1\@empty\string#3\endcsname \relax
455 \expandafter\RE@comp@read@spath \the\expandafter\RE@temptoks
456 \expandafter\RE@comp@read@spath \expandafter#3%
457 \else
458 \RE@define@first{#1\@empty}{#3}%
459 \csname#1\@empty\string#3\expandafter\endcsname
460 \fi
461 }
462 % \end{macrocode}
463 % \begin{macrocode}
464 \def\RE@first@comp@read@spath#1#2\RE@comp@read@spath#3{%
465 \RE@temptoks={#2}%
466 \expandafter\ifx \csname#1\@empty\string#3\endcsname \relax
467 \def\RE@first@search@item{#1\@empty}%
468 \expandafter\RE@comp@read@spath \the\expandafter\RE@temptoks
469 \expandafter\RE@comp@read@spath \expandafter#3%
470 \else
471 \csname#1\@empty\string#3\expandafter\endcsname
472 \fi
473 }
474 % \end{macrocode}
475 %
476 % The definition of |\RE@read@spath| is not quite trivial. It must
477 % not leave any |\fi| up ahead, since everything should eventually
478 % expand to the actual definition of the searched-for command, and
479 % this is very likely to have parameters. There must be no surplus
480 % tokens between this command and its arguments; this is why
481 %\begin{verbatim}
482 % \def\RE@read@spath#1#2\RE@read@spath#3{%
483 % \RE@temptoks={#2}%
484 % \expandafter\ifx \csname#1\string#3\endcsname \relax
485 % \expandafter\RE@read@spath\the\RE@temptoks\RE@read@spath#3%
486 % \else
487 % \RE@define@first{#1}{#3}%
488 % \csname#1\string#3\endcsname
489 % \fi
490 % }
491 %\end{verbatim}
492 % would not do as a definition of |\RE@read@spath|.
493 %
494 % A definition that would work is
495 %\begin{verbatim}
496 % \def\RE@read@spath#1#2\RE@read@spath#3{%
497 % \expandafter\ifx \csname#1\string#3\endcsname \relax
498 % \expandafter\@firstoftwo
499 % \else
500 % \expandafter\@secondoftwo
501 % \fi{%
502 % \RE@read@spath#2\RE@read@spath#3%
503 % }{%
504 % \RE@define@first{#1}{#3}%
505 % \csname#1\string#3\endcsname
506 % }%
507 % }
508 %\end{verbatim}
509 % but I prefer the ``save away'' definition since it makes a few
510 % additional features possible; the most important perhaps being that
511 % it gives a chance to peek in afterwards and see where the search
512 % ended (using |\ShowVariantSearchResult|).
513 % \end{macro}
514 % \end{macro}
515 % \end{macro}
516 % \end{macro}
517 %
518 %
519 %
520 % \subsubsection{Miscellaneous search-related macros}
521 %
522 % \begin{macro}{\RE@active@define@first}
523 % \begin{macro}{\RE@again@read@spath}
524 % |\RE@active@define@first| is the macro which performs the actual
525 % assignments done by the define first mechanism, if it is active.
526 % The macro simply expands to the suitable global assignment; |#1| is
527 % the block from the search path that found a definition (with
528 % |\@empty| added if the search was for a composition) and |#2| is the
529 % command or composition whose definition was searched.
530 %
531 % \begin{macrocode}
532 \def\RE@active@define@first#1#2{%
533 \global\expandafter\let
534 \csname\RE@first@search@item\string#2\expandafter\endcsname
535 \csname#1\string#2\endcsname
536 }
537 % \end{macrocode}
538 % In some cases, the scan of the search path is resumed after a
539 % variant has been found. This is made possible by the fact that the
540 % remaining serach path is stored in |\RE@temptoks|, but the define
541 % first mechanism adds a complication. It cannot be allowed to copy a
542 % variant other than the first in the search path as that could
543 % actually change the effect of a command.
544 %
545 % The typical case here (the only one possible to define using user
546 % level commands of \package{relenc}) is that a command has two
547 % variants, one of which is composed and one which is not. The
548 % composed occurs before the noncomposed and the default definition of
549 % the composed is to resume the scan of the search path. If the
550 % command is executed for an argument for which there is no
551 % composition, an active define first mechanism will hide all
552 % composite definitions!
553 %
554 % Thus the define first mechanism must be temporarily disabled.
555 % One way to do this is to put a dummy value in
556 % |\RE@first@search@item|, and this solution is implemented in
557 % |\RE@again@read@spath|.\label{RE@again@read@spath}
558 % \begin{macrocode}
559 \def\RE@again@read@spath{%
560 \def\RE@first@search@item##1\expandafter\endcsname{%
561 RE@garbage\expandafter\endcsname
562 }%
563 \expandafter\RE@read@spath \the\RE@temptoks \RE@read@spath
564 }
565 % \end{macrocode}
566 % \end{macro}\end{macro}
567 %
568 %
569 % \begin{macro}{\RE@var@not@found}
570 % \begin{macro}{\RE@gobble@readspath}
571 % \begin{macro}{\RE@text@comp@unavail}
572 % These macros put a graceful end to a search that has found
573 % nothing. When |\RE@var@not@found|, which should be the very last token
574 % in every search path (it is automatically added by
575 % |\SetEncodingSearchPath| and |\SetFamilySearchPath|), is expanded
576 % it should appear in the following context
577 % \begin{quote}
578 % |\expandafter|\,|\ifx|\,|\csname|\,|\RE@var@not@found|\,^^A
579 % \meta{optional \cs{@empty}}\\
580 % |\string|\,\meta{command or composition}\,|\endcsname|
581 % \end{quote}
582 % As |\RE@var@not@found| inserts an additional |\endcsname| and |\fi|
583 % when expanded by the |\csname|, the entire |\ifx| is finished
584 % before \TeX{} gets to |\RE@gobble|\B|@readspath|. There are however
585 % a lot of mismatched tokens left over by |\RE@var@not@found|, some of
586 % which will be used in composing the error message.
587 %
588 % \begin{macrocode}
589 \def\RE@var@not@found{relax\endcsname\relax\fi
590 \RE@gobble@readspath
591 }
592 % \end{macrocode}
593 %
594 % When |\RE@gobble@readspath| is expanded, it is in the context
595 % \begin{quote}
596 % |\RE@gobble@readspath|\,\meta{optional \cs{@empty}}\,^^A
597 % |\string|\\ \meta{command or composition}\,^^A
598 % |\endcsname|\,\meta{some text}\,|\fi|
599 % \end{quote}
600 % The |\fi| is the |\fi| that originally matched the |\ifx| mensioned
601 % above.
602 %
603 % The |\@empty| is there iff \meta{command or composition} is a
604 % composition. If it is, this composition is |\string|ed and the
605 % first backslash is thrown away. Then the remaining `other' tokens
606 % are given to |\RE@text@comp@unavail| which will figure out what is
607 % the original command and what is its argument. If it is not a
608 % composition, the command is given to |\TextSymbolUnavailable|. In
609 % any case, everything up to and including the |\fi| disappears.
610 %
611 % \begin{macrocode}
612 \def\RE@gobble@readspath#1\string#2\endcsname#3\fi{%
613 \ifx\@empty#1%
614 % \end{macrocode}
615 % If |#2| is a composition then
616 % \begin{macrocode}
617 \expandafter\expandafter \expandafter\RE@text@comp@unavail
618 \expandafter\@gobble \string#2\RE@text@comp@unavail
619 \else
620 \TextSymbolUnavailable{#2}%
621 \fi
622 }
623 % \end{macrocode}
624 %
625 % As there is a hyphen between the original command and its argument,
626 % |\RE@text@comp@unavail| splits the name of the composition at the
627 % first hyphen. This is the right thing to do as long as |-| is not
628 % used as part of the name of the original command (unlikely, as
629 % \LaTeX\ does not define |\-| as an encoding-specific command).
630 %
631 % \begin{macrocode}
632 \def\RE@text@comp@unavail#1-#2\RE@text@comp@unavail{%
633 \PackageError{relenc}{%
634 The composition of command #1 with #2\MessageBreak is declared %
635 in encoding \cf@encoding,\MessageBreak but no definition could %
636 be found%
637 }\@eha
638 }
639 % \end{macrocode}
640 %
641 % Example error text:
642 % \iffalse Some editing is necessary to compensate for the \catcode
643 % differences.\fi
644 %
645 % \ShowPackageError{relenc}{The composition of command
646 % \protect\foo\space with A\MessageBreak is declared in encoding
647 % XXX,\MessageBreak but no definition could be found}
648 % {\csname@eha\endcsname}
649 % \end{macro}
650 % \end{macro}
651 % \end{macro}
652 %
653 %
654 %
655 % \subsection{Making variable text commands}
656 %
657 % \subsubsection{Miscellaneous support macros}
658 %
659 % \begin{macro}{\RE@empty@is@qmark}
660 % Expands to its argument if that is nonempty, otherwise it expands
661 % to |?|. This macro is primarily meant to be used inside a |\csname|
662 % \textellipsis\ |\endcsname| block. As always, an ingenious fool might
663 % break it, but a category 3 |^^M| is extremely unlikely (and hard to
664 % type), so it should work for any reasonable argument.
665 % \begin{macrocode}
666 \begingroup
667 \lccode`\$=13\relax
668 \lowercase{%
669 \gdef\RE@empty@is@qmark#1{\ifx$#1$?\else#1\fi}%
670 }
671 \endgroup
672 % \end{macrocode}
673 % \end{macro}
674 %
675 % \begin{macro}{\RE@font@spec}
676 % This macro concatenates the four parameters \meta{encoding},
677 % \meta{family}, \meta{series}, and \meta{shape} into
678 % \package{relenc}'s name for this font, i.e., puts slashes between
679 % the arguments and replaces every empty argument with a question mark.
680 % \begin{macrocode}
681 \def\RE@font@spec#1#2#3#4{%
682 \RE@empty@is@qmark{#1}/\RE@empty@is@qmark{#2}/%
683 \RE@empty@is@qmark{#3}/\RE@empty@is@qmark{#4}%
684 }
685 % \end{macrocode}
686 % \end{macro}
687 %
688 % \begin{macro}{\RE@bsl@string}
689 % One thing which complicates the definition of the definition commands
690 % (which must work even if they appear in a font definition file) is
691 % that \LaTeX\ has the naughty habit of changing the \TeX\ parameter
692 % |\escapechar| when it is defing a new font (loading the
693 % corresponding font definition file). The |\escapechar| parameter
694 % decides which character, if any, should be put in front of a control
695 % sequence name which is |\string|ed or written to the log file as
696 % part of some |\tracing|\textellipsis\ operation. (To see this effect
697 % yourself, set |\tracingmacros| positive just before a font change
698 % that loads a new font definition file (better reset it to zero
699 % after the font change though) and have a look at the log
700 % file---throughout a large chunk of logged macro expansions there
701 % are no backslashes on the command names!) The reason I don't
702 % like this is that (i) it doesn't achieve anything that couldn't just
703 % as well be achieved by a combination of |\expandafter| and gobbling
704 % of unwanted tokens and (ii) some font definition files are read by
705 % \LaTeX\ having |\escapechar| set to its normal value, so you can't
706 % trust it either way!
707 %
708 % Still, that is how \LaTeX\ does it and this must somehow be coped
709 % with. The |\RE@bsl@string| macro acts like |\string| but inserts a
710 % backslash in front of control sequence names even when |\string|
711 % wouldn't insert anything there. It is used instead of |\string| in
712 % all defining commands.
713 %
714 % \begin{macrocode}
715 \def\RE@bsl@string{%
716 \ifnum \escapechar<\z@ \@backslashchar \fi
717 \string
718 }
719 % \end{macrocode}
720 % \end{macro}
721 %
722 %
723 %
724 % \subsubsection{Declaration commands}
725 %
726 % \begin{macro}{\DeclareTextVariableCommand}
727 % \begin{macro}{\DeclareTextVariableCommandNoDefault}
728 % \begin{macro}{\DeclareTextVariableSymbol}
729 % Two of these are the obvious counterparts of |\DeclareTextCommand|
730 % and |\Declare|\B|TextSymbol|. The parameters are the same, and the
731 % actual declaring (from the \LaTeXe\ kernel's point of view) is done
732 % by |\DeclareTextCommand|.
733 %
734 % |\DeclareTextVariableCommandNoDefault| is a new possibility that
735 % exists since a relaxed encoding definition file need not actually
736 % specify the definition of any font-dependent command. It can, for
737 % example, specify that ``Unless otherwise stated, use the definition
738 % from encoding \textellipsis{} ''.
739 %
740 % As the ordinary counterparts of these commands are preamble
741 % commands, I have made these preamble commands as well.
742 % \begin{macrocode}
743 \newcommand\DeclareTextVariableCommand{\RE@dec@text@varcmd\newcommand}
744 \@onlypreamble\DeclareTextVariableCommand
745 % \end{macrocode}
746 % \begin{macrocode}
747 \newcommand\DeclareTextVariableCommandNoDefault{%
748 \RE@dec@text@varcmd\@gobble
749 }
750 \@onlypreamble\DeclareTextVariableCommandNoDefault
751 % \end{macrocode}
752 % \begin{macrocode}
753 \newcommand\DeclareTextVariableSymbol[3]{%
754 \RE@dec@text@varcmd\chardef#1{#2}#3\relax
755 }
756 \@onlypreamble\DeclareTextVariableSymbol
757 % \end{macrocode}
758 % \begin{macrocode}
759 \def\RE@dec@text@varcmd#1#2#3{%
760 \DeclareTextCommand{#2}{#3}{\RE@text@variable#2}%
761 \expandafter#1\csname#3/?/?/?\string#2\endcsname
762 }
763 % \end{macrocode}
764 % \end{macro}
765 % \end{macro}
766 % \end{macro}
767 %
768 % \begin{macro}{\ProvideTextVariableCommand}
769 % This is the variable counterpart of |\ProvideTextCommand|, and it
770 % has the same set of parameters. Its definition is a bit more
771 % complicated than that of the earlier commands for declaring variable
772 % font-dependent commands, partly because |\ProvideTextCommand| does
773 % not tell whether the definition it provided was used, but also
774 % becuase this command need not be meaningless even if the
775 % font-dependent command it should declare already was declared.
776 %
777 % If the font-dependent command is not declared (the
778 % |\|\meta{encoding}|\|\meta{command} control sequence is |\relax|),
779 % |\ProvideTextCommand| is used to declare it and |\providecommand|
780 % is used to give an encoding level definition. If the font-dependent
781 % command was declared and variable, then |\providecommand| is still
782 % called, to give an encoding-level definition of the command in
783 % case there wasn't already one. Otherwise
784 % it must have been declared as a non-variable font-dependent command
785 % and the following info message is given:
786 % \ShowPackageInfo{relenc}{You have provided a declaration of
787 % \protect\foo\space in\MessageBreak encoding T1R as a
788 % variable command, but it was\MessageBreak already declared
789 % as a non-variable command.\MessageBreak Your declaration
790 % has been ignored}
791 % In this case, the slight problem of the left-over definition
792 % remains. This is taken care of by giving it to |\providecommand| as
793 % a definition of |\RE@garbage| (which was introduced for this kind
794 % of tasks).
795 %
796 % |\ProvideTextCommand| is not a preamble-only command, so I have
797 % left |\ProvideTextVariableCommand| free to use anywhere too, although
798 % I cannot see why it should be needed after |\begin|\,|{document}|.
799 % \begin{macrocode}
800 \newcommand\ProvideTextVariableCommand[2]{%
801 \expandafter\ifx \csname#2\string#1\endcsname \relax
802 \ProvideTextCommand#1#2{\RE@text@variable#1}%
803 \expandafter\providecommand
804 \csname#2/?/?/?\string#1\expandafter\endcsname
805 \else
806 \long\def\RE@garbage{\RE@text@variable#1}%
807 \expandafter\ifx \csname#2\string#1\endcsname \RE@garbage
808 \expandafter\providecommand
809 \csname#2/?/?/?\string#1\expandafter\expandafter
810 \expandafter\endcsname
811 \else
812 \PackageInfo{relenc}{You have provided a declaration of
813 \protect#1 in\MessageBreak encoding #2 as a variable
814 command, but it was\MessageBreak already declared as a
815 non-variable command.\MessageBreak Your declaration has
816 been ignored}%
817 \expandafter\providecommand
818 \csname RE@garbage\expandafter\expandafter
819 \expandafter\endcsname
820 \fi
821 \fi
822 }
823 % \end{macrocode}
824 % \end{macro}
825 %
826 % \iffalse
827 % A command that was later scrapped, as it turned out it wasn't needed:
828 % % \newcommand{\DeclareTextComposableVariable}[3]{%
829 % % \DeclareTextCommand{#1}{#2}[1]{\RE@text@variable#1{##1}}%
830 % % \expandafter\newcommand \csname#2/?/?/?\string#1\endcsname [1]{#3}%
831 % % }
832 % % \@onlypreamble\DeclareTextComposableVariable
833 % \fi
834 %
835 % \begin{macro}{\DeclareTextVariableAccent}
836 % This is the variable counterpart of |\DeclareTextAccent|, and again
837 % this counterpart has the same parameters as its non-variable model.
838 % Also, it is a preamble-only command, just as its model.
839 % \begin{macrocode}
840 \newcommand{\DeclareTextVariableAccent}[3]{%
841 \DeclareTextCommand{#1}{#2}{\RE@text@variable#1}%
842 \expandafter\newcommand \csname#2/?/?/?\string#1\endcsname
843 {\add@accent{#3}}%
844 }
845 \@onlypreamble\DeclareTextVariableAccent
846 % \end{macrocode}
847 % \end{macro}
848 %
849 %
850 % \subsubsection{Definition commands}
851 %
852 % There is an important difference between the declaration commands and
853 % the definition commands, and this has to do with when they are
854 % executed. A definition command usually appears in a \texttt{.fd}
855 % file, which is read in inside a group (usually several, but that is
856 % irrelevant), but the definitions it makes should be in force after the
857 % group has ended. Therefore the definitions must be global, but the
858 % |\newcommand| family of \LaTeX\ definition commands only make local
859 % definitions. Because of this, I have chosen to primarily use the
860 % \TeX\ primitive |\gdef| and its relatives in the definition commands,
861 % although in several cases \LaTeX-style alternatives are available as
862 % well.
863 %
864 % \begin{macro}{\DefineTextCommandVariant}
865 % The basic defintion command, |\gdef| style. As simple as it can
866 % be, but note that the \meta{parameter text} does not become one of
867 % the arguments of the macro. This has some consequences for when
868 % spaces are ignored.
869 % \begin{macrocode}
870 \newcommand{\DefineTextCommandVariant}[5]{%
871 \expandafter\gdef
872 \csname\RE@font@spec{#2}{#3}{#4}{#5}\RE@bsl@string#1\endcsname
873 }
874 % \end{macrocode}
875 % \end{macro}
876 %
877 % \begin{macro}{\DefineTextSymbolVariant}
878 % The basic command for defining a text symbol command.
879 % \begin{macrocode}
880 \newcommand{\DefineTextSymbolVariant}[6]{%
881 \global\expandafter\chardef
882 \csname\RE@font@spec{#2}{#3}{#4}{#5}\RE@bsl@string#1\endcsname
883 =#6\relax
884 }
885 % \end{macrocode}
886 % \end{macro}
887 %
888 % \begin{macro}{\DefineTextAccentVariant}
889 % The basic command for defining an accent command. Very much a
890 % special case of |\DefineTextCommandVariant|.
891 % \begin{macrocode}
892 \newcommand{\DefineTextAccentVariant}[6]{%
893 \expandafter\gdef
894 \csname\RE@font@spec{#2}{#3}{#4}{#5}\RE@bsl@string#1\endcsname
895 {\add@accent{#6}}%
896 }
897 % \end{macrocode}
898 % \end{macro}
899 %
900 % \begin{macro}{\NewTextCommandVariant}
901 % \begin{macro}{\RenewTextCommandVariant}
902 % \begin{macro}{\ProvideTextCommandVariant}
903 % \begin{macro}{\RE@make@text@cmd@variant}
904 % \begin{macro}{\RE@make@text@cmd@var@x}
905 % These commands are the \LaTeX-style commands to define variable
906 % font-dependent commands. As the \LaTeX\ commands they are built on is
907 % not really meant to be used for global definitions, this involves
908 % some hacking (using the \LaTeX\ core's private control sequences to
909 % do things they are not meant to do, for example). Everything would
910 % have been much simpler if the autoload format hook |\aut@global| had
911 % been available in all \LaTeX\ formats, but it is not. The purpose of
912 % |\RE@make@text@cmd@variant| is to save some |\csname| \ldots\
913 % |\endcsname| pairs, the real defining is done by
914 % |\RE@make@text@cmd@var@x|.
915 % \begin{macrocode}
916 \CheckCommand*{\newcommand}{\@star@or@long\new@command}
917 \newcommand{\NewTextCommandVariant}
918 {\RE@make@text@cmd@variant\new@command}
919 % \end{macrocode}
920 % \begin{macrocode}
921 \CheckCommand*{\renewcommand}{\@star@or@long\renew@command}
922 \newcommand{\RenewTextCommandVariant}
923 {\RE@make@text@cmd@variant\renew@command}
924 % \end{macrocode}
925 % \begin{macrocode}
926 \CheckCommand*{\providecommand}{\@star@or@long\provide@command}
927 \newcommand{\ProvideTextCommandVariant}
928 {\RE@make@text@cmd@variant\provide@command}
929 % \end{macrocode}
930 % \begin{macrocode}
931 \def\RE@make@text@cmd@variant#1#2#3#4#5#6{%
932 \expandafter\RE@make@text@cmd@var@x
933 \csname\RE@font@spec{#3}{#4}{#5}{#6}\RE@bsl@string#2\endcsname
934 {#1}%
935 }
936 % \end{macrocode}
937 % Instead of |\aut@global|, |\l@ngrel@x| is used as a hook. |\l@ngrel@x|
938 % is defined to be a macro whose last action is to execute |\global|. As
939 % |\l@ngrel@x| appears just before the central |\def|, this makes that
940 % definition global in exactly those cases where the definition is made.
941 % This requires that the topmost layer of |\newcommand| (and its cousins),
942 % the one in which the |*|-processing takes place, is stepped over.
943 % Otherwise the definition of |\l@ngrel@x| would be reset.
944 %
945 % If the command has an optional argument, however, a simple
946 %\begin{verbatim}
947 % \def\l@ngrel@x{\global}
948 %\end{verbatim}
949 % is not sufficient. In that case the command the user issues is only a
950 % preparation that inserts the default optional argument if none is
951 % present and issues the real command (the name of the real command is
952 % the name of the user command with an extra backslash prepended to it).
953 %
954 % The real command will be globally defined, thanks to the |\global|
955 % at the end of |\l@ngrel@x|, but the preparation command is at the time
956 % of |\l@ngrel@x| only locally defined. This is why |\l@ngrel@x| |\let|s
957 % the preparation command to itself globally, this preserves the
958 % definition but makes it global. If the command does not have an optional
959 % argument, this does no harm as the incorrect definition is overwritten
960 % with the correct just after |\l@ngrel@x|.
961 %
962 % Finally, |\l@ngrel@x| resets itself to |\relax|, in case something
963 % expects it to be |\long| or |\relax|. As |\l@ngrel@x| is not reset
964 % if no command definition takes place, there is a slight chance of
965 % error in that case, but at least all \LaTeX\ core user commands reset
966 % it before using so the hack should not have any side-effects.
967 % \begin{macrocode}
968 \def\RE@make@text@cmd@var@x#1#2{%
969 \def\l@ngrel@x{%
970 \global\let#1#1%
971 \let\l@ngrel@x\relax
972 \global
973 }%
974 #2#1%
975 }
976 % \end{macrocode}
977 % To examine sometime: Can |\globaldefs=1| be used instead here? As
978 % that makes all assignments global, there is a definite chance it
979 % might break something else.
980 % \end{macro}\end{macro}\end{macro}\end{macro}\end{macro}
981 %
982 % \iffalse
983 % An auxillary command that has been scrapped.
984 % % \begin{macro}{\RE@globalize@if@defined}
985 % % This command globally |\let|s its argument to itself, if it is
986 % % defined. This makes the definition of the argument global,
987 % % regardless of whether the definition was local or global earlier.
988 % % \begin{macrocode}
989 % \def\RE@globalize@if@defined#1{%
990 % \ifx#1\relax\else
991 % \global\let#1#1%
992 % \fi
993 % }
994 % % \end{macrocode}
995 % % \end{macro}
996 % \fi
997 %
998 %
999 % \subsection{Making compositions of font-dependent commands}
1000
1001 % \begin{macro}{\RE@if@composed}
1002 % This is a general test to see if a macro is a command that is set
1003 % up for having compositions, i.e., if the expansion of the macro
1004 % begins with |\@text@composite|. This is the same test as is used in
1005 % |\DeclareTextCompositeCommand|.
1006 %
1007 % The syntax is as follows:
1008 % \begin{quote}
1009 % |\RE@if@composed|\,\meta{command}\,\marg{then-text}\,^^A
1010 % \marg{else-text}
1011 % \end{quote}
1012 % expands to \meta{then-text} if \meta{command} can have
1013 % compositions and to \meta{else-text} otherwise.
1014 % \begin{macrocode}
1015 \def\RE@if@composed#1{%
1016 \expandafter\expandafter \expandafter\ifx
1017 \expandafter\@car #1\relax\relax\@nil \@text@composite
1018 % \end{macrocode}
1019 % If it is composite then \textellipsis
1020 % \begin{macrocode}
1021 \expandafter\@firstoftwo
1022 \else
1023 \expandafter\@secondoftwo
1024 \fi
1025 }
1026 % \end{macrocode}
1027 % \end{macro}
1028 %
1029 %
1030 % \subsubsection{Commands for compositions that are variable}
1031 %
1032 % The \LaTeXe\ kernel's method of forming the names of compositions is
1033 % to |\string| the name of the base command and append |-|\meta{argument}
1034 % to that, all of which is then |\csname|d. This generates names like
1035 % \begin{quote}
1036 % |\\T1\foo-a|
1037 % \end{quote}
1038 % for the command |\foo|'s composition with the argument |a| in the |T1|
1039 % encoding. As the \LaTeXe\ kernel's mechanism for checking for
1040 % compositions is used for compositions that have variable definitions
1041 % as well, the names of these commands are formed using the same
1042 % procedure.
1043 %
1044 % Should then the names of the variants of the composition be generated
1045 % from names as the above, then these names would be things like
1046 % \begin{quote}
1047 % |\T1R/zcm/m/n\\T1R\foo-a|
1048 % \end{quote}
1049 % which is a bit longish, even for my taste. Therefore the names of the
1050 % variants are formed from a base consisting only of the name of the
1051 % font-dependent command and its argument, which is |\\foo-a| in the above
1052 % example. This reduces the above to
1053 % \begin{quote}
1054 % |\T1R/zcm/m/n\\foo-a|
1055 % \end{quote}
1056 % saving two to four characters. This difference in naming does however
1057 % have some consequences for the usage of definitions from a non-relaxed
1058 % encoding.
1059 %
1060 %
1061 % If, for example, |{T1}| is included in the current search path and a
1062 % definition of the composition |\foo|\,|{a}| is looked for, a possible
1063 % definition of this in the |T1| encoding will not be found! This is
1064 % because the name tried is |\T1\\foo-a|, but the command is called
1065 % |\\T1\foo-a|. This is the reason for the macro |\RE@convert@nfss|,
1066 % which looks ahead to see if a composition or a plain command is
1067 % currently looked for. Had instead |{\RE@convert@nfss|\,|{T1}}| been
1068 % included, |\T1\\foo-a| would have been changed to |\\T1\foo-a|.
1069 %
1070 % \begin{macro}{\DeclareVariableTextComposition}
1071 % \begin{macro}{\RE@dec@var@text@comp}
1072 % This is the variable analog of \LaTeX's |\DeclareTextCompositeCommand|,
1073 % although it is somewhat less as it does not make a default
1074 % definition for the composition. Thus it is also an analog of
1075 % |\DeclareTextVariableCommandNoDefault| for compositions.
1076 % \begin{macrocode}
1077 \newcommand{\DeclareVariableTextComposition}[3]{%
1078 \expandafter\RE@dec@var@text@comp
1079 \csname\string#1-#3\expandafter\endcsname
1080 \csname\@backslashchar#2\string#1-#3\endcsname
1081 {#1}{#2}{#3}%
1082 }
1083 % \end{macrocode}
1084 % As |\DeclareVariableTextComposition| merely make a few combinations of
1085 % its arguments and then call |\RE@dec@var@text@comp|, the arguments of
1086 % the latter are worth an explanation. Continuing the above example of
1087 % |\foo|\,|{a}| in the |T1R| encoding, the arguments will be
1088 % \begin{quote}
1089 % \begin{tabular}{r@{ is }l r@{ is }l r@{ is }l}
1090 % |#1|&|\\foo-a|& |#2|&|\\T1R\foo-a| &\omit\span\omit\\
1091 % |#3|&|\foo|& |#4|&|T1R|& |#5|&|a|
1092 % \end{tabular}
1093 % \end{quote}
1094 %
1095 % Should the composition already have been declared, but the
1096 % definition is not variable, that definition is made the encoding
1097 % level definition and the composition is made variable. If the
1098 % definition is variable, an info message is given and the
1099 % definition is not changed.
1100 % \begin{macrocode}
1101 \def\RE@dec@var@text@comp#1#2#3#4#5{%
1102 \ifx#2\relax
1103 % \end{macrocode}
1104 % If this composition has not been declared then \textellipsis
1105 % \begin{macrocode}
1106 \DeclareTextCompositeCommand{#3}{#4}{#5}%
1107 {\RE@text@comp@variable#1}%
1108 \else
1109 \expandafter\expandafter \expandafter\ifx
1110 \expandafter\@car#2\@nil
1111 \RE@text@variable
1112 % \end{macrocode}
1113 % If this composition is variable then \textellipsis
1114 % \begin{macrocode}
1115 \PackageInfo{relenc}{Redundant \protect
1116 \DeclareVariableTextComposition.\MessageBreak
1117 The composition of \protect#3 with #5 is\MessageBreak
1118 already declared as a variable command\MessageBreak
1119 in encoding #4%
1120 }%
1121 \else
1122 \expandafter\let \csname#4/?/?/?\string#1\endcsname #2
1123 \def#2{\RE@text@comp@variable#1}%
1124 \fi
1125 \fi
1126 }
1127 % \end{macrocode}
1128 % Example message:
1129 % \ShowPackageInfo{relenc}{Redundant \protect
1130 % \DeclareVariableTextComposition.\MessageBreak
1131 % The composition of \protect\foo\space with a is\MessageBreak
1132 % already declared as a variable command\MessageBreak
1133 % in encoding T1R}
1134 % \end{macro}\end{macro}
1135 %
1136 %
1137 % \begin{macro}{\DefineTextCompositionVariant}
1138 % \begin{macro}{\DefineTextCompositionVariantCommand}
1139 % \begin{macro}{\RE@def@text@comp@var}
1140 % These are the commands that actually define variants of compositions.
1141 % The first makes the variant a chardef token, the second
1142 % makes it a parameterless macro.
1143 %
1144 % The arguments for |\RE@def@text@comp@var| should be the following
1145 % things: The command that does the defining (|\chardef| or |\gdef|),
1146 % the base user command, the relevant encoding, family, series, and
1147 % shape, and finally the argument for the composition. Note that the
1148 % actual definition (slot number or replacement text, respectively)
1149 % is not among the arguments of |\RE@def@text@comp@var|.
1150 % \begin{macrocode}
1151 \newcommand\DefineTextCompositionVariant[7]{%
1152 \global \RE@def@text@comp@var\chardef{#1}{#2}{#3}{#4}{#5}{#6}%
1153 #7\relax
1154 }
1155 % \end{macrocode}
1156 % \begin{macrocode}
1157 \newcommand\DefineTextCompositionVariantCommand{%
1158 \RE@def@text@comp@var\gdef
1159 }
1160 % \end{macrocode}
1161 % \begin{macrocode}
1162 \def\RE@def@text@comp@var#1#2#3#4#5#6#7{%
1163 \expandafter#1%
1164 \csname
1165 \RE@font@spec{#3}{#4}{#5}{#6}\@backslashchar
1166 \RE@bsl@string#1-#6%
1167 \endcsname
1168 }
1169 % \end{macrocode}
1170 % \end{macro}\end{macro}\end{macro}
1171 %
1172 % \begin{macro}{\DefineTextUncomposedVariant}
1173 % \begin{macro}{\RE@def@text@uncmp}
1174 % \begin{macro}{\RE@def@text@uncmp@x}
1175 % |\DefineTextUncomposedVariant| extracts the definition used for
1176 % arguments that does not have definitions, inserts the given
1177 % argument, and makes the resulting token sequence the definition of
1178 % the variant at hand. Doing this requires that the definition of
1179 % the command that the \LaTeXe\ kernel sees is taken apart, so it
1180 % might be worth describing how it is contructed.
1181 %
1182 % If |\foo| is composite in the |T1| encoding, |\T1\foo| is a macro
1183 % which expands to
1184 % \begin{quote}
1185 % |\@text@composite|\,|\T1\foo|\,|#1|\,|\@empty|\,^^A
1186 % |\@text@composite|\\
1187 % |{|\,\meta{noncomposite definition}\,|}|
1188 % \end{quote}
1189 % where \meta{noncomposite definition} is what is needed here. The
1190 % stuff before checks if the composition is defined, but in this case
1191 % things are best if that part is never expanded further that this.
1192 %
1193 % The actual ``work'' is done by |\RE@def@text@uncmp@x|, as this macro
1194 % contains the |\gdef| which is the only command in this that \TeX's
1195 % stomach sees; everything else just expands in one way or another
1196 % (unless the warning is issued, that of course contains some stomach
1197 % stuff too). |\DefineTextUncomposedVariant| makes two |\csname|s: The
1198 % name of the macro from which the definition is to be extracted and
1199 % the name of the macro to define.
1200 %
1201 % |\RE@def@text@uncmp| checks if the macro to extract from really is
1202 % composed, and if it is then it expands it \emph{one level}, feeding
1203 % it the \meta{argument} as argument. Then |\RE@def@text@uncmp@x| is
1204 % given this one level expansion, and the |\@text@composite|s and
1205 % everything between them is thrown away. The
1206 % \meta{noncomposite definition} is made the replacement text of a
1207 % |\gdef| defining the macro to be defined. If the macro to extract a
1208 % definition from is not composed however, a warning is given.
1209 %
1210 % As this command refers to a specific encoding's definition of a
1211 % command, the \meta{encoding} argument mustn't be empty.
1212 % \begin{macrocode}
1213 \newcommand\DefineTextUncomposedVariant[6]{%
1214 \expandafter\RE@def@text@uncmp
1215 \csname#2\RE@bsl@string#1\expandafter\endcsname
1216 \csname#2/\RE@empty@is@qmark{#3}/\RE@empty@is@qmark{#4}/%
1217 \RE@empty@is@qmark{#5}\@backslashchar\RE@bsl@string#1-#6%
1218 \endcsname
1219 {#6}{#1}{#2}%
1220 }
1221 % \end{macrocode}
1222 % \begin{macrocode}
1223 \def\RE@def@text@uncmp#1#2#3#4#5{%
1224 \RE@if@composed#1{%
1225 \expandafter\RE@def@text@uncmp@x #1{#3}{#2}%
1226 }{%
1227 \PackageWarning{relenc}{There are no compositions for %
1228 \protect#4 in\MessageBreak the #5 encoding. %
1229 \protect\DefineTextUncomposedVariant\MessageBreak
1230 makes no sense here%
1231 }%
1232 }%
1233 }
1234 % \end{macrocode}
1235 % \begin{macrocode}
1236 \def\RE@def@text@uncmp@x\@text@composite#1\@text@composite#2#3{%
1237 \gdef#3{#2}%
1238 }
1239 % \end{macrocode}
1240 % Example warning:
1241 % \ShowPackageWarning{relenc}{There are no compositions for ^^A
1242 % \string\foo\space in\MessageBreak the T1 encoding. ^^A
1243 % \string\DefineTextUncomposedVariant\MessageBreak
1244 % makes no sense here}
1245 % \end{macro}\end{macro}\end{macro}
1246 %
1247 %
1248 % \subsubsection{Commands for variants with compositions}
1249 %
1250 % The \package{relenc} package offers another way in which a command can
1251 % be defined relative to both argument and font, and that is to allow
1252 % variants of font-dependent commands to have compositions. It is pretty
1253 % similar to the usual making of composite commands in \LaTeX.
1254 %
1255 % \begin{macro}{\DefineTextVariantComposition}
1256 % \begin{macro}{\DefineTextVariantCompositionCommand}
1257 % These commands define the composition and make the variant a
1258 % command with compositions, if it is not already. The mechanism used
1259 % for compositions uses |\@text@composite|, exactly like the
1260 % compositions made by commands in the \LaTeXe\ kernel.
1261 %
1262 % |\DefineTextVariantComposition| makes the final definition a
1263 % chardef token. |\DefineTextVariantCompositionCommand| makes the
1264 % final definition a macro without parameters.
1265 %
1266 % An interesting point about these commands is that a variant need not
1267 % be defined before a composition of it is made! If this happens then
1268 % of course technicaly the variant gets defined, but its definition
1269 % for the case when that composition is not found is simply to set things
1270 % up for a continued scan of the search path. What makes this possible
1271 % is that the remaining search path is stored in |\RE@temptoks|.
1272 %
1273 % \begin{macrocode}
1274 \newcommand\DefineTextVariantComposition[7]{%
1275 \RE@def@text@var@comp\chardef{#1}{#2}{#3}{#4}{#5}{#6}#7\relax
1276 }
1277 % \end{macrocode}
1278 % \begin{macrocode}
1279 \newcommand\DefineTextVariantCompositionCommand{%
1280 \RE@def@text@var@comp\gdef
1281 }
1282 % \end{macrocode}
1283 %
1284 % \begin{macro}{\RE@def@text@var@comp}
1285 % \begin{macro}{\RE@make@text@comp}
1286 % These are the macros that do the actual work. The parameters of
1287 % |\RE@def@text|\B|@var@comp| are the user level command, the
1288 % encoding, family, series, and shape in question, the argument for
1289 % the composition, the assignment command
1290 % that should define the composition, and finally
1291 % the text that should be put after the control sequnce of the
1292 % composition to complete the assignment. When the assignment command
1293 % is |\chardef|, as is the case when |\DefineTextVariantComposition|
1294 % makes the call, this is simply a \meta{number}---the slot. The extra
1295 % |\relax| is to stop \TeX\ from reading ahead too
1296 % far when looking for the end of the \meta{number}.
1297 %
1298 % The first thing |\RE@def@text@var@comp| does is to check if the
1299 % variant the user wants do define a composition of is defined.
1300 % \begin{macrocode}
1301 \def\RE@def@text@var@comp#1#2#3#4#5#6#7{%
1302 \expandafter\let \expandafter\RE@garbage
1303 \csname\RE@font@spec{#3}{#4}{#5}{#6}\RE@bsl@string#2\endcsname
1304 \ifx \RE@garbage\relax
1305 % \end{macrocode}
1306 % This means the variant has not been defined. The default definition
1307 % given sets up a continued scan along the search path. The key macro
1308 % here is |\RE@again@read@spath| (the definition of which is found on
1309 % page \pageref{RE@again@read@spath}). It temporarily disables the
1310 % define first mechanism and then it expands to
1311 % \begin{quote}
1312 % |\expandafter|\,|\RE@read@spath|\,|\the|\,|\RE@temptoks|\,^^A
1313 % |\RE@read@spath|
1314 % \end{quote}
1315 % As the |##1| below has become |#1| when |\RE@make@text@comp| is
1316 % expanded, this will act as a normal |#1| in the definition
1317 % |\RE@make@text@comp| expands to.
1318 % \begin{macrocode}
1319 \expandafter\RE@make@text@comp\csname
1320 \RE@font@spec{#3}{#4}{#5}{#6}\RE@bsl@string#2%
1321 \endcsname {\RE@again@read@spath#2{##1}}%
1322 % \end{macrocode}
1323 % Otherwise it must be checked if the variant is composed. If it is,
1324 % then everything is fine, if it isn't, then the current definition
1325 % is made the default definition.
1326 % \begin{macrocode}
1327 \else
1328 \RE@if@composed\RE@garbage{}{%
1329 \expandafter\RE@make@text@comp
1330 \csname
1331 \RE@font@spec{#3}{#4}{#5}{#6}\RE@bsl@string#2%
1332 \expandafter\endcsname
1333 \expandafter{\RE@garbage{##1}}%
1334 }%
1335 \fi
1336 % \end{macrocode}
1337 % Then it is finally time to define the composition. This is pretty
1338 % straight off.
1339 % \begin{macrocode}
1340 \global\expandafter#1\csname
1341 \@backslashchar\RE@font@spec{#3}{#4}{#5}{#6}\RE@bsl@string#2-#7%
1342 \endcsname
1343 }
1344 % \end{macrocode}
1345 % |\RE@make@text@comp| makes |#1| a composed command, with |#2| as
1346 % the default definition. This is exactly what the corresponding
1347 % command in standard \LaTeX\ does, but for some reason \LaTeX\ ^^A
1348 % defines this command of the fly each time it is needed.
1349 % \begin{macrocode}
1350 \def\RE@make@text@comp#1#2{%
1351 \gdef#1##1{\@text@composite#1##1\@empty\@text@composite{#2}}%
1352 }
1353 % \end{macrocode}
1354 % \end{macro}\end{macro}\end{macro}\end{macro}
1355 %
1356 %
1357 % \subsection{Miscellanenous commands}
1358 %
1359 % \subsubsection{Search paths}
1360 %
1361 % A very important thing about search paths is that they are
1362 % responsible for ending a search that has found nothing, as the macros
1363 % which actually perform the search contain no mechanism for this. The
1364 % easiest way to ensure this is to append the token |\RE@var@not@found|
1365 % to every search path set, and this is exactly what the standard
1366 % commands for setting search paths do. Anyone who does not use these
1367 % commands for setting a search path must be aware that if a search
1368 % path does not contain any block that ends the search then some tiny errors
1369 % are likely to start infinite loops.
1370 %
1371 % \begin{macro}{\SetEncodingSearchPath}
1372 % \begin{macro}{\SetFamilySearchPath}
1373 % \begin{macro}{\RE@set@spath}
1374 % \begin{macro}{\RE@spath@catcodes}
1375 % These are all fairly standard. |\RE@set@spath| does the actual
1376 % setting of a search path while |\SetEncodingSearchPath| and
1377 % |\SetFamilySearchPath| merely form the name of the macro that will
1378 % store the search path and temporarily change some |\catcode|s to make
1379 % typing the search path somewhat easier. The |\catcode|s are changed
1380 % by |\RE@spath@catcodes|.
1381 %
1382 % \begin{macrocode}
1383 \newcommand{\SetEncodingSearchPath}[1]{%
1384 \begingroup
1385 \RE@spath@catcodes
1386 \expandafter\RE@set@spath \csname#1-path\endcsname
1387 }
1388 % \end{macrocode}
1389 % \begin{macrocode}
1390 \newcommand{\SetFamilySearchPath}[2]{%
1391 \begingroup
1392 \RE@spath@catcodes
1393 \expandafter\RE@set@spath \csname#1/#2-path\endcsname
1394 }
1395 % \end{macrocode}
1396 % \begin{macrocode}
1397 \def\RE@set@spath#1#2{%
1398 \gdef#1{#2\RE@var@not@found}%
1399 \endgroup
1400 }
1401 % \end{macrocode}
1402 % \begin{macrocode}
1403 \def\RE@spath@catcodes{%
1404 \catcode`\ =9\relax
1405 \catcode`\^^I=9\relax
1406 \catcode`\^^M=9\relax
1407 \catcode`\@=11\relax
1408 \catcode`\/=12\relax
1409 \catcode`\?=12\relax
1410 }
1411 % \end{macrocode}
1412 % \end{macro}\end{macro}\end{macro}\end{macro}
1413 %
1414 % \begin{macro}{\RE@convert@nfss}
1415 % For some relaxed encodings, one wants the definition of a
1416 % font-dependent command to be identical to the definition of the command
1417 % in a non-relaxed encoding (this is the case with \texttt{T1R}, which
1418 % is designed to be a relaxed version of \texttt{T1}). As there are
1419 % slight differences in how the names of compositions are generated
1420 % between the \LaTeXe\ kernel and \package{relenc}, it would not be
1421 % sufficient to simply include |{T1}| in the search path of the
1422 % \texttt{T1R} encoding to make it use \texttt{T1}'s definitions of
1423 % compositions as variants of that composition. The purpose of
1424 % |\RE@convert@nfss| is to overcome this by changing the names of the
1425 % variants of compositions where required. Including
1426 % |\RE@convert@nfss|\,|{T1}| in the search path of \texttt{T1R} gives
1427 % the intended effect.
1428 % \begin{macrocode}
1429 \def\RE@convert@nfss#1#2{%
1430 \ifx\@empty#2%
1431 \@backslashchar#1\expandafter\expandafter \expandafter\@gobble
1432 \else
1433 #1\expandafter#2%
1434 \fi
1435 }
1436 % \end{macrocode}
1437 % \end{macro}
1438 %
1439 %
1440 % \subsubsection{The define first mechanism}
1441 %
1442 % \begin{macro}{\ActivateDefineFirst}
1443 % \begin{macro}{\DeactivateDefineFirst}
1444 % These commands can be used to turn the define first mechanism on and
1445 % off. I am not sure at the moment whether implementing it was a good
1446 % idea, but as it exists it might as well stay so it can be evaluated.
1447 %
1448 % It could be worth pointing out that these commands act locally. The
1449 % define first mechanism, on the other hand, acts globally.
1450 % \begin{macrocode}
1451 \newcommand\ActivateDefineFirst{%
1452 \let\RE@define@first\RE@active@define@first
1453 }
1454 \newcommand\DeactivateDefineFirst{%
1455 \let\RE@define@first\@gobbletwo
1456 }
1457 % \end{macrocode}
1458 % \end{macro}\end{macro}
1459 %
1460 % \subsection{Debugging}
1461 %
1462 % \begin{macro}{\ShowVariantSearchResult}
1463 % This command offers a way to peek into the search mechanism, and in
1464 % particular to see where it stopped. This command has a potential to
1465 % come in real handy, but note that it is the \emph{remaining search
1466 % path} that is shown. You do not see the block that was actually
1467 % used, you see all blocks that come after it.
1468 % \begin{macrocode}
1469 \newcommand{\ShowVariantSearchResult}{%
1470 \immediate\write\sixt@@n{Encoding: \cf@encoding}%
1471 \immediate\write\sixt@@n{Family: \f@family}%
1472 \immediate\write\sixt@@n{Series: \f@series}%
1473 \immediate\write\sixt@@n{Shape: \f@shape}%
1474 \immediate\write\sixt@@n
1475 {Remaining search path:\MessageBreak\the\RE@temptoks}%
1476 \show\RE@first@search@item
1477 }
1478 % \end{macrocode}
1479 % \end{macro}
1480 %
1481 %
1482 % \subsection{Fix for a bug in \LaTeX}
1483 %
1484 % The definition of the control sequence |\@text@composite@x| in
1485 % \LaTeX{}es released 1998 and earlier has a bug (number 2930 in the
1486 % \LaTeX\ bugs database). The definition in question is
1487 %\begin{verbatim}
1488 % \def\@text@composite@x#1#2{%
1489 % \ifx#1\relax
1490 % \expandafter#2%
1491 % \else
1492 % #1%
1493 % \fi}
1494 %\end{verbatim}
1495 % The problem with this definition is the |\expandafter|. According to
1496 % \cite{ltoutenc}, it was ``added so that less chaos ensues from the
1497 % misuse of this code with commands that take several arguments'', but
1498 % unfortunately, it was placed in a position where it can do no good.
1499 % |#2| is in all reasonable cases a sequence of more than one token,
1500 % hence the |\expandafter| will not expand the following |\else|, but
1501 % some token in |#2| instead! I suspect that the |\expandafter| was
1502 % really meant to be placed in front of the |#1|, which actually is just
1503 % a single token.
1504 %
1505 % As it happens, the above bug can cause some serious problems when the
1506 % non-composite definition of a composite command happens to be
1507 % variable, since the above |\expandafter| will then expand a control
1508 % sequence which should \emph{not} be expanded.
1509 %
1510 % \begin{macro}{\@text@composite@x}
1511 % The following code fixes the above bug if the \LaTeX\ used is
1512 % one with that bug. This is done as a curtesy to all those \LaTeX\
1513 % users which (like myself) are not always updating \LaTeX\ as soon
1514 % as a new release appears. The definition of |\@text@composite@x| is
1515 % checked and, if it matches the above, replaced with the fixed
1516 % definition.
1517 % \begin{macrocode}
1518 \def\RE@garbage#1#2{%
1519 \ifx#1\relax
1520 \expandafter#2%
1521 \else
1522 #1%
1523 \fi}
1524 \ifx \@text@composite@x\RE@garbage
1525 \def\@text@composite@x#1{%
1526 \ifx #1\relax
1527 \expandafter\@secondoftwo
1528 \else
1529 \expandafter\@firstoftwo
1530 \fi
1531 #1%
1532 }
1533 \fi
1534 \let\RE@garbage\relax
1535 %</package>
1536 % \end{macrocode}
1537 % \end{macro}
1538 %
1539 \endinput
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549