docs: backport #33549 and #33524 to 0.11 (#33678)

* vim-patch:829eda7: runtime(new-tutor): update tutor and correct comandline completion

Problem: Some parts of the tutor are outdated.

- For example, pressing `<Tab>` after typing `:e` does not complete the
command `:edit`, but shows a completion menu with the first entry being
`:earlier`.

closes: vim/vim#17107

829eda7d38

Co-authored-by: Phạm Bình An <phambinhanctb2004@gmail.com>

Co-authored-by: zeertzjq <zeertzjq@outlook.com>
(cherry picked from commit 374e52a7ee)

* docs: provide example_init.lua #33524

Problem:
There are some "boilerplate" steps for new users. Although we are
constantly improving defaults and lifting patterns into core, users
eventually want to know how to start their own config, add plugins, etc.

Solution:
Add `runtime/example_init.lua` and refer to it from docs.

(cherry picked from commit 86b34ad073)

---------

Co-authored-by: zeertzjq <zeertzjq@outlook.com>

runtime/doc/lua-guide.txt

@@ -93,10 +93,9 @@ Finally, you can include Lua code in a Vimscript file by putting it inside a
 Using Lua files on startup                                    *lua-guide-config*
 
 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`
-and Vimscript in `init.lua`, which will be covered below.
+not both at the same time. This should be placed in your |config| directory
+(run `:echo stdpath('config')` to see where it is). Note that you can also use
+Lua in `init.vim` and Vimscript in `init.lua`, which will be covered below.
 
 If you'd like to run any other Lua script on |startup| automatically, then you
 can simply put it in `plugin/` in your |'runtimepath'|.

runtime/doc/nvim.txt

@@ -75,6 +75,16 @@ the same Nvim configuration on all of your machines, by creating
 ==============================================================================
 What next?                                                   *nvim-quickstart*
 
+If you want to use Lua to configure Nvim, you can copy an example
+configuration to your |init.lua|
+>vim
+    :exe 'edit' stdpath('config') .. '/init.lua'
+    :read $VIMRUNTIME/example_init.lua
+<
+See |lua-guide| for practical notes on using Lua to configure Nvim.
+
+"IDE" features in Nvim are provided by Language Server Protocol. See |lsp|
+
 If you are just trying out Nvim for a few minutes, and want to see the
 extremes of what it can do, try one of these popular "extension packs" or
 "distributions" (Note: Nvim is not affiliated with these projects, and does

runtime/example_init.lua

@@ -0,0 +1,88 @@
+-- Set <space> as the leader key
+-- See `:help mapleader`
+-- NOTE: Must happen before plugins are loaded (otherwise wrong leader will be used)
+vim.g.mapleader = ' '
+
+-- [[ Setting options ]] See `:h vim.o`
+-- NOTE: You can change these options as you wish!
+-- For more options, you can see `:help option-list`
+-- To see documentation for an option, you can use `:h 'optionname'`, for example `:h 'number'`
+-- (Note the single quotes)
+
+-- Print the line number in front of each line
+vim.o.number = true
+
+-- Use relative line numbers, so that it is easier to jump with j, k. This will affect the 'number'
+-- option above, see `:h number_relativenumber`
+vim.o.relativenumber = true
+
+-- Sync clipboard between OS and Neovim. Schedule the setting after `UiEnter` because it can
+-- increase startup-time. Remove this option if you want your OS clipboard to remain independent.
+-- See `:help 'clipboard'`
+vim.api.nvim_create_autocmd('UIEnter', {
+  callback = function()
+    vim.o.clipboard = 'unnamedplus'
+  end,
+})
+
+-- Case-insensitive searching UNLESS \C or one or more capital letters in the search term
+vim.o.ignorecase = true
+vim.o.smartcase = true
+
+-- Highlight the line where the cursor is on
+vim.o.cursorline = true
+
+-- Minimal number of screen lines to keep above and below the cursor.
+vim.o.scrolloff = 10
+
+-- Show <tab> and trailing spaces
+vim.o.list = true
+
+-- if performing an operation that would fail due to unsaved changes in the buffer (like `:q`),
+-- instead raise a dialog asking if you wish to save the current file(s) See `:help 'confirm'`
+vim.o.confirm = true
+
+-- [[ Set up keymaps ]] See `:h vim.keymap.set()`, `:h mapping`, `:h keycodes`
+
+-- Use <Esc> to exit terminal mode
+vim.keymap.set('t', '<Esc>', '<C-\\><C-n>')
+
+-- Map <A-j>, <A-k>, <A-h>, <A-l> to navigate between windows in any modes
+vim.keymap.set({ 't', 'i' }, '<A-h>', '<C-\\><C-n><C-w>h')
+vim.keymap.set({ 't', 'i' }, '<A-j>', '<C-\\><C-n><C-w>j')
+vim.keymap.set({ 't', 'i' }, '<A-k>', '<C-\\><C-n><C-w>k')
+vim.keymap.set({ 't', 'i' }, '<A-l>', '<C-\\><C-n><C-w>l')
+vim.keymap.set({ 'n' }, '<A-h>', '<C-w>h')
+vim.keymap.set({ 'n' }, '<A-j>', '<C-w>j')
+vim.keymap.set({ 'n' }, '<A-k>', '<C-w>k')
+vim.keymap.set({ 'n' }, '<A-l>', '<C-w>l')
+
+-- [[ Basic Autocommands ]].
+-- See `:h lua-guide-autocommands`, `:h autocmd`, `:h nvim_create_autocmd()`
+
+-- Highlight when yanking (copying) text.
+-- Try it with `yap` in normal mode. See `:h vim.hl.on_yank()`
+vim.api.nvim_create_autocmd('TextYankPost', {
+  desc = 'Highlight when yanking (copying) text',
+  callback = function()
+    vim.hl.on_yank()
+  end,
+})
+
+-- [[ Create user commands ]]
+-- See `:h nvim_create_user_command()` and `:h user-commands`
+
+-- Create a command `:GitBlameLine` that print the git blame for the current line
+vim.api.nvim_create_user_command('GitBlameLine', function()
+  local line_number = vim.fn.line('.') -- Get the current line number. See `:h line()`
+  local filename = vim.api.nvim_buf_get_name(0)
+  print(vim.fn.system({ 'git', 'blame', '-L', line_number .. ',+1', filename }))
+end, { desc = 'Print the git blame for the current line' })
+
+-- [[ Add optional packages ]]
+-- Nvim comes bundled with a set of packages that are not enabled by
+-- default. You can enable any of them by using the `:packadd` command.
+
+-- For example, to add the "nohlsearch" package to automatically turn off search highlighting after
+-- 'updatetime' and when going to insert mode
+vim.cmd('packadd! nohlsearch')

runtime/tutor/en/vim-01-beginner.tutor

@@ -464,7 +464,7 @@ Now go on to the next lesson.
 # Lesson 4.1: CURSOR LOCATION AND FILE STATUS
 
 ** Type `<C-g>`{normal} to show your location in a file and the file status.
- Type `G`{normal} to move to a line in the file. **
+ Type `{count}G`{normal} to move to line {count} in the file. **
 
 NOTE: Read the entire lesson before executing any of these steps!!
 
@@ -934,11 +934,20 @@ For more information type `:help init.vim`{vim}.
 
  3. Press `<C-d>`{normal} and Neovim will show a list of commands beginning with "e".
 
- 4. Press `<Tab>`{normal} and Neovim will complete the command name to ":edit".
+ 4. Press `<Tab>`{normal} and Neovim will show a menu with possible completions
+    (or complete the match, if the entered command is unique, e.g.
+    ":ed`<Tab>`{normal}" will be completed to ":edit").
 
- 5. Now add a space and the start of an existing file name: `:edit FIL`{vim}
+ 5. Use `<Tab>`{normal} or `<C-n>`{normal} to go to the next match. Or use
+    `<S-Tab>`{normal} or `<C-p>`{normal} to go to the previous match.
 
- 6. Press `<Tab>`{normal}. Neovim will complete the name ("FIL" -> "FILE", if it is unique).
+ 6. Choose the entry `edit`{vim}. Now you can see that the word `edit`{vim}
+    have been automatically inserted to the command line.
+
+ 7. Now add a space and the start of an existing file name: `:edit FIL`{vim}
+
+ 8. Press `<Tab>`{normal}. Vim will show a completion menu with list of file
+    names that start with `FIL`
 
 NOTE: Completion works for many commands. It is especially useful for `:help`{vim}.
 
@@ -956,7 +965,11 @@ NOTE: Completion works for many commands. It is especially useful for `:help`{vi
  5. Create an init.vim startup script to keep your preferred settings.
 
  6. While in command mode, press `<C-d>`{normal} to see possible completions.
-    Press `<Tab>`{normal} to use one completion.
+    Press `<Tab>`{normal} to use the completion menu and select a match.
+
+# What's next?
+
+Run `:help nvim-quickstart`{vim} to get started with configuring or extending Nvim.
 
 # CONCLUSION
 

runtime/tutor/ja/vim-01-beginner.tutor

@@ -31,7 +31,7 @@ NOTE: 以下の練習用コマンドにはこの文章を変更するものも
 また、次のようにコマンドを実行するよう求められることや、(後で詳しく説明します。)
 
     `:help`{vim} `<Enter>`{normal}
-	
+
 キーシークエンスを押すこともあります。
 ~~~ normal
     <Esc>0f<Space>d3wP$P
@@ -465,8 +465,8 @@ NOTE: タイプ中の間違いはバックスペースキーを使って直す
 
 # レッスン 4.1: 位置とファイルの情報
 
-** ファイル内での位置とファイルの状態を表示するには `<C-g>`{normal} をタイプします。ファイ
-   ル内のある行に移動するには `G`{normal} をタイプします。 **
+** ファイル内での位置とファイルの状態を表示するには `<C-g>`{normal} をタイプします。
+ファイル内の{count}行に移動するには `{count}G`{normal} をタイプします。 **
 
 NOTE: ステップを実行する前に、このレッスン全てに目を通しましょう!!
 
@@ -875,7 +875,7 @@ NOTE: 1つの検索コマンドだけ大文字小文字の区別をやめたい
 ~~~
 # レッスン 7.1: ヘルプコマンド
 
-** Use the online help system. **
+** オンラインヘルプシステムを使用する **
 
 Neovim には広範にわたるオンラインヘルプシステムがあります。
 
@@ -925,11 +925,19 @@ Neovim はとても自由度の高いエディタです。あなたの好きな
 
  3. `<C-d>`{normal} を押すと Neovim は "e" から始まるコマンドの一覧を表示します。
 
- 4. `<Tab>`{normal} とタイプすると Neoim は ":edit" というコマンド名を補完します。
+ 4. `<Tab>`{normal} を押すと、Neovim は可能な補完候補のメニューを表示します
+   （または、ただの一つのマッチがあるときは、補完します。
+     例: ":ed`<Tab>`{normal}" は":edit"に補完されます）。
 
- 5. さらに空白と、既存のファイル名の始まりを加えます: `:edit FIL`{vim}
+ 5. 次のマッチに移動するには `<Tab>`{normal} または `<C-n>`{normal}を使用し、
+   前のマッチに移動するには `<S-Tab>`{normal} または `<C-p>`{normal}を使用します。
 
- 6. `<Tab>`{normal} を押すと Neovim は名前を補完します。("FIL" -> "FILE"、重複しない場合)
+ 6. `edit`{vim} を選択すると、コマンドラインに`edit` が挿入されます。
+
+ 7. さらに空白と、既存のファイル名の始まりを加えます: `:edit FIL`{vim}
+
+ 8. `<Tab>`{normal}を押すと、Vim は `FIL` で始まるファイル名の候補リストを含む補完メニューを
+    表示します。
 
 NOTE: 補完は多くのコマンドで動作します。特に `:help`{vim} の際に役立ちます。
 

test/functional/plugin/tutor_spec.lua

@@ -131,7 +131,7 @@ describe(':Tutor', function()
       {0:  }University. E-mail: {2:bware@mines.colorado.edu}.                                  |
     ]]
 
-    feed(':960<CR>zt')
+    feed(':973<CR>zt')
     screen:expect(expected)
   end)
 end)