SOAP 1.2 Pt. 2 feedback - wording (semantic and editorial)

Some feedback regarding SOAP Version 1.2 Part 2:


Wording related to semantics:


* Section 3.1.6 doesn't say in which order array dimension sizes are listed.
   (It doesn't say whether the first size in the list is the size of the first
   dimension or is the size of the last dimension.)

* Section 3.1.6 uses its own definition of whitespace.  Should it refer to
   the XML specification's definition, so that if the XML specification's
   definition is modified in some future version (for example to include
   the EBCDIC newline character), future versions of the SOAP spec (which
   would refer to XML x.x instead of XML 1.0) will automatically follow XML
   evolution?

* Section 3.1.6 doesn't define that sequences of digit characters allowed
   by the syntax are to be interpreted as regular decimal representations
   of integers.

* "A relative URI whose base URI is ..."

   Is that wording technically correct?

   Does a relative URI really have a base URI, or is it the occurrence of
   a relative URI that has a base URI?

   (The relative URI "x" doesn't have a base URI.  If I put it (a copy of
   it?) in an HTML document and viewed the document, then the occurrence in
   the document would have a base URI (the URI from which I retrieved the
   document).)

   RFC 2396 refers to the base URI of a document and defines the base URI
   for resolution, but doesn't seem to mention a base URI of a URI reference.

   Should "A relative URI whose base URI is..." be "A relative URI that will
   be resolved against..."?

   Also, must it be relative, or is it just allowed to be relative?



Just editorial:


* The wording "invocations of method and procedure calls" is confusingly
   inaccurate.  (A call _is_ an invocation.  You can invoke a procedure;
   you can't invoke a procedure _call_ (well, unless you're talking about
   "invoking" (executing) a procedure call statement that sets up for and
   then actually invokes a procedure).)


* "is entirely platform independent" should be "is entirely
    platform-independent "


* As written, the wording:

     When mapping to or from a programming language method or procedure
     call, the name of which identifies...

   refers to the (non-existent) name of a _call_, instead of to the called
   method or procedure.


* "on an application or procedure-specific basis" should be
   "on an application- or procedure-specific basis"

* "the binding specific expression" should be "the binding-specific
    expression"

* "application defined data" should be "application-defined data"

* "the application defined name" should be "the application-defined name"


* "i.e. ..." should be "i.e., ..." (several instances)


* Delimiting special terms with brackets (e.g., "A [local name] of ref")
   is confusing (because it is not standard English use of brackets).


* "The struct is named identically to the procedure or method name":

   Either:

     "The struct name is identical to the procedure or method name."

   or:

     "The struct is named identically to the procedure or method."


* "are implementation defined" should be "are implementation-defined"


* "the distinction between per message-exchange and more widely scoped
   properties":

   - "per message-exchange [properties]" should be "per-message-exchange
     [properties]"

   - "the distinction between per-message-exchange properties and more
     widely scoped properties"  would be clearer


* "containers called Message Exchange Context..."

   Shouldn't that be "containers called the Message Exchange Context..."?


* In Figure 1, at least three labels don't match the terms in the
   immediately preceding text:
   - "SOAP" (instead of "SOAP node")
   - "Environment" (instead of Environment Context)
   - "Transport Message Exchange Context" (instead of "Message Exchange
     Context")

* It looks like "Environment" was intended to be renamed to "environment
   context" but not all references were edited.  For example, section
   5.1.2.2 says:

      The environment context is...

      The values...in Environment...

   and section 5.1.2 says:

      called...Environment Context.

   The intended form should be determined and all references should be
   edited to follow that indented form.


* Table 4 is extremely wide (and can be hard to read and print).  It
   would be helpfule if optional line breaks were be inserted in the
   long URIs in that table (and in other tables).


* "SOAP places no restrictions on the specificity of the URI or that it
   is resolvable."

   Something didn't get edited consistently.


* "The media type of the request entity body (if present) otherwise,
   omitted..."

   apparently should be:

     The media type of the request entity body, if present; otherwise,
     none...


* "The response message follows in HTTP response..." should be
   "The response message follows in the HTTP response..."


* "it is recommended that such behavior is disabled" should be
   "it is recommended that such behavior be disabled"

* "...it is strongly RECOMMENDED that...implications...is fully understood"
   should be:

      ...it is strongly RECOMMENDED that...implications...be fully understood


* "the schema recommendation is build on..." should be "the schema
   recommendation is built on..."


* The SOAP encoding schema linked to from the main document says:

   Schema defined in the SOAP Version 1.2 Part 2 specification Proposed
     Recommendation:
      http://www.w3.org/TR/2003/PR-soap12-part2-20030507/


* The main document _contain_ a copy of the SOAP Encoding Schema in the
   text.  Doing so would make the HTML document more self-contained.



Daniel Barclay

Received on Tuesday, 9 September 2003 17:29:13 UTC