Mercurial > vim
diff runtime/doc/various.txt @ 7:3fc0f57ecb91 v7.0001
updated for version 7.0001
| author | vimboss |
|---|---|
| date | Sun, 13 Jun 2004 20:20:40 +0000 |
| parents | |
| children | 7edf9b6e4c36 |
line wrap: on
line diff
new file mode 100644 --- /dev/null +++ b/runtime/doc/various.txt @@ -0,0 +1,1098 @@ +*various.txt* For Vim version 7.0aa. Last change: 2004 May 01 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Various commands *various* + +1. Various commands |various-cmds| +2. Online help |online-help| +3. Printing |printing| +4. Using Vim like less or more |less| + +============================================================================== +1. Various commands *various-cmds* + + *CTRL-L* +CTRL-L Clear and redraw the screen (later). + + *:redr* *:redraw* +:redr[aw][!] Redraw the screen right now. When ! is included it is + cleared first. + Useful to update the screen halfway executing a script + or function. Also when halfway a mapping and + 'lazyredraw' is set. + + *:redraws* *:redrawstatus* +:redraws[tatus][!] Redraw the status line of the current window. When ! + is included all status lines are redrawn. + Useful to update the status line(s) when 'statusline' + includes an item that doesn't cause automatic + updating. + + *N<Del>* +<Del> When entering a number: Remove the last digit. + Note: if you like to use <BS> for this, add this + mapping to your .vimrc: > + :map CTRL-V <BS> CTRL-V <Del> +< See |:fixdel| if your <Del> key does not do what you + want. + +:as[cii] or *ga* *:as* *:ascii* +ga Print the ascii value of the character under the + cursor in decimal, hexadecimal and octal. For + example, when the cursor is on a 'R': + <R> 82, Hex 52, Octal 122 ~ + When the character is a non-standard ASCII character, + but printable according to the 'isprint' option, the + non-printable version is also given. When the + character is larger than 127, the <M-x> form is also + printed. For example: + <~A> <M-^A> 129, Hex 81, Octal 201 ~ + <p> <|~> <M-~> 254, Hex fe, Octal 376 ~ + (where <p> is a special character) + The <Nul> character in a file is stored internally as + <NL>, but it will be shown as: + <^@> 0, Hex 00, Octal 000 ~ + Mnemonic: Get Ascii value. {not in Vi} + + *g8* +g8 Print the hex values of the bytes used in the + character under the cursor, assuming it is in |UTF-8| + encoding. This also shows composing characters. + Example of a character with three composing + characters: + e0 b8 81 + e0 b8 b9 + e0 b9 89 ~ + {not in Vi} + + *:p* *:pr* *:print* +:[range]p[rint] Print [range] lines (default current line). + Note: If you are looking for a way to print your text + file, you need an external program for that. In the + GUI you can use the File.Print menu entry. + (For printing on paper see |:hardcopy|) + +:[range]p[rint] {count} + Print {count} lines, starting with [range] (default + current line |cmdline-ranges|). + + *:P* *:Print* +:[range]P[rint] [count] + Just as ":print". Was apparently added to Vi for + people that keep the shift key pressed too long... + + *:l* *:list* +:[range]l[ist] [count] + Same as :print, but display unprintable characters + with '^'. + + *:nu* *:number* +:[range]nu[mber] [count] + Same as :print, but precede each line with its line + number. (See also 'highlight' option). + + *:#* +:[range]# [count] synonym for :number. + + *:z* *E144* +:{range}z[+-^.=]{count} Display several lines of text surrounding the line + specified with {range}, or around the current line + if there is no {range}. If there is a {count}, that's + how many lines you'll see; otherwise, the current + window size is used. + + :z can be used either alone or followed by any of + several punctuation marks. These have the following + effect: + + mark first line last line new location ~ + ---- ---------- --------- ------------ + + current line 1 scr forward 1 scr forward + - 1 scr back current line current line + ^ 2 scr back 1 scr back 1 scr back + . 1/2 scr back 1/2 scr fwd 1/2 src fwd + = 1/2 src back 1/2 scr fwd current line + + Specifying no mark at all is the same as "+". + If the mark is "=", a line of dashes is printed + around the current line. + +:{range}z#[+-^.=]{count} *:z#* + Like ":z", but number the lines. + {not in all versions of Vi, not with these arguments} + + *:=* +:= Print the last line number. + +:{range}= Prints the last line number in {range}. For example, + this prints the current line number: > + :.= + +:norm[al][!] {commands} *:norm* *:normal* + Execute Normal mode commands {commands}. This makes + it possible to execute Normal mode commands typed on + the command-line. {commands} is executed like it is + typed. For undo all commands are undone together. + If the [!] is given, mappings will not be used. + {commands} should be a complete command. If + {commands} does not finish a command, the last one + will be aborted as if <Esc> or <C-C> was typed. + The display isn't updated while ":normal" is busy. + This implies that an insert command must be completed + (to start Insert mode, see |:startinsert|). A ":" + command must be completed as well. + {commands} cannot start with a space. Put a 1 (one) + before it, 1 space is one space. + The 'insertmode' option is ignored for {commands}. + This command cannot be followed by another command, + since any '|' is considered part of the command. + This command can be used recursively, but the depth is + limited by 'maxmapdepth'. + When this command is called from a non-remappable + mapping |:noremap|, the argument can be mapped anyway. + An alternative is to use |:execute|, which uses an + expression as argument. This allows the use of + printable characters. Example: > + :exe "normal \<c-w>\<c-w>" +< {not in Vi, of course} + {not available when the |+ex_extra| feature was + disabled at compile time} + +:{range}norm[al][!] {commands} *:normal-range* + Execute Normal mode commands {commands} for each line + in the {range}. Before executing the {commands}, the + cursor is positioned in the first column of the range, + for each line. Otherwise it's the same as the + ":normal" command without a range. + {not in Vi} + Not available when |+ex_extra| feature was disabled at + compile time. + + *:sh* *:shell* *E371* +:sh[ell] This command starts a shell. When the shell exits + (after the "exit" command) you return to Vim. The + name for the shell command comes from 'shell' option. + *E360* + Note: This doesn't work when Vim on the Amiga was + started in QuickFix mode from a compiler, because the + compiler will have set stdin to a non-interactive + mode. + + *:!cmd* *:!* *E34* +:!{cmd} Execute {cmd} with the shell. See also the 'shell' + and 'shelltype' option. + Any '!' in {cmd} is replaced with the previous + external command (see also 'cpoptions'). But not when + there is a backslash before the '!', then that + backslash is removed. Example: ":!ls" followed by + ":!echo ! \! \\!" executes "echo ls ! \!". + After the command has been executed, the timestamp of + the current file is checked |timestamp|. + There cannot be a '|' in {cmd}, see |:bar|. + A newline character ends {cmd}, what follows is + interpreted as a following ":" command. However, if + there is a backslash before the newline it is removed + and {cmd} continues. It doesn't matter how many + backslashes are before the newline, only one is + removed. + On Unix the command normally runs in a non-interactive + shell. If you want an interactive shell to be used + (to use aliases) set 'shellcmdflag' to "-ic". + For Win32 also see |:!start|. + Vim redraws the screen after the command is finished, + because it may have printed any text. This requires a + hit-enter prompt, so that you can read any messages. + To avoid this use: > + :silent !{cmd} +< The screen is not redrawn then, thus you have to use + CTRL-L or ":redraw!" if the command did display + something. + Also see |shell-window|. + + *:!!* +:!! Repeat last ":!{cmd}". + + *:ve* *:version* +:ve[rsion] Print the version number of the editor. If the + compiler used understands "__DATE__" the compilation + date is mentioned. Otherwise a fixed release-date is + shown. + The following lines contain information about which + features were enabled when Vim was compiled. When + there is a preceding '+', the feature is included, + when there is a '-' it is excluded. To change this, + you have to edit feature.h and recompile Vim. + To check for this in an expression, see |has()|. + Here is an overview of the features. + The first column shows the smallest version in which + they are included: + T tiny + S small + N normal + B big + H huge + m manually enabled or depends on other features + (none) system dependent + Thus if a feature is marked with "N", it is included + in the normal, big and huge versions of Vim. + + *+feature-list* + *+ARP* Amiga only: ARP support included +B *+arabic* |Arabic| language support +N *+autocmd* |:autocmd|, automatic commands +m *+balloon_eval* |balloon-eval| support +N *+browse* |:browse| command +N *+builtin_terms* some terminals builtin |builtin-terms| +B *++builtin_terms* maximal terminals builtin |builtin-terms| +N *+byte_offset* support for 'o' flag in 'statusline' option, "go" + and ":goto" commands. +N *+cindent* |'cindent'|, C indenting +N *+clientserver* Unix and Win32: Remote invocation |clientserver| + *+clipboard* |clipboard| support +N *+cmdline_compl* command line completion |cmdline-completion| +N *+cmdline_hist* command line history |cmdline-history| +N *+cmdline_info* |'showcmd'| and |'ruler'| +N *+comments* |'comments'| support +N *+cryptv* encryption support |encryption| +B *+cscope* |cscope| support +N *+dialog_gui* Support for |:confirm| with GUI dialog. +N *+dialog_con* Support for |:confirm| with console dialog. +N *+dialog_con_gui* Support for |:confirm| with GUI and console dialog. +N *+diff* |vimdiff| and 'diff' +N *+digraphs* |digraphs| *E196* + *+dnd* Support for DnD into the "~ register |quote_~|. +B *+emacs_tags* |emacs-tags| files +N *+eval* expression evaluation |eval.txt| +N *+ex_extra* Vim's extra Ex commands: |:center|, |:left|, + |:normal|, |:retab| and |:right| +N *+extra_search* |'hlsearch'| and |'incsearch'| options. +B *+farsi* |farsi| language +N *+file_in_path* |gf|, |CTRL-W_f| and |<cfile>| +N *+find_in_path* include file searches: |[I|, |:isearch|, + |CTRL-W_CTRL-I|, |:checkpath|, etc. +N *+folding* |folding| + *+footer* |gui-footer| + *+fork* Unix only: |fork| shell commands +N *+gettext* message translations |multi-lang| + *+GUI_Athena* Unix only: Athena |GUI| + *+GUI_neXtaw* Unix only: neXtaw |GUI| + *+GUI_BeOS* BeOS only: BeOS |GUI| + *+GUI_GTK* Unix only: GTK+ |GUI| + *+GUI_Motif* Unix only: Motif |GUI| + *+GUI_Photon* QNX only: Photon |GUI| +m *+hangul_input* Hangul input support |hangul| + *+iconv* Compiled with the |iconv()| function, may have |/dyn| +N *+insert_expand* |insert_expand| Insert mode completion +N *+jumplist* |jumplist| +B *+keymap* |'keymap'| +B *+langmap* |'langmap'| +N *+libcall* |libcall()| +N *+linebreak* |'linebreak'|, |'breakat'| and |'showbreak'| +N *+lispindent* |'lisp'| +N *+listcmds* Vim commands for the list of buffers |buffer-hidden| + and argument list |:argdelete| +N *+localmap* Support for mappings local to a buffer |:map-local| +N *+menu* |:menu| +N *+mksession* |:mksession| +N *+modify_fname* |filename-modifiers| +N *+mouse* Mouse handling |mouse-using| +N *+mouseshape* |'mouseshape'| +B *+mouse_dec* Unix only: Dec terminal mouse handling |dec-mouse| +N *+mouse_gpm* Unix only: Linux console mouse handling |gpm-mouse| +B *+mouse_netterm* Unix only: netterm mouse handling |netterm-mouse| +N *+mouse_pterm* QNX only: pterm mouse handling |qnx-terminal| +N *+mouse_xterm* Unix only: xterm mouse handling |xterm-mouse| +B *+multi_byte* Korean and other languages |multibyte| + *+multi_byte_ime* Win32 input method for multibyte chars |multibyte-ime| +N *+multi_lang* non-English language support |multi-lang| +m *+netbeans_intg* |netbeans| +m *+ole* Win32 GUI only: |ole-interface| + *+osfiletype* Support for the 'osfiletype' option and filetype + checking in automatic commands. |autocmd-osfiletypes| +N *+path_extra* Up/downwards search in 'path' and 'tags' +m *+perl* Perl interface |perl|, may have |/dyn| + *+postscript* |:hardcopy| writes a PostScript file +N *+printer* |:hardcopy| command +m *+python* Python interface |python|, may have |/dyn| +N *+quickfix* |:make| and |quickfix| commands +B *+rightleft* Right to left typing |'rightleft'| +m *+ruby* Ruby interface |ruby|, may have |/dyn| +N *+scrollbind* |'scrollbind'| +B *+signs* |:sign| +N *+smartindent* |'smartindent'| +m *+sniff* SniFF interface |sniff| +N *+statusline* Options 'statusline', 'rulerformat' and special + formats of 'titlestring' and 'iconstring' +m *+sun_workshop* |workshop| +N *+syntax* Syntax highlighting |syntax| + *+system()* Unix only: opposite of |+fork| +N *+tag_binary* binary searching in tags file |tag-binary-search| +N *+tag_old_static* old method for static tags |tag-old-static| +m *+tag_any_white* any white space allowed in tags file |tag-any-white| +m *+tcl* Tcl interface |tcl|, may have |/dyn| + *+terminfo* uses |terminfo| instead of termcap +N *+termresponse* support for |t_RV| and |v:termresponse| +N *+textobjects* |text-objects| selection + *+tgetent* non-Unix only: able to use external termcap +N *+title* Setting the window title |'title'| +N *+toolbar* |gui-toolbar| +N *+user_commands* User-defined commands. |user-commands| +N *+viminfo* |'viminfo'| +N *+vertsplit* Vertically split windows |:vsplit| +N *+virtualedit* |'virtualedit'| +S *+visual* Visual mode |Visual-mode| +N *+visualextra* extra Visual mode commands |blockwise-operators| +N *+vreplace* |gR| and |gr| +N *+wildignore* |'wildignore'| +N *+wildmenu* |'wildmenu'| +S *+windows* more than one window +m *+writebackup* |'writebackup'| is default on +m *+xim* X input method |xim| + *+xfontset* X fontset support |xfontset| + *+xsmp* XSMP (X session management) support + *+xsmp_interact* interactive XSMP (X session management) support +N *+xterm_clipboard* Unix only: xterm clipboard handling +m *+xterm_save* save and restore xterm screen |xterm-screens| +N *+X11* Unix only: can restore window title |X11| + + */dyn* *E370* *E448* + To some of the features "/dyn" is added when the + feature is only available when the related library can + be dynamically loaded. + +:ve[rsion] {nr} Is now ignored. This was previously used to check the + version number of a .vimrc file. It was removed, + because you can now use the ":if" command for + version-dependent behavior. {not in Vi} + + *:redi* *:redir* +:redi[r][!] > {file} Redirect messages to file {file}. The messages which + are the output of commands are written to that file, + until redirection ends. The messages are also still + shown on the screen. When [!] is included, an + existing file is overwritten. When [!] is omitted, + and {file} exists, this command fails. + Only one ":redir" can be active at a time. Calls to + ":redir" will close any active redirection before + starting redirection to the new target. + To stop the messages and commands from being echoed to + the screen, put the commands in a function and call it + with ":silent call Function()". + {not in Vi} + +:redi[r] >> {file} Redirect messages to file {file}. Append if {file} + already exists. {not in Vi} + +:redi[r] @{a-zA-Z} Redirect messages to register {a-z}. Append to the + contents of the register if its name is given + uppercase {A-Z}. {not in Vi} + +:redi[r] @* Redirect messages to the clipboard. {not in Vi} + +:redi[r] @" Redirect messages to the unnamed register. {not in Vi} + +:redi[r] END End redirecting messages. {not in Vi} + + *:sil* *:silent* +:sil[ent][!] {command} Execute {command} silently. Normal messages will not + be given or added to the message history. + When [!] is added, error messages will also be + skipped, and commands and mappings will not be aborted + when an error is detected. |v:errmsg| is still set. + When [!] is not used, an error message will cause + further messages to be displayed normally. + Redirection, started with |:redir|, will continue as + usual, although there might be small differences. + This will allow redirecting the output of a command + without seeing it on the screen. Example: > + :redir >/tmp/foobar + :silent g/Aap/p + :redir END +< To execute a Normal mode command silently, use the + |:normal| command. For example, to search for a + string without messages: > + :silent exe "normal /path\<CR>" +< ":silent!" is useful to execute a command that may + fail, but the failure is to be ignored. Example: > + :let v:errmsg = "" + :silent! /^begin + :if v:errmsg != "" + : ... pattern was not found +< ":silent" will also avoid the hit-enter prompt. When + using this for an external command, this may cause the + screen to be messed up. Use |CTRL-L| to clean it up + then. + ":silent menu ..." defines a menu that will not echo a + Command-line command. The command will still produce + messages though. Use ":silent" in the command itself + to avoid that: ":silent menu .... :silent command". + + *:verb* *:verbose* +:[count]verb[ose] {command} + Execute {command} with 'verbose' set to [count]. If + [count] is omitted one is used. + The additional use of ":silent" makes messages + generated but not displayed. + The combination of ":silent" and ":verbose" can be + used to generate messages and check them with + |v:statusmsg| and friends. For example: > + :let v:statusmsg = "" + :silent verbose runtime foobar.vim + :if v:statusmsg != "" + : " foobar.vim could not be found + :endif +< When concatenating another command, the ":verbose" + only applies to the first one: > + :4verbose set verbose | set verbose +< verbose=4 ~ + verbose=0 ~ + + *K* +K Run a program to lookup the keyword under the + cursor. The name of the program is given with the + 'keywordprg' (kp) option (default is "man"). The + keyword is formed of letters, numbers and the + characters in 'iskeyword'. The keyword under or + right of the cursor is used. The same can be done + with the command > + :!{program} {keyword} +< There is an example of a program to use in the tools + directory of Vim. It is called 'ref' and does a + simple spelling check. + Special cases: + - If 'keywordprg' is empty, the ":help" command is + used. It's a good idea to include more characters + in 'iskeyword' then, to be able to find more help. + - When 'keywordprg' is equal to "man", a count before + "K" is inserted after the "man" command and before + the keyword. For example, using "2K" while the + cursor is on "mkdir", results in: > + !man 2 mkdir +< - When 'keywordprg' is equal to "man -s", a count + before "K" is inserted after the "-s". If there is + no count, the "-s" is removed. + {not in Vi} + + *v_K* +{Visual}K Like "K", but use the visually highlighted text for + the keyword. Only works when the highlighted text is + not more than one line. {not in Vi} + +[N]gs *gs* *:sl* *:sleep* +:[N]sl[eep] [N] [m] Do nothing for [N] seconds. When [m] is included, + sleep for [N] milliseconds. The count for "gs" always + uses seconds. The default is one second. > + :sleep "sleep for one second + :5sleep "sleep for five seconds + :sleep 100m "sleep for a hundred milliseconds + 10gs "sleep for ten seconds +< Can be interrupted with CTRL-C (CTRL-Break on MS-DOS). + "gs" stands for "goto sleep". While sleeping the + cursor is positioned in the text (if visible). {not + in Vi} + + *g_CTRL-A* +g CTRL-A Only when Vim was compiled with MEM_PROFILING defined + (which is very rare): print memory usage statistics. + Only useful for debugging Vim. + +============================================================================== +2. Online help *online-help* + + *help* *<Help>* *:h* *:help* *<F1>* *i_<F1>* *i_<Help>* +<Help> or +:h[elp] Open a window and display the help file in read-only + mode. If there is a help window open already, use + that one. Otherwise, if the current window uses the + full width of the screen or is at least 80 characters + wide, the help window will appear just above the + current window. Otherwise the new window is put at + the very top. + The 'helplang' option is used to select a language, if + the main help file is available in several languages. + {not in Vi} + + *{subject}* *E149* *E661* +:h[elp] {subject} Like ":help", additionally jump to the tag {subject}. + {subject} can include wildcards like "*", "?" and + "[a-z]": + :help z? jump to help for any "z" command + :help z. jump to the help for "z." + If there is no full match for the pattern, or there + are several matches, the "best" match will be used. + A sophisticated algorithm is used to decide which + match is better than another one. These items are + considered in the computation: + - A match with same case is much better than a match + with different case. + - A match that starts after a non-alphanumeric + character is better than a match in the middle of a + word. + - A match at or near the beginning of the tag is + better than a match further on. + - The more alphanumeric characters match, the better. + - The shorter the length of the match, the better. + + The 'helplang' option is used to select a language, if + the {subject} is available in several languages. + To find a tag in a specific language, append "@ab", + where "ab" is the two-letter language code. See + |help-translated|. + + Note that the longer the {subject} you give, the less + matches will be found. You can get an idea how this + all works by using commandline completion (type CTRL-D + after ":help subject"). + If there are several matches, you can have them listed + by hitting CTRL-D. Example: > + :help cont<Ctrl-D> +< To use a regexp |pattern|, first do ":help" and then + use ":tag {pattern}" in the help window. The + ":tnext" command can then be used to jump to other + matches, "tselect" to list matches and choose one. > + :help index| :tse z. +< This command can be followed by '|' and another + command, but you don't need to escape the '|' inside a + help command. So these both work: > + :help | + :help k| only +< Note that a space before the '|' is seen as part of + the ":help" argument. + You can also use <LF> or <CR> to separate the help + command from a following command. You need to type + CTRL-V first to insert the <LF> or <CR>. Example: > + :help so<C-V><CR>only +< {not in Vi} + +:h[elp]! [subject] Like ":help", but in non-English help files prefer to + find a tag in a file with the same language as the + current file. See |help-translated|. + + *:helpg* *:helpgrep* +:helpg[rep] {pattern} + Search all help text files and make a list of lines + in which {pattern} matches. Jumps to the first match. + You can navigate through the matches with the + |quickfix| commands, e.g., |:cnext| to jump to the + next one. Or use |:cwindow| to get the list of + matches in the quickfix window. + {pattern} is used as a Vim regexp |pattern|. + 'ignorecase' is not used, add "\c" to ignore case. + Example for case sensitive search: > + :helpgrep Uganda +< Example for case ignoring search: > + :helpgrep uganda\c +< Cannot be followed by another command, everything is + used as part of the pattern. But you can use + |:execute| when needed. + Compressed help files will not be searched (Debian + compresses the help files). + {not in Vi} + + +When no argument is given to |:help| the file given with the 'helpfile' option +will be opened. Otherwise the specified tag is searched for in all "doc/tags" +files in the directories specified in the 'runtimepath' option. + +The initial height of the help window can be set with the 'helpheight' option +(default 20). + +Jump to specific subjects by using tags. This can be done in two ways: +- Use the "CTRL-]" command while standing on the name of a command or option. + This only works when the tag is a keyword. "<C-Leftmouse>" and + "g<LeftMouse>" work just like "CTRL-]". +- use the ":ta {subject}" command. This also works with non-keyword + characters. + +Use CTRL-T or CTRL-O to jump back. +Use ":q" to close the help window. + +If there are several matches for an item you are looking for, this is how you +can jump to each one of them: +1. Open a help window +2. Use the ":tag" command with a slash prepended to the tag. E.g.: > + :tag /min +3. Use ":tnext" to jump to the next matching tag. + +It is possible to add help files for plugins and other items. You don't need +to change the distributed help files for that. See |add-local-help|. + +To write a local help file, see |write-local-help|. + +Note that the title lines from the local help files are automagically added to +the "LOCAL ADDITIONS" section in the "help.txt" help file |local-additions|. +This is done when viewing the file in Vim, the file itself is not changed. It +is done by going through all help files and obtaining the first line of each +file. The files in $VIMRUNTIME/doc are skipped. + + *help-xterm-window* +If you want to have the help in another xterm window, you could use this +command: > + :!xterm -e vim +help & +< + + *:helpfind* *:helpf* +:helpf[ind] Like |:help|, but use a dialog to enter the argument. + Only for backwards compatibility. It now executes the + ToolBar.FindHelp menu entry instead of using a builtin + dialog. {only when compiled with |+GUI_GTK|} +< {not in Vi} + + *:helpt* *:helptags* + *E154* *E150* *E151* *E152* *E153* *E670* +:helpt[ags] {dir} Generate the help tags file(s) for directory {dir}. + All "*.txt" and "*.??x" files in the directory are + scanned for a help tag definition in between stars. + The "*.??x" files are for translated docs, they + generate the "tags-??" file, see |help-translated|. + The generated tags files are sorted. + When there are duplicates an error message is given. + An existing tags file is silently overwritten. + To rebuild the help tags in the runtime directory + (requires write permission there): > + :helptags $VIMRUNTIME/doc +< {not in Vi} + + +TRANSLATED HELP *help-translated* + +It is possible to add translated help files, next to the original English help +files. Vim will search for all help in "doc" directories in 'runtimepath'. +This is only available when compiled with the |+multi_lang| feature. + +A set of translated help files consists of these files: + + help.abx + howto.abx + ... + tags-ab + +"ab" is the two-letter language code. Thus for Italian the names are: + + help.itx + howto.itx + ... + tags-it + +The 'helplang' option can be set to the preferred language(s). The default is +set according to the environment. Vim will first try to find a matching tag +in the preferred language(s). English is used when it cannot be found. + +To find a tag in a specific language, append "@ab" to a tag, where "ab" is the +two-letter language code. Example: > + :he user-manual@it + :he user-manual@en +The first one finds the Italian user manual, even when 'helplang' is empty. +The second one finds the English user manual, even when 'helplang' is set to +"it". + +When using command-line completion for the ":help" command, the "@en" +extention is only shown when a tag exists for multiple languages. When the +tag only exists for English "@en" is omitted. + +When using |CTRL-]| or ":help!" in a non-English help file Vim will try to +find the tag in the same language. If not found then 'helplang' will be used +to select a language. + +Help files must use latin1 or utf-8 encoding. Vim assumes the encoding is +utf-8 when finding non-ASCII characters in the first line. Thus you must +translate the header with "For Vim version". + +The same encoding must be used for the help files of one language in one +directory. You can use a different encoding for different languages and use +a different encoding for help files of the same language but in a different +directory. + +Hints for translators: +- Do not translate the tags. This makes it possible to use 'helplang' to + specify the preferred language. You may add new tags in your language. +- When you do not translate a part of a file, add tags to the English version, + using the "tag@en" notation. +- Make a package with all the files and the tags file available for download. + Users can drop it in one of the "doc" directories and start use it. + Report this to Bram, so that he can add a link on www.vim.org. +- Use the |:helptags| command to generate the tags files. It will find all + languages in the specified directory. + +============================================================================== +3. Printing *printing* + +On MS-Windows Vim can print your text on any installed printer. On other +systems a PostScript file is produced. This can be directly sent to a +PostScript printer. For other printers a program like ghostscript needs to be +used. + +3.1 PostScript Printing |postscript-printing| +3.2 PostScript Printing Encoding |postscript-print-encoding| +3.3 PostScript Printing Troubleshooting |postscript-print-trouble| +3.4 PostScript Utilities |postscript-print-util| +3.5 Formfeed Characters |printing-formfeed| + +{not in Vi} +{only available when compiled with |+printer| feature} + + *:ha* *:hardcopy* *E237* *E238* *E324* +:[range]ha[rdcopy][!] [arguments] + Send [range] lines (default whole file) to the + printer. + + On MS-Windows a dialog is displayed to allow selection + of printer, paper size etc. To skip the dialog, use + the [!]. In this case the printer defined by + 'printdevice' is used, or, if 'printdevice' is empty, + the system default printer. + + For systems other than MS-Windows, PostScript is + written in a temp file and 'printexpr' is used to + actually print it. Then [arguments] can be used by + 'printexpr' through |v:cmdarg|. Otherwise [arguments] + is ignored. 'printoptions' can be used to specify + paper size, duplex, etc. + +:[range]ha[rdcopy][!] >{filename} + As above, but write the resulting PostScript in file + {filename}. + Things like "%" are expanded |cmdline-special| + Careful: An existing file is silently overwritten. + {only available when compiled with the |+postscript| + feature} + On MS-Windows use the "print to file" feature of the + printer driver. + +Progress is displayed during printing as a page number and a percentage. To +abort printing use the interrupt key (CTRL-C or, on MS-systems, CTRL-Break). + +Printer output is controlled by the 'printfont' and 'printoptions' options. +'printheader' specifies the format of a page header. + +The printed file is always limited to the selected margins, irrespective of +the current window's 'wrap' or 'linebreak' settings. The "wrap" item in +'printoptions' can be used to switch wrapping off. +The current highlighting colors are used in the printout, with the following +considerations: +1) The normal background is always rendered as white (i.e. blank paper.) +2) White text or the default foreground is rendered as black, so that it shows + up! +3) If 'background' is "dark", then the colours are darkened to compensate for + the fact that otherwise they would be too bright to show up clearly on + white paper. + + +3.1 PostScript Printing *postscript-printing* + *E455* *E456* *E457* *E624* +Provided you have enough disk space there should be no problems generating a +PostScript file. You need to have the runtime files correctly installed (if +you can find the help files, they probably are). + +There are currently a number of limitations with PostScript printing: + +- 'printfont' - The font name is ignored (the Courier family is always used - + it should be available on all PostScript printers) but the font size is + used. + +- 'printoptions' - The duplex setting is used when generating PostScript + output, but it is up to the printer to take notice of the setting. If the + printer does not support duplex printing then it should be silently ignored. + Some printers, however, don't print at all. + +- 8-bit support - While a number of 8-bit print character encodings are + supported it is possible that some characters will not print. Whether a + character will print depends on the font in the printer knowing the + character. Missing characters will be replaced with an upside down question + mark, or a space if that character is also not known by the font. It may be + possible to get all the characters in an encoding to print by installing a + new version of the Courier font family. + +- Multi-byte support - Currently VIM will try to convert multi-byte characters + to the 8-bit encoding specified by 'printencoding' (or latin1 if it is + empty). Any characters that are not successfully converted are shown as + unknown characters. Printing will fail if VIM cannot convert the multi-byte + to the 8-bit encoding. + + +3.2 Custom 8-bit Print Character Encodings *postscript-print-encoding* + *E618* *E619* +To use your own print character encoding when printing 8-bit character data +you need to define your own PostScript font encoding vector. Details on how +to to define a font encoding vector is beyond the scope of this help file, but +you can find details in the PostScript Language Reference Manual, 3rd Edition, +published by Addison-Wesley and available in PDF form at +http://www.adobe.com/. The following describes what you need to do for VIM to +locate and use your print character encoding. + +i. Decide on a unique name for your encoding vector, one that does not clash + with any of the recognized or standard encoding names that VIM uses (see + |encoding-names| for a list), and that no one else is likely to use. +ii. Copy $VIMRUNTIME/print/latin1.ps to the print subdirectory in your + 'runtimepath' and rename it with your unique name. +iii. Edit your renamed copy of latin1.ps, replacing all occurrences of latin1 + with your unique name (don't forget the line starting %%Title:), and + modify the array of glyph names to define your new encoding vector. The + array must have exactly 256 entries or you will not be able to print! +iv. Within VIM, set 'printencoding' to your unique encoding name and then + print your file. VIM will now use your custom print character encoding. + +VIM will report an error with the resource file if you change the order or +content of the first 3 lines, other than the name of the encoding on the line +starting %%Title: or the version number on the line starting %%Version:. + +[Technical explanation for those that know PostScript - VIM looks for a file +with the same name as the encoding it will use when printing. The file +defines a new PostScript Encoding resource called /VIM-name, where name is the +print character encoding VIM will use.] + + +3.3 PostScript Printing Troubleshooting *postscript-print-trouble* + *E621* +Usually the only sign of a problem when printing with PostScript is that your +printout does not appear. If you are lucky you may get a printed page that +tells you the PostScript operator that generated the error that prevented the +print job completing. + +There are a number of possible causes as to why the printing may have failed: + +- Wrong version of the prolog resource file. The prolog resource file + contains some PostScript that VIM needs to be able to print. Each version + of VIM needs one particular version. Make sure you have correctly installed + the runtime files, and don't have any old versions of a file called prolog + in the print directory in your 'runtimepath' directory. + +- Paper size. Some PostScript printers will abort printing a file if they do + not support the requested paper size. By default VIM uses A4 paper. Find + out what size paper your printer normally uses and set the appropriate paper + size with 'printoptions'. If you cannot find the name of the paper used, + measure a sheet and compare it with the table of supported paper sizes listed + for 'printoptions', using the paper that is closest in both width AND height. + Note: The dimensions of actual paper may vary slightly from the ones listed. + If there is no paper listed close enough, then you may want to try psresize + from PSUtils, discussed below. + +- Two-sided printing (duplex). Normally a PostScript printer that does not + support two-sided printing will ignore any request to do it. However, some + printers may abort the job altogether. Try printing with duplex turned off. + Note: Duplex prints can be achieved manually using PS utils - see below. + +- Collated printing. As with Duplex printing, most PostScript printers that + do not support collating printouts will ignore a request to do so. Some may + not. Try printing with collation turned off. + +- Syntax highlighting. Some print management code may prevent the generated + PostScript file from being printed on a black and white printer when syntax + highlighting is turned on, even if solid black is the only color used. Try + printing with syntax highlighting turned off. + +A safe printoptions setting to try is: > + + :set printoptions=paper:A4,duplex:off,collate:n,syntax:n + +Replace "A4" with the paper size that best matches your printer paper. + + +3.4 PostScript Utilities *postscript-print-util* + +3.4.1 Ghostscript + +Ghostscript is a PostScript and PDF interpreter that can be used to display +and print on non-PostScript printers PostScript and PDF files. It can also +generate PDF files from PostScript. + +Ghostscript will run on a wide variety of platforms. + +There are three available versions: + +- AFPL Ghostscript (formerly Aladdin Ghostscript) which is free for + non-commercial use. It can be obtained from: + + http://www.cs.wisc.edu/~ghost/ + +- GNU Ghostscript which is available under the GNU General Public License. It + can be obtained from: + + ftp://mirror.cs.wisc.edu/pub/mirrors/ghost/gnu/ + +- A commercial version for inclusion in commercial products. + +Additional information on Ghostscript can also be found at: + + http://www.ghostscript.com/ + +Support for a number of non PostScript printers is provided in the +distribution as standard, but if you cannot find support for your printer +check the Ghostscript site for other printers not included by default. + + +3.4.2 Ghostscript Previewers. + +The interface to Ghostscript is very primitive so a number of graphical front +ends have been created. These allow easier PostScript file selection, +previewing at different zoom levels, and printing. Check supplied +documentation for full details. + +X11 + +- Ghostview. Obtainable from: + + http://www.cs.wisc.edu/~ghost/gv/ + +- gv. Derived from Ghostview. Obtainable from: + + http://wwwthep.physik.uni-mainz.de/~plass/gv/ + + Copies (possibly not the most recent) can be found at: + + http://www.cs.wisc.edu/~ghost/gv/ + +OpenVMS + +- Is apparently supported in the main code now (untested). See: + + http://wwwthep.physik.uni-mainz.de/~plass/gv/ + +Windows and OS/2 + +- GSview. Obtainable from: + + http://www.cs.wisc.edu/~ghost/gsview/ + +DOS + +- ps_view. Obtainable from: + + ftp://ftp.pg.gda.pl/pub/TeX/support/ps_view/ + ftp://ftp.dante.de/tex-archive/support/ps_view/ + +Linux + +- GSview. Linux version of the popular Windows and OS/2 previewer. + Obtainable from: + + http://www.cs.wisc.edu/~ghost/gsview/ + +- BMV. Different from Ghostview and gv in that it doesn't use X but svgalib. + Obtainable from: + + ftp://sunsite.unc.edu/pub/Linux/apps/graphics/viewers/svga/bmv-1.2.tgz + + +3.4.3 PSUtils + +PSUtils is a collection of utility programs for manipulating PostScript +documents. Binary distributions are available for many platforms, as well as +the full source. PSUtils can be found at: + + http://knackered.org/angus/psutils + +The utilities of interest include: + +- psnup. Convert PS files for N-up printing. +- psselect. Select page range and order of printing. +- psresize. Change the page size. +- psbook. Reorder and lay out pages ready for making a book. + +The output of one program can be used as the input to the next, allowing for +complex print document creation. + + +N-UP PRINTING + +The psnup utility takes an existing PostScript file generated from VIM and +convert it to an n-up version. The simplest way to create a 2-up printout is +to first create a PostScript file with: > + + :hardcopy > test.ps + +Then on your command line execute: > + + psnup -n 2 test.ps final.ps + +Note: You may get warnings from some Ghostscript previewers for files produced +by psnup - these may safely be ignored. + +Finally print the file final.ps to your PostScript printer with your +platform's print command. (You will need to delete the two PostScript files +afterwards yourself.) 'printexpr' could be modified to perform this extra +step before printing. + + +ALTERNATE DUPLEX PRINTING + +It is possible to achieve a poor man's version of duplex printing using the PS +utility psselect. This utility has options -e and -o for printing just the +even or odd pages of a PS file respectively. + +First generate a PS file with the 'hardcopy' command, then generate a new +files with all the odd and even numbered pages with: > + + psselect -o test.ps odd.ps + psselect -e test.ps even.ps + +Next print odd.ps with your platform's normal print command. Then take the +print output, turn it over and place it back in the paper feeder. Now print +even.ps with your platform's print command. All the even pages should now +appear on the back of the odd pages. + +There a couple of points to bear in mind: + +1. Position of the first page. If the first page is on top of the printout + when printing the odd pages then you need to reverse the order that the odd + pages are printed. This can be done with the -r option to psselect. This + will ensure page 2 is printed on the back of page 1. + Note: it is better to reverse the odd numbered pages rather than the even + numbered in case there are an odd number of pages in the original PS file. + +2. Paper flipping. When turning over the paper with the odd pages printed on + them you may have to either flip them horizontally (along the long edge) or + vertically (along the short edge), as well as possibly rotating them 180 + degrees. All this depends on the printer - it will be more obvious for + desktop ink jets than for small office laser printers where the paper path + is hidden from view. + + +3.5 Formfeed Characters *printing-formfeed* + +By default VIM does not do any special processing of |formfeed| control +characters. Setting the 'printoptions' formfeed item will make VIM recognize +formfeed characters and continue printing the current line at the beginning +of the first line on a new page. The use of formfeed characters provides +rudimentary print control but there are certain things to be aware of. + +VIM will always start printing a line (including a line number if enabled) +containing a formfeed character, even if it is the first character on the +line. This means if a line starting with a formfeed character is the first +line of a page then VIM will print a blank page. + +Since the line number is printed at the start of printing the line containing +the formfeed character, the remainder of the line printed on the new page +will not have a line number printed for it (in the same way as the wrapped +lines of a long line when wrap in 'printoptions' is enabled). + +If the formfeed character is the last character on a line, then printing will +continue on the second line of the new page, not the first. This is due to +VIM processing the end of the line after the formfeed character and moving +down a line to continue printing. + +Due to the points made above it is recommended that when formfeed character +processing is enabled, printing of line numbers is disabled, and that form +feed characters are not the last character on a line. Even then you may need +to adjust the number of lines before a formfeed character to prevent +accidental blank pages. + +============================================================================== +4. Using Vim like less or more *less* + +If you use the less or more program to view a file, you don't get syntax +highlighting. Thus you would like to use Vim instead. You can do this by +using the shell script "$VIMRUNTIME/macros/less.sh". + +This shell script uses the Vim script "$VIMRUNTIME/macros/less.vim". It sets +up mappings to simulate the commands that less supports. Otherwise, you can +still use the Vim commands. + +This isn't perfect. For example, when viewing a short file Vim will still use +the whole screen. But it works good enough for most uses, and you get syntax +highlighting. + +The "h" key will give you a short overview of the available commands. + + vim:tw=78:ts=8:ft=help:norl: