[Emacs-diffs] emacs-24 r116859: Improve doc of file-symlink-p per bug #17073.

[Eli Zaretskii]

------------------------------------------------------------
revno: 116859
revision-id: address@hidden
parent: address@hidden
fixes bug: http://debbugs.gnu.org/17073
committer: Eli Zaretskii <address@hidden>
branch nick: emacs-24
timestamp: Tue 2014-03-25 18:08:45 +0200
message:
  Improve doc of file-symlink-p per bug #17073.
  
   doc/lispref/files.texi (Kinds of Files): Improve documentation of
   file-symlink-p.  Add cross-references.
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/files.texi         files.texi-20091113204419-o5vbwnq5f7feedwu-6179

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-03-25 02:47:39 +0000
+++ b/doc/lispref/ChangeLog     2014-03-25 16:08:45 +0000
@@ -1,3 +1,8 @@
+2014-03-25  Eli Zaretskii  <address@hidden>
+
+       * files.texi (Kinds of Files): Improve documentation of
+       file-symlink-p.  (Bug#17073)  Add cross-references.
+
 2014-03-24  Barry O'Reilly  <address@hidden>
 
        * markers.texi (Moving Marker Positions): The 2014-03-02 doc

=== modified file 'doc/lispref/files.texi'
--- a/doc/lispref/files.texi    2014-03-18 01:19:03 +0000
+++ b/doc/lispref/files.texi    2014-03-25 16:08:45 +0000
@@ -950,22 +950,26 @@
 @defun file-symlink-p filename
 @cindex file symbolic links
 If the file @var{filename} is a symbolic link, the
address@hidden function returns the (non-recursive) link target
-as a string.  (Determining the file name that the link points to from
-the target is nontrivial.)  First, this function recursively follows
-symbolic links at all levels of parent directories.
address@hidden function returns its (non-recursive) link target
+as a string.  (The link target string is not necessarily the full
+absolute file name of the target; determining the full file name that
+the link points to is nontrivial, see below.)  If the leading
+directories of @var{filename} include symbolic links, this function
+recursively follows them.
 
-If the file @var{filename} is not a symbolic link (or there is no such file),
+If the file @var{filename} is not a symbolic link, or does not exist,
 @code{file-symlink-p} returns @code{nil}.
 
+Here are a few examples of using this function:
+
 @example
 @group
-(file-symlink-p "foo")
+(file-symlink-p "not-a-symlink")
      @result{} nil
 @end group
 @group
 (file-symlink-p "sym-link")
-     @result{} "foo"
+     @result{} "not-a-symlink"
 @end group
 @group
 (file-symlink-p "sym-link2")
@@ -976,6 +980,40 @@
      @result{} "/pub/bin"
 @end group
 @end example
+
+Note that in the third example, the function returned @file{sym-link},
+but did not proceed to resolve it, although that file is itself a
+symbolic link.  This is what we meant by ``non-recursive'' above---the
+process of following the symbolic links does not recurse if the link
+target is itself a link.
+
+The string that this function returns is what is recorded in the
+symbolic link; it may or may not include any leading directories.
+This function does @emph{not} expand the link target to produce a
+fully-qualified file name, and in particular does not use the leading
+directories, if any, of the @var{filename} argument if the link target
+is not an absolute file name.  Here's an example:
+
address@hidden
address@hidden
+(file-symlink-p "/foo/bar/baz")
+     @result{} "some-file"
address@hidden group
address@hidden example
+
address@hidden
+Here, although @file{/foo/bar/baz} was given as a fully-qualified file
+name, the result is not, and in fact does not have any leading
+directories at all.  And since @file{some-file} might itself be a
+symbolic link, you cannot simply prepend leading directories to it,
+nor even naively use @code{expand-file-name} (@pxref{File Name
+Expansion}) to produce its absolute file name.
+
+For this reason, this function is seldom useful if you need to
+determine more than just the fact that a file is or isn't a symbolic
+link.  If you actually need the file name of the link target, use
address@hidden or @code{file-truename}, described in
address@hidden
 @end defun
 
 The next two functions recursively follow symbolic links at