Merge branch 'issue-1158'

FIXES #1158

settings.conf

@@ -7,14 +7,26 @@
 # path to a directory or the keyword "local".
 #
 # "local" means:
-#   - modules in $LIBDIR/calamares/moduleswith
+#   - modules in $LIBDIR/calamares/modules, with
 #   - settings in SHARE/calamares/modules or /etc/calamares/modules.
+# In debug-mode (e.g. calamares -d) "local" also adds some paths
+# that make sense from inside the build-directory, so that you
+# can build-and-run with the latest modules immediately.
+#
+# Strings other than "local" are taken as paths and interpreted
+# relative to wherever Calamares is started. It is therefore **strongly**
+# recommended to use only absolute paths here. This is mostly useful
+# if your distro has forks of standard Calamares modules, but also
+# uses some form of upstream packaging which might overwrite those
+# forked modules -- then you can keep modules somewhere outside of
+# the "regular" module tree.
+#
 #
 # YAML: list of strings.
 modules-search: [ local ]
 
 # Instances section. This section is optional, and it defines custom instances
-# for modules of any kind. An instance entry has an instance name, a module
+# for modules of any kind. An instance entry has an module name, an instance
 # name, and a configuration file name. The primary goal of this mechanism is
 # to allow loading multiple instances of the same module, with different
 # configuration. If you don't need this, the instances section can safely be
@@ -22,24 +34,27 @@ modules-search: [ local ]
 #
 # Module name plus instance name makes an instance key, e.g.
 # "webview@owncloud", where "webview" is the module name (for the webview
-# viewmodule) and "owncloud" is the instance name, which loads a configuration
+# viewmodule) and "owncloud" is the instance name. In the *sequence*
-# file named "owncloud.conf" from any of the configuration file paths,
+# section below, use instance-keys to name instances (instead of just
-# including the webview module directory. This instance key can then be
+# a module name, for modules which have only a single instance).
-# referenced in the sequence section.
 #
-# For all modules without a custom instance specification, a default instance
+# Every module implicitly has an instance with the instance name equal
-# is generated automatically by Calamares. Therefore a statement such as
+# to its module name, e.g. "welcome@welcome". In the *sequence* section,
-# "webview" in the sequence section automatically implies an instance key of
+# mentioning a module without a full instance key (e.g. "welcome")
-# "webview@webview" even without explicitly defining this instance, and the
+# means that implicit module.
-# configuration file for this default instance "<modulename>@<modulename>" is
+#
-# always assumed to be "<modulename>.conf".
+# An instance must specify its configuration file (e.g. `webview-home.conf`).
+# The implicit instances all have configuration files named `<module>.conf`.
+# This (implict) way matches the source examples, where the welcome
+# module contains an example `welcome.conf`.
 #
 # For more information on running module instances, run Calamares in debug
 # mode and check the Modules page in the Debug information interface.
 #
-# A module that is often used with instances is dummyprocess, which will
+# A module that is often used with instances is shellprocess, which will
-# run a single (shell) command. By configuring more than one instance of
+# run shell commands specified in the configuration file. By configuring
-# the module, multiple shell commands can be run during install.
+# more than one instance of the module, multiple shell sessions can be run
+# during install.
 #
 # YAML: list of maps of string:string key-value pairs.
 #instances: