Merge branch 'master' into yagebu/option-fixes

1 files changed, 108 insertions, 30 deletions

diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 24410ddaac..3924dd4ebe 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -6,11 +6,10 @@
 
 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.
+Nvim differs from Vim in many ways, big and small.  This document is
+a complete and centralized reference of those differences.
 
-				      Type <M-]> to see the table of contents.
+				      Type |gO| to see the table of contents.
 
 ==============================================================================
 1. Configuration					    *nvim-configuration*
@@ -33,8 +32,10 @@ these differences.
 - 'backupdir' defaults to .,~/.local/share/nvim/backup (|xdg|)
 - 'belloff' defaults to "all"
 - 'complete' doesn't include "i"
+- 'cscopeverbose' is enabled
 - 'directory' defaults to ~/.local/share/nvim/swap// (|xdg|), auto-created
 - 'display' defaults to "lastline"
+- 'fillchars' defaults (in effect) to "vert:│,fold:·"
 - 'formatoptions' defaults to "tcqj"
 - 'history' defaults to 10000 (the maximum)
 - 'hlsearch' is set by default
@@ -48,6 +49,7 @@ these differences.
 - 'ruler' is set by default
 - 'sessionoptions' doesn't include "options"
 - 'showcmd' is set by default
+- 'sidescroll' defaults to 1
 - 'smarttab' is set by default
 - 'tabpagemax' defaults to 50
 - 'tags' defaults to "./tags;,tags"
@@ -61,26 +63,46 @@ these differences.
 
 MAJOR COMPONENTS ~
 
-Embedded terminal emulator	|terminal-emulator|
-RPC API				|RPC|
-Shared data			|shada|
-XDG base directories		|xdg|
+API				|API|
+Lua scripting			|lua|
 Job control			|job-control|
 Remote plugins			|remote-plugin|
-Python plugins			|provider-python|
-Clipboard integration		|provider-clipboard|
+Providers
+  Clipboard			|provider-clipboard|
+  Python plugins		|provider-python|
+  Ruby plugins			|provider-ruby|
+Shared data			|shada|
+Embedded terminal		|terminal|
+VimL parser			|nvim_parse_expression()|
+XDG base directories		|xdg|
 
 USER EXPERIENCE  ~
 
-Working intuitively and consistently is a major goal of Nvim. Examples:
+Working intuitively and consistently is a major goal of Nvim.
+
+							*feature-compile*
+- Nvim always includes ALL features, in contrast to Vim (which ships with
+  various combinations of 100+ optional features). Think of it as a leaner
+  version of Vim's "HUGE" build. This reduces surface area for bugs, and
+  removes a common source of confusion and friction for users.
 
-- Nvim does not have `-X`, a platform-specific option "sometimes" available in
-  Vim (with potential surprises: http://stackoverflow.com/q/14635295). Nvim
-  avoids features that cannot be provided on all platforms--instead that is
-  delegated to external plugins/extensions.
+- Nvim avoids features that cannot be provided on all platforms; instead that
+  is delegated to external plugins/extensions. E.g. the `-X` platform-specific
+  option is "sometimes" available in Vim (with potential surprises:
+  http://stackoverflow.com/q/14635295).
 
-- Test-only globals and functions such as test_autochdir(), test_settime(),
-  etc., are not exposed (because they don't exist).
+- Vim's internal test functions (test_autochdir(), test_settime(), etc.) are
+  not exposed (nor implemented); instead Nvim has a robust API.
+
+- Behaviors, options, documentation are removed if they cost users more time
+  than they save.
+
+Usability details have been improved where the benefit outweighs any
+backwards-compatibility cost. Some examples:
+
+- |K| in help documents can be used like |CTRL-]|.
+- Directories for 'directory' and 'undodir' are auto-created.
+- Terminal features such as 'guicursor' are enabled where possible.
 
 ARCHITECTURE ~
 
@@ -89,10 +111,13 @@ stability and allows those plugins to work without blocking the editor. Even
 "legacy" Python and Ruby plugins which use the old Vim interfaces (|if_py| and
 |if_ruby|) run out-of-process.
 
+Platform and I/O facilities are built upon libuv. Nvim benefits from libuv
+features and bug fixes, and other projects benefit from improvements to libuv
+by Nvim developers.
 
 FEATURES ~
 
-"Outline": Type <M-]> in |:Man| and |:help| pages to see a document outline.
+"Outline": Type |gO| in |:Man| and |:help| pages to see a document outline.
 
 |META| (ALT) chords are recognized, even in the terminal. Any |<M-| mapping
 will work. Some examples: <M-1>, <M-2>, <M-BS>, <M-Del>, <M-Ins>, <M-/>,
@@ -119,14 +144,15 @@ Variables:
   |v:windowid| is always available (for use by external UIs)
 
 Commands:
-  |:CheckHealth|
+  |:checkhealth|
   |:drop| is available on all platforms
   |:Man| is available by default, with many improvements such as completion
+  |:tchdir| tab-local |current-directory|
 
 Functions:
   |dictwatcheradd()| notifies a callback whenever a |Dict| is modified
   |dictwatcherdel()|
-  |execute()| works with |:redir|
+  |menu_get()|
   |msgpackdump()|, |msgpackparse()| provide msgpack de/serialization
 
 Events:
@@ -137,11 +163,23 @@ Events:
   |TextYankPost|
 
 Highlight groups:
+  |hl-NormalNC| highlights non-current windows
   |hl-QuickFixLine|
   |hl-Substitute|
   |hl-TermCursor|
   |hl-TermCursorNC|
   |hl-Whitespace| highlights 'listchars' whitespace
+  |expr-highlight| highlight groups (prefixed with "Nvim")
+
+Command-line highlighting:
+  The expression prompt (|@=|, |c_CTRL-R_=|, |i_CTRL-R_=|) is highlighted
+  using a built-in VimL expression parser. |expr-highlight|
+					*E5408* *E5409*
+  |input()|, |inputdialog()| support custom highlighting. |input()-highlight|
+					*g:Nvim_color_cmdline*
+  (Experimental) Command-line (|:|) is colored by callback defined in
+  `g:Nvim_color_cmdline` (this callback is for testing only, and will be
+  removed in the future).
 
 ==============================================================================
 4. Changed features					 *nvim-features-changed*
@@ -156,11 +194,22 @@ 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
 |provider-python|).
 
+Because of general |256-color| usage whereever possible, Nvim will even use
+256-colour capability on Linux virtual terminals.  Vim uses only 8 colours
+plus bright foreground on Linux VTs.
+
+Vim combines what is in its |builtin-terms| with what it reads from termcap,
+and has a |ttybuiltin| setting to control how that combination works.  Nvim
+uses either one or the other of an external |terminfo| entry or the built-in
+one.  It does not attempt to mix data from the two.
+
 |:!| does not support "interactive" commands. Use |:terminal| instead.
 (GUI Vim has a similar limitation, see ":help gui-pty" in Vim.)
 
 |system()| does not support writing/reading "backgrounded" commands. |E5677|
 
+|:redir| nested in |execute()| works.
+
 Nvim may throttle (skip) messages from shell commands (|:!|, |:grep|, |:make|)
 if there is too much output. No data is lost, this only affects display and
 makes things faster. |:terminal| output is never throttled.
@@ -246,19 +295,27 @@ Lua interface (|if_lua.txt|):
 - Lua has direct access to Nvim |API| via `vim.api`.
 - Lua package.path and package.cpath are automatically updated according to
   'runtimepath': |lua-require|.
-- Currently, most legacy Vim features are missing.
 
-|input()| and |inputdialog()| gained support for each other’s features (return 
-on cancel and completion respectively) via dictionary argument (replaces all 
+|input()| and |inputdialog()| support for each other’s features (return on
+cancel and completion respectively) via dictionary argument (replaces all
 other arguments if used).
 
+|input()| and |inputdialog()| support user-defined cmdline highlighting.
+
+Highlight groups:
+  |hl-ColorColumn|, |hl-CursorColumn| are lower priority than most other
+  groups
+
+VimL (Vim script) compatibility:
+  `count` does not alias to |v:count|
+
 ==============================================================================
 5. Missing legacy features				 *nvim-features-missing*
 
 Some legacy Vim features are not implemented:
 
 - |if_py|: vim.bindeval() and vim.Function() are not supported
-- |if_lua|: the `vim` object currently only supports `vim.api`
+- |if_lua|: the `vim` object is missing most legacy methods
 - *if_perl*
 - *if_mzscheme*
 - *if_tcl*
@@ -266,7 +323,7 @@ Some legacy Vim features are not implemented:
 ==============================================================================
 6. Removed features					 *nvim-features-removed*
 
-These features are in Vim, but have been intentionally removed from Nvim.
+These Vim features were intentionally removed from Nvim.
 
 			*'cp'* *'nocompatible'* *'nocp'* *'compatible'*
 Nvim is always "non-compatible" with Vi.
@@ -278,11 +335,33 @@ Ed-compatible mode:
   ":set noedcompatible" is ignored
   ":set edcompatible" is an error
 
-	*t_xx* *:set-termcap* *termcap-options* *t_AB* *t_Sb* *t_vb* *t_SI*
+			*t_xx* *termcap-options* *t_AB* *t_Sb* *t_vb* *t_SI*
 Nvim does not have special `t_XX` options nor <t_XX> keycodes to configure
 terminal capabilities. Instead Nvim treats the terminal as any other UI. For
 example, 'guicursor' sets the terminal cursor style if possible.
 
+			*:set-termcap*
+Start Nvim with 'verbose' level 3 to see the terminal capabilities. >
+	nvim -V3
+<
+			*'term'* *E529* *E530* *E531*
+'term' reflects the terminal type derived from |$TERM| and other environment
+checks.  For debugging only; not reliable during startup. >
+	:echo &term
+"builtin_x" means one of the |builtin-terms| was chosen, because the expected
+terminfo file was not found on the system.
+
+			*termcap*
+Nvim never uses the termcap database, only |terminfo| and |builtin-terms|.
+
+			*xterm-8bit* *xterm-8-bit*
+Xterm can be run in a mode where it uses true 8-bit CSI.  Supporting this
+requires autodetection of whether the terminal is in UTF-8 mode or non-UTF-8
+mode, as the 8-bit CSI character has to be written differently in each case.
+Vim issues a "request version" sequence to the terminal at startup and looks
+at how the terminal is sending CSI.  Nvim does not issue such a sequence and
+always uses 7-bit control sequences.
+
 'ttyfast':
   ":set ttyfast" is ignored
   ":set nottyfast" is an error
@@ -298,7 +377,6 @@ MS-DOS support:
 Test functions:
   test_alloc_fail()
   test_autochdir()
-  test_disable_char_avail()
   test_garbagecollect_now()
   test_null_channel()
   test_null_dict()
@@ -306,16 +384,17 @@ Test functions:
   test_null_list()
   test_null_partial()
   test_null_string()
+  test_override()
   test_settime()
 
 Other options:
   'antialias'
-  'cpoptions' ("g", "w", "H", "*", "-", "j", and all POSIX flags were removed)
+  'cpoptions' (g j k H w < * - and all POSIX flags were removed)
   'encoding' ("utf-8" is always used)
   'esckeys'
   'guioptions' "t" flag was removed
   *'guipty'* (Nvim uses pipes and PTYs consistently on all platforms.)
-  'highlight' (the builtin |highlight-groups| cannot be changed)
+  'highlight' (Names of builtin |highlight-groups| cannot be changed.)
   *'imactivatefunc'* *'imaf'*
   *'imactivatekey'* *'imak'*
   *'imstatusfunc'* *'imsf'*
@@ -324,7 +403,6 @@ Other options:
   'shelltype'
   *'shortname'* *'sn'* *'noshortname'* *'nosn'*
   *'swapsync'* *'sws'*
-  *'term'* *E529* *E530* *E531*
   *'termencoding'* *'tenc'* (Vim 7.4.852 also removed this for Windows)
   'textauto'
   'textmode'