mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-12-08 23:52:39 +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
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
|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<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.

142
runtime/doc/helphelp.txt
View File

@@ -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

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
==============================================================================
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
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_tools.txt'] = true,
['dev_vimpatch.txt'] = true,
['help.txt'] = true,
['faq.txt'] = true,
['gui.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]
" CTRL-W g] CTRL-W CTRL-] CTRL-W g CTRL-]
h
help helphelp
" Test for CTRL-]
call search('\<x\>$')
exe "norm! \<c-]>"

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

@@ -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:')

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

@@ -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('.'))