vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

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: