[Emacs-diffs] /srv/bzr/emacs/trunk r106715: * files.el (file-remote-p): Fix docstring. (Bug#10319)

[Michael Albinus]

------------------------------------------------------------
revno: 106715
author: Drew Adams  <address@hidden>
committer: Michael Albinus <address@hidden>
branch nick: trunk
timestamp: Wed 2011-12-21 19:33:38 +0100
message:
  * files.el (file-remote-p): Fix docstring.  (Bug#10319)
modified:
  lisp/ChangeLog
  lisp/files.el

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2011-12-21 12:20:40 +0000
+++ b/lisp/ChangeLog    2011-12-21 18:33:38 +0000
@@ -1,3 +1,7 @@
+2011-12-21  Drew Adams  <address@hidden>
+
+       * files.el (file-remote-p): Fix docstring.  (Bug#10319)
+
 2011-12-21  Jérémy Compostella  <address@hidden>
 
        * battery.el (battery-linux-sysfs): Add missing parameters from acpi.

=== modified file 'lisp/files.el'
--- a/lisp/files.el     2011-12-04 08:02:42 +0000
+++ b/lisp/files.el     2011-12-21 18:33:38 +0000
@@ -917,24 +917,41 @@
 
 (defun file-remote-p (file &optional identification connected)
   "Test whether FILE specifies a location on a remote system.
-Returns nil or a string identifying the remote connection (ideally
-a prefix of FILE).  For example, the remote identification for filename
-\"/address@hidden:/foo\" could be \"/address@hidden:\".
-A file is considered \"remote\" if accessing it is likely to be slower or
-less reliable than accessing local files.
-Furthermore, relative file names do not work across remote connections.
-
-IDENTIFICATION specifies which part of the identification shall
-be returned as string.  IDENTIFICATION can be the symbol
-`method', `user', `host' or `localname'; any other value is
-handled like nil and means to return the complete identification
-string.
-
-If CONNECTED is non-nil, the function returns an identification only
-if FILE is located on a remote system, and a connection is established
-to that remote system.
-
-`file-remote-p' will never open a connection on its own."
+A file is considered remote if accessing it is likely to
+be slower or less reliable than accessing local files.
+
+`file-remote-p' never opens a new remote connection.  It can
+only reuse a connection that is already open.
+
+Return nil or a string identifying the remote connection
+\(ideally a prefix of FILE).  Return nil if FILE is a relative
+file name.
+
+When IDENTIFICATION is nil, the returned string is a complete
+remote identifier: with components method, user, and host.  The
+components are those present in FILE, with defaults filled in for
+any that are missing.
+
+IDENTIFICATION can specify which part of the identification to
+return.  IDENTIFICATION can be the symbol `method', `user',
+`host', or `localname'.  Any other value is handled like nil and
+means to return the complete identification.  The string returned
+for IDENTIFICATION `localname' can differ depending on whether
+there is an existing connection.
+
+If CONNECTED is non-nil, return an identification only if FILE is
+located on a remote system and a connection is established to
+that remote system.
+
+Tip: You can use this expansion of remote identifier components
+     to derive a new remote file name from an existing one.  For
+     example, if FILE is \"/sudo::/path/to/file\" then
+
+       \(concat \(file-remote-p FILE) \"/bin/sh\")
+
+     returns a remote file name for file \"/bin/sh\" that has the
+     same remote identifier as FILE but expanded; a name such as
+     \"/sudo:address@hidden:/bin/sh\"."
   (let ((handler (find-file-name-handler file 'file-remote-p)))
     (if handler
        (funcall handler 'file-remote-p file identification connected)