path: root/Master/texmf-dist/source/latex/everypage/everypage.dtx

% \iffalse meta-comment
%
% Copyright 2006-2007
% Sergio Callegari <sergio.callegari@gmail.com>
%
% ---------------------------------------------
% This file is part of the everypage package,
% a contribution to the LaTeX2e system.
% ---------------------------------------------
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License, either version 1.3 of this licence, or
% any later version. The latest version of this license is at
% http://www.latex-project.org/lppl.txt and version 1.3 is part
% of all distributions of LaTeX version 2003/06/01 or later.
%
% This work has the LPPL maintenance status "author-maintained".
%
% This program consists of the files listed in the README file
% included in the package.
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{mathptmx, helvet, courier}
\EnableCrossrefs
\DoNotIndex{\def,\gdef,\let,\NeedsTeXFormat,\newcommand}
\DoNotIndex{\ProvidesPackage,\endinput}
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{everypage.dtx}
\end{document}
%</driver>
%
% \fi
%
% \CheckSum{44}
%
% \def\filename{everypage.dtx}
% \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
% \newcommand*{\file}[1]{\texttt {#1}}            ^^A typeset a file
% \newcommand*{\Lcount}[1]{\textsl {\small#1}}    ^^A typeset a counter
% \newcommand*{\pstyle}[1]{\textsl {#1}}          ^^A typeset a pagestyle
% \newcommand*{\Lenv}[1]{\texttt {#1}}            ^^A typeset an environment
%
% \title{The \Lpack{everypage} package\thanks{This file
%     (\texttt{\filename}) has version number \fileversion, last
%     revised \filedate.}}
%
% \author{%
%   Sergio Callegari\thanks{Sergio Callegari can be reached at
%       \texttt{sergio.callegar at gmail dot com}}} 
%
% \date{\docdate}
%
% \maketitle
%
% \begin{abstract}
%   The \Lpack{everypage} package extends \LaTeX\ providing hooks to do
%   actions on every page or on the current page. Specifically, actions
%   are performed \emph{before} the page is shipped, so they can be
%   used to put watermarks \emph{in the background} of a page, or to
%   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}
% 
% This program adds two \LaTeX\ hooks that get run when document
% pages are finalized and output to the dvi or pdf
% file. Specifically, one hook gets executed on every page, while the
% other is executed for the current page. Hook actions are are performed
% \emph{before} the page is output on the medium, and this is
% important to be able to play with the page layout or to put things
% \emph{behind} the page contents (e.g., watermarks such as an image,
% framing, the ``DRAFT'' word, and the like).
% 
% The package reminds in some sense \Lpack{bobhook} by Karsten
% Tinnefeld, but it differs in the way in which the hooks are
% implemented:
% 
% \begin{enumerate}
% \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.
%   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{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
%   |\@begindvi| is here postponed as much as possible, striving to
%   avoid interference with other packages using |\AtBeginDvi| or
%   anyway manipulating |\@begindvi|. Specifically \Lpack{everypage}
%   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}
% The |\AddEverypageHook| accepts one argument and adds it to the list
% of hooks that are run before every page is output. The
% |\AddThispageHook| accepts one argument and adds it to the list of
% hooks that are run before the current page is output.
%
% Note that once hooks are stacked, there is no way to unstack them,
% nor to clear them. In order to have hooks that get run only when
% specific conditions are met, conditionals must be included in the
% hooks.
% 
% Also note that no particular assumption is made on the \LaTeX\
% output driver, so \Lpack{everypage} should work equally well with
% \LaTeX\ and pdf\LaTeX. Furthermore, the package should work equally
% well with dvi, dvips, etc.\@ output drivers. Obviously, the final
% compatibility with the different output drivers depends on the
% actual code that is placed in the hooks.
%
% For usage examples, please see the \Lpack{flippdf} and
% \Lpack{draftwatermark} packages.
% 
% \StopEventually {}
% 
% \section{Implementation}
%
% Announce the name and version of the package, which requires
% \LaTeXe.
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{everypage}%
  [2007/06/20 1.1 Hooks to run on every page]
%    \end{macrocode}
%
% \begin{macro}{\sc@everypage@hook}\begin{macro}{\sc@everypage@hook}
% Define internal macros to hold the hooks and initialize them to
% contain nothing.
%    \begin{macrocode}
\newcommand{\sc@everypage@hook}{}
\newcommand{\sc@thispage@hook}{}
%    \end{macrocode}
% \end{macro}\end{macro}
%
% \begin{macro}{\AddEverypageHook}\begin{macro}{\AddThispageHook}
% Define the commands used to add the hooks.
%    \begin{macrocode}
\newcommand*{\AddEverypageHook}[1]{%
  \g@addto@macro\sc@everypage@hook{#1}}
\newcommand*{\AddThispageHook}[1]{%
  \g@addto@macro\sc@thispage@hook{#1}}
%    \end{macrocode}
% \end{macro}\end{macro}
%
% \begin{macro}{\sc@ep@init}
% 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 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@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. 
% 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
  \def\@begindvi{%
    \sc@everypage@hook
    \sc@thispage@hook
    \gdef\sc@thispage@hook{}
    \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
% insert the \Lpack{everypage} initialization routine in the queue of
% commands to be executed when the actual document begins. In this
% way, the \Lpack{everypage} initialization code is run \emph{after}
% other packages are loaded.
%    \begin{macrocode} 
\AtBeginDocument{\sc@ep@init}
\endinput
%    \end{macrocode}
%
% \Finale
% \PrintIndex
%
%% \CharacterTable
%%  {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
%%   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
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
\endinput

%%% Local Variables: 
%%% mode: doctex
%%% TeX-master: t
%%% End: