Re: Radical Parameters Proposal

/ Alex Milowski <alex@milowski.org> was heard to say:
| I feed like we lead ourselves into a deep dark road that
| leads into an abyss.  We have some basic requirements
| for parameters:
|
|   1. We need to be bind static values at the step-level.
|
|   2. We need to be able to select values for parameters from
|       input ports (pipeline or results of other steps).
|
| We've solved the above with the status quo document.
|
| We've also found that:
|
|  1. Different steps in the same "context" (e.g. sibling steps) may
|      having conflicting parameter names and values.
|
|   2. We need to be able to pass parameter values in from
|       external to the pipeline.
|
|   3. Some would like the ability to produce a parameter name/value
|       documents from steps within the pipeline (e.g. use XSLT to
|       generate step parameter bindings).
|
| With the status quo, (1) is a problem in that simple parameters
| passed in from "the command line" will conflict with the status
| quo.  The pipeline author has to do something with options to
| make that work with the status quo.

It's not just parameters from the command line, but any parameter set
on a compound step. I think our "treat the parameter pool like the
shell environment variable pool" decision, while simple in some ways,
was a mistake.

| Also, (2) has the consequence in the status quo document that
| if you pass in a parameter that for "step A" that unknowingly a
| parameter to "step B" that changes how "step B" works, you're
| going to get a different result than you might expect.  That's a big
| problem (or, at least, I think so).

Right.

| We just don't have a strong use case that supports (3) (see
| the requirements doc [1]).  We could certainly imagine that feature
| being useful and imagine more complicated versions of our
| use cases, but we haven't and doing so is adding work.
|
| Given all this, here's a radical proposal:
|
| 1. We drop in-scope parameters and cascading of parameter values.
|
| 2. Parameters can only be bound locally on the step invocation.
|
| 3. Options still work as they do and so you can always use
|    an option to pass in a parameter value by:
|
|      <p:parameter name="foo" select="$bar"/>
|
| 4. We allow the name to be set from a expression (syntax to
|    be "discussed):
|
|     <p:parameters match="/params/param" name="@name" select="@value"/>

I don't understand this step at all.

| 5. p:group no longer needs p:parameter as there isn't any in-scope
|    parameters.

By extension, none of the compound steps need it, I suppose.

| Keep in mind that you can still bind parameters to XPath
| expressions against ports.  That means you can pass
| a document to a pipeline with parameter name/value pairs
| of a syntax of you own choice and then select the values
| out of that document.
|
| What this means is that:
|
|   * if a step takes a parameter, you need to author that binding into
|     the pipeline.

Maybe this is where we need to go, but I'm uneasy about it because
one of the common cases, I think, will be a pipeline that does pre-
and post-processing of a single XSLT invocation. Like this one:

<p:pipeline xmlns:p="http://www.w3.org/2007/03/xproc"
	    xmlns:px="http://xproc.org/2007/03/xproc/ex">
<p:input port="source">
  <p:document href="langspec.xml"/>
</p:input>

<p:xinclude name="xinclude"/>

<p:validate-relax-ng name="validate">
  <p:input port="schema">
    <p:document href="../schema/dbspec.rng"/>
  </p:input>
</p:validate-relax-ng>

<p:xslt2 name="style">
  <p:input port="stylesheet">
    <p:document href="../style/dbspec.xsl"/>
  </p:input>
  <p:journal port="result" href="/tmp/secondary.xml"/>
</p:xslt2>

<p:store name="store">
  <p:option name="href" value="langspec.html"/>
</p:store>

<px:tidy name="tidy"/>

</p:pipeline>

When that XSLT invocation is transforming DocBook, there are literally
several hundred possible parameters. Telling the pipeline author to
provide options for all of them is impractical. Telling users they
can't pass options to the stylesheet probably makes XProc
uninteresting.

|   * you can only pass arbitrary parameters via an input to
|     the pipeline or a constructed result from some step in the pipeline.

But maybe we can use this to get around the preceding issue. Maybe.

|   * the author has ultimate control over parameter bindings and so
|     no command-line switch is ever going to make strange things
|     happen.
|
|   * if you have two XSLT steps with a need for different parameter
|     bindings, then you are just fine because you *have* to
|     specify parameter bindings.
|
| Our main use case is XSLT and most parameters to transformations
| are "feature switches" or additional datums.  As such, it isn't unreasonable
| to say, for V1, that you just have to know the transformation that you
| are embedding and if you want to expose a parameter to the user of
| the pipeline you either must use an option or bind the parameter value
| to a expression against an input port of the pipeline.

Unfortunately, I think for DocBook that might be unreasonable.

| I think this leaves the door open to future expansion and control over
| parameters and parameter sets.
|
| I did say it was radical and feel free to call me "insane".  :)

No, you're not insane (at least, this isn't evidence of insanity :-).
I was trying to craft something along the same lines.

If we said that there was some standard mechanism for reading "initial
parameters" from the pipeline's outside environment as a c:parameters
document, then maybe command line parameters could construct that. And
then steps could read it if they needed it.

I dunno. We need something.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | The facts, although interesting, are
http://nwalsh.com/            | usually irrelevant.