[Savannah-cvs] [709] (1/2) [bash-style-guide.mdwn]: typos and formatting

[iank]

Revision: 709
          
http://svn.savannah.gnu.org/viewvc/?view=rev&root=administration&revision=709
Author:   iank
Date:     2023-12-12 21:02:01 -0500 (Tue, 12 Dec 2023)
Log Message:
-----------
(1/2) [bash-style-guide.mdwn]: typos and formatting

>From f2f43ff429a58fd6d57602efeb5acb9802197789 Mon Sep 17 00:00:00 2001
From: bill-auger <mr.j.spam.me@gmail.com>
Date: Tue, 12 Dec 2023 19:51:44 -0500
Subject: [PATCH 1/2] [bash-style-guide.mdwn]: typos and formatting

Modified Paths:
--------------
    trunk/sviki/fsf/bash-style-guide.mdwn

Modified: trunk/sviki/fsf/bash-style-guide.mdwn
===================================================================
--- trunk/sviki/fsf/bash-style-guide.mdwn       2023-12-12 21:06:21 UTC (rev 
708)
+++ trunk/sviki/fsf/bash-style-guide.mdwn       2023-12-13 02:02:01 UTC (rev 
709)
@@ -1,6 +1,8 @@
 # FSF Tech Team Bash style guide
 
-Contributions are welcome. Send patches to
+Contributions are welcome
+(`git svn clone --stdlayout svn://svn.savannah.gnu.org/administration/`).
+Send patches to
 <https://lists.fsf.org/mailman/listinfo/tech-volunteer-meeting>. Info on
 volunteering with the FSF tech team:
 <https://libreplanet.org/wiki/Group:FSF:Tech_Team_Volunteers>
@@ -15,7 +17,7 @@
 
 Useful:
 
-* Man bash(1)
+* `info bash`
 
 * <https://mywiki.wooledge.org/EnglishFrontPage>
 
@@ -26,7 +28,7 @@
 
 About "portability": If you read something online that says, you should
 do it this way because is "more portable", you often want the exact
-opposite. It often means that bash or gnu coreutils can do it in a more
+opposite. It often means that bash or GNU coreutils can do it in a more
 readable or otherwise better way. We all deserve to use systems where we
 can install and use GNU software, don't hamstring yourself for the sake
 of catering to less capable systems unless you really have some good
@@ -45,7 +47,7 @@
 
 Scripts must be executable, preferably with no extension, but .sh is
 okay. lowercase-dash-separated. Scripts meant to be sourced (libraries)
-are more okay to have .sh extention. This is common practice scripts in
+are more okay to have .sh extension. This is common practice scripts in
 /usr/bin, don't have .sh, it's extraneous overhead to the person using
 it.
 
@@ -54,11 +56,11 @@
 
 # Shellcheck
 
-The shebang should not have arguments so bash script-name works the
-same. Use the set command instead.
+The shebang should not have arguments; so `BASH script-name` works the
+same. Use the `set` command instead.
 
 
-Before using any script, it should have no output from
+Before using any script, it should have no output from:
 
 ```
 shellcheck -x -e 2046,2068,2086,2206,2029,2033,2054,2164,2254 SCRIPT_FILE
@@ -71,13 +73,13 @@
 The following exceptions are for quoting variables. Shellcheck complains
 that unquoted variables will do splitting and globbing. You should
 simply know this and account for this it in your code. Most variables
-are things we know don't have spaces and it would be too verbose to
-quote them all the time. If the variable could have characters like
-space, *, ?, [, then definitely quote it unless you want globing. If it
-the variable is the program's args, always quote it, because the person
-running it can easily make errors. For scripts which are expected to
-take untrusted input, or process files or variables which could have
-spaces, run shellcheck with no exceptions to verify quoting.
+are things that we know don't have spaces, and it would be too verbose to
+quote them all the time. If the variable could have characters such as
+spaces, *, ?, [, etc, then definitely quote it unless you want globbing. If
+the variable is set to one of the program's CLI args, always quote it,
+because the person running the script can easily make errors. For scripts
+which are expected to take un-trusted input, or process files or variables
+which could have spaces, run shellcheck with no exceptions to verify quoting.
 
 ```
 # 2046 = unquoted $(cmd)
@@ -90,7 +92,7 @@
 Miscellaneous exceptions:
 
 ```
-# 2029 = Using unescaped variable in ssh call. Reason: This never
+# 2029 = Using un-escaped variable in ssh call. Reason: This never
   works, warning is generally a false positive.
 
 # 2032 = Warning about calling shell function over ssh. There are ways
@@ -97,18 +99,18 @@
   for this to be a false positive, and we generally don't need a warning
   that shellcheck doesn't know if a command exists.
 
-# 2033 = shell function as argument to another shell. Reason: This never
+# 2033 = Shell function as argument to another shell. Reason: This never
   works, warning is generally a false positive.
 
 # 2054 = Array declaration contains a comma. Reason: This is warning of a
-  mistake based on how other languages work, but this would never work
-  as expected in bash and is a legitimate thing to do.
+  mistake based on how other languages work; but commas are not special
+  in BASH, and even unquoted, they are legitimate array elements.
 
-# 2164 = cd without condition for failure. Reason: We use automatic error
+# 2164 = `cd` without condition for failure. Reason: We use automatic error
   handling.
 ```
 
-This is based on shellcheck version: 0.8.0 from trisquel 11. A newer
+This is based on shellcheck version: 0.8.0 from Trisquel 11. A newer
 shellcheck probably has new rules worth ignoring.
 
 ## Other shellcheck issues
@@ -121,11 +123,9 @@
 ```
 
 If the shellcheck you are using is too old for -x, get a new one using
-package pinning or haskell stack.
+package pinning or Haskell stack.
 
-
-
-For shellcheck SC2207/2206, how to avoid x=( $(cmd) ) and y=( $var ) since
+For shellcheck SC2207/2206, how to avoid `x=( $(cmd) )` and `y=( $var )` since
 it unnecessarily expands globs:
 
 For splitting a variable on spaces without glob expansion:
@@ -208,27 +208,23 @@
 readonly verbose
 ```
 
-Use local to make function local variables enforced. This adds
-readability and avoids error from using variable in an unintended
-scope. eg: `local y=5`
+Use `local` to properly scope variables as "function-local". This adds
+readability and avoids errors from using variables in unintended
+scopes. eg: `local y=5`
 
-
 Never quote literal integers.
 
-Prefer single quoting strings that have no subsitution (things that
-start with $).
+Prefer single-quoting strings that have no substitution (things that
+start with `$`).
 
-Non command options or path names can be optionally quoted. eg `x='oo'`
+Non-command options or path names can be optionally quoted, eg: `x='oo'`.
 
 
-
-
 Functions:
 
 Put all functions together near the top of the file after includes,
-constants, and set statements.
+constants, and `set` statements.
 
-
 Always use `return 0`, never `return`, because you can return nonzero
 by accident otherwise.
 
@@ -248,8 +244,8 @@
 ```
 
 
-For scripts with functions, copy/paste or source the bash-bear script
-<https://savannah.nongnu.org/git/?group=bash-bear-trap> , which will exit on 
error and print stack traces.
+For scripts with functions, copy/paste or `source` the bash-bear script
+<https://savannah.nongnu.org/git/?group=bash-bear-trap> , which will exit on 
error and print a stack trace.
 
 When you want to manually handle some error, use a variable, for example:
 
@@ -260,7 +256,7 @@
   echo do stuff
   result=false
 }
-test-funcc
+test-func
 $result || echo handling false result
 
 echo this prints too
@@ -267,19 +263,23 @@
 ```
 
 To allow a specific command to to fail, make it part of a conditional. eg:
+
+```
 iptables -D rule || [[ $? == 1 ]] # allow exit code 1 when rule doesn't exist
+```
 
 ### Gotchas in automatic error handling:
 
 ### Functions in conditionals
 
-Don't put functions in conditionals generally because the trap is
+Don't put functions in conditionals generally, because the trap is
 ignored in that function call. Instead, use a result variable. However,
-it ok for very short functions when only the last line can fail. eg:
+it is okay for very short functions when only the last line can fail. eg:
 
 ```
 afunc() { echo ok; "$@"; }
 ```
+
 ### Process Substitution
 
 Don't use process substitution when the command inside could fail,
@@ -305,7 +305,7 @@
 echo hello $(command-that-could-fail)
 ```
 
-Instead, do this
+Instead, do this:
 
 ```
 var=$(command-that-could-fail)
@@ -312,11 +312,21 @@
 echo hello "$var"
 ```
 
+Note that `var=` as shown above would be a global variable.
+In a function body, it is best to declare variables as function-local,
+as noted in the 'Variables:' section. However, be sure not to set the
+variable in the declaration command, which would re-introduce the bug
+we are trying to avoid here (it bypass the trap - shellcheck issue SC2155).
+If the variable should be declared with `local`, `declare`, `readonly`, etc,
+declare it without a value, then set it's value separately (eg: `local var`,
+or `local tmp` in the previous example).
+
 ### Arithmetic expressions
 
-If there is a syntax error in the expression in a condional `((
-expression ))`, it returns 1it does not cause the program to exit. That
-is bad and a source of bugs.
+If there is a syntax error in a conditional expression `(( expression ))`,
+the condition is false-ish; but it will not cause the program to exit
+nor traps to fire. This is generally the case for conditionals
+(eg: `if` statements); but it is a common, yet avoidable source of bugs.
 
 ```
 # Avoid this
@@ -350,7 +360,7 @@
 ## Manual error checking
 
 Explicit handling should
-be done for almost all commands not builtin to bash.
+be done for almost all commands not builtin to BASH.
 
 ```
 set -E -o pipefail
@@ -370,8 +380,8 @@
 fi
 ```
 
-3. If doing a best effort and not exiting on errors, exit code should be
-the higest error.
+If doing a best effort and not exiting on errors, the exit code should be
+the highest error.
 
 ```
 error=0; trap 'error=$(($?>$error?$?:$error))' ERR
@@ -390,8 +400,8 @@
 
 # Misc
 
-Prefer the use of builtins such as the Parameter Expansion functions in
-bash(1) as they are more robust.
+Prefer the use of built-ins such as the Parameter Expansion functions
+(see `info '(bash)Shell Parameter Expansion'`) as they are more robust.
 
 ```
 # Prefer this:
@@ -404,14 +414,14 @@
 ```
 
 
-Avoid eval.
+Avoid `eval`.
 
-Avoid $_. It is easy to alter the environment so it is broken. So far
-seen this happen in interactive shell only.
+Avoid `$_`. It is easy to alter the environment such that it is broken.
+So far, we have seen this happen only in the interactive shell.
 
 When a var might have spaces, double quote it.
 
-When input is generally untrusted, protect against input that starts
+When input is generally un-trusted, protect against input that starts
 with dash.
 
 ```
@@ -419,31 +429,28 @@
 rm -v ./* # a file could be named -rf
 ```
 
-Avoid set -u. empty vars are useful, check for them with [[ $var ]]. set
--u just leads to explicitly setting variables to empty and other hackery
-to avoid unset errors, making it complication that is not worth
-it. shellcheck will find completely unset variables.
+Avoid `set -u`. Empty vars are useful. Check for them with [[ $var ]]. `set
+-u` only leads to explicitly setting variables to empty, and other hackery
+to avoid unset errors - a complication which is not worth the trouble.
+`shellcheck` will find completely unset variables.
 
-Prefer $var except when ${var} is necessary or adds clarity, like 
"comb${x}ining strings"
+Prefer `$var` except when `${var}` is necessary or adds clarity, like 
`"comb${x}ining strings"`.
 
-Never use [. [[ is a special syntax which doesn't do variable expansion
+Never use `[`. `[[` is a special syntax which doesn't do variable expansion
 and avoids edge cases.
 
 Note: ikiwiki has trouble formatting the double bracket below, get the
 raw page with `git svn clone --stdlayout 
svn://svn.savannah.gnu.org/administration/`
 
-
 ```
-[[ $filename == *.png ]] # righthand globs over lefthand. filename has png 
extension
-# Quote only the righthand side when globbing is not desired.
-[[ $filename == "*.png" ]] # filename is literal string "*.png"
+[[ "$filename" == *.png ]] # right-hand globs over left-hand - matches 
filename with .png extension
+# Quote only the right-hand side when globbing is not desired.
+[[ "$filename" == "*.png" ]] # matches filename with literal asterisk "*.png"
 ```
 
-Use double equal for string equality [[ $x == 2 ]]
+Use double-equal for string equality, eg: `[[ "$x" == 2 ]]`.
 
-
-
-Use gnu getopts whenever there is more than one option, or an option and
+Use GNU getopts whenever there is more than one option, or an option and
 an argument. Reference info at:
 /usr/share/doc/util-linux/examples/getopt-parse.bash
 
@@ -484,8 +491,8 @@
 # License
 
 Copying and distribution of this file, with or without modification,
-are permitted in any medium without royalty provided the copyright
-notice and this notice are preserved.  This file is offered as-is,
+are permitted in any medium and without royalty, provided that the copyright
+notice and this notice are preserved. This file is offered as-is,
 without any warranty.
 
 This GNU all-permissive license applies to all the files in this