x/website: syntax rules in spec are not hyperlinked anymore

[griesemer]

In the (distant?) past, the syntax rules (EBNF grammar) were hyperlinked: clicking on the name of a production lead to the corresponding definition. This was very helpful to explore the grammar. The spec also used some of the link targets in the prose, some of which are now stale (such as MethodName). The recent CL 381954 tries to fix these by changing the links to section headers, but that is not the intent of those links - they should point to the grammar productions.

The spec source text (doc/go_spec.html) doesn't contain the link information, it is automatically hyperlinked by running Linkify (website/internal/spec/spec.go) which appears to be called from serveHTML (website/internal/web/site.go). For some reason it is not run, though. As an aside, the hyperlinking also checks that the EBNF is syntactically correct, another benefit.

Looking at the source of the served spec I see that it starts with <!DOCTYPE. The code in serveHTML checks for this and exits early. Maybe it's just a matter of swapping the order of the if's in that code? (That said, I'm not familiar with the details of how the website is created anymore, and where the <!DOCTYPE is added (it's not in doc/go_spec.html).

I suspect this should be fairly easy to fix if one knows where to look. It would be good to fix this for 1.18 as we have introduced new grammar. Also, having the EBNF syntax check and being able to jump to grammar productions is generally useful.

Not a release blocker because this appears to have been broken for a while.

[griesemer]

cc: @dmitshur @jamalc

[griesemer]

Ping. Can somebody familiar with the current workings of the website server comment on this? It would be a shame to have lost this ability, especially because the code is actually present, just not used.

[dmitshur]

I don't have a chance to look into this issue closely myself, but wanted to comment on this part, in case it helps point you in the right direction:

The code in serveHTML checks for this and exits early. Maybe it's just a matter of swapping the order of the if's in that code? (That said, I'm not familiar with the details of how the website is created anymore, and where the <!DOCTYPE is added (it's not in doc/go_spec.html).

In general, the Go website (primarily https://go.dev, but also other domains such as https://golang.org, https://tour.golang.org, https://golang.google.cn) is all served by the cmd/golangorg command in x/website, and its README is up to date and provides a good starting point. If you run the command locally, it'll serve the entire website, and that's a good way to check e.g. what happens if that if is swapped.

Looking at the source of the served spec I see that it starts with <!DOCTYPE.

The served HTML will always have the "<!DOCTYPE" prefix: it might be added automatically by internal/web, or it might coming from a .html content file that explicitly includes that prefix, which effectively disables the template wrapping.

(it's not in doc/go_spec.html)

That's the right place to look. Indeed, the go_spec.html content file doesn't have the "<!DOCTYPE" prefix, and so it's probably not relevant in this issue.

[gopherbot]

Change https://go.dev/cl/388859 mentions this issue: internal/web: fix syntax rules hyperlinks