Ecma262: Formatting large objects

[codehag]

This isn't a bug, its a formatting question/request. (cc @ljharb)
I am currently reading https://tc39.es/ecma262/#sec-parsemodule and the last instruction here returns a complex object with a number of fields. It looks like this in the text:

12. Return Source Text Module Record { [[Realm]]: realm, [[Environment]]: undefined, [[Namespace]]:
     undefined, [[Status]]: unlinked, [[EvaluationError]]: undefined, [[HostDefined]]: hostDefined, 
     [[ECMAScriptCode]]: body, [[Context]]: empty, [[ImportMeta]]: empty, [[RequestedModules]]: 
     requestedModules, [[ImportEntries]]: importEntries, [[LocalExportEntries]]: localExportEntries, 
     [[IndirectExportEntries]]: indirectExportEntries, [[StarExportEntries]]: starExportEntries, [[DFSIndex]]: 
     undefined, [[DFSAncestorIndex]]: undefined }.

I imagin this has been discussed in the past. Are there ideas of how to make this easier to read? For example:

12. Return Source Text Module Record { 
  [[Realm]]: realm, 
  [[Environment]]: undefined, 
  [[Namespace]]: undefined, 
  [[Status]]: unlinked, 
  [[EvaluationError]]: undefined, 
  [[HostDefined]]: hostDefined, 
  [[ECMAScriptCode]]: body, 
  [[Context]]: empty, 
  [[ImportMeta]]: empty, 
  [[RequestedModules]]: requestedModules, 
  [[ImportEntries]]: importEntries, 
  [[LocalExportEntries]]: localExportEntries, 
  [[IndirectExportEntries]]: indirectExportEntries, 
  [[StarExportEntries]]: starExportEntries, 
  [[DFSIndex]]: undefined, 
  [[DFSAncestorIndex]]: undefined 
}.

It takes up a lot more space, but it is also much easier to see what is going on.

[ljharb]

That seems fine to me, altho i'd hope ecmarkup could indent it more like this:

12. Return the Source Text Module Record { 
      [[Realm]]: realm, 
      [[Environment]]: undefined, 
      [[Namespace]]: undefined, 
      [[Status]]: unlinked, 
      [[EvaluationError]]: undefined, 
      [[HostDefined]]: hostDefined, 
      [[ECMAScriptCode]]: body, 
      [[Context]]: empty, 
      [[ImportMeta]]: empty, 
      [[RequestedModules]]: requestedModules, 
      [[ImportEntries]]: importEntries, 
      [[LocalExportEntries]]: localExportEntries, 
      [[IndirectExportEntries]]: indirectExportEntries, 
      [[StarExportEntries]]: starExportEntries, 
      [[DFSIndex]]: undefined, 
      [[DFSAncestorIndex]]: undefined 
    }.

[michaelficarra]

We should also sort slots lexicographically by name.

[bakkot]

Sounds good to the editors, but I suspect we'd need support in ecmarkdown for multi-line steps (or Records explicitly), which I'm not going to prioritize right away.

[jmdyck]

Note that there are two possibly-independent issues:

• Making the source easier to read.
• Making the rendered HTML easier to read.

I think the discussion so far has been mostly about the HTML rendering, but it's not always clear.

[jmdyck]

Note that there are a few places in the spec (e.g., CreateHTML) where the 'content' of an algorithm step includes a bulleted list. So I'm guessing that if the source were changed to something like this:

1. Return the Source Text Module Record with the following fields:
  * [[Realm]]: _realm_
  * [[Environment]]: *undefined*
  * [[Namespace]]: *undefined*
  * [[Status]]: ~unlinked~

then ecmarkup (without any changes) would render it more-or-less as @codehag suggests. (We'd just have to update the Record type clause to say that this is another syntax for defining records.)

[bakkot]

I think the discussion so far has been mostly about the HTML rendering, but it's not always clear.

Yeah, I'm concerned only about the HTML rendering. It'd be nice to also have the source text look good, but that's a much lesser concern since it affects far fewer people.

[ExE-Boss]

We could also define an <emu‑record> tag and use that somehow, for example like:

1.  Return the <emu-record name="Source Text Module Record">
        * [[Realm]]: _realm_
        * [[Environment]]: *undefined*
        * [[Namespace]]: *undefined*
        * [[Status]]: ~unlinked~
    </emu-record>.

Which would get rendered into:

<li>Return the <emu-record name="Source Text Module Record">
    <emu-xref href="#sourctextmodule-record"
        ><a href="#sourctextmodule-record">Source Text Module Record</a
    ></emu-xref> {
    <ul class="emu-record-fields">
        <li>[[Realm]]: <var>realm</var>,</li>
        <li>[[Environment]]: <emu-val>undefined</emu-val>,</li>
        <li>[[Namespace]]: <emu-val>undefined</emu-val>,</li>
        <li>[[Status]]: <emu-const>unlinked</emu-const></li>
    </ul>
}</emu-record>.</li>

With the CSS:

.emu-record-fields {
    list-style: none;
    margin-block-start: 0;
    margin-block-end: 0;
}

.emu-record-fields > li {
    display: block;
}