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

\startcomponent text-107

\prependtoks
  \ifdim\pagetotal>\lineheight\else
    \ifindentfirstparagraph\else\noindentation\fi
  \fi
\to \everypar

\environment text-000

\chapter {Ornaments everywhere}

The background mechanisms present in \CONTEXT\ have evolved
over time and with computers becoming faster, you can expect
new functionality to show up and existing functionality to
start using this technology. A simple background consist of
a colored area. Many commands accept settings like:

\starttyping
...[background=color,backgroundcolor=red,backgroundoffset=3pt]
\stoptyping

Instead of such an area you can define one or more so called
overlays:

\starttyping
\defineoverlay[one][...]
\defineoverlay[two][...]

...[background={one,two}]
\stoptyping

The name overlay comes from the fact that you stack them on
top of each other. A special overlay is \type {foreground},
and deep down in \CONTEXT\ there are more predefined
overlays.

In the \METAFUN\ manual you will find example of usage, so
here we stick to a simple code snippet for testing this
functionality:

\startbuffer
\defineoverlay[one][\green A]
\defineoverlay[two][\red   B]

\framed[background=one]       {1}
\framed[background={one,two}] {1---2}
\stopbuffer

\typebuffer

The rather ugly result is:

\startlinecorrection
\hbox{\getbuffer}
\stoplinecorrection

You can construct overlays by using \TEX\ boxing primitives
or commands like \type {\framed}. Alternatively you can use
another mechanism: layers. Layers collect content and flush
that when asked, for instance when an overlay is
constructed. Layers can be independent of a page, or bound
to a specific page number, left or right hand pages. Here
we look at independent layers.

All these mechanisms are fine tuned for cooperating with
the output routine (the part of \TEX\ that deals with
composing pages) and are well interact quite well with
\METAPOST\ graphics. Details of usage and tricks are
revealed in this manual as well as in styles that come with
\CONTEXT. In this chapter we will apply layers to graphics.
For this we need a few setups, like:

\starttyping
\setupbackgrounds
  [page]
  [background=pagegraphics]
\stoptyping

Here we have set up the page background to use an overlay
called \type {pagegraphics}. However, instead of an
overlay, we will use a layer. This layer will collect
content that goes into the page background. Whenever a
layer is defined, an overlay is automatically defined as
well.

\startbuffer
\definelayer
  [pagegraphics]
  [x=-2mm,
   y=-2mm,
   width=\paperwidth,
   height=\paperheight]
\stopbuffer

\typebuffer \getbuffer

When you fill a layer with content, you can influence the
placement with the \type {x} and \type {y} parameters as
well as \type {hoffset} and \type {voffset}, whichever you
prefer. The reference point and alignment are set with \type
{corner} and \type {location}.

Live can be made easier by using presets, especially for our
intended usage. The following presets are predefined.

\startbuffer
\definelayerpreset
  [lefttop] [corner={left,top},location={right,bottom}]
\definelayerpreset
  [righttop] [corner={right,top},location={left,bottom}]
\definelayerpreset
  [leftbottom] [corner={left,bottom},location={right,top}]
\definelayerpreset
  [rightbottom] [corner={right,bottom},location={left,top}]
\stopbuffer

\typebuffer \getbuffer

Because for this layer we have also preset the \type {x}
and \type {y}, those corners are laying a few millimeters
outside the page area. We have preset the size as well,
otherwise all corners would end up in the top left corner.

We will now fill this layer. Because the layer is hooked
into the page, it will be flushed when the page is
constructed. After the page is written to the output file,
the layer is emptied, unless its \type {state} is set to
\type {repeat}.

\startbuffer
\setlayer [extras] [preset=lefttop]     {\externalfigure[hacker]}
\setlayer [extras] [preset=righttop]    {\externalfigure[hacker]}
\setlayer [extras] [preset=leftbottom]  {\externalfigure[hacker]}
\setlayer [extras] [preset=rightbottom] {\externalfigure[hacker]}
\stopbuffer

\testpage[5] \typebuffer \getbuffer

Once you got the picture of layering, you will start using
this mechanism for all kind of tasks. Instead of putting
layers in a background, you can also directly place them, by
using one of the two (equivalent) commands:

\starttyping
\composedlayer{identifier}
\placelayer[identifier]
\stoptyping

Layer are quite convenient for defining title pages,
colofons, and special section heads, especially in
combination with \type {\framed}.

On top of the layer mechanism we have build a few more
mechanisms, like ornaments. You can use ornaments to
annotate graphics in such a way that the dimensions stay
unchanged.

\startbuffer
\defineornament
  [affiliation]
  [rotation=90,corner={right,bottom},location={right,top},
   hoffset=-.25ex]
  [frame=on,background=color,backgroundcolor=red,offset=0pt]
\stopbuffer

\typebuffer \getbuffer

The negative offset will overlay the text outside the
graphic. The meaning of the sign of coordinates and offsets
depends on the corner. \in {Figure} [fig:affi-1] shows the
result. We have put the reference point in the right bottom
corner. The ornament is anchored at the right top corner of
the dot you can picture at the reference point. The
ornament is shifted .25ex outwards.

\starttyping
\placefigure
  {}
  {\affiliation{graphic}{\externalfigure[hacker][width=3cm]}}
\stoptyping

\placefigure
  [here] [fig:affi-1] {Number 1}
  {\affiliation{graphic}{\externalfigure[hacker][width=3cm]}}

There are two ways to handle the placement. Alternative
\type {a} will change the dimensions of the graphic
according to the size of the ornament, while alternative
\type {b} acts as a pure overlay. In \in {figure}
[fig:affi-2] the ornament is not taken into account when
calculating the dimensions of the graphic. This is often
the prefered placement, because this way the (often small)
ornament will not it will not spoil visual alignment of
similar graphics.

\startbuffer
\defineornament
  [affiliation]
  [rotation=90,corner={right,bottom},location={right,top},
   hoffset=-.25ex,alternative=b]
  [frame=on,background=color,backgroundcolor=red,offset=0pt]
\stopbuffer

\typebuffer \getbuffer

\placefigure
  [here] [fig:affi-2] {Number 2}
  {\affiliation{graphic}{\externalfigure[hacker][width=3cm]}}

A positive offset will place the ornament on top of the
graphic (see \in {figure} [fig:affi-3]).

\startbuffer
\defineornament
  [affiliation]
  [rotation=90,corner={right,bottom},location={left,top},
   hoffset=.25ex,voffset=.25ex,alternative=a]
  [background=color,style=\ss\tfxx,backgroundcolor=white,offset=0pt]
\stopbuffer

\typebuffer \getbuffer

\placefigure
  [here] [fig:affi-3] {Number 3}
  {\affiliation{graphic}{\externalfigure[hacker][width=3cm]}}

You need to play a bit with this mechanism in order to get a
feeling for what the parameters do.

\startbuffer
\defineornament
  [affiliation]
  [rotation=90,corner={right,bottom},location={left,top},
   hoffset=.25ex,voffset=.25ex,alternative=b]
  [background=color,style=\ss\tfxx,backgroundcolor=white,offset=0pt]
\stopbuffer

\typebuffer \getbuffer

\placefigure
  [here] [fig:affi-4] {Number 4}
  {\affiliation{graphic}{\externalfigure[hacker][width=3cm]}}

Because the text is normally typeset quite small, you'd
better use a font that can be scaled down a lot.

\startbuffer
\definefont[AffiliationFont][Sans sa .25]

\defineornament
  [SomeAffiliation]
  [rotation=90,corner={right,bottom},location={right,top},
   hoffset=-.125ex,alternative=b]
  [style=AffiliationFont,offset=0pt]
\stopbuffer

\typebuffer \getbuffer

This affiliation is used as:

\startbuffer
\placefigure
  {Affiliations normally are typeset pretty small.}
  {\SomeAffiliation
     {author: Hester De Weert}
     {\externalfigure[hacker]}}
\stopbuffer

\typebuffer \getbuffer

Ornaments are implemented in terms of layers and collectors.
A few examples demonstrate how these can be used.

\startbuffer
\layeredtext
  [corner={right,bottom},location={left,top}]
  [background=color,backgroundcolor=white,offset=0pt]
  {graphic}
  {\externalfigure[hacker][width=3cm]}
\stopbuffer

\typebuffer \startlinecorrection \getbuffer \stoplinecorrection

\startbuffer
\layeredtext
  [rotation=90,corner={right,bottom},location={right,top}]
  [frame=on,offset=0pt]
  {graphic}
  {\externalfigure[hacker][width=3cm]}
\stopbuffer

\typebuffer \startlinecorrection \getbuffer \stoplinecorrection

\startbuffer
\layeredtext
  [rotation=90,corner={left,bottom},location={left,top}]
  [frame=on,offset=0pt]
  {graphic}
  {\externalfigure[hacker][width=3cm]}
\stopbuffer

\typebuffer \startlinecorrection \getbuffer \stoplinecorrection

\startbuffer
\collectedtext
  [corner={right,bottom},location={left,top}]
  [background=color,backgroundcolor=white,offset=0pt]
  {graphic}
  {\externalfigure[hacker][width=3cm]}
\stopbuffer

\typebuffer \startlinecorrection \getbuffer \stoplinecorrection

\startbuffer
\collectedtext
  [rotation=90,corner={right,bottom},location={right,top}]
  [frame=on,offset=0pt]
  {graphic}
  {\externalfigure[hacker][width=3cm]}
\stopbuffer

\typebuffer \startlinecorrection \getbuffer \stoplinecorrection

\startbuffer
\collectedtext
  [rotation=90,corner={left,bottom},location={left,top}]
  [frame=on,offset=0pt]
  {graphic}
  {\externalfigure[hacker][width=3cm]}
\stopbuffer

\typebuffer \startlinecorrection \getbuffer \stoplinecorrection

There are several methods to construct titlepages, headers,
and other compositions. Of course there are the low level
box constructors like \type {\hbox}, \type {\vbox} and
positioners like \type {\hskip}, \type {\hfill} and alike.

Another option is to fall back on the low level box macros
in the \CONTEXT\ support file \type {supp-box} or the higher
level \type {\framed} macro. You can use \type {\framed}
nested and by cleverly using the offsets and dimensions you
can do a lot.

Layers are another means. You can or instance construct a
title page in the following way:

\starttyping
\definelayer
  [titlepage]
  [width=\textwidth,
   height=\textheight]

\setlayer
  [titlepage]
  [preset=righttop,location={left,bottom},y=1cm,x=1cm]
  {\definedfont[Regular at 60pt]Welcome}

\setlayer
  [titlepage]
  [preset=rightbottom,location={right,top},y=2cm,x=2cm]
  {\definedfont[Regular at 30pt]By Me}
\stoptyping

This just fills the layer. Placement is done with:

\starttyping
\startstandardmakeup
  \flushlayer[titlepage]
\stopstandardmakeup
\stoptyping

or alternatively:

\starttyping
\setupbackgrounds[text][background=titlepage]
\startstandardmakeup \stopstandardmakeup
\setupbackgrounds[text][background=]
\stoptyping

Another way to collect content is to use a collector. A
collector starts out empty with:

\startbuffer
\definecollector[test][state=repeat]
\stopbuffer

\typebuffer \getbuffer

We can now stepwise fill this collector. For educational
purposes we've turn of tracing so that you can see what the
anchor points.

\startbuffer
\setcollector[test]
  [location={right,bottom}]
  {\externalfigure[detcow][frame=on,width=3cm]}
\stopbuffer

\typebuffer {\traceboxplacementtrue \getbuffer}

\startlinecorrection[blank] \flushcollector[test] \stoplinecorrection

\startbuffer
\setcollector[test]
  [corner={right,bottom},location={left,top}]
  {\framed[background=color,backgroundcolor=tyellow]{this is a cow}}
\stopbuffer

\typebuffer {\traceboxplacementtrue \getbuffer}

\startlinecorrection[blank] \flushcollector[test] \stoplinecorrection

\startbuffer
\setcollector[test]
  [corner={right,bottom},location={right,bottom}]
  {\framed[background=color,backgroundcolor=tblue]{that's for sure}}
\stopbuffer

\typebuffer {\traceboxplacementtrue \getbuffer}

\startlinecorrection[blank] \flushcollector[test] \stoplinecorrection

\startbuffer
\setcollector[test]
  [corner={left,top},location={left,top}]
  {\framed[background=color,backgroundcolor=tgreen]{a dutch cow}}
\stopbuffer

\typebuffer {\traceboxplacementtrue \getbuffer}

\startlinecorrection[blank] \flushcollector[test] \stoplinecorrection

\startbuffer
\setcollector[test]
  [corner=middle,
   location=middle]
  {\framed[background=color,backgroundcolor=tred]{nearly done}}
\stopbuffer

\typebuffer {\traceboxplacementtrue \getbuffer}

\startlinecorrection[blank] \flushcollector[test] \stoplinecorrection

In addition to the parameters shown here, you can also
provide additional ones: \type {x}, \type {y}, \type
{offset}, \type {hoffset} and \type {voffset} for
positioning and \type {rotation} for (as expected) rotating
the content in steps of 90 degrees. As with layers, the
coordinates and offsets can be used intermixed.

\startbuffer
\setcollector[test]
  [hoffset=4cm,
   voffset=-1cm,
   corner=middle,
   location=middle]
  {\framed{now}}
\stopbuffer

\typebuffer {\traceboxplacementtrue \getbuffer}

\startlinecorrection[blank] \flushcollector[test] \stoplinecorrection

We can show the intermediate results because we have set
the state of this collector to repeat. In this case you
need to erase the content manually, using:

\startbuffer
\resetcollector[test]
\stopbuffer

\typebuffer \getbuffer

The chapter titles of this document are (as usual in a
\CONTEXT\ document) typeset by the \type {\chapter} macro.
When thinking about implementing a non standard head, those
familiar with \CONTEXT's head macros will probably first
think of using one of the hooks, like:

\starttyping
\setuphead[chapter][command=\MyChapterHead]
\stoptyping

Here we have followed a different approach. First we set up
the chapter head. The \type {empty} directive instructs
\CONTEXT\ not to place the head itself, but still to include
the associated data in the text stream. This means that we
will not see a chapter title, but that there will be an
entry in the table of contents, that references will be set
up, that so called marks will be available, etc.

\starttyping
\setuphead
  [chapter]
  [placehead=empty,
   header=chapter,
   style=\BigText,
   numberstyle=\BigNumber]
\stoptyping

The \type {header} parameters instructs the head handler to
mark this page as special with regards to header texts. This
text is set up as follows:

\starttyping
\definetext
  [chapter]
  [header]
  [\setups{chapter}]
  []
\stoptyping

The setups are just series of typesetting instructions. For
the sake of readability, we have split them up.

\starttyping
\startsetups chapter
  \setups[chapter:title]
  \setups[chapter:number]
  \setups[chapter:finish]
\stopsetups
\stoptyping

The setups will use a dedicated layer for the chapter title:

\starttyping
\definelayer
  [chapter]
  [width=\dimexpr\makeupwidth+\cutspace\relax,
   height=\headerheight]
\stoptyping

The following code uses a macro \type {\setlayerframed}.
This is a combination between \type {\setlayer} and \type
{\framed}. We use two placement macros to typeset the title
and number. When doing so, we need to take care of both
numbered chapters and unnumbered titles.

\starttyping
\startsetups chapter:title

  \setlayerframed
    [chapter]
    [x=\dimexpr\makeupwidth+\cutspace\relax,location={left,bottom}]
    [height=\headerheight,
     foregroundcolor=white,
     background=color,
     backgroundcolor=blue,
     frame=off,
     offset=none,
     align={right,lohi}]
    {\hbox spread .5\cutspace
       {\hss
        \doiftextelse{\placeheadtext[chapter]}%
          {\placeheadtext[chapter]}%
          {\placeheadtext[title]}%
        \hss}\space
     \vskip.5cm}

\stopsetups
\stoptyping

Definitions like these may look complicated but in practice
you will construct them piecewise.

\starttyping
\startsetups chapter:number

  \setlayerframed
    [chapter]
    [x=\dimexpr\makeupwidth+\cutspace\relax,
     y=\vsize,
     location={left,bottom}]
    [width=\dimexpr\cutspace-\rightmargindistance\relax,
     height=\dimexpr\cutspace-\rightmargindistance\relax,
     foregroundcolor=white,
     background=color,
     backgroundcolor=red,
     frame=off,
     offset=none,
     align={middle,lohi}]
    {\hbox to \hsize
       {\hskip.5cm\hss
        \doifmode{*bodypart}{\placeheadnumber[chapter]}%
        \hss}}

\stopsetups
\stoptyping

The finishing touch is just a dummy frame with the chapter
background. We could have used the headertext background
instead.

\starttyping
\startsetups chapter:finish

  \framed
    [width=\makeupwidth,
     height=\headerheight,
     background=chapter,
     frame=off]
    {}

\stopsetups
\stoptyping

As the title of this manual suggests: it's in the details.
Most of our time is spent in optimizing spacing issues. If
you're designing the layout yourself, for a large part you
can fall back on the consistent spacing provided by \TEX,
i.e.\ think in terms of \type {em}'s, \type {ex}'s and
fractions or multiples of \type {\bodyfontsize}, as well as
base you're dimensions on those provided by the layout. When
dealing with translating a \DTP\ layout into something \TEX,
definitions like the above will often look more messy.

\stopcomponent
