httpwg / admin

When you want to speak to the manager.
10 stars 15 forks source link

style: headers *and* trailers #30

Open LPardue opened 2 years ago

LPardue commented 2 years ago

In https://github.com/httpwg/admin/blob/main/style-guide.md#header-and-trailer-fields the guidance says

If the field is specific to headers, trailers, requests, and/or responses, the definition should include the relevant terms, as above.

and

Subsequent occurrences should be unquoted, but always be followed by "field", "header field", or "trailer field" as appropriate.

Content-Digest, for example, is all of these things. So ends up being defined as "the Content-Digest request and response header and trailer field". We refreain from saying "header and trailer" everywhere though. Should we really just be saying "field" or does that gloss over the definition of the field too much?

Perhaps the style guide would benefit from the explicit counter case in the guidance along the lines of "if a field applies to multiple categories, those categories can be ommited and only "field" used. Or some other guidance if I'm not on the money,

mnot commented 2 years ago

Content-Digest, for example, is all of these things. So ends up being defined as "the Content-Digest request and response header and trailer field"

Not necessarily. I'd construct it as:

The Content-Digest field can occur in request and response messages, in the header or trailer section.