1*helphelp.txt* For Vim version 8.2. Last change: 2021 Nov 13 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 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> 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 157When no argument is given to |:help| the file given with the 'helpfile' option 158will be opened. Otherwise the specified tag is searched for in all "doc/tags" 159files in the directories specified in the 'runtimepath' option. 160 161If you would like to open the help in the current window, see this tip: 162|help-curwin|. 163 164The initial height of the help window can be set with the 'helpheight' option 165(default 20). 166 167When the help buffer is created, several local options are set to make sure 168the help text is displayed as it was intended: 169 'iskeyword' nearly all ASCII chars except ' ', '*', '"' and '|' 170 'foldmethod' "manual" 171 'tabstop' 8 172 'arabic' off 173 'binary' off 174 'buflisted' off 175 'cursorbind' off 176 'diff' off 177 'foldenable' off 178 'list' off 179 'modifiable' off 180 'number' off 181 'relativenumber' off 182 'rightleft' off 183 'scrollbind' off 184 'spell' off 185 186Jump to specific subjects by using tags. This can be done in two ways: 187- Use the "CTRL-]" command while standing on the name of a command or option. 188 This only works when the tag is a keyword. "<C-Leftmouse>" and 189 "g<LeftMouse>" work just like "CTRL-]". 190- use the ":ta {subject}" command. This also works with non-keyword 191 characters. 192 193Use CTRL-T or CTRL-O to jump back. 194Use ":q" to close the help window. 195 196If there are several matches for an item you are looking for, this is how you 197can jump to each one of them: 1981. Open a help window 1992. Use the ":tag" command with a slash prepended to the tag. E.g.: > 200 :tag /min 2013. Use ":tnext" to jump to the next matching tag. 202 203It is possible to add help files for plugins and other items. You don't need 204to change the distributed help files for that. See |add-local-help|. 205 206To write a local help file, see |write-local-help|. 207 208Note that the title lines from the local help files are automagically added to 209the "LOCAL ADDITIONS" section in the "help.txt" help file |local-additions|. 210This is done when viewing the file in Vim, the file itself is not changed. It 211is done by going through all help files and obtaining the first line of each 212file. The files in $VIMRUNTIME/doc are skipped. 213 214 *help-xterm-window* 215If you want to have the help in another xterm window, you could use this 216command: > 217 :!xterm -e vim +help & 218< 219 220 *:helpfind* *:helpf* 221:helpf[ind] Like |:help|, but use a dialog to enter the argument. 222 Only for backwards compatibility. It now executes the 223 ToolBar.FindHelp menu entry instead of using a builtin 224 dialog. {only when compiled with |+GUI_GTK|} 225 226 *:helpt* *:helptags* 227 *E154* *E150* *E151* *E152* *E153* *E670* 228:helpt[ags] [++t] {dir} 229 Generate the help tags file(s) for directory {dir}. 230 When {dir} is ALL then all "doc" directories in 231 'runtimepath' will be used. 232 233 All "*.txt" and "*.??x" files in the directory and 234 sub-directories are scanned for a help tag definition 235 in between stars. The "*.??x" files are for 236 translated docs, they generate the "tags-??" file, see 237 |help-translated|. The generated tags files are 238 sorted. 239 When there are duplicates an error message is given. 240 An existing tags file is silently overwritten. 241 242 The optional "++t" argument forces adding the 243 "help-tags" tag. This is also done when the {dir} is 244 equal to $VIMRUNTIME/doc. 245 246 To rebuild the help tags in the runtime directory 247 (requires write permission there): > 248 :helptags $VIMRUNTIME/doc 249 250============================================================================== 2512. Translated help files *help-translated* 252 253It is possible to add translated help files, next to the original English help 254files. Vim will search for all help in "doc" directories in 'runtimepath'. 255This is only available when compiled with the |+multi_lang| feature. 256 257At this moment translations are available for: 258 Chinese - multiple authors 259 French - translated by David Blanchet 260 Italian - translated by Antonio Colombo 261 Japanese - multiple authors 262 Polish - translated by Mikolaj Machowski 263 Russian - translated by Vassily Ragosin 264See the Vim website to find them: http://www.vim.org/translations.php 265 266A set of translated help files consists of these files: 267 268 help.abx 269 howto.abx 270 ... 271 tags-ab 272 273"ab" is the two-letter language code. Thus for Italian the names are: 274 275 help.itx 276 howto.itx 277 ... 278 tags-it 279 280The 'helplang' option can be set to the preferred language(s). The default is 281set according to the environment. Vim will first try to find a matching tag 282in the preferred language(s). English is used when it cannot be found. 283 284To find a tag in a specific language, append "@ab" to a tag, where "ab" is the 285two-letter language code. Example: > 286 :he user-manual@it 287 :he user-manual@en 288The first one finds the Italian user manual, even when 'helplang' is empty. 289The second one finds the English user manual, even when 'helplang' is set to 290"it". 291 292When using command-line completion for the ":help" command, the "@en" 293extension is only shown when a tag exists for multiple languages. When the 294tag only exists for English "@en" is omitted. When the first candidate has an 295"@ab" extension and it matches the first language in 'helplang' "@ab" is also 296omitted. 297 298When using |CTRL-]| or ":help!" in a non-English help file Vim will try to 299find the tag in the same language. If not found then 'helplang' will be used 300to select a language. 301 302Help files must use latin1 or utf-8 encoding. Vim assumes the encoding is 303utf-8 when finding non-ASCII characters in the first line. Thus you must 304translate the header with "For Vim version". 305 306The same encoding must be used for the help files of one language in one 307directory. You can use a different encoding for different languages and use 308a different encoding for help files of the same language but in a different 309directory. 310 311Hints for translators: 312- Do not translate the tags. This makes it possible to use 'helplang' to 313 specify the preferred language. You may add new tags in your language. 314- When you do not translate a part of a file, add tags to the English version, 315 using the "tag@en" notation. 316- Make a package with all the files and the tags file available for download. 317 Users can drop it in one of the "doc" directories and start use it. 318 Report this to Bram, so that he can add a link on www.vim.org. 319- Use the |:helptags| command to generate the tags files. It will find all 320 languages in the specified directory. 321 322============================================================================== 3233. Writing help files *help-writing* 324 325For ease of use, a Vim help file for a plugin should follow the format of the 326standard Vim help files, except fot the fist line. If you are writing a new 327help file it's best to copy one of the existing files and use it as a 328template. 329 330The first line in a help file should have the following format: 331 332*plugin_name.txt* {short description of the plugin} 333 334The first field is a help tag where ":help plugin_name" will jump to. The 335remainder of the line, after a Tab, describes the plugin purpose in a short 336way. This will show up in the "LOCAL ADDITIONS" section of the main help 337file. Check there that it shows up properly: |local-additions|. 338 339If you want to add a version number of last modification date, put it in the 340second line, right aligned. 341 342At the bottom of the help file, place a Vim modeline to set the 'textwidth' 343and 'tabstop' options and the 'filetype' to "help". Never set a global option 344in such a modeline, that can have undesired consequences. 345 346 347TAGS 348 349To define a help tag, place the name between asterisks (*tag-name*). The 350tag-name should be different from all the Vim help tag names and ideally 351should begin with the name of the Vim plugin. The tag name is usually right 352aligned on a line. 353 354When referring to an existing help tag and to create a hot-link, place the 355name between two bars (|) eg. |help-writing|. 356 357When referring to a Vim command and to create a hot-link, place the 358name between two backticks, eg. inside `:filetype`. You will see this is 359highlighted as a command, like a code block (see below). 360 361When referring to a Vim option in the help file, place the option name between 362two single quotes, eg. 'statusline' 363 364 365HIGHLIGHTING 366 367To define a column heading, use a tilde character at the end of the line. 368This will highlight the column heading in a different color. E.g. 369 370Column heading~ 371 372To separate sections in a help file, place a series of '=' characters in a 373line starting from the first column. The section separator line is highlighted 374differently. 375 376To quote a block of ex-commands verbatim, place a greater than (>) character 377at the end of the line before the block and a less than (<) character as the 378first non-blank on a line following the block. Any line starting in column 1 379also implicitly stops the block of ex-commands before it. E.g. > 380 function Example_Func() 381 echo "Example" 382 endfunction 383< 384 385The following are highlighted differently in a Vim help file: 386 - a special key name expressed either in <> notation as in <PageDown>, or 387 as a Ctrl character as in CTRL-X 388 - anything between {braces}, e.g. {lhs} and {rhs} 389 390The word "Note", "Notes" and similar automagically receive distinctive 391highlighting. So do these: 392 *Todo something to do 393 *Error something wrong 394 395You can find the details in $VIMRUNTIME/syntax/help.vim 396 397 *inclusion* 398Vim is for everybody, no matter race, gender or anything. Some people make a 399big deal about using "he" or "his" when referring to the user, thinking it 400means we assume the user is male. That is not the case, it's just a habit of 401writing help text, which quite often is many years old. Also, a lot of the 402text is written by contributors for whom English is not their first language. 403We do not make any assumptions about the gender of the user, no matter how the 404text is phrased. Some people have suggested using "they", but that is not 405regular English. We do not want to spend much time on this discussion. The 406goal is that the reader understands how Vim works, the exact wording is 407secondary. 408 409 410 vim:tw=78:ts=8:noet:ft=help:norl: 411