Re: Draft Review

/ Alex Milowski <alex@milowski.org> was heard to say:
| Section 1, Introduction :
|
|    * Second paragraph: The last parenthetical remark should just
|      be made into a sentence.

Done.

|    * Can't read the smallest text on Figure 2.

I'll work on that.

| Section 2, Pipeline Concepts :
|    * I'm not sure we want to use the term "subpipeline" for a
|      contected set of steps.  Having subpipeline label this concept
|      means we'll have a conflict for running pipelines as steps--which
|      is truly a sub-pipeline.

Uhm. Yeah. I'm not sure what to do about that just now. Perhaps as the
terminology for steps/step containers/stages/etc. coalesces it'll
become possible to remove this term.

| Section 2.1, Components :
|    * Last paragraph: In the definition of matching the component
|      signature there is the state "it specifies inputs that are not
|      declared".  In the case of the document aggregation component,
|      all the inputs are not explicitly declared because there can
|      be any number of inputs.  As such, this definition will needs
|      some work in conjunction with component declarations.

The signature is "the set of inputs, outputs, and parameters that it
is declared to accept." In the case of components like aggregate, I
intended the open-ended nature of the declaration (declare-input "*")
to cover the case you point out.

| Section 2.2:
|    * there is no mention of the error output

Fixed.

| Section 2.4: Component Graph
|    * I don't think "Component Graph" is the right term here as
|      Components don't describe their interconnections.  "Step graph"
|      would be more correct given our current terminology but that
|      sounds strange.  Maybe we could use the term "Flow Graph" ?

I'll give flow graph a try.

|    * The definition of connected needs some work because we don't
|      talk about paths and that's the standard definition from
|      graph theory.  If we want to avoid graph theory, maybe:
|
|      "Components A and B are connected if they are either
|       directly or indirectly connected.  A component A is directly
|       connected to B if an output of A is associated with an input
|       port of B.  Component A is indirectly connected to B if there
|       is a chain of directly connected components that allows
|       traversal from A to B."

Ok.

|       While I could see the potential use of term "indirectly
|       connected", I don't see that we need it right now.  I'm OK
|       with it remaining--deleting it is easy later!

The definitions of before and after appeal to indirectly
connectedness. And the acyclic requirement appeals to before and
after.

| Section 3.3 Viewport
|
|    The example needs to be better.

What's wrong with it?

| Section 4.1.3 Syntactic Shortcuts
|
|    * The use of the term "user-defined components" seems out-of-place
|      here.  I don't think of 'choose' as user-defined.

Indeed. "Step container" is what I meant :-)

|    * Per our non-decision today, the use of 'declare-input' in the
|      choose is now not valid.

Right. I added an ednote about that.

|    * The use of 'delcare-parameter' seems like it should be just a
|      'parameter' element.

No, I don't think so.

|    * s/param/parameter/g

Uh, well, I did s/parameter/param/g :-)

| Section 4.2.1:
|
|    * The statement that the name must be unique make no sense when
|      you aren't in the context of a pipeline library.  Maybe that
|      should be moved to the pipeline library section.

I assume that a pipeline outside of a pipeline library cannot shadow
the name of a pipeline within such a library, so I think it applies in
both cases.

|    * Maybe we should just replace all instances of 'declare-parameter'
|      with 'parameter' since at the pipeline level it can work the same
|      as in steps.  That is, where the parameter is calculated by a
|      select on an input of the pipeline.  Then 'declare-parameter' is
|      only in component declarations.

As long as we have the input/declare-input distinction, I think we should
preserve the analagous param/declare-param distinction.

| Section 4.2.2:
|    * Shouldn't declare-input allow an 'href' attribute?  I can see
|      that being very useful where you know there is a static document
|      in the environment and you'd like to specify the binding in the
|      pipeline document rather than outside.

Fixed.

| Section 4.2.3:
|    * I think declare-output should support here documents.

Fixed.

| Section 4.2.6:
|    * s/param/parameter/g
|    * input over which the select is running is missing.

Fixed.

|    * I'd like to have a 'value' attribute for literal values.

Added.

| Section 4.2.7
|    * s/param/parameter/g
|    * I think the attribute should be named 'names' since it is a list.

It's not a list, it's a single QName, or *:NCName or NCName:*

| Section 4.2.8, 4.2.9 and 4.2.11
|    * here we have 'declare-input' but 'choose' doesn't.
|    * 'declare-parameter' (or 'parameter') is missing.

I'll make them consistent.

| Section 4.2.10:
|    * I think the 'choose', 'when', and 'otherwise' should all start
|      with the same content model:
|
|      (p:declare-input*,p:decalre-output*,p:declare-parameter, ...)

I'll make them consistent.

| Section 4.2.13:
|    * Can a component definition have both named input ports and
|      a wild card?  This might be helpful for certain kind of
|      aggregation or packaging components that take arbitrary
|      inputs and organized them given a "template" on a named
|      port.  This seems technically OK to me.

I think so.

| Section 4.2.14:
|    * pipeline libraries should have an optional name for error
|      reporting.

Uhm, isn't it sufficient to identify the file?

                                        Be seeing you,
                                          norm

-- 
Norman Walsh
XML Standards Architect
Sun Microsystems, Inc.