....
The index looks for terms to be indexed in a document, collects them, turns them into target anchors and creates a sorted index as an HTML list, which is inserted at the place of a placeholder in the document. The resulting document is written to standard output.
The index is inserted at the place of a comment of the form <!--index--> or between two comments of the form <!--begin-index--> ... <!--end-index--> In the latter case, all existing content between the two comments is removed first.
Index terms are either elements of type <dfn> or elements with a class attribute of "index". (For backward compatibility, also class attributes "index-inst" and "index-def" are recognized.) <dfn> elements (and class "index-def") are considered more important than elements with class "index" and will appear in bold in the generated index.
The option -c adds additional classes, that are aliases for "index".
By default, the contents of the element are taken as the index term. Here are two examples of occurrences of the index term "shoe": A <dfn>shoe</dfn> is a piece of clothing that... completed by a leather <span class="index">shoe</span>...
If the term to be indexed is not equal to the contents of the element, the title attribute can be used to give the correct term: ... <dfn title="shoe">Shoes</dfn> are pieces of clothing that... ... with two leather <span class="index" title="shoe">shoes</span>...
The title attribute must also be used when the index term is a subterm of another. Subterms appear indented in the index, under their head term. To define a subterm, use a title attribute with two exclamation marks ("!!") between the term and the subterm, like this: <dfn title="shoe!!leather">...</dfn> <dfn title="shoe!!invention of">...</dfn> <em class="index" title="shoe!!protective!!steel nosed">...</em> As the last example above shows, there can be multiple levels of sub-subterms.
The title attribute also allows multiple index terms to be associated with a single occurrence. The multiple terms are separated with a vertical bar ("|"). Compare the following examples with the ones above: <dfn title="shoe|boot">...</dfn> <dfn title="shoe!!invention of|inventions!!shoe">...</dfn> These two elements both insert two terms into the index. Note that the second example above combines subterms and multiple terms.
It is possible to run index on a file that already has an index. The old target anchors and the old index will be removed before being re-generated.
Assumes UTF-8 as input. Doesn't expand character entities. Instead pipe the input through unent(1) and asc2xml(1) to convert it to UTF-8.