summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/everypage/everypage.dtx
blob: 02cf2149a38bd26a6821fcc3620afa3adc3cca25 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
% \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: