Index: openacs-4/packages/assessment/www/doc/grouping.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/grouping.adp,v
diff -u -r1.1.2.2 -r1.1.2.3
--- openacs-4/packages/assessment/www/doc/grouping.adp	25 Aug 2015 18:02:18 -0000	1.1.2.2
+++ openacs-4/packages/assessment/www/doc/grouping.adp	4 Jul 2016 11:33:12 -0000	1.1.2.3
@@ -16,23 +16,23 @@
 <p>The primary key assessment_id is a revision_id inherited from
 cr_revisions. Note, the CR provides two main types of entities --
 cr_items and cr_revisions. The latter are where sequential versions
-of the former go, while cr_items is where the "current" version of
-an entity can be stored, where unchanging elements of an entity are
-kept, or where data can be cached. This is particularly useful if
-the system needs a single "live" version, but it isn't appropriate
-in situations where all versions potentially are equally-important
-siblings. In the case of the Assessment package, it seems likely
-that in some applications, users would indeed want to designate a
-single "live" version, while in many others, they
-wouldn't. </p><p>Attributes of Assessments will include those previously included
+of the former go, while cr_items is where the "current"
+version of an entity can be stored, where unchanging elements of an
+entity are kept, or where data can be cached. This is particularly
+useful if the system needs a single "live" version, but
+it isn&#39;t appropriate in situations where all versions
+potentially are equally-important siblings. In the case of the
+Assessment package, it seems likely that in some applications,
+users would indeed want to designate a single "live"
+version, while in many others, they wouldn&#39;t. </p><p>Attributes of Assessments will include those previously included
 in Surveys plus some others:</p><ul>
 <li>assessment_id</li><li>cr:name - a curt name appropriate for urls<br>
-</li><li>cr:title - a formal title to use in page layouts etc</li><li>creator_id - Who is the "main" author and creator of this
-assessment</li><li>cr:description - text that can appear in introductory web
+</li><li>cr:title - a formal title to use in page layouts etc</li><li>creator_id - Who is the "main" author and creator of
+this assessment</li><li>cr:description - text that can appear in introductory web
 pages</li><li>instructions - text that explains any specific steps the
 subject needs to follow</li><li>mode - whether this is a standalone assessment (like current
-surveys), or if it provides an "assessment service" to another
-OpenACS app, or a "web service" via SOAP etc</li><li>editable_p - whether the response to the assessment is editable
+surveys), or if it provides an "assessment service" to
+another OpenACS app, or a "web service" via SOAP etc</li><li>editable_p - whether the response to the assessment is editable
 once an item has been responded to by the user.</li><li><span class="context"><span class="reg">anonymous_p - This
 shows whether the creator of the accessment will have the
 possibility to see the personal details of the respondee or not. In
@@ -51,7 +51,8 @@
 </li><li>return_url - URL the respondee will be redirected to after
 finishing the assessment. Should be redirected directly if no Thank
 you page is there. Otherwise the return_url should be set in the
-thank you page context, so we can have a "continue" URL.</li><li>start_time - At what time shall the assessment become available
+thank you page context, so we can have a "continue"
+URL.</li><li>start_time - At what time shall the assessment become available
 to the users (remark: It will only become available to the users
 who have at least the "respond" priviledge.</li><li>end_time - At what time the assessment becomes unavailable.
 This is a hard date, any response given after this time will be
@@ -132,8 +133,9 @@
 admin pages, not for end-user pages</li><li>instructions - text displayed on user pages</li><li>enabled_p - good to go?</li><li>required_p - probably not as useful as per-Item required_p but
 maybe worth having here; what should it mean, though? All Items in
 a required section need to be required? At least one? Maybe this
-isn't really useful.</li><li>content_value - references cr_revisions: for an image, audio
-file or video file</li><li>numeric_value - optional "number of points" for section</li><li>feedback_text - optional preset text to show user</li><li>max_time_to_complete - optional max number of seconds to
+isn&#39;t really useful.</li><li>content_value - references cr_revisions: for an image, audio
+file or video file</li><li>numeric_value - optional "number of points" for
+section</li><li>feedback_text - optional preset text to show user</li><li>max_time_to_complete - optional max number of seconds to
 perform Section</li>
 </ul><p>Permissions / Scope: Control of reuse previously was through a
 shareable_p boolean. As with Items and Assessments, we instead will
@@ -145,24 +147,25 @@
 </ul>
 </li><li>Section Display Types (as_section_display_types) define types
 of display for an groups of Items. Examples are a "compound
-question" such as "What is your height" where the response needs to
-include a textbox for "feet" and one for "inches". Other examples
-are "grids" of radiobutton multiple-choice Items in which each row
-is another Item and each column is a shared radiobutton, with the
-labels for the radiobutton options only displayed at the top of the
-grid (see <a href="http://www.epimetrics.com/demos">the SAQ</a> for
-an illustration of this).
+question" such as "What is your height" where the
+response needs to include a textbox for "feet" and one
+for "inches". Other examples are "grids" of
+radiobutton multiple-choice Items in which each row is another Item
+and each column is a shared radiobutton, with the labels for the
+radiobutton options only displayed at the top of the grid (see
+<a href="http://www.epimetrics.com/demos">the SAQ</a> for an
+illustration of this).
 <p>This entity is directly analogous in purpose and design to
 as_item_display_types.</p><ul>
-<li>section_display_type_id</li><li>section_type_name - name like "Vertical Column" or "Depth-first
-Grid" or "Combo Box"</li><li>pagination_style - all-items; one-item-per-page; variable (get
+<li>section_display_type_id</li><li>section_type_name - name like "Vertical Column" or
+"Depth-first Grid" or "Combo Box"</li><li>pagination_style - all-items; one-item-per-page; variable (get
 item groups from mapping table)</li><li>branched_p - whether this Section defines a branch point (so
 that the navigation procs should look for the next step) or whether
 this Section simply transitions to the next Section in the
 sort_order (it may be better not to use this denormalization and
 instead always look into the Sequencing mechanism for navigation --
-we're still fuzzy on this)</li><li>item_orientation - the pattern by which 2..n Items are laid out
-when displayed. Note that this isn't a purely stylistic issue
+we&#39;re still fuzzy on this)</li><li>item_orientation - the pattern by which 2..n Items are laid out
+when displayed. Note that this isn&#39;t a purely stylistic issue
 better left to the .adp templates or css; the patterns have
 semantic implications that the Assessment author appropriately
 should control here.
@@ -172,28 +175,31 @@
 then col</li>
 </ol>
 </li><li>item_labels_as headers_p - whether to display labels of the
-Items; if not, a "grid of radiobuttons" gets displayed. See
-discussion of Items and Item Choices <a href="http://openacs.org/projects/openacs/packages/assessment/design/as_items">
+Items; if not, a "grid of radiobuttons" gets displayed.
+See discussion of Items and Item Choices <a href="http://openacs.org/projects/openacs/packages/assessment/design/as_items">
 here</a>. There are contexts where a Section of Items all share the
-same Choices and should be laid out with the Items' item_subtexts
-as row headers and the radiobuttons (or checkboxes) only -- without
-their labels -- displayed in a grid (see <a href="http://www.cvoutcomes.org/questionnaires/one-questionnaire?questionnaire_id=5">
+same Choices and should be laid out with the Items'
+item_subtexts as row headers and the radiobuttons (or checkboxes)
+only -- without their labels -- displayed in a grid (see <a href="http://www.cvoutcomes.org/questionnaires/one-questionnaire?questionnaire_id=5">
 this example</a>).</li><li>presentation_type - may actually be superfluous...gotta think
-more about this, but there's at least one example:
+more about this, but there&#39;s at least one example:
 <ol>
 <li>ranking - a set of alternatives each need to be assigned an
-exclusive rank ("Indicate the order of US Presidents from bad to
-worse"). Is this one Item with multiple Item Choices? Actually,
-not, since each alternative has a value that must be separately
-stored (the tester would want to know that the testee ranked GWB
-last, for instance).</li><li>what others?</li>
+exclusive rank ("Indicate the order of US Presidents from bad
+to worse"). Is this one Item with multiple Item Choices?
+Actually, not, since each alternative has a value that must be
+separately stored (the tester would want to know that the testee
+ranked GWB last, for instance).</li><li>what others?</li>
 </ol>
 </li><li>item_alignment - the orientation between the "section
-description part" of the Section (if any) and the group of Items.
-Alternatives accommodate L-&gt;R and R-&gt;L alphabets (or is this
-handled automagically be Internationalization?) and include:
+description part" of the Section (if any) and the group of
+Items. Alternatives accommodate L-&gt;R and R-&gt;L alphabets (or
+is this handled automagically be Internationalization?) and
+include:
 <ol>
-<li>beside_left - the Items are left of the "heading"</li><li>beside_right - the Items are right of the "heading"</li><li>below - the Items are below the "heading"</li><li>above - the Items are above the "heading"</li>
+<li>beside_left - the Items are left of the
+"heading"</li><li>beside_right - the Items are right of the
+"heading"</li><li>below - the Items are below the "heading"</li><li>above - the Items are above the "heading"</li>
 </ol>
 </li><li>display_options - field to specify other stuff like the grid
 dimensions ("rows=10 cols=50" eg)</li>
@@ -202,8 +208,8 @@
 Section, caches display code, and contains optional overrides for
 Section and Item attributes:
 <ul>
-<li>item_id</li><li>section_id</li><li>enabled_p</li><li>required_p - whether Item must be answered</li><li>item_default</li><li>content_value - references CR</li><li>numeric_value - where optionally the "points" for the Item can
-be stored</li><li>feedback_text</li><li>max_time_to_complete</li><li>adp_chunk - display code</li><li>sort_order</li>
+<li>item_id</li><li>section_id</li><li>enabled_p</li><li>required_p - whether Item must be answered</li><li>item_default</li><li>content_value - references CR</li><li>numeric_value - where optionally the "points" for the
+Item can be stored</li><li>feedback_text</li><li>max_time_to_complete</li><li>adp_chunk - display code</li><li>sort_order</li>
 </ul>
 </li><li>Section Assessment Map (as_assessment_section_map) basically is
 a standard map, though we can override a few Section attributes