- From: Mark Nottingham <mark.nottingham@bea.com>
- Date: Fri, 28 Nov 2003 17:10:17 -0800
- To: "Xml-Dist-App@W3. Org" <xml-dist-app@w3.org>
> 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.) PROPOSAL: State that the sizes are listed in order, from first to last. > * 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? PROPOSAL: change whitespace definition to "<as defined by XML>" > * 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. PROPOSAL: No change. Rationale: By default, all digits are to be interpreted in this fashion. This is accepted practice in W3C specifications. > * "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? PROPOSAL: adopt suggested text. (table 4) > 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).) PROPOSAL: change "invocations of method and procedure calls" (section 4 Intro) to "invocations of methods and procedures." > * 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. PROPOSAL: change "language method or procedure call" (4.1.1) to "language 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" > > * "is entirely platform independent" should be "is entirely > platform-independent " > > * "are implementation defined" should be "are implementation-defined" PROPOSAL: Adopt the suggested text. Rationale: When a compound phrase is used as an adverb, it should be hyphenated. > * "i.e. ..." should be "i.e., ..." (several instances) PROPOSAL: No change. Rationale: This is a matter of style; either form is acceptable, as long as it is used consistently. > * Delimiting special terms with brackets (e.g., "A [local name] of > ref") > is confusing (because it is not standard English use of brackets). PROPOSAL: No change. Rationale: This is well-recognised notation in W3C specifications. > * "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." PROPOSAL: Adopt the second suggestion. (4.2.1) > * "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 PROPOSAL: Adopt the second suggestion. (5.1.2) > * "containers called Message Exchange Context..." > > Shouldn't that be "containers called the Message Exchange > Context..."? PROPOSAL: No change. Rationale: This doesn't add any clarity to the text. > * 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") PROPOSAL: Update the illustration. (5.1.2) > * 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. PROPOSAL: normalise on "Environment Context." > * 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). PROPOSAL: No change. > * "SOAP places no restrictions on the specificity of the URI or that it > is resolvable." > > Something didn't get edited consistently. PROPOSAL: "SOAP places no restrictions on the specificity of the URI, and does not guarantee that it is resolvable." > * "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... PROPOSAL: Adopt the suggested text. (Table 16) > * "The response message follows in HTTP response..." should be > "The response message follows in the HTTP response..." PROPOSAL: Adopt the suggested text. (Table 17) > * "it is recommended that such behavior is disabled" should be > "it is recommended that such behavior be disabled" PROPOSAL: Adopt the suggested text. (7.5.1.2) > * "...it is strongly RECOMMENDED that...implications...is fully > understood" > should be: > > ...it is strongly RECOMMENDED that...implications...be fully > understood PROPOSAL: Adopt the suggested text. (A.2) > * "the schema recommendation is build on..." should be "the schema > recommendation is built on..." PROPOSAL: Adopt the suggested text. (C.1) Also, should be "Recommendation", not "recommendation", throughout. > * 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/ PROPOSAL: Update text and link to REC. (8.1, 8.2) > * The main document _contain_ a copy of the SOAP Encoding Schema in the > text. Doing so would make the HTML document more self-contained. PROPOSAL: No change. Rationale: XML Schemas are not intended to be human-readable (Gudge notwithstanding). -- Mark Nottingham Principal Technologist Office of the CTO BEA Systems
Received on Friday, 28 November 2003 20:10:58 UTC