chore(http): Refresh headers docs (d-k) #36075

bsmth · 2024-09-27T09:17:44Z

Description

This PR refreshes a few HTTP headers pages.

common changes:

Improve See also
Capitalize Yes/No in properties table
Normalize The HTTP **`Header-Name`** (request|response) header in first sentence
Add status text to HTTPStatus macros, e.g. {{HTTPStatus("406", "406 Not Acceptable")}}
Remove improper use of quotes in and around code
Avoid escaping angle brackets in directive names in favor of backticks:

- \<directive>
+ `<directive>`

Motivation

Keeping content up-to-date, fixing formatting, unifying writing conventions

Related pull requests:

chore(http): Refresh some headers pages (~a-c) #36038

github-actions · 2024-09-27T09:19:15Z

Preview URLs (22 pages)

Flaws (1)

Note! 21 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/HTTP/Headers/Digest
Title: Digest
Flaw count: 1

bad_bcd_queries:
- No BCD data for query: http.headers.Digest

External URLs (7)

URL: /en-US/docs/Web/HTTP/Headers/Expect-CT
Title: Expect-CT

https://chromestatus.com/feature/6244547273687040 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTTP/Headers/Keep-Alive
Title: Keep-Alive

https://httpwg.org/specs/rfc9113.html (1 time) (Note! This may be a new URL 👀)
https://httpwg.org/specs/rfc9114.html (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTTP/Headers/DPR
Title: DPR

https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-client-hints-07 (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-security/user-agent-client-hints (1 time) (Note! This may be a new URL 👀)
https://wicg.github.io/responsive-image-client-hints/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTTP/Headers/If-None-Match
Title: If-None-Match

https://www.w3.org/1999/04/Editing/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2024-10-29 17:06:07)

github-actions · 2024-10-24T22:10:29Z

This pull request has merge conflicts that must be resolved before it can be merged.

hamishwillee · 2024-10-24T22:10:39Z

files/en-us/web/http/headers/date/index.md

@@ -7,12 +7,10 @@ browser-compat: http.headers.Date

 {{HTTPSidebar}}

-The **`Date`** general HTTP header contains the date and time
-at which the message originated.
+The HTTP **`Date`** header contains the date and time at which the message originated.


This form is used in some places. Up to you. I like the consistency.

Suggested change

The HTTP **`Date`** header contains the date and time at which the message originated.

The HTTP **`Date`** {{Glossary("Request header","request")}} and {{Glossary("Response header","response")}} header contains the date and time at which the message originated.

I was in two minds about this, my reasoning was it's either "requests only" or "responses only" (or a more granular classification), otherwise it's "a header" when it can be either, so I'm leaning towards leaving these out in those cases, what do you think?

Actually here's one that landed recently: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-WebSocket-Version

So let's go with this convention 👍🏻

I like the convention because you're explicitly saying if it can be a request, response, or both. Without mentioning both, you could have just forgotten to add the information. Tiny bit better for reader.

files/en-us/web/http/headers/date/index.md

files/en-us/web/http/headers/device-memory/index.md

hamishwillee · 2024-10-24T22:28:16Z

files/en-us/web/http/headers/digest/index.md

@@ -15,10 +15,11 @@ browser-compat: http.headers.Digest
 > Use {{HTTPHeader("Content-Digest")}} instead.
 > For `id-*` digest algorithms, use {{HTTPHeader("Repr-Digest")}}.

-The **`Digest`** response or request HTTP header provides the other side with a {{Glossary("digest")}} of the {{HTTPHeader("Content-Encoding")}}-encoded _selected representation_. It can be requested by using the {{HTTPHeader("Want-Digest")}} header.
+The HTTP **`Digest`** header provides the recipient with a {{Glossary("digest")}} of the {{HTTPHeader("Content-Encoding")}}-encoded _selected representation_.


Again, I like this form ...

Suggested change

The HTTP **`Digest`** header provides the recipient with a {{Glossary("digest")}} of the {{HTTPHeader("Content-Encoding")}}-encoded _selected representation_.

The HTTP **`Digest`** {{Glossary("Request header","request")}} and {{Glossary("Response header","response")}} header provides the recipient with a {{Glossary("digest")}} of the {{HTTPHeader("Content-Encoding")}}-encoded _selected representation_.

files/en-us/web/http/headers/digest/index.md

hamishwillee · 2024-10-24T22:40:15Z

files/en-us/web/http/headers/date/index.md

@@ -7,12 +7,10 @@ browser-compat: http.headers.Date

 {{HTTPSidebar}}

-The **`Date`** general HTTP header contains the date and time
-at which the message originated.


PS Also check https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/HTTP_header_page_template to make sure it matches all this work you are doing!

Note that the change you have made puts all the content up the top. I am happy with that, but in some case we might have too much information. So for the template I'd suggest that if the intro goes over the fold the author is allowed to add a separate section "Description" after the directive and before the direction, moving most of the content to that section.

That somewhat mirrors what Web APIs do.

add a separate section "Description" after the directive and before the direction

I don't follow this one 😄, where do you think "Description" should go?

So in Web APIs this appears after syntax sections, before Examples. The template hints that you have a short introductory sentence and then all the detail in the description. I don't particularly like that and try to avoid a description section if I can keep the text up the top succint.

So this pattern for HTTP would be:

Open to discussion. We don't have to do this, we just need to make sure that all this work you're doing is captured.

hamishwillee · 2024-10-24T22:43:00Z

files/en-us/web/http/headers/dpr/index.md

+
+Servers that opt in to the `DPR` client hint will typically also specify it in the {{HTTPHeader("Vary")}} header to inform caches that the server may send different responses based on the header value in a request.
+
+> [!WARNING]


I wonder if this warning should perhaps live up the top with the other headers?

I think we can put it up top, but we're getting pretty strong banner overload on this page now:

Absolutely correct. I don't think that matters because this is deprecated and we don't really want people to read it anyway :-).

That said, hopefully Ruth will eventually get the proposal for banners sorted out and implemented.

files/en-us/web/http/headers/dpr/index.md

hamishwillee · 2024-10-24T22:48:12Z

files/en-us/web/http/headers/early-data/index.md

-The **`Early-Data`** header is set by
-an intermediary to indicate that the request has been conveyed in [TLS early data](/en-US/docs/Web/Security/Transport_Layer_Security#tls_1.3),
-and also indicates that the intermediary understands the {{HTTPStatus("425", "425 Too Early")}} status code.
+The HTTP **`Early-Data`** {{Glossary("request header")}} is set by an intermediary to indicate that the request has been conveyed in [TLS early data](/en-US/docs/Web/Security/Transport_Layer_Security#tls_1.3), and also indicates that the intermediary understands the {{HTTPStatus("425", "425 Too Early")}} status code.


FWIW I don't really "get" this, but I am pretty sure that it doesn't matter - this is sufficient for most readers.

Maybe we can add some details to this page: https://aws.github.io/s2n-tls/usage-guide/ch14-early-data.html

I also noticed there's no See also section here

OK. I don't feel very strongly either way. It feels like the kind of thing only a deep dark expert would need, and they would read the spec.

files/en-us/web/http/headers/expect/index.md

files/en-us/web/http/headers/expires/index.md

files/en-us/web/http/headers/host/index.md

files/en-us/web/http/headers/if-modified-since/index.md

files/en-us/web/http/headers/if-none-match/index.md

files/en-us/web/http/headers/if-range/index.md

files/en-us/web/http/headers/keep-alive/index.md

Co-authored-by: Hamish Willee <[email protected]>

files/en-us/web/http/headers/if-unmodified-since/index.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Co-authored-by: Hamish Willee <[email protected]>

bsmth · 2024-10-31T11:27:34Z

files/en-us/web/http/headers/expect-ct/index.md

Missing a See also section on this page

bsmth added 2 commits September 27, 2024 11:13

chore(http): Refresh headers docs d-k

7845cf0

chore(http): Refresh headers docs d-k

36cf3aa

bsmth requested a review from a team as a code owner September 27, 2024 09:17

bsmth requested review from Elchi3 and removed request for a team September 27, 2024 09:17

github-actions bot added Content:HTTP HTTP docs size/l [PR only] 501-1000 LoC changed labels Sep 27, 2024

bsmth mentioned this pull request Sep 27, 2024

chore(http): Refresh headers docs i-r #36079

Merged

2 tasks

chore(http): Add glossary links to request and response header terms

4075e11

github-actions bot added the merge conflicts 🚧 [PR only] label Oct 24, 2024