This tutorial article explores some of the features in Storyspace 3 which make it quick and simple to turn long passages of text into structured hypertext by ‘exploding’ them, and which allow you to enhance your documents with progress bars and summary tables.

Exploding text

Although authoring content directly in Storyspace is the best way to write hypertext from scratch, in many cases you will need to bring in possibly quite substantial amounts of text which have already been written. How you break that up into writing spaces will determine how much time you have to spend post-processing that content.

Before importing text, you need to think through how Storyspace is going to segment it into writing spaces. I have chosen poetry to illustrate this, as it is (often) naturally divided into stanzas or verses, which are likely to form appropriate writing spaces.You may be converting from other formats such as LaTeX/TeX or text extracted from PDF files, in which case you might like to massage the text first using a powerful text editor such as BBEdit, or using the wonderful utility TextSoap. Placing custom markup to indicate intended divisions can be invaluable.

In a new Storyspace document, double click on the Map view to create a new writing space, and in the Outline view switch to Edit mode. Drag and drop or copy and paste the whole of the poem into that writing space.

Selecting the writing space in the Map view, use the Explode… command in the Note menu to bring up options for generating the individual writing spaces.

In this case, the First Sentence contains the intended title, but the default setting to break the text at paragraphs would create a separate writing space for each line in the poem, as indicated at the bottom right of the window. We want to break it into stanzas rather than lines.

To accomplish that, change the radio button at the top to Break at delimiter, which displays a text entry field into which we can try different delimiters. This is wonderfully interactive: you can try delimiters and see the example change and the resulting number of writing spaces, shown at the bottom. In the case of stanzas in plain text, a single newline delimiter \n would again break the text into lines, but a double newline \n\n is just perfect.

Supported delimiters include:

• \r for return
• \n for new line
• \t for tab
• any custom character(s)

each of which can be deleted during the explosion, or left in the text.

Once you are happy with those settings, click on the Explode button to generate the writing spaces.

When exploded, you will find the resulting single-stanza writing spaces inside a container inside a container. Their container is conveniently set to use a prototype Exploded Notes, which itself is placed in a container named Prototypes.

Opening the outermost container named according to the original writing space, here whole text, shows a nested container named exploded notes.

Inside the exploded notes container, each writing space now contains a single stanza from the original imported poem, and they are arranged in the order in which they were found in the original text. You can now link and edit the writing spaces as you wish.

Making a progress bar using the plot feature

The plot feature in writing spaces is inherited from Tinderbox, where is has more obvious benefits. It does have some quite neat applications in Storyspace, though. One is to provide feedback to the reader of their progress in a hypertext document, and an obvious way to do this is with a progress bar. This could be based on the proportion of writing spaces visited, or perhaps the number of clues correctly identified in a murder/mystery story.

Using the same exploded writing spaces just produced, I decided to use plot to inform the reader of their progress through those stanzas. From the last view of the individual writing spaces, click on the whole text container in the Breadcrumb Bar of the Map view to move up to their container. With that container selected, open the Inspector, and switch to the Appearance pane within it, and the Plot tab.

Enter the formula for the plot as
sum_if(child,$Visits,1)
which checks whether each child writing space within that container has a non-zero value for its Visits attribute. If it does, it increments one to its running total, yielding the total number of child writing spaces which have been visited.

Set the Pattern to bar, the Minimum to 0, and Maximum to 31 (the total number of child writing spaces). For this type of progress bar, the colours are set not in the Plot tab, but in the Interior tab. There I set the main Color to a number 2 grey, and the Accent to green, which provides the effect that I want. It is worth experimenting with these settings.

You can then open the container and visit its writing spaces, periodically moving back up to observe the effect on the progress bar of the container. Check that the formula works correctly, so that multiple visits to the same writing space do not increment the bar, and so on.

Adding a Summary Table

Instead of displaying a progress bar on the exploded notes container, it may be more helpful to list its contents and the number of times that each individual stanza has been visited. This can be accomplished very easily using a Summary Table.

To add a Summary Table, set the container’s colours back to something close to their default. Then click on the Summary Table icon at the top left of the container’s icon in the Map View. This will produce the Summary Table Properties editor, into which you should enter some properties to summarise, and their titles.

In this case, I have added three: the expression
$Text.paragraphs(1)
to provide the (Roman) numbering of that stanza, the WordCount attribute which gives the number of words in each stanza, and the total number of visits taken from the Visits attribute. Add these using the + button, and reorder them by dragging and dropping. You can then adjust the proportions of the icon in the Map view so that this Summary Table is shown clearly and completely.

Here are the two completed Storyspace 3 documents, the first showing the progress bar, and the second use of the Summary Table: explodingpoetryF

Happy hypertexting!