From b011fbfe6ca637c1cd68da317562c7134474a015 Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Fri, 10 Feb 2012 00:08:23 -0800 Subject: [PATCH] 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. --- doc/lispref/ChangeLog | 2 ++ doc/lispref/files.texi | 23 ++++++++++------------- etc/NEWS | 14 +++++++------- lisp/ChangeLog | 4 ++++ lisp/files.el | 26 ++++++++++++-------------- 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 + * 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 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 + + * files.el (remote-file-name-inhibit-cache): Doc fixes. + 2012-02-09 Lars Ingebrigtsen * 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))) -- 2.11.4.GIT