Understanding conditional page background in ConTeXt

Question

How does the following code work? Source: discussion on the mailing list

\setuplayout
  [header=0cm,
   topspace=1.625cm,
   footer=0cm,
   width=fit,
   height=fit]

\startMPinclusions
  numeric MyTitlePageDone[] ;
\stopMPinclusions

\startuseMPgraphic{background:normal}
  StartPage ;
  fill
    (topboundary Page --cycle) enlarged(0,5mm) shifted (0,-5mm)
    withcolor \MPcolor{color:background:\namedstructureuservariable{chapter}{mycolor}} ;
  StopPage ;
\stopuseMPgraphic

\defineoverlay
  [background:normal]
  [\useMPgraphic{background:normal}]

\startuseMPgraphic{background:title}
  if unknown MyTitlePageDone.\namedstructureuservariable{chapter}{mycolor} :
    StartPage ;
    fill ((topboundary Page --cycle) enlarged(0,5mm))
      shifted (0,-20mm)
      withcolor \MPcolor{color:title:\namedstructureuservariable{chapter}{mycolor}} ;
    StopPage ;
    MyTitlePageDone.\namedstructureuservariable{chapter}{mycolor} := 1 ;
  fi ;
\stopuseMPgraphic

\defineoverlay
  [background:title]
  [\useMPgraphic{background:title}]

\setupbackgrounds
  [page]
  [background={background:normal,background:title}]

\definecolor [color:title:one]      [r=0.86,g=0.88,b=0.76]
\definecolor [color:background:one] [.9(color:title:one)]

\definecolor [color:title:two]      [g=0.86,r=0.88,b=0.76]
\definecolor [color:background:two] [.9(color:title:two)]

\starttext

\startchapter[title=One][mycolor=one]
  \input tufte \page
  \input knuth
\stopchapter

\startchapter[title=Two][mycolor=two]
  \input tufte \page
  \input knuth
\stopchapter

\stoptext

Why are the backgrounds being applied conditionally? Why isn't the title page background applied to normal pages? In the code there doesn't seem to be any conditionals or checks to check the page type. The title background also gets applied to cover pages implemented via \startstandardmakeup, but gets a black color instead since the user variable isn't defined.

Some help in understanding this code is much appreciated.

Answer 1

Let's walk through the code. I skip the parts that are not relevant for understanding the conditional processing. First an empty MetaPost array is created.

\startMPinclusions
  numeric MyTitlePageDone[] ;
\stopMPinclusions

Now comes the part that actually prints the colourful bar underneath the chapter head.

\startuseMPgraphic{background:title}
  if unknown MyTitlePageDone.\namedstructureuservariable{chapter}{mycolor} :
    StartPage ;
    fill ((topboundary Page --cycle) enlarged(0,5mm))
      shifted (0,-20mm)
      withcolor \MPcolor{color:title:\namedstructureuservariable{chapter}{mycolor}} ;
    StopPage ;
    MyTitlePageDone.\namedstructureuservariable{chapter}{mycolor} := 1 ;
  fi ;
\stopuseMPgraphic

Let's simplify this code a little more:

\startuseMPgraphic{background:title}
  if unknown MyTitlePageDone.\namedstructureuservariable{chapter}{mycolor} :
    %%
    %% code for printing colourful bar skipped
    %%
    MyTitlePageDone.\namedstructureuservariable{chapter}{mycolor} := 1 ;
  fi ;
\stopuseMPgraphic

The macro \namedstructureuservariable{chapter}{mycolor} expands to the argument of the variable mycolor of the second argument provided to the \startchapter command, which is one in this case:

\startchapter[title=One][mycolor=one]

This means the line

if unknown MyTitlePageDone.\namedstructureuservariable{chapter}{mycolor} :

eventually becomes

if unknown MyTitlePageDone.one ;

which is a way to address the array element one in MetaPost. At each new chapter this condition evaluates to true since MyTitlePageDone[one] is indeed unknown. It has never been set before. The following code draws the colourful bar until this code is reached:

MyTitlePageDone.\namedstructureuservariable{chapter}{mycolor} := 1 ;

which becomes

MyTitlePageDone.one := 1 ;

and thus defines this array element. The number is not relevant since it's checked for unknown, not a particular value. On the next page the conditional

if unknown MyTitlePageDone.one ;

evaluates to false since this value is known (it was set to one on the previous page) and the code printing the bar is skipped.

This code relies on the fact that every chapter has a unique colour. Try what happens if you select the same colour for different chapters (use the mycolor= setting) and walk through the code again to find out why.