summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pages.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2006-01-09 00:56:57 +0000
committerKarl Berry <karl@freefriends.org>2006-01-09 00:56:57 +0000
commitf07bb53970ee2ecc53f81a206a3d3a67ef665e4a (patch)
tree6f57a1d62971db79e5ff023bdfd83b22cb971dc9 /Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pages.tex
parent007f67a693e4d031fd3d792df8e4d5f43e2cb2e7 (diff)
doc 6
git-svn-id: svn://tug.org/texlive/trunk@85 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pages.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pages.tex670
1 files changed, 670 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pages.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pages.tex
new file mode 100644
index 00000000000..3b6480b4f8e
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pages.tex
@@ -0,0 +1,670 @@
+% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>.
+%
+% This program can be redistributed and/or modified under the terms
+% of the LaTeX Project Public License Distributed from CTAN
+% archives in directory macros/latex/base/lppl.txt.
+
+
+\section{Page Management}
+
+This section describes the |pgfpages| packages. Although this package
+is not concerned with creating pictures, its implementation relies so
+heavily on \pgfname\ that it is documented here. Currently, |pgfpages|
+only works with \LaTeX, but if you are adventurous, feel free to hack
+the code so that it also works with plain \TeX.
+
+The aim of |pgfpages| is to provide a flexible way of putting multiple
+pages on a single page \emph{inside \TeX}. Thus, |pgfpages| is quite
+different from useful tools like |psnup| or |pdfnup| insofar as it
+creates its output in a single pass. Furthermore, it works uniformly
+with both |latex| and |pdflatex|, making it easy to put multiple pages
+on a single page without any fuss.
+
+A word of warning: \emph{using |pgfpages| will destroy
+ hyperlinks}. Actually, the hyperlinks are not destroyed, only they
+will appear at totally wrong positions on the final output. This is
+due to a fundamental flaw in the \pdf\ specification: In \pdf\ the
+bounding rectangle of a hyperlink is given in ``absolute
+page coordinates'' and translations or rotations do not affect
+them. Thus, the transformations applied by |pgfpages| to put the pages
+where you want them are (cannot, even) be applied to the coordinates
+of hyperlinks. It is unlikely that this will change in the foreseeable
+future.
+
+
+\subsection{Basic Usage}
+
+The internals of |pgfpages| are complex since the package can do all
+sorts of interesting tricks. For this reason, so-called \emph{layouts}
+are predefined that setup all option in appropriate ways.
+
+You use a layout as follows:
+\begin{codeexample}[code only]
+\documentclass{article}
+
+\usepackage{pgfpages}
+\pgfpagesuselayout{2 on 1}[a4paper,landscape,border shrink=5mm]
+
+\begin{document}
+This text is shown on the left.
+\clearpage
+This text is shown on the right.
+\end{document}
+\end{codeexample}
+
+The layout |2 on 1| puts two pages on a single page. The option
+|a4paper| tells |pgfpages| that the \emph{resulting} page (called the
+\emph{physical} page in the following) should be |a4paper| and it
+should be landscape (which is quite logical since putting two portrait
+pages next to each other gives a landscape page). Normally, the
+\emph{logical} pages, that is, the pages that \TeX\ ``thinks'' that it
+is typesetting, will have the same sizes, but this need not be the
+case. |pgfpages| will automatically scale down the logical pages such
+that two logical pages fit next to each other inside a DIN A4 page.
+
+The |border shrink| tells |pgfpages| that it should add an additional
+5mm to the shrinking such that a 5mm-wide border is shown around the
+resulting logical pages.
+
+As a second example, let us put two pages produced by the
+\textsc{beamer} class on a single page:
+
+\begin{codeexample}[code only]
+\documentclass{beamer}
+
+\usepackage{pgfpages}
+\pgfpagesuselayout{2 on 1}[a4paper,border shrink=5mm]
+
+\begin{document}
+\begin{frame}
+ This text is shown at the top.
+\end{frame}
+\begin{frame}
+ This text is shown at the bottom.
+\end{frame}
+\end{document}
+\end{codeexample}
+
+Note that we do not use the |landscape| option since \textsc{beamer}'s
+logical pages are already in landscape mode and putting two landscape
+pages on top of each other results in a portrait page. However, if you
+had used the |4 on 1| layout, you would have had to add |landscape|
+once more, using the |8 on 1| you must not, using |16 on 1| you need
+it yet again. And, no, there is no |32 on 1| layout.
+
+Another word of caution: \emph{using |pgfpages| will produce wrong
+ page numbers in the |.aux| file}. The reason is that \TeX\
+instantiates the page numbers when writing an |.aux| file only when
+the physical page is shipped out. Fortunately, this problem is easy to
+fix: First, typeset our file normally without using the
+|\pgfpagesuselayout| command (just put the comment marker |%| before it)
+Then, rerun \TeX\ with the |\pgfpagesuselayout| command included and add
+the command |\nofiles|. This command ensures that the |.aux| file is
+not modified, which is exactly what you want. So, to typeset the above
+example, you should actually first \TeX\ the following file:
+
+\begin{codeexample}[code only]
+\documentclass{article}
+
+\usepackage{pgfpages}
+%%\pgfpagesuselayout{2 on 1}[a4paper,landscape,border shrink=5mm]
+%%\nofiles
+
+\begin{document}
+This text is shown on the left.
+\clearpage
+This text is shown on the right.
+\end{document}
+\end{codeexample}
+and then typeset
+\begin{codeexample}[code only]
+\documentclass{article}
+
+\usepackage{pgfpages}
+\pgfpagesuselayout{2 on 1}[a4paper,landscape,border shrink=5mm]
+\nofiles
+
+\begin{document}
+This text is shown on the left.
+\clearpage
+This text is shown on the right.
+\end{document}
+\end{codeexample}
+
+The final basic example is the |resize to| layout (it works a bit like
+a hypothetical |1 on 1| layout). This layout resizes the logical page
+such that is fits the specified physical size. Since this does not
+change the page numbering, you need not worry about the |.aux| files
+with this layout. For example, adding the following lines will ensure
+that the physical output will fit on DIN A4 paper:
+\begin{codeexample}[code only]
+\usepackage{pgfpages}
+\pgfpagesuselayout{resize to}[a4paper]
+\end{codeexample}
+
+This can be very useful when you have to handle lots of papers that
+are typeset for, say, letter paper and you have an A4 printer or the
+other way round. For example, the following article will be fit for
+printing on letter paper:
+\begin{codeexample}[code only]
+\documentclass[a4paper]{article}
+%% a4 is currently the logical size and also the physical size
+
+\usepackage{pgfpages}
+\pgfpagesuselayout{resize to}[letterpaper]
+%% a4 is still the logical size, but letter is the physical one
+
+\begin{document}
+ \title{My Great Article}
+...
+\end{document}
+\end{codeexample}
+
+
+
+\subsection{The Predefined Layouts}
+
+This section explains the predefined layouts in more detail. You
+select a layout using the following command:
+\begin{command}{\pgfpagesuselayout\marg{layout}\oarg{options}}
+ Installs the specified \meta{layout} with the given \meta{options}
+ set. The predefined layouts and their permissible options are
+ explained below.
+
+ If this function is called multiple times, only the last call
+ ``wins.'' You can thereby overwrite any previous settings. In
+ particular, layouts \emph{do not} accumulate.
+
+ \example |\pgfpagesuselayout{resize to}[a4paper]|
+\end{command}
+
+\begin{pgflayout}{resize to}
+ This layout is used to resize every logical page to a specified
+ physical size. To determine the target size, the following options
+ may be given:
+ \begin{itemize}
+ \item
+ \declare{|physical paper height=|\meta{size}} sets the
+ height of the physical pape size to \meta{size}.
+ \item
+ \declare{|physical paper width=|\meta{size}} sets the
+ width of the physical pape size to \meta{size}.
+ \item
+ \declare{|a0paper|} sets the physical page size to DIN A0 paper.
+ \item
+ \declare{|a1paper|} sets the physical page size to DIN A1 paper.
+ \item
+ \declare{|a2paper|} sets the physical page size to DIN A2 paper.
+ \item
+ \declare{|a3paper|} sets the physical page size to DIN A3 paper.
+ \item
+ \declare{|a4paper|} sets the physical page size to DIN A4 paper.
+ \item
+ \declare{|a5paper|} sets the physical page size to DIN A5 paper.
+ \item
+ \declare{|a6paper|} sets the physical page size to DIN A6 paper.
+ \item
+ \declare{|letterpaper|} sets the physical page size to the
+ American letter paper size.
+ \item
+ \declare{|legalpaper|} sets the physical page size to the
+ American legal paper size.
+ \item
+ \declare{|executivepaper|} sets the physical page size to the
+ American executive paper size.
+ \item
+ \declare{|landscape|} swaps the height and the width of the
+ physical paper.
+ \item
+ \declare{|border shrink=|\meta{size}} additionally reduces the
+ size of the logical page on the physical page by \meta{size}.
+ \end{itemize}
+\end{pgflayout}
+
+\begin{pgflayout}{2 on 1}
+ Puts two logical pages alongside each other on each physical page if
+ the logical height is larger than the logical width (logical pages
+ are in portrait mode). Otherwise, two
+ logical pages are put on top of each other (logical pages are in
+ landscape mode). When using this layout, it is advisable to use the
+ |\nofiles| command, but this is not done automatically.
+
+ The same \meta{options} as for the |resize to| layout an be used,
+ plus the following option:
+ \begin{itemize}
+ \item
+ \declare{|odd numbered pages right|}
+ places the first page on the right.
+ \end{itemize}
+\end{pgflayout}
+
+
+\begin{pgflayout}{4 on 1}
+ Puts four logical pages on a single physical page.
+ The same \meta{options} as for the |resize to| layout an be used.
+\end{pgflayout}
+
+\begin{pgflayout}{8 on 1}
+ Puts eight logical pages on a single physical page. As for |2 on 1|,
+ the orientation depends on whether the logical pages are in
+ landscape mode or in portrait mode.
+\end{pgflayout}
+
+\begin{pgflayout}{16 on 1}
+ This is for the \textsc{ceo}.
+\end{pgflayout}
+
+\begin{pgflayout}{rounded corners}
+ \label{layout-rounded-corners}
+ This layout adds ``rounded corners'' to every page, which,
+ supposedly, looks nicer during presentations with projectors
+ (personally, I doubt this). This is done by (possibly) resizing the
+ page to the physical page size. Then four black rectangles are
+ drawn in each corner. Next, a clipping region is set up that
+ contains all of the logical page except for little rounded
+ corners. Finally, the logical page is draw, clipped against the
+ clipping region.
+
+ Note that every logical page should fill its background for this to
+ work.
+
+ In addition to the \meta{options} that can be given to |resize to|
+ the following options may be given.
+ \begin{itemize}
+ \item \declare{|corner width=|\meta{size}} specifies the size of
+ the corner.
+ \end{itemize}
+
+ \begin{codeexample}[code only]
+\documentclass{beamer}
+\usepackage{pgfpages}
+\pgfpagesuselayout{rounded corners}[corner width=5pt]
+\begin{document}
+...
+\end{document}
+\end{codeexample}
+\end{pgflayout}
+
+\begin{pgflayout}{two screens with lagging second}
+ This layout puts two logical pages alongside each other. The second
+ page always shows what the main
+ page showed on the previous physical page. Thus, the second page
+ ``lags behind'' the main page. This can be useful when you have to
+ projectors attached to your computer and can show different parts of
+ a physical page on different projectors.
+
+ The following \meta{options} may be given:
+ \begin{itemize}
+ \item \declare{|second right|} puts the second page right of the
+ main page. This will make the physical pages twice as wide
+ as the logical pages, but it will retain the height.
+ \item \declare{|second left|} puts the second page left,
+ otherwise it behave the same as |second right|.
+ \item \declare{|second bottom|} puts the second page below the main
+ page. This make the physical pages twice as high as the logical
+ ones.
+ \item \declare{|second top|} works like |second bottom|.
+ \end{itemize}
+\end{pgflayout}
+
+\begin{pgflayout}{two screens with optional second}
+ This layout works similarly to
+ |two screens with lagging second|. The difference is that the
+ contents of the second screen only changes when one of the commands
+ |\pgfshipoutlogicalpage{2}|\marg{box} or
+ |\pgfcurrentpagewillbelogicalpage{2}| is called. The first puts the
+ given \meta{box} on the second page. The second specifies that the
+ current page should be put there, once it is finished.
+
+ The same options as for |two screens with lagging second| may be
+ given.
+\end{pgflayout}
+
+
+
+You can define your own predefined layouts using the following
+command:
+
+\begin{command}{\pgfpagesdeclarelayout\marg{layout}\marg{before
+ actions}\marg{after actions}}
+ This command predefines a \meta{layout} that can later be installed
+ using the |\pgfpagesuselayout| command.
+
+ When |\pgfpagesuselayout|\marg{layout}\oarg{options} is called, the
+ following happens: First, the \meta{before actions} are
+ executed. They can be used, for example, to setup default values for
+ keys. Next, |\setkeys{pgfpagesuselayoutoption}|\marg{options} is
+ executed. Finally, the \meta{after actions} are executed.
+
+ Here is an example:
+\begin{codeexample}[code only]
+\pgfpagesdeclarelayout{resize to}
+{
+ \def\pgfpageoptionborder{0pt}
+}
+{
+ \pgfpagesphysicalpageoptions
+ {%
+ logical pages=1,%
+ physical height=\pgfpageoptionheight,%
+ physical width=\pgfpageoptionwidth%
+ }
+ \pgfpageslogicalpageoptions{1}
+ {%
+ resized width=\pgfphysicalwidth,%
+ resized height=\pgfphysicalheight,%
+ border shrink=\pgfpageoptionborder,%
+ center=\pgfpoint{.5\pgfphysicalwidth}{.5\pgfphysicalheight}%
+ }%
+}
+\end{codeexample}
+\end{command}
+
+
+
+
+\subsection{Defining a Layout}
+
+If none of the predefined layouts meets your problem or if you wish to
+modify them, you can create layouts from scratch. This section
+explains how this is done.
+
+Basically, |pgfpages| hooks into \TeX's |\shipout| function. This
+function is called whenever \TeX\ has completed typesetting a page and
+wishes to send this page to the |.dvi| or |.pdf| file. The |pgfpages|
+package redefines this command. Instead of sending the page to the output
+file, |pgfpages| stores it in an internal box and then acts as if the
+page had been output. When \TeX\ tries to output the next page using
+|\shipout|, this call is once more intercepted and the page is stored
+in another box. These boxes are called \emph{logical pages}.
+
+At some point, enough logical pages have been accumulated such that a
+\emph{physical page} can be output. When this happens, |pgfpages|
+possibly scales, rotates, and translates the logical pages (and
+possibly even does further modifications) and then puts them at
+certain positions of the \emph{physical} page. Once this page is fully
+assembled, the ``real'' or ``original'' |\shipout| is called to
+send the physical page to the output file.
+
+In reality, things are slightly more complicated. First, once a
+physical page has been shipped out, the logical pages are usually
+voided, but this need not be the case. Instead, it is possible that
+certain logical page just retain their contents after the physical
+page has been shipped out and these pages need not be filled once more
+before a physical shipout can occur. However, the contents of these
+logical pages can still be changed using special commands. It is also
+possible that after a shipout certain logical pages are filled with
+the contents of \emph{other} logical pages.
+
+A \emph{layout} defines for each logical page where it will go on the
+physical page and which further modifications should be done. The
+following two commands are used to define the layout:
+
+\begin{command}{\pgfpagesphysicalpageoptions\marg{options}}
+ This command sets the characteristic of the ``physical'' page. For
+ example, it is used to specify how many logical pages there are and
+ how many logical pages must be accumulated before a physical page is
+ shipped out. How each individual logical page is typeset is
+ specified using the command |\pgfpageslogicalpageoptions|, described
+ later.
+
+ \example A layout for putting two portrait pages on a single
+ landscape page:
+\begin{codeexample}[code only]
+\pgfpagesphysicalpageoptions
+{%
+ logical pages=2,%
+ physical height=\paperwidth,%
+ physical width=\paperheight,%
+}
+
+\pgfpageslogicalpageoptions{1}
+{%
+ resized width=.5\pgfphysicalwidth,%
+ resized height=\pgfphysicalheight,%
+ center=\pgfpoint{.25\pgfphysicalwidth}{.5\pgfphysicalheight}%
+}%
+\pgfpageslogicalpageoptions{2}
+{%
+ resized width=.5\pgfphysicalwidth,%
+ resized height=\pgfphysicalheight,%
+ center=\pgfpoint{.75\pgfphysicalwidth}{.5\pgfphysicalheight}%
+}%
+\end{codeexample}
+
+ The following \meta{options} may be set:
+ \begin{itemize}
+ \item \declare{|logical pages=|\meta{logical pages}} specified how many
+ logical pages there are, in total. These are numbered 1 to
+ \meta{logical pages}.
+ \item \declare{|first logical shipout=|\meta{first}}. See the the
+ next option. By default, \meta{first} is 1.
+ \item \declare{|last logical shipout=|\meta{last}}. Together
+ with the previous option, these two options define an interval of
+ pages inside the range 1 to \meta{logical pages}. Only this range
+ is used to store the pages that are shipped out by \TeX. This
+ means that after a physical shipout has just occured (or at the
+ beginning), the first time \TeX\ wishes to perform a shipout, the
+ page to be shipped out is stored in logical page \meta{first}. The
+ next time \TeX\ performs a shipout, the page is stored in logical
+ page $\meta{first} +1$ and so on, until the logical page
+ \meta{last} is also filled. Once this happens, a physical shipout
+ occurs and the process starts once more.
+
+ Note that logical pages that lie outside the interval between
+ \meta{first} and \meta{last} are filled only indirectly or when
+ special commands are used.
+
+ By default, \meta{last} equals \meta{logical pages}.
+ \item \declare{|current logical shipout=|\meta{current}} changes
+ an internal counter such that \TeX's next logical shipout will be
+ stored in logical page \meta{current}.
+
+ This option can be used to ``warp'' the logical page filling
+ mechanism to a certain page. You can both skip logical pages and
+ overwrite already filled logical pages. After the logical page
+ \meta{current} has been filled, the internal counter is
+ incremented normally as if the logical page \meta{current} had
+ been ``reached'' normally. If you specify a \meta{current} larger
+ to \meta{last}, a physical shipout will occur after the logical
+ page \meta{current} has been filled.
+ \item
+ \declare{|physical height=|\meta{height}}
+ specifies the height of the physical pages. This height is
+ typically different from the normal |\paperheight|, which is used
+ by \TeX\ for its typesetting and page breaking purposes.
+ \item
+ \declare{|physical width=|\meta{width}}
+ specifies the physical width.
+ \end{itemize}
+\end{command}
+
+
+\begin{command}{\pgfpageslogicalpageoptions\marg{logical page number}\marg{options}}
+ This command is used to specify where the logical page number
+ \meta{logical page number} will be placed on the physical page. In
+ addition, this command can be used to install additional ``code'' to
+ be executed when this page is put on the physical page.
+
+ The number \meta{logical page number} should be between 1 and
+ \meta{logical pages}, which has previously been installed using the
+ |\pgfpagesphysicalpageoptions| command.
+
+ The following \meta{options} may be given:
+ \begin{itemize}
+ \item
+ \declare{|center=|\meta{pgf point}}
+ specifies the center of the logical page inside the physical page
+ as a \pgfname-point. The origin of the coordinate system of the
+ physical page is at the \emph{lower} left corner.
+
+\begin{codeexample}[code only]
+\pgfpageslogicalpageoptions{1}
+{% center logical page on middle of left side
+ center=\pgfpoint{.25\pgfphysicalwidth}{.5\pgfphysicalheight}%
+ resized width=.5\pgfphysicalwidth,%
+ resized height=\pgfphysicalheight,%
+}
+\end{codeexample}
+
+ \item
+ \declare{|resized width=|\meta{size}}
+ specifies the width that the logical page should have \emph{at
+ most} on the physical page. To achieve this width, the pages is
+ scaled down appropriately \emph{or more}. The ``or more'' part
+ can happen if the |resize height| option is also used. In this
+ case, the scaling is chosen such that both the specified height
+ and width are met. The aspect ratio of a logical page is not
+ modified.
+ \item
+ \declare{|resized height=|\meta{height}}
+ specifies the maximum height of the logical page.
+ \item
+ \declare{|original width=|\meta{width}}
+ specifies the width the \TeX\ ``thinks'' that the logical page
+ has. This width is |\paperwidth| at the point of invocation, by
+ default. Note that setting this width to something different from
+ |\paperwidth| does \emph{not} change the |\pagewidth| during
+ \TeX's typesetting. You have to do that yourself.
+
+ You need this option only for special logical pages that have
+ a height or width different from the normal one and for which you
+ will (later on) set these sizes yourself.
+ \item
+ \declare{|original height=|\meta{height}}
+ works like |original width|.
+ \item
+ \declare{|scale=|\meta{factor}}
+ scales the page by at least the given \meta{factor}. A
+ \meta{factor} of |0.5| will half the size of the page, a factor or
+ |2| will double the size. ``At least'' means that if options like
+ |resize height| are given and if the scaling required to meet that
+ option is less than \meta{factor}, that other scaling is used
+ instead.
+ \item
+ \declare{|xscale=|\meta{factor}}
+ scales the logical page along the $x$-axis by the given
+ \meta{factor}. This scaling is done independently of any other
+ scaling. Mostly, this option is useful for a factor of |-1|, which
+ flips the page along the $y$-axis. The aspect ratio is not kept.
+ \item
+ \declare{|yscale=|\meta{factor}}
+ works like |xscale|, only for the $y$-axis.
+ \item
+ \declare{|rotation=|\meta{degree}}
+ rotates the page by \meta{degree} around its center. Use a degree
+ of |90| or |-90| to go from portrait to landscape and back. The
+ rotation need not be a multiple of |90|.
+ \item
+ \declare{|copy from=|\meta{logical page number}}.
+ Normally, after a physical shipout has occured, all logical pages
+ are voided in a loop. However, if this option is given, the
+ current logical page is filled with the contents of the old
+ logical page number \meta{logical page number}.
+
+ \example Have logical page 2 retain its contents:
+\begin{codeexample}[code only]
+\pgfpageslogicalpageoptions{2}{copy from=2}
+\end{codeexample}
+
+ \example Let logical page 2 show what logical page 1 showed on the
+ just-shipped-out physical page:
+\begin{codeexample}[code only]
+\pgfpageslogicalpageoptions{2}{copy from=1}
+\end{codeexample}
+ \item
+ \declare{|border shrink|=\meta{size}}
+ specifies an addition reduction of the size to which the page is
+ page is scaled down.
+ \item
+ \declare{|border code|=\meta{code}}.
+ When this option is given, the \meta{code} is executed before the
+ page box is inserted with a path preinstalled that is a rectangle
+ around the current logical page. Thus, setting \meta{code} to
+ |\pgfstroke| draws a rectangle around the logical page. Setting
+ \meta{code} to |\pgfsetlinewidth{3pt}\pgfstroke| results in a
+ thick (ugly) frame. Adding dashes and filling can result in
+ arbitrarily funky and distracting borders.
+
+ You can also call |\pgfdiscardpath| and add your own path
+ construction code (for example to paint a rectangle with rounded
+ corners). The coordinate system is setup in such a way that a
+ rectangle starting at the origin and having the height and width
+ of \TeX-box 0 will result in a rectangle filling exactly the
+ logical page currently being put on the physical page. The logical
+ page is inserted \emph{after} these commands have been executed.
+
+ \example Add a rectangle around the page:
+\begin{codeexample}[code only]
+\pgfpageslogicalpageoptions{1}{border code=\pgfstroke}
+\end{codeexample}
+ \item
+ \declare{|corner width|=\meta{size}}
+ adds black ``rounded corners'' to the page. See the description of
+ the predefined layout |rounded corners| on
+ page~\pageref{layout-rounded-corners}.
+ \end{itemize}
+\end{command}
+
+
+
+
+\subsection{Creating Logical Pages}
+
+Logical pages are created whenever a \TeX\ thinks that a page is full
+and performs a |\shipout| command. This will cause |pgfpages| to store
+the box that was supposed to be shipped out internally until enough
+logical pages have been collected such that a physical shipout can
+occur.
+
+Normally, whenever a logical shipout occurs that current page is
+stored in logical page number \meta{current logical page}. This
+counter is then incremented, until it is larger than \meta{last
+ logical shipout}. You can, however, directly change the value of
+\meta{current logical page} by calling |\pgfpagesphysicalpageoptions|.
+
+Another way to set the contents of a logical page is to use the
+following command:
+
+\begin{command}{\pgfpagesshipoutlogicalpage\marg{number}\meta{box}}
+ This command sets to logical page \meta{number} to \meta{box}. The
+ \meta{box} should be the code of a \TeX\ box command. This command
+ does not influence the counter \meta{current logical page} and does
+ not cause a physical shipout.
+
+\begin{codeexample}[code only]
+\pgfpagesshipoutlogicalpage{0}\vbox{Hi!}
+\end{codeexample}
+
+ This command can be used to set the contents of logical pages that
+ are normally not filled.
+\end{command}
+
+The final way of setting a logical page is using the following
+command:
+
+\begin{command}{\pgfpagescurrentpagewillbelogicalpage\marg{number}}
+ When the current \TeX\ page has been typeset, it will be become the given
+ logical page \meta{number}. This command ``interrupts'' the normal
+ order of logical pages, that is, it behaves like the previous
+ command and does not update the \meta{current logical page}
+ counter.
+
+\begin{codeexample}[code only]
+\pgfpagesuselayout{two screens with optional second}
+...
+Text for main page.
+\clearpage
+
+\pgfpagescurrentpagewillbelogicalpage{2}
+Text that goes to second page
+\clearpage
+
+Text for main page.
+\end{codeexample}
+\end{command}
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "pgfmanual"
+%%% End: