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
[EMAIL PROTECTED]
----- Original Message -----
From: "Stefan Seefeld" <[EMAIL PROTECTED]>
To: "DocBook Apps Mailing List" <[email protected]>
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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
