Updated table formatting, call-outs, html comments, improper escapes.

docs/commands/builtin/caller.md

@@ -8,7 +8,7 @@
 
 The `caller` builtin command is used to print execution frames of
 subroutine calls. Without giving a framenumber, the topmost execution
-frame information is printed (\"who called me\") wile linenumber and
+frame information is printed ("who called me") wile linenumber and
 filename.
 
 When an execution frame number is given (0 - topmost), the linenumber,
@@ -22,10 +22,10 @@ used in a loop (see the examples section below).
 
 The code below defines a function `die` that is used to exit the
 program. It prints a list of execution frames, starting with the topmost
-frame (0). The topmost frame is the \"caller of the die function\", in
-this case function \"f1\".
+frame (0). The topmost frame is the "caller of the die function", in
+this case function "f1".
 
-This way, you can print a \"stack trace\" for debugging or logging
+This way, you can print a "stack trace" for debugging or logging
 purposes.
 
 The code is made very simple, just to show the basic purposes.
@@ -70,9 +70,9 @@ f3
     [Bashdb](http://bashdb.sourceforge.net/) can assist in using some of
     Bash's more advanced debug features.
 -   The Bash manpage and help text specifies that the argument to
-    `caller` is an \"expr\" (whatever that means). Only an integer is
+    `caller` is an "expr" (whatever that means). Only an integer is
     actually allowed, with no special interpretation of an
-    \"expression\" as far as we can tell.
+    "expression" as far as we can tell.
 
 ## Portability considerations
 

docs/commands/builtin/declare.md

@@ -37,28 +37,28 @@ Below, `[-+]X` indicates an attribute, use `-X` to set the attribute,
 
   `[-+]A`   make NAMEs associative arrays
 
-  `[-+]c`   **Undocumented** convert NAMEs to \"capcase\" on assignment (makes the first letter upper-case and the rest lower). Requires Bash built with `-DCASEMOD_CAPCASE`
+  `[-+]c`   **Undocumented** convert NAMEs to "capcase" on assignment (makes the first letter upper-case and the rest lower). Requires Bash built with `-DCASEMOD_CAPCASE`
 
   `-f`      restrict action or display to function names and definitions (removing with `+f` is valid syntax, but leads to an error message)
 
   `-F`      restrict display to function names only (plus line number and source file when debugging)
 
   `-g`      create global variables when used in a shell function; otherwise ignored (by default, `declare` declares local scope variables when used in shell functions)
 
-  `[-+]i`   make NAMEs have the \"integer\" attribute
+  `[-+]i`   make NAMEs have the "integer" attribute
 
   `[-+]l`   convert NAMEs to lower case on assignment (makes sure the variable contains only lower case letters)
 
-  `[-+]n`   make NAME a reference to the variable named by its value. Introduced in Bash 4.3-alpha.\
-            \'\' \${!NAME}\'\' reveals the reference variable name, VALUE.\
-            Use `unset -n NAME` to unset the variable. (`unset -v NAME` unsets the VALUE variable.)\
+  `[-+]n`   make NAME a reference to the variable named by its value. Introduced in Bash 4.3-alpha.
+            ''`${!NAME}`'' reveals the reference variable name, VALUE.
+            Use `unset -n NAME` to unset the variable. (`unset -v NAME` unsets the VALUE variable.)
             Use `[[ -R NAME ]]` to test if NAME has been set to a VALUE, another variable's name.
 
   `-p`      display the attributes and value of each NAME
 
   `[-+]r`   make NAMEs readonly (removing with `+r` is valid syntax, but not possible)
 
-  `[-+]t`   make NAMEs have the \"trace\" attribute (effective only for functions)
+  `[-+]t`   make NAMEs have the "trace" attribute (effective only for functions)
 
   `[-+]u`   convert NAMEs to upper case on assignment (makes sure the variable contains only upper case letters)
 
@@ -76,13 +76,13 @@ Below, `[-+]X` indicates an attribute, use `-X` to set the attribute,
   != 0     assignment to a readonly variable
   != 0     removing the readonly-attribute from a readonly variable
   != 0     assignment to an array variable without the compound assignment syntax (`array=(...)`)
-  != 0     attempt to use `+a` to \"destroy\" an array
+  != 0     attempt to use `+a` to "destroy" an array
   != 0     attemt to display a non-existent function with `-f`
 
 ## Notes
 
 Unix shells offer very few datatypes. Bash and some other shells extend
-this by allowing \"attributes\" to be set on variable names. The only
+this by allowing "attributes" to be set on variable names. The only
 attributes specified by POSIX are `export` and `readonly`, which are set
 by their own dedicated builtins. Datatypes in bash have a few other
 interesting capabilities such as the ability to modify data on
@@ -92,23 +92,23 @@ assignment.
 
 ### Display defined functions
 
-`declare -f` can be used to display all defined functions\...
+`declare -f` can be used to display all defined functions...
 
     $ declare -f
-    foo () 
-    { 
+    foo ()
+    {
         echo "FOO is BAR"
     }
-    world () 
-    { 
+    world ()
+    {
         echo "Hello World!"
     }
 
-\...or just a specific defined function.
+...or just a specific defined function.
 
     $ declare -f foo
-    foo () 
-    { 
+    foo ()
+    {
         echo "FOO is BAR"
     }
 
@@ -172,7 +172,7 @@ for details. ksh93 namerefs are much more powerful than Bash's.
     considers `typeset` a special builtin, while Bash does not - even in
     POSIX mode. If you use `typeset`, you should attempt to only use it
     in portable ways.
--   **todo** nameref portability\...
+-   **todo** nameref portability...
 
 ## See also
 

docs/commands/builtin/echo.md

@@ -29,7 +29,7 @@ if given.
   `\a`           alert (bell)
   `\b`           backspace
   `\c`           suppress further output
-  `\e`           
+  `\e`
   `\E`           an escape character
   `\f`           form feed
   `\n`           new line
@@ -56,17 +56,14 @@ if given.
     case `-n` is always treated as a string, and backslash escapes are
     interpreted by default. `dash` has the misfeature of following this
     and interpreting escapes by default, but includes a `-n` feature for
-    suppressing newlines nevertheless.\
-    \
-    In practice, if you\'re able to assume a korn-like shell including
+    suppressing newlines nevertheless.
+
+    In practice, if you're able to assume a korn-like shell including
     bash, mksh, or zsh, `echo` when used in simple cases is generally
     reliable. For example, in the very common situation in which echo is
     supplied with a single argument and whose output is to have a
     newline appended, using `echo` is considered common practice.
 
-```{=html}
-<!-- -->
-```
 -   **Never use options to `echo`! *Ever*!** Any time you feel tempted
     to use `echo -e`, `-n`, or any other special feature of echo, **use
     [printf](../../commands/builtin/printf.md) instead!** If portability is a
@@ -76,9 +73,6 @@ if given.
     \$\'\...\' \'\'if targeting only shells that support this special
     quoting style.
 
-```{=html}
-<!-- -->
-```
 -   `ksh93` has a `print` command, which if coding specifically for
     `ksh93` should be preferred over `echo`.
     [printf](../../commands/builtin/printf.md) still includes most of the

docs/commands/builtin/eval.md

@@ -55,7 +55,7 @@ This code defines a set of identical functions using the supplied names.
 ### Using printf %q
 
 The `printf %q` format string performs shell escaping on its arguments.
-This makes `printf %q` the \"anti-eval\" - with each pass of a string
+This makes `printf %q` the "anti-eval" - with each pass of a string
 through printf requiring another `eval` to peel off the escaping again.
 
     while (( ++n <= 5 )) || ! evalBall="eval $evalBall"; do
@@ -112,16 +112,11 @@ controlled carefully by the caller is a good way to use it.
     `setopt POSIX_BUILTINS` -- looks like a regression). This works
     correctly in Bash POSIX mode, Dash, and mksh.
 
-```{=html}
-<!-- -->
-```
 -   `eval` is another one of the few Bash builtins with keyword-like
     conditional parsing of arguments that are in the form of compound
     assignments.
 
-```{=html}
-<!-- -->
-```
+
      $ ( eval a=( a b\\ c d ); printf '<%s> ' "${a[@]}"; echo ) # Only works in Bash.
     <a> <b c> <d>
      $ ( x=a; eval "$x"=( a b\\ c d ); printf '<%s> ' "${a[@]}"; echo ) # Argument is no longer in the form of a valid assignment, therefore ordinary parsing rules apply.
@@ -168,7 +163,7 @@ identical to those of [let](../../commands/builtin/let.md).
     eval](http://mywiki.wooledge.org/BashFAQ/006#Assigning_indirect.2BAC8-reference_variables)
 -   [More indirection via
     eval](http://fvue.nl/wiki/Bash:_Passing_variables_by_reference)
--   [Martin Väth's \"push\"](https://github.com/vaeth/push) --
+-   [Martin Väth's "push"](https://github.com/vaeth/push) --
     `printf %q` work-alike for POSIX.
--   [The \"magic alias\"
+-   [The "magic alias"
     hack](http://www.chiark.greenend.org.uk/~sgtatham/aliases.html)

docs/commands/builtin/kill.md

@@ -27,7 +27,7 @@ The `kill` command is a Bash builtin command instead of relying on the
 external `kill` command of the operating system to
 
 -   be able to use shell job specifications instead of Unix process IDs
--   be able to send signals (\"kill something\") also, when your process
+-   be able to send signals ("kill something") also, when your process
     limit is reached
 
 ### Options

docs/commands/builtin/let.md

@@ -10,8 +10,8 @@ The `let` builtin command evaluates each supplied word from left to
 right as an [arithmetic expression](../../syntax/arith_expr.md) and returns an
 exit code according to the truth value of the rightmost expression.
 
--   0 (TRUE) when `arg` evaluated to not 0 (arithmetic \"true\")
--   1 (FALSE) when `arg` evaluated to 0 (arithmetic \"false\")
+-   0 (TRUE) when `arg` evaluated to not 0 (arithmetic "true")
+-   1 (FALSE) when `arg` evaluated to 0 (arithmetic "false")
 
 For this return code mapping, please see [this
 section](../../syntax/arith_expr.md#arithmetic_expressions_and_return_codes).
@@ -50,7 +50,7 @@ used above only to illustrate how this precedence works. </WRAP>
 
 Unlike `((`, being a simple command `let` has its own environment. In
 Bash, built-ins that can set variables process any arithmetic under
-their own environment, which makes the variable effectively \"local\" to
+their own environment, which makes the variable effectively "local" to
 the builtin unless the variable is also set or modified by the builtin.
 This differs in other shells, such as ksh93, where environment
 assignments to regular builtins are always local even if the variable is
@@ -84,7 +84,7 @@ needed.
     choose `let` over `((` expecting it to work in more places.
 -   [expr(1)](http://pubs.opengroup.org/onlinepubs/9699919799/utilities/expr.html#tag_20_42)
     is a command one is likely to come across sooner or later. While it
-    is more \"standard\" than `let`, the above should always be
+    is more "standard" than `let`, the above should always be
     preferred. Both [arithmetic expansion](../../syntax/arith_expr.md)s and the
     `[` test operator are specified by POSIX(r) and satisfy almost all
     of expr's use-cases. Unlike `let`, `expr` cannot assign directly to
@@ -108,4 +108,4 @@ needed.
 -   Internal: [arithmetic evaluation compound
     command](../../syntax/ccmd/arithmetic_eval.md)
 
-[^1]: \...
+[^1]: ...

docs/commands/builtin/local.md

@@ -30,26 +30,20 @@ way, and takes all the same options, with 3 exceptions:
     have a builtin called `local`, but some such as `dash` and the
     busybox shell do.
 
-```{=html}
-<!-- -->
-```
 -   The behavior of function scope is not defined by POSIX, however
     local variables are implemented widely by bourne-like shells, and
     behavior differs substantially. Even the`dash` shell has local
     variables.
 
-```{=html}
-<!-- -->
-```
 -   In ksh93, using POSIX-style function definitions, `typeset` doesn't
     set `local` variables, but rather acts upon variables of the
     next-outermost scope (e.g. setting attributes). Using `typeset`
     within functions defined using ksh `function name {` syntax,
     variables follow roughly
     [lexical-scoping](http://community.schemewiki.org/?lexical-scope),
     except that functions themselves don't have scope, just like Bash.
-    This means that even functions defined within a \"function's
-    scope\" don't have access to non-local variables except through
+    This means that even functions defined within a "function's
+    scope" don't have access to non-local variables except through
     `namerefs`.
 
 ## See also

docs/commands/builtin/mapfile.md

@@ -14,7 +14,7 @@ This builtin is also accessible using the command name `readarray`.
 handling standard input (the other being `read`). `mapfile` reads lines
 of standard input and assigns each to the elements of an indexed array.
 If no array name is given, the default array name is `MAPFILE`. The
-target array must be a \"normal\" integer indexed array.
+target array must be a "normal" integer indexed array.
 
 `mapfile` returns success (0) unless an invalid option is given or the
 given array `ARRAY` is set readonly.
@@ -47,9 +47,9 @@ Here's a real-world example of interactive use borrowed from Gentoo
 workflow. Xorg updates require rebuilding drivers, and the
 Gentoo-suggested command is less than ideal, so let's Bashify it. The
 first command produces a list of packages, one per line. We can read
-those into the array named \"args\" using `mapfile`, stripping trailing
-newlines with the \'-t\' option. The resulting array is then expanded
-into the arguments of the \"emerge\" command - an interface to Gentoo's
+those into the array named "args" using `mapfile`, stripping trailing
+newlines with the '`-t`' option. The resulting array is then expanded
+into the arguments of the `emerge` command - an interface to Gentoo's
 package manager. This type of usage can make for a safe and effective
 replacement for xargs(1) in certain situations. Unlike xargs, all
 arguments are guaranteed to be passed to a single invocation of the
@@ -59,7 +59,7 @@ business.
     # eix --only-names -IC x11-drivers | { mapfile -t args; emerge -av1 "${args[@]}" <&1; }
 
 Note the use of command grouping to keep the emerge command inside the
-pipe's subshell and within the scope of \"args\". Also note the unusual
+pipe's subshell and within the scope of "args". Also note the unusual
 redirection. This is because the -a flag makes emerge interactive,
 asking the user for confirmation before continuing, and checking with
 isatty(3) to abort if stdin isn't pointed at a terminal. Since stdin of
@@ -71,11 +71,11 @@ wiki: <http://mywiki.wooledge.org/BashFAQ/024>
 ### The callback
 
 This is one of the more unusual features of a Bash builtin. As far as
-I\'m able to tell, the exact behavior is as follows: If defined, as each
+I'm able to tell, the exact behavior is as follows: If defined, as each
 line is read, the code contained within the string argument to the -C
 flag is evaluated and executed *before* the assignment of each array
 element. There are no restrictions to this string, which can be any
-arbitrary code, however, two additional \"words\" are automatically
+arbitrary code, however, two additional "words" are automatically
 appended to the end before evaluation: the index, and corresponding line
 of data to be assigned to the next array element. Since all this happens
 before assignment, the callback feature cannot be used to modify the
@@ -91,9 +91,9 @@ the appended words from printf.
 
 Really, the intended usage is for the callback to just contain the name
 of a function, with the extra words passed to it as arguments. If
-you\'re going to use callbacks at all, this is probably the best way
-because it allows for easy access to the arguments with no ugly \"code
-in a string\".
+you're going to use callbacks at all, this is probably the best way
+because it allows for easy access to the arguments with no ugly "code
+in a string".
 
     $ foo() { echo "|$1|"; }; mapfile -n 11 -c 2 -C 'foo' <file
     |2|
@@ -121,13 +121,13 @@ illustrates the callback behavior:
 
 Since redirects are syntactically allowed anywhere in a command, we put
 it before the printf to stay out of the way of additional arguments.
-Rather than opening \"outfile<n>\" for appending on each call by
+Rather than opening "outfile&lt;n&gt;" for appending on each call by
 calculating the filename, open an FD for each first and calculate which
 FD to send output to by measuring the size of x mod 2. The zero-width
 format specification is used to absorb the index number argument.
 
 Another variation might be to add each of these lines to the elements of
-separate arrays. I\'ll leave dissecting this one as an exercise for the
+separate arrays. I'll leave dissecting this one as an exercise for the
 reader. This is quite the hack but illustrates some interesting
 properties of printf -v and mapfile -C (which you should probably never
 use in real code).
@@ -147,7 +147,7 @@ use in real code).
 
 This example based on yet another #bash question illustrates mapfile in
 combination with read. The sample input is the heredoc to `main`. The
-goal is to build a \"struct\" based upon records in the input file made
+goal is to build a "struct" based upon records in the input file made
 up of the numbers following the colon on each line. Every 3rd line is a
 key followed by 2 corresponding fields. The showRecord function takes a
 key and returns the record.