Creating Documents

Document Editing

Steps for Creating Documents

Writing a whirlDOC document is most easily done with the three step process illustrated by the following diagram.

Document creation steps

The first step is to write the original text. Text can be written from scratch or text can be imported. Writing the text first allows the document to be easily read and revised without being cluttered with variant sentences and paragraphs. Just the original text can be concentrated on during this step.

Once the base text is finished, variant sentences and paragraphs are created. This is often done by cloning sentences or paragraphs then rearranging their text so they have the same meaning but different grammatical structure. Sentences or paragraphs that do not need to have a specific order can be set to be randomly ordered by changing element attributes.

Finally words and phrases are converted to spintax. This step is best done last because whirlDOC allows a word or phrase that appears throughout a document to have all instances converted to spintax at once. Variant sentences and paragraphs typically use the same or similar phrases, so doing this step after creating variants decreases the amount of time it takes to add spintax.

Writing Text

Working with whirlDOC’s editor is similar to using a regular text editor. Documents are opened, edited, and saved. A document is displayed as its whirlDOC structure of elements, paragraphs groups containing paragraphs containing line groups containing lines. Entering and revising a line, which usually contains a single sentence should be familiar. It is done just like any other editor. Buttons or repeated use of the enter key is used to create new elements.

Creating, Opening, and Saving Documents

The controls for opening and saving documents are located on the left of the application’s toolbar as well as the application’s "File" drop down menu. The controls are explained by their names except for the importation of text and HTML files. The icons used for the controls are shown below.

File tool buttons

New Document

This creates a new and empty document. The new document will have its document settings initialized to the default values in the application preferences, so the preferences provide a way to make sure all new documents start out with the same settings. The document’s settings can be changed later.

If there are unsaved changes to the current document then the user will be warned.

Open Document

This opens an existing whirlDOC document. Unsaved changes to the current document cause a warning so the user has the opportunity to save the document before it is replaced.


Saves a document using the file name the document was opened with or the file name it was last saved as.

Save As

Saves the document with a new file name. Subsequent use of "Save" will save using the new file name. By convention the file extension used for whirlDOC document’s is ".xwd". If the file name used in the dialog does not have an extension then ".xwd" will be added.

Import Text/HTML

This function imports a text or HTML file, converting it to a whirlDOC document. Three different source types are supported: Text from a local file, HTML from a local file, and HTML from a web site. Each source type has different options. The import dialog when importing text from a local file is shown below.

Text import dialog

Importing Text

When converting text files, it is assumed that paragraphs are separated by one or more blank lines. The text of a paragraph can consist of one line or multiple lines. Each paragraph is put into its own paragraph group, making it easy to create paragraph variants. Punctuation marks are used to split paragraphs into sentences, which are put into their own line groups, making it easy to add sentence variants.

As shown above by the dialog for importing a text file, there are three options for text file types: Plain text, text with spintax, and text with structural spintax. Plain text cannot contain any spintax. The second option, "Spintax," can contain spintax but the spintax cannot contain spintax; this is termed nested spintax. The "Structural Spintax" option allows nested spintax in special cases.

Structural Spintax

The structural spintax option can parse sentence variants enclosed in braces. Each variant is put in the same line group. For example, consider the following text.

{The scaly shark swam.|The slimy snake slithered.}

The above text will be imported as two lines in the same line group instead of a single segment of spintax. The lines can also contain spintax. The text below demonstrates this.

{The {scaly|swift} shark swam.|The {slimy|sneaky} snake slithered.}

This text will be parsed into two lines, each with a spintax segment. Multiple sentences within a block of text can contain variants. Consider this example.

The plant is {green|wilted}.  {The dog is brown.|The cat
is {black|striped}.}  Is the sky blue?  {It is not.|It is.}

With the "structural" import option, this block of text will be made into a single paragraph with four line groups. The first and third line groups will have one line. The second and fourth line groups will have two. Two of the lines will have a spintax segment.

Importing HTML

The conversion of HTML files is rudimentary. The content of all headers (H1, H2, H3, H4, H5, and H6) and paragraphs (P) is extracted from the file. The content of each tag is put into a paragraph in its own paragraph group. Paragraphs are broken into sentences using punctuation marks, and sentences are put into separate line groups. Importing spintax within HTML is not currently supported.

The dialog when importing HTML from a local file is displayed below. A text field for the location of the file is below the source type.

HTML import dialog

Importing HTML from a web site works just like importing from a file. The location of the file on the Internet is entered instead of a location of a file on the local computer. An example of a web page location is "". The "http://" can be omitted. The dialog for importing a web page is depicted below.

Web page import dialog

An Example of Importing

The following example shows importing a text file with no spintax. The three plain text paragraphs have one or more blank lines between them, and each paragraph has two or three sentences. The text file is shown below.

Twas brillig and the slithy toves did gyre and gimble
in the wabe. All mimsy were the borogoves and the mome
raths outgrabe.

Beware the Jabberwock, my son, the jaws that bite, the
claws that catch.  Beware the Jujub bird and shun the
frumious Bandersnatch.

He took his Vorpal sword in hand.  Long time the manxome
foe he sought. So rested he by the Tumtum tree and stood
a while in thought.

The import dialog is very simple to use and is shown below. Select the source type, a text file. Since the example has no spintax in it, select "Plain Text" as the text file type. Then set the location of the file.

Text import dialog

The text file is imported into three paragraphs with the first two paragraphs split into two sentences and the third split into three.

Text file import example

The import section in the advanced techniques chapter has several examples of importing text, including text that contains spintax and structural spintax.

Creating New Elements

Document elements can be created with the enter key. They can also be created with buttons on the application’s tool bar, which are depicted below. In addition, all operations appear in the application’s "Document" drop down menu. Each operation has a shortcut key, which can be seen by looking at the drop down menu.

Document editing tool icons

Using the Enter Key

The enter key can be used to create new structural elements and to split existing ones. This is done by hitting the enter key on an empty line, sometimes multiple times in succession.

Creating Bottom Elements

The graphic below shows how to create new elements at the bottom of existing elements.

Creating bottom elements with the enter key

Step one shows a document with the cursor at the end of a line. Hitting the enter key creates a new line within the line group, which is shown in step two. When a new line is at the bottom of a line group, hitting the enter key creates a new line group below that contains a single empty line. Hitting enter again makes a new paragraph, and the time after that creates a new paragraph group.

Creating Top Elements

Creating new elements at the top of existing ones works just like creating elements at the bottom. Hitting enter when the cursor is at the beginning of a line will create a new line above. Hitting enter on an empty line when the line is at the top of a line group will create a new line group above. The enter key can then be used to create higher level elements. This is illustrated below.

Creating top elements with the enter key

Splitting Line Groups

Line groups can be split with the enter key. To do this create a new line in the middle of a group then hit enter again on the new line. The following image demonstrates this.

Splitting line groups with the enter key

Splitting Paragraphs and Paragraph Groups

Paragraphs are split by creating an empty line group in the middle of a paragraph then hitting enter.

Splitting paragraphs with the enter key

Paragraph groups are split using an empty paragraph in the middle of the group.

Splitting paragraph groups with the enter key

Using the New Element Buttons

The second way to create elements is with the new element buttons, which are "New Line", "New Line Group", "New Paragraph", and "New Paragraph Group". These tools are available on the tool bar and under the "Document" drop down menu. All work similarly. The new element is created below the current location of the cursor unless the cursor is at the beginning of an element, in which case the new element is created above.

The image below shows the two ways the "New Line" tool works. A horizontal line separates the two cases, and the red arrows point out the position of the cursor before the tool is used. In the top case the cursor is within a line. The new line created is created below the line. In the second case, the cursor is at the beginning of the line so the line is created above.

Creating new lines

The following picture shows how the "New Paragraph" tool works the same way.

Creating new paragraphs

Cloning Elements

whirlDOC has tools to clone elements. These are usually used to clone lines or paragraphs but cloning of paragraph groups and line groups is also supported. Cloning is often useful for creating variant lines and paragraphs. The clone tools copy the element the cursor is on and place it below the element copied. The image below demonstrates this. At the top of the picture is a section of a document. Separated by horizontal black lines are the results of using clone line and clone paragraph on the top document section.

Cloning document elements

Creating Variants

The second usual step of writing a whirlDOC document is creating variant sentences and paragraphs. Usually one variant is randomly chosen from a group of variants when spinning a document variation. For example, a line group with three lines has one line selected at random. This behavior can be changed with element attributes so variants are rearranged instead of randomly chosen, which is explained later in the document editing chapter.

For randomly chosen variants, the variants are typically grammatical rearrangements. They maintain the same meaning but are structurally different. For example, take the simple sentence, “The geese flew over the house.” Two variants could easily be created.

The geese flew over the house.
Over the house the geese flew.

The two sentences are simple rearrangements. Beyond trivial rearrangement, another variant could be made.

The geese flew.  Over the house they went.

Going even further by adding or subtracting information that may not substantially alter the sentence’s paragraph, the following variants could be written.

Through the air the geese flew, and over the house they went.
The geese flew.

This leads to a simple sentence having five variant forms, which are shown below.

The geese flew over the house.
Over the house the geese flew.
The geese flew.  Over the house they went.
Through the air the geese flew, and over the house they went.
The geese flew.

More variants could be made for a more complex sentence. To spin a large number of document variations, not many variants need to be created for each element. For example, a document with ten sentences, each with two variants, has 1024 possible structural variations. Adding spintax would, of course, produce even more variations.