diff --git a/src/modules/packages/packages.conf b/src/modules/packages/packages.conf
index 94f3cfdb6..e42e8e9b8 100644
--- a/src/modules/packages/packages.conf
+++ b/src/modules/packages/packages.conf
@@ -31,9 +31,9 @@ backend: dummy
 #
 # Set "update_db" to 'true' for refreshing the database on the
 # target system. On target installations, which got installed by
-# unsquashing, a full system update may be needed. Otherwise 
+# unsquashing, a full system update may be needed. Otherwise
 # post-installing additional packages may result in conflicts.
-# Therefore set also "update_system" to 'true'. 
+# Therefore set also "update_system" to 'true'.
 #
 skip_if_no_internet: false
 update_db: true
@@ -87,9 +87,25 @@ update_system: false
 #     pre-script: touch /tmp/installing-vi
 #     post-script: rm -f /tmp/installing-vi
 #
-# The pre- and post-scripts are optional, but you cannot leave both out: using
-# "package: vi" with neither script option will trick Calamares into
-# trying to install a package named "package: vi", which is unlikely to work.
+# The pre- and post-scripts are optional, but you cannot leave both out
+# if you do use the *package* key: using "package: vi" with neither script
+# option will trick Calamares into trying to install a package named
+# "package: vi", which is unlikely to work.
+#
+# The pre- and post-scripts are **not** executed by a shell unless you
+# explicitly invoke `/bin/sh` in them. The command-lines are passed
+# to exec(), which does not understand shell syntax. In other words:
+#
+#     pre-script: ls | wc -l
+#
+# Will fail, because `|` is passed as a command-line argument to ls,
+# as are `wc`, and `-l`. No shell pipeline is set up, and ls is likely
+# to complain. Invoke the shell explicitly:
+#
+#     pre-script: /bin/sh -c \"ls | wc -l\"
+#
+# The above note on shell-expansion applies to versions up-to-and-including
+# Calamares 3.2.12, but will change in future.
 #
 # Any package name may be localized; this is used to install localization
 # packages for software based on the selected system locale. By including
@@ -104,7 +120,7 @@ update_system: false
 #
 # Take care that just plain `LOCALE` will not be replaced, so `foo-LOCALE` will
 # be left unchanged, while `foo-$LOCALE` will be changed. However, `foo-LOCALE`
-# **will** be removed from the list of packages (i.e. not installed), if 
+# **will** be removed from the list of packages (i.e. not installed), if
 # English is selected. If a non-English locale is selected, then `foo-LOCALE`
 # will be installed, unchanged (no language-name-substitution occurs).
 #