Re: Parameters Proposal

/ Alex Milowski <alex@milowski.org> was heard to say:
[...]
| Here's my proposal on this:
|
|   * We have one set of in-scope parameters available to a component.
|
|   * We add a feature for defining a set of excluded parameter
|     names.  This doesn't change the available in-scope
|     parameters.  It just provides a set of names that can be
|     used as needed by the component.  This syntax will
|     allow us to deal with wildcards and namespace prefix
|     resolution just as p:import-parameter does.
|
|     For example:
|
|        <p:exclude-parameter name="p:*"/>
|
|     defines as the set of excluded names as those in the
|     pipeline document namespace.  For XSLT, that would
|     exclude the "p:initial-mode" parameter.

So the user would write:

  <p:xslt>
    <p:input port="stylesheet" href="docbook.xsl"/>
    <p:parameter name="p:initial-mode" value="foo"/>
    <p:import-parameter name="db:*"/>
    <p:exclude-parameter name="p:*"/>
  </p:xslt>

Or even:

  <p:xslt>
    <p:input port="stylesheet" href="docbook.xsl"/>
    <p:parameter name="p:initial-mode" value="foo"/>
    <p:import-parameter name="db:*"/>
    <p:exclude-parameter name="p:*"/>
    <p:exclude-parameter name="db:bar"/>
  </p:xslt>

It looks like there's room for misunderstanding there :-)

|   * We change the syntax for setting parameters to:
|
|     Any child element that is not :
|
|        * p:input
|        * p:import-parameter
|        * the "new exclude parameter" element as above
|
|     is considered a parameter unless the element's namespace
|     is defined as ignorable.
|
|     The parameter is set via the same syntax as our current p:parameter
|     element.
|
|     This also means you can't use the element syntax to set a
|     parameter named 'p:input' and 'p:import-parameter'.
|
|     Example:
|
|        <p:xslt name="maketoc">
|            <p:input port="transform">...<p:input>
|            <p:initial-mode>toc</p:initial-mode>
|        </p:xslt>

Does this mean exactly the same thing as:

        <p:xslt name="maketoc">
            <p:input port="transform">...<p:input>
            <p:parameter name="p:initial-mode" value="toc"/>
        </p:xslt>

If so, I'm strongly opposed. I don't want to allow more than one way
to do something if we can possibly avoid it.

|   * We take advantage of having an attribute syntax for parameters
|     by taking any attribute and setting parameters via these rules:
|
|        1. If the name of the attribute is 'name', it is not a parameter.
| Note
|            that we need this because we need to name steps.
|        2. The component definition may define a default namespace for
|            parameters specified as attributes.  No default means no
|            namespace.
|        3. The parameter name is:
|              * qualified with a namespace and and the attribute name is
| used.
|              * in no namespace and the default namespace is taken into
|                consideration.
|        4. The parameter value is the value of the attribute.

I'm on the fence about whether or not I want to do this; see my point
above about not allowing more than one way to do something. But if we
did decide that this convenience was so important that we want to
allow it, I'd propose simpler rules:

1. Any attribute on a component that is in the pipeline namespace is
equivalent to a parameter with that name and the attribute's value.

So

  <p:xslt name="maketoc" p:initial-mode="toc">
    <p:input port="stylesheet">...<p:input>
  </p:xslt>

is absolutely equivalent to

  <p:xslt name="maketoc">
    <p:input port="stylesheet">...<p:input>
    <p:parameter name="p:initial-mode" value="toc"/>
  </p:xslt>

|     With the attribute syntax, you can now set a parameter named
|     'p:input' and 'p:import-parameter'.
|
|     Example:
|
|        <p:xslt name="maketoc" initial-mode="toc">
|            <p:input port="transform">...<p:input>
|        </p:xslt>
|
|     which assumes the default namespace for attribute parameters is the
|     pipeline document's namespace.

Attributes with no prefix are in no namespace, I wouldn't even
consider doing something that violated that user expectation.

|  * It is an error to set the same parameter via an attribute and a child
| element.
|
| I can certainly live without the attribute syntax for parameters--but I
| really do
| like it.  It also provides a way to set any parameter name as you can't
| have an parameter element named 'p:input' and 'p:import-parameter'.
| Consider also that we must have the element syntax because there would be
| no way of setting a parameter named 'name' otherwise.

There's no question that we have to have the p:parameter element because
that's how we set dynamic values. I'm not sure what your point is about
parameters named p:input as you can certainly say:

  <p:parameter name="p:input" value="foo"/>

| One drawback here is that we having the attribute syntax means we have
| two ways to set a parameter.
|
| Also, having the element name of the child element be the parameter name
| has one issue that we'd have to be careful about.  With the adoption of
| element names to specify component type, we'll need to define a
| set of ignorable namespaces for allowing documentation in our
| pipelines.  If we have ignorable namespaces, then a step can't
| specify a parameter in the ignorable namespace as an element
| unless we have a way of overriding the set of ignorable namespaces.  That
| is a snag but one that can be fixed in a reasonable way.

I think you've just convinced me that I don't want to specify
parameters using the name of the parameter as the name of the element.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh
XML Standards Architect
Sun Microsystems, Inc.