Merge pull request #1624 from Pyrohh/doc-fixes

doc: Misc. improvements to nvim-related docs

runtime/doc/nvim_clipboard.txt

@@ -6,25 +6,27 @@
 
 Clipboard integration for Nvim			       *nvim-clipboard*
 
-Nvim has no connection to the system clipboard, instead it is accessible
+Nvim has no direct connection to the system clipboard. Instead, it is
-through the |nvim-provider| infrastructure which transparently uses shell
+accessible through the |nvim-provider| infrastructure, which transparently
-commands for communicating with the clipboard.
+uses shell commands for communicating with the clipboard.
 
-To use clipboard on Nvim, make sure you have one of the following programs
+Clipboard access is implicitly enabled if any of the following clipboard tools
-installed and available on $PATH:
+is found in your `$PATH`.
 
 - xclip
-- xsel(newer alternative to xclip)
+- xsel (newer alternative to xclip)
-- pbcopy/pbpaste(already available on Mac OS X)
+- pbcopy/pbpaste (only for Mac OS X)
 
-Having any of these programs should enable the '+' and '*' registers. As an
+The presence of a suitable clipboard tool implicitly enables the '+' and '*'
-optional step, set the 'unnamedclip' option to transparently access clipboard
+registers.
-using the unnamed register. If you use the same |vimrc| for both Vim and Nvim,
+
-make sure you only set the option when `has('nvim')` is true:
+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:
 >
-    if has('nvim')
+    set clipboard+=unnamedplus
-      set unnamedclip
-    endif
 <
+See 'clipboard' for details and more options.
+
 ==============================================================================
  vim:tw=78:ts=8:noet:ft=help:norl:

runtime/doc/nvim_intro.txt

@@ -17,7 +17,7 @@ differentiate Nvim from Vim:
 2. Job control			|job-control|
 3. Python plugins		|nvim-python|
 4. Clipboard integration	|nvim-clipboard|
-5. Remote plugins	  	|remote-plugin|
+5. Remote plugins		|remote-plugin|
 6. Provider infrastructure	|nvim-provider|
 
 ==============================================================================

runtime/doc/nvim_provider.txt

@@ -25,7 +25,7 @@ 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: On the original Vim source code,
-clipboard functions account for more than 1k lines of C source code(and that
+clipboard functions account for more than 1k lines of C source code (and that
 is just on ui.c). All to peform two tasks that are now accomplished with
 simple shell commands such as xclip or pbcopy/pbpaste.
 
@@ -57,21 +57,20 @@ What these functions do is simple:
   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 
+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.
+|msgpack-rpc| clients (Nvim only) is easier to do in vimscript.
 
-Now, back to the python example. Instead of modifying vimscript to allow the
+Now, back to the python example. Instead of modifying vimscript to allow for
-definition of lowercase functions and commands(for the |:python|, |:pyfile|
+the definition of lowercase functions and commands (for the |:python|,
-and |:pydo| commands, and the |pyeval()| function), which would break
+|:pyfile|, and |:pydo| commands, and the |pyeval()| function), which would
-backwards compatibility with Vim, we implemented the
+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
+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.
+"think" it is running in a Vim compiled without |+python| feature.
-
 
 ==============================================================================
  vim:tw=78:ts=8:noet:ft=help:norl:

runtime/doc/nvim_python.txt

@@ -13,16 +13,16 @@ Python plugins and scripting in Nvim				  *nvim-python*
 1. Introduction						    *nvim-python-intro*
 
 Through an external python interpreter connected via |msgpack-rpc|, Nvim
-offers some support for the classic |python-vim| interface. For now only the
+offers some support for the legacy |python-vim| interface. For now only the
 old Vim 7.3 API is supported.
 
 ==============================================================================
 2. Quickstart					       *nvim-python-quickstart*
 
-If you just want to start using python plugins with Nvim quickly, here's a
+If you just want to start using Vim python plugins with Nvim quickly, here's a
-simple step-by-step:
+simple tutorial:
 
-- Make sure python 2.6 or 2.7 is available on your `$PATH`
+- Make sure python 2.6 or 2.7 is available in your `$PATH`
 - Install the `neovim` python package:
   >
       $ pip install neovim

runtime/doc/remote_plugin.txt

@@ -14,12 +14,12 @@ Nvim support for remote plugins 		  *remote-plugin*
 ==============================================================================
 1. Introduction					    *remote-plugin-intro*
 
-A big Nvim goal is to allow extensibility in arbitrary programming languages
+Extensibility is a primary goal of Nvim. Any programming language may be used
-without requiring direct support from the editor. This is achieved with
+to extend nvim without changes to nvim itself. This is achieved with remote
-remote plugins, coprocesses that have a direct communication channel(via
+plugins, coprocesses that have a direct communication channel (via
 |msgpack-rpc|) with the Nvim process.
 
-Even though these plugins are running in separate processes, they can call, be
+Even though these plugins are running in separate processes they can call, be
 called, and receive events just as if the code was being executed in the main
 process.
 
@@ -27,24 +27,24 @@ process.
 2. Plugin hosts					    *remote-plugin-hosts*
 
 While plugins can be implemented as arbitrary programs that communicate
-directly with Nvim API and are called via |rpcrequest()| and |rpcnotify()|,
+directly with the high-level Nvim API and are called via |rpcrequest()| and
-that is not the best approach available. Instead, developers should first
+|rpcnotify()|, that is not the best approach available. Instead, developers
-check if a plugin host implementation is available for their favorite
+should first check if a plugin host implementation is available for their
-programming language.
+chosen programming language.
 
 Plugin hosts are programs that provide a high level environment for plugins,
-and also take care of most boilerplate involved in defining commands, autocmds
+taking care of most boilerplate involved in defining commands, autocmds, and
-and functions that are implemented over msgpack-rpc connections. They are
+functions that are implemented over |msgpack-rpc| connections. Hosts are
-loaded the first time one of its registered plugins are required, keeping
+loaded only when one of their registered plugins require it, keeping Nvim's
-Nvim startup as fast a possible despite the number of installed plugins/hosts.
+startup as fast as possible if many plugins/hosts are installed.
 
 ==============================================================================
 3. Example					    *remote-plugin-example*
 
 The best way to learn about remote plugins is with an example, so let's see
-how a very useless python plugin looks like. This plugin exports a command, a
+what a python plugin looks like. This plugin exports a command, a function and
-function and an autocmd. The plugin is called 'Limit', and all it does is
+an autocmd. The plugin is called 'Limit', and all it does is limit the number
-limit the number of requests made to it. Here's the plugin source code:
+of requests made to it. Here's the plugin source code:
 >
     import neovim
 
@@ -53,7 +53,7 @@ limit the number of requests made to it. Here's the plugin source code:
         def __init__(self, vim):
             self.vim = vim
             self.calls = 0
-    
+
         @neovim.command('Cmd', range='', nargs='*', sync=True)
         def command_handler(self, args, range):
             self._increment_calls()
@@ -61,76 +61,75 @@ limit the number of requests made to it. Here's the plugin source code:
                 'Command: Called %d times, args: %s, range: %s' % (self.calls,
                                                                    args,
                                                                    range))
-    
+
         @neovim.autocmd('BufEnter', pattern='*.py', eval='expand("<afile>")',
                         sync=True)
         def autocmd_handler(self, filename):
             self._increment_calls()
             self.vim.current.line = (
                 'Autocmd: Called %s times, file: %s' % (self.calls, filename))
-    
+
         @neovim.function('Func')
         def function_handler(self, args):
             self._increment_calls()
             self.vim.current.line = (
                 'Function: Called %d times, args: %s' % (self.calls, args))
-    
+
         def _increment_calls(self):
             if self.calls == 5:
                 raise Exception('Too many calls!')
             self.calls += 1
 <
 
-As can be seen, the plugin is implemented using pure python idioms(classes,
+As can be seen, the plugin is implemented using pure python idioms (classes,
-methods and decorators), the translation between these language-specific
+methods, and decorators), the translation between these language-specific
-idioms to vimscript occurs while the plugin manifest is being generated(see
+idioms to vimscript occurs while the plugin manifest is being generated (see
 below).
 
 Notice that the exported command and autocmd are defined with the "sync" flag,
 which affects how Nvim calls the plugin: with "sync" the |rpcrequest()|
 function is used, which will block Nvim until the handler function returns a
 value. Without the "sync" flag, the call is made using a fire and forget
-approach with |rpcnotify()|(return values or exceptions raised in the handler
+approach with |rpcnotify()| (return values or exceptions raised in the handler
-function are ignored)
+function are ignored).
 
 To test the above plugin, it must be saved in "rplugin/python" in a
-'runtimepath' directory(~/.nvim/rplugin/python/limit.py for example).
+'runtimepath' directory (~/.nvim/rplugin/python/limit.py for example). Then,
-Then, the remote plugin manifest must be generated with
+the remote plugin manifest must be generated with `:UpdateRemotePlugins`.
-`:UpdateRemotePlugins`. 
 
 ==============================================================================
-4. remote plugin manifest			    *remote-plugin-manifest*
+4. Remote plugin manifest			    *remote-plugin-manifest*
 
-Just installing remote plugins to "rplugin/{host}" isn't enough to
+Just installing remote plugins to "rplugin/{host}" isn't enough for them to be
-load them at startup. The `:UpdateRemotePlugins`  command must be executed
+automatically loaded when required. The `:UpdateRemotePlugins` command must be
-every time a remote plugin is installed, updated, or deleted.
+executed every time a remote plugin is installed, updated, or deleted.
 
 `:UpdateRemotePlugins` will generate the remote plugin manifest, a special
 vimscript file containing declarations for all vimscript entities
 (commands/autocommands/functions) defined by all remote plugins, with each
 entity associated with the host and plugin path. The manifest can be seen as a
-generated extension to the user's vimrc(it even has the vimrc filename
+generated extension to the user's vimrc (it even has the vimrc filename
 prepended).
 
 The manifest declarations are nothing but calls to the remote#host#RegisterPlugin
 function, which will take care of bootstrapping the host as soon as the
-declared command, autocommand or function is used for the first time.
+declared command, autocommand, or function is used for the first time.
 
-The manifest generation step is necessary to keep editor startup fast in
+The manifest generation step is necessary to keep Nvim's startup fast in
-situations where a user has remote plugins with different hosts. For
+situations where a user has remote plugins with different hosts. For example,
-example, imagine a user that has three plugins, for python, java and .NET
+say a user has three plugins, for python, java and .NET hosts respectively. If
-hosts respectively, if we were to load all three plugins at startup, then
+we were to load all three plugins at startup, then three language runtimes
-three language runtimes would also be spawned which could take seconds!
+would also be spawned which could take seconds!
 
 With the manifest, each host will only be loaded when required. Continuing
-with the example, imagine the java plugin is a semantic completion engine for
+with the example, say the java plugin is a semantic completion engine for java
-java files, if it defines an BufEnter *.java autocommand then the java host
+source files. If it defines the autocommand "BufEnter *.java", then the java
-will only be spawned when java source files are loaded. 
+host will only be spawned when files ending with ".java" are loaded.
 
-If the explicit call to `:UpdateRemotePlugins` seems incovenient, try
+If the explicit call to `:UpdateRemotePlugins` seems incovenient, try to see
-to see it like this: Its a way to give IDE-like capabilities to nvim while
+it like this: It's a way to give IDE-like capabilities to nvim while still
-still keeping it a fast/lightweight editor for general use. It can also be
+keeping it fast and lightweight for general use. It can also be seen as
-seen as an analogous to the |:helptags| facility.
+analogous to the |:helptags| facility.
 
 ==============================================================================
  vim:tw=78:ts=8:noet:ft=help:norl: