% $StyleId: footnpag.doc,v 2.6 1995/11/10 18:21:26 schrod Exp $ %---------------------------------------------------------------------- % Written by Joachim Schrod . % Copyright conditions see below. % % LaTeX package footnpag % numbers footnotes subsequently per page % % [LaTeX in MAKEPROG] % (history at end) % If you have received this style file without the user manual (in the % file footnpag-user.tex or the respective DVI file), it's incomplete and % near to useless. If it was given to you as something that you shall % use as an author -- complain bitterly to your provider. You need the % documentation and you have a right on it! (Below you can find info % where to get the reference version.) %%%% %%%% %%%% These TeX macros were documented with the documentation system %%%% MAKEPROG and automatically converted to the current form. %%%% If you have MAKEPROG available you may transform it back to %%%% the original input: Remove every occurence of three percents %%%% and one optional blank from the beginning of a line and remove %%%% every line which starts with four percents. The following lex %%%% program will do this: %%%% %%%% %% %%%% %%%% ^%%%\ ? ; %%%% ^%%%%.*\n ; %%%% %%%% If you just want to print the documentation you may fetch %%%% the archive print-makeprog.tar.Z from ftp.th-darmstadt.de (directory %%%% pub/tex/latex). It contains *all* used styles -- but beware, they %%%% may not be in a documented form... %%%% %%%% %%% \documentclass{progltx} %%% \usepackage{footnpag-doc} % document-specific markup %%% \usepackage{fullpage} %%% \nofiles % no cross references %%% \RCS $StyleDate: 1995/11/10 18:21:26 $ %%% \begin{document} %%% \title{The \texttt{footnpag} Package\\ %%% {\large (Implementation)}% %%% } %%% \author{% % LaTeX does not discard unnecessary glue... %%% Joachim Schrod% %%% \thanks{% %%% \protect\raggedright %%% TU~Darmstadt, Computer Science Department, WG Systems Programming, %%% Alexanderstr.~10, D-64283~Darmstadt, Germany. %%% Email: \texttt{schrod@iti.informatik.th-darmstadt.de}.% %%% }% %%% } %%% \date{% %%% Revision \RCSStyleRevision\\ %%% (as of \RCSStyleDate)% %%% } %%% \maketitle %%% % doesn't work with progltx yet %%% %\tableofcontents %%% % ------------------------------------------------------------ %%% % %%% % subdocument: The user interface of footnpag.sty %%% % %%% \input{footnpag-user} %%% % %%% % ------------------------------------------------------------ %%% % %%% % subdocument: The internal interface %%% % %%% %\input{footnpag-conf} %%% % %%% % ------------------------------------------------------------ %%% \chap Implementation. %%% Please note, that this package was originally written for plain %%% \TeX{}. The original version is still available. This version will %%% evolve, and will finally be full \LaTeX{} code. %%% This module reserves the namespace |fnpp|. Due to the age of the code %%% it does not obey the namespace throughout, this has to be changed in a %%% future revision. %%% \beginprog \ifx \fnpp@loaded\undefined \def\fnpp@loaded{$StyleRevision: 2.6 $} \else \PackageWarningNoLine{footnpag}% {Some other package already uses namespace `fnpp'} \fi %%% \endprog %%% \sect Let's identify this package. %%% The code below is explained in the implementation documentation of the %%% |rcs| package. %%% \beginprog \begingroup \def\RCSPackage#1#2 $#3: #4 #5\endRCS $#6: #7 #8\endRCS{% \def\date{#4}\def\id{v#7}% \ProvidesPackage{#1}[\date\space\id\space #2]% } \RCSPackage{footnpag}{numbering footnotes per page} $StyleDate: 1995/11/10 18:21:26 $: 9999/00/00 \endRCS $StyleRevision: 2.6 $: 0.0 \endRCS \endgroup %%% \endprog %%% \sect This module is supported. Send bug reports, comments and %%% repairs. %%% The reference version may be retrieved via anonymous ftp from %%% |ftp.th-darmstadt.de| [130.83.47.112], directory |pub/tex/latex|. It's %%% placed there as a gzipped tar file. (The information on the IP~number %%% is dated August~3,~1995. %%% It might have changed, although this is very unlikely. Use your %%% friendly nameserver.) %%% \sect This is freely distributable software; you can redistribute it %%% and/or modify it under the terms of the GNU General Public License as %%% published by the Free Software Foundation; either version~2 of the %%% License, or (at your option) any later version. %%% This software is distributed in the hope that it will be useful, but %%% \textbf{without any warranty}; without even the implied warranty of %%% \textbf{merchantability} or \textbf{fitness for a particular purpose}. %%% See the GNU General Public License for more details. %%% You should have received a copy of the GNU General Public License in %%% the file |License| along with this package; if not, write to the Free %%% Software Foundation, Inc., 675~Mass Ave, Cambridge, MA~02139,~USA. %%% \sect Before we start we declare some shorthands for category codes. %%% By declaring the underscore~`(|_|)' as letter we can use it in our %%% macros. (I agree with \textsc{D.~Knuth} that %%% |\identifier_several_words_long| is more readable than %%% |\IdentifierSeveralWordsLong| and in every case better than |\p@@@s|.) %%% As this is a \LaTeX{} module the at sign is a letter anyhow; so %%% we can use the ``private'' \LaTeX{} macros; and with the underscore we %%% can make our own macros more readable. But as we have to restore this %%% category code at the end of this macro file we store its former value %%% in the control sequence |\CatUsCode|. This method is better than to %%% use a group because not all macros have to be defined global this way. %%% Since somebody might use more modules from me, this cseqs might be %%% defined already. %%% \beginprog \ifx \CatEscape\undefined \chardef\CatEscape=0 \chardef\CatOpen=1 \chardef\CatClose=2 \chardef\CatIgnore=9 \chardef\CatLetter=11 \chardef\CatOther=12 \chardef\CatActive=13 % is defined in Plain already \chardef\CatUsCode=\catcode`\_ \fi \catcode`\_=\CatLetter % top level macro file %%% \endprog %%% \sect Let's regard the implementation strategy. Because %%% the contents of one page is determined at (nearly) random places %%% with an asynchronous invogation of the output routine, we can not %%% give numbers to every footnote subsequently between output and %%% output: a footnote at the top of a page will perhaps get a number %%% before the output is triggered and there is no way to change this %%% number. The problem is like forward references to text places and it %%% is solved in a similar fashion. We need two \TeX{} runs to get the %%% numbering right but this is acceptable (who's got a finished text %%% after one run?!). In the first run we gather up in a file the %%% information where the footnotes are standing and in the second run %%% we use this information. %%% We must identify all footnotes if we write their numbers to the %%% footnote file, so each footnote gets an unary name built with the %%% counter |\foot_name_no|. The name is `|f@|\', where \ %%% is the footnote name number. This name building scheme has several %%% disadvantages, e.g.\ the insertion of a new footnote destroys the %%% knowledge of the former run about the following footnotes. If we would %%% have some knowledge about the document type we are using and the macro %%% set which is in effect we could insert other counters (e.g.\ the %%% chapter numbers) as well. %%% \chap Determing the footnote numbers. %%% Let's start with the initialization of the macro %%% set. We need a file descriptor, |\foot_file|, which we use for the %%% file interaction. The name of the file is built from the job name and %%% the suffix `|.fot|' (I hope that no macro package uses this suffix). %%% The |\init_footnote| macro reads the contents %%% of the footnote file if it exists (|\ifeof| returns true if the file %%% doesn't exist). The description of the reading of this file %%% (|\read_foot_file|) is deferred until we know the structure of the %%% contents. After reading, the file is closed and we can open it for %%% writing. For security, i.e.\ to have a defined minimal contents, we %%% immediately write |\relax| to the file. In the end the macro defines %%% itself to |\relax| to allow calling it again. %%% \beginprog \newread\old_foot_file \newwrite\foot_file \def\foot_file_name{\jobname.fot\relax} \def\init_footnote{% \openin\old_foot_file\foot_file_name \ifeof\old_foot_file \closein\old_foot_file \else \closein\old_foot_file \read_foot_file \fi \immediate\openout\foot_file\foot_file_name \immediate\write\foot_file{\relax}% \global\let\init_footnote\relax } %%% \endprog %%% \sect Remember, that we use |\foot_name_no| for the generation of a %%% name for each footnote. The actual number of the footnote mark is %%% stored in |\c@footnote|, the \LaTeX{} footnote counter. %%% In the beginning of every footnote |\init_footnote| is called to %%% guarantee that the handling is initialized (this especially means %%% that the footnote numbers are read in by the first footnote). %%% \beginprog \newcount\foot_name_no % for generating footnote mark names %%% \endprog %%% \sect It remains an open problem how to get the numbers there. The %%% footnote numbering must be initialized to zero in the output routine %%% and every footnote must increment this footnote number. The only %%% thing that is expanded during the output process is the output %%% routine itself and the |\write|'s, but the expanded tokens of %%% |\write| are written out, not interpreted. Well, the idea is simple: %%% We defer the counting to the second run and write the instructions %%% that do this to the file. The counting is then done while reading %%% the footnote file. %%% \noindent That means that the output routine adds entries like %%% % %%% \begin{quote} %%% |\c@footnote = 0| %%% \end{quote} %%% % %%% and every footnote adds an entry that looks like %%% % %%% \begin{quote} %%% |\advance\c@footnote by 1|\\ %%% |\xdef\csname f@|\ |\endcsname{\number\c@footnote}| %%% \end{quote} %%% % %%% where \ is replaced by the current footnote name number. %%% \sect The macro |\fnpp_next_footnote| determines the next footnote %%% number and stores it in |\c@footnote|, the official \LaTeX{} footnote %%% counter. This counter is used since |\footnotetext| constructs the %%% mark in the footnote text from it. One can say that %%% |\fnpp_next_footnote| is a non-typical way to step this counter, it's %%% a series iterator instead of an incrementer like |\stepcounter|. %%% The expansion of |\foot_name_no| must not be postponed until |\output| %%% time because there may be more footnotes coming on this page that'll %%% increase this number. %%% Therefore we first define the macro |\do_write| which contains the %%% |\write| and the expanded tokens which are to be put out. Every token %%% that should not be expanded is prefixed by |\string| (resulting in %%% character tokens that represent the token name). A |\space| must be %%% inserted to separate |\csname| from |f|. The |\xdef| in the (written) %%% definition code of |f@|\ is needed because the footnote file %%% will be read in within a group. %%% After writing the entry to the footnote file the number for this %%% footnote is set to~0 if it is not already defined (from a previous %%% run). %%% \beginprog \def\fnpp_next_footnote{% \init_footnote \global\advance\foot_name_no\@ne \edef\do_write{% \write\foot_file{% \string\advance\c@footnote\@ne \string\expandafter\xdef \string\csname\space f@\number\foot_name_no \endcsname{% \string\number\c@footnote }% }% }% \do_write \global\c@footnote 0\csname f@\number\foot_name_no \endcsname \relax } %%% \endprog %%% \sect It remains the reading of the footnote file. We have to read in %%% macros with names containing `|@|' characters. This will be done in %%% horizontal mode, so we ignore lineends to discard undesired spaces. %%% \beginprog \def\read_foot_file{% \begingroup \catcode`\@\CatLetter \catcode`\^^M\CatIgnore \input \foot_file_name \endgroup } %%% \endprog %%% \chap Connection to the output routine. %%% We must write the footnote number reset code at the start of each new %%% page. The most easy way to do this is to add an |\immediate\write| %%% to the output routine. %%% The output routine has no associated hook. (It should, of course. This %%% is no exotic wish.) So we have to add our code to it by redefining %%% some cseq. In a former version we really rebound |\output|, but that %%% was a leftover from the plain \TeX{} version. Then we had to check for %%% special |\output| invocations, which column we're in, etc. Now we rely %%% on some internals of \LaTeX{}: |\@outputpage| does the real ship out, %%% we just prepend our write to the front. %%% The reset code must not be written when no footnote was given by now. %%% We can check for the binding of |\init_footnote| to detect this, it's %%% |\relax| after the first footnote. %%% \beginprog \let\fnpp_orig_outputpage=\@outputpage \def\@outputpage{% \ifx \init_footnote\relax \immediate\write\foot_file{\c@footnote\z@}% \fi \fnpp_orig_outputpage } %%% \endprog %%% \chap The user interface. %%% Footnotes may be produced by |\footnote|, or by |\footnotemark| and %%% |\footnotetext| (the former creates the mark, the latter the text with %%% the last mark). All these tags have an optional argument, a number %%% that shall be used to create the mark for this specific invocation. %%% We redefine only the handling of macro invocations without optional %%% arguments. The original bindings are made available in the protected %%% interface, in case footnotes are used for unusual things. (See the %%% chunk on title matters below, for an example.) %%% \beginprog \let\FnppOrigFootnote=\footnote % save original bindings \let\FnppOrigFootnotemark=\footnotemark \def\footnote{% \@ifnextchar[% % ] (Emacs) \@xfootnote {\fnpp_next_footnote \@xfootnote[\the\c@footnote]}% } \def\footnotemark{% \@ifnextchar[% % ] (Emacs) \@xfootnotemark {\fnpp_next_footnote \@xfootnotemark[\the\c@footnote]}% } %%% \endprog %%% \sect Footnote tags in minipages behave a bit differently: There %%% |\footnote| and |\footnotetext| create minipage-local footnotes, %%% whereas |\footnotemark| creates a `global' footnote mark. I.e., if one %%% wants to make a footnote in a minipage that shall go on the page, one %%% has to specify |\footnotemark| in the minipage and |\footnotetext| %%% thereafter. |\footnotetext| uses the current value of the footnote %%% counter, since we set it by |\fnpp_next_footnote|, everything will %%% work. %%% \LaTeX{} makes a hook available to setup the minipage enviroment. But %%% the hook is initialized in a way that their own hook-enhancement %%% function does not work, we have to repair it first. No comment\,\dots %%% \beginprog \ifx \@minipagerestore\relax \let\@minipagerestore\@empty \fi \g@addto@macro\@minipagerestore{% \let\footnote\FnppOrigFootnote } %%% \endprog %%% \sect But footnotes are used for other things, too. E.g., to mention %%% affiliation or acknowledgements in title matters. This is done by %%% |\thanks| that uses |\footnotemark| to construct the respective marks. %%% The expansion of |\thanks| is done by |\maketitle| that resets the %%% footnote counter afterwards. But that reset does not work with this %%% package, as the footnote counter value is not used to determine the %%% next one. %%% The most simple solution is to reset |\footnotemark| during the %%% evaluation of |\maketitle|. We can do that in a group since all %%% side-effects of |\maketitle| should be global anyhow. %%% \beginprog \let\fnpp_orig_maketitle=\maketitle \def\maketitle{% \begingroup \let\footnotemark\FnppOrigFootnotemark \fnpp_orig_maketitle \endgroup } %%% \endprog %%% \chap The end. %%% Well, after all we're finished with this module. We must not forget to %%% restore the underscore catcode. %%% \beginprog \catcode`\_=\CatUsCode \endinput %%% \endprog %%% \sect I would like to thank those who helped me to improve this style. %%% % In particular, XXX provided XXXsubstantial parts of the code. %%% \textsc{Chris Thompson} sent change proposals that made the code more %%% robust. %%% \textsc{Frank Mittelbach} gave the impulse to make real \LaTeX{} %%% code out of the former plain \TeX{} code. (Actually, that's not as %%% drastic as it sounds. I threw half the code away and used stuff %%% already supplied by the \LaTeX{} kernel, then I added a few lines to %%% take care of minipages and front matter.) %%% \textsc{John Lu}, %%% \textsc{Sebastian Rahtz}, %%% and %%% \textsc{Frank Thomas} %%% provided error and problem reports. %%% %%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%% \vskip\PltxPreSectSkip %%% \begin{rcslog} %%% $StyleLog: footnpag.doc,v $ %%% \Revision 2.6 1995/11/10 18:21:26 schrod %%% Make |\footnotetext| usable in |minipage| environment, again.\\ %%% Problem reported by Sebastian Rahtz \path||. %%% \Revision 2.5 1995/08/04 00:18:34 schrod %%% Made a \LaTeXe{} package from this style option. %%% User manual is a separate document now, that's better for %%% installation. Started to change the distribution into one that %%% conforms to the `supported bundle guidelines.' %%% \Revision 2.4 1995/01/01 18:54:00 schrod %%% Optional arguments are supported now, |\footnotemark| may be used, %%% footnotes in minipages and title matter are handled correctly.\\ %%% (Enhancements requested by Frank Mittelbach %%% \path||.) %%% Started rewrite to a \LaTeXe{} package. Rearranged the code, used %%% \LaTeX{} internals. In particular, |\@outputpage| is now redefined, %%% instead of |\output|. I can throw away all checks for special output %%% invocations, which column we're in, etc., this way. Still, %%% documentation changes and some minor details are missing for the next %%% official release. %%% \Revision 2.3 1994/12/31 13:26:31 schrod %%% Spurious messages were produced on pages without footnotes before the %%% first footnote. I had to check if the footnote handling is initialized.\\ %%% (Bug reported at 25 Dec 93 by Frank Thomas \path||. %%% Actually repaired at 14 Jan 94, but change was not committed until now.) %%% \Revision 2.2 1993/02/02 11:04:18 schrod %%% If the first footnote was within a group, the footnote mechanism %%% was initialized a second time by the first footnote outside the group. %%% With this second initialization all information about previous %%% footnotes was discarded.\\ %%% (Bug reported on 01 Feb 93 by John Lu \path||.) %%% \Revision 2.1 1991/11/07 19:58:34 schrod %%% Set up for a new distribution, documentation is now in LaTeX. %%% Added first chapter where user interface and problems are explained. %%% \Revision 1.2 1989/04/21 00:00:00 schrod %%% Advances the usability in LaTeX (|\twocolumn|), %%% uses an own stream for reading, %%% resets the counter with |\immediate\write|. %%% (Improvements pointed out by Chris Thompson [CET].) %%% \end{rcslog} %%% \bigskip %%% \noindent \textsl{Pre-RCS version history}. %%% \medskip %%% \noindent Version 1.1 removed a |\begingroup| (88-10-20). %%% \smallskip %%% \noindent Version 1.0 was released in August, 1987. Actually, it was a %%% posting to \TeX{}hax. %%% \end{document} %%% %%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%% Local Variables: %%% mode: LaTeX %%% TeX-brace-indent-level: 4 %%% indent-tabs-mode: t %%% TeX-auto-untabify: nil %%% TeX-auto-regexp-list: LaTeX-auto-regexp-list %%% compile-command: "make footnpag.sty" %%% End: