Source Browser ?

1% language=us runpath=texruns:manuals/metafun
2
3\startcomponent metafun-backgrounds
4
5\environment metafun-environment
6
7\startchapter[reference=sec:page,title={Page backgrounds}]
8
9\startintro
10
11Especially in interactive documents, adding backgrounds to the page and text
12areas not only enhances readability, but also makes it more convenient to
13identify header, footers and navigational areas. In this chapter we will
14demonstrate that with \METAPOST\ we can go beyond the \TEX\ based features
15present in \CONTEXT. One section is dedicated to graphics and printing,
16especially bleeding.
17
18\stopintro
19
20\startsection[title={The basic layout}]
21
22\index {layout}
23
24In the \CONTEXT\ manual you can find many details on the composition of the page.
25When \TEX\ typesets text, crossing the page boundary triggers \TEX's output
26routine. This routine is responsible for pasting the body text that goes onto a
27page in the correct area. A simple representation of such a page is:
28
29\startbuffer[a]
30\startuseMPgraphic{layout 1}
31  pickup pencircle scaled 1mm ;
32  fill unitsquare xyscaled (7cm,8cm)
33    withcolor .85white ;
34  fill unitsquare xyscaled (5cm,5cm) shifted (1cm,1.5cm)
35    withcolor .625yellow ;
36  fill unitsquare xyscaled (5cm,1cm) shifted (1cm,.5cm)
37    withcolor .625red ;
38  fill unitsquare xyscaled (5cm,1cm) shifted (1cm,6.5cm)
39    withcolor .625red ;
40  draw unitsquare xyscaled (5cm,7cm) shifted (1cm,.5cm)
41    withcolor .25white ;
42  drawarrow (2cm,8cm) -- top (2cm,7.5cm) ;
43  drawarrow (0cm,7cm) -- lft (1cm,7cm) ;
44  clip currentpicture to unitsquare xyscaled (7cm,8cm) ;
45\stopuseMPgraphic
46\stopbuffer
47
48\startbuffer[b]
49\startuseMPgraphic{layout 2}
50  \includeMPgraphic{layout 1}
51  clip currentpicture to unitsquare scaled 3cm shifted (0,5cm) ;
52  currentpicture := currentpicture scaled 2 shifted (0,-8cm) ;
53  setbounds currentpicture to unitsquare xyscaled (6cm,8cm) ;
54\stopuseMPgraphic
55\stopbuffer
56
57\getbuffer[a,b]
58
59\startbuffer[c]
60\startlinecorrection[blank]
61\hbox
62  {\useMPgraphic{layout 1}\hskip1cm
63   \useMPgraphic{layout 2}}
64\stoplinecorrection
65\stopbuffer
66
67\getbuffer[c]
68
69The red areas are the header and footer, while the yellow areas contains the text
70flow. We can turn headers on and off and|/|or hide them. For this reason, the
71header, text and footer areas together make up the height of the text.
72
73A close look at the left picture will reveal that the two arrows point to the
74center of the lines. This is achieved by the \type {top} and \type {lft}
75directives. If we would not have clipped the picture, the arrow would have stuck
76half a line width outside the gray area that represents the page. When
77constructing such pictures, one should really pay attention to such details,
78since it pays off in the overall look and feel of the document.
79
80The vertical arrow represents the top space, while the horizontal arrow denotes
81the distance to the back of the cover (back space). By changing their values, you
82can shift the main body text on the page. In a double sided layout scheme, the
83back space is automatically mirrored on even pages.
84
85An advanced \METAPOST\ user may wonder why we hard code the dimensions, and avoid
86\METAPOST's powerful mechanisms for defining relations. Our experience has taught
87us that in pictures like this, providing a general solution seldom pays large
88dividents or savings in time.
89
90\typebuffer[a]
91
92As you can see, the left graphic is defined as a series of rectangles. The \type
93{xyscaled} macro is part of the \CONTEXT\ files, and saves some typing and space.
94It is defined as a primary, requiring both left and right operands.
95
96\starttyping
97primarydef p xyscaled q =
98  p xscaled (xpart q) yscaled (ypart q)
99enddef ;
100\stoptyping
101
102Zooming in on the top left corner only takes a few lines. First we clip the
103correct part, next we scale it up, and finally we let the bounding box suit the
104left picture.
105
106\typebuffer[b]
107
108This code demonstrates how you can reuse a graphic inside another one. This
109strategy can easily be used to stepwise build (or extend) graphics. The two
110graphics were put side by side with the following command. Watch the use of line
111correction commands. They optimize the white space around the graphic.
112
113\typebuffer[c]
114
115As soon as you want to make an electronic document, you will want to use
116different areas of the screen for different purposes: text, menus, buttons, etc.
117For this reason, \CONTEXT\ provides not only left and right margins, but also
118additional left and right edge areas and top and bottom margins. These areas are
119shown in the figure on the next page.
120
121\startbuffer[aa]
122pickup pencircle scaled 2pt ;
123
124numeric w[], h[], x[], y[], u ; u := .5cm ;
125
126numeric width  ; width  := \the\textwidth  ;
127numeric height ; height := \the\textheight ;
128\stopbuffer
129
130\startbuffer[bb]
131w[1] = 2u ; w[2] = 3u ; w[4] = 3u ; w[5] = 2u ;
132h[1] = 1u ; h[2] = 1u ; h[4] = 1u ; h[5] = 1u ;
133
134w[1]+w[2]+w[3]+w[4]+w[5]+4u = width  ;
135h[1]+h[2]+h[3]+h[4]+h[5]+4u = height ;
136
137x[1] = 1u ;                y[1] = 1u ;
138x[2] = x[1] + w[1] + .5u ; y[2] = y[1] + h[1] + .5u ;
139x[3] = x[2] + w[2] + .5u ; y[3] = y[2] + h[2] + .5u ;
140x[4] = x[3] + w[3] + .5u ; y[4] = y[3] + h[3] + .5u ;
141x[5] = x[4] + w[4] + .5u ; y[5] = y[4] + h[4] + .5u ;
142\stopbuffer
143
144\startbuffer[cc]
145def do_it (expr xx, yy, cc) =
146  draw unitsquare
147    xyscaled (w[xx],h[yy]) shifted (x[xx],y[yy])
148    withcolor if cc : .625red else : .625yellow fi ;
149enddef ;
150
151fill unitsquare xyscaled (width,height) withcolor .85white;
152
153do_it (1,1,false) ; do_it (5,1,false) ;
154do_it (2,1,false) ; do_it (3,1,false) ; do_it (4,1,false) ;
155
156do_it (1,2,false) ; do_it (5,2,false) ;
157do_it (2,2,true ) ; do_it (3,2,true ) ; do_it (4,2,true ) ;
158
159do_it (1,3,false) ; do_it (5,3,false) ;
160do_it (2,3,true ) ; do_it (3,3,true ) ; do_it (4,3,true ) ;
161
162do_it (1,4,false) ; do_it (5,4,false) ;
163do_it (2,4,true ) ; do_it (3,4,true ) ; do_it (4,4,true ) ;
164
165do_it (1,5,false) ; do_it (5,5,false) ;
166do_it (2,5,false) ; do_it (3,5,false) ; do_it (4,5,false) ;
167\stopbuffer
168
169\startbuffer[dd]
170def do_it (expr yy, tt) =
171  path p ;
172  p := unitsquare xyscaled (w[1],h[yy]) shifted (x[1],y[yy]) ;
173  label.lft(tt, center p shifted (-w[1]/2-u-.25cm,0)) ;
174enddef ;
175
176do_it (1,btex bottom etex) ;
177do_it (2,btex footer etex) ;
178do_it (3,btex text   etex) ;
179do_it (4,btex header etex) ;
180do_it (5,btex top    etex) ;
181\stopbuffer
182
183\startbuffer[ee]
184def do_it (expr xx, tt) =
185  path p ;
186  p := unitsquare xyscaled (w[xx],h[1]) shifted (x[xx],y[1]) ;
187  label(tt, center p shifted (0,height-h[1]/2)) ;
188enddef ;
189
190do_it (1,btex edge   etex) ;
191do_it (2,btex margin etex) ;
192do_it (3,btex text   etex) ;
193do_it (4,btex margin etex) ;
194do_it (5,btex edge   etex) ;
195\stopbuffer
196
197\startbuffer[ff]
198setbounds currentpicture to
199  unitsquare xyscaled (width,height) ;
200\stopbuffer
201
202% We use two chars for buffer names, otherwise we can get
203% get in conflict with the next buffers with similar names.
204
205\startpostponing
206\centerbox{\processMPbuffer[aa,bb,cc,dd,ee,ff]}
207\stoppostponing
208
209When defining this graphic, all areas have related dimensions. Here it makes
210sense to let \METAPOST\ calculate these dimensions as much as possible. First we
211define the five by five matrix of areas. We pass the width and height of the main
212text area. Because they are stored in \TEX\ dimension registers, we have to
213prefix them by \type {\the}.
214
215\typebuffer[aa]
216
217We now specify the lower left corners using \type {=} instead of the \type {:=},
218which means that \METAPOST\ will calculate \type {w[3]} and \type {h[3]} for us.
219
220\typebuffer[bb]
221
222Because we are going to repeat ourselves, we draw the areas using a macro.
223Depending on its importance, we color it red or yellow.
224
225\typebuffer[cc]
226
227This picture in itself is not yet explanatory, so we add some labels. Again, we
228use a macro, which we feed with a picture generated by \TEX. Since these pictures
229are filtered from the source and pre||processed, we cannot embed the \type
230{btex}||\type {etex} in the macro \type {do_it} and pass a string. It has to be
231done this way. \footnote {This is true only in a regular \METAPOST\ run. In
232\CONTEXT\ \MKIV\ we follow a different route.}
233
234\typebuffer[dd]
235
236In the horizontal direction we have edges, margins and text. There are left and
237right edges and margins, which are swapped on even pages when you typeset a
238double sided document.
239
240\typebuffer[ee]
241
242Since we want the graphic to match the dimensions of the text area of the current
243page, we have to make sure that the bounding box is adapted accordingly. By this
244action, the labels will fall outside the bounding box. When we directly embed a
245graphic, this works ok, but when we start scaling and reusing, due to the object
246reuse mechanism the graphic will be clipped to the bounding box.
247
248\typebuffer[ff]
249
250In the following sections we will demonstrate how you can put graphics behind
251these 25~areas, as well as behind the (left and right) page.
252
253\stopsection
254
255\startsection[title={Setting up backgrounds}]
256
257\index {overlays}
258\index {backgrounds}
259
260One way of protecting a document for unwanted usage is to put an annoying word in
261the background. If you like this, you may try the following. The macro \type
262{ysized} is part of the macros that come with \CONTEXT\ and scales a picture to a
263specific size.
264
265\startbuffer[a]
266\startuniqueMPgraphic{concept}
267  draw btex \colored[s=.8]{\bf CONCEPT} etex rotated 60 ;
268  currentpicture := currentpicture
269    ysized (\overlayheight-.5cm) ;
270\stopuniqueMPgraphic
271
272\defineoverlay[concept][\uniqueMPgraphic{concept}]
273\stopbuffer
274
275\typebuffer[a]
276
277You can now put this graphic in the page background by
278saying:
279
280\starttyping
281\setupbackgrounds[page][background=concept]
282\stoptyping
283
284You may consider the next alternative a bit better, but still it renders the text
285unreadable. Like \type {xysized}, the macro \type {enlarged} is not part of
286standard \METAPOST, but comes with \CONTEXT.
287
288\startbuffer[b]
289\startuniqueMPgraphic{copyright}
290  picture p ; p := btex \colored[s=.8]{COPYRIGHT} etex
291    rotated 90 ;
292  setbounds p to boundingbox p enlarged 1pt ;
293  draw p ;
294  currentpicture := currentpicture
295    xysized (\overlaywidth,\overlayheight) ;
296\stopuniqueMPgraphic
297
298\defineoverlay[copyright][\uniqueMPgraphic{copyright}]
299\stopbuffer
300
301\typebuffer[b]
302
303Again, we put this graphic in the background. By using a unique graphic, we make
304sure that it's rendered only once and reused when possible.
305
306\startbuffer[c]
307\setupbackgrounds[text][rightmargin][background=copyright]
308\stopbuffer
309
310\typebuffer[c]
311
312\doifnotmode{screen}{\getbuffer[b,c]}
313
314In both cases, we slightly scale down the graphic. We do so because otherwise a
315small portion of the text is clipped off. This is unrelated to \TEX\ or
316\METAPOST, but a characteristic of the font. Compare the following Pagella, Latin
317Modern and Termes gi's (the Pagella is the body font of this text).
318
319\startbuffer
320\hbox \bgroup
321    \hbox{\definedfont[file:texgyrepagella-regular at 6cm]gi}%
322    \hbox{\definedfont[file:lmroman10-regular      at 6cm]gi}%
323    \hbox{\definedfont[file:texgyretermes-regular  at 6cm]gi}%
324\egroup
325\stopbuffer
326
327\typebuffer
328
329\startlinecorrection[blank]
330{\showboxes \getbuffer}
331\stoplinecorrection
332
333Watch how the bounding boxes differ and sometimes cross the shape. So, in order
334not to loose part of a glyph when clipping, you need to add a bit of space. \in
335{Figure} [fig:annoying] shows the two backgrounds in action.
336
337\startbuffer
338\getbuffer[a,b]
339\def\ShowPage#1% % (yet) no image as background to image
340  {\framed       % possible due to nested file problems
341      [background=#1,offset=overlay]
342      {\typesetfile[mfun-900.tex][page=1,width=.4\textwidth]}}
343\startcombination
344  {\ShowPage{concept}}   {concept}
345  {\ShowPage{copyright}} {copyright}
346\stopcombination
347\stopbuffer
348
349\placefigure
350  [here][fig:annoying]
351  {Two examples of annoying backgrounds.}
352  {\getbuffer}
353
354If you really want to add such texts to a document, in \CONTEXT\ we don't have to
355use the page background, but can use one of the layout areas instead (like \type
356{[text][text]} or \type {[text][leftmargin]})
357
358\typebuffer[d]
359
360There is one drawback: when your left and right margin have different dimensions,
361the text will be scaled differently on odd and even pages. Normally this is no
362problem for a draft.
363
364As an alternative you can use the \type {\setuptexts} command and wrap the
365graphic in a box with the right dimensions, using code like:
366
367\starttyping
368\startuniqueMPgraphic{copyright}
369  picture p ; p := btex COPYRIGHT etex rotated 90 ;
370  setbounds p to boundingbox p enlarged 1pt ;
371  draw p withcolor .8white ;
372  xyscale_currentpicture(\the\leftmarginwidth,\the\textheight) ;
373\stopuniqueMPgraphic
374
375\setuptexttexts [margin] [] [\uniqueMPgraphic{copyright}]
376\stoptyping
377
378The graphic goes into the outer margin. The second argument can be used to put
379something in the inner margin.
380
381\stopsection
382
383\startsection[title={Multiple overlays}]
384
385\index{overlays+stack}
386
387\setupbackgrounds[text][rightmargin][background=]
388
389You can stack overlays. Consider the next case, where we assume that you have
390enabled interaction support using \type {\setupinteraction[state=start]}:
391
392\starttyping
393\setupbackgrounds
394  [page]
395  [background={color,nextpage},
396   backgroundcolor=darkyellow]
397\stoptyping
398
399Here, the page gets a colored background and a hyperlink to the next page,
400previously defined by:
401
402\starttyping
403\defineoverlay[nextpage][\overlaybutton{nextpage}]
404\stoptyping
405
406An \type {\overlaybutton} is just a button, with all attributes (color, frame,
407etc) set to nothing, having the dimensions of the overlay. The argument is one of
408the permitted destinations, like \type {nextpage}, \type {firstpage}, \type
409{SearchDocument} and alike.
410
411For efficiency reasons, the background areas (like \type {[text][text]}) are
412calculated only when their definition has changed. When a background changes per
413page, we have to recalculate it on each page. In the next example, the macro
414\type {\overlaybutton} generates a different button on each page. But, since we
415don't explicitly set the background at each page, there is no way the background
416drawing mechanism can know that this button has changed. Therefore, we must force
417recalculation with:
418
419\starttyping
420\setupbackgrounds[state=repeat]
421\stoptyping
422
423You can test this concept yourself with the following code. Here we assume that
424you have a file called \type {tufte.tex} on your system, which is the case if you
425have \CONTEXT\ installed. However, you can just as easily use any file having a
426paragraph of two of text.
427
428\starttyping
429\starttext
430\setupinteraction[state=start]
431\setupbackgrounds[state=repeat]
432\defineoverlay[nextpage][\overlaybutton{nextpage}]
433\setupbackgrounds[text][text][background=nextpage]
434\dorecurse{20}{\input tufte \par}
435\stoptext
436\stoptyping
437
438Note that you can move forward from page to page in the resulting \PDF\ file by
439clicking on each page with the mouse. Now compile this file without setting the
440background state to \type {repeat} and note the difference as you click pages
441with the mouse.
442
443Setting the state was not needed when we used the page background:
444
445\starttyping
446\setupbackgrounds[page][background=nextpage]
447\stoptyping
448
449The \type {\dorecurse} macro is handy for testing since it saves us typing. One
450can nest this macro as in:
451
452\starttyping
453\dorecurse{20}{\dorecurse{10}{Hello World! }\par}
454\stoptyping
455
456The current step is available in \type {\recurselevel} and the depth (nesting
457level) in \type {\recursedepth}.
458
459\stopsection
460
461\startsection[title={Crossing borders}]
462
463\index{backgrounds}
464
465In many cases, the previously mentioned background areas will suffice, but in the
466case of more complicated backgrounds, you may wish to use \METAPOST\ to draw
467graphics that combine or span these areas.
468
469At runtime \CONTEXT\ saves information on the layout that can be picked up by
470\METAPOST. The framework for a page graphic is:
471
472\starttyping
473StartPage;
474  % all kind of commands
475StopPage ;
476\stoptyping
477
478Between the \type {StartPage} and \type {StopPage} command you have access to a
479wide range of variables:
480
481\starttabulate[|l|Tp|]
482\HL
483\NC page       \NC PaperHeight PaperWidth               \NC \NR
484\NC            \NC PrintPaperHeight PrintPaperWidth     \NC \NR
485\NC            \NC PageOffset PageDepth                 \NC \NR
486\NC margins    \NC TopSpace BackSpace                   \NC \NR
487\NC text       \NC MakeupHeight MakeupWidth             \NC \NR
488\NC vertical   \NC TopHeight TopDistance                \NC \NR
489\NC            \NC HeaderHeight HeaderDistance          \NC \NR
490\NC            \NC TextHeight                           \NC \NR
491\NC            \NC FooterDistance FooterHeight          \NC \NR
492\NC            \NC BottomDistance BottomHeight          \NC \NR
493\NC horizontal \NC LeftEdgeWidth LeftEdgeDistance       \NC \NR
494\NC            \NC LeftMarginWidth LeftMarginDistance   \NC \NR
495\NC            \NC TextWidth                            \NC \NR
496\NC            \NC RightMarginDistance RightMarginWidth \NC \NR
497\NC            \NC RightEdgeDistance RightEdgeWidth     \NC \NR
498\HL
499\stoptabulate
500
501Since using these variables to construct paths is not that handy because the
502areas are available as predefined paths, which we will demonstrate here.
503
504\placefigure
505  [here][fig:back 1]
506  {A background with combined areas.}
507  {\startcombination
508     {\typesetfile[mfun-900.tex][page=2,width=.4\textwidth]}{even}
509     {\typesetfile[mfun-900.tex][page=3,width=.4\textwidth]}{odd}
510   \stopcombination}
511
512In \in {figure} [fig:back 1] you see two pages (odd and even) with a background
513spanning the outer margin and the text area. You can access an area in two ways.
514The area itself is available as \type {Area}.
515
516\starttyping
517StartPage ;
518  fill Area[Text][Text] withcolor .85white ;
519StopPage ;
520\stoptyping
521
522If you use an area this way, you will notice that it is not positioned at the
523right place. An \type {Area} is just a rectangle. If you want a positioned area,
524you should use the \type {Field} array:
525
526\starttyping
527StartPage ;
528  fill Field[Text][Text] withcolor .85white ;
529StopPage ;
530\stoptyping
531
532The location of an area is available in \type {Location}, so the previous
533definition is the same as:
534
535\starttyping
536StartPage ;
537  fill Area[Text][Text] shifted Location[Text][Text]
538    withcolor .85white ;
539StopPage ;
540\stoptyping
541
542The following definition fills and draws the margin and text areas.
543
544\typebuffer[back-2]
545
546This background is assigned to the page layer by saying:
547
548\typebuffer[back-0]
549
550As you can see in \in {figure} [fig:back 2], the text is typeset rather tightly
551between the left and right margins.
552
553\placefigure
554  [here][fig:back 2]
555  {A background with split areas.}
556  {\startcombination
557     {\typesetfile[mfun-900.tex][page=4,width=.4\textwidth]}{even}
558     {\typesetfile[mfun-900.tex][page=5,width=.4\textwidth]}{odd}
559   \stopcombination}
560
561This can easily be solved by enlarging the areas a bit. The next example
562demonstrates this on the text area, which is shown in \in {figure} [fig:back 3].
563
564\typebuffer[back-3]
565
566\placefigure
567  [here][fig:back 3]
568  {A background with enlarged text area.}
569  {\startcombination
570     {\typesetfile[mfun-900.tex][page=6,width=.4\textwidth]}{even}
571     {\typesetfile[mfun-900.tex][page=7,width=.4\textwidth]}{odd}
572   \stopcombination}
573
574The \type {enlarged} macro can be used like \type {shifted} and accepts either a
575numeric or a pair.
576
577How do we define a background as in \in {figure} [fig:back 1]? Because \type
578{Field} provides us the positioned areas, we can use the corners of those.
579
580\typebuffer[back-1]
581
582In this definition we calculate a different path for odd and even pages. When
583done, we enlarge the path a bit. If you want to use different offsets in all
584directions, you can use moved corner points.
585
586\typebuffer[back-4]
587
588Here we displace the corners randomly which leads to backgrounds like \in
589{figure} [fig:back 4]. The following definition would have worked as well:
590
591\typebuffer[back-4x]
592
593\placefigure
594  [here][fig:back 4]
595  {A random text area.}
596  {\startcombination
597     {\typesetfile[mfun-900.tex][page=8,width=.4\textwidth]}{even}
598     {\typesetfile[mfun-900.tex][page=9,width=.4\textwidth]}{odd}
599   \stopcombination}
600
601The previous graphics are defined as usable ones, which means that they will be
602recalculated each page. This is rather inefficient when the shapes don't change.
603But, using a reusable graphic instead, would result in only one graphic for both
604pages. Since the layout for the left and right page differs, another method is
605needed.
606
607Instead of putting the same graphic on the page layer, we put two different ones
608on the left and right page layer.
609
610\starttyping
611\defineoverlay[left page] [\useMPgraphic{left page}]
612\defineoverlay[right page][\useMPgraphic{right page}]
613
614\setupbackgrounds[leftpage] [background=left page]
615\setupbackgrounds[rightpage][background=right page]
616\stoptyping
617
618Now we only have to split the previously defined graphic into two parts. In order
619to force consistency, we isolate the code that fills and draws. The left page
620code looks like:
621
622\starttyping
623\startreusableMPgraphic{left page}
624  StartPage ;
625    path Main ; Main :=
626      llcorner Field[OuterMargin][Text] --
627      lrcorner Field[Text]       [Text] --
628      urcorner Field[Text]       [Text] --
629      ulcorner Field[OuterMargin][Text] -- cycle ;
630    \includeMPgraphic{draw page}
631  StopPage ;
632\stopreusableMPgraphic
633\stoptyping
634
635The right page text looks similar:
636
637\starttyping
638\startreusableMPgraphic{right page}
639  StartPage ;
640    path Main ; Main :=
641      lrcorner Field[OuterMargin][Text] --
642      llcorner Field[Text]       [Text] --
643      ulcorner Field[Text]       [Text] --
644      urcorner Field[OuterMargin][Text] -- cycle ;
645    \includeMPgraphic{draw page}
646  StopPage ;
647\stopreusableMPgraphic
648\stoptyping
649
650Watch how we used a reusable graphic first and a simple usable one next.
651Actually, the next graphic is not a stand alone graphic.
652
653\starttyping
654\startuseMPgraphic{draw page}
655  Main := Main enlarged 6pt ;
656  pickup pencircle scaled 2pt ;
657  fill Page withcolor .625white ;
658  fill Main withcolor .850white ;
659  draw Main withcolor .625red ;
660\stopuseMPgraphic
661\stoptyping
662
663We have seen some predefined paths and locations. Apart from the \type {Page}
664path, they take two arguments that specify their position on the layout grid.
665
666\starttabulate[|lT|l|]
667\HL
668\NC path Area     [][] \NC an area similar to a \CONTEXT\ one    \NC \NR
669\NC pair Location [][] \NC the position of this area             \NC \NR
670\NC path Field    [][] \NC the area positioned at the right place \NC \NR
671\NC path Page          \NC the page itself \NC \NR
672\HL
673\stoptabulate
674
675Some less used and more obscure variables are the following.
676
677\starttabulate[|lT|l|]
678\HL
679\NC numeric Hstep [] \NC the horizontal distance to the previous area \NC \NR
680\NC numeric Vstep [] \NC the vertical distance to the previous area \NC \NR
681\NC numeric Hsize [] \NC the width of an area  \NC \NR
682\NC numeric Vsize [] \NC the height of an area \NC \NR
683\HL
684\stoptabulate
685
686The array variables are accessed by using constants:
687
688\starttabulate[|l|l|]
689\HL
690\NC horizontal           \NC vertical        \NC \NR
691\HL
692\NC LeftEdge             \NC Top             \NC \NR
693\NC LeftEdgeSeparator    \NC TopSeparator    \NC \NR
694\NC LeftMargin           \NC Header          \NC \NR
695\NC LeftMarginSeparator  \NC HeaderSeparator \NC \NR
696\NC Text                 \NC Text            \NC \NR
697\NC RightMarginSeparator \NC FooterSeparator \NC \NR
698\NC RightMargin          \NC Footer          \NC \NR
699\NC RightEdgeSeparator   \NC BottomSeparator \NC \NR
700\NC RightEdge            \NC Bottom          \NC \NR
701\HL
702\stoptabulate
703
704In addition to these, there are \type {Margin}, \type {InnerMargin} and \type
705{OuterMargin} which adapt themselves to the current odd or even page. The same is
706true for \type {Edge}, \type {InnerEdge} and \type {OuterEdge}, although these
707will seldom be used, since interactive documents are always single sided.
708
709We started this chapter with spending a lot of code to simulate the page areas.
710It will be clear now that in practice this is much easier using the mechanism
711described here.
712
713\placefigure
714  [here][fig:back 5]
715  {A quick way to draw all used areas.}
716  {\setupexternalfigures[background=color,backgroundcolor=white]%
717   \startcombination
718     {\typesetfile[mfun-900.tex][page=10,width=.4\textwidth]}{even}
719     {\typesetfile[mfun-900.tex][page=11,width=.4\textwidth]}{odd}
720   \stopcombination}
721
722In \in {figure} [fig:back 5] we see all used areas. Areas that are not used are
723not drawn (which saves some testing). This background was defined as:
724
725\typebuffer[back-5]
726
727We use two nested \type {for} loops to step over the areas. A \type {for} loop
728with a step of~1 will fail, because the indices are defined in a rather special
729way. On the other hand, the mechanism is rather tolerant, in the sense that \type
730{[i][j]} and \type {[j][i]} are both accepted.
731
732\stopsection
733
734\startsection[title={Bleeding}]
735
736\index {bleeding}
737
738If you want to share your document all over the world, it makes sense to use a
739paper format like {\em letter} or {\em A4}. In that case, the layout often
740matches the paper size.
741
742\startlinecorrection[blank]
743\startMPcode
744  path p ; p := fullcircle xyscaled (21mm,29.7mm) ;
745  path q ; q := boundingbox p ;
746  fill q withcolor .625white ;
747  fill p withcolor .625yellow ;
748  currentpicture := currentpicture shifted (-31mm,0) ;
749  fill q withcolor .625white ;
750  fill p xsized (bbwidth(p)-2mm) withcolor .625yellow ;
751  currentpicture := currentpicture shifted (-31mm,0) ;
752  fill q withcolor .625white ;
753  fill p withcolor .625yellow ;
754  draw q enlarged -1mm withpen pencircle scaled 2mm withcolor .625white ;
755\stopMPcode
756\stoplinecorrection
757
758The left picture demonstrates what happens when you have a printer that is
759capable of printing from edge to edge. If you have such a printer, you're lucky.
760The middle picture demonstrates what happens if you have a properly set up
761printing program and|/|or printer: the page is scaled down so that the content
762fits into the non printable area of the printer. One reason why printers don't
763print from edge to edge is that the engine is not that happy when toner or ink
764ends up next to the page. The third picture shows what happens when a printer
765simply ignores content that runs over the non printable area. In many cases it's
766best to make sure that the content leaves a margin of 5mm from the edges.
767
768Books and magazines seldom use the popular desk||top paper sizes. Here the
769designer determined the paper size and layout more or less independent from the
770size of the sheet on which the result is printed. Instead of one page per sheet,
771arrangements of 2 upto 32 or more pages per sheet are made. The process of
772arranging pages in such a way that these sheets can be folded and combined into
773books is called page imposition. \CONTEXT\ supports a wide range of page
774imposition schemes. More information on this can be found in the \CONTEXT\
775manuals.
776
777The fact that the sheet on which a page is printed is larger than the page itself
778opens the possibility to use the full page for content. In that case, especially
779when you use background graphics, you need to make sure that indeed the page is
780covered completely. Where in desk top printing you can get away with imperfection
781simply because the printing engines have their limitations, in professional
782output you need to be more considerate.
783
784\startlinecorrection[blank]
785\startMPcode
786  path p ; p := fullsquare xyscaled (4cm,5cm) ;
787  path q ; q := fullsquare xyscaled (3cm,4cm) ;
788  path r ; r := fullsquare xyscaled (2cm,3cm) shifted (-.5cm,.5cm) ;
789  fill p withcolor .625white ;
790  fill q withcolor .850white ;
791  currentpicture := currentpicture shifted (-45mm,0) ;
792  fill p withcolor .625white ;
793  fill q withcolor .850white ;
794  fill r withcolor transparent(1,.5,.625yellow) ;
795  currentpicture := currentpicture shifted (-45mm,0) ;
796  fill p withcolor .625white ;
797  fill q withcolor .850white ;
798  r := r topenlarged 2mm leftenlarged 2mm ;
799  fill r withcolor transparent(1,.5,.625yellow) ;
800\stopMPcode
801\stoplinecorrection
802
803Slightly enlarging a graphic so that it exceeds the natural page limits is called
804bleeding. Because quite often layout elements have a rectangular nature,
805\METAFUN\ provides a couple of operations that can save you some work in defining
806bleeding boxes.
807
808\startbuffer
809path p, q ;
810def ShowPath =
811  fill p withcolor transparent(1,.5,.625yellow) ;
812  fill q withcolor transparent(1,.5,.625yellow) ;
813  currentpicture := currentpicture shifted (-25mm,0) ;
814enddef ;
815p := q := fullsquare xyscaled (2cm,3cm) ; ShowPath ;
816p := p leftenlarged   2mm ; ShowPath ;
817p := p topenlarged    2mm ; ShowPath ;
818p := p rightenlarged  2mm ; ShowPath ;
819p := p bottomenlarged 2mm ; ShowPath ;
820\stopbuffer
821
822\startlinecorrection[blank]
823\processMPbuffer
824\stoplinecorrection
825
826This graphic is generated as follows:
827
828\typebuffer
829
830The trick is in the last couple of lines. In addition to the general \type
831{enlarged} operator, we have 4~operators that enlarge a rectangle in a certain
832direction. This means that we can define the original path using dimensions
833related to the layout, and add bleed strips independently.
834
835\startbuffer
836path p ; p := fullsquare xyscaled (4cm,1cm) ;
837path q ; q := p leftenlarged 2mm topenlarged 2mm ;
838fill p withcolor transparent(1,.5,.625yellow) ;
839fill q withcolor transparent(1,.5,.625yellow) ;
840draw boundingbox currentpicture withcolor .625red ;
841\stopbuffer
842
843\typebuffer
844
845\startlinecorrection[blank]
846\processMPbuffer
847\stoplinecorrection
848
849This example demonstrates that when we enlarge a graphic, the bounding box also
850gets larger. Because this can interfere with the placement of such a graphic, we
851need to make sure that the bleeding is there but not seen.
852
853\startbuffer
854path p ; p := fullsquare xyscaled (4cm,1cm) ;
855path q ; q := p leftenlarged 2mm topenlarged 2mm ;
856fill p withcolor transparent(1,.5,.625yellow) ;
857fill q withcolor transparent(1,.5,.625yellow) ;
858setbounds currentpicture to p ;
859draw boundingbox currentpicture withcolor .625red ;
860\stopbuffer
861
862\typebuffer
863
864\startlinecorrection[blank]
865\processMPbuffer
866\stoplinecorrection
867
868There are two more operators: \type {innerenlarged} and \type {outerenlarged}.
869These expand to either \type {leftenlarged} or \type {rightenlarged}, depending
870on the page being left or right hand.
871
872\stopsection
873
874\stopchapter
875
876\stopcomponent
877