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

1 files changed, 46 insertions, 44 deletions

diff --git a/runtime/doc/lua-guide.txt b/runtime/doc/lua-guide.txt
index b971a7d2ad..c15b1b0495 100644
--- a/runtime/doc/lua-guide.txt
+++ b/runtime/doc/lua-guide.txt
@@ -10,16 +10,16 @@
 ==============================================================================
 Introduction                                                         *lua-guide*
 
-This guide will go through the basics of using Lua in Neovim. It is not meant
+This guide will go through the basics of using Lua in Nvim. It is not meant
 to be a comprehensive encyclopedia of all available features, nor will it
 detail all intricacies. Think of it as a survival kit -- the bare minimum
-needed to know to comfortably get started on using Lua in Neovim.
+needed to know to comfortably get started on using Lua in Nvim.
 
 An important thing to note is that this isn't a guide to the Lua language
-itself. Rather, this is a guide on how to configure and modify Neovim through
+itself. Rather, this is a guide on how to configure and modify Nvim through
 the Lua language and the functions we provide to help with this. Take a look
 at |luaref| and |lua-concepts| if you'd like to learn more about Lua itself.
-Similarly, this guide assumes some familiarity with the basics of Neovim
+Similarly, this guide assumes some familiarity with the basics of Nvim
 (commands, options, mappings, autocommands), which are covered in the
 |user-manual|.
 
@@ -27,22 +27,22 @@ Similarly, this guide assumes some familiarity with the basics of Neovim
 Some words on the API                                            *lua-guide-api*
 
 The purpose of this guide is to introduce the different ways of interacting
-with Neovim through Lua (the "API"). This API consists of three different
+with Nvim through Lua (the "API"). This API consists of three different
 layers:
 
-1. The "Vim API" inherited from Vim: |ex-commands| and |builtin-functions| as
+1. The "Vim API" inherited from Vim: |Ex-commands| and |builtin-functions| as
 well as |user-function|s in Vimscript. These are accessed through |vim.cmd()|
 and |vim.fn| respectively, which are discussed under |lua-guide-vimscript|
 below.
 
-2. The "Neovim API" written in C for use in remote plugins and GUIs; see |api|.
+2. The "Nvim API" written in C for use in remote plugins and GUIs; see |api|.
 These functions are accessed through |vim.api|.
 
 3. The "Lua API" written in and specifically for Lua. These are any other
 functions accessible through `vim.*` not mentioned already; see |lua-stdlib|.
 
 This distinction is important, as API functions inherit behavior from their
-original layer: For example, Neovim API functions always need all arguments to
+original layer: For example, Nvim API functions always need all arguments to
 be specified even if Lua itself allows omitting arguments (which are then
 passed as `nil`); and Vim API functions can use 0-based indexing even if Lua
 arrays are 1-indexed by default.
@@ -58,7 +58,7 @@ convenient to use from Lua.
 ==============================================================================
 Using Lua                                                  *lua-guide-using-Lua*
 
-To run Lua code from the Neovim command line, use the |:lua| command:
+To run Lua code from the Nvim command line, use the |:lua| command:
 >vim
     :lua print("Hello!")
 <
@@ -69,10 +69,10 @@ local keyword are not accessible outside of the command. This won't work:
     :lua print(foo)
     " prints "nil" instead of "1"
 <
-You can also use `:lua=`, which is the same as `:lua vim.pretty_print(...)`,
-to conveniently check the value of a variable or a table:
->lua
-    :lua=package
+You can also use `:lua=`, which is equivalent to `:lua vim.print(...)`, to
+conveniently check the value of a variable or a table:
+>vim
+    :lua =package
 <
 To run a Lua script in an external file, you can use the |:source| command
 exactly like for a Vimscript file:
@@ -80,7 +80,7 @@ exactly like for a Vimscript file:
     :source ~/programs/baz/myluafile.lua
 <
 Finally, you can include Lua code in a Vimscript file by putting it inside a
-|lua-heredoc| block:
+|:lua-heredoc| block:
 >vim
     lua << EOF
       local tbl = {1, 2, 3}
@@ -92,7 +92,7 @@ Finally, you can include Lua code in a Vimscript file by putting it inside a
 ------------------------------------------------------------------------------
 Using Lua files on startup                                    *lua-guide-config*
 
-Neovim supports using `init.vim` or `init.lua` as the configuration file, but
+Nvim supports using `init.vim` or `init.lua` as the configuration file, but
 not both at the same time. This should be placed in your |config| directory,
 which is typically `~/.config/nvim` for Linux, BSD, or macOS, and
 `~/AppData/Local/nvim/` for Windows. Note that you can use Lua in `init.vim`
@@ -114,10 +114,10 @@ Let's assume you have the following directory structure:
     |-- after/
     |-- ftplugin/
     |-- lua/
-    |  |-- myluamodule.lua
-    |  |-- other_modules/
-    |     |-- anothermodule.lua
-    |     |-- init.lua
+    |   |-- myluamodule.lua
+    |   |-- other_modules/
+    |       |-- anothermodule.lua
+    |       |-- init.lua
     |-- plugin/
     |-- syntax/
     |-- init.vim
@@ -167,8 +167,8 @@ the cache manually first:
 <
 ------------------------------------------------------------------------------
 See also:
-• |lua-require|
-• |luaref-pcall()|
+• |lua-module-load|
+• |pcall()|
 
 ==============================================================================
 Using Vim commands and functions from Lua                  *lua-guide-vimscript*
@@ -186,7 +186,7 @@ Note that special characters will need to be escaped with backslashes:
 >lua
     vim.cmd("%s/\\Vfoo/bar/g")
 <
-An alternative is to use a literal string (see |luaref-literal|) delimited by
+An alternative is to use a literal string (see |lua-literal|) delimited by
 double brackets `[[ ]]` as in
 >lua
     vim.cmd([[%s/\Vfoo/bar/g]])
@@ -199,8 +199,8 @@ this allows you to pass multiple commands to a single call of |vim.cmd()|:
       highlight link Warning Error
     ]])
 <
-This is the converse of |lua-heredoc| and allows you to include Vimscript code in
-your `init.lua`.
+This is the converse of |:lua-heredoc| and allows you to include Vimscript
+code in your `init.lua`.
 
 If you want to build your Vim command programmatically, the following form can
 be useful (all these are equivalent to the corresponding line above):
@@ -218,7 +218,7 @@ Vimscript are automatically converted:
     print(vim.fn.printf('Hello from %s', 'Lua'))
 
     local reversed_list = vim.fn.reverse({ 'a', 'b', 'c' })
-    print(vim.inspect(reversed_list)) -- { "c", "b", "a" }
+    vim.print(reversed_list) -- { "c", "b", "a" }
 
     local function print_stdout(chan_id, data, name)
       print(data[1])
@@ -261,7 +261,7 @@ Data types are converted automatically. For example:
       key2 = 300
     }
 
-    print(vim.inspect(vim.g.some_global_variable))
+    vim.print(vim.g.some_global_variable)
     --> { key1 = "value", key2 = 300 }
 <
 You can target specific buffers (via number), windows (via |window-ID|), or
@@ -279,7 +279,7 @@ Note that you cannot directly change fields of array variables. This won't
 work:
 >lua
     vim.g.some_global_variable.key2 = 400
-    vim.pretty_print(vim.g.some_global_variable)
+    vim.print(vim.g.some_global_variable)
     --> { key1 = "value", key2 = 300 }
 <
 Instead, you need to create an intermediate Lua table and change this:
@@ -287,7 +287,7 @@ Instead, you need to create an intermediate Lua table and change this:
     local temp_table = vim.g.some_global_variable
     temp_table.key2 = 400
     vim.g.some_global_variable = temp_table
-    vim.pretty_print(vim.g.some_global_variable)
+    vim.print(vim.g.some_global_variable)
     --> { key1 = "value", key2 = 400 }
 <
 To delete a variable, simply set it to `nil`:
@@ -350,7 +350,7 @@ use |vim.opt:get()|:
     --> {...} (big table)
     print(vim.opt.smarttab:get())
     --> false
-    vim.pretty_print(vim.opt.listchars:get())
+    vim.print(vim.opt.listchars:get())
     --> { space = '_', tab = '>~' }
 <
 ------------------------------------------------------------------------------
@@ -363,7 +363,7 @@ and `:let &listchars='space:_,tab:>~'`:
 • |vim.o|:  behaves like |:set|
 • |vim.go|: behaves like |:setglobal|
 • |vim.bo|: for buffer-scoped options
-• |vim.wo|: for window-scoped options
+• |vim.wo|: for window-scoped options (can be double indexed)
 
 For example:
 >lua
@@ -386,6 +386,9 @@ window is used:
 >lua
     vim.bo[4].expandtab = true -- sets expandtab to true in buffer 4
     vim.wo.number = true       -- sets number to true in current window
+    vim.wo[0].number = true    -- same as above
+    vim.wo[0][0].number = true -- sets number to true in current buffer
+                               -- in current window only
     print(vim.wo[0].number)    --> true
 <
 ------------------------------------------------------------------------------
@@ -459,9 +462,9 @@ useful options:
     vim.keymap.set('n', '<Leader>pl1', require('plugin').action,
       { desc = 'Execute action from plugin' })
 <
-• `remap`: By default, all mappings are nonrecursive by default (i.e.,
-  |vim.keymap.set()| behaves like |:noremap|). If the {rhs} is itself a mapping
-  that should be executed, set `remap = true`: >lua
+• `remap`: By default, all mappings are nonrecursive (i.e., |vim.keymap.set()|
+  behaves like |:noremap|). If the {rhs} is itself a mapping that should be
+  executed, set `remap = true`: >lua
     vim.keymap.set('n', '<Leader>ex1', '<cmd>echo "Example 1"<cr>')
     -- add a shorter mapping
     vim.keymap.set('n', 'e', '<Leader>ex1', { remap = true })
@@ -488,7 +491,7 @@ Autocommands                                            *lua-guide-autocommands*
 An |autocommand| is a Vim command or a Lua function that is automatically
 executed whenever one or more |events| are triggered, e.g., when a file is
 read or written, or when a window is created. These are accessible from Lua
-through the Neovim API.
+through the Nvim API.
 
 ------------------------------------------------------------------------------
 Creating autocommands                             *lua-guide-autocommand-create*
@@ -530,7 +533,7 @@ Examples:
     })
 <
 
-Neovim will always call a Lua function with a single table containing information
+Nvim will always call a Lua function with a single table containing information
 about the triggered autocommand. The most useful keys are
 • `match`: a string that matched the `pattern` (see |<amatch>|)
 • `buf`:   the number of the buffer the event was triggered in (see |<abuf>|)
@@ -539,7 +542,7 @@ about the triggered autocommand. The most useful keys are
 
 For example, this allows you to set buffer-local mappings for some filetypes:
 >lua
-    vim.api.nvim.create_autocmd("FileType", {
+    vim.api.nvim_create_autocmd("FileType", {
       pattern = "lua",
       callback = function(args)
         vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = args.buf })
@@ -624,9 +627,9 @@ in a different file:
 >lua
     local mygroup = vim.api.nvim_create_augroup('vimrc', { clear = false })
     vim.api.nvim_create_autocmd({ 'BufNewFile', 'BufRead' }, {
-      pattern = '*.html',
+      pattern = '*.c',
       group = mygroup,
-      command = 'set shiftwidth=4',
+      command = 'set noexpandtab',
     })
 <
 ------------------------------------------------------------------------------
@@ -657,7 +660,7 @@ See also
 • |nvim_exec_autocmds()|: execute all matching autocommands
 
 ==============================================================================
-User commands                                           *lua-guide-usercommands*
+User commands                                           *lua-guide-commands*
 
 |user-commands| are custom Vim commands that call a Vimscript or Lua function.
 Just like built-in commands, they can have arguments, act on ranges, or have
@@ -665,11 +668,10 @@ custom completion of arguments. As these are most useful for plugins, we will
 cover only the basics of this advanced topic.
 
 ------------------------------------------------------------------------------
-Creating user commands                           *lua-guide-usercommands-create*
+Creating user commands                           *lua-guide-commands-create*
 
-User commands can be created through the Neovim API with
-`vim.api.`|nvim_create_user_command()|. This function takes three mandatory
-arguments:
+User commands can be created via |nvim_create_user_command()|. This function
+takes three mandatory arguments:
 • a string that is the name of the command (which must start with an uppercase
   letter to distinguish it from builtin commands);
 • a string containing Vim commands or a Lua function that is executed when the
@@ -734,7 +736,7 @@ the remaining arguments are the same as for |nvim_create_user_command()|:
       { nargs = 1 })
 <
 ------------------------------------------------------------------------------
-Deleting user commands                           *lua-guide-usercommands-delete*
+Deleting user commands                           *lua-guide-commands-delete*
 
 User commands can be deleted with `vim.api.`|nvim_del_user_command()|. The only
 argument is the name of the command: