Adding upstream version 2:8.1.0875.upstream/2%8.1.0875upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 412 insertions, 0 deletions

diff --git a/runtime/doc/undo.txt b/runtime/doc/undo.txt
new file mode 100644
index 0000000..b6c9809
--- /dev/null
+++ b/runtime/doc/undo.txt
@@ -0,0 +1,412 @@
+*undo.txt*      For Vim version 8.1.  Last change: 2019 Jan 04
+
+
+		  VIM REFERENCE MANUAL    by Bram Moolenaar
+
+
+Undo and redo						*undo-redo*
+
+The basics are explained in section |02.5| of the user manual.
+
+1. Undo and redo commands	|undo-commands|
+2. Two ways of undo		|undo-two-ways|
+3. Undo blocks			|undo-blocks|
+4. Undo branches		|undo-branches|
+5. Undo persistence		|undo-persistence|
+6. Remarks about undo		|undo-remarks|
+
+==============================================================================
+1. Undo and redo commands				*undo-commands*
+
+<Undo>		or					*undo* *<Undo>* *u*
+u			Undo [count] changes.  {Vi: only one level}
+
+							*:u* *:un* *:undo*
+:u[ndo]			Undo one change.  {Vi: only one level}
+								*E830*
+:u[ndo] {N}		Jump to after change number {N}.  See |undo-branches|
+			for the meaning of {N}.  {not in Vi}
+
+							*CTRL-R*
+CTRL-R			Redo [count] changes which were undone.  {Vi: redraw
+			screen}
+
+							*:red* *:redo* *redo*
+:red[o]			Redo one change which was undone.  {Vi: no redo}
+
+							*U*
+U			Undo all latest changes on one line, the line where
+			the latest change was made. |U| itself also counts as
+			a change, and thus |U| undoes a previous |U|.
+			{Vi: while not moved off of the last modified line}
+
+The last changes are remembered.  You can use the undo and redo commands above
+to revert the text to how it was before each change.  You can also apply the
+changes again, getting back the text before the undo.
+
+The "U" command is treated by undo/redo just like any other command.  Thus a
+"u" command undoes a "U" command and a 'CTRL-R' command redoes it again.  When
+mixing "U", "u" and 'CTRL-R' you will notice that the "U" command will
+restore the situation of a line to before the previous "U" command.  This may
+be confusing.  Try it out to get used to it.
+The "U" command will always mark the buffer as changed.  When "U" changes the
+buffer back to how it was without changes, it is still considered changed.
+Use "u" to undo changes until the buffer becomes unchanged.
+
+==============================================================================
+2. Two ways of undo					*undo-two-ways*
+
+How undo and redo commands work depends on the 'u' flag in 'cpoptions'.
+There is the Vim way ('u' excluded) and the Vi-compatible way ('u' included).
+In the Vim way, "uu" undoes two changes.  In the Vi-compatible way, "uu" does
+nothing (undoes an undo).
+
+'u' excluded, the Vim way:
+You can go back in time with the undo command.  You can then go forward again
+with the redo command.  If you make a new change after the undo command,
+the redo will not be possible anymore.
+
+'u' included, the Vi-compatible way:
+The undo command undoes the previous change, and also the previous undo command.
+The redo command repeats the previous undo command.  It does NOT repeat a
+change command, use "." for that.
+
+Examples	Vim way			Vi-compatible way	~
+"uu"		two times undo		no-op
+"u CTRL-R"	no-op			two times undo
+
+Rationale:  Nvi uses the "." command instead of CTRL-R.  Unfortunately, this
+	    is not Vi compatible.  For example "dwdwu." in Vi deletes two
+	    words, in Nvi it does nothing.
+
+==============================================================================
+3. Undo blocks						*undo-blocks*
+
+One undo command normally undoes a typed command, no matter how many changes
+that command makes.  This sequence of undo-able changes forms an undo block.
+Thus if the typed key(s) call a function, all the commands in the function are
+undone together.
+
+If you want to write a function or script that doesn't create a new undoable
+change but joins in with the previous change use this command:
+
+						*:undoj* *:undojoin* *E790*
+:undoj[oin]		Join further changes with the previous undo block.
+			Warning: Use with care, it may prevent the user from
+			properly undoing changes.  Don't use this after undo
+			or redo.
+			{not in Vi}
+
+This is most useful when you need to prompt the user halfway through a change.
+For example in a function that calls |getchar()|.  Do make sure that there was
+a related change before this that you must join with.
+
+This doesn't work by itself, because the next key press will start a new
+change again.  But you can do something like this: >
+
+	:undojoin | delete
+
+After this an "u" command will undo the delete command and the previous
+change.
+
+To do the opposite, break a change into two undo blocks, in Insert mode use
+CTRL-G u.  This is useful if you want an insert command to be undoable in
+parts.  E.g., for each sentence.  |i_CTRL-G_u|
+Setting the value of 'undolevels' also breaks undo.  Even when the new value
+is equal to the old value.
+
+==============================================================================
+4. Undo branches				*undo-branches* *undo-tree*
+
+Above we only discussed one line of undo/redo.  But it is also possible to
+branch off.  This happens when you undo a few changes and then make a new
+change.  The undone changes become a branch.  You can go to that branch with
+the following commands.
+
+This is explained in the user manual: |usr_32.txt|.
+
+							*:undol* *:undolist*
+:undol[ist]		List the leafs in the tree of changes.  Example:
+			   number changes  when               saved ~
+			       88      88  2010/01/04 14:25:53
+			      108     107  08/07 12:47:51
+			      136      46  13:33:01             7
+			      166     164  3 seconds ago
+
+			The "number" column is the change number.  This number
+			continuously increases and can be used to identify a
+			specific undo-able change, see |:undo|.
+			The "changes" column is the number of changes to this
+			leaf from the root of the tree.
+			The "when" column is the date and time when this
+			change was made.  The four possible formats are:
+			    N seconds ago
+			    HH:MM:SS             hour, minute, seconds
+			    MM/DD HH:MM:SS       idem, with month and day
+			    YYYY/MM/DD HH:MM:SS  idem, with year
+			The "saved" column specifies, if this change was
+			written to disk and which file write it was. This can
+			be used with the |:later| and |:earlier| commands.
+			For more details use the |undotree()| function.
+
+							*g-*
+g-			Go to older text state.  With a count repeat that many
+			times.  {not in Vi}
+							*:ea* *:earlier*
+:earlier {count}	Go to older text state {count} times.
+:earlier {N}s		Go to older text state about {N} seconds before.
+:earlier {N}m		Go to older text state about {N} minutes before.
+:earlier {N}h		Go to older text state about {N} hours before.
+:earlier {N}d		Go to older text state about {N} days before.
+
+:earlier {N}f		Go to older text state {N} file writes before.
+			When changes were made since the last write
+			":earlier 1f" will revert the text to the state when
+			it was written.  Otherwise it will go to the write
+			before that.
+			When at the state of the first file write, or when
+			the file was not written, ":earlier 1f" will go to
+			before the first change.
+
+							*g+*
+g+			Go to newer text state.  With a count repeat that many
+			times.  {not in Vi}
+							*:lat* *:later*
+:later {count}		Go to newer text state {count} times.
+:later {N}s		Go to newer text state about {N} seconds later.
+:later {N}m		Go to newer text state about {N} minutes later.
+:later {N}h		Go to newer text state about {N} hours later.
+:later {N}d		Go to newer text state about {N} days later.
+
+:later {N}f		Go to newer text state {N} file writes later.
+			When at the state of the last file write, ":later 1f"
+			will go to the newest text state.
+
+
+Note that text states will become unreachable when undo information is cleared
+for 'undolevels'.
+
+Don't be surprised when moving through time shows multiple changes to take
+place at a time.  This happens when moving through the undo tree and then
+making a new change.
+
+EXAMPLE
+
+Start with this text:
+	one two three ~
+
+Delete the first word by pressing "x" three times:
+	ne two three ~
+	e two three ~
+	 two three ~
+
+Now undo that by pressing "u" three times:
+	e two three ~
+	ne two three ~
+	one two three ~
+
+Delete the second word by pressing "x" three times:
+	one wo three ~
+	one o three ~
+	one  three ~
+
+Now undo that by using "g-" three times:
+	one o three ~
+	one wo three ~
+	 two three ~
+
+You are now back in the first undo branch, after deleting "one".  Repeating
+"g-" will now bring you back to the original text:
+	e two three ~
+	ne two three ~
+	one two three ~
+
+Jump to the last change with ":later 1h":
+	one  three ~
+
+And back to the start again with ":earlier 1h":
+	one two three ~
+
+
+Note that using "u" and CTRL-R will not get you to all possible text states
+while repeating "g-" and "g+" does.
+
+==============================================================================
+5. Undo persistence		*undo-persistence* *persistent-undo*
+
+When unloading a buffer Vim normally destroys the tree of undos created for
+that buffer.  By setting the 'undofile' option, Vim will automatically save
+your undo history when you write a file and restore undo history when you edit
+the file again.
+
+The 'undofile' option is checked after writing a file, before the BufWritePost
+autocommands.  If you want to control what files to write undo information
+for, you can use a BufWritePre autocommand: >
+	au BufWritePre /tmp/* setlocal noundofile
+
+Vim saves undo trees in a separate undo file, one for each edited file, using
+a simple scheme that maps filesystem paths directly to undo files. Vim will
+detect if an undo file is no longer synchronized with the file it was written
+for (with a hash of the file contents) and ignore it when the file was changed
+after the undo file was written, to prevent corruption.  An undo file is also
+ignored if its owner differs from the owner of the edited file, except when
+the owner of the undo file is the current user.  Set 'verbose' to get a
+message about that when opening a file.
+
+Undo files are normally saved in the same directory as the file.  This can be
+changed with the 'undodir' option.
+
+When the file is encrypted, the text in the undo file is also crypted.  The
+same key and method is used. |encryption|
+
+Note that text properties are not stored in the undo file.  You can restore
+text properties so long as a buffer is loaded, but you cannot restore them
+from an undo file.  Rationale: It would require the associated text property
+types to be defined in exactly the same was as before, which cannot be
+guaranteed.
+
+You can also save and restore undo histories by using ":wundo" and ":rundo"
+respectively:
+							*:wundo* *:rundo*
+:wundo[!] {file}
+		Write undo history to {file}.
+		When {file} exists and it does not look like an undo file
+		(the magic number at the start of the file is wrong), then
+		this fails, unless the ! was added.
+		If it exists and does look like an undo file it is
+		overwritten. If there is no undo-history, nothing will be 
+		written.
+		Implementation detail: Overwriting happens by first deleting
+		the existing file and then creating a new file with the same
+		name. So it is not possible to overwrite an existing undofile
+		in a write-protected directory.
+		{not in Vi}
+
+:rundo {file}	Read undo history from {file}.
+		{not in Vi}
+
+You can use these in autocommands to explicitly specify the name of the
+history file.  E.g.: >
+
+	au BufReadPost * call ReadUndo()
+	au BufWritePost * call WriteUndo()
+	func ReadUndo()
+	  if filereadable(expand('%:h'). '/UNDO/' . expand('%:t'))
+	    rundo %:h/UNDO/%:t
+	  endif
+	endfunc
+	func WriteUndo()
+	  let dirname = expand('%:h') . '/UNDO'
+	  if !isdirectory(dirname)
+	    call mkdir(dirname)
+	  endif
+	  wundo %:h/UNDO/%:t
+	endfunc
+
+You should keep 'undofile' off, otherwise you end up with two undo files for
+every write.
+
+You can use the |undofile()| function to find out the file name that Vim would
+use.
+
+Note that while reading/writing files and 'undofile' is set most errors will
+be silent, unless 'verbose' is set.  With :wundo and :rundo you will get more
+error messages, e.g., when the file cannot be read or written.
+
+NOTE: undo files are never deleted by Vim.  You need to delete them yourself.
+
+Reading an existing undo file may fail for several reasons:
+*E822*	It cannot be opened, because the file permissions don't allow it.
+*E823*	The magic number at the start of the file doesn't match.  This usually
+	means it is not an undo file.
+*E824*	The version number of the undo file indicates that it's written by a
+	newer version of Vim.  You need that newer version to open it.  Don't
+	write the buffer if you want to keep the undo info in the file.
+"File contents changed, cannot use undo info"
+	The file text differs from when the undo file was written.  This means
+	the undo file cannot be used, it would corrupt the text.  This also
+	happens when 'encoding' differs from when the undo file was written.
+*E825*  The undo file does not contain valid contents and cannot be used.
+*E826*  The undo file is encrypted but decryption failed.
+*E827*  The undo file is encrypted but this version of Vim does not support
+	encryption.  Open the file with another Vim.
+*E832*  The undo file is encrypted but 'key' is not set, the text file is not
+	encrypted.  This would happen if the text file was written by Vim
+	encrypted at first, and later overwritten by not encrypted text.
+	You probably want to delete this undo file.
+"Not reading undo file, owner differs"
+	The undo file is owned by someone else than the owner of the text
+	file.  For safety the undo file is not used.
+
+Writing an undo file may fail for these reasons:
+*E828*	The file to be written cannot be created.  Perhaps you do not have
+	write permissions in the directory.
+"Cannot write undo file in any directory in 'undodir'"
+	None of the directories in 'undodir' can be used.
+"Will not overwrite with undo file, cannot read"
+	A file exists with the name of the undo file to be written, but it
+	cannot be read.  You may want to delete this file or rename it.
+"Will not overwrite, this is not an undo file"
+	A file exists with the name of the undo file to be written, but it
+	does not start with the right magic number.  You may want to delete
+	this file or rename it.
+"Skipping undo file write, nothing to undo"
+	There is no undo information to be written, nothing has been changed
+	or 'undolevels' is negative.
+*E829*	An error occurred while writing the undo file.  You may want to try
+	again.
+
+==============================================================================
+6. Remarks about undo					*undo-remarks*
+
+The number of changes that are remembered is set with the 'undolevels' option.
+If it is zero, the Vi-compatible way is always used.  If it is negative no
+undo is possible.  Use this if you are running out of memory.
+
+							*clear-undo*
+When you set 'undolevels' to -1 the undo information is not immediately
+cleared, this happens at the next change.  To force clearing the undo
+information you can use these commands: >
+	:let old_undolevels = &undolevels
+	:set undolevels=-1
+	:exe "normal a \<BS>\<Esc>"
+	:let &undolevels = old_undolevels
+	:unlet old_undolevels
+
+Marks for the buffer ('a to 'z) are also saved and restored, together with the
+text.  {Vi does this a little bit different}
+
+When all changes have been undone, the buffer is not considered to be changed.
+It is then possible to exit Vim with ":q" instead of ":q!" {not in Vi}.  Note
+that this is relative to the last write of the file.  Typing "u" after ":w"
+actually changes the buffer, compared to what was written, so the buffer is
+considered changed then.
+
+When manual |folding| is being used, the folds are not saved and restored.
+Only changes completely within a fold will keep the fold as it was, because
+the first and last line of the fold don't change.
+
+The numbered registers can also be used for undoing deletes.  Each time you
+delete text, it is put into register "1.  The contents of register "1 are
+shifted to "2, etc.  The contents of register "9 are lost.  You can now get
+back the most recent deleted text with the put command: '"1P'.  (also, if the
+deleted text was the result of the last delete or copy operation, 'P' or 'p'
+also works as this puts the contents of the unnamed register).  You can get
+back the text of three deletes ago with '"3P'.
+
+						*redo-register*
+If you want to get back more than one part of deleted text, you can use a
+special feature of the repeat command ".".  It will increase the number of the
+register used.  So if you first do ""1P", the following "." will result in a
+'"2P'.  Repeating this will result in all numbered registers being inserted.
+
+Example:	If you deleted text with 'dd....' it can be restored with
+		'"1P....'.
+
+If you don't know in which register the deleted text is, you can use the
+:display command.  An alternative is to try the first register with '"1P', and
+if it is not what you want do 'u.'.  This will remove the contents of the
+first put, and repeat the put command for the second register.  Repeat the
+'u.' until you got what you want.
+
+ vim:tw=78:ts=8:noet:ft=help:norl: