Re: [docbook] Re: documenting an API: RFE

[Stefan Seefeld <seefeld@sympatico.ca>]

Norman Walsh wrote:

> | What I'm thinking of is something similar to texinfo, and its way to deal
> | with indices (http://www.gnu.org/manual/texinfo-3.9/html_node/texinfo_137.html):
> 
> You can certainly create indexes in DocBook (by adding indexterm
> elements). And you could easily generate special-purpose indexes by
> gathering together the definitions that you markup in your sources.

Sorry, I totally missed the automatic index generation when reading your (online)
book. The examples on the <index> element all fill the index explicitely with
<indexentry>, that made it look inappropriate for my purposes.

I don't really understand what you mean with 'gathering together the definitions'.
I'd like to classify those 'indexterms' such that I could generate an index
for a specific class.

> | Using this scheme, I would like to have categories such as 'types',
> 
> <type>

My impression was that <type> is to be used to mark up a word within a text.
What I'm after is some structure such as a 'term' / 'synopsis' pair, i.e.
a formal definition (of types, in this case). Given that this is agnostic
to programming languages, I'd like to provide some attribute that gives
the language specific name of the type, i.e. the 'meta-type', such as
'class', 'typedef', 'enum' (in C++) to name just a few.

> | 'functions',
> 
> <function>

see above.

> | 'variables',
> 
> <varname>

see above. The term 'varname' makes it obvious (well, I think) that this
is not what I'm looking for: I'm not marking up a name, but a definition
of a variable (again, with a 'term' and a 'synopsis' or something semantically
equivalent).

> | 'concepts', 'requirements', 'patterns', etc., and then just use
> 
> These look more like section headings or something to me.

Indeed, they could be. But they may as well not. I'm trying to find a way
to mark an element in a way that doesn't impose any specific substructure,
yet allows me to recognize that this is a 'requirement' definition (say).
For example http://www.bredemeyer.com/pdf_files/UseCase_Template.PDF
proposes a table as a 'use case template'. I'd like to provide similar
templates for this and other artifacts that occur in the software development
process, using docbook. For now, I'm using '<variablelist role="usecase">,
and I wrote special xslt templates (and of course css styles) for all the
different output media I'd like to support (html and fo, notably).

So the question I have is: is this the right approach ? Could it be done
in better ways, a) within the current docbook vocabulary, and b) could
docbook itself be enhanced to better support this.
Again, I'd like to be able to generate an index for all 'use cases' (say).
Or, if a toc is more suitable, a 'toc'.

> | b) a means to generate indexes per category
> 
> That'd require a little more stylesheet work, but it's certainly possible.

yeah, it looks so. Such as adding a classifier attribute to indexterm
and index...

> | Would be fairly enough, and I believe make some of the elements that go
> | into the modelling direction (funcsynopsis, classsynopsis, etc.) obsolete.
> 
> Well, I'm not ready to throw out what we have (nor am I personally
> opposed to changing it to make it more useful). I just don't want to
> add another complex, modelling construct if we can avoid it.

Well, I'm not looking for an additional construct, but may be one that would
unify existing ones while at the same time being more generic.

Put differently, what is necessary (with or without changes to the docbook
dtd/schema) to be able to index all type definitions in the document (whether
classes, functions, enums, whatever).

Kind regards,
		Stefan