The eso-pic package∗

Rolf Niepraschk
[email protected]

1 Introduction
This package makes it easy to add some picture commands to every page at ab-
solute positions.

2 Usage
See also the example LATEX documents (eso-*.tex).

2.1 Basic commands for adding LATEX stuff to the page

background
\AddToShipoutPictureBG All the picture commands which are parameters of an \AddToShipoutPictureBG
command will be added to the internal macro \ESO@HookIBG. This macro is part
of a zero-length picture environment with basepoint at the lower left corner of
the page (default) or at the upper left corner (package option ”texcoord”). The
picture environment will be shipped out at every new page.
\AddToShipoutPictureBG* \AddToShipoutPictureBG* works like \AddToShipoutPictureBG but only for
the current page. It used the internal macro \ESO@HookIIBG which contents will
be removed automatically.
For compatibility the macros \AddToShipoutPicture and \AddToShipoutPicture*
are aliases for \AddToShipoutPictureBG and \AddToShipoutPictureBG*.
\AddToShipoutPictureFG Works like \AddToShipoutPictureBG but the picture commands are on the
\AddToShipoutPictureFG* top oft the normal document content.
\ClearShipoutPictureBG A call of \ClearShipoutPictureBG clears the contents of \ESO@HookIBG.
For compatibility the macro \ClearShipoutPicture is an alias for
\ClearShipoutPictureBG.
\ClearShipoutPictureFG A call of \ClearShipoutPictureFG clears the contents of \ESO@HookIFG.
\LenToUnit Allows a length as parameter to a picture command. Note that this macro is
no more necessary when using \usepackage{picture}.
\gridSetup \gridSetup[hgridunitnamei]{hgriduniti}{hlabelfactor i}{hgriddeltai}
{hgridDeltai}{hgapi}. For details see the implementation section.

∗ This document corresponds to eso-pic v2.0c, dated 2010/10/06.

1
 \AtPageUpperLeft Helper macros for easier positioning on the page.
\AtPageLowerLeft
\AtPageCenter 2.2 Package options
\AtTextUpperLeft
\AtTextLowerLeft Option Value Comments
\AtTextCenter pscoord empty or true, false The zero point of the coordinate system
\AtStockUpperLeft is the lower left corner of the page (the
\AtStockLowerLeft default).
\AtStockCenter texcoord empty or true, false The zero point of the coordinate system
is the upper left corner of the page.
grid empty or true, false A grid is drawing; default: false.
gridunit mm, in, bp, pt Distance between gridlines are multiples
of gridunit. default: mm.
gridcolor a valid color name Color of the main gridlines; default:
black
subgridcolor a valid color name Color of the subgridlines; default: black.
subgridstyle solid or dotted ‘dotted’ is very slow! default: solid.
colorgrid empty or true, false Shortcut for ‘grid=true’, ‘gridcolor=red’
and ‘subgridcolor=green’; default: false.
dvips empty or true, false Is also true if the package option dvips is
used by color or graphics. If true package
eepic is loaded for better performance of
dotted lines.

3 Implementation
3.1 The main functionality
1 \RequirePackage{atbegshi}
\LenToUnit
2 \providecommand*\LenToUnit[1]{#1\@gobble}

\ESO@isMEMOIR Support for the memoir class.

3 \newcommand\ESO@isMEMOIR[2]{#2}
4 \@ifclassloaded{memoir}{\renewcommand\ESO@isMEMOIR[2]{#1}}{}

\AtPageUpperLeft
5\newcommand\AtPageUpperLeft[1]{%
6 \put(0,\LenToUnit{-\ESO@yoffsetI}){#1}%
7}

\AtPageLowerLeft
8 \newcommand\AtPageLowerLeft[1]{\AtPageUpperLeft{%
9 \put(0,\LenToUnit{-\paperheight}){#1}}}

\AtPageCenter
10 \newcommand\AtPageCenter[1]{\AtPageUpperLeft{%
11 \put(\LenToUnit{.5\paperwidth},\LenToUnit{-.5\paperheight}){#1}}%
12 }

2
\AtStockLowerLeft
13 \newcommand\AtStockLowerLeft{}
14 \ESO@isMEMOIR{%
15 \renewcommand\AtStockLowerLeft[1]{%
16 \begingroup
17 \@tempdima=-\stockwidth
18 \advance\@tempdima\trimedge
19 \advance\@tempdima\paperwidth
20 \if@twoside\ifodd\c@page\else
21 \@tempdima=-\trimedge
22 \fi\fi
23 \@tempdimb=-\stockheight
24 \advance\@tempdimb\paperheight
25 \advance\@tempdimb\trimtop
26 \AtPageLowerLeft{%
27 \put(\LenToUnit{\@tempdima},\LenToUnit{\@tempdimb}){#1}%
28 }%
29 \endgroup
30 }
31 }{%
32 \let\AtStockLowerLeft=\AtPageLowerLeft
33 }

\AtStockUpperLeft
34 \newcommand\AtStockUpperLeft{}
35 \ESO@isMEMOIR{%
36 \renewcommand\AtStockUpperLeft[1]{%
37 \AtStockLowerLeft{%
38 \put(0,\LenToUnit{\stockheight}){#1}%
39 }%
40 }%
41 }{%
42 \let\AtStockUpperLeft=\AtPageUpperLeft
43 }

\AtStockCenter
44 \newcommand\AtStockCenter{}
45 \ESO@isMEMOIR{%
46 \renewcommand\AtStockCenter[1]{%
47 \AtStockLowerLeft{%
48 \put(\LenToUnit{.5\stockwidth},\LenToUnit{.5\stockheight}){#1}%
49 }%
50 }%
51 }{%
52 \let\AtStockCenter=\AtPageCenter
53 }

\AtTextUpperLeft
54 \ESO@isMEMOIR{%
55 \newcommand\AtTextUpperLeft[1]{%
56 \begingroup
57 \ifodd\c@page
58 \@tempdima=\spinemargin
59 \else

3
 60 \@tempdima=\paperwidth
61 \advance\@tempdima-\textwidth
62 \advance\@tempdima-\spinemargin
63 \fi
64 \@tempdimb=-\uppermargin
65 \AtPageUpperLeft{%
66 \put(\LenToUnit{\@tempdima},\LenToUnit{\@tempdimb}){#1}%
67 }%
68 \endgroup
69 }
70 }{%
71 \newcommand\AtTextUpperLeft[1]{%
72 \begingroup
73 \@tempdima=1in\relax
74 \ifodd\c@page
75 \advance\@tempdima\oddsidemargin
76 \else
77 \advance\@tempdima\evensidemargin
78 \fi
79 \@tempdimb=-1in\relax
80 \advance\@tempdimb-\topmargin
81 \advance\@tempdimb-\headheight
82 \advance\@tempdimb-\headsep
83 \AtPageUpperLeft{%
84 \put(\LenToUnit{\@tempdima},\LenToUnit{\@tempdimb}){#1}%
85 }%
86 \endgroup
87 }
88 }

\AtTextLowerLeft
89 \newcommand\AtTextLowerLeft[1]{\AtTextUpperLeft{%
90 \put(0,\LenToUnit{-\textheight}){#1}}}

\AtTextCenter
91 \newcommand\AtTextCenter[1]{\AtTextUpperLeft{%
92 \put(\LenToUnit{.5\textwidth},\LenToUnit{-.5\textheight}){#1}}}

\ESO@HookIBG
\ESO@HookIIBG 93 \newcommand{\ESO@HookIBG}{}
\ESO@HookIIIBG 94 \newcommand{\ESO@HookIIBG}{}
\ESO@HookIFG 95 \newcommand{\ESO@HookIIIBG}{}
\ESO@HookIIFG 96 \newcommand{\ESO@HookIFG}{}
97 \newcommand{\ESO@HookIIFG}{}
98 \newcommand{\ESO@HookI}{}
99 \newcommand{\ESO@HookII}{}
100 \newcommand{\ESO@HookIII}{}
101 \let\ESO@HookI=\ESO@HookIBG
102 \let\ESO@HookII=\ESO@HookIIBG
103 \let\ESO@HookIII=\ESO@HookIIIBG

\AddToShipoutPictureBG
\AddToShipoutPictureFG 104 \newcommand{\AddToShipoutPictureBG}{%
105 \@ifstar{\g@addto@macro\ESO@HookIIBG}{\g@addto@macro\ESO@HookIBG}}

4
 106 \newcommand{\AddToShipoutPicture}{}
107 \let\AddToShipoutPicture=\AddToShipoutPictureBG

\AddToShipoutPictureFG
108 \newcommand{\AddToShipoutPictureFG}{%
109 \@ifstar{\g@addto@macro\ESO@HookIIFG}{\g@addto@macro\ESO@HookIFG}}

\ClearShipoutPictureBG
\ClearShipoutPicture 110 \newcommand{\ClearShipoutPictureBG}{\global\let\ESO@HookIBG\@empty}
\ClearShipoutPictureFG 111 \newcommand{\ClearShipoutPicture}{}
112 \let\ClearShipoutPicture=\ClearShipoutPictureBG
113 \newcommand{\ClearShipoutPictureFG}{\global\let\ESO@HookIFG\@empty}

\AtBeginShipout (see package atbegshi)

\AtBeginShipoutUpperLeft 114 \ESO@isMEMOIR{%
ginShipoutUpperLeftForeground 115 \AtBeginShipout{%
116 \@tempdima=-\trimedge
117 \advance\@tempdima-\paperwidth
118 \advance\@tempdima\stockwidth
119 \if@twoside\ifodd\c@page\else
120 \advance\@tempdima2\trimedge
121 \advance\@tempdima\paperwidth
122 \advance\@tempdima-\stockwidth
123 \fi\fi
124 \@tempdimb=\ESO@yoffsetI
125 \advance\@tempdimb-\trimtop
126 \nointerlineskip
127 \AtBeginShipoutUpperLeft{%
128 \put(\LenToUnit{\@tempdima},\LenToUnit{\@tempdimb}){%
129 \ESO@HookIIIBG\ESO@HookIBG\ESO@HookIIBG
130 \global\let\ESO@HookIIBG\@empty
131 }%
132 }%
133 \AtBeginShipoutUpperLeftForeground{%
134 \put(\LenToUnit{\@tempdima},\LenToUnit{\@tempdimb}){%
135 \ESO@HookIFG\ESO@HookIIFG
136 \global\let\ESO@HookIIFG\@empty
137 }%
138 }%
139 }
140 }{%
141 \AtBeginShipout{%
142 \nointerlineskip
143 \AtBeginShipoutUpperLeft{%
144 \put(0,\LenToUnit{\ESO@yoffsetI}){%
145 \ESO@HookIIIBG\ESO@HookIBG\ESO@HookIIBG
146 \global\let\ESO@HookIIBG\@empty
147 }%
148 }%
149 \AtBeginShipoutUpperLeftForeground{%
150 \put(0,\LenToUnit{\ESO@yoffsetI}){%
151 \ESO@HookIFG\ESO@HookIIFG
152 \global\let\ESO@HookIIFG\@empty
153 }%

5
 154 }%
155 }
156 }

3.2 The background grid

157 \RequirePackage{keyval}
Initialising some macros
158 \newif\ifESO@dvips\ESO@dvipsfalse \newif\ifESO@grid\ESO@gridfalse
159 \newif\ifESO@texcoord\ESO@texcoordfalse
160 \newcommand*\ESO@gridunitname{}
161 \newcommand*\ESO@gridunit{}
162 \newcommand*\ESO@labelfactor{}
163 \newcommand*\ESO@griddelta{}\newcommand*\ESO@griddeltaY{}
164 \newcommand*\ESO@gridDelta{}\newcommand*\ESO@gridDeltaY{}
165 \newcommand*\ESO@gridcolor{}
166 \newcommand*\ESO@subgridcolor{}
167 \newcommand*\ESO@subgridstyle{dotted}% ???
168 \newcommand*\ESO@gap{}
169 \newcommand*\ESO@yoffsetI{}\newcommand*\ESO@yoffsetII{}
170 \newcommand*\ESO@gridlines{\thinlines}
171 \newcommand*\ESO@subgridlines{\thinlines}
172 \newcommand*\ESO@hline[1]{\ESO@subgridlines\line(1,0){#1}}
173 \newcommand*\ESO@vline[1]{\ESO@subgridlines\line(0,1){#1}}
174 \newcommand*\ESO@Hline[1]{\ESO@gridlines\line(1,0){#1}}
175 \newcommand*\ESO@Vline[1]{\ESO@gridlines\line(0,1){#1}}
176 \newcommand\ESO@fcolorbox[4][]{\fbox{#4}}
177 \newcommand\ESO@color[1]{}
178 \newcommand\ESO@colorbox[3][]{%
179 \begingroup
180 \fboxrule=\z@\fbox{#3}%
181 \endgroup
182 }

\gridSetup
183 \newcommand\gridSetup[6][]{%
184 \edef\ESO@gridunitname{#1}\edef\ESO@gridunit{#2}
185 \edef\ESO@labelfactor{#3}\edef\ESO@griddelta{#4}
186 \edef\ESO@gridDelta{#5}\edef\ESO@gap{#6}}

All the key-value options

187 \define@key{ESO}{texcoord}[true]{\csname ESO@texcoord#1\endcsname}
188 \define@key{ESO}{pscoord}[true]{\csname @tempswa#1\endcsname
189 \if@tempswa\ESO@texcoordfalse\else\ESO@texcoordtrue\fi}
190 \define@key{ESO}{dvips}[true]{\csname ESO@dvips#1\endcsname}
191 \define@key{ESO}{grid}[true]{\csname ESO@grid#1\endcsname
192 \setkeys{ESO}{gridcolor=black,subgridcolor=black}}
193 \define@key{ESO}{colorgrid}[true]{\csname ESO@grid#1\endcsname
194 \setkeys{ESO}{gridcolor=red,subgridcolor=green}}
195 \define@key{ESO}{gridcolor}{\def\ESO@gridcolor{#1}}
196 \define@key{ESO}{subgridcolor}{\def\ESO@subgridcolor{#1}}
197 \define@key{ESO}{subgridstyle}{\def\ESO@subgridstyle{#1}}%
198 \define@key{ESO}{gridunit}{%
199 \def\@tempa{#1}

6
 200 \def\@tempb{bp}
201 \ifx\@tempa\@tempb
202 \gridSetup[\@tempa]{1bp}{1}{10}{50}{2}
203 \else
204 \def\@tempb{pt}
205 \ifx\@tempa\@tempb
206 \gridSetup[\@tempa]{\p@}{1}{10}{50}{2}
207 \else
208 \def\@tempb{in}
209 \ifx\@tempa\@tempb
210 \gridSetup[\@tempa]{.1in}{.1}{2}{10}{.5}
211 \else
212 \gridSetup[mm]{1mm}{1}{5}{20}{1}
213 \fi
214 \fi
215 \fi
216 }
217 \setkeys{ESO}{subgridstyle=solid,pscoord=true,gridunit=mm}

\ProcessOptionsWithKV This macro can process package options using ‘key=value’ syntax.
218 \def\ProcessOptionsWithKV#1{%
219 \let\@tempc\@empty
220 \@for\CurrentOption:=\@classoptionslist\do{%
221 \@ifundefined{KV@#1@\CurrentOption}%
222 {}{\edef\@tempc{\@tempc,\CurrentOption,}}}%
223 \edef\@tempc{%
224 \noexpand\setkeys{#1}{\@tempc\@ptionlist{\@currname.\@currext}}}%
225 \@tempc
226 \AtEndOfPackage{\let\@unprocessedoptions\relax}}%

227 \ProcessOptionsWithKV{ESO}%

\ESO@div Divides length #1 by #2 × \ESO@gridunit and adds one. Result is in \@tempcnta.

228 \newcommand\ESO@div[2]{%
229 \@tempdima=#1\relax\@tempdimb=\ESO@gridunit\relax
230 \@tempdimb=#2\@tempdimb\divide\@tempdima by \@tempdimb
231 \@tempcnta\@tempdima\advance\@tempcnta\@ne}

232 \@ifundefined{colorbox}{%
233 \IfFileExists{xcolor.sty}{\RequirePackage{xcolor}}%
234 {\RequirePackage{color}}%
235 }{}%
236 \let\ESO@color=\color
237 \let\ESO@colorbox=\colorbox
238 \let\ESO@fcolorbox=\fcolorbox
239 \AtBeginDocument{%
240 \ESO@dvipsfalse
241 \@ifundefined{Gin@driver}{}%
242 {%
243 \ifx\Gin@driver\@empty\else%
244 \filename@parse{\Gin@driver}\def\reserved@a{dvips}%
245 \ifx\filename@base\reserved@a\ESO@dvipstrue\fi
246 \fi
247 }%

7
 248 \ifESO@dvips\def\@tempb{eepic}\else\def\@tempb{epic}\fi
249 \def\@tempa{dotted}%\def\ESO@gap{\LenToUnit{6\@wholewidth}}%
250 \ifx\@tempa\ESO@subgridstyle
251 \IfFileExists{\@tempb.sty}%
252 {%
253 \RequirePackage{\@tempb}
254 \renewcommand*\ESO@hline[1]{\ESO@subgridlines\dottedline{\ESO@gap}%
255 (0,0)(##1,0)}
256 \renewcommand*\ESO@vline[1]{\ESO@subgridlines\dottedline{\ESO@gap}%
257 (0,0)(0,##1)}
258 }{}
259 \else
260 \ifx\ESO@gridcolor\ESO@subgridcolor
261 \renewcommand*\ESO@gridlines{\thicklines}
262 \fi
263 \fi
264 }
265 \ifESO@texcoord
266 \def\ESO@yoffsetI{\z@}\def\ESO@yoffsetII{-\paperheight}
267 \edef\ESO@griddeltaY{-\ESO@griddelta}\edef\ESO@gridDeltaY{-\ESO@gridDelta}
268 \else
269 \def\ESO@yoffsetI{-\paperheight}\def\ESO@yoffsetII{\z@}
270 \edef\ESO@griddeltaY{\ESO@griddelta}\edef\ESO@gridDeltaY{\ESO@gridDelta}
271 \fi

\ESO@gridpicture
272 \newcommand\ESO@gridpicture{%
273 \begingroup
274 \setlength\unitlength{\ESO@gridunit}%
275 \ESO@color{\ESO@subgridcolor}%
— horizontal subgrid lines —
276 \ESO@div{\paperheight}{\ESO@griddelta}%
277 \multiput(0,0)(0,\ESO@griddeltaY){\@tempcnta}%
278 {\ESO@hline{\LenToUnit{\paperwidth}}}%
— vertical subgrid lines —
279 \ESO@div{\paperwidth}{\ESO@griddelta}%
280 \multiput(0,\LenToUnit{\ESO@yoffsetII})(\ESO@griddelta,0){\@tempcnta}%
281 {\ESO@vline{\LenToUnit{\paperheight}}}%
282 \ESO@color{\ESO@gridcolor}%
— horizontal grid lines —
283 \ESO@div{\paperheight}{\ESO@gridDelta}%
284 \multiput(0,0)(0,\ESO@gridDeltaY){\@tempcnta}%
285 {\ESO@Hline{\LenToUnit{\paperwidth}}}%
— vertical grid lines —
286 \ESO@div{\paperwidth}{\ESO@gridDelta}%
287 \multiput(0,\LenToUnit{\ESO@yoffsetII})(\ESO@gridDelta,0){\@tempcnta}%
288 {\ESO@Vline{\LenToUnit{\paperheight}}}%
— horizontal numbers —
289 \fontsize{10}{12}\normalfont%
290 \ESO@div{\paperwidth}{\ESO@gridDelta}%
291 \multiput(0,\ESO@gridDeltaY)(\ESO@gridDelta,0){\@tempcnta}{%

8
292 \@tempcntb=\@tempcnta\advance\@tempcntb-\@multicnt
293 \ifnum\@tempcntb>1\relax
294 \multiply\@tempcntb by \ESO@gridDelta\relax
295 \@tempdima=\@tempcntb sp\@tempdima=\ESO@labelfactor\@tempdima
296 \@tempcntb=\@tempdima%
297 \makebox(0,0)[c]{\ESO@colorbox{white}{\the\@tempcntb}}%
298 \fi}%
— vertical numbers —
299 \ifx\ESO@gridunitname\@empty\def\@tempa{0}\else\def\@tempa{1}\fi
300 \ESO@div{\paperheight}{\ESO@gridDelta}%
301 \multiput(\ESO@gridDelta,0)(0,\ESO@gridDeltaY){\@tempcnta}{%
302 \@tempcntb=\@tempcnta\advance\@tempcntb-\@multicnt%
303 \ifnum\@tempcntb>\@tempa\relax
304 \multiply\@tempcntb by \ESO@gridDelta\relax%
305 \@tempdima=\@tempcntb sp\@tempdima=\ESO@labelfactor\@tempdima
306 \@tempcntb=\@tempdima
307 \makebox(0,0)[c]{\ESO@colorbox{white}{\the\@tempcntb}}%
308 \fi
309 }%
— the unit label —
310 \ifx\ESO@gridunitname\@empty\else
311 \thicklines\fboxrule=\@wholewidth
312 \put(\ESO@gridDelta,\ESO@gridDeltaY){\makebox(0,0)[c]{%
313 \ESO@fcolorbox{\ESO@gridcolor}{white}{%
314 \textbf{\ESO@gridunitname}}}}%
315 \fi
316 \normalcolor%
317 \endgroup
318 }

Add the grid to the shipout picture (\ESO@HookIIIBG is independed from the user
commands \AddToShipoutPictureBG and \AddToShipoutPictureBG*).
319 \ifESO@grid\g@addto@macro\ESO@HookIIIBG{\ESO@gridpicture}\fi

Change History

v0.4 \LenToUnit, \AtPageUpperLeft,

General: Initial version . . . . . . . . 1 \AtPageCenter, \AtTextUpperLeft,
v0.5 and \AtTextCenter. . . . . . . . . 1
General: Some bug corrections . . . 1 v1.0a
v0.6 \ClearShipoutPictureFG: Changed
General: Some corrections for com- \let to \global\let (sug-
patibility with the html package gested by Alberto Lusiani). . . . 5
suggested by Ross Moore and a v1.0c
licence note . . . . . . . . . . . . . . 1 General: New command
v0.7 \AtTextLowerLeft and correc-
General: New command tions to \AtTextUpperLeft. . . . 1
\AddToShipoutPicture* . . . . . 1 v1.0d
v1.0 \LenToUnit: Using \providecommand
General: New commands instead of \newcommand for

9
 \LenToUnit . . . . . . . . . . . . . . 2 using with XeLATEX should be
v1.1 possible. . . . . . . . . . . . . . . . . . 7
General: New commands and pack- v2.0a
age options for background General: Better test of color/xcolor 7
grids. . . . . . . . . . . . . . . . . . . . 1 \AtStockCenter: New . . . . . . . . . 3
v1.1a \AtStockLowerLeft: New . . . . . . . 3
\AtStockUpperLeft: New . . . . . . . 3
\ESO@gridpicture: Font setting
\AtTextUpperLeft: Works now for
added. . . . . . . . . . . . . . . . . . . 8
class memoir . . . . . . . . . . . . . . 3
v1.1b
v2.0b
General: New command \AddToShipoutPictureFG: New
\AtPageLowerLeft . . . . . . . . . 1 command \AddToShipoutPictureFG
New package options ”texcoord” ........................ 4
and ”pscoord” . . . . . . . . . . . . 1 v2.0c
v1.1c \AtBeginShipoutUpperLeftForeground:
General: Remove the disadvanta- bugfix for memoir class (re-
geous check of ‘pdfTeX’. Now ported by YI Hoze) . . . . . . . . . 5

10