refactor/3.5d examples

CHANGELOG.md

@@ -29,14 +29,14 @@
 - Options before a subcommand are read as the tool reads them (`docker -H h run`, `npm --prefix dir run build`, `yarn --cwd dir add`, `kubectl -o yaml get pods`, `gh -R o/r pr list`), and a tool's global options are told apart from its subcommands' (`kubectl logs -o` is not an option; terraform takes only `-chdir=DIR`, `-version` and `-help` before the subcommand).
 - The pitfall for a variable that another shell does not have (`bash -c`, `sudo`, `su -c`, `ssh`, `docker exec`) reads the string as that shell reads it, so `\$n` in `bash -c "echo \$n"` counts; `env -u x` removes `x`, and a shell that reads startup files (`bash -l`, an exported `BASH_ENV`) may have any name. The shell and env's `-i`, `-u` and `NAME=value` count in an `env -S` string too (`env -S'-i bash -c' '…'`). Before, an escaped `\$n` was missed, and a shell started from an `env -S` string was not known.
 - `test` reads no options, as bash: in `test 1 -eq 2 --version`, `-eq` and `--version` are words of the expression (bash says "`--version' unexpected"). Before, they were shown as options.
-- A long option may be shortened to a unique prefix, as GNU tools allow, in `grep`, `sed`, GNU coreutils (`ls`, `cp`, `sort`, `tail`, `du`…), diffutils (`diff`, `cmp`), `gzip` and `tar`: `grep --invert` is `--invert-match`, `ls --almost` is `--almost-all`. These commands also know every long option of their `--help`. A prefix the tool finds ambiguous is shown as such. Before, these were "not in the dictionary". `grep` also knows `-G`, `--colour`, `--binary-files`, `--exclude-from` and the group separator options. `xargs --max-lines` and `mktemp --tmpdir` take a value only after `=`, as the tools do: in `xargs --max-lines echo`, `echo` is the command; before, it was taken for the value. Likewise `od -w f` reads `f` as input (before, as the width), and `install -t d a b` copies `a` and `b` into `d` (before, `-t` was unknown and `d` a file to copy).
+- A long option may be shortened to a unique prefix, as GNU tools allow, in `grep`, `sed`, GNU coreutils (`ls`, `cp`, `sort`, `tail`, `du`…), diffutils (`diff`, `cmp`), `gzip` and `tar`: `grep --invert` is `--invert-match`, `ls --almost` is `--almost-all`. These commands also know every long option of their `--help`. A prefix the tool finds ambiguous is shown as such. Before, these were "not in the dictionary". `grep` also knows `-G`, `--colour`, `--binary-files`, `--exclude-from` and the group separator options. `xargs --max-lines` and `mktemp --tmpdir` take a value only after `=`, as the tools do: in `xargs --max-lines echo`, `echo` is the command; before, it was taken for the value. Likewise `od -w f` reads `f` as input (before, as the width), and `install -t d a b` copies `a` and `b` into `d` (before, `-t` was unknown and `d` a file to copy). `seq -w -2 2` reads `-2` as the first number (before, an unknown option), `tail +2` is `-n +2` (before, a file), `tr -C` is `-c`, and `cut -n` is known. In `awk 'NR>1' f -v` and `perl -ne '…' f -l`, the last word is a file, as the options end at the program (perl: at its first file); before, it was an option. Likewise `getopt -o a x -u` passes `-u` on to be parsed. perl's `-l0` and `-0777` take their digits, and `-0ne` is `-0 -n -e` (before, `ne` was the value of `-0`). `git log --max-count 2` is known.
 - In `kubectl`, `helm` and `gh`, a short option written with `=` takes what follows the `=` as its value, as these tools read it: `gh pr list -R=o/r` names the repository `o/r`. Before, the value was shown as `=o/r`.
 - `openssl` reads `--name` as `-name`, as OpenSSL does: in `openssl rand --hex 4`, `--hex` is `-hex`. Before, it was an unknown option.
 - `grep -E -F` (two different matchers of `-E`, `-F`, `-G`, `-P`) says that grep refuses the line with "conflicting matchers specified" and exit status 2, and so does `tar -c -x` ("You may not specify more than one…"). Such a line gets no example, and grep's pattern is not read as a regex. Before, it was explained, with its example, as a search with one of the matchers, and tar's line as one of the operations.
 - `bash -O extglob -c '…'` and `bash --posix` are read as bash's options. Before, `-O` was not known and `extglob` was taken for the script to run.
 - Quick fixes (the rewrites offered for dialect warnings) are offered in every language of the `bashExplainer.languages` setting, and follow a change of that setting, as the hover does. Before, they were offered in `shellscript` documents only.
 - `"$@"` inside single quotes is text, so the words after `bash -c 'f "$@"'` are no longer said to depend on how many words it gives.
-- Examples and dialect checks read a command's options as the command reads them. `grep -e -v foo` searches for `-v`; its example said `-v` inverts the match. `sed -ie 's/a/b/' -e 's/c/d/' f` runs only `s/c/d/`, since `e` is the backup suffix of `-i`; the example ran both scripts. `sed -i.bak` now shows the file rewritten. The input of `grep -efoo data.txt | sort` and `awk '{ print }' v=1 | sort` is labelled as it is read (a file, then stdin), and a pipeline whose later stage reads a file instead of the pipe (`printf … | grep -e -v foo`) gets no whole-pipeline example. `tr --delete` is `-d`, and `find … -exec cmd {} '+'` runs the command once, quoted or not. The dialect check no longer takes `read -p -a v` for `read -a` (`-a` is the prompt), and finds `trap ERR`.
+- Examples and dialect checks read a command's options as the command reads them. `grep -e -v foo` searches for `-v`; its example said `-v` inverts the match. `sed -ie 's/a/b/' -e 's/c/d/' f` runs only `s/c/d/`, since `e` is the backup suffix of `-i`; the example ran both scripts. `sed -i.bak` now shows the file rewritten. The input of `grep -efoo data.txt | sort` and `awk '{ print }' v=1 | sort` is labelled as it is read (a file, then stdin), and a pipeline whose later stage reads a file instead of the pipe (`printf … | grep -e -v foo`) gets no whole-pipeline example. `tr --delete` is `-d`, and `find … -exec cmd {} '+'` runs the command once, quoted or not. The dialect check no longer takes `read -p -a v` for `read -a` (`-a` is the prompt), and finds `trap ERR`. The examples of sort, uniq, cut, tr, head, tail, seq, basename, dirname, wc, xargs, sed, grep, awk, perl and `read` read the options as the explanation does, so a long prefix (`sort --rev`, `sed --expr`), `tail +2` and `tr -C` now get an example. `xargs --replace echo {}` and `xargs --max-lines echo` run `echo` (before, `echo` was taken for the value), and `-i`, `-l` are followed. `seq 1 -w 3`, which seq refuses, gets no example; before, it showed output. `cat -n`, `tac -s x` and `rev FILE` in a pipeline, and `cat -n f | sort`, get no example; before, the example passed the input on as if they had no option. The `git log` example shows as many commits as `--max-count 2` asks (before, 3).
 - Explanations match bash in more places: `x=1 ''` (a command name that is not found, so `x` is not set), the variables that `exec {fd}>file`, `wait -p var` and `coproc name` set, and an error in `$(( ))` (a division by 0) or an assignment to a readonly variable, which discards the rest of the line, also when it is in a function the line calls (before, only the rest of the command, or nothing). A name written in the option's own word (`printf -vx 2`, `read -rax`, `wait -n -px`) is the variable set (before, `x` kept its old value, and a condition on it could be called decided), and `wait -p x` unsets `x` before it sets it (before, `x` kept its old value when no job ended). `exec cmd` in `( )` or `$( )` says that it ends only the subshell (before, it said nothing of the subshell). `'exit' 3` with quotes has its exit status known, 3, as `exit 3` has (before, it was the status of an unknown command). `$(true)`, `$(:)` and `$(false)` count as empty only where the name runs the builtin, not after `true() { echo a; }`, an alias of it or `enable -n true` (before, `x=$(true)` was taken to set `x` to nothing there). Functions defined after `set -a +a` or `set foo -a` (where `-a` is an argument) are not exported, so conditions in them are decided (before, none were). In a function whose every call is in a subshell (`m() { cd /tmp; }; echo | m`), `cd` says "It may run in a subshell (where its function is called; what the script does not show may call it too)" when a sourced file, a trap's action or an alias may also call the function (before, "It runs in a subshell", although `. ./lib.sh` may call it in the shell itself); a word that names the function without calling it (`command m`, `declare -f m`, `type m`) no longer turns this into "may" (before, it did). `cmd &> >(tee log)` and `&>> >(…)` send both outputs to the process substitution, also after a block or a loop (`{ …; } &> >(tee log)`, `done &> >(tee log)`) and before the command name (`&> >(tee log) cmd`) (before, it was read as an argument of the command, and the redirection as missing its target; after a block or a loop it was a syntax error, and before the name it was the command).
 - `unset f` says it removes the function when there is no variable `f`, as bash does. A pipeline whose stage is a function or an alias of the script (`sort() { tac; }; … | sort`) no longer shows the output of the program of that name as an example. Before, the first said "Unset the variable" and the second showed the output of the program, which the function does not give.
 - The ⚠ notes on words and pipelines follow what bash does here. After `IFS=; set -f`, `cp $a b` no longer says that `$a` is split (the token already said it is not); `X=1 echo "\$X"` no longer warns that `$X` is expanded first (`\$X` is text); a variable set by `((count++))`, `printf -v` or `mapfile` at the end of a pipeline, or by a function called there, is now reported as lost after it, and `echo '$n'` no longer counts as a later read. An alias of `rm` is taken for `rm`.