This is the mail archive of the docbook@lists.oasis-open.org 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]

Re: [docbook] Re: documenting an API: RFE

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:

<section>
  <title>Definitions ahead</title>
  <definition>
    <term>Something</term>
    <body>the actual definition</body></definition>
  </definition>
  <para>and now a list of them...</para>
  <definitionlist>
    <definition>
      <term>Something else</term>
      <body>the definition</body></definition>
    </definition>
    <definition>
      <term>And yet another</term>
      <body>the definition</body></definition>
    </definition>
  </definitionlist>
</section>

As you notice, I use 'definitionlist' as 'variablelist' is used,
but it's content 'definition' is not restricted to be used inside
'definitionlist'.

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', etc.).

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
cases, etc.
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.

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

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