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

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

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


Subject: Re: [docbook] RFE #1998852: Provide a mechanism to group parameters.


2008/7/18 Norman Walsh <ndw@nwalsh.com>:
The DocBook TC is considering solutions to RFC 1998852 which asks
for a mechanism to group method parameters.

Instead of creating new elements for this purpose, it was suggested
that we already have a group element that we could use for this
purpose. (It already serves an analagous role in grouping arguments in
a cmdsynopsis.)

The results can be seen in this experimental customization layer:

namespace ctrl = "http://nwalsh.com/xmlns/schema-control/"
namespace rng  = "http://relaxng.org/ns/structure/1.0"
namespace s = "http://www.ascc.net/xml/schematron"
namespace db = "http://docbook.org/ns/docbook"
default namespace = "http://docbook.org/ns/docbook"

include "../docbook.rnc" {

  db.constructorsynopsis =
     element constructorsynopsis {
        db.constructorsynopsis.attlist,
        db.modifier*,
        db.methodname?,
        ((db.methodparam|db.group.methodparam)+ | db.void?),
        db.exceptionname*
     }

  db.destructorsynopsis =
     element destructorsynopsis {
        db.destructorsynopsis.attlist,
        db.modifier*,
        db.methodname?,
        ((db.methodparam|db.group.methodparam)+ | db.void?),
        db.exceptionname*
     }

  db.methodsynopsis =
     element methodsynopsis {
        db.methodsynopsis.attlist,
        db.modifier*,
        (db.type | db.void)?,
        db.methodname,
        ((db.methodparam|db.group.methodparam)+ | db.void),
        db.exceptionname*,
        db.modifier*
     }

  db.funcprototype =
     element funcprototype {
        db.funcprototype.attlist,
        db.modifier*,
        db.funcdef,
        (db.void | db.varargs | ((db.paramdef|db.group.paramdef)+, db.varargs?)),
        db.modifier*
     }

}

[
  db:refname [ "group" ]
  db:refpurpose [ "A group of method parameters" ]
]
div {

  db.group.methodparam.role.attribute = attribute role { text }
  db.group.methodparam.choice.attribute = db.choice.opt.attribute

  db.group.methodparam.attlist =
     db.group.methodparam.role.attribute?
   & db.common.attributes
   & db.common.linking.attributes
   & db.group.methodparam.choice.attribute?

  db.group.methodparam =
     element group {
        db.group.methodparam.attlist,
        (db.methodparam|db.group.methodparam)+
     }
}

[
  db:refname [ "group" ]
  db:refpurpose [ "A group of parameters" ]
]
div {

  db.group.paramdef.role.attribute = attribute role { text }
  db.group.paramdef.choice.attribute = db.choice.opt.attribute

  db.group.paramdef.attlist =
     db.group.paramdef.role.attribute?
   & db.common.attributes
   & db.common.linking.attributes
   & db.group.paramdef.choice.attribute?

  db.group.paramdef =
     element group {
        db.group.paramdef.attlist,
        (db.paramdef|db.group.paramdef)+
     }
}

And its accompanying test document:

<article xmlns="http://docbook.org/ns/docbook">
<title>Method Parameter Grouping Test</title>

<methodsynopsis>
<type>int</type>
<methodname>x</methodname>
<methodparam>
<type>int</type>
<parameter>param1</parameter>
</methodparam>
<group choice="opt">
<methodparam>
<type>string</type>
<parameter>param2</parameter>
</methodparam>
<methodparam>
<type>float</type>
<parameter>param3</parameter>
</methodparam>
<group choice="opt">
<methodparam>
<type>array</type>
<parameter>param4</parameter>
</methodparam>
<methodparam>
<type>array</type>
<parameter>param5</parameter>
</methodparam>
<group choice="opt">
<methodparam>
<type>boolean</type>
<parameter>param6</parameter>
</methodparam>
</group>
</group>
</group>
</methodsynopsis>

</article>

This seems a perfectly tractable answer, but its worth noting that
this would be the first case of an element with two distinct,
unrelated content models. (We already use multiple patterns for the
same element to handle validation of some attribute co-constraints,
but those are much more closely related, or at least they feel that
way to me.)

Does anyone think that this would be confusing?

Technically, there is no way to represent this in DTD syntax and,
though it could be represented in XSD, our current method of
generating the XSD would not be able to cope. But I'm inclined to
think that we shouldn't feel constrained by the limitations of DTDs
and perhaps we need to build a better XSD in any event.

                                       Be seeing you,
                                         norm

--
Norman Walsh <ndw@nwalsh.com>      | One should always be a little
http://www.oasis-open.org/docbook/ | improbable.--Oscar Wilde
Chair, DocBook Technical Committee |

Hello all and thank you for looking at this.

Whilst the proposal only covered methodsynopsis, if it is not too late, is it possible to include this change for constructorsynopsis, destructorsynopsis, functionsynopsis as well?

I didn't look far enough beyond what I was doing when I made the proposal. Sorry.

Regards,

Richard Quadling.

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