% content=tex
%
% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa

\usemodule[mag-01,abr-02] % \setuplayout[grid=yes] \showgrid

\setvariables
  [magazine]
  [title={Manipulating the foreground},
   author=Hans Hagen,
   affiliation=PRAGMA ADE,
   date=November 2003,
   number=4]

\startbuffer[abstract]
  This issue describes a way to collapse an existing document is a
  rather special way by manipulating overlays. Only read this
  document if you are familiar with \PDF\ document inclusion and
  overlays.
\stopbuffer

\starttext \setups [titlepage] \setups [title]

There are several commands to include pages of a typeset document
(in \PDF\ format) into another document, for instance \type
{\slicepages}, \type {\insertpages}, \type {\filterpages}, \type
{\copypages} and \type {\combinepages}. Especially the first command
can be set up to reconstruct documents. The following setup was used
to typeset TugBoat 21/4 which was a kind of facsimile of \THANH's
thesis.

\starttyping
\starttext

% Tugboat is typeset in 10 points Computer Modern Roman in (more
% or less) letter format.

\setupbodyfont
  [10pt]

\setuppapersize
  [letter]
  [letter]

% The basine of the header line should be at 4pc from the top. For
% consistency we place the top of the footer line at 4pc from the
% bottom. Normally a tugboat does not have a footerline.

\setuplayout
  [topspace=0cm,
   header=\dimexpr(4pc+\dp\strutbox),
   headerdistance=1pc,
   bottomspace=0cm,
   footer=4pc,
   backspace=1in,
   width=middle,
   height=middle]

% We force the header and footer lines in a certain
% direction.

\setupheader[before=\vfill]
\setupfooter[after=\vfill]

% We use a doublesided layout, and do ou rown pagenumer placement.

\setuppagenumbering
  [alternative=doublesided,
   location=]

% There is the normal tugboat header ...

\setupheadertexts
  [TUGBoat, Volume 21 (2000), No. 4][pagenumber]
  [pagenumber][TUGBoat, Volume 21 (2000), No. 4]

% ... and a special footer.

\setupfootertexts
  [Micro-typographic extensions to the \TeX\ typesetting system]
  [\ifcase\slicedpagenumber\else\slicedpagenumber\fi]
  [\ifcase\slicedpagenumber\else\slicedpagenumber\fi]
  [Micro-typographic extensions to the \TeX\ typesetting system]

% Here starts the real thing. First the cover page:

\startstandardmakeup

  \centeredbox{Cover with graphic}

\stopstandardmakeup

% Next comes Barbara's introduction. We set the pagenumber to the
% one following issue 3.

\setuppagenumber[number=315]

\title{Defeating the Lion}

\startcolumns
  \dorecurse {149} {Barbara's introduction }
\stopcolumns

% We need to make sure that the thesis starts at a right page.

\page [right]

% Here comes the thesis.

\slicepages
  [xthesis.pdf]
  [n=0,                        % triggers full page clipping
   voffset=1in,                % probably thanhs origin
   height=23.55cm,             % a compromize for page 46
   width=22cm,                 % wide margins
   offset=\dimexpr(-1in- 2pt)] % experimental value
  [offset=\dimexpr(-1in+19pt)] % experimental value

\stoptext
\stoptyping
The main command in this setup is \type {\slicepages}, a command
that takes two or three arguments. Here we needed to specify a
slightly different clipping area for left and right hand pages.

For quick and dirty jobs, this method is not that comfortable
because it needs some experimenting and measuring. Nevertheless,
when Tobias Burnus posted the following question to the \CONTEXT\
mailing list, my first thoughts went to \type {\slicepages}.

\starttyping
I have a A5 document (as PDF file) which should be nx=2,ny=1 placed
on a landscape A4 paper.

The problem is that I want to have more whitespace on the left side
for stapling/punching which can easiest be done by letting the
included pages overlap. I tried distance=-4cm but it didn't work as
expected.

Desired result:

+---+-------------+------------+
|   |  first a5 . | second a5  |
|   |           . |            |
|   |           . |            |
|   |           . |            |
+---+-------------+------------+
 |              ^^^ - included pages overlap
 | extra wide margin
\stoptyping

Since he tried to solve this with \type {\combinepages}, I decided
to give that one a try.

First we make a small test file:

\typefile{mag-0004-000.tex}

It's often best to solve this kind of problems stepwise:

\typefile{mag-0004-001.tex}

\startpostponing

\placefigure
  [here] [fig:step 1] {Step 1}
  {\externalfigure[mag-0004-001.pdf][frame=on,width=\textwidth]}

\placefigure
  [here] [fig:step 1] {Step 2}
  {\externalfigure[mag-0004-002.pdf][frame=on,width=\textwidth]}

\stoppostponing

This leads to \in {figure} [fig:step 1]. We need to shift this
assemble to the right, so let's tune the layout a bit.

\typefile{mag-0004-002.tex}

\in {Figure} [fig:step 2] is still not what Tobias wants. Now, how
do we shift the left (odd) pages to the right while \type
{\combinepages} has no key for that?

The trick is in abusing the background handler (aka overlays). Many
commands provide this option, and backgrounds are specified as:

\starttyping
..., background=whatever, ...
..., background={color,whatever}, ...
..., background={whatever,whoknows}, ...
..., background={whatever,foreground,whoknowns}, ...
\stoptyping

Here \type {foreground} is a special kind of overlay, being the
content that gets the background. Normally we only use this overlay
when we want to move the foreground to the back (i.e. put something
else on top of it). The content itself is flushed with the command
\type {\foregroundbox} and once flushed, it will not be used again.

\typefile{mag-0004-003.tex}

So, we define a background layer, and for each odd page we flush the
foregroundbox and shift it to the right. For even pages, we leave
the  foregroundbox untouched and as a result it will be flushed in
the normal way.

\setups [listing] \setups [lastpage] \stoptext
