Re: [docbook] Re: Describing a methodparam

["Seth Call" <sethcall@gmail.com>]

Hi Norm,

Hard decision.  On one hand, ideally it'd be possible to eyeball descriptions along with the element they pertain to, which would be possible if there were embedded along with all the other elements relating to 'code modeling', so I have a strong urge to 'roll-my-own' structure my API documentation.  

However, if I do as you say, one would be able to know what they are looking at within a small amount of time, instead of having to figure out my arbitrary format.  The only downside be this layer of separation that will result in a fair amount of PgUp/PgDn as people hop from code elements to description elements.  A bit of human error is possible to. 

I'll go with what you say.  I do want to do it right, and I think that ultimately using the existing code modeling structures will mean I'm fighting the system less over the lifetime of this project.

I think, in order to keep it simple, I'm going to use <para> with a 'role' attribute of value 'description' (and of course xref to point back to original code elements) to give me something I can override in my XSLT rules.  I'm going to just lay the para's out 'flat' at the same level as the methodsynopsis (I don't have anything higher than methodsynopsis in the code heirarchy)

Thank you for replying,
Seth

On 12/12/06, Norman Walsh <ndw@nwalsh.com> wrote:

/ "Seth Call" <sethcall@gmail.com> was heard to say:
| I'm attempting to add a description to a methodparam, but see no correct way
| of doing so.

The methodparam and it's synopsis friends are one of the few places
where DocBook dips into modelling. Trying to mix the description
directly into that model would seem to greatly complicate it.

One option is to use linking (link the param to its description or
vice versa).

                                        Be seeing you,
                                          norm

--
Norman Walsh <ndw@nwalsh.com>      | Use the memory of thy predecessor
http://www.oasis-open.org/docbook/ | fairly, and tenderly; for if thou
Chair, DocBook Technical Committee | dost not, it is a debt will sure
                                   | be paid, when thou art gone.--Sir
                                   | Francis Bacon