3 % $Id: footnote.dtx,v 1.1 2002/02/03 20:49:03 mdw Exp $
5 % Save footnotes around boxing environments and things
7 % (c) 1996 Mark Wooding
9 %----- Revision history -----------------------------------------------------
11 % $Log: footnote.dtx,v $
12 % Revision 1.1 2002/02/03 20:49:03 mdw
13 % Checkin for new build system.
15 % Revision 1.13 1997/01/28 19:45:16 mdw
16 % Fixed stupid bug in AMS environment handling which stops the thing from
17 % working properly if you haven't included amsmath. Doh.
19 % Revision 1.12 1997/01/18 00:45:37 mdw
20 % Fix problems with duplicated footnotes in broken AMS environments which
21 % typeset things multiple times. This is a nasty kludge.
23 % Revision 1.11 1996/11/19 20:50:05 mdw
29 % \begin{meta-comment} <general public licence>
31 %% footnote package -- Save footnotes around boxing environments
32 %% Copyright (c) 1996 Mark Wooding
35 %% This program is free software; you can redistribute it and/or modify
36 %% it under the terms of the GNU General Public License as published by
37 %% the Free Software Foundation; either version 2 of the License, or
38 %% (at your option) any later version.
40 %% This program is distributed in the hope that it will be useful,
41 %% but WITHOUT ANY WARRANTY; without even the implied warranty of
42 %% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
43 %% GNU General Public License for more details.
45 %% You should have received a copy of the GNU General Public License
46 %% along with this program; if not, write to the Free Software
47 %% Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
52 % \begin{meta-comment} <Package preamble>
53 %<+package>\NeedsTeXFormat{LaTeX2e}
54 %<+package>\ProvidesPackage{footnote}
55 %<+package> [1997/01/28 1.13 Save footnotes around boxes]
63 %% {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
64 %% 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
65 %% Digits \0\1\2\3\4\5\6\7\8\9
66 %% Exclamation \! Double quote \" Hash (number) \#
67 %% Dollar \$ Percent \% Ampersand \&
68 %% Acute accent \' Left paren \( Right paren \)
69 %% Asterisk \* Plus \+ Comma \,
70 %% Minus \- Point \. Solidus \/
71 %% Colon \: Semicolon \; Less than \<
72 %% Equals \= Greater than \> Question mark \?
73 %% Commercial at \@ Left bracket \[ Backslash \\
74 %% Right bracket \] Circumflex \^ Underscore \_
75 %% Grave accent \` Left brace \{ Vertical bar \|
76 %% Right brace \} Tilde \~}
82 % \begin{meta-comment} <driver>
86 \describespackage{footnote}
92 % \section{User guide}
94 % This package provides some commands for handling footnotes slightly
95 % better than \LaTeX\ usually does; there are several commands and
96 % environments (notably |\parbox|, \env{minipage} and \env{tabular}
98 % The \package{mdwtab} package, provided in this distribution, handles
99 % footnotes correctly anyway; it uses an internal version of this package
102 % which `trap' footnotes so that they can't escape and appear at the bottom
105 % \DescribeEnv{savenotes}
106 % The \env{savenotes} environment saves up any footnotes encountered within
107 % it, and performs them all at the end.
109 % \DescribeMacro{\savenotes}
110 % \DescribeMacro{\spewnotes}
111 % If you're defining a command or environment, you can use the |\savenotes|
112 % command to start saving up footnotes, and the |\spewnotes| command to
113 % execute them all at the end. Note that |\savenotes| and |\spewnotes|
114 % enclose a group, so watch out. You can safely nest the commands and
115 % environments -- they work out if they're already working and behave
118 % \DescribeEnv{minipage*}
119 % To help things along a bit, the package provides a $*$-version of the
120 % \env{minipage} environment, which doesn't trap footnotes for itself (and
121 % in fact sends any footnotes it contains to the bottom of the page, where
124 % \DescribeMacro{\makesavenoteenv}
125 % The new \env{minipage$*$} environment was created with a magic command
126 % called |\makesavenoteenv|. It has a fairly simple syntax:
129 % <make-save-note-env-cmd> ::= \[[
130 % "\\makesavenoteenv"
131 % \begin{stack} \\ "[" <new-env-name> "]" \end{stack}
136 % Without the optional argument, it redefines the named environment so that
137 % it handles footnotes correctly. With the optional argument, it makes
138 % the new environment named by \<new-env-name> into a footnote-friendly
139 % version of the \<env-name> environment.
141 % \DescribeMacro{\parbox}
142 % The package also redefines the |\parbox| command so that it works properly
145 % \DescribeEnv{footnote}
146 % The other problem which people tend to experience with footnotes is that
147 % you can't put verbatim text (with the |\verb| comamnd or the \env{verbatim}
148 % environment) into the |\footnote| command's argument. This package
149 % provides a \env{footnote} \emph{environment}, which \emph{does} allow
150 % verbatim things. You use the environment just like you do the command.
151 % It's really easy. It even has an optional argument, which works the same
154 % \DescribeEnv{footnotetext}
155 % To go with the \env{footnote} environment, there's a \env{footnotetext}
156 % environment, which just puts the text in the bottom of the page, like
157 % |\footnotetext| does.
159 % There's a snag with these environments, though. Some other nonstandard
160 % environments, like \env{tabularx}, try to handle footnotes their own
161 % way, because they won't work otherwise. The way they do this is not
162 % compatible with the way that the \env{footnote} and \env{footnotetext}
163 % environments work, and you will get strange results if you try (there'll
164 % be odd vertical spacing, and the footnote text may well be incorrect).
166 % The solution to this problem is to send mail to David Carlisle persuading
167 % him to use this package to handle footnotes, rather than doing it his
173 % \section{Implementation}
175 % Most implementations of footnote-saving (in particular, that used in
176 % the \package{tabularx} and \package{longtable} packages) use a token
177 % list register to store the footnote text, and then expand it when whatever
178 % was preventing footnotes (usually a vbox) stops. This is no good at all
179 % if the footnotes contain things which might not be there by the time the
180 % expansion occurs. For example, references to things in temporary boxes
183 % This implementation therefore stores the footnotes up in a box register.
184 % This must be just as valid as using tokens, because all I'm going to do
185 % at the end is unbox the box).
189 \ifx\fn@notes\@@undefined%
194 % I'll need a length to tell me how wide the footnotes should be at the
201 % Of course, I can't set this up until I actually start saving footnotes.
202 % Until then I'll use |\columnwidth| (which works in \package{multicol}
203 % even though it doesn't have any right to).
206 \let\fn@colwidth\columnwidth
209 % And now a switch to remember if we're already handling footnotes,
212 \newif\if@savingnotes
216 % \subsection{Building footnote text}
218 % I need to emulate \LaTeX's footnote handling when I'm putting the notes
219 % into my box; this is also useful in the verbatim-in-footnotes stuff.
221 % \begin{macro}{\fn@startnote}
223 % Here's how a footnote gets started. Most of the code here is stolen
224 % from |\@footnotetext|.
229 \interlinepenalty\interfootnotelinepenalty%
230 \reset@font\footnotesize%
231 \floatingpenalty\@MM% Is this right???
233 \protected@edef\@currentlabel{\csname p@\@mpfn\endcsname\@thefnmark}%
240 % \begin{macro}{\fn@endnote}
242 % Footnotes are finished off by this macro. This is the easy bit.
245 \let\fn@endnote\color@endgroup
251 % \subsection{Footnote saving}
253 % \begin{macro}{\fn@fntext}
255 % Now to define how to actually do footnotes. I'll just add the notes to
256 % the bottom of the footnote box I'm building.
258 % There's some hacking added here to handle the case that a footnote is
259 % in an |\intertext| command within a broken \package{amsmath} alignment
260 % environment -- otherwise the footnotes get duplicated due to the way that
261 % that package measures equations.
263 % The correct solution of course is to
264 % implement aligning environments in a sensible way, by building the table
265 % and leaving penalties describing the intended format, and then pick that
266 % apart in a postprocessing phase. If I get the time, I'll start working
267 % on this again. I have a design worked out and the beginnings of an
268 % implementation, but it's going to be a long time coming.
273 \ifx\ifmeasuring@\@@undefined%
274 \expandafter\@secondoftwo\else\expandafter\@iden%
276 {\ifmeasuring@\expandafter\@gobble\else\expandafter\@iden\fi}%
278 \global\setbox\fn@notes\vbox{%
282 \rule\z@\footnotesep%
285 \@finalstrut\strutbox%
295 % \begin{macro}{\savenotes}
297 % The |\savenotes| declaration starts saving footnotes, to be spewed at a
298 % later date. We'll also remember which counter we're meant to use, and
299 % redefine the footnotes used by minipages.
301 % The idea here is that we'll gather up footnotes within the environment,
302 % and output them in whatever format they were being typeset outside the
305 % I'll take this a bit at a time. The start is easy: we need a group in
306 % which to keep our local definitions.
313 % Now, if I'm already saving footnotes away, I won't bother doing anything
314 % here. Otherwise I need to start hacking, and set the switch.
317 \if@savingnotes\else%
321 % I redefine the |\@footnotetext| command, which is responsible for adding
322 % a footnote to the appropriate insert. I'll redefine both the current
323 % version, and \env{minipage}'s specific version, in case there's a nested
327 \let\@footnotetext\fn@fntext%
328 \let\@mpfootnotetext\fn@fntext%
331 % I'd better make sure my box is empty before I start, and I must set up
332 % the column width so that later changes (e.g., in \env{minipage}) don't
333 % upset things too much.
336 \fn@width\columnwidth%
337 \let\fn@colwidth\fn@width%
338 \global\setbox\fn@notes\box\voidb@x%
341 % Now for some yuckiness. I want to ensure that \env{minipage} doesn't
342 % change how footnotes are handled once I've taken charge. I'll store the
343 % current values of |\thempfn| (which typesets a footnote marker) and
344 % |\@mpfn| (which contains the name of the current footnote counter).
347 \let\fn@thempfn\thempfn%
351 % The \env{minipage} environment provides a hook, called |\@minipagerestore|.
352 % Initially it's set to |\relax|, which is unfortunately unexpandable, so if
353 % I want to add code to it, I must check this possibility. I'll make it
354 % |\@empty| (which expands to nothing) if it's still |\relax|. Then I'll
355 % add my code to the hook, to override |\thempfn| and |\@mpfn| set up by
358 % Note that I can't just force the |mpfootnote| counter to be equal to
359 % the |footnote| one, because \env{minipage} clears |\c@mpfootnote| to zero
360 % when it starts. This method will ensure that even so, the current counter
364 \ifx\@minipagerestore\relax\let\@minipagerestore\@empty\fi%
365 \expandafter\def\expandafter\@minipagerestore\expandafter{%
367 \let\thempfn\fn@thempfn%
376 % \begin{macro}{\spewnotes}
378 % Now I can spew out the notes we saved. This is a bit messy, actually.
379 % Since the standard |\@footnotetext| implementation tries to insert funny
380 % struts and things, I must be a bit careful. I'll disable all this bits
381 % which start paragraphs prematurely.
386 \if@savingnotes\else\ifvoid\fn@notes\else\begingroup%
387 \let\@makefntext\@empty%
388 \let\@finalstrut\@gobble%
389 \let\rule\@gobbletwo%
390 \@footnotetext{\unvbox\fn@notes}%
397 % Now make an environment, for users.
400 \let\endsavenotes\spewnotes
403 % That's all that needs to be in the shared code section.
411 % \subsection{The \env{footnote} environment}
413 % Since |\footnote| is a command with an argument, things like \env{verbatim}
414 % are unwelcome in it. Every so often someone on |comp.text.tex| moans
415 % about it and I post a nasty hack to make it work. However, as a more
416 % permanent and `official' solution, here's an environment which does the
417 % job rather better. Lots of this is based on code from my latest attempt
420 % I'll work on this in a funny order, although I think it's easier to
421 % understand. First, I'll do some macros for reading the optional argument
422 % of footnote-related commands.
424 % \begin{macro}{\fn@getmark}
426 % Saying \syntax{"\\fn@getmark{"<default-code>"}{"<cont-code>"}"} will read
427 % an optional argument giving a value for the footnote counter; if the
428 % argument isn't there, the \<default-code> is executed, and it's expected
429 % to set up the appropriate counter to the current value. The footnote
430 % marker text is stored in the macro |\@thefnmark|, as is conventional for
431 % \LaTeX's footnote handling macros. Once this is done properly, the
432 % \<cont-code> is called to continue handling things.
434 % Since the handling of the optional argument plays with the footnote
435 % counter locally, I'll start a group right now to save some code. Then I'll
436 % decide what to do based on the presence of the argument.
439 \def\fn@getmark#1#2{%
443 {#1\fn@getmark@ii{#2}}%
447 % There's an optional argument, so I need to read it and assign it to the
451 \def\fn@getmark@i#1[#2]{%
452 \csname c@\@mpfn\endcsname#2%
457 % Finally, set up the macro properly, and end the group.
460 \def\fn@getmark@ii#1{%
461 \unrestored@protected@xdef\@thefnmark{\thempfn}%
469 % From argument reading, I'll move on to footnote typesetting.
471 % \begin{macro}{\fn@startfntext}
473 % The |\fn@startfntext| macro sets everything up for building the footnote
474 % in a box register, ready for unboxing into the footnotes insert. The
475 % |\fn@prefntext| macro is a style hook I'll set up later.
478 \def\fn@startfntext{%
479 \setbox\z@\vbox\bgroup%
482 \rule\z@\footnotesep%
489 % \begin{macro}{\fn@endfntext}
491 % Now I'll end the vbox, and add it to the footnote insertion. Again, I
492 % must be careful to prevent |\@footnotetext| from adding horizontal mode
493 % things in bad places.
497 \@finalstrut\strutbox%
501 \let\@makefntext\@empty%
502 \let\@finalstrut\@gobble%
503 \let\rule\@gobbletwo%
504 \@footnotetext{\unvbox\z@}%
511 % \begin{environment}{footnote}
513 % I can now start on the environment proper. First I'll look for an
520 % Oh. I've already come up against the first problem: that name's already
521 % used. I'd better save the original version.
524 \let\fn@latex@@footnote\footnote
527 % The best way I can think of for seeing if I'm in an environment is to
528 % look at |\@currenvir|. I'll need something to compare with, then.
531 \def\fn@footnote{footnote}
534 % Now to start properly. |;-)|
538 \ifx\@currenvir\fn@footnote%
539 \expandafter\@firstoftwo%
541 \expandafter\@secondoftwo%
543 {\fn@getmark{\stepcounter\@mpfn}%
544 {\leavevmode\unskip\@footnotemark\fn@startfntext}}%
545 {\fn@latex@@footnote}%
549 % Ending the environment is simple.
552 \let\endfootnote\fn@endfntext
557 % \begin{environment}{footnotetext}
559 % I'll do the same magic as before for |\footnotetext|.
562 \def\fn@footnotetext{footnotetext}
563 \let\fn@latex@@footnotetext\footnotetext
565 \ifx\@currenvir\fn@footnotetext%
566 \expandafter\@firstoftwo%
568 \expandafter\@secondoftwo%
570 {\fn@getmark{}\fn@startfntext}%
571 {\fn@latex@@footnotetext}%
573 \let\endfootnotetext\endfootnote
578 % \begin{macro}{\fn@prefntext}
579 % \begin{macro}{\fn@postfntext}
581 % Now for one final problem. The style hook for footnotes is the command
582 % |\@makefntext|, which takes the footnote text as its argument. Clearly
583 % this is utterly unsuitable, so I need to split it into two bits, where
584 % the argument is. This is very tricky, and doesn't deserve to work,
585 % although it appears to be a good deal more effective than it has any right
589 \long\def\@tempa#1\@@#2\@@@{\def\fn@prefntext{#1}\def\fn@postfntext{#2}}
590 \expandafter\@tempa\@makefntext\@@\@@@
597 % \subsection{Hacking existing environments}
599 % Some existing \LaTeX\ environments ought to have footnote handling but
600 % don't. Now's our chance.
602 % \begin{macro}{\makesavenoteenv}
604 % The |\makesavenoteenv| command makes an environment save footnotes around
607 % It would also be nice to make |\parbox| work with footnotes. I'll do this
611 \def\makesavenoteenv{\@ifnextchar[\fn@msne@ii\fn@msne@i}
614 % We're meant to redefine the environment. We'll copy it (using |\let|) to
615 % a magic name, and then pass it on to stage~2.
619 \expandafter\let\csname msne$#1\expandafter\endcsname%
620 \csname #1\endcsname%
621 \expandafter\let\csname endmsne$#1\expandafter\endcsname%
622 \csname end#1\endcsname%
623 \fn@msne@ii[#1]{msne$#1}%
627 % Now we'll define the new environment. The start is really easy, since we
628 % just need to insert a |\savenotes|. The end is more complex, since we
629 % need to preserve the |\if@endpe| flag so that |\end| can pick it up. I
630 % reckon that proper hooks should be added to |\begin| and |\end| so that
631 % environments can define things to be done outside the main group as
632 % well as within it; still, we can't all have what we want, can we?
635 \def\fn@msne@ii[#1]#2{%
636 \expandafter\edef\csname#1\endcsname{%
638 \expandafter\noexpand\csname#2\endcsname%
640 \expandafter\edef\csname end#1\endcsname{%
641 \expandafter\noexpand\csname end#2\endcsname%
642 \noexpand\expandafter%
644 \noexpand\if@endpe\noexpand\@endpetrue\noexpand\fi%
651 % \begin{environment}{minipage*}
653 % Let's define a \env{minipage$*$} environment which handles footnotes
654 % nicely. Really easy:
657 \makesavenoteenv[minipage*]{minipage}
662 % \begin{macro}{\parbox}
664 % Now to alter |\parbox| slightly, so that it handles footnotes properly.
665 % I'm going to do this fairly inefficiently, because I'm going to try and
666 % change it as little as possible.
668 % First, I'll save the old |\parbox| command. If I don't find a \lit{*},
669 % I'll just call this command.
672 \let\fn@parbox\parbox
675 % This is the clever bit: I don't know how many optional arguments
676 % Mr~Mittelbach and his chums will add to |\parbox|, so I'll handle any
677 % number. I'll store them all up in my first argument and call myself
678 % every time I find a new one. If I run out of optional arguments,
679 % I'll call the original |\parbox| command, surrounding it with |\savenotes|
683 \def\parbox{\@ifnextchar[{\fn@parbox@i{}}{\fn@parbox@ii{}}}
684 \def\fn@parbox@i#1[#2]{%
685 \@ifnextchar[{\fn@parbox@i{#1[#2]}}{\fn@parbox@ii{#1[#2]}}%
687 \long\def\fn@parbox@ii#1#2#3{\savenotes\fn@parbox#1{#2}{#3}\spewnotes}
698 % \hfill Mark Wooding, \today