Doc fixes for remote-file-name-inhibit-cache

* doc/lispref/files.texi (Magic File Names):
Tweak remote-file-name-inhibit-cache entry.
* lisp/files.el (remote-file-name-inhibit-cache): Doc fixes.
* etc/NEWS: Edits.

5 files changed, 35 insertions, 34 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 9e6ecdec16a..40fefde4396 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -9,6 +9,8 @@
 
 2012-02-10  Glenn Morris  <rgm@gnu.org>
 
+        * files.texi (Magic File Names): Tweak remote-file-name-inhibit-cache.
+
         * modes.texi (Basic Major Modes): Mention tabulated-list-mode.
 
 2012-02-08  Glenn Morris  <rgm@gnu.org>
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 087eb6ef1db..cf093ba36cb 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2862,24 +2862,21 @@ is a good way to come up with one.
 @end defun
 
 @defopt remote-file-name-inhibit-cache
-Whether to use the remote file-name cache for read access.
-
-File attributes of remote files are cached for better performance.  If
-they are changed out of Emacs' control, the cached values become
+The attributes of remote files can be cached for better performance.  If
+they are changed outside of Emacs's control, the cached values become
 invalid, and must be reread.
 
-When set to @code{nil}, cached values are always used.  This shall be
-set with care.  When set to @code{t}, cached values are never used.
-ALthough this is the safest value, it could result in performance
-degradation.
+When this variable is set to @code{nil}, cached values are never
+expired.  Use this setting with caution, only if you are sure nothing
+other than Emacs ever changes the remote files.  If it is set to
+@code{t}, cached values are never used.  This is the safest value, but
+could result in performance degradation.
 
 A compromise is to set it to a positive number.  This means that
 cached values are used for that amount of seconds since they were
-cached.
-
-In case a remote file is checked regularly, it might be reasonable to
-let-bind this variable to a value less then the time period between
-two checks.  Example:
+cached.  If a remote file is checked regularly, it might be a good
+idea to let-bind this variable to a value less than the time period
+between consecutive checks.  For example:
 
 @example
 (defun display-time-file-nonempty-p (file)
diff --git a/etc/NEWS b/etc/NEWS
index 4a69f18aad0..d7491b7560b 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -305,9 +305,6 @@ context in their return values.
 +++
 *** The new functions file-selinux-context and set-file-selinux-context
 get and set the SELinux context of a file.
----
-*** Tramp offers handlers for file-selinux-context and set-file-selinux-context
-for remote machines which support SELinux.
 
 ** Changes for exiting Emacs
 +++
@@ -385,9 +382,6 @@ If a theme is not in this list, Emacs queries before loading it, and
 offers to save the theme to `custom-safe-themes' automatically.  By
 default, all themes included in Emacs are treated as safe.
 
-** The user option `remote-file-name-inhibit-cache' controls whether
-the remote file-name cache is used for read access.
-
 ** File- and directory-local variable changes
 +++
 *** You can stop directory local vars from applying to subdirectories.
@@ -855,9 +849,15 @@ sql-list-all and sql-list-table.
 ---
 *** The following access methods are discontinued: "ssh1_old",
 "ssh2_old", "scp1_old", "scp2_old", "imap", "imaps" and "fish".
++++
+*** The user option `remote-file-name-inhibit-cache' controls whether
+remote file attributes are cached for better performance.
 ---
 *** The option `ange-ftp-binary-file-name-regexp' has changed its
 default value to "".
+---
+*** Handlers for file-selinux-context and set-file-selinux-context for
+remote machines that support SELinux.
 
 +++
 ** New function, url-queue-retrieve, fetches URLs asynchronously like
@@ -923,7 +923,7 @@ You can get a comparable behavior with:
 ---
 *** pc-mode.el is obsolete (CUA mode is much more comprehensive).
 
-[gnus.texi, message.texi need updating]
+[FIXME gnus.texi, message.texi need updating]
 *** pgg is obsolete (use EasyPG instead)
 
 ---
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 0769badf4f5..41728f0b997 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,7 @@
+2012-02-10  Glenn Morris  <rgm@gnu.org>
+
+        * files.el (remote-file-name-inhibit-cache): Doc fixes.
+
 2012-02-09  Lars Ingebrigtsen  <larsi@rusty>
 
         * mail/smtpmail.el (smtpmail-user-mail-address): New function.
diff --git a/lisp/files.el b/lisp/files.el
index 7bb44098223..87218c9a6e8 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -981,20 +981,18 @@ Tip: You can use this expansion of remote identifier components
 
 (defcustom remote-file-name-inhibit-cache 10
   "Whether to use the remote file-name cache for read access.
-
-When `nil', always use the cached values.
-When `t', never use them.
-A number means use them for that amount of seconds since they were
-cached.
-
-File attributes of remote files are cached for better performance.
-If they are changed out of Emacs' control, the cached values
-become invalid, and must be invalidated.
-
-In case a remote file is checked regularly, it might be
-reasonable to let-bind this variable to a value less then the
-time period between two checks.
-Example:
+When `nil', never expire cached values (caution)
+When `t', never use the cache (safe, but may be slow)
+A number means use cached values for that amount of seconds since caching.
+
+The attributes of remote files are cached for better performance.
+If they are changed outside of Emacs's control, the cached values
+become invalid, and must be reread.  If you are sure that nothing
+other than Emacs changes the files, you can set this variable to `nil'.
+
+If a remote file is checked regularly, it might be a good idea to
+let-bind this variable to a value less than the interval between
+consecutive checks.  For example:
 
   (defun display-time-file-nonempty-p (file)
     (let ((remote-file-name-inhibit-cache (- display-time-interval 5)))