2008/7/18 Norman Walsh <[EMAIL PROTECTED]>: > 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 <[EMAIL PROTECTED]> | 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!"
