Merge branch 'master' into lazier-arg_errmsg-gettext

13 files changed, 219 insertions, 157 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 2bcc996d8b..a118690876 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -9,8 +9,7 @@ Nvim API							   *API* *api*
 Nvim exposes a powerful API that can be used by plugins and external processes
 via |msgpack-rpc|, Lua and VimL (|eval-api|).
 
-Nvim can also be embedded in C applications as libnvim, so the application
-can control the embedded instance by calling the C API directly.
+Applications can also embed libnvim to work with the C API directly.
 
 ==============================================================================
 API Types							   *api-types*
@@ -55,6 +54,28 @@ error_types		Possible error types returned by API functions
 External programs ("clients") can use the metadata to discover the |rpc-api|.
 
 ==============================================================================
+API contract                                                     *api-contract*
+
+The API is made of functions and events. Clients call functions like those
+described at |api-global|, and may "attach" in order to receive rich events,
+described at |rpc-remote-ui|.
+
+As Nvim develops, its API may change only according the following "contract":
+
+- New functions and events may be added.
+  - Any such extensions are OPTIONAL: old clients may ignore them.
+- Function signatures will NOT CHANGE (after release).
+  - Functions introduced in the development (unreleased) version MAY CHANGE.
+    (Clients can dynamically check `api_prerelease`, etc. |api-metadata|)
+- Event parameters will not be removed or reordered (after release).
+- Events may be EXTENDED: new parameters may be added.
+- New items may be ADDED to map/list parameters/results of functions and
+  events.
+  - Any such new items are OPTIONAL: old clients may ignore them.
+  - Existing items will not be removed (after release).
+- Deprecated functions will not be removed until Nvim version 2.0
+
+==============================================================================
 Buffer highlighting					       *api-highlights*
 
 Nvim allows plugins to add position-based highlights to buffers. This is
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 76ccc42546..0e909aac65 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -6,22 +6,20 @@
 
 Development of Nvim.					*development*
 
-1. Design goals		|design-goals|
-2. Design decisions	|design-decisions|
+1. Design goals		        |design-goals|
+2. Developer guidelines	        |dev-help|
 
 Nvim is open source software.  Everybody is encouraged to contribute.
     https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md
 
-See src/nvim/README.md for a high-level overview of the source code:
-    https://github.com/neovim/neovim/blob/master/src/nvim/README.md
+See src/nvim/README.md for an overview of the source code.
 
 ==============================================================================
-1. Design goals						*design-goals*
+Design goals						*design-goals*
 
 Most important things come first (roughly).
 
-Note that quite a few items are contradicting.  This is intentional.  A
-balance must be found between them.
+Note that some items conflict; this is intentional.  A balance must be found.
 
 
 NVIM IS... IMPROVED					*design-improved*
@@ -41,7 +39,7 @@ completely different editor.  Extensions are done with a "Vi spirit".
 - There are many first-time and inexperienced Vim users.  Make it easy for
   them to start using Vim and learn more over time.
 - There is no limit to the features that can be added.  Selecting new features
-  is one based on (1) what users ask for, (2) how much effort it takes to
+  is based on (1) what users ask for, (2) how much effort it takes to
   implement and (3) someone actually implementing it.
 
 
@@ -56,20 +54,14 @@ Vim tries to help as many users on as many platforms as possible.
 - Support many compilers and libraries.  Not everybody is able or allowed to
   install another compiler or GUI library.
 - People switch from one platform to another, and from GUI to terminal
-  version.  Features should be present in all versions, or at least in as many
-  as possible with a reasonable effort.  Try to avoid that users must switch
-  between platforms to accomplish their work efficiently.
-- That a feature is not possible on some platforms, or only possible on one
-  platform, does not mean it cannot be implemented.  [This intentionally
-  contradicts the previous item, these two must be balanced.]
+  version.  Features should be present in all versions.
 
 
 NVIM IS... WELL DOCUMENTED				*design-documented*
 
 - A feature that isn't documented is a useless feature.  A patch for a new
   feature must include the documentation.
-- Documentation should be comprehensive and understandable.  Using examples is
-  recommended.
+- Documentation should be comprehensive and understandable.  Use examples.
 - Don't make the text unnecessarily long.  Less documentation means that an
   item is easier to find.
 - Do not prefix doc-tags with "nvim-". Use |vim_diff.txt| to document
@@ -77,12 +69,12 @@ NVIM IS... WELL DOCUMENTED				*design-documented*
   to mark a specific feature. No other distinction is necessary.
 - If a feature is removed, delete its doc entry and move its tag to
   |vim_diff.txt|.
+- Move deprecated features to |deprecated.txt|.
 
 
 NVIM IS... HIGH SPEED AND SMALL IN SIZE			*design-speed-size*
 
-Using Vim must not be a big attack on system resources.  Keep it small and
-fast.
+Keep Nvim small and fast.
 - Computers are becoming faster and bigger each year.  Vim can grow too, but
   no faster than computers are growing.  Keep Vim usable on older systems.
 - Many users start Vim from a shell very often.  Startup time must be short.
@@ -118,13 +110,14 @@ NVIM IS... NOT						*design-not*
 
 Nvim is not an operating system; instead it should be composed with other
 tools or hosted as a component. Marvim once said: "Unlike Emacs, Nvim does not
-include the kitchen sink... but you can use it for plumbing."
+include the kitchen sink... but it's good for plumbing."
 
 
 ==============================================================================
-2. Design decisions					*design-decisions*
+Developer guidelines				        *dev-help*
 
-JARGON	 							*dev-jargon*
+
+JARGON	 						*dev-jargon*
 
 API client ~
 All external UIs and remote plugins (as opposed to regular Vim plugins) are
@@ -150,15 +143,14 @@ the xterm window, a window inside Vim to view a buffer.
 To avoid confusion, other items that are sometimes called window have been
 given another name.  Here is an overview of the related items:
 
-screen		The whole display.  For the GUI it's something like 1024x768
-		pixels.  The Vim shell can use the whole screen or part of it.
+screen		The whole display.
 shell		The Vim application.  This can cover the whole screen (e.g.,
 		when running in a console) or part of it (xterm or GUI).
 window		View on a buffer.  There can be several windows in Vim,
 		together with the command line, menubar, toolbar, etc. they
 		fit in the shell.
 
-PROVIDERS 							*dev-provider*
+PROVIDERS 						*dev-provider*
 
 A goal of Nvim is to allow extension of the editor without special knowledge
 in the core. But some Vim components are too tightly coupled; in those cases
@@ -202,7 +194,7 @@ Python host isn't installed then the plugin will "think" it is running in
 a Vim compiled without the |+python| feature.
 
 
-API								*dev-api*
+API							*dev-api*
 
 Use this pattern to name new API functions:
     nvim_{thing}_{action}_{arbitrary-qualifiers}
@@ -233,4 +225,23 @@ _not_ a Buffer). The common {action} "list" indicates that it lists all
 bufs (plural) in the global context.
 
 
+EXTERNAL UI 						*dev-ui*
+
+External UIs should be aware of the |api-contract|. In particular, future
+versions of Nvim may add optional, new items to existing events. The API is
+strongly backwards-compatible, but clients must not break if new fields are
+added to existing events.
+
+External UIs are expected to implement some common features.
+
+- Users may want to configure UI-specific options. The UI should publish the
+  |GUIEnter| autocmd after attaching to Nvim: >
+    doautocmd GUIEnter
+- Options can be monitored for changes by the |OptionSet| autocmd. E.g. if the
+  user sets the 'guifont' option, this autocmd notifies channel 42: >
+    autocmd OptionSet guifont call rpcnotify(42, 'option-changed', 'guifont', &guifont)
+- cursor-shape change: 'guicursor' properties are sent in the mode_info_set UI
+  event.
+
+
  vim:tw=78:ts=8:ft=help:norl:
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 77db2699f8..107dd28ecd 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -38,7 +38,7 @@ done, the features in this document are not available.	See |+eval| and
 There are six types of variables:
 
 Number		A 32 or 64 bit signed number.  |expr-number| *Number*
-		Examples:  -123  0x10  0177
+		Examples:  -123  0x10  0177  0b1011
 
 Float		A floating point number. |floating-point-format| *Float*
 		Examples: 123.456  1.15e-6  -1.1e3
@@ -1022,9 +1022,10 @@ When expr8 is a |Funcref| type variable, invoke the function it refers to.
 number
 ------
 number			number constant			*expr-number* 
-						*hex-number* *octal-number*
+				*hex-number* *octal-number* *binary-number*
 
-Decimal, Hexadecimal (starting with 0x or 0X), or Octal (starting with 0).
+Decimal, Hexadecimal (starting with 0x or 0X), Binary (starting with 0b or 0B)
+and Octal (starting with 0).
 
 						*floating-point-format*
 Floating point numbers can be written in two forms:
@@ -1214,7 +1215,7 @@ The arguments are optional.  Example: >
 							*closure*
 Lambda expressions can access outer scope variables and arguments.  This is
 often called a closure.  Example where "i" a and "a:arg" are used in a lambda
-while they exists in the function scope.  They remain valid even after the
+while they exist in the function scope.  They remain valid even after the
 function returns: >
 	:function Foo(arg)
 	:  let i = 3
@@ -1425,8 +1426,8 @@ v:beval_winnr	The number of the window, over which the mouse pointer is. Only
 		window gets a number).
 
 					*v:beval_winid* *beval_winid-variable*
-v:beval_winid	The window ID of the window, over which the mouse pointer is.
-		Otherwise like v:beval_winnr.
+v:beval_winid	The |window-ID| of the window, over which the mouse pointer
+		is.  Otherwise like v:beval_winnr.
 
 					*v:char* *char-variable*
 v:char		Argument for evaluating 'formatexpr' and used for the typed
@@ -1686,7 +1687,7 @@ v:mouse_win	Window number for a mouse click obtained with |getchar()|.
 		zero when there was no mouse button click.
 
 					*v:mouse_winid* *mouse_winid-variable*
-v:mouse_winid	Window ID for a mouse click obtained with |getchar()|.
+v:mouse_winid	|window-ID| for a mouse click obtained with |getchar()|.
 		The value is zero when there was no mouse button click.
 
 					*v:mouse_lnum* *mouse_lnum-variable*
@@ -1922,9 +1923,10 @@ v:vim_did_enter	Zero until most of startup is done.  It is set to one just
 v:warningmsg	Last given warning message.  It's allowed to set this variable.
 
 					*v:windowid* *windowid-variable*
-v:windowid	Application-specific window ID ("window handle" in MS-Windows)
-		which may be set by any attached UI. Defaults to zero.
-		Note: for windows inside Vim use |winnr()| or |win_getid()|.
+v:windowid	Application-specific window "handle" which may be set by any
+		attached UI. Defaults to zero.
+		Note: For Nvim |windows| use |winnr()| or |win_getid()|, see
+		|window-ID|.
 
 ==============================================================================
 4. Builtin Functions					*functions*
@@ -1952,7 +1954,7 @@ assert_exception( {error} [, {msg}]) none  assert {error} is in v:exception
 assert_fails( {cmd} [, {error}])     none  assert {cmd} fails
 assert_false({actual} [, {msg}])     none  assert {actual} is false
 assert_inrange({lower}, {upper}, {actual} [, {msg}])
-				none  	assert {actual} is inside the range
+				none	assert {actual} is inside the range
 assert_match( {pat}, {text} [, {msg}]) none  assert {pat} matches {text}
 assert_notequal( {exp}, {act} [, {msg}]) none  assert {exp} is not equal {act}
 assert_notmatch( {pat}, {text} [, {msg}]) none  assert {pat} not matches {text}
@@ -1968,7 +1970,7 @@ buflisted({expr})		Number	|TRUE| if buffer {expr} is listed
 bufloaded({expr})		Number	|TRUE| if buffer {expr} is loaded
 bufname({expr})		String	Name of the buffer {expr}
 bufnr({expr} [, {create}])	Number	Number of the buffer {expr}
-bufwinid({expr})		Number	window ID of buffer {expr}
+bufwinid({expr})		Number	|window-ID| of buffer {expr}
 bufwinnr({expr})		Number	window number of buffer {expr}
 byte2line({byte})		Number	line number at byte count {byte}
 byteidx({expr}, {nr})		Number	byte index of {nr}'th char in {expr}
@@ -1991,7 +1993,7 @@ cos({expr})			Float	cosine of {expr}
 cosh({expr})			Float	hyperbolic cosine of {expr}
 count({list}, {expr} [, {ic} [, {start}]])
 				Number	 count how many {expr} are in {list}
-cscope_connection([{num} , {dbpath} [, {prepend}]])
+cscope_connection([{num}, {dbpath} [, {prepend}]])
 				Number	checks existence of cscope connection
 cursor({lnum}, {col} [, {off}])
 				Number	move cursor to {lnum}, {col}, {off}
@@ -2302,9 +2304,12 @@ tan({expr})			Float	tangent of {expr}
 tanh({expr})			Float	hyperbolic tangent of {expr}
 tempname()			String	name for a temporary file
 test_garbagecollect_now()	none	free memory right now for testing
+timer_info([{id}])		List	information about timers
+timer_pause({id}, {pause})	none	pause or unpause a timer
 timer_start({time}, {callback} [, {options}])
 				Number	create a timer
 timer_stop({timer})		none	stop a timer
+timer_stopall()			none	stop all timers
 tolower({expr})			String	the String {expr} switched to lowercase
 toupper({expr})			String	the String {expr} switched to uppercase
 tr({src}, {fromstr}, {tostr})	String	translate chars of {src} in {fromstr}
@@ -2320,10 +2325,10 @@ virtcol({expr})			Number	screen column of cursor or mark
 visualmode([expr])		String	last visual mode used
 wildmenumode()			Number	whether 'wildmenu' mode is active
 win_findbuf({bufnr})		List	find windows containing {bufnr}
-win_getid([{win} [, {tab}]])	Number	get window ID for {win} in {tab}
-win_gotoid({expr})		Number	go to window with ID {expr}
-win_id2tabwin({expr})		List	get tab and window nr from window ID
-win_id2win({expr})		Number	get window nr from window ID
+win_getid([{win} [, {tab}]])	Number	get |window-ID| for {win} in {tab}
+win_gotoid({expr})		Number	go to |window-ID| {expr}
+win_id2tabwin({expr})		List	get tab and window nr from |window-ID|
+win_id2win({expr})		Number	get window nr from |window-ID|
 winbufnr({nr})			Number	buffer number of window {nr}
 wincol()			Number	window column of the cursor
 winheight({nr})			Number	height of window {nr}
@@ -2414,7 +2419,7 @@ arglistid([{winnr} [, {tabnr}]])
 		With {winnr} only use this window in the current tab page.
 		With {winnr} and {tabnr} use the window in the specified tab
 		page.
-		{winnr} can be the window number or the window ID.
+		{winnr} can be the window number or the |window-ID|.
 
 							*argv()*
 argv([{nr}])	The result is the {nr}th file in the argument list of the
@@ -2649,7 +2654,7 @@ bufnr({expr} [, {create}])
 		them.  Use bufexists() to test for the existence of a buffer.
 
 bufwinid({expr})					*bufwinid()*
-		The result is a Number, which is the window ID of the first
+		The result is a Number, which is the |window-ID| of the first
 		window associated with buffer {expr}.  For the use of {expr},
 		see |bufname()| above.  If buffer {expr} doesn't exist or
 		there is no such window, -1 is returned.  Example: >
@@ -3203,8 +3208,12 @@ exepath({expr})						*exepath()*
 
 							*exists()*
 exists({expr})	The result is a Number, which is |TRUE| if {expr} is
-		defined, zero otherwise.  The {expr} argument is a string,
-		which contains one of these:
+		defined, zero otherwise.
+
+		For checking for a supported feature use |has()|.
+		For checking if a file exists use |filereadable()|.
+
+		The {expr} argument is a string, which contains one of these:
 			&option-name	Vim option (only checks if it exists,
 					not if it really works)
 			+option-name	Vim option that works.
@@ -3252,7 +3261,6 @@ exists({expr})	The result is a Number, which is |TRUE| if {expr} is
 					event and pattern.
 			##event		autocommand for this event is
 					supported.
-		For checking for a supported feature use |has()|.
 
 		Examples: >
 			exists("&mouse")
@@ -4065,7 +4073,7 @@ getcwd([{winnr}[, {tabnr}]])				*getcwd()*
 			getcwd(0)
 			getcwd(0, 0)
 <		If {winnr} is -1 it is ignored, only the tab is resolved.
-		{winnr} can be the window number or the window ID.
+		{winnr} can be the window number or the |window-ID|.
 
 
 getfsize({fname})					*getfsize()*
@@ -4160,7 +4168,7 @@ getline({lnum} [, {end}])
 
 getloclist({nr},[, {what}])				*getloclist()*
 		Returns a list with all the entries in the location list for
-		window {nr}. {nr} can be the window number or the window ID.
+		window {nr}.  {nr} can be the window number or the |window-ID|.
 		When {nr} is zero the current window is used.
 
 		For a location list window, the displayed location list is
@@ -4235,7 +4243,7 @@ getqflist([{what}])					*getqflist()*
 			type	type of the error, 'E', '1', etc.
 			valid	|TRUE|: recognized error message
 
-		When there is no error list or it's empty an empty list is
+		When there is no error list or it's empty, an empty list is
 		returned. Quickfix list entries with non-existing buffer
 		number are returned with "bufnr" set to zero.
 
@@ -4250,8 +4258,8 @@ getqflist([{what}])					*getqflist()*
 		returns only the items listed in {what} as a dictionary. The
 		following string items are supported in {what}:
 			nr	get information for this quickfix list
-			title	get list title
-			winid	get window id (if opened)
+			title	get the list title
+			winid	get the |window-ID| (if opened)
 			all	all of the above quickfix properties
 		Non-string items in {what} are ignored.
 		If "nr" is not present then the current quickfix list is used.
@@ -4261,7 +4269,7 @@ getqflist([{what}])					*getqflist()*
 		The returned dictionary contains the following entries:
 			nr	quickfix list number
 			title	quickfix list title text
-			winid	quickfix window id (if opened)
+			winid	quickfix |window-ID| (if opened)
 
 		Examples: >
 			:echo getqflist({'all': 1})
@@ -4272,7 +4280,7 @@ getreg([{regname} [, 1 [, {list}]]])			*getreg()*
 		The result is a String, which is the contents of register
 		{regname}.  Example: >
 			:let cliptext = getreg('*')
-<		When {regname} was not set the result is a empty string.
+<		When {regname} was not set the result is an empty string.
 
 		getreg('=') returns the last evaluated value of the expression
 		register.  (For use in maps.)
@@ -4308,10 +4316,10 @@ gettabinfo([{arg}])					*gettabinfo()*
 		empty List is returned.
 
 		Each List item is a Dictionary with the following entries:
-			nr		tab page number.
+			tabnr		tab page number.
 			variables	a reference to the dictionary with
 					tabpage-local variables
-			windows		List of window IDs in the tag page.
+			windows		List of |window-ID|s in the tag page.
 
 gettabvar({tabnr}, {varname} [, {def}])				*gettabvar()*
 		Get the value of a tab-local variable {varname} in tab page
@@ -4335,7 +4343,7 @@ gettabwinvar({tabnr}, {winnr}, {varname} [, {def}])		*gettabwinvar()*
 		Note that {varname} must be the name without "w:".
 		Tabs are numbered starting with one.  For the current tabpage
 		use |getwinvar()|.
-		{winnr} can be the window number or the window ID.
+		{winnr} can be the window number or the |window-ID|.
 		When {winnr} is zero the current window is used.
 		This also works for a global option, buffer-local option and
 		window-local option, but it doesn't work for a global variable
@@ -4363,20 +4371,20 @@ getwininfo([{winid}])					*getwininfo()*
 		is returned.  If the window does not exist the result is an
 		empty list.
 
-		Without an information about all the windows in all the tab
-		pages is returned.
+		Without {winid} information about all the windows in all the
+		tab pages is returned.
 
 		Each List item is a Dictionary with the following entries:
-			bufnum		number of buffer in the window
+			bufnr		number of buffer in the window
 			height		window height
 			loclist		1 if showing a location list
-			nr		window number
 			quickfix	1 if quickfix or location list window
-			tpnr		tab page number
+			tabnr		tab page number
 			variables	a reference to the dictionary with
 					window-local variables
 			width		window width
-			winid		window ID
+			winid		|window-ID|
+			winnr		window number
 
 		To obtain all window-local variables use: >
 			gettabwinvar({tabnr}, {winnr}, '&')
@@ -4480,9 +4488,8 @@ has_key({dict}, {key})					*has_key()*
 		an entry with key {key}.  Zero otherwise.
 
 haslocaldir([{winnr}[, {tabnr}]])			*haslocaldir()*
-		The result is a Number, which is 1 when the specified tabpage
-		or window has a local path set via |:lcd| or |:tcd|, and
-		0 otherwise.
+		The result is a Number, which is 1 when the tabpage or window
+		has set a local path via |:tcd| or |:lcd|, otherwise 0.
 
 		Tabs and windows are identified by their respective numbers,
 		0 means current tab or window. Missing argument implies 0.
@@ -4490,7 +4497,9 @@ haslocaldir([{winnr}[, {tabnr}]])			*haslocaldir()*
 			haslocaldir()
 			haslocaldir(0)
 			haslocaldir(0, 0)
-<		{winnr} can be the window number or the window ID.
+<		With {winnr} use that window in the current tabpage.
+		With {winnr} and {tabnr} use the window in that tabpage.
+		{winnr} can be the window number or the |window-ID|.
 		If {winnr} is -1 it is ignored, only the tab is resolved.
 
 hasmapto({what} [, {mode} [, {abbr}]])			*hasmapto()*
@@ -5337,7 +5346,8 @@ matchadd({group}, {pattern}[, {priority}[, {id} [, {dict}]]])
 		available from |getmatches()|.	All matches can be deleted in
 		one operation by |clearmatches()|.
 
-matchaddpos({group}, {pos}[, {priority}[, {id}[, {dict}]]])		*matchaddpos()*
+							*matchaddpos()*
+matchaddpos({group}, {pos}[, {priority}[, {id}[, {dict}]]])
 		Same as |matchadd()|, but requires a list of positions {pos}
 		instead of a pattern. This command is faster than |matchadd()|
 		because it does not require to handle regular expressions and
@@ -5807,6 +5817,9 @@ printf({fmt}, {expr1} ...)				*printf()*
 		s	The text of the String argument is used.  If a
 			precision is specified, no more bytes than the number
 			specified are used.
+			If the argument is not a String type, it is
+			automatically converted to text with the same format
+			as ":echo".
 							*printf-S*
 		S	The text of the String argument is used.  If a
 			precision is specified, no more display cells than the
@@ -6530,7 +6543,7 @@ setline({lnum}, {text})					*setline()*
 
 setloclist({nr}, {list} [, {action}[, {what}]])		*setloclist()*
 		Create or replace or add to the location list for window {nr}.
-		{nr} can be the window number or the window ID.
+		{nr} can be the window number or the |window-ID|.
 		When {nr} is zero the current window is used.
 
 		For a location list window, the displayed location list is
@@ -6722,7 +6735,7 @@ settabwinvar({tabnr}, {winnr}, {varname}, {val})	*settabwinvar()*
 		{val}.
 		Tabs are numbered starting with one.  For the current tabpage
 		use |setwinvar()|.
-		{winnr} can be the window number or the window ID.
+		{winnr} can be the window number or the |window-ID|.
 		When {winnr} is zero the current window is used.
 		This also works for a global or local buffer option, but it
 		doesn't work for a global or local buffer variable.
@@ -7173,7 +7186,7 @@ strwidth({expr})					*strwidth()*
 		Ambiguous, this function's return value depends on 'ambiwidth'.
 		Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
 
-submatch({nr}[, {list}])				*submatch()*
+submatch({nr}[, {list}])			*submatch()* *E935*
 		Only for an expression in a |:substitute| command or
 		substitute() function.
 		Returns the {nr}'th submatch of the matched text.  When {nr}
@@ -7397,7 +7410,7 @@ systemlist({cmd} [, {input} [, {keepempty}]])		*systemlist()*
 tabpagebuflist([{arg}])					*tabpagebuflist()*
 		The result is a |List|, where each item is the number of the
 		buffer associated with each window in the current tab page.
-		{arg} specifies the number of tab page to be used.  When
+		{arg} specifies the number of the tab page to be used. When
 		omitted the current tab page is used.
 		When {arg} is invalid the number zero is returned.
 		To get a list of all buffers in all tabs use this: >
@@ -7528,7 +7541,36 @@ tanh({expr})						*tanh()*
 <			-0.761594
 
 
-							*timer_start()*
+							*timer_info()*
+timer_info([{id}])
+		Return a list with information about timers.
+		When {id} is given only information about this timer is
+		returned.  When timer {id} does not exist an empty list is
+		returned.
+		When {id} is omitted information about all timers is returned.
+
+		For each timer the information is stored in a Dictionary with
+		these items:
+		    "id"	    the timer ID
+		    "time"	    time the timer was started with
+		    "repeat"	    number of times the timer will still fire;
+				    -1 means forever
+		    "callback"	    the callback
+
+timer_pause({timer}, {paused})				*timer_pause()*
+		Pause or unpause a timer.  A paused timer does not invoke its
+		callback when its time expires.  Unpausing a timer may cause
+		the callback to be invoked almost immediately if enough time
+		has passed.
+
+		Pausing a timer is useful to avoid the callback to be called
+		for a short time.
+
+		If {paused} evaluates to a non-zero Number or a non-empty
+		String, then the timer is paused, otherwise it is unpaused.
+		See |non-zero-arg|.
+
+						*timer_start()* *timer* *timers*
 timer_start({time}, {callback} [, {options}])
 		Create a timer and return the timer ID.
 
@@ -7557,7 +7599,12 @@ timer_start({time}, {callback} [, {options}])
 timer_stop({timer})					*timer_stop()*
 		Stop a timer.  The timer callback will no longer be invoked.
 		{timer} is an ID returned by timer_start(), thus it must be a
-		Number.
+		Number.  If {timer} does not exist there is no error.
+
+timer_stopall()						*timer_stopall()*
+		Stop all timers.  The timer callbacks will no longer be
+		invoked.  Useful if some timers is misbehaving.  If there are
+		no timers there is no error.
 
 tolower({expr})						*tolower()*
 		The result is a copy of the String given, with all uppercase
@@ -7759,11 +7806,11 @@ wildmenumode()					*wildmenumode()*
 
 
 win_findbuf({bufnr})					*win_findbuf()*
-		Returns a list with window IDs for windows that contain buffer
-		{bufnr}.  When there is none the list is empty.
+		Returns a list with |window-ID|s for windows that contain
+		buffer {bufnr}.  When there is none the list is empty.
 
 win_getid([{win} [, {tab}]])				*win_getid()*
-		Get the window ID for the specified window.
+		Get the |window-ID| for the specified window.
 		When {win} is missing use the current window.
 		With {win} this is the window number.  The top window has
 		number 1.
@@ -7788,7 +7835,7 @@ win_id2win({expr})					*win_id2win()*
 							*winbufnr()*
 winbufnr({nr})	The result is a Number, which is the number of the buffer
 		associated with window {nr}.  {nr} can be the window number or
-		the window ID.
+		the |window-ID|.
 		When {nr} is zero, the number of the buffer in the current
 		window is returned.
 		When window {nr} doesn't exist, -1 is returned.
@@ -7802,7 +7849,7 @@ wincol()	The result is a Number, which is the virtual column of the
 
 winheight({nr})						*winheight()*
 		The result is a Number, which is the height of window {nr}.
-		{nr} can be the window number or the window ID.
+		{nr} can be the window number or the |window-ID|.
 		When {nr} is zero, the height of the current window is
 		returned.  When window {nr} doesn't exist, -1 is returned.
 		An existing window always has a height of zero or more.
@@ -7882,7 +7929,7 @@ winsaveview()	Returns a |Dictionary| that contains information to restore
 
 winwidth({nr})						*winwidth()*
 		The result is a Number, which is the width of window {nr}.
-		{nr} can be the window number or the window ID.
+		{nr} can be the window number or the |window-ID|.
 		When {nr} is zero, the width of the current window is
 		returned.  When window {nr} doesn't exist, -1 is returned.
 		An existing window always has a width of zero or more.
diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt
index bab15bcbb6..0dc8fff975 100644
--- a/runtime/doc/index.txt
+++ b/runtime/doc/index.txt
@@ -1202,7 +1202,7 @@ tag	      command	      action ~
 |:display|	:di[splay]	display registers
 |:djump|	:dj[ump]	jump to #define
 |:dl|		:dl		short for |:delete| with the 'l' flag
-|:dl|		:del[ete]l	short for |:delete| with the 'l' flag
+|:del|		:del[ete]l	short for |:delete| with the 'l' flag
 |:dlist|	:dli[st]	list #defines
 |:doautocmd|	:do[autocmd]	apply autocommands to current buffer
 |:doautoall|	:doautoa[ll]	apply autocommands for all loaded buffers
@@ -1234,6 +1234,7 @@ tag	      command	      action ~
 |:file|		:f[ile]		show or set the current file name
 |:files|	:files		list all files in the buffer list
 |:filetype|	:filet[ype]	switch file type detection on/off
+|:filter|	:filt[er]	filter output of following command
 |:find|		:fin[d]		find file in 'path' and edit it
 |:finally|	:fina[lly]	part of a :try command
 |:finish|	:fini[sh]	quit sourcing a Vim script
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
index db349eca71..3ba1ce1f17 100644
--- a/runtime/doc/map.txt
+++ b/runtime/doc/map.txt
@@ -720,9 +720,6 @@ special key: >
 Don't type a real <Esc>, Vim will recognize the key code and replace it with
 <F1> anyway.
 
-Another problem may be that when keeping ALT or Meta pressed the terminal
-prepends ESC instead of setting the 8th bit.  See |:map-alt-keys|.
-
 						*recursive_mapping*
 If you include the {lhs} in the {rhs} you have a recursive mapping.  When
 {lhs} is typed, it will be replaced with {rhs}.  When the {lhs} which is
@@ -762,46 +759,14 @@ in the original Vi, you would get back the text before the first undo).
 
 1.10 MAPPING ALT-KEYS					*:map-alt-keys*
 
-In the GUI Vim handles the Alt key itself, thus mapping keys with ALT should
-always work.  But in a terminal Vim gets a sequence of bytes and has to figure
-out whether ALT was pressed or not.
-
-By default Vim assumes that pressing the ALT key sets the 8th bit of a typed
-character.  Most decent terminals can work that way, such as xterm, aterm and
-rxvt.  If your <A-k> mappings don't work it might be that the terminal is
-prefixing the character with an ESC character.  But you can just as well type
-ESC before a character, thus Vim doesn't know what happened (except for
-checking the delay between characters, which is not reliable).
-
-As of this writing, some mainstream terminals like gnome-terminal and konsole
-use the ESC prefix.  There doesn't appear a way to have them use the 8th bit
-instead.  Xterm should work well by default.  Aterm and rxvt should work well
-when started with the "--meta8" argument.  You can also tweak resources like
-"metaSendsEscape", "eightBitInput" and "eightBitOutput".
-
-On the Linux console, this behavior can be toggled with the "setmetamode"
-command.  Bear in mind that not using an ESC prefix could get you in trouble
-with other programs.  You should make sure that bash has the "convert-meta"
-option set to "on" in order for your Meta keybindings to still work on it
-(it's the default readline behavior, unless changed by specific system
-configuration).  For that, you can add the line: >
-
-	set convert-meta on
-
-to your ~/.inputrc file. If you're creating the file, you might want to use: >
-
-	$include /etc/inputrc
-
-as the first line, if that file exists on your system, to keep global options.
-This may cause a problem for entering special characters, such as the umlaut.
-Then you should use CTRL-V before that character.
-
-Bear in mind that convert-meta has been reported to have troubles when used in
-UTF-8 locales.  On terminals like xterm, the "metaSendsEscape" resource can be
-toggled on the fly through the "Main Options" menu, by pressing Ctrl-LeftClick
-on the terminal; that's a good last resource in case you want to send ESC when
-using other applications but not when inside VIM.
-
+In the GUI Nvim handles the |ALT| key itself, thus mapping keys with ALT
+should always work.  But in a terminal Nvim gets a sequence of bytes and has
+to figure out whether ALT was pressed.  Terminals may use ESC to indicate that
+ALT was pressed.  If ESC is followed by a {key} within 'ttimeoutlen'
+milliseconds, the ESC is interpreted as:
+        <ALT-{key}>
+otherwise it is interpreted as two key presses:
+        <ESC> {key}
 
 1.11 MAPPING AN OPERATOR				*:map-operator*
 
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 9be7dae84d..6b96271c4a 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -3499,7 +3499,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	if you want to use Vim as a modeless editor.
 	These Insert mode commands will be useful:
 	- Use the cursor keys to move around.
-	- Use CTRL-O to execute one Normal mode command |i_CTRL-O|).  When
+	- Use CTRL-O to execute one Normal mode command |i_CTRL-O|.  When
 	  this is a mapping, it is executed as if 'insertmode' was off.
 	  Normal mode remains active until the mapping is finished.
 	- Use CTRL-L to execute a number of Normal mode commands, then use
@@ -3689,6 +3689,8 @@ A jump table for the options with a short description can be found at |Q_op|.
 	be able to execute Normal mode commands.
 	This is the opposite of the 'keymap' option, where characters are
 	mapped in Insert mode.
+	Also consider resetting 'langremap' to avoid 'langmap' applies to
+	characters resulting from a mapping.
 	This option cannot be set from a |modeline| or in the |sandbox|, for
 	security reasons.
 
@@ -5025,6 +5027,8 @@ A jump table for the options with a short description can be found at |Q_op|.
 	"inclusive" means that the last character of the selection is included
 	in an operation.  For example, when "x" is used to delete the
 	selection.
+	When "old" is used and 'virtualedit' allows the cursor to move past
+	the end of line the line break still isn't included.
 	Note that when "exclusive" is used and selecting from the end
 	backwards, you cannot include the last character of a line, when
 	starting in Normal mode and 'virtualedit' empty.
diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt
index a918a4d34a..420f570c99 100644
--- a/runtime/doc/quickref.txt
+++ b/runtime/doc/quickref.txt
@@ -751,7 +751,7 @@ Short explanation of each option:		*option-list*
 'keywordprg'	  'kp'	    program to use for the "K" command
 'langmap'	  'lmap'    alphabetic characters for other language mode
 'langmenu'	  'lm'	    language to be used for the menus
-'langnoremap'	  'lnr'	    do not apply 'langmap' to mapped characters
+'langremap'	  'lrm'	    do apply 'langmap' to mapped characters
 'laststatus'	  'ls'	    tells when last window has status lines
 'lazyredraw'	  'lz'	    don't redraw while executing macros
 'linebreak'	  'lbr'     wrap long lines at a blank
diff --git a/runtime/doc/sign.txt b/runtime/doc/sign.txt
index e5a6b0be39..466a030e0c 100644
--- a/runtime/doc/sign.txt
+++ b/runtime/doc/sign.txt
@@ -188,7 +188,9 @@ JUMPING TO A SIGN					*:sign-jump* *E157*
 		If the file isn't displayed in window and the current file can
 		not be |abandon|ed this fails.
 
-:sign jump {id} buffer={nr}
-		Same, but use buffer {nr}.
+:sign jump {id} buffer={nr}					*E934*
+		Same, but use buffer {nr}.  This fails if buffer {nr} does not
+		have a name.
+
 
  vim:tw=78:ts=8:ft=help:norl:
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
index 2d1dd22222..14e8c5d76f 100644
--- a/runtime/doc/starting.txt
+++ b/runtime/doc/starting.txt
@@ -922,7 +922,7 @@ You might want to clean up your 'viewdir' directory now and then.
 
 To automatically save and restore views for *.c files: >
 	au BufWinLeave *.c mkview
-	au BufWinEnter *.c silent loadview
+	au BufWinEnter *.c silent! loadview
 
 ==============================================================================
 8. The ShaDa file				*shada* *shada-file*
diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index f7c2c0e120..3b54f9f268 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -3739,7 +3739,7 @@ Whether or not it is actually concealed depends on the value of the
 'conceallevel' option.  The 'concealcursor' option is used to decide whether
 concealable items in the current line are displayed unconcealed to be able to
 edit the line.
-Another way to conceal text with with |matchadd()|.
+Another way to conceal text is with |matchadd()|.
 
 concealends						*:syn-concealends*
 
@@ -4803,10 +4803,7 @@ guisp={color-name}					*highlight-guisp*
 	    Black	White
 	    Orange	Purple		Violet
 
-	In the Win32 GUI version, additional system colors are available.  See
-	|win32-colors|.
-
-	You can also specify a color by its Red, Green and Blue values.
+	You can also specify a color by its RGB (red, green, blue) values.
 	The format is "#rrggbb", where
 		"rr"	is the Red value
 		"gg"	is the Green value
diff --git a/runtime/doc/tagsrch.txt b/runtime/doc/tagsrch.txt
index 2c090a66fa..b47053e17b 100644
--- a/runtime/doc/tagsrch.txt
+++ b/runtime/doc/tagsrch.txt
@@ -90,7 +90,7 @@ The ignore-case matches are not found for a ":tag" command when:
 - 'tagcase' is "followscs" and 'smartcase' option is on and the pattern
   contains an upper case character.
 
-The gnore-case matches are found when:
+The ignore-case matches are found when:
 - a pattern is used (starting with a "/")
 - for ":tselect"
 - when 'tagcase' is "followic" and 'ignorecase' is off
@@ -432,9 +432,9 @@ The next file in the list is not used when:
 This also depends on whether case is ignored.  Case is ignored when:
 - 'tagcase' is "followic" and 'ignorecase' is set
 - 'tagcase' is "ignore"
-- 'tagcase' is "smart" and and the pattern only contains lower case
+- 'tagcase' is "smart" and the pattern only contains lower case
   characters.
-- 'tagcase' is "followscs" and 'smartcase' is set and and the pattern only
+- 'tagcase' is "followscs" and 'smartcase' is set and the pattern only
   contains lower case characters.
 If case is not ignored, and the tags file only has a match without matching
 case, the next tags file is searched for a match with matching case.  If no
@@ -803,24 +803,24 @@ CTRL-W d		Open a new window, with the cursor on the first
 
 								*:search-args*
 Common arguments for the commands above:
-[!]   When included, find matches in lines that are recognized as comments.
-      When excluded, a match is ignored when the line is recognized as a
-      comment (according to 'comments'), or the match is in a C comment (after
-      "//" or inside /* */).  Note that a match may be missed if a line is
-      recognized as a comment, but the comment ends halfway through the line.
-      And  if the line is a comment, but it is not recognized (according to
-      'comments') a match may be found in it anyway.  Example: >
+[!]	When included, find matches in lines that are recognized as comments.
+	When excluded, a match is ignored when the line is recognized as a
+	comment (according to 'comments'), or the match is in a C comment
+	(after "//" or inside /* */).  Note that a match may be missed if a
+	line is recognized as a comment, but the comment ends halfway the line.
+	And if the line is a comment, but it is not recognized (according to
+	'comments') a match may be found in it anyway.  Example: >
 		/* comment
 		   foobar */
-<     A match for "foobar" is found, because this line is not recognized as a
-      comment (even though syntax highlighting does recognize it).
-      Note: Since a macro definition mostly doesn't look like a comment, the
-      [!] makes no difference for ":dlist", ":dsearch" and ":djump".
-[/]   A pattern can be surrounded by '/'.  Without '/' only whole words are
-      matched, using the pattern "\<pattern\>".  Only after the second '/' a
-      next command can be appended with '|'.  Example: >
+<	A match for "foobar" is found, because this line is not recognized as
+	a comment (even though syntax highlighting does recognize it).
+	Note: Since a macro definition mostly doesn't look like a comment, the
+	[!] makes no difference for ":dlist", ":dsearch" and ":djump".
+[/]	A pattern can be surrounded by '/'.  Without '/' only whole words are
+	matched, using the pattern "\<pattern\>".  Only after the second '/' a
+	next command can be appended with '|'.  Example: >
 	:isearch /string/ | echo "the last one"
-<     For a ":djump", ":dsplit", ":dlist" and ":dsearch" command the pattern
-      is used as a literal string, not as a search pattern.
+<	For a ":djump", ":dsplit", ":dlist" and ":dsearch" command the pattern
+	is used as a literal string, not as a search pattern.
 
  vim:tw=78:ts=8:ft=help:norl:
diff --git a/runtime/doc/vi_diff.txt b/runtime/doc/vi_diff.txt
index 1a108caeaf..1fbd96f749 100644
--- a/runtime/doc/vi_diff.txt
+++ b/runtime/doc/vi_diff.txt
@@ -60,7 +60,7 @@ Support for different systems.
 	- Windows (XP SP 2 or greater)
 	- OS X
 
-Multi level undo.					|undo|
+Multi level persistent undo.					|undo|
 	'u' goes backward in time, 'CTRL-R' goes forward again.  Set option
 	'undolevels' to the number of changes to be remembered (default 1000).
 	Set 'undolevels' to 0 for a Vi-compatible one level undo.  Set it to
@@ -71,6 +71,9 @@ Multi level undo.					|undo|
 	create a branch in the undo tree.  This means you can go back to any
 	state of the text, there is no risk of a change causing text to be
 	lost forever. |undo-tree|
+	The undo information is stored in a file when the 'undofile' option is
+	set.  This means you can exit Vim, start Vim on a previously edited
+	file and undo changes that were made before exiting Vim.
 
 Graphical User Interface (GUI).				|gui|
 	Included support for GUI: menu's, mouse, scrollbars, etc.  You can
@@ -124,6 +127,13 @@ Plugins.						|add-plugin|
 	right directory.  That's an easy way to start using Vim scripts
 	written by others.  Plugins can be for all kind of files, or
 	specifically for a filetype.
+	Packages make this even easier. |packages|
+
+Asynchronous communication and timers.			|job-control| |timer|
+	Vim can exchange messages with other processes in the background.
+	Vim can start a job, communicate with it and stop it. |job-control|
+	Timers can fire once or repeatedly and invoke a function to do any
+	work. |timer|
 
 Repeat a series of commands.				|q|
 	"q{c}" starts recording typed characters into named register {c}.
diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt
index 4ed7b68194..fa7a7f2a81 100644
--- a/runtime/doc/windows.txt
+++ b/runtime/doc/windows.txt
@@ -69,7 +69,7 @@ places where a Normal mode command can't be used or is inconvenient.
 
 The main Vim window can hold several split windows.  There are also tab pages
 |tab-page|, each of which can hold multiple windows.
-
+					*window-ID* *winid* *windowid*
 Each window has a unique identifier called the window ID.  This identifier
 will not change within a Vim session. The |win_getid()| and |win_id2tabwin()|
 functions can be used to convert between the window/tab number and the
@@ -1026,6 +1026,10 @@ list of buffers. |unlisted-buffer|
 			h+	hidden buffers which are modified
 			a+	active buffers which are modified
 
+		When using |:filter| the pattern is matched against the
+		displayed buffer name, e.g.: >
+			filter /\.vim/ ls
+<
 						*:bad* *:badd*
 :bad[d]	[+lnum] {fname}
 		Add file name {fname} to the buffer list, without loading it.