The CollageSystem expects its input in a single plain text file that can be
created using any standard ASCII editor.
The notation of the syntax below uses
some kind of Backus-Naur-Form where most Nonterminals have hypertext
links to their definitions. Terminals represent the text that
has actually to be typed into the file.
Before the input file is presented to the parser of the CollageSystem,
it is preprocessed by the program cpp, the text preprocessor
of the C and C++ languages. The function of the preprocessor is documented in detail under the cpp or cc manpages. Here's a short summary of what it does:
# (number sign) is expected
to be followed by a preprocessor command, such as if, else, endif or define.
#define can be used to define all kinds of makros, i.e. for
constant definitions or even simple functions. Some examples:
#define pi 3.1415269 pi is replaced by 3.1415269.
#define quad(x) ((x)*(x)) quad(4) is replaced by ((4)*(4)) and this, in turn, is evaluated by the CollageSystem's parser in the way you would expect.
#if followed by a constant expression can be used to conditionally activate or deactivate portions of the text (conditional compilation). If the
expression evaluates to a zero value then the following text upto the next #endif is ignored so that the parser of the CollageSystem does not see it.
For example:
#define TRI 1
#if TRI
#define mypart polygon 0,0 1,0 .5,.7
#else
#define mypart polygon 0,0 1,0 1,1 0,1
#endif
If the macro TRI is defined as 1 then mypart will
be defined as a triangle. Otherwise, mypart will be a square.
#include followed by a filename enclosed in quotation marks
includes the file into the text. This can be used to split definitions over
several files and to build reusable libraries.
For example:#include "myParts.cgi"