Support variadic parameters

[cmb69]

So far, PhD does not support variadic parameters. Instead the manual
follows the convention to use ... as parameter name, which is then
rendered as $... in the docs. However, as of PHP 5.6.0 variadic
parameters are supported using the syntax ...$args; therefore, we are
going to support this notation for PhD.

While DocBook supports a <varargs> element, this cannot be used in
combination with named parameters. Therefore, we use the role
attribute of the <parameter> element to declare variadic parameters.
Since the role attribute is already used to designate reference
parameters, we support the following values now: "reference",
"variadic" and "reference variadic"; additional whitespace as well
as swapping the order of the words is supported.

---

After applying this patch to the docs:

Index: sscanf.xml
===================================================================
--- sscanf.xml	(revision 350547)
+++ sscanf.xml	(working copy)
@@ -12,7 +12,7 @@
    <type>mixed</type><methodname>sscanf</methodname>
    <methodparam><type>string</type><parameter>str</parameter></methodparam>
    <methodparam><type>string</type><parameter>format</parameter></methodparam>
-   <methodparam choice="opt"><type>mixed</type><parameter role="reference">...</parameter></methodparam>
+   <methodparam choice="opt"><type>mixed</type><parameter role="reference variadic">args</parameter></methodparam>
   </methodsynopsis>
   <para>
    The function <function>sscanf</function> is the input analog of
@@ -72,7 +72,7 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><parameter>...</parameter></term>
+     <term><parameter role="variadic">args</parameter></term>
      <listitem>
       <para>
        Optionally pass in variables by reference that will contain the parsed values.

We get the following output for the sscanf() page:

Old-style pseudo-variadics (i.e. ...) are rendered like before, but of course the manual should be updated to use proper variadic parameters.

[salathe]

Big thumbs up on this change. Don't forget the non-XHTML-based formats.

Edit: I forgot to say, I would probably have just used the rep attribute of methodparam... but that's just me.

[cmb69]

I forgot to say, I would probably have just used the rep attribute of methodparam... but that's just me.

Ah, interesting! Not sure how to handle <parameter> elements outside of <methodparam> then.

If we want to stick with the role attribute, it might make sense to support three role values ("reference", "variadic" and "variadic-reference") instead of multiple space separated words.

Anyhow, I just noticed that the scrolling for the php format doesn't work with the variadics. Need to look into that.

Don't forget the non-XHTML-based formats.

Ah, good point!

[salathe]

Not sure how to handle <parameter> elements outside of <methodparam> then.

Why would they need to be handled (differently than today)? I missed this change in your description above, which gets a 👎 from me.

If we want to stick with the role attribute, it might make sense to support three role values ("reference", "variadic" and "variadic-reference") instead of multiple space separated words.

Urgh no.

Don't forget the non-XHTML-based formats.

Ah, good point!

Good luck. 😄

[cmb69]

Why would they need to be handled (differently than today)? I missed this change in your description above, which gets a 👎 from me.

They don't need to be handled differently. This PR merely gives the option to use <parameter role="variadic"> to show the parameter name with ... preprended. That might not be a good idea, though.

Anyhow, maybe the <methodparam rep="repeat"> solution is preferable; see PR #29.

[cmb69]

PR #29 has been merged, rendering this PR obsolete.