This is the mail archive of the mailing list for the DocBook project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[docbook] Re: documenting an API: RFE

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

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 | bears and the dumber visitors
Chair, DocBook Technical Committee | intersect.--Steve Thompson,
                                   | wildlife biologist at Yosemite
                                   | National Park
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.7 <>


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

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]