[next] [prev] [prev-tail] [tail] [up]

### 16 Page Management

This section describes the pgfpages packages. Although this package is not concerned with creating pictures, its implementation relies so heavily on P G F that it is documented here. Currently, pgfpages only works with LA TEX, 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 inside T E X. 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: 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 P D F specification: In P D F 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.

#### 16.1 Basic Usage

The internals of pgfpages are complex since the package can do all sorts of interesting tricks. For this reason, so-called layouts are predefined that setup all option in appropriate ways.

You use a layout as follows:

\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}

The layout 2 on 1 puts two pages on a single page. The option a4paper tells pgfpages that the resulting page (called the 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 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 B E A M E R class on a single page:

\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}

Note that we do not use the landscape option since B E A M E R’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: 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:

\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}

and then typeset

\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}

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:

\usepackage{pgfpages} \pgfpagesuselayout{resize to}[a4paper]

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:

\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}

#### 16.2 The Predefined Layouts

This section explains the predefined layouts in more detail. You select a layout using the following command:

\pgfpagesuselayout{<layout>}[<options>]

  Installs the specified <layout> with the given <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 do not accumulate.

  Example: \pgfpagesuselayout{resize to}[a4paper]

\pgfpagesuselayout{resize to}[<options>]

  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:

  - physical paper height=<size> sets the height of the physical pape size to <size>.
  - physical paper width=<size> sets the width of the physical pape size to <size>.
  - a0paper sets the physical page size to DIN A0 paper.
  - a1paper sets the physical page size to DIN A1 paper.
  - a2paper sets the physical page size to DIN A2 paper.
  - a3paper sets the physical page size to DIN A3 paper.
  - a4paper sets the physical page size to DIN A4 paper.
  - a5paper sets the physical page size to DIN A5 paper.
  - a6paper sets the physical page size to DIN A6 paper.
  - letterpaper sets the physical page size to the American letter paper size.
  - legalpaper sets the physical page size to the American legal paper size.
  - executivepaper sets the physical page size to the American executive paper size.
  - landscape swaps the height and the width of the physical paper.
  - border shrink=<size> additionally reduces the size of the logical page on the physical page by <size>.

\pgfpagesuselayout{2 on 1}[<options>]

  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 <options> as for the resize to layout an be used, plus the following option:

  - odd numbered pages right places the first page on the right.

\pgfpagesuselayout{4 on 1}[<options>]

  Puts four logical pages on a single physical page. The same <options> as for the resize to layout an be used.

\pgfpagesuselayout{8 on 1}[<options>]

  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.

\pgfpagesuselayout{16 on 1}[<options>]

  This is for the C E O.

\pgfpagesuselayout{rounded corners}[<options>]

  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 <options> that can be given to resize to the following options may be given.

  - corner width=<size> specifies the size of the corner.

  \documentclass{beamer} \usepackage{pgfpages} \pgfpagesuselayout{rounded corners}[corner width=5pt] \begin{document} ...
  \end{document}

\pgfpagesuselayout{two screens with lagging second}[<options>]

  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 <options> may be given:

  - 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.
  - second left puts the second page left, otherwise it behave the same as second right.
  - second bottom puts the second page below the main page. This make the physical pages twice as high as the logical ones.
  - second top works like second bottom.

\pgfpagesuselayout{two screens with optional second}[<options>]

  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}{<box>} or \pgfcurrentpagewillbelogicalpage{2} is called. The first puts the given <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.

You can define your own predefined layouts using the following command:

\pgfpagesdeclarelayout{<layout>}{<before actions>}{<after actions>}

  This command predefines a <layout> that can later be installed using the \pgfpagesuselayout command.

  When \pgfpagesuselayout{<layout>}[<options>] is called, the following happens: First, the <before actions> are executed. They can be used, for example, to setup default values for keys. Next, \setkeys{pgfpagesuselayoutoption}{<options>} is executed. Finally, the <after actions> are executed.

  Here is an example:

  \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}%
  }%
  }

#### 16.3 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 logical pages.

At some point, enough logical pages have been accumulated such that a 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 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 other logical pages.

A 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:

\pgfpagesphysicalpageoptions{<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:

  \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}%
  }%

  The following <options> may be set:

  - logical pages=<logical pages> specified how many logical pages there are, in total. These are numbered 1 to <logical pages>.
  - first logical shipout=<first>. See the the next option. By default, <first> is 1.
  - last logical shipout=<last>. Together with the previous option, these two options define an interval of pages inside the range 1 to <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 <first>. The next time TEX performs a shipout, the page is stored in logical page <first>+1 and so on, until the logical page <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 <first> and <last> are filled only indirectly or when special commands are used.

    By default, <last> equals <logical pages>.

  - current logical shipout=<current> changes an internal counter such that TEX’s next logical shipout will be stored in logical page <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 <current> has been filled, the internal counter is incremented normally as if the logical page <current> had been “reached” normally. If you specify a <current> larger to <last>, a physical shipout will occur after the logical page <current> has been filled.

  - physical height=<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.
  - physical width=<width> specifies the physical width.

\pgfpageslogicalpageoptions{<logical page number>}{<options>}

  This command is used to specify where the logical page number <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 <logical page number> should be between 1 and <logical pages>, which has previously been installed using the \pgfpagesphysicalpageoptions command.

  The following <options> may be given:

  - center=<pgf point> specifies the center of the logical page inside the physical page as a P G F-point. The origin of the coordinate system of the physical page is at the lower left corner.

    \pgfpageslogicalpageoptions{1} {% center logical page on middle of left side center=\pgfpoint{.25\pgfphysicalwidth}{.5\pgfphysicalheight}% resized width=.5\pgfphysicalwidth,% resized height=\pgfphysicalheight,%
    }

  - resized width=<size> specifies the width that the logical page should have at most on the physical page. To achieve this width, the pages is scaled down appropriately 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.
  - resized height=<height> specifies the maximum height of the logical page.
  - original width=<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 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.

  - original height=<height> works like original width.
  - scale=<factor> scales the page by at least the given <factor>. A <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 <factor>, that other scaling is used instead.
  - xscale=<factor> scales the logical page along the x-axis by the given <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.
  - yscale=<factor> works like xscale, only for the y-axis.
  - rotation=<degree> rotates the page by <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.
  - copy from=<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 <logical page number>.

    Example: Have logical page 2 retain its contents:

    \pgfpageslogicalpageoptions{2}{copy from=2}

    Example: Let logical page 2 show what logical page 1 showed on the just-shipped-out physical page:

    \pgfpageslogicalpageoptions{2}{copy from=1}

  - border shrink=<size> specifies an addition reduction of the size to which the page is page is scaled down.
  - border code=<code>. When this option is given, the <code> is executed before the page box is inserted with a path preinstalled that is a rectangle around the current logical page. Thus, setting <code> to \pgfstroke draws a rectangle around the logical page. Setting <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 after these commands have been executed.

    Example: Add a rectangle around the page:

    \pgfpageslogicalpageoptions{1}{border code=\pgfstroke}

  - corner width=<size> adds black “rounded corners” to the page. See the description of the predefined layout rounded corners on page 211.

#### 16.4 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 <current logical page>. This counter is then incremented, until it is larger than <last logical shipout>. You can, however, directly change the value of <current logical page> by calling \pgfpagesphysicalpageoptions.

Another way to set the contents of a logical page is to use the following command:

\pgfpagesshipoutlogicalpage{<number>}<box>

  This command sets to logical page <number> to <box>. The <box> should be the code of a TEX box command. This command does not influence the counter <current logical page> and does not cause a physical shipout.

  \pgfpagesshipoutlogicalpage{0}\vbox{Hi!}

  This command can be used to set the contents of logical pages that are normally not filled.

The final way of setting a logical page is using the following command:

\pgfpagescurrentpagewillbelogicalpage{<number>}

  When the current TEX page has been typeset, it will be become the given logical page <number>. This command “interrupts” the normal order of logical pages, that is, it behaves like the previous command and does not update the <current logical page> counter.

  \pgfpagesuselayout{two screens with optional second} ... Text for main page. \clearpage \pgfpagescurrentpagewillbelogicalpage{2}
  Text that goes to second page
  \clearpage
  Text for main page.

[next] [prev] [prev-tail] [front] [up]