49564: always use descriptions included in the file-patterns style and allow the recursive-files style to also work in those cases

ChangeLog

@@ -1,5 +1,9 @@
 2021-11-12  Oliver Kiddle  <opk@zsh.org>
 
+	* 49564: Completion/Unix/Type/_files, Doc/Zsh/compsys.yo: always
+	use descriptions included in the file-patterns style and allow
+	the recursive-files style to also work in those cases
+
 	* 49562: Doc/Zsh/compsys.yo: remove old documentation for
 	other-files tag that was removed in 36165
 

Completion/Unix/Type/_files

@@ -92,7 +92,10 @@ for def in "$pats[@]"; do
     pat="${${sdef%%:${tag}*}//\\:/:}"
 
     if [[ "$sdef" = *:${tag}:* ]]; then
+      # If the file-patterns spec includes a description, use it and give the
+      # group/description options from it precedence over passed in parameters.
       descr="${(Q)sdef#*:${tag}:}"
+      end=
     else
       if (( $opts[(I)-X] )); then
         descr=
@@ -108,9 +111,16 @@ for def in "$pats[@]"; do
       while _next_label "$tag" expl "$descr"; do
         _comp_ignore=( $_comp_ignore $ign )
         if [[ -n "$end" ]]; then
-          if _path_files -g "$pat" "$opts[@]" "$expl[@]"; then
+          expl=( "$opts[@]" "$expl[@]" )
+        else
+          expl+=( "$opts[@]" )
+        fi
+
+        if _path_files -g "$pat" "$expl[@]"; then
           ret=0
-	  elif [[ $PREFIX$SUFFIX != */* ]] && zstyle -a ":completion:${curcontext}:$tag" recursive-files rfiles; then
+        elif [[ $PREFIX$SUFFIX != */* ]] && \
+            zstyle -a ":completion:${curcontext}:$tag" recursive-files rfiles
+        then
           for rfile in $rfiles; do
             if [[ $PWD/ = ${~rfile} ]]; then
               if [[ -z $subtree ]]; then
@@ -119,16 +129,13 @@ for def in "$pats[@]"; do
               for prepath in $subtree; do
                 oprefix=$PREFIX
                 PREFIX=$prepath/$PREFIX
-		  _path_files -g "$pat" "$opts[@]" "$expl[@]" && ret=0
+                _path_files -g "$pat" "$expl[@]" && ret=0
                 PREFIX=$oprefix
               done
               break
             fi
           done
         fi
-        else
-          _path_files "$expl[@]" -g "$pat" "$opts[@]" && ret=0
-        fi
       done
       (( ret )) || break
     done

Doc/Zsh/compsys.yo

@@ -1524,9 +1524,10 @@ If no `tt(:)var(tag)' is given the `tt(files)' tag will be used.
 The var(tag) may also be followed by an optional second colon and a
 description, which will be used for the `tt(%d)' in the value of
 the tt(format) style (if that is set) instead of the default
-description supplied by the completion function.  If the description
+description supplied by the completion function.  The inclusion
-given here contains itself a `tt(%d)', that is replaced with the
+of a description also gives precedence to associated options such as
-description supplied by the completion function.
+for completion grouping so it can be used where files should be
+separated.
 
 For example, to make the tt(rm) command first complete only names of
 object files and then the names of all files if there is no matching
@@ -1548,6 +1549,15 @@ all files using the pattern `tt(*)' at the first step and stops when it
 sees this pattern.  Note also it will never try a pattern more than once
 for a single completion attempt.
 
+To separate directories into a separate group from the files but still
+complete them at the first attempt, a description needs to be given.
+Note that directories need to be explicitly excluded from the
+globbed-files because `tt(*)' will match directories. For grouping, it
+is also necessary to set the tt(group-name) style.
+
+example(zstyle ':completion:*' file-patterns \ 
+    '%p+LPAR()^-/RPAR():globbed-files *(-/):directories:location')
+
 During the execution of completion functions, the tt(EXTENDED_GLOB)
 option is in effect, so the characters `tt(#)', `tt(~)' and `tt(^)' have
 special meanings in the patterns.
@@ -1971,9 +1981,10 @@ obtained by setting the style to an empty string (i.e. tt('')).
 )
 kindex(list-dirs-first, completion style)
 item(tt(list-dirs-first))(
-This is used by file completion.  If set, directories to be completed
+This is used by file completion and corresponds to a particular
-are listed separately from and before completion for other files,
+setting of the tt(file-patterns) style.
-regardless of tag ordering.
+If set, the default directories to be completed
+are listed separately from and before completion for other files.
 )
 kindex(list-grouped, completion style)
 item(tt(list-grouped))(