OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [docbook-apps] Grouping methodparams.

On 20/02/2008, Stefan Seefeld <seefeld@sympatico.ca> wrote:
> Richard Quadling wrote:
> > Hi.
> >
> > I am using methodsynopsis and have some parameters which are optional.
> >
> > But, there is a pair of parameters that have to go together.
> >
> > e.g. function(param1 [, param2 [, param3, param 4]])
> >
> > Here params 3 and 4 are to the function, but must both be present.
> > Either 1, 2 or 4 params. Never 3 params.
> I don't think this is currently possible, and I'm not sure adding
> support for this is appropriate. The whole set of <synopsis> tags is to
> reflect language artifacts as far as syntax is concerned, not to express
> semantic constraints on top of that.
> Norm indicated he didn't want docbook to incorporate more than a minimal
> set of modeling vocabulary. There is a whole lot of other things to be
> added if docbook were to expand into that modeling direction. (There is
> no 'type synopsis', for example.)
> May be an extension 'profile' could be created for such things ? <hint/>

I'm not sure I understand you. Does anyone know of any other APIs
documented using Docbook? I would really like to see how others have
handled this.

Our current solution is to provide multiple methodsynopsises.

> Regards,
>                 Stefan
> PS: As I'm working on a tool that generates a docbook reference manual
> from APIs (in different programming languages), I hit various
> limitations as to what can be represented in docbook. I do think having
> an extension vocabulary on top of docbook to capture this would be very
> helpful.
> There was a similar efford as part of boost
> (http://www.boost.org/doc/html/boostbook.html), and I believe it would
> be nice to move that closer to docbook. Norm, what's your perspective on
> this ?
> Regards,
>                 Stefan

Richard Quadling
Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498&r=213474731
"Standing on the shoulders of some very clever giants!"

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]