Merge pull request wasmerio#192 from jdanford/fix-documentation-forma…

…tting-and-grammar

Fix formatting and grammar in documentation

ARCHITECTURE.md

@@ -2,27 +2,27 @@
 
 Wasmer uses the following components:
 
-- [Cranelift](https://github.com/cranestation/cranelift): for compiling WASM function binaries into Machine IR
-- [wabt](https://github.com/pepyakin/wabt-rs): for transforming `.wast` files to `.wasm` and also to run WebAssembly spectests
-- [wasmparser](https://github.com/yurydelendik/wasmparser.rs): for parsing the `.wasm` files and translating them into WebAssembly Modules
+- [Cranelift](https://github.com/cranestation/cranelift): for compiling Wasm binaries to machine code
+- [wabt](https://github.com/pepyakin/wabt-rs): for transforming `.wast` files to `.wasm` and running WebAssembly spec tests
+- [wasmparser](https://github.com/yurydelendik/wasmparser.rs): for parsing the `.wasm` files and translating them into WebAssembly modules
 
-## How Wasmer works?
+## How Wasmer works
 
-The first time you run `wasmer run myfile.wasm`, wasmer will:
+The first time you run `wasmer run myfile.wasm`, Wasmer will:
 
-- Check if is a `.wast` file. If so, transform it to `.wasm`
-- Check that the provided binary is a valid WebAssembly one. That means, that its binary format starts with `\0asm`.
-- If it looks like a WebAssembly file, try to parse it with `wasmparser` and generate a `Module` from it
-- Once a `Module` is generated, an `Instance` is created with the proper `import_object` (that means, if is detected as an emscripten file, it will add the emscripten expected imports)
-- Try to call the WebAssembly start function, or if unexistent try to search for the one that is exported as `main`.
+- Check if is a `.wast` file, and if so, transform it to `.wasm`
+- Check that the provided binary is a valid WebAssembly one, i.e. its binary format starts with `\0asm`.
+- Parse it with `wasmparser` and generate a `Module` from it
+- Generate an `Instance` with the proper `import_object` (that means, if is detected to be an Emscripten file, it will add the Emscripten expected imports)
+- Try to call the WebAssembly `start` function, or if it does not exist, try to search for the function that is exported as `main`
 
 Find a more detailed explanation of the process below:
 
 ### Phase 1: Generating the Module / IR
 
 As the WebAssembly file is being parsed, it will read the sections in the WebAssembly file (memory, table, function, global and element definitions) using the `Module` (or `ModuleEnvironment`) as the structure to hold this information.
 
-However, the real IR initialization happens while a function body is being parsed/created. That means, when the parser reads the section `(func ...)`.
+However, the real IR initialization happens while a function body is being parsed/created, i.e. when the parser reads the section `(func ...)`.
 While the function body is being parsed the corresponding `FuncEnvironment` methods will be called.
 
 So for example, if the function is using a table, the `make_table` method within that `FuncEnvironment` will be called.
@@ -41,15 +41,14 @@ Once we have the compiled values, we will push them to memory and mark them as e
 
 #### Relocations
 
-Sometimes the functions that we generated will need to call other functions.
-However the generated code have no idea how to link this functions together.
+Sometimes the functions that we generate will need to call other functions, but the generated code has no idea how to link these functions together.
 
-For example, if a function `A` is calling function `B` (that means is having a `(call b)` on it's body) while compiling `A` we will have no idea where the function `B` lives on memory (as `B` is not yet compiled nor pushed into memory).
+For example, if a function `A` is calling function `B` (that means is having a `(call b)` on its body) while compiling `A` we will have no idea where the function `B` lives on memory (as `B` is not yet compiled nor pushed into memory).
 
 For that reason, we will start collecting all the calls that function `A` will need to do under the hood, and save it's offsets.
 We do that, so we can patch the function calls after compilation, to point to the correct memory address.
 
-Note: Sometimes this functions rather than living in the same WebAssembly module, they will be provided as import values.
+Note: sometimes this functions rather than living in the same WebAssembly module, they will be provided as import values.
 
 #### Traps
 
@@ -66,5 +65,5 @@ Once that's finished, we will have a `Instance` function that will be ready to e
 
 ## Emscripten
 
-The Wasmer Emscripten integration tries to wrap (and emulate) all the different syscalls that Emscripten needs.
-We provide this integration by filling the `import_object` with the emscripten functions, while instantiating the WebAssembly Instance.
+Wasmer's Emscripten integration tries to wrap (and emulate) all the different syscalls that Emscripten needs.
+We provide this integration by filling the `import_object` with the Emscripten functions, while instantiating the WebAssembly Instance.

ATTRIBUTIONS.md

@@ -2,17 +2,17 @@
 
 Wasmer is a community effort.
 In order to build the best WebAssembly runtime it's our duty to see how other runtimes are approaching the same space
-and get inspired from them on the things that they got right, so wasmer and its community can benefit from a solid
+and get inspired from them on the things that they got right, so Wasmer and its community can benefit from a solid
 foundation.
 
 These are the different project that we used as inspiration:
 
 - [Nebulet](https://github.com/nebulet/nebulet): as the base for creating a great Rust WebAssembly runtime
 - [WAVM](https://github.com/wavm/wavm): for their great integration and testing framework
 - [greenwasm](https://github.com/Kimundi/greenwasm): for their [spectests framework](https://github.com/Kimundi/greenwasm/tree/master/greenwasm-spectest)
-- [wasmtime](/wasmtime): on their [mmap implementation](https://github.com/CraneStation/wasmtime/blob/3f24098edc81cd9bf0f877fb7fba018cad0f039e/lib/runtime/src/mmap.rs).
-- [stackoverflow](https://stackoverflow.com/a/45795699/1072990): to create an efficient HashMap with pair keys.
-- [Emscripten](https://github.com/kripken/emscripten): for emtests test sources to ensure compatibility.
+- [wasmtime](https://github.com/CraneStation/wasmtime): for their [mmap implementation](https://github.com/CraneStation/wasmtime/blob/3f24098edc81cd9bf0f877fb7fba018cad0f039e/lib/runtime/src/mmap.rs)
+- [stackoverflow](https://stackoverflow.com/a/45795699/1072990): to create an efficient HashMap with pair keys
+- [Emscripten](https://github.com/kripken/emscripten): for emtests test sources to ensure compatibility
 
 We would love to hear from you if you think we can take inspiration from other projects that we haven't covered here.
 😊
@@ -21,10 +21,10 @@ We would love to hear from you if you think we can take inspiration from other p
 
 ### Nebulet
 
-```
+```text
 MIT License
 
-Copyright (c) 2018 
+Copyright (c) 2018
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -47,7 +47,7 @@ SOFTWARE.
 
 ### WAVM
 
-```
+```text
 Copyright (c) 2018, Andrew Scheidecker
 All rights reserved.
 
@@ -69,7 +69,7 @@ The contents of [Test/spec](Test/spec) is covered by the license in [Test/spec/L
 
 ### Greenwasm
 
-```
+```text
                               Apache License
                         Version 2.0, January 2004
                      http://www.apache.org/licenses/
@@ -275,7 +275,7 @@ limitations under the License.
 
 ### Wasmtime
 
-```
+```text
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -497,7 +497,7 @@ Software.
 ```
 
 ### Emscripten
-```
+```text
 Emscripten is available under 2 licenses, the MIT license and the
 University of Illinois/NCSA Open Source License.
 
@@ -557,7 +557,7 @@ the following conditions:
     Neither the names of Mozilla,
     nor the names of its contributors may be used to endorse
     or promote products derived from this Software without specific prior
-    written permission. 
+    written permission.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

LICENSE

@@ -1,6 +1,4 @@
-The MIT License (MIT)
-
-Copyright (c) 2018-Present Syrus Akbary
+Copyright (c) 2019 Syrus Akbary
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,51 +1,59 @@
-<p align="center"><a href="https://wasmer.io" target="_blank" rel="noopener noreferrer"><img width="400" src="https://raw.githubusercontent.com/wasmerio/wasmer/master/logo.png" alt="Wasmer logo"></a></p>
+<p align="center">
+  <a href="https://wasmer.io" target="_blank" rel="noopener noreferrer">
+    <img width="400" src="https://raw.githubusercontent.com/wasmerio/wasmer/master/logo.png" alt="Wasmer logo">
+  </a>
+</p>
 
 <p align="center">
-  <a href="https://circleci.com/gh/wasmerio/wasmer/"><img src="https://img.shields.io/circleci/project/github/wasmerio/wasmer/master.svg" alt="Build Status"></a>
-  <a href="https://github.com/wasmerio/wasmer/blob/master/LICENSE"><img src="https://img.shields.io/github/license/wasmerio/wasmer.svg" alt="License"></a>
+  <a href="https://circleci.com/gh/wasmerio/wasmer/">
+    <img src="https://img.shields.io/circleci/project/github/wasmerio/wasmer/master.svg" alt="Build Status">
+  </a>
+  <a href="https://github.com/wasmerio/wasmer/blob/master/LICENSE">
+    <img src="https://img.shields.io/github/license/wasmerio/wasmer.svg" alt="License">
+  </a>
   <a href="https://spectrum.chat/wasmer">
-    <img alt="Join the Wasmer Community" src="https://withspectrum.github.io/badge/badge.svg" />
+    <img src="https://withspectrum.github.io/badge/badge.svg" alt="Join the Wasmer Community">
   </a>
 </p>
 
 ## Introduction
 
-[Wasmer](https://wasmer.io/) is a Standalone JIT WebAssembly runtime, aiming to be fully compatible with Emscripten, Rust and Go.
+[Wasmer](https://wasmer.io/) is a standalone JIT WebAssembly runtime, aiming to be fully compatible with Emscripten, Rust and Go.
 
 Install Wasmer with:
 
 ```sh
 curl https://get.wasmer.io -sSfL | sh
 ```
 
-_**NEW ✨**: Now you can also embed Wasmer in your Rust application, check our [example repo](https://github.com/wasmerio/wasmer-rust-example) to see how to do it!_
+_**NEW ✨**: You can now embed Wasmer in your Rust application, check our [example repo](https://github.com/wasmerio/wasmer-rust-example) to see how!_
 
 ### Usage
 
-`wasmer` can execute both the standard binary format (`.wasm`) and the text
+Wasmer can execute both the standard binary format (`.wasm`) and the text
 format defined by the WebAssembly reference interpreter (`.wat`).
 
-Once installed, you will be able to run any WebAssembly files (_including Nginx, and Lua!_):
+Once installed, you will be able to run any WebAssembly files (_including nginx and Lua!_):
 
 ```sh
 # Run Lua
 wasmer run examples/lua.wasm
 
-# Run Nginx
+# Run nginx
 wasmer run examples/nginx/nginx.wasm -- -p examples/nginx -c nginx.conf
 ```
 
 ## Code Structure
 
 Wasmer is structured into different directories:
 
-- [`src`](./src): code related to the wasmer excutable binary itself
+- [`src`](./src): code related to the Wasmer executable itself
 - [`lib`](./lib): modularized libraries that Wasmer uses under the hood
-- [`examples`](./examples): some useful examples to getting started with wasmer
+- [`examples`](./examples): some useful examples to getting started with Wasmer
 
 ## Dependencies
 
-Building wasmer requires [rustup](https://rustup.rs/).
+Building Wasmer requires [rustup](https://rustup.rs/).
 
 To build on Windows, download and run [`rustup-init.exe`](https://win.rustup.rs/)
 then follow the onscreen instructions.
@@ -66,13 +74,13 @@ Please select your operating system:
 
 #### macOS
 
-If you have [homebrew](https://brew.sh/) installed:
+If you have [Homebrew](https://brew.sh/) installed:
 
 ```sh
 brew install cmake
 ```
 
-Or, in case you have [ports](https://www.macports.org/install.php):
+Or, in case you have [MacPorts](https://www.macports.org/install.php):
 
 ```sh
 sudo port install cmake
@@ -86,16 +94,16 @@ sudo apt install cmake
 
 #### Windows (MSVC)
 
-Windows support is _highly experimental_. Only simple wasm programs may be run, and no syscalls are allowed. This means
-nginx and lua do not work on Windows. See [this issue for ongoing Emscripten syscall polyfills for Windows](https://github.com/wasmerio/wasmer/pull/176).
+Windows support is _highly experimental_. Only simple Wasm programs may be run, and no syscalls are allowed. This means
+nginx and Lua do not work on Windows. See [this issue](https://github.com/wasmerio/wasmer/issues/176) regarding Emscripten syscall polyfills for Windows.
 
-1. Install Python for Windows (https://www.python.org/downloads/release/python-2714/). The Windows x86-64 MSI installer is fine.
-   You should change the installation to install the "Add python.exe to Path" feature.
+1. Install [Python for Windows](https://www.python.org/downloads/release/python-2714/). The Windows x86-64 MSI installer is fine.
+   Make sure to enable "Add python.exe to Path" during installation.
 
-2. Install Git for Windows (https://git-scm.com/download/win). DO allow it to add git.exe to the PATH (default
+2. Install [Git for Windows](https://git-scm.com/download/win). Allow it to add `git.exe` to your PATH (default
    settings for the installer are fine).
 
-3. Install CMake (https://cmake.org/download/). Ensure CMake is in the PATH.
+3. Install [CMake](https://cmake.org/download/). Ensure CMake is in your PATH.
 
 ## Building
 
@@ -113,15 +121,15 @@ cargo install --path .
 
 ## Testing
 
-Thanks to [spectests](https://github.com/wasmerio/wasmer/tree/master/lib/runtime-core/spectests) we can assure 100% compatibility with the WebAssembly spec test suite.
+Thanks to [spec tests](https://github.com/wasmerio/wasmer/tree/master/lib/spectests/spectests) we can ensure 100% compatibility with the WebAssembly spec test suite.
 
 Tests can be run with:
 
 ```sh
 make test
 ```
 
-If you need to re-generate the Rust tests from the spectests
+If you need to regenerate the Rust tests from the spec tests
 you can run:
 
 ```sh
@@ -138,20 +146,20 @@ make integration-tests
 
 Wasmer is an open project guided by strong principles, aiming to be modular, flexible and fast. It is open to the community to help set its direction.
 
-Below are some of the goals (written with order) of this project:
+Below are some of the goals of this project (in order of priority):
 
-- [x] It should be 100% compatible with the [WebAssembly Spectest](https://github.com/wasmerio/wasmer/tree/master/spectests)
+- [x] It should be 100% compatible with the [WebAssembly spec tests](https://github.com/wasmerio/wasmer/tree/master/lib/spectests/spectests)
 - [x] It should be fast _(partially achieved)_
 - [ ] Support Emscripten calls _(in the works)_
 - [ ] Support Rust ABI calls
-- [ ] Support GO ABI calls
+- [ ] Support Go ABI calls
 
 ## Architecture
 
-If you would like to know how Wasmer works under the hood, please visit our [ARCHITECTURE](https://github.com/wasmerio/wasmer/blob/master/ARCHITECTURE.md) document.
+If you would like to know how Wasmer works under the hood, please see [ARCHITECTURE.md](./ARCHITECTURE.md).
 
 ## License
 
-MIT/Apache-2.0
+Wasmer is primarily distributed under the terms of the [MIT license](http://opensource.org/licenses/MIT) ([LICENSE](./LICENSE)).
 
-<small>[Attributions](./ATTRIBUTIONS.md)</small>.
+[ATTRIBUTIONS](./ATTRIBUTIONS.md)

integration_tests/lua/README.md

@@ -1,8 +1,8 @@
 # `lua` integration test
 
 
-This starts wasmer with the lua wasm file. The test asserts on
-the output of wasmer. Run test with: 
+This starts Wasmer with the Lua Wasm file. The test makes assertions on
+the output of Wasmer. Run test with:
 
 ```
 > ./integration_tests/lua/test.sh

integration_tests/nginx/README.md

@@ -1,11 +1,11 @@
 # `nginx` integration test
 
 
-This starts wasmer with the nginx wasm file and serves an html
-file with some simple text to assert on. The test script does 
+This starts Wasmer with the nginx Wasm file and serves an HTML
+file with some simple text to assert on. The test script does
 the assertion.
 
-Run test with: 
+Run test with:
 
 ```
 > ./integration_tests/nginx/test.sh

lib/README.md

@@ -2,34 +2,34 @@
 
 Wasmer is modularized into different libraries, separated into three main sections:
 
-- [Runtime](#Runtime)
-- [Integrations](#Integrations)
-- [Backends](#Backends)
+- [Runtime](#runtime)
+- [Integrations](#integrations)
+- [Backends](#backends)
 
 ## Runtime
 
 The core of Wasmer is the runtime, which provides the necessary
-abstractions to create a good user-experience when embedding.
+abstractions to create a good user experience when embedding.
 
 The runtime is divided into two main libraries:
 
 - [runtime-core](./runtime-core/): The main implementation of the runtime.
-- [runtime](./runtime/): Easy-to-use api on top of runtime-core.
+- [runtime](./runtime/): Easy-to-use API on top of `runtime-core`.
 
 ## Integrations
 
-The intergration run on-top of the Wasmer runtime and allow us to run WebAssembly files compiled for different environments.
+The integration builds on the Wasmer runtime and allow us to run WebAssembly files compiled for different environments.
 
 Wasmer intends to support different integrations:
 
-- [emscripten](./emscripten): run emscripten-generated WebAssembly files, such as [Lua](../examples/lua.wasm) or [Nginx](../examples/nginx/nginx.wasm).
+- [emscripten](./emscripten): run Emscripten-generated WebAssembly files, such as [Lua](../examples/lua.wasm) or [nginx](../examples/nginx/nginx.wasm).
 - Go ABI: _we will work on this soon! Want to give us a hand? ✋_
-- Blazor: _researching period, see [tracking issue](https://github.com/wasmerio/wasmer/issues/97)_
+- Blazor: _research period, see [tracking issue](https://github.com/wasmerio/wasmer/issues/97)_
 
 ## Backends
 
 The Wasmer [runtime](./runtime) is designed to support multiple compiler backends, allowing the user
-to tune the codegen properties (compile speed, performance, etc) to fit your usecase best.
+to tune the codegen properties (compile speed, performance, etc) to best fit their use case.
 
 Currently, we support a Cranelift compiler backend: