WSDL 2.0 part 2 comment - 2.3.x, 2.2.x wording problems

Regarding the WSDL 2.0 part 2 CR document currently at
http://www.w3.org/TR/wsdl20-adjuncts:


* The sections on the message exchange patterns (2.3.1, 2.3.2, ..., 2.3.8)
   have a small wording problem.  They all begin with:

     This pattern consists of ...

   instead of something such as:

     The in-out pattern consists of ...

   (or

     The In-Out message exchange pattern consists of ...

   or whatever).

   Specifically, the main text does not stand on its own (independent of
   the headings) as it should.  Headings are not part of the text (not
   supposed to be required to be read to understand the text); they are
   just guides for finding or skipping portions of the text.

   (For example, notice how, say, section 4.1.2, XML Representation of the
   wrpc:signature Extension, starts off:

     The XML representation for the RPC signature extension is an
     attribute information item with ...

   instead of beginning:

     This is an attribute information item with ...

   Also, see any professionally edited book.)


   (Additionally, notice that with the current wording, nothing in the text
   or header clearly indicates what the patterns' names are.  For example,
   neither the text nor the header says of section 2.3.1 ever says "the
   In-Only MEP."

   The header text "In-Out" does indicate that "In-Out" has something to
   do with the following text, and even the pattern described in it, but
   doesn't make clear that is the name of the pattern.)


* More seriously, section 2.2.3 has a similar problem that does strongly
   affect the semantics of the text.  The section begins:

     Faults MUST NOT be propagated.

   Note how that current wording clearly says that faults must not be
   propagated, period (full stop).  (There is no mention that that applies
   only for a/the No Faults rule, as apparently intended.)

   The text should probably begin somewhat like this:

     Under the No Faults fault propagation rule, faults MUST NOT be
     propagated.

* Sections 2.2.1 and 2.2.2 have similar definitional problems.


* Presumably, the document is likely to have the same types of errors in
   other places, so it should be reviewed and corrected as necessary.


Daniel Barclay

Received on Thursday, 15 June 2006 19:27:35 UTC