ConTeXt: What are alternatives and rendering setups?

Question

I've seen the alternative keyword used throughout ConTeXt:

• \setuppagenumbering[alternative=doublesided]
• \setupheads[alternative=inmargin]
• \setuplist[section][alternative=d]

I assumed that it was just a popular keyword: an enumeration hardcoded into each macro definition, like:

def setuplist(alternative="a", ...):
    if alternative == "a":
        doAlternativeA
    elif alternative == "b":
        doAlternativeB
    elif alternative == "c":
        doAlternativeC
    elif alternative == "d":
        doAlternativeD

However the answer to ConTeXt: avoid enumeration items across pages defines a completely new alternative. This implies that alternatives in ConTeXt are a generic macro hook rather than per-macro keywords.

\defineuserdataalternative
  [itemize]
  [renderingsetup=userdata:itemize]

\defineuserdata [item] [alternative=itemize]

So what does the alternative keyword mean? At what stage is it used or called? What is its scope; what does it do?

Then there is the renderingsetup keyword for which I have the same questions. Is it specific to only a subset of ConTeXt macros or is it a generic macro hook? I assume it allows modification of the underlying TeX code before page rendering starts. How does that differ from the usual command= keyword? Why must it be defined via an alternative rather than directly?

Answer 1

The alternative keyword is commonly used to select between different pre-defined renderings of an element in ConTeXt. For example \setuphead[chapter][alternative=middle] will render chapter titles horizontally centered.

Is it specific to only a subset of ConTeXt macros or is it a generic macro hook?

Now of course, an alternative requires an implementation which performs the actual rendering. This is called a rendering setup and should be hidden from the user. In principle, the alternative keyword could select an implementation without the detour via the rendering setup but that would make it much harder to extend. Hence the modular approach was chosen. A rendering setup is not generic. For example a rendering setup which was written for a \setuphead alternative cannot be used with \setupitemize. Most setups which offer selection of an alternative support rending setups (exceptio probat regulam).

How does that differ from the usual command= keyword?

The reason why it is superior to command= is that the rendering setup this completely transparent for the user. Imagine a module which defines additional alternatives for \setupitemize. A user can now use them by simply knowing the additional alternative names. It therefore blends nicely into the existing interface and “feels” consistent.

Why must it be defined via an alternative rather than directly?

There is no rule that it has to but as I already outlined, it “feels” more consistent. It probably also makes your code more readable and makes it easier to maintain.