Conform format of online documentation

Author: mpilgrem

doc/run_command.md

@@ -17,19 +17,21 @@ Everything after `--` on the command line is interpreted as a command line
 argument to be passed to what is run, other than a first argument recognised as
 an executable target.
 
-By default, the `GHC_PACKAGE_PATH` environment variable is set for the
-subprocess. Pass the `--no-ghc-package-path` flag to not set the variable.
+By default:
 
-By default, the `STACK_EXE` environment variable is set with the path to Stack.
-Pass the `--no-stack-exe` flag to not set the variable.
+*   the `GHC_PACKAGE_PATH` environment variable is set for the subprocess. Pass
+    the `--no-ghc-package-path` flag to not set the variable; and
+
+*   the `STACK_EXE` environment variable is set with the path to Stack. Pass the
+    `--no-stack-exe` flag to not set the variable.
 
 The `--cwd` option can be used to set the working directory before the
 executable is run.
 
+The `--package` option (which can be specified multiple times) can be used to
+add a package name to build targets.
+
 The `--rts-options` option (which can be specified multiple times) can be used
 to pass a list of GHC's
 [runtime system (RTS) options](https://downloads.haskell.org/~ghc/latest/docs/users_guide/runtime_control.html#)
 to the executable when it is run. (The `+RTS` and `-RTS` must not be included.)
-
-The `--package` option (which can be specified multiple times) can be used to
-add a package name to build targets.

doc/unpack_command.md

@@ -8,4 +8,12 @@ stack unpack PACKAGE [--to ARG]
 
 `stack unpack` downloads a tarball for the specified package and unpacks it.
 
-Pass the option `--to <directory>` to specify the destination directory.
+By default:
+
+*   the download is for the most recent version of the package in the package
+    index (eg Hackage). Specify the package name and its version (for example,
+    `acme-missiles-0.1.0.0`) for a particular version of the package; and
+
+*   the package is unpacked into a directory named after the package and its
+    version. Pass the option `--to <directory>` to specify the destination
+    directory.

doc/upgrade_command.md

@@ -20,5 +20,8 @@ binary distribution (pass the `--binary-only` flag, the default) or from
 compiling source code (pass the `--source-only` flag). The `--binary-only` and
 `--source-only` flags are alternatives.
 
-`--git` is a convenient way to get the most recent version from the `master`
-branch, for those testing and living on the bleeding edge.
+When compiling from source code, by default:
+
+*   Stack will obtain the source code for the most recent version in the package
+    index (eg Hackage). Pass the flag `--git` to specify the most recent version
+    from the `master` branch of Stack's repository.

doc/upload_command.md

@@ -68,17 +68,17 @@ example:
      stack upload .
      ~~~
 
-## The `stack upload --candidate` flag
+## `--candidate` flag
 
 Pass the flag to upload a
 [package candidate](http://hackage.haskell.org/upload#candidates).
 
-## The `stack upload --ignore-check` flag
+## `--ignore-check` flag
 
 Pass the flag to disable checks of the package for common mistakes. By default,
 the command will check the package for common mistakes.
 
-## The `stack upload --pvp-bounds` option
+## `--pvp-bounds` option
 
 The `--pvp-bounds <pvp_bounds_mode>` option determines whether and, if so, how
 PVP version bounds should be added to the Cabal file of the package. The
@@ -89,12 +89,12 @@ available modes for use with Cabal file revisions are `lower-revision`,
 For futher information, see the
 [YAML configuration](yaml_configuration.md#pvp-bounds) documentation.
 
-## The `stack upload --tar-dir` option
+## `--tar-dir` option
 
 The `--tar-dir <path_to_directory>` option determines whether the package
 archive should be copied to the specified directory.
 
-## The `stack upload --[no-]test-tarball` flag
+## `--[no-]test-tarball` flag
 
 Default: Disabled