Debian Codegraph @

texmf-dist/source/latex/sauerj/metainfo.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 metainfo.dtx and metainfo.ins
23 % and the derived file metainfo.sty.
24 %
25 % \fi
26 %
27 % \iffalse
28 %
29 %<*driver>
30 \documentclass{ltxdoc}
31 \usepackage{metainfo}
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{metainfo}
51 %<package> [2004/11/25 v0.9.1 typeset document metainfo]
52 %
53 % \fi
54 %
55 % \CheckSum{386}
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 % \DoNotIndex{\@@input,\|}
73 % \DoNotIndex{\@ifundefined,\@ehc,\@empty,\@gobbletwo,\@nil}
74 % \DoNotIndex{\@startsection,\@tempa,\active,\baselineskip}
75 % \DoNotIndex{\begin,\bfseries,\bgroup,\catcode,\DeclareOption}
76 % \DoNotIndex{\def,\egroup,\else,\end,\endinput,\expandafter}
77 % \DoNotIndex{\fi,\futurelet,\gdef,\ifmmode,\ifcat,\ifx}
78 % \DoNotIndex{\index,\item,\let,\long,\newcommand,\newif}
79 % \DoNotIndex{\noexpand,\noindent,\normalfont,\normalsize}
80 % \DoNotIndex{\PackageError,\par,\ProcessOptions,\relax,\space}
81 % \DoNotIndex{\string,\textbf,\z@}
82 %
83 % \GetFileInfo{\jobname.sty}
84 %
85 % \title{The \textsf{metainfo} package\thanks{This document
86 % corresponds to \textsf{\filename}~\fileversion, dated \filedate.}}
87 %
88 % \author{Jonathan Sauer \\ \texttt{[email protected]}}
89 %
90 % \date{\filedate}
91 %
92 % \maketitle
93 %
94 % \begin{abstract}
95 % This file describes the \textsf{metainfo} package that typesets only
96 % special comments of a \TeX\ file.
97 %
98 % \end{abstract}
99 %
100 % \tableofcontents
101 %
102 % \section{Introduction}
103 %
104 % Suppose you write a text and include some annotations for yourself
105 % that are not printed, i.e. an explanation of a pun or a short
106 % summary of the current chapter in order to be able to later create a
107 % summary of the whole text. Then it would be nice to be able to
108 % extract these annotations and typeset them separately. This package
109 % provides the macro |\typesetmetainfo| to typeset only these
110 % annotations (herein called `metainfo', as they are information about
111 % the information contained in the text).
112 %
113 %
114 %
115 %
116 % \section{Macros}
117 %
118 % \DescribeMacro{\typesetmetainfo} Usage: |\typesetmetainfo|
119 % \marg{file}.
120 %
121 % Typesets the metainfo of the \TeX\ file \meta{file}. Anything not a
122 % metainfo---text, preamble---is skipped.
123 %
124 %
125 %
126 %
127 % \section{Formatting}
128 %
129 % \subsection{Metainfo after a heading}
130 %
131 % Any comments following a line with a heading are considered a
132 % metainfo and are typeset as if they were normal text. The first line
133 % that does not begin with a percent sign finishes the metainfo.
134 %
135 % A heading is started by a macro defined in |\\mi@@MIbeginnings|.
136 % Normally this macro contains |\chapter|, |\section|, |\subsection|,
137 % and |\subsubsection|, but you can of course redefine it.
138 %
139 % The heading itself is typeset as well, before the metainfo,
140 % resulting all metainfo being typeset using the outline of the normal
141 % document. Note that when writing a heading, some restriction apply:
142 %
143 % \begin{enumerate}
144 % \item The heading macro must be at the beginning of the line.
145 %
146 % \item Any parameters of the macro must be on the same line.
147 % (parameters split over several lines might work, but they
148 % are not guaranteed to)
149 %
150 % \end{enumerate}
151 %
152 %
153 %
154 %
155 % \subsection{Local metainfo}
156 %
157 % There is another way to include metainfo in a document, that is as a
158 % \emph{local metainfo}. A local metainfo is a metainfo not following
159 % a heading; instead they can appear anywhere in the text. They start
160 % with a double percent sign at the beginning of the line (|%%|); the
161 % line itself is then typeset as a metainfo as well as all the
162 % following lines beginning with a |%| (just as a metainfo following a
163 % heading). The first line that does not begin with a percent sign
164 % finishes the local metainfo.
165 %
166 % You can format a local metainfo using three macros. (see section
167 % \ref{sec:ExLoMI} on page \pageref{sec:ExLoMI} for an example how to
168 % customize them.)
169 %
170 % \begin{enumerate}
171 % \item |\mi@@firstlocalMItext|: The contents of this macro is
172 % inserted before the first local metainfo of a chapter.
173 %
174 % \item |\mi@@lastlocalMItext|: The contents of this macro is
175 % inserted after the last local metainfo of a chapter.
176 %
177 % \item |\mi@@everylocalMItext|: The contents of this macro is
178 % inserted before every local metainfo.
179 %
180 % \end{enumerate}
181 %
182 % \paragraph{Note} If you change these macros in your document
183 % preamble or your main document opposed to a package file, you must
184 % surround them with |\makeatletter| and |\makeatother|, as shown in
185 % the example below.
186 %
187 %
188 %
189 %
190 % \section{Package options}\label{sec:Options}
191 %
192 % The following package options exist:
193 %
194 % \begin{description}
195 % \item[compactheadings] Changes the section headings to be more
196 % compact in order to save some space.
197 %
198 % \item[indexshorthand] Provides shorthands for indexing.
199 % |^|\marg{text} indexes and typesets \meta{text}, |^^|\marg{text}
200 % only indexes it.\footnote{These shorthands have been inspired by
201 % Donald E. Knuth's own index macros used for the \TeX book.}
202 % For indexing, the standard index macro |\index| is used.
203 %
204 % These macros only work in text mode; in math mode, |^| is a
205 % superscript as predefined in \LaTeX.
206 %
207 % \item[listlocalmetainfo] Changes the macros |\mi@@firstlocalMItext|,
208 % |\mi@@lastlocalMItext| and |\mi@@everylocalMItext| (described in
209 % the section above) to |itemize| the local metainfo.
210 % \end{description}
211 %
212 %
213 %
214 %
215 % \section{Driver files}
216 %
217 % In order to typeset only the metainfo of a document, a special
218 % driver file is needed. This driver loads the packages necessary for
219 % typesetting the metainfo (at least the package \textsf{metainfo})
220 % and inputs the document to be typeset using |\typesetmetainfo|.
221 %
222 % \paragraph{Note} No package of the document processed using
223 % |\typesetmetainfo| is loaded, as the |\usepackage| macros are
224 % skipped. The same is true for any definitions in the document
225 % preamble or elsewhere: They are skipped, so if the metainfo relies
226 % on these definitions, they have to be included in the driver as
227 % well.
228 %
229 %
230 %
231 %
232 % \section{Examples}
233 %
234 % \subsection{Example driver file}
235 %
236 % The following driver file typesets the metainfo of the \TeX\ file
237 % `example.tex' using compact headings:
238 %
239 % \begin{verbatim}
240 % \documentclass{book}
241 % \usepackage[compactheadings]{metainfo}
242 %
243 % \begin{document}
244 % \typesetmetainfo{example}
245 % \end{document}
246 % \end{verbatim}
247 %
248 %
249 %
250 %
251 % \subsection{Example document}
252 %
253 % If we save the following file as `example.tex' and process it using
254 % the driver file in the example above \ldots
255 %
256 % \begin{verbatim}
257 % \documentclass{minimal}
258 % \usepackage{testpackage}
259 %
260 % \begin{document}
261 %
262 % \chapter{Chapter 1}
263 % % Metainfo for chapter `Chapter 1'
264 %
265 % \section{Section 1}
266 % % Metainfo for section `Section 1'
267 %
268 % This is some text.
269 %
270 % \chapter{Chapter 2}
271 % \section{Section 2}
272 % % Metainfo for section `Section 2'
273 %
274 % This is some more text.
275 %
276 % %% Local metainfo. This metainfo is a bit longer, but only
277 % % a little bit.
278 %
279 % \section{Section 3}
280 % % Metainfo for section `Section 3'
281 % \end{document}
282 % \end{verbatim}
283 %
284 % \ldots\ this results in:\footnote{Approximately, as the real
285 % formatting will differ slightly from the text typeset here.}
286 %
287 % \addvspace{\baselineskip}
288 % \textbf{Chapter 1}\par
289 % Metainfo for chapter `Chapter 1'
290 %
291 % \addvspace{\baselineskip}
292 % \textbf{Section 1}\par
293 % Metainfo for section `Section 1'
294 %
295 % \addvspace{\baselineskip}
296 % \textbf{Chapter 2}\par
297 % \textbf{Section 2}\par
298 % Metainfo for section `Section 2'
299 %
300 % \addvspace{\baselineskip}
301 % Annotations:\par
302 % Local metainfo. This metainfo is a bit longer, but only a little
303 % bit.
304 %
305 % \addvspace{\baselineskip}
306 % \textbf{Section 3}\par
307 % Metainfo for section `Section 3'
308 %
309 %
310 %
311 %
312 % \subsection{Example local metainfo formatting}\label{sec:ExLoMI}
313 %
314 % The following macros prefix local metainfo with `Annotations:' in
315 % bold typeface and typesets the local metainfo in an |itemize|
316 % environment:\footnote{Similar to the package option
317 % \texttt{listlocalmetainfo}, described in section \ref{sec:Options}
318 % on page \pageref{sec:Options} does.}
319 %
320 % \begin{verbatim}
321 % \makeatletter
322 % \def\mi@@firstlocalMItext{%
323 % \addvspace{\baselineskip}%
324 % \noindent\textbf{Annotations:}%
325 % \begin{itemize}%
326 % }
327 % \def\mi@@lastlocalMItext{%
328 % \end{itemize}%
329 % }
330 % \def\mi@@everylocalMItext{%
331 % \item\relax%
332 % }
333 % \makeatother
334 % \end{verbatim}
335 %
336 %
337 %
338 %
339 % \section{Notes/Limitations}
340 %
341 % \begin{itemize}
342 % \item Any text or macros on the same line as a heading are
343 % processed as well, immediately after the heading. Thus
344 % you can type |\section{foo}\label{sec:foo}| and refer
345 % to this section inside a metainfo using the label
346 % |sec:foo|.
347 %
348 % \item The document included using |\typesetmetainfo| must
349 % be a valid \LaTeX\ document insofar as that it must
350 % contain a |document| environment, because |\end{document}|
351 % serves as the ending delimiter for typesetting the
352 % metainfo.
353 %
354 % That also means that any metainfo following |\end{document}|
355 % is \emph{not} typeset.
356 %
357 % \end{itemize}
358 %
359 %
360 %
361 %
362 % \StopEventually{}
363 %
364 % \section{Implementation}
365 %
366 % \subsection{Main environments and macros}
367 %
368 % \begin{macro}{\typesetmetainfo}
369 %
370 % Usage: |\typesetmetainfo| \marg{file}.
371 %
372 % Typesets the metainfo of a document.
373 %
374 % \begin{macrocode}
375 \newcommand{\typesetmetainfo}[1]{%
376 \bgroup%
377 \mi@activenewline%
378 \mi@emptyactivepercent%
379 \mi@otherbraces%
380 \ifmi@indexmacros\mi@activehat\fi%
381 % \end{macrocode}
382 %
383 % We provide support for the standard \LaTeX\ |verbatim| environment:
384 %
385 % \begin{macrocode}
386 \let\mi@old@verbatim\@verbatim%
387 \def\@verbatim{%
388 \mi@old@verbatim%
389 \mi@verbatimnewline%
390 }%
391 % \end{macrocode}
392 %
393 % We use the original \TeX\ definition of |\input| (saved by \LaTeX\
394 % in |\@@input|), because we must continue with our special processing
395 % immediately after \meta{file} has been opened. This is a job for the
396 % original \TeX\ |\input|, as it simply switches the input stream to
397 % \meta{file} and expands to nothing.
398 %
399 % The |\relax| delimits the filename.
400 %
401 % \begin{macrocode}
402 \expandafter\mi@skiplines\@@input#1\relax%
403 \egroup%
404 }
405 % \end{macrocode}
406 % \end{macro}
407 %
408 %
409 %
410 %
411 % \subsection{Package customization}
412 %
413 % \begin{macro}{\mi@@MIbeginnings}
414 %
415 % Stores all the macros that can begin a metainfo.
416 %
417 % \begin{macrocode}
418 \def\mi@@MIbeginnings{\chapter\section\subsection\subsubsection}
419 % \end{macrocode}
420 % \end{macro}
421 %
422 %
423 % \begin{macro}{\mi@@firstlocalMItext}
424 %
425 % Stores the text inserted before the first local metainfo.
426 %
427 % \begin{macrocode}
428 \def\mi@@firstlocalMItext{\textbf{Annotations:}\par\noindent}
429 % \end{macrocode}
430 % \end{macro}
431 %
432 %
433 % \begin{macro}{\mi@@lastlocalMItext}
434 %
435 % Stores the text inserted after the last local metainfo.
436 %
437 % \begin{macrocode}
438 \def\mi@@lastlocalMItext{}
439 % \end{macrocode}
440 % \end{macro}
441 %
442 %
443 % \begin{macro}{\mi@@everylocalMItext}
444 %
445 % Stores the text inserted before every local metainfo.
446 %
447 % \begin{macrocode}
448 \def\mi@@everylocalMItext{}
449 % \end{macrocode}
450 % \end{macro}
451 %
452 %
453 %
454 %
455 % \subsection{Package options}
456 %
457 % \subsubsection{Headings}
458 %
459 % We provide the possibility of changing the headings to a more
460 % compact formatting:
461 %
462 % \begin{macrocode}
463 \DeclareOption{compactheadings}{%
464 \@ifundefined{thechapter}{}{%
465 \def\chapter{\@startsection{chapter}{0}{\z@}{-2\baselineskip}%
466 {\baselineskip}{\normalfont\normalsize\bfseries}}%
467 }%
468 \def\section{\@startsection{section}{1}{\z@}{-2\baselineskip}%
469 {\baselineskip}{\normalfont\normalsize\bfseries}}%
470 \def\subsection{\@startsection{subsection}{2}{\z@}{-2\baselineskip}%
471 {\baselineskip}{\normalfont\normalsize\bfseries}}%
472 \def\subsubsection{\@startsection{subsubsection}{3}{\z@}%
473 {-2\baselineskip}{\baselineskip}%
474 {\normalfont\normalsize\bfseries}}%
475 }
476 % \end{macrocode}
477 %
478 %
479 %
480 %
481 % \subsubsection{Index shorthand}
482 %
483 % \begin{macro}{\ifmi@indexmacros}
484 %
485 % |true|, if index shorthands specified using the package option
486 % |indexshorthand| are used, otherwise |false|:
487 %
488 % \begin{macrocode}
489 \newif\ifmi@indexmacros
490 \mi@indexmacrosfalse
491 % \end{macrocode}
492 % \end{macro}
493 %
494 % We provide the possibility of using the shorthand |^| for an index
495 % entry that is typeset, and |^^| for an index entry that is not
496 % typeset:
497 %
498 % \begin{macrocode}
499 \DeclareOption{indexshorthand}{%
500 \mi@indexmacrostrue%
501 % \end{macrocode}
502 %
503 %
504 % \begin{macro}{\mi@hat}
505 %
506 % We save the original meaning of |^|. We do not simply use |^| in the
507 % |\mi@hat|\ldots-macros, because then we would assume that |^| is not
508 % already an active character before our catcode change (which we will
509 % make in |\typesetmetainfo|). Normally, |^| has catcode 7
510 % (superscript), but if is was active (i.e. because of another package
511 % changing |^|), we would store an active |^| in the definition of the
512 % |\mi@hat|\ldots-macros. When later used this |^| would point to our
513 % macro |\mi@hat|, resulting in an endless loop. So we save the
514 % original meaning of |^| instead using |\let|, which, if |^| is
515 % active, would save the macro |^| would have been |\let| to.
516 %
517 % \begin{macrocode}
518 \let\mi@@@hat^%
519 % \end{macrocode}
520 % \end{macro}
521 %
522 %
523 % \begin{macro}{\mi@hat}
524 %
525 % Main macro for indexing and first step in deciding how to index:
526 %
527 % \begin{itemize}
528 % \item Math mode: Expand to the original definition of |^|.
529 %
530 % \item Otherwise: Check the next token using |\mi@hat@|.
531 %
532 % \end{itemize}
533 %
534 % \begin{macrocode}
535 \def\mi@hat{%
536 \ifmmode%
537 \expandafter\mi@@@hat%
538 \else%
539 \expandafter\futurelet\expandafter\@tempa\expandafter\mi@hat@%
540 \fi%
541 }
542 % \end{macrocode}
543 % \end{macro}
544 %
545 %
546 % \begin{macro}{\mi@hat@}
547 %
548 % Second step in deciding how to index. We know that we are not in
549 % math mode. The token following the hat has been prefetched and
550 % stored in |\@tempa|. (it has not been read yet)
551 %
552 % \begin{itemize}
553 % \item A second hat (|^|): Check the next token using |\mi@hat@twohats|.
554 %
555 % \item Opening brace: Typeset the index word and index it using
556 % it |\mi@indextypeset|.
557 %
558 % \item Otherwise: Display an error, as |^^| must be followed by
559 % a parameter in braces.
560 %
561 % \end{itemize}
562 %
563 % \begin{macrocode}
564 \def\mi@hat@{%
565 \ifx\@tempa\mi@hat%
566 \expandafter\mi@hat@twohats%
567 \else\ifx\@tempa\bgroup%
568 \expandafter\expandafter\expandafter\mi@indextypeset%
569 \else%
570 \mi@hat@errbrace%
571 \fi\fi%
572 }
573 % \end{macrocode}
574 % \end{macro}
575 %
576 %
577 % \begin{macro}{\mi@hat@twohats}
578 %
579 % First step in deciding how to index a word not typeset. We know we
580 % have two hats in a row (|^^|), but the second hat is not read yet
581 % (only prefetched using |\futurelet|). Therefore we gobble it using
582 % |#1|.
583 %
584 % \begin{macrocode}
585 \def\mi@hat@twohats#1{%
586 \futurelet\@tempa\mi@hat@twohats@%
587 }
588 % \end{macrocode}
589 % \end{macro}
590 %
591 %
592 % \begin{macro}{\mi@hat@twohats}
593 %
594 % Second step in deciding how to index a word not typeset. We know we
595 % have two hats in a row, both read. The token following the two hats
596 % has been prefetched and stored in |\@tempa|.
597 %
598 % Note that we could skip this step and simpy expand to |\index|,
599 % letting |\index| take care that a proper parameter follows.
600 %
601 % \begin{macrocode}
602 \def\mi@hat@twohats@{%
603 \ifx\@tempa\bgroup%
604 \expandafter\index%
605 \else%
606 \mi@hat@errbrace%
607 \fi%
608 }
609 % \end{macrocode}
610 % \end{macro}
611 %
612 %
613 % \begin{macro}{\mi@indextypeset}
614 %
615 % Usage: |\mi@indextypeset| \marg{word}. Typesets \meta{word} and
616 % indexes it using |\index|.
617 %
618 % \begin{macrocode}
619 \def\mi@indextypeset#1{%
620 #1\index{#1}%
621 }
622 % \end{macrocode}
623 % \end{macro}
624 %
625 %
626 % \begin{macro}{\mi@hat@errbrace}
627 %
628 % Error handling when a |^| or |^^| is not followed by a left brace.
629 %
630 % \begin{macrocode}
631 \def\mi@hat@errbrace{%
632 \PackageError{metainfo}{`\string^' or `\string^\string^' not %
633 followed by a left brace}\@ehc%
634 }
635 % \end{macrocode}
636 % \end{macro}
637 %
638 %
639 % End of |\DeclareOption{index}|:
640 %
641 % \begin{macrocode}
642 }
643 % \end{macrocode}
644 %
645 %
646 %
647 %
648 % \subsubsection{Other options}
649 %
650 % \begin{macrocode}
651 \DeclareOption{listlocalmetainfo}{%
652 \def\mi@@firstlocalMItext{%
653 \begin{itemize}%
654 }%
655 \def\mi@@lastlocalMItext{%
656 \end{itemize}%
657 }%
658 \def\mi@@everylocalMItext{%
659 \item\relax%
660 }%
661 }
662 % \end{macrocode}
663 %
664 %
665 %
666 %
667 % \begin{macrocode}
668 \ProcessOptions\relax
669 % \end{macrocode}
670 %
671 %
672 %
673 %
674 % \subsection{Internal environments and macros}
675 %
676 % \subsubsection{General definitions and flags}
677 %
678 % \paragraph{Strategy for dealing with catcode changes} At the
679 % beginning of the processing, the catcodes are changed as follows:
680 %
681 % \begin{tabular}{cl}
682 % |^^M| & 13 (active), set in |\mi@activenewline| \\
683 % |%| & 13, set in |\mi@emptyactivepercent| \\
684 % |{| & 12 (other), set in |\mi@otherbraces| \\
685 % |}| & 12, set in |\mi@otherbraces| \\
686 % |^| & 13, optionally set in |\mi@activehat| \\
687 % \end{tabular}
688 %
689 % If any macro changes the catcodes of these characters, it must reset
690 % them to these values after processing. If any macro needs the braces
691 % |{| and |}| for parameter grouping, it should use the macro
692 % |\mi@normalbraces| to change the catcodes accordingly.
693 %
694 %
695 % \begin{macro}{\ifmi@firstlocalMI}
696 %
697 % |true| if this is the first local metainfo, otherwise |false|. Used
698 % to insert |\mi@@firstlocalMItext| and |\mi@@lastlocalMItext|.
699 %
700 % \begin{macrocode}
701 \newif\ifmi@firstlocalMI
702 \mi@firstlocalMItrue
703 % \end{macrocode}
704 % \end{macro}
705 %
706 %
707 %
708 %
709 % \subsubsection{Modes}
710 %
711 % Three modes of processing exist:
712 %
713 % \begin{description}
714 % \item[Skipping text] Text is skipped line after line. If two
715 % percent signs are found at the beginning of a new line,
716 % a local metainfo is begun and the mode changed to
717 % `Typesetting a metainfo'.
718 %
719 % Main macro: |\mi@skiplines|.
720 %
721 % \item[Beginning metainfo] The appropriate heading is typeset
722 % and the remaining line of text skipped. The mode is then
723 % changed to `Typesetting a metainfo'.
724 %
725 % Main macro: |\mi@checkbeginMI|.
726 %
727 % \item[Typesetting a metainfo] The text is typeset. If a line does
728 % not start with a percent sign, the metainfo is done. The
729 % mode is then changed to `Skipping text'.
730 %
731 % Main macro: |\mi@typesetMI|.
732 %
733 % \end{description}
734 %
735 %
736 % \begin{macro}{\mi@skiplines}
737 %
738 % Main macro. Skips lines and checks the first token of a line (stored
739 % in |#1|) for two special cases:
740 %
741 % \begin{enumerate}
742 % \item A percent sign |%|: We check if it starts a local metainfo
743 % using |\mi@checkbeginlocalMI|.
744 %
745 % \item A control sequence: We check if it starts a new metainfo
746 % using |\mi@checkbeginMI|.
747 %
748 % \end{enumerate}
749 %
750 % \begin{macrocode}
751 \def\mi@skiplines#1{%
752 \ifx#1\mi@percentempty%
753 % \end{macrocode}
754 %
755 % A percent sign: We check if it starts a local metainfo.
756 %
757 % \begin{macrocode}
758 \expandafter\mi@checkbeginlocalMI%
759 \else\ifcat\noexpand#1\relax%
760 % \end{macrocode}
761 %
762 % A control sequence: We check if it starts a new metainfo.
763 %
764 % \begin{macrocode}
765 \expandafter\expandafter\expandafter\mi@checkbeginMI%
766 \else%
767 % \end{macrocode}
768 %
769 % Anything else: We skip it and the remaining line of text. Note that
770 % it could be a line ending (|^^M|), so it may be possible that we
771 % gobble only |#1|, which will be re-inserted into the stream below.
772 % That way we do not have to check if |#1| is a line ending.
773 %
774 % \begin{macrocode}
775 \expandafter\expandafter\expandafter\mi@gobbletolineend%
776 \fi\fi%
777 % \end{macrocode}
778 %
779 % We always insert the first token of a line back into the stream,
780 % even though it is not necessary for |\mi@checkbeginlocalMI|. But as
781 % normally most of the lines of a text will be skipped, we optimize
782 % for this case.
783 %
784 % \begin{macrocode}
785 #1%
786 }
787 % \end{macrocode}
788 % \end{macro}
789 %
790 %
791 % The following macros require |^^M| to be active:
792 %
793 % \begin{macrocode}
794 \bgroup
795 \catcode`\^^M=\active%
796 % \end{macrocode}
797 %
798 %
799 % \begin{macro}{\mi@typesetMI}
800 %
801 % Prepares the typesetting of a metainfo.
802 %
803 % \begin{macrocode}
804 \gdef\mi@typesetMI{%
805 \mi@normalbraces%
806 % \end{macrocode}
807 %
808 % Every CR we check if the next line continues the metainfo
809 % using |\mi@typesetMI@checkend|.
810 %
811 % \begin{macrocode}
812 \let^^M\mi@typesetMI@checkend%
813 % \end{macrocode}
814 %
815 % Now we start typesetting the text. We let \TeX\ take completely
816 % control instead of reading one line after the other; we will regain
817 % control at the end of each line using our redefinition of |^^M|.
818 %
819 % \begin{macrocode}
820 \ignorespaces%
821 }
822 % \end{macrocode}
823 % \end{macro}
824 %
825 %
826 % \begin{macro}{\mi@typesetMI@checkend}
827 %
828 % Called at a carriage return. If the token after the CR is equals to
829 % |\mi@percentempty|, the next line starts with a |%|, thus continuing
830 % the metainfo. Otherwise, the metainfo is finished.
831 %
832 % \begin{macrocode}
833 \long\gdef\mi@typesetMI@checkend#1{%
834 \ifx#1\mi@percentempty%
835 % \end{macrocode}
836 %
837 % The next line continues the comment. We check for an empty line:
838 %
839 % \begin{macrocode}
840 \expandafter\mi@typesetMI@checkend@%
841 \else%
842 % \end{macrocode}
843 %
844 % The next line finishes the comment:
845 %
846 % \begin{macrocode}
847 \mi@otherbraces%
848 \let^^M\@empty%
849 \expandafter\mi@skiplines\expandafter#1%
850 \fi%
851 }
852 % \end{macrocode}
853 % \end{macro}
854 %
855 %
856 % \begin{macro}{\mi@typesetMI@checkend@}
857 %
858 % Checks if a |^^M| (CR) follows immediately after the |%|. Then we
859 % insert a |\par|. Note that any spaces between the |%| and the CR
860 % are automatically skipped by using a non-delimited parameter.
861 %
862 % \begin{macrocode}
863 \long\gdef\mi@typesetMI@checkend@#1{%
864 \ifx#1\mi@typesetMI@checkend%
865 \par\expandafter\mi@typesetMI@checkend%
866 \else%
867 % \end{macrocode}
868 %
869 % We assume the line is |% |\meta{text} instead of |%|\meta{text},
870 % thus we insert back a space that was skipped before:
871 %
872 % \begin{macrocode}
873 \space%
874 \expandafter#1%
875 \fi%
876 }
877 % \end{macrocode}
878 % \end{macro}
879 %
880 %
881 % \begin{macro}{\mi@checkbeginMI}
882 %
883 % Usage: |\mi@checkbeginMI|\meta{cs}.
884 %
885 % First step in the check for the begin of a metainfo: Checks if
886 % \meta{cs} is a control sequence that can begin a metainfo.
887 %
888 % \begin{macrocode}
889 \gdef\mi@checkbeginMI#1{%
890 % \end{macrocode}
891 %
892 % Handle |\end|:
893 %
894 % \begin{macrocode}
895 \ifx#1\end%
896 \expandafter\mi@checkdocumentend%
897 \else%
898 % \end{macrocode}
899 %
900 % We check if \meta{cs} is a relevant control sequence. (these are
901 % stored in |\mi@@MIbeginnings|) Then we use |\mi@checkbeginMI@| to
902 % evaluate the result:
903 %
904 % \begin{macrocode}
905 \def\@tempa##1#1##2\@nil{\mi@checkbeginMI@{##2}#1}%
906 \expandafter\expandafter\expandafter\@tempa%
907 \expandafter\mi@@MIbeginnings\expandafter#1%
908 \expandafter\@nil%
909 \fi%
910 }
911 % \end{macrocode}
912 % \end{macro}
913 %
914 %
915 % \begin{macro}{\mi@checkbeginMI@}
916 %
917 % Support macro for |\mi@checkbeginMI|. Checks if |#2| is a relevant
918 % control sequence by checking if |#1| is empty (|false|) or not
919 % (|true|).
920 %
921 % \begin{macrocode}
922 \gdef\mi@checkbeginMI@#1#2{%
923 \ifx^^M#1^^M%
924 % \end{macrocode}
925 %
926 % Not a relevant control sequence: Skip till the end of the line.
927 %
928 % \begin{macrocode}
929 \expandafter\mi@gobbletolineend%
930 \else%
931 % \end{macrocode}
932 %
933 % A relevant control sequence. If there has been any local metainfo
934 % before this macro, we finish it by inserting |\mi@@lastlocalMItext|:
935 %
936 % \begin{macrocode}
937 \ifmi@firstlocalMI\else\mi@@lastlocalMItext\fi%
938 % \end{macrocode}
939 %
940 % We restore all character catcodes except for |^^M|, which we use to
941 % continue processing after the control sequence in question has been
942 % executed: (this is the reason a heading must appear on a single
943 % line, as otherweise |^^M| is executed more than once)
944 %
945 % \begin{macrocode}
946 \let^^M\mi@checkbeginMI@@%
947 \mi@normalbraces%
948 \mi@normalpercent%
949 % \end{macrocode}
950 %
951 % In any case, a local metainfo following this macro is the first, so
952 % we set the flag accordingly:
953 %
954 % \begin{macrocode}
955 \mi@firstlocalMItrue%
956 \expandafter#2%
957 \fi%
958 }
959 % \end{macrocode}
960 % \end{macro}
961 %
962 %
963 % \begin{macro}{\mi@checkbeginMI@@}
964 %
965 % Support macro for |\mi@checkbeginMI@|. Is called via |^^M| at the end
966 % of a line.
967 %
968 % \begin{macrocode}
969 \gdef\mi@checkbeginMI@@{%
970 \let^^M\@empty%
971 \mi@otherbraces%
972 \mi@emptyactivepercent%
973 \mi@checkbeginMI@@@%
974 }
975 % \end{macrocode}
976 % \end{macro}
977 %
978 % \begin{macrocode}
979 \egroup
980 % \end{macrocode}
981 %
982 %
983 % \begin{macro}{\mi@checkbeginMI@@@}
984 %
985 % Support macro for |\mi@checkbeginMI| and the second step in the
986 % check for the begin of a metainfo: Checks if the line after the
987 % control sequence begins with a percent sign.
988 %
989 % \begin{macrocode}
990 \def\mi@checkbeginMI@@@#1{%
991 \ifx#1\mi@percentempty%
992 % \end{macrocode}
993 %
994 % A percent sign: It starts a metainfo. Change to metainfo.
995 %
996 % \begin{macrocode}
997 \par%
998 \expandafter\mi@typesetMI%
999 \else%
1000 % \end{macrocode}
1001 %
1002 % Anything else: No metainfo follows. Ignore it.
1003 %
1004 % \begin{macrocode}
1005 \expandafter\mi@skiplines\expandafter#1%
1006 \fi%
1007 }
1008 % \end{macrocode}
1009 % \end{macro}
1010 %
1011 %
1012 % \begin{macro}{\mi@checkbeginlocalMI}
1013 %
1014 % Usage: |\mi@checkbeginlocalMI|\meta{dummy}\meta{next token}.
1015 %
1016 % \meta{dummy} is the result of an optimization of |\mi@skiplines|.
1017 % (see above)
1018 %
1019 % \begin{macrocode}
1020 \def\mi@checkbeginlocalMI#1#2{%
1021 \ifx#2\mi@percentempty%
1022 % \end{macrocode}
1023 %
1024 % A percent sign: It starts a local metainfo. Change to metainfo.
1025 %
1026 % \begin{macrocode}
1027 \par%
1028 \ifmi@firstlocalMI\mi@@firstlocalMItext\fi%
1029 \mi@@everylocalMItext%
1030 % \end{macrocode}
1031 %
1032 % We have begun to typeset the local metainfo, therefore we take note
1033 % that any local metainfo following this one is not the first.
1034 %
1035 % \begin{macrocode}
1036 \mi@firstlocalMIfalse%
1037 \expandafter\mi@typesetMI%
1038 \else%
1039 % \end{macrocode}
1040 %
1041 % Anything else: No, it is just a simple comment. Ignore it.
1042 %
1043 % \begin{macrocode}
1044 \expandafter\mi@gobbletolineend\expandafter#2%
1045 \fi%
1046 }
1047 % \end{macrocode}
1048 % \end{macro}
1049 %
1050 %
1051 % \begin{macro}{\mi@checkdocumentend}
1052 %
1053 % Checks if the |\end| just read ends the |document| environment.
1054 %
1055 % \begin{macrocode}
1056 \def\mi@checkdocumentend{%
1057 % \end{macrocode}
1058 %
1059 % We change the catcodes of braces back to normal in order to get the
1060 % name of the environment as the only parameter of |\mi@checkdocumentend@|
1061 % and not only the opening brace.
1062 %
1063 % \begin{macrocode}
1064 \mi@normalbraces%
1065 \mi@checkdocumentend@%
1066 }
1067 % \end{macrocode}
1068 % \end{macro}
1069 %
1070 %
1071 % \begin{macro}{\mi@checkdocumentend@}
1072 %
1073 % Support macro for |\mi@checkdocumentend|.
1074 %
1075 % \begin{macrocode}
1076 \def\mi@checkdocumentend@#1{%
1077 \def\@tempa{#1}%
1078 \ifx\@tempa\mi@textdocument%
1079 % \end{macrocode}
1080 %
1081 % If there has been any local metainfo before this macro, we finish it
1082 % by inserting |\mi@@lastlocalMItext|:
1083 %
1084 % \begin{macrocode}
1085 \ifmi@firstlocalMI\else\mi@@lastlocalMItext\fi%
1086 \expandafter\mi@gobbletolineend@any\expandafter\endinput%
1087 \else%
1088 % \end{macrocode}
1089 %
1090 % As are not done yet, we better set the catcode of braces to
1091 % `letter':
1092 %
1093 % \begin{macrocode}
1094 \mi@otherbraces%
1095 \expandafter\mi@skiplines%
1096 \fi%
1097 }
1098 % \end{macrocode}
1099 % \end{macro}
1100 %
1101 %
1102 % \begin{macro}{\mi@textdocument}
1103 %
1104 % The text `document' for |\mi@checkdocumentend|.
1105 %
1106 % \begin{macrocode}
1107 \def\mi@textdocument{document}
1108 % \end{macrocode}
1109 % \end{macro}
1110 %
1111 %
1112 %
1113 % \begin{macro}{\mi@percentempty}
1114 %
1115 % \begin{macrocode}
1116 \def\mi@percentempty{\@empty}
1117 % \end{macrocode}
1118 % \end{macro}
1119 %
1120 %
1121 %
1122 %
1123 % \subsubsection{Gobbling text}
1124 %
1125 % \begin{macrocode}
1126 \bgroup
1127 \catcode`\^^M=\active%
1128 % \end{macrocode}
1129 %
1130 %
1131 % \begin{macro}{\mi@gobbletolineend}
1132 %
1133 % Gobbles up any text till the end of the line. Continues with
1134 % |\mi@skiplines|. (specialization of |\mi@gobbletolineend@any|)
1135 %
1136 % \begin{macrocode}
1137 \gdef\mi@gobbletolineend{%
1138 \mi@gobbletolineend@any\mi@skiplines%
1139 }
1140 % \end{macrocode}
1141 % \end{macro}
1142 %
1143 %
1144 % \begin{macro}{\mi@gobbletolineend@any}
1145 %
1146 % Usage: |\mi@gobbletolineend@any| \marg{macro}.
1147 %
1148 % Gobbles up any text till the end of the line. Continues with
1149 % \meta{macro}. The macro is |long| in case the line (stored in |#2|)
1150 % contains a |\par|.
1151 %
1152 % \begin{macrocode}
1153 \long\gdef\mi@gobbletolineend@any#1#2^^M{%
1154 #1%
1155 }
1156 \egroup
1157 % \end{macrocode}
1158 % \end{macro}
1159 %
1160 %
1161 %
1162 % \subsubsection{Catcode changes}
1163 %
1164 % We define the macros for changing catcodes:
1165 %
1166 % \begin{macro}{\mi@activenewline}
1167 % \begin{macro}{\mi@verbatimnewline}
1168 % \begin{macro}{\mi@emptyactivepercent}
1169 % \begin{macro}{\mi@activehat}
1170 %
1171 % \begin{macrocode}
1172 \bgroup
1173 % \end{macrocode}
1174 %
1175 % We use \verb+|+ as the comment character as we make |%| active:
1176 %
1177 % \begin{macrocode}
1178 \catcode`\|=14 %
1179 \catcode`\^^M=\active%
1180 \catcode`\%=\active|
1181 \gdef\mi@activenewline{|
1182 \catcode`\^^M=\active|
1183 \let^^M\@empty|
1184 }|
1185 \gdef\mi@verbatimnewline{|
1186 \catcode`\^^M=\active|
1187 \def^^M{\par\@gobbletwo}|
1188 }|
1189 \gdef\mi@emptyactivepercent{|
1190 \catcode`\%=\active|
1191 \let%\mi@percentempty|
1192 }|
1193 \catcode`\^=\active|
1194 \gdef\mi@activehat{|
1195 \catcode`\^\active|
1196 \let^\mi@hat|
1197 }|
1198 \egroup
1199 % \end{macrocode}
1200 % \end{macro}
1201 % \end{macro}
1202 % \end{macro}
1203 % \end{macro}
1204 %
1205 %
1206 % \begin{macro}{\mi@normalpercent}
1207 %
1208 % \begin{macrocode}
1209 \def\mi@normalpercent{%
1210 \catcode`\%=14 %
1211 }
1212 % \end{macrocode}
1213 % \end{macro}
1214 %
1215 %
1216 % \begin{macro}{\mi@otherbraces}
1217 %
1218 % \begin{macrocode}
1219 \def\mi@otherbraces{%
1220 \catcode`\{=12 %
1221 \catcode`\}=12 %
1222 }
1223 % \end{macrocode}
1224 % \end{macro}
1225 %
1226 %
1227 % \begin{macro}{\mi@normalbraces}
1228 %
1229 % \begin{macrocode}
1230 \def\mi@normalbraces{%
1231 \catcode`\{=1 %
1232 \catcode`\}=2 %
1233 }
1234 % \end{macrocode}
1235 % \end{macro}
1236 %
1237 %
1238 %
1239 % \Finale
1240 % \PrintChanges
1241 % \PrintIndex
1242 \endinput