summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/everypage/everypage.dtx
blob: d23b6284b9cf1acdf7c3333d86109a6903aa495b (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
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
% \iffalse meta-comment
%
% Copyright 2006-2007, 2020
% Sergio Callegari <sergio.callegari@gmail.com>
%
% ---------------------------------------------
% This file is part of the everypage package,
% a contribution to the LaTeX2e system.
% ---------------------------------------------
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, version 1.3c.
% This license is in
%   https://www.latex-project.org/lppl/lppl-1-3c/
% and is part of all distributions of LaTeX later than
% 2008-05-04.
%
% This work has the LPPL maintenance status "maintained".
%
% This program consists of the files listed in the README file
% included in the package.
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{mathptmx}
\usepackage[T1]{fontenc}
\usepackage[scaled=0.92]{helvet}
% \usepackage{courier}
\usepackage{hologo}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{everypage.dtx}
\end{document}
%</driver>
%
% \fi
%
% \DoNotIndex{\@ifundefined, \g@addto@macro}
% \DoNotIndex{\def, \gdef, \let, \newcommand}
% \DoNotIndex{\MessageBreak, \PackageWarningNoLine, \NeedsTeXFormat}
% \DoNotIndex{\ProvidesPackage, \RequirePackage}
% \DoNotIndex{\put}
% \DoNotIndex{\endinput}
%
% \CheckSum{71}
%
% \def\filename{everypage.dtx}
% \def\fileversion{2.0b}
% \def\filedate{2020/10/17}
% \def\docdate{2020/10/17}
%
% \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
%
% \changes{R2.0b}{2020/10/17}{Fix statement about maintenance state.}
%
% \section*{WARNING}
% \changes{R2.0}{2020/10/11}{Package is now in a `legacy' status.}
% 
% This package is now in \emph{legacy status}. Functionality similar to
% that provided by this package has been directly implemented in \LaTeX\
% since its 2020 Fall release. Do not use \Lpack{everypage} in new
% documents and do not rely on it in new packages or classes of
% yours.
%
% \smallskip
% When running on a pre-2020-10-01 version of \LaTeX, \Lpack{everypage}
% will now fall back to \Lpack{everypage-1x}, its own past
% code base.\smallskip
%
% When running on a modern \LaTeX, \Lpack{everypage} will strive to
% provide its legacy interfaces by using the newer \LaTeX\ facilities.
% However, full equivalence is not possible and breakage may occur. When
% truly needed, try loading \Lpack{everypage-1x} in place of
% \Lpack{everypage} to force usage of the old code base. This is expected
% to keep working for a few more \LaTeX\ release cycles after Fall 2020.
%
% \bigskip\bigskip
%
% \begin{abstract}
%   The \Lpack{everypage} package was meant to extend \LaTeX\ providing
%   hooks to do actions on every page or on the current page. Currently,
%   similar functionality is directly provided by \LaTeX. Specifically,
%   \Lpack{everypage} supports actions 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 is in
%   many ways similar to \Lpack{bobhook} by Karsten Tinnefeld, but it
%   differs in the way in which the hooks are implemented. In some sense,
%   it may also be related to package \Lpack{everyshi} by Martin
%   Schroeder, but again the implementation is different.
% \end{abstract}
% 
% \section{Introduction}
%
% Until a recent past, \LaTeX\ provided no explicit hooks to be run as
% documents pages were finalized and output to the dvi or pdf
% file. Consequently, many solutions were developed to work around this
% limitation and to offer features (e.g., watermarks) that would otherwise
% be impossible. These solution included packages such as
% \Lpack{everyshi}, \Lpack{bobhook} and \Lpack{watermark}. Package
% \Lpack{everypage} was a solution providing plumbing that could be used
% in higher level packages such as \Lpack{draftwatermark} (watermarking)
% and \Lpack{flippdf} (print preprocessing) to mention a couple of them.
%
% All of these extensions relied on applying modifications to some \LaTeX\
% internals and as such were prone to subtle interactions with other
% packages and breakage. The situation has been cleared by the 2020 Fall
% \LaTeX\ release where an official and generic support for hooks has been
% introduced.
%
% As of today, \Lpack{everypage} can be considered obsolete. It needs to
% remain around because older releases of \LaTeX\ are still in use and
% legacy code exist that is based on the interfaces it exposes. However,
% no new document, class or package should be based on it. Furthermore, it
% can be expected that existing packages that use \Lpack{everypage} will
% progressively learn to rely directly on the new \LaTeX\ hook mechanism.
%
% This manual is meant to aid the transition by showing how
% \Lpack{everypage} is now being updated to cater both for older and newer
% \LaTeX\ kernels. Specifically, it illustrates:
% \begin{enumerate}
% \item how \Lpack{everypage} is now actually split in two packages:
%   \Lpack{everypage-1x}, providing the old code base; and
%   \Lpack{everypage} itself, that strives to implement the legacy
%   interface on top of the new mechanisms offered by \LaTeX;
% \item how \Lpack{everypage} can automatically import the old code base
%   as needed, how loading of the latter can be forced (if absolutely
%   needed or for comparison) and for how long the old code can be
%   expected to keep working with newer releases of \LaTeX;
% \item how the legacy interface of \Lpack{everypage}, once
%   implemented/emulated on top of the new \LaTeX\ facilities actually
%   differs from its nominal behavior.
% \end{enumerate}
%   
% \section{The original code base}
% \label{sec:original}
% \changes{R1.0}{2006/06/30}{%
%   Initial release.}
%
% The original implementation of \Lpack{everypage}, now available as
% \Lpack{everypage-1x}, 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).
%
% \subsection{User interface}
% \label{ssec:ui}
% 
% \DescribeMacro{\AddEverypageHook} The |\AddEverypageHook| command
% accepts one argument and adds it to the list of hooks that are run
% before every page is output. Similarly, the
% \DescribeMacro{\AddThispageHook}|\AddThispageHook| command accepts one
% argument, however it adds it to the list of hooks that are run before
% the \emph{current} page is output.
%
% The following rules apply:
%
% \begin{enumerate}
% \item once hooks are introduced and stacked in a series, there is no way
%   to unstack them, nor to clear them;
% \item in order to have hooks that get run only when specific conditions
%   are met, conditionals must be included in the hooks;
% \item \label{itm:formatting}%
%   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 and with the appropriate
%   appearance and style. When the hooks are run, the page is still empty,
%   so that one begins filling it at point (1\,inch, 1\,inch) from the top
%   left corner;
% \item \label{itm:nospace}%
%   the hook code should \emph{eat up no space}. This means that hooks
%   meant to place some material on the page, need to have the material
%   placed in a box with zero width and height beforehand.
% \item no particular assumption is made on the \LaTeX\ output
% driver, so \Lpack{everypage} should work equally well with \LaTeX,
% \hologo{pdfLaTeX}, \hologo{LuaLaTeX}, or \hologo{XeLaTeX}. Similarly,
% 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.
% \end{enumerate}
%
% \subsection{Comparison with other packages}
% 
% The purpose of the original code base is better understood by comparing
% it to other packages that were meant to solve related problems at the
% time when \LaTeX\ had no hook mechanism of its own:
%
% \begin{itemize}
% \item In comparison with \Lpack{bobhook} by Karsten Tinnefeld,
%   Lpack{everypage} (in its legacy incarnation) used to differ in purpose
%   and in the hook implementation. Package \Lpack{everypage} was meant to
%   make no assumption on what one could want to do on every page, whether
%   to add text, images, or some low-level instruction for the output
%   driver, or even to perform some accounting task. This made the package
%   lighter and more flexible at the cost of being more difficult to
%   use. In other words, \Lpack{everypage} was meant to be more of a
%   plumbing to be employed in higher level packages;
% \item in comparison with \Lpack{watermark} by Alexander I.~Rozhenko,
%   similar considerations could me made. Specifically, \Lpack{watermark}
%   is explicitly targeted at making it easy to put watermarks on document
%   pages, while \Lpack{everypage} is lower level.
% \item in comparison to both \Lpack{bobhook} and \Lpack{watermark},
%   \Lpack{everypage} used to employ a similar low level mechanism, by
%   manipulation of the internal \LaTeX\ macro |\@begindvi| to do the
%   job. However, the redefinition of |\@begindvi| in \Lpack{everypage}
%   was postponed as much as possible, striving to avoid interference with
%   other packages using |\AtBeginDvi| or anyway manipulating
%   |\@begindvi|. Furthermore, \Lpack{everypage} made no special
%   assumption on the initial code that |\@begindvi| might contain.
% \item in comparison with \Lpack{everyshi} by Martin Schroeder,
%   \Lpack{everypage} used to be similarly low level, but relied on
%   changing the |\@begindvi| macro, rather than the even lower-level
%   |\shipout| macro.
% \end{itemize}
%
% \subsection{Known applications of the \Lpack{everypage} code}
%
% Package \Lpack{everypage} has historically found application in at least
% two higher level packages, namely:
% \begin{itemize}
% \item \Lpack{draftwatermark}, meant at providing extended facilities for
%   page watermarking on all \LaTeX\ engines and output drivers; and
% \item \Lpack{flippdf}, meant at catering for a frequent preprint
%   requirement, where publisher may require a document with
%   \emph{mirrored} pages to get the best results out of a photographic
%   printout process.
% \end{itemize}
%
% \section{The new code base}
% \changes{R2.0}{2020/10/11}{%
%   Complete package rewrite to take advantage of the new
%   LaTeX hook mechanisms introduced in the Fall 2020 release.}
%   
% The new code base differs from the old one because it does not touch
% any \LaTeX\ internals. Conversely it relies on the hook mechanism that
% is officially provided by \LaTeX\ since its 2020 fall release.
% Obviously, this has no other purpose than to provide back
% compatibility for older \LaTeX\ code written before such \LaTeX\
% release and relying on the original \Lpack{everypage} interfaces.
%
% To this aim, the new code base does the following:
% \begin{enumerate}
% \item complains out loud, reminding that new code should not be based on
%   \Lpack{everypage}, but rather make direct usage of the new \LaTeX\
%   interfaces;
% \item checks whether the new \LaTeX\ interfaces are actually
%   available. If this is not the case, it resorts to loading
%   \Lpack{everypage-1x} that provides the old code base;
% \item \label{itm:addtohook}%
%   implements/emulates the |\AddEverypageHook| and |\AddThispageHook|
%   commands on top of the new |\AddToHook| and |\AddToHookNext| \LaTeX\
%   commands.
% \end{enumerate}
%
% With specific reference to point \ref{itm:addtohook} above, note that
% the new hook mechanism provided by \LaTeX\ is extensively documented in
% issue 32 of \emph{\LaTeX\ News} and in file
% |lthooks-doc.pdf|. Furthermore, consider that \Lpack{everypage} employs
% hooks in the \emph{shipout} class, which are documented in file
% |ltshipout-doc.pdf|.
%
% \subsection{Compatibility of the new code with the original \Lpack{everypage}
%   interface}
%
% Because the implementation is different and due to choices (in fact,
% quite reasonable ones) by the \LaTeX\ developers, the new implementation
% of \Lpack{everypage} cannot be exactly equivalent to the original one
% (hence, please, do not open bugs for this!).
%
% The main difference is the hook code provided by the user now gets
% wrapped in a |\put| command, inside a |picture| environment with
% |\unitlength| at 1\,pt. This is because \Lpack{everypage} relies on a
% |shipout/background| type hook. The |\put| command typesets material at
% (1\,in, -1\,in) to emulate the original coordinate system of
% \Lpack{everypage}. This means that some of the points about the
% interface in section~\ref{ssec:ui} do not apply anymore (or at least do
% not apply in the same way). Specifically, point \ref{itm:formatting}
% about lack of any pre-canned formatting is not completely true anymore,
% because of the implicit picture environment. Furthermore, point
% \ref{itm:nospace} about the need not to eat up space can now be
% completely ignored.
%
% While the changes described above seem to go in the direction of less
% rules and less concern, this might not be always true and subtle
% breakage of legacy code may happen in corner cases.
%
% \section{Forcing usage of the older code base}
%
% The usage of the older code base of \Lpack{everypage} can be forced by
% simply substituting |\usepackage{everypage-1x}| for
% |\usepackage{everypage}|. In this case, no warning about the package
% obsolescence is emitted, because it is assumed that the user knows what
% he/she is doing. However, explicitly requiring \Lpack{everypage-1x}
% is obviously discouraged.
%
% The old code base actually works just fine with the Fall 2020 \LaTeX\
% release and it will probably keep to do so for a few more \LaTeX\
% release cycles. This is mostly up to the \LaTeX\ developers and their
% will to maintain untouched some internal deprecated interfaces. In any case,
% |\usepackage{everypage-1x}| will eventually stop working and is now
% declared in an \emph{unmaintained state}.
%
%
% \StopEventually {}
% \section{Implementation}
% \subsection{Implementation of \Lpack{everypage}}
% \iffalse
%<*everypage>
% \fi
% Announce the name and version of the package, which requires
% \LaTeXe.
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{everypage}%
  [2020/10/17 R2.0b Hooks to run on every page]
%    \end{macrocode}
% Complain out loud about the package being obsolete.
%    \begin{macrocode}
\PackageWarningNoLine{everypage}{%
  Functionality similar to this package has recently\MessageBreak
  been implemented in LaTeX. This package is now in\MessageBreak
  legacy status.\MessageBreak
  Please, don't use it in new documents and packages}
%    \end{macrocode}
% Depending on the actual functionalities provided by \LaTeX\ consider
% loading \Lpack{everypage-1x}. If so doing, warn about this too and
% stop. Otherwise give some more warnings.
%    \begin{macrocode} 
\@ifundefined{AddToHook}{%
  \PackageWarningNoLine{everypage}{%
    You appear to be running a version of LaTeX\MessageBreak
    too old to provide the new functionality.\MessageBreak
    Forcing fallback to `everypage-1x` that\MessageBreak
    uses an older code base}
  \RequirePackage{everypage-1x}
  \endinput}{%
  \PackageWarningNoLine{everypage}{%
    You appear to be running a version of LaTeX\MessageBreak
    providing the new functionality.\MessageBreak
    Doing the best to deliver the original `everypage`\MessageBreak
    interface on top of it. Strict equivalence is\MessageBreak
    not possible, breakage may occur.\MessageBreak
    If truly needed, Use `everypage-1x` to force the\MessageBreak
    loading of an older code base}}
%    \end{macrocode}
% \begin{macro}{\AddEverypageHook}\begin{macro}{\AddThispageHook}%
% Finally, implement the \Lpack{everypage} interface on top of the \LaTeX\
% |shipout/background| hooks.
%    \begin{macrocode}
\newcommand*{\AddEverypageHook}[1]{%
  \AddToHook{shipout/background}{\put(1in,-1in){#1}}}
\newcommand*{\AddThispageHook}[1]{%
  \AddToHookNext{shipout/background}{\put(1in,-1in){#1}}}
%    \end{macrocode}
% \end{macro}\end{macro}
% \iffalse
%</everypage>
% \fi
%
% \subsection{Implementation of \Lpack{everypage-1x}}
% \iffalse
%<*everypage-1x>
% \fi
% Announce the name and version of the package, which requires
% \LaTeXe.
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{everypage-1x}%
  [2020/10/10 1.2 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}
% \changes{R1.1}{2007/06/20}{%
%   Fix an out of memory condition.}
% \changes{R1.2}{2020/10/10}{%
%   Reorder operations to take care of code to execute at the beginning of
%   the output  before the `everypage' hooks.}
% 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@begindvi
    \sc@everypage@hook
    \sc@thispage@hook
    \gdef\sc@thispage@hook{}}}
%    \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}
%    \end{macrocode}
% \iffalse
%</everypage-1x>
% \fi
%
% \Finale
% \PrintChanges
% \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: