1	# ======================================================================
     2	# comment table layout.
     3	#
     4	# Table of comments, with post-moderation.
     5	#
     6	# TW comments are post-moderated. If the first comment in a thread is
     7	# deleted, it will NOT cause the deletion of the whole thread. A thread
     8	# must accomodate for removal of selected entries, i.e. it must be
     9	# allowed contain interruptions, or even posts that refer to a deleted
    10	# post, without causing problems to the thread itself. It is the same as
    11	# with e-mail message threading in mailing-list archives.
    12	#
    13	# A post that starts a new thread will always have c_tree=R .
    14	#
    15	# Replying to an existing post will always require the specification
    16	# of c_parent as an argument.
    17	#
    18	# If, for any reasons, the parent disappears while a reply is being posted,
    19	# the operation will fail with an error. It may happen in case the
    20	# moderator has just banned the parent.
    21	#
    22	# NOTE: THIS TABLE MUST *NEVER* BE SORTED ON THE PK, OR THE WHOLE
    23	# THREADING STRUCTURE WILL BE LOST !!! Should this happen, things
    24	# may be fixes by sorting the table again on 'c_seq' .
    25	#
    26	# ======================================================================
    27	
    28	k_cmt		Table PK, in the form of YYYMMDDHHmmss-$CSA_PID
    29	
    30	c_parent	k_cmt of the entry this post is replying to.
    31			This field must be NOT NULL, and if the entry has
    32			no parent it is set equal to 'k_cmt'. This is similar
    33			to RFC822's 'References:' (or the old 'In-Reply-To:').
    34			The purpose of this field is to preserve insertion
    35			order, so as to form the threading.
    36	
    37	c_thread	'k_cmt' of the post that started the thread. It is always
    38			inherited from 'c_parent'.
    39	
    40	c_tree		Indenting "depth" of the post, for visualization purposes.
    41			It is formed by a sequence of as many "R" characters
    42			("Reply") as the indenting level. Since the thread must allow
    43			for interruptions, in fact the number of "R" chars isn't used
    44			literally, but it is considered to be relative to the lenght
    45			of the same field in the posts immediately preceeding and
    46			following this one.
    47	
    48	c_seq		Ordered sequence of records in table. It is re-computed
    49			upon every new post, to maintain the correct visualization
    50			of the threaded structure. The fact that the whole table
    51			changes at every new post makes it unsuitable for version-
    52			control with RCS. The banning process will therefore not
    53			rely on versioning to recover banned texts, which will
    54			thus be stored in the companion table 'page+ban' (see below).
    55	
    56	c_ctime		ISO8601 creation time-stamp of this post.
    57	
    58	c_creau		Post author (user-id, if available, otherwise either
    59			twauthor or 'anonymous'.
    60	
    61	c_aumail	Mandatory e-mail address of poster (unverified).
    62	
    63	c_auweb		Optional Web site URL of poster (unverified).
    64	
    65	c_creip		Poster IP address.
    66	
    67	c_banned	Banned stamp, in the form user_id:$CSA_TIME_ISO .
    68			Posts cannot be altered, not even by signed-in users,
    69			but only banned if necessary, and only by an editor.
    70			A banned post is replaced by a standard text (also in
    71			the subject, for lists), with the original post that
    72			can be recovered by an editor from 'page+ban' if needed.
    73	
    74	c_approved	Approved stamp, in the form user_id:$CSA_TIME_ISO .
    75			If this field is missing, the post will still be visible
    76			but it means the the post is still unverified, and thus
    77			it may potentially still be banned by the moderator.
    78	
    79	c_other		Misc subfields, separated by "|", much like 'auth:u_other'.
    80			The first (and, at the moment, only) subfield contains
    81			the MD5 hash of 'c_aumail', mainly for gravatar support.
    82	
    83	c_subject	Optional subject (max 64 char). Defaults to the first 64
    84			characters of c_text if not specified.
    85	
    86	c_text		Body of the post, which will allow for basic XHTML markup.
    87	
    88	c_excerpt	Optional comment abstract
    89	
    90	k_node		comment unique numeric node ID
    91	
    92	#EOF