Prefer httpwg.org over rfc-editor.org for IETF specs when possible #933
Comments
|
To revert the change that reverts the use of
|
tidoust
added a commit
to tidoust/specref
that referenced
this issue
Nov 23, 2023
The list was no longer complete as the IETF HTTP WG published a few other RFCs. Also, the https://httpwg.org/specs page is not such a good source for the list because it fails to list a few specs, and also contains one RFC that is actually not published under https://httpwg.org/specs. The comment explains how to extract the list from the underlying GitHub repository instead. In terms of updates, this will swap the URL of a few additional RFC entries from `www.rfc-editor.org` to `httpwg.org/specs`, notably RFC9110, RFC9111, RFC9112 and RFC9113. That's intended, the `httpwg.org/specs` versions are more readable, as discussed in: w3c/browser-specs#933
tidoust
added a commit
to tidoust/specref
that referenced
this issue
Nov 23, 2023
The list was no longer complete as the IETF HTTP WG published a few other RFCs. Also, the https://httpwg.org/specs page is not such a good source for the list because it fails to list a few specs, and also contains one RFC that is actually not published under https://httpwg.org/specs. The comment explains how to extract the list from the underlying GitHub repository instead. In terms of updates, this will swap the URL of a few additional RFC entries from `www.rfc-editor.org` to `httpwg.org/specs`, notably RFC9110, RFC9111, RFC9112 and RFC9113. That's intended, the `httpwg.org/specs` versions are more readable, as discussed in: w3c/browser-specs#933
tidoust
added a commit
that referenced
this issue
Nov 23, 2023
Take 3 :) PR #1135 actually had a couple of issues that made the code essentially useless because it only ran on a handful of IETF specs: - the code favored info from Specref over info from IETF - the code only really applied to drafts due to a buggy RegExp Fixing these problems yielded a new issue: the assumption that HTTP WG specs are always available under `httpwg.org` turns out to be wrong. Also, there are other specs that are not published by the HTTP WG but that still have an `httpwg.org` version. The code now looks at the actual list of specs in the underlying GitHub repository: https://github.com/httpwg/httpwg.github.io. As a result, the nightly URL of all IETF specs that have an `httpwg.org` version now targets that version, implementing the suggestion in #933 (see that issue for the list of affected specs). A companion PR was sent to Specref to implement a similar switch there: tobie/specref#766 The code also looks at the obsolescence data in datatracker and sets the `standing` and `obsoletedBy` properties accordingly. This fixes #327.
dontcallmedom
pushed a commit
to tobie/specref
that referenced
this issue
Nov 23, 2023
The list was no longer complete as the IETF HTTP WG published a few other RFCs. Also, the https://httpwg.org/specs page is not such a good source for the list because it fails to list a few specs, and also contains one RFC that is actually not published under https://httpwg.org/specs. The comment explains how to extract the list from the underlying GitHub repository instead. In terms of updates, this will swap the URL of a few additional RFC entries from `www.rfc-editor.org` to `httpwg.org/specs`, notably RFC9110, RFC9111, RFC9112 and RFC9113. That's intended, the `httpwg.org/specs` versions are more readable, as discussed in: w3c/browser-specs#933
|
Closing this issue as done. I prepared PRs to update the specs mentioned above:
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Via #920 (comment), where @sideshowbarker argues that httpwg.org would be better than rfc-editor.org:
[[
I propose considering to revert this change.
I don’t have any objection in principle for this change to be made based on weighing all the pros and cons — but I want to point out a statement in the issue description that appears to not be completely accurate:
I’m not completely sure I’m correctly understanding what’s meant by “URLs are just as readable”, but assuming what’s meant is that the published rfc-editor.org specs have readability for users equal to the readability of the httpwg.org versions, then I think that may not really be correct.
For example, compare these two:
Comparing those based on readability, I guess what jumps out right away is that the
Accept-Languageproduction in the HTTPWG version has syntax highlighting while the rfc-editor.org version doesn’t. That seems like a significant difference.But something else that to me at least is even more important for readability and usability — but that doesn’t jump out right away — is: the ABNF blocks for the productions in the HTTPWG version also have hyperlinks to the related section for that production.
For example, if you click on the word
weightin the HTTPWG version’s ABNF block, it jumps you to related section at for theweightproduction at https://httpwg.org/specs/rfc9110.html#quality.values.To me at least, that readability/usability difference between the HTTPWG versions and the rfc-editor.org versions is quite significant — given that it seems like a very-common information need/task for users of those specs is to be able to understand those productions and trace the references easily.
So I don’t object to this change being made on weighing all the factors and deciding that there are other factors that outweigh the readability deficiency of the rfc-editor.org versions — but I do object to this change being made on the basis of any claim that the rfc-editor.org URLs are just as readable.
]]
The text was updated successfully, but these errors were encountered: