% Copyright 2019 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 |6 on 1| or
|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}{6 on 1}
    Puts six logical pages on a single physical page.
\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: