summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pages.tex
diff options
context:
space:
mode:
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.tex810
1 files changed, 387 insertions, 423 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
index 452690a36d0..1975199a802 100644
--- 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
@@ -10,38 +10,36 @@
\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.
+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.
+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}
@@ -55,23 +53,22 @@ 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
+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:
+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}
@@ -88,24 +85,23 @@ As a second example, let us put two pages produced by the
\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:
-
+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}
@@ -119,7 +115,9 @@ This text is shown on the left.
This text is shown on the right.
\end{document}
\end{codeexample}
+%
and then typeset
+%
\begin{codeexample}[code only]
\documentclass{article}
@@ -134,21 +132,22 @@ 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:
+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:
+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
@@ -164,120 +163,108 @@ printing on letter paper:
\end{codeexample}
-
\subsection{The Predefined Layouts}
-This section explains the predefined layouts in more detail. You
-select a layout using the following command:
+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.
+ 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.
+ 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]|
+ \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}
+ 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}
+ 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.
+ 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.
+ 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}.
+ 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]
+\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]
@@ -285,60 +272,56 @@ select a layout using the following command:
...
\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}
+ 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.
+ 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.
-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.
- 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:
+ Here is an example:
+ %
\begin{codeexample}[code only]
\pgfpagesdeclarelayout{resize to}
{
@@ -360,58 +343,55 @@ command:
}%
}
\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.
+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}.
+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:
+\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:
+ 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
{%
@@ -434,72 +414,70 @@ following two commands are used to define the layout:
}%
\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}
+ 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.
-
+ 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
@@ -508,150 +486,134 @@ following two commands are used to define the layout:
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:
+ %
+ \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:
+ \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:
+ %
+ \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}
+ %
+ \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.
+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|.
+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:
+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.
-
+ 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.
+ 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:
+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.
-
+ 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}
...
@@ -664,8 +626,10 @@ Text that goes to second page
Text for main page.
\end{codeexample}
+ %
\end{command}
+
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "pgfmanual"