Debian Codegraph @

texmf-dist/doc/latex/pgfmorepages/pgfmorepages.tex

raw
1 \documentclass{ltxdoc}
2
3 \usepackage{tikz}
4 \usetikzlibrary{positioning}
5 \usepackage{pgfmorepages}
6 \usepackage{fancyvrb}
7
8 \GetFileInfo{pgfmorepages.sty}
9
10 \title{PGF \emph{more} Pages}
11 \author{Andrew Stacey \\ \texttt{[email protected]}}
12 \date{\fileversion\ from \filedate}
13
14 \begin{document}
15
16 \maketitle
17
18 \section{Introduction}
19
20 The \Verb+pgfmorepages+ package is a drop-in replacement for the \Verb+pgfpages+ package which comes with TikZ/PGF.
21 As it is a drop-in replacement, it \emph{ought} to be fully backwards compatible with \Verb+pgfpages+.
22
23 \Verb+pgfpages+ allows you the ability to place several pages of your document (hereafter \emph{logical pages}) onto one page of the output (hereafter \emph{physical pages}).
24 \Verb+pgfmorepages+ adds extra features, the primary one being that whereas \Verb+pgfpages+ is ``many to one'', \Verb+pgfmorepages+ is ``many to many''.
25 That is, while \Verb+pgfpages+ works one physical page at a time then \Verb+pgfmorepages+ can juggle several logical pages onto several physical pages.
26
27 As an example of its capability, the layout \Verb+4 on 2, book format+ places four logical pages onto two physical pages so that when folded it forms a booklet.
28 The layout is therefore:
29
30 \begin{center}
31 \begin{tikzpicture}
32 \node at (0,0) {\(4\)};
33 \node at (1,0) {\(1\)};
34 \node at (3,0) {\(2\)};
35 \node at (4,0) {\(3\)};
36 \draw (-.5,-.7) rectangle (.5,.7);
37 \draw (1,0) +(-.5,-.7) rectangle +(.5,.7);
38 \draw (3,0) +(-.5,-.7) rectangle +(.5,.7);
39 \draw (4,0) +(-.5,-.7) rectangle +(.5,.7);
40 \end{tikzpicture}
41 \end{center}
42
43 This requires knowing all four logical pages before the first physical page is output.
44
45 \section{Usage}
46
47 In your preamble:
48
49 \begin{verbatim}
50 \usepackage{pgfmorepages}
51 \end{verbatim}
52
53 \subsection{Layouts}
54
55 The original \Verb+pgfpages+ defined the following layouts:
56
57 \begin{itemize}
58 \item \Verb+rounded corners+
59 \item \Verb+resize to+
60 \item \Verb+two screens with lagging second+
61 \item \Verb+two screens with optional second+
62 \item \Verb+2 on 1+
63 \item \Verb+4 on 1+
64 \item \Verb+6 on 1+
65 \item \Verb+8 on 1+
66 \item \Verb+16 on 1+
67 \end{itemize}
68
69 The \Verb+pgfmorepages+ defines some extra layouts, which require the following command in your preamble:
70 %
71 \begin{verbatim}
72 \pgfmorepagesloadextralayouts
73 \end{verbatim}
74
75 \begin{itemize}
76 \item \Verb+4 on 2, odd then even+
77
78 \begin{center}
79 \begin{tikzpicture}
80 \node at (0,0) {\(1\)};
81 \node at (1,0) {\(3\)};
82 \node at (3,0) {\(2\)};
83 \node at (4,0) {\(4\)};
84 \draw (-.5,-.7) rectangle (.5,.7);
85 \draw (1,0) +(-.5,-.7) rectangle +(.5,.7);
86 \draw (3,0) +(-.5,-.7) rectangle +(.5,.7);
87 \draw (4,0) +(-.5,-.7) rectangle +(.5,.7);
88 \end{tikzpicture}
89 \end{center}
90
91 \item \Verb+4 on 2, even then odd+
92
93 \begin{center}
94 \begin{tikzpicture}
95 \node at (0,0) {\(2\)};
96 \node at (1,0) {\(4\)};
97 \node at (3,0) {\(1\)};
98 \node at (4,0) {\(3\)};
99 \draw (-.5,-.7) rectangle (.5,.7);
100 \draw (1,0) +(-.5,-.7) rectangle +(.5,.7);
101 \draw (3,0) +(-.5,-.7) rectangle +(.5,.7);
102 \draw (4,0) +(-.5,-.7) rectangle +(.5,.7);
103 \end{tikzpicture}
104 \end{center}
105
106 \item \Verb+4 on 2, book format+
107
108 \begin{center}
109 \begin{tikzpicture}
110 \node at (0,0) {\(4\)};
111 \node at (1,0) {\(1\)};
112 \node at (3,0) {\(2\)};
113 \node at (4,0) {\(3\)};
114 \draw (-.5,-.7) rectangle (.5,.7);
115 \draw (1,0) +(-.5,-.7) rectangle +(.5,.7);
116 \draw (3,0) +(-.5,-.7) rectangle +(.5,.7);
117 \draw (4,0) +(-.5,-.7) rectangle +(.5,.7);
118 \end{tikzpicture}
119 \end{center}
120
121 \item \Verb+8 on 4, book format+
122
123 \begin{center}
124 \begin{tikzpicture}
125 \node at (0,0) {\(8\)};
126 \node at (1,0) {\(1\)};
127 \node at (3,0) {\(2\)};
128 \node at (4,0) {\(7\)};
129 \node at (6,0) {\(6\)};
130 \node at (7,0) {\(3\)};
131 \node at (9,0) {\(4\)};
132 \node at (10,0) {\(5\)};
133 \draw (-.5,-.7) rectangle (.5,.7);
134 \draw (1,0) +(-.5,-.7) rectangle +(.5,.7);
135 \draw (3,0) +(-.5,-.7) rectangle +(.5,.7);
136 \draw (4,0) +(-.5,-.7) rectangle +(.5,.7);
137 \draw (6,0) +(-.5,-.7) rectangle +(.5,.7);
138 \draw (7,0) +(-.5,-.7) rectangle +(.5,.7);
139 \draw (9,0) +(-.5,-.7) rectangle +(.5,.7);
140 \draw (10,0) +(-.5,-.7) rectangle +(.5,.7);
141 \end{tikzpicture}
142 \end{center}
143
144 \item \Verb+8 on 4, book format, reverse second, single sided+
145
146 \begin{center}
147 \begin{tikzpicture}
148 \node at (0,0) {\(8\)};
149 \node at (1,0) {\(1\)};
150 \node at (3,0) {\(6\)};
151 \node at (4,0) {\(3\)};
152 \node[rotate=180] at (6,0) {\(5\)};
153 \node[rotate=180] at (7,0) {\(4\)};
154 \node[rotate=180] at (9,0) {\(7\)};
155 \node[rotate=180] at (10,0) {\(2\)};
156 \draw (-.5,-.7) rectangle (.5,.7);
157 \draw (1,0) +(-.5,-.7) rectangle +(.5,.7);
158 \draw (3,0) +(-.5,-.7) rectangle +(.5,.7);
159 \draw (4,0) +(-.5,-.7) rectangle +(.5,.7);
160 \draw (6,0) +(-.5,-.7) rectangle +(.5,.7);
161 \draw (7,0) +(-.5,-.7) rectangle +(.5,.7);
162 \draw (9,0) +(-.5,-.7) rectangle +(.5,.7);
163 \draw (10,0) +(-.5,-.7) rectangle +(.5,.7);
164 \end{tikzpicture}
165 \end{center}
166
167
168 \item \Verb+5 index cards+
169 \item \Verb+repeated 2-up+
170
171 \begin{center}
172 \begin{tikzpicture}
173 \node at (0,0) {\(1\)};
174 \node at (1,0) {\(1\)};
175 \node at (3,0) {\(2\)};
176 \node at (4,0) {\(2\)};
177 \draw (-.5,-.7) rectangle (.5,.7);
178 \draw (1,0) +(-.5,-.7) rectangle +(.5,.7);
179 \draw (3,0) +(-.5,-.7) rectangle +(.5,.7);
180 \draw (4,0) +(-.5,-.7) rectangle +(.5,.7);
181 \end{tikzpicture}
182 \end{center}
183
184 \item \Verb+repeated 4-up+
185
186 \begin{center}
187 \begin{tikzpicture}
188 \node at (0,0) {\(1\)};
189 \node at (1,0) {\(1\)};
190 \node at (0,1.4) {\(1\)};
191 \node at (1,1.4) {\(1\)};
192 \node at (3,0) {\(2\)};
193 \node at (4,0) {\(2\)};
194 \node at (3,1.4) {\(2\)};
195 \node at (4,1.4) {\(2\)};
196 \draw (-.5,-.7) rectangle (.5,.7);
197 \draw (1,0) +(-.5,-.7) rectangle +(.5,.7);
198 \draw (3,0) +(-.5,-.7) rectangle +(.5,.7);
199 \draw (4,0) +(-.5,-.7) rectangle +(.5,.7);
200 \draw (0,1.4) +(-.5,-.7) rectangle +(.5,.7);
201 \draw (1,1.4) +(-.5,-.7) rectangle +(.5,.7);
202 \draw (3,1.4) +(-.5,-.7) rectangle +(.5,.7);
203 \draw (4,1.4) +(-.5,-.7) rectangle +(.5,.7);
204 \end{tikzpicture}
205 \end{center}
206
207
208 \item \Verb+1 on 1+
209
210 This is a layout that ``resets'' the mechanism back to one logical page on one physical page.
211 It still uses the mechanics of the \Verb+pgfmorepages+ package so is not quite the same as removing it altogether, but is effectively the same.
212
213 \item \Verb+discard+
214
215 This layout discards all its pages.
216 Useful to remove pages from a document without changing the source file too much.
217
218 \end{itemize}
219
220 To use a layout, use the command:
221 %
222 \begin{verbatim}
223 \pgfpagesuselayout{<layout name>}[<optional arguments>]
224 \end{verbatim}
225
226
227
228 \subsection{Options}
229
230 The optional arguments are a superset of the ones that \Verb+pgfpages+ allows.
231
232 \begin{itemize}
233 \item \Verb+physical paper width+
234 \item \Verb+physical paper height+
235 \item \Verb+a0paper+
236 \item \Verb+a1paper+
237 \item \Verb+a2paper+
238 \item \Verb+a3paper+
239 \item \Verb+a4paper+
240 \item \Verb+a5paper+
241 \item \Verb+a6paper+
242 \item \Verb+letterpaper+
243 \item \Verb+legalpaper+
244 \item \Verb+executivepaper+
245 \item \Verb+landscape+
246 \item \Verb+border shrink+
247 \item \Verb+border code+
248 \item \Verb+corner width+
249 \item \Verb+odd numbered pages right+
250 \item \Verb+second right+
251 \item \Verb+second left+
252 \item \Verb+second top+
253 \item \Verb+second bottom+
254 \end{itemize}
255
256 The only additional option is \Verb+border code+ which, if the layout does anything with it, is designed for passing a command to the layout for the border path.
257 The intention of this is that sometimes it is useful to draw the page border when designing a document but you might want to disable it for the final version.
258 This makes it easy to switch between those (providing the layout supports it).
259
260 \subsection{Changing Layout}
261
262 The documentation for \Verb+pgfpages+ states that it is possible to change layout mid-document.
263 This turns out not to be correct for \Verb+pgfpages+ as it doesn't reset everything correctly.
264 \Verb+pgfmorepages+ fixes this\footnote{Or tries to -- I keep discovering new options that I haven't reset properly.}.
265 It is best practice to use a \Verb+\newpage+ or \Verb+\clearpage+ before doing so.
266 The layout \Verb+1 on 1+ is useful here as it sets the layout back to one logical page on one physical page.
267
268 \section{Defining a New Layout}
269
270 The best way to define a new layout is to start with one of the predefined ones and modify it.
271 To that end, here is an example layout with comments.
272
273 \begin{verbatim}
274 % Set the name of the layout
275 \pgfpagesdeclarelayout{4 on 2, book format}%
276 {%
277 % Unless overridden, this layout uses the same paper size
278 % but rotated so that two logical pages fit naturally on
279 % one physical page
280 \edef\pgfpageoptionheight{\the\paperwidth}
281 \edef\pgfpageoptionwidth{\the\paperheight}
282 % Defaults for the border
283 \def\pgfpageoptionborder{0pt}
284 \def\pgfpageoptionbordercode{}
285 % Start with the first page of the document
286 \def\pgfpageoptionfirstshipout{1}
287 }%
288 {%
289 % These are the settings for the physical pages
290 \pgfpagesphysicalpageoptions
291 {%
292 % Each set consists of 4 logical and 2 physical pages
293 logical pages=4,%
294 physical pages=2,%
295 physical height=\pgfpageoptionheight,%
296 physical width=\pgfpageoptionwidth,%
297 current logical shipout=\pgfpageoptionfirstshipout%
298 }
299 % These are the settings for the logical pages.
300 % These hold for all the logical pages.
301 \pgfpagessetdefaults{%
302 border code=\pgfpageoptionbordercode
303 }
304 % Our arrangement is different for two portrait pages
305 % on one landscape as opposed to two landscape on
306 % one portrait.
307 % This is for two portrait on one landscape
308 \ifdim\paperheight>\paperwidth\relax
309 % put side-by-side
310 % There are several ways to declare which logical page
311 % goes on which physical page. This command sets the
312 % physical page for the following logical pages. The
313 % second argument is any options to be set for that
314 % physical page.
315 \pgfpagesphysicalpage{1}{}
316 % Our fourth logical page goes on the first physical page
317 \pgfpageslogicalpageoptions{4}
318 {%
319 border shrink=\pgfpageoptionborder,%
320 resized width=.5\pgfphysicalwidth,%
321 resized height=\pgfphysicalheight,%
322 center=\pgfpoint{.25\pgfphysicalwidth}{.5\pgfphysicalheight}%
323 }%
324 % The second and third logical pages go on the second
325 % physical page.
326 \pgfpagesphysicalpage{2}{}
327 \pgfpageslogicalpageoptions{3}
328 {%
329 border shrink=\pgfpageoptionborder,%
330 resized width=.5\pgfphysicalwidth,%
331 resized height=\pgfphysicalheight,%
332 center=\pgfpoint{.75\pgfphysicalwidth}{.5\pgfphysicalheight}%
333 }%
334 \pgfpageslogicalpageoptions{2}
335 {%
336 border shrink=\pgfpageoptionborder,%
337 resized width=.5\pgfphysicalwidth,%
338 resized height=\pgfphysicalheight,%
339 center=\pgfpoint{.25\pgfphysicalwidth}{.5\pgfphysicalheight}%
340 }%
341 % The first logical page goes back on the first physical page.
342 \pgfpagesphysicalpage{1}{}
343 \pgfpageslogicalpageoptions{1}
344 {%
345 border shrink=\pgfpageoptionborder,%
346 resized width=.5\pgfphysicalwidth,%
347 resized height=\pgfphysicalheight,%
348 center=\pgfpoint{.75\pgfphysicalwidth}{.5\pgfphysicalheight}%
349 }%
350 \else
351 % These are essentially the same as above, except with
352 % two landscape pages on one portrait, so the pages
353 % are in different locations.
354 % stack on top of one another
355 \pgfpagesphysicalpage{1}{}
356 \pgfpageslogicalpageoptions{4}
357 {%
358 border shrink=\pgfpageoptionborder,%
359 resized width=\pgfphysicalwidth,%
360 resized height=.5\pgfphysicalheight,%
361 center=\pgfpoint{.5\pgfphysicalwidth}{.75\pgfphysicalheight}%
362 }%
363 \pgfpagesphysicalpage{2}{}
364 \pgfpageslogicalpageoptions{3}
365 {%
366 border shrink=\pgfpageoptionborder,%
367 resized width=\pgfphysicalwidth,%
368 resized height=.5\pgfphysicalheight,%
369 center=\pgfpoint{.5\pgfphysicalwidth}{.25\pgfphysicalheight}%
370 }%
371 \pgfpageslogicalpageoptions{2}
372 {%
373 border shrink=\pgfpageoptionborder,%
374 resized width=\pgfphysicalwidth,%
375 resized height=.5\pgfphysicalheight,%
376 center=\pgfpoint{.5\pgfphysicalwidth}{.75\pgfphysicalheight}%
377 }%
378 \pgfpagesphysicalpage{2}{}
379 \pgfpageslogicalpageoptions{1}
380 {%
381 border shrink=\pgfpageoptionborder,%
382 resized width=\pgfphysicalwidth,%
383 resized height=.5\pgfphysicalheight,%
384 center=\pgfpoint{.5\pgfphysicalwidth}{.25\pgfphysicalheight}%
385 }%
386 \fi
387 }
388 \end{verbatim}
389
390 \end{document}