From 79feaed5acdcb41959ce3f997a23dce838aa0efe Mon Sep 17 00:00:00 2001
From: hygienic-books <hygienic-books@tentic.net>
Date: Sat, 4 Nov 2023 00:20:39 +0100
Subject: [PATCH] docs(iso): Explain sed insert_n_before_m mechanism (#6)

---
 setup.sh | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/setup.sh b/setup.sh
index d5c7d85..ab95d0d 100644
--- a/setup.sh
+++ b/setup.sh
@@ -468,6 +468,29 @@ function in_file_in_array_insert_n_before_m () {
     arg_array="${2:?}"
     arg_string="${3:?}"
     arg_precede="${4:?}"
+
+    # Look for a line that contains in this order
+    # - String "${arg_array}" and a equals sign (=), assign capture group \1
+    # - Followed by as few characters as possible followed by either an
+    #   opening parenthesis or a space character, assign capture group \2
+    # - String "${arg_precede}", capture as capture group \3
+    # - Followed by either a closing parenthesis or a space which are then
+    #   followed by as many non-line break characters as possible, capture
+    #   as capture group \2
+    #
+    # For following example text we're assuming that:
+    # - "${arg_array}"   equals 'HOOKS'
+    # - "${arg_precede}" equals 'filesystems'
+    # - "${arg_string}"  equals 'zfs'
+    #
+    # This finds a 'HOOKS=' array definition that contains the string
+    # 'filesystems' either at the beginning of the 'HOOKS=(...)' opening
+    # parenthesis, at the very end or somewhere in the middle where it may
+    # be preceded or followed by one or more space characters. It saves
+    # 'HOOKS=', it saves whatever precedes 'filesystems' and 'filesystems'
+    # itself plus whatever comes after 'filesystems' until end of line. It
+    # lastly inserts 'zfs' and a space character right in front of
+    # 'filesystems'.
     sed -ri \
         -e 's'$'\x1''('"${arg_array}"'=)(.*?[( ])('"${arg_precede}"')([) ][^\r\n\f]*)'$'\x1''\1\2'"${arg_string}"' \3\4'$'\x1''g' \
         "${arg_file}"