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.

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 3b8b4fb3a9e3cbd01f373759ea34e47afd30f829..fc66d1c085df486341c87e4c9408a3dac390e365 100644 (file)
--- 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 78ccb9ba910dd1f82a05661d448be81b0aa64246..c2c58dae934593efdbc2b2990daa5573dafca50d 100644 (file)
--- 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 442d3aa48fbabf8d67bb9e637e46d0fbd3c6eea6..8256f2626dc64f3091a5bb031b954ff9822a69d1 100644 (file)
--- 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.