Doc precisment about remote link targets

* doc/lispref/files.texi (Truenames): Explain handling of
targets of `file-truename' and `make-symbolic-link', which
look like a remote file name.

* etc/NEWS: Precise examples for symlinks which look like
remote file names.  MUSTBENEW of `write-region' is not
propagated to file name handlers.

2 files changed, 35 insertions, 15 deletions

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 06466c9bba8..d04be63d7ec 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -1116,8 +1116,11 @@ file name component immediately preceding @samp{..} will be
 simplified away before @code{file-truename} is called.  To
 eliminate the need for a call to @code{expand-file-name},
 @code{file-truename} handles @samp{~} in the same way that
-@code{expand-file-name} does.  @xref{File Name Expansion,, Functions
-that Expand Filenames}.
+@code{expand-file-name} does.
+
+If the target of a symbolic links has remote file name syntax,
+@code{file-truename} returns it quoted.  @xref{File Name Expansion,,
+Functions that Expand Filenames}.
 @end defun
 
 @defun file-chase-links filename &optional limit
@@ -1736,10 +1739,15 @@ is treated only as a string; it need not name an existing file.
 If @var{ok-if-already-exists} is an integer, indicating interactive
 use, then leading @samp{~} is expanded and leading @samp{/:} is
 stripped in the @var{target} string.
+
 If @var{target} is a relative file name, the resulting symbolic link
 is interpreted relative to the directory containing the symbolic link.
 @xref{Relative File Names}.
 
+If both @var{target} and @var{newname} have remote file name syntax,
+and if both remote identifications are equal, the symbolic link points
+to the local file name part of @var{target}.
+
 This function is not available on systems that don't support symbolic
 links.
 @end deffn
diff --git a/etc/NEWS b/etc/NEWS
index 2b0c86d7afb..2824349a537 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1210,23 +1210,35 @@ The following changes are involved.
 ---
 *** 'file-attributes' and 'file-symlink-p' no longer prepend "/:" to
 symbolic links whose targets begin with "/" and contain ":".  For
-example, if a symbolic link "x" has a target "/y:z", (file-symlink-p
-"x") now returns "/y:z" rather than "/:/y:z".
+example, if a symbolic link "x" has a target "/y:z:", '(file-symlink-p
+"x")' now returns "/y:z:" rather than "/:/y:z:".
 
 ---
-*** 'make-symbolic-link' no longer looks for file name handlers when
-creating a local symbolic link.  For example, (make-symbolic-link
-"/y:z" "x") now creates a symlink to "/y:z" instead of failing.
+*** 'make-symbolic-link' no longer looks for file name handlers of
+target when creating a symbolic link.  For example,
+'(make-symbolic-link "/y:z:" "x")' now creates a symbolic link to
+"/y:z:" instead of failing.
+
++++
+*** 'make-symbolic-link' removes the remote part of a link target if
+target and newname have the same remote part.  For example,
+'(make-symbolic-link "/x:y:a" "/x:y:b")' creates a link with the
+literal string "a"; and '(make-symbolic-link "/x:y:a" "/x:z:b")'
+creates a link with the literal string "/x:y:a" instead of failing.
 
 +++
 *** 'make-symbolic-link' now expands a link target with leading "~"
 only when the optional third arg is an integer, as when invoked
-interactively.  For example, (make-symbolic-link "~y" "x") now creates
-a link with target the literal string "~y"; to get the old behavior,
-use (make-symbolic-link (expand-file-name "~y") "x").  To avoid this
-expansion in interactive use, you can now prefix the link target with
-"/:".  For example, (make-symbolic-link "/:~y" "x" 1) now creates a
-link to literal "~y".
+interactively.  For example, '(make-symbolic-link "~y" "x")' now
+creates a link with target the literal string "~y"; to get the old
+behavior, use '(make-symbolic-link (expand-file-name "~y") "x")'.  To
+avoid this expansion in interactive use, you can now prefix the link
+target with "/:".  For example, '(make-symbolic-link "/:~y" "x" 1)'
+now creates a link to literal "~y".
+
++++
+** 'file-truename' returns a quoted file name if the target of a
+symbolic link has remote file name syntax.
 
 +++
 ** Module functions are now implemented slightly differently; in
@@ -1235,8 +1247,8 @@ Code that depends on undocumented internals of the module system might
 break.
 
 ---
-** The arguments LOCKNAME and MUSTBENEW of 'write-region' are
-propagated to file name handlers now.
+** The argument LOCKNAME of 'write-region' is propagated to file name
+handlers now.
 
 ---
 ** When built against recent versions of GTK+, Emacs always uses