Graphics and media/Including pages from PDF documents

page-imp.mkii and page-sel.mkiv defines some handy macros for handling import of existing PDF documents.

Insert a PDF page as a figure

To insert a single page from a PDF document into your text as a figure, you can write

\externalfigure[file.pdf][page=1,width=...]

By default, the interactive elements of the included PDF file are discarded. To enable the interactive elements of the included PDF file, use

\externalfigure[filename.pdf][interaction=yes]

Insert PDF page(s) as full-page figures

If you simply want to insert the first "n" number of pages from a PDF as full-page figures, use \copypages. For example, to insert the first 30 pages scaled down to 95%, you can write

\copypages[file.pdf][n=30][scale=950]

Insertion always starts from the first page. Your existing headers, footers, crop marks will be printed on each page.

If, in addition, you want to insert blank pages after specified pages use \insertpages. For example, to insert the first 30 pages of a PDF and add a blank page after the first and the third page, you can write

\insertpages[file.pdf][1,3][n=30,width=18cm]

If you do not want to start insertion from page 1 and you want to specify precisely, which pages or page-ranges to insert, then use \filterpages. For example, to insert pages 1, 3, 4, 5 and 6, you can write

\filterpages[file.pdf][1,3,4:6][width=18cm]

To insert even/odd pages up to page 30.

\filterpages[file.pdf][even][width=18cm] % even/odd

(See also Taco's hack in Processing Lists for handling ranges of numbers or this thread in the mailing list.)

Merge a single PDF page into your document

To insert a single page from a PDF document after the current page as a full page without adding any headers, footers, etc., use this:

\startpagefigure[file.pdf][page=1,...]\stoppagefigure

which is equal to

\startTEXpage
    \externalfigure[file.pdf][page=1,width=...]
\stopTEXpage

Optionally, you can also add some text to the bottom of the PDF page. For more info, see \startpagefigure.

Note that with the latest CTX standalone beta as of 2017/05/27 (mkiv, LuaTeX) the way described seems not to work properly. In the output you might find the first page only, no matter which page argument (page=2...n) you use. The following workaround might provide useful in that case:

  \startpagemakeup
    \filterpages[file][n] % n in Natural
  \stoppagemakeup

Include a section from other PDF document

It is possible to include a whole section (part, chapter, section...) from another PDF document generated, using the value of its reference key, such as the one generated from the following source:

\setuppagenumbering[alternative=doublesided]
\starttext
  \dorecurse{25}
    {\startchapter[title={Chapter}, reference={c-\recurselevel}]
      \dorecurse{\recurselevel}
        {\input knuth}
     \stopchapter}
\stoptext

In the document you want the section to be included, use a loop (\dostepwiserecurse) from the value you get from \firstsectionpage and from \lastsectionpage, such as in:

\starttext
\dostepwiserecurse {\firstsectionpage[x][c-18]} {\lastsectionpage[x][c-18]} {1} {
  \startTEXpage[pagestate=start]
    \externalfigure[x.pdf][page=\recurselevel]
  \stopTEXpage
 }
\stoptext

The source PDF document (the one from which pages are included) needs also its .tuc file used to generate it. Which pages are related to which references are contained in this file.

Page numbering with \startpagefigure

Experience shows that when you include a page from a PDF file using \startpagefigure, the page number of your document is not increased. The included PDF page is completely excluded from the page numbering process. This is annoying if you include a PDF page in the middle of your document, and expect your page numbers to be correct after the PDF page.

One solution is to use the commands \insertpages, \filterpages, and \copypages. They correctly increment the page numbers. But those commands include the PDF pages like additional "layers" on your page, so it means that your headers, footers, crop marks, etc. will be printed on top of or behind the included PDF pages. (Headers and footers will be printed behind, crop marks will be printed on top of the included PDF.)

Another solution is to fix the page number manually after using \startpagefigure.

Let's say we include 3 pages from a PDF like this:

% Several pages of text here
\startpagefigure[include_this.pdf][page=4]\stoppagefigure
\startpagefigure[include_this.pdf][page=6]\stoppagefigure
\startpagefigure[include_this.pdf][page=11]\stoppagefigure
% Several pages of text here

Notice that \startpagefigure can include only 1 page at a time. After compiling the above file with ConTeXt, your page numbers will look like this:

...
Page 10
Page 11
Page 12
include_this.pdf page 4
include_this.pdf page 6
include_this.pdf page 11
Page 13
Page 14
...

This behavior is also reflected in the command line output of ConTeXt. The value of userpage is the page number which will be printed in your header/footer. Continuing the above example:

pages           > flushing realpage 12, userpage 10
pages           > flushing realpage 13, userpage 11
pages           > flushing realpage 14, userpage 12
 <include_this.pdf>
pages           > flushing realpage 15, userpage 13 <-- include_this.pdf page 4
pages           > flushing realpage 16, userpage 13 <-- include_this.pdf page 6
pages           > flushing realpage 17, userpage 13 <-- include_this.pdf page 11
pages           > flushing realpage 18, userpage 13 <-- First ConTeXt page after PDF pages
pages           > flushing realpage 19, userpage 14

Therefore, you must "fix" your page number after you finish including PDF pages. You can either set it to a fixed number by saying:

% Several pages of text here
\startpagefigure[include_this.pdf][page=4]\stoppagefigure
\startpagefigure[include_this.pdf][page=6]\stoppagefigure
\startpagefigure[include_this.pdf][page=11]\stoppagefigure
\setcounter [userpage] [16]
% Several pages of text here

Or, which is even better, increment the page number by the number of included PDF pages:

% Several pages of text here
\startpagefigure[include_this.pdf][page=4]\stoppagefigure
\startpagefigure[include_this.pdf][page=6]\stoppagefigure
\startpagefigure[include_this.pdf][page=11]\stoppagefigure
\setcounter [userpage] [\pagenumber+3]
% Several pages of text here

This way your command line output will be:

pages           > flushing realpage 12, userpage 10
pages           > flushing realpage 13, userpage 11
pages           > flushing realpage 14, userpage 12
 <include_this.pdf>
pages           > flushing realpage 15, userpage 13 <-- include_this.pdf page 4
pages           > flushing realpage 16, userpage 13 <-- include_this.pdf page 6
pages           > flushing realpage 17, userpage 13 <-- include_this.pdf page 11
pages           > flushing realpage 18, userpage 16 <-- First ConTeXt page after PDF pages
pages           > flushing realpage 19, userpage 17

This \setcounter command was tested and worked correctly with ConTeXt ver: 2013.10.01 20:08 MKIV beta. Other commands like \incrementnumber[page] or \page[+1] or \page[16] did not help to solve this problem correctly.

Printing Slides from a presentation

If you want to make a 2*3 matrix from all the slides in the document you can use the following example:

\setuppapersize
  [A4][A4] % or [A4,landscape][A4,landscape]

\setuplayout
  [header=0pt,footer=1cm,
   backspace=1cm,topspace=1cm,
   width=middle,height=middle]

\setupfootertexts
  [presentation---\currentdate\space---\space\pagenumber]

\starttext
  \combinepages[slides][nx=2,ny=3,frame=on]
\stoptext

Slicing the pages

The opposite of combining the pages together is to slice them in pieces.

This will make 3*3 pages out of your document (well, it depends on proportions).

\starttext
    \slicepages[slice1.pdf][n=3]
\stoptext

Adding comments to pages

\setuppagecomment[state=start,location=right]

\startpagecomment
\input knuth
\stoppagecomment

TODO: prepare a graphics for each example (See: To-Do List)

Reformatting a Single-Sided pdf for Double-Sided Printing

Context can be used as a pdf postprocessor.

This example takes an original single-sided document and applies differing horizontal offsets to odd and even pages. This simultaneously

• compensates for the fixed offset in the original, and
• introduces a new alternating one as required for double-sided printing

It is useful for printing reference manuals downloaded from the web.

% replace "Manual" with the name of your original pdf
\define\MySingleSidedDocument{Manual}

% can adjust topspace to move page etc
\setuplayout[\MySingleSidedDocument,topspace=1cm,header=0cm,backspace=0cm]
% suppress page numbering
\setuppagenumbering[location=]

\starttext

\getfiguredimensions[\MySingleSidedDocument]

\dorecurse\noffigurepages
  {\hbox to \textwidth
     {\ifodd\recurselevel
%adjust number to set odd page horizontal position
        \hskip-0.1cm\externalfigure[\MySingleSidedDocument][page=\recurselevel]\hss
      \else
%adjust number to set even page horizontal position
        \hskip-1.8cm\externalfigure[\MySingleSidedDocument][page=\recurselevel]\hss
      \fi}}
\stoptext