Re: Parameters Proposal

On 2/22/07, Norman Walsh <Norman.Walsh@sun.com> wrote:
>
> / 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 :-)



Sure... I'm not sure we really need  an "exclude parameters" feature.   It
would
be up to the component to use it and so it could really mislead
users in thinking they have control when they don't (i.e. the component
ignores the set of excluded names).

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



I think I missed one making clear one crutial point in that there is
no "p:parameter" element anymore.  Any parameter element can have the
same structure as our current p:parameter element:

   <p:xslt name="maketoc">
       <p:input port="transform">...<p:input>
       <p:initial-mode select="/config/@mode">
           <p:pipe .../>
       </p:initial-mode>
    </p:xslt>

Thus, there wouldn't be more than one way (unless you consider the
attribute syntax).

People might find that strange...


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.


I'd be fine with that rule but... I might not want it if I couldn't
use unqualified attributes for simple configuration options.


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


Just throwing it in there... without it, the specification of simple
configuration parameters harder... which makes me not want it.


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



Well... unless we  say that all parameter elements can have the same syntax
as our current p:parameter element.

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



That's a nasty problem.

I could keep our current story on parameters with the p:parameter element
and just not worry about "configuration" parameters.  If you set the
p:initial-mode parameter for XSLT to set the initial mode and then need
a diffferent value for your transformation, you lose.  You'll have to
import your stylesheet and use a different parameter name to set
that value.

Our story then becomes really simple:  component have access to
in-scope parameters and what they do with them is up to the component.


Besides, if we drop this whole thing we'll get done sooner!!!


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