request for feedback: editorial change to restructure SDOs #1950
Comments
|
I think restructuring the specification so that all the definition for each operation is in a single place, rather than spread across the various places each relevant syntactic form is defined, would be an improvement. |
|
yes yes so much yes |
|
As an editor and a reader, definitely in favor as well. |
|
In addition to providing a singular link target for a given SDO, it would also provide a place where one could describe the general semantics of the SDO (if that were deemed useful). Would you put all the SDOs in one place, or locate each at some appropriate spot in the spec, or a combination of the two approaches? Early Errors are syntax-directed rules; but I gather they'd stay where they are? |
I was envisioning they'd have their own section (maybe Evaluation is split out?). A nice alphabetical listing of them.
We discussed this during the call, actually. It'd probably be best to leave them where they are. We can also have a new annex that has a copy of all of them in one place. |
|
Now that I think about it, there won't be much of a reason for Annex A anymore, will there? |
|
Are you thinking that, once all the SDOs have been pulled out and collected in one section, what remains in the "body" of the spec would present the grammar in a 'concentrated' enough form that we wouldn't need Annex A? Well, certainly, clauses 11 through 15 would be a lot slimmer, but they wouldn't just be grammar. There'd also be:
Or are you thinking that some of that stuff would also migrate elsewhere, leaving basically just Syntax + Early Errors? |
|
I'm thinking that what remains will be fairly compact, yes. Once we've extracted the SDOs, we could get a better idea of whether it would make sense to move the AOs defined in those sections as well. But if we did do that, I think it should be a separate step. |
|
Moving that much text has the potential to create lots of merge conflicts for in-flight PRs (and pre-PR branches). Would you try to minimize that by resolving such PRs before extracting the SDOs? |
|
@waldemarhorwat points out that it would be useful for there to be links from each production to all of the SDOs which are defined for it. We should do that too. It should be possible to make that happen automatically from ecmarkup with a little work, though the definitions which are omitted because of the chain production rule would probably not get links without doing substantially more work. Since those aren't mentioned next to the productions currently, that omission will at least not make the state of affairs worse. |
|
Some issues this would resolve: |
|
Fun fact: according to Allen's JavaScript: The First 20 Years, this style is borrowed from the LISP 1.5 Programmer's Manual, specifically (the paper speculates) from the description of the PROG feature:
(The spec with this style was competing with Brendan Eich's spec at the initial TC39 meeting, and was chosen over it on the basis that it was written in Word and Ecma liked Word.) |
|
The spec has two distinct activities that are both referred to as evaluate/evaluating/evaluation:
Currently, they're in different parts of the spec, so the overlap in terminology is not a big deal. But if the restructuring proposed here brought them together as a single SDO, that might be confusing. So you might want to rename one of them first. |
Be careful that the links don't clutter up the grammar. (E.g., have them appear only on request.) I think the "worst case" is LabelledStatement, for which 14 different SDOs have an explicit definition:
|
|
@jmdyck what I was thinking was that those sections would be collectively replaced by a list of the SDOs: so instead of having 13.13.2-15 (or 14.9.2.1), there would be a single 13.13.2 which contained a 14-item list of SDO names, with those linking to the relevant part of the named SDO. I hope that wouldn't be too cluttered, but we'll have to experiment. (I was a little imprecise above: I didn't mean to say the names would be following each production but rather each set of productions, just the SDOs themselves do now.) |
|
Okay, that would leave the grammar easy to read. When you say "with those linking to the relevant part of the named SDO", do you mean that each SDO-clause would be divided into parts? (E.g., the clause dedicated to ContainsDuplicateLabels might have one part that's basically the current 13.13.2, and another that's 13.6.2, and so on?) |
|
What I'm currently envisioning is that it would not be divided in the sense of having a visual separation between parts, but rather it would have |
|
So, e.g., would the new
etc or like this?
etc The first sounds like what you were saying (a single clause with a 14-item list of SDO names), but the second sounds like what @waldemarhorwat was reported to suggest (links from each production to all of the SDOs which are defined for it). I suppose it could be either, at user option, because the content is going to be generated, right? |
|
Why would 13.13 contain a section for As such, I was expecting 13.13 to be just
(With those being links, of course.) Some sections have multiple productions defined, not all of which have all the relevant SDOs defined over them, but I am hopeful that won't be too confusing.
It could, though I'm probably not going to build support for other modes unless they're requested or seem particularly useful. And we do need to pick a canonical one for the PDF rendering sent to ECMA. |
Sorry, replace "13.13" in my comment with "13.2".
So given that the current 13.13.2 defines ContainsDuplicateLabels for 2 different productions, the new 13.13.2's "ContainsDuplicateLabels" would be a link to (say) whichever of those productions occurs first in the ContainsDuplicateLabels clause? |
Yup. But the productions would be adjacent within that clause, ordered the same way they are in the grammar, so hopefully it would be easy to find the one you were looking for. |
|
Yeah, that might work. Compared to the current rendering, it's got about the same amount of clicking-and-scrolling to get from a production to an SDO's definition for that production. It could be about optimal for the PDF rendering. But it might seem kind of coarse-grained to someone who wanted "links from each production to all of the SDOs which are defined for it". Here's a possible enhancement: currently, when you hover over a production, you get a pop-up with "Permalink Pin References". Consider adding "SDOs", which (similar to "References") opens a pane that lists all the SDOs defined on that production, each being a link to that SDO's definition for that production. (Even more fine-grained would be to do it per right-hand-side.) |
|
The "References" section of the popup actually already contains links to the SDOs defined over the production, going specifically to the definitions corresponding to that production. We could just keep that. |
No, I don't think it does. It looks to me like it contains links to places where the production's LHS-symbol occurs in the RHSs of other productions, or in algorithms, or in prose. Some of which might be in SDO definitions, but those would not generally be SDO definitions for the production in question. E.g., consider the IfStatement production. The References pane has 3 references, none of which are to SDO definitions. Yet 7 SDOs have definitions for IfStatement. Or look at the Block production. In 13.2.*, there are 10 SDOs defined on that production, but the "References" pane doesn't link to any of those definitions. It's the same with other productions I've tried. (One situation where it might look otherwise is when a production's LHS-symbol also appears on one or more of its RHSs, because then when the References pane links to RHS occurrences of that symbol, some of them might happen to be from the production in question.) |
|
We should be sure to do this for Contains as well (cf #2251). |
|
The SDO definitions in the RegExp clause are the only ones in the 'standard library' part of the spec. Are you thinking that they would be merged in with all the other SDOs, or would they undergo their own re-org, but stay within the RegExp clause? |
|
That's a good question. I'm inclined to leave them where they are - they are defined over a different grammar, after all. They also have the property that their definitions are not spread out: CapturingGroupNumber, for example, is only defined over two productions, and those definitions appear in the same clause. So there's much less reason to reorganize. I'm not sure they need to be reorganized at all. |
|
Looking into this more concretely: There's a few special cases. Of the remainder, 46 have definitions which are already contained in a single clause:
And only 41 have definitions which are split across multiple clauses:
The original proposal was to put all SDOs into a single clause, but I'm no longer sure that makes sense. I'm inclined to only reorganize this last group of 41, and to try to put each in the location where it makes the most sense, just as other abstract operations are spread across the specification wherever they make the most sense. (In several cases there's only a single callsite, so we can just put the definition after the algorithm which calls it.) |
In the most recent editor call, we were discussing general solutions to linking to SDOs such as those described in #1927 and #1821. I proposed a solution of restructuring the specification to group the definitions of each SDO together, instead of grouping all SDO definitions for each production together. This would allow us to link to the one place where an SDO is defined, and we believe would be generally more useful for readers. But we wanted to allow time for readers to give us feedback before this fairly significant restructuring of ECMA-262.
edit: WIP concrete proposal, will edit as conversation below develops:
The text was updated successfully, but these errors were encountered: