Re: DOCBOOK: Re: documenting an API: RFE

[Stefan Seefeld <seefeld@sympatico.ca>]

Hi Norman,

hoping that this thread simply got lost in your pile of mails
(instead of landing in your waste basket :-), I'll try another
one to show what kind of enhancements I'd like to see in docbook:

Norman Walsh wrote:

> | I'd like to document types, variables, constants,
> | functions, etc. But while some of them seem to be
> | supported (there are elements for 'classsynopsis'
> | and similar), others are not. Here is a list of elements
> | I miss. I'd very much appreciate if others could either
> | confirm that there is nothing semantically similar, or
> | how I could document these things instead:
> |
> | * 'type' seems to name types, not describe them. What
> |    about a 'typesynopsis' to actually define specific types ?
> 
> Can you show me an example of what you'd like to put in a type synopsis?

As you don't want to make docbook a modeling language, there is, as you
admit, not much value in emphasizing individual modeling specific artifacts
such as 'classes' (and thus 'classsynopsis'). So if we think for a moment
about all 'modeling-artifact' related markup being stripped off, it all
boils down to a refentry or similar. However, it would be wonderful to still
preserve a way to group or classify refentries, albeit not necessarily in
a fixed (hardcoded) way.

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):

Indices are generated for elements that are marked for a particular index.
That basically means all such entities are classified for specific (predefined
as well as user-defined) categories, and then a special command triggers the
generation of an index for a particular category.

Using this scheme, I would like to have categories such as 'types', 'functions',
'variables', 'concepts', 'requirements', 'patterns', etc., and then just use
refentries to actually describe all the individual items (with embedded 'synopsis'
elements).

In fact, having

a) a generic container that I can associate a user-defined 'type' with
    (such as 'concept', 'type', 'requirement') to hook up specific templates
    in the output generating xsl [*]

b) a means to generate indexes per category

Would be fairly enough, and I believe make some of the elements that go
into the modelling direction (funcsynopsis, classsynopsis, etc.) obsolete.

Does some of this make any sense ?

Kind regards,
		Stefan


[*] may be a 'generic container' isn't going to be a solution. May be an attribute
     would do the job. But the famous 'role' doesn't seem to be enough, if only
     because it's not preserved in the generated output in all cases.