1*various.txt* For Vim version 7.0aa. Last change: 2004 Jun 18 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7Various commands *various* 8 91. Various commands |various-cmds| 102. Online help |online-help| 113. Printing |printing| 124. Using Vim like less or more |less| 13 14============================================================================== 151. Various commands *various-cmds* 16 17 *CTRL-L* 18CTRL-L Clear and redraw the screen (later). 19 20 *:redr* *:redraw* 21:redr[aw][!] Redraw the screen right now. When ! is included it is 22 cleared first. 23 Useful to update the screen halfway executing a script 24 or function. Also when halfway a mapping and 25 'lazyredraw' is set. 26 27 *:redraws* *:redrawstatus* 28:redraws[tatus][!] Redraw the status line of the current window. When ! 29 is included all status lines are redrawn. 30 Useful to update the status line(s) when 'statusline' 31 includes an item that doesn't cause automatic 32 updating. 33 34 *N<Del>* 35<Del> When entering a number: Remove the last digit. 36 Note: if you like to use <BS> for this, add this 37 mapping to your .vimrc: > 38 :map CTRL-V <BS> CTRL-V <Del> 39< See |:fixdel| if your <Del> key does not do what you 40 want. 41 42:as[cii] or *ga* *:as* *:ascii* 43ga Print the ascii value of the character under the 44 cursor in decimal, hexadecimal and octal. For 45 example, when the cursor is on a 'R': 46 <R> 82, Hex 52, Octal 122 ~ 47 When the character is a non-standard ASCII character, 48 but printable according to the 'isprint' option, the 49 non-printable version is also given. When the 50 character is larger than 127, the <M-x> form is also 51 printed. For example: 52 <~A> <M-^A> 129, Hex 81, Octal 201 ~ 53 <p> <|~> <M-~> 254, Hex fe, Octal 376 ~ 54 (where <p> is a special character) 55 The <Nul> character in a file is stored internally as 56 <NL>, but it will be shown as: 57 <^@> 0, Hex 00, Octal 000 ~ 58 Mnemonic: Get Ascii value. {not in Vi} 59 60 *g8* 61g8 Print the hex values of the bytes used in the 62 character under the cursor, assuming it is in |UTF-8| 63 encoding. This also shows composing characters. 64 Example of a character with three composing 65 characters: 66 e0 b8 81 + e0 b8 b9 + e0 b9 89 ~ 67 {not in Vi} 68 69 *:p* *:pr* *:print* 70:[range]p[rint] Print [range] lines (default current line). 71 Note: If you are looking for a way to print your text 72 file, you need an external program for that. In the 73 GUI you can use the File.Print menu entry. 74 (For printing on paper see |:hardcopy|) 75 76:[range]p[rint] {count} 77 Print {count} lines, starting with [range] (default 78 current line |cmdline-ranges|). 79 80 *:P* *:Print* 81:[range]P[rint] [count] 82 Just as ":print". Was apparently added to Vi for 83 people that keep the shift key pressed too long... 84 85 *:l* *:list* 86:[range]l[ist] [count] 87 Same as :print, but display unprintable characters 88 with '^'. 89 90 *:nu* *:number* 91:[range]nu[mber] [count] 92 Same as :print, but precede each line with its line 93 number. (See also 'highlight' option). 94 95 *:#* 96:[range]# [count] synonym for :number. 97 98 *:z* *E144* 99:{range}z[+-^.=]{count} Display several lines of text surrounding the line 100 specified with {range}, or around the current line 101 if there is no {range}. If there is a {count}, that's 102 how many lines you'll see; otherwise, the current 103 window size is used. 104 105 :z can be used either alone or followed by any of 106 several punctuation marks. These have the following 107 effect: 108 109 mark first line last line new location ~ 110 ---- ---------- --------- ------------ 111 + current line 1 scr forward 1 scr forward 112 - 1 scr back current line current line 113 ^ 2 scr back 1 scr back 1 scr back 114 . 1/2 scr back 1/2 scr fwd 1/2 src fwd 115 = 1/2 src back 1/2 scr fwd current line 116 117 Specifying no mark at all is the same as "+". 118 If the mark is "=", a line of dashes is printed 119 around the current line. 120 121:{range}z#[+-^.=]{count} *:z#* 122 Like ":z", but number the lines. 123 {not in all versions of Vi, not with these arguments} 124 125 *:=* 126:= Print the last line number. 127 128:{range}= Prints the last line number in {range}. For example, 129 this prints the current line number: > 130 :.= 131 132:norm[al][!] {commands} *:norm* *:normal* 133 Execute Normal mode commands {commands}. This makes 134 it possible to execute Normal mode commands typed on 135 the command-line. {commands} is executed like it is 136 typed. For undo all commands are undone together. 137 If the [!] is given, mappings will not be used. 138 {commands} should be a complete command. If 139 {commands} does not finish a command, the last one 140 will be aborted as if <Esc> or <C-C> was typed. 141 The display isn't updated while ":normal" is busy. 142 This implies that an insert command must be completed 143 (to start Insert mode, see |:startinsert|). A ":" 144 command must be completed as well. 145 {commands} cannot start with a space. Put a 1 (one) 146 before it, 1 space is one space. 147 The 'insertmode' option is ignored for {commands}. 148 This command cannot be followed by another command, 149 since any '|' is considered part of the command. 150 This command can be used recursively, but the depth is 151 limited by 'maxmapdepth'. 152 When this command is called from a non-remappable 153 mapping |:noremap|, the argument can be mapped anyway. 154 An alternative is to use |:execute|, which uses an 155 expression as argument. This allows the use of 156 printable characters. Example: > 157 :exe "normal \<c-w>\<c-w>" 158< {not in Vi, of course} 159 {not available when the |+ex_extra| feature was 160 disabled at compile time} 161 162:{range}norm[al][!] {commands} *:normal-range* 163 Execute Normal mode commands {commands} for each line 164 in the {range}. Before executing the {commands}, the 165 cursor is positioned in the first column of the range, 166 for each line. Otherwise it's the same as the 167 ":normal" command without a range. 168 {not in Vi} 169 Not available when |+ex_extra| feature was disabled at 170 compile time. 171 172 *:sh* *:shell* *E371* 173:sh[ell] This command starts a shell. When the shell exits 174 (after the "exit" command) you return to Vim. The 175 name for the shell command comes from 'shell' option. 176 *E360* 177 Note: This doesn't work when Vim on the Amiga was 178 started in QuickFix mode from a compiler, because the 179 compiler will have set stdin to a non-interactive 180 mode. 181 182 *:!cmd* *:!* *E34* 183:!{cmd} Execute {cmd} with the shell. See also the 'shell' 184 and 'shelltype' option. 185 Any '!' in {cmd} is replaced with the previous 186 external command (see also 'cpoptions'). But not when 187 there is a backslash before the '!', then that 188 backslash is removed. Example: ":!ls" followed by 189 ":!echo ! \! \\!" executes "echo ls ! \!". 190 After the command has been executed, the timestamp of 191 the current file is checked |timestamp|. 192 There cannot be a '|' in {cmd}, see |:bar|. 193 A newline character ends {cmd}, what follows is 194 interpreted as a following ":" command. However, if 195 there is a backslash before the newline it is removed 196 and {cmd} continues. It doesn't matter how many 197 backslashes are before the newline, only one is 198 removed. 199 On Unix the command normally runs in a non-interactive 200 shell. If you want an interactive shell to be used 201 (to use aliases) set 'shellcmdflag' to "-ic". 202 For Win32 also see |:!start|. 203 Vim redraws the screen after the command is finished, 204 because it may have printed any text. This requires a 205 hit-enter prompt, so that you can read any messages. 206 To avoid this use: > 207 :silent !{cmd} 208< The screen is not redrawn then, thus you have to use 209 CTRL-L or ":redraw!" if the command did display 210 something. 211 Also see |shell-window|. 212 213 *:!!* 214:!! Repeat last ":!{cmd}". 215 216 *:ve* *:version* 217:ve[rsion] Print the version number of the editor. If the 218 compiler used understands "__DATE__" the compilation 219 date is mentioned. Otherwise a fixed release-date is 220 shown. 221 The following lines contain information about which 222 features were enabled when Vim was compiled. When 223 there is a preceding '+', the feature is included, 224 when there is a '-' it is excluded. To change this, 225 you have to edit feature.h and recompile Vim. 226 To check for this in an expression, see |has()|. 227 Here is an overview of the features. 228 The first column shows the smallest version in which 229 they are included: 230 T tiny 231 S small 232 N normal 233 B big 234 H huge 235 m manually enabled or depends on other features 236 (none) system dependent 237 Thus if a feature is marked with "N", it is included 238 in the normal, big and huge versions of Vim. 239 240 *+feature-list* 241 *+ARP* Amiga only: ARP support included 242B *+arabic* |Arabic| language support 243N *+autocmd* |:autocmd|, automatic commands 244m *+balloon_eval* |balloon-eval| support 245N *+browse* |:browse| command 246N *+builtin_terms* some terminals builtin |builtin-terms| 247B *++builtin_terms* maximal terminals builtin |builtin-terms| 248N *+byte_offset* support for 'o' flag in 'statusline' option, "go" 249 and ":goto" commands. 250N *+cindent* |'cindent'|, C indenting 251N *+clientserver* Unix and Win32: Remote invocation |clientserver| 252 *+clipboard* |clipboard| support 253N *+cmdline_compl* command line completion |cmdline-completion| 254N *+cmdline_hist* command line history |cmdline-history| 255N *+cmdline_info* |'showcmd'| and |'ruler'| 256N *+comments* |'comments'| support 257N *+cryptv* encryption support |encryption| 258B *+cscope* |cscope| support 259N *+dialog_gui* Support for |:confirm| with GUI dialog. 260N *+dialog_con* Support for |:confirm| with console dialog. 261N *+dialog_con_gui* Support for |:confirm| with GUI and console dialog. 262N *+diff* |vimdiff| and 'diff' 263N *+digraphs* |digraphs| *E196* 264 *+dnd* Support for DnD into the "~ register |quote_~|. 265B *+emacs_tags* |emacs-tags| files 266N *+eval* expression evaluation |eval.txt| 267N *+ex_extra* Vim's extra Ex commands: |:center|, |:left|, 268 |:normal|, |:retab| and |:right| 269N *+extra_search* |'hlsearch'| and |'incsearch'| options. 270B *+farsi* |farsi| language 271N *+file_in_path* |gf|, |CTRL-W_f| and |<cfile>| 272N *+find_in_path* include file searches: |[I|, |:isearch|, 273 |CTRL-W_CTRL-I|, |:checkpath|, etc. 274N *+folding* |folding| 275 *+footer* |gui-footer| 276 *+fork* Unix only: |fork| shell commands 277N *+gettext* message translations |multi-lang| 278 *+GUI_Athena* Unix only: Athena |GUI| 279 *+GUI_neXtaw* Unix only: neXtaw |GUI| 280 *+GUI_BeOS* BeOS only: BeOS |GUI| 281 *+GUI_GTK* Unix only: GTK+ |GUI| 282 *+GUI_Motif* Unix only: Motif |GUI| 283 *+GUI_Photon* QNX only: Photon |GUI| 284m *+hangul_input* Hangul input support |hangul| 285 *+iconv* Compiled with the |iconv()| function, may have |/dyn| 286N *+insert_expand* |insert_expand| Insert mode completion 287N *+jumplist* |jumplist| 288B *+keymap* |'keymap'| 289B *+langmap* |'langmap'| 290N *+libcall* |libcall()| 291N *+linebreak* |'linebreak'|, |'breakat'| and |'showbreak'| 292N *+lispindent* |'lisp'| 293N *+listcmds* Vim commands for the list of buffers |buffer-hidden| 294 and argument list |:argdelete| 295N *+localmap* Support for mappings local to a buffer |:map-local| 296N *+menu* |:menu| 297N *+mksession* |:mksession| 298N *+modify_fname* |filename-modifiers| 299N *+mouse* Mouse handling |mouse-using| 300N *+mouseshape* |'mouseshape'| 301B *+mouse_dec* Unix only: Dec terminal mouse handling |dec-mouse| 302N *+mouse_gpm* Unix only: Linux console mouse handling |gpm-mouse| 303B *+mouse_netterm* Unix only: netterm mouse handling |netterm-mouse| 304N *+mouse_pterm* QNX only: pterm mouse handling |qnx-terminal| 305N *+mouse_xterm* Unix only: xterm mouse handling |xterm-mouse| 306B *+multi_byte* Korean and other languages |multibyte| 307 *+multi_byte_ime* Win32 input method for multibyte chars |multibyte-ime| 308N *+multi_lang* non-English language support |multi-lang| 309m *+netbeans_intg* |netbeans| 310m *+ole* Win32 GUI only: |ole-interface| 311 *+osfiletype* Support for the 'osfiletype' option and filetype 312 checking in automatic commands. |autocmd-osfiletypes| 313N *+path_extra* Up/downwards search in 'path' and 'tags' 314m *+perl* Perl interface |perl|, may have |/dyn| 315 *+postscript* |:hardcopy| writes a PostScript file 316N *+printer* |:hardcopy| command 317m *+python* Python interface |python|, may have |/dyn| 318N *+quickfix* |:make| and |quickfix| commands 319B *+rightleft* Right to left typing |'rightleft'| 320m *+ruby* Ruby interface |ruby|, may have |/dyn| 321N *+scrollbind* |'scrollbind'| 322B *+signs* |:sign| 323N *+smartindent* |'smartindent'| 324m *+sniff* SniFF interface |sniff| 325N *+statusline* Options 'statusline', 'rulerformat' and special 326 formats of 'titlestring' and 'iconstring' 327m *+sun_workshop* |workshop| 328N *+syntax* Syntax highlighting |syntax| 329 *+system()* Unix only: opposite of |+fork| 330N *+tag_binary* binary searching in tags file |tag-binary-search| 331N *+tag_old_static* old method for static tags |tag-old-static| 332m *+tag_any_white* any white space allowed in tags file |tag-any-white| 333m *+tcl* Tcl interface |tcl|, may have |/dyn| 334 *+terminfo* uses |terminfo| instead of termcap 335N *+termresponse* support for |t_RV| and |v:termresponse| 336N *+textobjects* |text-objects| selection 337 *+tgetent* non-Unix only: able to use external termcap 338N *+title* Setting the window title |'title'| 339N *+toolbar* |gui-toolbar| 340N *+user_commands* User-defined commands. |user-commands| 341N *+viminfo* |'viminfo'| 342N *+vertsplit* Vertically split windows |:vsplit| 343N *+virtualedit* |'virtualedit'| 344S *+visual* Visual mode |Visual-mode| 345N *+visualextra* extra Visual mode commands |blockwise-operators| 346N *+vreplace* |gR| and |gr| 347N *+wildignore* |'wildignore'| 348N *+wildmenu* |'wildmenu'| 349S *+windows* more than one window 350m *+writebackup* |'writebackup'| is default on 351m *+xim* X input method |xim| 352 *+xfontset* X fontset support |xfontset| 353 *+xsmp* XSMP (X session management) support 354 *+xsmp_interact* interactive XSMP (X session management) support 355N *+xterm_clipboard* Unix only: xterm clipboard handling 356m *+xterm_save* save and restore xterm screen |xterm-screens| 357N *+X11* Unix only: can restore window title |X11| 358 359 */dyn* *E370* *E448* 360 To some of the features "/dyn" is added when the 361 feature is only available when the related library can 362 be dynamically loaded. 363 364:ve[rsion] {nr} Is now ignored. This was previously used to check the 365 version number of a .vimrc file. It was removed, 366 because you can now use the ":if" command for 367 version-dependent behavior. {not in Vi} 368 369 *:redi* *:redir* 370:redi[r][!] > {file} Redirect messages to file {file}. The messages which 371 are the output of commands are written to that file, 372 until redirection ends. The messages are also still 373 shown on the screen. When [!] is included, an 374 existing file is overwritten. When [!] is omitted, 375 and {file} exists, this command fails. 376 Only one ":redir" can be active at a time. Calls to 377 ":redir" will close any active redirection before 378 starting redirection to the new target. 379 To stop the messages and commands from being echoed to 380 the screen, put the commands in a function and call it 381 with ":silent call Function()". 382 {not in Vi} 383 384:redi[r] >> {file} Redirect messages to file {file}. Append if {file} 385 already exists. {not in Vi} 386 387:redi[r] @{a-zA-Z} Redirect messages to register {a-z}. Append to the 388 contents of the register if its name is given 389 uppercase {A-Z}. {not in Vi} 390 391:redi[r] @* Redirect messages to the clipboard. {not in Vi} 392 393:redi[r] @" Redirect messages to the unnamed register. {not in Vi} 394 395:redi[r] END End redirecting messages. {not in Vi} 396 397 *:sil* *:silent* 398:sil[ent][!] {command} Execute {command} silently. Normal messages will not 399 be given or added to the message history. 400 When [!] is added, error messages will also be 401 skipped, and commands and mappings will not be aborted 402 when an error is detected. |v:errmsg| is still set. 403 When [!] is not used, an error message will cause 404 further messages to be displayed normally. 405 Redirection, started with |:redir|, will continue as 406 usual, although there might be small differences. 407 This will allow redirecting the output of a command 408 without seeing it on the screen. Example: > 409 :redir >/tmp/foobar 410 :silent g/Aap/p 411 :redir END 412< To execute a Normal mode command silently, use the 413 |:normal| command. For example, to search for a 414 string without messages: > 415 :silent exe "normal /path\<CR>" 416< ":silent!" is useful to execute a command that may 417 fail, but the failure is to be ignored. Example: > 418 :let v:errmsg = "" 419 :silent! /^begin 420 :if v:errmsg != "" 421 : ... pattern was not found 422< ":silent" will also avoid the hit-enter prompt. When 423 using this for an external command, this may cause the 424 screen to be messed up. Use |CTRL-L| to clean it up 425 then. 426 ":silent menu ..." defines a menu that will not echo a 427 Command-line command. The command will still produce 428 messages though. Use ":silent" in the command itself 429 to avoid that: ":silent menu .... :silent command". 430 431 *:verb* *:verbose* 432:[count]verb[ose] {command} 433 Execute {command} with 'verbose' set to [count]. If 434 [count] is omitted one is used. ":0verbose" can be 435 used to set 'verbose' to zero. 436 The additional use of ":silent" makes messages 437 generated but not displayed. 438 The combination of ":silent" and ":verbose" can be 439 used to generate messages and check them with 440 |v:statusmsg| and friends. For example: > 441 :let v:statusmsg = "" 442 :silent verbose runtime foobar.vim 443 :if v:statusmsg != "" 444 : " foobar.vim could not be found 445 :endif 446< When concatenating another command, the ":verbose" 447 only applies to the first one: > 448 :4verbose set verbose | set verbose 449< verbose=4 ~ 450 verbose=0 ~ 451 452 *K* 453K Run a program to lookup the keyword under the 454 cursor. The name of the program is given with the 455 'keywordprg' (kp) option (default is "man"). The 456 keyword is formed of letters, numbers and the 457 characters in 'iskeyword'. The keyword under or 458 right of the cursor is used. The same can be done 459 with the command > 460 :!{program} {keyword} 461< There is an example of a program to use in the tools 462 directory of Vim. It is called 'ref' and does a 463 simple spelling check. 464 Special cases: 465 - If 'keywordprg' is empty, the ":help" command is 466 used. It's a good idea to include more characters 467 in 'iskeyword' then, to be able to find more help. 468 - When 'keywordprg' is equal to "man", a count before 469 "K" is inserted after the "man" command and before 470 the keyword. For example, using "2K" while the 471 cursor is on "mkdir", results in: > 472 !man 2 mkdir 473< - When 'keywordprg' is equal to "man -s", a count 474 before "K" is inserted after the "-s". If there is 475 no count, the "-s" is removed. 476 {not in Vi} 477 478 *v_K* 479{Visual}K Like "K", but use the visually highlighted text for 480 the keyword. Only works when the highlighted text is 481 not more than one line. {not in Vi} 482 483[N]gs *gs* *:sl* *:sleep* 484:[N]sl[eep] [N] [m] Do nothing for [N] seconds. When [m] is included, 485 sleep for [N] milliseconds. The count for "gs" always 486 uses seconds. The default is one second. > 487 :sleep "sleep for one second 488 :5sleep "sleep for five seconds 489 :sleep 100m "sleep for a hundred milliseconds 490 10gs "sleep for ten seconds 491< Can be interrupted with CTRL-C (CTRL-Break on MS-DOS). 492 "gs" stands for "goto sleep". While sleeping the 493 cursor is positioned in the text (if visible). {not 494 in Vi} 495 496 *g_CTRL-A* 497g CTRL-A Only when Vim was compiled with MEM_PROFILING defined 498 (which is very rare): print memory usage statistics. 499 Only useful for debugging Vim. 500 501============================================================================== 5022. Online help *online-help* 503 504 *help* *<Help>* *:h* *:help* *<F1>* *i_<F1>* *i_<Help>* 505<Help> or 506:h[elp] Open a window and display the help file in read-only 507 mode. If there is a help window open already, use 508 that one. Otherwise, if the current window uses the 509 full width of the screen or is at least 80 characters 510 wide, the help window will appear just above the 511 current window. Otherwise the new window is put at 512 the very top. 513 The 'helplang' option is used to select a language, if 514 the main help file is available in several languages. 515 {not in Vi} 516 517 *{subject}* *E149* *E661* 518:h[elp] {subject} Like ":help", additionally jump to the tag {subject}. 519 {subject} can include wildcards like "*", "?" and 520 "[a-z]": 521 :help z? jump to help for any "z" command 522 :help z. jump to the help for "z." 523 If there is no full match for the pattern, or there 524 are several matches, the "best" match will be used. 525 A sophisticated algorithm is used to decide which 526 match is better than another one. These items are 527 considered in the computation: 528 - A match with same case is much better than a match 529 with different case. 530 - A match that starts after a non-alphanumeric 531 character is better than a match in the middle of a 532 word. 533 - A match at or near the beginning of the tag is 534 better than a match further on. 535 - The more alphanumeric characters match, the better. 536 - The shorter the length of the match, the better. 537 538 The 'helplang' option is used to select a language, if 539 the {subject} is available in several languages. 540 To find a tag in a specific language, append "@ab", 541 where "ab" is the two-letter language code. See 542 |help-translated|. 543 544 Note that the longer the {subject} you give, the less 545 matches will be found. You can get an idea how this 546 all works by using commandline completion (type CTRL-D 547 after ":help subject"). 548 If there are several matches, you can have them listed 549 by hitting CTRL-D. Example: > 550 :help cont<Ctrl-D> 551< To use a regexp |pattern|, first do ":help" and then 552 use ":tag {pattern}" in the help window. The 553 ":tnext" command can then be used to jump to other 554 matches, "tselect" to list matches and choose one. > 555 :help index| :tse z. 556< This command can be followed by '|' and another 557 command, but you don't need to escape the '|' inside a 558 help command. So these both work: > 559 :help | 560 :help k| only 561< Note that a space before the '|' is seen as part of 562 the ":help" argument. 563 You can also use <LF> or <CR> to separate the help 564 command from a following command. You need to type 565 CTRL-V first to insert the <LF> or <CR>. Example: > 566 :help so<C-V><CR>only 567< {not in Vi} 568 569:h[elp]! [subject] Like ":help", but in non-English help files prefer to 570 find a tag in a file with the same language as the 571 current file. See |help-translated|. 572 573 *:helpg* *:helpgrep* 574:helpg[rep] {pattern}[@xx] 575 Search all help text files and make a list of lines 576 in which {pattern} matches. Jumps to the first match. 577 The optional [@xx] specifies that only matches in the 578 "xx" language are to be found. 579 You can navigate through the matches with the 580 |quickfix| commands, e.g., |:cnext| to jump to the 581 next one. Or use |:cwindow| to get the list of 582 matches in the quickfix window. 583 {pattern} is used as a Vim regexp |pattern|. 584 'ignorecase' is not used, add "\c" to ignore case. 585 Example for case sensitive search: > 586 :helpgrep Uganda 587< Example for case ignoring search: > 588 :helpgrep uganda\c 589< Example for searching in French help: > 590 :helpgrep backspace@fr 591< Cannot be followed by another command, everything is 592 used as part of the pattern. But you can use 593 |:execute| when needed. 594 Compressed help files will not be searched (Debian 595 compresses the help files). 596 {not in Vi} 597 598 599When no argument is given to |:help| the file given with the 'helpfile' option 600will be opened. Otherwise the specified tag is searched for in all "doc/tags" 601files in the directories specified in the 'runtimepath' option. 602 603The initial height of the help window can be set with the 'helpheight' option 604(default 20). 605 606Jump to specific subjects by using tags. This can be done in two ways: 607- Use the "CTRL-]" command while standing on the name of a command or option. 608 This only works when the tag is a keyword. "<C-Leftmouse>" and 609 "g<LeftMouse>" work just like "CTRL-]". 610- use the ":ta {subject}" command. This also works with non-keyword 611 characters. 612 613Use CTRL-T or CTRL-O to jump back. 614Use ":q" to close the help window. 615 616If there are several matches for an item you are looking for, this is how you 617can jump to each one of them: 6181. Open a help window 6192. Use the ":tag" command with a slash prepended to the tag. E.g.: > 620 :tag /min 6213. Use ":tnext" to jump to the next matching tag. 622 623It is possible to add help files for plugins and other items. You don't need 624to change the distributed help files for that. See |add-local-help|. 625 626To write a local help file, see |write-local-help|. 627 628Note that the title lines from the local help files are automagically added to 629the "LOCAL ADDITIONS" section in the "help.txt" help file |local-additions|. 630This is done when viewing the file in Vim, the file itself is not changed. It 631is done by going through all help files and obtaining the first line of each 632file. The files in $VIMRUNTIME/doc are skipped. 633 634 *help-xterm-window* 635If you want to have the help in another xterm window, you could use this 636command: > 637 :!xterm -e vim +help & 638< 639 640 *:helpfind* *:helpf* 641:helpf[ind] Like |:help|, but use a dialog to enter the argument. 642 Only for backwards compatibility. It now executes the 643 ToolBar.FindHelp menu entry instead of using a builtin 644 dialog. {only when compiled with |+GUI_GTK|} 645< {not in Vi} 646 647 *:helpt* *:helptags* 648 *E154* *E150* *E151* *E152* *E153* *E670* 649:helpt[ags] {dir} Generate the help tags file(s) for directory {dir}. 650 All "*.txt" and "*.??x" files in the directory are 651 scanned for a help tag definition in between stars. 652 The "*.??x" files are for translated docs, they 653 generate the "tags-??" file, see |help-translated|. 654 The generated tags files are sorted. 655 When there are duplicates an error message is given. 656 An existing tags file is silently overwritten. 657 To rebuild the help tags in the runtime directory 658 (requires write permission there): > 659 :helptags $VIMRUNTIME/doc 660< {not in Vi} 661 662 663TRANSLATED HELP *help-translated* 664 665It is possible to add translated help files, next to the original English help 666files. Vim will search for all help in "doc" directories in 'runtimepath'. 667This is only available when compiled with the |+multi_lang| feature. 668 669A set of translated help files consists of these files: 670 671 help.abx 672 howto.abx 673 ... 674 tags-ab 675 676"ab" is the two-letter language code. Thus for Italian the names are: 677 678 help.itx 679 howto.itx 680 ... 681 tags-it 682 683The 'helplang' option can be set to the preferred language(s). The default is 684set according to the environment. Vim will first try to find a matching tag 685in the preferred language(s). English is used when it cannot be found. 686 687To find a tag in a specific language, append "@ab" to a tag, where "ab" is the 688two-letter language code. Example: > 689 :he user-manual@it 690 :he user-manual@en 691The first one finds the Italian user manual, even when 'helplang' is empty. 692The second one finds the English user manual, even when 'helplang' is set to 693"it". 694 695When using command-line completion for the ":help" command, the "@en" 696extention is only shown when a tag exists for multiple languages. When the 697tag only exists for English "@en" is omitted. 698 699When using |CTRL-]| or ":help!" in a non-English help file Vim will try to 700find the tag in the same language. If not found then 'helplang' will be used 701to select a language. 702 703Help files must use latin1 or utf-8 encoding. Vim assumes the encoding is 704utf-8 when finding non-ASCII characters in the first line. Thus you must 705translate the header with "For Vim version". 706 707The same encoding must be used for the help files of one language in one 708directory. You can use a different encoding for different languages and use 709a different encoding for help files of the same language but in a different 710directory. 711 712Hints for translators: 713- Do not translate the tags. This makes it possible to use 'helplang' to 714 specify the preferred language. You may add new tags in your language. 715- When you do not translate a part of a file, add tags to the English version, 716 using the "tag@en" notation. 717- Make a package with all the files and the tags file available for download. 718 Users can drop it in one of the "doc" directories and start use it. 719 Report this to Bram, so that he can add a link on www.vim.org. 720- Use the |:helptags| command to generate the tags files. It will find all 721 languages in the specified directory. 722 723============================================================================== 7243. Printing *printing* 725 726On MS-Windows Vim can print your text on any installed printer. On other 727systems a PostScript file is produced. This can be directly sent to a 728PostScript printer. For other printers a program like ghostscript needs to be 729used. 730 7313.1 PostScript Printing |postscript-printing| 7323.2 PostScript Printing Encoding |postscript-print-encoding| 7333.3 PostScript Printing Troubleshooting |postscript-print-trouble| 7343.4 PostScript Utilities |postscript-print-util| 7353.5 Formfeed Characters |printing-formfeed| 736 737{not in Vi} 738{only available when compiled with |+printer| feature} 739 740 *:ha* *:hardcopy* *E237* *E238* *E324* 741:[range]ha[rdcopy][!] [arguments] 742 Send [range] lines (default whole file) to the 743 printer. 744 745 On MS-Windows a dialog is displayed to allow selection 746 of printer, paper size etc. To skip the dialog, use 747 the [!]. In this case the printer defined by 748 'printdevice' is used, or, if 'printdevice' is empty, 749 the system default printer. 750 751 For systems other than MS-Windows, PostScript is 752 written in a temp file and 'printexpr' is used to 753 actually print it. Then [arguments] can be used by 754 'printexpr' through |v:cmdarg|. Otherwise [arguments] 755 is ignored. 'printoptions' can be used to specify 756 paper size, duplex, etc. 757 758:[range]ha[rdcopy][!] >{filename} 759 As above, but write the resulting PostScript in file 760 {filename}. 761 Things like "%" are expanded |cmdline-special| 762 Careful: An existing file is silently overwritten. 763 {only available when compiled with the |+postscript| 764 feature} 765 On MS-Windows use the "print to file" feature of the 766 printer driver. 767 768Progress is displayed during printing as a page number and a percentage. To 769abort printing use the interrupt key (CTRL-C or, on MS-systems, CTRL-Break). 770 771Printer output is controlled by the 'printfont' and 'printoptions' options. 772'printheader' specifies the format of a page header. 773 774The printed file is always limited to the selected margins, irrespective of 775the current window's 'wrap' or 'linebreak' settings. The "wrap" item in 776'printoptions' can be used to switch wrapping off. 777The current highlighting colors are used in the printout, with the following 778considerations: 7791) The normal background is always rendered as white (i.e. blank paper.) 7802) White text or the default foreground is rendered as black, so that it shows 781 up! 7823) If 'background' is "dark", then the colours are darkened to compensate for 783 the fact that otherwise they would be too bright to show up clearly on 784 white paper. 785 786 7873.1 PostScript Printing *postscript-printing* 788 *E455* *E456* *E457* *E624* 789Provided you have enough disk space there should be no problems generating a 790PostScript file. You need to have the runtime files correctly installed (if 791you can find the help files, they probably are). 792 793There are currently a number of limitations with PostScript printing: 794 795- 'printfont' - The font name is ignored (the Courier family is always used - 796 it should be available on all PostScript printers) but the font size is 797 used. 798 799- 'printoptions' - The duplex setting is used when generating PostScript 800 output, but it is up to the printer to take notice of the setting. If the 801 printer does not support duplex printing then it should be silently ignored. 802 Some printers, however, don't print at all. 803 804- 8-bit support - While a number of 8-bit print character encodings are 805 supported it is possible that some characters will not print. Whether a 806 character will print depends on the font in the printer knowing the 807 character. Missing characters will be replaced with an upside down question 808 mark, or a space if that character is also not known by the font. It may be 809 possible to get all the characters in an encoding to print by installing a 810 new version of the Courier font family. 811 812- Multi-byte support - Currently VIM will try to convert multi-byte characters 813 to the 8-bit encoding specified by 'printencoding' (or latin1 if it is 814 empty). Any characters that are not successfully converted are shown as 815 unknown characters. Printing will fail if VIM cannot convert the multi-byte 816 to the 8-bit encoding. 817 818 8193.2 Custom 8-bit Print Character Encodings *postscript-print-encoding* 820 *E618* *E619* 821To use your own print character encoding when printing 8-bit character data 822you need to define your own PostScript font encoding vector. Details on how 823to to define a font encoding vector is beyond the scope of this help file, but 824you can find details in the PostScript Language Reference Manual, 3rd Edition, 825published by Addison-Wesley and available in PDF form at 826http://www.adobe.com/. The following describes what you need to do for VIM to 827locate and use your print character encoding. 828 829i. Decide on a unique name for your encoding vector, one that does not clash 830 with any of the recognized or standard encoding names that VIM uses (see 831 |encoding-names| for a list), and that no one else is likely to use. 832ii. Copy $VIMRUNTIME/print/latin1.ps to the print subdirectory in your 833 'runtimepath' and rename it with your unique name. 834iii. Edit your renamed copy of latin1.ps, replacing all occurrences of latin1 835 with your unique name (don't forget the line starting %%Title:), and 836 modify the array of glyph names to define your new encoding vector. The 837 array must have exactly 256 entries or you will not be able to print! 838iv. Within VIM, set 'printencoding' to your unique encoding name and then 839 print your file. VIM will now use your custom print character encoding. 840 841VIM will report an error with the resource file if you change the order or 842content of the first 3 lines, other than the name of the encoding on the line 843starting %%Title: or the version number on the line starting %%Version:. 844 845[Technical explanation for those that know PostScript - VIM looks for a file 846with the same name as the encoding it will use when printing. The file 847defines a new PostScript Encoding resource called /VIM-name, where name is the 848print character encoding VIM will use.] 849 850 8513.3 PostScript Printing Troubleshooting *postscript-print-trouble* 852 *E621* 853Usually the only sign of a problem when printing with PostScript is that your 854printout does not appear. If you are lucky you may get a printed page that 855tells you the PostScript operator that generated the error that prevented the 856print job completing. 857 858There are a number of possible causes as to why the printing may have failed: 859 860- Wrong version of the prolog resource file. The prolog resource file 861 contains some PostScript that VIM needs to be able to print. Each version 862 of VIM needs one particular version. Make sure you have correctly installed 863 the runtime files, and don't have any old versions of a file called prolog 864 in the print directory in your 'runtimepath' directory. 865 866- Paper size. Some PostScript printers will abort printing a file if they do 867 not support the requested paper size. By default VIM uses A4 paper. Find 868 out what size paper your printer normally uses and set the appropriate paper 869 size with 'printoptions'. If you cannot find the name of the paper used, 870 measure a sheet and compare it with the table of supported paper sizes listed 871 for 'printoptions', using the paper that is closest in both width AND height. 872 Note: The dimensions of actual paper may vary slightly from the ones listed. 873 If there is no paper listed close enough, then you may want to try psresize 874 from PSUtils, discussed below. 875 876- Two-sided printing (duplex). Normally a PostScript printer that does not 877 support two-sided printing will ignore any request to do it. However, some 878 printers may abort the job altogether. Try printing with duplex turned off. 879 Note: Duplex prints can be achieved manually using PS utils - see below. 880 881- Collated printing. As with Duplex printing, most PostScript printers that 882 do not support collating printouts will ignore a request to do so. Some may 883 not. Try printing with collation turned off. 884 885- Syntax highlighting. Some print management code may prevent the generated 886 PostScript file from being printed on a black and white printer when syntax 887 highlighting is turned on, even if solid black is the only color used. Try 888 printing with syntax highlighting turned off. 889 890A safe printoptions setting to try is: > 891 892 :set printoptions=paper:A4,duplex:off,collate:n,syntax:n 893 894Replace "A4" with the paper size that best matches your printer paper. 895 896 8973.4 PostScript Utilities *postscript-print-util* 898 8993.4.1 Ghostscript 900 901Ghostscript is a PostScript and PDF interpreter that can be used to display 902and print on non-PostScript printers PostScript and PDF files. It can also 903generate PDF files from PostScript. 904 905Ghostscript will run on a wide variety of platforms. 906 907There are three available versions: 908 909- AFPL Ghostscript (formerly Aladdin Ghostscript) which is free for 910 non-commercial use. It can be obtained from: 911 912 http://www.cs.wisc.edu/~ghost/ 913 914- GNU Ghostscript which is available under the GNU General Public License. It 915 can be obtained from: 916 917 ftp://mirror.cs.wisc.edu/pub/mirrors/ghost/gnu/ 918 919- A commercial version for inclusion in commercial products. 920 921Additional information on Ghostscript can also be found at: 922 923 http://www.ghostscript.com/ 924 925Support for a number of non PostScript printers is provided in the 926distribution as standard, but if you cannot find support for your printer 927check the Ghostscript site for other printers not included by default. 928 929 9303.4.2 Ghostscript Previewers. 931 932The interface to Ghostscript is very primitive so a number of graphical front 933ends have been created. These allow easier PostScript file selection, 934previewing at different zoom levels, and printing. Check supplied 935documentation for full details. 936 937X11 938 939- Ghostview. Obtainable from: 940 941 http://www.cs.wisc.edu/~ghost/gv/ 942 943- gv. Derived from Ghostview. Obtainable from: 944 945 http://wwwthep.physik.uni-mainz.de/~plass/gv/ 946 947 Copies (possibly not the most recent) can be found at: 948 949 http://www.cs.wisc.edu/~ghost/gv/ 950 951OpenVMS 952 953- Is apparently supported in the main code now (untested). See: 954 955 http://wwwthep.physik.uni-mainz.de/~plass/gv/ 956 957Windows and OS/2 958 959- GSview. Obtainable from: 960 961 http://www.cs.wisc.edu/~ghost/gsview/ 962 963DOS 964 965- ps_view. Obtainable from: 966 967 ftp://ftp.pg.gda.pl/pub/TeX/support/ps_view/ 968 ftp://ftp.dante.de/tex-archive/support/ps_view/ 969 970Linux 971 972- GSview. Linux version of the popular Windows and OS/2 previewer. 973 Obtainable from: 974 975 http://www.cs.wisc.edu/~ghost/gsview/ 976 977- BMV. Different from Ghostview and gv in that it doesn't use X but svgalib. 978 Obtainable from: 979 980 ftp://sunsite.unc.edu/pub/Linux/apps/graphics/viewers/svga/bmv-1.2.tgz 981 982 9833.4.3 PSUtils 984 985PSUtils is a collection of utility programs for manipulating PostScript 986documents. Binary distributions are available for many platforms, as well as 987the full source. PSUtils can be found at: 988 989 http://knackered.org/angus/psutils 990 991The utilities of interest include: 992 993- psnup. Convert PS files for N-up printing. 994- psselect. Select page range and order of printing. 995- psresize. Change the page size. 996- psbook. Reorder and lay out pages ready for making a book. 997 998The output of one program can be used as the input to the next, allowing for 999complex print document creation. 1000 1001 1002N-UP PRINTING 1003 1004The psnup utility takes an existing PostScript file generated from VIM and 1005convert it to an n-up version. The simplest way to create a 2-up printout is 1006to first create a PostScript file with: > 1007 1008 :hardcopy > test.ps 1009 1010Then on your command line execute: > 1011 1012 psnup -n 2 test.ps final.ps 1013 1014Note: You may get warnings from some Ghostscript previewers for files produced 1015by psnup - these may safely be ignored. 1016 1017Finally print the file final.ps to your PostScript printer with your 1018platform's print command. (You will need to delete the two PostScript files 1019afterwards yourself.) 'printexpr' could be modified to perform this extra 1020step before printing. 1021 1022 1023ALTERNATE DUPLEX PRINTING 1024 1025It is possible to achieve a poor man's version of duplex printing using the PS 1026utility psselect. This utility has options -e and -o for printing just the 1027even or odd pages of a PS file respectively. 1028 1029First generate a PS file with the 'hardcopy' command, then generate a new 1030files with all the odd and even numbered pages with: > 1031 1032 psselect -o test.ps odd.ps 1033 psselect -e test.ps even.ps 1034 1035Next print odd.ps with your platform's normal print command. Then take the 1036print output, turn it over and place it back in the paper feeder. Now print 1037even.ps with your platform's print command. All the even pages should now 1038appear on the back of the odd pages. 1039 1040There a couple of points to bear in mind: 1041 10421. Position of the first page. If the first page is on top of the printout 1043 when printing the odd pages then you need to reverse the order that the odd 1044 pages are printed. This can be done with the -r option to psselect. This 1045 will ensure page 2 is printed on the back of page 1. 1046 Note: it is better to reverse the odd numbered pages rather than the even 1047 numbered in case there are an odd number of pages in the original PS file. 1048 10492. Paper flipping. When turning over the paper with the odd pages printed on 1050 them you may have to either flip them horizontally (along the long edge) or 1051 vertically (along the short edge), as well as possibly rotating them 180 1052 degrees. All this depends on the printer - it will be more obvious for 1053 desktop ink jets than for small office laser printers where the paper path 1054 is hidden from view. 1055 1056 10573.5 Formfeed Characters *printing-formfeed* 1058 1059By default VIM does not do any special processing of |formfeed| control 1060characters. Setting the 'printoptions' formfeed item will make VIM recognize 1061formfeed characters and continue printing the current line at the beginning 1062of the first line on a new page. The use of formfeed characters provides 1063rudimentary print control but there are certain things to be aware of. 1064 1065VIM will always start printing a line (including a line number if enabled) 1066containing a formfeed character, even if it is the first character on the 1067line. This means if a line starting with a formfeed character is the first 1068line of a page then VIM will print a blank page. 1069 1070Since the line number is printed at the start of printing the line containing 1071the formfeed character, the remainder of the line printed on the new page 1072will not have a line number printed for it (in the same way as the wrapped 1073lines of a long line when wrap in 'printoptions' is enabled). 1074 1075If the formfeed character is the last character on a line, then printing will 1076continue on the second line of the new page, not the first. This is due to 1077VIM processing the end of the line after the formfeed character and moving 1078down a line to continue printing. 1079 1080Due to the points made above it is recommended that when formfeed character 1081processing is enabled, printing of line numbers is disabled, and that form 1082feed characters are not the last character on a line. Even then you may need 1083to adjust the number of lines before a formfeed character to prevent 1084accidental blank pages. 1085 1086============================================================================== 10874. Using Vim like less or more *less* 1088 1089If you use the less or more program to view a file, you don't get syntax 1090highlighting. Thus you would like to use Vim instead. You can do this by 1091using the shell script "$VIMRUNTIME/macros/less.sh". 1092 1093This shell script uses the Vim script "$VIMRUNTIME/macros/less.vim". It sets 1094up mappings to simulate the commands that less supports. Otherwise, you can 1095still use the Vim commands. 1096 1097This isn't perfect. For example, when viewing a short file Vim will still use 1098the whole screen. But it works good enough for most uses, and you get syntax 1099highlighting. 1100 1101The "h" key will give you a short overview of the available commands. 1102 1103 vim:tw=78:ts=8:ft=help:norl: 1104