Merge branch 'stable'

CONTRIBUTING.md

@@ -336,7 +336,7 @@ entry and
 [documentation](https://github.com/commercialhaskell/stack/tree/master/doc/)
 updates with your pull request.
 
-## Backwards Compatability
+## Backwards Compatibility
 
 The Stack package provides a library and an executable (`stack`) that depends on
 the library. The library is intended for use only by the executable.
@@ -482,7 +482,7 @@ That said, the following may help:
 * Stack's imports are listed alphabetically, including `Stack.Prelude`, where
   applicable. The module names are left aligned, with space left for `qualified`
   where it is absent.
-* Stack's code is sufficiently stable that explict import lists can sensibly be
+* Stack's code is sufficiently stable that explicit import lists can sensibly be
   used. The exception is the import of `Stack.Prelude`. Not all modules have
   comprehensive explicit import lists.
 * Short explicit import lists follow the module name. Longer lists start on the

doc/commands/build_command.md

@@ -623,6 +623,11 @@ command line arguments. For example, to pass `'a single quoted string'`:
     The content of single quotes is taken literally. Within single quotes, `''`
     escapes a single quote.
 
+!!! note "Runtime system (RTS) options"
+
+    RTS options must be quoted to prevent the RTS extracting them as its own
+    when the Stack executable is run.
+
 ### `--exec` option
 
 `stack build --exec '<command> [<argument(s)>]'` will run the specified command
@@ -719,6 +724,11 @@ command line arguments. For example, to pass `'a single quoted string'`:
     The content of single quotes is taken literally. Within single quotes, `''`
     escapes a single quote.
 
+!!! note "Runtime system (RTS) options"
+
+    RTS options must be quoted to prevent the RTS extracting them as its own
+    when the Stack executable is run.
+
 ## Flags affecting GHC's behaviour
 
 ### `--[no-]executable-profiling` flag

doc/commands/index.md

@@ -10,6 +10,36 @@ of the guide and the part on [configuration](../configure/index.md) provide
 information about some of those features, organised as a reference guide. Some
 of the features are complex and separate pages are dedicated to them.
 
+## stack command
+
+Stack is usually used with one of its commands (see further below). However:
+
+* `stack`, `stack --help` (or `-h`) lists Stack's commands, and flags and
+  options common to those commands;
+
+* `stack <command> --help` (or `-h`) — provides help on the particular Stack
+  command, including flags and options specific to the command; and
+
+* `stack --version` identifies the version and Git hash of the Stack executable.
+
+!!! info "Runtime system (RTS) options"
+
+    The Stack executable is built by GHC with the `-rtsopts=some` option. This
+    means that the RTS extracts command-line arguments bracketed between `+RTS`
+    and `-RTS` as its own when Stack is run. Only the following RTS
+    options are available:
+
+    *   `-?` (e.g. `stack +RTS -?`) causes the RTS to output information about
+        RTS options; and
+
+    *   `--info` (e.g. `stack +RTS --info`) causes the RTS to output information
+        about the RTS.
+
+    To avoid the RTS extracting such command-line arguments as its own when
+    using Stack commands such as [`exec`](exec_command.md),
+    [`test`](test_command.md) or [`bench`](bench_command.md), see the
+    documentation for those commands.
+
 ## Stack commands (thematic)
 
 ### Setting up

doc/maintainers/releases.md

@@ -67,7 +67,7 @@ Examples:
 
 4.  Check the copyright dates, and update if needed.
 
-5.  Check the backwards compatability section of `CONTRIBUTING.md` is up to
+5.  Check the backwards compatibility section of `CONTRIBUTING.md` is up to
     date.
 
 6.  Ensure CI matrices in docs (travis-complex, appveyor, azure) have current