Imported From: https://issues.scala-lang.org/browse/SI-9925?orig=1
Reporter: @dsbos

@som-snytt said:
https://github.com/scala/scala/blame/2.12.x/spec/13-syntax-summary.md#L32

It would be nice if there were a mechanism to synchronize productions in the summary with snippets in the main text.

@som-snytt said:
The definition is clarified by https://github.com/scala/scala/pull/5406/files and https://github.com/scala/scala/pull/5407/files

Maybe the syntax summary should be chapter 0 of the spec, since people overlook it.

@dsbos said:

The definition is clarified by https://github.com/scala/scala/pull/5406/files ...

Note that that PR clarifies only what "printable character" in the text refers to. (It doesn't address the fact that printableChar isn't actually specified in that chapter.) (I know; it's my PR.)

Maybe the syntax summary should be chapter 0 of the spec, since people overlook it.

Isn't the syntax summary supposed to be a summary--that is, isn't every grammar production listed in it supposed to be a copy of a production specified elsewhere? (Isn't that the norm for language specifications? It has been in those I've read and worked on.)

@som-snytt said:
I'm not sure if the ticket is calling for EBNF or just that printable gets its own entry in the list of character classes, where opchar uses it. opchar also appears in EBNF in the summary, but only in that prose list in the main text. Similarly everything in that list.

Printable also figures into the definition of blank line and multiline string.

It would be great to sync the summary <==> main text snippets. That would guarantee everything appears in both places somewhere.

Since many alternative productions appear in different sections of the text, I've always consulted the summary. But I've wanted the ability to follow a link back and forth. And searching into the summary is not trivial.

@SethTisue said:
Should I close as a "Not a Bug"?

@dsbos said (edited on Sep 29, 2016 9:17:19 PM UTC):

Should I close as a "Not a Bug"?

First, can I get an answer to my question above about the intent of syntax summary?

(Is it the case that each grammar production should be defined in some non-summary chapter, with the syntax summary being only a redundant copy?)

@dsbos said:

I'm not sure if the ticket is calling for EBNF or ...

I was calling for some explicit connection (in chapter 1) between printableChar and the text that talks about printable characters.

The simplest solution would be to copy the (pseudo-?)EBNF entry for printableChar from the summary character to chapter 1 (so that chapter 1's copy is the normative definition and the summary chapter's copy is just a (non-normative) copy).

@dsbos said (edited on Sep 29, 2016 9:12:43 PM UTC):
I notice that now http://www.scala-lang.org/files/archive/spec/2.11/01-lexical-syntax.html no longer refers to printableChar.

However, most of the non-terminals meant to be associated with the character-classes list right before section 1.1 (digit, lower, letter, lower, upper, and opchar) are in the same boat. (Referenced non-terminals are not actually defined in non-summary chapters.)

Similarly, I think that that list should be accompanied by (or possibly replaced by) ENBF entries for those non-terminals (copied from what already exists in the syntax summary chapter).

@som-snytt said:
Yes, that's what I was thinking in my last comment when I reopened the ticket, at your prompting.

There are a couple of other informal definitions to clarify. So I agree that ENBFing everything is least confusing.

I don't know the answer to how the syntax summary is intended.

@SethTisue said:

isn't every grammar production listed in it supposed to be a copy of a production specified elsewhere?

that's certainly my understanding. I can't think of an alternative

@dsbos said:
Where's a good place to discuss a slightly higher-level group of related changes to the form of specification?

(I'd like to have an HTML specification that has references to non-terminals linked to definitions of the terminals, so that it's easy to traverse to the definition, and, or course, I'd like to have a specification whose syntax summary matches the syntax defined in the body of the specification.

Getting there presumably involves creating some little utilities that at least checks for missing links and inconsistencies, but maybe inserts missing links too.

Creating such tools might push for switching to a slightly different EBNF syntax. (The current one doesn't have a token terminating each production, so it's not clear how to recognize the end of one production and the beginning of the next (at least without looking ahead for the ::=).))

Is there a good mailing list for discussing the pieces of that improvement? Or should I file a Jira report for the group and maybe sub-reports for the supporting pieces? Or something else?

@SethTisue said:

Is there a good mailing list for discussing [...]

yes! scala-internals