[docbook] Re: documenting an API: RFE

[Norman Walsh <ndw at nwalsh dot com>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

/ 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',
|> <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.

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,
                                          norm

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

iD8DBQE+iefmOyltUcwYWjsRAkCJAJ0czMchKUZNes4vpLG0VAD782YboACgn2GX
3vcN8Wg4WAKhgKmJsDoypTY=
=zf5e
-----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