Parallel hypertext: Storyspace metamorphosed 3

Before progressing with my hypertext version of Book 1 of Ovid’s Metamorphoses, for Storyspace and Tinderbox, there are three issues which I’d like to visit.

Tidy tiles

Mark Anderson, probably the greatest expert on these apps outside Eastgate Systems, has kindly pointed out one small blemish in the Map view of my previous version: even when in Read mode, the body text of the bilingual writing spaces leaks into the tile and is displayed as the conditional include code. I had rather ignored that as being a bit too difficult for me to solve, but Mark recommends the simple solution of setting the attribute $MapBodyTextSize to fix this.



To make this easier, I have now made all those bilingual writing spaces use a new prototype, which has $MapBodyTextSize set to 1, which suppresses the display of body text in the writing space tile. By default it is set to 0, which displays it, or you can specify the point size of the text, e.g. 12 for 12 point text.


An alternative might be to use a custom shape for the tiles, as body text is never displayed in those.

Why not explode the text?

Mark also asked a very good question: why didn’t I use Storyspace’s superb feature to explode imported text to generate the Latin and English writing spaces automatically?

If you’re not familiar with the power of this technique, I have written a tutorial on using this to import poetry which is divided into verses. It is a powerful technique which can very quickly convert large amounts of text into writing spaces with minimal effort.

I could have edited my source texts to use a common delimiter between each section destined for a separate writing space, and placed the title on the first line of the section. In this case, although I started preparing to do this, I decided not to, because the work involved in preparing the text before importation and in editing each writing space afterwards would, if anything, have been made more time-consuming. And it was that work which took much of the time.

I had two major tasks to perform on the text before I could even think about importing it into Storyspace: one was to reconcile the line numbering with most other Latin versions of the work, the other to decide where to divide the Latin and its matching English translation. Only when I examined a recent reference copy of the Latin did I discover that the Perseus version had line numbers which differed from that, for almost half the book.

Division of the text into writing spaces was also not simple. This had to be performed at matching points in both the Latin and English versions, although the translation is not sufficiently literal to move directly from one to the other. Some of the sections then had to be tried for length in Storyspace before making final decisions. Finally, the Latin and English writing spaces had to be named to match one another, the name giving the line numbers for the Latin section.

There are times when the process of actually importing the text is the quickest, simplest, and least controversial step!

Debugging and testing

I haven’t looked at these issues before, as my use of Storyspace’s scripting has been very simple, to date. However, one valuable aid for those debugging more advanced and complex scripts, and during user testing, is my Blowhole command tool, available from the Downloads menu at the top of this article.

Storyspace and Tinderbox give access to the command line with the runCommand() command. If you install Blowhole in an accessible path, such as /usr/local/bin, you can trigger it to make a timed entry into the log of a Mac running macOS Sierra: simply use the script
runCommand("/usr/local/bin/blowhole -d 42")
for example to write a default level entry in the log containing the number 42.


Unfortunately issues prevent the writing of arbitrary strings, which would be even more useful, but you can harness this to log the time that a reader enters each writing space. Add that script to the $OnVisit attribute of the prototype of the writing spaces which you want to monitor, then in each one, edit the integer to a unique number for that writing space.


After your test reader has worked through your hypertext, you can then run Consolation, my free tool for browsing Sierra’s logs (from the Downloads page), and filter on Blowhole’s subsystem, which is co.eclecticlight.blowhole. You’ll then see accurate timings for the moment that reader opened each writing space, with the integers telling you which writing space they visited, and the sequence. If you’re developing a ‘serious’ hypertext document, this information can usefully augment your reader-testing.

Adding the paintings

My major outstanding task for the parallel hypertext version was to add the paintings which I showed in my articles here. Out of the various options for including them, I have gone for the simplest, for author and reader, which is to place each image in its own writing space, and to create text links from the relevant section of parallel text out to the painting, then back into the original writing space.

As usual, I had to be meticulous in preparing the images of the paintings. Using GraphicConverter, I checked their resolution and set it to a standard, here 72 dpi, then scaled the image so that its longer dimension is 1024 pixels. This ensures that the 21 images do not inflate the document size too severely, and readers can keep windows to a reasonable and consistent size, but still view each painting in its entirety.

I created a prototype for the writing spaces containing paintings, although at the moment this only differs in the colour of the tile, and they are all placed inside a container named Gallery. I then added the captions and relevant text, and formed text links out to them from the appropriate section of parallel text, and back again to the same point.


The only slight delay in completing this resulted from the fact that I had to browse the writing spaces in Read mode in order to select the most appropriate location for each painting, but then had to switch back to Edit mode to add the anchor text and links. That is one of the disadvantages of using included text in a writing space, as you can only inspect its contents in Read mode.


The end result, my illustrated version of the Perseus parallel Latin and English versions of Ovid’s Metamorphoses Book 1, is here: ovidmetamorphosesbook1b

I hope that you enjoy reading it using Storyspace, Storyspace Reader, or Tinderbox.