helphelp.txt (20612B)
1 *helphelp.txt* For Vim version 9.2. Last change: 2026 Aug 25 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7 Help on help files *helphelp* 8 9 1. Help commands |online-help| 10 2. Translated help files |help-translated| 11 3. Writing help files |help-writing| 12 13 ============================================================================== 14 1. Help commands *online-help* 15 16 *help* *<Help>* *:h* *:help* *<F1>* *i_<F1>* *i_<Help>* 17 <Help> or 18 :h[elp] Open a window and display the help file in read-only 19 mode. If there is a help window open already, use 20 that one. Otherwise, if the current window uses the 21 full width of the screen or is at least 80 characters 22 wide, the help window will appear just above the 23 current window. Otherwise the new window is put at 24 the very top. 25 The 'helplang' option is used to select a language, if 26 the main help file is available in several languages. 27 28 *{subject}* *E149* *E661* 29 :h[elp] {subject} Like ":help", additionally jump to the tag {subject}. 30 For example: > 31 :help options 32 33 < {subject} can include wildcards such as "*", "?" and 34 "[a-z]": 35 :help z? jump to help for any "z" command 36 :help z. jump to the help for "z." 37 But when a tag exists it is taken literally: 38 :help :? jump to help for ":?" 39 40 If there is no full match for the pattern, or there 41 are several matches, the "best" match will be used. 42 A sophisticated algorithm is used to decide which 43 match is better than another one. These items are 44 considered in the computation: 45 - A match with same case is much better than a match 46 with different case. 47 - A match that starts after a non-alphanumeric 48 character is better than a match in the middle of a 49 word. 50 - A match at or near the beginning of the tag is 51 better than a match further on. 52 - The more alphanumeric characters match, the better. 53 - The shorter the length of the match, the better. 54 55 The 'helplang' option is used to select a language, if 56 the {subject} is available in several languages. 57 To find a tag in a specific language, append "@ab", 58 where "ab" is the two-letter language code. See 59 |help-translated|. 60 61 Note that the longer the {subject} you give, the less 62 matches will be found. You can get an idea how this 63 all works by using commandline completion (type CTRL-D 64 after ":help subject" |c_CTRL-D|). 65 If there are several matches, you can have them listed 66 by hitting CTRL-D. Example: > 67 :help cont<Ctrl-D> 68 69 < Instead of typing ":help CTRL-V" to search for help 70 for CTRL-V you can type: > 71 :help ^V 72 < This also works together with other characters, for 73 example to find help for CTRL-V in Insert mode: > 74 :help i^V 75 < 76 It is also possible to first do ":help" and then 77 use ":tag {pattern}" in the help window. The 78 ":tnext" command can then be used to jump to other 79 matches, "tselect" to list matches and choose one. > 80 :help index 81 :tselect /.*mode 82 83 < When there is no argument you will see matches for 84 "help", to avoid listing all possible matches (that 85 would be very slow). 86 The number of matches displayed is limited to 300. 87 88 The `:help` command can be followed by '|' and another 89 command, but you don't need to escape the '|' inside a 90 help command. So these both work: > 91 :help | 92 :help k| only 93 < Note that a space before the '|' is seen as part of 94 the ":help" argument. 95 You can also use <NL> or <CR> to separate the help 96 command from a following command. You need to type 97 CTRL-V first to insert the <NL> or <CR>. Example: > 98 :help so<C-V><CR>only 99 100 :h[elp]! [subject] Like ":help", but in non-English help files prefer to 101 find a tag in a file with the same language as the 102 current file. See |help-translated|. 103 104 *:helpc* *:helpclose* 105 :helpc[lose] Close one help window, if there is one. 106 Vim will try to restore the window layout (including 107 cursor position) to the same layout it was before 108 opening the help window initially. This might cause 109 triggering several autocommands. 110 111 *:helpg* *:helpgrep* 112 :helpg[rep] {pattern}[@xx] 113 Search all help text files and make a list of lines 114 in which {pattern} matches. Jumps to the first match. 115 The optional [@xx] specifies that only matches in the 116 "xx" language are to be found. 117 You can navigate through the matches with the 118 |quickfix| commands, e.g., |:cnext| to jump to the 119 next one. Or use |:cwindow| to get the list of 120 matches in the quickfix window. 121 {pattern} is used as a Vim regexp |pattern|. 122 'ignorecase' is not used, add "\c" to ignore case. 123 Example for case sensitive search: > 124 :helpgrep Uganda 125 < Example for case ignoring search: > 126 :helpgrep uganda\c 127 < Example for searching in French help: > 128 :helpgrep backspace@fr 129 < The pattern does not support line breaks, it must 130 match within one line. You can use |:grep| instead, 131 but then you need to get the list of help files in a 132 complicated way. 133 Cannot be followed by another command, everything is 134 used as part of the pattern. But you can use 135 |:execute| when needed. 136 Compressed help files will not be searched (Fedora 137 compresses the help files). 138 139 *:lh* *:lhelpgrep* 140 :lh[elpgrep] {pattern}[@xx] 141 Same as ":helpgrep", except the location list is used 142 instead of the quickfix list. If the help window is 143 already opened, then the location list for that window 144 is used. Otherwise, a new help window is opened and 145 the location list for that window is set. The 146 location list for the current window is not changed 147 then. 148 149 *:exu* *:exusage* 150 :exu[sage] Show help on Ex commands. Added to simulate the Nvi 151 command. 152 153 *:viu* *:viusage* 154 :viu[sage] Show help on Normal mode commands. Added to simulate 155 the Nvi command. 156 157 When no argument is given to |:help| the file given with the 'helpfile' option 158 will be opened. Otherwise the specified tag is searched for in all "doc/tags" 159 files in the directories specified in the 'runtimepath' option. 160 161 The initial height of the help window can be set with the 'helpheight' option 162 (default 20). 163 164 If you want to open help on {subject} in the current window, the helpcurwin 165 optional package can be used. See |package-helpcurwin|. 166 167 *help-buffer-options* 168 When the help buffer is created, several local options are set to make sure 169 the help text is displayed as it was intended: 170 'iskeyword' nearly all ASCII chars except ' ', '*', '"' and '|' 171 'foldmethod' "manual" 172 'tabstop' 8 173 'arabic' off 174 'binary' off 175 'buflisted' off 176 'cursorbind' off 177 'diff' off 178 'foldenable' off 179 'list' off 180 'modifiable' off 181 'number' off 182 'relativenumber' off 183 'rightleft' off 184 'scrollbind' off 185 'spell' off 186 187 Jump to specific subjects by using tags. This can be done in two ways: 188 - Use the "CTRL-]" command while standing on the name of a command or option. 189 This only works when the tag is a keyword. "<C-Leftmouse>" and 190 "g<LeftMouse>" work just like "CTRL-]". 191 - use the ":ta {subject}" command. This also works with non-keyword 192 characters. 193 194 Use CTRL-T or CTRL-O to jump back. 195 Use ":q" to close the help window. 196 197 If there are several matches for an item you are looking for, this is how you 198 can jump to each one of them: 199 1. Open a help window 200 2. Use the ":tag" command with a slash prepended to the tag. E.g.: > 201 :tag /min 202 3. Use ":tnext" to jump to the next matching tag. 203 204 It is possible to add help files for plugins and other items. You don't need 205 to change the distributed help files for that. See |add-local-help|. 206 207 To write a local help file, see |write-local-help|. 208 209 Note that the title lines from the local help files are automagically added to 210 the "LOCAL ADDITIONS" section in the "help.txt" help file |local-additions|. 211 This is done when viewing the file in Vim, the file itself is not changed. It 212 is done by going through all help files and obtaining the first line of each 213 file. The files in $VIMRUNTIME/doc are skipped. 214 215 *help-xterm-window* 216 If you want to have the help in another xterm window, you could use this 217 command: > 218 :!xterm -e vim +help & 219 < 220 221 *:helpfind* *:helpf* 222 :helpf[ind] Like |:help|, but use a dialog to enter the argument. 223 Only for backwards compatibility. It now executes the 224 ToolBar.FindHelp menu entry instead of using a builtin 225 dialog. {only when compiled with |+GUI_GTK|} 226 227 *:helpt* *:helptags* 228 *E150* *E151* *E152* *E153* *E154* *E670* 229 :helpt[ags] [++t] {dir} 230 Generate the help tags file(s) for directory {dir}. 231 When {dir} is ALL then all "doc" directories in 232 'runtimepath' will be used. 233 234 All "*.txt" and "*.??x" files in the directory and 235 sub-directories are scanned for a help tag definition 236 in between stars. The "*.??x" files are for 237 translated docs, they generate the "tags-??" file, see 238 |help-translated|. The generated tags files are 239 sorted. 240 When there are duplicates an error message is given. 241 An existing tags file is silently overwritten. 242 243 The optional "++t" argument forces adding the 244 "help-tags" tag. This is also done when the {dir} is 245 equal to $VIMRUNTIME/doc. 246 247 To rebuild the help tags in the runtime directory 248 (requires write permission there): > 249 :helptags $VIMRUNTIME/doc 250 < 251 *:HelpToc* *help-TOC* *help-toc-install* *package-helptoc* 252 253 If you want to access an interactive table of contents, from any position in 254 the file, you can use the helptoc plugin. Load the plugin with: >vim 255 256 packadd helptoc 257 < 258 *HelpToc-mappings* 259 Then you can use the `:HelpToc` command to open a popup menu. 260 The latter supports the following normal commands: > 261 262 key | effect 263 ----+--------------------------------------------------------- 264 c | select nearest entry from cursor position in main buffer 265 g | select first entry 266 G | select last entry 267 H | collapse one level 268 j | select next entry 269 J | same as j, and jump to corresponding line in main buffer 270 k | select previous entry 271 K | same as k, and jump to corresponding line in main buffer 272 L | expand one level 273 p | print current entry on command-line 274 275 P | same as p but automatically, whenever selection changes 276 | press multiple times to toggle feature on/off 277 278 q | quit menu 279 s | split window, and jump to selected entry 280 z | redraw menu with current entry at center 281 + | increase width of popup menu 282 - | decrease width of popup menu 283 ? | show/hide a help window 284 / | search for pattern 285 286 <C-D> | scroll down half a page 287 <C-U> | scroll up half a page 288 <PageUp> | scroll down a whole page 289 <PageDown> | scroll up a whole page 290 <Home> | select first entry 291 <End> | select last entry 292 293 The plugin can also provide a table of contents in buffers of the following 294 filetypes: asciidoc, html, man, markdown, tex, vim, and xhtml. In addition 295 it also provide a table of contents for a terminal buffer, which produces 296 entries that are the past executed shell commands. To find those, by default, 297 the following pattern is used: > 298 299 ^\w\+@\w\+:\f\+\$\s 300 301 This is meant to match a default bash prompt. If it doesn't match your 302 prompt, you can change the regexp with the `shell_prompt` key from the 303 `g:helptoc` dictionary variable: > 304 305 let g:helptoc = {'shell_prompt': 'regexp matching your shell prompt'} 306 307 Tip: After inserting a pattern to look for with the `/` command, if you press 308 <Esc> instead of <CR>, you can then get more context for each remaining entry 309 by pressing `J` or `K`. 310 311 Refer to |helptoc.txt| for more details about helptoc, particularly about 312 using it with filetypes other than help, and configuring its options. 313 Note: You need to `packadd helptoc` before you can jump to |helptoc.txt|. 314 315 ============================================================================== 316 2. Translated help files *help-translated* 317 318 It is possible to add translated help files, next to the original English help 319 files. Vim will search for all help in "doc" directories in 'runtimepath'. 320 This is only available when compiled with the |+multi_lang| feature. 321 322 At this moment translations are available for: 323 Chinese - multiple authors 324 French - translated by David Blanchet 325 Italian - translated by Antonio Colombo 326 Japanese - multiple authors 327 Polish - translated by Mikolaj Machowski 328 Russian - translated by Vassily Ragosin 329 Swedish - translated by Daniel Nylander 330 See the Vim website to find them: http://www.vim.org/translations.php 331 332 A set of translated help files consists of these files: 333 334 help.abx 335 howto.abx 336 ... 337 tags-ab 338 339 "ab" is the two-letter language code. Thus for Italian the names are: 340 341 help.itx 342 howto.itx 343 ... 344 tags-it 345 346 The 'helplang' option can be set to the preferred language(s). The default is 347 set according to the environment. Vim will first try to find a matching tag 348 in the preferred language(s). English is used when it cannot be found. 349 350 To find a tag in a specific language, append "@ab" to a tag, where "ab" is the 351 two-letter language code. Example: > 352 :he user-manual@it 353 :he user-manual@en 354 The first one finds the Italian user manual, even when 'helplang' is empty. 355 The second one finds the English user manual, even when 'helplang' is set to 356 "it". 357 358 When using command-line completion for the ":help" command, the "@en" 359 extension is only shown when a tag exists for multiple languages. When the 360 tag only exists for English "@en" is omitted. When the first candidate has an 361 "@ab" extension and it matches the first language in 'helplang' "@ab" is also 362 omitted. 363 364 When using |CTRL-]| or ":help!" in a non-English help file Vim will try to 365 find the tag in the same language. If not found then 'helplang' will be used 366 to select a language. 367 368 Help files must use latin1 or utf-8 encoding. Vim assumes the encoding is 369 utf-8 when finding non-ASCII characters in the first line. Thus you must 370 translate the header with "For Vim version". 371 372 The same encoding must be used for the help files of one language in one 373 directory. You can use a different encoding for different languages and use 374 a different encoding for help files of the same language but in a different 375 directory. 376 377 Hints for translators: 378 - Do not translate the tags. This makes it possible to use 'helplang' to 379 specify the preferred language. You may add new tags in your language. 380 - When you do not translate a part of a file, add tags to the English version, 381 using the "tag@en" notation. 382 - Make a package with all the files and the tags file available for download. 383 Users can drop it in one of the "doc" directories and start use it. 384 Report to the development team, so they can add a link on www.vim.org. 385 - Use the |:helptags| command to generate the tags files. It will find all 386 languages in the specified directory. 387 388 ============================================================================== 389 3. Writing help files *help-writing* 390 391 For ease of use, a Vim help file for a plugin should follow the format of the 392 standard Vim help files, except for the first line. If you are writing a new 393 help file it's best to copy one of the existing files and use it as a 394 template. 395 396 Vim help files generally use 2 spaces after a sentence (since they are written 397 using a fixed-width font and that was the preferred style in the 70s/80s), 398 like what is described here: https://english.stackexchange.com/a/2602 399 400 The first line in a help file should have the following format: 401 402 *plugin_name.txt* {short description of the plugin} 403 404 The first field is a help tag where ":help plugin_name" will jump to. The 405 remainder of the line, after a Tab, describes the plugin purpose in a short 406 way. This will show up in the "LOCAL ADDITIONS" section of the main help 407 file. Check there that it shows up properly: |local-additions|. 408 409 If you want to add a version number or last modification date, put it in the 410 second line, right aligned. 411 412 At the bottom of the help file, place a Vim modeline to set the 'textwidth' 413 and 'tabstop' options and the 'filetype' to "help". Never set a global option 414 in such a modeline, that can have undesired consequences. 415 416 417 STYLE 418 419 If your Vim has 'modeline' enabled, Vim should follow the preferred style 420 automatically when editing built-in help files. 421 422 Vim help files should be formatted for a 'textwidth' of 78 characters (with 423 'conceal' enabled), so they look good in a typical 80 x 24 terminal window; 424 use `:set colorcolumn=+0` as a visual guide. 425 426 Use two spaces between the final dot of a sentence of the first letter of the 427 next sentence. Like this. 428 429 Use tab characters for aligning content, with a 'tabstop' setting of 8. 430 This also helps reduce the file size. 431 432 Always use |:retab| after you have finished editing. Don't blindly use 433 |:retab!|, always review what will be changed to avoid unwanted changes. 434 435 436 TAGS 437 438 To define a help tag, place the name between asterisks ("*tag-name*"). The 439 tag-name should be different from all the Vim help tag names and ideally 440 should begin with the name of the Vim plugin. The tag name is usually right 441 aligned on a line. 442 443 When referring to an existing help tag and to create a hot-link, place the 444 name between two bars (|) eg. |help-writing|. 445 446 When referring to a Vim command and to create a hot-link, place the 447 name between two backticks, eg. inside `:filetype`. You will see this is 448 highlighted as a command, like a code block (see below). 449 450 When referring to a Vim option in the help file, place the option name between 451 two single quotes, eg. 'statusline' 452 453 454 HIGHLIGHTING 455 456 To define a column heading, use a tilde character at the end of the line. 457 This will highlight the column heading in a different color. E.g. 458 459 Column heading~ 460 461 To separate sections in a help file, place a series of '=' characters in a 462 line starting from the first column. The section separator line is 463 highlighted differently. 464 465 To quote a block of ex-commands verbatim, place a greater than (>) character 466 at the end of the line before the block and a less than (<) character as the 467 first non-blank on a line following the block. Any line starting in column 1 468 also implicitly stops the block of ex-commands before it. E.g. > 469 470 function Example_Func() 471 echo "Example" 472 endfunction 473 < 474 To enable syntax highlighting for a block of code, place a language name 475 annotation (e.g. "vim") after a greater than (>) character. E.g. >vim 476 477 function Example_Func() 478 echo "Example" 479 endfunction 480 < 481 *g:help_example_languages* 482 By default, help files only support Vim script highlighting. If you need 483 syntax highlighting for other languages, add to your |vimrc|: > 484 :let g:help_example_languages = #{ 485 \ vim: "vim", vim9: "vim", bash: "sh" } 486 The key represents the annotation marker name, and the value is the 'syntax' 487 name. 488 489 Note: If you do not include "vim" in "g:help_example_languages", its syntax 490 highlighting will not be enabled. If you set "g:help_example_languages" to an 491 empty value, syntax highlighting for embedded languages will be disabled. 492 493 Further note: Including arbitrary syntax languages into help files may not 494 always work perfectly, if the included 'syntax' script does not account for 495 such an import. 496 *help-notation* 497 The following are highlighted differently in a Vim help file: 498 - a special key name expressed either in <> notation as in <PageDown>, or 499 as a Ctrl character as in CTRL-X 500 - anything between {braces}, e.g. {lhs} and {rhs} 501 502 The word "Note", "Notes" and similar automagically receive distinctive 503 highlighting. So do these: 504 *Todo something to do 505 *Error something wrong 506 507 You can find the details in $VIMRUNTIME/syntax/help.vim 508 509 510 FILETYPE COMPLETION *ft-help-omni* 511 512 To get completion for help tags when writing a tag reference, you can use the 513 |i_CTRL-X_CTRL-O| command. 514 515 516 GENDER NEUTRAL LANGUAGE 517 *gender-neutral* *inclusion* 518 Vim is for everybody, no matter race, gender or anything. For new or updated 519 help text, gender neutral language is recommended. Some of the help text is 520 many years old and there is no need to change it. We do not make any 521 assumptions about the gender of the user, no matter how the text is phrased. 522 The goal is that the reader understands how Vim works, the exact wording is 523 secondary. 524 525 Many online technical style guides include sections about gender neutral 526 language. Here are a few: > 527 528 https://developers.google.com/style/pronouns 529 https://techwhirl.com/gender-neutral-technical-writing/ 530 https://www.skillsyouneed.com/write/gender-neutral-language.html 531 https://ualr.edu/writingcenter/avoid-sexist-language/ 532 < 533 Note: gender neutral language does not require using singular "they". 534 535 vim:tw=78:ts=8:noet:ft=help:norl: