codekingpro/portable-devtools

1*helphelp.txt*	For Vim version 9.2.  Last change: 2026 Feb 142 3 4		  VIM REFERENCE MANUAL	  by Bram Moolenaar5 6 7Help on help files					*helphelp*8 91. Help commands		|online-help|102. Translated help files	|help-translated|113. Writing help files		|help-writing|12 13==============================================================================141. Help commands					*online-help*15 16			*help* *<Help>* *:h* *:help* *<F1>* *i_<F1>* *i_<Help>*17<Help>		or18:h[elp]			Open a window and display the help file in read-only19			mode.  If there is a help window open already, use20			that one.  Otherwise, if the current window uses the21			full width of the screen or is at least 80 characters22			wide, the help window will appear just above the23			current window.  Otherwise the new window is put at24			the very top.25			The 'helplang' option is used to select a language, if26			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 options32 33<			{subject} can include wildcards such as "*", "?" and34			"[a-z]":35			   :help z?	jump to help for any "z" command36			   :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 there41			are several matches, the "best" match will be used.42			A sophisticated algorithm is used to decide which43			match is better than another one.  These items are44			considered in the computation:45			- A match with same case is much better than a match46			  with different case.47			- A match that starts after a non-alphanumeric48			  character is better than a match in the middle of a49			  word.50			- A match at or near the beginning of the tag is51			  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, if56			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.  See59			|help-translated|.60 61			Note that the longer the {subject} you give, the less62			matches will be found.  You can get an idea how this63			all works by using commandline completion (type CTRL-D64			after ":help subject" |c_CTRL-D|).65			If there are several matches, you can have them listed66			by hitting CTRL-D.  Example: >67				:help cont<Ctrl-D>68 69<			Instead of typing ":help CTRL-V" to search for help70			for CTRL-V you can type: >71				:help ^V72<			This also works together with other characters, for73			example to find help for CTRL-V in Insert mode: >74				:help i^V75<76			It is also possible to first do ":help" and then77			use ":tag {pattern}" in the help window.  The78			":tnext" command can then be used to jump to other79			matches, "tselect" to list matches and choose one. >80				:help index81				:tselect /.*mode82 83<			When there is no argument you will see matches for84			"help", to avoid listing all possible matches (that85			would be very slow).86			The number of matches displayed is limited to 300.87 88			The `:help` command can be followed by '|' and another89			command, but you don't need to escape the '|' inside a90			help command.  So these both work: >91				:help |92				:help k| only93<			Note that a space before the '|' is seen as part of94			the ":help" argument.95			You can also use <NL> or <CR> to separate the help96			command from a following command.  You need to type97			CTRL-V first to insert the <NL> or <CR>.  Example: >98				:help so<C-V><CR>only99 100:h[elp]! [subject]	Like ":help", but in non-English help files prefer to101			find a tag in a file with the same language as the102			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 (including107			cursor position) to the same layout it was before108			opening the help window initially.  This might cause109			triggering several autocommands.110 111							*:helpg* *:helpgrep*112:helpg[rep] {pattern}[@xx]113			Search all help text files and make a list of lines114			in which {pattern} matches.  Jumps to the first match.115			The optional [@xx] specifies that only matches in the116			"xx" language are to be found.117			You can navigate through the matches with the118			|quickfix| commands, e.g., |:cnext| to jump to the119			next one.  Or use |:cwindow| to get the list of120			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 Uganda125<			Example for case ignoring search: >126				:helpgrep uganda\c127<			Example for searching in French help: >128				:helpgrep backspace@fr129<			The pattern does not support line breaks, it must130			match within one line.  You can use |:grep| instead,131			but then you need to get the list of help files in a132			complicated way.133			Cannot be followed by another command, everything is134			used as part of the pattern.  But you can use135			|:execute| when needed.136			Compressed help files will not be searched (Fedora137			compresses the help files).138 139							*:lh* *:lhelpgrep*140:lh[elpgrep] {pattern}[@xx]141			Same as ":helpgrep", except the location list is used142			instead of the quickfix list.  If the help window is143			already opened, then the location list for that window144			is used.  Otherwise, a new help window is opened and145			the location list for that window is set.  The146			location list for the current window is not changed147			then.148 149							*:exu* *:exusage*150:exu[sage]		Show help on Ex commands.  Added to simulate the Nvi151			command.152 153							*:viu* *:viusage*154:viu[sage]		Show help on Normal mode commands.  Added to simulate155			the Nvi command.156 157When no argument is given to |:help| the file given with the 'helpfile' option158will be opened.  Otherwise the specified tag is searched for in all "doc/tags"159files in the directories specified in the 'runtimepath' option.160 161The initial height of the help window can be set with the 'helpheight' option162(default 20).163 164If you want to open help on {subject} in the current window, the helpcurwin165optional package can be used.  See |package-helpcurwin|.166 167						*help-buffer-options*168When the help buffer is created, several local options are set to make sure169the help text is displayed as it was intended:170    'iskeyword'		nearly all ASCII chars except ' ', '*', '"' and '|'171    'foldmethod'	"manual"172    'tabstop'		8173    'arabic'		off174    'binary'		off175    'buflisted'		off176    'cursorbind'	off177    'diff'		off178    'foldenable'	off179    'list'		off180    'modifiable'	off181    'number'		off182    'relativenumber'	off183    'rightleft'		off184    'scrollbind'	off185    'spell'		off186 187Jump 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>" and190  "g<LeftMouse>" work just like "CTRL-]".191- use the ":ta {subject}" command.  This also works with non-keyword192  characters.193 194Use CTRL-T or CTRL-O to jump back.195Use ":q" to close the help window.196 197If there are several matches for an item you are looking for, this is how you198can jump to each one of them:1991. Open a help window2002. Use the ":tag" command with a slash prepended to the tag.  E.g.: >201	:tag /min2023. Use ":tnext" to jump to the next matching tag.203 204It is possible to add help files for plugins and other items.  You don't need205to change the distributed help files for that.  See |add-local-help|.206 207To write a local help file, see |write-local-help|.208 209Note that the title lines from the local help files are automagically added to210the "LOCAL ADDITIONS" section in the "help.txt" help file |local-additions|.211This is done when viewing the file in Vim, the file itself is not changed.  It212is done by going through all help files and obtaining the first line of each213file.  The files in $VIMRUNTIME/doc are skipped.214 215							*help-xterm-window*216If you want to have the help in another xterm window, you could use this217command: >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 the224			ToolBar.FindHelp menu entry instead of using a builtin225			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 in232			'runtimepath' will be used.233 234			All "*.txt" and "*.??x" files in the directory and235			sub-directories are scanned for a help tag definition236			in between stars.  The "*.??x" files are for237			translated docs, they generate the "tags-??" file, see238			|help-translated|.  The generated tags files are239			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 the244			"help-tags" tag.  This is also done when the {dir} is245			equal to $VIMRUNTIME/doc.246 247			To rebuild the help tags in the runtime directory248			(requires write permission there): >249				:helptags $VIMRUNTIME/doc250<251		*:HelpToc* *help-TOC* *help-toc-install* *package-helptoc*252 253If you want to access an interactive table of contents, from any position in254the file, you can use the helptoc plugin.  Load the plugin with: >vim255 256    packadd helptoc257<258					*HelpToc-mappings*259Then you can use the `:HelpToc` command to open a popup menu.260The latter supports the following normal commands: >261 262	key | effect263	----+---------------------------------------------------------264	c   | select nearest entry from cursor position in main buffer265	g   | select first entry266	G   | select last entry267	H   | collapse one level268	j   | select next entry269	J   | same as j, and jump to corresponding line in main buffer270	k   | select previous entry271	K   | same as k, and jump to corresponding line in main buffer272	L   | expand one level273	p   | print current entry on command-line274 275	P   | same as p but automatically, whenever selection changes276	    | press multiple times to toggle feature on/off277 278	q   | quit menu279	s   | split window, and jump to selected entry280	z   | redraw menu with current entry at center281	+   | increase width of popup menu282	-   | decrease width of popup menu283	?   | show/hide a help window284	/   | search for pattern285 286	<C-D>      | scroll down half a page287	<C-U>      | scroll up half a page288	<PageUp>   | scroll down a whole page289	<PageDown> | scroll up a whole page290	<Home>     | select first entry291	<End>      | select last entry292 293The plugin can also provide a table of contents in buffers of the following294filetypes: asciidoc, html, man, markdown, tex, vim, and xhtml.  In addition295it also provide a table of contents for a terminal buffer, which produces296entries that are the past executed shell commands.  To find those, by default,297the following pattern is used: >298 299	^\w\+@\w\+:\f\+\$\s300 301This is meant to match a default bash prompt.  If it doesn't match your302prompt, you can change the regex with the `shell_prompt` key from the303`g:helptoc` dictionary variable: >304 305	let g:helptoc = {'shell_prompt': 'regex matching your shell prompt'}306 307Tip: After inserting a pattern to look for with the `/` command, if you press308<Esc> instead of <CR>, you can then get more context for each remaining entry309by pressing `J` or `K`.310 311Refer to |helptoc.txt| for more details about helptoc, particularly about312using it with filetypes other than help, and configuring its options.313Note:  You need to `packadd helptoc` before you can jump to |helptoc.txt|.314 315==============================================================================3162. Translated help files				*help-translated*317 318It is possible to add translated help files, next to the original English help319files.  Vim will search for all help in "doc" directories in 'runtimepath'.320This is only available when compiled with the |+multi_lang| feature.321 322At this moment translations are available for:323	Chinese  - multiple authors324	French   - translated by David Blanchet325	Italian  - translated by Antonio Colombo326	Japanese - multiple authors327	Polish   - translated by Mikolaj Machowski328	Russian  - translated by Vassily Ragosin329	Swedish  - translated by Daniel Nylander330See the Vim website to find them: http://www.vim.org/translations.php331 332A set of translated help files consists of these files:333 334	help.abx335	howto.abx336	...337	tags-ab338 339"ab" is the two-letter language code.  Thus for Italian the names are:340 341	help.itx342	howto.itx343	...344	tags-it345 346The 'helplang' option can be set to the preferred language(s).  The default is347set according to the environment.  Vim will first try to find a matching tag348in the preferred language(s).  English is used when it cannot be found.349 350To find a tag in a specific language, append "@ab" to a tag, where "ab" is the351two-letter language code.  Example: >352	:he user-manual@it353	:he user-manual@en354The first one finds the Italian user manual, even when 'helplang' is empty.355The second one finds the English user manual, even when 'helplang' is set to356"it".357 358When using command-line completion for the ":help" command, the "@en"359extension is only shown when a tag exists for multiple languages.  When the360tag only exists for English "@en" is omitted.  When the first candidate has an361"@ab" extension and it matches the first language in 'helplang' "@ab" is also362omitted.363 364When using |CTRL-]| or ":help!" in a non-English help file Vim will try to365find the tag in the same language.  If not found then 'helplang' will be used366to select a language.367 368Help files must use latin1 or utf-8 encoding.  Vim assumes the encoding is369utf-8 when finding non-ASCII characters in the first line.  Thus you must370translate the header with "For Vim version".371 372The same encoding must be used for the help files of one language in one373directory.  You can use a different encoding for different languages and use374a different encoding for help files of the same language but in a different375directory.376 377Hints for translators:378- Do not translate the tags.  This makes it possible to use 'helplang' to379  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 all386  languages in the specified directory.387 388==============================================================================3893. Writing help files					*help-writing*390 391For ease of use, a Vim help file for a plugin should follow the format of the392standard Vim help files, except for the first line.  If you are writing a new393help file it's best to copy one of the existing files and use it as a394template.395 396Vim help files generally use 2 spaces after a sentence (since they are written397using a fixed-width font and that was the preferred style in the 70s/80s),398like what is described here: https://english.stackexchange.com/a/2602399 400The first line in a help file should have the following format:401 402*plugin_name.txt*	{short description of the plugin}403 404The first field is a help tag where ":help plugin_name" will jump to.  The405remainder of the line, after a Tab, describes the plugin purpose in a short406way.  This will show up in the "LOCAL ADDITIONS" section of the main help407file.  Check there that it shows up properly: |local-additions|.408 409If you want to add a version number or last modification date, put it in the410second line, right aligned.411 412At the bottom of the help file, place a Vim modeline to set the 'textwidth'413and 'tabstop' options and the 'filetype' to "help".  Never set a global option414in such a modeline, that can have undesired consequences.415 416 417STYLE418 419If your Vim has 'modeline' enabled, Vim should follow the preferred style420automatically when editing built-in help files.421 422Vim help files should be formatted for a 'textwidth' of 78 characters (with423'conceal' enabled), so they look good in a typical 80 x 24 terminal window;424use `:set colorcolumn=+0` as a visual guide.425 426Use two spaces between the final dot of a sentence of the first letter of the427next sentence.  Like this.428 429Use tab characters for aligning content, with a 'tabstop' setting of 8.430This also helps reduce the file size.431 432Always use |:retab| after you have finished editing.  Don't blindly use433|:retab!|, always review what will be changed to avoid unwanted changes.434 435 436TAGS437 438To define a help tag, place the name between asterisks ("*tag-name*").  The439tag-name should be different from all the Vim help tag names and ideally440should begin with the name of the Vim plugin.  The tag name is usually right441aligned on a line.442 443When referring to an existing help tag and to create a hot-link, place the444name between two bars (|) eg. |help-writing|.445 446When referring to a Vim command and to create a hot-link, place the447name between two backticks, eg. inside `:filetype`.  You will see this is448highlighted as a command, like a code block (see below).449 450When referring to a Vim option in the help file, place the option name between451two single quotes, eg. 'statusline'452 453 454HIGHLIGHTING455 456To define a column heading, use a tilde character at the end of the line.457This will highlight the column heading in a different color.  E.g.458 459Column heading~460 461To separate sections in a help file, place a series of '=' characters in a462line starting from the first column.  The section separator line is463highlighted differently.464 465To quote a block of ex-commands verbatim, place a greater than (>) character466at the end of the line before the block and a less than (<) character as the467first non-blank on a line following the block.  Any line starting in column 1468also implicitly stops the block of ex-commands before it.  E.g. >469 470	function Example_Func()471	  echo "Example"472	endfunction473<474To enable syntax highlighting for a block of code, place a language name475annotation (e.g. "vim") after a greater than (>) character.  E.g. >vim476 477	function Example_Func()478	  echo "Example"479	endfunction480<481						*g:help_example_languages*482By default, help files only support Vim script highlighting.  If you need483syntax highlighting for other languages, add to your |vimrc|: >484	:let g:help_example_languages = #{485	      \	vim: "vim", vim9: "vim", bash: "sh" }486The key represents the annotation marker name, and the value is the 'syntax'487name.488 489Note: If you do not include "vim" in "g:help_example_languages", its syntax490highlighting will not be enabled.  If you set "g:help_example_languages" to an491empty value, syntax highlighting for embedded languages will be disabled.492 493Further note: Including arbitrary syntax languages into help files may not494always work perfectly, if the included 'syntax' script does not account for495such an import.496						*help-notation*497The following are highlighted differently in a Vim help file:498  - a special key name expressed either in <> notation as in <PageDown>, or499    as a Ctrl character as in CTRL-X500  - anything between {braces}, e.g. {lhs} and {rhs}501 502The word "Note", "Notes" and similar automagically receive distinctive503highlighting.  So do these:504	*Todo	something to do505	*Error	something wrong506 507You can find the details in $VIMRUNTIME/syntax/help.vim508 509 510FILETYPE COMPLETION					*ft-help-omni*511 512To get completion for help tags when writing a tag reference, you can use the513|i_CTRL-X_CTRL-O| command.514 515 516GENDER NEUTRAL LANGUAGE517						*gender-neutral* *inclusion*518Vim is for everybody, no matter race, gender or anything.  For new or updated519help text, gender neutral language is recommended.  Some of the help text is520many years old and there is no need to change it.  We do not make any521assumptions about the gender of the user, no matter how the text is phrased.522The goal is that the reader understands how Vim works, the exact wording is523secondary.524 525Many online technical style guides include sections about gender neutral526language.  Here are a few: >527 528	https://developers.google.com/style/pronouns529	https://techwhirl.com/gender-neutral-technical-writing/530	https://www.skillsyouneed.com/write/gender-neutral-language.html531	https://ualr.edu/writingcenter/avoid-sexist-language/532<533Note: gender neutral language does not require using singular "they".534 535 vim:tw=78:ts=8:noet:ft=help:norl:536