335 lines
16 KiB
HTML
335 lines
16 KiB
HTML
<?xml version="1.0" encoding="us-ascii"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
|
|
<head>
|
|
<link type="text/CSS" rel="stylesheet" href="style.css" />
|
|
<link type="image/x-icon" rel="shortcut icon" href="favicon.png" />
|
|
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
|
|
<title>Thalassa CMS official documentation</title>
|
|
</head><body>
|
|
<div class="theheader">
|
|
<a href="index.html"><img src="logo.png"
|
|
alt="thalassa cms logo" class="logo" /></a>
|
|
<h1><a href="index.html">Thalassa CMS official documentation</a></h1>
|
|
</div>
|
|
<div class="clear_both"></div>
|
|
<div class="navbar" id="uppernavbar"> <a href="menus.html#uppernavbar" title="previous" class="navlnk">⇐</a> <a href="userdoc.html#comment_sections" title="up" class="navlnk">⇑</a> <a href="index_bars.html#uppernavbar" title="next" class="navlnk">⇒</a> </div>
|
|
|
|
<div class="page_content">
|
|
|
|
<h1 class="page_title"><a href="">Comment sections</a></h1>
|
|
<div class="page_body">
|
|
|
|
<p>Contents: </p>
|
|
<ul>
|
|
<li><a href="#intro">Introductory stuff</a></li>
|
|
<li><a href="#storage">How comments are stored</a></li>
|
|
<li><a href="#style">Styling comment sections</a></li>
|
|
<li><a href="#config">Comment display configuration</a></li>
|
|
<li><a href="#cmt_macro">The <code>%[cmt: ]</code> macro</a></li>
|
|
</ul>
|
|
|
|
|
|
<h2 id="intro">Introductory stuff</h2>
|
|
|
|
<p>We already mentioned comment sections along with
|
|
<a href="page_sets.html#comments">page set items</a> and
|
|
<a href="lists.html#list_item_pages">list item pages</a>; 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.
|
|
</p>
|
|
<p>It is essential to know that Thalassa stores comments for a particular page
|
|
in a separate directory, where each comment is represented as a
|
|
<a href="headed_text.html">headed text file</a>. Comments written in
|
|
response to other comments store their parent comments' IDs, so logically
|
|
comments for a page form a <em>forest</em> 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.
|
|
</p>
|
|
<p>From the <code>thalassa</code> 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
|
|
(<code>thalcgi.cgi</code>) using web-based interface, but it is certainly
|
|
possible to manage them manually, by creating, editing and deleting the
|
|
files.
|
|
</p>
|
|
|
|
|
|
<h2 id="storage">How comments are stored</h2>
|
|
|
|
<p>Comments for a page are stored in a separate directory as
|
|
<a href="headed_text.html">headed text files</a>. 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, <code>0001</code>,
|
|
<code>0002</code>, <code>0237</code> 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 <code>13476</code>.
|
|
</p>
|
|
<p>In every comment-storing directory there's also a file named
|
|
<code>_hints</code>; 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 <code>O_EXCL</code> 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).
|
|
</p>
|
|
<p>The set of header fields recognized by Thalassa in comment files is
|
|
slightly different from <a href="page_sets.html#header_fields">that of page
|
|
set items</a>. First of all, the fields <code>encoding:</code> and
|
|
<code>format:</code> are used exclusively by the parser and aren't
|
|
accessible from Thalassa templates. The <code>id:</code> 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 <code>0021</code>, the comment ID will be
|
|
<code>21</code>). In future versions a check for correctness of the
|
|
<code>id:</code> header field may be implemented, so be prepared to that.
|
|
</p>
|
|
<p>Besides these three, Thalassa recognizes the following header fields in
|
|
comment files: <code>parent</code>, <code>unixtime</code>,
|
|
<code>user</code>, <code>flags</code>, <code>date</code>, <code>from</code>
|
|
and <code>title</code>. You can add any other fields if you need. The
|
|
fields <code>parent</code>, <code>unixtime</code>, <code>user</code> and
|
|
<code>flags</code> are not passed through any converters; all the other
|
|
fields, including any custom fields added by the user, are passed through
|
|
the <a href="headed_text.html#encodings">encoding converter if
|
|
necessary</a>. None of the header fields are passed through the
|
|
<a href="headed_text.html#formats">format converter</a>, only the body is.
|
|
</p>
|
|
<p>The recognized header fields are supposed to contain the following:</p>
|
|
<ul>
|
|
|
|
<li><code>parent</code> — the ID of the “parent” comment;
|
|
<code>0</code> or omitted field means the comment is “root”, that
|
|
is, was written as a response for the page's content, not another
|
|
comment;</li>
|
|
|
|
<li><code>unixtime</code> — as usual, seconds since Epoch;</li>
|
|
|
|
<li><code>user</code> — UID for registered (logged in) users, empty
|
|
or omitted for anonymous users;</li>
|
|
|
|
<li><code>flags</code> — a comma-separated list of <em>flags</em>,
|
|
of which Thalassa recognizes <code>hidden</code>, <code>premod</code> and
|
|
<code>anon</code>; the <code>thalassa</code> program only handles the
|
|
<code>hidden</code> flag, which means not to show the comment;</li>
|
|
|
|
<li><code>date</code> — the date in human-readable format;</li>
|
|
|
|
<li><code>from</code> — a “human-readable” name of the comment's
|
|
author, such as their real name; unlike the <code>user</code> field, this
|
|
value is supposed to be chosen by the posting person freely;</li>
|
|
|
|
<li><code>title</code> — well, the comment's title.</li>
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
<h2 id="style">Styling comment sections</h2>
|
|
|
|
<p>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.
|
|
</p>
|
|
<p>In Thalassa, a particular way of comment section generation is configured
|
|
with an ini section <code>[commentstyle <em>ID</em>]</code>.
|
|
Within ini sections of this group, the following parameters are recognized:
|
|
</p>
|
|
<ul>
|
|
|
|
<li><code>type</code> defines the most general way of organizing comments;
|
|
may be either <code>list</code> (for a plain sequence of comments), or
|
|
<code>tree</code> (for a “tree” representation, with replies
|
|
displayed right under the original comment, indented), or
|
|
<code>thread</code> (for a separate discussion page to be created per each
|
|
top-level comment);</li>
|
|
|
|
<li><code>reverse</code> controls whether comments should be displayed in
|
|
the reverse order (newer first); may be <code>yes</code> or
|
|
<code>no</code>; 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;</li>
|
|
|
|
<li><code>perpage</code> — how many comments to place on a single
|
|
page (an integral number, in decimal representation); the value
|
|
of <code>0</code> means to place all comments on one page, no matter
|
|
how many comments there are. <strong>In the present version of Thalassa, the
|
|
<code>tree</code> type can only work with zero <code>perpage</code> value,
|
|
otherwise comments won't be shown at all as there's a stub in the
|
|
code</strong>. Only the <code>list</code> type supports multipage
|
|
representation.</li>
|
|
|
|
<li><code>hidden_hold_place</code> — defines whether hidden comments
|
|
(as opposite to deleted comments) should still be counted as occupying
|
|
space on their pages; may be <code>yes</code> or <code>no</code>;</li>
|
|
|
|
<li><code>top_template</code> and <code>bottom_template</code> — what
|
|
HTML code to emit at the start and at the end of the comment section;</li>
|
|
|
|
<li><code>indent_template</code> and <code>unindent_template</code> (used
|
|
for the <code>tree</code> type only) — what HTML code to use to
|
|
increase and decrease the indentation level;</li>
|
|
|
|
<li><code>comment_template</code> and <code>comment_tail_template</code>
|
|
— how to display a single comment; for the <code>tree</code> type, the
|
|
code derived from <code>comment_template</code> is displayed first, then
|
|
(recursively) all child comments (replies, replies to replies etc) are
|
|
displayed, then goes the code derived from
|
|
<code>comment_tail_template</code>; with the <code>list</code> type, they
|
|
are simply concatenated so one can use the <code>comment_template</code>
|
|
parameter only, leaving <code>comment_tail_template</code> blank;</li>
|
|
|
|
<li><code>no_comments</code> — 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 <code>top_template</code> and
|
|
<code>bottom_template</code> are omitted.</li>
|
|
|
|
</ul>
|
|
|
|
<p>The <a href="#cmt_macro"><code>cmt</code> macro</a> is available within the
|
|
templates to provide access to the comment's properties and some additional
|
|
data.
|
|
</p>
|
|
|
|
<h2 id="config">Comment display configuration</h2>
|
|
|
|
<p>Ini sections of both <code>[pageset ]</code> and
|
|
<code>[list ]</code> groups can have the <code>comments</code>
|
|
parameter, which defines where to get the comments from and how to display
|
|
them.
|
|
</p>
|
|
<p>The value of this parameter may be (and usually is) a multiline text. The
|
|
first <strong>line</strong> must consist of two words: the first word (of the
|
|
first line) is the comment style, that is, the name of the desired
|
|
<code>[commentstyle ]</code> 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
|
|
<a href="#cmt_macro"><code>cmt</code> macro</a> with its <code>aux</code>
|
|
function. This makes it possible to use a single set of macros for
|
|
different comment 'realms'.
|
|
</p>
|
|
<p>For example, the <code>comments</code> parameter may look as follows:
|
|
</p>
|
|
<pre>
|
|
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]/
|
|
</pre>
|
|
|
|
|
|
|
|
<h2 id="cmt_macro">The <code>%[cmt: ]</code> macro</h2>
|
|
|
|
<p>The <code>%[cmt: ]</code> macro is available within
|
|
<a href="#style">comment style</a> 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.,
|
|
<code>%[cmt:title]</code> expands to the current comment's title. The
|
|
following functions are supported:</p>
|
|
<ul>
|
|
|
|
<li><code>id</code> — the comment ID (the number without leading
|
|
zeroes);</li>
|
|
|
|
<li><code>ifroot</code> 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;</li>
|
|
|
|
<li><code>ifhasparent</code> (or just <code>ifparent</code>) —
|
|
works like <code>ifroot</code>, but with the opposite condition;</li>
|
|
|
|
<li><code>parent</code> — the parent comment's ID, or <code>0</code>
|
|
for root comments;</li>
|
|
|
|
<li><code>pgofparent</code> 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 <code>list</code> comment style; in the present
|
|
version of Thalassa, this macro always returns an empty string for the
|
|
<code>tree</code> comment style, and for <code>thread</code> comment style
|
|
it only works for <strong>top-level comments displayed at the top of their
|
|
discussion pages</strong>, 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;</li>
|
|
|
|
<li><code>user</code> — the user ID, or an empty line for anonymous
|
|
comments;</li>
|
|
|
|
<li><code>unixtime</code> — the unixtime value (or empty string if
|
|
the value is not set);</li>
|
|
|
|
<li><code>date</code> — the date, which is either the
|
|
<code>date:</code> header field contents, or, if the header field is empty
|
|
or omitted, the date derived somehow from the <code>unixtime</code> value;</li>
|
|
|
|
<li><code>from</code> — the contents of the <code>from</code>
|
|
header field;</li>
|
|
|
|
<li><code>title</code> — the title;</li>
|
|
|
|
<li><code>text</code> — the body of the comment;</li>
|
|
|
|
<li><code>replies</code> — the number of replies (as of present,
|
|
only works for the <code>thread</code> style and only for top-level
|
|
comments, in any other case returns an empty string);</li>
|
|
|
|
<li><code>threadpg</code> — the URI of the page dedicated for the
|
|
comments posted in repy to this one; only works for the <code>thread</code>
|
|
style, and only for top-level comments displayed on the top-level page, in
|
|
any other case returns an empty string;</li>
|
|
|
|
<li><code>ifflag</code> accepts three additional arguments: the flag, the
|
|
<em>then value</em>, and the <em>else value</em>; if the given flag is
|
|
present in the <code>flags</code> header field, returns the <em>then
|
|
value</em>, otherwise returns the <em>else value</em>;</li>
|
|
|
|
<li><code>aux</code> accepts a key identifier as the additional argument,
|
|
and returns the value associated with the key within the
|
|
<a href="#config"><code>comments</code> parameter</a> of the respective page
|
|
set or list;</li>
|
|
|
|
<li><code>hf</code> 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.</li>
|
|
|
|
</ul>
|
|
</div>
|
|
|
|
</div>
|
|
<div class="navbar" id="bottomnavbar"> <a href="menus.html#bottomnavbar" title="previous" class="navlnk">⇐</a> <a href="userdoc.html#comment_sections" title="up" class="navlnk">⇑</a> <a href="index_bars.html#bottomnavbar" title="next" class="navlnk">⇒</a> </div>
|
|
|
|
<div class="bottomref"><a href="map.html">site map</a></div>
|
|
<div class="clear_both"></div>
|
|
<div class="thefooter">
|
|
<p>© Andrey Vikt. Stolyarov, 2023-2026</p>
|
|
</div>
|
|
</body></html>
|