search

xproc / 1.0-specification

The 1.0 XProc specification and now abandoned drafts of a 2.0 XML specification
12 stars 6 forks source link

Clarify the distinction between p:input declarations and connections even better #147

Open gimsieke opened 9 years ago

gimsieke commented 9 years ago

When I learned XProc, a thing that bothered me (and other people I know) is the dual nature of p:input as a declaration and as a connector. In the section about p:input, the distinct content models for declarations and connections are given and the distinction is explained, but I think it should be explained even more thoroughly. Maybe by giving non-normative examples there, and/or warning boxes in p:declare-step and p:input. The warning boxes could simply state that people should read the section thoroughly and understand this distinction. (Admitting that warning boxes only for this specific matter might make people think that they may read other parts of the spec less thoroughly, so unsure how to deal with this. Just wanted to let you know about this issue along my learning curve and ask whether you think that we should do something about it.)

xquery commented 9 years ago

I agree that the overloading of syntax in both instantiation/usage of a step and its declaration does result in a higher cognitive load.

Speaking for myself only, I think the changes in documentation is in scope for v2 but I do wonder if we need to consider any further steps.

josteinaj commented 9 years ago

How about p:input for declarations and p:with-input for invocations?

xquery commented 9 years ago

your suggestion provides an attractive symmetry, though I think the existing usage is an abstraction we may have to live with ... will present it to WG and see what consensus emerges.