Unify updates_start and updates to lines_event

Also rename changedtick -> changedtick_event

1 files changed, 33 insertions, 61 deletions

diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt
index 9ebebb8d61..571a08930c 100644
--- a/runtime/doc/msgpack_rpc.txt
+++ b/runtime/doc/msgpack_rpc.txt
@@ -242,7 +242,7 @@ the type codes, because a client may be built against one Nvim version but
 connect to another with different type codes.
 
 ==============================================================================
-6. Buffer Updates				                *buffer-updates* *rpc-buffer-updates*
+6. Buffer Updates				   *buffer-updates* *rpc-buffer-updates*
 
 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
@@ -253,94 +253,66 @@ BufferUpdates Events~
 
 The co-process will start receiving the following notification events:
 
-nvim_buf_updates_start[{buf}, {changedtick}, {linedata}, {more}]	 *nvim_buf_updates_start*
-
-  Nvim will send at least one of these notifications to confirm that buffer
-  updates are registered for this plugin, and possibly send the buffer's
-  contents. If the buffer is very large, nvim 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 nvim you can check the value of
-	|b:changedtick| as part of your request to ensure that no other
-	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 |nvim_buf_updates_start|
-  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. If you send the
-  |nvim_buf_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 nvim and not guaranteed to be any particular size.  Also the
-  number of {linedata} items may vary between notifications, so your plugin
-  must be prepared to receive the line data in whatever size lists nvim
-  decides to split it into.
-
-  {more} is a boolean which tells you whether or not to expect more
-  |nvim_buf_updates_start| notifications. When {more} is false, you can be certain
-  that you now have the entire buffer's contents.
-
-nvim_buf_update[{buf}, {changedtick}, {firstline}, {lastline}, {linedata}] *nvim_buf_update*
+                                                                   *nvim_buf_lines_event*
+nvim_buf_lines_event[{buf}, {changedtick}, {firstline}, {lastline}, {linedata}, {more}]
 
   Indicates that the lines between {firstline} and {lastline} (end-exclusive,
   zero-indexed) have been replaced with the new line data contained in the
   {linedata} list.  All buffer changes (even adding single characters) will be
   transmitted as whole-line changes.
 
-	{buf} is an API handle for the buffer.
+    {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 nvim 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 nvim 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
+    (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. {lastline} will be `-1` if the event is part of the initial
+    sending of the buffer.
 
-  {lastline} is the integer line number of the first line that was not 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.
+    {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. 
 
-  {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. 
+    {more} is a boolean which tells you whether or not to expect more
+    |nvim_buf_updates| notifications for a single buffer change (i.e. Nvim has
+    chunked up one event into several). Not yet used.
 
   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.
+  only used for the |inccommand| option.
 
-nvim_buf_changedtick[{buf}, {changedtick}]		                   *nvim_buf_changedtick*
+nvim_buf_changedtick_event[{buf}, {changedtick}]	 *nvim_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.
 
-  {buf} is an API handle for the buffer.
+    {buf} is an API handle for the buffer.
 
-  {changedtick} is the new value of |b:changedtick| for that buffer.
+    {changedtick} is the new value of |b:changedtick| for that buffer.
 
 nvim_buf_updates_end[{buf}]                                    		*nvim_buf_updates_end*
 
-  {buf} is an API handle for the buffer.
-
   Indicates that buffer updates for the nominated buffer have been disabled,
   either by calling |nvim_buf_detach| or because the buffer was unloaded
   (see |buffer-updates-limitations| for more information).
 
+    {buf} is an API handle for the buffer.
+
+
                                                       *buffer-updates-limitations*
 Limitations~