\startcomponent co-columns

\usemodule[visual] % for \fakewords

\environment contextref-env
\product contextref

\chapter[columns]{Columns}

\definecombination
  [fourpages]
  [%inbetween=\blank,
   distance=.5\bodyfontsize,
   width=\textwidth]

\definecombination
  [twopages]

\setuplayout
  [backspace=.1\paperwidth,
   topspace=.025\paperheight,
   header=0.025\paperheight,
   footer=0.025\paperheight,
   headerdistance=0.025\paperheight,
   footerdistance=0.025\paperheight,
   grid=yes,
   width=middle,
   height=middle]

\setuppagenumbering
  [alternative=doublesided,
   location=]

\setupwhitespace
  [line]

\setupblank
  [line]

\setuptyping
  [blank=halfline]

\startbuffer[twopages]

\startlinecorrection[blank]
\startcombination[twopages][2*1]
  {\externalfigure[twopages][page=1,lines=15]} {}
  {\externalfigure[twopages][page=2,lines=15]} {}
\stopcombination
\stoplinecorrection

\stopbuffer

\startbuffer[fourpages]

\startlinecorrection[blank]
\startcombination[fourpages][4*1]
  {\externalfigure[fourpages][page=1,lines=10]} {}
  {\externalfigure[fourpages][page=2,lines=10]} {}
  {\externalfigure[fourpages][page=3,lines=10]} {}
  {\externalfigure[fourpages][page=4,lines=10]} {}
\stopcombination
\stoplinecorrection

\stopbuffer

\startbuffer[eightpages]

\startlinecorrection[blank]
\startcombination[fourpages][4*2]
  {\externalfigure[eightpages][page=1,lines=10]} {}
  {\externalfigure[eightpages][page=2,lines=10]} {}
  {\externalfigure[eightpages][page=3,lines=10]} {}
  {\externalfigure[eightpages][page=4,lines=10]} {}
  {\externalfigure[eightpages][page=5,lines=10]} {}
  {\externalfigure[eightpages][page=6,lines=10]} {}
  {\externalfigure[eightpages][page=7,lines=10]} {}
  {\externalfigure[eightpages][page=8,lines=10]} {}
\stopcombination
\stoplinecorrection

\stopbuffer

\section{Introduction}
\index{columns}


This manual introduces {\em column sets}, one of the output
routines of \CONTEXT. Although column sets are mainly meant
for typesetting journals in a semi||automated way, you can
also use them for books. We assume that the user is familiar
with \CONTEXT\ and only discuss the commands that are
related to column sets. This manual is dedicated to those on
the \CONTEXT\ mailing list who urged me to explain how
column sets work.

This mechanism is still under construction which means that
functionality may be added and improved. Given the complex
nature of this kind of typeseting, you may occasionally run
into strange situations.

Column sets are not the most efficient mechanism in
\CONTEXT, partly because we're actually dealing with
multiple virtual pages (columns) per page, but mostly
because of the features that we need to support.

\startlines
Hans Hagen
PRAGMA ADE
Hasselt, April 2003
\stoplines

\section{Basics}

As soon as enough content is collected to build a page,
\TEX\ will invoke the output routine. This is not a fixed
piece of code, but a collection of macro calls. The default
output routine is a meant for typesetting a single column,
as in this document. A multi||column output routine is
available as well. This routine mixes well with the single
column one, and is activated by:

\starttyping
\startcolumns
some text ...
\stopcolumns
\stoptyping

There are some limitations to what you can do with this
kind of multi columns, which is why we have a third routine
at out disposal: {\em column sets}. This routine can be
used for rather complex layouts with graphics all over the
place, and text spanning columns or even spreads. There are
of course some shortcomings, which we will discuss later.

In the examples that follow we use the following style to
set up the layout:

\typefile{columns/cols-000.tex}

\page[mine]

Before we will demonstrate more complex layouts, we will
introduce a few features. In the next series of examples we
use fake text. You can enlarge the pages in your viewer if
you want to see more detail.

\useexternalfigure[fourpages][columns/cols-001] \getbuffer[fourpages]

These pages were typeset with the following code:

\typefile{columns/cols-001}

\page[mine]

The number of columns is not fixed to two. You can even have
a different number of columns on left and right pages.

\useexternalfigure[fourpages][columns/cols-002] \getbuffer[fourpages]

This time the input is:

\typefile{columns/cols-002}

\page[mine]

In order to get the balancing you want, you can manually
influence the height of a column.

\useexternalfigure[fourpages][columns/cols-003] \getbuffer[fourpages]

When you set the number of column lines to a positive value,
that will be the number of lines. A negative value will be
subtracted from the maximum number of lines.

\typefile{columns/cols-003}

\page[mine]

In articles you may want to let the introduction span
multiple columns. A column span is defined independent of a
column set and shows up as follows:

\useexternalfigure[fourpages][columns/cols-004] \getbuffer[fourpages]

Here we've given the span a background so that it stands
out.

\typefile{columns/cols-004}

\page[mine]

A column span can be positioned like any graphic. Later we
will discuss the placement options in more detail, for the
moment all you need to know is that \type {btlr} tells
\CONTEXT\ to place the graphic in the left bottom of the
the text area.

\useexternalfigure[fourpages][columns/cols-005] \getbuffer[fourpages]

Here we pass the \type {default} placement as parameter to
the span, but you can also set it at definition time. We use
a brute force simple column splitter to fake columns inside
the span.

\typefile{columns/cols-005}

\page[mine]

You are not limited to one column span. In this sense a
span is like a graphic: as long as there is room, it will
be placed where you want it to be placed. The main
difference between a span and a graphic is that a span
expects text and tries to align the baselines with the rest
of the text. In many ways a column span behaves like a
framed text.

\useexternalfigure[fourpages][columns/cols-006] \getbuffer[fourpages]

This time we flushed one of the spans from bottom to top,
starting at the right edge: \type {btrl}.

\typefile{columns/cols-006}

\page[mine]

Column spans are treated like graphics, which means that
they will float if needed. In the process, the width is
limited to the available space, which in some cases may
lead to a smaller span than you may expect. Think of a
column span, calculated (and prepared) in the last column
and ending up on the next page in the first column, where a
broader span would have been possible.

\useexternalfigure[fourpages][columns/cols-007] \getbuffer[fourpages]

\typefile{columns/cols-007}

\section{Graphics}

Most documents have graphics, and therefore column sets can
contain them. The main thing that you have to keep in mind
when placing graphics, is that column sets are based on
grids. Therefore spacing around graphics is also grid based.

\useexternalfigure[fourpages][columns/cols-101] \getbuffer[fourpages]

\typefile{columns/cols-101}

\page[mine]

You can tell \CONTEXT\ where it should place the graphic,
but this will only be honored when there is still place.

\useexternalfigure[eightpages][columns/cols-102] \getbuffer[eightpages]

The prefered location is passed as a four character
directive:

\typefile{columns/cols-102}

The following directives are available:

\starttabulate[|lT|p|]
\NC btlr     \NC flush from bottom to top    and left to right  \NC \NR
\NC btrl     \NC flush from bottom to top    and right to left  \NC \NR
\NC tblr     \NC flush from top    to bottom and left to right  \NC \NR
\NC tbrl     \NC flush from top    to bottom and right to left  \NC \NR
\NC lrbt     \NC flush from left   to right  and bottom to top  \NC \NR
\NC lrtb     \NC flush from left   to right  and top to bottom  \NC \NR
\NC rlbt     \NC flush from right  to left   and bottom to top  \NC \NR
\NC rltb     \NC flush from right  to left   and top to bottom  \NC \NR
\NC here     \NC try to place the graphic here                  \NC \NR
\NC fixd     \NC force the graphic here and don't float         \NC \NR
\NC fxtb:c*r \NC place the graphic at (c,r) or lower if needed  \NC \NR
\NC fxbt:c*r \NC place the graphic at (c,r) or higher if needed \NC \NR
\NC tops     \NC place the graphic at the top of the page       \NC \NR
\NC bots     \NC place the graphic at the bottom of the page    \NC \NR
\NC page     \NC place the graphic at a separate page           \NC \NR
\stoptabulate

In the next example we show the 16 directional locations:

\useexternalfigure[fourpages][columns/cols-103] \getbuffer[fourpages]

\typefile{columns/cols-103}

\section{Areas}

So far we have seen texts and graphics that span multiple
columns using span commands and floats placement commands.
We have also seen that you can define a different number of
columns for left and right pages. Now that we have arrives
at column areas you will see how we can span information
over not only a page but also over pages in a spread.

\useexternalfigure[fourpages][columns/cols-201] \getbuffer[fourpages]

Being a framed text, by default an area is aligned at the
baseline. You can lower an area by setting the \type
{location} to \type {depth}.

\typefile{columns/cols-201}

\page[mine]

You can position areas on the left, right or next page or on
both pages. When you set \type {state} to \type {repeat}, an
area is repeated, otherwise it is only placed once.

\useexternalfigure[fourpages][columns/cols-202] \getbuffer[fourpages]

Here we just repeat the areas. Normally this only make sense
when the content is worth repeating.

\typefile{columns/cols-202}

\page[mine]

Areas can span a spread, as is demonstrated in the next
example.

\useexternalfigure[fourpages][columns/cols-203] \getbuffer[fourpages]

\typefile{columns/cols-203}

\page[mine]

An application of a spread area is a title. In the next
example we show two spread pages.

\useexternalfigure[fourpages][columns/cols-204] \getbuffer[fourpages]

Watch how we explicitly go to a left page.

\typefile{columns/cols-204}

The \type {\GapText} macro is an experimental fun macro and is
used to make sure that we don't end up with a clipped
character.

\startlinecorrection[blank]
\startcombination
  {\clip
     [nx=2,ny=6,x=2,y=2]
     {\externalfigure[columns/cols-204][page=2][lines=40]}} {left page}
  {\clip
     [nx=2,ny=6,x=1,y=2]
     {\externalfigure[columns/cols-204][page=3][lines=40]}} {right page}
\stopcombination
\stoplinecorrection

This is a typical example of the kind of optimizations that
are needed when you make documents of styles with text that
spans a spread. In the next clip we visualize the gap.

\startlinecorrection[blank]
\startcombination
  {\clip
     [nx=2,ny=6,x=2,y=2]
     {\externalfigure[columns/cols-205][page=2][lines=40]}} {left page}
  {\clip
     [nx=2,ny=6,x=1,y=2]
     {\externalfigure[columns/cols-205][page=3][lines=40]}} {right page}
\stopcombination
\stoplinecorrection

\page[mine]

At some moment you may want to set up an area in advance as
we have done in the following example.

\useexternalfigure[fourpages][columns/cols-206] \getbuffer[fourpages]

The \type {page} key is used to specify the page in the
column set that the area should go into. Column set pages
start numbering at~1. The \type {fixed} stands for left or
right, whatever comes first.

\typefile{columns/cols-206}

\section{Columns}

You can use \type {\page} to go to a new page in a column
set. Likewise you can use \type {\column} to force a column
break.

\useexternalfigure[fourpages][columns/cols-301] \getbuffer[fourpages]

This example demonstrates that you can supply \type
{\column} with explicit directives.

\typefile{columns/cols-301}

You can use \type {\column[page]} as an alternative for
\type {\page}.

\section{Details}

This chapter will cover a couple of cosmetic details of
column sets. {\em Some features need to be improved,
especially in combination with areas, graphics and alike. We
will also provide side floats etc.}

\useexternalfigure[fourpages][columns/cols-401] \getbuffer[fourpages]

You can set the distance between columns for each pair of
columns. {\em Todo: left and right page distances and
margins.}

\typefile{columns/cols-401}

\page[mine]

When you can the distance of the first column as well. This
creates a margin.

\useexternalfigure[fourpages][columns/cols-402] \getbuffer[fourpages]

This time we used equal distances:

\typefile{columns/cols-402}

\page[mine]

The width of columns is normally calculated automatically,
but you can also set the width explicitly:

\useexternalfigure[fourpages][columns/cols-403] \getbuffer[fourpages]

In code:

\typefile{columns/cols-403}

\page[mine]

For special effects, you can set the width per column. In
that case you need to be aware of the fact that \TEX\ works
its way through the document per paragraph. Changing
the width halfway a paragraph is possible but will affect
the whole paragraph. Therefore, this feature works best when
you also goto the next column explicitly.

\useexternalfigure[fourpages][columns/cols-404] \getbuffer[fourpages]

In code:

\typefile{columns/cols-404}

\page[mine]

If you really want to change the width in the middle of a
paragraph, you can do a trial run and include a breakpoint
at the palce where you want it to occur:

\useexternalfigure[fourpages][columns/cols-405] \getbuffer[fourpages]

Again in code:

\typefile{columns/cols-405}

\page[mine]

Now, in situations like this, you definitely don't want the
second page to have a wide first column as well. You'll want
something:

\useexternalfigure[fourpages][columns/cols-406] \getbuffer[fourpages]

We achieved this by chaining two column sets:

\typefile{columns/cols-406}

\page[mine]

This is still not perfect. Adapting the width to a change in
column width is not trivial to implement in \TEX, especially
because changes in the output routine do not naturally
migrate to the outside world: output routines act in their
own grouped environment. However, in most cases such a
change is not desirable at all, since the second and
following columns need to have equal widthts. The following
solution is better.

\useexternalfigure[fourpages][columns/cols-407] \getbuffer[fourpages]

Watch how we expliticly set the widths of the columns before
entering the column set.

\typefile{columns/cols-407}

\section{Flows}

We will not introduce an old feature called text flow, but a
bit tricky in combination with column sets:

\useexternalfigure[fourpages][columns/cols-501] \getbuffer[fourpages]

Beware, this is some experimental code:

\typefile{columns/cols-501}

\section{Directions}

In this chapter we will cover typesetting from right to left
as we as chinese.

\section{Backgrounds}

As with many \CONTEXT\ components, column sets can have
backgrounds.

\useexternalfigure[fourpages][columns/cols-701] \getbuffer[fourpages]

Watch how we use the \type {each} keyword to tell \CONTEXT\
that we want to apply the background to each column of the
set.

\typefile{columns/cols-701}

\page[mine]

Normally, if you apply backgrounds this way, you will also
set the background offset. In a similar fashion you can
apply backgrounds to areas and spans. Such backgrounds can
be a color, or any overlay or layer you want.

\useexternalfigure[fourpages][columns/cols-702] \getbuffer[fourpages]

Here we've set the background offset as well as the frame.

\typefile{columns/cols-702}

\page[mine]

When dealing with areas, you need to be aware of the fact
that they are clipped, the content as well as the
background.

\useexternalfigure[fourpages][columns/cols-703] \getbuffer[fourpages]

De default clip offset is two times the lineheight, except
in the binding, where it is set to zero points. You can set
the clip offset with the \type {clipoffset} parameter.

\typefile{columns/cols-703}

\page[mine]

The text background mechanism is rather well adapted to
column sets. The following example is a variant on an
example shown in the manual titled {details}.

\useexternalfigure[eightpages][columns/cols-704] \getbuffer[eightpages]

Watch how we adapt the background to the fact and extent
that the text spans one or more columns.

\typefile{columns/cols-704}

Backgrounds that follow the paragraph shape also work ok in
column sets.

\page

\todo{an example of a bleeding graphic with column feed back (from techniek)}

\section{Spanning and More}

\todo{explanation} \page

\useexternalfigure[twopages][columns/cols-801] \getbuffer[twopages] \typefile{columns/cols-801} \page[mine]
\useexternalfigure[twopages][columns/cols-802] \getbuffer[twopages] \typefile{columns/cols-802} \page[mine]
\useexternalfigure[twopages][columns/cols-803] \getbuffer[twopages] \typefile{columns/cols-803} \page[mine]
\useexternalfigure[twopages][columns/cols-804] \getbuffer[twopages] \typefile{columns/cols-804} \page[mine]
\useexternalfigure[twopages][columns/cols-805] \getbuffer[twopages] \typefile{columns/cols-805} \page[mine]
\useexternalfigure[twopages][columns/cols-806] \getbuffer[twopages] \typefile{columns/cols-806} \page[mine]

\stopcomponent
