From c698ed05310034d38192174d20da6926586be3ca Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Wed, 15 Jun 2016 00:42:17 -0400 Subject: doc: cleanup --- runtime/autoload/provider/python.vim | 2 +- runtime/autoload/provider/python3.vim | 2 +- runtime/doc/nvim.txt | 2 +- runtime/doc/nvim_provider.txt | 74 ----------------------------------- runtime/doc/provider.txt | 74 +++++++++++++++++++++++++++++++++++ 5 files changed, 77 insertions(+), 77 deletions(-) delete mode 100644 runtime/doc/nvim_provider.txt create mode 100644 runtime/doc/provider.txt (limited to 'runtime') diff --git a/runtime/autoload/provider/python.vim b/runtime/autoload/provider/python.vim index cb9d5c5296..b99a046375 100644 --- a/runtime/autoload/provider/python.vim +++ b/runtime/autoload/provider/python.vim @@ -1,5 +1,5 @@ " The Python provider uses a Python host to emulate an environment for running -" python-vim plugins. See ":help nvim-provider" for more information. +" python-vim plugins. See ":help provider". " " Associating the plugin with the Python host is the first step because plugins " will be passed as command-line arguments diff --git a/runtime/autoload/provider/python3.vim b/runtime/autoload/provider/python3.vim index f4a751e7a2..4f47a03a9b 100644 --- a/runtime/autoload/provider/python3.vim +++ b/runtime/autoload/provider/python3.vim @@ -1,5 +1,5 @@ " The Python3 provider uses a Python3 host to emulate an environment for running -" python3 plugins. See ":help nvim-provider" for more information. +" python3 plugins. See ":help provider". " " Associating the plugin with the Python3 host is the first step because " plugins will be passed as command-line arguments diff --git a/runtime/doc/nvim.txt b/runtime/doc/nvim.txt index 5f41b8611b..00740dbe93 100644 --- a/runtime/doc/nvim.txt +++ b/runtime/doc/nvim.txt @@ -17,7 +17,7 @@ see |help.txt|. 5. Python plugins |nvim-python| 6. Clipboard integration |clipboard| 7. Remote plugins |remote-plugin| -8. Provider infrastructure |nvim-provider| +8. Provider infrastructure |provider| 9. Integrated terminal emulator |terminal-emulator| ============================================================================== diff --git a/runtime/doc/nvim_provider.txt b/runtime/doc/nvim_provider.txt deleted file mode 100644 index 09b3d5a3e7..0000000000 --- a/runtime/doc/nvim_provider.txt +++ /dev/null @@ -1,74 +0,0 @@ -*nvim_provider.txt* For Nvim. {Nvim} - - - NVIM REFERENCE MANUAL by Thiago de Arruda - - -Nvim provider infrastructure *nvim-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. - -============================================================================== - vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt new file mode 100644 index 0000000000..c139105f28 --- /dev/null +++ b/runtime/doc/provider.txt @@ -0,0 +1,74 @@ +*provider.txt* {Nvim} + + + 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. + +============================================================================== + vim:tw=78:ts=8:noet:ft=help:norl: -- cgit