The everyshi package^{∗}

Martin Schröder

Crüsemannallee 3 28213 Bremen Germany martin@oneiros.de

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

2001/05/15

Abstract

This packages provides hooks into \sshipout called \EveryShipout

     and \AtNextShipout analogous to \AtBeginDocument.

Contents

1 Introduction 1

2 Usage 1

3 Options 2

4 Required packages 2 5 The implementation 2 5.1 Allocations . . . . . . 2 5.2 The user-visible com-

mands . . . . . . . . . 2 5.3 Inserting the hooks . . 2

6 Acknowledgements 4

1 Introduction

This package provides the hooks \EveryShipout and \AtNextShipout whose arguments are 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[2].

Another application is a package for adding pictures to every page: esopic[1].

2 Usage

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

∗The version umber of this file is v3.00, last revised 2001/05/15.

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

Warning: The ⟨code⟩ is saved globally; there is currently no way to remove it.

\AtNextShipout \AtNextShipout{⟨code⟩} declares ⟨code⟩ that is saved internally and

New feature 2001/05/15

executed just before only the next \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 the commands is permitted: the code in the argument is stored (and executed) in the order of their declarations.

The argument of \AtNextShipout is executed after the argument of

\EveryShipout.

3 Options

The package has no options.

4 Required packages

The package does not require any further packages.

5 The implementation

1 ⟨∗package⟩

5.1 Allocations

First we allocate the hooks

\@EveryShipout@Hook The code to be executed before \shipout is stored in

\@EveryShipout@Hook.
 2 \newcommand{\@EveryShipout@Hook}{}

\@EveryShipout@AtNextHook The code to be executed just before the normal \shipout and

\@EveryShipout@EveryHook.
 3 \newcommand{\@EveryShipout@AtNextHook}{}

5.2 The user-visible commands

\EveryShipout \AtNextShipout The commands are modeled after \AtBeginDocument.
 4 \newcommand*{\EveryShipout}[1]
 5 {\g@addto@macro\@EveryShipout@Hook{#1}}
 6 \newcommand*{\AtNextShipout}[1]
 7 {\g@addto@macro\@EveryShipout@AtNextHook{#1}}

5.3 Inserting the hooks

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.
 8 \newcommand{\@EveryShipout@Shipout}{%
 9 \afterassignment\@EveryShipout@Test
10 \global\setbox\@cclv= %

11 }

\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.
12 \newcommand{\@EveryShipout@Test}{%
13 \ifvoid\@cclv\relax
14  \aftergroup\@EveryShipout@Output
15 \else
16  \@EveryShipout@Output
17 \fi%

18 }

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

accumulated via \EveryShipout and \AtNextShipout is called and then

the original \shipout stored in \@EveryShipout@Org@Shipout is called to

finally ship out \box255.

19 \newcommand{\@EveryShipout@Output}{%
20 \@EveryShipout@Hook%
21 \@EveryShipout@AtNextHook%

We have to reset \@EveryShipout@AtNextHook after each use.

22  \gdef\@EveryShipout@AtNextHook{}%
23 \@EveryShipout@Org@Shipout\box\@cclv%

24 }

\@EveryShipout@Org@Shipout The original \shipout is stored in \@EveryShipout@Org@Shipout by
\@EveryShipout@Init. Here we allocate it.
25 \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.
26 \newcommand*{\@EveryShipout@Init}{%
27 \message{ABD: EveryShipout initializing macros}%
28 \let\@EveryShipout@Org@Shipout\shipout
29 \let\shipout\@EveryShipout@Shipout

30 }

31 \AtBeginDocument{\@EveryShipout@Init}

6 ACKNOWLEDGEMENTS 4

32 ⟨/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] Rolf Niepraschk. The eso-pic package. CTAN:tex-archive/macros/

   latex/contrib/supported/ms/contrib/eso-pic.dtx. L^{A}TEX 2ε

package.

[2] 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; numbers underlined refer to the code line of the definition; numbers in roman refer to the code lines where the entry is used.

Symbols

\@EveryShipout@AtNextHook . . .

. . . . . . . . . . . . . . \underline{3}, 7, 21, 22

\@EveryShipout@Hook . . . . . \underline{2}, 5, 20
\@EveryShipout@Init . . . . . . . . . \underline{26}
\@EveryShipout@Org@Shipout . .

. . . . . . . . . . . . . . . 23, \underline{25}, 28

\@EveryShipout@Output . 14, 16, \underline{19}
\@EveryShipout@Shipout . . . . \underline{8}, 29
\@EveryShipout@Test . . . . . . . 9, \underline{12}

\@cclv . . . . . . . . . . . . . . 10, 13, 23

A

\afterassignment . . . . . . . . . . . . 9

\aftergroup . . . . . . . . . . . . . . . . 14

\AtBeginDocument . . . . . . . . . . . 31

\AtNextShipout . . . . . . . . . . . . 2, \underline{4}

B

\box . . . . . . . . . . . . . . . . . . . . . . 23

E

\else . . . . . . . . . . . . . . . . . . . . . 15 \EveryShipout . . . . . . . . . . . . . . . \underline{4}

F \fi . . . . . . . . . . . . . . . . . . . . . . 17

G \g@addto@macro . . . . . . . . . . . . 5, 7 \gdef . . . . . . . . . . . . . . . . . . . . . 22 \global . . . . . . . . . . . . . . . . . . . 10

I \ifvoid . . . . . . . . . . . . . . . . . . . 13

L \let . . . . . . . . . . . . . . . . . . . 28, 29

M \message . . . . . . . . . . . . . . . . . . 27

N \newcommand . 2–4, 6, 8, 12, 19, 25, 26

R \relax . . . . . . . . . . . . . . . . . . . . 13

S \setbox . . . . . . . . . . . . . . . . . . . 10 \shipout . . . . . . . . . . . . . . . 28, 29

Change History 5

Change History

v1.00

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

\AtNextShipout: \newcommand

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

General: Name changed from at-

shipou to everyshi . . . . . . . 1

\AtNextShipout:  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 . 3
\@EveryShipout@Test: new . . . 3

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 v3.00

                                    \@EveryShipout@AtNextHook:

new . . . . . . . . . . . . . . . . . 2

                                    \@EveryShipout@Hook: \newcommand

. . . . . . . . . . . . . . . . . . . . . 2

                                    \@EveryShipout@Init: output

message . . . . . . . . . . . . . . 3

                                    \@EveryShipout@Output: added
                                       call to \@EveryShipout@AtNextHook

. . . . . . . . . . . . . . . . . . . . . 3

                                    General:  \AtNextShipout

added . . . . . . . . . . . . . . . . 1 Reference to eso-pic added . . 1

                                    \AtNextShipout: \AtNextShipout

added . . . . . . . . . . . . . . . . 2