From 3651965a5be8847ac54abf0b385dcbe479a7a972 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Wed, 13 Jan 2021 16:54:47 +0200
Subject: Proofreading changes to Bash style guide

---
 doc/bash-style.cli | 36 +++++++++++++++++++-----------------
 1 file changed, 19 insertions(+), 17 deletions(-)

(limited to 'doc')

diff --git a/doc/bash-style.cli b/doc/bash-style.cli
index 435dfe3..a76053a 100644
--- a/doc/bash-style.cli
+++ b/doc/bash-style.cli
@@ -176,7 +176,7 @@ if [ -z \"$file\" ]; then
 fi
 
 if [ ! -d \"$file\" ]; then
-  fail \"'$file' does not exist or is not a directory\"
+  error \"'$file' does not exist or is not a directory\"
 fi
 \
 
@@ -257,8 +257,7 @@ while [ \"$#\" -gt 0 ]; do
     ...
 
     *)
-      shift
-      files=(\"${files[@]}\" \"$1\")
+      files+=(\"$1\")
       shift
       ;;
   esac
@@ -439,7 +438,7 @@ foo | readarray -t r
 
 In this case, if the function can fail, then the failure should be explicitly
 checked for (either by examining \c{PIPESTATUS} or via the lack of the
-result), since the error trap will not be triggered (unless the \c{pipefail}
+result), since the \c{ERR} trap will not be triggered (unless the \c{pipefail}
 shell option is set; see \l{#error-handing Error Handling} for details). For
 example:
 
@@ -508,7 +507,7 @@ For more information on returning data from functions, see
 
 \h1#error-handing|Error Handling|
 
-Our scripts use the error trap to automatically terminate the script in case
+Our scripts use the \c{ERR} trap to automatically terminate the script in case
 any command fails. This is also propagated to functions and subshells by
 specifying the \c{errtrace} shell option.
 
@@ -518,7 +517,7 @@ they are worth (see \l{https://mywiki.wooledge.org/BashPitfalls#pipefail
 \c{pipefail} pitfalls}, \l{https://mywiki.wooledge.org/BashPitfalls#nounset
 \c{nounset} pitfalls}).
 
-In particular, without \c{pipefail}, non-zero exist of any command in the
+In particular, without \c{pipefail}, a non-zero exit of any command in the
 pipeline except the last is ignored. As a result, the pipeline needs to be
 designed to work correctly in such cases, normally by relying on the input (or
 lack thereof) to the last command to convey the failure. Alternatively, the
@@ -550,7 +549,7 @@ But keep in mind that in Bash a failure is often indistinguishable from a
 true/false result. For example, in the above \c{grep} command, the result will
 be the same whether there is no match or if the file does not exist.
 
-Furthermore, in certain contexts, the above-mentioned error trap is ignored.
+Furthermore, in certain contexts, the above-mentioned \c{ERR} trap is ignored.
 Quoting from the Bash manual:
 
 \i{The \c{ERR} trap is not executed if the failed command is part of the
@@ -579,10 +578,9 @@ Here, the \c{cleanup()} function will continue executing (and may succeed)
 even if the \c{cd} command has failed.
 
 Note, however, that notwithstanding the above statement from the Bash manual,
-the trap is executed in all the commands of a pipeline provided the
-\c{errtrace} option is specified (presumably because commands of a pipeline
-are said to execute in subshells). As a result, the above code can be made to
-work using the pipe trick:
+the \c{ERR} trap is executed inside all the subshell commands of a pipeline
+provided the \c{errtrace} option is specified.  As a result, the above code
+can be made to work using the pipe trick:
 
 \
 cleanup /no/such/dir | cat
@@ -592,19 +590,23 @@ if [ \"${PIPESTATUS[0]}\" -ne 0 ]; then
 fi
 \
 
-\N|If the \c{pipefail} shell option is set, then the explicit \c{PIPESTATUS}
-check is not necessary since the function failure will trigger the error trap
-in the current shell.|
+\N|If \c{cleanup}'s \c{cd} fails, the \c{ERR} trap will be executed in the
++subshell, causing it to exit with an error status which the parent shell then
++makes available in \c{PIPESTATUS}.
+
+If the \c{pipefail} shell option is set, then the explicit \c{PIPESTATUS}
+check is not necessary since the function failure will trigger the \c{ERR}
+trap in the current shell.|
 
 The recommendation is then to avoid calling functions in contexts where the
-error trap is ignored resorting to the pipe trick where that's not possible.
+\c{ERR} trap is ignored resorting to the pipe trick where that's not possible.
 And to be mindful of the potential ambiguity between the true/false result and
 failure for other commands. The use of the \c{&&} and \c{||} command
 expressions is best left to the interactive shell.
 
 \N|The pipe trick cannot be used if the function needs to modify the global
 state. Such a function, however, can return the exit status also as part of
-the global state. The pipe trick can also be used to to ignore the exit status
+the global state. The pipe trick can also be used to ignore the exit status
 of a command (provided \c{pipefail} is not set).|
 
 The pipe trick can also be used to distinguish between different exit codes,
@@ -635,7 +637,7 @@ esac
 \
 
 \N|In such functions it makes sense to keep exit code 1 to mean failure so
-that the inherited error trap can be re-used.|
+that the inherited \c{ERR} trap can be re-used.|
 
 This technique can be further extended to implement functions that both
 return multiple exit codes and produce output, for example:
-- 
cgit v1.1