Advanced Importing

Advanced Techniques: Importing Files

The advanced techniques chapter is a companion to the introductory tutorial. Small document examples are used to demonstrate features of whirlDOC that were not covered in the earlier tutorial. Each demonstration is self-contained and does not rely on prior ones. The step-by-step procedures are not meant to be done by the reader like the steps in the introductory tutorial. They build upon what was shown there and can be seen as explanations of how to handle more complex situations.

Importing Plain Text Files

While documents can be typed into whirlDOC just like a regular editor, it is often easier to import a text file. HTML files can also be imported from a local file or fetched directly from a web site. This section demonstrates importing a plain text file.

When importing a text file, paragraphs are assumed to be separated by one or more blank lines. Each paragraph is put in its own paragraph group. Paragraphs are broken into sentences using punctuation marks, and each sentence is put in its own line group. The resulting whirlDOC document is ready to create variant sentences and variant paragraphs before adding spintax.

Below is an example text file that has two paragraphs with three sentences in the first and four in the second.

During a cool November the plague started at a military
research facility.  The contagion spread quickly, killing
nearly everyone who caught the disease.  By December the
remnants of city's population found themselves surrounded
by flesh craving zombies.

At first we hid in an apartment building and tried to stay
cool.  The doors and windows proved vulnerable. Food and
water ran low.  We had to move somewhere with resources
that was more defensible.

The import dialog (shown below) is easy to use. Select "Text File" as the source of the import. Select "Plain Text" as the text file type because there is no spintax in the file to be imported. Then set the text file’s file name.

Dialog to import text to spintax editor

When the file is imported, the following whirlDOC document is created. A document variation spun from the document will be just like the imported file. Each paragraph group will generate the one paragraph it contains. Each line group will select its one line, which will be used to make its parent paragraph. The only difference is that when spinning non-HTML output, paragraphs have a single blank line between paragraphs and are single lines with spaces between sentences.

Imported plain text file

Importing Text Files with Spintax

Text files containing spintax in standard form can also be imported. This works just like importing plain text files. Blank lines are used to detect paragraphs and punctuation marks are used to break paragraphs into sentences. Spintax within sentences is then translated.

This example shows the following text file with spintax being imported. The example has two paragraphs, the first with two sentences containing spintax and the second with one line containing no spintax. For illustrative purposes, there are two blank lines between the paragraphs.

{Jack and Jill|Jill and Jack} went up the {hill|hillock|knoll} to
{draw|fetch} a {bucket|pail} of water.  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.

To import the example, the "Spintax" option of the "Text File Type" section is selected.

Dialog for importing spintax

The document below depicts the text imported into whirlDOC. Note that the two blank lines between blocks of text are treated as a break between paragraphs just like a single blank line would be. The import process uses one or more blank lines to find paragraphs. Blank lines at the front or end of a text file are ignored.

Imported text file with spintax

Importing Text Files with Structural Spintax

whirlDOC can import text with structural spintax similar to what can be generated when spinning documents with the "Add Structural" option. The implementation is not complete. Variant sentences can be imported into the same line group, but variant paragraphs are not supported. Sentences can contain spintax. This example uses the following text file.

It was Tuesday.
{He went to the store.|To the store he went.}
{He {drove|went} to the store.|To the store he {drove|went}.}
Water is wet.

{{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}.}

The first block of text ending with the blank line will be imported into one paragraph. It has a variety of different sentence types for example purposes. The first and last lines are single sentences with no variants and no spintax. The second line has two variant sentences with no spintax. And the third line has two variant sentences with spintax.

The second block of text is a more complex paragraph with lots of spintax.

To import the file, the "Structural" option of the "Text File Type" section of the import dialog is checked.

Dialog for importing with structural spintax

The document imported from the text file is shown below. One thing to note is that even though the first block of text has its sentences on separate lines, the block is still imported into a single paragraph. Blank lines are used to detect paragraphs, so a paragraph’s sentences can all be on the same line or on separate lines.

Imported text file with structural spintax