Merge from emacs-24; up to 2014-03-23T23:14:52Z!yamaoka@jpl.org

4 files changed, 69 insertions, 17 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 71af1bc66a0..fdc266472e0 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,16 @@
+2014-03-26  Eli Zaretskii  <eliz@gnu.org>
+
+        * files.texi (Kinds of Files): Improve documentation of
+        file-symlink-p.  (Bug#17073)  Add cross-references.
+
+2014-03-26  Barry O'Reilly  <gundaetiapo@gmail.com>
+
+        * markers.texi (Moving Marker Positions): The 2014-03-02 doc
+        change mentioning undo's inability to handle relocated markers no
+        longer applies.  See bug#16818.
+        * text.texi (Undo): Expand documentation of (TEXT . POS) and
+        (MARKER . ADJUSTMENT) undo elements.
+
 2014-03-26  Glenn Morris  <rgm@gnu.org>
 
         * files.texi (File Locks): All systems support locking.
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index a00fa5b4795..64ed3a05ee6 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -950,22 +950,26 @@ as directories, symbolic links, and ordinary files.
 @defun file-symlink-p filename
 @cindex file symbolic links
 If the file @var{filename} is a symbolic link, the
-@code{file-symlink-p} 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.
-
-If the file @var{filename} is not a symbolic link (or there is no such file),
+@code{file-symlink-p} 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 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 @@ If the file @var{filename} is not a symbolic link (or there is no such file),
      @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:
+
+@example
+@group
+(file-symlink-p "/foo/bar/baz")
+     @result{} "some-file"
+@end group
+@end example
+
+@noindent
+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
+@code{file-chase-links} or @code{file-truename}, described in
+@ref{Truenames}.
 @end defun
 
 The next two functions recursively follow symbolic links at
diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi
index 19386d638fe..51b87ab1e5b 100644
--- a/doc/lispref/markers.texi
+++ b/doc/lispref/markers.texi
@@ -344,12 +344,10 @@ specify the insertion type, create them with insertion type
 @section Moving Marker Positions
 
   This section describes how to change the position of an existing
-marker.  When you do this, be sure you know how the marker is used
-outside of your program.  For example, moving a marker to an unrelated
-new position can cause undo to later adjust the marker incorrectly.
-Often when you wish to relocate a marker to an unrelated position, it
-is preferable to make a new marker and set the prior one to point
-nowhere.
+marker.  When you do this, be sure you know whether the marker is used
+outside of your program, and, if so, what effects will result from
+moving it---otherwise, confusing things may happen in other parts of
+Emacs.
 
 @defun set-marker marker position &optional buffer
 This function moves @var{marker} to @var{position}
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index f8a3e873449..7c5603fd645 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -1270,7 +1270,8 @@ This kind of element indicates how to reinsert text that was deleted.
 The deleted text itself is the string @var{text}.  The place to
 reinsert it is @code{(abs @var{position})}.  If @var{position} is
 positive, point was at the beginning of the deleted text, otherwise it
-was at the end.
+was at the end.  Zero or more (@var{marker} . @var{adjustment})
+elements follow immediately after this element.
 
 @item (t . @var{time-flag})
 This kind of element indicates that an unmodified buffer became
@@ -1296,8 +1297,10 @@ Here's how you might undo the change:
 @item (@var{marker} . @var{adjustment})
 This kind of element records the fact that the marker @var{marker} was
 relocated due to deletion of surrounding text, and that it moved
-@var{adjustment} character positions.  Undoing this element moves
-@var{marker} @minus{} @var{adjustment} characters.
+@var{adjustment} character positions.  If the marker's location is
+consistent with the (@var{text} . @var{position}) element preceding it
+in the undo list, then undoing this element moves @var{marker}
+@minus{} @var{adjustment} characters.
 
 @item (apply @var{funname} . @var{args})
 This is an extensible undo item, which is undone by calling