Comments are attached to either stories or polls, and are displayed below the story text or the poll graph when the full story or the poll results are viewed. If a poll is attached to a story, the same comments will display whether it's the story or its attached poll which is displayed.
All of the variables referenced below should be in the Comments section of the Site Controls.
There are two kinds of comments: editorial and topical.
Editorial comments are only displayed while the story they're attached to is in the queue, unless the user changes his comment view settings to explicitly include them, and top-level editorial comments can only be posted in the queue. Editorial comments are for suggestions to the author to improve the story, or reasons for voting the way the comment poster did. They shouldn't be used to discuss the topic of the story, because they will be hidden when (if) the story is posted.
Topical comments are displayed both in and out of the queue, and can be posted both in and out of the queue. Topical comments are for discussing the topic of the story, and not for providing suggestions for improvement, as they are displayed after posting when no changes are possible.
Replies to any comment take on the comment type of their parent; top-level comments allow the poster to choose whether it's topical or editorial if the story is still in the queue. Once out of the queue, only topical comments can be posted.
If you feel a comment is wrongly marked topical or editorial, you can change it using the ``toggle'' link at the end of the comment, right beside the ``delete'' link. Both require the perm comment_delete (A.12.4). Deleting a comment with replies leaves the replies but makes them all top-level comments.
The two types of comments are formatted using the block comment for topical comments, and the block moderation_comment for editorial comments. These blocks contain a number of special keys, such as for the subject, author, score, and date posted. The special keys are detailed in the block description, on your site. It's a good idea to make the two types of comments visually distinct; by default, topical comments have a blue border around the grey comment header information, while editorial comments have a red border.
Users can put a signature on every one of their comments if they like. If the variable allow_sig_behavior is on, users can choose to have them either ``stuck'' to the comment (ie, always displaying as originally posted), changed retroactivally whenever they change their sig (ie, always displaying the current sig, regardless of the sig in use when the comment was posted), or not display at all. This behavior can be set on a per-comment basis, with a default set in the user preferences. The default for new users is set in the variable default_sig_behavior.
Comments can be ordered in one of several ways. The user can change the view using the comment controls above and below the comment tree, and can set the preferred view in user preferences. The default for new and anonymous users are set in the variables default_comment_display, default_comment_order, and default_comment_sort.
default_comment_display can be set to one of the following comment views:
Since searchbots will be registered as anonymous users and only the latest browsers support the javascript used in the dynamic comments, the two dynamic modes are strongly not recommended as defaults.
The other sorting rules (sorting by age or rating) act as you would expect, but only sort the top-level comments. All replies are sorted by thread.
Unread comments can be marked as new for registered users, and the index pages can display the number of new comments in a story since a user last read it. The read/unread status is based on the highest comment number the last time the user displayed the story and comments; the system assumes that all comments displayed have been read. Displaying comments alone does not mark them as read.
The variable show_new_comments determines whether all, none, or only that user's hotlisted stories track which comments have been read, and the block new_comment_marker is displayed on the new comments.
The Scoop Box Exchange (see appendix B) has a box that will notify users if there is an unread reply to one of their comments. If you use this box, let your users know that comments are only marked read if they view the story; this has caused confusion in the past.
Comments can be posted using HTML, plain text, or ``autoformat'', a mode that translates common markup, such as what most people use in email, into HTML formatting. For example, it changes words surrounded by asterisks into bold text; *this* becomes this. A full description of the autoformat mode is included in your Scoop database; it can be found at |rootdir|/special/autoformat_syntax Each user can select their preferred mode and can change the mode for a single comment when posting. You can set the default for new and anonymous users to any of the three modes using the variable default_post_type. The default post type applies to both stories and comments.
The HTML tags permitted in stories and comments can be changed as desired, in the variable allowed_html. This has a specific format, described in the variable description, but basically you enter one HTML tag per line, follow it with any permitted attributes in a comma-separated list, and end it with ``-close'' if it must have a matching closing tag.
Permission to post topical comments is given with the perm comment_post (A.12.5), and permission to post editorial comments is given with both editorial_comments (A.12.21) and comment_post.
You can also give permission to post comments in certain sections using the Sections Admin Tool (A.9). To post a comment, a user must have both the comment_post general permission and the section-specific permission set. Removing either of those removes the user's ability to post; the former overall, and the latter in the specific section.
Comments in reply to polls are handled with the perm poll_post_comments (A.12.26) as well as comment_post; as with section permissions, both must be turned on for the user to be able to post comments to polls.
Comment rating uses an averaging, not an additive, system. Rather than having three people rate a comment ``up'' at the same time and have the comment end up with a higher score than any of them think it deserves, those three people can rate it at the value they think it should be, and their ratings are averaged, giving it a score much closer to the one it deserves. Fractional scores are very common, and are displayed to two decimal places.
Everybody with the perm comment_rate (A.12.6) can rate all comments except their own. Individual ratings are an integer value between the values set in the variables rating_min and rating_max, inclusive. The average rating of a user's comments determines his ``mojo'' (see section 4.11 for a full description), which, if it gets high enough, can make the user ``trusted'' and able to rate comments one point below rating_min; all comments with an average rating below rating_min are hidden from everybody except trusted users.
To give unrated comments a fighting chance when users choose to display comments sorted by rating, you can have comments start with a default rating. The first person to rate the comment completely overrides the default rating, and from there on ratings are averaged as usual. To give comments an initial rating, turn the variable use_initial_rating on, and set the variables anonymous_default_points and user_default_points to the values you want anonymous (if permitted) and registered user comments to start with.
Scoop's dynamic comment modes are truly neat. They do not load all comments then merely toggle the visibility of the appropriate sections of HTML; they actually request the individual comment from the server when you click to view it, and insert it into the page in the appropriate spot without reloading the entire page.
Dynamic comment mode is done using javascript, and only modern ``fifth-generation'' browsers can deal with it properly. That is, Netscape > 6; IE > 5; Mozilla and other gecko-based browsers, and later versions of Opera. Some other browsers may work with it, but those listed here are those known to work.
On a brand-new install, dynamic mode comments should be as easy to turn on as switching on the variable allow_dynamic_comment_mode. Older installs will take a bit more work, as information must be added to certain blocks, and that is hard to do automatically without clobbering your customizations.
The following items should be set as described below; if dynamic mode comments are turned on but not working properly, confirm that everything below is set correctly.
Alias /scoop/ "/www/scoop/html/" Alias /scoop/images/ "/www/scoop/html/images/"Then stop and start Apache. Paths should be adjusted as necessary for your setup. This will allow files in the scoop/html directory, such as robots.txt, backend.rdf, and dynamic-comments.js to be fetched normally.
<script type="text/javascript" src="|rootdir|/dynamic-comments.js"></script>Confirm that the path to dynamic-comments.js in this block is correct and leads to the file as noted in the first step.
When you have made sure that all of the above items are set correctly, the variable allow_dynamic_comment_mode may be turned on to allow users to choose dynamic comment display modes.
Note that the dynamic modes should never be set as default in the variable default_comment_display, because it does not work for older browsers or search spiders.