PATCH: 3.1.6-pws-2: globbing documentation

[Peter Stephenson <pws@xxxxxx>]

This clarifies the globbing documentation in ways which should be
familiar from recent discussions.  Please look at it and say if you
think that it has the opposite effect.

--- Doc/Zsh/expn.yo.doc	Wed Sep  1 14:41:33 1999
+++ Doc/Zsh/expn.yo	Fri Sep  3 15:52:48 1999
@@ -471,7 +471,7 @@
 Internally, each such expansion is converted into the
 equivalent list for brace expansion.  E.g., tt(${^var}) becomes
 tt({$var[1],$var[2],)...tt(}), and is processed as described in
-noderef(Brace Expansion) above.
+noderef(Brace Expansion) below.
 If word splitting is also in effect the
 tt($var[)var(N)tt(]) may themselves be split into different list
 elements.
@@ -933,6 +933,14 @@
 characters between the braces, in the manner of a search set.
 `tt(-)' is treated specially as in a search set, but `tt(^)' or `tt(!)' as
 the first character is treated normally.
+
+Note that brace expansion is not part of filename generation (globbing); an
+expression such as tt(*/{foo,bar}) is split into two separate words
+tt(*/foo) and tt(*/bar) before filename generation takes place.  In
+particular, note that this is liable to produce a `no match' error if
+em(either) of the two expressions does not match; this is to be contrasted
+with tt(*/(foo|bar)), which is treated as a single pattern but otherwise
+has similar effects.
 texinode(Filename Expansion)(Filename Generation)(Brace Expansion)(Expansion)
 sect(Filename Expansion)
 cindex(filename expansion)
@@ -1084,9 +1092,9 @@
 the `tt(LPAR())' is treated specially, as detailed below. The option
 tt(SH_GLOB) prevents bare parentheses from being used in this way, though
 the tt(KSH_GLOB) option is still available.
-Note that grouping cannot currently extend over multiple directories:
-a `tt(/)' separating a directory terminates processing of the current
-group; processing resumes after the end of the group.
+Note that grouping cannot extend over multiple directories: it is an error
+to have a `tt(/)' within a group (this only applies for patterns which
+match filenames).
 )
 item(var(x)tt(|)var(y))(
 Matches either var(x) or var(y).
@@ -1275,7 +1283,10 @@
 A pathname component of the form `tt(LPAR())var(foo)tt(/RPAR()#)'
 matches a path consisting of zero or more directories
 matching the pattern var(foo).
-As a shorthand, `tt(**/)' is equivalent to `tt((*/)#)'.
+
+As a shorthand, `tt(**/)' is equivalent to `tt((*/)#)'; note that this
+therefore matches files in the current directory as well as
+subdirectories.
 Thus:
 
 example(ls (*/)#bar)
@@ -1284,8 +1295,11 @@
 
 example(ls **/bar)
 
-does a recursive directory search for files named `tt(bar)', not following
-symbolic links.  To follow links, use `tt(***/)'.
+does a recursive directory search for files named `tt(bar)' (potentially
+including the file `tt(bar)' in the current directory), not following
+symbolic links.  To follow links, use `tt(***/)'.  Neither of these can be
+combined with other forms of globbing within the same filename segment; in
+that case, the `tt(*)' operators revert to their usual effect.
 subsect(Glob Qualifiers)
 cindex(globbing, qualifiers)
 cindex(qualifiers, globbing)

-- 
Peter Stephenson <pws@xxxxxx>       Tel: +39 050 844536
WWW:  http://www.ifh.de/~pws/
Dipartimento di Fisica, Via Buonarroti 2, 56100 Pisa, Italy