Re: [docbook] Indexterms - see and seealso linked to another indexterm

["Bob Stayton" <bobs@sagehill.net>]

[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:

 

  <dt>

 

To:

 

  <!-- add an id for the indexentry itself, not the term in the para -->
  <xsl:variable name="id" select="concat('ientry-', generate-id())"/>
  <dt id="{$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="''"/>

 

  <!-- get the text to match on -->

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

  <!-- use the 'primary' key that is already defined to locate the matching indexterm, then select the first with [1] -->
  <xsl:variable name="target" select="key('primary', $see)[1]"/>

 

  <!-- form the href -->

  <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>

   <!-- if there is a target, form the link -->
    <xsl:when test="$target">
      <a href="">
        <xsl:value-of select="see"/>
      </a>
    </xsl:when>
    <xsl:otherwise>
      <!-- you might generate an error message here if you expect all see elements to link -->

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

 

<!ENTITY primary   'normalize-space(concat(primary/@sortas, " ", primary))'>

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