[Spec.] Adding hypertext linking to grammar BNF

[Daniel Barclay]

The Scala language specification would be significantly more navigable if there were hypertext links between the grammar productions (that is, from each reference to a non-terminal in the BNF to the production that defines that non-terminal).

To give a feel for how navigable a grammar-hyperlinked version of the language specification could be, I have created a rough, proof-of-concept version (hacked together using grep and sed on the served-out HTML files).  See
http://dsbos.github.io/temp-scala-hyperlinked-spec/2016-11-13_2.12_output/index.html and dsbos/temp-scala-hyperlinked-spec.


I might be able to (help) implement that linking.

However, I'm not familiar with Jekyll and other technology that is used to generate the final HTML from the Markdown source, so I don't know what the most likely options are for either generating links automatically (by parsing the BNF) or at least providing some automated support for manually maintaining source that generates links (e.g., a checker to note new BNF items that are not marked up yet).

I'm thinking of writing a Scala utility to parse the BNF and add appropriate markup (e.g., Markdown source or HTML), but I don't know how (or whether) that would fit within the current processing pipeline.

What do the most likely options for adding such parsing and link generation seem to be?

Could anchors and links be added to the source Markdown, or would that make that BNF source too hard to read for maintainers?

Can whatever processes Markdown code blocks dispatch to plug-ins (per the language code, i.e., the "ebnf" in a "```ebnf" line?  If so, what programming languages could be used for such a plug-in?


Thanks,
Daniel

[Seth Tisue]

I don’t know the answers to most of your questions. But:

> I don't know how (or whether) that would fit within the current processing pipeline

The current processing pipeline is just some shell commands in .travis.yml. We are free to add basically anything reasonable to that, as long as it can be made to run on Travis. (It should not be too difficult for people to run locally as well, for testing.)

Seth