Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-pages.tex

raw
1 % Copyright 2019 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Page Management}
12
13 This section describes the |pgfpages| package. Although this package is not
14 concerned with creating pictures, its implementation relies so heavily on
15 \pgfname\ that it is documented here. Currently, |pgfpages| only works with
16 \LaTeX, but if you are adventurous, feel free to hack the code so that it also
17 works with plain \TeX.
18
19 The aim of |pgfpages| is to provide a flexible way of putting multiple pages on
20 a single page \emph{inside \TeX}. Thus, |pgfpages| is quite different from
21 useful tools like |psnup| or |pdfnup| insofar as it creates its output in a
22 single pass. Furthermore, it works uniformly with both |latex| and |pdflatex|,
23 making it easy to put multiple pages on a single page without any fuss.
24
25 A word of warning: \emph{using |pgfpages| will destroy hyperlinks}. Actually,
26 the hyperlinks are not destroyed, only they will appear at totally wrong
27 positions on the final output. This is due to a fundamental flaw in the \pdf\
28 specification: In \pdf\ the bounding rectangle of a hyperlink is given in
29 ``absolute page coordinates'' and translations or rotations do not affect them.
30 Thus, the transformations applied by |pgfpages| to put the pages where you want
31 them are (cannot, even) be applied to the coordinates of hyperlinks. It is
32 unlikely that this will change in the foreseeable future.
33
34
35 \subsection{Basic Usage}
36
37 The internals of |pgfpages| are complex since the package can do all sorts of
38 interesting tricks. For this reason, so-called \emph{layouts} are predefined
39 that set up all option in appropriate ways.
40
41 You use a layout as follows:
42 %
43 \begin{codeexample}[code only]
44 \documentclass{article}
45
46 \usepackage{pgfpages}
47 \pgfpagesuselayout{2 on 1}[a4paper,landscape,border shrink=5mm]
48
49 \begin{document}
50 This text is shown on the left.
51 \clearpage
52 This text is shown on the right.
53 \end{document}
54 \end{codeexample}
55
56 The layout |2 on 1| puts two pages on a single page. The option |a4paper| tells
57 |pgfpages| that the \emph{resulting} page (called the \emph{physical} page in
58 the following) should be |a4paper| and it should be landscape (which is quite
59 logical since putting two portrait pages next to each other gives a landscape
60 page). Normally, the \emph{logical} pages, that is, the pages that \TeX\
61 ``thinks'' that it is typesetting, will have the same sizes, but this need not
62 be the case. |pgfpages| will automatically scale down the logical pages such
63 that two logical pages fit next to each other inside a DIN A4 page.
64
65 The |border shrink| tells |pgfpages| that it should add an additional 5mm to
66 the shrinking such that a 5mm-wide border is shown around the resulting logical
67 pages.
68
69 As a second example, let us put two pages produced by the \textsc{beamer} class
70 on a single page:
71 %
72 \begin{codeexample}[code only]
73 \documentclass{beamer}
74
75 \usepackage{pgfpages}
76 \pgfpagesuselayout{2 on 1}[a4paper,border shrink=5mm]
77
78 \begin{document}
79 \begin{frame}
80 This text is shown at the top.
81 \end{frame}
82 \begin{frame}
83 This text is shown at the bottom.
84 \end{frame}
85 \end{document}
86 \end{codeexample}
87
88 Note that we do not use the |landscape| option since \textsc{beamer}'s logical
89 pages are already in landscape mode and putting two landscape pages on top of
90 each other results in a portrait page. However, if you had used the |4 on 1|
91 layout, you would have had to add |landscape| once more, using the |6 on 1| or
92 |8 on 1| you must not, using |16 on 1| you need it yet again. And, no, there is
93 no |32 on 1| layout.
94
95 Another word of caution: \emph{using |pgfpages| will produce wrong page numbers
96 in the |.aux| file}. The reason is that \TeX\ instantiates the page numbers
97 when writing an |.aux| file only when the physical page is shipped out.
98 Fortunately, this problem is easy to fix: First, typeset our file normally
99 without using the |\pgfpagesuselayout| command (just put the comment marker |%|
100 before it) Then, rerun \TeX\ with the |\pgfpagesuselayout| command included and
101 add the command |\nofiles|. This command ensures that the |.aux| file is not
102 modified, which is exactly what you want. So, to typeset the above example, you
103 should actually first \TeX\ the following file:
104 %
105 \begin{codeexample}[code only]
106 \documentclass{article}
107
108 \usepackage{pgfpages}
109 %%\pgfpagesuselayout{2 on 1}[a4paper,landscape,border shrink=5mm]
110 %%\nofiles
111
112 \begin{document}
113 This text is shown on the left.
114 \clearpage
115 This text is shown on the right.
116 \end{document}
117 \end{codeexample}
118 %
119 and then typeset
120 %
121 \begin{codeexample}[code only]
122 \documentclass{article}
123
124 \usepackage{pgfpages}
125 \pgfpagesuselayout{2 on 1}[a4paper,landscape,border shrink=5mm]
126 \nofiles
127
128 \begin{document}
129 This text is shown on the left.
130 \clearpage
131 This text is shown on the right.
132 \end{document}
133 \end{codeexample}
134
135 The final basic example is the |resize to| layout (it works a bit like a
136 hypothetical |1 on 1| layout). This layout resizes the logical page such that
137 is fits the specified physical size. Since this does not change the page
138 numbering, you need not worry about the |.aux| files with this layout. For
139 example, adding the following lines will ensure that the physical output will
140 fit on DIN A4 paper:
141 %
142 \begin{codeexample}[code only]
143 \usepackage{pgfpages}
144 \pgfpagesuselayout{resize to}[a4paper]
145 \end{codeexample}
146
147 This can be very useful when you have to handle lots of papers that are typeset
148 for, say, letter paper and you have an A4 printer or the other way round. For
149 example, the following article will be fit for printing on letter paper:
150 %
151 \begin{codeexample}[code only]
152 \documentclass[a4paper]{article}
153 %% a4 is currently the logical size and also the physical size
154
155 \usepackage{pgfpages}
156 \pgfpagesuselayout{resize to}[letterpaper]
157 %% a4 is still the logical size, but letter is the physical one
158
159 \begin{document}
160 \title{My Great Article}
161 ...
162 \end{document}
163 \end{codeexample}
164
165
166 \subsection{The Predefined Layouts}
167
168 This section explains the predefined layouts in more detail. You select a
169 layout using the following command:
170 %
171 \begin{command}{\pgfpagesuselayout\marg{layout}\oarg{options}}
172 Installs the specified \meta{layout} with the given \meta{options}. The
173 predefined layouts and their permissible options are explained below.
174
175 If this function is called multiple times, only the last call ``wins''. You
176 can thereby overwrite any previous settings. In particular, layouts
177 \emph{do not} accumulate.
178
179 \example |\pgfpagesuselayout{resize to}[a4paper]|
180 \end{command}
181
182 \begin{pgflayout}{resize to}
183 This layout is used to resize every logical page to a specified physical
184 size. To determine the target size, the following options may be given:
185 %
186 \begin{itemize}
187 \item \declare{|physical paper height=|\meta{size}} sets the height of
188 the physical page size to \meta{size}.
189 \item \declare{|physical paper width=|\meta{size}} sets the width of
190 the physical Pappe size to \meta{size}.
191 \item \declare{|a0paper|} sets the physical page size to DIN A0 paper.
192 \item \declare{|a1paper|} sets the physical page size to DIN A1 paper.
193 \item \declare{|a2paper|} sets the physical page size to DIN A2 paper.
194 \item \declare{|a3paper|} sets the physical page size to DIN A3 paper.
195 \item \declare{|a4paper|} sets the physical page size to DIN A4 paper.
196 \item \declare{|a5paper|} sets the physical page size to DIN A5 paper.
197 \item \declare{|a6paper|} sets the physical page size to DIN A6 paper.
198 \item \declare{|letterpaper|} sets the physical page size to the
199 American letter paper size.
200 \item \declare{|legalpaper|} sets the physical page size to the
201 American legal paper size.
202 \item \declare{|executivepaper|} sets the physical page size to the
203 American executive paper size.
204 \item \declare{|landscape|} swaps the height and the width of the
205 physical paper.
206 \item \declare{|border shrink=|\meta{size}} additionally reduces the
207 size of the logical page on the physical page by \meta{size}.
208 \end{itemize}
209 \end{pgflayout}
210
211 \begin{pgflayout}{2 on 1}
212 Puts two logical pages alongside each other on each physical page if the
213 logical height is larger than the logical width (logical pages are in
214 portrait mode). Otherwise, two logical pages are put on top of each other
215 (logical pages are in landscape mode). When using this layout, it is
216 advisable to use the |\nofiles| command, but this is not done
217 automatically.
218
219 The same \meta{options} as for the |resize to| layout can be used, plus the
220 following option:
221 %
222 \begin{itemize}
223 \item \declare{|odd numbered pages right|} places the first page on the
224 right.
225 \end{itemize}
226 \end{pgflayout}
227
228 \begin{pgflayout}{4 on 1}
229 Puts four logical pages on a single physical page. The same \meta{options}
230 as for the |resize to| layout can be used.
231 \end{pgflayout}
232
233 \begin{pgflayout}{6 on 1}
234 Puts six logical pages on a single physical page.
235 \end{pgflayout}
236
237 \begin{pgflayout}{8 on 1}
238 Puts eight logical pages on a single physical page. As for |2 on 1| and
239 |4 on 1|, the orientation depends on whether the logical pages are in
240 landscape mode or in portrait mode.
241 \end{pgflayout}
242
243 \begin{pgflayout}{16 on 1}
244 This is for the \textsc{ceo}.
245 \end{pgflayout}
246
247 \begin{pgflayout}{rounded corners}
248 \label{layout-rounded-corners}
249 This layout adds ``rounded corners'' to every page, which, supposedly,
250 looks nicer during presentations with projectors (personally, I doubt
251 this). This is done by (possibly) resizing the page to the physical page
252 size. Then four black rectangles are drawn in each corner. Next, a clipping
253 region is set up that contains all of the logical page except for little
254 rounded corners. Finally, the logical page is drawn and clipped against the
255 clipping region.
256
257 Note that every logical page should fill its background for this to work.
258
259 In addition to the \meta{options} that can be given to |resize to|, the
260 following options may be given.
261 %
262 \begin{itemize}
263 \item \declare{|corner width=|\meta{size}} specifies the size of the
264 corner.
265 \end{itemize}
266 %
267 \begin{codeexample}[code only]
268 \documentclass{beamer}
269 \usepackage{pgfpages}
270 \pgfpagesuselayout{rounded corners}[corner width=5pt]
271 \begin{document}
272 ...
273 \end{document}
274 \end{codeexample}
275 %
276 \end{pgflayout}
277
278 \begin{pgflayout}{two screens with lagging second}
279 This layout puts two logical pages alongside each other. The second page
280 always shows what the main page showed on the previous physical page. Thus,
281 the second page ``lags behind'' the main page. This can be useful when you
282 have two projectors attached to your computer and can show different parts
283 of a physical page on different projectors.
284
285 The following \meta{options} may be given:
286 %
287 \begin{itemize}
288 \item \declare{|second right|} puts the second page right of the main
289 page. This will make the physical pages twice as wide as the
290 logical pages, but it will retain the height.
291 \item \declare{|second left|} puts the second page left, otherwise it
292 behaves the same as |second right|.
293 \item \declare{|second bottom|} puts the second page below the main
294 page. This make the physical pages twice as high as the logical
295 ones.
296 \item \declare{|second top|} works like |second bottom|.
297 \end{itemize}
298 \end{pgflayout}
299
300 \begin{pgflayout}{two screens with optional second}
301 This layout works similarly to |two screens with lagging second|. The
302 difference is that the contents of the second screen only changes when one
303 of the commands |\pgfshipoutlogicalpage{2}|\marg{box} or
304 |\pgfcurrentpagewillbelogicalpage{2}| is called. The first puts the given
305 \meta{box} on the second page. The second specifies that the current page
306 should be put there, once it is finished.
307
308 The same options as for |two screens with lagging second| may be given.
309 \end{pgflayout}
310
311 You can define your own predefined layouts using the following command:
312
313 \begin{command}{\pgfpagesdeclarelayout\marg{layout}\marg{before actions}\marg{after actions}}
314 This command predefines a \meta{layout} that can later be installed using
315 the |\pgfpagesuselayout| command.
316
317 When |\pgfpagesuselayout|\marg{layout}\oarg{options} is called, the
318 following happens: First, the \meta{before actions} are executed. They can
319 be used, for example, to set up default values for keys. Next,
320 |\setkeys{pgfpagesuselayoutoption}|\marg{options} is executed. Finally, the
321 \meta{after actions} are executed.
322
323 Here is an example:
324 %
325 \begin{codeexample}[code only]
326 \pgfpagesdeclarelayout{resize to}
327 {
328 \def\pgfpageoptionborder{0pt}
329 }
330 {
331 \pgfpagesphysicalpageoptions
332 {%
333 logical pages=1,%
334 physical height=\pgfpageoptionheight,%
335 physical width=\pgfpageoptionwidth%
336 }
337 \pgfpageslogicalpageoptions{1}
338 {%
339 resized width=\pgfphysicalwidth,%
340 resized height=\pgfphysicalheight,%
341 border shrink=\pgfpageoptionborder,%
342 center=\pgfpoint{.5\pgfphysicalwidth}{.5\pgfphysicalheight}%
343 }%
344 }
345 \end{codeexample}
346 %
347 \end{command}
348
349
350 \subsection{Defining a Layout}
351
352 If none of the predefined layouts meets your problem or if you wish to modify
353 them, you can create layouts from scratch. This section explains how this is
354 done.
355
356 Basically, |pgfpages| hooks into \TeX's |\shipout| function. This function is
357 called whenever \TeX\ has completed typesetting a page and wishes to send this
358 page to the |.dvi| or |.pdf| file. The |pgfpages| package redefines this
359 command. Instead of sending the page to the output file, |pgfpages| stores it
360 in an internal box and then acts as if the page had been output. When \TeX\
361 tries to output the next page using |\shipout|, this call is once more
362 intercepted and the page is stored in another box. These boxes are called
363 \emph{logical pages}.
364
365 At some point, enough logical pages have been accumulated such that a
366 \emph{physical page} can be output. When this happens, |pgfpages| possibly
367 scales, rotates, and translates the logical pages (and possibly even does
368 further modifications) and then puts them at certain positions of the
369 \emph{physical} page. Once this page is fully assembled, the ``real'' or
370 ``original'' |\shipout| is called to send the physical page to the output file.
371
372 In reality, things are slightly more complicated. First, once a physical page
373 has been shipped out, the logical pages are usually voided, but this need not
374 be the case. Instead, it is possible that certain logical pages just retain
375 their contents after the physical page has been shipped out and these pages
376 need not be filled once more before a physical shipout can occur. However, the
377 contents of these logical pages can still be changed using special commands. It
378 is also possible that after a shipout certain logical pages are filled with the
379 contents of \emph{other} logical pages.
380
381 A \emph{layout} defines for each logical page where it will go on the physical
382 page and which further modifications should be done. The following two commands
383 are used to define the layout:
384
385 \begin{command}{\pgfpagesphysicalpageoptions\marg{options}}
386 This command sets the characteristics of the ``physical'' page. For
387 example, it is used to specify how many logical pages there are and how
388 many logical pages must be accumulated before a physical page is shipped
389 out. How each individual logical page is typeset is specified using the
390 command |\pgfpageslogicalpageoptions|, described later.
391
392 \example A layout for putting two portrait pages on a single landscape
393 page:
394 %
395 \begin{codeexample}[code only]
396 \pgfpagesphysicalpageoptions
397 {%
398 logical pages=2,%
399 physical height=\paperwidth,%
400 physical width=\paperheight,%
401 }
402
403 \pgfpageslogicalpageoptions{1}
404 {%
405 resized width=.5\pgfphysicalwidth,%
406 resized height=\pgfphysicalheight,%
407 center=\pgfpoint{.25\pgfphysicalwidth}{.5\pgfphysicalheight}%
408 }%
409 \pgfpageslogicalpageoptions{2}
410 {%
411 resized width=.5\pgfphysicalwidth,%
412 resized height=\pgfphysicalheight,%
413 center=\pgfpoint{.75\pgfphysicalwidth}{.5\pgfphysicalheight}%
414 }%
415 \end{codeexample}
416
417 The following \meta{options} may be set:
418 \begin{itemize}
419 \item \declare{|logical pages=|\meta{logical pages}} specified how many
420 logical pages there are, in total. These are numbered 1 to
421 \meta{logical pages}.
422 \item \declare{|first logical shipout=|\meta{first}}. See the next
423 option. By default, \meta{first} is 1.
424 \item \declare{|last logical shipout=|\meta{last}}. Together with the
425 previous option, these two options define an interval of pages
426 inside the range 1 to \meta{logical pages}. Only this range is used
427 to store the pages that are shipped out by \TeX. This means that
428 after a physical shipout has just occurred (or at the beginning),
429 the first time \TeX\ wishes to perform a shipout, the page to be
430 shipped out is stored in logical page \meta{first}. The next time
431 \TeX\ performs a shipout, the page is stored in logical page
432 $\meta{first} +1$ and so on, until the logical page \meta{last} is
433 also filled. Once this happens, a physical shipout occurs and the
434 process starts once more.
435
436 Note that logical pages that lie outside the interval between
437 \meta{first} and \meta{last} are filled only indirectly or when
438 special commands are used.
439
440 By default, \meta{last} equals \meta{logical pages}.
441 \item \declare{|current logical shipout=|\meta{current}} changes an
442 internal counter such that \TeX's next logical shipout will be
443 stored in logical page \meta{current}.
444
445 This option can be used to ``warp'' the logical page filling
446 mechanism to a certain page. You can both skip logical pages and
447 overwrite already filled logical pages. After the logical page
448 \meta{current} has been filled, the internal counter is incremented
449 normally as if the logical page \meta{current} had been ``reached''
450 normally. If you specify a \meta{current} larger than \meta{last},
451 a physical shipout will occur after the logical page \meta{current}
452 has been filled.
453 \item \declare{|physical height=|\meta{height}} specifies the height of
454 the physical pages. This height is typically different from the
455 normal |\paperheight|, which is used by \TeX\ for its typesetting
456 and page breaking purposes.
457 \item \declare{|physical width=|\meta{width}} specifies the physical
458 width.
459 \end{itemize}
460 \end{command}
461
462
463 \begin{command}{\pgfpageslogicalpageoptions\marg{logical page number}\marg{options}}
464 This command is used to specify where the logical page number \meta{logical
465 page number} will be placed on the physical page. In addition, this command
466 can be used to install additional ``code'' to be executed when this page is
467 put on the physical page.
468
469 The number \meta{logical page number} should be between 1 and \meta{logical
470 pages}, which has previously been installed using the
471 |\pgfpagesphysicalpageoptions| command.
472
473 The following \meta{options} may be given:
474 %
475 \begin{itemize}
476 \item \declare{|center=|\meta{pgf point}} specifies the center of the
477 logical page inside the physical page as a \pgfname-point. The
478 origin of the coordinate system of the physical page is at the
479 \emph{lower} left corner.
480 %
481 \begin{codeexample}[code only]
482 \pgfpageslogicalpageoptions{1}
483 {% center logical page on middle of left side
484 center=\pgfpoint{.25\pgfphysicalwidth}{.5\pgfphysicalheight}%
485 resized width=.5\pgfphysicalwidth,%
486 resized height=\pgfphysicalheight,%
487 }
488 \end{codeexample}
489 %
490 \item \declare{|resized width=|\meta{size}} specifies the width that
491 the logical page should have \emph{at most} on the physical page.
492 To achieve this width, the pages is scaled down appropriately
493 \emph{or more}. The ``or more'' part can happen if the
494 |resize height| option is also used. In this case, the scaling is
495 chosen such that both the specified height and width are met. The
496 aspect ratio of a logical page is not modified.
497 \item \declare{|resized height=|\meta{height}} specifies the maximum
498 height of the logical page.
499 \item \declare{|original width=|\meta{width}} specifies the width the
500 \TeX\ ``thinks'' that the logical page has. This width is
501 |\paperwidth| at the point of invocation, by default. Note that
502 setting this width to something different from |\paperwidth| does
503 \emph{not} change the |\pagewidth| during \TeX's typesetting. You
504 have to do that yourself.
505
506 You need this option only for special logical pages that have a
507 height or width different from the normal one and for which you
508 will (later on) set these sizes yourself.
509 \item \declare{|original height=|\meta{height}} works like
510 |original width|.
511 \item \declare{|scale=|\meta{factor}} scales the page by at least the
512 given \meta{factor}. A \meta{factor} of |0.5| will half the size of
513 the page, a factor or |2| will double the size. ``At least'' means
514 that if options like |resize height| are given and if the scaling
515 required to meet that option is less than \meta{factor}, that other
516 scaling is used instead.
517 \item \declare{|xscale=|\meta{factor}} scales the logical page along
518 the $x$-axis by the given \meta{factor}. This scaling is done
519 independently of any other scaling. Mostly, this option is useful
520 for a factor of |-1|, which flips the page along the $y$-axis. The
521 aspect ratio is not kept.
522 \item \declare{|yscale=|\meta{factor}} works like |xscale|, only for
523 the $y$-axis.
524 \item \declare{|rotation=|\meta{degree}} rotates the page by
525 \meta{degree} around its center. Use a degree of |90| or |-90| to
526 go from portrait to landscape and back. The rotation need not be a
527 multiple of |90|.
528 \item \declare{|copy from=|\meta{logical page number}}. Normally, after
529 a physical shipout has occurred, all logical pages are voided in a
530 loop. However, if this option is given, the current logical page is
531 filled with the contents of the old logical page number
532 \meta{logical page number}.
533
534 \example Have logical page 2 retain its contents:
535 %
536 \begin{codeexample}[code only]
537 \pgfpageslogicalpageoptions{2}{copy from=2}
538 \end{codeexample}
539
540 \example Let logical page 2 show what logical page 1 showed on the
541 just-shipped-out physical page:
542 %
543 \begin{codeexample}[code only]
544 \pgfpageslogicalpageoptions{2}{copy from=1}
545 \end{codeexample}
546 %
547 \item \declare{|border shrink|=\meta{size}} specifies an additional
548 reduction of the size to which the page is page is scaled.
549 \item \declare{|border code|=\meta{code}}. When this option is given,
550 the \meta{code} is executed before the page box is inserted with a
551 path preinstalled that is a rectangle around the current logical
552 page. Thus, setting \meta{code} to |\pgfstroke| draws a rectangle
553 around the logical page. Setting \meta{code} to
554 |\pgfsetlinewidth{3pt}\pgfstroke| results in a thick (ugly) frame.
555 Adding dashes and filling can result in arbitrarily funky and
556 distracting borders.
557
558 You can also call |\pgfdiscardpath| and add your own path
559 construction code (for example to paint a rectangle with rounded
560 corners). The coordinate system is set up in such a way that a
561 rectangle starting at the origin and having the height and width of
562 \TeX-box 0 will result in a rectangle filling exactly the logical
563 page currently being put on the physical page. The logical page is
564 inserted \emph{after} these commands have been executed.
565
566 \example Add a rectangle around the page:
567 %
568 \begin{codeexample}[code only]
569 \pgfpageslogicalpageoptions{1}{border code=\pgfstroke}
570 \end{codeexample}
571 %
572 \item \declare{|corner width|=\meta{size}} adds black ``rounded
573 corners'' to the page. See the description of the predefined layout
574 |rounded corners| on page~\pageref{layout-rounded-corners}.
575 \end{itemize}
576 \end{command}
577
578
579 \subsection{Creating Logical Pages}
580
581 Logical pages are created whenever \TeX\ thinks that a page is full and
582 performs a |\shipout| command. This will cause |pgfpages| to store the box that
583 was supposed to be shipped out internally until enough logical pages have been
584 collected such that a physical shipout can occur.
585
586 Normally, whenever a logical shipout occurs, that current page is stored in
587 logical page number \meta{current logical page}. This counter is then
588 incremented, until it is larger than \meta{last logical shipout}. You can,
589 however, directly change the value of \meta{current logical page} by calling
590 |\pgfpagesphysicalpageoptions|.
591
592 Another way to set the contents of a logical page is to use the following
593 command:
594
595 \begin{command}{\pgfpagesshipoutlogicalpage\marg{number}\meta{box}}
596 This command sets to logical page \meta{number} to \meta{box}. The
597 \meta{box} should be the code of a \TeX\ box command. This command does not
598 influence the counter \meta{current logical page} and does not cause a
599 physical shipout.
600 %
601 \begin{codeexample}[code only]
602 \pgfpagesshipoutlogicalpage{0}\vbox{Hi!}
603 \end{codeexample}
604
605 This command can be used to set the contents of logical pages that are
606 normally not filled.
607 \end{command}
608
609 The final way of setting a logical page is using the following command:
610
611 \begin{command}{\pgfpagescurrentpagewillbelogicalpage\marg{number}}
612 When the current \TeX\ page has been typeset, it will be become the given
613 logical page \meta{number}. This command ``interrupts'' the normal order of
614 logical pages, that is, it behaves like the previous command and does not
615 update the \meta{current logical page} counter.
616 %
617 \begin{codeexample}[code only]
618 \pgfpagesuselayout{two screens with optional second}
619 ...
620 Text for main page.
621 \clearpage
622
623 \pgfpagescurrentpagewillbelogicalpage{2}
624 Text that goes to second page
625 \clearpage
626
627 Text for main page.
628 \end{codeexample}
629 %
630 \end{command}
631
632
633 %%% Local Variables:
634 %%% mode: latex
635 %%% TeX-master: "pgfmanual"
636 %%% End: