Re: Arch Doc: 18 September 2003 Editor's Draft

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Editorial comments through section 2. Technical comments to follow in
a separate message.

- - The "List of Principles and Good Practice notes" would be better presented
  as three lists, I think. (Also, I think "Notes" should be capitalized in
  the title.)

- - Section 1, first paragraph:

  s/resources, related/resource, are related/

- - I think the idea of an icon for the trip story is a good idea, but
  I'd prefer a smaller, simpler icon.

- - In the paragraph where the icon first occurs:

  s/she can expect /she expects/
  s/should allow here/allows her/

- - In bullet "1" below that paragraph:

  The sentence "The information is provided by those responsible for
  'weather.example.com" seems out of place. Perhaps make it bullet 3?

- - In bullet "2":

  s/a new retrieval request action/new retrieval request actions/

- - In bullet "2. Interaction" of the next list:

  In the penultimate sentence, suggest delete the word "authority"

  Is the last sentence trying to state a fact "in our scenario, Nadia's
  browser talks directly to the origin server and does not use a cache
  or a proxy" or is it just telling the reader what Nadia's browser does.
  I think the latter is intended, and suggest moving that sentence immediately
  before the sentence that begins "The browser uses its configuration..."

- - In bullet "3. Representation":

  s/of resource state./of a resource. A resource communicates everything
  about its state through the representations it makes available/

- - Section 1.1 seems out of place. I think we've talked about this before, but
  it has to go earlier in the document. Maybe in the status section?
  Stumbling over "Audience of this Document" after reading about the three
  architectural divisions of webarch and the whole scenario explanation is
  very strange.

- - Section 2, first para:

  s/something will agree/something agree/

- - Section 2, third para (right before the "Use URIs" principle)

  s/It follows that any resource/it follows that every resource/
  s/, or annotate it./, annotate it, or perform any other operations on it./

- - Section 2.1, first para:

  s/is to compare the URIs/is to compare, as character strings, the URIs/
  s/, as character strings././
  s/, determination of/,/
  s/is based on/is determined by/

- - Section 2.1, second para after the "URI characters" good practice:

  s/inspection of two URIs/alone/
  s/they identify/two URIs that are not equivalent identify/

  Say "false negatives or positives" or "false positives or negatives" consistently.

- - Section 2.1, next para:

  s/licensed by relevant/licensed by the relevant/

- - Section 2.1, second para after the book icon:

  s/have no reason to/should not/

- - Section 2.3, second bullet of the second bulleted list:

  s/ldap.itc.umich.edu/ldap.example.org/

- - Section 2.3, first para below second list:

  s/of mapping between/of mappings between/
  s/process for registration of/process for registering a/

- - Section 2.3, next para:

  s/cost of introduction of new URI schemes/cost of introducing a new URI scheme/

- - Section 2.3, in the "New URI schemes" good practice

  s/existing scheme specifies/existing scheme provides/

- - Section 2.3, next para and the para that follows it:

  s/a agent/an agent/

- - Section 2.4.1 title:

  s/through Fragment Identifier/With A Fragment Identifier/

- - Section 2.4.1, globally:

  s/fragment identifier agent/fragment identifier/

- - Section 2.4.1, first para:

  s/additional identifying information/additional information/

- - Section 2.4.1, third bullet of first bulleted list:

  s/instance of "F"/instances of "F"/

- - Section 2.4.1, fourth bullet of first bulleted list:

  s/is "U#fragid"./is "U#fragid" when the resource retreived is in format "F"./

- - Section 2.4.1, first para following first bulleted list:

  Append "Fragment identifier semantics may differ among format specifications."
  Remove this sentence from the beginning of the last para in this section.

- - Section 2.4.1, second para following first bulleted list:

  s/that do specify/that specify/

- - Section 2.4.2, first and second paras:

  Suggest rewording:

    Suppose that the authority responsible for "weather.example.com"
    provides a visual map of the meteorological conditions in Oaxaca
    as part of the representation served for
    "http://weather.example.com/oaxaca". They might encode the same
    visual map in a number of image formats to meet different needs
    (e.g., they might serve PNG, SVG, and JPEG/JFIF). Nadia's browser
    and the server engage in HTTP content negotiation, so that Nadia
    receives the best image format her browser can handle or the image
    format she usually prefers.

    Suppose that the URI
    "http://weather.example.com/oaxaca/map#zicatela" refers to a
    portion of the weather map that shows the Zicatela Beach, where
    Nadia intends to go surfing.

    Clients can do something useful with the fragment identifier and
    the SVG representation because SVG defines fragment identifier
    semantics. On the other hand, clients cannot do anything useful
    with the fragment identifier and the PNG or JPEG/JFIF
    representations because their specifications do not specify
    fragment identifier semantics.

    Errors can occur when the authority responsible for a resource
    publishes a URI with a fragment identifier and representations of
    the resource do not have consistent fragment identifier semantics.
    Thus, the authority responsible for
    "http://weather.example.com/oaxaca/map#zicatela" introduces the possibility
    of error by making available PNG and JPEG/JFIF representations available
    where a fragment identifier may be present.

- - Section 2.5, last para before 2.5.1:

  Add "See related" to the beginning of the para.

- - Section 2.5.1, first para after "Available representations" good practice:

  s/budapest/oaxaca/  (There's no value in introducing a new location here.)

- - Section 2.5.1, bullet 2 of first numbered list:

  s/specification state that/specification and states that/

- - Section 2.5.1, last para before 2.5.2:

  Append "or any other format for that URI" to the para.

- - Section 2.5.2, first para:

  s/state of the resource; the user/state of the resource and the user/

- - Section 2.5.2, first para after "Safe retrieval" principle:

  s/oxaca/oaxaca/

  Delete "Remember that search engines may follow such links."

- - Section 2.6, second para *before* "URI ambiguity" good practice:

  s/persistent, nor that/persistent or that/

- - Section 2.6, second para after "URI ambiguity" good practice:

  s/Ambiguity, an error,/Ambiguity is an error and/

- - Section 2.6, penultimate para:

  s/manager would not be required/manager is not required/

  Delete the final clause ",as would be the case with protocols..."
  and make it a new sentence somehow.

- - Section 2.8.4

  Can we include a pointer to this work?

                                        Be seeing you,
                                          norm

- -- 
Norman.Walsh@Sun.COM    | During the first period of a man's life the
XML Standards Architect | greatest danger is: .--Kierkegaard
Web Tech. and Standards |
Sun Microsystems, Inc.  | 
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.3 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.8 <http://mailcrypt.sourceforge.net/>

iD8DBQE/a3BqOyltUcwYWjsRAvgVAKCsVuckq3s4mXYjsjGH6ETZSL8jQwCfc8Xp
ogU6DFXFrZeupyB1oSiNY58=
=xaIZ
-----END PGP SIGNATURE-----

Received on Friday, 19 September 2003 17:13:34 UTC