Doc

1 files changed, 94 insertions, 114 deletions

diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt
index e7c80236f8..8781c4589c 100644
--- a/runtime/doc/msgpack_rpc.txt
+++ b/runtime/doc/msgpack_rpc.txt
@@ -244,79 +244,59 @@ connect to another with different type codes.
 ==============================================================================
 6. Live Updates				      *live-updates* *rpc-live-updates*
 
-A dedicated API has been created to allow co-processes to be notified in
-real-time when the user changes a buffer in any way. It is difficult and
-error-prone to try and do this with autocommands such as |TextChanged|.
-
-							*live-updates-enabling*
-Setting Up~
-
-If your API client is a standalone co-process, it can use the
-`"nvim_buf_live_updates"`API method to activate Live Update events for a
-specific buffer. For example, in python >
-
-	import sys, neovim
-	nvim = neovim.attach('stdio')
-	bufnr = sys.argv[1]
-	nvim.buffers[bufnr].live_updates_start(True)
-
-After the `"nvim_buf_live_updates_start"` method is called with Argument `"True"`,
-neovim will send a series of notifications containing the entire buffer's
-contents and any subsequent changes. The buffer's contents are sent via
-notifications because if you were to use the other API methods to retrieve the
-buffer contents, the buffer could be changed again before you turn on live
-updates. This can cause a delay if your plugin activates live updates for a
-very large buffer, but it is the the most efficient way to maintain a copy of
-the entire buffer's contents inside your plugin.
-
-						      *live-updates-disabling*
-Turning Off~
-
-You can use `"nvim_buf_live_updates_stop"` to turn off notifications. One
-final notification will be sent to indicate that live updates are no longer
-active for the specified buffer. Alternatively, you can just close the
-channel.
-
-						    *live-updates-limitations*
-Limitations~
+A dedicated API has been created to allow co-processes to be notified  when a
+buffer is changed in any way. It is difficult and error-prone to try and do
+this with autocommands such as |TextChanged|.
 
-Note that any of the following actions will also turn off live updates because
-the buffer contents are unloaded from memory:
+                                                              *live-updates-api*
+LiveUpdate Functions~
 
-  - Closing all a buffer's windows (unless 'hidden' is enabled).
-  - Using |:edit| to reload the buffer
-  - reloading the buffer after it is changed from outside neovim.
+nvim_buf_live_updates_start({send_buffer})     *nvim_buf_live_updates_start()*
+              Register a plugin to receive notifications on buffer changes. An
+              initial |LiveUpdateStart| notification will be sent as a
+              confirmation. After that, |LiveUpdate| notifications will be
+              sent for buffer updates, and |LiveUpdateTick| notifications for
+              a new changedtick without buffer change.
+
+              Parameters:~
+                  {send_buffer}  Bool. If `"True"`, the initial
+                  |LiveUpdateStart| notification will also send the full
+                  buffer's content. If `"False"`, the notification will
+                  contain an empty list instead.
 
-							  *live-updates-events*
-Handling Events~
+nvim_buf_live_updates_stop()                    *nvim_buf_live_updates_stop()*
+              Unregister a plugin from buffer change notifications. A final
+              |LiveUpdateEnd| notification will be sent as confirmation.
 
-The co-process will start receiving the notification events which will be
-equivilent to the following |rpcnotify()| calls:
+                                                           *live-updates-events*
+LiveUpdate Events~
 
-1. rpcnotify({channel}, "LiveUpdateStart",		      *LiveUpdateStart*
-             [{buf}, {changedtick}, {linedata}, {more}])
+The co-process will start receiving the following notification events:
 
-	Neovim will send at least one of these notifications to provide you
-	with the original buffer contents. If the buffer is very large, neovim
-	will send the contents through in multiple events to avoid loading the
-	entire buffer's contents into memory at once.
+LiveUpdateStart[{buf}, {changedtick}, {linedata}, {more}]	 *LiveUpdateStart*
+
+  Neovim will send at least one of these notifications to confirm that
+  liveupdates are registered for this plugin, and possibly send the buffer's
+  contents. If the buffer is very large, neovim might send the contents through
+  in multiple events to avoid loading the entire buffer's contents into memory
+  at once.
 
 	{buf} is an API handle for the buffer.
 
 	{changedtick} is the value of |b:changedtick| for the buffer. If you
 	send an API command back to neovim you can check the value of
 	|b:changedtick| as part of your request to ensure that no other
-	changes have been made. See |live-update-race-conditions| for more
-	information.
+	changes have been made. 
 
 	{linedata} is a list of strings containing the buffer's contents. If
 	this list contains 100 strings, then they represent lines 1-100 of the
 	buffer.  Newline characters are not included in the strings, so empty
 	lines will be given as empty strings. If you receive another
-	`"LiveUpdateStart"` notification with another {linedata} list, then
+	|LiveUpdateStart| notification with another {linedata} list, then
 	these lines represent the next N lines of the buffer. I.e., a second
-	notification with another list of 100 strings will represent lines
-	101-200 of the buffer.
+  notification with another list of 100 strings will represent lines 101-200
+  of the buffer. If you send the |nvim_buf_live_updates_start| request with
+  its argument set to `"False"`, this will be empty.
 
 	{linedata} will always have at least 1 item, but the maximum length is
 	determined by neovim and not guaranteed to be any particular size.
@@ -324,12 +304,11 @@ equivilent to the following |rpcnotify()| calls:
 	your plugin must be prepared to receive the line data in whatever size
 	lists neovim decides to split it into.
 
-	{more} is a boolean which tells you whether or not to expect more
-	`"LiveUpdateStart"` notifications. When {more} is false, you can
-	be certain that you now have the entire buffer's contents.
+  {more} is a boolean which tells you whether or not to expect more
+  |LiveUpdateStart| notifications. When {more} is false, you can be certain
+  that you now have the entire buffer's contents.
 
-2. rpcnotify({channel}, "LiveUpdate",				  *LiveUpdate*
-	     [{buf}, {changedtick}, {firstline}, {lastline}, {linedata}])
+LiveUpdate[{buf}, {changedtick}, {firstline}, {lastline}, {linedata}] *LiveUpdate*
 
   Indicates that the lines between {firstline} and {lastline} (end-exclusive,
   zero-indexed) have been replaced with the new line data contained in the
@@ -338,95 +317,96 @@ equivilent to the following |rpcnotify()| calls:
 
 	{buf} is an API handle for the buffer.
 
-	{changedtick} is the value of |b:changedtick| for the buffer. If you
-	send an API command back to neovim you can check the value of
-	|b:changedtick| as part of your request to ensure that no other
-	changes have been made.
+  {changedtick} is the value of |b:changedtick| for the buffer. If you send an
+  API command back to neovim you can check the value of |b:changedtick| as
+  part of your request to ensure that no other changes have been made.
 
-	{firstline} is the integer line number of the first line that was
-	replaced. Note that {firstline} is zero-indexed, so if line `1` was
-	replaced then {firstline} will be `0` instead of `1`. {firstline} is
-	guaranteed to always be less than or equal to the number of lines that
-	were in the buffer before the lines were replaced.
+  {firstline} is the integer line number of the first line that was replaced.
+  Note that {firstline} is zero-indexed, so if line `1` was replaced then
+  {firstline} will be `0` instead of `1`. {firstline} is guaranteed to always
+  be less than or equal to the number of lines that were in the buffer before
+  the lines were replaced.
 
   {lastline} is the integer line number of the first line that was not
-  replaced. Note that {lastline} is zero-indexed, so if line numbers 2 to 5
-  were replaced, this will be `5` instead of `6`. {lastline} is guaranteed to
-  always be less than or equal to the number of lines that were in the buffer
-  before the lines were replaced.
-
-	{linedata} is a list of strings containing the contents of the new
-	buffer lines. Newline characters are not included in the strings, so
-	empty lines will be given as empty strings. If {numreplaced} is `1` or
-	more, then {linedata} may be an empty list (indicating that lines were
-	deleted from the buffer). But if {numreplaced} is `0` (indicating that
-	lines were added to the buffer) then {linedata} is guaranteed to
-	contain at least 1 item.
-
-	Note: sometimes {changedtick} will be |v:null|, which means that the
-	buffer text *looks* like it has changed, but actually hasn't. In this
-	case the lines in {linedata} contain the modified text that is shown
-	to the user, but doesn't reflect the actual buffer contents. Currently
-	this behaviour is only used for the 'inccommand' option.
-
-3. rpcnotify({channel}, "LiveUpdateTick",		      *LiveUpdateTick*
-	     [{buf}, {changedtick}])
-
-	Indicates that |b:changedtick| was incremented for the buffer {buf},
-	but no text was changed. This is currently only used by undo/redo.
+  replaced (i.e. the range {firstline}, {lastline} is end-exclusive). Note
+  that {lastline} is zero-indexed, so if line numbers 2 to 5 were replaced,
+  this will be `5` instead of `6`. {lastline} is guaranteed to always be less
+  than or equal to the number of lines that were in the buffer before the
+  lines were replaced.
 
-	{buf} is an API handle for the buffer.
+  {linedata} is a list of strings containing the contents of the new buffer
+  lines. Newline characters are not included in the strings, so empty lines
+  will be given as empty strings. 
 
-	{changedtick} is the new value of |b:changedtick| for that buffer.
+  Note: sometimes {changedtick} will be |v:null|, which means that the buffer
+  text *looks* like it has changed, but actually hasn't. In this case the
+  lines in {linedata} contain the modified text that is shown to the user, but
+  doesn't reflect the actual buffer contents. Currently this behaviour is only
+  used for the 'inccommand' option.
 
-4. rpcnotify({channel}, "LiveUpdateEnd", [{buf}])		*LiveUpdateEnd*
+LiveUpdateTick[{buf}, {changedtick}]		                   *LiveUpdateTick*
 
-	{buf} is an API handle for the buffer.
+  Indicates that |b:changedtick| was incremented for the buffer {buf}, but no
+  text was changed. This is currently only used by undo/redo.
+
+  {buf} is an API handle for the buffer.
 
-	Indicates that live updates for the nominated buffer have been
-	disabled, either by calling the api function `"nvim_buf_live_updates"`
-	with argument `false`, or because the buffer was unloaded (see
-	|live-updates-disabling| and |live-updates-limitations| for more
-	information).
+  {changedtick} is the new value of |b:changedtick| for that buffer.
 
-							*live-updates-examples*
+LiveUpdateEnd[{buf}]                                    		*LiveUpdateEnd*
+
+  {buf} is an API handle for the buffer.
+
+  Indicates that live updates for the nominated buffer have been disabled,
+  either by calling |nvim_buf_live_updates_stop| or because the buffer was
+  unloaded (see |live-updates-limitations| for more information).
+
+                                                      *live-updates-limitations*
+Limitations~
+
+Note that any of the following actions will also turn off live updates because
+the buffer contents are unloaded from memory:
+
+  - Closing all a buffer's windows (unless 'hidden' is enabled).
+  - Using |:edit| to reload the buffer
+  - reloading the buffer after it is changed from outside neovim.
+
+                                                       *live-updates-examples*
 Example Events~
 
 If live updates are activated a new empty buffer, the following
 |LiveUpdateStart| event will be sent: >
 
-	rpcnotify({channel}, "LiveUpdateStart", [{buf}, [""], v:false])
+  rpcnotify({channel}, "LiveUpdateStart", [{buf}, [""], v:false])
 
 If the user adds 2 new lines to the start of a buffer, the following event
 would be generated: >
 
-	rpcnotify({channel}, "LiveUpdate", [{buf}, 0, 0, ["line1", "line2"]])
+  rpcnotify({channel}, "LiveUpdate", [{buf}, 0, 0, ["line1", "line2"]])
 
 If the puts the cursor on a line containing the text `"Hello world"` and adds
 a `!` character to the end using insert mode, the following event would be
 generated: >
 
-	rpcnotify({channel}, "LiveUpdate",
-		  [{buf}, {linenr}, 1, ["Hello world!"]])
+  rpcnotify({channel}, "LiveUpdate", [{buf}, {linenr}, {linenr} + 1, ["Hello
+  world!"]])
 
 If the user moves their cursor to line 3 of a buffer and deletes 20 lines
 using `20dd`, the following event will be generated: >
 
-	rpcnotify({channel}, "LiveUpdate", [{buf}, 2, 20, []])
+  rpcnotify({channel}, "LiveUpdate", [{buf}, 2, 20, []])
 
 If the user selects lines 3-5 of a buffer using |linewise-visual| mode and
 then presses `p` to paste in a new block of 6 lines, then the following event
 would be sent to the co-process: >
 
-	rpcnotify({channel}, "LiveUpdate",
-		  [{buf}, 2, 3, ['pasted line 1', 'pasted line 2',
-				 'pasted line 3', 'pasted line 4',
-				 'pasted line 5', 'pasted line 6']])
+  rpcnotify({channel}, "LiveUpdate", [{buf}, 2, 5, ['pasted line 1', 'pasted
+  line 2', 'pasted line 3', 'pasted line 4', 'pasted line 5', 'pasted line
+  6']])
 
 If the user uses :edit to reload a buffer then the following event would be
 generated: >
 
-	rpcnotify({channel}, "LiveUpdateEnd", [{buf}])
-
+  rpcnotify({channel}, "LiveUpdateEnd", [{buf}])
 
  vim:tw=78:ts=8:ft=help:norl: