From bd20892bdf15e45c4ea5827250e3aa0c2ace24a0 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sat, 11 Jun 2016 13:57:02 -0400 Subject: doc: Move spell design discussion. It is worth preserving, but let it live in spell.txt so we can dedicate develop.txt to nvim-specific discussion. --- runtime/doc/develop.txt | 105 -------------------------------------------- runtime/doc/spell.txt | 113 +++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 108 insertions(+), 110 deletions(-) diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 8881845fdd..7ced8dd016 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -153,110 +153,5 @@ window View on a buffer. There can be several windows in Vim, fit in the shell. -Spell checking *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:ts=8:ft=help:norl: diff --git a/runtime/doc/spell.txt b/runtime/doc/spell.txt index a767f6cbbf..0902d5d10f 100644 --- a/runtime/doc/spell.txt +++ b/runtime/doc/spell.txt @@ -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: -- cgit From 23a3e58f02e37ed5c6f8fa1f4758d0ebe1aed8d3 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 13 Jun 2016 02:11:12 -0400 Subject: doc: msgpack_rpc: De-emphasize the transport protocol. Tighten our jargon, avoid mentioning "msgpack" everywhere we mention the RPC API. Prefer "RPC API" when speaking about the remote API. Though it's conceivable that we may one day support some protocol other than msgpack, that isn't relevant to most of our discussion of the API, including this document. The file name msgpack_rpc.txt is preserved to avoid totally breaking URLs. --- runtime/doc/api.txt | 6 +- runtime/doc/develop.txt | 37 +++-- runtime/doc/eval.txt | 32 ++--- runtime/doc/msgpack_rpc.txt | 320 +++++++++++++++++++++--------------------- runtime/doc/nvim_provider.txt | 11 +- runtime/doc/nvim_python.txt | 6 +- runtime/doc/remote_plugin.txt | 10 +- 7 files changed, 205 insertions(+), 217 deletions(-) diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index ca79465e0d..c35c393c8b 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -14,7 +14,7 @@ The C API of Nvim *nvim-api* 1. Introduction *nvim-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 +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 @@ -54,8 +54,8 @@ 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* diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 7ced8dd016..4912bb7ce2 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -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. +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 -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. +Nvim is open source software. Everybody is encouraged to contribute. + https://github.com/neovim/neovim/blob/master/CONTRIBUTING.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. @@ -78,7 +74,7 @@ VIM IS... WELL DOCUMENTED *design-documented* item is easier to find. -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. @@ -95,7 +91,7 @@ fast. 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 +102,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,10 +113,9 @@ 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." ============================================================================== diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 869fcf0078..8fbfec4a1c 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -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. @@ -2030,11 +2030,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 a |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 a |rpc| request to {channel} +rpcstart({prog}[, {argv}]) Spawns {prog} and opens a |rpc| channel +rpcstop({channel}) Closes a |rpc| {channel} screenattr({row}, {col}) Number attribute at screen position screenchar({row}, {col}) Number character at screen position screencol() Number current cursor column @@ -5525,31 +5525,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 diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index bafb9dfc2c..52d2efd8da 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -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* *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, see |nvim-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* - -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: - -- 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). - -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: - +4. Implementing API clients *rpc-api-client* *api-client* + +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 + +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 + +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. |nvim-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* - -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: - -- 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`. - -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|. +6. Vimscript functions *rpc-vim-functions* + +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. + +|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: diff --git a/runtime/doc/nvim_provider.txt b/runtime/doc/nvim_provider.txt index 91cd5fbfc7..8e8483e22b 100644 --- a/runtime/doc/nvim_provider.txt +++ b/runtime/doc/nvim_provider.txt @@ -6,10 +6,9 @@ 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|. +This document is written for developers. If you are a normal user or plugin +developer looking to learn about Nvim |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|. @@ -58,8 +57,8 @@ What these functions do is simple: 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. +integration with an external system, because calling shell commands and |rpc| +clients (Nvim only) is easier to do in vimscript. Now, back to the Python example. Instead of modifying vimscript to allow for the definition of lowercase functions and commands (for the |:python|, diff --git a/runtime/doc/nvim_python.txt b/runtime/doc/nvim_python.txt index 27955a76b1..c2a86650ac 100644 --- a/runtime/doc/nvim_python.txt +++ b/runtime/doc/nvim_python.txt @@ -13,10 +13,10 @@ Python plugins and scripting in Nvim *nvim-python* ============================================================================== 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. +Through external Python interpreters connected via |rpc|, Nvim supports the +legacy |python-vim| and |python3| interfaces. -Note: For now only the old Vim 7.3 API is supported. +Note: Only the Vim 7.3 API is supported; bindeval (Vim 7.4) is not. ============================================================================== 2. Quickstart *nvim-python-quickstart* diff --git a/runtime/doc/remote_plugin.txt b/runtime/doc/remote_plugin.txt index 139fcd83b9..3a2215f11c 100644 --- a/runtime/doc/remote_plugin.txt +++ b/runtime/doc/remote_plugin.txt @@ -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* -- cgit From cc6edfe357cfe139c6f08ea645d9ff6aa8cf008c Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Tue, 14 Jun 2016 23:12:43 -0400 Subject: doc: remove "nvim-" qualfier from tags It is almost never necessary to qualify documentation as "Nvim specific". The main exception to this is vim_diff.txt. --- runtime/doc/api.txt | 37 +++++++++++++++++++------------------ runtime/doc/develop.txt | 30 +++++++++++------------------- runtime/doc/msgpack_rpc.txt | 10 +++++----- 3 files changed, 35 insertions(+), 42 deletions(-) diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index c35c393c8b..bdeca367b1 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -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: @@ -58,7 +59,7 @@ 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 diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 4912bb7ce2..658de0dce9 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -9,12 +9,12 @@ Development of Nvim. *development* 1. Design goals |design-goals| 2. Design decisions |design-decisions| -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 - Nvim is open source software. Everybody is encouraged to contribute. https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md +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* @@ -72,6 +72,9 @@ NVIM 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. NVIM IS... HIGH SPEED AND SMALL IN SIZE *design-speed-size* @@ -85,8 +88,6 @@ 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. @@ -113,25 +114,14 @@ 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 +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 The word "window" is commonly used for several things: A window on the screen, @@ -147,6 +137,8 @@ window View on a buffer. There can be several windows in Vim, together with the command line, menubar, toolbar, etc. they fit in the shell. - +RPC API +API client +remote plugin vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index 52d2efd8da..2db7c498e3 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -35,10 +35,10 @@ The RPC API is like a more powerful version of Vim's `clientserver` feature. ============================================================================== 2. API mapping *rpc-api* -The Nvim C API, see |nvim-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. +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 (|api-client|s) normally provide wrappers that hide msgpack-rpc details from application developers. The wrappers can be @@ -184,7 +184,7 @@ Vim class with methods mapped to functions prefixed with `vim_`. ============================================================================== 5. Types *rpc-types* -The Nvim C API uses custom types for all functions. |nvim-api-types| +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 -- cgit From aaec820e6edc5149e03c7a835650ff19fb2c535a Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Tue, 14 Jun 2016 23:47:10 -0400 Subject: doc: Remove gui_w32.txt It's no longer relevant, except for 2 sections which are tracked as issues #4927 and #4928. --- runtime/doc/gui_w32.txt | 437 ------------------------------------------------ 1 file changed, 437 deletions(-) delete mode 100644 runtime/doc/gui_w32.txt diff --git a/runtime/doc/gui_w32.txt b/runtime/doc/gui_w32.txt deleted file mode 100644 index 228be9eab2..0000000000 --- a/runtime/doc/gui_w32.txt +++ /dev/null @@ -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. -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. - - *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- 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 :simalt f -This makes Alt-F pop down the 'File' menu (with the stock Menu.vim) by -simulating the keystrokes Alt, F. > - :map :simalt ~ -This maps Alt-Space to pop down the system menu for the Vim window. Note that -~ is used by simalt to represent the character. > - :map :simalt ~n -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: -- cgit From 4bad05ba97bdfb2dad6c834cfd22518d8be855df Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Wed, 15 Jun 2016 00:28:40 -0400 Subject: doc/clipboard: cleanup --- runtime/autoload/provider/clipboard.vim | 2 +- runtime/doc/change.txt | 2 +- runtime/doc/gui.txt | 4 ++-- runtime/doc/nvim.txt | 2 +- runtime/doc/nvim_clipboard.txt | 30 ++++++++++++++---------------- runtime/doc/nvim_from_vim.txt | 4 ++-- runtime/doc/nvim_provider.txt | 9 ++++----- runtime/doc/options.txt | 4 ++-- 8 files changed, 27 insertions(+), 30 deletions(-) diff --git a/runtime/autoload/provider/clipboard.vim b/runtime/autoload/provider/clipboard.vim index 2272519dfd..77bc8c781d 100644 --- a/runtime/autoload/provider/clipboard.vim +++ b/runtime/autoload/provider/clipboard.vim @@ -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 diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt index c3f1b69da7..4565cdf63e 100644 --- a/runtime/doc/change.txt +++ b/runtime/doc/change.txt @@ -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 diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt index 8d97678af2..e2fb501ac5 100644 --- a/runtime/doc/gui.txt +++ b/runtime/doc/gui.txt @@ -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 diff --git a/runtime/doc/nvim.txt b/runtime/doc/nvim.txt index a7c512d1dc..eb99c4047c 100644 --- a/runtime/doc/nvim.txt +++ b/runtime/doc/nvim.txt @@ -15,7 +15,7 @@ see |help.txt|. 3. Msgpack-RPC |msgpack-rpc| 4. Job control |job-control| 5. Python plugins |nvim-python| -6. Clipboard integration |nvim-clipboard| +6. Clipboard integration |clipboard| 7. Remote plugins |remote-plugin| 8. Provider infrastructure |nvim-provider| 9. Integrated terminal emulator |nvim-terminal-emulator| diff --git a/runtime/doc/nvim_clipboard.txt b/runtime/doc/nvim_clipboard.txt index 078382c7a7..9a747a1cf3 100644 --- a/runtime/doc/nvim_clipboard.txt +++ b/runtime/doc/nvim_clipboard.txt @@ -4,28 +4,26 @@ NVIM REFERENCE MANUAL by Thiago de Arruda -Clipboard integration for Nvim *nvim-clipboard* +Clipboard integration for Nvim *clipboard* -1. Intro |nvim-clipboard-intro| -2. X11 selection mechanism |nvim-clipboard-x11| +1. Intro |clipboard-intro| +2. X11 selection mechanism |clipboard-x11| ============================================================================== -1. Intro *nvim-clipboard-intro* +1. Intro *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. +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 -is found in your `$PATH`. +are 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/ + - 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. @@ -39,7 +37,7 @@ following option: See 'clipboard' for details and more options. ============================================================================== -2. X11 selection mechanism *nvim-clipboard-x11* *x11-selection* +2. X11 selection mechanism *clipboard-x11* *x11-selection* The clipboard providers for X11 store text in what is known as "selections". Selections are "owned" by an application, so when the application is closed, diff --git a/runtime/doc/nvim_from_vim.txt b/runtime/doc/nvim_from_vim.txt index 299eeb05f5..a8a5c35aae 100644 --- a/runtime/doc/nvim_from_vim.txt +++ b/runtime/doc/nvim_from_vim.txt @@ -16,8 +16,8 @@ it: 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. +See |nvim-intro|, especially |nvim-python| and |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|. diff --git a/runtime/doc/nvim_provider.txt b/runtime/doc/nvim_provider.txt index 8e8483e22b..09b3d5a3e7 100644 --- a/runtime/doc/nvim_provider.txt +++ b/runtime/doc/nvim_provider.txt @@ -6,11 +6,10 @@ Nvim provider infrastructure *nvim-provider* -This document is written for developers. If you are a normal user or plugin -developer looking to learn about Nvim |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|. +This document is for developers. If you are a normal user or plugin developer +looking to learn about Nvim |rpc| for implementing plugins in other +programming languages, see |remote-plugin|. For instructions on how to enable +Python plugins, see |nvim-python|. For clipboard, see |clipboard|. Instead of doing everything by itself, Nvim aims to simplify its own maintenance by delegating as much work as possible to external systems. But diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index ea0a18c6f3..2f1f8d1787 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -1353,7 +1353,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 +1363,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, -- cgit From 30a7d551ee54d03ae47d5566e0daff9302b3fefa Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Wed, 15 Jun 2016 00:33:48 -0400 Subject: doc/terminal: cleanup --- runtime/doc/eval.txt | 2 +- runtime/doc/nvim.txt | 2 +- runtime/doc/nvim_terminal_emulator.txt | 38 +++++++++++++++------------------- runtime/doc/options.txt | 3 +-- runtime/doc/various.txt | 2 +- 5 files changed, 21 insertions(+), 26 deletions(-) diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 8fbfec4a1c..86cab08982 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -6840,7 +6840,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| diff --git a/runtime/doc/nvim.txt b/runtime/doc/nvim.txt index eb99c4047c..5f41b8611b 100644 --- a/runtime/doc/nvim.txt +++ b/runtime/doc/nvim.txt @@ -18,7 +18,7 @@ see |help.txt|. 6. Clipboard integration |clipboard| 7. Remote plugins |remote-plugin| 8. Provider infrastructure |nvim-provider| -9. Integrated terminal emulator |nvim-terminal-emulator| +9. Integrated terminal emulator |terminal-emulator| ============================================================================== vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt index 6ef3aaebaa..45695ccf02 100644 --- a/runtime/doc/nvim_terminal_emulator.txt +++ b/runtime/doc/nvim_terminal_emulator.txt @@ -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): diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 2f1f8d1787..50b1262347 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -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|. diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt index a2c0f45b23..97c04d54e0 100644 --- a/runtime/doc/various.txt +++ b/runtime/doc/various.txt @@ -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: > -- cgit From c698ed05310034d38192174d20da6926586be3ca Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Wed, 15 Jun 2016 00:42:17 -0400 Subject: doc: cleanup --- runtime/autoload/provider/python.vim | 2 +- runtime/autoload/provider/python3.vim | 2 +- runtime/doc/nvim.txt | 2 +- runtime/doc/nvim_provider.txt | 74 ----------------------------------- runtime/doc/provider.txt | 74 +++++++++++++++++++++++++++++++++++ 5 files changed, 77 insertions(+), 77 deletions(-) delete mode 100644 runtime/doc/nvim_provider.txt create mode 100644 runtime/doc/provider.txt diff --git a/runtime/autoload/provider/python.vim b/runtime/autoload/provider/python.vim index cb9d5c5296..b99a046375 100644 --- a/runtime/autoload/provider/python.vim +++ b/runtime/autoload/provider/python.vim @@ -1,5 +1,5 @@ " The Python provider uses a Python host to emulate an environment for running -" python-vim plugins. See ":help nvim-provider" for more information. +" python-vim plugins. See ":help provider". " " Associating the plugin with the Python host is the first step because plugins " will be passed as command-line arguments diff --git a/runtime/autoload/provider/python3.vim b/runtime/autoload/provider/python3.vim index f4a751e7a2..4f47a03a9b 100644 --- a/runtime/autoload/provider/python3.vim +++ b/runtime/autoload/provider/python3.vim @@ -1,5 +1,5 @@ " The Python3 provider uses a Python3 host to emulate an environment for running -" python3 plugins. See ":help nvim-provider" for more information. +" python3 plugins. See ":help provider". " " Associating the plugin with the Python3 host is the first step because " plugins will be passed as command-line arguments diff --git a/runtime/doc/nvim.txt b/runtime/doc/nvim.txt index 5f41b8611b..00740dbe93 100644 --- a/runtime/doc/nvim.txt +++ b/runtime/doc/nvim.txt @@ -17,7 +17,7 @@ see |help.txt|. 5. Python plugins |nvim-python| 6. Clipboard integration |clipboard| 7. Remote plugins |remote-plugin| -8. Provider infrastructure |nvim-provider| +8. Provider infrastructure |provider| 9. Integrated terminal emulator |terminal-emulator| ============================================================================== diff --git a/runtime/doc/nvim_provider.txt b/runtime/doc/nvim_provider.txt deleted file mode 100644 index 09b3d5a3e7..0000000000 --- a/runtime/doc/nvim_provider.txt +++ /dev/null @@ -1,74 +0,0 @@ -*nvim_provider.txt* For Nvim. {Nvim} - - - NVIM REFERENCE MANUAL by Thiago de Arruda - - -Nvim provider infrastructure *nvim-provider* - -This document is for developers. If you are a normal user or plugin developer -looking to learn about Nvim |rpc| for implementing plugins in other -programming languages, see |remote-plugin|. For instructions on how to enable -Python plugins, see |nvim-python|. For clipboard, see |clipboard|. - -Instead of doing everything by itself, Nvim aims to simplify its own -maintenance by delegating as much work as possible to external systems. But -some Vim components are too tightly coupled and in some cases the refactoring -work necessary to swap in-house implementations by code that integrates to -other systems is too great. Nvim provider infrastructure is a facility that -aims to make this task simpler. - -To understand why the provider infrastructure is useful, let us consider two -examples of integration with external systems that are implemented in Vim and -are now decoupled from Nvim core as providers: - -The first example is clipboard integration: in the original Vim source code, -clipboard functions account for more than 1k lines of C source code (and that -is just on ui.c), all to perform two tasks that are now accomplished with -simple shell commands such as xclip or pbcopy/pbpaste. - -The other example is Python scripting support: Vim has three files dedicated to -embedding the Python interpreter: if_python.c, if_python3.c and if_py_both.h. -Together these files sum about 9.5k lines of C source code. On Nvim, Python -scripting is performed by an external host process that is running 2k sloc -Python program. - -In a perfect world, we would implement Python and clipboard integration in -pure vimscript and without touching the C code. Unfortunately we can't achieve -these goals without severely compromising backwards compatibility with Vim. -That's where providers come to the rescue. - -In essence, this infrastructure is a simple framework that simplifies the task -of calling vimscript from C code, making it simpler to rewrite C functions that -interact with external systems in pure vimscript. It is composed of two -functions in eval.c: - -- eval_call_provider(name, method, arguments): Call a provider(name) method - with arguments -- eval_has_provider(name): Checks if a provider is implemented - -What these functions do is simple: - -- eval_call_provider will call the provider#(name)#Call function passing in - the method and arguments. -- eval_has_provider will return true if the provider#(name)#Call function is - implemented, and is called by the "has" vimscript function to check if - features are available. - -The basic idea is that the provider#(name)#Call function should implement -integration with an external system, because calling shell commands and |rpc| -clients (Nvim only) is easier to do in vimscript. - -Now, back to the Python example. Instead of modifying vimscript to allow for -the definition of lowercase functions and commands (for the |:python|, -|:pyfile|, and |:pydo| commands, and the |pyeval()| function), which would -break backwards compatibility with Vim, we implemented the -autoload/provider/python.vim script and the provider#python#Call function -that is only defined if an external Python host is started successfully. - -That works well with the `has('python')` expression (normally used by Python -plugins) because if the Python host isn't installed then the plugin will -"think" it is running in a Vim compiled without |+python| feature. - -============================================================================== - vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt new file mode 100644 index 0000000000..c139105f28 --- /dev/null +++ b/runtime/doc/provider.txt @@ -0,0 +1,74 @@ +*provider.txt* {Nvim} + + + NVIM REFERENCE MANUAL by Thiago de Arruda + + +Nvim provider infrastructure *provider* + +This document is for developers. If you are a normal user or plugin developer +looking to learn about Nvim |rpc| for implementing plugins in other +programming languages, see |remote-plugin|. For instructions on how to enable +Python plugins, see |nvim-python|. For clipboard, see |clipboard|. + +Instead of doing everything by itself, Nvim aims to simplify its own +maintenance by delegating as much work as possible to external systems. But +some Vim components are too tightly coupled and in some cases the refactoring +work necessary to swap in-house implementations by code that integrates to +other systems is too great. Nvim provider infrastructure is a facility that +aims to make this task simpler. + +To understand why the provider infrastructure is useful, let us consider two +examples of integration with external systems that are implemented in Vim and +are now decoupled from Nvim core as providers: + +The first example is clipboard integration: in the original Vim source code, +clipboard functions account for more than 1k lines of C source code (and that +is just on ui.c), all to perform two tasks that are now accomplished with +simple shell commands such as xclip or pbcopy/pbpaste. + +The other example is Python scripting support: Vim has three files dedicated to +embedding the Python interpreter: if_python.c, if_python3.c and if_py_both.h. +Together these files sum about 9.5k lines of C source code. On Nvim, Python +scripting is performed by an external host process that is running 2k sloc +Python program. + +In a perfect world, we would implement Python and clipboard integration in +pure vimscript and without touching the C code. Unfortunately we can't achieve +these goals without severely compromising backwards compatibility with Vim. +That's where providers come to the rescue. + +In essence, this infrastructure is a simple framework that simplifies the task +of calling vimscript from C code, making it simpler to rewrite C functions that +interact with external systems in pure vimscript. It is composed of two +functions in eval.c: + +- eval_call_provider(name, method, arguments): Call a provider(name) method + with arguments +- eval_has_provider(name): Checks if a provider is implemented + +What these functions do is simple: + +- eval_call_provider will call the provider#(name)#Call function passing in + the method and arguments. +- eval_has_provider will return true if the provider#(name)#Call function is + implemented, and is called by the "has" vimscript function to check if + features are available. + +The basic idea is that the provider#(name)#Call function should implement +integration with an external system, because calling shell commands and |rpc| +clients (Nvim only) is easier to do in vimscript. + +Now, back to the Python example. Instead of modifying vimscript to allow for +the definition of lowercase functions and commands (for the |:python|, +|:pyfile|, and |:pydo| commands, and the |pyeval()| function), which would +break backwards compatibility with Vim, we implemented the +autoload/provider/python.vim script and the provider#python#Call function +that is only defined if an external Python host is started successfully. + +That works well with the `has('python')` expression (normally used by Python +plugins) because if the Python host isn't installed then the plugin will +"think" it is running in a Vim compiled without |+python| feature. + +============================================================================== + vim:tw=78:ts=8:noet:ft=help:norl: -- cgit From 7718f8f24c9e795103b639367a90992dd161bd01 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Wed, 15 Jun 2016 01:20:08 -0400 Subject: doc/provider: cleanup - Move design/impl discussion to develop.txt - Move clipboard notes to provider.txt --- runtime/doc/autocmd.txt | 3 +- runtime/doc/develop.txt | 47 ++++++++++++++++- runtime/doc/nvim_clipboard.txt | 61 ---------------------- runtime/doc/provider.txt | 116 ++++++++++++++++++----------------------- 4 files changed, 98 insertions(+), 129 deletions(-) delete mode 100644 runtime/doc/nvim_clipboard.txt diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 25ae94f784..6641732679 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -912,8 +912,7 @@ TermClose When a terminal buffer ends. {Nvim} *TermOpen* TermOpen When a terminal buffer is starting. This can be used to configure the terminal emulator by - setting buffer variables. - See |nvim-terminal-emulator| for details. + setting buffer variables. |terminal-emulator| *TermResponse* TermResponse After the response to |t_RV| is received from the terminal. The value of |v:termresponse| diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 658de0dce9..4013544311 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -122,7 +122,7 @@ include the kitchen sink... but you can use it for plumbing." ============================================================================== 2. Design decisions *design-decisions* -Naming the window +Window The word "window" is commonly used for several things: A window on the screen, the xterm window, a window inside Vim to view a buffer. @@ -137,6 +137,51 @@ window View on a buffer. There can be several windows in Vim, together with the command line, menubar, toolbar, etc. they fit in the shell. + +Providers *dev-provider* + +A goal of Nvim is to allow extension of the editor without special knowledge +in the core. But some Vim components are too tightly coupled; in those cases +a "provider" hook is exposed. + +Consider two examples of integration with external systems that are +implemented in Vim and are now decoupled from Nvim core as providers: + +1. In the Vim source code, clipboard logic accounts for more than 1k lines of + C source code (ui.c), to perform two tasks that are now accomplished with + shell commands such as xclip or pbcopy/pbpaste. + +2. Python scripting support: Vim has three files dedicated to embedding the + Python interpreter: if_python.c, if_python3.c and if_py_both.h. Together + these files sum about 9.5k lines of C source code. In contrast, Nvim Python + scripting is performed by an external host process implemented in ~2k lines + of Python. + +Ideally we could implement Python and clipboard integration in pure vimscript +and without touching the C code. But this is infeasible without compromising +backwards compatibility with Vim; that's where providers help. + +The provider framework helps call vimscript from C. It is composed of two +functions in eval.c: + +- eval_call_provider(name, method, arguments): calls provider#(name)#Call + with the method and arguments. +- eval_has_provider(name): Checks if a provider is implemented. Returns true + if the provider#(name)#Call function is implemented. Called by |has()| + (vimscript) to check if features are available. + +The provider#(name)#Call function implements integration with an external +system, because calling shell commands and |rpc| clients are easier to work +with in vimscript. + +For example, the Python provider is implemented by the +autoload/provider/python.vim script; the provider#python#Call function is only +defined if a valid external Python host is found. That works well with the +`has('python')` expression (normally used by Python plugins) because if the +Python host isn't installed then the plugin will "think" it is running in +a Vim compiled without the |+python| feature. + + RPC API API client remote plugin diff --git a/runtime/doc/nvim_clipboard.txt b/runtime/doc/nvim_clipboard.txt deleted file mode 100644 index 9a747a1cf3..0000000000 --- a/runtime/doc/nvim_clipboard.txt +++ /dev/null @@ -1,61 +0,0 @@ -*nvim_clipboard.txt* For Nvim. {Nvim} - - - NVIM REFERENCE MANUAL by Thiago de Arruda - - -Clipboard integration for Nvim *clipboard* - -1. Intro |clipboard-intro| -2. X11 selection mechanism |clipboard-x11| - -============================================================================== -1. Intro *clipboard-intro* - -Nvim has no direct connection to the system clipboard. Instead it is -accessible through a |provider| which transparently uses shell commands for -communicating with the clipboard. - -Clipboard access is implicitly enabled if any of the following clipboard tools -are found in your `$PATH`. - - - xclip - - xsel (newer alternative to xclip) - - pbcopy/pbpaste (Mac OS X) - - lemonade (for SSH) https://github.com/pocke/lemonade - - doitclient (for SSH) http://www.chiark.greenend.org.uk/~sgtatham/doit/ - -The presence of a suitable clipboard tool implicitly enables the '+' and '*' -registers. - -If you want to ALWAYS use the clipboard for ALL operations (as opposed -to interacting with the '+' and/or '*' registers explicitly), set the -following option: -> - set clipboard+=unnamedplus -< -See 'clipboard' for details and more options. - -============================================================================== -2. X11 selection mechanism *clipboard-x11* *x11-selection* - -The clipboard providers for X11 store text in what is known as "selections". -Selections are "owned" by an application, so when the application is closed, -the selection text is lost. - -The contents of selections are held by the originating application (e.g., upon -a copy), and only passed on to another application when that other application -asks for them (e.g., upon a paste). - - *quoteplus* *quote+* - -There are three documented X11 selections: `PRIMARY`, `SECONDARY`, and `CLIPBOARD`. -`CLIPBOARD` is typically used in X11 applications for copy/paste operations -(`Ctrl-c`/`v`), while `PRIMARY` is used for the last selected text, which is -generally inserted with the middle mouse button. - -Nvim's X11 clipboard providers only utilize the `PRIMARY` and `CLIPBOARD` -selections, used for the '*' and '+' registers, respectively. - -============================================================================== - vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt index c139105f28..5c335a39ef 100644 --- a/runtime/doc/provider.txt +++ b/runtime/doc/provider.txt @@ -4,71 +4,57 @@ NVIM REFERENCE MANUAL by Thiago de Arruda -Nvim provider infrastructure *provider* - -This document is for developers. If you are a normal user or plugin developer -looking to learn about Nvim |rpc| for implementing plugins in other -programming languages, see |remote-plugin|. For instructions on how to enable -Python plugins, see |nvim-python|. For clipboard, see |clipboard|. - -Instead of doing everything by itself, Nvim aims to simplify its own -maintenance by delegating as much work as possible to external systems. But -some Vim components are too tightly coupled and in some cases the refactoring -work necessary to swap in-house implementations by code that integrates to -other systems is too great. Nvim provider infrastructure is a facility that -aims to make this task simpler. - -To understand why the provider infrastructure is useful, let us consider two -examples of integration with external systems that are implemented in Vim and -are now decoupled from Nvim core as providers: - -The first example is clipboard integration: in the original Vim source code, -clipboard functions account for more than 1k lines of C source code (and that -is just on ui.c), all to perform two tasks that are now accomplished with -simple shell commands such as xclip or pbcopy/pbpaste. - -The other example is Python scripting support: Vim has three files dedicated to -embedding the Python interpreter: if_python.c, if_python3.c and if_py_both.h. -Together these files sum about 9.5k lines of C source code. On Nvim, Python -scripting is performed by an external host process that is running 2k sloc -Python program. - -In a perfect world, we would implement Python and clipboard integration in -pure vimscript and without touching the C code. Unfortunately we can't achieve -these goals without severely compromising backwards compatibility with Vim. -That's where providers come to the rescue. - -In essence, this infrastructure is a simple framework that simplifies the task -of calling vimscript from C code, making it simpler to rewrite C functions that -interact with external systems in pure vimscript. It is composed of two -functions in eval.c: - -- eval_call_provider(name, method, arguments): Call a provider(name) method - with arguments -- eval_has_provider(name): Checks if a provider is implemented - -What these functions do is simple: - -- eval_call_provider will call the provider#(name)#Call function passing in - the method and arguments. -- eval_has_provider will return true if the provider#(name)#Call function is - implemented, and is called by the "has" vimscript function to check if - features are available. - -The basic idea is that the provider#(name)#Call function should implement -integration with an external system, because calling shell commands and |rpc| -clients (Nvim only) is easier to do in vimscript. - -Now, back to the Python example. Instead of modifying vimscript to allow for -the definition of lowercase functions and commands (for the |:python|, -|:pyfile|, and |:pydo| commands, and the |pyeval()| function), which would -break backwards compatibility with Vim, we implemented the -autoload/provider/python.vim script and the provider#python#Call function -that is only defined if an external Python host is started successfully. - -That works well with the `has('python')` expression (normally used by Python -plugins) because if the Python host isn't installed then the plugin will -"think" it is running in a Vim compiled without |+python| feature. +Providers *provider* + +Nvim delegates some features to dynamic "providers". + +============================================================================== +Clipboard integration *clipboard* + +Nvim has no direct connection to the system clipboard. Instead it is +accessible through a |provider| which transparently uses shell commands for +communicating with the clipboard. + +Clipboard access is implicitly enabled if any of the following clipboard tools +are found in your `$PATH`. + + - xclip + - xsel (newer alternative to xclip) + - pbcopy/pbpaste (Mac OS X) + - lemonade (for SSH) https://github.com/pocke/lemonade + - doitclient (for SSH) http://www.chiark.greenend.org.uk/~sgtatham/doit/ + +The presence of a suitable clipboard tool implicitly enables the '+' and '*' +registers. + +If you want to ALWAYS use the clipboard for ALL operations (as opposed +to interacting with the '+' and/or '*' registers explicitly), set the +following option: +> + set clipboard+=unnamedplus +< +See 'clipboard' for details and more options. + +============================================================================== +X11 selection mechanism *clipboard-x11* *x11-selection* + +The clipboard providers for X11 store text in what is known as "selections". +Selections are "owned" by an application, so when the application is closed, +the selection text is lost. + +The contents of selections are held by the originating application (e.g., upon +a copy), and only passed on to another application when that other application +asks for them (e.g., upon a paste). + + *quoteplus* *quote+* + +There are three documented X11 selections: `PRIMARY`, `SECONDARY`, and `CLIPBOARD`. +`CLIPBOARD` is typically used in X11 applications for copy/paste operations +(`Ctrl-c`/`v`), while `PRIMARY` is used for the last selected text, which is +generally inserted with the middle mouse button. + +Nvim's X11 clipboard providers only utilize the `PRIMARY` and `CLIPBOARD` +selections, used for the '*' and '+' registers, respectively. ============================================================================== vim:tw=78:ts=8:noet:ft=help:norl: -- cgit From 37f560aedf36043d479775ccc20447801b615126 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Wed, 15 Jun 2016 01:53:00 -0400 Subject: doc/python: cleanup - Move info to providers.txt - Remove "nvim-" prefix. - Brevity, clarity, ... --- runtime/autoload/provider/pythonx.vim | 2 +- runtime/doc/if_pyth.txt | 2 +- runtime/doc/nvim.txt | 7 +-- runtime/doc/nvim_from_vim.txt | 4 +- runtime/doc/nvim_python.txt | 112 ---------------------------------- runtime/doc/provider.txt | 83 ++++++++++++++++++++++++- runtime/doc/vim_diff.txt | 8 ++- 7 files changed, 95 insertions(+), 123 deletions(-) delete mode 100644 runtime/doc/nvim_python.txt diff --git a/runtime/autoload/provider/pythonx.vim b/runtime/autoload/provider/pythonx.vim index c3256e8308..0ebf00112f 100644 --- a/runtime/autoload/provider/pythonx.vim +++ b/runtime/autoload/provider/pythonx.vim @@ -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] diff --git a/runtime/doc/if_pyth.txt b/runtime/doc/if_pyth.txt index f6bd365299..8946dd2e5a 100644 --- a/runtime/doc/if_pyth.txt +++ b/runtime/doc/if_pyth.txt @@ -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* diff --git a/runtime/doc/nvim.txt b/runtime/doc/nvim.txt index 00740dbe93..b8157cc714 100644 --- a/runtime/doc/nvim.txt +++ b/runtime/doc/nvim.txt @@ -14,11 +14,10 @@ see |help.txt|. 2. Differences from Vim |vim-differences| 3. Msgpack-RPC |msgpack-rpc| 4. Job control |job-control| -5. Python plugins |nvim-python| -6. Clipboard integration |clipboard| +5. Python plugins |provider-python| +6. Clipboard integration |provider-clipboard| 7. Remote plugins |remote-plugin| -8. Provider infrastructure |provider| -9. Integrated terminal emulator |terminal-emulator| +8. Embedded terminal emulator |terminal-emulator| ============================================================================== vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/nvim_from_vim.txt b/runtime/doc/nvim_from_vim.txt index a8a5c35aae..e078fc0110 100644 --- a/runtime/doc/nvim_from_vim.txt +++ b/runtime/doc/nvim_from_vim.txt @@ -16,8 +16,8 @@ it: ln -s ~/.vim $XDG_CONFIG_HOME/nvim ln -s ~/.vimrc $XDG_CONFIG_HOME/nvim/init.vim < -See |nvim-intro|, especially |nvim-python| and |clipboard|, for additional -software you might need to install to use all of Nvim's features. +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|. diff --git a/runtime/doc/nvim_python.txt b/runtime/doc/nvim_python.txt deleted file mode 100644 index c2a86650ac..0000000000 --- a/runtime/doc/nvim_python.txt +++ /dev/null @@ -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 interpreters connected via |rpc|, Nvim supports the -legacy |python-vim| and |python3| interfaces. - -Note: Only the Vim 7.3 API is supported; bindeval (Vim 7.4) is not. - -============================================================================== -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: diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt index 5c335a39ef..b25abb1bfd 100644 --- a/runtime/doc/provider.txt +++ b/runtime/doc/provider.txt @@ -9,7 +9,86 @@ Providers *provider* Nvim delegates some features to dynamic "providers". ============================================================================== -Clipboard integration *clipboard* +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 @@ -36,7 +115,7 @@ following option: See 'clipboard' for details and more options. ============================================================================== -X11 selection mechanism *clipboard-x11* *x11-selection* +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, diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index 508712ca75..8fdd59f2af 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -68,7 +68,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 @@ -161,6 +161,12 @@ Some `CTRL-SHIFT-...` key chords are distinguished from `CTRL-...` variants , , +Options: + 'statusline' supports unlimited alignment sections + +Commands: + |:CheckHealth| + Events: |TabNew| |TabNewEntered| -- cgit From 2dbf0400483be7c92c9a2f389ffa33ec48d8dff0 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Wed, 15 Jun 2016 01:59:28 -0400 Subject: doc: uppercase RPC --- runtime/doc/develop.txt | 4 ++-- runtime/doc/eval.txt | 16 ++++++++-------- runtime/doc/msgpack_rpc.txt | 2 +- runtime/doc/provider.txt | 2 +- runtime/doc/remote_plugin.txt | 4 ++-- 5 files changed, 14 insertions(+), 14 deletions(-) diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 4013544311..4c02dba3d6 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -171,8 +171,8 @@ functions in eval.c: (vimscript) to check if features are available. The provider#(name)#Call function implements integration with an external -system, because calling shell commands and |rpc| clients are easier to work -with in vimscript. +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 diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 86cab08982..0f6f7da997 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -2030,11 +2030,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 |rpc| notification to {channel} + Sends an |RPC| notification to {channel} rpcrequest({channel}, {method}[, {args}...]) - Sends a |rpc| request to {channel} -rpcstart({prog}[, {argv}]) Spawns {prog} and opens a |rpc| channel -rpcstop({channel}) Closes a |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 @@ -5525,20 +5525,20 @@ round({expr}) *round()* < -5.0 rpcnotify({channel}, {event}[, {args}...]) {Nvim} *rpcnotify()* - Sends {event} to {channel} via |rpc| and returns immediately. + 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 - |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 an |rpc| channel with the spawned process's + 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()| @@ -5547,7 +5547,7 @@ rpcstart({prog}[, {argv}]) {Nvim} *rpcstart()* :let rpc_chan = rpcstart('prog', ['arg1', 'arg2']) rpcstop({channel}) {Nvim} *rpcstop()* - Closes an |rpc| {channel}, possibly created via + Closes an |RPC| {channel}, possibly created via |rpcstart()|. Also closes channels created by connections to |v:servername|. diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index 2db7c498e3..2c4b1b35bc 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -4,7 +4,7 @@ NVIM REFERENCE MANUAL by Thiago de Arruda -RPC API for Nvim *rpc* *msgpack-rpc* +RPC API for Nvim *RPC* *rpc* *msgpack-rpc* 1. Introduction |rpc-intro| 2. API mapping |rpc-api| diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt index b25abb1bfd..db5c61879c 100644 --- a/runtime/doc/provider.txt +++ b/runtime/doc/provider.txt @@ -12,7 +12,7 @@ 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|, +external Python interpreters connected via |RPC|, Note: Only the Vim 7.3 API is supported; bindeval (Vim 7.4) is not. diff --git a/runtime/doc/remote_plugin.txt b/runtime/doc/remote_plugin.txt index 3a2215f11c..d906096a86 100644 --- a/runtime/doc/remote_plugin.txt +++ b/runtime/doc/remote_plugin.txt @@ -16,7 +16,7 @@ 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 |rpc|) with +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, @@ -33,7 +33,7 @@ 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 |rpc| connections. Hosts are loaded only +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. -- cgit From 742787fe9e9016971edf0eefc7cd9a1d19f73008 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Wed, 15 Jun 2016 21:33:47 -0400 Subject: doc: consolidate nvim.txt --- runtime/doc/develop.txt | 2 + runtime/doc/nvim.txt | 61 ++++++++++++++++++++------- runtime/doc/nvim_from_vim.txt | 50 ---------------------- runtime/doc/vim_diff.txt | 96 ++++++++++++++++++++++++------------------- src/nvim/version.c | 14 ++----- 5 files changed, 107 insertions(+), 116 deletions(-) delete mode 100644 runtime/doc/nvim_from_vim.txt diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 4c02dba3d6..1b77d87aac 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -75,6 +75,8 @@ NVIM IS... WELL DOCUMENTED *design-documented* - 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|. NVIM IS... HIGH SPEED AND SMALL IN SIZE *design-speed-size* diff --git a/runtime/doc/nvim.txt b/runtime/doc/nvim.txt index b8157cc714..904fb3c16c 100644 --- a/runtime/doc/nvim.txt +++ b/runtime/doc/nvim.txt @@ -1,23 +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 |provider-python| -6. Clipboard integration |provider-clipboard| -7. Remote plugins |remote-plugin| -8. Embedded terminal emulator |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 + endif +< +For a more granular approach use |exists()|: +> + if exists(':tnoremap') + tnoremap + 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: diff --git a/runtime/doc/nvim_from_vim.txt b/runtime/doc/nvim_from_vim.txt deleted file mode 100644 index e078fc0110..0000000000 --- a/runtime/doc/nvim_from_vim.txt +++ /dev/null @@ -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 |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 - endif -< -For a more granular approach, use |exists()|: -> - if exists(':tnoremap') - tnoremap - 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: diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index 8fdd59f2af..d30b0833db 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -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). + , , ... + , , , ... + , , ... + , , , , , , ... + + Note: Meta chords are case-sensitive ( is distinguished from ). + +Some `CTRL-SHIFT-...` key chords are distinguished from `CTRL-...` variants +(even in the terminal). Specifically, the following are known to work: + , + , + , + +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" @@ -140,45 +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). - , , ... - , , , ... - , , ... - , , , , , , ... - - Note: Meta chords are case-sensitive ( is distinguished from ). - -Some `CTRL-SHIFT-...` key chords are distinguished from `CTRL-...` variants -(even in the terminal). Specifically, the following are known to work: - , - , - , - -Options: - 'statusline' supports unlimited alignment sections - -Commands: - |:CheckHealth| - -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* diff --git a/src/nvim/version.c b/src/nvim/version.c index 04a6f63451..f0b4669462 100644 --- a/src/nvim/version.c +++ b/src/nvim/version.c @@ -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 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? https://neovim.io/community"), "", - N_("Still have questions?"), - N_("Reach out to the Neovim community at neovim.io/community."), + N_("type :q to exit "), + N_("type :help or for on-line help"), "", N_("Help poor children in Uganda!"), N_("type :help iccf for information "), - "", - N_("type :q to exit "), - N_("type :help or for on-line help"), - N_("type :help nvim for Neovim help "), }; // blanklines = screen height - # message lines -- cgit From 464bc16f81361a461c1da2769f13cebd82f067be Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 16 Jun 2016 00:27:11 -0400 Subject: build: Purge docs before rebuilding. If a help file is renamed, stale help files in the build workspace will cause duplicate tags (which causes the build to fail). To avoid this, always delete build/runtime/doc/ before building helptags. --- runtime/CMakeLists.txt | 18 +++++------------- 1 file changed, 5 insertions(+), 13 deletions(-) diff --git a/runtime/CMakeLists.txt b/runtime/CMakeLists.txt index 4dbd193dab..a30bae388d 100644 --- a/runtime/CMakeLists.txt +++ b/runtime/CMakeLists.txt @@ -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} -- cgit