Merge remote-tracking branch 'upstream/master' into floattitlefloattitle

59 files changed, 3560 insertions, 3885 deletions

diff --git a/runtime/doc/Makefile b/runtime/doc/Makefile
deleted file mode 100644
index 18d32c0820..0000000000
--- a/runtime/doc/Makefile
+++ /dev/null
@@ -1,40 +0,0 @@
-#
-# Makefile for the Vim documentation on Unix
-#
-# If you get "don't know how to make scratch", first run make in the source
-# directory.  Or remove the include below.
-
-AWK = awk
-
-DOCS = $(wildcard *.txt)
-HTMLS = $(DOCS:.txt=.html)
-
-.SUFFIXES:
-.SUFFIXES: .c .o .txt .html
-
-# Awk version of .txt to .html conversion.
-html: noerrors vimindex.html $(HTMLS)
-	@if test -f errors.log; then cat errors.log; fi
-
-noerrors:
-	-rm -f errors.log
-
-$(HTMLS): tags.ref
-
-.txt.html:
-	$(AWK) -f makehtml.awk $< >$@
-
-# index.html is the starting point for HTML, but for the help files it is
-# help.txt.  Therefore use vimindex.html for index.txt.
-index.html: help.txt
-	$(AWK) -f makehtml.awk help.txt >index.html
-
-vimindex.html: index.txt
-	$(AWK) -f makehtml.awk index.txt >vimindex.html
-
-tags.ref tags.html: tags
-	$(AWK) -f maketags.awk tags >tags.html
-
-clean:
-	-rm -f *.html tags.ref $(HTMLS) errors.log tags
-
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index a388592981..f92ef26399 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -83,6 +83,7 @@ and |rpcnotify()|:
     let nvim = jobstart(['nvim', '--embed'], {'rpc': v:true})
     echo rpcrequest(nvim, 'nvim_eval', '"Hello " . "world!"')
     call jobstop(nvim)
+<
 
 ==============================================================================
 API Definitions                                         *api-definitions*
@@ -92,7 +93,7 @@ The Nvim C API defines custom types for all function parameters. Some are just
 typedefs around C99 standard types, others are Nvim-defined data structures.
 
 Basic types ~
-
+>
   API Type                              C type
   ------------------------------------------------------------------------
   Nil
@@ -103,7 +104,7 @@ Basic types ~
   Array
   Dictionary (msgpack: map)
   Object
-
+<
   Note: empty Array is accepted as a valid argument for Dictionary parameter.
 
 Special types (msgpack EXT) ~
@@ -115,13 +116,13 @@ Special types (msgpack EXT) ~
   The EXT object data is the (integer) object handle. The EXT type codes given
   in the |api-metadata| `types` key are stable: they will not change and are
   thus forward-compatible.
-
+>
   EXT Type      C type                                  Data
   ------------------------------------------------------------------------
   Buffer        enum value kObjectTypeBuffer            |bufnr()|
   Window        enum value kObjectTypeWindow            |window-ID|
   Tabpage       enum value kObjectTypeTabpage           internal handle
-
+<
 
                                                         *api-indexing*
 Most of the API uses 0-based indices, and ranges are end-exclusive. For the
@@ -130,19 +131,19 @@ end of a range, -1 denotes the last line/column.
 Exception: the following API functions use "mark-like" indexing (1-based
 lines, 0-based columns):
 
-    |nvim_get_mark()|
-    |nvim_buf_get_mark()|
-    |nvim_buf_set_mark()|
-    |nvim_win_get_cursor()|
-    |nvim_win_set_cursor()|
+- |nvim_get_mark()|
+- |nvim_buf_get_mark()|
+- |nvim_buf_set_mark()|
+- |nvim_win_get_cursor()|
+- |nvim_win_set_cursor()|
 
 Exception: the following API functions use |extmarks| indexing (0-based
 indices, end-inclusive):
 
-    |nvim_buf_del_extmark()|
-    |nvim_buf_get_extmark_by_id()|
-    |nvim_buf_get_extmarks()|
-    |nvim_buf_set_extmark()|
+- |nvim_buf_del_extmark()|
+- |nvim_buf_get_extmark_by_id()|
+- |nvim_buf_get_extmarks()|
+- |nvim_buf_set_extmark()|
 
                                                         *api-fast*
 Most API functions are "deferred": they are queued on the main loop and
@@ -162,19 +163,19 @@ and return values.
 
 Nvim exposes its API metadata as a Dictionary with these items:
 
-version                 Nvim version, API level/compatibility
-version.api_level       API version integer *api-level*
-version.api_compatible  API is backwards-compatible with this level
-version.api_prerelease  Declares the API as unstable/unreleased >
-                        (version.api_prerelease && fn.since == version.api_level)
-functions               API function signatures, containing |api-types| info
-                        describing the return value and parameters.
-ui_events               |UI| event signatures
-ui_options              Supported |ui-option|s
-{fn}.since              API level where function {fn} was introduced
-{fn}.deprecated_since   API level where function {fn} was deprecated
-types                   Custom handle types defined by Nvim
-error_types             Possible error types returned by API functions
+- version                 Nvim version, API level/compatibility
+- version.api_level       API version integer *api-level*
+- version.api_compatible  API is backwards-compatible with this level
+- version.api_prerelease  Declares the API as unstable/unreleased
+                          `(version.api_prerelease && fn.since == version.api_level)`
+- functions               API function signatures, containing |api-types| info
+                          describing the return value and parameters.
+- ui_events               |UI| event signatures
+- ui_options              Supported |ui-option|s
+- {fn}.since              API level where function {fn} was introduced
+- {fn}.deprecated_since   API level where function {fn} was deprecated
+- types                   Custom handle types defined by Nvim
+- error_types             Possible error types returned by API functions
 
 About the `functions` map:
 
@@ -230,6 +231,15 @@ As Nvim evolves the API may change in compliance with this CONTRACT:
   - Existing items will not be removed (after release).
 - Deprecated functions will not be removed until Nvim version 2.0
 
+"Private" interfaces are NOT covered by this contract:
+
+- Undocumented (not in :help) functions or events of any kind
+- nvim__x ("double underscore") functions
+
+The idea is "versionless evolution", in the words of Rich Hickey:
+- Relaxing a requirement should be a compatible change.
+- Strengthening a promise should be a compatible change.
+
 ==============================================================================
 Global events                                               *api-global-events*
 
@@ -345,7 +355,7 @@ LUA ~
 In-process Lua plugins can receive buffer updates in the form of Lua
 callbacks. These callbacks are called frequently in various contexts;
 |textlock| prevents changing buffer contents and window layout (use
-|vim.schedule| to defer such operations to the main loop instead).
+|vim.schedule()| to defer such operations to the main loop instead).
 
 |nvim_buf_attach()| will take keyword args for the callbacks. "on_lines" will
 receive parameters ("lines", {buf}, {changedtick}, {firstline}, {lastline},
@@ -433,7 +443,7 @@ its config is non-empty: >
     if vim.api.nvim_win_get_config(window_id).relative ~= '' then
       -- window with this window_id is floating
     end
->
+<
 
 Buffer text can be highlighted by typical mechanisms (syntax highlighting,
 |api-highlights|). The |hl-NormalFloat| group highlights normal text;
@@ -455,7 +465,7 @@ Example: create a float with scratch buffer: >
     let win = nvim_open_win(buf, 0, opts)
     " optional: change highlight, otherwise Pmenu is used
     call nvim_win_set_option(win, 'winhl', 'Normal:MyHighlight')
->
+<
 
 ==============================================================================
 Extended marks                                  *api-extended-marks* *extmarks*
@@ -499,8 +509,8 @@ Let's set an extmark at the first row (row=0) and third column (column=2).
 
       01 2345678
     0 ex|ample..
-<        ^ extmark position
->
+        ^ extmark position
+
     let g:mark_ns = nvim_create_namespace('myplugin')
     let g:mark_id = nvim_buf_set_extmark(0, g:mark_ns, 0, 2, {})
 <
@@ -519,8 +529,8 @@ use |nvim_buf_del_extmark()|. Deleting "x" in our example: >
 
       0 12345678
     0 e|ample..
-<       ^ extmark position
->
+       ^ extmark position
+
     echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_id, {})
     => [0, 1]
 <
@@ -544,9 +554,9 @@ nvim__get_runtime({pat}, {all}, {*opts})                 *nvim__get_runtime()*
         |api-fast|
 
     Parameters: ~
-        {pat}   pattern of files to search for
-        {all}   whether to return all matches or only the first
-        {opts}  is_lua: only search lua subdirs
+      • {pat}   pattern of files to search for
+      • {all}   whether to return all matches or only the first
+      • {opts}  is_lua: only search lua subdirs
 
     Return: ~
         list of absolute paths to the found files
@@ -558,7 +568,7 @@ nvim__id({obj})                                                   *nvim__id()*
     in plugins.
 
     Parameters: ~
-        {obj}  Object to return.
+      • {obj}  Object to return.
 
     Return: ~
         its argument.
@@ -570,7 +580,7 @@ nvim__id_array({arr})                                       *nvim__id_array()*
     in plugins.
 
     Parameters: ~
-        {arr}  Array to return.
+      • {arr}  Array to return.
 
     Return: ~
         its argument.
@@ -582,7 +592,7 @@ nvim__id_dictionary({dct})                             *nvim__id_dictionary()*
     in plugins.
 
     Parameters: ~
-        {dct}  Dictionary to return.
+      • {dct}  Dictionary to return.
 
     Return: ~
         its argument.
@@ -594,7 +604,7 @@ nvim__id_float({flt})                                       *nvim__id_float()*
     in plugins.
 
     Parameters: ~
-        {flt}  Value to return.
+      • {flt}  Value to return.
 
     Return: ~
         its argument.
@@ -624,7 +634,7 @@ nvim_call_atomic({calls})                                 *nvim_call_atomic()*
         |RPC| only
 
     Parameters: ~
-        {calls}  an array of calls, where each call is described by an array
+      • {calls}  an array of calls, where each call is described by an array
                  with two elements: the request name, and an array of
                  arguments.
 
@@ -648,18 +658,18 @@ nvim_chan_send({chan}, {data})                              *nvim_chan_send()*
 
     Attributes: ~
         |RPC| only
-        |vim.api| only
+        Lua |vim.api| only
 
     Parameters: ~
-        {chan}  id of the channel
-        {data}  data to write. 8-bit clean: can contain NUL bytes.
+      • {chan}  id of the channel
+      • {data}  data to write. 8-bit clean: can contain NUL bytes.
 
 nvim_create_buf({listed}, {scratch})                       *nvim_create_buf()*
     Creates a new, empty, unnamed buffer.
 
     Parameters: ~
-        {listed}   Sets 'buflisted'
-        {scratch}  Creates a "throwaway" |scratch-buffer| for temporary work
+      • {listed}   Sets 'buflisted'
+      • {scratch}  Creates a "throwaway" |scratch-buffer| for temporary work
                    (always 'nomodified'). Also sets 'nomodeline' on the
                    buffer.
 
@@ -690,7 +700,7 @@ nvim_del_mark({name})                                        *nvim_del_mark()*
         fails with error if a lowercase or buffer local named mark is used.
 
     Parameters: ~
-        {name}  Mark name
+      • {name}  Mark name
 
     Return: ~
         true if the mark was deleted, else false.
@@ -703,31 +713,31 @@ nvim_del_var({name})                                          *nvim_del_var()*
     Removes a global (g:) variable.
 
     Parameters: ~
-        {name}  Variable name
+      • {name}  Variable name
 
 nvim_echo({chunks}, {history}, {opts})                           *nvim_echo()*
     Echo a message.
 
     Parameters: ~
-        {chunks}   A list of [text, hl_group] arrays, each representing a text
+      • {chunks}   A list of [text, hl_group] arrays, each representing a text
                    chunk with specified highlight. `hl_group` element can be
                    omitted for no highlight.
-        {history}  if true, add to |message-history|.
-        {opts}     Optional parameters. Reserved for future use.
+      • {history}  if true, add to |message-history|.
+      • {opts}     Optional parameters. Reserved for future use.
 
 nvim_err_write({str})                                       *nvim_err_write()*
     Writes a message to the Vim error buffer. Does not append "\n", the
     message is buffered (won't display) until a linefeed is written.
 
     Parameters: ~
-        {str}  Message
+      • {str}  Message
 
 nvim_err_writeln({str})                                   *nvim_err_writeln()*
     Writes a message to the Vim error buffer. Appends "\n", so the buffer is
     flushed (and displayed).
 
     Parameters: ~
-        {str}  Message
+      • {str}  Message
 
     See also: ~
         nvim_err_write()
@@ -739,8 +749,8 @@ nvim_eval_statusline({str}, {*opts})                  *nvim_eval_statusline()*
         |api-fast|
 
     Parameters: ~
-        {str}   Statusline string (see 'statusline').
-        {opts}  Optional parameters.
+      • {str}   Statusline string (see 'statusline').
+      • {opts}  Optional parameters.
                 • winid: (number) |window-ID| of the window to use as context
                   for statusline.
                 • maxwidth: (number) Maximum width of statusline.
@@ -750,7 +760,7 @@ nvim_eval_statusline({str}, {*opts})                  *nvim_eval_statusline()*
                 • highlights: (boolean) Return highlight information.
                 • use_winbar: (boolean) Evaluate winbar instead of statusline.
                 • use_tabline: (boolean) Evaluate tabline instead of
-                  statusline. When |TRUE|, {winid} is ignored. Mutually
+                  statusline. When true, {winid} is ignored. Mutually
                   exclusive with {use_winbar}.
 
     Return: ~
@@ -759,7 +769,7 @@ nvim_eval_statusline({str}, {*opts})                  *nvim_eval_statusline()*
         • width: (number) Display width of the statusline.
         • highlights: Array containing highlight information of the
           statusline. Only included when the "highlights" key in {opts} is
-          |TRUE|. Each element of the array is a |Dictionary| with these keys:
+          true. Each element of the array is a |Dictionary| with these keys:
           • start: (number) Byte index (0-based) of first character that uses
             the highlight.
           • group: (string) Name of highlight group.
@@ -775,8 +785,8 @@ nvim_exec_lua({code}, {args})                                *nvim_exec_lua()*
         |RPC| only
 
     Parameters: ~
-        {code}  Lua code to execute
-        {args}  Arguments to the code
+      • {code}  Lua code to execute
+      • {args}  Arguments to the code
 
     Return: ~
         Return value of Lua code if present or NIL.
@@ -797,9 +807,9 @@ nvim_feedkeys({keys}, {mode}, {escape_ks})                   *nvim_feedkeys()*
 <
 
     Parameters: ~
-        {keys}       to be typed
-        {mode}       behavior flags, see |feedkeys()|
-        {escape_ks}  If true, escape K_SPECIAL bytes in `keys` This should be
+      • {keys}       to be typed
+      • {mode}       behavior flags, see |feedkeys()|
+      • {escape_ks}  If true, escape K_SPECIAL bytes in `keys` This should be
                      false if you already used |nvim_replace_termcodes()|, and
                      true otherwise.
 
@@ -853,7 +863,7 @@ nvim_get_color_by_name({name})                      *nvim_get_color_by_name()*
 <
 
     Parameters: ~
-        {name}  Color name or "#rrggbb" string
+      • {name}  Color name or "#rrggbb" string
 
     Return: ~
         24-bit RGB value, or -1 for invalid argument.
@@ -871,7 +881,7 @@ nvim_get_context({*opts})                                 *nvim_get_context()*
     Gets a map of the current editor state.
 
     Parameters: ~
-        {opts}  Optional parameters.
+      • {opts}  Optional parameters.
                 • types: List of |context-types| ("regs", "jumps", "bufs",
                   "gvars", …) to gather, or empty for "all".
 
@@ -906,8 +916,8 @@ nvim_get_hl_by_id({hl_id}, {rgb})                        *nvim_get_hl_by_id()*
     Gets a highlight definition by id. |hlID()|
 
     Parameters: ~
-        {hl_id}  Highlight id as returned by |hlID()|
-        {rgb}    Export RGB colors
+      • {hl_id}  Highlight id as returned by |hlID()|
+      • {rgb}    Export RGB colors
 
     Return: ~
         Highlight definition map
@@ -919,8 +929,8 @@ nvim_get_hl_by_name({name}, {rgb})                     *nvim_get_hl_by_name()*
     Gets a highlight definition by name.
 
     Parameters: ~
-        {name}  Highlight group name
-        {rgb}   Export RGB colors
+      • {name}  Highlight group name
+      • {rgb}   Export RGB colors
 
     Return: ~
         Highlight definition map
@@ -937,7 +947,7 @@ nvim_get_keymap({mode})                                    *nvim_get_keymap()*
     Gets a list of global (non-buffer-local) |mapping| definitions.
 
     Parameters: ~
-        {mode}  Mode short-name ("n", "i", "v", ...)
+      • {mode}  Mode short-name ("n", "i", "v", ...)
 
     Return: ~
         Array of |maparg()|-like dictionaries describing mappings. The
@@ -953,8 +963,8 @@ nvim_get_mark({name}, {opts})                                *nvim_get_mark()*
         fails with error if a lowercase or buffer local named mark is used.
 
     Parameters: ~
-        {name}  Mark name
-        {opts}  Optional parameters. Reserved for future use.
+      • {name}  Mark name
+      • {opts}  Optional parameters. Reserved for future use.
 
     Return: ~
         4-tuple (row, col, buffer, buffername), (0, 0, 0, '') if the mark is
@@ -989,7 +999,7 @@ nvim_get_proc_children({pid})                       *nvim_get_proc_children()*
 nvim_get_runtime_file({name}, {all})                 *nvim_get_runtime_file()*
     Find files in runtime directories
 
-    'name' can contain wildcards. For example
+    "name" can contain wildcards. For example
     nvim_get_runtime_file("colors/*.vim", true) will return all color scheme
     files. Always use forward slashes (/) in the search pattern for
     subdirectories regardless of platform.
@@ -1000,8 +1010,8 @@ nvim_get_runtime_file({name}, {all})                 *nvim_get_runtime_file()*
         |api-fast|
 
     Parameters: ~
-        {name}  pattern of files to search for
-        {all}   whether to return all matches or only the first
+      • {name}  pattern of files to search for
+      • {all}   whether to return all matches or only the first
 
     Return: ~
         list of absolute paths to the found files
@@ -1010,7 +1020,7 @@ nvim_get_var({name})                                          *nvim_get_var()*
     Gets a global (g:) variable.
 
     Parameters: ~
-        {name}  Variable name
+      • {name}  Variable name
 
     Return: ~
         Variable value
@@ -1019,7 +1029,7 @@ nvim_get_vvar({name})                                        *nvim_get_vvar()*
     Gets a v: variable.
 
     Parameters: ~
-        {name}  Variable name
+      • {name}  Variable name
 
     Return: ~
         Variable value
@@ -1043,7 +1053,7 @@ nvim_input({keys})                                              *nvim_input()*
         |api-fast|
 
     Parameters: ~
-        {keys}  to be typed
+      • {keys}  to be typed
 
     Return: ~
         Number of bytes actually written (can be fewer than requested if the
@@ -1067,16 +1077,18 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col})
         |api-fast|
 
     Parameters: ~
-        {button}    Mouse button: one of "left", "right", "middle", "wheel".
-        {action}    For ordinary buttons, one of "press", "drag", "release".
+      • {button}    Mouse button: one of "left", "right", "middle", "wheel",
+                    "move".
+      • {action}    For ordinary buttons, one of "press", "drag", "release".
                     For the wheel, one of "up", "down", "left", "right".
-        {modifier}  String of modifiers each represented by a single char. The
+                    Ignored for "move".
+      • {modifier}  String of modifiers each represented by a single char. The
                     same specifiers are used as for a key press, except that
                     the "-" separator is optional, so "C-A-", "c-a" and "CA"
                     can all be used to specify Ctrl+Alt+click.
-        {grid}      Grid number if the client uses |ui-multigrid|, else 0.
-        {row}       Mouse row-position (zero-based, like redraw events)
-        {col}       Mouse column-position (zero-based, like redraw events)
+      • {grid}      Grid number if the client uses |ui-multigrid|, else 0.
+      • {row}       Mouse row-position (zero-based, like redraw events)
+      • {col}       Mouse column-position (zero-based, like redraw events)
 
 nvim_list_bufs()                                            *nvim_list_bufs()*
     Gets the current list of buffer handles
@@ -1127,7 +1139,7 @@ nvim_load_context({dict})                                *nvim_load_context()*
     Sets the current editor state from the given |context| map.
 
     Parameters: ~
-        {dict}  |Context| map.
+      • {dict}  |Context| map.
 
 nvim_notify({msg}, {log_level}, {opts})                        *nvim_notify()*
     Notify the user with a message
@@ -1136,9 +1148,9 @@ nvim_notify({msg}, {log_level}, {opts})                        *nvim_notify()*
     echo area but can be overridden to trigger desktop notifications.
 
     Parameters: ~
-        {msg}        Message to display to the user
-        {log_level}  The log level
-        {opts}       Reserved for future use.
+      • {msg}        Message to display to the user
+      • {log_level}  The log level
+      • {opts}       Reserved for future use.
 
 nvim_open_term({buffer}, {opts})                            *nvim_open_term()*
     Open a terminal instance in a buffer
@@ -1156,13 +1168,13 @@ nvim_open_term({buffer}, {opts})                            *nvim_open_term()*
     virtual terminal having the intended size.
 
     Parameters: ~
-        {buffer}  the buffer to use (expected to be empty)
-        {opts}    Optional parameters.
+      • {buffer}  the buffer to use (expected to be empty)
+      • {opts}    Optional parameters.
                   • on_input: lua callback for input sent, i e keypresses in
                     terminal mode. Note: keypresses are sent raw as they would
                     be to the pty master end. For instance, a carriage return
                     is sent as a "\r", not as a "\n". |textlock| applies. It
-                    is possible to call |nvim_chan_send| directly in the
+                    is possible to call |nvim_chan_send()| directly in the
                     callback however. ["input", term, bufnr, data]
 
     Return: ~
@@ -1173,7 +1185,7 @@ nvim_out_write({str})                                       *nvim_out