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.

Sign up for GitHub

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

Jump to bottom

Can't generate html #143

Closed
skef opened this issue Mar 21, 2023 · 5 comments
Closed

Can't generate html #143

skef opened this issue Mar 21, 2023 · 5 comments

Comments

@skef
Copy link
Contributor

skef commented Mar 21, 2023

I'm trying to generate HTML for the current main branch and am seeing fatal errors along the lines of:

bikeshed spec Overview.bs
LINE ~301: Couldn't find section '#name-get' in spec 'rfc9110':
[[rfc9110#name-get]]
 ✘  Did not generate, due to fatal errors
make: *** [Makefile:4: Overview.html] Error 2

However, at least informally it does seem like rfc9110 has a heading with that id, and more generally bikeshed documentation is pretty sparse on what it's doing and how one would go about fixing these. Any guidance?
@skef
Copy link
Contributor Author

skef commented Mar 21, 2023

Hmm, I guess the -f flag works for this. I'll leave this open as there do seem to be dangling references now.

@garretrieger
Copy link
Contributor

I ran into this recently as well, something seems to have changed in bikeshed at the latest version. For now I've been able to get it to compile without errors using bikeshed 3.10.0. I'll look into this a bit more and see if it's something we're doing wrong or if it's an issue with bikeshed.

@svgeesus svgeesus mentioned this issue Apr 4, 2023
Closed
@tidoust
Copy link
Member

tidoust commented Apr 6, 2023

As mentioned in the Bikeshed's issue, this is due to the switch to Webref for xref data. Webref currently uses httpwg.org URLs for IETF RFCs developed by the HTTP Working Group, and fragment IDs are not the same in the httpwg.org version compared with the rfc-editor.org version.

Now, please hold on updating the fragment IDs, we're re-evaluating switching back to rfc-editor.org URLs for RFC9110 in Webref. The use of httpwg.org URLs is a good idea for older RFCs as the rfc-editor.org URL is not as usable, but not really needed for more recent RFCs.

I keep you updated (I need to evaluate what specs would need to be updated if we switch back to rfc-editor.org URLs)

tidoust added a commit to w3c/browser-specs that referenced this issue Apr 6, 2023
@tidoust
Stop using httpwg.org URL for newish RFCs
2ed81d4 
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 tidoust mentioned this issue Apr 6, 2023
Merged
tidoust added a commit to w3c/browser-specs that referenced this issue Apr 6, 2023
@tidoust
Stop using httpwg.org URL for newish RFCs (#920)
c3919c5 
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

tidoust commented Apr 7, 2023

Quick status update: Webref (and Bikeshed) xref data now contains headings from the rfc-editor.org. Unfortunately, I'm afraid that's not going to solve your linking errors because, in Webref, the IDs that get extracted for headings are the IDs of the wrapping sections when they exist, and not the IDs of the heading elements themselves.

So, typically, you'd have to use rfc9110#section-9.3.1 and not rfc9110#name-get to link to section 9.3.1 GET. I don't know why these RFCs contain 2 IDs for essentially the same thing.

@garretrieger
Copy link
Contributor

Thanks for the updates, I'll update our references to use the new IDs.

garretrieger added a commit that referenced this issue Apr 12, 2023
@garretrieger
Update rfc9110 and rfc9111 to use section references.
27f88d4 
Bikeshed no longer supports the section name references. See: #143.
@garretrieger garretrieger mentioned this issue Apr 12, 2023
Merged
svgeesus pushed a commit that referenced this issue Apr 20, 2023
@garretrieger
Update rfc9110 and rfc9111 to use section references. (#144)
a656c4c 
Bikeshed no longer supports the section name references. See: #143.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@tidoust @skef @garretrieger