Contents:

• Publishing methods
• The [binary NNN] section group
• The [collection NNN] section group

Thalassa CMS is not designed to generate binary files, and is not capable of it; hence, in case you need any non-textual objects, there's only one option: to copy it into your site's tree from somewhere else. And this is a thing Thalassa can do for you. Certainly, you can use it to copy text files as well, if you want so.

Publishing methods

Let's first make a note that we hereinafter use the term “publishing” to denote any action which results in making a file or a directory that exists somewhere to be available within the tree of the site being generated. The simplest such action is just to copy the file or directory into the tree, but this is not the only way, because a hard link or a symbolic link may be created as well. In case you generate your content right on the server machine, this really will be publishing, but if you prefer to generate everything elsewhere and copy the generated content to the server, formally the term becomes incorrect. Despite that, we don't make any difference between the two situations, so the term publishing is used from now on for placing files into the generated tree, no matter whether the tree is really public or not.

Besides the choice whether the file in question should be copied, linked or symlinked to the target location, there are other questions to decide on, specially if not a single file but a whole directory (or a part of it) is to be published. Should hidden files (those with names starting with a dot) be ignored or published? Should symlinks be “followed” and handled as normal files, or copied as is, or ignored? Should subdirectories be published recursively with all their content, or ignored, or (if symlink is selected as the publishing method) symlinked? Finally, shouldn't anyting happen with the file mode, that is, with access rights for the published file?

The thalassa program is able to perform publishing for single files, as determined by [binary ] configuration section, as well as for directories, configured by [collection ] sections. Besides that, the same procedure is done for additional files during generation of a page that belongs to a page set. For all these situations, the similar set of questions is to be answered regarding how exactly the files are to be published, and this is determined by the same set of parameters:

• publish_method controls whether files are to be copied, linked or symlinked; the possible values are copy, link and symlink, case insensitive; if the value is not one of these words, publishing for the whole object will be silently skipped;
• publish_symlinks determines what is to be done with symbolic links if they are found in the directory being published; recognized values are follow, preserve and ignore; in case the value is empty or not recognized, the default ignore behaviour is assumed; follow means symbolic links don't need any special handling, so the files referenced to by them are processed as if they were found right in the traversed directory, without any links; preserve means that in the target directory, a symbolic link will be created with exactly the same name and value; finally, ignore (or any other value) means symbolic links will be ignored as if they didn't exist at all;
• publish_hidden and publish_recursive control whether hidden files should be published or not, and whether subdirectories should be recursively traversed (and their contend published) or not; both are boolean values, which means that the only recognized value is yes, and anything else, including empty and absent value, are taken to be “no”; in this particular case, anything but yes means the publishing procedure will ignore hidden files or subdirectories, respectively;
• chmod forces a particular mode (access rights) to be set on files being published; the mode must be given as an octal number (see discussion related to simple pages where the same parameter is used); please note this parameter only affects regular files being copied; it is ignored for symbolic links and directories, as well as for publish_methods other than copy.

It is a good idea to remember that:

• hard link can not be made across filesystem borders;
• directories can not be hard-linked at all.

Macroprocessing is not done in any of these parameters' values, at least in the present version of Thalassa.

The [binary NNN] section group

Sections of the [binary NNN] group are designed to publish a single existing file; despite the name, files are not obliged to be binaries, the name “binary” should be taken as standing for the files that may be binaries.

Parameters recognized in these sections are source (the name of the original file), dest (the name and path for the file inside your generated tree), and all parameters enumerated in the section discussing publish methods, such as publish_method, chmod etc.

Both source and dest default to the section name, so the most minimalistic [binary ] may look like this:

  [binary logo.jpg]
  publish_method = copy

There is no default for the publish_method parameter, and empty sections are ignored anyway, so perhaps one can't make this more minimalistic.

The source value may either be an absolute path, or a relative one, in which case it is taken relative to the working directory of thalassa (typically the root of your site sources). In contrast, the dest value is always taken to be relative to the rootdir, even if it starts with a slash.

Please note the dest parameter must contain the file name, it can't be just a directory to place the file in.

In case you always set both source and dest explicitly, you can use any arbitrary identifier as the name of the section; only make sure you use different names for different sections, so that sections are not joined.

Both source and dest are passed through the macroprocessor to make options available.

The [collection NNN] section group

The term “collection” is used in Thalassa CMS for a set of files to be published as they are; basically it is a directory containing files.

Collections are defined with configuration sections named [collection NNN], which contain parameters sourcedir (the collection's origin), destdir (where to place the files inside your site's tree), and all parameters enumerated in the publish methods section, such as publish_method, publish_hidden etc.

Both sourcedir and destdir default to the section name (that NNN thing). There is no default for the publish_method parameter, so it must be given explicitly. See the publish methods section for a discussion how files are published.

The sourcedir value may be both an absolute or a relative path, (relative to the working directory of thalassa, typically the root of your site sources). The destdir value is always taken to be relative to the rootdir, even if it starts with a slash. Set the destdir to “/” to place files right in the root directory of your site.

If the publish_recursive is set to yes and there are subdirectories in your collection source directory, the same directory subtree will be created inside your web tree, even if the publish_method is “link” (please remember that directories can not be hardlinked). Furhtermore, the same will happen for the “symlink” method; if you want your subdirectories to be symlinked rather than making the same tree, set publish_recursive to no.

Please note there's no way to really ignore subsirectories in the symlink publish mode, as symbolic links to directories technically don't differ from symlinks to regular files.

In case you always set both sourcedir and destdir explicitly, you can use any arbitrary identifier as the name of the collection, but make sure you use different names for different collections.

Both sourcedir and destdir are passed through the macroprocessor to make options available.