[tracking] Document the configuration file format

- switch to 'enabled' and 'default' settings, independently.
 - document user-tracking as unimplemented.

settings.conf

@@ -66,6 +66,7 @@ sequence:
   - keyboard
   - partition
   - users
+  - tracking
   - summary
 - exec:
 #  - dummycpp

src/modules/tracking/tracking.conf

@@ -1,14 +1,69 @@
+# Settings for various kinds of tracking that Distributions can
+# enable. Distributions looking at tracking should be aware of
+# the privacy (and hence communications) impact of that tracking,
+# and are advised to consult the Mozilla and KDE policies on
+# privacy and user tracking.
+#
+# There are three areas of tracking (-configuration) supported
+# by Calamares It is up to individual Distributions to create
+# suitable backends / configuration scripts for each. The
+# different areas are:
+#
+# install:  This is "phone home" functionality at the end of the
+#           install process. When enabled, it contacts the given
+#           URL. The URL can contain the special token $MACHINE,
+#           which is replaced by the machine-id of the installed
+#           system (if available, blank otherwise).
+#
+# machine:  This enables machine-level tracking on a (semi-)
+#           continuous basis. It is meant to keep track of installed
+#           systems and their continued use / updating.
+#
+# user:     This area enables user-level tracking, along the lines
+#           of the KDE User Telemetry Policy. It enables specific
+#           collection of data at a user- and application-level,
+#           possibly including actions done in an application.
+#           For the KDE environment, this enables user tracking
+#           with the appropriate framework, and the KDE User Telemetry
+#           policy applies.
+#
+# Each area has a key *enabled*, and a key *default*. If the area
+# is enabled, it is shown to the user with a checkbox to enable
+# or disable that piece of user-tracking. The default state of that
+# checkbox is set to the value of *default*. Both keys default to
+# "off", disabling all tracking-configuration through Calamares.
+#
+# Each area may have other configuration keys, depending on the
+# area and how it needs to be configured.
 ---
-machine:
-  - tracking: false
-  - style: neon
-  - path: /etc/machine-file
-
-user:
-  - tracking: false
-  - style: neon
 
+# The install area has one specific configuration key:
+#   url:    this URL (remember to include the protocol, and prefer https)
+#           is fetched (with a GET request, and the data discarded) at
+#           the end of the installation process. The token $MACHINE
+#           in the URL is replaced by the machine-id of the installed
+#           system, if it is available, and otherwise blank. Typically
+#           you would add `?id=$MACHINE` as a GET parameter.
+#
+# Note that phone-home only works if the system has an internet
+# connection; it is a good idea to require internet in the welcome
+# module then.
 install:
-  - tracking: false
+  - enabled: false
+  - default: false
+  - url:
+
+# The machine area has one specific configuration key:
+#   style:  This string specifies what kind of tracking configuration
+#           needs to be done. There is currently only one valid
+#           style, "neon", which edits two files in the installed
+#           system to enable system-tracking.
+machine:
+  - enabled: false
+  - default: false
   - style: neon
 
+# The user area is not yet implemented, and has no specific configuration.
+user:
+  - enabled: false
+  - default: false