Update sample settings.conf with new syntax and documentation.

settings.conf

@@ -7,79 +7,115 @@
 # directory or the keyword "local".
 # "local" means LIBDIR/calamares/modules with settings in SHARE/calamares/modules or
 # /etc/calamares/modules.
+# YAML: list of strings.
 modules-search: [ local ]
 
-# We define the module names in the order they should show up (QtWidget view modules,
+# Instances section. This section is optional, and it defines custom instances for
-# with one or more pages) OR be executed if enqueued (all other modules).
+# modules of any kind. An instance entry has an instance name, a module name, and
-# Pages can also enqueue jobs for delayed execution in the order specified for the
+# a configuration file name.
-# install phase, so a viewmodule name can appear in more than one phase.
+# 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
-# Phase 1 - prepare.
+# section can safely be left empty.
-# View modules are shown as UI pages, jobs from job modules are executed immediately in
+# Module name plus instance name makes an instance key, e.g. "webview@owncloud",
-# the background.
+# where "webview" is the module name (for the webview viewmodule) and "owncloud"
-# Jobs should be executed sparingly (if at all) in this phase.
+# is the instance name, which loads a configuration file named "owncloud.conf" from
-prepare:
+# any of the configuration file paths, including the webview module directory.
-- welcome
+# This instance key can then be referenced in the sequence section.
-- license
+# For all modules without a custom instance specification, a default instance is
-- locale
+# generated automatically by Calamares. Therefore a statement such as "webview" in
-- keyboard
+# the sequence section automatically implies an instance key of "webview@webview"
-- partition
+# even without explicitly defining this instance, and the configuration file for
-- users
+# this default instance "<modulename>@<modulename>" is always assumed to be
-- webview
+# "<modulename>.conf".
-- summary
+# For more information on running module instances, run Calamares in debug mode
-
+# and check the Modules page in the Debug information interface.
-# Phase 2 - install.
+# YAML: list of maps of string:string key-value pairs.
-# View modules are not shown. Only the view modules shown in the previous phase are
+instances:
-# allowed, their names should be added here as placeholders to specify the order in
+- id:       owncloud
-# which view module jobs should be enqueued. Job modules are also allowed.
+  module:   webview
-install:
+  config:   owncloud.conf
-#- dummyprocess
-#- dummypython
-- partition
-- mount
-- unpackfs
-- machineid
-- fstab
-- locale
-- keyboard
-- localecfg
-- initcpiocfg
-- initcpio
-- users
-- displaymanager
-- networkcfg
-- hwclock
-- services
-#- dracut
-#- initramfs
-- grubcfg
-- bootloader
-- umount
-
-# Phase 3 - postinstall.
-# View modules are shown as UI pages, jobs from job modules are executed immediately in
-# the background.
-# Jobs should be executed sparingly (if at all) in this phase.
-postinstall:
-- finished
 
+# Sequence section. This section describes the sequence of modules, both
+# viewmodules and jobmodules, as they should appear and/or run.
+# A jobmodule instance key (or name) can only appear in an exec phase, whereas
+# a viewmodule instance key (or name) can appear in both exec and show phases.
+# There is no limit to the number of show or exec phases. However, the same module
+# instance key should not appear more than once per phase, and deployers should
+# take notice that the global storage structure is persistent throughout the
+# application lifetime, possibly influencing behavior across phases.
+# A show phase defines a sequence of viewmodules (and therefore pages). These
+# viewmodules can offer up jobs for the execution queue.
+# An exec phase displays a progress page (with brandable slideshow). This progress
+# page iterates over the modules listed in the *immediately preceding* show phase,
+# and enqueues their jobs, as well as any other jobs from jobmodules, in the order
+# defined in the current exec phase.
+# It then executes the job queue and clears it. If a viewmodule offers up a job
+# for execution, but the module name (or instance key) isn't listed in the
+# immediately following exec phase, this job will not be executed.
+# WARNING: when upgrading from Calamares 1.1, this section requires manual
+# intervention. There are no fixed prepare/install/postinstall phases any more,
+# and all limitations on the number of phases, number of pages, and number of
+# instances are lifted.
+# YAML: list of lists of strings.
+sequence:
+- show:
+  - welcome
+  - locale
+  - keyboard
+  - partition
+  - users
+  - summary
+- exec:
+#  - dummyprocess
+#  - dummypython
+  - partition
+  - mount
+  - unpackfs
+  - machineid
+  - fstab
+  - locale
+  - keyboard
+  - localecfg
+  - initcpiocfg
+  - initcpio
+  - users
+  - displaymanager
+  - networkcfg
+  - hwclock
+  - services
+#  - dracut
+  - initramfs
+#  - grubcfg
+  - bootloader
+  - umount
+- show:
+  - webview@owncloud
+  - finished
 
 # A branding component is a directory, either in SHARE/calamares/branding or in
 # /etc/calamares/branding (the latter takes precedence). The directory must contain a
-# YAML file branding.desc which may reference additional resources (such as images or QML)
+# YAML file branding.desc which may reference additional resources (such as images) as
-# as paths relative to the current directory.
+# paths relative to the current directory.
+# A branding component can also ship a QML slideshow for execution pages, along with
+# translation files.
 # Only the name of the branding component (directory) should be specified here, Calamares
 # then takes care of finding it and loading the contents.
-branding: default
+# YAML: string.
+branding: netrunner-rolling
 
-# If this is set to true, Calamares will show an "are you sure?" prompt right before the
+# If this is set to true, Calamares will show an "Are you sure?" prompt right before
-# install phase, i.e. at the point of no return. If it's false, no prompt is shown.
+# each execution phase, i.e. at points of no return. If this is set to false, no prompt
+# is shown.
 # Default is false.
+# YAML: boolean.
 prompt-install: false
 
-# If this is set to true, all target environment calls will be executed on the current
+# If this is set to true, Calamares will execute all target environment commands in the
-# (host) system rather than on the target (chrooted) system.
+# current environment, without chroot. This setting is considered experimental, and it
-# Only set this to true in exceptional circumstances, if you are not using Calamares as
+# should only be used when setting up Calamares as a post-install configuration tool, as
-# a system installer.
+# opposed to a full operating system installer.
+# Some official Calamares modules are not expected to function with this setting.
+# Packagers beware, here be dragons.
 # Default is false.
+# YAML: boolean.
 dont-chroot: false