Join GitHub today
How was this manual constructed? #4
This is an extremely useful resource. I'm just wondering, how it was constructed, and how definitive it is considered to be?
I believe that the following is the definitive WebAssembly specification:
Although while it describes the language, it does that without reference to syntax.
What did you use as the source reference for constructing this guide?
(and if i can help resolve some TODOs I certainly will)
I wrote it myself, as I was closely involved with the design of WebAssembly, and I work on one of the major implementations. I originally wrote this document as a proposal for a starting-point for an official spec for WebAssembly, before there was an official spec document. The proposal was rejected, in favor of a plan to form what is now the official spec document. Consequently, it's not definitive in any official sense.
Since then, I haven't put a lot of time into it, so it's not as polished as it could be. However, I personally still find it more readable than the official spec, so I continue to fix errors whenever I notice them, and I accept PRs and issues. I'm not aware of any outstanding errors at this time.
At the time, it was my hope that WebAssembly's semantics would be very simple, such that a simple description in the style of the document here could easily and completely describe them. However, several of my proposals to that effect were rejected, and WebAssembly ended up with semantics that get very tricky. I attempted to describe the semantics that were accepted in this document, however it's quite possible that I've gotten some things subtly wrong.
Thanks for letting me know. I must admit, I find your documentation much more accessible than the official spec document, and use it is my primary reference. Thanks for all the effort you've put into this.
I do wonder whether it's worth adding a few words to the top of the document to describe what it is? i.e. an un-official spec document, written with readability and usability in mind, written by- and for- the community.
This might encourage other WebAssembly users to contribute changes.
At the moment it feels quite official, which might actually discourage contribution (I'd be nervous about questioning an official spec!)
Sure. I sort of started something in the README.md, but I appreciate the feedback. Would you be interested in making a specific suggestion in a PR? Otherwise, I can write something up myself, but I'm interested if you have specific ideas for how to present this.