Introduction to whirlDOC

Introduction to whirlDOC

whirlDOC Overview

whirlDOC is a spintax editor and document spinner. The spintax concept is extended beyond words to sentences and paragraphs. It is used to create source documents from which many document variations can be produced. Documents can be as simple as a two or three sentence description or they can be long articles with many paragraphs. Document variations are often used for search engine optimization, which is gaming search engines to give websites better search results. whirlDOC can also be used for many other purposes, like article marketing, producing varied product or service descriptions, and creating variations of boilerplate.


Document variations are usually produced with a technique called spintax.. The word spintax is a portmanteau of spin and syntax. Spin comes from "spinning" a document into variations. Syntax refers to the special syntax used to define spintax within text. An example of this syntax is "{film|movie|flick}".

The concept of spintax is that words are designated as choices between synonyms. For example, the word "film" could be set to be a choice between the synonyms "film," "movie," and "flick." One of the choices is randomly chosen when spinning a document variation.

whirlDOC’s editor makes it easy to add, view, and change spintax. Documents with lots of spintax are easy to work with because spintax segments are collapsed down to single words or phrases, which can be clicked on to see synonyms. This reduces a document that is a cluttered morass of spintax into a document that is as readable as a document without spintax.

Synonyms used in spintax are stored in a thesaurus so they are available to add spintax to future documents with a click of a button. This makes whirlDOC adapt to a user’s unique language patterns. whirlDOC also comes with a built-in "master" thesaurus that contains a large collection of common sets of synonyms so it is simple to start adding spintax to documents.

Beyond Spintax

whirlDOC goes beyond spintax by using variants of sentences and paragraphs to spin documents. One variant in each set of variants can be chosen at random or variants can be randomly rearranged. This produces a large number of document variations that appear considerably different than the source document.

For example, a paragraph could have four sentences, each with two variants. One of the variants for each sentence will be chosen when spinning, so there will be sixteen possible variations of the paragraph. (2*2*2*2 = 16) With spintax in the sentences, the total number of possibilities can be huge.

whirlDOC Feature List

  • whirlDOC makes it easy to add spintax to a document and select, edit, and change spintax synonyms.
  • For documents where perfect grammatical correctness is not needed, spintax can be added to an entire document with the auto magic function. This automatically adds as much spintax as possible without user selection of synonyms.
  • The editor’s display hides spintax so only one phrase is visible, making spintax laden sentences easy to read. Clicking on a spintax segment loads its phrases into an editing panel where the phrases can be viewed and changed.
  • Spintax segments that use the same set of phrases are linked together, so changes to multiple spintax segments can be made at the same time.
  • While editing, the editor dynamically displays the maximum characters that spinning can produce.
  • With a click of a button, a document can be tested by spinning a variation and displaying it in a test pane where it is easily checked for grammar mistakes from spintax or it can be copied then pasted into another application.
  • Documents are structured as groups of sentence and paragraph variants. Choices between variants are made when spinning a document.
  • By changing element attributes, groups of sentence variants can be set so one sentence is randomly chosen from its group or all variants are randomly rearranged. The same can be done for groups of paragraph variants.
  • Sections of the document can be collapsed, often called folded, to make long documents with lots of sentence and paragraph variants more manageable. Folded sections are protected from most spintax editing functions.
  • Document variations can be spun one at a time or in bulk. The resulting files may be compressed into a ZIP file to make the files easily portable.
  • Spun document variations can retain spintax so they can be fed into third party applications that use spintax.
  • In addition to retaining spintax, sentence and paragraph variants can be turned into blocks of spintax so sentence and paragraph variants are retained for use by third party applications even though those applications do not read whirlDOC document files.
  • When spinning, characters with a special meaning in HTML, like double quotes, can be converted to HTML codes. Paragraphs can optionally be wrapped in HTML "P" tags.
  • Plain text files, with or without spintax, can be converted to whirlDOC documents by importing them.
  • whirlDOC can import HTML files from local files or directly from the web.
  • The application comes with a "master" thesaurus, which provides common sets of words for adding spintax to documents.
  • New words and phrases used in spintax are added to a "user" thesaurus. This makes the application adapt to a user’s writing style and specific language needs, like technical jargon and slang.
  • whirlDOC’s built-in thesaurus editor can view and edit its "user" thesaurus. The "master" thesaurus can be viewed with the editor.
  • Thesaurus files may be exported and imported so thesauruses can be exchanged between users. Imported thesauruses can be merged with the existing "user" thesaurus or replace it.

Editor Screenshot

An explanation of the editor and how to use it is given in the introductory tutorial. The document editing chapter details all editor functions. A reduced size image of the main editing screen is shown below.

Spintax Editor Screenshot

Briefly, on the right is a document being edited. The document’s sentences include spintax, which is shown underlined in blue. At the upper left is the panel for editing spintax . At the lower left are dialogs for displaying and changing attributes of the document’s structural elements.

Document Structure and High Level Variation

whirlDOC spins document variations at two levels. Low level variation is done at the word and phrase level with spintax.. High level variation is done by altering the document structure with paragraph and sentence variants. The spun variations can have much greater differences than what can be accomplished with just spintax.

Documents are structured as a hierarchy of elements that is fully explained by the chapter about whirlDOC documents. The diagram below shows the structure.

Document Structure

Paragraph groups contain paragraph variants, and paragraphs contain line groups with sentence variants. Sentences, called lines, contain plain text and spintax segments. The diagram shows a paragraph group with two paragraphs. The first paragraph contains two line groups, both of which have two line variants. The second paragraph contains one line group with two line variants.

The following picture portrays a document in whirlDOC with the same structure as the diagram above. It shows parts of two nursery rhymes. This demonstrates whirlDOC’s method of varying documents at the structural level. Each line has two variants with the same meaning but a different grammatical structure.

Example of document structure

Spintax for Low Level Variation

Spintax is a standard method for producing word and phrase variations in documents. It is used by many other applications. Spintax works by randomly choosing a word from a set of synonyms. In whirlDOC terminology these synonym sets are called phrase sets.

Standard spintax is surrounded by braces with phrases separated by "pipe" characters. An example of text containing a spintax segment with three phrases is shown below.

The {quick|fast|speedy} brown fox...

whirlDOC hides this gory detail so only one phrase of spintax is visible. As the image below shows, the same sentence is more readable in whirlDOC’s editor. The word "fast" can be clicked to put the spintax’s synonyms in the spintax panel where they can be viewed and edited.

Example of displaying spintax

Phrase Sets

The phrases for a spintax segment are bundled as a phrase set. Although the phrases are usually single words, multiple word phrases can be used as well. Phrases should be interchangeable synonyms. They need to be able to be substituted for each other while maintaining near equivalent meaning and correct grammar.

A key concept of whirlDOC is multiple spintax segments in a document can use the same phrase set. This means that multiple spintax segments sprinkled throughout a document can be changed at the same time by editing the phrase set. This makes editing a document’s spintax easy.

The Master, User, and Document Thesauruses

Phrase sets are collected in thesauruses where they are available to easily add spintax to documents. Adding spintax is as simple as clicking a button to find phrases in a document that are also in a thesaurus then clicking another button to convert the phrases to spintax.

whirlDOC keeps three thesauruses, a "master" thesaurus, a "user" thesaurus, and a "document" thesaurus.

The application comes with a built-in thesaurus, called the "master" thesaurus, that contains a large variety of common words and their interchangeable synonyms. It provides a starting point for adding spintax without creating new phrase sets.

The "user" thesaurus begins empty when whirlDOC is first installed. Phrase sets are added to it as documents are edited. This creates a thesaurus adapted to a user’s specific needs and writing style. Technical terms and jargon, slang terms, and phrase sets not in the master thesaurus are entered into the user thesaurus where they are available for adding spintax to future documents. This happens automatically so the user only has to concern himself with editing the document at hand.

Every whirlDOC document contains an embedded thesaurus named the "document" thesaurus. It contains all the phrase sets used by the document’s spintax. This makes documents portable between copies of whirlDOC, no matter what phrase sets are in each copy’s "user" thesaurus.

A Document Example and Document Creation Steps

A simple example will serve to explain whirlDOC documents, the usual steps for creating documents, and variations spun from documents. The first two lines of a nursery rhyme are used. The step-by-step creation of this document is covered in the introductory tutorial.

First the plain text is entered in the editor. This can be done by writing the text in the editor or by importing a text or HTML file. The document is shown in following picture.

Write Initial Text Example

This is how documents appear in the editor. The document’s structure has two paragraph groups, each with one paragraph containing one line group with one line. When spinning document variations, a blank line is usually put between the paragraphs. Document settings can be changed to put paragraphs in HTML "P" tags. The graphic symbols are explained in the introductory tutorial, but the structure should be understandable. The editor depicts the nested document structure shown in the structure picture presented earlier.

The next step is to enter variants for lines and paragraphs. For this example, only line variants are used. Each of these is a grammatical rearrangement of the original line. When generating a document variation, one of the two lines in each line group will be chosen at random. The picture below shows the two line variants added to the document.

Create Variants Example

Spintax is added after line and paragraph variants. whirlDOC makes it easy to convert multiple words and phrases to the same spintax, so it is quicker to add spintax after adding variants.

Add Spintax Example

The above image depicts the example document with spintax added. Spintax is shown in underlined blue, and phrase sets for spintax have been hidden by only displaying one phrase for each spintax segment. This makes lines much more readable than if the spintax was shown with all phrases. To demonstrate this, the text below shows the first line as it would appear with standard spintax.

{Jack and Jill|Jill and Jack} {climbed|trudged|went} up the
{hill|hillock|knoll} to {draw|fetch|get} a {bucket|pail} of water.

This is much more difficult to read and would be more difficult still if spintax segments contained more than two or three phrases.

Finally, three variations are generated by spinning the document. The variations are shown in the image below. They are separated by black dividing lines. Even though the two nursery rhyme lines are simple, there is still a lot of variation. Much more variation would be possible if the paragraphs had more than one line, lines had more than two variants, and variants were used for paragraphs.

Document Variations