* files.el (file-remote-p): Fix docstring. (Bug#10319)

2 files changed, 39 insertions, 18 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index cf029ddb03e..2cf35375245 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,7 @@
+2011-12-21  Drew Adams  <drew.adams@oracle.com>
+
+        * files.el (file-remote-p): Fix docstring.  (Bug#10319)
+
 2011-12-21  Jérémy Compostella  <jeremy.compostella@gmail.com>
 
         * battery.el (battery-linux-sysfs): Add missing parameters from acpi.
diff --git a/lisp/files.el b/lisp/files.el
index 40b6e7d56b4..0f7386511f6 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -917,24 +917,41 @@ See `load-file' for a different interface to `load'."
 
 (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
-\"/user@host:/foo\" could be \"/user@host:\".
-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:root@myhost:/bin/sh\"."
   (let ((handler (find-file-name-handler file 'file-remote-p)))
     (if handler
         (funcall handler 'file-remote-p file identification connected)