[shellprocess] Improve config docs

src/modules/shellprocess/shellprocess.conf

@@ -14,6 +14,10 @@
 #  - `USER` is replaced by the username, set on the user page.
 #
 # Variables are written as `${var}`, e.g. `${ROOT}`.
+# Write `$$` to get a shell-escaped `\$` in the shell command.
+# It is not possible to get an un-escaped `$` in the shell command
+# (either the command will fail because of undefined variables, or
+# you get a shell-escaped `\$`).
 #
 # The (global) timeout for the command list can be set with
 # the *timeout* key. The value is a time in seconds, default
@@ -35,20 +39,33 @@
 #
 # The value of *script* may be:
 #   - a single string; this is one command that is executed.
-#   - a single object (this is not useful).
+#   - a single object (see below).
 #   - a list of items; these are executed one at a time, by
 #     separate shells (/bin/sh -c is invoked for each command).
 #     Each list item may be:
 #     - a single string; this is one command that is executed.
 #     - a single object, specifying a key *command* and (optionally)
 #       a key *timeout* to set the timeout for this specific
-#       command differently from the global setting.
+#       command differently from the global setting. An optional
+#       key *environment* is a list of strings to put into the
+#       environment of the command.
 #
-# Using a single object is not useful because the same effect can
+# Using a single object is not generally useful because the same effect
-# be obtained with a single string and a global timeout, but when
+# can be obtained with a single string and a global timeout, except
-# there are multiple commands to execute, one of them might have
+# when the command needs environment-settings. When there are
+# multiple commands to execute, one of them might have
 # a different timeout than the others.
 #
+# The environment strings should all be "KEY='some value'" strings,
+# as if they can be typed into the shell. Quoting the environment
+# strings with "" in YAML is recommended. Adding the '' quotes ensures
+# that the value will not be interpreted by the shell. Writing
+# environment strings is the same as placing `export KEY='some value' ;`
+# in front of the *command*.
+#
+# Calamares variable expansion is **also** done on the environment strings.
+# Write `$$` to get a literal `$` in the shell command.
+#
 # To change the description of the job, set the *name* entries in *i18n*.
 ---
 # Set to true to run in host, rather than target system