1*various.txt* For Vim version 7.0aa. Last change: 2004 Jun 14 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} 575 Search all help text files and make a list of lines 576 in which {pattern} matches. Jumps to the first match. 577 You can navigate through the matches with the 578 |quickfix| commands, e.g., |:cnext| to jump to the 579 next one. Or use |:cwindow| to get the list of 580 matches in the quickfix window. 581 {pattern} is used as a Vim regexp |pattern|. 582 'ignorecase' is not used, add "\c" to ignore case. 583 Example for case sensitive search: > 584 :helpgrep Uganda 585< Example for case ignoring search: > 586 :helpgrep uganda\c 587< Cannot be followed by another command, everything is 588 used as part of the pattern. But you can use 589 |:execute| when needed. 590 Compressed help files will not be searched (Debian 591 compresses the help files). 592 {not in Vi} 593 594 595When no argument is given to |:help| the file given with the 'helpfile' option 596will be opened. Otherwise the specified tag is searched for in all "doc/tags" 597files in the directories specified in the 'runtimepath' option. 598 599The initial height of the help window can be set with the 'helpheight' option 600(default 20). 601 602Jump to specific subjects by using tags. This can be done in two ways: 603- Use the "CTRL-]" command while standing on the name of a command or option. 604 This only works when the tag is a keyword. "<C-Leftmouse>" and 605 "g<LeftMouse>" work just like "CTRL-]". 606- use the ":ta {subject}" command. This also works with non-keyword 607 characters. 608 609Use CTRL-T or CTRL-O to jump back. 610Use ":q" to close the help window. 611 612If there are several matches for an item you are looking for, this is how you 613can jump to each one of them: 6141. Open a help window 6152. Use the ":tag" command with a slash prepended to the tag. E.g.: > 616 :tag /min 6173. Use ":tnext" to jump to the next matching tag. 618 619It is possible to add help files for plugins and other items. You don't need 620to change the distributed help files for that. See |add-local-help|. 621 622To write a local help file, see |write-local-help|. 623 624Note that the title lines from the local help files are automagically added to 625the "LOCAL ADDITIONS" section in the "help.txt" help file |local-additions|. 626This is done when viewing the file in Vim, the file itself is not changed. It 627is done by going through all help files and obtaining the first line of each 628file. The files in $VIMRUNTIME/doc are skipped. 629 630 *help-xterm-window* 631If you want to have the help in another xterm window, you could use this 632command: > 633 :!xterm -e vim +help & 634< 635 636 *:helpfind* *:helpf* 637:helpf[ind] Like |:help|, but use a dialog to enter the argument. 638 Only for backwards compatibility. It now executes the 639 ToolBar.FindHelp menu entry instead of using a builtin 640 dialog. {only when compiled with |+GUI_GTK|} 641< {not in Vi} 642 643 *:helpt* *:helptags* 644 *E154* *E150* *E151* *E152* *E153* *E670* 645:helpt[ags] {dir} Generate the help tags file(s) for directory {dir}. 646 All "*.txt" and "*.??x" files in the directory are 647 scanned for a help tag definition in between stars. 648 The "*.??x" files are for translated docs, they 649 generate the "tags-??" file, see |help-translated|. 650 The generated tags files are sorted. 651 When there are duplicates an error message is given. 652 An existing tags file is silently overwritten. 653 To rebuild the help tags in the runtime directory 654 (requires write permission there): > 655 :helptags $VIMRUNTIME/doc 656< {not in Vi} 657 658 659TRANSLATED HELP *help-translated* 660 661It is possible to add translated help files, next to the original English help 662files. Vim will search for all help in "doc" directories in 'runtimepath'. 663This is only available when compiled with the |+multi_lang| feature. 664 665A set of translated help files consists of these files: 666 667 help.abx 668 howto.abx 669 ... 670 tags-ab 671 672"ab" is the two-letter language code. Thus for Italian the names are: 673 674 help.itx 675 howto.itx 676 ... 677 tags-it 678 679The 'helplang' option can be set to the preferred language(s). The default is 680set according to the environment. Vim will first try to find a matching tag 681in the preferred language(s). English is used when it cannot be found. 682 683To find a tag in a specific language, append "@ab" to a tag, where "ab" is the 684two-letter language code. Example: > 685 :he user-manual@it 686 :he user-manual@en 687The first one finds the Italian user manual, even when 'helplang' is empty. 688The second one finds the English user manual, even when 'helplang' is set to 689"it". 690 691When using command-line completion for the ":help" command, the "@en" 692extention is only shown when a tag exists for multiple languages. When the 693tag only exists for English "@en" is omitted. 694 695When using |CTRL-]| or ":help!" in a non-English help file Vim will try to 696find the tag in the same language. If not found then 'helplang' will be used 697to select a language. 698 699Help files must use latin1 or utf-8 encoding. Vim assumes the encoding is 700utf-8 when finding non-ASCII characters in the first line. Thus you must 701translate the header with "For Vim version". 702 703The same encoding must be used for the help files of one language in one 704directory. You can use a different encoding for different languages and use 705a different encoding for help files of the same language but in a different 706directory. 707 708Hints for translators: 709- Do not translate the tags. This makes it possible to use 'helplang' to 710 specify the preferred language. You may add new tags in your language. 711- When you do not translate a part of a file, add tags to the English version, 712 using the "tag@en" notation. 713- Make a package with all the files and the tags file available for download. 714 Users can drop it in one of the "doc" directories and start use it. 715 Report this to Bram, so that he can add a link on www.vim.org. 716- Use the |:helptags| command to generate the tags files. It will find all 717 languages in the specified directory. 718 719============================================================================== 7203. Printing *printing* 721 722On MS-Windows Vim can print your text on any installed printer. On other 723systems a PostScript file is produced. This can be directly sent to a 724PostScript printer. For other printers a program like ghostscript needs to be 725used. 726 7273.1 PostScript Printing |postscript-printing| 7283.2 PostScript Printing Encoding |postscript-print-encoding| 7293.3 PostScript Printing Troubleshooting |postscript-print-trouble| 7303.4 PostScript Utilities |postscript-print-util| 7313.5 Formfeed Characters |printing-formfeed| 732 733{not in Vi} 734{only available when compiled with |+printer| feature} 735 736 *:ha* *:hardcopy* *E237* *E238* *E324* 737:[range]ha[rdcopy][!] [arguments] 738 Send [range] lines (default whole file) to the 739 printer. 740 741 On MS-Windows a dialog is displayed to allow selection 742 of printer, paper size etc. To skip the dialog, use 743 the [!]. In this case the printer defined by 744 'printdevice' is used, or, if 'printdevice' is empty, 745 the system default printer. 746 747 For systems other than MS-Windows, PostScript is 748 written in a temp file and 'printexpr' is used to 749 actually print it. Then [arguments] can be used by 750 'printexpr' through |v:cmdarg|. Otherwise [arguments] 751 is ignored. 'printoptions' can be used to specify 752 paper size, duplex, etc. 753 754:[range]ha[rdcopy][!] >{filename} 755 As above, but write the resulting PostScript in file 756 {filename}. 757 Things like "%" are expanded |cmdline-special| 758 Careful: An existing file is silently overwritten. 759 {only available when compiled with the |+postscript| 760 feature} 761 On MS-Windows use the "print to file" feature of the 762 printer driver. 763 764Progress is displayed during printing as a page number and a percentage. To 765abort printing use the interrupt key (CTRL-C or, on MS-systems, CTRL-Break). 766 767Printer output is controlled by the 'printfont' and 'printoptions' options. 768'printheader' specifies the format of a page header. 769 770The printed file is always limited to the selected margins, irrespective of 771the current window's 'wrap' or 'linebreak' settings. The "wrap" item in 772'printoptions' can be used to switch wrapping off. 773The current highlighting colors are used in the printout, with the following 774considerations: 7751) The normal background is always rendered as white (i.e. blank paper.) 7762) White text or the default foreground is rendered as black, so that it shows 777 up! 7783) If 'background' is "dark", then the colours are darkened to compensate for 779 the fact that otherwise they would be too bright to show up clearly on 780 white paper. 781 782 7833.1 PostScript Printing *postscript-printing* 784 *E455* *E456* *E457* *E624* 785Provided you have enough disk space there should be no problems generating a 786PostScript file. You need to have the runtime files correctly installed (if 787you can find the help files, they probably are). 788 789There are currently a number of limitations with PostScript printing: 790 791- 'printfont' - The font name is ignored (the Courier family is always used - 792 it should be available on all PostScript printers) but the font size is 793 used. 794 795- 'printoptions' - The duplex setting is used when generating PostScript 796 output, but it is up to the printer to take notice of the setting. If the 797 printer does not support duplex printing then it should be silently ignored. 798 Some printers, however, don't print at all. 799 800- 8-bit support - While a number of 8-bit print character encodings are 801 supported it is possible that some characters will not print. Whether a 802 character will print depends on the font in the printer knowing the 803 character. Missing characters will be replaced with an upside down question 804 mark, or a space if that character is also not known by the font. It may be 805 possible to get all the characters in an encoding to print by installing a 806 new version of the Courier font family. 807 808- Multi-byte support - Currently VIM will try to convert multi-byte characters 809 to the 8-bit encoding specified by 'printencoding' (or latin1 if it is 810 empty). Any characters that are not successfully converted are shown as 811 unknown characters. Printing will fail if VIM cannot convert the multi-byte 812 to the 8-bit encoding. 813 814 8153.2 Custom 8-bit Print Character Encodings *postscript-print-encoding* 816 *E618* *E619* 817To use your own print character encoding when printing 8-bit character data 818you need to define your own PostScript font encoding vector. Details on how 819to to define a font encoding vector is beyond the scope of this help file, but 820you can find details in the PostScript Language Reference Manual, 3rd Edition, 821published by Addison-Wesley and available in PDF form at 822http://www.adobe.com/. The following describes what you need to do for VIM to 823locate and use your print character encoding. 824 825i. Decide on a unique name for your encoding vector, one that does not clash 826 with any of the recognized or standard encoding names that VIM uses (see 827 |encoding-names| for a list), and that no one else is likely to use. 828ii. Copy $VIMRUNTIME/print/latin1.ps to the print subdirectory in your 829 'runtimepath' and rename it with your unique name. 830iii. Edit your renamed copy of latin1.ps, replacing all occurrences of latin1 831 with your unique name (don't forget the line starting %%Title:), and 832 modify the array of glyph names to define your new encoding vector. The 833 array must have exactly 256 entries or you will not be able to print! 834iv. Within VIM, set 'printencoding' to your unique encoding name and then 835 print your file. VIM will now use your custom print character encoding. 836 837VIM will report an error with the resource file if you change the order or 838content of the first 3 lines, other than the name of the encoding on the line 839starting %%Title: or the version number on the line starting %%Version:. 840 841[Technical explanation for those that know PostScript - VIM looks for a file 842with the same name as the encoding it will use when printing. The file 843defines a new PostScript Encoding resource called /VIM-name, where name is the 844print character encoding VIM will use.] 845 846 8473.3 PostScript Printing Troubleshooting *postscript-print-trouble* 848 *E621* 849Usually the only sign of a problem when printing with PostScript is that your 850printout does not appear. If you are lucky you may get a printed page that 851tells you the PostScript operator that generated the error that prevented the 852print job completing. 853 854There are a number of possible causes as to why the printing may have failed: 855 856- Wrong version of the prolog resource file. The prolog resource file 857 contains some PostScript that VIM needs to be able to print. Each version 858 of VIM needs one particular version. Make sure you have correctly installed 859 the runtime files, and don't have any old versions of a file called prolog 860 in the print directory in your 'runtimepath' directory. 861 862- Paper size. Some PostScript printers will abort printing a file if they do 863 not support the requested paper size. By default VIM uses A4 paper. Find 864 out what size paper your printer normally uses and set the appropriate paper 865 size with 'printoptions'. If you cannot find the name of the paper used, 866 measure a sheet and compare it with the table of supported paper sizes listed 867 for 'printoptions', using the paper that is closest in both width AND height. 868 Note: The dimensions of actual paper may vary slightly from the ones listed. 869 If there is no paper listed close enough, then you may want to try psresize 870 from PSUtils, discussed below. 871 872- Two-sided printing (duplex). Normally a PostScript printer that does not 873 support two-sided printing will ignore any request to do it. However, some 874 printers may abort the job altogether. Try printing with duplex turned off. 875 Note: Duplex prints can be achieved manually using PS utils - see below. 876 877- Collated printing. As with Duplex printing, most PostScript printers that 878 do not support collating printouts will ignore a request to do so. Some may 879 not. Try printing with collation turned off. 880 881- Syntax highlighting. Some print management code may prevent the generated 882 PostScript file from being printed on a black and white printer when syntax 883 highlighting is turned on, even if solid black is the only color used. Try 884 printing with syntax highlighting turned off. 885 886A safe printoptions setting to try is: > 887 888 :set printoptions=paper:A4,duplex:off,collate:n,syntax:n 889 890Replace "A4" with the paper size that best matches your printer paper. 891 892 8933.4 PostScript Utilities *postscript-print-util* 894 8953.4.1 Ghostscript 896 897Ghostscript is a PostScript and PDF interpreter that can be used to display 898and print on non-PostScript printers PostScript and PDF files. It can also 899generate PDF files from PostScript. 900 901Ghostscript will run on a wide variety of platforms. 902 903There are three available versions: 904 905- AFPL Ghostscript (formerly Aladdin Ghostscript) which is free for 906 non-commercial use. It can be obtained from: 907 908 http://www.cs.wisc.edu/~ghost/ 909 910- GNU Ghostscript which is available under the GNU General Public License. It 911 can be obtained from: 912 913 ftp://mirror.cs.wisc.edu/pub/mirrors/ghost/gnu/ 914 915- A commercial version for inclusion in commercial products. 916 917Additional information on Ghostscript can also be found at: 918 919 http://www.ghostscript.com/ 920 921Support for a number of non PostScript printers is provided in the 922distribution as standard, but if you cannot find support for your printer 923check the Ghostscript site for other printers not included by default. 924 925 9263.4.2 Ghostscript Previewers. 927 928The interface to Ghostscript is very primitive so a number of graphical front 929ends have been created. These allow easier PostScript file selection, 930previewing at different zoom levels, and printing. Check supplied 931documentation for full details. 932 933X11 934 935- Ghostview. Obtainable from: 936 937 http://www.cs.wisc.edu/~ghost/gv/ 938 939- gv. Derived from Ghostview. Obtainable from: 940 941 http://wwwthep.physik.uni-mainz.de/~plass/gv/ 942 943 Copies (possibly not the most recent) can be found at: 944 945 http://www.cs.wisc.edu/~ghost/gv/ 946 947OpenVMS 948 949- Is apparently supported in the main code now (untested). See: 950 951 http://wwwthep.physik.uni-mainz.de/~plass/gv/ 952 953Windows and OS/2 954 955- GSview. Obtainable from: 956 957 http://www.cs.wisc.edu/~ghost/gsview/ 958 959DOS 960 961- ps_view. Obtainable from: 962 963 ftp://ftp.pg.gda.pl/pub/TeX/support/ps_view/ 964 ftp://ftp.dante.de/tex-archive/support/ps_view/ 965 966Linux 967 968- GSview. Linux version of the popular Windows and OS/2 previewer. 969 Obtainable from: 970 971 http://www.cs.wisc.edu/~ghost/gsview/ 972 973- BMV. Different from Ghostview and gv in that it doesn't use X but svgalib. 974 Obtainable from: 975 976 ftp://sunsite.unc.edu/pub/Linux/apps/graphics/viewers/svga/bmv-1.2.tgz 977 978 9793.4.3 PSUtils 980 981PSUtils is a collection of utility programs for manipulating PostScript 982documents. Binary distributions are available for many platforms, as well as 983the full source. PSUtils can be found at: 984 985 http://knackered.org/angus/psutils 986 987The utilities of interest include: 988 989- psnup. Convert PS files for N-up printing. 990- psselect. Select page range and order of printing. 991- psresize. Change the page size. 992- psbook. Reorder and lay out pages ready for making a book. 993 994The output of one program can be used as the input to the next, allowing for 995complex print document creation. 996 997 998N-UP PRINTING 999 1000The psnup utility takes an existing PostScript file generated from VIM and 1001convert it to an n-up version. The simplest way to create a 2-up printout is 1002to first create a PostScript file with: > 1003 1004 :hardcopy > test.ps 1005 1006Then on your command line execute: > 1007 1008 psnup -n 2 test.ps final.ps 1009 1010Note: You may get warnings from some Ghostscript previewers for files produced 1011by psnup - these may safely be ignored. 1012 1013Finally print the file final.ps to your PostScript printer with your 1014platform's print command. (You will need to delete the two PostScript files 1015afterwards yourself.) 'printexpr' could be modified to perform this extra 1016step before printing. 1017 1018 1019ALTERNATE DUPLEX PRINTING 1020 1021It is possible to achieve a poor man's version of duplex printing using the PS 1022utility psselect. This utility has options -e and -o for printing just the 1023even or odd pages of a PS file respectively. 1024 1025First generate a PS file with the 'hardcopy' command, then generate a new 1026files with all the odd and even numbered pages with: > 1027 1028 psselect -o test.ps odd.ps 1029 psselect -e test.ps even.ps 1030 1031Next print odd.ps with your platform's normal print command. Then take the 1032print output, turn it over and place it back in the paper feeder. Now print 1033even.ps with your platform's print command. All the even pages should now 1034appear on the back of the odd pages. 1035 1036There a couple of points to bear in mind: 1037 10381. Position of the first page. If the first page is on top of the printout 1039 when printing the odd pages then you need to reverse the order that the odd 1040 pages are printed. This can be done with the -r option to psselect. This 1041 will ensure page 2 is printed on the back of page 1. 1042 Note: it is better to reverse the odd numbered pages rather than the even 1043 numbered in case there are an odd number of pages in the original PS file. 1044 10452. Paper flipping. When turning over the paper with the odd pages printed on 1046 them you may have to either flip them horizontally (along the long edge) or 1047 vertically (along the short edge), as well as possibly rotating them 180 1048 degrees. All this depends on the printer - it will be more obvious for 1049 desktop ink jets than for small office laser printers where the paper path 1050 is hidden from view. 1051 1052 10533.5 Formfeed Characters *printing-formfeed* 1054 1055By default VIM does not do any special processing of |formfeed| control 1056characters. Setting the 'printoptions' formfeed item will make VIM recognize 1057formfeed characters and continue printing the current line at the beginning 1058of the first line on a new page. The use of formfeed characters provides 1059rudimentary print control but there are certain things to be aware of. 1060 1061VIM will always start printing a line (including a line number if enabled) 1062containing a formfeed character, even if it is the first character on the 1063line. This means if a line starting with a formfeed character is the first 1064line of a page then VIM will print a blank page. 1065 1066Since the line number is printed at the start of printing the line containing 1067the formfeed character, the remainder of the line printed on the new page 1068will not have a line number printed for it (in the same way as the wrapped 1069lines of a long line when wrap in 'printoptions' is enabled). 1070 1071If the formfeed character is the last character on a line, then printing will 1072continue on the second line of the new page, not the first. This is due to 1073VIM processing the end of the line after the formfeed character and moving 1074down a line to continue printing. 1075 1076Due to the points made above it is recommended that when formfeed character 1077processing is enabled, printing of line numbers is disabled, and that form 1078feed characters are not the last character on a line. Even then you may need 1079to adjust the number of lines before a formfeed character to prevent 1080accidental blank pages. 1081 1082============================================================================== 10834. Using Vim like less or more *less* 1084 1085If you use the less or more program to view a file, you don't get syntax 1086highlighting. Thus you would like to use Vim instead. You can do this by 1087using the shell script "$VIMRUNTIME/macros/less.sh". 1088 1089This shell script uses the Vim script "$VIMRUNTIME/macros/less.vim". It sets 1090up mappings to simulate the commands that less supports. Otherwise, you can 1091still use the Vim commands. 1092 1093This isn't perfect. For example, when viewing a short file Vim will still use 1094the whole screen. But it works good enough for most uses, and you get syntax 1095highlighting. 1096 1097The "h" key will give you a short overview of the available commands. 1098 1099 vim:tw=78:ts=8:ft=help:norl: 1100