<!-- $Id: README.txt,v 1.1.2.4 2008/10/15 18:08:28 LasseP Exp $ -->
COMMENT_REVISIONS.MODULE


<h3>Overview</h3>

With GB Comment Revisions you get a revision system for comments, like Drupal already offers for nodes.

<h3>Features</h3>
  - Creation of revisions for comments
  - Automatic creation of revisions on edit without action by user
  - Maximum amount of allowed revisions
  - Listed view of revisions for a comment

<h3>Requirements</h3>
comment.module


<h3>Installation</h3>
  1. Copy comment_revisions folder to sites/all/modules
  2. Enable comment_revisions module
  3. Edit settings


<h3>The Setup</h3>
After installing the Comment Revisions module, you can edit the settings here:
<a href="admin/settings/commentrevisions">
Administer -> Site Configuration -> GB Comment Revisions
</a>

<u>You can set the following options:</u>
- Enable automatic creation of revisions
     Use this to activate the automatic creation of revisions. Now everytime a User with the role 'force revision' edits his own comment, a revision is created.
- Maximum number of automatic revisions
     When you enabled the automatic creation of revisions, set this to your needs. The revisions will be deleted when limit is reached. This way you only have the
     newest revisions. I.e. if you set this to 5, only the 5 newest revisions will be stored in the database
 - Maximum number of administrator revisions
   Same as above, only for users with the 'create revisions' and only if it's not the comment of the user. If 0, these users can create an infinite amount of revisions for a comment (use with care).

After you're satisfied with your settings, click on 'Save Settings'.
Your revision system for comments is now up and running.


<h3>Role types</h3>
Comment Revisions offers the following roles.
<ol>
 <li>administer comment revisions
     This is the one who can control the settings page</li>
 <li>create revisions
     This one can create revisions for other users comments.
     Only suitable if he's also allowed to edit other peoples comments.</li>
 <li>willful create own
     This is a special one. People with this role can decide by themself
     if they want to create a revision of their own comment or not. They can also, if automatic
     creation of revisions is turned off, create revisions.</li>
 <li>stash revisions
     This role is needed for users to be allowed to stash a revision. i.e. make it invisible</li>
 <li>unstash revisions
     This role is needed for users to be allowed to unstash a revision. i.e. make it visible</li>
 <li>view stashed revisions
     This role is needed for users to be allowed to view invisible revisions</li>
 <li>revert revisions
     This role is needed for users to be allowed to revert to a revision</li>
 <li>delete revisions
     This role is needed for users who should be allowed to delete revisions</li>
 <li>view revisions
     This role is needed for users to view revisions (of all comments!)</li>
 <li>view own revisions
     Can view his own revisions of his own comments.
     If a User has both, view own and view revisions, the view revision permission will supercede.</li>
 <li>force revision
     Users are forced to create a revision by editing a comment</li>
 <li>except from froced
     If all authenticated users are forced to create revisions automaticly
     you can use this role to exclude users from this.</li>
</ol>

Here are some suggestions:
In a Forum you want users to post comments. Nothing more. But you want to see what they had typed, before editing (Please regard your local law!). Then, the user who is allowed to write posts in a forum should get the "force revisions" permission. The moderators should be able to see those revisions for control. Therefore they also need to edit posts, they should be able to create revisions in order to keep the unchanged version. As a result, the moderators need the "View revisions", "Create revisions", "Revert revisions" and maybe "Delete revisions".

If you do not want to have automatic generation, but still want to use the features for some special cases, you can use the "Willful create own" permission. This user will be able to create revisions for his own comments only, even if automatic generation is turned off.

If you have automatic generation enabled, and want to allow some special users to be out of this generation system, maybe because you trust them, you can use the "Except from forced" permission. If a user with this permission edits a comment, a revision will not be created, even if automatic generation is turned on. This permission does not depend on the permissions "Create revisions" or "Willful create own".


<h3>How to use</h3>
After enabling 'Enable automatic creation of user revisions' a revision of a users comment will be created after editing. If he hasn't got any other roles, only the administrator and allowed users (Role: 'View revisions') can see that there are revisions by the "View Revisions" link in the comments link section. Clicking on that reveals a list of all created revisions for this particular comment.
Having the right roles a user is now able to revert to another revision or to delete a revision.

ATTENTION: Whenever you delete a comment, all of its revisions get deleted too.


<h3>Credits</h3>
Thanks to everyone who ever posted something at drupal.org or other support sites. Also thanks to everyone willing to help in #drupal and drupal-support
