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

104 files changed, 7683 insertions, 7414 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..0e1cc3c28c 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -51,7 +51,7 @@ 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
 Nvim instance:
->
+>ruby
     #!/usr/bin/env ruby
     # Requires msgpack-rpc: gem install msgpack-rpc
     #
@@ -79,10 +79,11 @@ functions can be called interactively:
 <
 You can also embed Nvim via |jobstart()|, and communicate using |rpcrequest()|
 and |rpcnotify()|:
->
+>vim
     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:
 
@@ -200,9 +201,9 @@ any of these approaches:
      Example (requires Python "pyyaml" and "msgpack-python" modules): >
      nvim --api-info | python -c 'import msgpack, sys, yaml; yaml.dump(msgpack.unpackb(sys.stdin.buffer.read()), sys.stdout)'
 <
-  3. Use the |api_info()| Vimscript function. >
+  3. Use the |api_info()| Vimscript function. >vim
      :lua print(vim.inspect(vim.fn.api_info()))
-<     Example using |filter()| to exclude non-deprecated API functions: >
+<     Example using |filter()| to exclude non-deprecated API functions: >vim
      :new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name')
 
 ==============================================================================
@@ -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,16 +355,16 @@ 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},
 {new_lastline}, {old_byte_size} [, {old_utf32_size}, {old_utf16_size}]).
 Unlike remote channel events the text contents are not passed. The new text can
-be accessed inside the callback as
-
-    `vim.api.nvim_buf_get_lines(buf, firstline, new_lastline, true)`
+be accessed inside the callback as >lua
 
+    vim.api.nvim_buf_get_lines(buf, firstline, new_lastline, true)
+<
 {old_byte_size} is the total size of the replaced region {firstline} to
 {lastline} in bytes, including the final newline after {lastline}. if
 `utf_sizes` is set to true in |nvim_buf_attach()| keyword args, then the
@@ -390,7 +400,7 @@ performance can be improved by calling |nvim_buf_add_highlight()| as an
 asynchronous notification, after first (synchronously) requesting a source id.
 
 Example using the Python API client (|pynvim|):
->
+>python
     src = vim.new_highlight_source()
     buf = vim.current.buffer
     for i in range(5):
@@ -404,7 +414,7 @@ clear highlights from a specific source, in a specific line range or the
 entire buffer by passing in the line range 0, -1 (the latter is the default in
 python as used above).
 
-Example using the API from Vimscript: >
+Example using the API from Vimscript: >vim
 
     call nvim_buf_set_lines(0, 0, 0, v:true, ["test text"])
     let src = nvim_buf_add_highlight(0, 0, "String", 1, 0, 4)
@@ -428,12 +438,12 @@ Two ways to create a floating window:
 To close it use |nvim_win_close()| or a command such as |:close|.
 
 To check whether a window is floating, check whether the `relative` option in
-its config is non-empty: >
+its config is non-empty: >lua
 
     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;
@@ -446,7 +456,7 @@ Currently, floating windows don't support some widgets like scrollbar.
 The output of |:mksession| does not include commands for restoring floating
 windows.
 
-Example: create a float with scratch buffer: >
+Example: create a float with scratch buffer: >vim
 
     let buf = nvim_create_buf(v:false, v:true)
     call nvim_buf_set_lines(buf, 0, -1, v:true, ["test", "text"])
@@ -455,10 +465,10 @@ 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*
+Extended marks                       *api-extended-marks* *extmarks* *extmark*
 
 Extended marks (extmarks) represent buffer annotations that track text changes
 in the buffer. They can represent cursors, folds, misspelled words, anything
@@ -499,30 +509,32 @@ 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
+<
+>vim
     let g:mark_ns = nvim_create_namespace('myplugin')
     let g:mark_id = nvim_buf_set_extmark(0, g:mark_ns, 0, 2, {})
 <
-We can get the mark by its id: >
+We can get the mark by its id: >vim
 
     echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_id, {})
-    => [0, 2]
+    " => [0, 2]
 
-We can get all marks in a buffer by |namespace| (or by a range): >
+We can get all marks in a buffer by |namespace| (or by a range): >vim
 
     echo nvim_buf_get_extmarks(0, g:mark_ns, 0, -1, {})
-    => [[1, 0, 2]]
+    " => [[1, 0, 2]]
 
 Deleting all surrounding text does NOT remove an extmark! To remove extmarks
 use |nvim_buf_del_extmark()|. Deleting "x" in our example: >
 
       0 12345678
     0 e|ample..
-<       ^