[JS] Bikeshed usage/web spec conventions feedback

[domenic]

I realize the draft is pretty rough, but I wanted to provide some early guidance on things I noticed. I can't find the source so I'm not able to inspect it to help more, but just to start:

• We don't generally typographically mark up "true" and "false" in web specs.
• Use Infra where possible. E.g. instead of List, do [=list=]. Optionally you can then do things like [=list/For each=].
• For ES abstract operations:
  • Add them to your anchors block (example)
  • Reference them later with <a abstract-op>Operation</a>(...) (example)
• In general, don't use direct links into other specs; you want to set up your anchors block so that autolinking just works. This can be tricky but is worth it in general.
• "compile a WebAssembly module":
  • The argument should be {{BufferSource}} not just BufferSource
  • Creating objects in web specs is vague and hand-wavy, unfortunately. (Related: State that by default all objects are created in the relevant realm of this whatwg/webidl#135 .) But we usually say create a new {{X}} object, not the spec's current "Let module be a new object whose [[Prototype]] is the interface prototype object of Module."
• compile(bytes):
  • We're trying to move away from performing steps after you've returned. So instead use a structure like https://www.w3.org/2001/tag/doc/promises-guide#explicit-async-steps which creates, performs in parallel steps, then returns.
  • Don't fulfill promises; resolve them.
  • Link to the promises guide for resolving/rejecting promises. It's not perfect but it's what everyone else does so when we fix the promises guide to be better you'll get the trickle-down effects.
• "instantiate a WebAssembly module":
  • There seems to be a switch to monospace for variables; stick with |var|.
  • Link to Infra for Assert (just [=Assert=] should do it).
  • I guess in general this algorithm is still in the process of being converted, so I'll leave it alone.

[littledan]

Thanks for the review! I'll make these changes. You can find the source in https://github.com/littledan/spec/blob/new-js.bs/document/JS.bs if you're curious.

[domenic]

Great! Maybe you could add a link in the header back to the repository.

[littledan]

OK, I've made most of these changes and finished the initial conversion; you can see the first draft in https://littledan.github.io/spec/document/JS.html .

[ericprud]

@domenic, can this issue be closed?