Improve documentation of 'file-name-concat'

* doc/lispref/files.texi (Directory Names):
* src/fileio.c (Ffile_name_concat): Advise not to use
'file-name-concat' unless necessary.  (Bug#76023)

2 files changed, 12 insertions, 0 deletions

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 97ad7c6b7fa..c285cd1c683 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2459,6 +2459,14 @@ results in any way.
 This is almost the same as using @code{concat}, but @var{dirname} (and
 the non-final components) may or may not end with slash characters,
 and this function will not double those characters.
+
+In most cases, one or more calls to @code{expand-file-name} (@pxref{File
+Name Expansion} are better suited for the job of generating file names
+with leading directories than this function.  Use this function only if
+some of the special features of @code{expand-file-name} get in the way
+of what your program needs to do.  For example, the special handling by
+@code{expand-file-name} of @file{~}, @file{~@var{user}}, and @code{nil},
+or the removal of @file{.} and @file{..} might not be what you want.
 @end defun
 
   To convert a directory name to its abbreviation, use this
diff --git a/src/fileio.c b/src/fileio.c
index 7042dbca258..66aef91d9e7 100644
--- a/src/fileio.c
+++ b/src/fileio.c
@@ -847,6 +847,10 @@ Each element in COMPONENTS must be a string or nil.
 DIRECTORY or the non-final elements in COMPONENTS may or may not end
 with a slash -- if they don't end with a slash, a slash will be
 inserted before concatenating.
+In most cases, one or more calls to `expand-file-name' are better
+suited for the job than this function.  Use this function only if
+some of the special expansions done by `expand-file-name' get in
+the way of what your program needs to do.
 usage: (file-name-concat DIRECTORY &rest COMPONENTS)  */)
   (ptrdiff_t nargs, Lisp_Object *args)
 {