Re: Option or parameter?

Norman Walsh wrote:
> Options provide configuration information for the pipeline processor
> to use when it is setting up the steps. Things such as whether or not
> the XInclude processor outputs xml:base attributes, what initial mode
> the XSLT processor should use, whether validation should be strict or
> lax. Options are strictly local to the step on which they occur,
> they aren't in the environment and they aren't visibile to other
> steps.
> 
> Parameters are information that the processor passes blindly to the
> step. The processor neither knows nor cares what they do or what
> they're for, it just assumes the step will know. Any parameter visible
> to a compound step is also visible to all its contained steps.
> Parameter values are passed in the environment. Parameters may be
> shadowed.

It seems that you're saying that the distinction between options and 
parameters is that options are used to configure atomic components and 
parameters are used to configure compound components (including called 
pipelines).

I think that distinction is hard on users. It means that they have to 
know whether a particular component is an atomic component or a compound 
component when they call it. That's fine in a very basic environment 
where all atomic components are in the XProc namespace, but in a more 
complex one where you have components (in multiple namespaces) provided 
by the implementation and pipeline libraries, it's going to be hell.

Let me take another tack. Take as a starting point an XSLT 2.0 step:

<p:xslt2>
   <p:input port="stylesheet">
     <p:document href="foo2html.xsl" />
   </p:input>
   <p:option name="initial-mode" select="$view" />
   <p:import-parameter name="*" />
</p:xslt2>

Let's say that we want to provide an easier interface to calling the 
foo2html.xsl stylesheet, and wrap it in a pipeline. Currently, this has 
to be:

<p:pipeline name="my:foo2html">
   <p:input port="source" />
   <p:output port="result" />
   <p:parameter name="initial-mode" required="yes" />
   <p:parameter name="*" />
   <p:xslt2>
     <p:input port="stylesheet">
       <p:document href="foo2html.xsl" />
     </p:input>
     <p:option name="initial-mode" value="$initial-mode" />
     <p:import-parameter name="*" />
   </p:xslt2>
</p:pipeline>

and I replace my original <p:xslt2> with:

<my:foo2html>
   <p:parameter name="initial-mode" select="$view" />
   <p:import-parameter name="*" />
</my:foo2html>

I had to make three changes here: change the name of the step (as 
expected), remove the <p:input> (as expected), and change the <p:option> 
to <p:parameter> (as completely unexpected).

What's more, now my stylesheet works differently. Turns out it had an 
initial-mode parameter declared, and now it's picking up the value from 
the pipeline environment! Along with all the other parameters, used to 
configure the pipeline and the steps that the pipeline calls, that are 
flying around in the pipeline.

By comparison, if <p:parameter> is reserved for passing parameters into 
stylesheets (and other components that require arbitrary name/value 
pairs) then I only have to make the expected changes in the call in the 
original pipeline, and I don't end up with naming clashes.

Cheers,

Jeni
-- 
Jeni Tennison
http://www.jenitennison.com

Received on Wednesday, 25 April 2007 14:21:33 UTC