[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] feature/tramp-thread-safe 4615b91 4/7: Document visiting f
From: |
Michael Albinus |
Subject: |
[Emacs-diffs] feature/tramp-thread-safe 4615b91 4/7: Document visiting files asynchronously |
Date: |
Sat, 4 Aug 2018 06:50:11 -0400 (EDT) |
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
- [Emacs-diffs] feature/tramp-thread-safe updated (c6db534 -> d1f39eb), Michael Albinus, 2018/08/04
- [Emacs-diffs] feature/tramp-thread-safe 11ff7fa 5/7: Add list-threads command and thread-list-mode, Michael Albinus, 2018/08/04
- [Emacs-diffs] feature/tramp-thread-safe d7314b3 3/7: find-file-asynchronously can also be a regexp, Michael Albinus, 2018/08/04
- [Emacs-diffs] feature/tramp-thread-safe d1f39eb 7/7: Merge branch 'feature/tramp-thread-safe', Michael Albinus, 2018/08/04
- [Emacs-diffs] feature/tramp-thread-safe d7f3187 6/7: Improve vc-mutex use, Michael Albinus, 2018/08/04
- [Emacs-diffs] feature/tramp-thread-safe 4615b91 4/7: Document visiting files asynchronously,
Michael Albinus <=
- [Emacs-diffs] feature/tramp-thread-safe 4d340cd 2/7: Add find-file-asynchronously, Michael Albinus, 2018/08/04
- [Emacs-diffs] feature/tramp-thread-safe bba62df 1/7: Introducing thread-safe Tramp, Michael Albinus, 2018/08/04