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, 20 insertions, 15 deletions

diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index 415bce613..ada69c99a 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -39,11 +39,11 @@ be familiar to most command line users.
 
 Typically, options are single letters preceded by a hyphen (tt(-)).
 Options that take an argument accept it either immediately following the
-option letter or after white space, for example `tt(print -C3 *)' or
-`tt(print -C 3 *)' are equivalent.  Arguments to options are not the
+option letter or after white space, for example `tt(print -C3 {1..9})' or
+`tt(print -C 3 {1..9})' are equivalent.  Arguments to options are not the
 same as arguments to the command; the documentation indicates which is
 which.  Options that do not take an argument may be combined in a single
-word, for example `tt(print -ca *)' and `tt(print -c -a *)' are
+word, for example `tt(print -rca -- *)' and `tt(print -r -c -a -- *)' are
 equivalent.
 
 Some shell builtin commands also take options that begin with `tt(+)'
@@ -54,14 +54,14 @@ Options (together with their individual arguments, if any) must appear
 in a group before any non-option arguments; once the first non-option
 argument has been found, option processing is terminated.
 
-All builtin commands other than precommand modifiers, even those that
-have no options, can be given the argument `tt(-)tt(-)' to terminate option
-processing.  This indicates that the following words are non-option
-arguments, but is otherwise ignored.  This is useful in cases where
-arguments to the command may begin with `tt(-)'.  For historical
-reasons, most builtin commands also recognize a single `tt(-)' in a
-separate word for this purpose; note that this is less standard and
-use of `tt(-)tt(-)' is recommended.
+All builtin commands other than `tt(echo)' and precommand modifiers,
+even those that have no options, can be given the argument `tt(-)tt(-)'
+to terminate option processing.  This indicates that the following words
+are non-option arguments, but is otherwise ignored.  This is useful in
+cases where arguments to the command may begin with `tt(-)'.  For
+historical reasons, most builtin commands (including `tt(echo)') also
+recognize a single `tt(-)' in a separate word for this purpose; note
+that this is less standard and use of `tt(-)tt(-)' is recommended.
 
 startitem()
 prefix(-)
@@ -114,9 +114,9 @@ var(text) is any non-empty string, it is replaced by the text
 a literal string, not a pattern.  A trailing space in var(value) is not
 special in this case.  For example,
 
-example(alias -s ps=gv)
+example(alias -s ps='gv --')
 
-will cause the command `tt(*.ps)' to be expanded to `tt(gv *.ps)'.  As
+will cause the command `tt(*.ps)' to be expanded to `tt(gv -- *.ps)'.  As
 alias expansion is carried out earlier than globbing, the `tt(*.ps)' will
 then be expanded.  Suffix aliases constitute a different name space from
 other aliases (so in the above example it is still possible
@@ -1258,7 +1258,10 @@ If given together with tt(-o) or tt(-O), sorting is performed
 case-independently.
 )
 item(tt(-l))(
-Print the arguments separated by newlines instead of spaces.
+Print the arguments separated by newlines instead of spaces.  Note: if
+the list of arguments is empty, tt(print -l) will still output one empty
+line. To print a possibly-empty list of arguments one per line, use
+tt(print -C1), as in `tt(print -rC1 -- "$list[@]")'.
 )
 item(tt(-m))(
 Take the first argument as a pattern (should be quoted), and remove
@@ -1269,7 +1272,9 @@ item(tt(-n))(
 Do not add a newline to the output.
 )
 item(tt(-N))(
-Print the arguments separated and terminated by nulls.
+Print the arguments separated and terminated by nulls. Again,
+tt(print -rNC1 -- "$list[@]") is a canonical way to print an
+arbitrary list as null-delimited records.
 )
 item(tt(-o))(
 Print the arguments sorted in ascending order.