diff options
| -rw-r--r-- | runtime/doc/autocmd.txt | 3 | ||||
| -rw-r--r-- | runtime/doc/develop.txt | 47 | ||||
| -rw-r--r-- | runtime/doc/nvim_clipboard.txt | 61 | ||||
| -rw-r--r-- | runtime/doc/provider.txt | 116 |
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: |