See under and see also under

[Richard Hamilton <hamilton@xmlpress.net>]

In response to my action item from the last DocBook TC meeting, here is my proposal for adding see under and see also under to the DocBook schema.

See under and see also under are used by indexers to create a reference to a secondary (or even tertiary) index entry.

For example, consider the following indexterm:
<indexterm><primary>PDF</primary><secondary>format lock-in</secondary><indexterm>

If this indexterm is repeated several times in your document, and you wanted to create a reference from a more generic "format lock-in" primary entry, rather than repeat all of the links specific to PDF, you might want to generate a see also entry like the following:
<indexterm><primary>format lock-in</primary><seealso>PDF</indexterm>

However, if the primary PDF entry has many different secondary terms, you might prefer to point directly to the "format lock-in" secondary entry. This can be done by making the second indexterm a "see also under" indexterm.

I've attached a PDF from one of our books that uses see under and see also under. The instances are highlighted in yellow. The first page has the referencing terms and the second page has the referenced terms. The meaning for the reader is that if you see the following in your index "format lock-in (see under PDF)" you would look for "format lock-in" as a secondary term under the primary term PDF.

I suggest the following markup for this case.

1) The referenced <indexterm> element would remain unchanged.
2) The <see> or <seealso> element on the referencing <indexterm> would have an optional class attribute with the following possible values:
      - "under" this is the "see under/seealso under" case
      - "normal" this is the current, default case, and would be the default if no class attribute is present

Here is how the previous example would look:
<indexterm><primary>format lock-in</primary><seealso class="under">PDF</seealso></indexterm>

As with see and see also, there is no implication that processing should generate a hot link in output formats that allow links (though it would cool if it could:-). And there would be no changes to any other content models; just the addition of the class attribute in these two places. Since the default class is "normal," existing indexterms would work as they always have.

Best Regards,
Dick Hamilton
-------
XML Press
XML for Technical Communicators
http://xmlpress.net
hamilton@xmlpress.net

Attachment: See-under-example.pdf
Description: Adobe PDF document