diff options
Diffstat (limited to 'runtime/doc/os_win32.txt')
| -rw-r--r-- | runtime/doc/os_win32.txt | 338 |
1 files changed, 338 insertions, 0 deletions
diff --git a/runtime/doc/os_win32.txt b/runtime/doc/os_win32.txt new file mode 100644 index 0000000..e72ecc8 --- /dev/null +++ b/runtime/doc/os_win32.txt @@ -0,0 +1,338 @@ +*os_win32.txt* For Vim version 9.0. Last change: 2022 Sep 18 + + + VIM REFERENCE MANUAL by George Reilly + + + *win32* *Win32* *MS-Windows* +This file documents the idiosyncrasies of the Win32 version of Vim. + +The Win32 version of Vim works on Windows 7, 8, 10 and 11. There are both +console and GUI versions. + +If you have Windows XP or Vista then Vim 9.0 up to patch level 495 can be +used. + +The 32 bit version also runs on 64 bit MS-Windows systems. + +1. Known problems |win32-problems| +2. Startup |win32-startup| +3. Restore screen contents |win32-restore| +4. Using the mouse |win32-mouse| +5. Running under Windows 95 |win32-win95| +6. Running under Windows 3.1 |win32-win3.1| +7. Installation package |win32-installer| +8. Win32 mini FAQ |win32-faq| + +Additionally, there are a number of common Win32 and DOS items: +File locations |dos-locations| +Using backslashes |dos-backslash| +Standard mappings |dos-standard-mappings| +Screen output and colors |dos-colors| +File formats |dos-file-formats| +:cd command |dos-:cd| +Interrupting |dos-CTRL-Break| +Temp files |dos-temp-files| +Shell option default |dos-shell| +PowerShell defaults |dos-powershell| + +Win32 GUI |gui-w32| + +Credits: +The Win32 version was written by George V. Reilly <george@reilly.org>. +The original Windows NT port was done by Roger Knobbe <RogerK@wonderware.com>. +The GUI version was made by George V. Reilly and Robert Webb. + +For compiling see "src/INSTALLpc.txt". *win32-compiling* + + *WSL* +When using Vim on WSL (Windows Subsystem for Linux) the remarks here do not +apply, `has('win32')` will return false then. In case you need to know +whether Vim is running on WSL you can use `exists('$WSLENV')`. + +============================================================================== +1. Known problems *win32-problems* + +When doing file name completion, Vim also finds matches for the short file +name. But Vim will still find and use the corresponding long file name. For +example, if you have the long file name "this_is_a_test" with the short file +name "this_i~1", the command ":e *1" will start editing "this_is_a_test". + +============================================================================== +2. Startup *win32-startup* + +Current directory *win32-curdir* + +If Vim is started with a single file name argument, and it has a full path +(starts with "x:\"), Vim assumes it was started from the file explorer and +will set the current directory to where that file is. To avoid this when +typing a command to start Vim, use a forward slash instead of a backslash. +Example: > + + vim c:\text\files\foo.txt + +Will change to the "C:\text\files" directory. > + + vim c:/text\files\foo.txt + +Will use the current directory. + + +Term option *win32-term* + +The only kind of terminal type that the Win32 version of Vim understands is +"win32", which is built-in. If you set 'term' to anything else, you will +probably get very strange behavior from Vim. Therefore Vim does not obtain +the default value of 'term' from the environment variable "TERM". + +$PATH *win32-PATH* + +The directory of the Vim executable is appended to $PATH. This is mostly to +make "!xxd" work, as it is in the Tools menu. And it also means that when +executable() returns 1 the executable can actually be executed. + +Command line arguments *win32-cmdargs* + +Analysis of a command line into parameters is not standardised in MS-Windows. +Vim and gvim used to use different logic to parse it (before 7.4.432), and the +logic was also depended on what it was compiled with. Now Vim and gvim both +use the CommandLineToArgvW() Win32 API, so they behave in the same way. + +The basic rules are: *win32-backslashes* + a) A parameter is a sequence of graphic characters. + b) Parameters are separated by white space. + c) A parameter can be enclosed in double quotes to include white space. + d) A sequence of zero or more backslashes (\) and a double quote (") + is special. The effective number of backslashes is halved, rounded + down. An even number of backslashes reverses the acceptability of + spaces and tabs, an odd number of backslashes produces a literal + double quote. + +So: + " is a special double quote + \" is a literal double quote + \\" is a literal backslash and a special double quote + \\\" is a literal backslash and a literal double quote + \\\\" is 2 literal backslashes and a special double quote + \\\\\" is 2 literal backslashes and a literal double quote + etc. + +Example: > + vim "C:\My Music\freude" +"set ignorecase" +/"\"foo\\" +\"bar\\\" + +opens "C:\My Music\freude" and executes the line mode commands: > + set ignorecase; /"foo\ and /bar\" + +These rules are also described in the reference of the CommandLineToArgvW API: + https://msdn.microsoft.com/en-us/library/windows/desktop/bb776391.aspx + + *win32-quotes* +There are additional rules for quotes (which are not well documented). +As described above, quotes inside a file name (or any other command line +argument) can be escaped with a backslash. E.g. > + vim -c "echo 'foo\"bar'" + +Alternatively use three quotes to get one: > + vim -c "echo 'foo"""bar'" + +The quotation rules are: + +1. A `"` starts quotation. +2. Another `"` or `""` ends quotation. If the quotation ends with `""`, a `"` + is produced at the end of the quoted string. + +Examples, with [] around an argument: + "foo" -> [foo] + "foo"" -> [foo"] + "foo"bar -> [foobar] + "foo" bar -> [foo], [bar] + "foo""bar -> [foo"bar] + "foo"" bar -> [foo"], [bar] + "foo"""bar" -> [foo"bar] + + +============================================================================== +3. Restore screen contents *win32-restore* + +When 'restorescreen' is set (which is the default), Vim will restore the +original contents of the console when exiting or when executing external +commands. If you don't want this, use ":set nors". |'restorescreen'| + +============================================================================== +4. Using the mouse *win32-mouse* + +The Win32 version of Vim supports using the mouse. If you have a two-button +mouse, the middle button can be emulated by pressing both left and right +buttons simultaneously - but note that in the Win32 GUI, if you have the right +mouse button pop-up menu enabled (see 'mouse'), you should err on the side of +pressing the left button first. |mouse-using| + +When the mouse doesn't work, try disabling the "Quick Edit Mode" feature of +the console. + +============================================================================== +5. Running under Windows 95 *win32-win95* + *windows95* *windows98* *windowsme* +Windows 95/98/ME support was removed in patch 8.0.0029 If you want to use it +you will need to get a version older than that. + +============================================================================== +6. Running under Windows 3.1 *win32-win3.1* + + *win32s* *windows-3.1* *gui-w32s* *win16* +There was a special version of gvim that runs under Windows 3.1 and 3.11. +Support was removed in patch 7.4.1364. + +============================================================================== +7. Installation package *win32-installer* + +A simple installer for windows is available at http://www.vim.org/download.php +(stable version) and nightly builds are also available at +https://github.com/vim/vim-win32-installer/releases/ + +The nightly builds include 32bit and 64bit builds, have most features enabled +and usually also contain an extra cryptographic signed installer, so Windows +will not complain. + +To use the installer, simply run the exe file. The following switches are +also supported: > + + gvim_<version>.exe /S -> silent install without any dialogues + gvim_<version>.exe /D=C:\vim -> Install into directory c:\vim + -> /D must be the last argument + gvim_<version>.exe /S /D=c:\vim -> silent install into c:\vim +< +The default installation directory can alternatively be given by setting the +$VIM environment variable. + +============================================================================== +8. Win32 mini FAQ *win32-faq* + +Q. How do I change the font? +A. In the GUI version, you can use the 'guifont' option. Example: > + :set guifont=Lucida_Console:h15:cDEFAULT +< In the console version, you need to set the font of the console itself. + You cannot do this from within Vim. + +Q. How do I type dead keys on Windows NT? +A. Dead keys work on NT 3.51. Just type them as you would in any other + application. + On NT 4.0, you need to make sure that the default locale (set in the + Keyboard part of the Control Panel) is the same as the currently active + locale. Otherwise the NT code will get confused and crash! This is a NT + 4.0 problem, not really a Vim problem. + +Q. I'm using Vim to edit a symbolically linked file on a Unix NFS file server. + When I write the file, Vim does not "write through" the symlink. Instead, + it deletes the symbolic link and creates a new file in its place. Why? +A. On Unix, Vim is prepared for links (symbolic or hard). A backup copy of + the original file is made and then the original file is overwritten. This + assures that all properties of the file remain the same. On non-Unix + systems, the original file is renamed and a new file is written. Only the + protection bits are set like the original file. However, this doesn't work + properly when working on an NFS-mounted file system where links and other + things exist. The only way to fix this in the current version is not + making a backup file, by ":set nobackup nowritebackup" |'writebackup'| + +Q. I'm using Vim to edit a file on a Unix file server through Samba. When I + write the file, the owner of the file is changed. Why? +A. When writing a file Vim renames the original file, this is a backup (in + case writing the file fails halfway). Then the file is written as a new + file. Samba then gives it the default owner for the file system, which may + differ from the original owner. + To avoid this set the 'backupcopy' option to "yes". Vim will then make a + copy of the file for the backup, and overwrite the original file. The + owner isn't changed then. + +Q. How do I get to see the output of ":make" while it's running? +A. Basically what you need is to put a tee program that will copy its input + (the output from make) to both stdout and to the errorfile. You can find a + copy of tee (and a number of other GNU tools) at + http://gnuwin32.sourceforge.net or http://unxutils.sourceforge.net + Alternatively, try the more recent Cygnus version of the GNU tools at + http://www.cygwin.com Other Unix-style tools for Win32 are listed at + http://directory.google.com/Top/Computers/Software/Operating_Systems/Unix/Win32/ + When you do get a copy of tee, you'll need to add > + :set shellpipe=\|\ tee +< to your _vimrc. + +Q. I'm storing files on a remote machine that works with VisionFS, and files + disappear! +A. VisionFS can't handle certain dot (.) three letter extension file names. + SCO declares this behavior required for backwards compatibility with 16bit + DOS/Windows environments. The two commands below demonstrate the behavior: +> + echo Hello > file.bat~ + dir > file.bat +< + The result is that the "dir" command updates the "file.bat~" file, instead + of creating a new "file.bat" file. This same behavior is exhibited in Vim + when editing an existing file named "foo.bat" because the default behavior + of Vim is to create a temporary file with a '~' character appended to the + name. When the file is written, it winds up being deleted. + + Solution: Add this command to your _vimrc file: > + :set backupext=.temporary + +Q. How do I change the blink rate of the cursor? +A. You can't! This is a limitation of the NT console. NT 5.0 is reported to + be able to set the blink rate for all console windows at the same time. + + *:!start* +Q. How can I asynchronously run an external command or program, or open a + document or URL with its default program? +A. When using :! to run an external command, you can run it with "start". For + example, to run notepad: > + :!start notepad +< To open "image.jpg" with the default image viewer: > + :!start image.jpg +< To open the folder of the current file in Windows Explorer: > + :!start %:h +< To open the Vim home page with the default browser: > + :!start http://www.vim.org/ +< + Using "start" stops Vim switching to another screen, opening a new console, + or waiting for the program to complete; it indicates that you are running a + program that does not affect the files you are editing. Programs begun + with :!start do not get passed Vim's open file handles, which means they do + not have to be closed before Vim. + To avoid this special treatment, use ":! start". + There are two optional arguments (see the next Q): + /min the window will be minimized + /b no console window will be opened + You can use only one of these flags at a time. A second one will be + treated as the start of the command. + *windows-asynchronously* +Q. How do I avoid getting a window for programs that I run asynchronously? +A. You have two possible solutions depending on what you want: + 1) You may use the /min flag in order to run program in a minimized state + with no other changes. It will work equally for console and GUI + applications. + 2) You can use the /b flag to run console applications without creating a + console window for them (GUI applications are not affected). But you + should use this flag only if the application you run doesn't require any + input. Otherwise it will get an EOF error because its input stream + (stdin) would be redirected to \\.\NUL (stdout and stderr too). + + Example for a console application, run Exuberant ctags: > + :!start /min ctags -R . +< When it has finished you should see file named "tags" in your current + directory. You should notice the window title blinking on your taskbar. + This is more noticeable for commands that take longer. + Now delete the "tags" file and run this command: > + :!start /b ctags -R . +< You should have the same "tags" file, but this time there will be no + blinking on the taskbar. + Example for a GUI application: > + :!start /min notepad + :!start /b notepad +< The first command runs notepad minimized and the second one runs it + normally. + + *windows-icon* +Q. I don't like the Vim icon, can I change it? +A. Yes, place your favorite icon in bitmaps/vim.ico in a directory of + 'runtimepath'. For example ~/vimfiles/bitmaps/vim.ico. + + + vim:tw=78:ts=8:noet:ft=help:norl: |