Difference between revisions of "Setups"

From Wiki
Jump to navigation Jump to search
(First draft)
 
Line 1: Line 1:
== Setups ==
+
In ConTEXt, setups are a rather common variant on macros. Setups have two useful properties:
  
In ConTeXt it is easy to create local variables and grouping. Local variables can be simulated as in:
+
* 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 {{cmd|space}}, {{cmd|crlf}}, {{cmd|par}}, etc.
  
 +
* If you call the setup inside a {{cmd|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 ==
 +
 +
* {{cmd|startsetup| mysetup}} begins a setup definition
 +
* {{cmd|setup|[mysetup]}} invokes a setup.
 +
 +
== Examples ==
 +
 +
 +
Here are two simple examples:
 +
{{Multicol}}
 +
<texcode width=50%>
 +
% Create two setups
 +
\startsetup doc:print
 +
    \setuppapersize[A4][A4]
 +
\stopsetup
 +
 +
\startsetup doc:screen
 +
    \setuppapersize[S6][S4]
 +
\stopsetup
 +
 +
% Use one or another setup
 +
\doifmodeelse {paper} {
 +
    \setup[doc:print]
 +
} {
 +
    \setup[doc:screen]
 +
}
 +
</texcode>
 +
{{Multicol-break}}
 
<texcode>
 
<texcode>
\startsetups whatever
+
% Set up a headertext. Whitespace is ignored
% some useful definitions here
+
\startsetup[doc:header]
\stopsetups
+
    \marking[chapter]
 
+
    \space
\definestartstop[whatever][commands=\setups{whatever}]
+
    --
 +
    \space
 +
    \pagenumber
 +
\stopsetup
  
\startwhatever
+
% Use the setup
Using definitions here.
+
\setupheadertexts[\setup{doc:header}]
\stopwhatever
 
 
</texcode>
 
</texcode>
 +
{{Multicol-end}}
  
But 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):
+
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):
  
 
<texcode>
 
<texcode>
Line 35: Line 68:
 
\starttext
 
\starttext
 
\startsetups settest
 
\startsetups settest
\def\command{do something with}
+
    \def\command{do something with}
I want to \command{} command.
+
   
 +
    I want to \command{} my command.
 
\stopsetups
 
\stopsetups
  
 
\start
 
\start
\setups{settest}
+
    \setups{settest}
 
\stop
 
\stop
  
Line 68: Line 102:
 
To give you the idea, try this example.
 
To give you the idea, try this example.
  
The <tt>set</tt>-part is called
+
* When you initialize the namespace, the setups assigned to {{code|set}} are called.
* '''right after''' the definition of the namespace (initialisation) and
 
* '''after''' a value is assigned to a variable.
 
The <tt>reset</tt>-part is called
 
* '''right after''' any assignment, but still in front of the <tt>set</tt>-part.
 
  
<texcode>
+
* When you assign a variable to the namespace, first the setup in {{code|reset}} is called, and then the setup in {{code|set}}.
\setupoutput[pdftex]
 
  
 +
<context source=yes>
 
\startsetups namespace:set
 
\startsetups namespace:set
%
+
    % Print message to log and to document
\writestatus{VARIABLES}{namespace:set is beeing called..}%
+
    \writestatus{VARIABLES}{namespace:set is being called..}%
\ {\green [namespace:set]}
+
    \space{\green [namespace:set]}
  % whatever must be done with your variables after you assign a value
+
    \def\applecolor{red}
  %
+
    % whatever must be done with your variables after you assign a value
  % (initialisation with defaults,..)
+
    % (initialisation with defaults,..)
 
\stopsetups
 
\stopsetups
  
 +
\startsetups namespace:reset
 +
  % Print message to log and document
 +
  \writestatus{VARIABLES}{namespace:set is being called..}%
 +
  \space{\red[namespace:reset]}
  
\startsetups namespace:reset
 
%
 
\writestatus{VARIABLES}{namespace:set is beeing called..}%
 
\ {\green [namespace:reset]}
 
 
   % whatever must be done after an assignment (verification, calculation,..)
 
   % whatever must be done after an assignment (verification, calculation,..)
 
\stopsetups
 
\stopsetups
Line 98: Line 128:
 
\setvariables[namespace]
 
\setvariables[namespace]
 
   [set={\setups[namespace:set]},
 
   [set={\setups[namespace:set]},
 +
  key={Apples are \applecolor!},
 
   reset={\setups[namespace:reset]},
 
   reset={\setups[namespace:reset]},
 
   ]
 
   ]
Line 114: Line 145:
  
 
\stoptext
 
\stoptext
 
+
</context>
</texcode>
 

Revision as of 14:37, 16 May 2013

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

Examples

Here are two simple examples:

% Create two setups
\startsetup doc:print
    \setuppapersize[A4][A4]
\stopsetup

\startsetup doc:screen
    \setuppapersize[S6][S4]
\stopsetup

% Use one or another setup
\doifmodeelse {paper} {
    \setup[doc:print]
} {
    \setup[doc:screen]
}
% Set up a headertext. Whitespace is ignored
\startsetup[doc:header]
    \marking[chapter]
    \space
    --
    \space
    \pagenumber
\stopsetup

% 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{\green [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:set 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