Re: Comments on August 10 editors' draft through section 2.6

/ ht@inf.ed.ac.uk (Henry S. Thompson) was heard to say:
[...]
| 2.1 Steps:
|
|  Should we make
|
|   "The steps that occur directly inside a compound step are called
|    contained steps."
|
|  more accurate, e.g. by saying
|
|   "The steps that occur as children or, in the case of *p:choose* and
|    *p:try*, as grandchildren, of a compound step are called contained
|    steps."

On further reflection, I don't think I want to call the grandchildren
of a p:choose it's contained steps. I think a p:choose contains p:when
and p:otherwise steps and each of those has its own contained step.

| 2.1.1 Step names:
|
|  In the discussion of the example, both p:choose and p:when are given
|  names, so one concludes they are steps.  But in the production for
|  subpipeline above, only p:choose appears.  I think we need to say
|  something explicit, sooner rather than later, about the slightly
|  anomalous state of p:when, p:otherwise and p:catch, perhaps along the
|  lines of:
|
|    p:when, p:otherwise and p:catch have a special status.  Although
|    they behave in many ways as compound steps, in that they wrap a
|    subpipeline and may specify inputs and outputs, they are not
|    independent.  They *must* only appear immediately within p:choose
|    (p:when and p:otherwise) or p:try (p:catch).
|
|    On the other hand p:choose and p:try are special too, in that they
|    *must not* contain other steps directly, but only indirectly.
|
|  which might go somewhere near the end of 2.1.

I added the following near the end of 2.1:

<para>This simple distinction between atomic and compound steps is
occasionally stretched. The immediate children of some compound steps,
e.g. <tag>p:choose</tag> and <tag>p:try</tag>, are special. In the
case of <tag>p:choose</tag>, the <tag>p:when</tag> and
<tag>p:otherwise</tag> elements serve as wrappers around different
pipelines at most one of which will be processed. In the case of
<tag>p:try</tag>, the <tag>p:catch</tag> element is a wrapper around a
subpipeline that will only be processed if the initial
<tag>p:group</tag> fails. Acknowledging this slight irregularity, we
nevertheless treat all compound steps as if they directly contained
one or more subpipelines.</para>

| 2.2 Inputs and Outputs:
|
|  The list of allowed sources for input bindings needs something added
|  along the lines of
|
|    * A special port provided by an ancestor compound step,
|      e.g. 'current' for p:for-each and p:viewport

Ok.

|  Similarly, the second bullet of allowed destinations for outputs
|  should read somethign like:
|
|    * One of the outputs declared on the top-level p:pipeline step, or
|      on its container.

Actually, I think it's sufficient to say simply "on its container".
The p:pipeline can't connect one of its outputs to one of its
grandchildren.

|  Note the asymmetry between the above two changes -- is it correct?

I changed bullet four of the "input" list to simply:

<para>One of the inputs declared on one of its ancestors.</para>

It turns out that the only compound step on which we provide p:inputs
is p:pipeline, so it amounts to the same thing but reads more
symetrically.

| 2.3 Primary Inputs and Outputs:
|
|  I'm not happy that the definitions of primary i/o are contractdicted
|  by the prose which immediately follows.  I suggest they be rewritten
|  along the following lines:

I like your proposed text, but I don't see any contradiction in what
follows. Clue, please?

|   Definition: If a step has a document input port which is explicitly
|   marked "primary='yes'", or if it has exactly one document input
|   port, and that port is _not_ explicitly marked "primary='no'", then
|   that input port is the primary input port of the step.] If a step
|   has a single input port and that port is explicitly designated as
|   not being the primary input port, or if a step has more than one
|   input port and none is explicitly designated the primary, then the
|   primary input port of that step is undefined.
|
|   It is an error (xxx) for a step to explicitly designate more than
|   one document input port as primary.
|
|  and similarly for output ports.
|
|  ------
|
|  The following can't be right:
|
|   "Additionally, if a compound step has no declared inputs and the
|    first step in its subpipeline has an unbound primary input, then an
|    implicit primary input port (named \u201csource\u201d) will be added
|    to the compound step."
|
| Compound steps other than p:pipeline _can't have_ declared inputs.
| The passing of the _default readable port_ down is handled by the
| general rule in 2.7, modified if necessary by the individual compound
| steps.
|
| I think this was drafted in false parallel to the subsequent para, and
| should be changed to _only_ apply to p:pipeline, as follows:

Indeed.

|   "Additionally, if a p:pipeline step has no declared inputs and the
|    first step in its subpipeline has an unbound primary input, then an
|    implicit primary input port (named \u201csource\u201d) will be
|    added to the p:pipeline (and consequently bound to the first step's
|    primary input port)."
|
| A similar parenthesis could be added to the parallel sentence for
| outputs:
|
|   "If a compound step has no declared outputs and the last step in
|    its subpipeline has an unbound primary output, then an implicit
|    primary output port (named \u201cresult\u201d) will be added to the
|    compound step (and consequently the last step's primary output will
|    be bound to it)."

Ok.

| ------
|
|  Overall, I am a bit worried about the bulleted lists here, as they
|  are not all exactly right -- perhaps at the end of the section we
|  could add something such as

Where is "here"?

|    The above lists of possible port-to-port connections are only
|    summaries---the exact details are given below in sections 2.7 and
|    5.11.
|
| 2.5 Parameters:
|
|  A parallel change to the one suggested above should be made to the
|  definition of primary parameter input port.

Ok.

| ------
|
|  availble -> available

Got it.

| [C.2 Fragment Identifiers:
|
|   Excellent!]

:-)

| I'm going to ship this and pick up with section 2.7 in a subsequent
| message.

Please do!

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | All things are contingent. And there is
http://nwalsh.com/            | chaos.--Spalding Gray