1*helphelp.txt* For Vim version 8.1. Last change: 2019 May 04 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 <LF> or <CR> to separate the help 96 command from a following command. You need to type 97 CTRL-V first to insert the <LF> 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 107 *:helpg* *:helpgrep* 108:helpg[rep] {pattern}[@xx] 109 Search all help text files and make a list of lines 110 in which {pattern} matches. Jumps to the first match. 111 The optional [@xx] specifies that only matches in the 112 "xx" language are to be found. 113 You can navigate through the matches with the 114 |quickfix| commands, e.g., |:cnext| to jump to the 115 next one. Or use |:cwindow| to get the list of 116 matches in the quickfix window. 117 {pattern} is used as a Vim regexp |pattern|. 118 'ignorecase' is not used, add "\c" to ignore case. 119 Example for case sensitive search: > 120 :helpgrep Uganda 121< Example for case ignoring search: > 122 :helpgrep uganda\c 123< Example for searching in French help: > 124 :helpgrep backspace@fr 125< The pattern does not support line breaks, it must 126 match within one line. You can use |:grep| instead, 127 but then you need to get the list of help files in a 128 complicated way. 129 Cannot be followed by another command, everything is 130 used as part of the pattern. But you can use 131 |:execute| when needed. 132 Compressed help files will not be searched (Fedora 133 compresses the help files). 134 135 *:lh* *:lhelpgrep* 136:lh[elpgrep] {pattern}[@xx] 137 Same as ":helpgrep", except the location list is used 138 instead of the quickfix list. If the help window is 139 already opened, then the location list for that window 140 is used. Otherwise, a new help window is opened and 141 the location list for that window is set. The 142 location list for the current window is not changed 143 then. 144 145 *:exu* *:exusage* 146:exu[sage] Show help on Ex commands. Added to simulate the Nvi 147 command. 148 149 *:viu* *:viusage* 150:viu[sage] Show help on Normal mode commands. Added to simulate 151 the Nvi command. 152 153When no argument is given to |:help| the file given with the 'helpfile' option 154will be opened. Otherwise the specified tag is searched for in all "doc/tags" 155files in the directories specified in the 'runtimepath' option. 156 157The initial height of the help window can be set with the 'helpheight' option 158(default 20). 159 160Jump to specific subjects by using tags. This can be done in two ways: 161- Use the "CTRL-]" command while standing on the name of a command or option. 162 This only works when the tag is a keyword. "<C-Leftmouse>" and 163 "g<LeftMouse>" work just like "CTRL-]". 164- use the ":ta {subject}" command. This also works with non-keyword 165 characters. 166 167Use CTRL-T or CTRL-O to jump back. 168Use ":q" to close the help window. 169 170If there are several matches for an item you are looking for, this is how you 171can jump to each one of them: 1721. Open a help window 1732. Use the ":tag" command with a slash prepended to the tag. E.g.: > 174 :tag /min 1753. Use ":tnext" to jump to the next matching tag. 176 177It is possible to add help files for plugins and other items. You don't need 178to change the distributed help files for that. See |add-local-help|. 179 180To write a local help file, see |write-local-help|. 181 182Note that the title lines from the local help files are automagically added to 183the "LOCAL ADDITIONS" section in the "help.txt" help file |local-additions|. 184This is done when viewing the file in Vim, the file itself is not changed. It 185is done by going through all help files and obtaining the first line of each 186file. The files in $VIMRUNTIME/doc are skipped. 187 188 *help-xterm-window* 189If you want to have the help in another xterm window, you could use this 190command: > 191 :!xterm -e vim +help & 192< 193 194 *:helpfind* *:helpf* 195:helpf[ind] Like |:help|, but use a dialog to enter the argument. 196 Only for backwards compatibility. It now executes the 197 ToolBar.FindHelp menu entry instead of using a builtin 198 dialog. {only when compiled with |+GUI_GTK|} 199 200 *:helpt* *:helptags* 201 *E154* *E150* *E151* *E152* *E153* *E670* 202:helpt[ags] [++t] {dir} 203 Generate the help tags file(s) for directory {dir}. 204 When {dir} is ALL then all "doc" directories in 205 'runtimepath' will be used. 206 207 All "*.txt" and "*.??x" files in the directory and 208 sub-directories are scanned for a help tag definition 209 in between stars. The "*.??x" files are for 210 translated docs, they generate the "tags-??" file, see 211 |help-translated|. The generated tags files are 212 sorted. 213 When there are duplicates an error message is given. 214 An existing tags file is silently overwritten. 215 216 The optional "++t" argument forces adding the 217 "help-tags" tag. This is also done when the {dir} is 218 equal to $VIMRUNTIME/doc. 219 220 To rebuild the help tags in the runtime directory 221 (requires write permission there): > 222 :helptags $VIMRUNTIME/doc 223 224============================================================================== 2252. Translated help files *help-translated* 226 227It is possible to add translated help files, next to the original English help 228files. Vim will search for all help in "doc" directories in 'runtimepath'. 229This is only available when compiled with the |+multi_lang| feature. 230 231At this moment translations are available for: 232 Chinese - multiple authors 233 French - translated by David Blanchet 234 Italian - translated by Antonio Colombo 235 Japanese - multiple authors 236 Polish - translated by Mikolaj Machowski 237 Russian - translated by Vassily Ragosin 238See the Vim website to find them: http://www.vim.org/translations.php 239 240A set of translated help files consists of these files: 241 242 help.abx 243 howto.abx 244 ... 245 tags-ab 246 247"ab" is the two-letter language code. Thus for Italian the names are: 248 249 help.itx 250 howto.itx 251 ... 252 tags-it 253 254The 'helplang' option can be set to the preferred language(s). The default is 255set according to the environment. Vim will first try to find a matching tag 256in the preferred language(s). English is used when it cannot be found. 257 258To find a tag in a specific language, append "@ab" to a tag, where "ab" is the 259two-letter language code. Example: > 260 :he user-manual@it 261 :he user-manual@en 262The first one finds the Italian user manual, even when 'helplang' is empty. 263The second one finds the English user manual, even when 'helplang' is set to 264"it". 265 266When using command-line completion for the ":help" command, the "@en" 267extension is only shown when a tag exists for multiple languages. When the 268tag only exists for English "@en" is omitted. When the first candidate has an 269"@ab" extension and it matches the first language in 'helplang' "@ab" is also 270omitted. 271 272When using |CTRL-]| or ":help!" in a non-English help file Vim will try to 273find the tag in the same language. If not found then 'helplang' will be used 274to select a language. 275 276Help files must use latin1 or utf-8 encoding. Vim assumes the encoding is 277utf-8 when finding non-ASCII characters in the first line. Thus you must 278translate the header with "For Vim version". 279 280The same encoding must be used for the help files of one language in one 281directory. You can use a different encoding for different languages and use 282a different encoding for help files of the same language but in a different 283directory. 284 285Hints for translators: 286- Do not translate the tags. This makes it possible to use 'helplang' to 287 specify the preferred language. You may add new tags in your language. 288- When you do not translate a part of a file, add tags to the English version, 289 using the "tag@en" notation. 290- Make a package with all the files and the tags file available for download. 291 Users can drop it in one of the "doc" directories and start use it. 292 Report this to Bram, so that he can add a link on www.vim.org. 293- Use the |:helptags| command to generate the tags files. It will find all 294 languages in the specified directory. 295 296============================================================================== 2973. Writing help files *help-writing* 298 299For ease of use, a Vim help file for a plugin should follow the format of the 300standard Vim help files. If you are writing a new help file it's best to copy 301one of the existing files and use it as a template. 302 303The first line in a help file should have the following format: 304 305*helpfile_name.txt* For Vim version 7.3 Last change: 2010 June 4 306 307The first field is a link to the help file name. The second field describes 308the applicable Vim version. The last field specifies the last modification 309date of the file. Each field is separated by a tab. 310 311At the bottom of the help file, place a Vim modeline to set the 'textwidth' 312and 'tabstop' options and the 'filetype' to "help". Never set a global option 313in such a modeline, that can have consequences undesired by whoever reads that 314help. 315 316 317TAGS 318 319To define a help tag, place the name between asterisks (*tag-name*). The 320tag-name should be different from all the Vim help tag names and ideally 321should begin with the name of the Vim plugin. The tag name is usually right 322aligned on a line. 323 324When referring to an existing help tag and to create a hot-link, place the 325name between two bars (|) eg. |help-writing|. 326 327When referring to a Vim command and to create a hot-link, place the 328name between two backticks, eg. inside `:filetype`. You will see this is 329highlighted as a command, like a code block (see below). 330 331When referring to a Vim option in the help file, place the option name between 332two single quotes, eg. 'statusline' 333 334 335HIGHLIGHTING 336 337To define a column heading, use a tilde character at the end of the line. 338This will highlight the column heading in a different color. E.g. 339 340Column heading~ 341 342To separate sections in a help file, place a series of '=' characters in a 343line starting from the first column. The section separator line is highlighted 344differently. 345 346To quote a block of ex-commands verbatim, place a greater than (>) character 347at the end of the line before the block and a less than (<) character as the 348first non-blank on a line following the block. Any line starting in column 1 349also implicitly stops the block of ex-commands before it. E.g. > 350 function Example_Func() 351 echo "Example" 352 endfunction 353< 354 355The following are highlighted differently in a Vim help file: 356 - a special key name expressed either in <> notation as in <PageDown>, or 357 as a Ctrl character as in CTRL-X 358 - anything between {braces}, e.g. {lhs} and {rhs} 359 360The word "Note", "Notes" and similar automagically receive distinctive 361highlighting. So do these: 362 *Todo something to do 363 *Error something wrong 364 365You can find the details in $VIMRUNTIME/syntax/help.vim 366 367 vim:tw=78:ts=8:noet:ft=help:norl: 368