diff --git a/src/modules/packages/packages.conf b/src/modules/packages/packages.conf
index 7bf589243..6e3af05a8 100644
--- a/src/modules/packages/packages.conf
+++ b/src/modules/packages/packages.conf
@@ -33,23 +33,84 @@ update_db: true
 # storage called "packageOperations" and it is processed
 # after the static list in the job configuration.
 #
-#operations:
-#  - install:
-#      - pkg1
-#      - pkg2
-#  - remove:
-#      - pkg3
-#      - pkg4
-#  - try_install:   # no system install failure if a package cannot be installed
-#      - pkg5
-#  - try_remove:    # no system install failure if a package cannot be removed
-#      - pkg2
-#      - pkg1
-#  - install:
-#      - pkgs6
-#      - pkg7
-#  - localInstall:
-#      - /path/to/pkg8
+# Allowed package operations are:
+#  - install, try_install: will call the package manager to
+#       install one or more packages. The install target will
+#       abort the whole installation if package-installation
+#       fails, while try_install carries on. Packages may be
+#       listed as (localized) names, or as (localized) package-data.
+#       See below for the description of the format.
+# - localInstall: this is used to call the package manager
+#       to install a package from a path-to-a-package. This is
+#       useful if you have a static package archive on the install media.
+# - remove, try_remove: will call the package manager to
+#       remove one or more packages. The remove target will
+#       abort the whole installation if package-removal fails,
+#       while try_remove carries on. Packages may be listed as
+#       (localized) names.
+#
+# There are two formats for naming packages: as a name # or as package-data,
+# which is an object notation providing package-name, as well as pre- and
+# post-install scripts.
+#
+# Here are both formats, for installing vi. The first one just names the
+# package for vi (using the naming of the installed package manager), while
+# the second contains three data-items; the pre-script is run before invoking
+# the package manager, and the post-script runs once it is done.
+#
+# - install
+#   - vi
+#   - package: vi
+#     pre-script: touch /tmp/installing-vi
+#     post-script: rm -f /tmp/installing-vi
+#
+# The pre- and post-scripts are optional, but not both optional: using
+# "package: vi" with neither script option will trick Calamares into
+# trying to install a package named "package: vi", which is unlikely to work.
+#
+# Any package name may be localized; this is used to install localization
+# packages for software based on the selected system locale. By including
+# the string LOCALE in the package name, the following happens:
+#
+# - if the system locale is English (generally US English; en_GB is a valid
+#   localization), then the package is not installed at all,
+# - otherwise LOCALE is replaced by the Bcp47 name of the selected system
+#   locale, e.g. nl_BE.
+#
+# The following installs localizations for vi, if they are relevant; if
+# there is no localization, installation continues normally.
+#
+# - install
+#   - vi-LOCALE
+#   - package: vi-LOCALE
+#     pre-script: touch /tmp/installing-vi
+#     post-script: rm -f /tmp/installing-vi
+#
+# When installing packages, Calamares will invoke the package manager
+# with a list of package names if it can; package-data prevents this because
+# of the scripts that need to run. In other words, this:
+#
+# - install:
+#   - vi
+#   - binutils
+#   - package: wget
+#     pre-script: touch /tmp/installing-wget
+#
+# This will invoke the package manager three times, once for each package,
+# because not all of them are simple package names. You can speed up the
+# process if you have only a few pre-scriots, by using multiple install targets:
+#
+# - install:
+#   - vi
+#   - binutils
+# - install:
+#   - package: wget
+#     pre-script: touch /tmp/installing-wget
+#
+# This will call the package manager once with the package-names "vi" and
+# "binutils", and then a second time for "wget". When installing large numbers
+# of packages, this can lead to a considerable time savings.
+#
 operations:
   - install:
     - vi