path: root/macros/latex/contrib/ms/everyshi.dtx

% \iffalse
%% File: everyshi.dtx Copyright (C) 2001 Martin Schr\"oder
%
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{everyshi}
%<package>         [2001/05/15 v3.00 EveryShipout Package (MS)]
%
%<*driver>
\ProvidesFile{everyshi.drv}
      [1999/06/08 v2.03 Driver for EveryShipout Package (MS)]
\documentclass{ltxdoc}
\usepackage{url}
\usepackage[toc]{multitoc}
\usepackage{everyshi}
\GetFileInfo{everyshi.sty}
\setcounter{IndexColumns}{2}
\EnableCrossrefs
%%\DisableCrossrefs% Say \DisableCrossrefs if index is ready
\CodelineIndex    % Index code by line number
\OnlyDescription  % comment out for implementation details
%%\OldMakeIndex    % use if your MakeIndex is pre-v2.9
\setcounter{IndexColumns}{2}
\setlength{\IndexMin}{30ex}
\setlength{\columnseprule}{.4pt}
\begin{document}
   \DocInput{everyshi.dtx}
\end{document}
%</driver>
%
% Copyright (C) 2001 by Martin Schr\"oder.  All rights reserved.
%
% This program may be redistributed and/or modified under the terms
% of the LaTeX Project Public License, either version 1.0 of this
% license, or (at your option) any later version.
% The latest version of this license is in
%   CTAN:macros/latex/base/lppl.txt.
%
% Happy users are requested to send me a postcard. :-)
%
% For error reports in case of UNCHANGED versions see everyshi.ins
%
% \fi
%
% \CheckSum{51}
%
%% \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         \~}
%%
%% \iffalse meta-comment
%% ===================================================================
%%  @LaTeX-package-file{
%%     author          = {Martin Schr\"oder},
%%     version         = "3.00",
%%     date            = "15 May 2001",
%%     filename        = "everyshi.sty",
%%     address         = {Martin Schr\"oder
%%                        Cr\"usemannallee 3
%%                        28213 Bremen
%%                        Germany},
%%     telephone       = "+49-421-2239425",
%%     email           = "martin@oneiros.de",
%%     pgp-Key         = "2048 bit / KeyID 292814E5",
%%     pgp-fingerprint = "7E86 6EC8 97FA 2995 82C3  FEA5 2719 090E",
%      checksum        = "51832 357 1434 12417",
%      codetable       = "ISO/ASCII",
%      keywords        = "LaTeX2e, \shipout",
%      supported       = "yes",
%%     docstring       = "LaTeX package which provides hooks into
%%                        \cs{shipout}.
%
%                         The checksum field above contains a CRC-16
%                         checksum as the first value, followed by
%                         the equivalent of the standard UNIX wc
%                         (word count) utility output of lines,
%                         words, and characters.  This is produced
%                         by Robert Solovay's checksum utility."
%%  }
%% ===================================================================
%% \fi
%
%  \changes{v1.00}{1994/12/04}{New}
%  \changes{v1.02}{1994/12/07}{Name changed from \textsf{atshipou} to 
%                                \textsf{everyshi}}
%  \changes{v1.03}{1994/12/09}{Documentation improved}
%  \changes{v2.00}{1995/01/25}{Redesign}
%  \changes{v2.02}{1998/08/09}{Documentation improved}
%  \changes{v2.03}{1999/06/08}{Moved to LPPL}
%  \changes{v3.00}{2001/05/15}{\cs{AtNextShipout} added}
%
%  \newcommand*{\package}[1]{\textnormal{\sffamily#1}}
%  \newcommand*{\NEWfeature}[1]{%
%     \hskip 1sp \marginpar{\small\sffamily\raggedright
%     New feature\\#1}}
%
% ^^A -----------------------------
%
%  \changes{v2.01}{1997-03-09}{Fixed use of \cs{newline} in title.}
%  \title{\unskip
%           The \package{everyshi} package^^A
%           \thanks{^^A
%              The version umber of this file is \fileversion,
%              last revised \filedate.\protect\newline
%              The name \textsf{everyshi} is a tribute to the $8+3$
%              file-naming convention of certain ``operating
%              systems''; strictly speaking it should be 
%              \textsf{everyshipout}.}^^A
%        }
%  \author{Martin Schr\"oder\\[0.5ex]
%          \normalsize  Cr\"usemannallee 3\\
%          \normalsize  28213 Bremen\\
%          \normalsize  Germany\\
%          \normalsize  martin@oneiros.de\\
%          \scriptsize \texttt{PGP-Key: 2048 bit / KeyID 292814E5}\\[-0.5em]
%          \scriptsize \texttt{7E86 6EC8 97FA 2995~~82C3 FEA5 2719 090E}}
%  \date{\filedate}
%  \maketitle
%
% ^^A -----------------------------
%
%
%  \begin{abstract}
%     This packages provides hooks into \cs{sshipout} 
%     called \cs{EveryShipout} and \cs{AtNextShipout} analogous to 
%     \cs{AtBeginDocument}.
%  \end{abstract}
%
%  \pagestyle{headings}
%
% ^^A -----------------------------
%
%  \tableofcontents
%
% ^^A -----------------------------
%
%  \section{Introduction}
%
%  This package provides the hooks \cs{EveryShipout} and 
%  \cs{AtNextShipout} whose arguments are executed after the output 
%  routine has constructed \cs{box255}, and before \cs{shipout} is 
%  called.
%
%  An example application for this package would be a package for
%  adding text to the bottom of each page.
%  Such a package does exist: \package{prelim2e}\cite{package:prelim2e}.
%
%  \changes{v3.00}{2001/05/15}{Reference to \package{eso-pic} added}
%  Another application is a package for adding pictures to every page:
%  \package{eso-pic}\cite{package:eso-pic}.
%
% ^^A -----------------------------
%
%  \section{Usage}
%
%  \cs{EveryShipout}\marg{code} declares
%  \mbox{$\langle$\emph{code}$\rangle$} that is saved internally
%  and executed before each \cs{shipout}.
%
%  \emph{Warning:} The \mbox{$\langle$\emph{code}$\rangle$} is saved 
%  globally; there is currently no way to remove it.
%
%  \DescribeMacro{\AtNextShipout}
%  \NEWfeature{2001/05/15}
%  \cs{AtNextShipout}\marg{code} declares
%  \mbox{$\langle$\emph{code}$\rangle$} that is saved internally
%  and executed just before \emph{only the next} \cs{shipout}.
%
%  The \meta{code} is executed after \cs{box255} has been constructed
%  by the output routine and can change \cs{box255}.
%  \cs{shipout} is called \emph{after} \meta{code}.
%
%  Repeated use of the commands is permitted: the code in the
%  argument is stored (and executed) in the order of their
%  declarations.
%
%  The argument of \cs{AtNextShipout} is executed \emph{after}
%  the argument of \cs{EveryShipout}.
%
% ^^A -----------------------------
%
%  \section{Options}
%
%  The package has no options.
%
% ^^A -----------------------------
%
%  \section{Required packages}
%
%  The package does not require any further packages.
%
% ^^A -----------------------------
%
%  \StopEventually{^^A

% ^^A -----------------------------
%
%  \section{Acknowledgements}
%  ^^A
%  Version 2.0 of \package{everyshi} borrows heavily from
%  \textsf{quire.tex} of the \textsf{Midnight Macros} by Marcel R.~van 
%  der Goot (\texttt{marcel@cs.caltech.edu}).
%  The pointer to \textsf{quire} was provided by Lothar Meyer-Lerbs
%  (\texttt{\TeX{}Satz@zfn.uni-bremen.de}).
%  As usual Rebecca Stiels improved the quality of this documentation.
%
%
% ^^A -----------------------------
%
%  \begin{thebibliography}{1}
%     \raggedright
%     \bibitem{package:eso-pic}
%        Rolf Niepraschk.
%        \newblock The \package{eso-pic} package.
%        \newblock \url{CTAN: tex-archive/macros/latex/contrib/supported/ms/contrib/eso-pic.dtx}.
%        \newblock \LaTeXe{} package.
%     \bibitem{package:prelim2e}
%        Martin Schr\"oder.
%        \newblock The \package{prelim2e} package.
%        \newblock \url{CTAN: tex-archive/macros/latex/contrib/supported/ms/prelim2e.dtx}.
%        \newblock \LaTeXe{} package.
%  \end{thebibliography}
%
%     }
%
% ^^A -----------------------------
%
%  \section{The implementation}
%  \raggedright
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
%
%
% ^^A -----------------------------
%
%  \subsection{Allocations}
%  ^^A
%  First we allocate the hooks
%  \begin{macro}{\@EveryShipout@Hook}
%  \changes{v2.00}{1995/01/25}{Name changed from \cs{@shipouthook} to
%                                \cs{@EveryShipout@Hook}}
%  \changes{v3.00}{2001/05/15}{\cs{newcommand}}
%  The code to be executed before \cs{shipout} is stored in
%  \cs{@EveryShipout@Hook}.
%    \begin{macrocode}
\newcommand{\@EveryShipout@Hook}{}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\@EveryShipout@AtNextHook}
%  \changes{v3.00}{2001/05/15}{new}
%  The code to be executed just before the normal \cs{shipout}
%  and \cs{@EveryShipout@EveryHook}.
%    \begin{macrocode}
\newcommand{\@EveryShipout@AtNextHook}{}
%    \end{macrocode}
%  \end{macro}
%
%
% ^^A -----------------------------
%
%  \subsection{The user-visible commands}
%  ^^A
%  \begin{macro}{\EveryShipout}
%  \begin{macro}{\AtNextShipout}
%  \changes{v1.01}{1994/12/06}{\cs{newcommand} instead of \cs{def}}
%  \changes{v1.02}{1994/12/07}{Name changed from \cs{AtShipout} to 
%                                \cs{EveryShipOut}}
%  \changes{v3.00}{2001/05/15}{\cs{AtNextShipout} added}
%  The commands are modeled after \cs{AtBeginDocument}.
%    \begin{macrocode}
\newcommand*{\EveryShipout}[1]
   {\g@addto@macro\@EveryShipout@Hook{#1}}
\newcommand*{\AtNextShipout}[1]
   {\g@addto@macro\@EveryShipout@AtNextHook{#1}}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%
%
% ^^A -----------------------------
%
%  \subsection{Inserting the hooks}
%  ^^A
%  We want to redefine \cs{shipout} so that first \cs{box255} is
%  constructed and after that we can do something and at last shipout
%  the (possible modified) \cs{box255}.
%  Alas, this does not work in the usual way, since \cs{shipout} is
%  a \TeX{} primitive whose argument is a \meta{box}.
%  This means that simply redefining \cs{shipout} via \cs{newcommand[1]}
%  is impossible since \meta{box} can be something like \cs{box255} or
%  something like \cs{vbox\{\ldots\}}.
%  In the first case \texttt{\#1} would be \meta{\cs{box}} (without 
%  \meta{255}); in the second case it would be \meta{\cs{vbox}} (without
%  \meta{\{\ldots\}}).
%
%  The solution we use here is borrowed from \textsf{quire.tex} by
%  Marcel R.~van der Goot.
%  It is based upon \cs{afterassignment} and \cs{aftergroup}.
%
%  \begin{macro}{\@EveryShipout@Shipout}
%  \changes{v2.00}{1995/01/25}{new}
%  \cs{@EveryShipout@Shipout} is our replacement for \cs{shipout}.
%    \begin{macrocode}
\newcommand{\@EveryShipout@Shipout}{%
   \afterassignment\@EveryShipout@Test
   \global\setbox\@cclv= %
   }
%    \end{macrocode}
%  \cs{box255} is set to whatever comes after \cs{shipout}; but after
%  that assignment \cs{@EveryShipout@Test} is called.
%  \end{macro}
%
%  \begin{macro}{\@EveryShipout@Test}
%  \changes{v2.00}{1995/01/25}{new}
%  \cs{@EveryShipout@Test} determines if \cs{shipout} is called with
%  an argument like \cs{box255} or something like \cs{vbox\{\ldots\}}.
%  In the later case we delay the call of \cs{@EveryShipout@Output} 
%  (where the original \cs{shipout} is called) via \cs{aftergroup}.
%    \begin{macrocode}
\newcommand{\@EveryShipout@Test}{%
   \ifvoid\@cclv\relax
      \aftergroup\@EveryShipout@Output
   \else
      \@EveryShipout@Output
   \fi%
   }
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\@EveryShipout@Output}
%  \changes{v2.00}{1995/01/25}{new}
%  \changes{v3.00}{2001/05/15}{added call to \cs{@EveryShipout@AtNextHook}}
%  \cs{@EveryShipout@Output} does the actual work.
%  First the \meta{code} accumulated via \cs{EveryShipout} and 
%  \cs{AtNextShipout} is called and then the original \cs{shipout} stored 
%  in \cs{@EveryShipout@Org@Shipout} is called to finally ship out 
%  \cs{box255}.
%    \begin{macrocode}
\newcommand{\@EveryShipout@Output}{%
   \@EveryShipout@Hook%
   \@EveryShipout@AtNextHook%
%    \end{macrocode}
%  We have to reset \cs{@EveryShipout@AtNextHook} after each use.
%    \begin{macrocode}
      \gdef\@EveryShipout@AtNextHook{}%
   \@EveryShipout@Org@Shipout\box\@cclv%
   }
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\@EveryShipout@Org@Shipout}
%  \changes{v2.00}{1995/01/25}{new}
%  The original \cs{shipout} is stored in \cs{@EveryShipout@Org@Shipout}
%  by \cs{@EveryShipout@Init}.
%  Here we allocate it.
%    \begin{macrocode}
\newcommand{\@EveryShipout@Org@Shipout}{}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\@EveryShipout@Init}
%  \changes{v2.00}{1995/01/25}{new}
%  \changes{v3.00}{2001/05/15}{output message}
%  \cs{@EveryShipout@Init} stores the original \cs{shipout} in 
%  \cs{@EveryShipout@Org@Shipout} and sets \cs{shipout} to 
%  \cs{@EveryShipout@Shipout}.
%  This is done at \cs{begin\{document\}} via \cs{AtBeginDocument}.
%    \begin{macrocode}
\newcommand*{\@EveryShipout@Init}{%
   \message{ABD: EveryShipout initializing macros}%
   \let\@EveryShipout@Org@Shipout\shipout
   \let\shipout\@EveryShipout@Shipout
   }
\AtBeginDocument{\@EveryShipout@Init}
%    \end{macrocode}
%  \end{macro}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
%
% ^^A -----------------------------
%
%  \Finale
%
%   \PrintIndex\PrintChanges
%   ^^A Make sure that the index is not printed twice
%   ^^A (ltxdoc.cfg might have a second \PrintIndex command)
%   \let\PrintChanges\relax
%   \let\PrintIndex\relax