Re: Parameters

"Toman, Vojtech" <vojtech.toman@emc.com> writes:
>> Let's consider the requirement for parameters and some use cases.
>> 
>> The requirement: in the simple case where the pipeline author does
>> nothing with (may even be entirely ignorant of) parameters, users can
>> still pass parameters to steps in the pipeline.
>> 
>> In other words, given this pipeline:
>> 
>> <p:declare-step version="1.0" name="main" type="ex:simple"
>>                 xmlns:p="http://www.w3.org/ns/xproc">
>>   <p:input port="source"/>
>>   <p:output port="result"/>
>> 
>>   <p:xinclude/>
>> 
>>   <p:xslt>
>>     <p:input port="stylesheet">
>>       <p:document href="style.xsl"/>
>>     </p:input>
>>   </p:xslt>
>> </p:declare-step>
>> 
>> It must be possible for users to pass parameters to the contained XSLT
>> step. This is the requirement that forces us to indulge in some sort of
>> magic. The whole magic binding of parameter input ports in V1 is based
>> on this requirement.
>
> OK. I have not been with the WG since the very beginning, so if this
> has always been a hard requirement, then I give up.

It was a V1 requirement. We can reconsider the requirement in V2. As I
went on to say later in this message, I fear that if we drop that
requirement, almost no pipeline will accept any parameters at all
because most pipeline authors won't think to support them.

> (Btw, do we all agree that the above pipeline is invalid (the primary
> parameter port of p:xslt is unconnected) - but even if it were valid,
> that the user cannot pass any parameters to the pipeline, because it
> has no parameter ports?)

Yes. (Proving, in passing, just how broken parameters are in V1!)
Here's what I meant:

<p:declare-step version="1.0" name="main" type="ex:simple"
                xmlns:p="http://www.w3.org/ns/xproc">
  <p:input port="source"/>
  <p:input port="parameters" kind="parameter"/>
  <p:output port="result"/>

  <p:xinclude/>

  <p:xslt>
    <p:input port="stylesheet">
      <p:document href="style.xsl"/>
    </p:input>
  </p:xslt>
</p:declare-step>

> The way I see the above example is this (and it actually feels natural
> to me): ex:simple has no parameter input port, therefore the user
> cannot pass any parameters to it (nor to the stylesheet). However, if
> I - as the pipeline author - am aware that the stylesheet takes
> parameters AND I DO WANT to give the user the ability to pass
> parameters to the stylesheet, I may decide to add a parameter input
> port to the main pipeline. On the other hand, if the stylesheet takes
> parameters BUT I DON'T WANT the user to pass any parameters to it, I
> simply don't add a parameter port to the pipeline.

That amount of control is still present in the Edinburgh proposal.

  <p:xslt>
    <p:with-option name="parameters" select="map:new()"/>

(Or maybe we make the type of the parameters port map(QName,item*)? in
which case I can simply pass in the empty sequence.)

>> It also means that the vast majority of pipelines will *not* accept
>> *any* parameters because the pipeline author will never have thought of
>> it.
>
> I prefer a situation where pipelines accept parameters because the
> pipeline author has thought about it.

I understand the appeal.

>> The only thing you don't get, really, is the ability to control the
>> parameters used by a third party pipeline that was written without
>> thinking about parameters.
>
> Yes. I am just worried that we are being a bit too optimistic here (in
> the "it will work out somehow" sense) about what can go wrong with
> this setup.

But that's completely analagous to the current setup with a single
primary parameter input port. And I've never seen a pipeline with more
than one parameter input port in the wild.

I'm not aware of any reports of problems, even though there are
clearly opportunities for problems in principle.

> Having no magic for parameters makes things even simpler :)

Not simpler for users. The advantage of a little bit of magic is that,
I think, most things just work most of the time. You can pass through
the occasional parameter and it works even though you didn't plan for
it.

If, after you've been using XProc for years and your comfortable with
it, you finally come across a situation where the defaulting story
does the wrong thing, you can easily fix it.

> But honestly, I see the benefits of the proposal, I am just worried
> about three things:
>
> 1. The maintainability if you depend on 3rd-party pipelines

Even in V1, if you wanted 3rd-party pipelines to work reliably, you'd
need to use multiple parameter input ports and manage things quite
carefully. I'm not going to assert that's *never* been done, but it sure
isn't the common case in my experience. 

> 2. That we may be trading one complex/confusing V1 concept (parameter
> input ports) for another (named parameter maps, and p:parameter-map()
> lurking in the option declarations)

Fair point. I think it's vastly less complex, but there's still a
little subtlety lurking.

> 3. Do we really need all of this?

If we want to satisfy the aforementioned requirement, I think we have
to do *something* magic.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh
Lead Engineer
MarkLogic Corporation
Phone: +1 512 761 6676
www.marklogic.com