Re: [docbook] Re: open RFEs for possible inclusion in final DocBookV4.3

[Stefan Seefeld <seefeld@sympatico.ca>]

Norman Walsh wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> / Stefan Seefeld <seefeld@sympatico.ca> was heard to say:
> | What's the status of RFE 714764 ('new classifier attrib for
> | <indexterm> and <index>') ?
> |
> | I'd love to be able to generate API documentation in docbook, with
> | separate listings of functions, types, variables, etc.
> 
> Right, and I think I have an action to show how this could be done
> without index changes.
> 
> Basically, the idea is to generate one index for <indexterm>s, another
> for <function>s, another for <type>s, another for <variable>s, etc.
> 
> If that's sufficient for your use case, I really don't think any new markup
> is required. I certainly wouldn't want you to have to do this:
> 
>   <variable>someVarName</variable>
>   <indexterm class="variables"><primary>someVarName</primary></indexterm>

right, having an index for <function> (etc.) would certainly be useful.
However, the problem is that this is not extensible. The main idea 
behind my RFE was that this would allow me to define my own vocabulary,
on top of the docbook one. I could (say) define a 'user case' in terms
of a variablelist, and then generate an index for all 'use cases'.

That would work because my (domain specific) vocabulary would sit on top
of docbook, and not require docbook to notice.

Another point (a symptom of the same problem, I think) is that I would
interpret an 'index of functions' as a listing of *definitions*
(functions, variables, whatever), while the entities you mention
('<function>', '<type>', etc.) are not targetted at definitions, but at
*references* to functions, types, etc., i.e. '<type>FooBar</type>'
merely states that FooBar is a type, it doesn't define it.

Or so at least I understand docbook.

Kind regards,
		Stefan