The everyshi package^{∗}

Martin Schröder

Crüsemannallee 3 D-28213 Bremen Martin.Schroeder@ACM.org

                           PGP-Key:  2048 bit / KeyID 292814E5
                        7E86 6EC8 97FA 2995  82C3 FEA5 2719 090E

1999/06/08

Abstract

This package defines a new command \EveryShipout analogous to \AtBeginDocument etc., whose argument is executed before each

     \shipout.

Contents

1 Introduction 1

2 Usage 1

3 Options 2 4 Required packages 2

5 The implementation 2

6 Acknowledgements 3

1 Introduction

This package provides the hook \EveryShipout whose argument is executed after the output routine has constructed \box255, and before \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: prelim2e[1].

2 Usage

\EveryShipout{⟨code⟩} declares ⟨code⟩ that is saved internally and executed before each \shipout.

The ⟨code⟩ is executed after \box255 has been constructed by the output routine and can change \box255. \shipout is called after ⟨code⟩.

Repeated use of this command is permitted: the code in the argument is stored (and executed) in the order of their declarations.

∗The version umber of this file is v2.03, last revised 1999/06/08.

The name everyshi is a tribute to the 8 + 3 file-naming convention of certain “operating systems”; strictly speaking it should be everyshipout.

3 Options

The package has no options.

4 Required packages

The package does not require any further packages.

5 The implementation

1 ⟨∗package⟩

\@EveryShipout@Hook The code to be executed before \shipout is stored in \@EveryShipout@Hook.
 2 \let\@EveryShipout@Hook\@empty
\EveryShipout  \EveryShipout is modeled after \AtBeginDocument.
 3 \newcommand{\EveryShipout}{\g@addto@macro\@EveryShipout@Hook}

We want to redefine \shipout so that first \box255 is constructed and after that we can do something and at last shipout the (possible modified) \box255. Alas, this does not work in the usual way, since \shipout is a TEX primitive whose argument is a ⟨box⟩. This means that simply redefining \shipout via \newcommand[1] is impossible since ⟨box⟩ can be something like \box255 or something like \vbox{...}. In the first case #1 would be ⟨\box ⟩ (without ⟨255 ⟩); in the second case it would be ⟨\vbox ⟩ (without ⟨{… }⟩).

The solution we use here is borrowed from quire.tex by Marcel R. van

der Goot. It is based upon \afterassignment and \aftergroup.
\@EveryShipout@Shipout  \@EveryShipout@Shipout is our replacement for \shipout.
 4 \newcommand{\@EveryShipout@Shipout}{%
 5 \afterassignment\@EveryShipout@Test
 6 \global\setbox\@cclv= %
 7 }

\box255 is set to whatever comes after \shipout; but after that assignment

\@EveryShipout@Test is called.
\@EveryShipout@Test  \@EveryShipout@Test determines if \shipout is called with an argument

like \box255 or something like \vbox{...}. In the later case we delay the call of \@EveryShipout@Output (where the original \shipout is called) via

\aftergroup.
 8 \newcommand{\@EveryShipout@Test}{%
 9 \ifvoid\@cclv\relax
10  \aftergroup\@EveryShipout@Output
11 \else
12  \@EveryShipout@Output
13 \fi%

\@EveryShipout@Output  \@EveryShipout@Output does the actual work. First the ⟨code⟩ accumu-

lated via \EveryShipout is called and then the original \shipout stored in

\@EveryShipout@Org@Shipout is called to finally ship out \box255.
15 \newcommand{\@EveryShipout@Output}{%
16 \@EveryShipout@Hook%
17 \@EveryShipout@Org@Shipout\box\@cclv%

18 }

\@EveryShipout@Org@Shipout The original \shipout is stored in \@EveryShipout@Org@Shipout by
\@EveryShipout@Init. Here we allocate it.
19 \newcommand{\@EveryShipout@Org@Shipout}{}
\@EveryShipout@Init  \@EveryShipout@Init  stores  the  original  \shipout  in
\@EveryShipout@Org@Shipout  and  sets  \shipout  to
\@EveryShipout@Shipout. This is done at \begin{document} via
\AtBeginDocument.
20 \newcommand*{\@EveryShipout@Init}{%
21 \let\@EveryShipout@Org@Shipout\shipout
22 \let\shipout\@EveryShipout@Shipout

23 }

24 \AtBeginDocument{\@EveryShipout@Init}

25 ⟨/package⟩

6 Acknowledgements

Version 2.0 of everyshi borrows heavily from quire.tex of the Midnight Macros by Marcel R. van der Goot (marcel@cs.caltech.edu). The pointer to quire was provided by Lothar Meyer-Lerbs (TEXSatz@zfn.uni-bremen.de). As usual Rebecca Stiels improved the quality of this documentation.

References

[1] Martin Schröder. The prelim2e package. CTAN:

   tex-archive/macros/latex/contrib/supported/ms/prelim2e.dtx.

L^{A}TEX 2ε package.

Index

Numbers written in italic refer to the page where the corresponding entry is described, the ones underlined to the code line of the definition, the rest to the code lines where the entry is used.

Symbols

\@EveryShipout@Hook . . . . . \underline{2}, 3, 16
\@EveryShipout@Init . . . . . . . . . \underline{20}
\@EveryShipout@Org@Shipout . .

. . . . . . . . . . . . . . . 17, \underline{19}, 21

\@EveryShipout@Output . 10, 12, \underline{15}

                                    \@EveryShipout@Shipout . . . . \underline{4}, 22
                                    \@EveryShipout@Test . . . . . . . . 5, \underline{8}

\@cclv . . . . . . . . . . . . . . . . 6, 9, 17 \@empty . . . . . . . . . . . . . . . . . . . . 2

A

                                    \afterassignment . . . . . . . . . . . . 5

Change History 4

\aftergroup . . . . . . . . . . . . . . . . 10

\AtBeginDocument . . . . . . . . . . . 24

B

\box . . . . . . . . . . . . . . . . . . . . . . 17

E

\else . . . . . . . . . . . . . . . . . . . . . 11 \EveryShipout . . . . . . . . . . . . . . . \underline{3}

F

\fi . . . . . . . . . . . . . . . . . . . . . . 13

G

\g@addto@macro . . . . . . . . . . . . . . 3 \global . . . . . . . . . . . . . . . . . . . . 6

I \ifvoid . . . . . . . . . . . . . . . . . . . . 9

L \let . . . . . . . . . . . . . . . . . 2, 21, 22

N \newcommand . . . . . 3, 4, 8, 15, 19, 20

R \relax . . . . . . . . . . . . . . . . . . . . . 9

S \setbox . . . . . . . . . . . . . . . . . . . . 6 \shipout . . . . . . . . . . . . . . . 21, 22

Change History

v1.00

General: New . . . . . . . . . . . . . 1 v1.01

   \EveryShipout: \newcommand

instead of \def . . . . . . . . . 2 v1.02

General: Name changed from at-

shipou to everyshi . . . . . . . 1

   \EveryShipout: Name changed
      from  \AtShipout  to
      \EveryShipOut . . . . . . . . . 2

v1.03

General: Documentation im-

proved . . . . . . . . . . . . . . . 1 v2.00

   \@EveryShipout@Hook: Name
      changed from \@shipouthook

                                          to \@EveryShipout@Hook . . 2
                                       \@EveryShipout@Init: new . . . 3
                                       \@EveryShipout@Org@Shipout:

new . . . . . . . . . . . . . . . . . 3

                                       \@EveryShipout@Output: new . 3
                                       \@EveryShipout@Shipout: new . 2
                                       \@EveryShipout@Test: new . . . 2

General: Redesign . . . . . . . . . . 1 v2.01

General: Fixed use of \newline

in title. . . . . . . . . . . . . . . . 1 v2.02

General: Documentation im-

proved . . . . . . . . . . . . . . . 1 v2.03

General: Moved to LPPL . . . . . 1