From 8d251607e08e1ea4df201928b5bee21782a6526e Mon Sep 17 00:00:00 2001 From: Michael Albinus Date: Tue, 5 Sep 2017 15:32:03 +0200 Subject: [PATCH] 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. --- doc/lispref/files.texi | 12 ++++++++++-- etc/NEWS | 38 +++++++++++++++++++++++++------------- 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 -- 2.39.2