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)

(cherry picked from commit 143f1096daa686841f1409bd63835167bb7e8aca)

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index a63942ce50c709b700577483a04d1ae4a8c142ea..494eb6461b5d6e3587f5709afefd78d5a7626f8f 100644 (file)
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2471,6 +2471,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 cdf57618af167f96f116e7a9b2b8f31857fd2a74..7e1ac3fc383d2af0f6c450fa323f90675d197f87 100644 (file)
--- 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)
 {