Debian Codegraph @

texmf-dist/source/latex/dialogl/grabhedr.dtx

raw
1 %%% ====================================================================
2 %%% @LaTeX-style-file{
3 %%% filename = "grabhedr.dtx",
4 %%% version = "1.99a",
5 %%% date = "2013/01/24",
6 %%% author = "Michael Downes",
7 %%% copyright = "This file is part of the dialogl package, released
8 %%% under the LPPL; see dialogl.ins for details."
9 %%% keywords = "TeX, file header,
10 %%% supported = "no",
11 %%% abstract = "This file defines a macro \inputfwh
12 %%% to be used instead of \input, to allow TeX to grab
13 %%% information from standardized file headers in the form
14 %%% proposed by Nelson Beebe during his term as president of the
15 %%% TeX Users Group. Of which all this here is an example.",
16 %%% }
17 %%% ====================================================================
18 %
19 % \iffalse
20 %<*driver>
21 \input{dia-driv.tex}
22 %</driver>
23 % \fi
24 %
25 % \section{Introduction}
26 % This file defines a function \cw{inputfwh} to be used instead of
27 % \cw{input}, to allow \tex/ to grab information from standardized
28 % file headers in the form proposed by Nelson Beebe during his term
29 % as president of the \tex/ Users Group. Usage:
30 %\begin{usage}
31 %\inputfwh{file.nam}
32 %\end{usage}
33 % Functions \cw{localcatcodes} and \cw{restorecatcodes} for
34 % managing catcode changes are also defined herein, as well as a
35 % handful of utility functions, many of them borrowed from
36 % \fn{latex.tex}: \cw{@empty}, \cw{@gobble}, \cw{@gobbletwo},
37 % \cw{@car}, \cw{@@input}, \cw{toks@}, \cw{afterfi},
38 % \cw{fileversiondate}, \cw{trap.input}.
39 %
40 % The use of \cw{inputfwh}, \cw{fileversiondate}, and
41 % \cw{trap.input} as illustrated in \fn{dialog.sty} is cumbersome
42 % klugery that in fact would better be handled by appropriate
43 % functionality built into the format file. But none of the major
44 % formats have anything along these lines yet. (It would also help
45 % if \tex/ made the current input file name accessible, like
46 % \cw{inputlineno}.)
47 %
48 % \StopEventually{}
49 %
50 % \section{Implementation}
51 % Standard package identification:
52 % \begin{macrocode}
53 %<*2e>
54 \NeedsTeXFormat{LaTeX2e}
55 \ProvidesPackage{grabhedr}[1994/11/08 v0.9j]
56 %</2e>
57 % \end{macrocode}
58 %
59 % By enclosing this entire file in a group, saving and restoring
60 % catcodes `by hand' is rendered unnecessary. This is perhaps the
61 % best way to locally change catcodes, better than the
62 % \cw{localcatcodes} function defined below. But it tends to be
63 % inconvenient for the \tex/ programmer: every time you add
64 % something you have to remember to make it global; if you're like
65 % me, you end up making every change twice, with an abortive test
66 % run of \tex/ in between, in which you discover that a certain
67 % control sequence is undefined because you didn't assign it
68 % globally. (Using \cw{globaldefs} = 1 is dangerous in my experience;
69 % you have to take care not to accidentally change any variables that
70 % you don't want to be changed globally.)
71 % \begin{macrocode}
72 \begingroup
73 % \end{macrocode}
74 % Inside this group, enforce normal catcodes. All definitions must
75 % be global in order to persist beyond the \cw{endgroup}.
76 % \begin{macrocode}
77 \catcode96 12 % left quote
78 \catcode`\= 12
79 \catcode`\{=1 \catcode`\}=2 \catcode`\#=6
80 \catcode`\$=3 \catcode`\~=13 \catcode`\^=7
81 \catcode`\_=8 \catcode`\^^M=5 \catcode`\"=12
82 % \end{macrocode}
83 % Make \qc{\@} a letter for use in `private' control sequences.
84 % \begin{macrocode}
85 \catcode`\@=11
86 % \end{macrocode}
87 %
88 % \section{Preliminaries}
89 % For \cw{@empty}, \cw{@gobble}, \ldots{} we use the \latex/ names so
90 % that if \fn{grabhedr.sty} is used with \latex/ we won't waste hash
91 % table and string pool space.
92 %
93 % \begin{macro}{\@empty}
94 % Empty macro, for \cw{ifx} tests or initialization of variables.
95 % \begin{macrocode}
96 \gdef\@empty{}
97 % \end{macrocode}
98 % \end{macro}
99 %
100 % \begin{macro}{\@gobble}
101 % \begin{macro}{\@gobbletwo}
102 % \begin{macro}{\@gobblethree}
103 % Functions for gobbling unwanted tokens.
104 % \begin{macrocode}
105 \long\gdef\@gobble#1{}
106 \long\gdef\@gobbletwo#1#2{}
107 \long\gdef\@gobblethree#1#2#3{}
108 % \end{macrocode}
109 % \end{macro}
110 % \end{macro}
111 % \end{macro}
112 %
113 % \begin{macro}{\@car}
114 % The function \cw{@car}, though not really needed by
115 % \fn{grabhedr.sty}, is needed by the principal customers of
116 % \fn{grabhedr.sty} (e.g., \fn{dialog.sty}).
117 % \begin{macrocode}
118 \long\gdef\@car#1#2\@nil{#1}
119 % \end{macrocode}
120 % \end{macro}
121 %
122 % \begin{macro}{\@@input}
123 % To define \cw{@@input} as in \latex/ we want to let it equal to
124 % the primitive \cw{input}. But if a \latex/ format is being used
125 % we don't want to execute that assignment because by now
126 % \cw{input} has changed its meaning. And if some other format is
127 % being used it behooves us to check, before defining \cw{@@input},
128 % whether \cw{input} still has its primitive meaning. Otherwise
129 % there's a good chance \cw{inputfwh} will fail to work properly.
130 % \begin{macrocode}
131 \ifx\UndEFiNed\@@input % LaTeX not loaded.
132 % \end{macrocode}
133 % This code shows a fairly easy way to check whether the meaning of a
134 % primitive control sequence is still the original meaning.
135 % \begin{macrocode}
136 \edef\0{\meaning\input}\edef\1{\string\input}%
137 \ifx\0\1%
138 \global\let\@@input\input
139 \else
140 \errhelp{%
141 Grabhedr.sty needs to know the name of the
142 \input primitive in order to define \inputfwh
143 properly. Consult a TeXnician for help.}
144 \errmessage{%
145 Non-primitive \noexpand\input detected}%
146 \fi
147 \fi
148 % \end{macrocode}
149 % \end{macro}
150 %
151 % \begin{macro}{\toks@}
152 % Scratch token register.
153 % \begin{macrocode}
154 \global\toksdef\toks@=0
155 % \end{macrocode}
156 % \end{macro}
157 %
158 % \begin{macro}{\afterfi}
159 % Sonja Maus's function for throwing code over the \cw{fi} (``An
160 % Expansion Power Lemma'', \TUB{} vol 12 no 2 June 1991). (Except
161 % that she called this function \cw{beforefi}.)
162 %
163 % \begin{macrocode}
164 \long\gdef\afterfi#1\fi{\fi#1}
165 % \end{macrocode}
166 % \end{macro}
167 %
168 % \begin{macro}{\nx@}
169 % We will be using \cw{noexpand} a lot; this abbreviation improves
170 % the readability of the code.
171 % \begin{macrocode}
172 \global\let\nx@\noexpand
173 % \end{macrocode}
174 % \end{macro}
175 %
176 % \begin{macro}{\xp@}
177 % Another convenient abbreviation.
178 % \begin{macrocode}
179 \global\let\xp@\expandafter
180 % \end{macrocode}
181 % \end{macro}
182 %
183 % \section{Reading standard file headers}
184 % The function \cw{inputfwh} (`input file with header') inputs
185 % the given file, checking first to see if it starts with a
186 % standardized file header; if so, the filename, version and date
187 % are scanned for and stored in a control sequence.
188 %
189 % For maximum robustness, we strive to rely on the fewest possible
190 % assumptions about what the file that is about to be input might
191 % contain.
192 %
193 % Assumption 1: Percent character \qc{\%} has category 14. I.e., if
194 % the first line of the file to be input starts with \qc{\%}, it is
195 % OK to throw away that line.
196 %
197 % \begin{macro}{\@percentchar}
198 % \begin{macrocode}
199 \begingroup \lccode`\.=`\%%
200 \lowercase{\gdef\@percentchar{.}}%
201 \endgroup
202 % \end{macrocode}
203 % \end{macro}
204 %
205 % \begin{macro}{\fileversiondate}
206 % The function \cw{fileversiondate} is not only a useful support
207 % function for \cw{inputfwh}, it can also be used by itself at the
208 % beginning of a file to set file name, version, and date correctly
209 % even if the file is input by some means other than
210 % \cw{inputfwh}\Dash assuming that the arguments of the
211 % \cw{fileversiondate} command are kept properly up to date.
212 % \begin{macrocode}
213 \gdef\fileversiondate#1#2#3{%
214 \xp@\xdef\csname#1\endcsname{#2 (#3)}%
215 \def\filename{#1}\def\fileversion{#2}%
216 \def\filedate{#3}%
217 \message{#1 \csname#1\endcsname}%
218 }
219 % \end{macrocode}
220 % And now apply \cw{fileversiondate} to this file.
221 % \begin{macrocode}
222 %<*209>
223 \fileversiondate{grabhedr.sty}{0.9j}{1994/11/08}
224 %</209>
225 % \end{macrocode}
226 % \end{macro}
227 %
228 % \begin{macro}{\@filehdrstart}
229 % \fn{filehdr.el} by default adds a string of equal signs (with an
230 % initial comment prefix) at the very top of a file header. This
231 % string must be scanned away first before we can start looking for
232 % the real information of the file header.
233 % \begin{macrocode}
234 \xdef\@filehdrstart{%
235 \@percentchar\@percentchar\@percentchar\space
236 ==================================%
237 ==================================}
238 % \end{macrocode}
239 % \end{macro}
240 %
241 % \begin{macro}{\@scanfileheader}
242 % The purpose of this function is just to scan up to the opening
243 % brace that marks the beginning of the file header body.
244 % Everything before that is ignored, not needed for our present
245 % purposes.
246 % \begin{macrocode}
247 \gdef\@scanfileheader#1@#2#{\@xscanfileheader}
248 % \end{macrocode}
249 % \end{macro}
250 %
251 % \begin{macro}{\@xscanfileheader}
252 % Throw in some dummy values of version and date at the end so that
253 % all we require from a file header is that the filename field must
254 % be present.
255 % \begin{macrocode}
256 \long\gdef\@xscanfileheader#1{%
257 \@yscanfileheader#1{} version = "??",
258 date = "??",\@yscanfileheader}
259 % \end{macrocode}
260 % \end{macro}
261 %
262 % \begin{macro}{\@yscanfileheader}
263 % This function assumes that filename, version, and date of a file
264 % are listed in that order (but not necessarily adjacent). It's
265 % possible for the version and date to be missing, or out of order,
266 % but the corresponding \tex/ variables \cw{fileversion} and
267 % \cw{filedate} will not get set properly unless the order is:
268 % filename, [\ldots,] version, [\ldots,] date. Trying to handle
269 % different orderings would be desirable but I haven't yet been
270 % struck by a suitable flash of insight on how to do it without
271 % grubby, time-consuming picking apart of the entire file header.
272 % \begin{macrocode}
273 \long\gdef\@yscanfileheader
274 #1 filename = "#2",#3 version = "#4",%
275 #5 date = "#6",#7\@yscanfileheader{%
276 \endgroup
277 \csname fileversiondate\endcsname{#2}{#4}{#6}%
278 }
279 % \end{macrocode}
280 % \end{macro}
281 %
282 % \begin{macro}{\@readfirstheaderline}
283 % This function has to look at the first line of the file to see if
284 % it has the expected form for the first line of a file header.
285 % \begin{macrocode}
286 \begingroup
287 \lccode`\$=`\^^M
288 \lowercase{\gdef\@readfirstheaderline#1$}{%
289 \toks@{#1}%
290 \edef\@tempa{\@percentchar\the\toks@}%
291 \ifx\@tempa\@filehdrstart
292 \endgroup \begingroup
293 \catcode`\%=9 \catcode`\^^M=5 \catcode`\@=11
294 % \end{macrocode}
295 % Double quote and equals sign need to be category 12 in order for
296 % the parameter matching of \cw{@xscanfileheader} to work, and
297 % space needs its normal catcode of 10.
298 % \begin{macrocode}
299 \catcode`\ =10 \catcode`\==12 \catcode`\"=12
300 \xp@\@scanfileheader
301 \else
302 \message{(* Missing file header? *)}%
303 \afterfi\endgroup
304 \fi}
305 \endgroup
306 % \end{macrocode}
307 % \end{macro}
308 %
309 % \begin{macro}{\@xinputfwh}
310 % An auxiliary function.
311 % \begin{macrocode}
312 \gdef\@xinputfwh{%
313 \ifx\next\@readfirstheaderline
314 % \end{macrocode}
315 % Sanitize a few characters. Otherwise an unmatched brace or other
316 % special character might cause a problem in the process of reading
317 % the first line as a macro argument.
318 % \begin{macrocode}
319 \catcode`\%=12 \catcode`\{=12 \catcode`\}=12
320 \catcode`\\=12 \catcode`\^^L=12
321 \catcode`\^=12
322 % Unique terminator token for the first line.
323 \catcode`\^^M=3\relax
324 \else \endgroup\fi
325 }
326 % \end{macrocode}
327 % \end{macro}
328 %
329 % \begin{macro}{\@inputfwh}
330 % Auxiliary function, carries out the necessary \cw{futurelet}.
331 % \begin{macrocode}
332 \gdef\@inputfwh{\futurelet\next\@xinputfwh}
333 % \end{macrocode}
334 % \end{macro}
335 %
336 % \begin{macro}{\inputfwh}
337 % Strategy for (almost) bulletproof reading of the first line of
338 % the input file is like this: Give the percent sign a special
339 % catcode, then use \cw{futurelet} to freeze the catcode of the
340 % first token in the input file. If the first token is {\em not\/}
341 % a percent character, then fine, just close the group wherein the
342 % percent character had its special catcode, and proceed with
343 % normal input; the first token will have its proper catcode
344 % because we did not change anything except the percent character.
345 % Otherwise, we still proceed with `normal' input execution, but by
346 % making \qc{\%} active and defining it suitably, we can carry out
347 % further tests to see if the first file line has the expected form
348 % (three percent signs plus lots of equal signs).
349 % \begin{macrocode}
350 \gdef\inputfwh#1{%
351 \begingroup\catcode`\%=\active
352 \endlinechar`\^^M\relax
353 \lccode`\~=`\%\relax
354 \lowercase{\let~}\@readfirstheaderline
355 \xp@\@inputfwh\@@input #1\relax
356 }
357 % \end{macrocode}
358 % \end{macro}
359 %
360 % \section{Managing catcode changes}
361 %
362 % A survey of other methods for saving and restoring catcodes would
363 % be more work than I have time for at the moment. The method
364 % given here is the best one I know (other methods use up one extra
365 % control sequence name per file, or don't robustly
366 % handle multiple levels of file nesting).
367 %
368 % \begin{macro}{\localcatcodes}
369 % The \cw{localcatcodes} function changes catcodes according to the
370 % character/catcode pairs given in its argument, saving the
371 % previous catcode values of those characters on a stack so that
372 % they can be retrieved later with \cw{restorecatcodes}. Example:
373 %\begin{usage}
374 %\localcatcodes{\@{11}\"\active}
375 %\end{usage}
376 % to change the catcode of \cs{\@} to 11 (letter) and the catcode
377 % of \qc{\"} to 13 (active). In \plaintex/ you'd better be careful
378 % to use \qc{\+} instead of \cs{\+} in the argument of
379 % \cw{localcatcodes} because of the outerness of \cs{\+}.
380 %
381 % This function works by using token registers 0 and 4
382 % to accumulate catcode assignment statements: in \cw{toks0} we put
383 % the statements necessary to restore catcodes to their previous
384 % values, while in \cw{toks 4} we put the statements necessary to
385 % set catcodes to their new values.
386 % \begin{macrocode}
387 \gdef\localcatcodes#1{%
388 \ifx\@empty\@catcodestack
389 \gdef\@catcodestack{{}}%
390 \fi
391 \def\do##1##2{%
392 \ifnum##2>\z@
393 \catcode\number`##1 \space
394 \number\catcode`##1\relax
395 \expandafter\do\fi}%
396 \xdef\@catcodestack{{\do#1\relax\m@ne}%
397 \@catcodestack}%
398 \def\do##1##2{\catcode`##1 ##2\relax\do}%
399 \do#1\ {\catcode32\let\do}%
400 }
401 % \end{macrocode}
402 % \end{macro}
403 %
404 % \begin{macro}{\@catcodestack}
405 % Init the stack with an empty element; otherwise popping the
406 % next-to-last element would wrongly remove braces from the last
407 % element. But as a matter of fact we could just as well initialize
408 % \cw{@catcodestack} to empty because \cw{localcatcodes} is careful
409 % to add an empty final element if necessary.
410 % \begin{macrocode}
411 \gdef\@catcodestack{{}}
412 % \end{macrocode}
413 % \end{macro}
414 %
415 % \begin{macro}{\restorecatcodes}
416 % The function \cw{restorecatcodes} has to pop the stack and
417 % execute the popped code.
418 % \begin{macrocode}
419 \gdef\restorecatcodes{%
420 \begingroup
421 \ifx\@empty\@catcodestack
422 \errmessage{Can't pop catcodes;
423 \nx@\@catcodestack = empty}%
424 \endgroup
425 \else
426 \def\do##1##2\do{%
427 \gdef\@catcodestack{##2}%
428 % \end{macrocode}
429 % Notice the placement of \arg{1} after the \cw{endgroup}, so that
430 % the catcode assignments are local assignments.
431 % \begin{macrocode}
432 \endgroup##1}%
433 \xp@\do\@catcodestack\do
434 \fi
435 }
436 % \end{macrocode}
437 % \end{macro}
438 %
439 % \section{Trapping redundant input statements}
440 % The utility \fn{listout.tex} calls \fn{menus.sty}, which calls
441 % \fn{dialog.sty}, and all three of these files start by loading
442 % \fn{grabhedr.sty} in order to take advantage of its functions
443 % \cw{fileversiondate}, \cw{localcatcodes}, and \cw{inputfwh}. But
444 % consequently, when \fn{listout.tex} is used there will be two
445 % redundant attempts to load \fn{grabhedr.sty}. The straightforward
446 % way to avoid the redundant input attempts would be to surround
447 % them with an \cw{ifx} test:
448 %
449 %^^V \ifx\undefined\fileversiondate
450 %^^V \input grabhedr.sty \relax
451 %^^V \fileversiondate{foo.bar}{0.9e}{10-Jun-1993}
452 %^^V \fi
453 %
454 % This method has a few drawbacks, however: (1)~the conditional
455 % remains open throughout the processing of everything in
456 % \fn{grabhedr.sty} and the \cw{fileversiondate} statement, which
457 % makes any \cw{else} or \cw{fi} mismatch problems harder to debug;
458 % (2)~if \cw{undefined} becomes accidentally defined the \cw{ifx}
459 % test will fail; (3)~choosing the right control sequence to test
460 % against \cw{undefined} requires a little care.
461 %
462 % In a situation where we know that the file to be input has had
463 % \cw{fileversiondate} applied to it, if it was already input, then
464 % we have a failsafe control sequence that we can test to find out
465 % whether the file has already been input\Dash the name
466 % of the file. Assuming a standard form for the input statement
467 % (one that will work with either plain \tex/ or \latex/, and makes
468 % as few assumptions as possible), we can write a function that
469 % will trap input statements and execute them only if the given
470 % file has not yet been loaded:
471 %
472 %^^V \csname trap.input\endcsname
473 %^^V \input grabhedr.sty \relax
474 %^^V \fileversiondate{foo.bar}{1.2}{1993-Jun-07}
475 %
476 % \begin{macro}{\trap.input}
477 % The function \cw{trap.input} scans for an input statement in
478 % canonical form and executes it if and only if the file has not yet
479 % been input (more precisely, if the control sequence consisting of
480 % the file name is undefined, which means that it has not had
481 % \cw{fileversiondate} applied to it). The canonical form
482 % that I consider to be the best is \cw{input} \meta{full file
483 % name}{\tt\char32 }\cw{relax}. Having the \cw{relax} means that the
484 % input statement will not try to expand beyond the end of the line
485 % if \cw{endlinechar} is catcoded to 9 (ignore), as is done rather
486 % frequently now by progressive \tex/ programmers. The \cw{relax}
487 % would ordinarily render the space after the file name unnecessary,
488 % but I prefer leaving the space in to avoid interfering with
489 % redefinitions of \cw{input} to take a space-delimited argument
490 % that are occasionally done to achieve other special effects (see,
491 % for example, ``Organizing a large collection of stylefiles'', by
492 % Angelika Binding, {\sl Cahiers GUTenberg}, num\'ero 10--11,
493 % septembre 1991, p.~175.) \latex/'s argument form
494 % \cw{input}\verb"{...}" cannot, unfortunately, be the
495 % canonical form if \plaintex/ compatibility is required.
496 % \begin{macrocode}
497 \expandafter\gdef\csname trap.input\endcsname
498 \input#1 \relax{%
499 \expandafter\ifx\csname#1\endcsname\relax
500 \afterfi\inputfwh{#1}\relax
501 \fi}
502 % \end{macrocode}
503 % \end{macro}
504 %
505 % End the group that encloses this entire file, and then call
506 % \cw{endinput}.
507 % \begin{macrocode}
508 \endgroup
509 \endinput
510 % \end{macrocode}
511 %
512 % \CheckSum{294}
513 % \Finale