docbook-apps

[moving this over to the docbook-apps mailing list where stylesheet issues are discussed]

Hi Maria,
This has been a long standing feature request. I always thought it would be difficult because of the complexity of the indexing machinery, but I just looked again and I think it can be done without too much trouble.

The basic problem is that the entries in the index are generated from indexterm elements that reside in the document. You cannot directly use the id of an indexterm, because that is used to link back into the text. So an index entry needs to generate its own unique id. Then the stylesheet needs to match the text from the <see> to the first <primary> element that matches (there may be many).

To insert the index entry id attributes, you would need to customize the template in autoidx.xsl that starts with:

<xsl:template match="indexterm" mode="index-primary">

For the HTML version, the change would look like this, which uses the id of the indexterm but prepends 'ientry-' to it to differentiate it.

Change:

To:


<xsl:variable name="id" select="concat('ientry-', generate-id())"/>

Then you would need to customize the mode='index-see' template with something like this:

<xsl:template match="indexterm" mode="index-see">

<xsl:template match="indexterm" mode="index-see">
<xsl:param name="scope" select="."/>
<xsl:param name="role" select="''"/>
<xsl:param name="type" select="''"/>


<xsl:variable name="see" select="normalize-space(see)"/>

<xsl:variable name="target" select="key('primary', $see)[1]"/>


<xsl:variable name="href">
<xsl:if test="$target">
<xsl:value-of select="concat('#ientry-', generate-id($target))"/>
</xsl:if>
</xsl:variable>

<xsl:text> (</xsl:text>
<xsl:call-template name="gentext">
<xsl:with-param name="key" select="'see'"/>
</xsl:call-template>
<xsl:text> </xsl:text>
<xsl:choose>

<xsl:when test="$target">

<xsl:value-of select="see"/>

</xsl:when>
<xsl:otherwise>

<xsl:value-of select="see"/>
</xsl:otherwise>
</xsl:choose>
<xsl:text>)</xsl:text>
</xsl:template>

I did not test this much, so there may be issues that arise when you try it. For example, I just remembered that the 'primary' key is actually constructed as follows:



That means indexterms with an @sortas attribute would not match. You might need to construct your own xsl:key that does not include @sortas, something like this (untested):

<xsl:key name="primaryonly"
match="indexterm"
use="normalize-space(primary)"/>

and then use 'primaryonly' in the key() function above.

When <see> is working, then do something similar for see-also, and for FO output.

This is such a nice feature I think I'll add it to the next release, with a param to turn it on or off.

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net


From: Maria Lowas
Sent: Tuesday, October 08, 2013 7:11 AM
To: docbook@lists.oasis-open.org
Subject: [docbook] Indexterms - see and seealso linked to another indexterm


Hi everyone,

I am at the point of creating an index and I though it would be nice if the <see> and <seealso> elements were linked to the term they are pointing to, that is, to another index entry. In this way, if you have something like this:

<indexterm>
<primary>group</primary>
<see>user group</see>
</indexterm>

and you get:

group (see user group)

you can click "user group" and see the index entries for this term (secondary entries, linked topics/pages etc.) instead of scrolling/searching for it. Is there any sensible way to achieve it? I've been looking through docs (DocBool XSL: The Complete Guide) and the mailing list, but I couldn't find any straight forward answer. My document is processed to HTML and PDF.

Any thoughts?

Regards,

Maria Lowas


--------------------------------------------------------------------- To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org For additional commands, e-mail: docbook-help@lists.oasis-open.org

On 2013-10-08 Bob Stayton wrote:
> The basic problem is that the entries in the index are generated from
> indexterm elements that reside in the document. You cannot directly use
> the id of an indexterm, because that is used to link back into the
> text.
> So an index entry needs to generate its own unique id. Then the
> stylesheet needs to match the text from the <see> to the first
> <primary>
> element that matches (there may be many).

I am attaching my customization I use for some time (for FO/PDF). It
generates required IDs [1] and corresponding links to them.

I use it rather on simple indexes so it may not work in more complex ones.

HTH, Jan

__________
[1] IDs are composed from normalized primary/secondary entries (spaces are
translated into dashes). Bob's approach to use the generate-id() function
seems to be better here.