Generate markdown files automatically

[j-f1]

I transcribed the human-readable markdown files into spec.estree then adapted estree-formal to make a script to parse it back into markdown documents.

There’s also the ability to generate JSON and TypeScript output, although it’s not being used at this time.

If you agree that this is a good direction, I can also look into generating the other es-version files with only the changes included.

Closes #209. Closes #208.

View rendered ES5 spec
View full rendered spec

[j-f1]

An overview of the spec.estree syntax:

• it’s mostly additive on top of the old syntax; the only thing that’s been removed is comment support.
• Add an @added([year], [proposal-slug]) decorator to almost anything to indicate it was added in that version (or use @es6 for ES6)
• Add an @section(level1 > level2 > ....) decorator to an interface to place it under a given heading. The default is to place it under a heading named for the first parent interface
• Add an @at-root decorator to an interface to place it at the top level
• Add an @headerless decorator to suppress creating a header (and section) for this interface
• Add a “comment” (using // syntax on one or more lines) before a key in an interface or the interface itself to add human-readable documentation.

[j-f1]

Another note: it would be easy to generate versions of the es2015…es2020 files that contain the entire spec as of that version instead of just the diffs by changing one function parameter in index.js. Outputting only the new/changed things should be possible but requires a bit more work.

[j-f1]

I'm not the person who is going to be maintaining the specs for years to come, so if you have any suggestions for changes to the syntax, I would be happy to implement them.

[nzakas]

Wow, this is intriguing. I think we're trying to figure out how to move forward with spec-year versions right now, so we will follow up here once we've resolved the direction. Thanks so much for this.

[JLHwung]

LGTM

[j-f1]

Any opinions on what should be done with the versioned Markdown files? Should they contain the entire spec as of that version or should I figure out how to make them just contain the relevant changes?