% language=us

% author    : Hans Hagen & Mikael Sundqvist
% 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.

% context --pattern=columnsets-*.tex --parallel

\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")
    draw textext.urt("\ssbf the context lmtx way")
        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 were originally meant for typesetting journals in a
semi-automated way, you can also use them for books, educational materials,
leaflets and such. This mechanism was already there in \MKII, was adapted to
\MKIV\ but in \MKXL\ we decided to overhaul it more drastically. Where in the
former approach there was a mix between setting up spreads either of not with
already placed content it was still a sequential processing of content. Graphics
are being placed as one goes and there are various ways to anchor them on still
available places. The gaps in columns (slots) that result from this get filled
with following content.

In \MKXL\ a different approach is followed. We have a set of spreads and one can
put elements on them beforehand. This can be done before the content is entered
or during entering. However the content itself is not yet placed. That happens
when the column set ends. Of course there can also be figures in the flow but
these end up at the location where they were defined, at the top or at the
bottom. The reason why they will not end up on the current page is that there is
no concept of a current page any more. Say that we have 10 spreads with two times
three columns. That gives us 60 slots to fill, maybe even more if we have split
columns by content already placed explicitly. The accumulated content is
distributed over these 60 slot as good as possible, which can take several passes
of optimization. \footnote {Although we can have hundreds of passes to get this
right users won't notice this as a performance hit: the approach is surprisingly
fast.} This means that a specific line can end up on a different page depending
on what is considered best. \footnote {This means that instead of an independent
output routine we have a special page shape based balancing routine that works in
combination with the ship out part of the main single column routine.}

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. For that
reason we have two manuals. This one just describes various mechanisms that make
up column sets. In another manual we discuss the approach to making nice looking
document using column sets. In both cases we assume that the user is familiar
with \CONTEXT\ and only discuss the commands that are related to column sets.

This approach to column sets is made possible because the \LUAMETATEX\ engine has
some features that are of help. Although one can approach this \quote
{academically} we didn't do that: we just started from what we already had (in
mind) and wanted to do better. In order do that we started working on some
demanding documents, one being nice looking lecture notes with lots of graphics
and math, in multiple columns, meant for both looking good at the screen and
looking great in print. At the same time we looked at parallel documents as often
requested by users. Both resulted in what in the engine is called \quote {main
vertical list} interception and \quote {balancing}. As we progressed we handled
notes and later split notes (using inserts), marks (also per column), top and
bottom floats (also using inserts), selective discarding elements (spacing
related), and so on. Because these and other specific properties have to be
handled and in the end we basically got an alternative page builder, one inspired
by \CONTEXT\ features and demands. Compared to the single pass progressive page
builder we gain a lot but also loose a little, most noticeably split footnotes
(inserts) are done differently but in practice that should not be an issue. The
low level mechanisms involved are discussed in a so called \quote {lowlevel}
manual, articles and presentations.

We might come up with more features but only when we think that they are not only
reliable but also easy to explain. \footnote {An example of this are notes. We
handle them per column slot and one column can have more slots. We don't support
page wide notes but of course end notes are possible, even in columns. In fact
one can have notes in different layout areas. This idea is that one should just
use what is provided which makes more sense than trying to fit demands of (say)
publishers and designers who have little clue of what an engine like we use can
do. For users it's easier to work with reliable mechanism than to fight tricky
heuristics. When extending this mechanism we discussed various solutions and
features but rejected them for the reasons mentioned.} Keep in mind that a bit
of extra manual work in the end is easier than some complex configurable hard to
explain mechanism. As usual, we're sure that users come up with nice looking
results and|/|or very advanced parallel documents using multiple note categories
mixed with graphics and such, which in turn might inspire us to cook up easier to
use features.

We hope that you have as much fun as we had when upgrading and playing with this
mechanism, and yes, you can also use it for single columns, so let's see what
designs users will come up with.

\startlines
Hans Hagen
Mikael Sundqvist
\stoplines

\stopchapter

% \iffalse

\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 \quote {mixed columns} mechanism has been introduced that will be
developed further and eventually replace the old multi column handler. Another
multi columns mechanism is called \quote {page columns} which basically is
treating each column as a page which in turn means that we can support for
instance side floats. Then there are \quote {column sets} that can be used to
construct pages with a more complex layout. 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 column sets.
As mentioned in the introduction the variant in \MKXL\ (aka \LMTX) is not
entirely compatible with the one in \MKII\ and \MKIV. We considered keeping the
old variant as option but eventually moved that to the \type {oldcolumnsets}
module. That means that this manual differs a bit from the manual meant for the
older variant. \footnote {The actually is also an alternative single column
\quote {page layout} mechanism that supports plugins, for instance a \type
{\bTABLE} based makeup, but that's not really a different output routine.}

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{mvlcolumnsets-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{mvlcolumnsets-001}

These pages were typeset with the following code:

\ShowFile{mvlcolumnsets-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{mvlcolumnsets-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{mvlcolumnsets-002}

This time the input is:

\ShowFile{mvlcolumnsets-002}

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

\SixPages{mvlcolumnsets-002}

\page[mine]

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

\FourSpread{mvlcolumnsets-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{mvlcolumnsets-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{mvlcolumnsets-004}

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

\ShowFile{mvlcolumnsets-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{mvlcolumnsets-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{mvlcolumnsets-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{mvlcolumnsets-006}

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

\ShowFile{mvlcolumnsets-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{mvlcolumnsets-007}

\ShowFile{mvlcolumnsets-007}

\page[mine]

Be aware of the fact that we start at the beginning of the column set. In the old
approach we flushed slotwise but because we now flush the whole mvl stream, these
spans behave different. You can however use a subcolumnset and do an intermediate
balance and then position a next span.

\FourSpread{mvlcolumnsets-008}

\ShowFile{mvlcolumnsets-008}

\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{mvlcolumnsets-101}

\ShowFile{mvlcolumnsets-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{mvlcolumnsets-102}

The prefered location is passed as a four character directive:

\ShowFile{mvlcolumnsets-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{mvlcolumnsets-103}

\ShowFile{mvlcolumnsets-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{mvlcolumnsets-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{mvlcolumnsets-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{mvlcolumnsets-202}

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

\ShowFile{mvlcolumnsets-202}

\page[mine]

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

\FourSpread{mvlcolumnsets-203}

\ShowFile{mvlcolumnsets-203}

\page[mine]

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

\FourSpread{mvlcolumnsets-204}

Watch how we explicitly go to a left page.

\ShowFile{mvlcolumnsets-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[mvlcolumnsets-204.tex][page=2]}}}
  {left page}
  {\scale[width=.4\textwidth]{\clip
     [nx=2,ny=6,x=1,y=2]
     {\typesetfile[mvlcolumnsets-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[mvlcolumnsets-205.tex][page=2]}}}
  {left page}
  {\scale[width=.4\textwidth]{\clip
     [nx=2,ny=6,x=1,y=2]
     {\typesetfile[mvlcolumnsets-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{mvlcolumnsets-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{mvlcolumnsets-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{mvlcolumnsets-301}
%
% This example demonstrates that you can supply \type {\column} with explicit
% directives.
%
% \ShowFile{mvlcolumnsets-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{mvlcolumnsets-401}

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

\ShowFile{mvlcolumnsets-401}

\page[mine]

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

\FourSpread{mvlcolumnsets-402}

This time we used equal distances:

\ShowFile{mvlcolumnsets-402}

\page[mine]

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

\FourSpread{mvlcolumnsets-403}

In code:

\ShowFile{mvlcolumnsets-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{mvlcolumnsets-404}

In code:

\ShowFile{mvlcolumnsets-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{mvlcolumnsets-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{mvlcolumnsets-405}

% \page[mine]

\stopchapter

\startchapter[title=Directions]

\FourSpread{mvlcolumnsets-601}

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

\ShowFile{mvlcolumnsets-601}

% \page[mine]

\stopchapter

\startchapter[title=Backgrounds]

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

\FourSpread{mvlcolumnsets-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{mvlcolumnsets-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{mvlcolumnsets-702}

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

\ShowFile{mvlcolumnsets-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{mvlcolumnsets-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{mvlcolumnsets-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{mvlcolumnsets-704}

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

\ShowFile{mvlcolumnsets-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{mvlcolumnsets-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{mvlcolumnsets-901}

\page[mine]

\FourSpread{mvlcolumnsets-902}

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

\ShowFile{mvlcolumnsets-902}

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

\stopchapter

\startchapter[title=Notes]

Notes are implemented using inserts and these are collected per column (slot).
Keep in mind that the splitter optimized over pages so we get an average optimal
result. If you use very large and many notes the results can be disappointing in
which case you should consider using end notes.

\EightSpread{mvlcolumnsets-1010}

\page[mine]

Top and bottom notes also use inserts.

\EightSpread{mvlcolumnsets-1011}

\stopchapter

\startchapter[title=Commands]

This manual doesn't show some of the more subtle details, like how half line
spacing carries over slots and how for instance figures can be places on future
spreads. Slot crossing content that can be discarded is also not shown here. We
use the low level mvl and balancing features provided by the engine, do much of
the management in \LUA, while the optimizing loops happen in \TEX. We could more
more to \LUA\ but this way we can test the new primitives and performance is
fine. It also makes for better (visual) tracing.

When you set up a document using columns sets it might be that you want to
generate a version without doing so, just using the regular, single column, page
builder routine. In that case some commands that relate to column sets are
ignored, others just process the content that they wrap.

\starttabulate[|l|l|]
\FL
\NC \type{\definecolumnset}            \NC obeyed    \NC \NR
\NC \type{\setupcolumnset}             \NC obeyed    \NC \NR
\NC \type{\startcolumnset}             \NC processed \NC \NR
\ML
\NC \type{\setupcolumnsetlines}        \NC ignored   \NC \NR
\NC \type{\setupcolumnsetstart}        \NC ignored   \NC \NR
\ML
\NC \type{\definecolumnsetarea}        \NC obeyed    \NC \NR
\NC \type{\setupcolumnsetarea}         \NC obeyed    \NC \NR
\NC \type{\setupcolumnsetareatext}     \NC ignored   \NC \NR
\ML
\NC \type{\reservecolumnset}           \NC ignored   \NC \NR
\NC \type{\setcolumnset}               \NC ignored   \NC \NR
\NC \type{\startsetcolumnset}          \NC ignored   \NC \NR
\NC \type{\emptycolumnset}             \NC ignored   \NC \NR
\NC \type{\blockcolumnsetrows}         \NC ignored   \NC \NR
\ML
\NC \type{\startcolumnsetspan}         \NC ignored   \NC \NR
\NC \type{\columnsethspan}             \NC adapted   \NC \NR
\NC \type{\columnsetspanwidth}         \NC adapted   \NC \NR
\ML
\NC \type{\startcolumnsetsheet}        \NC processed \NC \NR
\NC \type{\startcolumnsetsheetdelayed} \NC processed \NC \NR
\NC \type{\startcolumnsetspreadsheets} \NC processed \NC \NR
\ML
\NC \type{\definesubcolumnset}         \NC obeyed    \NC \NR
\NC \type{\setupsubcolumnset}          \NC obeyed    \NC \NR
\NC \type{\startsubcolumnset}          \NC processed \NC \NR
\ML
\NC \type{\flushcolumnset}             \NC ignored   \NC \NR
\NC \type{\flushsubcolumnsets}         \NC ignored   \NC \NR
\NC \type{\processcolumnset}           \NC ignored   \NC \NR
\NC \type{\balancesubcolumnset}        \NC ignored   \NC \NR
\ML
\NC \type{\startwidecolumnset}         \NC processed \NC \NR
\LL
\stoptabulate

When you set up a style for column sets the first thing to do is to define one.
The content then goes between the start and stop command. Setting up start and
lines can be done per sheet. Special content like graphics can be put on sheets
beforehand or in the flow. Keep in mind that the content is collected, but that
sheet and spread specifications are applied immediately.

Some commands, like flushing and balancing, assume that sub column sets are used
and these need to be set up beforehand. Columns can have a different width and a
sub stream uses that but mixing different widths for the same stream doesn't work
out well.

The \type {\page} command accepts \type {yes}, \type {slot}, \type {here} and
\type {force}, and the \type {\column} command handles \type {yes} and \type
{spread}. Keep in mind that because we process the content for all slots in one
go, we don't know actually know where we are. These commands puts signals in the
stream and these can interfere with spacing, although when you use them you
probably don't expect spacing there anyway and vertical space is discarded when
we cross a slot.

When a column set is active a mode is set, so for instance the \type {example}
column set uses in this manual has a mode \typ {columnset:example} that gets set
or unset depending on the \type {state} parameter being \type {start}.

The in-stream float placement handles \type {here}, \type {force}, \type {top}
and \type {bottom} but also specific slot placement but in that case you flush on
the spot. Floats that can be places will be delayed and end up after the column
set is done.

\stopchapter

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

% mvlcolumnsets-301.tex % \page \column
%
% mvlcolumnsets-801.tex % balancing
% mvlcolumnsets-802.tex % balancing
% mvlcolumnsets-803.tex % balancing
% mvlcolumnsets-804.tex % balancing
% mvlcolumnsets-805.tex % balancing
% mvlcolumnsets-806.tex % balancing

\stopdocument
