Contents:

• General configuration overview
• The [general] configuration section
• The [format] section
• The [html] section
• The [options NNN] section group

General configuration overview

General configuration, in the sense that it affects most general aspects of Thalassa's functioning, is done with:

• [options NNN] section group, in which parameters are set that are later available via the %[opt: ] macro;
• [general] section, which sets the most “global” parameters, such as the path for the web tree to be generated and the option set selector(s);
• [format] section, in which the base character encoding (codepage) may be configured, as well as the list of HTML tags allowed for user-supplied content;
• [html] section, in which HTML snippets and simple templates are defined.

The [general] configuration section

The [general] configuration section contains parameters that affect functioning of the thalassa program as a whole; some of them may be overriden by command line options. All parameters in this section are passed through the macroprocessor to make it possible to use the options. The only exception is the opt_selector parameter, in which macro expansion is not done.

The rootdir parameter sets the directory serving as the root for your site's tree. Both relative or absolute path may be specified; as usual for Unix-like operating systems, the path is considered absolute in case its first char is “/”, otherwise it is taken relative to the working directory — either directory from which thalassa is invoked, or the directory explicitly specified at the command line with the respective option.

By default (in case the parameter is not specified in the configuration files), “html” is used, so the site will be generated in the html subdirectory of your source tree. In most cases you'd probably want to specify something that starts with ../.

This parameter can be overriden with gen -t dir command line option.

The base_url and base_uri parameters set the base URL (the URL without the local part, e.g. http://www.example.com) and the base URI (the local part of the URL to which the root of your generated tree corresponds, typically just “/”). By default, base_url is empty string and base_uri is “/”.

The base_url parameter is not used by Thalassa itself, it is only made available with the %base_url% macro. This may be useful when you need to specify a “canonical” reference to your site, e.g., for an RSS feed.

In contrast, the base_uri parameter is actively used by Thalassa when it has to generate navigation links on its own; the obvious cases of such use are index bars and links from comment answers to parent comments within comment sections.

The inifiles parameter specifies additional ini files to be loaded by thalassa. The value is simply a list of file names, separated either with whitespace, or with commas, or both — you can write it however you like. Please note that there's no way to specify a file with whitespace chars in its name, nor with commas, and this is not going to change, because we believe spaces and commas must never be used in file names.

Additional files loaded this way may as well contain the [general]/inifiles parameter, thus specifying more files, and thalassa is able to handle it correclty. Loading files one by one, thalassa memorizes names of the files it loaded already, so a file is never loaded more than once, unless it is specified by different names. For example, my.ini and ./my.ini obviously name the same file, but being taken as strings, these names are different, so it is relatively easy to fool thalassa and force it to read the same file more than once. Don't do it, the result will never be of any use.

You can specify ini files at the command line as well, but this doesn't override the inifiles parameter, in the sense that if the files you specify at command line contain the parameter, then files enumerated in the parameter will be loaded, too.

The spooldir parameter specifies the directory to be used for the spooler mode. The default value is _spool, but in most cases it is better to place this directory together with the thalcgi.cgi's session database. This parameter is only used in case thalassa is explicitly instructed to work in spool mode; in particular, if you don't use the dynamic features of Thalassa CMS (that is, the CGI program), then you shouldn't care about this parameter at all.

The opt_selector parameter is used to choose a set of options in case several such sets are preconfigured within the [options NNN] section group. Specifiers may be used with the parameter; if given, specifiers should match options section IDs, and the value will only be used for the corresponding section. The value set without specifiers is, as usual, considered the default; thalassa uses it for option sections for which there's no specific value.

In the present version, the default (and only the default) opt_selector value can be overriden by command line.

In contrast to all other options within the [general] section, the value(s) for the opt_selector parameter are not passed through the macroprocessor.

The [format] section

The [format] section affects conversions performed on headed text files when they are used in content generation. Two parameters are currently recognized in this section:

• encoding declares the character encoding used both in the ini files and for the generated HTML files. See the headed text files page for discussion of character encodings. If this parameter is omitted or empty, Thalassa assumes no encoding conversions is ever needed and acts completely encoding-agnostic.
• tags enumerates HTML tags allowed in user-supplied content, namely in comments and in some of the set pages (see page sets here). If omitted or empty, it means no tags are allowed at all, so all tags get filtered off.

The values of both parameters are passed through the macroprocessor to make the options available.

Once again, this only affects headed text files; no content that comes from the ini files is affected by parameters of this section in any way.

The [html] section

The [html] section contains named HTML snippets, which are available where you need them via macro calls %[html:snippet_name]. You can have as many parameters in this section as you wish, and name them whatever you like. Well, not really whatever: make sure you only use latin letters, digits and the underscore char for the parameters' names, or else you are almost guaranteed to have problems.

For example, if you place a parameter foobar into the section, like this:

  [html]
  foobar = foo bar bur buzz

— then anywhere where the macroprocessing is done, macro call %[html:foobar] will be replaced with (expanded to) the string “foo bar bur buzz”.

Macroprocessing is done on the values, which allows to use macros in your snippets, including the %[html: ] macro itself, so you can use your snippets within other snippets.

The %[html: ] macro can accept additional arguments (there's no formal limit on their count), and such arguments can be referenced within the snippets as %0%, %1%, %2%, ... %17% etc. Only remember that they are numbered from zero, which may be not what you're used to. For example, if you have a snippet

  [html]
  notwhat = %0% is not a thing I %1%.

— then %[html:notwhat:Ice cream:like] will turn into “Ice cream is not a thing I like.”, while %[html:notwhat:Fish oil:hate] turns into “Fish oil is not a thing I hate.”. This allows to use the [html] section and the macro not only for simple snippets, but for a kind of templates as well.

The [options NNN] section group

Sections of the [options ] group are intended to contain relatively small values that allow to customize the site's configuration. Values of the parameters are accessible by calling the %[opt: ] macro; it accepts exactly two arguments, the first is the section name, and the second is the parameter name. For example, if the ini files contain

  [options foo]
  bar = abracadabra

then %[opt:foo:bar] will expand to “abracadabra”.

All parameters in this section group may have specifiers, but generally (unless empty string is the desired default value) it is a good idea to provide the default value as well, like this:

  [options colors]

  text:night = #808080
  text:matrix = #00aa00
  text = #000000

  background:night = #000000
  background:matrix = #000000
  background:girly = #ffc0cb
  background = #ffffff

As we already mentioned, specific values here are chosen by the parameter opt_selector from the [general] section, and this parameter, in turn, may have a specifier which corresponds to the options section ID. For example, here:

  [general]
  opt_selector:colors = matrix
  opt_selector = twilight

the word matrix will be used as the specifier for the section [options matrix], and the word twilight will affect all the other sections in the [options ] section group.

Macroprocessing is not performed within this section group.