From 9c457f944904d3e0fb490fcab3fe1ef7a35b124b Mon Sep 17 00:00:00 2001
From: Adriaan de Groot <groot@kde.org>
Date: Mon, 12 Oct 2020 23:11:00 +0200
Subject: [PATCH] [shellprocess] Improve documentation and examples

---
 src/modules/shellprocess/shellprocess.conf | 36 +++++++++++++++++++---
 1 file changed, 31 insertions(+), 5 deletions(-)

diff --git a/src/modules/shellprocess/shellprocess.conf b/src/modules/shellprocess/shellprocess.conf
index 00d88851f..44b6d145a 100644
--- a/src/modules/shellprocess/shellprocess.conf
+++ b/src/modules/shellprocess/shellprocess.conf
@@ -24,16 +24,42 @@
 #
 # The value of *script* may be:
 #   - a single string; this is one command that is executed.
-#   - a list of strings; these are executed one at a time, by
+#   - a single object (this is not useful).
+#   - a list of items; these are executed one at a time, by
 #     separate shells (/bin/sh -c is invoked for each command).
-#   - an object, specifying a key *command* and (optionally)
-#     a key *timeout* to set the timeout for this specific
-#     command differently from the global setting.
+#     Each list item may be:
+#     - a single string; this is one command that is executed.
+#     - a single object, specifying a key *command* and (optionally)
+#       a key *timeout* to set the timeout for this specific
+#       command differently from the global setting.
+#
+# Using a single object is not useful because the same effect can
+# be obtained with a single string and a global timeout, but when
+# there are multiple commands to execute, one of them might have
+# a different timeout than the others.
 ---
 dontChroot: false
 timeout: 10
+
+# Script may be a single string (because false returns an error exit
+# code, this will trigger a failure in the installation):
+#
+# script: "/usr/bin/false"
+
+# Script may be a list of strings (because false returns an error exit
+# code, **but** the command starts with a "-", the error exit is
+# ignored and installation continues):
+#
+# script:
+#     - "-/usr/bin/false"
+#     - "/bin/ls"
+#     - "/usr/bin/true"
+
+# Script may be a lit of items (if the touch command fails, it is
+# ignored; the slowloris command has a different timeout from the
+# other commands in the list):
 script:
     - "-touch @@ROOT@@/tmp/thingy"
-    - "/usr/bin/false"
+    - "/usr/bin/true"
     - command: "/usr/local/bin/slowloris"
       timeout: 3600