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.
BLUEPHRASE 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 BLUEPHRASE 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.