Terminology

This is a proposal on how to name things in GraceTMPL. It's work in progress, so stay tuned.

Variable

A variable is a value with a name and can be set by the application within a certain environment

Environment

is the context for a number of variables. Environments can be organized in a treelike structure, i.e. each environment may have one other environment where it resides in and a number of other environments which reside in it.

Variable substitution

is the action where a certain variable name with an optional context name and fallback value are used to produce a new value. For this, the current environment is searched for a variable with the specified name. If the first part of the given context matches one of the child environments, the variable is searched in the corresponding environment. If this lookup doesn't yield a value (even an empty string is a value!) the parent environment is asked for substitution. If we should end with no successful lookup at all, the fallback value is returned, if one was given. If it was omitted, the resulting string will be a description of the variable specification to allow for template debugging

Variable expansion

operates on a string which may contain any number of variable specifications which are parsed for context, variable name and fallback string. With these informations, the variable specification is replaced by the result of the variable substitution.

Variable specification

is a string which addresses a variable within a certain context and may contain a fallback value. Valid variable specifications are (within quotes):

• "$NAME"
• "${NAME}"
• "${NAME:}" (here, the fallback is "")
• "${NAME:FALLBACK}"
• "${CONTEXT::NAME}"
• "${CONTEXT1::CONTEXT2::NAME}"
  ...

Protected graph

is a graph to which the application cannot add data. The application will not even know the graph is there. It doesn't appear in the requestinfo and also doesn't add to the graphs-per-page count. Even so, it will be processed when producing output files, literal data is taken as found in the template and copy-data-sets will be copied. Variable expansion is fully functional but there (naturally) are no variables set in the graph. A graph can be marked a protected graph by adding two spaces (" ") to the front and the end of the graph's subtitle. If the subtitle is otherwise empty, this makes four spaces.

Literal-data

is a dataset which appears in the template and is literally passed to the output file. It's invisible to the application, i.e. it does not appear in the requestinfo list and cannot be changed or overwritten by the application. Variable expansion works, however, though (naturally) no variables can be set within the literal-data-set. Graph autoscaling is turned off for literal data.

When "-set" is omitted, the data itself is referred to, otherwise all additional information, like legend string, formats, etc. are included.

Literal-data-sets are marked by adding "$!" to the end of their legend string.

Copy-data

is a dataset which gets its data by copying that of another data set. The source data must have been produced by the application, i.e. it must not be literal-data or copy-data. The copy-data-set itself is invisible to the application, i.e. it does not appear in the requestinfo list and cannot be changed or overwritten by the application (in this regard it's very similar to literal-data-sets). As with literal-data-sets, variable expansion works, though (naturally) no variables can be set by the application.

When "-set" is omitted, the data itself is referred to, otherwise all additional information, like legend string, formats, etc. are included.

Data can be copied by adding a special string to the destination set's legend string, namely "$'<gX.sY" or "$=<gX.sY" (as described in detail above)

Autoscaling

is done to adjust a graph's axis ranges to show all of the data the application provides. The only kind of data not taken into account is literal data. GraceTMPL's autoscale function works somewhat different from the one XmGrace provides, the emphasis is on displaying as much data as possible, not on prettifying the axis range (this is no insult on the XmGrace autoscale policy!). Autoscaling is turned on for each axis by default and can be turned off explicitely by adding two spaces (" ") to the front and the end of the axistitle. If the axistitle is otherwise empty, this makes four spaces.

---