Document Attributes

Element Attributes

The elements of a document, the document’s root, paragraph groups, paragraphs, line groups, and lines, have attributes that determine how document variations are generated when spinning the document. These attributes decide how an element’s child elements are selected, how the selected children are combined, and the probability of selecting a child.

Usually the default settings for elements do not have to be changed. The defaults are set for the typical use of documents. Attributes can be changed to produce different behavior. For example, line groups default to choosing one of their lines at random but the selection attribute can be changed so all lines are selected but put in random order.

Select Mode

The select mode determines how an element selects its children during document spinning. Line groups select lines, paragraphs select line groups, paragraph groups select paragraphs, and the document root selects paragraph groups. There are three possible selection policies, choose one child at random, choose all but put them in random order, and choose all in normal sequence.

To explain each selection policy, a line group with three lines will be used. For each selection policy, a figure is shown with all possible variations separated by black horizontal lines. The attribute panel for the line group is shown set to the selection policy being explained.

Choose One

Select Mode Attribute: Choose

The choose one randomly policy is denoted by the "choose" option on the attribute panel. The image shows the three possible paragraph variations that can be produced by the line group as one of its lines is chosen at random. The chance of choosing a line is determined by the frequency attribute of the lines; this is discussed in the frequency section below. If default frequencies are used then each line has an equal chance of being selected.

This is the default selection policy for line groups and paragraph groups. These defaults makes sense because line groups normally contain sentence variants, one of which is chosen at random for document variations, and paragraph groups normally contain paragraph variants, one of which is chosen at random during spinning.

Random Order

Select Mode Attribute: Order

Random order is set with the "order" option on the panel. This selection policy selects all children and puts them in random order. The figure shows the six paragraph variations that can be spun. The paragraph variations show how a paragraph is assembled by putting spaces between lines selected by its line groups.

Normal Sequence

Select Mode Attribute: Sequence

The final selection policy selects all children and keeps them in their normal sequence. This is set with the "sequence" option on the attribute panel. The illustration shows that only one variation can be generated.

This is the default selection policy for paragraphs because paragraphs typically select all their line groups in the order they appear in the document. The root level of a document also defaults to selecting paragraph groups using this policy.

Icon Arrows Change with Select Mode

The select mode changes the arrows used in the icon to the left of an element’s content. The examples above show this. Hollow arrows are used for random selection, orange arrows are used for random order, and solid black arrows are used for sequence. This allows the select mode of an element to be seen without clicking it to view the attribute panels.

Combine Mode

The combine mode determines how selected children are combined. Children can be combined into a single line with spaces between each child or they can be left as separate lines. The pictures used to illustrate each mode show a paragraph with three line groups, each with a single line. The attribute panel for the paragraph is shown along with the output generated.


Combine Mode: Combine

The combine policy, set with the "combine" option on the panel, combines its children by putting them into one line separated by two spaces. This is the default combine mode for paragraphs.

Do Not Combine

Combine Mode Attribute: No Combine

The "no combine" option on the panel indicates that child elements should not be combined. They are left as separate lines. When whirlDOC spins a plain text variation, a blank line is placed between each line. Document settings can be changed to output HTML paragraphs instead.


When an element’s selection mode is set to choose one of its children randomly, the children’s frequency determines the odds of each child being chosen. The formula is simple. The frequencies of all children are totaled and the chance of a child being chosen is its frequency divided by the total.

For example, if a line group has three lines, the first with a frequency of 1.0, the second with 2.0, and the third with 3.0, then the chance of the first line being chosen will be one in six (1.0 / 6.0). The second line will be chosen one third of the time (2.0 / 6.0), and the third line will be chosen half the time (3.0 / 6.0). The following picture illustrates this.

Frequency Attribute Example

The default frequency of all elements is 1.0, so all children have an equal chance of being chosen unless the frequencies are changed.