Tweak readmes

CONTRIBUTING.md

@@ -0,0 +1 @@
+docs/section-6-contributing.md

README.md

@@ -5,9 +5,14 @@
 
 Tree-sitter is a parser generator tool and an incremental parsing library. It can build a concrete syntax tree for a source file and efficiently update the syntax tree as the source file is edited. Tree-sitter aims to be:
 
-* **General** enough to parse any programming language
-* **Fast** enough to parse on every keystroke in a text editor
-* **Robust** enough to provide useful results even in the presence of syntax errors
-* **Dependency-free** so that the runtime library (which is written in pure C) can be embedded in any application
+- **General** enough to parse any programming language
+- **Fast** enough to parse on every keystroke in a text editor
+- **Robust** enough to provide useful results even in the presence of syntax errors
+- **Dependency-free** so that the runtime library (which is written in pure C) can be embedded in any application
 
-[Documentation](https://tree-sitter.github.io/tree-sitter/)
+## Links
+
+- [Documentation](https://tree-sitter.github.io)
+- [Rust binding](lib/binding_rust/README.md)
+- [WASM binding](lib/binding_web/README.md)
+- [Command-line interface](cli/README.md)

docs/section-6-contributing.md

@@ -18,7 +18,7 @@ To make changes to Tree-sitter, you should have:
 1. A C compiler, for compiling the core library and the generated parsers.
 2. A [Rust toolchain](https://rustup.rs/), for compiling the Rust bindings, the highlighting library, and the CLI.
 3. Node.js and NPM, for generating parsers from `grammar.js` files.
-4. Either [Docker](https://www.docker.com/) or [Emscripten](https://emscripten.org/), for compiling the library to WASM.
+4. Either [Emscripten](https://emscripten.org/) or [Docker](https://www.docker.com/), for compiling the library to WASM.
 
 ### Building
 
@@ -86,7 +86,7 @@ You can run the tests under the debugger (either `lldb` or `gdb`) using the `-g`
 script/test test_does_something -g
 ```
 
-Part of the Tree-sitter test suite involves parsing the *corpus* tests for several different languages and performing randomized edits to each example in the corpus. If you just want to run the tests for a particular *language*, you can pass the `-l` flag. And if you want to run a particular *example* from the corpus, you can pass the `-e` flag:
+Part of the Tree-sitter test suite involves parsing the _corpus_ tests for several different languages and performing randomized edits to each example in the corpus. If you just want to run the tests for a particular _language_, you can pass the `-l` flag. And if you want to run a particular _example_ from the corpus, you can pass the `-e` flag:
 
 ```sh
 script/test -l javascript -e Arrays
@@ -96,18 +96,18 @@ script/test -l javascript -e Arrays
 
 The main [`tree-sitter/tree-sitter`](https://github.com/tree-sitter/tree-sitter) repository contains the source code for several packages that are published to package registries for different languages:
 
-* Rust crates on [crates.io](https://crates.io):
-  * [`tree-sitter`](https://crates.io/crates/tree-sitter) - A Rust binding to the core library
-  * [`tree-sitter-highlight`](https://crates.io/crates/tree-sitter-highlight) - The syntax-highlighting library
-  * [`tree-sitter-cli`](https://crates.io/crates/tree-sitter-cli) - The command-line tool
-* JavaScript modules on [npmjs.com](https://npmjs.com):
-  * [`web-tree-sitter`](https://www.npmjs.com/package/web-tree-sitter) - A WASM-based JavaScript binding to the core library
-  * [`tree-sitter-cli`](https://www.npmjs.com/package/tree-sitter-cli) - The command-line tool
+- Rust crates on [crates.io](https://crates.io):
+  - [`tree-sitter`](https://crates.io/crates/tree-sitter) - A Rust binding to the core library
+  - [`tree-sitter-highlight`](https://crates.io/crates/tree-sitter-highlight) - The syntax-highlighting library
+  - [`tree-sitter-cli`](https://crates.io/crates/tree-sitter-cli) - The command-line tool
+- JavaScript modules on [npmjs.com](https://npmjs.com):
+  - [`web-tree-sitter`](https://www.npmjs.com/package/web-tree-sitter) - A WASM-based JavaScript binding to the core library
+  - [`tree-sitter-cli`](https://www.npmjs.com/package/tree-sitter-cli) - The command-line tool
 
 There are also several other dependent repositories that contain other published packages:
 
-* [`tree-sitter/node-tree-sitter`](https://github.com/tree-sitter/py-tree-sitter) - Node.js bindings to the core library, published as [`tree-sitter`](https://www.npmjs.com/package/tree-sitter) on npmjs.com
-* [`tree-sitter/py-tree-sitter`](https://github.com/tree-sitter/py-tree-sitter) - Python bindings to the core library, published as [`tree-sitter`](https://pypi.org/project/tree-sitter) on [PyPI.org](https://pypi.org).
+- [`tree-sitter/node-tree-sitter`](https://github.com/tree-sitter/py-tree-sitter) - Node.js bindings to the core library, published as [`tree-sitter`](https://www.npmjs.com/package/tree-sitter) on npmjs.com
+- [`tree-sitter/py-tree-sitter`](https://github.com/tree-sitter/py-tree-sitter) - Python bindings to the core library, published as [`tree-sitter`](https://pypi.org/project/tree-sitter) on [PyPI.org](https://pypi.org).
 
 ## Publishing New Releases
 
@@ -115,31 +115,31 @@ Publishing a new release of the CLI requires these steps:
 
 1. Commit and push all outstanding changes and verify that CI passes:
 
-    ```sh
-    git commit -m "Fix things"
-    git push
-    ```
+   ```sh
+   git commit -m "Fix things"
+   git push
+   ```
 
 2. Create a new tag:
 
-    ```sh
-    script/version patch
-    ```
+   ```sh
+   script/version patch
+   ```
 
-    This will determine the current version, increment the *patch* version number, and update the `Cargo.toml` and `package.json` files for the Rust and Node CLI packages. It will then create a commit and a tag for the new version. For more information about the arguments that are allowed, see the documentation for the [`npm version`](https://docs.npmjs.com/cli/version) command.
+   This will determine the current version, increment the _patch_ version number, and update the `Cargo.toml` and `package.json` files for the Rust and Node CLI packages. It will then create a commit and a tag for the new version. For more information about the arguments that are allowed, see the documentation for the [`npm version`](https://docs.npmjs.com/cli/version) command.
 
 3. Push the commit and the tag:
 
-    ```sh
-    git push
-    git push --tags
-    ```
+   ```sh
+   git push
+   git push --tags
+   ```
 
 4. Wait for CI to pass. Because of the git tag, the CI jobs will publish artifacts to [a GitHub release](https://github.com/tree-sitter/tree-sitter/releases). The npm module of `tree-sitter-cli` works by downloading the appropriate binary from the corresponding GitHub release during installation. So it's best not to publish the npm package until the binaries are uploaded.
 
 5. Publish the npm package:
 
-    ```sh
-    cd cli/npm
-    npm publish
-    ```
+   ```sh
+   cd cli/npm
+   npm publish
+   ```

lib/binding_rust/README.md

@@ -1,5 +1,4 @@
-Rust Tree-sitter
-================
+# Rust Tree-sitter
 
 [![Build Status](https://travis-ci.org/tree-sitter/tree-sitter.svg?branch=master)](https://travis-ci.org/tree-sitter/tree-sitter)
 [![Build status](https://ci.appveyor.com/api/projects/status/vtmbd6i92e97l55w/branch/master?svg=true)](https://ci.appveyor.com/project/maxbrunsfeld/tree-sitter/branch/master)
@@ -14,15 +13,12 @@ First, create a parser:
 ```rust
 use tree_sitter::{Parser, Language};
 
-// ...
-
 let mut parser = Parser::new();
 ```
 
 Tree-sitter languages consist of generated C code. To make sure they're properly compiled and linked, you can create a [build script](https://doc.rust-lang.org/cargo/reference/build-scripts.html) like the following (assuming `tree-sitter-javascript` is in your root directory):
-```rust
-extern crate cc;
 
+```rust
 use std::path::PathBuf;
 
 fn main() {
@@ -37,12 +33,13 @@ fn main() {
 ```
 
 Add the `cc` crate to your `Cargo.toml` under `[build-dependencies]`:
+
 ```toml
 [build-dependencies]
 cc="*"
 ```
 
-To then use languages from rust, you must declare them as `extern "C"` functions and invoke them with `unsafe`. Then you can assign them to the parser. 
+To then use languages from rust, you must declare them as `extern "C"` functions and invoke them with `unsafe`. Then you can assign them to the parser.
 
 ```rust
 extern "C" { fn tree_sitter_c() -> Language; }