Merge branch 'master' into s-dash-stdin

1 files changed, 28 insertions, 200 deletions

diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt
index c074eb43ff..2d8f5af6d2 100644
--- a/runtime/doc/msgpack_rpc.txt
+++ b/runtime/doc/msgpack_rpc.txt
@@ -1,4 +1,3 @@
-*msgpack_rpc.txt*							{Nvim}
 
 
 		 NVIM REFERENCE MANUAL    by Thiago de Arruda
@@ -6,12 +5,7 @@
 
 RPC API for Nvim				     *RPC* *rpc* *msgpack-rpc*
 
-1. Introduction			|rpc-intro|
-2. API mapping			|rpc-api|
-3. Connecting			|rpc-connecting|
-4. Clients			|rpc-api-client|
-5. Types			|rpc-types|
-6. Remote UIs			|rpc-remote-ui|
+				      Type |gO| to see the table of contents.
 
 ==============================================================================
 1. Introduction						            *rpc-intro*
@@ -33,7 +27,7 @@ programs can:
 The RPC API is like a more powerful version of Vim's `clientserver` feature.
 
 ==============================================================================
- 2. API mapping							    *rpc-api*
+2. API mapping							    *rpc-api*
 
 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
@@ -66,24 +60,24 @@ To get a formatted dump of the API using python (requires the `pyyaml` and
 ==============================================================================
 3. Connecting						      *rpc-connecting*
 
-There are several ways to open a msgpack-rpc channel to an Nvim instance:
+See |channel-intro|, for various ways to open a channel. Most of the channel
+opening functions take an `rpc` key in the options dictionary, to enable rpc.
 
-  1. Through stdin/stdout when `nvim` is started with `--embed`. This is how
-     applications can embed Nvim.
+Additionally, rpc channels can be opened by other processes connecting to
+TCP/IP sockets or named pipes listened to by nvim.
 
-  2. Through stdin/stdout of some other process spawned by |jobstart()|.
-     Set the "rpc" key to |v:true| in the options dict to use the job's stdin
-     and stdout as a single msgpack channel that is processed directly by
-     Nvim.  Then it is not possible to process raw data to or from the
-     process's stdin and stdout. stderr can still be used, though.
+An rpc socket is automatically created with each instance. The socket
+ location is stored in |v:servername|. By default this is a named pipe
+with an automatically generated address. See |XXX|.
 
-  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 before starting Nvim: >
+To make Nvim listen on a TCP/IP socket instead, set the
+   |$NVIM_LISTEN_ADDRESS| environment variable before starting Nvim: >
         NVIM_LISTEN_ADDRESS=127.0.0.1:6666 nvim
-<
+<Also, more sockets and named pipes can be listened on using |serverstart()|.
+
+Note that localhost TCP sockets are generally less secure than named pipes,
+and can lead to vunerabilities like remote code execution.
+
 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
@@ -180,7 +174,7 @@ contains information that makes this task easier (see also |rpc-types|):
     even more strongly-typed APIs.
   - Functions that are considered to be methods that operate on instances of
     Nvim special types (msgpack EXT) will have the `"method"` attribute set to
-    `true`. The reciever type is the type of the first argument. The method
+    `true`. The receiver type is the type of the first argument. The method
     names are prefixed with `nvim_` plus a shortened type name, e.g.
     `nvim_buf_get_lines` represents the `get_lines` method of a Buffer instance.
     - Global functions have `"method"` set to `false` and are prefixed with just
@@ -197,7 +191,7 @@ prefix is stripped off.
 5. Types							    *rpc-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:
+At the RPC layer, 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)
@@ -219,15 +213,16 @@ Special types (msgpack EXT) ~
   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
-an integer, but not a Window or Tabpage.
+API functions expecting one of the special EXT types may be passed an integer
+instead, but not another EXT type. E.g. Buffer may be passed as an integer but
+not as a Window or Tabpage. The EXT object data is the object id encoded as
+a msgpack integer: For buffers this is the |bufnr()| and for windows the
+|window-ID|. For tabpages the id is an internal handle, not the tabpage
+number.
+
+To determine the type codes of the special EXT types, inspect the `types` key
+of the |api-metadata| at runtime. Example JSON representation: >
 
-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
-`nvim_get_api_info` method at runtime. Here's a sample JSON representation of
-the `types` object:
->
   "types": {
     "Buffer": {
       "id": 0,
@@ -242,176 +237,9 @@ the `types` object:
       "prefix": "nvim_tabpage_"
     }
   }
-<
+
 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. Remote UIs					           *rpc-remote-ui*
-
-Nvim allows Graphical user interfaces to be implemented by separate processes
-communicating with Nvim over the RPC API. Currently the ui model conists of a
-terminal-like grid with one single, monospace font size, with a few elements
-that could be drawn separately from the grid (for the momemnt only the popup
-menu)
-
-After connecting to a nvim instance (typically a spawned, embedded instance)
-use the |nvim_ui_attach|(width, height, options) API method to tell nvim that your
-program wants to draw the nvim screen on a grid with "width" times
-"height" cells. "options" should be a dictionary with the following (all
-optional) keys:
-	`rgb`:			Controls what color format to use.
-				Set to true (default) to use 24-bit rgb
-				colors.
-				Set to false to use terminal color codes (at
-				most 256 different colors).
-	`popupmenu_external`:	Instead of drawing the completion popupmenu on
-				the grid, Nvim will send higher-level events to
-				the ui and let it draw the popupmenu.
-				Defaults to false.
-
-Nvim will then send msgpack-rpc notifications, with the method name "redraw"
-and a single argument, an array of screen updates (described below).
-These should be processed in order. Preferably the user should only be able to
-see the screen state after all updates are processed (not any intermediate
-state after processing only a part of the array).
-
-Screen updates are arrays. The first element a string describing the kind
-of update.
-
-["resize", width, height]
-	The grid is resized to `width` and `height` cells.
-
-["clear"]
-	Clear the screen.
-
-["eol_clear"]
-	Clear from the cursor position to the end of the current line.
-
-["cursor_goto", row, col]
-	Move the cursor to position (row, col). Currently, the same cursor is
-	used to define the position for text insertion and the visible cursor.
-	However, only the last cursor position, after processing the entire
-	array in the "redraw" event, is intended to be a visible cursor
-	position.
-
-["update_fg", color]
-["update_bg", color]
-["update_sp", color]
-	Set the default foreground, background and special colors
-	respectively.
-
-["highlight_set", attrs]
-	Set the attributes that the next text put on the screen will have.
-	`attrs` is a dict with the keys below. Any absent key is reset
-	to its default value. Color defaults are set by the `update_fg` etc
-	updates. All boolean keys default to false.
-
-	`foreground`:	foreground color.
-	`background`:	backround color.
-	`special`:	color to use for underline and undercurl, when present.
-	`reverse`:	reverse video. Foreground and background colors are
-			switched.
-	`italic`:	italic text.
-	`bold`:		bold text.
-	`underline`:	underlined text. The line has `special` color.
-	`undercurl`:	undercurled text. The curl has `special` color.
-
-["put", text]
-	The (utf-8 encoded) string `text` is put at the cursor position
-	(and the cursor is advanced), with the highlights as set by the
-	last `highlight_set` update.
-
-["set_scroll_region", top, bot, left, right]
-	Define the scroll region used by `scroll` below.
-
-["scroll", count]
-	Scroll the text in the scroll region. The diagrams below illustrate
-	what will happen, depending on the scroll direction. "=" is used to
-	represent the SR(scroll region) boundaries and "-" the moved rectangles.
-	Note that dst and src share a common region.
-
-	If count is bigger than 0, move a rectangle in the SR up, this can
-	happen while scrolling down.
->
-		+-------------------------+
-		| (clipped above SR)      |            ^
-		|=========================| dst_top    |
-		| dst (still in SR)       |            |
-		+-------------------------+ src_top    |
-		| src (moved up) and dst  |            |
-		|-------------------------| dst_bot    |
-		| src (cleared)           |            |
-		+=========================+ src_bot
-<
-	If count is less than zero, move a rectangle in the SR down, this can
-	happen while scrolling up.
->
-		+=========================+ src_top
-		| src (cleared)           |            |
-		|------------------------ | dst_top    |
-		| src (moved down) and dst|            |
-		+-------------------------+ src_bot    |
-		| dst (still in SR)       |            |
-		|=========================| dst_bot    |
-		| (clipped below SR)      |            v
-		+-------------------------+
-<
-["set_title", title]
-["set_icon", icon]
-	Set the window title, and icon (minimized) window title, respectively.
-	In windowing systems not distinguishing between the two, "set_icon"
-	can be ignored.
-
-["mouse_on"]
-["mouse_off"]
-	Tells the client whether mouse support, as determined by |'mouse'|
-	option, is considered to be active in the current mode. This is mostly
-	useful for a terminal frontend, or other situations where nvim mouse
-	would conflict with other usages of the mouse. It is safe for a client
-	to ignore this and always send mouse events.
-
-["busy_on"]
-["busy_off"]
-	Nvim started or stopped being busy, and possibly not responsible to user
-	input. This could be indicated to the user by hiding the cursor.
-
-["suspend"]
-	|:suspend| command or |Ctrl-Z| mapping is used. A terminal client (or other
-	client where it makes sense) could suspend itself.  Other clients can
-	safely ignore it.
-
-["bell"]
-["visual_bell"]
-	Notify the user with an audible or visual bell, respectively.
-
-["update_menu"]
-	The menu mappings changed.
-
-["mode_change", mode]
-	The mode changed. Currently sent when "insert", "replace", "cmdline" and
-	"normal" modes are entered. A client could for instance change the cursor
-	shape.
-
-["popupmenu_show", items, selected, row, col]
-	When `popupmenu_external` is set to true, nvim will not draw the
-	popupmenu on the grid, instead when the popupmenu is to be displayed
-	this update is sent. `items` is an array of the items to show, the
-	items are themselves arrays of the form [word, kind, menu, info]
-	as defined at |complete-items|, except that `word` is replaced by
-	`abbr` if present.  `selected` is the initially selected item, either a
-	zero-based index into the array of items, or -1 if no item is
-	selected. `row` and `col` is the anchor position, where the first
-	character of the completed word will be.
-
-["popupmenu_select", selected]
-	An item in the currently displayed popupmenu is selected. `selected`
-	is either a zero-based index into the array of items from the last
-	`popupmenu_show` event, or -1 if no item is selected.
-
-["popupmenu_hide"]
-	The popupmenu is hidden.
 
-==============================================================================
- vim:tw=78:ts=8:noet:ft=help:norl: