Merge #4923 from justinmk/doc

doc: cleanup
2025-10-01 07:28:34 +00:00 · 2016-06-16 01:48:05 -04:00
parent 1b1be69cd6 464bc16f81
commit 51fe40a033
27 changed files with 647 additions and 1189 deletions
--- 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
+    -u NONE -i NONE -e --headless -c "helptags ++t doc" -c quit
    -i NONE
    -e
    --headless
    -c "helptags ++t ."
    -c quit
  DEPENDS
    copy_docfiles
    nvim
-  WORKING_DIRECTORY "${GENERATED_RUNTIME_DIR}/doc"
+  WORKING_DIRECTORY "${GENERATED_RUNTIME_DIR}"
 )
 add_custom_command(OUTPUT ${GENERATED_HELP_TAGS}
--- 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
--- 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
--- 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
--- 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]
--- 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|
+C API for Nvim							   *API* *api*
-2. API Types			|nvim-api-types|
+
-3. API metadata			|nvim-api-metadata|
+1. Introduction			|api-intro|
-4. Buffer highlighting		|nvim-api-highlights|
+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
+Nvim exposes a public API for external code to interact with the Nvim core. In
-the NVim core. In the present version of Nvim the API is primarily used by
+the present version of Nvim the API is primarily used by external processes to
-external processes to interact with Nvim using the msgpack-rpc protocol, see
+interact with Nvim using the msgpack-rpc protocol, see |msgpack-rpc|. The API
-|msgpack-rpc|. The API will also be used from vimscript to access new Nvim core
+will also be used from vimscript to access new Nvim core features, but this is
-features, but this is not implemented yet. Later on, Nvim might be embeddable
+not implemented yet. Later on, Nvim might be embeddable in C applications as
-in C applications as libnvim, and the application will then control the
+libnvim, and the application will then control the embedded instance by
-embedded instance by calling the C API directly.
+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
+This metadata is mostly useful for external programs accessing the API via
-msgpack-api, see |msgpack-rpc-api|.
+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
--- 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.
+				setting buffer variables. |terminal-emulator|
 				See |nvim-terminal-emulator| for details.
 							*TermResponse*
 TermResponse			After the response to |t_RV| is received from
 				the terminal.  The value of |v:termresponse|
--- 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
--- 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*
+Development of Nvim.					*development*
 This text is important for those who want to be involved in further developing
 Vim.
 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
+Nvim is open source software.  Everybody is encouraged to contribute.
-code.
+    https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md
-Vim is open source software.  Everybody is encouraged to contribute to help
+See src/nvim/README.md for a high-level overview of the source code:
-improving Vim.  For sending patches a context diff "diff -c" is preferred.
+    https://github.com/neovim/neovim/blob/master/src/nvim/README.md
 Also see http://vim.wikia.com/wiki/How_to_make_and_submit_a_patch.
 ==============================================================================
 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
+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
+tools or hosted as a component. Marvim once said: "Unlike Emacs, Nvim does not
-not attempt to include everything but the kitchen sink, but some people use it
+include the kitchen sink... but you can use it for plumbing."
 for plumbing."
 ==============================================================================
 2. Design decisions					*design-decisions*
-Folding
+Window
 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
 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*
+Providers 							*dev-provider*
-When spell checking was going to be added to Vim a survey was done over the
+A goal of Nvim is to allow extension of the editor without special knowledge
-available spell checking libraries and programs.  Unfortunately, the result
+in the core. But some Vim components are too tightly coupled; in those cases
-was that none of them provided sufficient capabilities to be used as the spell
+a "provider" hook is exposed.
 checking engine in Vim, for various reasons:
- Missing support for multi-byte encodings.  At least UTF-8 must be supported,
+Consider two examples of integration with external systems that are
-  so that more than one language can be used in the same file.
+implemented in Vim and are now decoupled from Nvim core as providers:
-  Doing on-the-fly conversion is not always possible (would require iconv
+
-  support).
+1. In the Vim source code, clipboard logic accounts for more than 1k lines of
- For the programs and libraries: Using them as-is would require installing
+   C source code (ui.c), to perform two tasks that are now accomplished with
-  them separately from Vim.  That's mostly not impossible, but a drawback.
+   shell commands such as xclip or pbcopy/pbpaste.
- Performance: A few tests showed that it's possible to check spelling on the
+
-  fly (while redrawing), just like syntax highlighting.  But the mechanisms
+2. Python scripting support: Vim has three files dedicated to embedding the
-  used by other code are much slower.  Myspell uses a hashtable, for example.
+   Python interpreter: if_python.c, if_python3.c and if_py_both.h. Together
-  The affix compression that most spell checkers use makes it slower too.
+   these files sum about 9.5k lines of C source code. In contrast, Nvim Python
- For using an external program like aspell a communication mechanism would
+   scripting is performed by an external host process implemented in ~2k lines
-  have to be setup.  That's complicated to do in a portable way (Unix-only
+   of Python.
-  would be relatively simple, but that's not good enough).  And performance
+
-  will become a problem (lots of process switching involved).
+Ideally we could implement Python and clipboard integration in pure vimscript
- Missing support for words with non-word characters, such as "Etten-Leur" and
+and without touching the C code. But this is infeasible without compromising
-  "et al.", would require marking the pieces of them OK, lowering the
+backwards compatibility with Vim; that's where providers help.
-  reliability.
+
- Missing support for regions or dialects.  Makes it difficult to accept
+The provider framework helps call vimscript from C. It is composed of two
-  all English words and highlight non-Canadian words differently.
+functions in eval.c:
- Missing support for rare words.  Many words are correct but hardly ever used
+
-  and could be a misspelled often-used word.
+- eval_call_provider(name, method, arguments): calls provider#(name)#Call
- For making suggestions the speed is less important and requiring to install
+  with the method and arguments.
-  another program or library would be acceptable.  But the word lists probably
+- eval_has_provider(name): Checks if a provider is implemented. Returns true
-  differ, the suggestions may be wrong words.
+  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.
-Spelling suggestions				*develop-spell-suggestions*
+RPC API
-
+API client
-For making suggestions there are two basic mechanisms:
+remote plugin
 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:ts=8:ft=help:norl:
--- 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
+		|$NVIM_LISTEN_ADDRESS| on startup. |serverstop()|
 		latter is modified or unset. |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}
+				Sends an |RPC| request to {channel}
-rpcstart({prog}[, {argv}])	Spawns {prog} and opens a |msgpack-rpc| channel
+rpcstart({prog}[, {argv}])	Spawns {prog} and opens an |RPC| channel
-rpcstop({channel})		Closes a |msgpack-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
+		Sends {event} to {channel} via |RPC| and returns immediately.
-		immediately. If {channel} is 0, the event is broadcast to all
+		If {channel} is 0, the event is broadcast to all channels.
-		channels. Example: >
+		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
+		and opens an |RPC| channel with the spawned process's
-		stdin/stdout. It returns:
+		stdin/stdout. Returns:
-		  - The channel id on success, which is used by |rpcrequest()|,
+		  - 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|
--- 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
--- a/runtime/doc/gui_w32.txt
+++ b/runtime/doc/gui_w32.txt
@@ -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:
--- 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*
--- 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|
+1. Introduction			|rpc-intro|
-2. API mapping			|msgpack-rpc-api|
+2. API mapping			|rpc-api|
-3. Connecting			|msgpack-rpc-connecting|
+3. Connecting			|rpc-connecting|
-4. Clients			|msgpack-rpc-clients|
+4. Clients			|rpc-client|
-5. Types			|msgpack-rpc-types|
+5. Types			|rpc-types|
-6. Wrapping methods		|msgpack-rpc-wrap-methods|
+6. Vimscript functions		|rpc-vim-functions|
 7. Vimscript functions		|msgpack-rpc-vim-functions|
 ==============================================================================
-1. Introduction						    *msgpack-rpc-intro*
+1. Introduction						            *rpc-intro*
-The primary way to control a running Nvim instance is through
+The primary way to control Nvim programmatically is the RPC API, which speaks
-MessagePack-RPC, a messaging protocol that uses the MessagePack serialization
+MessagePack-RPC ("msgpack-rpc"), a messaging protocol that uses the
-format: https://github.com/msgpack/msgpack/blob/7498cf3/spec.md.
+MessagePack serialization format:
-From now on, we refer to the protocol as msgpack-rpc.
+  https://github.com/msgpack/msgpack/blob/0b8f5ac/spec.md
-At this point, only plugins use msgpack-rpc, but eventually even user
+All kinds of Nvim "clients" use the RPC API: user interfaces (GUIs), remote
-interaction will happen through it, since user interfaces will be separate
+plugins, scripts like "nvr" (https://github.com/mhinz/neovim-remote), and even
-programs that control a headless Nvim instance.
+`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
+The RPC API is like a more powerful version of Vim's `clientserver` feature.
 - 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.
 ==============================================================================
-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
+The Nvim C |API| is automatically exposed to the RPC API by the build system,
-interface by the build system, which parses headers at src/nvim/api from the
+which parses headers at src/nvim/api/*. A dispatch function is generated which
-project root. A dispatch function is generated, which matches msgpack-rpc method
+matches RPC API method names with public API functions, converting/validating
-names with non-static API functions, converting/validating arguments and return
+arguments and return values back to msgpack.
 values back to msgpack.
-Client libraries will normally provide wrappers that hide msgpack-rpc details
+Client libraries (|api-client|s) normally provide wrappers that hide
-from programmers. The wrappers can be automatically generated by reading
+msgpack-rpc details from application developers. The wrappers can be
-bundled API metadata from a compiled Nvim instance.
+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`
+  1. Connect to a running Nvim instance and call `vim_get_api_info` via
-   via msgpack-rpc. This is best for clients written in dynamically-typed
+     msgpack-rpc. This is best for clients written in dynamic languages which
-   languages, which can define functions at runtime.
+     can define functions at runtime.
-2. By starting Nvim with the `--api-info` command-line option, which makes Nvim
+  2. Start Nvim with the `--api-info` command-line option, which dumps a blob
-   dump a blob of msgpack metadata to standard output and exit. This is best
+     of msgpack metadata to standard output. This is useful for clients
-   for clients written in statically-typed languages, which require a separate
+     written in statically-compiled languages.
   compilation step.
-Here's a simple way to get human-readable description of the API (requires
+To get a human-readable list of API functions: >
-Python and the `pyyaml`/`msgpack-python` pip packages):
+    :new|put =map(msgpackparse(systemlist('nvim --api-info'))[0].functions, 'v:val.name._VAL[0]')
->
+<
-    nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))' > api.yaml
+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.
+  1. Through stdin/stdout when `nvim` is started with `--embed`. This is how
-   This is how other programs can embed Nvim.
+     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. The socket
-3. Through the socket automatically created with each instance. To get the
+     location is stored in |v:servername|.
   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|.
-4. Through a TCP/IP socket. To make Nvim listen on a TCP/IP socket, set the
+  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:
+     |$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
+Connecting to the socket is the easiest way a programmer can test the API,
-can be done through any msgpack-rpc client library or fully-featured Nvim client
+which can be done through any msgpack-rpc client library or full-featured
-(which we'll see in the next section). Here's a Ruby script that prints 'hello
+|api-client|. Here's a Ruby script that prints 'hello world!' in the current
-world!' in the current Nvim instance:
+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*
+4. Implementing API clients			*rpc-api-client* *api-client*
-Nvim is still in alpha, so there's no in-depth documentation explaining how to
+All external UIs and remote plugins (as opposed to regular Vim plugins) are
-properly implement a client library yet. The Python client (the pip package
+"clients" in general; but we call something an "API client" if its purpose is
-"neovim") will always be up-to-date with the latest API changes, so its source
+to abstract or wrap the RPC API for the convenience of other applications
-code is the best documentation currently available. There are some guidelines
+(just like a REST client or SDK such as boto3 for AWS: you can speak AWS REST
-however:
+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
- Separate the transport layer from the rest of the library. See
+The Python client (pip package "neovim") is the reference implementation of an
-  |msgpack-rpc-connecting| for details on how clients can connect to Nvim.
+API client. It is always up-to-date with the Nvim API, so its source code and
- Use a MessagePack library that implements at least version 5 of the
+test suite are an authoritative reference.
-  MessagePack spec, which supports the `bin` and `ext` types used by Nvim.
+    https://github.com/neovim/python-client
 - 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
+API client implementation guidelines ~
 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:
  - 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|.
+The Nvim C API uses custom types for all functions. |api-types|
-For the purpose of mapping to msgpack, he types can be split into two groups:
+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
+  - Basic types that map natively to msgpack (and probably have a default
-  representation in msgpack-supported programming languages)
+    representation in msgpack-supported programming languages)
- Special Nvim types that map to msgpack EXT with custom type codes.
+  - Special Nvim types that map to msgpack EXT with custom type codes.
-Basic type mapping:
+Basic types ~
-Nil				  -> msgpack nil
+  Nil                               -> msgpack nil
-Boolean				  -> msgpack boolean
+  Boolean                           -> msgpack boolean
-Integer (signed 64-bit integer)	  -> msgpack integer
+  Integer (signed 64-bit integer)   -> msgpack integer
-Float (IEEE 754 double precision) -> msgpack float
+  Float (IEEE 754 double precision) -> msgpack float
-String				  -> msgpack string
+  String                            -> msgpack string
-Array				  -> msgpack array
+  Array                             -> msgpack array
-Dictionary			  -> msgpack map
+  Dictionary                        -> msgpack map
-Special Nvim types that use msgpack EXT:
+Special types (msgpack EXT) ~
-Buffer				  -> enum value kObjectTypeBuffer
+  Buffer                            -> enum value kObjectTypeBuffer
-Window				  -> enum value kObjectTypeWindow
+  Window                            -> enum value kObjectTypeWindow
-Tabpage				  -> enum value kObjectTypeTabpage
+  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
+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
+the type codes, because a client may be built against one Nvim version but
-to another with different type codes.
+connect to another with different type codes.
 ==============================================================================
-6. Wrapping methods				     *msgpack-rpc-wrap-methods*
+6. Vimscript functions				           *rpc-vim-functions*
-As mentioned before, clients should provide an API that hides msgpack-rpc
+RPC functions are available in Vimscript:
 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
+  1. |rpcstart()|: Similarly to |jobstart()|, this will spawn a co-process
-  functions.
+     with its standard handles connected to Nvim. The difference is that it's
- Each function metadata object has type information about the return value
+     not possible to process raw data to or from the process's stdin, stdout,
-  and parameters. These can be used for generating strongly-typed APIs in
+     or stderr.  This is because the job's stdin and stdout are used as
-  static languages.
+     a single msgpack channel that is processed directly by Nvim.
- Container types may be decorated with type/size constraints, e.g.
+  2. |rpcstop()|: Same as |jobstop()|, but operates on handles returned by
-  ArrayOf(Buffer) or ArrayOf(Integer, 2). This can be useful to generate even
+     |rpcstart()|.
-  more strongly-typed APIs.
+  3. |rpcrequest()|: Sends a msgpack-rpc request to the process.
- Methods that operate instances of Nvim's types are prefixed with the type
+  4. |rpcnotify()|: Sends a msgpack-rpc notification to the process.
  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
+|rpcrequest()| and |rpcnotify()| can also be used with channels connected to
-that represent Nvim's types, and the methods of each class could be defined
+a nvim server. |v:servername|
 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|.
 ==============================================================================
 vim:tw=78:ts=8:noet:ft=help:norl:
--- 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.
+If you are new to Vim (and Nvim) see |help.txt| or type ":Tutor".
-It is not meant for Vim beginners. For a basic introduction to Vim,
+If you already use Vim (but not Nvim) see |nvim-from-vim| for a quickstart.
 see |help.txt|.
-1. Transitioning from Vim	 |nvim-from-vim|
+Nvim is emphatically a fork of Vim, not a clone: compatibility with Vim is
-2. Differences from Vim		 |vim-differences|
+maintained where possible. See |vim_diff.txt| for the complete reference of
-3. Msgpack-RPC			 |msgpack-rpc|
+differences from Vim.
-4. Job control			 |job-control|
+
-5. Python plugins		 |nvim-python|
+==============================================================================
-6. Clipboard integration	 |nvim-clipboard|
+Transitioning from Vim				*nvim-from-vim*
-7. Remote plugins		 |remote-plugin|
+
-8. Provider infrastructure	 |nvim-provider|
+To start the transition, link your previous configuration so Nvim can use it:
-9. Integrated terminal emulator	 |nvim-terminal-emulator|
+>
    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:
--- a/runtime/doc/nvim_clipboard.txt
+++ b/runtime/doc/nvim_clipboard.txt
@@ -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:
--- a/runtime/doc/nvim_from_vim.txt
+++ b/runtime/doc/nvim_from_vim.txt
@@ -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:
--- a/runtime/doc/nvim_provider.txt
+++ b/runtime/doc/nvim_provider.txt
@@ -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:
--- a/runtime/doc/nvim_python.txt
+++ b/runtime/doc/nvim_python.txt
@@ -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:
--- 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|
+1. Introduction			|terminal-emulator-intro|
-2. Spawning			|nvim-terminal-emulator-spawning|
+2. Spawning			|terminal-emulator-spawning|
-3. Input			|nvim-terminal-emulator-input|
+3. Input			|terminal-emulator-input|
-4. Configuration		|nvim-terminal-emulator-configuration|
+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
+Nvim offers a mostly complete VT220/xterm terminal emulator. The terminal is
-complete VT220/xterm-like terminal emulator. The terminal is presented to the
+presented as a special buffer type, asynchronously updated to mirror the
-user as a special buffer type, one that is asynchronously updated to mirror
+virtual terminal display as data is received from the program connected to it.
-the virtual terminal display as data is received from the program connected
+For most purposes, terminal buffers behave a lot like normal buffers with
-to it. For most purposes, terminal buffers behave a lot like normal buffers
+'nomodifiable' set.
 with 'nomodifiable' set.
-
+The implementation is powered by libvterm, a powerful abstract terminal
-The implementation is powered by libvterm[1], a powerful abstract terminal
+emulation library. http://www.leonerd.org.uk/code/libvterm/
 emulation library.
 [1]: 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):
--- 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
+			terminal is created. |terminal-emulator|
 			more information.
 	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,
--- a/runtime/doc/provider.txt
+++ 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:
--- 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
+plugins, coprocesses that have a direct communication channel (via |RPC|) with
-|msgpack-rpc|) with the Nvim process.
+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
+functions that are implemented over |RPC| connections. Hosts are loaded only
-loaded only when one of their registered plugins require it, keeping Nvim's
+when one of their registered plugins require it, keeping Nvim's startup as
-startup as fast as possible, even if many plugins/hosts are installed.
+fast as possible, even if many plugins/hosts are installed.
 ==============================================================================
 3. Example					    *remote-plugin-example*
--- 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:
--- 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:
 >
--- 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|
+3. New features			|nvim-features|
-4. New features			|nvim-features-new|
+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
@@ -140,39 +191,6 @@ Additional differences:
  itself.
 - 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*
--- 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\" or \":help nvim\" to get started!"),
    N_("Type :Tutor<Enter> to get started!"),
    "",
-    N_("Already know your way around Vim?"),
+    N_("Still have questions? https://neovim.io/community"),
    N_("See :help nvim-intro for an introduction to Neovim."),
    "",
    N_("Still have questions?"),
    N_("Reach out to the Neovim community at neovim.io/community."),
    "",
    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 "),
+    "",
    N_("Help poor children in Uganda!"),
    N_("type  :help iccf<Enter>       for information "),
  };
  // blanklines = screen height - # message lines