IntenseFinance/neovim
3
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-02-25 18:55:25 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge #4923 from justinmk/doc

Browse Source 
doc: cleanup
This commit is contained in:
Justin M. Keyes 2016-06-16 01:48:05 -04:00 committed by GitHub
commit 51fe40a033
27 changed files with 647 additions and 1189 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
runtime/CMakeLists.txt
View File

@ -26,23 +26,15 @@ foreach(DF ${DOCFILES})
list(APPEND BUILDDOCFILES ${GENERATED_RUNTIME_DIR}/doc/${F})
endforeach()
add_custom_command(OUTPUT copy_docfiles
COMMAND ${CMAKE_COMMAND} -E copy_directory
${PROJECT_SOURCE_DIR}/runtime/doc ${GENERATED_RUNTIME_DIR}/doc
)
add_custom_target(helptags
COMMAND ${CMAKE_COMMAND} -E remove_directory ${GENERATED_RUNTIME_DIR}/doc
COMMAND ${CMAKE_COMMAND} -E copy_directory
${PROJECT_SOURCE_DIR}/runtime/doc ${GENERATED_RUNTIME_DIR}/doc
COMMAND "${PROJECT_BINARY_DIR}/bin/nvim"
-u NONE
-i NONE
-e
--headless
-c "helptags ++t ."
-c quit
-u NONE -i NONE -e --headless -c "helptags ++t doc" -c quit
DEPENDS
copy_docfiles
nvim
WORKING_DIRECTORY "${GENERATED_RUNTIME_DIR}/doc"
WORKING_DIRECTORY "${GENERATED_RUNTIME_DIR}"
)
add_custom_command(OUTPUT ${GENERATED_HELP_TAGS}

2
runtime/autoload/provider/clipboard.vim
View File

@ -58,7 +58,7 @@ elseif executable('doitclient')
let s:copy['*'] = s:copy['+']
let s:paste['*'] = s:paste['+']
else
echom 'clipboard: No clipboard tool available. See :help nvim-clipboard'
echom 'clipboard: No clipboard tool available. See :help clipboard'
finish
endif

2
runtime/autoload/provider/python.vim
View File

@ -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

2
runtime/autoload/provider/python3.vim
View File

@ -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

2
runtime/autoload/provider/pythonx.vim
View File

@ -106,7 +106,7 @@ function! s:check_interpreter(prog, major_ver, skip) abort
if v:shell_error == 2
return [0, prog_path . ' does not have the neovim module installed. '
\ . 'See ":help nvim-python".']
\ . 'See ":help provider-python".']
elseif v:shell_error == 127
" This can happen with pyenv's shims.
return [0, prog_path . ' does not exist: ' . prog_ver]

41
runtime/doc/api.txt
View File

@ -1,31 +1,32 @@
*api.txt* For Nvim. {Nvim}
*api.txt* {Nvim}
NVIM REFERENCE MANUAL by Thiago de Arruda
The C API of Nvim *nvim-api*
1. Introduction |nvim-api-intro|
2. API Types |nvim-api-types|
3. API metadata |nvim-api-metadata|
4. Buffer highlighting |nvim-api-highlights|
C API for Nvim *API* *api*
1. Introduction |api-intro|
2. API Types |api-types|
3. API metadata |api-metadata|
4. Buffer highlighting |api-highlights|
==============================================================================
1. Introduction *nvim-api-intro*
1. Introduction *api-intro*
Nvim defines a C API as the primary way for external code to interact with
the NVim core. In the present version of Nvim the API is primarily used by
external processes to interact with Nvim using the msgpack-rpc protocol, see
|msgpack-rpc|. The API will also be used from vimscript to access new Nvim core
features, but this is not implemented yet. Later on, Nvim might be embeddable
in C applications as libnvim, and the application will then control the
embedded instance by calling the C API directly.
Nvim exposes a public API for external code to interact with the Nvim core. In
the present version of Nvim the API is primarily used by external processes to
interact with Nvim using the msgpack-rpc protocol, see |msgpack-rpc|. The API
will also be used from vimscript to access new Nvim core features, but this is
not implemented yet. Later on, Nvim might be embeddable in C applications as
libnvim, and the application will then control the embedded instance by
calling the C API directly.
==============================================================================
2. API Types *nvim-api-types*
2. API Types *api-types*
Nvim's C API uses custom types for all functions. Some are just typedefs
around C99 standard types, and some are Nvim defined data structures.
around C99 standard types, and some are Nvim-defined data structures.
Boolean -> bool
Integer (signed 64-bit integer) -> int64_t
@ -46,7 +47,7 @@ Window -> enum value kObjectTypeWindow
Tabpage -> enum value kObjectTypeTabpage
==============================================================================
3. API metadata *nvim-api-metadata*
3. API metadata *api-metadata*
Nvim exposes metadata about the API as a Dictionary with the following keys:
@ -54,11 +55,11 @@ functions calling signature of the API functions
types The custom handle types defined by Nvim
error_types The possible kinds of errors an API function can exit with.
This metadata is mostly useful for external programs accessing the api over
msgpack-api, see |msgpack-rpc-api|.
This metadata is mostly useful for external programs accessing the API via
RPC, see |rpc-api|.
==============================================================================
4. Buffer highlighting *nvim-api-highlights*
4. Buffer highlighting *api-highlights*
Nvim allows plugins to add position-based highlights to buffers. This is
similar to |matchaddpos()| but with some key differences. The added highlights

3
runtime/doc/autocmd.txt
View File

@ -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|

2
runtime/doc/change.txt
View File

@ -1250,7 +1250,7 @@ register.
Use these registers for storing and retrieving the selected text for the GUI.
See |quotestar| and |quoteplus|. When the clipboard is not available or not
working, the unnamed register is used instead. For Unix systems and Mac OS X,
see |nvim-clipboard|.
see |primary-selection|.
9. Black hole register "_ *quote_*
When writing to this register, nothing happens. This can be used to delete

201
runtime/doc/develop.txt
View File

@ -1,23 +1,19 @@
*develop.txt* For Vim version 7.4. Last change: 2016 Jan 31
*develop.txt*
VIM REFERENCE MANUAL by Bram Moolenaar
NVIM REFERENCE MANUAL
Development of Vim. *development*
This text is important for those who want to be involved in further developing
Vim.
Development of Nvim. *development*
1. Design goals |design-goals|
2. Design decisions |design-decisions|
See the file "src/nvim/README.md" for a high-level overview of the source
code.
Nvim is open source software. Everybody is encouraged to contribute.
https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md
Vim is open source software. Everybody is encouraged to contribute to help
improving Vim. For sending patches a context diff "diff -c" is preferred.
Also see http://vim.wikia.com/wiki/How_to_make_and_submit_a_patch.
See src/nvim/README.md for a high-level overview of the source code:
https://github.com/neovim/neovim/blob/master/src/nvim/README.md
==============================================================================
1. Design goals *design-goals*
@ -28,7 +24,7 @@ Note that quite a few items are contradicting. This is intentional. A
balance must be found between them.
VIM IS... IMPROVED *design-improved*
NVIM IS... IMPROVED *design-improved*
The IMproved bits of Vim should make it a better Vi, without becoming a
completely different editor. Extensions are done with a "Vi spirit".
@ -49,7 +45,7 @@ completely different editor. Extensions are done with a "Vi spirit".
implement and (3) someone actually implementing it.
VIM IS... MULTI PLATFORM *design-multi-platform*
NVIM IS... MULTI PLATFORM *design-multi-platform*
Vim tries to help as many users on as many platforms as possible.
- Support many kinds of terminals. The minimal demands are cursor positioning
@ -68,7 +64,7 @@ Vim tries to help as many users on as many platforms as possible.
contradicts the previous item, these two must be balanced.]
VIM IS... WELL DOCUMENTED *design-documented*
NVIM IS... WELL DOCUMENTED *design-documented*
- A feature that isn't documented is a useless feature. A patch for a new
feature must include the documentation.
@ -76,9 +72,14 @@ VIM IS... WELL DOCUMENTED *design-documented*
recommended.
- Don't make the text unnecessarily long. Less documentation means that an
item is easier to find.
- Do not prefix doc-tags with "nvim-". Use |vim_diff.txt| to document
differences from Vim. The {Nvim} annotation is also available
to mark a specific feature. No other distinction is necessary.
- If a feature is removed, delete its doc entry and move its tag to
|vim_diff.txt|.
VIM IS... HIGH SPEED AND SMALL IN SIZE *design-speed-size*
NVIM IS... HIGH SPEED AND SMALL IN SIZE *design-speed-size*
Using Vim must not be a big attack on system resources. Keep it small and
fast.
@ -89,13 +90,11 @@ fast.
possible. Useful commands may take longer.
- Don't forget that some people use Vim over a slow connection. Minimize the
communication overhead.
- Items that add considerably to the size and are not used by many people
should be a feature that can be disabled.
- Vim is a component among other components. Don't turn it into a massive
application, but have it work well together with other programs.
VIM IS... MAINTAINABLE *design-maintain*
NVIM IS... MAINTAINABLE *design-maintain*
- The source code should not become a mess. It should be reliable code.
- Use comments in a useful way! Quoting the function name and argument names
@ -106,7 +105,7 @@ VIM IS... MAINTAINABLE *design-maintain*
knowledge spread to other parts of the code.
VIM IS... FLEXIBLE *design-flexible*
NVIM IS... FLEXIBLE *design-flexible*
Vim should make it easy for users to work in their preferred styles rather
than coercing its users into particular patterns of work. This can be for
@ -117,27 +116,15 @@ be used to adjust Vim to the desire of the user and its environment.
NVIM IS... NOT *design-not*
Nvim is not an Operating System; instead it should be composed with other
tools, or hosted as a component. Marvim once said: "Unlike Emacs, Nvim does
not attempt to include everything but the kitchen sink, but some people use it
for plumbing."
Nvim is not an operating system; instead it should be composed with other
tools or hosted as a component. Marvim once said: "Unlike Emacs, Nvim does not
include the kitchen sink... but you can use it for plumbing."
==============================================================================
2. Design decisions *design-decisions*
Folding
Several forms of folding should be possible for the same buffer. For example,
have one window that shows the text with function bodies folded, another
window that shows a function body.
Folding is a way to display the text. It should not change the text itself.
Therefore the folding has been implemented as a filter between the text stored
in a buffer (buffer lines) and the text displayed in a window (logical lines).
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.
@ -153,110 +140,52 @@ window View on a buffer. There can be several windows in Vim,
fit in the shell.
Spell checking *develop-spell*
Providers *dev-provider*
When spell checking was going to be added to Vim a survey was done over the
available spell checking libraries and programs. Unfortunately, the result
was that none of them provided sufficient capabilities to be used as the spell
checking engine in Vim, for various reasons:
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.
- Missing support for multi-byte encodings. At least UTF-8 must be supported,
so that more than one language can be used in the same file.
Doing on-the-fly conversion is not always possible (would require iconv
support).
- For the programs and libraries: Using them as-is would require installing
them separately from Vim. That's mostly not impossible, but a drawback.
- Performance: A few tests showed that it's possible to check spelling on the
fly (while redrawing), just like syntax highlighting. But the mechanisms
used by other code are much slower. Myspell uses a hashtable, for example.
The affix compression that most spell checkers use makes it slower too.
- For using an external program like aspell a communication mechanism would
have to be setup. That's complicated to do in a portable way (Unix-only
would be relatively simple, but that's not good enough). And performance
will become a problem (lots of process switching involved).
- Missing support for words with non-word characters, such as "Etten-Leur" and
"et al.", would require marking the pieces of them OK, lowering the
reliability.
- Missing support for regions or dialects. Makes it difficult to accept
all English words and highlight non-Canadian words differently.
- Missing support for rare words. Many words are correct but hardly ever used
and could be a misspelled often-used word.
- For making suggestions the speed is less important and requiring to install
another program or library would be acceptable. But the word lists probably
differ, the suggestions may be wrong words.
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 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.
Spelling suggestions *develop-spell-suggestions*
For making suggestions there are two basic mechanisms:
1. Try changing the bad word a little bit and check for a match with a good
word. Or go through the list of good words, change them a little bit and
check for a match with the bad word. The changes are deleting a character,
inserting a character, swapping two characters, etc.
2. Perform soundfolding on both the bad word and the good words and then find
matches, possibly with a few changes like with the first mechanism.
The first is good for finding typing mistakes. After experimenting with
hashtables and looking at solutions from other spell checkers the conclusion
was that a trie (a kind of tree structure) is ideal for this. Both for
reducing memory use and being able to try sensible changes. For example, when
inserting a character only characters that lead to good words need to be
tried. Other mechanisms (with hashtables) need to try all possible letters at
every position in the word. Also, a hashtable has the requirement that word
boundaries are identified separately, while a trie does not require this.
That makes the mechanism a lot simpler.
Soundfolding is useful when someone knows how the words sounds but doesn't
know how it is spelled. For example, the word "dictionary" might be written
as "daktonerie". The number of changes that the first method would need to
try is very big, it's hard to find the good word that way. After soundfolding
the words become "tktnr" and "tkxnry", these differ by only two letters.
To find words by their soundfolded equivalent (soundalike word) we need a list
of all soundfolded words. A few experiments have been done to find out what
the best method is. Alternatives:
1. Do the sound folding on the fly when looking for suggestions. This means
walking through the trie of good words, soundfolding each word and
checking how different it is from the bad word. This is very efficient for
memory use, but takes a long time. On a fast PC it takes a couple of
seconds for English, which can be acceptable for interactive use. But for
some languages it takes more than ten seconds (e.g., German, Catalan),
which is unacceptable slow. For batch processing (automatic corrections)
it's too slow for all languages.
2. Use a trie for the soundfolded words, so that searching can be done just
like how it works without soundfolding. This requires remembering a list
of good words for each soundfolded word. This makes finding matches very
fast but requires quite a lot of memory, in the order of 1 to 10 Mbyte.
For some languages more than the original word list.
3. Like the second alternative, but reduce the amount of memory by using affix
compression and store only the soundfolded basic word. This is what Aspell
does. Disadvantage is that affixes need to be stripped from the bad word
before soundfolding it, which means that mistakes at the start and/or end
of the word will cause the mechanism to fail. Also, this becomes slow when
the bad word is quite different from the good word.
The choice made is to use the second mechanism and use a separate file. This
way a user with sufficient memory can get very good suggestions while a user
who is short of memory or just wants the spell checking and no suggestions
doesn't use so much memory.
Word frequency
For sorting suggestions it helps to know which words are common. In theory we
could store a word frequency with the word in the dictionary. However, this
requires storing a count per word. That degrades word tree compression a lot.
And maintaining the word frequency for all languages will be a heavy task.
Also, it would be nice to prefer words that are already in the text. This way
the words that appear in the specific text are preferred for suggestions.
What has been implemented is to count words that have been seen during
displaying. A hashtable is used to quickly find the word count. The count is
initialized from words listed in COMMON items in the affix file, so that it
also works when starting a new file.
This isn't ideal, because the longer Vim is running the higher the counts
become. But in practice it is a noticeable improvement over not using the word
count.
RPC API
API client
remote plugin
vim:tw=78:ts=8:ft=help:norl:

34
runtime/doc/eval.txt
View File

@ -1653,9 +1653,9 @@ v:scrollstart String describing the script or function that caused the
hit-enter prompt.
*v:servername* *servername-variable*
*$NVIM_LISTEN_ADDRESS*
v:servername Default {Nvim} server address. Equivalent to
|$NVIM_LISTEN_ADDRESS| on startup, but may differ if the
latter is modified or unset. |serverstop()|
|$NVIM_LISTEN_ADDRESS| on startup. |serverstop()|
Read-only.
@ -2031,11 +2031,11 @@ resolve({filename}) String get filename a shortcut points to
reverse({list}) List reverse {list} in-place
round({expr}) Float round off {expr}
rpcnotify({channel}, {event}[, {args}...])
Sends a |msgpack-rpc| notification to {channel}
Sends an |RPC| notification to {channel}
rpcrequest({channel}, {method}[, {args}...])
Sends a |msgpack-rpc| request to {channel}
rpcstart({prog}[, {argv}]) Spawns {prog} and opens a |msgpack-rpc| channel
rpcstop({channel}) Closes a |msgpack-rpc| {channel}
Sends an |RPC| request to {channel}
rpcstart({prog}[, {argv}]) Spawns {prog} and opens an |RPC| channel
rpcstop({channel}) Closes an |RPC| {channel}
screenattr({row}, {col}) Number attribute at screen position
screenchar({row}, {col}) Number character at screen position
screencol() Number current cursor column
@ -5526,31 +5526,31 @@ round({expr}) *round()*
< -5.0
rpcnotify({channel}, {event}[, {args}...]) {Nvim} *rpcnotify()*
Sends {event} to {channel} via |msgpack-rpc| and returns
immediately. If {channel} is 0, the event is broadcast to all
channels. Example: >
Sends {event} to {channel} via |RPC| and returns immediately.
If {channel} is 0, the event is broadcast to all channels.
Example: >
:au VimLeave call rpcnotify(0, "leaving")
rpcrequest({channel}, {method}[, {args}...]) {Nvim} *rpcrequest()*
Sends a request to {channel} to invoke {method} via
|msgpack-rpc| and blocks until a response is received.
|RPC| and blocks until a response is received.
Example: >
:let result = rpcrequest(rpc_chan, "func", 1, 2, 3)
rpcstart({prog}[, {argv}]) {Nvim} *rpcstart()*
Spawns {prog} as a job (optionally passing the list {argv}),
and opens a |msgpack-rpc| channel with the spawned process's
stdin/stdout. It returns:
- The channel id on success, which is used by |rpcrequest()|,
and opens an |RPC| channel with the spawned process's
stdin/stdout. Returns:
- channel id on success, which is used by |rpcrequest()|,
|rpcnotify()| and |rpcstop()|
- 0 on failure.
- 0 on failure
Example: >
:let rpc_chan = rpcstart('prog', ['arg1', 'arg2'])
rpcstop({channel}) {Nvim} *rpcstop()*
Closes a |msgpack-rpc| {channel}, possibly created via
Closes an |RPC| {channel}, possibly created via
|rpcstart()|. Also closes channels created by connections to
|$NVIM_LISTEN_ADDRESS|.
|v:servername|.
screenattr(row, col) *screenattr()*
Like screenchar(), but return the attribute. This is a rather
@ -6841,7 +6841,7 @@ termopen({cmd}[, {opts}]) {Nvim} *termopen()*
and `$TERM` is set to "xterm-256color".
Returns the same values as |jobstart()|.
See |nvim-terminal-emulator| for more information.
See |terminal-emulator| for more information.
tan({expr}) *tan()*
Return the tangent of {expr}, measured in radians, as a |Float|

4
runtime/doc/gui.txt
View File

@ -395,9 +395,9 @@ You may make selections with the mouse (see |gui-mouse-select|), or by using
Vim's Visual mode (see |v|). If 'a' is present in 'guioptions', then
whenever a selection is started (Visual or Select mode), or when the selection
is changed, Vim becomes the owner of the windowing system's primary selection
(on MS-Windows the |gui-clipboard| is used).
(on MS-Windows the |clipboard| is used).
*clipboard*
*primary-selection*
There is a special register for storing this selection, it is the "*
register. Nothing is put in here unless the information about what text is
selected is about to change (e.g. with a left mouse click somewhere), or when

437
runtime/doc/gui_w32.txt
View File

@ -1,437 +0,0 @@
*gui_w32.txt* For Vim version 7.4. Last change: 2014 Dec 20
VIM REFERENCE MANUAL by Bram Moolenaar
Vim's Win32 Graphical User Interface *gui-w32* *win32-gui*
1. Starting the GUI |gui-w32-start|
2. Vim as default editor |vim-default-editor|
3. Using the clipboard |gui-clipboard|
4. Shell Commands |gui-shell-win32|
5. Special colors |win32-colors|
6. Windows dialogs & browsers |gui-w32-dialogs|
7. Command line arguments |gui-w32-cmdargs|
8. Various |gui-w32-various|
Other relevant documentation:
|gui.txt| For generic items of the GUI.
|os_win32.txt| For Win32 specific items.
==============================================================================
1. Starting the GUI *gui-w32-start*
The Win32 GUI version of Vim will always start the GUI, no matter how you
start it or what it's called.
The GUI will always run in the Windows subsystem. Mostly shells automatically
return with a command prompt after starting gvim. If not, you should use the
"start" command: >
start gvim [options] file ..
Note: All fonts (bold, italic) must be of the same size!!! If you don't do
this, text will disappear or mess up the display. Vim does not check the font
sizes. It's the size in screen pixels that must be the same. Note that some
fonts that have the same point size don't have the same pixel size!
Additionally, the positioning of the fonts must be the same (ascent and
descent).
The Win32 GUI has an extra menu item: "Edit/Select Font". It brings up the
standard Windows font selector.
Setting the menu height doesn't work for the Win32 GUI.
*gui-win32-maximized*
If you want Vim to start with a maximized window, add this command to your
vimrc or gvimrc file: >
au GUIEnter * simalt ~x
<
==============================================================================
2. Vim as default editor *vim-default-editor*
To set Vim as the default editor for a file type:
1. Start a Windows Explorer
2. Choose View/Options -> File Types
3. Select the path to gvim for every file type that you want to use it for.
(you can also use three spaces in the file type field, for files without an
extension).
In the "open" action, use: >
gvim "%1"
< The quotes are required for using file names with embedded spaces.
You can also use this: >
gvim "%L"
< This should avoid short (8.3 character) file names in some situations. But
I'm not sure if this works everywhere.
When you open a file in Vim by double clicking it, Vim changes to that
file's directory.
If you want Vim to start full-screen, use this for the Open action: >
gvim -c "simalt ~x" "%1"
Another method, which also works when you put Vim in another directory (e.g.,
when you have got a new version):
1. select a file you want to use Vim with
2. <Shift-F10>
3. select "Open With..." menu entry
4. click "Other..."
5. browse to the (new) location of Vim and click "Open"
6. make "Always Use this program..." checked
7. <OK>
*send-to-menu* *sendto*
You can also install Vim in the "Send To" menu:
1. Start a Windows Explorer
2. Navigate to your sendto directory:
Windows NT: %windir%\profiles\%user%\sendto (e.g.
"c:\winnt\profiles\mattha\sendto").
3. Right-click in the file pane and select New->Shortcut
4. Follow the shortcut wizard, using the full path to VIM/GVIM.
When you 'send a file to Vim', Vim changes to that file's directory. Note,
however, that any long directory names will appear in their short (MS-DOS)
form. This is a limitation of the Windows "Send To" mechanism.
*notepad*
You could replace notepad.exe with gvim.exe, but that has a few side effects.
Some programs rely on notepad arguments, which are not recognized by Vim. For
example "notepad -p" is used by some applications to print a file. It's
better to leave notepad where it is and use another way to start Vim.
*win32-popup-menu*
A more drastic approach is to install an "Edit with Vim" entry in the popup
menu for the right mouse button. With this you can edit any file with Vim.
This can co-exist with the file associations mentioned above. The difference
is that the file associations will make starting Vim the default action. With
the "Edit with Vim" menu entry you can keep the existing file association for
double clicking on the file, and edit the file with Vim when you want. For
example, you can associate "*.mak" with your make program. You can execute
the makefile by double clicking it and use the "Edit with Vim" entry to edit
the makefile.
You can select any files and right-click to see a menu option called "Edit
with gvim". Choosing this menu option will invoke gvim with the file you have
selected. If you select multiple files, you will find two gvim-related menu
options:
"Edit with multiple gvims" -- one gvim for each file in the selection
"Edit with single gvim" -- one gvim for all the files in the selection
And if there already is a gvim running:
"Edit with existing gvim" -- edit the file with the running gvim
The "edit with existing Vim" entries can be disabled by adding an entry in the
registry under HKLM\Software\Vim\Gvim, named DisableEditWithExisting, and with
any value.
*install-registry*
You can add the "Edit with Vim" menu entry in an easy way by using the
"install.exe" program. It will add several registry entries for you.
You can also do this by hand. This is complicated! Use the install.exe if
you can.
1. Start the registry editor with "regedit".
2. Add these keys:
key value name value ~
HKEY_CLASSES_ROOT\CLSID\{51EEE242-AD87-11d3-9C1E-0090278BBD99}
{default} Vim Shell Extension
HKEY_CLASSES_ROOT\CLSID\{51EEE242-AD87-11d3-9C1E-0090278BBD99}\InProcServer32
{default} {path}\gvimext.dll
ThreadingModel Apartment
HKEY_CLASSES_ROOT\*\shellex\ContextMenuHandlers\gvim
{default} {51EEE242-AD87-11d3-9C1E-0090278BBD99}
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Approved
{51EEE242-AD87-11d3-9C1E-0090278BBD99}
Vim Shell Extension
HKEY_LOCAL_MACHINE\Software\Vim\Gvim
path {path}\gvim.exe
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall\vim 5.6
DisplayName Vim 5.6: Edit with Vim popup menu entry
UninstallString {path}\uninstal.exe
Replace {path} with the path that leads to the executable.
Don't type {default}, this is the value for the key itself.
To remove "Edit with Vim" from the popup menu, just remove the registry
entries mentioned above. The "uninstal.exe" program can do this for you. You
can also use the entry in the Windows standard "Add/Remove Programs" list.
If you notice that this entry overrules other file type associations, set
those associations again by hand (using Windows Explorer, see above). This
only seems to happen on some Windows NT versions (Windows bug?). Procedure:
1. Find the name of the file type. This can be done by starting the registry
editor, and searching for the extension in \\HKEY_CLASSES_ROOT
2. In a Windows Explorer, use View/Options/File Types. Search for the file
type in the list and click "Edit". In the actions list, you can select on
to be used as the default (normally the "open" action) and click on the
"Set Default" button.
Vim in the "Open With..." context menu *win32-open-with-menu*
If you use the Vim install program you have the choice to add Vim to the "Open
With..." menu. This means you can use Vim to edit many files. Not every file
(for unclear reasons...), thus the "Edit with Vim" menu entry is still useful.
One reason to add this is to be able to edit HTML files directly from Internet
Explorer. To enable this use the "Tools" menu, "Internet Options..." entry.
In the dialog select the "Programs" tab and select Vim in the "HTML editor"
choice. If it's not there than installing didn't work properly.
Doing this manually can be done with this script:
----------------------------------------------------------
REGEDIT4
[HKEY_CLASSES_ROOT\Applications\gvim.exe]
[HKEY_CLASSES_ROOT\Applications\gvim.exe\shell]
[HKEY_CLASSES_ROOT\Applications\gvim.exe\shell\edit]
[HKEY_CLASSES_ROOT\Applications\gvim.exe\shell\edit\command]
@="c:\\vim\\vim62\\gvim.exe \"%1\""
[HKEY_CLASSES_ROOT\.htm\OpenWithList\gvim.exe]
[HKEY_CLASSES_ROOT\*\OpenWithList\gvim.exe]
----------------------------------------------------------
Change the "c:\\vim\\vim62" bit to where gvim.exe is actually located.
To uninstall this run the Vim uninstall program or manually delete the
registry entries with "regedit".
==============================================================================
3. Using the clipboard *gui-clipboard*
Windows has a clipboard, where you can copy text to, and paste text from. Vim
supports this in several ways. For other systems see |gui-selections|.
The "* register reflects the contents of the clipboard. |quotestar|
When the "unnamed" string is included in the 'clipboard' option, the unnamed
register is the same. Thus you can yank to and paste from the clipboard
without prepending "* to commands.
The 'a' flag in 'guioptions' is not included by default. This means that text
is only put on the clipboard when an operation is performed on it. Just
Visually selecting text doesn't put it on the clipboard. When the 'a' flag is
included, the text is copied to the clipboard even when it is not operated
upon.
*mswin.vim*
To use the standard MS-Windows way of CTRL-X, CTRL-C and CTRL-V, use the
$VIMRUNTIME/mswin.vim script. You could add this line to your _vimrc file: >
source $VIMRUNTIME/mswin.vim
Since CTRL-C is used to copy the text to the clipboard, it can't be used to
cancel an operation. Use CTRL-Break for that.
CTRL-Z is used for undo. This means you can't suspend Vim with this key, use
|:suspend| instead (if it's supported at all).
*CTRL-V-alternative* *CTRL-Q*
Since CTRL-V is used to paste, you can't use it to start a blockwise Visual
selection. You can use CTRL-Q instead. You can also use CTRL-Q in Insert
mode and Command-line mode to get the old meaning of CTRL-V. But CTRL-Q
doesn't work for terminals when it's used for control flow.
NOTE: The clipboard support still has a number of bugs.
==============================================================================
4. Shell Commands *gui-shell-win32*
Vim uses another window for external commands, to make it possible to run any
command. The external command gets its own environment for running, just like
it was started from a DOS prompt.
*win32-vimrun*
Executing an external command is done indirectly by the "vimrun" command. The
"vimrun.exe" must be in the path for this to work. Or it must be in the same
directory as the Vim executable. If "vimrun" cannot be found, the command is
executed directly, but then the DOS window closes immediately after the
external command has finished.
WARNING: If you close this window with the "X" button, and confirm the
question if you really want to kill the application, Vim may be killed too!
(This does not apply to commands run asynchronously with ":!start".)
*win32-!start*
Normally, Vim waits for a command to complete before continuing (this makes
sense for most shell commands which produce output for Vim to use). If you
want Vim to start a program and return immediately, you can use the following
syntax on W95 & NT: >
:!start [/min] {command}
The optional "/min" causes the window to be minimized.
==============================================================================
5. Special colors *win32-colors*
On Win32, the normal DOS colors can be used. See |dos-colors|.
Additionally the system configured colors can also be used. These are known
by the names Sys_XXX, where XXX is the appropriate system color name, from the
following list (see the Win32 documentation for full descriptions). Case is
ignored.
Sys_3DDKShadow Sys_3DFace Sys_BTNFace
Sys_3DHilight Sys_3DHighlight Sys_BTNHilight
Sys_BTNHighlight Sys_3DLight Sys_3DShadow
Sys_BTNShadow Sys_ActiveBorder Sys_ActiveCaption
Sys_AppWorkspace Sys_Background Sys_Desktop
Sys_BTNText Sys_CaptionText Sys_GrayText
Sys_Highlight Sys_HighlightText Sys_InactiveBorder
Sys_InactiveCaption Sys_InactiveCaptionText Sys_InfoBK
Sys_InfoText Sys_Menu Sys_MenuText
Sys_ScrollBar Sys_Window Sys_WindowFrame
Sys_WindowText
Probably the most useful values are
Sys_Window Normal window background
Sys_WindowText Normal window text
Sys_Highlight Highlighted background
Sys_HighlightText Highlighted text
These extra colors are also available:
Gray, Grey, LightYellow, SeaGreen, Orange, Purple, SlateBlue, Violet,
*rgb.txt*
Additionally, colors defined by a "rgb.txt" file can be used. This file is
well known from X11. A few lines from it: >
255 218 185 peach puff
205 133 63 peru
255 181 197 pink
This shows the layout of the file: First the R, G and B value as a decimal
number, followed by the name of the color. The four fields are separated by
spaces.
You can get an rgb.txt file from any X11 distribution. It is located in a
directory like "/usr/X11R6/lib/X11/". For Vim it must be located in the
$VIMRUNTIME directory. Thus the file can be found with "$VIMRUNTIME/rgb.txt".
==============================================================================
*gui-w32-dialogs* *dialog*
6. Windows dialogs & browsers
The Win32 GUI can use familiar Windows components for some operations, as well
as the traditional interface shared with the console version.
6.1 Dialogs
The dialogs displayed by the "confirm" family (i.e. the 'confirm' option,
|:confirm| command and |confirm()| function) are GUI-based rather than the
console-based ones used by other versions. The 'c' flag in 'guioptions'
changes this.
6.2 File Browsers
When prepending ":browse" before file editing commands, a file requester is
used to allow you to select an existing file. See |:browse|.
==============================================================================
7. Command line arguments *gui-w32-cmdargs*
Analysis of a command line into parameters is not standardised in MS Windows.
Gvim has to provide logic to analyse a command line. This logic is likely to
be different from the default logic provided by a compilation system used to
build vim. The differences relate to unusual double quote (") usage.
The arguments "C:\My Music\freude.txt" and "+/Sch\"iller" are handled in the
same way. The argument "+/Sch""iller" may be handled different by gvim and
vim, depending what it was compiled with.
The rules are:
a) A parameter is a sequence of graphic characters.
b) Parameters are separated by white space.
c) A parameter can be enclosed in double quotes to include white space.
d) A sequence of zero or more backslashes (\) and a double quote (")
is special. The effective number of backslashes is halved, rounded
down. An even number of backslashes reverses the acceptability of
spaces and tabs, an odd number of backslashes produces a literal
double quote.
So:
" is a special double quote
\" is a literal double quote
\\" is a literal backslash and a special double quote
\\\" is a literal backslash and a literal double quote
\\\\" is 2 literal backslashes and a special double quote
\\\\\" is 2 literal backslashes and a literal double quote
etc.
Example: >
gvim "C:\My Music\freude" +"set ignorecase" +/"\"foo\\" +\"bar\\\"
opens "C:\My Music\freude" and executes the line mode commands: >
set ignorecase; /"foo\ and /bar\"
==============================================================================
8. Various *gui-w32-various*
*gui-w32-printing*
The "File/Print" menu prints the text with syntax highlighting, see
|:hardcopy|. If you just want to print the raw text and have a default
printer installed this should also work: >
:w >>prn
Vim supports a number of standard MS Windows features. Some of these are
detailed elsewhere: see |'mouse'|, |win32-hidden-menus|.
*drag-n-drop-win32*
You can drag and drop one or more files into the Vim window, where they will
be opened as normal. See |drag-n-drop|.
*:simalt* *:sim*
:sim[alt] {key} simulate pressing {key} while holding Alt pressed.
{only for Win32 versions}
Normally, Vim takes control of all Alt-<Key> combinations, to increase the
number of possible mappings. This clashes with the standard use of Alt as the
key for accessing menus.
The quick way of getting standard behavior is to set the 'winaltkeys' option
to "yes". This however prevents you from mapping Alt keys at all.
Another way is to set 'winaltkeys' to "menu". Menu shortcut keys are then
handled by windows, other ALT keys can be mapped. This doesn't allow a
dependency on the current state though.
To get round this, the :simalt command allows Vim (when 'winaltkeys' is not
"yes") to fake a Windows-style Alt keypress. You can use this to map Alt key
combinations (or anything else for that matter) to produce standard Windows
actions. Here are some examples: >
:map <M-f> :simalt f<CR>
This makes Alt-F pop down the 'File' menu (with the stock Menu.vim) by
simulating the keystrokes Alt, F. >
:map <M-Space> :simalt ~<CR>
This maps Alt-Space to pop down the system menu for the Vim window. Note that
~ is used by simalt to represent the <Space> character. >
:map <C-n> :simalt ~n<CR>
Maps Control-N to produce the keys Alt-Space followed by N. This minimizes the
Vim window via the system menu.
Note that the key changes depending on the language you are using.
*intellimouse-wheel-problems*
When using the Intellimouse mouse wheel causes Vim to stop accepting input, go
to:
ControlPanel - Mouse - Wheel - UniversalScrolling - Exceptions
And add gvim to the list of applications. This problem only appears to happen
with the Intellimouse driver 2.2 and when "Universal Scrolling" is turned on.
XPM support *w32-xpm-support*
Gvim can be build on MS-Windows with support for XPM files. |+xpm_w32|
See the Make_mvc.mak file for instructions, search for XPM.
To try out if XPM support works do this: >
:help
:exe 'sign define vimxpm icon=' . $VIMRUNTIME . '\\vim16x16.xpm'
:exe 'sign place 1 line=1 name=vimxpm file=' . expand('%:p')
<
vim:tw=78:sw=4:ts=8:ft=help:norl:

2
runtime/doc/if_pyth.txt
View File

@ -16,7 +16,7 @@ The Python Interface to Vim *python* *Python*
8. pyeval(), py3eval() Vim functions |python-pyeval|
9. Python 3 |python3|
See |nvim-python| for more information. {Nvim}
See |provider-python| for more information. {Nvim}
==============================================================================
1. Commands *python-commands*

306
runtime/doc/msgpack_rpc.txt
View File

@ -1,97 +1,88 @@
*msgpack_rpc.txt* For Nvim. {Nvim}
*msgpack_rpc.txt* {Nvim}
NVIM REFERENCE MANUAL by Thiago de Arruda
The Msgpack-RPC Interface to Nvim *msgpack-rpc*
RPC API for Nvim *RPC* *rpc* *msgpack-rpc*
1. Introduction |msgpack-rpc-intro|
2. API mapping |msgpack-rpc-api|
3. Connecting |msgpack-rpc-connecting|
4. Clients |msgpack-rpc-clients|
5. Types |msgpack-rpc-types|
6. Wrapping methods |msgpack-rpc-wrap-methods|
7. Vimscript functions |msgpack-rpc-vim-functions|
1. Introduction |rpc-intro|
2. API mapping |rpc-api|
3. Connecting |rpc-connecting|
4. Clients |rpc-client|
5. Types |rpc-types|
6. Vimscript functions |rpc-vim-functions|
==============================================================================
1. Introduction *msgpack-rpc-intro*
1. Introduction *rpc-intro*
The primary way to control a running Nvim instance is through
MessagePack-RPC, a messaging protocol that uses the MessagePack serialization
format: https://github.com/msgpack/msgpack/blob/7498cf3/spec.md.
From now on, we refer to the protocol as msgpack-rpc.
The primary way to control Nvim programmatically is the RPC API, which speaks
MessagePack-RPC ("msgpack-rpc"), a messaging protocol that uses the
MessagePack serialization format:
https://github.com/msgpack/msgpack/blob/0b8f5ac/spec.md
At this point, only plugins use msgpack-rpc, but eventually even user
interaction will happen through it, since user interfaces will be separate
programs that control a headless Nvim instance.
All kinds of Nvim "clients" use the RPC API: user interfaces (GUIs), remote
plugins, scripts like "nvr" (https://github.com/mhinz/neovim-remote), and even
`nvim` itself can control other `nvim` instances. By connecting to the RPC API
programs can:
By connecting to the msgpack-rpc interface, programs can:
- Call any API function
- Listen for events
- Receive remote calls from Nvim
- Call any Nvim API function
- Listen for Nvim events
- Receive remote calls from Nvim
Nvim's msgpack-rpc interface is like a more powerful version of Vim's
`clientserver` feature.
The RPC API is like a more powerful version of Vim's `clientserver` feature.
==============================================================================
2. API mapping *msgpack-rpc-api*
2. API mapping *rpc-api*
The Nvim C API, see |nvim-api|, is automatically exposed to the msgpack-rpc
interface by the build system, which parses headers at src/nvim/api from the
project root. A dispatch function is generated, which matches msgpack-rpc method
names with non-static API functions, converting/validating arguments and return
values back to msgpack.
The Nvim C |API| is automatically exposed to the RPC API by the build system,
which parses headers at src/nvim/api/*. A dispatch function is generated which
matches RPC API method names with public API functions, converting/validating
arguments and return values back to msgpack.
Client libraries will normally provide wrappers that hide msgpack-rpc details
from programmers. The wrappers can be automatically generated by reading
bundled API metadata from a compiled Nvim instance.
Client libraries (|api-client|s) normally provide wrappers that hide
msgpack-rpc details from application developers. The wrappers can be
automatically generated by reading bundled API metadata from a compiled Nvim
instance.
There are two ways to obtain API metadata:
1. By connecting to a running Nvim instance and calling `vim_get_api_info`
via msgpack-rpc. This is best for clients written in dynamically-typed
languages, which can define functions at runtime.
1. Connect to a running Nvim instance and call `vim_get_api_info` via
msgpack-rpc. This is best for clients written in dynamic languages which
can define functions at runtime.
2. By starting Nvim with the `--api-info` command-line option, which makes Nvim
dump a blob of msgpack metadata to standard output and exit. This is best
for clients written in statically-typed languages, which require a separate
compilation step.
2. Start Nvim with the `--api-info` command-line option, which dumps a blob
of msgpack metadata to standard output. This is useful for clients
written in statically-compiled languages.
Here's a simple way to get human-readable description of the API (requires
Python and the `pyyaml`/`msgpack-python` pip packages):
>
nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))' > api.yaml
To get a human-readable list of API functions: >
:new|put =map(msgpackparse(systemlist('nvim --api-info'))[0].functions, 'v:val.name._VAL[0]')
<
To get a formatted dump of the API using python (requires the `pyyaml` and
`msgpack-python` packages): >
nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))'
<
==============================================================================
3. Connecting *msgpack-rpc-connecting*
3. Connecting *rpc-connecting*
There are four ways to open msgpack-rpc streams to Nvim:
There are several ways to open a msgpack-rpc stream to an Nvim server:
1. Through Nvim's stdin/stdout when it's started with the `--embed` option.
This is how other programs can embed Nvim.
1. Through stdin/stdout when `nvim` is started with `--embed`. This is how
applications can embed Nvim.
2. Through the stdin/stdout of a program spawned by the |rpcstart()| function.
2. Through stdin/stdout of some other process spawned by |rpcstart()|.
*$NVIM_LISTEN_ADDRESS*
3. Through the socket automatically created with each instance. To get the
socket location for a running Nvim instance (which is random by default),
see the |$NVIM_LISTEN_ADDRESS| environment variable:
>
:echo $NVIM_LISTEN_ADDRESS
<
See also |v:servername|.
3. Through the socket automatically created with each instance. The socket
location is stored in |v:servername|.
4. Through a TCP/IP socket. To make Nvim listen on a TCP/IP socket, set the
|$NVIM_LISTEN_ADDRESS| environment variable in a shell before starting Nvim:
>
4. Through a TCP/IP socket. To make Nvim listen on a TCP/IP socket, set the
|$NVIM_LISTEN_ADDRESS| environment variable before starting Nvim: >
NVIM_LISTEN_ADDRESS=127.0.0.1:6666 nvim
<
Connecting to the socket is the easiest way a programmer can test the API, which
can be done through any msgpack-rpc client library or fully-featured Nvim client
(which we'll see in the next section). Here's a Ruby script that prints 'hello
world!' in the current Nvim instance:
Connecting to the socket is the easiest way a programmer can test the API,
which can be done through any msgpack-rpc client library or full-featured
|api-client|. Here's a Ruby script that prints 'hello world!' in the current
Nvim instance:
>
#!/usr/bin/env ruby
# Requires msgpack-rpc: gem install msgpack-rpc
@ -118,72 +109,103 @@ functions can be called interactively:
>>> nvim = attach('socket', path='[address]')
>>> nvim.command('echo "hello world!"')
<
One can also spawn and connect to an embedded Nvim instance via |rpcstart()|
You can also embed an Nvim instance via |rpcstart()|
>
let vim = rpcstart('nvim', ['--embed'])
echo rpcrequest(vim, 'vim_eval', '"Hello " . "world!"')
call rpcstop(vim)
<
==============================================================================
4. Implementing new clients *msgpack-rpc-clients*
4. Implementing API clients *rpc-api-client* *api-client*
Nvim is still in alpha, so there's no in-depth documentation explaining how to
properly implement a client library yet. The Python client (the pip package
"neovim") will always be up-to-date with the latest API changes, so its source
code is the best documentation currently available. There are some guidelines
however:
All external UIs and remote plugins (as opposed to regular Vim plugins) are
"clients" in general; but we call something an "API client" if its purpose is
to abstract or wrap the RPC API for the convenience of other applications
(just like a REST client or SDK such as boto3 for AWS: you can speak AWS REST
using an HTTP client like curl, but boto3 wraps that in a convenient python
interface). For example, the lua-client is an API client:
https://github.com/neovim/lua-client
- Separate the transport layer from the rest of the library. See
|msgpack-rpc-connecting| for details on how clients can connect to Nvim.
- Use a MessagePack library that implements at least version 5 of the
MessagePack spec, which supports the `bin` and `ext` types used by Nvim.
- Read API metadata in order to create client-side wrappers for all
msgpack-rpc methods.
- Use a single-threaded event loop library/pattern.
- Use a fiber/coroutine library for the language being used for implementing a
client. These greatly simplify concurrency and allow the library to expose a
blocking API on top of a non-blocking event loop without the complexity that
comes with preemptive multitasking.
- Don't assume anything about the order that responses to msgpack-rpc requests
will arrive.
- Clients should expect msgpack-rpc requests, which need to be handled
immediately because Nvim is blocked while waiting for the client response.
- Clients should expect to receive msgpack-rpc notifications, but these don't
need to be handled immediately because they won't block Nvim (although they
should probably be handled immediately anyway).
The Python client (pip package "neovim") is the reference implementation of an
API client. It is always up-to-date with the Nvim API, so its source code and
test suite are an authoritative reference.
https://github.com/neovim/python-client
Most of the complexity could be handled by a msgpack-rpc library that supports
server to client requests and notifications, but it's not clear if this is part
of the msgpack-rpc spec. At least the Ruby msgpack-rpc library does not seem
to support it:
API client implementation guidelines ~
- Separate the transport layer from the rest of the library. See
|rpc-connecting| for details on how clients can connect to Nvim.
- Use a MessagePack library that implements at least version 5 of the
MessagePack spec, which supports the `bin` and `ext` types used by Nvim.
- Read API metadata in order to create client-side wrappers for all
msgpack-rpc methods.
- Use a single-threaded event loop library/pattern.
- Use a fiber/coroutine library for the language being used for implementing
a client. These greatly simplify concurrency and allow the library to
expose a blocking API on top of a non-blocking event loop without the
complexity that comes with preemptive multitasking.
- Don't assume anything about the order that responses to msgpack-rpc
requests will arrive.
- Clients should expect msgpack-rpc requests, which need to be handled
immediately because Nvim is blocked while waiting for the client response.
- Clients should expect to receive msgpack-rpc notifications, but these
don't need to be handled immediately because they won't block Nvim
(although they should probably be handled immediately anyway).
Note: Most of the complexity could be handled by a msgpack-rpc library that
supports server to client requests and notifications, but it's not clear if
this is part of the msgpack-rpc spec. At least the Ruby msgpack-rpc library
does not seem to support it:
https://github.com/msgpack-rpc/msgpack-rpc-ruby/blob/master/lib/msgpack/rpc/transport/tcp.rb#L150-L158
API metadata object ~
API clients exist to hide msgpack-rpc details. The API metadata object
contains information that makes this task easier (see also |rpc-types|):
- The "functions" key contains a list of metadata objects for individual
functions.
- Each function metadata object has |rpc-types| information about the return
value and parameters. These can be used for generating strongly-typed APIs
in static languages.
- Container types may be decorated with type/size constraints, e.g.
ArrayOf(Buffer) or ArrayOf(Integer, 2). This can be useful to generate
even more strongly-typed APIs.
- Methods that operate on instances of Nvim special types (msgpack EXT) are
prefixed with the type name in lower case, e.g. `buffer_get_line`
represents the `get_line` method of a Buffer instance.
- Global methods are prefixed with `vim`, e.g. `vim_get_buffers`.
So for an object-oriented language, an API client contains the classes
representing Nvim special types, and the methods of each class could be
defined by inspecting the method name prefix. There could also be a singleton
Vim class with methods mapped to functions prefixed with `vim_`.
==============================================================================
5. Types *msgpack-rpc-types*
5. Types *rpc-types*
Nvim's C API uses custom types for all functions, se |nvim-api-types|.
For the purpose of mapping to msgpack, he types can be split into two groups:
The Nvim C API uses custom types for all functions. |api-types|
For the purpose of mapping to msgpack, the types can be split into two groups:
- Basic types that map natively to msgpack (and probably have a default
representation in msgpack-supported programming languages)
- Special Nvim types that map to msgpack EXT with custom type codes.
- Basic types that map natively to msgpack (and probably have a default
representation in msgpack-supported programming languages)
- Special Nvim types that map to msgpack EXT with custom type codes.
Basic type mapping:
Basic types ~
Nil -> msgpack nil
Boolean -> msgpack boolean
Integer (signed 64-bit integer) -> msgpack integer
Float (IEEE 754 double precision) -> msgpack float
String -> msgpack string
Array -> msgpack array
Dictionary -> msgpack map
Nil -> msgpack nil
Boolean -> msgpack boolean
Integer (signed 64-bit integer) -> msgpack integer
Float (IEEE 754 double precision) -> msgpack float
String -> msgpack string
Array -> msgpack array
Dictionary -> msgpack map
Special Nvim types that use msgpack EXT:
Special types (msgpack EXT) ~
Buffer -> enum value kObjectTypeBuffer
Window -> enum value kObjectTypeWindow
Tabpage -> enum value kObjectTypeTabpage
Buffer -> enum value kObjectTypeBuffer
Window -> enum value kObjectTypeWindow
Tabpage -> enum value kObjectTypeTabpage
An API method expecting one of these types may be passed an integer instead,
although they are not interchangeable. For example, a Buffer may be passed as
@ -191,7 +213,7 @@ an integer, but not a Window or Tabpage.
The most reliable way of determining the type codes for the special Nvim types
is to inspect the `types` key of metadata dictionary returned by the
`vim_get_api_info` method at runtime. Here's an example JSON representation of
`vim_get_api_info` method at runtime. Here's a sample JSON representation of
the `types` object:
>
"types": {
@ -206,55 +228,27 @@ the `types` object:
}
}
<
Even for statically compiled clients, it's a good practice to avoid hardcoding
the type codes, because a client may be built against one Nvim version but connect
to another with different type codes.
Even for statically compiled clients it is good practice to avoid hardcoding
the type codes, because a client may be built against one Nvim version but
connect to another with different type codes.
==============================================================================
6. Wrapping methods *msgpack-rpc-wrap-methods*
6. Vimscript functions *rpc-vim-functions*
As mentioned before, clients should provide an API that hides msgpack-rpc
details from programmers, and the API metadata object contains information
that makes this task easier:
RPC functions are available in Vimscript:
- The "functions" key contains a list of metadata objects for individual
functions.
- Each function metadata object has type information about the return value
and parameters. These can be used for generating strongly-typed APIs in
static languages.
- Container types may be decorated with type/size constraints, e.g.
ArrayOf(Buffer) or ArrayOf(Integer, 2). This can be useful to generate even
more strongly-typed APIs.
- Methods that operate instances of Nvim's types are prefixed with the type
name in lower case, e.g. `buffer_get_line` represents the `get_line` method
of a Buffer instance.
- Global methods are prefixed with `vim`, e.g. `vim_get_buffers`.
1. |rpcstart()|: Similarly to |jobstart()|, this will spawn a co-process
with its standard handles connected to Nvim. The difference is that it's
not possible to process raw data to or from the process's stdin, stdout,
or stderr. This is because the job's stdin and stdout are used as
a single msgpack channel that is processed directly by Nvim.
2. |rpcstop()|: Same as |jobstop()|, but operates on handles returned by
|rpcstart()|.
3. |rpcrequest()|: Sends a msgpack-rpc request to the process.
4. |rpcnotify()|: Sends a msgpack-rpc notification to the process.
So, for an object-oriented language, a client library would have the classes
that represent Nvim's types, and the methods of each class could be defined
by inspecting the method name prefix. There could also be a singleton Vim
class with methods mapped to functions prefixed with `vim_`
==============================================================================
7. Vimscript functions *msgpack-rpc-vim-functions*
Four msgpack-rpc functions are available in Vimscript:
1. |rpcstart()|: Similarly to |jobstart()|, this will spawn a co-process with
its standard handles connected to Nvim. The difference is that it's not
possible to process raw data to or from the process's stdin, stdout, or
stderr. This is because the job's stdin and stdout are used as a single
msgpack channel that is processed directly by Nvim.
2. |rpcstop()|: Same as |jobstop()|, but operates on handles returned by
|rpcstart()|.
3. |rpcrequest()|: Sends a msgpack-rpc request to the process.
4. |rpcnotify()|: Sends a msgpack-rpc notification to the process.
The last two functions may also be used with channels created from
connections to |$NVIM_LISTEN_ADDRESS|.
|rpcrequest()| and |rpcnotify()| can also be used with channels connected to
a nvim server. |v:servername|
==============================================================================
vim:tw=78:ts=8:noet:ft=help:norl:

62
runtime/doc/nvim.txt
View File

@ -1,24 +1,56 @@
*nvim.txt* For Nvim. {Nvim}
*nvim.txt* {Nvim}
NVIM REFERENCE MANUAL *nvim*
NVIM REFERENCE MANUAL
Introduction to Nvim *nvim-intro*
Nvim *nvim* *nvim-intro*
This is an introduction for Vim users who are just getting started with Nvim.
It is not meant for Vim beginners. For a basic introduction to Vim,
see |help.txt|.
If you are new to Vim (and Nvim) see |help.txt| or type ":Tutor".
If you already use Vim (but not Nvim) see |nvim-from-vim| for a quickstart.
1. Transitioning from Vim |nvim-from-vim|
2. Differences from Vim |vim-differences|
3. Msgpack-RPC |msgpack-rpc|
4. Job control |job-control|
5. Python plugins |nvim-python|
6. Clipboard integration |nvim-clipboard|
7. Remote plugins |remote-plugin|
8. Provider infrastructure |nvim-provider|
9. Integrated terminal emulator |nvim-terminal-emulator|
Nvim is emphatically a fork of Vim, not a clone: compatibility with Vim is
maintained where possible. See |vim_diff.txt| for the complete reference of
differences from Vim.
==============================================================================
Transitioning from Vim *nvim-from-vim*
To start the transition, link your previous configuration so Nvim can use it:
>
mkdir -p ${XDG_CONFIG_HOME:=$HOME/.config}
ln -s ~/.vim $XDG_CONFIG_HOME/nvim
ln -s ~/.vimrc $XDG_CONFIG_HOME/nvim/init.vim
<
See |provider-python| and |provider-clipboard| for additional software you
might need to use some features.
Your Vim configuration might not be entirely compatible with Nvim. For a
full list of differences between Vim and Nvim see |vim-differences|.
The |'ttymouse'| option, for example, was removed from Nvim (mouse support
should work without it). If you use the same |vimrc| for Vim and Nvim,
consider guarding |'ttymouse'| in your configuration like so:
>
if !has('nvim')
set ttymouse=xterm2
endif
<
Conversely, if you have Nvim specific configuration items, you could do
this:
>
if has('nvim')
tnoremap <Esc> <C-\><C-n>
endif
<
For a more granular approach use |exists()|:
>
if exists(':tnoremap')
tnoremap <Esc> <C-\><C-n>
endif
<
Now you should be able to explore Nvim more comfortably. Check |nvim-features|
for more information.
==============================================================================
vim:tw=78:ts=8:noet:ft=help:norl:

63
runtime/doc/nvim_clipboard.txt
View File

@ -1,63 +0,0 @@
*nvim_clipboard.txt* For Nvim. {Nvim}
NVIM REFERENCE MANUAL by Thiago de Arruda
Clipboard integration for Nvim *nvim-clipboard*
1. Intro |nvim-clipboard-intro|
2. X11 selection mechanism |nvim-clipboard-x11|
==============================================================================
1. Intro *nvim-clipboard-intro*
Nvim has no direct connection to the system clipboard. Instead, it is
accessible through the |nvim-provider| infrastructure, which transparently
uses shell commands for communicating with the clipboard.
Clipboard access is implicitly enabled if any of the following clipboard tools
is found in your `$PATH`.
- xclip
- xsel (newer alternative to xclip)
- pbcopy/pbpaste (only for Mac OS X)
- lemonade (useful for SSH machine)
https://github.com/pocke/lemonade
- doitclient (another option for SSH setups from the maintainer of PuTTY)
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 *nvim-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:

50
runtime/doc/nvim_from_vim.txt
View File

@ -1,50 +0,0 @@
*nvim_from_vim.txt* For Nvim. {Nvim}
NVIM REFERENCE MANUAL
Transitioning from Vim *nvim-from-vim*
Nvim is emphatically a fork of Vim, so compatibility to Vim should be pretty
good.
To start the transition, link your previous configuration so Nvim can use
it:
>
mkdir -p ${XDG_CONFIG_HOME:=$HOME/.config}
ln -s ~/.vim $XDG_CONFIG_HOME/nvim
ln -s ~/.vimrc $XDG_CONFIG_HOME/nvim/init.vim
<
See |nvim-intro|, especially |nvim-python| and |nvim-clipboard|, for
additional software you might need to install to use all of Nvim's features.
Your Vim configuration might not be entirely compatible with Nvim. For a
full list of differences between Vim and Nvim, see |vim-differences|.
The |'ttymouse'| option, for example, was removed from Nvim (mouse support
should work without it). If you use the same |vimrc| for Vim and Nvim,
consider guarding |'ttymouse'| in your configuration like so:
>
if !has('nvim')
set ttymouse=xterm2
endif
<
Conversely, if you have Nvim specific configuration items, you could do
this:
>
if has('nvim')
tnoremap <Esc> <C-\><C-n>
endif
<
For a more granular approach, use |exists()|:
>
if exists(':tnoremap')
tnoremap <Esc> <C-\><C-n>
endif
<
Now you should be able to explore Nvim more comfortably. Check |nvim| for more
information.
==============================================================================
vim:tw=78:ts=8:noet:ft=help:norl:

76
runtime/doc/nvim_provider.txt
View File

@ -1,76 +0,0 @@
*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 |remote-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 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
|msgpack-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:

112
runtime/doc/nvim_python.txt
View File

@ -1,112 +0,0 @@
*nvim_python.txt* For Nvim. {Nvim}
NVIM REFERENCE MANUAL by Thiago de Arruda
Python plugins and scripting in Nvim *nvim-python*
1. Introduction |nvim-python-intro|
2. Quickstart |nvim-python-quickstart|
3. Troubleshooting |nvim-python-troubleshooting|
==============================================================================
1. Introduction *nvim-python-intro*
Through external Python 2/3 interpreters connected via |msgpack-rpc|, Nvim
offers some support for the legacy |python-vim| and |python3| interfaces.
Note: For now only the old Vim 7.3 API is supported.
==============================================================================
2. Quickstart *nvim-python-quickstart*
If you used a package manager to install Nvim, there's a good chance that
it also provides the `neovim` Python package. If it doesn't, follow these
steps to install the package with Python's package manager, `pip`.
Note: Depending on your system, `pip` might refer to Python 2 or Python 3,
which is why the following instructions mention `pip2` or `pip3`
explicitly. If one of these is not available for you, maybe `pip`
is what you want.
To use Vim Python 2/3 plugins with Nvim, do the following:
- For Python 2 plugins, make sure an interpreter for Python 2.6 or 2.7 is
available in your `$PATH`, then install the `neovim` Python package systemwide:
>
$ sudo pip2 install neovim
<
or for the current user:
>
$ pip2 install --user neovim
<
- For Python 3 plugins, make sure an interpreter for Python 3.3 or above is
available in your `$PATH`, then install the `neovim` Python package systemwide:
>
$ sudo pip3 install neovim
<
or for the current user:
>
$ pip3 install --user neovim
<
Note: If you previously installed the package, get the latest version by
appending the `--upgrade` flag to the commands above.
==============================================================================
*g:python_host_prog*
To point Nvim to a specific Python 2 interpreter, set |g:python_host_prog|:
>
let g:python_host_prog = '/path/to/python'
<
*g:python3_host_prog*
To point Nvim to a specific Python 3 interpreter, set |g:python3_host_prog|:
>
let g:python3_host_prog = '/path/to/python3'
<
*g:loaded_python_provider*
To disable Python 2 interface, set `g:loaded_python_provider` to 1:
>
let g:loaded_python_provider = 1
<
*g:loaded_python3_provider*
To disable Python 3 interface, set `g:loaded_python3_provider` to 1:
>
let g:loaded_python3_provider = 1
<
*g:python_host_skip_check*
To disable Python 2 interpreter check, set `g:python_host_skip_check` to 1:
Note: If you disable Python 2 check, you must install neovim module properly.
>
let g:python_host_skip_check = 1
<
*g:python3_host_skip_check*
To disable Python 3 interpreter check, set `g:python3_host_skip_check` to 1:
Note: If you disable Python 3 check, you must install neovim module properly.
>
let g:python3_host_skip_check = 1
<
==============================================================================
3. Troubleshooting *nvim-python-troubleshooting*
If you are experiencing issues with a plugin that uses the `neovim` Python
client, you can use the |:CheckHealth| command to quickly rule out your setup
as a problem.
*:CheckHealth*
:CheckHealth[!] Check your setup for common problems that may be keeping a
plugin from functioning correctly. Including the output of
this command in bug reports can help reduce the amount of
time it takes to address your issue. If [!] is present, the
output will be placed in a new buffer which can make it
easier to save to a file or copy to the clipboard.
==============================================================================
vim:tw=78:ts=8:noet:ft=help:norl:

38
runtime/doc/nvim_terminal_emulator.txt
View File

@ -1,34 +1,30 @@
*nvim_terminal_emulator.txt* For Nvim. {Nvim}
*terminal_emulator.txt* {Nvim}
NVIM REFERENCE MANUAL by Thiago de Arruda
Nvim integrated terminal emulator *nvim-terminal-emulator*
Embedded terminal emulator *terminal-emulator*
1. Introduction |nvim-terminal-emulator-introduction|
2. Spawning |nvim-terminal-emulator-spawning|
3. Input |nvim-terminal-emulator-input|
4. Configuration |nvim-terminal-emulator-configuration|
1. Introduction |terminal-emulator-intro|
2. Spawning |terminal-emulator-spawning|
3. Input |terminal-emulator-input|
4. Configuration |terminal-emulator-configuration|
==============================================================================
1. Introduction *nvim-terminal-emulator-introduction*
1. Introduction *terminal-emulator-intro*
One feature that distinguishes Nvim from Vim is that it implements a mostly
complete VT220/xterm-like terminal emulator. The terminal is presented to the
user as a special buffer type, one that is asynchronously updated to mirror
the virtual terminal display as data is received from the program connected
to it. For most purposes, terminal buffers behave a lot like normal buffers
with 'nomodifiable' set.
Nvim offers a mostly complete VT220/xterm terminal emulator. The terminal is
presented as a special buffer type, asynchronously updated to mirror the
virtual terminal display as data is received from the program connected to it.
For most purposes, terminal buffers behave a lot like normal buffers with
'nomodifiable' set.
The implementation is powered by libvterm[1], a powerful abstract terminal
emulation library.
[1]: http://www.leonerd.org.uk/code/libvterm/
The implementation is powered by libvterm, a powerful abstract terminal
emulation library. http://www.leonerd.org.uk/code/libvterm/
==============================================================================
2. Spawning *nvim-terminal-emulator-spawning*
2. Spawning *terminal-emulator-spawning*
There are 3 ways to create a terminal buffer:
@ -46,7 +42,7 @@ Note that |:mksession| will "save" the terminal buffers by restarting all
programs when the session is restored.
==============================================================================
3. Input *nvim-terminal-emulator-input*
3. Input *terminal-emulator-input*
Sending input is possible by entering terminal mode, which is achieved by
pressing any key that would enter insert mode in a normal buffer (|i| or |a|
@ -90,7 +86,7 @@ Mouse input is also fully supported, and has the following behavior:
the terminal wont lose focus and the hovered window will be scrolled.
==============================================================================
4. Configuration *nvim-terminal-emulator-configuration*
4. Configuration *terminal-emulator-configuration*
Terminal buffers can be customized through the following global/buffer-local
variables (set via the |TermOpen| autocmd):

7
runtime/doc/options.txt
View File

@ -1172,8 +1172,7 @@ A jump table for the options with a short description can be found at |Q_op|.
help help buffer (you are not supposed to set this
manually)
terminal terminal buffer, this is set automatically when a
terminal is created. See |nvim-terminal-emulator| for
more information.
terminal is created. |terminal-emulator|
This option is used together with 'bufhidden' and 'swapfile' to
specify special kinds of buffers. See |special-buffers|.
@ -1353,7 +1352,7 @@ A jump table for the options with a short description can be found at |Q_op|.
used regardless of whether "unnamed" is in 'clipboard'
or not. The clipboard register can always be
explicitly accessed using the "* notation. Also see
|gui-clipboard|.
|clipboard|.
*clipboard-unnamedplus*
unnamedplus A variant of the "unnamed" flag which uses the
@ -1363,7 +1362,7 @@ A jump table for the options with a short description can be found at |Q_op|.
register. When "unnamed" is also included to the
option, yank and delete operations (but not put)
will additionally copy the text into register
'*'. See |nvim-clipboard|.
'*'. See |clipboard|.
*clipboard-autoselect*
autoselect Works like the 'a' flag in 'guioptions': If present,

139
runtime/doc/provider.txt Normal file
View File

@ -0,0 +1,139 @@
*provider.txt* {Nvim}
NVIM REFERENCE MANUAL by Thiago de Arruda
Providers *provider*
Nvim delegates some features to dynamic "providers".
==============================================================================
Python integration *provider-python*
Nvim supports the Vim legacy |python-vim| and |python3| interfaces via
external Python interpreters connected via |RPC|,
Note: Only the Vim 7.3 API is supported; bindeval (Vim 7.4) is not.
PYTHON QUICKSTART ~
If you used a package manager to install Nvim there's a good chance that
it also provides the `neovim` Python package. If it doesn't, follow these
steps to install the package with Python's package manager, `pip`.
Note: Depending on your system, `pip` might refer to Python 2 or Python 3,
which is why the following instructions mention `pip2` or `pip3`
explicitly. If one of these is not available, try `pip`.
To use Vim Python 2/3 plugins with Nvim:
- For Python 2 plugins, make sure an interpreter for Python 2.6 or 2.7 is
available in your `$PATH`, then install the `neovim` Python package systemwide: >
$ sudo pip2 install --upgrade neovim
<
or for the current user: >
$ pip2 install --user --upgrade neovim
<
- For Python 3 plugins, make sure an interpreter for Python 3.3 or above is
available in your `$PATH`, then install the `neovim` Python package systemwide: >
$ sudo pip3 install --upgrade neovim
<
or for the current user: >
$ pip3 install --user --upgrade neovim
<
Note: The `--upgrade` flag ensures you have the latest version even if
a previous version was already installed.
PYTHON PROVIDER CONFIGURATION ~
*g:python_host_prog*
Set `g:python_host_prog` to point Nvim to a specific Python 2 interpreter: >
let g:python_host_prog = '/path/to/python'
<
*g:python3_host_prog*
Set `g:python3_host_prog` to point Nvim to a specific Python 3 interpreter: >
let g:python3_host_prog = '/path/to/python3'
<
*g:loaded_python_provider*
To disable Python 2 support: >
let g:loaded_python_provider = 1
<
*g:loaded_python3_provider*
To disable Python 3 support: >
let g:loaded_python3_provider = 1
<
*g:python_host_skip_check*
Set `g:python_host_skip_check` to disable the Python 2 interpreter check.
Note: This requires you to install the python-neovim module properly. >
let g:python_host_skip_check = 1
<
*g:python3_host_skip_check*
Set `g:python3_host_skip_check` to disable the Python 3 interpreter check.
Note: This requires you to install the python3-neovim module properly. >
let g:python3_host_skip_check = 1
TROUBLESHOOTING *python-trouble*
If you have trouble with a plugin that uses the `neovim` Python client, use
the |:CheckHealth| command to diagnose your setup.
*:CheckHealth*
:CheckHealth[!] Check your setup for common problems that may be keeping a
plugin from functioning correctly. Include the output of
this command in bug reports to help reduce the amount of
time it takes to address your issue. With "!" the output
will be placed in a new buffer which can make it easier to
save to a file or copy to the clipboard.
==============================================================================
Clipboard integration *provider-clipboard* *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:

10
runtime/doc/remote_plugin.txt
View File

@ -16,8 +16,8 @@ Nvim support for remote plugins *remote-plugin*
Extensibility is a primary goal of Nvim. Any programming language may be used
to extend Nvim without changes to Nvim itself. This is achieved with remote
plugins, coprocesses that have a direct communication channel (via
|msgpack-rpc|) with the Nvim process.
plugins, coprocesses that have a direct communication channel (via |RPC|) with
the Nvim process.
Even though these plugins run in separate processes they can call, be called,
and receive events just as if the plugin's code were executed in the main
@ -33,9 +33,9 @@ check whether a plugin host is available for their chosen programming language.
Plugin hosts are programs that provide a high-level environment for plugins,
taking care of most boilerplate involved in defining commands, autocmds, and
functions that are implemented over |msgpack-rpc| connections. Hosts are
loaded only when one of their registered plugins require it, keeping Nvim's
startup as fast as possible, even if many plugins/hosts are installed.
functions that are implemented over |RPC| connections. Hosts are loaded only
when one of their registered plugins require it, keeping Nvim's startup as
fast as possible, even if many plugins/hosts are installed.
==============================================================================
3. Example *remote-plugin-example*

113
runtime/doc/spell.txt
View File

@ -1,4 +1,4 @@
*spell.txt* For Vim version 7.4. Last change: 2016 Jan 08
*spell.txt*
VIM REFERENCE MANUAL by Bram Moolenaar
@ -11,10 +11,6 @@ Spell checking *spell*
3. Generating a spell file |spell-mkspell|
4. Spell file format |spell-file-format|
Note: There also is a vimspell plugin. If you have it you can do ":help
vimspell" to find about it. But you will probably want to get rid of the
plugin and use the 'spell' option instead, it works better.
==============================================================================
1. Quick start *spell-quickstart* *E756*
@ -1633,4 +1629,111 @@ WORDCHARS (Hunspell) *spell-WORDCHARS*
is no need to separate words before checking them (using a
trie instead of a hashtable).
==============================================================================
5. Spell checker design *develop-spell*
When spell checking was going to be added to Vim a survey was done over the
available spell checking libraries and programs. Unfortunately, the result
was that none of them provided sufficient capabilities to be used as the spell
checking engine in Vim, for various reasons:
- Missing support for multi-byte encodings. At least UTF-8 must be supported,
so that more than one language can be used in the same file.
Doing on-the-fly conversion is not always possible (would require iconv
support).
- For the programs and libraries: Using them as-is would require installing
them separately from Vim. That's mostly not impossible, but a drawback.
- Performance: A few tests showed that it's possible to check spelling on the
fly (while redrawing), just like syntax highlighting. But the mechanisms
used by other code are much slower. Myspell uses a hashtable, for example.
The affix compression that most spell checkers use makes it slower too.
- For using an external program like aspell a communication mechanism would
have to be setup. That's complicated to do in a portable way (Unix-only
would be relatively simple, but that's not good enough). And performance
will become a problem (lots of process switching involved).
- Missing support for words with non-word characters, such as "Etten-Leur" and
"et al.", would require marking the pieces of them OK, lowering the
reliability.
- Missing support for regions or dialects. Makes it difficult to accept
all English words and highlight non-Canadian words differently.
- Missing support for rare words. Many words are correct but hardly ever used
and could be a misspelled often-used word.
- For making suggestions the speed is less important and requiring to install
another program or library would be acceptable. But the word lists probably
differ, the suggestions may be wrong words.
Spelling suggestions *develop-spell-suggestions*
For making suggestions there are two basic mechanisms:
1. Try changing the bad word a little bit and check for a match with a good
word. Or go through the list of good words, change them a little bit and
check for a match with the bad word. The changes are deleting a character,
inserting a character, swapping two characters, etc.
2. Perform soundfolding on both the bad word and the good words and then find
matches, possibly with a few changes like with the first mechanism.
The first is good for finding typing mistakes. After experimenting with
hashtables and looking at solutions from other spell checkers the conclusion
was that a trie (a kind of tree structure) is ideal for this. Both for
reducing memory use and being able to try sensible changes. For example, when
inserting a character only characters that lead to good words need to be
tried. Other mechanisms (with hashtables) need to try all possible letters at
every position in the word. Also, a hashtable has the requirement that word
boundaries are identified separately, while a trie does not require this.
That makes the mechanism a lot simpler.
Soundfolding is useful when someone knows how the words sounds but doesn't
know how it is spelled. For example, the word "dictionary" might be written
as "daktonerie". The number of changes that the first method would need to
try is very big, it's hard to find the good word that way. After soundfolding
the words become "tktnr" and "tkxnry", these differ by only two letters.
To find words by their soundfolded equivalent (soundalike word) we need a list
of all soundfolded words. A few experiments have been done to find out what
the best method is. Alternatives:
1. Do the sound folding on the fly when looking for suggestions. This means
walking through the trie of good words, soundfolding each word and
checking how different it is from the bad word. This is very efficient for
memory use, but takes a long time. On a fast PC it takes a couple of
seconds for English, which can be acceptable for interactive use. But for
some languages it takes more than ten seconds (e.g., German, Catalan),
which is unacceptable slow. For batch processing (automatic corrections)
it's too slow for all languages.
2. Use a trie for the soundfolded words, so that searching can be done just
like how it works without soundfolding. This requires remembering a list
of good words for each soundfolded word. This makes finding matches very
fast but requires quite a lot of memory, in the order of 1 to 10 Mbyte.
For some languages more than the original word list.
3. Like the second alternative, but reduce the amount of memory by using affix
compression and store only the soundfolded basic word. This is what Aspell
does. Disadvantage is that affixes need to be stripped from the bad word
before soundfolding it, which means that mistakes at the start and/or end
of the word will cause the mechanism to fail. Also, this becomes slow when
the bad word is quite different from the good word.
The choice made is to use the second mechanism and use a separate file. This
way a user with sufficient memory can get very good suggestions while a user
who is short of memory or just wants the spell checking and no suggestions
doesn't use so much memory.
Word frequency
For sorting suggestions it helps to know which words are common. In theory we
could store a word frequency with the word in the dictionary. However, this
requires storing a count per word. That degrades word tree compression a lot.
And maintaining the word frequency for all languages will be a heavy task.
Also, it would be nice to prefer words that are already in the text. This way
the words that appear in the specific text are preferred for suggestions.
What has been implemented is to count words that have been seen during
displaying. A hashtable is used to quickly find the word count. The count is
initialized from words listed in COMMON items in the affix file, so that it
also works when starting a new file.
This isn't ideal, because the longer Vim is running the higher the counts
become. But in practice it is a noticeable improvement over not using the word
count.
vim:tw=78:sw=4:ts=8:ft=help:norl:

2
runtime/doc/various.txt
View File

@ -220,7 +220,7 @@ g8 Print the hex values of the bytes used in the
Like |:enew|, it will fail if the current buffer is
modified, but can be forced with "!". See |termopen()|
and |nvim-terminal-emulator| for more information.
and |terminal-emulator|.
To switch to terminal mode automatically:
>

92
runtime/doc/vim_diff.txt
View File

@ -12,8 +12,8 @@ these differences.
1. Configuration |nvim-configuration|
2. Defaults |nvim-defaults|
3. Changed features |nvim-features-changed|
4. New features |nvim-features-new|
3. New features |nvim-features|
4. Changed features |nvim-features-changed|
5. Missing legacy features |nvim-features-missing|
6. Removed features |nvim-features-removed|
@ -58,7 +58,58 @@ these differences.
- 'wildmenu' is set by default
==============================================================================
3. Changed features *nvim-features-changed*
3. New Features *nvim-features*
MAJOR FEATURES ~
Embedded terminal emulator |terminal-emulator|
Shared data |shada|
RPC API |RPC|
Job control |job-control|
Remote plugins |remote-plugin|
Python plugins |provider-python|
Clipboard integration |provider-clipboard|
OTHER FEATURES ~
|bracketed-paste-mode| is built-in and enabled by default.
Meta (alt) chords are recognized (even in the terminal).
<M-1>, <M-2>, ...
<M-BS>, <M-Del>, <M-Ins>, ...
<M-/>, <M-\>, ...
<M-Space>, <M-Enter>, <M-=>, <M-->, <M-?>, <M-$>, ...
Note: Meta chords are case-sensitive (<M-a> is distinguished from <M-A>).
Some `CTRL-SHIFT-...` key chords are distinguished from `CTRL-...` variants
(even in the terminal). Specifically, the following are known to work:
<C-Tab>, <C-S-Tab>
<C-BS>, <C-S-BS>
<C-Enter>, <C-S-Enter>
Options:
'statusline' supports unlimited alignment sections
Commands:
|:CheckHealth|
Events:
|TabNew|
|TabNewEntered|
|TabClosed|
|TermOpen|
|TermClose|
Highlight groups:
|hl-EndOfBuffer|
|hl-TermCursor|
|hl-TermCursorNC|
==============================================================================
4. Changed features *nvim-features-changed*
Nvim always builds with all features, in contrast to Vim which may have
certain features removed/added at compile-time. This is like if Vim's "HUGE"
@ -68,7 +119,7 @@ build).
If a Python interpreter is available on your `$PATH`, |:python| and |:python3|
are always available and may be used simultaneously in separate plugins. The
`neovim` pip package must be installed to use Python plugins in Nvim (see
|nvim-python|).
|provider-python|).
|mkdir()| behaviour changed:
1. Assuming /tmp/foo does not exist and /tmp can be written to
@ -140,39 +191,6 @@ Additional differences:
itself.
- ShaDa file keeps search direction (|v:searchforward|), viminfo does not.
==============================================================================
4. New Features *nvim-features-new*
See |nvim-intro| for a list of Nvim's largest new features.
|bracketed-paste-mode| is built-in and enabled by default.
Meta (alt) chords are recognized (even in the terminal).
<M-1>, <M-2>, ...
<M-BS>, <M-Del>, <M-Ins>, ...
<M-/>, <M-\>, ...
<M-Space>, <M-Enter>, <M-=>, <M-->, <M-?>, <M-$>, ...
Note: Meta chords are case-sensitive (<M-a> is distinguished from <M-A>).
Some `CTRL-SHIFT-...` key chords are distinguished from `CTRL-...` variants
(even in the terminal). Specifically, the following are known to work:
<C-Tab>, <C-S-Tab>
<C-BS>, <C-S-BS>
<C-Enter>, <C-S-Enter>
Events:
|TabNew|
|TabNewEntered|
|TabClosed|
|TermOpen|
|TermClose|
Highlight groups:
|hl-EndOfBuffer|
|hl-TermCursor|
|hl-TermCursorNC|
==============================================================================
5. Missing legacy features *nvim-features-missing*
*if_ruby* *if_lua* *if_perl* *if_mzscheme* *if_tcl*

16
src/nvim/version.c
View File

@ -1904,21 +1904,15 @@ void intro_message(int colon)
N_("by Bram Moolenaar et al."),
N_("Vim is open source and freely distributable"),
"",
N_("First time using a vi-like editor?"),
N_("Type :Tutor<Enter> to get started!"),
N_("Type \":Tutor\" or \":help nvim\" to get started!"),
"",
N_("Already know your way around Vim?"),
N_("See :help nvim-intro for an introduction to Neovim."),
"",
N_("Still have questions?"),
N_("Reach out to the Neovim community at neovim.io/community."),
"",
N_("Help poor children in Uganda!"),
N_("type :help iccf<Enter> for information "),
N_("Still have questions? https://neovim.io/community"),
"",
N_("type :q<Enter> to exit "),
N_("type :help<Enter> or <F1> for on-line help"),
N_("type :help nvim<Enter> for Neovim help "),
"",
N_("Help poor children in Uganda!"),
N_("type :help iccf<Enter> for information "),
};
// blanklines = screen height - # message lines