Merge branch 'master' into expression-parser

10 files changed, 99 insertions, 68 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 7c6b8a3c1a..e12cd1cfa9 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -171,8 +171,8 @@ nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special})
                 Parameters:~
                     {str}        String to be converted.
                     {from_part}  Legacy Vim parameter. Usually true.
-                    {do_lt}      Also translate <lt>. Does nothing if
-                                 `special` is false.
+                    {do_lt}      Also translate <lt>. Ignored if `special` is
+                                 false.
                     {special}    Replace |keycodes|, e.g. <CR> becomes a "\n"
                                  char.
 
@@ -309,20 +309,24 @@ nvim_set_option({name}, {value})                           *nvim_set_option()*
                     {value}  New option value
 
 nvim_out_write({str})                                       *nvim_out_write()*
-                Writes a message to vim output buffer
+                Writes a message to the Vim output buffer. Does not append
+                "\n", the message is buffered (won't display) until a linefeed
+                is written.
 
                 Parameters:~
                     {str}  Message
 
 nvim_err_write({str})                                       *nvim_err_write()*
-                Writes a message to vim error buffer
+                Writes a message to the Vim error buffer. Does not append
+                "\n", the message is buffered (won't display) until a linefeed
+                is written.
 
                 Parameters:~
                     {str}  Message
 
 nvim_err_writeln({str})                                   *nvim_err_writeln()*
-                Writes a message to vim error buffer. Appends a linefeed to
-                ensure all contents are written.
+                Writes a message to the Vim error buffer. Appends "\n", so the
+                buffer is flushed (and displayed).
 
                 Parameters:~
                     {str}  Message
diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt
index 9fe815ea9c..8974a5c64e 100644
--- a/runtime/doc/editing.txt
+++ b/runtime/doc/editing.txt
@@ -1271,7 +1271,7 @@ Commands for changing the working directory can be suffixed with a bang "!"
 
 							*:lcd-* 
 :lcd[!] -		Change to the previous current directory (before the
-			previous ":tcd {path}" command).
+			previous ":lcd {path}" command).
 
 							*:pw* *:pwd* *E187*
 :pw[d]			Print the current directory name.
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 29e254b0b3..b37b0e8836 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1522,14 +1522,16 @@ v:errors	Errors found by assert functions, such as |assert_true()|.
 
 					*v:event* *event-variable*
 v:event		Dictionary of event data for the current |autocommand|.  Valid
-		only during the autocommand lifetime: storing or passing
-		`v:event` is invalid.  Copy it instead: >
+		only during the event lifetime; storing or passing v:event is
+		invalid!  Copy it instead: >
 			au TextYankPost * let g:foo = deepcopy(v:event)
 <		Keys vary by event; see the documentation for the specific
-		event, e.g. |TextYankPost|.
+		event, e.g. |DirChanged| or |TextYankPost|.
 			KEY		DESCRIPTION ~
-			operator	The current |operator|.  Also set for
-					Ex commands (unlike |v:operator|). For
+			cwd		Current working directory
+			scope		Event-specific scope name.
+			operator	Current |operator|.  Also set for Ex
+					commands (unlike |v:operator|). For
 					example if |TextYankPost| is triggered
 					by the |:yank| Ex command then
 					`v:event['operator']` is "y".
@@ -4726,7 +4728,8 @@ input({opts})
 		"-complete=" argument.	Refer to |:command-completion| for
 		more information.  Example: >
 			let fname = input("File: ", "", "file")
-<							*E5400* *E5402*
+
+<					*input()-highlight* *E5400* *E5402*
 		The optional `highlight` key allows specifying function which
 		will be used for highlighting user input.  This function
 		receives user input as its only argument and must return
@@ -4744,6 +4747,30 @@ input({opts})
 		sections must be ordered so that next hl_start_col is greater
 		then or equal to previous hl_end_col.
 
+		Example (try some input with parentheses): >
+			highlight RBP1 guibg=Red ctermbg=red
+			highlight RBP2 guibg=Yellow ctermbg=yellow
+			highlight RBP3 guibg=Green ctermbg=green
+			highlight RBP4 guibg=Blue ctermbg=blue
+			let g:rainbow_levels = 4
+			function! RainbowParens(cmdline)
+			  let ret = []
+			  let i = 0
+			  let lvl = 0
+			  while i < len(a:cmdline)
+			    if a:cmdline[i] is# '('
+			      call add(ret, [i, i + 1, 'RBP' . ((lvl % g:rainbow_levels) + 1)])
+			      let lvl += 1
+			    elseif a:cmdline[i] is# ')'
+			      let lvl -= 1
+			      call add(ret, [i, i + 1, 'RBP' . ((lvl % g:rainbow_levels) + 1)])
+			    endif
+			    let i += 1
+			  endwhile
+			  return ret
+			endfunction
+			call input({'prompt':'>','highlight':'RainbowParens'})
+<
 		Highlight function is called at least once for each new
 		displayed input string, before command-line is redrawn.  It is
 		expected that function is pure for the duration of one input()
diff --git a/runtime/doc/message.txt b/runtime/doc/message.txt
index c6c6f49026..58ababf229 100644
--- a/runtime/doc/message.txt
+++ b/runtime/doc/message.txt
@@ -449,12 +449,6 @@ changed.  To avoid the message reset the 'warn' option.
 Something inside Vim went wrong and resulted in a NULL pointer.  If you know
 how to reproduce this problem, please report it. |bugs|
 
-							*E172*  >
-  Only one file name allowed
-
-The ":edit" command only accepts one file name.  When you want to specify
-several files for editing use ":next" |:next|.
-
 						*E41* *E82* *E83* *E342*  >
   Out of memory!
   Out of memory!  (allocating {number} bytes)
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index c6965648ef..d55eb7405c 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -6267,11 +6267,11 @@ A jump table for the options with a short description can be found at |Q_op|.
 	when part of a command has been typed.
 
 						*'title'* *'notitle'*
-'title'			boolean	(default off, on when title can be restored)
+'title'			boolean	(default off)
 			global
 	When on, the title of the window will be set to the value of
 	'titlestring' (if it is not empty), or to:
-		filename [+=-] (path) - VIM
+		filename [+=-] (path) - NVIM
 	Where:
 		filename	the name of the file being edited
 		-		indicates the file cannot be modified, 'ma' off
@@ -6279,7 +6279,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 		=		indicates the file is read-only
 		=+		indicates the file is read-only and modified
 		(path)		is the path of the file being edited
-		- VIM		the server name |v:servername| or "VIM"
+		- NVIM		the server name |v:servername| or "NVIM"
 
 								*'titlelen'*
 'titlelen'		number	(default 85)
@@ -6295,11 +6295,10 @@ A jump table for the options with a short description can be found at |Q_op|.
 	'titlelen' is also used for the 'titlestring' option.
 
 						*'titleold'*
-'titleold'		string	(default "Thanks for flying Vim")
+'titleold'		string	(default "")
 			global
-	This option will be used for the window title when exiting Vim if the
-	original title cannot be restored.  Only happens if 'title' is on or
-	'titlestring' is not empty.
+	If not empty, this option will be used to set the window title when
+	exiting.  Only if 'title' is enabled.
 	This option cannot be set from a |modeline| or in the |sandbox|, for
 	security reasons.
 						*'titlestring'*
@@ -6748,19 +6747,19 @@ A jump table for the options with a short description can be found at |Q_op|.
 						*'winhighlight'* *'winhl'*
 'winhighlight' 'winhl'	string (default empty)
 			local to window
-	Window-local highlights.  Comma-delimited list of |group-name| pairs
-	"{hl-builtin}:{hl-group},..." where each {hl-builtin} is a group (from
-	|highlight-groups|) to be overridden by {hl-group} in the window where
-	this option was set.  Only builting ui highlights are supported, not
-	syntax highlighting.  For that purpose, use |:ownsyntax|.
+	Window-local highlights.  Comma-delimited list of highlight
+	|group-name| pairs "{hl-builtin}:{hl},..." where each {hl-builtin} is
+	a built-in |highlight-groups| item to be overridden by {hl} group in
+	the window.  Only built-in |highlight-groups| are supported, not
+	syntax highlighting (use |:ownsyntax| for that).
 	
-	Most highlights occuring within the frame of a window are supported.
 	Highlights of vertical separators are determined by the window to the
 	left of the separator.  The highlight of a tabpage in |tabline| is
-	determined by the last focused window in the tabpage.  Highlights of
+	determine by the last-focused window of the tabpage.  Highlights of
 	the popupmenu are determined by the current window.  Highlights in the
-	message area are not overridable.  Example for overriding the
-	backgrond color: >
+	message area cannot be overridden.
+
+	Example: show a different color for non-current windows: >
 		set winhighlight=Normal:MyNormal,NormalNC:MyNormalNC
 <
 			*'winfixheight'* *'wfh'* *'nowinfixheight'* *'nowfh'*
diff --git a/runtime/doc/pi_health.txt b/runtime/doc/pi_health.txt
index 8354c0470f..f77267288c 100644
--- a/runtime/doc/pi_health.txt
+++ b/runtime/doc/pi_health.txt
@@ -64,11 +64,11 @@ health#report_info({msg})				*health#report_info*
 health#report_ok({msg})					*health#report_ok*
 	Displays a "success" message.
 
-health#report_warn({msg}, [{suggestions}])		*health#report_warn*
-        Displays a warning. {suggestions} is an optional List of suggestions.
+health#report_warn({msg}, [{advice}])			*health#report_warn*
+        Displays a warning. {advice} is an optional List of suggestions.
 
-health#report_error({msg}, [{suggestions}])		*health#report_error*
-        Displays an error. {suggestions} is an optional List of suggestions.
+health#report_error({msg}, [{advice}])			*health#report_error*
+        Displays an error. {advice} is an optional List of suggestions.
 
 health#{plugin}#check()					*health.user_checker*
         This is the form of a healthcheck definition. Call the above functions
diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index fd17e3b381..73841edb09 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -3270,11 +3270,10 @@ improve screen updating rates (see |:syn-sync| for more on this). >
 The g:vimsyn_embed option allows users to select what, if any, types of
 embedded script highlighting they wish to have. >
 
-   g:vimsyn_embed == 0   : don't embed any scripts
-   g:vimsyn_embed =~ 'P' : support embedded python
+   g:vimsyn_embed == 0      : disable (don't embed any scripts)
+   g:vimsyn_embed == 'lPr'  : support embedded lua, python and ruby
 <
-By default, g:vimsyn_embed is a string supporting interpreters that your vim
-itself supports.
+This option is disabled by default.
 						*g:vimsyn_folding*
 
 Some folding is now supported with syntax/vim.vim: >
diff --git a/runtime/doc/term.txt b/runtime/doc/term.txt
index d99f9b7160..39eb0673c4 100644
--- a/runtime/doc/term.txt
+++ b/runtime/doc/term.txt
@@ -41,16 +41,17 @@ $TERM is also important because it is mirrored by SSH to the remote session,
 unlike other common client-end environment variables ($COLORTERM,
 $XTERM_VERSION, $VTE_VERSION, $KONSOLE_PROFILE_NAME, $TERM_PROGRAM, ...).
 
- For this terminal            Set $TERM to                |builtin-terms|?
-
-  iTerm.app                "iterm" or "iTerm.app"                Y
-  anything libvte based    "vte" or "vte-256color"               Y
-   (e.g. GNOME Terminal)   (aliases: "gnome", "gnome-256color")
-  tmux                     "tmux" or "tmux-256color"             Y
-  screen                   "screen" or "screen-256color"         Y
-  PuTTY                    "putty" or "putty-256color"           Y
-  Terminal.app             "nsterm"                              N
-  Linux virtual terminal   "linux" or "linux-256color"           Y
+  For this terminal           Set $TERM to                  |builtin-terms|
+  -------------------------------------------------------------------------
+  iTerm (original)            iterm, iTerm.app                    N
+  iTerm2 (new capabilities)   iterm2, iTerm2.app                  Y
+  anything libvte-based       vte, vte-256color                   Y
+   (e.g. GNOME Terminal)      (aliases: gnome, gnome-256color)
+  tmux                        tmux, tmux-256color                 Y
+  screen                      screen, screen-256color             Y
+  PuTTY                       putty, putty-256color               Y
+  Terminal.app                nsterm                              N
+  Linux virtual terminal      linux, linux-256color               Y
 
 					*builtin-terms* *builtin_terms*
 If a |terminfo| database is not available, or no entry for the terminal type is
diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index f06c062ee3..223a0135b2 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -212,7 +212,6 @@ g8			Print the hex values of the bytes used in the
 			Equivalent to: >
 			      :enew
 			      :call termopen('{cmd}')
-			      :startinsert
 <
 			See |termopen()|.
 
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 2f031c0b1f..861fa65c3a 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -6,9 +6,8 @@
 
 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.
 
@@ -72,12 +71,18 @@ Clipboard integration		|provider-clipboard|
 
 USER EXPERIENCE  ~
 
-Working intuitively and consistently is a major goal of Nvim. Examples:
+Working intuitively and consistently is a major goal of Nvim.
 
-- 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.
+							*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 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).
 
 - Vim's internal test functions (test_autochdir(), test_settime(), etc.) are
   not exposed (nor implemented); instead Nvim has a robust API.
@@ -268,13 +273,16 @@ 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()| now support user-defined cmdline highlighting.
+|input()| and |inputdialog()| support user-defined cmdline highlighting.
+
+Highlight groups:
+  |hl-ColorColumn|, |hl-CursorColumn|, |hl-CursorLine| are lower priority than
+  (overridden by) most other highlight groups.
 
 ==============================================================================
 5. Missing legacy features				 *nvim-features-missing*
@@ -282,7 +290,7 @@ other arguments if used).
 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*
@@ -290,7 +298,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.