Fix #6035 Improve extra-dep and lock files documentation

Author: mpilgrem

doc/global_flags.md

@@ -118,7 +118,12 @@ Default: `read-write`, if snapshot specified in YAML configuration file;
 `read-only`, if a different snapshot is specified on the command line.
 
 Pass the option `--lock-file <mode>` to specify how Stack interacts with lock
-files. Valid modes are `error-on-write`, `ignore`, `read-only` and `read-write`.
+files. Valid modes are:
+
+* `error-on-write`: Stack reports an error, rather than write a lock file;
+* `ignore`: Stack ignores lock files;
+* `read-only`: Stack only reads lock files; and
+* `read-write`: Stack reads and writes lock files.
 
 ## `--[no-]modify-code-page` flag
 

doc/lock_files.md

@@ -145,30 +145,40 @@ packages:
       sha256: 614bc0cca76937507ea0a5ccc17a504c997ce458d7f2f9e43b15a10c8eaeb033
 ~~~
 
-## Creation
+## Creation procedure
 
 Whenever a project-level configuration file (`stack.yaml`) is loaded, Stack
 checks for a lock file in the same file path, with a `.lock` extension added.
 For example, if you command:
 
 ~~~text
-stack build --stack-yaml my-stack.yaml
+stack --stack-yaml my-stack.yaml build
 ~~~
 
-Stack will use a lock file in the location `my-stack.yaml.lock`. For the rest of
-this document, we'll assume that the files are simply `stack.yaml` and
+or
+
+~~~text
+stack --stack-yaml my-stack.yaml build --dry-run
+~~~
+
+then Stack will use a lock file in the location `my-stack.yaml.lock`. For the
+rest of this document, we'll assume that the files are simply `stack.yaml` and
 `stack.yaml.lock`.
 
-If the lock file does not exist, it will be created by:
+If the lock file does not exist, subject to Stack's
+[`--lock-file`](global_flags.md#-lock-file-option) option, it will be
+created by:
 
 * Loading the `stack.yaml`
 * Loading all snapshot files
 * Completing all missing information
-* Writing out the new `stack.yaml.lock` file
+* Writing out the new `stack.yaml.lock` file to the disk
 
 ## Update procedure
 
-When loading a Stack project all completed package or snapshot locations (even
-when they were completed using information from a lock file) get collected to
-form a new lock file in memory and compare against the one on disk, writing if
-there are any differences.
+Whenever a project-level configuration file (`stack.yaml`) is loaded, all
+completed package or snapshot locations (even those completed using information
+from a lock file) get collected to form a new lock file in memory. Subject to
+Stack's [`--lock-file`](global_flags.md#-lock-file-option) option, that new lock
+file is compared against the one on disk and, if there are any differences,
+written out to the disk.

doc/pantry.md

@@ -98,49 +98,45 @@ generated in a [lock file](lock_files.md).
 
 ### Hackage packages
 
-Packages can be stated by a name-version combination. The basic syntax for this
-is:
+A package can be identified by its name, version and its Cabal file revision
+number, with `0` being the original Cabal file. For example:
 
 ~~~yaml
 extra-deps:
-- acme-missiles-0.3
+- acme-missiles-0.3@rev:0
 ~~~
 
-Using this syntax, the most recent Cabal file revision available will
-be used.
-
-You can specify a specific revision number, with `0` being the original file,
-like this:
+A package name and version only can be stated. Using this syntax, the most
+recent Cabal file revision available in the package index will be used. For
+example:
 
 ~~~yaml
 extra-deps:
-- acme-missiles-0.3@rev:0
+- acme-missiles-0.3
 ~~~
 
-For safer, more reproducible builds, you can optionally specify the SHA256 hash
-of the Cabal file's contents, like this:
+This may result in one build differing from another, if a further Cabal file
+revision is added to the package index between builds.
+
+Alternatively, you can specify the package name and version with the SHA256 hash
+of the contents of its Cabal file. Doing so is slighly more resilient than using
+the Cabal file revision number, as it does not rely on the correct ordering in
+the package index. For example:
 
 ~~~yaml
 extra-deps:
 - acme-missiles-0.3@sha256:2ba66a092a32593880a87fb00f3213762d7bca65a687d45965778deb8694c5d1
 ~~~
 
-You can optionally also specify the size of the Cabal file in bytes, like this:
+Optionally, you can specify also the size of the Cabal file in bytes. For
+example:
 
 ~~~yaml
 extra-deps:
 - acme-missiles-0.3@sha256:2ba66a092a32593880a87fb00f3213762d7bca65a687d45965778deb8694c5d1,631
 ~~~
 
-!!! note
-
-    Specifying package using SHA256 is slightly more resilient in that it does
-    not rely on correct ordering in the package index, while revision number is
-    likely simpler to use. In practice, both should guarantee equally
-    reproducible build plans.
-
-You can also include the Pantry tree information. The following would be
-generated and stored in the lock file:
+Optionally, you can specify also the Pantry tree information. For example:
 
 ~~~yaml
 - hackage: acme-missiles-0.3@sha256:2ba66a092a32593880a87fb00f3213762d7bca65a687d45965778deb8694c5d1,613
@@ -149,6 +145,10 @@ generated and stored in the lock file:
     sha256: 614bc0cca76937507ea0a5ccc17a504c997ce458d7f2f9e43b15a10c8eaeb033
 ~~~
 
+The SHA256 hash of the contents of the Cabal file and its size in bytes is
+provided in Stack's lock file. For further information, see the
+[lock files](lock_files.md) documentation.
+
 ### Git and Mercurial repositories
 
 You can give a Git or Mercurial repository at a specific commit, and Stack will