Document Spinning

Document Spinning

Generating document variations is called document spinning. The normal spinning behavior is to replace each spintax segment with a phrase randomly chosen from the segment’s set of phrases. When default element attributes are used, structural elements, like line groups and paragraph groups, are produced by randomly choosing a child element. For example, one line of a line group’s lines is chosen at random.

"Whirl" dialog options can change the normal spinning behavior to retain spintax segments so variations can be fed into third party applications that will resolve the spintax. In most cases large blocks of spintax can be created from a document’s structural elements, which allows third party tools to produce output with more variation than with just spintax segments retained. The advanced tab has options to make the output more compatible with HTML.

Spun variations can be written to separate files or appended into one large file, and the output files can optionally be compressed into a ZIP file.

Whirl

Document variations are spun with the "Whirl" dialog, which is popped up with the "Whirl and Write…" menu item of the "Spin" drop down menu. The dialog looks similar to the following picture.

Whirl Dialog

To use the dialog, select the options. Each is described below but briefly they are: How spintax is handled, whether ZIP compression will be used, and whether the variations will be put into one file or kept as individual files. Select options in the advanced tab if HTML compatibility is needed. After the options are selected, choose the name of the file(s) to write, the number of variations to spin, and the directory where files will be written.

The following document is used for examples in the explanations of the dialog options.

Example of retaining spintax

Resolving or Retaining Spintax

There are three options for how spintax is put into a document variation: "resolve", "retain", and "add structural". The last two are used when the generated output will be fed into third party applications that will resolve the spintax.

Resolve

The resolve option causes all spintax in the document to be resolved by randomly choosing one of its phrases. Below is a variation of the example document with spintax resolved.

To draw a pail of water, Jill and Jack went up the hillock.  Jack fell down
and busted his crown and Jill came tumbling after.

Up Jack got and home did trot as swift as he could caper.

The example shows the first paragraph on two lines but this is done for illustrative purposes so the example fits on the page. Actual variations put paragraphs into single lines.

The first paragraph has two line groups, which each produce a line. The example variation shows how a paragraph is assembled by putting two spaces between the lines from its line groups.

The two paragraphs are separated by a blank line, which is the way paragraphs are separated for plain text. Document settings or the "Advanced" tab can be used to put paragraphs into HTML "P" tags.

Retain

The retain option will keep spintax in variations. It will be in standard spintax format, i.e. "{xxx|yyy|zzz}". The spun variations can then be used by another application that will resolve the spintax. A variation with retained spintax follows.

{Jack and Jill|Jill and Jack} went up the {hill|hillock|knoll} to
{draw|fetch} a {bucket|pail} of water.  Jack {fell down|fell over} and
{broke|busted|cracked|fractured} his {crown|head|melon} and Jill came
{falling down|tumbling} after.

Up Jack got and home did trot as {fast|fleet|quick|rapid|speedy|swift} as
he could caper.

Again the paragraphs are wrapped to multiple lines so they fit on the page.

Add Structural

This option will retain spintax and in certain cases the structure of the document will be turned into spintax. If the ‘select mode’ of a line group is set to ‘choose’, which is the default mode, then the line group will be turned into a large block of spintax that randomly selects one of its lines. The same is true of paragraph groups. The example below shows how each line group has been converted to spintax that includes the line group’s lines.

{{Jack and Jill|Jill and Jack} went up the {hill|hillock|knoll} to
{draw|fetch} a {bucket|pail} of water.|To {draw|fetch} a {bucket|pail} of
water, {Jack and Jill|Jill and Jack} went up the {hill|hillock|knoll}.}
{Jack {fell down|fell over} and {broke|busted|cracked|fractured} his
{crown|head|melon} and Jill came {falling down|tumbling} after.|Jill came
{falling down|tumbling} after Jack {fell down|fell over} and
{broke|busted|cracked|fractured} his {crown|head|melon}.}

{Up Jack got and home did trot as {fast|fleet|quick|rapid|speedy|swift} as
he could caper.|As {fast|fleet|quick|rapid|speedy|swift} as he could caper,
Jack got up and trotted home.}

Third party tools can use this output to generate variations even though they do not read whirlDOC format documents. The variations will be much more varied than just retaining the document’s spintax because the third party tools will be able to randomly choose sentences and paragraphs as well as words.

Combining Output

The "Combine Mode" determines whether output variations are kept as separate files or combined into one file. There are three options: "Individual Files", "Combine", and "Combine With Div". The last two produce a single file containing all the variations.

Individual Files

This will put each variation in its own file. The files will be named "xxx_yyy.txt", where "xxx" is the file name selected in the dialog and "yyy" is a number that starts as one and increases for each variation. For example, if the file name put in the dialog is "test" and two variations are spun then the variations will be written to these files:

test_1.txt
test_2.txt

Combine

This option combines all variations into a single file with no divider between variations. The file written will be the file name entered in the dialog. For example, if the file name is "test" and two variations are produced then the file written will be "test.txt". The contents of the file will be something like the following.

To fetch a pail of water, Jill and Jack went up the knoll.  Jill came falling
down after Jack fell down and busted his melon.

As speedy as he could caper, Jack got up and trotted home.
To draw a bucket of water, Jack and Jill went up the hillock.  Jill came tumbling after
Jack fell over and fractured his crown.

As fast as he could caper, Jack got up and trotted home.

The lines have been wrapped so they fit on the page. The two variations are put one after another with no separation.

Combine With Div

This combines all variations into a single text file with a divider between each variation. The number of a variation is put at the end of the divider before a variation. The name of the file written is the same as the "Combine" option. The following illustrates two variations generated with this option.

----------------------------------------------------------------1
To fetch a pail of water, Jack and Jill went up the hillock.  Jack fell down and
fractured his melon and Jill came falling down after.

As fast as he could caper, Jack got up and trotted home.
----------------------------------------------------------------2
Jill and Jack went up the hillock to draw a pail of water.  Jack fell down and
cracked his crown and Jill came tumbling after.

Up Jack got and home did trot as swift as he could caper.

Output Format

The “Output Format” section of the dialog selects whether the output files will be compressed into a single ZIP file or kept as separate files. A compressed file may make it easier to handle a large number of variations when they need to be exchanged between computers.

  • ZIP Text Files: All output files will be combined into a single ZIP compression file.
  • Text Files: Output files will be kept as separate text files.

File Names

The file name field determines the file name of whirled variations and the file name of the ZIP file if one is written. A number will be appended for each variation. For example, if the file name is "foo.txt" or "foo" then first variation will be "foo_1.txt". If a ZIP file is written then the file name of the ZIP will be "foo.zip".

The Advanced Tab

The advanced tab has options for making variations more compatible with HTML. These options are taken from the document’s document settings, which are saved within a document. If the same options are always used when spinning a document then the document settings can be set so the advanced options do not have to be changed. New documents get their initial settings from the application preferences, so if the same settings are used for most documents then the preferences can be used to make sure all new documents have the same initial settings.

Note that changing options in the advanced tab does not change a document’s document settings. It just changes the spinning so it is different than the settings.

The advanced tab looks similar to the image below. It has two sections, one for conversion of special characters to HTML codes and one for changing how paragraphs are outputted.

Whirl dialog advanced tab

Character Codes

The character codes section determines how characters that have a special meaning in HTML are handled. Each option is named for the HTML code that will be used. Selecting an option will convert characters of that type to the HTML code, which is an ampersand followed by the code followed by a semicolon. For example, the "QUOT" option will convert double quotes to """.

Paragraphs

The paragraph style determines whether paragraphs are outputted as plain text or HTML style paragraphs, which is text wrapped in "P" tags. The prior examples in the chapter showed plain text paragraphs, which have paragraphs separated by a blank line. Below is an example of a variation spun with HTML style paragraphs.

<p>Jack and Jill went up the hillock to draw a bucket of water.  Jack
fell over and fractured his crown and Jill came falling down after.</p>
<p>Up Jack got and home did trot as fleet as he could caper.</p>

Quick Whirl

Often only a single document variation is needed so the options of the whirl dialog are not necessary. One way to do this is to use the testing buttons to generate an example in the test pane, where the text can be copied to the clipboard. If a file with the variation is needed then the quick whirl dialog can be used. This dialog is a simplified version of the full whirl dialog. It looks similar to the following image.

Quick Whirl Dialog

The dialog has the same options for retaining spintax as the Whirl dialog. All other options have been removed because they are only relevant for spinning multiple files. The advanced options will be taken from the document’s document settings.

Using the dialog is simple. Select the spintax retention policy then choose the file name of the file to be written.