The pdfpages Package^{∗}

Andreas MATTHIAS

                      amat@kabsi.at

2001/11/21

Abstract

This package makes it easy to insert pages of external PDF documents. It is based on PDFL^{A}TEX and does not work with L^{A}TEX.

Contents

1 Introduction 1

2 Usage 1 2.1 Package Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2.2 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2.3 The Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3 Required Packages 6

4 Acknowledgment 7

1 Introduction

Creating PDF documents it is sometimes useful to insert pages of other, external PDF documents. This can be done with the \includegraphics command from

the graphics package. But a simple \includegraphics{doc.pdf} normally pro-

duces ‘Overfull \hbox’ and ‘Overfull \vbox’ warnings, because the size of the inserted pages does not match the print space.

The pdfpages package makes it easy to insert pages of external PDF documents without worrying about the print space. It even gives you the possibility to arrange several logical pages onto each sheet of paper. (Like ‘psnup’.)

2 Usage

2.1 Package Options

\usepackage[⟨options⟩]{pdfpages}

∗This file has version number v0.2a, last revised 2001/11/21.

⟨option⟩ – final: Inserts pages. This is the default.

draft: Does not insert pages, but prints a box and the filename instead.

2.2 Commands

\includepdf Inserts pages of an external PDF document.

\includepdf[⟨key=val⟩]{⟨filename⟩}

⟨key=val⟩ – A comma separated list of options using the

⟨key⟩=⟨value⟩ syntax.

⟨filename⟩ – Filename of the PDF document.

The following list describes all possible options of \includepdf. All options are using the ⟨key=value⟩ syntax. If options are marked with ‘changed’ on the left margin, their syntax or meaning has changed since pdfpages v0.1i. New options are marked with ‘new’.

• Main options:

pages Selects pages to insert. The argument is a comma separated list containing page numbers (pages={3,5,6,8}), ranges of page numbers (pages={4-9}) or any combination. To insert empty pages use {}. E. g.: pages={3,{},8-11,15} will insert page 3, an empty page, and pages 8, 9, 10, 11, and 15. Page ranges are specified by the following syntax: ⟨m⟩-⟨n⟩. This selects all pages between ⟨m⟩ and ⟨n⟩. Omitting ⟨m⟩ defaults to the first page, omitting ⟨n⟩ defaults to the last page of the document. E. g.: pages=- will insert all pages of the document. (Default: pages=1)

changed nup Puts multiple logical pages onto each sheet of paper. The syntax of this option is: nup=⟨xnup⟩x⟨ynup⟩. Where ⟨xnup⟩ and ⟨ynup⟩ specify the number of logical pages in vertical and horizontal direction, which are arranged on each sheet of paper. (Default: nup=1x1)

changed landscape Specifies the format of the sheet of paper (not of the logical pages). Either ‘true’ or ‘false’ (or no value, which is equivalent to ‘true’). (Default:

landscape=false)

• Layout options:

new delta Puts some horizontal and vertical space between the logical pages. The argument should be two dimensions, separated by space. See chapter 2.3 and figure 1. (Default: delta=0 0).

offset Displaces origin of the inserted pages. The argument should be two dimensions, separated by space. See chapter 2.3 and figure 1. (Default:

offset=0 0)

frame Puts a frame around each logical page. Either ‘true’ or ‘false’ (or no value, which is equivalent to ‘true’). (Default: frame=false) new column Pdfpages normally uses ‘row-major’ layout, where successive pages

are placed in rows along the paper. The column option changes the output into a ‘column-major’ layout, where successive pages are arranged in columns down the paper. Either ‘true’ or ‘false’ (or no value, which is equivalent to ‘true’). (Default: column=false)

new columnstrict By default the last page is not set in a strict ‘columnmajor’ layout, if the logical page does not fill up the whole page. The columnstrict option forces a strict ‘column-major’ layout for the last page. Either ‘true’ or ‘false’ (or no value, which is equivalent to ‘true’).

(Default: columnstrict=false)

1 4 2 5 3

     columnstrict=true

1 3 5 2 4

                             columnstrict=false

openright This option puts an empty page before the first logical page. In combination with nup=2x1, nup=2x2, etc., this means that the first page is on the right side. The same effect can be achieved with the pages option, if an empty page is inserted in front of the first page. Either ‘true’ or ‘false’ (or no value, which is equivalent to ‘true’). (Default: openright=false)

pagecommand Declares L^{A}TEX commands, which are executed on each sheet

of paper. (Default: pagecommand={\thispagestyle{empty}})

turn By default pages in landscape format are displayed in landscape orientation (if the PDF viewer supports this). With turn=false this can be prohibited. Either ‘true’ or ‘false’ (or no value, which is equivalent to ‘true’). (Default: turn=true)

new noautoscale By default pages are scaled automatically. This can be suppressed with the noautoscale option. In combination with the scale option (from graphicx) you has full control over the scaling process. Either ‘true’ or ‘false’ (or no value, which is equivalent to ‘true’). (Default:

noautoscale=false)

• Hypertext options:

link Inserted pages become a target of a hyperlink. The name of the link is ‘⟨filename ⟩.⟨page number ⟩’. ⟨filename⟩ is equal to the ⟨filename⟩ of \includepdf, i. e. potential file extensions are not stripped. Either ‘true’ or ‘false’ (or no value, which is equivalent to ‘true’). (Default:

link=false)

linkname Changes the default linkname created by the option link. Instead of ⟨filename⟩ the value of this option is used. E. g. linkname=mylink produces the linknames ‘mylink.⟨page number ⟩’.

(Default: linkname=⟨filename ⟩.⟨page number ⟩)

thread Combines pages to an article thread. Either ‘true’ or ‘false’ (or no

value, which is equivalent to ‘true’). (Default: thread=false) threadname Several threads are distinguished by their names. By default

this name is equal to the filename. It can be changed with this option. This is useful if the same file is inserted twice or more times and should not be combined to one single thread. (Default: threadname=⟨filename ⟩) linktodoc Lets the inserted pages be hyperlinks to the document from which

they were extracted. Either ‘true’ or ‘false’ (or no value, which is equivalent to ‘true’). (Default: linktodoc=false)

• Additional hypertext options:

linkfit Specifies the way the viewer displays a linked page. This option changes the default behavior of the option link. Possible values are:

       fitb, fith, fitv, fitr, xyz zoom ⟨integer ⟩, etc. These are destina-

tions (\pdfdest) like they are described in [1]. (Default: linkfit=fitr)

linktodocfit By default the option linktodoc opens the page in ‘Fit in Window’ view. Another view can be specified with this option. Possible values are the legal PDF tokens: /FitH ⟨top⟩, /FitV ⟨left⟩, etc. (See [2] for more details.) (Default: linktodocfit=/Fit)

linkfilename Sets the name (with path) of the file to be linked to by the option linktodoc. You will hardly ever need this option. (Default:

       linkfilename=⟨filename ⟩)

• Obsolete options:

deltax Puts some horizontal space between the logical pages. The argument should be one dimension, separated by space. (Default: deltax=0).

deltay Puts some vertical space between the logical pages. The argument should be one dimension, separated by space. (Default: deltay=0).

Internally the command \includepdf makes use of the \includegraphics command from the graphicx (actually graphics) package. This way it is possible to use all the options of \includegraphics, too. Options which are not interpreted

by \includepdf are passed directly to \includegraphics.

Especially the ‘trim’ and ‘clip’ options of \includegraphics are quite useful, if only parts of a page should be inserted. (Maybe to cut off the header and footer of the inserted pages.) Just use the ‘trim’ and ‘clip’ options as if they were options of \inlcudepdf. They will be passed to \includegraphics internally.

\includepdfmerge Inserts pages of several external PDF documents.

\includepdfmerge[⟨key=val⟩]{⟨file-page-list⟩}

⟨key=val⟩ – A comma separated list of options using the

⟨key⟩=⟨value⟩ syntax.

⟨file-page-list⟩ – ⟨filename⟩ [,⟨page spec⟩] [,⟨file-page-list⟩] A comma separated list of filenames and optional ⟨page spec⟩ specifiers. A ⟨page spec⟩ can be everything the option pages accepts.

The \includepdfmerge command uses the same options as \includepdf with one exception. The option pages has no meaning for \includepdfmerge. Instead the ⟨page spec⟩ specifier is used to specify which pages should be inserted. The ⟨page spec⟩ specifier accepts the same values as the pages option. If no ⟨page spec⟩ specifier is given, only the first page will be inserted.

[figure: delx; delx; dely; dely; offx; offy]

physical sheet of paper  delta=⟨delx⟩ ⟨dely⟩
logical pages  offset=⟨offx⟩ ⟨offy⟩

centered position

Figure 1: Layout \includepdfset If you need the same options for \includepdf all the time, it is possible to de-

fine global options with \includepdfset. The argument of \includepdfset is a comma separated list of options, using the ⟨key⟩=⟨value⟩ syntax. These options are processed each time \includepdf is called. Local options (passed as an optional argument directly to \includepdf) are overwriting global options:

   \includepdfset{⟨global options⟩}
   \includepdf[⟨local options⟩]{pdf-file}

Only options specific to this package can be made global by \includepdfset. Options of the graphicx package are not concerned.

\threadinfodict A thread information dictionary contains information about the thread, such as its title, author, and creation date. Use the macro \threadinfodict to set these entries. This macro has one argument taking the thread information dictionary in low-level PDF commands. See [2] for more information. This macro can be redefined. E. g.:

   \renewcommand*{\threadinfodict}
     {/I << /Title (My first thread) /Author (That's me!) >>}

2.3 The Layout

The default layout can be changed by the options delta and offset. Figure 1 shows the meaning of these options.

The inserted logical pages are being centered on the sheet of paper by default. To displace them use the offset option, which argument should be two dimensions. E. g. offset=10mm 14mm means that the logical pages are displaced by 10 mm in horizontal direction and by 14 mm in vertical direction.

By default logical pages are being arranged side by side. To put some space between them, use the delta option, whose argument should be two dimensions. Figure 1 shows the meaning of delta.

The layout options delta and offset always refer to a sheet of paper in portrait orientation. No matter whether you have set the landscape option to true, or not.

If you are confused about horizontal (x) and vertical (y) directions, just set the option turn=false. Now your PDF viewer shows the pages in the same orientation as in figure 1. And the options delta and offset have the same meaning as in figure 1. Regardless of any other options.

3 Required Packages

The pdfpages package requires the following packages:

eso-pic CTAN:macros/latex/contrib/supported/ms/contrib/ Download the

whole ms/ directory, because eso-pic.sty requires everyshi.sty from that directory.

graphicx, ifthen, calc These packages belong to the standard L^{A}TEX distribution.

Furthermore it requires a recent version of:

pdftex.def http://www.tug.org/applications/pdftex/pdftex.def

Since pdfTEX, Version 3.14159-1.00a-pretest-20010806, PDF import has improved a lot. This results in much smaller file sizes, faster processing and the intuitively correct treatment of landscape pages. The latest version of pdfTEX can be found

at: ftp://ftp.muni.cz/pub/tex/local/cstug/thanh/pdftex.

4 Acknowledgment

I would like to thank Rolf Niepraschk and Heiko Oberdiek for their useful hints and suggestions. As well as Ross Moore, who encouraged me to implement the hypertext features.

References

[1] Hàn Thế Thành, Sebastian Rahtz, Hans Hagen, The pdfTeX user manual, http://www.tug.org/applications/pdftex/pdftex-s.pdf

[2] PDF Reference, Second Edition, Adobe Systems Incorporated, http://partners.adobe.com/asn/developer/acrosdk/DOCS/PDFRef.pdf