[Emacs-diffs] feature/tramp-thread-safe 4615b91 4/7: Document visiting files asynchronously

[Michael Albinus]

branch: feature/tramp-thread-safe
commit 4615b9148cc8d043ef7bc265d0b948178df60eb0
Author: Michael Albinus <address@hidden>
Commit: Michael Albinus <address@hidden>

    Document visiting files asynchronously
    
    * doc/emacs/files.texi (Visiting):
    * doc/lispref/files.texi (Visiting Functions): Document visiting
    files asynchronously.
    
    * etc/NEWS: Rework entry about asynchronous file visiting.
    
    * lisp/files.el (find-file, find-file-other-window)
    (find-file-other-frame, find-file-existing)
    (find-alternate-file-other-window, find-alternate-file)
    (find-file-literally): Adapt docstring.
---
 doc/emacs/files.texi   | 28 ++++++++++++++++++++++++++++
 doc/lispref/files.texi | 43 ++++++++++++++++++++++++++++++-------------
 etc/NEWS               | 13 +++++++------
 lisp/files.el          | 20 +++++++++++++-------
 4 files changed, 78 insertions(+), 26 deletions(-)

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index f0a11fd..46e64c2 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -228,6 +228,34 @@ File Names}, for information on how to visit a file whose 
name
 actually contains wildcard characters.  You can disable the wildcard
 feature by customizing @code{find-file-wildcards}.
 
address@hidden visiting files asynchronously
address@hidden find-file-asynchronously
+  Sometimes, it is handy to visit a file asynchronously.  This means,
+while loading the file into its buffer Emacs keeps responsive, and you
+can continue to edit other files, or call commands.  This is
+controlled by the user option @code{find-file-asynchronously}.  If
+this option is @code{nil} (the default), visiting a file is performed
+synchronously.  A regexp value let files, which name matches the
+regexp, being visited asynchronously, and synchronously otherwise.
+The value @code{t} forces asynchronous visiting of files
+unconditionally.
+
+If you want to visit all remote files asynchronously, you should set
+
address@hidden
address@hidden
+(customize-set-variable
+  'find-file-asynchronously tramp-file-name-regexp
+  "Visit remote files asynchronously")
address@hidden group
address@hidden example
+
+  With a prefix argument @kbd{C-u}, the meaning of
address@hidden will be reverted.  If this user option
+is @code{nil}, visiting a file is performed asynchronously.  Contrary,
+if this user option is address@hidden, visiting a file is performed
+synchronously.
+
 @kindex C-x C-v
 @findex find-alternate-file
   If you visit the wrong file unintentionally by typing its name
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 068cf05..9faa47b 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -96,7 +96,7 @@ not alter it, the fastest way is to use 
@code{insert-file-contents} in a
 temporary buffer.  Visiting the file is not necessary and takes longer.
 @xref{Reading from Files}.
 
address@hidden Command find-file filename &optional wildcards
address@hidden Command find-file filename &optional wildcards async
 This command selects a buffer visiting the file @var{filename},
 using an existing buffer if there is one, and otherwise creating a
 new buffer and reading the file into it.  It also returns that buffer.
@@ -105,7 +105,8 @@ Aside from some technical details, the body of the 
@code{find-file}
 function is basically equivalent to:
 
 @smallexample
-(switch-to-buffer (find-file-noselect filename nil nil wildcards))
+(switch-to-buffer
+  (find-file-noselect filename nil nil wildcards async))
 @end smallexample
 
 @noindent
@@ -115,21 +116,27 @@ If @var{wildcards} is address@hidden, which is always 
true in an
 interactive call, then @code{find-file} expands wildcard characters in
 @var{filename} and visits all the matching files.
 
+If @var{async} is address@hidden, the file will be loaded into the
+buffer asynchronously.  Interactively, this is indicated by either
+setting user option @code{find-file-asynchronously} to address@hidden,
+or by a prefix argument.
+
 When @code{find-file} is called interactively, it prompts for
 @var{filename} in the minibuffer.
 @end deffn
 
address@hidden Command find-file-literally filename
address@hidden Command find-file-literally filename &optional async
 This command visits @var{filename}, like @code{find-file} does, but it
 does not perform any format conversions (@pxref{Format Conversion}),
 character code conversions (@pxref{Coding Systems}), or end-of-line
 conversions (@pxref{Coding System Basics, End of line conversion}).
-The buffer visiting the file is made unibyte, and its major mode is
-Fundamental mode, regardless of the file name.  File local variable
-specifications  in the file (@pxref{File Local Variables}) are
-ignored, and automatic decompression and adding a newline at the end
-of the file due to @code{require-final-newline} (@pxref{Saving
-Buffers, require-final-newline}) are also disabled.
+If called interactively, the argument @var{async} is determined like
+in @code{find-file}.  The buffer visiting the file is made unibyte,
+and its major mode is Fundamental mode, regardless of the file name.
+File local variable specifications in the file (@pxref{File Local
+Variables}) are ignored, and automatic decompression and adding a
+newline at the end of the file due to @code{require-final-newline}
+(@pxref{Saving Buffers, require-final-newline}) are also disabled.
 
 Note that if Emacs already has a buffer visiting the same file
 non-literally, it will not visit the same file literally, but instead
@@ -139,7 +146,7 @@ buffer and then read the file contents into it using
 @code{insert-file-contents-literally} (@pxref{Reading from Files}).
 @end deffn
 
address@hidden find-file-noselect filename &optional nowarn rawfile wildcards
address@hidden find-file-noselect filename &optional nowarn rawfile wildcards 
async
 This function is the guts of all the file-visiting functions.  It
 returns a buffer visiting the file @var{filename}.  You may make the
 buffer current or display it in a window if you wish, but this
@@ -157,7 +164,9 @@ Reading the file involves decoding the file's contents 
(@pxref{Coding
 Systems}), including end-of-line conversion, and format conversion
 (@pxref{Format Conversion}).  If @var{wildcards} is address@hidden,
 then @code{find-file-noselect} expands wildcard characters in
address@hidden and visits all the matching files.
address@hidden and visits all the matching files.  If @var{async} is
address@hidden and there are several matching files due to expansion
+of wildcard characters, every file will be loaded in an own thread.
 
 This function displays warning or advisory messages in various peculiar
 cases, unless the optional argument @var{nowarn} is address@hidden  For
@@ -191,7 +200,7 @@ various files.
 @end example
 @end defun
 
address@hidden Command find-file-other-window filename &optional wildcards
address@hidden Command find-file-other-window filename &optional wildcards async
 This command selects a buffer visiting the file @var{filename}, but
 does so in a window other than the selected window.  It may use
 another existing window or split a window; see @ref{Switching
@@ -201,7 +210,7 @@ When this command is called interactively, it prompts for
 @var{filename}.
 @end deffn
 
address@hidden Command find-file-read-only filename &optional wildcards
address@hidden Command find-file-read-only filename &optional wildcards async
 This command selects a buffer visiting the file @var{filename}, like
 @code{find-file}, but it marks the buffer as read-only.  @xref{Read Only
 Buffers}, for related functions and variables.
@@ -219,6 +228,14 @@ the @code{find-file} commands ignore their @var{wildcards} 
argument
 and never treat wildcard characters specially.
 @end defopt
 
address@hidden find-file-asynchronously
+If this variable is address@hidden, a file will be visited
+asynchronously when called interactively.  If it is a regular
+expression, it must match the file name to be visited.  This behavior
+is toggled by a prefix argument to the interactive call of the file
+visiting command.
address@hidden defopt
+
 @defopt find-file-hook
 The value of this variable is a list of functions to be called after a
 file is visited.  The file's local-variables specification (if any) will
diff --git a/etc/NEWS b/etc/NEWS
index 50d1b59..8d18d3e 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -209,13 +209,14 @@ large files.  Now it also offers a third alternative: to 
visit the
 file literally, as in 'find-file-literally', which speeds up
 navigation and editing of large files.
 
---- (Documentation to be added)
++++
 ** Files can be visited asynchronously.
-If the file visiting commands are prefixed like 'C-u C-x C-f ...', the
-files are loaded asynchronously into the respective buffers.  I.e.,
-Emacs is still responsive while loading the files, which is useful
-especially for remote files.  See the node "(emacs) Visiting" in the
-user manual for the supported commands..
+If the new user option 'find-file-asynchronously' has a proper non-nil
+value, interactive file visiting commands load the file asynchronously
+into the respective buffer.  I.e., Emacs is still responsive while
+loading the files, which is useful especially for remote files.  See
+the node "(emacs) Visiting" in the user manual for the supported
+commands.
 
 
 * Changes in Specialized Modes and Packages in Emacs 27.1
diff --git a/lisp/files.el b/lisp/files.el
index 88c4752..128648f 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -1629,7 +1629,7 @@ suppress wildcard expansion by setting 
`find-file-wildcards' to nil.
 
 If ASYNC is non-nil, the file will be loaded into the buffer
 asynchronously.  Interactively, this is indicated by either
-setting `find-file-asynchronously' to nil, or by a prefix
+setting `find-file-asynchronously' to non-nil, or by a prefix
 argument.
 
 To visit a file without any kind of conversion and without
@@ -1665,7 +1665,8 @@ Interactively, or if WILDCARDS is non-nil in a call from 
Lisp,
 expand wildcards (if any) and visit multiple files.
 
 If ASYNC is non-nil, the file will be loaded into the buffer
-asynchronously.  Interactively, this is indicated by a prefix
+asynchronously.  Interactively, this is indicated by either
+setting `find-file-asynchronously' to non-nil, or by a prefix
 argument."
   (interactive
    (find-file-read-args "Find file in other window: "
@@ -1702,7 +1703,8 @@ Interactively, or if WILDCARDS is non-nil in a call from 
Lisp,
 expand wildcards (if any) and visit multiple files.
 
 If ASYNC is non-nil, the file will be loaded into the buffer
-asynchronously.  Interactively, this is indicated by a prefix
+asynchronously.  Interactively, this is indicated by either
+setting `find-file-asynchronously' to non-nil, or by a prefix
 argument."
   (interactive
    (find-file-read-args "Find file in other frame: "
@@ -1723,7 +1725,8 @@ Like \\[find-file], but only allow a file that exists, 
and do not allow
 file names with wildcards.
 
 If ASYNC is non-nil, the file will be loaded into the buffer
-asynchronously.  Interactively, this is indicated by a prefix
+asynchronously.  Interactively, this is indicated by either
+setting `find-file-asynchronously' to non-nil, or by a prefix
 argument."
    (interactive
     (find-file-read-args "Find existing file: " t))
@@ -1781,7 +1784,8 @@ Interactively, or if WILDCARDS is non-nil in a call from 
Lisp,
 expand wildcards (if any) and replace the file with multiple files.
 
 If ASYNC is non-nil, the file will be loaded into the buffer
-asynchronously.  Interactively, this is indicated by a prefix
+asynchronously.  Interactively, this is indicated by either
+setting `find-file-asynchronously' to non-nil, or by a prefix
 argument."
   (interactive
    (save-selected-window
@@ -1823,7 +1827,8 @@ Interactively, or if WILDCARDS is non-nil in a call from 
Lisp,
 expand wildcards (if any) and replace the file with multiple files.
 
 If ASYNC is non-nil, the file will be loaded into the buffer
-asynchronously.  Interactively, this is indicated by a prefix
+asynchronously.  Interactively, this is indicated by either
+setting `find-file-asynchronously' to non-nil, or by a prefix
 argument.
 
 If the current buffer is an indirect buffer, or the base buffer
@@ -2493,7 +2498,8 @@ If Emacs already has a buffer which is visiting the file,
 this command asks you whether to visit it literally instead.
 
 If ASYNC is non-nil, the file will be loaded into the buffer
-asynchronously.  Interactively, this is indicated by a prefix
+asynchronously.  Interactively, this is indicated by either
+setting `find-file-asynchronously' to non-nil, or by a prefix
 argument.
 
 In non-interactive use, the value is the buffer where the file is