runtime: Some nvim documentation fixes pointed by @oni-link

This commit is contained in:
Thiago de Arruda 2014-09-14 10:42:23 -03:00
parent 037ca796a0
commit e59d1c5816
5 changed files with 32 additions and 25 deletions

View File

@ -303,7 +303,7 @@ Name triggered by ~
|InsertLeave| when leaving Insert mode |InsertLeave| when leaving Insert mode
|InsertCharPre| when a character was typed in Insert mode, before |InsertCharPre| when a character was typed in Insert mode, before
inserting it inserting it
|JobActivity| when something interesting happen with a job |JobActivity| when something interesting happens with a job
|TextChanged| after a change was made to the text in Normal mode |TextChanged| after a change was made to the text in Normal mode
|TextChangedI| after a change was made to the text in Insert mode |TextChangedI| after a change was made to the text in Insert mode

View File

@ -4019,7 +4019,12 @@ jobsend({job}, {data}) {Nvim} *jobsend()*
jobstart({name}, {prog}[, {argv}]) {Nvim} *jobstart()* jobstart({name}, {prog}[, {argv}]) {Nvim} *jobstart()*
Spawns {prog} as a job and associate it with the {name} string, Spawns {prog} as a job and associate it with the {name} string,
which will be used to match the "filename pattern" in which will be used to match the "filename pattern" in
|JobActivity| events. See |job-control| for more information. |JobActivity| events. It returns:
- The job id on success, which is used by |jobsend()| and
|jobstop()|
- 0 when the job table is full or on invalid arguments
- -1 when {prog} is not executable
See |job-control| for more information.
jobstop({job}) {Nvim} *jobstop()* jobstop({job}) {Nvim} *jobstop()*
Stop a job created with |jobstart| by sending a `SIGTERM` Stop a job created with |jobstart| by sending a `SIGTERM`
@ -5083,10 +5088,12 @@ rpcrequest({channel}, {method}[, {args}...]) {Nvim} *rpcrequest()*
rpcstart({prog}[, {argv}]) {Nvim} *rpcstart()* rpcstart({prog}[, {argv}]) {Nvim} *rpcstart()*
Spawns {prog} as a job(optionally passing the {argv} list), Spawns {prog} as a job(optionally passing the {argv} list),
and open a |msgpack-rpc| channel with the spawned process and opens a |msgpack-rpc| channel with the spawned process
stdin/stdout. Returns the channel id, which is used by stdin/stdout. It returns:
|rpcrequest()|, |rpcnotify()| and |rpcstop()| - The channel id on success, which is used by |rpcrequest()|,
It expects the rpc channel id as argument. Example: > |rpcnotify()| and |rpcstop()|
- 0 on failure.
Example: >
:let rpc_chan = rpcstart('prog', ['arg1', 'arg2']) :let rpc_chan = rpcstart('prog', ['arg1', 'arg2'])
rpcstop({channel}) {Nvim} *rpcstop()* rpcstop({channel}) {Nvim} *rpcstop()*

View File

@ -66,14 +66,14 @@ nvim instance:
< <
Here's what is happening: Here's what is happening:
- Two bash instances are spawned |jobstart()| and their stdin/stdout/stderr - Two bash instances are spawned by |jobstart()| and their stdin/stdout/stderr
are connected to nvim. are connected to nvim.
- The first shell is idle, waiting to read commands from it's stdin - The first shell is idle, waiting to read commands from it's stdin
- The second shell is passed the -c option to execute a command and exit. In - The second shell is passed the -c option to execute a command and exit. In
our case, the command is a for loop that will print numbers and exit after our case, the command is a for loop that will print numbers and exit after
a while. a while.
- The JobHandler function is called by the JobActivity autocommand(notice how - The JobHandler function is called by the JobActivity autocommand(notice how
it the shell* pattern matches the `shell1` and `shell2` names passed to the shell* pattern matches the `shell1` and `shell2` names passed to
|jobstart()|), and it takes care of displaying stdout/stderr received from |jobstart()|), and it takes care of displaying stdout/stderr received from
the shells. the shells.
- The v:job_data is an array set by the JobActivity event. It has the - The v:job_data is an array set by the JobActivity event. It has the
@ -86,9 +86,9 @@ Here's what is happening:
To send data to the job's stdin, one can use the |jobsend()| function, like To send data to the job's stdin, one can use the |jobsend()| function, like
this: this:
> >
:call jobsend(job1, 'ls\n')<cr> :call jobsend(job1, 'ls\n')
:call jobsend(job1, 'invalid-command\n')<cr> :call jobsend(job1, 'invalid-command\n')
:call jobsend(job1, 'exit\n')<cr> :call jobsend(job1, 'exit\n')
< <
A job may be killed at any time with the |jobstop()| function: A job may be killed at any time with the |jobstop()| function:
> >

View File

@ -17,20 +17,20 @@ The Msgpack-RPC Interface to Nvim *msgpack-rpc*
============================================================================== ==============================================================================
1. Introduction *msgpack-rpc-intro* 1. Introduction *msgpack-rpc-intro*
The primary means of controlling a running nvim instance is through The primary means of controlling a running Nvim instance is through
MessagePack-RPC, a messaging protocol that uses the MessagePack serialization MessagePack-RPC, a messaging protocol that uses the MessagePack serialization
format: https://github.com/msgpack/msgpack/blob/7498cf3/spec.md. format: https://github.com/msgpack/msgpack/blob/7498cf3/spec.md.
From now on, we'll be referring to the protocol as msgpack-rpc. From now on, we'll be referring to the protocol as msgpack-rpc.
At this point, only plugins use msgpack-rpc, but eventually even user At this point, only plugins use msgpack-rpc, but eventually even user
interaction will be achieved through the protocol, since user interfaces will interaction will be achieved through the protocol, since user interfaces will
be separate programs that control a headless nvim instance. be separate programs that control a headless Nvim instance.
This is what can be achieved by connecting to the msgpack-rpc interface: This is what can be achieved by connecting to the msgpack-rpc interface:
- Call any nvim API function - Call any Nvim API function
- Listen for nvim events - Listen for Nvim events
- Receive remote calls from nvim - Receive remote calls from Nvim
Nvim's msgpack-rpc interface can be seen as a more powerful version of Vim's Nvim's msgpack-rpc interface can be seen as a more powerful version of Vim's
`clientserver` feature. `clientserver` feature.
@ -69,7 +69,7 @@ python and the pyyaml/msgpack-python pip packages):
There are four ways to open msgpack-rpc streams to nvim: There are four ways to open msgpack-rpc streams to nvim:
1. Through nvim's stdin/stdout when started with the `--embed` option. This 1. Through nvim's stdin/stdout when started with the `--embed` option. This is
how other programs can embed nvim. how other programs can embed nvim.
2. Through stdin/stdout of a program spawned by the |rpcstart()| function. 2. Through stdin/stdout of a program spawned by the |rpcstart()| function.
@ -122,7 +122,7 @@ functions can be called interactively:
Nvim is still alpha and there's no in-depth documentation explaining how to Nvim is still alpha and there's no in-depth documentation explaining how to
properly implement a client library. The python client(neovim pip package) properly implement a client library. The python client(neovim pip package)
will be always up-to-date with the latest API changes, so it's source code is will be always up-to-date with the latest API changes, so it's source code is
best documentation currently available. There are some guidelines however: the best documentation currently available. There are some guidelines however:
- Separate the transport layer from the rest of the library(See - Separate the transport layer from the rest of the library(See
|msgpack-rpc-connecting| for details of how a client can connect to nvim). |msgpack-rpc-connecting| for details of how a client can connect to nvim).
@ -134,7 +134,7 @@ best documentation currently available. There are some guidelines however:
- Use a fiber/coroutine library for the language you are implementing a client - Use a fiber/coroutine library for the language you are implementing a client
for. These greatly simplify concurrency and allow the library to expose a for. These greatly simplify concurrency and allow the library to expose a
blocking API on top of a non-blocking event loop without the complexity blocking API on top of a non-blocking event loop without the complexity
that comes with preemptive multi-tasking. that comes with preemptive multitasking.
- Don't assume anything about the order that responses to msgpack-rpc requests - Don't assume anything about the order that responses to msgpack-rpc requests
will arrive. will arrive.
- Clients should expect to receive msgpack-rpc requests, which need to be - Clients should expect to receive msgpack-rpc requests, which need to be
@ -159,7 +159,7 @@ around C99 standard types). The types can be split into two groups:
- Basic types that map natively to msgpack(and probably have a default - Basic types that map natively to msgpack(and probably have a default
representation in msgpack-supported programming languages) representation in msgpack-supported programming languages)
- Special Nvim types that map to msgpack ext with custom type codes. - Special Nvim types that map to msgpack EXT with custom type codes.
Basic type mapping: Basic type mapping:
@ -171,7 +171,7 @@ String -> msgpack binary
Array -> msgpack array Array -> msgpack array
Dictionary -> msgpack map Dictionary -> msgpack map
Special Nvim types that use msgpack ext: Special Nvim types that use msgpack EXT:
Buffer -> enum value kObjectTypeBuffer Buffer -> enum value kObjectTypeBuffer
Window -> enum value kObjectTypeWindow Window -> enum value kObjectTypeWindow
@ -231,7 +231,7 @@ Four functions related to msgpack-rpc are available to vimscript:
- |rpcstart()|: Similarly to |jobstart()|, this will spawn a co-process with - |rpcstart()|: Similarly to |jobstart()|, this will spawn a co-process with
it's standard handles connected to Nvim, the difference is that it's not it's standard handles connected to Nvim, the difference is that it's not
possible to process raw data to/from the process stdin/stdout/stderr(Since possible to process raw data to/from the process stdin/stdout/stderr(Since
the job's stdin/stdout combo are used as a msgpack channgel that is the job's stdin/stdout combo are used as a msgpack channel that is
processed directly by Nvim C code). processed directly by Nvim C code).
- |rpcstop()|: Same as |jobstop()|, but operates on handles returned by - |rpcstop()|: Same as |jobstop()|, but operates on handles returned by
|rpcstart().| |rpcstart().|

View File

@ -6,9 +6,9 @@
Introduction to Nvim *nvim-intro* Introduction to Nvim *nvim-intro*
This is an introduction new Nvim users. It is meant for experienced Vim users This is an introduction to Vim users that are just getting started with Nvim.
that want to get started with Nvim. For a basic introduction to Vim, see It is not meant for Vim beginners. For a basic introduction to Vim,
|help.txt|. see |help.txt|.
For now, it is just an index with the most relevant topics/features that For now, it is just an index with the most relevant topics/features that
differentiate Nvim from Vim: differentiate Nvim from Vim: