% author    : Hans Hagen
% copyright : ConTeXt Development Team
% license   : Creative Commons Attribution ShareAlike 4.0 International
% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions
% origin    : the ConTeXt distribution
%
% comment   : Because this manual is distributed with TeX distributions it comes with a rather
%             liberal license. We try to adapt these documents to upgrades in the (sub)systems
%             that they describe. Using parts of the content otherwise can therefore conflict
%             with existing functionality and we cannot be held responsible for that. Many of
%             the manuals contain characteristic graphics and personal notes or examples that
%             make no sense when used out-of-context.
%
% comment   : Some chapters might have been published in TugBoat, the NTG Maps, the ConTeXt
%             Group journal or otherwise. Thanks to the editors for corrections. Also thanks
%             to users for testing, feedback and corrections.

\dontcomplain

\definepagebreak[mine][yes]

% A complete otf optima pack is too expensive for this (I only have the
% type one set).
%
% \usetypescriptfile
%   [type-ghz]
%
% \usetypescript
%   [sans]
%   [optima-nova]
%
% \setupbodyfont
%   [optima-nova,11pt]
%
% \definefont[QuiteLarge][SansBold sa 3]
% \definefont[NotSoLarge][SansBold sa 1.5]
%
% So we could use:
%
% \setupbodyfont
%   [pagella,11pt]
%
% \definefont[QuiteLarge][Bold sa 2.50]
% \definefont[NotSoLarge][Bold sa 1.25]
%
% But this one has a matching sans:

\setupbodyfont
  [dejavu,11pt]

\definefont[QuiteLarge][SansBold sa 2.50]
\definefont[NotSoLarge][SansBold sa 1.25]

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

\setuppagenumbering
  [alternative=doublesided,
   location=]

\setupwhitespace
  [line]

\setupblank
  [line]

\setuptyping
  [blank=halfline]

\startsetups [pagenumber]
    \hbox to .2\paperwidth {
        \hss
        Page \pagenumber
        \hss
    }
\stopsetups

\setupfooter [before=\vfill,after=\vfill,style=\bf,color=color-4]
\setupheader [before=\vfill,after=\vfill,style=\bf,color=color-4]

\setupfootertexts [] [\setups{pagenumber}]
\setupheadertexts [] [\setups{chapterhead}]

\startsetups [chapterhead]
    \hbox to .2\paperwidth {
        \hss
        \getmarking[chapter]
        \hss
    }
\stopsetups

\setuphead
  [chapter]
  [header=empty]

\definecolor[color-1][.5(red,green)]
\definecolor[color-2][.5(green,blue)]
\definecolor[color-3][.5(blue,red)]
\definecolor[color-4][.5(white,black)]
\definecolor[color-5][.5(white,color-4)]
\definecolor[color-6][.2(white,color-4)]

\usemodule[typesetting]

\setupcombination
  [style=mono]

\startuseMPgraphic{page}
StartPage ;
    path p ;
    numeric n; n := PageNumber ;
    numeric w; w := bbwidth(Page) ;
    numeric h; h := bbheight(Page) ;
    def DrawBit (expr bit, dx, dy) =
        path p ; p := unitsquare xyscaled(w/5,h/40) shifted (dx*w/10,dy*(h-h/40)) ;
        if n div bit > 0 :
            n := n - (n div bit)*bit ;
            fill p withcolor \MPcolor{color-1} ;
        else :
            fill p withcolor \MPcolor{color-2} ;
        fi ;
    enddef ;
    DrawBit(32,7,1) ;
    DrawBit(16,4,1) ;
    DrawBit( 8,1,1) ;
    DrawBit( 4,7,0) ;
    DrawBit( 2,4,0) ;
    DrawBit( 1,1,0) ;
StopPage ;
\stopuseMPgraphic

\startuniqueMPgraphic{frame}
    fill OverlayBox withcolor \MPcolor{color-5} ;
\stopuniqueMPgraphic

\startuniqueMPgraphic{contrast}
    fill OverlayBox withcolor \MPcolor{color-4} ;
\stopuniqueMPgraphic

\defineoverlay[page]    [\useMPgraphic{page}]
\defineoverlay[frame]   [\useMPgraphic{frame}]
\defineoverlay[contrast][\useMPgraphic{contrast}]

\setuphead
  [chapter]
  [style=\QuiteLarge,
   color=color-3,
   number=no]

\setuplist
  [chapter]
  [command=\MyListCommand,
   alternative=command]

\starttexdefinition unexpanded MyListCommand #1#2#3
    \snaptogrid
        [line,-line]\vbox {
            \tfb
            \setstrut
            \strut#2
            \quad#3
        }
\stoptexdefinition

\setupmargindata
  [style=\tttf,
   color=color-3]

\starttexdefinition unexpanded ShowFile #1
    \margintext
        {\cldcontext{string.match("#1","\letterpercent d+")}}
    \typefile
        [range={environment}]
        {#1}
\stoptexdefinition

% \typefile[range=4]  {...}
% \typefile[range={=}]{...} % start after comment lines

\starttexdefinition unexpanded ShowEnvironmentFile #1
    \margintext
        {\cldcontext{string.match("#1","\letterpercent d+")}}
    \typefile
        [range={=startenvironment}]
        {#1}
\stoptexdefinition

\startdocument

\startMPpage
StartPage ;
    path p ; numeric w, h, d ; picture q ;
    if true :
        q := image(draw textext.urt("\ssbf COLUMNS") withcolor \MPcolor{color-6}) ;
    else :
        q := image(draw textext.urt("\ssbf COLUMNSETS") withcolor \MPcolor{color-6}) ;
    fi ;
    w := bbwidth(Page) ;
    h := bbheight(Page) ;
    d := h/100 ;
    fill Page withcolor \MPcolor{color-1} ;
    p := Page xysized (w,d) ;
    for i := 5d step 2d until h-5d :
        fill p shifted (0,i) withcolor \MPcolor{color-2} ;
    endfor
    p := Page xysized(w/10,h) ;
    for i = 0, .3, .6, .9 :
        fill p shifted (i*w,0) withcolor \MPcolor{color-1} withtransparency(1,.75) ;
    endfor ;
    def do_it(expr sz, sh) =
        p := Page xysized sz ;
        fill p shifted sh withcolor \MPcolor{color-3} withtransparency(1,.5) ;
        draw q xysized (bbwidth(p),bbheight(p)) shifted sh ;
    enddef ;
    do_it ((2w/10,17d),(.1w,20d)) ;
    do_it ((2w/10,15d),(.1w,56d)) ;
    do_it ((2w/10,21d),(.4w,66d)) ;
    do_it ((2w/10,13d),(.7w,38d)) ;
    do_it ((5w/10,13d),(.4w,13d)) ;
    draw textext.urt("\ssbf Hans Hagen")
        xysized (5w/10,5d)
        shifted (.4w,6d)
        withcolor \MPcolor{color-5} ;
StopPage ;
\stopMPpage

\page[empty] \setuppagenumber[number=1]

\setupbackgrounds
  [page]
  [background=page]

\starttitle[title=Contents]

    \placelist[chapter]

\stoptitle

\startchapter[title=Introduction]

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 mechanism performs okay but it needs to be used with care: an occasional
manual intervention is needed to get optimal results. After all, we're operating
in the area where normally click and point desktop publishing is used.

{\bf For the moment you need to load the new code with: \type{\usemodule[newcolumnsets]}}

\startlines
Hans Hagen
PRAGMA ADE
Hasselt, 2003\endash2016
\stoplines

\stopchapter

\startchapter[title=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

In \MKIV\ a new mixed column mechanism has been introduced that will be
developped further and eventually replace the old multi column handler. In \MKII\
there is also a columnset mechanism that can be used to construct complex multi
column pages. In \MKIV\ this gets replaced by grid columns. All these multi
column mechanisms have in common that the output routine is more complex because
now a page is in fact a collection of pages wrapped onto one. Each column is
(from \TEX's perspective) similar to a one narrow column page. Here we focus on
columnsets (page grids).

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. The
number in the margin serves a reference to the file where this snippet of \TEX\
is stored.

\ShowEnvironmentFile{columnsets-000}

\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.

\FourSpread{columnsets-001}

These pages were typeset with the following code:

\ShowFile{columnsets-001}

We will showmost examples on a spread, so we don't show a first page. On a
spread like above we number columns from~1 to~4, which in practice means that in
this case columns starting on right page start with column~3!

\SixPages{columnsets-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.

\FourSpread{columnsets-002}

This time the input is:

\ShowFile{columnsets-002}

Again, we started on a right page but showed the spreads. You can see it from the
positioning of the header texts.

\SixPages{columnsets-002}

\page[mine]

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

\FourSpread{columnsets-003}

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.

\ShowFile{columnsets-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:

\FourSpread{columnsets-004}

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

\ShowFile{columnsets-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.

\FourSpread{columnsets-005}

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.

\ShowFile{columnsets-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.

\FourSpread{columnsets-006}

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

\ShowFile{columnsets-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.

\FourSpread{columnsets-007}

\ShowFile{columnsets-007}

\stopchapter

\startchapter[title=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.

\FourSpread{columnsets-101}

\ShowFile{columnsets-101}

\page[mine]

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

\EightSpread{columnsets-102}

The prefered location is passed as a four character directive:

\ShowFile{columnsets-102}

\page[mine]

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 directional locations:

\OneSpread{columnsets-103}

\ShowFile{columnsets-103}

\stopchapter

\startchapter[title=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.

\FourSpread{columnsets-201}

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}.

\ShowFile{columnsets-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.

\FourSpread{columnsets-202}

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

\ShowFile{columnsets-202}

\page[mine]

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

\FourSpread{columnsets-203}

\ShowFile{columnsets-203}

\page[mine]

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

\FourSpread{columnsets-204}

Watch how we explicitly go to a left page.

\ShowFile{columnsets-204}

\page[mine]

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
  {\scale[width=.4\textwidth]{\clip
     [nx=2,ny=6,x=2,y=2]
     {\typesetfile[columnsets-204.tex][page=2]}}}
  {left page}
  {\scale[width=.4\textwidth]{\clip
     [nx=2,ny=6,x=1,y=2]
     {\typesetfile[columnsets-204.tex][page=3]}}}
  {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
  {\scale[width=.4\textwidth]{\clip
     [nx=2,ny=6,x=2,y=2]
     {\typesetfile[columnsets-205.tex][page=2]}}}
  {left page}
  {\scale[width=.4\textwidth]{\clip
     [nx=2,ny=6,x=1,y=2]
     {\typesetfile[columnsets-205.tex][page=3]}}}
  {right page}
\stopcombination
\stoplinecorrection

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

\FourSpread{columnsets-206}

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.

\ShowFile{columnsets-206}

\stopchapter

\startchapter[title=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.

\FourPages{columnsets-301}

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

\ShowFile{columnsets-301}

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

\stopchapter

\startchapter[title=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.}

\FourSpread{columnsets-401}

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

\ShowFile{columnsets-401}

\page[mine]

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

\FourSpread{columnsets-402}

This time we used equal distances:

\ShowFile{columnsets-402}

\page[mine]

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

\FourSpread{columnsets-403}

In code:

\ShowFile{columnsets-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.

\FourSpread{columnsets-404}

In code:

\ShowFile{columnsets-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:

\FourSpread{columnsets-405}

In the second spread you see how the narrow hsize carries on in the wider
column. A \type {\column} command will synchronize the hsize.

\ShowFile{columnsets-405}

% \page[mine]

\stopchapter

\startchapter[title=Directions]

\FourSpread{columnsets-601}

The direction of flushing columns is determined by the \type {direction}
parameters as demonstrated below.

\ShowFile{columnsets-601}

% \page[mine]

\stopchapter

\startchapter[title=Backgrounds]

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

\FourSpread{columnsets-701}

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

\ShowFile{columnsets-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.

\FourSpread{columnsets-702}

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

\ShowFile{columnsets-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.

\FourSpread{columnsets-703}

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.

\ShowFile{columnsets-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}.

\EightSpread{columnsets-704}

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

\ShowFile{columnsets-704}

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

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

% \page[mine]

\stopchapter

\startchapter[title=Numbering lines]

\FourSpread{columnsets-901}

This example shows how numbering lines in columns works out. In a two column
layout the numbers end up in the outer margins by default. If you want you can
set the \type {location} to for instance \type {left} or \type {right}.

\ShowFile{columnsets-901}

\page[mine]

\FourSpread{columnsets-902}

In a three column setup the numbers end up in the left margins.Make sure you make
the distance large enough.

\ShowFile{columnsets-902}

% \page[mine]
%
% \FourSpread{columnsets-903}
%
% This example shows again lune numbers but here we made sure that there is no
% stretch in the whitespace.
%
% \ShowFile{columnsets-903}

\stopchapter

% \startchapter[title=Spanning and More]
%
% {\em todo: explanation} \page
%
% \TwoPages{columnsets-801} \ShowFile{columnsets-801} \page[mine]
% \TwoPages{columnsets-802} \ShowFile{columnsets-802} \page[mine]
% \TwoPages{columnsets-803} \ShowFile{columnsets-803} \page[mine]
% \TwoPages{columnsets-804} \ShowFile{columnsets-804} \page[mine]
% \TwoPages{columnsets-805} \ShowFile{columnsets-805} \page[mine]
% \TwoPages{columnsets-806} \ShowFile{columnsets-806} \page[mine]
%
% \stopchapter

\stopdocument