- Comment module documentation improvements; updates by Charlie, patch by Al.

2 files changed, 124 insertions, 10 deletions

diff --git a/modules/comment.module b/modules/comment.module
index 2db900ffb..17e687a29 100644
--- a/modules/comment.module
+++ b/modules/comment.module
@@ -5,11 +5,68 @@ $GLOBALS["cmodes"] = array(1 => t("Flat list - collapsed"), 2 => t("Flat list -
 $GLOBALS["corder"] = array(1 => t("Date - newest first"), 2 => t("Date - oldest first"));
 
 function comment_help() {
-  $output .= t("<p>The comment module enables users to submit posts that are directly associated with a piece of content, a node.  These associated posts are called <i>comments</i>.  Comments may be <i>threaded</i>, which means that Drupal keeps track of multiple subconversations around a piece of content.  Threading helps to keep the comment conversation organized.  Users are presented with several ways to view the comment conversation, and if desired, users may easily choose a <i>flat</i> presentation of comments instead of a threaded one.  Further, users may choose to order their comments view by <i>newest comments first</i> or by <i>oldest comments first</i>.  Finally, users may view a folded list, where only comment <i>subjects</i> are displayed, or an expanded list, where the whole comment is shown.</p>");
-  $output .= t("<p>Since a busy site generates lots of comments, Drupal takes care to present a personalized view of comments for each user. A user can setup how they want they comments displayed -- Threaded/Flat, Expanded/Folded -- and how many comments to display per page. If there are more comments than you have configured to display on a page, navigation links are displayed.  The home page displays, for the current user, the number of read and unread comments for a given node.  Also, the tracker module (when installed) displays all recent comments on the site.  Finally, comments which the user has not yet read are highlighted with a red star (this graphic may depend on the current theme).</p>");
-  $output .= t("<p>Comments behave like other user submissions in Drupal.  Specifically, if the administrator has enabled them, ". l("filters", "admin/system/filters") .", like smileys and HTML, work fine.  Also, throttles are usually enabled to prevent a single user from spamming the web site with too many comments in a short period of time.</p>");
-  $output .= t("<p>Administrators may control which roles are allowed to submit, submit without moderation, view and administer comments using the \"post comments\", \"post comments without approval\", \"access comments\", and \"administrate comments\" ". l("user permissions", "admin/user/permission") .".  Additionally, administrators may set the default display view, edit or search through comments on the ". l("comments admininistration page", "admin/comment") .".</p>");
-  $output .= t("<p>If you really have a lot of comments, you can enable moderation. You assign ". l("moderation permissions", "admin/user/permission") ." to role(s), then setup some \"". l("moderation votes","admin/comment/moderation/votes") ."\"; these votes will appear to moderators in a dropdown menu near the comment. You also have to assign, for every role and every vote, ". l("a value", "admin/comment/moderation/matrix") .", which can be either positive or negative. This allows, if you wish, some roles to have greater \"weight\" in their moderation. If you set a value to 0, that vote won't be available to that role. When a user moderates, the value of their vote is added or subtracted to the score of that comment. Next your have to setup the \"". l("Queue settings", "admin/system/modules/queue") ."\" to allow a moderated comment to either be posted or dumped. Finally, you may want to setup the ". l("comment thresholds", "admin/comment/moderation/threshold") .": these are floor/ceiling values which users can set in the comment control panel. Thresholds are useful for hiding poorly rated comments from your users while they are reading.</p>");
+  $output .= t("<p>When enabled, the Drupal comment module creates a discussion board for each Drupal node. Users can post comments to discuss a forum topic, weblog post, collaborative book page, etc.</p>
+
+<h3>User control of comment display</h3>
+<p>Attached to each comment board is a control panel for customizing the way that comments are displayed. Users can control the chronological ordering of posts (newest or oldest first) and the number of posts to display on each page. Additional settings include:</p>
+<ul>
+ <li><b>Threaded </b>-- Comment posts are displayed much like the subject view of an email client: the posts are grouped according to the conversations and subconversations.</li>
+ <li><b>Flat </b>-- Displays the posts in chronological order, in the order in which they are posted.</li>
+ <li><b>Expanded </b>-- Displays the title and text for each post.</li>
+ <li><b>Collapsed</b> -- Displays only the title for each post.</li>
+</ul>
+<p>When users choose <i>save settings</i>, the comments are then redisplayed with the user's choices. Know that administrators can set the default settings for the control panel, along with other comment configuration defaults, in <i>site configuration &raquo; modules &raquo; comment</i>.</p>
+<p>NOTE: When comment moderation is enabled, users will have another control panel option to control thresholds (see below).</p>
+
+<h3>Additional comment configurations</h3>
+<p>Comments behave like other user submissions in Drupal. Filters, smileys and HTML that work in nodes will also work with content. To prevent a single user from spamming the web site with too many comments, administrators can set a comment throttle in <i>site configuration</i> under <i>Submission settings</i>.</p>
+<p>Administrators can control access to various comment module functions through <i>user management &raquo; user permissions</i>. Know that in a new Drupal installation, all comment permissions are disabled by default. The choice of which permissions to grant to which roles (groups of users) is left up to the site administrator.</p>
+<p>The following permissions can be enabled for anonymous users, authenticated users, or any other roles that the administrator chooses to define:</p>
+<ul>
+ <li><b>Access comments</b> -- Necessary for users to view comments.</li>
+ <li><b>Administrate comments</b> -- Gives the user complete control over configuring, editing and deleting all comments on the site. Best reserved for very trusted users.</li>
+ <li><b>Moderate comments</b> -- Users with this permission can rate comment postings (see more on moderation below).</li>
+ <li><b>Post comments</b> -- Allows users to post comments into an administrator moderation queue. Administrators then post the comment to the site. </li>
+ <li><b>Post comments without approval</b> -- Bypasses the administrator moderation queue and comments are posted directly.</li>
+</ul>
+
+<h3>Notification of new comments</h3>
+<p>Drupal provides specific features to inform site members when new comments have been posted:</p>
+<ul>
+  <li>On the home page, Drupal displays the total number of comments along with each node. Drupal also tracks comments read by individual site members. Logged in members will see a notice accompanying nodes containing comments which they have not read.</li>
+  <li>The <i>tracker</i> module displays all recent posts on the site (note that the tracker module is disabled by default). When logged in, members will find a <i>view recent posts </i>in their user information block with a link to the <i>Recent activity</i> page. This page is a useful way to browse new or updated nodes and comments. Content which the user has not yet read is tagged with a red star (this graphic may depend on the current theme). Visit the comment board for any node, and Drupal will display a red <i>new</i> label beside the text of unread comments.</li>
+ <li>Some administrators may want to <a href=\"http://drupal.org/node/view/68\">download</a>, install and configure the notify module. Users can then request that Drupal send them an email when new comments are posted (the notify module requires that cron.php be configured properly).</li>
+</ul>
+
+<h3>Comment moderation</h3>
+<p>On sites with active commenting from users, the administrator can turn over comment moderation to the community. </p>
+<p>With comment moderation, each comment is automatically assigned an initial rating. As users read comments, they can apply a vote which affects the comment rating. At the same time, users have an additional option in the control panel which allows them to set a threshold for comment display. Those comments with ratings lower than the set threshold will not appear.</p>
+<p>To enable moderation, the administrator must grant <i>moderate comments</i> permissions. Then, a number of options in <i>comment management &raquo; comment moderation</i> must be configured.</p>
+
+<h4>Moderation votes</h4>
+<p>The first step is to create moderation labels which allow users to rate a comment.  Go to <i>comment management &raquo; comment moderation &raquo; votes</i>. In the <i>vote</i> field, enter the textual labels which users will see when casting their votes. Some examples might be</p>
+<ul>
+ <li>Excellent +3</li>
+ <li>Insightful +2</li>
+ <li>Caught My Attention +1</li>
+ <li>Useful +1</li>
+ <li>Redundant -1</li>
+ <li>Flame -3</li>
+</ul>
+<p>So that users know how there votes affect the comment, these examples include the vote value as part of the label, although that is optional.</p>
+<p>Using the weight option, you can control the order in which the votes appear to users. Setting the weight heavier (positive numbers) will make the vote label appear at the bottom of the list. Lighter (a negative number) will push it to the top. To encourage positive voting, a useful order might be higher values, positive votes, at the top, with negative votes at the bottom.</p>
+
+<h4>Moderators/vote values matrix</h4>
+
+<p> Next go to <i>comment management &raquo; comment moderation &raquo; matrix</i>.  Enter vote values for each of the labels in the matrix with each permission role. The values entered here will be used to create the rating for each comment.</p>
+<p>NOTE: Comment ratings are calculated by averaging user votes with the initial rating.</p>
+<h4>Creating comment thresholds</h4>
+<p>In <i>comment management &raquo; comment moderation &raquo; thresholds</i>, you'll have to create some comment thresholds to make the comment rating system useful. When comment moderation is enabled and the thresholds are created, users will find another comment control panel option for selecting thresholds. They'll use the thresholds you enter here to filter out comments with low ratings. Consequently, you'll probably want to create more than one threshold to give users some flexibility in filtering comments.</p>
+<p>When creating the thresholds, note that the <i>Minimum score</i> is asking you for the lowest rating that a comment can have in order to be displayed.</p>
+<p>To see a common example of how thresholds work, you might visit <a href=\"http://slashdot.org/\">Slashdot</a> and view one of their comment boards associated with a story. You can reset the thresholds in their comment control panel.</p>
+
+<h4>Initial comment scores</h4>
+<p>Finally, you may want to enter some <i>initial comment scores</i>. In <i>comment management &raquo; initial comment scores </i>you can assign a beginning rating for all comments posted by a particular permission role. If you do not assign any initial scores, Drupal will assign a rating of <b>0</b> as the default.</p>");
 
   return $output;
 }
diff --git a/modules/comment/comment.module b/modules/comment/comment.module
index 2db900ffb..17e687a29 100644
--- a/modules/comment/comment.module
+++ b/modules/comment/comment.module
@@ -5,11 +5,68 @@ $GLOBALS["cmodes"] = array(1 => t("Flat list - collapsed"), 2 => t("Flat list -
 $GLOBALS["corder"] = array(1 => t("Date - newest first"), 2 => t("Date - oldest first"));
 
 function comment_help() {
-  $output .= t("<p>The comment module enables users to submit posts that are directly associated with a piece of content, a node.  These associated posts are called <i>comments</i>.  Comments may be <i>threaded</i>, which means that Drupal keeps track of multiple subconversations around a piece of content.  Threading helps to keep the comment conversation organized.  Users are presented with several ways to view the comment conversation, and if desired, users may easily choose a <i>flat</i> presentation of comments instead of a threaded one.  Further, users may choose to order their comments view by <i>newest comments first</i> or by <i>oldest comments first</i>.  Finally, users may view a folded list, where only comment <i>subjects</i> are displayed, or an expanded list, where the whole comment is shown.</p>");
-  $output .= t("<p>Since a busy site generates lots of comments, Drupal takes care to present a personalized view of comments for each user. A user can setup how they want they comments displayed -- Threaded/Flat, Expanded/Folded -- and how many comments to display per page. If there are more comments than you have configured to display on a page, navigation links are displayed.  The home page displays, for the current user, the number of read and unread comments for a given node.  Also, the tracker module (when installed) displays all recent comments on the site.  Finally, comments which the user has not yet read are highlighted with a red star (this graphic may depend on the current theme).</p>");
-  $output .= t("<p>Comments behave like other user submissions in Drupal.  Specifically, if the administrator has enabled them, ". l("filters", "admin/system/filters") .", like smileys and HTML, work fine.  Also, throttles are usually enabled to prevent a single user from spamming the web site with too many comments in a short period of time.</p>");
-  $output .= t("<p>Administrators may control which roles are allowed to submit, submit without moderation, view and administer comments using the \"post comments\", \"post comments without approval\", \"access comments\", and \"administrate comments\" ". l("user permissions", "admin/user/permission") .".  Additionally, administrators may set the default display view, edit or search through comments on the ". l("comments admininistration page", "admin/comment") .".</p>");
-  $output .= t("<p>If you really have a lot of comments, you can enable moderation. You assign ". l("moderation permissions", "admin/user/permission") ." to role(s), then setup some \"". l("moderation votes","admin/comment/moderation/votes") ."\"; these votes will appear to moderators in a dropdown menu near the comment. You also have to assign, for every role and every vote, ". l("a value", "admin/comment/moderation/matrix") .", which can be either positive or negative. This allows, if you wish, some roles to have greater \"weight\" in their moderation. If you set a value to 0, that vote won't be available to that role. When a user moderates, the value of their vote is added or subtracted to the score of that comment. Next your have to setup the \"". l("Queue settings", "admin/system/modules/queue") ."\" to allow a moderated comment to either be posted or dumped. Finally, you may want to setup the ". l("comment thresholds", "admin/comment/moderation/threshold") .": these are floor/ceiling values which users can set in the comment control panel. Thresholds are useful for hiding poorly rated comments from your users while they are reading.</p>");
+  $output .= t("<p>When enabled, the Drupal comment module creates a discussion board for each Drupal node. Users can post comments to discuss a forum topic, weblog post, collaborative book page, etc.</p>
+
+<h3>User control of comment display</h3>
+<p>Attached to each comment board is a control panel for customizing the way that comments are displayed. Users can control the chronological ordering of posts (newest or oldest first) and the number of posts to display on each page. Additional settings include:</p>
+<ul>
+ <li><b>Threaded </b>-- Comment posts are displayed much like the subject view of an email client: the posts are grouped according to the conversations and subconversations.</li>
+ <li><b>Flat </b>-- Displays the posts in chronological order, in the order in which they are posted.</li>
+ <li><b>Expanded </b>-- Displays the title and text for each post.</li>
+ <li><b>Collapsed</b> -- Displays only the title for each post.</li>
+</ul>
+<p>When users choose <i>save settings</i>, the comments are then redisplayed with the user's choices. Know that administrators can set the default settings for the control panel, along with other comment configuration defaults, in <i>site configuration &raquo; modules &raquo; comment</i>.</p>
+<p>NOTE: When comment moderation is enabled, users will have another control panel option to control thresholds (see below).</p>
+
+<h3>Additional comment configurations</h3>
+<p>Comments behave like other user submissions in Drupal. Filters, smileys and HTML that work in nodes will also work with content. To prevent a single user from spamming the web site with too many comments, administrators can set a comment throttle in <i>site configuration</i> under <i>Submission settings</i>.</p>
+<p>Administrators can control access to various comment module functions through <i>user management &raquo; user permissions</i>. Know that in a new Drupal installation, all comment permissions are disabled by default. The choice of which permissions to grant to which roles (groups of users) is left up to the site administrator.</p>
+<p>The following permissions can be enabled for anonymous users, authenticated users, or any other roles that the administrator chooses to define:</p>
+<ul>
+ <li><b>Access comments</b> -- Necessary for users to view comments.</li>
+ <li><b>Administrate comments</b> -- Gives the user complete control over configuring, editing and deleting all comments on the site. Best reserved for very trusted users.</li>
+ <li><b>Moderate comments</b> -- Users with this permission can rate comment postings (see more on moderation below).</li>
+ <li><b>Post comments</b> -- Allows users to post comments into an administrator moderation queue. Administrators then post the comment to the site. </li>
+ <li><b>Post comments without approval</b> -- Bypasses the administrator moderation queue and comments are posted directly.</li>
+</ul>
+
+<h3>Notification of new comments</h3>
+<p>Drupal provides specific features to inform site members when new comments have been posted:</p>
+<ul>
+  <li>On the home page, Drupal displays the total number of comments along with each node. Drupal also tracks comments read by individual site members. Logged in members will see a notice accompanying nodes containing comments which they have not read.</li>
+  <li>The <i>tracker</i> module displays all recent posts on the site (note that the tracker module is disabled by default). When logged in, members will find a <i>view recent posts </i>in their user information block with a link to the <i>Recent activity</i> page. This page is a useful way to browse new or updated nodes and comments. Content which the user has not yet read is tagged with a red star (this graphic may depend on the current theme). Visit the comment board for any node, and Drupal will display a red <i>new</i> label beside the text of unread comments.</li>
+ <li>Some administrators may want to <a href=\"http://drupal.org/node/view/68\">download</a>, install and configure the notify module. Users can then request that Drupal send them an email when new comments are posted (the notify module requires that cron.php be configured properly).</li>
+</ul>
+
+<h3>Comment moderation</h3>
+<p>On sites with active commenting from users, the administrator can turn over comment moderation to the community. </p>
+<p>With comment moderation, each comment is automatically assigned an initial rating. As users read comments, they can apply a vote which affects the comment rating. At the same time, users have an additional option in the control panel which allows them to set a threshold for comment display. Those comments with ratings lower than the set threshold will not appear.</p>
+<p>To enable moderation, the administrator must grant <i>moderate comments</i> permissions. Then, a number of options in <i>comment management &raquo; comment moderation</i> must be configured.</p>
+
+<h4>Moderation votes</h4>
+<p>The first step is to create moderation labels which allow users to rate a comment.  Go to <i>comment management &raquo; comment moderation &raquo; votes</i>. In the <i>vote</i> field, enter the textual labels which users will see when casting their votes. Some examples might be</p>
+<ul>
+ <li>Excellent +3</li>
+ <li>Insightful +2</li>
+ <li>Caught My Attention +1</li>
+ <li>Useful +1</li>
+ <li>Redundant -1</li>
+ <li>Flame -3</li>
+</ul>
+<p>So that users know how there votes affect the comment, these examples include the vote value as part of the label, although that is optional.</p>
+<p>Using the weight option, you can control the order in which the votes appear to users. Setting the weight heavier (positive numbers) will make the vote label appear at the bottom of the list. Lighter (a negative number) will push it to the top. To encourage positive voting, a useful order might be higher values, positive votes, at the top, with negative votes at the bottom.</p>
+
+<h4>Moderators/vote values matrix</h4>
+
+<p> Next go to <i>comment management &raquo; comment moderation &raquo; matrix</i>.  Enter vote values for each of the labels in the matrix with each permission role. The values entered here will be used to create the rating for each comment.</p>
+<p>NOTE: Comment ratings are calculated by averaging user votes with the initial rating.</p>
+<h4>Creating comment thresholds</h4>
+<p>In <i>comment management &raquo; comment moderation &raquo; thresholds</i>, you'll have to create some comment thresholds to make the comment rating system useful. When comment moderation is enabled and the thresholds are created, users will find another comment control panel option for selecting thresholds. They'll use the thresholds you enter here to filter out comments with low ratings. Consequently, you'll probably want to create more than one threshold to give users some flexibility in filtering comments.</p>
+<p>When creating the thresholds, note that the <i>Minimum score</i> is asking you for the lowest rating that a comment can have in order to be displayed.</p>
+<p>To see a common example of how thresholds work, you might visit <a href=\"http://slashdot.org/\">Slashdot</a> and view one of their comment boards associated with a story. You can reset the thresholds in their comment control panel.</p>
+
+<h4>Initial comment scores</h4>
+<p>Finally, you may want to enter some <i>initial comment scores</i>. In <i>comment management &raquo; initial comment scores </i>you can assign a beginning rating for all comments posted by a particular permission role. If you do not assign any initial scores, Drupal will assign a rating of <b>0</b> as the default.</p>");
 
   return $output;
 }