doc: Introduce vim-differences #2141

This documents the differences between nvim and nvim.

Regarding the removal of references to 'renderoptions': it was never
added in the first place, so there's no need to mention its "removal".

11 files changed, 173 insertions, 36 deletions

diff --git a/runtime/doc/Makefile b/runtime/doc/Makefile
index 2b338cc565..2f9063231d 100644
--- a/runtime/doc/Makefile
+++ b/runtime/doc/Makefile
@@ -21,7 +21,6 @@ DOCS = \
 	digraph.txt \
 	editing.txt \
 	eval.txt \
-	remote_plugin.txt \
 	farsi.txt \
 	filetype.txt \
 	fold.txt \
@@ -76,6 +75,7 @@ DOCS = \
 	quotes.txt \
 	recover.txt \
 	remote.txt \
+	remote_plugin.txt \
 	repeat.txt \
 	rileft.txt \
 	russian.txt \
@@ -127,6 +127,7 @@ DOCS = \
 	usr_toc.txt \
 	various.txt \
 	vi_diff.txt \
+	vim_diff.txt \
 	visual.txt \
 	windows.txt
 
@@ -142,7 +143,6 @@ HTMLS = \
 	digraph.html \
 	editing.html \
 	eval.html \
-	remote_plugin.html \
 	farsi.html \
 	filetype.html \
 	fold.html \
@@ -196,6 +196,7 @@ HTMLS = \
 	quotes.html \
 	recover.html \
 	remote.html \
+	remote_plugin.html \
 	repeat.html \
 	rileft.html \
 	russian.html \
@@ -248,6 +249,7 @@ HTMLS = \
 	usr_toc.html \
 	various.html \
 	vi_diff.html \
+	vim_diff.html \
 	vimindex.html \
 	visual.html \
 	windows.html
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index 6a9e4f025d..dc236fc78f 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -862,13 +862,13 @@ TabEnter			Just after entering a tab page. |tab-page|
 TabLeave			Just before leaving a tab page. |tab-page|
 				A WinLeave event will have been triggered
 				first.
-							*TabNew*
+						 {Nvim} *TabNew*
 TabNew				When creating a new tab page. |tab-page|
 				After WinEnter and before TabEnter.
-							*TabNewEntered*
+						 {Nvim} *TabNewEntered*
 TabNewEntered			After entering a new tab page. |tab-page|
 				After BufEnter.
-							*TabClosed*
+						 {Nvim} *TabClosed*
 TabClosed			After closing a tab page. <afile> can be used
 				for the tab page number.
 							*TermChanged*
diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt
index cfa9dc8795..34ca6d0d12 100644
--- a/runtime/doc/help.txt
+++ b/runtime/doc/help.txt
@@ -166,6 +166,7 @@ Interfaces ~
 |sign.txt|	debugging signs
 
 Versions ~
+|vim_diff.txt|	Main differences between Nvim and Vim
 |vi_diff.txt|	Main differences between Vim and Vi
 						*sys-file-list*
 Remarks about specific systems ~
diff --git a/runtime/doc/nvim_intro.txt b/runtime/doc/nvim_intro.txt
index d6389a815d..d44648c575 100644
--- a/runtime/doc/nvim_intro.txt
+++ b/runtime/doc/nvim_intro.txt
@@ -1,4 +1,4 @@
-*nvim_intro.txt*    For Nvim.						 {Nvim}
+*nvim_intro.txt*    For Nvim.						{Nvim}
 
 
 		 NVIM REFERENCE MANUAL    by Thiago de Arruda
@@ -6,19 +6,20 @@
 
 Introduction to Nvim					*nvim* *nvim-intro*
 
-This is an introduction to Vim users that are just getting started with Nvim.
+This is an introduction for Vim users who are just getting started with Nvim.
 It is not meant for Vim beginners. For a basic introduction to Vim,
 see |help.txt|.
 
 For now, it is just an index with the most relevant topics/features that
 differentiate Nvim from Vim:
 
-1. Msgpack-RPC			|msgpack-rpc|
-2. Job control			|job-control|
-3. Python plugins		|nvim-python|
-4. Clipboard integration	|nvim-clipboard|
-5. Remote plugins		|remote-plugin|
-6. Provider infrastructure	|nvim-provider|
+1. Differences from Vim		|vim-differences|
+2. Msgpack-RPC			|msgpack-rpc|
+3. Job control			|job-control|
+4. Python plugins		|nvim-python|
+5. Clipboard integration	|nvim-clipboard|
+6. Remote plugins		|remote-plugin|
+7. Provider infrastructure	|nvim-provider|
 
 ==============================================================================
  vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/nvim_python.txt b/runtime/doc/nvim_python.txt
index 3e24163ad7..531036d567 100644
--- a/runtime/doc/nvim_python.txt
+++ b/runtime/doc/nvim_python.txt
@@ -1,4 +1,4 @@
-*nvim_python.txt*    For Nvim.						 {Nvim}
+*nvim_python.txt*    For Nvim.						{Nvim}
 
 
 		 NVIM REFERENCE MANUAL    by Thiago de Arruda
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 627bc4158e..a9e1d0f381 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -1620,8 +1620,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	|fold-marker|.
 
 			*'compatible'* *'cp'* *'nocompatible'* *'nocp'*
-'compatible' 'cp'	Removed. {Nvim}
-	"set nocp" is ignored, and "set cp" is an error.
+'compatible' 'cp'	Removed. |vim-differences| {Nvim}
 
 						*'complete'* *'cpt'* *E535*
 'complete' 'cpt'	string	(default: ".,w,b,u,t,i")
@@ -2093,7 +2092,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 			with system specific functions.
 
 						*'cryptmethod'* *'cm'*
-'cryptmethod'		Removed. {Nvim}
+'cryptmethod'		Removed. |vim-differences| {Nvim}
 
 						*'cscopepathcomp'* *'cspc'*
 'cscopepathcomp' 'cspc'	number	(default 0)
@@ -2413,11 +2412,10 @@ A jump table for the options with a short description can be found at |Q_op|.
 		both	width and height of windows is affected
 
 			   *'ed'* *'edcompatible'* *'noed'* *'noedcompatible'*
-'edcompatible' 'ed'	Removed. {Nvim}
-	"set noed" is ignored, and "set ed" is an error.
+'edcompatible' 'ed'	Removed. |vim-differences| {Nvim}
 
 					*'encoding'* *'enc'* *E543*
-'encoding' 'enc'	string (default: "latin1" or value from $LANG)
+'encoding' 'enc'	string (default: "utf-8" or value from $LANG)
 			global
 			{only available when compiled with the |+multi_byte|
 			feature}
@@ -4239,7 +4237,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	Otherwise only one space is inserted.
 
 					*'key'*
-'key'			Removed. {Nvim}
+'key'			Removed. |vim-differences| {Nvim}
 
 					*'keymap'* *'kmp'* *E544*
 'keymap' 'kmp'		string	(default "")
@@ -5390,7 +5388,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	characters are put before the number.
 	See |hl-LineNr|  and |hl-CursorLineNr| for the highlighting used for
 	the number.
-	
+
 	The number in front of the cursor line also depends on the value of
 	'number', see |number_relativenumber| for all combinations of the two
 	options.
@@ -5404,9 +5402,6 @@ A jump table for the options with a short description can be found at |Q_op|.
 	this option at the default "on".  Only switch it off when working with
 	old Vi scripts.
 
-						*'renderoptions'* *'rop'*
-'renderoptions' 'rop'	Removed. {Nvim} will choose the best renderer available.
-
 						*'report'*
 'report'		number	(default 2)
 			global
@@ -6022,7 +6017,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	    shm=at	Abbreviation, and truncate message when necessary.
 
 				 *'shortname'* *'sn'* *'noshortname'* *'nosn'*
-'shortname' 'sn'	Removed. {Nvim}
+'shortname' 'sn'	Removed. |vim-differences| {Nvim}
 
 						*'showbreak'* *'sbr'* *E595*
 'showbreak' 'sbr'	string	(default "")
@@ -7148,8 +7143,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 'ttybuiltin' 'tbi'	Removed. {Nvim}
 
 				     *'ttyfast'* *'tf'* *'nottyfast'* *'notf'*
-'ttyfast' 'tf'		Removed. {Nvim}
-	"set tf" is ignored, and "set notf" is an error.
+'ttyfast' 'tf'		Removed. |vim-differences| {Nvim}
 
 						*'ttymouse'* *'ttym'*
 'ttymouse' 'ttym'	string	(default depends on 'term')
diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt
index 4425caa9bb..1554b823eb 100644
--- a/runtime/doc/quickref.txt
+++ b/runtime/doc/quickref.txt
@@ -824,7 +824,6 @@ Short explanation of each option:		*option-list*
 'regexpengine'	  're'	    default regexp engine to use
 'relativenumber'  'rnu'	    show relative line number in front of each line
 'remap'			    allow mappings to work recursively
-'renderoptions'	  'rop'	    options for text rendering on Windows
 'report'		    threshold for reporting nr. of lines changed
 'restorescreen'   'rs'	    Win32: restore screen when exiting
 'revins'	  'ri'	    inserting characters will work backwards
diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index 214a7de6f4..19289dafec 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -4760,7 +4760,7 @@ DiffChange	diff mode: Changed line |diff.txt|
 DiffDelete	diff mode: Deleted line |diff.txt|
 							*hl-DiffText*
 DiffText	diff mode: Changed text within a changed line |diff.txt|
-							*hl-EndOfBuffer*
+						 {Nvim} *hl-EndOfBuffer*
 EndOfBuffer	filler lines (~) after the end of the buffer.
 		By default, this is highlighted like |hl-NonText|.
 							*hl-ErrorMsg*
diff --git a/runtime/doc/todo.txt b/runtime/doc/todo.txt
index 2e843bed63..f66bc961f0 100644
--- a/runtime/doc/todo.txt
+++ b/runtime/doc/todo.txt
@@ -1882,11 +1882,6 @@ When 'encoding' is utf-8 typing text at the end of the line causes previously
 typed characters to be redrawn.  Caused by patch 7.1.329. (Tyler Spivey, 2008
 Sep 3, 11)
 
-When Vim in an xterm owns the selection and the user does ":shell" Vim doesn't
-respond to selection requests.  Invoking XtDisownSelection() before executing
-the shell doesn't help.  Would require forking and doing a message loop, like
-what happens for the GUI.
-
 X11: Putting more than about 262040 characters of text on the clipboard and
 pasting it in another Vim doesn't work.  (Dominique Pelle, 2008 Aug 21-23)
 clip_x11_request_selection_cb() is called with zero value and length.
diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index c8dc331361..7797b02ba8 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -222,7 +222,7 @@ g8			Print the hex values of the bytes used in the
 			at compile time}
 
 						  *:sh* *:shell* *E371* *E360*
-:sh[ell]		Removed. {Nvim}
+:sh[ell]		Removed. |vim-differences| {Nvim}
 
 							*:!cmd* *:!* *E34*
 :!{cmd}			Execute {cmd} with the shell. See also 'shell'.
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
new file mode 100644
index 0000000000..82b38381ca
--- /dev/null
+++ b/runtime/doc/vim_diff.txt
@@ -0,0 +1,145 @@
+*vim_diff.txt*    For Nvim.						{Nvim}
+
+
+			    NVIM REFERENCE MANUAL
+
+
+Differences between Nvim and Vim			       *vim-differences*
+
+Throughout the help files, differences between Nvim and Vim are indicated via
+the "{Nvim}" tag.  This document is a complete and centralized list of all
+these differences.
+
+1. Configuration		|nvim-configuration|
+2. Option defaults		|nvim-option-defaults|
+3. Changed features		|nvim-features-changed|
+4. New features			|nvim-features-new|
+5. Missing legacy features	|nvim-features-missing|
+6. Removed features		|nvim-features-removed|
+
+
+==============================================================================
+1. Configuration					    *nvim-configuration*
+
+- Use ".nvimrc" instead of ".vimrc" for storing configuration.
+- Use ".nvim" instead of ".vim" to store configuration files.
+- Use ".nviminfo" instead of ".viminfo" for persistent session information.
+
+==============================================================================
+2. Option defaults					  *nvim-option-defaults*
+
+- 'nocompatible' is always set
+- 'encoding' defaults to "utf-8"
+
+==============================================================================
+3. Changed features					 *nvim-features-changed*
+
+Nvim always builds with all features, in contrast to Vim which may have
+certain features removed/added at compile-time.  This is like if Vim's "HUGE"
+build was the only Vim release type (except Nvim is smaller than Vim's "HUGE"
+build).
+
+If a Python interpreter is available on your `$PATH`, |:python| and |:python3|
+are always available and may be used simultaneously in separate plugins.  The
+`neovim` pip package must be installed to use Python plugins in Nvim (see
+|nvim-python|).
+
+==============================================================================
+4. New Features						     *nvim-features-new*
+
+See |nvim-intro| for a list of Nvim's largest new features.
+
+Nvim has a built-in terminal emulator, which can be accessed using
+`:term[inal]`.  By default, <C-\><C-n> exits terminal mode, but `:tmap` and
+`:tnoremap` can be used to change this and create other terminal mode
+mappings.
+
+Meta key chords are recognized (even in the terminal).
+- <M-1>, <M-2>, ...
+- <M-BS>, <M-Del>, <M-Ins>, ...
+- <M-/>, <M-\>, ...
+- <M-Space>, <M-Enter>, <M-=>, <M-->, <M-?>, <M-$>, ...
+
+CTRL-SHIFT-... key chords are distinguished from CTRL-... variants (even in
+the terminal).
+- <C-Tab>, <C-S-Tab>
+- <C-BS>, <C-S-BS>
+- <C-Enter>, <C-S-Enter>
+
+Events:
+- |TabNew|
+- |TabNewEntered|
+- |TabClosed|
+
+Highlight groups:
+- |hl-EndOfBuffer|
+
+==============================================================================
+5. Missing legacy features				 *nvim-features-missing*
+
+These legacy Vim features may be implemented in the future, but they are not
+planned for the current milestone.
+
+- vim.bindeval() (new feature in Vim 7.4 Python interface)
+- if_ruby
+- if_lua
+- if_perl
+- if_mzscheme
+- if_tcl
+
+==============================================================================
+6. Removed features					 *nvim-features-removed*
+
+These features are in Vim, but have been intentionally removed from Nvim.
+
+Vi-compatible mode
+- ":set nocompatible" is ignored
+- ":set compatible" is an error
+
+Ed-compatible mode
+- ":set noedcompatible" is ignored
+- ":set edcompatible" is an error
+
+'ttyfast'
+- ":set ttyfast" is ignored
+- ":set nottyfast" is an error
+
+EBCDIC support
+
+8.3 filesystem support
+- 'shortname'
+
+Encryption support
+- 'cryptmethod'
+- 'key'
+
+MS-DOS support
+- 'bioskey'
+- 'conskey'
+
+'shelltype'
+":shell"
+":mode", no longer accepts an argument
+'textauto'
+'textmode'
+
+"Easy mode" (eview, evim, nvim -y)
+"(g)vimdiff" (solely an alias for (g)nvim -d, i.e. |diff-mode|)
+"Vi mode" (nvim -v)
+
+The ability to start nvim via the following aliases has been removed in favor
+of just using their command line arguments:
+
+  ex        nvim -e
+  exim      nvim -E
+  view      nvim -R
+  gvim      nvim -g
+  gex       nvim -eg
+  gview     nvim -Rg
+  rvim      nvim -Z
+  rview     nvim -RZ
+  rgvim     nvim -gZ
+  rgview    nvim -RgZ
+
+==============================================================================
+ vim:tw=78:ts=8:noet:ft=help:norl: