Subject: p2: Purely editorial feedback

From: Mark Nottingham <[email-masked]>
Date: Sat, 20 Apr 2013 17:39:50 +1000

Strictly editorial feedback on the current p2:

* 1. Introduction doesn't read smoothly. I'm happy to make a proposal if necessary. 

* 2 "The target of each HTTP request"   s/each/a/

* 3.1 "The following header fields are defined to convey representation metadata:"  This reads as if it's a closed set. Suggest removing "are defined to".

* 3.1.1 a more appropriate section title would be "Processing Representation Data" or "Processing Representation Metadata" (depending on intent)

* 3.1.2.1 "Frequently, the representation is stored in coded form, transmitted directly, and only decoded by the recipient."   Saying "final recipient" would be clearer.

* 3.1.4.1 "...by other means (not defined by HTTP)..." --> "...by other means (not defined by this document)..."  (two occurrences) 

* 3.4.1. "When content negotiation preferences are sent by the user agent in a request in order to encourage..."   The use of "in order" is slightly confusing here, esp. to a non-native speaker; we don't want to imply that they're ordered.  Suggest dropping "in order".

* 4.1 Last paragraph - "A client can send conditional request header fields..."   Suggest prefixing with "For example," and moving up to be after the first paragraph.

* 4.3.5 "action seems okay" is too informal.

* 4.3.7 "The OPTIONS method requests information about the communication options available on the request/response chain identified by the effective request URI."  This can be misread; suggest:

"The OPTIONS method requests information about the communications options available for the target resource, either at the origin server or an intervening intermediary."

* 5.3 should be a subsection of 3.4.1; there are already a number of headers defined in section 3, and it's better to have all of the conneg material together.

* 6.5.8 "...could not be completed due to a conflict with the current state of the resource." --> "... with the current state of the target resource."

Cheers,

--
Mark Nottingham   http://www.mnot.net/

---

From: Willy Tarreau <[email-masked]>
Date: Sat, 20 Apr 2013 10:01:14 +0200

> * 2 "The target of each HTTP request"   s/each/a/

Isn't it s/each/an/ instead ?

(I'm not a native speaker and that's how I learned it, but I can be corrected).

Willy

---

From: Mark Nottingham <[email-masked]>
Date: Sat, 20 Apr 2013 18:02:46 +1000

> (I'm not a native speaker and that's how I learned it, but I can be corrected).

It depends on whether you pronounce it "aigch" or "haigch." I personally don't care which we choose, as long as it's consistent.

Cheers,

---

From: Mark Nottingham <[email-masked]>
Date: Sat, 20 Apr 2013 18:25:48 +1000

Just a few more...

* 3.4 - "supplier of representations to the origin server" seems odd; shouldn't this just be "the resource"?

* 3.4 introduces "proactive" and "reactive" conneg, as a replacement for server-driven and agent-driven. I'm not at all sure that these terms are any better than the previous ones, and changing them may just create more confusion. Can we either find better ones, or revert to the originals?

* 3.4.2 explains reactive negotiation (i.e., where the client chooses from a list of links), and gives examples of how it's done with 300 responses, but doesn't mention that a hypertext format can support reactive negotiation natively, and therefore can happen with 200 OK responses as well (and I believe this is by far the most common form of conneg on the Web today). It would be good to illustrate this.

* 4.1 second to last paragraph talks about when Allow should be generated, but speaks about it in terms of an origin server generating the header, when it's very often implemented on a per-resource basis. Consider couching in those terms.

---

From: Amos Jeffries <[email-masked]>
Date: Sun, 21 Apr 2013 14:39:38 +1200

> * 3.1.2.1 "Frequently, the representation is stored in coded form, transmitted directly, and only decoded by the recipient."   Saying "final recipient" would be clearer.

But incorect. Encoded from responses are routinely decoded by 
intermediary proxies for processing (think AV scanners on gzipped 
objects). They fall under "recipient", but not "final recipient".

Amos

---

From: Mark Nottingham <[email-masked]>
Date: Sun, 21 Apr 2013 21:25:10 +1000

On 21/04/2013, at 12:39 PM, Amos Jeffries <[email-masked]> wrote:

> But incorect. Encoded from responses are routinely decoded by intermediary proxies for processing (think AV scanners on gzipped objects). They fall under "recipient", but not "final recipient".

This isn't normative, and the sentence starts with "frequently"; without "final", the "only" is quite odd...

---

From: Mark Nottingham <[email-masked]>
Date: Mon, 22 Apr 2013 13:48:19 +1000

Now:
  http://trac.tools.ietf.org/wg/httpbis/trac/ticket/450

---

From: James Cloos <[email-masked]>
Date: Wed, 24 Apr 2013 20:38:41 -0400

>>>>> "MN" == Mark Nottingham <[email-masked]> writes:

MN> It depends on whether you pronounce it "aigch" or "haigch." I
MN> personally don't care which we choose, as long as it's consistent.

No it doesn't.  An intiial H is ignored for a vs an, so both /aich/
and /haich/ take an.

-JimC
-- 
James Cloos <[email-masked]>         OpenPGP: 1024D/ED7DAEA6