Debian Codegraph @

texmf-dist/source/latex/everypage/everypage.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright 2006-2007, 2020
4 % Sergio Callegari <[email protected]>
5 %
6 % ---------------------------------------------
7 % This file is part of the everypage package,
8 % a contribution to the LaTeX2e system.
9 % ---------------------------------------------
10 %
11 % This work may be distributed and/or modified under the
12 % conditions of the LaTeX Project Public License, version 1.3c.
13 % This license is in
14 % https://www.latex-project.org/lppl/lppl-1-3c/
15 % and is part of all distributions of LaTeX later than
16 % 2008-05-04.
17 %
18 % This work has the LPPL maintenance status "maintained".
19 %
20 % This program consists of the files listed in the README file
21 % included in the package.
22 %
23 %<*driver>
24 \documentclass{ltxdoc}
25 \usepackage{mathptmx}
26 \usepackage[T1]{fontenc}
27 \usepackage[scaled=0.92]{helvet}
28 % \usepackage{courier}
29 \usepackage{hologo}
30 \EnableCrossrefs
31 \CodelineIndex
32 \RecordChanges
33 \begin{document}
34 \DocInput{everypage.dtx}
35 \end{document}
36 %</driver>
37 %
38 % \fi
39 %
40 % \DoNotIndex{\@ifundefined, \g@addto@macro}
41 % \DoNotIndex{\def, \gdef, \let, \newcommand}
42 % \DoNotIndex{\MessageBreak, \PackageWarningNoLine, \NeedsTeXFormat}
43 % \DoNotIndex{\ProvidesPackage, \RequirePackage}
44 % \DoNotIndex{\put}
45 % \DoNotIndex{\endinput}
46 %
47 % \CheckSum{71}
48 %
49 % \def\filename{everypage.dtx}
50 % \def\fileversion{2.0b}
51 % \def\filedate{2020/10/17}
52 % \def\docdate{2020/10/17}
53 %
54 % \newcommand*{\Lpack}[1]{\textsf {#1}} ^^A typeset a package
55 % \newcommand*{\Lopt}[1]{\textsf {#1}} ^^A typeset an option
56 % \newcommand*{\file}[1]{\texttt {#1}} ^^A typeset a file
57 % \newcommand*{\Lcount}[1]{\textsl {\small#1}} ^^A typeset a counter
58 % \newcommand*{\pstyle}[1]{\textsl {#1}} ^^A typeset a pagestyle
59 % \newcommand*{\Lenv}[1]{\texttt {#1}} ^^A typeset an environment
60 %
61 % \title{The \Lpack{everypage} package\thanks{This file
62 % (\texttt{\filename}) has version number \fileversion, last
63 % revised \filedate.}}
64 %
65 % \author{%
66 % Sergio Callegari\thanks{Sergio Callegari can be reached at
67 % \texttt{sergio.callegar at gmail dot com}}}
68 %
69 % \date{\docdate}
70 %
71 % \maketitle
72 %
73 % \changes{R2.0b}{2020/10/17}{Fix statement about maintenance state.}
74 %
75 % \section*{WARNING}
76 % \changes{R2.0}{2020/10/11}{Package is now in a `legacy' status.}
77 %
78 % This package is now in \emph{legacy status}. Functionality similar to
79 % that provided by this package has been directly implemented in \LaTeX\
80 % since its 2020 Fall release. Do not use \Lpack{everypage} in new
81 % documents and do not rely on it in new packages or classes of
82 % yours.
83 %
84 % \smallskip
85 % When running on a pre-2020-10-01 version of \LaTeX, \Lpack{everypage}
86 % will now fall back to \Lpack{everypage-1x}, its own past
87 % code base.\smallskip
88 %
89 % When running on a modern \LaTeX, \Lpack{everypage} will strive to
90 % provide its legacy interfaces by using the newer \LaTeX\ facilities.
91 % However, full equivalence is not possible and breakage may occur. When
92 % truly needed, try loading \Lpack{everypage-1x} in place of
93 % \Lpack{everypage} to force usage of the old code base. This is expected
94 % to keep working for a few more \LaTeX\ release cycles after Fall 2020.
95 %
96 % \bigskip\bigskip
97 %
98 % \begin{abstract}
99 % The \Lpack{everypage} package was meant to extend \LaTeX\ providing
100 % hooks to do actions on every page or on the current page. Currently,
101 % similar functionality is directly provided by \LaTeX. Specifically,
102 % \Lpack{everypage} supports actions performed \emph{before} the page is
103 % shipped, so they can be used to put watermarks \emph{in the
104 % background} of a page, or to set the page layout. The package is in
105 % many ways similar to \Lpack{bobhook} by Karsten Tinnefeld, but it
106 % differs in the way in which the hooks are implemented. In some sense,
107 % it may also be related to package \Lpack{everyshi} by Martin
108 % Schroeder, but again the implementation is different.
109 % \end{abstract}
110 %
111 % \section{Introduction}
112 %
113 % Until a recent past, \LaTeX\ provided no explicit hooks to be run as
114 % documents pages were finalized and output to the dvi or pdf
115 % file. Consequently, many solutions were developed to work around this
116 % limitation and to offer features (e.g., watermarks) that would otherwise
117 % be impossible. These solution included packages such as
118 % \Lpack{everyshi}, \Lpack{bobhook} and \Lpack{watermark}. Package
119 % \Lpack{everypage} was a solution providing plumbing that could be used
120 % in higher level packages such as \Lpack{draftwatermark} (watermarking)
121 % and \Lpack{flippdf} (print preprocessing) to mention a couple of them.
122 %
123 % All of these extensions relied on applying modifications to some \LaTeX\
124 % internals and as such were prone to subtle interactions with other
125 % packages and breakage. The situation has been cleared by the 2020 Fall
126 % \LaTeX\ release where an official and generic support for hooks has been
127 % introduced.
128 %
129 % As of today, \Lpack{everypage} can be considered obsolete. It needs to
130 % remain around because older releases of \LaTeX\ are still in use and
131 % legacy code exist that is based on the interfaces it exposes. However,
132 % no new document, class or package should be based on it. Furthermore, it
133 % can be expected that existing packages that use \Lpack{everypage} will
134 % progressively learn to rely directly on the new \LaTeX\ hook mechanism.
135 %
136 % This manual is meant to aid the transition by showing how
137 % \Lpack{everypage} is now being updated to cater both for older and newer
138 % \LaTeX\ kernels. Specifically, it illustrates:
139 % \begin{enumerate}
140 % \item how \Lpack{everypage} is now actually split in two packages:
141 % \Lpack{everypage-1x}, providing the old code base; and
142 % \Lpack{everypage} itself, that strives to implement the legacy
143 % interface on top of the new mechanisms offered by \LaTeX;
144 % \item how \Lpack{everypage} can automatically import the old code base
145 % as needed, how loading of the latter can be forced (if absolutely
146 % needed or for comparison) and for how long the old code can be
147 % expected to keep working with newer releases of \LaTeX;
148 % \item how the legacy interface of \Lpack{everypage}, once
149 % implemented/emulated on top of the new \LaTeX\ facilities actually
150 % differs from its nominal behavior.
151 % \end{enumerate}
152 %
153 % \section{The original code base}
154 % \label{sec:original}
155 % \changes{R1.0}{2006/06/30}{%
156 % Initial release.}
157 %
158 % The original implementation of \Lpack{everypage}, now available as
159 % \Lpack{everypage-1x}, adds two \LaTeX\ hooks that get
160 % run when document pages are finalized and output to the dvi or pdf
161 % file. Specifically, one hook gets executed on every page, while the
162 % other is executed for the current page. Hook actions are are performed
163 % \emph{before} the page is output on the medium, and this is important to
164 % be able to play with the page layout or to put things \emph{behind} the
165 % page contents (e.g., watermarks).
166 %
167 % \subsection{User interface}
168 % \label{ssec:ui}
169 %
170 % \DescribeMacro{\AddEverypageHook} The |\AddEverypageHook| command
171 % accepts one argument and adds it to the list of hooks that are run
172 % before every page is output. Similarly, the
173 % \DescribeMacro{\AddThispageHook}|\AddThispageHook| command accepts one
174 % argument, however it adds it to the list of hooks that are run before
175 % the \emph{current} page is output.
176 %
177 % The following rules apply:
178 %
179 % \begin{enumerate}
180 % \item once hooks are introduced and stacked in a series, there is no way
181 % to unstack them, nor to clear them;
182 % \item in order to have hooks that get run only when specific conditions
183 % are met, conditionals must be included in the hooks;
184 % \item \label{itm:formatting}%
185 % there is no formatting inherent in the hooks. If one wants to put some
186 % watermark on a page, it is his own duty to put in the hook the code to
187 % place the watermark in the right position and with the appropriate
188 % appearance and style. When the hooks are run, the page is still empty,
189 % so that one begins filling it at point (1\,inch, 1\,inch) from the top
190 % left corner;
191 % \item \label{itm:nospace}%
192 % the hook code should \emph{eat up no space}. This means that hooks
193 % meant to place some material on the page, need to have the material
194 % placed in a box with zero width and height beforehand.
195 % \item no particular assumption is made on the \LaTeX\ output
196 % driver, so \Lpack{everypage} should work equally well with \LaTeX,
197 % \hologo{pdfLaTeX}, \hologo{LuaLaTeX}, or \hologo{XeLaTeX}. Similarly,
198 % the package should work equally well with dvi, dvips, etc.\@ output
199 % drivers. Obviously, the final compatibility with the different output
200 % drivers depends on the actual code that is placed in the hooks.
201 % \end{enumerate}
202 %
203 % \subsection{Comparison with other packages}
204 %
205 % The purpose of the original code base is better understood by comparing
206 % it to other packages that were meant to solve related problems at the
207 % time when \LaTeX\ had no hook mechanism of its own:
208 %
209 % \begin{itemize}
210 % \item In comparison with \Lpack{bobhook} by Karsten Tinnefeld,
211 % Lpack{everypage} (in its legacy incarnation) used to differ in purpose
212 % and in the hook implementation. Package \Lpack{everypage} was meant to
213 % make no assumption on what one could want to do on every page, whether
214 % to add text, images, or some low-level instruction for the output
215 % driver, or even to perform some accounting task. This made the package
216 % lighter and more flexible at the cost of being more difficult to
217 % use. In other words, \Lpack{everypage} was meant to be more of a
218 % plumbing to be employed in higher level packages;
219 % \item in comparison with \Lpack{watermark} by Alexander I.~Rozhenko,
220 % similar considerations could me made. Specifically, \Lpack{watermark}
221 % is explicitly targeted at making it easy to put watermarks on document
222 % pages, while \Lpack{everypage} is lower level.
223 % \item in comparison to both \Lpack{bobhook} and \Lpack{watermark},
224 % \Lpack{everypage} used to employ a similar low level mechanism, by
225 % manipulation of the internal \LaTeX\ macro |\@begindvi| to do the
226 % job. However, the redefinition of |\@begindvi| in \Lpack{everypage}
227 % was postponed as much as possible, striving to avoid interference with
228 % other packages using |\AtBeginDvi| or anyway manipulating
229 % |\@begindvi|. Furthermore, \Lpack{everypage} made no special
230 % assumption on the initial code that |\@begindvi| might contain.
231 % \item in comparison with \Lpack{everyshi} by Martin Schroeder,
232 % \Lpack{everypage} used to be similarly low level, but relied on
233 % changing the |\@begindvi| macro, rather than the even lower-level
234 % |\shipout| macro.
235 % \end{itemize}
236 %
237 % \subsection{Known applications of the \Lpack{everypage} code}
238 %
239 % Package \Lpack{everypage} has historically found application in at least
240 % two higher level packages, namely:
241 % \begin{itemize}
242 % \item \Lpack{draftwatermark}, meant at providing extended facilities for
243 % page watermarking on all \LaTeX\ engines and output drivers; and
244 % \item \Lpack{flippdf}, meant at catering for a frequent preprint
245 % requirement, where publisher may require a document with
246 % \emph{mirrored} pages to get the best results out of a photographic
247 % printout process.
248 % \end{itemize}
249 %
250 % \section{The new code base}
251 % \changes{R2.0}{2020/10/11}{%
252 % Complete package rewrite to take advantage of the new
253 % LaTeX hook mechanisms introduced in the Fall 2020 release.}
254 %
255 % The new code base differs from the old one because it does not touch
256 % any \LaTeX\ internals. Conversely it relies on the hook mechanism that
257 % is officially provided by \LaTeX\ since its 2020 fall release.
258 % Obviously, this has no other purpose than to provide back
259 % compatibility for older \LaTeX\ code written before such \LaTeX\
260 % release and relying on the original \Lpack{everypage} interfaces.
261 %
262 % To this aim, the new code base does the following:
263 % \begin{enumerate}
264 % \item complains out loud, reminding that new code should not be based on
265 % \Lpack{everypage}, but rather make direct usage of the new \LaTeX\
266 % interfaces;
267 % \item checks whether the new \LaTeX\ interfaces are actually
268 % available. If this is not the case, it resorts to loading
269 % \Lpack{everypage-1x} that provides the old code base;
270 % \item \label{itm:addtohook}%
271 % implements/emulates the |\AddEverypageHook| and |\AddThispageHook|
272 % commands on top of the new |\AddToHook| and |\AddToHookNext| \LaTeX\
273 % commands.
274 % \end{enumerate}
275 %
276 % With specific reference to point \ref{itm:addtohook} above, note that
277 % the new hook mechanism provided by \LaTeX\ is extensively documented in
278 % issue 32 of \emph{\LaTeX\ News} and in file
279 % |lthooks-doc.pdf|. Furthermore, consider that \Lpack{everypage} employs
280 % hooks in the \emph{shipout} class, which are documented in file
281 % |ltshipout-doc.pdf|.
282 %
283 % \subsection{Compatibility of the new code with the original \Lpack{everypage}
284 % interface}
285 %
286 % Because the implementation is different and due to choices (in fact,
287 % quite reasonable ones) by the \LaTeX\ developers, the new implementation
288 % of \Lpack{everypage} cannot be exactly equivalent to the original one
289 % (hence, please, do not open bugs for this!).
290 %
291 % The main difference is the hook code provided by the user now gets
292 % wrapped in a |\put| command, inside a |picture| environment with
293 % |\unitlength| at 1\,pt. This is because \Lpack{everypage} relies on a
294 % |shipout/background| type hook. The |\put| command typesets material at
295 % (1\,in, -1\,in) to emulate the original coordinate system of
296 % \Lpack{everypage}. This means that some of the points about the
297 % interface in section~\ref{ssec:ui} do not apply anymore (or at least do
298 % not apply in the same way). Specifically, point \ref{itm:formatting}
299 % about lack of any pre-canned formatting is not completely true anymore,
300 % because of the implicit picture environment. Furthermore, point
301 % \ref{itm:nospace} about the need not to eat up space can now be
302 % completely ignored.
303 %
304 % While the changes described above seem to go in the direction of less
305 % rules and less concern, this might not be always true and subtle
306 % breakage of legacy code may happen in corner cases.
307 %
308 % \section{Forcing usage of the older code base}
309 %
310 % The usage of the older code base of \Lpack{everypage} can be forced by
311 % simply substituting |\usepackage{everypage-1x}| for
312 % |\usepackage{everypage}|. In this case, no warning about the package
313 % obsolescence is emitted, because it is assumed that the user knows what
314 % he/she is doing. However, explicitly requiring \Lpack{everypage-1x}
315 % is obviously discouraged.
316 %
317 % The old code base actually works just fine with the Fall 2020 \LaTeX\
318 % release and it will probably keep to do so for a few more \LaTeX\
319 % release cycles. This is mostly up to the \LaTeX\ developers and their
320 % will to maintain untouched some internal deprecated interfaces. In any case,
321 % |\usepackage{everypage-1x}| will eventually stop working and is now
322 % declared in an \emph{unmaintained state}.
323 %
324 %
325 % \StopEventually {}
326 % \section{Implementation}
327 % \subsection{Implementation of \Lpack{everypage}}
328 % \iffalse
329 %<*everypage>
330 % \fi
331 % Announce the name and version of the package, which requires
332 % \LaTeXe.
333 % \begin{macrocode}
334 \NeedsTeXFormat{LaTeX2e}
335 \ProvidesPackage{everypage}%
336 [2020/10/17 R2.0b Hooks to run on every page]
337 % \end{macrocode}
338 % Complain out loud about the package being obsolete.
339 % \begin{macrocode}
340 \PackageWarningNoLine{everypage}{%
341 Functionality similar to this package has recently\MessageBreak
342 been implemented in LaTeX. This package is now in\MessageBreak
343 legacy status.\MessageBreak
344 Please, don't use it in new documents and packages}
345 % \end{macrocode}
346 % Depending on the actual functionalities provided by \LaTeX\ consider
347 % loading \Lpack{everypage-1x}. If so doing, warn about this too and
348 % stop. Otherwise give some more warnings.
349 % \begin{macrocode}
350 \@ifundefined{AddToHook}{%
351 \PackageWarningNoLine{everypage}{%
352 You appear to be running a version of LaTeX\MessageBreak
353 too old to provide the new functionality.\MessageBreak
354 Forcing fallback to `everypage-1x` that\MessageBreak
355 uses an older code base}
356 \RequirePackage{everypage-1x}
357 \endinput}{%
358 \PackageWarningNoLine{everypage}{%
359 You appear to be running a version of LaTeX\MessageBreak
360 providing the new functionality.\MessageBreak
361 Doing the best to deliver the original `everypage`\MessageBreak
362 interface on top of it. Strict equivalence is\MessageBreak
363 not possible, breakage may occur.\MessageBreak
364 If truly needed, Use `everypage-1x` to force the\MessageBreak
365 loading of an older code base}}
366 % \end{macrocode}
367 % \begin{macro}{\AddEverypageHook}\begin{macro}{\AddThispageHook}%
368 % Finally, implement the \Lpack{everypage} interface on top of the \LaTeX\
369 % |shipout/background| hooks.
370 % \begin{macrocode}
371 \newcommand*{\AddEverypageHook}[1]{%
372 \AddToHook{shipout/background}{\put(1in,-1in){#1}}}
373 \newcommand*{\AddThispageHook}[1]{%
374 \AddToHookNext{shipout/background}{\put(1in,-1in){#1}}}
375 % \end{macrocode}
376 % \end{macro}\end{macro}
377 % \iffalse
378 %</everypage>
379 % \fi
380 %
381 % \subsection{Implementation of \Lpack{everypage-1x}}
382 % \iffalse
383 %<*everypage-1x>
384 % \fi
385 % Announce the name and version of the package, which requires
386 % \LaTeXe.
387 % \begin{macrocode}
388 \NeedsTeXFormat{LaTeX2e}
389 \ProvidesPackage{everypage-1x}%
390 [2020/10/10 1.2 Hooks to run on every page]
391 % \end{macrocode}
392 %
393 % \begin{macro}{\sc@everypage@hook}\begin{macro}{\sc@everypage@hook}
394 % Define internal macros to hold the hooks and initialize them to
395 % contain nothing.
396 % \begin{macrocode}
397 \newcommand{\sc@everypage@hook}{}
398 \newcommand{\sc@thispage@hook}{}
399 % \end{macrocode}
400 % \end{macro}\end{macro}
401 %
402 % \begin{macro}{\AddEverypageHook}\begin{macro}{\AddThispageHook}
403 % Define the commands used to add the hooks.
404 % \begin{macrocode}
405 \newcommand*{\AddEverypageHook}[1]{%
406 \g@addto@macro\sc@everypage@hook{#1}}
407 \newcommand*{\AddThispageHook}[1]{%
408 \g@addto@macro\sc@thispage@hook{#1}}
409 % \end{macrocode}
410 % \end{macro}\end{macro}
411 %
412 % \begin{macro}{\sc@ep@init}
413 % The internal initialization code of the package. The package works
414 % by redefining the normal |\@outputpage| routine that takes care of
415 % outputting pages, so that the modified version first calls a special
416 % preamble, and then calls the original |\@outputpage| code and
417 % finally a postamble.
418 % \begin{macrocode}
419 \newcommand*{\sc@ep@init}{%
420 \let\sc@op@saved\@outputpage
421 \def\@outputpage{%
422 \sc@op@preamble
423 \sc@op@saved
424 \sc@op@postamble}}
425 % \end{macrocode}
426 % \end{macro}
427 %
428 % \begin{macro}{\sc@op@preamble}
429 % \changes{R1.1}{2007/06/20}{%
430 % Fix an out of memory condition.}
431 % \changes{R1.2}{2020/10/10}{%
432 % Reorder operations to take care of code to execute at the beginning of
433 % the output before the `everypage' hooks.}
434 % The outputpage preamble contains instructions to redefine the
435 % |\@begindvi| macro that is called at every page output by the
436 % original |\@outputpage| code.
437 % Specifically: first the original |\@begindvi| is saved; then the
438 % hooks are called; then the hooks for the current page
439 % are cleared; eventually, the saved |\@begindvi| is called.
440 % \begin{macrocode}
441 \newcommand*{\sc@op@preamble}{%
442 \let\sc@begindvi\@begindvi
443 \def\@begindvi{%
444 \sc@begindvi
445 \sc@everypage@hook
446 \sc@thispage@hook
447 \gdef\sc@thispage@hook{}}}
448 % \end{macrocode}
449 % \end{macro}
450 %
451 % \begin{macro}{\sc@op@postamble}
452 % The outputpage postamble simply restores the |\@begindvi| command to
453 % the saved value.
454 % \begin{macrocode}
455 \newcommand*{\sc@op@postamble}{%
456 \let\@begindvi\sc@begindvi}
457 % \end{macrocode}
458 % Note that in exceptional cases this might not be the intended
459 % behaviour. For instance, consider situations where
460 % the |\@begindvi| is hacked by some other package to modify
461 % itself. By restoring the saved value, one might lose the
462 % modifications. This potential issue is currently under
463 % investigation.
464 % \end{macro}
465 %
466 % As the very last thing, the |\AtBeginDocument| macro is called to
467 % insert the \Lpack{everypage} initialization routine in the queue of
468 % commands to be executed when the actual document begins. In this
469 % way, the \Lpack{everypage} initialization code is run \emph{after}
470 % other packages are loaded.
471 % \begin{macrocode}
472 \AtBeginDocument{\sc@ep@init}
473 % \end{macrocode}
474 % \iffalse
475 %</everypage-1x>
476 % \fi
477 %
478 % \Finale
479 % \PrintChanges
480 % \PrintIndex
481 %
482 % \CharacterTable
483 % {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
484 % 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
485 % Digits \0\1\2\3\4\5\6\7\8\9
486 % Exclamation \! Double quote \" Hash (number) \#
487 % Dollar \$ Percent \% Ampersand \&
488 % Acute accent \' Left paren \( Right paren \)
489 % Asterisk \* Plus \+ Comma \,
490 % Minus \- Point \. Solidus \/
491 % Colon \: Semicolon \; Less than \<
492 % Equals \= Greater than \> Question mark \?
493 % Commercial at \@ Left bracket \[ Backslash \\
494 % Right bracket \] Circumflex \^ Underscore \_
495 % Grave accent \` Left brace \{ Vertical bar \|
496 % Right brace \} Tilde \~}
497 \endinput
498
499 % %% Local Variables:
500 % %% mode: doctex
501 % %% TeX-master: t
502 % %% End: