2.5. Variables

2.5.1. Introduction

A variable is a named value. Document-wide settings are controlled in SDF using variables. Likewise, authors can define and access their own variables. In either case, the value of a variable can be referenced in a paragraph by delimiting it with the special symbols [[ and ]].

For example:

  !define MY_EMAIL 'abc@xyz.com'
  My electronic mail address is [[MY_EMAIL]].

The result is:

My electronic mail address is abc@xyz.com.

2.5.2. Commonly used system variables

Some commonly used system variables are:

Variable	Description
Options:
OPT_LOOK	the overall look (e.g. simple, fancy)
OPT_STYLE	the general type (e.g. memo, manual)
Titles:
DOC_NAME	the title, excluding the type (e.g. SDF)
DOC_TYPE	the title type (e.g. User Guide)
DOC_AUTHOR	the author
DOC_TOC	the number of heading levels in the table of contents

2.5.3. Setting variables

Variables can be set via:

the define macro
the default macro
the init macro
sdf's command line.

To undefine a variable, use the undef macro.

2.5.4. The Define macro

Variables are usually set in SDF by using the define macro. The format is:

   !define symbol [expression]

Examples are:

   !define LONG
   !define VERSION "1.002"

symbol is a sequence of letters, digits and underscore. If expression is omitted, the default value is 1.

2.5.5. The Default macro

It is often a good idea to only define a variable if it does not already have a value. To do this, use the default macro. The format is:

   !default symbol [expression]

For example:

   !default VERSION "1.002"

symbol is a sequence of letters, digits and underscore. If expression is omitted, the default value is 1.

2.5.6. The Init macro

Generally speaking, the first thing sdf does is to load the standard library (stdlib.sdm). However, if the first line of an SDF document is the init macro, the nominated variables are initialised before the standard library is loaded. This allows an SDF document to initialise variables used within the standard library. The format of the init macro is:

   !init name1["="expression1]";" name2["="expression2] ...

For example:

   !init OPT_STYLE="memo"

Note: Certain variables cannot be set after the standard library is loaded. These variables can only be set via sdf's command line or via the init macro.

2.5.7. Using the command line

It is occasionally useful to set variables via sdf's -D option. Multiple definitions can be separated by commas. For example:

   sdf -DLONG,VERSION="1.002" ...

Alternatively, the option can be repeated. For example:

   sdf -DLONG -DVERSION="1.002" ...

In either case, if a value is not specified for a variable, 1 is assumed.

Note: Variables set on the command line override the values set by the init macro.