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

[Norman Walsh <ndw@nwalsh.com>]

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

/ Stefan Seefeld <seefeld@sympatico.ca> was heard to say:
| 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:

Lost in some pile, I guess. I was also unsubscribed for a few days (grrrrr...)

Anyway, I'm still trying to get caught up.

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

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.

| Using this scheme, I would like to have categories such as 'types',

<type>

| 'functions',

<function>

| 'variables',

<varname>

| 'concepts', 'requirements', 'patterns', etc., and then just use

These look more like section headings or something to me. Perhaps:

<section role="concept"><title>The Art of Debugging</title>
...

| 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 [*]

<section>?

| b) a means to generate indexes per category

That'd require a little more stylesheet work, but it's certainly possible.

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

Well, I'm not ready to throw out what we have (nor am I personally
opposed to changing it to make it more useful). I just don't want to
add another complex, modelling construct if we can avoid it.

                                        Be seeing you,
                                          norm

- -- 
Norman Walsh <ndw@nwalsh.com>      | The human race consists of the
http://www.oasis-open.org/docbook/ | dangerously insane and such as are
Chair, DocBook Technical Committee | not.--Mark Twain
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.7 <http://mailcrypt.sourceforge.net/>

iD8DBQE+hepAOyltUcwYWjsRAvwYAJ4wLpHFRLqARYXTXeBYlScRXJH8QQCeI2PN
auWFa6qYkR37wAAnFfm9pDQ=
=iVId
-----END PGP SIGNATURE-----