Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Stop using httpwg.org URL for newish RFCs #920

Merged
merged 1 commit into from
Apr 6, 2023
Merged

Stop using httpwg.org URL for newish RFCs #920

merged 1 commit into from
Apr 6, 2023

Conversation

tidoust
Copy link
Member

@tidoust tidoust commented Apr 6, 2023

Entries for RFC9110, RFC9111, RFC9112, RFC9113 and RFC9114 were explicitly forcing the use of httpwg.org URLs. That's not really useful since the rfc-editor.org URLs are just as readable. That also introduces hiccups because fragment IDs are not the same in both versions, as in: w3c/IFT#143

This update drops the explicit mention. In practice, that means that the info in browser-specs will align itself with whatever is in Specref, and Specref has the appropriate logic (httpwg.org for old RFCs, rfc-editor.org for newer ones).

Looking at Webref data, this switch will only impact the FedCM spec. Other specs that reference the afore-mentioned RFCs do not link to sections.

Example of update that this will introduce:

{
  "url": "https://www.rfc-editor.org/rfc/rfc9114",
  "seriesComposition": "full",
  "shortname": "rfc9114",
  "series": {
    "shortname": "rfc9114",
    "currentSpecification": "rfc9114",
    "title": "HTTP/3",
    "shortTitle": "HTTP/3",
    "nightlyUrl": "https://www.rfc-editor.org/rfc/rfc9114"
  },
  "nightly": {
    "url": "https://www.rfc-editor.org/rfc/rfc9114",
    "status": "Proposed Standard",
    "repository": "https://github.com/httpwg/httpwg.github.io",
    "alternateUrls": [],
    "sourcePath": "specs/rfc9114.xml",
    "filename": "rfc9114.html"
  },
  "organization": "IETF",
  "groups": [
    {
      "name": "QUIC Working Group",
      "url": "https://datatracker.ietf.org/wg/quic/"
    }
  ],
  "title": "HTTP/3",
  "source": "specref",
  "shortTitle": "HTTP/3",
  "categories": [
    "browser"
  ],
  "standing": "good"
}

Entries for RFC9110, RFC9111, RFC9112, RFC9113 and RFC9114 were explicitly
forcing the use of `httpwg.org` URLs. That's not really useful since the
`rfc-editor.org` URLs are just as readable. That also introduces hiccups
because fragment IDs are not the same in both versions, as in:
w3c/IFT#143

This update drops the explicit mention. In practice, that means that the
info in browser-specs will align itself with whatever is in Specref, and
Specref has the appropriate logic (`httpwg.org` for old RFCs, `rfc-editor.org`
for newer ones).

Looking at Webref data, this switch will only impact the FedCM spec. Other
specs that reference the afore-mentioned RFCs do not link to sections.

Example of update that this will introduce:

```json
{
  "url": "https://www.rfc-editor.org/rfc/rfc9114",
  "seriesComposition": "full",
  "shortname": "rfc9114",
  "series": {
    "shortname": "rfc9114",
    "currentSpecification": "rfc9114",
    "title": "HTTP/3",
    "shortTitle": "HTTP/3",
    "nightlyUrl": "https://www.rfc-editor.org/rfc/rfc9114"
  },
  "nightly": {
    "url": "https://www.rfc-editor.org/rfc/rfc9114",
    "status": "Proposed Standard",
    "repository": "https://github.com/httpwg/httpwg.github.io",
    "alternateUrls": [],
    "sourcePath": "specs/rfc9114.xml",
    "filename": "rfc9114.html"
  },
  "organization": "IETF",
  "groups": [
    {
      "name": "QUIC Working Group",
      "url": "https://datatracker.ietf.org/wg/quic/"
    }
  ],
  "title": "HTTP/3",
  "source": "specref",
  "shortTitle": "HTTP/3",
  "categories": [
    "browser"
  ],
  "standing": "good"
}
```
@tidoust
Copy link
Member Author

tidoust commented Apr 6, 2023

I'll prepare a PR to update the FedCM spec once that gets merged

@tidoust tidoust merged commit c3919c5 into main Apr 6, 2023
@tidoust tidoust deleted the httpwg-rfc branch April 6, 2023 10:29
@sideshowbarker
Copy link
Contributor

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:

the rfc-editor.org URLs are just as readable

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-Language production 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 weight in the HTTPWG version’s ABNF block, it jumps you to related section at for the weight production 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants