Much printed non-fiction is already decidedly non-linear, as it is interspersed with notes and/or citations of references. Before embarking on any significant non-fiction writing in Storyspace or any other authoring environment, it is essential to explore how notes and references can and should be handled.

I will start with notes, which are the more generic, and first ask whether they remain a useful feature in hypertext. By notes (which includes sidenotes, footnotes, and endnotes) I mean short textual asides, which are not part of the main content by virtue of their limited relevance, or specialised nature. We anticipate that many, probably most, readers will not want to see the contents of a note, at least at their first reading, but that that content needs to be provided without getting in the way of the main thread.

For example, I could here wax lyrical about Edward Tufte’s predilection for long sidenotes, a condition from which I suffer too. But, as this is not directly relevant to this account, it is best to hive it off into a separate writing space. And that is one of the main differences between linear text and hypertext: the convenience of moving to a linked note.

Books and papers have the problem that placing a note on the same page as the text referring to it reduces the space available to the main content, and complicates page design. But placing notes at the end of each chapter, or at the end of the whole work, is disruptive when a reader does wish to refer to a note.

Hypertext has no such limitations: a note will simply be a linked writing space from the main flow. The reader is invited to visit it if they wish, and once they have done so, will be returned to the original writing space. That is easy to design and implement in Storyspace 3.

References are both more complex, and have already ingrained protocols. In the physical and natural sciences, although references may work similarly to notes, they do so in many-to-one relationships; a single reference may be cited many times in different parts of a book or paper. The content of the reference is usually discussed in the main flow of text, rather than as an aside.

In the humanities and some of the ‘softer’ sciences, references may largely be relegated to short discussions in notes, where the citation and reference are both given in full. In that circumstance, I would consider them to be notes rather than simple references.

The above examples give an idea as to the range of common referencing protocols. The top excerpt shows the use of numbered references, as is almost universal in papers published in physical and natural science journals. Sometimes the reference number is given in a superscript, which (in electronic papers, at least) is often barely visible. It is also widely acknowledged – and demonstrated by Wikipedia referencing – that such superscripts are difficul targets for accurate clicking.

Below that are some numbered endnotes from a humanities paper, showing how they include both aside comments and references. Towards the bottom are two examples of more readable referencing systems based on authors and year, which are an alternative to simple numbering, and enhance rather than disrupt the content.

Currently Storyspace 3 is not as well-equipped as Tinderbox for implementing either of the two common science systems of referencing, as they require a many-to-one link from the main text to each reference, which returns to the original location in the main text. That is supported in Tinderbox, but non-trivial to implement in Storyspace 3.

It is also worth briefly considering the best reference manager: for either Storyspace 3 or Tinderbox, this is without doubt Bookends ($59.99 direct from here, or £44.99 in the Mac App Store). Aside from its own impressive capabilities, Bookends is strongly integrated with Storyspace and Tinderbox, giving you excellent choices about how you incorporate references stored in its database. If you are still in doubt, try the downloadable demo version.

Implementing notes, or references as notes

These are a classic case for the use of prototypes and containers, and for the appropriate use of attributes to contain the component parts of each reference.

My own choice is for a family of prototypes representing each type of reference: journal article, book, thesis, report, etc. Although you could create an ancestral prototype for them all, in true object-orientated programming style, I think the benefits of that are largely theoretical, as there would be few unmodified attributes inherited from the single ancestor. For this workthrough I will avoid committing myself and just implement a single prototype for journal articles.

If you are unsure of how best to implement this, and have Tinderbox to hand, a neat way to cheat is to use its recent Footnote feature, and see how that appears when you open a saved TBX document using Storyspace 3 (which currently lacks such footnotes). There are two alternatives: to put the footnote writing space as a sibling of the main writing space, or as a child, in a container. As we are likely to have many notes or references, the latter is probably preferable in most cases.

The only other preparatory advice is not to be tempted to use the References attributes in Storyspace 3 to store the elements of a reference. These are intended for use when importing from Bookends, and seem to behave in a manner which is tailored for that purpose: they persistently terminate in a semi-colon, which gets frustrating when trying to use them, and if you were to import references from Bookends, you could find that trampling over your own implementation.

Workthrough

With a new Storyspace document, first create the prototype writing space named journal, for references to papers in journals. Using the Document Inspector, create the User attributes you will need to store the elements for each journal reference: mAuthors, mDate, mIssue, mJournal, mPages, mTitle, and mVol, each of string type. As you add them in the Document Inspector, ensure that each is made a Key Attribute for the journal prototype, then using the top + Add Key Attributes button, add OnVisit and Caption attributes as key.

I think that it can be useful here to automatically build the Text and Caption content of each reference writing space from its user attributes. This gives the writing spaces in your main thread the ability to access information from each of the references readily. So construct an OnVisit action which will first create a Caption along the lines of Adams & Brown (2015), as a short and informative citation, and then concatenates the rest of the reference material to form the full information in Text:
$Caption=$mAuthors+" ("+$mDate+")"; $Text=$Caption+" "+$mTitle+". "+$mJournal+" "+$mVol+"("+$mIssue+"): "+$mPages+"."
or however you wish to format the Caption and Text.

Your journal prototype is now ready for you to create some example references.

First, though, create the container for them: create a new writing space and name it refs. Then create another new writing space for your first reference. Drag and drop that reference writing space onto the refs one, in the Map view, and refs changes to be a container, holding that first reference.

Double-click in the container area (the blank enclosed area below the container title) to open the container and see the first reference. Note how the top of the Map view now shows the container hierarchy, confirming that you are inside the refs container.

Click in the Map view icon’s lower right tab to set the writing space’s prototype to journal, and fill in some sample information to its attributes. Then deselect the writing space by clicking away from it, and select it again. Its Text and Caption attributes should now be filled automatically from the other attributes, and the Caption displayed on the writing space icon shown in the Map view. Here I have enlarged the icon sufficient for it to show the reference Text, and added a Badge to the prototype – you can use different badges for different types of references or notes.

Click on the left element in the top bar of the Map view (here named notesrefs1) to move back up to the top level of the document. Next create an example writing space from the main thread, which will call and link to that example reference. Create a new writing space, calling it MainThread1, and putting some example text in it which cites the reference.

Now create a text link from the Text citation of that reference to the reference’s writing space. Because the latter is not visible at present in the Map view, as it is inside a container, you need to do this carefully, using both of the turquoise parking spaces provided. The one on the right, just to the left of the current writing space Title, contains the text, and is the Text Link Parking Space. To add the relevant text to it, simply select the text in the Outline view (in Edit mode). The parking space then changes to show the letter T, indicating that the selected text has been parked in it.

If you were linking that directly to a writing space now visible in the Map view, you could drag from that parking space straight to the writing space icon in the Map view. As you cannot see that icon, but will have to open its container to see it, you must now drag from the Text Link Parking Space to its opposite number on the left, at the top of the Map view, to park the link in the Main Parking Space. Once parked, that will also change to show a T.

Then double-click in the refs container area to open it, and locate the reference’s writing space. There, drag from the Main Parking Space (left) to the reference’s writing space, and drop the link there to complete the process. A floating window will appear offering to make that link, as a text link (i.e. from the original selected text), which you should accept.

The link from the reference writing space back to the main thread is not a text link, but a basic (plain) one. Again you use the Main Parking Space (left) as an intermediary, as you cannot see the destination writing space in the Map view. Drag from the main link connector (downward arrow) of the reference writing space icon up to the Main Parking Space (at the left), switch the Map view back up to the top level notesrefs1, and drag from the Main Parking Space down to the MainThread1 writing space. The window will pop up offering to make the link, which this time is not a text link, and now the two writing spaces should be correctly linked.

Switch the Outline view to Read mode, and test this out. Open the MainThread1 writing space, and the citation should appear in blue, indicating that it is a text link. Click on that, and you should be taken to the full reference. Press Return from there, and you should be taken back by the plain link to MainThread1.

Conclusion

This works very well for notes of all kinds, and the humanities forms of note-references. The problem with references as generally used in the sciences is that, whilst you can have many citations linking to the same actual reference, the only ways to return the reader to the correct writing space (the one from which they linked to the reference) involve hand-coding guarded links for each reference, or perhaps non-trivial scripting.

In contrast, Tinderbox now offers the Go Back command (shortcut Command-‘), which would offer Storyspace a simple option for handling this. In fact, Go Back is a valuable command for any reader who arrives at the end of a link thinking that they have come to the wrong place, and just wants to go back to where they were. An alternative would be for following a link to be an undoable command, allowing you to Undo instead of Go Back.

I also rather hope that Mark Anderson or another more experienced user can perhaps suggest an easy solution to this return link problem.

As ever, my completed document is free to download from here: notesrefs1

Happy hypertexting!