W3C home > Mailing lists > Public > xmlp-comments@w3.org > January 2003

Comments for CR-soap12-part0-20021219

From: Susan Lesch <lesch@w3.org>
Date: Sun, 26 Jan 2003 04:10:44 -0800
Message-Id: <p05111b04ba5979233859@[192.168.123.158]>
To: xmlp-comments@w3.org

Hello,

Here are editorial comments for your "SOAP Version 1.2 Part 0: Primer"
Candidate Recommendation [1].

Decide whether SOAP 1.2 is one or three specs. If a "Part" could
ever conceivably be updated without the others, I'd say it's three.
XML Schema was treated as one spec though it has three parts. Then
SOAP 1.2 "specification(s)" should match throughout the primer.

Decide whether to capitalize primer (Primer) or not and use that
throughout.

This page shows how to link to Parts 1 and 2 from within Part 0.
People reading from printouts need to know part and section numbers.

http://www.w3.org/2001/06/manual/#linking-within

Words in the TOC and headings can be capitalized, for example, 2.2.2
Remote Procedure Calls and 4. Using Various Protocol Bindings.

Reword to avoid "we" (even if that means using the passive voice). For
example, s/In section 2.2.1 we return to our example/Section 2.2.1
returns to the example/

http://www.w3.org/2001/06/manual/#Translations
http://lists.w3.org/Archives/Public/www-international/2000AprJun/0058

There are 151 occurrences of style="color: #000000" that need to be
cut.

In several places, style="color: #000000" turns links from blue to
black, for example:
     <a href="#L10309" style="color: #000000">section 4.1</a>

There are 13 empty <span>s and one empty <code> that can be cut.

The tables need summary attributes.

W3C uses en-US. You could replace the whilsts (chiefly British) with
whiles.
http://www.m-w.com/cgi-bin/dictionary?va=whilst

Also you could, in the first occurrence, do something like "primer
(pronounced <em>prim</em>-er)" as an aid to the reader. prime-er is
chiefly British.

http://www.m-w.com/cgi-bin/dictionary?va=primer
http://www.bartleby.com/61/wavs/87/P0558700.wav

"The document is believed to be stable, and to encourage implementation
by the developer community." needs re-writing to be a complete sentence.

Some of the following need global replacement, some are single occurrences.

s/simplicitly/simplicity/
s/behaviour/behavior/
s/Recommandation/Recommendation/
s/accomodate/accommodate/
s/[XML InfoSet]/[XML Infoset]/
s/realise/realize/
s/W3C members/W3C Members/
s/the following criterion/the following criteria/
s/Implementation experience have been gathered/Implementation 
experience has been gathered/
s/W3C membership/W3C Membership/
s/progress."A/progress." A/
s/corresponding XML Infosets/corresponding XML infosets/ (I think, not sure)
s/SOAP Part 2 Tabe 16/SOAP Part 2 Table 16/
s/NOT recommended/<strong>not</strong> recommended/
s/Web Architecture/Web architecture/
s/et al/et al./
s/Usage Scenarios WD/SOAP Version 1.2 Usage Scenarios Working Draft/
s/Members of the Working Group/Participants in the Working Group/
s/Tibco/TIBCO/
s/Mitre/MITRE/
s/Previous members/Previous participants/
s/(EDF (Electricite de France))/(EDF [Electricit&eacute; de France])/
s/Hewlett Packard/Hewlett-Packard/
s/Developmentor/DevelopMentor/

I saw about 6 links that contain their preceding space. For example,
this needs a space after "called":
     called<a
     href="http://www.w3.org/TR/2002/CR-soap12-part1-20021219/#encapsulation">
     header blocks</a>
(same for "which is a role", "the ultimate SOAP receiver", "variety of
message exchange patterns", "sub-element, env:Node")

The second occurrence of Interface Definition Language should be
capitalized. Either that or establish (IDL) after the first occurrence
and use that in the second.

In "freestanding [XML 1.0]" the reference link is missing.

This sentence is too long:

     Furthermore, in the case when an RPC definition is such that all
     parts of its method description can be described as
     resource-identifying and hence the entire resource may be
     identified by a URI, and the supplier of the resource can assure
     that a retrieval request is safe, then SOAP Version 1.2 recommends
     that the choice of the Web method property of GET and the use of
     the SOAP Response message exchange pattern used as described in
     section 4.1.1.

It could be two, something like:

     When all parts of an RPC definition method description can be
     described as resource-identifying, the entire resource may be
     identified by a URI. In this case, if the supplier of the resource
     can assure that a retrieval request is safe, then SOAP Version 1.2
     recommends the Web method property of GET and the SOAP Response
     message exchange pattern used as described in section 4.1.1.

This paragraph confused me:

     SOAP Version 1.2 has a number of changes in syntax and provides
     additional (or clarified) semantics from those described in [SOAP
     1.1]. The following is a list of features where the two
     specifications differ. The purpose of this list is to provide the
     reader with a quick and easily accessible summary of the
     differences between the two specifications. The following list has
     been put in categories purely for ease of reference, and in some
     cases, an item might equally well have been placed in one or
     another category.

It could be shorter, something like:

     SOAP Version 1.2 has a number of changes in syntax and provides
     additional and clarified semantics from those in [SOAP 1.1]. The
     following is a summary of features where the two specifications
     differ. The categories are purely for ease of reference. In some
     cases, an item might equally well have been placed in another
     category.

Reference titles should point to the dated version. See:

http://www.w3.org/2001/06/manual/#References

    "If there is an institutionalized identifier (URI) for a document,
     cite the most specific identifier. For example, link to
     http://www.w3.org/TR/1999/REC-html401-19991224 rather than to
     http://www.w3.org/TR/html4/."

In References and throughout, you have "[SOAP Part1]" yet "[XML Schema
Part 1]". I would make the spacing match. Same for part 2.

Also in References, for [SMTP] you can link to those RFCs and treat
them like the other references. I think IETF recommends URIs like this:

http://www.rfc-editor.org/rfc/rfcNNNN.txt

[1] http://www.w3.org/TR/2002/CR-soap12-part0-20021219/

Best wishes for your project,
-- 
Susan Lesch           http://www.w3.org/People/Lesch/
mailto:lesch@w3.org               tel:+1.858.483.4819
World Wide Web Consortium (W3C)    http://www.w3.org/
Received on Sunday, 26 January 2003 07:11:10 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 27 October 2009 08:42:28 GMT