X

Do your readers a favor: give them an index

Indexing

Serious works of reference need a good index, something that goes beyond simple word searching.

Blue-phrase 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:

  1. 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 ' ... '.
  2. An unmarked entry consists solely of the metatopic.
  3. 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 ( ... ).
  4. 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:

div {
h1 Index
!build-index
}

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

<div>
<h1>Index</h1>
...
<div class='bees'>
<dfn><a id=ix25 class='defining' href='#ix20'>Bees</a></dfn>
<ul>
<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>
</ul>
</div>
...
<div class='honey'>
<dfn><a id=ix29 class='defining' href='#ix24'>Honey</a></dfn>
</div>
...
</div>

Each entry in the index is hyperlinked back to the original place in the body matter where the indexmark was placed.

Do your readers a favor: give them an index