Merge remote-tracking branch 'origin/master' into 5.9

Right now, as we're preparing to tag the 5.8 release, the 5.9 branch is
maintained as a topic branch off master.

* origin/master:
  45287: zshexpn: Describe parameter elision and add some introductory prose
  45302: bin_umask(): Queue signals around umask().
  users/24656: docs: Add an example of setting and querying zstyles
  users/24659: Cross-ref doc for matchers.
  45296: D02glob: Clean up after test from users/24633
  45290: New helper script for listing XFail tests.
  users/24633: Add an xfail test for users/24619.
  unposted: additional typo fix
  45280: _git: add -local variants
  users/24628 (fixed): More doc for selectw-word-style widgets.
  45266: Fix losetup completion, broken in da085b7a20729401c725f91ae930200d0deda64f (41720).
  unposted: Fix punctuation.
  use /dev/fd on Cygwin for process substitution
  unposted: Two additional typo fixes.
  Fix typos reported by codespell in shell code
  Fix typos reported by codespell in Src/
  45269: Fix misspellings in completions and elsewhere.
  45261: _gcc: Detect clang-as-gcc
  unposted: internal: Remove Vim modeline that interferes with ztst.vim.
  unposted: internal: ztst.vim: Use :syn-sync to work around (#x) and "`\\\\\\\\`" confusing the highlighting.
  unposted: internal: zyodl.vim: Support glob qualifiers in example()'s
  unposted: internal: zyodl.vim: Support yodl comments.
  github #44: Allow completion for picocom to list symlinks to character devices
  45245: _gcc: add some clang specific warnings
  45231: _rsync: When completing remote modules, ignore more of the motd.
  unposted: _tac: Eliminate superfluous variable
  45226: _man: Improve completion of file paths
  45184: Clarify documentation of %-sequences understood by compadd -[Xx]
  45239: Remove 'appendhistory' from zsh-newuser-install
  45218: add more options to swaks completion
  45196: fix completion after make -C, allowing for -C being used multiple times
  unposted (after 45183): Fix yodl error: "contrib.yo:4457: No macro: back(...)".
  45181: Fix workers/45164: ${(S)%%} will now consider the empty string as a potential match.
  45183: Improve documentation examples
  unposted: Add some tests for ${(S)}, including a regression test for workers/45164.
  45169/0002 (tweaked for trailing newlines): Add an expected-to-fail test for workers/44007.
  45169/0001: In the test suite, allow test cases to be marked as expected to fail.
  users/24582 + users/24583: Add regression tests for the previous commit.
  24581: Fix array assignments in shell word splitting and completion.
  45160: zshexpn: Expand documentation of (S)
  45150 + 45152: zshexpn: Use a more minimal example in the documentation of (#b).
  unposted: internal: Vim ztst support: Add an ftplugin in addition to the syntax highlighter.
  45130: _multi_parts: Always pass -f to compadd if given by caller
  unposted: zerrmsg(): Fix macro guard missed in previous commit
  unposted: ChangeLog for last commit
  internal: Allow %L in zerrmsg() in non-debug builds, too.

1 files changed, 69 insertions, 30 deletions

diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index d7147dbd7..c129b4228 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -400,7 +400,7 @@ backslashes.
 For example, the following piece of filename generation code
 with the tt(EXTENDED_GLOB) option:
 
-example(print *.c+LPAR()#q:s/#%+LPAR()#b+RPAR()s+LPAR()*+RPAR().c/'S${match[1]}.C'/+RPAR())
+example(print -r -- *.c+LPAR()#q:s/#%+LPAR()#b+RPAR()s+LPAR()*+RPAR().c/'S${match[1]}.C'/+RPAR())
 
 takes the expansion of tt(*.c) and applies the glob qualifiers in the
 tt(LPAR()#q)var(...)tt(RPAR()) expression, which consists of a substitution
@@ -582,7 +582,25 @@ and subscript notation to access individual array elements.
 Note in particular the fact that words of unquoted parameters are not
 automatically split on whitespace unless the option tt(SH_WORD_SPLIT) is
 set; see references to this option below for more details.  This is an
-important difference from other shells.
+important difference from other shells.  However, as in other shells,
+null words are elided from unquoted parameters' expansions.
+
+With default options, after the assignments:
+
+example(array=("first word" "" "third word")
+scalar="only word")
+
+then tt($array) substitutes two words, `tt(first word)' and `tt(third
+word)', and tt($scalar) substitutes a single word `tt(only word)'.  Note
+that second element of tt(array) was elided.  Scalar parameters can
+be elided too if their value is null (empty).  To avoid elision, use quoting as
+follows: tt("$scalar") for scalars and tt("${array[@]}") or tt("${(@)array}")
+for arrays.  (The last two forms are equivalent.)
+
+Parameter expansions can involve em(flags), as in `tt(${(@kv)aliases})',
+and other operators, such as `tt(${PREFIX:-"/usr/local"})'.  Parameter
+expansions can also be nested.  These topics will be introduced below.
+The full rules are complicated and are noted at the end.
 
 In the expansions discussed below that require a pattern, the form of
 the pattern is the same as that used for filename generation;
@@ -594,17 +612,8 @@ noderef(Modifiers) in noderef(History Expansion) can be
 applied:  for example, tt(${i:s/foo/bar/}) performs string
 substitution on the expansion of parameter tt($i).
 
-In the following descriptions, `word' refers to a single word
+In the following descriptions, `var(word)' refers to a single word
 substituted on the command line, not necessarily a space delimited word.
-With default options, after the assignments:
-
-example(array=("first word" "second word")
-scalar="only word")
-
-then tt($array) substitutes two words, `tt(first word)' and `tt(second
-word)', and tt($scalar) substitutes a single word `tt(only word)'.  This
-may be modified by explicit or implicit word-splitting, however.  The
-full rules are complicated and are noted at the end.
 
 startitem()
 item(tt(${)var(name)tt(}))(
@@ -1394,11 +1403,40 @@ used with the tt(${)...tt(/)...tt(}) forms.
 
 startitem()
 item(tt(S))(
-Search substrings as well as beginnings or ends; with tt(#) start
-from the beginning and with tt(%) start from the end of the string.
+With tt(#) or tt(##), search for the match that starts closest to the start of
+the string (a `substring match'). Of all matches at a particular position,
+tt(#) selects the shortest and tt(##) the longest:
+
+example(% str="aXbXc"
+% echo ${+LPAR()S+RPAR()str#X*}
+abXc
+% echo ${+LPAR()S+RPAR()str##X*}
+a
+% )
+
+With tt(%) or tt(%%), search for the match that starts closest to the end of
+the string:
+
+example(% str="aXbXc"
+% echo ${+LPAR()S+RPAR()str%X*}
+aXbc
+% echo ${+LPAR()S+RPAR()str%%X*}
+aXb
+% )
+
+(Note that tt(%) and tt(%%) don't search for the match that ends closest to the
+end of the string, as one might expect.)
+
 With substitution via tt(${)...tt(/)...tt(}) or
 tt(${)...tt(//)...tt(}), specifies non-greedy matching, i.e. that the
-shortest instead of the longest match should be replaced.
+shortest instead of the longest match should be replaced:
+
+example(% str="abab"
+% echo ${str/*b/_}
+_
+% echo ${+LPAR()S+RPAR()str/*b/_}
+_ab
+% )
 )
 item(tt(I:)var(expr)tt(:))(
 Search the var(expr)th match (where var(expr) evaluates to a number).
@@ -2264,12 +2302,13 @@ parentheses can be referenced.
 
 For example,
 
-example(foo="a string with a message"
-if [[ $foo = (a|an)' '(#b)(*)' '* ]]; then
+example(foo="a_string_with_a_message"
+if [[ $foo = (a|an)_(#b)(*) ]]; then
   print ${foo[$mbegin[1],$mend[1]]}
 fi)
 
-prints `tt(string with a)'.  Note that the first parenthesis is before the
+prints `tt(string_with_a_message)'.
+Note that the first set of parentheses is before the
 tt((#b)) and does not create a backreference.
 
 Backreferences work with all forms of pattern matching other than filename
@@ -2492,11 +2531,11 @@ therefore matches files in the current directory as well as
 subdirectories.
 Thus:
 
-example(ls (*/)#bar)
+example(ls -ld -- (*/)#bar)
 
 or
 
-example(ls **/bar)
+example(ls -ld -- **/bar)
 
 does a recursive directory search for files named `tt(bar)' (potentially
 including the file `tt(bar)' in the current directory).  This form does not
@@ -2511,11 +2550,11 @@ they are treated as if both a tt(/) plus a further tt(*) are present.
 Hence:
 
 example(setopt GLOBSTARSHORT
-ls **.c)
+ls -ld -- **.c)
 
 is equivalent to
 
-example(ls **/*.c)
+example(ls -ld -- **/*.c)
 subsect(Glob Qualifiers)
 cindex(globbing, qualifiers)
 cindex(qualifiers, globbing)
@@ -2707,7 +2746,7 @@ appropriate test.  For example,
 
 example(nt+LPAR()RPAR() { [[ $REPLY -nt $NTREF ]] }
 NTREF=reffile
-ls -l *(+nt))
+ls -ld -- *(+nt))
 
 lists all files in the directory that have been modified more recently than
 tt(reffile).
@@ -2898,36 +2937,36 @@ is performed, although note that the presence of the parentheses
 causes the entire expression to be subjected to any global pattern matching
 options such as tt(NULL_GLOB). Thus:
 
-example(ls *(-/))
+example(ls -ld -- *(-/))
 
 lists all directories and symbolic links that point to directories,
 and
 
-example(ls *(-@))
+example(ls -ld -- *(-@))
 
 lists all broken symbolic links, and
 
-example(ls *(%W))
+example(ls -ld -- *(%W))
 
 lists all world-writable device files in the current directory, and
 
-example(ls *(W,X))
+example(ls -ld -- *(W,X))
 
 lists all files in the current directory that are
 world-writable or world-executable, and
 
-example(echo /tmp/foo*(u0^@:t))
+example(print -rC1 /tmp/foo*(u0^@:t))
 
 outputs the basename of all root-owned files beginning with the string
 `tt(foo)' in tt(/tmp), ignoring symlinks, and
 
-example(ls *.*~(lex|parse).[ch](^D^l1))
+example(ls -ld -- *.*~(lex|parse).[ch](^D^l1))
 
 lists all files having a link count of one whose names contain a dot
 (but not those starting with a dot, since tt(GLOB_DOTS) is explicitly
 switched off) except for tt(lex.c), tt(lex.h), tt(parse.c) and tt(parse.h).
 
-example(print b*.pro+LPAR()#q:s/pro/shmo/+RPAR()(#q.:s/builtin/shmiltin/))
+example(print -rC1 b*.pro+LPAR()#q:s/pro/shmo/+RPAR()(#q.:s/builtin/shmiltin/))
 
 demonstrates how colon modifiers and other qualifiers may be chained
 together.  The ordinary qualifier `tt(.)' is applied first, then the colon