everypage 1.1 (19feb08)

git-svn-id: svn://tug.org/texlive/trunk@6701 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 48 insertions, 26 deletions

diff --git a/Master/texmf-dist/source/latex/everypage/everypage.dtx b/Master/texmf-dist/source/latex/everypage/everypage.dtx
index 38f168900cf..02cf2149a38 100644
--- a/Master/texmf-dist/source/latex/everypage/everypage.dtx
+++ b/Master/texmf-dist/source/latex/everypage/everypage.dtx
@@ -1,6 +1,6 @@
 % \iffalse meta-comment
 %
-% Copyright 2006
+% Copyright 2006-2007
 % Sergio Callegari <sergio.callegari@gmail.com>
 %
 % ---------------------------------------------
@@ -34,12 +34,12 @@
 %
 % \fi
 %
-% \CheckSum{41}
+% \CheckSum{44}
 %
 % \def\filename{everypage.dtx}
-% \def\fileversion{1.0}
-% \def\filedate{2006/06/30}
-% \def\docdate{2006/06/30}
+% \def\fileversion{1.1}
+% \def\filedate{2007/06/20}
+% \def\docdate{2007/06/20}
 %
 % \newcommand*{\Lpack}[1]{\textsf {#1}}           ^^A typeset a package
 % \newcommand*{\Lopt}[1]{\textsf {#1}}            ^^A typeset an option
@@ -68,6 +68,9 @@
 %   set the page layout. The package reminds in some sense
 %   \Lpack{bobhook} by Karsten Tinnefeld, but it differs in the way in
 %   which the hooks are implemented, as detailed in the following.
+%   In some sense it may also be related to the package
+%   \Lpack{everyshi} by Martin Schroeder, but again the implementation
+%   is different.
 % \end{abstract}
 % 
 % \section{Introduction}
@@ -89,19 +92,19 @@
 % \item there is no formatting inherent in the hooks. If one wants to
 %   put some watermark on a page, it is his own duty to put in the
 %   hook the code to place the watermark in the right position. Also
-%   note that the hooks code should \emph{eat up no space} in the page.
-%   Again, if the hooks are meant to place some material on the page,
-%   it is the duty of the hook programmer to put code in the hooks to
-%   pretend that the material has zero width and zero height.
+%   note that the hooks code should \emph{eat up no space} in the
+%   page.  Again, if the hooks are meant to place some material on the
+%   page, it is the duty of the hook programmer to put code in the
+%   hooks to pretend that the material has zero width and zero height.
 %   The implementation is \emph{lighter} than the \Lpack{bobhook} one,
 %   and possibly more flexible, since one is not limited by any
 %   pre-coded formatting for the hooks. On the other hand it is
 %   possibly more difficult to use. Nonetheless, it is easy to think
-%   of other packages relying on \Lpack{bobhook} and delivering more
-%   user-friendly \emph{task specific} interfaces. The packages
-%   \Lpack{flippdf} meant to deliver mirrored pages in a PDF document
-%   and \Lpack{draftwatermark} meant to add a watermark to document
-%   pages are examples of this.
+%   of other packages relying on \Lpack{everypage} to deliver more
+%   user-friendly and \emph{task specific} interfaces. Already there
+%   are a couple of them: the package \Lpack{flippdf} produces
+%   mirrored pages in a PDF document and \Lpack{draftwatermark}
+%   watermarks document pages.
 % \item similarly to \Lpack{bobhook} and \Lpack{watermark}, the
 %   package relies on the manipolatoin of the internal \LaTeX\ macro
 %   |\@begindvi| to do the job. However, the redefinition of
@@ -111,6 +114,12 @@
 %   makes no special assumption on the initial code that |\@begindvi|
 %   might contain.
 % \end{enumerate}
+%
+% Also in some sense \Lpack{everypage} can be related to package
+% \Lpack{everyshi} by Martin Schroeder, but it differs radically from
+% it in the implementation. In fact,\Lpack{everypage} operates by
+% manipulation of the |\@begindvi| macro, rather than at the
+% lower level |\shipout| macro.
 % 
 % \section{User interface}
 % \DescribeMacro{\AddEverypageHook}\DescribeMacro{\AddThispageHook}
@@ -143,7 +152,7 @@
 %    \begin{macrocode}
 \NeedsTeXFormat{LaTeX2e}
 \ProvidesPackage{everypage}%
-  [2006/06/30 1.0 Hooks to run on every page]
+  [2007/06/20 1.1 Hooks to run on every page]
 %    \end{macrocode}
 %
 % \begin{macro}{\sc@everypage@hook}\begin{macro}{\sc@everypage@hook}
@@ -169,26 +178,25 @@
 % The internal initialization code of the package. The package works
 % by redefining the normal |\@outputpage| routine that takes care of
 % outputting pages, so that the modified version first calls a special
-% preamble, and then calls the original |\@outputpage| code. 
+% preamble, and then calls the original |\@outputpage| code and
+% finally a postamble. 
 %    \begin{macrocode}
 \newcommand*{\sc@ep@init}{%    
   \let\sc@op@saved\@outputpage
   \def\@outputpage{%
     \sc@op@preamble
-    \sc@op@saved}}
+    \sc@op@saved
+    \sc@op@postamble}}
 %    \end{macrocode}
 % \end{macro}
 %
 % \begin{macro}{\sc@op@preamble}
 % The outputpage preamble contains instructions to redefine the
 % |\@begindvi| macro that is called at every page output by the
-% original |\@outputpage| code. Then, the hooks for the current page
-% are cleared.  Specifically, the |\@begindvi| macro is redefined so
-% that first the hooks are called and then the normal |\@begindvi| is
-% restored to the original code and run. Restoring |\@begindvi| before
-% actually running it is indispensible, because a usual trick of the
-% code that one normally finds in |\@begindvi| is to redefine
-% |\@begindvi| itself.
+% original |\@outputpage| code. 
+% Specifically: first the original |\@begindvi| is saved; then the
+% hooks are called; then the hooks for the current page
+% are cleared; eventually, the saved |\@begindvi| is called.
 %    \begin{macrocode}
 \newcommand*{\sc@op@preamble}{%
   \let\sc@begindvi\@begindvi
@@ -196,9 +204,23 @@
     \sc@everypage@hook
     \sc@thispage@hook
     \gdef\sc@thispage@hook{}
-    \let\@begindvi\sc@begindvi
-    \@begindvi}}
+    \sc@begindvi}}
+%    \end{macrocode}
+% \end{macro}
+% 
+% \begin{macro}{\sc@op@postamble}
+% The outputpage postamble simply restores the |\@begindvi| command to
+% the saved value. 
+%    \begin{macrocode}
+\newcommand*{\sc@op@postamble}{%
+  \let\@begindvi\sc@begindvi}
 %    \end{macrocode}
+% Note that in exceptional cases this might not be the intended
+% behaviour. For instance, consider situations where 
+% the |\@begindvi| is hacked by some other package to modify
+% itself. By restoring the saved value, one might lose the
+% modifications. This potential issue is currently under
+% investigation. 
 % \end{macro}
 % 
 % As the very last thing, the |\AtBeginDocument| macro is called to