Contents:

• Introductory stuff
• How comments are stored
• Styling comment sections
• Comment display configuration
• The %[cmt: ] macro

Introductory stuff

We already mentioned comment sections along with page set items and list item pages; those two are the only two kinds of pages generated by Thalassa that can have comments. Please use the two links, specially the former, to refresh your impressions.

It is essential to know that Thalassa stores comments for a particular page in a separate directory, where each comment is represented as a headed text file. Comments written in response to other comments store their parent comments' IDs, so logically comments for a page form a forest of trees, each tree having a root comment which was posted as a response for the original page content as such (not as a response to another comment). However, Thalassa is able to display comments both as a tree and as a flat sequence.

From the thalassa program's point of view, comments are just one kind of content to be converted to HTML. Typically, they are created, edited, deleted and otherwise handled with the Thalassa CGI program (thalcgi.cgi) using web-based interface, but it is certainly possible to manage them manually, by creating, editing and deleting the files.

How comments are stored

Comments for a page are stored in a separate directory as headed text files. Every comment has its numeric ID, starting with 1 (zero is a reserved value). In the present version of Thalassa, there's a hardcoded limit of 50'000 comments for a single page (within a single directory); if this eventually becomes a problem for you, please contact the author (well, I've never seen more than 3000 comments for a single article or post). File names for comments normally consist of four digits, that is, 0001, 0002, 0237 etc. In (highly unlikely) case there are more than 9999 comments in a directory, the files for comments with IDs exceeding 9999 will be named according to their IDs without leading zeroes, like 13476.

In every comment-storing directory there's also a file named _hints; despite its name, which is plural, in the present version it only stores one number: the maximum numerical ID of the existing comments. The file is advisory in the sense that if it is lost, corrupted or even just outdated, this will cause no failure: Thalassa CGI program always uses the O_EXCL flag when it creates new comment files, so if, despite the hint, a file with the supposed next free ID already exists, Thalassa CGI will try subsequent numbers, one by one. The only case when inconsistent value of the “hint” can cause a problem is when it is actually higher than the maximal ID of an existing comment, but this can't happen in the course of normal operations (although one can create this situation by manually editing the file).

The set of header fields recognized by Thalassa in comment files is slightly different from that of page set items. First of all, the fields encoding: and format: are used exclusively by the parser and aren't accessible from Thalassa templates. The id: field is handled in special manner; actually, in the present version the comment ID is fully determined by its file name, and is the number, but with no leading zeroes (e.g., for a file named 0021, the comment ID will be 21). In future versions a check for correctness of the id: header field may be implemented, so be prepared to that.

Besides these three, Thalassa recognizes the following header fields in comment files: parent, unixtime, user, flags, date, from and title. You can add any other fields if you need. The fields parent, unixtime, user and flags are not passed through any converters; all the other fields, including any custom fields added by the user, are passed through the encoding converter if necessary. None of the header fields are passed through the format converter, only the body is.

The recognized header fields are supposed to contain the following:

• parent — the ID of the “parent” comment; 0 or omitted field means the comment is “root”, that is, was written as a response for the page's content, not another comment;
• unixtime — as usual, seconds since Epoch;
• user — UID for registered (logged in) users, empty or omitted for anonymous users;
• flags — a comma-separated list of flags, of which Thalassa recognizes hidden, premod and anon; the thalassa program only handles the hidden flag, which means not to show the comment;
• date — the date in human-readable format;
• from — a “human-readable” name of the comment's author, such as their real name; unlike the user field, this value is supposed to be chosen by the posting person freely;
• title — well, the comment's title.

Styling comment sections

There are different ways for visualizing a set of comments. They can be displayed as a flat sequence, one by one, with replies having some kind of reference to their parent comments; they can also be displayed as a tree, with replies right under their parents, indented to show the parent-child relationship; besides that, it is possible to display top-level comments on one page, generating a separate page for each top-level comment's replies. For a flat sequence, all comments may be placed on a single physical page, or on a sequence of pages, each holding a number of comments up to a certain maximum value. The comments may be displayed in the native order as well as in the reverse order. The last but not least, whatever approach you choose, it still needs to be implemented as HTML code, and there are a lot of choices on this step, too.

In Thalassa, a particular way of comment section generation is configured with an ini section [commentstyle ID]. Within ini sections of this group, the following parameters are recognized:

• type defines the most general way of organizing comments; may be either list (for a plain sequence of comments), or tree (for a “tree” representation, with replies displayed right under the original comment, indented), or thread (for a separate discussion page to be created per each top-level comment);
• reverse controls whether comments should be displayed in the reverse order (newer first); may be yes or no; please note that for the “tree” type, only the root comments may be placed in the reverse order, while all replies of the same level are always displayed in the native order, and, similarly, for the “thread” type, only the main page (with the top-level comments) gets reversed, while on discussion pages the comments are always placed in the native order;
• perpage — how many comments to place on a single page (an integral number, in decimal representation); the value of 0 means to place all comments on one page, no matter how many comments there are. In the present version of Thalassa, the tree type can only work with zero perpage value, otherwise comments won't be shown at all as there's a stub in the code. Only the list type supports multipage representation.
• hidden_hold_place — defines whether hidden comments (as opposite to deleted comments) should still be counted as occupying space on their pages; may be yes or no;
• top_template and bottom_template — what HTML code to emit at the start and at the end of the comment section;
• indent_template and unindent_template (used for the tree type only) — what HTML code to use to increase and decrease the indentation level;
• comment_template and comment_tail_template — how to display a single comment; for the tree type, the code derived from comment_template is displayed first, then (recursively) all child comments (replies, replies to replies etc) are displayed, then goes the code derived from comment_tail_template; with the list type, they are simply concatenated so one can use the comment_template parameter only, leaving comment_tail_template blank;
• no_comments — what to display in case there are no comments on this page at all, even hidden; in this case, this is the only thing displayed, even top_template and bottom_template are omitted.

The cmt macro is available within the templates to provide access to the comment's properties and some additional data.

Comment display configuration

Ini sections of both [pageset ] and [list ] groups can have the comments parameter, which defines where to get the comments from and how to display them.

The value of this parameter may be (and usually is) a multiline text. The first line must consist of two words: the first word (of the first line) is the comment style, that is, the name of the desired [commentstyle ] section, and the second word is the comment directory path (usually a template). Additional lines form a dictionary, the first word being the key, and the rest of the line (leading and trailing whitespace stripped) being the value; these values are available within comment templates through the cmt macro with its aux function. This makes it possible to use a single set of macros for different comment 'realms'.

For example, the comments parameter may look as follows:

  comments = tree1 db/comments/page%[li:id]
      cgi_reply_path  /thalcgi.cgi/comment/page/%[li:id]/
      cgi_view_path   /thalcgi.cgi/cmta/page/%[li:id]/

The %[cmt: ] macro

The %[cmt: ] macro is available within comment style templates to provide access to comments' properties and some additional data. The macro accepts one or more arguments, first of them being the function name; e.g., %[cmt:title] expands to the current comment's title. The following functions are supported:

• id — the comment ID (the number without leading zeroes);
• ifroot accepts two additional arguments and return the first of them if the current comment is “root” (has no parent comments), otherwise returns the second one;
• ifhasparent (or just ifparent) — works like ifroot, but with the opposite condition;
• parent — the parent comment's ID, or 0 for root comments;
• pgofparent returns the URI of the page containing the parent comment, or an empty line if there's no parent comment; mainly this macro is intended for the list comment style; in the present version of Thalassa, this macro always returns an empty string for the tree comment style, and for thread comment style it only works for top-level comments displayed at the top of their discussion pages, returning the URI of the top-level page (which may even be used for detecting this situation from within the templates), and returns an empty string for all other cases;
• user — the user ID, or an empty line for anonymous comments;
• unixtime — the unixtime value (or empty string if the value is not set);
• date — the date, which is either the date: header field contents, or, if the header field is empty or omitted, the date derived somehow from the unixtime value;
• from — the contents of the from header field;
• title — the title;
• text — the body of the comment;
• replies — the number of replies (as of present, only works for the thread style and only for top-level comments, in any other case returns an empty string);
• threadpg — the URI of the page dedicated for the comments posted in repy to this one; only works for the thread style, and only for top-level comments displayed on the top-level page, in any other case returns an empty string;
• ifflag accepts three additional arguments: the flag, the then value, and the else value; if the given flag is present in the flags header field, returns the then value, otherwise returns the else value;
• aux accepts a key identifier as the additional argument, and returns the value associated with the key within the comments parameter of the respective page set or list;
• hf accepts a header field name as the additional parameter and returns the value of that header field; doesn't work for header fields recognized by Thalassa, only for additional headers.