Intro Tutorial, Part 1

Introductory Tutorial, Part 1

This tutorial gives detailed, step-by-step procedures for creating a simple whirlDOC document made from the first two lines of a nursery rhyme. Even though the document is trivial, its creation explains the basics of the whirlDOC document structure, the usual process for making documents, and the application features needed for the general use of whirlDOC. A thorough explanation of these subjects is given in the manual chapters about documents, the document editor, and document editing., The advanced techniques chapter demonstrates more complex subjects, like deletion of spintax and changing element attributes.

Document Creation Steps

whirlDOC documents are typically created with a three step process. The initial text is imported or written, sentences and paragraph variants are created, then spintax is added. This process is depicted below.

Document Creation Steps

The first step is to create the initial text. It can be written from scratch or imported from a text or HTML file. This tutorial shows the text being written starting with a blank document while the advanced techniques chapter demonstrates importing various types of text files.

While whirlDOC uses spintax for document variation at the word and phrase level, structural variation is done with variant sentences and paragraphs. Making these variants is step two in the process. The variants usually have the same meaning expressed in different ways. A document with a good set of variants can be spun into variations that appear very different from one another but still convey the same information, which is the purpose of a whirlDOC document.

Spintax segments are added as the last step. Each segment is a set of phrases, which are usually single words, one of which is chosen at random when generating a document variation. Adding spintax is done by finding phrases in a document that can be replaced with a set of synonym phrases, a phrase set. This is usually done last because whirlDOC makes it easy to find a phrase that appears many times throughout a document and convert all its instances to the same spintax. Since variant sentences and paragraphs typically use many of the same words and phrases, adding spintax last allows spintax to be added to all variants at once instead of doing each variant individually.

The Document Editor

The image below portrays the document editor. The document being edited is displayed on the right in the edit pane. On the upper left is the spintax panel for displaying, editing, and creating spintax segments and their phrase sets. On the lower left is the attribute panel, which contains dialogs for editing a document’s attributes. This tutorial only uses the editing pane and spintax panel.

whirlDOC editor screenshot

The following picture of the editor labels the features used by the tutorial. These features are detailed in the document editor pages, but the use of most are straightforward and demonstrated in this chapter.

Editor features used by tutorial

Document Structure

The editor’s document display shows the structure of the document being edited. Documents are a hierarchy of elements. At the top level is a series of paragraph groups that each contain one or more paragraph variants. Paragraphs are a series of line groups that each contain one or more line variants. Lines, which are usually sentences, can have spintax segments. How the editor depicts this is shown below.

Display of document elements

The children of an element are bracketed and indented to make the relationship with their parent more evident. Except for lines, elements are indicated with a small icon, which can be clicked to fold and unfold a document section. These icons are used throughout the application for functions that deal with that type of element. For example, the icon for a paragraph is used to indicate the paragraph attribute panel. It is also used for the "New Paragraph" button. Lines have a small black square to their left, and spintax is blue and underlined.

The picture above shows a very simple document. The one below portrays a more complex document with two paragraphs within one paragraph group. The first paragraph has two line groups. The second has one. All line groups have two line variants.

Example of document structure

When a document variation of the above document with default attributes is spun, one of the paragraphs is randomly selected. Then one line in each of the selected paragraph’s line groups is randomly chosen. The chosen lines are assembled into a paragraph.

The Tutorial

For the tutorial, a document will be made with a single paragraph and two sentences. Each sentence will have two variants. The first two lines of the "Jack and Jill" nursery rhyme will be used. So the goal will be to produce variations of the following paragraph.

Jack and Jill went up the hill to fetch a pail
of water.  Jack fell down and broke his crown,
and Jill came tumbling after.

The tutorial is presented in the usual three steps for creating a whirlDOC document. The initial text will be written. Variant sentences will be created. Finally, spintax will be added. The document will look like this at the end of each step.

Tutorial at end of each step

Each step will be broken into a series of step-by-step procedures, each of which makes a single document change. For each step the spintax panel is shown on the left and the document in the edit pane is shown on the right. Features that are used, changed, or relevant are pointed out with red arrows.

Step 1: Write Initial Text

The first step is to write the initial text. The nursery rhyme has two sentences that will each be put into a separate line group so the final document will be assembled into a single paragraph. The procedure for writing the text follows.

Steps to Write Initial Text

Writing each line is as simple as typing it into a line element. Operations, like cut, copy, and paste, which are customary for a regular text editor are available. The procedure shows how the enter key can be used to create new lines and line groups. Using the enter key at the end of a line creates a new line within a line group. Using it on an empty line at the bottom of a line group creates a new line group. If this is continued then hitting enter again will result in a new paragraph, and another time will create a new paragraph group. Another way to create new lines and line groups is with the "New Line" and "New Line Group" buttons.

Step 2: Create Variants

One variant for each sentence will be created in step two. The simplest variants to create are grammatical rearrangements. For example, the sentence "She went to the store." can be rearranged as "To the store she went.". With some creativity and a complex sentence, many variants can easily be created, especially if there is less than critical information that can be added or omitted. The steps for creating the tutorial’s variants are portrayed below.

Steps to create variants

Instead of using the enter key like the first step, the creation of new lines is done two different ways for illustrative purposes. The first is made by creating a new line with the "New Line" function then typing the sentence variant in the new line. When the cursor is in the middle of a line, "New Line" creates a new line below the current line. If the cursor is at the beginning of the line then the new line is created above. All the new element functions work like this.

The second sentence variant is created by cloning a line with the "Clone Line" function then using copy and paste to rearrange the text. One feature of selecting text with the mouse is that if the spintax panel is empty or a new phrase set is being created then the selected text is put into the panel. This feature is used for creating spintax. Since it only happens when the panel is clear or contains a new phrase set, this can be safely ignored when copying and pasting because it does not affect phrase sets used by the document’s spintax. The spintax panel can be cleared when it is needed later.