[CMF-checkins] CVS: CMF/DCWorkflow/help - 002-expressions.stx:1.2 004-actionbox.stx:1.2 011-states.stx:1.2 021-transition.stx:1.2 031-variables.stx:1.2 041-worklists.stx:1.2

[Shane Hathaway]

Update of /cvs-repository/CMF/DCWorkflow/help
In directory cvs.zope.org:/tmp/cvs-serv2493

Modified Files:
	002-expressions.stx 004-actionbox.stx 011-states.stx 
	021-transition.stx 031-variables.stx 041-worklists.stx 
Log Message:
Minor revisions of help docs


=== CMF/DCWorkflow/help/002-expressions.stx 1.1 => 1.2 ===
   'workflow' -- The workflow definition object
   'scripts' -- The scripts in the workflow definition object
 
- 'state_change' objects provide the following 
- attributes:
+ 'state_change' objects provide the following attributes, some of which
+ are duplicates of the above information:
 
    - 'status' is a mapping containing the workflow status. This
    includes all the variables defined in the variable tab with "store
    in state" checked.
 
-   - 'object' is the object being modified by workflow. Same as 'here'?
+   - 'object' is the object being modified by workflow.
+     (Same as the 'here' variable above.)
 
-   - 'workflow' is the workflow definition object. Same as the
-   workflow context, above?
+   - 'workflow' is the workflow definition object.  (Same as the
+   'workflow' variable above.)
   
-   - 'transition' is the transition object being executed. Same
-   as above?
+   - 'transition' is the transition object being executed.  (Same
+   as the 'transition' variable above.)
 
-   - 'old_state' is the former state object. Former status? Is this
-   the same value in the contexts of pre and post scripts?
+   - 'old_state' is the former state object.  The name of the former state,
+   for example "published", is available as 'old_state.getId()'.  (Note
+   that DCWorkflow defines 'state' and 'status' as different entities;
+   the name of the current 'state' is stored in the 'status'.  The word
+   clash is unfortunate; patches welcome.)
 
-   - 'new_state' is the destination state object. Ditto?
+   - 'new_state' is the destination state object.  Use 'new_state.getId()'
+   to access the new state name.
 
    - 'kwargs' is the keyword arguments passed to the doActionFor() method.
 


=== CMF/DCWorkflow/help/004-actionbox.stx 1.1 => 1.2 ===
 
   - isAnonymous
 
- [**Note:** How are these actually used without a TALES expression to use
- them in?]
+  Note that this formatting is done using standard Python string formatting
+  rather than TALES.  It might be more appropriate to use TALES instead.
+  As always, patches welcome.
+


=== CMF/DCWorkflow/help/011-states.stx 1.1 => 1.2 ===
  the possible transitions from that state (and their titles). You can go
  straight to the details of each state and transition from here.
 
- [**Note:** Display bug - you can still see possible transitions that 
- have been deleted, though the don't show up in the action box or on a
- state's properties tab] 
-
  Within a state's properties tab you can set the title, and the
  transitions that are possible from this state from a list of
  all the available transitions created in the workflow's 


=== CMF/DCWorkflow/help/021-transition.stx 1.1 => 1.2 ===
   reviewer adding comments to the review history, but not taking any
   action, updating some variable, or invoking scripts.
 
-  Trigger type - There are three 
-  types:
+  Trigger type - There are three types:
 
     - User actions are the familiar user initiated transitions activated
     by actions in the action box.
@@ -26,13 +25,14 @@
     - Automatic transitions are executed any time other workflow
     events occur; so if a user action results in the content moving
     to a state that has automatic transitions, they will be executed.
-    [*Note:* In what order? Mutually exclusive guards seem necessary.]
+    (You should use mutually exclusive guards to prevent indeterminate
+    behavior.)
 
     - WorkflowMethod initiate actions occur as a side effect when
     a method of the content object with the same name as the
     transtion, and that has been wrapped in the WorkflowMethod class
-    is called.[*Note:* is the core method executed before or after the
-    transition is attempted?]
+    is called.  DCWorkflow executes the body of the method just before
+    the workflow transition.
 
 
   Scripts - Perform complicated behaviours either before or after the


=== CMF/DCWorkflow/help/031-variables.stx 1.1 => 1.2 ===
  
   Variable update mode -- Select whether the variable is updated on
   every transition (in which case, you should set a default
-  expression), or whether it should only update if a transitions or
+  expression), or whether it should only update if a transition or
   state sets a value.
 
   Default value -- Set the default value to some string.
 
   Default expression -- This is a TALES expression (as described in
-  Expressions) and overrides the default value
+  Expressions) and overrides the default value.
 
   Guards -- See the "Guards" section. 
 


=== CMF/DCWorkflow/help/041-worklists.stx 1.1 => 1.2 ===
   that urlquotes that query so it can be passed straight to the search
   page. This way, the work list count and the number of items on the 
   search page will be the same as they are derived from the same
-  query string, defined in one place.]
+  query string, defined in one place.
+
+  Reply from Shane: work lists already exercise the catalog too heavily,
+  and most people don't understand their purpose.  Expanding their
+  capabilities further could impact performance.  I think perhaps
+  the UI should instead display work lists on a user's home page rather
+  than the actions box, which would open up new possibilities.]
  
  The guard fields are described in detail in the "Guards"
  section. It's probably better to avoid using permission and role
@@ -57,8 +63,7 @@
   - Whether the user can view content which is in that
   state
 
- This has some unexpected 
- consequences:
+ This has some unexpected consequences:
 
   - If you have several workflow that use the same state variable,
   and similar state names, and each has a work list on, say, the