Merge #4923 from justinmk/doc

doc: cleanup

27 files changed, 657 insertions, 1199 deletions

diff --git a/runtime/CMakeLists.txt b/runtime/CMakeLists.txt
index 4dbd193dab..a30bae388d 100644
--- a/runtime/CMakeLists.txt
+++ b/runtime/CMakeLists.txt
@@ -26,23 +26,15 @@ foreach(DF ${DOCFILES})
   list(APPEND BUILDDOCFILES ${GENERATED_RUNTIME_DIR}/doc/${F})
 endforeach()
 
-add_custom_command(OUTPUT copy_docfiles
-    COMMAND ${CMAKE_COMMAND} -E copy_directory
-    ${PROJECT_SOURCE_DIR}/runtime/doc ${GENERATED_RUNTIME_DIR}/doc
-)
-
 add_custom_target(helptags
+  COMMAND ${CMAKE_COMMAND} -E remove_directory ${GENERATED_RUNTIME_DIR}/doc
+  COMMAND ${CMAKE_COMMAND} -E copy_directory
+    ${PROJECT_SOURCE_DIR}/runtime/doc ${GENERATED_RUNTIME_DIR}/doc
   COMMAND "${PROJECT_BINARY_DIR}/bin/nvim"
-    -u NONE
-    -i NONE
-    -e
-    --headless
-    -c "helptags ++t ."
-    -c quit
+    -u NONE -i NONE -e --headless -c "helptags ++t doc" -c quit
   DEPENDS
-    copy_docfiles
     nvim
-  WORKING_DIRECTORY "${GENERATED_RUNTIME_DIR}/doc"
+  WORKING_DIRECTORY "${GENERATED_RUNTIME_DIR}"
 )
 
 add_custom_command(OUTPUT ${GENERATED_HELP_TAGS}
diff --git a/runtime/autoload/provider/clipboard.vim b/runtime/autoload/provider/clipboard.vim
index 2272519dfd..77bc8c781d 100644
--- a/runtime/autoload/provider/clipboard.vim
+++ b/runtime/autoload/provider/clipboard.vim
@@ -58,7 +58,7 @@ elseif executable('doitclient')
   let s:copy['*'] = s:copy['+']
   let s:paste['*'] = s:paste['+']
 else
-  echom 'clipboard: No clipboard tool available. See :help nvim-clipboard'
+  echom 'clipboard: No clipboard tool available. See :help clipboard'
   finish
 endif
 
diff --git a/runtime/autoload/provider/python.vim b/runtime/autoload/provider/python.vim
index cb9d5c5296..b99a046375 100644
--- a/runtime/autoload/provider/python.vim
+++ b/runtime/autoload/provider/python.vim
@@ -1,5 +1,5 @@
 " The Python provider uses a Python host to emulate an environment for running
-" python-vim plugins. See ":help nvim-provider" for more information.
+" python-vim plugins. See ":help provider".
 "
 " Associating the plugin with the Python host is the first step because plugins
 " will be passed as command-line arguments
diff --git a/runtime/autoload/provider/python3.vim b/runtime/autoload/provider/python3.vim
index f4a751e7a2..4f47a03a9b 100644
--- a/runtime/autoload/provider/python3.vim
+++ b/runtime/autoload/provider/python3.vim
@@ -1,5 +1,5 @@
 " The Python3 provider uses a Python3 host to emulate an environment for running
-" python3 plugins. See ":help nvim-provider" for more information.
+" python3 plugins. See ":help provider".
 "
 " Associating the plugin with the Python3 host is the first step because
 " plugins will be passed as command-line arguments
diff --git a/runtime/autoload/provider/pythonx.vim b/runtime/autoload/provider/pythonx.vim
index c3256e8308..0ebf00112f 100644
--- a/runtime/autoload/provider/pythonx.vim
+++ b/runtime/autoload/provider/pythonx.vim
@@ -106,7 +106,7 @@ function! s:check_interpreter(prog, major_ver, skip) abort
 
   if v:shell_error == 2
     return [0, prog_path . ' does not have the neovim module installed. '
-          \ . 'See ":help nvim-python".']
+          \ . 'See ":help provider-python".']
   elseif v:shell_error == 127
     " This can happen with pyenv's shims.
     return [0, prog_path . ' does not exist: ' . prog_ver]
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index ca79465e0d..bdeca367b1 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -1,31 +1,32 @@
-*api.txt*    For Nvim.							 {Nvim}
+*api.txt*		 						{Nvim}
 
 
 		 NVIM REFERENCE MANUAL    by Thiago de Arruda
 
-The C API of Nvim						     *nvim-api*
 
-1. Introduction			|nvim-api-intro|
-2. API Types			|nvim-api-types|
-3. API metadata			|nvim-api-metadata|
-4. Buffer highlighting		|nvim-api-highlights|
+C API for Nvim							   *API* *api*
+
+1. Introduction			|api-intro|
+2. API Types			|api-types|
+3. API metadata			|api-metadata|
+4. Buffer highlighting		|api-highlights|
 
 ==============================================================================
-1. Introduction			*nvim-api-intro*
+1. Introduction							   *api-intro*
 
-Nvim defines a C API as the primary way for external code to interact with
-the NVim core. In the present version of Nvim the API is primarily used by
-external processes to interact with Nvim using the msgpack-rpc protocol, see
-|msgpack-rpc|. The API will also be used from vimscript to access new Nvim core
-features, but this is not implemented yet. Later on, Nvim might be embeddable
-in C applications as libnvim, and the application will then control the
-embedded instance by calling the C API directly.
+Nvim exposes a public API for external code to interact with the Nvim core. In
+the present version of Nvim the API is primarily used by external processes to
+interact with Nvim using the msgpack-rpc protocol, see |msgpack-rpc|. The API
+will also be used from vimscript to access new Nvim core features, but this is
+not implemented yet. Later on, Nvim might be embeddable in C applications as
+libnvim, and the application will then control the embedded instance by
+calling the C API directly.
 
 ==============================================================================
-2. API Types						       *nvim-api-types*
+2. API Types							   *api-types*
 
 Nvim's C API uses custom types for all functions. Some are just typedefs
-around C99 standard types, and some are Nvim defined data structures.
+around C99 standard types, and some are Nvim-defined data structures.
 
 Boolean				  -> bool
 Integer (signed 64-bit integer)	  -> int64_t
@@ -46,7 +47,7 @@ Window				  -> enum value kObjectTypeWindow
 Tabpage				  -> enum value kObjectTypeTabpage
 
 ==============================================================================
-3. API metadata						    *nvim-api-metadata*
+3. API metadata							 *api-metadata*
 
 Nvim exposes metadata about the API as a Dictionary with the following keys:
 
@@ -54,11 +55,11 @@ functions  	calling signature of the API functions
 types		The custom handle types defined by Nvim
 error_types	The possible kinds of errors an API function can exit with.
 
-This metadata is mostly useful for external programs accessing the api over
-msgpack-api, see |msgpack-rpc-api|.
+This metadata is mostly useful for external programs accessing the API via
+RPC, see |rpc-api|.
 
 ==============================================================================
-4. Buffer highlighting					  *nvim-api-highlights*
+4. Buffer highlighting					       *api-highlights*
 
 Nvim allows plugins to add position-based highlights to buffers. This is
 similar to |matchaddpos()| but with some key differences. The added highlights
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index 25ae94f784..6641732679 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -912,8 +912,7 @@ TermClose			When a terminal buffer ends.
 						 {Nvim} *TermOpen*
 TermOpen			When a terminal buffer is starting.  This can
 				be used to configure the terminal emulator by
-				setting buffer variables.
-				See |nvim-terminal-emulator| for details.
+				setting buffer variables. |terminal-emulator|
 							*TermResponse*
 TermResponse			After the response to |t_RV| is received from
 				the terminal.  The value of |v:termresponse|
diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt
index c3f1b69da7..4565cdf63e 100644
--- a/runtime/doc/change.txt
+++ b/runtime/doc/change.txt
@@ -1250,7 +1250,7 @@ register.
 Use these registers for storing and retrieving the selected text for the GUI.
 See |quotestar| and |quoteplus|.  When the clipboard is not available or not
 working, the unnamed register is used instead.  For Unix systems and Mac OS X,
-see |nvim-clipboard|.
+see |primary-selection|.
 
 9. Black hole register "_				*quote_*
 When writing to this register, nothing happens.  This can be used to delete
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 8881845fdd..1b77d87aac 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -1,23 +1,19 @@
-*develop.txt*   For Vim version 7.4.  Last change: 2016 Jan 31
+*develop.txt*
 
 
-		  VIM REFERENCE MANUAL    by Bram Moolenaar
+                            NVIM REFERENCE MANUAL
 
 
-Development of Vim.					*development*
-
-This text is important for those who want to be involved in further developing
-Vim.
+Development of Nvim.					*development*
 
 1. Design goals		|design-goals|
 2. Design decisions	|design-decisions|
 
-See the file "src/nvim/README.md" for a high-level overview of the source
-code.
+Nvim is open source software.  Everybody is encouraged to contribute.
+    https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md
 
-Vim is open source software.  Everybody is encouraged to contribute to help
-improving Vim.  For sending patches a context diff "diff -c" is preferred.
-Also see http://vim.wikia.com/wiki/How_to_make_and_submit_a_patch.
+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
 
 ==============================================================================
 1. Design goals						*design-goals*
@@ -28,7 +24,7 @@ Note that quite a few items are contradicting.  This is intentional.  A
 balance must be found between them.
 
 
-VIM IS... IMPROVED					*design-improved*
+NVIM IS... IMPROVED					*design-improved*
 
 The IMproved bits of Vim should make it a better Vi, without becoming a
 completely different editor.  Extensions are done with a "Vi spirit".
@@ -49,7 +45,7 @@ completely different editor.  Extensions are done with a "Vi spirit".
   implement and (3) someone actually implementing it.
 
 
-VIM IS... MULTI PLATFORM				*design-multi-platform*
+NVIM IS... MULTI PLATFORM				*design-multi-platform*
 
 Vim tries to help as many users on as many platforms as possible.
 - Support many kinds of terminals.  The minimal demands are cursor positioning
@@ -68,7 +64,7 @@ Vim tries to help as many users on as many platforms as possible.
   contradicts the previous item, these two must be balanced.]
 
 
-VIM IS... WELL DOCUMENTED				*design-documented*
+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.
@@ -76,9 +72,14 @@ VIM IS... WELL DOCUMENTED				*design-documented*
   recommended.
 - 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
+  differences from Vim. The {Nvim} annotation is also available
+  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|.
 
 
-VIM IS... HIGH SPEED AND SMALL IN SIZE			*design-speed-size*
+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.
@@ -89,13 +90,11 @@ fast.
   possible.  Useful commands may take longer.
 - Don't forget that some people use Vim over a slow connection.  Minimize the
   communication overhead.
-- Items that add considerably to the size and are not used by many people
-  should be a feature that can be disabled.
 - Vim is a component among other components.  Don't turn it into a massive
   application, but have it work well together with other programs.
 
 
-VIM IS... MAINTAINABLE					*design-maintain*
+NVIM IS... MAINTAINABLE					*design-maintain*
 
 - The source code should not become a mess.  It should be reliable code.
 - Use comments in a useful way!  Quoting the function name and argument names
@@ -106,7 +105,7 @@ VIM IS... MAINTAINABLE					*design-maintain*
   knowledge spread to other parts of the code.
 
 
-VIM IS... FLEXIBLE					*design-flexible*
+NVIM IS... FLEXIBLE					*design-flexible*
 
 Vim should make it easy for users to work in their preferred styles rather
 than coercing its users into particular patterns of work.  This can be for
@@ -117,27 +116,15 @@ be used to adjust Vim to the desire of the user and its environment.
 
 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 attempt to include everything but the kitchen sink, but some people use it
-for plumbing."
+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."
 
 
 ==============================================================================
 2. Design decisions					*design-decisions*
 
-Folding
-
-Several forms of folding should be possible for the same buffer.  For example,
-have one window that shows the text with function bodies folded, another
-window that shows a function body.
-
-Folding is a way to display the text.  It should not change the text itself.
-Therefore the folding has been implemented as a filter between the text stored
-in a buffer (buffer lines) and the text displayed in a window (logical lines).
-
-
-Naming the window
+Window
 
 The word "window" is commonly used for several things: A window on the screen,
 the xterm window, a window inside Vim to view a buffer.
@@ -153,110 +140,52 @@ window		View on a buffer.  There can be several windows in Vim,
 		fit in the shell.
 
 
-Spell checking						*develop-spell*
-
-When spell checking was going to be added to Vim a survey was done over the
-available spell checking libraries and programs.  Unfortunately, the result
-was that none of them provided sufficient capabilities to be used as the spell
-checking engine in Vim, for various reasons:
-
-- Missing support for multi-byte encodings.  At least UTF-8 must be supported,
-  so that more than one language can be used in the same file.
-  Doing on-the-fly conversion is not always possible (would require iconv
-  support).
-- For the programs and libraries: Using them as-is would require installing
-  them separately from Vim.  That's mostly not impossible, but a drawback.
-- Performance: A few tests showed that it's possible to check spelling on the
-  fly (while redrawing), just like syntax highlighting.  But the mechanisms
-  used by other code are much slower.  Myspell uses a hashtable, for example.
-  The affix compression that most spell checkers use makes it slower too.
-- For using an external program like aspell a communication mechanism would
-  have to be setup.  That's complicated to do in a portable way (Unix-only
-  would be relatively simple, but that's not good enough).  And performance
-  will become a problem (lots of process switching involved).
-- Missing support for words with non-word characters, such as "Etten-Leur" and
-  "et al.", would require marking the pieces of them OK, lowering the
-  reliability.
-- Missing support for regions or dialects.  Makes it difficult to accept
-  all English words and highlight non-Canadian words differently.
-- Missing support for rare words.  Many words are correct but hardly ever used
-  and could be a misspelled often-used word.
-- For making suggestions the speed is less important and requiring to install
-  another program or library would be acceptable.  But the word lists probably
-  differ, the suggestions may be wrong words.
-
-
-Spelling suggestions				*develop-spell-suggestions*
-
-For making suggestions there are two basic mechanisms:
-1. Try changing the bad word a little bit and check for a match with a good
-   word.  Or go through the list of good words, change them a little bit and
-   check for a match with the bad word.  The changes are deleting a character,
-   inserting a character, swapping two characters, etc.
-2. Perform soundfolding on both the bad word and the good words and then find
-   matches, possibly with a few changes like with the first mechanism.
-
-The first is good for finding typing mistakes.  After experimenting with
-hashtables and looking at solutions from other spell checkers the conclusion
-was that a trie (a kind of tree structure) is ideal for this.  Both for
-reducing memory use and being able to try sensible changes.  For example, when
-inserting a character only characters that lead to good words need to be
-tried.  Other mechanisms (with hashtables) need to try all possible letters at
-every position in the word.  Also, a hashtable has the requirement that word
-boundaries are identified separately, while a trie does not require this.
-That makes the mechanism a lot simpler.
-
-Soundfolding is useful when someone knows how the words sounds but doesn't
-know how it is spelled.  For example, the word "dictionary" might be written
-as "daktonerie".  The number of changes that the first method would need to
-try is very big, it's hard to find the good word that way.  After soundfolding
-the words become "tktnr" and "tkxnry", these differ by only two letters.
-
-To find words by their soundfolded equivalent (soundalike word) we need a list
-of all soundfolded words.  A few experiments have been done to find out what
-the best method is.  Alternatives:
-1. Do the sound folding on the fly when looking for suggestions.  This means
-   walking through the trie of good words, soundfolding each word and
-   checking how different it is from the bad word.  This is very efficient for
-   memory use, but takes a long time.  On a fast PC it takes a couple of
-   seconds for English, which can be acceptable for interactive use.  But for
-   some languages it takes more than ten seconds (e.g., German, Catalan),
-   which is unacceptable slow.  For batch processing (automatic corrections)
-   it's too slow for all languages.
-2. Use a trie for the soundfolded words, so that searching can be done just
-   like how it works without soundfolding.  This requires remembering a list
-   of good words for each soundfolded word.  This makes finding matches very
-   fast but requires quite a lot of memory, in the order of 1 to 10 Mbyte.
-   For some languages more than the original word list.
-3. Like the second alternative, but reduce the amount of memory by using affix
-   compression and store only the soundfolded basic word.  This is what Aspell
-   does.  Disadvantage is that affixes need to be stripped from the bad word
-   before soundfolding it, which means that mistakes at the start and/or end
-   of the word will cause the mechanism to fail.  Also, this becomes slow when
-   the bad word is quite different from the good word.
-
-The choice made is to use the second mechanism and use a separate file.  This
-way a user with sufficient memory can get very good suggestions while a user
-who is short of memory or just wants the spell checking and no suggestions
-doesn't use so much memory.
-
-
-Word frequency
-
-For sorting suggestions it helps to know which words are common.  In theory we
-could store a word frequency with the word in the dictionary.  However, this
-requires storing a count per word.  That degrades word tree compression a lot.
-And maintaining the word frequency for all languages will be a heavy task.
-Also, it would be nice to prefer words that are already in the text.  This way
-the words that appear in the specific text are preferred for suggestions.
-
-What has been implemented is to count words that have been seen during
-displaying.  A hashtable is used to quickly find the word count.  The count is
-initialized from words listed in COMMON items in the affix file, so that it
-also works when starting a new file.
-
-This isn't ideal, because the longer Vim is running the higher the counts
-become.  But in practice it is a noticeable improvement over not using the word
-count.
+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
+a "provider" hook is exposed.
+
+Consider two examples of integration with external systems that are
+implemented in Vim and are now decoupled from Nvim core as providers:
+
+1. In the Vim source code, clipboard logic accounts for more than 1k lines of
+   C source code (ui.c), to perform two tasks that are now accomplished with
+   shell commands such as xclip or pbcopy/pbpaste.
+
+2. Python scripting support: Vim has three files dedicated to embedding the
+   Python interpreter: if_python.c, if_python3.c and if_py_both.h. Together
+   these files sum about 9.5k lines of C source code. In contrast, Nvim Python
+   scripting is performed by an external host process implemented in ~2k lines
+   of Python.
+
+Ideally we could implement Python and clipboard integration in pure vimscript
+and without touching the C code. But this is infeasible without compromising
+backwards compatibility with Vim; that's where providers help.
+
+The provider framework helps call vimscript from C. It is composed of two
+functions in eval.c:
+
+- eval_call_provider(name, method, arguments): calls provider#(name)#Call
+  with the method and arguments.
+- eval_has_provider(name): Checks if a provider is implemented. Returns true
+  if the provider#(name)#Call function is implemented. Called by |has()|
+  (vimscript) to check if features are available.
+
+The provider#(name)#Call function implements integration with an external
+system, because shell commands and |RPC| clients are easier to work with in
+vimscript.
+
+For example, the Python provider is implemented by the
+autoload/provider/python.vim script; the provider#python#Call function is only
+defined if a valid external Python host is found. That works well with the
+`has('python')` expression (normally used by Python plugins) because if the
+Python host isn't installed then the plugin will "think" it is running in
+a Vim compiled without the |+python| feature.
+
+
+RPC API
+API client
+remote plugin
 
  vim:tw=78:ts=8:ft=help:norl:
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 71a7682f15..b89b68837e 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1653,9 +1653,9 @@ v:scrollstart	String describing the script or function that caused the
 		hit-enter prompt.
 
 					*v:servername* *servername-variable*
+					*$NVIM_LISTEN_ADDRESS*
 v:servername	Default {Nvim} server address. Equivalent to
-		|$NVIM_LISTEN_ADDRESS| on startup, but may differ if the
-		latter is modified or unset. |serverstop()|
+		|$NVIM_LISTEN_ADDRESS| on startup. |serverstop()|
 		Read-only.
 
 		
@@ -2031,11 +2031,11 @@ resolve({filename})		String	get filename a shortcut points to
 reverse({list})		List	reverse {list} in-place
 round({expr})			Float	round off {expr}
 rpcnotify({channel}, {event}[, {args}...])
-				Sends a |msgpack-rpc| notification to {channel}
+				Sends an |RPC| notification to {channel}
 rpcrequest({channel}, {method}[, {args}...])
-				Sends a |msgpack-rpc| request to {channel}
-rpcstart({prog}[, {argv}])	Spawns {prog} and opens a |msgpack-rpc| channel
-rpcstop({channel})		Closes a |msgpack-rpc| {channel}
+				Sends an |RPC| request to {channel}
+rpcstart({prog}[, {argv}])	Spawns {prog} and opens an |RPC| channel
+rpcstop({channel})		Closes an |RPC| {channel}
 screenattr({row}, {col})	Number	attribute at screen position
 screenchar({row}, {col})	Number	character at screen position
 screencol()			Number	current cursor column
@@ -5526,31 +5526,31 @@ round({expr})							*round()*
 <			-5.0
 
 rpcnotify({channel}, {event}[, {args}...])		  {Nvim} *rpcnotify()*
-		Sends {event} to {channel} via |msgpack-rpc| and returns
-		immediately. If {channel} is 0, the event is broadcast to all
-		channels. Example: >
+		Sends {event} to {channel} via |RPC| and returns immediately.
+		If {channel} is 0, the event is broadcast to all channels.
+		Example: >
 			:au VimLeave call rpcnotify(0, "leaving")
 
 rpcrequest({channel}, {method}[, {args}...])		 {Nvim} *rpcrequest()*
 		Sends a request to {channel} to invoke {method} via
-		|msgpack-rpc| and blocks until a response is received.
+		|RPC| and blocks until a response is received.
 		Example: >
 			:let result = rpcrequest(rpc_chan, "func", 1, 2, 3)
 
 rpcstart({prog}[, {argv}])				   {Nvim} *rpcstart()*
 		Spawns {prog} as a job (optionally passing the list {argv}),
-		and opens a |msgpack-rpc| channel with the spawned process's
-		stdin/stdout. It returns:
-		  - The channel id on success, which is used by |rpcrequest()|,
+		and opens an |RPC| channel with the spawned process's
+		stdin/stdout. Returns:
+		  - channel id on success, which is used by |rpcrequest()|,
 		    |rpcnotify()| and |rpcstop()|
-		  - 0 on failure.
+		  - 0 on failure
 		Example: >
 			:let rpc_chan = rpcstart('prog', ['arg1', 'arg2'])
 
 rpcstop({channel})					    {Nvim} *rpcstop()*
-		Closes a |msgpack-rpc| {channel}, possibly created via
+		Closes an |RPC| {channel}, possibly created via
 		|rpcstart()|. Also closes channels created by connections to
-		|$NVIM_LISTEN_ADDRESS|.
+		|v:servername|.
 
 screenattr(row, col)						*screenattr()*
 		Like screenchar(), but return the attribute.  This is a rather
@@ -6841,7 +6841,7 @@ termopen({cmd}[, {opts}])			{Nvim} *termopen()*
 		and `$TERM` is set to "xterm-256color".
 		Returns the same values as |jobstart()|.
 
-		See |nvim-terminal-emulator| for more information.
+		See |terminal-emulator| for more information.
 
 tan({expr})						*tan()*
 		Return the tangent of {expr}, measured in radians, as a |Float|
diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt
index 8d97678af2..e2fb501ac5 100644
--- a/runtime/doc/gui.txt
+++ b/runtime/doc/gui.txt
@@ -395,9 +395,9 @@ You may make selections with the mouse (see |gui-mouse-select|), or by using
 Vim's Visual mode (see |v|).  If 'a' is present in 'guioptions', then
 whenever a selection is started (Visual or Select mode), or when the selection
 is changed, Vim becomes the owner of the windowing system's primary selection
-(on MS-Windows the |gui-clipboard| is used).
+(on MS-Windows the |clipboard| is used).
 
-							*clipboard*
+							*primary-selection*
 There is a special register for storing this selection, it is the "*
 register.  Nothing is put in here unless the information about what text is
 selected is about to change (e.g. with a left mouse click somewhere), or when
diff --git a/runtime/doc/gui_w32.txt b/runtime/doc/gui_w32.txt
deleted file mode 100644
index 228be9eab2..0000000000
--- a/runtime/doc/gui_w32.txt
+++ /dev/null
@@ -1,437 +0,0 @@
-*gui_w32.txt*   For Vim version 7.4.  Last change: 2014 Dec 20
-
-
-		  VIM REFERENCE MANUAL    by Bram Moolenaar
-
-
-Vim's Win32 Graphical User Interface			*gui-w32* *win32-gui*
-
-1. Starting the GUI		|gui-w32-start|
-2. Vim as default editor	|vim-default-editor|
-3. Using the clipboard		|gui-clipboard|
-4. Shell Commands		|gui-shell-win32|
-5. Special colors		|win32-colors|
-6. Windows dialogs & browsers	|gui-w32-dialogs|
-7. Command line arguments	|gui-w32-cmdargs|
-8. Various			|gui-w32-various|
-
-Other relevant documentation:
-|gui.txt|	For generic items of the GUI.
-|os_win32.txt| 	For Win32 specific items.
-
-==============================================================================
-1. Starting the GUI					*gui-w32-start*
-
-The Win32 GUI version of Vim will always start the GUI, no matter how you
-start it or what it's called.
-
-The GUI will always run in the Windows subsystem.  Mostly shells automatically
-return with a command prompt after starting gvim.  If not, you should use the
-"start" command: >
-	start gvim [options] file ..
-
-Note: All fonts (bold, italic) must be of the same size!!!  If you don't do
-this, text will disappear or mess up the display.  Vim does not check the font
-sizes.  It's the size in screen pixels that must be the same.  Note that some
-fonts that have the same point size don't have the same pixel size!
-Additionally, the positioning of the fonts must be the same (ascent and
-descent).
-
-The Win32 GUI has an extra menu item:  "Edit/Select Font".  It brings up the
-standard Windows font selector.
-
-Setting the menu height doesn't work for the Win32 GUI.
-
-							*gui-win32-maximized*
-If you want Vim to start with a maximized window, add this command to your
-vimrc or gvimrc file: >
-	au GUIEnter * simalt ~x
-<
-==============================================================================
-2. Vim as default editor				*vim-default-editor*
-
-To set Vim as the default editor for a file type:
-1. Start a Windows Explorer
-2. Choose View/Options -> File Types
-3. Select the path to gvim for every file type that you want to use it for.
-   (you can also use three spaces in the file type field, for files without an
-   extension).
-   In the "open" action, use: >
-	gvim "%1"
-<  The quotes are required for using file names with embedded spaces.
-   You can also use this: >
-	gvim "%L"
-<  This should avoid short (8.3 character) file names in some situations.  But
-   I'm not sure if this works everywhere.
-
-When you open a file in Vim by double clicking it, Vim changes to that
-file's directory.
-
-If you want Vim to start full-screen, use this for the Open action: >
-	gvim -c "simalt ~x" "%1"
-
-Another method, which also works when you put Vim in another directory (e.g.,
-when you have got a new version):
-1. select a file you want to use Vim with
-2. <Shift-F10>
-3. select "Open With..." menu entry
-4. click "Other..."
-5. browse to the (new) location of Vim and click "Open"
-6. make "Always Use this program..." checked
-7. <OK>
-
-						*send-to-menu* *sendto*
-You can also install Vim in the "Send To" menu:
-1. Start a Windows Explorer
-2. Navigate to your sendto directory:
-   Windows NT: %windir%\profiles\%user%\sendto (e.g.
-	       "c:\winnt\profiles\mattha\sendto").
-3. Right-click in the file pane and select New->Shortcut
-4. Follow the shortcut wizard, using the full path to VIM/GVIM.
-
-When you 'send a file to Vim', Vim changes to that file's directory.  Note,
-however, that any long directory names will appear in their short (MS-DOS)
-form.  This is a limitation of the Windows "Send To" mechanism.
-
-						*notepad*
-You could replace notepad.exe with gvim.exe, but that has a few side effects.
-Some programs rely on notepad arguments, which are not recognized by Vim.  For
-example "notepad -p" is used by some applications to print a file.  It's
-better to leave notepad where it is and use another way to start Vim.
-
-						*win32-popup-menu*
-A more drastic approach is to install an "Edit with Vim" entry in the popup
-menu for the right mouse button.  With this you can edit any file with Vim.
-
-This can co-exist with the file associations mentioned above.  The difference
-is that the file associations will make starting Vim the default action.  With
-the "Edit with Vim" menu entry you can keep the existing file association for
-double clicking on the file, and edit the file with Vim when you want.  For
-example, you can associate "*.mak" with your make program.  You can execute
-the makefile by double clicking it and use the "Edit with Vim" entry to edit
-the makefile.
-
-You can select any files and right-click to see a menu option called "Edit
-with gvim".  Choosing this menu option will invoke gvim with the file you have
-selected.  If you select multiple files, you will find two gvim-related menu
-options:
-"Edit with multiple gvims"  -- one gvim for each file in the selection
-"Edit with single gvim"     -- one gvim for all the files in the selection
-And if there already is a gvim running:
-"Edit with existing gvim"   -- edit the file with the running gvim
-
-The "edit with existing Vim" entries can be disabled by adding an entry in the
-registry under HKLM\Software\Vim\Gvim, named DisableEditWithExisting, and with
-any value.
-						*install-registry*
-You can add the "Edit with Vim" menu entry in an easy way by using the
-"install.exe" program.  It will add several registry entries for you.
-
-You can also do this by hand.  This is complicated!  Use the install.exe if
-you can.
-
-1. Start the registry editor with "regedit".
-2. Add these keys:
-   key		value name		    value ~
-   HKEY_CLASSES_ROOT\CLSID\{51EEE242-AD87-11d3-9C1E-0090278BBD99}
-		{default}		    Vim Shell Extension
-   HKEY_CLASSES_ROOT\CLSID\{51EEE242-AD87-11d3-9C1E-0090278BBD99}\InProcServer32
-		{default}		    {path}\gvimext.dll
-		ThreadingModel		    Apartment
-   HKEY_CLASSES_ROOT\*\shellex\ContextMenuHandlers\gvim
-		{default}		    {51EEE242-AD87-11d3-9C1E-0090278BBD99}
-   HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Approved
-		{51EEE242-AD87-11d3-9C1E-0090278BBD99}
-					    Vim Shell Extension
-   HKEY_LOCAL_MACHINE\Software\Vim\Gvim
-		path			    {path}\gvim.exe
-   HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall\vim 5.6
-		DisplayName		    Vim 5.6: Edit with Vim popup menu entry
-		UninstallString		    {path}\uninstal.exe
-
-   Replace {path} with the path that leads to the executable.
-   Don't type {default}, this is the value for the key itself.
-
-To remove "Edit with Vim" from the popup menu, just remove the registry
-entries mentioned above.  The "uninstal.exe" program can do this for you.  You
-can also use the entry in the Windows standard "Add/Remove Programs" list.
-
-If you notice that this entry overrules other file type associations, set
-those associations again by hand (using Windows Explorer, see above).  This
-only seems to happen on some Windows NT versions (Windows bug?).  Procedure:
-1. Find the name of the file type.  This can be done by starting the registry
-   editor, and searching for the extension in \\HKEY_CLASSES_ROOT
-2. In a Windows Explorer, use View/Options/File Types.  Search for the file
-   type in the list and click "Edit".  In the actions list, you can select on
-   to be used as the default (normally the "open" action) and click on the
-   "Set Default" button.
-
-
-Vim in the "Open With..." context menu			*win32-open-with-menu*
-
-If you use the Vim install program you have the choice to add Vim to the "Open
-With..." menu.  This means you can use Vim to edit many files.  Not every file
-(for unclear reasons...), thus the "Edit with Vim" menu entry is still useful.
-
-One reason to add this is to be able to edit HTML files directly from Internet
-Explorer.  To enable this use the "Tools" menu, "Internet Options..." entry.
-In the dialog select the "Programs" tab and select Vim in the "HTML editor"
-choice.  If it's not there than installing didn't work properly.
-
-Doing this manually can be done with this script:
-
-----------------------------------------------------------
-REGEDIT4
-
-[HKEY_CLASSES_ROOT\Applications\gvim.exe]
-
-[HKEY_CLASSES_ROOT\Applications\gvim.exe\shell]
-
-[HKEY_CLASSES_ROOT\Applications\gvim.exe\shell\edit]
-
-[HKEY_CLASSES_ROOT\Applications\gvim.exe\shell\edit\command]
-@="c:\\vim\\vim62\\gvim.exe \"%1\""
-
-[HKEY_CLASSES_ROOT\.htm\OpenWithList\gvim.exe]
-
-[HKEY_CLASSES_ROOT\*\OpenWithList\gvim.exe]
-
-----------------------------------------------------------
-
-Change the "c:\\vim\\vim62" bit to where gvim.exe is actually located.
-
-To uninstall this run the Vim uninstall program or manually delete the
-registry entries with "regedit".
-
-==============================================================================
-3. Using the clipboard					*gui-clipboard*
-
-Windows has a clipboard, where you can copy text to, and paste text from.  Vim
-supports this in several ways.  For other systems see |gui-selections|.
-
-The "* register reflects the contents of the clipboard.  |quotestar|
-
-When the "unnamed" string is included in the 'clipboard' option, the unnamed
-register is the same.  Thus you can yank to and paste from the clipboard
-without prepending "* to commands.
-
-The 'a' flag in 'guioptions' is not included by default.  This means that text
-is only put on the clipboard when an operation is performed on it.  Just
-Visually selecting text doesn't put it on the clipboard.  When the 'a' flag is
-included, the text is copied to the clipboard even when it is not operated
-upon.
-
-							*mswin.vim*
-To use the standard MS-Windows way of CTRL-X, CTRL-C and CTRL-V, use the
-$VIMRUNTIME/mswin.vim script.  You could add this line to your _vimrc file: >
-	source $VIMRUNTIME/mswin.vim
-
-Since CTRL-C is used to copy the text to the clipboard, it can't be used to
-cancel an operation.  Use CTRL-Break for that.
-
-CTRL-Z is used for undo.  This means you can't suspend Vim with this key, use
-|:suspend| instead (if it's supported at all).
-
-						*CTRL-V-alternative* *CTRL-Q*
-Since CTRL-V is used to paste, you can't use it to start a blockwise Visual
-selection.  You can use CTRL-Q instead.  You can also use CTRL-Q in Insert
-mode and Command-line mode to get the old meaning of CTRL-V.  But CTRL-Q
-doesn't work for terminals when it's used for control flow.
-
-NOTE: The clipboard support still has a number of bugs.
-
-==============================================================================
-4. Shell Commands					*gui-shell-win32*
-
-Vim uses another window for external commands, to make it possible to run any
-command.  The external command gets its own environment for running, just like
-it was started from a DOS prompt.
-
-							*win32-vimrun*
-Executing an external command is done indirectly by the "vimrun" command.  The
-"vimrun.exe" must be in the path for this to work.  Or it must be in the same
-directory as the Vim executable.  If "vimrun" cannot be found, the command is
-executed directly, but then the DOS window closes immediately after the
-external command has finished.
-WARNING: If you close this window with the "X" button, and confirm the
-question if you really want to kill the application, Vim may be killed too!
-(This does not apply to commands run asynchronously with ":!start".)
-
-							*win32-!start*
-Normally, Vim waits for a command to complete before continuing (this makes
-sense for most shell commands which produce output for Vim to use).  If you
-want Vim to start a program and return immediately, you can use the following
-syntax on W95 & NT: >
-	:!start [/min] {command}
-The optional "/min" causes the window to be minimized.
-
-==============================================================================
-5. Special colors					*win32-colors*
-
-On Win32, the normal DOS colors can be used.  See |dos-colors|.
-
-Additionally the system configured colors can also be used.  These are known
-by the names Sys_XXX, where XXX is the appropriate system color name, from the
-following list (see the Win32 documentation for full descriptions).  Case is
-ignored.
-
-Sys_3DDKShadow		Sys_3DFace			Sys_BTNFace
-Sys_3DHilight		Sys_3DHighlight			Sys_BTNHilight
-Sys_BTNHighlight	Sys_3DLight			Sys_3DShadow
-Sys_BTNShadow		Sys_ActiveBorder		Sys_ActiveCaption
-Sys_AppWorkspace	Sys_Background			Sys_Desktop
-Sys_BTNText		Sys_CaptionText			Sys_GrayText
-Sys_Highlight		Sys_HighlightText		Sys_InactiveBorder
-Sys_InactiveCaption	Sys_InactiveCaptionText		Sys_InfoBK
-Sys_InfoText		Sys_Menu			Sys_MenuText
-Sys_ScrollBar		Sys_Window			Sys_WindowFrame
-Sys_WindowText
-
-Probably the most useful values are
-	Sys_Window	    Normal window background
-	Sys_WindowText      Normal window text
-	Sys_Highlight       Highlighted background
-	Sys_HighlightText   Highlighted text
-
-These extra colors are also available:
-Gray, Grey, LightYellow, SeaGreen, Orange, Purple, SlateBlue, Violet,
-
-								*rgb.txt*
-Additionally, colors defined by a "rgb.txt" file can be used.  This file is
-well known from X11.  A few lines from it: >
-
-  255 218 185		   peach puff
-  205 133  63		   peru
-  255 181 197		   pink
-
-This shows the layout of the file:  First the R, G and B value as a decimal
-number, followed by the name of the color.  The four fields are separated by
-spaces.
-
-You can get an rgb.txt file from any X11 distribution.  It is located in a
-directory like "/usr/X11R6/lib/X11/".  For Vim it must be located in the
-$VIMRUNTIME directory.  Thus the file can be found with "$VIMRUNTIME/rgb.txt".
-
-==============================================================================
-						*gui-w32-dialogs* *dialog*
-6. Windows dialogs & browsers
-
-The Win32 GUI can use familiar Windows components for some operations, as well
-as the traditional interface shared with the console version.
-
-
-6.1 Dialogs
-
-The dialogs displayed by the "confirm" family (i.e. the 'confirm' option,
-|:confirm| command and |confirm()| function) are GUI-based rather than the
-console-based ones used by other versions.  The 'c' flag in 'guioptions'
-changes this.
-
-
-6.2 File Browsers
-
-When prepending ":browse" before file editing commands, a file requester is
-used to allow you to select an existing file.  See |:browse|.
-
-==============================================================================
-7. Command line arguments				*gui-w32-cmdargs*
-
-Analysis of a command line into parameters is not standardised in MS Windows.
-Gvim has to provide logic to analyse a command line.  This logic is likely to
-be different from the default logic provided by a compilation system used to
-build vim.  The differences relate to unusual double quote (") usage.
-The arguments "C:\My Music\freude.txt" and "+/Sch\"iller" are handled in the
-same way.  The argument "+/Sch""iller" may be handled different by gvim and
-vim, depending what it was compiled with.
-
-The rules are:
-      a) A parameter is a sequence of graphic characters.
-      b) Parameters are separated by white space.
-      c) A parameter can be enclosed in double quotes to include white space.
-      d) A sequence of zero or more backslashes (\) and a double quote (")
-	is special.  The effective number of backslashes is halved, rounded
-	down.  An even number of backslashes reverses the acceptability of
-	spaces and tabs, an odd number of backslashes produces a literal
-	double quote.
-
-So:
-	"	is a special double quote
-	\"	is a literal double quote
-	\\"	is a literal backslash and a special double quote
-	\\\"	is a literal backslash and a literal double quote
-	\\\\"	is 2 literal backslashes and a special double quote
-	\\\\\"	is 2 literal backslashes and a literal double quote
-	etc.
-
-Example: >
-	gvim "C:\My Music\freude" +"set ignorecase" +/"\"foo\\" +\"bar\\\"
-
-opens "C:\My Music\freude" and executes the line mode commands: >
-	set ignorecase; /"foo\ and /bar\"
-
-==============================================================================
-8. Various						*gui-w32-various*
-
-							*gui-w32-printing*
-The "File/Print" menu prints the text with syntax highlighting, see
-|:hardcopy|.  If you just want to print the raw text and have a default
-printer installed this should also work: >
-	:w >>prn
-
-Vim supports a number of standard MS Windows features.  Some of these are
-detailed elsewhere: see |'mouse'|, |win32-hidden-menus|.
-
-							*drag-n-drop-win32*
-You can drag and drop one or more files into the Vim window, where they will
-be opened as normal.  See |drag-n-drop|.
-
-							*:simalt* *:sim*
-:sim[alt] {key}		simulate pressing {key} while holding Alt pressed.
-			{only for Win32 versions}
-
-Normally, Vim takes control of all Alt-<Key> combinations, to increase the
-number of possible mappings.  This clashes with the standard use of Alt as the
-key for accessing menus.
-The quick way of getting standard behavior is to set the 'winaltkeys' option
-to "yes".  This however prevents you from mapping Alt keys at all.
-Another way is to set 'winaltkeys' to "menu".  Menu shortcut keys are then
-handled by windows, other ALT keys can be mapped.  This doesn't allow a
-dependency on the current state though.
-To get round this, the :simalt command allows Vim (when 'winaltkeys' is not
-"yes") to fake a Windows-style Alt keypress.  You can use this to map Alt key
-combinations (or anything else for that matter) to produce standard Windows
-actions.  Here are some examples: >
-
-	:map <M-f> :simalt f<CR>
-This makes Alt-F pop down the 'File' menu (with the stock Menu.vim) by
-simulating the keystrokes Alt, F. >
-	:map <M-Space> :simalt ~<CR>
-This maps Alt-Space to pop down the system menu for the Vim window.  Note that
-~ is used by simalt to represent the <Space> character. >
-	:map <C-n> :simalt ~n<CR>
-Maps Control-N to produce the keys Alt-Space followed by N.  This minimizes the
-Vim window via the system menu.
-
-Note that the key changes depending on the language you are using.
-
-						*intellimouse-wheel-problems*
-When using the Intellimouse mouse wheel causes Vim to stop accepting input, go
-to:
-	ControlPanel - Mouse - Wheel - UniversalScrolling - Exceptions
-
-And add gvim to the list of applications.  This problem only appears to happen
-with the Intellimouse driver 2.2 and when "Universal Scrolling" is turned on.
-
-
-XPM support						*w32-xpm-support*
-
-Gvim can be build on MS-Windows with support for XPM files.  |+xpm_w32|
-See the Make_mvc.mak file for instructions, search for XPM.
-
-To try out if XPM support works do this: >
-	:help
-	:exe 'sign define vimxpm icon=' . $VIMRUNTIME . '\\vim16x16.xpm'
-	:exe 'sign place 1 line=1 name=vimxpm file=' . expand('%:p')
-<
-
- vim:tw=78:sw=4:ts=8:ft=help:norl:
diff --git a/runtime/doc/if_pyth.txt b/runtime/doc/if_pyth.txt
index f6bd365299..8946dd2e5a 100644
--- a/runtime/doc/if_pyth.txt
+++ b/runtime/doc/if_pyth.txt
@@ -16,7 +16,7 @@ The Python Interface to Vim				*python* *Python*
 8. pyeval(), py3eval() Vim functions		|python-pyeval|
 9. Python 3					|python3|
 
-See |nvim-python| for more information. {Nvim}
+See |provider-python| for more information. {Nvim}
 
 ==============================================================================
 1. Commands						*python-commands*
diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt
index bafb9dfc2c..2c4b1b35bc 100644
--- a/runtime/doc/msgpack_rpc.txt
+++ b/runtime/doc/msgpack_rpc.txt
@@ -1,97 +1,88 @@
-*msgpack_rpc.txt*    For Nvim.						 {Nvim}
+*msgpack_rpc.txt*							{Nvim}
 
 
 		 NVIM REFERENCE MANUAL    by Thiago de Arruda
 
 
-The Msgpack-RPC Interface to Nvim				  *msgpack-rpc*
+RPC API for Nvim				     *RPC* *rpc* *msgpack-rpc*
 
-1. Introduction			|msgpack-rpc-intro|
-2. API mapping			|msgpack-rpc-api|
-3. Connecting			|msgpack-rpc-connecting|
-4. Clients			|msgpack-rpc-clients|
-5. Types			|msgpack-rpc-types|
-6. Wrapping methods		|msgpack-rpc-wrap-methods|
-7. Vimscript functions		|msgpack-rpc-vim-functions|
+1. Introduction			|rpc-intro|
+2. API mapping			|rpc-api|
+3. Connecting			|rpc-connecting|
+4. Clients			|rpc-client|
+5. Types			|rpc-types|
+6. Vimscript functions		|rpc-vim-functions|
 
 ==============================================================================
-1. Introduction						    *msgpack-rpc-intro*
+1. Introduction						            *rpc-intro*
 
-The primary way to control a running Nvim instance is through
-MessagePack-RPC, a messaging protocol that uses the MessagePack serialization
-format: https://github.com/msgpack/msgpack/blob/7498cf3/spec.md.
-From now on, we refer to the protocol as msgpack-rpc.
+The primary way to control Nvim programmatically is the RPC API, which speaks
+MessagePack-RPC ("msgpack-rpc"), a messaging protocol that uses the
+MessagePack serialization format:
+  https://github.com/msgpack/msgpack/blob/0b8f5ac/spec.md
 
-At this point, only plugins use msgpack-rpc, but eventually even user
-interaction will happen through it, since user interfaces will be separate
-programs that control a headless Nvim instance.
+All kinds of Nvim "clients" use the RPC API: user interfaces (GUIs), remote
+plugins, scripts like "nvr" (https://github.com/mhinz/neovim-remote), and even
+`nvim` itself can control other `nvim` instances. By connecting to the RPC API
+programs can:
 
-By connecting to the msgpack-rpc interface, programs can:
+  - Call any API function
+  - Listen for events
+  - Receive remote calls from Nvim
 
-- Call any Nvim API function
-- Listen for Nvim events
-- Receive remote calls from Nvim
-
-Nvim's msgpack-rpc interface is like a more powerful version of Vim's
-`clientserver` feature.
+The RPC API is like a more powerful version of Vim's `clientserver` feature.
 
 ==============================================================================
-2. API mapping						      *msgpack-rpc-api*
+ 2. API mapping							    *rpc-api*
 
-The Nvim C API, see |nvim-api|, is automatically exposed to the msgpack-rpc
-interface by the build system, which parses headers at src/nvim/api from the
-project root. A dispatch function is generated, which matches msgpack-rpc method
-names with non-static API functions, converting/validating arguments and return
-values back to msgpack.
+The Nvim C |API| is automatically exposed to the RPC API by the build system,
+which parses headers at src/nvim/api/*. A dispatch function is generated which
+matches RPC API method names with public API functions, converting/validating
+arguments and return values back to msgpack.
 
-Client libraries will normally provide wrappers that hide msgpack-rpc details
-from programmers. The wrappers can be automatically generated by reading
-bundled API metadata from a compiled Nvim instance.
+Client libraries (|api-client|s) normally provide wrappers that hide
+msgpack-rpc details from application developers. The wrappers can be
+automatically generated by reading bundled API metadata from a compiled Nvim
+instance.
 
 There are two ways to obtain API metadata:
 
-1. By connecting to a running Nvim instance and calling `vim_get_api_info`
-   via msgpack-rpc. This is best for clients written in dynamically-typed
-   languages, which can define functions at runtime.
+  1. Connect to a running Nvim instance and call `vim_get_api_info` via
+     msgpack-rpc. This is best for clients written in dynamic languages which
+     can define functions at runtime.
 
-2. By starting Nvim with the `--api-info` command-line option, which makes Nvim
-   dump a blob of msgpack metadata to standard output and exit. This is best
-   for clients written in statically-typed languages, which require a separate
-   compilation step.
+  2. Start Nvim with the `--api-info` command-line option, which dumps a blob
+     of msgpack metadata to standard output. This is useful for clients
+     written in statically-compiled languages.
 
-Here's a simple way to get human-readable description of the API (requires
-Python and the `pyyaml`/`msgpack-python` pip packages):
->
-    nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))' > api.yaml
+To get a human-readable list of API functions: >
+    :new|put =map(msgpackparse(systemlist('nvim --api-info'))[0].functions, 'v:val.name._VAL[0]')
+<
+To get a formatted dump of the API using python (requires the `pyyaml` and
+`msgpack-python` packages): >
+    nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))'
 <
 ==============================================================================
-3. Connecting					       *msgpack-rpc-connecting*
+3. Connecting						      *rpc-connecting*
 
-There are four ways to open msgpack-rpc streams to Nvim:
+There are several ways to open a msgpack-rpc stream to an Nvim server:
 
-1. Through Nvim's stdin/stdout when it's started with the `--embed` option.
-   This is how other programs can embed Nvim.
+  1. Through stdin/stdout when `nvim` is started with `--embed`. This is how
+     applications can embed Nvim.
 
-2. Through the stdin/stdout of a program spawned by the |rpcstart()| function.
+  2. Through stdin/stdout of some other process spawned by |rpcstart()|.
 
-							*$NVIM_LISTEN_ADDRESS*
-3. Through the socket automatically created with each instance. To get the
-   socket location for a running Nvim instance (which is random by default),
-   see the |$NVIM_LISTEN_ADDRESS| environment variable:
->
-       :echo $NVIM_LISTEN_ADDRESS
-<
-   See also |v:servername|.
+  3. Through the socket automatically created with each instance. The socket
+     location is stored in |v:servername|.
 
-4. Through a TCP/IP socket. To make Nvim listen on a TCP/IP socket, set the
-   |$NVIM_LISTEN_ADDRESS| environment variable in a shell before starting Nvim:
->
+  4. Through a TCP/IP socket. To make Nvim listen on a TCP/IP socket, set the
+     |$NVIM_LISTEN_ADDRESS| environment variable before starting Nvim: >
         NVIM_LISTEN_ADDRESS=127.0.0.1:6666 nvim
 <
-Connecting to the socket is the easiest way a programmer can test the API, which
-can be done through any msgpack-rpc client library or fully-featured Nvim client
-(which we'll see in the next section). Here's a Ruby script that prints 'hello
-world!' in the current Nvim instance:
+Connecting to the socket is the easiest way a programmer can test the API,
+which can be done through any msgpack-rpc client library or full-featured
+|api-client|. Here's a Ruby script that prints 'hello world!' in the current
+Nvim instance:
 >
     #!/usr/bin/env ruby
     # Requires msgpack-rpc: gem install msgpack-rpc
@@ -118,72 +109,103 @@ functions can be called interactively:
     >>> nvim = attach('socket', path='[address]')
     >>> nvim.command('echo "hello world!"')
 <
-One can also spawn and connect to an embedded Nvim instance via |rpcstart()|
+You can also embed an Nvim instance via |rpcstart()|
 >
     let vim = rpcstart('nvim', ['--embed'])
     echo rpcrequest(vim, 'vim_eval', '"Hello " . "world!"')
     call rpcstop(vim)
 <
 ==============================================================================
-4. Implementing new clients				  *msgpack-rpc-clients*
-
-Nvim is still in alpha, so there's no in-depth documentation explaining how to
-properly implement a client library yet. The Python client (the pip package
-"neovim") will always be up-to-date with the latest API changes, so its source
-code is the best documentation currently available. There are some guidelines
-however:
-
-- Separate the transport layer from the rest of the library. See
-  |msgpack-rpc-connecting| for details on how clients can connect to Nvim.
-- Use a MessagePack library that implements at least version 5 of the
-  MessagePack spec, which supports the `bin` and `ext` types used by Nvim.
-- Read API metadata in order to create client-side wrappers for all
-  msgpack-rpc methods.
-- Use a single-threaded event loop library/pattern.
-- Use a fiber/coroutine library for the language being used for implementing a
-  client. These greatly simplify concurrency and allow the library to expose a
-  blocking API on top of a non-blocking event loop without the complexity that
-  comes with preemptive multitasking.
-- Don't assume anything about the order that responses to msgpack-rpc requests
-  will arrive.
-- Clients should expect msgpack-rpc requests, which need to be handled
-  immediately because Nvim is blocked while waiting for the client response.
-- Clients should expect to receive msgpack-rpc notifications, but these don't
-  need to be handled immediately because they won't block Nvim (although they
-  should probably be handled immediately anyway).
-
-Most of the complexity could be handled by a msgpack-rpc library that supports
-server to client requests and notifications, but it's not clear if this is part
-of the msgpack-rpc spec. At least the Ruby msgpack-rpc library does not seem
-to support it:
-
+4. Implementing API clients			*rpc-api-client* *api-client*
+
+All external UIs and remote plugins (as opposed to regular Vim plugins) are
+"clients" in general; but we call something an "API client" if its purpose is
+to abstract or wrap the RPC API for the convenience of other applications
+(just like a REST client or SDK such as boto3 for AWS: you can speak AWS REST
+using an HTTP client like curl, but boto3 wraps that in a convenient python
+interface). For example, the lua-client is an API client:
+    https://github.com/neovim/lua-client
+
+The Python client (pip package "neovim") is the reference implementation of an
+API client. It is always up-to-date with the Nvim API, so its source code and
+test suite are an authoritative reference.
+    https://github.com/neovim/python-client
+
+API client implementation guidelines ~
+
+  - Separate the transport layer from the rest of the library. See
+    |rpc-connecting| for details on how clients can connect to Nvim.
+  - Use a MessagePack library that implements at least version 5 of the
+    MessagePack spec, which supports the `bin` and `ext` types used by Nvim.
+  - Read API metadata in order to create client-side wrappers for all
+    msgpack-rpc methods.
+  - Use a single-threaded event loop library/pattern.
+  - Use a fiber/coroutine library for the language being used for implementing
+    a client. These greatly simplify concurrency and allow the library to
+    expose a blocking API on top of a non-blocking event loop without the
+    complexity that comes with preemptive multitasking.
+  - Don't assume anything about the order that responses to msgpack-rpc
+    requests will arrive.
+  - Clients should expect msgpack-rpc requests, which need to be handled
+    immediately because Nvim is blocked while waiting for the client response.
+  - Clients should expect to receive msgpack-rpc notifications, but these
+    don't need to be handled immediately because they won't block Nvim
+    (although they should probably be handled immediately anyway).
+
+Note: Most of the complexity could be handled by a msgpack-rpc library that
+supports server to client requests and notifications, but it's not clear if
+this is part of the msgpack-rpc spec. At least the Ruby msgpack-rpc library
+does not seem to support it:
 https://github.com/msgpack-rpc/msgpack-rpc-ruby/blob/master/lib/msgpack/rpc/transport/tcp.rb#L150-L158
 
+API metadata object ~
+
+API clients exist to hide msgpack-rpc details. The API metadata object
+contains information that makes this task easier (see also |rpc-types|):
+
+  - The "functions" key contains a list of metadata objects for individual
+    functions.
+  - Each function metadata object has |rpc-types| information about the return
+    value and parameters. These can be used for generating strongly-typed APIs
+    in static languages.
+  - Container types may be decorated with type/size constraints, e.g.
+    ArrayOf(Buffer) or ArrayOf(Integer, 2). This can be useful to generate
+    even more strongly-typed APIs.
+  - Methods that operate on instances of Nvim special types (msgpack EXT) are
+    prefixed with the type name in lower case, e.g. `buffer_get_line`
+    represents the `get_line` method of a Buffer instance.
+  - Global methods are prefixed with `vim`, e.g. `vim_get_buffers`.
+
+So for an object-oriented language, an API client contains the classes
+representing Nvim special types, and the methods of each class could be
+defined by inspecting the method name prefix. There could also be a singleton
+Vim class with methods mapped to functions prefixed with `vim_`.
+
 ==============================================================================
-5. Types						    *msgpack-rpc-types*
+5. Types							    *rpc-types*
 
-Nvim's C API uses custom types for all functions, se |nvim-api-types|.
-For the purpose of mapping to msgpack, he types can be split into two groups:
+The Nvim C API uses custom types for all functions. |api-types|
+For the purpose of mapping to msgpack, the types can be split into two groups:
 
-- Basic types that map natively to msgpack (and probably have a default
-  representation in msgpack-supported programming languages)
-- Special Nvim types that map to msgpack EXT with custom type codes.
+  - Basic types that map natively to msgpack (and probably have a default
+    representation in msgpack-supported programming languages)
+  - Special Nvim types that map to msgpack EXT with custom type codes.
 
-Basic type mapping:
+Basic types ~
 
-Nil				  -> msgpack nil
-Boolean				  -> msgpack boolean
-Integer (signed 64-bit integer)	  -> msgpack integer
-Float (IEEE 754 double precision) -> msgpack float
-String				  -> msgpack string
-Array				  -> msgpack array
-Dictionary			  -> msgpack map
+  Nil                               -> msgpack nil
+  Boolean                           -> msgpack boolean
+  Integer (signed 64-bit integer)   -> msgpack integer
+  Float (IEEE 754 double precision) -> msgpack float
+  String                            -> msgpack string
+  Array                             -> msgpack array
+  Dictionary                        -> msgpack map
 
-Special Nvim types that use msgpack EXT:
+Special types (msgpack EXT) ~
 
-Buffer				  -> enum value kObjectTypeBuffer
-Window				  -> enum value kObjectTypeWindow
-Tabpage				  -> enum value kObjectTypeTabpage
+  Buffer                            -> enum value kObjectTypeBuffer
+  Window                            -> enum value kObjectTypeWindow
+  Tabpage                           -> enum value kObjectTypeTabpage
 
 An API method expecting one of these types may be passed an integer instead,
 although they are not interchangeable. For example, a Buffer may be passed as
@@ -191,7 +213,7 @@ an integer, but not a Window or Tabpage.
 
 The most reliable way of determining the type codes for the special Nvim types
 is to inspect the `types` key of metadata dictionary returned by the
-`vim_get_api_info` method at runtime. Here's an example JSON representation of
+`vim_get_api_info` method at runtime. Here's a sample JSON representation of
 the `types` object:
 >
   "types": {
@@ -206,55 +228,27 @@ the `types` object:
     }
   }
 <
-Even for statically compiled clients, it's a good practice to avoid hardcoding
-the type codes, because a client may be built against one Nvim version but connect
-to another with different type codes.
+Even for statically compiled clients it is good practice to avoid hardcoding
+the type codes, because a client may be built against one Nvim version but
+connect to another with different type codes.
 
 ==============================================================================
-6. Wrapping methods				     *msgpack-rpc-wrap-methods*
-
-As mentioned before, clients should provide an API that hides msgpack-rpc
-details from programmers, and the API metadata object contains information
-that makes this task easier:
-
-- The "functions" key contains a list of metadata objects for individual
-  functions.
-- Each function metadata object has type information about the return value
-  and parameters. These can be used for generating strongly-typed APIs in
-  static languages.
-- Container types may be decorated with type/size constraints, e.g.
-  ArrayOf(Buffer) or ArrayOf(Integer, 2). This can be useful to generate even
-  more strongly-typed APIs.
-- Methods that operate instances of Nvim's types are prefixed with the type
-  name in lower case, e.g. `buffer_get_line` represents the `get_line` method
-  of a Buffer instance.
-- Global methods are prefixed with `vim`, e.g. `vim_get_buffers`.
-
-So, for an object-oriented language, a client library would have the classes
-that represent Nvim's types, and the methods of each class could be defined
-by inspecting the method name prefix. There could also be a singleton Vim
-class with methods mapped to functions prefixed with `vim_`
-
-==============================================================================
-7. Vimscript functions				   *msgpack-rpc-vim-functions*
-
-Four msgpack-rpc functions are available in Vimscript:
-
-1. |rpcstart()|: Similarly to |jobstart()|, this will spawn a co-process with
-   its standard handles connected to Nvim. The difference is that it's not
-   possible to process raw data to or from the process's stdin, stdout, or
-   stderr.  This is because the job's stdin and stdout are used as a single
-   msgpack channel that is processed directly by Nvim.
-
-2. |rpcstop()|: Same as |jobstop()|, but operates on handles returned by
-   |rpcstart()|.
-
-3. |rpcrequest()|: Sends a msgpack-rpc request to the process.
-
-4. |rpcnotify()|: Sends a msgpack-rpc notification to the process.
-
-The last two functions may also be used with channels created from
-connections to |$NVIM_LISTEN_ADDRESS|.
+6. Vimscript functions				           *rpc-vim-functions*
+
+RPC functions are available in Vimscript:
+
+  1. |rpcstart()|: Similarly to |jobstart()|, this will spawn a co-process
+     with its standard handles connected to Nvim. The difference is that it's
+     not possible to process raw data to or from the process's stdin, stdout,
+     or stderr.  This is because the job's stdin and stdout are used as
+     a single msgpack channel that is processed directly by Nvim.
+  2. |rpcstop()|: Same as |jobstop()|, but operates on handles returned by
+     |rpcstart()|.
+  3. |rpcrequest()|: Sends a msgpack-rpc request to the process.
+  4. |rpcnotify()|: Sends a msgpack-rpc notification to the process.
+
+|rpcrequest()| and |rpcnotify()| can also be used with channels connected to
+a nvim server. |v:servername|
 
 ==============================================================================
  vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/nvim.txt b/runtime/doc/nvim.txt
index a7c512d1dc..904fb3c16c 100644
--- a/runtime/doc/nvim.txt
+++ b/runtime/doc/nvim.txt
@@ -1,24 +1,56 @@
-*nvim.txt*    For Nvim.						{Nvim}
+*nvim.txt*								{Nvim}
 
 
-		 NVIM REFERENCE MANUAL				*nvim*
+			    NVIM REFERENCE MANUAL
 
 
-Introduction to Nvim				*nvim-intro*
+Nvim						*nvim* *nvim-intro*
 
-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|.
+If you are new to Vim (and Nvim) see |help.txt| or type ":Tutor".
+If you already use Vim (but not Nvim) see |nvim-from-vim| for a quickstart.
 
-1. Transitioning from Vim	 |nvim-from-vim|
-2. Differences from Vim		 |vim-differences|
-3. Msgpack-RPC			 |msgpack-rpc|
-4. Job control			 |job-control|
-5. Python plugins		 |nvim-python|
-6. Clipboard integration	 |nvim-clipboard|
-7. Remote plugins		 |remote-plugin|
-8. Provider infrastructure	 |nvim-provider|
-9. Integrated terminal emulator	 |nvim-terminal-emulator|
+Nvim is emphatically a fork of Vim, not a clone: compatibility with Vim is
+maintained where possible. See |vim_diff.txt| for the complete reference of
+differences from Vim.
+
+==============================================================================
+Transitioning from Vim				*nvim-from-vim*
+
+To start the transition, link your previous configuration so Nvim can use it:
+>
+    mkdir -p ${XDG_CONFIG_HOME:=$HOME/.config}
+    ln -s ~/.vim $XDG_CONFIG_HOME/nvim
+    ln -s ~/.vimrc $XDG_CONFIG_HOME/nvim/init.vim
+<
+See |provider-python| and |provider-clipboard| for additional software you
+might need to use some features.
+
+Your Vim configuration might not be entirely compatible with Nvim. For a
+full list of differences between Vim and Nvim see |vim-differences|.
+
+The |'ttymouse'| option, for example, was removed from Nvim (mouse support
+should work without it). If you use the same |vimrc| for Vim and Nvim,
+consider guarding |'ttymouse'| in your configuration like so:
+>
+    if !has('nvim')
+        set ttymouse=xterm2
+    endif
+<
+Conversely, if you have Nvim specific configuration items, you could do
+this:
+>
+    if has('nvim')
+        tnoremap <Esc> <C-\><C-n>
+    endif
+<
+For a more granular approach use |exists()|:
+>
+    if exists(':tnoremap')
+        tnoremap <Esc> <C-\><C-n>
+    endif
+<
+Now you should be able to explore Nvim more comfortably. Check |nvim-features|
+for more information.
 
 ==============================================================================
  vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/nvim_clipboard.txt b/runtime/doc/nvim_clipboard.txt
deleted file mode 100644
index 078382c7a7..0000000000
--- a/runtime/doc/nvim_clipboard.txt
+++ /dev/null
@@ -1,63 +0,0 @@
-*nvim_clipboard.txt*    For Nvim.					{Nvim}
-
-
-		 NVIM REFERENCE MANUAL    by Thiago de Arruda
-
-
-Clipboard integration for Nvim					*nvim-clipboard*
-
-1. Intro			|nvim-clipboard-intro|
-2. X11 selection mechanism	|nvim-clipboard-x11|
-
-==============================================================================
-1. Intro						  *nvim-clipboard-intro*
-
-Nvim has no direct connection to the system clipboard. Instead, it is
-accessible through the |nvim-provider| infrastructure, which transparently
-uses shell commands for communicating with the clipboard.
-
-Clipboard access is implicitly enabled if any of the following clipboard tools
-is found in your `$PATH`.
-
-- xclip
-- xsel (newer alternative to xclip)
-- pbcopy/pbpaste (only for Mac OS X)
-- lemonade (useful for SSH machine)
-  https://github.com/pocke/lemonade
-- doitclient (another option for SSH setups from the maintainer of PuTTY)
-  http://www.chiark.greenend.org.uk/~sgtatham/doit/
-
-The presence of a suitable clipboard tool implicitly enables the '+' and '*'
-registers.
-
-If you want to ALWAYS use the clipboard for ALL operations (as opposed
-to interacting with the '+' and/or '*' registers explicitly), set the
-following option:
->
-    set clipboard+=unnamedplus
-<
-See 'clipboard' for details and more options.
-
-==============================================================================
-2. X11 selection mechanism		      *nvim-clipboard-x11* *x11-selection*
-
-The clipboard providers for X11 store text in what is known as "selections".
-Selections are "owned" by an application, so when the application is closed,
-the selection text is lost.
-
-The contents of selections are held by the originating application (e.g., upon
-a copy), and only passed on to another application when that other application
-asks for them (e.g., upon a paste).
-
-							      *quoteplus* *quote+*
-
-There are three documented X11 selections: `PRIMARY`, `SECONDARY`, and `CLIPBOARD`.
-`CLIPBOARD` is typically used in X11 applications for copy/paste operations
-(`Ctrl-c`/`v`), while `PRIMARY` is used for the last selected text, which is
-generally inserted with the middle mouse button.
-
-Nvim's X11 clipboard providers only utilize the `PRIMARY` and `CLIPBOARD`
-selections, used for the '*' and '+' registers, respectively.
-
-==============================================================================
- vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/nvim_from_vim.txt b/runtime/doc/nvim_from_vim.txt
deleted file mode 100644
index 299eeb05f5..0000000000
--- a/runtime/doc/nvim_from_vim.txt
+++ /dev/null
@@ -1,50 +0,0 @@
-*nvim_from_vim.txt*    For Nvim.						{Nvim}
-
-
-		 NVIM REFERENCE MANUAL
-
-
-Transitioning from Vim				*nvim-from-vim*
-
-Nvim is emphatically a fork of Vim, so compatibility to Vim should be pretty
-good.
-
-To start the transition, link your previous configuration so Nvim can use
-it:
->
-    mkdir -p ${XDG_CONFIG_HOME:=$HOME/.config}
-    ln -s ~/.vim $XDG_CONFIG_HOME/nvim
-    ln -s ~/.vimrc $XDG_CONFIG_HOME/nvim/init.vim
-<
-See |nvim-intro|, especially |nvim-python| and |nvim-clipboard|, for
-additional software you might need to install to use all of Nvim's features.
-
-Your Vim configuration might not be entirely compatible with Nvim. For a
-full list of differences between Vim and Nvim, see |vim-differences|.
-
-The |'ttymouse'| option, for example, was removed from Nvim (mouse support
-should work without it). If you use the same |vimrc| for Vim and Nvim,
-consider guarding |'ttymouse'| in your configuration like so:
->
-    if !has('nvim')
-        set ttymouse=xterm2
-    endif
-<
-Conversely, if you have Nvim specific configuration items, you could do
-this:
->
-    if has('nvim')
-        tnoremap <Esc> <C-\><C-n>
-    endif
-<
-For a more granular approach, use |exists()|:
->
-    if exists(':tnoremap')
-        tnoremap <Esc> <C-\><C-n>
-    endif
-<
-Now you should be able to explore Nvim more comfortably. Check |nvim| for more
-information.
-
-==============================================================================
- vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/nvim_provider.txt b/runtime/doc/nvim_provider.txt
deleted file mode 100644
index 91cd5fbfc7..0000000000
--- a/runtime/doc/nvim_provider.txt
+++ /dev/null
@@ -1,76 +0,0 @@
-*nvim_provider.txt*    For Nvim.					{Nvim}
-
-
-		 NVIM REFERENCE MANUAL    by Thiago de Arruda
-
-
-Nvim provider infrastructure			       *nvim-provider*
-
-First of all, this document is meant to be read by developers interested in
-contributing to the refactoring effort. If you are a normal user or plugin
-developer looking to learn about Nvim |msgpack-rpc| infrastructure for
-implementing plugins in other programming languages, see |remote-plugin|.
-For instructions on how to enable Python plugins, see |nvim-python|. For
-clipboard, see |nvim-clipboard|.
-
-Instead of doing everything by itself, Nvim aims to simplify its own
-maintenance by delegating as much work as possible to external systems. But
-some Vim components are too tightly coupled and in some cases the refactoring
-work necessary to swap in-house implementations by code that integrates to
-other systems is too great. Nvim provider infrastructure is a facility that
-aims to make this task simpler.
-
-To understand why the provider infrastructure is useful, let us consider two
-examples of integration with external systems that are implemented in Vim and
-are now decoupled from Nvim core as providers:
-
-The first example is clipboard integration: in the original Vim source code,
-clipboard functions account for more than 1k lines of C source code (and that
-is just on ui.c), all to perform two tasks that are now accomplished with
-simple shell commands such as xclip or pbcopy/pbpaste.
-
-The other example is Python scripting support: Vim has three files dedicated to
-embedding the Python interpreter: if_python.c, if_python3.c and if_py_both.h.
-Together these files sum about 9.5k lines of C source code. On Nvim, Python
-scripting is performed by an external host process that is running 2k sloc
-Python program.
-
-In a perfect world, we would implement Python and clipboard integration in
-pure vimscript and without touching the C code. Unfortunately we can't achieve
-these goals without severely compromising backwards compatibility with Vim.
-That's where providers come to the rescue.
-
-In essence, this infrastructure is a simple framework that simplifies the task
-of calling vimscript from C code, making it simpler to rewrite C functions that
-interact with external systems in pure vimscript. It is composed of two
-functions in eval.c:
-
-- eval_call_provider(name, method, arguments): Call a provider(name) method
-  with arguments
-- eval_has_provider(name): Checks if a provider is implemented
-
-What these functions do is simple:
-
-- eval_call_provider will call the provider#(name)#Call function passing in
-  the method and arguments.
-- eval_has_provider will return true if the provider#(name)#Call function is
-  implemented, and is called by the "has" vimscript function to check if
-  features are available.
-
-The basic idea is that the provider#(name)#Call function should implement
-integration with an external system, because calling shell commands and
-|msgpack-rpc| clients (Nvim only) is easier to do in vimscript.
-
-Now, back to the Python example. Instead of modifying vimscript to allow for
-the definition of lowercase functions and commands (for the |:python|,
-|:pyfile|, and |:pydo| commands, and the |pyeval()| function), which would
-break backwards compatibility with Vim, we implemented the
-autoload/provider/python.vim script and the provider#python#Call function
-that is only defined if an external Python host is started successfully.
-
-That works well with the `has('python')` expression (normally used by Python
-plugins) because if the Python host isn't installed then the plugin will
-"think" it is running in a Vim compiled without |+python| feature.
-
-==============================================================================
- vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/nvim_python.txt b/runtime/doc/nvim_python.txt
deleted file mode 100644
index 27955a76b1..0000000000
--- a/runtime/doc/nvim_python.txt
+++ /dev/null
@@ -1,112 +0,0 @@
-*nvim_python.txt*    For Nvim.						{Nvim}
-
-
-		 NVIM REFERENCE MANUAL    by Thiago de Arruda
-
-
-Python plugins and scripting in Nvim				  *nvim-python*
-
-1. Introduction			|nvim-python-intro|
-2. Quickstart			|nvim-python-quickstart|
-3. Troubleshooting		|nvim-python-troubleshooting|
-
-==============================================================================
-1. Introduction						    *nvim-python-intro*
-
-Through external Python 2/3 interpreters connected via |msgpack-rpc|, Nvim
-offers some support for the legacy |python-vim| and |python3| interfaces.
-
-Note: For now only the old Vim 7.3 API is supported.
-
-==============================================================================
-2. Quickstart						 *nvim-python-quickstart*
-
-If you used a package manager to install Nvim, there's a good chance that
-it also provides the `neovim` Python package. If it doesn't, follow these
-steps to install the package with Python's package manager, `pip`.
-
-Note: Depending on your system, `pip` might refer to Python 2 or Python 3,
-      which is why the following instructions mention `pip2` or `pip3`
-      explicitly. If one of these is not available for you, maybe `pip`
-      is what you want.
-
-To use Vim Python 2/3 plugins with Nvim, do the following:
-
-- For Python 2 plugins, make sure an interpreter for Python 2.6 or 2.7 is
-  available in your `$PATH`, then install the `neovim` Python package systemwide:
-  >
-    $ sudo pip2 install neovim
-<
-  or for the current user:
->
-    $ pip2 install --user neovim
-<
-- For Python 3 plugins, make sure an interpreter for Python 3.3 or above is
-  available in your `$PATH`, then install the `neovim` Python package systemwide:
-  >
-    $ sudo pip3 install neovim
-<
-  or for the current user:
->
-    $ pip3 install --user neovim
-<
-Note: If you previously installed the package, get the latest version by
-      appending the `--upgrade` flag to the commands above.
-
-==============================================================================
-							   *g:python_host_prog*
-
-To point Nvim to a specific Python 2 interpreter, set |g:python_host_prog|:
->
-    let g:python_host_prog = '/path/to/python'
-<
-							   *g:python3_host_prog*
-
-To point Nvim to a specific Python 3 interpreter, set |g:python3_host_prog|:
->
-    let g:python3_host_prog = '/path/to/python3'
-<
-						   *g:loaded_python_provider*
-
-To disable Python 2 interface, set `g:loaded_python_provider` to 1:
->
-    let g:loaded_python_provider = 1
-<
-						   *g:loaded_python3_provider*
-
-To disable Python 3 interface, set `g:loaded_python3_provider` to 1:
->
-    let g:loaded_python3_provider = 1
-<
-						   *g:python_host_skip_check*
-
-To disable Python 2 interpreter check, set `g:python_host_skip_check` to 1:
-Note: If you disable Python 2 check, you must install neovim module properly.
->
-    let g:python_host_skip_check = 1
-<
-						   *g:python3_host_skip_check*
-
-To disable Python 3 interpreter check, set `g:python3_host_skip_check` to 1:
-Note: If you disable Python 3 check, you must install neovim module properly.
->
-    let g:python3_host_skip_check = 1
-<
-==============================================================================
-3. Troubleshooting				  *nvim-python-troubleshooting*
-
-If you are experiencing issues with a plugin that uses the `neovim` Python
-client, you can use the |:CheckHealth| command to quickly rule out your setup
-as a problem.
-
-								 *:CheckHealth*
-:CheckHealth[!]	  Check your setup for common problems that may be keeping a
-		  plugin from functioning correctly.  Including the output of
-		  this command in bug reports can help reduce the amount of
-		  time it takes to address your issue.  If [!] is present, the
-		  output will be placed in a new buffer which can make it
-		  easier to save to a file or copy to the clipboard.
-
-
-==============================================================================
- vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt
index 6ef3aaebaa..45695ccf02 100644
--- a/runtime/doc/nvim_terminal_emulator.txt
+++ b/runtime/doc/nvim_terminal_emulator.txt
@@ -1,34 +1,30 @@
-*nvim_terminal_emulator.txt*    For Nvim.				{Nvim}
+*terminal_emulator.txt*    						{Nvim}
 
 
 		 NVIM REFERENCE MANUAL    by Thiago de Arruda
 
 
-Nvim integrated terminal emulator		     *nvim-terminal-emulator*
+Embedded terminal emulator				   *terminal-emulator*
 
-1. Introduction			|nvim-terminal-emulator-introduction|
-2. Spawning			|nvim-terminal-emulator-spawning|
-3. Input			|nvim-terminal-emulator-input|
-4. Configuration		|nvim-terminal-emulator-configuration|
+1. Introduction			|terminal-emulator-intro|
+2. Spawning			|terminal-emulator-spawning|
+3. Input			|terminal-emulator-input|
+4. Configuration		|terminal-emulator-configuration|
 
 ==============================================================================
-1. Introduction			      *nvim-terminal-emulator-introduction*
+1. Introduction					     *terminal-emulator-intro*
 
-One feature that distinguishes Nvim from Vim is that it implements a mostly
-complete VT220/xterm-like terminal emulator. The terminal is presented to the
-user as a special buffer type, one that is asynchronously updated to mirror
-the virtual terminal display as data is received from the program connected
-to it. For most purposes, terminal buffers behave a lot like normal buffers
-with 'nomodifiable' set.
+Nvim offers a mostly complete VT220/xterm terminal emulator. The terminal is
+presented as a special buffer type, asynchronously updated to mirror the
+virtual terminal display as data is received from the program connected to it.
+For most purposes, terminal buffers behave a lot like normal buffers with
+'nomodifiable' set.
 
-
-The implementation is powered by libvterm[1], a powerful abstract terminal
-emulation library.
-
-[1]: http://www.leonerd.org.uk/code/libvterm/
+The implementation is powered by libvterm, a powerful abstract terminal
+emulation library. http://www.leonerd.org.uk/code/libvterm/
 
 ==============================================================================
-2. Spawning			      *nvim-terminal-emulator-spawning*
+2. Spawning					  *terminal-emulator-spawning*
 
 There are 3 ways to create a terminal buffer:
 
@@ -46,7 +42,7 @@ Note that |:mksession| will "save" the terminal buffers by restarting all
 programs when the session is restored.
 
 ==============================================================================
-3. Input			      *nvim-terminal-emulator-input*
+3. Input					     *terminal-emulator-input*
 
 Sending input is possible by entering terminal mode, which is achieved by
 pressing any key that would enter insert mode in a normal buffer (|i| or |a|
@@ -90,7 +86,7 @@ Mouse input is also fully supported, and has the following behavior:
   the terminal wont lose focus and the hovered window will be scrolled.
 
 ==============================================================================
-4. Configuration		     *nvim-terminal-emulator-configuration*
+4. Configuration			     *terminal-emulator-configuration*
 
 Terminal buffers can be customized through the following global/buffer-local
 variables (set via the |TermOpen| autocmd):
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index ea0a18c6f3..50b1262347 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -1172,8 +1172,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	  help		help buffer (you are not supposed to set this
 			manually)
 	  terminal	terminal buffer, this is set automatically when a 
-			terminal is created. See |nvim-terminal-emulator| for
-			more information.
+			terminal is created. |terminal-emulator|
 
 	This option is used together with 'bufhidden' and 'swapfile' to
 	specify special kinds of buffers.   See |special-buffers|.
@@ -1353,7 +1352,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 			used regardless of whether "unnamed" is in 'clipboard'
 			or not.  The clipboard register can always be
 			explicitly accessed using the "* notation.  Also see
-			|gui-clipboard|.
+			|clipboard|.
 
 						*clipboard-unnamedplus*
 	unnamedplus	A variant of the "unnamed" flag which uses the
@@ -1363,7 +1362,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 			register.  When "unnamed" is also included to the
 			option, yank and delete operations (but not put)
 			will additionally copy the text into register
-			'*'. See |nvim-clipboard|.
+			'*'. See |clipboard|.
 
 						*clipboard-autoselect*
 	autoselect	Works like the 'a' flag in 'guioptions': If present,
diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt
new file mode 100644
index 0000000000..db5c61879c
--- /dev/null
+++ b/runtime/doc/provider.txt
@@ -0,0 +1,139 @@
+*provider.txt*								{Nvim}
+
+
+		 NVIM REFERENCE MANUAL    by Thiago de Arruda
+
+
+Providers	 						    *provider*
+
+Nvim delegates some features to dynamic "providers".
+
+==============================================================================
+Python integration		    	      *provider-python*
+
+Nvim supports the Vim legacy |python-vim| and |python3| interfaces via
+external Python interpreters connected via |RPC|,
+
+Note: Only the Vim 7.3 API is supported; bindeval (Vim 7.4) is not.
+
+
+PYTHON QUICKSTART ~
+
+If you used a package manager to install Nvim there's a good chance that
+it also provides the `neovim` Python package. If it doesn't, follow these
+steps to install the package with Python's package manager, `pip`.
+
+Note: Depending on your system, `pip` might refer to Python 2 or Python 3,
+      which is why the following instructions mention `pip2` or `pip3`
+      explicitly. If one of these is not available, try `pip`.
+
+To use Vim Python 2/3 plugins with Nvim:
+
+- For Python 2 plugins, make sure an interpreter for Python 2.6 or 2.7 is
+  available in your `$PATH`, then install the `neovim` Python package systemwide: >
+    $ sudo pip2 install --upgrade neovim
+<
+  or for the current user: >
+    $ pip2 install --user --upgrade neovim
+<
+- For Python 3 plugins, make sure an interpreter for Python 3.3 or above is
+  available in your `$PATH`, then install the `neovim` Python package systemwide: >
+    $ sudo pip3 install --upgrade neovim
+<
+  or for the current user: >
+    $ pip3 install --user --upgrade neovim
+<
+Note: The `--upgrade` flag ensures you have the latest version even if
+      a previous version was already installed.
+
+PYTHON PROVIDER CONFIGURATION ~
+						*g:python_host_prog*
+Set `g:python_host_prog` to point Nvim to a specific Python 2 interpreter: >
+    let g:python_host_prog = '/path/to/python'
+<
+						*g:python3_host_prog*
+Set `g:python3_host_prog` to point Nvim to a specific Python 3 interpreter: >
+    let g:python3_host_prog = '/path/to/python3'
+<
+						*g:loaded_python_provider*
+To disable Python 2 support: >
+    let g:loaded_python_provider = 1
+<
+						*g:loaded_python3_provider*
+To disable Python 3 support: >
+    let g:loaded_python3_provider = 1
+<
+						*g:python_host_skip_check*
+Set `g:python_host_skip_check` to disable the Python 2 interpreter check.
+Note: This requires you to install the python-neovim module properly. >
+    let g:python_host_skip_check = 1
+<
+						*g:python3_host_skip_check*
+Set `g:python3_host_skip_check` to disable the Python 3 interpreter check.
+Note: This requires you to install the python3-neovim module properly. >
+    let g:python3_host_skip_check = 1
+
+
+TROUBLESHOOTING					*python-trouble*
+
+If you have trouble with a plugin that uses the `neovim` Python client, use
+the |:CheckHealth| command to diagnose your setup.
+
+								 *:CheckHealth*
+:CheckHealth[!]	  Check your setup for common problems that may be keeping a
+		  plugin from functioning correctly.  Include the output of
+		  this command in bug reports to help reduce the amount of
+		  time it takes to address your issue.  With "!" the output
+		  will be placed in a new buffer which can make it easier to
+		  save to a file or copy to the clipboard.
+
+==============================================================================
+Clipboard integration 			      *provider-clipboard* *clipboard*
+
+Nvim has no direct connection to the system clipboard. Instead it is
+accessible through a |provider| which transparently uses shell commands for
+communicating with the clipboard.
+
+Clipboard access is implicitly enabled if any of the following clipboard tools
+are found in your `$PATH`.
+
+  - xclip
+  - xsel (newer alternative to xclip)
+  - pbcopy/pbpaste (Mac OS X)
+  - lemonade (for SSH) https://github.com/pocke/lemonade
+  - doitclient (for SSH) http://www.chiark.greenend.org.uk/~sgtatham/doit/
+
+The presence of a suitable clipboard tool implicitly enables the '+' and '*'
+registers.
+
+If you want to ALWAYS use the clipboard for ALL operations (as opposed
+to interacting with the '+' and/or '*' registers explicitly), set the
+following option:
+>
+    set clipboard+=unnamedplus
+<
+See 'clipboard' for details and more options.
+
+==============================================================================
+X11 selection mechanism			      *clipboard-x11* *x11-selection*
+
+The clipboard providers for X11 store text in what is known as "selections".
+Selections are "owned" by an application, so when the application is closed,
+the selection text is lost.
+
+The contents of selections are held by the originating application (e.g., upon
+a copy), and only passed on to another application when that other application
+asks for them (e.g., upon a paste).
+
+							      *quoteplus* *quote+*
+
+There are three documented X11 selections: `PRIMARY`, `SECONDARY`, and `CLIPBOARD`.
+`CLIPBOARD` is typically used in X11 applications for copy/paste operations
+(`Ctrl-c`/`v`), while `PRIMARY` is used for the last selected text, which is
+generally inserted with the middle mouse button.
+
+Nvim's X11 clipboard providers only utilize the `PRIMARY` and `CLIPBOARD`
+selections, used for the '*' and '+' registers, respectively.
+
+==============================================================================
+ vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/remote_plugin.txt b/runtime/doc/remote_plugin.txt
index 139fcd83b9..d906096a86 100644
--- a/runtime/doc/remote_plugin.txt
+++ b/runtime/doc/remote_plugin.txt
@@ -16,8 +16,8 @@ Nvim support for remote plugins 		  *remote-plugin*
 
 Extensibility is a primary goal of Nvim. Any programming language may be used
 to extend Nvim without changes to Nvim itself. This is achieved with remote
-plugins, coprocesses that have a direct communication channel (via
-|msgpack-rpc|) with the Nvim process.
+plugins, coprocesses that have a direct communication channel (via |RPC|) with
+the Nvim process.
 
 Even though these plugins run in separate processes they can call, be called,
 and receive events just as if the plugin's code were executed in the main
@@ -33,9 +33,9 @@ check whether a plugin host is available for their chosen programming language.
 
 Plugin hosts are programs that provide a high-level environment for plugins,
 taking care of most boilerplate involved in defining commands, autocmds, and
-functions that are implemented over |msgpack-rpc| connections. Hosts are
-loaded only when one of their registered plugins require it, keeping Nvim's
-startup as fast as possible, even if many plugins/hosts are installed.
+functions that are implemented over |RPC| connections. Hosts are loaded only
+when one of their registered plugins require it, keeping Nvim's startup as
+fast as possible, even if many plugins/hosts are installed.
 
 ==============================================================================
 3. Example					    *remote-plugin-example*
diff --git a/runtime/doc/spell.txt b/runtime/doc/spell.txt
index a767f6cbbf..0902d5d10f 100644
--- a/runtime/doc/spell.txt
+++ b/runtime/doc/spell.txt
@@ -1,4 +1,4 @@
-*spell.txt*	For Vim version 7.4.  Last change: 2016 Jan 08
+*spell.txt*
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -11,10 +11,6 @@ Spell checking						*spell*
 3. Generating a spell file	|spell-mkspell|
 4. Spell file format		|spell-file-format|
 
-Note: There also is a vimspell plugin.  If you have it you can do ":help
-vimspell" to find about it.  But you will probably want to get rid of the
-plugin and use the 'spell' option instead, it works better.
-
 ==============================================================================
 1. Quick start					*spell-quickstart* *E756*
 
@@ -1633,4 +1629,111 @@ WORDCHARS	(Hunspell)				*spell-WORDCHARS*
 		is no need to separate words before checking them (using a
 		trie instead of a hashtable).
 
+==============================================================================
+5. Spell checker design					*develop-spell*
+
+When spell checking was going to be added to Vim a survey was done over the
+available spell checking libraries and programs.  Unfortunately, the result
+was that none of them provided sufficient capabilities to be used as the spell
+checking engine in Vim, for various reasons:
+
+- Missing support for multi-byte encodings.  At least UTF-8 must be supported,
+  so that more than one language can be used in the same file.
+  Doing on-the-fly conversion is not always possible (would require iconv
+  support).
+- For the programs and libraries: Using them as-is would require installing
+  them separately from Vim.  That's mostly not impossible, but a drawback.
+- Performance: A few tests showed that it's possible to check spelling on the
+  fly (while redrawing), just like syntax highlighting.  But the mechanisms
+  used by other code are much slower.  Myspell uses a hashtable, for example.
+  The affix compression that most spell checkers use makes it slower too.
+- For using an external program like aspell a communication mechanism would
+  have to be setup.  That's complicated to do in a portable way (Unix-only
+  would be relatively simple, but that's not good enough).  And performance
+  will become a problem (lots of process switching involved).
+- Missing support for words with non-word characters, such as "Etten-Leur" and
+  "et al.", would require marking the pieces of them OK, lowering the
+  reliability.
+- Missing support for regions or dialects.  Makes it difficult to accept
+  all English words and highlight non-Canadian words differently.
+- Missing support for rare words.  Many words are correct but hardly ever used
+  and could be a misspelled often-used word.
+- For making suggestions the speed is less important and requiring to install
+  another program or library would be acceptable.  But the word lists probably
+  differ, the suggestions may be wrong words.
+
+
+Spelling suggestions				*develop-spell-suggestions*
+
+For making suggestions there are two basic mechanisms:
+1. Try changing the bad word a little bit and check for a match with a good
+   word.  Or go through the list of good words, change them a little bit and
+   check for a match with the bad word.  The changes are deleting a character,
+   inserting a character, swapping two characters, etc.
+2. Perform soundfolding on both the bad word and the good words and then find
+   matches, possibly with a few changes like with the first mechanism.
+
+The first is good for finding typing mistakes.  After experimenting with
+hashtables and looking at solutions from other spell checkers the conclusion
+was that a trie (a kind of tree structure) is ideal for this.  Both for
+reducing memory use and being able to try sensible changes.  For example, when
+inserting a character only characters that lead to good words need to be
+tried.  Other mechanisms (with hashtables) need to try all possible letters at
+every position in the word.  Also, a hashtable has the requirement that word
+boundaries are identified separately, while a trie does not require this.
+That makes the mechanism a lot simpler.
+
+Soundfolding is useful when someone knows how the words sounds but doesn't
+know how it is spelled.  For example, the word "dictionary" might be written
+as "daktonerie".  The number of changes that the first method would need to
+try is very big, it's hard to find the good word that way.  After soundfolding
+the words become "tktnr" and "tkxnry", these differ by only two letters.
+
+To find words by their soundfolded equivalent (soundalike word) we need a list
+of all soundfolded words.  A few experiments have been done to find out what
+the best method is.  Alternatives:
+1. Do the sound folding on the fly when looking for suggestions.  This means
+   walking through the trie of good words, soundfolding each word and
+   checking how different it is from the bad word.  This is very efficient for
+   memory use, but takes a long time.  On a fast PC it takes a couple of
+   seconds for English, which can be acceptable for interactive use.  But for
+   some languages it takes more than ten seconds (e.g., German, Catalan),
+   which is unacceptable slow.  For batch processing (automatic corrections)
+   it's too slow for all languages.
+2. Use a trie for the soundfolded words, so that searching can be done just
+   like how it works without soundfolding.  This requires remembering a list
+   of good words for each soundfolded word.  This makes finding matches very
+   fast but requires quite a lot of memory, in the order of 1 to 10 Mbyte.
+   For some languages more than the original word list.
+3. Like the second alternative, but reduce the amount of memory by using affix
+   compression and store only the soundfolded basic word.  This is what Aspell
+   does.  Disadvantage is that affixes need to be stripped from the bad word
+   before soundfolding it, which means that mistakes at the start and/or end
+   of the word will cause the mechanism to fail.  Also, this becomes slow when
+   the bad word is quite different from the good word.
+
+The choice made is to use the second mechanism and use a separate file.  This
+way a user with sufficient memory can get very good suggestions while a user
+who is short of memory or just wants the spell checking and no suggestions
+doesn't use so much memory.
+
+
+Word frequency
+
+For sorting suggestions it helps to know which words are common.  In theory we
+could store a word frequency with the word in the dictionary.  However, this
+requires storing a count per word.  That degrades word tree compression a lot.
+And maintaining the word frequency for all languages will be a heavy task.
+Also, it would be nice to prefer words that are already in the text.  This way
+the words that appear in the specific text are preferred for suggestions.
+
+What has been implemented is to count words that have been seen during
+displaying.  A hashtable is used to quickly find the word count.  The count is
+initialized from words listed in COMMON items in the affix file, so that it
+also works when starting a new file.
+
+This isn't ideal, because the longer Vim is running the higher the counts
+become.  But in practice it is a noticeable improvement over not using the word
+count.
+
  vim:tw=78:sw=4:ts=8:ft=help:norl:
diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index a2c0f45b23..97c04d54e0 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -220,7 +220,7 @@ g8			Print the hex values of the bytes used in the
 
 			Like |:enew|, it will fail if the current buffer is
 			modified, but can be forced with "!".  See |termopen()|
-			and |nvim-terminal-emulator| for more information.
+			and |terminal-emulator|.
 
 			To switch to terminal mode automatically:
 >
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 508712ca75..d30b0833db 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -12,8 +12,8 @@ these differences.
 
 1. Configuration		|nvim-configuration|
 2. Defaults			|nvim-defaults|
-3. Changed features		|nvim-features-changed|
-4. New features			|nvim-features-new|
+3. New features			|nvim-features|
+4. Changed features		|nvim-features-changed|
 5. Missing legacy features	|nvim-features-missing|
 6. Removed features		|nvim-features-removed|
 
@@ -58,7 +58,58 @@ these differences.
 - 'wildmenu' is set by default
 
 ==============================================================================
-3. Changed features					 *nvim-features-changed*
+3. New Features						       *nvim-features*
+
+
+MAJOR FEATURES ~
+
+Embedded terminal emulator	|terminal-emulator|
+Shared data			|shada|
+RPC API				|RPC|
+Job control			|job-control|
+Remote plugins			|remote-plugin|
+Python plugins			|provider-python|
+Clipboard integration		|provider-clipboard|
+
+
+OTHER FEATURES ~
+
+|bracketed-paste-mode| is built-in and enabled by default.
+
+Meta (alt) 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-$>, ...
+
+  Note: Meta chords are case-sensitive (<M-a> is distinguished from <M-A>).
+
+Some `CTRL-SHIFT-...` key chords are distinguished from `CTRL-...` variants
+(even in the terminal). Specifically, the following are known to work:
+  <C-Tab>, <C-S-Tab>
+  <C-BS>, <C-S-BS>
+  <C-Enter>, <C-S-Enter>
+
+Options:
+  'statusline' supports unlimited alignment sections
+
+Commands:
+  |:CheckHealth|
+
+Events:
+  |TabNew|
+  |TabNewEntered|
+  |TabClosed|
+  |TermOpen|
+  |TermClose|
+
+Highlight groups:
+  |hl-EndOfBuffer|
+  |hl-TermCursor|
+  |hl-TermCursorNC|
+
+==============================================================================
+4. 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"
@@ -68,7 +119,7 @@ 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|).
+|provider-python|).
 
 |mkdir()| behaviour changed:
 1. Assuming /tmp/foo does not exist and /tmp can be written to
@@ -141,39 +192,6 @@ Additional differences:
 - ShaDa file keeps search direction (|v:searchforward|), viminfo does not.
 
 ==============================================================================
-4. New Features						     *nvim-features-new*
-
-See |nvim-intro| for a list of Nvim's largest new features.
-
-|bracketed-paste-mode| is built-in and enabled by default.
-
-Meta (alt) 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-$>, ...
-
-  Note: Meta chords are case-sensitive (<M-a> is distinguished from <M-A>).
-
-Some `CTRL-SHIFT-...` key chords are distinguished from `CTRL-...` variants
-(even in the terminal). Specifically, the following are known to work:
-  <C-Tab>, <C-S-Tab>
-  <C-BS>, <C-S-BS>
-  <C-Enter>, <C-S-Enter>
-
-Events:
-  |TabNew|
-  |TabNewEntered|
-  |TabClosed|
-  |TermOpen|
-  |TermClose|
-
-Highlight groups:
-  |hl-EndOfBuffer|
-  |hl-TermCursor|
-  |hl-TermCursorNC|
-
-==============================================================================
 5. Missing legacy features				 *nvim-features-missing*
 				     *if_ruby* *if_lua* *if_perl* *if_mzscheme* *if_tcl*
 
diff --git a/src/nvim/version.c b/src/nvim/version.c
index c2e17b7377..5364fee953 100644
--- a/src/nvim/version.c
+++ b/src/nvim/version.c
@@ -1904,21 +1904,15 @@ void intro_message(int colon)
     N_("by Bram Moolenaar et al."),
     N_("Vim is open source and freely distributable"),
     "",
-    N_("First time using a vi-like editor?"),
-    N_("Type :Tutor<Enter> to get started!"),
+    N_("Type \":Tutor\" or \":help nvim\" to get started!"),
     "",
-    N_("Already know your way around Vim?"),
-    N_("See :help nvim-intro for an introduction to Neovim."),
+    N_("Still have questions? https://neovim.io/community"),
     "",
-    N_("Still have questions?"),
-    N_("Reach out to the Neovim community at neovim.io/community."),
+    N_("type  :q<Enter>               to exit         "),
+    N_("type  :help<Enter>  or  <F1>  for on-line help"),
     "",
     N_("Help poor children in Uganda!"),
     N_("type  :help iccf<Enter>       for information "),
-    "",
-    N_("type  :q<Enter>               to exit         "),
-    N_("type  :help<Enter>  or  <F1>  for on-line help"),
-    N_("type  :help nvim<Enter>       for Neovim help "),
   };
 
   // blanklines = screen height - # message lines