Do your readers a favor: give them an index
Serious works of reference need a good index, something that goes beyond simple word searching.
BLUEPHRASE has indexmark notation which is used to mark passages for inclusion in an index. The notation for this uses special square-bracket doppelmarks that look like this [[ ... ]].
Inside the doppelmarks, there are four types index entries: defining entries, unmarked entries, secondary entries, and cross-reference entries. All four begin with a metatopic, which is an arbitrary name beginning with a dot. In the examples that follow, the metatopic is .bees.
The four types of indexmarks use the following notation:
- A defining entry consists of a metatopic and the word or phrase that is to be added to the index, delimited with single-quotes, like ' ... '.
- An unmarked entry consists solely of the metatopic.
- A secondary entry consists of a metatopic and an alternate word or phrase, which is to be added to the index as a "see also" item, and which is delimited with parentheses, like ( ... ).
- A cross-reference entry consists of two metatopics.
Here's an example of each type of indexmark:
defining entry [[.bees 'Bees']]
unmarked entry [[.bees]]
secondary entry [[.bees (army)]]
cross-reference entry [[.bees .honey]]
Honey [[.honey 'Honey']]
Building the index
The indexmark entries are coalesced into an index where a build pragma occurs. Here's what it might look like:
Then, the relevant portion of the emitted output (ignoring all other indexmarks, for brevity) would look like this:
<dfn><a id=ix25 class='defining' href='#ix20'>Bees</a></dfn>
<li>also <a id=ix26 class='unmarked' href='#ix21'>1</a></li>
<li><a id=ix27 class='secondary' href='#ix22'>army</a></li>
<li><a id=ix28 class='crossref' href='#ix24'>(see also Honey)</a></li>
<dfn><a id=ix29 class='defining' href='#ix24'>Honey</a></dfn>
Each entry in the index is hyperlinked back to the original place in the body matter where the indexmark was placed.