From 6c67b0dbdab7d2211ac3cd0ae576f2927434534c Mon Sep 17 00:00:00 2001
From: Timo Stollenwerk <timo@zmag.de>
Date: Fri, 15 Oct 2010 14:49:54 +0000
Subject: [PATCH] Update workflow documentation. we are not there yet.

svn path=/plone.app.discussion/trunk/; revision=40648
---
 docs/source/workflow.txt | 62 ++++++++++++++++++++--------------------
 1 file changed, 31 insertions(+), 31 deletions(-)

diff --git a/docs/source/workflow.txt b/docs/source/workflow.txt
index ceed267..caed6c4 100644
--- a/docs/source/workflow.txt
+++ b/docs/source/workflow.txt
@@ -9,56 +9,56 @@ workflows.
 Introduction
 ============
 
-Workflow and permissions...
-
-
-Workflow
-========
-
-plone.app.discussion ships with a simple one-state workflow and a review 
-workflow for comments:
+plone.app.discussion tries to use the default Plone permission and workflow
+engine as much as possible. plone.app.discussion ships with a simple one-state 
+workflow and a review workflow for comments:
 
 1) **Comment Single State Workflow**: 
 
-   Essentially a workflow with no transitions, but it has a Published state, 
+   Essentially a workflow with no transitions, but it has a published state, 
    so portlets and applications that expect that state will continue to work.
-  
-  
+
 2) **Comment Review Workflow**: A simple review workflow for comments
     
-    ...
-
+   A simple review workflow that comes with two states (pending and published)
+   and a single transition (publish).
+    
+   The 'pending' state is the initial state. 'published' is the state where the
+   comment is visible to everyone and non-editable.
+    
+   The 'publish' transition is protected by the 'Review comments' permission.
+    
+   ::
+    
+     * --> [pending] -- {publish} --> [published]--> *
 
 .. note:: For a general introduction to workflows in Plone see: 
           http://plone.org/documentation/kb/creating-workflows-in-plone/
 
 
-Comment Single State Workflow
------------------------------
+Custom comment workflow
+=======================
 
-...
+You can create and enable any custom workflow on the "comment" content type. 
+Though, there are some special hooks in plone.app.discussion that check if the
+workflow that is enabled for the "comment" content type has a 'pending' state in
+order to do the following things:
 
+  1) A portal message will be shown to the user after posting a comment, if
+     the comment just entered the 'pending' state.
 
-Comment Review Workflow
------------------------
+  2) A message is shown to the user if he/she accesses the bulk moderation view 
+     and workflow is enabled for comments that does not implement a 'pending'
+     state.
 
-The comment review workflow comes with two states (pending and published) and
-one transition (publish).
+  3) A moderator will only be emailed when comment moderation is enabled in the
+     discussion control panel and the comment workflow contains a 'pending'
+     state. 
 
-The 'pending' state is the initial state. 'published' is the state where the
-comment is visible to everyone and non-editable.
-
-The 'publish' transition is protected by the 'Review comments' permission.
-
-::
-
-  * --> [pending] -- {publish} --> [published]--> *
-
-           
+          
 Permissions
 ===========
 
 "Review comments" permission, by default "Manager" and "Reviewer"
 
 "Reply to item" permission, by default "Manager" and "Member"
-