This is the mail archive of the
mailing list for the DocBook project.
Re: [docbook] Re: documenting an API: RFE
- From: Stefan Seefeld <seefeld at sympatico dot ca>
- To: docbook <docbook at lists dot oasis-open dot org>
- Date: Thu, 03 Apr 2003 12:59:48 -0500
- Subject: Re: [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> <email@example.com>
Norman Walsh wrote:
| 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.
as it happens, I just filed an RFE concerning multiple 'typed' indexes.
That should make one aspect of what I'm talking about clear.
When thinking about it more, it hit me that what I'm looking for is in
some way covered by 'variablelist'. What I want is a structure for
(formal) definitions, i.e. possibly a generalization of 'varlistentry',
basically a pair of <term/> and <definition/>, where <definition/> would
be a wrapper for about anything (similar to the relatively generic child
of 'varlistentry' ('listitem'). It would be a generalization as such a
definition could well live outside of a list:
<body>the actual definition</body></definition>
<para>and now a list of them...</para>
<term>And yet another</term>
As you notice, I use 'definitionlist' as 'variablelist' is used,
but it's content 'definition' is not restricted to be used inside
Ok, that was the general part about 'definitions'. Another issue
related to definitions is some markup that describes the nature
of the thing being defined. As I suggeted earlier, docbook is a
bit inconsistent here, as it already supports some form of 'definition'
for specific objects (I'm thinking of 'classsynopsis', 'funcsynopsis',
With the appropriate markup, this could all be put into my suggested
'definition' structure. The markup that is still needed should be
general in nature, and extensible, i.e. user-defineable:
I may want to define types, constants, variables, requirements, use
Docbook should not be concerned about these, i.e. these 'types'
should be provided by the user. With some additional help from the
stylesheets this could be used in various ways, such as index or toc
generation, etc., or to format different definitions differently.
|> | '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.
the example shows a table with predefined rows. It's semantically
equivalent to a variablelist with predefined terms, where the user just
has to fill out the definitions...
The way I use this now is to set the 'role' attribute for the
variablelist parent element, and then provide xslt templates for this,
so I can control the output specifically (in html I just make sure the
'role' classifier is preserved so I can decorate the content with css,
in fo I generate an 'fo:block' to get the same effect).
However, not all definitions may be suitably represented by
variablelists. Still I'd like to mark it as being a 'definition'.
That's why I'm wondering whether docbook could be made a little more
expressive in this direction.
I believe together with the type specific index generation this is
already an extremely useful enhancement.
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