Parameters Proposal

I voted concur because after all that has been discussed both on the call
and
on the mailing list, I don't think the straw poll question was specific
enough.
There wasn't enough time to discuss that on the call in the last few
minutes.

I'm torn in that:

   * We've been discussing syntax where having child elements for
     parameters would really be a nice way to go.  There are
     plenty of options for extending this now and in the future.

  * The distinction between "configuration" parameters that are needed
    statically and application parameters is really small.  That means I
    think I've been convinced that Jeni is right here in that users won't
    get it.  Changing the syntax for specifying parameters misled
    me here...

I can live with having environment constraints that analyze pipelines
for statically known parameters (or not) and do appropriate additional
semantics.

For example, if an implementation has a script parameter to a script
component, they could set a security constraint that says they won't
accept that parameter dynamically.  A simple inspection of the
pipeline document can determine that and throw an error for a
security violation.

I think these choices are independent of each other.

The current status quo is that a step only gets parameters that are:

   * specified on the step itself
   * imported via an "p:import-parameter" element.

It might be nice to have the inverse of p:import-parameter to
allow the component to know what it can exclude from that set
for component purposes (e.g. exclude parameter p:initial-mode
from the set of parameters given to the XSLT transform).  I think
that will be useful for custom components that pass parameters
to component implementations that *enumerate* the set of
parameters available (something you can't do right now in XSLT
1 or 2).

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.

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

   * 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.

     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.

  * 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.

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.

For example, suppose someone uses Docbook for inline documentation
in their pipeline.  They would make the Docbook namespace
ignorable.  Now, if a transformation uses the same namespace for
stylesheet parameters, at the step level, they would need to be able
to say that the Docbook namespace is significant for parameter
elements somehow or they would need to say that certain parameter names
are significant.

The are a couple ways out of that box:

   * force the user to use the attribute syntax for that parameter
     name.
   * use p:import-parameter somehow
   * use the component definition (doesn't work for XSLT
     parameters)
   * use an attribute on the step element to re-define the namespace
     as significant (conflicts with setting parameters via
     attributes).
   * use a qualified attribute on the parameter element to
     make it significant.

That last one is my preference in that if the 'my' prefix's resolved
namespace is ignoreable, we could do:

<p:xslt name="makeitgo">
<my:parameter p:ignoreable='false'>...</my:parameter>
</p:xslt>

This is just an ugly case that shouldn't happen that often.


-- 
--Alex Milowski
"The excellence of grammar as a guide is proportional to the paucity of the
inflexions, i.e. to the degree of analysis effected by the language
considered."

Bertrand Russell in a footnote of Principles of Mathematics