diff options
author | Karl Berry <karl@freefriends.org> | 2007-01-08 00:08:40 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2007-01-08 00:08:40 +0000 |
commit | daaf73cce84a5e3a01af71bd2328c039fa2d8445 (patch) | |
tree | 1639ba34af7ef4c6c0c32edc7de5513157fa4b11 /Master/texmf-dist/doc/latex/footnpag/footnpag.doc | |
parent | 849deadf599d4c3a3b94dfeb1a4fb8e3bba89c75 (diff) |
footnpag doc update (5jan07)
git-svn-id: svn://tug.org/texlive/trunk@3224 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/footnpag/footnpag.doc')
-rw-r--r-- | Master/texmf-dist/doc/latex/footnpag/footnpag.doc | 559 |
1 files changed, 559 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/footnpag/footnpag.doc b/Master/texmf-dist/doc/latex/footnpag/footnpag.doc new file mode 100644 index 00000000000..ad6dc2a10c7 --- /dev/null +++ b/Master/texmf-dist/doc/latex/footnpag/footnpag.doc @@ -0,0 +1,559 @@ +% $StyleId: footnpag.doc,v 2.6 1995/11/10 18:21:26 schrod Exp $ +%---------------------------------------------------------------------- +% Written by Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>. +% 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.) + + + + +\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@|\<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|<s.rahtz@elsevier.co.uk>|. + +\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|<mittelbach@mzdmza.zdv.uni-mainz.de>|.) + +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|<frank@glocke.robin.de>|. +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|<luj@ecn.purdue.edu>|.) + +\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: |