Porting from WordPress to Storyspace, 6: glossary and index

I was feeling quite pleased after my last article in this series sorted out two of the remaining issues with my hypertext account of the history of oil painting. Until yesterday, when I realised that I had almost committed the cardinal sin of forgetting the ‘end matter’.

Anyone who has read one of my reviews of art books here will know that I am a stickler for the end matter. It doesn’t matter how wonderful a book is, if it doesn’t come with at least one index, I will slate it. This may appear unfair – after all, hardly any works of fiction come with an index, yet À la recherche du temps perdu, Lord of the Rings, and other epics all seem to get by without them. But then I am hardly likely to want to look up the first words said by Gollum, and if I do need to check the names of Frodo’s relatives, there are other places to do that.

There are plenty of times when the reason that you have opened a copy of a non-fiction book is to look up a specific piece of information. You don’t want to idly thumb through a chapter, or have to try to remember the context in which it was mentioned. You just want to go straight to the page, and find the answer. So too with non-fiction hypertext, a reader needs to be able to look matters up.

Glossaries are invaluable to spare your reader from having to look thinks up in an index or, even worse, discovering that you don’t actually explain what a technical term means, rush off to another book to find out. As glossaries are a simpler issue, I will get them out of the way first.

wp2sspace501

I start where these articles often start, by making a prototype for these new writing spaces into which I will put glossary entries and the index. My plan is to implement them quite differently: the glossary will consist of a container in which individual writing spaces for each of the entries will go, but my index will be a single writing space containing each of the index items. The reasons for this will become clearer as I progress.

These prototypes are, for the moment, only distinct in terms of their badge and the colour of the tile.

wp2sspace502

Each glossary entry, based on the prototype GlossaryItem, is named according to the word(s) it represents in the glossary, and contains suitably informative text for that entry. It is kept in the Glossary container, which not only keeps it out of the way of the main threads, but allows the reader to open the glossary and browse it, if they wish, just as they can in a physical book.

One note here: I pasted in text directly from an article on my blog on which to base this entry. It needed to be reflowed, using the Reset Margins sub-command from the Style command in the Format menu. If text in a writing space seems to have acquired idiosyncratic margins and spacing, open the writing space containing it, select all the text, and use that command to clean it up.

wp2sspace503

I am going to use stretchtext to insert the respective glossary contents into a writing space, because it needs to be seen in context. However, it should not disrupt the original context. You don’t want a couple of hundred words about drying oils suddenly appearing in the middle of the main text. So glossary items relevant to each writing space get a section of their own at the foot of the main text. To flag that there is a glossary entry, I have used the open book emoji, both in the main text and in the glossary listing at the end.

I thought about being more subtle and using coloured text, but this would quickly run into issues for readers with limited colour perception. This is, I think, the first good use I have made of emoji, and they do seem to work quite well. They also work happily inside the anchor text, which is pleasing.

wp2sspace504

This is how that writing space looks when in Read mode. I would have liked to put a space between the emoji and the text, but it ends up being almost a tab width, which is I think too distracting to the reader.

wp2sspace505

This is the expanded version, in Read mode. I think that you’ll agree that is far too much to stick into the main text above. I like the contrasting font, although perhaps the glossary font size could come down a tad.

I’m happy with that for a glossary entry, so I’ll turn now to the index.

wp2sspace506

If you have explored Storyspace properly, you will know that it has a powerful Find command in the Edit menu. Why should a reader need both that and an index? This is a similar argument to whether any electronic book or document needs an index, if there is a good find command.

The best answer is to talk to a professional indexer. This seems to be a dying trade now, given the number of books being published without any form of index, but any good indexer will explain how they are so much more skilled than any search command can be.

Having just written a glossary entry for the term drying oil, I’ll use that as an example. The words drying oil and drying oils appear in many of the writing spaces in this document, as you’d expect them to. Most uses are in passing, and not likely to be of much help to someone who, say, wants to read about the different drying oils used in oil painting. A proper index can focus the reader much better, and take them straight to the text that they seek.

So the built-in search, wonderful though it is, is something of a blunt tool. It will find all uses of a word or words, including many which are of no interest to the reader. That said, Storyspace’s search tool is rather better than many: it gives you the name and view location of each writing space containing a hit, which does give the reader more help than most such tools. But I still think a carefully-constructed index will be better focussed.

wp2sspace507

The way that a reader uses an index is rather more straightforward: they identify the index entry which looks closest to what they want, and then expect to be taken to that entry in the text. This makes it ideally implemented using a text link. If you want to, you can put each index term into its own writing space, but I think that is too finely granular: a single writing space containing all the index terms in alphabetical order, with each term linking out to the writing space containing the destination content.

The secret then is in qualifying each term to guess in advance what the reader will look for. Here we can also give the name of the destination writing space, which should help them choose the right item to click.

wp2sspace508

If they click on the last entry, drying oil, types, it should then take them straight to the discussion of drying oils in the sidethread which I made a few articles ago. They may then wish to follow its links up, or use the Go Back command to return them to the index.

Other documents will no doubt fare better with different implementations, but for this one, I think that they should meet the expectations of most readers.

Happy hypertexting!