Merge remote-tracking branch 'upstream/master' into aucmd_textputpostaucmd_textputpost

1 files changed, 60 insertions, 63 deletions

diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt
index f77db5fab3..7df2eb9742 100644
--- a/runtime/doc/editing.txt
+++ b/runtime/doc/editing.txt
@@ -169,33 +169,26 @@ If you want to keep the changed buffer without saving it, switch on the
 2. Editing a file					*edit-a-file*
 
 							*:e* *:edit* *reload*
-:e[dit] [++opt] [+cmd]	Edit the current file.  This is useful to re-edit the
+:e[dit][!] [++opt] [+cmd]
+			Edit the current file.  This is useful to re-edit the
 			current file, when it has been changed outside of Vim.
-			This fails when changes have been made to the current
-			buffer and 'autowriteall' isn't set or the file can't
-			be written.
-			Also see |++opt| and |+cmd|.
-
 							*:edit!* *discard*
-:e[dit]! [++opt] [+cmd]
-			Edit the current file always.  Discard any changes to
-			the current buffer.  This is useful if you want to
-			start all over again.
+			If [!] is given, unsaved changes in the current buffer
+			are discarded. Without [!] the command fails if there
+			are unsaved changes, unless 'autowriteall' is set and
+			the file can be written.
 			Also see |++opt| and |+cmd|.
 
 							*:edit_f*
-:e[dit] [++opt] [+cmd] {file}
+:e[dit][!] [++opt] [+cmd] {file}
 			Edit {file}.
-			This fails when changes have been made to the current
-			buffer, unless 'hidden' is set or 'autowriteall' is
-			set and the file can be written.
-			Also see |++opt| and |+cmd|.
-
 							*:edit!_f*
-:e[dit]! [++opt] [+cmd] {file}
-			Edit {file} always.  Discard any changes to the
-			current buffer.
+			If [!] is given, unsaved changes in the current buffer
+			are discarded. Without [!] the command fails if there
+			are unsaved changes, unless 'hidden' is set or
+			'autowriteall' is set and the file can be written.
 			Also see |++opt| and |+cmd|.
+
 							*:edit_#* *:e#*
 :e[dit] [++opt] [+cmd] #[count]
 			Edit the [count]th buffer (as shown by |:files|).
@@ -356,7 +349,9 @@ as a wildcard when "[" is in the 'isfname' option.  A simple way to avoid this
 is to use "path\[[]abc]", this matches the file "path\[abc]".
 
 					*starstar-wildcard*
-Expanding "**" is possible on Unix, Win32, macOS and a few other systems.
+Expanding "**" is possible on Unix, Win32, macOS and a few other systems (but
+it may depend on your 'shell' setting on Unix and macOS. It's known to work
+correctly for zsh; for bash this requires at least bash version >= 4.X).
 This allows searching a directory tree.  This goes up to 100 directories deep.
 Note there are some commands where this works slightly differently, see
 |file-searching|.
@@ -539,10 +534,10 @@ set to "dos", otherwise it is set to "unix".  When 'fileformats' includes
 "mac".
 
 If the 'fileformat' option is set to "dos" on non-MS-Windows systems the
-message "[dos format]" is shown to remind you that something unusual is
-happening.  On MS-Windows systems you get the message "[unix format]" if
-'fileformat' is set to "unix".  On all systems but the Macintosh you get the
-message "[mac format]" if 'fileformat' is set to "mac".
+message "[dos]" is shown to remind you that something unusual is happening.  On
+MS-Windows systems you get the message "[unix]" if 'fileformat' is set to
+"unix".  On all systems you get the message "[mac]" if 'fileformat' is set to
+"mac".
 
 If the 'fileformats' option is empty and DOS format is used, but while reading
 a file some lines did not end in <CR><NL>, "[CR missing]" will be included in
@@ -804,8 +799,8 @@ first line (the last line in Ex mode).
 
 							*{arglist}*
 The wildcards in the argument list are expanded and the file names are sorted.
-Thus you can use the command "vim *.c" to edit all the C files.  From within
-Vim the command ":n *.c" does the same.
+Thus you can use the command `vim *.c` to edit all the C files.  From within
+Vim the command `:n *.c` does the same.
 
 White space is used to separate file names.  Put a backslash before a space or
 tab to include it in a file name.  E.g., to edit the single file "foo bar": >
@@ -820,12 +815,10 @@ by the shell before executing the find program.
 When there is an argument list you can see which file you are editing in the
 title of the window (if there is one and 'title' is on) and with the file
 message you get with the "CTRL-G" command.  You will see something like
-	(file 4 of 11)
-If 'shortmess' contains 'f' it will be
 	(4 of 11)
 If you are not really editing the file at the current position in the argument
 list it will be
-	(file (4) of 11)
+	((4) of 11)
 This means that you are position 4 in the argument list, but not editing the
 fourth file in the argument list.  This happens when you do ":e file".
 
@@ -889,7 +882,7 @@ Example: >
 	:args *.c
 	:argdo set ff=unix | update
 This sets the 'fileformat' option to "unix" and writes the file if it is now
-changed.  This is done for all *.c files.
+changed.  This is done for all `*.c` files.
 
 Example: >
 	:args *.[ch]
@@ -1058,14 +1051,14 @@ lost the original file.
 
 						*DOS-format-write*
 If the 'fileformat' is "dos", <CR><NL> is used for <EOL>.  This is default
-for Windows. On other systems the message "[dos format]" is shown to
+for Windows. On other systems the message "[dos]" is shown to
 remind you that an unusual <EOL> was used.
 						*Unix-format-write*
 If the 'fileformat' is "unix", <NL> is used for <EOL>.  On Windows
-the message "[unix format]" is shown.
+the message "[unix]" is shown.
 						*Mac-format-write*
-If the 'fileformat' is "mac", <CR> is used for <EOL>.  On non-Mac systems the
-message "[mac format]" is shown.
+If the 'fileformat' is "mac", <CR> is used for <EOL>.  The
+message "[mac]" is shown.
 
 See also |file-formats| and the 'fileformat' and 'fileformats' options.
 
@@ -1078,6 +1071,13 @@ will get the ACL info of the original file.
    The ACL info is also used to check if a file is read-only (when opening the
 file).
 
+					*xattr* *E1506* *E1508* *E1509*
+xattr stands for Extended Attributes.  It is an advanced way to save metadata
+alongside the file in the filesystem.  It depends on the actual filesystem
+being used and Vim supports it only on a Linux system.
+   Vim attempts to preserve the extended attribute info when writing a file.
+The backup file will get the extended attribute of the original file.
+
 						*read-only-share*
 When MS-Windows shares a drive on the network it can be marked as read-only.
 This means that even if the file read-only attribute is absent, and the ACL
@@ -1217,10 +1217,10 @@ MULTIPLE WINDOWS AND BUFFERS				*window-exit*
 							*:confirm* *:conf*
 :conf[irm] {command}	Execute {command}, and use a dialog when an
 			operation has to be confirmed.  Can be used on the
-			|:q|, |:qa| and |:w| commands (the latter to override
-			a read-only setting), and any other command that can
-			fail in such a way, such as |:only|, |:buffer|,
-			|:bdelete|, etc.
+			|:edit|, |:q|, |:qa| and |:w| commands (the latter to
+			override a read-only setting), and any commands that
+			can fail because of unsaved changes, such as |:only|,
+			|:buffer|, |:bdelete|, etc.
 
 Examples: >
   :confirm w foo
@@ -1245,8 +1245,8 @@ If you want to always use ":confirm", set the 'confirm' option.
 			|:diffsplit|, |:diffpatch|, |:pedit|, |:redir|,
 			|:source|, |:update|, |:visual|, |:vsplit|,
 			and |:qall| if 'confirm' is set.
-			{only in Win32 GUI, in console `browse edit` works
-			if the FileExplorer autocommand group exists}
+			Note: only in Win32 GUI; in console `:browse edit`
+			works if the FileExplorer autocommand group exists.
 			When ":browse" is not possible you get an error
 			message.  If {command} doesn't support browsing, the
 			{command} is executed without a dialog.
@@ -1581,7 +1581,7 @@ There are three different types of searching:
    so they work on all operating systems.  Note that "**" only acts as a
    special wildcard when it is at the start of a name.
 
-   The usage of '*' is quite simple: It matches 0 or more characters.  In a
+   The usage of "*" is quite simple: It matches 0 or more characters.  In a
    search pattern this would be ".*".  Note that the "." is not used for file
    searching.
 
@@ -1668,29 +1668,26 @@ There are three different types of searching:
 ==============================================================================
 12. Trusted Files						*trust*
 
-Nvim has the ability to execute arbitrary code through the 'exrc' option. In
-order to prevent executing code from untrusted sources, Nvim has the concept of
-"trusted files". An untrusted file will not be executed without the user's
-consent, and a user can permanently mark a file as trusted or untrusted using
-the |:trust| command or the |vim.secure.read()| function.
+Nvim executes arbitrary code found on the filesystem if 'exrc' is enabled. To
+prevent executing malicious code, only "trusted files" are executed. You can
+mark a file as trusted or untrusted using the |:trust| command or the
+|vim.secure.read()| function.
 
 							*:trust* *E5570*
-:trust [++deny] [++remove] [{file}]
-
-			Manage files in the trust database. Without any options
-			or arguments, :trust adds the file associated with the
-			current buffer to the trust database, along with the
-			SHA256 hash of its contents.
-
-			[++deny] marks the file associated with the current
-			buffer (or {file}, if given) as denied; no prompts will
-			be displayed to the user and the file will never be
-			executed.
-
-			[++remove] removes the file associated with the current
-			buffer (or {file}, if given) from the trust database.
-			Future attempts to read the file in a secure setting
-			(i.e. with 'exrc' or |vim.secure.read()|) will prompt
-			the user if the file is trusted.
+:trust [++deny] [++remove] [file]
+
+			Manage trusted files. Without ++ options, :trust marks
+			the current buffer as trusted, keyed on a hash of its
+			contents. The trust list is stored on disk, Nvim will
+			re-use it after restarting.
+
+			[++deny] marks [file] (or current buffer if no [file]) as
+			untrusted: it will never be executed, 'exrc' will
+			ignore it.
+
+			[++remove] removes [file] (or current buffer if no
+			[file]) from the trust list. When the file is
+			discovered by 'exrc' or |vim.secure.read()|, the user
+			will be asked whether to trust or deny the file.
 
  vim:tw=78:ts=8:noet:ft=help:norl: