This is the mail archive of the
mailing list for the DocBook project.
[docbook] Re: documenting an API: RFE
- From: Norman Walsh <ndw at nwalsh dot com>
- To: docbook <docbook at lists dot oasis-open dot org>
- Date: Tue, 01 Apr 2003 14:26:30 -0500
- Subject: [docbook] Re: documenting an API: RFE
- References: <3E6AA059.firstname.lastname@example.org> <email@example.com><3E81256D.firstname.lastname@example.org> <email@example.com><3E8663CD.firstname.lastname@example.org>
-----BEGIN PGP SIGNED MESSAGE-----
/ Stefan Seefeld <seefeld at sympatico dot ca> was heard to say:
| 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.
Right. I think you want to generate some additional index terms from
other markup, perhaps implicitly. I wasn't suggesting that you need to
markup all your cases with indexterm explicitly.
| 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',
| 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.
I'm sorry, I'm obviously being clueless. Can you provide some concrete
examples? Just make up the element names you think you need. I simply
don't understand what you're looking for yet.
|> | '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
I'm offline at the moment, so I can't look at the example.
| 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).
If variablelist suits your needs, that seems like a fine approach to me.
| 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'.
| 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).
I don't think I can offer any enhancement suggestions until I
understand your needs better.
Be seeing you,
Norman Walsh <ndw at nwalsh dot com> | My problems start when the smarter
http://www.oasis-open.org/docbook/ | bears and the dumber visitors
Chair, DocBook Technical Committee | intersect.--Steve Thompson,
| wildlife biologist at Yosemite
| National Park
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.7 <http://mailcrypt.sourceforge.net/>
-----END PGP SIGNATURE-----
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