Skip to content

Renaming p:input to p:with–input for port connections

Jump to bottom
Gerrit Imsieke edited this page Sep 12, 2017 · 2 revisions

One idea to improve learnability of XProc and prevent learners from running into troubles is to remove the dual use of <p:input /> in XProc 1.0: <p:input /> is either the declaration of an input port or provides an input port with a connection when calling a step.

We do not have such an ambiguity with options: Options are declared with <p:option /> and values are provided to declared option via <p:with-option />. Therefor we discussed about using <p:input /> in XProc 3.0 only for the declaration of ports and introduce <p:with-input /> for port binding.

Of course this change will make XProc even more verbose. To give you an idea of this might look like, I took one of the example pipelines from the specs (where all connections are explicit) and changed it to the proposed new style:

    <p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
		name="xinclude-and-validate"
		version="3.0">
      <p:input port="source" primary="true"/>
      <p:input port="schemas" sequence="true"/>
      <p:output port="result">
        <p:pipe step="validated" port="result"/>
      </p:output>

      <p:xinclude name="included">
        <p:with-input port="source">
          <p:pipe step="xinclude-and-validate" port="source"/>
        </p:with-input>
      </p:xinclude>

      <p:validate-with-xml-schema name="validated">
        <p:with-input port="source">
          <p:pipe step="included" port="result"/>
        </p:with-input>
        <p:with-input port="schema">
          <p:pipe step="xinclude-and-validate" port="schemas"/>
        </p:with-input>
      </p:validate-with-xml-schema>
    </p:declare-step>

I will add one or more examples in the coming days

The basic question from my point of view is, whether this change will result in the improvements we expect from it. Having to type 10 letters more may be an acceptable price for improved learnability.

If you take this change together with proposed syntactic sugar, the effort to write a pipeline might be comparable to XProc 1.0 (hopefully even less). For example if we have

    <p:with-input port="source" href="uri" />

as a shortcut for

    <p:with-input port="source">
      <p:document href="uri" />
    </p:with-input>

We could do the same with <p:pipe /> if someone comes up with a clever proposal to distinguish between the bound port and the pipe port:

    <p:with-input port="source" step="step" ??="port" />

Please feel free to put your comments, critique or proposals below. Please separate it with a horizontal rule to improve readability.

GI: Maybe step-port="…"?

I wonder, though, whether learning this syntactic alternative for simple plumbing tasks will make it even harder for beginners to grasp the language.

Generally, although it looks verbose and unfamiliar in the beginning, I’m in favor of p:with-input for connections. People who argue for conciseness should consider renaming p:with-option to p:option (or they should consider not using an XML syntax at all…)

Clone this wiki locally