QIL: A Normative Scheme for Labelled Narrative

QIL is a scheme for labelling arbitrary segments of narrative when writing-up deductive reasoning such as ‘proof arguments’. I have been using this locally for my own work as there appear to be no published recommendations in this area. Depending on their background, other writers may find this presentation useful.

Narrative is, by its very nature, sequential. When one part needs to reference another part, either forwards or backwards, then we take it for granted that there will be an associated reference point: some identifier or label that will allow us to find the target text.

Chapters and sections are obvious examples of this. For instance: “see Ch. 12, and Sec. 12.1” (actual abbreviations dependent upon your style guide). The separating space would usually be a non-breaking space in order to prevent the number being separated onto a different line. Both of these cases would usually have alternative textual titles, too, although the chapter name and section heading would be less used for frequent intra-document references.

We also take it for granted that individual non-narrative items, such as Tables, Figures, Plates, etc., can be referenced directly. Their numbering usually runs consecutively throughout a document, beginning with number 1, and separately from each other.[1] For instance: “see Figure 12”.

The QIL Goals

The goals of this scheme were:

• Visually identifiable way of labelling and referencing arbitrary narrative sentences or paragraphs
• Associating certain semantics with the labels by using distinct introducers
• Ensuring that the scheme is useable in both documents created via a word-processor and in online blog posts or other Web pages
• Ensuring that their usage in electronic documents and online makes effective use of the corresponding hyperlink support

While headings could be used to label paragraphs, it would break the flow of the surrounding narrative, and so it may not be justified simply to create a label for future reference.

Although not part of the QIL scheme, I have used the following convention for headings when collecting together information from large-scale cluster research. It allows two neighbouring heading levels to specify a person followed by the sources relating to them, or a source followed by personae mentioned in that source.

.

Person-based (Person → Sources)

A number of sources provide enough direct and non-conflicting evidence to create a coherent snapshot of a person with some of their lineage or history. This will usually reference multiple sources, which would be described under secondary headings.

Source-based (Source → Personae)

A given source provides references to one or more individuals (or ‘personae’) whose identities and relationships to references in other sources has yet to be determined. Those distinct personae would be described under secondary headings.

However, I also needed to be able to create much lower-level labels for deductive logic. Having identifiable labels at this level may also help keep software visualisations in-step with the written argument, but this is an area which has yet to be explored to its full potential

Mathematics

Mathematics is a subject that includes an array of concepts that may need to be labelled and referenced, including equations, lemmas, and axioms. The most familiar one to the layperson will be equations, and I will briefly examine how these are handled in order to find a precedent for QIL.

When manipulating equations, such as when deriving a mathematical proof, references to prior equations will be essential. For instance: “Rearranging Eq. (1.2) and substituting Eqs. (2.1) and (2.2) gives…”. Note that the equations are typically numbered using the enclosing section number plus some sequential equation number within that section. Note also that associated references are usually preceded by the abbreviation “Eq.” or “Eqs.”.[2]

                                           E = mc²                                                                             (3.2)

Any scheme that applies to segments of narrative must be as simple as this, and embrace the basic requirements of relative numbering and the distinguishing of references from associated labels.

QIL In Microsoft Word

The QIL scheme began in Microsoft Word using the following format:

L(n.n.n):         Label

L(n.n.n)          Reference to label

The last integer (’.n’) was relative to the active heading-2 level numbering (the preceding ‘n.n’). The introducer, “L”, was then supplemented with a couple of other letters to provide some essential semantics, as follows:

• Q(n.n.n): A query regarding anomalous evidence, conflicts, etc., that requires subsequent explanation or resolution
• I(n.n.n): An inference made from evidence and/or other inferences that may be used subsequently
• L(n.n.n): A general label for anything that may be cited later

Generating these is quite easy in Word because there are corresponding field codes: the invisible directives that can be embedded within your text. For instance, in order to generate “Q(2.3.7):” at a location within a heading-2 level of “2.3”, you could do the following:

• Type the “Q(“
• Ctrl+F9 to open a pair of field-code braces
• Right-click and select ‘Edit Field…’
• Select ‘StyleRef’, with the options of ‘Heading 2’ level and ‘Insert paragraph number’
• Type the “.”
• Ctrl+F9 again
• Select ‘Seq’. Change the field code to “SEQ Q”, “SEQ I”, etc., as appropriate
• Type the final “):”

Yes, this sounds excessive but there are easier ways.

The SEQ field code takes an arbitrary identifier so you can support separate sequences running concurrently: “Q”, “I”, and “L” in this scheme. They each start from 1, and continue until reset with a code such as “SEQ Q \r1”; hence, you would need one of these if switching to a new section. Although basing it on heading-1 level would be workable, and dependent upon your written style, the alternative of simply using global numbering, as in “Q(23):”, may be easier to generate but harder to find the corresponding label in your narrative.

If we go to the ‘Word Options’ and temporarily turn on the option to see these field codes (usually under ‘Advanced > Show document content > Show field codes instead of their values’), then we would see:

Q({ STYLEREF "Heading 2" \n }.{ SEQ Q }):

An easier way to generate these labels is to use copy-and-paste; any of them can be copied to a different section, selected with the mouse, and right-click ‘Update Field’ in order to create an entirely new one. However, my recommended method is to use the Word ‘Building Blocks’ feature, formerly called ‘AutoText’.

Select examples of each of the three labels (one at a time), type Alt+F3, and save them as named Building Blocks (e.g. QLab, ILab, LLab). You could also save copies of the corresponding ‘reset’ cases (e.g. QLabR, ILabR, LLabR). You can summon these at any time by typing their name followed by F3. The beauty of this scheme is that these definitions are stored in a Word file called ‘Building Blocks.dotx’, and so will be available in future documents.

Also, showing the underlying field codes — should you ever need them — can be done more easily using Alt+F9 to toggle their display.

Before we can generate a reference to one of these labels, we need to bookmark its textual location. Select the label with the mouse, but not the trailing “:”. Using ‘Bookmark’ in the ‘Links’ area of the ‘Insert’ tab, type in a name for the bookmark, and select ‘Add’. We then have a named location (rather than just a label) that we can reference later.

To generate a reference to it, select ‘Cross-reference’ in the same ‘Links’ area, select ‘Bookmark’ and ‘Bookmark text’ in the two drop-down lists, leave ‘Insert as hyperlink’ unchecked (for now), and chose a named bookmark. This will generate a copy of the corresponding bookmarked text (e.g. Q(2.3.7)) rather than the bookmark name, which is merely a local symbolic name. Looking again at the invisible field codes would reveal something similar to:

Example reference is { REF Q_2_3_7 \h }.

It is tempting to just use a name such as “Q_2_3_7”, as I have been doing in this article, but the inevitable moving around of sections will require labels to be re-generated (done by Ctrl+A to select everything in the document, and F9 to update all of its fields), and that would cause the symbolic name to get out of step with the actual text. A better scheme is to adopt functional names: ones that describes the associated query, inference, or whatever. Note that there are limitations on these names: basically 1–40 characters, beginning with a letter or underscore, and containing no punctuation or whitespace.

What we have here is a workable scheme for printed documents; we now need to look at it in the context of electronic documents and blogs (or other Web pages).

Word Hyperlinks

Word has two mechanisms for hyperlinking its bookmarks, and they are subtly different, although their terminology sounds too similar to the casual user:

• Select ‘Cross-reference’ in the ‘Links’ area of the ‘Insert’ tab. Select ‘Bookmark’ and ‘Bookmark text’ from the two drop-down lists, and ensure that ‘Insert as hyperlink’ is checked. I’ll refer to these as “Bookmark hyperlinks”.
• Select ‘Hyperlink’ from the same ‘Links’ area. Select ‘Place in This Document’ on the left, and select the required bookmark from the main tree panel. I’ll refer to these as “URL Hyperlinks”.

Comparing these mechanisms using the above bookmark-reference example gives the following respective field codes.

Example reference is { REF Q_2_3_7 \h }.

Example reference is { HYPERLINK \1 “Q_2_3_7” }.

Now these both hyperlink to the same bookmark, but their capabilities are not the same.

1. When you insert a bookmark hyperlink then it nicely substitutes the bookmarked text — the QIL label in our case — as opposed to some symbolic bookmark name that is more relevant to the author than to the reader. When you insert a URL hyperlink then you only get the bookmark name. Although you can change the ‘Text to display’, you may need a good memory to recall the bookmarked label. Also, any such display text is fixed, and will not be kept in-step if you move sections around, since the display text is not part of the field code. Clearly this Word feature has not been thought out very well.
2. A bookmark hyperlink looks like normal text until you hover over it, whereas a URL hyperlink is underlined and rendered in blue like normal Web hyperlinks. If you hover over either then they nicely show you the underlying bookmark name and the instruction ‘Ctrl+Click to follow link’.
3. Most importantly, when saving the document as “Web Page, Filtered” — required for blogs and other HTML versions — then bookmark hyperlinks are discarded, but URL hyperlinks are not!

At first, I thought that neither of these did what I needed, and that my scheme was therefore doomed without major change.

Blog Hyperlinks

I’d previously written about using bookmarks in blogs at Using Bookmarks with Blogger, although I had to update that article following the findings of this more recent one.

The HTML equivalent of a bookmark is called an “anchor”, and is represented by the <a> element. Given an example sentence of:

L(4.1.3): This resolves the query at Q(1.2.6).

the HTML version we would hope for would be similar to:

<a name=”L_4_1_3”>L(4.1.3)</a>: This resolves the query at <a href=”#Q_1_2_6”>Q(1.2.6)</a>.

Where “L_4_1_3” and “Q_1_2_6” are simply the bookmark names that I had chosen.

In Using Microsoft Word with Blogger, I recommended saving Word documents as “Web Page, Filtered”, and not just “Web Page”, when using them to generate new blog posts. This is because it filters out the excessively verbose and complicated HTML that Word generates by default, and is necessary for the correct operation of feedburner (notifying people of new blog-posts).

The first thing I noticed was that the displayed document, following the new saved-as format, is not what is saved to disk; it appears to be using the full Word HTML version, which is why it all looks fine. The disk version will not have any representation of bookmark hyperlinks. Also, the anchor points stop after the first parenthesis, showing ‘<a name=”L_4_1_3”>L(</a>4.1.3)’ rather than the correct form in the example above. This appears to be a bug in Word 2007/2010 where the presence of the field codes representing those numbers clashes with the bookmarking, but it is not a showstopper because at least the anchor begins at the correct text location.

Given the flexibility that Word is endowed with, I was rather surprised by the hiccups and limitations when trying to implement this scheme. Although I mentioned some of the issues on a Word forum, I never expected any changes because — based on previous experience — you would be told ‘that’s the way it is’, ‘it works as intended’, and ‘we don’t recommend what you’re trying to achieve’. I can’t abide that sort of reaction from the fringes (the actual developers would probably be interested), but I wasn’t going to give up that easily either.

With the two types of Word hyperlink, one was much easier to use while the other was the one that was represented in the HTML. What I found was an unexpected hybrid that was not that onerous, and which seems to work in both 2007 and 2010 versions:

• Generate a bookmark hyperlink for your chosen bookmark name
• This deposits the bookmarked text (the QIL label) rather than the name, as required
• If you’ve already forgotten the bookmark name in the preceding seconds, just hover over it
• Select the deposited reference with the mouse and convert it to a URL hyperlink to the same bookmark

The interesting thing about this is that it still looks like the normal bookmark hyperlink (not underlined, and not coloured blue) but it really is a URL hyperlink and so works when saving as “Web Page, Filtered” in order to generate your blog page (see Using Microsoft Word with Blogger). The display text gets correctly updated in this case (unlike the manually inserted display-text mentioned earlier) since any text selected at the time the URL hyperlink is inserted becomes its display text, and in this scenario that contained the necessary field codes.

This scheme isn’t as complicated as it sounds, but some hoops had had to be jumped through. Using macros or add-ins could make it much more streamline.

---

[1] Joe Schall, "Effective Technical Writing in the Information Age: Textual References to Figures and Tables", John A. Dutton e-Education Institute - Pennsylvania State University (https://www.e-education.psu.edu/styleforstudents/c4_p11.html : accessed 28 Nov 2016).

[2] Drs. Nathan Champagne, Scott Gold, Steve Jones, Terry McConathy, and Ramu Ramachandran, “Guidelines for Equations, Units, and Mathematical Notation: An addendum to the Thesis/Dissertation Guidelines provided by the Graduate School...”, College of Engineering & Science [COES] - Louisiana Tech University (http://www.latech.edu/graduate_school/thesis_dissertations/coes_equation_guidelines.pdf : undated but parts last updated 23 Feb 2006, accessed 28 Nov 2016).