thac0/vim
1
0
Fork 0
forked from aniani/vim
Code Activity

updated for version 7.0001

Browse Source
This commit is contained in:
Bram Moolenaar
2004-06-13 20:20:40 +00:00
parent b4210b3bc1
commit 071d4279d6
1588 changed files with 750846 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

363
runtime/doc/Makefile Normal file
View File

@@ -0,0 +1,363 @@
#
# Makefile for the Vim documentation on Unix
#
# If you get "don't know how to make scratch", first run make in the source
# directory. Or remove the include below.
AWK = awk
# Set to $(VIMTARGET) when executed from src/Makefile.
VIMEXE = vim
# include the config.mk from the source directory. It's only needed to set
# AWK, used for "make html". Comment this out if the include gives problems.
include ../../src/auto/config.mk
DOCS = \
arabic.txt \
autocmd.txt \
change.txt \
cmdline.txt \
debugger.txt \
develop.txt \
diff.txt \
digraph.txt \
editing.txt \
eval.txt \
farsi.txt \
filetype.txt \
fold.txt \
gui.txt \
gui_w16.txt \
gui_w32.txt \
gui_x11.txt \
hangulin.txt \
hebrew.txt \
help.txt \
howto.txt \
if_cscop.txt \
if_ole.txt \
if_perl.txt \
if_pyth.txt \
if_ruby.txt \
if_sniff.txt \
if_tcl.txt \
indent.txt \
index.txt \
insert.txt \
intro.txt \
map.txt \
message.txt \
motion.txt \
mbyte.txt \
mlang.txt \
netbeans.txt \
options.txt \
os_390.txt \
os_amiga.txt \
os_beos.txt \
os_dos.txt \
os_mac.txt \
os_mint.txt \
os_msdos.txt \
os_os2.txt \
os_qnx.txt \
os_risc.txt \
os_unix.txt \
os_vms.txt \
os_win32.txt \
pattern.txt \
pi_expl.txt \
pi_gzip.txt \
pi_netrw.txt \
pi_spec.txt \
quickfix.txt \
quickref.txt \
quotes.txt \
recover.txt \
remote.txt \
repeat.txt \
rileft.txt \
russian.txt \
scroll.txt \
sign.txt \
sponsor.txt \
starting.txt \
syntax.txt \
tagsrch.txt \
term.txt \
tips.txt \
todo.txt \
uganda.txt \
undo.txt \
usr_01.txt \
usr_02.txt \
usr_03.txt \
usr_04.txt \
usr_05.txt \
usr_06.txt \
usr_07.txt \
usr_08.txt \
usr_09.txt \
usr_10.txt \
usr_11.txt \
usr_12.txt \
usr_20.txt \
usr_21.txt \
usr_22.txt \
usr_23.txt \
usr_24.txt \
usr_25.txt \
usr_26.txt \
usr_27.txt \
usr_28.txt \
usr_29.txt \
usr_30.txt \
usr_31.txt \
usr_40.txt \
usr_41.txt \
usr_42.txt \
usr_43.txt \
usr_44.txt \
usr_45.txt \
usr_90.txt \
usr_toc.txt \
various.txt \
version4.txt \
version5.txt \
version6.txt \
vi_diff.txt \
visual.txt \
windows.txt \
workshop.txt
HTMLS = \
arabic.html \
autocmd.html \
change.html \
cmdline.html \
debugger.html \
develop.html \
diff.html \
digraph.html \
editing.html \
eval.html \
farsi.html \
filetype.html \
fold.html \
gui.html \
gui_w16.html \
gui_w32.html \
gui_x11.html \
hangulin.html \
hebrew.html \
help.html \
howto.html \
if_cscop.html \
if_ole.html \
if_perl.html \
if_pyth.html \
if_ruby.html \
if_sniff.html \
if_tcl.html \
indent.html \
index.html \
insert.html \
intro.html \
map.html \
message.html \
motion.html \
mbyte.html \
mlang.html \
netbeans.html \
options.html \
os_390.html \
os_amiga.html \
os_beos.html \
os_dos.html \
os_mac.html \
os_mint.html \
os_msdos.html \
os_os2.html \
os_qnx.html \
os_risc.html \
os_unix.html \
os_vms.html \
os_win32.html \
pattern.html \
pi_expl.html \
pi_gzip.html \
pi_netrw.html \
pi_spec.html \
quickfix.html \
quickref.html \
quotes.html \
recover.html \
remote.html \
repeat.html \
rileft.html \
russian.html \
scroll.html \
sign.html \
sponsor.html \
starting.html \
syntax.html \
tagsrch.html \
tags.html \
term.html \
tips.html \
todo.html \
uganda.html \
undo.html \
usr_01.html \
usr_02.html \
usr_03.html \
usr_04.html \
usr_05.html \
usr_06.html \
usr_07.html \
usr_08.html \
usr_09.html \
usr_10.html \
usr_11.html \
usr_12.html \
usr_20.html \
usr_21.html \
usr_22.html \
usr_23.html \
usr_24.html \
usr_25.html \
usr_26.html \
usr_27.html \
usr_28.html \
usr_29.html \
usr_30.html \
usr_31.html \
usr_40.html \
usr_41.html \
usr_42.html \
usr_43.html \
usr_44.html \
usr_45.html \
usr_90.html \
usr_toc.html \
various.html \
version4.html \
version5.html \
version6.html \
vi_diff.html \
visual.html \
windows.html \
workshop.html
.SUFFIXES:
.SUFFIXES: .c .o .txt .html
all: tags vim.man vimdiff.man vimtutor.man xxd.man
# Use Vim to generate the tags file. Can only be used when Vim has been
# compiled and installed. Supports multiple languages.
vimtags: $(DOCS)
$(VIMEXE) -u NONE -esX -c "helptags ." -c quit
# Use "doctags" to generate the tags file. Only works for English!
tags: doctags $(DOCS)
./doctags $(DOCS) | LANG=C LC_ALL=C sort >tags
uniq -d -2 tags
doctags: doctags.c
$(CC) doctags.c -o doctags
vim.man: vim.1
nroff -man vim.1 | sed -e s/.//g > vim.man
vimdiff.man: vimdiff.1
nroff -man vimdiff.1 | sed -e s/.//g > vimdiff.man
vimtutor.man: vimtutor.1
nroff -man vimtutor.1 | sed -e s/.//g > vimtutor.man
xxd.man: xxd.1
nroff -man xxd.1 | sed -e s/.//g > xxd.man
uganda.nsis.txt: uganda.txt
sed -e 's/[ ]*\*[-a-zA-Z0-9.]*\*//g' -e 's/vim:tw=78://' \
uganda.txt | uniq >uganda.nsis.txt
# Awk version of .txt to .html conversion.
html: noerrors tags tags.ref $(HTMLS)
@if test -f errors.log; then more errors.log; fi
noerrors:
-rm -f errors.log
.txt.html:
$(AWK) -f makehtml.awk $< >$@
tags.ref tags.html: tags
$(AWK) -f maketags.awk tags >tags.html
# Perl version of .txt to .html conversion.
# There can't be two rules to produce a .html from a .txt file.
# Just run over all .txt files each time one changes. It's fast anyway.
perlhtml: tags $(DOCS)
./vim2html.pl tags $(DOCS)
clean:
-rm doctags *.html tags.ref
# These files are in the extra archive, skip if not present
arabic.txt:
touch arabic.txt
farsi.txt:
touch farsi.txt
hebrew.txt:
touch hebrew.txt
russian.txt:
touch russian.txt
gui_w16.txt:
touch gui_w16.txt
gui_w32.txt:
touch gui_w32.txt
if_ole.txt:
touch if_ole.txt
os_390.txt:
touch os_390.txt
os_amiga.txt:
touch os_amiga.txt
os_beos.txt:
touch os_beos.txt
os_dos.txt:
touch os_dos.txt
os_mac.txt:
touch os_mac.txt
os_mint.txt:
touch os_mint.txt
os_msdos.txt:
touch os_msdos.txt
os_os2.txt:
touch os_os2.txt
os_qnx.txt:
touch os_qnx.txt
os_risc.txt:
touch os_risc.txt
os_win32.txt:
touch os_win32.txt

323
runtime/doc/arabic.txt Normal file
View File

@@ -0,0 +1,323 @@
*arabic.txt* For Vim version 7.0aa. Last change: 2004 Jun 09
VIM REFERENCE MANUAL by Nadim Shaikli
Arabic Language support (options & mappings) for Vim *Arabic*
{Vi does not have any of these commands}
*E800*
In order to use right-to-left and Arabic mapping support, it is
necessary to compile VIM with the |+arabic| feature.
These functions have been created by Nadim Shaikli <nadim-at-arabeyes.org>
It is best to view this file with these settings within VIM's GUI: >
:set encoding=utf-8
:set arabicshape
Introduction
------------
Arabic is a rather demanding language in which a number of special
features are required. Characters are right-to-left oriented and
ought to appear as such on the screen (ie. from right to left).
Arabic also requires shaping of its characters, meaning the same
character has a different visual form based on its relative location
within a word (initial, medial, final or stand-alone). Arabic also
requires two different forms of combining and the ability, in
certain instances, to either superimpose up to two characters on top
of another (composing) or the actual substitution of two characters
into one (combining). Lastly, to display Arabic properly one will
require not only ISO-8859-6 (U+0600-U+06FF) fonts, but will also
require Presentation Form-B (U+FE70-U+FEFF) fonts both of which are
subsets within a so-called ISO-10646-1 font.
The commands, prompts and help files are not in Arabic, therefore
the user interface remains the standard Vi interface.
Highlights
----------
o Editing left-to-right files as in the original VIM hasn't changed.
o Viewing and editing files in right-to-left windows. File
orientation is per window, so it is possible to view the same
file in right-to-left and left-to-right modes, simultaneously.
o No special terminal with right-to-left capabilities is required.
The right-to-left changes are completely hardware independent.
Only Arabic fonts are necessary.
o Compatible with the original VIM. Almost all features work in
right-to-left mode (there are liable to be bugs).
o Changing keyboard mapping and reverse insert modes using a single
command.
o Toggling complete Arabic support via a single command.
o While in Arabic mode, numbers are entered from left to right. Upon
entering a none number character, that character will be inserted
just into the left of the last number.
o Arabic keymapping on the command line in reverse insert mode.
o Proper Bidirectional functionality is possible given VIM is
started within a Bidi capable terminal emulator.
Arabic Fonts *arabicfonts*
------------
VIM requires monospaced fonts of which there are many out there.
Arabic requires ISO-8859-6 as well as Presentation Form-B fonts
(without Form-B, Arabic will _NOT_ be usable). It is highly
recommended that users search for so-called 'ISO-10646-1' fonts.
Do an Internet search or check www.arabeyes.org for further
info on where to attain the necessary Arabic fonts.
Font Installation
-----------------
o Installation of fonts for X Window systems (Unix/Linux)
Depending on your system, copy your_ARABIC_FONT file into a
directory of your choice. Change to the directory containing
the Arabic fonts and execute the following commands:
% mkfontdir
% xset +fp path_name_of_arabic_fonts_directory
Usage
-----
Prior to the actual usage of Arabic within VIM, a number of settings
need to be accounted for and invoked.
o Setting the Arabic fonts
+ For VIM GUI set the 'guifont' to your_ARABIC_FONT. This is done
by entering the following command in the VIM window.
>
:set guifont=your_ARABIC_FONT
<
NOTE: the string 'your_ARABIC_FONT' is used to denote a complete
font name akin to that used in linux/unix system.
(eg. -misc-fixed-medium-r-normal--20-200-75-75-c-100-iso10646-1)
You can append the 'guifont' set command to your .vimrc file
in order to get the same above noted results. In other words,
you can include ':set guifont=your_ARABIC_FONT' to your .vimrc
file.
+ Under the X Window environment, you can also start VIM with
'-fn your_ARABIC_FONT' option.
o Setting the appropriate character Encoding
To enable the correct Arabic encoding the following command needs
to be appended,
>
:set encoding=utf-8
<
to your .vimrc file (entering the command manually into you VIM
window is highly discouraged). In short, include ':set
encoding=utf-8' to your .vimrc file.
Attempts to use Arabic without UTF-8 will result the following
warning message,
*W17* >
Arabic requires UTF-8, do ':set encoding=utf-8'
o Enable Arabic settings [short-cut]
In order to simplify and streamline things, you can either invoke
VIM with the command-line option,
% vim -A my_utf8_arabic_file ...
or enable 'arabic' via the following command within VIM
>
:set arabic
<
The two above noted possible invocations are the preferred manner
in which users are instructed to proceed. Baring an enabled 'termbidi'
setting, both command options:
1. set the appropriate keymap
2. enable the deletion of a single combined pair character
3. enable rightleft mode
4. enable rightleftcmd mode (affecting the command-line)
5. enable arabicshape mode (do visual character alterations)
You may also append the command to your .vimrc file and simply
include ':set arabic' to it.
You are also capable of disabling Arabic support via
>
:set noarabic
<
which resets everything that the command had enabled without touching
the global settings as they could affect other possible open buffers.
In short the 'noarabic' command,
1. resets to the alternate keymap
2. disables the deletion of a single combined pair character
3. disables rightleft mode
NOTE: the 'arabic' command takes into consideration 'termbidi' for
possible external bi-directional (bidi) support from the
terminal ("mlterm" for instance offers such support).
'termbidi', if available, is superior to rightleft support
and its support is preferred due to its level of offerings.
'arabic' when 'termbidi' is enabled only sets the keymap.
If, on the other hand, you'd like to be verbose and explicit and
are opting not to use the 'arabic' short-cut command, here's what
is needed (ie. if you use ':set arabic' you can skip this section) -
+ Arabic Keymapping Activation
To activate the Arabic keymap (ie. to remap your English/Latin
keyboard to look-n-feel like a standard Arabic one), set the
'keymap' command to "arabic". This is done by entering
>
:set keymap=arabic
<
in your VIM window. You can also append the 'keymap' set command to
your .vimrc file. In other words, you can include ':set keymap=arabic'
to your .vimrc file.
To turn toggle (or switch) your keymapping between Arabic and the
default mapping (English), it is advised that users use the 'CTRL-^'
key press while in insert (or add/replace) mode. The command-line
will display your current mapping by displaying an "Arabic" string
next to your insertion mode (eg. -- INSERT Arabic --) indicating
your current keymap.
+ Arabic deletion of a combined pair character
By default VIM has the 'delcombine' option disabled. This option
allows the deletion of ALEF in a LAM_ALEF (LAA) combined character
and still retain the LAM (ie. it reverts to treating the combined
character as its natural two characters form -- this also pertains
to harakat and their combined forms). You can enable this option
by entering
>
:set delcombine
<
in our VIM window. You can also append the 'delcombine' set command
to your .vimrc file. In other words, you can include ':set delcombine'
to your .vimrc file.
+ Arabic right-to-left Mode
By default VIM starts in Left-to-right mode. 'rightleft' is the
command that allows one to alter a window's orientation - that can
be accomplished via,
- Toggling between left-to-right and right-to-left modes is
accomplished through ':set rightleft' and ':set norightleft'.
- While in Left-to-right mode, enter ':set rl' in the command line
('rl' is the abbreviation for rightleft).
- Put the ':set rl' line in your '.vimrc' file to start the VIM in
right-to-left mode permanently.
+ Arabic right-to-left command-line Mode
For certain commands the editing can be done in right-to-left mode.
Currently this is only applicable to search commands.
This is controlled with the 'rightleftcmd' option. The default is
"search", which means that windows in which 'rightleft' is set will
edit search commands in right-left mode. To disable this behavior,
>
:set rightleftcmd=
<
To enable right-left editing of search commands again,
>
:set rightleftcmd&
<
+ Arabic Shaping Mode
To activate the required visual characters alterations (shaping,
composing, combining) which the Arabic language requires, enable
the 'arabicshape' command. This is done by entering
>
:set arabicshape
<
in our VIM window. You can also append the 'arabicshape' set
command to your .vimrc file. In other words, you can include
':set arabicshape' to your .vimrc file.
Keymap/Keyboard *arabickeymap*
---------------
The character/letter encoding used in VIM is the standard UTF-8.
It is widely discouraged that any other encoding be used or even
attempted.
Note: UTF-8 is an all encompassing encoding and as such is
the only supported (and encouraged) encoding with
regard to Arabic (all other proprietary encodings
should be discouraged and frowned upon).
o Keyboard
+ CTRL-^ in insert/replace mode toggles between Arabic/Latin mode
+ Keyboard mapping is based on the Microsoft's Arabic keymap (the
defacto standard in the Arab world):
+---------------------------------------------------------------------+
|! |@ |# |$ |% |^ |& |* |( |) |_ |+ || |~ ّ |
|1 ١ |2 ٢ |3 ٣ |4 ٤ |5 ٥ |6 ٦ |7 ٧ |8 ٨ |9 ٩ |0 ٠ |- |= |\ |` ذ |
+---------------------------------------------------------------------+
|Q َ |W ً |E ُ |R ٌ |T لإ |Y إ |U ` |I ÷ |O x |P ؛ |{ < |} > |
|q ض |w ص |e ث |r ق |t ف |y غ |u ع |i ه |o خ |p ح |[ ج |] د |
+-----------------------------------------------------------+
|A ِ |S ٍ |D [ |F ] |G لأ |H أ |J ـ |K ، |L / |: |" |
|a ش |s س |d ي |f ب |g ل |h ا |j ت |k ن |l م |; ك |' ط |
+------------------------------------------------------+
|Z ~ |X ْ |C { |V } |B لآ |N آ |M ' |< , |> . |? ؟ |
|z ئ |x ء |c ؤ |v ر |b لا |n ى |m ة |, و |. ز |/ ظ |
+-------------------------------------------------+
Restrictions
------------
o VIM in its GUI form does not currently support Bi-directionality
(ie. the ability to see both Arabic and Latin intermixed within
the same line).
Known Bugs
----------
There is one known minor bug,
1. If you insert a haraka (eg. Fatha (U+064E)) after a LAM (U+0644)
and then insert an ALEF (U+0627), the appropriate combining will
not happen due to the sandwiched haraka resulting in something
that will NOT be displayed correctly.
WORK-AROUND: Don't include harakats between LAM and ALEF combos.
In general, don't anticipate to see correct visual
representation with regard to harakats and LAM+ALEF
combined characters (even those entered after both
characters). The problem noted is strictly a visual
one, meaning saving such a file will contain all the
appropriate info/encodings - nothing is lost.
No other bugs are known to exist.
vim:tw=78:ts=8:ft=help:norl:

904
runtime/doc/autocmd.txt Normal file
View File

@@ -0,0 +1,904 @@
*autocmd.txt* For Vim version 7.0aa. Last change: 2004 Apr 20
VIM REFERENCE MANUAL by Bram Moolenaar
Automatic commands *autocommand*
For a basic explanation, see section |40.3| in the user manual.
1. Introduction |autocmd-intro|
2. Defining autocommands |autocmd-define|
3. Removing autocommands |autocmd-remove|
4. Listing autocommands |autocmd-list|
5. Events |autocmd-events|
6. Patterns |autocmd-patterns|
7. Groups |autocmd-groups|
8. Executing autocommands |autocmd-execute|
9. Using autocommands |autocmd-use|
{Vi does not have any of these commands}
{only when the |+autocmd| feature has not been disabled at compile time}
==============================================================================
1. Introduction *autocmd-intro*
You can specify commands to be executed automatically for when reading or
writing a file, when entering or leaving a buffer or window, and when exiting
Vim. For example, you can create an autocommand to set the 'cindent' option
for files matching *.c. You can also use autocommands to implement advanced
features, such as editing compressed files (see |gzip-example|). The usual
place to put autocommands is in your .vimrc or .exrc file.
*E203* *E204* *E143*
WARNING: Using autocommands is very powerful, and may lead to unexpected side
effects. Be careful not to destroy your text.
- It's a good idea to do some testing on an expendable copy of a file first.
For example: If you use autocommands to decompress a file when starting to
edit it, make sure that the autocommands for compressing when writing work
correctly.
- Be prepared for an error halfway through (e.g., disk full). Vim will mostly
be able to undo the changes to the buffer, but you may have to clean up the
changes to other files by hand (e.g., compress a file that has been
decompressed).
- If the BufRead* events allow you to edit a compressed file, the FileRead*
events should do the same (this makes recovery possible in some rare cases).
It's a good idea to use the same autocommands for the File* and Buf* events
when possible.
==============================================================================
2. Defining autocommands *autocmd-define*
Note: The ":autocmd" command cannot be followed by another command, since any
'|' is considered part of the command.
*:au* *:autocmd*
:au[tocmd] [group] {event} {pat} [nested] {cmd}
Add {cmd} to the list of commands that Vim will
execute automatically on {event} for a file matching
{pat}. Vim always adds the {cmd} after existing
autocommands, so that the autocommands execute in the
order in which they were given. See |autocmd-nested|
for [nested].
Note that special characters (e.g., "%", "<cword>") in the ":autocmd"
arguments are not expanded when the autocommand is defined. These will be
expanded when the Event is recognized, and the {cmd} is executed. The only
exception is that "<sfile>" is expanded when the autocmd is defined. Example:
>
:au BufNewFile,BufRead *.html so <sfile>:h/html.vim
Here Vim expands <sfile> to the name of the file containing this line.
When your .vimrc file is sourced twice, the autocommands will appear twice.
To avoid this, put this command in your .vimrc file, before defining
autocommands: >
:autocmd! " Remove ALL autocommands for the current group.
If you don't want to remove all autocommands, you can instead use a variable
to ensure that Vim includes the autocommands only once: >
:if !exists("autocommands_loaded")
: let autocommands_loaded = 1
: au ...
:endif
When the [group] argument is not given, Vim uses the current group (as defined
with ":augroup"); otherwise, Vim uses the group defined with [group]. Note
that [group] must have been defined before. You cannot define a new group
with ":au group ..."; use ":augroup" for that.
While testing autocommands, you might find the 'verbose' option to be useful: >
:set verbose=9
This setting makes Vim echo the autocommands as it executes them.
When defining an autocommand in a script, it will be able to call functions
local to the script and use mappings local to the script. When the event is
triggered and the command executed, it will run in the context of the script
it was defined in. This matters if |<SID>| is used in a command.
When executing the commands, the messages from one command overwrites a
previous message. This is different from when executing the commands
manually. Mostly the screen will not scroll up, thus there is no hit-enter
prompt. When one command outputs two messages this can happen anyway.
==============================================================================
3. Removing autocommands *autocmd-remove*
:au[tocmd]! [group] {event} {pat} [nested] {cmd}
Remove all autocommands associated with {event} and
{pat}, and add the command {cmd}. See
|autocmd-nested| for [nested].
:au[tocmd]! [group] {event} {pat}
Remove all autocommands associated with {event} and
{pat}.
:au[tocmd]! [group] * {pat}
Remove all autocommands associated with {pat} for all
events.
:au[tocmd]! [group] {event}
Remove ALL autocommands for {event}.
:au[tocmd]! [group] Remove ALL autocommands.
When the [group] argument is not given, Vim uses the current group (as defined
with ":augroup"); otherwise, Vim uses the group defined with [group].
==============================================================================
4. Listing autocommands *autocmd-list*
:au[tocmd] [group] {event} {pat}
Show the autocommands associated with {event} and
{pat}.
:au[tocmd] [group] * {pat}
Show the autocommands associated with {pat} for all
events.
:au[tocmd] [group] {event}
Show all autocommands for {event}.
:au[tocmd] [group] Show all autocommands.
If you provide the [group] argument, Vim lists only the autocommands for
[group]; otherwise, Vim lists the autocommands for ALL groups. Note that this
argument behavior differs from that for defining and removing autocommands.
==============================================================================
5. Events *autocmd-events* *E215* *E216*
*autocommand-events* *{event}*
Vim recognizes the following events. Vim ignores the case of event names
(e.g., you can use "BUFread" or "bufread" instead of "BufRead").
*BufNewFile*
BufNewFile When starting to edit a file that doesn't
exist. Can be used to read in a skeleton
file.
*BufReadPre* *E200* *E201*
BufReadPre When starting to edit a new buffer, before
reading the file into the buffer. Not used
if the file doesn't exist.
*BufRead* *BufReadPost*
BufRead or BufReadPost When starting to edit a new buffer, after
reading the file into the buffer, before
executing the modelines. See |BufWinEnter|
for when you need to do something after
processing the modelines.
This does NOT work for ":r file". Not used
when the file doesn't exist. Also used after
successfully recovering a file.
*BufReadCmd*
BufReadCmd Before starting to edit a new buffer. Should
read the file into the buffer. |Cmd-event|
*BufFilePre*
BufFilePre Before changing the name of the current buffer
with the ":file" or ":saveas" command.
*BufFilePost*
BufFilePost After changing the name of the current buffer
with the ":file" or ":saveas" command.
*FileReadPre*
FileReadPre Before reading a file with a ":read" command.
*FileReadPost*
FileReadPost After reading a file with a ":read" command.
Note that Vim sets the '[ and '] marks to the
first and last line of the read. This can be
used to operate on the lines just read.
*FileReadCmd*
FileReadCmd Before reading a file with a ":read" command.
Should do the reading of the file. |Cmd-event|
*FilterReadPre* *E135*
FilterReadPre Before reading a file from a filter command.
Vim checks the pattern against the name of
the current buffer, not the name of the
temporary file that is the output of the
filter command.
*FilterReadPost*
FilterReadPost After reading a file from a filter command.
Vim checks the pattern against the name of
the current buffer as with FilterReadPre.
*FileType*
FileType When the 'filetype' option has been set.
<afile> can be used for the name of the file
where this option was set, and <amatch> for
the new value of 'filetype'.
See |filetypes|.
*Syntax*
Syntax When the 'syntax' option has been set.
<afile> can be used for the name of the file
where this option was set, and <amatch> for
the new value of 'syntax'.
See |:syn-on|.
*StdinReadPre*
StdinReadPre Before reading from stdin into the buffer.
Only used when the "-" argument was used when
Vim was started |--|.
*StdinReadPost*
StdinReadPost After reading from the stdin into the buffer,
before executing the modelines. Only used
when the "-" argument was used when Vim was
started |--|.
*BufWrite* *BufWritePre*
BufWrite or BufWritePre Before writing the whole buffer to a file.
*BufWritePost*
BufWritePost After writing the whole buffer to a file
(should undo the commands for BufWritePre).
*BufWriteCmd*
BufWriteCmd Before writing the whole buffer to a file.
Should do the writing of the file and reset
'modified' if successful. The buffer contents
should not be changed. |Cmd-event|
*FileWritePre*
FileWritePre Before writing to a file, when not writing the
whole buffer.
*FileWritePost*
FileWritePost After writing to a file, when not writing the
whole buffer.
*FileWriteCmd*
FileWriteCmd Before writing to a file, when not writing the
whole buffer. Should do the writing to the
file. Should not change the buffer.
|Cmd-event|
*FileAppendPre*
FileAppendPre Before appending to a file.
*FileAppendPost*
FileAppendPost After appending to a file.
*FileAppendCmd*
FileAppendCmd Before appending to a file. Should do the
appending to the file. |Cmd-event|
*FilterWritePre*
FilterWritePre Before writing a file for a filter command or
making a diff.
Vim checks the pattern against the name of
the current buffer, not the name of the
temporary file that is the output of the
filter command.
*FilterWritePost*
FilterWritePost After writing a file for a filter command or
making a diff.
Vim checks the pattern against the name of
the current buffer as with FilterWritePre.
*FileChangedShell*
FileChangedShell When Vim notices that the modification time of
a file has changed since editing started.
Also when the file attributes of the file
change. |timestamp|
Mostly triggered after executing a shell
command, but also with a |:checktime| command
or when Vim regains input focus.
This autocommand is triggered for each changed
file. It is not used when 'autoread' is set
and the buffer was not changed. If a
FileChangedShell autocommand is present the
warning message and prompt is not given.
This is useful for reloading related buffers
which are affected by a single command.
NOTE: When this autocommand is executed, the
current buffer "%" may be different from the
buffer that was changed "<afile>".
NOTE: The commands must not change the current
buffer, jump to another buffer or delete a
buffer. *E246*
NOTE: This event never nests, to avoid an
endless loop. This means that while executing
commands for the FileChangedShell event no
other FileChangedShell event will be
triggered.
*FileChangedRO*
FileChangedRO Before making the first change to a read-only
file. Can be used to check-out the file from
a source control system. Not triggered when
the change was caused by an autocommand.
WARNING: This event is triggered when making a
change, just before the change is applied to
the text. If the autocommand moves the cursor
the effect of the change is undefined.
*FocusGained*
FocusGained When Vim got input focus. Only for the GUI
version and a few console versions where this
can be detected.
*FocusLost*
FocusLost When Vim lost input focus. Only for the GUI
version and a few console versions where this
can be detected.
*FuncUndefined*
FuncUndefined When a user function is used but it isn't
defined. Useful for defining a function only
when it's used. Both <amatch> and <afile> are
set to the name of the function.
*CursorHold*
CursorHold When the user doesn't press a key for the time
specified with 'updatetime'. Not re-triggered
until the user has pressed a key (i.e. doesn't
fire every 'updatetime' ms if you leave Vim to
make some coffee. :) See |CursorHold-example|
for previewing tags.
This event is only triggered in Normal mode.
Note: Interactive commands cannot be used for
this event. There is no hit-enter prompt,
the screen is updated directly (when needed).
Note: In the future there will probably be
another option to set the time.
Hint: to force an update of the status lines
use: >
:let &ro = &ro
< {only on Amiga, Unix, Win32, MSDOS and all GUI
versions}
*BufEnter*
BufEnter After entering a buffer. Useful for setting
options for a file type. Also executed when
starting to edit a buffer, after the
BufReadPost autocommands.
*BufLeave*
BufLeave Before leaving to another buffer. Also when
leaving or closing the current window and the
new current window is not for the same buffer.
Not used for ":qa" or ":q" when exiting Vim.
*BufWinEnter*
BufWinEnter After a buffer is displayed in a window. This
can be when the buffer is loaded (after
processing the modelines), when a hidden
buffer is displayed in a window (and is no
longer hidden) or a buffer already visible in
a window is also displayed in another window.
*BufWinLeave*
BufWinLeave Before a buffer is removed from a window.
Not when it's still visible in another window.
Also triggered when exiting. It's triggered
before BufUnload or BufHidden.
NOTE: When this autocommand is executed, the
current buffer "%" may be different from the
buffer being unloaded "<afile>".
*BufUnload*
BufUnload Before unloading a buffer. This is when the
text in the buffer is going to be freed. This
may be after a BufWritePost and before a
BufDelete. Also used for all buffers that are
loaded when Vim is going to exit.
NOTE: When this autocommand is executed, the
current buffer "%" may be different from the
buffer being unloaded "<afile>".
*BufHidden*
BufHidden Just after a buffer has become hidden. That
is, when there are no longer windows that show
the buffer, but the buffer is not unloaded or
deleted. Not used for ":qa" or ":q" when
exiting Vim.
NOTE: When this autocommand is executed, the
current buffer "%" may be different from the
buffer being unloaded "<afile>".
*BufNew*
BufNew Just after creating a new buffer. Also used
just after a buffer has been renamed. When
the buffer is added to the buffer list BufAdd
will be triggered too.
NOTE: When this autocommand is executed, the
current buffer "%" may be different from the
buffer being created "<afile>".
*BufCreate* *BufAdd*
BufAdd or BufCreate Just after creating a new buffer which is
added to the buffer list, or adding a buffer
to the buffer list.
Also used just after a buffer in the buffer
list has been renamed.
The BufCreate event is for historic reasons.
NOTE: When this autocommand is executed, the
current buffer "%" may be different from the
buffer being created "<afile>".
*BufDelete*
BufDelete Before deleting a buffer from the buffer list.
The BufUnload may be called first (if the
buffer was loaded).
Also used just before a buffer in the buffer
list is renamed.
NOTE: When this autocommand is executed, the
current buffer "%" may be different from the
buffer being deleted "<afile>".
*BufWipeout*
BufWipeout Before completely deleting a buffer. The
BufUnload and BufDelete events may be called
first (if the buffer was loaded and was in the
buffer list). Also used just before a buffer
is renamed (also when it's not in the buffer
list).
NOTE: When this autocommand is executed, the
current buffer "%" may be different from the
buffer being deleted "<afile>".
*WinEnter*
WinEnter After entering another window. Not done for
the first window, when Vim has just started.
Useful for setting the window height.
If the window is for another buffer, Vim
executes the BufEnter autocommands after the
WinEnter autocommands.
Note: When using ":split fname" the WinEnter
event is triggered after the split but before
the file "fname" is loaded.
*WinLeave*
WinLeave Before leaving a window. If the window to be
entered next is for a different buffer, Vim
executes the BufLeave autocommands before the
WinLeave autocommands (but not for ":new").
Not used for ":qa" or ":q" when exiting Vim.
*CmdwinEnter*
CmdwinEnter After entering the command-line window.
Useful for setting options specifically for
this special type of window. This is
triggered _instead_ of BufEnter and WinEnter.
<afile> is set to a single character,
indicating the type of command-line.
|cmdwin-char|
*CmdwinLeave*
CmdwinLeave Before leaving the command-line window.
Useful to clean up any global setting done
with CmdwinEnter. This is triggered _instead_
of BufLeave and WinLeave.
<afile> is set to a single character,
indicating the type of command-line.
|cmdwin-char|
*GUIEnter*
GUIEnter After starting the GUI successfully, and after
opening the window. It is triggered before
VimEnter when using gvim. Can be used to
position the window from a .gvimrc file: >
:autocmd GUIEnter * winpos 100 50
< *VimEnter*
VimEnter After doing all the startup stuff, including
loading .vimrc files, executing the "-c cmd"
arguments, creating all windows and loading
the buffers in them.
*VimLeavePre*
VimLeavePre Before exiting Vim, just before writing the
.viminfo file. This is executed only once,
if there is a match with the name of what
happens to be the current buffer when exiting.
Mostly useful with a "*" pattern. >
:autocmd VimLeavePre * call CleanupStuff()
< To detect an abnormal exit use |v:dying|.
*VimLeave*
VimLeave Before exiting Vim, just after writing the
.viminfo file. Executed only once, like
VimLeavePre.
To detect an abnormal exit use |v:dying|.
*EncodingChanged*
EncodingChanged Fires off when the 'encoding' option is
changed. Useful to set up fonts, for example.
*FileEncoding*
FileEncoding Obsolete. It still works and is equivalent
to |EncodingChanged|.
*RemoteReply*
RemoteReply When a reply from a Vim that functions as
server was received |server2client()|.
<amatch> is equal to the {serverid} from which
the reply was sent, and <afile> is the actual
reply string.
Note that even if an autocommand is defined,
the reply should be read with |remote_read()|
to consume it.
*TermChanged*
TermChanged After the value of 'term' has changed. Useful
for re-loading the syntax file to update the
colors, fonts and other terminal-dependent
settings. Executed for all loaded buffers.
*TermResponse*
TermResponse After the response to |t_RV| is received from
the terminal. The value of |v:termresponse|
can be used to do things depending on the
terminal version.
*UserGettingBored*
UserGettingBored When the user hits CTRL-C. Just kidding! :-)
*User*
User Never executed automatically. To be used for
autocommands that are only executed with
":doautocmd".
You can specify a comma-separated list of event names. No white space can be
used in this list. The command applies to all the events in the list.
For READING FILES there are four kinds of events possible:
BufNewFile starting to edit a non-existent file
BufReadPre BufReadPost starting to edit an existing file
FilterReadPre FilterReadPost read the temp file with filter output
FileReadPre FileReadPost any other file read
Vim uses only one of these four kinds when reading a file. The "Pre" and
"Post" events are both triggered, before and after reading the file.
Note that the autocommands for the *ReadPre events and all the Filter events
are not allowed to change the current buffer (you will get an error message if
this happens). This is to prevent the file to be read into the wrong buffer.
Note that the 'modified' flag is reset AFTER executing the BufReadPost
and BufNewFile autocommands. But when the 'modified' option was set by the
autocommands, this doesn't happen.
You can use the 'eventignore' option to ignore a number of events or all
events.
==============================================================================
6. Patterns *autocmd-patterns* *{pat}*
The file pattern {pat} is tested for a match against the file name in one of
two ways:
1. When there is no '/' in the pattern, Vim checks for a match against only
the tail part of the file name (without its leading directory path).
2. When there is a '/' in the pattern, Vim checks for a match against the
both short file name (as you typed it) and the full file name (after
expanding it to a full path and resolving symbolic links).
Examples: >
:autocmd BufRead *.txt set et
Set the 'et' option for all text files. >
:autocmd BufRead /vim/src/*.c set cindent
Set the 'cindent' option for C files in the /vim/src directory. >
:autocmd BufRead /tmp/*.c set ts=5
If you have a link from "/tmp/test.c" to "/home/nobody/vim/src/test.c", and
you start editing "/tmp/test.c", this autocommand will match.
Note: To match part of a path, but not from the root directory, use a '*' as
the first character. Example: >
:autocmd BufRead */doc/*.txt set tw=78
This autocommand will for example be executed for "/tmp/doc/xx.txt" and
"/usr/home/piet/doc/yy.txt". The number of directories does not matter here.
The file name that the pattern is matched against is after expanding
wildcards. Thus is you issue this command: >
:e $ROOTDIR/main.$EXT
The argument is first expanded to: >
/usr/root/main.py
Before it's matched with the pattern of the autocommand. Careful with this
when using events like FileReadCmd, the value of <amatch> may not be what you
expect.
Environment variables can be used in a pattern: >
:autocmd BufRead $VIMRUNTIME/doc/*.txt set expandtab
And ~ can be used for the home directory (if $HOME is defined): >
:autocmd BufWritePost ~/.vimrc so ~/.vimrc
:autocmd BufRead ~archive/* set readonly
The environment variable is expanded when the autocommand is defined, not when
the autocommand is executed. This is different from the command!
*file-pattern*
The pattern is interpreted like mostly used in file names:
* matches any sequence of characters
? matches any single character
\? matches a '?'
. matches a '.'
~ matches a '~'
, separates patterns
\, matches a ','
{ } like \( \) in a |pattern|
, inside { }: like \| in a |pattern|
\ special meaning like in a |pattern|
[ch] matches 'c' or 'h'
[^ch] match any character but 'c' and 'h'
Note that for all systems the '/' character is used for path separator (even
MS-DOS and OS/2). This was done because the backslash is difficult to use
in a pattern and to make the autocommands portable across different systems.
Matching with the pattern is done when an event is triggered. Changing the
buffer name in one of the autocommands, or even deleting the buffer, does not
change which autocommands will be executed. Example: >
au BufEnter *.foo bdel
au BufEnter *.foo set modified
This will delete the current buffer and then set 'modified' in what has become
the current buffer instead. Vim doesn't take into account that "*.foo"
doesn't match with that buffer name. It matches "*.foo" with the name of the
buffer at the moment the event was triggered.
==============================================================================
7. Groups *autocmd-groups*
Autocommands can be put together in a group. This is useful for removing or
executing a group of autocommands. For example, all the autocommands for
syntax highlighting are put in the "highlight" group, to be able to execute
":doautoall highlight BufRead" when the GUI starts.
When no specific group is selected, Vim uses the default group. The default
group does not have a name. You cannot execute the autocommands from the
default group separately; you can execute them only by executing autocommands
for all groups.
Normally, when executing autocommands automatically, Vim uses the autocommands
for all groups. The group only matters when executing autocommands with
":doautocmd" or ":doautoall", or when defining or deleting autocommands.
The group name can contain any characters except white space. The group name
"end" is reserved (also in uppercase).
The group name is case sensitive. Note that this is different from the event
name!
*:aug* *:augroup*
:aug[roup] {name} Define the autocmd group name for the
following ":autocmd" commands. The name "end"
or "END" selects the default group.
*:augroup-delete* *E367*
:aug[roup]! {name} Delete the autocmd group {name}. Don't use
this if there is still an autocommand using
this group! This is not checked.
To enter autocommands for a specific group, use this method:
1. Select the group with ":augroup {name}".
2. Delete any old autocommands with ":au!".
3. Define the autocommands.
4. Go back to the default group with "augroup END".
Example: >
:augroup uncompress
: au!
: au BufEnter *.gz %!gunzip
:augroup END
This prevents having the autocommands defined twice (e.g., after sourcing the
.vimrc file again).
==============================================================================
8. Executing autocommands *autocmd-execute*
Vim can also execute Autocommands non-automatically. This is useful if you
have changed autocommands, or when Vim has executed the wrong autocommands
(e.g., the file pattern match was wrong).
Note that the 'eventignore' option applies here too. Events listed in this
option will not cause any commands to be executed.
*:do* *:doau* *:doautocmd* *E217*
:do[autocmd] [group] {event} [fname]
Apply the autocommands matching [fname] (default:
current file name) for {event} to the current buffer.
You can use this when the current file name does not
match the right pattern, after changing settings, or
to execute autocommands for a certain event.
It's possible to use this inside an autocommand too,
so you can base the autocommands for one extension on
another extension. Example: >
:au Bufenter *.cpp so ~/.vimrc_cpp
:au Bufenter *.cpp doau BufEnter x.c
< Be careful to avoid endless loops. See
|autocmd-nested|.
When the [group] argument is not given, Vim executes
the autocommands for all groups. When the [group]
argument is included, Vim executes only the matching
autocommands for that group. Note: if you use an
undefined group name, Vim gives you an error message.
*:doautoa* *:doautoall*
:doautoa[ll] [group] {event} [fname]
Like ":doautocmd", but apply the autocommands to each
loaded buffer. Note that {fname} is used to select
the autocommands, not the buffers to which they are
applied.
Careful: Don't use this for autocommands that delete a
buffer, change to another buffer or change the
contents of a buffer; the result is unpredictable.
This command is intended for autocommands that set
options, change highlighting, and things like that.
==============================================================================
9. Using autocommands *autocmd-use*
For WRITING FILES there are four possible sets of events. Vim uses only one
of these sets for a write command:
BufWriteCmd BufWritePre BufWritePost writing the whole buffer
FilterWritePre FilterWritePost writing to filter temp file
FileAppendCmd FileAppendPre FileAppendPost appending to a file
FileWriteCmd FileWritePre FileWritePost any other file write
When there is a matching "*Cmd" autocommand, it is assumed it will do the
writing. No further writing is done and the other events are not triggered.
|Cmd-event|
Note that the *WritePost commands should undo any changes to the buffer that
were caused by the *WritePre commands; otherwise, writing the file will have
the side effect of changing the buffer.
Before executing the autocommands, the buffer from which the lines are to be
written temporarily becomes the current buffer. Unless the autocommands
change the current buffer or delete the previously current buffer, the
previously current buffer is made the current buffer again.
The *WritePre and *AppendPre autocommands must not delete the buffer from
which the lines are to be written.
The '[ and '] marks have a special position:
- Before the *ReadPre event the '[ mark is set to the line just above where
the new lines will be inserted.
- Before the *ReadPost event the '[ mark is set to the first line that was
just read, the '] mark to the last line.
- Before executing the *WritePre and *AppendPre autocommands the '[ mark is
set to the first line that will be written, the '] mark to the last line.
Careful: '[ and '] change when using commands that change the buffer.
In commands which expect a file name, you can use "<afile>" for the file name
that is being read |:<afile>| (you can also use "%" for the current file
name). "<abuf>" can be used for the buffer number of the currently effective
buffer. This also works for buffers that doesn't have a name. But it doesn't
work for files without a buffer (e.g., with ":r file").
*gzip-example*
Examples for reading and writing compressed files: >
:augroup gzip
: autocmd!
: autocmd BufReadPre,FileReadPre *.gz set bin
: autocmd BufReadPost,FileReadPost *.gz '[,']!gunzip
: autocmd BufReadPost,FileReadPost *.gz set nobin
: autocmd BufReadPost,FileReadPost *.gz execute ":doautocmd BufReadPost " . expand("%:r")
: autocmd BufWritePost,FileWritePost *.gz !mv <afile> <afile>:r
: autocmd BufWritePost,FileWritePost *.gz !gzip <afile>:r
: autocmd FileAppendPre *.gz !gunzip <afile>
: autocmd FileAppendPre *.gz !mv <afile>:r <afile>
: autocmd FileAppendPost *.gz !mv <afile> <afile>:r
: autocmd FileAppendPost *.gz !gzip <afile>:r
:augroup END
The "gzip" group is used to be able to delete any existing autocommands with
":autocmd!", for when the file is sourced twice.
("<afile>:r" is the file name without the extension, see |:_%:|)
The commands executed for the BufNewFile, BufRead/BufReadPost, BufWritePost,
FileAppendPost and VimLeave events do not set or reset the changed flag of the
buffer. When you decompress the buffer with the BufReadPost autocommands, you
can still exit with ":q". When you use ":undo" in BufWritePost to undo the
changes made by BufWritePre commands, you can still do ":q" (this also makes
"ZZ" work). If you do want the buffer to be marked as modified, set the
'modified' option.
To execute Normal mode commands from an autocommand, use the ":normal"
command. Use with care! If the Normal mode command is not finished, the user
needs to type characters (e.g., after ":normal m" you need to type a mark
name).
If you want the buffer to be unmodified after changing it, reset the
'modified' option. This makes it possible to exit the buffer with ":q"
instead of ":q!".
*autocmd-nested* *E218*
By default, autocommands do not nest. If you use ":e" or ":w" in an
autocommand, Vim does not execute the BufRead and BufWrite autocommands for
those commands. If you do want this, use the "nested" flag for those commands
in which you want nesting. For example: >
:autocmd FileChangedShell *.c nested e!
The nesting is limited to 10 levels to get out of recursive loops.
It's possible to use the ":au" command in an autocommand. This can be a
self-modifying command! This can be useful for an autocommand that should
execute only once.
There is currently no way to disable the autocommands. If you want to write a
file without executing the autocommands for that type of file, write it under
another name and rename it with a shell command. In some situations you can
use the 'eventignore' option.
Note: When reading a file (with ":read file" or with a filter command) and the
last line in the file does not have an <EOL>, Vim remembers this. At the next
write (with ":write file" or with a filter command), if the same line is
written again as the last line in a file AND 'binary' is set, Vim does not
supply an <EOL>. This makes a filter command on the just read lines write the
same file as was read, and makes a write command on just filtered lines write
the same file as was read from the filter. For example, another way to write
a compressed file: >
:autocmd FileWritePre *.gz set bin|'[,']!gzip
:autocmd FileWritePost *.gz undo|set nobin
<
*autocommand-pattern*
You can specify multiple patterns, separated by commas. Here are some
examples: >
:autocmd BufRead * set tw=79 nocin ic infercase fo=2croq
:autocmd BufRead .letter set tw=72 fo=2tcrq
:autocmd BufEnter .letter set dict=/usr/lib/dict/words
:autocmd BufLeave .letter set dict=
:autocmd BufRead,BufNewFile *.c,*.h set tw=0 cin noic
:autocmd BufEnter *.c,*.h abbr FOR for (i = 0; i < 3; ++i)<CR>{<CR>}<Esc>O
:autocmd BufLeave *.c,*.h unabbr FOR
For makefiles (makefile, Makefile, imakefile, makefile.unix, etc.): >
:autocmd BufEnter ?akefile* set include=^s\=include
:autocmd BufLeave ?akefile* set include&
To always start editing C files at the first function: >
:autocmd BufRead *.c,*.h 1;/^{
Without the "1;" above, the search would start from wherever the file was
entered, rather than from the start of the file.
*skeleton* *template*
To read a skeleton (template) file when opening a new file: >
:autocmd BufNewFile *.c 0r ~/vim/skeleton.c
:autocmd BufNewFile *.h 0r ~/vim/skeleton.h
:autocmd BufNewFile *.java 0r ~/vim/skeleton.java
To insert the current date and time in a *.html file when writing it: >
:autocmd BufWritePre,FileWritePre *.html ks|call LastMod()|'s
:fun LastMod()
: if line("$") > 20
: let l = 20
: else
: let l = line("$")
: endif
: exe "1," . l . "g/Last modified: /s/Last modified: .*/Last modified: " .
: \ strftime("%Y %b %d")
:endfun
You need to have a line "Last modified: <date time>" in the first 20 lines
of the file for this to work. Vim replaces <date time> (and anything in the
same line after it) with the current date and time. Explanation:
ks mark current position with mark 's'
call LastMod() call the LastMod() function to do the work
's return the cursor to the old position
The LastMod() function checks if the file is shorter than 20 lines, and then
uses the ":g" command to find lines that contain "Last modified: ". For those
lines the ":s" command is executed to replace the existing date with the
current one. The ":execute" command is used to be able to use an expression
for the ":g" and ":s" commands. The date is obtained with the strftime()
function. You can change its argument to get another date string.
When entering :autocmd on the command-line, completion of events and command
names may be done (with <Tab>, CTRL-D, etc.) where appropriate.
Vim executes all matching autocommands in the order that you specify them.
It is recommended that your first autocommand be used for all files by using
"*" as the file pattern. This means that you can define defaults you like
here for any settings, and if there is another matching autocommand it will
override these. But if there is no other matching autocommand, then at least
your default settings are recovered (if entering this file from another for
which autocommands did match). Note that "*" will also match files starting
with ".", unlike Unix shells.
*autocmd-searchpat*
Autocommands do not change the current search patterns. Vim saves the current
search patterns before executing autocommands then restores them after the
autocommands finish. This means that autocommands do not affect the strings
highlighted with the 'hlsearch' option. Within autocommands, you can still
use search patterns normally, e.g., with the "n" command.
If you want an autocommand to set the search pattern, such that it is used
after the autocommand finishes, use the ":let @/ =" command.
The search-highlighting cannot be switched off with ":nohlsearch" in an
autocommand. Use the 'h' flag in the 'viminfo' option to disable search-
highlighting when starting Vim.
*Cmd-event*
When using one of the "*Cmd" events, the matching autocommands are expected to
do the file reading or writing. This can be used when working with a special
kind of file, for example on a remote system.
CAREFUL: If you use these events in a wrong way, it may have the effect of
making it impossible to read or write the matching files! Make sure you test
your autocommands properly. Best is to use a pattern that will never match a
normal file name, for example "ftp://*".
When defining a BufReadCmd it will be difficult for Vim to recover a crashed
editing session. When recovering from the original file, Vim reads only those
parts of a file that are not found in the swap file. Since that is not
possible with a BufReadCmd, use the |:preserve| command to make sure the
original file isn't needed for recovery. You might want to do this only when
you expect the file to be modified.
The |v:cmdarg| variable holds the "++enc=" and "++ff=" argument that are
effective. These should be used for the command that reads/writes the file.
The |v:cmdbang| variable is one when "!" was used, zero otherwise.
See the $VIMRUNTIME/plugin/netrw.vim for examples.
vim:tw=78:ts=8:ft=help:norl:

1425
runtime/doc/change.txt Normal file
View File

File diff suppressed because it is too large Load Diff

992
runtime/doc/cmdline.txt Normal file
View File

@@ -0,0 +1,992 @@
*cmdline.txt* For Vim version 7.0aa. Last change: 2004 Mar 31
VIM REFERENCE MANUAL by Bram Moolenaar
*Cmdline-mode* *Command-line-mode*
Command-line mode *Cmdline* *Command-line* *mode-cmdline* *:*
Command-line mode is used to enter Ex commands (":"), search patterns
("/" and "?"), and filter commands ("!").
Basic command line editing is explained in chapter 20 of the user manual
|usr_20.txt|.
1. Command-line editing |cmdline-editing|
2. Command-line completion |cmdline-completion|
3. Ex command-lines |cmdline-lines|
4. Ex command-line ranges |cmdline-ranges|
5. Ex special characters |cmdline-special|
6. Command-line window |cmdline-window|
==============================================================================
1. Command-line editing *cmdline-editing*
Normally characters are inserted in front of the cursor position. You can
move around in the command-line with the left and right cursor keys. With the
<Insert> key, you can toggle between inserting and overstriking characters.
{Vi: can only alter the last character in the line}
Note that if your keyboard does not have working cursor keys or any of the
other special keys, you can use ":cnoremap" to define another key for them.
For example, to define tcsh style editing keys: *tcsh-style* >
:cnoremap <C-A> <Home>
:cnoremap <C-F> <Right>
:cnoremap <C-B> <Left>
:cnoremap <Esc>b <S-Left>
:cnoremap <Esc>f <S-Right>
(<> notation |<>|; type all this literally)
*cmdline-too-long*
When the command line is getting longer than what fits on the screen, only the
part that fits will be shown. The cursor can only move in this visible part,
thus you cannot edit beyond that.
*cmdline-history* *history*
The command-lines that you enter are remembered in a history table. You can
recall them with the up and down cursor keys. There are actually four
history tables:
- one for ':' commands
- one for search strings
- one for expressions
- one for input lines, typed for the |input()| function.
These are completely separate. Each history can only be accessed when
entering the same type of line.
Use the 'history' option to set the number of lines that are remembered
(default: 20).
Notes:
- When you enter a command-line that is exactly the same as an older one, the
old one is removed (to avoid repeated commands moving older commands out of
the history).
- Only commands that are typed are remembered. Ones that completely come from
mappings are not put in the history
- All searches are put in the search history, including the ones that come
from commands like "*" and "#". But for a mapping, only the last search is
remembered (to avoid that long mappings trash the history).
{Vi: no history}
{not available when compiled without the |+cmdline_hist| feature}
There is an automatic completion of names on the command-line; see
|cmdline-completion|.
*c_CTRL-V*
CTRL-V Insert next non-digit literally. Up to three digits form the
decimal value of a single byte. The non-digit and the three
digits are not considered for mapping. This works the same
way as in Insert mode (see above, |i_CTRL-V|).
Note: Under Windows CTRL-V is often mapped to paste text.
Use CTRL-Q instead then.
*c_CTRL-Q*
CTRL-Q Same as CTRL-V. But with some terminals it is used for
control flow, it doesn't work then.
*c_<Left>*
<Left> cursor left
*c_<Right>*
<Right> cursor right
*c_<S-Left>*
<S-Left> or <C-Left> *c_<C-Left>*
cursor one WORD left
*c_<S-Right>*
<S-Right> or <C-Right> *c_<C-Right>*
cursor one WORD right
CTRL-B or <Home> *c_CTRL-B* *c_<Home>*
cursor to beginning of command-line
CTRL-E or <End> *c_CTRL-E* *c_<End>*
cursor to end of command-line
*c_<LeftMouse>*
<LeftMouse> cursor to position of mouse click.
CTRL-H *c_<BS>* *c_CTRL-H*
<BS> delete the character in front of the cursor (see |:fixdel| if
your <BS> key does not do what you want).
*c_<Del>*
<Del> delete the character under the cursor (at end of line:
character before the cursor) (see |:fixdel| if your <Del>
key does not do what you want).
*c_CTRL-W*
CTRL-W delete the word before the cursor
*c_CTRL-U*
CTRL-U remove all characters between the cursor position and
the beginning of the line. Previous versions of vim
deleted all characters on the line. If that is the
preferred behavior, add the following to your .vimrc: >
:cnoremap <C-U> <C-E><C-U>
<
Note: if the command-line becomes empty with one of the
delete commands, Command-line mode is quit.
*c_<Insert>*
<Insert> Toggle between insert and overstrike. {not in Vi}
{char1} <BS> {char2} or *c_digraph*
CTRL-K {char1} {char2} *c_CTRL-K*
enter digraph (see |digraphs|). When {char1} is a special
key, the code for that key is inserted in <> form. {not in Vi}
CTRL-R {0-9a-z"%#:-=.} *c_CTRL-R* *c_<C-R>*
Insert the contents of a numbered or named register. Between
typing CTRL-R and the second character '"' will be displayed
to indicate that you are expected to enter the name of a
register.
The text is inserted as if you typed it, but mappings and
abbreviations are not used. Command-line completion through
'wildchar' is not triggered though. And characters that end
the command line are inserted literally (<Esc>, <CR>, <NL>,
<C-C>). A <BS> or CTRL-W could still end the command line
though, and remaining characters will then be interpreted in
another mode, which might not be what you intended.
Special registers:
'"' the unnamed register, containing the text of
the last delete or yank
'%' the current file name
'#' the alternate file name
'*' the clipboard contents (X11: primary selection)
'+' the clipboard contents
'/' the last search pattern
':' the last command-line
'-' the last small (less than a line) delete
'.' the last inserted text
*c_CTRL-R_=*
'=' the expression register: you are prompted to
enter an expression (see |expression|)
See |registers| about registers. {not in Vi}
CTRL-R CTRL-F *c_CTRL-R_CTRL-F* *c_<C-R>_<C-F>*
CTRL-R CTRL-P *c_CTRL-R_CTRL-P* *c_<C-R>_<C-P>*
CTRL-R CTRL-W *c_CTRL-R_CTRL-W* *c_<C-R>_<C-W>*
CTRL-R CTRL-A *c_CTRL-R_CTRL-A* *c_<C-R>_<C-A>*
Insert the object under the cursor:
CTRL-F the Filename under the cursor
CTRL-P the Filename under the cursor, expanded with
'path' as in |gf|
CTRL-W the Word under the cursor
CTRL-A the WORD under the cursor; see |WORD|
{not in Vi}
CTRL-F and CTRL-P: {only when +file_in_path feature is
included}
*c_CTRL-R_CTRL-R* *c_<C-R>_<C-R>*
*c_CTRL-R_CTRL-O* *c_<C-R>_<C-O>*
CTRL-R CTRL-R {0-9a-z"%#:-=. CTRL-F CTRL-P CTRL-W CTRL-A}
CTRL-R CTRL-O {0-9a-z"%#:-=. CTRL-F CTRL-P CTRL-W CTRL-A}
Insert register or object under the cursor. Works like
|c_CTRL-R| but inserts the text literally. For example, if
register a contains "xy^Hz" (where ^H is a backspace),
"CTRL-R a" will insert "xz" while "CTRL-R CTRL-R a" will
insert "xy^Hz".
CTRL-\ e {expr} *c_CTRL-\_e*
Evaluate {expr} and replace the whole command line with the
result. You will be prompted for the expression, type <Enter>
to finish it. It's most useful in mappings though. See
|expression|.
See |c_CTRL-R_=| for inserting the result of an expression.
Useful functions are |getcmdline()| and |getcmdpos()|.
The cursor position is unchanged, except when the cursor was
at the end of the line, then it stays at the end.
|setcmdpos()| can be used to set the cursor position.
Example: >
:cmap <F7> <C-\>eAppendSome()<CR>
:func AppendSome()
:let cmd = getcmdline() . " Some()"
:" place the cursor on the )
:call setcmdpos(strlen(cmd))
:return cmd
:endfunc
<
*c_CTRL-Y*
CTRL-Y When there is a modeless selection, copy the selection into
the clipboard. |modeless-selection|
If there is no selection CTRL-Y is inserted as a character.
CTRL-J *c_CTRL-J* *c_<NL>* *c_<CR>*
<CR> or <NL> start entered command
*c_<Esc>*
<Esc> When typed and 'x' not present in 'cpoptions', quit
Command-line mode without executing. In macros or when 'x'
present in 'cpoptions', start entered command.
*c_CTRL-C*
CTRL-C quit command-line without executing
*c_<Up>*
<Up> recall older command-line from history, whose beginning
matches the current command-line (see below).
{not available when compiled without the |+cmdline_hist|
feature}
*c_<Down>*
<Down> recall more recent command-line from history, whose beginning
matches the current command-line (see below).
{not available when compiled without the |+cmdline_hist|
feature}
*c_<S-Up>* *c_<PageUp>*
<S-Up> or <PageUp>
recall older command-line from history
{not available when compiled without the |+cmdline_hist|
feature}
*c_<S-Down>* *c_<PageDown>*
<S-Down> or <PageDown>
recall more recent command-line from history
{not available when compiled without the |+cmdline_hist|
feature}
CTRL-D command-line completion (see |cmdline-completion|)
'wildchar' option
command-line completion (see |cmdline-completion|)
CTRL-N command-line completion (see |cmdline-completion|)
CTRL-P command-line completion (see |cmdline-completion|)
CTRL-A command-line completion (see |cmdline-completion|)
CTRL-L command-line completion (see |cmdline-completion|)
*c_CTRL-_*
CTRL-_ a - switch between Hebrew and English keyboard mode, which is
private to the command-line and not related to hkmap.
This is useful when Hebrew text entry is required in the
command-line, searches, abbreviations, etc. Applies only if
Vim is compiled with the |+rightleft| feature and the
'allowrevins' option is set.
See |rileft.txt|.
b - switch between Farsi and English keyboard mode, which is
private to the command-line and not related to fkmap. In
Farsi keyboard mode the characters are inserted in reverse
insert manner. This is useful when Farsi text entry is
required in the command-line, searches, abbreviations, etc.
Applies only if Vim is compiled with the |+farsi| feature.
See |farsi.txt|.
*c_CTRL-^*
CTRL-^ Toggle the use of language |:lmap| mappings and/or Input
Method.
When typing a pattern for a search command and 'imsearch' is
not -1, VAL is the value of 'imsearch', otherwise VAL is the
value of 'iminsert'.
When language mappings are defined:
- If VAL is 1 (langmap mappings used) it becomes 0 (no langmap
mappings used).
- If VAL was not 1 it becomes 1, thus langmap mappings are
enabled.
When no language mappings are defined:
- If VAL is 2 (Input Method is used) it becomes 0 (no input
method used)
- If VAL has another value it becomes 2, thus the Input Method
is enabled.
These language mappings are normally used to type characters
that are different from what the keyboard produces. The
'keymap' option can be used to install a whole number of them.
When entering a command line, langmap mappings are switched
off, since you are expected to type a command. After
switching it on with CTRL-^, the new state is not used again
for the next command or Search pattern.
{not in Vi}
For Emacs-style editing on the command-line see |emacs-keys|.
The <Up> and <Down> keys take the current command-line as a search string.
The beginning of the next/previous command-lines are compared with this
string. The first line that matches is the new command-line. When typing
these two keys repeatedly, the same string is used again. For example, this
can be used to find the previous substitute command: Type ":s" and then <Up>.
The same could be done by typing <S-Up> a number of times until the desired
command-line is shown. (Note: the shifted arrow keys do not work on all
terminals)
*his* *:history*
:his[tory] Print the history of last entered commands.
{not in Vi}
{not available when compiled without the |+cmdline_hist|
feature}
:his[tory] [{name}] [{first}][, [{last}]]
List the contents of history {name} which can be:
c[md] or : command-line history
s[earch] or / search string history
e[xpr] or = expression register history
i[nput] or @ input line history
a[ll] all of the above
{not in Vi}
If the numbers {first} and/or {last} are given, the respective
range of entries from a history is listed. These numbers can
be specified in the following form:
*:history-indexing*
A positive number represents the absolute index of an entry
as it is given in the first column of a :history listing.
This number remains fixed even if other entries are deleted.
A negative number means the relative position of an entry,
counted from the newest entry (which has index -1) backwards.
Examples:
List entries 6 to 12 from the search history: >
:history / 6,12
<
List the recent five entries from all histories: >
:history all -5,
==============================================================================
2. Command-line completion *cmdline-completion*
When editing the command-line, a few commands can be used to complete the
word before the cursor. This is available for:
- Command names: At the start of the command-line.
- Tags: Only after the ":tag" command.
- File names: Only after a command that accepts a file name or a setting for
an option that can be set to a file name. This is called file name
completion.
- Options: Only after the ":set" command.
- Mappings: Only after a ":map" or similar command.
- Variable and function names: Only after a ":if", ":call" or similar command.
When Vim was compiled with the |+cmdline_compl| feature disabled, only file
names, directories and help items can be completed.
These are the commands that can be used:
*c_CTRL-D*
CTRL-D List names that match the pattern in front of the cursor.
When showing file names, directories are highlighted (see
'highlight' option). Names where 'suffixes' matches are moved
to the end.
*c_CTRL-I* *c_wildchar* *c_<Tab>*
'wildchar' option
A match is done on the pattern in front of the cursor. The
match (if there are several, the first match) is inserted
in place of the pattern. (Note: does not work inside a
macro, because <Tab> or <Esc> are mostly used as 'wildchar',
and these have a special meaning in some macros.) When typed
again and there were multiple matches, the next
match is inserted. After the last match, the first is used
again (wrap around).
The behavior can be changed with the 'wildmode' option.
*c_CTRL-N*
CTRL-N After using 'wildchar' which got multiple matches, go to next
match. Otherwise recall more recent command-line from history.
<S-Tab> *c_CTRL-P* *c_<S-Tab>*
CTRL-P After using 'wildchar' which got multiple matches, go to
previous match. Otherwise recall older command-line from
history. <S-Tab> only works with the GUI, on the Amiga and
with MS-DOS.
*c_CTRL-A*
CTRL-A All names that match the pattern in front of the cursor are
inserted.
*c_CTRL-L*
CTRL-L A match is done on the pattern in front of the cursor. If
there is one match, it is inserted in place of the pattern.
If there are multiple matches the longest common part is
inserted in place of the pattern. If the result is shorter
than the pattern, no completion is done.
The 'wildchar' option defaults to <Tab> (CTRL-E when in Vi compatible mode; in
a previous version <Esc> was used). In the pattern standard wildcards '*' and
'?' are accepted. '*' matches any string, '?' matches exactly one character.
If you like tcsh's autolist completion, you can use this mapping:
:cnoremap X <C-L><C-D>
(Where X is the command key to use, <C-L> is CTRL-L and <C-D> is CTRL-D)
This will find the longest match and then list all matching files.
If you like tcsh's autolist completion, you can use the 'wildmode' option to
emulate it. For example, this mimics autolist=ambiguous:
:set wildmode=longest,list
This will find the longest match with the first 'wildchar', then list all
matching files with the next.
*suffixes*
For file name completion you can use the 'suffixes' option to set a priority
between files with almost the same name. If there are multiple matches,
those files with an extension that is in the 'suffixes' option are ignored.
The default is ".bak,~,.o,.h,.info,.swp,.obj", which means that files ending
in ".bak", "~", ".o", ".h", ".info", ".swp" and ".obj" are sometimes ignored.
It is impossible to ignore suffixes with two dots. Examples:
pattern: files: match: ~
test* test.c test.h test.o test.c
test* test.h test.o test.h and test.o
test* test.i test.h test.c test.i and test.c
If there is more than one matching file (after ignoring the ones matching
the 'suffixes' option) the first file name is inserted. You can see that
there is only one match when you type 'wildchar' twice and the completed
match stays the same. You can get to the other matches by entering
'wildchar', CTRL-N or CTRL-P. All files are included, also the ones with
extensions matching the 'suffixes' option.
To completely ignore files with some extension use 'wildignore'.
The old value of an option can be obtained by hitting 'wildchar' just after
the '='. For example, typing 'wildchar' after ":set dir=" will insert the
current value of 'dir'. This overrules file name completion for the options
that take a file name.
If you would like using <S-Tab> for CTRL-P in an xterm, put this command in
your .cshrc: >
xmodmap -e "keysym Tab = Tab Find"
And this in your .vimrc: >
:cmap <Esc>[1~ <C-P>
==============================================================================
3. Ex command-lines *cmdline-lines*
The Ex commands have a few specialties:
*:quote*
'"' at the start of a line causes the whole line to be ignored. '"'
after a command causes the rest of the line to be ignored. This can be used
to add comments. Example: >
:set ai "set 'autoindent' option
It is not possible to add a comment to a shell command ":!cmd" or to the
":map" command and friends, because they see the '"' as part of their
argument.
*:bar* *:\bar*
'|' can be used to separate commands, so you can give multiple commands in one
line. If you want to use '|' in an argument, precede it with '\'.
These commands see the '|' as their argument, and can therefore not be
followed by another command:
:argdo
:autocmd
:bufdo
:command
:cscope
:debug
:folddoopen
:folddoclosed
:function
:global
:help
:helpfind
:make
:normal
:perl
:perldo
:promptfind
:promptrepl
:pyfile
:python
:registers
:read !
:scscope
:tcl
:tcldo
:tclfile
:vglobal
:windo
:write !
:[range]!
a user defined command without the "-bar" argument |:command|
Note that this is confusing (inherited from Vi): With ":g" the '|' is included
in the command, with ":s" it is not.
To be able to use another command anyway, use the ":execute" command.
Example (append the output of "ls" and jump to the first line): >
:execute 'r !ls' | '[
There is one exception: When the 'b' flag is present in 'cpoptions', with the
":map" and ":abbr" commands and friends CTRL-V needs to be used instead of
'\'. You can also use "<Bar>" instead. See also |map_bar|.
Examples: >
:!ls | wc view the output of two commands
:r !ls | wc insert the same output in the text
:%g/foo/p|> moves all matching lines one shiftwidth
:%s/foo/bar/|> moves one line one shiftwidth
:map q 10^V| map "q" to "10|"
:map q 10\| map \ l map "q" to "10\" and map "\" to "l"
(when 'b' is present in 'cpoptions')
You can also use <NL> to separate commands in the same way as with '|'. To
insert a <NL> use CTRL-V CTRL-J. "^@" will be shown. Using '|' is the
preferred method. But for external commands a <NL> must be used, because a
'|' is included in the external command. To avoid the special meaning of <NL>
it must be preceded with a backslash. Example: >
:r !date<NL>-join
This reads the current date into the file and joins it with the previous line.
Note that when the command before the '|' generates an error, the following
commands will not be executed.
Because of Vi compatibility the following strange commands are supported: >
:| print current line (like ":p")
:3| print line 3 (like ":3p")
:3 goto line 3
A colon is allowed between the range and the command name. It is ignored
(this is Vi compatible). For example: >
:1,$:s/pat/string
When the character '%' or '#' is used where a file name is expected, they are
expanded to the current and alternate file name (see the chapter "editing
files" |:_%| |:_#|).
Embedded spaces in file names are allowed on the Amiga if one file name is
expected as argument. Trailing spaces will be ignored, unless escaped with a
backslash or CTRL-V. Note that the ":next" command uses spaces to separate
file names. Escape the spaces to include them in a file name. Example: >
:next foo\ bar goes\ to school\
starts editing the three files "foo bar", "goes to" and "school ".
When you want to use the special characters '"' or '|' in a command, or want
to use '%' or '#' in a file name, precede them with a backslash. The
backslash is not required in a range and in the ":substitute" command.
*:_!*
The '!' (bang) character after an Ex command makes the command behave in a
different way. The '!' should be placed immediately after the command, without
any blanks in between. If you insert blanks the '!' will be seen as an
argument for the command, which has a different meaning. For example:
:w! name write the current buffer to file "name", overwriting
any existing file
:w !name send the current buffer as standard input to command
"name"
==============================================================================
4. Ex command-line ranges *cmdline-ranges* *[range]* *E16* *E493*
Some Ex commands accept a line range in front of them. This is noted as
[range]. It consists of one or more line specifiers, separated with ',' or
';'.
The basics are explained in section |10.3| of the user manual.
*:,* *:;*
When separated with ';' the cursor position will be set to that line
before interpreting the next line specifier. This doesn't happen for ','.
Examples: >
4,/this line/
< from line 4 till match with "this line" after the cursor line. >
5;/that line/
< from line 5 till match with "that line" after line 5.
The default line specifier for most commands is the cursor position, but the
commands ":write" and ":global" have the whole file (1,$) as default.
If more line specifiers are given than required for the command, the first
one(s) will be ignored.
Line numbers may be specified with: *:range* *E14* *{address}*
{number} an absolute line number
. the current line *:.*
$ the last line in the file *:$*
% equal to 1,$ (the entire file) *:%*
't position of mark t (lowercase) *:'*
'T position of mark T (uppercase); when the mark is in
another file it cannot be used in a range
/{pattern}[/] the next line where {pattern} matches *:/*
?{pattern}[?] the previous line where {pattern} matches *:?*
\/ the next line where the previously used search
pattern matches
\? the previous line where the previously used search
pattern matches
\& the next line where the previously used substitute
pattern matches
Each may be followed (several times) by '+' or '-' and an optional number.
This number is added or subtracted from the preceding line number. If the
number is omitted, 1 is used.
The "/" and "?" after {pattern} are required to separate the pattern from
anything that follows.
The "/" and "?" may be preceded with another address. The search starts from
there. The difference from using ';' is that the cursor isn't moved.
Examples: >
/pat1//pat2/ Find line containing "pat2" after line containing
"pat1", without moving the cursor.
7;/pat2/ Find line containing "pat2", after line 7, leaving
the cursor in line 7.
The {number} must be between 0 and the number of lines in the file. When
using a 0 (zero) this is interpreted as a 1 by most commands. Commands that
use it as a count do use it as a zero (|:tag|, |:pop|, etc). Some commands
interpret the zero as "before the first line" (|:read|, search pattern, etc).
Examples: >
.+3 three lines below the cursor
/that/+1 the line below the next line containing "that"
.,$ from current line until end of file
0;/that the first line containing "that", also matches in the
first line.
1;/that the first line after line 1 containing "that"
Some commands allow for a count after the command. This count is used as the
number of lines to be used, starting with the line given in the last line
specifier (the default is the cursor line). The commands that accept a count
are the ones that use a range but do not have a file name argument (because
a file name can also be a number).
Examples: >
:s/x/X/g 5 substitute 'x' by 'X' in the current line and four
following lines
:23d 4 delete lines 23, 24, 25 and 26
Folds and Range
When folds are active the line numbers are rounded off to include the whole
closed fold. See |fold-behavior|.
Reverse Range
A range should have the lower line number first. If this is not the case, Vim
will ask you if it should swap the line numbers. This is not done within the
global command ":g".
Count and Range *N:*
When giving a count before entering ":", this is translated into:
:.,.+(count - 1)
In words: The 'count' lines at and after the cursor. Example: To delete
three lines: >
3:d<CR> is translated into: .,.+2d<CR>
<
Visual Mode and Range *v_:*
{Visual}: Starts a command-line with the Visual selected lines as a
range. The code ":'<,'>" is used for this range, which makes
it possible to select a similar line from the command-line
history for repeating a command on different Visually selected
lines.
==============================================================================
5. Ex special characters *cmdline-special*
In Ex commands, at places where a file name can be used, the following
characters have a special meaning. These can also be used in the expression
function expand() |expand()|.
% is replaced with the current file name *:_%*
# is replaced with the alternate file name *:_#*
#n (where n is a number) is replaced with the file name of
buffer n. "#0" is the same as "#"
## is replaced with all names in the argument list *:_##*
concatenated, separated by spaces. Each space in a name
is preceded with a backslash.
Note that these give the file name as it was typed. If an absolute path is
needed (when using the file name from a different directory), you need to add
":p". See |filename-modifiers|.
Note that backslashes are inserted before spaces, so that the command will
correctly interpret the file name. But this doesn't happen for shell
commands. For those you probably have to use quotes: >
:!ls "%"
:r !spell "%"
To avoid the special meaning of '%' and '#' insert a backslash before it.
Detail: The special meaning is always escaped when there is a backslash before
it, no matter how many backslashes.
you type: result ~
# alternate.file
\# #
\\# \#
*:<cword>* *:<cWORD>* *:<cfile>* *<cfile>*
*:<sfile>* *<sfile>* *:<afile>* *<afile>*
*:<abuf>* *<abuf>* *:<amatch>* *<amatch>*
*E495* *E496* *E497* *E498* *E499* *E500*
Note: these are typed literally, they are not special keys!
<cword> is replaced with the word under the cursor (like |star|)
<cWORD> is replaced with the WORD under the cursor (see |WORD|)
<cfile> is replaced with the path name under the cursor (like what
|gf| uses)
<afile> when executing autocommands, is replaced with the file name
for a file read or write
<abuf> when executing autocommands, is replaced with the currently
effective buffer number (for ":r file" it is the current
buffer, the file being read is not in a buffer).
<amatch> when executing autocommands, is replaced with the match for
which this autocommand was executed. It differs form
<afile> only when the file name isn't used to match with
(for FileType and Syntax events).
<sfile> when executing a ":source" command, is replaced with the
file name of the sourced file;
when executing a function, is replaced with
"function {function-name}"; function call nesting is
indicated like this:
"function {function-name1}..{function-name2}". Note that
filename-modifiers are useless when <sfile> is used inside
a function.
*filename-modifiers*
*:_%:* *::8* *::p* *::.* *::~* *::h* *::t* *::r* *::e* *::s* *::gs*
The file name modifiers can be used after "%", "#", "#n", "<cfile>", "<sfile>",
"<afile>" or "<abuf>". They are also used with the |fnamemodify()| function.
These are not available when Vim has been compiled without the |+modify_fname|
feature.
These modifiers can be given, in this order:
:p Make file name a full path. Must be the first modifier. Also
changes "~/" (and "~user/" for Unix and VMS) to the path for
the home directory. If the name is a directory a path
separator is added at the end. For a file name that does not
exist and does not have an absolute path the result is
unpredictable.
:8 Converts the path to 8.3 short format (currently only on
win32). Will act on as much of a path that is an existing
path.
:~ Reduce file name to be relative to the home directory, if
possible. File name is unmodified if it is not below the home
directory.
:. Reduce file name to be relative to current directory, if
possible. File name is unmodified if it is not below the
current directory.
For maximum shortness, use ":~:.".
:h Head of the file name (the last component and any separators
removed). Cannot be used with :e, :r or :t.
Can be repeated to remove several components at the end.
When the file name ends in a path separator, only the path
separator is removed. Thus ":p:h" on a directory name results
on the directory name itself (without trailing slash).
When the file name is an absolute path (starts with "/" for
Unix; "x:\" for MS-DOS, WIN32, OS/2; "drive:" for Amiga), that
part is not removed. When there is no head (path is relative
to current directory) the result is empty.
:t Tail of the file name (last component of the name). Must
precede any :r or :e.
:r Root of the file name (the last extension removed). When
there is only an extension (file name that starts with '.',
e.g., ".vimrc"), it is not removed. Can be repeated to remove
several extensions (last one first).
:e Extension of the file name. Only makes sense when used alone.
When there is no extension the result is empty.
When there is only an extension (file name that starts with
'.'), the result is empty. Can be repeated to include more
extensions. If there are not enough extensions (but at least
one) as much as possible are included.
:s?pat?sub?
Substitute the first occurrence of "pat" with "sub". This
works like the |:s| command. "pat" is a regular expression.
Any character can be used for '?', but it must not occur in
"pat" or "sub".
After this, the previous modifiers can be used again. For
example ":p", to make a full path after the substitution.
:gs?pat?sub?
Substitute all occurrences of "path" with "sub". Otherwise
this works like ":s".
Examples, when the file name is "src/version.c", current dir
"/home/mool/vim": >
:p /home/mool/vim/src/version.c
:p:. src/version.c
:p:~ ~/vim/src/version.c
:h src
:p:h /home/mool/vim/src
:p:h:h /home/mool/vim
:t version.c
:p:t version.c
:r src/version
:p:r /home/mool/vim/src/version
:t:r version
:e c
:s?version?main? src/main.c
:s?version?main?:p /home/mool/vim/src/main.c
:p:gs?/?\\? \home\mool\vim\src\version.c
Examples, when the file name is "src/version.c.gz": >
:p /home/mool/vim/src/version.c.gz
:e gz
:e:e c.gz
:e:e:e c.gz
:e:e:r c
:r src/version.c
:r:e c
:r:r src/version
:r:r:r src/version
<
*extension-removal* *:_%<*
If a "<" is appended to "%", "#", "#n" or "CTRL-V p" the extension of the file
name is removed (everything after and including the last '.' in the file
name). This is included for backwards compatibility with version 3.0, the
":r" form is preferred. Examples: >
% current file name
%< current file name without extension
# alternate file name for current window
#< idem, without extension
#31 alternate file number 31
#31< idem, without extension
<cword> word under the cursor
<cWORD> WORD under the cursor (see |WORD|)
<cfile> path name under the cursor
<cfile>< idem, without extension
Note: Where a file name is expected wildcards expansion is done. On Unix the
shell is used for this, unless it can be done internally (for speed).
Backticks also work, like in >
:n `echo *.c`
(backtick expansion is not possible in |restricted-mode|)
But expansion is only done if there are any wildcards before expanding the
'%', '#', etc.. This avoids expanding wildcards inside a file name. If you
want to expand the result of <cfile>, add a wildcard character to it.
Examples: (alternate file name is "?readme?")
command expands to ~
:e # :e ?readme?
:e `ls #` :e {files matching "?readme?"}
:e #.* :e {files matching "?readme?.*"}
:cd <cfile> :cd {file name under cursor}
:cd <cfile>* :cd {file name under cursor plus "*" and then expanded}
When the expanded argument contains a "!" and it is used for a shell command
(":!cmd", ":r !cmd" or ":w !cmd"), it is escaped with a backslash to avoid it
being expanded into a previously used command. When the 'shell' option
contains "sh", this is done twice, to avoid the shell trying to expand the
"!".
*filename-backslash*
For filesystems that use a backslash as directory separator (MS-DOS, Windows,
OS/2), it's a bit difficult to recognize a backslash that is used to escape
the special meaning of the next character. The general rule is: If the
backslash is followed by a normal file name character, it does not have a
special meaning. Therefore "\file\foo" is a valid file name, you don't have
to type the backslash twice.
An exception is the '$' sign. It is a valid character in a file name. But
to avoid a file name like "$home" to be interpreted as an environment variable,
it needs to be preceded by a backslash. Therefore you need to use "/\$home"
for the file "$home" in the root directory. A few examples:
FILE NAME INTERPRETED AS ~
$home expanded to value of environment var $home
\$home file "$home" in current directory
/\$home file "$home" in root directory
\\$home file "\\", followed by expanded $home
==============================================================================
6. Command-line window *cmdline-window* *cmdwin*
In the command-line window the command line can be edited just like editing
text in any window. It is a special kind of window, because you cannot leave
it in a normal way.
{not available when compiled without the |+cmdline_hist| or |+vertsplit|
feature}
OPEN
There are two ways to open the command-line window:
1. From Command-line mode, use the key specified with the 'cedit' option.
The default is CTRL-F when 'compatible' is not set.
2. From Normal mode, use the "q:", "q/" or "q?" command. *q:* *q/* *q?*
This starts editing an Ex command-line ("q:") or search string ("q/" or
"q?"). Note that this is not possible while recording is in progress (the
"q" stops recording then).
When the window opens it is filled with the command-line history. The last
line contains the command as typed so far. The left column will show a
character that indicates the type of command-line being edited, see
|cmdwin-char|.
Vim will be in Normal mode when the editor is opened, except when 'insertmode'
is set.
The height of the window is specified with 'cmdwinheight' (or smaller if there
is no room). The window is always full width and is positioned just above the
command-line.
EDIT
You can now use commands to move around and edit the text in the window. Both
in Normal mode and Insert mode.
It is possible to use ":", "/" and other commands that use the command-line,
but it's not possible to open another command-line window then. There is no
nesting.
*E11*
The command-line window is not a normal window. It is not possible to move to
another window or edit another buffer. All commands that would do this are
disabled in the command-line window. Of course it _is_ possible to execute
any command that you entered in the command-line window.
CLOSE *E199*
There are several ways to leave the command-line window:
<CR> Execute the command-line under the cursor. Works both in
Insert and in Normal mode.
CTRL-C Continue in Command-line mode. The command-line under the
cursor is used as the command-line. Works both in Insert and
in Normal mode. ":close" also works. There is no redraw,
thus the window will remain visible.
:quit Discard the command line and go back to Normal mode.
":exit", ":xit" and CTRL-\ CTRL-N also work.
:qall Quit Vim, unless there are changes in some buffer.
:qall! Quit Vim, discarding changes to any buffer.
Once the command-line window is closed the old window sizes are restored. The
executed command applies to the window and buffer where the command-line was
started from. This works as if the command-line window was not there, except
that there will be an extra screen redraw.
The buffer used for the command-line window is deleted. Any changes to lines
other than the one that is executed with <CR> are lost.
VARIOUS
The command-line window cannot be used:
- when there already is a command-line window (no nesting)
- for entering a encryption key or when using inputsecret()
- when Vim was not compiled with the +vertsplit feature
Some options are set when the command-line window is opened:
'filetype' "vim", when editing an Ex command-line; this starts Vim syntax
highlighting if it was enabled
'rightleft' off
'modifiable' on
'buftype' "nofile"
'swapfile' off
It is allowed to write the buffer contents to a file. This is an easy way to
save the command-line history and read it back later.
If the 'wildchar' option is set to <Tab>, and the command-line window is used
for an Ex command, then two mappings will be added to use <Tab> for completion
in the command-line window, like this: >
:imap <buffer> <Tab> <C-X><C-V>
:nmap <buffer> <Tab> a<C-X><C-V>
Note that hitting <Tab> in Normal mode will do completion on the next
character. That way it works at the end of the line.
If you don't want these mappings, disable them with: >
au CmdwinEnter [:>] iunmap <Tab>
au CmdwinEnter [:>] nunmap <Tab>
You could put these lines in your vimrc file.
While in the command-line window you cannot use the mouse to put the cursor in
another window, or drag statuslines of other windows. You can drag the
statusline of the command-line window itself and the statusline above it.
Thus you can resize the command-line window, but not others.
AUTOCOMMANDS
Two autocommand events are used: |CmdwinEnter| and |CmdwinLeave|. Since this
window is of a special type, the WinEnter, WinLeave, BufEnter and BufLeave
events are not triggered. You can use the Cmdwin events to do settings
specifically for the command-line window. Be careful not to cause side
effects!
Example: >
:au CmdwinEnter : let b:cpt_save = &cpt | set cpt=v
:au CmdwinLeave : let &cpt = b:cpt_save
This sets 'complete' to use command-line completion in Insert mode for CTRL-N.
Another example: >
:au CmdwinEnter [/?] startinsert
This will make Vim start in Insert mode in the command-line window.
*cmdwin-char*
The character used for the pattern indicates the type of command-line:
: normal Ex command
> debug mode command |debug-mode|
/ forward search string
? backward search string
= expression for "= |expr-register|
@ string for |input()|
- text for |:insert| or |:append|
vim:tw=78:ts=8:ft=help:norl:

135
runtime/doc/debugger.txt Normal file
View File

@@ -0,0 +1,135 @@
*debugger.txt* For Vim version 7.0aa. Last change: 2001 Dec 22
VIM REFERENCE MANUAL by Gordon Prieur
Debugger Support Features *debugger-support*
1. Debugger Features |debugger-features|
2. Vim Compile Options |debugger-compilation|
3. Integrated Debuggers |debugger-integration|
{Vi does not have any of these features}
==============================================================================
1. Debugger Features *debugger-features*
The following features are available for an integration with a debugger or
an Integrated Programming Environment (IPE) or Integrated Development
Environment (IDE):
Alternate Command Input |alt-input|
Debug Signs |debug-signs|
Debug Source Highlight |debug-highlight|
Message Footer |gui-footer|
Balloon Evaluation |balloon-eval|
These features were added specifically for use in the Motif version of gvim.
However, the |alt-input| and |debug-highlight| were written to be usable in
both vim and gvim. Some of the other features could be used in the non-GUI
vim with slight modifications. However, I did not do this nor did I test the
reliability of building for vim or non Motif GUI versions.
1.1 Alternate Command Input *alt-input*
For Vim to work with a debugger there must be at least an input connection
with a debugger or external tool. In many cases there will also be an output
connection but this isn't absolutely necessary.
The purpose of the input connection is to let the external debugger send
commands to Vim. The commands sent by the debugger should give the debugger
enough control to display the current debug environment and state.
The current implementation is based on the X Toolkit dispatch loop and the
XtAddInput() function call.
1.2 Debug Signs *debug-signs*
Many debuggers mark specific lines by placing a small sign or color highlight
on the line. The |:sign| command lets the debugger set this graphic mark. Some
examples where this feature would be used would be a debugger showing an arrow
representing the Program Counter (PC) of the program being debugged. Another
example would be a small stop sign for a line with a breakpoint. These visible
highlights let the user keep track of certain parts of the state of the
debugger.
This feature can be used with more than debuggers, too. An IPE can use a sign
to highlight build errors, searched text, or other things. The sign feature
can also work together with the |debug-highlight| to ensure the mark is
highly visible.
Debug signs are defined and placed using the |:sign| command.
1.3 Debug Source Highlight *debug-highlight*
This feature allows a line to have a predominant highlight. The highlight is
intended to make a specific line stand out. The highlight could be made to
work for both vim and gvim, whereas the debug sign is, in most cases, limited
to gvim. The one exception to this is Sun Microsystem's dtterm. The dtterm
from Sun has a "sign gutter" for showing signs.
1.4 Message Footer *gui-footer*
The message footer can be used to display messages from a debugger or IPE. It
can also be used to display menu and toolbar tips. The footer area is at the
bottom of the GUI window, below the line used to display colon commands.
The display of the footer is controlled by the 'guioptions' letter 'F'.
1.5 Balloon Evaluation *balloon-eval*
This feature allows a debugger, or other external tool, to display dynamic
information based on where the mouse is pointing. The purpose of this feature
was to allow Sun's Visual WorkShop debugger to display expression evaluations.
However, the feature was implemented in as general a manner as possible and
could be used for displaying other information as well.
The Balloon Evaluation has some settable parameters too. The font list and
colors can be set via X resources (XmNballoonEvalFontList,
XmNballoonEvalBackground, and XmNballoonEvalForeground).
The 'balloondelay' option sets the delay before an attempt is made to show a
balloon.
The 'ballooneval' option needs to be set to switch it on.
Balloon evaluation is only available when compiled with the |+balloon_eval|
and |+sun_workshop| features.
The Balloon evaluation functions are also used to show a tooltip for the
toolbar. The 'ballooneval' option does not need to be set for this. But the
other settings apply.
==============================================================================
2. Vim Compile Options *debugger-compilation*
The debugger features were added explicitly for use with Sun's Visual
WorkShop Integrated Programming Environment (ipe). However, they were done
in as generic a manner as possible so that integration with other debuggers
could also use some or all of the tools used with Sun's ipe.
The following compile time preprocessor variables control the features:
Alternate Command Input ALT_X_INPUT
Debug Glyphs FEAT_SIGNS
Debug Highlights FEAT_SIGNS
Message Footer FEAT_FOOTER
Balloon Evaluation FEAT_BEVAL
The first integration with a full IPE/IDE was with Sun Visual WorkShop. To
compile a gvim which interfaces with VWS set the following flag, which sets
all the above flags:
Sun Visual WorkShop FEAT_SUN_WORKSHOP
==============================================================================
3. Integrated Debuggers *debugger-integration*
Currently the only fully integrated debugger/IPE/IDE is Sun's Visual WorkShop
Integrated Programming Environment.
vim:tw=78:sw=4:ts=8:ft=help:norl:

384
runtime/doc/develop.txt Normal file
View File

@@ -0,0 +1,384 @@
*develop.txt* For Vim version 7.0aa. Last change: 2004 Jan 17
VIM REFERENCE MANUAL by Bram Moolenaar
Development of Vim. *development*
This text is important for those who want to be involved in further developing
Vim.
1. Design goals |design-goals|
2. Coding style |coding-style|
3. Design decisions |design-decisions|
4. Assumptions |design-assumptions|
See the file README.txt in the "src" directory for an overview of the source
code.
Vim is open source software. Everybody is encouraged to contribute to help
improving Vim. For sending patches a context diff "diff -c" is preferred.
Also see http://www.vim.org/tips/tip.php?tip_id=618.
==============================================================================
1. Design goals *design-goals*
Most important things come first (roughly).
Note that quite a few items are contradicting. This is intentional. A
balance must be found between them.
VIM IS... VI COMPATIBLE *design-compatible*
First of all, it should be possible to use Vim as a drop-in replacement for
Vi. When the user wants to, he can use Vim in compatible mode and hardly
notice any difference with the original Vi.
Exceptions:
- We don't reproduce obvious Vi bugs in Vim.
- There are different versions of Vi. I am using Version 3.7 (6/7/85) as a
reference. But support for other versions is also included when possible.
The Vi part of POSIX is not considered a definitive source.
- Vim adds new commands, you cannot rely on some command to fail because it
didn't exist in Vi.
- Vim will have a lot of features that Vi doesn't have. Going back from Vim
to Vi will be a problem, this cannot be avoided.
- Some things are hardly ever used (open mode, sending an e-mail when
crashing, etc.). Those will only be included when someone has a good reason
why it should be included and it's not too much work.
- For some items it is debatable whether Vi compatibility should be
maintained. There will be an option flag for these.
VIM IS... IMPROVED *design-improved*
The IMproved bits of Vim should make it a better Vi, without becoming a
completely different editor. Extensions are done with a "Vi spirit".
- Use the keyboard as much as feasible. The mouse requires a third hand,
which we don't have. Many terminals don't have a mouse.
- When the mouse is used anyway, avoid the need to switch back to the
keyboard. Avoid mixing mouse and keyboard handling.
- Add commands and options in a consistent way. Otherwise people will have a
hard time finding and remembering them. Keep in mind that more commands and
options will be added later.
- A feature that people do not know about is a useless feature. Don't add
obscure features, or at least add hints in documentation that they exists.
- Minimize using CTRL and other modifiers, they are more difficult to type.
- There are many first-time and inexperienced Vim users. Make it easy for
them to start using Vim and learn more over time.
- There is no limit to the features that can be added. Selecting new features
is one based on (1) what users ask for, (2) how much effort it takes to
implement and (3) someone actually implementing it.
VIM IS... MULTI PLATFORM *design-multi-platform*
Vim tries to help as many users on as many platforms as possible.
- Support many kinds of terminals. The minimal demands are cursor positioning
and clear-screen. Commands should only use key strokes that most keyboards
have. Support all the keys on the keyboard for mapping.
- Support many platforms. A condition is that there is someone willing to do
Vim development on that platform, and it doesn't mean messing up the code.
- Support many compilers and libraries. Not everybody is able or allowed to
install another compiler or GUI library.
- People switch from one platform to another, and from GUI to terminal
version. Features should be present in all versions, or at least in as many
as possible with a reasonable effort. Try to avoid that users must switch
between platforms to accomplish their work efficiently.
- That a feature is not possible on some platforms, or only possible on one
platform, does not mean it cannot be implemented. [This intentionally
contradicts the previous item, these two must be balanced.]
VIM IS... WELL DOCUMENTED *design-documented*
- A feature that isn't documented is a useless feature. A patch for a new
feature must include the documentation.
- Documentation should be comprehensive and understandable. Using examples is
recommended.
- Don't make the text unnecessarily long. Less documentation means that an
item is easier to find.
VIM IS... HIGH SPEED AND SMALL IN SIZE *design-speed-size*
Using Vim must not be a big attack on system resources. Keep it small and
fast.
- Computers are becoming faster and bigger each year. Vim can grow too, but
no faster than computers are growing. Keep Vim usable on older systems.
- Many users start Vim from a shell very often. Startup time must be short.
- Commands must work efficiently. The time they consume must be as small as
possible. Useful commands may take longer.
- Don't forget that some people use Vim over a slow connection. Minimize the
communication overhead.
- Items that add considerably to the size and are not used by many people
should be a feature that can be disabled.
- Vim is a component among other components. Don't turn it into a massive
application, but have it work well together with other programs.
VIM IS... MAINTAINABLE *design-maintain*
- The source code should not become a mess. It should be reliable code.
- Use the same layout in all files to make it easy to read |coding-style|.
- Use comments in a useful way!
- Porting to another platform should be made easy, without having to change
too much platform-independent code.
- Use the object-oriented spirit: Put data and code together. Minimize the
knowledge spread to other parts of the code.
VIM IS... FLEXIBLE *design-flexible*
Vim should make it easy for users to work in their preferred styles rather
than coercing its users into particular patterns of work. This can be for
items with a large impact (e.g., the 'compatible' option) or for details. The
defaults are carefully chosen such that most users will enjoy using Vim as it
is. Commands and options can be used to adjust Vim to the desire of the user
and its environment.
VIM IS... NOT *design-not*
- Vim is not a shell or an Operating System. You will not be able to run a
shell inside Vim or use it to control a debugger. This should work the
other way around: Use Vim as a component from a shell or in an IDE.
A satirical way to say this: "Unlike Emacs, Vim does not attempt to include
everything but the kitchen sink, but some people say that you can clean one
with it. ;-)"
- Vim is not a fancy GUI editor that tries to look nice at the cost of
being less consistent over all platforms. But functional GUI features are
welcomed.
==============================================================================
2. Coding style *coding-style*
These are the rules to use when making changes to the Vim source code. Please
stick to these rules, to keep the sources readable and maintainable.
This list is not complete. Look in the source code for more examples.
MAKING CHANGES *style-changes*
The basic steps to make changes to the code:
1. Adjust the documentation. Doing this first gives you an impression of how
your changes affect the user.
2. Make the source code changes.
3. Check ../doc/todo.txt if the change affects any listed item.
4. Make a patch with "diff -c" against the unmodified code and docs.
5. Make a note about what changed and include it with the patch.
USE OF COMMON FUNCTIONS *style-functions*
Some functions that are common to use, have a special Vim version. Always
consider using the Vim version, because they were introduced with a reason.
NORMAL NAME VIM NAME DIFFERENCE OF VIM VERSION
free() vim_free() Checks for freeing NULL
malloc() alloc() Checks for out of memory situation
malloc() lalloc() Like alloc(), but has long argument
strcpy() STRCPY() Includes cast to (char *), for char_u * args
strchr() vim_strchr() Accepts special characters
strrchr() vim_strrchr() Accepts special characters
isspace() vim_isspace() Can handle characters > 128
iswhite() vim_iswhite() Only TRUE for Tab and space
memcpy() vim_memmove() Handles overlapped copies
bcopy() vim_memmove() Handles overlapped copies
memset() vim_memset() Uniform for all systems
NAMES *style-names*
Function names can not be more than 31 characters long (because of VMS).
Don't use "delete" as a variable name, C++ doesn't like it.
Because of the requirement that Vim runs on as many systems as possible, we
need to avoid using names that are already defined by the system. This is a
list of names that are known to cause trouble. The name is given as a regexp
pattern.
is.*() POSIX, ctype.h
to.*() POSIX, ctype.h
d_.* POSIX, dirent.h
l_.* POSIX, fcntl.h
gr_.* POSIX, grp.h
pw_.* POSIX, pwd.h
sa_.* POSIX, signal.h
mem.* POSIX, string.h
str.* POSIX, string.h
wcs.* POSIX, string.h
st_.* POSIX, stat.h
tms_.* POSIX, times.h
tm_.* POSIX, time.h
c_.* POSIX, termios.h
MAX.* POSIX, limits.h
__.* POSIX, system
_[A-Z].* POSIX, system
E[A-Z0-9]* POSIX, errno.h
*_t POSIX, for typedefs. Use *_T instead.
wait don't use as argument to a function, conflicts with types.h
index shadows global declaration
time shadows global declaration
new C++ reserved keyword
try Borland C++ doesn't like it to be used as a variable.
basename() GNU string function
dirname() GNU string function
get_env_value() Linux system function
VARIOUS *style-various*
Typedef'ed names should end in "_t": >
typedef int some_t;
Define'ed names should be uppercase: >
#define SOME_THING
Features always start with "FEAT_": >
#define FEAT_FOO
Don't use '\"', some compilers can't handle it. '"' works fine.
Don't use:
#if HAVE_SOME
Some compilers can't handle that and complain that "HAVE_SOME" is not defined.
Use
#ifdef HAVE_SOME
or
#if defined(HAVE_SOME)
STYLE *style-examples*
General rule: One statement per line.
Wrong: if (cond) a = 1;
OK: if (cond)
a = 1;
Wrong: while (cond);
OK: while (cond)
;
Wrong: do a = 1; while (cond);
OK: do
a = 1;
while (cond);
Functions start with:
Wrong: int function_name(int arg1, int arg2)
OK: /*
* Explanation of what this function is used for.
*
* Return value explanation.
*/
int
function_name(arg1, arg2)
int arg1; /* short comment about arg1 */
int arg2; /* short comment about arg2 */
{
int local; /* comment about local */
local = arg1 * arg2;
NOTE: Don't use ANSI style function declarations. A few people still have to
use a compiler that doesn't support it.
SPACES AND PUNCTUATION *style-spaces*
No space between a function name and the bracket:
Wrong: func (arg);
OK: func(arg);
Do use a space after if, while, switch, etc.
Wrong: if(arg) for(;;)
OK: if (arg) for (;;)
Use a space after a comma and semicolon:
Wrong: func(arg1,arg2); for (i = 0;i < 2;++i)
OK: func(arg1, arg2); for (i = 0; i < 2; ++i)
Use a space before and after '=', '+', '/', etc.
Wrong: var=a*5;
OK: var = a * 5;
In general: Use empty lines to group lines of code together. Put a comment
just above the group of lines. This makes it more easy to quickly see what is
being done.
OK: /* Prepare for building the table. */
get_first_item();
table_idx = 0;
/* Build the table */
while (has_item())
table[table_idx++] = next_item();
/* Finish up. */
cleanup_items();
generate_hash(table);
==============================================================================
3. Design decisions *design-decisions*
Folding
Several forms of folding should be possible for the same buffer. For example,
have one window that shows the text with function bodies folded, another
window that shows a function body.
Folding is a way to display the text. It should not change the text itself.
Therefore the folding has been implemented as a filter between the text stored
in a buffer (buffer lines) and the text displayed in a window (logical lines).
Naming the window
The word "window" is commonly used for several things: A window on the screen,
the xterm window, a window inside Vim to view a buffer.
To avoid confusion, other items that are sometimes called window have been
given another name. Here is an overview of the related items:
screen The whole display. For the GUI it's something like 1024x768
pixels. The Vim shell can use the whole screen or part of it.
shell The Vim application. This can cover the whole screen (e.g.,
when running in a console) or part of it (xterm or GUI).
window View on a buffer. There can be several windows in Vim,
together with the command line, menubar, toolbar, etc. they
fit in the shell.
To be continued...
==============================================================================
4. Assumptions *design-assumptions*
Size of variables:
char 8 bit signed
char_u 8 bit unsigned
int 16, 32 or 64 bit signed
unsigned 16, 32 or 64 bit unsigned
long 32 or 64 bit signed, can hold a pointer
Note that some compilers cannot handle long lines or strings. The C89
standard specifies a limit of 509 characters.
vim:tw=78:ts=8:ft=help:norl:

371
runtime/doc/diff.txt Normal file
View File

@@ -0,0 +1,371 @@
*diff.txt* For Vim version 7.0aa. Last change: 2004 May 01
VIM REFERENCE MANUAL by Bram Moolenaar
*diff* *vimdiff* *gvimdiff* *diff-mode*
This file describes the +diff feature: Showing differences between two or
three versions of the same file.
The basics are explained in section |08.7| of the user manual.
1. Starting diff mode |vimdiff|
2. Viewing diffs |view-diffs|
3. Jumping to diffs |jumpto-diffs|
4. Copying diffs |copy-diffs|
5. Diff options |diff-options|
{not in Vi}
==============================================================================
1. Starting diff mode
The easiest way to start editing in diff mode is with the "vimdiff" command.
This starts Vim as usual, and additionally sets up for viewing the differences
between the arguments. >
vimdiff file1 file2 [file3 [file4]]
This is equivalent to: >
vim -d file1 file2 [file3 [file4]]
You may also use "gvimdiff" or "vim -d -g". The GUI is started then.
You may also use "viewdiff" or "gviewdiff". Vim starts in readonly mode then.
"r" may be prepended for restricted mode (see |-Z|).
The second and following arguments may also be a directory name. Vim will
then append the file name of the first argument to the directory name to find
the file.
This only works when a standard "diff" command is available. See 'diffexpr'.
What happens is that Vim opens a window for each of the files. This is like
using the |-O| argument. This uses vertical splits. If you prefer horizontal
splits add the |-o| argument: >
vimdiff -o file1 file2 [file3]
In each of the edited files these options are set:
'diff' on
'scrollbind' on
'scrollopt' includes "hor"
'wrap' off
'foldmethod' "diff"
'foldcolumn' 2
These options are set local to the window. When editing another file they are
reset to the global value.
The differences shown are actually the differences in the buffer. Thus if you
make changes after loading a file, these will be included in the displayed
diffs. You might have to do ":diffupdate" now and then, not all changes are
immediately taken into account.
In your .vimrc file you could do something special when Vim was started in
diff mode. You could use a construct like this: >
if &diff
setup for diff mode
else
setup for non-diff mode
endif
While already in Vim you can start diff mode in three ways.
*E98*
:diffsplit {filename} *:diffs* *:diffsplit*
Open a new window on the file {filename}. The options are set
as for "vimdiff" for the current and the newly opened window.
Also see 'diffexpr'.
*:difft* *:diffthis*
:diffthis Make the current window part of the diff windows. This sets
the option like for "vimdiff".
:diffpatch {patchfile} *:diffp* *:diffpatch*
Use the current buffer, patch it with the diff found in
{patchfile} and open a buffer on the result. The options are
set as for "vimdiff".
{patchfile} can be in any format that the "patch" program
understands or 'patchexpr' can handle.
Note that {patchfile} should only contain a diff for one file,
the current file. If {patchfile} contains diffs for other
files as well, the results are unpredictable. Vim changes
directory to /tmp to avoid files in the current directory
accidentally being patched. But it may still result in
various ".rej" files to be created. And when absolute path
names are present these files may get patched anyway.
To make these commands use a vertical split, prepend |:vertical|. Examples: >
:vert diffsplit main.c~
:vert diffpatch /tmp/diff
<
*E96*
There can be up to four buffers with 'diff' set.
Since the option values are remembered with the buffer, you can edit another
file for a moment and come back to the same file and be in diff mode again.
If you don't want diff mode, reset the 'diff' option. And you probably want
to get rid of the fold column: >
:set nodiff foldcolumn=0
==============================================================================
2. Viewing diffs *view-diffs*
The effect is that the diff windows show the same text, with the differences
highlighted. When scrolling the text, the 'scrollbind' option will make the
text in other windows to be scrolled as well. With vertical splits the text
should be aligned properly.
The alignment of text will go wrong when:
- 'wrap' is on, some lines will be wrapped and occupy two or more screen
lines
- folds are open in one window but not another
- 'scrollbind' is off
- changes have been made to the text
- "filler" is not present in 'diffopt', deleted/inserted lines makes the
alignment go wrong
All the buffers edited in a window where the 'diff' option is set will join in
the diff. This is also possible for hidden buffers. They must have been
edited in a window first for this to be possible.
Since 'diff' is a window-local option, it's possible to view the same buffer
in diff mode in one window and "normal" in another window. It is also
possible to view the changes you have made to a buffer, but since Vim doesn't
allow having two buffers for the same file, you need to make a copy of the
original file and diff with that. For example: >
:!cp % tempfile
:diffsplit tempfile
A buffer that is unloaded cannot be used for the diff. But it does work for
hidden buffers. You can use ":hide" to close a window without unloading the
buffer.
*:diffu* *:diffupdate*
Vim attempts to keep the differences updated when you make changes to the
text. This mostly takes care of inserted and deleted lines. Changes within a
line and more complicated changes do not cause the differences to be updated.
To force the differences to be updated use: >
:diffupdate
Vim will show filler lines for lines that are missing in one window but are
present in another. These lines were inserted in another file or deleted in
this file. Removing "filler" from the 'diffopt' option will make Vim not
display these filler lines.
Folds are used to hide the text that wasn't changed. See |folding| for all
the commands that can be used with folds.
The context of lines above a difference that are not included in the fold can
be set with the 'diffopt' option. For example, to set the context to three
lines: >
:set diffopt=filler,context:3
The diffs are highlighted with these groups:
|hl-DiffAdd| DiffAdd Added (inserted) lines. These lines exist in
this buffer but not in another.
|hl-DiffChange| DiffChange Changed lines.
|hl-DiffText| DiffText Changed text inside a Changed line. Vim
finds the first character that is different,
and the last character that is different
(searching from the end of the line). The
text in between is highlighted. This means
that parts in the middle that are still the
same are highlighted anyway.
|hl-DiffDelete| DiffDelete Deleted lines. Also called filler lines,
because they don't really exist in this
buffer.
==============================================================================
3. Jumping to diffs *jumpto-diffs*
Two commands can be used to jump to diffs:
*[c*
[c Jump backwards to the previous start of a change.
When a count is used, do it that many times.
*]c*
]c Jump forwards to the next start of a change.
When a count is used, do it that many times.
It is an error if there is no change for the cursor to move to.
==============================================================================
4. Diff copying *copy-diffs* *E99* *E100* *E101* *E102* *E103*
There are two commands to copy text from one buffer to another. The result is
that the buffers will be equal within the specified range.
*:diffg* *:diffget*
:[range]diffg[et] [bufspec]
Modify the current buffer to undo difference with another
buffer. If [bufspec] is given, that buffer is used.
Otherwise this only works if there is one other buffer in diff
mode.
See below for [range].
*:diffpu* *:diffput*
:[range]diffpu[t] [bufspec]
Modify another buffer to undo difference with the current
buffer. Just like ":diffget" but the other buffer is modified
instead of the current one.
See below for [range].
*do*
do Same as ":diffget" without argument or range. The "o" stands
for "obtain" ("dg" can't be used, it could be the start of
"dgg"!).
*dp*
dp Same as ":diffput" without argument or range.
When no [range] is given, the diff at the cursor position or just above it is
affected. When [range] is used, Vim tries to only put or get the specified
lines. When there are deleted lines, this may not always be possible.
There can be deleted lines below the last line of the buffer. When the cursor
is on the last line in the buffer and there is no diff above this line, the
":diffget" and "do" commands will obtain lines from the other buffer.
To be able to get those lines from another buffer in a [range] it's allowed to
use the last line number plus one. This command gets all diffs from the other
buffer: >
:1,$+1diffget
Note that deleted lines are displayed, but not counted as text lines. You
can't move the cursor into them. To fill the deleted lines with the lines
from another buffer use ":diffget" on the line below them.
The [bufspec] argument above can be a buffer number, a pattern for a buffer
name or a part of a buffer name. Examples:
:diffget Use the other buffer which is in diff mode
:diffget 3 Use buffer 3
:diffget v2 Use the buffer which matches "v2" and is in
diff mode (e.g., "file.c.v2")
==============================================================================
5. Diff options *diff-options*
Also see |'diffopt'| and the "diff" item of |'fillchars'|.
FINDING THE DIFFERENCES *diff-diffexpr*
The 'diffexpr' option can be set to use something else than the standard
"diff" program to compare two files and find the differences.
When 'diffexpr' is empty, Vim uses this command to find the differences
between file1 and file2: >
diff file1 file2 > outfile
The ">" is replaced with the value of 'shellredir'.
The output of "diff" must be a normal "ed" style diff. Do NOT use a context
diff. This example explains the format that Vim expects: >
1a2
> bbb
4d4
< 111
7c7
< GGG
---
> ggg
The "1a2" item appends the line "bbb".
The "4d4" item deletes the line "111".
The '7c7" item replaces the line "GGG" with "ggg".
When 'diffexpr' is not empty, Vim evaluates to obtain a diff file in the
format mentioned. These variables are set to the file names used:
v:fname_in original file
v:fname_new new version of the same file
v:fname_out resulting diff file
Additionally, 'diffexpr' should take care of "icase" and "iwhite" in the
'diffopt' option. 'diffexpr' cannot change the value of 'lines' and
'columns'.
Example (this does almost the same as 'diffexpr' being empty): >
set diffexpr=MyDiff()
function MyDiff()
let opt = ""
if &diffopt =~ "icase"
let opt = opt . "-i "
endif
if &diffopt =~ "iwhite"
let opt = opt . "-b "
endif
silent execute "!diff -a --binary " . opt . v:fname_in . " " . v:fname_new .
\ " > " . v:fname_out
endfunction
The "-a" argument is used to force comparing the files as text, comparing as
binaries isn't useful. The "--binary" argument makes the files read in binary
mode, so that a CTRL-Z doesn't end the text on DOS.
*E97*
Vim will do a test if the diff output looks alright. If it doesn't, you will
get an error message. Possible causes:
- The "diff" program cannot be executed.
- The "diff" program doesn't produce normal "ed" style diffs (see above).
- The 'shell' and associated options are not set correctly. Try if filtering
works with a command like ":!sort".
- You are using 'diffexpr' and it doesn't work.
If it's not clear what the problem is set the 'verbose' option to see more
messages.
USING PATCHES *diff-patchexpr*
The 'patchexpr' option can be set to use something else than the standard
"patch" program.
When 'patchexpr' is empty, Vim will call the "patch" program like this: >
patch -o outfile origfile < patchfile
This should work fine with most versions of the "patch" program. Note that a
CR in the middle of a line may cause problems, it is seen as a line break.
If the default doesn't work for you, set the 'patchexpr' to an expression that
will have the same effect. These variables are set to the file names used:
v:fname_in original file
v:fname_diff patch file
v:fname_out resulting patched file
Example (this does the same as 'patchexpr' being empty): >
let patchexpr=MyPatch
function MyPatch
:call system("patch -o " . v:fname_out . " " . v:fname_in .
\ " < " . v:fname_diff)
endfunction
Make sure that using the "patch" program doesn't have unwanted side effects.
For example, watch out for additionally generated files, which should be
deleted. It should just patch the file and nothing else.
Vim will change directory to "/tmp" or another temp directory before
evaluating 'patchexpr'. This hopefully avoids that files in the current
directory are accidentally patched. Vim will also delete files starting with
v:fname_in and ending in ".rej" and ".orig".
vim:tw=78:ts=8:ft=help:norl:

322
runtime/doc/digraph.txt Normal file
View File

@@ -0,0 +1,322 @@
*digraph.txt* For Vim version 7.0aa. Last change: 2001 Sep 03
VIM REFERENCE MANUAL by Bram Moolenaar
Digraphs *digraphs* *Digraphs*
Digraphs are used to enter characters that normally cannot be entered by
an ordinary keyboard. These are mostly accented characters which have the
eighth bit set. The digraphs are easier to remember than the decimal number
that can be entered with CTRL-V (see |i_CTRL-V|).
There is a brief introduction on digraphs in the user manual: |24.9|
An alternative is using the 'keymap' option.
1. Defining digraphs |digraphs-define|
2. Using digraphs |digraphs-use|
3. Default digraphs |digraphs-default|
{Vi does not have any of these commands}
==============================================================================
1. Defining digraphs *digraphs-define*
*:dig* *:digraphs*
:dig[raphs] show currently defined digraphs.
*E104* *E39*
:dig[raphs] {char1}{char2} {number} ...
Add digraph {char1}{char2} to the list. {number} is
the decimal representation of the character.
Example: >
:digr e: 235 a: 228
< Avoid defining a digraph with '_' (underscore) as the
first character, it has a special meaning in the
future.
Vim is normally compiled with the |+digraphs| feature. If the feature is
disabled, the ":digraph" command will display an error message.
Example of the output of ":digraphs": >
TH Þ 222 ss ß 223 a! à 224 a' á 225 a> â 226 a? ã 227 a: ä 228
The first two characters in each column are the characters you have to type to
enter the digraph.
In the middle of each column is the resulting character. This may be mangled
if you look at it on a system that does not support digraphs or if you print
this file.
The decimal number is the number of the character.
==============================================================================
2. Using digraphs *digraphs-use*
There are two methods to enter digraphs: *i_digraph*
CTRL-K {char1} {char2} or
{char1} <BS> {char2}
The first is always available; the second only when the 'digraph' option is
set.
If a digraph with {char1}{char2} does not exist, Vim searches for a digraph
{char2}{char1}. This helps when you don't remember which character comes
first.
Note that when you enter CTRL-K {char1}, where {char1} is a special key, Vim
enters the code for that special key. This is not a digraph.
Once you have entered the digraph, Vim treats the character like a normal
character that occupies only one character in the file and on the screen.
Example: >
'B' <BS> 'B' will enter the broken '|' character (166)
'a' <BS> '>' will enter an 'a' with a circumflex (226)
CTRL-K '-' '-' will enter a soft hyphen (173)
The current digraphs are listed with the ":digraphs" command. Some of the
default ones are listed below |digraph-table|.
For CTRL-K, there is one general digraph: CTRL-K <Space> {char} will enter
{char} with the highest bit set. You can use this to enter meta-characters.
The <Esc> character cannot be part of a digraph. When hitting <Esc>, Vim
stops digraph entry and ends Insert mode or Command-line mode, just like
hitting an <Esc> out of digraph context. Use CTRL-V 155 to enter meta-ESC
(CSI).
If you accidentally typed an 'a' that should be an 'e', you will type 'a' <BS>
'e'. But that is a digraph, so you will not get what you want. To correct
this, you will have to type <BS> e again. To avoid this don't set the
'digraph' option and use CTRL-K to enter digraphs.
You may have problems using Vim with characters which have an ASCII value
above 128. For example: You insert ue (u-umlaut) and the editor echoes \334
in Insert mode. After leaving the Insert mode everything is fine. Note that
fmt removes all characters with ASCII codes above 128 from the text being
formatted. On some Unix systems this means you have to define the
environment-variable LC_CTYPE. If you are using csh, then put the following
line in your .cshrc: >
setenv LC_CTYPE iso_8859_1
==============================================================================
3. Default digraphs *digraphs-default*
Vim comes with a set of default digraphs. Check the output of ":digraphs" to
see them.
On most systems Vim uses the same digraphs. They work for the Unicode and
ISO-8859-1 character sets. These default digraphs are taken from the RFC1345
mnemonics. To make it easy to remember the mnemonic, the second character has
a standard meaning:
char name char meaning ~
Exclamation mark ! Grave
Apostrophe ' Acute accent
Greater-Than sign > Circumflex accent
Question Mark ? tilde
Hyphen-Minus - Macron
Left parenthesis ( Breve
Full Stop . Dot Above
Colon : Diaeresis
Comma , Cedilla
Underline _ Underline
Solidus / Stroke
Quotation mark " Double acute accent
Semicolon ; Ogonek
Less-Than sign < Caron
Zero 0 Ring above
Two 2 Hook
Nine 9 Horn
Equals = Cyrillic
Asterisk * Greek
Percent sign % Greek/Cyrillic special
Plus + smalls: Arabic, capitals: Hebrew
Three 3 some Latin/Greek/Cyrillic letters
Four 4 Bopomofo
Five 5 Hiragana
Six 6 Katakana
Example: a: is ä and o: is ö
These are the RFC1345 digraphs for the one-byte characters. See the output of
":digraphs" for the others. The characters above 255 are only available when
Vim was compiled with the |+multi_byte| feature.
*digraph-table*
char digraph hex dec official name ~
^@ NU 0x00 0 NULL (NUL)
^A SH 0x01 1 START OF HEADING (SOH)
^B SX 0x02 2 START OF TEXT (STX)
^C EX 0x03 3 END OF TEXT (ETX)
^D ET 0x04 4 END OF TRANSMISSION (EOT)
^E EQ 0x05 5 ENQUIRY (ENQ)
^F AK 0x06 6 ACKNOWLEDGE (ACK)
^G BL 0x07 7 BELL (BEL)
^H BS 0x08 8 BACKSPACE (BS)
^I HT 0x09 9 CHARACTER TABULATION (HT)
^@ LF 0x0a 10 LINE FEED (LF)
^K VT 0x0b 11 LINE TABULATION (VT)
^L FF 0x0c 12 FORM FEED (FF)
^M CR 0x0d 13 CARRIAGE RETURN (CR)
^N SO 0x0e 14 SHIFT OUT (SO)
^O SI 0x0f 15 SHIFT IN (SI)
^P DL 0x10 16 DATALINK ESCAPE (DLE)
^Q D1 0x11 17 DEVICE CONTROL ONE (DC1)
^R D2 0x12 18 DEVICE CONTROL TWO (DC2)
^S D3 0x13 19 DEVICE CONTROL THREE (DC3)
^T D4 0x14 20 DEVICE CONTROL FOUR (DC4)
^U NK 0x15 21 NEGATIVE ACKNOWLEDGE (NAK)
^V SY 0x16 22 SYNCRONOUS IDLE (SYN)
^W EB 0x17 23 END OF TRANSMISSION BLOCK (ETB)
^X CN 0x18 24 CANCEL (CAN)
^Y EM 0x19 25 END OF MEDIUM (EM)
^Z SB 0x1a 26 SUBSTITUTE (SUB)
^[ EC 0x1b 27 ESCAPE (ESC)
^\ FS 0x1c 28 FILE SEPARATOR (IS4)
^] GS 0x1d 29 GROUP SEPARATOR (IS3)
^^ RS 0x1e 30 RECORD SEPARATOR (IS2)
^_ US 0x1f 31 UNIT SEPARATOR (IS1)
SP 0x20 32 SPACE
# Nb 0x23 35 NUMBER SIGN
$ DO 0x24 36 DOLLAR SIGN
@ At 0x40 64 COMMERCIAL AT
[ <( 0x5b 91 LEFT SQUARE BRACKET
\ // 0x5c 92 REVERSE SOLIDUS
] )> 0x5d 93 RIGHT SQUARE BRACKET
^ '> 0x5e 94 CIRCUMFLEX ACCENT
` '! 0x60 96 GRAVE ACCENT
{ (! 0x7b 123 LEFT CURLY BRACKET
| !! 0x7c 124 VERTICAL LINE
} !) 0x7d 125 RIGHT CURLY BRACKET
~ '? 0x7e 126 TILDE
^? DT 0x7f 127 DELETE (DEL)
~@ PA 0x80 128 PADDING CHARACTER (PAD)
~A HO 0x81 129 HIGH OCTET PRESET (HOP)
~B BH 0x82 130 BREAK PERMITTED HERE (BPH)
~C NH 0x83 131 NO BREAK HERE (NBH)
~D IN 0x84 132 INDEX (IND)
~E NL 0x85 133 NEXT LINE (NEL)
~F SA 0x86 134 START OF SELECTED AREA (SSA)
~G ES 0x87 135 END OF SELECTED AREA (ESA)
~H HS 0x88 136 CHARACTER TABULATION SET (HTS)
~I HJ 0x89 137 CHARACTER TABULATION WITH JUSTIFICATION (HTJ)
~J VS 0x8a 138 LINE TABULATION SET (VTS)
~K PD 0x8b 139 PARTIAL LINE FORWARD (PLD)
~L PU 0x8c 140 PARTIAL LINE BACKWARD (PLU)
~M RI 0x8d 141 REVERSE LINE FEED (RI)
~N S2 0x8e 142 SINGLE-SHIFT TWO (SS2)
~O S3 0x8f 143 SINGLE-SHIFT THREE (SS3)
~P DC 0x90 144 DEVICE CONTROL STRING (DCS)
~Q P1 0x91 145 PRIVATE USE ONE (PU1)
~R P2 0x92 146 PRIVATE USE TWO (PU2)
~S TS 0x93 147 SET TRANSMIT STATE (STS)
~T CC 0x94 148 CANCEL CHARACTER (CCH)
~U MW 0x95 149 MESSAGE WAITING (MW)
~V SG 0x96 150 START OF GUARDED AREA (SPA)
~W EG 0x97 151 END OF GUARDED AREA (EPA)
~X SS 0x98 152 START OF STRING (SOS)
~Y GC 0x99 153 SINGLE GRAPHIC CHARACTER INTRODUCER (SGCI)
~Z SC 0x9a 154 SINGLE CHARACTER INTRODUCER (SCI)
~[ CI 0x9b 155 CONTROL SEQUENCE INTRODUCER (CSI)
~\ ST 0x9c 156 STRING TERMINATOR (ST)
~] OC 0x9d 157 OPERATING SYSTEM COMMAND (OSC)
~^ PM 0x9e 158 PRIVACY MESSAGE (PM)
~_ AC 0x9f 159 APPLICATION PROGRAM COMMAND (APC)
| NS 0xa0 160 NO-BREAK SPACE
¡ !I 0xa1 161 INVERTED EXCLAMATION MARK
¢ Ct 0xa2 162 CENT SIGN
£ Pd 0xa3 163 POUND SIGN
¤ Cu 0xa4 164 CURRENCY SIGN
¥ Ye 0xa5 165 YEN SIGN
¦ BB 0xa6 166 BROKEN BAR
§ SE 0xa7 167 SECTION SIGN
¨ ': 0xa8 168 DIAERESIS
© Co 0xa9 169 COPYRIGHT SIGN
ª -a 0xaa 170 FEMININE ORDINAL INDICATOR
« << 0xab 171 LEFT-POINTING DOUBLE ANGLE QUOTATION MARK
¬ NO 0xac 172 NOT SIGN
­ -- 0xad 173 SOFT HYPHEN
® Rg 0xae 174 REGISTERED SIGN
¯ 'm 0xaf 175 MACRON
° DG 0xb0 176 DEGREE SIGN
± +- 0xb1 177 PLUS-MINUS SIGN
² 2S 0xb2 178 SUPERSCRIPT TWO
³ 3S 0xb3 179 SUPERSCRIPT THREE
´ '' 0xb4 180 ACUTE ACCENT
µ My 0xb5 181 MICRO SIGN
¶ PI 0xb6 182 PILCROW SIGN
· .M 0xb7 183 MIDDLE DOT
¸ ', 0xb8 184 CEDILLA
¹ 1S 0xb9 185 SUPERSCRIPT ONE
º -o 0xba 186 MASCULINE ORDINAL INDICATOR
» >> 0xbb 187 RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK
¼ 14 0xbc 188 VULGAR FRACTION ONE QUARTER
½ 12 0xbd 189 VULGAR FRACTION ONE HALF
¾ 34 0xbe 190 VULGAR FRACTION THREE QUARTERS
¿ ?I 0xbf 191 INVERTED QUESTION MARK
À A! 0xc0 192 LATIN CAPITAL LETTER A WITH GRAVE
Á A' 0xc1 193 LATIN CAPITAL LETTER A WITH ACUTE
 A> 0xc2 194 LATIN CAPITAL LETTER A WITH CIRCUMFLEX
à A? 0xc3 195 LATIN CAPITAL LETTER A WITH TILDE
Ä A: 0xc4 196 LATIN CAPITAL LETTER A WITH DIAERESIS
Å AA 0xc5 197 LATIN CAPITAL LETTER A WITH RING ABOVE
Æ AE 0xc6 198 LATIN CAPITAL LETTER AE
Ç C, 0xc7 199 LATIN CAPITAL LETTER C WITH CEDILLA
È E! 0xc8 200 LATIN CAPITAL LETTER E WITH GRAVE
É E' 0xc9 201 LATIN CAPITAL LETTER E WITH ACUTE
Ê E> 0xca 202 LATIN CAPITAL LETTER E WITH CIRCUMFLEX
Ë E: 0xcb 203 LATIN CAPITAL LETTER E WITH DIAERESIS
Ì I! 0xcc 204 LATIN CAPITAL LETTER I WITH GRAVE
Í I' 0xcd 205 LATIN CAPITAL LETTER I WITH ACUTE
Î I> 0xce 206 LATIN CAPITAL LETTER I WITH CIRCUMFLEX
Ï I: 0xcf 207 LATIN CAPITAL LETTER I WITH DIAERESIS
Ð D- 0xd0 208 LATIN CAPITAL LETTER ETH (Icelandic)
Ñ N? 0xd1 209 LATIN CAPITAL LETTER N WITH TILDE
Ò O! 0xd2 210 LATIN CAPITAL LETTER O WITH GRAVE
Ó O' 0xd3 211 LATIN CAPITAL LETTER O WITH ACUTE
Ô O> 0xd4 212 LATIN CAPITAL LETTER O WITH CIRCUMFLEX
Õ O? 0xd5 213 LATIN CAPITAL LETTER O WITH TILDE
Ö O: 0xd6 214 LATIN CAPITAL LETTER O WITH DIAERESIS
× *X 0xd7 215 MULTIPLICATION SIGN
Ø O/ 0xd8 216 LATIN CAPITAL LETTER O WITH STROKE
Ù U! 0xd9 217 LATIN CAPITAL LETTER U WITH GRAVE
Ú U' 0xda 218 LATIN CAPITAL LETTER U WITH ACUTE
Û U> 0xdb 219 LATIN CAPITAL LETTER U WITH CIRCUMFLEX
Ü U: 0xdc 220 LATIN CAPITAL LETTER U WITH DIAERESIS
Ý Y' 0xdd 221 LATIN CAPITAL LETTER Y WITH ACUTE
Þ TH 0xde 222 LATIN CAPITAL LETTER THORN (Icelandic)
ß ss 0xdf 223 LATIN SMALL LETTER SHARP S (German)
à a! 0xe0 224 LATIN SMALL LETTER A WITH GRAVE
á a' 0xe1 225 LATIN SMALL LETTER A WITH ACUTE
â a> 0xe2 226 LATIN SMALL LETTER A WITH CIRCUMFLEX
ã a? 0xe3 227 LATIN SMALL LETTER A WITH TILDE
ä a: 0xe4 228 LATIN SMALL LETTER A WITH DIAERESIS
å aa 0xe5 229 LATIN SMALL LETTER A WITH RING ABOVE
æ ae 0xe6 230 LATIN SMALL LETTER AE
ç c, 0xe7 231 LATIN SMALL LETTER C WITH CEDILLA
è e! 0xe8 232 LATIN SMALL LETTER E WITH GRAVE
é e' 0xe9 233 LATIN SMALL LETTER E WITH ACUTE
ê e> 0xea 234 LATIN SMALL LETTER E WITH CIRCUMFLEX
ë e: 0xeb 235 LATIN SMALL LETTER E WITH DIAERESIS
ì i! 0xec 236 LATIN SMALL LETTER I WITH GRAVE
í i' 0xed 237 LATIN SMALL LETTER I WITH ACUTE
î i> 0xee 238 LATIN SMALL LETTER I WITH CIRCUMFLEX
ï i: 0xef 239 LATIN SMALL LETTER I WITH DIAERESIS
ð d- 0xf0 240 LATIN SMALL LETTER ETH (Icelandic)
ñ n? 0xf1 241 LATIN SMALL LETTER N WITH TILDE
ò o! 0xf2 242 LATIN SMALL LETTER O WITH GRAVE
ó o' 0xf3 243 LATIN SMALL LETTER O WITH ACUTE
ô o> 0xf4 244 LATIN SMALL LETTER O WITH CIRCUMFLEX
õ o? 0xf5 245 LATIN SMALL LETTER O WITH TILDE
ö o: 0xf6 246 LATIN SMALL LETTER O WITH DIAERESIS
÷ -: 0xf7 247 DIVISION SIGN
ø o/ 0xf8 248 LATIN SMALL LETTER O WITH STROKE
ù u! 0xf9 249 LATIN SMALL LETTER U WITH GRAVE
ú u' 0xfa 250 LATIN SMALL LETTER U WITH ACUTE
û u> 0xfb 251 LATIN SMALL LETTER U WITH CIRCUMFLEX
ü u: 0xfc 252 LATIN SMALL LETTER U WITH DIAERESIS
ý y' 0xfd 253 LATIN SMALL LETTER Y WITH ACUTE
þ th 0xfe 254 LATIN SMALL LETTER THORN (Icelandic)
ÿ y: 0xff 255 LATIN SMALL LETTER Y WITH DIAERESIS
vim:tw=78:ts=8:ft=help:norl:

83
runtime/doc/doctags.c Normal file
View File

@@ -0,0 +1,83 @@
/* vim:set ts=4 sw=4:
* this program makes a tags file for vim_ref.txt
*
* Usage: doctags vim_ref.txt vim_win.txt ... >tags
*
* A tag in this context is an identifier between stars, e.g. *c_files*
*/
#include <stdio.h>
#include <string.h>
#include <ctype.h>
#include <stdlib.h>
#define LINELEN 200
int
main(argc, argv)
int argc;
char **argv;
{
char line[LINELEN];
char *p1, *p2;
char *p;
FILE *fd;
if (argc <= 1)
{
fprintf(stderr, "Usage: doctags docfile ... >tags\n");
exit(1);
}
printf("help-tags\ttags\t1\n");
while (--argc > 0)
{
++argv;
fd = fopen(argv[0], "r");
if (fd == NULL)
{
fprintf(stderr, "Unable to open %s for reading\n", argv[0]);
continue;
}
while (fgets(line, LINELEN, fd) != NULL)
{
p1 = strchr(line, '*'); /* find first '*' */
while (p1 != NULL)
{
p2 = strchr(p1 + 1, '*'); /* find second '*' */
if (p2 != NULL && p2 > p1 + 1) /* skip "*" and "**" */
{
for (p = p1 + 1; p < p2; ++p)
if (*p == ' ' || *p == '\t' || *p == '|')
break;
/*
* Only accept a *tag* when it consists of valid
* characters, there is white space before it and is
* followed by a white character or end-of-line.
*/
if (p == p2
&& (p1 == line || p1[-1] == ' ' || p1[-1] == '\t')
&& (strchr(" \t\n\r", p[1]) != NULL
|| p[1] == '\0'))
{
*p2 = '\0';
++p1;
printf("%s\t%s\t/*", p1, argv[0]);
while (*p1)
{
/* insert backslash before '\\' and '/' */
if (*p1 == '\\' || *p1 == '/')
putchar('\\');
putchar(*p1);
++p1;
}
printf("*\n");
p2 = strchr(p2 + 1, '*'); /* find next '*' */
}
}
p1 = p2;
}
}
fclose(fd);
}
return 0;
}

1432
runtime/doc/editing.txt Normal file
View File

File diff suppressed because it is too large Load Diff

4583
runtime/doc/eval.txt Normal file
View File

File diff suppressed because it is too large Load Diff

49
runtime/doc/evim.1 Normal file
View File

@@ -0,0 +1,49 @@
.TH EVIM 1 "2002 February 16"
.SH NAME
evim \- easy Vim, edit a file with Vim and setup for modeless editing
.SH SYNOPSIS
.br
.B evim
[options] [file ..]
.br
.B eview
.SH DESCRIPTION
.B eVim
starts
.B Vim
and sets options to make it behave like a modeless editor.
This is still Vim but used as a point-and-click editor.
This feels a lot like using Notepad on MS-Windows.
.B eVim
will always run in the GUI, to enable the use of menus and toolbar.
.PP
Only to be used for people who really can't work with Vim in the normal way.
Editing will be much less efficient.
.PP
.B eview
is the same, but starts in read-only mode. It works just like evim -R.
.PP
See vim(1) for details about Vim, options, etc.
.PP
The 'insertmode' option is set to be able to type text directly.
.br
Mappings are setup to make Copy and Paste work with the MS-Windows keys.
CTRL-X cuts text, CTRL-C copies text and CTRL-V pastes text.
Use CTRL-Q to obtain the original meaning of CTRL-V.
.SH OPTIONS
See vim(1).
.SH FILES
.TP 15
/usr/local/lib/vim/evim.vim
The script loaded to initialize eVim.
.SH AKA
Also Known As "Vim for gumbies".
When using evim you are expected to take a handkerchief,
make a knot in each corner and wear it on your head.
.SH SEE ALSO
vim(1)
.SH AUTHOR
Most of
.B Vim
was made by Bram Moolenaar, with a lot of help from others.
See the Help/Credits menu.

269
runtime/doc/farsi.txt Normal file
View File

@@ -0,0 +1,269 @@
*farsi.txt* For Vim version 7.0aa. Last change: 2002 Oct 29
VIM REFERENCE MANUAL by Mortaza Ghassab Shiran
Right to Left and Farsi Mapping for Vim *farsi* *Farsi*
{Vi does not have any of these commands}
*E27*
In order to use right-to-left and Farsi mapping support, it is necessary to
compile Vim with the |+farsi| feature.
These functions have been made by Mortaza G. Shiran <shiran@jps.net>
Introduction
------------
In right-to-left oriented files the characters appear on the screen from right
to left. This kind of file is most useful when writing Farsi documents,
composing faxes or writing Farsi memos.
The commands, prompts and help files are not in Farsi, therefore the user
interface remains the standard Vi interface.
Highlights
----------
o Editing left-to-right files as in the original Vim, no change.
o Viewing and editing files in right-to-left windows. File orientation is
per window, so it is possible to view the same file in right-to-left and
left-to-right modes, simultaneously.
o Compatibility to the original Vim. Almost all features work in
right-to-left mode (see bugs below).
o Changing keyboard mapping and reverse insert modes using a single
command.
o Backing from reverse insert mode to the correct place in the file
(if possible).
o While in Farsi mode, numbers are entered from left to right. Upon entering
a none number character, that character will be inserted just into the
left of the last number.
o No special terminal with right-to-left capabilities is required. The
right-to-left changes are completely hardware independent. Only
Farsi font is necessary.
o Farsi keymapping on the command line in reverse insert mode.
o Toggling between left-to-right and right-to-left via F8 function key.
o Toggling between Farsi ISIR-3342 standard encoding and VIM Farsi via F9
function key. Since this makes sense only for the text written in
right-to-left mode, this function is also supported only in right-to-left
mode.
Farsi Fonts *farsi fonts*
-----------
If the "extra" archive has been unpacked, the following files are found in the
subdirectories of the '$VIM/farsi' directory:
+ far-a01.pcf X Windows fonts for Unix including Linux systems
+ far-a01.bf X Windows fonts for SunOs
+ far-a01.f16 a screen fonts for Unix including Linux systems
+ far-a01.fon a monospaced fonts for Windows NT/95/98
+ far-a01.com a screen fonts for DOS
Font Installation
-----------------
o Installation of fonts for MS Window systems (NT/95/98)
From 'Control Panel' folder, start the 'Fonts' program. Then from 'file'
menu item select 'Install New Fonts ...'. Browse and select the
'far-a01.fon', then follow the installation guide.
NOTE: several people have reported that this does not work. The solution
is unknown.
o Installation of fonts for X Window systems (Unix/Linux)
Depending on your system, copy far-a01.pcf.Z or far-a01.pcf.gz into a
directory of your choice. Change to the directory containing the Farsi
fonts and execute the following commands:
> mkfontdir
> xset +fp path_name_of_farsi_fonts_directory
o Installation of fonts for X Window systems (SunOs)
Copy far-a01.bf font into a directory of your choice.
Change to the directory containing the far-a01.fb fonts and
execute the following commands:
> fldfamily
> xset +fp path_name_of_fonts_directory
o Installation of ASCII screen fonts (Unix/Linux)
For Linux system, copy the far-a01.f16 fonts into /usr/lib/kbd/consolefonts
directory and execute the setfont program as "setfont far-a01.f16". For
other systems (e.g. SCO Unix), please refer to the fonts installation
section of your system administration manuals.
o Installation of ASCII screen fonts (DOS)
After system power on, prior to the first use of VIM, upload the Farsi
fonts by executing the far-a01.com font uploading program.
Usage
-----
Prior to starting VIM, the environment in which VIM can run in Farsi mode,
must be set. In addition to installation of Farsi fonts, following points
refer to some of the system environments, which you may need to set:
Key code mapping, loading graphic card in ASCII screen mode, setting the IO
driver in 8 bit clean mode ... .
o Setting the Farsi fonts
+ For VIM GUI set the 'guifont' to far-a01. This is done by entering
':set guifont=far-a01' in the VIM window.
You can have 'guifont' set to far-a01 by VIM during the VIM startup
by appending the ':set guifont=far-a01' into your .vimrc file
(in case of NT/95/98 platforms _vimrc).
Under the X Window environment, you can also start the VIM with
'-fn far-a01' option.
+ For the VIM within a xterm, start a xterm with the Farsi fonts (e.g.
kterm -fn far-a01). Then start the VIM inside the kterm.
+ For VIM under DOS, prior to the first usage of VIM, upload the Farsi
fonts by executing the far-a01.com fonts uploading program.
o Farsi Keymapping Activation
To activate the Farsi keymapping, set either 'altkeymap' or 'fkmap'.
This is done by entering ':set akm' or ':set fk' in the VIM window.
You can have 'altkeymap' or 'fkmap' set as default by appending ':set akm'
or ':set fk' in your .vimrc file or _vimrc in case of NT/95/98 platforms.
To turn off the Farsi keymapping as a default second language keymapping,
reset the 'altkeymap' by entering ':set noakm'.
o right-to-left Farsi Mode
By default VIM starts in Left-to-right mode. Following are ways to change
the window orientation:
+ Start the VIM with -F option (e.g. vim -F ... ).
+ Use F8 function key to toggle between left-to-right and right-to-left.
+ While in Left-to-right mode, enter 'set rl' in the command line ('rl' is
the abbreviation for rightleft).
+ Put the 'set rl' line in your '.vimrc' file to start the VIM in
right-to-left mode permanently.
Encoding
--------
The letter encoding used is the VIM extended ISIR-3342 standard with a built
in function to convert between VIM extended ISIR-3342 and ISIR-3342 standard.
For document portability reasons, the letter encoding is kept the same across
different platforms (i.e. UNIX's, NT/95/98, MS DOS, ...).
o Keyboard
+ CTRL-_ in insert/replace modes toggles between Farsi(akm)/Latin
mode as follows:
+ CTRL-_ moves the cursor to the end of the typed text in edit mode.
+ CTRL-_ in command mode only toggles keyboard mapping between Farsi(akm)/
Latin. The Farsi text is then entered in reverse insert mode.
+ F8 - Toggles between left-to-right and right-to-left.
+ F9 - Toggles the encoding between ISIR-3342 standard and VIM extended
ISIR-3342 (supported only in right-to-left mode).
+ Keyboard mapping is based on the Iranian ISIRI-2901 standard.
Following table shows the keyboard mapping while Farsi(akm) mode set:
-------------------------------------
` 1 2 3 4 5 6 7 8 9 0 - =
¢ ± ² ³ ´ µ ¶ · ¸ ¹ ° ­ ½
-------------------------------------
~ ! @ # $ % ^ & * ( ) _ +
~ £ § ® ¤ ¥ ª ¬ è ¨ © é «
-------------------------------------
q w e r t z u i o p [ ]
Ó Ò Æ Ù Ø Õ Ö à Ê É Ç ˆ
-------------------------------------
Q W E R T Z U I O P { }
÷ õ ô ó ò ý ð ö [ ] { }
-------------------------------------
a s d f g h j k l ; ' \
Ñ Ð á Ã Ü Á Å Þ Ý Ú Û ë
-------------------------------------
A S D F G H J K L : " |
ù û  þ ú ø À ü æ ç º » ê
-------------------------------------
< y x c v b n m , . /
¾ × Ô Î Í Ì Ë Ä ß ¦ ¯
-------------------------------------
> Y X C V B N M < > ?
¼ ñ Ô Ï Í ¡ Ë Â ¾ ¼ ¿
-------------------------------------
Note:
¡ stands for Farsi PSP (break without space)
¢ stands for Farsi PCN (for HAMZE attribute )
Restrictions
------------
o In insert/replace mode and fkmap (Farsi mode) set, CTRL-B is not
supported.
o If you change the character mapping between Latin/Farsi, the redo buffer
will be reset (emptied). That is, redo is valid and will function (using
'.') only within the mode you are in.
o While numbers are entered in Farsi mode, the redo buffer will be reset
(emptied). That is, you can not redo the last changes (using '.') after
entering numbers.
o While in left-to-right and Farsi mode set, CTRL-R is not supported.
o While in right-to-left mode, the search on 'Latin' pattern does not work,
except if you enter the Latin search pattern in reverse.
o In the command mode, there is no support for entering the numbers from left
to right and also for the sake of the flexibility the keymapping logic is
restricted.
o Under X Window environment, if you want to run the VIM within a xterm
terminal emulator and Farsi mode set, you need to have an ANSI compatible
xterm terminal emulator. This is because the letter codes above 128 decimal
have certain meanings in the standard xterm terminal emulator.
Note: Under X Window environment, VIM GUI works fine in Farsi mode.
This eliminates the need of any xterm terminal emulator.
Bugs
----
While in insert/replace and Farsi mode set, if you repeatedly change the
cursor position (via cursor movement) and enter new text and then try to undo
the last change, the undo will lag one change behind. But as you continue to
undo, you will reach the original line of text. You can also use U to undo all
changes made in the current line.
For more information about the bugs refer to rileft.txt.
vim:tw=78:ts=8:ft=help:norl:

529
runtime/doc/filetype.txt Normal file
View File

@@ -0,0 +1,529 @@
*filetype.txt* For Vim version 7.0aa. Last change: 2004 May 05
VIM REFERENCE MANUAL by Bram Moolenaar
Filetypes *filetype* *file-type*
1. Filetypes |filetypes|
2. Filetype plugin |filetype-plugins|
3. Docs for the default filetype plugins. |ftplugin-docs|
Also see |autocmd.txt|.
{Vi does not have any of these commands}
==============================================================================
1. Filetypes *filetypes* *file-types*
Vim can detect the type of file that is edited. This is done by checking the
file name and sometimes by inspecting the contents of the file for specific
text.
*:filetype* *:filet*
To enable file type detection, use this command in your vimrc: >
:filetype on
Each time a new or existing file is edited, Vim will try to recognize the type
of the file and set the 'filetype' option. This will trigger the FileType
event, which can be used to set the syntax highlighting, set options, etc.
NOTE: Filetypes and 'compatible' don't work together well, since being Vi
compatible means options are global. Resetting 'compatible' is recommended,
if you didn't do that already.
Detail: The ":filetype on" command will load one of these files:
Amiga $VIMRUNTIME/filetype.vim
Mac $VIMRUNTIME:filetype.vim
MS-DOS $VIMRUNTIME\filetype.vim
RiscOS Vim:Filetype
Unix $VIMRUNTIME/filetype.vim
VMS $VIMRUNTIME/filetype.vim
This file is a Vim script that defines autocommands for the
BufNewFile and BufRead events. If the file type is not found by the
name, the file $VIMRUNTIME/scripts.vim is used to detect it from the
contents of the file.
To add your own file types, see |new-filetype| below.
If the file type is not detected automatically, or it finds the wrong type,
you can either set the 'filetype' option manually, or add a modeline to your
file. Example, for in an IDL file use the command: >
:set filetype=idl
or add this |modeline| to the file: >
/* vim: set filetype=idl : */
<
*:filetype-plugin-on*
You can enable loading the plugin files for specific file types with: >
:filetype plugin on
If filetype detection was not switched on yet, it will be as well.
This actually loads the file "ftplugin.vim" in 'runtimepath'.
The result is that when a file is edited its plugin file is loaded (if there
is one for the detected filetype). |filetype-plugin|
*:filetype-plugin-off*
You can disable it again with: >
:filetype plugin off
The filetype detection is not switched off then. But if you do switch off
filetype detection, the plugins will not be loaded either.
This actually loads the file "ftplugof.vim" in 'runtimepath'.
*:filetype-indent-on*
You can enable loading the indent file for specific file types with: >
:filetype indent on
If filetype detection was not switched on yet, it will be as well.
This actually loads the file "indent.vim" in 'runtimepath'.
The result is that when a file is edited its indent file is loaded (if there
is one for the detected filetype). |indent-expression|
*:filetype-indent-off*
You can disable it again with: >
:filetype indent off
The filetype detection is not switched off then. But if you do switch off
filetype detection, the indent files will not be loaded either.
This actually loads the file "indoff.vim" in 'runtimepath'.
*:filetype-off*
To disable file type detection, use this command: >
:filetype off
This will keep the flags for "plugin" and "indent", but since no file types
are being detected, they won't work until the next ":filetype on".
Overview: *:filetype-overview*
command detection plugin indent ~
:filetype on on unchanged unchanged
:filetype off off unchanged unchanged
:filetype plugin on on on unchanged
:filetype plugin off unchanged off unchanged
:filetype indent on on unchanged on
:filetype indent off unchanged unchanged off
:filetype plugin indent on on on on
:filetype plugin indent off unchanged off off
To see the current status, type: >
:filetype
The output looks something like this: >
filetype detection:ON plugin:ON indent:OFF
The file types are also used for syntax highlighting. If the ":syntax on"
command is used, the file type detection is installed too. There is no need
to do ":filetype on" after ":syntax on".
To disable one of the file types, add a line in the your filetype file, see
|remove-filetype|.
*filetype-detect*
To detect the file type again: >
:filetype detect
Use this if you started with an empty file and typed text that makes it
possible to detect the file type. For example, when you entered this in a
shell script: "#!/bin/csh".
When filetype detection was off, it will be enabled first, like the "on"
argument was used.
*filetype-overrule*
When the same extension is used for two filetypes, Vim tries to guess what
kind of file it is. This doesn't always work. A number of global variables
can be used to overrule the filetype used for certain extensions:
file name variable ~
*.asa g:filetype_asa |aspvbs-syntax| |aspperl-syntax|
*.asp g:filetype_asp |aspvbs-syntax| |aspperl-syntax|
*.asm g:asmsyntax |asm-syntax|
*.prg g:filetype_prg
*.pl g:filetype_pl
*.inc g:filetype_inc
*.w g:filetype_w |cweb-syntax|
*.i g:filetype_i |progress-syntax|
*.p g:filetype_p |pascal-syntax|
*.sh g:bash_is_sh |sh-syntax|
*filetype-ignore*
To avoid that certain files are being inspected, the g:ft_ignore_pat variable
is used. The default value is set like this: >
:let g:ft_ignore_pat = '\.\(Z\|gz\|bz2\|zip\|tgz\)$'
This means that the contents of compressed files are not inspected.
*new-filetype*
If a file type that you want to use is not detected yet, there are three ways
to add it. In any way, it's better not modify the $VIMRUNTIME/filetype.vim
file. It will be overwritten when installing a new version of Vim.
A. If you want to overrule all default file type checks.
This works by writing one file for each filetype. The disadvantage is that
means there can be many files. The advantage is that you can simply drop
this file in the right directory to make it work.
1. Create your user runtime directory. You would normally use the first
item of the 'runtimepath' option. Then create the directory "ftdetect"
inside it. Example for Unix: >
:!mkdir ~/.vim
:!mkdir ~/.vim/ftdetect
<
2. Create a file that contains an autocommand to detect the file type.
Example: >
au BufRead,BufNewFile *.mine set filetype=mine
< Note that there is no "augroup" command, this has already been done
when sourcing your file. You could also use the pattern "*" and then
check the contents of the file to recognize it.
Write this file as "mine.vim" in the "ftdetect" directory in your user
runtime directory. For example, for Unix: >
:w ~/.vim/ftdetect/mine.vim
< 3. To use the new filetype detection you must restart Vim.
The files in the "ftdetect" directory are used after all the default
checks, thus they can overrule a previously detected file type.
B. If you want to detect your file after the default file type checks.
This works like A above, but instead of setting 'filetype' unconditionally
use ":setfiletype". This will only set 'filetype' if no file type was
detected yet. Example: >
au BufRead,BufNewFile *.txt setfiletype text
<
You can also use the already detected file type in your command. For
example, to use the file type "mypascal" when "pascal" has been detected: >
au BufRead,BufNewFile * if &ft == 'pascal' | set ft=mypascal
| endif
C. If your file type can be detected by the file name.
1. Create your user runtime directory. You would normally use the first
item of the 'runtimepath' option. Example for Unix: >
:!mkdir ~/.vim
<
2. Create a file that contains autocommands to detect the file type.
Example: >
" my filetype file
if exists("did_load_filetypes")
finish
endif
augroup filetypedetect
au! BufRead,BufNewFile *.mine setfiletype mine
au! BufRead,BufNewFile *.xyz setfiletype drawing
augroup END
< Write this file as "filetype.vim" in your user runtime directory. For
example, for Unix: >
:w ~/.vim/filetype.vim
< 3. To use the new filetype detection you must restart Vim.
Your filetype.vim will be sourced before the default FileType autocommands
have been installed. Your autocommands will match first, and the
":setfiletype" command will make sure that no other autocommands will set
'filetype' after this.
*new-filetype-scripts*
D. If your filetype can only be detected by inspecting the contents of the
file.
1. Create your user runtime directory. You would normally use the first
item of the 'runtimepath' option. Example for Unix: >
:!mkdir ~/.vim
<
2. Create a vim script file for doing this. Example: >
if did_filetype() " filetype already set..
finish " ..don't do these checks
endif
if getline(1) =~ '^#!.*\<mine\>'
setfiletype mine
elseif getline(1) =~? '\<drawing\>'
setfiletype drawing
endif
< See $VIMRUNTIME/scripts.vim for more examples.
Write this file as "scripts.vim" in your user runtime directory. For
example, for Unix: >
:w ~/.vim/scripts.vim
<
3. The detection will work right away, no need to restart Vim.
Your scripts.vim is loaded before the default checks for file types, which
means that your rules override the default rules in
$VIMRUNTIME/scripts.vim.
*remove-filetype*
If a file type is detected that is wrong for you, install a filetype.vim or
scripts.vim to catch it (see above). You can set 'filetype' to a non-existing
name to avoid that it will be set later anyway: >
:set filetype=ignored
If you are setting up a system with many users, and you don't want each user
to add/remove the same filetypes, consider writing the filetype.vim and
scripts.vim files in a runtime directory that is used for everybody. Check
the 'runtimepath' for a directory to use. If there isn't one, set
'runtimepath' in the |system-vimrc|. Be careful to keep the default
directories!
*autocmd-osfiletypes*
On operating systems which support storing a file type with the file, you can
specify that an autocommand should only be executed if the file is of a
certain type.
The actual type checking depends on which platform you are running Vim
on; see your system's documentation for details.
To use osfiletype checking in an autocommand you should put a list of types to
match in angle brackets in place of a pattern, like this: >
:au BufRead *.html,<&faf;HTML> runtime! syntax/html.vim
This will match:
- Any file whose name ends in `.html'
- Any file whose type is `&faf' or 'HTML', where the meaning of these types
depends on which version of Vim you are using.
Unknown types are considered NOT to match.
You can also specify a type and a pattern at the same time (in which case they
must both match): >
:au BufRead <&fff>diff*
This will match files of type `&fff' whose names start with `diff'.
Note that osfiletype checking is skipped if Vim is compiled without the
|+osfiletype| feature.
*plugin-details*
The "plugin" directory can be in any of the directories in the 'runtimepath'
option. All of these directories will be searched for plugins and they are
all loaded. For example, if this command: >
set runtimepath
produces this output: >
runtimepath=/etc/vim,~/.vim,/usr/local/share/vim/vim60
then Vim will load all plugins in these directories: >
/etc/vim/plugin/
~/.vim/plugin/
/usr/local/share/vim/vim60/plugin/
Note that the last one is the value of $VIMRUNTIME which has been expanded.
What if it looks like your plugin is not being loaded? You can find out what
happens when Vim starts up by using the |-V| argument: >
vim -V1
You will see a lot of messages, in between them is a remark about loading the
plugins. It starts with: >
Searching for "plugin/*.vim" in
There you can see where Vim looks for your plugin scripts.
==============================================================================
2. Filetype plugin *filetype-plugins*
When loading filetype plugins has been enabled |:filetype-plugin-on|, options
will be set and mappings defined. These are all local to the buffer, they
will not be used for other files.
Defining mappings for a filetype may get in the way of the mappings you
define yourself. There are a few ways to avoid this:
1. Set the "maplocalleader" variable to the key sequence you want the mappings
to start with. Example: >
:let maplocalleader = ","
< All mappings will then start with a comma instead of the default, which
is a backslash. Also see |<LocalLeader>|.
2. Define your own mapping. Example: >
:map ,p <Plug>MailQuote
< You need to check the description of the plugin file below for the
functionality it offers and the string to map to.
You need to define your own mapping before the plugin is loaded (before
editing a file of that type). The plugin will then skip installing the
default mapping.
3. Disable defining mappings for a specific filetype by setting a variable,
which contains the name of the filetype. For the "mail" filetype this
would be: >
:let no_mail_maps = 1
4. Disable defining mappings for all filetypes by setting a variable: >
:let no_plugin_maps = 1
<
*ftplugin-overrule*
If a global filetype plugin does not do exactly what you want, there are three
ways to change this:
1. Add a few settings.
You must create a new filetype plugin in a directory early in
'runtimepath'. For Unix, for example you could use this file: >
vim ~/.vim/ftplugin/fortran.vim
< You can set those settings and mappings that you would like to add. Note
that the global plugin will be loaded after this, it may overrule the
settings that you do here. If this is the case, you need to use one of the
following two methods.
2. Make a copy of the plugin and change it.
You must put the copy in a directory early in 'runtimepath'. For Unix, for
example, you could do this: >
cp $VIMRUNTIME/ftplugin/fortran.vim ~/.vim/ftplugin/fortran.vim
< Then you can edit the copied file to your liking. Since the b:did_ftplugin
variable will be set, the global plugin will not be loaded.
A disadvantage of this method is that when the distributed plugin gets
improved, you will have to copy and modify it again.
3. Overrule the settings after loading the global plugin.
You must create a new filetype plugin in a directory from the end of
'runtimepath'. For Unix, for example, you could use this file: >
vim ~/.vim/after/ftplugin/fortran.vim
< In this file you can change just those settings that you want to change.
==============================================================================
3. Docs for the default filetype plugins. *ftplugin-docs*
CHANGELOG *changelog-plugin*
Allows for easy entrance of Changelog entries in Changelog files. There are
some commands, mappings, and variables worth exploring:
Options:
'comments' is made empty to not mess up formatting.
'textwidth' is set to 78, which is standard.
'formatoptions' the 't' flag is added to wrap when inserting text.
Commands:
NewChangelogEntry Adds a new Changelog entry in an intelligent fashion
(see below).
Local mappings:
<Leader>o Starts a new Changelog entry in an equally intelligent
fashion (see below).
Global mappings:
NOTE: The global mappings are accessed by sourcing the
ftplugin/changelog.vim file first, e.g. with >
runtime ftplugin/man.vim
< in your |.vimrc|.
<Leader>o Switches to the ChangeLog buffer opened for the
current directory, or opens it in a new buffer if it
exists in the current directory. Then it does the
same as the local <Leader>o described above.
Variables:
g:changelog_timeformat The date (and time) format used in ChangeLog entries.
The format accepted is the same as for the
|strftime()| function.
The default is "%Y-%m-%d" which is the standard format
for many ChangeLog layouts.
g:changelog_username The name and email address of the user.
The default is deduced from environment variables and
system files. It searches /etc/passwd for the comment
part of the current user, which informally contains
the real name of the user up to the first separating
comma. then it checks the $NAME environment variable
and finally runs `whoami` and `hostname` to build an
email address. The final form is >
Full Name <user@host>
<
g:changelog_new_date_format
The format to use when creating a new date-entry.
The following table describes special tokens in the
string:
%% insert a single '%' character
%d insert the date from above
%u insert the user from above
%c where to position cursor when done
The default is "%d %u\n\n\t* %c\n\n", which produces
something like (| is where cursor will be, unless at
the start of the line where it denotes the beginning
of the line) >
|2003-01-14 Full Name <user@host>
|
| * |
<
g:changelog_new_entry_format
The format used when creating a new entry.
The following table describes special tokens in the
string:
%c where to position cursor when done
The default is "\t*%c", which produces something
similar to >
| * |
<
g:changelog_date_entry_search
The search pattern to use when searching for a
date-entry.
The same tokens that can be used for
g:changelog_new_date_format can be used here as well.
The default is '^\s*%d\_s*%u' which finds lines
matching the form >
|2003-01-14 Full Name <user@host>
< and some similar formats.
The Changelog entries are inserted where they add the least amount of text.
After figuring out the current date and user, the file is searched for an
entry beginning with the current date and user and if found adds another item
under it. If not found, a new entry and item is prepended to the beginning of
the Changelog.
FORTRAN *fortran-plugin*
Options:
'expandtab' is switched on to avoid tabs as required by the Fortran
standards unless the user has set fortran_have_tabs in .vimrc.
'textwidth' is set to 72 for fixed source format as required by the
Fortran standards and to 80 for free source format.
'formatoptions' is set to break code and comment lines and to preserve long
lines. You can format comments with |gq|.
For further discussion of fortran_have_tabs and the method used for the
detection of source format see |fortran-syntax|.
MAIL *mail-plugin*
Options:
'modeline' is switched off to avoid the danger of trojan horses, and to
avoid that a Subject line with "Vim:" in it will cause an
error message.
'textwidth' is set to 72. This is often recommended for e-mail.
'formatoptions' is set to break text lines and to repeat the comment leader
in new lines, so that a leading ">" for quotes is repeated.
You can also format quoted text with |gq|.
Local mappings:
<LocalLeader>q or \\MailQuote
Quotes the text selected in Visual mode, or from the cursor position
to the end of the file in Normal mode. This means "> " is inserted in
each line.
MAN *man-plugin* *:Man*
Displays a manual page in a nice way. Also see the user manual
|find-manpage|.
To start using the ":Man" command before any manual page was loaded, source
this script from your startup vimrc file: >
runtime ftplugin/man.vim
Options:
'iskeyword' the '.' character is added to be able to use CTRL-] on the
manual page name.
Commands:
Man {name} Display the manual page for {name} in a window.
Man {number} {name}
Display the manual page for {name} in a section {number}.
Global mapping:
<Leader>K Displays the manual page for the word under the cursor.
Local mappings:
CTRL-] Jump to the manual page for the word under the cursor.
CTRL-T Jump back to the previous manual page.
RPM SPEC *spec-plugin*
Since the text for this plugin is rather long it has been put in a separate
file: |pi_spec.txt|.
vim:tw=78:ts=8:ft=help:norl:

581
runtime/doc/fold.txt Normal file
View File

@@ -0,0 +1,581 @@
*fold.txt* For Vim version 7.0aa. Last change: 2004 May 20
VIM REFERENCE MANUAL by Bram Moolenaar
Folding *Folding* *folding*
You can find an introduction on folding in chapter 28 of the user manual.
|usr_28.txt|
1. Fold methods |fold-methods|
2. Fold commands |fold-commands|
3. Fold options |fold-options|
4. Behavior of folds |fold-behavior|
{Vi has no Folding}
{not available when compiled without the +folding feature}
==============================================================================
1. Fold methods *fold-methods*
The folding method can be set with the 'foldmethod' option.
When setting 'foldmethod' to a value other than "manual", all folds are
deleted and new ones created. Switching to the "manual" method doesn't remove
the existing folds. This can be used to first define the folds automatically
and then change them manually.
There are six methods to select folds:
manual manually define folds
indent more indent means a higher fold level
expr specify an expression to define folds
syntax folds defined by syntax highlighting
diff folds for unchanged text
marker folds defined by markers in the text
MANUAL *fold-manual*
Use commands to manually define the fold regions. This can also be used by a
script that parses text to find folds.
The level of a fold is only defined by its nesting. To increase the fold
level of a fold for a range of lines, define a fold inside it that has the
same lines.
The manual folds are lost when you abandon the file. To save the folds use
the |:mkview| command. The view can be restored later with |:loadview|.
INDENT *fold-indent*
The folds are automatically defined by the indent of the lines.
The foldlevel is computed from the indent of the line, divided by the
'shiftwidth' (rounded down). A sequence of lines with the same or higher fold
level form a fold, with the lines with a higher level forming a nested fold.
The nesting of folds is limited with 'foldnestmax'.
Some lines are ignored and get the fold level of the line above or below it,
whatever is the lowest. These are empty or white lines and lines starting
with a character in 'foldignore'. White space is skipped before checking for
characters in 'foldignore'. For C use "#" to ignore preprocessor lines.
When you want to ignore lines in another way, use the 'expr' method. The
|indent()| function can be used in 'foldexpr' to get the indent of a line.
EXPR *fold-expr*
The folds are automatically defined by their foldlevel, like with the "indent"
method. The value of the 'foldexpr' option is evaluated to get the foldlevel
of a line. Examples:
This will create a fold for all consecutive lines that start with a Tab: >
:set foldexpr=getline(v:lnum)[0]==\"\\t\"
This will call a function to compute the fold level: >
:set foldexpr=MyFoldLevel(v:lnum)
This will make a fold out of paragraphs separated by blank lines: >
:set foldexpr=getline(v:lnum)=~'^\\s*$'&&getline(v:lnum+1)=~'\\S'?'<1':1
this does the same: >
:set foldexpr=getline(v:lnum-1)=~'^\\s*$'&&getline(v:lnum)=~'\\S'?'>1':1
Note that backslashes must be used to escape characters that ":set" handles
differently (space, backslash, double quote, etc., see |option-backslash|).
These are the conditions with which the expression is evaluated:
- The current buffer and window are set for the line.
- The variable "v:lnum" is set to the line number.
- The result is used for the fold level in this way:
value meaning ~
0 the line is not in a fold
1, 2, .. the line is in a fold with this level
-1 the fold level is undefined, use the fold level of a
line before or after this line, whichever is the
lowest.
"=" use fold level from the previous line
"a1", "a2", .. add one, two, .. to the fold level of the previous
line
"s1", "s2", .. subtract one, two, .. from the fold level of the
previous line
"<1", "<2", .. a fold with this level ends at this line
">1", ">2", .. a fold with this level starts at this line
It is not required to mark the start (end) of a fold with ">1" ("<1"), a fold
will also start (end) when the fold level is higher (lower) than the fold
level of the previous line.
There must be no side effects from the expression. The text in the buffer,
cursor position, the search patterns, options etc. must not be changed.
If there is some error in the expression, or the resulting value isn't
recognized, there is no error message and the fold level will be zero.
For debugging the 'debug' option can be set to "msg", the error messages will
be visible then.
Note: Since the expression has to be evaluated for every line, this fold
method can be very slow!
Try to avoid the "=", "a" and "s" return values, since Vim often has to search
backwards for a line for which the fold level is defined. This can be slow.
|foldlevel()| can be useful to compute a fold level relative to a previous
fold level. But note that foldlevel() may return -1 if the level is not known
yet. And it returns the level at the start of the line, while a fold might
end in that line.
SYNTAX *fold-syntax*
A fold is defined by syntax items that have the "fold" argument. |:syn-fold|
The fold level is defined by nesting folds. The nesting of folds is limited
with 'foldnestmax'.
Be careful to specify proper syntax syncing. If this is not done right, folds
may differ from the displayed highlighting. This is especially relevant when
using patterns that match more than one line. In case of doubt, try using
brute-force syncing: >
:syn sync fromstart
DIFF *fold-diff*
The folds are automatically defined for text that is not part of a change or
close to a change.
This method only works properly when the 'diff' option is set for the current
window and changes are being displayed. Otherwise the whole buffer will be
one big fold.
The 'diffopt' option can be used to specify the context. That is, the number
of lines between the fold and a change that are not included in the fold. For
example, to use a context of 8 lines: >
:set diffopt=filler,context:8
The default context is six lines.
When 'scrollbind' is also set, Vim will attempt to keep the same folds open in
other diff windows, so that the same text is visible.
MARKER *fold-marker*
Markers in the text tell where folds start and end. This allows you to
precisely specify the folds. This will allow deleting and putting a fold,
without the risk of including the wrong lines. The 'foldtext' option is
normally set such that the text before the marker shows up in the folded line.
This makes it possible to give a name to the fold.
Markers can have a level included, or can use matching pairs. Including a
level is easier, you don't have to add end markers and avoid problems with
non-matching marker pairs. Example: >
/* global variables {{{1 */
int varA, varB;
/* functions {{{1 */
/* funcA() {{{2 */
void funcA() {}
/* funcB() {{{2 */
void funcB() {}
A fold starts at a "{{{" marker. The following number specifies the fold
level. What happens depends on the difference between the current fold level
and the level given by the marker:
1. If a marker with the same fold level is encountered, the previous fold
ends and another fold with the same level starts.
2. If a marker with a higher fold level is found, a nested fold is started.
3. if a marker with a lower fold level is found, all folds up to and including
this level end and a fold with the specified level starts.
The number indicates the fold level. A zero cannot be used.
You can use "}}}" with a digit to indicate the level of the fold that
ends. The fold level of the following line will be one less than the
indicated level. Note that Vim doesn't look back to the level of the matching
marker (that would take too much time). Example: >
{{{1
fold level here is 1
{{{3
fold level here is 3
}}}3
fold level here is 2
You can also use matching pairs of "{{{" and "}}}" markers to define folds.
Each "{{{" increases the fold level by one, each "}}}" decreases the fold
level by one. Be careful to keep the markers matching! Example: >
{{{
fold level here is 1
{{{
fold level here is 2
}}}
fold level here is 1
You can mix using markers with a number and without a number. A useful way of
doing this is to use numbered markers for large folds, and unnumbered markers
locally in a function. For example use level one folds for the sections of
your file like "structure definitions", "local variables" and "functions".
Use level 2 markers for each definition and function, Use unnumbered markers
inside functions. When you make changes in a function to split up folds, you
don't have to renumber the markers.
The markers can be set with the 'foldmarker' option. It is recommended to
keep this at the default value of "{{{,}}}", so that files can be exchanged
between Vim users. Only change it when it is required for the file (e.g., it
contains markers from another folding editor, or the default markers cause
trouble for the language of the file).
*fold-create-marker*
"zf" can be used to create a fold defined by markers. Vim will insert the
markers for you. Vim will append the start and end marker, as specified with
'foldmarker'. The markers are appended to the end of the line.
'commentstring' is used if it isn't empty.
This does not work properly when:
- The line already contains a marker with a level number. Vim then doesn't
know what to do.
- Folds nearby use a level number in their marker which gets in the way.
- The line is inside a comment, 'commentstring' isn't empty and nested
comments don't work. For example with C: adding /* {{{ */ inside a comment
will truncate the existing comment. Either put the marker before or after
the comment, or add the marker manually.
Generally it's not a good idea to let Vim create markers when you already have
markers with a level number.
*fold-delete-marker*
"zd" can be used to delete a fold defined by markers. Vim will delete the
markers for you. Vim will search for the start and end markers, as specified
with 'foldmarker', at the start and end of the fold. When the text around the
marker matches with 'commentstring', that text is deleted as well.
This does not work properly when:
- A line contains more than one marker and one of them specifies a level.
Only the first one is removed, without checking if this will have the
desired effect of deleting the fold.
- The marker contains a level number and is used to start or end several folds
at the same time.
==============================================================================
2. Fold commands *fold-commands* *E490*
All folding commands start with "z". Hint: the "z" looks like a folded piece
of paper, if you look at it from the side.
CREATING AND DELETING FOLDS ~
*zf* *E350*
zf{motion} or
{Visual}zf Operator to create a fold.
This only works when 'foldmethod' is "manual" or "marker".
The new fold will be closed for the "manual" method.
'foldenable' will be set.
Also see |fold-create-marker|.
*zF*
zF Create a fold for N lines. Works like "zf".
:{range}fo[ld] *:fold* *:fo*
Create a fold for the lines in {range}. Works like "zf".
*zd* *E351*
zd Delete one fold at the cursor. When the cursor is on folded
line, that fold is deleted. Nested folds are moved one level
up. In Visual mode all folds (partially) in the selected area
are deleted. Careful: This easily deletes more folds than you
expect and there is no undo.
This only works when 'foldmethod' is "manual" or "marker".
Also see |fold-delete-marker|.
*zD*
zD Delete folds recursively at the cursor. In Visual mode all
folds (partially) in the selected area and all nested folds in
them are deleted.
This only works when 'foldmethod' is "manual" or "marker".
Also see |fold-delete-marker|.
*zE* *E352*
zE Eliminate all folds in the window.
This only works when 'foldmethod' is "manual" or "marker".
Also see |fold-delete-marker|.
OPENING AND CLOSING FOLDS ~
A fold smaller than 'foldminlines' will always be displayed like it was open.
Therefore the commands below may work differently on small folds.
*zo*
zo Open one fold under the cursor. When a count is given, that
many folds deep will be opened. In Visual mode one level of
folds is opened for all lines in the selected area.
*zO*
zO Open all folds under the cursor recursively. Folds that don't
contain the cursor line are unchanged.
In Visual mode it opens all folds that are in the selected
area, also those that are only partly selected.
*zc*
zc Close one fold under the cursor. When a count is given, that
many folds deep are closed. In Visual mode one level of folds
is closed for all lines in the selected area.
'foldenable' will be set.
*zC*
zC Close all folds under the cursor recursively. Folds that
don't contain the cursor line are unchanged.
In Visual mode it closes all folds that are in the selected
area, also those that are only partly selected.
'foldenable' will be set.
*za*
za When on a closed fold: open it. When folds are nested, you
may have to use "za" several times. When a count is given,
that many closed folds are opened.
When on an open fold: close it and set 'foldenable'. This
will only close one level, since using "za" again will open
the fold. When a count is given that many folds will be
closed (that's not the same as repeating "za" that many
times).
*zA*
zA When on a closed fold: open it recursively.
When on an open fold: close it recursively and set
'foldenable'.
*zv*
zv View cursor line: Open just enough folds to make the line in
which the cursor is located not folded.
*zx*
zx Update folds: Undo manually opened and closed folds: re-apply
'foldlevel', then do "zv": View cursor line.
*zX*
zX Undo manually opened and closed folds: re-apply 'foldlevel'.
*zm*
zm Fold more: Subtract one from 'foldlevel'. If 'foldlevel' was
already zero nothing happens.
'foldenable' will be set.
*zM*
zM Close all folds: set 'foldlevel' to 0.
'foldenable' will be set.
*zr*
zr Reduce folding: Add one to 'foldlevel'.
*zR*
zR Open all folds. This sets 'foldlevel' to highest fold level.
*:foldo* *:foldopen*
:{range}foldo[pen][!]
Open folds in {range}. When [!] is added all folds are
opened. Useful to see all the text in {range}. Without [!]
one level of folds is opened.
*:foldc* *:foldclose*
:{range}foldc[lose][!]
Close folds in {range}. When [!] is added all folds are
closed. Useful to hide all the text in {range}. Without [!]
one level of folds is closed.
*zn*
zn Fold none: reset 'foldenable'. All folds will be open.
*zN*
zN Fold normal: set 'foldenable'. All folds will be as they
were before.
*zi*
zi Invert 'foldenable'.
MOVING OVER FOLDS ~
*[z*
[z Move to the start of the current open fold. If already at the
start, move to the start of the fold that contains it. If
there is no containing fold, the command fails.
When a count is used, repeats the command N times.
*]z*
]z Move to the end of the current open fold. If already at the
end, move to the end of the fold that contains it. If there
is no containing fold, the command fails.
When a count is used, repeats the command N times.
*zj*
zj Move downwards to the start of the next fold. A closed fold
is counted as one fold.
When a count is used, repeats the command N times.
This command can be used after an |operator|.
*zk*
zk Move upwards to the end of the previous fold. A closed fold
is counted as one fold.
When a count is used, repeats the command N times.
This command can be used after an |operator|.
EXECUTING COMMANDS ON FOLDS ~
:[range]foldd[oopen] {cmd} *:foldd* *:folddoopen*
Execute {cmd} on all lines that are not in a closed fold.
When [range] is given, only these lines are used.
Each time {cmd} is executed the cursor is positioned on the
line it is executed for.
This works like the ":global" command: First all lines that
are not in a closed fold are marked. Then the {cmd} is
executed for all marked lines. Thus when {cmd} changes the
folds, this has no influence on where it is executed (except
when lines are deleted, of course).
Example: >
:folddoopen s/end/loop_end/ge
< Note the use of the "e" flag to avoid getting an error message
where "end" doesn't match.
:[range]folddoc[losed] {cmd} *:folddoc* *:folddoclosed*
Execute {cmd} on all lines that are in a closed fold.
Otherwise like ":folddoopen".
==============================================================================
3. Fold options *fold-options*
COLORS *fold-colors*
The colors of a closed fold are set with the Folded group |hl-Folded|. The
colors of the fold column are set with the FoldColumn group |hl-FoldColumn|.
Example to set the colors: >
:highlight Folded guibg=grey guifg=blue
:highlight FoldColumn guibg=darkgrey guifg=white
FOLDLEVEL *fold-foldlevel*
'foldlevel' is a number option: The higher the more folded regions are open.
When 'foldlevel' is 0, all folds are closed.
When 'foldlevel' is positive, some folds closed.
When 'foldlevel' is very high, all folds are open.
'foldlevel' is applied when it is changed. After that manually folds can be
opened and closed.
When increased, folds above the new level are opened. No manually opened
folds will be closed.
When decreased, folds above the new level are closed. No manually closed
folds will be opened.
FOLDTEXT *fold-foldtext*
'foldtext' is a string option that specifies an expression. This expression
is evaluated to obtain the text displayed for a closed fold. Example: >
:set foldtext=v:folddashes.substitute(getline(v:foldstart),'/\\*\\\|\\*/\\\|{{{\\d\\=','','g')
This shows the first line of the fold, with "/*", "*/" and "{{{" removed.
Note the use of backslashes to avoid some characters to be interpreted by the
":set" command. It's simpler to define a function and call that: >
:set foldtext=MyFoldText()
:function MyFoldText()
: let line = getline(v:foldstart)
: let sub = substitute(line, '/\*\|\*/\|{{{\d\=', '', 'g')
: return v:folddashes . sub
:endfunction
Evaluating 'foldtext' is done in the |sandbox|. The current window is set to
the window that displays the line. Errors are ignored.
The default value is |foldtext()|. This returns a reasonable text for most
types of folding. If you don't like it, you can specify your own 'foldtext'
expression. It can use these special Vim variables:
v:foldstart line number of first line in the fold
v:foldend line number of last line in the fold
v:folddashes a string that contains dashes to represent the
foldlevel.
v:foldlevel the foldlevel of the fold
In the result a TAB is replaced with a space and unprintable characters are
made into printable characters.
The resulting line is truncated to fit in the window, it never wraps.
When there is room after the text, it is filled with the character specified
by 'fillchars'.
Note that backslashes need to be used for characters that the ":set" command
handles differently: Space, backslash and double-quote. |option-backslash|
FOLDCOLUMN *fold-foldcolumn*
'foldcolumn' is a number, which sets the width for a column on the side of the
window to indicate folds. When it is zero, there is no foldcolumn. A normal
value is 4 or 5. The minimal useful value is 2. The maximum is 12.
An open fold is indicated with a column that has a '-' at the top and '|'
characters below it. This column stops where the open fold stops. When folds
nest, the nested fold is one character right of the fold it's contained in.
A closed fold is indicated with a '+'.
Where the fold column is too narrow to display all nested folds, digits are
shown to indicate the nesting level.
The mouse can also be used to open and close folds by clicking in the
fold column:
- Click on a '+' to open the closed fold at this row.
- Click on any other non-blank character to close the open fold at this row.
OTHER OPTIONS
'foldenable' 'fen': Open all folds while not set.
'foldexpr' 'fde': Expression used for "expr" folding.
'foldignore' 'fdi': Characters used for "indent" folding.
'foldmarker' 'fmr': Defined markers used for "marker" folding.
'foldmethod' 'fdm': Name of the current folding method.
'foldminlines' 'fml': Minimum number of screen lines for a fold to be
displayed closed.
'foldnestmax' 'fdn': Maximum nesting for "indent" and "syntax" folding.
'foldopen' 'fdo': Which kinds of commands open closed folds.
'foldclose' 'fcl': When the folds not under the cursor are closed.
==============================================================================
4. Behavior of folds *fold-behavior*
When moving the cursor upwards or downwards and when scrolling, the cursor
will move to the first line of a sequence of folded lines. When the cursor is
already on a folded line, it moves to the next unfolded line or the next
closed fold.
While the cursor is on folded lines, the cursor is always displayed in the
first column. The ruler does show the actual cursor position, but since the
line is folded, it cannot be displayed there.
Many movement commands handle a sequence of folded lines like an empty line.
For example, the "w" command stops once in the first column.
When in Insert mode, the cursor line is never folded. That allows you to see
what you type!
When using an operator, a closed fold is included as a whole. Thus "dl"
deletes the whole closed fold under the cursor.
For Ex commands the range is adjusted to always start at the first line of a
fold and end at the last line of a fold. Thus this command: >
:s/foo/bar/g
when used with the cursor on a closed fold, will replace "foo" with "bar" in
all lines of the fold.
This does not happen for |:folddoopen| and |:folddoclosed|.
When editing a buffer that has been edited before, the last used folding
settings are used again. For manual folding the defined folds are restored.
For all folding methods the manually opened and closed folds are restored.
If this buffer has been edited in this window, the values from back then are
used. Otherwise the values from the window where the buffer was edited last
are used.
==============================================================================
vim:tw=78:ts=8:ft=help:norl:

951
runtime/doc/gui.txt Normal file
View File

@@ -0,0 +1,951 @@
*gui.txt* For Vim version 7.0aa. Last change: 2004 Jun 02
VIM REFERENCE MANUAL by Bram Moolenaar
Vim's Graphical User Interface *gui* *GUI*
1. Starting the GUI |gui-start|
2. Scrollbars |gui-scrollbars|
3. Mouse Control |gui-mouse|
4. Making GUI Selections |gui-selections|
5. Menus |menus|
6. Extras |gui-extras|
7. Shell Commands |gui-shell|
Other GUI documentation:
|gui_x11.txt| For specific items of the X11 GUI.
|gui_w32.txt| For specific items of the Win32 GUI.
{Vi does not have any of these commands}
==============================================================================
1. Starting the GUI *gui-start* *E229* *E233*
First you must make sure you actually have a version of Vim with the GUI code
included. You can check this with the ":version" command, it should include
"+GUI_Athena", "+GUI_BeOS", "+GUI_GTK", "+GUI_Motif" or "MS-Windows ... bit
GUI version".
How to start the GUI depends on the system used. Mostly you can run the
GUI version of Vim with:
gvim [options] [files...]
The X11 version of Vim can run both in GUI and in non-GUI mode. See
|gui-x11-start|.
*gui-init* *gvimrc* *.gvimrc* *_gvimrc*
When the GUI starts up initializations are carried out, in this order:
- The termcap options are reset to their default value for the GUI.
- If the system menu file exists, it is sourced. The name of this file is
normally "$VIMRUNTIME/menu.vim". You can check this with ":version". Also
see |$VIMRUNTIME|. To skip loading the system menu include 'M' in
'guioptions'. *buffers-menu* *no_buffers_menu*
The system menu file includes a "Buffers" menu. If you don't want this, set
the "no_buffers_menu" variable in your .vimrc (not .gvimrc!): >
:let no_buffers_menu = 1
< NOTE: Switching on syntax highlighting also loads the menu file, thus
disabling the Buffers menu must be done before ":syntax on".
The path names are truncated to 35 characters. You can truncate them at a
different length, for example 50, like this: >
:let bmenu_max_pathlen = 50
- If the "-U {gvimrc}" command-line option has been used when starting Vim,
the {gvimrc} file will be read for initializations. The following
initializations are skipped.
- For Unix and MS-Windows, if the system gvimrc exists, it is sourced. The
name of this file is normally "$VIM/gvimrc". You can check this with
":version". Also see |$VIM|.
- The following are tried, and only the first one that exists is used:
- If the GVIMINIT environment variable exists and is not empty, it is
executed as an Ex command.
- If the user gvimrc file exists, it is sourced. The name of this file is
normally "$HOME/.gvimrc". You can check this with ":version".
- For Win32, when $HOME is not set, "$VIM\_gvimrc" is used.
- When a "_gvimrc" file is not found, ".gvimrc" is tried too. And vice
versa.
- If the 'exrc' option is set (which is NOT the default) the file ./.gvimrc
is sourced, if it exists and isn't the same file as the system or user
gvimrc file. If this file is not owned by you, some security restrictions
apply. When ".gvimrc" is not found, "_gvimrc" is tried too. For Macintosh
and DOS/Win32 "_gvimrc" is tried first.
NOTE: All but the first one are not carried out if Vim was started with
"-u NONE" and no "-U" argument was given, or when started with "-U NONE".
All this happens AFTER the normal Vim initializations, like reading your
.vimrc file. See |initialization|.
But the GUI window is only opened after all the initializations have been
carried out. If you want some commands to be executed just after opening the
GUI window, use the |GUIEnter| autocommand event. Example: >
:autocommand GUIEnter * winpos 100 50
You can use the gvimrc files to set up your own customized menus (see |:menu|)
and initialize other things that you may want to set up differently from the
terminal version.
Recommended place for your personal GUI initializations:
Unix $HOME/.gvimrc
OS/2 $HOME/.gvimrc or $VIM/.gvimrc
MS-DOS and Win32 $HOME/_gvimrc or $VIM/_gvimrc
Amiga s:.gvimrc or $VIM/.gvimrc
There are a number of options which only have meaning in the GUI version of
Vim. These are 'guicursor', 'guifont', 'guipty' and 'guioptions'. They are
documented in |options.txt| with all the other options.
If using the Motif or Athena version of the GUI (but not for the GTK+ or Win32
version), a number of X resources are available. See |gui-resources|.
Another way to set the colors for different occasions is with highlight
groups. The "Normal" group is used to set the background and foreground
colors. Example (which looks nice): >
:highlight Normal guibg=grey90
The "guibg" and "guifg" settings override the normal background and
foreground settings. The other settings for the Normal highlight group are
not used. Use the 'guifont' option to set the font.
Also check out the 'guicursor' option, to set the colors for the cursor in
various modes.
Vim tries to make the window fit on the screen when it starts up. This avoids
that you can't see part of it. On the X Window System this requires a bit of
guesswork. You can change the height that is used for the window title and a
task bar with the 'guiheadroom' option.
*:winp* *:winpos* *E188*
:winp[os]
Display current position of the top left corner of the GUI vim
window in pixels. Does not work in all versions.
:winp[os] {X} {Y} *E466*
Put the GUI vim window at the given {X} and {Y} coordinates.
The coordinates should specify the position in pixels of the
top left corner of the window. Does not work in all versions.
Does work in an (new) xterm |xterm-color|.
When the GUI window has not been opened yet, the values are
remembered until the window is opened. The position is
adjusted to make the window fit on the screen (if possible).
*:win* *:winsize* *E465*
:win[size] {width} {height}
Set the window height to {width} by {height} characters.
Obsolete, use ":set lines=11 columns=22".
If you get less lines than expected, check the 'guiheadroom'
option.
If you are running the X Window System, you can get information about the
window Vim is running in with this command: >
:!xwininfo -id $WINDOWID
==============================================================================
2. Scrollbars *gui-scrollbars*
There are vertical scrollbars and a horizontal scrollbars. You may
configure which ones appear with the 'guioptions' option.
The interface looks like this (with ":set guioptions=mlrb"):
+------------------------------+
| File Edit Help | <- Menu bar (m)
+-+--------------------------+-+
|^| |^|
|#| Text area. |#|
| | | |
|v|__________________________|v|
Normal status line -> |-+ File.c 5,2 +-|
between Vim windows |^|""""""""""""""""""""""""""|^|
| | | |
| | Another file buffer. | |
| | | |
|#| |#|
Left scrollbar (l) -> |#| |#| <- Right
|#| |#| scrollbar (r)
| | | |
|v| |v|
+-+--------------------------+-+
| |< #### >| | <- Bottom
+-+--------------------------+-+ scrollbar (b)
Any of the scrollbar or menu components may be turned off by not putting the
appropriate letter in the 'guioptions' string. The bottom scrollbar is
only useful when 'nowrap' is set.
VERTICAL SCROLLBARS *gui-vert-scroll*
Each Vim window has a scrollbar next to it which may be scrolled up and down
to move through the text in that buffer. The size of the scrollbar-thumb
indicates the fraction of the buffer which can be seen in the window.
When the scrollbar is dragged all the way down, the last line of the file
will appear in the top of the window.
If a window is shrunk to zero height (by the growth of another window) its
scrollbar disappears. It reappears when the window is restored.
If a window is vertically split, it will get a scrollbar when it is the
current window and when, taking the middle of the current window and drawing a
vertical line, this line goes through the window.
When there are scrollbars on both sides, and the middle of the current window
is on the left half, the right scrollbar column will contain scrollbars for
the rightmost windows. The same happens on the other side.
HORIZONTAL SCROLLBARS *gui-horiz-scroll*
The horizontal scrollbar (at the bottom of the Vim GUI) may be used to
scroll text sideways when the 'wrap' option is turned off. The
scrollbar-thumb size is such that the text of the longest visible line may be
scrolled as far as possible left and right. The cursor is moved when
necessary, it must remain on a visible character (unless 'virtualedit' is
set).
Computing the length of the longest visible takes quite a bit of computation,
and it has to be done every time something changes. If this takes too much
time or you don't like the cursor jumping to another line, include the 'h'
flag in 'guioptions'. Then the scrolling is limited by the text of the
current cursor line.
*athena-intellimouse*
If you have an Intellimouse and an X server that supports using the wheel,
then you can use the wheel to scroll the text up and down in gvim. This works
with XFree86 4.0 and later, and with some older versions when you add patches.
See |scroll-mouse-wheel|.
For older versions of XFree86 you must patch your X server. The following
page has a bit of information about using the Intellimouse on Linux as well as
links to the patches and X server binaries (may not have the one you need
though):
http://www.inria.fr/koala/colas/mouse-wheel-scroll/
==============================================================================
3. Mouse Control *gui-mouse*
The mouse only works if the appropriate flag in the 'mouse' option is set.
When the GUI is switched on, and 'mouse' wasn't set yet, the 'mouse' option is
automatically set to "a", enabling it for all modes except for the
|hit-enter| prompt. If you don't want this, a good place to change the
'mouse' option is the "gvimrc" file.
Other options that are relevant:
'mousefocus' window focus follows mouse pointer |gui-mouse-focus|
'mousemodel' what mouse button does which action
'mousehide' hide mouse pointer while typing text
'selectmode' whether to start Select mode or Visual mode
A quick way to set these is with the ":behave" command.
*:behave* *:be*
:be[have] {model} Set behavior for mouse and selection. Valid
arguments are:
mswin MS-Windows behavior
xterm Xterm behavior
Using ":behave" changes these options:
option mswin xterm ~
'selectmode' "mouse,key" ""
'mousemodel' "popup" "extend"
'keymodel' "startsel,stopsel" ""
'selection' "exclusive" "inclusive"
In the $VIMRUNTIME directory, there is a script called |mswin.vim|, which will
also map a few keys to the MS-Windows cut/copy/paste commands. This is NOT
compatible, since it uses the CTRL-V, CTRL-X and CTRL-C keys. If you don't
mind, use this command: >
:so $VIMRUNTIME/mswin.vim
For scrolling with a wheel on a mouse, see |scroll-mouse-wheel|.
3.1 Moving Cursor with Mouse *gui-mouse-move*
Click the left mouse button somewhere in a text buffer where you want the
cursor to go, and it does!
This works in when 'mouse' contains ~
Normal mode 'n' or 'a'
Visual mode 'v' or 'a'
Insert mode 'i' or 'a'
Select mode is handled like Visual mode.
You may use this with an operator such as 'd' to delete text from the current
cursor position to the position you point to with the mouse. That is, you hit
'd' and then click the mouse somewhere.
*gui-mouse-focus*
The 'mousefocus' option can be set to make the keyboard focus follow the
mouse pointer. This means that the window where the mouse pointer is, is the
active window. Warning: this doesn't work very well when using a menu,
because the menu command will always be applied to the top window.
If you are on the ':' line (or '/' or '?'), then clicking the left or right
mouse button will position the cursor on the ':' line (if 'mouse' contains
'c', 'a' or 'A').
In any situation the middle mouse button may be clicked to paste the current
selection.
3.2 Selection with Mouse *gui-mouse-select*
The mouse can be used to start a selection. How depends on the 'mousemodel'
option:
'mousemodel' is "extend": use the right mouse button
'mousemodel' is "popup": use the left mouse button, while keeping the Shift
key pressed.
If there was no selection yet, this starts a selection from the old cursor
position to the position pointed to with the mouse. If there already is a
selection then the closest end will be extended.
If 'selectmode' contains "mouse", then the selection will be in Select mode.
This means that typing normal text will replace the selection. See
|Select-mode|. Otherwise, the selection will be in Visual mode.
Double clicking may be done to make the selection word-wise, triple clicking
makes it line-wise, and quadruple clicking makes it rectangular block-wise.
See |gui-selections| on how the selection is used.
3.3 Other Text Selection with Mouse *gui-mouse-modeless*
*modeless-selection*
A different kind of selection is used when:
- in Command-line mode
- in the Command-line window and pointing in another window
- at the |hit-enter| prompt
- whenever the current mode is not in the 'mouse' option
- when holding the CTRL and SHIFT keys in the GUI
Since Vim continues like the selection isn't there, and there is no mode
associated with the selection, this is called modeless selection. Any text in
the Vim window can be selected. Select the text by pressing the left mouse
button at the start, drag to the end and release. To extend the selection,
use the right mouse button when 'mousemodel' is "extend", or the left mouse
button with the shift key pressed when 'mousemodel' is "popup".
The middle mouse button pastes the text.
The selection is removed when the selected text is scrolled or changed.
On the command line CTRL-Y can be used to copy the selection into the
clipboard. To do this from Insert mode, use CTRL-O : CTRL-Y <CR>.
3.4 Using Mouse on Status Lines *gui-mouse-status*
Clicking the left or right mouse button on the status line below a Vim
window makes that window the current window. This actually happens on button
release (to be able to distinguish a click from a drag action).
With the left mouse button a status line can be dragged up and down, thus
resizing the windows above and below it. This does not change window focus.
The same can be used on the vertical separator: click to give the window left
of it focus, drag left and right to make windows wider and narrower.
3.5 Various Mouse Clicks *gui-mouse-various*
<S-LeftMouse> Search forward for the word under the mouse click.
When 'mousemodel' is "popup" this starts or extends a
selection.
<S-RightMouse> Search backward for the word under the mouse click.
<C-LeftMouse> Jump to the tag name under the mouse click.
<C-RightMouse> Jump back to position before the previous tag jump
(same as "CTRL-T")
3.6 Mouse Mappings *gui-mouse-mapping*
The mouse events, complete with modifiers, may be mapped. Eg: >
:map <S-LeftMouse> <RightMouse>
:map <S-LeftDrag> <RightDrag>
:map <S-LeftRelease> <RightRelease>
:map <2-S-LeftMouse> <2-RightMouse>
:map <2-S-LeftDrag> <2-RightDrag>
:map <2-S-LeftRelease> <2-RightRelease>
:map <3-S-LeftMouse> <3-RightMouse>
:map <3-S-LeftDrag> <3-RightDrag>
:map <3-S-LeftRelease> <3-RightRelease>
:map <4-S-LeftMouse> <4-RightMouse>
:map <4-S-LeftDrag> <4-RightDrag>
:map <4-S-LeftRelease> <4-RightRelease>
These mappings make selection work the way it probably should in a Motif
application, with shift-left mouse allowing for extending the visual area
rather than the right mouse button.
Mouse mapping with modifiers does not work for modeless selection.
3.7 Drag and drop *drag-n-drop*
You can drag and drop one or more files into the Vim window, where they will
be opened as if a |:drop| command was used.
If you hold down Shift while doing this, Vim changes to the first dropped
file's directory. If you hold Ctrl Vim will always split a new window for the
file. Otherwise it's only done if the current buffer has been changed.
You can also drop a directory on Vim. This starts the explorer plugin for
that directory (assuming it was enabled, otherwise you'll get an error
message). Keep Shift pressed to change to the directory instead.
If Vim happens to be editing a command line, the names of the dropped files
and directories will be inserted at the cursor. This allows you to use these
names with any Ex command. Special characters (space, tab, double quote and
'|'; backslash on non-MS-Windows systems) will be escaped.
==============================================================================
4. Making GUI Selections *gui-selections*
*quotestar*
You may make selections with the mouse (see |gui-mouse-select|), or by using
Vim's Visual mode (see |v|). If 'a' is present in 'guioptions', then
whenever a selection is started (Visual or Select mode), or when the selection
is changed, Vim becomes the owner of the windowing system's primary selection
(on MS-Windows the |gui-clipboard| is used; under X11, the |x11-selection| is
used - you should read whichever of these is appropriate now).
*clipboard*
There is a special register for storing this selection, it is the "*
register. Nothing is put in here unless the information about what text is
selected is about to change (eg with a left mouse click somewhere), or when
another application wants to paste the selected text. Then the text is put
in the "* register. For example, to cut a line and make it the current
selection/put it on the clipboard: >
"*dd
Similarly, when you want to paste a selection from another application, e.g.,
by clicking the middle mouse button, the selection is put in the "* register
first, and then 'put' like any other register. For example, to put the
selection (contents of the clipboard): >
"*p
When using this register under X11, also see |x11-selection|. This also
explains the related "+ register.
Note that when pasting text from one Vim into another separate Vim, the type
of selection (character, line, or block) will also be copied. For other
applications the type is always character. However, if the text gets
transferred via the |x11-cut-buffer|, the selection type is ALWAYS lost.
When the "unnamed" string is included in the 'clipboard' option, the unnamed
register is the same as the "* register. Thus you can yank to and paste the
selection without prepending "* to commands.
==============================================================================
5. Menus *menus*
For an introduction see |usr_42.txt| in the user manual.
5.1 Using Menus *using-menus*
Basically, menus can be used just like mappings. You can define your own
menus, as many as you like.
Long-time Vim users won't use menus much. But the power is in adding your own
menus and menu items. They are most useful for things that you can't remember
what the key sequence was.
For creating menus in a different language, see |:menutrans|.
*menu.vim*
The default menus are read from the file "$VIMRUNTIME/menu.vim". See
|$VIMRUNTIME| for where the path comes from. You can set up your own menus.
Starting off with the default set is a good idea. You can add more items, or,
if you don't like the defaults at all, start with removing all menus
|:unmenu-all|. You can also avoid the default menus being loaded by adding
this line to your .vimrc file (NOT your .gvimrc file!): >
:let did_install_default_menus = 1
If you also want to avoid the Syntax menu: >
:let did_install_syntax_menu = 1
If you do want the Syntax menu but not all the entries for each available
syntax file (which take quite a bit of time to load): >
:let skip_syntax_sel_menu = 1
<
*console-menus*
Although this documentation is in the GUI section, you can actually use menus
in console mode too. You will have to load |menu.vim| explicitly then, it is
not done by default. You can use the |:emenu| command and command-line
completion with 'wildmenu' to access the menu entries almost like a real menu
system. To do this, put these commands in your .vimrc file: >
:source $VIMRUNTIME/menu.vim
:set wildmenu
:set cpo-=<
:set wcm=<C-Z>
:map <F4> :emenu <C-Z>
Pressing <F4> will start the menu. You can now use the cursor keys to select
a menu entry. Hit <Enter> to execute it. Hit <Esc> if you want to cancel.
This does require the |+menu| feature enabled at compile time.
*tear-off-menus*
GTK+ and Motif support Tear-off menus. These are sort of sticky menus or
pop-up menus that are present all the time. If the resizing does not work
correctly, this may be caused by using something like "Vim*geometry" in the
defaults. Use "Vim.geometry" instead.
The Win32 GUI version emulates Motif's tear-off menus. Actually, a Motif user
will spot the differences easily, but hopefully they're just as useful. You
can also use the |:tearoff| command together with |hidden-menus| to create
floating menus that do not appear on the main menu bar.
5.2 Creating New Menus *creating-menus*
*:me* *:menu* *:noreme* *:noremenu*
*:am* *:amenu* *:an* *:anoremenu*
*:nme* *:nmenu* *:nnoreme* *:nnoremenu*
*:ome* *:omenu* *:onoreme* *:onoremenu*
*:vme* *:vmenu* *:vnoreme* *:vnoremenu*
*:ime* *:imenu* *:inoreme* *:inoremenu*
*:cme* *:cmenu* *:cnoreme* *:cnoremenu*
*E330* *E327* *E331* *E336* *E333*
*E328* *E329* *E337*
To create a new menu item, use the ":menu" commands. They are mostly like
the ":map" set of commands but the first argument is a menu item name, given
as a path of menus and submenus with a '.' between them. eg: >
:menu File.Save :w<CR>
:inoremenu File.Save <C-O>:w<CR>
:menu Edit.Big\ Changes.Delete\ All\ Spaces :%s/[ ^I]//g<CR>
This last one will create a new item in the menu bar called "Edit", holding
the mouse button down on this will pop up a menu containing the item
"Big Changes", which is a sub-menu containing the item "Delete All Spaces",
which when selected, performs the operation.
Special characters in a menu name:
& The next character is the shortcut key. Make sure each
shortcut key is only used once in a (sub)menu. If you want to
insert a literal "&" in the menu name use "&&".
<Tab> Separates the menu name from right-aligned text. This can be
used to show the equivalent typed command. The text "<Tab>"
can be used here for convenience. If you are using a real
Tab, don't forget to put a backslash before it!
Example: >
:amenu &File.&Open<Tab>:e :browse e<CR>
[typed literally]
With the shortcut "F" (while keeping the <Alt> key pressed), and then "O",
this menu can be used. The second part is shown as "Open :e". The ":e"
is right aligned, and the "O" is underlined, to indicate it is the shortcut.
The ":amenu" command can be used to define menu entries for all modes at once.
To make the command work correctly, a character is automatically inserted for
some modes:
mode inserted appended ~
Normal nothing nothing
Visual <C-C> <C-\><C-G>
Insert <C-O>
Cmdline <C-C> <C-\><C-G>
Op-pending <C-C> <C-\><C-G>
Appending CTRL-\ CTRL-G is for going back to insert mode when 'insertmode' is
set. |CTRL-\_CTRL-G|
Example: >
:amenu File.Next :next^M
is equal to: >
:nmenu File.Next :next^M
:vmenu File.Next ^C:next^M^\^G
:imenu File.Next ^O:next^M
:cmenu File.Next ^C:next^M^\^G
:omenu File.Next ^C:next^M^\^G
Careful: In Insert mode this only works for a SINGLE Normal mode command,
because of the CTRL-O. If you have two or more commands, you will need to use
the ":imenu" command. For inserting text in any mode, you can use the
expression register: >
:amenu Insert.foobar "='foobar'<CR>P
Note that the '<' and 'k' flags in 'cpoptions' also apply here (when
included they make the <> form and raw key codes not being recognized).
Note that <Esc> in Cmdline mode executes the command, like in a mapping. This
is Vi compatible. Use CTRL-C to quit Cmdline mode.
*:menu-<silent>* *:menu-silent*
To define a menu which will not be echoed on the command line, add
"<silent>" as the first argument. Example: >
:menu <silent> Settings.Ignore\ case :set ic<CR>
The ":set ic" will not be echoed when using this menu. Messages from the
executed command are still given though. To shut them up too, add a ":silent"
in the executed command: >
:menu <silent> Search.Header :exe ":silent normal /Header\r"<CR>
<
*:menu-<script>* *:menu-script*
The "to" part of the menu will be inspected for mappings. If you don't want
this, use the ":noremenu" command (or the similar one for a specific mode).
If you do want to use script-local mappings, add "<script>" as the very first
argument to the ":menu" command or after "<silent>".
*menu-priority*
You can give a priority to a menu. Menus with a higher priority go more to
the right. The priority is given as a number before the ":menu" command.
Example: >
:80menu Buffer.next :bn<CR>
The default menus have these priorities:
File 10
Edit 20
Tools 40
Syntax 50
Buffers 60
Window 70
Help 9999
When no or zero priority is given, 500 is used.
The priority for the PopUp menu is not used.
The Help menu will be placed on the far right side of the menu bar on systems
which support this (Motif and GTK+). For GTK+ 2, this is not done anymore
because right-aligning the Help menu is now discouraged UI design.
You can use a priority higher than 9999, to make it go after the Help menu,
but that is non-standard and is discouraged. The highest possible priority is
about 32000. The lowest is 1.
*sub-menu-priority*
The same mechanism can be used to position a sub-menu. The priority is then
given as a dot-separated list of priorities, before the menu name: >
:menu 80.500 Buffer.next :bn<CR>
Giving the sub-menu priority is only needed when the item is not to be put
in a normal position. For example, to put a sub-menu before the other items: >
:menu 80.100 Buffer.first :brew<CR>
Or to put a sub-menu after the other items, and further items with default
priority will be put before it: >
:menu 80.900 Buffer.last :blast<CR>
When a number is missing, the default value 500 will be used: >
:menu .900 myMenu.test :echo "text"<CR>
The menu priority is only used when creating a new menu. When it already
existed, e.g., in another mode, the priority will not change. Thus, the
priority only needs to be given the first time a menu is used.
An exception is the PopUp menu. There is a separate menu for each mode
(Normal, Op-pending, Visual, Insert, Cmdline). The order in each of these
menus can be different. This is different from menu-bar menus, which have
the same order for all modes.
NOTE: sub-menu priorities currently don't work for all versions of the GUI.
*menu-separator* *E332*
Menu items can be separated by a special item that inserts some space between
items. Depending on the system this is displayed as a line or a dotted line.
These items must start with a '-' and end in a '-'. The part in between is
used to give it a unique name. Priorities can be used as with normal items.
Example: >
:menu Example.item1 :do something
:menu Example.-Sep- :
:menu Example.item2 :do something different
Note that the separator also requires a rhs. It doesn't matter what it is,
because the item will never be selected. Use a single colon to keep it
simple.
*gui-toolbar*
The toolbar is currently available in the Win32, Athena, Motif, GTK+ (X11) and
Photon GUI. It should turn up in other GUIs in due course. The default
toolbar is setup in menu.vim.
The display of the toolbar is controlled by the 'guioptions' letter 'T'. You
can thus have menu & toolbar together, or either on its own, or neither.
The appearance is controlled by the 'toolbar' option. You can chose between
an image, text or both.
*toolbar-icon*
The toolbar is defined as a special menu called ToolBar, which only has one
level. Vim interprets the items in this menu as follows:
1) If an "icon=" argument was specified, the file with this name is used.
The file can either be specified with the full path or with the base name.
In the last case it is searched for in the "bitmaps" directory in
'runtimepath', like in point 3). Examples: >
:amenu icon=/usr/local/pixmaps/foo_icon.xpm ToolBar.Foo :echo "Foo"<CR>
:amenu icon=FooIcon ToolBar.Foo :echo "Foo"<CR>
< Note that in the first case the extension is included, while in the second
case it is omitted.
If the file cannot be opened the next points are tried.
A space in the file name must be escaped with a backslash.
A menu priority must come _after_ the icon argument: >
:amenu icon=foo 1.42 ToolBar.Foo :echo "42!"<CR>
2) An item called 'BuiltIn##', where ## is a number, is taken as number ## of
the built-in bitmaps available in Vim. Currently there are 31 numbered
from 0 to 30 which cover most common editing operations |builtin-tools|. >
:amenu ToolBar.BuiltIn22 :call SearchNext("back")<CR>
3) An item with another name is first searched for in the directory
"bitmaps" in 'runtimepath'. If found, the bitmap file is used as the
toolbar button image. Note that the exact filename is OS-specific: For
example, under Win32 the command >
:amenu ToolBar.Hello :echo "hello"<CR>
< would find the file 'hello.bmp'. Under GTK+/X11 it is 'Hello.xpm'. With
GTK+ 2 the files 'Hello.png', 'Hello.xpm' and 'Hello.bmp' are checked for
existence, and the first one found would be used.
For MS-Windows and GTK+ 2 the bitmap is scaled to fit the button. For
MS-Windows a size of 18 by 18 pixels works best.
For MS-Windows the bitmap should have 16 colors with the standard palette.
The light grey pixels will be changed to the Window frame color and the
dark grey pixels to the window shadow color. More colors might also work,
depending on your system.
4) If the bitmap is still not found, Vim checks for a match against its list
of built-in names. Each built-in button image has a name.
So the command >
:amenu ToolBar.Open :e
< will show the built-in "open a file" button image if no open.bmp exists.
All the built-in names can be seen used in menu.vim.
5) If all else fails, a blank, but functioning, button is displayed.
*builtin-tools*
nr Name Normal action ~
00 New open new window
01 Open browse for file to open in current window
02 Save write buffer to file
03 Undo undo last change
04 Redo redo last undone change
05 Cut delete selected text to clipboard
06 Copy copy selected text to clipboard
07 Paste paste text from clipboard
08 Print print current buffer
09 Help open a buffer on Vim's builtin help
10 Find start a search command
11 SaveAll write all modified buffers to file
12 SaveSesn write session file for current situation
13 NewSesn write new session file
14 LoadSesn load session file
15 RunScript browse for file to run as a Vim script
16 Replace prompt for substitute command
17 WinClose close current window
18 WinMax make current window use many lines
19 WinMin make current window use few lines
20 WinSplit split current window
21 Shell start a shell
22 FindPrev search again, backward
23 FindNext search again, forward
24 FindHelp prompt for word to search help for
25 Make run make and jump to first error
26 TagJump jump to tag under the cursor
27 RunCtags build tags for files in current directory
28 WinVSplit split current window vertically
29 WinMaxWidth make current window use many columns
30 WinMinWidth make current window use few columns
*hidden-menus* *win32-hidden-menus*
In the Win32 and GTK+ GUI, starting a menu name with ']' excludes that menu
from the main menu bar. You must then use the |:popup| or |:tearoff| command
to display it.
*popup-menu*
In the Win32, GTK+, Motif, Athena and Photon GUI, you can define the special
menu "PopUp". This is the menu that is displayed when the right mouse button
is pressed, if 'mousemodel' is set to popup or popup_setpos.
5.3 Showing What Menus Are Mapped To *showing-menus*
To see what an existing menu is mapped to, use just one argument after the
menu commands (just like you would with the ":map" commands). If the menu
specified is a submenu, then all menus under that hierarchy will be shown.
If no argument is given after :menu at all, then ALL menu items are shown
for the appropriate mode (eg, Command-line mode for :cmenu).
Special characters in the list, just before the rhs:
* The menu was defined with "nore" to disallow remapping.
& The menu was defined with "<script>" to allow remapping script-local
mappings only.
- The menu was disabled.
Note that hitting <Tab> while entering a menu name after a menu command may
be used to complete the name of the menu item.
5.4 Executing Menus *execute-menus*
*:em* *:emenu* *E334* *E335*
:[range]em[enu] {menu} Execute {menu} from the command line.
The default is to execute the Normal mode
menu. If a range is specified, it executes
the Visual mode menu.
If used from <c-o>, it executes the
insert-mode menu Eg: >
:emenu File.Exit
If the console-mode vim has been compiled with WANT_MENU defined, you can
use :emenu to access useful menu items you may have got used to from GUI
mode. See 'wildmenu' for an option that works well with this. See
|console-menus| for an example.
When using a range, if the lines match with '<,'>, then the menu is executed
using the last visual selection.
5.5 Deleting Menus *delete-menus*
*:unme* *:unmenu*
*:aun* *:aunmenu*
*:nunme* *:nunmenu*
*:ounme* *:ounmenu*
*:vunme* *:vunmenu*
*:iunme* *:iunmenu*
*:cunme* *:cunmenu*
To delete a menu item or a whole submenu, use the unmenu commands, which are
analogous to the unmap commands. Eg: >
:unmenu! Edit.Paste
This will remove the Paste item from the Edit menu for Insert and
Command-line modes.
Note that hitting <Tab> while entering a menu name after an umenu command
may be used to complete the name of the menu item for the appropriate mode.
To remove all menus use: *:unmenu-all* >
:unmenu * " remove all menus in Normal and visual mode
:unmenu! * " remove all menus in Insert and Command-line mode
:aunmenu * " remove all menus in all modes
If you want to get rid of the menu bar: >
:set guioptions-=m
5.6 Disabling Menus *disable-menus*
*:menu-disable* *:menu-enable*
If you do not want to remove a menu, but disable it for a moment, this can be
done by adding the "enable" or "disable" keyword to a ":menu" command.
Examples: >
:menu disable &File.&Open\.\.\.
:amenu enable *
:amenu disable &Tools.*
The command applies to the modes as used with all menu commands. Note that
characters like "&" need to be included for translated names to be found.
When the argument is "*", all menus are affected. Otherwise the given menu
name and all existing submenus below it are affected.
5.7 Examples for Menus *menu-examples*
Here is an example on how to add menu items with menu's! You can add a menu
item for the keyword under the cursor. The register "z" is used. >
:nmenu Words.Add\ Var wb"zye:menu! Words.<C-R>z <C-R>z<CR>
:nmenu Words.Remove\ Var wb"zye:unmenu! Words.<C-R>z<CR>
:vmenu Words.Add\ Var "zy:menu! Words.<C-R>z <C-R>z <CR>
:vmenu Words.Remove\ Var "zy:unmenu! Words.<C-R>z<CR>
:imenu Words.Add\ Var <Esc>wb"zye:menu! Words.<C-R>z <C-R>z<CR>a
:imenu Words.Remove\ Var <Esc>wb"zye:unmenu! Words.<C-R>z<CR>a
(the rhs is in <> notation, you can copy/paste this text to try out the
mappings, or put these lines in your gvimrc; "<C-R>" is CTRL-R, "<CR>" is
the <CR> key. |<>|)
5.8 Tooltips & Menu tips
See section |42.4| in the user manual.
*:tmenu* *:tm*
:tm[enu] {menupath} {rhs} Define a tip for a menu or tool. {only in
X11 and Win32 GUI}
:tm[enu] [menupath] List menu tips. {only in X11 and Win32 GUI}
*:tunmenu* *:tu*
:tu[nmenu] {menupath} Remove a tip for a menu or tool.
{only in X11 and Win32 GUI}
When a tip is defined for a menu item, it appears in the command-line area
when the mouse is over that item, much like a standard Windows menu hint in
the status bar. (Except when Vim is in Command-line mode, when of course
nothing is displayed.)
When a tip is defined for a ToolBar item, it appears as a tooltip when the
mouse pauses over that button, in the usual fashion. Use the |hl-Tooltip|
highlight group to change its colors.
A "tip" can be defined for each menu item. For example, when defining a menu
item like this: >
:amenu MyMenu.Hello :echo "Hello"<CR>
The tip is defined like this: >
:tmenu MyMenu.Hello Displays a greeting.
And delete it with: >
:tunmenu MyMenu.Hello
Tooltips are currently only supported for the X11 and Win32 GUI. However, they
should appear for the other gui platforms in the not too distant future.
The ":tmenu" command works just like other menu commands, it uses the same
arguments. ":tunmenu" deletes an existing menu tip, in the same way as the
other unmenu commands.
If a menu item becomes invalid (i.e. its actions in all modes are deleted) Vim
deletes the menu tip (and the item) for you. This means that :aunmenu deletes
a menu item - you don't need to do a :tunmenu as well.
5.9 Popup Menus
In the Win32 and GTK+ GUI, you can cause a menu to popup at the cursor.
This behaves similarly to the PopUp menus except that any menu tree can
be popped up.
This command is for backwards compatibility, using it is discouraged, because
it behaves in a strange way.
*:popup* *:popu*
:popu[p] {name} Popup the menu {name}. The menu named must
have at least one subentry, but need not
appear on the menu-bar (see |hidden-menus|).
{only available for Win32 and GTK GUI}
Example: >
:popup File
will make the "File" menu (if there is one) appear at the text cursor. >
:amenu ]Toolbar.Make :make<CR>
:popup ]Toolbar
This creates a popup menu that doesn't exist on the main menu-bar.
Note that a menu that starts with ']' will not be displayed.
==============================================================================
6. Extras *gui-extras*
This section describes other features which are related to the GUI.
- With the GUI, there is no wait for one second after hitting escape, because
the key codes don't start with <Esc>.
- Typing ^V followed by a special key in the GUI will insert "<Key>", since
the internal string used is meaningless. Modifiers may also be held down to
get "<Modifiers-Key>".
- In the GUI, the modifiers SHIFT, CTRL, and ALT (or META) may be used within
mappings of special keys and mouse events. eg: :map <M-LeftDrag> <LeftDrag>
- In the GUI, several normal keys may have modifiers in mappings etc, these
are <Space>, <Tab>, <NL>, <CR>, <Esc>.
- To check in a Vim script if the GUI is being used, you can use something
like this: >
if has("gui_running")
echo "yes, we have a GUI"
else
echo "Boring old console"
endif
==============================================================================
7. Shell Commands *gui-shell*
For the X11 GUI the external commands are executed inside the gvim window.
See |gui-pty|.
WARNING: Executing an external command from the X11 GUI will not always
work. "normal" commands like "ls", "grep" and "make" mostly work fine.
Commands that require an intelligent terminal like "less" and "ispell" won't
work. Some may even hang and need to be killed from another terminal. So be
careful!
For the Win32 GUI the external commands are executed in a separate window.
See |gui-shell-win32|.
vim:tw=78:sw=4:ts=8:ft=help:norl:

186
runtime/doc/gui_w16.txt Normal file
View File

@@ -0,0 +1,186 @@
*gui_w16.txt* For Vim version 7.0aa. Last change: 2001 Sep 03
VIM REFERENCE MANUAL by Bram Moolenaar
Vim's Graphical User Interface *gui-w16* *win16-gui*
1. Starting the GUI |win16-start|
2. Vim as default editor |win16-default-editor|
3. Using the clipboard |win16-clipboard|
4. Shell Commands |win16-shell|
5. Special colors |win16-colors|
6. Windows dialogs & browsers |win16-dialogs|
7. Various |win16-various|
Other relevant documentation:
|gui.txt| For generic items of the GUI.
|os_msdos.txt| For items common to DOS and Windows.
|gui_w32.txt| Some items here are also applicable to the Win16 version.
{Vi does not have a Windows GUI}
The Win16 version of Vim will run on Windows 3.1 or later. It has not been
tested on 3.0, it probably won't work without being recompiled and
modified. (but you really should upgrade to 3.11 anyway. :)
In most respects it behaves identically to the Win32 GUI version, including
having a flat-style toolbar(!). The chief differences:
1) Bold/Italic text is not available, to speed up repaint/reduce resource
usage. (You can re-instate this by undefining MSWIN16_FASTTEXT.)
2) No tearoff menu emulation.
3) No OLE interface.
4) No long filename support (of course)
5) No tooltips on toolbar buttons - instead they produce command-line tips
like menu items do.
6) Line length limited to 32767 characters (like 16-bit DOS version)
==============================================================================
1. Starting the GUI *win16-start*
The Win16 GUI version of Vim will always start the GUI, no matter how you
start it or what it's called. There is no 'console' version as such, but you
can use one of the DOS versions in a DOS box.
The Win16 GUI has an extra menu item: "Window/Select Font". It brings up the
standard Windows font selector. Note that bold and italic fonts are not
supported in an attempt to maximize GDI drawing speed.
Setting the menu height doesn't work for the Win16 GUI.
*win16-maximized*
If you want Vim to start with a maximized window, add this command to your
vimrc or gvimrc file: >
au GUIEnter * simalt ~x
<
There is a specific version of gvim.exe that runs under the Win32s subsystem
of Windows 3.1 or 3.11. See |win32s|.
==============================================================================
2. Vim as default editor *win16-default-editor*
To set Vim as the default editor for a file type you can use File Manager's
"Associate" feature.
When you open a file in Vim by double clicking it, Vim changes to that
file's directory.
See also |notepad|.
==============================================================================
3. Using the clipboard *win16-clipboard*
Windows has a clipboard, where you can copy text to, and paste text from. Vim
supports this in several ways.
The clipboard works in the same way as the Win32 version: see |gui-clipboard|.
==============================================================================
4. Shell Commands *win16-shell*
Vim spawns a DOS window for external commands, to make it possible to run any
DOS command. The window uses the _default.pif settings.
*win16-!start*
Normally, Vim waits for a command to complete before continuing (this makes
sense for most shell commands which produce output for Vim to use). If you
want Vim to start a program and return immediately, you can use the following
syntax:
:!start {command}
This may only work for a Windows program though.
Don't forget that you must tell Windows 3.1x to keep executing a DOS command
in the background while you switch back to Vim.
==============================================================================
5. Special colors *win16-colors*
On Win16, the normal DOS colors can be used. See |dos-colors|.
Additionally the system configured colors can also be used. These are known
by the names Sys_XXX, where XXX is the appropriate system color name, from the
following list (see the Win32 documentation for full descriptions). Case is
ignored.
Sys_BTNFace Sys_BTNShadow Sys_ActiveBorder
Sys_ActiveCaption Sys_AppWorkspace Sys_Background
Sys_BTNText Sys_CaptionText Sys_GrayText
Sys_Highlight Sys_HighlightText Sys_InactiveBorder
Sys_InactiveCaption Sys_InactiveCaptionText Sys_Menu
Sys_MenuText Sys_ScrollBar Sys_Window
Sys_WindowFrame Sys_WindowText
Probably the most useful values are
Sys_Window Normal window background
Sys_WindowText Normal window text
Sys_Highlight Highlighted background
Sys_HighlightText Highlighted text
These extra colors are also available:
Gray, Grey, LightYellow, SeaGreen, Orange, Purple, SlateBlue, Violet,
See also |rgb.txt|.
==============================================================================
*win16-dialogs*
6. Windows dialogs & browsers
The Win16 GUI can use familiar Windows components for some operations, as well
as the traditional interface shared with the console version.
6.1 Dialogs
The dialogs displayed by the "confirm" family (i.e. the 'confirm' option,
|:confirm| command and |confirm()| function are GUI-based rather than the
console-based ones used by other versions. There is no option to change this.
6.2 File Browsers
When prepending ":browse" before file editing commands, a file requester is
used to allow you to select an existing file. See |:browse|.
==============================================================================
7. Various *win16-various*
*win16-printing*
The "File/Print" menu uses Notepad to print the current buffer. This is a bit
clumsy, but it's portable. If you want something else, you can define your
own print command. For example, you could look for the 16-bit version of
PrintFile. See $VIMRUNTIME/menu.vim for how it works by default.
Using this should also work: >
:w >>prn
Vim supports a number of standard MS Windows features. Some of these are
detailed elsewhere: see |'mouse'|, |win32-hidden-menus|.
Also see |:simalt|
*win16-drag-n-drop*
You can drag and drop one or more files into the vim window, where they will
be opened as normal. If you hold down Shift while doing this, Vim changes to
the (first) dropped file's directory. If you hold Ctrl, Vim will always split
a new window for the file. Otherwise it's only done if the current buffer has
been changed.
You can also drop a directory's icon, but rather than open all files in the
directory (which wouldn't usually be what you want) Vim instead changes to
that directory and begins a new file.
If Vim happens to be editing a command line, the names of the dropped files
and directories will be inserted at the cursor. This allows you to use these
names with any Ex command.
*win16-truetype*
It is recommended that you use a raster font and not a TrueType
fixed-pitch font. e.g. Use Courier, not Courier New. This is not just
to use less resources but because there are subtle bugs in the
handling of fixed-pitch TrueType in Win3.1x. In particular, when you move
a block cursor over a pipe character '|', the cursor is drawn in the wrong
size and bits get left behind. This is a bug in the Win3.1x GDI, it doesn't
happen if you run the exe under 95/NT.
vim:tw=78:sw=4:ts=8:ft=help:norl:

472
runtime/doc/gui_w32.txt Normal file
View File

@@ -0,0 +1,472 @@
*gui_w32.txt* For Vim version 7.0aa. Last change: 2004 May 03
VIM REFERENCE MANUAL by Bram Moolenaar
Vim's Win32 Graphical User Interface *gui-w32* *win32-gui*
1. Starting the GUI |gui-w32-start|
2. Vim as default editor |vim-default-editor|
3. Using the clipboard |gui-clipboard|
4. Shell Commands |gui-shell-win32|
5. Special colors |win32-colors|
6. Windows dialogs & browsers |gui-w32-dialogs|
7. Command line arguments |gui-w32-cmdargs|
8. Various |gui-w32-various|
Other relevant documentation:
|gui.txt| For generic items of the GUI.
|os_win32.txt| For Win32 specific items.
{Vi does not have a Windows GUI}
==============================================================================
1. Starting the GUI *gui-w32-start*
The Win32 GUI version of Vim will always start the GUI, no matter how you
start it or what it's called.
The GUI will always run in the Windows subsystem. Mostly shells automatically
return with a command prompt after starting gvim. If not, you should use the
"start" command: >
start gvim [options] file ..
Note: All fonts (bold, italic) must be of the same size!!! If you don't do
this, text will disappear or mess up the display. Vim does not check the font
sizes. It's the size in screen pixels that must be the same. Note that some
fonts that have the same point size don't have the same pixel size!
Additionally, the positioning of the fonts must be the same (ascent and
descent).
The Win32 GUI has an extra menu item: "Edit/Select Font". It brings up the
standard Windows font selector.
Setting the menu height doesn't work for the Win32 GUI.
*gui-win32-maximized*
If you want Vim to start with a maximized window, add this command to your
vimrc or gvimrc file: >
au GUIEnter * simalt ~x
<
*gui-w32s*
There is a specific version of gvim.exe that runs under the Win32s subsystem
of Windows 3.1 or 3.11. See |win32s|.
==============================================================================
2. Vim as default editor *vim-default-editor*
To set Vim as the default editor for a file type:
1. Start a Windows Explorer
2. Chose View/Options -> File Types
3. Select the path to gvim for every file type that you want to use it for.
(you can also use three spaces in the file type field, for files without an
extension).
In the "open" action, use: >
gvim "%1"
< The quotes are required for using file names with embedded spaces.
You can also use this: >
gvim "%L"
< This should avoid short (8.3 character) file names in some situations. But
I'm not sure if this works everywhere.
When you open a file in Vim by double clicking it, Vim changes to that
file's directory.
If you want Vim to start full-screen, use this for the Open action: >
gvim -c "simalt ~x" "%1"
Another method, which also works when you put Vim in another directory (e.g.,
when you have got a new version):
1. select a file you want to use Vim with
2. <Shift-F10>
3. select "Open With..." menu entry
4. click "Other..."
5. browse to the (new) location of Vim and click "Open"
6. make "Always Use this program..." checked
7. <OK>
*send-to-menu* *sendto*
You can also install Vim in the "Send To" menu:
1. Start a Windows Explorer
2. Navigate to your sendto directory:
Windows 95: %windir%\sendto (e.g. "c:\windows\sendto")
Windows NT: %windir%\profiles\%user%\sendto (e.g.
"c:\winnt\profiles\mattha\sendto").
3. Right-click in the file pane and select New->Shortcut
4. Follow the shortcut wizard, using the full path to VIM/GVIM.
When you 'send a file to Vim', Vim changes to that file's directory. Note,
however, that any long directory names will appear in their short (MS-DOS)
form. This is a limitation of the Windows "Send To" mechanism.
*notepad*
You could replace notepad.exe with gvim.exe, but that has a few side effects.
Some programs rely on notepad arguments, which are not recognized by Vim. For
example "notepad -p" is used by some applications to print a file. It's
better to leave notepad where it is and use another way to start Vim.
*win32-popup-menu*
A more drastic approach is to install an "Edit with Vim" entry in the popup
menu for the right mouse button. With this you can edit any file with Vim.
This can co-exist with the file associations mentioned above. The difference
is that the file associations will make starting Vim the default action. With
the "Edit with Vim" menu entry you can keep the existing file association for
double clicking on the file, and edit the file with Vim when you want. For
example, you can associate "*.mak" with your make program. You can execute
the makefile by double clicking it and use the "Edit with Vim" entry to edit
the makefile.
You can select any files and right-click to see a menu option called "Edit
with gvim". Chosing this menu option will invoke gvim with the file you have
selected. If you select multiple files, you will find two gvim-related menu
options:
"Edit with multiple gvims" -- one gvim for each file in the selection
"Edit with single gvim" -- one gvim for all the files in the selection
And if there already is a gvim running:
"Edit with existing gvim" -- edit the file with the running gvim
*install-registry*
You can add the "Edit with Vim" menu entry in an easy way by using the
"install.exe" program. It will add several registry entries for you.
You can also do this by hand. This is complicated! Use the install.exe if
you can.
1. Start the registry editor with "regedit".
2. Add these keys:
key value name value ~
HKEY_CLASSES_ROOT\CLSID\{51EEE242-AD87-11d3-9C1E-0090278BBD99}
{default} Vim Shell Extension
HKEY_CLASSES_ROOT\CLSID\{51EEE242-AD87-11d3-9C1E-0090278BBD99}\InProcServer32
{default} {path}\gvimext.dll
ThreadingModel Apartment
HKEY_CLASSES_ROOT\*\shellex\ContextMenuHandlers\gvim
{default} {51EEE242-AD87-11d3-9C1E-0090278BBD99}
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Approved
{51EEE242-AD87-11d3-9C1E-0090278BBD99}
Vim Shell Extension
HKEY_LOCAL_MACHINE\Software\Vim\Gvim
path {path}\gvim.exe
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall\vim 5.6
DisplayName Vim 5.6: Edit with Vim popup menu entry
UninstallString {path}\uninstal.exe
Replace {path} with the path that leads to the executable.
Don't type {default}, this is the value for the key itself.
To remove "Edit with Vim" from the popup menu, just remove the registry
entries mentioned above. The "uninstal.exe" program can do this for you. You
can also use the entry in the Windows standard "Add/Remove Programs" list.
If you notice that this entry overrules other file type associations, set
those associations again by hand (using Windows Explorer, see above). This
only seems to happen on some Windows NT versions (Windows bug?). Procedure:
1. Find the name of the file type. This can be done by starting the registry
editor, and searching for the extension in \\HKEY_CLASSES_ROOT
2. In a Windows Explorer, use View/Options/File Types. Search for the file
type in the list and click "Edit". In the actions list, you can select on
to be used as the default (normally the "open" action) and click on the
"Set Default" button.
Vim in the "Open With..." context menu *win32-open-with-menu*
If you use the Vim install program you have the choice to add Vim to the "Open
With..." menu. This means you can use Vim to edit many files. Not every file
(for unclear reasons...), thus the "Edit with Vim" menu entry is still useful.
One reason to add this is to be able to edit HTML files directly from Internet
Explorer. To enable this use the "Tools" menu, "Internet Options..." entry.
In the dialog select the "Programs" tab and select Vim in the "HTML editor"
choice. If it's not there than installing didn't work properly.
Doing this manually can be done with this script:
----------------------------------------------------------
REGEDIT4
[HKEY_CLASSES_ROOT\Applications\gvim.exe]
[HKEY_CLASSES_ROOT\Applications\gvim.exe\shell]
[HKEY_CLASSES_ROOT\Applications\gvim.exe\shell\edit]
[HKEY_CLASSES_ROOT\Applications\gvim.exe\shell\edit\command]
@="c:\\vim\\vim62\\gvim.exe \"%1\""
[HKEY_CLASSES_ROOT\.htm\OpenWithList\gvim.exe]
[HKEY_CLASSES_ROOT\*\OpenWithList\gvim.exe]
----------------------------------------------------------
Change the "c:\\vim\\vim62" bit to where gvim.exe is actually located.
To uninstall this run the Vim uninstall program or manually delete the
registry entries with "regedit".
==============================================================================
3. Using the clipboard *gui-clipboard*
Windows has a clipboard, where you can copy text to, and paste text from. Vim
supports this in several ways. For other systems see |gui-selections|.
The "* register reflects the contents of the clipboard. |quotestar|
When the "unnamed" string is included in the 'clipboard' option, the unnamed
register is the same. Thus you can yank to and paste from the clipboard
without prepending "* to commands.
The 'a' flag in 'guioptions' is not included by default. This means that text
is only put on the clipboard when an operation is performed on it. Just
Visually selecting text doesn't put it on the clipboard. When the 'a' flag is
included, the text is copied to the clipboard even when it is not operated
upon.
*mswin.vim*
To use the standard MS-Windows way of CTRL-X, CTRL-C and CTRL-V, use the
$VIMRUNTIME/mswin.vim script. You could add this line to your _vimrc file: >
source $VIMRUNTIME/mswin.vim
Since CTRL-C is used to copy the text to the clipboard, it can't be used to
cancel an operation. Use CTRL-Break for that.
*CTRL-V-alternative*
Since CTRL-V is used to paste, you can't use it to start a blockwise Visual
selection. You can use CTRL-Q instead. You can also use CTRL-Q in Insert
mode and Command-line mode to get the old meaning of CTRL-V. But CTRL-Q
doesn't work for terminals when it's used for control flow.
NOTE: The clipboard support still has a number of bugs. See |todo|.
==============================================================================
4. Shell Commands *gui-shell-win32*
Vim uses another window for external commands, to make it possible to run any
command. The external command gets its own environment for running, just like
it was started from a DOS prompt.
*win32-vimrun*
Executing an external command is done indirectly by the "vimrun" command. The
"vimrun.exe" must be in the path for this to work. Or it must be in the same
directory as the Vim executable. If "vimrun" cannot be found, the command is
executed directly, but then the DOS window closes immediately after the
external command has finished.
WARNING: If you close this window with the "X" button, and confirm the
question if you really want to kill the application, Vim may be killed too!
(This does not apply to commands run asynchronously with ":!start".)
In Windows 95, the window in which the commands are executed is always 25x80
characters, to be as DOS compatible as possible (this matters!). The default
system font is used. On NT, the window will be the default you have set up for
"Console" in Control Panel. On Win32s, the properties of the DOS box are
determined by _default.pif in the windows directory.
*msdos-mode*
If you get a dialog that says "This program is set to run in MS-DOS mode..."
when you run an external program, you can solve this by changing the
properties of the associated shortcut:
- Use a Windows Explorer to find the command.com that is used. It can be
c:\command.com, c:\dos\command.com, c:\windows\command.com, etc.
- With the right mouse button, select properties of this command.com.
- In the Program tab select "Advanced".
- Unselect "MS-DOS mode".
- Click "OK" twice.
*win32-!start*
Normally, Vim waits for a command to complete before continuing (this makes
sense for most shell commands which produce output for Vim to use). If you
want Vim to start a program and return immediately, you can use the following
syntax on W95 & NT: >
:!start {command}
On Win32s, you will have to go to another window instead. Don't forget that
you must tell Windows 3.1x to keep executing a DOS command in the background
while you switch back to Vim.
==============================================================================
5. Special colors *win32-colors*
On Win32, the normal DOS colors can be used. See |dos-colors|.
Additionally the system configured colors can also be used. These are known
by the names Sys_XXX, where XXX is the appropriate system color name, from the
following list (see the Win32 documentation for full descriptions). Case is
ignored. note: On Win32s not all of these colors are supported.
Sys_3DDKShadow Sys_3DFace Sys_BTNFace
Sys_3DHilight Sys_3DHighlight Sys_BTNHilight
Sys_BTNHighlight Sys_3DLight Sys_3DShadow
Sys_BTNShadow Sys_ActiveBorder Sys_ActiveCaption
Sys_AppWorkspace Sys_Background Sys_Desktop
Sys_BTNText Sys_CaptionText Sys_GrayText
Sys_Highlight Sys_HighlightText Sys_InactiveBorder
Sys_InactiveCaption Sys_InactiveCaptionText Sys_InfoBK
Sys_InfoText Sys_Menu Sys_MenuText
Sys_ScrollBar Sys_Window Sys_WindowFrame
Sys_WindowText
Probably the most useful values are
Sys_Window Normal window background
Sys_WindowText Normal window text
Sys_Highlight Highlighted background
Sys_HighlightText Highlighted text
These extra colors are also available:
Gray, Grey, LightYellow, SeaGreen, Orange, Purple, SlateBlue, Violet,
*rgb.txt*
Additionally, colors defined by a "rgb.txt" file can be used. This file is
well known from X11. A few lines from it: >
255 218 185 peach puff
205 133 63 peru
255 181 197 pink
This shows the layout of the file: First the R, G and B value as a decimal
number, followed by the name of the color. The four fields are separated by
spaces.
You can get an rgb.txt file from any X11 distribution. It is located in a
directory like "/usr/X11R6/lib/X11/". For Vim it must be located in the
$VIMRUNTIME directory. Thus the file can be found with "$VIMRUNTIME/rgb.txt".
==============================================================================
*gui-w32-dialogs* *dialog*
6. Windows dialogs & browsers
The Win32 GUI can use familiar Windows components for some operations, as well
as the traditional interface shared with the console version.
6.1 Dialogs
The dialogs displayed by the "confirm" family (i.e. the 'confirm' option,
|:confirm| command and |confirm()| function) are GUI-based rather than the
console-based ones used by other versions. The 'c' flag in 'guioptions'
changes this.
6.2 File Browsers
When prepending ":browse" before file editing commands, a file requester is
used to allow you to select an existing file. See |:browse|.
6.3 Tearoff Menus
The Win32 GUI emulates Motif's tear-off menus. At the top of each menu you
will see a small graphic "rip here" sign. Selecting it will cause a floating
window to be created with the same menu entries on it. The floating menu can
then be accessed just as if it was the original (including sub-menus), but
without having to go to the menu bar each time.
This is most useful if you find yourself using a command buried in a sub-menu
over and over again.
The tearoff menus can be positioned where you like, and always stay just above
the Main Vim window. You can get rid of them by closing them as usual; they
also of course close when you exit Vim.
*:tearoff* *:te*
:te[aroff] {name} Tear-off the menu {name}. The menu named must have at
least one subentry, but need not appear on the
menu-bar (see |win32-hidden-menus|).
Example: >
:tearoff File
will make the "File" menu (if there is one) appear as a tearoff menu. >
:amenu ]Toolbar.Make :make<CR>
:tearoff ]Toolbar
This creates a floating menu that doesn't exist on the main menu-bar.
Note that a menu that starts with ']' will not be displayed.
==============================================================================
7. Command line arguments *gui-w32-cmdargs*
Analysis of a command line into parameters is not standardised in MS Windows.
Gvim has to provide logic to analyse a command line. This logic is likely to
be different from the default logic provided by a compilation system used to
build vim. The differences relate to unusual double quote (") usage.
The arguments "C:\My Music\freude.txt" and "+/Sch\"iller" are handled in the
same way. The argument "+/Sch""iller" may be handled different by gvim and
vim, depending what it was compiled with.
The rules are:
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: >
gvim "C:\My Music\freude" +"set ignorecase" +/"\"foo\\" +\"bar\\\"
opens "C:\My Music\freude" and executes the line mode commands: >
set ignorecase; /"foo\ and /bar\"
==============================================================================
8. Various *gui-w32-various*
*gui-w32-printing*
The "File/Print" menu prints the text with syntax highlighting, see
|:hardcopy|. If you just want to print the raw text and have a default
printer installed this should also work: >
:w >>prn
Vim supports a number of standard MS Windows features. Some of these are
detailed elsewhere: see |'mouse'|, |win32-hidden-menus|.
*drag-n-drop-win32*
You can drag and drop one or more files into the Vim window, where they will
be opened as normal. See |drag-n-drop|.
*:simalt* *:si*
:sim[alt] {key} simulate pressing {key} while holding Alt pressed.
{not in Vi} {only for Win32 versions}
Normally, Vim takes control of all Alt-<Key> combinations, to increase the
number of possible mappings. This clashes with the standard use of Alt as the
key for accessing menus.
The quick way of getting standard behavior is to set the 'winaltkeys' option
to "yes". This however prevents you from mapping Alt keys at all.
Another way is to set 'winaltkeys' to "menu". Menu shortcut keys are then
handled by windows, other ALT keys can be mapped. This doesn't allow a
dependency on the current state though.
To get round this, the :simalt command allows Vim (when 'winaltkeys' is not
"yes") to fake a Windows-style Alt keypress. You can use this to map Alt key
combinations (or anything else for that matter) to produce standard Windows
actions. Here are some examples: >
:map <M-f> :simalt f<CR>
This makes Alt-F pop down the 'File' menu (with the stock Menu.vim) by
simulating the keystrokes Alt, F. >
:map <M-Space> :simalt ~<CR>
This maps Alt-Space to pop down the system menu for the Vim window. Note that
~ is used by simalt to represent the <Space> character. >
:map <C-n> :simalt ~n<CR>
Maps Control-N to produce the keys Alt-Space followed by N. This minimizes the
Vim window via the system menu.
*intellimouse-wheel-problems*
When using the Intellimouse mouse wheel causes Vim to stop accepting input, go
to:
ControlPanel - Mouse - Wheel - UniversalScrolling - Exceptions
And add gvim to the list of applications. This problem only appears to happen
with the Intellimouse driver 2.2 and when "Universal Scrolling" is turned on.
vim:tw=78:sw=4:ts=8:ft=help:norl:

576
runtime/doc/gui_x11.txt Normal file
View File

@@ -0,0 +1,576 @@
*gui_x11.txt* For Vim version 7.0aa. Last change: 2004 Mar 16
VIM REFERENCE MANUAL by Bram Moolenaar
Vim's Graphical User Interface *gui-x11* *GUI-X11*
*Athena* *Motif*
1. Starting the X11 GUI |gui-x11-start|
2. GUI Resources |gui-resources|
3. Shell Commands |gui-pty|
4. Various |gui-x11-various|
5. GTK version |gui-gtk|
6. GNOME version |gui-gnome|
7. Compiling |gui-x11-compiling|
8. X11 selection mechanism |x11-selection|
Other relevant documentation:
|gui.txt| For generic items of the GUI.
{Vi does not have any of these commands}
==============================================================================
1. Starting the X11 GUI *gui-x11-start* *E665*
Then you can run the GUI version of Vim in either of these ways:
gvim [options] [files...]
vim -g [options] [files...]
So if you call the executable "gvim", or make "gvim" a link to the executable,
then the GUI version will automatically be used. Additional characters may be
added after "gvim", for example "gvim-5".
You may also start up the GUI from within the terminal version by using one of
these commands:
:gui [++opt] [+cmd] [-f|-b] [files...] *:gu* *:gui*
:gvim [++opt] [+cmd] [-f|-b] [files...] *:gv* *:gvim*
The "-f" option runs Vim in the foreground.
The "-b" option runs Vim in the background (this is the default).
Also see |++opt| and |+cmd|.
*gui-fork*
When the GUI is started, it does a fork() and exits the current process.
When gvim was started from a shell this makes the shell accept further
commands. If you don't want this (e.g. when using gvim for a mail program
that waits for gvim to exit), start gvim with "gvim -f", "vim -gf" or use
":gui -f". Don't use "vim -fg", because "-fg" specifies the foreground
color.
When using "gvim -f" and then ":gui", Vim will run in the foreground. The
"-f" argument will be remembered. To force running Vim in the background use
":gui -b".
"gvim --nofork" does the same as "gvim -f".
If you want the GUI to run in the foreground always, include the 'f'
flag in 'guioptions'. |-f|.
==============================================================================
2. GUI Resources *gui-resources* *.Xdefaults*
If using the Motif or Athena version of the GUI (not for the GTK+ or Win32
version), a number of X resources are available. You should use Vim's class
"Vim" when setting these. They are as follows:
Resource name Meaning ~
reverseVideo Boolean: should reverse video be used?
background Color of background.
foreground Color of normal text.
scrollBackground Color of trough portion of scrollbars.
scrollForeground Color of slider and arrow portions of scrollbars.
menuBackground Color of menu backgrounds.
menuForeground Color of menu foregrounds.
tooltipForeground Color of tooltip and balloon foreground.
tooltipBackground Color of tooltip and balloon background.
font Name of font used for normal text.
boldFont Name of font used for bold text.
italicFont Name of font used for italic text.
boldItalicFont Name of font used for bold, italic text.
menuFont Name of font used for the menus, used when compiled
without the |+xfontset| feature
menuFontSet Name of fontset used for the menus, used when compiled
with the |+xfontset| feature
tooltipFont Name of the font used for the tooltip and balloons.
When compiled with the |+xfontset| feature this is a
fontset name.
geometry Initial geometry to use for gvim's window (default
is same size as terminal that started it).
scrollbarWidth Thickness of scrollbars.
borderWidth Thickness of border around text area.
menuHeight Height of the menu bar (only for Athena).
A special font for italic, bold, and italic-bold text will only be used if
the user has specified one via a resource. No attempt is made to guess what
fonts should be used for these based on the normal text font.
Note that the colors can also be set with the ":highlight" command, using the
"Normal", "Menu", "Tooltip", and "Scrollbar" groups. Example: >
:highlight Menu guibg=lightblue
:highlight Tooltip guibg=yellow
:highlight Scrollbar guibg=lightblue guifg=blue
:highlight Normal guibg=grey90
<
*font-sizes*
Note: All fonts (except for the menu and tooltip) must be of the same size!!!
If you don't do this, text will disappear or mess up the display. Vim does
not check the font sizes. It's the size in screen pixels that must be the
same. Note that some fonts that have the same point size don't have the same
pixel size! Additionally, the positioning of the fonts must be the same
(ascent and descent). You can check this with "xlsfonts -l {fontname}".
If any of these things are also set with Vim commands, eg with
":set guifont=Screen15", then this will override the X resources (currently
'guifont' is the only option that is supported).
Here is an example of what you might put in your ~/.Xdefaults file: >
Vim*useSchemes: all
Vim*sgiMode: true
Vim*useEnhancedFSB: true
Vim.foreground: Black
Vim.background: Wheat
Vim*fontList: 7x13
The first three of these are standard resources on Silicon Graphics machines
which make Motif applications look even better, highly recommended!
The "Vim*fontList" is to set the menu font for Motif. Example: >
Vim*menuBar*fontList: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
With Athena: >
Vim*menuBar*SmeBSB*font: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
Vim*menuBar*MenuButton*font: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
NOTE: A more portable, and indeed more correct, way to specify the menu font
in either Motif or Athena is through the resource: >
Vim.menuFont: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
Or, when compiled with the |+xfontset| feature: >
Vim.menuFontSet: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
Don't use "Vim*geometry" in the defaults. This will break the menus. Use
"Vim.geometry" instead.
If you get an error message "Cannot allocate colormap entry for "gray60",
try adding this to your Vim resources (change the colors to your liking): >
Vim*scrollBackground: Black
Vim*scrollForeground: Blue
The resources can also be set with arguments to Vim:
argument meaning ~
*-gui*
-display {display} Run vim on {display} *-display*
-iconic Start vim iconified *-iconic*
-background {color} Use {color} for the background *-background*
-bg {color} idem *-bg*
-foreground {color} Use {color} for normal text *-foreground*
-fg {color} idem *-fg*
-ul {color} idem *-ul*
-font {font} Use {font} for normal text *-font*
-fn {font} idem *-fn*
-boldfont {font} Use {font} for bold text *-boldfont*
-italicfont {font} Use {font} for italic text *-italicfont*
-menufont {font} Use {font} for menu items *-menufont*
-menufontset {fontset} Use {fontset} for menu items *-menufontset*
-mf {font} idem *-mf*
-geometry {geom} Use {geom} for initial geometry *-geometry*
-geom {geom} idem, see |-geometry-example| *-geom*
-borderwidth {width} Use a border width of {width} *-borderwidth*
-bw {width} idem *-bw*
*-scrollbarwidth*
-scrollbarwidth {width} Use a scrollbar width of {width}
-sw {width} idem *-sw*
-menuheight {height} Use a menu bar height of {height} *-menuheight*
-mh {height} idem *-mh*
NOTE: On Motif the value is ignored, the menu height
is computed to fit the menus.
-reverse Use reverse video *-reverse*
-rv idem *-rv*
+reverse Don't use reverse video *-+reverse*
+rv idem *-+rv*
-xrm {resource} Set the specified resource *-xrm*
Note about reverse video: Vim checks that the result is actually a light text
on a dark background. The reason is that some X11 versions swap the colors,
and some don't. These two examples will both give yellow text on a blue
background:
gvim -fg Yellow -bg Blue -reverse
gvim -bg Yellow -fg Blue -reverse
*-geometry-example*
An example for the geometry argument: >
gvim -geometry 80x63+8+100
This creates a window with 80 columns and 63 lines at position 8 pixels from
the left and 100 pixels from the top of the screen.
==============================================================================
3. Shell Commands *gui-pty*
WARNING: Executing an external command from the GUI will not always work.
"normal" commands like "ls", "grep" and "make" mostly work fine. Commands
that require an intelligent terminal like "less" and "ispell" won't work.
Some may even hang and need to be killed from another terminal. So be
careful!
There are two ways to do the I/O with a shell command: Pipes and a pseudo-tty.
The default is to use a pseudo-tty. This should work best on most systems.
Unfortunately, the implementation of the pseudo-tty is different on every Unix
system. And some systems require root permission. To avoid running into
problems with a pseudo-tty when you least expect it, test it when not editing
a file. Be prepared to "kill" the started command or Vim. Commands like
":r !cat" may hang!
If using a pseudo-tty does not work for you, reset the 'guipty' option: >
:set noguipty
Using a pipe should work on any Unix system, but there are disadvantages:
- Some shell commands will notice that a pipe is being used and behave
differently. E.g., ":!ls" will list the files in one column.
- The ":sh" command won't show a prompt, although it will sort of work.
- When using ":make" it's not possible to interrupt with a CTRL-C.
Typeahead while the external command is running is often lost. This happens
both with a pipe and a pseudo-tty. This is a known problem, but it seems it
can't be fixed (or at least, it's very difficult).
*gui-pty-erase*
When your erase character is wrong for an external command, you should fix
this in your "~/.cshrc" file, or whatever file your shell uses for
initializations. For example, when you want to use backspace to delete
characters, but hitting backspaces produces "^H" instead, try adding this to
your "~/.cshrc": >
stty erase ^H
The ^H is a real CTRL-H, type it as CTRL-V CTRL-H.
==============================================================================
4. Various *gui-x11-various*
*gui-x11-printing*
The "File/Print" menu simply sends the current buffer to "lpr". No options or
whatever. If you want something else, you can define your own print command.
For example: >
:10amenu File.Print :w !lpr -Php3
:10vmenu File.Print :w !lpr -Php3
<
*X11-icon*
Vim uses a black&white icon by default when compiled with Motif or Athena. A
colored Vim icon is included as $VIMRUNTIME/vim32x32.xpm. For GTK+, this is
the builtin icon used. Unfortunately, how you should install it depends on
your window manager. When you use this, remove the 'i' flag from
'guioptions', to remove the black&white icon: >
:set guioptions-=i
If you use one of the fvwm* family of window managers simply add this line to
your .fvwm2rc configuration file: >
Style "vim" Icon vim32x32.xpm
Make sure the icon file's location is consistent with the window manager's
ImagePath statement. Either modify the ImagePath from within your .fvwm2rc or
drop the icon into one the pre-defined directories: >
ImagePath /usr/X11R6/include/X11/pixmaps:/usr/X11R6/include/X11/bitmaps
Note: older versions of fvwm use "IconPath" instead of "ImagePath".
For CDE "dtwm" (a derivative of Motif) add this line in the .Xdefaults: >
Dtwm*Vim*iconImage: /usr/local/share/vim/vim32x32.xpm
For "mwm" (Motif window manager) the line would be: >
Mwm*Vim*iconImage: /usr/local/share/vim/vim32x32.xpm
Mouse Pointers Available in X11 *X11_mouse_shapes*
By using the |'mouseshape'| option, the mouse pointer can be automatically
changed whenever Vim enters one of its various modes (e.g., Insert or
Command). Currently, the available pointers are:
arrow an arrow pointing northwest
beam a I-like vertical bar
size an arrow pointing up and down
busy a wristwatch
blank an invisible pointer
crosshair a thin "+" sign
hand1 a dark hand pointing northeast
hand2 a light hand pointing northwest
pencil a pencil pointing southeast
question question_arrow
right_arrow an arrow pointing northeast
up_arrow an arrow pointing upwards
Additionally, any of the mouse pointers that are built into X11 may be
used by specifying an integer from the X11/cursorfont.h include file.
If a name is used that exists on other systems, but not in X11, the default
"arrow" pointer is used.
==============================================================================
5. GTK version *gui-gtk* *GTK+* *GTK*
The GTK version of the GUI works a little bit different.
GTK does _not_ use the traditional X resource settings. Thus items in your
~/.Xdefaults or app-defaults files are not used.
Many of the traditional X command line arguments are not supported. (e.g.,
stuff like -bg, -fg, etc). The ones that are supported are:
command line argument resource name meaning ~
-fn or -font .font font name for the text
-geom or -geometry .geometry size of the gvim window
-rv or -reverse *reverseVideo white text on black background
-display display to be used
-fg -foreground {color} foreground color
-bg -background {color} background color
To set the font, see |'guifont'|. For GTK, there's also a menu option that
does this.
Additionally, there are these command line arguments, which are handled by GTK
internally. Look in the GTK documentation for how they are used:
--sync
--gdk-debug
--gdk-no-debug
--no-xshm (not in GTK+ 2)
--xim-preedit (not in GTK+ 2)
--xim-status (not in GTK+ 2)
--gtk-debug
--gtk-no-debug
--g-fatal-warnings
--gtk-module
--display (GTK+ counterpart of -display; works the same way.)
--screen (The screen number; for GTK+ 2.2 multihead support.)
These arguments are ignored when the |+netbeans_intg| feature is used:
-xrm
-mf
As for colors, Vim's color settings (for syntax highlighting) is still
done the traditional Vim way. See |:highlight| for more help.
If you want to set the colors of remaining gui components (e.g., the
menubar, scrollbar, whatever), those are GTK specific settings and you
need to set those up in some sort of gtkrc file. You'll have to refer
to the GTK documentation, however little there is, on how to do this.
See http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html
for more information.
*gtk-tooltip-colors*
Example, which sets the tooltip colors to black on light-yellow: >
style "tooltips"
{
bg[NORMAL] = "#ffffcc"
fg[NORMAL] = "#000000"
}
widget "gtk-tooltips*" style "tooltips"
Write this in the file ~/.gtkrc and it will be used by GTK+. For GTK+ 2
you might have to use the file ~/.gtkrc-2.0 instead, depending on your
distribution.
Using Vim as a GTK+ plugin *gui-gtk-socketid*
When the GTK+ version of Vim starts up normally, it creates its own top level
window (technically, a 'GtkWindow'). GTK+ provides an embedding facility with
its GtkSocket and GtkPlug widgets. If one GTK+ application creates a
GtkSocket widget in one of its windows, an entirely different GTK+ application
may embed itself into the first application by creating a top-level GtkPlug
widget using the socket's ID.
If you pass Vim the command-line option '--socketid' with a decimal or
hexadecimal value, Vim will create a GtkPlug widget using that value instead
of the normal GtkWindow. This enables Vim to act as a GTK+ plugin.
This really is a programmer's interface, and is of no use without a supporting
application to spawn the Vim correctly. For more details on GTK+ sockets, see
http://www.gtk.org/api/
Note that this feature requires the latest GTK version. GTK 1.2.10 still has
a small problem. The socket feature has not yet been tested with GTK+ 2 --
feel free to volunteer.
==============================================================================
6. GNOME version *gui-gnome* *Gnome* *GNOME*
The GNOME GUI works just like the GTK+ version. See |GTK+| above for how it
works. It looks a bit different though, and implements one important feature
that's not available in the plain GTK+ GUI: Interaction with the session
manager. |gui-gnome-session|
These are the different looks:
- Uses GNOME dialogs (GNOME 1 only). The GNOME 2 GUI uses the same nice
dialogs as the GTK+ 2 version.
- Uses the GNOME dock, so that the toolbar and menubar can be moved to
different locations other than the top (e.g., the toolbar can be placed on
the left, right, top, or bottom). The placement of the menubar and
toolbar is only saved in the GNOME 2 version.
- That means the menubar and toolbar handles are back! Yeah! And the
resizing grid still works too.
GNOME is automatically compiled with if it was found by configure.
(FIXME: Is this still true? Use --enable-gnome-check to force it to.)
GNOME session support *gui-gnome-session* *gnome-session*
On logout, Vim shows the well-known exit confirmation dialog if any buffers
are modified. Clicking [Cancel] will stop the logout process. Otherwise the
current session is stored to disk by using the |:mksession| command, and
restored the next time you log in.
The GNOME session support should also work with the KDE session manager.
If you are experiencing any problems please report them as bugs.
Note: The automatic session save works entirely transparent, in order to
avoid conflicts with your own session files, scripts and autocommands. That
means in detail:
- The session file is stored to a separate directory (usually $HOME/.gnome2).
- 'sessionoptions' is ignored, and a hardcoded set of appropriate flags is
used instead: >
blank,curdir,folds,globals,help,options,winsize
- The internal variable |v:this_session| is not changed when storing the
session. Also, it is restored to its old value when logging in again.
The position and size of the GUI window is not saved by Vim since doing so
is the window manager's job. But if compiled with GTK+ 2 support, Vim helps
the WM to identify the window by restoring the window role (using the |--role|
command line argument).
==============================================================================
7. Compiling *gui-x11-compiling*
If using X11, Vim's Makefile will by default first try to find the necessary
GTK+ files on your system. If the GTK+ files cannot be found, then the Motif
files will be searched for. Finally, if this fails, the Athena files will be
searched for. If all three fail, the GUI will be disabled.
For GTK+, Vim's configuration process requires that GTK+ be properly
installed. That is, the shell script 'gtk-config' must be in your PATH, and
you can already successful compile, build, and execute a GTK+ program. The
reason for this is because the compiler flags (CFLAGS) and link flags
(LDFLAGS) are obtained through the 'gtk-config' shell script.
If you want to build with GTK+ 2 support pass the --enable-gtk2-check argument
to ./configure. Optionally, support for GNOME 2 will be compiled if the
--enable-gnome-check option is also given. Note that the support for GTK+ 2
is still experimental. However, many people have reported that it works just
fine for them.
Otherwise, if you are using Motif or Athena, when you have the Motif or Athena
files in a directory where configure doesn't look, edit the Makefile to enter
the names of the directories. Search for "GUI_INC_LOC" for an example to set
the Motif directories, "CONF_OPT_X" for Athena.
*gui-x11-gtk*
At the time of this writing, you may use either GTK+ version 1.0.6 or 1.2. It
is suggested that you use v1.2 since not all of Vim's GUI features are present
if using v1.0.6. For instance, there are no tearoff menus present in v1.0.6.
Using a version from GTK+'s CVS tree may or may not work, and is therefore not
supported and not recommended.
For the experimental GTK+ 2 GUI, using the latest release of the GTK+ 2.0 or
GTK+ 2.2 series is recommended. CVS HEAD seems to work fine most of time as
well.
Lastly, although GTK+ has supposedly been ported to the Win32 platform, this
has not been tested with Vim and is also unsupported. Also, it's unlikely to
even compile since GTK+ GUI uses parts of the generic X11 code. This might
change in distant future; particularly because getting rid of the X11 centric
code parts is also required for GTK+ framebuffer support.
*gui-x11-motif*
For Motif, you need at least Motif version 1.2 and/or X11R5. Motif 2.0 and
X11R6 are OK. Motif 1.1 and X11R4 might work, no guarantee (there may be a
few problems, but you might make it compile and run with a bit of work, please
send me the patches if you do). The newest releases of LessTif have been
reported to work fine too.
*gui-x11-athena*
The Athena version uses the Xaw widget set by default. If you have the 3D
version, you might want to link with Xaw3d instead. This will make the
menus look a bit better. Edit the Makefile and look for "XAW_LIB". The
scrollbars will remain the same, because Vim has its own, which are already
3D (in fact, they look more like Motif).
*gui-x11-neXtaw*
The neXtaw version is mostly like Athena, but uses different widgets.
*gui-x11-misc*
In general, do not try to mix files from different GTK+, Motif, Athena and X11
versions. This will cause problems. For example, using header files for
X11R5 with a library for X11R6 probably doesn't work (although the linking
won't give an error message, Vim will crash later).
==============================================================================
8. X11 selection mechanism *x11-selection*
If using X11, in either the GUI or an xterm with an X11-aware Vim, then Vim
provides varied access to the X11 selection and clipboard. These are accessed
by using the two selection registers "* and "+.
X11 provides two basic types of global store, selections and cut-buffers,
which differ in one important aspect: selections are "owned" by an
application, and disappear when that application (e.g., Vim) exits, thus
losing the data, whereas cut-buffers, are stored within the X-server itself
and remain until written over or the X-server exits (e.g., upon logging out).
The contents of selections are held by the originating application (e.g., upon
a copy), and only passed on to another application when that other application
asks for them (e.g., upon a paste).
The contents of cut-buffers are immediately written to, and are then
accessible directly from the X-server, without contacting the originating
application.
*quoteplus* *quote+*
There are three documented X selections: PRIMARY (which is expected to
represent the current visual selection - as in Vim's Visual mode), SECONDARY
(which is ill-defined) and CLIPBOARD (which is expected to be used for
cut, copy and paste operations).
Of these three, Vim uses PRIMARY when reading and writing the "* register
(hence when the X11 selections are available, Vim sets a default value for
|'clipboard'| of "autoselect"), and CLIPBOARD when reading and writing the "+
register. Vim does not access the SECONDARY selection.
Examples: (assuming the default option values)
- Select an URL in Visual mode in Vim. Go to a text field in Netscape and
click the middle mouse button. The selected text will be inserted
(hopefully!).
- Select some text in Netscape by dragging with the mouse. Go to Vim and
press the middle mouse button: The selected text is inserted.
- Select some text in Vim and do "+y. Go to Netscape, select some text in a
textfield by dragging with the mouse. Now use the right mouse button and
select "Paste" from the popup menu. The selected text is overwritten by the
text from Vim.
Note that the text in the "+ register remains available when making a Visual
selection, which makes other text available in the "* register. That allows
overwriting selected text.
*x11-cut-buffer*
There are, by default, 8 cut-buffers: CUT_BUFFER0 to CUT_BUFFER7. Vim only
uses CUT_BUFFER0, which is the one that xterm uses by default.
Whenever Vim is about to become unavailable (either via exiting or becoming
suspended), and thus unable to respond to another application's selection
request, it writes the contents of any owned selection to CUT_BUFFER0. If the
"+ CLIPBOARD selection is owned by Vim, then this is written in preference,
otherwise if the "* PRIMARY selection is owned by Vim, then that is written.
Similarly, when Vim tries to paste from "* or "+ (either explicitly, or, in
the case of the "* register, when the middle mouse button is clicked), if the
requested X selection is empty or unavailable, Vim reverts to reading the
current value of the CUT_BUFFER0.
Note that when text is copied to CUT_BUFFER0 in this way, the type of
selection (character, line or block) is always lost, even if it is a Vim which
later pastes it.
Xterm, by default, always writes visible selections to both PRIMARY and
CUT_BUFFER0. When it pastes, it uses PRIMARY if this is available, or else
falls back upon CUT_BUFFER0. For this reason, when cutting and pasting
between Vim and an xterm, you should use the "* register. Xterm doesn't use
CLIPBOARD, thus the "+ doesn't work with xterm.
Most newer applications will provide their current selection via PRIMARY ("*)
and use CLIPBOARD ("+) for cut/copy/paste operations. You thus have access to
both by choosing to use either of the "* or "+ registers.
vim:tw=78:sw=4:ts=8:ft=help:norl:

101
runtime/doc/hangulin.txt Normal file
View File

@@ -0,0 +1,101 @@
*hangulin.txt* For Vim version 7.0aa. Last change: 2001 Sep 03
VIM REFERENCE MANUAL by Chi-Deok Hwang and Sung-Hyun Nam
Introduction *hangul*
------------
It is to input hangul, the Korean language, with VIM GUI version.
If you have a XIM program, you can use another |+xim| feature.
Basically, it is for whom has no XIM program.
Compile
-------
Next is a basic option. You can add any other configure option. >
./configure --with-x --enable-multibyte --enable-fontset --enable-hangulinput
And you should check the feature.h. If |+hangul_input| feature is enabled
by configure, you can select more options such as keyboard type, 2 bulsik
or 3 bulsik. You can find keywords like next in there. >
#define HANGUL_DEFAULT_KEYBOARD 2
#define ESC_CHG_TO_ENG_MODE
/* #define X_LOCALE */
/* #define SLOW_XSERVER */
Environment variables
---------------------
You should set LANG variable to Korean locale such as ko or ko_KR.euc.
If you set LC_ALL variable, it should be set to Korean locale also.
VIM resource
------------
You should add nexts to your global vimrc ($HOME/.vimrc). >
:set fileencoding=korea
Keyboard
--------
You can change keyboard type (2 bulsik or 3 bulsik) using VIM_KEYBOARD
or HANGUL_KEYBOARD_TYPE environment variables. For sh, just do (2 bulsik): >
export VIM_KEYBOARD="2"
or >
export HANGUL_KEYBOARD_TYPE="2"
If both are set, VIM_KEYBOARD has higher priority.
Hangul Fonts
------------
You can set text font using $HOME/.Xdefaults or $HOME/.gvimrc.
But to use Hangul, you should set 'guifontset' in your vimrc.
$HOME/.Xdefaults: >
Vim.font: english_font
! Nexts are for hangul menu with Athena
*international: True
Vim*fontSet: english_font,hangul_font
! Nexts are for hangul menu with Motif
*international: True
Vim*fontList: english_font;hangul_font:
$HOME/.gvimrc: >
set guifontset=english_font,hangul_font
attention! the , (comma) or ; (semicolon)
And there should be no ':set guifont'. If it exists, then Gvim ignores
':set guifontset'. It means VIM runs without fontset supporting.
So, you can see only English. Hangul does not be correctly displayed.
After 'fontset' feature is enabled, VIM does not allow using 'font'.
For example, if you use >
:set guifontset=eng_font,your_font
in your .gvimrc, then you should do for syntax >
:hi Comment guifg=Cyan font=another_eng_font,another_your_font
If you just do >
:hi Comment font=another_eng_font
then you can see a GOOD error message. Be careful!
hangul_font width should be twice than english_font width.
Unsupported Feature
-------------------
Johab font not yet supported. And I don't have any plan.
If you really want to use johab font, you can use the
hanguldraw.c in gau package.
Hanja input not yet supported. And I don't have any plan.
If you really want to input hanja, just use VIM with hanterm.
Bug or Comment
--------------
Send comments, patches and suggestions to:
Chi-Deok Hwang <hwang@mizi.co.kr>
Nam SungHyun <namsh@lge.com>
vim:tw=78:ts=8:ft=help:norl:

145
runtime/doc/hebrew.txt Normal file
View File

@@ -0,0 +1,145 @@
*hebrew.txt* For Vim version 7.0aa. Last change: 2003 May 11
VIM REFERENCE MANUAL by Ron Aaron (and Avner Lottem)
Hebrew Language support (options & mapping) for Vim *hebrew*
The supporting 'rightleft' functionality was originally created by Avner
Lottem:
E-mail: alottem@iil.intel.com
Phone: +972-4-8307322
Ron Aaron <ron@ronware.org> is currently helping support these features.
{Vi does not have any of these commands}
All this is only available when the |+rightleft| feature was enabled at
compile time.
Introduction
------------
Hebrew-specific options are 'hkmap', 'hkmapp' 'keymap'=hebrew and 'aleph'.
Hebrew-useful options are 'delcombine', 'allowrevins', 'revins', 'rightleft'
and 'rightleftcmd'.
The 'rightleft' mode reverses the display order, so characters are displayed
from right to left instead of the usual left to right. This is useful
primarily when editing Hebrew or other Middle-Eastern languages.
See |rileft.txt| for further details.
Details
--------------
+ Options:
+ 'rightleft' ('rl') sets window orientation to right-to-left. This means
that the logical text 'ABC' will be displayed as 'CBA', and will start
drawing at the right edge of the window, not the left edge.
+ 'hkmap' ('hk') sets keyboard mapping to Hebrew, in insert/replace modes.
+ 'aleph' ('al'), numeric, holds the decimal code of Aleph, for keyboard
mapping.
+ 'hkmapp' ('hkp') sets keyboard mapping to 'phonetic hebrew'
NOTE: these three ('hkmap', 'hkmapp' and 'aleph') are obsolete. You should
use ":set keymap=hebrewp" instead.
+ 'delcombine' ('deco'), boolean, if editing UTF-8 encoded Hebrew, allows
one to remove the niqud or te`amim by pressing 'x' on a character (with
associated niqud).
+ 'rightleftcmd' ('rlc') makes the command-prompt for searches show up on
the right side. It only takes effect if the window is 'rightleft'.
+ Encoding:
+ Under Unix, ISO 8859-8 encoding (Hebrew letters codes: 224-250).
+ Under MS DOS, PC encoding (Hebrew letters codes: 128-154).
These are defaults, that can be overridden using the 'aleph' option.
+ You should prefer using UTF8, as it supports the combining-characters
('deco' does nothing if UTF8 encoding is not active).
+ Vim arguments:
+ 'vim -H file' starts editing a Hebrew file, i.e. 'rightleft' and 'hkmap'
are set.
+ Keyboard:
+ The 'allowrevins' option enables the CTRL-_ command in Insert mode and
in Command-line mode.
+ CTRL-_ in insert/replace modes toggles 'revins' and 'hkmap' as follows:
When in rightleft window, 'revins' and 'nohkmap' are toggled, since
English will likely be inserted in this case.
When in norightleft window, 'revins' 'hkmap' are toggled, since Hebrew
will likely be inserted in this case.
CTRL-_ moves the cursor to the end of the typed text.
+ CTRL-_ in command mode only toggles keyboard mapping (see Bugs below).
This setting is independent of 'hkmap' option, which only applies to
insert/replace mode.
Note: On some keyboards, CTRL-_ is mapped to CTRL-?.
+ Keyboard mapping while 'hkmap' is set (standard Israeli keyboard):
q w e r t y u i o p
/ ' ק ר א ט ו ן ם פ
a s d f g h j k l ; '
ש ד ג כ ע י ח ל ך ף ,
z x c v b n m , . /
ז ס ב ה נ מ צ ת ץ .
This is also the keymap when 'keymap=hebrew' is set. The advantage of
'keymap' is that it works properly when using UTF8, e.g. it inserts the
correct characters; 'hkmap' does not. The 'keymap' keyboard can also
insert niqud and te`amim. To see what those mappings are,look at the
keymap file 'hebrew.vim' etc.
Typing backwards
If the 'revins' (reverse insert) option is set, inserting happens backwards.
This can be used to type Hebrew. When inserting characters the cursor is not
moved and the text moves rightwards. A <BS> deletes the character under the
cursor. CTRL-W and CTRL-U also work in the opposite direction. <BS>, CTRL-W
and CTRL-U do not stop at the start of insert or end of line, no matter how
the 'backspace' option is set.
There is no reverse replace mode (yet).
If the 'showmode' option is set, "-- REVERSE INSERT --" will be shown in the
status line when reverse Insert mode is active.
When the 'allowrevins' option is set, reverse Insert mode can be also entered
via CTRL-_, which has some extra functionality: First, keyboard mapping is
changed according to the window orientation -- if in a left-to-right window,
'revins' is used to enter Hebrew text, so the keyboard changes to Hebrew
('hkmap' is set); if in a right-to-left window, 'revins' is used to enter
English text, so the keyboard changes to English ('hkmap' is reset). Second,
when exiting 'revins' via CTRL-_, the cursor moves to the end of the typed
text (if possible).
Pasting when in a rightleft window
----------------------------------
When cutting text with the mouse and pasting it in a rightleft window
the text will be reversed, because the characters come from the cut buffer
from the left to the right, while inserted in the file from the right to
the left. In order to avoid it, toggle 'revins' (by typing CTRL-? or CTRL-_)
before pasting.
Hebrew characters and the 'isprint' variable
--------------------------------------------
Sometimes Hebrew character codes are in the non-printable range defined by
the 'isprint' variable. For example in the Linux console, the Hebrew font
encoding starts from 128, while the default 'isprint' variable is @,161-255.
The result is that all Hebrew characters are displayed as ~x. To solve this
problem, set isprint=@,128-255.
vim:tw=78:ts=8:ft=help:norl:

197
runtime/doc/help.txt Normal file
View File

@@ -0,0 +1,197 @@
*help.txt* For Vim version 7.0aa. Last change: 2004 May 04
VIM - main help file
k
Move around: Use the cursor keys, or "h" to go left, h l
"j" to go down, "k" to go up, "l" to go right. j
Close this window: Use ":q<Enter>".
Get out of Vim: Use ":qa!<Enter>" (careful, all changes are lost!).
Jump to a subject: Position the cursor on a tag between |bars| and hit CTRL-].
With the mouse: ":set mouse=a" to enable the mouse (in xterm or GUI).
Double-click the left mouse button on a tag between |bars|.
Jump back: Type CTRL-T or CTRL-O (repeat to go further back).
Get specific help: It is possible to go directly to whatever you want help
on, by giving an argument to the ":help" command |:help|.
It is possible to further specify the context:
*help-context*
WHAT PREPEND EXAMPLE ~
Normal mode commands (nothing) :help x
Visual mode commands v_ :help v_u
Insert mode commands i_ :help i_<Esc>
Command-line commands : :help :quit
Command-line editing c_ :help c_<Del>
Vim command arguments - :help -r
Options ' :help 'textwidth'
Search for help: Type ":help word", then hit CTRL-D to see matching
help entries for "word".
VIM stands for Vi IMproved. Most of VIM was made by Bram Moolenaar, but only
through the help of many others. See |credits|.
------------------------------------------------------------------------------
*doc-file-list* *Q_ct*
BASIC:
|quickref| Overview of the most common commands you will use
|tutor| 30 minutes training course for beginners
|copying| About copyrights
|iccf| Helping poor children in Uganda
|sponsor| Sponsor Vim development, become a registered Vim user
|www| Vim on the World Wide Web
|bugs| Where to send bug reports
USER MANUAL: These files explain how to accomplish an editing task.
|usr_toc.txt| Table Of Contents
Getting Started ~
|usr_01.txt| About the manuals
|usr_02.txt| The first steps in Vim
|usr_03.txt| Moving around
|usr_04.txt| Making small changes
|usr_05.txt| Set your settings
|usr_06.txt| Using syntax highlighting
|usr_07.txt| Editing more than one file
|usr_08.txt| Splitting windows
|usr_09.txt| Using the GUI
|usr_10.txt| Making big changes
|usr_11.txt| Recovering from a crash
|usr_12.txt| Clever tricks
Editing Effectively ~
|usr_20.txt| Typing command-line commands quickly
|usr_21.txt| Go away and come back
|usr_22.txt| Finding the file to edit
|usr_23.txt| Editing other files
|usr_24.txt| Inserting quickly
|usr_25.txt| Editing formatted text
|usr_26.txt| Repeating
|usr_27.txt| Search commands and patterns
|usr_28.txt| Folding
|usr_29.txt| Moving through programs
|usr_30.txt| Editing programs
|usr_31.txt| Exploiting the GUI
Tuning Vim ~
|usr_40.txt| Make new commands
|usr_41.txt| Write a Vim script
|usr_42.txt| Add new menus
|usr_43.txt| Using filetypes
|usr_44.txt| Your own syntax highlighted
|usr_45.txt| Select your language
Making Vim Run ~
|usr_90.txt| Installing Vim
REFERENCE MANUAL: These files explain every detail of Vim.
General subjects ~
|intro.txt| general introduction to Vim; notation used in help files
|help.txt| overview and quick reference (this file)
|index.txt| alphabetical index of all commands
|help-tags| all the tags you can jump to (index of tags)
|howto.txt| how to do the most common editing tasks
|tips.txt| various tips on using Vim
|message.txt| (error) messages and explanations
|quotes.txt| remarks from users of Vim
|todo.txt| known problems and desired extensions
|develop.txt| development of Vim
|uganda.txt| Vim distribution conditions and what to do with your money
Basic editing ~
|starting.txt| starting Vim, Vim command arguments, initialisation
|editing.txt| editing and writing files
|motion.txt| commands for moving around
|scroll.txt| scrolling the text in the window
|insert.txt| Insert and Replace mode
|change.txt| deleting and replacing text
|indent.txt| automatic indenting for C and other languages
|undo.txt| Undo and Redo
|repeat.txt| repeating commands, Vim scripts and debugging
|visual.txt| using the Visual mode (selecting a text area)
|various.txt| various remaining commands
|recover.txt| recovering from a crash
Advanced editing ~
|cmdline.txt| Command-line editing
|options.txt| description of all options
|pattern.txt| regexp patterns and search commands
|map.txt| key mapping and abbreviations
|tagsrch.txt| tags and special searches
|quickfix.txt| commands for a quick edit-compile-fix cycle
|windows.txt| commands for using multiple windows and buffers
|syntax.txt| syntax highlighting
|diff.txt| working with two or three versions of the same file
|autocmd.txt| automatically executing commands on an event
|filetype.txt| settings done specifically for a type of file
|eval.txt| expression evaluation, conditional commands
|fold.txt| hide (fold) ranges of lines
Special issues ~
|remote.txt| using Vim as a server or client
|term.txt| using different terminals and mice
|digraph.txt| list of available digraphs
|mbyte.txt| multi-byte text support
|mlang.txt| non-English language support
|arabic.txt| Arabic language support and editing
|farsi.txt| Farsi (Persian) editing
|hebrew.txt| Hebrew language support and editing
|russian.txt| Russian language support and editing
|hangulin.txt| Hangul (Korean) input mode
|rileft.txt| right-to-left editing mode
GUI ~
|gui.txt| Graphical User Interface (GUI)
|gui_w16.txt| Windows 3.1 GUI
|gui_w32.txt| Win32 GUI
|gui_x11.txt| X11 GUI
Interfaces ~
|if_cscop.txt| using cscope with Vim
|if_perl.txt| Perl interface
|if_pyth.txt| Python interface
|if_sniff.txt| SNiFF+ interface
|if_tcl.txt| Tcl interface
|if_ole.txt| OLE automation interface for Win32
|if_ruby.txt| Ruby interface
|debugger.txt| Interface with a debugger
|workshop.txt| Sun Visual Workshop interface
|netbeans.txt| NetBeans External Editor interface
|sign.txt| debugging signs
Versions ~
|vi_diff.txt| Main differences between Vim and Vi
|version4.txt| Differences between Vim version 3.0 and 4.x
|version5.txt| Differences between Vim version 4.6 and 5.x
|version6.txt| Differences between Vim version 5.7 and 6.x
*sys-file-list*
Remarks about specific systems ~
|os_390.txt| OS/390 Unix
|os_amiga.txt| Amiga
|os_beos.txt| BeOS and BeBox
|os_dos.txt| MS-DOS and MS-Windows NT/95 common items
|os_mac.txt| Macintosh
|os_mint.txt| Atari MiNT
|os_msdos.txt| MS-DOS (plain DOS and DOS box under Windows)
|os_os2.txt| OS/2
|os_qnx.txt| QNX
|os_risc.txt| RISC-OS
|os_unix.txt| Unix
|os_vms.txt| VMS
|os_win32.txt| MS-Windows 95/98/NT
*standard-plugin-list*
Standard plugins ~
|pi_netrw.txt| Reading and writing files over a network
|pi_gzip.txt| Reading and writing compressed files
|pi_expl.txt| File explorer
LOCAL ADDITIONS: *local-additions*
------------------------------------------------------------------------------
*bars* Bars example
Now that you've jumped here with CTRL-] or a double mouse click, you can use
CTRL-T, CTRL-O, g<RightMouse>, or <C-RightMouse> to go back to where you were.
------------------------------------------------------------------------------
vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=help:norl:

BIN
runtime/doc/help.txt.info Executable file
View File

Binary file not shown.

96
runtime/doc/howto.txt Normal file
View File

@@ -0,0 +1,96 @@
*howto.txt* For Vim version 7.0aa. Last change: 2001 Sep 03
VIM REFERENCE MANUAL by Bram Moolenaar
How to ... *howdoi* *how-do-i* *howto* *how-to*
|tutor| get started
|:quit| exit? I'm trapped, help me!
|initialization| initialize Vim
|vimrc-intro| write a Vim script file (vimrc)
|suspend| suspend Vim
|usr_11.txt| recover after a crash
|07.4| keep a backup of my file when writing over it
|usr_07.txt| edit files
|23.4| edit binary files
|usr_24.txt| insert text
|deleting| delete text
|usr_04.txt| change text
|04.5| copy and move text
|usr_25.txt| format text
|30.6| format comments
|30.2| indent C programs
|25.3| automatically set indent
|usr_26.txt| repeat commands
|02.5| undo and redo
|usr_03.txt| move around
|word-motions| word motions
|left-right-motions| left-right motions
|up-down-motions| up-down motions
|object-motions| text-object motions
|various-motions| various motions
|object-select| text-object selection
|'whichwrap'| move over line breaks
|'virtualedit'| move to where there is no text
|usr_27.txt| specify pattern for searches
|tags-and-searches| do tags and special searches
|29.4| search in include'd files used to find
variables, functions, or macros
|K| look up manual for the keyword under cursor
|03.7| scroll
|'sidescroll'| scroll horizontally/sideways
|'scrolloff'| set visible context lines
|mode-switching| change modes
|04.4| use Visual mode
|'insertmode'| start Vim in Insert mode
|40.1| map keys
|24.7| create abbreviations
|ins-expandtab| expand a tab to spaces in Insert mode
|i_CTRL-R| insert contents of a register in Insert mode
|24.3| complete words in Insert mode
|25.1| break a line before it gets too long
|20.1| do command-line editing
|20.3| do command-line completion
|'cmdheight'| increase the height of command-line
|10.3| specify command-line ranges
|40.3| specify commands to be executed automatically
before/after reading/writing entering/leaving a
buffer/window
|'autowrite'| write automatically
|30.1| speedup edit-compile-edit cycle or compile and fix
errors within Vim
|options| set options
|auto-setting| set options automatically
|term-dependent-settings| set options depending on terminal name
|save-settings| save settings
|:quote| comment my exrc/vimrc/gvimrc files
|'helpheight'| change the default help height
|'highlight'| set various highlighting modes
|'title'| set the window title
|'icon'| set window icon title
|'report'| avoid seeing the change messages on every line
|'shortmess'| avoid |hit-enter| prompts
|mouse-using| use mouse with Vim
|usr_08.txt| manage multiple windows and buffers
|gui.txt| use the gui
|You can't! (yet)| do dishes using Vim
|usr_06.txt| switch on syntax highlighting
|2html.vim| convert a colored file to HTML
|less| use Vim like less or more with syntax highlighting
vim:tw=78:ts=8:ft=help:norl:

474
runtime/doc/if_cscop.txt Normal file
View File

@@ -0,0 +1,474 @@
*if_cscop.txt* For Vim version 7.0aa. Last change: 2004 Jan 17
VIM REFERENCE MANUAL by Andy Kahn
*cscope* *Cscope*
This document explains how to use Vim's cscope interface.
Cscope is a tool like ctags, but think of it as ctags on steroids since it
does a lot more than what ctags provides. In Vim, jumping to a result from
a cscope query is just like jumping to any tag; it is saved on the tag stack
so that with the right keyboard mappings, you can jump back and forth between
functions as you normally would with |tags|.
1. Cscope introduction |cscope-intro|
2. Cscope related commands |cscope-commands|
3. Cscope options |cscope-options|
4. How to use cscope in Vim |cscope-howtouse|
5. Limitations |cscope-limitations|
6. Suggested usage |cscope-suggestions|
7. Availability & Information |cscope-info|
This is currently for Unix and Win32 only.
{Vi does not have any of these commands}
==============================================================================
1. Cscope introduction *cscope-intro*
The following text is taken from a version of the cscope man page:
-----
Cscope is an interactive screen-oriented tool that helps you:
Learn how a C program works without endless flipping through a thick
listing.
Locate the section of code to change to fix a bug without having to
learn the entire program.
Examine the effect of a proposed change such as adding a value to an
enum variable.
Verify that a change has been made in all source files such as adding
an argument to an existing function.
Rename a global variable in all source files.
Change a constant to a preprocessor symbol in selected lines of files.
It is designed to answer questions like:
Where is this symbol used?
Where is it defined?
Where did this variable get its value?
What is this global symbol's definition?
Where is this function in the source files?
What functions call this function?
What functions are called by this function?
Where does the message "out of space" come from?
Where is this source file in the directory structure?
What files include this header file?
Cscope answers these questions from a symbol database that it builds the
first time it is used on the source files. On a subsequent call, cscope
rebuilds the database only if a source file has changed or the list of
source files is different. When the database is rebuilt the data for the
unchanged files is copied from the old database, which makes rebuilding
much faster than the initial build.
-----
When cscope is normally invoked, you will get a full-screen selection
screen allowing you to make a query for one of the above questions.
However, once a match is found to your query and you have entered your
text editor to edit the source file containing match, you cannot simply
jump from tag to tag as you normally would with vi's Ctrl-] or :tag
command.
Vim's cscope interface is done by invoking cscope with its line-oriented
interface, and then parsing the output returned from a query. The end
result is that cscope query results become just like regular tags, so
you can jump to them just like you do with normal tags (Ctrl-] or :tag)
and then go back by popping off the tagstack with Ctrl-T. (Please note
however, that you don't actually jump to a cscope tag simply by doing
Ctrl-] or :tag without remapping these commands or setting an option.
See the remaining sections on how the cscope interface works and for
suggested use.)
==============================================================================
2. Cscope related commands *cscope-commands*
*:cscope* *:cs* *:scs* *:scscope* *E259* *E262* *E561* *E560*
All cscope commands are accessed through suboptions to the main cscope
command ":cscope". The shortest abbreviation is ":cs". The ":scscope"
command does the same and also splits the window (short: "scs").
The available subcommands are:
*E563* *E564* *E566* *E568* *E569* *E622* *E623*
*E625* *E626* *E609*
add : Add a new cscope database/connection.
USAGE :cs add {file|dir} [pre-path] [flags]
[pre-path] is the pathname used with the -P command to cscope.
[flags] are any additional flags you want to pass to cscope.
EXAMPLES >
:cscope add /usr/local/cdb/cscope.out
:cscope add /projects/vim/cscope.out /usr/local/vim
:cscope add cscope.out /usr/local/vim -C
<
*cscope-find* *cs-find*
*E565* *E567*
find : Query cscope. All cscope query options are available
except option #5 ("Change this grep pattern").
USAGE :cs find {querytype} {name}
{querytype} corresponds to the actual cscope line
interface numbers as well as default nvi commands:
0 or s: Find this C symbol
1 or g: Find this definition
2 or d: Find functions called by this function
3 or c: Find functions calling this function
4 or t: Find this text string
6 or e: Find this egrep pattern
7 or f: Find this file
8 or i: Find files #including this file
EXAMPLES >
:cscope find c vim_free
:cscope find 3 vim_free
<
These two examples perform the same query. >
:cscope find 0 DEFAULT_TERM
<
Executing this example on the source code for Vim 5.1 produces the
following output:
Cscope tag: DEFAULT_TERM
# line filename / context / line
1 1009 vim-5.1-gtk/src/term.c <<GLOBAL>>
#define DEFAULT_TERM (char_u *)"amiga"
2 1013 vim-5.1-gtk/src/term.c <<GLOBAL>>
#define DEFAULT_TERM (char_u *)"win32"
3 1017 vim-5.1-gtk/src/term.c <<GLOBAL>>
#define DEFAULT_TERM (char_u *)"pcterm"
4 1021 vim-5.1-gtk/src/term.c <<GLOBAL>>
#define DEFAULT_TERM (char_u *)"ansi"
5 1025 vim-5.1-gtk/src/term.c <<GLOBAL>>
#define DEFAULT_TERM (char_u *)"vt52"
6 1029 vim-5.1-gtk/src/term.c <<GLOBAL>>
#define DEFAULT_TERM (char_u *)"os2ansi"
7 1033 vim-5.1-gtk/src/term.c <<GLOBAL>>
#define DEFAULT_TERM (char_u *)"ansi"
8 1037 vim-5.1-gtk/src/term.c <<GLOBAL>>
# undef DEFAULT_TERM
9 1038 vim-5.1-gtk/src/term.c <<GLOBAL>>
#define DEFAULT_TERM (char_u *)"beos-ansi"
10 1042 vim-5.1-gtk/src/term.c <<GLOBAL>>
#define DEFAULT_TERM (char_u *)"mac-ansi"
11 1335 vim-5.1-gtk/src/term.c <<set_termname>>
term = DEFAULT_TERM;
12 1459 vim-5.1-gtk/src/term.c <<set_termname>>
if (STRCMP(term, DEFAULT_TERM))
13 1826 vim-5.1-gtk/src/term.c <<termcapinit>>
term = DEFAULT_TERM;
14 1833 vim-5.1-gtk/src/term.c <<termcapinit>>
term = DEFAULT_TERM;
15 3635 vim-5.1-gtk/src/term.c <<update_tcap>>
p = find_builtin_term(DEFAULT_TERM);
Enter nr of choice (<CR> to abort):
The output shows several pieces of information:
1. The tag number (there are 15 in this example).
2. The line number where the tag occurs.
3. The filename where the tag occurs.
4. The context of the tag (e.g., global, or the function name).
5. The line from the file itself.
help : Show a brief synopsis.
USAGE :cs help
*E260* *E261*
kill : Kill a cscope connection (or kill all cscope connections).
USAGE :cs kill {num|partial_name}
To kill a cscope connection, the connection number or a partial
name must be specified. The partial name is simply any part of
the pathname of the cscope database. Kill a cscope connection
using the partial name with caution!
If the specified connection number is -1, then _ALL_ cscope
connections will be killed.
reset : Reinit all cscope connections.
USAGE :cs reset
show : Show cscope connections.
USAGE :cs show
*:cstag* *E257* *E562*
If you use cscope as well as ctags, |:cstag| allows you to search one or
the other before making a jump. For example, you can choose to first
search your cscope database(s) for a match, and if one is not found, then
your tags file(s) will be searched. The order in which this happens
is determined by the value of |csto|. See |cscope-options| for more
details.
|:cstag| performs the equivalent of ":cs find g" on the identifier when
searching through the cscope database(s).
|:cstag| performs the equivalent of |:tjump| on the identifier when searching
through your tags file(s).
==============================================================================
3. Cscope options *cscope-options*
Use the |:set| command to set all cscope options. Ideally, you would do
this in one of your startup files (e.g., .vimrc). Some cscope related
variables are only valid within |.vimrc|. Setting them after vim has
started will have no effect!
*cscopeprg* *csprg*
'cscopeprg' specifies the command to execute cscope. The default is
"cscope". For example: >
:set csprg=/usr/local/bin/cscope
<
*cscopequickfix* *csqf* *E469*
{not available when compiled without the |+quickfix| feature}
'cscopequickfix' specifies whether to use quickfix window to show cscope
results. This is a list of comma-separated values. Each item consists of
|cscope-find| command (s, g, d, c, t, e, f or i) and flag (+, - or 0).
'+' indicates that results must be appended to quickfix window,
'-' implies previous results clearance, '0' or command absence - don't use
quickfix. Search is performed from start until first command occurrence.
The default value is "" (don't use quickfix anyway). The following value
seems to be useful: "s-,c-,d-,i-,t-,e-".
*cscopetag* *cst*
If 'cscopetag' set, the commands ":tag" and CTRL-] as well as "vim -t" will
always use |:cstag| instead of the default :tag behavior. Effectively, by
setting 'cst', you will always search your cscope databases as well as your
tag files. The default is off. Examples: >
:set cst
:set nocst
<
*cscopetagorder* *csto*
The value of 'csto' determines the order in which |:cstag| performs a search.
If 'csto' is set to zero, cscope database(s) are searched first, followed
by tag file(s) if cscope did not return any matches. If 'csto' is set to
one, tag file(s) are searched before cscope database(s). The default is zero.
Examples: >
:set csto=0
:set csto=1
<
*cscopeverbose* *csverb*
If 'cscopeverbose' is not set (the default), messages will not be printed
indicating success or failure when adding a cscope database. Ideally, you
should reset this option in your |.vimrc| before adding any cscope databases,
and after adding them, set it. From then on, when you add more databases
within Vim, you will get a (hopefully) useful message should the database fail
to be added. Examples: >
:set csverb
:set nocsverb
<
*cscopepathcomp* *cspc*
The value of 'cspc' determines how many components of a file's path to
display. With the default value of zero the entire path will be displayed.
The value one will display only the filename with no path. Other values
display that many components. For example: >
:set cspc=3
will display the last 3 components of the file's path, including the file
name itself.
==============================================================================
4. How to use cscope in Vim *cscope-howtouse*
The first thing you need to do is to build a cscope database for your
source files. For the most basic case, simply do "cscope -b". Please
refer to the cscope man page for more details.
Assuming you have a cscope database, you need to "add" the database to Vim.
This establishes a cscope "connection" and makes it available for Vim to use.
You can do this in your .vimrc file, or you can do it manually after starting
vim. For example, to add the cscope database "cscope.out", you would do:
:cs add cscope.out
You can double-check the result of this by executing ":cs show". This will
produce output which looks like this:
# pid database name prepend path
0 28806 cscope.out <none>
Note:
Because of the Microsoft RTL limitations, Win32 version shows 0 instead
of the real pid.
Once a cscope connection is established, you can make queries to cscope and
the results will be printed to you. Queries are made using the command
":cs find". For example:
:cs find g ALIGN_SIZE
This can get a little cumbersome since one ends up doing a significant
amount of typing. Fortunately, there are ways around this by mapping
shortcut keys. See |cscope-suggestions| for suggested usage.
If the results return only one match, you will automatically be taken to it.
If there is more than one match, you will be given a selection screen to pick
the match you want to go to. After you have jumped to the new location,
simply hit Ctrl-T to get back to the previous one.
==============================================================================
5. Limitations *cscope-limitations*
Cscope support for Vim is only available on systems that support these four
system calls: fork(), pipe(), execl(), waitpid(). This means it is mostly
limited to Unix systems.
Additionally Cscope support works for Win32. For more information and a
cscope version for Win32 see:
http://iamphet.nm.ru/cscope/index.html
There are a couple of hard-coded limitations:
1. The maximum number of cscope connections allowed is 8. Do you
really need more?
2. Doing a |:tjump| when |:cstag| searches the tag files is not
configurable (e.g., you can't do a tselect instead).
==============================================================================
6. Suggested usage *cscope-suggestions*
Put these entries in your .vimrc (adjust the pathname accordingly to your
setup): >
if has("cscope")
set csprg=/usr/local/bin/cscope
set csto=0
set cst
set nocsverb
" add any database in current directory
if filereadable("cscope.out")
cs add cscope.out
" else add database pointed to by environment
elseif $CSCOPE_DB != ""
cs add $CSCOPE_DB
endif
set csverb
endif
By setting 'cscopetag', we have effectively replaced all instances of the :tag
command with :cstag. This includes :tag, Ctrl-], and "vim -t". In doing
this, the regular tag command not only searches your ctags generated tag
files, but your cscope databases as well.
Some users may want to keep the regular tag behavior and have a different
shortcut to access :cstag. For example, one could map Ctrl-_ (underscore)
to :cstag with the following command: >
map <C-_> :cstag <C-R>=expand("<cword>")<CR><CR>
A couple of very commonly used cscope queries (using ":cs find") is to
find all functions calling a certain function and to find all occurrences
of a particular C symbol. To do this, you can use these mappings as an
example: >
map g<C-]> :cs find 3 <C-R>=expand("<cword>")<CR><CR>
map g<C-\> :cs find 0 <C-R>=expand("<cword>")<CR><CR>
These mappings for Ctrl-] (right bracket) and Ctrl-\ (backslash) allow you to
place your cursor over the function name or C symbol and quickly query cscope
for any matches.
Or you may use the following scheme, inspired by Vim/Cscope tutorial from
Cscope Home Page (http://cscope.sourceforge.net/): >
nmap <C-_>s :cs find s <C-R>=expand("<cword>")<CR><CR>
nmap <C-_>g :cs find g <C-R>=expand("<cword>")<CR><CR>
nmap <C-_>c :cs find c <C-R>=expand("<cword>")<CR><CR>
nmap <C-_>t :cs find t <C-R>=expand("<cword>")<CR><CR>
nmap <C-_>e :cs find e <C-R>=expand("<cword>")<CR><CR>
nmap <C-_>f :cs find f <C-R>=expand("<cfile>")<CR><CR>
nmap <C-_>i :cs find i ^<C-R>=expand("<cfile>")<CR>$<CR>
nmap <C-_>d :cs find d <C-R>=expand("<cword>")<CR><CR>
" Using 'CTRL-spacebar' then a search type makes the vim window
" split horizontally, with search result displayed in
" the new window.
nmap <C-Space>s :scs find s <C-R>=expand("<cword>")<CR><CR>
nmap <C-Space>g :scs find g <C-R>=expand("<cword>")<CR><CR>
nmap <C-Space>c :scs find c <C-R>=expand("<cword>")<CR><CR>
nmap <C-Space>t :scs find t <C-R>=expand("<cword>")<CR><CR>
nmap <C-Space>e :scs find e <C-R>=expand("<cword>")<CR><CR>
nmap <C-Space>f :scs find f <C-R>=expand("<cfile>")<CR><CR>
nmap <C-Space>i :scs find i ^<C-R>=expand("<cfile>")<CR>$<CR>
nmap <C-Space>d :scs find d <C-R>=expand("<cword>")<CR><CR>
" Hitting CTRL-space *twice* before the search type does a vertical
" split instead of a horizontal one
nmap <C-Space><C-Space>s
\:vert scs find s <C-R>=expand("<cword>")<CR><CR>
nmap <C-Space><C-Space>g
\:vert scs find g <C-R>=expand("<cword>")<CR><CR>
nmap <C-Space><C-Space>c
\:vert scs find c <C-R>=expand("<cword>")<CR><CR>
nmap <C-Space><C-Space>t
\:vert scs find t <C-R>=expand("<cword>")<CR><CR>
nmap <C-Space><C-Space>e
\:vert scs find e <C-R>=expand("<cword>")<CR><CR>
nmap <C-Space><C-Space>i
\:vert scs find i ^<C-R>=expand("<cfile>")<CR>$<CR>
nmap <C-Space><C-Space>d
\:vert scs find d <C-R>=expand("<cword>")<CR><CR>
==============================================================================
7. Cscope availability and information *cscope-info*
If you do not already have cscope (it did not come with your compiler
license or OS distribution), then you can download it for free from:
http://cscope.sourceforge.net/
This is released by SCO under the BSD license.
If you want a newer version of cscope, you will probably have to buy it.
According to the (old) nvi documentation:
You can buy version 13.3 source with an unrestricted license
for $400 from AT&T Software Solutions by calling +1-800-462-8146.
Also you can download cscope 13.x and mlcscope 14.x (multi-lingual cscope
which supports C, C++, Java, lex, yacc, breakpoint listing, Ingres, and SDL)
from World-Wide Exptools Open Source packages page:
http://www.bell-labs.com/project/wwexptools/packages.html
In Solaris 2.x, if you have the C compiler license, you will also have
cscope. Both are usually located under /opt/SUNWspro/bin
SGI developers can also get it. Search for Cscope on this page:
http://freeware.sgi.com/index-by-alpha.html
https://toolbox.sgi.com/toolbox/utilities/cscope/
The second one is for those who have a password for the SGI toolbox.
There is source to an older version of a cscope clone (called "cs") available
on the net. Due to various reasons, this is not supported with Vim.
The cscope interface/support for Vim was originally written by
Andy Kahn <ackahn@netapp.com>. The original structure (as well as a tiny
bit of code) was adapted from the cscope interface in nvi. Please report
any problems, suggestions, patches, et al., you have for the usage of
cscope within Vim to him.
*cscope-win32*
For a cscope version for Win32 see: http://iamphet.nm.ru/cscope/index.html
Win32 support was added by Sergey Khorev <khorev@softlab.ru>. Contact him
if you have Win32-specific issues.
vim:tw=78:ts=8:ft=help:norl:

162
runtime/doc/if_ole.txt Normal file
View File

@@ -0,0 +1,162 @@
*if_ole.txt* For Vim version 7.0aa. Last change: 2003 Jun 19
VIM REFERENCE MANUAL by Paul Moore
The OLE Interface to Vim *ole-interface*
1. Activation |ole-activation|
2. Methods |ole-methods|
3. The "normal" command |ole-normal|
4. Registration |ole-registration|
5. MS Visual Studio integration |MSVisualStudio|
{Vi does not have any of these commands}
OLE is only available when compiled with the |+ole| feature. See
src/if_ole.INSTALL.
An alternative is using the client-server communication |clientserver|.
==============================================================================
1. Activation *ole-activation*
Vim acts as an OLE automation server, accessible from any automation client,
for example, Visual Basic, Python, or Perl. The Vim application "name" (its
"ProgID", in OLE terminology) is "Vim.Application".
Hence, in order to start a Vim instance (or connect to an already running
instance), code similar to the following should be used:
[Visual Basic] >
Dim Vim As Object
Set Vim = CreateObject("Vim.Application")
[Python] >
from win32com.client.dynamic import Dispatch
vim = Dispatch('Vim.Application')
[Perl] >
use Win32::OLE;
$vim = new Win32::OLE 'Vim.Application';
Vim does not support acting as a "hidden" OLE server, like some other OLE
Automation servers. When a client starts up an instance of Vim, that instance
is immediately visible. Simply closing the OLE connection to the Vim instance
is not enough to shut down the Vim instance - it is necessary to explicitly
execute a quit command (for example, :qa!, :wqa).
==============================================================================
2. Methods *ole-methods*
Vim exposes four methods for use by clients.
*ole-sendkeys*
SendKeys(keys) Execute a series of keys.
This method takes a single parameter, which is a string of keystrokes. These
keystrokes are executed exactly as if they had been types in at the keyboard.
Special keys can be given using their <..> names, as for the right hand side
of a mapping. Note: Execution of the Ex "normal" command is not supported -
see below |ole-normal|.
Examples (Visual Basic syntax) >
Vim.SendKeys "ihello<Esc>"
Vim.SendKeys "ma1GV4jy`a"
These examples assume that Vim starts in Normal mode. To force Normal mode,
start the key sequence with CTRL-\ CTRL-N as in >
Vim.SendKeys "<C-\><C-N>ihello<Esc>"
CTRL-\ CTRL-N returns Vim to Normal mode, when in Insert or Command-line mode.
Note that this doesn't work halfway a Vim command
*ole-eval*
Eval(expr) Evaluate an expression.
This method takes a single parameter, which is an expression in Vim's normal
format (see |expression|). It returns a string, which is the result of
evaluating the expression.
Examples (Visual Basic syntax) >
Line20 = Vim.Eval("getline(20)")
Twelve = Vim.Eval("6 + 6") ' Note this is a STRING
Font = Vim.Eval("&guifont")
<
*ole-setforeground*
SetForeground() Make the Vim window come to the foreground
This method takes no arguments. No value is returned.
Example (Visual Basic syntax) >
Vim.SetForeground
<
*ole-gethwnd*
GetHwnd() Return the handle of the Vim window.
This method takes no arguments. It returns the hwnd of the main Vimwindow.
You can use this if you are writing something which needs to manipulate the
Vim window, or to track it in the z-order, etc.
Example (Visual Basic syntax) >
Vim_Hwnd = Vim.GetHwnd
<
==============================================================================
3. The "normal" command *ole-normal*
Due to the way Vim processes OLE Automation commands, combined with the method
of implementation of the ex command :normal, it is not possible to execute the
:normal command via OLE automation. Any attempt to do so will fail, probably
harmlessly, although possibly in unpredictable ways.
There is currently no practical way to trap this situation, and users must
simply be aware of the limitation.
==============================================================================
4. Registration *ole-registration* *E243*
Before Vim will act as an OLE server, it must be registered in the system
registry. In order to do this, Vim should be run with a single parameter of
"-register".
*-register* >
gvim -register
If gvim with OLE support is run and notices that no Vim OLE server has been
registered, it will present a dialog and offers you the choice to register by
clicking "Yes".
In some situations registering is not possible. This happens when the
registry is not writable. If you run into this problem you need to run gvim
as "Administrator".
Once vim is registered, the application path is stored in the registry. Before
moving, deleting, or upgrading Vim, the registry entries should be removed
using the "-unregister" switch.
*-unregister* >
gvim -unregister
The OLE mechanism will use the first registered Vim it finds. If a Vim is
already running, this one will be used. If you want to have (several) Vim
sessions open that should not react to OLE commands, use the non-OLE version,
and put it in a different directory. The OLE version should then be put in a
directory that is not in your normal path, so that typing "gvim" will start
the non-OLE version.
*-silent*
To avoid the message box that pops up to report the result, prepend "-silent":
>
gvim -silent -register
gvim -silent -unregister
==============================================================================
5. MS Visual Studio integration *MSVisualStudio* *VisVim*
The OLE version can be used to run Vim as the editor in Microsoft Visual
Studio. This is called "VisVim". It is included in the archive that contains
the OLE version. The documentation can be found in the runtime directory, the
README_VisVim.txt file.
==============================================================================
vim:tw=78:ts=8:ft=help:norl:

258
runtime/doc/if_perl.txt Normal file
View File

@@ -0,0 +1,258 @@
*if_perl.txt* For Vim version 7.0aa. Last change: 2004 May 01
VIM REFERENCE MANUAL by Sven Verdoolaege
and Matt Gerassimof
Perl and Vim *perl* *Perl*
1. Editing Perl files |perl-editing|
2. Compiling VIM with Perl interface |perl-compiling|
3. Using the Perl interface |perl-using|
{Vi does not have any of these commands}
The Perl interface only works when Vim was compiled with the |+perl| feature.
==============================================================================
1. Editing Perl files *perl-editing*
Vim syntax highlighting supports Perl and POD files. Vim assumes a file is
Perl code if the filename has a .pl or .pm suffix. Vim also examines the first
line of a file, regardless of the filename suffix, to check if a file is a
Perl script (see scripts.vim in Vim's syntax directory). Vim assumes a file
is POD text if the filename has a .POD suffix.
To use tags with Perl, you need a recent version of Exuberant ctags. Look
here:
http://ctags.sourceforge.net
Alternatively, you can use the Perl script pltags.pl, which is shipped with
Vim in the $VIMRUNTIME/tools directory. This script has currently more
features than Exuberant ctags' Perl support.
==============================================================================
2. Compiling VIM with Perl interface *perl-compiling*
To compile Vim with Perl interface, you need Perl 5.004 (or later). Perl must
be installed before you compile Vim. Vim's Perl interface does NOT work with
the 5.003 version that has been officially released! It will probably work
with Perl 5.003_05 and later.
The Perl patches for Vim were made by:
Sven Verdoolaege <skimo@breughel.ufsia.ac.be>
Matt Gerassimof
Perl for MS-Windows can be found at:
http://www.perl.com/CPAN/ports/nt/Standard/x86/
==============================================================================
3. Using the Perl interface *perl-using*
*:perl* *:pe*
:pe[rl] {cmd} Execute Perl command {cmd}. The current package
is "main".
:pe[rl] << {endpattern}
{script}
{endpattern}
Execute Perl script {script}.
{endpattern} must NOT be preceded by any white space.
If {endpattern} is omitted, it defaults to a dot '.'
like for the |:append| and |:insert| commands. Using
'.' helps when inside a function, because "$i;" looks
like the start of an |:insert| command to Vim.
This form of the |:perl| command is mainly useful for
including perl code in vim scripts.
Note: This command doesn't work when the Perl feature
wasn't compiled in. To avoid errors, see
|script-here|.
Example vim script: >
function! WhitePearl()
perl << EOF
VIM::Msg("pearls are nice for necklaces");
VIM::Msg("rubys for rings");
VIM::Msg("pythons for bags");
VIM::Msg("tcls????");
EOF
endfunction
<
*:perldo* *:perld*
:[range]perld[o] {cmd} Execute Perl command {cmd} for each line in the
[range], with $_ being set to the text of each line in
turn, without a trailing <EOL>. Setting $_ will change
the text, but note that it is not possible to add or
delete lines using this command.
The default for [range] is the whole file: "1,$".
Here are some things you can try: >
:perl $a=1
:perldo $_ = reverse($_);1
:perl VIM::Msg("hello")
:perl $line = $curbuf->Get(42)
<
*E299*
Executing Perl commands in the |sandbox| is limited. ":perldo" will not be
possible at all. ":perl" will be evaluated in the Safe environment, if
possible.
*perl-overview*
Here is an overview of the functions that are available to Perl: >
:perl VIM::Msg("Text") # displays a message
:perl VIM::Msg("Error", "ErrorMsg") # displays an error message
:perl VIM::Msg("remark", "Comment") # displays a highlighted message
:perl VIM::SetOption("ai") # sets a vim option
:perl $nbuf = VIM::Buffers() # returns the number of buffers
:perl @buflist = VIM::Buffers() # returns array of all buffers
:perl $mybuf = (VIM::Buffers('qq.c'))[0] # returns buffer object for 'qq.c'
:perl @winlist = VIM::Windows() # returns array of all windows
:perl $nwin = VIM::Windows() # returns the number of windows
:perl ($success, $v) = VIM::Eval('&path') # $v: option 'path', $success: 1
:perl ($success, $v) = VIM::Eval('&xyz') # $v: '' and $success: 0
:perl $v = VIM::Eval('expand("<cfile>")') # expands <cfile>
:perl $curwin->SetHeight(10) # sets the window height
:perl @pos = $curwin->Cursor() # returns (row, col) array
:perl @pos = (10, 10)
:perl $curwin->Cursor(@pos) # sets cursor to @pos
:perl $curwin->Cursor(10,10) # sets cursor to row 10 col 10
:perl $mybuf = $curwin->Buffer() # returns the buffer object for window
:perl $curbuf->Name() # returns buffer name
:perl $curbuf->Number() # returns buffer number
:perl $curbuf->Count() # returns the number of lines
:perl $l = $curbuf->Get(10) # returns line 10
:perl @l = $curbuf->Get(1 .. 5) # returns lines 1 through 5
:perl $curbuf->Delete(10) # deletes line 10
:perl $curbuf->Delete(10, 20) # delete lines 10 through 20
:perl $curbuf->Append(10, "Line") # appends a line
:perl $curbuf->Append(10, "Line1", "Line2", "Line3") # appends 3 lines
:perl @l = ("L1", "L2", "L3")
:perl $curbuf->Append(10, @l) # appends L1, L2 and L3
:perl $curbuf->Set(10, "Line") # replaces line 10
:perl $curbuf->Set(10, "Line1", "Line2") # replaces lines 10 and 11
:perl $curbuf->Set(10, @l) # replaces 3 lines
<
*perl-Msg*
VIM::Msg({msg}, {group}?)
Displays the message {msg}. The optional {group}
argument specifies a highlight group for Vim to use
for the message.
*perl-SetOption*
VIM::SetOption({arg}) Sets a vim option. {arg} can be any argument that the
":set" command accepts. Note that this means that no
spaces are allowed in the argument! See |:set|.
*perl-Buffers*
VIM::Buffers([{bn}...]) With no arguments, returns a list of all the buffers
in an array context or returns the number of buffers
in a scalar context. For a list of buffer names or
numbers {bn}, returns a list of the buffers matching
{bn}, using the same rules as Vim's internal
|bufname()| function.
*perl-Windows*
VIM::Windows([{wn}...]) With no arguments, returns a list of all the windows
in an array context or returns the number of windows
in a scalar context. For a list of window numbers
{wn}, returns a list of the windows with those
numbers.
*perl-DoCommand*
VIM::DoCommand({cmd}) Executes Ex command {cmd}.
*perl-Eval*
VIM::Eval({expr}) Evaluates {expr} and returns (success, val).
success=1 indicates that val contains the value of
{expr}; success=0 indicates a failure to evaluate
the expression. '@x' returns the contents of register
x, '&x' returns the value of option x, 'x' returns the
value of internal |variables| x, and '$x' is equivalent
to perl's $ENV{x}. All |functions| accessible from
the command-line are valid for {expr}.
*perl-SetHeight*
Window->SetHeight({height})
Sets the Window height to {height}, within screen
limits.
*perl-GetCursor*
Window->Cursor({row}?, {col}?)
With no arguments, returns a (row, col) array for the
current cursor position in the Window. With {row} and
{col} arguments, sets the Window's cursor position to
{row} and {col}. Note that {col} is numbered from 0,
Perl-fashion, and thus is one less than the value in
Vim's ruler.
Window->Buffer() *perl-Buffer*
Returns the Buffer object corresponding to the given
Window.
*perl-Name*
Buffer->Name() Returns the filename for the Buffer.
*perl-Number*
Buffer->Number() Returns the number of the Buffer.
*perl-Count*
Buffer->Count() Returns the number of lines in the Buffer.
*perl-Get*
Buffer->Get({lnum}, {lnum}?, ...)
Returns a text string of line {lnum} in the Buffer
for each {lnum} specified. An array can be passed
with a list of {lnum}'s specified.
*perl-Delete*
Buffer->Delete({lnum}, {lnum}?)
Deletes line {lnum} in the Buffer. With the second
{lnum}, deletes the range of lines from the first
{lnum} to the second {lnum}.
*perl-Append*
Buffer->Append({lnum}, {line}, {line}?, ...)
Appends each {line} string after Buffer line {lnum}.
The list of {line}s can be an array.
*perl-Set*
Buffer->Set({lnum}, {line}, {line}?, ...)
Replaces one or more Buffer lines with specified
{lines}s, starting at Buffer line {lnum}. The list of
{line}s can be an array. If the arguments are
invalid, replacement does not occur.
$main::curwin
The current window object.
$main::curbuf
The current buffer object.
*script-here*
When using a script language in-line, you might want to skip this when the
language isn't supported. But this mechanism doesn't work: >
if has('perl')
perl << EOF
this will NOT work!
EOF
endif
Instead, put the Perl/Python/Ruby/etc. command in a function and call that
function: >
if has('perl')
function DefPerl()
perl << EOF
this works
EOF
endfunction
call DefPerl()
endif
Note that "EOF" must be at the start of the line.
vim:tw=78:ts=8:ft=help:norl:

299
runtime/doc/if_pyth.txt Normal file
View File

@@ -0,0 +1,299 @@
*if_pyth.txt* For Vim version 7.0aa. Last change: 2004 Feb 28
VIM REFERENCE MANUAL by Paul Moore
The Python Interface to Vim *python* *Python*
1. Commands |python-commands|
2. The vim module |python-vim|
3. Buffer objects |python-buffer|
4. Range objects |python-range|
5. Window objects |python-window|
{Vi does not have any of these commands}
The Python interface is available only when Vim was compiled with the
|+python| feature.
==============================================================================
1. Commands *python-commands*
*:python* *:py* *E205* *E263* *E264*
:[range]py[thon] {stmt}
Execute Python statement {stmt}.
:[range]py[thon] << {endmarker}
{script}
{endmarker}
Execute Python script {script}.
Note: This command doesn't work when the Python
feature wasn't compiled in. To avoid errors, see
|script-here|.
{endmarker} must NOT be preceded by any white space. If {endmarker} is
omitted from after the "<<", a dot '.' must be used after {script}, like
for the |:append| and |:insert| commands.
This form of the |:python| command is mainly useful for including python code
in Vim scripts.
Example: >
function! IcecreamInitialize()
python << EOF
class StrawberryIcecream:
def __call__(self):
print 'EAT ME'
EOF
endfunction
<
Note: Python is very sensitive to the indenting. Also make sure the "class"
line and "EOF" do not have any indent.
*:pyfile* *:pyf*
:[range]pyf[ile] {file}
Execute the Python script in {file}. The whole
argument is used as a single file name. {not in Vi}
Both of these commands do essentially the same thing - they execute a piece of
Python code, with the "current range" |python-range| set to the given line
range.
In the case of :python, the code to execute is in the command-line.
In the case of :pyfile, the code to execute is the contents of the given file.
Python commands cannot be used in the |sandbox|.
To pass arguments you need to set sys.argv[] explicitly. Example: >
:python import sys
:python sys.argv = ["foo", "bar"]
:pyfile myscript.py
Here are some examples *python-examples* >
:python from vim import *
:python from string import upper
:python current.line = upper(current.line)
:python print "Hello"
:python str = current.buffer[42]
(Note that changes - like the imports - persist from one command to the next,
just like in the Python interpreter.)
==============================================================================
2. The vim module *python-vim*
Python code gets all of its access to vim (with one exception - see
|python-output| below) via the "vim" module. The vim module implements two
methods, three constants, and one error object. You need to import the vim
module before using it: >
:python import vim
Overview >
print "Hello" # displays a message
vim.command(cmd) # execute an ex command
w = vim.windows[n] # gets window "n"
cw = vim.current.window # gets the current window
b = vim.buffers[n] # gets buffer "n"
cb = vim.current.buffer # gets the current buffer
w.height = lines # sets the window height
w.cursor = (row, col) # sets the window cursor position
pos = w.cursor # gets a tuple (row, col)
name = b.name # gets the buffer file name
line = b[n] # gets a line from the buffer
lines = b[n:m] # gets a list of lines
num = len(b) # gets the number of lines
b[n] = str # sets a line in the buffer
b[n:m] = [str1, str2, str3] # sets a number of lines at once
del b[n] # deletes a line
del b[n:m] # deletes a number of lines
Methods of the "vim" module
vim.command(str) *python-command*
Executes the vim (ex-mode) command str. Returns None.
Examples: >
vim.command("set tw=72")
vim.command("%s/aaa/bbb/g")
< The following definition executes Normal mode commands: >
def normal(str):
vim.command("normal "+str)
# Note the use of single quotes to delimit a string containing
# double quotes
normal('"a2dd"aP')
< *E659*
The ":python" command cannot be used recursively with Python 2.2 and
older. This only works with Python 2.3 and later: >
:python vim.command("python print 'Hello again Python'")
vim.eval(str) *python-eval*
Evaluates the expression str using the vim internal expression
evaluator (see |expression|). Returns the expression result as a
string.
Examples: >
text_width = vim.eval("&tw")
str = vim.eval("12+12") # NB result is a string! Use
# string.atoi() to convert to
# a number.
Error object of the "vim" module
vim.error *python-error*
Upon encountering a Vim error, Python raises an exception of type
vim.error.
Example: >
try:
vim.command("put a")
except vim.error:
# nothing in register a
Constants of the "vim" module
Note that these are not actually constants - you could reassign them.
But this is silly, as you would then lose access to the vim objects
to which the variables referred.
vim.buffers *python-buffers*
A sequence object providing access to the list of vim buffers. The
object supports the following operations: >
b = vim.buffers[i] # Indexing (read-only)
b in vim.buffers # Membership test
n = len(vim.buffers) # Number of elements
for b in vim.buffers: # Sequential access
<
vim.windows *python-windows*
A sequence object providing access to the list of vim windows. The
object supports the following operations: >
w = vim.windows[i] # Indexing (read-only)
w in vim.windows # Membership test
n = len(vim.windows) # Number of elements
for w in vim.windows: # Sequential access
<
vim.current *python-current*
An object providing access (via specific attributes) to various
"current" objects available in vim:
vim.current.line The current line (RW) String
vim.current.buffer The current buffer (RO) Buffer
vim.current.window The current window (RO) Window
vim.current.range The current line range (RO) Range
The last case deserves a little explanation. When the :python or
:pyfile command specifies a range, this range of lines becomes the
"current range". A range is a bit like a buffer, but with all access
restricted to a subset of lines. See |python-range| for more details.
Output from Python *python-output*
Vim displays all Python code output in the Vim message area. Normal
output appears as information messages, and error output appears as
error messages.
In implementation terms, this means that all output to sys.stdout
(including the output from print statements) appears as information
messages, and all output to sys.stderr (including error tracebacks)
appears as error messages.
*python-input*
Input (via sys.stdin, including input() and raw_input()) is not
supported, and may cause the program to crash. This should probably be
fixed.
==============================================================================
3. Buffer objects *python-buffer*
Buffer objects represent vim buffers. You can obtain them in a number of ways:
- via vim.current.buffer (|python-current|)
- from indexing vim.buffers (|python-buffers|)
- from the "buffer" attribute of a window (|python-window|)
Buffer objects have one read-only attribute - name - the full file name for
the buffer. They also have three methods (append, mark, and range; see below).
You can also treat buffer objects as sequence objects. In this context, they
act as if they were lists (yes, they are mutable) of strings, with each
element being a line of the buffer. All of the usual sequence operations,
including indexing, index assignment, slicing and slice assignment, work as
you would expect. Note that the result of indexing (slicing) a buffer is a
string (list of strings). This has one unusual consequence - b[:] is different
from b. In particular, "b[:] = None" deletes the whole of the buffer, whereas
"b = None" merely updates the variable b, with no effect on the buffer.
Buffer indexes start at zero, as is normal in Python. This differs from vim
line numbers, which start from 1. This is particularly relevant when dealing
with marks (see below) which use vim line numbers.
The buffer object methods are:
b.append(str) Append a line to the buffer
b.append(list) Append a list of lines to the buffer
Note that the option of supplying a list of strings to
the append method differs from the equivalent method
for Python's built-in list objects.
b.mark(name) Return a tuple (row,col) representing the position
of the named mark (can also get the []"<> marks)
b.range(s,e) Return a range object (see |python-range|) which
represents the part of the given buffer between line
numbers s and e |inclusive|.
Examples (assume b is the current buffer) >
print b.name # write the buffer file name
b[0] = "hello!!!" # replace the top line
b[:] = None # delete the whole buffer
del b[:] # delete the whole buffer (same as above)
b[0:0] = [ "a line" ] # add a line at the top
del b[2] # delete a line (the third)
b.append("bottom") # add a line at the bottom
n = len(b) # number of lines
(row,col) = b.mark('a') # named mark
r = b.range(1,5) # a sub-range of the buffer
==============================================================================
4. Range objects *python-range*
Range objects represent a part of a vim buffer. You can obtain them in a
number of ways:
- via vim.current.range (|python-current|)
- from a buffer's range() method (|python-buffer|)
A range object is almost identical in operation to a buffer object. However,
all operations are restricted to the lines within the range (this line range
can, of course, change as a result of slice assignments, line deletions, or
the range.append() method).
The range object attributes are:
r.start Index of first line into the buffer
r.end Index of last line into the buffer
The range object methods are:
r.append(str) Append a line to the range
r.append(list) Append a list of lines to the range
Note that the option of supplying a list of strings to
the append method differs from the equivalent method
for Python's built-in list objects.
Example (assume r is the current range):
# Send all lines in a range to the default printer
vim.command("%d,%dhardcopy!" % (r.start+1,r.end+1))
==============================================================================
5. Window objects *python-window*
Window objects represent vim windows. You can obtain them in a number of ways:
- via vim.current.window (|python-current|)
- from indexing vim.windows (|python-windows|)
You can manipulate window objects only through their attributes. They have no
methods, and no sequence or other interface.
Window attributes are:
buffer (read-only) The buffer displayed in this window
cursor (read-write) The current cursor position in the window
This is a tuple, (row,col).
height (read-write) The window height, in rows
width (read-write) The window width, in columns
The height attribute is writable only if the screen is split horizontally.
The width attribute is writable only if the screen is split vertically.
==============================================================================
vim:tw=78:ts=8:ft=help:norl:

175
runtime/doc/if_ruby.txt Normal file
View File

@@ -0,0 +1,175 @@
*if_ruby.txt* For Vim version 7.0aa. Last change: 2004 Mar 14
VIM REFERENCE MANUAL by Shugo Maeda
The Ruby Interface to Vim *ruby* *Ruby*
1. Commands |ruby-commands|
2. The VIM module |ruby-vim|
3. VIM::Buffer objects |ruby-buffer|
4. VIM::Window objects |ruby-window|
5. Global variables |ruby-globals|
{Vi does not have any of these commands}
*E266* *E267* *E268* *E269* *E270* *E271* *E272* *E273*
The Ruby interface only works when Vim was compiled with the |+ruby| feature.
The home page for ruby is http://www.ruby-lang.org/. You can find links for
downloading Ruby there.
==============================================================================
1. Commands *ruby-commands*
*:ruby* *:rub*
:rub[y] {cmd} Execute Ruby command {cmd}.
:rub[y] << {endpattern}
{script}
{endpattern}
Execute Ruby script {script}.
{endpattern} must NOT be preceded by any white space.
If {endpattern} is omitted, it defaults to a dot '.'
like for the |:append| and |:insert| commands. This
form of the |:ruby| command is mainly useful for
including ruby code in vim scripts.
Note: This command doesn't work when the Ruby feature
wasn't compiled in. To avoid errors, see
|script-here|.
Example Vim script: >
function! RedGem()
ruby << EOF
class Garnet
def initialize(s)
@buffer = VIM::Buffer.current
vimputs(s)
end
def vimputs(s)
@buffer.append(@buffer.count,s)
end
end
gem = Garnet.new("pretty")
EOF
endfunction
<
*:rubydo* *:rubyd* *E265*
:[range]rubyd[o] {cmd} Evaluate Ruby command {cmd} for each line in the
[range], with $_ being set to the text of each line in
turn, without a trailing <EOL>. Setting $_ will change
the text, but note that it is not possible to add or
delete lines using this command.
The default for [range] is the whole file: "1,$".
*:rubyfile* *:rubyf*
:rubyf[ile] {file} Execute the Ruby script in {file}. This is the same as
":ruby load 'file'", but allows file name completion.
Executing Ruby commands is not possible in the |sandbox|.
==============================================================================
2. The VIM module *ruby-vim*
Ruby code gets all of its access to vim via the "VIM" module.
Overview >
print "Hello" # displays a message
VIM.command(cmd) # execute an ex command
num = VIM::Window.count # gets the number of windows
w = VIM::Window[n] # gets window "n"
cw = VIM::Window.current # gets the current window
num = VIM::Buffer.count # gets the number of buffers
b = VIM::Buffer[n] # gets buffer "n"
cb = VIM::Buffer.current # gets the current buffer
w.height = lines # sets the window height
w.cursor = [row, col] # sets the window cursor position
pos = w.cursor # gets an array [row, col]
name = b.name # gets the buffer file name
line = b[n] # gets a line from the buffer
num = b.count # gets the number of lines
b[n] = str # sets a line in the buffer
b.delete(n) # deletes a line
b.append(n, str) # appends a line after n
<
Module Functions:
*ruby-message*
VIM::message({msg})
Displays the message {msg}.
*ruby-set_option*
VIM::set_option({arg})
Sets a vim option. {arg} can be any argument that the ":set" command
accepts. Note that this means that no spaces are allowed in the
argument! See |:set|.
*ruby-command*
VIM::command({cmd})
Executes Ex command {cmd}.
*ruby-evaluate*
VIM::evaluate({expr})
Evaluates {expr} using the vim internal expression evaluator (see
|expression|). Returns the expression result as a string.
==============================================================================
3. VIM::Buffer objects *ruby-buffer*
VIM::Buffer objects represent vim buffers.
Class Methods:
current Returns the current buffer object.
count Returns the number of buffers.
self[{n}] Returns the buffer object for the number {n}. The first number
is 0.
Methods:
name Returns the name of the buffer.
number Returns the number of the buffer.
count Returns the number of lines.
length Returns the number of lines.
self[{n}] Returns a line from the buffer. {n} is the line number.
self[{n}] = {str}
Sets a line in the buffer. {n} is the line number.
delete({n}) Deletes a line from the buffer. {n} is the line number.
append({n}, {str})
Appends a line after the line {n}.
==============================================================================
4. VIM::Window objects *ruby-window*
VIM::Window objects represent vim windows.
Class Methods:
current Returns the current window object.
count Returns the number of windows.
self[{n}] Returns the window object for the number {n}. The first number
is 0.
Methods:
buffer Returns the buffer displayed in the window.
height Returns the height of the window.
height = {n} Sets the window height to {n}.
cursor Returns a [row, col] array for the cursor position.
cursor = [{row}, {col}]
Sets the cursor position to {row} and {col}.
==============================================================================
4. Global variables *ruby-globals*
There are two global variables.
$curwin The current window object.
$curbuf The current buffer object.
==============================================================================
vim:tw=78:ts=8:ft=help:norl:

95
runtime/doc/if_sniff.txt Normal file
View File

@@ -0,0 +1,95 @@
*if_sniff.txt* For Vim version 7.0aa. Last change: 2001 Sep 03
VIM REFERENCE MANUAL
by Anton Leherbauer (toni@takefive.co.at)
SNiFF+ and Vim *sniff*
1. Introduction |sniff-intro|
2. Commands |sniff-commands|
3. Compiling Vim with SNiFF+ interface |sniff-compiling|
{Vi does not have any of these commands} *E275* *E274* *E276* *E278* *E279*
The SNiFF+ interface only works, when Vim was compiled with the |+sniff|
feature.
==============================================================================
1. Introduction *sniff-intro*
The following features for the use with SNiFF+ are available:
* Vim can be used for all editing requests
* SNiFF+ recognizes and updates all browsers when a file is saved in Vim
* SNiFF+ commands can be issued directly from Vim
How to use Vim with SNiFF+
1. Make sure SNiFF+ is running.
2. In the Editor view of the Preferences dialog set the Field named
'External Editor' to 'Emacs/Vim'.
4. Start Vim
5. Connect to SNiFF+ (:sniff connect)
Once a connection is established, SNiFF+ uses Vim for all requests to show or
edit source code. On the other hand, you can send queries to SNiFF+ with the
:sniff command.
==============================================================================
2. Commands *sniff-commands*
*:sniff* *:sni*
:sni[ff] request [symbol] Send request to sniff with optional symbol.
{not in Vi}
:sni[ff] Display all possible requests and the connection
status
Most requests require a symbol (identifier) as parameter. If it is omitted,
Vim will use the current word under the cursor.
The available requests are listed below:
request mapping description
-------------------------------------------------------------------------------
connect sc Establish connection with SNiFF+.
Make sure SNiFF+ is prepared for this in the
Preferences
disconnect sq Disconnect from SNiFF+. You can reconnect any
time with :sniff connect (or 'sc')
toggle st Toggle between implementation
and definition file
find-symbol sf Load the symbol into a Symbol Browser
browse-class sb Loads the class into a Class Browser
superclass ss Edit superclass of symbol
overridden so Edit overridden method of symbol
retrieve-file srf Retrieve symbol in current file
retrieve-project srp Retrieve symbol in current project
retrieve-all-projects srP Retrieve symbol in all projects
retrieve-next sR Retrieve symbol using current Retriever
settings
goto-symbol sg Goto definition or implementation of symbol
hierarchy sh Load symbol into the Hierarchy Browser
restr-hier sH same as above but show only related classes
xref-to sxt Start a refers-to query on symbol and
load the results into the Cross Referencer
xref-by sxb Start a referred-by query on symbol
xref-has sxh Start a refers-to components query on symbol
xref-used-by sxu Start a referred-by as component query on
symbol
show-docu sd Show documentation of symbol
gen-docu sD Generate documentation of symbol
The mappings are defined in a file 'sniff.vim', which is part of every SNiFF+
product ($SNIFF_DIR/config/sniff.vim). This file is sourced whenever Vim
connects to SNiFF+.
==============================================================================
3. Compiling Vim with SNiFF+ interface *sniff-compiling*
To compile Vim with SNiFF+ support, you need two source files of the extra
archive: if_sniff.c and if_sniff.h.
On Unix: Edit the Makefile and uncomment the line "--enable-sniff". Or run
configure manually with this argument.
On NT: Specify SNIFF=yes with your make command.
vim:tw=78:ts=8:ft=help:norl:

512
runtime/doc/if_tcl.txt Normal file
View File

@@ -0,0 +1,512 @@
*if_tcl.txt* For Vim version 7.0aa. Last change: 2004 Jan 17
VIM REFERENCE MANUAL by Ingo Wilken
The Tcl Interface to Vim *tcl* *Tcl* *TCL*
1. Commands |tcl-ex-commands|
2. Tcl commands |tcl-commands|
3. Tcl variables |tcl-variables|
4. Tcl window commands |tcl-window-cmds|
5. Tcl buffer commands |tcl-buffer-cmds|
6. Miscellaneous; Output from Tcl |tcl-misc| |tcl-output|
7. Known bugs & problems |tcl-bugs|
8. Examples |tcl-examples|
{Vi does not have any of these commands} *E280* *E281*
The Tcl interface only works when Vim was compiled with the |+tcl| feature.
WARNING: There are probably still some bugs. Please send bug reports,
comments, ideas etc to <Ingo.Wilken@informatik.uni-oldenburg.de>
==============================================================================
1. Commands *tcl-ex-commands* *E571* *E572*
*:tcl* *:tc*
:tc[l] {cmd} Execute Tcl command {cmd}.
:[range]tc[l] << {endmarker}
{script}
{endmarker}
Execute Tcl script {script}.
Note: This command doesn't work when the Tcl feature
wasn't compiled in. To avoid errors, see
|script-here|.
{endmarker} must NOT be preceded by any white space. If {endmarker} is
omitted from after the "<<", a dot '.' must be used after {script}, like for
the |:append| and |:insert| commands.
This form of the |:tcl| command is mainly useful for including tcl code in Vim
scripts.
Example: >
function! DefineDate()
tcl << EOF
proc date {} {
return [clock format [clock seconds]]
}
EOF
endfunction
<
*:tcldo* *:tcld*
:[range]tcld[o] {cmd} Execute Tcl command {cmd} for each line in [range]
with the variable "line" being set to the text of each
line in turn, and "lnum" to the line number. Setting
"line" will change the text, but note that it is not
possible to add or delete lines using this command.
If {cmd} returns an error, the command is interrupted.
The default for [range] is the whole file: "1,$".
See |tcl-var-line| and |tcl-var-lnum|. {not in Vi}
*:tclfile* *:tclf*
:tclf[ile] {file} Execute the Tcl script in {file}. This is the same as
":tcl source {file}", but allows file name completion.
{not in Vi}
Note that Tcl objects (like variables) persist from one command to the next,
just as in the Tcl shell.
Executing Tcl commands is not possible in the |sandbox|.
==============================================================================
2. Tcl commands *tcl-commands*
Tcl code gets all of its access to vim via commands in the "::vim" namespace.
The following commands are implemented: >
::vim::beep # Guess.
::vim::buffer {n} # Create Tcl command for one buffer.
::vim::buffer list # Create Tcl commands for all buffers.
::vim::command [-quiet] {cmd} # Execute an ex command.
::vim::expr {expr} # Use Vim's expression evaluator.
::vim::option {opt} # Get vim option.
::vim::option {opt} {val} # Set vim option.
::vim::window list # Create Tcl commands for all windows.
Commands:
::vim::beep *tcl-beep*
Honk. Does not return a result.
::vim::buffer {n} *tcl-buffer*
::vim::buffer exists {n}
::vim::buffer list
Provides access to vim buffers. With an integer argument, creates a
buffer command (see |tcl-buffer-cmds|) for the buffer with that
number, and returns its name as the result. Invalid buffer numbers
result in a standard Tcl error. To test for valid buffer numbers,
vim's internal functions can be used: >
set nbufs [::vim::expr bufnr("$")]
set isvalid [::vim::expr "bufexists($n)"]
< The "list" option creates a buffer command for each valid buffer, and
returns a list of the command names as the result.
Example: >
set bufs [::vim::buffer list]
foreach b $bufs { $b append end "The End!" }
< The "exists" option checks if a buffer with the given number exists.
Example: >
if { [::vim::buffer exists $n] } { ::vim::command ":e #$n" }
< This command might be replaced by a variable in future versions.
See also |tcl-var-current| for the current buffer.
::vim::command {cmd} *tcl-command*
::vim::command -quiet {cmd}
Execute the vim (ex-mode) command {cmd}. Any ex command that affects
a buffer or window uses the current buffer/current window. Does not
return a result other than a standard Tcl error code. After this
command is completed, the "::vim::current" variable is updated.
The "-quiet" flag suppresses any error messages from vim.
Examples: >
::vim::command "set ts=8"
::vim::command "%s/foo/bar/g"
< To execute normal-mode commands, use "normal" (see |:normal|): >
set cmd "jj"
::vim::command "normal $cmd"
< See also |tcl-window-command| and |tcl-buffer-command|.
::vim::expr {expr} *tcl-expr*
Evaluates the expression {expr} using vim's internal expression
evaluator (see |expression|). Any expression that queries a buffer
or window property uses the current buffer/current window. Returns
the result as a string.
Examples: >
set perl_available [::vim::expr has("perl")]
< See also |tcl-window-expr| and |tcl-buffer-expr|.
::vim::option {opt} *tcl-option*
::vim::option {opt} {value}
Without second argument, queries the value of a vim option. With this
argument, sets the vim option to {value}, and returns the previous
value as the result. Any options that are marked as 'local to buffer'
or 'local to window' affect the current buffer/current window. The
global value is not changed, use the ":set" command for that. For
boolean options, {value} should be "0" or "1", or any of the keywords
"on", "off" or "toggle". See |option-summary| for a list of options.
Example: >
::vim::option ts 8
< See also |tcl-window-option| and |tcl-buffer-option|.
::vim::window {option} *tcl-window*
Provides access to vim windows. Currently only the "list" option is
implemented. This creates a window command (see |tcl-window-cmds|) for
each window, and returns a list of the command names as the result.
Example: >
set wins [::vim::window list]
foreach w $wins { $w height 4 }
< This command might be replaced by a variable in future versions.
See also |tcl-var-current| for the current window.
==============================================================================
3. Tcl variables *tcl-variables*
The ::vim namespace contains a few variables. These are created when the Tcl
interpreter is called from vim and set to current values. >
::vim::current # array containing "current" objects
::vim::lbase # number of first line
::vim::range # array containing current range numbers
line # current line as a string (:tcldo only)
lnum # current line number (:tcldo only)
Variables:
::vim::current *tcl-var-current*
This is an array providing access to various "current" objects
available in vim. The contents of this array are updated after
"::vim::command" is called, as this might change vim's current
settings (e.g., by deleting the current buffer).
The "buffer" element contains the name of the buffer command for the
current buffer. This can be used directly to invoke buffer commands
(see |tcl-buffer-cmds|). This element is read-only.
Example: >
$::vim::current(buffer) insert begin "Hello world"
< The "window" element contains the name of the window command for the
current window. This can be used directly to invoke window commands
(see |tcl-window-cmds|). This element is read-only.
Example: >
$::vim::current(window) height 10
<
::vim::lbase *tcl-var-lbase*
This variable controls how Tcl treats line numbers. If it is set to
'1', then lines and columns start at 1. This way, line numbers from
Tcl commands and vim expressions are compatible. If this variable is
set to '0', then line numbers and columns start at 0 in Tcl. This is
useful if you want to treat a buffer as a Tcl list or a line as a Tcl
string and use standard Tcl commands that return an index ("lsort" or
"string first", for example). The default value is '1'. Currently,
any non-zero values is treated as '1', but your scripts should not
rely on this. See also |tcl-linenumbers|.
::vim::range *tcl-var-range*
This is an array with three elements, "start", "begin" and "end". It
contains the line numbers of the start and end row of the current
range. "begin" is the same as "start". This variable is read-only.
See |tcl-examples|.
line *tcl-var-line*
lnum *tcl-var-lnum*
These global variables are only available if the ":tcldo" ex command
is being executed. They contain the text and line number of the
current line. When the Tcl command invoked by ":tcldo" is completed,
the current line is set to the contents of the "line" variable, unless
the variable was unset by the Tcl command. The "lnum" variable is
read-only. These variables are not in the "::vim" namespace so they
can be used in ":tcldo" without much typing (this might be changed in
future versions). See also |tcl-linenumbers|.
==============================================================================
4. Tcl window commands *tcl-window-cmds*
Window commands represent vim windows. They are created by several commands:
::vim::window list |tcl-window|
"windows" option of a buffer command |tcl-buffer-windows|
The ::vim::current(window) variable contains the name of the window command
for the current window. A window command is automatically deleted when the
corresponding vim window is closed.
Lets assume the name of the window command is stored in the Tcl variable "win",
i.e. "$win" calls the command. The following options are available: >
$win buffer # Create Tcl command for window's buffer.
$win command {cmd} # Execute ex command in windows context.
$win cursor # Get current cursor position.
$win cursor {var} # Set cursor position from array variable.
$win cursor {row} {col} # Set cursor position.
$win delcmd {cmd} # Call Tcl command when window is closed.
$win expr {expr} # Evaluate vim expression in windows context.
$win height # Report the window's height.
$win height {n} # Set the window's height.
$win option {opt} [val] # Get/Set vim option in windows context.
Options:
$win buffer *tcl-window-buffer*
Creates a Tcl command for the window's buffer, and returns its name as
the result. The name should be stored in a variable: >
set buf [$win buffer]
< $buf is now a valid Tcl command. See |tcl-buffer-cmds| for the
available options.
$win cursor *tcl-window-cursor*
$win cursor {var}
$win cursor {row} {col}
Without argument, reports the current cursor position as a string.
This can be converted to a Tcl array variable: >
array set here [$win cursor]
< "here(row)" and "here(column)" now contain the cursor position.
With a single argument, the argument is interpreted as the name of a
Tcl array variable, which must contain two elements "row" and "column".
These are used to set the cursor to the new position: >
$win cursor here ;# not $here !
< With two arguments, sets the cursor to the specified row and column: >
$win cursor $here(row) $here(column)
< Invalid positions result in a standard Tcl error, which can be caught
with "catch". The row and column values depend on the "::vim::lbase"
variable. See |tcl-var-lbase|.
$win delcmd {cmd} *tcl-window-delcmd*
Registers the Tcl command {cmd} as a deletion callback for the window.
This command is executed (in the global scope) just before the window
is closed. Complex commands should be build with "list": >
$win delcmd [list puts vimerr "window deleted"]
< See also |tcl-buffer-delcmd|.
$win height *tcl-window-height*
$win height {n}
Without argument, reports the window's current height. With an
argument, tries to set the window's height to {n}, then reports the
new height (which might be different from {n}).
$win command [-quiet] {cmd} *tcl-window-command*
$win expr {expr} *tcl-window-expr*
$win option {opt} [val] *tcl-window-option*
These are similar to "::vim::command" etc., except that everything is
done in the context of the window represented by $win, instead of the
current window. For example, setting an option that is marked 'local
to window' affects the window $win. Anything that affects or queries
a buffer uses the buffer displayed in this window (i.e. the buffer
that is represented by "$win buffer"). See |tcl-command|, |tcl-expr|
and |tcl-option| for more information.
Example: >
$win option number on
==============================================================================
5. Tcl buffer commands *tcl-buffer-cmds*
Buffer commands represent vim buffers. They are created by several commands:
::vim::buffer {N} |tcl-buffer|
::vim::buffer list |tcl-buffer|
"buffer" option of a window command |tcl-window-buffer|
The ::vim::current(buffer) variable contains the name of the buffer command
for the current buffer. A buffer command is automatically deleted when the
corresponding vim buffer is destroyed. Whenever the buffer's contents are
changed, all marks in the buffer are automatically adjusted. Any changes to
the buffer's contents made by Tcl commands can be undone with the "undo" vim
command (see |undo|).
Lets assume the name of the buffer command is stored in the Tcl variable "buf",
i.e. "$buf" calls the command. The following options are available: >
$buf append {n} {str} # Append a line to buffer, after line {n}.
$buf command {cmd} # Execute ex command in buffers context.
$buf count # Report number of lines in buffer.
$buf delcmd {cmd} # Call Tcl command when buffer is deleted.
$buf delete {n} # Delete a single line.
$buf delete {n} {m} # Delete several lines.
$buf expr {expr} # Evaluate vim expression in buffers context.
$buf get {n} # Get a single line as a string.
$buf get {n} {m} # Get several lines as a list.
$buf insert {n} {str} # Insert a line in buffer, as line {n}.
$buf last # Report line number of last line in buffer.
$buf mark {mark} # Report position of buffer mark.
$buf name # Report name of file in buffer.
$buf number # Report number of this buffer.
$buf option {opt} [val] # Get/Set vim option in buffers context.
$buf set {n} {text} # Replace a single line.
$buf set {n} {m} {list} # Replace several lines.
$buf windows # Create Tcl commands for buffer's windows.
<
*tcl-linenumbers*
Most buffer commands take line numbers as arguments. How Tcl treats these
numbers depends on the "::vim::lbase" variable (see |tcl-var-lbase|). Instead
of line numbers, several keywords can be also used: "top", "start", "begin",
"first", "bottom", "end" and "last".
Options:
$buf append {n} {str} *tcl-buffer-append*
$buf insert {n} {str} *tcl-buffer-insert*
Add a line to the buffer. With the "insert" option, the string
becomes the new line {n}, with "append" it is inserted after line {n}.
Example: >
$buf insert top "This is the beginning."
$buf append end "This is the end."
< To add a list of lines to the buffer, use a loop: >
foreach line $list { $buf append $num $line ; incr num }
<
$buf count *tcl-buffer-count*
Reports the total number of lines in the buffer.
$buf delcmd {cmd} *tcl-buffer-delcmd*
Registers the Tcl command {cmd} as a deletion callback for the buffer.
This command is executed (in the global scope) just before the buffer
is deleted. Complex commands should be build with "list": >
$buf delcmd [list puts vimerr "buffer [$buf number] gone"]
< See also |tcl-window-delcmd|.
$buf delete {n} *tcl-buffer-delete*
$buf delete {n} {m}
Deletes line {n} or lines {n} through {m} from the buffer.
This example deletes everything except the last line: >
$buf delete first [expr [$buf last] - 1]
<
$buf get {n} *tcl-buffer-get*
$buf get {n} {m}
Gets one or more lines from the buffer. For a single line, the result
is a string; for several lines, a list of strings.
Example: >
set topline [$buf get top]
<
$buf last *tcl-buffer-last*
Reports the line number of the last line. This value depends on the
"::vim::lbase" variable. See |tcl-var-lbase|.
$buf mark {mark} *tcl-buffer-mark*
Reports the position of the named mark as a string, similar to the
cursor position of the "cursor" option of a window command (see
|tcl-window-cursor|). This can be converted to a Tcl array variable: >
array set mpos [$buf mark "a"]
< "mpos(column)" and "mpos(row)" now contain the position of the mark.
If the mark is not set, a standard Tcl error results.
$buf name
Reports the name of the file in the buffer. For a buffer without a
file, this is an empty string.
$buf number
Reports the number of this buffer. See |:buffers|.
This example deletes a buffer from vim: >
::vim::command "bdelete [$buf number]"
<
$buf set {n} {string} *tcl-buffer-set*
$buf set {n} {m} {list}
Replace one or several lines in the buffer. If the list contains more
elements than there are lines to replace, they are inserted into the
buffer. If the list contains fewer elements, any unreplaced line is
deleted from the buffer.
$buf windows *tcl-buffer-windows*
Creates a window command for each window that displays this buffer, and
returns a list of the command names as the result.
Example: >
set winlist [$buf windows]
foreach win $winlist { $win height 4 }
< See |tcl-window-cmds| for the available options.
$buf command [-quiet] {cmd} *tcl-buffer-command*
$buf expr {exr} *tcl-buffer-expr*
$buf option {opt} [val] *tcl-buffer-option*
These are similar to "::vim::command" etc., except that everything is
done in the context of the buffer represented by $buf, instead of the
current buffer. For example, setting an option that is marked 'local
to buffer' affects the buffer $buf. Anything that affects or queries
a window uses the first window in vim's window list that displays this
buffer (i.e. the first entry in the list returned by "$buf windows").
See |tcl-command|, |tcl-expr| and |tcl-option| for more information.
Example: >
if { [$buf option modified] } { $buf command "w" }
==============================================================================
6. Miscellaneous; Output from Tcl *tcl-misc* *tcl-output*
The standard Tcl commands "exit" and "catch" are replaced by custom versions.
"exit" terminates the current Tcl script and returns to vim, which deletes the
Tcl interpreter. Another call to ":tcl" then creates a new Tcl interpreter.
"exit" does NOT terminate vim! "catch" works as before, except that it does
not prevent script termination from "exit". An exit code != 0 causes the ex
command that invoked the Tcl script to return an error.
Two new I/O streams are available in Tcl, "vimout" and "vimerr". All output
directed to them is displayed in the vim message area, as information messages
and error messages, respectively. The standard Tcl output streams stdout and
stderr are mapped to vimout and vimerr, so that a normal "puts" command can be
used to display messages in vim.
==============================================================================
7. Known bugs & problems *tcl-bugs*
Calling one of the Tcl ex commands from inside Tcl (via "::vim::command") may
have unexpected side effects. The command creates a new interpreter, which
has the same abilities as the standard interpreter - making "::vim::command"
available in a safe child interpreter therefore makes the child unsafe. (It
would be trivial to block nested :tcl* calls or ensure that such calls from a
safe interpreter create only new safe interpreters, but quite pointless -
depending on vim's configuration, "::vim::command" may execute arbitrary code
in any number of other scripting languages.) A call to "exit" within this new
interpreter does not affect the old interpreter; it only terminates the new
interpreter, then script processing continues normally in the old interpreter.
Input from stdin is currently not supported.
==============================================================================
8. Examples: *tcl-examples*
Here are a few small (and maybe useful) Tcl scripts.
This script sorts the lines of the entire buffer (assume it contains a list
of names or something similar):
set buf $::vim::current(buffer)
set lines [$buf get top bottom]
set lines [lsort -dictionary $lines]
$buf set top bottom $lines
This script reverses the lines in the buffer. Note the use of "::vim::lbase"
and "$buf last" to work with any line number setting.
set buf $::vim::current(buffer)
set t $::vim::lbase
set b [$buf last]
while { $t < $b } {
set tl [$buf get $t]
set bl [$buf get $b]
$buf set $t $bl
$buf set $b $tl
incr t
incr b -1
}
This script adds a consecutive number to each line in the current range:
set buf $::vim::current(buffer)
set i $::vim::range(start)
set n 1
while { $i <= $::vim::range(end) } {
set line [$buf get $i]
$buf set $i "$n\t$line"
incr i ; incr n
}
The same can also be done quickly with two ex commands, using ":tcldo":
:tcl set n 1
:[range]tcldo set line "$n\t$line" ; incr n
This procedure runs an ex command on each buffer (idea stolen from Ron Aaron):
proc eachbuf { cmd } {
foreach b [::vim::buffer list] {
$b command $cmd
}
}
Use it like this:
:tcl eachbuf %s/foo/bar/g
Be careful with Tcl's string and backslash substitution, tough. If in doubt,
surround the ex command with curly braces.
If you want to add some Tcl procedures permanently to vim, just place them in
a file (e.g. "~/.vimrc.tcl" on Unix machines), and add these lines to your
startup file (usually "~/.vimrc" on Unix):
if has("tcl")
tclfile ~/.vimrc.tcl
endif
==============================================================================
vim:tw=78:ts=8:ft=help:norl:

522
runtime/doc/indent.txt Normal file
View File

@@ -0,0 +1,522 @@
*indent.txt* For Vim version 7.0aa. Last change: 2004 Apr 25
VIM REFERENCE MANUAL by Bram Moolenaar
This file is about indenting C programs and other files.
1. Indenting C programs |C-indenting|
2. Indenting by expression |indent-expression|
==============================================================================
1. Indenting C programs *C-indenting*
The basics for C indenting are explained in section |30.2| of the user manual.
Vim has options for automatically indenting C program files. These options
affect only the indent and do not perform other formatting. For comment
formatting, see |format-comments|.
Note that this will not work when the |+smartindent| or |+cindent| features
have been disabled at compile time.
There are in fact four methods available for indentation:
'autoindent' uses the indent from the previous line.
'smartindent' is like 'autoindent' but also recognizes some C syntax to
increase/reduce the indent where appropriate.
'cindent' Works more cleverly than the other two and is configurable to
different indenting styles.
'indentexpr' The most flexible of all: Evaluates an expression to compute
the indent of a line. When non-empty this method overrides
the other ones. See |indent-expression|.
The rest of this section describes the 'cindent' option.
Note that 'cindent' indenting does not work for every code scenario. Vim
is not a C compiler: it does not recognize all syntax.
These four options control C program indenting:
'cindent' Enables Vim to perform C program indenting automatically.
'cinkeys' Specifies which keys trigger reindenting in insert mode.
'cinoptions' Sets your preferred indent style.
'cinwords' Defines keywords that start an extra indent in the next line.
If 'lisp' is not on and 'equalprg' is empty, the "=" operator indents using
Vim's built-in algorithm rather than calling an external program.
See |autocommand| for how to set the 'cindent' option automatically for C code
files and reset it for others.
*cinkeys-format* *indentkeys-format*
The 'cinkeys' option is a string that controls Vim's indenting in response to
typing certain characters or commands in certain contexts. Note that this not
only triggers C-indenting. When 'indentexpr' is not empty 'indentkeys' is
used instead. The format of 'cinkeys' and 'indentkeys' is equal.
The default is "0{,0},0),:,0#,!^F,o,O,e" which specifies that indenting occurs
as follows:
"0{" if you type '{' as the first character in a line
"0}" if you type '}' as the first character in a line
"0)" if you type ')' as the first character in a line
":" if you type ':' after a label or case statement
"0#" if you type '#' as the first character in a line
"!^F" if you type CTRL-F (which is not inserted)
"o" if you type a <CR> anywhere or use the "o" command (not in
insert mode!)
"O" if you use the "O" command (not in insert mode!)
"e" if you type the second 'e' for an "else" at the start of a
line
Characters that can precede each key:
! When a '!' precedes the key, Vim will not insert the key but will
instead reindent the current line. This allows you to define a
command key for reindenting the current line. CTRL-F is the default
key for this. Be careful if you define CTRL-I for this because CTRL-I
is the ASCII code for <Tab>.
* When a '*' precedes the key, Vim will reindent the line before
inserting the key. If 'cinkeys' contains "*<Return>", Vim reindents
the current line before opening a new line.
0 When a zero precedes the key (but appears after '!' or '*') Vim will
reindent the line only if the key is the first character you type in
the line. When used before "=" Vim will only reindent the line if
there is only white space before the word.
When neither '!' nor '*' precedes the key, Vim reindents the line after you
type the key. So ';' sets the indentation of a line which includes the ';'.
Special key names:
<> Angle brackets mean spelled-out names of keys. For example: "<Up>",
"<Ins>" (see |key-notation|).
^ Letters preceded by a caret (^) are control characters. For example:
"^F" is CTRL-F.
o Reindent a line when you use the "o" command or when Vim opens a new
line below the current one (e.g., when you type <Enter> in insert
mode).
O Reindent a line when you use the "O" command.
e Reindent a line that starts with "else" when you type the second 'e'.
: Reindent a line when a ':' is typed which is after a label or case
statement. Don't reindent for a ":" in "class::method" for C++. To
Reindent for any ":", use "<:>".
=word Reindent when typing the last character of "word". "word" may
actually be part of another word. Thus "=end" would cause reindenting
when typing the "d" in "endif" or "endwhile". But not when typing
"bend". Also reindent when completion produces a word that starts
with "word". "0=word" reindents when there is only white space before
the word.
=~word Like =word, but ignore case.
If you really want to reindent when you type 'o', 'O', 'e', '0', '<', '>',
'*', ':' or '!', use "<o>", "<O>", "<e>", "<0>", "<<>", "<>>", "<*>", "<:>" or
"<!>", respectively, for those keys.
For an emacs-style indent mode where lines aren't indented every time you
press Enter but only if you press Tab, I suggest:
:set cinkeys=0{,0},:,0#,!<Tab>,!^F
You might also want to switch off 'autoindent' then.
Note: If you change the current line's indentation manually, Vim ignores the
cindent settings for that line. This prevents vim from reindenting after you
have changed the indent by typing <BS>, <Tab>, or <Space> in the indent or
used CTRL-T or CTRL-D.
*cinoptions-values*
The 'cinoptions' option sets how Vim performs indentation. In the list below,
"N" represents a number of your choice (the number can be negative). When
there is an 's' after the number, Vim multiplies the number by 'shiftwidth':
"1s" is 'shiftwidth', "2s" is two times 'shiftwidth', etc. You can use a
decimal point, too: "-0.5s" is minus half a 'shiftwidth'. The examples below
assume a 'shiftwidth' of 4.
>N Amount added for "normal" indent. Used after a line that should
increase the indent (lines starting with "if", an opening brace,
etc.). (default 'shiftwidth').
cino= cino=>2 cino=>2s >
if (cond) if (cond) if (cond)
{ { {
foo; foo; foo;
} } }
<
eN Add N to the prevailing indent inside a set of braces if the
opening brace at the End of the line (more precise: is not the
first character in a line). This is useful if you want a
different indent when the '{' is at the start of the line from
when '{' is at the end of the line. (default 0).
cino= cino=e2 cino=e-2 >
if (cond) { if (cond) { if (cond) {
foo; foo; foo;
} } }
else else else
{ { {
bar; bar; bar;
} } }
<
nN Add N to the prevailing indent for a statement after an "if",
"while", etc., if it is NOT inside a set of braces. This is
useful if you want a different indent when there is no '{'
before the statement from when there is a '{' before it.
(default 0).
cino= cino=n2 cino=n-2 >
if (cond) if (cond) if (cond)
foo; foo; foo;
else else else
{ { {
bar; bar; bar;
} } }
<
fN Place the first opening brace of a function or other block in
column N. This applies only for an opening brace that is not
inside other braces and is at the start of the line. What comes
after the brace is put relative to this brace. (default 0).
cino= cino=f.5s cino=f1s >
func() func() func()
{ { {
int foo; int foo; int foo;
<
{N Place opening braces N characters from the prevailing indent.
This applies only for opening braces that are inside other
braces. (default 0).
cino= cino={.5s cino={1s >
if (cond) if (cond) if (cond)
{ { {
foo; foo; foo;
<
}N Place closing braces N characters from the matching opening
brace. (default 0).
cino= cino={2,}-0.5s cino=}2 >
if (cond) if (cond) if (cond)
{ { {
foo; foo; foo;
} } }
<
^N Add N to the prevailing indent inside a set of braces if the
opening brace is in column 0. This can specify a different
indent for whole of a function (some may like to set it to a
negative number). (default 0).
cino= cino=^-2 cino=^-s >
func() func() func()
{ { {
if (cond) if (cond) if (cond)
{ { {
a = b; a = b; a = b;
} } }
} } }
<
:N Place case labels N characters from the indent of the switch().
(default 'shiftwidth').
cino= cino=:0 >
switch (x) switch(x)
{ {
case 1: case 1:
a = b; a = b;
default: default:
} }
<
=N Place statements occurring after a case label N characters from
the indent of the label. (default 'shiftwidth').
cino= cino==10 >
case 11: case 11: a = a + 1;
a = a + 1; b = b + 1;
<
lN If N != 0 Vim will align with a case label instead of the
statement after it in the same line.
cino= cino=l1 >
switch (a) { switch (a) {
case 1: { case 1: {
break; break;
} }
<
bN If N != 0 Vim will align a final "break" with the case label,
so that case..break looks like a sort of block. (default: 0).
cino= cino=b1 >
switch (x) switch(x)
{ {
case 1: case 1:
a = b; a = b;
break; break;
default: default:
a = 0; a = 0;
break; break;
} }
<
gN Place C++ scope declarations N characters from the indent of the
block they are in. (default 'shiftwidth'). A scope declaration
can be "public:", "protected:" or "private:".
cino= cino=g0 >
{ {
public: public:
a = b; a = b;
private: private:
} }
<
hN Place statements occurring after a C++ scope declaration N
characters from the indent of the label. (default
'shiftwidth').
cino= cino=h10 >
public: public: a = a + 1;
a = a + 1; b = b + 1;
<
pN Parameter declarations for K&R-style function declarations will
be indented N characters from the margin. (default
'shiftwidth').
cino= cino=p0 cino=p2s >
func(a, b) func(a, b) func(a, b)
int a; int a; int a;
char b; char b; char b;
<
tN Indent a function return type declaration N characters from the
margin. (default 'shiftwidth').
cino= cino=t0 cino=t7 >
int int int
func() func() func()
<
iN Indent C++ base class declarations and contructor
initializations, if they start in a new line (otherwise they
are aligned at the right side of the ':').
(default 'shiftwidth').
cino= cino=i0 >
class MyClass : class MyClass :
public BaseClass public BaseClass
{} {}
MyClass::MyClass() : MyClass::MyClass() :
BaseClass(3) BaseClass(3)
{} {}
<
+N Indent a continuation line (a line that spills onto the next) N
additional characters. (default 'shiftwidth').
cino= cino=+10 >
a = b + 9 * a = b + 9 *
c; c;
<
cN Indent comment lines after the comment opener, when there is no
other text with which to align, N characters from the comment
opener. (default 3). See also |format-comments|.
cino= cino=c5 >
/* /*
text. text.
*/ */
<
CN When N is non-zero, indent comment lines by the amount specified
with the c flag above even if there is other text behind the
comment opener. (default 0).
cino=c0 cino=c0,C1 >
/******** /********
text. text.
********/ ********/
< (Example uses ":set comments& comments-=s1:/* comments^=s0:/*")
/N Indent comment lines N characters extra. (default 0).
cino= cino=/4 >
a = b; a = b;
/* comment */ /* comment */
c = d; c = d;
<
(N When in unclosed parentheses, indent N characters from the line
with the unclosed parentheses. Add a 'shiftwidth' for every
unclosed parentheses. When N is 0 or the unclosed parentheses
is the first non-white character in its line, line up with the
next non-white character after the unclosed parentheses.
(default 'shiftwidth' * 2).
cino= cino=(0 >
if (c1 && (c2 || if (c1 && (c2 ||
c3)) c3))
foo; foo;
if (c1 && if (c1 &&
(c2 || c3)) (c2 || c3))
{ {
<
uN Same as (N, but for one level deeper. (default 'shiftwidth').
cino= cino=u2 >
if (c123456789 if (c123456789
&& (c22345 && (c22345
|| c3)) || c3))
<
UN When N is non-zero, do not ignore the indenting specified by
( or u in case that the unclosed parentheses is the first
non-white character in its line. (default 0).
cino= or cino=(s cino=(s,U1 >
c = c1 && c = c1 &&
( (
c2 || c2 ||
c3 c3
) && c4; ) && c4;
<
wN When in unclosed parentheses and N is non-zero and either
using "(0" or "u0", respectively, or using "U0" and the unclosed
parentheses is the first non-white character in its line, line
up with the character immediately after the unclosed parentheses
rather than the first non-white character. (default 0).
cino=(0 cino=(0,w1 >
if ( c1 if ( c1
&& ( c2 && ( c2
|| c3)) || c3))
foo; foo;
<
WN When in unclosed parentheses and N is non-zero and either
using "(0" or "u0", respectively and the unclosed parentheses is
the last non-white character in its line and it is not the
closing parentheses, indent the following line N characters
relative to the outer context (i.e. start of the line or the
next unclosed parentheses). (default: 0).
cino=(0 cino=(0,W4 >
a_long_line( a_long_line(
argument, argument,
argument); argument);
a_short_line(argument, a_short_line(argument,
argument); argument);
<
mN When N is non-zero, line up a line starting with a closing
parentheses with the first character of the line with the
matching opening parentheses. (default 0).
cino=(s cino=(s,m1 >
c = c1 && ( c = c1 && (
c2 || c2 ||
c3 c3
) && c4; ) && c4;
if ( if (
c1 && c2 c1 && c2
) )
foo; foo;
<
*java-cinoptions* *java-indenting*
jN Indent java anonymous classes correctly. The value 'N' is
currently unused but must be non-zero (e.g. 'j1'). 'j1' will
indent for example the following code snippet correctly: >
object.add(new ChangeListener() {
public void stateChanged(ChangeEvent e) {
do_something();
}
});
<
)N Vim searches for unclosed parentheses at most N lines away.
This limits the time needed to search for parentheses. (default
20 lines).
*N Vim searches for unclosed comments at most N lines away. This
limits the time needed to search for the start of a comment.
(default 30 lines).
The defaults, spelled out in full, are:
cinoptions=>s,e0,n0,f0,{0,}0,^0,:s,=s,l0,gs,hs,ps,ts,+s,c3,C0,(2s,us,
\U0,w0,m0,j0,)20,*30
Vim puts a line in column 1 if:
- It starts with '#' (preprocessor directives), if 'cinkeys' contains '#'.
- It starts with a label (a keyword followed by ':', other than "case" and
"default").
- Any combination of indentations causes the line to have less than 0
indentation.
==============================================================================
2. Indenting by expression *indent-expression*
The basics for using flexible indenting are explained in section |30.3| of the
user manual.
If you want to write your own indent file, it must set the 'indentexpr'
option. Setting the 'indentkeys' option is often useful. See the
$VIMRUNTIME/indent directory for examples.
REMARKS ABOUT SPECIFIC INDENT FILES ~
FORTRAN *fortran-indent*
Block if, select case, and where constructs are indented. Comments, labelled
statements and continuation lines are indented if the Fortran is in free
source form, whereas they are not indented if the Fortran is in fixed source
form because of the left margin requirements. Hence manual indent corrections
will be necessary for labelled statements and continuation lines when fixed
source form is being used. For further discussion of the method used for the
detection of source format see |fortran-syntax|.
Do loops ~
All do loops are left unindented by default. Do loops can be unstructured in
Fortran with (possibly multiple) loops ending on a labelled executable
statement of almost arbitrary type. Correct indentation requires
compiler-quality parsing. Old code with do loops ending on labelled statements
of arbitrary type can be indented with elaborate programs such as Tidy
(http://www.unb.ca/chem/ajit/f_tidy.htm). Structured do/continue loops are
also left unindented because continue statements are also used for purposes
other than ending a do loop. Programs such as Tidy can convert structured
do/continue loops to the do/enddo form. Do loops of the do/enddo variety can
be indented. If you use only structured loops of the do/enddo form, you should
declare this by setting the fortran_do_enddo variable in your .vimrc as
follows >
let fortran_do_enddo=1
in which case do loops will be indented. If all your loops are of do/enddo
type only in, say, .f90 files, then you should set a buffer flag with an
autocommand such as >
au! BufRead,BufNewFile *.f90 let b:fortran_do_enddo=1
to get do loops indented in .f90 files and left alone in Fortran files with
other extensions such as .for.
VERILOG *verilog-indent*
General block statements such as if, for, case, always, initial, function,
specify and begin, etc., are indented. The module block statements (first
level blocks) are not indented by default. you can turn on the indent with
setting a variable in the .vimrc as follows: >
let b:verilog_indent_modules = 1
then the module blocks will be indented. To stop this, remove the variable: >
:unlet b:verilog_indent_modules
To set the variable only for Verilog file. The following statements can be
used: >
au BufReadPost * if exists("b:current_syntax")
au BufReadPost * if b:current_syntax == "verilog"
au BufReadPost * let b:verilog_indent_modules = 1
au BufReadPost * endif
au BufReadPost * endif
Furthermore, setting the variable b:verilog_indent_width to change the
indenting width (default is 'shiftwidth'): >
let b:verilog_indent_width = 4
let b:verilog_indent_width = &sw * 2
In addition, you can turn the verbose mode for debug issue: >
let b:verilog_indent_verbose = 1
Make sure to do ":set cmdheight=2" first to allow the display of the message.
vim:tw=78:ts=8:ft=help:norl:

1423
runtime/doc/index.txt Normal file
View File

File diff suppressed because it is too large Load Diff

1064
runtime/doc/insert.txt Normal file
View File

File diff suppressed because it is too large Load Diff

890
runtime/doc/intro.txt Normal file
View File

@@ -0,0 +1,890 @@
*intro.txt* For Vim version 7.0aa. Last change: 2004 Jun 12
VIM REFERENCE MANUAL by Bram Moolenaar
Introduction to Vim *ref* *reference*
1. Introduction |intro|
2. Vim on the internet |internet|
3. Credits |credits|
4. Notation |notation|
5. Modes, introduction |vim-modes-intro|
6. Switching from mode to mode |mode-switching|
7. The window contents |window-contents|
8. Definitions |definitions|
==============================================================================
1. Introduction *intro*
Vim stands for Vi IMproved. It used to be Vi IMitation, but there are so many
improvements that a name change was appropriate. Vim is a text editor which
includes almost all the commands from the Unix program "Vi" and a lot of new
ones. It is very useful for editing programs and other plain text.
All commands are given with the keyboard. This has the advantage that you
can keep your fingers on the keyboard and your eyes on the screen. For those
who want it, there is mouse support and a GUI version with scrollbars and
menus (see |gui.txt|).
An overview of this manual can be found in the file "help.txt", |help.txt|.
It can be accessed from within Vim with the <Help> or <F1> key and with the
|:help| command (just type ":help", without the bars or quotes).
The 'helpfile' option can be set to the name of the help file, in case it
is not located in the default place. You can jump to subjects like with tags:
Use CTRL-] to jump to a subject under the cursor, use CTRL-T to jump back.
Throughout this manual the differences between Vi and Vim are mentioned in
curly braces, like this: {Vi does not have on-line help}. See |vi_diff.txt|
for a summary of the differences between Vim and Vi.
This manual refers to Vim on various machines. There may be small differences
between different computers and terminals. Besides the remarks given in this
document, there is a separate document for each supported system, see
|sys-file-list|.
This manual is a reference for all the Vim commands and options. This is not
an introduction to the use of Vi or Vim, it gets a bit complicated here and
there. For beginners, there is a hands-on |tutor|. To learn using Vim, read
the user manual |usr_toc.txt|.
*book*
There are many books on Vi that contain a section for beginners. There are
two books I can recommend:
"Vim - Vi Improved" by Steve Oualline
This is the very first book completely dedicated to Vim. It is very good for
beginners. The most often used commands are explained with pictures and
examples. The less often used commands are also explained, the more advanced
features are summarized. There is a comprehensive index and a quick
reference. Parts of this book have been included in the user manual
|frombook|.
Published by New Riders Publishing. ISBN: 0735710015
For more information try one of these:
http://iccf-holland.org/click5.html
http://www.vim.org/iccf/click5.html
"Learning the Vi editor" by Linda Lamb and Arnold Robbins
This is a book about Vi that includes a chapter on Vim (in the sixth edition).
The first steps in Vi are explained very well. The commands that Vim adds are
only briefly mentioned. There is also a German translation.
Published by O'Reilly. ISBN: 1-56592-426-6.
==============================================================================
2. Vim on the internet *internet*
*www* *faq* *FAQ* *distribution* *download*
The Vim pages contain the most recent information about Vim. They also
contain links to the most recent version of Vim. The FAQ is a list of
Frequently Asked Questions. Read this if you have problems.
VIM home page: http://www.vim.org/
VIM FAQ: http://vimdoc.sf.net/
Downloading: ftp://ftp.vim.org/pub/vim/MIRRORS
Usenet News group where Vim is discussed: *news* *usenet*
comp.editors
This group is also for other editors. If you write about Vim, don't forget to
mention that.
*mail-list* *maillist*
There are several mailing lists for Vim:
<vim@vim.org>
For discussions about using existing versions of Vim: Useful mappings,
questions, answers, where to get a specific version, etc.
<vim-dev@vim.org> *vim-dev* *vimdev*
For discussions about changing Vim: New features, porting, patches,
beta-test versions, etc.
<vim-announce@vim.org> *vim-announce*
Announcements about new versions of Vim; also for beta-test versions
and ports to different systems.
<vim-multibyte@vim.org> *vim-multibyte*
For discussions about using and improving the multi-byte aspects of
Vim.
<vim-mac@vim.org> *vim-mac*
For discussions about using and improving the Macintosh version of
Vim.
See http://www.vim.org/maillist.php for the latest information.
NOTE:
- You can only send messages to these lists if you have subscribed!
- You need to send the messages from the same location as where you subscribed
from (to avoid spam mail).
- Maximum message size is 40000 characters.
*subscribe-maillist*
If you want to join, send a message to
<vim-help@vim.org>
Make sure that your "From:" address is correct. Then the list server will
give you help on how to subscribe.
You can retrieve old messages from the maillist software, and an index of
messages. Ask vim-help for instructions.
Archives are kept at: *maillist-archive*
http://groups.yahoo.com/group/vim
http://groups.yahoo.com/group/vimdev
http://groups.yahoo.com/group/vimannounce
http://groups.yahoo.com/group/vim-multibyte
http://groups.yahoo.com/group/vim-mac
Additional maillists:
<vim-fr@club.voila.fr> *french-maillist*
Vim list in the French language. Subscribe by sending a message to
<vim-fr-subscribe@club.voila.fr>
Or go to http://groups.yahoo.com/group/vim-fr.
Bug reports: *bugs* *bug-reports* *bugreport.vim*
Send bug reports to: Vim bugs <bugs@vim.org>
This is not a maillist but the message is redirected to the Vim maintainer.
Please be brief; all the time that is spent on answering mail is subtracted
from the time that is spent on improving Vim! Always give a reproducible
example and try to find out which settings or other things influence the
appearance of the bug. Try different machines, if possible. Send me patches
if you can!
In case of doubt, use: >
:so $VIMRUNTIME/bugreport.vim
This will create a file "bugreport.txt" in the current directory, with a lot
of information of your environment. Before sending this out, check if it
doesn't contain any confidential information!
*debug-vim*
When Vim crashes in one of the test files, and you are using gcc for
compilation, here is what you can do to find out exactly where Vim crashes:
1. Compile Vim with the "-g" option (there is a line in the Makefile for this,
which you can uncomment).
2. Execute these commands (replace "11" with the test that fails): >
cd testdir
gdb ../vim
run -u unix.vim -U NONE -s dotest.in test11.in
3. Check where Vim crashes, gdb should give a message for this.
4. Get a stack trace from gdb with this command: >
where
< You can check out different places in the stack trace with: >
frame 3
< Replace "3" with one of the numbers in the stack trace.
*year-2000* *Y2K*
Since Vim internally doesn't use dates for editing, there is no year 2000
problem to worry about. Vim does use the time in the form of seconds since
January 1st 1970. It is used for a time-stamp check of the edited file and
the swap file, which is not critical and should only cause warning messages.
There might be a year 2038 problem, when the seconds don't fit in a 32 bit int
anymore. This depends on the compiler, libraries and operating system.
Specifically, time_t and the ctime() function are used. And the time_t is
stored in four bytes in the swap file. But that's only used for printing a
file date/time for recovery, it will never affect normal editing.
The Vim strftime() function directly uses the strftime() system function.
localtime() uses the time() system function. getftime() uses the time
returned by the stat() system function. If your system libraries are year
2000 compliant, Vim is too.
The user may create scripts for Vim that use external commands. These might
introduce Y2K problems, but those are not really part of Vim itself.
==============================================================================
3. Credits *credits* *author*
Most of Vim was written by Bram Moolenaar <Bram@vim.org>.
Parts of the documentation come from several Vi manuals, written by:
W.N. Joy
Alan P.W. Hewett
Mark Horton
The Vim editor is based on Stevie and includes (ideas from) other software,
worked on by the people mentioned here. Other people helped by sending me
patches, suggestions and giving feedback about what is good and bad in Vim.
Vim would never have become what it is now, without the help of these people!
Ron Aaron Win32 GUI changes
Zoltan Arpadffy work on VMS port
Tony Andrews Stevie
Gert van Antwerpen changes for DJGPP on MS-DOS
Berkeley DB(3) ideas for swap file implementation
Keith Bostic Nvi
Walter Briscoe Makefile updates, various patches
Ralf Brown SPAWNO library for MS-DOS
Robert Colon many useful remarks
Marcin Dalecki GTK+ GUI port, toolbar icons, gettext()
Kayhan Demirel sent me news in Uganda
Chris & John Downey xvi (ideas for multi-windows version)
Henk Elbers first VMS port
Eric Fischer Mac port, 'cindent', and other improvements
Benji Fisher Answering lots of user questions
Bill Foster Athena GUI port
Loic Grenie xvim (ideas for multi windows version)
Sven Guckes Vim promotor and previous WWW page maintainer
Darren Hiebert Exuberant ctags
Bruce Hunsaker improvements for VMS port
Andy Kahn Cscope support, GTK+ GUI port
Oezguer Kesim Maintainer of Vim Mailing Lists
Axel Kielhorn work on the Macintosh port
Steve Kirkendall Elvis
Roger Knobbe original port to Windows NT
Sergey Laskavy Vim's help from Moscow
Felix von Leitner Maintainer of Vim Mailing Lists
David Leonard Port of Python extensions to Unix
Avner Lottem Edit in right-to-left windows
Flemming Madsen X11 client-server, various features and patches
MicroSoft Gave me a copy of DevStudio to compile Vim with
Paul Moore Python interface extensions, many patches
Katsuhito Nagano Work on multi-byte versions
Sung-Hyun Nam Work on multi-byte versions
Vince Negri Win32 GUI and generic console enhancements
Steve Oualline Author of the first Vim book |frombook|
George V. Reilly Win32 port, Win32 GUI start-off
Stephen Riehm bug collector
Stefan Roemer various patches and help to users
Ralf Schandl IBM OS/390 port
Olaf Seibert DICE and BeBox version, regexp improvements
Mortaza Shiran Farsi patches
Peter da Silva termlib
Paul Slootman OS/2 port
Henry Spencer regular expressions
Dany St-Amant Macintosh port
Tim Thompson Stevie
G. R. (Fred) Walter Stevie
Sven Verdoolaege Perl interface
Robert Webb Command-line completion, GUI versions, and
lots of patches
Ingo Wilken Tcl interface
Mike Williams PostScript printing
Juergen Weigert Lattice version, AUX improvements, UNIX and
MS-DOS ports, autoconf
Stefan 'Sec' Zehl Maintainer of vim.org
I wish to thank all the people that sent me bug reports and suggestions. The
list is too long to mention them all here. Vim would not be the same without
the ideas from all these people: They keep Vim alive!
In this documentation there are several references to other versions of Vi:
*Vi*
Vi "the original". Without further remarks this is the version
of Vi that appeared in Sun OS 4.x. ":version" returns
"Version 3.7, 6/7/85". Sometimes other versions are referred
to. Only runs under Unix. Source code only available with a
license. More information on Vi can be found through:
http://vi-editor.org [doesn't currently work...]
*Posix*
Posix From the IEEE standard 1003.2, Part 2: Shell and utilities.
Generally known as "Posix". This is a textual description of
how Vi is supposed to work.
The version used is a draft from beginning 1996, so all remarks are
"expected to comply to" this. Anything can change though...
*Nvi*
Nvi The "New" Vi. The version of Vi that comes with BSD 4.4 and FreeBSD.
Very good compatibility with the original Vi, with a few extensions.
The version used is 1.79. ":version" returns "Version 1.79
(10/23/96)". There has been no release the last few years, although
there is a development version 1.81.
Source code is freely available.
*Elvis*
Elvis Another Vi clone, made by Steve Kirkendall. Very compact but isn't
as flexible as Vim.
The version used is 2.1. It is still being developed. Source code is
freely available.
==============================================================================
4. Notation *notation*
When syntax highlighting is used to read this, text that is not typed
literally is often highlighted with the Special group. These are items in [],
{} and <>, and CTRL-X.
Note that Vim uses all possible characters in commands. Sometimes the [], {}
and <> are part of what you type, the context should make this clear.
[] Characters in square brackets are optional.
*count* *[count]* *E489*
[count] An optional number that may precede the command to multiply
or iterate the command. If no number is given, a count of one
is used, unless otherwise noted. Note that in this manual the
[count] is not mentioned in the description of the command,
but only in the explanation. This was done to make the
commands easier to look up. If the 'showcmd' option is on,
the (partially) entered count is shown at the bottom of the
window. You can use <Del> to erase the last digit (|N<Del>|).
*[quotex]*
["x] An optional register designation where text can be stored.
See |registers|. The x is a single character between 'a' and
'z' or 'A' and 'Z' or '"', and in some cases (with the put
command) between '0' and '9', '%', '#', or others. The
uppercase and lowercase letter designate the same register,
but the lowercase letter is used to overwrite the previous
register contents, while the uppercase letter is used to
append to the previous register contents. Without the ""x" or
with """" the stored text is put into the unnamed register.
*{}*
{} Curly braces denote parts of the command which must appear,
but which can take a number of different values. The
differences between Vim and Vi are also given in curly braces
(this will be clear from the context).
*{char1-char2}*
{char1-char2} A single character from the range char1 to char2. For
example: {a-z} is a lowercase letter. Multiple ranges may be
concatenated. For example, {a-zA-Z0-9} is any alphanumeric
character.
*{motion}*
{motion} A command that moves the cursor. These are explained in
|motion.txt|. Examples:
w to start of next word
b to begin of current word
4j four lines down
/The<CR> to next occurrence of "The"
This is used after an |operator| command to move over the text
that is to be operated upon.
- If the motion includes a count and the operator also has a
count, the two counts are multiplied. For example: "2d3w"
deletes six words.
- The motion can be backwards, e.g. "db" to delete to the
start of the word.
- The motion can also be a mouse click. The mouse is not
supported in every terminal though.
- The ":omap" command can be used to map characters while an
operator is pending.
- Ex commands can be used to move the cursor. This can be
used to call a function that does some complicated motion.
The motion is always characterwise exclusive, no matter
what ":" command is used. This means it's impossible to
include the last character of a line without the line break
(unless 'virtualedit' is set).
If the Ex command changes the text before where the operator
starts or jumps to another buffer the result is
unpredictable. It is possible to change the text further
down. Jumping to another buffer is possible if the current
buffer is not unloaded.
*{Visual}*
{Visual} A selected text area. It is started with the "v", "V", or
CTRL-V command, then any cursor movement command can be used
to change the end of the selected text.
This is used before an |operator| command to highlight the
text that is to be operated upon.
See |Visual-mode|.
*<character>*
<character> A special character from the table below, optionally with
modifiers, or a single ASCII character with modifiers.
*'character'*
'c' A single ASCII character.
*CTRL-{char}*
CTRL-{char} {char} typed as a control character; that is, typing {char}
while holding the CTRL key down. The case of {char} does not
matter; thus CTRL-A and CTRL-a are equivalent. But on some
terminals, using the SHIFT key will produce another code,
don't use it then.
*'option'*
'option' An option, or parameter, that can be set to a value, is
enclosed in single quotes. See |options|.
*quotecommandquote*
"command" A reference to a command that you can type is enclosed in
double quotes.
*key-notation* *key-codes* *keycodes*
These names for keys are used in the documentation. They can also be used
with the ":map" command (insert the key name by pressing CTRL-K and then the
key you want the name for).
notation meaning equivalent decimal value(s) ~
-----------------------------------------------------------------------
<Nul> zero CTRL-@ 0 (stored as 10) *<Nul>*
<BS> backspace CTRL-H 8 *backspace*
<Tab> tab CTRL-I 9 *tab* *Tab*
*linefeed*
<NL> linefeed CTRL-J 10 (used for <Nul>)
<FF> formfeed CTRL-L 12 *formfeed*
<CR> carriage return CTRL-M 13 *carriage-return*
<Return> same as <CR> *<Return>*
<Enter> same as <CR> *<Enter>*
<Esc> escape CTRL-[ 27 *escape* *<Esc>*
<Space> space 32 *space*
<lt> less-than < 60 *<lt>*
<Bslash> backslash \ 92 *backslash* *<Bslash>*
<Bar> vertical bar | 124 *<Bar>*
<Del> delete 127
<CSI> command sequence intro ALT-Esc 155 *<CSI>*
<xCSI> CSI when typed in the GUI *<xCSI>*
<EOL> end-of-line (can be <CR>, <LF> or <CR><LF>,
depends on system and 'fileformat') *<EOL>*
<Up> cursor-up *cursor-up* *cursor_up*
<Down> cursor-down *cursor-down* *cursor_down*
<Left> cursor-left *cursor-left* *cursor_left*
<Right> cursor-right *cursor-right* *cursor_right*
<S-Up> shift-cursor-up
<S-Down> shift-cursor-down
<S-Left> shift-cursor-left
<S-Right> shift-cursor-right
<C-Left> control-cursor-left
<C-Right> control-cursor-right
<F1> - <F12> function keys 1 to 12 *function_key* *function-key*
<S-F1> - <S-F12> shift-function keys 1 to 12 *<S-F1>*
<Help> help key
<Undo> undo key
<Insert> insert key
<Home> home *home*
<End> end *end*
<PageUp> page-up *page_up* *page-up*
<PageDown> page-down *page_down* *page-down*
<kHome> keypad home (upper left) *keypad-home*
<kEnd> keypad end (lower left) *keypad-end*
<kPageUp> keypad page-up (upper right) *keypad-page-up*
<kPageDown> keypad page-down (lower right) *keypad-page-down*
<kPlus> keypad + *keypad-plus*
<kMinus> keypad - *keypad-minus*
<kMultiply> keypad * *keypad-multiply*
<kDivide> keypad / *keypad-divide*
<kEnter> keypad Enter *keypad-enter*
<kPoint> keypad Decimal point *keypad-point*
<k0> - <k9> keypad 0 to 9 *keypad-0* *keypad-9*
<S-...> shift-key *shift* *<S-*
<C-...> control-key *control* *ctrl* *<C-*
<M-...> alt-key or meta-key *meta* *alt* *<M-*
<A-...> same as <M-...> *<A-*
<D-...> command-key (Macintosh only) *<D-*
<t_xx> key with "xx" entry in termcap
-----------------------------------------------------------------------
Note: The shifted cursor keys, the help key, and the undo key are only
available on a few terminals. On the Amiga, shifted function key 10 produces
a code (CSI) that is also used by key sequences. It will be recognized only
after typing another key.
Note: There are two codes for the delete key. 127 is the decimal ASCII value
for the delete key, which is always recognized. Some delete keys send another
value, in which case this value is obtained from the termcap entry "kD". Both
values have the same effect. Also see |:fixdel|.
Note: The keypad keys are used in the same way as the corresponding "normal"
keys. For example, <kHome> has the same effect as <Home>. If a keypad key
sends the same raw key code as its non-keypad equivalent, it will be
recognized as the non-keypad code. For example, when <kHome> sends the same
code as <Home>, when pressing <kHome> Vim will think <Home> was pressed.
Mapping <kHome> will not work then.
*<>*
Examples are often given in the <> notation. Sometimes this is just to make
clear what you need to type, but often it can be typed literally, e.g., with
the ":map" command. The rules are:
1. Any printable characters are typed directly, except backslash and '<'
2. A backslash is represented with "\\", double backslash, or "<Bslash>".
3. A real '<' is represented with "\<" or "<lt>". When there is no
confusion possible, a '<' can be used directly.
4. "<key>" means the special key typed. This is the notation explained in
the table above. A few examples:
<Esc> Escape key
<C-G> CTRL-G
<Up> cursor up key
<C-LeftMouse> Control- left mouse click
<S-F11> Shifted function key 11
<M-a> Meta- a ('a' with bit 8 set)
<M-A> Meta- A ('A' with bit 8 set)
<t_kd> "kd" termcap entry (cursor down key)
If you want to use the full <> notation in Vim, you have to make sure the '<'
flag is excluded from 'cpoptions' (when 'compatible' is not set, it already is
by default). >
:set cpo-=<
The <> notation uses <lt> to escape the special meaning of key names. Using a
backslash also works, but only when 'cpoptions' does not include the 'B' flag.
Examples for mapping CTRL-H to the six characters "<Home>": >
:imap <C-H> \<Home>
:imap <C-H> <lt>Home>
The first one only works when the 'B' flag is not in 'cpoptions'. The second
one always works.
To get a literal "<lt>" in a mapping: >
:map <C-L> <lt>lt>
For mapping, abbreviation and menu commands you can then copy-paste the
examples and use them directly. Or type them literally, including the '<' and
'>' characters. This does NOT work for other commands, like ":set" and
":autocmd"!
==============================================================================
5. Modes, introduction *vim-modes-intro* *vim-modes*
Vim has six BASIC modes:
*Normal* *Normal-mode* *command-mode*
Normal mode In Normal mode you can enter all the normal editor
commands. If you start the editor you are in this
mode (unless you have set the 'insertmode' option,
see below). This is also known as command mode.
Visual mode This is like Normal mode, but the movement commands
extend a highlighted area. When a non-movement
command is used, it is executed for the highlighted
area. See |Visual-mode|.
If the 'showmode' option is on "-- VISUAL --" is shown
at the bottom of the window.
Select mode This looks most like the MS-Windows selection mode.
Typing a printable character deletes the selection
and starts Insert mode. See |Select-mode|.
If the 'showmode' option is on "-- SELECT --" is shown
at the bottom of the window.
Insert mode In Insert mode the text you type is inserted into the
buffer. See |Insert-mode|.
If the 'showmode' option is on "-- INSERT --" is shown
at the bottom of the window.
Command-line mode In Command-line mode (also called Cmdline mode) you
Cmdline mode can enter one line of text at the bottom of the
window. This is for the Ex commands, ":", the pattern
search commands, "?" and "/", and the filter command,
"!". |Cmdline-mode|
Ex mode Like Command-line mode, but after entering a command
you remain in Ex mode. Very limited editing of the
command line. |Ex-mode|
There are five ADDITIONAL modes. These are variants of the BASIC modes:
*Operator-pending* *Operator-pending-mode*
Operator-pending mode This is like Normal mode, but after an operator
command has started, and Vim is waiting for a {motion}
to specify the text that the operator will work on.
Replace mode Replace mode is a special case of Insert mode. You
can do the same things as in Insert mode, but for
each character you enter, one character of the existing
text is deleted. See |Replace-mode|.
If the 'showmode' option is on "-- REPLACE --" is
shown at the bottom of the window.
Insert Normal mode Entered when CTRL-O given in Insert mode. This is
like Normal mode, but after executing one command Vim
returns to Insert mode.
If the 'showmode' option is on "-- (insert) --" is
shown at the bottom of the window.
Insert Visual mode Entered when starting a Visual selection from Insert
mode, e.g., by using CTRL-O and then "v", "V" or
CTRL-V. When the Visual selection ends, Vim returns
to Insert mode.
If the 'showmode' option is on "-- (insert) VISUAL --"
is shown at the bottom of the window.
Insert Select mode Entered when starting Select mode from Insert mode.
E.g., by dragging the mouse or <S-Right>.
When the Select mode ends, Vim returns to Insert mode.
If the 'showmode' option is on "-- (insert) SELECT --"
is shown at the bottom of the window.
==============================================================================
6. Switching from mode to mode *mode-switching*
If for any reason you do not know which mode you are in, you can always get
back to Normal mode by typing <Esc> twice. This doesn't work for Ex mode
though, use ":visual".
You will know you are back in Normal mode when you see the screen flash or
hear the bell after you type <Esc>. However, when pressing <Esc> after using
CTRL-O in Insert mode you get a beep but you are still in Insert mode, type
<Esc> again.
*i_esc*
TO mode ~
Normal Visual Select Insert Replace Cmd-line Ex ~
FROM mode ~
Normal v V ^V *4 *1 R : / ? ! Q
Visual *2 ^G c C -- : --
Select *5 ^O ^G *6 -- -- --
Insert <Esc> -- -- <Insert> -- --
Replace <Esc> -- -- <Insert> -- --
Command-line *3 -- -- :start -- --
Ex :vi -- -- -- -- --
- NA
-- not possible
*1 Go from Normal mode to Insert mode by giving the command "i", "I", "a",
"A", "o", "O", "c", "C", "s" or S".
*2 Go from Visual mode to Normal mode by giving a non-movement command, which
causes the command to be executed, or by hitting <Esc> "v", "V" or "CTRL-V"
(see |v_v|), which just stops Visual mode without side effects.
*3 Go from Command-line mode to Normal mode by:
- Hitting <CR> or <NL>, which causes the entered command to be executed.
- Deleting the complete line (e.g., with CTRL-U) and giving a final <BS>.
- Hitting CTRL-C or <Esc>, which quits the command-line without executing
the command.
In the last case <Esc> may be the character defined with the 'wildchar'
option, in which case it will start command-line completion. You can
ignore that and type <Esc> again. {Vi: when hitting <Esc> the command-line
is executed. This is unexpected for most people; therefore it was changed
in Vim. But when the <Esc> is part of a mapping, the command-line is
executed. If you want the Vi behaviour also when typing <Esc>, use ":cmap
^V<Esc> ^V^M"}
*4 Go from Normal to Select mode by:
- use the mouse to select text while 'selectmode' contains "mouse"
- use a non-printable command to move the cursor while keeping the Shift
key pressed, and the 'selectmode' option contains "key"
- use "v", "V" or "CTRL-V" while 'selectmode' contains "cmd"
- use "gh", "gH" or "g CTRL-H" |g_CTRL-H|
*5 Go from Select mode to Normal mode by using a non-printable command to move
the cursor, without keeping the Shift key pressed.
*6 Go from Select mode to Insert mode by typing a printable character. The
selection is deleted and the character is inserted.
If the 'insertmode' option is on, editing a file will start in Insert mode.
*CTRL-\_CTRL-N* *i_CTRL-\_CTRL-N* *c_CTRL-\_CTRL-N* *v_CTRL-\_CTRL-N*
Additionally the command CTRL-\ CTRL-N or <C-\><C-N> can be used to go to
Normal mode from any other mode. This can be used to make sure Vim is in
Normal mode, without causing a beep like <Esc> would. However, this does not
work in Ex mode. When used after a command that takes an argument, such as
|f| or |m|, the timeout set with 'ttimeoutlen' applies.
*CTRL-\_CTRL-G* *i_CTRL-\_CTRL-G* *c_CTRL-\_CTRL-G* *v_CTRL-\_CTRL-G*
The command CTRL-\ CTRL-G or <C-\><C-G> can be used to go to Insert mode when
'insertmode' is set. Otherwise it goes to Normal mode. This can be used to
make sure Vim is in the mode indicated by 'insertmode', without knowing in
what mode Vim currently is.
*Q* *mode-Ex* *Ex-mode* *Ex* *EX* *E501*
Q Switch to "Ex" mode. This is a bit like typing ":"
commands one after another, except:
- You don't have to keep pressing ":".
- The screen doesn't get updated after each command.
- There is no normal command-line editing.
- Mappings and abbreviations are not used.
In fact, you are editing the lines with the "standard"
line-input editing commands (<Del> or <BS> to erase,
CTRL-U to kill the whole line).
Vim will enter this mode by default if it's invoked as
"ex" on the command-line.
Use the ":vi" command |:visual| to exit "Ex" mode.
Note: In older versions of Vim "Q" formatted text,
that is now done with |gq|. But if you use the
|vimrc_example.vim| script "Q" works like "gq".
*gQ*
gQ Switch to "Ex" mode, but really behave like typing ":"
commands after another. All command line editing,
completion etc. is available.
Use the ":vi" command |:visual| to exit "Ex" mode.
{not in Vi}
==============================================================================
7. The window contents *window-contents*
In Normal mode and Insert/Replace mode the screen window will show the current
contents of the buffer: What You See Is What You Get. There are two
exceptions:
- When the 'cpoptions' option contains '$', and the change is within one line,
the text is not directly deleted, but a '$' is put at the last deleted
character.
- When inserting text in one window, other windows on the same text are not
updated until the insert is finished.
{Vi: The screen is not always updated on slow terminals}
Lines longer than the window width will wrap, unless the 'wrap' option is off
(see below). The 'linebreak' option can be set to wrap at a blank character.
If the window has room after the last line of the buffer, Vim will show '~' in
the first column of the last lines in the window, like this: >
+-----------------------+
|some line |
|last line |
|~ |
|~ |
+-----------------------+
Thus the '~' lines indicate that the end of the buffer was reached.
If the last line in a window doesn't fit, Vim will indicate this with a '@' in
the first column of the last lines in the window, like this: >
+-----------------------+
|first line |
|second line |
|@ |
|@ |
+-----------------------+
Thus the '@' lines indicate that there is a line that doesn't fit in the
window.
When the "lastline" flag is present in the 'display' option, you will not see
'@' characters at the left side of window. If the last line doesn't fit
completely, only the part that fits is shown, and the last three characters of
the last line are replaced with "@@@", like this: >
+-----------------------+
|first line |
|second line |
|a very long line that d|
|oesn't fit in the wi@@@|
+-----------------------+
If there is a single line that is too long to fit in the window, this is a
special situation. Vim will show only part of the line, around where the
cursor is. There are no special characters shown, so that you can edit all
parts of this line.
{Vi: gives an "internal error" on lines that do not fit in the window}
The '@' occasion in the 'highlight' option can be used to set special
highlighting for the '@' and '~' characters. This makes it possible to
distinguish them from real characters in the buffer.
The 'showbreak' option contains the string to put in front of wrapped lines.
*wrap-off*
If the 'wrap' option is off, long lines will not wrap. Only the part that
fits on the screen is shown. If the cursor is moved to a part of the line
that is not shown, the screen is scrolled horizontally. The advantage of
this method is that columns are shown as they are and lines that cannot fit
on the screen can be edited. The disadvantage is that you cannot see all the
characters of a line at once. The 'sidescroll' option can be set to the
minimal number of columns to scroll. {Vi: has no 'wrap' option}
All normal ASCII characters are displayed directly on the screen. The <Tab>
is replaced with the number of spaces that it represents. Other non-printing
characters are replaced with "^{char}", where {char} is the non-printing
character with 64 added. Thus character 7 (bell) will be shown as "^G".
Characters between 127 and 160 are replaced with "~{char}", where {char} is
the character with 64 subtracted. These characters occupy more than one
position on the screen. The cursor can only be positioned on the first one.
If you set the 'number' option, all lines will be preceded with their
number. Tip: If you don't like wrapping lines to mix with the line numbers,
set the 'showbreak' option to eight spaces:
":set showbreak=\ \ \ \ \ \ \ \ "
If you set the 'list' option, <Tab> characters will not be shown as several
spaces, but as "^I". A '$' will be placed at the end of the line, so you can
find trailing blanks.
In Command-line mode only the command-line itself is shown correctly. The
display of the buffer contents is updated as soon as you go back to Command
mode.
The last line of the window is used for status and other messages. The
status messages will only be used if an option is on:
status message option default Unix default ~
current mode 'showmode' on on
command characters 'showcmd' on off
cursor position 'ruler' off off
The current mode is "-- INSERT --" or "-- REPLACE --", see |'showmode'|. The
command characters are those that you typed but were not used yet. {Vi: does
not show the characters you typed or the cursor position}
If you have a slow terminal you can switch off the status messages to speed
up editing:
:set nosc noru nosm
If there is an error, an error message will be shown for at least one second
(in reverse video). {Vi: error messages may be overwritten with other
messages before you have a chance to read them}
Some commands show how many lines were affected. Above which threshold this
happens can be controlled with the 'report' option (default 2).
On the Amiga Vim will run in a CLI window. The name Vim and the full name of
the current file name will be shown in the title bar. When the window is
resized, Vim will automatically redraw the window. You may make the window as
small as you like, but if it gets too small not a single line will fit in it.
Make it at least 40 characters wide to be able to read most messages on the
last line.
On most Unix systems, resizing the window is recognized and handled correctly
by Vim. {Vi: not ok}
==============================================================================
8. Definitions *definitions*
screen The whole area that Vim uses to work in. This can be
a terminal emulator window. Also called "the Vim
window".
window A view on a buffer.
A screen contains one or more windows, separated by status lines and with the
command line at the bottom.
+-------------------------------+
screen | window 1 | window 2 |
| | |
| | |
|= status line =|= status line =|
| window 3 |
| |
| |
|==== status line ==============|
|command line |
+-------------------------------+
The command line is also used for messages. It scrolls up the screen when
there is not enough room in the command line.
A difference is made between four types of lines:
buffer lines The lines in the buffer. This is the same as the
lines as they are read from/written to a file. They
can be thousands of characters long.
logical lines The buffer lines with folding applied. Buffer lines
in a closed fold are changed to a single logical line:
"+-- 99 lines folded". They can be thousands of
characters long.
window lines The lines displayed in a window: A range of logical
lines with wrapping, line breaks, etc. applied. They
can only be as long as the width of the window allows,
longer lines are wrapped or truncated.
screen lines The lines of the screen that Vim uses. Consists of
the window lines of all windows, with status lines
and the command line added. They can only be as long
as the width of the screen allows. When the command
line gets longer it wraps and lines are scrolled to
make room.
buffer lines logical lines window lines screen lines ~
1. one 1. one 1. +-- folded 1. +-- folded
2. two 2. +-- folded 2. five 2. five
3. three 3. five 3. six 3. six
4. four 4. six 4. seven 4. seven
5. five 5. seven 5. === status line ===
6. six 6. aaa
7. seven 7. bbb
8. ccc ccc c
1. aaa 1. aaa 1. aaa 9. cc
2. bbb 2. bbb 2. bbb 10. ddd
3. ccc ccc ccc 3. ccc ccc ccc 3. ccc ccc c 11. ~
4. ddd 4. ddd 4. cc 12. === status line ===
5. ddd 13. (command line)
6. ~
==============================================================================
vim:tw=78:ts=8:ft=help:norl:

780
runtime/doc/makehtml.awk Normal file
View File

@@ -0,0 +1,780 @@
BEGIN {
# some initialization variables
asciiart="no";
wasset="no";
lineset=0;
sample="no";
while ( getline ti <"tags.ref" > 0 ) {
nf=split(ti,tag," ");
tagkey[tag[1]]="yes";tagref[tag[1]]=tag[2];
}
skip_word["and"]="yes";
skip_word["backspace"]="yes";
skip_word["beep"]="yes";
skip_word["bugs"]="yes";
skip_word["da"]="yes";
skip_word["end"]="yes";
skip_word["ftp"]="yes";
skip_word["go"]="yes";
skip_word["help"]="yes";
skip_word["home"]="yes";
skip_word["news"]="yes";
skip_word["index"]="yes";
skip_word["insert"]="yes";
skip_word["into"]="yes";
skip_word["put"]="yes";
skip_word["reference"]="yes";
skip_word["section"]="yes";
skip_word["space"]="yes";
skip_word["starting"]="yes";
skip_word["toggle"]="yes";
skip_word["various"]="yes";
skip_word["version"]="yes";
skip_word["is"]="yes";
}
#
# protect special chars
#
/[><&á]/ {gsub(/&/,"\\&amp;");gsub(/>/,"\\&gt;");gsub(/</,"\\&lt;");gsub("á","\\&aacute;");}
#
# end of sample lines by non-blank in first column
#
sample == "yes" && substr($0,1,4) == "&lt;" { sample = "no"; gsub(/^&lt;/, " "); }
sample == "yes" && substr($0,1,1) != " " && substr($0,1,1) != " " && length($0) > 0 { sample = "no" }
#
# sample lines printed bold unless empty...
#
sample == "yes" && $0 =="" { print ""; next; }
sample == "yes" && $0 !="" { print "<B>" $0 "</B>"; next; }
#
# start of sample lines in next line
#
$0 == "&gt;" { sample = "yes"; print ""; next; }
substr($0,length($0)-4,5) == " &gt;" { sample = "yes"; gsub(/ &gt;$/, ""); }
#
# header lines printed bold, colored
#
substr($0,length($0),1) == "~" { print "<B><FONT COLOR=\"PURPLE\">" substr($0,1,length($0)-1) "</FONT></B>"; next; }
#
#ad hoc code
#
/^"\|\& / {gsub(/\|/,"\\&#124;"); }
/ = b / {gsub(/ b /," \\&#98; "); }
#
# one letter tag
#
/[ ]\*.\*[ ]/ {gsub(/\*/,"ZWWZ"); }
#
# isolated "*"
#
/[ ]\*[ ]/ {gsub(/ \* /," \\&#42; ");
gsub(/ \* /," \\&#42; ");
gsub(/ \* /," \\&#42; ");
gsub(/ \* /," \\&#42; "); }
#
# tag start
#
/[ ]\*[^ ]/ {gsub(/ \*/," ZWWZ");gsub(/ \*/," ZWWZ");}
/^\*[^ ]/ {gsub(/^\*/,"ZWWZ");}
#
# tag end
#
/[^ ]\*$/ {gsub(/\*$/,"ZWWZ");}
/[^ \/ ]\*[ ]/ {gsub(/\*/,"ZWWZ");}
#
# isolated "|"
#
/[ ]\|[ ]/ {gsub(/ \| /," \\&#124; ");
gsub(/ \| /," \\&#124; ");
gsub(/ \| /," \\&#124; ");
gsub(/ \| /," \\&#124; "); }
/'\|'/ { gsub(/'\|'/,"'\\&#124;'"); }
/\^V\|/ {gsub(/\^V\|/,"^V\\&#124;");}
/ \\\| / {gsub(/\|/,"\\&#124;");}
#
# one letter pipes and "||" false pipe (digraphs)
#
/[ ]\|.\|[ ]/ && asciiart == "no" {gsub(/\|/,"YXXY"); }
/^\|.\|[ ]/ {gsub(/\|/,"YXXY"); }
/\|\|/ {gsub(/\|\|/,"\\&#124;\\&#124;"); }
/^shellpipe/ {gsub(/\|/,"\\&#124;"); }
#
# pipe start
#
/[ ]\|[^ ]/ && asciiart == "no" {gsub(/ \|/," YXXY");
gsub(/ \|/," YXXY");}
/^\|[^ ]/ {gsub(/^\|/,"YXXY");}
#
# pipe end
#
/[^ ]\|$/ && asciiart == "no" {gsub(/\|$/,"YXXY");}
/[^ ]\|[s ,.); ]/ && asciiart == "no" {gsub(/\|/,"YXXY");}
/[^ ]\|]/ && asciiart == "no" {gsub(/\|/,"YXXY");}
#
# various
#
/'"/ {gsub(/'"/,"\\&#39;\\&#34;'");}
/"/ {gsub(/"/,"\\&quot;");}
/%/ {gsub(/%/,"\\&#37;");}
NR == 1 { nf=split(FILENAME,f,".")
print "<HTML>";
print "<HEAD>"
if ( FILENAME == "mbyte.txt" ) {
# needs utf-8 as uses many languages
print "<META HTTP-EQUIV=\"Content-type\" content=\"text/html; charset=UTF-8\">";
} else {
# common case - Latin1
print "<META HTTP-EQUIV=\"Content-type\" content=\"text/html; charset=ISO-8859-1\">";
}
print "<TITLE>Vim documentation: " f[1] "</TITLE>";
print "</HEAD>";
print "<BODY BGCOLOR=\"#ffffff\">";
print "<H1>Vim documentation: " f[1] "</H1>";
print "<A NAME=\"top\"></A>";
if ( FILENAME != "help.txt" ) {
print "<A HREF=\"help.html\">main help file</A>\n";
}
print "<HR>";
print "<PRE>";
filename=f[1]".html";
}
# set to a low value to test for few lines of text
# NR == 99999 { exit; }
# ignore underlines and tags
substr($0,1,5) == " vim:" { next; }
substr($0,1,4) == "vim:" { next; }
# keep just whole lines of "-", "="
substr($0,1,3) == "===" && substr($0,75,1) != "=" { next; }
substr($0,1,3) == "---" && substr($0,75,1) != "-" { next; }
{
nstar = split($0,s,"ZWWZ");
for ( i=2 ; i <= nstar ; i=i+2 ) {
nbla=split(s[i],blata,"[ ]");
if ( nbla > 1 ) {
gsub("ZWWZ","*");
nstar = split($0,s,"ZWWZ");
}
}
npipe = split($0,p,"YXXY");
for ( i=2 ; i <= npipe ; i=i+2 ) {
nbla=split(p[i],blata,"[ ]");
if ( nbla > 1 ) {
gsub("YXXY","|");
ntabs = split($0,p,"YXXY");
}
}
}
FILENAME == "gui.txt" && asciiart == "no" \
&& $0 ~ /\+----/ && $0 ~ /----\+/ {
asciiart= "yes";
asciicnt=0;
}
FILENAME == "quotes.txt" && asciiart == "no" \
&& $0 ~ /In summary:/ {
asciiart= "yes";
asciicnt=0;
}
FILENAME == "usr_20.txt" && asciiart == "no" \
&& $0 ~ /an empty line at the end:/ {
asciiart= "yes";
asciicnt=0;
}
asciiart == "yes" && $0=="" { asciicnt++; }
asciiart == "yes" && asciicnt == 2 { asciiart = "no"; }
asciiart == "yes" { npipe = 1; }
# { print NR " <=> " asciiart; }
#
# line contains "*"
#
nstar > 2 && npipe < 3 {
printf("\n");
for ( i=1; i <= nstar ; i=i+2 ) {
this=s[i];
put_this();
ii=i+1;
nbla = split(s[ii],blata," ");
if ( ii <= nstar ) {
if ( nbla == 1 && substr(s[ii],length(s[ii]),1) != " " ) {
printf("*<A NAME=\"%s\"></A>",s[ii]);
printf("<B>%s</B>*",s[ii]);
} else {
printf("*%s*",s[ii]);
}
}
}
printf("\n");
next;
}
#
# line contains "|"
#
npipe > 2 && nstar < 3 {
if ( npipe%2 == 0 ) {
for ( i=1; i < npipe ; i++ ) {
gsub("ZWWZ","*",p[i]);
printf("%s|",p[i]);
}
printf("%s\n",p[npipe]);
next;
}
for ( i=1; i <= npipe ; i++ )
{
if ( i % 2 == 1 ) {
gsub("ZWWZ","*",p[i]);
this=p[i];
put_this();
}
else {
nfn=split(p[i],f,".");
if ( nfn == 1 || f[2] == "" || f[1] == "" || length(f[2]) < 3 ) {
find_tag1();
}
else {
printf "|<A HREF=\"" f[1] ".html\">" p[i] "</A>|";
}
}
}
printf("\n");
next;
}
#
# line contains both "|" and "*"
#
npipe > 2 && nstar > 2 {
printf("\n");
for ( j=1; j <= nstar ; j=j+2 ) {
npipe = split(s[j],p,"YXXY");
if ( npipe > 1 ) {
for ( np=1; np<=npipe; np=np+2 ) {
this=p[np];
put_this();
i=np+1;find_tag1();
}
} else {
this=s[j];
put_this();
}
jj=j+1;
nbla = split(s[jj],blata," ");
if ( jj <= nstar && nbla == 1 && s[jj] != "" ) {
printf("*<A NAME=\"%s\"></A>",s[jj]);
printf("<B>%s</B>*",s[jj]);
} else {
if ( s[jj] != "" ) {
printf("*%s*",s[jj]);
}
}
}
printf("\n");
next;
}
#
# line contains e-mail address john.doe@some.place.edu
#
$0 ~ /@/ && $0 ~ /[a-zA-Z0-9]@[a-z]/ \
{
nemail=split($0,em," ");
if ( substr($0,1,1) == " " ) { printf(" "); }
for ( i=1; i <= nemail; i++ ) {
if ( em[i] ~ /@/ ) {
if ( substr(em[i],2,3) == "lt;" && substr(em[i],length(em[i])-2,3) == "gt;" ) {
mailaddr=substr(em[i],5,length(em[i])-8);
printf("<A HREF=\"mailto:%s\">&lt;%s&gt;</A> ",mailaddr,mailaddr);
} else {
if ( substr(em[i],2,3) == "lt;" && substr(em[i],length(em[i])-3,3) == "gt;" ) {
mailaddr=substr(em[i],5,length(em[i])-9);
printf("<A HREF=\"mailto:%s\">&lt;%s&gt;</A>%s ",mailaddr,mailaddr,substr(em[i],length(em[i]),1));
} else {
printf("<A HREF=\"mailto:%s\">%s</A> ",em[i],em[i]);
}
}
} else {
printf("%s ",em[i]);
}
}
#print "*** " NR " " FILENAME " - possible mail ref";
printf("\n");
next;
}
#
# line contains http / ftp reference
#
$0 ~ /http:\/\// || $0 ~ /ftp:\/\// {
gsub("URL:","");
gsub("&lt;","");
gsub("&gt;","");
gsub("\\(","");
gsub("\\)","");
nemail=split($0,em," ");
for ( i=1; i <= nemail; i++ ) {
if ( substr(em[i],1,5) == "http:" ||
substr(em[i],1,4) == "ftp:" ) {
if ( substr(em[i],length(em[i]),1) != "." ) {
printf(" <A HREF=\"%s\">%s</A>",em[i],em[i]);
} else {
em[i]=substr(em[i],1,length(em[i])-1);
printf(" <A HREF=\"%s\">%s</A>.",em[i],em[i]);
}
} else {
printf(" %s",em[i]);
}
}
#print "*** " NR " " FILENAME " - possible http ref";
printf("\n");
next;
}
#
# some lines contains just one "almost regular" "*"...
#
nstar == 2 {
this=s[1];
put_this();
printf("*");
this=s[2];
put_this();
printf("\n");
next;
}
#
# regular line
#
{ ntabs = split($0,tb," ");
for ( i=1; i < ntabs ; i++) {
this=tb[i];
put_this();
printf(" ");
}
this=tb[ntabs];
put_this();
printf("\n");
}
asciiart == "yes" && $0 ~ /\+-\+--/ \
&& $0 ~ "scrollbar" { asciiart = "no"; }
END {
topback();
print "</PRE>\n</BODY>\n\n\n</HTML>"; }
#
# as main we keep index.txt (by default)
# other candidate, help.txt
#
function topback () {
if ( FILENAME != "tags" ) {
if ( FILENAME != "help.txt" ) {
printf("<A HREF=\"#top\">top</A> - ");
printf("<A HREF=\"help.html\">main help file</A>\n");
} else {
printf("<A HREF=\"#top\">top</A>\n");
}
}
}
function find_tag1() {
if ( p[i] == "" ) { return; }
if ( tagkey[p[i]] == "yes" ) {
which=tagref[p[i]];
put_href();
return;
}
# if not found, then we have a problem
print "============================================" >>"errors.log";
print FILENAME ", line " NR ", pointer: >>" p[i] "<<" >>"errors.log";
print $0 >>"errors.log";
which="intro.html";
put_href();
}
function see_tag() {
# ad-hoc code:
if ( atag == "\"--" || atag == "--\"" ) { return; }
if_already();
if ( already == "yes" ) {
printf("%s",aword);
return;
}
allow_one_char="no";
find_tag2();
if ( done == "yes" ) { return; }
rightchar=substr(atag,length(atag),1);
if ( rightchar == "." \
|| rightchar == "," \
|| rightchar == ":" \
|| rightchar == ";" \
|| rightchar == "!" \
|| rightchar == "?" \
|| rightchar == ")" ) {
atag=substr(atag,1,length(atag)-1);
if_already();
if ( already == "yes" ) {
printf("%s",aword);
return;
}
find_tag2();
if ( done == "yes" ) { printf("%s",rightchar);return; }
leftchar=substr(atag,1,1);
lastbut1=substr(atag,length(atag),1);
if ( leftchar == "'" && lastbut1 == "'" ) {
allow_one_char="yes";
atag=substr(atag,2,length(atag)-2);
if_already();
if ( already == "yes" ) {
printf("%s",aword);
return;
}
printf("%s",leftchar);
aword=substr(atag,1,length(atag))""lastbut1""rightchar;
find_tag2();
if ( done == "yes" ) { printf("%s%s",lastbut1,rightchar);return; }
}
}
atag=aword;
leftchar=substr(atag,1,1);
if ( leftchar == "'" && rightchar == "'" ) {
allow_one_char="yes";
atag=substr(atag,2,length(atag)-2);
if ( atag == "<" ) { printf(" |%s|%s| ",atag,p[2]); }
if_already();
if ( already == "yes" ) {
printf("%s",aword);
return;
}
printf("%s",leftchar);
find_tag2();
if ( done == "yes" ) { printf("%s",rightchar);return; }
printf("%s%s",atag,rightchar);
return;
}
last2=substr(atag,length(atag)-1,2);
first2=substr(atag,1,2);
if ( first2 == "('" && last2 == "')" ) {
allow_one_char="yes";
atag=substr(atag,3,length(atag)-4);
if_already();
if ( already == "yes" ) {
printf("%s",aword);
return;
}
printf("%s",first2);
find_tag2();
if ( done == "yes" ) { printf("%s",last2);return; }
printf("%s%s",atag,last2);
return;
}
if ( last2 == ".)" ) {
atag=substr(atag,1,length(atag)-2);
if_already();
if ( already == "yes" ) {
printf("%s",aword);
return;
}
find_tag2();
if ( done == "yes" ) { printf("%s",last2);return; }
printf("%s%s",atag,last2);
return;
}
if ( last2 == ")." ) {
atag=substr(atag,1,length(atag)-2);
find_tag2();
if_already();
if ( already == "yes" ) {
printf("%s",aword);
return;
}
if ( done == "yes" ) { printf("%s",last2);return; }
printf("%s%s",atag,last2);
return;
}
first6=substr(atag,1,6);
last6=substr(atag,length(atag)-5,6);
if ( last6 == atag ) {
printf("%s",aword);
return;
}
last6of7=substr(atag,length(atag)-6,6);
if ( first6 == "&quot;" && last6of7 == "&quot;" && length(atag) > 12 ) {
allow_one_char="yes";
atag=substr(atag,7,length(atag)-13);
if_already();
if ( already == "yes" ) {
printf("%s",aword);
return;
}
printf("%s",first6);
find_tag2();
if ( done == "yes" ) { printf("&quot;%s",rightchar); return; }
printf("%s&quot;%s",atag,rightchar);
return;
}
if ( first6 == "&quot;" && last6 != "&quot;" ) {
allow_one_char="yes";
atag=substr(atag,7,length(atag)-6);
if ( atag == "[" ) { printf("&quot;%s",atag); return; }
if ( atag == "." ) { printf("&quot;%s",atag); return; }
if ( atag == ":" ) { printf("&quot;%s",atag); return; }
if ( atag == "a" ) { printf("&quot;%s",atag); return; }
if ( atag == "A" ) { printf("&quot;%s",atag); return; }
if ( atag == "g" ) { printf("&quot;%s",atag); return; }
if_already();
if ( already == "yes" ) {
printf("&quot;%s",atag);
return;
}
printf("%s",first6);
find_tag2();
if ( done == "yes" ) { return; }
printf("%s",atag);
return;
}
if ( last6 == "&quot;" && first6 == "&quot;" ) {
allow_one_char="yes";
atag=substr(atag,7,length(atag)-12);
if_already();
if ( already == "yes" ) {
printf("%s",aword);
return;
}
printf("%s",first6);
find_tag2();
if ( done == "yes" ) { printf("%s",last6);return; }
printf("%s%s",atag,last6);
return;
}
last6of7=substr(atag,length(atag)-6,6);
if ( last6of7 == "&quot;" && first6 == "&quot;" ) {
allow_one_char="yes";
atag=substr(atag,7,length(atag)-13);
#printf("\natag=%s,aword=%s\n",atag,aword);
if_already();
if ( already == "yes" ) {
printf("%s",aword);
return;
}
printf("%s",first6);
find_tag2();
if ( done == "yes" ) { printf("%s%s",last6of7,rightchar);return; }
printf("%s%s%s",atag,last6of7,rightchar);
return;
}
printf("%s",aword);
}
function find_tag2() {
done="no";
# no blanks present in a tag...
ntags=split(atag,blata,"[ ]");
if ( ntags > 1 ) { return; }
if ( ( allow_one_char == "no" ) && \
( index("!#$%\&'()+,-./0:;=?@ACINX\\[\\]^_`at\\{\\}~",atag) !=0 ) ) {
return;
}
if ( skip_word[atag] == "yes" ) { return; }
if ( wasset == "yes" && lineset == NR ) {
wasset="no";
see_opt();
if ( done_opt == "yes" ) {return;}
}
if ( wasset == "yes" && lineset != NR ) {
wasset="no";
}
if ( atag == ":set" ) {
wasset="yes";
lineset=NR;
}
if ( tagkey[atag] == "yes" ) {
which=tagref[atag];
put_href2();
done="yes";
}
}
function find_tag3() {
done="no";
# no blanks present in a tag...
ntags=split(btag,blata,"[ ]");
if ( ntags > 1 ) { return; }
if ( ( allow_one_char == "no" ) && \
( index("!#$%\&'()+,-./0:;=?@ACINX\\[\\]^_`at\\{\\}~",btag) !=0 ) ) {
return;
}
if ( skip_word[btag] == "yes" ) { return; }
if ( tagkey[btag] == "yes" ) {
which=tagref[btag];
put_href3();
done="yes";
}
}
function put_href() {
if ( p[i] == "" ) { return; }
if ( which == FILENAME ) {
printf("|<A HREF=\"#%s\">%s</A>|",p[i],p[i]);
}
else {
nz=split(which,zz,".");
if ( zz[2] == "txt" || zz[1] == "tags" ) {
printf("|<A HREF=\"%s.html#%s\">%s</A>|",zz[1],p[i],p[i]);
}
else {
printf("|<A HREF=\"intro.html#%s\">%s</A>|",p[i],p[i]);
}
}
}
function put_href2() {
if ( atag == "" ) { return; }
if ( which == FILENAME ) {
printf("<A HREF=\"#%s\">%s</A>",atag,atag);
}
else {
nz=split(which,zz,".");
if ( zz[2] == "txt" || zz[1] == "tags" ) {
printf("<A HREF=\"%s.html#%s\">%s</A>",zz[1],atag,atag);
}
else {
printf("<A HREF=\"intro.html#%s\">%s</A>",atag,atag);
}
}
}
function put_href3() {
if ( btag == "" ) { return; }
if ( which == FILENAME ) {
printf("<A HREF=\"#%s\">%s</A>",btag,btag2);
}
else {
nz=split(which,zz,".");
if ( zz[2] == "txt" || zz[1] == "tags" ) {
printf("<A HREF=\"%s.html#%s\">%s</A>",zz[1],btag,btag2);
}
else {
printf("<A HREF=\"intro.html#%s\">%s</A>",btag,btag2);
}
}
}
function put_this() {
ntab=split(this,ta," ");
for ( nta=1 ; nta <= ntab ; nta++ ) {
ata=ta[nta];
lata=length(ata);
aword="";
for ( iata=1 ; iata <=lata ; iata++ ) {
achar=substr(ata,iata,1);
if ( achar != " " ) { aword=aword""achar; }
else {
if ( aword != "" ) { atag=aword;
see_tag();
aword="";
printf(" "); }
else {
printf(" ");
}
}
}
if ( aword != "" ) { atag=aword;
see_tag();
}
if ( nta != ntab ) { printf(" "); }
}
}
function if_already() {
already="no";
if ( npipe < 2 ) { return; }
if ( atag == ":au" && p[2] == ":autocmd" ) { already="yes";return; }
for ( npp=2 ; npp <= npipe ; npp=npp+2 ) {
if ( ( (index(p[npp],atag)) != 0 \
&& length(p[npp]) > length(atag) \
&& length(atag) >= 1 \
) \
|| (p[npp] == atag) \
) {
# printf("p=|%s|,tag=|%s| ",p[npp],atag);
already="yes"; return; }
}
}
function see_opt() {
done_opt="no";
stag=atag;
nfields = split(atag,tae,"=");
if ( nfields > 1 ) {
btag="'"tae[1]"'";
btag2=tae[1];
find_tag3();
if (done == "yes") {
for ( ntae=2 ; ntae <= nfields ; ntae++ ) {
printf("=%s",tae[ntae]);
}
atag=stag;
done_opt="yes";
return;
}
btag=tae[1];
btag2=tae[1];
find_tag3();
if ( done=="yes" ) {
for ( ntae=2 ; ntae <= nfields ; ntae++ ) {
printf("=%s",tae[ntae]);
}
atag=stag;
done_opt="yes";
return;
}
}
nfields = split(atag,tae,"&quot;");
if ( nfields > 1 ) {
btag="'"tae[1]"'";
btag2=tae[1];
find_tag3();
if (done == "yes") {
printf("&quot;");
atag=stag;
done_opt="yes";
return;
}
btag=tae[1];
btag2=tae[1];
find_tag3();
if (done == "yes") {
printf("&quot;");
atag=stag;
done_opt="yes";
return;
}
}
btag="'"tae[1]"'";
btag2=tae[1];
find_tag3();
if (done == "yes") {
atag=stag;
done_opt="yes";
return;
}
btag=tae[1];
btag2=tae[1];
find_tag3();
if (done == "yes") {
atag=stag;
done_opt="yes";
return;
}
atag=stag;
}

42
runtime/doc/maketags.awk Normal file
View File

@@ -0,0 +1,42 @@
BEGIN { FS=" "; }
NR == 1 { nf=split(FILENAME,f,".")
print "<HTML>";
print "<HEAD><TITLE>" f[1] "</TITLE></HEAD>";
print "<BODY BGCOLOR=\"#ffffff\">";
print "<H1>Vim Documentation: " f[1] "</H1>";
print "<A NAME=\"top\"></A>";
print "<HR>";
print "<PRE>";
}
{
#
# protect special chars
#
gsub(/&/,"\\&amp;");
gsub(/>/,"\\&gt;");
gsub(/</,"\\&lt;");
gsub(/"/,"\\&quot;");
gsub(/%/,"\\&#37;");
nf=split($0,tag," ");
tagkey[t]=tag[1];tagref[t]=tag[2];tagnum[t]=NR;
print $1 " " $2 " line " NR >"tags.ref"
n=split($2,w,".");
printf ("|<A HREF=\"%s.html#%s\">%s</A>| %s\n",w[1],$1,$1,$2);
}
END {
topback();
print "</PRE>\n</BODY>\n\n\n</HTML>";
}
#
# as main we keep index.txt (by default)
# other candidate, help.txt
#
function topback () {
printf("<A HREF=\"#top\">top</A> - ");
printf("<A HREF=\"help.html\">back to help</A>\n");
}

1094
runtime/doc/map.txt Normal file
View File

File diff suppressed because it is too large Load Diff

1368
runtime/doc/mbyte.txt Normal file
View File

File diff suppressed because it is too large Load Diff

775
runtime/doc/message.txt Normal file
View File

@@ -0,0 +1,775 @@
*message.txt* For Vim version 7.0aa. Last change: 2004 Jan 17
VIM REFERENCE MANUAL by Bram Moolenaar
This file contains an alphabetical list of messages and error messages that
Vim produces. You can use this if you don't understand what the message
means. It is not complete though.
1. Old messages |:messages|
2. Error messages |error-messages|
3. Messages |messages|
==============================================================================
1. Old messages *:messages* *:mes* *message-history*
The ":messages" command can be used to view previously given messages. This
is especially useful when messages have been overwritten or truncated. This
depends on the 'shortmess' option.
The number of remembered messages is fixed at 20.
If you are using translated messages, the first printed line tells who
maintains the messages or the translations. You can use this to contact the
maintainer when you spot a mistake.
If you want to find help on a specific (error) message, use the ID at the
start of the message. For example, to get help on the message: >
E72: Close error on swap file
or (translated): >
E72: Errore durante chiusura swap file
Use: >
:help E72
If you are lazy, it also works without the shift key: >
:help e72
==============================================================================
2. Error messages *error-messages*
When an error message is displayed, but it is removed before you could read
it, you can see it again with: >
:echo errmsg
or view a list of recent messages with: >
:messages
LIST OF MESSAGES
*E222* *E228* *E232* *E256* *E293* *E298* *E304* *E317*
*E318* *E356* *E438* *E439* *E440* *E316* *E320* *E322*
*E323* *E341* *E473* *E570* >
Add to read buffer
makemap: Illegal mode
Cannot create BalloonEval with both message and callback
Hangul automata ERROR
block was not locked
Didn't get block nr {N}?
ml_timestamp: Didn't get block 0??
pointer block id wrong {N}
Updated too many blocks?
get_varp ERROR
u_undo: line numbers wrong
undo list corrupt
undo line missing
ml_get: cannot find line {N}
cannot find line {N}
line number out of range: {N} past the end
line count wrong in block {N}
Internal error
fatal error in cs_manage_matches
This is an internal error. If you can reproduce it, please send in a bug
report. |bugs|
>
ATTENTION
Found a swap file by the name ...
See |ATTENTION|.
*E92* >
Buffer {N} not found
The buffer you requested does not exist. This can also happen when you have
wiped out a buffer which contains a mark or is referenced in another way.
|:bwipeout|
*E95* >
Buffer with this name already exists
You cannot have two buffers with the same name.
*E72* >
Close error on swap file
The |swap-file|, that is used to keep a copy of the edited text, could not be
closed properly. Mostly harmless.
*E169* >
Command too recursive
This happens when an Ex command executes an Ex command that executes an Ex
command, etc. This is only allowed 200 times. When it's more there probably
is an endless loop. Probably a |:execute| or |:source| command is involved.
*E254* >
Cannot allocate color {name}
The color name {name} is unknown. See |gui-colors| for a list of colors that
are available on most systems.
*E458* >
Cannot allocate colormap entry for "xxxx"
Cannot allocate colormap entry, some colors may be incorrect
This means that there are not enough colors available for Vim. It will still
run, but some of the colors will not appear in the specified color. Try
stopping other applications that use many colors, or start them after starting
gvim.
Netscape is known to consume a lot of colors. You can avoid this by telling
it to use its own colormap: >
netscape -install
Or tell it to limit to a certain number of colors (64 should work well): >
netscape -ncols 64
This can also be done with a line in your Xdefaults file: >
Netscape*installColormap: Yes
or >
Netscape*maxImageColors: 64
<
*E79* >
Cannot expand wildcards
A filename contains a strange combination of characters, which causes Vim to
attempt expanding wildcards but this fails. This does NOT mean that no
matching file names could be found, but that the pattern was illegal.
*E459* >
Cannot go back to previous directory
While expanding a file name, Vim failed to go back to the previously used
directory. All file names being used may be invalid now! You need to have
execute permission on the current directory.
*E190* *E212* >
Cannot open "{filename}" for writing
Can't open file for writing
For some reason the file you are writing to cannot be created or overwritten.
The reason could be that you do not have permission to write in the directory
or the file name is not valid.
*E166* >
Can't open linked file for writing
You are trying to write to a file which can't be overwritten, and the file is
a link (either a hard link or a symbolic link). Writing might still be
possible if the directory that contains the link or the file is writable, but
Vim now doesn't know if you want to delete the link and write the file in its
place, or if you want to delete the file itself and write the new file in its
place. If you really want to write the file under this name, you have to
manually delete the link or the file, or change the permissions so that Vim
can overwrite.
*E46* >
Cannot set read-only variable "{name}"
You are trying to assign a value to an argument of a function |a:var| or a Vim
internal variable |v:var| which is read-only.
*E90* >
Cannot unload last buffer
Vim always requires one buffer to be loaded, otherwise there would be nothing
to display in the window.
*E40* >
Can't open errorfile <filename>
When using the ":make" or ":grep" commands: The file used to save the error
messages or grep output cannot be opened. This can have several causes:
- 'shellredir' has a wrong value.
- The shell changes directory, causing the error file to be written in another
directory. This could be fixed by changing 'makeef', but then the make
command is still executed in the wrong directory.
- 'makeef' has a wrong value.
- The 'grepprg' or 'makeprg' could not be executed. This cannot always be
detected (especially on MS-Windows). Check your $PATH.
>
Can't open file C:\TEMP\VIoD243.TMP
On MS-Windows, this message appears when the output of an external command was
to be read, but the command didn't run successfully. This can be caused by
many things. Check the 'shell', 'shellquote', 'shellxquote', 'shellslash' and
related options. It might also be that the external command was not found,
there is no different error message for that.
*E12* >
Command not allowed from exrc/vimrc in current dir or tag search
Some commands are not allowed for security reasons. These commands mostly
come from a .exrc or .vimrc file in the current directory, or from a tags
file. Also see 'secure'.
*E74* >
Command too complex
A mapping resulted in a very long command string. Could be caused by a
mapping that indirectly calls itself.
>
CONVERSION ERROR
When writing a file and the text "CONVERSION ERROR" appears, this means that
some bits were lost when converting text from the internally used UTF-8 to the
format of the file. The file will not be marked unmodified. If you care
about the loss of information, set the 'fileencoding' option to another value
that can handle the characters in the buffer and write again. If you don't
care, you can abandon the buffer or reset the 'modified' option.
*E302* >
Could not rename swap file
When the file name changes, Vim tries to rename the |swap-file| as well.
This failed and the old swap file is now still used. Mostly harmless.
*E43* *E44* >
Damaged match string
Corrupted regexp program
Something inside Vim went wrong and resulted in a corrupted regexp. If you
know how to reproduce this problem, please report it. |bugs|
*E208* *E209* *E210* >
Error writing to "{filename}"
Error closing "{filename}"
Error reading "{filename}"
This occurs when Vim is trying to rename a file, but a simple change of file
name doesn't work. Then the file will be copied, but somehow this failed.
The result may be that both the original file and the destination file exist
and the destination file may be incomplete.
>
Vim: Error reading input, exiting...
This occurs when Vim cannot read typed characters while input is required.
Vim got stuck, the only thing it can do is exit. This can happen when both
stdin and stderr are redirected and executing a script that doesn't exit Vim.
*E47* >
Error while reading errorfile
Reading the error file was not possible. This is NOT caused by an error
message that was not recognized.
*E80* >
Error while writing
Writing a file was not completed successfully. The file is probably
incomplete.
*E13* *E189* >
File exists (use ! to override)
"{filename}" exists (use ! to override)
You are protected from accidentally overwriting a file. When you want to
write anyway, use the same command, but add a "!" just after the command.
Example: >
:w /tmp/test
changes to: >
:w! /tmp/test
<
*E139* >
File is loaded in another buffer
You are trying to write a file under a name which is also used in another
buffer. This would result in two versions of the same file.
*E142* >
File not written: Writing is disabled by 'write' option
The 'write' option is off. This makes all commands that try to write a file
generate this message. This could be caused by a |-m| commandline argument.
You can switch the 'write' option on with ":set write".
*E25* >
GUI cannot be used: Not enabled at compile time
You are running a version of Vim that doesn't include the GUI code. Therefore
"gvim" and ":gui" don't work.
*E49* >
Invalid scroll size
This is caused by setting an invalid value for the 'scroll', 'scrolljump' or
'scrolloff' options.
*E17* >
"{filename}" is a directory
You tried to write a file with the name of a directory. This is not possible.
You probably need to append a file name.
*E19* >
Mark has invalid line number
You are using a mark that has a line number that doesn't exist. This can
happen when you have a mark in another file, and some other program has
deleted lines from it.
*E219* *E220* >
Missing {.
Missing }.
Using a {} construct in a file name, but there is a { without a matching } or
the other way around. It should be used like this: {foo,bar}. This matches
"foo" and "bar".
*E315* >
ml_get: invalid lnum:
This is an internal Vim error. Please try to find out how it can be
reproduced, and submit a bug report |bugreport.vim|.
*E173* >
{number} more files to edit
You are trying to exit, while the last item in the argument list has not been
edited. This protects you from accidentally exiting when you still have more
files to work on. See |argument-list|. If you do want to exit, just do it
again and it will work.
*E23* *E194* >
No alternate file
No alternate file name to substitute for '#'
The alternate file is not defined yet. See |alternate-file|.
*E32* >
No file name
The current buffer has no name. To write it, use ":w fname". Or give the
buffer a name with ":file fname".
*E141* >
No file name for buffer {number}
One of the buffers that was changed does not have a file name. Therefore it
cannot be written. You need to give the buffer a file name: >
:buffer {number}
:file {filename}
<
*E33* >
No previous substitute regular expression
When using the '~' character in a pattern, it is replaced with the previously
used pattern in a ":substitute" command. This fails when no such command has
been used yet. See |/~|.
*E35* >
No previous regular expression
When using an empty search pattern, the previous search pattern is used. But
that is not possible if there was no previous search.
*E24* >
No such abbreviation
You have used an ":unabbreviate" command with an argument which is not an
existing abbreviation. All variations of this command give the same message:
":cunabbrev", ":iunabbrev", etc. Check for trailing white space.
>
/dev/dsp: No such file or directory
Only given for GTK GUI with Gnome support. Gnome tries to use the audio
device and it isn't present. You can ignore this error.
*E31* >
No such mapping
You have used an ":unmap" command with an argument which is not an existing
mapping. All variations of this command give the same message: ":cunmap",
":unmap!", etc. Check for trailing white space.
*E37* *E89* >
No write since last change (use ! to override)
No write since last change for buffer {N} (use ! to override)
You are trying to |abandon| a file that has changes. Vim protects you from
losing your work. You can either write the changed file with ":w", or, if you
are sure, |abandon| it anyway, and lose all the changes. This can be done by
adding a '!' character just after the command you used. Example: >
:e other_file
changes to: >
:e! other_file
<
*E162* >
No write since last change for buffer "{name}"
This appears when you try to exit Vim while some buffers are changed. You
will either have to write the changed buffer (with |:w|), or use a command to
abandon the buffer forcefully, e.g., with ":qa!". Careful, make sure you
don't throw away changes you really want to keep. You might have forgotten
about a buffer, especially when 'hidden' is set.
*E38* >
Null argument
Something inside Vim went wrong and resulted in a NULL pointer. If you know
how to reproduce this problem, please report it. |bugs|
*E172* >
Only one file name allowed
The ":edit" command only accepts one file name. When you want to specify
several files for editing use ":next" |:next|.
*E41* *E82* *E83* *E342* >
Out of memory!
Out of memory! (allocating {number} bytes)
Cannot allocate any buffer, exiting...
Cannot allocate buffer, using other one...
Oh, oh. You must have been doing something complicated, or some other program
is consuming your memory. Be careful! Vim is not completely prepared for an
out-of-memory situation. First make sure that any changes are saved. Then
try to solve the memory shortage. To stay on the safe side, exit Vim and
start again. Also see |msdos-limitations|.
*E339* >
Pattern too long
This only happens on systems with 16 bit ints: The compiled regexp pattern is
longer than about 65000 characters. Try using a shorter pattern.
*E45* >
'readonly' option is set (use ! to override)
You are trying to write a file that was marked as read-only. To write the
file anyway, either reset the 'readonly' option, or add a '!' character just
after the command you used. Example: >
:w
changes to: >
:w!
<
*E294* *E295* *E301* >
Read error in swap file
Seek error in swap file read
Oops, lost the swap file!!!
Vim tried to read text from the |swap-file|, but something went wrong. The
text in the related buffer may now be corrupted! Check carefully before you
write a buffer. You may want to write it in another file and check for
differences.
*E192* >
Recursive use of :normal too deep
You are using a ":normal" command, whose argument again uses a ":normal"
command in a recursive way. This is restricted to 'maxmapdepth' levels. This
example illustrates how to get this message: >
:map gq :normal gq<CR>
If you type "gq", it will execute this mapping, which will call "gq" again.
*E22* >
Scripts nested too deep
Scripts can be read with the "-s" command-line argument and with the ":source"
command. The script can then again read another script. This can continue
for about 14 levels. When more nesting is done, Vim assumes that there is a
recursive loop somewhere and stops with this error message.
*E319* >
Sorry, the command is not available in this version
You have used a command that is not present in the version of Vim you are
using. When compiling Vim, many different features can be enabled or
disabled. This depends on how big Vim has chosen to be and the operating
system. See |+feature-list| for when which feature is available. The
|:version| command shows which feature Vim was compiled with.
*E300* >
Swap file already exists (symlink attack?)
This message appears when Vim is trying to open a swap file and finds it
already exists or finds a symbolic link in its place. This shouldn't happen,
because Vim already checked that the file doesn't exist. Either someone else
opened the same file at exactly the same moment (very unlikely) or someone is
attempting a symlink attack (could happen when editing a file in /tmp or when
'directory' starts with "/tmp", which is a bad choice).
*E432* >
Tags file not sorted: {file name}
Vim (and Vi) expect tags files to be sorted in ASCII order. Binary searching
can then be used, which is a lot faster than a linear search. If your tags
files are not properly sorted, reset the |'tagbsearch'| option.
This message is only given when Vim detects a problem when searching for a
tag. Sometimes this message is not given, even thought the tags file is not
properly sorted.
*E460* >
The resource fork would be lost (add ! to override)
On the Macintosh (classic), when writing a file, Vim attempts to preserve all
info about a file, including its resource fork. If this is not possible you
get this error message. Append "!" to the command name to write anyway (and
lose the info).
*E424* >
Too many different highlighting attributes in use
Vim can only handle about 223 different kinds of highlighting. If you run
into this limit, you have used too many |:highlight| commands with different
arguments. A ":highlight link" is not counted.
*E77* >
Too many file names
When expanding file names, more than one match was found. Only one match is
allowed for the command that was used.
*E303* >
Unable to open swap file for "{filename}", recovery impossible
Vim was not able to create a swap file. You can still edit the file, but if
Vim unexpected exits the changes will be lost. And Vim may consume a lot of
memory when editing a big file. You may want to change the 'directory' option
to avoid this error. See |swap-file|.
*E140* >
Use ! to write partial buffer
When using a range to write part of a buffer, it is unusual to overwrite the
original file. It is probably a mistake (e.g., when Visual mode was active
when using ":w"), therefore Vim requires using a ! after the command, e.g.:
":3,10w!".
>
Warning: Cannot convert string "<Key>Escape,_Key_Cancel" to type
VirtualBinding
Messages like this appear when starting up. This is not a Vim problem, your
X11 configuration is wrong. You can find a hint on how to solve this here:
http://groups.yahoo.com/group/solarisonintel/message/12179.
*W10* >
Warning: Changing a readonly file
The file is read-only and you are making a change to it anyway. You can use
the |FileChangedRO| autocommand event to avoid this message (the autocommand
must reset the 'readonly' option). See 'modifiable' to completely disallow
making changes to a file.
*W13* >
Warning: File "{filename}" has been created after editing started
You are editing a file in Vim when it didn't exist, but it does exist now.
You will have to decide if you want to keep the version in Vim or the newly
created file. This message is not given when 'buftype' is not empty.
*W11* >
Warning: File "{filename}" has changed since editing started
The file which you have started editing has got another timestamp and the
contents changed (more precisely: When reading the file again with the current
option settings and autocommands you would end up with different text). This
probably means that some other program changed the file. You will have to
find out what happened, and decide which version of the file you want to keep.
Set the 'autoread' option if you want to do this automatically.
This message is not given when 'buftype' is not empty.
There is one situation where you get this message even though there is nothing
wrong: If you save a file in Windows on the day the daylight saving time
starts. It can be fixed in one of these ways:
- Add this line in your autoexec.bat: >
SET TZ=-1
< Adjust the "-1" for your time zone.
- Disable "automatically adjust clock for daylight saving changes".
- Just write the file again the next day. Or set your clock to the next day,
write the file twice and set the clock back.
*W12* >
Warning: File "{filename}" has changed and the buffer was changed in Vim as well
Like the above, and the buffer for the file was changed in this Vim as well.
You will have to decide if you want to keep the version in this Vim or the one
on disk. This message is not given when 'buftype' is not empty.
*W16* >
Warning: Mode of file "{filename}" has changed since editing started
When the timestamp for a buffer was changed and the contents are still the
same but the mode (permissions) have changed. This usually occurs when
checking out a file from a version control system, which causes the read-only
bit to be reset. It should be safe to reload the file. Set 'autoread' to
automatically reload the file.
*E211* >
Warning: File "{filename}" no longer available
The file which you have started editing has disappeared, or is no longer
accessible. Make sure you write the buffer somewhere to avoid losing
changes. This message is not given when 'buftype' is not empty.
*W14* >
Warning: List of file names overflow
You must be using an awful lot of buffers. It's now possible that two buffers
have the same number, which causes various problems. You might want to exit
Vim and restart it.
*E296* *E297* >
Seek error in swap file write
Write error in swap file
This mostly happens when the disk is full. Vim could not write text into the
|swap-file|. It's not directly harmful, but when Vim unexpectedly exits some
text may be lost without recovery being possible. Vim might run out of memory
when this problem persists.
*connection-refused* >
Xlib: connection to "<machine-name:0.0" refused by server
This happens when Vim tries to connect to the X server, but the X server does
not allow a connection. The connection to the X server is needed to be able
to restore the title and for the xterm clipboard support. Unfortunately this
error message cannot be avoided, except by disabling the |+xterm_clipboard|
and |+X11| features.
*E10* >
\\ should be followed by /, ? or &
A command line started with a backslash or the range of a command contained a
backslash in a wrong place. This is often caused by command-line continuation
being disabled. Remove the 'C' flag from the 'cpoptions' option to enable it.
*E471* >
Argument required
This happens when an Ex command with mandatory argument(s) was executed, but
no argument has been specified.
*E474* *E475* >
Invalid argument
An Ex command has been executed, but an invalid argument has been specified.
*E488* >
Trailing characters
An argument has been added to an Ex command that does not permit one.
*E477* *E478* >
No ! allowed
Don't panic!
You have added a "!" after an Ex command that doesn't permit one.
*E481* >
No range allowed
A range was specified for an Ex command that doesn't permit one. See
|cmdline-ranges|.
*E482* *E483* >
Can't create file {filename}
Can't get temp file name
Vim cannot create a temporary file.
*E484* *E485* >
Can't open file %s"
Can't read file %s"
Vim cannot read a temporary file.
*E464* >
Ambiguous use of user-defined command
There are two user-defined commands with a common name prefix, and you used
Command-line completion to execute one of them. |user-cmd-ambiguous|
Example: >
:command MyCommand1 echo "one"
:command MyCommand2 echo "two"
:MyCommand
<
*E492* >
Not an editor command
You tried to execute a command that is neither an Ex command nor
a user-defined command.
==============================================================================
3. Messages *messages*
This is an (incomplete) overview of various messages that Vim gives:
*hit-enter* *press-enter* *hit-return* *press-return* >
Hit ENTER or type command to continue
This message is given when there is something on the screen for you to read,
and the screen is about to be redrawn:
- After executing an external command (e.g., ":!ls" and "=").
- Something is displayed on the status line that is longer than the width of
the window, or runs into the 'showcmd' or 'ruler' output.
-> Hit <Enter> or <Space> to redraw the screen and continue, without that key
being used otherwise.
-> Hit ":" or any other Normal mode command character to start that command.
-> Hit <C-Y> to copy (yank) a modeless selection to the clipboard register.
-> Use a menu. The characters defined for Cmdline-mode are used.
-> When 'mouse' contains the 'r' flag, clicking the left mouse button works
like pressing <Space>. This makes it impossible to select text though.
-> For the GUI clicking the left mouse button in the last line works like
pressing <Space>.
{Vi: only ":" commands are interpreted}
To reduce the number of hit-enter prompts:
- Set 'cmdheight' to 2 or higher.
- Add flags to 'shortmess'.
- Reset 'showcmd' and/or 'ruler'.
Also see 'mouse'. The hit-enter message is highlighted with the |hl-Question|
group.
*more-prompt* *pager* >
-- More --
-- More -- (RET: line, SPACE: page, d: half page, q: quit)
-- More -- (RET/BS: line, SPACE/b: page, d/u: half page, q: quit)
This message is given when the screen is filled with messages. It is only
given when the 'more' option is on. It is highlighted with the |hl-MoreMsg|
group.
Type effect ~
<CR> or <NL> or j or <Down> one more line
<BS> or k or <Up> one line back (*)
<Space> or <PageDown> next page
b or <PageUp> previous page (*)
d down half a page
u up half a page (*)
q, <Esc> or CTRL-C stop the listing
: stop the listing and enter a
command-line
<C-Y> yank (copy) a modeless selection to
the clipboard ("* and "+ registers)
{menu-entry} what the menu is defined to in
Cmdline-mode.
<LeftMouse> (**) next page
Any other key causes the meaning of the keys to be displayed.
(*) backwards scrolling is only supported for these commands: >
:clist
(**) Clicking the left mouse button only works:
- For the GUI: in the last line of the screen.
- When 'r' is included in 'mouse' (but then selecting text won't work).
Note: The typed key is directly obtained from the terminal, it is not mapped
and typeahead is ignored.
vim:tw=78:ts=8:ft=help:norl:

205
runtime/doc/mlang.txt Normal file
View File

@@ -0,0 +1,205 @@
*mlang.txt* For Vim version 7.0aa. Last change: 2004 Feb 24
VIM REFERENCE MANUAL by Bram Moolenaar
Multi-language features *multilang* *multi-lang*
This is about using messages and menus in various languages. For editing
multi-byte text see |multibyte|.
The basics are explained in the user manual: |usr_45.txt|.
1. Messages |multilang-messages|
2. Menus |multilang-menus|
3. Scripts |multilang-scripts|
Also see |help-translated| for multi-language help.
{Vi does not have any of these features}
{not available when compiled without the |+multi_lang| feature}
==============================================================================
1. Messages *multilang-messages*
Vim picks up the locale from the environment. In most cases this means Vim
will use the language that you prefer, unless it's not available.
To see a list of supported locale names on your system, look in one of these
directories (for Unix):
/usr/lib/locale ~
/usr/share/locale ~
Unfortunately, upper/lowercase differences matter. Also watch out for the
use of "-" and "_".
*:lan* *:lang* *:language* *E197*
:lan[guage]
:lan[guage] mes[sages]
:lan[guage] cty[pe]
:lan[guage] tim[e]
Print the current language (aka locale).
With the "messages" argument the language used for
messages is printed. Technical: LC_MESSAGES.
With the "ctype" argument the language used for
character encoding is printed. Technical: LC_CTYPE.
With the "time" argument the language used for
strftime() is printed. Technical: LC_TIME.
Without argument all parts of the locale are printed
(this is system dependent).
The current language can also be obtained with the
|v:lang|, |v:ctype| and |v:lc_time| variables.
:lan[guage] {name}
:lan[guage] mes[sages] {name}
:lan[guage] cty[pe] {name}
:lan[guage] tim[e] {name}
Set the current language (aka locale) to {name}.
The locale {name} must be a valid locale on your
system. Some systems accept aliases like "en" or
"en_US", but some only accept the full specification
like "en_US.ISO_8859-1".
With the "messages" argument the language used for
messages is set. This can be different when you want,
for example, English messages while editing Japanese
text. This sets $LC_MESSAGES.
With the "ctype" argument the language used for
character encoding is set. This affects the libraries
that Vim was linked with. It's unusual to set this to
a different value from 'encoding'. This sets
$LC_CTYPE.
With the "time" argument the language used for time
and date messages is set. This affects strftime().
This sets $LC_TIME.
Without an argument both are set, and additionally
$LANG is set.
This will make a difference for items that depend on
the language (some messages, time and date format).
Not fully supported on all systems
If this fails there will be an error message. If it
succeeds there is no message. Example: >
:language
Current language: C
:language de_DE.ISO_8859-1
:language mes
Current messages language: de_DE.ISO_8859-1
:lang mes en
<
MS-WINDOWS MESSAGE TRANSLATIONS *win32-gettext*
If you used the self-installing .exe file, message translations should work
already. Otherwise get the libintl.dll file if you don't have it yet:
http://sourceforge.net/projects/gettext
This also contains tools xgettext, msgformat and others.
libintl.dll should be placed in same directory with (g)vim.exe, or some
place where PATH environment value describe. Message files (vim.mo)
have to be placed in "$VIMRUNTIME/lang/xx/LC_MESSAGES", where "xx" is the
abbreviation of the language (mostly two letters).
If you write your own translations you need to generate the .po file and
convert it to a .mo file. You need to get the source distribution and read
the file "src/po/README.txt".
To overrule the automatic choice of the language, set the $LANG variable to
the language of your choice. use "en" to disable translations. >
:let $LANG = 'ja'
(text for Windows by Muraoka Taro)
==============================================================================
2. Menus *multilang-menus*
See |45.2| for the basics.
Note that if changes have been made to the menus after the translation was
done, some of the menus may be shown in English. Please try contacting the
maintainer of the translation and ask him to update it. You can find the
name and e-mail address of the translator in
"$VIMRUNTIME/lang/menu_<lang>.vim".
To set the font (or fontset) to use for the menus, use the |:highlight|
command. Example: >
:highlight Menu font=k12,r12
ALIAS LOCALE NAMES
Unfortunately, the locale names are different on various systems, even though
they are for the same language and encoding. If you do not get the menu
translations you expected, check the output of this command: >
echo v:lang
Now check the "$VIMRUNTIME/lang" directory for menu translation files that use
a similar language. A difference in a "-" being a "_" already causes a file
not to be found! Another common difference to watch out for is "iso8859-1"
versus "iso_8859-1". Fortunately Vim makes all names lowercase, thus you
don't have to worry about case differences. Spaces are changed to
underscores, to avoid having to escape them.
If you find a menu translation file for your language with a different name,
create a file in your own runtime directory to load that one. The name of
that file could be: >
~/.vim/lang/menu_<v:lang>.vim
Check the 'runtimepath' option for directories which are searched. In that
file put a command to load the menu file with the other name: >
runtime lang/menu_<other_lang>.vim
TRANSLATING MENUS
If you want to do your own translations, you can use the |:menutrans| command,
explained below. It is recommended to put the translations for one language
in a Vim script. For a language that has no translation yet, please consider
becoming the maintainer and make your translations available to all Vim users.
Send an e-mail to the Vim maintainer <maintainer@vim.org>.
*:menut* *:menutrans* *:menutranslate*
:menut[ranslate] clear
Clear all menu translations.
:menut[ranslate] {english} {mylang}
Translate menu name {english} to {mylang}. All
special characters like "&" and "<Tab>" need to be
included. Spaces and dots need to be escaped with a
backslash, just like in other |:menu| commands.
See the $VIMRUNTIME/lang directory for examples.
To try out your translations you first have to remove all menus. This is how
you can do it without restarting Vim: >
:source $VIMRUNTIME/delmenu.vim
:source <your-new-menu-file>
:source $VIMRUNTIME/menu.vim
Each part of a menu path is translated separately. The result is that when
"Help" is translated to "Hilfe" and "Overview" to "Überblick" then
"Help.Overview" will be translated to "Hilfe.Überblick".
==============================================================================
3. Scripts *multilang-scripts*
In Vim scripts you can use the |v:lang| variable to get the current language
(locale). The default value is "C" or comes from the $LANG environment
variable.
The following example shows how this variable is used in a simple way, to make
a message adapt to language preferences of the user, >
:if v:lang =~ "de_DE"
: echo "Guten Morgen"
:else
: echo "Good morning"
:endif
<
vim:tw=78:sw=4:ts=8:ft=help:norl:

1191
runtime/doc/motion.txt Normal file
View File

File diff suppressed because it is too large Load Diff

735
runtime/doc/netbeans.txt Normal file
View File

@@ -0,0 +1,735 @@
*netbeans.txt* For Vim version 7.0aa. Last change: 2004 May 01
VIM REFERENCE MANUAL by Gordon Prieur
NetBeans ExternalEditor Integration Features *netbeans*
*netbeans-support*
1. Introduction |netbeans-intro|
2. NetBeans Key Bindings |netbeans-keybindings|
3. Configuring Vim for NetBeans |netbeans-configure|
4. Downloading NetBeans |netbeans-download|
5. Preparing NetBeans for Vim |netbeans-preparation|
6. Obtaining the External Editor Module |obtaining-exted|
7. Setting up NetBeans to run with Vim |netbeans-setup|
8. Messages |netbeans-messages|
9. Running Vim from NetBeans |netbeans-run|
10. NetBeans protocol |netbeans-protocol|
11. Known problems |netbeans-problems|
{Vi does not have any of these features}
{only available when compiled with the |+netbeans_intg| feature}
==============================================================================
1. Introduction *netbeans-intro*
NetBeans is an open source Integrated Development Environment developed
jointly by Sun Microsystems, Inc. and the netbeans.org developer community.
Initially just a Java IDE, NetBeans has had C, C++, and Fortran support added
in recent releases.
For more information visit the main NetBeans web site http://www.netbeans.org
or the NetBeans External Editor site at http://externaleditor.netbeans.org.
Sun Microsystems, Inc. also ships NetBeans under the name Sun ONE Studio.
Visit http://www.sun.com for more information regarding the Sun ONE Studio
product line.
Current releases of NetBeans provide full support for Java and limited support
for C, C++, and Fortran. Current releases of Sun ONE Studio provide full
support for Java, C, C++, and Fortran.
The interface to NetBeans is also supported by Agide, the A-A-P GUI IDE.
Agide is very different from NetBeans:
- Based on Python instead of Java, much smaller footprint and fast startup.
- Agide is a framework in which many different tools can work together.
See the A-A-P website for information: http://www.A-A-P.org.
==============================================================================
2. NetBeans Key Bindings *netbeans-keybindings*
Vim understands a number of key bindings that execute NetBeans commands. These
are typically all the Function key combinations. To execute a NetBeans command,
the user must press the Pause key followed by a NetBeans key binding. For
example, in order to compile a Java file, the NetBeans key binding is "F9". So,
while in vim, press "Pause F9" to compile a java file. To toggle a breakpoint
at the current line, press "Pause Shift F8".
The Pause key is Function key 21. If you don't have a working Pause key and
want to use F8 instead, use: >
:map <F8> <F21>
The External Editor module dynamically reads the NetBeans key bindings so vim
should always have the latest key bindings, even when NetBeans changes them.
==============================================================================
3. Configuring Vim for NetBeans *netbeans-configure*
For more help installing vim, please read |usr_90.txt| in the Vim User Manual.
On Unix
When running configure without arguments the NetBeans interface should be
included. That is, if the configure check to find out if your system supports
the required features succeeds.
In case you do not want the NetBeans interface you can disable it by
uncommenting a line with "--disable-netbeans" in the Makefile.
Currently, only gvim is supported in this integration as NetBeans does not
have means to supply a terminal emulator for the vim command. Furthermore,
there is only GUI support for GTK, GNOME, and Motif.
If Motif support is required the user must supply XPM libraries. See
|workshop-xpm| for details on obtaining the latest version of XPM.
On MS-Windows
The Win32 support is now in beta stage.
To use XPM signs on Win32 (e.g. when using with NetBeans) you can compile
XPM by yourself or use precompiled libraries from http://iamphet.nm.ru/misc/
(for MS Visual C++) or http://gnuwin32.sourceforge.net (for MinGW).
==============================================================================
4. Downloading NetBeans *netbeans-download*
The NetBeans IDE is available for download from netbeans.org. You can download
a released version, download sources, or use CVS to download the current
source tree. If you choose to download sources, follow directions from
netbeans.org on building NetBeans.
Depending on the version of NetBeans you download, you may need to do further
work to get the required External Editor module. This is the module which lets
NetBeans work with gvim (or xemacs :-). See http://externaleditor.netbeans.org
for details on downloading this module if your NetBeans release does not have
it.
For C, C++, and Fortran support you will also need the cpp module. See
http://cpp.netbeans.org for information regarding this module.
You can also download Sun ONE Studio from Sun Microsystems, Inc for a 30 day
free trial. See http://www.sun.com for further details.
==============================================================================
5. Preparing NetBeans for Vim *netbeans-preparation*
In order for NetBeans to work with vim, the NetBeans External Editor module
must be loaded and enabled. If you have a Sun ONE Studio Enterprise Edition
then this module should be loaded and enabled. If you have a NetBeans release
you may need to find another way of obtaining this open source module.
You can check if you have this module by opening the Tools->Options dialog
and drilling down to the "Modules" list (IDE Configuration->System->Modules).
If your Modules list has an entry for "External Editor" you must make sure
it is enabled (the "Enabled" property should have the value "True"). If your
Modules list has no External Editor see the next section on |obtaining-exted|.
==============================================================================
6. Obtaining the External Editor Module *obtaining-exted*
There are 2 ways of obtaining the External Editor module. The easiest way
is to use the NetBeans Update Center to download and install the module.
Unfortunately, some versions do not have this module in their update
center. If you cannot download via the update center you will need to
download sources and build the module. I will try and get the module
available from the NetBeans Update Center so building will be unnecessary.
Also check http://externaleditor.netbeans.org for other availability options.
To download the External Editor sources via CVS and build your own module,
see http://externaleditor.netbeans.org and http://www.netbeans.org.
Unfortunately, this is not a trivial procedure.
==============================================================================
7. Setting up NetBeans to run with Vim *netbeans-setup*
Assuming you have loaded and enabled the NetBeans External Editor module
as described in |netbeans-preparation| all you need to do is verify that
the gvim command line is properly configured for your environment.
Open the Tools->Options dialog and open the Editing category. Select the
External Editor. The right hand pane should contain a Properties tab and
an Expert tab. In the Properties tab make sure the "Editor Type" is set
to "Vim". In the Expert tab make sure the "Vim Command" is correct.
You should be careful if you change the "Vim Command". There are command
line options there which must be there for the connection to be properly
set up. You can change the command name but thats about it. If your gvim
can be found by your $PATH then the VIM Command can start with "gvim". If
you don't want gvim searched from your $PATH then hard code in the full
Unix path name. At this point you should get a gvim for any source file
you open in NetBeans.
If some files come up in gvim and others (with different file suffixes) come
up in the default NetBeans editor you should verify the MIME type in the
Expert tab MIME Type property. NetBeans is MIME oriented and the External
Editor will only open MIME types specified in this property.
==============================================================================
8. Messages *netbeans-messages*
These messages are specific for NetBeans:
*E463*
Region is guarded, cannot modify
NetBeans defines guarded areas in the text, which you cannot
change.
*E656*
NetBeans dissallows writes of unmodified buffers
NetBeans does not support writes of unmodified buffers that
were opened from NetBeans.
*E657*
Partial writes disallowed for NetBeans buffers
NetBeans does not support partial writes for buffers that were
opened from NetBeans.
*E658*
NetBeans connection lost for this buffer
NetBeans has become confused about the state of this file.
Rather than risc data corruption, NetBeans has severed the
connection for this file. Vim will take over responsibility
for saving changes to this file and NetBeans will no longer
know of these changes.
==============================================================================
9. Running Vim from NetBeans *netbeans-run*
NetBeans starts Vim with the |-nb| argument. Three forms can be used, that
differ in the way the information for the connection is specified:
-nb={fname} from a file
-nb:{hostname}:{addr}:{password} directly
-nb from a file or environment
*E660* *E668*
For security reasons, the best method is to write the information in a file
readable only by the user. The name of the file can be passed with the
"-nb={fname}" argument or, when "-nb" is used without a parameter, the
environment variable "__NETBEANS_CONINFO". The file must contain these three
lines, in any order:
host={hostname}
port={addr}
auth={password}
Other lines are ignored. The caller of Vim is responsible for deleting the
file afterwards.
{hostname} is the name of the machine where NetBeans is running. When omitted
the environment variable "__NETBEANS_HOST" is used or the default "localhost".
{addr} is the port number for NetBeans. When omitted the environment variable
"__NETBEANS_SOCKET" is used or the default 3219.
{password} is the password for connecting to NetBeans. When omitted the
environment variable "__NETBEANS_VIM_PASSWORD" is used or "changeme".
==============================================================================
10. NetBeans protocol *netbeans-protocol*
The communication between NetBeans and Vim uses plain text messages. This
protocol was first designed to work with the external editor module of
NetBeans (see http://externaleditor.netbeans.org). Later it was extended to
work with Agide (A-A-P GUI IDE, see http://www.a-a-p.org). The extensions are
marked with "version 2.1".
Version 2.2 of the protocol has several minor changes which should only
affect NetBeans users (ie, not Agide users). However, a bug was fixed which
could cause confusion. The netbeans_saved() function sent a "save" protocol
command. In protocol version 2.1 and earlier this was incorrectly interpreted
as a notification that a write had taken place. In reality, it told NetBeans
to save the file so multiple writes were being done. This caused various
problems and has been fixed in 2.2. To decrease the likelyhood of this
confusion happening again, netbeans_saved() has been renamed to
netbeans_save_buffer().
The messages are currently sent over a socket. Since the messages are in
plain UTF-8 text this protocol could also be used with any other communication
mechanism.
10.1 Kinds of messages |nb-messages|
10.2 Terms |nb-terms|
10.3 Commands |nb-commands|
10.4 Functions and Replies |nb-functions|
10.5 Events |nb-events|
10.6 Special messages |nb-special|
*E627* *E628* *E629* *E630* *E631* *E632* *E633* *E634* *E635* *E636*
*E637* *E638* *E639* *E640* *E641* *E642* *E643* *E644* *E645* *E646*
*E647* *E648* *E649* *E650* *E651* *E652* *E653* *E654*
These errors occur when a message violates the protocol.
10.1 Kinds of messages *nb-messages*
There are four kinds of messages:
kind direction comment ~
Command IDE -> editor no reply necessary
Function IDE -> editor editor must send back a reply
Reply editor -> IDE only in response to a Function
Event editor -> IDE no reply necessary
The messages are sent as a single line with a terminating newline character.
Arguments are separated by a single space. The first item of the message
depends on the kind of message:
kind first item example ~
Command bufID:name!seqno 11:showBalloon!123 "text"
Function bufID:name/seqno 11:getLength/123
Reply seqno 123 5000
Event bufID:name=123 11:keyCommand=123 "S-F2"
10.2 Terms *nb-terms*
bufID Buffer number. A message may be either for a specific buffer
or generic. Generic messages use a bufID of zero. NOTE: this
buffer ID is assigned by the IDE, it is not Vim's buffer
number. The bufID must be a sequentially rising number,
starting at one.
seqno The IDE uses a sequence number for Commands and Functions. A
Reply must use the sequence number of the Function that it is
associated with. A zero sequence number can be used for
Events (the seqno of the last received Command or Function can
also be used).
string Argument in double quotes. Text is in UTF-8 encoding. This
means ASCII is passed as-is. Special characters are
represented with a backslash:
\" double quote
\n newline
\r carriage-return
\t tab (optional, also works literally)
\\ backslash
NUL bytes are not allowed!
boolean Argument with two possible values:
T true
F false
number Argument with a decimal number.
optnum Argument with either a decimal number or "none" (without the
quotes).
offset A number argument that indicates a byte position in a buffer.
The first byte has offset zero. Line breaks are counted for
how they appear in the file (CR/LF counts for two bytes).
Note that a multi-byte character is counted for the number of
bytes it takes.
lnum/col Argument with a line number and column number position. The
line number starts with one, the column is the byte position,
starting with zero. Note that a multi-byte character counts
for several columns.
pathname String argument: file name with full path.
10.3 Commands *nb-commands*
actionMenuItem Not implemented.
actionSensitivity
Not implemented.
addAnno serNum typeNum off len
Place an annotation in this buffer.
Arguments:
serNum number serial number of this placed
annotation, used to be able to remove
it
typeNum number sequence number of the annotation
defined with defineAnnoType for this
buffer
off number offset where annotation is to be placed
len number not used
In version 2.1 "lnum/col" can be used instead of "off".
balloonResult text
Not implemented.
close Close the buffer. This leaves us without current buffer, very
dangerous to use!
create Creates a buffer without a name. Replaces the current buffer
(it's hidden when it was changed).
NetBeans uses this as the first command for a file that is
being opened. The sequence of commands could be:
create
setCaretListener (ignored)
setModified (no effect)
setContentType (ignored)
startDocumentListen
setTitle
setFullName
defineAnnoType typeNum typeName tooltip glyphFile fg bg
Define a type of annotation for this buffer.
Arguments:
typeNum number sequence number (not really used)
typeName string name that identifies this annotation
tooltip string not used
glyphFile string name of icon file
fg optnum foreground color for line highlighting
bg optnum background color for line highlighting
Vim will define a sign for the annotation.
When both "fg" and "bg" are "none" no line highlighting is
used (new in version 2.1).
When "glyphFile" is empty, no text sign is used (new in
version 2.1).
When "glyphFile" is one or two characters long, a text sign is
defined (new in version 2.1).
Note: the annotations will be defined in sequence, and the
sequence number is later used with addAnno.
editFile pathname
Set the name for the buffer and edit the file "pathname", a
string argument.
Normal way for the IDE to tell the editor to edit a file. If
the IDE is going to pass the file text to the editor use these
commands instead:
setFullName
insert
initDone
New in version 2.1.
enableBalloonEval
Not implemented.
endAtomic End an atomic operation. The changes between "startAtomic"
and "endAtomic" can be undone as one operation. But it's not
implemented yet. Redraw when necessary.
guard off len
Mark an area in the buffer as guarded. This means it cannot
be edited. "off" and "len" are numbers and specify the text
to be guarded.
initDone Mark the buffer as ready for use. Implicitly makes the buffer
the current buffer. Fires the BufReadPost autocommand event.
moveAnnoToFront serNum
Not implemented.
netbeansBuffer isNetbeansBuffer
If "isNetbeansBuffer" is "T" then this buffer is ``owned'' by
NetBeans.
New in version 2.2.
putBufferNumber pathname
Associate a buffer number with the Vim buffer by the name
"pathname", a string argument. To be used when the editor
reported editing another file to the IDE and the IDE needs to
tell the editor what buffer number it will use for this file.
Also marks the buffer as initialized.
New in version 2.1.
raise Bring the editor to the foreground.
New in version 2.1.
removeAnno serNum
Remove a previously place annotation for this buffer.
"serNum" is the same number used in addAnno.
save Save the buffer when it was modified. The other side of the
interface is expected to write the buffer and invoke
"setModified" to reset the "changed" flag of the buffer.
The writing is skipped when one of these conditions is true:
- 'write' is not set
- the buffer is read-only
- the buffer does not have a file name
- 'buftype' disallows writing
New in version 2.2.
setAsUser Not implemented.
setBufferNumber pathname
Associate a buffer number with Vim buffer by the name
"pathname". To be used when the editor reported editing
another file to the IDE and the IDE needs to tell the editor
what buffer number it will use for this file.
Has the side effect of making the buffer the current buffer.
See "putBufferNumber" for a more useful command.
setContentType
Not implemented.
setDot off Make the buffer the current buffer and set the cursor at the
specified position. If there are folds they are opened to
make the cursor line visible.
In version 2.1 "lnum/col" can be used instead of "off".
setExitDelay seconds
Set the delay for exiting to "seconds", a number.
This delay is used to give the IDE a chance to handle things
before really exiting. The default delay is two seconds.
New in version 2.1.
setFullName pathname
Set the file name to be used for a buffer to "pathname", a
string argument.
Used when the IDE wants to edit a file under control of the
IDE. This makes the buffer the current buffer, but does not
read the file. "insert" commands will be used next to set the
contents.
setLocAndSize Not implemented.
setMark Not implemented.
setModified modified
When the boolean argument "modified" is "T" mark the buffer as
modified, when it is "F" mark it as unmodified.
setReadOnly Not implemented.
setStyle Not implemented.
setTitle name
Set the title for the buffer to "name", a string argument.
The title is only used for NetBeans functions, not by Vim.
setVisible visible
When the boolean argument "visible" is "T", goto the buffer.
The "F" argument does nothing.
showBalloon text
Show a balloon (popup window) at the mouse pointer position,
containing "text", a string argument. The balloon should
disappear when the mouse is moved more than a few pixels.
New in version 2.1.
specialKeys Not implemented.
startAtomic Begin an atomic operation. The screen will not be updated
until "endAtomic" is given.
startCaretListen
Not implemented.
startDocumentListen
Mark the buffer to report changes to the IDE with the
"insert" and "remove" events. The default is to report
changes.
stopCaretListen
Not implemented.
stopDocumentListen
Mark the buffer to stop reporting changes to the IDE.
Opposite of startDocumentListen.
unguard off len
Opposite of "guard", remove guarding for a text area.
version Not implemented.
10.4 Functions and Replies *nb-functions*
getDot Not implemented.
getCursor Return the current buffer and cursor position.
The reply is:
seqno bufID lnum col off
seqno = sequence number of the function
bufID = buffer ID of the current buffer (if this is unknown -1
is used)
lnum = line number of the cursor (first line is one)
col = column number of the cursor (in bytes, zero based)
off = offset of the cursor in the buffer (in bytes)
New in version 2.1.
getLength Return the length of the buffer in bytes.
Reply example for a buffer with 5000 bytes:
123 5000
TODO: explain use of partial line.
getMark Not implemented.
getModified When a buffer is specified: Return zero if the buffer does not
have changes, one if it does have changes.
When no buffer is specified (buffer number zero): Return the
number of buffers with changes. When the result is zero it's
safe to tell Vim to exit.
New in version 2.1.
getText Return the contents of the buffer as a string.
Reply example for a buffer with two lines
123 "first line\nsecond line\n"
NOTE: docs indicate an offset and length argument, but this is
not implemented.
insert off text
Insert "text" before position "off". "text" is a string
argument, "off" a number.
Possible replies:
123 no problem
123 !message failed
Note that the message in the reply is not quoted.
remove off length
Delete "length" bytes of text at position "off". Both
arguments are numbers.
Possible replies:
123 no problem
123 !message failed
Note that the message in the reply is not quoted.
saveAndExit Perform the equivalent of closing Vim: ":confirm qall".
If there are no changed files or the user does not cancel the
operation Vim exits and no result is sent back. The IDE can
consider closing the connection as a successful result.
If the user cancels the operation the number of modified
buffers that remains is returned and Vim does not exit.
New in version 2.1.
10.5 Events *nb-events*
balloonEval off len type
The mouse pointer rests on text for a short while. When "len"
is zero, there is no selection and the pointer is at position
"off". When "len" is non-zero the text from position "off" to
"off" + "len" is selected.
Only sent after "enableBalloonEval" was used for this buffer.
"type" is not yet defined.
Not implemented yet.
balloonText text
Used when 'ballooneval' is set and the mouse pointer rests on
some text for a moment. "text" is a string, the text under
the mouse pointer.
New in version 2.1.
buttonRelease button lnum col
Report which button was pressed and the location of the cursor
at the time of the release. Only for buffers that are owned
by NetBeans. This event is not sent if the button was
released while the mouse was in the status line or in a
separator line. If col is less than 1 the button release was
in the sign area.
New in version 2.2.
fileClosed Not implemented.
fileModified Not implemented.
fileOpened pathname open modified
A file was opened by the user.
Arguments:
pathname string name of the file
open boolean always "T"
modified boolean always "F"
geometry cols rows x y
Report the size and position of the editor window.
Arguments:
cols number number of text columns
rows number number of text rows
x number pixel position on screen
y number pixel position on screen
Only works for Motif.
insert off text
Text "text" has been inserted in Vim at position "off".
Only fired when enabled, see "startDocumentListen".
invokeAction Not implemented.
keyCommand keyName
Reports a special key being pressed with name "keyName", which
is a string.
Supported key names:
F1 function key 1
F2 function key 2
...
F12 function key 12
' ' space (without the quotes)
! exclamation mark
... any other ASCII printable character
~ tilde
X any unrecognized key
The key may be prepended by "C", "S" and/or "M" for Control,
Shift and Meta (Alt) modifiers. If there is a modifier a dash
is used to separate it from the key name. For example:
"C-F2".
ASCII characters are new in version 2.1.
keyAtPos keyName lnum/col
Like "keyCommand" and also report the line number and column
of the cursor.
New in version 2.1.
killed A file was closed by the user. Only for files that have been
assigned a number by the IDE.
newDotAndMark off off
Reports the position of the cursor being at "off" bytes into
the buffer. Only sent just before a "keyCommand" event.
quit Not implemented.
remove off len
Text was deleted in Vim at position "off" with byte length
"len".
Only fired when enabled, see "startDocumentListen".
revert Not implemented.
save The buffer has been saved and is now unmodified.
Only fired when enabled, see "startDocumentListen".
startupDone The editor has finished its startup work and is ready for
editing files.
New in version 2.1.
unmodified The buffer is now unmodified.
Only fired when enabled, see "startDocumentListen".
version vers Report the version of the interface implementation. Vim
reports "2.2" (including the quotes).
10.6 Special messages *nb-special*
These messages do not follow the style of the messages above. They are
terminated by a newline character.
ACCEPT Not used.
AUTH password editor -> IDE: First message that the editor sends to the IDE.
Must contain the password for the socket server, as specified
with the |-nb| argument. No quotes are used!
DISCONNECT IDE -> editor: break the connection. The editor will exit.
The IDE must only send this message when there are no unsaved
changes!
DETACH IDE -> editor: break the connection without exiting the
editor. Used when the IDE exits without bringing down the
editor as well.
New in version 2.1.
REJECT Not used.
==============================================================================
11. Known problems *netbeans-problems*
NUL bytes are not possible. For editor -> IDE they will appear as NL
characters. For IDE -> editor they cannot be inserted.
vim:tw=78:ts=8:ft=help:norl:

6826
runtime/doc/options.txt Normal file
View File

File diff suppressed because it is too large Load Diff

340
runtime/doc/os_390.txt Normal file
View File

@@ -0,0 +1,340 @@
*os_390.txt* For Vim version 7.0aa. Last change: 2003 Jun 03
VIM REFERENCE MANUAL by Ralf Schandl
*zOS* *z/OS* *OS390* *os390* *MVS*
This file contains the particulars for the z/OS UNIX version of Vim.
1. Open source on z/OS UNIX |zOS-open-source|
2. Your feedback is needed |zOS-feedback|
3. Building VIM for z/OS UNIX |zOS-building|
4. ASCII/EBCDIC dependent scripts |zOS-has-ebcdic|
5. XTerm Problems |zOS-xterm|
6. Motif Problems |zOS-Motif|
7 Bugs |zOS-Bugs|
8. Known weaknesses |zOS-weaknesses|
9. Changes |zOS-changes|
DISCLAIMER: ~
We are IBM employees, but IBM is not responsible for this port. This is our
private fun, and is provided in the hopes that it may be useful to others.
Please note that this software has NOT been submitted to any formal IBM
testing and is published AS IS. Please do not contact IBM for support for this
software, as it is not an official component of any IBM product. IT IS NOT
SUPPORTED, GUARANTEED, OR RELATED WHATSOEVER TO IBM.
Contributors: ~
The port to z/OS UNIX was done by Ralf Schandl for the Redbook mentioned
below.
Changes, bug-reports, or both by:
David Moore
Anthony Giorgio <agiorgio@fastmail.fm>
and others
This document was written by Ralf Schandl and revised by Anthony Giorgio.
==============================================================================
1. Open source on z/OS UNIX *OS390-open-source* *zOS-open-source*
If you are interested in other Open Source Software on z/OS UNIX, have a
look at the following Redbook:
Mike MacIsaac et al
"Open Source Software for z/OS and OS/390 UNIX"
IBM Form Number: SG24-5944-01
ISBN: 0738424633
You can find out more information, order a hard copy, or download a PDF
version of these Redbooks at:
http://www.redbooks.ibm.com
==============================================================================
2. Your feedback is needed *OS390-feedback* *zOS-feedback*
Vim should compile, link, and run right out of the box on a standard IBM z/OS
UNIX mainframe. I've personally run it on z/OS V1R2 and V1R3 machines without
problems.
Many changes had to be done to the code to port Vim to z/OS UNIX. As like
most UNIX programs, Vim contained heavy ASCII dependencies. I might have
missed an ASCII dependency, or it is possible that a new one has been added
with a feature or bug fix. Most programmers are simply not aware of possible
ASCII/EBCDIC conversion issues. If you hit a problem that seems related to
this, feel free to contact us at the email addresses above.
One indication of ASCII/EBCDIC conversion problems is screen corruption with
"unprintable" characters. For example, at one point the errorbell was broken
in Vim. Any time Vim tried to ring the terminal bell an ASCII character 0x07
would be printed. This works fine on most terminals, but is broken on an
EBCDIC one. The correct solution was to define a different value for the bell
character on EBCDIC systems.
Remember, it's only possible to fix a bug if the community knows about it.
Don't rely on someone else to report it! See the section |bug-reports|.
==============================================================================
3. Building VIM for z/OS UNIX *OS390-building* *zOS-building*
A word on debugging code first: ~
The normal run of configure adds the flag '-g' to the compiler options,
to include debugging information into the executable. This information
are normally removed from the executable with the strip command during
installation. On z/OS UNIX, it is not possible to remove this from
the executable. The strip command exists on z/OS UNIX and is called
during the installation, but it does nothing. It is equivalent to the
'touch' command. This is due to the way debug symbols are stored in the
objects generated by the compiler.
If you want to build Vim without debugging code, export the environment
variable CFLAGS set to an empty string before you call the configure script.
>
export CFLAGS=""
Building without X11: ~
Note: Use cc to build Vim. The c89 compiler has stricter syntax checking
and will not compile Vim cleanly.
If you build VIM without X11 support, compiling and building is
straightforward. Don't forget to export _CC_CCMODE=1 before calling
configure and make.
>
$ export _CC_CCMODE=1
$./configure --with-features=big --without-x --enable-gui=no
$ make
$ make test
<
Test notes:
Test 11 will fail if you do not have gzip installed.
Test 42 will fail, as VIM on z/OS UNIX doesn't support the multibyte
feature. (David Moore: "Doesn't work _yet_! :-) I'll see what I
can do.")
>
$ make install
Building with X11: ~
There are two ways for building Vim with X11 support. You can link it
statically with the X11 libraries or can bind it with the X11 DLLs. The
statically linked version results in a huge executable (~13MB), while the
dynamically linked executable is much smaller (~4.5MB).
Here is what you do, if you want Motif:
a) Static link >
$ configure --with-features=big --enable-gui=motif
$ make
<
VIM is now linked statically with the X11 libraries.
b) Dynamic link:
Make VIM as described for the static link. Then change the contents of
the 'auto/link.sed' file by appending: >
s%-lXm *%/usr/lib/Xm.x %g
s%-lX11 *%/usr/lib/X11.x %g
s%-lSM *%/usr/lib/SM.x %g
s%-lICE *%/usr/lib/ICE.x %g
<
Then do: >
$ rm vim
$ make
<
Now Vim is linked with the X11-DLLs.
See the Makefile and the file link.sh on how link.sed is used.
==============================================================================
4. ASCII/EBCDIC dependent scripts *OS390-has-ebcdic* *zOS-has-ebcdic*
For the internal script language the feature "ebcdic" was added. With this
you can fix ASCII dependent scripts like this:
>
if has("ebcdic")
let space = 64
else
let space = 32
endif
<
==============================================================================
5. XTerm problems *OS390-xterm* *zOS-xterm*
Note: This problem was resolved in version 6.1b. ~
I saw one problem with XTerm on z/OS UNIX. The terminal code for moving the
cursor to the left is wrong in the termlib database. Perhaps not wrong, but
it didn't work with VIM syntax highlighting and command line cursor movement.
If the highlighting is messed up while you type, but is okay after you refreshed
the screen with <C-L> or if you can't move to the left with the cursor key on
the command line, try adding >
:set t_le=^H
<
to your .vimrc. Note: '^H' is one character, hit <C-V><C-H> to get it.
==============================================================================
6. Motif Problems *OS390-Motif* *zOS-Motif*
It seems that in porting the Motif library to z/OS, a translation from EBCDIC
to ASCII for the accelerator characters of the pull-down menus was forgotten.
Even after I tried to hand convert the menus, the accelerator keys continued
to only work for the opening of menus (like <Alt-F> to open the file menu).
They still do not work for the menu items themselves (like <Alt-F>O to open
the file browser).
There is no solution for this as of yet.
==============================================================================
7. Bugs *OS390-bugs* *zOS-Bugs*
- Vim will consistently hang when a large amount of text is selected in
visual block mode. This may be due to a memory corruption issue. Note that
this occurs in both the terminal and gui versions.
==============================================================================
8. Known weaknesses *OS390-weaknesses* *zOS-weaknesses*
- No binary search in tag files.
The program /bin/sort sorts by ASCII value by default. This program is
normally used by ctags to sort the tags. There might be a version of
ctags out there, that does it right, but we can't be sure. So this seems to
be a permanent restriction.
- Multibyte support (utf-8) doesn't work, it's disabled at compile time.
(|multibyte|)
- The cscope interface (|cscope|) doesn't work for the version of cscope
that we use on our mainframe. We have a copy of version 15.0b12, and it
causes Vim to hang when using the "cscope add" command. I'm guessing that
the binary format of the cscope database isn't quite what Vim is expecting.
I've tried to port the current version of cscope (15.3) to z/OS, without
much success. If anyone is interested in trying, drop me a line if you
make any progress.
- No glib/gtk support. I have not been able to successfully compile glib on
z/OS UNIX. This means you'll have to live without the pretty gtk toolbar.
Never tested:
- Perl interface (|perl|)
- Hangul input (|hangul|)
- Encryption support (|encryption|)
- Langmap (|'langmap'|)
- Python support (|Python|)
- Right-to-left mode (|'rightleft'|)
- SNiFF+ interface (|sniff|)
- TCL interface (|tcl|)
...
If you try any of these features and they work, drop us a note!
==============================================================================
9. Changes *OS390-changes* *zOS-changes*
This is a small reference of the changes made to the z/OS port of Vim. It is
not an exhaustive summary of all the modifications made to the code base.
6.1b (beta):
Changed KS_LE in term.c to be "\b" instead of "\010" This fixed the
screen corruption problems in gVim reported by Anthony Giorgio.
Anthony Giorgio updated this document:
- Changed OS/390 to z/OS where appropriate. IBM decided to rename
all of its servers and operating systems. z/OS and OS/390
are the same product, but the version numbering system was
reset for the name change. (e.g. OS/390 V2R11 == z/OS V1R1)
- Added information about second edition of the Open Source Redbook.
- Moved Redbook information to a separate section.
- Various tweaks and changes.
- Updated testing section.
6.0au:
Changed configure.in
Changed documentation.
Anthony Giorgio fixed the errorbell.
David Moore found some problems, which were fixed by Bram and/or David for
6.0au.
6.0q (alpha):
Minor changes for nrformats=alpha (see |'nrformats'|).
Problem with hard-coded keycode for the English pound sign. Added a define in
ascii.h
Disabled multibyte for EBCDIC in feature.h
6.0f (alpha):
First compile of Vim 6 on z/OS UNIX. Some minor changes were needed.
Finally found the reason why make from the top level didn't work (I must have
been blind before!). The Makefile contained a list of targets in one target
line. On all other UNIX's the macro $@ evaluates to the first target in this
list, only on z/OS UNIX it evaluates to the last one :-(.
5.6-390d:
Cleaned up some hacks.
5.6-390c:
I grepped through the source and examined every spot with a character
involved in a operation (+-). I hope I now found all EBCDIC/ASCII
stuff, but ....
Fixed:
- fixed warning message in do_fixdel()
- fixed translation from Ctrl-Char to symbolic name (like ^h to CTRL-H)
for :help
- fixed yank/delete/... into register
- fixed :register command
- fixed viminfo register storing
- fixed quick-access table in findoptions()
- fixed 'g^H' select mode
- fixed tgetstr() 'get terminal capability string', ESC and
Ctrl chars where wrong. (Not used on OS/390 UNIX)
ctags:
- added trigraphs support (used in prolog of system header files)
(get.c)
- fixed sorting order with LC_COLLATE=S390 to force EBCDIC sorting.
(sort.c)
5.6-390b:
Changed:
- configure.in:
- added test for OS/390 UNIX
- added special compiler and linker options if building with X11
- configure:
- after created via autoconf hand-edited it to make the test for
ICEConnectionNumber work. This is a autoconf problem. OS/390 UNIX
needs -lX11 for this.
- Makefile
- Don't include the lib directories ('-L...') into the variable
ALL_LIBS. Use own variable ALL_LIB_DIRS instead. A fully POSIX
compliant compiler must not accept objects/libraries and options
mixed. Now we can call the linker like this:
$(CC) $(LDFLAGS) $(ALL_LIB_DIRS) $(OBJ) $(ALL_LIBS)
Fixed:
- Double quote couldn't be entered
Missed ASCII dependencies while setting up terminal
In ASCII 127 is the delete char, in EBCDIC codepage 1047 the value 127
is the double quote.
- fixed ':fixdel'
5.6-390a:
first alpha release for OS/390 UNIX.
Addition:
- For the internal script language I added the feature "ebcdic".
This can be queried with the has()-function of the internal
script language.
------------------------------------------------------------------------------
vim:tw=78:fo=tcq2:ts=8:ft=help:norl:

139
runtime/doc/os_amiga.txt Normal file
View File

@@ -0,0 +1,139 @@
*os_amiga.txt* For Vim version 7.0aa. Last change: 2004 Apr 25
VIM REFERENCE MANUAL by Bram Moolenaar
*Amiga*
This file contains the particularities for the Amiga version of Vim.
There is also a section specifically for |MorphOS| below.
Installation on the Amiga:
- Assign "VIM:" to the directory where the Vim "doc" directory is. Vim will
look for the file "VIM:doc/help.txt" (for the help command).
Setting the environment variable $VIM also works. And the other way around:
when $VIM used and it is not defined, "VIM:" is used.
- With DOS 1.3 or earlier: Put "arp.library" in "libs:". Vim must have been
compiled with the |+ARP| feature enabled. Make sure that newcli and run are
in "C:" (for executing external commands).
- Put a shell that accepts a command with "-c" (e.g. "Csh" from Fish disk
624) in "c:" or in any other directory that is in your search path (for
executing external commands).
If you have sufficient memory you can avoid startup delays by making Vim and
csh resident with the command "rez csh vim". You will have to put
"rezlib.library" in your "libs:" directory. Under 2.0 you will need rez
version 0.5.
If you do not use digraphs, you can save some memory by recompiling without
the |+digraphs| feature. If you want to use Vim with other terminals you can
recompile with the TERMCAP option. Vim compiles with Manx 5.x and SAS 6.x.
See the makefiles and feature.h.
If you want to use different colors set the termcap codes:
t_mr (for inverted text)
t_md (for bold text)
t_me (for normal text after t_mr and t_md)
t_so (for standout mode)
t_se (for normal text after t_so)
t_us (for underlined text)
t_ue (for normal text after t_us)
t_ZH (for italic text)
t_ZR (for normal text after t_ZH)
Standard ANSI escape sequences are used. The codes are:
30 grey char 40 grey cell >0 grey background 0 all attributes off
31 black char 41 black cell >1 black background 1 boldface
32 white char 42 white cell >2 white background 2 faint
33 blue char 43 blue cell >3 blue background 3 italic
34 grey char 44 grey cell >4 grey background 4 underscore
35 black char 45 black cell >5 black background 7 reverse video
36 white char 46 white cell >6 white background 8 invisible
37 blue char 47 blue cell >7 blue background
The codes with '>' must be the last. The cell and background color should be
the same. The codes can be combined by separating them with a semicolon. For
example to get white text on a blue background: >
:set t_me=^V<Esc>[0;32;43;>3m
:set t_se=^V<Esc>[0;32;43;>3m
:set t_ue=^V<Esc>[0;32;43;>3m
:set t_ZR=^V<Esc>[0;32;43;>3m
:set t_md=^V<Esc>[1;32;43;>3m
:set t_mr=^V<Esc>[7;32;43;>3m
:set t_so=^V<Esc>[0;31;43;>3m
:set t_us=^V<Esc>[4;32;43;>3m
:set t_ZH=^V<Esc>[3;32;43;>3m
When using multiple commands with a filter command, e.g. >
:r! echo this; echo that
Only the output of the last command is used. To fix this you have to group the
commands. This depends on the shell you use (that is why it is not done
automatically in Vim). Examples: >
:r! (echo this; echo that)
:r! {echo this; echo that}
Commands that accept a single file name allow for embedded spaces in the file
name. However, when using commands that accept several file names, embedded
spaces need to be escaped with a backslash.
------------------------------------------------------------------------------
Vim for MorphOS *MorphOS*
[this section mostly by Ali Akcaagac]
For the latest info about the MorphOS version:
http://www.akcaagac.com/index_vim.html
Problems ~
There are a couple of problems which are not MorphOS related but more Vim and
UN*X related. When starting up Vim in ram: it complains with a nag requester
from MorphOS please simply ignore it. Another problem is when running Vim as
is some plugins will cause a few problems which you can ignore as well.
Hopefully someone will be fixing it over the time.
To pass all these problems for now you can either run:
vim <file to be edited>
or if you want to run Vim plain and enjoy the motion of Helpfiles etc. it then
would be better to enter:
vim --noplugins <of course you can add a file>
Installation ~
1) Please copy the binary 'VIM' file to c:
2) Get the Vim runtime package from:
ftp://ftp.vim.org/pub/vim/amiga/vim62rt.tgz
and unpack it in your 'Apps' directory of the MorphOS installation. For me
this would create following directory hierarchy:
MorphOS:Apps/Vim/Vim62/...
3) Add the following lines to your s:shell-startup (Important!).
;Begin VIM
Set VIM=MorphOS:Apps/Vim/Vim62
Assign HOME: ""
;End VIM
4) Copy the '.vimrc' file to s:
5) There is also a file named 'color-sequence' included in this archive. This
will set the MorphOS Shell to show ANSI colors. Please copy the file to s:
and change the s:shell-startup to:
;Begin VIM
Set VIM=MorphOS:Apps/Vim/Vim62
Assign HOME: ""
Execute S:Color-Sequence
Cls
;End VIM
vim:tw=78:ts=8:ft=help:norl:

348
runtime/doc/os_beos.txt Normal file
View File

@@ -0,0 +1,348 @@
*os_beos.txt* For Vim version 7.0aa. Last change: 2004 May 01
VIM REFERENCE MANUAL by Bram Moolenaar
*BeOS* *BeBox*
This is a port of Vim 5.1 to the BeOS Preview Release 2 (also known as PR2)
or later.
This file contains the particularities for the BeBox/BeOS version of Vim. For
matters not discussed in this file, Vim behaves very much like the Unix
|os_unix.txt| version.
1. General |beos-general|
2. Compiling Vim |beos-compiling|
3. Timeout in the Terminal |beos-timeout|
4. Unicode vs. Latin1 |beos-unicode|
5. The BeOS GUI |beos-gui|
6. The $VIM directory |beos-vimdir|
7. Drag & Drop |beos-dragndrop|
8. Single Launch vs. Multiple
Launch |beos-launch|
9. Fonts |beos-fonts|
10. The meta key modifier |beos-meta|
11. Mouse key mappings |beos-mouse|
12. Color names |beos-colors|
13. Compiling with Perl |beos-perl|
1. General *beos-general*
The default syntax highlighting mostly works with different foreground colors
to highlight items. This works best if you set your Terminal window to a
darkish background and light letters. Some middle-grey background (for
instance (r,g,b)=(168,168,168)) with black letters also works nicely. If you
use the default light background and dark letters, it may look better to
simply reverse the notion of foreground and background color settings. To do
this, add this to your .vimrc file (where <Esc> may need to be replaced with
the escape character): >
:if &term == "beos-ansi"
: set t_AB=<Esc>[3%dm
: set t_AF=<Esc>[4%dm
:endif
2. Compiling Vim *beos-compiling*
From the Advanced Access Preview Release (AAPR) on, Vim can be configured with
the standard configure script. To get the compiler and its flags right, use
the following command-line in the shell (you can cut and paste it in one go):
CC=$BE_C_COMPILER CFLAGS="$BE_DEFAULT_C_FLAGS -O7" \
./configure --prefix=/boot/home/config
$BE_C_COMPILER is usually "mwcc", $BE_DEFAULT_C_FLAGS is usually "-I- -I."
When configure has run, and you wish to enable GUI support, you must edit the
config.mk file so that the lines with GUI_xxx refer to $(BEOSGUI_xxx) instead
of $(NONE_xxx).
Alternatively you can make this change in the Makefile; it will have a
more permanent effect. Search for "NONE_".
After compilation you need to add the resources to the binary. Add the
following few lines near the end (before the line with "exit $exit_value") of
the link.sh script to do this automatically.
rmattr BEOS:TYPE vim
copyres os_beos.rsrc vim
mimeset vim
Also, create a dummy file "strip":
#!/bin/sh
mimeset $1
exit 0
You will need it when using "make install" to install Vim.
Now type "make" to compile Vim, then "make install" to install it.
If you want to install Vim by hand, you must copy Vim to $HOME/config/bin, and
create a bunch of symlinks to it ({g,r,rg}{vim,ex,view}). Furthermore you must
copy Vims configuration files to $HOME/config/share/vim:
vim-5.0s/{*.vim,doc,syntax}. For completeness, you should also copy the nroff
manual pages to $HOME/config/man/man1. Don't forget ctags/ctags and xxd/xxd!
Obviously, you need the unlimited linker to actually link Vim. See
http://www.metrowerks.com for purchasing the CodeWarrior compiler for BeOS.
There are currently no other linkers that can do the job.
This won't be able to include the Perl or Python interfaces even if
you have the appropriate files installed. |beos-perl|
3. Timeout in the Terminal *beos-timeout*
Because some POSIX/UNIX features are still missing[1], there is no direct OS
support for read-with-timeout in the Terminal. This would meat that you cannot
use :mappings of more than one character, unless you also :set notimeout.
|'timeout'|
To circumvent this problem, I added a workaround to provide the necessary
input with timeout by using an extra thread which reads ahead one character.
As a side effect, it also makes Vim recognize when the Terminal window
resizes.
Function keys are not supported in the Terminal since they produce very
indistinctive character sequences.
These problems do not exist in the GUI.
[1]: there is no select() on file descriptors; also the termios VMIN and VTIME
settings do not seem to work properly. This has been the case since DR7 at
least and still has not been fixed as of PR2.
*beos-unicode*
4. Unicode vs. Latin1 *beos-utf8*
BeOS uses Unicode and UTF-8 for text strings (16-bit characters encoded to
8-bit characters). Vim assumes ISO-Latin1 or other 8-bit character codes.
This does not produce the desired results for non-ASCII characters. Try the
command :digraphs to see. If they look messed up, use :set isprint=@ to
(slightly) improve the display of ISO-Latin1 characters 128-255. This works
better in the GUI, depending on which font you use (below).
You may also use the /boot/bin/xtou command to convert UTF-8 files from (xtou
-f iso1 filename) or to (xtou -t iso1 filename) ISO-Latin1 characters.
5. The BeOS GUI *beos-gui*
Normally Vim starts with the GUI if you start it as gvim or vim -g. The BeOS
version tries to determine if it was started from the Tracker instead of the
Terminal, and if so, use the GUI anyway. However, the current detection scheme
is fooled if you use the command "vim - </dev/null" or "vim filename &". The
latter can be called a feature but probably only works because there is no
BSD-style job control.
Stuff that does not work yet:
- Running external commands from the GUI does not work 100% (again due to lack
of support for select()). There was a choice between seeing the command's
output, or being able to interrupt it. I chose for seeing the output. Even
now the command sometimes crashes mysteriously, apparently in Be's
malloc_internal() called from the putenv() function, after fork()ing. (data
access exception occurred, ec01b0ec: 90e80000 *stw r7, 0x0000 (r8))(:!ls
works usually, :r !ls usually doesn't). This has been reported as bug
# 971215-083826.
- The window title.
- Starting the GUI from the Terminal version with :gui always acts as if
:gui -f were used. There is no way to fix this that I can see.
- There are some small display glitches here and there that I hope to clean up
later. Most of them occur when the window is partially obscured. Some of
them seem to be bugs in BeOS, because the Terminal has similar glitches.
- Mouse up events are not generated when outside the window. This is a bug in
BeOS. You can notice this when selecting text and moving the cursor outside
the window, then letting go of the mouse button. Another way is when you
drag the scrollbar and do the same thing. Because Vim still thinks you are
still playing with the scrollbar it won't change it itself. I provided a
workaround which kicks in when the window is activated or deactivated (so it
works best with focus- follows-mouse (/boot/bin/ffm) turned on).
- The cursor does not flash (very low priority; I'm not sure I even like it
when it flashes)
The $VIM directory *beos-vimdir*
$VIM is the symbolic name for the place where Vims support files are stored.
The default value for $VIM is set at compile time and can be determined with >
:version
The normal value is /boot/home/config/share/vim. If you don't like it you can
set the VIM environment variable to override this, or set 'helpfile' in your
.vimrc: >
:if version >= 500
: set helpfile=~/vim/vim54/doc/help.txt
: syntax on
:endif
7. Drag & Drop *beos-dragndrop*
You can drop files and directories on either the Vim icon (starts a new Vim
session, unless you use the File Types application to set Vim to be "Single
Launch") or on the Vim window (starts editing the files). Dropping a folder
sets Vim's current working directory. |:cd| |:pwd| If you drop files or
folders with either SHIFT key pressed, Vim changes directory to the folder
that contains the first item dropped. When starting Vim, there is no need to
press shift: Vim behaves as if you do.
Files dropped set the current argument list. |argument-list|
8. Single Launch vs. Multiple Launch *beos-launch*
As distributed Vim's Application Flags (as seen in the FileTypes preference)
are set to Multiple Launch. If you prefer, you can set them to Single Launch
instead. Attempts to start a second copy of Vim will cause the first Vim to
open the files instead. This works from the Tracker but also from the command
line. In the latter case, non-file (option) arguments are not supported.
NB: Only the GUI version has a BApplication (and hence Application Flags).
This section does not apply to the GUI-less version, should you compile one.
9. Fonts *beos-fonts*
Set fonts with >
:set guifont=Courier10_BT/Roman/10
where the first part is the font family, the second part the style, and the
third part the size. You can use underscores instead of spaces in family and
style.
Best results are obtained with monospaced fonts (such as Courier). Vim
attempts to use all fonts in B_FIXED_SPACING mode but apparently this does not
work for proportional fonts (despite what the BeBook says).
Vim also tries to use the B_ISO8859_1 encoding, also known as ISO Latin 1.
This also does not work for all fonts. It does work for Courier, but not for
ProFontISOLatin1/Regular (strangely enough). You can verify this by giving the >
:digraphs
command, which lists a bunch of characters with their ISO Latin 1 encoding.
If, for instance, there are "box" characters among them, or the last character
isn't a dotted-y, then for this font the encoding does not work.
If the font you specify is unavailable, you get the system fixed font.
Standard fixed-width system fonts are:
ProFontISOLatin1/Regular
Courier10_BT/Roman
Courier10_BT/Italic
Courier10_BT/Bold
Courier10_BT/Bold_Italic
Standard proportional system fonts are:
Swis721_BT/Roman
Swis721_BT/Italic
Swis721_BT/Bold
Swis721_BT/Bold_Italic
Dutch801_Rm_BT/Roman
Dutch801_Rm_BT/Italic
Dutch801_Rm_BT/Bold
Dutch801_Rm_BT/Bold_Italic
Baskerville/Roman
Baskerville/Italic
Baskerville/Bold
Baskerville/Bold_Italic
SymbolProp_BT/Regular
Try some of them, just for fun.
10. The meta key modifier *beos-meta*
The META key modifier is obtained by the left or right OPTION keys. This is
because the ALT (aka COMMAND) keys are not passed to applications.
11. Mouse key mappings *beos-mouse*
Vim calls the various mouse buttons LeftMouse, MiddleMouse and RightMouse. If
you use the default Mouse preference settings these names indeed correspond to
reality. Vim uses this mapping:
Button 1 -> LeftMouse,
Button 2 -> RightMouse,
Button 3 -> MiddleMouse.
If your mouse has fewer than 3 buttons you can provide your own mapping from
mouse clicks with modifier(s) to other mouse buttons. See the file
vim-5.x/macros/swapmous.vim for an example. |gui-mouse-mapping|
12. Color names *beos-colors*
Vim has a number of color names built-in. Additional names are read from the
file $VIMRUNTIME/rgb.txt, if present. This file is basically the color
database from X. Names used from this file are cached for efficiency.
13. Compiling with Perl *beos-perl*
Compiling with Perl support enabled is slightly tricky. The Metrowerks
compiler has some strange ideas where to search for include files. Since
several include files with Perl have the same names as some Vim header
files, the wrong ones get included. To fix this, run the following Perl
script while in the vim-5.0/src directory: >
preproc.pl > perl.h
#!/bin/env perl
# Simple #include expander, just good enough for the Perl header files.
use strict;
use IO::File;
use Config;
sub doinclude
{
my $filename = $_[0];
my $fh = new IO::File($filename, "r");
if (defined $fh) {
print "/* Start of $filename */\n";
while (<$fh>) {
if (/^#include "(.*)"/) {
doinclude($1);
print "/* Back in $filename */\n";
} else {
print $_;
}
}
print "/* End of $filename */\n";
undef $fh;
} else {
print "/* Cannot open $filename */\n";
print "#include \"$filename\"\n";
}
}
chdir $Config{installarchlib}."/CORE";
doinclude "perl.h";
It expands the "perl.h" header file, using only other Perl header files.
Now you can configure & make Vim with the --enable-perlinterp option.
Be warned though that this adds about 616 kilobytes to the size of Vim!
Without Perl, Vim with default features and GUI is about 575K, with Perl
it is about 1191K.
-Olaf Seibert
[Note: these addresses no longer work:]
<rhialto@polder.ubc.kun.nl>
http://polder.ubc.kun.nl/~rhialto/be
vim:tw=78:ts=8:ft=help:norl:

295
runtime/doc/os_dos.txt Normal file
View File

@@ -0,0 +1,295 @@
*os_dos.txt* For Vim version 7.0aa. Last change: 2003 Dec 20
VIM REFERENCE MANUAL by Bram Moolenaar
*dos* *DOS*
This file documents the common particularities of the MS-DOS and Win32
versions of Vim. Also see |os_win32.txt| and |os_msdos.txt|.
1. File locations |dos-locations|
2. Using backslashes |dos-backslash|
3. Standard mappings |dos-standard-mappings|
4. Screen output and colors |dos-colors|
5. File formats |dos-file-formats|
6. :cd command |dos-:cd|
7. Interrupting |dos-CTRL-Break|
8. Temp files |dos-temp-files|
9. Shell option default |dos-shell|
==============================================================================
1. File locations *dos-locations*
If you keep the Vim executable in the directory that contains the help and
syntax subdirectories, there is no need to do anything special for Vim to
work. No registry entries or environment variables need to be set. Just make
sure that the directory is in your search path, or use a shortcut on the
desktop.
Your vimrc files ("_vimrc" and "_gvimrc") are normally located one directory
up from the runtime files. If you want to put them somewhere else, set the
environment variable $VIM to the directory where you keep them. Example: >
set VIM=C:\user\piet
Will find "c:\user\piet\_vimrc".
Note: This would only be needed when the computer is used by several people.
Otherwise it's simpler to keep your _vimrc file in the default place.
If you move the executable to another location, you also need to set the $VIM
environment variable. The runtime files will be found in "$VIM/vim{version}".
Example: >
set VIM=E:\vim
Will find the version 5.4 runtime files in "e:\vim\vim54".
Note: This is _not_ recommended. The preferred way is to keep the executable
in the runtime directory.
If you move your executable AND want to put your "_vimrc" and "_gvimrc" files
somewhere else, you must set $VIM to where you vimrc files are, and set
$VIMRUNTIME to the runtime files. Example: >
set VIM=C:\usr\piet
set VIMRUNTIME=E:\vim\vim54
Will find "c:\user\piet\_vimrc" and the runtime files in "e:\vim\vim54".
See |$VIM| and |$VIMRUNTIME| for more information.
Under Windows 95, you can set $VIM in your C:\autoexec.bat file. For
example: >
set VIM=D:\vim
Under Windows NT, you can set environment variables for each user separately
under "Start/Settings/Control Panel->System", or through the properties in the
menu of "My Computer", under the Environment Tab.
==============================================================================
2. Using backslashes *dos-backslash*
Using backslashes in file names can be a problem. Vi halves the number of
backslashes for some commands. Vim is a bit more tolerant and does not remove
backslashes from a file name, so ":e c:\foo\bar" works as expected. But when
a backslash occurs before a special character (space, comma, backslash, etc.),
Vim removes the backslash. Use slashes to avoid problems: ":e c:/foo/bar"
works fine. Vim replaces the slashes with backslashes internally to avoid
problems with some MS-DOS programs and Win32 programs.
When you prefer to use forward slashes, set the 'shellslash' option. Vim will
then replace backslashes with forward slashes when expanding file names. This
is especially useful when using a Unix-like 'shell'.
==============================================================================
3. Standard mappings *dos-standard-mappings*
CTRL-PageUp cursor to first screen line *<C-PageUp>*
CTRL-PageDown cursor to last screen line, last character *<C-PageDown>*
These mappings accomplish this:
key key code Normal/Visual mode Insert mode ~
CTRL-PageUp <M-N><M-C-D> H <C-O>H
CTRL-PageDown <M-N>v L$ <C-O>L<C-O>$
Additionally, these keys are available for copy/cut/paste. In the Win32
and DJGPP versions, they also use the clipboard.
Shift-Insert paste text (from clipboard) *<S-Insert>*
CTRL-Insert copy Visual text (to clipboard) *<C-Insert>*
CTRL-Del cut Visual text (to clipboard) *<C-Del>*
Shift-Del cut Visual text (to clipboard) *<S-Del>*
These mappings accomplish this (Win32 and DJGPP versions of Vim):
key key code Normal Visual Insert ~
Shift-Insert <M-N><M-T> "*P "-d"*P <C-R><C-O>*
CTRL-Insert <M-N><M-U> "*y
Shift-Del <M-N><M-W> "*d
CTRL-Del <M-N><M-X> "*d
Or these mappings (non-Win32 version of Vim):
key key code Normal Visual Insert ~
Shift-Insert <M-N><M-T> P "-dP <C-R><C-O>"
CTRL-Insert <M-N><M-U> y
Shift-Del <M-N><M-W> d
CTRL-Del <M-N><M-X> d
When the clipboard is supported, the "* register is used.
==============================================================================
4. Screen output and colors *dos-colors*
The default output method for the screen is to use bios calls. This works
right away on most systems. You do not need ansi.sys. You can use ":mode" to
set the current screen mode. See |:mode|.
To change the screen colors that Vim uses, you can use the |:highlight|
command. The Normal highlight group specifies the colors Vim uses for normal
text. For example, to get grey text on a blue background: >
:hi Normal ctermbg=Blue ctermfg=grey
See |highlight-groups| for other groups that are available.
A DOS console does not support attributes like bold and underlining. You can
set the color used in five modes with nine termcap options. Note that this is
not necessary since you can set the color directly with the ":highlight"
command; these options are for backward compatibility with older Vim versions.
The |'highlight'| option specifies which of the five modes is used for which
action. >
:set t_mr=^V^[\|xxm start of invert mode
:set t_md=^V^[\|xxm start of bold mode
:set t_me=^V^[\|xxm back to normal text
:set t_so=^V^[\|xxm start of standout mode
:set t_se=^V^[\|xxm back to normal text
:set t_us=^V^[\|xxm start of underline mode
:set t_ue=^V^[\|xxm back to normal text
:set t_ZH=^V^[\|xxm start of italics mode
:set t_ZR=^V^[\|xxm back to normal text
^V is CTRL-V
^[ is <Esc>
You must replace xx with a decimal code, which is the foreground color number
and background color number added together:
COLOR FOREGROUND BACKGROUND ~
Black 0 0
DarkBlue 1 16
DarkGreen 2 32
DarkCyan 3 48
DarkRed 4 64
DarkMagenta 5 80
Brown, DarkYellow 6 96
LightGray 7 112
DarkGray 8 128 *
Blue, LightBlue 9 144 *
Green, LightGreen 10 160 *
Cyan, LightCyan 11 176 *
Red, LightRed 12 192 *
Magenta, LightMagenta 13 208 *
Yellow, LightYellow 14 224 *
White 15 240 *
* Depending on the display mode, the color codes above 128 may not be
available, and code 128 will make the text blink.
When you use 0, the color is reset to the one used when you started Vim
(usually 7, lightgray on black, but you can override this. If you have
overridden the default colors in a command prompt, you may need to adjust
some of the highlight colors in your vimrc---see below).
This is the default for t_me.
The defaults for the various highlight modes are:
t_mr 112 reverse mode: Black text (0) on LightGray (112)
t_md 15 bold mode: White text (15) on Black (0)
t_me 0 normal mode (revert to default)
t_so 31 standout mode: White (15) text on DarkBlue (16)
t_se 0 standout mode end (revert to default)
t_czh 225 italic mode: DarkBlue text (1) on Yellow (224)
t_czr 0 italic mode end (revert to default)
t_us 67 underline mode: DarkCyan text (3) on DarkRed (64)
t_ue 0 underline mode end (revert to default)
These colors were chosen because they also look good when using an inverted
display, but you can change them to your liking.
Example: >
:set t_mr=^V^[\|97m " start of invert mode: DarkBlue (1) on Brown (96)
:set t_md=^V^[\|67m " start of bold mode: DarkCyan (3) on DarkRed (64)
:set t_me=^V^[\|112m " back to normal mode: Black (0) on LightGray (112)
:set t_so=^V^[\|37m " start of standout mode: DarkMagenta (5) on DarkGreen
(32)
:set t_se=^V^[\|112m " back to normal mode: Black (0) on LightGray (112)
==============================================================================
5. File formats *dos-file-formats*
If the 'fileformat' option is set to "dos" (which is the default), Vim accepts
a single <NL> or a <CR><NL> pair for end-of-line (<EOL>). When writing a
file, Vim uses <CR><NL>. Thus, if you edit a file and write it, Vim replaces
<NL> with <CR><NL>.
If the 'fileformat' option is set to "unix", Vim uses a single <NL> for <EOL>
and shows <CR> as ^M.
You can use Vim to replace <NL> with <CR><NL> by reading in any mode and
writing in Dos mode (":se ff=dos").
You can use Vim to replace <CR><NL> with <NL> by reading in Dos mode and
writing in Unix mode (":se ff=unix").
Vim sets 'fileformat' automatically when 'fileformats' is not empty (which is
the default), so you don't really have to worry about what you are doing.
|'fileformat'| |'fileformats'|
If you want to edit a script file or a binary file, you should set the
'binary' option before loading the file. Script files and binary files may
contain single <NL> characters which Vim would replace with <CR><NL>. You can
set 'binary' automatically by starting Vim with the "-b" (binary) option.
==============================================================================
6. :cd command *dos-:cd*
The ":cd" command recognizes the drive specifier and changes the current
drive. Use ":cd c:" to make drive C the active drive. Use ":cd d:\foo" to go
to the directory "foo" in the root of drive D. Vim also recognizes UNC names
if the system supports them; e.g., ":cd \\server\share\dir". |:cd|
==============================================================================
7. Interrupting *dos-CTRL-Break*
Use CTRL-Break instead of CTRL-C to interrupt searches. Vim does not detect
the CTRL-C until it tries to read a key.
==============================================================================
8. Temp files *dos-temp-files*
Only for the 16 bit and 32 bit DOS version:
Vim puts temporary files (for filtering) in the first of these directories
that exists and in which Vim can create a file:
$TMP
$TEMP
C:\TMP
C:\TEMP
current directory
For the Win32 version (both console and GUI):
Vim uses standard Windows functions to obtain a temporary file name (for
filtering). The first of these directories that exists and in which Vim can
create a file is used:
$TMP
$TEMP
current directory
==============================================================================
9. Shell option default *dos-shell*
The default for the 'sh' ('shell') option is "command.com" on Windows 95 and
"cmd.exe" on Windows NT. If SHELL is defined, Vim uses SHELL instead, and if
SHELL is not defined but COMSPEC is, Vim uses COMSPEC. Vim starts external
commands with "<shell> /c <command_name>". Typing CTRL-Z starts a new command
subshell. Return to Vim with "exit". |'shell'| |CTRL-Z|
If you are running a third-party shell, you may need to set the
|'shellcmdflag'| ('shcf') and |'shellquote'| ('shq') or |'shellxquote'|
('sxq') options. Unfortunately, this also depends on the version of Vim used.
For example, with the MKS Korn shell or with bash, the values of the options
should be:
DOS 16 bit DOS 32 bit Win32 ~
'shellcmdflag' -c -c -c
'shellquote' "
'shellxquote' "
For Dos 16 bit this starts the shell as:
<shell> -c "command name" >file
For Win32 as:
<shell> -c "command name >file"
For DOS 32 bit, DJGPP does this internally somehow.
When starting up, Vim checks for the presence of "sh" anywhere in the 'shell'
option. If it is present, Vim sets the 'shellcmdflag' and 'shellquote' or
'shellxquote' options will be set as described above.
vim:tw=78:ts=8:ft=help:norl:

98
runtime/doc/os_mac.txt Normal file
View File

@@ -0,0 +1,98 @@
*os_mac.txt* For Vim version 7.0aa. Last change: 2004 Apr 27
VIM REFERENCE MANUAL by Bram Moolenaar et al.
*mac* *Mac* *macintosh* *Macintosh*
This file documents the particularities of the Macintosh version of Vim.
NOTE: This file is a bit outdated. You might find more useful info here:
http://macvim.swdev.org/
1. Filename Convention |mac-filename|
2. .vimrc an .vim files |mac-vimfile|
3. FAQ |mac-faq|
4. Known Lack |mac-lack|
5. Mac Bug Report |mac-bug|
6. Compiling Vim |mac-compile|
There was a Mac port for version 3.0 of Vim. Here are the first few lines
from the old file:
VIM Release Notes
Initial Macintosh release, VIM version 3.0
19 October 1994
Eric Fischer
<enf1@midway.uchicago.edu>, <eric@jcp.uchicago.edu>, <etaoin@uchicago.edu>
5759 N. Guilford Ave
Indianapolis IN 46220 USA
==============================================================================
1. Filename Convention *mac-filename*
You can use either the unix or mac path separator or a mix of both. In order
to determine if the specified filename is relative to the current folder or
absolute (i.e. relative to the "Desktop"), the following algorithm is used:
If the path start by a "/", the path is absolute
If the path start by a ":", the path is relative
If the path doesn't start by neither a "/" nor ":",
and a ":" is found before a "/" then the path is absolute
>
:e /HD/text
:e HD:text
< Edit the file "text" of the disk "HD" >
:e :src:main.c
:e src/main.c
< Edit the file "main.c" in the folder "src" in the current folder >
:e os_mac.c
< Edit the file "os_mac.c" in the current folder.
You can use the |$VIM| and |$VIMRUNTIME| variable. >
:so $VIMRUNTIME:syntax:syntax.vim
==============================================================================
2. .vimrc and .vim files *mac-vimfile*
On the Mac files starting with a dot "." are discouraged, thus the rc files
are named "vimrc" or "_vimrc" and "gvimrc" or "_gvimrc". These files can be in
any format (mac, dos or unix). Vim can handle any file format when the
|'nocompatible'| option is set, otherwise it will only handle mac format
files.
==============================================================================
3. Mac FAQ *mac-faq*
Q: I can't enter non-ASCII character in Apple Terminal.
A: Under Window Settings, Emulation, make sure that "Escape non-ASCII
characters" is not checked.
==============================================================================
4. Mac Lack *mac-lack*
-The filenames containing both ":" and "/" are sometimes misinterpreted.
(just re-execute the command)
-Scrollbar are not scrolling live, and when only the arrow or scroll area,
a limit of 32 line or page is scrolled.
-Syntax highlighting works on 68k Macs but is _really_ slow.
==============================================================================
5. Mac Bug Report *mac-bug*
When reporting any Mac specific bug or feature change, please use the vim-mac
maillist |vim-mac|. However, you need to be subscribed. An alternative is to
send a message to the current MacVim maintainers:
mac@vim.org
==============================================================================
6. Compiling Vim *mac-compile*
See the file "src/INSTALLmac.txt" that comes with the source files.
vim:tw=78:ts=8:ft=help:norl:

39
runtime/doc/os_mint.txt Normal file
View File

@@ -0,0 +1,39 @@
*os_mint.txt* For Vim version 7.0aa. Last change: 2001 Sep 03
VIM REFERENCE MANUAL by Jens M. Felderhoff
*MiNT* *Atari*
This file contains the particularities for the Atari MiNT version of Vim.
For compiling Vim on the Atari running MiNT see "INSTALL" and "Makefile"
in the src directory.
Vim for MiNT behaves almost exactly like the Unix version.
The Unix behavior described in the documentation also refers to the
MiNT version of Vim unless explicitly stated otherwise.
For wildcard expansion of <~> (home directory) you need a shell that
expands the tilde. The vanilla Bourne shell doesn't recognize it.
With csh and ksh it should work OK.
The MiNT version of vim needs the termcap file /etc/termcap with the
terminal capabilities of your terminal. Builtin termcaps are
supported for the vt52 terminal. Termcap entries for the TOSWIN window
manager and the virtual console terminals have been appended to the
termcap file that comes with the Vim distribution.
If you should encounter problems with swapped <BS> and <Del> keys, see
|:fixdel|.
Because terminal updating under MiNT is often slow (e.g. serial line
terminal), the 'showcmd' and 'ruler' options are default off.
If you have a fast terminal, try setting them on. You might
also want to set 'ttyfast'.
Send bug reports to
Jens M. Felderhoff, e-mail: <jmf@infko.uni-koblenz.de>
vim:tw=78:ts=8:ft=help:norl:

270
runtime/doc/os_msdos.txt Normal file
View File

@@ -0,0 +1,270 @@
*os_msdos.txt* For Vim version 7.0aa. Last change: 2001 Sep 03
VIM REFERENCE MANUAL by Bram Moolenaar
*msdos* *ms-dos* *MSDOS* *MS-DOS*
This file contains the particularities for the MS-DOS version of Vim.
1. Two versions for MS-DOS |msdos-versions|
2. Known problems |msdos-problems|
3. Long file names |msdos-longfname|
4. Termcap codes |msdos-termcap|
5. Shifted arrow keys |msdos-arrows|
6. Filename extensions |msdos-fname-extensions|
7. Memory usage and limitations |msdos-limitations|
8. Symbolically linked files |msdos-linked-files|
9. Copy/paste in a dos box |msdos-copy-paste|
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|
For compiling Vim see src/INSTALL.pc. *msdos-compiling*
==============================================================================
1. Two versions for MS-DOS *msdos-versions*
There are two versions of Vim that can be used with MS-DOS machines:
*dos16*
Dos16 version Can be used on any MS-DOS system, only uses up to 640 Kbyte of
memory. Also runs on OS/2, Windows 95, and NT. Excludes some
Vim-specific features (autocommands, syntax highlighting,
etc.). Recommended for use on pre-386 machines.
*dos32*
Dos32 version Requires 386 processor and a |DPMI| driver, uses all
available memory. Supports long file names and the Windows
clipboard, but NOT on Windows NT. Recommended for MS-DOS,
Windows 3.1 and Windows 95.
There are also two versions that run under Windows:
Win32 version Requires Windows 95 or Windows NT, uses all available
memory, supports long file names, etc. Has some problems on
Windows 95. Recommended for Windows NT. See |os_win32.txt|
Win32 GUI Requirements like the Win32 version, but runs in its own
window, instead of a console. Has scrollbars, menu, etc.
Recommended for Windows 95 and Windows NT. See |gui-w32|.
It is recommended to use the Dos32 or Win32 version. Although the Dos16
version is able to edit very big files, it quickly runs out of memory when
making big changes. Disabling undo helps: ":set ul=-1". The screen updating
of the Dos16 version is the fastest of the three on DOS or Windows 95; on
Windows NT, the Win32 version is just as fast.
*DPMI*
For the Dos32 version, you may need a DPMI driver when running in MS-DOS. If
you are running Windows or installed a clever memory manager, it will probably
work already. If you get the message "No DPMI", you need to install a DPMI
driver. Such a driver is included with the executable in CSDPMI4B.ZIP. Run
"cwsdpmi" just before starting Vim each time. Or you might want to include
"cwsdpmi -p" in your autoexec.bat to make it resident. The latest version of
"CSDPMI*.ZIP" can be obtained from: "ftp.neosoft.com:pub/users/s/sandmann".
*minimal-features*
The 16 bit DOS version has been compiled with minimal features. Check the
|+feature-list| which ones are included (marked with a "T").
You can include more features by editing feature.h and recompiling.
==============================================================================
2. Known problems *msdos-problems*
When using smartdrive (MS-DOS 6.x) with write-behind caching, it is possible
that Vim will try to create a swap file on a read-only file system (e.g.
write protected floppy). You will then be given the message >
A serious disk error has occurred .., Retry (r)?
There is nothing you can do but unprotect the floppy or switch off the
computer. Even CTRL-ALT-DEL will not get you out of this. This is really a
problem of smartdrive, not Vim. Smartdrive works fine otherwise. If this
bothers you, don't use the write-behind caching.
Vim can't read swap files that have been opened already, unless the "share"
command has been used. If you see stray warnings for existing swap files,
include the "share" command in your config.sys or autoexec.bat (see your MSDOS
documentation).
The Dos16 version can only have about 10 files open (in a window or hidden) at
one time. With more files you will get error messages when trying to read or
write a file, and for filter commands. Or Vim runs out of memory, and random
problems may result.
The Dos32 version cannot have an unlimited number of files open at any one
time. The limit depends on the setting of FILES in your CONFIG.SYS. This
defaults to 15; if you need to edit a lot of files, you should increase this.
If you do not set FILES high enough, you can get strange errors, and shell
commands may cause a crash!
The Dos32 version can work with long file names. When doing file name
completion, matches for the short file name will also be found. But this will
result in 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".
When using the Dos32 version and you run into problems with DPMI support,
check if there is a program in your config.sys that eats resources. One
program known to cause this problem is "netx", which says "NetWare v. 3.26
Workstation shell". Replace it with version 3.32 to fix the problem.
The Dos32 version will parse its arguments to handle quotation. This is good
to edit a file with spaces in its name, for example: >
vim "program files\accessories\ppp.scp"
A side effect is that single quotes are removed. Insert a backslash to avoid
that. For example, to edit the file "fi'le.txt": >
vim fi\'le.txt
==============================================================================
3. Long file names *msdos-longfname*
If the Dos32 version is run on Windows 95, it can use long file names. It
will work by default. If you want to disable this, use this setting:
set LFN=N
You can put this in your autoexec.bat file.
Note: If you have installed DJGPP on your machine, you probably have a
"djgpp.env" file, which contains "LFN=n". You need to use "LFN=Y" to switch
on using long file names then.
==============================================================================
4. Termcap codes *msdos-termcap*
If you want to use another output method (e.g., when using a terminal on a COM
port), set the terminal name to "pcansi". You can change the termcap options
when needed (see |terminal-options|). Note that the
normal IBM ansi.sys does not support all the codes of the builtin pcansi
terminal. If you use ansi.sys, you will need to delete the termcap entries
t_al and t_dl with >
:set t_al= t_dl=
Otherwise, the screen will not be updated correctly. It is better to use
nansi.sys, nnansi.sys, or the like instead of ansi.sys.
If you want to use Vim on a terminal connected to a COM: port, reset the
'bioskey' option. Otherwise the commands will be read from the PC keyboard.
CTRL-C and CTRL-P may not work correctly with 'bioskey' reset.
==============================================================================
5. Shifted arrow keys *msdos-arrows*
Use CTRL-arrow-left and CTRL-arrow-right instead of SHIFT-arrow-left and
SHIFT-arrow-right. The arrow-up and arrow-down cannot be used with SHIFT or
CTRL.
==============================================================================
6. Filename extensions *msdos-fname-extensions*
MS-DOS allows for only one file name extension. Therefore, when appending an
extension, the '.' in the original file name is replaced with a '_', the name
is truncated to 8 characters, and the new extension (e.g., ".swp") is
appended. Two examples: "test.c" becomes "test_c.bak", "thisisat.est"
becomes "thisisat.bak". To reduce these problems, the default for
'backupext' is "~" instead of ".bak". The backup file for "thisisat.est"
then becomes "thisisat.es~". The 'shortname' option is not available,
because it would always be set.
==============================================================================
7. Memory usage and limitations *msdos-limitations*
A swap file is used to store most of the text. You should be able to edit
very large files. However, memory is used for undo and other things. If you
delete a lot of text, you can still run out of memory in the Dos16 version.
If Vim gives an "Out of memory" warning, you should stop editing. The result
of further editing actions is unpredictable. Setting 'undolevels' to 0 saves
some memory. Running the maze macros on a big maze is guaranteed to run out
of memory, because each change is remembered for undo. In this case set
'undolevels' to a negative number. This will switch off undo completely.
*msdos-clipboard-limits*
In the Dos32 version, extended memory is used to avoid these problems.
However, if you are using the clipboard, you can still run into memory
limitations because the Windows clipboard can only communicate with Vim using
Dos memory. This means that the largest amount of text that can be sent to
or received from the Windows clipboard is limited by how much free Dos memory
is available on your system.
You can usually maximize the amount of available Dos memory by adding the
following lines to Dos's "config.sys" file: >
DOS=HIGH,UMB
DEVICE=C:\WINDOWS\himem.sys
DEVICE=C:\WINDOWS\emm386.exe RAM
Modifying config.sys in this way will also help to make more memory available
for the Dos16 version, if you are using that.
In the Dos16 version the line length is limited to about 32000 characters.
When reading a file the lines are automatically split. But editing a line
in such a way that it becomes too long may give unexpected results.
==============================================================================
8. Symbolically linked files *msdos-linked-files*
When using Vim to edit a symbolically linked file on a unix NFS file server,
you may run into problems.
When writing the file, Vim does not "write through" the symlink. Instead, it
deletes the symbolic link and creates a new file in its place.
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'|
==============================================================================
9. Copy/paste in a dos box *msdos-copy-paste*
*E450* *E451* *E452* *E453* *E454*
The 32 bit version can copy/paste from/to the Windows clipboard directly. Use
the "* register. Large amounts of text can be copied this way, but it must be
possible to allocate memory for it, see |msdos-clipboard-limits|. When moving
text from one Vim to another, the type of the selection
(characterwise/linewise/blockwise) is passed on.
In other versions, the following can be used.
(posted to comp.editors by John Velman <velman@igate1.hac.com>)
How to copy/paste text from/to vim in a dos box:
1) to get VIM to run in a window, instead of full screen, press alt+enter.
This toggles back and forth between full screen and a dos window.
NOTE: In Windows 95 you must have the property "Fast Pasting" unchecked!
In the properties dialog box for the MS-DOS window, go to "MS-DOS
Prompt/Misc/Fast pasting" and make sure that it is NOT checked.
To make this permanent, change the properties for
"\windows\system\conagent.exe" (from Philip Nelson, unverified).
2) To paste something _into_ Vim, put Vim in insert mode.
3) put the text you want to paste on the windows clipboard.
4) Click the control box in the upper left of the Vim window. (This looks
like a big minus sign). If you don't want to use the mouse, you can get
this with alt+spacebar.
5) on the resulting dropdown menu choose "Edit"
6) on the child dropdown menu choose "Paste"
To copy something from the Vim window to the clipboard,
1) select the control box to get the control drop down menu.
2) select "Edit".
3) select "Mark"
4) using either the keys or the mouse, select the part of the Vim window that
you want to copy. To use the keys, use the arrow keys, and hold down shift
to extend the selection.
5) when you've completed your selection, press 'enter.' The selection
is now in the windows clipboard. By the way, this can be any
rectangular selection, for example columns 4-25 in rows 7-10. It can
include anything in the VIM window: the output of a :!dir, for
example.
vim:tw=78:ts=8:ft=help:norl:

220
runtime/doc/os_os2.txt Normal file
View File

@@ -0,0 +1,220 @@
*os_os2.txt* For Vim version 7.0aa. Last change: 2004 Jan 09
VIM REFERENCE MANUAL by Paul Slootman
*os2* *OS2* *OS/2*
This file contains the particularities for the OS/2 version of Vim.
At present there is no native PM version of the GUI version of Vim: The OS/2
version is a console application. However, there is now a Win32s-compatible
GUI version, which should be usable by owners of Warp 4 (which supports
Win32s) in a Win-OS/2 session. The notes in this file refer to the native
console version.
NOTE
This OS/2 port works well for me and a couple of other OS/2 users; however,
since I haven't had much feedback, that either means no (OS/2-specific) bugs
exist (besides the ones mentioned below), or no one has yet created a
situation in which any bugs are apparent. File I/O in Dos and Unix mode,
binary mode, and FAT handling all seem to work well, which would seem to be
the most likely places for trouble.
A known problem is that files opened by Vim are inherited by other programs
that are started via a shell escape from within Vim. This specifically means
that Vim won't be able to remove the swap file(s) associated with buffers open
at the time the other program was started, until the other program is stopped.
At that time, the swap file may be removed, but if Vim could not do that the
first time, it won't be removed at all. You'll get warnings that some other
Vim session may be editing the file when you start Vim up again on that file.
This can be reproduced with ":!start epm". Now quit Vim, and start Vim again
with the file that was in the buffer at the time epm was started. I'm working
on this!
A second problem is that Vim doesn't understand the situation when using it
when accessing the OS/2 system via the network, e.g. using telnet from a Unix
system, and then starting Vim. The problem seems to be that OS/2 =sometimes=
recognizes function / cursor keys, and tries to convert those to the
corresponding OS/2 codes generated by the "normal" PC keyboard. I've been
testing a workaround (mapping the OS/2 codes to the correct functions), but so
far I can't say anything conclusive (this is on Warp 3, by the way). In the
meantime any help will be appreciated.
PREREQUISITES
To run Vim, you need the emx runtime environment (at least rev. 0.9b). This
is generally available as (ask Archie about it):
emxrt.zip emx runtime package
I've included a copy of emx.dll, which should be copied to one of the
directories listed in your LIBPATH. Emx is GPL'ed, but the emx.dll library is
not (read COPYING.EMX to find out what that means to you).
This emx.dll is from the emxfix04.zip package, which unfortunately has a bug,
eh, I mean a POSIX feature, in select(). Versions of Vim before 3.27 will
appear to hang when starting (actually, while processing vimrc). Hit <Enter> a
couple of times until Vim starts working if this happens. Next, get an up to
date version of Vim!
HELP AND VIMRC FILE
If you unpack the archive that Vim came in and run Vim directly from where it
was unpacked, Vim should be able to find the runtime files and your .vimrc
without any settings.
If you put the runtime files separately from the binary, the VIM environment
variable is used to find the location of the help files and the system .vimrc.
Place an entry such as this in CONFIG.SYS: >
SET VIM=c:/local/lib/vim
Put your .vimrc and your other Vim files in this directory. Copy the runtime
directory to this directory. Each version of Vim has its own runtime
directory. It will be called something like "c:/local/lib/vim/vim54". Thus
you get a tree of Vim files like this:
c:/local/lib/vim/.vimrc
c:/local/lib/vim/vim54/filetype.vim
c:/local/lib/vim/vim54/doc/help.txt
etc.
Note: .vimrc may also be called _vimrc to accommodate those who have chosen to
install OS/2 on a FAT file system. Vim first tries to find .vimrc and if that
fails, looks for _vimrc in the same place. The existence of a .vimrc or
_vimrc file influences the 'compatible' options, which can have unexpected side
effects. See |'compatible'|.
If you're using network drives with OS/2, then you can install Vim on a
network drive (including .vimrc; this is then called the "system" vimrc file),
and then use a personal copy of .vimrc (the "user" vimrc file). This should be
located in a directory indicated by the HOME environment variable.
ENVIRONMENT VARIABLES IN FILE NAMES
This HOME environment variable is also used when using ~ in file names, so
":e ~/textfile" will edit the file "textfile" in the directory referred to by
HOME. Additionally you can use other environment variables in file names, as
as ":n $SRC/*.c".
The HOME environment variable is also used to locate the .viminfo file
(see |viminfo-file|). There is no support yet for .viminfo on FAT file
systems yet, sorry. You could try the -i startup flag (as in "vim -i
$HOME/_viminfo") however.
If the HOME environment variable is not set, the value "C:/" is used as a
default.
BACKSLASHES
Using slashes ('/') and backslashes ('\') can be a bit of a problem (see
|dos-backslash| for more explanation), but in almost all cases Vim does "The
Right Thing". Vim itself uses backslashes in file names, but will happily
accept forward slashes if they are entered (in fact, sometimes that works
better!).
TEMP FILES
Temporary files (for filtering) are put in the first directory in the next
list that exists and where a file can be created:
$TMP
$TEMP
C:\TMP
C:\TEMP
current directory
TERMINAL SETTING
*os2ansi*
Use "os2ansi" as the TERM environment variable (or don't set it at all, as the
default is the correct value). You can set term to os2ansi in the .vimrc, in
case you need TERM to be a different value for other applications. The
problem is that OS/2 ANSI emulation is quite limited (it doesn't have insert /
delete line, for example).
If you want to use a different value for TERM (because of other programs, for
example), make sure that the termcap entry for that TERM value has the
appropriate key mappings. The termcap.dat distributed with emx does not always
have them. Here are some suitable values to add to the termcap entry of your
choice; these allow the cursor keys and the named function keys (such as
pagedown) to work.
:ku=\316H:kd=\316P:kl=\316K:kr=\316M:%i=\316t:#4=\316s:\
:kD=\316S:kI=\316R:kN=\316Q:kP=\316I:kh=\316G:@7=\316O:\
:k1=\316;:k2=\316<:k3=\316=:k4=\316>:k5=\316?:k6=\316@:\
:k7=\316A:k8=\316B:k9=\316C:k;=\316D:
Paul Slootman
43 LINE WINDOW
A suggestion from Steven Tryon, on how to run Vim in a bigger window:
When I call Vim from an OS/2 WPS application such as PMMail it comes up
in the default 25-line mode. To get a more useful window size I make
my external editor "vimbig.cmd" which in turn calls "vimbig2.cmd".
Brute force and awkwardness, perhaps, but it works.
vimbig.cmd: >
@echo off
start "Vi Improved" /f vimbig2.cmd %1 %2 %3 %4
vimbig2.cmd: >
@echo off
mode 80,43
vim.exe %1 %2 %3 %4
exit
<
CLIPBOARD ACCESS (provided by Alexander Wagner)
Vim for OS/2 has no direct access to the system clipboard. To enable access
anyway you need an additional tool which gives you access to the clipboard
from within a vio application. The freeware package clipbrd.zip by Stefan
Gruendel can be used for this purpose. You might download the package
including precompiled binaries and all sources from:
http://www.stellarcom.org/vim/index.html
Installation of this package is straight forward: just put the two executables
that come with this package into a directory within your PATH for Vim should
be able to call them from whatever directory you are working.
To copy text from the clipboard to your Vim session you can use the :r
command. Simply call clipbrd.exe from within Vim in the following way: >
:r !clipbrd -r
To copy text from Vim to the system clipboard just mark the text in the usual
vim-manner and call: >
:!clipbrd -w
which will write your selection right into OS/2's clipboard.
For ease of use you might want to add some maps for this commands. E.g. to
use F11 to paste the clipboard into Vim and F12 to copy selected text to the
clipboard you would use: >
if has("os2")
imap <F11> <ESC>:r !clipbrd -r<CR>i
vmap <F12> :!clipbrd -w<cr>
else
imap <F11> <ESC>"*p<CR>i
vmap <F12> "*y
endif
This will ensure that only on OS/2 clipbrd is called whereas on other
platforms vims build in mechanism is used. (To enable this functions on every
load of Vim place the above lines in your .vimrc.)
vim:tw=78:ts=8:ft=help:norl:

138
runtime/doc/os_qnx.txt Normal file
View File

@@ -0,0 +1,138 @@
*os_qnx.txt* For Vim version 7.0aa. Last change: 2004 Apr 23
VIM REFERENCE MANUAL by Julian Kinraid
*QNX* *qnx*
1. General |qnx-general|
2. Compiling Vim |qnx-compiling|
3. Terminal support |qnx-terminal|
4. Photon GUI |photon-gui|
5. Photon fonts |photon-fonts|
6. Bugs & things To Do
==============================================================================
1. General *qnx-general*
Vim on QNX behaves much like other unix versions. |os_unix.txt|
2. Compiling Vim *qnx-compiling*
Vim can be compiled using the standard configure/make approach. If you want to
compile for X11, pass the --with-x option to configure. Otherwise, running
./configure without any arguments or passing --enable-gui=photon, will compile
vim with the Photon gui support. Run ./configure --help , to find out other
features you can enable/disable.
3. Terminal support *qnx-terminal*
Vim has support for the mouse and clipboard in a pterm, if those options
are compiled in, which they are normally.
The options that affect mouse support are |'mouse'| and |'ttymouse'|. When
using the mouse, only simple left and right mouse clicking/dragging is
supported. If you hold down shift, ctrl, or alt while using the mouse, pterm
will handle the mouse itself. It will make a selection, separate from what
vim's doing.
When the mouse is in use, you can press Alt-RightMouse to open the pterm menu.
To turn the mouse off in vim, set the mouse option to nothing, set mouse=
4. Photon GUI *photon-gui*
To start the gui for vim, you need to run either gvim or vim -g, otherwise
the terminal version will run. For more info - |gui-x11-start|
Supported features:
:browse command |:browse|
:confirm command |:confirm|
Cursor blinking |'guicursor'|
Menus, popup menus and menu priorities |:menu|
|popup-menu|
|menu-priority|
Toolbar |gui-toolbar|
|'toolbar'|
Font selector (:set guifont=*) |photon-fonts|
Mouse focus |'mousefocus'|
Mouse hide |'mousehide'|
Mouse cursor shapes |'mouseshape'|
Clipboard |gui-clipboard|
Unfinished features:
Various international support, such as Farsi & Hebrew support,
different encodings, etc.
This help file
Unsupported features:
Find & Replace window |:promptfind|
Tearoff menus
Other things which I can't think of so I can't list them
5. Fonts *photon-fonts*
You set fonts in the gui with the guifont option >
:set guifont=Lucida\ Terminal
<
The font must be a monospace font, and any spaces in the font name must be
escaped with a '\'. The default font used is PC Terminal, size 8. Using
'*' as the font name will open a standard Photon font selector where you can
select a font.
Following the name, you can include optional settings to control the size and
style of the font, each setting separated by a ':'. Not all fonts support the
various styles.
The options are,
s{size} Set the size of the font to {size}
b Bold style
a Use antialiasing
i Italic style
Examples:
Set the font to monospace size 10 with antialiasing >
:set guifont=monospace:s10:a
<
Set the font to Courier size 12, with bold and italics >
:set guifont=Courier:s12:b:i
<
Select a font with the requester >
:set guifont=*
<
6. Bugs & things To Do
Known problems:
- Vim hangs sometimes when running an external program. Workaround:
put this line in your |vimrc| file: >
set noguipty
Bugs:
- Still a slight problem with menu highlighting
- When using phditto/phinows/etc., if you are using a font that
doesn't support the bold attribute, when vim attempts to draw
bold text it will be all messed up.
- The cursor can sometimes be hard to see.
- A number of minor problems that can fixed :)
Todo:
- Improve multi-language support.
- Options for setting the fonts used in the menu and toolbar.
- Find & Replace dialog.
- The clientserver features.
- Maybe tearoff menus.
- Replace usage of fork() with spawn() when launching external
programs.
vim:tw=78:sw=4:ts=8:ts=8:ft=help:norl:

323
runtime/doc/os_risc.txt Normal file
View File

@@ -0,0 +1,323 @@
*os_risc.txt* For Vim version 7.0aa. Last change: 2004 May 01
VIM REFERENCE MANUAL by Thomas Leonard
*riscos* *RISCOS* *RISC-OS*
This file contains the particularities for the RISC OS version of Vim.
The RISC OS port is a completely new port and is not based on the old `archi'
port.
1. File locations |riscos-locations|
2. Filename munging |riscos-munging|
3. Command-line use |riscos-commandline|
4. Desktop (GUI) use |riscos-gui|
5. Remote use (telnet) |riscos-remote|
6. Temporary files |riscos-temp-files|
7. Interrupting |riscos-interrupt|
8. Memory usage |riscos-memory|
9. Filetypes |riscos-filetypes|
10. The shell |riscos-shell|
11. Porting new releases |riscos-porting|
If I've missed anything, email me and I'll try to fix it. In fact, even if I
haven't missed anything then email me anyway to give me some confidence that it
actually works!
Thomas Leonard <tal197@ecs.soton.ac.uk>
[these URLs no longer work...]
Port homepage: http://www.ecs.soton.ac.uk/~tal197/
or try: http://www.soton.ac.uk/~tal197/
==============================================================================
*riscos-locations*
1. File locations
The Vim executable and shared resource files are all stored inside the !Vim
application directory.
When !Vim is first seen by the filer, it aliases the *vi and *ex commands to
run the command-line versions of Vim (see |riscos-commandline|).
!Vim.Resources and !Vim.Resources2 contain the files from the standard Vim
distribution, but modified slightly to work within the limits of ADFS, plus
some extra files such as the window templates.
User choices are read from `Choices:*' and are saved to `<Choices$Write>.*'.
If you have the new !Boot structure then these should be set up already. If
not, set Choices$Path to a list of directories to search when looking for
user configuration files. Set Choices$Write to the directory you want files
to be saved into (so your search patterns and marks can be remembered between
sessions).
==============================================================================
*riscos-munging*
2. Filename munging
All pathname munging is disabled by default, so Vim should behave like a
normal RISC OS application now. So, if you want to edit `doc/html' then you
actually type `*vi doc/html'.
The only times munging is done is when:
- Searching included files from C programs, since these are always munged.
See |[I|.
Note: make sure you are in the right directory when you use this
command (ie the one with subdirectories 'c' and 'h').
- Sourcing files using |:so|.
Paths starting `$VIM/' are munged like this:
$VIM/syntax/help.vim -> Vim:syntax.help
Also, files ending in `.vim' have their extensions removed, and slashes
replaced with dots.
Some tag files and script files may have to be edited to work under this port.
==============================================================================
*riscos-commandline*
3. Command-line use
To use Vim from the command-line use the `*vi' command (or '*ex' for
|Ex-mode|).
Type `*vi -h' for a list of options.
Running the command-line version of Vim in a large high-color mode may cause
the scrolling to be very slow. Either change to a mode with fewer colors or
use the GUI version.
Also, holding down Ctrl will slow it down even more, and Ctrl-Shift will
freeze it, as usual for text programs.
==============================================================================
*riscos-gui*
4. Desktop use
Limitations:
- Left scrollbars don't work properly (right and bottom are fine).
- Doesn't increase scroll speed if it gets behind.
You can resize the window by dragging the lower-right corner, even though
there is no icon shown there.
You can use the --rows and --columns arguments to specify the initial size of
the Vim window, like this: >
*Vi -g --rows 20 --columns 80
The global clipboard is supported, so you can select some text and then
paste it directly into another application (provided it supports the
clipboard too).
Clicking Menu now opens a menu like a normal RISC OS program. Hold down Shift
when clicking Menu to paste (from the global clipboard).
Dragging a file to the window replaces the CURRENT buffer (the one with the
cursor, NOT the one you dragged to) with the file.
Dragging with Ctrl held down causes a new Vim window to be opened for the
file (see |:sp|).
Dragging a file in with Shift held down in insert mode inserts the pathname of
the file.
:browse :w opens a standard RISC OS save box.
:browse :e opens a directory viewer.
For fonts, you have the choice of the system font, an outline font, the system
font via ZapRedraw and any of the Zap fonts via ZapRedraw: >
:set guifont=
< To use the system font via the VDU drivers. Supports
bold and underline.
>
:set guifont=Corpus.Medium
< Use the named outline font. You can use any font, but
only monospaced ones like Corpus look right.
>
:set guifont=Corpus.Medium:w8:h12:b:i
< As before, but with size of 8 point by 12 point, and
in bold italic.
If only one of width and height is given then that
value is used for both. If neither is given then 10
point is used.
Thanks to John Kortink, Vim can use the ZapRedraw module. Start the font name
with '!' (or '!!' for double height), like this: >
:set guifont=!!
< Use the system font, but via ZapRedraw. This gives a
faster redraw on StrongARM processors, but you can't
get bold or italic text. Double height.
>
:set guifont=!script
< Uses the named Zap font (a directory in VimFont$Path).
The redraw is the same speed as for '!!', but you get
a nicer looking font.
Only the "man+" and "script" fonts are supplied
currently, but you can use any of the Zap fonts if
they are in VimFont$Path.
Vim will try to load font files '0', 'B', 'I' and 'IB'
from the named directory. Only '0' (normal style) MUST
be present. Link files are not currently supported.
Note that when using ZapRedraw the edit bar is drawn in front of the character
you are on rather than behind it. Also redraw is incorrect for screen modes
with eigen values of 0. If the font includes control characters then you can
get Vim to display them by changing the 'isprint' option.
If you find the scrolling is too slow on your machine, try experimenting
with the 'scrolljump' and 'ttyscroll' options.
In particular, StrongARM users may find that: >
:set ttyscroll=0
makes scrolling faster in high-color modes.
=============================================================================
*riscos-remote*
5. Remote use (telnet)
I have included a built-in termcap entry, but you can edit the termcap file to
allow other codes to be used if you want to use Vim from a remote terminal.
Although I do not have an internet connection to my Acorn, I have managed to
run Vim in a FreeTerm window using the loopback connection.
It seems to work pretty well now, using '*vi -T ansi'.
==============================================================================
*riscos-temp-files*
6. Temporary files
If Vim crashes then the swap and backup files (if any) will be in the
directories set with the 'directory' and 'bdir' options. By default the swap
files are in <Wimp$ScrapDir> (ie inside !Scrap) and backups are in the
directory you were saving to. Vim will allow you to try and recover the file
when you next try to edit it.
To see a list of swap files, press <F12> and type `*vi -r'.
Vim no longer brings up ATTENTION warnings if you try to edit two files with
the same name in different directories.
However, it also no longer warns if you try to edit the same file twice (with
two copies of Vim), though you will still be warned when you save that the
datestamp has changed.
==============================================================================
*riscos-interrupt*
7. Interrupting
To break out of a looping macro, or similar, hold down Escape in the
command-line version, or press CTRL-C in the GUI version.
==============================================================================
*riscos-memory*
8. Memory usage
Vim will use dynamic areas on RISC OS 3.5 or later. If you can use them on
older machines then edit the !RunTxt and GVim files. I don't know what UnixLib
does by default on these machines so I'm playing safe.
It doesn't work at all well without dynamic areas, since it can't change its
memory allocation once running. Hence you should edit `!Vim.GVim' and
`!Vim.!RunTxt' to choose the best size for you. You probably need at least
about 1400K.
==============================================================================
*riscos-filetypes*
9. Filetypes
You can now specify that autocommands are only executed for files of certain
types. The filetype is given in the form &xxx, when xxx is the filetype.
Filetypes must be specified by number (eg &fff for Text).
The system has changed from version 5.3. The new sequence of events is:
- A file is loaded. |'osfiletype'| is set to the RISC OS filetype.
- Based on the filetype and pathname, Vim will try to set |'filetype'| to the
Vim-type of the file.
- Setting this option may load syntax files and perform other actions.
- Saving the file will give it a filetype of |'osfiletype'|.
Some examples may make this clearer:
Kind of file loaded osfiletype filetype ~
C code 'c.hellow' Text (&fff) C
LaTeX document LaTeX (&2a8) TeX
Draw document DrawFile (&aff) (not changed)
==============================================================================
*riscos-shell*
10. The shell
- Bangs (!s) are only replaced if they are followed by a space or end-of-line,
since many pathnames contain them.
- You can prefix the command with '~', which stops any output from being
displayed. This also means that you don't have to press <Enter> afterwards,
and stops the screen from being redrawn. {only in the GUI version}
==============================================================================
*riscos-porting*
11. Porting new releases to RISC OS
Downloading everything you need:
- Get the latest source distribution (see www.vim.org)
- Get the runtime environment files (eg these help files)
- Get the `extra' archive (contains the RISC OS specific bits)
- Get the RISC OS binary distribution (if possible)
Unarchiving:
- Create a raFS disk and put the archives on it.
- Un-gzip them
- Un-tar them (*tar xELf 50 archive/tar)
Recompiling the sources:
- Create c, s, and h directories.
- Put all the header files in 'h' \
- Put all the C files in `c' | And lose the extensions
- Put the assembler file (`swis/s') in 's' /
- Rename all the files in `proto' to `h', like this:
raFS::VimSrc.source.proto.file/pro
becomes
raFS::VimSrc.source.h.file_pro
- In the files `h.proto' and `c.termlib', search and replace
.pro"
with
_pro.h"
- Create a simple Makefile if desired and do '*make -k'
Use 'CC = gcc -DRISCOS -DUSE_GUI -O2 -x c' in the Makefile
- Save the binary as !Vim.Vim in the binary distribution
Updating the run-time environment:
- Replace old or missing files inside !Vim.Resources with the
new files.
- Remove files in `doc' not ending in `/txt', except for `tags'.
- Lose the extensions from the files in `doc'.
- Edit the `doc.tags' file. Remove extensions from the second column: >
:%s/^\(.[^\t]*\t.*\)\.txt\t/\1\t/
- Remove extensions from the syntax files. Split them into two directories
to avoid the 77 entry limit on old ADFS filesystems.
- Edit `Vim:FileType' to match `*.c.*' as well as `*/c' and so on.
Add filetype checking too.
- Edit `Vim:Menu' and remove all the keys from the menus: >
:%s/<Tab>[^ \t]*//
<
vim:tw=78:ts=8:ft=help:norl:

60
runtime/doc/os_unix.txt Normal file
View File

@@ -0,0 +1,60 @@
*os_unix.txt* For Vim version 7.0aa. Last change: 2003 Mar 15
VIM REFERENCE MANUAL by Bram Moolenaar
*unix* *Unix*
This file contains the particularities for the Unix version of Vim.
For compiling Vim on Unix see "INSTALL" and "Makefile" in the src directory.
The default help file name is "/usr/local/lib/vim/help.txt"
The files "$HOME/.vimrc" and "$HOME/.exrc" are used instead of "s:.vimrc" and
"s:.exrc". Additionally "/usr/local/etc/vimrc" is used first.
If "/usr/local/share" exists it is used instead of "/usr/local/lib".
Temporary files (for filtering) are put in "/tmp". If you want to place them
somewhere else, set the environment variable $TMPDIR to the directory you
prefer.
With wildcard expansion you can use '~' (home directory) and '$'
(environment variable).
*fork* *spoon*
For executing external commands fork()/exec() is used when possible, otherwise
system() is used, which is a bit slower. The output of ":version" includes
|+fork| when fork()/exec() is used, |+system()| when system() is used. This
can be changed at compile time.
(For forking of the GUI version see |gui-fork|).
Because terminal updating under Unix is often slow (e.g. serial line
terminal, shell window in suntools), the 'showcmd' and 'ruler' options
are default off. If you have a fast terminal, try setting them on. You might
also want to set 'ttyfast'.
When using Vim in an xterm the mouse clicks can be used by Vim by setting
'mouse' to "a". If there is access to an X-server gui style copy/paste will
be used and visual feedback will be provided while dragging with the mouse.
If you then still want the xterm copy/paste with the mouse, press the shift
key when using the mouse. See |mouse-using|. Visual feedback while dragging
can also be achieved via the 'ttymouse' option if your xterm is new enough.
*terminal-colors*
To use colors in Vim you can use the following example (if your terminal
supports colors, but "T_Co" is empty or zero): >
:set t_me=^[[0;1;36m " normal mode (undoes t_mr and t_md)
:set t_mr=^[[0;1;33;44m " reverse (invert) mode
:set t_md=^[[1;33;41m " bold mode
:set t_se=^[[1;36;40m " standout end
:set t_so=^[[1;32;45m " standout mode
:set t_ue=^[[0;1;36m " underline end
:set t_us=^[[1;32m " underline mode start
[the ^[ is an <Esc>, type CTRL-V <Esc> to enter it]
For real color terminals the ":highlight" command can be used.
The file "tools/Vim132" is a shell script that can be used to put Vim in 132
column mode on a vt100 and lookalikes.
vim:tw=78:ts=8:ft=help:norl:

779
runtime/doc/os_vms.txt Normal file
View File

@@ -0,0 +1,779 @@
*os_vms.txt* For Vim version 7.0aa. Last change: 2004 May 16
VIM REFERENCE MANUAL
*VMS* *vms*
This file contains the particularities for the VMS version of Vim.
You can reach this information file by typing :help VMS in Vim command
prompt.
1. Getting started |vms-started|
2. Download files |vms-download|
3. Compiling |vms-compiling|
4. Problems |vms-problems|
5. Deploy |vms-deploy|
6. Practical usage |vms-usage|
7. GUI mode questions |vms-gui|
8. Useful notes |vms-notes|
9. VMS related changes |vms-changes|
10. Authors |vms-authors|
==============================================================================
1. Getting started *vms-started*
Vim (Vi IMproved) is a vi-compatible text editor that runs on nearly every
operating system known to humanity. Now use Vim on OpenVMS too, in character
or X/Motif environment. It is fully featured and absolutely compatible with
Vim on other operating systems.
==============================================================================
2. Download files *vms-download*
You can download the Vim source code by ftp from the official Vim site:
ftp://ftp.vim.org/pub/vim/
Or use one of the mirrors:
ftp://ftp.vim.org/pub/vim/MIRRORS
You will need both the Unix and Extra archives to build vim.exe for VMS.
For using Vim's full power you will need the runtime files as well.
You can download precompiled executables from:
http://www.polarhome.com/vim/
ftp://ftp.polarhome.com/pub/vim/
To use the precompiled binary version, you need one of these archives:
vim-XX-exe-alpha-gui.zip Alpha GUI/Motif executables
vim-XX-exe-alpha-gtk.zip Alpha GUI/GTK executables
vim-XX-exe-alpha-term.zip Alpha console executables
vim-XX-exe-vax-gui.zip VAX GUI executables
vim-XX-exe-vax-term.zip VAX console executables
and of course
vim-XX-runtime.zip runtime files
The binary archives contain: vim.exe, ctags.exe, xxd.exe, mms_vim.exe files.
==============================================================================
3. Compiling *vms-compiling*
See the file [.SRC]INSTALLVMS.TXT.
==============================================================================
4. Problems *vms-problems*
The code has been tested under Open VMS 6.2 - 7.3 on Alpha and VAX platforms
with the DECC compiler. It should work without bigger problems.
If it happened that your system does not have some include libraries you can
tune up in OS_VMS_CONF.H file.
If you decided to build Vim with +perl, +python, etc. options, first you need
to download OpenVMS distributions of Perl and Python. Build and deploy the
libraries and change adequate lines in MAKE_VMS.MMS file. There should not be
problem from Vim side.
Note: Under VAX it should work with DEC C compiler without problem. VAXC
compiler is not fully ANSI C compatible in pre-processor directives
semantics, therefore you have to use a converter program what will do the
lion part of the job. For detailed instruction read file INSTALLvms.txt
MMS_VIM.EXE is building together with VIM.EXE, but for XD.EXE you should
change to subdirectory and build it separately.
CTAGS is not part of Vim source distribution any more, however the OpenVMS
specific source might contain CTAGS source files as it is described above.
You can find more information about CTAGS on VMS at
http://www.polarhome.com/ctags/
Advanced users may try some acrobatics in FEATURE.H file also.
It is possible to compile with +xfontset +xim options too, but then you have
to set up GUI fonts etc. correctly. See. :help xim from Vim command prompt.
You may want to use GUI with GTK icons, then you have to download and install
GTK for OpenVMS or at least runtime shareable images - LIBGTK from
polarhome.com
For more advanced questions, please send your problem to Vim on VMS mailing
list <vim-vms@polarhome.com>
More about the vim-vms list can be found at:
http://www.polarhome.com/mailman/listinfo/vim-vms
==============================================================================
5. Deploy *vms-deploy*
Vim uses a special directory structure to hold the document and runtime files:
vim (or wherever)
|- tmp
|- vim57
|----- doc
|----- syntax
|- vim60
|----- doc
|----- syntax
|- vim61
|----- doc
|----- syntax
vimrc (system rc files)
gvimrc
Use: >
define/nolog VIM device:[path.vim]
define/nolog VIMRUNTIME device:[path.vim.vim60]
define/nolog TMP device:[path.tmp]
to get vim.exe to find its document, filetype, and syntax files, and to
specify a directory where temporary files will be located. Copy the "runtime"
subdirectory of the vim distribution to vimruntime.
Logicals $VIMRUNTIME and $TMP are optional.
If $VIMRUNTIME is not set, Vim will guess and try to set up automatically.
Read more about at :help runtime
If $TMP is not set, you will not be able to use some functions as CTAGS,
XXD, printing etc. that use temporary directory for normal operation.
$TMP directory should be readable and writable by the user(s).
The easiest way to set up $TMP is to define logical: >
define/nolog TMP SYS$SCRATCH
or as: >
define/nolog TMP SYS$LOGIN
==============================================================================
6. Practical usage *vms-usage*
Usually, you want to run just one version of Vim on your system, therefore
it is enough to dedicate one directory for Vim.
Copy all Vim runtime directory structure to the deployment position.
Add the following lines to your LOGIN.COM (in SYS$LOGIN directory).
Set up logical $VIM as: >
$ define VIM device:<path>
Set up some symbols: >
$ ! vi starts Vim in chr. mode.
$ vi*m :== mcr VIM:VIM.EXE
$ !gvi starts Vim in GUI mode.
$ gv*im :== spawn/nowait mcr VIM:VIM.EXE -g
Please, check the notes for customization and configuration of symbols.
You may want to create .vimrc and .gvimrc files in your home directory
(SYS$LOGIN) to overwrite default settings.
The easiest way is just rename example files. You may leave the menu file
(MENU.VIM) and files vimrc and gvimrc in the original $VIM directory. It will
be default setup for all users, and for users is enough just to have their
own additions or resetting in home directory in files .vimrc and .gvimrc.
It should work without problems.
Note: Remember, system rc files (default for all users) does not have leading
"." So, system rc files are: >
$VIM:vimrc
$VIM:gvimrc
$VIM:menu.vim
and user's customized rc files are: >
sys$login:.vimrc
sys$login:.gvimrc
You can check that everything is on the right place with the :version command.
Example LOGIN.COM: >
$ define/nolog VIM RF10:[UTIL.VIM]
$ vi*m :== mcr VIM:VIM.EXE
$ gv*im:== spawn/nowait/input=NLA0 mcr VIM:VIM.EXE -g -GEOMETRY 80x40
$ set disp/create/node=192.168.5.223/trans=tcpip
Note: This set-up should be enough, if you are working on standalone server or
clustered environment, but if you want to use Vim as internode editor in
DECNET environment, it will satisfy you as well.
You just have to define the "whole" path: >
$ define VIM "<server_name>[""user password""]::device:<path>"
$ vi*m :== "mcr VIM:VIM.EXE"
as for example: >
$ define VIM "PLUTO::RF10:[UTIL.VIM]"
$ define VIM "PLUTO""ZAY mypass""::RF10:[UTIL.VIM]" ! if passwd required
You can also use $VIMRUNTIME logical to point to proper version of Vim if you
have installed more versions in the same time. If $VIMRUNTIME is not defined
Vim will borrow value from $VIM logical. You can find more information about
$VIMRUNTIME logical by typing :help runtime as a Vim command.
System administrators might want to set up a system wide Vim installation,
then add to the SYS$STARTUP:SYLOGICALS.COM >
$ define/nolog/sys VIM device:<path>
$ define/nolog/sys TMP SYS$SCRATCH
and to the SYS$STARTUP:SYLOGIN.COM >
$ vi*m :== mcr VIM:VIM.EXE
$ gv*im:== spawn/nowait/input=NLA0 mcr VIM:VIM.EXE -g -GEOMETRY 80x40
It will set up normal Vim work environment for every user on the system.
==============================================================================
7. GUI mode questions *vms-gui*
OpenVMS in a real mainframe OS, therefore even if it has a GUI console, most of
the users does not use a native X/Window environment during normal operation.
It is not possible to start Vim in GUI mode "just like that". But anyhow it is
not too complicate either.
First of all: you will need an executable that is built with enabled GUI.
Second: you need to have installed DECW/Motif on your VMS server, otherwise
you will get errors that some shareable libraries are missing.
Third: If you choose to run Vim with extra feature as GUI/GTK then you need
GTK installation too or at least GTK runtime environment (LIBGTK etc.)
1) If you are working on the VMS X/Motif console:
Start Vim with the command: >
$ mc device:<path>VIM.EXE -g
<
or type :gui as a command to the Vim command prompt. For more info :help gui
2) If you are working on other X/Window environment as Unix or some remote X
VMS console. Set up display to your host with: >
$ set disp/create/node=<your IP address>/trans=<transport-name>
<
and start Vim as in point 1. You can find more help in VMS documentation or
type: help set disp in VMS prompt.
Examples: >
$ set disp/create/node=192.168.5.159 ! default trans is DECnet
$ set disp/create/node=192.168.5.159/trans=tcpip ! TCP/IP network
$ set disp/create/node=192.168.5.159/trans=local ! display on the same node
Note: you should define just one of these.
For more information type $help set disp in VMS prompt.
3) Another elegant solution is XDM if you have installed on OpenVMS box.
It is possible to work from XDM client as from GUI console.
4) If you are working on MS Windows or other non X/Window environment
You need to set up one X server and run Vim as in point 2.
For MS Windows there are available free X servers as MIX , Omni X etc.
as well as excellent commercial products as eXcursion or ReflectionX with
buit in DEC support.
Please note, that executables without GUI are slightly faster during startup
then with enabled GUI in character mode. Therefore, if you do not use GUI
features, it is worth to choose non GUI executables.
==============================================================================
8. Useful notes *vms-notes*
8.1 backspace/delete
8.2 Filters
8.3 VMS file version numbers
8.4 Directory conversion
8.5 Remote host invocation
8.6 Terminal problems
8.7 Hex-editing and other external tools
8.8 Sourcing vimrc and gvimrc
8.9 Printing from Vim
8.10 Setting up the symbols
8.11 diff and other GNU programs
8.12 diff-mode
8.13 Allow '$' in C keywords
8.14 VIMTUTOR for beginners
8.1 backspace/delete
There are backspace/delete key inconsistencies with VMS.
:fixdel doesn't do the trick, but the solution is: >
:inoremap ^? ^H " for terminal mode
:inoremap <Del> ^H " for gui mode
Read more in ch: 8.6 (Terminal problems).
(Bruce Hunsaker <BNHunsaker@chq.byu.edu> Vim 5.3)
8.2 Filters
Vim supports filters; ie. if you have a sort program that can handle
input/output redirection like Unix (<infile >outfile), you could use >
:map \s 0!'aqsort<CR>
(Charles E. Campbell, Jr. <cec@gryphon.gsfc.nasa.gov> Vim 5.4)
8.3 VMS file version numbers
Vim is saving files into a new file with the next higher file version
number, try these settings. >
:set nobackup " does not create *.*_ backup files
:set nowritebackup " does not have any purpose on VMS. It's default.
Recovery is working perfect as well from the default swap file.
Read more with :help swapfile
(Claude Marinier <ClaudeMarinier@xwavesolutions.com> Vim 5.5, Zoltan Arpadffy
Vim 5.6 )
8.4 Directory conversion
Vim will internally convert any unix-style paths and even mixed unix/VMS
paths into VMS style paths. Some typical conversions resemble:
/abc/def/ghi -> abc:[def]ghi.
/abc/def/ghi.j -> abc:[def]ghi.j
/abc/def/ghi.j;2 -> abc:[def]ghi.j;2
/abc/def/ghi/jkl/mno -> abc:[def.ghi.jkl]mno.
abc:[def.ghi]jkl/mno -> abc:[def.ghi.jkl]mno.
./ -> current directory
../ -> relative parent directory
[.def.ghi] -> relative child directory
./def/ghi -> relative child directory
Note: You may use <,> brackets as well (device:<path>file.ext;version) as
rf10:<user.zay.work>test.c;1
(David Elins <delins@foliage.com>, Jerome Lauret
<JLAURET@mail.chem.sunysb.edu> Vim 5.6 )
8.5 Remote host invocation
It is possible to use Vim as an internode editor.
1. Edit some file from remote node: >
vi "<server>""username passwd""::<device>:<path><filename>;<version>"
example: >
vi "pluto""zay passwd""::RF10:<USER.ZAY.WORK>TEST.C;1"
Note: syntax is very important, otherwise VMS will recognize more parameters
instead of one (resulting with: file not found)
2. Set up Vim as your internode editor. If Vim is not installed on your host,
just set up your IP address, full Vim path including the server name and run
the command procedure below: >
$ if (p1 .eqs. "") .OR. (p2 .eqs. "") then goto usage
$ set disp/create/node=<your_IP_here>/trans=tcpip
$ define "VIM "<vim_server>""''p1' ''p2'""::<device>:<vim_path>"
$ vi*m :== "mcr VIM:VIM.EXE"
$ gv*im :== "spawn/nowait mcr VIM:VIM.EXE -g"
$ goto end
$ usage:
$ write sys$output " Please enter username and password as a parameter."
$ write sys$output " Example: @SETVIM.COM username passwd"
$ end:
Note: Never use it in clustered environment (you do not need it), and load could
be very-very slow, but even faster then a local Emacs. :-)
(Zoltan Arpadffy, Vim 5.6)
8.6 Terminal problems
If your terminal name is not known to Vim and it is trying to find the default
one you will get the following message during start-up:
---
Terminal entry not found in termcap
'unknown-terminal' not known. Available built-in terminals are:
builtin_gui
builtin_riscos
builtin_amiga
builtin_beos-ansi
builtin_ansi
builtin_vt320
builtin_vt52
builtin_pcansi
builtin_win32
builtin_xterm
builtin_iris-ansi
builtin_debug
builtin_dumb
defaulting to 'vt320'
---
The solution is to define default terminal name: >
$ ! unknown terminal name. let us use vt320 or ansi instead.
$ ! Note: it's case sensitive
$ define term "vt320"
Terminals from VT100 to VT320 (as V300, VT220, VT200 ) do not need any extra
keyboard mappings. They should work perfect as they are, including arrows,
Ins, Del buttons etc. Except Backspace in GUI mode. To solve it, add to
.gvimrc: >
inoremap <Del> <BS>
Vim will also recognize that they are fast terminals.
If you have some annoying line jumping on the screen between windows add to
your .vimrc file: >
set ttyfast " set fast terminal
Note: if you're using Vim on remote host or through very slow connection, it's
recommended to avoid fast terminal option with: >
set nottyfast " set terminal to slow mode
(Zoltan Arpadffy, Vim 5.6)
8.7 Hex-editing and other external tools
A very important difference between OpenVMS and other systems is that VMS uses
special commands to execute executables: >
RUN <path>filename
MCR <path>filename <parameters>
OpenVMS users always have to be aware that the Vim command :! "just" drop them
to DCL prompt. This feature is possible to use without any problem with all
DCL commands, but if we want to execute some program as XXD, CTAGS, JTAGS etc.
we're running into trouble if we following the Vim documentation (see: help
xxd).
Solution: Execute with the MC command and add the full path to the executable.
Example: Instead of :%!xxd command use: >
:%!mc vim:xxd
... or in general: >
:!mc <path>filename <parameters>
Note: You can use XXD, and CTAGS from GUI menu.
To customize ctags it is possible to define logical $CTAGS with standard
parameters as: >
define/nolog CTAGS "--totals -o sys$login:tags"
For additional information, please read :help tagsearch and CTAGS
documentation at http://ctags.sourceforge.net/ctags.html.
(Zoltan Arpadffy, Vim 5.6-70)
8.8 Sourcing vimrc and gvimrc
If you want to use your .vimrc and .gvimrc from other platforms (e.g. Windows)
you can get in trouble if you ftp that file(s): VMS has different end-of-line
indication.
The symptom is that ViM is not sourcing your .vimrc/.gvimrc, even if you say:
>
:so sys$login:.vimrc
One trick is to compress (e.g. zip) the files on the other platform and
uncompress it on VMS; if you have the same symptom, try to create the files
with copy-paste (for this you need both op. systems reachable from one
machine, e.g. an Xterm on Windows or telnet to Windows from VMS).
(Sandor Kopanyi, <sandor.kopanyi@mailbox.hu> Vim 6.0a)
8.9 Printing from Vim
To be able to print from Vim (running in GUI mode) under VMS you have to set
up $TMP logical which should point to some temporary directory and logical
SYS$PRINT to your default print queue.
Example: >
$define SYS$PRINT HP5ANSI
You can print out whole buffer or just the marked area.
More info under :help hardcopy
(Zoltan Arpadffy, Vim 6.0c)
8.10 Setting up the symbols
When I use GVIM this way and press CTRL-Y in the parent terminal, gvim exits.
I now use a different symbol that seems to work OK and fixes the problem.
I suggest this instead: >
$ GV*IM:==SPAWN/NOWAIT/INPUT=NLA0: MCR VIM:VIM.EXE -G -GEOMETRY 80X40
The /INPUT=NLA0: separates the standard input of the gvim process from the
parent terminal, to block signals from the parent window.
Without the -GEOMETRY, the GVIM window size will be minimal and the menu
will be confused after a window-resize.
(Carlo Mekenkamp, Coen Engelbarts, Vim 6.0ac)
8.11 diff and other GNU programs
From 6.0 diff functionality has been implemented, but OpenVMS does not use
GNU/Unix like diff therefore built in diff does not work.
There is a simple solution to solve this anomaly. Install an Unix like diff
and Vim will work perfect in diff mode too. You just have to redefine your
diff program as: >
define /nolog diff <GNU_PATH>diff.exe
Another, more sophisticated solution is described below (8.12 diff-mode)
There are some other programs as patch, make etc that may cause same problems.
At www.polarhome.com is possible to download an GNU package for Alpha and VAX
boxes that is meant to solve GNU problems on OpenVMS.
( Zoltan Arpadffy, Vim 6.1)
8.12 diff-mode
Vim 6.0 and higher supports vim diff-mode (See |new-diff-mode|, |diff-mode|
and |08.7|). This uses the external program 'diff' and expects a Unix-like
output format from diff. The standard VMS diff has a different output
format. To use vim on VMS in diff-mode, you need to:
1 Install a Unix-like diff program, e.g. GNU diff
2 Tell vim to use the Unix-like diff for diff-mode.
You can download GNU diff from the VIM-VMS website, it is one of the GNU
tools in http://www.polarhome.com/vim/files/gnu_tools.zip. I suggest to
unpack it in a separate directory "GNU" and create a logical GNU: that
points to that directory. e.g: >
DEFINE GNU <DISK>:[<DIRECTORY>.BIN.GNU]
You may also want to define a symbol GDIFF, to use the GNU diff from the DCL
prompt: >
GDIFF :== $GNU:DIFF.EXE
Now you need to tell vim to use the new diff program. Take the example
settings from |diff-diffexpr| and change the call to the external diff
program to the new diff on VMS. Add this to your .vimrc file: >
" Set up vimdiff options
if v:version >= 600
" Use GNU diff on VMS
set diffexpr=MyDiff()
function MyDiff()
let opt = ""
if &diffopt =~ "icase"
let opt = opt . "-i "
endif
if &diffopt =~ "iwhite"
let opt = opt . "-b "
endif
silent execute "!mc GNU:diff.exe -a " . opt . v:fname_in . " " . v:fname_new .
\ " > " . v:fname_out
endfunction
endif
You can now use vim in diff-mode, e.g. to compare two files in read-only
mode: >
$ VIM -D/R <FILE1> <FILE2>
You can also define new symbols for vimdiff, e.g.: >
$ VIMDIFF :== 'VIM' -D/R
$ GVIMDIFF :== 'GVIM' -D/R
You can now compare files in 4 ways: >
1. VMS diff: $ DIFF <FILE1> <FILE2>
2. GNU diff: $ GDIFF <FILE1> <FILE2>
3. VIM diff: $ VIMDIFF <FILE1> <FILE2>
4. GVIM diff: $ GVIMDIFF <FILE1> <FILE2>
( Coen Engelbarts, Vim 6.1)
8.13 Allow '$' in C keywords
DEC C uses many identifiers with '$' in them. This is not allowed in ANSI C,
and vim recognises the '$' as the end of the identifier. You can change this
with the |iskeyword|command.
Add this command to your .vimrc file: >
autocmd FileType c,cpp,cs set iskeyword+=$
You can also create the file(s) $VIM/FTPLUGIN/C.VIM (and/or CPP.VIM and
CS.VIM) and add this command: >
set iskeyword+=$
Now word-based commands, e.g. the '*'-search-command and the CTRL-]
tag-lookup, work on the whole identifier. (Ctags on VMS also supports '$' in
C keywords since ctags version 5.1.)
( Coen Engelbarts, Vim 6.1)
8.14 VIMTUTOR for beginners
It exits VIMTUTOR.COM DCL script that can help Vim beginners to learn/make
first steps with Vim on OpenVMS. Depending of binary distribution you may start
it with: >
@vim:vimtutor
(Thomas.R.Wyant III, Vim 6.1)
==============================================================================
9. VMS related changes *vms-changes*
Version 6.3 (2004 May 10)
- Improved vms_read function
- CTAGS v5.5.4 included
- Documentation corrected and updated
Version 6.2 (2003 May 7)
- Corrected VMS system call results
- Low level character input is rewritten
- Correction in tag and quickfix handling
- First GTK build
- Make file changes
- GTK feature added
- Define for OLD_VMS
- OpenVMS version 6.2 or older
- Documentation updated with GTK features
- CTAGS v5.5 included
- VMS VIM tutor created
Version 6.1 (2002 Mar 25)
- TCL init_tcl() problem fixed
- CTAGS v5.4 included
- GNU tools binaries for OpenVMS
- Make file changes
- PERL, PYTHON and TCL support improved
- InstallVMS.txt has a detailed description HOWTO build
- VMS/Unix file handling rewritten
- Minor casting and bug fixes
Version 6.0 (2001 Sep 28)
- Unix and VMS code has been merged
- separated "really" VMS related code
- included all possible Unix functionality
- simplified or deleted the configuration files
- makefile MAKE_VMS.MMS reviewed
- menu changes (fixed printing, CTAGS and XXD usage)
- fixed variable RMS record format handling anomaly
- corrected syntax, ftplugin etc files load
- changed expand_wildcards and expandpath functions to work more general
- created OS_VMS_FILTER.COM - DECC->VAXC pre-processor directive convert
script.
- Improved code's VAXC and new DECC compilers compatibility
- changed quickfix parameters:
- errormessage format to suite DECC
- search, make and other commands to suite VMS system
- updated and renamed MMS make files for Vim and CTAGS.
- CTAGS has been removed from source distribution of Vim but it will remain
in OpenVMS binary distributions.
- simplified build/configuration procedure
- created INSTALLvms.txt - detailed compiling instructions under VMS.
- updated test scripts.
Version 5.8 (2001 Jun 1)
- OS_VMS.TXT updated with new features.
- other minor fixes.
- documentation updated
- this version had been tested much more than any other OpenVMS version
earlier
Version 5.7 (2000 Jun 24)
- New CTAGS v5.0 in distribution
- Documentation updated
Version 5.6 (2000 Jan 17)
- VMS filename related changes:
- version handling (open everything, save to new version)
- correct file extension matching for syntax (version problem)
- handle <,> characters and passwords in directory definition
- handle internode/remote invocation and editing with passwords
- OpenVMS files will be treated case insensitive from now
- corrected response of expand("%:.") etc path related functions
(in one word: VMS directory handling internally)
- version command
- corrected (+,-) information data
- added compiler and OS version
- added user and host information
- resolving $VIM and $VIMRUNTIME logicals
- VMS port is in MAX_FEAT (maximum features) club with Unix, Win32 and OS/2.
- enabled farsi, rightleft etc. features
- undo level raised up to 1000
- Updated OS_VMS.MMS file.
- maximum features ON is default
- Vim is compilable with +perl, +python and +tcl features.
- improved MMK compatibility
- Created MAKEFILE_VMS.MMS, makefile for testing Vim during development.
- Defined DEC terminal VT320
- compatibility for VT3*0, VT2*0 and VT1*0 - ANSI terminals
backwards, but not VT340 and newer with colour capability.
- VT320 is default terminal for OpenVMS
- these new terminals are also fast ttys (default for OpenVMS).
- allowed dec_mouse ttym
- Updated files vimrc and gvimrc with VMS specific suggestions.
- OS_VMS.TXT updated with new features.
Version 5.5 (1999 Dec 3)
- Popup menu line crash corrected.
- Handle full file names with version numbers.
- Directory handling (CD command etc.)
- Corrected file name conversion VMS to Unix and v.v.
- Correct response of expand wildcards
- Recovery is working from this version under VMS as well.
- Improved terminal and signal handing.
- Improved OS_VMS.TXT
Version 5.4 (1999 Sep 9)
- Cut and paste mismatch corrected.
- Motif directories during open and save are corrected.
Version 5.3 (1998 Oct 12)
- Minor changes in the code
- Standard distribution with +GUI option
Version 5.1 (1998 Apr 21)
- Syntax and DEC C changes in the code
- Fixing problems with the /doc subdirectory
- Improve OS_VMS.MMS
Version 4.5 (1996 Dec 16)
- First VMS port by Henk Elbers <henk@xs4all.nl>
==============================================================================
10. Authors *vms-authors*
OpenVMS documentation and executables are maintained by:
Zoltan Arpadffy <arpadffy@polarhome.com>
This document uses parts and remarks from earlier authors and contributors
of OS_VMS.TXT:
Charles E. Campbell, Jr. <cec@gryphon.gsfc.nasa.gov>
Bruce Hunsaker <BNHunsaker@chq.byu.edu>
Sandor Kopanyi <sandor.kopanyi@mailbox.hu>
vim:tw=78:ts=8:ft=help:norl:

319
runtime/doc/os_win32.txt Normal file
View File

@@ -0,0 +1,319 @@
*os_win32.txt* For Vim version 7.0aa. Last change: 2004 May 01
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 both Windows NT and Windows 95. There are
both console and GUI versions. There is GUI version for use in the Win32s
subsystem in Windows 3.1[1]. You can also use the 32-bit DOS version of Vim
instead. See |os_msdos.txt|.
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 3.1 |win32-win3.1|
6. 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|
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/INSTALL.pc". *win32-compiling*
==============================================================================
1. Known problems *windows95* *win32-problems*
There are a few known problems with running in a console on Windows 95. As
far as we know, this is the same in Windows 98 and Windows ME.
Comments from somebody working at Microsoft: "Win95 console support has always
been and will always be flaky".
1. Dead key support doesn't work.
2. Resizing the window with ":set columns=nn lines=nn" works, but executing
external commands MAY CAUSE THE SYSTEM TO HANG OR CRASH.
3. Screen updating is slow, unless you change 'columns' or 'lines' to a
non-DOS value. But then the second problem applies!
If this bothers you, use the 32 bit MS-DOS version or the Win32 GUI version.
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".
==============================================================================
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 3.1 *win32-win3.1*
*win32s* *windows-3.1*
There is a special version of Gvim that runs under Windows 3.1 and 3.11. You
need the gvim.exe that was compiled with Visual C++ 4.1.
To run the Win32 version under Windows 3.1, you need to install Win32s. You
might have it already from another Win32 application which you have installed.
If Vim doesn't seem to be running properly, get the latest version: 1.30c.
You can find it at:
http://support.microsoft.com/download/support/mslfiles/pw1118.exe
(Microsoft moved it again, we don't know where it is now :-( ).
The reason for having two versions of gvim.exe is that the Win32s version was
compiled with VC++ 4.1. This is the last version of VC++ that supports Win32s
programs. VC++ 5.0 is better, so that one was used for the Win32 version.
Apart from that, there is no difference between the programs. If you are in a
mixed environment, you can use the gvim.exe for Win32s on both.
The Win32s version works the same way as the Win32 version under 95/NT. When
running under Win32s the following differences apply:
- You cannot use long file names, because Windows 3.1 doesn't support them!
- When executing an external command, it doesn't return an exit code. After
doing ":make" you have to do ":cn" yourself.
==============================================================================
6. Win32 mini FAQ *win32-faq*
Q. Why does the Win32 version of Vim update the screen so slowly on Windows 95?
A. The support for Win32 console mode applications is very buggy in Win95.
For some unknown reason, the screen updates very slowly when Vim is run at
one of the standard resolutions (80x25, 80x43, or 80x50) and the 16-bit DOS
version updates the screen much more quickly than the Win32 version.
However, if the screen is set to some other resolution, such as by ":set
columns=100" or ":set lines=40", screen updating becomes about as fast as
it is with the 16-bit version.
WARNING: Changing 'columns' may make Windows 95 crash while updating the
window (complaints --> Microsoft). Since this mostly works, this has not
been disabled, but be careful with changing 'columns'.
Changing the screen resolution makes updates faster, but it brings
additional problems. External commands (e.g., ":!dir") can cause Vim to
freeze when the screen is set to a non-standard resolution, particularly
when 'columns' is not equal to 80. It is not possible for Vim to reliably
set the screen resolution back to the value it had upon startup before
running external commands, so if you change the number of 'lines' or
'columns', be very, very careful. In fact, Vim will not allow you to
execute external commands when 'columns' is not equal to 80, because it is
so likely to freeze up afterwards.
None of the above applies on Windows NT. Screen updates are fast, no
matter how many 'lines' or 'columns' the window has, and external commands
do not cause Vim to freeze.
Q. So if the Win32 version updates the screen so slowly on Windows 95 and the
16-bit DOS version updates the screen quickly, why would I want to run the
Win32 version?
A. Firstly, the Win32 version isn't that slow, especially when the screen is
set to some non-standard number of 'lines' or 'columns'. Secondly, the
16-bit DOS version has some severe limitations: It can't do big changes and
it doesn't know about long file names. The Win32 version doesn't have these
limitations and it's faster overall (the same is true for the 32-bit DJGPP
DOS version of Vim). The Win32 version is smarter about handling the
screen, the mouse, and the keyboard than the DJGPP version is.
Q. And what about the 16-bit DOS version versus the Win32 version on NT?
A. There are no good reasons to run the 16-bit DOS version on NT. The Win32
version updates the screen just as fast as the 16-bit version does when
running on NT. All of the above disadvantages apply. Finally, DOS
applications can take a long time to start up and will run more slowly. On
non-Intel NT platforms, the DOS version is almost unusably slow, because it
runs on top of an 80x86 emulator.
Q. How do I change the font?
A. In the GUI version, you can use the 'guifont' option.
In the console version, you need to set the font of the console itself.
You cannot do this from within Vim.
Q. When I change the size of the console window with ':set lines=xx' or
similar, the font changes! (Win95)
A. You have the console font set to 'Auto' in Vim's (or your MS-DOS prompt's)
properties. This makes W95 guess (badly!) what font is best. Set an explicit
font instead.
Q. Why can't I paste into Vim when running Windows 95?
A. In the properties dialog box for the MS-DOS window, go to "MS-DOS
Prompt/Misc/Fast pasting" and make sure that it is NOT checked. You should
also do ":set paste" in Vim to avoid unexpected effects. |'paste'|
Q. How do I type dead keys on Windows 95, in the console version?
(A dead key is an accent key, such as acute, grave, or umlaut, that doesn't
produce a character by itself, but when followed by another key, produces
an accented character, such as a-acute, e-grave, u-umlaut, n-tilde, and so
on. Very useful for most European languages. English-language keyboard
layouts don't use dead keys, as far as we know.)
A. You don't. The console mode input routines simply do not work correctly in
Windows 95, and I have not been able to work around them. In the words
of a senior developer at Microsoft:
Win95 console support has always been and will always be flaky.
The flakiness is unavoidable because we are stuck between the world of
MS-DOS keyboard TSRs like KEYB (which wants to cook the data;
important for international) and the world of Win32.
So keys that don't "exist" in MS-DOS land (like dead keys) have a
very tenuous existence in Win32 console land. Keys that act
differently between MS-DOS land and Win32 console land (like
capslock) will act flaky.
Don't even _mention_ the problems with multiple language keyboard
layouts...
You may be able to fashion some sort of workaround with the digraphs
mechanism. |digraphs|
The best solution is to use the Win32 GUI version gvim.exe. Alternatively,
you can try one of the DOS versions of Vim where dead keys reportedly do
work.
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. 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 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 run an external command or program asynchronously?
A. When using :! to run an external command, you can run it with "start": >
:!start winfile.exe<CR>
< 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 effect 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".
Q. I'm using Win32s, and when I try to run an external command like "make",
Vim doesn't wait for it to finish! Help!
A. The problem is that a 32-bit application (Vim) can't get notification from
Windows that a 16-bit application (your DOS session) has finished. Vim
includes a work-around for this, but you must set up your DOS commands to
run in a window, not full-screen. Unfortunately the default when you
install Windows is full-screen. To change this:
1) Start PIF editor (in the Main program group)
2) Open the file "_DEFAULT.PIF" in your Windows directory.
3) Changes the display option from "Full Screen" to "Windowed".
4) Save and exit.
To test, start Vim and type >
:!dir C:\<CR>".
< You should see a DOS box window appear briefly with the directory listing.
Q. I use Vim under Win32s and NT. In NT, I can define the console to default to
50 lines, so that I get a 80x50 shell when I ':sh'. Can I do the same in
W3.1x, or am I stuck with 80x25?
A. Edit SYSTEM.INI and add 'ScreenLines=50' to the [NonWindowsApp] section. DOS
prompts and external DOS commands will now run in a 50-line window.
vim:tw=78:fo=tcq2:ts=8:ft=help:norl:

1146
runtime/doc/pattern.txt Normal file
View File

File diff suppressed because it is too large Load Diff

215
runtime/doc/pi_expl.txt Normal file
View File

@@ -0,0 +1,215 @@
*pi_expl.txt* For Vim version 7.0aa. Last change: 2002 Nov 08
VIM REFERENCE MANUAL by M A Aziz Ahmed
updated by Mark Waggoner
*file-explorer* *file-browser*
Plugin for exploring (or browsing) directories and files
1. Starting the file explorer |expl-starting|
The functionality mentioned here is a |standard-plugin|.
This plugin is only available if 'compatible' is not set.
You can avoid loading this plugin by setting the "loaded_explorer" variable: >
:let loaded_explorer = 1
{Vi does not have any of this}
==============================================================================
1. Starting the file explorer *expl-starting*
This plugin is used to explore directories inside Vim. The file explorer is
launched whenever the user tries to edit a directory.
*:Explore* *:Sexplore*
To launch the explorer in the directory of the file currently edited: >
:Explore
If the file has changes the window is split. To always split the window: >
:Sexplore
To launch the explorer in a specific directory: >
:Explore dirname
:Sexplore dirname
From inside the explorer move your cursor to a line containing a file or
directory name. The following command keys are available:
<enter> will open the file in the window the explorer is currently
occupying.
'o' will split a new window and open the file in the new window.
'O' will open the file chosen using the window that the cursor was in just
before you started or entered the explorer window. If the explorer is
the only window, it will first split a new window to use for the file to
be opened.
'p' will open (or use) the preview window showing the file
'x' will execute the file with the system tools. Only when supported
(currently MS-Windows and KDE).
When splitting off a new window, you can control where the split window will
go relative to the explorer window using the variables g:explVertical,
g:explSplitBelow and g:explSplitRight.
*g:explVertical*
*g:explSplitBelow*
*g:explSplitRight*
*g:explStartBelow*
*g:explStartRight*
To control whether the split is made horizontally or vertically, use: >
let g:explVertical=1 " Split vertically
let g:explVertical=0 " Split horizontally (default)
To control where the window goes relative to the explorer window when
splitting horizontally, use the variable: >
let g:explSplitBelow=1 " Put new window below explorer window
let g:explSplitBelow=0 " Put new window above explorer window
The default for this is the setting of splitbelow at the time the plugin is
loaded.
To control where the windows goes relative to the explorer window when
splitting vertically, use the variable: >
let g:explSplitRight=1 " Put new window to the right of the explorer
let g:explSplitRight=0 " Put new window to the left of the explorer
The default for this is the setting of splitright at the time the plugin is
loaded.
To use a different split method for the explorer window, use: >
let g:explStartRight=1 " Put new explorer window to the right of the
" current window
let g:explStartRight=0 " Put new explorer window to the left of the
" current window
The default for this set to g:explSplitRight at the time the plugin is loaded.
To use a different split method for the explorer window, use: >
let g:explStartBelow=1 " Put new explorer window below the
" current window
let g:explStartBelow=0 " Put new explorer window above the
" current window
The default for this set to g:explSplitBelow at the time the plugin is loaded.
The start splits allow for the explorer window to be placed in a file browser
type arrangement, where the directories are shown on the left and the contents
opened on the right. The start split settings are only used when issuing
the Sexplore command.
Note that the window split is done a little bit differently than window splits
are usually done. Ordinarily, when splitting a window, the space occupied by
the current window will be split to give space for the new window. The
explorer attempts to instead split from a window adjacent to the explorer
window so that the explorer window will not change sizes. If there is not an
adjacent window in the direction you are splitting, the explorer window is
split.
*g:explWinSize*
After opening a file with the 'o' command, you might want to resize the
explorer window. This can be done by setting the variable >
let g:explWinSize=N
N is the number of rows (when the window is split horizontally) or the number
of columns (when the window is split vertically). If g:explWinSize is set to
an empty string (""), resizing will not be done. g:explWinSize defaults to
15.
*g:explDetailedList*
The file size (in bytes) and modification time can be displayed inside the
file explorer window. By pressing 'i', you can toggle between the name only
display and the more lengthy display. If you want the size and date to show
by default, use >
let g:explDetailedList=1
Doing this may slightly slow down explorer. The difference may or may not be
noticeable depending on your system and whether the directory is local or on
the network and on the size of the directory.
*g:explDateFormat*
The format of date displayed is configurable using the variable
g:explDateFormat. explorer uses this variable to pass to strftime() to fetch
the date information. |strftime()| The default is >
let g:explDateFormat="%d %b %Y %H:%M"
Note that for sorting purposes, the date is always placed at the end of the
line in its 'raw' form. If you have syntax highlighting turned on, this raw
date should be invisible.
*g:explHideFiles*
You can hide some files by filling the variable g:explHidFiles with regular
expressions. A filename that matches any of these regular expressions will not
be shown. For example, >
let g:explHideFiles='^\.,\.gz$,\.exe$,\.zip$'
will not show files that begin with "." and those that end in .gz, .exe or
.zip. However, all directory names will always be shown. If while exploring,
you'd like to see the hidden files as well, use the command "a".
The explorer header will indicate if filtering is being done.
*g:explDetailedHelp*
The help information spanning a few lines can be turned off (and just a single
help message enabled) using the option >
let g:explDetailedHelp=0
You can anytime switch to the detailed help format by pressing ?.
*explorer-delete*
Pressing 'D' inside explorer deletes the file under the cursor. You can delete
many files by visually selecting them and using 'D'. The deletion is
interactive in the form y/n/a/q. Directory deletion is not supported (mainly
because there is no way to delete a directory using a vim built-in function).
*explorer-rename*
Pressing 'R' inside explorer will allow you to rename the file under the
cursor.
*g:explSortBy*
The display in the file explorer can be sorted in forward or reverse order by
name, size, or modification date. You can set the default sorting direction
with the option >
let g:explSortBy='name' " alphabetically
let g:explSortBy='reverse name' " reverse alphabetically
let g:explSortBy='date' " newest first
let g:explSortBy='reverse date' " oldest first
let g:explSortBy='size' " largest first
let g:explSortBy='reverse size' " smallest first
While in the explorer, you can rotate through the sort fields by pressing the
's' key and you can reverse the current sort order by pressing the 'r' key.
Sorting on fields other than the name will be faster if the size and date are
displayed (using 'i' or g:explDetailedList).
The explorer heading will indicate the current sort order.
*g:explDirsFirst*
To control the segregation of directories and files, you can set this option >
let g:explDirsFirst=1 " Directories at the top of the list (default)
let g:explDirsFirst=0 " Directories mixed in with files
let g:explDirsFirst=-1 " Directories at the bottom of the list
*g:explSuffixesLast*
To control the segregation of files matching the suffixes option, you can set
this option >
let g:explSuffixesLast=1 " Files matching suffixes sorted at the bottom
" of the list (default)
let g:explSuffixesLast=0 " Files matching suffixes sorted normally
let g:explSuffixesLast=-1 " Files matching suffixes sorted at the top of
" the list
The heading will indicate if suffixes have been moved to the end (or start) of
the list.
*g:explUseSeparators*
Directories and files matching the suffixes list will be highlighted. If you
have the directories, files, and suffixes separated, and you would like a
separator line between the groups, you can set the option >
let g:explUseSeparators=1 " Use separator lines
let g:explUseSeparators=0 " Don't use separator lines
<
*g:explFileHandler*
If you set the "g:explFileHandler" variable to the name of a function, typing
'x' will call this function. The file or directory under the cursor will be
passed as an argument to the function. Suppose you have KDE, you could use
this: >
function MyFileHandler(fn)
exec "silent! !kfmclient exec " . escape(a:fn,' \%#')
endfunction
let g:explFileHandler = 'MyFileHandler'
For Win32 the variable is set by default to invoke the execute action. If you
type 'x' on a HTML file, Microsoft Internet Explorer will start (or whatever
application you have associated with HTML files).
==============================================================================
vim:tw=78:noet:ts=8:ft=help:norl:

39
runtime/doc/pi_gzip.txt Normal file
View File

@@ -0,0 +1,39 @@
*pi_gzip.txt* For Vim version 7.0aa. Last change: 2002 Oct 29
VIM REFERENCE MANUAL by Bram Moolenaar
Editing compressed files with Vim *gzip* *bzip2* *compress*
1. Autocommands |gzip-autocmd|
The functionality mentioned here is a |standard-plugin|.
This plugin is only available if 'compatible' is not set.
You can avoid loading this plugin by setting the "loaded_gzip" variable: >
:let loaded_gzip = 1
{Vi does not have any of this}
==============================================================================
1. Autocommands *gzip-autocmd*
The plugin installs autocommands to intercept reading and writing of files
with these extensions:
extension compression ~
*.Z compress (Lempel-Ziv)
*.gz gzip
*.bz2 bzip2
That's actually the only thing you need to know. There are no options.
After decompressing a file, the filetype will be detected again. This will
make a file like "foo.c.gz" get the "c" filetype.
If you have 'patchmode' set, it will be appended after the extension for
compression. Thus editing the patchmode file will not give you the automatic
decompression. You have to rename the file if you want this.
==============================================================================
vim:tw=78:ts=8:ft=help:norl:

543
runtime/doc/pi_netrw.txt Normal file
View File

@@ -0,0 +1,543 @@
*pi_netrw.txt* For Vim version 7.0aa. Last change: Apr 21, 2004
VIM REFERENCE MANUAL by Charles E. Campbell, Jr.
*dav* *http* *network* *rcp* *scp*
*fetch* *netrw* *Nread* *rsync* *sftp*
*ftp* *netrw.vim* *Nwrite* *netrw-file*
==============================================================================
0. Contents *netrw-contents*
1. Netrw Reference.....................................|netrw-ref|
2. Network-Oriented File Transfer......................|netrw-xfer|
3. Activation..........................................|netrw-activate|
4. Transparent File Transfer...........................|netrw-transparent|
5. Ex Commands.........................................|netrw-ex|
6. Variables and Options...............................|netrw-var|
7. Debugging...........................................|netrw-debug|
8. New Stuff...........................................|netrw-new|
9. Credits.............................................|netrw-credits|
The functionality mentioned here is done via using |standard-plugin|
techniques. This plugin is only available if
set nocp " 'compatible' is not set
filetype plugin on " plugins are enabled
You can avoid loading this plugin by setting the "loaded_netrw" variable
in your <.vimrc> file: >
:let loaded_netrw = 1
{Vi does not have any of this}
==============================================================================
1. Netrw Reference *netrw-ref*
OPTIONS
let g:netrw_ftp =0 use ftp (default) (uid password)
=1 use alternate ftp method (user uid password)
If you're having trouble with ftp, try changing the value
of this variable in your <.vimrc> to change methods
let g:netrw_ignorenetrc= 1
If you have a <.netrc> file but it doesn't work and you
want it ignored, then set this variable as shown. Its mere
existence is enough to cause <.netrc> to be ignored.
Controlling External Applications
Protocol Variable Default Value
-------- ---------------- -------------
dav: g:netrw_dav_cmd = "cadaver"
fetch: g:netrw_fetch_cmd = "fetch -o"
ftp: g:netrw_ftp_cmd = "ftp"
http: g:netrw_http_cmd = "fetch -o" else if fetch is available
http: g:netrw_http_cmd = "wget -q -O" If wget is available
rcp: g:netrw_rcp_cmd = "rcp"
rsync: g:netrw_rsync_cmd = "rsync -a"
scp: g:netrw_scp_cmd = "scp -q"
sftp: g:netrw_sftp_cmd = "sftp"
READING
:Nread ? give help
:Nread "machine:file" uses rcp
:Nread "machine file" uses ftp with <.netrc>
:Nread "machine id password file" uses ftp
:Nread "dav://machine[:port]/file" uses cadaver
:Nread "fetch://[user@]machine/file" uses fetch
:Nread "ftp://[user@]machine[[:#]port]/file" uses ftp autodetects <.netrc>
:Nread "http://[user@]machine/file" uses http uses wget
:Nread "rcp://[user@]machine/file" uses rcp
:Nread "rsync://[user@]machine[:port]/file" uses rsync
:Nread "scp://[user@]machine[[:#]port]/file" uses scp
:Nread "sftp://[user@]machine/file" uses sftp
WRITING
:Nwrite ? give help
:Nwrite "machine:file" uses rcp
:Nwrite "machine file" uses ftp with <.netrc>
:Nwrite "machine id password file" uses ftp
:Nwrite "dav://machine[:port]/file" uses cadaver
:Nwrite "ftp://[user@]machine[[:#]port]/file" uses ftp autodetects <.netrc>
:Nwrite "rcp://[user@]machine/file" uses rcp
:Nwrite "rsync://[user@]machine[:port]/file" uses rsync
:Nwrite "scp://[user@]machine[[:#]port]/file" uses scp
:Nwrite "sftp://[user@]machine/file" uses sftp
http: not supported!
USER AND PASSWORD CHANGING
Attempts to use ftp will prompt you for a user-id and a password.
These will be saved in g:netrw_uid and g:netrw_passwd Subsequent uses
of ftp will re-use those. If you need to use a different user id
and/or password, you'll want to call NetUserPass() first.
:NetUserPass [uid [password]] -- prompts as needed
:call NetUserPass() -- prompts for uid and password
:call NetUserPass("uid") -- prompts for password
:call NetUserPass("uid","password") -- sets global uid and password
VARIABLES
b:netrw_lastfile last file Network-read/written retained on
a per-buffer basis (supports plain :Nw )
s:netrw_line during Nw/NetWrite, holds current line number
s:netrw_col during Nw/NetWrite, holds current column number
s:netrw_line and s:netrw_col are used to
restore the cursor position on writes
g:netrw_ftp if it doesn't exist, use default ftp
=0 use default ftp (uid password)
=1 use alternate ftp method (user uid password)
g:netrw_ftpmode ="binary" (default)
="ascii" (or your choice)
g:netrw_uid (ftp) user-id, retained on a per-session basis
g:netrw_passwd (ftp) password, retained on a per-session basis
g:netrw_win95ftp =0 use unix-style ftp even if win95/win98/winME
=1 use default method to do ftp
g:netrw_cygwin =1 assume scp under windows is from cygwin
(default if windows)
=0 assume scp under windows accepts
windows-style paths (default otherwise)
g:netrw_use_nt_rcp=0 don't use the rcp of WinNT, Win2000 and WinXP (default)
=1 use the rcp of WinNT,... in binary mode
==============================================================================
2. Network-Oriented File Transfer *netrw-xfer*
Network-oriented file transfer under Vim is implemented by a VimL-based script
(<netrw.vim>) using plugin techniques. It currently supports both reading
and writing across networks using rcp, scp, ftp or ftp+<.netrc>, scp, fetch,
dav/cadaver, rsync, or sftp.
http is currently supported read-only via use of wget or fetch.
<netrw.vim> is a standard plugin which acts as glue between Vim and the
various file transfer programs. It uses autocommand events (BufReadCmd,
FileReadCmd, BufWriteCmd) to intercept reads/writes with url-like filenames. >
ex. vim ftp://hostname/path/to/file
<
The characters preceding the colon specify the protocol to use;
in the example, its ftp. The <netrw.vim> script then formulates
a command or a series of commands (typically ftp) which it issues
to an external program (ftp, scp, etc) which does the actual file
transfer/protocol. Files are read from/written to a temporary file
(under Unix/Linux, /tmp/...) which the <netrw.vim> script will
clean up.
One may modify any protocol's implementing external application
by setting a variable (ex. scp uses the variable g:netrw_scp_cmd,
which is defaulted to "scp -q").
Ftp, an old protocol, seems to be blessed by numerous implementations.
Unfortunately, some implementations are noisy (ie., add junk to the end
of the file). Thus, concerned users may decide to write a NetReadFixup()
function that will clean up after reading with their ftp. Some Unix systems
(ie., FreeBSD) provide a utility called "fetch" which uses the ftp protocol
but is not noisy and more convenient, actually, for <netrw.vim> to use.
Consequently, if "fetch" is executable, it will be used to do reads for
ftp://... (and http://...) . See |netrw-var| for more about this.
For rcp, scp, sftp, and http, one may use network-oriented file transfers
transparently; ie.
>
vim rcp://[user@]machine/path
vim scp://[user@]machine/path
<
If your ftp supports <.netrc>, then it too can be just as transparently used
if the needed triad of machine name, user id, and password are present in
that file. Your ftp must be able to use the <.netrc> file on its own, however.
>
vim ftp://[user@]machine[[:#]portnumber]/path
<
However, ftp will often need to query the user for the userid and password.
The latter will be done "silently"; ie. asterisks will show up instead of
the actually-typed-in password. Netrw will retain the userid and password
for subsequent read/writes from the most recent transfer so subsequent
transfers (read/write) to or from that machine will take place without
additional prompting.
*netrw-urls*
+=================================+============================+============+
| Reading | Writing | Uses |
+=================================+============================+============+
| DAV: | | |
| dav://host/path | | cadaver |
| :Nread dav://host/path | :Nwrite dav://host/path | cadaver |
+---------------------------------+----------------------------+------------+
| FETCH: | | |
| fetch://[user@]host/path | | |
| fetch://[user@]host:http/path | Not Available | fetch |
| :Nread fetch://[user@]host/path| | |
+---------------------------------+----------------------------+------------+
| FILE: | | |
| file:///* | file:///* | |
| file://localhost/* | file://localhost/* | |
+---------------------------------+----------------------------+------------+
| FTP: (*3) | (*3) | |
| ftp://[user@]host/path | ftp://[user@]host/path | ftp (*2) |
| :Nread ftp://host/path | :Nwrite ftp://host/path | ftp+.netrc |
| :Nread host path | :Nwrite host path | ftp+.netrc |
| :Nread host uid pass path | :Nwrite host uid pass path | ftp |
+---------------------------------+----------------------------+------------+
| HTTP: wget is executable: (*4) | | |
| http://[user@]host/path | Not Available | wget |
+---------------------------------+----------------------------+------------+
| HTTP: fetch is executable (*4) | | |
| http://[user@]host/path | Not Available | fetch |
+---------------------------------+----------------------------+------------+
| RCP: | | |
| rcp://[user@]host/path | rcp://[user@]host/path | rcp |
+---------------------------------+----------------------------+------------+
| RSYNC: | | |
| rsync://[user@]host/path | rsync://[user@]host/path | rsync |
| :Nread rsync://host/path | :Nwrite rsync://host/path | rsync |
| :Nread rcp://host/path | :Nwrite rcp://host/path | rcp |
+---------------------------------+----------------------------+------------+
| SCP: | | |
| scp://[user@]host/path | scp://[user@]host/path | scp |
| :Nread scp://host/path | :Nwrite scp://host/path | scp (*1) |
+---------------------------------+----------------------------+------------+
| SFTP: | | |
| sftp://[user@]host/path | sftp://[user@]host/path | sftp |
| :Nread sftp://host/path | :Nwrite sftp://host/path | sftp (*1) |
+=================================+============================+============+
(*1) For an absolute path use scp://machine//path.
(*2) if <.netrc> is present, it is assumed that it will
work with your ftp client. Otherwise the script will
prompt for user-id and password.
(*3) for ftp, "machine" may be machine#port or machine:port
if a different port is needed than the standard ftp port
(*4) for http:..., if wget is available it will be used. Otherwise,
if fetch is available it will be used.
Both the :Nread and the :Nwrite ex-commands can accept multiple filenames.
NETRC *netrw-netrc*
The typical syntax for lines in a <.netrc> file is given as shown below.
Ftp under Unix usually support <.netrc>; Windows' ftp usually doesn't.
>
machine {full machine name} login {user-id} password "{password}"
default login {user-id} password "{password}"
Your ftp client must handle the use of <.netrc> on its own, but if the
<.netrc> file exists, an ftp transfer will not ask for the user-id or
password.
Note:
Since this file contains passwords, make very sure nobody else can
read this file! Most programs will refuse to use a .netrc that is
readable for others. Don't forget that the system administrator can
still read the file!
PASSWORD *netrw-passwd*
The script attempts to get passwords for ftp invisibly using |inputsecret()|,
a built-in Vim function. See |netrw-uidpass| for how to change the password
after one has set it.
Unfortunately there doesn't appear to be a way for netrw to feed a password
to scp. Thus every transfer via scp will require re-entry of the password.
==============================================================================
3. Activation *netrw-activate*
Network-oriented file transfers are available by default whenever
|'nocompatible'| mode is enabled. The <netrw.vim> file resides in your
system's vim-plugin directory and is sourced automatically whenever you
bring up vim.
==============================================================================
4. Transparent File Transfer *netrw-transparent*
Transparent file transfers occur whenever a regular file read or write
(invoked via an |:autocmd| for |BufReadCmd| or |BufWriteCmd| events) is made.
Thus one may use files across networks as if they were local. >
vim ftp://[user@]machine/path
...
:wq
==============================================================================
5. Ex Commands *netrw-ex*
The usual read/write commands are supported. There are also a couple of
additional commands available.
:[range]Nw Write the specified lines to the current
file as specified in b:netrw_lastfile.
:[range]Nw {netfile} [{netfile}]...
Write the specified lines to the {netfile}.
:Nread
Read the specified lines into the current
buffer from the file specified in
b:netrw_lastfile.
:Nread {netfile} {netfile}...
Read the {netfile} after the current line.
*netrw-uidpass*
:call NetUserPass()
If b:netrw_uid and b:netrw_passwd don't exist,
this function query the user for them.
:call NetUserPass("userid")
This call will set the b:netrw_uid and, if
the password doesn't exist, will query the user for it.
:call NetUserPass("userid","passwd")
This call will set both the b:netrw_uid and b:netrw_passwd.
The user-id and password are used by ftp transfers. One may
effectively remove the user-id and password by using ""
strings.
==============================================================================
6. Variables and Options *netrw-options* *netrw-var*
The script <netrw.vim> uses several variables which can affect <netrw.vim>'s
behavior. These variables typically may be set in the user's <.vimrc> file:
g:netrw_uid Holds current user-id for ftp.
g:netrw_passwd Holds current password for ftp.
b:netrw_lastfile Holds latest method/machine/path.
b:netrw_line Holds current line number (during NetWrite)
b:netrw_col Holds current cursor position (during NetWrite)
g:netrw_ftp =0 use default ftp (uid password)
=1 use alternate ftp (user uid password)
(see |netrw-options|)
g:netrw_ftpmode ="binary" (default)
="ascii" (your choice)
g:netrw_ignorenetrc =1 (default)
if you have a <.netrc> file but you don't
want it used, then set this variable. Its
mere existence is enough to cause <.netrc>
to be ignored.
g:netrw_win95ftp =0 use unix-style ftp even if win95/98/ME/etc
=1 use default method to do ftp
g:netrw_cygwin =1 assume scp under windows is from cygwin
(default/windows)
=0 assume scp under windows accepts windows
style paths (default/else)
g:netrw_use_nt_rcp =0 don't use WinNT/2K/XP's rcp (default)
=1 use WinNT/2K/XP's rcp, binary mode
The script will also make use of the following variables internally, albeit
temporarily.
g:netrw_method Index indicating rcp/ftp+.netrc/ftp
g:netrw_machine Holds machine name parsed from input
g:netrw_fname Holds filename being accessed
*netrw-protocol*
>
------------------------
Protocol Control Options
------------------------
Option Type Setting Meaning ~
--------- -------- -------------- --------------------------- >
netrw_ftp variable =doesn't exist userid set by "user userid"
=0 userid set by "user userid"
=1 userid set by "userid"
NetReadFixup function =doesn't exist no change
=exists Allows user to have files
read via ftp automatically
transformed however they wish
by NetReadFixup()
g:netrw_dav_cmd variable ="cadaver"
g:netrw_fetch_cmd variable ="fetch -o"
g:netrw_ftp_cmd variable ="ftp"
g:netrw_http_cmd variable ="fetch -o" else if fetch is executable
g:netrw_http_cmd variable ="wget -O" if wget is executable
g:netrw_rcp_cmd variable ="rcp"
g:netrw_rsync_cmd variable ="rsync -a"
g:netrw_scp_cmd variable ="scp -q"
g:netrw_sftp_cmd variable ="sftp"
<
The first two options both help with certain ftp's that give trouble otherwise.
In order to best understand how to use these options if ftp is giving you
troubles, a bit of discussion follows on how netrw does ftp reads.
The g:netrw_..._cmd variables specify the external program to use handle
the associated protocol (rcp, ftp, etc), plus any options.
Netrw typically builds up lines of one of the following formats in a
temporary file:
>
IF g:netrw_ftp !exists or is not 1 IF g:netrw_ftp exists and is 1
---------------------------------- ------------------------------
open machine [port] open machine [port]
user userid password userid password
[g:netrw_ftpmode] password
get filename tempfile [g:netrw_ftpmode]
get filename tempfile
<
Netrw then executes the lines above by use of a filter:
>
:%! {g:netrw_ftp_cmd} -i [-n]
<
where
g:netrw_ftp_cmd is usually "ftp",
-i tells ftp not to be interactive
-n means don't use netrc and is used for Method #3 (ftp w/o <.netrc>)
If <.netrc> exists it will be used to avoid having to query the user for
userid and password). The transferred file is put into a temporary file.
The temporary file is then read into the main editing session window that
requested it and the temporary file deleted.
If your ftp doesn't accept the "user" command and immediately just demands
a userid, then try putting "let netrw_ftp=1" in your <.vimrc>.
*netrw-fixup*
If your ftp for whatever reason generates unwanted lines (such as AUTH
messages) you may write a NetReadFixup(tmpfile) function:
>
function! NetReadFixup(method,line1,line2)
" a:line1: first new line in current file
" a:line2: last new line in current file
if a:method == 1 "rcp
elseif a:method == 2 "ftp + <.netrc>
elseif a:method == 3 "ftp + machine,uid,password,filename
elseif a:method == 4 "scp
elseif a:method == 5 "http/wget
elseif a:method == 6 "dav/cadaver
elseif a:method == 7 "rsync
elseif a:method == 8 "fetch
elseif a:method == 9 "sftp
else " complain
endif
endfunction
>
The NetReadFixup() function will be called if it exists and thus allows
you to customize your reading process. As a further example, <netrw.vim>
contains just such a function to handle Windows 95 ftp. For whatever
reason, Windows 95's ftp dumps four blank lines at the end of a transfer,
and so it is desirable to automate their removal. Here's some code taken
from <netrw.vim> itself:
>
if has("win95") && g:netrw_win95ftp
fu! NetReadFixup(method, line1, line2)
if method == 3 " ftp (no <.netrc>)
let fourblanklines= line2 - 3
silent fourblanklines.",".line2."g/^\s*/d"
endif
endfunction
endif
>
==============================================================================
7. Debugging *netrw-debug*
The <netrw.vim> script is typically available as:
/usr/local/share/vim/vim6x/plugin/netrw.vim
which is loaded automatically at startup (assuming :set nocp).
1. Get the <Decho.vim> script, available as:
http://mysite.verizon.net/astronaut/vim/index.html#vimlinks_scripts
as "Decho, a vimL debugging aid"
or
http://vim.sourceforge.net/scripts/script.php?script_id=120
and put it into your local plugin directory
2. Edit the <netrw.vim> file as follows:
:DechoOn
(to restore to normal, use :DechoOff )
3. Then bring up vim and attempt a transfer. A set of messages
should appear concerning the steps that <netrw.vim> took in
attempting to read/write your file over the network. Please
send that information to <netrw.vim>'s maintainer,
drchipNOSPAM at campbellfamily.biz - NOSPAM
==============================================================================
8. New Stuff *netrw-new* *netrw-newstuff*
v43: * moved "Explanation" comments to <pi_netrw.txt> help file
as "Network Reference" (|netrw-ref|)
* <netrw.vim> now uses Dfunc() Decho() and Dret() for debugging
* removed superfluous NetRestorePosn() calls
v42: * now does BufReadPre and BufReadPost events on file:///*
and file://localhost/*
v41: * installed file:///* and file://localhost/* handling
v40: * prevents redraw when a protocol error occurs so that the
user may see it
v39: * sftp support
v38: * Now uses NetRestorePosn() calls with Nread/Nwrite commands
* Temporary files now removed via bwipe! instead of bwipe
(thanks to Dave Roberts)
v37: * Claar's modifications which test if ftp is successful, otherwise
give an error message
* After a read, the alternate file was pointing to the temp file.
The temp file buffer is now wiped out.
* removed silent from transfer methods so user can see what's
happening
==============================================================================
9. Credits *netrw-credits*
Vim editor by Bram Moolenaar (Thanks, Bram!)
dav support by C Campbell
fetch support by Bram Moolenaar and C Campbell
ftp support by C Campbell <NdrOchip@ScampbellPfamily.AbizM> - NOSPAM
http support by Bram Moolenaar <bram@moolenaar.net>
rcp
rsync support by C Campbell (suggested by Erik Warendorph)
scp support by raf <raf@comdyn.com.au>
sftp support by C Campbell
inputsecret(), BufReadCmd, BufWriteCmd contributed by C Campbell
Jérôme Augé -- also using new buffer method with ftp+.netrc
Bram Moolenaar -- obviously vim itself, :e and v:cmdarg use, fetch,...
Yasuhiro Matsumoto -- pointing out undo+0r problem and a solution
Erik Warendorph -- for several suggestions (g:netrw_..._cmd
variables, rsync etc)
Doug Claar -- modifications to test for success with ftp operation
==============================================================================
vim:tw=78:ts=8:ft=help:norl:

111
runtime/doc/pi_spec.txt Normal file
View File

@@ -0,0 +1,111 @@
*pi_spec.txt* For Vim version 7.0aa. Last change: 2002 Oct 29
by Gustavo Niemeyer ~
This is a filetype plugin to work with rpm spec files.
Currently, this Vim plugin allows you to easily update the %changelog
section in RPM spec files. It will even create a section for you if it
doesn't exist yet. If you've already inserted an entry today, it will
give you the opportunity to just add a new item in today's entry. If you
don't provide a format string (|spec_chglog_format|), it'll ask you an
email address and build a format string by itself.
1. How to use it |spec-how-to-use-it|
2. Customizing |spec-customizing|
==============================================================================
1. How to use it *spec-how-to-use-it*
The spec_chglog plugin provides a map like the following:
:map <buffer> <LocalLeader>c <Plug>SpecChangelog
It means that you may run the plugin inside a spec file by pressing
your maplocalleader key (default is '\') plus 'c'. If you do not have
|spec_chglog_format| set, the plugin will ask you for an email address
to use in this edit session.
Everytime you run the plugin, it will check to see if the last entry
in the changelog has been written today and by you. If it's the entry
mathes, it will just insert a new changelog item, otherwise it will
create a new changelog entry. If you are running with
|spec_chglog_release_info| enabled, it will also check if the name, version
and release matches. The plugin is smart enough to ask you if it should
update the package release, if you have not done so.
Setting a map *spec-setting-a-map*
-------------
As you should know, you can easily set a map to access any Vim command (or
anything, for that matter). If you don't like the default map of
<LocalLeader>c, you may just set up your own key. The following line
shows you how you could do this in your .vimrc file, mapping the plugin to
the <F5> key:
au FileType spec map <buffer> <F5> <Plug>SpecChangelog
Note: the plugin will respect your desire to change the default mapping
and won't set it.
This command will add a map only in the spec file buffers.
==============================================================================
2. Customizing *spec-customizing*
The format string *spec_chglog_format*
-----------------
You can easily customize how your spec file entry will look like. To do
this just set the variable "spec_chglog_format" in your .vimrc file like
this: >
let spec_chglog_format = "%a %b %d %Y My Name <my@email.com>"
Note that "%a %b %d %Y" is the most used time format. If you don't provide
a format string, when you run the SpecChangelog command for the first
time, it will ask you an email address and build the |spec_chglog_format|
variable for you. This way, you will only need to provide your email
address once.
To discover which format options you can use, take a look at the strftime()
function man page.
Where to insert new items *spec_chglog_prepend*
-------------------------
The plugin will usually insert new %changelog entry items (note that it's
not the entry itself) after the existing ones. If you set the
spec_chglog_prepend variable >
let spec_chglog_prepend = 1
it will insert new items before the existing ones.
Inserting release info *spec_chglog_release_info*
----------------------
If you want, the plugin may automatically insert release information
on each changelog entry. One advantage of turning this feature on is
that it may control if the release has been updated after the last
change in the package or not. If you have not updated the package
version or release, it will ask you if it should update the package
release for you. To turn this feature on, just insert the following
code in your .vimrc: >
let spec_chglog_release_info = 1
Then, the first item in your changelog entry will be something like: >
+ name-1.0-1cl
If you don't like the release updating feature and don't want to answer
"No" each time it detects an old release, you may disable it with >
let spec_chglog_never_increase_release = 1
Good luck!!
vim:tw=78:ts=8:ft=help:norl:

1010
runtime/doc/quickfix.txt Normal file
View File

File diff suppressed because it is too large Load Diff

1325
runtime/doc/quickref.txt Normal file
View File

File diff suppressed because it is too large Load Diff

274
runtime/doc/quotes.txt Normal file
View File

@@ -0,0 +1,274 @@
*quotes.txt* For Vim version 7.0aa. Last change: 2004 May 06
VIM REFERENCE MANUAL by Bram Moolenaar
*quotes*
Here are some nice quotes about Vim that I collected from news and mail.
vim (vim) noun - Ebullient vitality and energy. [Latin, accusative of vis,
strength] (Dictionary)
Vim is so much better than vi that a great many of my old vi :map's became
immediately obsolete! (Tony Nugent, Australia)
Coming with a very GUI mindset from Windows, I always thought of people using
Vi as some kind of outer space alien in human clothes. Once I tried I really
got addicted by its power and now I found myself typing Vim keypresses in the
oddest places! That's why I would like to see Vim embedded in every
application which deals with text editing. (José Fonseca)
I was a 12-year emacs user who switched to Vim about a year ago after finally
giving up on the multiple incompatible versions, flaky contributed packages,
disorganized keystrokes, etc. And it was one of the best moves I ever made.
(Joel Burton)
Although all of the programs were used during the preparation of the new and
revised material, most of the editing was done with Vim versions 4.5 and 5.0
under GNU-Linux (Redhat 4.2). (Arnold Robbins, Israel, author of "Learning
the Vi editor")
Out of all the open software i've ever seen and used, and i've seen a lot, Vim
is the best, most useful and highest quality to work with, second only to the
linux kernel itself. (Peter Jay Salzman)
It's well worth noting that the _entirety_ of SourceForge was written using
Vim and its nifty PHP syntax highlighting. I think the entire SF.net tech
staff uses Vim and we're all excited to have you aboard! (Tim Perdue)
Vim is one of a select bunch of tools for which I have no substitute. It is
a brilliant piece of work! (Biju Chacko)
A previous girlfriend of mine switched to emacs. Needless to say, the
relationship went nowhere. (Geoffrey Mann)
I rarely think about Vim, in the same way that I guess a fish rarely thinks
about water. It's the environment in which everything else happens. I'm a
fairly busy system administrator working on a lot of different platforms. Vim
is the only thing that's consistent across all my systems, and it's just about
the only thing that doesn't break from time to time. When a new system comes
in the door without Vim, I install it right away. Great to have a tool that's
the same everywhere, that's completely reliable, so I can ignore it and think
about other things. (Pete Schaeffer)
Having recently succeeded in running Vim via telnet through a Nokia
Communicator, I can now report that it works nicely on a Palm Pilot too.
(Allan Kelly, Scotland)
You've done a tremendous job with 'VIM', Bram! The more I use it, the more
impressed I get (I am an old 'vi' die hard who once started out with early
versions of 'emacs' in the late 1970's and was relieved by finding 'vi' in the
first UNIX I came across in 1983). In my opinion, it's about time 'VIM'
replace 'emacs' as the standard for top editors. (Bo Thide', Sweden)
I love and use VIM heavily too. (Larry Wall)
Vi is like a Ferrari, if you're a beginner, it handles like a bitch, but once
you get the hang of it, its small, powerful and FAST! (Unknown)
VIM is like a new model Ferrari, and sounds like one too - "VIIIIIIMMM!"
(Stephen Riehm, Germany)
Schon bei Nutzung eines Bruchteils der VIM-Funktionen wird der Benutzer recht
schnell die Vorzuege dieses Editors kennen- und schaetzenlernen.
Translated: Even when only using a fraction of VIM-functions, the user will
quickly get used to and appreciate the advantages of this editor. (Garry
Glendown, conclusion of an article on VIM in iX magazine 9/1998)
I've recently acquired the O'Reilly book on VI (it also discusses VIM
in-depth), and I'm amazed at just how powerful this application is. (Jeffrey
Rankin)
This guide was written using the Windows 9.x distribution of GVIM, which is
quite possibly the greatest thing to come along since God created the naked
girl. (Michael DiBernardo)
Boy, I thought I knew almost everything about VIM, but every time I browse the
online documentation, I hit upon a minor but cool aspect of a VIM feature that
I didn't know before! I must say the documentation is one the finest I've
ever seen in a product -- even better than most commercial products.
(Gautam Mudunuri)
VIM 4.5 is really a fantastic editor. It has sooooo many features and more
importantly, the defaults are so well thought out that you really don't have
to change anything!! Words cannot express my amazement and gratitude to the
creators of VIM. Keep it up. (Vikas, USA)
I wonder how long it will be before people will refer to other Vi editors as
VIM clones? (Darren Hiebert)
I read about [auto-positioning-in-file-based-on-the-errors-from-make] in one
of those "Perfect Programmer's Editor" threads and was delighted to discover
that VIM already supports it. (Brendan Macmillan, Australia)
I just discovered VIM (5.0) and I'm telling everyone I know about it!
I tell them VIM stands for VI for the new (M)illenium. Thanks so much!
(Matt F. Valentine)
I think from now on "vi" should be called "Vim Imitation", not the other way
around. (Rungun Ramanathan)
The Law of VIM:
For each member b of the possible behaviour space B of program P, there exists
a finite time t before which at least one user u in the total user space U of
program P will request b becomes a member of the allowed behaviour space B'
(B' <= B).
In other words: Sooner or later everyone wants everything as an option.
(Negri)
Whenever I move to a new computing platform, the first thing I do is to port
VIM. Lately, I am simply stunned by its ease of compilation using the
configure facility. (A.M. Sabuncu, Turkey)
The options are really excellent and very powerful. (Anish Maharaj)
The Spring user-interface designs are in, and word from the boutiques is that
80x24 text-only mode is back with a *vengeance! Vi editor clone VIM burst onto
March desk-tops with a dazzling show of pastel syntax highlights for its 5.0
look. Strident and customizable, VIM raises eyebrows with its interpretation
of the classic Vi single-key macro collection.
http://www.ntk.net/index.cgi?back=archive98/now0327.txt&line=179#l
I just wanted to take this opportunity to let you know that VIM 5 ROCKS!
Syntax highlighting: how did I survive without it?! Thank you for creating
mankind's best editor! (Mun Johl, USA)
Thanks again for VIM. I use it every day on Linux. (Eric Foster-Johnson,
author of the book "UNIX Programming Tools")
The BEST EDITOR EVER (Stuart Woolford)
I have used most of VIM's fancy features at least once, many frequently, and I
can honestly say that I couldn't live with anything less anymore. My
productivity has easily doubled compared to what it was when I used vi.
(Sitaram Chamarty)
I luv VIM. It is incredible. I'm naming my first-born Vimberly. (Jose
Unpingco, USA)
Hint: "VIM" is "vi improved" - much better! (Sven Guckes, Germany)
I use VIM every day. I spend more time in VIM than in any other program...
It's the best vi clone there is. I think it's great. (Craig Sanders,
Australia)
I strongly advise using VIM--its infinite undo/redo saved me much grief.
(Terry Brown)
Thanks very much for writing what in my opinion is the finest text editor on
the planet. If I were to get another cat, I would name it "Vim".
(Bob Sheehan, USA)
I typed :set all and the screen FILLED up with options. A whole screen of
things to be set and unset. I saw some of my old friends like wrapmargin,
modelines and showmode, but the screen was FILLED with new friends! I love
them all! I love VIM! I'm so happy that I've found this editor! I feel
like how I once felt when I started using vi after a couple of years of using
ed. I never thought I'd forsake my beloved ed, but vi ... oh god, vi was
great. And now, VIM. (Peter Jay Salzman, USA)
I am really happy with such a wonderful software package. Much better than
almost any expensive, off the shelf program. (Jeff Walker)
Whenever I reread the VIM documentation I'm overcome with excitement at the
power of the editor. (William Edward Webber, Australia)
Hurrah for VIM!! It is "at your fingertips" like vi, and has the extensions
that vi sorely needs: highlighting for executing commands on blocks, an easily
navigable and digestible help screen, and more. (Paul Pax)
The reason WHY I don't have this amazingly useful macro any more, is that I
now use VIM - and this is built in!! (Stephen Riehm, Germany)
I am a user of VIM and I love it. I use it to do all my programming, C,
C++, HTML what ever. (Tim Allwine)
I discovered VIM after years of struggling with the original vi, and I just
can't live without it any more. (Emmanuel Mogenet, USA)
Emacs has not a bit of chance to survive so long as VIM is around. Besides,
it also has the most detailed software documentation I have ever seen---much
better than most commercial software! (Leiming Qian)
This version of VIM will just blow people apart when they discover just how
fantastic it is! (Tony Nugent, Australia)
I took your advice & finally got VIM & I'm really impressed. Instant convert.
(Patrick Killelea, USA)
VIM is by far my favorite piece of shareware and I have been particularly
pleased with version 3.0. This is really a solid piece of work. (Robert
Colon, USA)
VIM is a joy to use, it is so well thought and practical that I wonder why
anybody would use visual development tools. VIM is powerful and elegant, it
looks deceptively simple but is almost as complex as a 747 (especially when I
look at my growing .vimrc), keep up that wonderful job, VIM is a centerpiece
of the free software world. (Louis-David Mitterand, USA)
I cannot believe how great it is to use VIM. I think the guys at work are
getting tired of hearing me bragging about it. Others eyes are lighting up.
(Rick Croote)
Emacs takes way to much time to start up and run, it is to big and bulky for
effective use and the interface is more confusing than it is of any help. VIM
however is short, it is fast, it is powerful, it has a good interface and it
is all purpose. (Paal Ditlefsen Ekran)
From the first time I got VIM3.0, I was very enthusiastic. It has almost no
problems. The swapfile handling and the backup possibilities are robust, also
the protection against editing one file twice. It is very compatible to the
real VI (and that is a MUST, because my brain is trained over years in using
it). (Gert van Antwerpen, Holland)
Visual mode in VIM is a very powerful thing! (Tony Nugent, Australia)
I have to say that VIM is =THE= single greatest piece of source code to ever
come across the net (Jim Battle, USA).
In fact, if you do want to get a new vi I'd suggest VIM-3.0. This is, by
far, the best version of vi I've ever seen (Albert W. Schueller).
I should mention that VIM is a very good editor and can compete with anything
(Ilya Beloozerov).
To tell the truth sometimes I used elvis, vile, xvi, calvin, etc. And this is
the reason that I can state that VIM is the best! (Ferenc Deak, Hungary)
VIM is by far the best editor that I have used in a long time, and I have
looked at just about every thing that is available for every platform that I
use. VIM is the best on all of them. (Guy L. Oliver)
VIM is the greatest editor since the stone chisel. (Jose Unpingco, USA)
I would like to say that with VIM I am finally making the 'emacs to vi'
transition - as an Editor it is so much better in many ways: keyboard layout,
memory usage, text alteration to name 3. (Mark Adam)
In fact, now if I want to know what a particular setting does in vi, I fire up
VIM and check out it's help! (Nikhil Patel, USA)
As a vi user, VIM has made working with text a far more pleasant task than
before I encountered this program. (Steinar Knutsen, Norway)
I use VIM since version 3.0. Since that time, it is the ONLY editor I use,
with Solaris, Linux and OS/2 Warp. I suggest all my friends to use VIM, they
try, and they continue using it. VIM is really the best software I have ever
downloaded from the Internet, and the best editor I know of. (Marco
Eccettuato, Italy)
In summary:
__ ___ _ _ _ ___ _____
\ \ / (_)_ __ ___ (_)___ | | | |/ _ \_ _|
\ \ / /| | '_ ` _ \ | / __| | |_| | | | || |
\ V / | | | | | | | | \__ \ | _ | |_| || |
\_/ |_|_| |_| |_| |_|___/ |_| |_|\___/ |_|
____ _____ _ _ _____ _____ _ _
/ ___|_ _| | | | ___| ___| | |
\___ \ | | | | | | |_ | |_ | | |
___) || | | |_| | _| | _| |_|_|
|____/ |_| \___/|_| |_| (_|_) (Tony Nugent, Australia)
vim:tw=78:ts=8:ft=help:norl:

165
runtime/doc/recover.txt Normal file
View File

@@ -0,0 +1,165 @@
*recover.txt* For Vim version 7.0aa. Last change: 2004 Apr 16
VIM REFERENCE MANUAL by Bram Moolenaar
Recovery after a crash *crash-recovery*
You have spent several hours typing in that text that has to be finished
next morning, and then disaster strikes: Your computer crashes.
DON'T PANIC!
You can recover most of your changes from the files that Vim uses to store
the contents of the file. Mostly you can recover your work with one command:
vim -r filename
1. The swap file |swap-file|
2. Recovery |recovery|
==============================================================================
1. The swap file *swap-file*
Vim stores the things you changed in a swap file. Using the original file
you started from plus the swap file you can mostly recover your work.
You can see the name of the current swap file being used with the command:
:sw[apname] *:sw* *:swapname*
The name of the swap file is normally the same as the file you are editing,
with the extension ".swp".
- On Unix, a '.' is prepended to swap file names in the same directory as the
edited file. This avoids that the swap file shows up in a directory
listing.
- On MS-DOS machines and when the 'shortname' option is on, any '.' in the
original file name is replaced with '_'.
- If this file already exists (e.g., when you are recovering from a crash) a
warning is given and another extension is used, ".swo", ".swn", etc.
- An existing file will never be overwritten.
- The swap file is deleted as soon as Vim stops editing the file.
Technical: The replacement of '.' with '_' is done to avoid problems with
MS-DOS compatible filesystems (e.g., crossdos, multidos). If Vim
is able to detect that the file is on an MS-DOS-like filesystem, a
flag is set that has the same effect as the 'shortname' option.
This flag is reset when you start editing another file.
*E326*
If the ".swp" file name already exists, the last character is
decremented until there is no file with that name or ".saa" is
reached. In the last case, no swap file is created.
By setting the 'directory' option you can place the swap file in another place
than where the edited file is.
Advantages:
- You will not pollute the directories with ".swp" files.
- When the 'directory' is on another partition, reduce the risk of damaging
the file system where the file is (in a crash).
Disadvantages:
- You can get name collisions from files with the same name but in different
directories (although Vim tries to avoid that by comparing the path name).
This will result in bogus ATTENTION warning messages.
- When you use your home directory, and somebody else tries to edit the same
file, he will not see your swap file and will not get the ATTENTION waring
message.
On the Amiga you can also use a recoverable ram disk, but there is no 100%
guarantee that this works. Putting swap files in a normal ram disk (like RAM:
on the Amiga) or in a place that is cleared when rebooting (like /tmp on Unix)
makes no sense, you will lose the swap file in a crash.
If you want to put swap files in a fixed place, put a command resembling the
following ones in your .vimrc:
:set dir=dh2:tmp (for Amiga)
:set dir=~/tmp (for Unix)
:set dir=c:\\tmp (for MS-DOS and Win32)
This is also very handy when editing files on floppy. Of course you will have
to create that "tmp" directory for this to work!
For read-only files, a swap file is not used. Unless the file is big, causing
the amount of memory used to be higher than given with 'maxmem' or
'maxmemtot'. And when making a change to a read-only file, the swap file is
created anyway.
The 'swapfile' option can be reset to avoid creating a swapfile.
Detecting an existing swap file ~
You can find this in the user manual, section |11.3|.
Updating the swapfile ~
The swap file is updated after typing 200 characters or when you have not
typed anything for four seconds. This only happens if the buffer was
changed, not when you only moved around. The reason why it is not kept up to
date all the time is that this would slow down normal work too much. You can
change the 200 character count with the 'updatecount' option. You can set
the time with the 'updatetime' option. The time is given in milliseconds.
After writing to the swap file Vim syncs the file to disk. This takes some
time, especially on busy Unix systems. If you don't want this you can set the
'swapsync' option to an empty string. The risk of losing work becomes bigger
though. On some non-Unix systems (MS-DOS, Amiga) the swap file won't be
written at all.
If the writing to the swap file is not wanted, it can be switched off by
setting the 'updatecount' option to 0. The same is done when starting Vim
with the "-n" option. Writing can be switched back on by setting the
'updatecount' option to non-zero. Swap files will be created for all buffers
when doing this. But when setting 'updatecount' to zero, the existing swap
files will not be removed, it will only affect files that will be opened
after this.
If you want to make sure that your changes are in the swap file use this
command:
*:pre* *:preserve* *E313* *E314*
:pre[serve] Write all text for all buffers into swap file. The
original file is no longer needed for recovery. {Vi:
emergency exit}
A Vim swap file can be recognized by the first six characters: "b0VIM ".
After that comes the version number, e.g., "3.0".
==============================================================================
2. Recovery *recovery* *E308* *E311*
Basic file recovery is explained in the user manual: |usr_11.txt|.
Another way to do recovery is to start Vim and use the ":recover" command.
This is easy when you start Vim to edit a file and you get the "ATTENTION:
Found a swap file ..." message. In this case the single command ":recover"
will do the work. You can also give the name of the file or the swap file to
the recover command:
*:rec* *:recover* *E305* *E306* *E307*
:rec[over] [file] Try to recover [file] from the swap file. If [file]
is not given use the file name for the current
buffer. The current contents of the buffer are lost.
This command fails if the buffer was modified.
:rec[over]! [file] Like ":recover", but any changes in the current
buffer are lost.
*E312* *E309* *E310*
Vim has some intelligence about what to do if the swap file is corrupt in
some way. If Vim has doubt about what it found, it will give an error
message and insert lines with "???" in the text. If you see an error message
while recovering, search in the file for "???" to see what is wrong. You may
want to cut and paste to get the text you need.
The most common remark is "???LINES MISSING". This means that Vim cannot read
the text from the original file. This can happen if the system crashed and
parts of the original file were not written to disk.
Be sure that the recovery was successful before overwriting the original
file or deleting the swap file. It is good practice to write the recovered
file elsewhere and run 'diff' to find out if the changes you want are in the
recovered file.
Once you are sure the recovery is ok delete the swap file. Otherwise, you
will continue to get warning messages that the ".swp" file already exists.
{Vi: recovers in another way and sends mail if there is something to recover}
vim:tw=78:ts=8:ft=help:norl:

188
runtime/doc/remote.txt Normal file
View File

@@ -0,0 +1,188 @@
*remote.txt* For Vim version 7.0aa. Last change: 2003 Nov 10
VIM REFERENCE MANUAL by Bram Moolenaar
Vim client-server communication *client-server*
1. Common functionality |clientserver|
2. X11 specific items |x11-clientserver|
3. MS-Windows specific items |w32-clientserver|
{Vi does not have any of these commands}
==============================================================================
1. Common functionality *clientserver*
When compiled with the |+clientserver| option, Vim can act as a command
server. It accepts messages from a client and executes them. At the same
time, Vim can function as a client and send commands to a Vim server.
The following command line arguments are available:
argument meaning ~
--remote [+{cmd}] {file} ... *--remote*
Open the file list in a remote Vim. When
there is no Vim server, execute locally.
There is one optional init command: +{cmd}.
This must be an Ex command that can be
followed by "|".
The rest of the command line is taken as the
file list. Thus any non-file arguments must
come before this.
You cannot edit stdin this way |--|.
The remote Vim is raised. If you don't want
this use >
vim --remote-send "<C-\><C-N>:n filename<CR>"
< --remote-silent [+{cmd}] {file} ... *--remote-silent*
As above, but don't complain if there is no
server and the file is edited locally.
--remote-wait [+{cmd}] {file} ... *--remote-wait*
As --remote, but wait for files to complete
(unload) in remote Vim.
--remote-wait-silent [+{cmd}] {file} ... *--remote-wait-silent*
As --remote-wait, but don't complain if there
is no server.
*--servername*
--servername {name} Become the server {name}. When used together
with one of the --remote commands: connect to
server {name} instead of the default (see
below).
*--remote-send*
--remote-send {keys} Send {keys} to server and exit.
*--remote-expr*
--remote-expr {expr} Evaluate {expr} in server and
print the result on stdout.
*--serverlist*
--serverlist Output a list of server names.
Examples ~
Edit "file.txt" in an already running GVIM server: >
gvim --remote file.txt
Edit "file.txt" in an already running server called FOOBAR: >
gvim --servername FOOBAR --remote file.txt
Edit "file.txt" in server "FILES" if it exists, become server "FILES"
otherwise: >
gvim --servername FILES --remote-silent file.txt
This doesn't work, all arguments after --remote will be used as file names: >
gvim --remote --servername FOOBAR file.txt
Edit file "+foo" in a remote server (note the use of "./" to avoid the special
meaning of the leading plus): >
vim --remote ./+foo
Tell the remote server "BLA" to write all files and exit: >
vim --servername BLA --remote-send '<C-\><C-N>:wqa<CR>'
SERVER NAME
By default Vim will try to register the name under which it was invoked (gvim,
egvim ...). This can be overridden with the --servername argument. If the
specified name is not available, a postfix is applied until a free name is
encountered, ie. "gvim1" for the second invocation of gvim on a particular
X-server. The resulting name is available in the servername builtin variable
|v:servername|. The case of the server name is ignored, thus "gvim" and
"GVIM" are considered equal.
When Vim is invoked with --remote, --remote-wait or --remote-send it will try
to locate the server name determined by the invocation name and --servername
argument as described above. If an exact match is not available, the first
server with the number postfix will be used. If a name with the number
postfix is specified with the --servername argument, it must match exactly.
If no server can be located and --remote or --remote-wait was used, Vim will
start up according to the rest of the command line and do the editing by
itself. This way it is not necessary to know whether gvim is already started
when sending command to it.
The --serverlist argument will cause Vim to print a list of registered command
servers on the standard output (stdout) and exit.
Win32 Note: Making the Vim server go to the foreground doesn't always work,
because MS-Windows doesn't allow it. The client will move the server to the
foreground when using the --remote or --remote-wait argument and the server
name starts with "g".
REMOTE EDITING
The --remote argument will cause a |:drop| command to be constructed from the
rest of the command line and sent as described above.
The --remote-wait argument does the same thing and additionally sets up to
wait for each of the files to have been edited. This uses the BufUnload
event, thus as soon as a file has been unloaded, Vim assumes you are done
editing it.
Note that the --remote and --remote-wait arguments will consume the rest of
the command line. Ie. all remaining arguments will be regarded as filenames.
You can not put options there!
FUNCTIONS
*E240* *E573*
There are a number of Vim functions for scripting the command server. See
the description in |eval.txt| or use CTRL-] on the function name to jump to
the full explanation.
synopsis explanation ~
remote_expr( server, string, idvar) send expression
remote_send( server, string, idvar) send key sequence
serverlist() get a list of available servers
remote_peek( serverid, retvar) check for reply string
remote_read( serverid) read reply string
server2client( serverid, string) send reply string
remote_foreground( server) bring server to the front
See also the explanation of |CTRL-\_CTRL-N|. Very useful as a leading key
sequence.
The {serverid} for server2client() can be obtained with expand("<client>")
==============================================================================
2. X11 specific items *x11-clientserver*
*E247* *E248* *E251* *E258* *E277*
The communication between client and server goes through the X server. The
display of the Vim server must be specified. The usual protection of the X
server is used, you must be able to open a window on the X server for the
communication to work. It is possible to communicate between different
systems.
By default, a GUI Vim will register a name on the X-server by which it can be
addressed for subsequent execution of injected strings. Vim can also act as
a client and send strings to other instances of Vim on the same X11 display.
When an X11 GUI Vim (gvim) is started, it will try to register a send-server
name on the 'VimRegistry' property on the root window.
A non GUI Vim with access to the X11 display (|xterm-clipboard| enabled), can
also act as a command server if a server name is explicitly given with the
--servername argument.
An empty --servername argument will cause the command server to be disabled.
To send commands to a Vim server from another application, read the source
file src/if_xcmdsrv.c, it contains some hints about the protocol used.
==============================================================================
3. Win32 specific items *w32-clientserver*
Every Win32 Vim can work as a server, also in the console. You do not need a
version compiled with OLE. Windows messages are used, this works on any
version of MS-Windows. But only communication within one system is possible.
Since MS-Windows messages are used, any other application should be able to
communicate with a Vim server. An alternative is using the OLE functionality
|ole-interface|.
When using gvim, the --remote-wait only works properly this way: >
start /w gvim --remote-wait file.txt
<
vim:tw=78:sw=4:ts=8:ft=help:norl:

529
runtime/doc/repeat.txt Normal file
View File

@@ -0,0 +1,529 @@
*repeat.txt* For Vim version 7.0aa. Last change: 2004 Apr 02
VIM REFERENCE MANUAL by Bram Moolenaar
Repeating commands, Vim scripts and debugging *repeating*
Chapter 26 of the user manual introduces repeating |usr_26.txt|.
1. Single repeats |single-repeat|
2. Multiple repeats |multi-repeat|
3. Complex repeats |complex-repeat|
4. Using Vim scripts |using-scripts|
5. Debugging scripts |debug-scripts|
==============================================================================
1. Single repeats *single-repeat*
*.*
. Repeat last change, with count replaced with [count].
Also repeat a yank command, when the 'y' flag is
included in 'cpoptions'.
Simple changes can be repeated with the "." command. Without a count, the
count of the last change is used. If you enter a count, it will replace the
last one. If the last change included a specification of a numbered register,
the register number will be incremented. See |redo-register| for an example
how to use this. Note that when repeating a command that used a Visual
selection, the same SIZE of area is used, see |visual-repeat|.
*@:*
@: Repeat last command-line [count] times.
{not available when compiled without the
|+cmdline_hist| feature}
==============================================================================
2. Multiple repeats *multi-repeat*
*:g* *:global* *E147* *E148*
:[range]g[lobal]/{pattern}/[cmd]
Execute the Ex command [cmd] (default ":p") on the
lines within [range] where {pattern} matches.
:[range]g[lobal]!/{pattern}/[cmd]
Execute the Ex command [cmd] (default ":p") on the
lines within [range] where {pattern} does NOT match.
*:v* *:vglobal*
:[range]v[global]/{pattern}/[cmd]
Same as :g!.
The global commands work by first scanning through the [range] lines and
marking each line where a match occurs (for a multi-line pattern, only the
start of the match matters).
In a second scan the [cmd] is executed for each marked line with its line
number prepended. For ":v" and ":g!" the command is executed for each not
marked line. If a line is deleted its mark disappears.
The default for [range] is the whole buffer (1,$). Use "CTRL-C" to interrupt
the command. If an error message is given for a line, the command for that
line is aborted and the global command continues with the next marked or
unmarked line.
To repeat a non-Ex command, you can use the ":normal" command: >
:g/pat/normal {commands}
Make sure that {commands} ends with a whole command, otherwise Vim will wait
for you to type the rest of the command for each match. The screen will not
have been updated, so you don't know what you are doing. See |:normal|.
The undo/redo command will undo/redo the whole global command at once.
The previous context mark will only be set once (with "''" you go back to
where the cursor was before the global command).
The global command sets both the last used search pattern and the last used
substitute pattern (this is vi compatible). This makes it easy to globally
replace a string:
:g/pat/s//PAT/g
This replaces all occurrences of "pat" with "PAT". The same can be done with:
:%s/pat/PAT/g
Which is two characters shorter!
==============================================================================
3. Complex repeats *complex-repeat*
*q* *recording*
q{0-9a-zA-Z"} Record typed characters into register {0-9a-zA-Z"}
(uppercase to append). The 'q' command is disabled
while executing a register, and it doesn't work inside
a mapping. {Vi: no recording}
q Stops recording. (Implementation note: The 'q' that
stops recording is not stored in the register, unless
it was the result of a mapping) {Vi: no recording}
*@*
@{0-9a-z".=*} Execute the contents of register {0-9a-z".=*} [count]
times. Note that register '%' (name of the current
file) and '#' (name of the alternate file) cannot be
used. For "@=" you are prompted to enter an
expression. The result of the expression is then
executed. See also |@:|. {Vi: only named registers}
*@@*
@@ Repeat the previous @{0-9a-z":*} [count] times.
:[addr]*{0-9a-z".=} *:@* *:star*
:[addr]@{0-9a-z".=*} Execute the contents of register {0-9a-z".=*} as an Ex
command. First set cursor at line [addr] (default is
current line). When the last line in the register does
not have a <CR> it will be added automatically when
the 'e' flag is present in 'cpoptions'.
Note that the ":*" command is only recognized when the
'*' flag is present in 'cpoptions'. This is NOT the
default when 'nocompatible' is used.
For ":@=" the last used expression is used. The
result of evaluating the expression is executed as an
Ex command.
Mappings are not recognized in these commands.
{Vi: only in some versions} Future: Will execute the
register for each line in the address range.
*:@:*
:[addr]@: Repeat last command-line. First set cursor at line
[addr] (default is current line). {not in Vi}
*:@@*
:[addr]@@ Repeat the previous :@{0-9a-z"}. First set cursor at
line [addr] (default is current line). {Vi: only in
some versions}
==============================================================================
4. Using Vim scripts *using-scripts*
For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|.
*:so* *:source* *load-vim-script*
:so[urce] {file} Read Ex commands from {file}. These are commands that
start with a ":".
:so[urce]! {file} Read Vim commands from {file}. These are commands
that are executed from Normal mode, like you type
them.
When used after |:global|, |:argdo|, |:windo|,
|:bufdo|, in a loop or when another command follows
the display won't be updated while executing the
commands.
{not in Vi}
*:ru* *:runtime*
:ru[ntime][!] {file} ..
Read Ex commands from {file} in each directory given
by 'runtimepath'. There is no error for non-existing
files. Example: >
:runtime syntax/c.vim
< There can be multiple {file} arguments, separated by
spaces. Each {file} is searched for in the first
directory from 'runtimepath', then in the second
directory, etc. Use a backslash to include a space
inside {file} (although it's better not to use spaces
in file names, it causes trouble).
When [!] is included, all found files are sourced.
When it is not included only the first found file is
sourced.
When {file} contains wildcards it is expanded to all
matching files. Example: >
:runtime! plugin/*.vim
< This is what Vim uses to load the plugin files when
starting up. This similar command: >
:runtime plugin/*.vim
< would source the first file only.
When 'verbose' is one or higher, there is a message
when no file could be found.
When 'verbose' is two or higher, there is a message
about each searched file.
{not in Vi}
:scripte[ncoding] [encoding] *:scripte* *:scriptencoding* *E167*
Specify the character encoding used in the script.
The following lines will be converted from [encoding]
to the value of the 'encoding' option, if they are
different. Examples: >
scriptencoding iso-8859-5
scriptencoding cp932
<
When [encoding] is empty, no conversion is done. This
can be used to restrict conversion to a sequence of
lines: >
scriptencoding euc-jp
... lines to be converted ...
scriptencoding
... not converted ...
< When conversion isn't supported by the system, there
is no error message and no conversion is done.
Don't use "ucs-2" or "ucs-4", scripts cannot be in
these encodings (they would contain NUL bytes).
When a sourced script starts with a BOM (Byte Order
Mark) in utf-8 format Vim will recognized it, no need
to use ":scriptencoding utf-8" then.
When compiled without the |+multi_byte| feature this
command is ignored.
{not in Vi}
*:scrip* *:scriptnames*
:scrip[tnames] List all sourced script names, in the order they were
first sourced. The number is used for the script ID
|<SID>|.
{not in Vi} {not available when compiled without the
|+eval| feature}
*:fini* *:finish* *E168*
:fini[sh] Stop sourcing a script. Can only be used in a Vim
script file. This is a quick way to skip the rest of
the file. If it is used after a |:try| but before the
matching |:finally| (if present), the commands
following the ":finally" up to the matching |:endtry|
are executed first. This process applies to all
nested ":try"s in the script. The outermost ":endtry"
then stops sourcing the script. {not in Vi}
All commands and command sequences can be repeated by putting them in a named
register and then executing it. There are two ways to get the commands in the
register:
- Use the record command "q". You type the commands once, and while they are
being executed they are stored in a register. Easy, because you can see
what you are doing. If you make a mistake, "p"ut the register into the
file, edit the command sequence, and then delete it into the register
again. You can continue recording by appending to the register (use an
uppercase letter).
- Delete or yank the command sequence into the register.
Often used command sequences can be put under a function key with the ':map'
command.
An alternative is to put the commands in a file, and execute them with the
':source!' command. Useful for long command sequences. Can be combined with
the ':map' command to put complicated commands under a function key.
The ':source' command reads Ex commands from a file line by line. You will
have to type any needed keyboard input. The ':source!' command reads from a
script file character by character, interpreting each character as if you
typed it.
Example: When you give the ":!ls" command you get the |hit-enter| prompt. If
you ':source' a file with the line "!ls" in it, you will have to type the
<Enter> yourself. But if you ':source!' a file with the line ":!ls" in it,
the next characters from that file are read until a <CR> is found. You will
not have to type <CR> yourself, unless ":!ls" was the last line in the file.
It is possible to put ':source[!]' commands in the script file, so you can
make a top-down hierarchy of script files. The ':source' command can be
nested as deep as the number of files that can be opened at one time (about
15). The ':source!' command can be nested up to 15 levels deep.
You can use the "<sfile>" string (literally, this is not a special key) inside
of the sourced file, in places where a file name is expected. It will be
replaced by the file name of the sourced file. For example, if you have a
"other.vimrc" file in the same directory as your ".vimrc" file, you can source
it from your ".vimrc" file with this command: >
:source <sfile>:h/other.vimrc
In script files terminal-dependent key codes are represented by
terminal-independent two character codes. This means that they can be used
in the same way on different kinds of terminals. The first character of a
key code is 0x80 or 128, shown on the screen as "~@". The second one can be
found in the list |key-notation|. Any of these codes can also be entered
with CTRL-V followed by the three digit decimal code. This does NOT work for
the <t_xx> termcap codes, these can only be used in mappings.
*:source_crnl* *W15*
MS-DOS, Win32 and OS/2: Files that are read with ":source" normally have
<CR><NL> <EOL>s. These always work. If you are using a file with <NL> <EOL>s
(for example, a file made on Unix), this will be recognized if 'fileformats'
is not empty and the first line does not end in a <CR>. This fails if the
first line has something like ":map <F1> :help^M", where "^M" is a <CR>. If
the first line ends in a <CR>, but following ones don't, you will get an error
message, because the <CR> from the first lines will be lost.
Macintosh: Files that are read with ":source" normally have <CR> <EOL>s.
These always work. If you are using a file with <NL> <EOL>s (for example, a
file made on Unix), this will be recognized if 'fileformats' is not empty and
the first line does not end in a <CR>. Be careful not to use a file with <NL>
linebreaks which has a <CR> in first line.
On other systems, Vim expects ":source"ed files to end in a <NL>. These
always work. If you are using a file with <CR><NL> <EOL>s (for example, a
file made on MS-DOS), all lines will have a trailing <CR>. This may cause
problems for some commands (e.g., mappings). There is no automatic <EOL>
detection, because it's common to start with a line that defines a mapping
that ends in a <CR>, which will confuse the automaton.
*line-continuation*
Long lines in a ":source"d Ex command script file can be split by inserting
a line continuation symbol "\" (backslash) at the start of the next line.
There can be white space before the backslash, which is ignored.
Example: the lines >
:set comments=sr:/*,mb:*,el:*/,
\://,
\b:#,
\:%,
\n:>,
\fb:-
are interpreted as if they were given in one line:
:set comments=sr:/*,mb:*,el:*/,://,b:#,:%,n:>,fb:-
All leading whitespace characters in the line before a backslash are ignored.
Note however that trailing whitespace in the line before it cannot be
inserted freely; it depends on the position where a command is split up
whether additional whitespace is allowed or not.
There is a problem with the ":append" and ":insert" commands: >
:1append
\asdf
.
The backslash is seen as a line-continuation symbol, thus this results in the
command: >
:1appendasdf
.
To avoid this, add the 'C' flag to the 'cpoptions' option: >
:set cpo+=C
:1append
\asdf
.
:set cpo-=C
Note that when the commands are inside a function, you need to add the 'C'
flag when defining the function, it is not relevant when executing it. >
:set cpo+=C
:function Foo()
:1append
\asdf
.
:endfunction
:set cpo-=C
Rationale:
Most programs work with a trailing backslash to indicate line
continuation. Using this in Vim would cause incompatibility with Vi.
For example for this Vi mapping: >
:map xx asdf\
< Therefore the unusual leading backslash is used.
==============================================================================
5. Debugging scripts *debug-scripts*
Besides the obvious messages that you can add to your scripts to find out what
they are doing, Vim offers a debug mode. This allows you to step through a
sourced file or user function and set breakpoints.
NOTE: The debugging mode is far from perfect. Debugging will have side
effects on how Vim works. You cannot use it to debug everything. For
example, the display is messed up by the debugging messages.
{Vi does not have a debug mode}
An alternative to debug mode is setting the 'verbose' option. With a bigger
number it will give more verbose messages about what Vim is doing.
STARTING DEBUG MODE *debug-mode*
To enter debugging mode use one of these methods:
1. Start Vim with the |-D| argument: >
vim -D file.txt
< Debugging will start as soon as the first vimrc file is sourced. This is
useful to find out what is happening when Vim is starting up. A side
effect is that Vim will switch the terminal mode before initialisations
have finished, with unpredictable results.
For a GUI-only version (Windows, Macintosh) the debugging will start as
soon as the GUI window has been opened. To make this happen early, add a
":gui" command in the vimrc file.
*:debug*
2. Run a command with ":debug" prepended. Debugging will only be done while
this command executes. Useful for debugging a specific script or user
function. And for scripts and functions used by autocommands. Example: >
:debug edit test.txt.gz
3. Set a breakpoint in a sourced file or user function. You could do this in
the command line: >
vim -c "breakadd file */explorer.vim" .
< This will run Vim and stop in the first line of the "explorer.vim" script.
Breakpoints can also be set while in debugging mode.
In debugging mode every executed command is displayed before it is executed.
Comment lines, empty lines and lines that are not executed are skipped. When
a line contains two commands, separated by "|", each command will be displayed
separately.
DEBUG MODE
Once in debugging mode, the usual Ex commands can be used. For example, to
inspect the value of a variable: >
echo idx
When inside a user function, this will print the value of the local variable
"idx". Prepend "g:" to get the value of a global variable: >
echo g:idx
All commands are executed in the context of the current function or script.
You can also set options, for example setting or resetting 'verbose' will show
what happens, but you might want to set it just before executing the lines you
are interested in: >
:set verbose=20
Commands that require updating the screen should be avoided, because their
effect won't be noticed until after leaving debug mode. For example: >
:help
won't be very helpful.
There is a separate command-line history for debug mode.
The line number for a function line is relative to the start of the function.
If you have trouble figuring out where you are, edit the file that defines
the function in another Vim, search for the start of the function and do
"99j". Replace "99" with the line number.
Additionally, these commands can be used:
*>cont*
cont Continue execution until the next breakpoint is hit.
*>quit*
quit Abort execution. This is like using CTRL-C, some
things might still be executed, doesn't abort
everything. Still stops at the next breakpoint.
*>next*
next Execute the command and come back to debug mode when
it's finished. This steps over user function calls
and sourced files.
*>step*
step Execute the command and come back to debug mode for
the next command. This steps into called user
functions and sourced files.
*>interrupt*
interrupt This is like using CTRL-C, but unlike ">quit" comes
back to debug mode for the next command that is
executed. Useful for testing |:finally| and |:catch|
on interrupt exceptions.
*>finish*
finish Finish the current script or user function and come
back to debug mode for the command after the one that
sourced or called it.
About the additional commands in debug mode:
- There is no command-line completion for them, you get the completion for the
normal Ex commands only.
- You can shorten them, up to a single character: "c", "n", "s" and "f".
- Hitting <CR> will repeat the previous one. When doing another command, this
is reset (because it's not clear what you want to repeat).
- When you want to use the Ex command with the same name, prepend a colon:
":cont", ":next", ":finish" (or shorter).
DEFINING BREAKPOINTS
*:breaka* *:breakadd*
:breaka[dd] func [lnum] {name}
Set a breakpoint in a function. Example: >
:breakadd func Explore
< Doesn't check for a valid function name, thus the breakpoint
can be set before the function is defined.
:breaka[dd] file [lnum] {name}
Set a breakpoint in a sourced file. Example: >
:breakadd file 43 .vimrc
The [lnum] is the line number of the breakpoint. Vim will stop at or after
this line. When omitted line 1 is used.
{name} is a pattern that is matched with the file or function name. The
pattern is like what is used for autocommands. There must be a full match (as
if the pattern starts with "^" and ends in "$"). A "*" matches any sequence
of characters. 'ignorecase' is not used, but "\c" can be used in the pattern
to ignore case |/\c|. Don't include the () for the function name!
The match for sourced scripts is done against the full file name. Examples: >
breakadd file explorer
won't match, the path is missing. >
breakadd file *explorer.vim
matches ".../plugin/explorer.vim" and ".../plugin/iexplorer.vim". >
breakadd file */explorer.vim
matches ".../plugin/explorer.vim" only.
The match for functions is done against the name as it's shown in the output
of ":function". For local functions this means that something like "<SNR>99_"
is prepended.
DELETING BREAKPOINTS
*:breakd* *:breakdel* *E161*
:breakd[el] {nr}
Delete breakpoint {nr}. Use |:breaklist| to see the number of
each breakpoint.
:breakd[el] func [lnum] {name}
Delete a breakpoint in a function.
:breakd[el] file [lnum] {name}
Delete a breakpoint in a sourced file.
When [lnum] is omitted, the first breakpoint in the function or file is
deleted.
The {name} must be exactly the same as what was typed for the ":breakadd"
command. "explorer", "*explorer.vim" and "*explorer*" are different.
LISTING BREAKPOINTS
*:breakl* *:breaklist*
:breakl[ist]
List all breakpoints.
OBSCURE
*:debugg* *:debuggreedy*
:debugg[reedy]
Read debug mode commands from the normal input stream, instead
of getting them directly from the user. Only useful for test
scripts. Example: >
echo 'q^Mq' | vim -e -s -c debuggreedy -c 'breakadd file script.vim' -S script.vim
:0debugg[reedy]
Undo ":debuggreedy": get debug mode commands directly from the
user, don't use typeahead for debug commands.
vim:tw=78:ts=8:ft=help:norl:

125
runtime/doc/rileft.txt Normal file
View File

@@ -0,0 +1,125 @@
*rileft.txt* For Vim version 7.0aa. Last change: 2003 May 07
VIM REFERENCE MANUAL by Avner Lottem
updated by Nadim Shaikli
Right to Left display mode for Vim *rileft*
These functions were originally created by Avner Lottem:
E-mail: alottem@iil.intel.com
Phone: +972-4-8307322
{Vi does not have any of these commands}
*E26*
This feature is only available when the |+rightleft| feature was enabled
at compile time.
Introduction
------------
Some languages such as Arabic, Farsi, Hebrew (among others) require the
ability to display their text from right-to-left. Files in those languages
are stored conventionally and the right-to-left requirement is only a
function of the display engine (per the Unicode specification). In
right-to-left oriented files the characters appear on the screen from
right to left.
Bidirectionality (or bidi for short) is what Unicode offers as a full
solution to these languages. Bidi offers the user the ability to view
both right-to-left as well as left-to-right text properly at the same time
within the same window. Vim currently, due to simplicity, does not offer
bidi and is merely opting to present a functional means to display/enter/use
right-to-left languages. An older hybrid solution in which direction is
encoded for every character (or group of characters) are not supported either
as this kind of support is out of the scope of a simple addition to an
existing editor (and its not sanctioned by Unicode either).
Highlights
----------
o Editing left-to-right files as in the original Vim, no change.
o Viewing and editing files in right-to-left windows. File orientation
is per window, so it is possible to view the same file in right-to-left
and left-to-right modes, simultaneously. (Useful for editing mixed files
in which both right-to-left and left-to-right text exist).
o Compatibility to the original Vim. Almost all features work in
right-to-left mode (see Bugs below).
o Backing from reverse insert mode to the correct place in the file
(if possible).
o No special terminal with right-to-left capabilities is required. The
right-to-left changes are completely hardware independent.
o Many languages use and require right-to-left support. These languages
can quite easily be supported given the inclusion of their required
keyboard mappings and some possible minor code change. Some of the
current supported languages include - |arabic.txt|, |farsi.txt| and
|hebrew.txt|.
Of Interest...
--------------
o Invocations
-----------
+ 'rightleft' ('rl') sets window orientation to right-to-left.
+ 'delcombine' ('deco'), boolean, if editing UTF-8 encoded languages,
allows one to remove a composing character which gets superimposed
on those that proceeded them (some languages require this).
+ 'rightleftcmd' ('rlc') sets the command-line within certain modes
(such as search) to be utilized in right-to-left orientation as well.
o Typing backwards *ins-reverse*
----------------
In lieu of using full-fledged the 'rightleft' option, one can opt for
reverse insertion. When the 'revins' (reverse insert) option is set,
inserting happens backwards. This can be used to type right-to-left
text. When inserting characters the cursor is not moved and the text
moves rightwards. A <BS> deletes the character under the cursor.
CTRL-W and CTRL-U also work in the opposite direction. <BS>, CTRL-W
and CTRL-U do not stop at the start of insert or end of line, no matter
how the 'backspace' option is set.
There is no reverse replace mode (yet).
If the 'showmode' option is set, "-- REVERSE INSERT --" will be shown
in the status line when reverse Insert mode is active.
o Pasting when in a rightleft window
----------------------------------
When cutting text with the mouse and pasting it in a rightleft window
the text will be reversed, because the characters come from the cut buffer
from the left to the right, while inserted in the file from the right to
the left. In order to avoid it, toggle 'revins' before pasting.
Bugs
----
o Does not handle CTRL-A and CTRL-X commands (add and subtract) correctly
when in rightleft window.
o Does not support reverse insert and rightleft modes on the command-line.
However, functionality of the editor is not reduced, because it is
possible to enter mappings, abbreviations and searches typed from the
left to the right on the command-line.
o Somewhat slower in right-to-left mode, because right-to-left motion is
emulated inside Vim, not by the controlling terminal.
o When the Athena GUI is used, the bottom scrollbar works in the wrong
direction. This is difficult to fix.
o When both 'rightleft' and 'revins' are on: 'textwidth' does not work.
Lines do not wrap at all; you just get a single, long line.
o There is no full bidirectionality (bidi) support.
vim:tw=78:ts=8:ft=help:norl:

83
runtime/doc/russian.txt Normal file
View File

@@ -0,0 +1,83 @@
*russian.txt* For Vim version 7.0aa. Last change: 2004 Jun 09
VIM REFERENCE MANUAL by Vassily Ragosin
Russian language localization and support in Vim *russian* *Russian*
1. Introduction |russian-intro|
2. Russian keymaps |russian-keymap|
3. Localization |russian-l18n|
4. Known issues |russian-issues|
===============================================================================
1. Introduction *russian-intro*
Russian language is supported perfectly well in Vim. You can type and view
Russian text just as any other, without the need to tweak the settings.
===============================================================================
2. Russian keymaps *russian-keymap*
To switch between languages you can use your system native keyboard switcher,
or use one of the Russian keymaps, included in the Vim distribution. For
example,
>
:set keymap=russian-jcukenwin
<
In the latter case, you can switch between languages even if you do not have
system Russian keyboard or independently from a system-wide keyboard settings.
See 'keymap'. You can also map a key to switch between keyboards, if you
choose the latter option. See |:map|.
For your convenience, to avoid switching between keyboards, when you need to
enter Normal mode command, you can also set 'langmap' option:
>
:set langmap=ФИСВУАПРШОЛДЬТЩЗЙКЫЕГМЦЧНЯ;ABCDEFGHIJKLMNOPQRSTUVWXYZ,
фисвуапршолдьтщзйкыегмцчня;abcdefghijklmnopqrstuvwxyz
This is in utf-8, you cannot read this if your 'encoding' is not utf-8.
You have to type this command in one line, it is wrapped for the sake of
readability.
===============================================================================
3. Localization *russian-l18n*
If you wish to use messages, help files, menus and other items translated to
Russian, you will need to install the RuVim Language Pack, available in
different codepages from
http://www.sourceforge.net/projects/ruvim/
Make sure that your Vim is at least 6.2.506 and use ruvim 0.5 or later for
automatic installs. Vim also needs to be compiled with |+gettext| feature for
user interface items translations to work.
After downloading an archive from RuVim project, unpack it into your
$VIMRUNTIME directory. We recommend using UTF-8 archive, if your version of
Vim is compiled with |+multi_byte| feature enabled.
In order to use the Russian documentation, make sure you have set the
'helplang' option to "ru".
===============================================================================
4. Known issues *russian-issues*
-- If you are using Russian message translations in Win32 console, then
you may see the output produced by "vim --help", "vim --version" commands
and Win32 console window title appearing in a wrong codepage. This problem
is related to a bug in GNU gettext library and may be fixed in the future
releases of gettext.
-- When using the Win32 console version of Vim you may experience a problem
with many Cyrillic glyphs being replaced by whitespaces for some unknown
reason. Sergey Khorev suggested a registry hack to avoid this:
REGEDIT4
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Nls\CodePage]
"1252"="c_1251.nls"
===============================================================================
vim:tw=78:ts=8:ft=help:norl:

303
runtime/doc/scroll.txt Normal file
View File

@@ -0,0 +1,303 @@
*scroll.txt* For Vim version 7.0aa. Last change: 2004 Jun 08
VIM REFERENCE MANUAL by Bram Moolenaar
Scrolling *scrolling*
These commands move the contents of the window. If the cursor position is
moved off of the window, the cursor is moved onto the window (with
'scrolloff' screen lines around it). A page is the number of lines in the
window minus two. The mnemonics for these commands may be a bit confusing.
Remember that the commands refer to moving the window (the part of the buffer
that you see) upwards or downwards in the buffer. When the window moves
upwards in the buffer, the text in the window moves downwards on your screen.
See section |03.7| of the user manual for an introduction.
1. Scrolling downwards |scroll-down|
2. Scrolling upwards |scroll-up|
3. Scrolling relative to cursor |scroll-cursor|
4. Scrolling horizontally |scroll-horizontal|
5. Scrolling synchronously |scroll-binding|
6. Scrolling with a mouse wheel |scroll-mouse-wheel|
==============================================================================
1. Scrolling downwards *scroll-down*
The following commands move the edit window (the part of the buffer that you
see) downwards (this means that more lines downwards in the text buffer can be
seen):
*CTRL-E*
CTRL-E Scroll window [count] lines downwards in the buffer.
Mnemonic: Extra lines.
*CTRL-D*
CTRL-D Scroll window Downwards in the buffer. The number of
lines comes from the 'scroll' option (default: half a
screen). If [count] given, first set 'scroll' option
to [count]. The cursor is moved the same number of
lines down in the file (if possible; when lines wrap
and when hitting the end of the file there may be a
difference). When the cursor is on the last line of
the buffer nothing happens and a beep is produced.
See also 'startofline' option.
{difference from vi: Vim scrolls 'scroll' screen
lines, instead of file lines; makes a difference when
lines wrap}
<S-Down> or *<S-Down>* *<kPageDown>*
<PageDown> or *<PageDown>* *CTRL-F*
CTRL-F Scroll window [count] pages Forwards (downwards) in
the buffer. See also 'startofline' option.
*z+*
z+ Without [count]: Redraw with the line just below the
window at the top of the window. Put the cursor in
that line, at the first non-blank in the line.
With [count]: just like "z<CR>".
==============================================================================
2. Scrolling upwards *scroll-up*
The following commands move the edit window (the part of the buffer that you
see) upwards (this means that more lines upwards in the text buffer can be
seen):
*CTRL-Y*
CTRL-Y Scroll window [count] lines upwards in the buffer.
Note: When using the MS-Windows key bindings CTRL-Y is
remapped to redo.
*CTRL-U*
CTRL-U Scroll window Upwards in the buffer. The number of
lines comes from the 'scroll' option (default: half a
screen). If [count] given, first set the 'scroll'
option to [count]. The cursor is moved the same
number of lines up in the file (if possible; when
lines wrap and when hitting the end of the file there
may be a difference). When the cursor is on the first
line of the buffer nothing happens and a beep is
produced. See also 'startofline' option.
{difference from vi: Vim scrolls 'scroll' screen
lines, instead of file lines; makes a difference when
lines wrap}
<S-Up> or *<S-Up>* *<kPageUp>*
<PageUp> or *<PageUp>* *CTRL-B*
CTRL-B Scroll window [count] pages Backwards (upwards) in the
buffer. See also 'startofline' option.
*z^*
z^ Without [count]: Redraw with the line just above the
window at the bottom of the window. Put the cursor in
that line, at the first non-blank in the line.
With [count]: First scroll the text to put the [count]
line at the bottom of the window, then redraw with the
line which is now at the top of the window at the
bottom of the window. Put the cursor in that line, at
the first non-blank in the line.
==============================================================================
3. Scrolling relative to cursor *scroll-cursor*
The following commands reposition the edit window (the part of the buffer that
you see) while keeping the cursor on the same line:
*z<CR>*
z<CR> Redraw, line [count] at top of window (default
cursor line). Put cursor at first non-blank in the
line.
*zt*
zt Like "z<CR>", but leave the cursor in the same
column. {not in Vi}
*zN<CR>*
z{height}<CR> Redraw, make window {height} lines tall. This is
useful to make the number of lines small when screen
updating is very slow. Cannot make the height more
than the physical screen height.
*z.*
z. Redraw, line [count] at center of window (default
cursor line). Put cursor at first non-blank in the
line.
*zz*
zz Like "z.", but leave the cursor in the same column.
Careful: If caps-lock is on, this commands becomes
"ZZ": write buffer and exit! {not in Vi}
*z-*
z- Redraw, line [count] at bottom of window (default
cursor line). Put cursor at first non-blank in the
line.
*zb*
zb Like "z-", but leave the cursor in the same column.
{not in Vi}
==============================================================================
4. Scrolling horizontally *scroll-horizontal*
For the following four commands the cursor follows the screen. If the
character that the cursor is on is moved off the screen, the cursor is moved
to the closest character that is on the screen. The value of 'sidescroll' is
not used.
z<Right> or *zl* *z<Right>*
zl Scroll the screen [count] characters to the left.
This only works when 'wrap' is off. {not in Vi}
z<Left> or *zh* *z<Left>*
zh Scroll the screen [count] characters to the right.
This only works when 'wrap' is off. {not in Vi}
*zL*
zL Scroll the screen half a screenwidth to the left.
This only works when 'wrap' is off. {not in Vi}
*zH*
zH Scroll the screen half a screenwidth to the right.
This only works when 'wrap' is off. {not in Vi}
For the following two commands the cursor is not moved in the text, only the
text scrolls on the screen.
*zs*
zs Scroll the screen horizontally to position the cursor
at the start (left side) of the screen. This only
works when 'wrap' is off. {not in Vi}
*ze*
ze Scroll the screen horizontally to position the cursor
at the end (right side) of the screen. This only
works when 'wrap' is off. {not in Vi}
==============================================================================
5. Scrolling synchronously *scroll-binding*
Occasionally, it is desirable to bind two or more windows together such that
when one window is scrolled, the other windows are scrolled also. In Vim,
windows can be given this behavior by setting the (window-specific)
'scrollbind' option. When a window that has 'scrollbind' set is scrolled, all
other 'scrollbind' windows are scrolled the same amount, if possible. The
behavior of 'scrollbind' can be modified by the 'scrollopt' option.
When using the scrollbars, the binding only happens when scrolling the window
with focus (where the cursor is). You can use this to avoid scroll-binding
for a moment without resetting options.
When a window also has the 'diff' option set, the scroll-binding uses the
differences between the two buffers to synchronize the position precisely.
Otherwise the following method is used.
*scrollbind-relative*
Each 'scrollbind' window keeps track of its "relative offset," which can be
thought of as the difference between the current window's vertical scroll
position and the other window's vertical scroll position. When one of the
'scrollbind' windows is asked to vertically scroll past the beginning or end
limit of its text, the window no longer scrolls, but remembers how far past
the limit it wishes to be. The window keeps this information so that it can
maintain the same relative offset, regardless of its being asked to scroll
past its buffer's limits.
However, if a 'scrollbind' window that has a relative offset that is past its
buffer's limits is given the cursor focus, the other 'scrollbind' windows must
jump to a location where the current window's relative offset is valid. This
behavior can be changed by clearing the 'jump' flag from the 'scrollopt'
option.
*syncbind* *:syncbind*
:syncbind Force all 'scrollbind' windows to have the same
relative offset. I.e., when any of the 'scrollbind'
windows is scrolled to the top of its buffer, all of
the 'scrollbind' windows will also be at the top of
their buffers.
*scrollbind-quickadj*
The 'scrollbind' flag is meaningful when using keyboard commands to vertically
scroll a window, and also meaningful when using the vertical scrollbar of the
window which has the cursor focus. However, when using the vertical scrollbar
of a window which doesn't have the cursor focus, 'scrollbind' is ignored.
This allows quick adjustment of the relative offset of 'scrollbind' windows.
==============================================================================
6. Scrolling with a mouse wheel *scroll-mouse-wheel*
When your mouse has a scroll wheel, it should work with Vim in the GUI. How
it works depends on your system. It might also work in an xterm
|xterm-mouse-wheel|.
For the Win32 GUI the scroll action is hard coded. It works just like
dragging the scrollbar of the current window. How many lines are scrolled
depends on your mouse driver. If the scroll action causes input focus
problems, see |intellimouse-wheel-problems|.
For the X11 GUIs (Motif, Athena and GTK) scrolling the wheel generates key
presses <MouseDown> and <MouseUp>. The default action for these keys are:
<MouseDown> scroll three lines down. *<MouseDown>*
<S-MouseDown> scroll a full page down. *<S-MouseDown>*
<C-MouseDown> scroll a full page down. *<C-MouseDown>*
<MouseUp> scroll three lines up. *<MouseUp>*
<S-MouseUp> scroll a full page up. *<S-MouseUp>*
<C-MouseUp> scroll a full page up. *<C-MouseUp>*
This should work in all modes, except when editing the command line.
Note that <MouseDown> is used for scrolling the text down, this happens when
you turn the mouse wheel up!
You can modify this behavior by mapping the keys. For example, to make the
scroll wheel move one line or half a page in Normal mode: >
:map <MouseDown> <C-Y>
:map <S-MouseDown> <C-U>
:map <MouseUp> <C-E>
:map <S-MouseUp> <C-D>
You can also use Alt and Ctrl modifiers.
This only works when Vim gets the scroll wheel events, of course. You can
check if this works with the "xev" program.
When using Xfree86, the /etc/XF86Config file should have the correct entry for
your mouse. For FreeBSD, this entry works for a Logitech scrollmouse: >
Protocol "MouseMan"
Device "/dev/psm0"
ZAxisMapping 4 5
See the Xfree86 documentation for information.
*xterm-mouse-wheel*
To use the mouse wheel in a new xterm you only have to make the scroll wheel
work in your Xserver, as mentioned above.
To use the mouse wheel in an older xterm you must do this:
1. Make it work in your Xserver, as mentioned above.
2. Add translations for the xterm, so that the xterm will pass a scroll event
to Vim as an escape sequence.
3. Add mappings in Vim, to interpret the escape sequences as <MouseUp> or
<MouseDown> keys.
You can do the translations by adding this to your ~.Xdefaults file (or other
file where your X resources are kept): >
XTerm*VT100.Translations: #override \n\
s<Btn4Down>: string("0x9b") string("[64~") \n\
s<Btn5Down>: string("0x9b") string("[65~") \n\
<Btn4Down>: string("0x9b") string("[62~") \n\
<Btn5Down>: string("0x9b") string("[63~") \n\
<Btn4Up>: \n\
<Btn5Up>:
Add these mappings to your vimrc file: >
:map <M-Esc>[62~ <MouseDown>
:map! <M-Esc>[62~ <MouseDown>
:map <M-Esc>[63~ <MouseUp>
:map! <M-Esc>[63~ <MouseUp>
:map <M-Esc>[64~ <S-MouseDown>
:map! <M-Esc>[64~ <S-MouseDown>
:map <M-Esc>[65~ <S-MouseUp>
:map! <M-Esc>[65~ <S-MouseUp>
<
vim:tw=78:ts=8:ft=help:norl:

191
runtime/doc/sign.txt Normal file
View File

@@ -0,0 +1,191 @@
*sign.txt* For Vim version 7.0aa. Last change: 2004 May 22
VIM REFERENCE MANUAL by Gordon Prieur
and Bram Moolenaar
Sign Support Features *sign-support*
1. Introduction |sign-intro|
2. Commands |sign-commands|
{Vi does not have any of these features}
{only available when compiled with the |+signs| feature}
==============================================================================
1. Introduction *sign-intro* *signs*
When a debugger or other IDE tool is driving an editor it needs to be able
to give specific highlights which quickly tell the user useful information
about the file. One example of this would be a debugger which had an icon
in the left-hand column denoting a breakpoint. Another example might be an
arrow representing the Program Counter (PC). The sign features allow both
placement of a sign, or icon, in the left-hand side of the window and
definition of a highlight which will be applied to that line. Displaying the
sign as an image is most likely only feasible in gvim (although Sun
Microsystem's dtterm does support this its the only terminal emulator I know
of which does). A text sign and the highlight should be feasible in any color
terminal emulator.
Signs and highlights are not useful just for debuggers. Sun's Visual
WorkShop uses signs and highlights to mark build errors and SourceBrowser
hits. Additionally, the debugger supports 8 to 10 different signs and
highlight colors. |workshop| Same for Netbeans |netbeans|.
There are two steps in using signs:
1. Define the sign. This specifies the image, text and highlighting. For
example, you can define a "break" sign with an image of a stop roadsign and
text "!!".
2. Place the sign. This specifies the file and line number where the sign is
displayed. A defined sign can be placed several times in different lines
and files.
When signs are defined for a file, Vim will automatically add a column of two
characters to display them in. When the last sign is unplaced the column
disappears again. The color of the column is set with the SignColumn group
|hl-SignColumn|. Example to set the color: >
:highlight SignColumn guibg=darkgrey
==============================================================================
2. Commands *sign-commands* *:sig* *:sign*
Here is an example that places a sign piet, displayed with the text ">>", in
line 23 of the current file: >
:sign define piet text=>> texthl=Search
:exe ":sign place 2 line=23 name=piet file=" . expand("%:p")
And here is the command to delete it again: >
:sign unplace 2
Note that the ":sign" command cannot be followed by another command or a
comment. If you do need that, use the |:execute| command.
DEFINING A SIGN. *:sign-define* *E255* *E160* *E612*
:sign define {name} {argument}...
Define a new sign or set attributes for an existing sign.
The {name} can either be a number (all digits) or a name
starting with a non-digit.
About 120 different signs can be defined.
Accepted arguments:
icon={pixmap}
Define the file name where the bitmap can be found. Should be
a full path. The bitmap should fit in the place of two
characters. This is not checked. If the bitmap is too big it
will cause redraw problems. Only GTK 2 can scale the bitmap
to fit the space available.
toolkit supports ~
GTK 1 pixmap (.xpm)
GTK 2 many
Motif pixmap (.xpm)
linehl={group}
Highlighting group used for the whole line the sign is placed
in. Most useful is defining a background color.
text={text} *E239*
Define the text that is displayed when there is no icon or the
GUI is not being used. Only printable characters are allowed
and they must occupy one or two display cells.
texthl={group}
Highlighting group used for the text item.
DELETING A SIGN *:sign-undefine* *E155*
:sign undefine {name}
Deletes a previously defined sign. If signs with this {name}
are still placed this will cause trouble.
LISTING SIGNS *:sign-list* *E156*
:sign list Lists all defined signs and their attributes.
:sign list {name}
Lists one defined sign and its attributes.
PLACING SIGNS *:sign-place* *E158*
:sign place {id} line={lnum} name={name} file={fname}
Place sign defined as {name} at line {lnum} in file {fname}.
*:sign-fname*
The file {fname} must already be loaded in a buffer. The
exact file name must be used, wildcards, $ENV and ~ are not
expanded, white space must not be escaped. Trailing white
space is ignored.
The sign is remembered under {id}, this can be used for
further manipulation. {id} must be a number.
It's up to the user to make sure the {id} is used only once in
each file (if it's used several times unplacing will also have
to be done several times and making changes may not work as
expected).
:sign place {id} line={lnum} name={name} buffer={nr}
Same, but use buffer {nr}.
:sign place {id} name={name} file={fname}
Change the placed sign {id} in file {fname} to use the defined
sign {name}. See remark above about {fname} |:sign-fname|.
This can be used to change the displayed sign without moving
it (e.g., when the debugger has stopped at a breakpoint).
:sign place {id} name={name} buffer={nr}
Same, but use buffer {nr}.
REMOVING SIGNS *:sign-unplace* *E159*
:sign unplace {id} file={fname}
Remove the previously placed sign {id} from file {fname}.
See remark above about {fname} |:sign-fname|.
:sign unplace {id} buffer={nr}
Same, but use buffer {nr}.
:sign unplace {id}
Remove the previously placed sign {id} from all files it
appears in.
:sign unplace *
Remove all placed signs.
:sign unplace
Remove the placed sign at the cursor position.
LISTING PLACED SIGNS
:sign place file={fname}
List signs placed in file {fname}.
See remark above about {fname} |:sign-fname|.
:sign place buffer={nr}
List signs placed in buffer {nr}.
:sign place List placed signs in all files.
JUMPING TO A SIGN *:sign-jump* *E157*
:sign jump {id} file={fname}
Open the file {fname} or jump to the window that contains
{fname} and position the cursor at sign {id}.
See remark above about {fname} |:sign-fname|.
If the file isn't displayed in window and the current file can
not be |abandon|ed this fails.
:sign jump {id} buffer={nr}
Same, but use buffer {nr}.
vim:tw=78:ts=8:ft=help:norl:

229
runtime/doc/sponsor.txt Normal file
View File

@@ -0,0 +1,229 @@
*sponsor.txt* For Vim version 7.0aa. Last change: 2004 Apr 23
VIM REFERENCE MANUAL by Bram Moolenaar
SPONSOR VIM DEVELOPMENT *sponsor*
Fixing bugs and adding new features takes a lot of effort. For a few years
Bram has attempted to do this next to a full-time job. During that time the
todo list kept getting longer and longer.
In order for Bram to support Vim properly he needs your support. Through your
donations Bram will be able to have a part-time job and spend more time on
fixing bugs and adding new features.
For the most recent information about sponsoring look on the Vim web site:
http://www.vim.org/sponsor/
More explanations can be found in the |sponsor-faq|.
REGISTERED VIM USER *register*
You can become a registered Vim user by sending at least 10 euro. This works
similar to sponsoring Vim, see |sponsor| above. Registration was made
possible for the situation where your boss or bookkeeper may be willing to
register software, but does not like the terms "sponsoring" and "donation".
More explanations can be found in the |register-faq|.
VOTE FOR FEATURES *vote-for-features*
To give registered Vim users and sponsors an advantage over lurkers they can
vote for the items Bram should work on. How does this voting work?
1. You send at least 10 euro. See below for ways to transfer money
|send-money|.
2. You will be e-mailed a registration key. Enter this key on your account
page on the Vim website. You can easily create an account if you don't
have one yet.
3. You can enter your votes on the voting page. There is a link to that page
on your account page after entering a registration key. Your votes will
be counted for two years.
4. The voting results appear on the results page, which is visible for
everybody: http://www.vim.org/sponsor/vote_results.php
Additionally, once you have send 100 euro or more in total, your name appears
in the "Vim hall of honour": http://www.vim.org/sponsor/hall_of_honour.php
But only if you enable this on your account page.
HOW TO SEND MONEY *send-money*
Creditcard Through PayPal, see the PayPal site for information:
https://www.paypal.com
The e-mail address for sending sponsorship money is:
donate@vim.org
The e-mail address for Vim registration is:
register@vim.org
Using Euro is preferred, other currencies are also accepted.
In Euro countries a bank transfer is preferred, this has lower
costs.
Bank transfer Transfer to Bram's account at the Postbank: 1644503. For
international transfers you can use these numbers:
IBAN: NL79 PSTB 0001 6445 03
SWIFT/BIC: PSTBNL21
This is the address of the bank:
ING Bank Amsterdam, Foreign Operations
PO Box 1800
1000 BV Amsterdam
The Netherlands
Include "Vim sponsor" or "Vim registration" in the comment of
your money transfer. Send me an e-mail that mentions the
amount you transferred if you want to vote for features and
show others you are a registered Vim user or sponsor.
Cash Small amounts can be send with ordinary mail. Put something
around the money, so that it's not noticable from the outside.
Mention your e-mail address if you want to vote for features
and show others you are a registered Vim user or sponsor.
This is Bram's address: Bram Moolenaar
Clematisstraat 30
5925 BE Venlo
The Netherlands
ALTERNATIVE
If you don't care about sponsoring Vim Development or becoming a registered
Vim user, but do care about helping needy children, consider giving to the
ICCF Holland foundation. This is the charity recommended by Vim's author.
The money is used for a children centre in the south of Uganda, where AIDS has
caused many victims. See |uganda|.
QUESTIONS AND ANSWERS *sponsor-faq* *register-faq*
Why should I give money?
Bram has tried to work on Vim next to a full-time job. The list of known bugs
and ideas for new features has constantly been growing during this time. Bram
simply can't spend enough time on Vim development when he has a full-time job.
Your contribution will make it possible for Bram to have a part-time job and
spend much more time on Vim development. Bugs will be fixed quicker and new
Vim releases will become available more often.
How much money should I send?
That is up to you. The more you give, the more time Bram can work on Vim. An
indication for individuals that use Vim at home: 10 Euro per year. For
professional use: 30 Euro per year per person. Send at least 10 euro to be
able to vote for features.
What do I get in return?
Each registered Vim user and sponsor who donates at least 10 euro will be able
to vote for new features. These votes will give priority to the work on Vim.
The votes are valid for two years. The more money you send the more your
votes count |votes-counted|.
If you send 100 Euro or more in total you will be mentioned on the "Vim hall
of honour" page on the Vim web site. But only if you enable this on your
account page. You can also select whether the amount will be visible.
How do I become a Vim sponsor or registered Vim user?
Send money, as explained above |send-money| and include your e-mail address.
When the money has been received you will receive a unique registration key.
This key can be used on the Vim website to activate voting on your Vim
account. You will then get an extra page where you can vote for features and
choose whether others will be able to see that you donated. There is a link
to this page on your "My Account" page.
What is the difference between sponsoring and registering?
It has a different name. Use the term "registration" if your boss doesn't
like "sponsoring" or "donation". The benefits are the same.
How can I send money?
See |send-money|. Check the web site for the most recent information:
http://www.vim.org/sponsor/
Why don't you use the SourceForge donation system?
SourceForge takes 5% of the donations for themselves. If you want to support
SourceForge you can send money to them directly.
I cannot afford to send money, may I still use Vim?
Yes.
I did not register Vim, can I use all available features?
Yes.
I noticed a bug, do I need to register before I can report it?
No, suggestions for improving Vim can always be given. For improvements use
the developer |maillist|, for reporting bugs see |bugs|.
How are my votes counted? *votes-counted*
You may vote when you send 10 euro or more. You can enter up to ten votes.
You can select the same item several times to give it more points. You can
also enter three counter votes, these count as negative points.
When you send 30 euro or more the points are doubled. Above 100 euro they
count four times, above 300 euro they count six times, above 1000 euro ten
times.
Can I change my votes?
You can change your votes any time you like, up to two years after you
sent money. The points will be counted right away.
How about Charityware?
You have to decide yourself whether you want to sponsor Vim development, help
the poor children in Uganda (see |uganda|) or both. Bram will certainly keep
on supporting the project in Uganda. In the (unlikely) situation that Bram
gets more donations for Vim development than he needs, he will send the money
to Uganda.
I donated $$$, now please add feature XYZ!
There is no direct relation between your donation and the work Bram does.
Otherwise you would be paying for work and Bram has to pay income tax over the
donation. If you want to hire Bram for specific work, contact him directly,
don't use the donation system.
Are the donations tax deductable?
No. Setting up a system for this is complex and imposes too many restrictions.
The donations to help the children in |Uganda| are tax deductable in Holland,
Germany, Canada and probably also in the USA.
Can you send me a bill?
Sending a bill would mean Bram does something in return for your contribution.
That is work and would mean Bram has to pay income tax over the amount. It is
possible, but the net amount will be lower.
vim:tw=78:ts=8:ft=help:norl:

1418
runtime/doc/starting.txt Normal file
View File

File diff suppressed because it is too large Load Diff

4161
runtime/doc/syntax.txt Normal file
View File

File diff suppressed because it is too large Load Diff

6649
runtime/doc/tags Normal file
View File

File diff suppressed because it is too large Load Diff

809
runtime/doc/tagsrch.txt Normal file
View File

@@ -0,0 +1,809 @@
*tagsrch.txt* For Vim version 7.0aa. Last change: 2004 Apr 29
VIM REFERENCE MANUAL by Bram Moolenaar
Tags and special searches *tags-and-searches*
See section |29.1| of the user manual for an introduction.
1. Jump to a tag |tag-commands|
2. Tag stack |tag-stack|
3. Tag match list |tag-matchlist|
4. Tags details |tag-details|
5. Tags file format |tags-file-format|
6. Include file searches |include-search|
==============================================================================
1. Jump to a tag *tag-commands*
*tag* *tags*
A tag is an identifier that appears in a "tags" file. It is a sort of label
that can be jumped to. For example: In C programs each function name can be
used as a tag. The "tags" file has to be generated by a program like ctags,
before the tag commands can be used.
With the ":tag" command the cursor will be positioned on the tag. With the
CTRL-] command, the keyword on which the cursor is standing is used as the
tag. If the cursor is not on a keyword, the first keyword to the right of the
cursor is used.
The ":tag" command works very well for C programs. If you see a call to a
function and wonder what that function does, position the cursor inside of the
function name and hit CTRL-]. This will bring you to the function definition.
An easy way back is with the CTRL-T command. Also read about the tag stack
below.
*:ta* *:tag* *E426* *E429*
:ta[g][!] {ident} Jump to the definition of {ident}, using the
information in the tags file(s). Put {ident} in the
tag stack. See |tag-!| for [!].
{ident} can be a regexp pattern, see |tag-regexp|.
When there are several matching tags for {ident}, the
first one is jumped to. |:tnext|.
g<LeftMouse> *g<LeftMouse>*
<C-LeftMouse> *<C-LeftMouse>* *CTRL-]*
CTRL-] Jump to the definition of the keyword under the
cursor. Same as ":tag {ident}", where {ident} is the
keyword under or after cursor. {Vi: identifier after
the cursor}
*v_CTRL-]*
{Visual}CTRL-] Same as ":tag {ident}", where {ident} is the text that
is highlighted. {not in Vi}
*telnet-CTRL-]*
CTRL-] is the default telnet escape key. When you type CTRL-] to jump to a
tag, you will get the telnet prompt instead. Most versions of telnet allow
changing or disabling the default escape key. See the telnet man page. You
can 'telnet -E {Hostname}' to disable the escape character, or 'telnet -e
{EscapeCharacter} {Hostname}' to specify another escape character. If
possible, try to use "rsh" instead of "telnet" to avoid this problem.
*tag-priority*
When there are multiple matches for a tag, this priority is used:
1. "FSC" A full matching static tag for the current file.
2. "F C" A full matching global tag for the current file.
3. "F " A full matching global tag for another file.
4. "FS " A full matching static tag for another file.
5. " SC" An ignore-case matching static tag for the current file.
6. " C" An ignore-case matching global tag for the current file.
7. " " An ignore-case matching global tag for another file.
8. " S " An ignore-case matching static tag for another file.
Note that when the current file changes, the priority list is mostly not
changed, to avoid confusion when using ":tnext". It is changed when using
":tag {ident}".
The ignore-case matches are not found for a ":tag" command when the
'ignorecase' option is off. They are found when a pattern is used (starting
with a "/") and for ":tselect", also when 'ignorecase' is off. Note that
using ignore-case tag searching disables binary searching in the tags file,
which causes a slowdown. This can be avoided by fold-case sorting the tag
file. See the 'tagbsearch' option for an explanation.
==============================================================================
2. Tag stack *tag-stack* *tagstack* *E425*
On the tag stack is remembered which tags you jumped to, and from where.
Tags are only pushed onto the stack when the 'tagstack' option is set.
g<RightMouse> *g<RightMouse>*
<C-RightMouse> *<C-RightMouse>* *CTRL-T*
CTRL-T Jump to [count] older entry in the tag stack
(default 1). {not in Vi}
*:po* *:pop* *E555* *E556*
:[count]po[p][!] Jump to [count] older entry in tag stack (default 1).
See |tag-!| for [!]. {not in Vi}
:[count]ta[g][!] Jump to [count] newer entry in tag stack (default 1).
See |tag-!| for [!]. {not in Vi}
*:tags*
:tags Show the contents of the tag stack. The active
entry is marked with a '>'. {not in Vi}
The output of ":tags" looks like this:
# TO tag FROM line in file/line
1 1 main 1 harddisk2:text/vim/test
> 2 2 FuncA 58 i = FuncA(10);
3 1 FuncC 357 harddisk2:text/vim/src/amiga.c
This list shows the tags that you jumped to and the cursor position before
that jump. The older tags are at the top, the newer at the bottom.
The '>' points to the active entry. This is the tag that will be used by the
next ":tag" command. The CTRL-T and ":pop" command will use the position
above the active entry.
Below the "TO" is the number of the current match in the match list. Note
that this doesn't change when using ":pop" or ":tag".
The line number and file name are remembered to be able to get back to where
you were before the tag command. The line number will be correct, also when
deleting/inserting lines, unless this was done by another program (e.g.
another instance of Vim).
For the current file, the "file/line" column shows the text at the position.
An indent is removed and a long line is truncated to fit in the window.
You can jump to previously used tags with several commands. Some examples:
":pop" or CTRL-T to position before previous tag
{count}CTRL-T to position before {count} older tag
":tag" to newer tag
":0tag" to last used tag
The most obvious way to use this is while browsing through the call graph of
a program. Consider the following call graph:
main ---> FuncA ---> FuncC
---> FuncB
(Explanation: main calls FuncA and FuncB; FuncA calls FuncC).
You can get from main to FuncA by using CTRL-] on the call to FuncA. Then
you can CTRL-] to get to FuncC. If you now want to go back to main you can
use CTRL-T twice. Then you can CTRL-] to FuncB.
If you issue a ":ta {ident}" or CTRL-] command, this tag is inserted at the
current position in the stack. If the stack was full (it can hold up to 20
entries), the oldest entry is deleted and the older entries shift one
position up (their index number is decremented by one). If the last used
entry was not at the bottom, the entries below the last used one are
deleted. This means that an old branch in the call graph is lost. After the
commands explained above the tag stack will look like this:
# TO tag FROM line in file
1 main 1 harddisk2:text/vim/test
2 FuncB 59 harddisk2:text/vim/src/main.c
*E73*
When you try to use the tag stack while it doesn't contain anything you will
get an error message.
==============================================================================
3. Tag match list *tag-matchlist* *E427* *E428*
When there are several matching tags, these commands can be used to jump
between them. Note that these command don't change the tag stack, they keep
the same entry.
*:ts* *:tselect*
:ts[elect][!] [ident] List the tags that match [ident], using the
information in the tags file(s).
When [ident] is not given, the last tag name from the
tag stack is used.
With a '>' in the first column is indicated which is
the current position in the list (if there is one).
[ident] can be a regexp pattern, see |tag-regexp|.
See |tag-priority| for the priorities used in the
listing. {not in Vi}
Example output:
>
nr pri kind tag file
1 F f mch_delay os_amiga.c
mch_delay(msec, ignoreinput)
> 2 F f mch_delay os_msdos.c
mch_delay(msec, ignoreinput)
3 F f mch_delay os_unix.c
mch_delay(msec, ignoreinput)
Enter nr of choice (<CR> to abort):
<
See |tag-priority| for the "pri" column. Note that
this depends on the current file, thus using
":tselect xxx" can produce different results.
The "kind" column gives the kind of tag, if this was
included in the tags file.
The "info" column shows information that could be
found in the tags file. It depends on the program
that produced the tags file.
When the list is long, you may get the |more-prompt|.
If you already see the tag you want to use, you can
type 'q' and enter the number.
*:sts* *:stselect*
:sts[elect][!] [ident] Does ":tselect[!] [ident]" and splits the window for
the selected tag. {not in Vi}
*g]*
g] Like CTRL-], but use ":tselect" instead of ":tag".
{not in Vi}
*v_g]*
{Visual}g] Same as "g]", but use the highlighted text as the
identifier. {not in Vi}
*:tj* *:tjump*
:tj[ump][!] [ident] Like ":tselect", but jump to the tag directly when
there is only one match. {not in Vi}
*:stj* *:stjump*
:stj[ump][!] [ident] Does ":tjump[!] [ident]" and splits the window for the
selected tag. {not in Vi}
*g_CTRL-]*
g CTRL-] Like CTRL-], but use ":tjump" instead of ":tag".
{not in Vi}
*v_g_CTRL-]*
{Visual}g CTRL-] Same as "g CTRL-]", but use the highlighted text as
the identifier. {not in Vi}
*:tn* *:tnext*
:[count]tn[ext][!] Jump to [count] next matching tag (default 1). See
|tag-!| for [!]. {not in Vi}
*:tp* *:tprevious*
:[count]tp[revious][!] Jump to [count] previous matching tag (default 1).
See |tag-!| for [!]. {not in Vi}
*:tN* *:tNext*
:[count]tN[ext][!] Same as ":tprevious". {not in Vi}
*:tr* *:trewind*
:[count]tr[ewind][!] Jump to first matching tag. If [count] is given, jump
to [count]th matching tag. See |tag-!| for [!]. {not
in Vi}
*:tf* *:tfirst*
:[count]tf[irst][!] Same as ":trewind". {not in Vi}
*:tl* *:tlast*
:tl[ast][!] Jump to last matching tag. See |tag-!| for [!]. {not
in Vi}
When there is no other message, Vim shows which matching tag has been jumped
to, and the number of matching tags: >
tag 1 of 3 or more
The " or more" is used to indicate that Vim didn't try all the tags files yet.
When using ":tnext" a few times, or with ":tlast", more matches may be found.
When you didn't see this message because of some other message, or you just
want to know where you are, this command will show it again (and jump to the
same tag as last time): >
:0tn
<
*tag-skip-file*
When a matching tag is found for which the file doesn't exist, this match is
skipped and the next matching tag is used. Vim reports this, to notify you of
missing files. When the end of the list of matches has been reached, an error
message is given.
The tag match list can also be used in the preview window. The commands are
the same as above, with a "p" prepended.
{not available when compiled without the |+quickfix| feature}
*:pts* *:ptselect*
:pts[elect][!] [ident] Does ":tselect[!] [ident]" and shows the new tag in a
"Preview" window. See |:ptag| for more info.
{not in Vi}
*:ptj* *:ptjump*
:ptj[ump][!] [ident] Does ":tjump[!] [ident]" and shows the new tag in a
"Preview" window. See |:ptag| for more info.
{not in Vi}
*:ptn* *:ptnext*
:[count]ptn[ext][!] ":tnext" in the preview window. See |:ptag|.
{not in Vi}
*:ptp* *:ptprevious*
:[count]ptp[revious][!] ":tprevious" in the preview window. See |:ptag|.
{not in Vi}
*:ptN* *:ptNext*
:[count]ptN[ext][!] Same as ":ptprevious". {not in Vi}
*:ptr* *:ptrewind*
:[count]ptr[ewind][!] ":trewind" in the preview window. See |:ptag|.
{not in Vi}
*:ptf* *:ptfirst*
:[count]ptf[irst][!] Same as ":ptrewind". {not in Vi}
*:ptl* *:ptlast*
:ptl[ast][!] ":tlast" in the preview window. See |:ptag|.
{not in Vi}
==============================================================================
4. Tags details *tag-details*
*static-tag*
A static tag is a tag that is defined for a specific file. In a C program
this could be a static function.
In Vi jumping to a tag sets the current search pattern. This means that
the "n" command after jumping to a tag does not search for the same pattern
that it did before jumping to the tag. Vim does not do this as we consider it
to be a bug. You can still find the tag search pattern in the search history.
If you really want the old Vi behavior, set the 't' flag in 'cpoptions'.
*tag-binary-search*
Vim uses binary searching in the tags file to find the desired tag quickly
(when enabled at compile time |+tag_binary|). But this only works if the
tags file was sorted on ASCII byte value. Therefore, if no match was found,
another try is done with a linear search. If you only want the linear search,
reset the 'tagbsearch' option. Or better: Sort the tags file!
Note that the binary searching is disabled when not looking for a tag with a
specific name. This happens when ignoring case and when a regular expression
is used that doesn't start with a fixed string. Tag searching can be a lot
slower then. The former can be avoided by case-fold sorting the tags file.
See 'tagbsearch' for details.
*tag-regexp*
The ":tag" and "tselect" commands accept a regular expression argument. See
|pattern| for the special characters that can be used.
When the argument starts with '/', it is used as a pattern. If the argument
does not start with '/', it is taken literally, as a full tag name.
Examples: >
:tag main
< jumps to the tag "main" that has the highest priority. >
:tag /^get
< jumps to the tag that starts with "get" and has the highest priority. >
:tag /norm
< lists all the tags that contain "norm", including "id_norm".
When the argument both exists literally, and match when used as a regexp, a
literal match has a higher priority. For example, ":tag /open" matches "open"
before "open_file" and "file_open".
*tag-!*
If the tag is in the current file this will always work. Otherwise the
performed actions depend on whether the current file was changed, whether a !
is added to the command and on the 'autowrite' option:
tag in file autowrite ~
current file changed ! option action ~
-----------------------------------------------------------------------------
yes x x x goto tag
no no x x read other file, goto tag
no yes yes x abandon current file, read other file, goto
tag
no yes no on write current file, read other file, goto
tag
no yes no off fail
-----------------------------------------------------------------------------
- If the tag is in the current file, the command will always work.
- If the tag is in another file and the current file was not changed, the
other file will be made the current file and read into the buffer.
- If the tag is in another file, the current file was changed and a ! is
added to the command, the changes to the current file are lost, the other
file will be made the current file and read into the buffer.
- If the tag is in another file, the current file was changed and the
'autowrite' option is on, the current file will be written, the other
file will be made the current file and read into the buffer.
- If the tag is in another file, the current file was changed and the
'autowrite' option is off, the command will fail. If you want to save
the changes, use the ":w" command and then use ":tag" without an argument.
This works because the tag is put on the stack anyway. If you want to lose
the changes you can use the ":tag!" command.
*tag-security*
Note that Vim forbids some commands, for security reasons. This works like
using the 'secure' option for exrc/vimrc files in the current directory. See
|trojan-horse| and |sandbox|.
When the {tagaddress} changes a buffer, you will get a warning message:
"WARNING: tag command changed a buffer!!!"
In a future version changing the buffer will be impossible. All this for
security reasons: Somebody might hide a nasty command in the tags file, which
would otherwise go unnoticed. Example: >
:$d|/tag-function-name/
{this security prevention is not present in Vi}.
In Vi the ":tag" command sets the last search pattern when the tag is searched
for. In Vim this is not done, the previous search pattern is still remembered,
unless the 't' flag is present in 'cpoptions'. The search pattern is always
put in the search history, so you can modify it if searching fails.
*emacs-tags* *emacs_tags* *E430*
Emacs style tag files are only supported if Vim was compiled with the
|+emacs_tags| feature enabled. Sorry, there is no explanation about Emacs tag
files here, it is only supported for backwards compatibility :-).
*tags-option*
The 'tags' option is a list of file names. Each of these files is searched
for the tag. This can be used to use a different tags file than the default
file "tags". It can also be used to access a common tags file.
The next file in the list is not used when:
- A matching static tag for the current buffer has been found.
- A matching global tag has been found.
This also depends on the 'ignorecase' option. If it is off, and the tags file
only has a match without matching case, the next tags file is searched for a
match with matching case. If no tag with matching case is found, the first
match without matching case is used. If 'ignorecase' is on, and a matching
global tag with or without matching case is found, this one is used, no
further tags files are searched.
When a tag file name starts with "./", the '.' is replaced with the path of
the current file. This makes it possible to use a tags file in the directory
where the current file is (no matter what the current directory is). The idea
of using "./" is that you can define which tag file is searched first: In the
current directory ("tags,./tags") or in the directory of the current file
("./tags,tags").
For example: >
:set tags=./tags,tags,/home/user/commontags
In this example the tag will first be searched for in the file "tags" in the
directory where the current file is. Next the "tags" file in the current
directory. If it is not found there, then the file "/home/user/commontags"
will be searched for the tag.
This can be switched off by including the 'd' flag in 'cpoptions', to make
it Vi compatible. "./tags" will than be the tags file in the current
directory, instead of the tags file in the directory where the current file
is.
Instead of the comma a space may be used. Then a backslash is required for
the space to be included in the string option: >
:set tags=tags\ /home/user/commontags
To include a space in a file name use three backslashes. To include a comma
in a file name use two backslashes. For example, use: >
:set tags=tag\\\ file,/home/user/common\\,tags
for the files "tag file" and "/home/user/common,tags". The 'tags' option will
have the value "tag\ file,/home/user/common\,tags".
If the 'tagrelative' option is on (which is the default) and using a tag file
in another directory, file names in that tag file are relative to the
directory where the tag file is.
==============================================================================
5. Tags file format *tags-file-format* *E431*
*ctags* *jtags*
A tags file can be created with an external command, for example "ctags". It
will contain a tag for each function. Some versions of "ctags" will also make
a tag for each "#defined" macro, typedefs, enums, etc.
Some programs that generate tags files:
ctags As found on most Unix systems. Only supports C. Only
does the basic work.
exuberant ctags This a very good one. It works for C, C++, Java,
Fortran, Eiffel and others. It can generate tags for
many items. See http://ctags.sourceforge.net.
etags Connected to Emacs. Supports many languages.
JTags For Java, in Java. It can be found at
http://www.fleiner.com/jtags/.
ptags.py For Python, in Python. Found in your Python source
directory at Tools/scripts/ptags.py.
ptags For Perl, in Perl. It can be found at
http://www.eleves.ens.fr:8080/home/nthiery/Tags/.
gnatxref For Ada. See http://www.gnuada.org/. gnatxref is
part of the gnat package.
The lines in the tags file must have one of these three formats:
1. {tagname} {TAB} {tagfile} {TAB} {tagaddress}
2. {tagfile}:{tagname} {TAB} {tagfile} {TAB} {tagaddress}
3. {tagname} {TAB} {tagfile} {TAB} {tagaddress} {term} {field} ..
The first is a normal tag, which is completely compatible with Vi. It is the
only format produced by traditional ctags implementations. This is often used
for functions that are global, also referenced in other files.
The lines in the tags file can end in <LF> or <CR><LF>. On the Macintosh <CR>
also works. The <CR> and <NL> characters can never appear inside a line.
*tag-old-static*
The second format is for a static tag only. It is obsolete now, replaced by
the third format. It is only supported by Elvis 1.x and Vim and a few
versions of ctags. A static tag is often used for functions that are local,
only referenced in the file {tagfile}. Note that for the static tag, the two
occurrences of {tagfile} must be exactly the same. Also see |tags-option|
below, for how static tags are used.
The third format is new. It includes additional information in optional
fields at the end of each line. It is backwards compatible with Vi. It is
only supported by new versions of ctags (such as Exuberant ctags).
{tagname} The identifier. Normally the name of a function, but it can
be any identifier. It cannot contain a <Tab>.
{TAB} One <Tab> character. Note: previous versions allowed any
white space here. This has been abandoned to allow spaces in
{tagfile}. It can be re-enabled by including the
|+tag_any_white| feature at compile time. *tag-any-white*
{tagfile} The file that contains the definition of {tagname}. It can
have an absolute or relative path. It may contain environment
variables and wildcards (although the use of wildcards is
doubtful). It cannot contain a <Tab>.
{tagaddress} The Ex command that positions the cursor on the tag. It can
be any Ex command, although restrictions apply (see
|tag-security|). Posix only allows line numbers and search
commands, which are mostly used.
{term} ;" The two characters semicolon and double quote. This is
interpreted by Vi as the start of a comment, which makes the
following be ignored. This is for backwards compatibility
with Vi, it ignores the following fields.
{field} .. A list of optional fields. Each field has the form:
<Tab>{fieldname}:{value}
The {fieldname} identifies the field, and can only contain
alphabetical characters [a-zA-Z].
The {value} is any string, but cannot contain a <Tab>.
These characters are special:
"\t" stands for a <Tab>
"\r" stands for a <CR>
"\n" stands for a <NL>
"\\" stands for a single '\' character
There is one field that doesn't have a ':'. This is the kind
of the tag. It is handled like it was preceded with "kind:".
See the documentation of ctags for the kinds it produces.
The only other field currently recognized by Vim is "file:"
(with an empty value). It is used for a static tag.
The first lines in the tags file can contain lines that start with
!_TAG_
These are sorted to the first lines, only rare tags that start with "!" can
sort to before them. Vim recognizes two items. The first one is the line
that indicates if the file was sorted. When this line is found, Vim uses
binary searching for the tags file:
!_TAG_FILE_SORTED<Tab>1<Tab>{anything} ~
A tag file may be case-fold sorted to avoid a linear search when 'ignorecase'
is on. See 'tagbsearch' for details. The value '2' should be used then:
!_TAG_FILE_SORTED<Tab>2<Tab>{anything} ~
The other tag that Vim recognizes, but only when compiled with the
|+multi_byte| feature, is the encoding of the tags file:
!_TAG_FILE_ENCODING<Tab>utf-8<Tab>{anything} ~
Here "utf-8" is the encoding used for the tags. Vim will then convert the tag
being searched for from 'encoding' to the encoding of the tags file. And when
listing tags the reverse happens. When the conversion fails the unconverted
tag is used.
*tag-search*
The command can be any Ex command, but often it is a search command.
Examples:
tag1 file1 /^main(argc, argv)/ ~
tag2 file2 108 ~
The command is always executed with 'magic' not set. The only special
characters in a search pattern are "^" (begin-of-line) and "$" (<EOL>).
See |pattern|. Note that you must put a backslash before each backslash in
the search text. This is for backwards compatibility with Vi.
*E434* *E435*
If the command is a normal search command (it starts and ends with "/" or
"?"), some special handling is done:
- Searching starts on line 1 of the file.
The direction of the search is forward for "/", backward for "?".
Note that 'wrapscan' does not matter, the whole file is always searched. {Vi
does use 'wrapscan', which caused tags sometimes not be found). {Vi starts
searching in line 2 of another file. It does not find a tag in line 1 of
another file when 'wrapscan' is not set}
- If the search fails, another try is done ignoring case. If that fails too,
a search is done for:
"^tagname[ \t]*("
(the tag with '^' prepended and "[ \t]*(" appended). When using function
names, this will find the function name when it is in column 0. This will
help when the arguments to the function have changed since the tags file was
made. If this search also fails another search is done with:
"^[#a-zA-Z_].*\<tagname[ \t]*("
This means: A line starting with '#' or an identifier and containing the tag
followed by white space and a '('. This will find macro names and function
names with a type prepended. {the extra searches are not in Vi}.
==============================================================================
6. Include file searches *include-search* *definition-search*
*E387* *E388* *E389*
These commands look for a string in the current file and in all encountered
included files (recursively). This can be used to find the definition of a
variable, function or macro. If you only want to search in the current
buffer, use the commands listed at |pattern-searches|.
These commands are not available when the |+find_in_path| feature was disabled
at compile time.
When a line is encountered that includes another file, that file is searched
before continuing in the current buffer. Files included by included files are
also searched. When an include file could not be found it is silently
ignored. Use the |:checkpath| command to discover which files could not be
found, possibly your 'path' option is not set up correctly. Note: the
included file is searched, not a buffer that may be editing that file. Only
for the current file the lines in the buffer are used.
The string can be any keyword or a defined macro. For the keyword any match
will be found. For defined macros only lines that match with the 'define'
option will be found. The default is "^#\s*define", which is for C programs.
For other languages you probably want to change this. See 'define' for an
example for C++. The string cannot contain an end-of-line, only matches
within a line are found.
When a match is found for a defined macro, the displaying of lines continues
with the next line when a line ends in a backslash.
The commands that start with "[" start searching from the start of the current
file. The commands that start with "]" start at the current cursor position.
The 'include' option is used to define a line that includes another file. The
default is "\^#\s*include", which is for C programs. Note: Vim does not
recognize C syntax, if the 'include' option matches a line inside
"#ifdef/#endif" or inside a comment, it is searched anyway. The 'isfname'
option is used to recognize the file name that comes after the matched
pattern.
The 'path' option is used to find the directory for the include files that
do not have an absolute path.
The 'comments' option is used for the commands that display a single line or
jump to a line. It defines patterns that may start a comment. Those lines
are ignored for the search, unless [!] is used. One exception: When the line
matches the pattern "^# *define" it is not considered to be a comment.
If you want to list matches, and then select one to jump to, you could use a
mapping to do that for you. Here is an example: >
:map <F4> [I:let nr = input("Which one: ")<Bar>exe "normal " . nr ."[\t"<CR>
<
*[i*
[i Display the first line that contains the keyword
under the cursor. The search starts at the beginning
of the file. Lines that look like a comment are
ignored (see 'comments' option). If a count is given,
the count'th matching line is displayed, and comment
lines are not ignored. {not in Vi}
*]i*
]i like "[i", but start at the current cursor position.
{not in Vi}
*:is* *:isearch*
:[range]is[earch][!] [count] [/]pattern[/]
Like "[i" and "]i", but search in [range] lines
(default: whole file).
See |:search-args| for [/] and [!]. {not in Vi}
*[I*
[I Display all lines that contain the keyword under the
cursor. Filenames and line numbers are displayed
for the found lines. The search starts at the
beginning of the file. {not in Vi}
*]I*
]I like "[I", but start at the current cursor position.
{not in Vi}
*:il* *:ilist*
:[range]il[ist][!] [/]pattern[/]
Like "[I" and "]I", but search in [range] lines
(default: whole file).
See |:search-args| for [/] and [!]. {not in Vi}
*[_CTRL-I*
[ CTRL-I Jump to the first line that contains the keyword
under the cursor. The search starts at the beginning
of the file. Lines that look like a comment are
ignored (see 'comments' option). If a count is given,
the count'th matching line is jumped to, and comment
lines are not ignored. {not in Vi}
*]_CTRL-I*
] CTRL-I like "[ CTRL-I", but start at the current cursor
position. {not in Vi}
*:ij* *:ijump*
:[range]ij[ump][!] [count] [/]pattern[/]
Like "[ CTRL-I" and "] CTRL-I", but search in
[range] lines (default: whole file).
See |:search-args| for [/] and [!]. {not in Vi}
CTRL-W CTRL-I *CTRL-W_CTRL-I* *CTRL-W_i*
CTRL-W i Open a new window, with the cursor on the first line
that contains the keyword under the cursor. The
search starts at the beginning of the file. Lines
that look like a comment line are ignored (see
'comments' option). If a count is given, the count'th
matching line is jumped to, and comment lines are not
ignored. {not in Vi}
*:isp* *:isplit*
:[range]isp[lit][!] [count] [/]pattern[/]
Like "CTRL-W i" and "CTRL-W i", but search in
[range] lines (default: whole file).
See |:search-args| for [/] and [!]. {not in Vi}
*[d*
[d Display the first macro definition that contains the
macro under the cursor. The search starts from the
beginning of the file. If a count is given, the
count'th matching line is displayed. {not in Vi}
*]d*
]d like "[d", but start at the current cursor position.
{not in Vi}
*:ds* *:dsearch*
:[range]ds[earch][!] [count] [/]string[/]
Like "[d" and "]d", but search in [range] lines
(default: whole file).
See |:search-args| for [/] and [!]. {not in Vi}
*[D*
[D Display all macro definitions that contain the macro
under the cursor. Filenames and line numbers are
displayed for the found lines. The search starts
from the beginning of the file. {not in Vi}
*]D*
]D like "[D", but start at the current cursor position.
{not in Vi}
*:dl* *:dlist*
:[range]dl[ist][!] [/]string[/]
Like "[D" and "]D", but search in [range] lines
(default: whole file).
See |:search-args| for [/] and [!]. {not in Vi}
*[_CTRL-D*
[ CTRL-D Jump to the first macro definition that contains the
keyword under the cursor. The search starts from
the beginning of the file. If a count is given, the
count'th matching line is jumped to. {not in Vi}
*]_CTRL-D*
] CTRL-D like "[ CTRL-D", but start at the current cursor
position. {not in Vi}
*:dj* *:djump*
:[range]dj[ump][!] [count] [/]string[/]
Like "[ CTRL-D" and "] CTRL-D", but search in
[range] lines (default: whole file).
See |:search-args| for [/] and [!]. {not in Vi}
CTRL-W CTRL-D *CTRL-W_CTRL-D* *CTRL-W_d*
CTRL-W d Open a new window, with the cursor on the first
macro definition line that contains the keyword
under the cursor. The search starts from the
beginning of the file. If a count is given, the
count'th matching line is jumped to. {not in Vi}
*:dsp* *:dsplit*
:[range]dsp[lit][!] [count] [/]string[/]
Like "CTRL-W d", but search in [range] lines
(default: whole file).
See |:search-args| for [/] and [!]. {not in Vi}
*:che* *:checkpath*
:che[ckpath] List all the included files that could not be found.
{not in Vi}
:che[ckpath]! List all the included files. {not in Vi}
*:search-args*
Common arguments for the commands above:
[!] When included, find matches in lines that are recognized as comments.
When excluded, a match is ignored when the line is recognized as a
comment (according to 'comments'), or the match is in a C comment (after
"//" or inside /* */). Note that a match may be missed if a line is
recognized as a comment, but the comment ends halfway the line.
And if the line is a comment, but it is not recognized (according to
'comments') a match may be found in it anyway. Example: >
/* comment
foobar */
< A match for "foobar" is found, because this line is not recognized as a
comment (even though syntax highlighting does recognize it).
Note: Since a macro definition mostly doesn't look like a comment, the
[!] makes no difference for ":dlist", ":dsearch" and ":djump".
[/] A pattern can be surrounded by '/'. Without '/' only whole words are
matched, using the pattern "\<pattern\>". Only after the second '/' a
next command can be appended with '|'. Example: >
:isearch /string/ | echo "the last one"
< For a ":djump", ":dsplit", ":dlist" and ":dsearch" command the pattern
is used as a literal string, not as a search pattern.
vim:tw=78:ts=8:ft=help:norl:

808
runtime/doc/term.txt Normal file
View File

@@ -0,0 +1,808 @@
*term.txt* For Vim version 7.0aa. Last change: 2004 Jan 09
VIM REFERENCE MANUAL by Bram Moolenaar
Terminal information *terminal-info*
Vim uses information about the terminal you are using to fill the screen and
recognize what keys you hit. If this information is not correct, the screen
may be messed up or keys may not be recognized. The actions which have to be
performed on the screen are accomplished by outputting a string of
characters. Special keys produce a string of characters. These strings are
stored in the terminal options, see |terminal-options|.
NOTE: Most of this is not used when running the |GUI|.
1. Startup |startup-terminal|
2. Terminal options |terminal-options|
3. Window size |window-size|
4. Slow and fast terminals |slow-fast-terminal|
5. Using the mouse |mouse-using|
==============================================================================
1. Startup *startup-terminal*
When Vim is started a default terminal type is assumed. For the Amiga this is
a standard CLI window, for MS-DOS the pc terminal, for Unix an ansi terminal.
A few other terminal types are always available, see below |builtin-terms|.
You can give the terminal name with the '-T' Vim argument. If it is not given
Vim will try to get the name from the TERM environment variable.
*termcap* *terminfo* *E557* *E558* *E559*
On Unix the terminfo database or termcap file is used. This is referred to as
"termcap" in all the documentation. At compile time, when running configure,
the choice whether to use terminfo or termcap is done automatically. When
running Vim the output of ":version" will show |+terminfo| if terminfo is
used. Also see |xterm-screens|.
On non-Unix systems a termcap is only available if Vim was compiled with
TERMCAP defined.
*builtin-terms* *builtin_terms*
Which builtin terminals are available depends on a few defines in feature.h,
which need to be set at compile time:
define output of ":version" terminals builtin ~
NO_BUILTIN_TCAPS -builtin_terms none
SOME_BUILTIN_TCAPS +builtin_terms most common ones (default)
ALL_BUILTIN_TCAPS ++builtin_terms all available
You can see a list of available builtin terminals with ":set term=xxx" (when
not running the GUI). Also see |+builtin_terms|.
If the termcap code is included Vim will try to get the strings for the
terminal you are using from the termcap file and the builtin termcaps. Both
are always used, if an entry for the terminal you are using is present. Which
one is used first depends on the 'ttybuiltin' option:
'ttybuiltin' on 1: builtin termcap 2: external termcap
'ttybuiltin' off 1: external termcap 2: builtin termcap
If an option is missing in one of them, it will be obtained from the other
one. If an option is present in both, the one first encountered is used.
Which external termcap file is used varies from system to system and may
depend on the environment variables "TERMCAP" and "TERMPATH". See "man
tgetent".
Settings depending on terminal *term-dependent-settings*
If you want to set options or mappings, depending on the terminal name, you
can do this best in your .vimrc. Example: >
if &term == "xterm"
... xterm maps and settings ...
elseif &term =~ "vt10."
... vt100, vt102 maps and settings ...
endif
<
*raw-terminal-mode*
For normal editing the terminal will be put into "raw" mode. The strings
defined with 't_ti' and 't_ks' will be sent to the terminal. Normally this
puts the terminal in a state where the termcap codes are valid and activates
the cursor and function keys. When Vim exits the terminal will be put back
into the mode it was before Vim started. The strings defined with 't_te' and
't_ke' will be sent to the terminal. On the Amiga, with commands that execute
an external command (e.g., "!!"), the terminal will be put into Normal mode
for a moment. This means that you can stop the output to the screen by
hitting a printing key. Output resumes when you hit <BS>.
*cs7-problem*
Note: If the terminal settings are changed after running Vim, you might have
an illegal combination of settings. This has been reported on Solaris 2.5
with "stty cs8 parenb", which is restored as "stty cs7 parenb". Use
"stty cs8 -parenb -istrip" instead, this is restored correctly.
Some termcap entries are wrong in the sense that after sending 't_ks' the
cursor keys send codes different from the codes defined in the termcap. To
avoid this you can set 't_ks' (and 't_ke') to empty strings. This must be
done during initialization (see |initialization|), otherwise it's too late.
Some termcap entries assume that the highest bit is always reset. For
example: The cursor-up entry for the Amiga could be ":ku=\E[A:". But the
Amiga really sends "\233A". This works fine if the highest bit is reset,
e.g., when using an Amiga over a serial line. If the cursor keys don't work,
try the entry ":ku=\233A:".
Some termcap entries have the entry ":ku=\E[A:". But the Amiga really sends
"\233A". On output "\E[" and "\233" are often equivalent, on input they
aren't. You will have to change the termcap entry, or change the key code with
the :set command to fix this.
Many cursor key codes start with an <Esc>. Vim must find out if this is a
single hit of the <Esc> key or the start of a cursor key sequence. It waits
for a next character to arrive. If it does not arrive within one second a
single <Esc> is assumed. On very slow systems this may fail, causing cursor
keys not to work sometimes. If you discover this problem reset the 'timeout'
option. Vim will wait for the next character to arrive after an <Esc>. If
you want to enter a single <Esc> you must type it twice. Resetting the
'esckeys' option avoids this problem in Insert mode, but you lose the
possibility to use cursor and function keys in Insert mode.
On the Amiga the recognition of window resizing is activated only when the
terminal name is "amiga" or "builtin_amiga".
Some terminals have confusing codes for the cursor keys. The televideo 925 is
such a terminal. It sends a CTRL-H for cursor-left. This would make it
impossible to distinguish a backspace and cursor-left. To avoid this problem
CTRL-H is never recognized as cursor-left.
*vt100-cursor-keys* *xterm-cursor-keys*
Other terminals (e.g., vt100 and xterm) have cursor keys that send <Esc>OA,
<Esc>OB, etc. Unfortunately these are valid commands in insert mode: Stop
insert, Open a new line above the new one, start inserting 'A', 'B', etc.
Instead of performing these commands Vim will erroneously recognize this typed
key sequence as a cursor key movement. To avoid this and make Vim do what you
want in either case you could use these settings: >
:set notimeout " don't timeout on mappings
:set ttimeout " do timeout on terminal key codes
:set timeoutlen=100 " timeout after 100 msec
This requires the key-codes to be sent within 100msec in order to recognize
them as a cursor key. When you type you normally are not that fast, so they
are recognized as individual typed commands, even though Vim receives the same
sequence of bytes.
*vt100-function-keys* *xterm-function-keys*
An xterm can send function keys F1 to F4 in two modes: vt100 compatible or
not. Because Vim cannot know what the xterm is sending, both types of keys
are recognized. The same happens for the <Home> and <End> keys.
normal vt100 ~
<F1> t_k1 <Esc>[11~ <xF1> <Esc>OP *<xF1>-xterm*
<F2> t_k2 <Esc>[12~ <xF2> <Esc>OQ *<xF2>-xterm*
<F3> t_k3 <Esc>[13~ <xF3> <Esc>OR *<xF3>-xterm*
<F4> t_k4 <Esc>[14~ <xF4> <Esc>OS *<xF4>-xterm*
<Home> t_kh <Esc>[7~ <xHome> <Esc>OH *<xHome>-xterm*
<End> t_@7 <Esc>[4~ <xEnd> <Esc>OF *<xEnd>-xterm*
When Vim starts, <xF1> is mapped to <F1>, <xF2> to <F2> etc. This means that
by default both codes do the same thing. If you make a mapping for <xF2>,
because your terminal does have two keys, the default mapping is overwritten,
thus you can use the <F2> and <xF2> keys for something different.
*xterm-shifted-keys*
Newer versions of xterm support shifted function keys and special keys. Vim
recognizes most of them. Use ":set termcap" to check which are supported and
what the codes are. Mostly these are not in a termcap, they are only
supported by the builtin_xterm termcap.
*xterm-scroll-region*
The default termcap entry for xterm on Sun and other platforms does not
contain the entry for scroll regions. Add ":cs=\E[%i%d;%dr:" to the xterm
entry in /etc/termcap and everything should work.
*xterm-end-home-keys*
On some systems (at least on FreeBSD with XFree86 3.1.2) the codes that the
<End> and <Home> keys send contain a <Nul> character. To make these keys send
the proper key code, add these lines to your ~/.Xdefaults file:
*VT100.Translations: #override \n\
<Key>Home: string("0x1b") string("[7~") \n\
<Key>End: string("0x1b") string("[8~")
*xterm-8bit* *xterm-8-bit*
Xterm can be run in a mode where it uses 8-bit escape sequences. The CSI code
is used instead of <Esc>[. The advantage is that an <Esc> can quickly be
recognized in Insert mode, because it can't be confused with the start of a
special key.
For the builtin termcap entries, Vim checks if the 'term' option contains
"8bit" anywhere. It then uses 8-bit characters for the termcap entries, the
mouse and a few other things. You would normally set $TERM in your shell to
"xterm-8bit" and Vim picks this up and adjusts to the 8-bit setting
automatically.
When Vim receives a response to the |t_RV| (request version) sequence and it
starts with CSI, it assumes that the terminal is in 8-bit mode and will
convert all key sequences to their 8-bit variants.
==============================================================================
2. Terminal options *terminal-options* *E436*
The terminal options can be set just like normal options. But they are not
shown with the ":set all" command. Instead use ":set termcap".
It is always possible to change individual strings by setting the
appropriate option. For example: >
:set t_ce=^V^[[K (CTRL-V, <Esc>, [, K)
{Vi: no terminal options. You have to exit Vi, edit the termcap entry and
try again}
The options are listed below. The associated termcap code is always equal to
the last two characters of the option name. Only one termcap code is
required: Cursor motion, 't_cm'.
The options 't_da', 't_db', 't_ms', 't_xs' represent flags in the termcap.
When the termcap flag is present, the option will be set to "y". But any
non-empty string means that the flag is set. An empty string means that the
flag is not set. 't_CS' works like this too, but it isn't a termcap flag.
OUTPUT CODES
option meaning ~
t_AB set background color (ANSI) *t_AB* *'t_AB'*
t_AF set foreground color (ANSI) *t_AF* *'t_AF'*
t_AL add number of blank lines *t_AL* *'t_AL'*
t_al add new blank line *t_al* *'t_al'*
t_bc backspace character *t_bc* *'t_bc'*
t_cd clear to end of screen *t_cd* *'t_cd'*
t_ce clear to end of line *t_ce* *'t_ce'*
t_cl clear screen *t_cl* *'t_cl'*
t_cm cursor motion (required!) *E437* *t_cm* *'t_cm'*
t_Co number of colors *t_Co* *'t_Co'*
t_CS if non-empty, cursor relative to scroll region *t_CS* *'t_CS'*
t_cs define scrolling region *t_cs* *'t_cs'*
t_CV define vertical scrolling region *t_CV* *'t_CV'*
t_da if non-empty, lines from above scroll down *t_da* *'t_da'*
t_db if non-empty, lines from below scroll up *t_db* *'t_db'*
t_DL delete number of lines *t_DL* *'t_DL'*
t_dl delete line *t_dl* *'t_dl'*
t_fs set window title end (from status line) *t_fs* *'t_fs'*
t_ke exit "keypad transmit" mode *t_ke* *'t_ke'*
t_ks start "keypad transmit" mode *t_ks* *'t_ks'*
t_le move cursor one char left *t_le* *'t_le'*
t_mb blinking mode *t_mb* *'t_mb'*
t_md bold mode *t_md* *'t_md'*
t_me Normal mode (undoes t_mr, t_mb, t_md and color) *t_me* *'t_me'*
t_mr reverse (invert) mode *t_mr* *'t_mr'*
*t_ms* *'t_ms'*
t_ms if non-empty, cursor can be moved in standout/inverse mode
t_nd non destructive space character *t_nd* *'t_nd'*
t_op reset to original color pair *t_op* *'t_op'*
t_RI cursor number of chars right *t_RI* *'t_RI'*
t_Sb set background color *t_Sb* *'t_Sb'*
t_Sf set foreground color *t_Sf* *'t_Sf'*
t_se standout end *t_se* *'t_se'*
t_so standout mode *t_so* *'t_so'*
t_sr scroll reverse (backward) *t_sr* *'t_sr'*
t_te out of "termcap" mode *t_te* *'t_te'*
t_ti put terminal in "termcap" mode *t_ti* *'t_ti'*
t_ts set window title start (to status line) *t_ts* *'t_ts'*
t_ue underline end *t_ue* *'t_ue'*
t_us underline mode *t_us* *'t_us'*
t_ut clearing uses the current background color *t_ut* *'t_ut'*
t_vb visual bell *t_vb* *'t_vb'*
t_ve cursor visible *t_ve* *'t_ve'*
t_vi cursor invisible *t_vi* *'t_vi'*
t_vs cursor very visible *t_vs* *'t_vs'*
*t_xs* *'t_xs'*
t_xs if non-empty, standout not erased by overwriting (hpterm)
t_ZH italics mode *t_ZH* *'t_ZH'*
t_ZR italics end *t_ZR* *'t_ZR'*
Added by Vim (there are no standard codes for these):
t_IS set icon text start *t_IS* *'t_IS'*
t_IE set icon text end *t_IE* *'t_IE'*
t_WP set window position (Y, X) in pixels *t_WP* *'t_WP'*
t_WS set window size (height, width) in characters *t_WS* *'t_WS'*
t_RV request terminal version string (for xterm) *t_RV* *'t_RV'*
|xterm-8bit| |v:termresponse| |'ttymouse'| |xterm-codes|
KEY CODES
Note: Use the <> form if possible
option name meaning ~
t_ku <Up> arrow up *t_ku* *'t_ku'*
t_kd <Down> arrow down *t_kd* *'t_kd'*
t_kr <Right> arrow right *t_kr* *'t_kr'*
t_kl <Left> arrow left *t_kl* *'t_kl'*
<S-Up> shift arrow up
<S-Down> shift arrow down
t_%i <S-Right> shift arrow right *t_%i* *'t_%i'*
t_#4 <S-Left> shift arrow left *t_#4* *'t_#4'*
t_k1 <F1> function key 1 *t_k1* *'t_k1'*
<xF1> alternate F1 *<xF1>*
t_k2 <F2> function key 2 *<F2>* *t_k2* *'t_k2'*
<xF2> alternate F2 *<xF2>*
t_k3 <F3> function key 3 *<F3>* *t_k3* *'t_k3'*
<xF3> alternate F3 *<xF3>*
t_k4 <F4> function key 4 *<F4>* *t_k4* *'t_k4'*
<xF4> alternate F4 *<xF4>*
t_k5 <F5> function key 5 *<F5>* *t_k5* *'t_k5'*
t_k6 <F6> function key 6 *<F6>* *t_k6* *'t_k6'*
t_k7 <F7> function key 7 *<F7>* *t_k7* *'t_k7'*
t_k8 <F8> function key 8 *<F8>* *t_k8* *'t_k8'*
t_k9 <F9> function key 9 *<F9>* *t_k9* *'t_k9'*
t_k; <F10> function key 10 *<F10>* *t_k;* *'t_k;'*
t_F1 <F11> function key 11 *<F11>* *t_F1* *'t_F1'*
t_F2 <F12> function key 12 *<F12>* *t_F2* *'t_F2'*
t_F3 <F13> function key 13 *<F13>* *t_F3* *'t_F3'*
t_F4 <F14> function key 14 *<F14>* *t_F4* *'t_F4'*
t_F5 <F15> function key 15 *<F15>* *t_F5* *'t_F5'*
t_F6 <F16> function key 16 *<F16>* *t_F6* *'t_F6'*
t_F7 <F17> function key 17 *<F17>* *t_F7* *'t_F7'*
t_F8 <F18> function key 18 *<F18>* *t_F8* *'t_F8'*
t_F9 <F19> function key 19 *<F19>* *t_F9* *'t_F9'*
<S-F1> shifted function key 1
<S-xF1> alternate <S-F1> *<S-xF1>*
<S-F2> shifted function key 2 *<S-F2>*
<S-xF2> alternate <S-F2> *<S-xF2>*
<S-F3> shifted function key 3 *<S-F3>*
<S-xF3> alternate <S-F3> *<S-xF3>*
<S-F4> shifted function key 4 *<S-F4>*
<S-xF4> alternate <S-F4> *<S-xF4>*
<S-F5> shifted function key 5 *<S-F5>*
<S-F6> shifted function key 6 *<S-F6>*
<S-F7> shifted function key 7 *<S-F7>*
<S-F8> shifted function key 8 *<S-F8>*
<S-F9> shifted function key 9 *<S-F9>*
<S-F10> shifted function key 10 *<S-F10>*
<S-F11> shifted function key 11 *<S-F11>*
<S-F12> shifted function key 12 *<S-F12>*
t_%1 <Help> help key *t_%1* *'t_%1'*
t_&8 <Undo> undo key *t_&8* *'t_&8'*
t_kI <Insert> insert key *t_kI* *'t_kI'*
t_kD <Del> delete key *t_kD* *'t_kD'*
t_kb <BS> backspace key *t_kb* *'t_kb'*
t_kB <S-Tab> back-tab (shift-tab) *<S-Tab>* *t_kB* *'t_kB'*
t_kh <Home> home key *t_kh* *'t_kh'*
t_#2 <S-Home> shifted home key *<S-Home>* *t_#2* *'t_#2'*
<xHome> alternate home key *<xHome>*
t_@7 <End> end key *t_@7* *'t_@7'*
t_*7 <S-End> shifted end key *<S-End>* *t_star7* *'t_star7'*
<xEnd> alternate end key *<xEnd>*
t_kP <PageUp> page-up key *t_kP* *'t_kP'*
t_kN <PageDown> page-down key *t_kN* *'t_kN'*
t_K1 <kHome> keypad home key *t_K1* *'t_K1'*
t_K4 <kEnd> keypad end key *t_K4* *'t_K4'*
t_K3 <kPageUp> keypad page-up key *t_K3* *'t_K3'*
t_K5 <kPageDown> keypad page-down key *t_K5* *'t_K5'*
t_K6 <kPlus> keypad plus key *<kPlus>* *t_K6* *'t_K6'*
t_K7 <kMinus> keypad minus key *<kMinus>* *t_K7* *'t_K7'*
t_K8 <kDivide> keypad divide *<kDivide>* *t_K8* *'t_K8'*
t_K9 <kMultiply> keypad multiply *<kMultiply>* *t_K9* *'t_K9'*
t_KA <kEnter> keypad enter key *<kEnter>* *t_KA* *'t_KA'*
t_KB <kPoint> keypad decimal point *<kPoint>* *t_KB* *'t_KB'*
t_KC <k0> keypad 0 *<k0>* *t_KC* *'t_KC'*
t_KD <k1> keypad 1 *<k1>* *t_KD* *'t_KD'*
t_KE <k2> keypad 2 *<k2>* *t_KE* *'t_KE'*
t_KF <k3> keypad 3 *<k3>* *t_KF* *'t_KF'*
t_KG <k4> keypad 4 *<k4>* *t_KG* *'t_KG'*
t_KH <k5> keypad 5 *<k5>* *t_KH* *'t_KH'*
t_KI <k6> keypad 6 *<k6>* *t_KI* *'t_KI'*
t_KJ <k7> keypad 7 *<k7>* *t_KJ* *'t_KJ'*
t_KK <k8> keypad 8 *<k8>* *t_KK* *'t_KK'*
t_KL <k9> keypad 9 *<k9>* *t_KL* *'t_KL'*
<Mouse> leader of mouse code *<Mouse>*
Note about t_so and t_mr: When the termcap entry "so" is not present the
entry for "mr" is used. And vice versa. The same is done for "se" and "me".
If your terminal supports both inversion and standout mode, you can see two
different modes. If your terminal supports only one of the modes, both will
look the same.
The keypad keys, when they are not mapped, behave like the equivalent normal
key.
*xterm-codes*
There is a special trick to obtain the key codes which currently only works
for xterm. When |t_RV| is defined and a response is received which indicates
an xterm with patchlevel 141 or higher, Vim uses special escape sequences to
request the key codes directly from the xterm. The responses are used to
adjust the various t_ codes. This avoids the problem that the xterm can
produce different codes, depending on the mode it is in (8-bit, VT102,
VT220, etc.). The result is that codes like <xF1> are no longer needed.
Note: This is only done on startup. If the xterm options are changed after
Vim has started, the escape sequences may not be recognized any more.
*termcap-colors*
Note about colors: The 't_Co' option tells Vim the number of colors available.
When it is non-zero, the 't_AB' and 't_AF' options are used to set the color.
If one of these is not available, 't_Sb' and 't_Sf' are used. 't_me' is used
to reset to the default colors.
*termcap-title*
The 't_ts' and 't_fs' options are used to set the window title if the terminal
allows title setting via sending strings. They are sent before and after the
title string, respectively. Similar 't_IS' and 't_IE' are used to set the
icon text. These are Vim-internal extensions of the Unix termcap, so they
cannot be obtained from an external termcap. However, the builtin termcap
contains suitable entries for xterm and iris-ansi, so you don't need to set
them here.
*hpterm*
If inversion or other highlighting does not work correctly, try setting the
't_xs' option to a non-empty string. This makes the 't_ce' code be used to
remove highlighting from a line. This is required for "hpterm". Setting the
'weirdinvert' option has the same effect as making 't_xs' non-empty, and vice
versa.
*scroll-region*
Some termcaps do not include an entry for 'cs' (scroll region), although the
terminal does support it. For example: xterm on a Sun. You can use the
builtin_xterm or define t_cs yourself. For example: >
:set t_cs=^V^[[%i%d;%dr
Where ^V is CTRL-V and ^[ is <Esc>.
The vertical scroll region t_CV is not a standard termcap code. Vim uses it
internally in the GUI. But it can also be defined for a terminal, if you can
find one that supports it. The two arguments are the left and right column of
the region which to restrict the scrolling to. Just like t_cs defines the top
and bottom lines. Defining t_CV will make scrolling in vertically split
windows a lot faster. Don't set t_CV when t_da or t_db is set (text isn't
cleared when scrolling).
Unfortunately it is not possible to deduce from the termcap how cursor
positioning should be done when using a scrolling region: Relative to the
beginning of the screen or relative to the beginning of the scrolling region.
Most terminals use the first method. A known exception is the MS-DOS console
(pcterm). The 't_CS' option should be set to any string when cursor
positioning is relative to the start of the scrolling region. It should be
set to an empty string otherwise. It defaults to "yes" when 'term' is
"pcterm".
Note for xterm users: The shifted cursor keys normally don't work. You can
make them work with the xmodmap command and some mappings in Vim.
Give these commands in the xterm:
xmodmap -e "keysym Up = Up F13"
xmodmap -e "keysym Down = Down F16"
xmodmap -e "keysym Left = Left F18"
xmodmap -e "keysym Right = Right F19"
And use these mappings in Vim:
:map <t_F3> <S-Up>
:map! <t_F3> <S-Up>
:map <t_F6> <S-Down>
:map! <t_F6> <S-Down>
:map <t_F8> <S-Left>
:map! <t_F8> <S-Left>
:map <t_F9> <S-Right>
:map! <t_F9> <S-Right>
Instead of, say, <S-Up> you can use any other command that you want to use the
shift-cursor-up key for. (Note: To help people that have a Sun keyboard with
left side keys F14 is not used because it is confused with the undo key; F15
is not used, because it does a window-to-front; F17 is not used, because it
closes the window. On other systems you can probably use them.)
==============================================================================
3. Window size *window-size*
[This is about the size of the whole window Vim is using, not a window that is
created with the ":split" command.]
If you are running Vim on an Amiga and the terminal name is "amiga" or
"builtin_amiga", the amiga-specific window resizing will be enabled. On Unix
systems three methods are tried to get the window size:
- an ioctl call (TIOCGSIZE or TIOCGWINSZ, depends on your system)
- the environment variables "LINES" and "COLUMNS"
- from the termcap entries "li" and "co"
If everything fails a default size of 24 lines and 80 columns is assumed. If
a window-resize signal is received the size will be set again. If the window
size is wrong you can use the 'lines' and 'columns' options to set the
correct values.
One command can be used to set the screen size:
*:mod* *:mode* *E359* *E362*
:mod[e] [mode]
Without argument this only detects the screen size and redraws the screen.
With MS-DOS it is possible to switch screen mode. [mode] can be one of these
values:
"bw40" 40 columns black&white
"c40" 40 columns color
"bw80" 80 columns black&white
"c80" 80 columns color (most people use this)
"mono" 80 columns monochrome
"c4350" 43 or 50 lines EGA/VGA mode
number mode number to use, depends on your video card
==============================================================================
4. Slow and fast terminals *slow-fast-terminal*
*slow-terminal*
If you have a fast terminal you may like to set the 'ruler' option. The
cursor position is shown in the status line. If you are using horizontal
scrolling ('wrap' option off) consider setting 'sidescroll' to a small
number.
If you have a slow terminal you may want to reset the 'showcmd' option.
The command characters will not be shown in the status line. If the terminal
scrolls very slowly, set the 'scrolljump' to 5 or so. If the cursor is moved
off the screen (e.g., with "j") Vim will scroll 5 lines at a time. Another
possibility is to reduce the number of lines that Vim uses with the command
"z{height}<CR>".
If the characters from the terminal are arriving with more than 1 second
between them you might want to set the 'timeout' and/or 'ttimeout' option.
See the "Options" chapter |options|.
If your terminal does not support a scrolling region, but it does support
insert/delete line commands, scrolling with multiple windows may make the
lines jump up and down. If you don't want this set the 'ttyfast' option.
This will redraw the window instead of scroll it.
If your terminal scrolls very slowly, but redrawing is not slow, set the
'ttyscroll' option to a small number, e.g., 3. This will make Vim redraw the
screen instead of scrolling, when there are more than 3 lines to be scrolled.
If you are using a color terminal that is slow, use this command: >
hi NonText cterm=NONE ctermfg=NONE
This avoids that spaces are sent when they have different attributes. On most
terminals you can't see this anyway.
If you are using Vim over a slow serial line, you might want to try running
Vim inside the "screen" program. Screen will optimize the terminal I/O quite
a bit.
If you are testing termcap options, but you cannot see what is happening,
you might want to set the 'writedelay' option. When non-zero, one character
is sent to the terminal at a time (does not work for MS-DOS). This makes the
screen updating a lot slower, making it possible to see what is happening.
==============================================================================
5. Using the mouse *mouse-using*
This section is about using the mouse on a terminal or a terminal window. How
to use the mouse in a GUI window is explained in |gui-mouse|. For scrolling
with a mouse wheel see |scroll-mouse-wheel|.
Don't forget to enable the mouse with this commands: >
:set mouse=a
Otherwise Vim won't recognize the mouse in all modes (See 'mouse').
Currently the mouse is supported for Unix in an xterm window, in a Linux
console (with GPM |gpm-mouse|), for MS-DOS and in a Windows console.
Mouse clicks can be used to position the cursor, select an area and paste.
These characters in the 'mouse' option tell in which situations the mouse will
be used by Vim:
n Normal mode
v Visual mode
i Insert mode
c Command-line mode
h all previous modes when in a help file
a all previous modes
r for |hit-enter| prompt
A auto-select in Visual mode
The default for 'mouse' is empty, the mouse is not used. Normally you would
do: >
:set mouse=a
to start using the mouse (this is equivalent to setting 'mouse' to "nvich").
If you only want to use the mouse in a few modes or also want to use it for
the two questions you will have to concatenate the letters for those modes.
For example: >
:set mouse=nv
Will make the mouse work in Normal mode and Visual mode. >
:set mouse=h
Will make the mouse work in help files only (so you can use "g<LeftMouse>" to
jump to tags).
Whether the selection that is started with the mouse is in Visual mode or
Select mode depends on whether "mouse" is included in the 'selectmode'
option.
In an xterm, with the currently active mode included in the 'mouse' option,
normal mouse clicks are used by Vim, mouse clicks with the shift or ctrl key
pressed go to the xterm. With the currently active mode not included in
'mouse' all mouse clicks go to the xterm.
*xterm-clipboard*
In the Athena and Motif GUI versions, when running in a terminal and there is
access to the X-server (DISPLAY is set), the copy and paste will behave like
in the GUI. If not, the middle mouse button will insert the unnamed register.
In that case, here is how you copy and paste a piece of text:
Copy/paste with the mouse and Visual mode ('mouse' option must be set, see
above):
1. Press left mouse button on first letter of text, move mouse pointer to last
letter of the text and release the button. This will start Visual mode and
highlight the selected area.
2. Press "y" to yank the Visual text in the unnamed register.
3. Click the left mouse button at the insert position.
4. Click the middle mouse button.
Shortcut: If the insert position is on the screen at the same time as the
Visual text, you can do 2, 3 and 4 all in one: Click the middle mouse button
at the insert position.
Note: When the |-X| command line argument is used, Vim will not connect to the
X server and copy/paste to the X clipboard (selection) will not work. Use the
shift key with the mouse buttons to let the xterm do the selection.
*xterm-command-server*
When the X-server clipboard is available, the command server described in
|x11-clientserver| can be enabled with the --servername command line argument.
*xterm-copy-paste*
NOTE: In some (older) xterms, it's not possible to move the cursor past column
95. This is an xterm problem, not Vim's. Get a newer xterm |color-xterm|.
Copy/paste in xterm with (current mode NOT included in 'mouse'):
1. Press left mouse button on first letter of text, move mouse pointer to last
letter of the text and release the button.
2. Use normal Vim commands to put the cursor at the insert position.
3. Press "a" to start Insert mode.
4. Click the middle mouse button.
5. Press ESC to end Insert mode.
(The same can be done with anything in 'mouse' if you keep the shift key
pressed while using the mouse.)
Note: if you lose the 8th bit when pasting (special characters are translated
into other characters), you may have to do "stty cs8 -istrip -parenb" in your
shell before starting Vim.
Thus in an xterm the shift and ctrl keys cannot be used with the mouse. Mouse
commands requiring the CTRL modifier can be simulated by typing the "g" key
before using the mouse:
"g<LeftMouse>" is "<C-LeftMouse> (jump to tag under mouse click)
"g<RightMouse>" is "<C-RightMouse> ("CTRL-T")
*mouse-mode-table* *mouse-overview*
A short overview of what the mouse buttons do, when 'mousemodel' is "extend":
Normal Mode:
event position selection change action ~
cursor window ~
<LeftMouse> yes end yes
<C-LeftMouse> yes end yes "CTRL-]" (2)
<S-LeftMouse> yes no change yes "*" (2) *<S-LeftMouse>*
<LeftDrag> yes start or extend (1) no *<LeftDrag>*
<LeftRelease> yes start or extend (1) no
<MiddleMouse> yes if not active no put
<MiddleMouse> yes if active no yank and put
<RightMouse> yes start or extend yes
<S-RightMouse> yes no change yes "#" (2) *<S-RightMouse>*
<C-RightMouse> no no change no "CTRL-T"
<RightDrag> yes extend no *<RightDrag>*
<RightRelease> yes extend no *<RightRelease>*
Insert or Replace Mode:
event position selection change action ~
cursor window ~
<LeftMouse> yes (cannot be active) yes
<C-LeftMouse> yes (cannot be active) yes "CTRL-O^]" (2)
<S-LeftMouse> yes (cannot be active) yes "CTRL-O*" (2)
<LeftDrag> yes start or extend (1) no like CTRL-O (1)
<LeftRelease> yes start or extend (1) no like CTRL-O (1)
<MiddleMouse> no (cannot be active) no put register
<RightMouse> yes start or extend yes like CTRL-O
<S-RightMouse> yes (cannot be active) yes "CTRL-O#" (2)
<C-RightMouse> no (cannot be active) no "CTRL-O CTRL-T"
In a help window:
event position selection change action ~
cursor window ~
<2-LeftMouse> yes (cannot be active) no "^]" (jump to help tag)
When 'mousemodel' is "popup", these are different:
Normal Mode:
event position selection change action ~
cursor window ~
<S-LeftMouse> yes start or extend (1) no
<RightMouse> no popup menu no
Insert or Replace Mode:
event position selection change action ~
cursor window ~
<S-LeftMouse> yes start or extend (1) no like CTRL-O (1)
<RightMouse> no popup menu no
(1) only if mouse pointer moved since press
(2) only if click is in same buffer
Clicking the left mouse button causes the cursor to be positioned. If the
click is in another window that window is made the active window. When
editing the command-line the cursor can only be positioned on the
command-line. When in Insert mode Vim remains in Insert mode. If 'scrolloff'
is set, and the cursor is positioned within 'scrolloff' lines from the window
border, the text is scrolled.
A selection can be started by pressing the left mouse button on the first
character, moving the mouse to the last character, then releasing the mouse
button. You will not always see the selection until you release the button,
only in some versions (GUI, MS-DOS, WIN32) will the dragging be shown
immediately. Note that you can make the text scroll by moving the mouse at
least one character in the first/last line in the window when 'scrolloff' is
non-zero.
In Normal, Visual and Select mode clicking the right mouse button causes the
Visual area to be extended. When 'mousemodel' is "popup", the left button has
to be used while keeping the shift key pressed. When clicking in a window
which is editing another buffer, the Visual or Select mode is stopped.
*double-click*
Double, triple and quadruple clicks are supported when the GUI is active,
for MS-DOS and Win32, and for an xterm (if the gettimeofday() function is
available). For selecting text, extra clicks extend the selection:
click select ~
double word or % match *<2-LeftMouse>*
triple line *<3-LeftMouse>*
quadruple rectangular block *<4-LeftMouse>*
Exception: In a Help window a double click jumps to help for the word that is
clicked on.
A double click on a word selects that word. 'iskeyword' is used to specify
which characters are included in a word. A double click on a character
that has a match selects until that match (like using "v%"). If the match is
an #if/#else/#endif block, the selection becomes linewise.
For MS-DOS and xterm the time for double clicking can be set with the
'mousetime' option. For the other systems this time is defined outside of
Vim.
An example, for using a double click to jump to the tag under the cursor: >
:map <2-LeftMouse> :exe "tag ". expand("<cword>")<CR>
Dragging the mouse with a double click (button-down, button-up, button-down
and then drag) will result in whole words to be selected. This continues
until the button is released, at which point the selection is per character
again.
*gpm-mouse*
The GPM mouse is only supported when the |+mouse_gpm| feature was enabled at
compile time. The GPM mouse driver (Linux console) does not support quadruple
clicks.
In Insert mode, when a selection is started, Vim goes into Normal mode
temporarily. When Visual or Select mode ends, it returns to Insert mode.
This is like using CTRL-O in Insert mode. Select mode is used when the
'selectmode' option contains "mouse".
*drag-status-line*
When working with several windows, the size of the windows can be changed by
dragging the status line with the mouse. Point the mouse at a status line,
press the left button, move the mouse to the new position of the status line,
release the button. Just clicking the mouse in a status line makes that window
the current window, without moving the cursor. If by selecting a window it
will change position or size, the dragging of the status line will look
confusing, but it will work (just try it).
*<MiddleRelease>* *<MiddleDrag>*
Mouse clicks can be mapped. The codes for mouse clicks are:
code mouse button normal action ~
<LeftMouse> left pressed set cursor position
<LeftDrag> left moved while pressed extend selection
<LeftRelease> left released set selection end
<MiddleMouse> middle pressed paste text at cursor position
<MiddleDrag> middle moved while pressed -
<MiddleRelease> middle released -
<RightMouse> right pressed extend selection
<RightDrag> right moved while pressed extend selection
<RightRelease> right released set selection end
<X1Mouse> X1 button pressed - *X1Mouse*
<X1Drag> X1 moved while pressed - *X1Drag*
<X1Release> X1 button release - *X1Release*
<X2Mouse> X2 button pressed - *X2Mouse*
<X2Drag> X2 moved while pressed - *X2Drag*
<X2Release> X2 button release - *X2Release*
The X1 and X2 buttons refer to the extra buttons found on some mice. The
'Microsoft Explorer' mouse has these buttons available to the right thumb.
Currently X1 and X2 only work on Win32 environments.
Examples: >
:noremap <MiddleMouse> <LeftMouse><MiddleMouse>
Paste at the position of the middle mouse button click (otherwise the paste
would be done at the cursor position). >
:noremap <LeftRelease> <LeftRelease>y
Immediately yank the selection, when using Visual mode.
Note the use of ":noremap" instead of "map" to avoid a recursive mapping.
>
:map <X1Mouse> <C-O>
:map <X2Mouse> <C-I>
Map the X1 and X2 buttons to go forwards and backwards in the jump list, see
|CTRL-O| and |CTRL-I|.
*mouse-swap-buttons*
To swap the meaning of the left and right mouse buttons: >
:noremap <LeftMouse> <RightMouse>
:noremap <LeftDrag> <RightDrag>
:noremap <LeftRelease> <RightRelease>
:noremap <RightMouse> <LeftMouse>
:noremap <RightDrag> <LeftDrag>
:noremap <RightRelease> <LeftRelease>
:noremap g<LeftMouse> <C-RightMouse>
:noremap g<RightMouse> <C-LeftMouse>
:noremap! <LeftMouse> <RightMouse>
:noremap! <LeftDrag> <RightDrag>
:noremap! <LeftRelease> <RightRelease>
:noremap! <RightMouse> <LeftMouse>
:noremap! <RightDrag> <LeftDrag>
:noremap! <RightRelease> <LeftRelease>
<
vim:tw=78:ts=8:ft=help:norl:

445
runtime/doc/tips.txt Normal file
View File

@@ -0,0 +1,445 @@
*tips.txt* For Vim version 7.0aa. Last change: 2004 Feb 17
VIM REFERENCE MANUAL by Bram Moolenaar
Tips and ideas for using Vim *tips*
Don't forget to browse the user manual, it also contains lots of useful tips
|usr_toc.txt|.
Editing C programs |C-editing|
Finding where identifiers are used |ident-search|
Switching screens in an xterm |xterm-screens|
Scrolling in Insert mode |scroll-insert|
Smooth scrolling |scroll-smooth|
Correcting common typing mistakes |type-mistakes|
Counting words, lines, etc. |count-items|
Restoring the cursor position |restore-position|
Renaming files |rename-files|
Speeding up external commands |speed-up|
Useful mappings |useful-mappings|
Compressing the help files |gzip-helpfile|
Hex editing |hex-editing|
Executing shell commands in a window |shell-window|
Using <> notation in autocommands |autocmd-<>|
==============================================================================
Editing C programs *C-editing*
There are quite a few features in Vim to help you edit C program files. Here
is an overview with tags to jump to:
|usr_29.txt| Moving through programs chapter in the user manual.
|usr_30.txt| Editing programs chapter in the user manual.
|C-indenting| Automatically set the indent of a line while typing
text.
|=| Re-indent a few lines.
|format-comments| Format comments.
|:checkpath| Show all recursively included files.
|[i| Search for identifier under cursor in current and
included files.
|[_CTRL-I| Jump to match for "[i"
|[I| List all lines in current and included files where
identifier under the cursor matches.
|[d| Search for define under cursor in current and included
files.
|CTRL-]| Jump to tag under cursor (e.g., definition of a
function).
|CTRL-T| Jump back to before a CTRL-] command.
|:tselect| Select one tag out of a list of matching tags.
|gd| Go to Declaration of local variable under cursor.
|gD| Go to Declaration of global variable under cursor.
|gf| Go to file name under the cursor.
|%| Go to matching (), {}, [], /* */, #if, #else, #endif.
|[/| Go to previous start of comment.
|]/| Go to next end of comment.
|[#| Go back to unclosed #if, #ifdef, or #else.
|]#| Go forward to unclosed #else or #endif.
|[(| Go back to unclosed '('
|])| Go forward to unclosed ')'
|[{| Go back to unclosed '{'
|]}| Go forward to unclosed '}'
|v_ab| Select "a block" from "[(" to "])", including braces
|v_ib| Select "inner block" from "[(" to "])"
|v_aB| Select "a block" from "[{" to "]}", including brackets
|v_iB| Select "inner block" from "[{" to "]}"
==============================================================================
Finding where identifiers are used *ident-search*
You probably already know that |tags| can be used to jump to the place where a
function or variable is defined. But sometimes you wish you could jump to all
the places where a function or variable is being used. This is possible in
two ways:
1. Using the |:grep| command. This should work on most Unix systems,
but can be slow (it reads all files) and only searches in one directory.
2. Using ID utils. This is fast and works in multiple directories. It uses a
database to store locations. You will need some additional programs for
this to work. And you need to keep the database up to date.
Using the GNU id-tools:
What you need:
- The GNU id-tools installed (mkid is needed to create ID and lid is needed to
use the macros).
- An identifier database file called "ID" in the current directory. You can
create it with the shell command "mkid file1 file2 ..".
Put this in your .vimrc: >
map _u :call ID_search()<Bar>execute "/\\<" . g:word . "\\>"<CR>
map _n :n<Bar>execute "/\\<" . g:word . "\\>"<CR>
function! ID_search()
let g:word = expand("<cword>")
let x = system("lid --key=none ". g:word)
let x = substitute(x, "\n", " ", "g")
execute "next " . x
endfun
To use it, place the cursor on a word, type "_u" and vim will load the file
that contains the word. Search for the next occurrence of the word in the
same file with "n". Go to the next file with "_n".
This has been tested with id-utils-3.2 (which is the name of the id-tools
archive file on your closest gnu-ftp-mirror).
[the idea for this comes from Andreas Kutschera]
==============================================================================
Switching screens in an xterm *xterm-screens* *xterm-save-screen*
(From comp.editors, by Juergen Weigert, in reply to a question)
:> Another question is that after exiting vim, the screen is left as it
:> was, i.e. the contents of the file I was viewing (editing) was left on
:> the screen. The output from my previous like "ls" were lost,
:> ie. no longer in the scrolling buffer. I know that there is a way to
:> restore the screen after exiting vim or other vi like editors,
:> I just don't know how. Helps are appreciated. Thanks.
:
:I imagine someone else can answer this. I assume though that vim and vi do
:the same thing as each other for a given xterm setup.
They not necessarily do the same thing, as this may be a termcap vs.
terminfo problem. You should be aware that there are two databases for
describing attributes of a particular type of terminal: termcap and
terminfo. This can cause differences when the entries differ AND when of
the programs in question one uses terminfo and the other uses termcap
(also see |+terminfo|).
In your particular problem, you are looking for the control sequences
^[[?47h and ^[[?47l. These switch between xterms alternate and main screen
buffer. As a quick workaround a command sequence like >
echo -n "^[[?47h"; vim ... ; echo -n "^[[?47l"
may do what you want. (My notation ^[ means the ESC character, further down
you'll see that the databases use \E instead).
On startup, vim echoes the value of the termcap variable ti (terminfo:
smcup) to the terminal. When exiting, it echoes te (terminfo: rmcup). Thus
these two variables are the correct place where the above mentioned control
sequences should go.
Compare your xterm termcap entry (found in /etc/termcap) with your xterm
terminfo entry (retrieved with /usr/5bin/infocmp -C xterm). Both should
contain entries similar to: >
:te=\E[2J\E[?47l\E8:ti=\E7\E[?47h:
PS: If you find any difference, someone (your sysadmin?) should better check
the complete termcap and terminfo database for consistency.
NOTE 1: If you recompile Vim with FEAT_XTERM_SAVE defined in feature.h, the
builtin xterm will include the mentioned "te" and "ti" entries.
NOTE 2: If you want to disable the screen switching, and you don't want to
change your termcap, you can add these lines to your .vimrc: >
:set t_ti= t_te=
==============================================================================
Scrolling in Insert mode *scroll-insert*
If you are in insert mode and you want to see something that is just off the
screen, you can use CTRL-X CTRL-E and CTRL-X CTRL-Y to scroll the screen.
|i_CTRL-X_CTRL-E|
To make this easier, you could use these mappings: >
:inoremap <C-E> <C-X><C-E>
:inoremap <C-Y> <C-X><C-Y>
(Type this literally, make sure the '<' flag is not in 'cpoptions').
You then lose the ability to copy text from the line above/below the cursor
|i_CTRL-E|.
Also consider setting 'scrolloff' to a larger value, so that you can always see
some context around the cursor. If 'scrolloff' is bigger than half the window
height, the cursor will always be in the middle and the text is scrolled when
the cursor is moved up/down.
==============================================================================
Smooth scrolling *scroll-smooth*
If you like the scrolling to go a bit smoother, you can use these mappings: >
:map <C-U> <C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y>
:map <C-D> <C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E>
(Type this literally, make sure the '<' flag is not in 'cpoptions').
==============================================================================
Correcting common typing mistakes *type-mistakes*
When there are a few words that you keep on typing in the wrong way, make
abbreviations that correct them. For example: >
:ab teh the
:ab fro for
==============================================================================
Counting words, lines, etc. *count-items*
To count how often any pattern occurs in a buffer, set 'report' to 0, and use
the substitute command to replace the pattern with itself. The reported
number of substitutions is the number of items. Examples: >
:set report=0
:%s/./&/g characters
:%s/\i\+/&/g words
:%s/^ lines
:%s/the/&/g "the" anywhere
:%s/\<the\>/&/g "the" as a word
You might want to reset 'hlsearch' or do ":nohlsearch".
This does not work if the 'modifiable' option is off. An alternative is using
|v_g_CTRL-G| in Visual mode.
*count-bytes*
If you want to count bytes, you can use this:
Visually select the characters (block is also possible)
Use "y" to yank the characters
Use the strlen() function: >
:echo strlen(@")
A line break is counted for one byte.
==============================================================================
Restoring the cursor position *restore-position*
Sometimes you want to write a mapping that makes a change somewhere in the
file and restores the cursor position, without scrolling the text. For
example, to change the date mark in a file: >
:map <F2> msHmtgg/Last [cC]hange:\s*/e+1<CR>"_D"=strftime("%Y %b %d")<CR>p'tzt`s
Breaking up saving the position:
ms store cursor position in the 's' mark
H go to the first line in the window
mt store this position in the 't' mark
Breaking up restoring the position:
't go to the line previously at the top of the window
zt scroll to move this line to the top of the window
`s jump to the original position of the cursor
==============================================================================
Renaming files *rename-files*
Say I have a directory with the following files in them (directory picked at
random :-):
buffer.c
charset.c
digraph.c
...
and I want to rename *.c *.bla. I'd do it like this: >
$ vim
:r! ls *.c
:%s/\(.*\).c/mv & \1.bla
:w !sh
:q!
==============================================================================
Speeding up external commands *speed-up*
In some situations, execution of an external command can be very slow. This
can also slow down wildcard expansion on Unix. Here are a few suggestions to
increase the speed.
If your .cshrc (or other file, depending on the shell used) is very long, you
should separate it into a section for interactive use and a section for
non-interactive use (often called secondary shells). When you execute a
command from Vim like ":!ls", you do not need the interactive things (for
example, setting the prompt). Put the stuff that is not needed after these
lines: >
if ($?prompt == 0) then
exit 0
endif
Another way is to include the "-f" flag in the 'shell' option, e.g.: >
:set shell=csh\ -f
(the backslash is needed to include the space in the option).
This will make csh completely skip the use of the .cshrc file. This may cause
some things to stop working though.
==============================================================================
Useful mappings *useful-mappings*
Here are a few mappings that some people like to use.
*map-backtick* >
:map ' `
Make the single quote work like a backtick. Puts the cursor on the column of
a mark, instead of going to the first non-blank character in the line.
*emacs-keys*
For Emacs-style editing on the command-line: >
" start of line
:cnoremap <C-A> <Home>
" back one character
:cnoremap <C-B> <Left>
" delete character under cursor
:cnoremap <C-D> <Del>
" end of line
:cnoremap <C-E> <End>
" forward one character
:cnoremap <C-F> <Right>
" recall newer command-line
:cnoremap <C-N> <Down>
" recall previous (older) command-line
:cnoremap <C-P> <Up>
" back one word
:cnoremap <Esc><C-B> <S-Left>
" forward one word
:cnoremap <Esc><C-F> <S-Right>
NOTE: This requires that the '<' flag is excluded from 'cpoptions'. |<>|
*format-bullet-list*
This mapping will format any bullet list. It requires that there is an empty
line above and below each list entry. The expression commands are used to
be able to give comments to the parts of the mapping. >
:let m = ":map _f :set ai<CR>" " need 'autoindent' set
:let m = m . "{O<Esc>" " add empty line above item
:let m = m . "}{)^W" " move to text after bullet
:let m = m . "i <CR> <Esc>" " add space for indent
:let m = m . "gq}" " format text after the bullet
:let m = m . "{dd" " remove the empty line
:let m = m . "5lDJ" " put text after bullet
:execute m |" define the mapping
(<> notation |<>|. Note that this is all typed literally. ^W is "^" "W", not
CTRL-W. You can copy/paste this into Vim if '<' is not included in
'cpoptions')
Note that the last comment starts with |", because the ":execute" command
doesn't accept a comment directly.
You also need to set 'textwidth' to a non-zero value, e.g., >
:set tw=70
A mapping that does about the same, but takes the indent for the list from the
first line (Note: this mapping is a single long line with a lot of spaces): >
:map _f :set ai<CR>}{a <Esc>WWmmkD`mi<CR><Esc>kkddpJgq}'mJO<Esc>j
<
*collapse*
These two mappings reduce a sequence of empty (;b) or blank (;n) lines into a
single line >
:map ;b GoZ<Esc>:g/^$/.,/./-j<CR>Gdd
:map ;n GoZ<Esc>:g/^[ <Tab>]*$/.,/[^ <Tab>]/-j<CR>Gdd
==============================================================================
Compressing the help files *gzip-helpfile*
For those of you who are really short on disk space, you can compress the help
files and still be able to view them with Vim. This makes accessing the help
files a bit slower and requires the "gzip" program.
(1) Compress all the help files: "gzip doc/*.txt".
(2) Edit "doc/tags" and change the ".txt" to ".txt.gz": >
:%s=\(\t.*\.txt\)\t=\1.gz\t=
(3) Add this line to your vimrc: >
set helpfile={dirname}/help.txt.gz
Where {dirname} is the directory where the help files are. The |gzip| plugin
will take care of decompressing the files.
You must make sure that $VIMRUNTIME is set to where the other Vim files are,
when they are not in the same location as the compressed "doc" directory. See
|$VIMRUNTIME|.
==============================================================================
Executing shell commands in a window *shell-window*
There have been questions for the possibility to execute a shell in a window
inside Vim. The answer: you can't! Including this would add a lot of code to
Vim, which is a good reason not to do this. After all, Vim is an editor, it
is not supposed to do non-editing tasks. However, to get something like this,
you might try splitting your terminal screen or display window with the
"splitvt" program. You can probably find it on some ftp server. The person
that knows more about this is Sam Lantinga <slouken@cs.ucdavis.edu>.
An alternative is the "window" command, found on BSD Unix systems, which
supports multiple overlapped windows. Or the "screen" program, found at
www.uni-erlangen.de, which supports a stack of windows.
==============================================================================
Hex editing *hex-editing* *using-xxd*
See section |23.4| of the user manual.
If one has a particular extension that one uses for binary files (such as exe,
bin, etc), you may find it helpful to automate the process with the following
bit of autocmds for your <.vimrc>. Change that "*.bin" to whatever
comma-separated list of extension(s) you find yourself wanting to edit: >
" vim -b : edit binary using xxd-format!
augroup Binary
au!
au BufReadPre *.bin let &bin=1
au BufReadPost *.bin if &bin | %!xxd
au BufReadPost *.bin set ft=xxd | endif
au BufWritePre *.bin if &bin | %!xxd -r
au BufWritePre *.bin endif
au BufWritePost *.bin if &bin | %!xxd
au BufWritePost *.bin set nomod | endif
augroup END
==============================================================================
Using <> notation in autocommands *autocmd-<>*
The <> notation is not recognized in the argument of an :autocmd. To avoid
having to use special characters, you could use a self-destroying mapping to
get the <> notation and then call the mapping from the autocmd. Example:
*map-self-destroy* >
" This is for automatically adding the name of the file to the menu list.
" It uses a self-destroying mapping!
" 1. use a line in the buffer to convert the 'dots' in the file name to \.
" 2. store that in register '"'
" 3. add that name to the Buffers menu list
" WARNING: this does have some side effects, like overwriting the
" current register contents and removing any mapping for the "i" command.
"
autocmd BufNewFile,BufReadPre * nmap i :nunmap i<CR>O<C-R>%<Esc>:.g/\./s/\./\\./g<CR>0"9y$u:menu Buffers.<C-R>9 :buffer <C-R>%<C-V><CR><CR>
autocmd BufNewFile,BufReadPre * normal i
Another method, perhaps better, is to use the ":execute" command. In the
string you can use the <> notation by preceding it with a backslash. Don't
forget to double the number of existing backslashes and put a backslash before
'"'.
>
autocmd BufNewFile,BufReadPre * exe "normal O\<C-R>%\<Esc>:.g/\\./s/\\./\\\\./g\<CR>0\"9y$u:menu Buffers.\<C-R>9 :buffer \<C-R>%\<C-V>\<CR>\<CR>"
For a real buffer menu, user functions should be used (see |:function|), but
then the <> notation isn't used, which defeats using it as an example here.
vim:tw=78:ts=8:ft=help:norl:

3441
runtime/doc/todo.txt Normal file
View File

File diff suppressed because it is too large Load Diff

277
runtime/doc/uganda.txt Normal file
View File

@@ -0,0 +1,277 @@
*uganda.txt* For Vim version 7.0aa. Last change: 2004 May 12
VIM REFERENCE MANUAL by Bram Moolenaar
*uganda* *Uganda* *copying* *copyright* *license*
SUMMARY
*iccf* *ICCF*
Vim is Charityware. You can use and copy it as much as you like, but you are
encouraged to make a donation for needy children in Uganda. Please see |kcc|
below or visit the ICCF web site, available at these URLs:
http://iccf-holland.org/
http://www.vim.org/iccf/
You can also sponsor the development of Vim. Vim sponsors can vote for
features. See |sponsor|.
The Open Publication License applies to the Vim documentation, see
|manual-copyright|.
=== begin of license ===
VIM LICENSE
I) There are no restrictions on distributing unmodified copies of Vim except
that they must include this license text. You can also distribute
unmodified parts of Vim, likewise unrestricted except that they must
include this license text. You are also allowed to include executables
that you made from the unmodified Vim sources, plus your own usage
examples and Vim scripts.
II) It is allowed to distribute a modified (or extended) version of Vim,
including executables and/or source code, when the following four
conditions are met:
1) This license text must be included unmodified.
2) The modified Vim must be distributed in one of the following five ways:
a) If you make changes to Vim yourself, you must clearly describe in
the distribution how to contact you. When the maintainer asks you
(in any way) for a copy of the modified Vim you distributed, you
must make your changes, including source code, available to the
maintainer without fee. The maintainer reserves the right to
include your changes in the official version of Vim. What the
maintainer will do with your changes and under what license they
will be distributed is negotiable. If there has been no negotiation
then this license, or a later version, also applies to your changes.
The current maintainer is Bram Moolenaar <Bram@vim.org>. If this
changes it will be announced in appropriate places (most likely
vim.sf.net, www.vim.org and/or comp.editors). When it is completely
impossible to contact the maintainer, the obligation to send him
your changes ceases. Once the maintainer has confirmed that he has
received your changes they will not have to be sent again.
b) If you have received a modified Vim that was distributed as
mentioned under a) you are allowed to further distribute it
unmodified, as mentioned at I). If you make additional changes the
text under a) applies to those changes.
c) Provide all the changes, including source code, with every copy of
the modified Vim you distribute. This may be done in the form of a
context diff. You can choose what license to use for new code you
add. The changes and their license must not restrict others from
making their own changes to the official version of Vim.
d) When you have a modified Vim which includes changes as mentioned
under c), you can distribute it without the source code for the
changes if the following three conditions are met:
- The license that applies to the changes permits you to distribute
the changes to the Vim maintainer without fee or restriction, and
permits the Vim maintainer to include the changes in the official
version of Vim without fee or restriction.
- You keep the changes for at least three years after last
distributing the corresponding modified Vim. When the maintainer
or someone who you distributed the modified Vim to asks you (in
any way) for the changes within this period, you must make them
available to him.
- You clearly describe in the distribution how to contact you. This
contact information must remain valid for at least three years
after last distributing the corresponding modified Vim, or as long
as possible.
e) When the GNU General Public License (GPL) applies to the changes,
you can distribute the modified Vim under the GNU GPL version 2 or
any later version.
3) A message must be added, at least in the output of the ":version"
command and in the intro screen, such that the user of the modified Vim
is able to see that it was modified. When distributing as mentioned
under 2)e) adding the message is only required for as far as this does
not conflict with the license used for the changes.
4) The contact information as required under 2)a) and 2)d) must not be
removed or changed, except that the person himself can make
corrections.
III) If you distribute a modified version of Vim, you are encouraged to use
the Vim license for your changes and make them available to the
maintainer, including the source code. The preferred way to do this is
by e-mail or by uploading the files to a server and e-mailing the URL.
If the number of changes is small (e.g., a modified Makefile) e-mailing a
context diff will do. The e-mail address to be used is
<maintainer@vim.org>
IV) It is not allowed to remove this license from the distribution of the Vim
sources, parts of it or from a modified version. You may use this
license for previous Vim releases instead of the license that they came
with, at your option.
=== end of license ===
Note:
- If you are happy with Vim, please express that by reading the rest of this
file and consider helping needy children in Uganda.
- If you want to support further Vim development consider becoming a
|sponsor|.
- According to Richard Stallman the Vim license is GNU GPL compatible.
A few minor changes have been made since he checked it, but that should not
make a difference.
- If you link Vim with a library that goes under the GNU GPL, this limits
further distribution to the GNU GPL. Also when you didn't actually change
anything in Vim.
- Once a change is included that goes under the GNU GPL, this forces all
further changes to also be made under the GNU GPL or a compatible license.
- If you distribute a modified version of Vim, you can include your name and
contact information with the "--with-modified-by" configure argument or the
MODIFIED_BY define.
==============================================================================
Kibaale Children's Centre *kcc*
Kibaale Children's Centre (KCC) is located in Kibaale, a small town in the
south of Uganda, near Tanzania, in East Africa. The area is known as Rakai
District. The population is mostly farmers. Although people are poor, there
is enough food. But this district is suffering from AIDS more than any other
part of the world. Some say that it started there. Estimations are that 10
to 30% of the Ugandans are infected with HIV. Because parents die, there are
many orphans. In this district about 60,000 children have lost one or both
parents, out of a population of 350,000. And this is still continuing.
The children need a lot of help. The KCC is working hard to provide the needy
with food, medical care and education. Food and medical care to keep them
healthy now, and education so that they can take care of themselves in the
future. KCC works on a Christian base, but help is given to children of any
religion.
The key to solving the problems in this area is education. This has been
neglected in the past years with president Idi Amin and the following civil
wars. Now that the government is stable again, the children and parents have
to learn how to take care of themselves and how to avoid infections. There is
also help for people who are ill and hungry, but the primary goal is to
prevent people from getting ill and to teach them how to grow healthy food.
Most of the orphans are living in an extended family. An uncle or older
sister is taking care of them. Because these families are big and the income
(if any) is low, a child is lucky if it gets healthy food. Clothes, medical
care and schooling is beyond its reach. To help these needy children, a
sponsorship program was put into place. A child can be financially adopted.
For a few dollars a month KCC sees to it that the child gets indispensable
items, is healthy, goes to school and KCC takes care of anything else that
needs to be done for the child and the family that supports it.
Besides helping the child directly, the environment where the child grows up
needs to be improved. KCC helps schools to improve their teaching methods.
There is a demonstration school at the centre and teacher trainings are given.
Health workers are being trained, hygiene education is carried out and
households are stimulated to build a proper latrine. I helped setting up a
production site for cement slabs. These are used to build a good latrine.
They are sold below cost price.
There is a small clinic at the project, which provides children and their
family with medical help. When needed, transport to a hospital is offered.
Immunization programs are carried out and help is provided when an epidemic is
breaking out (measles and cholera have been a problem).
Summer 1994 to summer 1995 I spent a whole year at the centre, working as a
volunteer. I have helped to expand the centre and worked in the area of water
and sanitation. I learned that the help that the KCC provides really helps.
Now that I'm back in Holland, I would like to continue supporting KCC. To do
this I'm raising funds and organizing the sponsorship program. Please
consider one of these possibilities:
1. Sponsor a child in primary school: 17 euro a month (or more).
2. Sponsor a child in secondary school: 25 euro a month (or more).
3. Sponsor the clinic: Any amount a month or quarter
4. A one-time donation
Compared with other organizations that do child sponsorship the amounts are
very low. This is because the money goes directly to the centre. Less than
5% is used for administration. This is possible because this is a small
organization that works with volunteers. If you would like to sponsor a
child, you should have the intention to do this for at least one year.
How do you know that the money will be spent right? First of all you have my
personal guarantee as the author of Vim. I trust the people that are working
at the centre, I know them personally. Further more, the centre is
co-sponsored and inspected by World Vision, Save the Children Fund and
International Child Care Fund. The centre is visited about once a year to
check the progress (at our own cost). I have visited the centre myself in
1996, 1998, 2000, 2001 and 2003. The visit reports are on the ICCF web site.
If you have any further questions, send me e-mail: <Bram@vim.org>.
The address of the centre is:
Kibaale Children's Centre
p.o. box 1658
Masaka, Uganda, East Africa
Sending money:
Check the ICCF web site for the latest information! See |iccf| for the URL.
USA and Canada: Contact Kibaale Children's Fund (KCF) in Surrey, Canada. They
take care of the Canadian sponsors for the children in
Kibaale. You can send them a one time donation directly.
Please send me a note so that know what has been donated
because of Vim. Ask KCF for information about sponsorship.
Kibaale Children's Fund c/o Pacific Academy
10238-168 Street
Surrey, B.C. V4N 1Z4
Canada
Phone: 604-581-5353
If you make a donation to Kibaale Children's Fund (KCF) you
will receive a tax receipt which can be submitted with your
tax return (under the Free Trade Agreement tax receipts issued
by an organization registered in Canada are fully accepted by
the IRS in the USA, with a few conditions).
Holland: Transfer to the account of "Stichting ICCF Holland" in Venlo.
This will allow for tax deduction (if you live in Holland)!
Postbank, nr. 4548774
Germany: It is possible to make donations that allow for a tax return.
Check the ICCF web site for the latest information:
http://iccf-holland.org/germany.html
World: Use a postal money order. That should be possible from any
country, mostly from the post office. Use this name (which is
in my passport): "Abraham Moolenaar". Use Euro for the
currency if possible.
Europe: Use a bank transfer if possible. Your bank should have a form
that you can use for this. See "Others" below for the swift
code and IBAN number.
Any other method should work. Ask for information about
sponsorship.
Credit Card: You can use PayPal to send money with a Credit card. This is
the most widely used Internet based payment system. It's
really simple to use. Use this link to find more info:
https://www.paypal.com/affil/pal=Bram%40moolenaar.net
The e-mail address for sending the money to is:
Bram@iccf-holland.org
For amounts above $150 sending a cheque is preferred.
Others: Transfer to one of these accounts if possible:
Postbank, account 4548774
Swift code: INGB NL 2A
IBAN: NL47 PSTB 0004 5487 74
under the name "stichting ICCF Holland", Venlo
If that doesn't work:
Rabobank Venlo, account 3765.05.117
Swift code: RABO NL 2U
under the name "Bram Moolenaar", Venlo
Otherwise, send a cheque in euro or US dollars to the address
below. Minimal amount: $70 (my bank does not accept smaller
amounts for foreign cheques, sorry)
Address to send cheques to:
stichting ICCF Holland
Bram Moolenaar
Clematisstraat 30
5925 BE Venlo
The Netherlands
vim:tw=78:ts=8:ft=help:norl:

117
runtime/doc/undo.txt Normal file
View File

@@ -0,0 +1,117 @@
*undo.txt* For Vim version 7.0aa. Last change: 2003 Oct 21
VIM REFERENCE MANUAL by Bram Moolenaar
Undo and redo *undo-redo*
The basics are explained in section |02.5| of the user manual.
1. Undo and redo commands |undo-commands|
2. Two ways of undo |undo-two-ways|
3. Remarks about undo |undo-remarks|
==============================================================================
1. Undo and redo commands *undo-commands*
<Undo> or *undo* *<Undo>* *u*
u Undo [count] changes. {Vi: only one level}
*:u* *:un* *:undo*
:u[ndo] Undo one change. {Vi: only one level}
*CTRL-R*
CTRL-R Redo [count] changes which were undone. {Vi: redraw
screen}
*:red* *:redo* *redo*
:red[o] Redo one change which was undone. {Vi: no redo}
*U*
U Undo all latest changes on one line. {Vi: while not
moved off of it}
The last changes are remembered. You can use the undo and redo commands above
to revert the text to how it was before each change. You can also apply the
changes again, getting back the text before the undo.
The "U" command is treated by undo/redo just like any other command. Thus a
"u" command undoes a "U" command and a 'CTRL-R' command redoes it again. When
mixing "U", "u" and 'CTRL-R' you will notice that the "U" command will
restore the situation of a line to before the previous "U" command. This may
be confusing. Try it out to get used to it.
The "U" command will always mark the buffer as changed. When "U" changes the
buffer back to how it was without changes, it is still considered changed.
Use "u" to undo changes until the buffer becomes unchanged.
==============================================================================
2. Two ways of undo *undo-two-ways*
How undo and redo commands work depends on the 'u' flag in 'cpoptions'.
There is the Vim way ('u' excluded) and the vi-compatible way ('u' included).
In the Vim way, "uu" undoes two changes. In the Vi-compatible way, "uu" does
nothing (undoes an undo).
'u' excluded, the Vim way:
You can go back in time with the undo command. You can then go forward again
with the redo command. If you make a new change after the undo command,
the redo will not be possible anymore.
'u' included, the Vi-compatible way:
The undo command undoes the previous change, and also the previous undo command.
The redo command repeats the previous undo command. It does NOT repeat a
change command, use "." for that.
Examples Vim way Vi-compatible way ~
"uu" two times undo no-op
"u CTRL-R" no-op two times undo
Rationale: Nvi uses the "." command instead of CTRL-R. Unfortunately, this
is not Vi compatible. For example "dwdwu." in Vi deletes two
words, in Nvi it does nothing.
==============================================================================
3. Remarks about undo *undo-remarks*
The number of changes that are remembered is set with the 'undolevels' option.
If it is zero, the Vi-compatible way is always used. If it is negative no
undo is possible. Use this if you are running out of memory.
Marks for the buffer ('a to 'z) are also saved and restored, together with the
text. {Vi does this a little bit different}
When all changes have been undone, the buffer is not considered to be changed.
It is then possible to exit Vim with ":q" instead of ":q!" {not in Vi}. Note
that this is relative to the last write of the file. Typing "u" after ":w"
actually changes the buffer, compared to what was written, so the buffer is
considered changed then.
When manual |folding| is being used, the folds are not saved and restored.
Only changes completely within a fold will keep the fold as it was, because
the first and last line of the fold don't change.
The numbered registers can also be used for undoing deletes. Each time you
delete text, it is put into register "1. The contents of register "1 are
shifted to "2, etc. The contents of register "9 are lost. You can now get
back the most recent deleted text with the put command: '"1P'. (also, if the
deleted text was the result of the last delete or copy operation, 'P' or 'p'
also works as this puts the contents of the unnamed register). You can get
back the text of three deletes ago with '"3P'.
*redo-register*
If you want to get back more than one part of deleted text, you can use a
special feature of the repeat command ".". It will increase the number of the
register used. So if you first do ""1P", the following "." will result in a
'"2P'. Repeating this will result in all numbered registers being inserted.
Example: If you deleted text with 'dd....' it can be restored with
'"1P....'.
If you don't know in which register the deleted text is, you can use the
:display command. An alternative is to try the first register with '"1P', and
if it is not what you want do 'u.'. This will remove the contents of the
first put, and repeat the put command for the second register. Repeat the
'u.' until you got what you want.
vim:tw=78:ts=8:ft=help:norl:

180
runtime/doc/usr_01.txt Normal file
View File

@@ -0,0 +1,180 @@
*usr_01.txt* For Vim version 7.0aa. Last change: 2004 May 01
VIM USER MANUAL - by Bram Moolenaar
About the manuals
This chapter introduces the manuals available with Vim. Read this to know the
conditions under which the commands are explained.
|01.1| Two manuals
|01.2| Vim installed
|01.3| Using the Vim tutor
|01.4| Copyright
Next chapter: |usr_02.txt| The first steps in Vim
Table of contents: |usr_toc.txt|
==============================================================================
*01.1* Two manuals
The Vim documentation consists of two parts:
1. The User manual
Task oriented explanations, from simple to complex. Reads from start to
end like a book.
2. The Reference manual
Precise description of how everything in Vim works.
The notation used in these manuals is explained here: |notation|
JUMPING AROUND
The text contains hyperlinks between the two parts, allowing you to quickly
jump between the description of an editing task and a precise explanation of
the commands and options used for it. Use these two commands:
Press CTRL-] to jump to a subject under the cursor.
Press CTRL-O to jump back (repeat to go further back).
Many links are in vertical bars, like this: |bars|. An option name, like
'number', a command in double quotes like ":write" and any other word can also
be used as a link. Try it out: Move the cursor to CTRL-] and press CTRL-]
on it.
Other subjects can be found with the ":help" command, see |help.txt|.
==============================================================================
*01.2* Vim installed
Most of the manuals assume that Vim has been properly installed. If you
didn't do that yet, or if Vim doesn't run properly (e.g., files can't be found
or in the GUI the menus do not show up) first read the chapter on
installation: |usr_90.txt|.
*not-compatible*
The manuals often assume you are using Vim with Vi-compatibility switched
off. For most commands this doesn't matter, but sometimes it is important,
e.g., for multi-level undo. An easy way to make sure you are using the right
setup, copy the example vimrc file. By doing this inside Vim you don't have
to check out where it is located. How to do this depends on the system you
are using:
Unix: >
:!cp -i $VIMRUNTIME/vimrc_example.vim ~/.vimrc
MS-DOS, MS-Windows, OS/2: >
:!copy $VIMRUNTIME/vimrc_example.vim $VIM/_vimrc
Amiga: >
:!copy $VIMRUNTIME/vimrc_example.vim $VIM/.vimrc
If the file already exists you probably want to keep it.
If you start Vim now, the 'compatible' option should be off. You can check it
with this command: >
:set compatible?
If it responds with "nocompatible" you are doing well. If the response is
"compatible" you are in trouble. You will have to find out why the option is
still set. Perhaps the file you wrote above is not found. Use this command
to find out: >
:scriptnames
If your file is not in the list, check its location and name. If it is in the
list, there must be some other place where the 'compatible' option is switched
back on.
For more info see |vimrc| and |compatible-default|.
Note:
This manual is about using Vim in the normal way. There is an
alternative called "evim" (easy Vim). This is still Vim, but used in
a way that resembles a click-and-type editor like Notepad. It always
stays in Insert mode, thus it feels very different. It is not
explained in the user manual, since it should be mostly self
explanatory. See |evim-keys| for details.
==============================================================================
*01.3* Using the Vim tutor *tutor* *vimtutor*
Instead of reading the text (boring!) you can use the vimtutor to learn your
first Vim commands. This is a 30 minute tutorial that teaches the most basic
Vim functionality hands-on.
On Unix and MS-Windows, if Vim has been properly installed, you can start it
from the shell:
>
vimtutor
This will make a copy of the tutor file, so that you can edit it without
the risk of damaging the original.
There are a few translated versions of the tutor. To find out if yours is
available, use the two-letter language code. For French: >
vimtutor fr
For OpenVMS, if Vim has been properly installed, you can start vimtutor from a
VMS prompt with: >
@VIM:vimtutor
Optionally add the two-letter language code as above.
On other systems, you have to do a little work:
1. Copy the tutor file. You can do this with Vim (it knows where to find it):
>
vim -u NONE -c 'e $VIMRUNTIME/tutor/tutor' -c 'w! TUTORCOPY' -c 'q'
<
This will write the file "TUTORCOPY" in the current directory. To use a
translated version of the tutor, append the two-letter language code to the
filename. For French:
>
vim -u NONE -c 'e $VIMRUNTIME/tutor/tutor.fr' -c 'w! TUTORCOPY' -c 'q'
<
2. Edit the copied file with Vim:
>
vim -u NONE -c "set nocp" TUTORCOPY
<
The extra arguments make sure Vim is started in a good mood.
3. Delete the copied file when you are finished with it:
>
del TUTORCOPY
<
==============================================================================
*01.4* Copyright *manual-copyright*
The Vim user manual and reference manual are Copyright (c) 1988-2003 by Bram
Moolenaar. This material may be distributed only subject to the terms and
conditions set forth in the Open Publication License, v1.0 or later. The
latest version is presently available at:
http://www.opencontent.org/opl.shtml
People who contribute to the manuals must agree with the above copyright
notice.
*frombook*
Parts of the user manual come from the book "Vi IMproved - Vim" by Steve
Oualline (published by New Riders Publishing, ISBN: 0735710015). The Open
Publication License applies to this book. Only selected parts are included
and these have been modified (e.g., by removing the pictures, updating the
text for Vim 6.0 and fixing mistakes). The omission of the |frombook| tag
does not mean that the text does not come from the book.
Many thanks to Steve Oualline and New Riders for creating this book and
publishing it under the OPL! It has been a great help while writing the user
manual. Not only by providing literal text, but also by setting the tone and
style.
If you make money through selling the manuals, you are strongly encouraged to
donate part of the profit to help AIDS victims in Uganda. See |iccf|.
==============================================================================
Next chapter: |usr_02.txt| The first steps in Vim
Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:

504
runtime/doc/usr_02.txt Normal file
View File

@@ -0,0 +1,504 @@
*usr_02.txt* For Vim version 7.0aa. Last change: 2004 Jun 08
VIM USER MANUAL - by Bram Moolenaar
The first steps in Vim
This chapter provides just enough information to edit a file with Vim. Not
well or fast, but you can edit. Take some time to practice with these
commands, they form the base for what follows.
|02.1| Running Vim for the First Time
|02.2| Inserting text
|02.3| Moving around
|02.4| Deleting characters
|02.5| Undo and Redo
|02.6| Other editing commands
|02.7| Getting out
|02.8| Finding help
Next chapter: |usr_03.txt| Moving around
Previous chapter: |usr_01.txt| About the manuals
Table of contents: |usr_toc.txt|
==============================================================================
*02.1* Running Vim for the First Time
To start Vim, enter this command: >
gvim file.txt
In UNIX you can type this at any command prompt. If you are running Microsoft
Windows, open an MS-DOS prompt window and enter the command.
In either case, Vim starts editing a file called file.txt. Because this
is a new file, you get a blank window. This is what your screen will look
like:
+---------------------------------------+
|# |
|~ |
|~ |
|~ |
|~ |
|"file.txt" [New file] |
+---------------------------------------+
('#" is the cursor position.)
The tilde (~) lines indicate lines not in the file. In other words, when Vim
runs out of file to display, it displays tilde lines. At the bottom of the
screen, a message line indicates the file is named file.txt and shows that you
are creating a new file. The message information is temporary and other
information overwrites it.
THE VIM COMMAND
The gvim command causes the editor to create a new window for editing. If you
use this command: >
vim file.txt
the editing occurs inside your command window. In other words, if you are
running inside an xterm, the editor uses your xterm window. If you are using
an MS-DOS command prompt window under Microsoft Windows, the editing occurs
inside this window. The text in the window will look the same for both
versions, but with gvim you have extra features, like a menu bar. More about
that later.
==============================================================================
*02.2* Inserting text
The Vim editor is a modal editor. That means that the editor behaves
differently, depending on which mode you are in. The two basic modes are
called Normal mode and Insert mode. In Normal mode the characters you type
are commands. In Insert mode the characters are inserted as text.
Since you have just started Vim it will be in Normal mode. To start Insert
mode you type the "i" command (i for Insert). Then you can enter
the text. It will be inserted into the file. Do not worry if you make
mistakes; you can correct them later. To enter the following programmer's
limerick, this is what you type: >
iA very intelligent turtle
Found programming UNIX a hurdle
After typing "turtle" you press the <Enter> key to start a new line. Finally
you press the <Esc> key to stop Insert mode and go back to Normal mode. You
now have two lines of text in your Vim window:
+---------------------------------------+
|A very intelligent turtle |
|Found programming UNIX a hurdle |
|~ |
|~ |
| |
+---------------------------------------+
WHAT IS THE MODE?
To be able to see what mode you are in, type this command: >
:set showmode
You will notice that when typing the colon Vim moves the cursor to the last
line of the window. That's where you type colon commands (commands that start
with a colon). Finish this command by pressing the <Enter> key (all commands
that start with a colon are finished this way).
Now, if you type the "i" command Vim will display --INSERT-- at the bottom
of the window. This indicates you are in Insert mode.
+---------------------------------------+
|A very intelligent turtle |
|Found programming UNIX a hurdle |
|~ |
|~ |
|-- INSERT -- |
+---------------------------------------+
If you press <Esc> to go back to Normal mode the last line will be made blank.
GETTING OUT OF TROUBLE
One of the problems for Vim novices is mode confusion, which is caused by
forgetting which mode you are in or by accidentally typing a command that
switches modes. To get back to Normal mode, no matter what mode you are in,
press the <Esc> key. Sometimes you have to press it twice. If Vim beeps back
at you, you already are in Normal mode.
==============================================================================
*02.3* Moving around
After you return to Normal mode, you can move around by using these keys:
h left *hjkl*
j down
k up
l right
At first, it may appear that these commands were chosen at random. After all,
who ever heard of using l for right? But actually, there is a very good
reason for these choices: Moving the cursor is the most common thing you do in
an editor, and these keys are on the home row of your right hand. In other
words, these commands are placed where you can type them the fastest
(especially when you type with ten fingers).
Note:
You can also move the cursor by using the arrow keys. If you do,
however, you greatly slow down your editing because to press the arrow
keys, you must move your hand from the text keys to the arrow keys.
Considering that you might be doing it hundreds of times an hour, this
can take a significant amount of time.
Also, there are keyboards which do not have arrow keys, or which
locate them in unusual places; therefore, knowing the use of the hjkl
keys helps in those situations.
One way to remember these commands is that h is on the left, l is on the
right and j points down. In a picture: >
k
h l
j
The best way to learn these commands is by using them. Use the "i" command to
insert some more lines of text. Then use the hjkl keys to move around and
insert a word somewhere. Don't forget to press <Esc> to go back to Normal
mode. The |vimtutor| is also a nice way to learn by doing.
For Japanese users, Hiroshi Iwatani suggested using this:
Komsomolsk
^
|
Huan Ho <--- ---> Los Angeles
(Yellow river) |
v
Java (the island, not the programming language)
==============================================================================
*02.4* Deleting characters
To delete a character, move the cursor over it and type "x". (This is a
throwback to the old days of the typewriter, when you deleted things by typing
xxxx over them.) Move the cursor to the beginning of the first line, for
example, and type xxxxxxx (seven x's) to delete "A very ". The result should
look like this:
+---------------------------------------+
|intelligent turtle |
|Found programming UNIX a hurdle |
|~ |
|~ |
| |
+---------------------------------------+
Now you can insert new text, for example by typing: >
iA young <Esc>
This begins an insert (the i), inserts the words "A young", and then exits
insert mode (the final <Esc>). The result:
+---------------------------------------+
|A young intelligent turtle |
|Found programming UNIX a hurdle |
|~ |
|~ |
| |
+---------------------------------------+
DELETING A LINE
To delete a whole line use the "dd" command. The following line will
then move up to fill the gap:
+---------------------------------------+
|Found programming UNIX a hurdle |
|~ |
|~ |
|~ |
| |
+---------------------------------------+
DELETING A LINE BREAK
In Vim you can join two lines together, which means that the line break
between them is deleted. The "J" command does this.
Take these two lines:
A young intelligent ~
turtle ~
Move the cursor to the first line and press "J":
A young intelligent turtle ~
==============================================================================
*02.5* Undo and Redo
Suppose you delete too much. Well, you can type it in again, but an easier
way exists. The "u" command undoes the last edit. Take a look at this in
action: After using "dd" to delete the first line, "u" brings it back.
Another one: Move the cursor to the A in the first line:
A young intelligent turtle ~
Now type xxxxxxx to delete "A young". The result is as follows:
intelligent turtle ~
Type "u" to undo the last delete. That delete removed the g, so the undo
restores the character.
g intelligent turtle ~
The next u command restores the next-to-last character deleted:
ng intelligent turtle ~
The next u command gives you the u, and so on:
ung intelligent turtle ~
oung intelligent turtle ~
young intelligent turtle ~
young intelligent turtle ~
A young intelligent turtle ~
Note:
If you type "u" twice, and the result is that you get the same text
back, you have Vim configured to work Vi compatible. Look here to fix
this: |not-compatible|.
This text assumes you work "The Vim Way". You might prefer to use
the good old Vi way, but you will have to watch out for small
differences in the text then.
REDO
If you undo too many times, you can press CTRL-R (redo) to reverse the
preceding command. In other words, it undoes the undo. To see this in
action, press CTRL-R twice. The character A and the space after it disappear:
young intelligent turtle ~
There's a special version of the undo command, the "U" (undo line) command.
The undo line command undoes all the changes made on the last line that was
edited. Typing this command twice cancels the preceding "U".
A very intelligent turtle ~
xxxx Delete very
A intelligent turtle ~
xxxxxx Delete turtle
A intelligent ~
Restore line with "U"
A very intelligent turtle ~
Undo "U" with "u"
A intelligent ~
The "U" command is a change by itself, which the "u" command undoes and CTRL-R
redoes. This might be a bit confusing. Don't worry, with "u" and CTRL-R you
can go to any of the situations you had.
==============================================================================
*02.6* Other editing commands
Vim has a large number of commands to change the text. See |Q_in| and below.
Here are a few often used ones.
APPENDING
The "i" command inserts a character before the character under the cursor.
That works fine; but what happens if you want to add stuff to the end of the
line? For that you need to insert text after the cursor. This is done with
the "a" (append) command.
For example, to change the line
and that's not saying much for the turtle. ~
to
and that's not saying much for the turtle!!! ~
move the cursor over to the dot at the end of the line. Then type "x" to
delete the period. The cursor is now positioned at the end of the line on the
e in turtle. Now type >
a!!!<Esc>
to append three exclamation points after the e in turtle:
and that's not saying much for the turtle!!! ~
OPENING UP A NEW LINE
The "o" command creates a new, empty line below the cursor and puts Vim in
Insert mode. Then you can type the text for the new line.
Suppose the cursor is somewhere in the first of these two lines:
A very intelligent turtle ~
Found programming UNIX a hurdle ~
If you now use the "o" command and type new text: >
oThat liked using Vim<Esc>
The result is:
A very intelligent turtle ~
That liked using Vim ~
Found programming UNIX a hurdle ~
The "O" command (uppercase) opens a line above the cursor.
USING A COUNT
Suppose you want to move up nine lines. You can type "kkkkkkkkk" or you can
enter the command "9k". In fact, you can precede many commands with a number.
Earlier in this chapter, for instance, you added three exclamation points to
the end of a line by typing "a!!!<Esc>". Another way to do this is to use the
command "3a!<Esc>". The count of 3 tells the command that follows to triple
its effect. Similarly, to delete three characters, use the command "3x". The
count always comes before the command it applies to.
==============================================================================
*02.7* Getting out
To exit, use the "ZZ" command. This command writes the file and exits.
Note:
Unlike many other editors, Vim does not automatically make a backup
file. If you type "ZZ", your changes are committed and there's no
turning back. You can configure the Vim editor to produce backup
files, see |07.4|.
DISCARDING CHANGES
Sometimes you will make a sequence of changes and suddenly realize you were
better off before you started. Not to worry; Vim has a
quit-and-throw-things-away command. It is: >
:q!
Don't forget to press <Enter> to finish the command.
For those of you interested in the details, the three parts of this command
are the colon (:), which enters Command-line mode; the q command, which tells
the editor to quit; and the override command modifier (!).
The override command modifier is needed because Vim is reluctant to throw
away changes. If you were to just type ":q", Vim would display an error
message and refuse to exit:
E37: No write since last change (use ! to override) ~
By specifying the override, you are in effect telling Vim, "I know that what
I'm doing looks stupid, but I'm a big boy and really want to do this."
If you want to continue editing with Vim: The ":e!" command reloads the
original version of the file.
==============================================================================
*02.8* Finding help
Everything you always wanted to know can be found in the Vim help files.
Don't be afraid to ask!
To get generic help use this command: >
:help
You could also use the first function key <F1>. If your keyboard has a <Help>
key it might work as well.
If you don't supply a subject, ":help" displays the general help window.
The creators of Vim did something very clever (or very lazy) with the help
system: They made the help window a normal editing window. You can use all
the normal Vim commands to move through the help information. Therefore h, j,
k, and l move left, down, up and right.
To get out of the help window, use the same command you use to get out of
the editor: "ZZ". This will only close the help window, not exit Vim.
As you read the help text, you will notice some text enclosed in vertical bars
(for example, |help|). This indicates a hyperlink. If you position the
cursor anywhere between the bars and press CTRL-] (jump to tag), the help
system takes you to the indicated subject. (For reasons not discussed here,
the Vim terminology for a hyperlink is tag. So CTRL-] jumps to the location
of the tag given by the word under the cursor.)
After a few jumps, you might want to go back. CTRL-T (pop tag) takes you
back to the preceding position. CTRL-O (jump to older position) also works
nicely here.
At the top of the help screen, there is the notation *help.txt*. This name
between "*" characters is used by the help system to define a tag (hyperlink
destination).
See |29.1| for details about using tags.
To get help on a given subject, use the following command: >
:help {subject}
To get help on the "x" command, for example, enter the following: >
:help x
To find out how to delete text, use this command: >
:help deleting
To get a complete index of all Vim commands, use the following command: >
:help index
When you need to get help for a control character command (for example,
CTRL-A), you need to spell it with the prefix "CTRL-". >
:help CTRL-A
The Vim editor has many different modes. By default, the help system displays
the normal-mode commands. For example, the following command displays help
for the normal-mode CTRL-H command: >
:help CTRL-H
To identify other modes, use a mode prefix. If you want the help for the
insert-mode version of a command, use "i_". For CTRL-H this gives you the
following command: >
:help i_CTRL-H
When you start the Vim editor, you can use several command-line arguments.
These all begin with a dash (-). To find what the -t argument does, for
example, use the command: >
:help -t
The Vim editor has a number of options that enable you to configure and
customize the editor. If you want help for an option, you need to enclose it
in single quotation marks. To find out what the 'number' option does, for
example, use the following command: >
:help 'number'
The table with all mode prefixes can be found here: |help-context|.
Special keys are enclosed in angle brackets. To find help on the up-arrow key
in Insert mode, for instance, use this command: >
:help i_<Up>
If you see an error message that you don't understand, for example:
E37: No write since last change (use ! to override) ~
You can use the error ID at the start to find help about it: >
:help E37
==============================================================================
Next chapter: |usr_03.txt| Moving around
Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:

654
runtime/doc/usr_03.txt Normal file
View File

@@ -0,0 +1,654 @@
*usr_03.txt* For Vim version 7.0aa. Last change: 2004 Jan 17
VIM USER MANUAL - by Bram Moolenaar
Moving around
Before you can insert or delete text the cursor has to be moved to the right
place. Vim has a large number of commands to position the cursor. This
chapter shows you how to use the most important ones. You can find a list of
these commands below |Q_lr|.
|03.1| Word movement
|03.2| Moving to the start or end of a line
|03.3| Moving to a character
|03.4| Matching a paren
|03.5| Moving to a specific line
|03.6| Telling where you are
|03.7| Scrolling around
|03.8| Simple searches
|03.9| Simple search patterns
|03.10| Using marks
Next chapter: |usr_04.txt| Making small changes
Previous chapter: |usr_02.txt| The first steps in Vim
Table of contents: |usr_toc.txt|
==============================================================================
*03.1* Word movement
To move the cursor forward one word, use the "w" command. Like most Vim
commands, you can use a numeric prefix to move past multiple words. For
example, "3w" moves three words. This figure shows how it works:
This is a line with example text ~
--->-->->----------------->
w w w 3w
Notice that "w" moves to the start of the next word if it already is at the
start of a word.
The "b" command moves backward to the start of the previous word:
This is a line with example text ~
<----<--<-<---------<---
b b b 2b b
There is also the "e" command that moves to the next end of a word and "ge",
which moves to the previous end of a word:
This is a line with example text ~
<- <--- -----> ---->
ge ge e e
If you are at the last word of a line, the "w" command will take you to the
first word in the next line. Thus you can use this to move through a
paragraph, much faster than using "l". "b" does the same in the other
direction.
A word ends at a non-word character, such as a ".", "-" or ")". To change
what Vim considers to be a word, see the 'iskeyword' option.
It is also possible to move by white-space separated WORDs. This is not a
word in the normal sense, that's why the uppercase is used. The commands for
moving by WORDs are also uppercase, as this figure shows:
ge b w e
<- <- ---> --->
This is-a line, with special/separated/words (and some more). ~
<----- <----- --------------------> ----->
gE B W E
With this mix of lowercase and uppercase commands, you can quickly move
forward and backward through a paragraph.
==============================================================================
*03.2* Moving to the start or end of a line
The "$" command moves the cursor to the end of a line. If your keyboard has
an <End> key it will do the same thing.
The "^" command moves to the first non-blank character of the line. The "0"
command (zero) moves to the very first character of the line. The <Home> key
does the same thing. In a picture:
^
<------------
.....This is a line with example text ~
<----------------- --------------->
0 $
(the "....." indicates blanks here)
The "$" command takes a count, like most movement commands. But moving to
the end of the line several times doesn't make sense. Therefore it causes the
editor to move to the end of another line. For example, "1$" moves you to
the end of the first line (the one you're on), "2$" to the end of the next
line, and so on.
The "0" command doesn't take a count argument, because the "0" would be
part of the count. Unexpectedly, using a count with "^" doesn't have any
effect.
==============================================================================
*03.3* Moving to a character
One of the most useful movement commands is the single-character search
command. The command "fx" searches forward in the line for the single
character x. Hint: "f" stands for "Find".
For example, you are at the beginning of the following line. Suppose you
want to go to the h of human. Just execute the command "fh" and the cursor
will be positioned over the h:
To err is human. To really foul up you need a computer. ~
---------->--------------->
fh fy
This also shows that the command "fy" moves to the end of the word really.
You can specify a count; therefore, you can go to the "l" of "foul" with
"3fl":
To err is human. To really foul up you need a computer. ~
--------------------->
3fl
The "F" command searches to the left:
To err is human. To really foul up you need a computer. ~
<---------------------
Fh
The "tx" command works like the "fx" command, except it stops one character
before the searched character. Hint: "t" stands for "To". The backward
version of this command is "Tx".
To err is human. To really foul up you need a computer. ~
<------------ ------------->
Th tn
These four commands can be repeated with ";". "," repeats in the other
direction. The cursor is never moved to another line. Not even when the
sentence continues.
Sometimes you will start a search, only to realize that you have typed the
wrong command. You type "f" to search backward, for example, only to realize
that you really meant "F". To abort a search, press <Esc>. So "f<Esc>" is an
aborted forward search and doesn't do anything. Note: <Esc> cancels most
operations, not just searches.
==============================================================================
*03.4* Matching a paren
When writing a program you often end up with nested () constructs. Then the
"%" command is very handy: It moves to the matching paren. If the cursor is
on a "(" it will move to the matching ")". If it's on a ")" it will move to
the matching "(".
%
<----->
if (a == (b * c) / d) ~
<---------------->
%
This also works for [] and {} pairs. (This can be defined with the
'matchpairs' option.)
When the cursor is not on a useful character, "%" will search forward to find
one. Thus if the cursor is at the start of the line of the previous example,
"%" will search forward and find the first "(". Then it moves to its match:
if (a == (b * c) / d) ~
---+---------------->
%
==============================================================================
*03.5* Moving to a specific line
If you are a C or C++ programmer, you are familiar with error messages such as
the following:
prog.c:33: j undeclared (first use in this function) ~
This tells you that you might want to fix something on line 33. So how do you
find line 33? One way is to do "9999k" to go to the top of the file and "32j"
to go down thirty two lines. It is not a good way, but it works. A much
better way of doing things is to use the "G" command. With a count, this
command positions you at the given line number. For example, "33G" puts you
on line 33. (For a better way of going through a compiler's error list, see
|usr_30.txt|, for information on the :make command.)
With no argument, "G" positions you at the end of the file. A quick way to
go to the start of a file use "gg". "1G" will do the same, but is a tiny bit
more typing.
| first line of a file ^
| text text text text |
| text text text text | gg
7G | text text text text |
| text text text text
| text text text text
V text text text text |
text text text text | G
text text text text |
last line of a file V
Another way to move to a line is using the "%" command with a count. For
example "50%" moves you to halfway the file. "90%" goes to near the end.
The previous assumes that you want to move to a line in the file, no matter if
it's currently visible or not. What if you want to move to one of the lines
you can see? This figure shows the three commands you can use:
+---------------------------+
H --> | text sample text |
| sample text |
| text sample text |
| sample text |
M --> | text sample text |
| sample text |
| text sample text |
| sample text |
L --> | text sample text |
+---------------------------+
Hints: "H" stands for Home, "M" for Middle and "L" for Last.
==============================================================================
*03.6* Telling where you are
To see where you are in a file, there are three ways:
1. Use the CTRL-G command. You get a message like this (assuming the 'ruler'
option is off):
"usr_03.txt" line 233 of 650 --35%-- col 45-52 ~
This shows the name of the file you are editing, the line number where the
cursor is, the total number of lines, the percentage of the way through
the file and the column of the cursor.
Sometimes you will see a split column number. For example, "col 2-9".
This indicates that the cursor is positioned on the second character, but
because character one is a tab, occupying eight spaces worth of columns,
the screen column is 9.
2. Set the 'number' option. This will display a line number in front of
every line: >
:set number
<
To switch this off again: >
:set nonumber
<
Since 'number' is a boolean option, prepending "no" to its name has the
effect of switching it off. A boolean option has only these two values,
it is either on or off.
Vim has many options. Besides the boolean ones there are options with
a numerical value and string options. You will see examples of this where
they are used.
3. Set the 'ruler' option. This will display the cursor position in the
lower right corner of the Vim window: >
:set ruler
Using the 'ruler' option has the advantage that it doesn't take much room,
thus there is more space for your text.
==============================================================================
*03.7* Scrolling around
The CTRL-U command scrolls down half a screen of text. Think of looking
through a viewing window at the text and moving this window up by half the
height of the window. Thus the window moves up over the text, which is
backward in the file. Don't worry if you have a little trouble remembering
which end is up. Most users have the same problem.
The CTRL-D command moves the viewing window down half a screen in the file,
thus scrolls the text up half a screen.
+----------------+
| some text |
| some text |
| some text |
+---------------+ | some text |
| some text | CTRL-U --> | |
| | | 123456 |
| 123456 | +----------------+
| 7890 |
| | +----------------+
| example | CTRL-D --> | 7890 |
+---------------+ | |
| example |
| example |
| example |
| example |
+----------------+
To scroll one line at a time use CTRL-E (scroll up) and CTRL-Y (scroll down).
Think of CTRL-E to give you one line Extra. (If you use MS-Windows compatible
key mappings CTRL-Y will redo a change instead of scroll.)
To scroll forward by a whole screen (except for two lines) use CTRL-F. The
other way is backward, CTRL-B is the command to use. Fortunately CTRL-F is
Forward and CTRL-B is Backward, that's easy to remember.
A common issue is that after moving down many lines with "j" your cursor is at
the bottom of the screen. You would like to see the context of the line with
the cursor. That's done with the "zz" command.
+------------------+ +------------------+
| some text | | some text |
| some text | | some text |
| some text | | some text |
| some text | zz --> | line with cursor |
| some text | | some text |
| some text | | some text |
| line with cursor | | some text |
+------------------+ +------------------+
The "zt" command puts the cursor line at the top, "zb" at the bottom. There
are a few more scrolling commands, see |Q_sc|. To always keep a few lines of
context around the cursor, use the 'scrolloff' option.
==============================================================================
*03.8* Simple searches
To search for a string, use the "/string" command. To find the word include,
for example, use the command: >
/include
You will notice that when you type the "/" the cursor jumps to the last line
of the Vim window, like with colon commands. That is where you type the word.
You can press the backspace key (backarrow or <BS>) to make corrections. Use
the <Left> and <Right> cursor keys when necessary.
Pressing <Enter> executes the command.
Note:
The characters .*[]^%/\?~$ have special meaning. If you want to use
them in a search you must put a \ in front of them. See below.
To find the next occurrence of the same string use the "n" command. Use this
to find the first #include after the cursor: >
/#include
And then type "n" several times. You will move to each #include in the text.
You can also use a count if you know which match you want. Thus "3n" finds
the third match. Using a count with "/" doesn't work.
The "?" command works like "/" but searches backwards: >
?word
The "N" command repeats the last search the opposite direction. Thus using
"N" after a "/" command search backwards, using "N" after "?" searches
forward.
IGNORING CASE
Normally you have to type exactly what you want to find. If you don't care
about upper or lowercase in a word, set the 'ignorecase' option: >
:set ignorecase
If you now search for "word", it will also match "Word" and "WORD". To match
case again: >
:set noignorecase
HISTORY
Suppose you do three searches: >
/one
/two
/three
Now let's start searching by typing a simple "/" without pressing <Enter>. If
you press <Up> (the cursor key), Vim puts "/three" on the command line.
Pressing <Enter> at this point searches for three. If you do not press
<Enter>, but press <Up> instead, Vim changes the prompt to "/two". Another
press of <Up> moves you to "/one".
You can also use the <Down> cursor key to move through the history of
search commands in the other direction.
If you know what a previously used pattern starts with, and you want to use it
again, type that character before pressing <Up>. With the previous example,
you can type "/o<Up>" and Vim will put "/one" on the command line.
The commands starting with ":" also have a history. That allows you to recall
a previous command and execute it again. These two histories are separate.
SEARCHING FOR A WORD IN THE TEXT
Suppose you see the word "TheLongFunctionName" in the text and you want to
find the next occurrence of it. You could type "/TheLongFunctionName", but
that's a lot of typing. And when you make a mistake Vim won't find it.
There is an easier way: Position the cursor on the word and use the "*"
command. Vim will grab the word under the cursor and use it as the search
string.
The "#" command does the same in the other direction. You can prepend a
count: "3*" searches for the third occurrence of the word under the cursor.
SEARCHING FOR WHOLE WORDS
If you type "/the" it will also match "there". To only find words that end
in "the" use: >
/the\>
The "\>" item is a special marker that only matches at the end of a word.
Similarly "\<" only matches at the begin of a word. Thus to search for the
word "the" only: >
/\<the\>
This does not match "there" or "soothe". Notice that the "*" and "#" commands
use these start-of-word and end-of-word markers to only find whole words (you
can use "g*" and "g#" to match partial words).
HIGHLIGHTING MATCHES
While editing a program you see a variable called "nr". You want to check
where it's used. You could move the cursor to "nr" and use the "*" command
and press "n" to go along all the matches.
There is another way. Type this command: >
:set hlsearch
If you now search for "nr", Vim will highlight all matches. That is a very
good way to see where the variable is used, without the need to type commands.
To switch this off: >
:set nohlsearch
Then you need to switch it on again if you want to use it for the next search
command. If you only want to remove the highlighting, use this command: >
:nohlsearch
This doesn't reset the option. Instead, it disables the highlighting. As
soon as you execute a search command, the highlighting will be used again.
Also for the "n" and "N" commands.
TUNING SEARCHES
There are a few options that change how searching works. These are the
essential ones:
>
:set incsearch
This makes Vim display the match for the string while you are still typing it.
Use this to check if the right match will be found. Then press <Enter> to
really jump to that location. Or type more to change the search string.
>
:set nowrapscan
This stops the search at the end of the file. Or, when you are searching
backwards, at the start of the file. The 'wrapscan' option is on by default,
thus searching wraps around the end of the file.
INTERMEZZO
If you like one of the options mentioned before, and set it each time you use
Vim, you can put the command in your Vim startup file.
Edit the file, as mentioned at |not-compatible|. Or use this command to
find out where it is: >
:scriptnames
Edit the file, for example with: >
:edit ~/.vimrc
Then add a line with the command to set the option, just like you typed it in
Vim. Example: >
Go:set hlsearch<Esc>
"G" moves to the end of the file. "o" starts a new line, where you type the
":set" command. You end insert mode with <Esc>. Then write the file: >
ZZ
If you now start Vim again, the 'hlsearch' option will already be set.
==============================================================================
*03.9* Simple search patterns
The Vim editor uses regular expressions to specify what to search for.
Regular expressions are an extremely powerful and compact way to specify a
search pattern. Unfortunately, this power comes at a price, because regular
expressions are a bit tricky to specify.
In this section we mention only a few essential ones. More about search
patterns and commands in chapter 27 |usr_27.txt|. You can find the full
explanation here: |pattern|.
BEGINNING AND END OF A LINE
The ^ character matches the beginning of a line. On an English-US keyboard
you find it above the 6. The pattern "include" matches the word include
anywhere on the line. But the pattern "^include" matches the word include
only if it is at the beginning of a line.
The $ character matches the end of a line. Therefore, "was$" matches the
word was only if it is at the end of a line.
Let's mark the places where "the" matches in this example line with "x"s:
the solder holding one of the chips melted and the ~
xxx xxx xxx
Using "/the$" we find this match:
the solder holding one of the chips melted and the ~
xxx
And with "/^the" we find this one:
the solder holding one of the chips melted and the ~
xxx
You can try searching with "/^the$", it will only match a single line
consisting of "the". White space does matter here, thus if a line contains a
space after the word, like "the ", the pattern will not match.
MATCHING ANY SINGLE CHARACTER
The . (dot) character matches any existing character. For example, the
pattern "c.m" matches a string whose first character is a c, whose second
character is anything, and whose the third character is m. Example:
We use a computer that became the cummin winter. ~
xxx xxx xxx
MATCHING SPECIAL CHARACTERS
If you really want to match a dot, you must avoid its special meaning by
putting a backslash before it.
If you search for "ter.", you will find these matches:
We use a computer that became the cummin winter. ~
xxxx xxxx
Searching for "ter\." only finds the second match.
==============================================================================
*03.10* Using marks
When you make a jump to a position with the "G" command, Vim remembers the
position from before this jump. This position is called a mark. To go back
where you came from, use this command: >
``
This ` is a backtick or open single-quote character.
If you use the same command a second time you will jump back again. That's
because the ` command is a jump itself, and the position from before this jump
is remembered.
Generally, every time you do a command that can move the cursor further than
within the same line, this is called a jump. This includes the search
commands "/" and "n" (it doesn't matter how far away the match is). But not
the character searches with "fx" and "tx" or the word movements "w" and "e".
Also, "j" and "k" are not considered to be a jump. Even when you use a
count to make them move the cursor quite a long way away.
The `` command jumps back and forth, between two points. The CTRL-O command
jumps to older positions (Hint: O for older). CTRL-I then jumps back to newer
positions (Hint: I is just next to O on the keyboard). Consider this sequence
of commands: >
33G
/^The
CTRL-O
You first jump to line 33, then search for a line that starts with "The".
Then with CTRL-O you jump back to line 33. Another CTRL-O takes you back to
where you started. If you now use CTRL-I you jump to line 33 again. And
to the match for "The" with another CTRL-I.
| example text ^ |
33G | example text | CTRL-O | CTRL-I
| example text | |
V line 33 text ^ V
| example text | |
/^The | example text | CTRL-O | CTRL-I
V There you are | V
example text
Note:
CTRL-I is the same as <Tab>.
The ":jumps" command gives a list of positions you jumped to. The entry which
you used last is marked with a ">".
NAMED MARKS
Vim enables you to place your own marks in the text. The command "ma" marks
the place under the cursor as mark a. You can place 26 marks (a through z) in
your text. You can't see them, it's just a position that Vim remembers.
To go to a mark, use the command `{mark}, where "{mark} is the mark letter.
Thus to move to the a mark:
>
`a
The command 'mark (single quotation mark, or apostrophe) moves you to the
beginning of the line containing the mark. This differs from the `mark
command, which moves you to marked column.
The marks can be very useful when working on two related parts in a file.
Suppose you have some text near the start of the file you need to look at,
while working on some text near the end of the file.
Move to the text at the start and place the s (start) mark there: >
ms
The move to the text you want to work on and put the e (end) mark there: >
me
Now you can move around, and when you want to look at the start of the file,
you use this to jump there: >
's
Then you can use '' to jump back to where you were, or 'e to jump to the text
you were working on at the end.
There is nothing special about using s for start and e for end, they are
just easy to remember.
You can use this command to get a list of marks: >
:marks
You will notice a few special marks. These include:
' The cursor position before doing a jump
" The cursor position when last editing the file
[ Start of the last change
] End of the last change
==============================================================================
Next chapter: |usr_04.txt| Making small changes
Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:

514
runtime/doc/usr_04.txt Normal file
View File

@@ -0,0 +1,514 @@
*usr_04.txt* For Vim version 7.0aa. Last change: 2004 Jun 08
VIM USER MANUAL - by Bram Moolenaar
Making small changes
This chapter shows you several ways of making corrections and moving text
around. It teaches you the three basic ways to change text: operator-motion,
Visual mode and text objects.
|04.1| Operators and motions
|04.2| Changing text
|04.3| Repeating a change
|04.4| Visual mode
|04.5| Moving text
|04.6| Copying text
|04.7| Using the clipboard
|04.8| Text objects
|04.9| Replace mode
|04.10| Conclusion
Next chapter: |usr_05.txt| Set your settings
Previous chapter: |usr_03.txt| Moving around
Table of contents: |usr_toc.txt|
==============================================================================
*04.1* Operators and motions
In chapter 2 you learned the "x" command to delete a single character. And
using a count: "4x" deletes four characters.
The "dw" command deletes a word. You may recognize the "w" command as the
move word command. In fact, the "d" command may be followed by any motion
command, and it deletes from the current location to the place where the
cursor winds up.
The "4w" command, for example, moves the cursor over four words. The d4w
command deletes four words.
To err is human. To really foul up you need a computer. ~
------------------>
d4w
To err is human. you need a computer. ~
Vim only deletes up to the position where the motion takes the cursor. That's
because Vim knows that you probably don't want to delete the first character
of a word. If you use the "e" command to move to the end of a word, Vim
guesses that you do want to include that last character:
To err is human. you need a computer. ~
-------->
d2e
To err is human. a computer. ~
Whether the character under the cursor is included depends on the command you
used to move to that character. The reference manual calls this "exclusive"
when the character isn't included and "inclusive" when it is.
The "$" command moves to the end of a line. The "d$" command deletes from the
cursor to the end of the line. This is an inclusive motion, thus the last
character of the line is included in the delete operation:
To err is human. a computer. ~
------------>
d$
To err is human ~
There is a pattern here: operator-motion. You first type an operator command.
For example, "d" is the delete operator. Then you type a motion command like
"4l" or "w". This way you can operate on any text you can move over.
==============================================================================
*04.2* Changing text
Another operator is "c", change. It acts just like the "d" operator, except
it leaves you in Insert mode. For example, "cw" changes a word. Or more
specifically, it deletes a word and then puts you in Insert mode.
To err is human ~
------->
c2wbe<Esc>
To be human ~
This "c2wbe<Esc>" contains these bits:
c the change operator
2w move two words (they are deleted and Insert mode started)
be insert this text
<Esc> back to Normal mode
If you have paid attention, you will have noticed something strange: The space
before "human" isn't deleted. There is a saying that for every problem there
is an answer that is simple, clear, and wrong. That is the case with the
example used here for the "cw" command. The c operator works just like the
d operator, with one exception: "cw". It actually works like "ce", change to
end of word. Thus the space after the word isn't included. This is an
exception that dates back to the old Vi. Since many people are used to it
now, the inconsistency has remained in Vim.
MORE CHANGES
Like "dd" deletes a whole line, "cc" changes a whole line. It keeps the
existing indent (leading white space) though.
Just like "d$" deletes until the end of the line, "c$" changes until the end
of the line. It's like doing "d$" to delete the text and then "a" to start
Insert mode and append new text.
SHORTCUTS
Some operator-motion commands are used so often that they have been given a
single letter command:
x stands for dl (delete character under the cursor)
X stands for dh (delete character left of the cursor)
D stands for d$ (delete to end of the line)
C stands for c$ (change to end of the line)
s stands for cl (change one character)
S stands for cc (change a whole line)
WHERE TO PUT THE COUNT
The commands "3dw" and "d3w" delete three words. If you want to get really
picky about things, the first command, "3dw", deletes one word three times;
the command "d3w" deletes three words once. This is a difference without a
distinction. You can actually put in two counts, however. For example,
"3d2w" deletes two words, repeated three times, for a total of six words.
REPLACING WITH ONE CHARACTER
The "r" command is not an operator. It waits for you to type a character, and
will replace the character under the cursor with it. You could do the same
with "cl" or with the "s" command, but with "r" you don't have to press <Esc>
there is somerhing grong here ~
rT rt rw
There is something wrong here ~
Using a count with "r" causes that many characters to be replaced with the
same character. Example:
There is something wrong here ~
5rx
There is something xxxxx here ~
To replace a character with a line break use "r<Enter>". This deletes one
character and inserts a line break. Using a count here only applies to the
number of characters deleted: "4r<Enter>" replaces four characters with one
line break.
==============================================================================
*04.3* Repeating a change
The "." command is one of the most simple yet powerful commands in Vim. It
repeats the last change. For instance, suppose you are editing an HTML file
and want to delete all the <B> tags. You position the cursor on the first <
and delete the <B> with the command "df>". You then go to the < of the next
</B> and kill it using the "." command. The "." command executes the last
change command (in this case, "df>"). To delete another tag, position the
cursor on the < and use the "." command.
To <B>generate</B> a table of <B>contents ~
f< find first < --->
df> delete to > -->
f< find next < --------->
. repeat df> --->
f< find next < ------------->
. repeat df> -->
The "." command works for all changes you make, except for the "u" (undo),
CTRL-R (redo) and commands that start with a colon (:).
Another example: You want to change the word "four" to "five". It appears
several times in your text. You can do this quickly with this sequence of
commands:
/four<Enter> find the first string "four"
cwfive<Esc> change the word to "five"
n find the next "four"
. repeat the change to "five'
n find the next "four"
. repeat the change
etc.
==============================================================================
*04.4* Visual mode
To delete simple items the operator-motion changes work quite well. But often
it's not so easy to decide which command will move over the text you want to
change. Then you can use Visual mode.
You start Visual mode by pressing "v". You move the cursor over the text you
want to work on. While you do this, the text is highlighted. Finally type
the operator command.
For example, to delete from halfway one word to halfway another word:
This is an examination sample of visual mode ~
---------->
velllld
This is an example of visual mode ~
When doing this you don't really have to count how many times you have to
press "l" to end up in the right position. You can immediately see what text
will be deleted when you press "d".
If at any time you decide you don't want to do anything with the highlighted
text, just press <Esc> and Visual mode will stop without doing anything.
SELECTING LINES
If you want to work on whole lines, use "V" to start Visual mode. You will
see right away that the whole line is highlighted, without moving around.
When you move left or right nothing changes. When you move up or down the
selection is extended whole lines at a time.
For example, select three lines with "Vjj":
+------------------------+
| text more text |
>> | more text more text | |
selected lines >> | text text text | | Vjj
>> | text more | V
| more text more |
+------------------------+
SELECTING BLOCKS
If you want to work on a rectangular block of characters, use CTRL-V to start
Visual mode. This is very useful when working on tables.
name Q1 Q2 Q3
pierre 123 455 234
john 0 90 39
steve 392 63 334
To delete the middle "Q2" column, move the cursor to the "Q" of "Q2". Press
CTRL-V to start blockwise Visual mode. Now move the cursor three lines down
with "3j" and to the next word with "w". You can see the first character of
the last column is included. To exclude it, use "h". Now press "d" and the
middle column is gone.
GOING TO THE OTHER SIDE
If you have selected some text in Visual mode, and discover that you need to
change the other end of the selection, use the "o" command (Hint: o for other
end). The cursor will go to the other end, and you can move the cursor to
change where the selection starts. Pressing "o" again brings you back to the
other end.
When using blockwise selection, you have four corners. "o" only takes you to
one of the other corners, diagonally. Use "O" to move to the other corner in
the same line.
Note that "o" and "O" in Visual mode work very different from Normal mode,
where they open a new line below or above the cursor.
==============================================================================
*04.5* Moving text
When you delete something with the "d", "x", or another command, the text is
saved. You can paste it back by using the p command. (The Vim name for
this is put).
Take a look at how this works. First you will delete an entire line, by
putting the cursor on the line you want to delete and typing "dd". Now you
move the cursor to where you want to put the line and use the "p" (put)
command. The line is inserted on the line below the cursor.
a line a line a line
line 2 dd line 3 p line 3
line 3 line 2
Because you deleted an entire line, the "p" command placed the text line below
the cursor. If you delete part of a line (a word, for instance), the "p"
command puts it just after the cursor.
Some more boring try text to out commands. ~
---->
dw
Some more boring text to out commands. ~
------->
welp
Some more boring text to try out commands. ~
MORE ON PUTTING
The "P" command puts text like "p", but before the cursor. When you deleted a
whole line with "dd", "P" will put it back above the cursor. When you deleted
a word with "dw", "P" will put it back just before the cursor.
You can repeat putting as many times as you like. The same text will be used.
You can use a count with "p" and "P". The text will be repeated as many times
as specified with the count. Thus "dd" and then "3p" puts three copies of the
same deleted line.
SWAPPING TWO CHARACTERS
Frequently when you are typing, your fingers get ahead of your brain (or the
other way around?). The result is a typo such as "teh" for "the". Vim
makes it easy to correct such problems. Just put the cursor on the e of "teh"
and execute the command "xp". This works as follows: "x" deletes the
character e and places it in a register. "p" puts the text after the cursor,
which is after the h.
teh th the ~
x p
==============================================================================
*04.6* Copying text
To copy text from one place to another, you could delete it, use "u" to undo
the deletion and then "p" to put it somewhere else. There is an easier way:
yanking. The "y" operator copies text into a register. Then a "p" command
can be used to put it.
Yanking is just a Vim name for copying. The "c" letter was already used
for the change operator, and "y" was still available. Calling this
operator "yank" made it easier to remember to use the "y" key.
Since "y" is an operator, you use "yw" to yank a word. A count is possible as
usual. To yank two words use "y2w". Example:
let sqr = LongVariable * ~
-------------->
y2w
let sqr = LongVariable * ~
p
let sqr = LongVariable * LongVariable ~
Notice that "yw" includes the white space after a word. If you don't want
this, use "ye".
The "yy" command yanks a whole line, just like "dd" deletes a whole line.
Unexpectedly, while "D" deletes from the cursor to the end of the line, "Y"
works like "yy", it yanks the whole line. Watch out for this inconsistency!
Use "y$" to yank to the end of the line.
a text line yy a text line a text line
line 2 line 2 p line 2
last line last line a text line
last line
==============================================================================
*04.7* Using the clipboard
If you are using the GUI version of Vim (gvim), you can find the "Copy" item
in the "Edit" menu. First select some text with Visual mode, then use the
Edit/Copy menu. The selected text is now copied to the clipboard. You can
paste the text in other programs. In Vim itself too.
If you have copied text to the clipboard in another application, you can paste
it in Vim with the Edit/Paste menu. This works in Normal mode and Insert
mode. In Visual mode the selected text is replaced with the pasted text.
The "Cut" menu item deletes the text before it's put on the clipboard. The
"Copy", "Cut" and "Paste" items are also available in the popup menu (only
when there is a popup menu, of course). If your Vim has a toolbar, you can
also find these items there.
If you are not using the GUI, or if you don't like using a menu, you have to
use another way. You use the normal "y" (yank) and "p" (put) commands, but
prepend "* (double-quote star) before it. To copy a line to the clipboard: >
"*yy
To put text from the clipboard back into the text: >
"*p
This only works on versions of Vim that include clipboard support. More about
the clipboard in section |09.3| and here: |clipboard|.
==============================================================================
*04.8* Text objects
If the cursor is in the middle of a word and want to delete that word, you
need to move back to its start before you can do "dw". There is a simpler way
to do this: "daw".
this is some example text. ~
daw
this is some text. ~
The "d" of "daw" is the delete operator. "aw" is a text object. Hint: "aw"
stands for "A Word". Thus "daw" is "Delete A Word". To be precise, the white
space after the word is also deleted (the white space before the word at the
end of the line).
Using text objects is the third way to make changes in Vim. We already had
operator-motion and Visual mode. Now we add operator-text object.
It is very similar to operator-motion, but instead of operating on the text
between the cursor position before and after a movement command, the text
object is used as a whole. It doesn't matter where in the object the cursor
was.
To change a whole sentence use "cis". Take this text:
Hello there. This ~
is an example. Just ~
some text. ~
Move to the start of the second line, on "is an". Now use "cis":
Hello there. Just ~
some text. ~
The cursor is in between the blanks in the first line. Now you type the new
sentence "Another line.":
Hello there. Another line. Just ~
some text. ~
"cis" consists of the "c" (change) operator and the "is" text object. This
stands for "Inner Sentence". There is also the "as" (a sentence) object. The
difference is that "as" includes the white space after the sentence and "is"
doesn't. If you would delete a sentence, you want to delete the white space
at the same time, thus use "das". If you want to type new text the white
space can remain, thus you use "cis".
You can also use text objects in Visual mode. It will include the text object
in the Visual selection. Visual mode continues, thus you can do this several
times. For example, start Visual mode with "v" and select a sentence with
"as". Now you can repeat "as" to include more sentences. Finally you use an
operator to do something with the selected sentences.
You can find a long list of text objects here: |text-objects|.
==============================================================================
*04.9* Replace mode
The "R" command causes Vim to enter replace mode. In this mode, each
character you type replaces the one under the cursor. This continues until
you type <Esc>.
In this example you start Replace mode on the first "t" of "text":
This is text. ~
Rinteresting.<Esc>
This is interesting. ~
You may have noticed that this command replaced 5 characters in the line with
twelve others. The "R" command automatically extends the line if it runs out
of characters to replace. It will not continue on the next line.
You can switch between Insert mode and Replace mode with the <Insert> key.
When you use <BS> (backspace) to make correction, you will notice that the
old text is put back. Thus it works like an undo command for the last typed
character.
==============================================================================
*04.10* Conclusion
The operators, movement commands and text objects give you the possibility to
make lots of combinations. Now that you know how it works, you can use N
operators with M movement commands to make N * M commands!
You can find a list of operators here: |operator|
For example, there are many other ways to delete pieces of text. Here are a
few often used ones:
x delete character under the cursor (short for "dl")
X delete character before the cursor (short for "dh")
D delete from cursor to end of line (short for "d$")
dw delete from cursor to next start of word
db delete from cursor to previous start of word
diw delete word under the cursor (excluding white space)
daw delete word under the cursor (including white space)
dG delete until the end of the file
dgg delete until the start of the file
If you use "c" instead of "d" they become change commands. And with "y" you
yank the text. And so forth.
There are a few often used commands to make changes that didn't fit somewhere
else:
~ change case of the character under the cursor, and move the
cursor to the next character. This is not an operator (unless
'tildeop' is set), thus you can't use it with a motion
command. It does works in Visual mode and changes case for
all the selected text then.
I Start Insert mode after moving the cursor to the first
non-blank in the line.
A Start Insert mode after moving the cursor to the end of the
line.
==============================================================================
Next chapter: |usr_05.txt| Set your settings
Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:

616
runtime/doc/usr_05.txt Normal file
View File

@@ -0,0 +1,616 @@
*usr_05.txt* For Vim version 7.0aa. Last change: 2004 Mar 12
VIM USER MANUAL - by Bram Moolenaar
Set your settings
Vim can be tuned to work like you want it to. This chapter shows you how to
make Vim start with options set to different values. Add plugins to extend
Vims capabilities. Or define your own macros.
|05.1| The vimrc file
|05.2| The example vimrc file explained
|05.3| Simple mappings
|05.4| Adding a plugin
|05.5| Adding a help file
|05.6| The option window
|05.7| Often used options
Next chapter: |usr_06.txt| Using syntax highlighting
Previous chapter: |usr_04.txt| Making small changes
Table of contents: |usr_toc.txt|
==============================================================================
*05.1* The vimrc file *vimrc-intro*
You probably got tired of typing commands that you use very often. To start
with all your favorite option settings and mappings, you write them in what is
called the vimrc file. Vim reads this file when it starts up.
If you have trouble finding your vimrc file, use this command: >
:scriptnames
One of the first files in the list should be called ".vimrc" or "_vimrc" and
is located in your home directory.
If you don't have a vimrc file yet, see |vimrc| to find out where you can
create a vimrc file. Also, the ":version" command mentions the name of the
"user vimrc file" Vim looks for.
For Unix this file is always used: >
~/.vimrc
For MS-DOS and MS-Windows it is mostly one of these: >
$HOME/_vimrc
$VIM/_vimrc
The vimrc file can contain all the commands that you type after a colon. The
most simple ones are for setting options. For example, if you want Vim to
always start with the 'incsearch' option on, add this line you your vimrc
file: >
set incsearch
For this new line to take effect you need to exit Vim and start it again.
Later you will learn how to do this without exiting Vim.
This chapter only explains the most basic items. For more information on how
to write a Vim script file: |usr_41.txt|.
==============================================================================
*05.2* The example vimrc file explained *vimrc_example.vim*
In the first chapter was explained how the example vimrc (included in the
Vim distribution) file can be used to make Vim startup in not-compatible mode
(see |not-compatible|). The file can be found here:
$VIMRUNTIME/vimrc_example.vim ~
In this section we will explain the various commands used in this file. This
will give you hints about how to set up your own preferences. Not everything
will be explained though. Use the ":help" command to find out more.
>
set nocompatible
As mentioned in the first chapter, these manuals explain Vim working in an
improved way, thus not completely Vi compatible. Setting the 'compatible'
option off, thus 'nocompatible' takes care of this.
>
set backspace=indent,eol,start
This specifies where in Insert mode the <BS> is allowed to delete the
character in front of the cursor. The three items, separated by commas, tell
Vim to delete the white space at the start of the line, a line break and the
character before where Insert mode started.
>
set autoindent
This makes Vim use the indent of the previous line for a newly created line.
Thus there is the same amount of white space before the new line. For example
when pressing <Enter> in Insert mode, and when using the "o" command to open a
new line.
>
if has("vms")
set nobackup
else
set backup
endif
This tells Vim to keep a backup copy of a file when overwriting it. But not
on the VMS system, since it keeps old versions of files already. The backup
file will have the same name as the original file with "~" added. See |07.4|
>
set history=50
Keep 50 commands and 50 search patterns in the history. Use another number if
you want to remember fewer or more lines.
>
set ruler
Always display the current cursor position in the lower right corner of the
Vim window.
>
set showcmd
Display an incomplete command in the lower right corner of the Vim window,
left of the ruler. For example, when you type "2f", Vim is waiting for you to
type the character to find and "2f" is displayed. When you press "w" next,
the "2fw" command is executed and the displayed "2f" is removed.
+-------------------------------------------------+
|text in the Vim window |
|~ |
|~ |
|-- VISUAL -- 2f 43,8 17% |
+-------------------------------------------------+
^^^^^^^^^^^ ^^^^^^^^ ^^^^^^^^^^
'showmode' 'showcmd' 'ruler'
>
set incsearch
Display the match for a search pattern when halfway typing it.
>
map Q gq
This defines a key mapping. More about that in the next section. This
defines the "Q" command to do formatting with the "gq" operator. This is how
it worked before Vim 5.0. Otherwise the "Q" command starts Ex mode, but you
will not need it.
>
vnoremap p <Esc>:let current_reg = @"<CR>gvs<C-R>=current_reg<CR><Esc>
This is a complicated mapping. It will not be explained how it works here.
What it does is to make "p" in Visual mode overwrite the selected text with
the previously yanked text. You can see that mappings can be used to do quite
complicated things. Still, it is just a sequence of commands that are
executed like you typed them.
>
if &t_Co > 2 || has("gui_running")
syntax on
set hlsearch
endif
This switches on syntax highlighting, but only if colors are available. And
the 'hlsearch' option tells Vim to highlight matches with the last used search
pattern. The "if" command is very useful to set options only when some
condition is met. More about that in |usr_41.txt|.
*vimrc-filetype* >
filetype plugin indent on
This switches on three very clever mechanisms:
1. Filetype detection.
Whenever you start editing a file, Vim will try to figure out what kind of
file this is. When you edit "main.c", Vim will see the ".c" extension and
recognize this as a "c" filetype. When you edit a file that starts with
"#!/bin/sh", Vim will recognize it as a "sh" filetype.
The filetype detection is used for syntax highlighting and the other two
items below.
See |filetypes|.
2. Using filetype plugin files
Many different filetypes are edited with different options. For example,
when you edit a "c" file, it's very useful to set the 'cindent' option to
automatically indent the lines. These commonly useful option settings are
included with Vim in filetype plugins. You can also add your own, see
|write-filetype-plugin|.
3. Using indent files
When editing programs, the indent of a line can often be computed
automatically. Vim comes with these indent rules for a number of
filetypes. See |:filetype-indent-on| and 'indentexpr'.
>
autocmd FileType text setlocal textwidth=78
This makes Vim break text to avoid lines getting longer than 78 characters.
But only for files that have been detected to be plain text. There are
actually two parts here. "autocmd FileType text" is an autocommand. This
defines that when the file type is set to "text" the following command is
automatically executed. "setlocal textwidth=78" sets the 'textwidth' option
to 78, but only locally in one file.
>
autocmd BufReadPost *
\ if line("'\"") > 0 && line("'\"") <= line("$") |
\ exe "normal g`\"" |
\ endif
Another autocommand. This time it is used after reading any file. The
complicated stuff after it checks if the '" mark is defined, and jumps to it
if so. The backslash at the start of a line is used to continue the command
from the previous line. That avoids a line getting very long.
See |line-continuation|. This only works in a Vim script file, not when
typing commands at the command-line.
==============================================================================
*05.3* Simple mappings
A mapping enables you to bind a set of Vim commands to a single key. Suppose,
for example, that you need to surround certain words with curly braces. In
other words, you need to change a word such as "amount" into "{amount}". With
the :map command, you can tell Vim that the F5 key does this job. The command
is as follows: >
:map <F5> i{<Esc>ea}<Esc>
<
Note:
When entering this command, you must enter <F5> by typing four
characters. Similarly, <Esc> is not entered by pressing the <Esc>
key, but by typing five characters. Watch out for this difference
when reading the manual!
Let's break this down:
<F5> The F5 function key. This is the trigger key that causes the
command to be executed as the key is pressed.
i{<Esc> Insert the { character. The <Esc> key ends Insert mode.
e Move to the end of the word.
a}<Esc> Append the } to the word.
After you execute the ":map" command, all you have to do to put {} around a
word is to put the cursor on the first character and press F5.
In this example, the trigger is a single key; it can be any string. But when
you use an existing Vim command, that command will no longer be available.
You better avoid that.
One key that can be used with mappings is the backslash. Since you
probably want to define more than one mapping, add another character. You
could map "\p" to add parens around a word, and "\c" to add curly braces, for
example: >
:map \p i(<Esc>ea)<Esc>
:map \c i{<Esc>ea}<Esc>
You need to type the \ and the p quickly after another, so that Vim knows they
belong together.
The ":map" command (with no arguments) lists your current mappings. At
least the ones for Normal mode. More about mappings in section |40.1|.
==============================================================================
*05.4* Adding a plugin *add-plugin* *plugin*
Vim's functionality can be extended by adding plugins. A plugin is nothing
more than a Vim script file that is loaded automatically when Vim starts. You
can add a plugin very easily by dropping it in your plugin directory.
{not available when Vim was compiled without the |+eval| feature}
There are two types of plugins:
global plugin: Used for all kinds of files
filetype plugin: Only used for a specific type of file
The global plugins will be discussed first, then the filetype ones
|add-filetype-plugin|.
GLOBAL PLUGINS *standard-plugin*
When you start Vim, it will automatically load a number of global plugins.
You don't have to do anything for this. They add functionality that most
people will want to use, but which was implemented as a Vim script instead of
being compiled into Vim. You can find them listed in the help index
|standard-plugin-list|. Also see |load-plugins|.
*add-global-plugin*
You can add a global plugin to add functionality that will always be present
when you use Vim. There are only two steps for adding a global plugin:
1. Get a copy of the plugin.
2. Drop it in the right directory.
GETTING A GLOBAL PLUGIN
Where can you find plugins?
- Some come with Vim. You can find them in the directory $VIMRUNTIME/macros
and its sub-directories.
- Download from the net, check out http://vim.sf.net.
- They are sometimes posted in a Vim |maillist|.
- You could write one yourself, see |write-plugin|.
USING A GLOBAL PLUGIN
First read the text in the plugin itself to check for any special conditions.
Then copy the file to your plugin directory:
system plugin directory ~
Unix ~/.vim/plugin/
PC and OS/2 $HOME/vimfiles/plugin or $VIM/vimfiles/plugin
Amiga s:vimfiles/plugin
Macintosh $VIM:vimfiles:plugin
Mac OS X ~/.vim/plugin/
RISC-OS Choices:vimfiles.plugin
Example for Unix (assuming you didn't have a plugin directory yet): >
mkdir ~/.vim
mkdir ~/.vim/plugin
cp /usr/local/share/vim/vim60/macros/justify.vim ~/.vim/plugin
That's all! Now you can use the commands defined in this plugin to justify
text.
FILETYPE PLUGINS *add-filetype-plugin* *ftplugins*
The Vim distribution comes with a set of plugins for different filetypes that
you can start using with this command: >
:filetype plugin on
That's all! See |vimrc-filetype|.
If you are missing a plugin for a filetype you are using, or you found a
better one, you can add it. There are two steps for adding a filetype plugin:
1. Get a copy of the plugin.
2. Drop it in the right directory.
GETTING A FILETYPE PLUGIN
You can find them in the same places as the global plugins. Watch out if the
type of file is mentioned, then you know if the plugin is a global or a
filetype one. The scripts in $VIMRUNTIME/macros are global ones, the filetype
plugins are in $VIMRUNTIME/ftplugin.
USING A FILETYPE PLUGIN *ftplugin-name*
You can add a filetype plugin by dropping it in the right directory. The
name of this directory is in the same directory mentioned above for global
plugins, but the last part is "ftplugin". Suppose you have found a plugin for
the "stuff" filetype, and you are on Unix. Then you can move this file to the
ftplugin directory: >
mv thefile ~/.vim/ftplugin/stuff.vim
If that file already exists you already have a plugin for "stuff". You might
want to check if the existing plugin doesn't conflict with the one you are
adding. If it's OK, you can give the new one another name: >
mv thefile ~/.vim/ftplugin/stuff_too.vim
The underscore is used to separate the name of the filetype from the rest,
which can be anything. If you would use "otherstuff.vim" it wouldn't work, it
would be loaded for the "otherstuff" filetype.
On MS-DOS you cannot use long filenames. You would run into trouble if you
add a second plugin and the filetype has more than six characters. You can
use an extra directory to get around this: >
mkdir $VIM/vimfiles/ftplugin/fortran
copy thefile $VIM/vimfiles/ftplugin/fortran/too.vim
The generic names for the filetype plugins are: >
ftplugin/<filetype>.vim
ftplugin/<filetype>_<name>.vim
ftplugin/<filetype>/<name>.vim
Here "<name>" can be any name that you prefer.
Examples for the "stuff" filetype on Unix: >
~/.vim/ftplugin/stuff.vim
~/.vim/ftplugin/stuff_def.vim
~/.vim/ftplugin/stuff/header.vim
The <filetype> part is the name of the filetype the plugin is to be used for.
Only files of this filetype will use the settings from the plugin. The <name>
part of the plugin file doesn't matter, you can use it to have several plugins
for the same filetype. Note that it must end in ".vim".
Further reading:
|filetype-plugins| Documentation for the filetype plugins and information
about how to avoid that mappings cause problems.
|load-plugins| When the global plugins are loaded during startup.
|ftplugin-overrule| Overruling the settings from a global plugin.
|write-plugin| How to write a plugin script.
|plugin-details| For more information about using plugins or when your
plugin doesn't work.
|new-filetype| How to detect a new file type.
==============================================================================
*05.5* Adding a help file *add-local-help* *matchit-install*
If you are lucky, the plugin you installed also comes with a help file. We
will explain how to install the help file, so that you can easily find help
for your new plugin.
Let us use the "matchit.vim" plugin as an example (it is included with
Vim). This plugin makes the "%" command jump to matching HTML tags,
if/else/endif in Vim scripts, etc. Very useful, although it's not backwards
compatible (that's why it is not enabled by default).
This plugin comes with documentation: "matchit.txt". Let's first copy the
plugin to the right directory. This time we will do it from inside Vim, so
that we can use $VIMRUNTIME. (You may skip some of the "mkdir" commands if
you already have the directory.) >
:!mkdir ~/.vim
:!mkdir ~/.vim/plugin
:!cp $VIMRUNTIME/macros/matchit.vim ~/.vim/plugin
Now create a "doc" directory in one of the directories in 'runtimepath'. >
:!mkdir ~/.vim/doc
Copy the help file to the "doc" directory. >
:!cp $VIMRUNTIME/macros/matchit.txt ~/.vim/doc
Now comes the trick, which allows you to jump to the subjects in the new help
file: Generate the local tags file with the |:helptags| command. >
:helptags ~/.vim/doc
Now you can use the >
:help g%
command to find help for "g%" in the help file you just added. You can see an
entry for the local help file when you do: >
:help local-additions
The title lines from the local help files are automagically added to this
section. There you can see which local help files have been added and jump to
them through the tag.
For writing a local help file, see |write-local-help|.
==============================================================================
*05.6* The option window
If you are looking for an option that does what you want, you can search in
the help files here: |options|. Another way is by using this command: >
:options
This opens a new window, with a list of options with a one-line explanation.
The options are grouped by subject. Move the cursor to a subject and press
<Enter> to jump there. Press <Enter> again to jump back. Or use CTRL-O.
You can change the value of an option. For example, move to the "displaying
text" subject. Then move the cursor down to this line:
set wrap nowrap ~
When you hit <Enter>, the line will change to:
set nowrap wrap ~
The option has now been switched off.
Just above this line is a short description of the 'wrap' option. Move the
cursor one line up to place it in this line. Now hit <Enter> and you jump to
the full help on the 'wrap' option.
For options that take a number or string argument you can edit the value.
Then press <Enter> to apply the new value. For example, move the cursor a few
lines up to this line:
set so=0 ~
Position the cursor on the zero with "$". Change it into a five with "r5".
Then press <Enter> to apply the new value. When you now move the cursor
around you will notice that the text starts scrolling before you reach the
border. This is what the 'scrolloff' option does, it specifies an offset
from the window border where scrolling starts.
==============================================================================
*05.7* Often used options
There are an awful lot of options. Most of them you will hardly ever use.
Some of the more useful ones will be mentioned here. Don't forget you can
find more help on these options with the ":help" command, with single quotes
before and after the option name. For example: >
:help 'wrap'
In case you have messed up an option value, you can set it back to the
default by putting a ampersand (&) after the option name. Example: >
:set iskeyword&
NOT WRAPPING LINES
Vim normally wraps long lines, so that you can see all of the text. Sometimes
it's better to let the text continue right of the window. Then you need to
scroll the text left-right to see all of a long line. Switch wrapping of with
this command: >
:set nowrap
Vim will automatically scroll the text when you move to text that is not
displayed. To see a context of ten characters, do this: >
:set sidescroll=10
This doesn't change the text in the file, only the way it is displayed.
WRAPPING MOVEMENT COMMANDS
Most commands for moving around will stop moving at the start and end of a
line. You can change that with the 'whichwrap' option. This sets it to the
default value: >
:set whichwrap=b,s
This allows the <BS> key, when used in the first position of a line, to move
the cursor to the end of the previous line. And the <Space> key moves from
the end of a line to the start of the next one.
To allow the cursor keys <Left> and <Right> to also wrap, use this command: >
:set whichwrap=b,s,<,>
This is still only for Normal mode. To let <Left> and <Right> do this in
Insert mode as well: >
:set whichwrap=b,s,<,>,[,]
There are a few other flags that can be added, see 'whichwrap'.
VIEWING TABS
When there are tabs in a file, you cannot see where they are. To make them
visible: >
:set list
Now every Tab is displayed as ^I. And a $ is displayed at the end of each
line, so that you can spot trailing spaces that would otherwise go unnoticed.
A disadvantage is that this looks ugly when there are many Tabs in a file.
If you have a color terminal, or are using the GUI, Vim can show the spaces
and tabs as highlighted characters. Use the 'listchars' option: >
:set listchars=tab:>-,trail:-
Now every tab will be displayed as ">---" (with more or less "-") and trailing
white space as "-". Looks a lot better, doesn't it?
KEYWORDS
The 'iskeyword' option specifies which characters can appear in a word: >
:set iskeyword
< iskeyword=@,48-57,_,192-255 ~
The "@" stands for all alphabetic letters. "48-57" stands for ASCII
characters 48 to 57, which are the numbers 0 to 9. "192-255" are the
printable latin characters.
Sometimes you will want to include a dash in keywords, so that commands
like "w" consider "upper-case" to be one word. You can do it like this: >
:set iskeyword+=-
:set iskeyword
< iskeyword=@,48-57,_,192-255,- ~
If you look at the new value, you will see that Vim has added a comma for you.
To remove a character use "-=". For example, to remove the underscore: >
:set iskeyword-=_
:set iskeyword
< iskeyword=@,48-57,192-255,- ~
This time a comma is automatically deleted.
ROOM FOR MESSAGES
When Vim starts there is one line at the bottom that is used for messages.
When a message is long, it is either truncated, thus you can only see part of
it, or the text scrolls and you have to press <Enter> to continue.
You can set the 'cmdheight' option to the number of lines used for
messages. Example: >
:set cmdheight=3
This does mean there is less room to edit text, thus it's a compromise.
==============================================================================
Next chapter: |usr_06.txt| Using syntax highlighting
Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:

277
runtime/doc/usr_06.txt Normal file
View File

@@ -0,0 +1,277 @@
*usr_06.txt* For Vim version 7.0aa. Last change: 2002 Jul 14
VIM USER MANUAL - by Bram Moolenaar
Using syntax highlighting
Black and white text is boring. With colors your file comes to life. This
not only looks nice, it also speeds up your work. Change the colors used for
the different sorts of text. Print your text, with the colors you see on the
screen.
|06.1| Switching it on
|06.2| No or wrong colors?
|06.3| Different colors
|06.4| With colors or without colors
|06.5| Printing with colors
|06.6| Further reading
Next chapter: |usr_07.txt| Editing more than one file
Previous chapter: |usr_05.txt| Set your settings
Table of contents: |usr_toc.txt|
==============================================================================
*06.1* Switching it on
It all starts with one simple command: >
:syntax enable
That should work in most situations to get color in your files. Vim will
automagically detect the type of file and load the right syntax highlighting.
Suddenly comments are blue, keywords brown and strings red. This makes it
easy to overview the file. After a while you will find that black&white text
slows you down!
If you always want to use syntax highlighting, put the ":syntax enable"
command in your |vimrc| file.
If you want syntax highlighting only when the terminal supports colors, you
can put this in your |vimrc| file: >
if &t_Co > 1
syntax enable
endif
If you want syntax highlighting only in the GUI version, put the ":syntax
enable" command in your |gvimrc| file.
==============================================================================
*06.2* No or wrong colors?
There can be a number of reasons why you don't see colors:
- Your terminal does not support colors.
Vim will use bold, italic and underlined text, but this doesn't look
very nice. You probably will want to try to get a terminal with
colors. For Unix, I recommend the xterm from the XFree86 project:
|xfree-xterm|.
- Your terminal does support colors, but Vim doesn't know this.
Make sure your $TERM setting is correct. For example, when using an
xterm that supports colors: >
setenv TERM xterm-color
<
or (depending on your shell): >
TERM=xterm-color; export TERM
< The terminal name must match the terminal you are using. If it
still doesn't work, have a look at |xterm-color|, which shows a few
ways to make Vim display colors (not only for an xterm).
- The file type is not recognized.
Vim doesn't know all file types, and sometimes it's near to impossible
to tell what language a file uses. Try this command: >
:set filetype
<
If the result is "filetype=" then the problem is indeed that Vim
doesn't know what type of file this is. You can set the type
manually: >
:set filetype=fortran
< To see which types are available, look in the directory
$VIMRUNTIME/syntax. For the GUI you can use the Syntax menu.
Setting the filetype can also be done with a |modeline|, so that the
file will be highlighted each time you edit it. For example, this
line can be used in a Makefile (put it near the start or end of the
file): >
# vim: syntax=make
< You might know how to detect the file type yourself. Often the file
name extension (after the dot) can be used.
See |new-filetype| for how to tell Vim to detect that file type.
- There is no highlighting for your file type.
You could try using a similar file type by manually setting it as
mentioned above. If that isn't good enough, you can write your own
syntax file, see |mysyntaxfile|.
Or the colors could be wrong:
- The colored text is very hard to read.
Vim guesses the background color that you are using. If it is black
(or another dark color) it will use light colors for text. If it is
white (or another light color) it will use dark colors for text. If
Vim guessed wrong the text will be hard to read. To solve this, set
the 'background' option. For a dark background: >
:set background=dark
< And for a light background: >
:set background=light
< Make sure you put this _before_ the ":syntax enable" command,
otherwise the colors will already have been set. You could do
":syntax reset" after setting 'background' to make Vim set the default
colors again.
- The colors are wrong when scrolling bottom to top.
Vim doesn't read the whole file to parse the text. It starts parsing
wherever you are viewing the file. That saves a lot of time, but
sometimes the colors are wrong. A simple fix is hitting CTRL-L. Or
scroll back a bit and then forward again.
For a real fix, see |:syn-sync|. Some syntax files have a way to make
it look further back, see the help for the specific syntax file. For
example, |tex.vim| for the TeX syntax.
==============================================================================
*06.3* Different colors *:syn-default-override*
If you don't like the default colors, you can select another color scheme. In
the GUI use the Edit/Color Scheme menu. You can also type the command: >
:colorscheme evening
"evening" is the name of the color scheme. There are several others you might
want to try out. Look in the directory $VIMRUNTIME/colors.
When you found the color scheme that you like, add the ":colorscheme" command
to your |vimrc| file.
You could also write your own color scheme. This is how you do it:
1. Select a color scheme that comes close. Copy this file to your own Vim
directory. For Unix, this should work: >
!mkdir ~/.vim/colors
!cp $VIMRUNTIME/colors/morning.vim ~/.vim/colors/mine.vim
<
This is done from Vim, because it knows the value of $VIMRUNTIME.
2. Edit the color scheme file. These entries are useful:
term attributes in a B&W terminal
cterm attributes in a color terminal
ctermfg foreground color in a color terminal
ctermbg background color in a color terminal
gui attributes in the GUI
guifg foreground color in the GUI
guibg background color in the GUI
For example, to make comments green: >
:highlight Comment ctermfg=green guifg=green
<
Attributes you can use for "cterm" and "gui" are "bold" and "underline".
If you want both, use "bold,underline". For details see the |:highlight|
command.
3. Tell Vim to always use your color scheme. Put this line in your |vimrc|: >
colorscheme mine
If you want to see what the most often used color combinations look like, use
these commands: >
:edit $VIMRUNTIME/syntax/colortest.vim
:source %
You will see text in various color combinations. You can check which ones are
readable and look nice.
==============================================================================
*06.4* With colors or without colors
Displaying text in color takes a lot of effort. If you find the displaying
too slow, you might want to disable syntax highlighting for a moment: >
:syntax clear
When editing another file (or the same one) the colors will come back.
*:syn-off*
If you want to stop highlighting completely use: >
:syntax off
This will completely disable syntax highlighting and remove it immediately for
all buffers.
*:syn-manual*
If you want syntax highlighting only for specific files, use this: >
:syntax manual
This will enable the syntax highlighting, but not switch it on automatically
when starting to edit a buffer. To switch highlighting on for the current
buffer, set the 'syntax' option: >
:set syntax=ON
<
==============================================================================
*06.5* Printing with colors *syntax-printing*
In the MS-Windows version you can print the current file with this command: >
:hardcopy
You will get the usual printer dialog, where you can select the printer and a
few settings. If you have a color printer, the paper output should look the
same as what you see inside Vim. But when you use a dark background the
colors will be adjusted to look good on white paper.
There are several options that change the way Vim prints:
'printdevice'
'printheader'
'printfont'
'printoptions'
To print only a range of lines, use Visual mode to select the lines and then
type the command: >
v100j:hardcopy
"v" starts Visual mode. "100j" moves a hundred lines down, they will be
highlighted. Then ":hardcopy" will print those lines. You can use other
commands to move in Visual mode, of course.
This also works on Unix, if you have a PostScript printer. Otherwise, you
will have to do a bit more work. You need to convert the text to HTML first,
and then print it from a web browser such as Netscape.
Convert the current file to HTML with this command: >
:source $VIMRUNTIME/syntax/2html.vim
You will see it crunching away, this can take quite a while for a large file.
Some time later another window shows the HTML code. Now write this somewhere
(doesn't matter where, you throw it away later):
>
:write main.c.html
Open this file in your favorite browser and print it from there. If all goes
well, the output should look exactly as it does in Vim. See |2html.vim| for
details. Don't forget to delete the HTML file when you are done with it.
Instead of printing, you could also put the HTML file on a web server, and let
others look at the colored text.
==============================================================================
*06.6* Further reading
|usr_44.txt| Your own syntax highlighted.
|syntax| All the details.
==============================================================================
Next chapter: |usr_07.txt| Editing more than one file
Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:

479
runtime/doc/usr_07.txt Normal file
View File

@@ -0,0 +1,479 @@
*usr_07.txt* For Vim version 7.0aa. Last change: 2004 Mar 12
VIM USER MANUAL - by Bram Moolenaar
Editing more than one file
No matter how many files you have, you can edit them without leaving Vim.
Define a list of files to work on and jump from one to the other. Copy text
from one file and put it in another one.
|07.1| Edit another file
|07.2| A list of files
|07.3| Jumping from file to file
|07.4| Backup files
|07.5| Copy text between files
|07.6| Viewing a file
|07.7| Changing the file name
Next chapter: |usr_08.txt| Splitting windows
Previous chapter: |usr_06.txt| Using syntax highlighting
Table of contents: |usr_toc.txt|
==============================================================================
*07.1* Edit another file
So far you had to start Vim for every file you wanted to edit. There is a
simpler way. To start editing another file, use this command: >
:edit foo.txt
You can use any file name instead of "foo.txt". Vim will close the current
file and open the new one. If the current file has unsaved changes, however,
Vim displays an error message and does not open the new file:
E37: No write since last change (use ! to override) ~
Note:
Vim puts an error ID at the start of each error message. If you do
not understand the message or what caused it, look in the help system
for this ID. In this case: >
:help E37
At this point, you have a number of alternatives. You can write the file
using this command: >
:write
Or you can force Vim to discard your changes and edit the new file, using the
force (!) character: >
:edit! foo.txt
If you want to edit another file, but not write the changes in the current
file yet, you can make it hidden: >
:hide edit foo.txt
The text with changes is still there, but you can't see it. This is further
explained in section |22.4|: The buffer list.
==============================================================================
*07.2* A list of files
You can start Vim to edit a sequence of files. For example: >
vim one.c two.c three.c
This command starts Vim and tells it that you will be editing three files.
Vim displays just the first file. After you have done your thing in this
file, to edit the next file you use this command: >
:next
If you have unsaved changes in the current file, you will get an error
message and the ":next" will not work. This is the same problem as with
":edit" mentioned in the previous section. To abandon the changes: >
:next!
But mostly you want to save the changes and move on to the next file. There
is a special command for this: >
:wnext
This does the same as using two separate commands: >
:write
:next
WHERE AM I?
To see which file in the argument list you are editing, look in the window
title. It should show something like "(2 of 3)". This means you are editing
the second file out of three files.
If you want to see the list of files, use this command: >
:args
This is short for "arguments". The output might look like this:
one.c [two.c] three.c ~
These are the files you started Vim with. The one you are currently editing,
"two.c", is in square brackets.
MOVING TO OTHER ARGUMENTS
To go back one file: >
:previous
This is just like the ":next" command, except that it moves in the other
direction. Again, there is a shortcut command for when you want to write the
file first: >
:wprevious
To move to the very last file in the list: >
:last
And to move back to the first one again: >
:first
There is no ":wlast" or ":wfirst" command though!
You can use a count for ":next" and ":previous". To skip two files forward: >
:2next
AUTOMATIC WRITING
When moving around the files and making changes, you have to remember to use
":write". Otherwise you will get an error message. If you are sure you
always want to write modified files, you can tell Vim to automatically write
them: >
:set autowrite
When you are editing a file which you may not want to write, switch it off
again: >
:set noautowrite
EDITING ANOTHER LIST OF FILES
You can redefine the list of files without the need to exit Vim and start it
again. Use this command to edit three other files: >
:args five.c six.c seven.h
Or use a wildcard, like it's used in the shell: >
:args *.txt
Vim will take you to the first file in the list. Again, if the current file
has changes, you can either write the file first, or use ":args!" (with !
added) to abandon the changes.
DID YOU EDIT THE LAST FILE?
*arglist-quit*
When you use a list of files, Vim assumes you want to edit them all. To
protect you from exiting too early, you will get this error when you didn't
edit the last file in the list yet:
E173: 46 more files to edit ~
If you really want to exit, just do it again. Then it will work (but not when
you did other commands in between).
==============================================================================
*07.3* Jumping from file to file
To quickly jump between two files, press CTRL-^ (on English-US keyboards the ^
is above the 6 key). Example: >
:args one.c two.c three.c
You are now in one.c. >
:next
Now you are in two.c. Now use CTRL-^ to go back to one.c. Another CTRL-^ and
you are back in two.c. Another CTRL-^ and you are in one.c again. If you now
do: >
:next
You are in three.c. Notice that the CTRL-^ command does not change the idea
of where you are in the list of files. Only commands like ":next" and
":previous" do that.
The file you were previously editing is called the "alternate" file. When you
just started Vim CTRL-^ will not work, since there isn't a previous file.
PREDEFINED MARKS
After jumping to another file, you can use two predefined marks which are very
useful: >
`"
This takes you to the position where the cursor was when you left the file.
Another mark that is remembered is the position where you made the last
change: >
`.
Suppose you are editing the file "one.txt". Somewhere halfway the file you
use "x" to delete a character. Then you go to the last line with "G" and
write the file with ":w". You edit several other files, and then use ":edit
one.txt" to come back to "one.txt". If you now use `" Vim jumps to the last
line of the file. Using `. takes you to the position where you deleted the
character. Even when you move around in the file `" and `. will take you to
the remembered position. At least until you make another change or leave the
file.
FILE MARKS
In chapter 4 was explained how you can place a mark in a file with "mx" and
jump to that position with "`x". That works within one file. If you edit
another file and place marks there, these are specific for that file. Thus
each file has its own set of marks, they are local to the file.
So far we were using marks with a lowercase letter. There are also marks
with an uppercase letter. These are global, they can be used from any file.
For example suppose that we are editing the file "foo.txt". Go to halfway the
file ("50%") and place the F mark there (F for foo): >
50%mF
Now edit the file "bar.txt" and place the B mark (B for bar) at its last line:
>
GmB
Now you can use the "'F" command to jump back to halfway foo.txt. Or edit yet
another file, type "'B" and you are at the end of bar.txt again.
The file marks are remembered until they are placed somewhere else. Thus you
can place the mark, do hours of editing and still be able to jump back to that
mark.
It's often useful to think of a simple connection between the mark letter
and where it is placed. For example, use the H mark in a header file, M in
a Makefile and C in a C code file.
To see where a specific mark is, give an argument to the ":marks" command: >
:marks M
You can also give several arguments: >
:marks MCP
Don't forget that you can use CTRL-O and CTRL-I to jump to older and newer
positions without placing marks there.
==============================================================================
*07.4* Backup files
Usually Vim does not produce a backup file. If you want to have one, all you
need to do is execute the following command: >
:set backup
The name of the backup file is the original file with a ~ added to the end.
If your file is named data.txt, for example, the backup file name is
data.txt~.
If you do not like the fact that the backup files end with ~, you can
change the extension: >
:set backupext=.bak
This will use data.txt.bak instead of data.txt~.
Another option that matters here is 'backupdir'. It specifies where the
backup file is written. The default, to write the backup in the same
directory as the original file, will mostly be the right thing.
Note:
When the 'backup' option isn't set but the 'writebackup' is, Vim will
still create a backup file. However, it is deleted as soon as writing
the file was completed successfully. This functions as a safety
against losing your original file when writing fails in some way (disk
full is the most common cause; being hit by lightning might be
another, although less common).
KEEPING THE ORIGINAL FILE
If you are editing source files, you might want to keep the file before you
make any changes. But the backup file will be overwritten each time you write
the file. Thus it only contains the previous version, not the first one.
To make Vim keep the original file, set the 'patchmode' option. This
specifies the extension used for the first backup of a changed file. Usually
you would do this: >
:set patchmode=.orig
When you now edit the file data.txt for the first time, make changes and write
the file, Vim will keep a copy of the unchanged file under the name
"data.txt.orig".
If you make further changes to the file, Vim will notice that
"data.txt.orig" already exists and leave it alone. Further backup files will
then be called "data.txt~" (or whatever you specified with 'backupext').
If you leave 'patchmode' empty (that is the default), the original file
will not be kept.
==============================================================================
*07.5* Copy text between files
This explains how to copy text from one file to another. Let's start with a
simple example. Edit the file that contains the text you want to copy. Move
the cursor to the start of the text and press "v". This starts Visual mode.
Now move the cursor to the end of the text and press "y". This yanks (copies)
the selected text.
To copy the above paragraph, you would do: >
:edit thisfile
/This
vjjjj$y
Now edit the file you want to put the text in. Move the cursor to the
character where you want the text to appear after. Use "p" to put the text
there. >
:edit otherfile
/There
p
Of course you can use many other commands to yank the text. For example, to
select whole lines start Visual mode with "V". Or use CTRL-V to select a
rectangular block. Or use "Y" to yank a single line, "yaw" to yank-a-word,
etc.
The "p" command puts the text after the cursor. Use "P" to put the text
before the cursor. Notice that Vim remembers if you yanked a whole line or a
block, and puts it back that way.
USING REGISTERS
When you want to copy several pieces of text from one file to another, having
to switch between the files and writing the target file takes a lot of time.
To avoid this, copy each piece of text to its own register.
A register is a place where Vim stores text. Here we will use the
registers named a to z (later you will find out there are others). Let's copy
a sentence to the f register (f for First): >
"fyas
The "yas" command yanks a sentence like before. It's the "f that tells Vim
the text should be place in the f register. This must come just before the
yank command.
Now yank three whole lines to the l register (l for line): >
"l3Y
The count could be before the "l just as well. To yank a block of text to the
b (for block) register: >
CTRL-Vjjww"by
Notice that the register specification "b is just before the "y" command.
This is required. If you would have put it before the "w" command, it would
not have worked.
Now you have three pieces of text in the f, l and b registers. Edit
another file, move around and place the text where you want it: >
"fp
Again, the register specification "f comes before the "p" command.
You can put the registers in any order. And the text stays in the register
until you yank something else into it. Thus you can put it as many times as
you like.
When you delete text, you can also specify a register. Use this to move
several pieces of text around. For example, to delete-a-word and write it in
the w register: >
"wdaw
Again, the register specification comes before the delete command "d".
APPENDING TO A FILE
When collecting lines of text into one file, you can use this command: >
:write >> logfile
This will write the text of the current file to the end of "logfile". Thus it
is appended. This avoids that you have to copy the lines, edit the log file
and put them there. Thus you save two steps. But you can only append to the
end of a file.
To append only a few lines, select them in Visual mode before typing
":write". In chapter 10 you will learn other ways to select a range of lines.
==============================================================================
*07.6* Viewing a file
Sometimes you only want to see what a file contains, without the intention to
ever write it back. There is the risk that you type ":w" without thinking and
overwrite the original file anyway. To avoid this, edit the file read-only.
To start Vim in readonly mode, use this command: >
vim -R file
On Unix this command should do the same thing: >
view file
You are now editing "file" in read-only mode. When you try using ":w" you
will get an error message and the file won't be written.
When you try to make a change to the file Vim will give you a warning:
W10: Warning: Changing a readonly file ~
The change will be done though. This allows for formatting the file, for
example, to be able to read it easily.
If you make changes to a file and forgot that it was read-only, you can
still write it. Add the ! to the write command to force writing.
If you really want to forbid making changes in a file, do this: >
vim -M file
Now every attempt to change the text will fail. The help files are like this,
for example. If you try to make a change you get this error message:
E21: Cannot make changes, 'modifiable' is off ~
You could use the -M argument to setup Vim to work in a viewer mode. This is
only voluntary though, since these commands will remove the protection: >
:set modifiable
:set write
==============================================================================
*07.7* Changing the file name
A clever way to start editing a new file is by using an existing file that
contains most of what you need. For example, you start writing a new program
to move a file. You know that you already have a program that copies a file,
thus you start with: >
:edit copy.c
You can delete the stuff you don't need. Now you need to save the file under
a new name. The ":saveas" command can be used for this: >
:saveas move.c
Vim will write the file under the given name, and edit that file. Thus the
next time you do ":write", it will write "move.c". "copy.c" remains
unmodified.
When you want to change the name of the file you are editing, but don't
want to write the file, you can use this command: >
:file move.c
Vim will mark the file as "not edited". This means that Vim knows this is not
the file you started editing. When you try to write the file, you might get
this message:
E13: File exists (use ! to override) ~
This protects you from accidentally overwriting another file.
==============================================================================
Next chapter: |usr_08.txt| Splitting windows
Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:

511
runtime/doc/usr_08.txt Normal file
View File

@@ -0,0 +1,511 @@
*usr_08.txt* For Vim version 7.0aa. Last change: 2004 Jun 04
VIM USER MANUAL - by Bram Moolenaar
Splitting windows
Display two different files above each other. Or view two locations in the
file at the same time. See the difference between two files by putting them
side by side. All this is possible with split windows.
|08.1| Split a window
|08.2| Split a window on another file
|08.3| Window size
|08.4| Vertical splits
|08.5| Moving windows
|08.6| Commands for all windows
|08.7| Viewing differences with vimdiff
|08.8| Various
Next chapter: |usr_09.txt| Using the GUI
Previous chapter: |usr_07.txt| Editing more than one file
Table of contents: |usr_toc.txt|
==============================================================================
*08.1* Split a window
The easiest way to open a new window is to use the following command: >
:split
This command splits the screen into two windows and leaves the cursor in the
top one:
+----------------------------------+
|/* file one.c */ |
|~ |
|~ |
|one.c=============================|
|/* file one.c */ |
|~ |
|one.c=============================|
| |
+----------------------------------+
What you see here is two windows on the same file. The line with "====" is
that status line. It displays information about the window above it. (In
practice the status line will be in reverse video.)
The two windows allow you to view two parts of the same file. For example,
you could make the top window show the variable declarations of a program, and
the bottom one the code that uses these variables.
The CTRL-W w command can be used to jump between the windows. If you are in
the top window, CTRL-W w jumps to the window below it. If you are in the
bottom window it will jump to the first window. (CTRL-W CTRL-W does the same
thing, in case you let go of the CTRL key a bit later.)
CLOSE THE WINDOW
To close a window, use the command: >
:close
Actually, any command that quits editing a file works, like ":quit" and "ZZ".
But ":close" prevents you from accidentally exiting Vim when you close the
last window.
CLOSING ALL OTHER WINDOWS
If you have opened a whole bunch of windows, but now want to concentrate on
one of them, this command will be useful: >
:only
This closes all windows, except for the current one. If any of the other
windows has changes, you will get an error message and that window won't be
closed.
==============================================================================
*08.2* Split a window on another file
The following command opens a second window and starts editing the given file:
>
:split two.c
If you were editing one.c, then the result looks like this:
+----------------------------------+
|/* file two.c */ |
|~ |
|~ |
|two.c=============================|
|/* file one.c */ |
|~ |
|one.c=============================|
| |
+----------------------------------+
To open a window on a new, empty file, use this: >
:new
You can repeat the ":split" and ":new" commands to create as many windows as
you like.
==============================================================================
*08.3* Window size
The ":split" command can take a number argument. If specified, this will be
the height of the new window. For example, the following opens a new window
three lines high and starts editing the file alpha.c: >
:3split alpha.c
For existing windows you can change the size in several ways. When you have a
working mouse, it is easy: Move the mouse pointer to the status line that
separates two windows, and drag it up or down.
To increase the size of a window: >
CTRL-W +
To decrease it: >
CTRL-W -
Both of these commands take a count and increase or decrease the window size
by that many lines. Thus "4 CTRL-W +" make the window four lines higher.
To set the window height to a specified number of lines: >
{height}CTRL-W _
That's: a number {height}, CTRL-W and then an underscore (the - key with Shift
on English-US keyboards).
To make a window as high as it can be, use the CTRL-W _ command without a
count.
USING THE MOUSE
In Vim you can do many things very quickly from the keyboard. Unfortunately,
the window resizing commands require quite a bit of typing. In this case,
using the mouse is faster. Position the mouse pointer on a status line. Now
press the left mouse button and drag. The status line will move, thus making
the window on one side higher and the other smaller.
OPTIONS
The 'winheight' option can be set to a minimal desired height of a window and
'winminheight' to a hard minimum height.
Likewise, there is 'winwidth' for the minimal desired width and
'winminwidth' for the hard minimum width.
The 'equalalways' option, when set, makes Vim equalize the windows sizes
when a window is closed or opened.
==============================================================================
*08.4* Vertical splits
The ":split" command creates the new window above the current one. To make
the window appear at the left side, use: >
:vsplit
or: >
:vsplit two.c
The result looks something like this:
+--------------------------------------+
|/* file two.c */ |/* file one.c */ |
|~ |~ |
|~ |~ |
|~ |~ |
|two.c===============one.c=============|
| |
+--------------------------------------+
Actually, the | lines in the middle will be in reverse video. This is called
the vertical separator. It separates the two windows left and right of it.
There is also the ":vnew" command, to open a vertically split window on a new,
empty file. Another way to do this: >
:vertical new
The ":vertical" command can be inserted before another command that splits a
window. This will cause that command to split the window vertically instead
of horizontally. (If the command doesn't split a window, it works
unmodified.)
MOVING BETWEEN WINDOWS
Since you can split windows horizontally and vertically as much as you like,
you can create any layout of windows. Then you can use these commands to move
between them:
CTRL-W h move to the window on the left
CTRL-W j move to the window below
CTRL-W k move to the window above
CTRL-W l move to the window on the right
CTRL-W t move to the TOP window
CTRL-W b move to the BOTTOM window
You will notice the same letters as used for moving the cursor. And the
cursor keys can also be used, if you like.
More commands to move to other windows: |Q_wi|.
==============================================================================
*08.5* Moving windows
You have split a few windows, but now they are in the wrong place. Then you
need a command to move the window somewhere else. For example, you have three
windows like this:
+----------------------------------+
|/* file two.c */ |
|~ |
|~ |
|two.c=============================|
|/* file three.c */ |
|~ |
|~ |
|three.c===========================|
|/* file one.c */ |
|~ |
|one.c=============================|
| |
+----------------------------------+
Clearly the last one should be at the top. Go to that window (using CTRL-W w)
and the type this command: >
CTRL-W K
This uses the uppercase letter K. What happens is that the window is moved to
the very top. You will notice that K is again used for moving upwards.
When you have vertical splits, CTRL-W K will move the current window to the
top and make it occupy the full with of the Vim window. If this is your
layout:
+-------------------------------------------+
|/* two.c */ |/* three.c */ |/* one.c */ |
|~ |~ |~ |
|~ |~ |~ |
|~ |~ |~ |
|~ |~ |~ |
|~ |~ |~ |
|two.c=========three.c=========one.c========|
| |
+-------------------------------------------+
Then using CTRL-W K in the middle window (three.c) will result in:
+-------------------------------------------+
|/* three.c */ |
|~ |
|~ |
|three.c====================================|
|/* two.c */ |/* one.c */ |
|~ |~ |
|two.c==================one.c===============|
| |
+-------------------------------------------+
The other three similar commands (you can probably guess these now):
CTRL-W H move window to the far left
CTRL-W J move window to the bottom
CTRL-W L move window to the far right
==============================================================================
*08.6* Commands for all windows
When you have several windows open and you want to quit Vim, you can close
each window separately. A quicker way is using this command: >
:qall
This stands for "quit all". If any of the windows contain changes, Vim will
not exit. The cursor will automatically be positioned in a window with
changes. You can then either use ":write" to save the changes, or ":quit!" to
throw them away.
If you know there are windows with changes, and you want to save all these
changes, use this command: >
:wall
This stands for "write all". But actually, it only writes files with
changes. Vim knows it doesn't make sense to write files that were not
changed.
And then there is the combination of ":qall" and ":wall": the "write and
quit all" command: >
:wqall
This writes all modified files and quits Vim.
Finally, there is a command that quits Vim and throws away all changes: >
:qall!
Be careful, there is no way to undo this command!
OPENING A WINDOW FOR ALL ARGUMENTS
To make Vim open a window for each file, start it with the "-o" argument: >
vim -o one.txt two.txt three.txt
This results in:
+-------------------------------+
|file one.txt |
|~ |
|one.txt========================|
|file two.txt |
|~ |
|two.txt========================|
|file three.txt |
|~ |
|three.txt======================|
| |
+-------------------------------+
The "-O" argument is used to get vertically split windows.
When Vim is already running, the ":all" command opens a window for each
file in the argument list. ":vertical all" does it with vertical splits.
==============================================================================
*08.7* Viewing differences with vimdiff
There is a special way to start Vim, which shows the differences between two
files. Let's take a file "main.c" and insert a few characters in one line.
Write this file with the 'backup' option set, so that the backup file
"main.c~" will contain the previous version of the file.
Type this command in a shell (not in Vim): >
vimdiff main.c~ main.c
Vim will start, with two windows side by side. You will only see the line
in which you added characters, and a few lines above and below it.
VV VV
+-----------------------------------------+
|+ +--123 lines: /* a|+ +--123 lines: /* a| <- fold
| text | text |
| text | text |
| text | text |
| text | changed text | <- changed line
| text | text |
| text | ------------------| <- deleted line
| text | text |
| text | text |
| text | text |
|+ +--432 lines: text|+ +--432 lines: text| <- fold
| ~ | ~ |
| ~ | ~ |
|main.c~==============main.c==============|
| |
+-----------------------------------------+
(This picture doesn't show the highlighting, use the vimdiff command for a
better look.)
The lines that were not modified have been collapsed into one line. This is
called a closed fold. They are indicated in the picture with "<- fold". Thus
the single fold line at the top stands for 123 text lines. These lines are
equal in both files.
The line marked with "<- changed line" is highlighted, and the inserted
text is displayed with another color. This clearly shows what the difference
is between the two files.
The line that was deleted is displayed with "---" in the main.c window.
See the "<- deleted line" marker in the picture. These characters are not
really there. They just fill up main.c, so that it displays the same number
of lines as the other window.
THE FOLD COLUMN
Each window has a column on the left with a slightly different background. In
the picture above these are indicated with "VV". You notice there is a plus
character there, in front of each closed fold. Move the mouse pointer to that
plus and click the left button. The fold will open, and you can see the text
that it contains.
The fold column contains a minus sign for an open fold. If you click on
this -, the fold will close.
Obviously, this only works when you have a working mouse. You can also use
"zo" to open a fold and "zc" to close it.
DIFFING IN VIM
Another way to start in diff mode can be done from inside Vim. Edit the
"main.c" file, then make a split and show the differences: >
:edit main.c
:vertical diffsplit main.c~
The ":vertical" command is used to make the window split vertically. If you
omit this, you will get a horizontal split.
If you have a patch or diff file, you can use the third way to start diff
mode. First edit the file to which the patch applies. Then tell Vim the name
of the patch file: >
:edit main.c
:vertical diffpatch main.c.diff
WARNING: The patch file must contain only one patch, for the file you are
editing. Otherwise you will get a lot of error messages, and some files might
be patched unexpectedly.
The patching will only be done to the copy of the file in Vim. The file on
your harddisk will remain unmodified (until you decide to write the file).
SCROLL BINDING
When the files have more changes, you can scroll in the usual way. Vim will
try to keep both the windows start at the same position, so you can easily see
the differences side by side.
When you don't want this for a moment, use this command: >
:set noscrollbind
JUMPING TO CHANGES
When you have disabled folding in some way, it may be difficult to find the
changes. Use this command to jump forward to the next change: >
]c
To go the other way use: >
[c
Prepended a count to jump further away.
REMOVING CHANGES
You can move text from one window to the other. This either removes
differences or adds new ones. Vim doesn't keep the highlighting updated in
all situations. To update it use this command: >
:diffupdate
To remove a difference, you can move the text in a highlighted block from one
window to another. Take the "main.c" and "main.c~" example above. Move the
cursor to the left window, on the line that was deleted in the other window.
Now type this command: >
dp
The change will be removed by putting the text of the current window in the
other window. "dp" stands for "diff put".
You can also do it the other way around. Move the cursor to the right
window, to the line where "changed" was inserted. Now type this command: >
do
The change will now be removed by getting the text from the other window.
Since there are no changes left now, Vim puts all text in a closed fold.
"do" stands for "diff obtain". "dg" would have been better, but that already
has a different meaning ("dgg" deletes from the cursor until the first line).
For details about diff mode, see |vimdiff|.
==============================================================================
*08.8* Various
The 'laststatus' option can be used to specify when the last window has a
statusline:
0 never
1 only when there are split windows (the default)
2 always
Many commands that edit another file have a variant that splits the window.
For Command-line commands this is done by prepending an "s". For example:
":tag" jumps to a tag, ":stag" splits the window and jumps to a
tag.
For Normal mode commands a CTRL-W is prepended. CTRL-^ jumps to the
alternate file, CTRL-W CTRL-^ splits the window and edits the alternate file.
The 'splitbelow' option can be set to make a new window appear below the
current window. The 'splitright' option can be set to make a vertically split
window appear right of the current window.
When splitting a window you can prepend a modifier command to tell where the
window is to appear:
:leftabove {cmd} left or above the current window
:aboveleft {cmd} idem
:rightbelow {cmd} right or below the current window
:belowright {cmd} idem
:topleft {cmd} at the top or left of the Vim window
:botright {cmd} at the bottom or right of the Vim window
==============================================================================
Next chapter: |usr_09.txt| Using the GUI
Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:

289
runtime/doc/usr_09.txt Normal file
View File

@@ -0,0 +1,289 @@
*usr_09.txt* For Vim version 7.0aa. Last change: 2001 Sep 03
VIM USER MANUAL - by Bram Moolenaar
Using the GUI
Vim works in an ordinary terminal. GVim can do the same things and a few
more. The GUI offers menus, a toolbar, scrollbars and other items. This
chapter is about these extra things that the GUI offers.
|09.1| Parts of the GUI
|09.2| Using the mouse
|09.3| The clipboard
|09.4| Select mode
Next chapter: |usr_10.txt| Making big changes
Previous chapter: |usr_08.txt| Splitting windows
Table of contents: |usr_toc.txt|
==============================================================================
*09.1* Parts of the GUI
You might have an icon on your desktop that starts gVim. Otherwise, one of
these commands should do it: >
gvim file.txt
vim -g file.txt
If this doesn't work you don't have a version of Vim with GUI support. You
will have to install one first.
Vim will open a window and display "file.txt" in it. What the window looks
like depends on the version of Vim. It should resemble the following picture
(for as far as this can be shown in ASCII!).
+----------------------------------------------------+
| file.txt + (~/dir) - VIM X | <- window title
+----------------------------------------------------+
| File Edit Tools Syntax Buffers Window Help | <- menubar
+----------------------------------------------------+
| aaa bbb ccc ddd eee fff ggg hhh iii jjj | <- toolbar
| aaa bbb ccc ddd eee fff ggg hhh iii jjj |
+----------------------------------------------------+
| file text | ^ |
| ~ | # |
| ~ | # | <- scrollbar
| ~ | # |
| ~ | # |
| ~ | # |
| | V |
+----------------------------------------------------+
The largest space is occupied by the file text. This shows the file in the
same way as in a terminal. With some different colors and another font
perhaps.
THE WINDOW TITLE
At the very top is the window title. This is drawn by your window system.
Vim will set the title to show the name of the current file. First comes the
name of the file. Then some special characters and the directory of the file
in parens. These special character can be present:
- The file cannot be modified (e.g., a help file)
+ The file contains changes
= The file is read-only
=+ The file is read-only, contains changes anyway
If nothing is shown you have an ordinary, unchanged file.
THE MENUBAR
You know how menus work, right? Vim has the usual items, plus a few more.
Browse them to get an idea of what you can use them for. A relevant submenu
is Edit/Global Settings. You will find these entries:
Toggle Toolbar make the toolbar appear/disappear
Toggle Bottom Scrollbar make a scrollbar appear/disappear at the bottom
Toggle Left Scrollbar make a scrollbar appear/disappear at the left
Toggle Right Scrollbar make a scrollbar appear/disappear at the right
On most systems you can tear-off the menus. Select the top item of the menu,
the one that looks like a dashed line. You will get a separate window with
the items of the menu. It will hang around until you close the window.
THE TOOLBAR
This contains icons for the most often used actions. Hopefully the icons are
self-explanatory. There are tooltips to get an extra hint (move the mouse
pointer to the icon without clicking and don't move it for a second).
The "Edit/Global Settings/Toggle Toolbar" menu item can be used to make the
toolbar disappear. If you never want a toolbar, use this command in your
vimrc file: >
:set guioptions-=T
This removes the 'T' flag from the 'guioptions' option. Other parts of the
GUI can also be enabled or disabled with this option. See the help for it.
THE SCROLLBARS
By default there is one scrollbar on the right. It does the obvious thing.
When you split the window, each window will get its own scrollbar.
You can make a horizontal scrollbar appear with the menu item
Edit/Global Settings/Toggle Bottom Scrollbar. This is useful in diff mode, or
when the 'wrap' option has been reset (more about that later).
When there are vertically split windows, only the windows on the right side
will have a scrollbar. However, when you move the cursor to a window on the
left, it will be this one the that scrollbar controls. This takes a bit of
time to get used to.
When you work with vertically split windows, consider adding a scrollbar on
the left. This can be done with a menu item, or with the 'guioptions' option:
>
:set guioptions+=l
This adds the 'l' flag to 'guioptions'.
==============================================================================
*09.2* Using the mouse
Standards are wonderful. In Microsoft Windows, you can use the mouse to
select text in a standard manner. The X Window system also has a standard
system for using the mouse. Unfortunately, these two standards are not the
same.
Fortunately, you can customize Vim. You can make the behavior of the mouse
work like an X Window system mouse or a Microsoft Windows mouse. The following
command makes the mouse behave like an X Window mouse: >
:behave xterm
The following command makes the mouse work like a Microsoft Windows mouse: >
:behave mswin
The default behavior of the mouse on UNIX systems is xterm. The default
behavior on a Microsoft Windows system is selected during the installation
process. For details about what the two behaviors are, see |:behave|. Here
follows a summary.
XTERM MOUSE BEHAVIOR
Left mouse click position the cursor
Left mouse drag select text in Visual mode
Middle mouse click paste text from the clipboard
Right mouse click extend the selected text until the mouse
pointer
MSWIN MOUSE BEHAVIOR
Left mouse click position the cursor
Left mouse drag select text in Select mode (see |09.4|)
Left mouse click, with Shift extend the selected text until the mouse
pointer
Middle mouse click paste text from the clipboard
Right mouse click display a pop-up menu
The mouse can be further tuned. Check out these options if you want to change
the way how the mouse works:
'mouse' in which mode the mouse is used by Vim
'mousemodel' what effect a mouse click has
'mousetime' time between clicks for a double-click
'mousehide' hide the mouse while typing
'selectmode' whether the mouse starts Visual or Select mode
==============================================================================
*09.3* The clipboard
In section |04.7| the basic use of the clipboard was explained. There is one
essential thing to explain about X-windows: There are actually two places to
exchange text between programs. MS-Windows doesn't have this.
In X-Windows there is the "current selection". This is the text that is
currently highlighted. In Vim this is the Visual area (this assumes you are
using the default option settings). You can paste this selection in another
application without any further action.
For example, in this text select a few words with the mouse. Vim will
switch to Visual mode and highlight the text. Now start another gVim, without
a file name argument, so that it displays an empty window. Click the middle
mouse button. The selected text will be inserted.
The "current selection" will only remain valid until some other text is
selected. After doing the paste in the other gVim, now select some characters
in that window. You will notice that the words that were previously selected
in the other gVim window are displayed differently. This means that it no
longer is the current selection.
You don't need to select text with the mouse, using the keyboard commands for
Visual mode works just as well.
THE REAL CLIPBOARD
Now for the other place with which text can be exchanged. We call this the
"real clipboard", to avoid confusion. Often both the "current selection" and
the "real clipboard" are called clipboard, you'll have to get used to that.
To put text on the real clipboard, select a few different words in one of
the gVims you have running. Then use the Edit/Copy menu entry. Now the text
has been copied to the real clipboard. You can't see this, unless you have
some application that shows the clipboard contents (e.g., KDE's klipper).
Now select the other gVim, position the cursor somewhere and use the
Edit/Paste menu. You will see the text from the real clipboard is inserted.
USING BOTH
This use of both the "current selection" and the "real clipboard" might sound
a bit confusing. But it is very useful. Let's show this with an example.
Use one gVim with a text file and perform these actions:
- Select two words in Visual mode.
- Use the Edit/Copy menu to get these words onto the clipboard.
- Select one other word in Visual mode.
- Use the Edit/Paste menu item. What will happen is that the single selected
word is replaced with the two words from the clipboard.
- Move the mouse pointer somewhere else and click the middle button. You
will see that the word you just overwrote with the clipboard is inserted
here.
If you use the "current selection" and the "real clipboard" with care, you can
do a lot of useful editing with them.
USING THE KEYBOARD
If you don't like using the mouse, you can access the current selection and
the real clipboard with two registers. The "* register is for the current
selection.
To make text become the current selection, use Visual mode. For example,
to select a whole line just press "V".
To insert the current selection before the cursor: >
"*P
Notice the uppercase "P". The lowercase "p" puts the text after the cursor.
The "+ register is used for the real clipboard. For example, to copy the text
from the cursor position until the end of the line to the clipboard: >
"+y$
Remember, "y" is yank, which is Vim's copy command.
To insert the contents of the real clipboard before the cursor: >
"+P
It's the same as for the current selection, but uses the plus (+) register
instead of the star (*) register.
==============================================================================
*09.4* Select mode
And now something that is used more often on MS-Windows than on X-Windows.
But both can do it. You already know about Visual mode. Select mode is like
Visual mode, because it is also used to select text. But there is an obvious
difference: When typing text, the selected text is deleted and the typed text
replaces it.
To start working with Select mode, you must first enable it (for MS-Windows
it is probably already enabled, but you can do this anyway): >
:set selectmode+=mouse
Now use the mouse to select some text. It is highlighted like in Visual mode.
Now press a letter. The selected text is deleted, and the single letter
replaces it. You are in Insert mode now, thus you can continue typing.
Since typing normal text causes the selected text to be deleted, you can not
use the normal movement commands "hjkl", "w", etc. Instead, use the shifted
function keys. <S-Left> (shifted cursor left key) moves the cursor left. The
selected text is changed like in Visual mode. The other shifted cursor keys
do what you expect. <S-End> and <S-Home> also work.
You can tune the way Select mode works with the 'selectmode' option.
==============================================================================
Next chapter: |usr_10.txt| Making big changes
Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:

822
runtime/doc/usr_10.txt Normal file
View File

@@ -0,0 +1,822 @@
*usr_10.txt* For Vim version 7.0aa. Last change: 2004 Mar 12
VIM USER MANUAL - by Bram Moolenaar
Making big changes
In chapter 4 several ways to make small changes were explained. This chapter
goes into making changes that are repeated or can affect a large amount of
text. The Visual mode allows doing various things with blocks of text. Use
an external program to do really complicated things.
|10.1| Record and playback commands
|10.2| Substitution
|10.3| Command ranges
|10.4| The global command
|10.5| Visual block mode
|10.6| Reading and writing part of a file
|10.7| Formatting text
|10.8| Changing case
|10.9| Using an external program
Next chapter: |usr_11.txt| Recovering from a crash
Previous chapter: |usr_09.txt| Using the GUI
Table of contents: |usr_toc.txt|
==============================================================================
*10.1* Record and playback commands
The "." command repeats the preceding change. But what if you want to do
something more complex than a single change? That's where command recording
comes in. There are three steps:
1. The "q{register}" command starts recording keystrokes into the register
named {register}. The register name must be between a and z.
2. Type your commands.
3. To finish recording, press q (without any extra character).
You can now execute the macro by typing the command "@{register}".
Take a look at how to use these commands in practice. You have a list of
filenames that look like this:
stdio.h ~
fcntl.h ~
unistd.h ~
stdlib.h ~
And what you want is the following:
#include "stdio.h" ~
#include "fcntl.h" ~
#include "unistd.h" ~
#include "stdlib.h" ~
You start by moving to the first character of the first line. Next you
execute the following commands:
qa Start recording a macro in register a.
^ Move to the beginning of the line.
i#include "<Esc> Insert the string #include " at the beginning
of the line.
$ Move to the end of the line.
a"<Esc> Append the character double quotation mark (")
to the end of the line.
j Go to the next line.
q Stop recording the macro.
Now that you have done the work once, you can repeat the change by typing the
command "@a" three times.
The "@a" command can be preceded by a count, which will cause the macro to
be executed that number of times. In this case you would type: >
3@a
MOVE AND EXECUTE
You might have the lines you want to change in various places. Just move the
cursor to each location and use the "@a" command. If you have done that once,
you can do it again with "@@". That's a bit easier to type. If you now
execute register b with "@b", the next "@@" will use register b.
If you compare the playback method with using ".", there are several
differences. First of all, "." can only repeat one change. As seen in the
example above, "@a" can do several changes, and move around as well.
Secondly, "." can only remember the last change. Executing a register allows
you to make any changes and then still use "@a" to replay the recorded
commands. Finally, you can use 26 different registers. Thus you can remember
26 different command sequences to execute.
USING REGISTERS
The registers used for recording are the same ones you used for yank and
delete commands. This allows you to mix recording with other commands to
manipulate the registers.
Suppose you have recorded a few commands in register n. When you execute
this with "@n" you notice you did something wrong. You could try recording
again, but perhaps you will make another mistake. Instead, use this trick:
G Go to the end of the file.
o<Esc> Create an empty line.
"np Put the text from the n register. You now see
the commands you typed as text in the file.
{edits} Change the commands that were wrong. This is
just like editing text.
0 Go to the start of the line.
"ny$ Yank the corrected commands into the n
register.
dd Delete the scratch line.
Now you can execute the corrected commands with "@n". (If your recorded
commands include line breaks, adjust the last two items in the example to
include all the lines.)
APPENDING TO A REGISTER
So far we have used a lowercase letter for the register name. To append to a
register, use an uppercase letter.
Suppose you have recorded a command to change a word to register c. It
works properly, but you would like to add a search for the next word to
change. This can be done with: >
qC/word<Enter>q
You start with "qC", which records to the c register and appends. Thus
writing to an uppercase register name means to append to the register with
the same letter, but lowercase.
This works both with recording and with yank and delete commands. For
example, you want to collect a sequence of lines into the a register. Yank
the first line with: >
"aY
Now move to the second line, and type: >
"AY
Repeat this command for all lines. The a register now contains all those
lines, in the order you yanked them.
==============================================================================
*10.2* Substitution *find-replace*
The ":substitute" command enables you to perform string replacements on a
whole range of lines. The general form of this command is as follows: >
:[range]substitute/from/to/[flags]
This command changes the "from" string to the "to" string in the lines
specified with [range]. For example, you can change "Professor" to "Teacher"
in all lines with the following command: >
:%substitute/Professor/Teacher/
<
Note:
The ":substitute" command is almost never spelled out completely.
Most of the time, people use the abbreviated version ":s". From here
on the abbreviation will be used.
The "%" before the command specifies the command works on all lines. Without
a range, ":s" only works on the current line. More about ranges in the next
section |10.3|.
By default, the ":substitute" command changes only the first occurrence on
each line. For example, the preceding command changes the line:
Professor Smith criticized Professor Johnson today. ~
to:
Teacher Smith criticized Professor Johnson today. ~
To change every occurrence on the line, you need to add the g (global) flag.
The command: >
:%s/Professor/Teacher/g
results in (starting with the original line):
Teacher Smith criticized Teacher Johnson today. ~
Other flags include p (print), which causes the ":substitute" command to print
out each line it changes. The c (confirm) flag tells ":substitute" to ask you
for confirmation before it performs each substitution. Enter the following: >
:%s/Professor/Teacher/c
Vim finds the first occurrence of "Professor" and displays the text it is
about to change. You get the following prompt: >
replace with Teacher (y/n/a/q/l/^E/^Y)?
At this point, you must enter one of the following answers:
y Yes; make this change.
n No; skip this match.
a All; make this change and all remaining ones without
further confirmation.
q Quit; don't make any more changes.
l Last; make this change and then quit.
CTRL-E Scroll the text one line up.
CTRL-Y Scroll the text one line down.
The "from" part of the substitute command is actually a pattern. The same
kind as used for the search command. For example, this command only
substitutes "the" when it appears at the start of a line: >
:s/^the/these/
If you are substituting with a "from" or "to" part that includes a slash, you
need to put a backslash before it. A simpler way is to use another character
instead of the slash. A plus, for example: >
:s+one/two+one or two+
==============================================================================
*10.3* Command ranges
The ":substitute" command, and many other : commands, can be applied to a
selection of lines. This is called a range.
The simple form of a range is {number},{number}. For example: >
:1,5s/this/that/g
Executes the substitute command on the lines 1 to 5. Line 5 is included.
The range is always placed before the command.
A single number can be used to address one specific line: >
:54s/President/Fool/
Some commands work on the whole file when you do not specify a range. To make
them work on the current line the "." address is used. The ":write" command
works like that. Without a range, it writes the whole file. To make it write
only the current line into a file: >
:.write otherfile
The first line always has number one. How about the last line? The "$"
character is used for this. For example, to substitute in the lines from the
cursor to the end: >
:.,$s/yes/no/
The "%" range that we used before, is actually a short way to say "1,$", from
the first to the last line.
USING A PATTERN IN A RANGE
Suppose you are editing a chapter in a book, and want to replace all
occurrences of "grey" with "gray". But only in this chapter, not in the next
one. You know that only chapter boundaries have the word "Chapter" in the
first column. This command will work then: >
:?^Chapter?,/^Chapter/s=grey=gray=g
You can see a search pattern is used twice. The first "?^Chapter?" finds the
line above the current position that matches this pattern. Thus the ?pattern?
range is used to search backwards. Similarly, "/^Chapter/" is used to search
forward for the start of the next chapter.
To avoid confusion with the slashes, the "=" character was used in the
substitute command here. A slash or another character would have worked as
well.
ADD AND SUBTRACT
There is a slight error in the above command: If the title of the next chapter
had included "grey" it would be replaced as well. Maybe that's what you
wanted, but what if you didn't? Then you can specify an offset.
To search for a pattern and then use the line above it: >
/Chapter/-1
You can use any number instead of the 1. To address the second line below the
match: >
/Chapter/+2
The offsets can also be used with the other items in a range. Look at this
one: >
:.+3,$-5
This specifies the range that starts three lines below the cursor and ends
five lines before the last line in the file.
USING MARKS
Instead of figuring out the line numbers of certain positions, remembering them
and typing them in a range, you can use marks.
Place the marks as mentioned in chapter 3. For example, use "mt" to mark
the top of an area and "mb" to mark the bottom. Then you can use this range
to specify the lines between the marks (including the lines with the marks): >
:'t,'b
VISUAL MODE AND RANGES
You can select text with Visual mode. If you then press ":" to start a colon
command, you will see this: >
:'<,'>
Now you can type the command and it will be applied to the range of lines that
was visually selected.
Note:
When using Visual mode to select part of a line, or using CTRL-V to
select a block of text, the colon commands will still apply to whole
lines. This might change in a future version of Vim.
The '< and '> are actually marks, placed at the start and end of the Visual
selection. The marks remain at their position until another Visual selection
is made. Thus you can use the "'<" command to jump to position where the
Visual area started. And you can mix the marks with other items: >
:'>,$
This addresses the lines from the end of the Visual area to the end of the
file.
A NUMBER OF LINES
When you know how many lines you want to change, you can type the number and
then ":". For example, when you type "5:", you will get: >
:.,.+4
Now you can type the command you want to use. It will use the range "."
(current line) until ".+4" (four lines down). Thus it spans five lines.
==============================================================================
*10.4* The global command
The ":global" command is one of the more powerful features of Vim. It allows
you to find a match for a pattern and execute a command there. The general
form is: >
:[range]global/{pattern}/{command}
This is similar to the ":substitute" command. But, instead of replacing the
matched text with other text, the command {command} is executed.
Note:
The command executed for ":global" must be one that starts with a
colon. Normal mode commands can not be used directly. The |:normal|
command can do this for you.
Suppose you want to change "foobar" to "barfoo", but only in C++ style
comments. These comments start with "//". Use this command: >
:g+//+s/foobar/barfoo/g
This starts with ":g". That is short for ":global", just like ":s" is short
for ":substitute". Then the pattern, enclosed in plus characters. Since the
pattern we are looking for contains a slash, this uses the plus character to
separate the pattern. Next comes the substitute command that changes "foobar"
into "barfoo".
The default range for the global command is the whole file. Thus no range
was specified in this example. This is different from ":substitute", which
works on one line without a range.
The command isn't perfect, since it also matches lines where "//" appears
halfway a line, and the substitution will also take place before the "//".
Just like with ":substitute", any pattern can be used. When you learn more
complicated patterns later, you can use them here.
==============================================================================
*10.5* Visual block mode
With CTRL-V you can start selection of a rectangular area of text. There are
a few commands that do something special with the text block.
There is something special about using the "$" command in Visual block mode.
When the last motion command used was "$", all lines in the Visual selection
will extend until the end of the line, also when the line with the cursor is
shorter. This remains effective until you use a motion command that moves the
cursor horizontally. Thus using "j" keeps it, "h" stops it.
INSERTING TEXT
The command "I{string}<Esc>" inserts the text {string} in each line, just
left of the visual block. You start by pressing CTRL-V to enter visual block
mode. Now you move the cursor to define your block. Next you type I to enter
Insert mode, followed by the text to insert. As you type, the text appears on
the first line only.
After you press <Esc> to end the insert, the text will magically be
inserted in the rest of the lines contained in the visual selection. Example:
include one ~
include two ~
include three ~
include four ~
Move the cursor to the "o" of "one" and press CTRL-V. Move it down with "3j"
to "four". You now have a block selection that spans four lines. Now type: >
Imain.<Esc>
The result:
include main.one ~
include main.two ~
include main.three ~
include main.four ~
If the block spans short lines that do not extend into the block, the text is
not inserted in that line. For example, make a Visual block selection that
includes the word "long" in the first and last line of this text, and thus has
no text selected in the second line:
This is a long line ~
short ~
Any other long line ~
^^^^ selected block
Now use the command "Ivery <Esc>". The result is:
This is a very long line ~
short ~
Any other very long line ~
In the short line no text was inserted.
If the string you insert contains a newline, the "I" acts just like a Normal
insert command and affects only the first line of the block.
The "A" command works the same way, except that it appends after the right
side of the block.
There is one special case for "A": Select a Visual block and then use "$"
to make the block extend to the end of each line. Using "A" now will append
the text to the end of each line.
Using the same example from above, and then typing "$A XXX<Esc>, you get
this result:
This is a long line XXX ~
short XXX ~
Any other long line XXX ~
This really requires using the "$" command. Vim remembers that it was used.
Making the same selection by moving the cursor to the end of the longest line
with other movement commands will not have the same result.
CHANGING TEXT
The Visual block "c" command deletes the block and then throws you into Insert
mode to enable you to type in a string. The string will be inserted in each
line in the block.
Starting with the same selection of the "long" words as above, then typing
"c_LONG_<Esc>", you get this:
This is a _LONG_ line ~
short ~
Any other _LONG_ line ~
Just like with "I" the short line is not changed. Also, you can't enter a
newline in the new text.
The "C" command deletes text from the left edge of the block to the end of
line. It then puts you in Insert mode so that you can type in a string,
which is added to the end of each line.
Starting with the same text again, and typing "Cnew text<Esc>" you get:
This is a new text ~
short ~
Any other new text ~
Notice that, even though only the "long" word was selected, the text after it
is deleted as well. Thus only the location of the left edge of the visual
block really matters.
Again, short lines that do not reach into the block are excluded.
Other commands that change the characters in the block:
~ swap case (a -> A and A -> a)
U make uppercase (a -> A and A -> A)
u make lowercase (a -> a and A -> a)
FILLING WITH A CHARACTER
To fill the whole block with one character, use the "r" command. Again,
starting with the same example text from above, and then typing "rx":
This is a xxxx line ~
short ~
Any other xxxx line ~
Note:
If you want to include characters beyond the end of the line in the
block, check out the 'virtualedit' feature in chapter 25.
SHIFTING
The command ">" shifts the selected text to the right one shift amount,
inserting whitespace. The starting point for this shift is the left edge of
the visual block.
With the same example again, ">" gives this result:
This is a long line ~
short ~
Any other long line ~
The shift amount is specified with the 'shiftwidth' option. To change it to
use 4 spaces: >
:set shiftwidth=4
The "<" command removes one shift amount of whitespace at the left
edge of the block. This command is limited by the amount of text that is
there; so if there is less than a shift amount of whitespace available, it
removes what it can.
JOINING LINES
The "J" command joins all selected lines together into one line. Thus it
removes the line breaks. Actually, the line break, leading white space and
trailing white space is replaced by one space. Two spaces are used after a
line ending (that can be changed with the 'joinspaces' option).
Let's use the example that we got so familiar with now. The result of
using the "J" command:
This is a long line short Any other long line ~
The "J" command doesn't require a blockwise selection. It works with "v" and
"V" selection in exactly the same way.
If you don't want the white space to be changed, use the "gJ" command.
==============================================================================
*10.6* Reading and writing part of a file
When you are writing an e-mail message, you may want to include another file.
This can be done with the ":read {filename}" command. The text of the file is
put below the cursor line.
Starting with this text:
Hi John, ~
Here is the diff that fixes the bug: ~
Bye, Pierre. ~
Move the cursor to the second line and type: >
:read patch
The file named "patch" will be inserted, with this result:
Hi John, ~
Here is the diff that fixes the bug: ~
2c2 ~
< for (i = 0; i <= length; ++i) ~
--- ~
> for (i = 0; i < length; ++i) ~
Bye, Pierre. ~
The ":read" command accepts a range. The file will be put below the last line
number of this range. Thus ":$r patch" appends the file "patch" at the end of
the file.
What if you want to read the file above the first line? This can be done
with the line number zero. This line doesn't really exist, you will get an
error message when using it with most commands. But this command is allowed:
>
:0read patch
The file "patch" will be put above the first line of the file.
WRITING A RANGE OF LINES
To write a range of lines to a file, the ":write" command can be used.
Without a range it writes the whole file. With a range only the specified
lines are written: >
:.,$write tempo
This writes the lines from the cursor until the end of the file into the file
"tempo". If this file already exists you will get an error message. Vim
protects you from accidentally overwriting an existing file. If you know what
you are doing and want to overwrite the file, append !: >
:.,$write! tempo
CAREFUL: The ! must follow the ":write" command immediately, without white
space. Otherwise it becomes a filter command, which is explained later in
this chapter.
APPENDING TO A FILE
In the first section of this chapter was explained how to collect a number of
lines into a register. The same can be done to collect lines in a file.
Write the first line with this command: >
:.write collection
Now move the cursor to the second line you want to collect, and type this: >
:.write >>collection
The ">>" tells Vim the "collection" file is not to be written as a new file,
but the line must be appended at the end. You can repeat this as many times
as you like.
==============================================================================
*10.7* Formatting text
When you are typing plain text, it's nice if the length of each line is
automatically trimmed to fit in the window. To make this happen while
inserting text, set the 'textwidth' option: >
:set textwidth=72
You might remember that in the example vimrc file this command was used for
every text file. Thus if you are using that vimrc file, you were already
using it. To check the current value of 'textwidth': >
:set textwidth
Now lines will be broken to take only up to 72 characters. But when you
insert text halfway a line, or when you delete a few words, the lines will get
too long or too short. Vim doesn't automatically reformat the text.
To tell Vim to format the current paragraph: >
gqap
This starts with the "gq" command, which is an operator. Following is "ap",
the text object that stands for "a paragraph". A paragraph is separated from
the next paragraph by an empty line.
Note:
A blank line, which contains white space, does NOT separate
paragraphs. This is hard to notice!
Instead of "ap" you could use any motion or text object. If your paragraphs
are properly separated, you can use this command to format the whole file: >
gggqG
"gg" takes you to the first line, "gq" is the format operator and "G" the
motion that jumps to the last line.
In case your paragraphs aren't clearly defined, you can format just the lines
you manually select. Move the cursor to the first line you want to format.
Start with the command "gqj". This formats the current line and the one below
it. If the first line was short, words from the next line will be appended.
If it was too long, words will be moved to the next line. The cursor moves to
the second line. Now you can use "." to repeat the command. Keep doing this
until you are at the end of the text you want to format.
==============================================================================
*10.8* Changing case
You have text with section headers in lowercase. You want to make the word
"section" all uppercase. Do this with the "gU" operator. Start with the
cursor in the first column: >
gUw
< section header ----> SECTION header
The "gu" operator does exactly the opposite: >
guw
< SECTION header ----> section header
You can also use "g~" to swap case. All these are operators, thus they work
with any motion command, with text objects and in Visual mode.
To make an operator work on lines you double it. The delete operator is
"d", thus to delete a line you use "dd". Similarly, "gugu" makes a whole line
lowercase. This can be shortened to "guu". "gUgU" is shortened to "gUU" and
"g~g~" to "g~~". Example: >
g~~
< Some GIRLS have Fun ----> sOME girls HAVE fUN ~
==============================================================================
*10.9* Using an external program
Vim has a very powerful set of commands, it can do anything. But there may
still be something that an external command can do better or faster.
The command "!{motion}{program}" takes a block of text and filters it
through an external program. In other words, it runs the system command
represented by {program}, giving it the block of text represented by {motion}
as input. The output of this command then replaces the selected block.
Because this summarizes badly if you are unfamiliar with UNIX filters, take
a look at an example. The sort command sorts a file. If you execute the
following command, the unsorted file input.txt will be sorted and written to
output.txt. (This works on both UNIX and Microsoft Windows.) >
sort <input.txt >output.txt
Now do the same thing in Vim. You want to sort lines 1 through 5 of a file.
You start by putting the cursor on line 1. Next you execute the following
command: >
!5G
The "!" tells Vim that you are performing a filter operation. The Vim editor
expects a motion command to follow, indicating which part of the file to
filter. The "5G" command tells Vim to go to line 5, so it now knows that it
is to filter lines 1 (the current line) through 5.
In anticipation of the filtering, the cursor drops to the bottom of the
screen and a ! prompt displays. You can now type in the name of the filter
program, in this case "sort". Therefore, your full command is as follows: >
!5Gsort<Enter>
The result is that the sort program is run on the first 5 lines. The output
of the program replaces these lines.
line 55 line 11
line 33 line 22
line 11 --> line 33
line 22 line 44
line 44 line 55
last line last line
The "!!" command filters the current line through a filter. In Unix the "date"
command prints the current time and date. "!!date<Enter>" replaces the current
line with the output of "date". This is useful to add a timestamp to a file.
WHEN IT DOESN'T WORK
Starting a shell, sending it text and capturing the output requires that Vim
knows how the shell works exactly. When you have problems with filtering,
check the values of these options:
'shell' specifies the program that Vim uses to execute
external programs.
'shellcmdflag' argument to pass a command to the shell
'shellquote' quote to be used around the command
'shellxquote' quote to be used around the command and redirection
'shelltype' kind of shell (only for the Amiga)
'shellslash' use forward slashes in the command (only for
MS-Windows and alikes)
'shellredir' string used to write the command output into a file
On Unix this is hardly ever a problem, because there are two kinds of shells:
"sh" like and "csh" like. Vim checks the 'shell' option and sets related
options automatically, depending on whether it sees "csh" somewhere in
'shell'.
On MS-Windows, however, there are many different shells and you might have
to tune the options to make filtering work. Check the help for the options
for more information.
READING COMMAND OUTPUT
To read the contents of the current directory into the file, use this:
on Unix: >
:read !ls
on MS-Windows: >
:read !dir
The output of the "ls" or "dir" command is captured and inserted in the text,
below the cursor. This is similar to reading a file, except that the "!" is
used to tell Vim that a command follows.
The command may have arguments. And a range can be used to tell where Vim
should put the lines: >
:0read !date -u
This inserts the current time and date in UTC format at the top of the file.
(Well, if you have a date command that accepts the "-u" argument.) Note the
difference with using "!!date": that replaced a line, while ":read !date" will
insert a line.
WRITING TEXT TO A COMMAND
The Unix command "wc" counts words. To count the words in the current file: >
:write !wc
This is the same write command as before, but instead of a file name the "!"
character is used and the name of an external command. The written text will
be passed to the specified command as its standard input. The output could
look like this:
4 47 249 ~
The "wc" command isn't verbose. This means you have 4 lines, 47 words and 249
characters.
Watch out for this mistake: >
:write! wc
This will write the file "wc" in the current directory, with force. White
space is important here!
REDRAWING THE SCREEN
If the external command produced an error message, the display may have been
messed up. Vim is very efficient and only redraws those parts of the screen
that it knows need redrawing. But it can't know about what another program
has written. To tell Vim to redraw the screen: >
CTRL-L
==============================================================================
Next chapter: |usr_11.txt| Recovering from a crash
Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:

287
runtime/doc/usr_11.txt Normal file
View File

@@ -0,0 +1,287 @@
*usr_11.txt* For Vim version 7.0aa. Last change: 2004 Apr 23
VIM USER MANUAL - by Bram Moolenaar
Recovering from a crash
Did your computer crash? And you just spent hours editing? Don't panic! Vim
keeps enough information on harddisk to be able to restore most of your work.
This chapter shows you how to get your work back and explains how the swap
file is used.
|11.1| Basic recovery
|11.2| Where is the swap file?
|11.3| Crashed or not?
|11.4| Further reading
Next chapter: |usr_12.txt| Clever tricks
Previous chapter: |usr_10.txt| Making big changes
Table of contents: |usr_toc.txt|
==============================================================================
*11.1* Basic recovery
In most cases recovering a file is quite simple, assuming you know which file
you were editing (and the harddisk is still working). Start Vim on the file,
with the "-r" argument added: >
vim -r help.txt
Vim will read the swap file (used to store text you were editing) and may read
bits and pieces of the original file. If all is well, you will see these
messages (with different file names, of course):
Using swap file ".help.txt.swp" ~
Original file "~/vim/runtime/doc/help.txt" ~
Recovery completed. You should check if everything is OK. ~
(You might want to write out this file under another name ~
and run diff with the original file to check for changes) ~
Delete the .swp file afterwards. ~
To be on the safe side, write this file under another name: >
:write help.txt.recovered
Compare the file with the original file to check if you ended up with what you
expected. Vimdiff is very useful for this |08.7|. Watch out for the original
file to contain a more recent version (you saved the file just before the
computer crashed). And check that no lines are missing (something went wrong
that Vim could not recover).
If Vim produces warning messages when recovering, read them carefully.
This is rare though.
It's normal that the last few changes can not be recovered. Vim flushes the
changes to disk when you don't type for about four seconds, or after typing
about two hundred characters. This is set with the 'updatetime' and
'updatecount' options. Thus when Vim didn't get a chance to save itself when
the system went down, the changes after the last flush will be lost.
If you were editing without a file name, give an empty string as argument: >
vim -r ""
You must be in the right directory, otherwise Vim can't find the swap file.
==============================================================================
*11.2* Where is the swap file?
Vim can store the swap file in several places. Normally it is in the same
directory as the original file. To find it, change to the directory of the
file, and use: >
vim -r
Vim will list the swap files that it can find. It will also look in other
directories where the swap file for files in the current directory may be
located. It will not find swap files in any other directories though, it
doesn't search the directory tree.
The output could look like this:
Swap files found: ~
In current directory: ~
1. .main.c.swp ~
owned by: mool dated: Tue May 29 21:00:25 2001 ~
file name: ~mool/vim/vim6/src/main.c ~
modified: YES ~
user name: mool host name: masaka.moolenaar.net ~
process ID: 12525 ~
In directory ~/tmp: ~
-- none -- ~
In directory /var/tmp: ~
-- none -- ~
In directory /tmp: ~
-- none -- ~
If there are several swap files that look like they may be the one you want to
use, a list is given of these swap files and you are requested to enter the
number of the one you want to use. Carefully look at the dates to decide
which one you want to use.
In case you don't know which one to use, just try them one by one and check
the resulting files if they are what you expected.
USING A SPECIFIC SWAP FILE
If you know which swap file needs to be used, you can recover by giving the
swap file name. Vim will then finds out the name of the original file from
the swap file.
Example: >
vim -r .help.txt.swo
This is also handy when the swap file is in another directory than expected.
If this still does not work, see what file names Vim reports and rename the
files accordingly. Check the 'directory' option to see where Vim may have
put the swap file.
Note:
Vim tries to find the swap file by searching the directories in the
'dir' option, looking for files that match "filename.sw?". If
wildcard expansion doesn't work (e.g., when the 'shell' option is
invalid), Vim does a desperate try to find the file "filename.swp".
If that fails too, you will have to give the name of the swapfile
itself to be able to recover the file.
==============================================================================
*11.3* Crashed or not? *ATTENTION* *E325*
Vim tries to protect you from doing stupid things. Suppose you innocently
start editing a file, expecting the contents of the file to show up. Instead,
Vim produces a very long message:
E325: ATTENTION ~
Found a swap file by the name ".main.c.swp" ~
owned by: mool dated: Tue May 29 21:09:28 2001 ~
file name: ~mool/vim/vim6/src/main.c ~
modified: no ~
user name: mool host name: masaka.moolenaar.net ~
process ID: 12559 (still running) ~
While opening file "main.c" ~
dated: Tue May 29 19:46:12 2001 ~
~
(1) Another program may be editing the same file. ~
If this is the case, be careful not to end up with two ~
different instances of the same file when making changes. ~
Quit, or continue with caution. ~
~
(2) An edit session for this file crashed. ~
If this is the case, use ":recover" or "vim -r main.c" ~
to recover the changes (see ":help recovery"). ~
If you did this already, delete the swap file ".main.c.swp" ~
to avoid this message. ~
You get this message, because, when starting to edit a file, Vim checks if a
swap file already exists for that file. If there is one, there must be
something wrong. It may be one of these two situations.
1. Another edit session is active on this file. Look in the message for the
line with "process ID". It might look like this:
process ID: 12559 (still running) ~
The text "(still running)" indicates that the process editing this file
runs on the same computer. When working on a non-Unix system you will not
get this extra hint. When editing a file over a network, you may not see
the hint, because the process might be running on another computer. In
those two cases you must find out what the situation is yourself.
If there is another Vim editing the same file, continuing to edit will
result in two versions of the same file. The one that is written last will
overwrite the other one, resulting in loss of changes. You better quit
this Vim.
2. The swap file might be the result from a previous crash of Vim or the
computer. Check the dates mentioned in the message. If the date of the
swap file is newer than the file you were editing, and this line appears:
modified: YES ~
Then you very likely have a crashed edit session that is worth recovering.
If the date of the file is newer than the date of the swap file, then
either it was changed after the crash (perhaps you recovered it earlier,
but didn't delete the swap file?), or else the file was saved before the
crash but after the last write of the swap file (then you're lucky: you
don't even need that old swap file). Vim will warn you for this with this
extra line:
NEWER than swap file! ~
UNREADABLE SWAP FILE
Sometimes the line
[cannot be read] ~
will appear under the name of the swap file. This can be good or bad,
depending on circumstances.
It is good if a previous editing session crashed without having made any
changes to the file. Then a directory listing of the swap file will show
that it has zero bytes. You may delete it and proceed.
It is slightly bad if you don't have read permission for the swap file. You
may want to view the file read-only, or quit. On multi-user systems, if you
yourself did the last changes under a different login name, a logout
followed by a login under that other name might cure the "read error". Or
else you might want to find out who last edited (or is editing) the file and
have a talk with them.
It is very bad if it means there is a physical read error on the disk
containing the swap file. Fortunately, this almost never happens.
You may want to view the file read-only at first (if you can), to see the
extent of the changes that were "forgotten". If you are the one in charge of
that file, be prepared to redo your last changes.
WHAT TO DO?
If dialogs are supported you will be asked to select one of five choices:
Swap file ".main.c.swp" already exists! ~
[O]pen Read-Only, (E)dit anyway, (R)ecover, (Q)uit, (A)bort, (D)elete it: ~
O Open the file readonly. Use this when you just want to view the file and
don't need to recover it. You might want to use this when you know someone
else is editing the file, but you just want to look in it and not make
changes.
E Edit the file anyway. Use this with caution! If the file is being edited
in another Vim, you might end up with two versions of the file. Vim will
try to warn you when this happens, but better be safe then sorry.
R Recover the file from the swap file. Use this if you know that the swap
file contains changes that you want to recover.
Q Quit. This avoids starting to edit the file. Use this if there is another
Vim editing the same file.
When you just started Vim, this will exit Vim. When starting Vim with
files in several windows, Vim quits only if there is a swap file for the
first one. When using an edit command, the file will not be loaded and you
are taken back to the previously edited file.
A Abort. Like Quit, but also abort further commands. This is useful when
loading a script that edits several files, such as a session with multiple
windows.
D Delete the swap file. Use this when you are sure you no longer need it.
For example, when it doesn't contain changes, or when the file itself is
newer than the swap file.
On Unix this choice is only offered when the process that created the
swap file does not appear to be running.
If you do not get the dialog (you are running a version of Vim that does not
support it), you will have to do it manually. To recover the file, use this
command: >
:recover
Vim cannot always detect that a swap file already exists for a file. This is
the case when the other edit session puts the swap files in another directory
or when the path name for the file is different when editing it on different
machines. Therefore, don't rely on Vim always warning you.
If you really don't want to see this message, you can add the 'A' flag to the
'shortmess' option. But it's very unusual that you need this.
==============================================================================
*11.4* Further reading
|swap-file| An explanation about where the swap file will be created and
what its name is.
|:preserve| Manually flushing the swap file to disk.
|:swapname| See the name of the swap file for the current file.
'updatecount' Number of key strokes after which the swap file is flushed to
disk.
'updatetime' Timeout after which the swap file is flushed to disk.
'swapsync' Whether the disk is synced when the swap file is flushed.
'directory' List of directory names where to store the swap file.
'maxmem' Limit for memory usage before writing text to the swap file.
'maxmemtot' Same, but for all files in total.
==============================================================================
Next chapter: |usr_12.txt| Clever tricks
Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:

358
runtime/doc/usr_12.txt Normal file
View File

@@ -0,0 +1,358 @@
*usr_12.txt* For Vim version 7.0aa. Last change: 2004 May 01
VIM USER MANUAL - by Bram Moolenaar
Clever tricks
By combining several commands you can make Vim do nearly everything. In this
chapter a number of useful combinations will be presented. This uses the
commands introduced in the previous chapters and a few more.
|12.1| Replace a word
|12.2| Change "Last, First" to "First Last"
|12.3| Sort a list
|12.4| Reverse line order
|12.5| Count words
|12.6| Find a man page
|12.7| Trim blanks
|12.8| Find where a word is used
Next chapter: |usr_20.txt| Typing command-line commands quickly
Previous chapter: |usr_11.txt| Recovering from a crash
Table of contents: |usr_toc.txt|
==============================================================================
*12.1* Replace a word
The substitute command can be used to replace all occurrences of a word with
another word: >
:%s/four/4/g
The "%" range means to replace in all lines. The "g" flag at the end causes
all words in a line to be replaced.
This will not do the right thing if your file also contains "thirtyfour".
It would be replaced with "thirty4". To avoid this, use the "\<" item to
match the start of a word: >
:%s/\<four/4/g
Obviously, this still goes wrong on "fourty". Use "\>" to match the end of a
word: >
:%s/\<four\>/4/g
If you are programming, you might want to replace "four" in comments, but not
in the code. Since this is difficult to specify, add the "c" flag to have the
substitute command prompt you for each replacement: >
:%s/\<four\>/4/gc
REPLACING IN SEVERAL FILES
Suppose you want to replace a word in more than one file. You could edit each
file and type the command manually. It's a lot faster to use record and
playback.
Let's assume you have a directory with C++ files, all ending in ".cpp".
There is a function called "GetResp" that you want to rename to "GetAnswer".
vim *.cpp Start Vim, defining the argument list to
contain all the C++ files. You are now in the
first file.
qq Start recording into the q register
:%s/\<GetResp\>/GetAnswer/g
Do the replacements in the first file.
:wnext Write this file and move to the next one.
q Stop recording.
@q Execute the q register. This will replay the
substitution and ":wnext". You can verify
that this doesn't produce an error message.
999@q Execute the q register on the remaining files.
At the last file you will get an error message, because ":wnext" cannot move
to the next file. This stops the execution, and everything is done.
Note:
When playing back a recorded sequence, an error stops the execution.
Therefore, make sure you don't get an error message when recording.
There is one catch: If one of the .cpp files does not contain the word
"GetResp", you will get an error and replacing will stop. To avoid this, add
the "e" flag to the substitute command: >
:%s/\<GetResp\>/GetAnswer/ge
The "e" flag tells ":substitute" that not finding a match is not an error.
==============================================================================
*12.2* Change "Last, First" to "First Last"
You have a list of names in this form:
Doe, John ~
Smith, Peter ~
You want to change that to:
John Doe ~
Peter Smith ~
This can be done with just one command: >
:%s/\([^,]*\), \(.*\)/\2 \1/
Let's break this down in parts. Obviously it starts with a substitute
command. The "%" is the line range, which stands for the whole file. Thus
the substitution is done in every line in the file.
The arguments for the substitute command are "/from/to/". The slashes
separate the "from" pattern and the "to" string. This is what the "from"
pattern contains:
\([^,]*\), \(.*\) ~
The first part between \( \) matches "Last" \( \)
match anything but a comma [^,]
any number of times *
matches ", " literally ,
The second part between \( \) matches "First" \( \)
any character .
any number of times *
In the "to" part we have "\2" and "\1". These are called backreferences.
They refer to the text matched by the "\( \)" parts in the pattern. "\2"
refers to the text matched by the second "\( \)", which is the "First" name.
"\1" refers to the first "\( \)", which is the "Last" name.
You can use up to nine backreferences in the "to" part of a substitute
command. "\0" stands for the whole matched pattern. There are a few more
special items in a substitute command, see |sub-replace-special|.
==============================================================================
*12.3* Sort a list
In a Makefile you often have a list of files. For example:
OBJS = \ ~
version.o \ ~
pch.o \ ~
getopt.o \ ~
util.o \ ~
getopt1.o \ ~
inp.o \ ~
patch.o \ ~
backup.o ~
To sort this list, filter the text through the external sort command: >
/^OBJS
j
:.,/^$/-1!sort
This goes to the first line, where "OBJS" is the first thing in the line.
Then it goes one line down and filters the lines until the next empty line.
You could also select the lines in Visual mode and then use "!sort". That's
easier to type, but more work when there are many lines.
The result is this:
OBJS = \ ~
backup.o ~
getopt.o \ ~
getopt1.o \ ~
inp.o \ ~
patch.o \ ~
pch.o \ ~
util.o \ ~
version.o \ ~
Notice that a backslash at the end of each line is used to indicate the line
continues. After sorting, this is wrong! The "backup.o" line that was at
the end didn't have a backslash. Now that it sorts to another place, it
must have a backslash.
The simplest solution is to add the backslash with "A \<Esc>". You can
keep the backslash in the last line, if you make sure an empty line comes
after it. That way you don't have this problem again.
==============================================================================
*12.4* Reverse line order
The |:global| command can be combined with the |:move| command to move all the
lines before the first line, resulting in a reversed file. The command is: >
:global/^/m 0
Abbreviated: >
:g/^/m 0
The "^" regular expression matches the beginning of the line (even if the line
is blank). The |:move| command moves the matching line to after the mythical
zeroth line, so the current matching line becomes the first line of the file.
As the |:global| command is not confused by the changing line numbering,
|:global| proceeds to match all remaining lines of the file and puts each as
the first.
This also works on a range of lines. First move to above the first line and
mark it with "mt". Then move the cursor to the last line in the range and
type: >
:'t+1,.g/^/m 't
==============================================================================
*12.5* Count words
Sometimes you have to write a text with a maximum number of words. Vim can
count the words for you.
When the whole file is what you want to count the words in, use this
command: >
g CTRL-G
Do not type a space after the g, this is just used here to make the command
easy to read.
The output looks like this:
Col 1 of 0; Line 141 of 157; Word 748 of 774; Byte 4489 of 4976 ~
You can see on which word you are (748), and the total number of words in the
file (774).
When the text is only part of a file, you could move to the start of the text,
type "g CTRL-G", move to the end of the text, type "g CTRL-G" again, and then
use your brain to compute the difference in the word position. That's a good
exercise, but there is an easier way. With Visual mode, select the text you
want to count words in. Then type g CTRL-G. The result:
Selected 5 of 293 Lines; 70 of 1884 Words; 359 of 10928 Bytes ~
For other ways to count words, lines and other items, see |count-items|.
==============================================================================
*12.6* Find a man page *find-manpage*
While editing a shell script or C program, you are using a command or function
that you want to find the man page for (this is on Unix). Let's first use a
simple way: Move the cursor to the word you want to find help on and press >
K
Vim will run the external "man" program on the word. If the man page is
found, it is displayed. This uses the normal pager to scroll through the text
(mostly the "more" program). When you get to the end pressing <Enter> will
get you back into Vim.
A disadvantage is that you can't see the man page and the text you are working
on at the same time. There is a trick to make the man page appear in a Vim
window. First, load the man filetype plugin: >
:runtime! ftplugin/man.vim
Put this command in your vimrc file if you intend to do this often. Now you
can use the ":Man" command to open a window on a man page: >
:Man csh
You can scroll around and the text is highlighted. This allows you to find
the help you were looking for. Use CTRL-W w to jump to the window with the
text you were working on.
To find a man page in a specific section, put the section number first.
For example, to look in section 3 for "echo": >
:Man 3 echo
To jump to another man page, which is in the text with the typical form
"word(1)", press CTRL-] on it. Further ":Man" commands will use the same
window.
To display a man page for the word under the cursor, use this: >
\K
(If you redefined the <Leader>, use it instead of the backslash).
For example, you want to know the return value of "strstr()" while editing
this line:
if (strstr(input, "aap") == ) ~
Move the cursor to somewhere on "strstr" and type "\K". A window will open
to display the man page for strstr().
==============================================================================
*12.7* Trim blanks
Some people find spaces and tabs at the end of a line useless, wasteful, and
ugly. To remove whitespace at the end of every line, execute the following
command: >
:%s/\s\+$//
The line range "%" is used, thus this works on the whole file. The pattern
that the ":substitute" command matches with is "\s\+$". This finds white
space characters (\s), 1 or more of them (\+), before the end-of-line ($).
Later will be explained how you write patterns like this |usr_27.txt|.
The "to" part of the substitute command is empty: "//". Thus it replaces
with nothing, effectively deleting the matched white space.
Another wasteful use of spaces is placing them before a Tab. Often these can
be deleted without changing the amount of white space. But not always!
Therefore, you can best do this manually. Use this search command: >
/
You cannot see it, but there is a space before a tab in this command. Thus
it's "/<Space><Tab>". Now use "x" to delete the space and check that the
amount of white space doesn't change. You might have to insert a Tab if it
does change. Type "n" to find the next match. Repeat this until no more
matches can be found.
==============================================================================
*12.8* Find where a word is used
If you are a UNIX user, you can use a combination of Vim and the grep command
to edit all the files that contain a given word. This is extremely useful if
you are working on a program and want to view or edit all the files that
contain a specific variable.
For example, suppose you want to edit all the C program files that contain
the word "frame_counter". To do this you use the command: >
vim `grep -l frame_counter *.c`
Let's look at this command in detail. The grep command searches through a set
of files for a given word. Because the -l argument is specified, the command
will only list the files containing the word and not print the matching lines.
The word it is searching for is "frame_counter". Actually, this can be any
regular expression. (Note: What grep uses for regular expressions is not
exactly the same as what Vim uses.)
The entire command is enclosed in backticks (`). This tells the UNIX shell
to run this command and pretend that the results were typed on the command
line. So what happens is that the grep command is run and produces a list of
files, these files are put on the Vim command line. This results in Vim
editing the file list that is the output of grep. You can then use commands
like ":next" and ":first" to browse through the files.
FINDING EACH LINE
The above command only finds the files in which the word is found. You still
have to find the word within the files.
Vim has a built-in command that you can use to search a set of files for a
given string. If you want to find all occurrences of "error_string" in all C
program files, for example, enter the following command: >
:grep error_string *.c
This causes Vim to search for the string "error_string" in all the specified
files (*.c). The editor will now open the first file where a match is found
and position the cursor on the first matching line. To go to the next
matching line (no matter in what it is file), use the ":cnext" command. To go
to the previous match, use the ":cprev" command. Use ":clist" to see all the
matches and where they are.
The ":grep" command uses the external commands grep (on Unix) or findstr
(on Windows). You can change this by setting the option 'grepprg'.
==============================================================================
Next chapter: |usr_20.txt| Typing command-line commands quickly
Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:

384
runtime/doc/usr_20.txt Normal file
View File

@@ -0,0 +1,384 @@
*usr_20.txt* For Vim version 7.0aa. Last change: 2003 Apr 30
VIM USER MANUAL - by Bram Moolenaar
Typing command-line commands quickly
Vim has a few generic features that makes it easier to enter commands. Colon
commands can be abbreviated, edited and repeated. Completion is available for
nearly everything.
|20.1| Command line editing
|20.2| Command line abbreviations
|20.3| Command line completion
|20.4| Command line history
|20.5| Command line window
Next chapter: |usr_21.txt| Go away and come back
Previous chapter: |usr_12.txt| Clever tricks
Table of contents: |usr_toc.txt|
==============================================================================
*20.1* Command line editing
When you use a colon (:) command or search for a string with / or ?, Vim puts
the cursor on the bottom of the screen. There you type the command or search
pattern. This is called the Command line. Also when it's used for entering a
search command.
The most obvious way to edit the command you type is by pressing the <BS> key.
This erases the character before the cursor. To erase another character,
typed earlier, first move the cursor with the cursor keys.
For example, you have typed this: >
:s/col/pig/
Before you hit <Enter>, you notice that "col" should be "cow". To correct
this, you type <Left> five times. The cursor is now just after "col". Type
<BS> and "w" to correct: >
:s/cow/pig/
Now you can press <Enter> directly. You don't have to move the cursor to the
end of the line before executing the command.
The most often used keys to move around in the command line:
<Left> one character left
<Right> one character right
<S-Left> or <C-Left> one word left
<S-Right> or <C-Right> one word right
CTRL-B or <Home> to begin of command line
CTRL-E or <End> to end of command line
Note:
<S-Left> (cursor left key with Shift key pressed) and <C-Left> (cursor
left key with Control pressed) will not work on all keyboards. Same
for the other Shift and Control combinations.
You can also use the mouse to move the cursor.
DELETING
As mentioned, <BS> deletes the character before the cursor. To delete a whole
word use CTRL-W.
/the fine pig ~
CTRL-W
/the fine ~
CTRL-U removes all text, thus allows you to start all over again.
OVERSTRIKE
The <Insert> key toggles between inserting characters and replacing the
existing ones. Start with this text:
/the fine pig ~
Move the cursor to the start of "fine" with <S-Left> twice (or <Left> eight
times, if <S-Left> doesn't work). Now press <Insert> to switch to overstrike
and type "great":
/the greatpig ~
Oops, we lost the space. Now, don't use <BS>, because it would delete the
"t" (this is different from Replace mode). Instead, press <Insert> to switch
from overstrike to inserting, and type the space:
/the great pig ~
CANCELLING
You thought of executing a : or / command, but changed your mind. To get rid
of what you already typed, without executing it, press CTRL-C or <Esc>.
Note:
<Esc> is the universal "get out" key. Unfortunately, in the good old
Vi pressing <Esc> in a command line executed the command! Since that
might be considered to be a bug, Vim uses <Esc> to cancel the command.
But with the 'cpoptions' option it can be made Vi compatible. And
when using a mapping (which might be written for Vi) <Esc> also works
Vi compatible. Therefore, using CTRL-C is a method that always works.
If you are at the start of the command line, pressing <BS> will cancel the
command. It's like deleting the ":" or "/" that the line starts with.
==============================================================================
*20.2* Command line abbreviations
Some of the ":" commands are really long. We already mentioned that
":substitute" can be abbreviated to ":s". This is a generic mechanism, all
":" commands can be abbreviated.
How short can a command get? There are 26 letters, and many more commands.
For example, ":set" also starts with ":s", but ":s" doesn't start a ":set"
command. Instead ":set" can be abbreviated to ":se".
When the shorter form of a command could be used for two commands, it
stands for only one of them. There is no logic behind which one, you have to
learn them. In the help files the shortest form that works is mentioned. For
example: >
:s[ubstitute]
This means that the shortest form of ":substitute" is ":s". The following
characters are optional. Thus ":su" and ":sub" also work.
In the user manual we will either use the full name of command, or a short
version that is still readable. For example, ":function" can be abbreviated
to ":fu". But since most people don't understand what that stands for, we
will use ":fun". (Vim doesn't have a ":funny" command, otherwise ":fun" would
be confusing too.)
It is recommended that in Vim scripts you write the full command name. That
makes it easier to read back when you make later changes. Except for some
often used commands like ":w" (":write") and ":r" (":read").
A particularly confusing one is ":end", which could stand for ":endif",
":endwhile" or ":endfunction". Therefore, always use the full name.
SHORT OPTION NAMES
In the user manual the long version of the option names is used. Many options
also have a short name. Unlike ":" commands, there is only one short name
that works. For example, the short name of 'autoindent' is 'ai'. Thus these
two commands do the same thing: >
:set autoindent
:set ai
You can find the full list of long and short names here: |option-list|.
==============================================================================
*20.3* Command line completion
This is one of those Vim features that, by itself, is a reason to switch from
Vi to Vim. Once you have used this, you can't do without.
Suppose you have a directory that contains these files:
info.txt
intro.txt
bodyofthepaper.txt
To edit the last one, you use the command: >
:edit bodyofthepaper.txt
It's easy to type this wrong. A much quicker way is: >
:edit b<Tab>
Which will result in the same command. What happened? The <Tab> key does
completion of the word before the cursor. In this case "b". Vim looks in the
directory and finds only one file that starts with a "b". That must be the
one you are looking for, thus Vim completes the file name for you.
Now type: >
:edit i<Tab>
Vim will beep, and give you: >
:edit info.txt
The beep means that Vim has found more than one match. It then uses the first
match it found (alphabetically). If you press <Tab> again, you get: >
:edit intro.txt
Thus, if the first <Tab> doesn't give you the file you were looking for, press
it again. If there are more matches, you will see them all, one at a time.
If you press <Tab> on the last matching entry, you will go back to what you
first typed: >
:edit i
Then it starts all over again. Thus Vim cycles through the list of matches.
Use CTRL-P to go through the list in the other direction:
<------------------- <Tab> -------------------------+
|
<Tab> --> <Tab> -->
:edit i :edit info.txt :edit intro.txt
<-- CTRL-P <-- CTRL-P
|
+---------------------- CTRL-P ------------------------>
CONTEXT
When you type ":set i" instead of ":edit i" and press <Tab> you get: >
:set icon
Hey, why didn't you get ":set info.txt"? That's because Vim has context
sensitive completion. The kind of words Vim will look for depends on the
command before it. Vim knows that you cannot use a file name just after a
":set" command, but you can use an option name.
Again, if you repeat typing the <Tab>, Vim will cycle through all matches.
There are quite a few, it's better to type more characters first: >
:set isk<Tab>
Gives: >
:set iskeyword
Now type "=" and press <Tab>: >
:set iskeyword=@,48-57,_,192-255
What happens here is that Vim inserts the old value of the option. Now you
can edit it.
What is completed with <Tab> is what Vim expects in that place. Just try
it out to see how it works. In some situations you will not get what you
want. That's either because Vim doesn't know what you want, or because
completion was not implemented for that situation. In that case you will get
a <Tab> inserted (displayed as ^I).
LIST MATCHES
When there are many matches, you would like to see an overview. Do this by
pressing CTRL-D. For example, pressing CTRL-D after: >
:set is
results in: >
:set is
incsearch isfname isident iskeyword isprint
:set is
Vim lists the matches and then comes back with the text you typed. You can
now check the list for the item you wanted. If it isn't there, you can use
<BS> to correct the word. If there are many matches, type a few more
characters before pressing <Tab> to complete the rest.
If you have watched carefully, you will have noticed that "incsearch"
doesn't start with "is". In this case "is" stands for the short name of
"incsearch". (Many options have a short and a long name.) Vim is clever
enough to know that you might have wanted to expand the short name of the
option into the long name.
THERE IS MORE
The CTRL-L command completes the word to the longest unambiguous string. If
you type ":edit i" and there are files "info.txt" and "info_backup.txt" you
will get ":edit info".
The 'wildmode' option can be used to change the way completion works.
The 'wildmenu' option can be used to get a menu-like list of matches.
Use the 'suffixes' option to specify files that are less important and appear
at the end of the list of files.
The 'wildignore' option specifies files that are not listed at all.
More about all of this here: |cmdline-completion|
==============================================================================
*20.4* Command line history
In chapter 3 we briefly mentioned the history. The basics are that you can
use the <Up> key to recall an older command line. <Down> then takes you back
to newer commands.
There are actually four histories. The ones we will mention here are for ":"
commands and for "/" and "?" search commands. The "/" and "?" commands share
the same history, because they are both search commands. The two other
histories are for expressions and input lines for the input() function.
|cmdline-history|
Suppose you have done a ":set" command, typed ten more colon commands and then
want to repeat that ":set" command again. You could press ":" and then ten
times <Up>. There is a quicker way: >
:se<Up>
Vim will now go back to the previous command that started with "se". You have
a good chance that this is the ":set" command you were looking for. At least
you should not have to press <Up> very often (unless ":set" commands is all
you have done).
The <Up> key will use the text typed so far and compare it with the lines in
the history. Only matching lines will be used.
If you do not find the line you were looking for, use <Down> to go back to
what you typed and correct that. Or use CTRL-U to start all over again.
To see all the lines in the history: >
:history
That's the history of ":" commands. The search history is displayed with this
command: >
:history /
CTRL-P will work like <Up>, except that it doesn't matter what you already
typed. Similarly for CTRL-N and <Down>. CTRL-P stands for previous, CTRL-N
for next.
==============================================================================
*20.5* Command line window
Typing the text in the command line works different from typing text in Insert
mode. It doesn't allow many commands to change the text. For most commands
that's OK, but sometimes you have to type a complicated command. That's where
the command line window is useful.
Open the command line window with this command: >
q:
Vim now opens a (small) window at the bottom. It contains the command line
history, and an empty line at the end:
+-------------------------------------+
|other window |
|~ |
|file.txt=============================|
|:e c |
|:e config.h.in |
|:set path=.,/usr/include,, |
|:set iskeyword=@,48-57,_,192-255 |
|:set is |
|:q |
|: |
|command-line=========================|
| |
+-------------------------------------+
You are now in Normal mode. You can use the "hjkl" keys to move around. For
example, move up with "5k" to the ":e config.h.in" line. Type "$h" to go to
the "i" of "in" and type "cwout". Now you have changed the line to:
:e config.h.out ~
Now press <Enter> and this command will be executed. The command line window
will close.
The <Enter> command will execute the line under the cursor. It doesn't
matter whether Vim is in Insert mode or in Normal mode.
Changes in the command line window are lost. They do not result in the
history to be changed. Except that the command you execute will be added to
the end of the history, like with all executed commands.
The command line window is very useful when you want to have overview of the
history, lookup a similar command, change it a bit and execute it. A search
command can be used to find something.
In the previous example the "?config" search command could have been used
to find the previous command that contains "config". It's a bit strange,
because you are using a command line to search in the command line window.
While typing that search command you can't open another command line window,
there can be only one.
==============================================================================
Next chapter: |usr_21.txt| Go away and come back
Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:

456
runtime/doc/usr_21.txt Normal file
View File

@@ -0,0 +1,456 @@
*usr_21.txt* For Vim version 7.0aa. Last change: 2004 Mar 29
VIM USER MANUAL - by Bram Moolenaar
Go away and come back
This chapter goes into mixing the use of other programs with Vim. Either by
executing program from inside Vim or by leaving Vim and coming back later.
Furthermore, this is about the ways to remember the state of Vim and restore
it later.
|21.1| Suspend and resume
|21.2| Executing shell commands
|21.3| Remembering information; viminfo
|21.4| Sessions
|21.5| Views
|21.6| Modelines
Next chapter: |usr_22.txt| Finding the file to edit
Previous chapter: |usr_20.txt| Typing command-line commands quickly
Table of contents: |usr_toc.txt|
==============================================================================
*21.1* Suspend and resume
Like most Unix programs Vim can be suspended by pressing CTRL-Z. This stops
Vim and takes you back to the shell it was started in. You can then do any
other commands until you are bored with them. Then bring back Vim with the
"fg" command. >
CTRL-Z
{any sequence of shell commands}
fg
You are right back where you left Vim, nothing has changed.
In case pressing CTRL-Z doesn't work, you can also use ":suspend".
Don't forget to bring Vim back to the foreground, you would lose any changes
that you made!
Only Unix has support for this. On other systems Vim will start a shell for
you. This also has the functionality of being able to execute shell commands.
But it's a new shell, not the one that you started Vim from.
When you are running the GUI you can't go back to the shell where Vim was
started. CTRL-Z will minimize the Vim window instead.
==============================================================================
*21.2* Executing shell commands
To execute a single shell command from Vim use ":!{command}". For example, to
see a directory listing: >
:!ls
:!dir
The first one is for Unix, the second one for MS-Windows.
Vim will execute the program. When it ends you will get a prompt to hit
<Enter>. This allows you to have a look at the output from the command before
returning to the text you were editing.
The "!" is also used in other places where a program is run. Let's take
a look at an overview:
:!{program} execute {program}
:r !{program} execute {program} and read its output
:w !{program} execute {program} and send text to its input
:[range]!{program} filter text through {program}
Notice that the precense of a range before "!{program}" makes a big
difference. Without it executes the program normally, with the range a number
of text lines is filtered through the program.
Executing a whole row of programs this way is possible. But a shell is much
better at it. You can start a new shell this way: >
:shell
This is similar to using CTRL-Z to suspend Vim. The difference is that a new
shell is started.
When using the GUI the shell will be using the Vim window for its input and
output. Since Vim is not a terminal emulator, this will not work perfectly.
If you have trouble, try toggling the 'guipty' option. If this still doesn't
work well enough, start a new terminal to run the shell in. For example with:
>
:!xterm&
==============================================================================
*21.3* Remembering information; viminfo
After editing for a while you will have text in registers, marks in various
files, a command line history filled with carefully crafted commands. When
you exit Vim all of this is lost. But you can get it back!
The viminfo file is designed to store status information:
Command-line and Search pattern history
Text in registers
Marks for various files
The buffer list
Global variables
Each time you exit Vim it will store this information in a file, the viminfo
file. When Vim starts again, the viminfo file is read and the information
restored.
The 'viminfo' option is set by default to restore a limited number of items.
You might want to set it to remember more information. This is done through
the following command: >
:set viminfo=string
The string specifies what to save. The syntax of this string is an option
character followed by an argument. The option/argument pairs are separated by
commas.
Take a look at how you can build up your own viminfo string. First, the '
option is used to specify how many files for which you save marks (a-z). Pick
a nice even number for this option (1000, for instance). Your command now
looks like this: >
:set viminfo='1000
The f option controls whether global marks (A-Z and 0-9) are stored. If this
option is 0, none are stored. If it is 1 or you do not specify an f option,
the marks are stored. You want this feature, so now you have this: >
:set viminfo='1000,f1
The < option controls how many lines are saved for each of the registers. By
default, all the lines are saved. If 0, nothing is saved. To avoid adding
thousands of lines to your viminfo file (which might never get used and makes
starting Vim slower) you use a maximum of 500 lines: >
:set viminfo='1000,f1,<500
<
Other options you might want to use:
: number of lines to save from the command line history
@ number of lines to save from the input line history
/ number of lines to save from the search history
r removable media, for which no marks will be stored (can be
used several times)
! global variables that start with an uppercase letter and
don't contain lowercase letters
h disable 'hlsearch' highlighting when starting
% the buffer list (only restored when starting Vim without file
arguments)
c convert the text using 'encoding'
n name used for the viminfo file (must be the last option)
See the 'viminfo' option and |viminfo-file| for more information.
When you run Vim multiple times, the last one exiting will store its
information. This may cause information that previously exiting Vims stored
to be lost. Each item can be remembered only once.
GETTING BACK TO WHERE YOU WERE
You are halfway editing a file and it's time to leave for holidays. You exit
Vim and go enjoy yourselves, forgetting all about your work. After a couple
of weeks you start Vim, and type:
>
'0
And you are right back where you left Vim. So you can get on with your work.
Vim creates a mark each time you exit Vim. The last one is '0. The
position that '0 pointed to is made '1. And '1 is made to '2, and so forth.
Mark '9 is lost.
The ":marks" command is useful to find out where '0 to '9 will take you.
MOVE INFO FROM ONE VIM TO ANOTHER
You can use the ":wviminfo" and ":rviminfo" commands to save and restore the
information while still running Vim. This is useful for exchanging register
contents between two instances of Vim, for example. In the first Vim do: >
:wviminfo! ~/tmp/viminfo
And in the second Vim do: >
:rviminfo! ~/tmp/viminfo
Obviously, the "w" stands for "write" and the "r" for "read".
The ! character is used by ":wviminfo" to forcefully overwrite an existing
file. When it is omitted, and the file exists, the information is merged into
the file.
The ! character used for ":rviminfo" means that all the information is
used, this may overwrite existing information. Without the ! only information
that wasn't set is used.
These commands can also be used to store info and use it again later. You
could make a directory full of viminfo files, each containing info for a
different purpose.
==============================================================================
*21.4* Sessions
Suppose you are editing along, and it is the end of the day. You want to quit
work and pick up where you left off the next day. You can do this by saving
your editing session and restoring it the next day.
A Vim session contains all the information about what you are editing.
This includes things such as the file list, window layout, global variables,
options and other information. (Exactly what is remembered is controlled by
the 'sessionoptions' option, described below.)
The following command creates a session file: >
:mksession vimbook.vim
Later if you want to restore this session, you can use this command: >
:source vimbook.vim
If you want to start Vim and restore a specific session, you can use the
following command: >
vim -S vimbook.vim
This tells Vim to read a specific file on startup. The 'S' stands for
session (actually, you can source any Vim script with -S, thus it might as
well stand for "source").
The windows that were open are restored, with the same position and size as
before. Mappings and option values are like before.
What exactly is restored depends on the 'sessionoptions' option. The
default value is "blank,buffers,curdir,folds,help,options,winsize".
blank keep empty windows
buffers all buffers, not only the ones in a window
curdir the current directory
folds folds, also manually created ones
help the help window
options all options and mappings
winsize window sizes
Change this to your liking. To also restore the size of the Vim window, for
example, use: >
:set sessionoptions+=resize
SESSION HERE, SESSION THERE
The obvious way to use sessions is when working on different projects.
Suppose you store you session files in the directory "~/.vim". You are
currently working on the "secret" project and have to switch to the "boring"
project: >
:wall
:mksession! ~/.vim/secret.vim
:source ~/.vim/boring.vim
This first uses ":wall" to write all modified files. Then the current session
is saved, using ":mksession!". This overwrites the previous session. The
next time you load the secret session you can continue where you were at this
point. And finally you load the new "boring" session.
If you open help windows, split and close various window, and generally mess
up the window layout, you can go back to the last saved session: >
:source ~/.vim/boring.vim
Thus you have complete control over whether you want to continue next time
where you are now, by saving the current setup in a session, or keep the
session file as a starting point.
Another way of using sessions is to create a window layout that you like to
use, and save this in a session. Then you can go back to this layout whenever
you want.
For example, this is a nice layout to use:
+----------------------------------------+
| VIM - main help file |
| |
|Move around: Use the cursor keys, or "h|
|help.txt================================|
|explorer | |
|dir |~ |
|dir |~ |
|file |~ |
|file |~ |
|file |~ |
|file |~ |
|~/=========|[No File]===================|
| |
+----------------------------------------+
This has a help window at the top, so that you can read this text. The narrow
vertical window on the left contains a file explorer. This is a Vim plugin
that lists the contents of a directory. You can select files to edit there.
More about this in the next chapter.
Create this from a just started Vim with: >
:help
CTRL-W w
:vertical split ~/
You can resize the windows a bit to your liking. Then save the session with:
>
:mksession ~/.vim/mine.vim
Now you can start Vim with this layout: >
vim -S ~/.vim/mine.vim
Hint: To open a file you see listed in the explorer window in the empty
window, move the cursor to the filename and press "O". Double clicking with
the mouse will also do this.
UNIX AND MS-WINDOWS
Some people have to do work on MS-Windows systems one day and on Unix another
day. If you are one of them, consider adding "slash" and "unix" to
'sessionoptions'. The session files will then be written in a format that can
be used on both systems. This is the command to put in your vimrc file: >
:set sessionoptions+=unix,slash
Vim will use the Unix format then, because the MS-Windows Vim can read and
write Unix files, but Unix Vim can't read MS-Windows format session files.
Similarly, MS-Windows Vim understands file names with / to separate names, but
Unix Vim doesn't understand \.
SESSIONS AND VIMINFO
Sessions store many things, but not the position of marks, contents of
registers and the command line history. You need to use the viminfo feature
for these things.
In most situations you will want to use sessions separately from viminfo.
This can be used to switch to another session, but keep the command line
history. And yank text into registers in one session, and paste it back in
another session.
You might prefer to keep the info with the session. You will have to do
this yourself then. Example: >
:mksession! ~/.vim/secret.vim
:wviminfo! ~/.vim/secret.viminfo
And to restore this again: >
:source ~/.vim/secret.vim
:rviminfo! ~/.vim/secret.viminfo
==============================================================================
*21.5* Views
A session stores the looks of the whole of Vim. When you want to store the
properties for one window only, use a view.
The use of a view is for when you want to edit a file in a specific way.
For example, you have line numbers enabled with the 'number' option and
defined a few folds. Just like with sessions, you can remember this view on
the file and restore it later. Actually, when you store a session, it stores
the view of each window.
There are two basic ways to use views. The first is to let Vim pick a name
for the view file. You can restore the view when you later edit the same
file. To store the view for the current window: >
:mkview
Vim will decide where to store the view. When you later edit the same file
you get the view back with this command: >
:loadview
That's easy, isn't it?
Now you want to view the file without the 'number' option on, or with all
folds open, you can set the options to make the window look that way. Then
store this view with: >
:mkview 1
Obviously, you can get this back with: >
:loadview 1
Now you can switch between the two views on the file by using ":loadview" with
and without the "1" argument.
You can store up to ten views for the same file this way, one unnumbered
and nine numbered 1 to 9.
A VIEW WITH A NAME
The second basic way to use views is by storing the view in a file with a name
you chose. This view can be loaded while editing another file. Vim will then
switch to editing the file specified in the view. Thus you can use this to
quickly switch to editing another file, with all its options set as you saved
them.
For example, to save the view of the current file: >
:mkview ~/.vim/main.vim
You can restore it with: >
:source ~/.vim/main.vim
==============================================================================
*21.6* Modelines
When editing a specific file, you might set options specifically for that
file. Typing these commands each time is boring. Using a session or view for
editing a file doesn't work when sharing the file between several people.
The solution for this situation is adding a modeline to the file. This is
a line of text that tells Vim the values of options, to be used in this file
only.
A typical example is a C program where you make indents by a multiple of 4
spaces. This requires setting the 'shiftwidth' option to 4. This modeline
will do that:
/* vim:set shiftwidth=4: */ ~
Put this line as one of the first or last five lines in the file. When
editing the file, you will notice that 'shiftwidth' will have been set to
four. When editing another file, it's set back to the default value of eight.
For some files the modeline fits well in the header, thus it can be put at
the top of the file. For text files and other files where the modeline gets
in the way of the normal contents, put it at the end of the file.
The 'modelines' option specifies how many lines at the start and end of the
file are inspected for containing a modeline. To inspect ten lines: >
:set modelines=10
The 'modeline' option can be used to switch this off. Do this when you are
working as root or don't trust the files you are editing: >
:set nomodeline
Use this format for the modeline:
any-text vim:set {option}={value} ... : any-text ~
The "any-text" indicates that you can put any text before and after the part
that Vim will use. This allows making it look like a comment, like what was
done above with /* and */.
The " vim:" part is what makes Vim recognize this line. The must be white
space before "vim", or "vim" must be at the start of the line. Thus using
something like "gvim:" will not work.
The part between the colons is a ":set" command. It works the same way as
typing the ":set" command, except that you need to insert a backslash before a
colon (otherwise it would be seen as the end of the modeline).
Another example:
// vim:set textwidth=72 dir=c\:\tmp: use c:\tmp here ~
There is an extra backslash before the first colon, so that it's included in
the ":set" command. The text after the second colon is ignored, thus a remark
can be placed there.
For more details see |modeline|.
==============================================================================
Next chapter: |usr_22.txt| Finding the file to edit
Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:

364
runtime/doc/usr_22.txt Normal file
View File

@@ -0,0 +1,364 @@
*usr_22.txt* For Vim version 7.0aa. Last change: 2003 Mar 17
VIM USER MANUAL - by Bram Moolenaar
Finding the file to edit
Files can be found everywhere. So how do you find them? Vim offers various
ways to browse the directory tree. There are commands to jump to a file that
is mentioned in another. And Vim remembers which files have been edited
before.
|22.1| The file explorer
|22.2| The current directory
|22.3| Finding a file
|22.4| The buffer list
Next chapter: |usr_23.txt| Editing other files
Previous chapter: |usr_21.txt| Go away and come back
Table of contents: |usr_toc.txt|
==============================================================================
*22.1* The file explorer
Vim has a plugin that makes it possible to edit a directory. Try this: >
:edit .
Through the magic of autocommands and Vim scripts, the window will be filled
with the contents of the directory. It looks like this:
" Press ? for keyboard shortcuts ~
" Sorted by name (.bak,~,.o,.h,.info,.swp,.obj,.orig,.rej at end of list) ~
"= /home/mool/vim/vim6/runtime/doc/ ~
../ ~
check/ ~
Makefile ~
autocmd.txt ~
change.txt ~
eval.txt~ ~
filetype.txt~ ~
help.txt.info ~
You can see these items:
1. A comment about using ? to get help for the functionality of the file
explorer.
2. The second line mentions how the items in the directory are listed. They
can be sorted in several ways.
3. The third line is the name of the current directory.
4. The "../" directory item. This is the parent directory.
5. The directory names.
6. The ordinary file names. As mentioned in the second line, some are not
here but "at the end of the list".
7. The less ordinary file names. You are expected to use these less often,
therefore they have been moved to the end.
If you have syntax highlighting enabled, the different parts are highlighted
to make it easier to spot them.
You can use Normal mode Vim commands to move around in the text. For example,
move to a file and press <Enter>. Now you are editing that file. To go back
to the explorer use ":edit ." again. CTRL-O also works.
Try using <Enter> while the cursor is on a directory name. The result is
that the explorer moves into that directory and displays the items found
there. Pressing <Enter> on the first directory "../" moves you one level
higher. Pressing "-" does the same thing, without the need to move to the
"../" item first.
You can press ? to get short help on the things you can do in the explorer.
This is what you get:
" <enter> : open file or directory ~
" o : open new window for file/directory ~
" O : open file in previously visited window ~
" p : preview the file ~
" i : toggle size/date listing ~
" s : select sort field r : reverse sort ~
" - : go up one level c : cd to this dir ~
" R : rename file D : delete file ~
" :help file-explorer for detailed help ~
The first few commands are for selecting a file to display. Depending on what
command you use, the file appears somewhere:
<Enter> Uses the current window.
o Opens a new window.
O Uses the previously visited window.
p Uses the preview window, and moves the cursor back
into the explorer window. |preview-window|
The following commands are used to display other information:
i Display the size and date for the file. Using i again
will hide the information.
s Use the field the cursor is in to sort on. First
display the size and date with i. Then Move the
cursor to the size of any file and press s. The files
will now be sorted on size. Press s wile the cursor
is on a date and the items will be sorted on date.
r reverse the sorting order (either size or date)
There are a few extra commands:
c Change the current directory to the displayed
directory. You can then type an ":edit" command for
one of the files without prepending the path.
R Rename the file under the cursor. You will be
prompted for the new name.
D Delete the file under the cursor. You will get a
prompt to confirm this.
==============================================================================
*22.2* The current directory
Just like the shell, Vim has the concept of a current directory. Suppose you
are in your home directory and want to edit several files in a directory
"VeryLongFileName". You could do: >
:edit VeryLongFileName/file1.txt
:edit VeryLongFileName/file2.txt
:edit VeryLongFileName/file3.txt
To avoid much of the typing, do this: >
:cd VeryLongFileName
:edit file1.txt
:edit file2.txt
:edit file3.txt
The ":cd" command changes the current directory. You can see what the current
directory is with the ":pwd" command: >
:pwd
/home/Bram/VeryLongFileName
Vim remembers the last directory that you used. Use "cd -" to go back to it.
Example: >
:pwd
/home/Bram/VeryLongFileName
:cd /etc
:pwd
/etc
:cd -
:pwd
/home/Bram/VeryLongFileName
:cd -
:pwd
/etc
WINDOW LOCAL DIRECTORY
When you split a window, both windows use the same current directory. When
you want to edit a number of files somewhere else in the new window, you can
make it use a different directory, without changing the current directory in
the other window. This is called a local directory. >
:pwd
/home/Bram/VeryLongFileName
:split
:lcd /etc
:pwd
/etc
CTRL-W w
:pwd
/home/Bram/VeryLongFileName
So long as no ":lcd" command has been used, all windows share the same current
directory. Doing a ":cd" command in one window will also change the current
directory of the other window.
For a window where ":lcd" has been used a different current directory is
remembered. Using ":cd" or ":lcd" in other windows will not change it.
When using a ":cd" command in a window that uses a different current
directory, it will go back to using the shared directory.
==============================================================================
*22.3* Finding a file
You are editing a C program that contains this line:
#include "inits.h" ~
You want to see what is in that "inits.h" file. Move the cursor on the name
of the file and type: >
gf
Vim will find the file and edit it.
What if the file is not in the current directory? Vim will use the 'path'
option to find the file. This option is a list of directory names where to
look for your file.
Suppose you have your include files located in "c:/prog/include". This
command will add it to the 'path' option: >
:set path+=c:/prog/include
This directory is an absolute path. No matter where you are, it will be the
same place. What if you have located files in a subdirectory, below where the
file is? Then you can specify a relative path name. This starts with a dot:
>
:set path+=./proto
This tells Vim to look in the directory "proto", below the directory where the
file in which you use "gf" is. Thus using "gf" on "inits.h" will make Vim
look for "proto/inits.h", starting in the directory of the file.
Without the "./", thus "proto", Vim would look in the "proto" directory
below the current directory. And the current directory might not be where the
file that you are editing is located.
The 'path' option allows specifying the directories where to search for files
in many more ways. See the help on the 'path' option.
The 'isfname' option is used to decide which characters are included in the
file name, and which ones are not (e.g., the " character in the example
above).
When you know the file name, but it's not to be found in the file, you can
type it: >
:find inits.h
Vim will then use the 'path' option to try and locate the file. This is the
same as the ":edit" command, except for the use of 'path'.
To open the found file in a new window use CTRL-W f instead of "gf", or use
":sfind" instead of ":find".
A nice way to directly start Vim to edit a file somewhere in the 'path': >
vim "+find stdio.h"
This finds the file "stdio.h" in your value of 'path'. The quotes are
necessary to have one argument |-+c|.
==============================================================================
*22.4* The buffer list
The Vim editor uses the term buffer to describe a file being edited.
Actually, a buffer is a copy of the file that you edit. When you finish
changing the buffer, you write the contents of the buffer to the file.
Buffers not only contain file contents, but also all the marks, settings, and
other stuff that goes with it.
HIDDEN BUFFERS
Suppose you are editing the file one.txt and need to edit the file two.txt.
You could simply use ":edit two.txt", but since you made changes to one.txt
that won't work. You also don't want to write one.txt yet. Vim has a
solution for you: >
:hide edit two.txt
The buffer "one.txt" disappears from the screen, but Vim still knows that you
are editing this buffer, so it keeps the modified text. This is called a
hidden buffer: The buffer contains text, but you can't see it.
The ":hide" command argument is another command. It makes that command
behave like the 'hidden' option was set. You could also set this option
yourself. The effect is that when any buffer is abandoned, it becomes hidden.
Be careful! When you have hidden buffers with changes, don't exit Vim
without making sure you have saved all the buffers.
INACTIVE BUFFERS
When a buffer has been used once, Vim remembers some information about it.
When it is not displayed in a window and it is not hidden, it is still in the
buffer list. This is called an inactive buffer. Overview:
Active Appears in a window, text loaded.
Hidden Not in a window, text loaded.
Inactive Not in a window, no text loaded.
The inactive buffers are remembered, because Vim keeps information about them,
like marks. And remembering the file name is useful too, so that you can see
which files you have edited. And edit them again.
LISTING BUFFERS
View the buffer list with this command: >
:buffers
A command which does the same, is not so obvious to list buffers, but is much
shorter to type: >
:ls
The output could look like this:
1 #h "help.txt" line 62 ~
2 %l+ "usr_21.txt" line 1 ~
3 "usr_toc.txt" line 1 ~
The first column contains the buffer number. You can use this to edit the
buffer without having to type the name, see below.
After the buffer number come the flags. Then the name of the file
and the line number where the cursor was the last time.
The flags that can appear are these (from left to right):
u Buffer is unlisted |unlisted-buffer|.
% Current buffer.
# Alternate buffer.
l Buffer is loaded and displayed.
h Buffer is loaded but hidden.
= Buffer is read-only.
- Buffer is not modifiable, the 'modifiable' option is off.
+ Buffer has been modified.
EDITING A BUFFER
You can edit a buffer by its number. That avoids having to type the file
name: >
:buffer 2
But the only way to know the number is by looking in the buffer list. You can
use the name, or part of it, instead: >
:buffer help
Vim will find a best match for the name you type. If there is only one
buffer that matches the name, it will be used. In this case "help.txt".
To open a buffer in a new window: >
:sbuffer 3
This works with a name as well.
USING THE BUFFER LIST
You can move around in the buffer list with these commands:
:bnext go to next buffer
:bprevious go to previous buffer
:bfirst go to the first buffer
:blast go to the last buffer
To remove a buffer from the list, use this command: >
:bdelete 3
Again, this also works with a name.
If you delete a buffer that was active (visible in a window), that window
will be closed. If you delete the current buffer, the current window will be
closed. If it was the last window, Vim will find another buffer to edit. You
can't be editing nothing!
Note:
Even after removing the buffer with ":bdelete" Vim still remembers it.
It's actually made "unlisted", it no longer appears in the list from
":buffers". The ":buffers!" command will list unlisted buffers (yes,
Vim can do the impossible). To really make Vim forget about a buffer,
use ":bwipe". Also see the 'buflisted' option.
==============================================================================
Next chapter: |usr_23.txt| Editing other files
Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:

343
runtime/doc/usr_23.txt Normal file
View File

@@ -0,0 +1,343 @@
*usr_23.txt* For Vim version 7.0aa. Last change: 2001 Sep 03
VIM USER MANUAL - by Bram Moolenaar
Editing other files
This chapter is about editing files that are not ordinary files. With Vim you
can edit files that are compressed or encrypted. Some files need to be
accessed over the internet. With some restrictions, binary files can be
edited as well.
|23.1| DOS, Mac and Unix files
|23.2| Files on the internet
|23.3| Encryption
|23.4| Binary files
|23.5| Compressed files
Next chapter: |usr_24.txt| Inserting quickly
Previous chapter: |usr_22.txt| Finding the file to edit
Table of contents: |usr_toc.txt|
==============================================================================
*23.1* DOS, Mac and Unix files
Back in the early days, the old Teletype machines used two characters to
start a new line. One to move the carriage back to the first position
(carriage return, <CR>), another to move the paper up (line feed, <LF>).
When computers came out, storage was expensive. Some people decided that
they did not need two characters for end-of-line. The UNIX people decided
they could use <Line Feed> only for end-of-line. The Apple people
standardized on <CR>. The MS-DOS (and Microsoft Windows) folks decided to
keep the old <CR><LF>.
This means that if you try to move a file from one system to another, you
have line-break problems. The Vim editor automatically recognizes the
different file formats and handles things properly behind your back.
The option 'fileformats' contains the various formats that will be tried
when a new file is edited. The following command, for example, tells Vim to
try UNIX format first and MS-DOS format second: >
:set fileformats=unix,dos
You will notice the format in the message you get when editing a file. You
don't see anything if you edit a native file format. Thus editing a Unix file
on Unix won't result in a remark. But when you edit a dos file, Vim will
notify you of this:
"/tmp/test" [dos] 3L, 71C ~
For a Mac file you would see "[mac]".
The detected file format is stored in the 'fileformat' option. To see
which format you have, execute the following command: >
:set fileformat?
The three names that Vim uses are:
unix <LF>
dos <CR><LF>
mac <CR>
USING THE MAC FORMAT
On Unix, <LF> is used to break a line. It's not unusual to have a <CR>
character halfway a line. Incidentally, this happens quite often in Vi (and
Vim) scripts.
On the Macintosh, where <CR> is the line break character, it's possible to
have a <LF> character halfway a line.
The result is that it's not possible to be 100% sure whether a file
containing both <CR> and <LF> characters is a Mac or a Unix file. Therefore,
Vim assumes that on Unix you probably won't edit a Mac file, and doesn't check
for this type of file. To check for this format anyway, add "mac" to
'fileformats': >
:set fileformats+=mac
Then Vim will take a guess at the file format. Watch out for situations where
Vim guesses wrong.
OVERRULING THE FORMAT
If you use the good old Vi and try to edit an MS-DOS format file, you will
find that each line ends with a ^M character. (^M is <CR>). The automatic
detection avoids this. Suppose you do want to edit the file that way? Then
you need to overrule the format: >
:edit ++ff=unix file.txt
The "++" string is an item that tells Vim that an option name follows, which
overrules the default for this single command. "++ff" is used for
'fileformat'. You could also use "++ff=mac" or "++ff=dos".
This doesn't work for any option, only "++ff" and "++enc" are currently
implemented. The full names "++fileformat" and "++encoding" also work.
CONVERSION
You can use the 'fileformat' option to convert from one file format to
another. Suppose, for example, that you have an MS-DOS file named README.TXT
that you want to convert to UNIX format. Start by editing the MS-DOS format
file: >
vim README.TXT
Vim will recognize this as a dos format file. Now change the file format to
UNIX: >
:set fileformat=unix
:write
The file is written in Unix format.
==============================================================================
*23.2* Files on the internet
Someone sends you an e-mail message, which refers to a file by its URL. For
example:
You can find the information here: ~
ftp://ftp.vim.org/pub/vim/README ~
You could start a program to download the file, save it on your local disk and
then start Vim to edit it.
There is a much simpler way. Move the cursor to any character of the URL.
Then use this command: >
gf
With a bit of luck, Vim will figure out which program to use for downloading
the file, download it and edit the copy. To open the file in a new window use
CTRL-W f.
If something goes wrong you will get an error message. It's possible that
the URL is wrong, you don't have permission to read it, the network connection
is down, etc. Unfortunately, it's hard to tell the cause of the error. You
might want to try the manual way of downloading the file.
Accessing files over the internet works with the netrw plugin. Currently URLs
with these formats are recognized:
ftp:// uses ftp
rcp:// uses rcp
scp:// uses scp
http:// uses wget (reading only)
Vim doesn't do the communication itself, it relies on the mentioned programs
to be available on your computer. On most Unix systems "ftp" and "rcp" will
be present. "scp" and "wget" might need to be installed.
Vim detects these URLs for each command that starts editing a new file, also
with ":edit" and ":split", for example. Write commands also work, except for
http://.
For more information, also about passwords, see |netrw|.
==============================================================================
*23.3* Encryption
Some information you prefer to keep to yourself. For example, when writing
a test on a computer that students also use. You don't want clever students
to figure out a way to read the questions before the exam starts. Vim can
encrypt the file for you, which gives you some protection.
To start editing a new file with encryption, use the "-x" argument to start
Vim. Example: >
vim -x exam.txt
Vim prompts you for a key used for encrypting and decrypting the file:
Enter encryption key: ~
Carefully type the secret key now. You cannot see the characters you type,
they will be replaced by stars. To avoid the situation that a typing mistake
will cause trouble, Vim asks you to enter the key again:
Enter same key again: ~
You can now edit this file normally and put in all your secrets. When you
finish editing the file and tell Vim to exit, the file is encrypted and
written.
When you edit the file with Vim, it will ask you to enter the same key
again. You don't need to use the "-x" argument. You can also use the normal
":edit" command. Vim adds a magic string to the file by which it recognizes
that the file was encrypted.
If you try to view this file using another program, all you get is garbage.
Also, if you edit the file with Vim and enter the wrong key, you get garbage.
Vim does not have a mechanism to check if the key is the right one (this makes
it much harder to break the key).
SWITCHING ENCRYPTION ON AND OFF
To disable the encryption of a file, set the 'key' option to an empty string:
>
:set key=
The next time you write the file this will be done without encryption.
Setting the 'key' option to enable encryption is not a good idea, because
the password appears in the clear. Anyone shoulder-surfing can read your
password.
To avoid this problem, the ":X" command was created. It asks you for an
encryption key, just like the "-x" argument did: >
:X
Enter encryption key: ******
Enter same key again: ******
LIMITS ON ENCRYPTION
The encryption algorithm used by Vim is weak. It is good enough to keep out
the casual prowler, but not good enough to keep out a cryptology expert with
lots of time on his hands. Also you should be aware that the swap file is not
encrypted; so while you are editing, people with superuser privileges can read
the unencrypted text from this file.
One way to avoid letting people read your swap file is to avoid using one.
If the -n argument is supplied on the command line, no swap file is used
(instead, Vim puts everything in memory). For example, to edit the encrypted
file "file.txt" without a swap file use the following command: >
vim -x -n file.txt
When already editing a file, the swapfile can be disabled with: >
:setlocal noswapfile
Since there is no swapfile, recovery will be impossible. Save the file a bit
more often to avoid the risk of losing your changes.
While the file is in memory, it is in plain text. Anyone with privilege can
look in the editor's memory and discover the contents of the file.
If you use a viminfo file, be aware that the contents of text registers are
written out in the clear as well.
If you really want to secure the contents of a file, edit it only on a
portable computer not connected to a network, use good encryption tools, and
keep the computer locked up in a big safe when not in use.
==============================================================================
*23.4* Binary files
You can edit binary files with Vim. Vim wasn't really made for this, thus
there are a few restrictions. But you can read a file, change a character and
write it back, with the result that only that one character was changed and
the file is identical otherwise.
To make sure that Vim does not use its clever tricks in the wrong way, add
the "-b" argument when starting Vim: >
vim -b datafile
This sets the 'binary' option. The effect of this is that unexpected side
effects are turned off. For example, 'textwidth' is set to zero, to avoid
automatic formatting of lines. And files are always read in Unix file format.
Binary mode can be used to change a message in a program. Be careful not to
insert or delete any characters, it would stop the program from working. Use
"R" to enter replace mode.
Many characters in the file will be unprintable. To see them in Hex format: >
:set display=uhex
Otherwise, the "ga" command can be used to see the value of the character
under the cursor. The output, when the cursor is on an <Esc>, looks like
this:
<^[> 27, Hex 1b, Octal 033 ~
There might not be many line breaks in the file. To get some overview switch
the 'wrap' option off: >
:set nowrap
BYTE POSITION
To see on which byte you are in the file use this command: >
g CTRL-G
The output is verbose:
Col 9-16 of 9-16; Line 277 of 330; Word 1806 of 2058; Byte 10580 of 12206 ~
The last two numbers are the byte position in the file and the total number of
bytes. This takes into account how 'fileformat' changes the number of bytes
that a line break uses.
To move to a specific byte in the file, use the "go" command. For
example, to move to byte 2345: >
2345go
USING XXD
A real binary editor shows the text in two ways: as it is and in hex format.
You can do this in Vim by first converting the file with the "xxd" program.
This comes with Vim.
First edit the file in binary mode: >
vim -b datafile
Now convert the file to a hex dump with xxd: >
:%!xxd
The text will look like this:
0000000: 1f8b 0808 39d7 173b 0203 7474 002b 4e49 ....9..;..tt.+NI ~
0000010: 4b2c 8660 eb9c ecac c462 eb94 345e 2e30 K,.`.....b..4^.0 ~
0000020: 373b 2731 0b22 0ca6 c1a2 d669 1035 39d9 7;'1.".....i.59. ~
You can now view and edit the text as you like. Vim treats the information as
ordinary text. Changing the hex does not cause the printable character to be
changed, or the other way around.
Finally convert it back with:
>
:%!xxd -r
Only changes in the hex part are used. Changes in the printable text part on
the right are ignored.
See the manual page of xxd for more information.
==============================================================================
*23.5* Compressed files
This is easy: You can edit a compressed file just like any other file. The
"gzip" plugin takes care of decompressing the file when you edit it. And
compressing it again when you write it.
These compression methods are currently supported:
.Z compress
.gz gzip
.bz2 bzip2
Vim uses the mentioned programs to do the actual compression and
decompression. You might need to install the programs first.
==============================================================================
Next chapter: |usr_24.txt| Inserting quickly
Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:

573
runtime/doc/usr_24.txt Normal file
View File

@@ -0,0 +1,573 @@
*usr_24.txt* For Vim version 7.0aa. Last change: 2003 Aug 18
VIM USER MANUAL - by Bram Moolenaar
Inserting quickly
When entering text, Vim offers various ways to reduce the number of keystrokes
and avoid typing mistakes. Use Insert mode completion to repeat previously
typed words. Abbreviate long words to short ones. Type characters that
aren't on your keyboard.
|24.1| Making corrections
|24.2| Showing matches
|24.3| Completion
|24.4| Repeating an insert
|24.5| Copying from another line
|24.6| Inserting a register
|24.7| Abbreviations
|24.8| Entering special characters
|24.9| Digraphs
|24.10| Normal mode commands
Next chapter: |usr_25.txt| Editing formatted text
Previous chapter: |usr_23.txt| Editing other files
Table of contents: |usr_toc.txt|
==============================================================================
*24.1* Making corrections
The <BS> key was already mentioned. It deletes the character just before the
cursor. The <Del> key does the same for the character under (after) the
cursor.
When you typed a whole word wrong, use CTRL-W:
The horse had fallen to the sky ~
CTRL-W
The horse had fallen to the ~
If you really messed up a line and want to start over, use CTRL-U to delete
it. This keeps the text after the cursor and the indent. Only the text from
the first non-blank to the cursor is deleted. With the cursor on the "f" of
"fallen" in the next line pressing CTRL-U does this:
The horse had fallen to the ~
CTRL-U
fallen to the ~
When you spot a mistake a few words back, you need to move the cursor there to
correct it. For example, you typed this:
The horse had follen to the ground ~
You need to change "follen" to "fallen". With the cursor at the end, you
would type this to correct it: >
<Esc>4blraA
< get out of Insert mode <Esc>
four words back 4b
move on top of the "o" l
replace with "a" ra
restart Insert mode A
Another way to do this: >
<C-Left><C-Left><C-Left><C-Left><Right><Del>a<End>
< four words back <C-Left><C-Left><C-Left><C-Left>
move on top of the "o" <Right>
delete the "o" <Del>
insert an "a" a
go to end of the line <End>
This uses special keys to move around, while remaining in Insert mode. This
resembles what you would do in a modeless editor. It's easier to remember,
but takes more time (you have to move your hand from the letters to the cursor
keys, and the <End> key is hard to press without looking at the keyboard).
These special keys are most useful when writing a mapping that doesn't
leave Insert mode. The extra typing doesn't matter then.
An overview of the keys you can use in Insert mode:
<C-Home> to start of the file
<PageUp> a whole screenful up
<Home> to start of line
<S-Left> one word left
<C-Left> one word left
<S-Right> one word right
<C-Right> one word right
<End> to end of the line
<PageDown> a whole screenful down
<C-End> to end of the file
There are a few more, see |ins-special-special|.
==============================================================================
*24.2* Showing matches
When you type a ) it would be nice to see with which ( it matches. To make
Vim do that use this command: >
:set showmatch
When you now type a text like "(example)", as soon as you type the ) Vim will
briefly move the cursor to the matching (, keep it there for half a second,
and move back to where you were typing.
In case there is not matching (, Vim will beep. Then you know that you
might have forgotten the ( somewhere, or typed a ) too many.
The match will also be shown for [] and {} pairs. You don't have to wait
with typing the next character, as soon as Vim sees it the cursor will move
back and inserting continues as before.
You can change the time Vim waits with the 'matchtime' option. For
example, to make Vim wait one and a half second: >
:set matchtime=15
The time is specified in tenths of a second.
==============================================================================
*24.3* Completion
Vim can automatically complete words on insertion. You type the first part of
a word, press CTRL-P, and Vim guesses the rest.
Suppose, for example, that you are creating a C program and want to type in
the following:
total = ch_array[0] + ch_array[1] + ch_array[2]; ~
You start by entering the following:
total = ch_array[0] + ch_ ~
At this point, you tell Vim to complete the word using the command CTRL-P.
Vim searches for a word that starts with what's in front of the cursor. In
this case, it is "ch_", which matches with the word ch_array. So typing
CTRL-P gives you the following:
total = ch_array[0] + ch_array ~
After a little more typing, you get this (ending in a space):
total = ch_array[0] + ch_array[1] + ~
If you now type CTRL-P Vim will search again for a word that completes the
word before the cursor. Since there is nothing in front of the cursor, it
finds the first word backwards, which is "ch_array". Typing CTRL-P again
gives you the next word that matches, in this case "total". A third CTRL-P
searches further back. If there is nothing else, it causes the editor to run
out of words, so it returns to the original text, which is nothing. A fourth
CTRL-P causes the editor to start over again with "ch_array".
To search forward, use CTRL-N. Since the search wraps around the end of the
file, CTRL-N and CTRL-P will find the same matches, but in a different
sequence. Hint: CTRL-N is Next-match and CTRL-P is Previous-match.
The Vim editor goes through a lot of effort to find words to complete. By
default, it searches the following places:
1. Current file
2. Files in other windows
3. Other loaded files (hidden buffers)
4. Files which are not loaded (inactive buffers)
5. Tag files
6. All files #included by the current file
OPTIONS
You can customize the search order with the 'complete' option.
The 'ignorecase' option is used. When it is set, case differences are ignored
when searching for matches.
A special option for completion is 'infercase'. This is useful to find
matches while ignoring case ('ignorecase' must be set) but still using the
case of the word typed so far. Thus if you type "For" and Vim finds a match
"fortunately", it will result in "Fortunately".
COMPLETING SPECIFIC ITEMS
If you know what you are looking for, you can use these commands to complete
with a certain type of item:
CTRL-X CTRL-F file names
CTRL-X CTRL-L whole lines
CTRL-X CTRL-D macro definitions (also in included files)
CTRL-X CTRL-I current and included files
CTRL-X CTRL-K words from a dictionary
CTRL-X CTRL-T words from a thesaurus
CTRL-X CTRL-] tags
CTRL-X CTRL-V Vim command line
After each of them CTRL-N can be used to find the next match, CTRL-P to find
the previous match.
More information for each of these commands here: |ins-completion|.
COMPLETING FILE NAMES
Let's take CTRL-X CTRL-F as an example. This will find file names. It scans
the current directory for files and displays each one that matches the word in
front of the cursor.
Suppose, for example, that you have the following files in the current
directory:
main.c sub_count.c sub_done.c sub_exit.c
Now enter Insert mode and start typing:
The exit code is in the file sub ~
At this point, you enter the command CTRL-X CTRL-F. Vim now completes the
current word "sub" by looking at the files in the current directory. The
first match is sub_count.c. This is not the one you want, so you match the
next file by typing CTRL-N. This match is sub_done.c. Typing CTRL-N again
takes you to sub_exit.c. The results:
The exit code is in the file sub_exit.c ~
If the file name starts with / (Unix) or C:\ (MS-Windows) you can find all
files in the file system. For example, type "/u" and CTRL-X CTRL-F. This
will match "/usr" (this is on Unix):
the file is found in /usr/ ~
If you now press CTRL-N you go back to "/u". Instead, to accept the "/usr/"
and go one directory level deeper, use CTRL-X CTRL-F again:
the file is found in /usr/X11R6/ ~
The results depend on what is found in your file system, of course. The
matches are sorted alphabetically.
==============================================================================
*24.4* Repeating an insert
If you press CTRL-A, the editor inserts the text you typed the last time you
were in Insert mode.
Assume, for example, that you have a file that begins with the following:
"file.h" ~
/* Main program begins */ ~
You edit this file by inserting "#include " at the beginning of the first
line:
#include "file.h" ~
/* Main program begins */ ~
You go down to the beginning of the next line using the commands "j^". You
now start to insert a new "#include" line. So you type: >
i CTRL-A
The result is as follows:
#include "file.h" ~
#include /* Main program begins */ ~
The "#include " was inserted because CTRL-A inserts the text of the previous
insert. Now you type "main.h"<Enter> to finish the line:
#include "file.h" ~
#include "main.h" ~
/* Main program begins */ ~
The CTRL-@ command does a CTRL-A and then exits Insert mode. That's a quick
way of doing exactly the same insertion again.
==============================================================================
*24.5* Copying from another line
The CTRL-Y command inserts the character above the cursor. This is useful
when you are duplicating a previous line. For example, you have this line of
C code:
b_array[i]->s_next = a_array[i]->s_next; ~
Now you need to type the same line, but with "s_prev" instead of "s_next".
Start the new line, and press CTRL-Y 14 times, until you are at the "n" of
"next":
b_array[i]->s_next = a_array[i]->s_next; ~
b_array[i]->s_ ~
Now you type "prev":
b_array[i]->s_next = a_array[i]->s_next; ~
b_array[i]->s_prev ~
Continue pressing CTRL-Y until the following "next":
b_array[i]->s_next = a_array[i]->s_next; ~
b_array[i]->s_prev = a_array[i]->s_ ~
Now type "prev;" to finish it off.
The CTRL-E command acts like CTRL-Y except it inserts the character below the
cursor.
==============================================================================
*24.6* Inserting a register
The command CTRL-R {register} inserts the contents of the register. This is
useful to avoid having to type a long word. For example, you need to type
this:
r = VeryLongFunction(a) + VeryLongFunction(b) + VeryLongFunction(c) ~
The function name is defined in a different file. Edit that file and move the
cursor on top of the function name there, and yank it into register v: >
"vyiw
"v is the register specification, "yiw" is yank-inner-word. Now edit the file
where the new line is to be inserted, and type the first letters:
r = ~
Now use CTRL-R v to insert the function name:
r = VeryLongFunction ~
You continue to type the characters in between the function name, and use
CTRL-R v two times more.
You could have done the same with completion. Using a register is useful
when there are many words that start with the same characters.
If the register contains characters such as <BS> or other special characters,
they are interpreted as if they had been typed from the keyboard. If you do
not want this to happen (you really want the <BS> to be inserted in the text),
use the command CTRL-R CTRL-R {register}.
==============================================================================
*24.7* Abbreviations
An abbreviation is a short word that takes the place of a long one. For
example, "ad" stands for "advertisement". Vim enables you to type an
abbreviation and then will automatically expand it for you.
To tell Vim to expand "ad" into "advertisement" every time you insert it,
use the following command: >
:iabbrev ad advertisement
Now, when you type "ad", the whole word "advertisement" will be inserted into
the text. This is triggered by typing a character that can't be part of a
word, for example a space:
What Is Entered What You See
I saw the a I saw the a ~
I saw the ad I saw the ad ~
I saw the ad<Space> I saw the advertisement<Space> ~
The expansion doesn't happen when typing just "ad". That allows you to type a
word like "add", which will not get expanded. Only whole words are checked
for abbreviations.
ABBREVIATING SEVERAL WORDS
It is possible to define an abbreviation that results in multiple words. For
example, to define "JB" as "Jack Benny", use the following command: >
:iabbrev JB Jack Benny
As a programmer, I use two rather unusual abbreviations: >
:iabbrev #b /****************************************
:iabbrev #e <Space>****************************************/
These are used for creating boxed comments. The comment starts with #b, which
draws the top line. I then type the comment text and use #e to draw the
bottom line.
Notice that the #e abbreviation begins with a space. In other words, the
first two characters are space-star. Usually Vim ignores spaces between the
abbreviation and the expansion. To avoid that problem, I spell space as seven
characters: <, S, p, a, c, e, >.
Note:
":iabbrev" is a long word to type. ":iab" works just as well.
That's abbreviating the abbreviate command!
FIXING TYPING MISTAKES
It's very common to make the same typing mistake every time. For example,
typing "teh" instead of "the". You can fix this with an abbreviation: >
:abbreviate teh the
You can add a whole list of these. Add one each time you discover a common
mistake.
LISTING ABBREVIATIONS
The ":abbreviate" command lists the abbreviations:
:abbreviate
i #e ****************************************/
i #b /****************************************
i JB Jack Benny
i ad advertisement
! teh the
The "i" in the first column indicates Insert mode. These abbreviations are
only active in Insert mode. Other possible characters are:
c Command-line mode :cabbrev
! both Insert and Command-line mode :abbreviate
Since abbreviations are not often useful in Command-line mode, you will mostly
use the ":iabbrev" command. That avoids, for example, that "ad" gets expanded
when typing a command like: >
:edit ad
DELETING ABBREVIATIONS
To get rid of an abbreviation, use the ":unabbreviate" command. Suppose you
have the following abbreviation: >
:abbreviate @f fresh
You can remove it with this command: >
:unabbreviate @f
While you type this, you will notice that @f is expanded to "fresh". Don't
worry about this, Vim understands it anyway (except when you have an
abbreviation for "fresh", but that's very unlikely).
To remove all the abbreviations: >
:abclear
":unabbreviate" and ":abclear" also come in the variants for Insert mode
(":iunabbreviate and ":iabclear") and Command-line mode (":cunabbreviate" and
":cabclear").
REMAPPING ABBREVIATIONS
There is one thing to watch out for when defining an abbreviation: The
resulting string should not be mapped. For example: >
:abbreviate @a adder
:imap dd disk-door
When you now type @a, you will get "adisk-doorer". That's not what you want.
To avoid this, use the ":noreabbrev" command. It does the same as
":abbreviate", but avoids that the resulting string is used for mappings: >
:noreabbrev @a adder
Fortunately, it's unlikely that the result of an abbreviation is mapped.
==============================================================================
*24.8* Entering special characters
The CTRL-V command is used to insert the next character literally. In other
words, any special meaning the character has, it will be ignored. For
example: >
CTRL-V <Esc>
Inserts an escape character. Thus you don't leave Insert mode. (Don't type
the space after CTRL-V, it's only to make this easier to read).
Note:
On MS-Windows CTRL-V is used to paste text. Use CTRL-Q instead of
CTRL-V. On Unix, on the other hand, CTRL-Q does not work on some
terminals, because it has a special meaning.
You can also use the command CTRL-V {digits} to insert a character with the
decimal number {digits}. For example, the character number 127 is the <Del>
character (but not necessarily the <Del> key!). To insert <Del> type: >
CTRL-V 127
You can enter characters up to 255 this way. When you type fewer than two
digits, a non-digit will terminate the command. To avoid the need of typing a
non-digit, prepend one or two zeros to make three digits.
All the next commands insert a <Tab> and then a dot:
CTRL-V 9.
CTRL-V 09.
CTRL-V 009.
To enter a character in hexadecimal, use an "x" after the CTRL-V: >
CTRL-V x7f
This also goes up to character 255 (CTRL-V xff). You can use "o" to type a
character as an octal number and two more methods allow you to type up to
a 16 bit and a 32 bit number (e.g., for a Unicode character): >
CTRL-V o123
CTRL-V u1234
CTRL-V U12345678
==============================================================================
*24.9* Digraphs
Some characters are not on the keyboard. For example, the copyright character
(©). To type these characters in Vim, you use digraphs, where two characters
represent one. To enter a ©, for example, you press three keys: >
CTRL-K Co
To find out what digraphs are available, use the following command: >
:digraphs
Vim will display the digraph table. Here are three lines of it:
AC ~_ 159 NS | 160 !I ¡ 161 Ct ¢ 162 Pd £ 163 Cu ¤ 164 Ye ¥ 165 ~
BB ¦ 166 SE § 167 ': ¨ 168 Co © 169 -a ª 170 << « 171 NO ¬ 172 ~
-- ­ 173 Rg ® 174 'm ¯ 175 DG ° 176 +- ± 177 2S ² 178 3S ³ 179 ~
This shows, for example, that the digraph you get by typing CTRL-K Pd is the
character (£). This is character number 163 (decimal).
Pd is short for Pound. Most digraphs are selected to give you a hint about
the character they will produce. If you look through the list you will
understand the logic.
You can exchange the first and second character, if there is no digraph for
that combination. Thus CTRL-K dP also works. Since there is no digraph for
"dP" Vim will also search for a "Pd" digraph.
Note:
The digraphs depend on the character set that Vim assumes you are
using. On MS-DOS they are different from MS-Windows. Always use
":digraphs" to find out which digraphs are currently available.
You can define your own digraphs. Example: >
:digraph a" ä
This defines that CTRL-K a" inserts an ä character. You can also specify the
character with a decimal number. This defines the same digraph: >
:digraph a" 228
More information about digraphs here: |digraphs|
Another way to insert special characters is with a keymap. More about that
here: |45.5|
==============================================================================
*24.10* Normal mode commands
Insert mode offers a limited number of commands. In Normal mode you have many
more. When you want to use one, you usually leave Insert mode with <Esc>,
execute the Normal mode command, and re-enter Insert mode with "i" or "a".
There is a quicker way. With CTRL-O {command} you can execute any Normal
mode command from Insert mode. For example, to delete from the cursor to the
end of the line: >
CTRL-O D
You can execute only one Normal mode command this way. But you can specify a
register or a count. A more complicated example: >
CTRL-O "g3dw
This deletes up to the third word into register g.
==============================================================================
Next chapter: |usr_25.txt| Editing formatted text
Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:

Some files were not shown because too many files have changed in this diff Show More