Debian Codegraph @

texmf-dist/source/latex/sauerj/collect.dtx

raw
1 % \iffalse meta-comment
2 % Line endings: UNIX
3 % Tab size: 4
4 %
5 % Copyright 2004 Jonathan Sauer
6 %
7 % This work may be distributed and/or modified under the
8 % conditions of the LaTeX Project Public License, either version 1.3
9 % of this license or (at your option) any later version.
10 % The latest version of this license is in
11 %
12 % http://www.latex-project.org/lppl.txt
13 %
14 % and version 1.3 or later is part of all distributions of LaTeX
15 % version 2003/12/01 or later.
16 %
17 % This work has the LPPL maintenance status "maintained".
18 %
19 % The Current Maintainer of this work is Jonathan Sauer
20 % (<[email protected]>).
21 %
22 % This work consists of the files collect.dtx and collect.ins
23 % and the derived file collect.sty.
24 %
25 % \fi
26 %
27 % \iffalse
28 %
29 %<*driver>
30 \documentclass{ltxdoc}
31 \usepackage{collect}
32 \EnableCrossrefs
33 \CodelineIndex
34 \RecordChanges
35 % Modification of verbatim for tabs in listings
36 \makeatletter
37 {\catcode`\ =\active%
38 \catcode`\^^I=\active%
39 \gdef\@vobeyspaces{%
40 \catcode`\ \active\let \@xobeysp%
41 \catcode`\^^I\active\def^^I{~~}%
42 }}%
43 \makeatother
44 \begin{document}
45 \DocInput{\jobname.dtx}
46 \end{document}
47 %</driver>
48 %
49 %<package>\NeedsTeXFormat{LaTeX2e}
50 %<package>\ProvidesPackage{collect}
51 %<package> [2004/09/12 v0.9 collect the contents of an environment]
52 %
53 % \fi
54 %
55 % \CheckSum{256}
56 % \CharacterTable
57 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
58 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
59 % Digits \0\1\2\3\4\5\6\7\8\9
60 % Exclamation \! Double quote \" Hash (number) \#
61 % Dollar \$ Percent \% Ampersand \&
62 % Acute accent \' Left paren \( Right paren \)
63 % Asterisk \* Plus \+ Comma \,
64 % Minus \- Point \. Solidus \/
65 % Colon \: Semicolon \; Less than \<
66 % Equals \= Greater than \> Question mark \?
67 % Commercial at \@ Left bracket \[ Backslash \\
68 % Right bracket \] Circumflex \^ Underscore \_
69 % Grave accent \` Left brace \{ Vertical bar \|
70 % Right brace \} Tilde \~}
71 %
72 %
73 % \DoNotIndex{\@currenvir,\@ehc,\@ifundefined,\@input}
74 % \DoNotIndex{\@tempa,\@tempb,\bgroup,\catcode,\closeout,\csname}
75 % \DoNotIndex{\def,\edef,\egroup,\else,\end,\endcsname,\expandafter}
76 % \DoNotIndex{\fi,\futurelet,\gdef,\global,\ifx,\immediate,\jobname,\let,\long}
77 % \DoNotIndex{\meaning,\newcommand,\newenvironment,\newif,\newwrite}
78 % \DoNotIndex{\openout,\PackageError,\par,\strip@prefix,\the,\toks@}
79 % \DoNotIndex{\write}
80 %
81 % \GetFileInfo{\jobname.sty}
82 %
83 % \title{The \textsf{collect} package\thanks{This document
84 % corresponds to \textsf{\filename}~\fileversion, dated \filedate.}}
85 %
86 % \author{Jonathan Sauer \\ \texttt{[email protected]}}
87 %
88 % \date{\filedate}
89 %
90 % \maketitle
91 %
92 % \begin{abstract}
93 % This file describes the \textsf{collect} package that
94 % makes it possible to collect text for later use.
95 %
96 % \end{abstract}
97 %
98 % \tableofcontents
99 %
100 % \section{Introduction}
101 %
102 % Suppose you are writing the specification of a programming language.
103 % Then you will surely insert definitions of the grammar (i.e. using
104 % the \textsf{syntax} package). Most likely you will insert the
105 % grammar for i.e. loops, conditions et cetera in the appropriate
106 % chapter, but for easy implementation of a parser, you will want to
107 % include the complete grammar as an appendix, so that one does not
108 % have to collect the complete grammar from the bits in each chapter.
109 %
110 % Of course you could do this by hand using the copy-and-paste
111 % facility of your text editor. But this is cumbersome and errorprone
112 % if you modify the grammar afterwards, i.e. for a second version.
113 %
114 % This package provides the |collect| environment that typesets
115 % its contents and collects it for later use as well.
116 %
117 % In other situations you will want to save the contents of an
118 % environment in a macro. Then the |collectinmacro| environment
119 % should do the trick.
120 %
121 %
122 %
123 % \section{Usage}
124 %
125 % \paragraph{General note} If an environment exists in a normal and a
126 % starred form (i.e. |collect| and |collect*|), then the former does
127 % not typeset the environment contents, while the latter typesets it.
128 % Note, too, that the normal and the starred version of an environment
129 % often have a different number of parameters.
130 %
131 % \paragraph{Stripping of spaces} All environments strip any leading
132 % space before the start of the text and any trailing space after the
133 % end of the text. Trailing |\par|s (i.e. resulting from a blank line
134 % at the end of the environment) are \emph{not} removed.
135 %
136 %
137 %
138 %
139 % \subsection{\texttt{collect}}
140 %
141 % You can define several \emph{collections}. Each collection can be
142 % used independently to collect text across the document. You define a
143 % collection using |\definecollection|, use it in the |collect| and
144 % |collect*| environment and typeset it using |\includecollection|.
145 %
146 % \paragraph{Note} The name of the collection is used as the suffix of
147 % the file that stores the collection (the complete name is
148 % \meta{jobname}|.|\meta{name)}. So you should not name a collection
149 % |tex|, |log|, |dvi|, |pdf| and so on.
150 %
151 % \paragraph{Note} You can only include a collection after completely
152 % collecting it. If you include it and continue to collect afterwards,
153 % the collection will be cleared after its inclusion.
154 %
155 % This can be used to recycle a collection: Use it in the first part
156 % of your document to collect text, typeset this text using
157 % |\includecollection| and then reuse the collection in the second
158 % part of your document to collect new text which will finally be
159 % typeset using |\includecollection| a second time.
160 %
161 %
162 % \DescribeMacro{\definecollection} Usage: |\definecollection|
163 % \marg{name}.
164 %
165 % Defines a collection of the name \meta{name}.
166 %
167 %
168 % \DescribeEnv{collect*} Usage: |\begin{collect*}|
169 % \marg{name} \marg{before} \marg{after} \marg{beforecol}
170 % \marg{aftercol} \ldots\ |\end{collect*}|.
171 %
172 % Collects the text inside the environment in the collection
173 % \meta{name}. Then typesets the text. \meta{name} must have been
174 % defined using |\definecollection|.
175 %
176 % \meta{before} and \meta{after} are tokens inserted before and after
177 % the environment contents in the collection as well as the typeset
178 % text.
179 %
180 % \meta{beforecol} and \meta{aftercol} are tokens inserted before and
181 % after the environment contents only in the collection. This can be
182 % used to insert a section heading (\meta{beforecol}) and a backref to
183 % the section where the text has been collected (\meta{aftercol}).
184 %
185 % \paragraph{Note} The |collect*| environment uses a temporary file
186 % \meta{jobname}|.tmp| to temporarily store the environment contents
187 % and include it afterwards.\footnote{This way, catcode changes inside
188 % the environment are honored.}
189 %
190 %
191 % \DescribeEnv{collect} Usage: |\begin{collect}| \marg{name}
192 % \marg{beforecol} \marg{aftercol} \ldots\ |\end{collect}|.
193 %
194 % Collects the text inside the environment in the collection
195 % \meta{name}. \emph{Does not} typeset the text (therefore, the two
196 % parameters \meta{before} and \meta{after} are missing); except for
197 % that, this environment is identical to |collect*|.
198 %
199 %
200 % \DescribeMacro{\includecollection} Usage: |\includecollection|
201 % \marg{name}. Includes the collection \meta{name}. Afterwards, the
202 % collection is reset.
203 %
204 % You can include the collection \emph{before} it is actually
205 % collected in the same way you can include a table of contents at the
206 % beginning of your document. Simply say |\includecollection| and then
207 % use the |collect*| or |collect| environment to collect text. Then
208 % run \LaTeX\ on your file \emph{twice}. (the first time to collect
209 % the text, the second time to put it in the document using
210 % |\includecollection|)
211 %
212 %
213 %
214 % \subsection{Other environments}
215 %
216 % \DescribeEnv{collectinmacro} Usage: |\begin{collectinmacro}|
217 % \marg{macro} \marg{before} \marg{after} \ldots\
218 % |\end{collectinmacro}|.
219 %
220 % Collects the contents of an environment inside a macro \meta{macro}
221 % without typesetting it. If \meta{macro} has been defined prior to
222 % using this environment, its previous meaning is lost. The new
223 % definition is global.
224 %
225 % \meta{before} and \meta{after} are tokens inserted before and after
226 % the environment contents in the macro.
227 %
228 % \paragraph{Important note} This environment differs slightly from
229 % |collect| and |collect*|: Some macros, i.e. |\verb|, do not work
230 % correctly when \meta{macro} is used later on.\footnote{As the
231 % catcodes have already been set when collecting the contents and
232 % cannot be changed afterwards, at least not without e\TeX.}
233 %
234 %
235 %
236 %
237 % \section{Examples}
238 %
239 % \subsection{\texttt{collect}}
240 %
241 % \begin{verbatim}
242 % \begin{collect*}{tst}{Before\par}{\par After}{Before file\par}{\par After file}
243 % This is a test
244 % \end{collect*}
245 % \end{verbatim}
246 %
247 % \noindent This results in the following text typeset directly:
248 %
249 % \begin{verbatim}
250 % Before
251 % This is a test
252 % After
253 % \end{verbatim}
254 %
255 % \noindent And following text is typeset when the collection |tst| is
256 % included using |\includecollection{tst}|:
257 %
258 % \begin{verbatim}
259 % Before file
260 % Before
261 % This is a test
262 % After
263 % After file
264 % \end{verbatim}
265 %
266 %
267 %
268 %
269 % \subsection{Other environments}
270 %
271 % \begin{verbatim}
272 % \begin{collectinmacro}{\collectedtext}{Before\par}{\par After}
273 % This is a test
274 % \end{collectinmacro}
275 % \end{verbatim}
276 %
277 % \noindent This results in no text typeset directly and the following
278 % text stored in the macro |\collectedtext|:
279 %
280 % \begin{verbatim}
281 % Before\par This is a test\par After
282 % \end{verbatim}
283 %
284 %
285 %
286 %
287 % \section{Creating your own environment}
288 %
289 % You can create your own environment based on any of the environments
290 % in this package, i.e. to create a |grammarpart| environment to
291 % typeset part of a grammar.
292 %
293 % You can for example say:
294 %
295 % \begin{verbatim}
296 % \definecollection{gra}
297 %
298 % \newenvironment{grammarpart}[1]{%
299 % \@nameuse{collect*}{gra}{%
300 % \emph{Start of grammar `#1'}\par%
301 % }{%
302 % \par\emph{End of grammar}\par%
303 % }{%
304 % \subsection{#1}%
305 % }{%
306 % \par See some section in the text.
307 % }%
308 % }{%
309 % \@nameuse{endcollect*}%
310 % }
311 % \end{verbatim}
312 %
313 % \noindent This will create a |grammarpart| environment with one
314 % parameter, the part of the grammar defined. (i.e. `Identifiers') At
315 % the start of the environment the text `\emph{Start of grammar
316 % \meta{part}}' will be typeset, followed by the grammar (the contents
317 % of the environment), and finally a line `\emph{End of grammar}' will
318 % be added.
319 %
320 % When including the collected grammar parts using
321 % |\includecollection| each grammar part will be prefixed by a
322 % subsection heading bearing the grammar part as its title and
323 % suffixed by `See some section in the text.' (this could be extended
324 % to include a backref using |\ref|\meta{label})
325 %
326 % \paragraph{Note} If you use any of the environments inside a custom
327 % environment to afterwards collect text with this custom environment
328 % (as in the example of the |grammarpart| environment above), you
329 % \emph{must not} begin and end it using |\begin| and |\end|, or the
330 % environment contents will not be collected correctly. You must use
331 % |\@nameuse{|\meta{environment}|}| and
332 % |\@nameuse{end|\meta{environment}|}| as in the example above, or, if
333 % the environment is not starred, |\|\meta{environment} and
334 % |\end|\meta{environment}.
335 %
336 % \paragraph{Note} You still can use the environments of this package
337 % inside other environments (i.e. a |itemize| environment) without any
338 % problems.
339 %
340 %
341 %
342 %
343 % \section{Notes}
344 %
345 % \begin{itemize}
346 % \item If you use any of the environments inside your own
347 % environment, note that the end of the environment is
348 % executed, but not included in the collected text! (that's
349 % why the the environments |collect*| and |collectinmacro|
350 % have two parameters for including text before and after
351 % the environment, \meta{before} and \meta{after}).
352 %
353 % \end{itemize}
354 %
355 %
356 %
357 %
358 % \StopEventually{}
359 %
360 % \section{Implementation}
361 %
362 % \subsection{Main environments and macros}
363 %
364 % \subsubsection{\texttt{collect}}
365 %
366 % \begin{macro}{\definecollection}
367 %
368 % Usage: |\definecollection| \marg{name}
369 %
370 % Defines a collection \meta{name}.
371 %
372 % This macro allocates a |\newwrite| |CE@@|\meta{name}|@out| and
373 % defines a |\newif| |CE@@|\meta{name}|open|.
374 %
375 % \begin{macrocode}
376 \newcommand{\definecollection}[1]{%
377 \@ifundefined{CE@@#1@out}{%
378 \expandafter\newwrite\csname CE@@#1@out\endcsname%
379 \expandafter\newif\csname ifCE@@#1@open\endcsname%
380 \csname CE@@#1@openfalse\endcsname%
381 }{%
382 \PackageError{collect}{Collection `#1' has already %
383 been defined}{\@ehc}%
384 }%
385 }
386 % \end{macrocode}
387 % \end{macro}
388 %
389 %
390 % \begin{environment}{collect*}
391 %
392 % Usage: |\begin{collect*}| \marg{name} \marg{before}
393 % \marg{after} \marg{beforecol} \marg{aftercol} \ldots\
394 % |\end{collect*}|.
395 %
396 % \begin{macrocode}
397 \newenvironment{collect*}[5]{%
398 \global\toks@{}%
399 \def\CE@file{#1}%
400 \def\CE@preenv{#2}%
401 \def\CE@postenv{#3}%
402 \def\CE@prefileenv{#4}%
403 \def\CE@postfileenv{#5}%
404 \CE@get@env@body@start%
405 }{%
406 % \end{macrocode}
407 %
408 % What are we doing? We make sure the collection is open, then we save
409 % \meta{beforecol}, \meta{before}, the collected environment contents,
410 % \meta{after} and \meta{aftercol} in the collection file.
411 %
412 % \begin{macrocode}
413 \CE@ensure@opened{\CE@file}%
414 \edef\@tempa{\csname CE@@\CE@file @out\endcsname}%
415 \immediate\write\@tempa{\CE@meaning\CE@prefileenv}%
416 \immediate\write\@tempa{\CE@meaning\CE@preenv}%
417 \immediate\write\@tempa{\the\toks@}%
418 \immediate\write\@tempa{\CE@meaning\CE@postenv}%
419 \immediate\write\@tempa{\CE@meaning\CE@postfileenv}%
420 % \end{macrocode}
421 %
422 % Now we repeat the same thing, but with the temporary file and
423 % writing only \meta{before}, the collected environment contents and
424 % \meta{after}. Then we include the temporary file.
425 %
426 % Why so complicated, as we have the contents of the environment in
427 % |\toks@|? Because the catcodes might not be correct, i.e. if |\verb|
428 % is used inside the environment. So we have to read the environment
429 % contents again, which without e\TeX\ is only possible using a
430 % temporary file.
431 %
432 % \begin{macrocode}
433 \immediate\openout\CE@tmp@out=\jobname.tmp%
434 \immediate\write\CE@tmp@out{\CE@meaning\CE@preenv}%
435 \immediate\write\CE@tmp@out{\the\toks@}%
436 \immediate\write\CE@tmp@out{\CE@meaning\CE@postenv}%
437 \immediate\closeout\CE@tmp@out%
438 \@input{\jobname.tmp}%
439 \par%
440 }
441 % \end{macrocode}
442 % \end{environment}
443 %
444 %
445 % \begin{environment}{collect}
446 %
447 % Usage: |\begin{collect}| \marg{name} \marg{beforecol}
448 % \marg{aftercol} \ldots\ |\end{collect}|.
449 %
450 % \begin{macrocode}
451 \newenvironment{collect}[3]{%
452 \global\toks@{}%
453 \def\CE@file{#1}%
454 \def\CE@prefileenv{#2}%
455 \def\CE@postfileenv{#3}%
456 \CE@get@env@body@start%
457 }{%
458 % \end{macrocode}
459 %
460 % As this environment, contrary to |collect*|, does not typeset its
461 % contents, we only write to the collection file:
462 %
463 % \begin{macrocode}
464 \CE@ensure@opened{\CE@file}%
465 \edef\@tempa{\csname CE@@\CE@file @out\endcsname}%
466 \immediate\write\@tempa{\CE@meaning\CE@prefileenv}%
467 \immediate\write\@tempa{\the\toks@}%
468 \immediate\write\@tempa{\CE@meaning\CE@postfileenv}%
469 }
470 % \end{macrocode}
471 % \end{environment}
472 %
473 %
474 % \begin{macro}{\includecollection}
475 %
476 % Usage: |\includecollection| \marg{name}.
477 %
478 % Includes the collection \meta{name} which must have been defined
479 % previously using |\definecollection|. Afterwards, the collection is
480 % cleared.
481 %
482 % \begin{macrocode}
483 \newcommand{\includecollection}[1]{%
484 \CE@ensure@closed{#1}%
485 \@input{\jobname.#1}%
486 }
487 % \end{macrocode}
488 % \end{macro}
489 %
490 %
491 %
492 % \subsubsection{Other environments}
493 %
494 % \begin{environment}{collectinmacro}
495 %
496 % Usage: |\begin{collectinmacro}| \marg{macro} \marg{before}
497 % \marg{after} \ldots\ |\end{collectinmacro}|.
498 %
499 % Collects the contents of an environment inside a macro.
500 %
501 % \begin{macrocode}
502 \newenvironment{collectinmacro}[3]{%
503 \def\CE@destmacro{#1}%
504 \def\CE@postenv{#3}%
505 % \end{macrocode}
506 %
507 % We initialize the result with \meta{before}:
508 %
509 % \begin{macrocode}
510 \toks@{#2}%
511 \CE@get@env@body@start%
512 }{%
513 % \end{macrocode}
514 %
515 % We add \meta{after}:
516 %
517 % \begin{macrocode}
518 \toks@\expandafter\expandafter\expandafter{%
519 \expandafter\the\expandafter\toks@\CE@postenv}%
520 % \end{macrocode}
521 %
522 % Finally we globally define \meta{macro} to contain the collected
523 % contents:
524 %
525 % \begin{macrocode}
526 \expandafter\expandafter\expandafter%
527 \gdef\expandafter\CE@destmacro\expandafter{\the\toks@}%
528 \toks@{}%
529 }
530 % \end{macrocode}
531 % \end{environment}
532 %
533 %
534 %
535 %
536 % \subsection{Internal environments and macros}
537 %
538 % We allocate a new |\newwrite| for the processing of a temporary
539 % file:
540 %
541 % \begin{macrocode}
542 \newwrite\CE@tmp@out
543 % \end{macrocode}
544 %
545 %
546 % \begin{macro}{\CE@get@env@body@start}
547 %
548 % Starts the collecting of the contents of an environment. (the
549 % environment starts immediately after the macro)
550 %
551 % \begin{macrocode}
552 \def\CE@get@env@body@start{%
553 \let\@tempa\CE@get@env@body%
554 % \end{macrocode}
555 %
556 % We may have to gobble leading spaces, therefore we check the first
557 % character in the environment:
558 %
559 % \begin{macrocode}
560 \futurelet\@tempb\CE@get@env@body@start@%
561 }
562 % \end{macrocode}
563 % \end{macro}
564 %
565 %
566 % \begin{macro}{\CE@get@env@body@start@}
567 %
568 % Support macro for |\CE@get@env@body@start|. Checks if the next token
569 % is a space, then calls |\CE@get@env@body@start@@|. Otherwise, the
570 % collecting of the environment contents is started.
571 %
572 % \begin{macrocode}
573 \def\CE@get@env@body@start@{%
574 % \end{macrocode}
575 %
576 % |\@sptoken| contains a single space and is defined in
577 % \textsf{ltdefns.dtx}:
578 %
579 % \begin{macrocode}
580 \ifx\@tempb\@sptoken%
581 \expandafter\CE@get@env@body@start@@%
582 \else%
583 \expandafter\CE@get@env@body%
584 \fi%
585 }
586 % \end{macrocode}
587 % \end{macro}
588 %
589 %
590 % \begin{macro}{\CE@get@env@body@start@@}
591 %
592 % Support macro for |\CE@get@env@body@start@|. Gobbles up any space
593 % following the macro, then start the collecting of the environment
594 % contents using |\CE@get@env@body|.
595 %
596 % \begin{macrocode}
597 \def\CE@get@env@body@start@@{%
598 \afterassignment\CE@get@env@body%
599 \let\@tempb= %
600 }
601 % \end{macrocode}
602 % \end{macro}
603 %
604 %
605 % \begin{macro}{\CE@get@env@body}
606 %
607 % Usage: |\CE@get@env@body| \marg{body} |\end| \marg{envname}.
608 %
609 % To ensure proper initialization, this macro should not be called
610 % directly; instead |\CE@get@env@body@start| should be called.
611 %
612 % First we change the catcode of |Q| to 3 (math switch) in order to
613 % have a really unique character for parameter matching later
614 % on.\footnote{Taken from `Around the bend 15'} We do this in a group
615 % in order to easily restore the catcode later on and make all macro
616 % definitions global:
617 %
618 % \begin{macrocode}
619 \bgroup
620 \catcode`\Q=3
621 % \end{macrocode}
622 %
623 % Now we begin the macro:
624 %
625 % \begin{macrocode}
626 \long\gdef\CE@get@env@body#1\end#2{%
627 % \end{macrocode}
628 %
629 % Right at the beginning of the macro, we are at an |\end| (and |#1|
630 % contains the contents prior to it). We check if it ends the current
631 % environment (|#2| contains the name of the environment ended):
632 %
633 % \begin{macrocode}
634 \def\@tempb{#2}%
635 \ifx\@tempb\@currenvir%
636 % \end{macrocode}
637 %
638 % \paragraph{Yes, it ends the current environment.} We add the
639 % contents to |\toks@| and are done. But we do not add the contents
640 % directly as there may be a trailing space left (multiple spaces have
641 % been collapsed into one space by \TeX). So we call
642 % |\CE@get@env@body@| using delimited parameters (note that |Q| has
643 % catcode 3, therefore a normal |Q| is not matched).
644 %
645 % What exactly is going on here? Suppose we have the text
646 %
647 % \begin{verbatim}
648 % Hello World_
649 % \end{verbatim}
650 % %
651 % \noindent (the |_| denotes the trailing space). Then
652 % |\CE@get@env@body@| is called like this:
653 %
654 % \begin{verbatim}
655 % \CE@get@env@body@Hello World Q Q
656 % \end{verbatim}
657 % %
658 % \noindent |\CE@get@env@body@| matches the parameters like this: |#1|
659 % is `Hello World'; leaving |_Q| (added by the call from
660 % |\CE@get@env@body|) in the input. |\CE@get@env@body@| then calls
661 % |\CE@get@env@body@@| using |#1| and |Q|, resulting in the call:
662 %
663 % \begin{verbatim}
664 % \CE@get@env@body@@Hello WorldQ Q
665 % \end{verbatim}
666 % %
667 % \noindent |\CE@get@env@body@@| matches its parameter like this: |#1|
668 % is `Hello World' again, and |#2| is the second |Q|.
669 %
670 % But what happened to the space between the two |Q|s? As |#2| is not
671 % a delimited parameter, \TeX\ skips spaces after matching the first
672 % |Q| until it reaches the second |Q|, thus gobbling up the space
673 % inbetween.\footnote{c.f. \TeX book chapter 20.}
674 %
675 % \addvspace{\baselineskip}\noindent Now suppose we have the text
676 % \begin{verbatim}
677 % Hello World
678 % \end{verbatim}
679 % %
680 % \noindent without any trailing space. Then |\CE@get@env@body@| is
681 % called like this:
682 %
683 % \begin{verbatim}
684 % \CE@get@env@body@Hello WorldQ Q
685 % \end{verbatim}
686 % %
687 % \noindent |\CE@get@env@body@| matches its parameters like this: |#1|
688 % is `Hello WorldQ'. |\CE@get@env@body@| then calls
689 % |\CE@get@env@body@@| using |#1| and |Q|, resulting in the call:
690 %
691 % \begin{verbatim}
692 % \CE@get@env@body@@Hello WorldQQ
693 % \end{verbatim}
694 % %
695 % \noindent |\CE@get@env@body@@| matches its parameter like this: |#1|
696 % is `Hello World' without the trailing `Q', and |#2| is the second
697 % |Q|. The only difference to the situation described above is the
698 % missing space between the two |Q|s.
699 %
700 % Remember that the `Q' is always `Q' with catcode 3, thus no `Q' in
701 % the environment contents is matched.
702 %
703 % \begin{macrocode}
704 \CE@get@env@body@#1Q Q%
705 \def\@tempa{\end{#2}}%
706 \else
707 % \end{macrocode}
708 %
709 % \paragraph{No, it ends another environment.} We add the contents as
710 % well as the |\end|\meta{environment} to |\toks@|. Then we continue
711 % collecting:
712 %
713 % \begin{macrocode}
714 \toks@\expandafter{\the\toks@#1\end{#2}}%
715 \fi%
716 \@tempa%
717 }
718 % \end{macrocode}
719 % \end{macro}
720 %
721 %
722 % \begin{macro}{\CE@get@env@body@}
723 %
724 % Support macro for |\CE@get@env@body|. See |\CE@get@env@body| for
725 % explanations.
726 %
727 % \begin{macrocode}
728 \long\gdef\CE@get@env@body@#1 Q{%
729 \CE@get@env@body@@#1Q%
730 }
731 % \end{macrocode}
732 % \end{macro}
733 %
734
735 % \begin{macro}{\CE@get@env@body@@}
736 %
737 % Support macro for |\CE@get@env@body@|. See |\CE@get@env@body| for
738 % explanations.
739 %
740 % \begin{macrocode}
741 \long\gdef\CE@get@env@body@@#1Q#2{%
742 \toks@\expandafter{\the\toks@#1}%
743 }
744 % \end{macrocode}
745 % \end{macro}
746 %
747 % Finally we end the group, thus restoring the catcode of |Q|:
748 %
749 % \begin{macrocode}
750 \egroup
751 % \end{macrocode}
752 %
753 %
754 % \begin{macro}{\CE@meaning}
755 %
756 % Usage: |\CE@meaning| \marg{macro}.
757 %
758 % Expands to the meaning of \meta{macro}.
759 %
760 % \begin{macrocode}
761 \long\def\CE@meaning#1{%
762 \expandafter\strip@prefix\meaning#1%
763 }
764 % \end{macrocode}
765 % \end{macro}
766 %
767 %
768 % \begin{macro}{\CE@ensure@opened}
769 %
770 % Usage: |\CE@ensure@opened| \marg{name}.
771 %
772 % Ensures that the file for collection \meta{name} is opened.
773 %
774 % \begin{macrocode}
775 \def\CE@ensure@opened#1{%
776 \@ifundefined{ifCE@@#1@open}{%
777 \PackageError{collect}{Collection `#1' has not been defined}{\@ehc}%
778 }{%
779 \csname ifCE@@#1@open\endcsname\else%
780 \expandafter\immediate\expandafter\openout%
781 \csname CE@@#1@out\endcsname=\jobname.#1%
782 \expandafter\global\csname CE@@#1@opentrue\endcsname%
783 \fi%
784 }%
785 }
786 % \end{macrocode}
787 % \end{macro}
788 %
789 %
790 % \begin{macro}{\CE@ensure@closed}
791 %
792 % Usage: |\CE@ensure@closed| \marg{name}.
793 %
794 % Ensures that the file for collection \meta{name} is closed.
795 %
796 % \begin{macrocode}
797 \def\CE@ensure@closed#1{%
798 \@ifundefined{ifCE@@#1@open}{%
799 \PackageError{collect}{Collection `#1' has not been defined}{\@ehc}%
800 }{%
801 \csname ifCE@@#1@open\endcsname%
802 \expandafter\immediate\expandafter\closeout%
803 \csname CE@@#1@out\endcsname%
804 \expandafter\global\csname CE@@#1@openfalse\endcsname%
805 \fi%
806 }%
807 }
808 % \end{macrocode}
809 % \end{macro}
810 %
811 %
812 % \Finale
813 % \PrintChanges
814 % \PrintIndex
815 \endinput