runtime/docs/msgpack-rpc: Misc. fixes

- Correct apostrophe usage, primarily with it's/its
- Correct usage of 'e.g.'
- Capitalize acronyms
- Prepend NVIM_LISTEN_ADDRESS with '$' to match previous instance
- Avoid awkward phrasing
- Make lists with an explicitly stated number of points numbered to
  match other such lists
- Added space before parentheses
- rm trailing whitespace

1 files changed, 46 insertions, 43 deletions

diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt
index 8567f4a00e..800ab08ce3 100644
--- a/runtime/doc/msgpack_rpc.txt
+++ b/runtime/doc/msgpack_rpc.txt
@@ -38,27 +38,28 @@ Nvim's msgpack-rpc interface can be seen as a more powerful version of Vim's
 ==============================================================================
 2. API							      *msgpack-rpc-api*
 
-Nvim C API is automatically exposed to the msgpack-rpc interface by the
+The Nvim C 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, and it will match msgpack-rpc method names
+dispatch function is generated, which matches msgpack-rpc method names
 with non-static API functions, converting/validating arguments and return
 values back to msgpack.
 
 Client libraries will normally provide wrappers that hide msgpack-rpc details
-from programmers, which can be automatically generated by reading bundled api
+from programmers, which can be automatically generated by reading bundled API
 metadata from a compiled nvim instance.
 
 There are two ways to obtain API metadata:
 
-- By connecting to a running nvim instance and calling `vim_get_api_metadata`
-  via msgpack-rpc. This is the preferred way for clients written in
-  dynamically-typed languages, which can define functions at runtime.
-- Through the `--api-info` command-line option, which makes nvim to dump a
-  msgpack blob containing the metadata to stdout and exit. This is preferred
-  when writing clients for statically-typed languages, which require a
-  separate compilation step.
+1. By connecting to a running nvim instance and calling `vim_get_api_metadata`
+   via msgpack-rpc. This is the preferred way for clients written in
+   dynamically-typed languages, which can define functions at runtime.
 
-Here's a simple way to get human-readable description of the API(requires
+2. Through the `--api-info` command-line option, which makes nvim dump a
+   msgpack blob containing metadata to stdout and exit. This is preferred
+   when writing clients for statically-typed languages, which require a
+   separate compilation step.
+
+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
@@ -66,7 +67,6 @@ python and the pyyaml/msgpack-python pip packages):
 ==============================================================================
 3. Connecting					       *msgpack-rpc-connecting*
 
-
 There are four ways to open msgpack-rpc streams to nvim:
 
 1. Through nvim's stdin/stdout when started with the `--embed` option. This is
@@ -74,31 +74,31 @@ There are four ways to open msgpack-rpc streams to nvim:
 
 2. Through stdin/stdout of a program spawned by the |rpcstart()| function.
 
-3. Through the socket automatically created with every instance. To find out
-   the socket location(which is random by default) from a running nvim
+3. Through the socket automatically created with each instance. To find out
+   the socket location (which is random by default) from a running nvim
    instance, one can inspect the *$NVIM_LISTEN_ADDRESS* environment variable
    like this:
 >
     :echo $NVIM_LISTEN_ADDRESS
 <
-4. Through a tcp/ip socket. To make nvim listen on a tcp/ip socket, you need
-   to set the NVIM_LISTEN_ADDRESS environment variable before starting, like
+4. Through a TCP/IP socket. To make nvim listen on a TCP/IP socket, you need
+   to set the $NVIM_LISTEN_ADDRESS environment variable before starting, like
    this:
 >
     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 a fully-featured
-Nvim client(which we'll see below). Here's a ruby script that will print the
+which can be done through any msgpack-rpc client library or fully-featured
+Nvim client (which we'll see below). Here's a ruby script that will print the
 string 'hello world!' on the current nvim instance:
 >
     #!/usr/bin/env ruby
     # Requires msgpack-rpc: gem install msgpack-rpc
-    # 
-    # To run this script, execute it from a running nvim instance(notice the
+    #
+    # To run this script, execute it from a running nvim instance (notice the
     # trailing '&' which is required since nvim won't process events while
     # running a blocking command):
-    # 
+    #
     #	:!./hello.rb &
     #
     # Or from another shell by setting NVIM_LISTEN_ADDRESS:
@@ -120,15 +120,15 @@ functions can be called interactively:
 4. Implementing new clients				  *msgpack-rpc-clients*
 
 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)
-will be always up-to-date with the latest API changes, so it's source code is
+properly implement a client library. The python client (neovim pip package)
+will be always 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
+- Separate the transport layer from the rest of the library (see
   |msgpack-rpc-connecting| for details of how a client can connect to nvim).
 - Use a msgpack library that implements the spec version 5, Nvim uses the
   BIN/EXT types.
-- Read api metadata in order to create client-side wrappers for all
+- 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 you are implementing a client
@@ -138,10 +138,10 @@ the best documentation currently available. There are some guidelines however:
 - Don't assume anything about the order that responses to msgpack-rpc requests
   will arrive.
 - Clients should expect to receive msgpack-rpc requests, which need to be
-  handled immediately since Nvim is blocked while waiting for the client
+  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(Though you
+  need to be handled immediately because they won't block Nvim (though you
   probably want to handle them immediately anyway).
 
 
@@ -154,14 +154,14 @@ https://github.com/msgpack-rpc/msgpack-rpc-ruby/blob/master/lib/msgpack/rpc/tran
 ==============================================================================
 5. Types						    *msgpack-rpc-types*
 
-Nvim's C API uses custom types for all functions(some are just typedefs
+Nvim's C API uses custom types for all functions (some are just typedefs
 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)
 - Special Nvim types that map to msgpack EXT with custom type codes.
 
-Basic type mapping: 
+Basic type mapping:
 
 Nil				  -> msgpack nil
 Boolean				  -> msgpack boolean
@@ -210,15 +210,15 @@ that makes this task easier:
 - 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, eg:
+- 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. Eg: `buffer_get_line` represents the `get_line` method
+  name in lower case, e.g. `buffer_get_line` represents the `get_line` method
   of a Buffer instance.
-- Global methods are prefixed with `vim`. Eg: `vim_list_buffers`
+- Global methods are prefixed with `vim`, e.g.`vim_list_buffers`.
 
-So, for a object-oriented language, a client library would have the classes
+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_`
@@ -228,15 +228,18 @@ class with methods mapped to functions prefixed with `vim_`
 
 Four functions related to msgpack-rpc are available to vimscript:
 
-- |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
-  possible to process raw data to/from the process stdin/stdout/stderr(Since
-  the job's stdin/stdout combo are used as a msgpack channel that is
-  processed directly by Nvim C code).
-- |rpcstop()|: Same as |jobstop()|, but operates on handles returned by
-  |rpcstart()|.
-- |rpcrequest()|: Sends a msgpack-rpc request to the process.
-- |rpcnotify()|: Sends a msgpack-rpc notification to the process.
+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/from the process stdin/stdout/stderr (since
+   the job's stdin/stdout combo are used as a msgpack channel that is
+   processed directly by Nvim C code).
+
+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|.