X

The sane way to build a glossary of terms

Defining

Technical writing uses acronyms and jargon whose meanings need to be defined. Non-technical writing sometimes makes use of foreign language words whose meaning also needs to be defined. These are classic situations where preparing a glossary is a good idea.

Blue-phrase has special glossmark notation to aid in this preparation. The first time any uncommon word is used in a manuscript, the author delimits it using special vertical-bar doppelmarks that look like this || ... ||.

Inside the doppelmarks, are two delimited expressions:

  • the word being defined (referred to as the interscribed expression), which is delimited with single-quotes ' ... ', and
  • the word's definition (referred to as the adjunct expression), which is delimited with double-quotes " ... ".

Here's an example of glossmarks:

This was a high-water mark in ||'détente' "easing of hostilities"||
between the United States and the Soviet Union.

When this blue-phrase is compiled, the emitted HTML contains the interscribed expression, with a hyperlink to its definition, which appears elsewhere. Here's how the example would be emitted:

<p>This was a high-water mark in <a id=gl20 href='#gl23'>détente</a> between the United States and the Soviet Union.</p>

Building the glossary

The adjunct expressions from all of the glossmarks in your manuscript are gathered together and emitted where a build pragma occurs. Glossaries can be ordered alphabetically, or in the order that they occur within the body-matter. Here's what it might look like:

div {
h1 Glossary of Terms
!build-glossary *order=alpha
}

Then, the relevant portion of the emitted output (ignoring all other glossmarks, for brevity) would look like this:

<div>
<h1>Glossary of Terms</h1>
<dl>
...
<dt id=gl23><a href='#gl20'>détente</a></dt>
<dd>easing of hostilities</dd>
...
</dl>
</div>

Each definition is hyperlinked back to the original place in the body matter where the word first occurred.

The sane way to build a glossary of terms