docbook-apps

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.

By using choice="opt" on the methodparam, I can mark the parameters
individually, but not as a group.

Is there any way of doing this that I'm missing?

If not, then is it possible to introduce a new tag - methodparamgroup.

I could then ...

<methodsynopsis>
<type>string</type>
<methodname>number_format</methodname>
<methodparam>
<type>float</type>
<parameter>number</parameter>
</methodparam>
<methodparamgroup choice="opt">
<methodparam>
<type>int</type>
<parameter>decimals</parameter>
</methodparam>
<methodparamgroup choice="opt">
<methodparam>
<type>string</type>
<parameter>dec_point</parameter>
</methodparam>
<methodparam>
<type>string</type>
<parameter>thousands_sep</parameter>
</methodparam>
</methodparamgroup>
</methodparamgroup>
</methodsynopsis>

This would allow me to have 1, 2 or 4 parameters (which is what I want).

I would like the methodparamgroup to support both the choice and the
rep attributes and contain only methodparams and methodparamgroups.

I suspect that this mechanism may be useful in other groupings
(cmdsynoposis, funcsynopsis, etc.) and the name of methodparamgroup
may need to be changed. That's fine, it is the mechanism and not the
tag I'm after.

Any ideas? Have I missed something?

Regards,

Richard.

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

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/>

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

--

...ich hab' noch einen Koffer in Berlin...

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!"

Richard Quadling wrote:
> 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.

(For the record, I was referring to Synopsis:
http://synopsis.fresco.org, which is a tool with similar features to
doxygene. It's about the only one, though that can generate DocBook output.)

As to your actual question: yes, I believe it would be better to list
this as a set of functions with different signatures (an overload set in
C++). For example:

http://boost.org/libs/python/doc/v2/class.html#class_-spec-ctors

This wasn't generated from docbook, but it could easily be.
(One funcsynopsis can hold more than one funcprototype.)

> Our current solution is to provide multiple methodsynopsises.

Exactly. I think this is the right thing to do.

Regards,
Stefan

--

...ich hab' noch einen Koffer in Berlin...