New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

How was this manual constructed? #4

Closed
ColinEberhardt opened this Issue Dec 19, 2017 · 5 comments

Comments

Projects
None yet
2 participants
@ColinEberhardt
Copy link
Contributor

ColinEberhardt commented Dec 19, 2017

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:

https://webassembly.github.io/spec/

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)

@sunfishcode

This comment has been minimized.

Copy link
Owner

sunfishcode commented Dec 19, 2017

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.

@ColinEberhardt

This comment has been minimized.

Copy link
Contributor

ColinEberhardt commented Dec 20, 2017

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!)

@sunfishcode

This comment has been minimized.

Copy link
Owner

sunfishcode commented Dec 20, 2017

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.

@ColinEberhardt

This comment has been minimized.

Copy link
Contributor

ColinEberhardt commented Dec 21, 2017

Would you be interested in making a specific suggestion in a PR?

Yeah, I'd be happy to give it a go. See #5

I've also made a guess at a suitable open source licence.

@sunfishcode

This comment has been minimized.

Copy link
Owner

sunfishcode commented Dec 22, 2017

Closing now that #5 is merged and the initial questions answered; feel free to reopen or file new issues if you have more questions!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment