From 308b34b7ef49e503e72ec3cdbffc2821f1682355 Mon Sep 17 00:00:00 2001
From: Mike Gerwitz <mike.gerwitz@rtspecialty.com>
Date: Fri, 2 Feb 2018 09:41:01 -0500
Subject: [PATCH] doc: Group documentation

The primary motivation behind this change was documentation of
links.  Developers (including myself---it's been a while) misinterpreted
then as references to existing groups, not arbitrary names.

* doc/program.texi (Defining Groups): New section.
  (Group Styles): Reference to new section.
---
 doc/program.texi | 110 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 108 insertions(+), 2 deletions(-)

diff --git a/doc/program.texi b/doc/program.texi
index 94a1e12..e77efba 100644
--- a/doc/program.texi
+++ b/doc/program.texi
@@ -116,7 +116,7 @@ It also displays question help text (also configured through the XML)
 
 @cindex Group, Styling
 Groups support a number of @dfn{group styles} that determine how
-  they are delimited from other groups;
+  they are delimited from other groups (@pxref{Defining Groups});
   how the elements they contain are rendered and laid out;
   and how multiple indexes are displayed, added, and removed.
 A list of available styles is detailed in @ref{t:group-styles}.
@@ -184,13 +184,119 @@ A list of available styles is detailed in @ref{t:group-styles}.
 @helpwanted
 
 @menu
-* Specifying Predicates::
+* Defining Groups::       Grouping questions and other entities.
+* Specifying Predicates:: Predicating display of entities.
 @end menu
 
 
+@node Defining Groups
+@subsection Defining Groups
+
+@cindex Group
+A @dfn{group} organizes and relates entities.
+If given a @xmlattr{title},
+  a header will be displayed above the group with that title.
+A group may optionally be given a unique identifier@tie{}@xmlattr{id},
+  which is useful for debugging and scripting;
+    any such identifier should be @code{snake_case}.
+
+@float Figure, f:group
+@example
+  <group title="Foo Group">
+    <question id="question_1" ... />
+    <question id="question_2" ... />
+  </group>
+@end example
+@caption{Defining a simple group with a title}
+@end float
+
+@cindex Group, Styling
+Groups can be independently styled in a number of different ways to
+  provide different data representations (@pxref{Group Styles}).
+Style is optional@mdash{
+  }the @samp{default} group displays only the first index of each
+    entity.
+Further styling can be done using CSS using @xmlattr{class}.
+
+@cindex Group, Leader
+@cindex Group, Indexes
+All questions within a group share the same number of indexes;
+  this is accomplished by monitoring the @dfn{group leader}.
+By default,
+  the leader is the first indexable entity in the group (question,
+    answer, or display);
+      this can be overridden with the @xmlattr{indexedBy} attribute.
+This attribute is only practically meaningful if the chosen group
+  style supports indexes (@pxref{Group Styles}).
+
+
+@float Figure, f:group-leader
+@example
+  <group id="leader_override" indexedBy="question_2" style="tabbed">
+    <question id="question_1" ... />
+    <question id="question_2" ... />
+  </group>
+@end example
+@caption{Overriding group leader using @xmlattr{indexedBy}}
+@end float
+
+@cindex Group, Locking
+Some group styles allow the user to add indexes;
+  set @xmlattr{locked} to@tie{}@samp{true} to suppress this feature.
+
+@subsubsection Linking Groups
+@cindex Group, Linking
+Data collection for similar entities may span multiple steps or
+  groups;
+    for example,
+      one group may allow the user to define their risk locations,
+        and a future group may ask for additional information for each
+        of those locations.
+To have all entities within each of those groups share index length,
+  they may be linked.
+
+A @dfn{group link} is an arbitrary name given to a set of groups.
+Each group that wants to be part of the same link must set
+  @xmlattr{link} to the same string.
+The name of the link does not matter@mdash{
+  }it is @emph{not} a reference to a group@tie{}@xmlattr{id}.
+
+@float Figure, f:group-link
+@example
+  <group id="location" link="locations" style="tabbed">
+    <question id="address" ... />
+    <question id="city" ... />
+  </group>
+
+  <group id="underwriting" link="locations" style="tabbed">
+    <question id="diving_board" ... />
+    <question id="rabid_dog" ... />
+  </group>
+@end example
+@caption{Linking groups using @xmlattr{link}}
+@end float
+
+In @ref{f:group-link},
+  each question in @var{location} and @var{underwriting} will have the
+  same number of indexes@mdash{
+    }any time a new index is added to @var{location},
+      @var{underwriting} questions too will gain another index and
+      vice versa.
+There is no limit to the number of groups that can share the same link.
+
+@devnote{Linked groups are implemented such that the union of all fields
+       in each of the groups of a given link are assigned to each of the
+       individual groups.
+     When the leader of any group changes,
+       a new index is initialized for each group field,
+         which (in the case of linked groups) is comprised of all
+         fields in the link.}
+
+
 @node Specifying Predicates
 @subsection Specifying Predicates
 
+@cindex Predicate
 Object predicates (@pxref{Predicate System}) are specified using the
   @xmlattr{when} attribute of certain nodes.
 It must contain a string of references understood by the system