% language=us

\environment details-environment

\startcomponent details-floatingaround

\startchapter[title={Floating around}]

\index {floats}

Graphics, tables and alike are often treated as floating bodies. This means that
when such a body does not fit on the current page, it will be moved to the next
one. In the examples we will use figures, but much of what we demonstrate here
applies to all floats.

A side float is a float which placement one way or another depends on the text
that follows it. In its simplest form, the text flows around it, for instance in:

\startbuffer
\placefigure[left,none]{caption}{\framed[height=1cm]{graphic}}
\stopbuffer

\typebuffer

The first keyword of such a call is treated as a placement directive, so this
figure will be placed left. The \type {none} directive nils the caption.

\getbuffer \fakewords{60}{80}

When the figure does not fit on the page, a page break is issued. A figure can
span multiple paragraphs. When a next graphic is placed the previous figure will
be padded if needed. First an example of multiple paragraphs.

\getbuffer \fakewords{30}{40} \par \fakewords{30}{40}

Multiple floats in a row will lead to padding. The amount of padding is a
combination of empty lines and the normal white space following the float. The
visual quality of the result depends on the graphic itself.

\start \tracesidefloatstrue

\getbuffer \fakewords{30}{40}

\getbuffer \fakewords{30}{40} \fakewords{30}{40}

\stop

Here we show the baseline of the first paragraph after the float as well as the
filler. The whitespace around a graphic also depends on the inter|-|paragraph
whitespace. As with many automated mechanisms, compromises are made. A one point
smaller figure may result in an extra empty line.

Later we will demonstrate a lot of tuning options, but first we give a few more
examples. Most of the tuning options can be driven by keywords as well as
(global) settings.

\startbuffer
\placefigure
  [left,nonumber]
  {caption} {\framed[height=1cm]{graphic}}
\stopbuffer

\typebuffer

The \type {nonumber} keyword suppresses the label and figure number. You can do
this for all figures with

\starttyping
\setupcaption[figure][number=no]
\stoptyping

The previous placement command results in the following side float.

\getbuffer \fakewords{80}{100}

Another handy keyword is \type {none}.

\startbuffer
\placefigure
  [left,none]{quoting knuth}
  {\framed[height=1cm]{graphic}}
\stopbuffer

\typebuffer \getbuffer \fakewords{80}{100}

Control over spacing is exercised by means of the keywords \type {high}, \type
{low} and \type {fit}.

\startbuffer
\placefigure
  [left,none,high]{}
  {\framed[height=1cm]{graphic}}
\stopbuffer

\typebuffer \getbuffer \fakewords{80}{100}

\startbuffer
\placefigure
  [left,none,high,low]{}
  {\framed[height=1cm]{graphic}}
\stopbuffer

\typebuffer \getbuffer \fakewords{80}{100}

\startbuffer
\placefigure
  [left,none,fit]{}
  {\framed[height=1cm]{graphic}}
\stopbuffer

\typebuffer \getbuffer \fakewords{80}{100}

In the examples so far, we saw additional spacing around the graphic. We will now
(for a while) disable the surrounding whitespace.

\startbuffer
\setupfloat
  [figure]
  [sidespacebefore=none,
   sidespaceafter=none]
\stopbuffer

\typebuffer

With these settings a simple left placement looks as follows. The top of the side
float aligns with the maximum height of a line.

\start \getbuffer \tracesidefloatstrue

\startbuffer
\placefigure
  [left,none]
  {} {\framed[height=1cm]{graphic}}
\stopbuffer

\typebuffer \getbuffer \fakewords{30}{40} \par \stop

You can change the alignment by setting the \type {sidealign} variable, for
instance:

\starttyping
\setupfloat
  [figure]
  [sidealign=line]
\stoptyping

The three keywords \type {height}, \type {line} and \type {depth} can also be
passed directly:

\startbuffer
\placefigure
  [left,none,height]{}
  {\framed[height=1cm]{graphic}}
\stopbuffer

\typebuffer

The three alignments disable the spacing before the float and show up as follows.

\bgroup \tracesidefloatstrue \getbuffer \fakewords{30}{40} \par \egroup

\startbuffer
\placefigure
  [left,none,line]{}
  {\framed[height=1cm]{graphic}}
\stopbuffer

\bgroup \tracesidefloatstrue \getbuffer \fakewords{30}{40} \par \egroup

\startbuffer
\placefigure
  [left,none,depth]{}
  {\framed[height=1cm]{graphic}}
\stopbuffer

\bgroup \tracesidefloatstrue \getbuffer \fakewords{30}{40} \par \egroup

So far the floats took up space in the main text body area. In addition to the
\type {left} (or \type {right}) directive we can use \type {inner} or \type
{outer} to force left or right placement depending in the spread.

Instead of spoiling paper in the text areas, we can use the margin and edges:
\type {leftmargin} and \type {leftedge}, \type {rightmargin} and \type
{rightedge}, but also \type {innermargin} and \type {outermargin}, \type
{inneredge} and \type {outeredge}.

The next couple of pages we will highlight the margins and edges so that we can
see what happens.

\setupbackgrounds [text] [leftedge]    [background=color]
\setupbackgrounds [text] [rightedge]   [background=color]
\setupbackgrounds [text] [leftmargin]  [background=color]
\setupbackgrounds [text] [rightmargin] [background=color]

\startbuffer
\placefigure
  [leftmargin,none]
  {} {\framed{!}}
\stopbuffer

\typebuffer \getbuffer \fakewords{30}{40}

\startbuffer
\placefigure
  [leftmargin,none]
  {} {\framed[width=1cm]{!}}
\stopbuffer

\typebuffer \getbuffer \fakewords{30}{40}

\startbuffer
\placefigure
  [leftmargin,none]
  {} {\framed[width=1.5cm]{!}}
\stopbuffer

\typebuffer \getbuffer \fakewords{30}{40}

The placement directives can be combined with setting distance and width
parameters, thereby not only opening a world of possibilities, but also creating
confusion. Therefore, we will illustrate these features by cloning floats.

\startbuffer
\definefloat
  [marginfigure]
  [figure]

\setupfloat
  [marginfigure]
  [leftmargindistance=-\leftmargintotal,
   default={left,none,low}]
\stopbuffer

\typebuffer \getbuffer

The definition command clones figure into a new class of figures. There are two
ways to use such a float :

\starttyping
\placefloat
  [marginfigure]
  {} {\framed[width=1.5cm]{!}}
\stoptyping

or directly:

\startbuffer
\placemarginfigure
  {} {\framed[width=1.5cm]{!}}
\stopbuffer

\typebuffer

Both placement calls will result in a figure sticking into the margin.

\getbuffer \fakewords{30}{40}

By manipulating the margin distance, you can align graphics to vertical grid
lines, like the edge:

\startbuffer
\definefloat
  [edgefigure]
  [figure]

\setupfloat
  [edgefigure]
  [leftmargindistance=-\innercombitotal,
   default={left,none,low,high}]
\stopbuffer

\typebuffer \getbuffer

The \type {\innercombitotal} is one of the many available dimensions. This
measure is the combined width of the margin and edge.

\startbuffer
\placeedgefigure
  {} {\framed[width=1.5cm]{!}}
\stopbuffer

\typebuffer \getbuffer \fakewords{30}{40}

\startbuffer
\placeedgefigure
  {} {\framed[width=\innercombitotal]{!}}
\stopbuffer

\typebuffer \getbuffer \fakewords{30}{40}

You need to be aware of the fact that the margins and edges are not related to
the backspace and cut space settings. When you set up a layout, you need to think
of the right page as starting point. In a double sided layout, the margins are
swapped in the page composition stage. Unless you explicitly go to a left or
right page, you don't know if your left margin will be swapped or not.

For this reason \CONTEXT\ provides the inner and outer margin|/|edge dimensions.
These are automatically synchronized when the float is constructed. So, if you
want to automatically adapt the float placement and width to the current left
margin in a double sided document, you can use the inner dimensions.

\starttabulate[||||]
\NC dimension                  \NC left page
                               \NC right page                 \NC\NR
\NC \type{\outermarginwidth}   \NC \type{\leftmarginwidth}
                               \NC \type{\rightmarginwidth}   \NC\NR
\NC \type{\innermarginwidth}   \NC \type{\rightmarginwidth}
                               \NC \type{\leftmarginwidth}    \NC\NR
\NC \type{\outermargindistance}\NC \type{\leftmargindistance}
                               \NC \type{\rightmargindistance}\NC\NR
\NC \type{\innermargindistance}\NC \type{\rightmargindistance}
                               \NC \type{\leftmargindistance} \NC\NR
\stoptabulate

Similar dimensions are available for the edges. You can save yourself some
calculations by using the following dimensions:

\starttabulate[|||||]
\NC \type{\leftmargintotal}  \NC left  margin width \NC + \NC left  margin distance \NC\NR
\NC \type{\rightmargintotal} \NC right margin width \NC + \NC right margin distance \NC\NR
\NC \type{\innermargintotal} \NC inner margin width \NC + \NC inner margin distance \NC\NR
\NC \type{\outermargintotal} \NC outer margin width \NC + \NC outer margin distance \NC\NR
\stoptabulate

As you may expect, the edge totals are available as well, which leave a few more
totals, namely the combinations of margin and edge.

\starttabulate[|||]
\NC \type{\leftsidetotal}   \NC left  margin width \NC + \NC left  edge total \NC\NR
\NC \type{\rightsidetotal}  \NC right margin width \NC + \NC right edge total \NC\NR
\TB
\NC \type{\innersidetotal}  \NC inner margin width \NC + \NC inner edge total \NC\NR
\NC \type{\outersidetotal}  \NC outer margin width \NC + \NC outer edge total \NC\NR
\TB
\NC \type{\leftcombitotal}  \NC left  margin total \NC + \NC left  edge total \NC\NR
\NC \type{\rightcombitotal} \NC right margin total \NC + \NC right edge total \NC\NR
\TB
\NC \type{\innercombitotal} \NC inner margin total \NC + \NC inner edge total \NC\NR
\NC \type{\outercombitotal} \NC outer margin total \NC + \NC outer edge total \NC\NR
\stoptabulate

Adaptive back- and cutspace dimensions are also available:

\starttabulate[|||||]
\NC \type{\innerspacewidth} \NC adaptive backspace \NC\NR
\NC \type{\outerspacewidth} \NC adaptive cutspace  \NC\NR
\stoptabulate

There is one drawback in using the inner and outer dimensions: if you also change
the height of the float dynamically, you may end up in a kind of loop because a
page break may occur at a non||expected place.

While negative values move float into the margin, positive values will move the
float into the text. It will be of no surprise that you can also set the right
margin distance. Keep in mind that this distance is not related to the text
margin, but to the float margin.

\startbuffer
\setupfloat
  [edgefigure]
  [leftmargindistance=-\outercombitotal,
   rightmargindistance=-\outercombitotal,
   default={outer,none,low,high}]
\stopbuffer

\typebuffer \getbuffer

The locations \type {inner} and \type {outer} change with the left or right page.

\startbuffer
\placeedgefigure
  {} {\framed[width=\outercombitotal]{!}}
\stopbuffer

\typebuffer \getbuffer \fakewords{30}{40}

\startbuffer
\placeedgefigure
  {} {\framed[width=8cm]{!}}
\stopbuffer

\typebuffer \getbuffer \fakewords{30}{40}

As a result of manipulating the floats margin settings, the side floats can start
in the margin (or edge). You should not confuse this with margin floats, i.e.\
side floats that are explicitly placed in the margins.

\startbuffer
\placefigure[leftmargin,none]
  {} {\framed{!}}
\stopbuffer

\typebuffer \getbuffer \fakewords{30}{40}

\startbuffer
\placefigure[leftmargin,none]
  {} {\framed[width=.5cm]{!}}
\stopbuffer

\typebuffer \getbuffer \fakewords{30}{40}

\startbuffer
\placefigure[leftmargin,none]
  {} {\framed[width=1.5cm]{!}}
\stopbuffer

\typebuffer \getbuffer \fakewords{30}{40}

\startbuffer
\placefigure[leftmargin,none]
  {} {\framed[width=5cm]{!}}
\stopbuffer

\typebuffer \getbuffer \fakewords{30}{40}

The margin side floats align to the margin and the edge floats to the edge. This
way you can create bleeding figures.

\startbuffer
\placefigure[leftedge,none]
  {} {\framed{!}}
\stopbuffer

\typebuffer \getbuffer \fakewords{30}{40}

There are situations where you don't know the dimensions in advance. In order to
prevent unwanted side effects, for instance part of a graphic disappearing
outside the page boundary, \CONTEXT\ provides a few options. The most crude one
is setting the \type {criterium}, as in:

\starttyping
\setupfloat
  [figure]
  [criterium=.25\textwidth]
\stoptyping

This will automatically turn figures that are wider than 25\% of the text width
into normal floats instead of side floats. But let's not fall back on that
feature now.

You can use \type {maxwidth} and \type {minwidth} variables to control the
placement in more detail. The exact result depends on the settings of \type
{location}. By default we center, but you can set the location to \type {left} or
\type {right} to achieve a different alignment.

\startbuffer
\definefloat
  [midmarginfigure]
  [figure]

\setupfloat
  [midmarginfigure]
  [minwidth=\leftmarginwidth,
   default={leftmargin,none}]
\stopbuffer

\typebuffer \getbuffer

You can use \type {maxwidth} and \type {minwidth} variables to control the
placement in more detail. The exact result depends on the settings of \type
{location}. By default we center, but you can set the location to \type {left} or
\type {right} to achieve a different alignment.

\startbuffer
\placemidmarginfigure
  {} {\framed[width=1.5cm]{!}}
\stopbuffer

\typebuffer \getbuffer \fakewords{30}{40}

The meaning of \type {maxwidth} depends on the kind of float. First we place a
left float with a width smaller than \type {maxwidth}.

\start

\startbuffer
\setupfloat[figure][maxwidth=2cm]
\stopbuffer

\typebuffer \getbuffer

\startbuffer
\placefigure[left,none]{}{\framed[width=1cm]{!}}
\stopbuffer

\typebuffer \getbuffer \fakewords{30}{40}

When the width exceeds the maxwidth, the float will be centered. This is because
we have no reference alignment point.

\startbuffer
\placefigure[left,none]{}{\framed[width=5cm]{!}}
\stopbuffer

\typebuffer \getbuffer \fakewords{30}{40}

In margin floats, the \type {maxwidth} settings have a different result. First we
place a small graphic.

\startbuffer
\setupfloat[figure][maxwidth=\leftmarginwidth]
\stopbuffer

\typebuffer \getbuffer

\startbuffer
\placefigure[leftmargin,none]{}{\framed[width=1cm]{!}}
\stopbuffer

\typebuffer \getbuffer \fakewords{30}{40}

Because the left and right margin of this document are the same |<|the edges
differ|>| we don't need to use inner and outer dimensions.

\startbuffer
\setupfloat[figure][maxwidth=\leftmarginwidth]
\stopbuffer

\typebuffer \getbuffer

A wider than \type {maxwidth} graphic will behave like a mixture of a margin and
text side float. Watch how we align the float to the margin.

\startbuffer
\placefigure[leftmargin,none]{}{\framed[width=5cm]{!}}
\stopbuffer

\typebuffer \getbuffer \fakewords{30}{40}

\stop

Instead of setting the width you can give \type {hanging} a try. The next
examples demonstrate this.

\startbuffer
\placefigure[leftmargin,hanging,none]{}{\framed[width=5cm]{!}}
\stopbuffer

\typebuffer \getbuffer \fakewords{30}{40}

\startbuffer
\placefigure[left,hanging,none]{}{\framed[width=5cm]{!}}
\stopbuffer

\typebuffer \getbuffer \fakewords{30}{40}

You can move down|/|up margin floats with the \type {\movesidefloat} macro. Such
shifts come in handy when you have multiple side floats near to each other.

\startbuffer
\movesidefloat [+2*line]
\placemidmarginfigure {} {\framed{!}}
\stopbuffer

\typebuffer \getbuffer \fakewords{30}{40}

Given the default placement template, this is equivalent to the following
command. Watch out, a simple \type {line} has a different effect (alignment).

\starttyping
\placemidmarginfigure
  [leftmargin,none,+2*line]
  {} {\framed{!}}
\stoptyping

Another nice keyword is \type {long}:

\startbuffer
\placefigure
  [leftmargin,none,long]
  {} {\framed[height=2cm,width=2cm]{!}}

Watch how we move down. The effect is that we skip over the margin figure.

\placefigure
  [leftmargin,none]
  {} {\framed[height=1cm,width=2cm]{!}}
\stopbuffer

\typebuffer \getbuffer \fakewords{30}{40}

\startbuffer
\placefigure
  [leftmargin,none]
  {} {\framed[height=2cm,width=2cm]{!}}

Do we clash or not?

\placefigure
  [leftmargin,none]
  {} {\framed[height=2cm,width=2cm]{!}}

Did we clash or not?
\stopbuffer

\typebuffer \getbuffer

There are a few macros that can be of help with solving clashes in side floats:

\starttabulate
\NC \tex {flushsidefloats} \NC
    This macro moves down as much as is needed to separate the side floats of
    each other. \NC \NR
\NC \tex {forgetsidefloats} \NC
    this macro kind of forgets that a side float is in progress. \NC \NR
\stoptabulate

Use these macros with care. If you change the dimensions of the graphic and|/|or
content involved, reconsider the use of these directives.

The next couple of spreads we will demonstrate some example definitions. These
placements are taken from one of the styles we made for typesetting a series of
school math books which illustrations and tables all over the pages.

First we fine tune the spacing around side floats and verbatim text.

\startbuffer[setupa]
\setupfloats
  [sidespacebefore=none,
   sidespaceafter=depth]

\setuptyping
  [margin=]
\stopbuffer

\typebuffer[setupa]

The placements have rather verbose names. In this case the word \quote {edge} is
used to identify bleeding floats (with an cut||off margin of 3mm). The \quote
{text} floats are side floats positioned in the main text flow.

\startbuffer[setupb]
\definefloat [marginfigure]       [marginfigures]       [figure]
\definefloat [middlemarginfigure] [middlemarginfigures] [figure]
\definefloat [middlefigure]       [middlefigures]       [figure]
\definefloat [textfigure]         [textfigures]         [figure]
\definefloat [leftfigure]         [leftfigures]         [figure]
\definefloat [rightfigure]        [rightfigures]        [figure]
\definefloat [bleedfigure]        [bleedfigures]        [figure]
\stopbuffer

\typebuffer[setupa]

Watch how we define fall backs for too wide content (\type
{criterium} as well as use \type {maxwidth} to manipulate
the placement of content that falls off the margins.

The black rules are set up with:

\startbuffer[setupc]
\setupblackrules[color=tred,depth=0pt,height=1.5cm]
\stopbuffer

\typebuffer[setupc]

\page[left]

\startbuffer[series]

\startbuffer
\setupfloat
  [marginfigure]
  [criterium=.5\textwidth,
   maxwidth=\rightmarginwidth,
   default={outermargin,none}]
\stopbuffer

\getbuffer \typebuffer

\startbuffer
\placemarginfigure{}{\blackrule[width=.25cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placemarginfigure{}{\blackrule[width=.5cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placemarginfigure{}{\blackrule[width=1cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placemarginfigure{}{\blackrule[width=2cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placemarginfigure{}{\blackrule[width=4cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placemarginfigure{}{\blackrule[width=8cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placemarginfigure{}{\blackrule[width=16cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\stopbuffer

{\getbuffer[setupa,setupb,setupc,series]} \page
{\getbuffer[setupa,setupb,setupc,series]} \page

\startbuffer[series]

\startbuffer
\setupfloat
  [middlemarginfigure]
  [minwidth=\rightmarginwidth,
   criterium=\backspace,
   location=middle,
   default={outermargin,none}]
\stopbuffer

\getbuffer \typebuffer

\startbuffer
\placemiddlemarginfigure{}{\blackrule[width=.25cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placemiddlemarginfigure{}{\blackrule[width=.5cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placemiddlemarginfigure{}{\blackrule[width=1cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placemiddlemarginfigure{}{\blackrule[width=2cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placemiddlemarginfigure{}{\blackrule[width=4cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placemiddlemarginfigure{}{\blackrule[width=8cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placemiddlemarginfigure{}{\blackrule[width=16cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\stopbuffer

{\getbuffer[setupa,setupb,setupc,series]} \page
{\getbuffer[setupa,setupb,setupc,series]} \page

\startbuffer[series]

\startbuffer
\setupfloat
  [middlefigure]
  [default={here,none}]
\stopbuffer

\getbuffer \typebuffer

\startbuffer
\placemiddlefigure{}{\blackrule[width=.25cm]}
\stopbuffer

\getbuffer \typebuffer

\startbuffer
\placemiddlefigure{}{\blackrule[width=.5cm]}
\stopbuffer

\getbuffer \typebuffer

\startbuffer
\placemiddlefigure{}{\blackrule[width=1cm]}
\stopbuffer

\getbuffer \typebuffer

\startbuffer
\placemiddlefigure{}{\blackrule[width=2cm]}
\stopbuffer

\getbuffer \typebuffer

\startbuffer
\placemiddlefigure{}{\blackrule[width=4cm]}
\stopbuffer

\getbuffer \typebuffer

\startbuffer
\placemiddlefigure{}{\blackrule[width=8cm]}
\stopbuffer

\getbuffer \typebuffer

%\startbuffer
%\placemiddlefigure{}{\blackrule[width=16cm]}
%\stopbuffer
%
%\getbuffer \typebuffer

\stopbuffer

{\getbuffer[setupa,setupb,setupc,series]} \page
{\getbuffer[setupa,setupb,setupc,series]} \page

\startbuffer[series]

\startbuffer
\setupfloat
  [textfigure]
  [criterium=.5\textwidth,
   default={outer,none}]
\stopbuffer

\getbuffer \typebuffer

\startbuffer
\placetextfigure{}{\blackrule[width=.25cm]}
\stopbuffer

\getbuffer \typebuffer

\startbuffer
\placetextfigure{}{\blackrule[width=.5cm]}
\stopbuffer

\getbuffer \typebuffer

\startbuffer
\placetextfigure{}{\blackrule[width=1cm]}
\stopbuffer

\getbuffer \typebuffer

\startbuffer
\placetextfigure{}{\blackrule[width=2cm]}
\stopbuffer

\getbuffer \typebuffer

\startbuffer
\placetextfigure{}{\blackrule[width=4cm]}
\stopbuffer

\getbuffer \typebuffer

\startbuffer
\placetextfigure{}{\blackrule[width=8cm]}
\stopbuffer

\getbuffer \typebuffer

\startbuffer
\placetextfigure{}{\blackrule[width=16cm]}
\stopbuffer

\getbuffer \typebuffer

\stopbuffer

{\getbuffer[setupa,setupb,setupc,series]} \page
{\getbuffer[setupa,setupb,setupc,series]} \page

\startbuffer[series]

\startbuffer
\setupfloat
  [leftfigure]
  [criterium=.5\textwidth,
   default={left,none}]
\stopbuffer

\getbuffer \typebuffer

\startbuffer
\placeleftfigure{}{\blackrule[width=.25cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placeleftfigure{}{\blackrule[width=.5cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placeleftfigure{}{\blackrule[width=1cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placeleftfigure{}{\blackrule[width=2cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placeleftfigure{}{\blackrule[width=4cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placeleftfigure{}{\blackrule[width=8cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placeleftfigure{}{\blackrule[width=16cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\stopbuffer

{\getbuffer[setupa,setupb,setupc,series]} \page
{\getbuffer[setupa,setupb,setupc,series]} \page

\startbuffer[series]

\startbuffer
\setupfloat
  [rightfigure]
  [criterium=.5\textwidth,
   default={right,none}]
\stopbuffer

\getbuffer \typebuffer

\startbuffer
\placerightfigure{}{\blackrule[width=.25cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placerightfigure{}{\blackrule[width=.5cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placerightfigure{}{\blackrule[width=1cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placerightfigure{}{\blackrule[width=2cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placerightfigure{}{\blackrule[width=4cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placerightfigure{}{\blackrule[width=8cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placerightfigure{}{\blackrule[width=16cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\stopbuffer

{\getbuffer[setupa,setupb,setupc,series]} \page
{\getbuffer[setupa,setupb,setupc,series]} \page

\startbuffer[series]

\startbuffer
\setupfloat
  [bleedfigure]
  [criterium=.5\textwidth,
   leftmargindistance=-1mm,
   rightmargindistance=-1mm,
   default={backspace,none}]
\stopbuffer

\getbuffer \typebuffer

\startbuffer
\placebleedfigure{}{\blackrule[width=.25cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placebleedfigure{}{\blackrule[width=.5cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placebleedfigure{}{\blackrule[width=1cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placebleedfigure{}{\blackrule[width=2cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placebleedfigure{}{\blackrule[width=4cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placebleedfigure{}{\blackrule[width=8cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placebleedfigure{}{\blackrule[width=16cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\stopbuffer

{\getbuffer[setupa,setupb,setupc,series]} \page
{\getbuffer[setupa,setupb,setupc,series]} \page

\startbuffer[series]

\startbuffer
\setupfloat
  [bleedfigure]
  [criterium=.5\textwidth,
   leftmargindistance=-1mm,
   rightmargindistance=-1mm,
   default={cutspace,none}]
\stopbuffer

\getbuffer \typebuffer

\startbuffer
\placebleedfigure{}{\blackrule[width=.25cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placebleedfigure{}{\blackrule[width=.5cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placebleedfigure{}{\blackrule[width=1cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placebleedfigure{}{\blackrule[width=2cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placebleedfigure{}{\blackrule[width=4cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placebleedfigure{}{\blackrule[width=8cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\startbuffer
\placebleedfigure{}{\blackrule[width=16cm]}
\stopbuffer

\getbuffer \typebuffer \flushsidefloats

\stopbuffer

{\getbuffer[setupa,setupb,setupc,series]} \page
{\getbuffer[setupa,setupb,setupc,series]} \page

\page

\setupbackgrounds [text] [leftedge]    [background=]
\setupbackgrounds [text] [rightedge]   [background=]
\setupbackgrounds [text] [leftmargin]  [background=]
\setupbackgrounds [text] [rightmargin] [background=]

At \CONTEXT\ and Bacho\TEX meetings it is now a tradition that Harald König and I
spend some time on figuring out what happens with border cases and interfences
with user intervention. As it's hard to nail down I decided to add some more
tracing and control. So, the remainder of this chapter is dedicated to Harald.

We will now demonstrate some features in a way that makes it possible to
compare to the simple default case. Options can be passed as keywords:

\starttyping
\placefigure
  [left,...]
  [fig:whatever]
  {caption}
  {content}
\stoptyping

or as settings:

\starttyping
\startplacefigure
  [default={left,...},
   title=caption,
   reference=fig:whatever]

    content

\stopplacefigure
\stoptyping

It is important to realize that all that spacing can interfere with additional
hard coded corrections at the users end. We don't show the effects of \type
{sidespacebefore} and \type {sidespaceafter}, the two general vertical spacing
hooks. These are currently set to {\tttf \rootfloatparameter {sidespacebefore}}
and {\tttf \rootfloatparameter {sidespaceafter}} respectively. The \type
{sidealign} parameter is always winning from a keyword doing the same.

The last few examples demonstrate that you can define an instance. Often that's
the best way to deal with special cases in a consistent way. For instance:

\starttyping
\definefloat
  [LeftTwo]
  [figure]

\setupfloat
  [LeftTwo]
  [default=left,
   sidealign=line]
\stoptyping

First we show some keyword variant, next some parameter driven versions.

\def\SampleKeyword#1%
  {\setbuffer[foo]
     \useMPlibrary[dum]
     \setupbodyfont[dejavu]
     \setuplayout[page]
     \placefigure[left]{}{\externalfigure[dummy]} \samplefile{sapolsky} \samplefile{sapolsky}
     \placefigure[#1]  {}{\externalfigure[dummy]} \samplefile{sapolsky} \samplefile{sapolsky}
   \endbuffer
   \framed
     [background=color,backgroundcolor=white,offset=overlay]
     {\scale
        [width=.45\textwidth]
        {\typesetbuffer[foo]}}}

\def\SampleSettings#1#2#3%
  {\setbuffer[foo]
     \useMPlibrary[dum]
     \setupbodyfont[dejavu]
     \setuplayout[page]
     \definefloat[#1][figure]
     \setupfloat[#1][default=left]
     \definefloat[#2][figure]
     \setupfloat[#2][#3]
     \startplacefloat[#1] \externalfigure[dummy] \stopplacefloat \samplefile{sapolsky} \samplefile{sapolsky}
     \startplacefloat[#2] \externalfigure[dummy] \stopplacefloat \samplefile{sapolsky} \samplefile{sapolsky}
   \endbuffer
   \framed
     [background=color,backgroundcolor=white,offset=overlay]
     {\scale
        [width=.45\textwidth]
        {\typesetbuffer[foo]}}}

\startbuffer[LeftOne]
\definefloat[LeftOne][figure]

\setupfloat
  [LeftOne]
  [default=left]
\stopbuffer

\startbuffer[LeftTwo]
\definefloat[LeftTwo][figure]

\setupfloat
  [LeftTwo]
  [default=left,
   sidealign=line]
\stopbuffer

\startbuffer[LeftThree]
\definefloat[LeftThree][figure]

\setupfloat
  [LeftThree]
  [default={left,2*line}]
\stopbuffer

\startbuffer[LeftFour]
\definefloat[LeftFour][figure]

\setupfloat
  [LeftFour]
  [default={left},
   topoffset=5pt]
\stopbuffer

\startbuffer[LeftFive]
\definefloat[LeftFive][figure]

\setupfloat
  [LeftFive]
  [default={left},
   bottomoffset=5pt,
   topoffset=5pt]
\stopbuffer

\startlinecorrection
\startcombination[2*2]
    {\SampleKeyword{left,high}}     {\type{left,high}}
    {\SampleKeyword{left,low}}      {\type{left,low}}
    {\SampleKeyword{left,high,low}} {\type{left,high,low}}
    {\SampleKeyword{left,fit}}      {\type{left,fit}}
\stopcombination
\stoplinecorrection

\startlinecorrection
\startcombination[2*2]
    {\SampleKeyword{left,halfline}} {\type{left,halfline}}
    {\SampleKeyword{left,height}}   {\type{left,height}}
    {\SampleKeyword{left,depth}}    {\type{left,depth}}
    {\SampleKeyword{left,grid}}     {\type{left,grid}}
\stopcombination
\stoplinecorrection

\startlinecorrection
\startcombination[2*2]
    {\SampleKeyword{left,line}}     {\type{left,line}}
    {\SampleKeyword{left,1*line}}   {\type{left,1*line}}
    {\SampleKeyword{left,2*line}}   {\type{left,2*line}}
    {\SampleKeyword{left,3*line}}   {\type{left,3*line}}
\stopcombination
\stoplinecorrection

\startlinecorrection
\startcombination[2*2]
    {\SampleSettings{LeftOne}{LeftTwo}  {default={left,line}}}
                                        {\typ{default={left,line}}}
    {\SampleSettings{LeftOne}{LeftThree}{default={left,2*line}}}
                                        {\typ{default={left,2*line}}}
    {\SampleSettings{LeftOne}{LeftFour} {default=left,topoffset=5pt}}
                                        {\typ{default=left, topoffset=5pt}}
    {\SampleSettings{LeftOne}{LeftFive} {default=left, topoffset=5pt, bottomoffset=5pt}}
                                        {\typ{default=left, topoffset=5pt, bottomoffset=5pt}}
\stopcombination
\stoplinecorrection

There is some tracing built in but as this mechanism is rather complex it only
gives an idea about what is going on. Here is an example:

\startbuffer[one]
\enabletrackers[floats.anchoring]

\showframe

\setupfloat
  [sidespacebefore=big,
   sidespaceafter=big]

\starttext
    \dorecurse{10}{
        \placefigure[left]{#1.1}{}
        a small sentence \par
        \placefigure[left]{#1.2}{}
        a small sentence \par
        \input klein \par
    }
\stoptext
\stopbuffer

\typebuffer[one]

In \in {figure} [fig:side:one:1] and \in {figure} [fig:side:one:2] you see the
first two pages of the typeset result.

The anchor to the text is showed in orange and an optional shift in red. The content
is in green and a depth compensation in magenta. Dummy lines added for proper
spacing as well as progressing beyond a previous float are in blue.

\startplacefigure[title={Side float tracing example 1, page 1.},reference=fig:side:one:1]
    \scale[width=\textwidth]{\typesetbuffer[one][page=1]}
\stopplacefigure

\startplacefigure[title={Side float tracing example 1, page 2.},reference=fig:side:one:2]
    \scale[width=\textwidth]{\typesetbuffer[one][page=2]}
\stopplacefigure

A second example that uses different settings is shown in \in {figure}
[fig:side:two:1] and \in {figure} [fig:side:two:2].

\startbuffer[two]
\enabletrackers[floats.anchoring]

\setupfloat
  [sidespacebefore=,
   sidespaceafter=big,
   step=small]

\showframe

\starttext
    \dorecurse{10}{
        \placefigure[left]{#1.1}{}
        a small sentence \par
        \placefigure[left]{#1.2}{}
        a small sentence \par
        \input klein \par
    }
\stoptext
\stopbuffer

\typebuffer[two]

\startplacefigure[title={Side float tracing example 2, page 1.},reference=fig:side:two:1]
   \framed
      [background=color,backgroundcolor=white,offset=overlay]
      {\scale[width=\textwidth]{\typesetbuffer[two][page=1]}}
\stopplacefigure

\startplacefigure[title={Side float tracing example 2, page 2.},reference=fig:side:two:2]
   \framed
      [background=color,backgroundcolor=white,offset=overlay]
      {\scale[width=\textwidth]{\typesetbuffer[two][page=2]}}
\stopplacefigure

\startbuffer[three]
\usemodule[simulate]

\setuplayout
  [tight]

\setupbodyfont
  [dejavu]

\enabletrackers
  [floats.anchoring]

\setupfloats
  [sidethreshold=.5\strutdp, % default, use "old" for previous implementation
   step=small]

\definemeasure[MyHeight][3cm]
\definemeasure[MyWidth] [3cm]

% \setupheadertexts
%   [width=\measure{MyWidth}\quad height=\measure{MyHeight}]

\unexpanded\def\FakeWords#1%
  {\simulatewords
     [n=#1,m=#1,min=1,max=5,hyphen=no,color=text,line=yes,random=1234]}

\starttext

\startbuffer
    \FakeWords{100}\par
    \placefigure
        [left] {oeps}
        {\framed[width=\measure{MyWidth},height=\measure{MyHeight}]{}}
    \FakeWords  {2}\par
    \FakeWords  {3}\par
    \FakeWords  {5}\par
    \FakeWords  {4}\par
    \FakeWords{200}\par
    \placefigure
        [left] {oeps}
        {\framed[width=\measure{MyWidth},height=\measure{MyHeight}]{}}
    \FakeWords{200}\par
\stopbuffer

\dostepwiserecurse {\number\dimexpr3cm} {\number\dimexpr4cm} {\number\dimexpr0.25cm} {
    \definemeasure[MyWidth][#1sp]
    \dostepwiserecurse {\number\dimexpr3cm} {\number\dimexpr4cm} {\number\dimexpr0.25cm} {
        \definemeasure[MyHeight][##1sp]
        \start
            \setupwhitespace[none]
            \getbuffer \page
        \stop
        \start
            \setupwhitespace[big]
            \getbuffer \page
        \stop
    }
}
\stoptext
\stopbuffer

Progressing next to a side float and determining how many lines to indent is a
somewhat complex mechamism because many factors play a role and spacing can
interfere badly. The decision about the number of lines to hang is to some extend
controllable but there are cases when you need to steer it (for instance by
scaling an image). In the next overviews we see the result of the following
somewhat complex setup:

\typebuffer[three]

The \type {step} parameter controls how we fill up the space when we need to
progress beyond it for instance because another float shows up or because we
issue a \type {\flushsidefloats}. Its value can be \type {big}, \type {medium} or
\type {small} and defaults to \type {small} which gives of enough precision. The
\type {sidethreshold} parameter controls the number of lines that we hang around
the float. Here we only show the consequence of the the threshold. A larger
threshold result in mode whitespace below the side float. You can zoom in to see
what happens at the bottom of the float (or run the examples yourself).

\def\ShowSample#1%
  {\framed
     [background=color,backgroundcolor=white,offset=overlay]
     {\scale
        [width=\dimexpr(\textwidth-2\emwidth)/3\relax]
        {\typesetbuffer[three][page=#1]}}}

\startplacefigure[title={The working of default step and side threshold (no whitespace.},reference=fig:side:three:1]
    \startcombination[3*3]
        {\ShowSample {1}} {} {\ShowSample {3}} {} {\ShowSample {5}} {}
        {\ShowSample {7}} {} {\ShowSample {9}} {} {\ShowSample {9}} {}
        {\ShowSample{11}} {} {\ShowSample{13}} {} {\ShowSample{15}} {}
    \stopcombination
\stopplacefigure

\startplacefigure[title={The working of default step and side threshold (whitespace).},reference=fig:side:three:2]
    \startcombination[3*3]
        {\ShowSample {2}} {} {\ShowSample {4}} {} {\ShowSample {6}} {}
        {\ShowSample {8}} {} {\ShowSample{10}} {} {\ShowSample{12}} {}
        {\ShowSample{12}} {} {\ShowSample{14}} {} {\ShowSample{15}} {}
    \stopcombination
\stopplacefigure

\stopchapter

\stopcomponent