Storyspace Reader: a tutorial, 3

My first two tutorials should have given you a good idea of how to use Storyspace Reader’s tools, how to work your way through a hypertext document, and how to customise its settings. This tutorial follows up on navigation, showing you advanced techniques for dealing with more complex hypertext in the Map view.

To try this tutorial for yourself, you will need a copy of Storyspace Reader, available with the previous tutorial file here: falloficarus
and the additional example document here: TreesInTheLandscape3

When you have downloaded and unzipped them, move the app into your Applications folder, and the document(s) into your ~/Documents folder, or a folder somewhere within it. Open the Storyspace Reader app, and using the Open command in its File menu, open the example document named TreesInTheLandscape3.tbx which you have just unzipped. Keep its original Zip archive for the moment.


Adjust the contents of the Map view until the upper section of tiles is comfortably visible in the view, then click/tap anywhere in the text view, or press the Return key, to move on to the about writing space as shown.

The about writing space has two types of links leading from it: there are five text links, which take you from the blue text to their respective linked writing spaces, and a plain or default link which is followed when you click/tap elsewhere, or press Return. On the Map view, the plain link (which takes you down to outro) is shown with less frequent breaks in its line, the text links with more frequent breaks, so that you can distinguish them.


So when you click on the blue text This book, you are transferred to the writing space named book introduction. Note the effects this has on the links shown in the Map view: the only link from this new writing space takes you back to about, and that link is shown as the default link in the map.

Click/tap or press Return to follow that plain link back to about, and you can repeat this with the other text links from there, watching how the Map view responds.


In the about writing space, click/tap anywhere away from blue text links, or press Return, and you move on to outro. Adjust the position of the tiles within the Map view so that you can now view the lower set of tiles, including chapter 1, all the way down to Gainsborough and Poussin 2. outro has only a plain link, the default, to take you down to chapter 1. Follow it.


This section of hypertext has been structured so that it must be read in a didactic or pedagogic fashion, as if a student textbook. You have to visit each of its sections in order before you can visit the next one, and you can only access the in-depth writing spaces when you have visited all the spaces shown in this one. This is accomplished by links with guard fields, which are shown in the Map view.

When you first arrive in chapter 1, there is only one link which is open to you: clicking/tapping on the top image (Rubens) in the text view will take you to Rubens 1. The other four images also have links, but at present you do not satisfy the conditions for those links to be open to you. Those links are shown in the Map view with an open diamond with a line across it, to show that the links exist but are not yet open.

If you hover the pointer over the images in the text view, you will notice that it changes to a hand with pointing index finger when over the top image (Rubens), but remains an arrow over the lower images: this indicates that only the top image is clickable as a text link.


Click or tap on it, and the link will take you to Rubens 1. You will now notice that the previously-open diamond on the link to Rubens 2 has changed to become filled: this indicates that the guard condition is now satisfied (you have opened Rubens 1), and when you return to chapter 1, its image will now be activated as a link to take you to Rubens 2.

However, Rubens 1 has two other links, to Rubens Landscape and Rubens Landscape cap, which are not open to you yet, and are still marked with open diamonds.


Click/tap or press Return to move back to chapter 1, and you can now follow the link on the second image in the text view to see that item.


Once you have visited each of the links from the images in chapter 1, all the guards from that writing space are now open, and their links fully functional.


So too are the two links from Rubens 1: return to that writing space now, and you will see its text view has changed. The image now links to Rubens Landscape, and blue text has appeared reading Details, which is a text link through to Rubens Landscape cap. The contents of the text view may change according to the state of any guards on links from its content.

If you now close this hypertext and open it again, because you as a reader have already completed the required sequence of reading, all the guards remain open. To return to the state in which you first opened it, with its guards closed, you will need to open a fresh copy of the document, something readily done by unzipping the original download again.

Text links, guards, and other features of links in Storyspace are very sophisticated, and hypertext authors can use them to create many different effects. These can include the sequential revelation of clues in a detective story, interaction in which your reading responses modify the plot, and more. Try implementing those in iBooks, Kindle, or plain HTML.

For the insatiably curious, this article is a Storyspace tutorial which explains how that hypertext document was created, and how those guards work.