From: Eli Zaretskii <eliz@gnu.org>
Date: Thu, 6 Feb 2025 08:42:04 +0000 (+0200)
Subject: Improve documentation of 'file-name-concat'
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=652cf1ab781e5f59a1cb2e4dc7e66ac1c05b5224;p=emacs.git

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 a63942ce50c..494eb6461b5 100644
--- 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 cdf57618af1..7e1ac3fc383 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)
 {