Re: Spec progress

Hi Norm,

Norm Walsh wrote:
> Those wishing to peek at the inner working's of your humble editor's
> deranged mind are encouraged to consider the evidence at
> 
>   http://www.w3.org/XML/XProc/docs/langspec.html
> 
> I've worked my way from the top of the document down to Section 4.6.
> (Everything after that is likely to be cruft.)

Good work! I know we want to get this out the door, so I've tried to 
limit myself to editorial comments. Feel free to ignore those that aren't.

1. Section 2 (Pipeline Concepts), 2nd para, last sentence:

   s/imputs/inputs/


2. Section 2.1 (Components), last para, last sentence:

   "In other words, every input and required parameter must be specified;
    no undeclared outputs can be specified, but some declared outputs may
    be left unspecified; and no undeclared parameters can be specified,
    but parameters that are not required do not have to be specified."

isn't all that much clearer than the more formal definition! :) Perhaps:

   "In other words, every input and required parameter must be specified
    and only inputs, outputs, and parameters that are declared may be
    specified. Outputs and optional parameters do not have to be
    specified."

(FWIW, if we don't specify outputs when we instantiate components (i.e. 
don't have a <output> within <step> then we should probably change this 
definition to make it clearer that "specifying an output" actually means 
referencing it from elsewhere.)


3. Section 2.2 (Inputs and Outputs), 1st para, 2nd sentence:

   "Each XML document (or document in a sequence) must be a well formed
    XML document conforming to the document production of [ XML 1.0 ] or
    the document production of [ XML 1.1 ]."

One day it would be useful to have a note or something that indicates 
that implementations can pass character streams, SAX streams, Infosets, 
DOMs, PSVIs, XDMs or whatever else they might want to between components 
as long as these data structures represent well-formed XML documents. At 
the moment it sounds a bit as though XML documents can only be 
represented as character streams.


4. Section 2.3 (Parameters), only para, 3rd sentence:

   "If a document or other node is given as the value of a parameter, the
    string value of the specified node will be used."

I think we also want numbers/booleans and other data types to be 
automatically cast to strings.


5. Section 3.2 (For-each):

I think it would be useful to mention that for-eaches can have multiple 
output ports.


6. Section 3.3 (Viewport):

Nice example!


7. Section 3.4 (Choose), 1st para, 1st sentence:

   "A choose component selects exactly one of a set of possible
    subpipelines based on the evaluation of an XPath expression."

   s/an XPath expression/XPath expressions/


8. Section 3.4 (Choose), 2nd para:

   "For example, a choose might test an input document and apply XML
    Schema validation if it is an XML Schema document, apply RELAX NG
    validation if it is a RELAX NG grammar, and perform no validation
    otherwise."

I think you probably mean:

   "For example, a choose might test an schema and apply XML Schema
    validation to an input document if the schema is an XML Schema
    document, apply RELAX NG validation if the schema is a RELAX NG
    grammar, and perform no validation otherwise."


9. Section 3.4 (Choose), 3rd para:

   "Each subpipeline is associated with a separate XPath expression that
    is evaluated in the context of the specified input document. The
    specified input document can be different for different XPath
    expressions."

would be clearer as:

   "Each subpipeline is associated with a separate XPath expression that
    is evaluated in the context of a document. The context document can
    be different for different XPath expressions."

(I don't *think* we want to call these 'input document's because that 
implies that the context document for the test must be an input to the 
pipeline, whereas it could be an output from a previous step.)


10. Section 3.4 (Choose)

There ought to be some mention in here of a 'default subpipeline' that 
gets evaluated if none of the XPath expressions evaluate to true (i.e. 
the 'otherwise' branch).


11. Section 3.5 (Try/Catch), 1st para:

   "A try component isolates a subpipeline that fails at runtime. If any
    component in the try subpipeline fails, then the subpipeline in the
    catch component is processed and the result of the try component is
    the result of the subpipline specified in the catch. If all the
    components in the try subpipline proceed to completion without
    signalling an error, then the result of the try component is the
    result of that subpipline and the catch subpipline is never
    processed."

This is a bit confusing because of the slippery distinction between the 
"try component" and the "try subpipeline", and the introduction of a 
"catch component". Perhaps it would help to call it a "trap component" 
which has a "try subpipeline" and a "catch subpipeline"? Something like:

   "A trap component isolates a subpipeline that fails at runtime. It has
    a try subpipeline and a catch subpipeline. The try subpipeline is
    evaluated, and if any component in the try subpipeline fails, then
    the catch subpipeline is evaluated and the result of the trap
    component is the result of the catch subpipline. If all the
    components in the try subpipline proceed to completion without
    signalling an error, then the result of the trap component is the
    result of the try subpipline and the catch subpipline is never
    processed."


12. Section 3.5 (Try/Catch), 4th para:

   s/assure/ensure/


13. Section 4.1 (p:pipeline-library Element):

This implies that you're going to define a <p:import-library> element. I 
think this should just be called <p:import>, since I think we agreed 
that it could import standalone pipelines as well as pipeline libraries.


14. Section 4.3 (p:declare-input) and Section 4.4 (p:declare-output)

Were we going to have a sequence="yes|no" on these?


15. Section 4.3 (p:declare-input) With a source attribute, last para, 
last sentence:

   "It is a static error if the specified port is not a source."

I don't think you've defined what "a source" is anywhere? Presumably it 
means "an output from a previous step, or an input to the subpipeline". 
You also might want to mention something about the syntax for specifying 
other input ports in the same subpipeline (is the 'stepname' required in 
these circumstances?).


16. Section 4.3 (p:declare-input) With a "here" document and
     Section 4.4 (p:declare-output) With a "here" document

"literal-content" could be taken as meaning a serialized XML document 
(e.g. in a CDATA section). Perhaps calling it "embedded-document" or 
something similar would help.


17. Section 4.3 (p:declare-input)

You haven't mentioned the select attribute for filtering. Perhaps you're 
not including it in this version of the WD.


18. Section 4.4 (p:declare-output) With a source attribute, last-1 para, 
last sentence:

   "It is a static error if the specified port is not a sink."

I don't think you mean "a sink" here (not that you've defined what "a 
sink" means anyway). The port specified in an output declaration must be 
either an output from a contained step or an input to the subpipeline 
(i.e. what you called "a source" when you talked about p:declare-input). 
Port specifications never reference sinks.


A last general comment: I can understand why you've separated the 
language constructs from the syntax for those language constructs, but I 
think it would be easier to understand what's intended if they weren't 
separated. In my view, the syntax specifications (and examples) help to 
explain the abstract notions. If you were thinking of reorganising 
anyway, take this as a nudge to do so.

Cheers,

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

Received on Friday, 18 August 2006 14:32:50 UTC