[doc/error-catalog] Add 3 hints related to \ escaping

Addresses issues in pull request #1824.

Now we have 4 hints!

doc/error-catalog.md

@@ -29,7 +29,8 @@ If you see an error that you don't understand:
    one used.
 1. Add a tagged section below, with hints and explanations.
    - Quote the error message.  You may want copy and paste from the output of
-     `test/{parse,runtime,ysh-parse,ysh-runtime}-errors.sh`.
+     `test/{parse,runtime,ysh-parse,ysh-runtime}-errors.sh`.  Add an HTML
+     comment `<!-- -->` about it if you do so.
    - Link to relevant sections in the [**Oils Reference**](ref/index.html).
 1. Optionally, add your name to the acknowledgements list at the end of this
    doc.
@@ -64,6 +65,11 @@ These error codes start at `10`.
 
 ### OILS-ERR-10
 
+<!--
+Generated with:
+test/ysh-parse-errors.sh test-func-var-checker
+-->
+
 ```
       setvar x = true
              ^
@@ -77,7 +83,52 @@ These error codes start at `10`.
 
 ### OILS-ERR-11
 
-Invalid char escape.
+<!--
+Generated with:
+test/ysh-parse-errors.sh ysh_c_strings (this may move)
+-->
+
+```
+  echo $'\z'
+         ^
+[ -c flag ]:1: Invalid char escape in C-style string literal (OILS-ERR-11)
+```
+
+- Did you mean `$'\\z'`?  Backslashes must be escaped in `$''` and `u''` and
+  `b''` strings.
+- Did you mean something like `$'\n'`?  Only valid escapes are accepted in YSH.
+
+### OILS-ERR-12
+
+<!--
+Generated with:
+test/ysh-parse-errors.sh ysh_dq_strings (this may move)
+-->
+
+```
+  echo "\z"
+        ^
+[ -c flag ]:1: Invalid char escape in double quoted string (OILS-ERR-12)
+```
+
+- Did you mean `"\\z"`?  Backslashes must be escaped in double-quoted strings.
+- Did you mean something like `"\$"`?  Only valid escapes are accepted in YSH.
+
+### OILS-ERR-13
+
+<!--
+Generated with:
+test/ysh-parse-errors.sh ysh_bare_words (this may move)
+-->
+
+```
+  echo \z
+       ^~
+[ -c flag ]:1: Invalid char escape in unquoted word (OILS-ERR-13)
+```
+
+- Did you mean `\\z`?  Backslashes must be escaped in unquoted words.
+- Did you mean something like `\$`?  Only valid escapes are accepted in YSH.
 
 ## Runtime Errors - Traditional Shell
 

osh/cmd_parse.py

@@ -446,8 +446,9 @@ def Check(self, keyword_id, name_tok):
         if keyword_id == Id.KW_SetVar:
             if name not in top:
                 # Note: the solution could be setglobal, etc.
-                p_die("setvar couldn't find matching 'var %s' (OILS-ERR-10)" %
-                      name, name_tok)
+                p_die(
+                    "setvar couldn't find matching 'var %s' (OILS-ERR-10)" %
+                    name, name_tok)
 
 
 class ctx_VarChecker(object):

osh/word_parse.py

@@ -667,7 +667,9 @@ def ReadSingleQuoted(self, lex_mode, left_token, tokens, is_ysh_expr):
 
                 # x = $'\z' is disallowed; ditto for echo $'\z' if shopt -u parse_backslash
                 if is_ysh_expr or not self.parse_opts.parse_backslash():
-                    p_die("Invalid char escape in C-style string literal", tok)
+                    p_die(
+                        "Invalid char escape in C-style string literal (OILS-ERR-11)",
+                        tok)
 
                 tokens.append(tok)
 
@@ -944,7 +946,7 @@ def _ReadLikeDQ(self, left_token, is_ysh_expr, out_parts):
                         if (is_ysh_expr or
                                 not self.parse_opts.parse_backslash()):
                             p_die(
-                                "Invalid char escape in double quoted string",
+                                "Invalid char escape in double quoted string (OILS-ERR-12)",
                                 self.cur_token)
                     elif self.token_type == Id.Lit_Dollar:
                         if is_ysh_expr or not self.parse_opts.parse_dollar():
@@ -1611,7 +1613,7 @@ def _MaybeReadWordPart(self, is_first, lex_mode, parts):
             ch = lexer.TokenSliceLeft(tok, 1)
             if not self.parse_opts.parse_backslash():
                 if not pyutil.IsValidCharEscape(ch):
-                    p_die('Invalid char escape (parse_backslash)',
+                    p_die('Invalid char escape in unquoted word (OILS-ERR-13)',
                           self.cur_token)
 
             part = word_part.EscapedLiteral(self.cur_token,

test/parse-errors.sh

@@ -654,7 +654,7 @@ extra-newlines() {
   '
 }
 
-ysh_string_literals() {
+ysh_c_strings() {
   set +o errexit
 
   # bash syntax
@@ -682,6 +682,10 @@ EOF
 echo $'\z'
 EOF
   _ysh-parse-error-here <<'EOF'
+echo $'\z'
+EOF
+  # Expression mode
+  _ysh-parse-error-here <<'EOF'
 const bad = $'\z'
 EOF
 
@@ -696,27 +700,6 @@ EOF
   # \xH not allowed
   _ysh-parse-error-here <<'EOF'
 const bad = c'\xf'
-EOF
-
-  _should-parse 'echo "\z"'
-  # Double quoted is an error
-  _assert-status-2 +O parse_backslash -n -c 'echo parse_backslash "\z"'
-  _ysh-parse-error 'echo "\z"'  # not in Oil
-  _ysh-parse-error 'const bad = "\z"'  # not in expression mode
-
-  # C style escapes not respected
-  _should-parse 'echo "\u1234"'  # ok in OSH
-  _ysh-parse-error 'echo "\u1234"'  # not in Oil
-  _ysh-parse-error 'const bad = "\u1234"'
-
-  _should-parse 'echo "`echo hi`"'
-  _ysh-parse-error 'echo "`echo hi`"'
-  _ysh-parse-error 'const bad = "`echo hi`"'
-
-  _ysh-parse-error 'setvar x = "\z"'
-
-  _ysh-parse-error-here <<'EOF'
-setvar x = $'\z'
 EOF
 }
 
@@ -746,7 +729,35 @@ EOF
 setvar x = $'trailing\
 '
 EOF
+}
+
+ysh_dq_strings() {
+  set +o errexit
+
+  # Double quoted is an error
+  _should-parse 'echo "\z"'
+  _assert-status-2 +O parse_backslash -n -c 'echo parse_backslash "\z"'
+
+  _ysh-parse-error 'echo "\z"'  # not in Oil
+  _ysh-parse-error 'const bad = "\z"'  # not in expression mode
+
+  # C style escapes not respected
+  _should-parse 'echo "\u1234"'  # ok in OSH
+  _ysh-parse-error 'echo "\u1234"'  # not in Oil
+  _ysh-parse-error 'const bad = "\u1234"'
+
+  _should-parse 'echo "`echo hi`"'
+  _ysh-parse-error 'echo "`echo hi`"'
+  _ysh-parse-error 'const bad = "`echo hi`"'
+
+  _ysh-parse-error 'setvar x = "\z"'
+}
+
+ysh_bare_words() {
+  set +o errexit
 
+  _ysh-should-parse 'echo \$'
+  _ysh-parse-error 'echo \z'
 }
 
 parse_backticks() {
@@ -937,8 +948,10 @@ cases-in-strings() {
   regex_literals
   proc_sig
   proc_arg_list
-  ysh_string_literals
+  ysh_c_strings
   test_bug_1825_backslashes
+  ysh_dq_strings
+  ysh_bare_words
 
   parse_backticks
   parse_dollar