- From: Nilo Mitra (EUS) <Nilo.Mitra@am1.ericsson.se>
- Date: Mon, 24 Feb 2003 15:35:09 -0600
- To: "'xmlp-comments@w3.org'" <xmlp-comments@w3.org>
- Cc: "'lesch@w3.org'" <lesch@w3.org>
Susan: Thank you very much for your detailed comments on the SOAP 1.2 Part 0: Primer [1]. As editor, I was assigned to handle your editorial comments, which was assigned as CR Issue #405. I have handled the vast majority of them fully, and show the detailed disposition of comments below. This issue is now closed, and further editing, if felt necessary, will be done at a future date. Thank you, Nilo > From: Susan Lesch <&References="lesch@w3.org > <mailto:lesch@w3.org?Subject=Re:%20Comments%20for%20CR-soap12- > part0-20021219&In-Reply-To=<p05111b04ba5979233859@[192.168.123.158]>> > Subject: Comments for CR-soap12-part0-20021219 > > > 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. > Decided to handle it as three parts. Please see thread elsewhere. > Decide whether to capitalize primer (Primer) or not and use that > throughout. > Decided to use lower case 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 > <http://www.w3.org/2001/06/manual/> > Not done in all cases, as the continuous parenthetical textual linkages would interrupt the flow of the text, and make many paragraphs unreadable. > Words in the TOC and headings can be capitalized, for example, 2.2.2 > Remote Procedure Calls and 4. Using Various Protocol Bindings. > Done, except for "And" > 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://www.w3.org/2001/06/manual/> > <http://lists.w3.org/Archives/Public/www-international/2000Apr > Jun/0058> > Done. > There are 151 occurrences of style="color: #000000" that need to be > cut. > Not done. I don't know how these got in. I use Amaya which inserts these without asking. > In several places, style="color: #000000" turns links from blue to > black, for example: > <a href="#L10309" style="color: #000000">section 4.1</a> > Corrected. > There are 13 empty <span>s and one empty <code> that can be cut. > Not done. I don't know how these got inserted. But I haven't searched for these. > The tables need summary attributes. > Done. > W3C uses en-US. You could replace the whilsts (chiefly British) with > whiles. > <http://www.m-w.com/cgi-bin/dictionary?va=whilst> > Done. > 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> > Not done. decided to let people pronounce as they please. > "The document is believed to be stable, and to encourage > implementation > by the developer community." needs re-writing to be a > complete sentence. > Corrected, but likely to change as this is part of a boilerplate that I did not insert. > 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é de France])/ > s/Hewlett Packard/Hewlett-Packard/ > s/Developmentor/DevelopMentor/ > Done. > 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/#enca > psulation <http://www.w3.org/TR/2002/CR-soap12-part1-20021219/>"> > header blocks</a> > (same for "which is a role", "the ultimate SOAP receiver", "variety of > message exchange patterns", "sub-element, env:Node") > Couldn't find these. I'll recheck later. > 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. > Done. > In "freestanding [XML 1.0]" the reference link is missing. > Done. > 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. > Done, following your second suggestion suggestion with a slight alteration. > 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. > Done, following a hybrid of your suggestions and the original. > Reference titles should point to the dated version. See: > > http://www.w3.org/2001/06/manual/#References <http://www.w3.org/2001/06/manual/> > "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/>." Done. >In References and throughout, you have "[SOAP Part1]" yet "[XML Schema >Part 1]". I would make the spacing match. Same for part 2. Done. >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> Done. [1] <http://www.w3.org/TR/2002/CR-soap12-part0-20021219/>
Received on Monday, 24 February 2003 16:35:16 UTC