% Copyright 2006 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section{Page Management}

This section describes the |pgfpages| package. 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 set up 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}. 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 page size to \meta{size}.
  \item
    \declare{|physical paper width=|\meta{size}} sets the
    width of the physical Pappe 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 can 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 can be used.
\end{pgflayout}

\begin{pgflayout}{8 on 1}
  Puts eight logical pages on a single physical page. As for |2 on 1| and |4 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 drawn and 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 two
  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 behaves 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 set up 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 pages 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 characteristics 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
      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 occurred (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
    than \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 occurred, 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 additional reduction of the size to which the page is
    page is scaled.
  \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  set up 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 \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:
