Liquid Glossaries

The Liquid Glossaries are an ancillary issue to the process of writing academic documents and as such is being looked into. The web page for this project is http://www.liquid.info/glossary.html and the blog posts relating to it are on http://wordpress.liquid.info/category/liquid-glossaries/ The relevance of glossaries for Liquid View is that the Liquid View needs to be able to show glossaries where required, in an visually efficient way.

You may have noticed the large amount of links to blog posts in this article. This is not only because I wrote too much, it is also an exercise in learning how to write re-usable chunks, which is where the Liquid Glossaries will come in.

Create a Glossary Entry

User selects text does keyboard shortcut cmd-l and the Glossary Dialogue opens with the selected text copied into the ‘Heading’ field. 

If the user did not select text but does cmd-l the Glossary Dialogue opens and the user can type in a Heading. 

There is a visual mock-up here: http://wordpress.liquid.info/glossaries-over-coffee/ 

The Glossary Dialogue

The Glossary Dialogue contains various fields, all of which can support rich text. They include: 

 

•  The ‘Heading’, or the subject for the entry. Name to be decided. 

•  Brief Definition (max 140 characters, indicated in [hard brackets for use in the Visible Glossary View]) 

•  Full Definition (long. This field can contain external links as well as in-document links

•  Option to save to Personal Glossary or only use in this document

On clicking ‘OK’/Enter, the Glossary Definition is saved to a database in the Author application (or in the document, depending on preference, as above). This database is connected to online versions (to be developed and discussed).

Interacting with Glossary Entries in Edit Mode

Wether the author has created an entry while working on the current document or created it earlier, the author can interact with the glossary entry in much the same was as interacting with a citation in Author. The Glossary Definitions are not visibly indicated (by default) so that to interact with the selected text’s glossary entry the author would need to do the cmd-l keyboard shortcut (or ctrl-click and choose). If there was a document entry it comes up for editing, if there was none, a new dialogue, as above, is presented. 

Glossary Logic

If the glossary entry is two or more words long, even though it can also be spawned on one (as shown in the screenshot in the blog entry referred to above), then if the single word spawn is followed by a capitalised word, it will not spawn. This is so that an entry can be for a name and if the author refers to another name where the first name is the same as what’s in a glossary entry, but has a different last name, it will not interfere.

Interacting with Glossary Entries in Read Mode

 

•  In Read mode the reader can click on text with a glossary definition to see the Glossary Dialogue in Read Mode (similar to the Citation Dialogue in Read mode). 

   

Visible Glossaries 

•  The reader can choose to turn on [Visible Glossaries] where all the Brief Definitions are automatically shown in-line in the text, either the first time they appear or every time then appear, in [Hard Brackets, in grey]. This mode can be turned on in a Glossary Dialogue button in Read Mode or through cmd-[ or cmd-] (’tab’ will have to be used if the user wants to indent). 

–   If the [Brief Definition] is clicked on in Read or Edit mode, it will open the Glossary Dialogue in Read or Edit mode. This text cannot be further interacted with on the page. 

Publishing A Document with Glossary

When the author chooses to Publish the document the document will be presented with all the ‘Brief Definitions’ inline, [inside hard brackets, in grey] for the author to review. The author can click on any of these definitions to turn them off (and the text goes red) and back on again with another click if mistakenly clicked on. The document is then published with a list of all the Glossary Entries at the end of the document (same as Citations are listed at the end of the document under ‘References’). How the glossary entries are embedded is up for discussion. 

Glossaries. Over Coffee.

Mark and Chris and I had a long discussion about glossaries where we ended up with the simplified dialog box shown here.

The logic is that the user creates a new entry, as in the case of an entry for ‘Mark Anderson’ here. The text [in the hard brackets] is the brief summary which will appear if the reader chooses to view brief summaries. The main body text is full rich text, which the user can enter URLs into etc. and where any mentioned Glossary entries will be interactable.

There is further an option to save this entry into the person’s glossary or just keep it for this document only.

The Botton underlined ‘Mark’ is showing what other text strings will activate this glossary.

Glossary Logic: If the glossary entry is two or more words long, even though it can also be spawned on one (as shown in the screenshot in the blog entry referred to above), then if the single word spawn is followed by a capitalised word, it will not spawn. This is so that an entry can be for a name and if the author refers to another name where the first name is the same as what’s in a glossary entry, but has a different last name, it will not interfere.

 

Chris’ notes:

 

Audio record of the meeting (marked private):

https://soundcloud.com/user-75792421/chris-mark-glossary-chat-may-2nd

 

And Chris’ notes via email later:

 

What we see here is the representation of a kind of relationship object which relates the following:

A search term within a scope [ “Mark” within the scope of the whole document ]

A (liquid) text #1 “Anderson Southampton PhD Student”. This is constrained to contain no structural elements (paragraphs etc.) but can have other elements (links, bold, etc.)

A (liquid) text string #2 “Mark Anderson\nHe is also at Southampton…”. This is constrained that it is a titled article, so the first text in the string must be a heading. The dialogue has chosen to place the rendering of the heading in a different part of the form, but editing it edits the text.

There is a heading relationship/range/whatever we call markup in this system, defined as the Mark Anderson text range at the start of text #2 to the end of character 13, indicating this is a title of level 1 within the article. This constrains the content that it may not contain additional markup. It also implicitly designates a section which exists between the start of this heading and the end of the flow of text, or the next title of the same or higher-level.

 

Smart Glossaries

Friday I went to the Groucho where I met Joe and we discussed the glossary opportunities, as I started with Mark and Chris earlier in the week. Here are my notes as developed over Easter Weekend:

Problems Addressed

One of the issues with writing something within your field is that, as an author, you are likely to have written something about what you are about to write and it can easily feel like you are duplication efforts and this can be a real source of frustration, something I first noticed when working with Doug. It would be worthwhile to define something once, in a glossary, and then have this available for reuse later. 

Another issue that as a reader, a document in a different field than your own where terms may be used that you are not used to or used in ways you are not used to. 

Both of these problems can be addressed within the framework of a modern glossary system. 

Opportunity

The notion of re-use writing and of writing in smaller chunks and then linking it together is not new and in some ways it seems this is what many feel hypertext is about. This glossary implementation can support such an approach. 

Glossary

A glossary is a collection of glosses, which are “word inserted as an explanation, translation, or definition,” (Harper)

A glossary is not a definition in any objective way. In a narrow sense it can be seen as an elucidation of specific text written by a specific author in a specific document. It would not be stretching the definition of a glossary to allow an author to build a glossary over time and to 

The notion is to build a glossary (a ‘gloss’ of person meaning, not a dictionary) for an author, as you go along authoring documents, and the glossary is then appended to a document on  publish, with levels of information visible as the reader requires. 

Process

Assigning Glossary Entries to Keywords

The author selects the text which needs a glossary entry and cmd-y(or ‘l’, not determined yet) to produce the Glossary Dialog (as outlined below). In this dialog the author has rich options for assigning glossary meaning but only the ‘Short/Twitter Description’ () summary is required. 

A way to enter a person is a bit different from entering a place or concept, since the full name of the person should not be in the Short description since the first name would then be doubled if shown inline, as you can see in the example.

Edit

Over time the author’s glossary will grow and be re-useable. The user can at any time access previously added glossary items to edit or delete them. The user can also choose to add to glossary entries over time. 

Publishing

On publishing the document all the words in the document which have glossary entries are highlighted in order for the author to review the text in case some are contextually wrong. A simple click on a word disconnects it from the glossary (if a mistake is made, a click on the word will automatically re-connect it).

The published document will get a document with a ‘Glossary’ section appended at the end, so that the reader can choose to read the glossary before reading the rest of the document. The reader can interact with the glossary text at will as well, including having an option to have every glossary term highlighted on first occurrence.  

Example

• Without the glossary expanded, the text looks like this, same as the introduction to this blog post: 

Friday I went to the Groucho where I met Joe and we discussed the glossary opportunities, as I started with Mark and Chris earlier in the week.

• Showing only text in the ‘Short/Twitter Description’ summary inline in the text, after each occurrence. This is a reader option and can be applied to any arbitrary section of the document, it does not have to be the whole document BTW, The last example has the number 15 in brackets and that refers to the week number, a number used in Norway more than in England.

Friday (the 15th of April 2017) I (Hegland, PhD Student Southampton) went to the Groucho (a media club in Soho, London, of which I am a member and I love it there) where I met Joe (Corneli, University of Edinburgh) and we discussed the glossary opportunities (re-inventing glossaries as discussed in my blogs), as I started with Mark (Anderson, PhD Student Southampton) and Chris (Gutteridge, EC Southampton) earlier in the week (15).

• And this is what it would look like if non-expanded but interacting with the word ‘Joe’, perhaps simply by mouse-over/pointing to the text or clicking on it:

Friday I went to the Groucho where I met Joe (Corneli, University of Edinburgh) and we discussed the glossary opportunities, as I started with Mark and Chris earlier in the week.

• Here I have bolded the text ‘glossary opportunities’ has been marked to highlight, to show the reader that it has a glossary definition attached:

Friday I went to the Groucho where I met Joe and we discussed the glossary opportunities, as I started with Mark and Chris earlier in the week.

Create New Glossary Entry : Dialog

Selected  Keyword Appears As Heading

Category: [        ]  this field acts very much like assigning tags in macOS: user can click on a list or add new

Short/Twitter Description (if person’s name, only last name, then description): ( ) this is what would appear in-sentence if reader-requested

Fuller Glossary (If person’s name, start with full name): [        ] 

Appended Comments: [        ] This only appears when opening a previously created glossary item

Highlight? • whether or not this should be highlighted in the text on first appearance, if the author wants to emphasise this to the reader

Uses: [        ] how this text should be used

Related words: [        ]  related words to click to also see

First used in the sentence: Automatic inclusion

URL to this Entry: Automatically generated

Mathematical logic: [        ]

Programming logic/code: [        ]

Show what this word is (dictionary lookup) such as verb etc. (user editable): 

Very Experimental

Logic: [        ] this is where the system uses logic to infer what the text should really read:

Here • Use the current location when authoring

At a specific Date in the future. Change grammar when passed this date.

Automatically Assigned

URL to this entry is fixed to the bottom of the dialog (with  a ‘glossary’ tag): http:…. &glossary

Who has referred to this entry/cited it: [  Pop-Up Menu or List \/]

Implementation

Infrastructure

There needs to be ways to store the entries and retrieve them over a network. Where the entries are stored should be flexible however, and the user should be able to set this.

Multi User

The system should allow for multi-user systems, such as in a research team.

Summary

Allowing the author to add to a glossary easily lets the author build up a series of statements which can then be re-employed for a reader or for the author automatically, again and again. In some ways this is an angle of writing ‘hyper textually’ but it does not imply the complicated linkages which mid-90s hypertext notions wrestled with.