[services] Document the configuration file.

- Change the example to be harmless (empty)
 - Document the structure of the entries

src/modules/services/services.conf

@@ -1,20 +1,45 @@
+# Systemd services manipulation.
+#
+# This module can enable services and targets for systemd
+# (if packaging doesn't already do that). It can calso
+# disable services (but not targets).
+#
+# First, services are enabled; then targets; then services
+# are disabled -- this order of operations is fixed.
 ---
-#systemd services and targets are enabled in this precise order
 
-services:
-  - name: "NetworkManager"  #name of the service file
-    mandatory: false        #true=> if enabling fails the installer errors out and quits
-                            #false=>if enabling fails print warning to console and continue
-  - name: "cups"
-    mandatory: false
+# There are three configuration keys for this module:
+# *services*, *targets* and *disable*. The value of each
+# key is a list of entries. Each entry has two keys:
+#   - *name* is the (string) name of the service or target that is being
+#     changed. Use quotes.
+#   - *mandatory* is a boolean option, which states whether the change
+#     must be done successfully. If systemd reports an error while changing
+#     a mandatory entry, the installation will fail. When mandatory is false,
+#     errors for that entry (service or target) are ignored.
+#
+# Use [] to express an empty list.
 
-targets:
-  - name: "graphical"
-    mandatory: true
+# # This example enables NetworkManager (and fails if it can't),
+# # disables cups (and ignores failure). Then it enables the
+# # graphical target (e.g. so that SDDM runs for login), and
+# # finally disables pacman-init (an ArchLinux-only service).
+# #
+# services:
+#   - name: "NetworkManager"
+#     mandatory: true
+#   - name: "cups"
+#     mandatory: false
+#
+# targets:
+#   - name: "graphical"
+#     mandatory: true
+#
+# disable:
+#   - name: "pacman-init"
+#     mandatory: false
 
-disable:
-  - name: "pacman-init"
-    mandatory: false
-
-# Example to express an empty list:
-# disable: []
+# By default, no changes are made.
+services: []
+targets: []
+disable: []