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-Tag: archive/raspbian/1%30.1+1-3+rpi1^2~2^2~20^2~59
X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=143f1096daa686841f1409bd63835167bb7e8aca;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)
---

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)
 {