diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt index cbda237891..61f11fc712 100644 --- a/runtime/doc/help.txt +++ b/runtime/doc/help.txt @@ -1,179 +1,142 @@ *help.txt* Nvim - NVIM - help - k - Move around: Use the cursor keys, or "h" to go left, h l - "j" to go down, "k" to go up, "l" to go right. j -Close this window: Use ":q". - Get out of Vim: Use ":qa!" (careful, all changes are lost!). - -Jump to a subject: Position the cursor on a tag (e.g. |bars|) and hit CTRL-]. - With the mouse: Double-click the left mouse button on a tag, e.g. |bars|. - Jump back: Type CTRL-O. Repeat to go further back. - -Get specific help: It is possible to go directly to whatever you want help - on, by giving an argument to the |:help| command. - Prepend something to specify the context: *help-context* - - WHAT PREPEND EXAMPLE ~ - Normal mode command :help x - Visual mode command v_ :help v_u - Insert mode command i_ :help i_ - Command-line command : :help :quit - Command-line editing c_ :help c_ - Vim command argument - :help -r - Option ' :help 'textwidth' - Regular expression / :help /[ - See |help-summary| for more contexts and an explanation. - See |notation| for an explanation of the help syntax. - - Search for help: Type ":help word", then hit CTRL-D to see matching - help entries for "word". - Or use ":helpgrep word". |:helpgrep| - - Getting started: Do the Vim tutor, a 30-minute interactive course for the - basic commands, see |vimtutor|. - Read the user manual from start to end: |usr_01.txt| - -Vim stands for Vi IMproved. Most of Vim was made by Bram Moolenaar, but only -through the help of many others. See |credits|. - ============================================================================== -NVIM DOCUMENTATION +Nvim documentation + +If you are new to Nvim, see |nvim-intro|. (To go to a help link, move the +cursor to it and hit CTRL-], or ctrl-click with mouse. Try it here: |bars|.) ------------------------------------------------------------------------------ -ABOUT NVIM *reference_toc* *doc-file-list* *Q_ct* +About Nvim *reference_toc* *Q_ct* -|news| News since the previous release -|nvim| Transitioning from Vim -|vim-differences| Nvim compared to Vim -|faq| Frequently Asked Questions -|user-manual| User manual: How to accomplish editing tasks. -|quickref| Overview of common commands -|tutor| 30-minute interactive course for beginners -|copying| About copyrights -|Kuwasha| Helping poor children in Uganda -|sponsor| Sponsor Vim development, become a registered Vim user -|www| Vim on the World Wide Web -|bugs| Where to send bug reports -|support| Supported platforms +- |news| News since the previous release +- |nvim| Getting start with Nvim +- |tutor| 30-minute interactive course for beginners +- |vim-differences| Nvim compared to Vim +- |faq| Frequently Asked Questions +- |tips| Various tips +- |bugs| Where to send bug reports +- |support| Supported platforms +- |copying| About copyrights ------------------------------------------------------------------------------ -GENERAL +Usage -|intro| Introduction to Vim; notation used in help files -|helphelp| Using the :help files -|index| Index of all commands -|tips| Various tips on using Vim -|message.txt| (Error) messages and explanations -|uganda.txt| Vim distribution and what to do with your money +- |helphelp| Using the `:help` files +- |intro| Introduction to Vim +- |quickref| Overview of common commands +- |index| Index of all commands +- |user-manual| User manual: How to accomplish editing tasks. +- |message.txt| (Error) messages and explanations +- |Kuwasha| Helping poor children in Uganda ------------------------------------------------------------------------------ -BASIC EDITING +Basic editing -|starting| Starting Vim, Vim command arguments, initialisation -|edit-files| Editing and writing files -|motion.txt| Commands for moving around -|scrolling| Scrolling the text in the window -|insert.txt| Insert and Replace mode -|change.txt| Deleting and replacing text -|undo-redo| Undo and Redo -|repeat.txt| Repeating commands, Vim scripts and debugging -|visual-mode| Using Visual mode (selecting text) -|various| Various other commands -|crash-recovery| Recovering from a crash +- |starting| Starting Vim, Vim command arguments, initialisation +- |edit-files| Editing and writing files +- |motion.txt| Commands for moving around +- |scrolling| Scrolling the text in the window +- |insert.txt| Insert and Replace mode +- |change.txt| Deleting and replacing text +- |undo-redo| Undo and Redo +- |repeat.txt| Repeating commands, Vim scripts and debugging +- |visual-mode| Using Visual mode (selecting text) +- |various| Various other commands +- |crash-recovery| Recovering from a crash ------------------------------------------------------------------------------ -ADVANCED EDITING +Advanced editing -|cmdline| Command-line editing -|options| Description of all options -|pattern-searches| Vim regexp patterns and search commands -|key-mapping| Key mapping (shortcuts), abbreviations -|tags| Tags and special searches -|windows| Commands for using windows and buffers -|tabpage| Commands for using tabpages -|spell| Spell checking -|diff| Comparing files -|folding| Hide (fold) ranges of lines -|terminal| Embedded terminal emulator +- |cmdline| Command-line editing +- |options| Description of all options +- |pattern-searches| Vim regexp patterns and search commands +- |key-mapping| Key mapping (shortcuts), abbreviations +- |tags| Tags and special searches +- |windows| Commands for using windows and buffers +- |tabpage| Commands for using tabpages +- |spell| Spell checking +- |diff| Comparing files +- |folding| Hide (fold) ranges of lines +- |terminal| Embedded terminal emulator ------------------------------------------------------------------------------ -API (EXTENSIBILITY/SCRIPTING/PLUGINS) +API (extensibility/scripting/plugins) -|api| Nvim API via RPC, Lua and Vimscript -|ui| Nvim UI protocol -|lua-guide| Nvim Lua guide -|lua| Lua API -|luaref| Lua reference manual -|luvref| Luv (|vim.uv|) reference manual -|autocmd| Event handlers -|job-control| Spawn and control multiple processes -|channel| Nvim asynchronous IO -|vimscript| Vimscript reference -|vimscript-functions| Vimscript functions -|remote-plugin| Nvim remote plugins -|health| Health checking +- |api| Nvim API via RPC, Lua and Vimscript +- |ui| Nvim UI protocol +- |lua-guide| Nvim Lua guide +- |lua| Lua API +- |luaref| Lua reference manual +- |luvref| Luv (|vim.uv|) reference manual +- |autocmd| Event handlers +- |job-control| Spawn and control multiple processes +- |channel| Nvim asynchronous IO +- |vimscript| Vimscript reference +- |vimscript-functions| Vimscript functions +- |remote-plugin| Nvim remote plugins +- |health| Health checking ------------------------------------------------------------------------------ -PROGRAMMING LANGUAGE SUPPORT +Programming language support -|lsp| Language Server Protocol (LSP) -|diagnostic-api| Diagnostic framework -|treesitter| Incremental syntax parsing -|indent.txt| automatic indenting for C and other languages -|syntax| syntax highlighting -|filetype| Settings for specific types of files -|quickfix| Commands for a quick edit-compile-fix cycle -|ft_ada.txt| Ada filetype plugin -|ft_hare.txt| Filetype plugin for Hare -|ft_ps1.txt| PowerShell filetype plugin -|ft_raku.txt| Raku filetype plugin -|ft_rust.txt| Rust filetype plugin -|ft_sql.txt| SQL filetype plugin +- |lsp| Language Server Protocol (LSP) +- |diagnostic-api| Diagnostic framework +- |treesitter| Incremental syntax parsing +- |indent.txt| automatic indenting for C and other languages +- |syntax| syntax highlighting +- |filetype| Settings for specific types of files +- |quickfix| Commands for a quick edit-compile-fix cycle +- |ft_ada.txt| Ada filetype plugin +- |ft_hare.txt| Filetype plugin for Hare +- |ft_ps1.txt| PowerShell filetype plugin +- |ft_raku.txt| Raku filetype plugin +- |ft_rust.txt| Rust filetype plugin +- |ft_sql.txt| SQL filetype plugin ------------------------------------------------------------------------------ UI -|tui| Builtin UI -|gui| External (graphical) UIs -|signs| Signs displayed as window decorations (the "gutter") +- |tui| Builtin UI +- |gui| External (graphical) UIs +- |signs| Signs displayed as window decorations (the "gutter") ------------------------------------------------------------------------------ -LANGUAGE SUPPORT +Multilingual support -|digraph| List of available digraphs -|mbyte.txt| Multibyte text support -|mlang.txt| Non-English language support -|rileft.txt| Right-to-left editing mode -|l10n-arabic.txt| Arabic language support and editing -|l10n-hebrew.txt| Hebrew language support and editing -|l10n-russian.txt| Russian language support and editing -|l10n-vietnamese.txt| Vietnamese language support and editing +- |digraph| List of available digraphs +- |mbyte.txt| Multibyte text support +- |mlang.txt| Non-English language support +- |rileft.txt| Right-to-left editing mode +- |l10n-arabic.txt| Arabic language support and editing +- |l10n-hebrew.txt| Hebrew language support and editing +- |l10n-russian.txt| Russian language support and editing +- |l10n-vietnamese.txt| Vietnamese language support and editing ------------------------------------------------------------------------------ -INTEROP +Interop -|provider| Builtin remote plugin hosts -|if_perl| Perl interface -|if_pyth| Python interface -|if_ruby| Ruby interface +- |provider| Builtin remote plugin hosts +- |if_perl| Perl interface +- |if_pyth| Python interface +- |if_ruby| Ruby interface ------------------------------------------------------------------------------ -VERSIONS +Versions -|deprecated| Deprecated features that will be removed -|vi-differences| Differences between Vim and Vi +- |deprecated| Deprecated features that will be removed +- |vi-differences| Differences between Vim and Vi ------------------------------------------------------------------------------ -DEVELOPING NVIM +Developing nvim -|dev| Development of Nvim -|dev-arch| Internal architecture, modules, data structures -|dev-style| Development style guidelines -|dev-theme| Design guidelines (colorschemes etc.) -|dev-tools| Tools and techniques for developing Nvim -|dev-vimpatch| Merging patches from Vim +- |dev| Development of Nvim +- |dev-arch| Internal architecture, modules, data structures +- |dev-style| Development style guidelines +- |dev-test| Writing and running tests +- |dev-theme| Design guidelines (colorschemes etc.) +- |dev-tools| Tools and techniques for developing Nvim +- |dev-vimpatch| Merging patches from Vim Standard plugins ~ @@ -189,7 +152,7 @@ Now that you've jumped here with CTRL-] or a double mouse click, you can use CTRL-T, CTRL-O, g, or to go back to where you were. Note that tags are within | characters, but when highlighting is enabled these -characters are hidden. That makes it easier to read a command. +characters are hidden (for aesthetics). You can use CTRL-] on any word (even if it is not within "|") and Nvim will try to find help for it. Especially for options in single quotes, e.g. diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt index e927da8ea7..70eeb01e00 100644 --- a/runtime/doc/helphelp.txt +++ b/runtime/doc/helphelp.txt @@ -9,7 +9,143 @@ Help on help files *helphelp* Type |gO| to see the table of contents. ============================================================================== -1. Help commands *online-help* +Help tag conventions *help-context* + +Get specific help: It is possible to go directly to whatever you want help +on, by giving an argument to the |:help| command. Prepend something to specify +the context: > + + WHAT PREPEND EXAMPLE + Normal mode command :help x + Visual mode command v_ :help v_u + Insert mode command i_ :help i_ + Command-line command : :help :quit + Command-line editing c_ :help c_ + Vim command argument - :help -r + Option ' :help 'textwidth' + Regular expression / :help /[ + +See |help-summary| for more contexts and an explanation. +See |notation| for an explanation of the help syntax. + +SEARCH FOR HELP + +Type ":help word", then hit CTRL-D to see matching help entries for "word". Or +use ":helpgrep word". |:helpgrep| + +============================================================================== +Notation *notation* + +When syntax highlighting is used to read this, text that is not typed +literally is often highlighted with the Special group. These are items in [], +{} and <>, and CTRL-X. + +Note that Vim uses all possible characters in commands. Sometimes the [], {} +and <> are part of what you type, the context should make this clear. + + +- [] Characters in square brackets are optional. + + *count* *[count]* +- [count] An optional number that may precede the command to multiply + or iterate the command. If no number is given, a count of one + is used, unless otherwise noted. Note that in this manual the + [count] is not mentioned in the description of the command, + but only in the explanation. This was done to make the + commands easier to look up. If the 'showcmd' option is on, + the (partially) entered count is shown at the bottom of the + window. You can use to erase the last digit (|N|). + + *[quotex]* +- ["x] An optional register designation where text can be stored. + See |registers|. The x is a single character between 'a' and + 'z' or 'A' and 'Z' or '"', and in some cases (with the put + command) between '0' and '9', '%', '#', or others. The + uppercase and lowercase letter designate the same register, + but the lowercase letter is used to overwrite the previous + register contents, while the uppercase letter is used to + append to the previous register contents. Without the ""x" or + with """" the stored text is put into the unnamed register. + + *{}* +- {} Curly braces denote parts of the command which must appear, + but which can take a number of different values. The + differences between Vim and Vi are also given in curly braces + (this will be clear from the context). + + *{char1-char2}* +- {char1-char2} A single character from the range char1 to char2. For + example: {a-z} is a lowercase letter. Multiple ranges may be + concatenated. For example, {a-zA-Z0-9} is any alphanumeric + character. + + *{motion}* *movement* +- {motion} A command that moves the cursor. These are explained in + |motion.txt|. + - Examples: + - `w` to start of next word + - `b` to begin of current word + - `4j` four lines down + - `/The` to next occurrence of "The" + - This is used after an |operator| command to move over the + text that is to be operated upon. + - If the motion includes a count and the operator also has + a count, the two counts are multiplied. For example: + "2d3w" deletes six words. + - The motion can be backwards, e.g. "db" to delete to the + start of the word. + - The motion can also be a mouse click. The mouse is not + supported in every terminal though. + - The ":omap" command can be used to map characters while an + operator is pending. + - Ex commands can be used to move the cursor. This can be + used to call a function that does some complicated motion. + The motion is always charwise exclusive, no matter what + ":" command is used. This means it's impossible to + include the last character of a line without the line + break (unless 'virtualedit' is set). If the Ex command + changes the text before where the operator starts or jumps + to another buffer the result is unpredictable. It is + possible to change the text further down. Jumping to + another buffer is possible if the current buffer is not + unloaded. + + *{Visual}* +- {Visual} A selected text area. It is started with the "v", "V", or + CTRL-V command, then any cursor movement command can be used + to change the end of the selected text. + This is used before an |operator| command to highlight the + text that is to be operated upon. + See |Visual-mode|. + + ** +- A special character from the table below, optionally with + modifiers, or a single ASCII character with modifiers. + + *'character'* +- 'c' A single ASCII character. + + *CTRL-{char}* +- CTRL-{char} {char} typed as a control character; that is, typing {char} + while holding the CTRL key down. The case of {char} is + ignored; thus CTRL-A and CTRL-a are equivalent. But in + some terminals and environments, using the SHIFT key will + produce a distinct code (e.g. CTRL-SHIFT-a); in these + environments using the SHIFT key will not trigger commands + such as CTRL-A. + + *'option'* +- 'option' An option, or parameter, that can be set to a value, is + enclosed in single quotes. See |options|. + + *quotecommandquote* +- "command" A reference to a command that you can type is enclosed in + double quotes. +- `command` New style command, this distinguishes it from other quoted + text and strings. + +============================================================================== +Help commands *online-help* *help* ** *:h* *:help* ** *i_* *i_* or @@ -240,7 +376,7 @@ file. The files in $VIMRUNTIME/doc are skipped. ============================================================================== -2. Translated help files *help-translated* +Translated help files *help-translated* It is possible to add translated help files, next to the original English help files. Vim will search for all help in "doc" directories in 'runtimepath'. @@ -311,7 +447,7 @@ Hints for translators: languages in the specified directory. ============================================================================== -3. Writing help files *help-writing* +Writing help files *help-writing* For ease of use, a Vim help file for a plugin should follow the format of the standard Vim help files, except for the first line. If you are writing a new diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt index 5b1c4bbd62..16da1ee456 100644 --- a/runtime/doc/intro.txt +++ b/runtime/doc/intro.txt @@ -122,117 +122,8 @@ memory however you may see fit. - Say Farewell: https://github.com/vim/vim/discussions/12737 ============================================================================== -Notation *notation* +Keycodes *key-notation* *key-codes* *keycodes* -When syntax highlighting is used to read this, text that is not typed -literally is often highlighted with the Special group. These are items in [], -{} and <>, and CTRL-X. - -Note that Vim uses all possible characters in commands. Sometimes the [], {} -and <> are part of what you type, the context should make this clear. - - -- [] Characters in square brackets are optional. - - *count* *[count]* -- [count] An optional number that may precede the command to multiply - or iterate the command. If no number is given, a count of one - is used, unless otherwise noted. Note that in this manual the - [count] is not mentioned in the description of the command, - but only in the explanation. This was done to make the - commands easier to look up. If the 'showcmd' option is on, - the (partially) entered count is shown at the bottom of the - window. You can use to erase the last digit (|N|). - - *[quotex]* -- ["x] An optional register designation where text can be stored. - See |registers|. The x is a single character between 'a' and - 'z' or 'A' and 'Z' or '"', and in some cases (with the put - command) between '0' and '9', '%', '#', or others. The - uppercase and lowercase letter designate the same register, - but the lowercase letter is used to overwrite the previous - register contents, while the uppercase letter is used to - append to the previous register contents. Without the ""x" or - with """" the stored text is put into the unnamed register. - - *{}* -- {} Curly braces denote parts of the command which must appear, - but which can take a number of different values. The - differences between Vim and Vi are also given in curly braces - (this will be clear from the context). - - *{char1-char2}* -- {char1-char2} A single character from the range char1 to char2. For - example: {a-z} is a lowercase letter. Multiple ranges may be - concatenated. For example, {a-zA-Z0-9} is any alphanumeric - character. - - *{motion}* *movement* -- {motion} A command that moves the cursor. These are explained in - |motion.txt|. - - Examples: - - `w` to start of next word - - `b` to begin of current word - - `4j` four lines down - - `/The` to next occurrence of "The" - - This is used after an |operator| command to move over the - text that is to be operated upon. - - If the motion includes a count and the operator also has - a count, the two counts are multiplied. For example: - "2d3w" deletes six words. - - The motion can be backwards, e.g. "db" to delete to the - start of the word. - - The motion can also be a mouse click. The mouse is not - supported in every terminal though. - - The ":omap" command can be used to map characters while an - operator is pending. - - Ex commands can be used to move the cursor. This can be - used to call a function that does some complicated motion. - The motion is always charwise exclusive, no matter what - ":" command is used. This means it's impossible to - include the last character of a line without the line - break (unless 'virtualedit' is set). If the Ex command - changes the text before where the operator starts or jumps - to another buffer the result is unpredictable. It is - possible to change the text further down. Jumping to - another buffer is possible if the current buffer is not - unloaded. - - *{Visual}* -- {Visual} A selected text area. It is started with the "v", "V", or - CTRL-V command, then any cursor movement command can be used - to change the end of the selected text. - This is used before an |operator| command to highlight the - text that is to be operated upon. - See |Visual-mode|. - - ** -- A special character from the table below, optionally with - modifiers, or a single ASCII character with modifiers. - - *'character'* -- 'c' A single ASCII character. - - *CTRL-{char}* -- CTRL-{char} {char} typed as a control character; that is, typing {char} - while holding the CTRL key down. The case of {char} is - ignored; thus CTRL-A and CTRL-a are equivalent. But in - some terminals and environments, using the SHIFT key will - produce a distinct code (e.g. CTRL-SHIFT-a); in these - environments using the SHIFT key will not trigger commands - such as CTRL-A. - - *'option'* -- 'option' An option, or parameter, that can be set to a value, is - enclosed in single quotes. See |options|. - - *quotecommandquote* -- "command" A reference to a command that you can type is enclosed in - double quotes. -- `command` New style command, this distinguishes it from other quoted - text and strings. - - *key-notation* *key-codes* *keycodes* These names for keys are used in the documentation. They can also be used with the ":map" command. diff --git a/src/gen/gen_help_html.lua b/src/gen/gen_help_html.lua index c6dfe769c8..08ab301eed 100644 --- a/src/gen/gen_help_html.lua +++ b/src/gen/gen_help_html.lua @@ -69,6 +69,7 @@ local new_layout = { ['dev_theme.txt'] = true, ['dev_tools.txt'] = true, ['dev_vimpatch.txt'] = true, + ['help.txt'] = true, ['faq.txt'] = true, ['gui.txt'] = true, ['intro.txt'] = true, diff --git a/test/old/testdir/test_normal.vim b/test/old/testdir/test_normal.vim index 5e15858ec3..8980a5187a 100644 --- a/test/old/testdir/test_normal.vim +++ b/test/old/testdir/test_normal.vim @@ -1941,7 +1941,7 @@ func Test_normal25_tag() " Testing for CTRL-] g CTRL-] g] " CTRL-W g] CTRL-W CTRL-] CTRL-W g CTRL-] - h + help helphelp " Test for CTRL-] call search('\$') exe "norm! \" diff --git a/test/old/testdir/test_visual.vim b/test/old/testdir/test_visual.vim index f5a5970e24..4e04a567e3 100644 --- a/test/old/testdir/test_visual.vim +++ b/test/old/testdir/test_visual.vim @@ -2610,12 +2610,12 @@ endfunc func Test_getregion_invalid_buf() new - help - call cursor(5, 7) + help index + call cursor(7, 6) norm! mA - call cursor(5, 18) + call cursor(7, 18) norm! mB - call assert_equal(['Move around:'], getregion(getpos("'A"), getpos("'B"))) + call assert_equal(['file contains'], getregion(getpos("'A"), getpos("'B"))) " close the help window q call assert_fails("call getregion(getpos(\"'A\"), getpos(\"'B\"))", 'E681:') diff --git a/test/old/testdir/test_window_cmd.vim b/test/old/testdir/test_window_cmd.vim index 1849758117..dc71180c7b 100644 --- a/test/old/testdir/test_window_cmd.vim +++ b/test/old/testdir/test_window_cmd.vim @@ -599,11 +599,12 @@ func Test_window_jump_tag() help /Kuwasha - call assert_match('^|Kuwasha|', getline('.')) + call assert_match('^- |Kuwasha|', getline('.')) call assert_equal(2, winnr('$')) + norm! fK 2wincmd } call assert_equal(3, winnr('$')) - call assert_match('^|Kuwasha|', getline('.')) + call assert_match('^- |Kuwasha|', getline('.')) wincmd k call assert_match('\*Kuwasha\*', getline('.')) call assert_equal(2, winheight(0)) @@ -612,6 +613,7 @@ func Test_window_jump_tag() set previewheight=4 help /bugs + norm! fb wincmd } wincmd k call assert_match('\*bugs\*', getline('.'))