[More quick guides]

A quick guide to
creating indexes
in Prince 14

Or, is it indices?

Books often have an index at that back, helping readers find topics of interest. Generating such indexes (we'll stick to that term, it's commonly used in the publishing industry) is a strenous task. Humans are good at marking the topics which should be added to the index, but computers are better at keeping track of page numbers and such. The script described in this guide will show you how Prince, a HTML-to-PDF-via-CSS converter, can help you create fantastic indexes for you next book.

Three composers

We start with a simple HTML document, which has one paragraph and the names of three composers. Also, there is an empty ol elememt, ready to be filled with index entries:

html<script type="text/javascript" src="https://princexml.com/howcome/2021/guides/charms.js"></script>
<body onload="index()">

<p>The era of Baroque music (1600-1750) began when the first operas were written and when contrapuntal music became prevalent. Composers from the Baroque era include <span class=ix>Bach</span>, <span class=ix>Telemann</span> and <span class=ix>Händel</span>. 

<div class=index>
<h2>Index</h2>
<ol id=index></ol>
</div>

As you can see in the rendered document above right, the three composer names appear in the index. They were added there by the script, which looks for certain elements; span elements of class ix will be pointed to from the index, and their content will be used as the index entry.

Four pages

An index is only useful when there is more than one page. Here are three paragraphs which end up on on different pages:

html<p>The era of Baroque music (1600-1750) began when the first operas were written and contrapuntal music became prevalent. Composers from the Baroque era include <span class=ix>Bach</span>, <span class=ix>Telemann</span> and <span class=ix>Händel</span>. Among these, <span class=ix>Bach</span> stands first.
...
<p>The death of <span class=ix>Bach</span> signifies the end of the Baroque, and the start of the Classical period. The music of the Classical period (1750-1800) is characterized by homophonic texture, often featuring a prominent melody with accompaniment. <span class=ix>Haydn</span> and <span class=ix>Mozart</span> are among the central figures of the Classical period. 
...
<p>In 1800, the Romantic era (1800-1890s) in music developed, with <span class=ix>Beethoven</span> and <span class=ix>Schubert</span> as transitional composers who introduced a more dramatic, expressive style. <span class=ix>Bach</span>, <span class=ix>Händel</span>, and <span class=ix>Mozart</span> were not part of this period, and they are mentioned only so that they appear in the index. 

In the example above, page ranges have been collapsed so that 1, 2, 3 becomes 1–3.

Adding emphasis

An index often contains many references to the same subject, of which one may be more important than the others. These important references are often marked by using a bold typeface. In our code, we use the ixb class name to mark emphasis; the class name is highlighted in red in the sample code below:

html<p>The era of Baroque music (1600-1750) began when the first operas were written and contrapuntal music became prevalent. Composers from the Baroque era include <span class=ix>Bach</span>, <span class=ix>Telemann</span> and <span class=ix>Händel</span>. Among these, <span class=ixb>Bach</span> stands first.
...
<p>The death of <span class=ix>Bach</span> signifies the end of the Baroque, and the start of the Classical period. The music of the Classical period (1750-1800) is characterized by homophonic texture, often featuring a prominent melody with accompaniment. <span class=ix>Haydn</span> and <span class=ixb>Mozart</span> are among the central figures of the Classical period. 
...
<p>In 1800, the Romantic era (1800-1890s) in music developed, with <span class=ix>Beethoven</span> and <span class=ix>Schubert</span> as transitional composers who introduced a more dramatic, expressive style. <span class=ix>Bach</span>, <span class=ix>Händel</span>, and <span class=ix>Mozart</span> were not part of this period, and they are mentioned only so that they appear in the index.

An emphasized reference will cancel a normal reference, and will break a sequence of normal references that would otherwise collapse.

Two-level indexes

A subject in an index will often have a two-level entry. A book on classical music will have many references to Bach and it is helpful to give readers more context when looking for the right page.

html<p>The era of Baroque music (1600-1750) began when the first operas were written and contrapuntal music became prevalent. Composers from the Baroque era include members of the <span class=ix title="Bach; family">Bach</span> family, <span class=ix>Telemann</span> and <span class=ixb>Händel</span>. Among these, <span class=ixb title="Bach; Johann Sebastian">Johann Sebastian Bach</span> stands first. 
...
<p>The death of <span class=ix title="Bach; Johann Sebastian">Bach</span> signifies the end of the Baroque, and the start of the Classical period. The music of the Classical period (1750-1800) is characterized by homophonic texture, often featuring a prominent melody with accompaniment. <span class=ix>Haydn</span> and <span class=ixb title="Mozart; Amadeus">Mozart</span> are among the central figures of the Classical period. 
...
<p>In 1800, the Romantic era (1800-1890s) in music developed, with <span class=ix>Beethoven</span> and <span class=ix>Schubert</span> as transitional composers who introduced a more dramatic, expressive style. <span class=ix title="Bach; yet again">Bach</span>, <span class=ix>Händel</span>, and <span class=ix title="Mozart; the man">Mozart</span> were not part of this period, and they are mentioned only so that they appear in the index. 

Styling indexes

The script-generated elements that make up the index can be styled. The script generates a structure like this:

<ol id=index>
  ...
  <li class=entry>Händel <a class=ixb ...>1</a>, <a class=ix ...>3</a>
  <li class=entry>Mozart
  <li class=subentry>Amadeus <a class=ixb ...>2</a>
  ...
</ol>

Here is the style sheet used in this example:

html#index { columns: 2; column-rule: thin solid black; }
#index li { 
  list-style-type: none; 
  margin: 0 0 0 1.5em; 
  text-indent: -1.5em;  
}
#index li.subentry { 
  list-style-type: none; 
  margin-left: 2.5em; 
}
#index a.ixb { font-weight: bold; }
#index a { color: black }

span.ixb { background: #FF6 }
span.ix { background: #FFA }

Notice that the referenced words are also styled (by highlighting) in the above example.

Multipass

Creating indexes in Prince 14 relies on the multipass feature, which formats the document several times. Between each run, a script can modify the document to improve layout. These scripts do amazing things in Prince, but will not work in browsers.

2021-01-06 Håkon Wium Lie