doc/provider: cleanup

- Move design/impl discussion to develop.txt
- Move clipboard notes to provider.txt

4 files changed, 98 insertions, 129 deletions

diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index 25ae94f784..6641732679 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -912,8 +912,7 @@ TermClose			When a terminal buffer ends.
 						 {Nvim} *TermOpen*
 TermOpen			When a terminal buffer is starting.  This can
 				be used to configure the terminal emulator by
-				setting buffer variables.
-				See |nvim-terminal-emulator| for details.
+				setting buffer variables. |terminal-emulator|
 							*TermResponse*
 TermResponse			After the response to |t_RV| is received from
 				the terminal.  The value of |v:termresponse|
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 658de0dce9..4013544311 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -122,7 +122,7 @@ include the kitchen sink... but you can use it for plumbing."
 ==============================================================================
 2. Design decisions					*design-decisions*
 
-Naming the window
+Window
 
 The word "window" is commonly used for several things: A window on the screen,
 the xterm window, a window inside Vim to view a buffer.
@@ -137,6 +137,51 @@ window		View on a buffer.  There can be several windows in Vim,
 		together with the command line, menubar, toolbar, etc. they
 		fit in the shell.
 
+
+Providers 							*dev-provider*
+
+A goal of Nvim is to allow extension of the editor without special knowledge
+in the core. But some Vim components are too tightly coupled; in those cases
+a "provider" hook is exposed.
+
+Consider two examples of integration with external systems that are
+implemented in Vim and are now decoupled from Nvim core as providers:
+
+1. In the Vim source code, clipboard logic accounts for more than 1k lines of
+   C source code (ui.c), to perform two tasks that are now accomplished with
+   shell commands such as xclip or pbcopy/pbpaste.
+
+2. Python scripting support: Vim has three files dedicated to embedding the
+   Python interpreter: if_python.c, if_python3.c and if_py_both.h. Together
+   these files sum about 9.5k lines of C source code. In contrast, Nvim Python
+   scripting is performed by an external host process implemented in ~2k lines
+   of Python.
+
+Ideally we could implement Python and clipboard integration in pure vimscript
+and without touching the C code. But this is infeasible without compromising
+backwards compatibility with Vim; that's where providers help.
+
+The provider framework helps call vimscript from C. It is composed of two
+functions in eval.c:
+
+- eval_call_provider(name, method, arguments): calls provider#(name)#Call
+  with the method and arguments.
+- eval_has_provider(name): Checks if a provider is implemented. Returns true
+  if the provider#(name)#Call function is implemented. Called by |has()|
+  (vimscript) to check if features are available.
+
+The provider#(name)#Call function implements integration with an external
+system, because calling shell commands and |rpc| clients are easier to work
+with in vimscript.
+
+For example, the Python provider is implemented by the
+autoload/provider/python.vim script; the provider#python#Call function is only
+defined if a valid external Python host is found. That works well with the
+`has('python')` expression (normally used by Python plugins) because if the
+Python host isn't installed then the plugin will "think" it is running in
+a Vim compiled without the |+python| feature.
+
+
 RPC API
 API client
 remote plugin
diff --git a/runtime/doc/nvim_clipboard.txt b/runtime/doc/nvim_clipboard.txt
deleted file mode 100644
index 9a747a1cf3..0000000000
--- a/runtime/doc/nvim_clipboard.txt
+++ /dev/null
@@ -1,61 +0,0 @@
-*nvim_clipboard.txt*    For Nvim.					{Nvim}
-
-
-		 NVIM REFERENCE MANUAL    by Thiago de Arruda
-
-
-Clipboard integration for Nvim					     *clipboard*
-
-1. Intro			|clipboard-intro|
-2. X11 selection mechanism	|clipboard-x11|
-
-==============================================================================
-1. Intro						       *clipboard-intro*
-
-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.
-
-==============================================================================
-2. X11 selection mechanism			   *clipboard-x11* *x11-selection*
-
-The clipboard providers for X11 store text in what is known as "selections".
-Selections are "owned" by an application, so when the application is closed,
-the selection text is lost.
-
-The contents of selections are held by the originating application (e.g., upon
-a copy), and only passed on to another application when that other application
-asks for them (e.g., upon a paste).
-
-							      *quoteplus* *quote+*
-
-There are three documented X11 selections: `PRIMARY`, `SECONDARY`, and `CLIPBOARD`.
-`CLIPBOARD` is typically used in X11 applications for copy/paste operations
-(`Ctrl-c`/`v`), while `PRIMARY` is used for the last selected text, which is
-generally inserted with the middle mouse button.
-
-Nvim's X11 clipboard providers only utilize the `PRIMARY` and `CLIPBOARD`
-selections, used for the '*' and '+' registers, respectively.
-
-==============================================================================
- vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt
index c139105f28..5c335a39ef 100644
--- a/runtime/doc/provider.txt
+++ b/runtime/doc/provider.txt
@@ -4,71 +4,57 @@
 		 NVIM REFERENCE MANUAL    by Thiago de Arruda
 
 
-Nvim provider infrastructure					    *provider*
-
-This document is for developers. If you are a normal user or plugin developer
-looking to learn about Nvim |rpc| for implementing plugins in other
-programming languages, see |remote-plugin|. For instructions on how to enable
-Python plugins, see |nvim-python|. For clipboard, see |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 |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.
+Providers	 						    *provider*
+
+Nvim delegates some features to dynamic "providers".
+
+==============================================================================
+Clipboard integration 						   *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: