master 74519db: Further clarification of directory-files* doc

[Michael Albinus]

branch: master
commit 74519db6dfcffad8ac7a273d43992d2535320a8c
Author: Michael Albinus <michael.albinus@gmx.de>
Commit: Michael Albinus <michael.albinus@gmx.de>

    Further clarification of directory-files* doc
    
    * doc/lispref/files.texi (Contents of Directories):
    Precise description of MATCH-REGEXP of directory-files.  Add
    directory-files-no-dot-files-regexp.
    
    * lisp/files.el (directory-files-no-dot-files-regexp): Revert last fix.
    
    * src/dired.c (Fdirectory_files)
    (Fdirectory_files_and_attributes): Fix wording in docstring.
---
 doc/lispref/files.texi | 21 +++++++++++++++++----
 lisp/files.el          |  2 +-
 src/dired.c            |  4 ++--
 3 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 3b8b4fb..fc66d1c 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2926,11 +2926,11 @@ absolute file names.  Otherwise, it returns the names 
relative to
 the specified directory.
 
 If @var{match-regexp} is non-@code{nil}, this function returns only
-those file names that contain a match for that regular expression---the
-other file names are excluded from the list.  On case-insensitive
-filesystems, the regular expression matching is case-insensitive.
+those file names whose non-directory part contain a match for that
+regular expression---the other file names are excluded from the list.
+On case-insensitive filesystems, the regular expression matching is
+case-insensitive.
 
-@c Emacs 19 feature
 If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort
 the list, so you get the file names in no particular order.  Use this if
 you want the utmost possible speed and don't care what order the files
@@ -3007,6 +3007,19 @@ corresponding argument to @code{file-attributes} 
(@pxref{Definition
 of file-attributes}).
 @end defun
 
+@defvr Constant directory-files-no-dot-files-regexp
+This regular expression matches any file name except @samp{.} and
+@samp{..}.  More precisely, it matches parts of any nonempty string
+except those two.  It is useful as the @var{match-regexp} argument to
+@code{directory-files} and @code{directory-files-and-attributes}:
+
+@example
+(directory-files "/foo" nil directory-files-no-dot-files-regexp)
+@end example
+
+returns @code{nil}, if directory @samp{/foo} is empty.
+@end defvr
+
 @defun file-expand-wildcards pattern &optional full
 This function expands the wildcard pattern @var{pattern}, returning
 a list of file names that match it.
diff --git a/lisp/files.el b/lisp/files.el
index 78ccb9b..c2c58da 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -5787,7 +5787,7 @@ If called interactively, then PARENTS is non-nil."
 
 (defconst directory-files-no-dot-files-regexp
   "[^.]\\|\\.\\.\\."
-  "Regexp matching any non-directory part of a file name except \".\" and 
\"..\".
+  "Regexp matching any file name except \".\" and \"..\".
 More precisely, it matches parts of any nonempty string except those two.
 It is useful as the regexp argument to `directory-files' and
 `directory-files-and-attributes'.")
diff --git a/src/dired.c b/src/dired.c
index 442d3aa..8256f26 100644
--- a/src/dired.c
+++ b/src/dired.c
@@ -293,7 +293,7 @@ DEFUN ("directory-files", Fdirectory_files, 
Sdirectory_files, 1, 4, 0,
 There are three optional arguments:
 If FULL is non-nil, return absolute file names.  Otherwise return names
  that are relative to the specified directory.
-If MATCH is non-nil, mention only file names which non-directory part
+If MATCH is non-nil, mention only file names whose non-directory part
  matches the regexp MATCH.
 If NOSORT is non-nil, the list is not sorted--its order is unpredictable.
  Otherwise, the list returned is sorted with `string-lessp'.
@@ -326,7 +326,7 @@ by `file-attributes'.
 This function accepts four optional arguments:
 If FULL is non-nil, return absolute file names.  Otherwise return names
  that are relative to the specified directory.
-If MATCH is non-nil, mention only file names which non-directory part
+If MATCH is non-nil, mention only file names whose non-directory part
  matches the regexp MATCH.
 If NOSORT is non-nil, the list is not sorted--its order is unpredictable.
  NOSORT is useful if you plan to sort the result yourself.