Grouping methodparams

[Norman Walsh <ndw@nwalsh.com>]

At the July meeting, I took an action to draft a content model for
addressing RFE #1998852[1].

Here it is:

namespace db = "http://docbook.org/ns/docbook";
default namespace = "http://docbook.org/ns/docbook";

# The only change here is to allow db.group.methodparams or
# db.methodparam in each of the synopses.

include "../docbook.rnc" {

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

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

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

}

# ======================================================================

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

   db.group.methodparams.role.attribute = attribute role { text }
   db.group.methodparams.rep.attribute = db.rep.attribute
   db.group.methodparams.choice.attribute = db.choice.opt.attribute

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

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

With the test case adapted to the new markup:

<chapter xmlns="http://docbook.org/ns/docbook";>
<title>Some title</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>

</chapter>

Pros:

* Addresses the requirement
* Reuses semantically similar construct from cmdsynopsis
* Doesn't add any new elements

Cons:

* Creates an element named <group> that has two substantially
  different content models depending on the context in which it is
  used.

Comments?

                                        Be seeing you,
                                          norm

[1] https://sourceforge.net/tracker/index.php?func=detail&aid=1998852&group_id=21935&atid=384107

-- 
Norman Walsh <ndw@nwalsh.com>      | Debugging is 99% complete most of
http://www.oasis-open.org/docbook/ | the time--Fred Brooks, jr.
Chair, DocBook Technical Committee |

PGP signature