This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: [docbook] Re: documenting an API: RFE
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
---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe at lists dot oasis-open dot org
For additional commands, e-mail: docbook-help at lists dot oasis-open dot org