Opened 7 years ago

Closed 6 years ago

Last modified 6 years ago

#450 closed editorial (fixed)

p2 Editorial feedback

Reported by: mnot@… Owned by: draft-ietf-httpbis-p2-semantics@…
Priority: normal Milestone: 24
Component: p2-semantics Severity: In WG Last Call
Keywords: Cc:

Description

  • 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."
  • 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.

Change History (5)

comment:1 Changed 6 years ago by mnot@…

[2347] dealt with everything except the intro rewrite and moving 5.3 to be a subsection of 3.4.1. The former can be dropped unless someone wants to do it; the latter probably needs to be done by Julian or Roy.

comment:2 Changed 6 years ago by fielding@…

From [2352]:

(editorial) tweaks on the changes from [2347]; addresses #450

comment:3 Changed 6 years ago by fielding@…

Section 3 covers representations in general (any message). 3.1 defines header fields for content metadata (in any message). 3.4.1 is just an overview of how content negotiation works, in general, with forward references to the actual mechanisms.

Section 5 covers request header fields, which is where the proactive negotiation header fields belong.

I can't put 5.3 inside of 3.4.1 because they do not apply to messages in general. I can't put 3.4.1 inside 5.3 because that would leave a half-empty discussion of content negotiation in general. I can't put all of 3.4 in in 5.3 because the other forms of content negotiation have nothing to do with request header fields.

I see no reason to change the existing structure. The forward references are sufficient to cover a general reading, and the specific mechanisms are detailed where an implementer would expect them to be described.

comment:4 Changed 6 years ago by mnot@…

  • Resolution set to fixed
  • Status changed from new to closed

OK.

comment:5 Changed 6 years ago by julian.reschke@…

  • Milestone changed from unassigned to 24
Note: See TracTickets for help on using tickets.