Repeats with !Groups!

    Frequently there is a connection between a <<*Repeat*>> prompt at the 'top' of a document with elements further down. For example if there are 'three' shareholders accounted for at the top of the document, three additional text blocks may be needed further down in the document to account for the number of shares each holds. The various <<*Repeat*>> blocks can be tied together with a  common !groupname!

   Structure:  <<*Repeat*!groupname!*(text1)>> . . . <<*Repeat*!groupname!*(text2)>>.

   When encountered during a document assembly session, Pathagoras will ask "How many times do you want to repeat (groupname)?"

   Example (A 'repeat ask' is placed at the top of the document. It's sole purpose is to ask 'How many shareholders?"  If the repeat ask is not included, the 'How many shareholders?' question will be asked when Pathagoras encounters the first substantive 'repeat block' ):

   When encountered during a document assembly session, the very first line (the repeat gatherer) causes Pathagoras to ask for the number of shareholders. It will use the answer further down the document to duplicate the text between the remaining << and >> markers the designated number of times. Of course, all [variables] inside any repeat block will be properly incremented.

   Here the result of the answer to "How many shareholders?" is 3.:

The !GroupName! that you assign to a Repeat block can be shared with subsequent <<*Options*>> blocks carrying the same name. Some restrictions apply. If you want the Repeat value to control a subsequent Option,

1.You must set the Repeat Value first. It must be set via an <<*AskRepeat*> question at the top of the document

2.The number of choices you can set for the <<*Options*>> block can be 3 and only 3. While the actual text can be anything, the nature of the text must be as follows:

•The first choice must reflect the text you want in the document if the Repeat value is 0.

•The second choice must reflect the text you want in the document if the Repeat value is 1.

•The third choice must reflect the text you want in the document if the Repeat value is 2 or more.

•The 'reason' for this rule is not necessarily obvious, so here is our stab at an explanation:
 
The primary interplay of a Repeat value to a subsequent Options block is to set noun to verb consistency. In English, 'None are', but 'One is' and 'Two (and three, four, etc.) are." Plus, words like "in equal shares" would apply to an estate distribution to two or more children, but not to 0 children or to one child. Other examples abound that suggest that 3 choices can address the full range of possibilities.
 
Further, it simply would not be reasonable (or practical) for a document author, faced with a possible repeat of 100 shareholders, would have to compose 100 separate choices in an Options block.

•Our surveys suggested that 3 is the right number.

Example:

<<*AskRepeat*!Children!*>>

<<*Options*!Children!*There were no children born of our marriage./One child, namely [ChildName], was born of the marriage/There were <<*Repeat*!children!Return*one>> children were born of the marriage and their names are <<*Repeat(and)*!children![Child]>>>>

3.Not so much a rule, but strong advice: Don't accidentally reset the Repeat value by creating an *AskOptions* or *AskOptional* prompt with the same groupname. This will cause the Repeat value to be overwritten.

4.You can avoid the above restrictions simply by having an Options !groupname! that is different from the Repeats !groupname!.

The use of !Groups! is found in other Pathagoras routines. See Variables(!Groups!) and Options(!Groups!)

 If you want to return to the editing screen the spelled out value of a number that has previously been assigned to a !groupname! for a Repeat, you can do so by enclosing the !groupname! within double angle brackets. E.g., from the above examples, <<!shareholders!>> will return 'three' to the screen if '3' was the answer to the 'How many shareholders are there' prompt higher up in the document.