Zonk has a single system configuration file which lives in its program directory, this is named <fn>ZonkSys</fn>.
It must have a header line as described in <ref genc>general concepts</r>.
It then contains five sections:
<ul>
<li>$static: Static variable definitions
<li>$controls: controls the way the program works
<li>$mappings: maps input datafile names to templates
<li>$trans: Transformation definitions
<li>$styles: Style definitions
</ul>
Each of these sections is delimited by the section heading listed. They are described in more detail below.
<sh>$static:</sh>
These are variable definitions in the format as detailed in <ref dlay>datafile layout</r>. However variables defined in the system file can only have one value and are therefore known as 'static'. It is useful to understand the difference between Zonk's static and dynamic mode variables as they can have subtlely different behaviour at various times, see <ref genc>general concepts</r>. Variables defined in this way are available to all templates that Zonk uses. Note though that a user variable which uses the same name will temporaily 'mask' the system variable unless a special modifier is used to access the system value (again, see <ref genc>general concepts</r> for more details).
<sh>$controls:</sh>
The current control items are:
<dl>
<dt><lit>userlog: <var>filename</var></lit><dd>Specifies where output from any <ref clog><zonk log></r> commands should be written. Should be a full filename including path.
<dt><lit>syslog:</lit><dd>Enables system logging of program (debug) information. This control <i>does not</i> take a filename. The output is always written to the file ZonkLog inside Zonk's program directory.
<dt><lit>msgnowarn:</lit><dd>Suppresses display of warning messages (though they will still be written to the system log if enabled).
<dt><lit>msgnoinfo</lit><dd>Suppresses display of most informational messages. Again they will still be written to the system log.
</dl>Note with the preceeding two items that messages generated before the config file has been read in cannot, for obvious reasons, be suppressed.
<dl>
<dt><lit>movetodir: <var>directory path</var></lit><dd>If specified then datafiles are moved from their original location into this directory once they have been successfully processed. Note that this makes use of the OS 'rename' command and therefore will fail if any of the following are true:
<ul>The destination directory does not exist
The destination directory is on a different logical device
There is already a file in the destination directory with the intended name
</ul>
Note that a failure to successfully move the datafile does <i>not</i> cause an error producing the output html.
The <i>raison d'etre</i> of this option is to help with processing whole directories of datafiles. By moving each file that has been successfully processed, should an error be found in a file, the error can be corrected and the whole directory processed again without the need to redo those files which were previously correct.
<dt><lit>USdates:</lit><dd>This control will modify the behaviour of the date parser when parsing all numeric dates. By default the parser treats these as UK format that is dd-mm-yyyy. Using this option they are treated as mm-dd-yyyy. Note that the parser will, in either case, try the alternative format if the date does not make sense in the default format.
Where <var>mapname</var> is an alphanumeric string which gives a name to this mapping. It is not actually used by the program but required to give the configuration file a consistent format.
<var>regular expression</var> is a <ref regex>Perl-compatible regular expression</r> used to match against the datafile name.
<var>filename</var> is the name of the template file to use if a match is found. If this does not include a path then the current directory needs to be set appropriately. It is also possible for the name to contain a <ref wild>'wild date'</r> element.
If a datafile contains a <ref dlay><lit>$usetemplate</lit></r> directive then any mappings are ignored. However in the absence of such a directive the datafile name is tested with each mapping in the order listed until a match is found, and then the specified template is used. Thus the most specific mapping should be given first, finishing with the most general. Should no mappings match the datafile name then an error is generated.
Where <var>transform name</var> is an alphanumeric identifier by which this transform will be referred to when needed.
<var>search expression</var> is a <ref regex>Perl-compatible regular expression</r> which the search engine will try against any given value
<var>replace expression</var> is a string to replace any match of the search expression with and may contain any of the following special sequences:
<ul>
\0 - the whole of the matched part of the value
\1 .. \9 - The match for the nth bracketed part of the search string (see the <ref regex>PCRE documentation</r> for details).
\n - insert a newline character
\r - insert a return character
\t - insert a tab character
\\ - insert a '\'
</ul>
<sh>$styles:</sh>
These take the form:
<lit><var>style name</var>: <var>style on string</var>::<var>style off string</var></lit>
where <var>style name</var> is an alphanumeric name for the style which is then used inside angle brackets within datafile values.
<var>style on string</var> is the string to insert into a value whenever <<var>style name</var>> is encountered, and the <ref ctagv>substyles</r> option has been used. This string can be made up of any combination of html directives and literal text.
<var>style off string</var> is made up the same as <var>style on string</var> except that it is substituted in wherever </<var>style name</var>> is found.
<sh>User Global files</sh>
The global file is, in most respects like the system configuration file except that you are able to specify the name of the global file to use at runtime. Variable definitions in the global file are also static and 'sit between' user and system definitions in the hierarchy. That is given the same variable name the user file has preference over the global file which has preference over the system file. Again you can <ref ctagv>force access</r> to a global value if you need to. You need not specify a global file at all if it is not required.
Some of the control options have no effect in a global file. The ones that are ignored are, <lit>$syslog, $msgnowarn, $msgnoinfo</lit>
With the other options, you cannot unset one that has been set in the system file but where it takes a parameter, you may redefine it.
You may specify $mappings in a global file but if you do then these totally replace whatever $mappings are in the system file.
$styles and $trans add to the system definitions. If you define one with the same name as in the system file then the global definition will override the system one and (unlike with variables) there is no way to access the system definition.
