commit f01c212e37b091820be633d45f2ae852f4c002f3
parent 3f16037e45cfd7e66986e938ff2a6ff6165ebbed
Author: Justin M. Keyes <justinkz@gmail.com>
Date: Tue, 28 Oct 2025 17:18:47 -0400
docs: rework main help page
Diffstat:
7 files changed, 259 insertions(+), 266 deletions(-)
diff --git 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<Enter>".
- Get out of Vim: Use ":qa!<Enter>" (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_<Esc>
- Command-line command : :help :quit
- Command-line editing c_ :help c_<Del>
- 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*
-
-|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
+About Nvim *reference_toc* *Q_ct*
+
+- |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
-
-|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
+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
------------------------------------------------------------------------------
-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
+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
------------------------------------------------------------------------------
-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 (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
------------------------------------------------------------------------------
-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
+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
------------------------------------------------------------------------------
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<RightMouse>, or <C-RightMouse> 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
@@ -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_<Esc>
+ Command-line command : :help :quit
+ Command-line editing c_ :help c_<Del>
+ 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 <Del> to erase the last digit (|N<Del>|).
+
+ *[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<CR>` 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|.
+
+ *<character>*
+- <character> 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* *<Help>* *:h* *:help* *<F1>* *i_<F1>* *i_<Help>*
<Help> 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
@@ -122,117 +122,8 @@ memory however you may see fit.
- Say Farewell: https://github.com/vim/vim/discussions/12737
==============================================================================
-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 <Del> to erase the last digit (|N<Del>|).
-
- *[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<CR>` 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|.
-
- *<character>*
-- <character> 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*
+Keycodes *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
@@ -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
@@ -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('\<x\>$')
exe "norm! \<c-]>"
diff --git 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
@@ -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('.'))
