1 files changed, 77 insertions, 0 deletions
diff --git a/runtime/doc/nvim_provider.txt b/runtime/doc/nvim_provider.txt
new file mode 100644
index 0000000000..e67a5c174c
--- /dev/null
+++ b/runtime/doc/nvim_provider.txt
@@ -0,0 +1,77 @@
+*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 |external-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 it's 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: On 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 peform 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 embed 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 severly compromising backwards compatibility with Vim.
+Thats where providers comes to rescue.
+
+In essence, this infrastructure 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 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: