OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


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


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]