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]
