This is the beginning of my list of all the "editorial" things I've spotted while reading the spec. Warning, many Oxford comma remarks pending... ;) I'm aware it's still a work in progress. This will be a part one because I don't think I'll manage to copy everything in one go.
Will use backticks for code, double quotes for quoting. p2 = paragraph two (etc) and is relative to the page (not section/header).
Page number; approximate position; quote; comment
3; 4.2.1 line 2; "literal notation"; make this bold too (consistent with "constructors" being bold)
3; p5; "implicit"; it's (going to be) explicitly exposed through `__proto__`, when that happens this sentence should probably adjusted accordingly
3; p5; "prototype chain"; isn't this "prototypal chain"?
3; 4.2.1 figure 1; this really needs fixing. Even knowing exactly what it does I don't think this clearly represents prototypal inheritance. I'm sure we can create a better example? Maybe one that simply uses `Foo` as the parent class and `foo` for the children?
3; p1; "objects and structure"; the "and" should be "objects, structure" because there's another "and" following this list.
4; p2; ; should this mention the `class` way of defining an object too? Aside from replacing the cryptic symbols with some concrete words, a codified example would be very welcome here. Maybe even two; one with and one without the class keyword.
4; 4.3; in general; The repetitive value vs type headers here could be caught in a more generic sense.
4; 4.3; general; There's a lot of topics missing that deserve to be in here. Especially new topics. I've not written them down centrally so I have no immediate list here. Instead I'll add this note down the road. To start, "generators" should be in this list.
4; note at bottom; "has a single prototype object"; add "optional" somewhere
5; 4.3.4 and 4.3.5; ; code examples welcome here
5; 4.3.8; ; "supplied by the host environment" was explicitly removed but I feel like it should still be there.
5; last note ; ; kind of redundant with 4.3.14 following immediately, stating the same thing.
6; 4.3.15 note; ; could be noted that a primitive is not strictly equal to it's boxed version (as it is in as3). This goes for all the primitives of course.
6; 4.3.19; "A Number value is a member of the Number type and", is kind of redundant. Especially with 4.3.20 following it, but even without.
6; 4.3.20; "(NaN) values"; "(NaN) value", js only knows one.
6; 4.3.23; "is a IEEE" ... "value"; "is any of the IEEE" ... "values". (Sorry if just bikeshed, this feels better).
7; 4.3.24; "subroutine"; very odd word for the ES language.
7; 4.3.24 note; "A function's ... in ECMAScript"; apart from a tautology, this comment either needs clarification (here), a reference to the clarification, or should be removed from this note here. It doesn't help.
7; 4.3.24; "built-in object that is a function"; "... that is specified by this specification", otherwise it's merely stating the obvious (and even with that suffix, it's still just stating the obvious). Maybe "A regular object that also contains executable code and can be invoked"/called/executed/whatever.
7; 4.3.25 note; "An implementation ... this specification"; not sure whether this sentence adds anything.
7; 4.3.27; "function that ... a property"; "any property that is a function"
7; 4.3.30 4.3.31; ; these sections should probably be re-ordered such that they follow 4.3.26 ("property") immediately?
7; 4.3.31; ; please change the wording of this sentence. It breaks my fragile informal mind :)
7; 5; in general; do we really need to go into parser theory in this specification? Might it be legacy that could be removed while still capable of using formal grammar in the spec? If not removed, I'd suggest moving it to an appendix, as it's not really important to the language.
7; 5.1.1; last sentence; Is that important? (I know there are some references to "chain" later, but the term didn't feel relevant to those context either).
8; p4; ; If you're going to cover regex, why not add JSON and quasis as well?
8; p5; ; The whole concept of colon count confused me to hell the first time I read the spec (few years ago). Reading it again now I'd say it's very much not important and the whole colon count thing should be thrown out. I'd suggest to not make the distinction with something insignificant as colons, but instead use clear production names to make sure productions stick to their own grammar. If not that, then choose another way of clarifying to which (sub-)grammar a production belongs. And make them unique per such grammar.
8; p10; ; drop this (see above)
9; p1; "to avoid ambiguities"; Like what? (regex, quasi, etc.). No need to go deeper into it, just an example so the reader knows what you're talking about or when this applies.
9; p2; ; the JSON grammar is only applied by `JSON.parse`. Wouldn't it make more sense to explain that this is the case? Rather than go for the generic case like it is now.
9; p4; ; drop (see above)
9; 5.1.6; "Grammar Notation" (title); "Grammar Formatting"
9; p5; "Terminal symbols ... are shown ..."; No point in going through all the grammar names. Just say "Terminal symbols are shown in fixed ...".
On a side note; especially for print; it might be useful to also mark up terminal symbols with a slight gray background. Just to clarify that this is in fact a terminal symbol. In most cases the fixed with font is sufficient, but sometimes (especially in one or two character cases), it's not.
Fun fact; the first time I read the spec (a few years ago) it really took me a few pages to realize that "terminal symbol" did not refer to a (keyboard) character entered in a console (terminal). Even with all the parser theory and p5 specifically, this fact was not at first clear to me. Not sure how this could have been prevented though.
9; p6; "(The number ... production belongs.)"; drop if the colon thing is dropped (see above).
9; p9; ; the opt sub could be replaced by a question mark. This is partially a bikeshed, but also might help in some cases where the production names and opt sub is literally quoted in regular text. The "opt" sub sometimes looks odd to me in such cases. And it's shorter, so that counts too... ;)
Nothing on page 10!
Will continue this. If any preferences in my formatting above or anything else please let me know.
p6; 4.3.16; "integer"; should be "integers"
(In reply to comment #0)
>
> 3; 4.2.1 line 2; "literal notation"; make this bold too (consistent with
> "constructors" being bold)
This section uses bold italic to introduce the definition of a new term. In this case "constructors" is such a term, but "literal notation" seems to be just a descriptive phrase. So, I think the current emphasis is correct. This is all ancient text and perhaps someday it will get rewritten and restyled but doing so isn';t an immediate priority.
>
> 3; p5; "implicit"; it's (going to be) explicitly exposed through `__proto__`,
> when that happens this sentence should probably adjusted accordingly
>
> 3; p5; "prototype chain"; isn't this "prototypal chain"?
>
> 3; 4.2.1 figure 1; this really needs fixing. Even knowing exactly what it does
> I don't think this clearly represents prototypal inheritance. I'm sure we can
> create a better example? Maybe one that simply uses `Foo` as the parent class
> and `foo` for the children?
>
> 3; p1; "objects and structure"; the "and" should be "objects, structure"
> because there's another "and" following this list.
replaced "and" with "while"
>
> 4; p2; ; should this mention the `class` way of defining an object too? Aside
> from replacing the cryptic symbols with some concrete words, a codified example
> would be very welcome here. Maybe even two; one with and one without the class
> keyword.
>
> 4; 4.3; in general; The repetitive value vs type headers here could be caught
> in a more generic sense.
This is the required ISO standard style for definitions.
>
> 4; 4.3; general; There's a lot of topics missing that deserve to be in here.
> Especially new topics. I've not written them down centrally so I have no
> immediate list here. Instead I'll add this note down the road. To start,
> "generators" should be in this list.
yes, needs to be updated
>
> 4; note at bottom; "has a single prototype object"; add "optional" somewhere
>
I think the next sentence covering a null prototype value is adequate.
> 5; 4.3.4 and 4.3.5; ; code examples welcome here
>
> 5; 4.3.8; ; "supplied by the host environment" was explicitly removed but I
> feel like it should still be there.
No, there are exotic objects that are part of the core language.
>
> 5; last note ; ; kind of redundant with 4.3.14 following immediately, stating
> the same thing.
>
> 6; 4.3.15 note; ; could be noted that a primitive is not strictly equal to it's
> boxed version (as it is in as3). This goes for all the primitives of course.
>
> 6; 4.3.19; "A Number value is a member of the Number type and", is kind of
> redundant. Especially with 4.3.20 following it, but even without.
>
> 6; 4.3.20; "(NaN) values"; "(NaN) value", js only knows one.
ok
>
> 6; 4.3.23; "is a IEEE" ... "value"; "is any of the IEEE" ... "values". (Sorry
> if just bikeshed, this feels better).
>
> 7; 4.3.24; "subroutine"; very odd word for the ES language.
>
> 7; 4.3.24 note; "A function's ... in ECMAScript"; apart from a tautology, this
> comment either needs clarification (here), a reference to the clarification, or
> should be removed from this note here. It doesn't help.
>
> 7; 4.3.24; "built-in object that is a function"; "... that is specified by this
> specification", otherwise it's merely stating the obvious (and even with that
> suffix, it's still just stating the obvious). Maybe "A regular object that also
> contains executable code and can be invoked"/called/executed/whatever.
>
> 7; 4.3.25 note; "An implementation ... this specification"; not sure whether
> this sentence adds anything.
>
> 7; 4.3.27; "function that ... a property"; "any property that is a function"
>
> 7; 4.3.30 4.3.31; ; these sections should probably be re-ordered such that they
> follow 4.3.26 ("property") immediately?
>
> 7; 4.3.31; ; please change the wording of this sentence. It breaks my fragile
> informal mind :)
>
> 7; 5; in general; do we really need to go into parser theory in this
> specification? Might it be legacy that could be removed while still capable of
> using formal grammar in the spec? If not removed, I'd suggest moving it to an
> appendix, as it's not really important to the language.
This section isn't about parser theory. It is about defining the grammar terminology used within the specification.
>
> 7; 5.1.1; last sentence; Is that important? (I know there are some references
> to "chain" later, but the term didn't feel relevant to those context either).
>
> 8; p4; ; If you're going to cover regex, why not add JSON and quasis as well?
JSON is convered in 5.1.5. Quasis don't use a distinct grammar.
>
> 8; p5; ; The whole concept of colon count confused me to hell the first time I
> read the spec (few years ago). Reading it again now I'd say it's very much not
> important and the whole colon count thing should be thrown out. I'd suggest to
> not make the distinction with something insignificant as colons, but instead
> use clear production names to make sure productions stick to their own grammar.
> If not that, then choose another way of clarifying to which (sub-)grammar a
> production belongs. And make them unique per such grammar.
>
> 8; p10; ; drop this (see above)
>
> 9; p1; "to avoid ambiguities"; Like what? (regex, quasi, etc.). No need to go
> deeper into it, just an example so the reader knows what you're talking about
> or when this applies.
>
> 9; p2; ; the JSON grammar is only applied by `JSON.parse`. Wouldn't it make
> more sense to explain that this is the case? Rather than go for the generic
> case like it is now.
>
> 9; p4; ; drop (see above)
>
> 9; 5.1.6; "Grammar Notation" (title); "Grammar Formatting"
>
> 9; p5; "Terminal symbols ... are shown ..."; No point in going through all the
> grammar names. Just say "Terminal symbols are shown in fixed ...".
>
> On a side note; especially for print; it might be useful to also mark up
> terminal symbols with a slight gray background. Just to clarify that this is in
> fact a terminal symbol. In most cases the fixed with font is sufficient, but
> sometimes (especially in one or two character cases), it's not.
>
> Fun fact; the first time I read the spec (a few years ago) it really took me a
> few pages to realize that "terminal symbol" did not refer to a (keyboard)
> character entered in a console (terminal). Even with all the parser theory and
> p5 specifically, this fact was not at first clear to me. Not sure how this
> could have been prevented though.
>
> 9; p6; "(The number ... production belongs.)"; drop if the colon thing is
> dropped (see above).
>
> 9; p9; ; the opt sub could be replaced by a question mark. This is partially a
> bikeshed, but also might help in some cases where the production names and opt
> sub is literally quoted in regular text. The "opt" sub sometimes looks odd to
> me in such cases. And it's shorter, so that counts too... ;)
>
> Nothing on page 10!
>
> Will continue this. If any preferences in my formatting above or anything else
> please let me know.
There are still some good suggestions here so I'm going to keep this open but deferred to ES7