Re #5305 Improve existing stack script --extra-dep documentation

Author: mpilgrem

doc/commands/script_command.md

@@ -52,8 +52,18 @@ For example:
 stack script --snapshot lts-23.14 MyScript.hs
 ~~~
 
-A package version can be added to the snapshot on the command line with the
-`--extra-dep` option (which can be specified multiple times).
+An extra-dep from the package index can be added to the snapshot on the command
+line with the `--extra-dep` option (which can be specified multiple times).
+
+Such an extra-dep can be specified using a valid YAML string value. For further
+information, see the [package location](../topics/package_location.md)
+documentation. Examples are:
+
+~~~text
+--extra-dep acme-missiles-0.3
+--extra-dep acme-missiles-0.3@rev:0
+--extra-dep acme-missiles-0.3@sha256:2ba66a092a32593880a87fb00f3213762d7bca65a687d45965778deb8694c5d1,613
+~~~
 
 GHC boot packages that have been 'replaced' (see further below) can be specified
 as an `--extra-dep`.

doc/topics/package_location.md

@@ -62,7 +62,7 @@ example (where the file size is `631` bytes):
 
 ~~~yaml
 extra-deps:
-- acme-missiles-0.3@sha256:2ba66a092a32593880a87fb00f3213762d7bca65a687d45965778deb8694c5d1,631
+- acme-missiles-0.3@sha256:2ba66a092a32593880a87fb00f3213762d7bca65a687d45965778deb8694c5d1,613
 ~~~
 
 Optionally, you can specify also the Pantry tree information. For example:

doc/topics/scripts.md

@@ -139,6 +139,8 @@ stack script --snapshot lts-23.14 -- MyScript.hs arg1 arg2 +RTS -s -RTS
 where `+RTS -s -RTS` are some of GHC's
 [runtime system (RTS) options](https://downloads.haskell.org/~ghc/latest/docs/users_guide/runtime_control.html).
 
+Arguments that include spaces can be quoted using double quotation marks.
+
 ## Just-in-time compilation
 
 As with using [`stack script`](../commands/script_command.md) at the command
@@ -169,6 +171,20 @@ options, or by providing a comma or space separated list. For example:
 -}
 ~~~
 
+## Using extra-deps
+
+As with using [`stack script`](../commands/script_command.md) at the command
+line, you can also specify one or more extra-deps from the package index using a
+valid YAML string for each. For example:
+
+~~~haskell
+#!/usr/bin/env stack
+{- stack script
+   --snapshot lts-23.14
+   --extra-dep acme-missile-0.3@rev:0
+-}
+~~~
+
 ## Stack configuration for scripts
 
 When using the [`stack script`](../commands/script_command.md) command, as when