From 2d885fc8f57a9592c2cfa5502ff591a8a42da2ac Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Sat, 22 Oct 2016 17:48:52 +0200
Subject: Update bash style guide

---
 doc/bash-style.cli | 35 ++++++++++++++++++++++++-----------
 1 file changed, 24 insertions(+), 11 deletions(-)

diff --git a/doc/bash-style.cli b/doc/bash-style.cli
index 67f9da2..347a859 100644
--- a/doc/bash-style.cli
+++ b/doc/bash-style.cli
@@ -121,7 +121,7 @@ example:
 
 \
 quiet=\"n\"
-tools=\"/usr/local\"
+tools=/usr/local
 file=
 \
 
@@ -142,7 +142,7 @@ while [ \"$#\" -gt 0 ]; do
       shift
       ;;
     *)
-      if [ -n \"$1\" ]; then
+      if [ -n \"$file\" ]; then
         error \"$usage\"
       fi
 
@@ -153,6 +153,9 @@ while [ \"$#\" -gt 0 ]; do
 done
 \
 
+If the value you are expecting from the command line is a directory path,
+the always strip the trailing slash (as shown above for the \c{-t} option).
+
 \h#struct-opt-arg-valid|OPTIONS-ARGUMENTS-VALIDATION|
 
 Validate option/argument values. For example:
@@ -183,12 +186,6 @@ if [ -n \"$foo\" ]; then
 fi
 \
 
-We also quote every variable assignment:
-
-\
-quiet=\"y\"
-\
-
 This also applies to command substitution (which we always write as
 \c{$(foo arg)} rather than \c{`foo arg`}), for example:
 
@@ -202,6 +199,22 @@ Note that a command substitution creates a new quoting context, for example:
 list=\"$(basename \"$1\")\"
 \
 
+We also quote values that are \i{strings} as opposed to options/file names,
+paths, or integers. If setting a variable that will contain one of these
+unquoted value, try to give it a name that reflects its type (e.g.,
+\c{foo_file} rather than \c{foo_name}). Prefer single quotes for \c{sed}
+scripts, for example:
+
+\
+proto=\"https\"
+quiet=\"y\"
+verbosity=1
+dir=/etc
+out=/dev/null
+file=manifest
+seds='s%^./%%'
+\
+
 Note that quoting will inhibit globbing so you may end up with expansions
 along these lines:
 
@@ -251,11 +264,11 @@ any command fails. If you need to check the exit status of a command, use
 \c{if}, for example:
 
 \
-if grep \"foo\" \"bar\"; then
+if grep \"foo\" /tmp/bar; then
   info \"found\"
 fi
 
-if ! grep \"foo\" \"bar\"; then
+if ! grep \"foo\" /tmp/bar; then
   info \"not found\"
 fi
 \
@@ -302,7 +315,7 @@ function dist()
 
 If the evaluation of the value may fail (e.g., it contains a program
 substitution), then place the assignment on a separate line since \c{local}
-will ignore the error. For example
+will cause the error to be ignore. For example:
 
 \
 function dist()
-- 
cgit v1.1