Add some notes on usage, and re-arrange things.

README.md

@@ -15,6 +15,73 @@ In other words, this plugin allows you to lint while you type.
 and is still in rapid development. Documentation and stable APIs will
 follow later.
 
+## Supported Languages and Tools
+
+This plugin supports the following languages and tools. All available
+tools will be run in combination, so they can be complementary.
+
+<!--
+Keep the table rows sorted alphabetically by the language name,
+and the tools in the tools column sorted alphabetically by the tool
+name. That seems to be the fairest way to arrange this table.
+-->
+
+| Language | Tools |
+| -------- | ----- |
+| Bash | [-n flag](https://www.gnu.org/software/bash/manual/bash.html#index-set) |
+| Bourne Shell | [-n flag](http://linux.die.net/man/1/sh) |
+| C | [gcc](https://gcc.gnu.org/) |
+| D | [dmd](https://dlang.org/dmd-linux.html)^ |
+| Fortran | [gcc](https://gcc.gnu.org/) |
+| Haskell | [ghc](https://www.haskell.org/ghc/)^ |
+| JavaScript | [eslint](http://eslint.org/), [jscs](http://jscs.info/), [jshint](http://jshint.com/) |
+| Python | [flake8](http://flake8.pycqa.org/en/latest/) |
+| Ruby   | [rubocop](https://github.com/bbatsov/rubocop) |
+
+*^ Supported only on Unix machines via a wrapper script.*
+
+If you would like to see support for more languages and tools, please
+[create an issue](https://github.com/w0rp/ale/issues)
+or [create a pull request](https://github.com/w0rp/ale/pulls).
+If your tool can read from stdin or you have code to suggest which is good,
+support can be happily added for more tools.
+
+## Usage
+
+Once this plugin is installed, while editing your files in supported
+languages and tools which have been correctly installed,
+this plugin will send the contents of your text buffers to a variety of
+programs for checking the syntax and semantics of your programs. By default,
+linters will be re-run in the background to check your syntax when you open
+new buffers or as you make edits to your files.
+
+This plugin offers a variety of global flags for turning options on or off,
+all of which are given defaults and described in the [flags](plugin/ale/aaflags.vim)
+file. Linting on open, setting of signs, populating the loclist, and so forth may
+all be configured as desired.
+
+### Selecting Particular Linters
+
+By default, all available tools for all supported languages will be run.
+If you want to only select a subset of the tools, simply create a
+`g:ale_linters` dictionary in your vimrc file mapping filetypes
+to lists of linters to run.
+
+```vim
+let g:ale_linters = {
+\   'javascript': ['eslint'],
+\}
+```
+
+For all languages unspecified in the dictionary, all possible linters will
+be run for those languages, just as when the dictionary is not defined.
+Running many linters should not typically obstruct editing in Vim,
+as they will all be executed in separate processes simultaneously.
+
+This plugin will look for linters in the [`ale_linters`](ale_linters) directory.
+Each directory within corresponds to a particular filetype in Vim, and each file
+in each directory corresponds to the name of a particular linter.
+
 ## Installation
 
 To install this plugin, you should use one of the following methods.
@@ -46,7 +113,7 @@ Plugin 'https://github.com/w0rp/ale.git'
 
 See the Vundle documentation for more information.
 
-### Installation manually
+### Manual Installation
 
 For installation without a package manager, you can clone this git repository
 into a bundle directory as with pathogen, and add the repository to your
@@ -70,34 +137,3 @@ filetype plugin on
 
 Because the author of this plugin is a weird nerd, this is his preferred
 installation method.
-
-## Supported Languages and Tools
-
-This plugin supports the following languages and tools. All available
-tools will be run in combination, so they can be complementary.
-
-<!--
-Keep the table rows sorted alphabetically by the language name,
-and the tools in the tools column sorted alphabetically by the tool
-name. That seems to be the fairest way to arrange this table.
--->
-
-| Language | Tools |
-| -------- | ----- |
-| Bash | [-n flag](https://www.gnu.org/software/bash/manual/bash.html#index-set) |
-| Bourne Shell | [-n flag](http://linux.die.net/man/1/sh) |
-| C | [gcc](https://gcc.gnu.org/) |
-| D | [dmd](https://dlang.org/dmd-linux.html)^ |
-| Fortran | [gcc](https://gcc.gnu.org/) |
-| Haskell | [ghc](https://www.haskell.org/ghc/)^ |
-| JavaScript | [eslint](http://eslint.org/), [jscs](http://jscs.info/), [jshint](http://jshint.com/) |
-| Python | [flake8](http://flake8.pycqa.org/en/latest/) |
-| Ruby   | [rubocop](https://github.com/bbatsov/rubocop) |
-
-*^ Supported only on Unix machines via a wrapper script.*
-
-If you would like to see support for more languages and tools, please
-[create an issue](https://github.com/w0rp/ale/issues)
-or [create a pull request](https://github.com/w0rp/ale/pulls).
-If your tool can read from stdin or you have code to suggest which is good,
-support can be happily added for more tools.