Expand README to include more information about features (#358)

1 files changed, 101 insertions, 44 deletions

diff --git a/README.md b/README.md
index d78ac28..54702d3 100644
--- a/README.md
+++ b/README.md
@@ -1,30 +1,47 @@
 [![MELPA](https://melpa.org/packages/rust-mode-badge.svg)](https://melpa.org/#/rust-mode)
 
-# Emacs mode for editing Rust source code
-
 <!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
 **Table of Contents**
 
+- [Introduction](#introduction)
 - [Installation](#installation)
     - [Melpa](#melpa)
-    - [straight](#straight)
-    - [Manual Installation](#manual-installation)
-- [Indentation](#indentation)
-- [rustfmt](#rustfmt)
-- [Tests](#tests)
-- [LSP](#lsp)
-    - [eglot](#eglot)
-    - [lsp-mode](#lsp-mode)
-- [Other useful packages](#other-useful-packages)
+    - [Manual installation](#manual-installation)
+- [Feature guide](#feature-guide)
+    - [Indentation](#indentation)
+    - [Code formatting](#code-formatting)
+    - [Running / testing / compiling code](#running--testing--compiling-code)
+    - [Clippy](#clippy)
+    - [Easy insertion of !dbg](#easy-insertion-of-dbg)
+- [Other recommended packages](#other-recommended-packages)
+    - [Auto-completion / code navigation](#auto-completion--code-navigation)
+    - [flycheck](#flycheck)
+    - [cargo.el](#cargoel)
+    - [Rustic](#rustic)
+- [For package maintainers](#for-package-maintainers)
+    - [Tests](#tests)
 
 <!-- markdown-toc end -->
 
+# Introduction
+`rust-mode` makes editing [Rust](http://rust-lang.org) code with Emacs
+enjoyable. It requires Emacs 24 or later, and is include in both
+[Emacs Prelude](https://github.com/bbatsov/prelude) and
+[Spacemacs](https://github.com/syl20bnr/spacemacs) by default.
+
+This mode provides:
+- Syntax highlighting (for Font Lock Mode)
+- Indentation
+- Integration with Cargo, clippy and rustfmt
+
+This mode does _not_ provide autocompletion, or jumping to function /
+trait definitions. See [Integration with Rust Language Server](#rust-language-server)
+below for tips on how to enable this.
+
+
 # Installation
 
 ## Melpa
-
-`rust-mode` makes editing [Rust](http://rust-lang.org) code with Emacs
-enjoyable. It requires Emacs 24 or later.
 The package is available on MELPA. Add this to your init.el.
 
 ``` elisp
@@ -43,60 +60,100 @@ And put this in your config to load rust-mode automatically:
 
 `(require 'rust-mode)`
 
-## straight
-
-[straight.el](https://github.com/raxod502/straight.el#install-packages) clones each of your packages directly from its source. There are good additional [installation instructions](https://github.crookster.org/switching-to-straight.el-from-emacs-26-builtin-package.el/) for moving your package management from package.el to straight.
-
-## Manual Installation
-
-Add this to your init.el:
+## Manual installation
+Clone this repository locally, and add this to your init.el:
 
 ``` elisp
 (add-to-list 'load-path "/path/to/rust-mode/")
 (autoload 'rust-mode "rust-mode" nil t)
 ```
 
-# Indentation
+# Feature guide
+## Indentation
+Commands like <TAB> should indent correctly.
 
-The Rust style guide recommends spaces for indentation; to follow the
-recommendation add this to your init.el:
+The Rust style guide recommends spaces rather than tabs for
+indentation; to follow the recommendation add this to your init.el,
+which forces indentation to always use spaces.
 
 ```elisp
 (add-hook 'rust-mode-hook
           (lambda () (setq indent-tabs-mode nil)))
 ```
 
-# rustfmt
+## Code formatting
 
 The `rust-format-buffer` function will format your code with
-[rustfmt](https://github.com/rust-lang/rustfmt) if installed. By default,
-this is bound to `C-c C-f`.
+[rustfmt](https://github.com/rust-lang/rustfmt) if installed. By
+default, this is bound to `C-c C-f`.
 
-Placing `(setq rust-format-on-save t)` in your init.el will enable automatic
-running of `rust-format-buffer` when you save a buffer.
+The variable `rust-format-on-save` enables automatic formatting on
+save. For example, add the following in your init.el to enable format
+on save:
 
-# Tests
+``` elisp
+(setq rust-format-on-save t)
+```
 
-The file `rust-mode-tests.el` contains tests that can be run via
-[ERT](http://www.gnu.org/software/emacs/manual/html_node/ert/index.html).
-You can use `run_rust_emacs_tests.sh` to run them in batch mode, if
-you set the environment variable EMACS to a program that runs emacs.
+## Running / testing / compiling code
+
+The `rust-run`, `rust-test` and `rust-build` functions shell out to
+Cargo to run, test or build your code. Under the hood, these use the
+standard Emacs `compile` function.
+
+These are not bound by default. To bind these to keyboard shortcuts,
+you can use the following in your init.el:
+
+``` elisp
+(define-key rust-mode-map (kbd "C-c C-c") 'rust-run)
+```
+
+## Clippy
+`rust-run-clippy` runs
+[Clippy](https://github.com/rust-lang/rust-clippy), a linter. 
+
+## Easy insertion of !dbg
+`rust-dbg-wrap-or-unwrap` either wraps or unwraps the current region
+in `dbg!`. This can be useful for easily adding debug lines to your
+program.
 
-# LSP
+This is bound to `C-c C-d` by default.
 
-## eglot
 
-[Installation instructions](https://github.com/joaotavora/eglot#connecting-automatically) 
+# Other recommended packages
 
-## lsp-mode
+## Auto-completion / code navigation
+This package does not provide integration with
+[RLS](https://github.com/rust-lang/rls), which provides
+auto-completion and code navigation. To use this you need an Emacs
+package that supports LSP.
 
-[Installation instructions](https://github.com/emacs-lsp/lsp-mode#installation)
+Two examples are:
+- [LSP](https://github.com/emacs-lsp/lsp-mode)
+- [eglot](https://github.com/joaotavora/eglot)
 
+A lighter package that uses
+[racer](https://github.com/racer-rust/racer) is
+[emacs-racer](https://github.com/racer-rust/emacs-racer).
 
-You can find more information in the [lsp-mode wiki](https://github.com/emacs-lsp/lsp-mode/wiki/Rust).
+## flycheck
+[flycheck](https://github.com/flycheck/flycheck) allows highlighting
+compile errors and Clippy lints inline.
 
-# Other useful packages
+## cargo.el
+[cargo.el](https://github.com/kwrooijen/cargo.el) provides a minor
+mode for integration with Cargo, Rust's package manager.
 
-* [cargo.el](https://github.com/kwrooijen/cargo.el) Emacs Minor Mode for Cargo, Rust's Package Manager
-* [emacs-racer](https://github.com/racer-rust/emacs-racer) Racer support for Emacs
-* [rustic](https://github.com/brotzeit/rustic) Rust development environment for Emacs
+## Rustic
+[rustic](https://github.com/brotzeit/rustic) is a fork of rust-mode,
+extending it with other features such as integration with LSP and with flycheck.
+
+
+# For package maintainers
+
+## Tests
+
+The file `rust-mode-tests.el` contains tests that can be run via
+[ERT](http://www.gnu.org/software/emacs/manual/html_node/ert/index.html).
+You can use `run_rust_emacs_tests.sh` to run them in batch mode, if
+you set the environment variable EMACS to a program that runs emacs.