mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-12-11 09:02:40 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: rework main help page

Browse Source
This commit is contained in:
Justin M. Keyes
2025-10-28 17:18:47 -04:00
parent 3f16037e45
commit f01c212e37
7 changed files with 253 additions and 260 deletions
Download Patch File Download Diff File Expand all files Collapse all files

243
runtime/doc/help.txt
View File

@@ -1,179 +1,142 @@
*help.txt* Nvim *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* About Nvim *reference_toc* *Q_ct*
|news| News since the previous release - |news| News since the previous release
|nvim| Transitioning from Vim - |nvim| Getting start with Nvim
|vim-differences| Nvim compared to Vim - |tutor| 30-minute interactive course for beginners
|faq| Frequently Asked Questions - |vim-differences| Nvim compared to Vim
|user-manual| User manual: How to accomplish editing tasks. - |faq| Frequently Asked Questions
|quickref| Overview of common commands - |tips| Various tips
|tutor| 30-minute interactive course for beginners - |bugs| Where to send bug reports
|copying| About copyrights - |support| Supported platforms
|Kuwasha| Helping poor children in Uganda - |copying| About copyrights
|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
------------------------------------------------------------------------------ ------------------------------------------------------------------------------
GENERAL Usage
|intro| Introduction to Vim; notation used in help files - |helphelp| Using the `:help` files
|helphelp| Using the :help files - |intro| Introduction to Vim
|index| Index of all commands - |quickref| Overview of common commands
|tips| Various tips on using Vim - |index| Index of all commands
|message.txt| (Error) messages and explanations - |user-manual| User manual: How to accomplish editing tasks.
|uganda.txt| Vim distribution and what to do with your money - |message.txt| (Error) messages and explanations
- |Kuwasha| Helping poor children in Uganda
------------------------------------------------------------------------------ ------------------------------------------------------------------------------
BASIC EDITING Basic editing
|starting| Starting Vim, Vim command arguments, initialisation - |starting| Starting Vim, Vim command arguments, initialisation
|edit-files| Editing and writing files - |edit-files| Editing and writing files
|motion.txt| Commands for moving around - |motion.txt| Commands for moving around
|scrolling| Scrolling the text in the window - |scrolling| Scrolling the text in the window
|insert.txt| Insert and Replace mode - |insert.txt| Insert and Replace mode
|change.txt| Deleting and replacing text - |change.txt| Deleting and replacing text
|undo-redo| Undo and Redo - |undo-redo| Undo and Redo
|repeat.txt| Repeating commands, Vim scripts and debugging - |repeat.txt| Repeating commands, Vim scripts and debugging
|visual-mode| Using Visual mode (selecting text) - |visual-mode| Using Visual mode (selecting text)
|various| Various other commands - |various| Various other commands
|crash-recovery| Recovering from a crash - |crash-recovery| Recovering from a crash
------------------------------------------------------------------------------ ------------------------------------------------------------------------------
ADVANCED EDITING Advanced editing
|cmdline| Command-line editing - |cmdline| Command-line editing
|options| Description of all options - |options| Description of all options
|pattern-searches| Vim regexp patterns and search commands - |pattern-searches| Vim regexp patterns and search commands
|key-mapping| Key mapping (shortcuts), abbreviations - |key-mapping| Key mapping (shortcuts), abbreviations
|tags| Tags and special searches - |tags| Tags and special searches
|windows| Commands for using windows and buffers - |windows| Commands for using windows and buffers
|tabpage| Commands for using tabpages - |tabpage| Commands for using tabpages
|spell| Spell checking - |spell| Spell checking
|diff| Comparing files - |diff| Comparing files
|folding| Hide (fold) ranges of lines - |folding| Hide (fold) ranges of lines
|terminal| Embedded terminal emulator - |terminal| Embedded terminal emulator
------------------------------------------------------------------------------ ------------------------------------------------------------------------------
API (EXTENSIBILITY/SCRIPTING/PLUGINS) API (extensibility/scripting/plugins)
|api| Nvim API via RPC, Lua and Vimscript - |api| Nvim API via RPC, Lua and Vimscript
|ui| Nvim UI protocol - |ui| Nvim UI protocol
|lua-guide| Nvim Lua guide - |lua-guide| Nvim Lua guide
|lua| Lua API - |lua| Lua API
|luaref| Lua reference manual - |luaref| Lua reference manual
|luvref| Luv (|vim.uv|) reference manual - |luvref| Luv (|vim.uv|) reference manual
|autocmd| Event handlers - |autocmd| Event handlers
|job-control| Spawn and control multiple processes - |job-control| Spawn and control multiple processes
|channel| Nvim asynchronous IO - |channel| Nvim asynchronous IO
|vimscript| Vimscript reference - |vimscript| Vimscript reference
|vimscript-functions| Vimscript functions - |vimscript-functions| Vimscript functions
|remote-plugin| Nvim remote plugins - |remote-plugin| Nvim remote plugins
|health| Health checking - |health| Health checking
------------------------------------------------------------------------------ ------------------------------------------------------------------------------
PROGRAMMING LANGUAGE SUPPORT Programming language support
|lsp| Language Server Protocol (LSP) - |lsp| Language Server Protocol (LSP)
|diagnostic-api| Diagnostic framework - |diagnostic-api| Diagnostic framework
|treesitter| Incremental syntax parsing - |treesitter| Incremental syntax parsing
|indent.txt| automatic indenting for C and other languages - |indent.txt| automatic indenting for C and other languages
|syntax| syntax highlighting - |syntax| syntax highlighting
|filetype| Settings for specific types of files - |filetype| Settings for specific types of files
|quickfix| Commands for a quick edit-compile-fix cycle - |quickfix| Commands for a quick edit-compile-fix cycle
|ft_ada.txt| Ada filetype plugin - |ft_ada.txt| Ada filetype plugin
|ft_hare.txt| Filetype plugin for Hare - |ft_hare.txt| Filetype plugin for Hare
|ft_ps1.txt| PowerShell filetype plugin - |ft_ps1.txt| PowerShell filetype plugin
|ft_raku.txt| Raku filetype plugin - |ft_raku.txt| Raku filetype plugin
|ft_rust.txt| Rust filetype plugin - |ft_rust.txt| Rust filetype plugin
|ft_sql.txt| SQL filetype plugin - |ft_sql.txt| SQL filetype plugin
------------------------------------------------------------------------------ ------------------------------------------------------------------------------
UI UI
|tui| Builtin UI - |tui| Builtin UI
|gui| External (graphical) UIs - |gui| External (graphical) UIs
|signs| Signs displayed as window decorations (the "gutter") - |signs| Signs displayed as window decorations (the "gutter")
------------------------------------------------------------------------------ ------------------------------------------------------------------------------
LANGUAGE SUPPORT Multilingual support
|digraph| List of available digraphs - |digraph| List of available digraphs
|mbyte.txt| Multibyte text support - |mbyte.txt| Multibyte text support
|mlang.txt| Non-English language support - |mlang.txt| Non-English language support
|rileft.txt| Right-to-left editing mode - |rileft.txt| Right-to-left editing mode
|l10n-arabic.txt| Arabic language support and editing - |l10n-arabic.txt| Arabic language support and editing
|l10n-hebrew.txt| Hebrew language support and editing - |l10n-hebrew.txt| Hebrew language support and editing
|l10n-russian.txt| Russian language support and editing - |l10n-russian.txt| Russian language support and editing
|l10n-vietnamese.txt| Vietnamese language support and editing - |l10n-vietnamese.txt| Vietnamese language support and editing
------------------------------------------------------------------------------ ------------------------------------------------------------------------------
INTEROP Interop
|provider| Builtin remote plugin hosts - |provider| Builtin remote plugin hosts
|if_perl| Perl interface - |if_perl| Perl interface
|if_pyth| Python interface - |if_pyth| Python interface
|if_ruby| Ruby interface - |if_ruby| Ruby interface
------------------------------------------------------------------------------ ------------------------------------------------------------------------------
VERSIONS Versions
|deprecated| Deprecated features that will be removed - |deprecated| Deprecated features that will be removed
|vi-differences| Differences between Vim and Vi - |vi-differences| Differences between Vim and Vi
------------------------------------------------------------------------------ ------------------------------------------------------------------------------
DEVELOPING NVIM Developing nvim
|dev| Development of Nvim - |dev| Development of Nvim
|dev-arch| Internal architecture, modules, data structures - |dev-arch| Internal architecture, modules, data structures
|dev-style| Development style guidelines - |dev-style| Development style guidelines
|dev-theme| Design guidelines (colorschemes etc.) - |dev-test| Writing and running tests
|dev-tools| Tools and techniques for developing Nvim - |dev-theme| Design guidelines (colorschemes etc.)
|dev-vimpatch| Merging patches from Vim - |dev-tools| Tools and techniques for developing Nvim
- |dev-vimpatch| Merging patches from Vim
Standard plugins ~ 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. 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 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 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. try to find help for it. Especially for options in single quotes, e.g.

142
runtime/doc/helphelp.txt
View File

@@ -9,7 +9,143 @@ Help on help files *helphelp*
Type |gO| to see the table of contents. 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* *<Help>* *:h* *:help* *<F1>* *i_<F1>* *i_<Help>*
<Help> or <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 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'. files. Vim will search for all help in "doc" directories in 'runtimepath'.
@@ -311,7 +447,7 @@ Hints for translators:
languages in the specified directory. 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 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 standard Vim help files, except for the first line. If you are writing a new

111
runtime/doc/intro.txt
View File

@@ -122,117 +122,8 @@ memory however you may see fit.
- Say Farewell: https://github.com/vim/vim/discussions/12737 - 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 <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*
These names for keys are used in the documentation. They can also be used These names for keys are used in the documentation. They can also be used
with the ":map" command. with the ":map" command.

1
src/gen/gen_help_html.lua
View File

@@ -69,6 +69,7 @@ local new_layout = {
['dev_theme.txt'] = true, ['dev_theme.txt'] = true,
['dev_tools.txt'] = true, ['dev_tools.txt'] = true,
['dev_vimpatch.txt'] = true, ['dev_vimpatch.txt'] = true,
['help.txt'] = true,
['faq.txt'] = true, ['faq.txt'] = true,
['gui.txt'] = true, ['gui.txt'] = true,
['intro.txt'] = true, ['intro.txt'] = true,

2
test/old/testdir/test_normal.vim
View File

@@ -1941,7 +1941,7 @@ func Test_normal25_tag()
" Testing for CTRL-] g CTRL-] g] " Testing for CTRL-] g CTRL-] g]
" CTRL-W g] CTRL-W CTRL-] CTRL-W g CTRL-] " CTRL-W g] CTRL-W CTRL-] CTRL-W g CTRL-]
h help helphelp
" Test for CTRL-] " Test for CTRL-]
call search('\<x\>$') call search('\<x\>$')
exe "norm! \<c-]>" exe "norm! \<c-]>"

8
test/old/testdir/test_visual.vim
View File

@@ -2610,12 +2610,12 @@ endfunc
func Test_getregion_invalid_buf() func Test_getregion_invalid_buf()
new new
help help index
call cursor(5, 7) call cursor(7, 6)
norm! mA norm! mA
call cursor(5, 18) call cursor(7, 18)
norm! mB 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 " close the help window
q q
call assert_fails("call getregion(getpos(\"'A\"), getpos(\"'B\"))", 'E681:') call assert_fails("call getregion(getpos(\"'A\"), getpos(\"'B\"))", 'E681:')

6
test/old/testdir/test_window_cmd.vim
View File

@@ -599,11 +599,12 @@ func Test_window_jump_tag()
help help
/Kuwasha /Kuwasha
call assert_match('^|Kuwasha|', getline('.')) call assert_match('^- |Kuwasha|', getline('.'))
call assert_equal(2, winnr('$')) call assert_equal(2, winnr('$'))
norm! fK
2wincmd } 2wincmd }
call assert_equal(3, winnr('$')) call assert_equal(3, winnr('$'))
call assert_match('^|Kuwasha|', getline('.')) call assert_match('^- |Kuwasha|', getline('.'))
wincmd k wincmd k
call assert_match('\*Kuwasha\*', getline('.')) call assert_match('\*Kuwasha\*', getline('.'))
call assert_equal(2, winheight(0)) call assert_equal(2, winheight(0))
@@ -612,6 +613,7 @@ func Test_window_jump_tag()
set previewheight=4 set previewheight=4
help help
/bugs /bugs
norm! fb
wincmd } wincmd }
wincmd k wincmd k
call assert_match('\*bugs\*', getline('.')) call assert_match('\*bugs\*', getline('.'))