Re: [docbook-apps] auto-index, HOWTO

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

The index entries can be customized.  Although the indexing templates are in 
general among the most complex in the DocBook stylesheets, customizing the 
text of the reference link is pretty easy.  In html/autoidx.xsl, the text is 
generated in the template with name="reference" with this line:

        <xsl:apply-templates select="$target[1]" 
mode="index-title-content"/>

where $target is the container element of the indexterm (typically a section 
element).  The template with mode="index-title-content" is currently defined 
as simply applying templates in mode="title.markup", which generates the 
section title.

You could modify this to pass the indexterm as a template parameter:

<xsl:apply-templates select="$target[1]" mode="index-title-content">
   <xsl:with-param name="indexterm" select="."/>
</xsl:apply-templates>

and then customize the template with mode="index-title-content" to receive 
that parameter and append information from the indexterm to the title 
generated using whatever syntax you like.


Maybe I don't understand your usage of the term "qualification" here, but I 
don't see how your notation adds any information for the reader:

> foo(), B::foo(), C::foo()
> foo(int), B::foo(int)

It seems to be repeating the indexterm as a suffix to the section title, 
which to me makes the entry harder to read.  How would this look for 
indexterms in section titles with more than one word?

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net


----- Original Message ----- 
From: "Stefan Seefeld" <seefeld@sympatico.ca>
To: "DocBook Apps Mailing List" <docbook-apps@lists.oasis-open.org>
Sent: Monday, January 21, 2008 11:38 AM
Subject: Re: [docbook-apps] auto-index, HOWTO


> Bob,
>
> thanks for the quick clarification. I'm not sure whether to be happy about 
> the fact that the current behavior is a feature, not a bug. :-)
>
> Bob Stayton wrote:
>
>> http://www.sagehill.net/docbookxsl/IndexOutput.html
>>
>> Suggestions for alternate designs in HTML output are welcome.
>
> I'm not quite sure I have better ideas, though I certainly don't find the 
> current behavior intuitive.
>
> In particular, "DocBook: The Definitive Guide"
> contains this description for indexterm:
>
> "In other words, the IndexTerm is placed in the flow of the document at 
> the point where the IndexEntry in the Index should point."
>
> Compare that to
>
> "The links go to the top of the section rather than to the anchor point 
> within the section. That's done to permit multiple identical indexterms in 
> the same section to collapse to a single entry. That's done to avoid 
> having to repeat the section title."
>
> from the your book (the link you just pointed me at). Aren't these two 
> statements contradictory ?
>
>
> As far as the label is concerned, I would expect it to be used to 
> disambiguate indexterms with common primary texts. (Though I'm not sure 
> what uniqueness rules apply to index terms, or the things that index terms 
> refer to, and so it isn't clear what disambiguation should actually do.
>
> Here is a use case, just to illustrate what I'm trying to achieve:
>
> Consider an API reference, somewhat similar to the snippet I attached to 
> my previous mail. There is an indexterm for each declaration I want to 
> document. However, typically, entities are nested in scopes. A label may 
> be the unqualified id, with full qualification used to disambiguate. (The 
> qualified name could be provided as an additional label attribute, or be 
> computed from the docbook document structure, assuming there is a match 
> from source code scopes to docbook sections.
>
> And, as a specific example, in C++:
>
> namespace A
> {
> namespace B
> {
>   void foo();
>   void foo(int);
> }
> namespace C
> {
>   void foo();
> }
> }
>
> in docbook:
>
> <section><title>A</title>
> <section><title>B</title>
> <synopsis>void foo();</synopsis>
> <indexterm><primary>foo()</primary></indexterm></section>
> <synopsis>void foo(int);</synopsis>
> <indexterm><primary>foo(int)</primary></indexterm><section><title>C</title>
> <synopsis>void foo();</synopsis>
> <indexterm><primary>foo()</primary></indexterm>
> </section>
> </section>
>
> At present, this will generate an index
>
> foo(), B, C
> foo(int), B
>
> (with 'B' and 'C' linking to sections 'B' and 'C' respectively.) What I 
> would like to see is an index
>
> foo(), B::foo(), C::foo()
> foo(int), B::foo(int)
>
> Is there any way to get there ? (I understand that the computation of 
> qualified names is beyond the scope of docbook, but being able to either 
> provide qualified names in the document, or by overriding some xsl 
> templates to do the computation, may work fine.
>
> Thanks,
> Stefan
>
> -- 
>
>       ...ich hab' noch einen Koffer in Berlin...
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>
>
>