Merge from origin/emacs-26

22922c7 (origin/emacs-26) * doc/emacs/entering.texi (Entering Emacs):...
59657c4 Document 'window-at-side-p' in the Elisp manual
2b35ed0 Document external-debugging-output in the Elisp Manual (Bug#2...
db6564c Fix scroll-margin docstring (Bug#13791)
732d1b9 Clarify that `ansi-term' is almost the same as `term' (Bug#18...
f706c59 Update manual description of locate-file (Bug#23650)
1602262 Clarify effect of print-gensym (Bug#27776)
53e9fa2 * lisp/custom.el (defcustom): Fix docstring (Bug#27891).
607cc4e Define cl-type-definition button type as needed (Bug#28899)
9e6889c Emphasize that GPG passphrase caching is temporary (Bug#29907)
4b5711b Fix @examples in cc-mode.info, where lines were getting glued...
71961f1 Minor change in "Mode Line" section of Emacs manual
55a2b76 More fixes in the Emacs manual

1 files changed, 10 insertions, 0 deletions

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 6a0312bd2f3..70d6ec9cdb3 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -1541,6 +1541,16 @@ argument.  If @var{predicate} is @code{nil} or omitted,
 @xref{Kinds of Files}, for other useful predicates, e.g.,
 @code{file-executable-p} and @code{file-directory-p}.
 
+This function will normally skip directories, so if you want it to
+find directories, make sure the @var{predicate} function returns
+@code{dir-ok} for them.  For example:
+
+@example
+(locate-file "html" '("/var/www" "/srv") nil
+             (lambda (f) (if (file-directory-p f) 'dir-ok)))
+@end example
+
+
 For compatibility, @var{predicate} can also be one of the symbols
 @code{executable}, @code{readable}, @code{writable}, @code{exists}, or
 a list of one or more of these symbols.