docs: broken highlighting in syntax summary for `"`

[unkarjedy]

https://dotty.epfl.ch/docs/reference/syntax.html

[pikinier20]

The highlight.js interpreted this snippet as bash. According to https://highlightjs.org/static/demo/ it supports BNF but unfortunately no EBNF. We can try BNF highlighting and if it'll be still broken, disable highlighting.

[pikinier20]

Another thing is that this page is moved to: https://dotty.epfl.ch/docs/internals/syntax.html where the problem is solved. Shouldn't we remove the page from reference and add redirect to updated version?

[julienrf]

Good point @pikinier20. Yes, we need to figure out why there are two occurrences of this file, and which one should be kept.

[odersky]

There are two syntax.md pages, one in reference and one in internals. The internals page contains also experimental features supported by the compiler and sketches a translation into trees.

[julienrf]

I believe that keeping only one file to maintain would be simpler. Currently, if someone contributes a fix to reference/syntax.md we have to remember to tell them to also fix it under internals/syntax.md.

Would it be possible to keep only one file? That file would include the experimental features.

[odersky]

I think we need two files. One is docs for the official language reference, the other is docs for our internal implementation. Syntax changes should be rare and well thought through. Changing two syntax.md files is the least of our worries. We also have to change scalameta, ammonite, IntelliJ and all the other tools. That's the real burden.

[julienrf]

OK, then to fix the original issue we should just follow @pikinier20’s proposal: try marking the snippet as BNF code, and if it does not work mark it as plain text.

[unkarjedy]

I think we need two files. One is docs for the official language reference, the other is docs for our internal implementation.

From what I saw it's mostly about some small note/comment to some BNF rule. Otherwise the files looks the same

Some draft idea: As I understand there is some control of how *.md files are preprocessed and rendered (somewhere around here ?) Those implementation notes could be inserted in a single reference/syntax.md. syntax.md could be rendered in two modes then: with comments left and without the comments.

The comments could be marked using some special reserved marker, e.g. <<<< or ////, which would be removed on rendering.

### Types
```ebnf
Type              ::=  FunType
                    |  HkTypeParamClause ‘=>>’ Type                             ////LambdaTypeTree(ps, t)
                    |  FunParamClause ‘=>>’ Type                                ////TermLambdaTypeTree(ps, t)
                    |  MatchType
                    |  InfixType ;
FunType           ::=  FunTypeArgs (‘=>’ | ‘?=>’) Type                          ////Function(ts, t)
                    |  HKTypeParamClause '=>' Type                              ////PolyFunction(ps, t) ;

[julienrf]

The Scaladoc processing logic can not really be special-cased for the Scala 3 documentation only, as it aims to be a general documentation generator.

However, it might be possible to share common content by leveraging the template engine, I guess?

[odersky]

Reopened since a commit was reverted by #14958