Setups

In ConTeXt, setups are a rather common variant on macros. Setups have two useful properties:

• Spaces inside setups are ignored. This means that you can format the setup's contents with spaces and linebreaks for maximum readability, instead of having to write a dense macro or, worse, a long in-place definition. You can explicitly request spaces with \space, \crlf, \par, etc.

• If you call the setup inside a \start (just 'start') environment, any definitions made by that setup remain inside that group. This lets you define macros in a setup, and then call the setup inside a group to use the macros as 'local macros' of sorts.

Commands

• \startsetups mysetup begins a setup definition (with optional brackets around mysetup)
• \setup[mysetup] or \setups[mysetup] invokes a setup or even several as a list.
• There’s also \directsetup{mysetup} and \fastsetup{mysetup}, these were faster in MkIV but make no sense any more in LMTX. Both take just one setup name and do less error checking.

Examples

Here are two simple examples:

% Create two setups \startsetups doc:print \setuppapersize[A4][A4] \stopsetups \startsetups doc:screen \setuppapersize[S6][S4] \stopsetups % Use one or another setup \doifmodeelse {paper} { \setup[doc:print] } { \setup[doc:screen] }

% Set up a headertext. Whitespace is ignored \startsetups[doc:header] \marking[chapter] \space -- \space \pagenumber \stopsetups % Use the setup \setupheadertexts[\setup{doc:header}]

You can place setups almost everywhere and environment will not be affected by their execution. It is useful to wrap overlay definitions and such in setups as in (copied from Colorful_CD_Inlay page):

\defineoverlay [origin] [\setups{origin}]

\startsetups origin
    \vbox to \overlayheight {
        \vfill\tfxx\setstrut
        \hsize\overlaywidth
        \hfill Fiona Apple\enspace EM\enspace2005\quad\strut\endgraf
        \kern1ex
    }
\stopsetups

You can even do things like:

\starttext
\startsetups settest
    \def\command{do something with}
    
    I want to \command{} my command.
\stopsetups

\start
    \setups{settest}
\stop

\command aaa  % will give "undefined control sequence" error

\stoptext

Using setups for namespaces

Using \setups for a variable namespace allows an easier control over the containing variables. All you have to do is to define the setups namespace:set and/or namespace:reset for a given namespace. Now every time a variable of that namespace is assigned (written), ConTeXt automatically calls these setups. Reading of variables is totally unaffected by these settings. A possible use are default values, calculations and even verification.

So once you have 'setup' your variables proper, you don't have to worry about unset variables and alike any more. Also changes can be made easy, as there is only one common setup. The drawback is the slower speed in use, as every assignment to a variable calls these setups.

To give you the idea, try this example.

• When you initialize the namespace, the setups assigned to set are called.

• When you assign a variable to the namespace, first the setup in reset is called, and then the setup in set.

\startsetups namespace:set
    % Print message to log and to document
    \writestatus{VARIABLES}{namespace:set is being called..}%
    \space{\blue[namespace:set]}
    \def\applecolor{red}
    % whatever must be done with your variables after you assign a value
    % (initialisation with defaults,..)
\stopsetups

\startsetups namespace:reset
  % Print message to log and document
  \writestatus{VARIABLES}{namespace:reset is being called..}%
  \space{\red[namespace:reset]}

  % whatever must be done after an assignment (verification, calculation,..)
\stopsetups


% \setups[namespace:set] is automatically called right after 'set' is assigned
\setvariables[namespace]
  [set={\setups[namespace:set]},
   key={Apples are \applecolor!},
   reset={\setups[namespace:reset]},
  ]

% watch for the colors
\setupcolors[state=start]

\starttext
\hairline
{\bf reading has no effect\par}
{\tt Calling \type{\getvariable{namespace}{key}}...\getvariable{namespace}{key}}

\blank
{\bf writing calls reset and set\par}
{\tt Calling \type{\setvariables[namespace][key=value]}...\setvariables[namespace][key=value]}

\stoptext