% $StyleId: footnpag.doc,v 2.6 1995/11/10 18:21:26 schrod Exp $
%----------------------------------------------------------------------
% Written by Joachim Schrod <[email protected]>.
% 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{[email protected]}.%
%%% }%
%%% }
%%% \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@|\<nameno>', where \<nameno>
%%% 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@|\<nameno> |\endcsname{\number\c@footnote}|
%%% \end{quote}
%%% %
%%% where \<nameno> 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@|\<nameno> 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|<[email protected]>|.
%%% \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|<[email protected]>|.)
%%% 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|<[email protected]>|.
%%% 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|<[email protected]>|.)
%%% \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:
|
