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

\startcomponent text-103

\environment text-000

\start \setuphead [chapter] [after=]

\chapter {Backgrounds behind text}

\setuptextbackground
  [mp=mpos:par:columnset,
   method=mpos:par:columnset]

\startbuffer[setup-a]
\definetextbackground[intro]
  [backgroundcolor=infogray, 
   backgroundoffset=.25cm, 
   offset=.5cm,
   frame=off,
   location=paragraph,
   color=white]
\stopbuffer

\startbuffer[setup-b]
\definetextbackground[subintro]
  [backgroundcolor=textgray, 
   backgroundoffset=0pt, 
   offset=0pt,
   frame=off,
   location=text,
   color=blue]
\stopbuffer

\startbuffer[demo-a]
\starttextbackground[intro]
A rather common way to draw attention to a passage, is to add
a background. In this chapter we will therefore discuss how 
to enhance your document with \starttextbackground [subintro] 
colorful areas that either or not follow the shape of your 
paragraph. \stoptextbackground\ Be warned: this chapter has 
so many backgrounds that you should consider wearing sunglasses.
\stoptextbackground
\stopbuffer

\getbuffer[setup-a,setup-b,demo-a]

\blank

In the previous paragraph we demonstrated two important
features of the background handler: you can nest
backgrounds and backgrounds can be tight or wide. Features
like this will often be used in combination with others,
like special section headers. The raw coding of the
previous paragraph is therefore not representative. 

\typebuffer[demo-a]

The outer background commands were defined as follows: 

\typebuffer[setup-a]

Here, the \type {paragraph} option ensures that the 
background covers the width of the body text. The inner 
background is defined in a similar way, but this time we 
choose \type {text} placement. 

\typebuffer[setup-b]

In this document we use protruding characters (hanging 
punctuation) so we've chosen a rather large offset, one that
also matches the rest of the page design. 

Those who are familiar with the way \TEX\ works will 
probably see what problems can occur with backgrounds like 
this. What happens for instance when we cross page 
boundaries, and how will more complicated paragraph shapes 
be handled? 

The current implementation tries to handle page breaks and 
paragraph shapes as good as possible. This works well in 
normal one||column mode and columnsets. 

\startbuffer[setup-c]
\definetextbackground [A] [backgroundcolor=infogray]
\definetextbackground [B] [backgroundcolor=textgray]

\setuptextbackground
  [backgroundoffset=0pt, 
   offset=0pt,
   frame=off,
   location=text]
\stopbuffer

\getbuffer[setup-c]

\startbuffer[demo-b]
\placefigure[left]{none}{\externalfigure[detcow][width=2cm]}

\starttextbackground [A] In this example, the paragraph shape 
is determined by the graphic placed left of the text.
\starttextbackground [B] This feature is implemented using the 
\type {\hangindent} and \type {\hangafter} primitives, which 
means that we need to keep track of their state. In addition, 
we need to handle the indentation directives \type {\leftskip}, 
\type {\rightskip} and \type {\parindent}.  \stoptextbackground\ 
Because backgrounds end up in a different background overlay, 
nesting them is no problem, and it is even possible to move 
them to the front and back, as we will demonstrate in a few 
lines. \stoptextbackground 
\stopbuffer 

{\setupalign[nothanging]\getbuffer[demo-b]\par} 

\typebuffer[demo-b]

The backgrounds were defined as: 

\typebuffer[setup-c]

\startbuffer[setup-d]
\setuptextbackground [B] [backgroundcolor=green,level=+2]
\stopbuffer

{\setupalign[nothanging]\getbuffer[setup-d,demo-b]\par} 

This time we moved the inner background a few levels up. By
default they reside at \type {level=-1}. This way, by using
a non transparent color, we can hide information. 

\typebuffer[setup-d]

Unless you mess around too much with boxes, backgrounds work 
as expected in most situations. According to the 
Merriam||Webster on the authors laptop: 

\startbuffer
\starttabulate[|l|p|l|]
\NC background \NC \starttextbackground [A] the part of a 
    painting representing what lies behind objects in the 
    \starttextbackground [B] foreground \stoptextbackground 
    \stoptextbackground \NC one \NC \NR 
\TB [halfline]
\NC foreground \NC \starttextbackground [A] the part of a 
    scene or representation that is nearest to and in front 
    of the \starttextbackground [B] spectator 
    \stoptextbackground \stoptextbackground \NC two \NC \NR 
\TB [halfline]
\NC spectator \NC  \starttextbackground [A] one who looks 
    on or watches \stoptextbackground \NC three \NC \NR 
\stoptabulate
\stopbuffer

\getbuffer

This is coded similar to normal running text. A table like
this is in a way still part of the text flow. As floating body
(see \in {table} [tab:back]) it can virtually end up
everywhere. 

\placetable 
  [here] [tab:back] 
  {} {\hsize.75\textwidth\getbuffer}

\start 

  \definefloat[mytable][table]
  \setupfloat[mytable]
    [leftmargindistance=-\innermargintotal]

  \placemytable 
    [left,high,low] [tab:back-m] 
    {} {\hsize.5\textwidth\getbuffer}

  Keeping track of the state of a paragraph in a table in 
  combination with background is not entirely trivial. The 
  current implementation evolved from less clever ones and, 
  unless you start doing complicated box manipulations with 
  the float content, works quite well. One reason why we 
  made backgrounds work in tables (and especially floating 
  tables) is that is was needed for typesetting books for 
  primary and secundary education. In there, we want to be 
  able to hide the answers that students are supposed to 
  fill in. 

  \flushsidefloats 

\stop

\startbuffer
\startcombination[3*1]
  {\externalfigure[back-4.pdf][page=1,width=.3\textwidth]}{Page 1}
  {\externalfigure[back-4.pdf][page=2,width=.3\textwidth]}{Page 2}
  {\externalfigure[back-4.pdf][page=3,width=.3\textwidth]}{Page 3}
\stopcombination
\stopbuffer

In \in {figure} [fig:columns] you can see an advanced
example of backgrounds running over columns. If you look
carefully, you will notice that the background depends on 
the kind of background at hand: 

\startitemize[n,packed]
\item the text starts and flows on 
\item the text flows on (or stands alone) 
\item the text flows on and ends 
\stopitemize

This information is available when you want to draw your own 
backgrounds. Here the graphic was defined as follows: 

\placefigure [hier] [fig:columns] {} {\getbuffer}

\starttyping
\startuseMPgraphic{mpos:par:columnset:shade}
  path p, q, r ; numeric h ; 
  for i=1 upto nofmultipars : 
    p := multipars[i] ;
    q := multipars[i] topenlarged    -.5h ;
    r := multipars[i] bottomenlarged -.5h ;
    h := bbheight(p) ; 
    if     multilocs[i] = 1 : 
      linear_shade(p,8,boxfillcolor,white) ; 
    elseif multilocs[i] = 2 : 
      linear_shade(q,8,boxfillcolor,white) ; 
      linear_shade(r,8,white,boxfillcolor) ; 
    else :
      linear_shade(p,8,white,boxfillcolor) ; 
    fi ;
  endfor ; 
\stopuseMPgraphic
\stoptyping

This graphic is hooked into the background setup by setting 
the \type {mp} variable. 

\starttyping
\definetextbackground
  [shade]
  [location=paragraph,
   backgroundcolor=shadecolor,
   mp=mpos:par:columnset:shade,
   methode=mpos:par:columnset,
   leftoffset=\topskipgap,
   before=\blank,
   after=\blank]
\stoptyping


\noindent todo: parameters 

\noindent todo: moving up/down in layout stack 

\noindent todo: default fills/line options  


\page \stop

\stopcomponent
