From c2e38d42055fe720797b5c1ff1c3ff7dbcb91aa5 Mon Sep 17 00:00:00 2001 From: simonlaszcz Date: Fri, 24 May 2024 17:07:11 +0100 Subject: [PATCH] ATARI TOS port --- .gitignore | 9 + README_tos.txt | 2 + runtime_tos/colors/README.txt | 72 + runtime_tos/colors/blue.vim | 55 + runtime_tos/colors/darkblue.vim | 66 + runtime_tos/colors/default.vim | 23 + runtime_tos/colors/delek.vim | 55 + runtime_tos/colors/desert.vim | 108 ++ runtime_tos/colors/elflord.vim | 50 + runtime_tos/colors/evening.vim | 56 + runtime_tos/colors/industry.vim | 40 + runtime_tos/colors/koehler.vim | 72 + runtime_tos/colors/morning.vim | 56 + runtime_tos/colors/murphy.vim | 41 + runtime_tos/colors/pablo.vim | 26 + runtime_tos/colors/peachpuff.vim | 60 + runtime_tos/colors/ron.vim | 45 + runtime_tos/colors/shine.vim | 60 + runtime_tos/colors/slate.vim | 56 + runtime_tos/colors/torte.vim | 50 + runtime_tos/colors/zellner.vim | 54 + runtime_tos/compiler/devpac.vim | 17 + runtime_tos/compiler/gcc.vim | 39 + runtime_tos/doc/doctags.c | 83 + runtime_tos/doc/help.txt | 100 ++ runtime_tos/doc/os_atari.txt | 180 +++ runtime_tos/doc/uganda.txt | 288 ++++ runtime_tos/doc/usr_01.txt | 192 +++ runtime_tos/doc/usr_02.txt | 564 +++++++ runtime_tos/doc/usr_03.txt | 654 ++++++++ runtime_tos/doc/usr_04.txt | 514 +++++++ runtime_tos/doc/usr_05.txt | 624 ++++++++ runtime_tos/doc/usr_06.txt | 280 ++++ runtime_tos/doc/usr_07.txt | 479 ++++++ runtime_tos/doc/usr_08.txt | 601 ++++++++ runtime_tos/doc/usr_09.txt | 289 ++++ runtime_tos/doc/usr_10.txt | 824 ++++++++++ runtime_tos/doc/usr_11.txt | 307 ++++ runtime_tos/doc/usr_12.txt | 358 +++++ runtime_tos/doc/usr_20.txt | 384 +++++ runtime_tos/doc/usr_21.txt | 499 ++++++ runtime_tos/doc/usr_22.txt | 400 +++++ runtime_tos/doc/usr_23.txt | 343 +++++ runtime_tos/doc/usr_24.txt | 606 ++++++++ runtime_tos/doc/usr_25.txt | 578 +++++++ runtime_tos/doc/usr_26.txt | 221 +++ runtime_tos/doc/usr_27.txt | 563 +++++++ runtime_tos/doc/usr_28.txt | 426 +++++ runtime_tos/doc/usr_29.txt | 613 ++++++++ runtime_tos/doc/usr_30.txt | 643 ++++++++ runtime_tos/doc/usr_31.txt | 272 ++++ runtime_tos/doc/usr_32.txt | 180 +++ runtime_tos/doc/usr_40.txt | 657 ++++++++ runtime_tos/doc/usr_41.txt | 2472 ++++++++++++++++++++++++++++++ runtime_tos/doc/usr_42.txt | 365 +++++ runtime_tos/doc/usr_43.txt | 173 +++ runtime_tos/doc/usr_44.txt | 719 +++++++++ runtime_tos/doc/usr_45.txt | 419 +++++ runtime_tos/doc/usr_90.txt | 498 ++++++ runtime_tos/doc/usr_toc.txt | 354 +++++ runtime_tos/indent/README.txt | 45 + runtime_tos/indent/c.vim | 15 + runtime_tos/plugin/filetype.vix | 175 +++ runtime_tos/readme.txt | 1 + runtime_tos/syntax/README.txt | 38 + runtime_tos/syntax/asm68k.vim | 391 +++++ runtime_tos/syntax/basic.vim | 179 +++ runtime_tos/syntax/c.vim | 466 ++++++ runtime_tos/syntax/colors.vim | 81 + runtime_tos/syntax/forth.vim | 347 +++++ runtime_tos/syntax/make.vim | 143 ++ runtime_tos/syntax/modula2.vim | 86 ++ runtime_tos/syntax/modula3.vim | 72 + runtime_tos/syntax/nosyntax.vim | 30 + runtime_tos/syntax/pascal.vim | 373 +++++ runtime_tos/syntax/syncolor.vim | 85 + runtime_tos/syntax/synload.vim | 78 + runtime_tos/syntax/syntax.vim | 43 + runtime_tos/syntax/tags.vim | 47 + runtime_tos/syntax/vim.vim | 922 +++++++++++ runtime_tos/syntax/viminfo.vim | 44 + runtime_tos/syntax/xxd.vim | 42 + runtime_tos/syntax/z8a.vim | 114 ++ src/Make_tos.mak | 179 +++ src/blank.st | Bin 0 -> 737280 bytes src/blowfish.c | 5 +- src/diff.c | 8 +- src/digraph.c | 2 +- src/eval.c | 8 + src/ex_cmds.c | 2 + src/ex_cmds.h | 12 + src/ex_cmds2.c | 13 + src/ex_docmd.c | 52 + src/ex_getln.c | 11 +- src/feature.h | 8 +- src/fileio.c | 6 +- src/globals.h | 13 +- src/macros.h | 8 +- src/mbyte.c | 2 +- src/memfile.c | 2 +- src/memline.c | 12 +- src/misc1.c | 16 +- src/misc2.c | 4 +- src/netbeans.c | 2 +- src/normal.c | 3 + src/ops.c | 3 + src/option.c | 7 +- src/os_tos.c | 1210 +++++++++++++++ src/os_tos.h | 252 +++ src/os_tos_debug.h | 31 + src/os_tos_ext.c | 257 ++++ src/os_tos_ext.h | 53 + src/os_tos_geneva.h | 24 + src/os_tos_magic.h | 59 + src/os_tos_vdo.c | 809 ++++++++++ src/os_tos_vdo.h | 16 + src/proto.h | 3 + src/proto/ex_cmds2.pro | 3 + src/proto/os_tos.pro | 59 + src/proto/syntax.pro | 3 + src/search.c | 2 + src/syntax.c | 23 + src/tag.c | 6 +- src/term.c | 95 +- src/tos_utils/Makefile | 23 + src/tos_utils/tospal.c | 11 + src/version.c | 7 + src/vim.h | 22 +- src/vimrc | 2 + src/vimrcs | 1 + src/vimrct | 24 + src/window.c | 2 +- src/xxd/Make_tos.mak | 25 + src/xxd/xxd.c | 18 +- 134 files changed, 25990 insertions(+), 79 deletions(-) create mode 100644 README_tos.txt create mode 100644 runtime_tos/colors/README.txt create mode 100644 runtime_tos/colors/blue.vim create mode 100644 runtime_tos/colors/darkblue.vim create mode 100644 runtime_tos/colors/default.vim create mode 100644 runtime_tos/colors/delek.vim create mode 100644 runtime_tos/colors/desert.vim create mode 100644 runtime_tos/colors/elflord.vim create mode 100644 runtime_tos/colors/evening.vim create mode 100644 runtime_tos/colors/industry.vim create mode 100644 runtime_tos/colors/koehler.vim create mode 100644 runtime_tos/colors/morning.vim create mode 100644 runtime_tos/colors/murphy.vim create mode 100644 runtime_tos/colors/pablo.vim create mode 100644 runtime_tos/colors/peachpuff.vim create mode 100644 runtime_tos/colors/ron.vim create mode 100644 runtime_tos/colors/shine.vim create mode 100644 runtime_tos/colors/slate.vim create mode 100644 runtime_tos/colors/torte.vim create mode 100644 runtime_tos/colors/zellner.vim create mode 100644 runtime_tos/compiler/devpac.vim create mode 100644 runtime_tos/compiler/gcc.vim create mode 100644 runtime_tos/doc/doctags.c create mode 100644 runtime_tos/doc/help.txt create mode 100644 runtime_tos/doc/os_atari.txt create mode 100644 runtime_tos/doc/uganda.txt create mode 100644 runtime_tos/doc/usr_01.txt create mode 100644 runtime_tos/doc/usr_02.txt create mode 100644 runtime_tos/doc/usr_03.txt create mode 100644 runtime_tos/doc/usr_04.txt create mode 100644 runtime_tos/doc/usr_05.txt create mode 100644 runtime_tos/doc/usr_06.txt create mode 100644 runtime_tos/doc/usr_07.txt create mode 100644 runtime_tos/doc/usr_08.txt create mode 100644 runtime_tos/doc/usr_09.txt create mode 100644 runtime_tos/doc/usr_10.txt create mode 100644 runtime_tos/doc/usr_11.txt create mode 100644 runtime_tos/doc/usr_12.txt create mode 100644 runtime_tos/doc/usr_20.txt create mode 100644 runtime_tos/doc/usr_21.txt create mode 100644 runtime_tos/doc/usr_22.txt create mode 100644 runtime_tos/doc/usr_23.txt create mode 100644 runtime_tos/doc/usr_24.txt create mode 100644 runtime_tos/doc/usr_25.txt create mode 100644 runtime_tos/doc/usr_26.txt create mode 100644 runtime_tos/doc/usr_27.txt create mode 100644 runtime_tos/doc/usr_28.txt create mode 100644 runtime_tos/doc/usr_29.txt create mode 100644 runtime_tos/doc/usr_30.txt create mode 100644 runtime_tos/doc/usr_31.txt create mode 100644 runtime_tos/doc/usr_32.txt create mode 100644 runtime_tos/doc/usr_40.txt create mode 100644 runtime_tos/doc/usr_41.txt create mode 100644 runtime_tos/doc/usr_42.txt create mode 100644 runtime_tos/doc/usr_43.txt create mode 100644 runtime_tos/doc/usr_44.txt create mode 100644 runtime_tos/doc/usr_45.txt create mode 100644 runtime_tos/doc/usr_90.txt create mode 100644 runtime_tos/doc/usr_toc.txt create mode 100644 runtime_tos/indent/README.txt create mode 100644 runtime_tos/indent/c.vim create mode 100644 runtime_tos/plugin/filetype.vix create mode 100644 runtime_tos/readme.txt create mode 100644 runtime_tos/syntax/README.txt create mode 100644 runtime_tos/syntax/asm68k.vim create mode 100644 runtime_tos/syntax/basic.vim create mode 100644 runtime_tos/syntax/c.vim create mode 100644 runtime_tos/syntax/colors.vim create mode 100644 runtime_tos/syntax/forth.vim create mode 100644 runtime_tos/syntax/make.vim create mode 100644 runtime_tos/syntax/modula2.vim create mode 100644 runtime_tos/syntax/modula3.vim create mode 100644 runtime_tos/syntax/nosyntax.vim create mode 100644 runtime_tos/syntax/pascal.vim create mode 100644 runtime_tos/syntax/syncolor.vim create mode 100644 runtime_tos/syntax/synload.vim create mode 100644 runtime_tos/syntax/syntax.vim create mode 100644 runtime_tos/syntax/tags.vim create mode 100644 runtime_tos/syntax/vim.vim create mode 100644 runtime_tos/syntax/viminfo.vim create mode 100644 runtime_tos/syntax/xxd.vim create mode 100644 runtime_tos/syntax/z8a.vim create mode 100644 src/Make_tos.mak create mode 100644 src/blank.st create mode 100644 src/os_tos.c create mode 100644 src/os_tos.h create mode 100644 src/os_tos_debug.h create mode 100644 src/os_tos_ext.c create mode 100644 src/os_tos_ext.h create mode 100644 src/os_tos_geneva.h create mode 100644 src/os_tos_magic.h create mode 100644 src/os_tos_vdo.c create mode 100644 src/os_tos_vdo.h create mode 100644 src/proto/os_tos.pro create mode 100644 src/tos_utils/Makefile create mode 100644 src/tos_utils/tospal.c create mode 100644 src/vimrc create mode 100644 src/vimrcs create mode 100644 src/vimrct create mode 100644 src/xxd/Make_tos.mak diff --git a/.gitignore b/.gitignore index f13ca061b37884..6d90493176f3d2 100644 --- a/.gitignore +++ b/.gitignore @@ -70,3 +70,12 @@ src/testdir/small.vim src/testdir/tiny.vim src/testdir/test*.out src/testdir/test.log + +# TOS +tostest/ +tmp/ +*.ttp +*.tos +log.* +tags +run.sh diff --git a/README_tos.txt b/README_tos.txt new file mode 100644 index 00000000000000..e4489bedd231cf --- /dev/null +++ b/README_tos.txt @@ -0,0 +1,2 @@ +:rez to change resolution +Current resolution from v:resolution variable diff --git a/runtime_tos/colors/README.txt b/runtime_tos/colors/README.txt new file mode 100644 index 00000000000000..3b3445cbc9096f --- /dev/null +++ b/runtime_tos/colors/README.txt @@ -0,0 +1,72 @@ +README.txt for color scheme files + +These files are used for the ":colorscheme" command. They appear in the +Edit/Color Scheme menu in the GUI. + + +Hints for writing a color scheme file: + +There are two basic ways to define a color scheme: + +1. Define a new Normal color and set the 'background' option accordingly. + set background={light or dark} + highlight clear + highlight Normal ... + ... + +2. Use the default Normal color and automatically adjust to the value of + 'background'. + highlight clear Normal + set background& + highlight clear + if &background == "light" + highlight Error ... + ... + else + highlight Error ... + ... + endif + +You can use ":highlight clear" to reset everything to the defaults, and then +change the groups that you want differently. This also will work for groups +that are added in later versions of Vim. +Note that ":highlight clear" uses the value of 'background', thus set it +before this command. +Some attributes (e.g., bold) might be set in the defaults that you want +removed in your color scheme. Use something like "gui=NONE" to remove the +attributes. + +In case you want to set 'background' depending on the colorscheme selected, +this autocmd might be useful: + autocmd SourcePre */colors/blue_sky.vim set background=dark +Replace "blue_sky" with the name of the colorscheme. + +In case you want to tweak a colorscheme after it was loaded, check out that +ColorScheme autocmd event. + +To see which highlight group is used where, find the help for +"highlight-groups" and "group-name". + +You can use ":highlight" to find out the current colors. Exception: the +ctermfg and ctermbg values are numbers, which are only valid for the current +terminal. Use the color names instead. See ":help cterm-colors". + +The default color settings can be found in the source file src/syntax.c. +Search for "highlight_init". + +If you think you have a color scheme that is good enough to be used by others, +please check the following items: + +- Does it work in a color terminal as well as in the GUI? +- Is "g:colors_name" set to a meaningful value? In case of doubt you can do + it this way: + let g:colors_name = expand(':t:r') +- Is 'background' either used or appropriately set to "light" or "dark"? +- Try setting 'hlsearch' and searching for a pattern, is the match easy to + spot? +- Split a window with ":split" and ":vsplit". Are the status lines and + vertical separators clearly visible? +- In the GUI, is it easy to find the cursor, also in a file with lots of + syntax highlighting? +- Do not use hard coded escape sequences, these will not work in other + terminals. Always use color names or #RRGGBB for the GUI. diff --git a/runtime_tos/colors/blue.vim b/runtime_tos/colors/blue.vim new file mode 100644 index 00000000000000..86de8a4dc435cb --- /dev/null +++ b/runtime_tos/colors/blue.vim @@ -0,0 +1,55 @@ +" local syntax file - set colors on a per-machine basis: +" vim: tw=0 ts=4 sw=4 +" Vim color file +" Maintainer: Steven Vertigan +" Last Change: 2006 Sep 23 +" Revision #5: Switch main text from white to yellow for easier contrast, +" fixed some problems with terminal backgrounds. + +set background=dark +hi clear +if exists("syntax_on") + syntax reset +endif +let g:colors_name = "blue" +hi Normal guifg=yellow guibg=darkBlue ctermfg=yellow ctermbg=darkBlue +hi NonText guifg=magenta ctermfg=lightMagenta +hi comment guifg=gray ctermfg=gray ctermbg=darkBlue gui=bold +hi constant guifg=cyan ctermfg=cyan +hi identifier guifg=gray ctermfg=red +hi statement guifg=white ctermfg=white ctermbg=darkBlue gui=none +hi preproc guifg=green ctermfg=green +hi type guifg=orange ctermfg=lightRed ctermbg=darkBlue +hi special guifg=magenta ctermfg=lightMagenta ctermbg=darkBlue +hi Underlined guifg=cyan ctermfg=cyan gui=underline cterm=underline +hi label guifg=yellow ctermfg=yellow +hi operator guifg=orange gui=bold ctermfg=lightRed ctermbg=darkBlue + +hi ErrorMsg guifg=orange guibg=darkBlue ctermfg=lightRed +hi WarningMsg guifg=cyan guibg=darkBlue ctermfg=cyan gui=bold +hi ModeMsg guifg=yellow gui=NONE ctermfg=yellow +hi MoreMsg guifg=yellow gui=NONE ctermfg=yellow +hi Error guifg=red guibg=darkBlue gui=underline ctermfg=red + +hi Todo guifg=black guibg=orange ctermfg=black ctermbg=darkYellow +hi Cursor guifg=black guibg=white ctermfg=black ctermbg=white +hi Search guifg=black guibg=orange ctermfg=black ctermbg=darkYellow +hi IncSearch guifg=black guibg=yellow ctermfg=black ctermbg=darkYellow +hi LineNr guifg=cyan ctermfg=cyan +hi title guifg=white gui=bold cterm=bold + +hi StatusLineNC gui=NONE guifg=black guibg=blue ctermfg=black ctermbg=blue +hi StatusLine gui=bold guifg=cyan guibg=blue ctermfg=cyan ctermbg=blue +hi VertSplit gui=none guifg=blue guibg=blue ctermfg=blue ctermbg=blue + +hi Visual term=reverse ctermfg=black ctermbg=darkCyan guifg=black guibg=darkCyan + +hi DiffChange guibg=darkGreen guifg=black ctermbg=darkGreen ctermfg=black +hi DiffText guibg=olivedrab guifg=black ctermbg=lightGreen ctermfg=black +hi DiffAdd guibg=slateblue guifg=black ctermbg=blue ctermfg=black +hi DiffDelete guibg=coral guifg=black ctermbg=cyan ctermfg=black + +hi Folded guibg=orange guifg=black ctermbg=yellow ctermfg=black +hi FoldColumn guibg=gray30 guifg=black ctermbg=gray ctermfg=black +hi cIf0 guifg=gray ctermfg=gray + diff --git a/runtime_tos/colors/darkblue.vim b/runtime_tos/colors/darkblue.vim new file mode 100644 index 00000000000000..411712272821b7 --- /dev/null +++ b/runtime_tos/colors/darkblue.vim @@ -0,0 +1,66 @@ +" Vim color file +" Maintainer: Bohdan Vlasyuk +" Last Change: 2008 Jul 18 + +" darkblue -- for those who prefer dark background +" [note: looks bit uglier with come terminal palettes, +" but is fine on default linux console palette.] + +set bg=dark +hi clear +if exists("syntax_on") + syntax reset +endif + +let colors_name = "darkblue" + +hi Normal guifg=#c0c0c0 guibg=#000040 ctermfg=gray ctermbg=black +hi ErrorMsg guifg=#ffffff guibg=#287eff ctermfg=white ctermbg=lightblue +hi Visual guifg=#8080ff guibg=fg gui=reverse ctermfg=lightblue ctermbg=fg cterm=reverse +hi VisualNOS guifg=#8080ff guibg=fg gui=reverse,underline ctermfg=lightblue ctermbg=fg cterm=reverse,underline +hi Todo guifg=#d14a14 guibg=#1248d1 ctermfg=red ctermbg=darkblue +hi Search guifg=#90fff0 guibg=#2050d0 ctermfg=white ctermbg=darkblue cterm=underline term=underline +hi IncSearch guifg=#b0ffff guibg=#2050d0 ctermfg=darkblue ctermbg=gray + +hi SpecialKey guifg=cyan ctermfg=darkcyan +hi Directory guifg=cyan ctermfg=cyan +hi Title guifg=magenta gui=none ctermfg=magenta cterm=bold +hi WarningMsg guifg=red ctermfg=red +hi WildMenu guifg=yellow guibg=black ctermfg=yellow ctermbg=black cterm=none term=none +hi ModeMsg guifg=#22cce2 ctermfg=lightblue +hi MoreMsg ctermfg=darkgreen ctermfg=darkgreen +hi Question guifg=green gui=none ctermfg=green cterm=none +hi NonText guifg=#0030ff ctermfg=darkblue + +hi StatusLine guifg=blue guibg=darkgray gui=none ctermfg=blue ctermbg=gray term=none cterm=none +hi StatusLineNC guifg=black guibg=darkgray gui=none ctermfg=black ctermbg=gray term=none cterm=none +hi VertSplit guifg=black guibg=darkgray gui=none ctermfg=black ctermbg=gray term=none cterm=none + +hi Folded guifg=#808080 guibg=#000040 ctermfg=darkgrey ctermbg=black cterm=bold term=bold +hi FoldColumn guifg=#808080 guibg=#000040 ctermfg=darkgrey ctermbg=black cterm=bold term=bold +hi LineNr guifg=#90f020 ctermfg=green cterm=none + +hi DiffAdd guibg=darkblue ctermbg=darkblue term=none cterm=none +hi DiffChange guibg=darkmagenta ctermbg=magenta cterm=none +hi DiffDelete ctermfg=blue ctermbg=cyan gui=bold guifg=Blue guibg=DarkCyan +hi DiffText cterm=bold ctermbg=red gui=bold guibg=Red + +hi Cursor guifg=black guibg=yellow ctermfg=black ctermbg=yellow +hi lCursor guifg=black guibg=white ctermfg=black ctermbg=white + + +hi Comment guifg=#80a0ff ctermfg=darkred +hi Constant ctermfg=magenta guifg=#ffa0a0 cterm=none +hi Special ctermfg=brown guifg=Orange cterm=none gui=none +hi Identifier ctermfg=cyan guifg=#40ffff cterm=none +hi Statement ctermfg=yellow cterm=none guifg=#ffff60 gui=none +hi PreProc ctermfg=magenta guifg=#ff80ff gui=none cterm=none +hi type ctermfg=green guifg=#60ff60 gui=none cterm=none +hi Underlined cterm=underline term=underline +hi Ignore guifg=bg ctermfg=bg + +" suggested by tigmoid, 2008 Jul 18 +hi Pmenu guifg=#c0c0c0 guibg=#404080 +hi PmenuSel guifg=#c0c0c0 guibg=#2050d0 +hi PmenuSbar guifg=blue guibg=darkgray +hi PmenuThumb guifg=#c0c0c0 diff --git a/runtime_tos/colors/default.vim b/runtime_tos/colors/default.vim new file mode 100644 index 00000000000000..70311571dba098 --- /dev/null +++ b/runtime_tos/colors/default.vim @@ -0,0 +1,23 @@ +" Vim color file +" Maintainer: Bram Moolenaar +" Last Change: 2001 Jul 23 + +" This is the default color scheme. It doesn't define the Normal +" highlighting, it uses whatever the colors used to be. + +" Set 'background' back to the default. The value can't always be estimated +" and is then guessed. +hi clear Normal +set bg& + +" Remove all existing highlighting and set the defaults. +hi clear + +" Load the syntax highlighting defaults, if it's enabled. +if exists("syntax_on") + syntax reset +endif + +let colors_name = "default" + +" vim: sw=2 diff --git a/runtime_tos/colors/delek.vim b/runtime_tos/colors/delek.vim new file mode 100644 index 00000000000000..8c5f7f4fe3aab1 --- /dev/null +++ b/runtime_tos/colors/delek.vim @@ -0,0 +1,55 @@ +" Vim color file +" Maintainer: David Schweikert +" Last Change: 2014 Mar 19 + +hi clear + +let g:colors_name = "delek" + +" Normal should come first +hi Normal guifg=Black guibg=White +hi Cursor guifg=bg guibg=fg +hi lCursor guifg=NONE guibg=Cyan + +" Note: we never set 'term' because the defaults for B&W terminals are OK +hi DiffAdd ctermbg=LightBlue guibg=LightBlue +hi DiffChange ctermbg=LightMagenta guibg=LightMagenta +hi DiffDelete ctermfg=Blue ctermbg=LightCyan gui=bold guifg=Blue guibg=LightCyan +hi DiffText ctermbg=Red cterm=bold gui=bold guibg=Red +hi Directory ctermfg=DarkBlue guifg=Blue +hi ErrorMsg ctermfg=White ctermbg=DarkRed guibg=Red guifg=White +hi FoldColumn ctermfg=DarkBlue ctermbg=Grey guibg=Grey guifg=DarkBlue +hi Folded ctermbg=Grey ctermfg=DarkBlue guibg=LightGrey guifg=DarkBlue +hi IncSearch cterm=reverse gui=reverse +hi LineNr ctermfg=Brown guifg=Brown +hi ModeMsg cterm=bold gui=bold +hi MoreMsg ctermfg=DarkGreen gui=bold guifg=SeaGreen +hi NonText ctermfg=Blue gui=bold guifg=gray guibg=white +hi Pmenu guibg=LightBlue +hi PmenuSel ctermfg=White ctermbg=DarkBlue guifg=White guibg=DarkBlue +hi Question ctermfg=DarkGreen gui=bold guifg=SeaGreen +if &background == "light" + hi Search ctermfg=NONE ctermbg=Yellow guibg=Yellow guifg=NONE +else + hi Search ctermfg=Black ctermbg=Yellow guibg=Yellow guifg=Black +endif +hi SpecialKey ctermfg=DarkBlue guifg=Blue +hi StatusLine cterm=bold ctermbg=blue ctermfg=yellow guibg=gold guifg=blue +hi StatusLineNC cterm=bold ctermbg=blue ctermfg=black guibg=gold guifg=blue +hi Title ctermfg=DarkMagenta gui=bold guifg=Magenta +hi VertSplit cterm=reverse gui=reverse +hi Visual ctermbg=NONE cterm=reverse gui=reverse guifg=Grey guibg=fg +hi VisualNOS cterm=underline,bold gui=underline,bold +hi WarningMsg ctermfg=DarkRed guifg=Red +hi WildMenu ctermfg=Black ctermbg=Yellow guibg=Yellow guifg=Black + +" syntax highlighting +hi Comment cterm=NONE ctermfg=DarkRed gui=NONE guifg=red2 +hi Constant cterm=NONE ctermfg=DarkGreen gui=NONE guifg=green3 +hi Identifier cterm=NONE ctermfg=DarkCyan gui=NONE guifg=cyan4 +hi PreProc cterm=NONE ctermfg=DarkMagenta gui=NONE guifg=magenta3 +hi Special cterm=NONE ctermfg=LightRed gui=NONE guifg=deeppink +hi Statement cterm=bold ctermfg=Blue gui=bold guifg=blue +hi Type cterm=NONE ctermfg=Blue gui=bold guifg=blue + +" vim: sw=2 diff --git a/runtime_tos/colors/desert.vim b/runtime_tos/colors/desert.vim new file mode 100644 index 00000000000000..7166220f2626d9 --- /dev/null +++ b/runtime_tos/colors/desert.vim @@ -0,0 +1,108 @@ +" Vim color file +" Maintainer: Hans Fugal +" Last Change: $Date: 2004/06/13 19:30:30 $ +" Last Change: $Date: 2004/06/13 19:30:30 $ +" URL: http://hans.fugal.net/vim/colors/desert.vim +" Version: $Id: desert.vim,v 1.1 2004/06/13 19:30:30 vimboss Exp $ + +" cool help screens +" :he group-name +" :he highlight-groups +" :he cterm-colors + +set background=dark +if version > 580 + " no guarantees for version 5.8 and below, but this makes it stop + " complaining + hi clear + if exists("syntax_on") + syntax reset + endif +endif +let g:colors_name="desert" + +hi Normal guifg=White guibg=grey20 + +" highlight groups +hi Cursor guibg=khaki guifg=slategrey +"hi CursorIM +"hi Directory +"hi DiffAdd +"hi DiffChange +"hi DiffDelete +"hi DiffText +"hi ErrorMsg +hi VertSplit guibg=#c2bfa5 guifg=grey50 gui=none +hi Folded guibg=grey30 guifg=gold +hi FoldColumn guibg=grey30 guifg=tan +hi IncSearch guifg=slategrey guibg=khaki +"hi LineNr +hi ModeMsg guifg=goldenrod +hi MoreMsg guifg=SeaGreen +hi NonText guifg=LightBlue guibg=grey30 +hi Question guifg=springgreen +hi Search guibg=peru guifg=wheat +hi SpecialKey guifg=yellowgreen +hi StatusLine guibg=#c2bfa5 guifg=black gui=none +hi StatusLineNC guibg=#c2bfa5 guifg=grey50 gui=none +hi Title guifg=indianred +hi Visual gui=none guifg=khaki guibg=olivedrab +"hi VisualNOS +hi WarningMsg guifg=salmon +"hi WildMenu +"hi Menu +"hi Scrollbar +"hi Tooltip + +" syntax highlighting groups +hi Comment guifg=SkyBlue +hi Constant guifg=#ffa0a0 +hi Identifier guifg=palegreen +hi Statement guifg=khaki +hi PreProc guifg=indianred +hi Type guifg=darkkhaki +hi Special guifg=navajowhite +"hi Underlined +hi Ignore guifg=grey40 +"hi Error +hi Todo guifg=orangered guibg=yellow2 + +" color terminal definitions +hi SpecialKey ctermfg=darkgreen +hi NonText cterm=bold ctermfg=darkblue +hi Directory ctermfg=darkcyan +hi ErrorMsg cterm=bold ctermfg=7 ctermbg=1 +hi IncSearch cterm=NONE ctermfg=yellow ctermbg=green +hi Search cterm=NONE ctermfg=grey ctermbg=blue +hi MoreMsg ctermfg=darkgreen +hi ModeMsg cterm=NONE ctermfg=brown +hi LineNr ctermfg=3 +hi Question ctermfg=green +hi StatusLine cterm=bold,reverse +hi StatusLineNC cterm=reverse +hi VertSplit cterm=reverse +hi Title ctermfg=5 +hi Visual cterm=reverse +hi VisualNOS cterm=bold,underline +hi WarningMsg ctermfg=1 +hi WildMenu ctermfg=0 ctermbg=3 +hi Folded ctermfg=darkgrey ctermbg=NONE +hi FoldColumn ctermfg=darkgrey ctermbg=NONE +hi DiffAdd ctermbg=4 +hi DiffChange ctermbg=5 +hi DiffDelete cterm=bold ctermfg=4 ctermbg=6 +hi DiffText cterm=bold ctermbg=1 +hi Comment ctermfg=darkcyan +hi Constant ctermfg=brown +hi Special ctermfg=5 +hi Identifier ctermfg=6 +hi Statement ctermfg=3 +hi PreProc ctermfg=5 +hi Type ctermfg=2 +hi Underlined cterm=underline ctermfg=5 +hi Ignore cterm=bold ctermfg=7 +hi Ignore ctermfg=darkgrey +hi Error cterm=bold ctermfg=7 ctermbg=1 + + +"vim: sw=4 diff --git a/runtime_tos/colors/elflord.vim b/runtime_tos/colors/elflord.vim new file mode 100644 index 00000000000000..f74a828947f75f --- /dev/null +++ b/runtime_tos/colors/elflord.vim @@ -0,0 +1,50 @@ +" local syntax file - set colors on a per-machine basis: +" vim: tw=0 ts=4 sw=4 +" Vim color file +" Maintainer: Ron Aaron +" Last Change: 2003 May 02 + +set background=dark +hi clear +if exists("syntax_on") + syntax reset +endif +let g:colors_name = "elflord" +hi Normal guifg=cyan guibg=black +hi Comment term=bold ctermfg=DarkCyan guifg=#80a0ff +hi Constant term=underline ctermfg=Magenta guifg=Magenta +hi Special term=bold ctermfg=DarkMagenta guifg=Red +hi Identifier term=underline cterm=bold ctermfg=Cyan guifg=#40ffff +hi Statement term=bold ctermfg=Yellow gui=bold guifg=#aa4444 +hi PreProc term=underline ctermfg=LightBlue guifg=#ff80ff +hi Type term=underline ctermfg=LightGreen guifg=#60ff60 gui=bold +hi Function term=bold ctermfg=White guifg=White +hi Repeat term=underline ctermfg=White guifg=white +hi Operator ctermfg=Red guifg=Red +hi Ignore ctermfg=black guifg=bg +hi Error term=reverse ctermbg=Red ctermfg=White guibg=Red guifg=White +hi Todo term=standout ctermbg=Yellow ctermfg=Black guifg=Blue guibg=Yellow + +" Common groups that link to default highlighting. +" You can specify other highlighting easily. +hi link String Constant +hi link Character Constant +hi link Number Constant +hi link Boolean Constant +hi link Float Number +hi link Conditional Repeat +hi link Label Statement +hi link Keyword Statement +hi link Exception Statement +hi link Include PreProc +hi link Define PreProc +hi link Macro PreProc +hi link PreCondit PreProc +hi link StorageClass Type +hi link Structure Type +hi link Typedef Type +hi link Tag Special +hi link SpecialChar Special +hi link Delimiter Special +hi link SpecialComment Special +hi link Debug Special diff --git a/runtime_tos/colors/evening.vim b/runtime_tos/colors/evening.vim new file mode 100644 index 00000000000000..298fd2481163b7 --- /dev/null +++ b/runtime_tos/colors/evening.vim @@ -0,0 +1,56 @@ +" Vim color file +" Maintainer: Bram Moolenaar +" Last Change: 2006 Apr 14 + +" This color scheme uses a dark grey background. + +" First remove all existing highlighting. +set background=dark +hi clear +if exists("syntax_on") + syntax reset +endif + +let colors_name = "evening" + +hi Normal ctermbg=DarkGrey ctermfg=White guifg=White guibg=grey20 + +" Groups used in the 'highlight' and 'guicursor' options default value. +hi ErrorMsg term=standout ctermbg=DarkRed ctermfg=White guibg=Red guifg=White +hi IncSearch term=reverse cterm=reverse gui=reverse +hi ModeMsg term=bold cterm=bold gui=bold +hi StatusLine term=reverse,bold cterm=reverse,bold gui=reverse,bold +hi StatusLineNC term=reverse cterm=reverse gui=reverse +hi VertSplit term=reverse cterm=reverse gui=reverse +hi Visual term=reverse ctermbg=black guibg=grey60 +hi VisualNOS term=underline,bold cterm=underline,bold gui=underline,bold +hi DiffText term=reverse cterm=bold ctermbg=Red gui=bold guibg=Red +hi Cursor guibg=Green guifg=Black +hi lCursor guibg=Cyan guifg=Black +hi Directory term=bold ctermfg=LightCyan guifg=Cyan +hi LineNr term=underline ctermfg=Yellow guifg=Yellow +hi MoreMsg term=bold ctermfg=LightGreen gui=bold guifg=SeaGreen +hi NonText term=bold ctermfg=LightBlue gui=bold guifg=LightBlue guibg=grey30 +hi Question term=standout ctermfg=LightGreen gui=bold guifg=Green +hi Search term=reverse ctermbg=Yellow ctermfg=Black guibg=Yellow guifg=Black +hi SpecialKey term=bold ctermfg=LightBlue guifg=Cyan +hi Title term=bold ctermfg=LightMagenta gui=bold guifg=Magenta +hi WarningMsg term=standout ctermfg=LightRed guifg=Red +hi WildMenu term=standout ctermbg=Yellow ctermfg=Black guibg=Yellow guifg=Black +hi Folded term=standout ctermbg=LightGrey ctermfg=DarkBlue guibg=LightGrey guifg=DarkBlue +hi FoldColumn term=standout ctermbg=LightGrey ctermfg=DarkBlue guibg=Grey guifg=DarkBlue +hi DiffAdd term=bold ctermbg=DarkBlue guibg=DarkBlue +hi DiffChange term=bold ctermbg=DarkMagenta guibg=DarkMagenta +hi DiffDelete term=bold ctermfg=Blue ctermbg=DarkCyan gui=bold guifg=Blue guibg=DarkCyan +hi CursorColumn term=reverse ctermbg=Black guibg=grey40 +hi CursorLine term=underline cterm=underline guibg=grey40 + +" Groups for syntax highlighting +hi Constant term=underline ctermfg=Magenta guifg=#ffa0a0 guibg=grey5 +hi Special term=bold ctermfg=LightRed guifg=Orange guibg=grey5 +if &t_Co > 8 + hi Statement term=bold cterm=bold ctermfg=Yellow guifg=#ffff60 gui=bold +endif +hi Ignore ctermfg=DarkGrey guifg=grey20 + +" vim: sw=2 diff --git a/runtime_tos/colors/industry.vim b/runtime_tos/colors/industry.vim new file mode 100644 index 00000000000000..ac9103b5c5d285 --- /dev/null +++ b/runtime_tos/colors/industry.vim @@ -0,0 +1,40 @@ +" Vim color file +" Maintainer: Shian Lee +" Last Change: 2014 Mar 6 (for vim 7.4) +" Remark: "industry" stands for 'industrial' color scheme. In industrial +" HMI (Human-Machine-Interface) programming, using a standard color +" scheme is mandatory in many cases (in traffic-lights for example): +" LIGHT_RED is 'Warning' +" LIGHT_YELLOW is 'Attention' +" LIGHT_GREEN is 'Normal' +" LIGHT_MAGENTA is 'Warning-Attention' (light RED-YELLOW) +" LIGHT_CYAN is 'Attention-Normal' (light YELLOW-GREEN). +" BLACK is Dark-High-Contrast Background for maximum safety. +" BLUE is Shade of BLACK (not supposed to get attention). +" +" Industrial color scheme is by nature clear, safe and productive. +" Yet, depends on the file type's syntax, it might appear incorrect. + +" Reset to dark background, then reset everything to defaults: +set background=dark +highlight clear +if exists("syntax_on") + syntax reset +endif + +let colors_name = "industry" + +" First set Normal to regular white on black text colors: +hi Normal ctermfg=LightGray ctermbg=Black guifg=#dddddd guibg=Black + +" Syntax highlighting (other color-groups using default, see :help group-name): +hi Comment cterm=NONE ctermfg=DarkCyan gui=NONE guifg=#00aaaa +hi Constant cterm=NONE ctermfg=LightCyan gui=NONE guifg=#00ffff +hi Identifier cterm=NONE ctermfg=LightMagenta gui=NONE guifg=#ff00ff +hi Function cterm=NONE ctermfg=LightGreen gui=NONE guifg=#00ff00 +hi Statement cterm=NONE ctermfg=White gui=bold guifg=#ffffff +hi PreProc cterm=NONE ctermfg=Yellow gui=NONE guifg=#ffff00 +hi Type cterm=NONE ctermfg=LightGreen gui=bold guifg=#00ff00 +hi Special cterm=NONE ctermfg=LightRed gui=NONE guifg=#ff0000 +hi Delimiter cterm=NONE ctermfg=Yellow gui=NONE guifg=#ffff00 + diff --git a/runtime_tos/colors/koehler.vim b/runtime_tos/colors/koehler.vim new file mode 100644 index 00000000000000..a36f9f6972c95f --- /dev/null +++ b/runtime_tos/colors/koehler.vim @@ -0,0 +1,72 @@ +" local syntax file - set colors on a per-machine basis: +" vim: tw=0 ts=4 sw=4 +" Vim color file +" Maintainer: Ron Aaron +" Last Change: 2013 May 23 + +hi clear +set background=dark +if exists("syntax_on") + syntax reset +endif +let g:colors_name = "koehler" +hi Normal guifg=white guibg=black +hi Scrollbar guifg=darkcyan guibg=cyan +hi Menu guifg=black guibg=cyan +hi SpecialKey term=bold cterm=bold ctermfg=darkred guifg=#cc0000 +hi NonText term=bold cterm=bold ctermfg=darkred gui=bold guifg=#cc0000 +hi Directory term=bold cterm=bold ctermfg=brown guifg=#cc8000 +hi ErrorMsg term=standout cterm=bold ctermfg=grey ctermbg=red guifg=White guibg=Red +hi Search term=reverse ctermfg=white ctermbg=red guifg=white guibg=Red +hi MoreMsg term=bold cterm=bold ctermfg=darkgreen gui=bold guifg=SeaGreen +hi ModeMsg term=bold cterm=bold gui=bold guifg=White guibg=Blue +hi LineNr term=underline cterm=bold ctermfg=darkcyan guifg=Yellow +hi Question term=standout cterm=bold ctermfg=darkgreen gui=bold guifg=Green +hi StatusLine term=bold,reverse cterm=bold ctermfg=lightblue ctermbg=white gui=bold guifg=blue guibg=white +hi StatusLineNC term=reverse ctermfg=white ctermbg=lightblue guifg=white guibg=blue +hi Title term=bold cterm=bold ctermfg=darkmagenta gui=bold guifg=Magenta +hi Visual term=reverse cterm=reverse gui=reverse +hi WarningMsg term=standout cterm=bold ctermfg=darkred guifg=Red +hi Cursor guifg=bg guibg=Green +hi Comment term=bold cterm=bold ctermfg=cyan guifg=#80a0ff +hi Constant term=underline cterm=bold ctermfg=magenta guifg=#ffa0a0 +hi Special term=bold cterm=bold ctermfg=red guifg=Orange +hi Identifier term=underline ctermfg=brown guifg=#40ffff +hi Statement term=bold cterm=bold ctermfg=yellow gui=bold guifg=#ffff60 +hi PreProc term=underline ctermfg=darkmagenta guifg=#ff80ff +hi Type term=underline cterm=bold ctermfg=lightgreen gui=bold guifg=#60ff60 +hi Error term=reverse ctermfg=darkcyan ctermbg=black guifg=Red guibg=Black +hi Todo term=standout ctermfg=black ctermbg=darkcyan guifg=Blue guibg=Yellow +hi CursorLine term=underline guibg=#555555 cterm=underline +hi CursorColumn term=underline guibg=#555555 cterm=underline +hi MatchParen term=reverse ctermfg=blue guibg=Blue +hi TabLine term=bold,reverse cterm=bold ctermfg=lightblue ctermbg=white gui=bold guifg=blue guibg=white +hi TabLineFill term=bold,reverse cterm=bold ctermfg=lightblue ctermbg=white gui=bold guifg=blue guibg=white +hi TabLineSel term=reverse ctermfg=white ctermbg=lightblue guifg=white guibg=blue +hi Underlined term=underline cterm=bold,underline ctermfg=lightblue guifg=lightblue gui=bold,underline +hi Ignore ctermfg=black ctermbg=black guifg=black guibg=black +hi link IncSearch Visual +hi link String Constant +hi link Character Constant +hi link Number Constant +hi link Boolean Constant +hi link Float Number +hi link Function Identifier +hi link Conditional Statement +hi link Repeat Statement +hi link Label Statement +hi link Operator Statement +hi link Keyword Statement +hi link Exception Statement +hi link Include PreProc +hi link Define PreProc +hi link Macro PreProc +hi link PreCondit PreProc +hi link StorageClass Type +hi link Structure Type +hi link Typedef Type +hi link Tag Special +hi link SpecialChar Special +hi link Delimiter Special +hi link SpecialComment Special +hi link Debug Special diff --git a/runtime_tos/colors/morning.vim b/runtime_tos/colors/morning.vim new file mode 100644 index 00000000000000..f1ab841416207d --- /dev/null +++ b/runtime_tos/colors/morning.vim @@ -0,0 +1,56 @@ +" Vim color file +" Maintainer: Bram Moolenaar +" Last Change: 2006 Apr 15 + +" This color scheme uses a light grey background. + +" First remove all existing highlighting. +set background=light +hi clear +if exists("syntax_on") + syntax reset +endif + +let colors_name = "morning" + +hi Normal ctermfg=Black ctermbg=LightGrey guifg=Black guibg=grey90 + +" Groups used in the 'highlight' and 'guicursor' options default value. +hi ErrorMsg term=standout ctermbg=DarkRed ctermfg=White guibg=Red guifg=White +hi IncSearch term=reverse cterm=reverse gui=reverse +hi ModeMsg term=bold cterm=bold gui=bold +hi StatusLine term=reverse,bold cterm=reverse,bold gui=reverse,bold +hi StatusLineNC term=reverse cterm=reverse gui=reverse +hi VertSplit term=reverse cterm=reverse gui=reverse +hi Visual term=reverse ctermbg=grey guibg=grey80 +hi VisualNOS term=underline,bold cterm=underline,bold gui=underline,bold +hi DiffText term=reverse cterm=bold ctermbg=Red gui=bold guibg=Red +hi Cursor guibg=Green guifg=NONE +hi lCursor guibg=Cyan guifg=NONE +hi Directory term=bold ctermfg=DarkBlue guifg=Blue +hi LineNr term=underline ctermfg=Brown guifg=Brown +hi MoreMsg term=bold ctermfg=DarkGreen gui=bold guifg=SeaGreen +hi NonText term=bold ctermfg=Blue gui=bold guifg=Blue guibg=grey80 +hi Question term=standout ctermfg=DarkGreen gui=bold guifg=SeaGreen +hi Search term=reverse ctermbg=Yellow ctermfg=NONE guibg=Yellow guifg=NONE +hi SpecialKey term=bold ctermfg=DarkBlue guifg=Blue +hi Title term=bold ctermfg=DarkMagenta gui=bold guifg=Magenta +hi WarningMsg term=standout ctermfg=DarkRed guifg=Red +hi WildMenu term=standout ctermbg=Yellow ctermfg=Black guibg=Yellow guifg=Black +hi Folded term=standout ctermbg=Grey ctermfg=DarkBlue guibg=LightGrey guifg=DarkBlue +hi FoldColumn term=standout ctermbg=Grey ctermfg=DarkBlue guibg=Grey guifg=DarkBlue +hi DiffAdd term=bold ctermbg=LightBlue guibg=LightBlue +hi DiffChange term=bold ctermbg=LightMagenta guibg=LightMagenta +hi DiffDelete term=bold ctermfg=Blue ctermbg=LightCyan gui=bold guifg=Blue guibg=LightCyan +hi CursorLine term=underline cterm=underline guibg=grey80 +hi CursorColumn term=reverse ctermbg=grey guibg=grey80 + +" Colors for syntax highlighting +hi Constant term=underline ctermfg=DarkRed guifg=Magenta guibg=grey95 +hi Special term=bold ctermfg=DarkMagenta guifg=SlateBlue guibg=grey95 +if &t_Co > 8 + hi Statement term=bold cterm=bold ctermfg=Brown gui=bold guifg=Brown +endif +hi Ignore ctermfg=LightGrey guifg=grey90 + +" vim: sw=2 diff --git a/runtime_tos/colors/murphy.vim b/runtime_tos/colors/murphy.vim new file mode 100644 index 00000000000000..1f439964efeeed --- /dev/null +++ b/runtime_tos/colors/murphy.vim @@ -0,0 +1,41 @@ +" local syntax file - set colors on a per-machine basis: +" vim: tw=0 ts=4 sw=4 +" Vim color file +" Maintainer: Ron Aaron +" Last Change: 2003 May 02 + +hi clear +set background=dark +if exists("syntax_on") + syntax reset +endif +let g:colors_name = "murphy" + +hi Normal ctermbg=Black ctermfg=lightgreen guibg=Black guifg=lightgreen +hi Comment term=bold ctermfg=LightRed guifg=Orange +hi Constant term=underline ctermfg=LightGreen guifg=White gui=NONE +hi Identifier term=underline ctermfg=LightCyan guifg=#00ffff +hi Ignore ctermfg=black guifg=bg +hi PreProc term=underline ctermfg=LightBlue guifg=Wheat +hi Search term=reverse guifg=white guibg=Blue +hi Special term=bold ctermfg=LightRed guifg=magenta +hi Statement term=bold ctermfg=Yellow guifg=#ffff00 gui=NONE +hi Type ctermfg=LightGreen guifg=grey gui=none +hi Error term=reverse ctermbg=Red ctermfg=White guibg=Red guifg=White +hi Todo term=standout ctermbg=Yellow ctermfg=Black guifg=Blue guibg=Yellow +" From the source: +hi Cursor guifg=Orchid guibg=fg +hi Directory term=bold ctermfg=LightCyan guifg=Cyan +hi ErrorMsg term=standout ctermbg=DarkRed ctermfg=White guibg=Red guifg=White +hi IncSearch term=reverse cterm=reverse gui=reverse +hi LineNr term=underline ctermfg=Yellow guifg=Yellow +hi ModeMsg term=bold cterm=bold gui=bold +hi MoreMsg term=bold ctermfg=LightGreen gui=bold guifg=SeaGreen +hi NonText term=bold ctermfg=Blue gui=bold guifg=Blue +hi Question term=standout ctermfg=LightGreen gui=bold guifg=Cyan +hi SpecialKey term=bold ctermfg=LightBlue guifg=Cyan +hi StatusLine term=reverse,bold cterm=reverse gui=NONE guifg=White guibg=darkblue +hi StatusLineNC term=reverse cterm=reverse gui=NONE guifg=white guibg=#333333 +hi Title term=bold ctermfg=LightMagenta gui=bold guifg=Pink +hi WarningMsg term=standout ctermfg=LightRed guifg=Red +hi Visual term=reverse cterm=reverse gui=NONE guifg=white guibg=darkgreen diff --git a/runtime_tos/colors/pablo.vim b/runtime_tos/colors/pablo.vim new file mode 100644 index 00000000000000..e6bf7370461a45 --- /dev/null +++ b/runtime_tos/colors/pablo.vim @@ -0,0 +1,26 @@ +" local syntax file - set colors on a per-machine basis: +" vim: tw=0 ts=4 sw=4 +" Vim color file +" Maintainer: Ron Aaron +" Last Change: 2003 May 02 + +hi clear +set background=dark +if exists("syntax_on") + syntax reset +endif +let g:colors_name = "pablo" + +highlight Comment ctermfg=8 guifg=#808080 +highlight Constant ctermfg=14 cterm=none guifg=#00ffff gui=none +highlight Identifier ctermfg=6 guifg=#00c0c0 +highlight Statement ctermfg=3 cterm=bold guifg=#c0c000 gui=bold +highlight PreProc ctermfg=10 guifg=#00ff00 +highlight Type ctermfg=2 guifg=#00c000 +highlight Special ctermfg=12 guifg=#0000ff +highlight Error ctermbg=9 guibg=#ff0000 +highlight Todo ctermfg=4 ctermbg=3 guifg=#000080 guibg=#c0c000 +highlight Directory ctermfg=2 guifg=#00c000 +highlight StatusLine ctermfg=11 ctermbg=12 cterm=none guifg=#ffff00 guibg=#0000ff gui=none +highlight Normal guifg=#ffffff guibg=#000000 +highlight Search ctermbg=3 guibg=#c0c000 diff --git a/runtime_tos/colors/peachpuff.vim b/runtime_tos/colors/peachpuff.vim new file mode 100644 index 00000000000000..3c15305b0099c0 --- /dev/null +++ b/runtime_tos/colors/peachpuff.vim @@ -0,0 +1,60 @@ +" Vim color file +" Maintainer: David Ne\v{c}as (Yeti) +" Last Change: 2003-04-23 +" URL: http://trific.ath.cx/Ftp/vim/colors/peachpuff.vim + +" This color scheme uses a peachpuff background (what you've expected when it's +" called peachpuff?). +" +" Note: Only GUI colors differ from default, on terminal it's just `light'. + +" First remove all existing highlighting. +set background=light +hi clear +if exists("syntax_on") + syntax reset +endif + +let colors_name = "peachpuff" + +hi Normal guibg=PeachPuff guifg=Black + +hi SpecialKey term=bold ctermfg=4 guifg=Blue +hi NonText term=bold cterm=bold ctermfg=4 gui=bold guifg=Blue +hi Directory term=bold ctermfg=4 guifg=Blue +hi ErrorMsg term=standout cterm=bold ctermfg=7 ctermbg=1 gui=bold guifg=White guibg=Red +hi IncSearch term=reverse cterm=reverse gui=reverse +hi Search term=reverse ctermbg=3 guibg=Gold2 +hi MoreMsg term=bold ctermfg=2 gui=bold guifg=SeaGreen +hi ModeMsg term=bold cterm=bold gui=bold +hi LineNr term=underline ctermfg=3 guifg=Red3 +hi Question term=standout ctermfg=2 gui=bold guifg=SeaGreen +hi StatusLine term=bold,reverse cterm=bold,reverse gui=bold guifg=White guibg=Black +hi StatusLineNC term=reverse cterm=reverse gui=bold guifg=PeachPuff guibg=Gray45 +hi VertSplit term=reverse cterm=reverse gui=bold guifg=White guibg=Gray45 +hi Title term=bold ctermfg=5 gui=bold guifg=DeepPink3 +hi Visual term=reverse cterm=reverse gui=reverse guifg=Grey80 guibg=fg +hi VisualNOS term=bold,underline cterm=bold,underline gui=bold,underline +hi WarningMsg term=standout ctermfg=1 gui=bold guifg=Red +hi WildMenu term=standout ctermfg=0 ctermbg=3 guifg=Black guibg=Yellow +hi Folded term=standout ctermfg=4 ctermbg=7 guifg=Black guibg=#e3c1a5 +hi FoldColumn term=standout ctermfg=4 ctermbg=7 guifg=DarkBlue guibg=Gray80 +hi DiffAdd term=bold ctermbg=4 guibg=White +hi DiffChange term=bold ctermbg=5 guibg=#edb5cd +hi DiffDelete term=bold cterm=bold ctermfg=4 ctermbg=6 gui=bold guifg=LightBlue guibg=#f6e8d0 +hi DiffText term=reverse cterm=bold ctermbg=1 gui=bold guibg=#ff8060 +hi Cursor guifg=bg guibg=fg +hi lCursor guifg=bg guibg=fg + +" Colors for syntax highlighting +hi Comment term=bold ctermfg=4 guifg=#406090 +hi Constant term=underline ctermfg=1 guifg=#c00058 +hi Special term=bold ctermfg=5 guifg=SlateBlue +hi Identifier term=underline ctermfg=6 guifg=DarkCyan +hi Statement term=bold ctermfg=3 gui=bold guifg=Brown +hi PreProc term=underline ctermfg=5 guifg=Magenta3 +hi Type term=underline ctermfg=2 gui=bold guifg=SeaGreen +hi Ignore cterm=bold ctermfg=7 guifg=bg +hi Error term=reverse cterm=bold ctermfg=7 ctermbg=1 gui=bold guifg=White guibg=Red +hi Todo term=standout ctermfg=0 ctermbg=3 guifg=Blue guibg=Yellow + diff --git a/runtime_tos/colors/ron.vim b/runtime_tos/colors/ron.vim new file mode 100644 index 00000000000000..1e9caa3150fa3b --- /dev/null +++ b/runtime_tos/colors/ron.vim @@ -0,0 +1,45 @@ +" local syntax file - set colors on a per-machine basis: +" vim: tw=0 ts=4 sw=4 +" Vim color file +" Maintainer: Ron Aaron +" Last Change: 2013 May 24 + +set background=dark +hi clear +if exists("syntax_on") + syntax reset +endif +let g:colors_name = "ron" +hi Normal guifg=cyan guibg=black +hi NonText guifg=yellow guibg=#303030 +hi comment guifg=green +hi constant guifg=cyan gui=bold +hi identifier guifg=cyan gui=NONE +hi statement guifg=lightblue gui=NONE +hi preproc guifg=Pink2 +hi type guifg=seagreen gui=bold +hi special guifg=yellow +hi ErrorMsg guifg=Black guibg=Red +hi WarningMsg guifg=Black guibg=Green +hi Error guibg=Red +hi Todo guifg=Black guibg=orange +hi Cursor guibg=#60a060 guifg=#00ff00 +hi Search guibg=darkgray guifg=black gui=bold +hi IncSearch gui=NONE guibg=steelblue +hi LineNr guifg=darkgrey +hi title guifg=darkgrey +hi ShowMarksHL ctermfg=cyan ctermbg=lightblue cterm=bold guifg=yellow guibg=black gui=bold +hi StatusLineNC gui=NONE guifg=lightblue guibg=darkblue +hi StatusLine gui=bold guifg=cyan guibg=blue +hi label guifg=gold2 +hi operator guifg=orange +hi clear Visual +hi Visual term=reverse cterm=reverse gui=reverse +hi DiffChange guibg=darkgreen +hi DiffText guibg=olivedrab +hi DiffAdd guibg=slateblue +hi DiffDelete guibg=coral +hi Folded guibg=gray30 +hi FoldColumn guibg=gray30 guifg=white +hi cIf0 guifg=gray +hi diffOnly guifg=red gui=bold diff --git a/runtime_tos/colors/shine.vim b/runtime_tos/colors/shine.vim new file mode 100644 index 00000000000000..afc72b30fb2ff8 --- /dev/null +++ b/runtime_tos/colors/shine.vim @@ -0,0 +1,60 @@ +" Vim color file +" Maintainer: Yasuhiro Matsumoto +" Last Change: 2001 May 25 + +" This look like normal text editor. +" This color scheme uses a light background. + +" First remove all existing highlighting. +set background=light +hi clear +if exists("syntax_on") + syntax reset +endif + +let colors_name = "shine" + +hi Normal ctermbg=White ctermfg=Black guifg=Black guibg=White + +" Groups used in the 'highlight' and 'guicursor' options default value. +hi ErrorMsg term=standout ctermbg=DarkRed ctermfg=White guibg=Red guifg=White +hi IncSearch term=reverse cterm=reverse gui=reverse +hi ModeMsg term=bold cterm=bold gui=bold +hi StatusLine term=reverse,bold cterm=reverse,bold gui=reverse,bold +hi StatusLineNC term=reverse cterm=reverse gui=reverse +hi VertSplit term=reverse cterm=reverse gui=reverse +hi Visual term=reverse cterm=reverse gui=reverse guifg=Grey guibg=fg +hi VisualNOS term=underline,bold cterm=underline,bold gui=underline,bold +hi DiffText term=reverse cterm=bold ctermbg=Red gui=bold guibg=Red +hi Cursor ctermbg=Green guibg=Green guifg=Black +hi lCursor guibg=Cyan guifg=Black +hi Directory term=bold ctermfg=LightRed guifg=Red +hi LineNr term=underline ctermfg=Yellow guifg=Yellow +hi MoreMsg term=bold ctermfg=LightGreen gui=bold guifg=SeaGreen +hi NonText term=bold ctermfg=LightBlue gui=bold guifg=LightBlue guibg=grey90 +hi Question term=standout ctermfg=LightGreen gui=bold guifg=Green +hi Search term=reverse ctermbg=Yellow ctermfg=Black guibg=Yellow guifg=Black +hi SpecialKey term=bold ctermfg=LightBlue guifg=Blue +hi Title term=bold ctermfg=LightMagenta gui=bold guifg=Magenta +hi WarningMsg term=standout ctermfg=LightRed guifg=Red +hi WildMenu term=standout ctermbg=Yellow ctermfg=Black guibg=Yellow guifg=Black +hi Folded term=standout ctermbg=LightGrey ctermfg=DarkBlue guibg=LightGrey guifg=DarkBlue +hi FoldColumn term=standout ctermbg=LightGrey ctermfg=DarkBlue guibg=Grey guifg=DarkBlue +hi DiffAdd term=bold ctermbg=DarkBlue guibg=DarkBlue +hi DiffChange term=bold ctermbg=DarkMagenta guibg=DarkMagenta +hi DiffDelete term=bold ctermfg=Blue ctermbg=DarkCyan gui=bold guifg=Blue guibg=DarkCyan + +hi Comment ctermfg=DarkGrey ctermbg=White guifg=DarkGrey gui=bold +hi SpecialChar ctermfg=DarkGrey ctermbg=White guifg=DarkGrey gui=bold +hi StorageClass ctermfg=Red ctermbg=White guifg=Red gui=bold +hi Number ctermfg=LightRed ctermbg=White guifg=LightRed gui=bold + +" Groups for syntax highlighting +hi Constant term=underline ctermfg=Magenta guifg=#a07070 guibg=grey80 +hi Special term=bold ctermfg=LightRed guifg=DarkOrange guibg=grey80 +if &t_Co > 8 + hi Statement term=bold cterm=bold ctermfg=DarkGreen ctermbg=White guifg=#ffff60 gui=bold +endif +hi Ignore ctermfg=LightGrey guifg=grey90 + +" vim: sw=2 diff --git a/runtime_tos/colors/slate.vim b/runtime_tos/colors/slate.vim new file mode 100644 index 00000000000000..f9a70b8777878c --- /dev/null +++ b/runtime_tos/colors/slate.vim @@ -0,0 +1,56 @@ +"%% SiSU Vim color file +" Slate Maintainer: Ralph Amissah +" (originally looked at desert Hans Fugal http://hans.fugal.net/vim/colors/desert.vim (2003/05/06) +:set background=dark +:highlight clear +if version > 580 + hi clear + if exists("syntax_on") + syntax reset + endif +endif +let colors_name = "slate" +:hi Normal guifg=White guibg=grey15 +:hi Cursor guibg=khaki guifg=slategrey +:hi VertSplit guibg=#c2bfa5 guifg=grey40 gui=none cterm=reverse +:hi Folded guibg=black guifg=grey40 ctermfg=grey ctermbg=darkgrey +:hi FoldColumn guibg=black guifg=grey20 ctermfg=4 ctermbg=7 +:hi IncSearch guifg=green guibg=black cterm=none ctermfg=yellow ctermbg=green +:hi ModeMsg guifg=goldenrod cterm=none ctermfg=brown +:hi MoreMsg guifg=SeaGreen ctermfg=darkgreen +:hi NonText guifg=RoyalBlue guibg=grey15 cterm=bold ctermfg=blue +:hi Question guifg=springgreen ctermfg=green +:hi Search guibg=peru guifg=wheat cterm=none ctermfg=grey ctermbg=blue +:hi SpecialKey guifg=yellowgreen ctermfg=darkgreen +:hi StatusLine guibg=#c2bfa5 guifg=black gui=none cterm=bold,reverse +:hi StatusLineNC guibg=#c2bfa5 guifg=grey40 gui=none cterm=reverse +:hi Title guifg=gold gui=bold cterm=bold ctermfg=yellow +:hi Statement guifg=CornflowerBlue ctermfg=lightblue +:hi Visual gui=none guifg=khaki guibg=olivedrab cterm=reverse +:hi WarningMsg guifg=salmon ctermfg=1 +:hi String guifg=SkyBlue ctermfg=darkcyan +:hi Comment term=bold ctermfg=11 guifg=grey40 +:hi Constant guifg=#ffa0a0 ctermfg=brown +:hi Special guifg=darkkhaki ctermfg=brown +:hi Identifier guifg=salmon ctermfg=red +:hi Include guifg=red ctermfg=red +:hi PreProc guifg=red guibg=white ctermfg=red +:hi Operator guifg=Red ctermfg=Red +:hi Define guifg=gold gui=bold ctermfg=yellow +:hi Type guifg=CornflowerBlue ctermfg=2 +:hi Function guifg=navajowhite ctermfg=brown +:hi Structure guifg=green ctermfg=green +:hi LineNr guifg=grey50 ctermfg=3 +:hi Ignore guifg=grey40 cterm=bold ctermfg=7 +:hi Todo guifg=orangered guibg=yellow2 +:hi Directory ctermfg=darkcyan +:hi ErrorMsg cterm=bold guifg=White guibg=Red cterm=bold ctermfg=7 ctermbg=1 +:hi VisualNOS cterm=bold,underline +:hi WildMenu ctermfg=0 ctermbg=3 +:hi DiffAdd ctermbg=4 +:hi DiffChange ctermbg=5 +:hi DiffDelete cterm=bold ctermfg=4 ctermbg=6 +:hi DiffText cterm=bold ctermbg=1 +:hi Underlined cterm=underline ctermfg=5 +:hi Error guifg=White guibg=Red cterm=bold ctermfg=7 ctermbg=1 +:hi SpellErrors guifg=White guibg=Red cterm=bold ctermfg=7 ctermbg=1 diff --git a/runtime_tos/colors/torte.vim b/runtime_tos/colors/torte.vim new file mode 100644 index 00000000000000..0e7a916a1c60ae --- /dev/null +++ b/runtime_tos/colors/torte.vim @@ -0,0 +1,50 @@ +" Vim color file +" Maintainer: Thorsten Maerz +" Last Change: 2006 Dec 07 +" grey on black +" optimized for TFT panels + +set background=dark +hi clear +if exists("syntax_on") + syntax reset +endif +"colorscheme default +let g:colors_name = "torte" + +" hardcoded colors : +" GUI Comment : #80a0ff = Light blue + +" GUI +highlight Normal guifg=Grey80 guibg=Black +highlight Search guifg=Black guibg=Red gui=bold +highlight Visual guifg=#404040 gui=bold +highlight Cursor guifg=Black guibg=Green gui=bold +highlight Special guifg=Orange +highlight Comment guifg=#80a0ff +highlight StatusLine guifg=blue guibg=white +highlight Statement guifg=Yellow gui=NONE +highlight Type gui=NONE + +" Console +highlight Normal ctermfg=LightGrey ctermbg=Black +highlight Search ctermfg=Black ctermbg=Red cterm=NONE +highlight Visual cterm=reverse +highlight Cursor ctermfg=Black ctermbg=Green cterm=bold +highlight Special ctermfg=Brown +highlight Comment ctermfg=Blue +highlight StatusLine ctermfg=blue ctermbg=white +highlight Statement ctermfg=Yellow cterm=NONE +highlight Type cterm=NONE + +" only for vim 5 +if has("unix") + if v:version<600 + highlight Normal ctermfg=Grey ctermbg=Black cterm=NONE guifg=Grey80 guibg=Black gui=NONE + highlight Search ctermfg=Black ctermbg=Red cterm=bold guifg=Black guibg=Red gui=bold + highlight Visual ctermfg=Black ctermbg=yellow cterm=bold guifg=#404040 gui=bold + highlight Special ctermfg=LightBlue cterm=NONE guifg=LightBlue gui=NONE + highlight Comment ctermfg=Cyan cterm=NONE guifg=LightBlue gui=NONE + endif +endif + diff --git a/runtime_tos/colors/zellner.vim b/runtime_tos/colors/zellner.vim new file mode 100644 index 00000000000000..ab875825c9934a --- /dev/null +++ b/runtime_tos/colors/zellner.vim @@ -0,0 +1,54 @@ +" local syntax file - set colors on a per-machine basis: +" vim: tw=0 ts=4 sw=4 +" Vim color file +" Maintainer: Ron Aaron +" Last Change: 2003 May 02 + +set background=light +hi clear +if exists("syntax_on") + syntax reset +endif +let g:colors_name = "zellner" + +hi Comment term=bold ctermfg=Red guifg=Red +hi Normal guifg=black guibg=white +hi Constant term=underline ctermfg=Magenta guifg=Magenta +hi Special term=bold ctermfg=Magenta guifg=Magenta +hi Identifier term=underline ctermfg=Blue guifg=Blue +hi Statement term=bold ctermfg=DarkRed gui=NONE guifg=Brown +hi PreProc term=underline ctermfg=Magenta guifg=Purple +hi Type term=underline ctermfg=Blue gui=NONE guifg=Blue +hi Visual term=reverse ctermfg=Yellow ctermbg=Red gui=NONE guifg=Black guibg=Yellow +hi Search term=reverse ctermfg=Black ctermbg=Cyan gui=NONE guifg=Black guibg=Cyan +hi Tag term=bold ctermfg=DarkGreen guifg=DarkGreen +hi Error term=reverse ctermfg=15 ctermbg=9 guibg=Red guifg=White +hi Todo term=standout ctermbg=Yellow ctermfg=Black guifg=Blue guibg=Yellow +hi StatusLine term=bold,reverse cterm=NONE ctermfg=Yellow ctermbg=DarkGray gui=NONE guifg=Yellow guibg=DarkGray +hi! link MoreMsg Comment +hi! link ErrorMsg Visual +hi! link WarningMsg ErrorMsg +hi! link Question Comment +hi link String Constant +hi link Character Constant +hi link Number Constant +hi link Boolean Constant +hi link Float Number +hi link Function Identifier +hi link Conditional Statement +hi link Repeat Statement +hi link Label Statement +hi link Operator Statement +hi link Keyword Statement +hi link Exception Statement +hi link Include PreProc +hi link Define PreProc +hi link Macro PreProc +hi link PreCondit PreProc +hi link StorageClass Type +hi link Structure Type +hi link Typedef Type +hi link SpecialChar Special +hi link Delimiter Special +hi link SpecialComment Special +hi link Debug Special diff --git a/runtime_tos/compiler/devpac.vim b/runtime_tos/compiler/devpac.vim new file mode 100644 index 00000000000000..92894341e85519 --- /dev/null +++ b/runtime_tos/compiler/devpac.vim @@ -0,0 +1,17 @@ +" Vim compiler file +" Compiler: Devpac3 assembler +" Maintainer: Simon Laszcz +" Latest Revision: 2024-05-03 + +if exists("current_compiler") + finish +endif +let current_compiler = "devpac" + +let s:cpo_save = &cpo +set cpo&vim + +CompilerSet errorformat=Error:\ %m\ at\ line\ %l\ in\ file\ %f,%-G%.%# + +let &cpo = s:cpo_save +unlet s:cpo_save diff --git a/runtime_tos/compiler/gcc.vim b/runtime_tos/compiler/gcc.vim new file mode 100644 index 00000000000000..aee31d92c2ee5b --- /dev/null +++ b/runtime_tos/compiler/gcc.vim @@ -0,0 +1,39 @@ +" Vim compiler file +" Compiler: GNU C Compiler +" Maintainer: Nikolai Weibull +" Latest Revision: 2010-10-14 + +if exists("current_compiler") + finish +endif +let current_compiler = "gcc" + +let s:cpo_save = &cpo +set cpo&vim + +CompilerSet errorformat= + \%*[^\"]\"%f\"%*\\D%l:%c:\ %m, + \%*[^\"]\"%f\"%*\\D%l:\ %m, + \\"%f\"%*\\D%l:%c:\ %m, + \\"%f\"%*\\D%l:\ %m, + \%-G%f:%l:\ %trror:\ (Each\ undeclared\ identifier\ is\ reported\ only\ once, + \%-G%f:%l:\ %trror:\ for\ each\ function\ it\ appears\ in.), + \%f:%l:%c:\ %trror:\ %m, + \%f:%l:%c:\ %tarning:\ %m, + \%f:%l:%c:\ %m, + \%f:%l:\ %trror:\ %m, + \%f:%l:\ %tarning:\ %m, + \%f:%l:\ %m, + \\"%f\"\\,\ line\ %l%*\\D%c%*[^\ ]\ %m, + \%D%*\\a[%*\\d]:\ Entering\ directory\ [`']%f', + \%X%*\\a[%*\\d]:\ Leaving\ directory\ [`']%f', + \%D%*\\a:\ Entering\ directory\ [`']%f', + \%X%*\\a:\ Leaving\ directory\ [`']%f', + \%DMaking\ %*\\a\ in\ %f + +if exists('g:compiler_gcc_ignore_unmatched_lines') + CompilerSet errorformat+=%-G%.%# +endif + +let &cpo = s:cpo_save +unlet s:cpo_save diff --git a/runtime_tos/doc/doctags.c b/runtime_tos/doc/doctags.c new file mode 100644 index 00000000000000..9213dd9c1e236e --- /dev/null +++ b/runtime_tos/doc/doctags.c @@ -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 +#include +#include +#include + +#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; +} diff --git a/runtime_tos/doc/help.txt b/runtime_tos/doc/help.txt new file mode 100644 index 00000000000000..bbf2148a1061d7 --- /dev/null +++ b/runtime_tos/doc/help.txt @@ -0,0 +1,100 @@ +*help.txt* For Vim version 7.4. Last change: 2012 Dec 06 + + 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". + Get out of Vim: Use ":qa!" (careful, all changes are lost!). + +Jump to a subject: Position the cursor on a tag (e.g. |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, e.g. |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. + It is possible to further specify the context: + *help-context* + WHAT PREPEND EXAMPLE ~ + Normal mode command (nothing) :help x + Visual mode command v_ :help v_u + Insert mode command i_ :help i_ + Command-line command : :help :quit + Command-line editing c_ :help c_ + Vim command argument - :help -r + Option ' :help 'textwidth' + Search for help: Type ":help word", then hit CTRL-D to see matching + help entries for "word". + Or use ":helpgrep word". |:helpgrep| + +For notes on this Atari TOS port, see |os_atari.txt|. + +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* +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 +|usr_32.txt| The undo tree + +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 + +General subjects ~ +|uganda.txt| Vim distribution conditions and what to do with your money + +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, or to go back to where you were. + +Note that tags are within | characters, but when highlighting is enabled these +characters are hidden. That makes it easier to read a command. + +Anyway, you can use CTRL-] on any word, also when it is not within |, and Vim +will try to find help for it. Especially for options in single quotes, e.g. +'compatible'. + +------------------------------------------------------------------------------ + vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=help:norl: diff --git a/runtime_tos/doc/os_atari.txt b/runtime_tos/doc/os_atari.txt new file mode 100644 index 00000000000000..f9ae5315b9a32b --- /dev/null +++ b/runtime_tos/doc/os_atari.txt @@ -0,0 +1,180 @@ +*os_atari.txt* For Vim version 7.4. Last change: 2024 May 07 + + Notes on the Atari TOS Port + +|TOS_01| Introduction +|TOS_02| Installation +|TOS_03| Using a Shell +|TOS_04| Setting the Palette +|TOS_05| Changing Resolution +|TOS_06| Changing the Keyboard Repeat Rate +|TOS_07| Development + +============================================================================== + +*TOS_01* Introduction *atari* + +The distribution contains tiny, small and normal feature builds. The +executables are named vimt.ttp, vims.ttp and vim.ttp respectively. + +vimt.ttp starts and quits much faster than vim.ttp and is also much smaller +(~450Kb vs. ~1Mb) but has far fewer features (e.g. splits, command windows and +eval are missing). + +More advanced features such as tags and syntax highlighting are very slow on +an 8MHz machine. tags performance might be improved by copying tag files to a +RAM disk and using the option 'set tags=path1;path2...'. Using an accelerator +will improve performance all round. + +============================================================================== + +*TOS_02* Installation + +Each build has its own rc file, namely: vimrct, vimrcs and vimrc. +vimrc includes vimrcs and vimrcs includes vimrct. + +Some features are missing from certain builds (e.g. tiny and small do not +support eval) and will give errors if used in the builds rc file. + +The distribution includes a cut down runtime. You may use the full Vim runtime +if you wish but having fewer files to glob improves performance. + +You should set the following environment variables in your shell: +VIM +VIMRUNTIME +HOME + +However, if not set the following defaults are used: +VIM=C:\VIM +VIMRUNTIME=C:\VIM\RT + +The following variables are available in the normal build (which supports the +'eval' feature): + +*v:resolution* The current resolution. + Either st-{low,med,hi}, tt-{low,med,hi} or a Falcon mode + such as 320x200, 384x240 etc +*v:machine* The current machine. + Either ST, STe, TT, Falcon or unknown +*v:os* The current OS. + Either TOS, MagiC, MiNT or Geneva + +They could be used to conditionally set options in vimrc. + +============================================================================== + +*TOS_03* Using a Shell *shell* *gulam* + +Any shell that sets the _shell_p vector can be used, e.g. Gulam. + +:lmake and :lopen can be used in vim.ttp. By default Vim attempts to execute the +make utility in the current working directory. If make is not installed, the +simplest way to get this to work is to create a shell script called 'make'. + +e.g. make.g might contain: + +gen.ttp $1 + +then to make the file being edited: + +:lmake % + +Ensure your PATH environment variable is set correctly first. + +The cut down runtime includes compiler files for gcc and devpac. These files +will format the error output from these programs for display by :lopen. + +For devpac you will need to set the default compiler first. Do this with the +command: + +:compiler devpac + +============================================================================== + +*TOS_04* Setting the Palette *palvim* *palmap* + +Vim colours are numbered thus: + +0 Black +1 DarkBlue +2 DarkGreen +3 DarkCyan +4 DarkRed +5 DarkMagenta +6 Brown +7 LightGray +8 DarkGray +9 Blue +10 Green +11 Cyan +12 Red +13 Magenta +14 Yellow +15 White + +:palvim (single TOS only) + +Changes the palette to the Vim colours above. A colour remapping occurs to +enure that the Vim background colour matches the border colour. When using a +resolution with fewer than 16 colours an additional colour remapping takes +place. This port supports a maxium of 16 colours even on the TT and Falcon. + +When Vim is quit, the startup palette is restored. + +The distribution includes many Vim colour schemes. Some target 256 colour +xterm displays so will not display perfectly. However the 'blue' scheme works +well accross all machines. + +Tab through all colour schemes with: + +:color + +For example, to set the blue scheme use: + +:palvim +:color blue + +:palmap {16 hex char string} + +You may map your existing palette to the Vim colour numbers by supplying a 16 +character hex string. + +e.g. + +:palmap abc0123456789def + +will map colour index 10 to Vim colour number 0 etc + +============================================================================== + +*TOS_05* Changing Resolution *rez* + +:rez will display the current resolution. +:rez name will set the named resolution +:rez will allow you to through all valid resolutions. + +When Vim is quit, the startup resolution is restored. + +The current resolution is stored in the variable |v:resolution|. + +============================================================================== + +*TOS_06* Changing the Keyboard Repeat Rate *Kbrate* + +:Kbrate Display the current setting +:Kbrate initial every Set keypresses to repeat after an initial + number of ticks and then every n 50/60Hz ticks. + +When Vim is quit, the startup repeat rate is restored. + +============================================================================== + +*TOS_07* Development *develop* + +Changes to the existing code are wrapped with the 'TOS' macro. + +All os_atari_* files and Make_tos.mak are specific to this port. + +============================================================================== + +vim:tw=78:ts=8:ft=help:norl:noexpandtab: diff --git a/runtime_tos/doc/uganda.txt b/runtime_tos/doc/uganda.txt new file mode 100644 index 00000000000000..113df4f64f4534 --- /dev/null +++ b/runtime_tos/doc/uganda.txt @@ -0,0 +1,288 @@ +*uganda.txt* For Vim version 7.4. Last change: 2013 Jul 06 + + + 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/ + http://www.iccf.nl/ + +You can also sponsor the development of Vim. Vim sponsors can vote for +features. See |sponsor|. The money goes to Uganda anyway. + +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 . 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 + + +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|. The money goes to Uganda anyway. + +- 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* *charity* + +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). + *donate* +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. +When I came back to Holland, I wanted 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 has been +co-sponsored and inspected by World Vision, Save the Children Fund and is now +under the supervision of Pacific Academy Outreach Society. The centre is +visited about once a year to check the progress (at our own cost). I have +visited the centre myself many times, starting in 1993. The visit reports are +on the ICCF web site. + +If you have any further questions, send me e-mail: . + +The address of the centre is: + Kibaale Children's Centre + p.o. box 1658 + Masaka, Uganda, East Africa + +Sending money: *iccf-donations* + +Check the ICCF web site for the latest information! See |iccf| for the URL. + + +USA: The methods mentioned below can be used. + Sending a check to the Nehemiah Group Outreach Society (NGOS) + is no longer possible, unfortunately. We are looking for + another way to get you an IRS tax receipt. + For sponsoring a child contact KCF in Canada (see below). US + checks can be sent to them to lower banking costs. + +Canada: Contact Kibaale Children's Fund (KCF) in Surrey, Canada. They + take care of the Canadian sponsors for the children in + Kibaale. KCF forwards 100% of the money to the project in + Uganda. You can send them a one time donation directly. + Please send me a note so that I 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. + +Holland: Transfer to the account of "Stichting ICCF Holland" in Lisse. + This will allow for tax deduction if you live in Holland. + Postbank, nr. 4548774 + IBAN: NL95 INGB 0004 5487 74 + +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/en_US/mrb/pal=XAC62PML3GF8Q + The e-mail address for sending the money to is: + Bram@iccf-holland.org + For amounts above 400 Euro ($500) sending a check is + preferred. + +Others: Transfer to one of these accounts if possible: + Postbank, account 4548774 + Swift code: INGB NL 2A + IBAN: NL95 INGB 0004 5487 74 + under the name "stichting ICCF Holland", Lisse + If that doesn't work: + Rabobank Lisse, account 3765.05.117 + Swift code: RABO NL 2U + under the name "Bram Moolenaar", Lisse + Otherwise, send a check in euro or US dollars to the address + below. Minimal amount: $70 (my bank does not accept smaller + amounts for foreign check, sorry) + +Address to send checks to: + Bram Moolenaar + Finsterruetihof 1 + 8134 Adliswil + Switzerland + +This address is expected to be valid for a long time. + + vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime_tos/doc/usr_01.txt b/runtime_tos/doc/usr_01.txt new file mode 100644 index 00000000000000..11fa2173d68e2f --- /dev/null +++ b/runtime_tos/doc/usr_01.txt @@ -0,0 +1,192 @@ +*usr_01.txt* For Vim version 7.4. Last change: 2010 Nov 03 + + 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|. The bars themselves may +be hidden or invisible, see below. 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|. + +The bars and stars are usually hidden with the |conceal| feature. They also +use |hl-Ignore|, using the same color for the text as the background. You can +make them visible with: > + :set conceallevel=0 + :hi link HelpBar Normal + :hi link HelpStar Normal + +============================================================================== +*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 a nice +setup is to 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, if Vim has been properly installed, you can start it from the shell: +> + vimtutor + +On MS-Windows you can find it in the Program/Vim menu. Or execute +vimtutor.bat in the $VIMRUNTIME directory. + +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 + +On Unix, if you prefer using the GUI version of Vim, use "gvimtutor" or +"vimtutor -g" instead of "vimtutor". + +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/openpub/ + +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 later, 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: diff --git a/runtime_tos/doc/usr_02.txt b/runtime_tos/doc/usr_02.txt new file mode 100644 index 00000000000000..8bfa9ba05d1609 --- /dev/null +++ b/runtime_tos/doc/usr_02.txt @@ -0,0 +1,564 @@ +*usr_02.txt* For Vim version 7.4. Last change: 2010 Jul 20 + + 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 key to start a new line. Finally +you press the 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 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 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 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 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 + +This begins an insert (the i), inserts the words "A young", and then exits +insert mode (the final ). 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. More about that in section |32.2|. + +============================================================================== +*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!!! + +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 + +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!!!". Another way to do this is to use the +command "3a!". 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 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 . If your keyboard has a +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_ + +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 + + +Summary: *help-summary* > + :help +< Gives you very general help. Scroll down to see a list of all + helpfiles, including those added locally (i.e. not distributed + with Vim). > + :help user-toc.txt +< Table of contents of the User Manual. > + :help :subject +< Ex-command "subject", for instance the following: > + :help :help +< Help on getting help. > + :help abc +< normal-mode command "abc". > + :help CTRL-B +< Control key in Normal mode. > + :help i_abc + :help i_CTRL-B +< The same in Insert mode. > + :help v_abc + :help v_CTRL-B +< The same in Visual mode. > + :help c_abc + :help c_CTRL-B +< The same in Command-line mode. > + :help 'subject' +< Option 'subject'. > + :help subject() +< Function "subject". > + :help -subject +< Command-line option "-subject". > + :help +subject +< Compile-time feature "+subject". > + :help EventName +< Autocommand event "EventName". > + :help digraphs.txt +< The top of the helpfile "digraph.txt". + Similarly for any other helpfile. > + :help pattern +< Find a help tag starting with "pattern". Repeat for + others. > + :help pattern +< See all possible help tag matches "pattern" at once. > + :helpgrep pattern +< Search the whole text of all help files for pattern "pattern". + Jumps to the first match. Jump to other matches with: > + :cn +< next match > + :cprev + :cN +< previous match > + :cfirst + :clast +< first or last match > + :copen + :cclose +< open/close the quickfix window; press to jump + to the item under the cursor + + +============================================================================== + +Next chapter: |usr_03.txt| Moving around + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime_tos/doc/usr_03.txt b/runtime_tos/doc/usr_03.txt new file mode 100644 index 00000000000000..6173260895f44b --- /dev/null +++ b/runtime_tos/doc/usr_03.txt @@ -0,0 +1,654 @@ +*usr_03.txt* For Vim version 7.4. Last change: 2006 Jun 21 + + 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 parenthesis +|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 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 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 . So "f" is an +aborted forward search and doesn't do anything. Note: cancels most +operations, not just searches. + +============================================================================== +*03.4* Matching a parenthesis + +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 ) to make corrections. Use +the and cursor keys when necessary. + Pressing executes the command. + + Note: + The characters .*[]^%/\?~$ have special meanings. 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 . If +you press (the cursor key), Vim puts "/three" on the command line. +Pressing at this point searches for three. If you do not press +, but press instead, Vim changes the prompt to "/two". Another +press of moves you to "/one". + You can also use the 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 . With the previous example, +you can type "/o" 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: > + + /\ + +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 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 + +"G" moves to the end of the file. "o" starts a new line, where you type the +":set" command. You end insert mode with . 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 . + +The ":jumps" command gives a list of positions you jumped to. The entry which +you used last is marked with a ">". + + +NAMED MARKS *bookmark* + +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 + +Then 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: diff --git a/runtime_tos/doc/usr_04.txt b/runtime_tos/doc/usr_04.txt new file mode 100644 index 00000000000000..c09cb204c5db1b --- /dev/null +++ b/runtime_tos/doc/usr_04.txt @@ -0,0 +1,514 @@ +*usr_04.txt* For Vim version 7.4. Last change: 2008 Sep 06 + + 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 + + To be human ~ + +This "c2wbe" contains these bits: + + c the change operator + 2w move two words (they are deleted and Insert mode started) + be insert this text + 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 + + 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". This deletes one +character and inserts a line break. Using a count here only applies to the +number of characters deleted: "4r" 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 tags. You position the cursor on the first < +and delete the with the command "df>". You then go to the < of the next + 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 generate a table of 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 find the first string "four" + cwfive 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 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 differently 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 you 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 . + In this example you start Replace mode on the first "t" of "text": + + This is text. ~ + Rinteresting. + + 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 key. + +When you use (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 work 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: diff --git a/runtime_tos/doc/usr_05.txt b/runtime_tos/doc/usr_05.txt new file mode 100644 index 00000000000000..f71cf42cff68df --- /dev/null +++ b/runtime_tos/doc/usr_05.txt @@ -0,0 +1,624 @@ +*usr_05.txt* For Vim version 7.4. Last change: 2012 Nov 20 + + 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 +Vim's 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 +Vim with all your favorite option settings and mappings, you write them in +what is called the vimrc file. Vim executes the commands in this file when it +starts up. + +If you already have a vimrc file (e.g., when your sysadmin has one setup for +you), you can edit it this way: > + + :edit $MYVIMRC + +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 and Macintosh this file is always used and is recommended: + + ~/.vimrc ~ + +For MS-DOS and MS-Windows you can use 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 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 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 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 _g y:exe "grep /" . escape(@", '\\/') . "/ *.c *.h" + +This mapping yanks the visually selected text and searches for it in C files. +This is a complicated mapping. 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. + + *restore-cursor* > + autocmd BufReadPost * + \ if line("'\"") > 1 && 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 i{ea} +< + Note: + When entering this command, you must enter by typing four + characters. Similarly, is not entered by pressing the + key, but by typing five characters. Watch out for this difference + when reading the manual! + +Let's break this down: + The F5 function key. This is the trigger key that causes the + command to be executed as the key is pressed. + + i{ Insert the { character. The key ends Insert mode. + + e Move to the end of the word. + + a} 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 parentheses around a word, and "\c" to add curly braces, +for example: > + + :map \p i(ea) + :map \c i{ea} + +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. There is a large collection on http://www.vim.org. +- They are sometimes posted in a Vim |maillist|. +- You could write one yourself, see |write-plugin|. + +Some plugins come as a vimball archive, see |vimball|. +Some plugins can be updated automatically, see |getscript|. + + +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. + +Instead of putting plugins directly into the plugin/ directory, you may +better organize them by putting them into subdirectories under plugin/. +As an example, consider using "~/.vim/plugin/perl/*.vim" for all your Perl +plugins. + + +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 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/.vim + ftplugin/_.vim + ftplugin//.vim + +Here "" 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 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 +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 + +The "cp" command is for Unix, on MS-DOS you can use "copy". + +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 + to jump there. Press 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 , 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 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 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 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 an 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 off +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 key, when used in the first position of a line, to move +the cursor to the end of the previous line. And the key moves from +the end of a line to the start of the next one. + +To allow the cursor keys and to also wrap, use this command: > + + :set whichwrap=b,s,<,> + +This is still only for Normal mode. To let and 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 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: diff --git a/runtime_tos/doc/usr_06.txt b/runtime_tos/doc/usr_06.txt new file mode 100644 index 00000000000000..5e3c7726d48d0d --- /dev/null +++ b/runtime_tos/doc/usr_06.txt @@ -0,0 +1,280 @@ +*usr_06.txt* For Vim version 7.4. Last change: 2009 Oct 28 + + 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 +this command: > + + :runtime syntax/colortest.vim + +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. + +Convert the current file to HTML with this command: > + + :TOhtml + +In case that doesn't work: > + + :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: diff --git a/runtime_tos/doc/usr_07.txt b/runtime_tos/doc/usr_07.txt new file mode 100644 index 00000000000000..8a0600b84d2f1c --- /dev/null +++ b/runtime_tos/doc/usr_07.txt @@ -0,0 +1,479 @@ +*usr_07.txt* For Vim version 7.4. Last change: 2006 Apr 24 + + 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: diff --git a/runtime_tos/doc/usr_08.txt b/runtime_tos/doc/usr_08.txt new file mode 100644 index 00000000000000..2ac6fea0024cda --- /dev/null +++ b/runtime_tos/doc/usr_08.txt @@ -0,0 +1,601 @@ +*usr_08.txt* For Vim version 7.4. Last change: 2006 Jul 18 + + 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 +|08.9| Tab pages + + 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 almost 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 width 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 + + +============================================================================== +*08.9* Tab pages + +You will have noticed that windows never overlap. That means you quickly run +out of screen space. The solution for this is called Tab pages. + +Assume you are editing "thisfile". To create a new tab page use this command: > + + :tabedit thatfile + +This will edit the file "thatfile" in a window that occupies the whole Vim +window. And you will notice a bar at the top with the two file names: + + +----------------------------------+ + | thisfile | /thatfile/ __________X| (thatfile is bold) + |/* thatfile */ | + |that | + |that | + |~ | + |~ | + |~ | + | | + +----------------------------------+ + +You now have two tab pages. The first one has a window for "thisfile" and the +second one a window for "thatfile". It's like two pages that are on top of +eachother, with a tab sticking out of each page showing the file name. + +Now use the mouse to click on "thisfile" in the top line. The result is + + +----------------------------------+ + | /thisfile/ | thatfile __________X| (thisfile is bold) + |/* thisfile */ | + |this | + |this | + |~ | + |~ | + |~ | + | | + +----------------------------------+ + +Thus you can switch between tab pages by clicking on the label in the top +line. If you don't have a mouse or don't want to use it, you can use the "gt" +command. Mnemonic: Goto Tab. + +Now let's create another tab page with the command: > + + :tab split + +This makes a new tab page with one window that is editing the same buffer as +the window we were in: + + +-------------------------------------+ + | thisfile | /thisfile/ | thatfile __X| (thisfile is bold) + |/* thisfile */ | + |this | + |this | + |~ | + |~ | + |~ | + | | + +-------------------------------------+ + +You can put ":tab" before any Ex command that opens a window. The window will +be opened in a new tab page. Another example: > + + :tab help gt + +Will show the help text for "gt" in a new tab page. + +A few more things you can do with tab pages: + +- click with the mouse in the space after the last label + The next tab page will be selected, like with "gt". + +- click with the mouse on the "X" in the top right corner + The current tab page will be closed. Unless there are unsaved + changes in the current tab page. + +- double click with the mouse in the top line + A new tab page will be created. + +- the "tabonly" command + Closes all tab pages except the current one. Unless there are unsaved + changes in other tab pages. + +For more information about tab pages see |tab-page|. + +============================================================================== + +Next chapter: |usr_09.txt| Using the GUI + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime_tos/doc/usr_09.txt b/runtime_tos/doc/usr_09.txt new file mode 100644 index 00000000000000..68575f51844d84 --- /dev/null +++ b/runtime_tos/doc/usr_09.txt @@ -0,0 +1,289 @@ +*usr_09.txt* For Vim version 7.4. Last change: 2006 Apr 24 + + 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. (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. and 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: diff --git a/runtime_tos/doc/usr_10.txt b/runtime_tos/doc/usr_10.txt new file mode 100644 index 00000000000000..4398c4d64fcc0d --- /dev/null +++ b/runtime_tos/doc/usr_10.txt @@ -0,0 +1,824 @@ +*usr_10.txt* For Vim version 7.4. Last change: 2006 Nov 05 + + 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 " Insert the string #include " at the beginning + of the line. + $ Move to the end of the line. + a" 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 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/wordq + +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 the last 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}" 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 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. + +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 ". 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. And it does insert text in a short line. Thus you can +make a choice whether you do or don't want to append text to a short line. + 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, 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_", 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" 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 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 + +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" 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: diff --git a/runtime_tos/doc/usr_11.txt b/runtime_tos/doc/usr_11.txt new file mode 100644 index 00000000000000..9935ded48c03ec --- /dev/null +++ b/runtime_tos/doc/usr_11.txt @@ -0,0 +1,307 @@ +*usr_11.txt* For Vim version 7.4. Last change: 2010 Jul 20 + + VIM USER MANUAL - by Bram Moolenaar + + Recovering from a crash + + +Did your computer crash? And you just spent hours editing? Don't panic! Vim +stores enough information 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 Vim recovered your changes 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) ~ + You may want to delete the .swp file now. ~ + +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|. For example: > + + :write help.txt.recovered + :edit # + :diffsp help.txt + +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. + +If the recovery resulted in text that is exactly the same as the file +contents, you will get this message: + + Using swap file ".help.txt.swp" ~ + Original file "~/vim/runtime/doc/help.txt" ~ + Recovery completed. Buffer contents equals file contents. ~ + You may want to delete the .swp file now. ~ + +This usually happens if you already recovered your changes, or you wrote the +file after making changes. It is safe to delete the swap file now. + +It is 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. +Vim recognizes files with the pattern *.s[uvw][a-z] as swap files. + +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? *swap-exists-choices* + +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. + +For remarks about encryption and the swap file, see |:recover-crypt|. + +============================================================================== +*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: diff --git a/runtime_tos/doc/usr_12.txt b/runtime_tos/doc/usr_12.txt new file mode 100644 index 00000000000000..fba1b532747624 --- /dev/null +++ b/runtime_tos/doc/usr_12.txt @@ -0,0 +1,358 @@ +*usr_12.txt* For Vim version 7.4. Last change: 2007 May 11 + + 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/\" to match the end of +a word: > + + :%s/\/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/\/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/\/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/\/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 \". 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 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 , 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 "/". 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 file it is), 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: diff --git a/runtime_tos/doc/usr_20.txt b/runtime_tos/doc/usr_20.txt new file mode 100644 index 00000000000000..5f0a66018709c8 --- /dev/null +++ b/runtime_tos/doc/usr_20.txt @@ -0,0 +1,384 @@ +*usr_20.txt* For Vim version 7.4. Last change: 2006 Apr 24 + + 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 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 , you notice that "col" should be "cow". To correct +this, you type five times. The cursor is now just after "col". Type + and "w" to correct: > + + :s/cow/pig/ + +Now you can press 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: + + one character left + one character right + or one word left + or one word right + CTRL-B or to begin of command line + CTRL-E or to end of command line + + Note: + (cursor left key with Shift key pressed) and (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, 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 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 twice (or eight +times, if doesn't work). Now press to switch to overstrike +and type "great": + + /the greatpig ~ + +Oops, we lost the space. Now, don't use , because it would delete the +"t" (this is different from Replace mode). Instead, press 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 . + + Note: + is the universal "get out" key. Unfortunately, in the good old + Vi pressing in a command line executed the command! Since that + might be considered to be a bug, Vim uses 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) 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 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 + +Which will result in the same command. What happened? The 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 + +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 again, you get: > + + :edit intro.txt + +Thus, if the first 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 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: + + <------------------- -------------------------+ + | + --> --> + :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 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 , Vim will cycle through all matches. +There are quite a few, it's better to type more characters first: > + + :set isk + +Gives: > + + :set iskeyword + +Now type "=" and press : > + + :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 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 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 + to correct the word. If there are many matches, type a few more +characters before pressing 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 key to recall an older command line. 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 . There is a quicker way: > + + :se + +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 very often (unless ":set" commands is all +you have done). + +The 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 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 , except that it doesn't matter what you already +typed. Similarly for CTRL-N and . 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 and this command will be executed. The command line window +will close. + The 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: diff --git a/runtime_tos/doc/usr_21.txt b/runtime_tos/doc/usr_21.txt new file mode 100644 index 00000000000000..450d3943375776 --- /dev/null +++ b/runtime_tos/doc/usr_21.txt @@ -0,0 +1,499 @@ +*usr_21.txt* For Vim version 7.4. Last change: 2012 Nov 02 + + 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 +. 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 presence 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 STOPPED VIM + +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. + + +GETTING BACK TO SOME FILE + +If you want to go back to a file that you edited recently, but not when +exiting Vim, there is a slightly more complicated way. You can see a list of +files by typing the command: > + + :oldfiles +< 1: ~/.viminfo ~ + 2: ~/text/resume.txt ~ + 3: /tmp/draft ~ + +Now you would like to edit the second file, which is in the list preceded by +"2:". You type: > + + :e #<2 + +Instead of ":e" you can use any command that has a file name argument, the +"#<2" item works in the same place as "%" (current file name) and "#" +(alternate file name). So you can also split the window to edit the third +file: > + + :split #<3 + +That #<123 thing is a bit complicated when you just want to edit a file. +Fortunately there is a simpler way: > + + :browse oldfiles +< 1: ~/.viminfo ~ + 2: ~/text/resume.txt ~ + 3: /tmp/draft ~ + -- More -- + +You get the same list of files as with |:oldfiles|. If you want to edit +"resume.txt" first press "q" to stop the listing. You will get a prompt: + + Type number and (empty cancels): ~ + +Type "2" and press to edit the second file. + +More info at |:oldfiles|, |v:oldfiles| and |c_#<|. + + +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 your 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 windows, 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 choose. 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 on Unix or Administrator on MS-Windows, or when you 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. There 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: diff --git a/runtime_tos/doc/usr_22.txt b/runtime_tos/doc/usr_22.txt new file mode 100644 index 00000000000000..cff8e9db1e3d20 --- /dev/null +++ b/runtime_tos/doc/usr_22.txt @@ -0,0 +1,400 @@ +*usr_22.txt* For Vim version 7.4. Last change: 2012 Nov 15 + + 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 browser +|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 browser + +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: + +" ============================================================================ ~ +" Netrw Directory Listing (netrw v109) ~ +" Sorted by name ~ +" Sort sequence: [\/]$,\.h$,\.c$,\.cpp$,*,\.info$,\.swp$,\.o$\.obj$,\.bak$ ~ +" Quick Help: :help -:go up dir D:delete R:rename s:sort-by x:exec ~ +" ============================================================================ ~ +../ ~ +./ ~ +check/ ~ +Makefile ~ +autocmd.txt ~ +change.txt ~ +eval.txt~ ~ +filetype.txt~ ~ +help.txt.info ~ + +You can see these items: + +1. The name of the browsing tool and its version number +2. The name of the browsing directory +3. The method of sorting (may be by name, time, or size) +4. How names are to be sorted (directories first, then *.h files, + *.c files, etc) +5. How to get help (use the key), and an abbreviated listing + of available commands +6. A listing of files, including "../", which allows one to list + the parent directory. + +If you have syntax highlighting enabled, the different parts are highlighted +so as to make it easier to spot them. + +You can use Normal mode Vim commands to move around in the text. For example, +move the cursor atop a file and press ; you will then be editing that +file. To go back to the browser use ":edit ." again, or use ":Explore". +CTRL-O also works. + +Try using while the cursor is atop a directory name. The result is +that the file browser moves into that directory and displays the items found +there. Pressing 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 help on the things you can do in the netrw file +browser. This is what you get: > + + 9. Directory Browsing netrw-browse netrw-dir netrw-list netrw-help + + MAPS netrw-maps + .............Help.......................................|netrw-help| + .............Browsing...................................|netrw-cr| + ............Deleting Files or Directories..............|netrw-delete| + -................Going Up...................................|netrw--| + a................Hiding Files or Directories................|netrw-a| + mb...............Bookmarking a Directory....................|netrw-mb| + gb...............Changing to a Bookmarked Directory.........|netrw-gb| + c................Make Browsing Directory The Current Dir....|netrw-c| + d................Make A New Directory.......................|netrw-d| + D................Deleting Files or Directories..............|netrw-D| + ............Edit File/Directory Hiding List............|netrw-ctrl-h| + i................Change Listing Style.......................|netrw-i| + ............Refreshing the Listing.....................|netrw-ctrl-l| + o................Browsing with a Horizontal Split...........|netrw-o| + p................Use Preview Window.........................|netrw-p| + P................Edit in Previous Window....................|netrw-p| + q................Listing Bookmarks and History..............|netrw-q| + r................Reversing Sorting Order....................|netrw-r| +< (etc) + +The key thus brings you to a netrw directory browsing contents help page. +It's a regular help page; use the usual |CTRL-]| to jump to tagged help items +and |CTRL-O| to jump back. + +To select files for display and editing: (with the cursor is atop a filename) + + Open the file in the current window. |netrw-cr| + o Horizontally split window and display file |netrw-o| + v Vertically split window and display file |netrw-v| + p Use the |preview-window| |netrw-p| + P Edit in the previous window |netrw-P| + t Open file in a new tab |netrw-t| + +The following normal-mode commands may be used to control the browser display: + + i Controls listing style (thin, long, wide, and tree). + The long listing includes size and date information. + s Repeatedly pressing s will change the way the files + are sorted; one may sort on name, modification time, + or size. + r Reverse the sorting order. + +As a sampling of extra normal-mode commands: + + c Change Vim's notion of the current directory to be + the same as the browser directory. (see + |g:netrw_keepdir| to control this, too) + R Rename the file or directory under the cursor; a + prompt will be issued for the new name. + D Delete the file or directory under the cursor; a + confirmation request will be issued. + mb gb Make bookmark/goto bookmark + + +One may also use command mode; again, just a sampling: + + :Explore [directory] Browse specified/current directory + :NetrwSettings A comprehensive list of your current netrw + settings with help linkage. + +The netrw browser is not limited to just your local machine; one may use +urls such as: (that trailing / is important) + + :Explore ftp://somehost/path/to/dir/ + :e scp://somehost/path/to/dir/ + +See |netrw-browse| for more. + +============================================================================== +*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 argument of ":hide" is another command. ":hide" makes that command +behave as if 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 %a + "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. + a 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 the 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: diff --git a/runtime_tos/doc/usr_23.txt b/runtime_tos/doc/usr_23.txt new file mode 100644 index 00000000000000..63cbc612decc42 --- /dev/null +++ b/runtime_tos/doc/usr_23.txt @@ -0,0 +1,343 @@ +*usr_23.txt* For Vim version 7.4. Last change: 2006 Apr 24 + + 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, ), another to move the paper up (line feed, ). + 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 only for end-of-line. The Apple people +standardized on . The MS-DOS (and Microsoft Windows) folks decided to +keep the old . + 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 + dos + mac + + +USING THE MAC FORMAT + +On Unix, is used to break a line. It's not unusual to have a +character halfway a line. Incidentally, this happens quite often in Vi (and +Vim) scripts. + On the Macintosh, where is the line break character, it's possible to +have a character halfway a line. + The result is that it's not possible to be 100% sure whether a file +containing both and 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 ). 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 , 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: diff --git a/runtime_tos/doc/usr_24.txt b/runtime_tos/doc/usr_24.txt new file mode 100644 index 00000000000000..46a22c683c7cfd --- /dev/null +++ b/runtime_tos/doc/usr_24.txt @@ -0,0 +1,606 @@ +*usr_24.txt* For Vim version 7.4. Last change: 2006 Jul 23 + + 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 key was already mentioned. It deletes the character just before the +cursor. The 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: > + + 4blraA + +< get out of Insert mode + four words back 4b + move on top of the "o" l + replace with "a" ra + restart Insert mode A + +Another way to do this: > + + a + +< four words back + move on top of the "o" + delete the "o" + insert an "a" a + go to end of the line + +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 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: + + to start of the file + a whole screenful up + to start of line + one word left + one word left + one word right + one word right + to end of the line + a whole screenful down + 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 no 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. + + +COMPLETING IN SOURCE CODE + +Source code files are well structured. That makes it possible to do +completion in an intelligent way. In Vim this is called Omni completion. In +some other editors it's called intellisense, but that is a trademark. + +The key to Omni completion is CTRL-X CTRL-O. Obviously the O stands for Omni +here, so that you can remember it easier. Let's use an example for editing C +source: + + { ~ + struct foo *p; ~ + p-> ~ + +The cursor is after "p->". Now type CTRL-X CTRL-O. Vim will offer you a list +of alternatives, which are the items that "struct foo" contains. That is +quite different from using CTRL-P, which would complete any word, while only +members of "struct foo" are valid here. + +For Omni completion to work you may need to do some setup. At least make sure +filetype plugins are enabled. Your vimrc file should contain a line like +this: > + filetype plugin on +Or: > + filetype plugin indent on + +For C code you need to create a tags file and set the 'tags' option. That is +explained |ft-c-omni|. For other filetypes you may need to do something +similar, look below |compl-omni-filetypes|. It only works for specific +filetypes. Check the value of the 'omnifunc' option to find out if it would +work. + +============================================================================== +*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" 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 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 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 I saw the advertisement ~ + +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 ****************************************/ + +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 + +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 +character (but not necessarily the key!). To insert 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 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 , +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: diff --git a/runtime_tos/doc/usr_25.txt b/runtime_tos/doc/usr_25.txt new file mode 100644 index 00000000000000..5a687599b357cf --- /dev/null +++ b/runtime_tos/doc/usr_25.txt @@ -0,0 +1,578 @@ +*usr_25.txt* For Vim version 7.4. Last change: 2007 May 11 + + VIM USER MANUAL - by Bram Moolenaar + + Editing formatted text + + +Text hardly ever comes in one sentence per line. This chapter is about +breaking sentences to make them fit on a page and other formatting. +Vim also has useful features for editing single-line paragraphs and tables. + +|25.1| Breaking lines +|25.2| Aligning text +|25.3| Indents and tabs +|25.4| Dealing with long lines +|25.5| Editing tables + + Next chapter: |usr_26.txt| Repeating + Previous chapter: |usr_24.txt| Inserting quickly +Table of contents: |usr_toc.txt| + +============================================================================== +*25.1* Breaking lines + +Vim has a number of functions that make dealing with text easier. By default, +the editor does not perform automatic line breaks. In other words, you have +to press yourself. This is useful when you are writing programs where +you want to decide where the line ends. It is not so good when you are +creating documentation and want the text to be at most 70 character wide. + If you set the 'textwidth' option, Vim automatically inserts line breaks. +Suppose, for example, that you want a very narrow column of only 30 +characters. You need to execute the following command: > + + :set textwidth=30 + +Now you start typing (ruler added): + + 1 2 3 + 12345678901234567890123456789012345 + I taught programming for a whi ~ + +If you type "l" next, this makes the line longer than the 30-character limit. +When Vim sees this, it inserts a line break and you get the following: + + 1 2 3 + 12345678901234567890123456789012345 + I taught programming for a ~ + whil ~ + +Continuing on, you can type in the rest of the paragraph: + + 1 2 3 + 12345678901234567890123456789012345 + I taught programming for a ~ + while. One time, I was stopped ~ + by the Fort Worth police, ~ + because my homework was too ~ + hard. True story. ~ + +You do not have to type newlines; Vim puts them in automatically. + + Note: + The 'wrap' option makes Vim display lines with a line break, but this + doesn't insert a line break in the file. + + +REFORMATTING + +The Vim editor is not a word processor. In a word processor, if you delete +something at the beginning of the paragraph, the line breaks are reworked. In +Vim they are not; so if you delete the word "programming" from the first line, +all you get is a short line: + + 1 2 3 + 12345678901234567890123456789012345 + I taught for a ~ + while. One time, I was stopped ~ + by the Fort Worth police, ~ + because my homework was too ~ + hard. True story. ~ + +This does not look good. To get the paragraph into shape you use the "gq" +operator. + Let's first use this with a Visual selection. Starting from the first +line, type: > + + v4jgq + +"v" to start Visual mode, "4j" to move to the end of the paragraph and then +the "gq" operator. The result is: + + 1 2 3 + 12345678901234567890123456789012345 + I taught for a while. One ~ + time, I was stopped by the ~ + Fort Worth police, because my ~ + homework was too hard. True ~ + story. ~ + +Note: there is a way to do automatic formatting for specific types of text +layouts, see |auto-format|. + +Since "gq" is an operator, you can use one of the three ways to select the +text it works on: With Visual mode, with a movement and with a text object. + The example above could also be done with "gq4j". That's less typing, but +you have to know the line count. A more useful motion command is "}". This +moves to the end of a paragraph. Thus "gq}" formats from the cursor to the +end of the current paragraph. + A very useful text object to use with "gq" is the paragraph. Try this: > + + gqap + +"ap" stands for "a-paragraph". This formats the text of one paragraph +(separated by empty lines). Also the part before the cursor. + If you have your paragraphs separated by empty lines, you can format the +whole file by typing this: > + + gggqG + +"gg" to move to the first line, "gqG" to format until the last line. + Warning: If your paragraphs are not properly separated, they will be joined +together. A common mistake is to have a line with a space or tab. That's a +blank line, but not an empty line. + +Vim is able to format more than just plain text. See |fo-table| for how to +change this. See the 'joinspaces' option to change the number of spaces used +after a full stop. + It is possible to use an external program for formatting. This is useful +if your text can't be properly formatted with Vim's builtin command. See the +'formatprg' option. + +============================================================================== +*25.2* Aligning text + +To center a range of lines, use the following command: > + + :{range}center [width] + +{range} is the usual command-line range. [width] is an optional line width to +use for centering. If [width] is not specified, it defaults to the value of +'textwidth'. (If 'textwidth' is 0, the default is 80.) + For example: > + + :1,5center 40 + +results in the following: + + I taught for a while. One ~ + time, I was stopped by the ~ + Fort Worth police, because my ~ + homework was too hard. True ~ + story. ~ + + +RIGHT ALIGNMENT + +Similarly, the ":right" command right-justifies the text: > + + :1,5right 37 + +gives this result: + + I taught for a while. One ~ + time, I was stopped by the ~ + Fort Worth police, because my ~ + homework was too hard. True ~ + story. ~ + +LEFT ALIGNMENT + +Finally there is this command: > + + :{range}left [margin] + +Unlike ":center" and ":right", however, the argument to ":left" is not the +length of the line. Instead it is the left margin. If it is omitted, the +text will be put against the left side of the screen (using a zero margin +would do the same). If it is 5, the text will be indented 5 spaces. For +example, use these commands: > + + :1left 5 + :2,5left + +This results in the following: + + I taught for a while. One ~ + time, I was stopped by the ~ + Fort Worth police, because my ~ + homework was too hard. True ~ + story. ~ + + +JUSTIFYING TEXT + +Vim has no built-in way of justifying text. However, there is a neat macro +package that does the job. To use this package, execute the following +command: > + + :runtime macros/justify.vim + +This Vim script file defines a new visual command "_j". To justify a block of +text, highlight the text in Visual mode and then execute "_j". + Look in the file for more explanations. To go there, do "gf" on this name: +$VIMRUNTIME/macros/justify.vim. + +An alternative is to filter the text through an external program. Example: > + + :%!fmt + +============================================================================== +*25.3* Indents and tabs + +Indents can be used to make text stand out from the rest. The example texts +in this manual, for example, are indented by eight spaces or a tab. You would +normally enter this by typing a tab at the start of each line. Take this +text: + the first line ~ + the second line ~ + +This is entered by typing a tab, some text, , tab and more text. + The 'autoindent' option inserts indents automatically: > + + :set autoindent + +When a new line is started it gets the same indent as the previous line. In +the above example, the tab after the is not needed anymore. + + +INCREASING INDENT + +To increase the amount of indent in a line, use the ">" operator. Often this +is used as ">>", which adds indent to the current line. + The amount of indent added is specified with the 'shiftwidth' option. The +default value is 8. To make ">>" insert four spaces worth of indent, for +example, type this: > + + :set shiftwidth=4 + +When used on the second line of the example text, this is what you get: + + the first line ~ + the second line ~ + +"4>>" will increase the indent of four lines. + + +TABSTOP + +If you want to make indents a multiple of 4, you set 'shiftwidth' to 4. But +when pressing a you still get 8 spaces worth of indent. To change this, +set the 'softtabstop' option: > + + :set softtabstop=4 + +This will make the key insert 4 spaces worth of indent. If there are +already four spaces, a character is used (saving seven characters in the +file). (If you always want spaces and no tab characters, set the 'expandtab' +option.) + + Note: + You could set the 'tabstop' option to 4. However, if you edit the + file another time, with 'tabstop' set to the default value of 8, it + will look wrong. In other programs and when printing the indent will + also be wrong. Therefore it is recommended to keep 'tabstop' at eight + all the time. That's the standard value everywhere. + + +CHANGING TABS + +You edit a file which was written with a tabstop of 3. In Vim it looks ugly, +because it uses the normal tabstop value of 8. You can fix this by setting +'tabstop' to 3. But you have to do this every time you edit this file. + Vim can change the use of tabstops in your file. First, set 'tabstop' to +make the indents look good, then use the ":retab" command: > + + :set tabstop=3 + :retab 8 + +The ":retab" command will change 'tabstop' to 8, while changing the text such +that it looks the same. It changes spans of white space into tabs and spaces +for this. You can now write the file. Next time you edit it the indents will +be right without setting an option. + Warning: When using ":retab" on a program, it may change white space inside +a string constant. Therefore it's a good habit to use "\t" instead of a +real tab. + +============================================================================== +*25.4* Dealing with long lines + +Sometimes you will be editing a file that is wider than the number of columns +in the window. When that occurs, Vim wraps the lines so that everything fits +on the screen. + If you switch the 'wrap' option off, each line in the file shows up as one +line on the screen. Then the ends of the long lines disappear off the screen +to the right. + When you move the cursor to a character that can't be seen, Vim will scroll +the text to show it. This is like moving a viewport over the text in the +horizontal direction. + By default, Vim does not display a horizontal scrollbar in the GUI. If you +want to enable one, use the following command: > + + :set guioptions+=b + +One horizontal scrollbar will appear at the bottom of the Vim window. + +If you don't have a scrollbar or don't want to use it, use these commands to +scroll the text. The cursor will stay in the same place, but it's moved back +into the visible text if necessary. + + zh scroll right + 4zh scroll four characters right + zH scroll half a window width right + ze scroll right to put the cursor at the end + zl scroll left + 4zl scroll four characters left + zL scroll half a window width left + zs scroll left to put the cursor at the start + +Let's attempt to show this with one line of text. The cursor is on the "w" of +"which". The "current window" above the line indicates the text that is +currently visible. The "window"s below the text indicate the text that is +visible after the command left of it. + + |<-- current window -->| + some long text, part of which is visible in the window ~ + ze |<-- window -->| + zH |<-- window -->| + 4zh |<-- window -->| + zh |<-- window -->| + zl |<-- window -->| + 4zl |<-- window -->| + zL |<-- window -->| + zs |<-- window -->| + + +MOVING WITH WRAP OFF + +When 'wrap' is off and the text has scrolled horizontally, you can use the +following commands to move the cursor to a character you can see. Thus text +left and right of the window is ignored. These never cause the text to +scroll: + + g0 to first visible character in this line + g^ to first non-blank visible character in this line + gm to middle of this line + g$ to last visible character in this line + + |<-- window -->| + some long text, part of which is visible ~ + g0 g^ gm g$ + + +BREAKING AT WORDS *edit-no-break* + +When preparing text for use by another program, you might have to make +paragraphs without a line break. A disadvantage of using 'nowrap' is that you +can't see the whole sentence you are working on. When 'wrap' is on, words are +broken halfway, which makes them hard to read. + A good solution for editing this kind of paragraph is setting the +'linebreak' option. Vim then breaks lines at an appropriate place when +displaying the line. The text in the file remains unchanged. + Without 'linebreak' text might look like this: + + +---------------------------------+ + |letter generation program for a b| + |ank. They wanted to send out a s| + |pecial, personalized letter to th| + |eir richest 1000 customers. Unfo| + |rtunately for the programmer, he | + +---------------------------------+ +After: > + + :set linebreak + +it looks like this: + + +---------------------------------+ + |letter generation program for a | + |bank. They wanted to send out a | + |special, personalized letter to | + |their richest 1000 customers. | + |Unfortunately for the programmer,| + +---------------------------------+ + +Related options: +'breakat' specifies the characters where a break can be inserted. +'showbreak' specifies a string to show at the start of broken line. +Set 'textwidth' to zero to avoid a paragraph to be split. + + +MOVING BY VISIBLE LINES + +The "j" and "k" commands move to the next and previous lines. When used on +a long line, this means moving a lot of screen lines at once. + To move only one screen line, use the "gj" and "gk" commands. When a line +doesn't wrap they do the same as "j" and "k". When the line does wrap, they +move to a character displayed one line below or above. + You might like to use these mappings, which bind these movement commands to +the cursor keys: > + + :map gk + :map gj + + +TURNING A PARAGRAPH INTO ONE LINE + +If you want to import text into a program like MS-Word, each paragraph should +be a single line. If your paragraphs are currently separated with empty +lines, this is how you turn each paragraph into a single line: > + + :g/./,/^$/join + +That looks complicated. Let's break it up in pieces: + + :g/./ A ":global" command that finds all lines that contain + at least one character. + ,/^$/ A range, starting from the current line (the non-empty + line) until an empty line. + join The ":join" command joins the range of lines together + into one line. + +Starting with this text, containing eight lines broken at column 30: + + +----------------------------------+ + |A letter generation program | + |for a bank. They wanted to | + |send out a special, | + |personalized letter. | + | | + |To their richest 1000 | + |customers. Unfortunately for | + |the programmer, | + +----------------------------------+ + +You end up with two lines: + + +----------------------------------+ + |A letter generation program for a | + |bank. They wanted to send out a s| + |pecial, personalized letter. | + |To their richest 1000 customers. | + |Unfortunately for the programmer, | + +----------------------------------+ + +Note that this doesn't work when the separating line is blank but not empty; +when it contains spaces and/or tabs. This command does work with blank lines: +> + :g/\S/,/^\s*$/join + +This still requires a blank or empty line at the end of the file for the last +paragraph to be joined. + +============================================================================== +*25.5* Editing tables + +Suppose you are editing a table with four columns: + + nice table test 1 test 2 test 3 ~ + input A 0.534 ~ + input B 0.913 ~ + +You need to enter numbers in the third column. You could move to the second +line, use "A", enter a lot of spaces and type the text. + For this kind of editing there is a special option: > + + set virtualedit=all + +Now you can move the cursor to positions where there isn't any text. This is +called "virtual space". Editing a table is a lot easier this way. + Move the cursor by searching for the header of the last column: > + + /test 3 + +Now press "j" and you are right where you can enter the value for "input A". +Typing "0.693" results in: + + nice table test 1 test 2 test 3 ~ + input A 0.534 0.693 ~ + input B 0.913 ~ + +Vim has automatically filled the gap in front of the new text for you. Now, +to enter the next field in this column use "Bj". "B" moves back to the start +of a white space separated word. Then "j" moves to the place where the next +field can be entered. + + Note: + You can move the cursor anywhere in the display, also beyond the end + of a line. But Vim will not insert spaces there, until you insert a + character in that position. + + +COPYING A COLUMN + +You want to add a column, which should be a copy of the third column and +placed before the "test 1" column. Do this in seven steps: +1. Move the cursor to the left upper corner of this column, e.g., with + "/test 3". +2. Press CTRL-V to start blockwise Visual mode. +3. Move the cursor down two lines with "2j". You are now in "virtual space": + the "input B" line of the "test 3" column. +4. Move the cursor right, to include the whole column in the selection, plus + the space that you want between the columns. "9l" should do it. +5. Yank the selected rectangle with "y". +6. Move the cursor to "test 1", where the new column must be placed. +7. Press "P". + +The result should be: + + nice table test 3 test 1 test 2 test 3 ~ + input A 0.693 0.534 0.693 ~ + input B 0.913 ~ + +Notice that the whole "test 1" column was shifted right, also the line where +the "test 3" column didn't have text. + +Go back to non-virtual cursor movements with: > + + :set virtualedit= + + +VIRTUAL REPLACE MODE + +The disadvantage of using 'virtualedit' is that it "feels" different. You +can't recognize tabs or spaces beyond the end of line when moving the cursor +around. Another method can be used: Virtual Replace mode. + Suppose you have a line in a table that contains both tabs and other +characters. Use "rx" on the first tab: + + inp 0.693 0.534 0.693 ~ + + | + rx | + V + + inpx0.693 0.534 0.693 ~ + +The layout is messed up. To avoid that, use the "gr" command: + + inp 0.693 0.534 0.693 ~ + + | + grx | + V + + inpx 0.693 0.534 0.693 ~ + +What happens is that the "gr" command makes sure the new character takes the +right amount of screen space. Extra spaces or tabs are inserted to fill the +gap. Thus what actually happens is that a tab is replaced by "x" and then +blanks added to make the text after it keep its place. In this case a +tab is inserted. + When you need to replace more than one character, you use the "R" command +to go to Replace mode (see |04.9|). This messes up the layout and replaces +the wrong characters: + + inp 0 0.534 0.693 ~ + + | + R0.786 | + V + + inp 0.78634 0.693 ~ + +The "gR" command uses Virtual Replace mode. This preserves the layout: + + inp 0 0.534 0.693 ~ + + | + gR0.786 | + V + + inp 0.786 0.534 0.693 ~ + +============================================================================== + +Next chapter: |usr_26.txt| Repeating + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime_tos/doc/usr_26.txt b/runtime_tos/doc/usr_26.txt new file mode 100644 index 00000000000000..cc2395962143a3 --- /dev/null +++ b/runtime_tos/doc/usr_26.txt @@ -0,0 +1,221 @@ +*usr_26.txt* For Vim version 7.4. Last change: 2006 Apr 24 + + VIM USER MANUAL - by Bram Moolenaar + + Repeating + + +An editing task is hardly ever unstructured. A change often needs to be made +several times. In this chapter a number of useful ways to repeat a change +will be explained. + +|26.1| Repeating with Visual mode +|26.2| Add and subtract +|26.3| Making a change in many files +|26.4| Using Vim from a shell script + + Next chapter: |usr_27.txt| Search commands and patterns + Previous chapter: |usr_25.txt| Editing formatted text +Table of contents: |usr_toc.txt| + +============================================================================== +*26.1* Repeating with Visual mode + +Visual mode is very handy for making a change in any sequence of lines. You +can see the highlighted text, thus you can check if the correct lines are +changed. But making the selection takes some typing. The "gv" command +selects the same area again. This allows you to do another operation on the +same text. + Suppose you have some lines where you want to change "2001" to "2002" and +"2000" to "2001": + + The financial results for 2001 are better ~ + than for 2000. The income increased by 50%, ~ + even though 2001 had more rain than 2000. ~ + 2000 2001 ~ + income 45,403 66,234 ~ + +First change "2001" to "2002". Select the lines in Visual mode, and use: > + + :s/2001/2002/g + +Now use "gv" to reselect the same text. It doesn't matter where the cursor +is. Then use ":s/2000/2001/g" to make the second change. + Obviously, you can repeat these changes several times. + +============================================================================== +*26.2* Add and subtract + +When repeating the change of one number into another, you often have a fixed +offset. In the example above, one was added to each year. Instead of typing +a substitute command for each year that appears, the CTRL-A command can be +used. + Using the same text as above, search for a year: > + + /19[0-9][0-9]\|20[0-9][0-9] + +Now press CTRL-A. The year will be increased by one: + + The financial results for 2002 are better ~ + than for 2000. The income increased by 50%, ~ + even though 2001 had more rain than 2000. ~ + 2000 2001 ~ + income 45,403 66,234 ~ + +Use "n" to find the next year, and press "." to repeat the CTRL-A ("." is a +bit quicker to type). Repeat "n" and "." for all years that appear. + Hint: set the 'hlsearch' option to see the matches you are going to change, +then you can look ahead and do it faster. + +Adding more than one can be done by prepending the number to CTRL-A. Suppose +you have this list: + + 1. item four ~ + 2. item five ~ + 3. item six ~ + +Move the cursor to "1." and type: > + + 3 CTRL-A + +The "1." will change to "4.". Again, you can use "." to repeat this on the +other numbers. + +Another example: + + 006 foo bar ~ + 007 foo bar ~ + +Using CTRL-A on these numbers results in: + + 007 foo bar ~ + 010 foo bar ~ + +7 plus one is 10? What happened here is that Vim recognized "007" as an octal +number, because there is a leading zero. This notation is often used in C +programs. If you do not want a number with leading zeros to be handled as +octal, use this: > + + :set nrformats-=octal + +The CTRL-X command does subtraction in a similar way. + +============================================================================== +*26.3* Making a change in many files + +Suppose you have a variable called "x_cnt" and you want to change it to +"x_counter". This variable is used in several of your C files. You need to +change it in all files. This is how you do it. + Put all the relevant files in the argument list: > + + :args *.c +< +This finds all C files and edits the first one. Now you can perform a +substitution command on all these files: > + + :argdo %s/\/x_counter/ge | update + +The ":argdo" command takes an argument that is another command. That command +will be executed on all files in the argument list. + The "%s" substitute command that follows works on all lines. It finds the +word "x_cnt" with "\". The "\<" and "\>" are used to match the whole +word only, and not "px_cnt" or "x_cnt2". + The flags for the substitute command include "g" to replace all occurrences +of "x_cnt" in the same line. The "e" flag is used to avoid an error message +when "x_cnt" does not appear in the file. Otherwise ":argdo" would abort on +the first file where "x_cnt" was not found. + The "|" separates two commands. The following "update" command writes the +file only if it was changed. If no "x_cnt" was changed to "x_counter" nothing +happens. + +There is also the ":windo" command, which executes its argument in all +windows. And ":bufdo" executes its argument on all buffers. Be careful with +this, because you might have more files in the buffer list than you think. +Check this with the ":buffers" command (or ":ls"). + +============================================================================== +*26.4* Using Vim from a shell script + +Suppose you have a lot of files in which you need to change the string +"-person-" to "Jones" and then print it. How do you do that? One way is to +do a lot of typing. The other is to write a shell script to do the work. + The Vim editor does a superb job as a screen-oriented editor when using +Normal mode commands. For batch processing, however, Normal mode commands do +not result in clear, commented command files; so here you will use Ex mode +instead. This mode gives you a nice command-line interface that makes it easy +to put into a batch file. ("Ex command" is just another name for a +command-line (:) command.) + The Ex mode commands you need are as follows: > + + %s/-person-/Jones/g + write tempfile + quit + +You put these commands in the file "change.vim". Now to run the editor in +batch mode, use this shell script: > + + for file in *.txt; do + vim -e -s $file < change.vim + lpr -r tempfile + done + +The for-done loop is a shell construct to repeat the two lines in between, +while the $file variable is set to a different file name each time. + The second line runs the Vim editor in Ex mode (-e argument) on the file +$file and reads commands from the file "change.vim". The -s argument tells +Vim to operate in silent mode. In other words, do not keep outputting the +:prompt, or any other prompt for that matter. + The "lpr -r tempfile" command prints the resulting "tempfile" and deletes +it (that's what the -r argument does). + + +READING FROM STDIN + +Vim can read text on standard input. Since the normal way is to read commands +there, you must tell Vim to read text instead. This is done by passing the +"-" argument in place of a file. Example: > + + ls | vim - + +This allows you to edit the output of the "ls" command, without first saving +the text in a file. + If you use the standard input to read text from, you can use the "-S" +argument to read a script: > + + producer | vim -S change.vim - + + +NORMAL MODE SCRIPTS + +If you really want to use Normal mode commands in a script, you can use it +like this: > + + vim -s script file.txt ... +< + Note: + "-s" has a different meaning when it is used without "-e". Here it + means to source the "script" as Normal mode commands. When used with + "-e" it means to be silent, and doesn't use the next argument as a + file name. + +The commands in "script" are executed like you typed them. Don't forget that +a line break is interpreted as pressing . In Normal mode that moves +the cursor to the next line. + To create the script you can edit the script file and type the commands. +You need to imagine what the result would be, which can be a bit difficult. +Another way is to record the commands while you perform them manually. This +is how you do that: > + + vim -w script file.txt ... + +All typed keys will be written to "script". If you make a small mistake you +can just continue and remember to edit the script later. + The "-w" argument appends to an existing script. That is good when you +want to record the script bit by bit. If you want to start from scratch and +start all over, use the "-W" argument. It overwrites any existing file. + +============================================================================== + +Next chapter: |usr_27.txt| Search commands and patterns + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime_tos/doc/usr_27.txt b/runtime_tos/doc/usr_27.txt new file mode 100644 index 00000000000000..fb096593f28878 --- /dev/null +++ b/runtime_tos/doc/usr_27.txt @@ -0,0 +1,563 @@ +*usr_27.txt* For Vim version 7.4. Last change: 2010 Mar 28 + + VIM USER MANUAL - by Bram Moolenaar + + Search commands and patterns + + +In chapter 3 a few simple search patterns were mentioned |03.9|. Vim can do +much more complex searches. This chapter explains the most often used ones. +A detailed specification can be found here: |pattern| + +|27.1| Ignoring case +|27.2| Wrapping around the file end +|27.3| Offsets +|27.4| Matching multiple times +|27.5| Alternatives +|27.6| Character ranges +|27.7| Character classes +|27.8| Matching a line break +|27.9| Examples + + Next chapter: |usr_28.txt| Folding + Previous chapter: |usr_26.txt| Repeating +Table of contents: |usr_toc.txt| + +============================================================================== +*27.1* Ignoring case + +By default, Vim's searches are case sensitive. Therefore, "include", +"INCLUDE", and "Include" are three different words and a search will match +only one of them. + Now switch on the 'ignorecase' option: > + + :set ignorecase + +Search for "include" again, and now it will match "Include", "INCLUDE" and +"InClUDe". (Set the 'hlsearch' option to quickly see where a pattern +matches.) + You can switch this off again with: > + + :set noignorecase + +But let's keep it set, and search for "INCLUDE". It will match exactly the +same text as "include" did. Now set the 'smartcase' option: > + + :set ignorecase smartcase + +If you have a pattern with at least one uppercase character, the search +becomes case sensitive. The idea is that you didn't have to type that +uppercase character, so you must have done it because you wanted case to +match. That's smart! + With these two options set you find the following matches: + + pattern matches ~ + word word, Word, WORD, WoRd, etc. + Word Word + WORD WORD + WoRd WoRd + + +CASE IN ONE PATTERN + +If you want to ignore case for one specific pattern, you can do this by +prepending the "\c" string. Using "\C" will make the pattern to match case. +This overrules the 'ignorecase' and 'smartcase' options, when "\c" or "\C" is +used their value doesn't matter. + + pattern matches ~ + \Cword word + \CWord Word + \cword word, Word, WORD, WoRd, etc. + \cWord word, Word, WORD, WoRd, etc. + +A big advantage of using "\c" and "\C" is that it sticks with the pattern. +Thus if you repeat a pattern from the search history, the same will happen, no +matter if 'ignorecase' or 'smartcase' was changed. + + Note: + The use of "\" items in search patterns depends on the 'magic' option. + In this chapter we will assume 'magic' is on, because that is the + standard and recommended setting. If you would change 'magic', many + search patterns would suddenly become invalid. + + Note: + If your search takes much longer than you expected, you can interrupt + it with CTRL-C on Unix and CTRL-Break on MS-DOS and MS-Windows. + +============================================================================== +*27.2* Wrapping around the file end + +By default, a forward search starts searching for the given string at the +current cursor location. It then proceeds to the end of the file. If it has +not found the string by that time, it starts from the beginning and searches +from the start of the file to the cursor location. + Keep in mind that when repeating the "n" command to search for the next +match, you eventually get back to the first match. If you don't notice this +you keep searching forever! To give you a hint, Vim displays this message: + + search hit BOTTOM, continuing at TOP ~ + +If you use the "?" command, to search in the other direction, you get this +message: + + search hit TOP, continuing at BOTTOM ~ + +Still, you don't know when you are back at the first match. One way to see +this is by switching on the 'ruler' option: > + + :set ruler + +Vim will display the cursor position in the lower righthand corner of the +window (in the status line if there is one). It looks like this: + + 101,29 84% ~ + +The first number is the line number of the cursor. Remember the line number +where you started, so that you can check if you passed this position again. + + +NOT WRAPPING + +To turn off search wrapping, use the following command: > + + :set nowrapscan + +Now when the search hits the end of the file, an error message displays: + + E385: search hit BOTTOM without match for: forever ~ + +Thus you can find all matches by going to the start of the file with "gg" and +keep searching until you see this message. + If you search in the other direction, using "?", you get: + + E384: search hit TOP without match for: forever ~ + +============================================================================== +*27.3* Offsets + +By default, the search command leaves the cursor positioned on the beginning +of the pattern. You can tell Vim to leave it some other place by specifying +an offset. For the forward search command "/", the offset is specified by +appending a slash (/) and the offset: > + + /default/2 + +This command searches for the pattern "default" and then moves to the +beginning of the second line past the pattern. Using this command on the +paragraph above, Vim finds the word "default" in the first line. Then the +cursor is moved two lines down and lands on "an offset". + +If the offset is a simple number, the cursor will be placed at the beginning +of the line that many lines from the match. The offset number can be positive +or negative. If it is positive, the cursor moves down that many lines; if +negative, it moves up. + + +CHARACTER OFFSETS + +The "e" offset indicates an offset from the end of the match. It moves the +cursor onto the last character of the match. The command: > + + /const/e + +puts the cursor on the "t" of "const". + From that position, adding a number moves forward that many characters. +This command moves to the character just after the match: > + + /const/e+1 + +A positive number moves the cursor to the right, a negative number moves it to +the left. For example: > + + /const/e-1 + +moves the cursor to the "s" of "const". + +If the offset begins with "b", the cursor moves to the beginning of the +pattern. That's not very useful, since leaving out the "b" does the same +thing. It does get useful when a number is added or subtracted. The cursor +then goes forward or backward that many characters. For example: > + + /const/b+2 + +Moves the cursor to the beginning of the match and then two characters to the +right. Thus it lands on the "n". + + +REPEATING + +To repeat searching for the previously used search pattern, but with a +different offset, leave out the pattern: > + + /that + //e + +Is equal to: > + + /that/e + +To repeat with the same offset: > + + / + +"n" does the same thing. To repeat while removing a previously used offset: > + + // + + +SEARCHING BACKWARDS + +The "?" command uses offsets in the same way, but you must use "?" to separate +the offset from the pattern, instead of "/": > + + ?const?e-2 + +The "b" and "e" keep their meaning, they don't change direction with the use +of "?". + + +START POSITION + +When starting a search, it normally starts at the cursor position. When you +specify a line offset, this can cause trouble. For example: > + + /const/-2 + +This finds the next word "const" and then moves two lines up. If you +use "n" to search again, Vim could start at the current position and find the same +"const" match. Then using the offset again, you would be back where you started. +You would be stuck! + It could be worse: Suppose there is another match with "const" in the next +line. Then repeating the forward search would find this match and move two +lines up. Thus you would actually move the cursor back! + +When you specify a character offset, Vim will compensate for this. Thus the +search starts a few characters forward or backward, so that the same match +isn't found again. + +============================================================================== +*27.4* Matching multiple times + +The "*" item specifies that the item before it can match any number of times. +Thus: > + + /a* + +matches "a", "aa", "aaa", etc. But also "" (the empty string), because zero +times is included. + The "*" only applies to the item directly before it. Thus "ab*" matches +"a", "ab", "abb", "abbb", etc. To match a whole string multiple times, it +must be grouped into one item. This is done by putting "\(" before it and +"\)" after it. Thus this command: > + + /\(ab\)* + +Matches: "ab", "abab", "ababab", etc. And also "". + +To avoid matching the empty string, use "\+". This makes the previous item +match one or more times. > + + /ab\+ + +Matches "ab", "abb", "abbb", etc. It does not match "a" when no "b" follows. + +To match an optional item, use "\=". Example: > + + /folders\= + +Matches "folder" and "folders". + + +SPECIFIC COUNTS + +To match a specific number of items use the form "\{n,m}". "n" and "m" are +numbers. The item before it will be matched "n" to "m" times |inclusive|. +Example: > + + /ab\{3,5} + +matches "abbb", "abbbb" and "abbbbb". + When "n" is omitted, it defaults to zero. When "m" is omitted it defaults +to infinity. When ",m" is omitted, it matches exactly "n" times. +Examples: + + pattern match count ~ + \{,4} 0, 1, 2, 3 or 4 + \{3,} 3, 4, 5, etc. + \{0,1} 0 or 1, same as \= + \{0,} 0 or more, same as * + \{1,} 1 or more, same as \+ + \{3} 3 + + +MATCHING AS LITTLE AS POSSIBLE + +The items so far match as many characters as they can find. To match as few +as possible, use "\{-n,m}". It works the same as "\{n,m}", except that the +minimal amount possible is used. + For example, use: > + + /ab\{-1,3} + +Will match "ab" in "abbb". Actually, it will never match more than one b, +because there is no reason to match more. It requires something else to force +it to match more than the lower limit. + The same rules apply to removing "n" and "m". It's even possible to remove +both of the numbers, resulting in "\{-}". This matches the item before it +zero or more times, as few as possible. The item by itself always matches +zero times. It is useful when combined with something else. Example: > + + /a.\{-}b + +This matches "axb" in "axbxb". If this pattern would be used: > + + /a.*b + +It would try to match as many characters as possible with ".*", thus it +matches "axbxb" as a whole. + +============================================================================== +*27.5* Alternatives + +The "or" operator in a pattern is "\|". Example: > + + /foo\|bar + +This matches "foo" or "bar". More alternatives can be concatenated: > + + /one\|two\|three + +Matches "one", "two" and "three". + To match multiple times, the whole thing must be placed in "\(" and "\)": > + + /\(foo\|bar\)\+ + +This matches "foo", "foobar", "foofoo", "barfoobar", etc. + Another example: > + + /end\(if\|while\|for\) + +This matches "endif", "endwhile" and "endfor". + +A related item is "\&". This requires that both alternatives match in the +same place. The resulting match uses the last alternative. Example: > + + /forever\&... + +This matches "for" in "forever". It will not match "fortuin", for example. + +============================================================================== +*27.6* Character ranges + +To match "a", "b" or "c" you could use "/a\|b\|c". When you want to match all +letters from "a" to "z" this gets very long. There is a shorter method: > + + /[a-z] + +The [] construct matches a single character. Inside you specify which +characters to match. You can include a list of characters, like this: > + + /[0123456789abcdef] + +This will match any of the characters included. For consecutive characters +you can specify the range. "0-3" stands for "0123". "w-z" stands for "wxyz". +Thus the same command as above can be shortened to: > + + /[0-9a-f] + +To match the "-" character itself make it the first or last one in the range. +These special characters are accepted to make it easier to use them inside a +[] range (they can actually be used anywhere in the search pattern): + + \e + \t + \r + \b + +There are a few more special cases for [] ranges, see |/[]| for the whole +story. + + +COMPLEMENTED RANGE + +To avoid matching a specific character, use "^" at the start of the range. +The [] item then matches everything but the characters included. Example: > + + /"[^"]*" +< + " a double quote + [^"] any character that is not a double quote + * as many as possible + " a double quote again + +This matches "foo" and "3!x", including the double quotes. + + +PREDEFINED RANGES + +A number of ranges are used very often. Vim provides a shortcut for these. +For example: > + + /\a + +Finds alphabetic characters. This is equal to using "/[a-zA-Z]". Here are a +few more of these: + + item matches equivalent ~ + \d digit [0-9] + \D non-digit [^0-9] + \x hex digit [0-9a-fA-F] + \X non-hex digit [^0-9a-fA-F] + \s white space [ ] ( and ) + \S non-white characters [^ ] (not and ) + \l lowercase alpha [a-z] + \L non-lowercase alpha [^a-z] + \u uppercase alpha [A-Z] + \U non-uppercase alpha [^A-Z] + + Note: + Using these predefined ranges works a lot faster than the character + range it stands for. + These items can not be used inside []. Thus "[\d\l]" does NOT work to + match a digit or lowercase alpha. Use "\(\d\|\l\)" instead. + +See |/\s| for the whole list of these ranges. + +============================================================================== +*27.7* Character classes + +The character range matches a fixed set of characters. A character class is +similar, but with an essential difference: The set of characters can be +redefined without changing the search pattern. + For example, search for this pattern: > + + /\f\+ + +The "\f" items stands for file name characters. Thus this matches a sequence +of characters that can be a file name. + Which characters can be part of a file name depends on the system you are +using. On MS-Windows, the backslash is included, on Unix it is not. This is +specified with the 'isfname' option. The default value for Unix is: > + + :set isfname + isfname=@,48-57,/,.,-,_,+,,,#,$,%,~,= + +For other systems the default value is different. Thus you can make a search +pattern with "\f" to match a file name, and it will automatically adjust to +the system you are using it on. + + Note: + Actually, Unix allows using just about any character in a file name, + including white space. Including these characters in 'isfname' would + be theoretically correct. But it would make it impossible to find the + end of a file name in text. Thus the default value of 'isfname' is a + compromise. + +The character classes are: + + item matches option ~ + \i identifier characters 'isident' + \I like \i, excluding digits + \k keyword characters 'iskeyword' + \K like \k, excluding digits + \p printable characters 'isprint' + \P like \p, excluding digits + \f file name characters 'isfname' + \F like \f, excluding digits + +============================================================================== +*27.8* Matching a line break + +Vim can find a pattern that includes a line break. You need to specify where +the line break happens, because all items mentioned so far don't match a line +break. + To check for a line break in a specific place, use the "\n" item: > + + /the\nword + +This will match at a line that ends in "the" and the next line starts with +"word". To match "the word" as well, you need to match a space or a line +break. The item to use for it is "\_s": > + + /the\_sword + +To allow any amount of white space: > + + /the\_s\+word + +This also matches when "the " is at the end of a line and " word" at the +start of the next one. + +"\s" matches white space, "\_s" matches white space or a line break. +Similarly, "\a" matches an alphabetic character, and "\_a" matches an +alphabetic character or a line break. The other character classes and ranges +can be modified in the same way by inserting a "_". + +Many other items can be made to match a line break by prepending "\_". For +example: "\_." matches any character or a line break. + + Note: + "\_.*" matches everything until the end of the file. Be careful with + this, it can make a search command very slow. + +Another example is "\_[]", a character range that includes a line break: > + + /"\_[^"]*" + +This finds a text in double quotes that may be split up in several lines. + +============================================================================== +*27.9* Examples + +Here are a few search patterns you might find useful. This shows how the +items mentioned above can be combined. + + +FINDING A CALIFORNIA LICENSE PLATE + +A sample license plate number is "1MGU103". It has one digit, three uppercase +letters and three digits. Directly putting this into a search pattern: > + + /\d\u\u\u\d\d\d + +Another way is to specify that there are three digits and letters with a +count: > + + /\d\u\{3}\d\{3} + +Using [] ranges instead: > + + /[0-9][A-Z]\{3}[0-9]\{3} + +Which one of these you should use? Whichever one you can remember. The +simple way you can remember is much faster than the fancy way that you can't. +If you can remember them all, then avoid the last one, because it's both more +typing and slower to execute. + + +FINDING AN IDENTIFIER + +In C programs (and many other computer languages) an identifier starts with a +letter and further consists of letters and digits. Underscores can be used +too. This can be found with: > + + /\<\h\w*\> + +"\<" and "\>" are used to find only whole words. "\h" stands for "[A-Za-z_]" +and "\w" for "[0-9A-Za-z_]". + + Note: + "\<" and "\>" depend on the 'iskeyword' option. If it includes "-", + for example, then "ident-" is not matched. In this situation use: > + + /\w\@ + + zfap + +You will see that the paragraph is replaced by a highlighted line. You have +created a fold. |zf| is an operator and |ap| a text object selection. You +can use the |zf| operator with any movement command to create a fold for the +text that it moved over. |zf| also works in Visual mode. + +To view the text again, open the fold by typing: > + + zo + +And you can close the fold again with: > + + zc + +All the folding commands start with "z". With some fantasy, this looks like a +folded piece of paper, seen from the side. The letter after the "z" has a +mnemonic meaning to make it easier to remember the commands: + + zf F-old creation + zo O-pen a fold + zc C-lose a fold + +Folds can be nested: A region of text that contains folds can be folded +again. For example, you can fold each paragraph in this section, and then +fold all the sections in this chapter. Try it out. You will notice that +opening the fold for the whole chapter will restore the nested folds as they +were, some may be open and some may be closed. + +Suppose you have created several folds, and now want to view all the text. +You could go to each fold and type "zo". To do this faster, use this command: > + + zr + +This will R-educe the folding. The opposite is: > + + zm + +This folds M-ore. You can repeat "zr" and "zm" to open and close nested folds +of several levels. + +If you have nested several levels deep, you can open all of them with: > + + zR + +This R-educes folds until there are none left. And you can close all folds +with: > + + zM + +This folds M-ore and M-ore. + +You can quickly disable the folding with the |zn| command. Then |zN| brings +back the folding as it was. |zi| toggles between the two. This is a useful +way of working: +- create folds to get overview on your file +- move around to where you want to do your work +- do |zi| to look at the text and edit it +- do |zi| again to go back to moving around + +More about manual folding in the reference manual: |fold-manual| + +============================================================================== +*28.3* Working with folds + +When some folds are closed, movement commands like "j" and "k" move over a +fold like it was a single, empty line. This allows you to quickly move around +over folded text. + +You can yank, delete and put folds as if it was a single line. This is very +useful if you want to reorder functions in a program. First make sure that +each fold contains a whole function (or a bit less) by selecting the right +'foldmethod'. Then delete the function with "dd", move the cursor and put it +with "p". If some lines of the function are above or below the fold, you can +use Visual selection: +- put the cursor on the first line to be moved +- hit "V" to start Visual mode +- put the cursor on the last line to be moved +- hit "d" to delete the selected lines. +- move the cursor to the new position and "p"ut the lines there. + +It is sometimes difficult to see or remember where a fold is located, thus +where a |zo| command would actually work. To see the defined folds: > + + :set foldcolumn=4 + +This will show a small column on the left of the window to indicate folds. +A "+" is shown for a closed fold. A "-" is shown at the start of each open +fold and "|" at following lines of the fold. + +You can use the mouse to open a fold by clicking on the "+" in the foldcolumn. +Clicking on the "-" or a "|" below it will close an open fold. + +To open all folds at the cursor line use |zO|. +To close all folds at the cursor line use |zC|. +To delete a fold at the cursor line use |zd|. +To delete all folds at the cursor line use |zD|. + +When in Insert mode, the fold at the cursor line is never closed. That allows +you to see what you type! + +Folds are opened automatically when jumping around or moving the cursor left +or right. For example, the "0" command opens the fold under the cursor +(if 'foldopen' contains "hor", which is the default). The 'foldopen' option +can be changed to open folds for specific commands. If you want the line +under the cursor always to be open, do this: > + + :set foldopen=all + +Warning: You won't be able to move onto a closed fold then. You might want to +use this only temporarily and then set it back to the default: > + + :set foldopen& + +You can make folds close automatically when you move out of it: > + + :set foldclose=all + +This will re-apply 'foldlevel' to all folds that don't contain the cursor. +You have to try it out if you like how this feels. Use |zm| to fold more and +|zr| to fold less (reduce folds). + +The folding is local to the window. This allows you to open two windows on +the same buffer, one with folds and one without folds. Or one with all folds +closed and one with all folds open. + +============================================================================== +*28.4* Saving and restoring folds + +When you abandon a file (starting to edit another one), the state of the folds +is lost. If you come back to the same file later, all manually opened and +closed folds are back to their default. When folds have been created +manually, all folds are gone! To save the folds use the |:mkview| command: > + + :mkview + +This will store the settings and other things that influence the view on the +file. You can change what is stored with the 'viewoptions' option. +When you come back to the same file later, you can load the view again: > + + :loadview + +You can store up to ten views on one file. For example, to save the current +setup as the third view and load the second view: > + + :mkview 3 + :loadview 2 + +Note that when you insert or delete lines the views might become invalid. +Also check out the 'viewdir' option, which specifies where the views are +stored. You might want to delete old views now and then. + +============================================================================== +*28.5* Folding by indent + +Defining folds with |zf| is a lot of work. If your text is structured by +giving lower level items a larger indent, you can use the indent folding +method. This will create folds for every sequence of lines with the same +indent. Lines with a larger indent will become nested folds. This works well +with many programming languages. + +Try this by setting the 'foldmethod' option: > + + :set foldmethod=indent + +Then you can use the |zm| and |zr| commands to fold more and reduce folding. +It's easy to see on this example text: + +This line is not indented + This line is indented once + This line is indented twice + This line is indented twice + This line is indented once +This line is not indented + This line is indented once + This line is indented once + +Note that the relation between the amount of indent and the fold depth depends +on the 'shiftwidth' option. Each 'shiftwidth' worth of indent adds one to the +depth of the fold. This is called a fold level. + +When you use the |zr| and |zm| commands you actually increase or decrease the +'foldlevel' option. You could also set it directly: > + + :set foldlevel=3 + +This means that all folds with three times a 'shiftwidth' indent or more will +be closed. The lower the foldlevel, the more folds will be closed. When +'foldlevel' is zero, all folds are closed. |zM| does set 'foldlevel' to zero. +The opposite command |zR| sets 'foldlevel' to the deepest fold level that is +present in the file. + +Thus there are two ways to open and close the folds: +(A) By setting the fold level. + This gives a very quick way of "zooming out" to view the structure of the + text, move the cursor, and "zoom in" on the text again. + +(B) By using |zo| and |zc| commands to open or close specific folds. + This allows opening only those folds that you want to be open, while other + folds remain closed. + +This can be combined: You can first close most folds by using |zm| a few times +and then open a specific fold with |zo|. Or open all folds with |zR| and +then close specific folds with |zc|. + +But you cannot manually define folds when 'foldmethod' is "indent", as that +would conflict with the relation between the indent and the fold level. + +More about folding by indent in the reference manual: |fold-indent| + +============================================================================== +*28.6* Folding with markers + +Markers in the text are used to specify the start and end of a fold region. +This gives precise control over which lines are included in a fold. The +disadvantage is that the text needs to be modified. + +Try it: > + + :set foldmethod=marker + +Example text, as it could appear in a C program: + + /* foobar () {{{ */ + int foobar() + { + /* return a value {{{ */ + return 42; + /* }}} */ + } + /* }}} */ + +Notice that the folded line will display the text before the marker. This is +very useful to tell what the fold contains. + +It's quite annoying when the markers don't pair up correctly after moving some +lines around. This can be avoided by using numbered markers. Example: + + /* global variables {{{1 */ + int varA, varB; + + /* functions {{{1 */ + /* funcA() {{{2 */ + void funcA() {} + + /* funcB() {{{2 */ + void funcB() {} + /* }}}1 */ + +At every numbered marker a fold at the specified level begins. This will make +any fold at a higher level stop here. You can just use numbered start markers +to define all folds. Only when you want to explicitly stop a fold before +another starts you need to add an end marker. + +More about folding with markers in the reference manual: |fold-marker| + +============================================================================== +*28.7* Folding by syntax + +For each language Vim uses a different syntax file. This defines the colors +for various items in the file. If you are reading this in Vim, in a terminal +that supports colors, the colors you see are made with the "help" syntax file. + In the syntax files it is possible to add syntax items that have the "fold" +argument. These define a fold region. This requires writing a syntax file +and adding these items in it. That's not so easy to do. But once it's done, +all folding happens automatically. + Here we'll assume you are using an existing syntax file. Then there is +nothing more to explain. You can open and close folds as explained above. +The folds will be created and deleted automatically when you edit the file. + +More about folding by syntax in the reference manual: |fold-syntax| + +============================================================================== +*28.8* Folding by expression + +This is similar to folding by indent, but instead of using the indent of a +line a user function is called to compute the fold level of a line. You can +use this for text where something in the text indicates which lines belong +together. An example is an e-mail message where the quoted text is indicated +by a ">" before the line. To fold these quotes use this: > + + :set foldmethod=expr + :set foldexpr=strlen(substitute(substitute(getline(v:lnum),'\\s','',\"g\"),'[^>].*','','')) + +You can try it out on this text: + +> quoted text he wrote +> quoted text he wrote +> > double quoted text I wrote +> > double quoted text I wrote + +Explanation for the 'foldexpr' used in the example (inside out): + getline(v:lnum) gets the current line + substitute(...,'\\s','','g') removes all white space from the line + substitute(...,'[^>].*','','') removes everything after leading '>'s + strlen(...) counts the length of the string, which + is the number of '>'s found + +Note that a backslash must be inserted before every space, double quote and +backslash for the ":set" command. If this confuses you, do > + + :set foldexpr + +to check the actual resulting value. To correct a complicated expression, use +the command-line completion: > + + :set foldexpr= + +Where is a real Tab. Vim will fill in the previous value, which you can +then edit. + +When the expression gets more complicated you should put it in a function and +set 'foldexpr' to call that function. + +More about folding by expression in the reference manual: |fold-expr| + +============================================================================== +*28.9* Folding unchanged lines + +This is useful when you set the 'diff' option in the same window. The +|vimdiff| command does this for you. Example: > + + :setlocal diff foldmethod=diff scrollbind nowrap foldlevel=1 + +Do this in every window that shows a different version of the same file. You +will clearly see the differences between the files, while the text that didn't +change is folded. + +For more details see |fold-diff|. + +============================================================================== +*28.10* Which fold method to use? + +All these possibilities make you wonder which method you should choose. +Unfortunately, there is no golden rule. Here are some hints. + +If there is a syntax file with folding for the language you are editing, that +is probably the best choice. If there isn't one, you might try to write it. +This requires a good knowledge of search patterns. It's not easy, but when +it's working you will not have to define folds manually. + +Typing commands to manually fold regions can be used for unstructured text. +Then use the |:mkview| command to save and restore your folds. + +The marker method requires you to change the file. If you are sharing the +files with other people or you have to meet company standards, you might not +be allowed to add them. + The main advantage of markers is that you can put them exactly where you +want them. That avoids that a few lines are missed when you cut and paste +folds. And you can add a comment about what is contained in the fold. + +Folding by indent is something that works in many files, but not always very +well. Use it when you can't use one of the other methods. However, it is +very useful for outlining. Then you specifically use one 'shiftwidth' for +each nesting level. + +Folding with expressions can make folds in almost any structured text. It is +quite simple to specify, especially if the start and end of a fold can easily +be recognized. + If you use the "expr" method to define folds, but they are not exactly how +you want them, you could switch to the "manual" method. This will not remove +the defined folds. Then you can delete or add folds manually. + +============================================================================== + +Next chapter: |usr_29.txt| Moving through programs + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime_tos/doc/usr_29.txt b/runtime_tos/doc/usr_29.txt new file mode 100644 index 00000000000000..f13cd3a4096fdf --- /dev/null +++ b/runtime_tos/doc/usr_29.txt @@ -0,0 +1,613 @@ +*usr_29.txt* For Vim version 7.4. Last change: 2008 Jun 28 + + VIM USER MANUAL - by Bram Moolenaar + + Moving through programs + + +The creator of Vim is a computer programmer. It's no surprise that Vim +contains many features to aid in writing programs. Jump around to find where +identifiers are defined and used. Preview declarations in a separate window. +There is more in the next chapter. + +|29.1| Using tags +|29.2| The preview window +|29.3| Moving through a program +|29.4| Finding global identifiers +|29.5| Finding local identifiers + + Next chapter: |usr_30.txt| Editing programs + Previous chapter: |usr_28.txt| Folding +Table of contents: |usr_toc.txt| + +============================================================================== +*29.1* Using tags + +What is a tag? It is a location where an identifier is defined. An example +is a function definition in a C or C++ program. A list of tags is kept in a +tags file. This can be used by Vim to directly jump from any place to the +tag, the place where an identifier is defined. + To generate the tags file for all C files in the current directory, use the +following command: > + + ctags *.c + +"ctags" is a separate program. Most Unix systems already have it installed. +If you do not have it yet, you can find Exuberant ctags here: + + http://ctags.sf.net ~ + +Now when you are in Vim and you want to go to a function definition, you can +jump to it by using the following command: > + + :tag startlist + +This command will find the function "startlist" even if it is in another file. + The CTRL-] command jumps to the tag of the word that is under the cursor. +This makes it easy to explore a tangle of C code. Suppose, for example, that +you are in the function "write_block". You can see that it calls +"write_line". But what does "write_line" do? By placing the cursor on the +call to "write_line" and pressing CTRL-], you jump to the definition of this +function. + The "write_line" function calls "write_char". You need to figure out what +it does. So you position the cursor over the call to "write_char" and press +CTRL-]. Now you are at the definition of "write_char". + + +-------------------------------------+ + |void write_block(char **s; int cnt) | + |{ | + | int i; | + | for (i = 0; i < cnt; ++i) | + | write_line(s[i]); | + |} | | + +-----------|-------------------------+ + | + CTRL-] | + | +----------------------------+ + +--> |void write_line(char *s) | + |{ | + | while (*s != 0) | + | write_char(*s++); | + |} | | + +--------|-------------------+ + | + CTRL-] | + | +------------------------------------+ + +--> |void write_char(char c) | + |{ | + | putchar((int)(unsigned char)c); | + |} | + +------------------------------------+ + +The ":tags" command shows the list of tags that you traversed through: + + :tags + # TO tag FROM line in file/text ~ + 1 1 write_line 8 write_block.c ~ + 2 1 write_char 7 write_line.c ~ + > ~ +> +Now to go back. The CTRL-T command goes to the preceding tag. In the example +above you get back to the "write_line" function, in the call to "write_char". + This command takes a count argument that indicates how many tags to jump +back. You have gone forward, and now back. Let's go forward again. The +following command goes to the tag on top of the list: > + + :tag + +You can prefix it with a count and jump forward that many tags. For example: +":3tag". CTRL-T also can be preceded with a count. + These commands thus allow you to go down a call tree with CTRL-] and back +up again with CTRL-T. Use ":tags" to find out where you are. + + +SPLIT WINDOWS + +The ":tag" command replaces the file in the current window with the one +containing the new function. But suppose you want to see not only the old +function but also the new one? You can split the window using the ":split" +command followed by the ":tag" command. Vim has a shorthand command that does +both: > + :stag tagname + +To split the current window and jump to the tag under the cursor use this +command: > + + CTRL-W ] + +If a count is specified, the new window will be that many lines high. + + +MORE TAGS FILES + +When you have files in many directories, you can create a tags file in each of +them. Vim will then only be able to jump to tags within that directory. + To find more tags files, set the 'tags' option to include all the relevant +tags files. Example: > + + :set tags=./tags,./../tags,./*/tags + +This finds a tags file in the same directory as the current file, one +directory level higher and in all subdirectories. + This is quite a number of tags files, but it may still not be enough. For +example, when editing a file in "~/proj/src", you will not find the tags file +"~/proj/sub/tags". For this situation Vim offers to search a whole directory +tree for tags files. Example: > + + :set tags=~/proj/**/tags + + +ONE TAGS FILE + +When Vim has to search many places for tags files, you can hear the disk +rattling. It may get a bit slow. In that case it's better to spend this +time while generating one big tags file. You might do this overnight. + This requires the Exuberant ctags program, mentioned above. It offers an +argument to search a whole directory tree: > + + cd ~/proj + ctags -R . + +The nice thing about this is that Exuberant ctags recognizes various file +types. Thus this doesn't work just for C and C++ programs, also for Eiffel +and even Vim scripts. See the ctags documentation to tune this. + Now you only need to tell Vim where your big tags file is: > + + :set tags=~/proj/tags + + +MULTIPLE MATCHES + +When a function is defined multiple times (or a method in several classes), +the ":tag" command will jump to the first one. If there is a match in the +current file, that one is used first. + You can now jump to other matches for the same tag with: > + + :tnext + +Repeat this to find further matches. If there are many, you can select which +one to jump to: > + + :tselect tagname + +Vim will present you with a list of choices: + + # pri kind tag file ~ + 1 F f mch_init os_amiga.c ~ + mch_init() ~ + 2 F f mch_init os_mac.c ~ + mch_init() ~ + 3 F f mch_init os_msdos.c ~ + mch_init(void) ~ + 4 F f mch_init os_riscos.c ~ + mch_init() ~ + Enter nr of choice ( to abort): ~ + +You can now enter the number (in the first column) of the match that you would +like to jump to. The information in the other columns give you a good idea of +where the match is defined. + +To move between the matching tags, these commands can be used: + + :tfirst go to first match + :[count]tprevious go to [count] previous match + :[count]tnext go to [count] next match + :tlast go to last match + +If [count] is omitted then one is used. + + +GUESSING TAG NAMES + +Command line completion is a good way to avoid typing a long tag name. Just +type the first bit and press : > + + :tag write_ + +You will get the first match. If it's not the one you want, press until +you find the right one. + Sometimes you only know part of the name of a function. Or you have many +tags that start with the same string, but end differently. Then you can tell +Vim to use a pattern to find the tag. + Suppose you want to jump to a tag that contains "block". First type +this: > + + :tag /block + +Now use command line completion: press . Vim will find all tags that +contain "block" and use the first match. + The "/" before a tag name tells Vim that what follows is not a literal tag +name, but a pattern. You can use all the items for search patterns here. For +example, suppose you want to select a tag that starts with "write_": > + + :tselect /^write_ + +The "^" specifies that the tag starts with "write_". Otherwise it would also +be found halfway a tag name. Similarly "$" at the end makes sure the pattern +matches until the end of a tag. + + +A TAGS BROWSER + +Since CTRL-] takes you to the definition of the identifier under the cursor, +you can use a list of identifier names as a table of contents. Here is an +example. + First create a list of identifiers (this requires Exuberant ctags): > + + ctags --c-types=f -f functions *.c + +Now start Vim without a file, and edit this file in Vim, in a vertically split +window: > + + vim + :vsplit functions + +The window contains a list of all the functions. There is some more stuff, +but you can ignore that. Do ":setlocal ts=99" to clean it up a bit. + In this window, define a mapping: > + + :nnoremap 0yew:tag " + +Move the cursor to the line that contains the function you want to go to. +Now press . Vim will go to the other window and jump to the selected +function. + + +RELATED ITEMS + +You can set 'ignorecase' to make case in tag names be ignored. + +The 'tagbsearch' option tells if the tags file is sorted or not. The default +is to assume a sorted tags file, which makes a tags search a lot faster, but +doesn't work if the tags file isn't sorted. + +The 'taglength' option can be used to tell Vim the number of significant +characters in a tag. + +When you use the SNiFF+ program, you can use the Vim interface to it |sniff|. +SNiFF+ is a commercial program. + +Cscope is a free program. It does not only find places where an identifier is +declared, but also where it is used. See |cscope|. + +============================================================================== +*29.2* The preview window + +When you edit code that contains a function call, you need to use the correct +arguments. To know what values to pass you can look at how the function is +defined. The tags mechanism works very well for this. Preferably the +definition is displayed in another window. For this the preview window can be +used. + To open a preview window to display the function "write_char": > + + :ptag write_char + +Vim will open a window, and jumps to the tag "write_char". Then it takes you +back to the original position. Thus you can continue typing without the need +to use a CTRL-W command. + If the name of a function appears in the text, you can get its definition +in the preview window with: > + + CTRL-W } + +There is a script that automatically displays the text where the word under +the cursor was defined. See |CursorHold-example|. + +To close the preview window use this command: > + + :pclose + +To edit a specific file in the preview window, use ":pedit". This can be +useful to edit a header file, for example: > + + :pedit defs.h + +Finally, ":psearch" can be used to find a word in the current file and any +included files and display the match in the preview window. This is +especially useful when using library functions, for which you do not have a +tags file. Example: > + + :psearch popen + +This will show the "stdio.h" file in the preview window, with the function +prototype for popen(): + + FILE *popen __P((const char *, const char *)); ~ + +You can specify the height of the preview window, when it is opened, with the +'previewheight' option. + +============================================================================== +*29.3* Moving through a program + +Since a program is structured, Vim can recognize items in it. Specific +commands can be used to move around. + C programs often contain constructs like this: + + #ifdef USE_POPEN ~ + fd = popen("ls", "r") ~ + #else ~ + fd = fopen("tmp", "w") ~ + #endif ~ + +But then much longer, and possibly nested. Position the cursor on the +"#ifdef" and press %. Vim will jump to the "#else". Pressing % again takes +you to the "#endif". Another % takes you to the "#ifdef" again. + When the construct is nested, Vim will find the matching items. This is a +good way to check if you didn't forget an "#endif". + When you are somewhere inside a "#if" - "#endif", you can jump to the start +of it with: > + + [# + +If you are not after a "#if" or "#ifdef" Vim will beep. To jump forward to +the next "#else" or "#endif" use: > + + ]# + +These two commands skip any "#if" - "#endif" blocks that they encounter. +Example: + + #if defined(HAS_INC_H) ~ + a = a + inc(); ~ + # ifdef USE_THEME ~ + a += 3; ~ + # endif ~ + set_width(a); ~ + +With the cursor in the last line, "[#" moves to the first line. The "#ifdef" +- "#endif" block in the middle is skipped. + + +MOVING IN CODE BLOCKS + +In C code blocks are enclosed in {}. These can get pretty long. To move to +the start of the outer block use the "[[" command. Use "][" to find the end. +This assumes that the "{" and "}" are in the first column. + The "[{" command moves to the start of the current block. It skips over +pairs of {} at the same level. "]}" jumps to the end. + An overview: + + function(int a) + +-> { + | if (a) + | +-> { + [[ | | for (;;) --+ + | | +-> { | + | [{ | | foo(32); | --+ + | | [{ | if (bar(a)) --+ | ]} | + +-- | +-- break; | ]} | | + | } <-+ | | ][ + +-- foobar(a) | | + } <-+ | + } <-+ + +When writing C++ or Java, the outer {} block is for the class. The next level +of {} is for a method. When somewhere inside a class use "[m" to find the +previous start of a method. "]m" finds the next start of a method. + +Additionally, "[]" moves backward to the end of a function and "]]" moves +forward to the start of the next function. The end of a function is defined +by a "}" in the first column. + + int func1(void) + { + return 1; + +----------> } + | + [] | int func2(void) + | +-> { + | [[ | if (flag) + start +-- +-- return flag; + | ][ | return 2; + | +-> } + ]] | + | int func3(void) + +----------> { + return 3; + } + +Don't forget you can also use "%" to move between matching (), {} and []. +That also works when they are many lines apart. + + +MOVING IN BRACES + +The "[(" and "])" commands work similar to "[{" and "]}", except that they +work on () pairs instead of {} pairs. +> + [( +< <-------------------------------- + <------- + if (a == b && (c == d || (e > f)) && x > y) ~ + --------------> + --------------------------------> > + ]) + +MOVING IN COMMENTS + +To move back to the start of a comment use "[/". Move forward to the end of a +comment with "]/". This only works for /* - */ comments. + + +-> +-> /* + | [/ | * A comment about --+ + [/ | +-- * wonderful life. | ]/ + | */ <-+ + | + +-- foo = bar * 3; --+ + | ]/ + /* a short comment */ <-+ + +============================================================================== +*29.4* Finding global identifiers + +You are editing a C program and wonder if a variable is declared as "int" or +"unsigned". A quick way to find this is with the "[I" command. + Suppose the cursor is on the word "column". Type: > + + [I + +Vim will list the matching lines it can find. Not only in the current file, +but also in all included files (and files included in them, etc.). The result +looks like this: + + structs.h ~ + 1: 29 unsigned column; /* column number */ ~ + +The advantage over using tags or the preview window is that included files are +searched. In most cases this results in the right declaration to be found. +Also when the tags file is out of date. Also when you don't have tags for the +included files. + However, a few things must be right for "[I" to do its work. First of all, +the 'include' option must specify how a file is included. The default value +works for C and C++. For other languages you will have to change it. + + +LOCATING INCLUDED FILES + + Vim will find included files in the places specified with the 'path' +option. If a directory is missing, some include files will not be found. You +can discover this with this command: > + + :checkpath + +It will list the include files that could not be found. Also files included +by the files that could be found. An example of the output: + + --- Included files not found in path --- ~ + ~ + vim.h --> ~ + ~ + ~ + +The "io.h" file is included by the current file and can't be found. "vim.h" +can be found, thus ":checkpath" goes into this file and checks what it +includes. The "functions.h" and "clib/exec_protos.h" files, included by +"vim.h" are not found. + + Note: + Vim is not a compiler. It does not recognize "#ifdef" statements. + This means every "#include" statement is used, also when it comes + after "#if NEVER". + +To fix the files that could not be found, add a directory to the 'path' +option. A good place to find out about this is the Makefile. Look out for +lines that contain "-I" items, like "-I/usr/local/X11". To add this directory +use: > + + :set path+=/usr/local/X11 + +When there are many subdirectories, you can use the "*" wildcard. Example: > + + :set path+=/usr/*/include + +This would find files in "/usr/local/include" as well as "/usr/X11/include". + +When working on a project with a whole nested tree of included files, the "**" +items is useful. This will search down in all subdirectories. Example: > + + :set path+=/projects/invent/**/include + +This will find files in the directories: + + /projects/invent/include ~ + /projects/invent/main/include ~ + /projects/invent/main/os/include ~ + etc. + +There are even more possibilities. Check out the 'path' option for info. + If you want to see which included files are actually found, use this +command: > + + :checkpath! + +You will get a (very long) list of included files, the files they include, and +so on. To shorten the list a bit, Vim shows "(Already listed)" for files that +were found before and doesn't list the included files in there again. + + +JUMPING TO A MATCH + +"[I" produces a list with only one line of text. When you want to have a +closer look at the first item, you can jump to that line with the command: > + + [ + +You can also use "[ CTRL-I", since CTRL-I is the same as pressing . + +The list that "[I" produces has a number at the start of each line. When you +want to jump to another item than the first one, type the number first: > + + 3[ + +Will jump to the third item in the list. Remember that you can use CTRL-O to +jump back to where you started from. + + +RELATED COMMANDS + + [i only lists the first match + ]I only lists items below the cursor + ]i only lists the first item below the cursor + + +FINDING DEFINED IDENTIFIERS + +The "[I" command finds any identifier. To find only macros, defined with +"#define" use: > + + [D + +Again, this searches in included files. The 'define' option specifies what a +line looks like that defines the items for "[D". You could change it to make +it work with other languages than C or C++. + The commands related to "[D" are: + + [d only lists the first match + ]D only lists items below the cursor + ]d only lists the first item below the cursor + +============================================================================== +*29.5* Finding local identifiers + +The "[I" command searches included files. To search in the current file only, +and jump to the first place where the word under the cursor is used: > + + gD + +Hint: Goto Definition. This command is very useful to find a variable or +function that was declared locally ("static", in C terms). Example (cursor on +"counter"): + + +-> static int counter = 0; + | + | int get_counter(void) + gD | { + | ++counter; + +-- return counter; + } + +To restrict the search even further, and look only in the current function, +use this command: > + + gd + +This will go back to the start of the current function and find the first +occurrence of the word under the cursor. Actually, it searches backwards to +an empty line above a "{" in the first column. From there it searches forward +for the identifier. Example (cursor on "idx"): + + int find_entry(char *name) + { + +-> int idx; + | + gd | for (idx = 0; idx < table_len; ++idx) + | if (strcmp(table[idx].name, name) == 0) + +-- return idx; + } + +============================================================================== + +Next chapter: |usr_30.txt| Editing programs + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime_tos/doc/usr_30.txt b/runtime_tos/doc/usr_30.txt new file mode 100644 index 00000000000000..b2be512980adb7 --- /dev/null +++ b/runtime_tos/doc/usr_30.txt @@ -0,0 +1,643 @@ +*usr_30.txt* For Vim version 7.4. Last change: 2007 Nov 10 + + VIM USER MANUAL - by Bram Moolenaar + + Editing programs + + +Vim has various commands that aid in writing computer programs. Compile a +program and directly jump to reported errors. Automatically set the indent +for many languages and format comments. + +|30.1| Compiling +|30.2| Indenting C files +|30.3| Automatic indenting +|30.4| Other indenting +|30.5| Tabs and spaces +|30.6| Formatting comments + + Next chapter: |usr_31.txt| Exploiting the GUI + Previous chapter: |usr_29.txt| Moving through programs +Table of contents: |usr_toc.txt| + +============================================================================== +*30.1* Compiling + +Vim has a set of so called "quickfix" commands. They enable you to compile a +program from within Vim and then go through the errors generated and fix them +(hopefully). You can then recompile and fix any new errors that are found +until finally your program compiles without any error. + +The following command runs the program "make" (supplying it with any argument +you give) and captures the results: > + + :make {arguments} + +If errors were generated, they are captured and the editor positions you where +the first error occurred. + Take a look at an example ":make" session. (Typical :make sessions generate +far more errors and fewer stupid ones.) After typing ":make" the screen looks +like this: + + :!make | &tee /tmp/vim215953.err ~ + gcc -g -Wall -o prog main.c sub.c ~ + main.c: In function 'main': ~ + main.c:6: too many arguments to function 'do_sub' ~ + main.c: At top level: ~ + main.c:10: parse error before '}' ~ + make: *** [prog] Error 1 ~ + + 2 returned ~ + "main.c" 11L, 111C ~ + (3 of 6): too many arguments to function 'do_sub' ~ + Press ENTER or type command to continue ~ + +From this you can see that you have errors in the file "main.c". When you +press , Vim displays the file "main.c", with the cursor positioned on +line 6, the first line with an error. You did not need to specify the file or +the line number, Vim knew where to go by looking in the error messages. + + +---------------------------------------------------+ + |int main() | + |{ | + | int i=3; | + cursor -> | do_sub("foo"); | + | ++i; | + | return (0); | + |} | + |} | + | ~ | + |(3 of 12): too many arguments to function 'do_sub' | + +---------------------------------------------------+ + +The following command goes to where the next error occurs: > + + :cnext + +Vim jumps to line 10, the last line in the file, where there is an extra '}'. + When there is not enough room, Vim will shorten the error message. To see +the whole message use: > + + :cc + +You can get an overview of all the error messages with the ":clist" command. +The output looks like this: > + + :clist +< 3 main.c: 6:too many arguments to function 'do_sub' ~ + 5 main.c: 10:parse error before '}' ~ + +Only the lines where Vim recognized a file name and line number are listed +here. It assumes those are the interesting lines and the rest is just boring +messages. However, sometimes unrecognized lines do contain something you want +to see. Output from the linker, for example, about an undefined function. +To see all the messages add a "!" to the command: > + + :clist! +< 1 gcc -g -Wall -o prog main.c sub.c ~ + 2 main.c: In function 'main': ~ + 3 main.c:6: too many arguments to function 'do_sub' ~ + 4 main.c: At top level: ~ + 5 main.c:10: parse error before '}' ~ + 6 make: *** [prog] Error 1 ~ + +Vim will highlight the current error. To go back to the previous error, use: +> + :cprevious + +Other commands to move around in the error list: + + :cfirst to first error + :clast to last error + :cc 3 to error nr 3 + + +USING ANOTHER COMPILER + +The name of the program to run when the ":make" command is executed is defined +by the 'makeprg' option. Usually this is set to "make", but Visual C++ users +should set this to "nmake" by executing the following command: > + + :set makeprg=nmake + +You can also include arguments in this option. Special characters need to +be escaped with a backslash. Example: > + + :set makeprg=nmake\ -f\ project.mak + +You can include special Vim keywords in the command specification. The % +character expands to the name of the current file. So if you execute the +command: > + :set makeprg=make\ %:S + +When you are editing main.c, then ":make" executes the following command: > + + make main.c + +This is not too useful, so you will refine the command a little and use the :r +(root) modifier: > + + :set makeprg=make\ %:r:S.o + +Now the command executed is as follows: > + + make main.o + +More about these modifiers here: |filename-modifiers|. + + +OLD ERROR LISTS + +Suppose you ":make" a program. There is a warning message in one file and an +error message in another. You fix the error and use ":make" again to check if +it was really fixed. Now you want to look at the warning message. It doesn't +show up in the last error list, since the file with the warning wasn't +compiled again. You can go back to the previous error list with: > + + :colder + +Then use ":clist" and ":cc {nr}" to jump to the place with the warning. + To go forward to the next error list: > + + :cnewer + +Vim remembers ten error lists. + + +SWITCHING COMPILERS + +You have to tell Vim what format the error messages are that your compiler +produces. This is done with the 'errorformat' option. The syntax of this +option is quite complicated and it can be made to fit almost any compiler. +You can find the explanation here: |errorformat|. + +You might be using various different compilers. Setting the 'makeprg' option, +and especially the 'errorformat' each time is not easy. Vim offers a simple +method for this. For example, to switch to using the Microsoft Visual C++ +compiler: > + + :compiler msvc + +This will find the Vim script for the "msvc" compiler and set the appropriate +options. + You can write your own compiler files. See |write-compiler-plugin|. + + +OUTPUT REDIRECTION + +The ":make" command redirects the output of the executed program to an error +file. How this works depends on various things, such as the 'shell'. If your +":make" command doesn't capture the output, check the 'makeef' and +'shellpipe' options. The 'shellquote' and 'shellxquote' options might also +matter. + +In case you can't get ":make" to redirect the file for you, an alternative is +to compile the program in another window and redirect the output into a file. +Then have Vim read this file with: > + + :cfile {filename} + +Jumping to errors will work like with the ":make" command. + +============================================================================== +*30.2* Indenting C style text + +A program is much easier to understand when the lines have been properly +indented. Vim offers various ways to make this less work. For C or C style +programs like Java or C++, set the 'cindent' option. Vim knows a lot about C +programs and will try very hard to automatically set the indent for you. Set +the 'shiftwidth' option to the amount of spaces you want for a deeper level. +Four spaces will work fine. One ":set" command will do it: > + + :set cindent shiftwidth=4 + +With this option enabled, when you type something such as "if (x)", the next +line will automatically be indented an additional level. + + if (flag) + Automatic indent ---> do_the_work(); + Automatic unindent <-- if (other_flag) { + Automatic indent ---> do_file(); + keep indent do_some_more(); + Automatic unindent <-- } + +When you type something in curly braces ({}), the text will be indented at the +start and unindented at the end. The unindenting will happen after typing the +'}', since Vim can't guess what you are going to type. + +One side effect of automatic indentation is that it helps you catch errors in +your code early. When you type a } to finish a function, only to find that +the automatic indentation gives it more indent than what you expected, there +is probably a } missing. Use the "%" command to find out which { matches the +} you typed. + A missing ) and ; also cause extra indent. Thus if you get more white +space than you would expect, check the preceding lines. + +When you have code that is badly formatted, or you inserted and deleted lines, +you need to re-indent the lines. The "=" operator does this. The simplest +form is: > + + == + +This indents the current line. Like with all operators, there are three ways +to use it. In Visual mode "=" indents the selected lines. A useful text +object is "a{". This selects the current {} block. Thus, to re-indent the +code block the cursor is in: > + + =a{ + +I you have really badly indented code, you can re-indent the whole file with: +> + gg=G + +However, don't do this in files that have been carefully indented manually. +The automatic indenting does a good job, but in some situations you might want +to overrule it. + + +SETTING INDENT STYLE + +Different people have different styles of indentation. By default Vim does a +pretty good job of indenting in a way that 90% of programmers do. There are +different styles, however; so if you want to, you can customize the +indentation style with the 'cinoptions' option. + By default 'cinoptions' is empty and Vim uses the default style. You can +add various items where you want something different. For example, to make +curly braces be placed like this: + + if (flag) ~ + { ~ + i = 8; ~ + j = 0; ~ + } ~ + +Use this command: > + + :set cinoptions+={2 + +There are many of these items. See |cinoptions-values|. + +============================================================================== +*30.3* Automatic indenting + +You don't want to switch on the 'cindent' option manually every time you edit +a C file. This is how you make it work automatically: > + + :filetype indent on + +Actually, this does a lot more than switching on 'cindent' for C files. First +of all, it enables detecting the type of a file. That's the same as what is +used for syntax highlighting. + When the filetype is known, Vim will search for an indent file for this +type of file. The Vim distribution includes a number of these for various +programming languages. This indent file will then prepare for automatic +indenting specifically for this file. + +If you don't like the automatic indenting, you can switch it off again: > + + :filetype indent off + +If you don't like the indenting for one specific type of file, this is how you +avoid it. Create a file with just this one line: > + + :let b:did_indent = 1 + +Now you need to write this in a file with a specific name: + + {directory}/indent/{filetype}.vim + +The {filetype} is the name of the file type, such as "cpp" or "java". You can +see the exact name that Vim detected with this command: > + + :set filetype + +In this file the output is: + + filetype=help ~ + +Thus you would use "help" for {filetype}. + For the {directory} part you need to use your runtime directory. Look at +the output of this command: > + + set runtimepath + +Now use the first item, the name before the first comma. Thus if the output +looks like this: + + runtimepath=~/.vim,/usr/local/share/vim/vim60/runtime,~/.vim/after ~ + +You use "~/.vim" for {directory}. Then the resulting file name is: + + ~/.vim/indent/help.vim ~ + +Instead of switching the indenting off, you could write your own indent file. +How to do that is explained here: |indent-expression|. + +============================================================================== +*30.4* Other indenting + +The most simple form of automatic indenting is with the 'autoindent' option. +It uses the indent from the previous line. A bit smarter is the 'smartindent' +option. This is useful for languages where no indent file is available. +'smartindent' is not as smart as 'cindent', but smarter than 'autoindent'. + With 'smartindent' set, an extra level of indentation is added for each { +and removed for each }. An extra level of indentation will also be added for +any of the words in the 'cinwords' option. Lines that begin with # are +treated specially: all indentation is removed. This is done so that +preprocessor directives will all start in column 1. The indentation is +restored for the next line. + + +CORRECTING INDENTS + +When you are using 'autoindent' or 'smartindent' to get the indent of the +previous line, there will be many times when you need to add or remove one +'shiftwidth' worth of indent. A quick way to do this is using the CTRL-D and +CTRL-T commands in Insert mode. + For example, you are typing a shell script that is supposed to look like +this: + + if test -n a; then ~ + echo a ~ + echo "-------" ~ + fi ~ + +Start off by setting these options: > + + :set autoindent shiftwidth=3 + +You start by typing the first line, and the start of the second line: + + if test -n a; then ~ + echo ~ + +Now you see that you need an extra indent. Type CTRL-T. The result: + + if test -n a; then ~ + echo ~ + +The CTRL-T command, in Insert mode, adds one 'shiftwidth' to the indent, no +matter where in the line you are. + You continue typing the second line, and the third line. This time +the indent is OK. Then and the last line. Now you have this: + + if test -n a; then ~ + echo a ~ + echo "-------" ~ + fi ~ + +To remove the superfluous indent in the last line press CTRL-D. This deletes +one 'shiftwidth' worth of indent, no matter where you are in the line. + When you are in Normal mode, you can use the ">>" and "<<" commands to +shift lines. ">" and "<" are operators, thus you have the usual three ways to +specify the lines you want to indent. A useful combination is: > + + >i{ + +This adds one indent to the current block of lines, inside {}. The { and } +lines themselves are left unmodified. ">a{" includes them. In this example +the cursor is on "printf": + + original text after ">i{" after ">a{" + + if (flag) if (flag) if (flag) ~ + { { { ~ + printf("yes"); printf("yes"); printf("yes"); ~ + flag = 0; flag = 0; flag = 0; ~ + } } } ~ + +============================================================================== +*30.5* Tabs and spaces + +'tabstop' is set to eight by default. Although you can change it, you quickly +run into trouble later. Other programs won't know what tabstop value you +used. They probably use the default value of eight, and your text suddenly +looks very different. Also, most printers use a fixed tabstop value of eight. +Thus it's best to keep 'tabstop' alone. (If you edit a file which was written +with a different tabstop setting, see |25.3| for how to fix that.) + For indenting lines in a program, using a multiple of eight spaces makes +you quickly run into the right border of the window. Using a single space +doesn't provide enough visual difference. Many people prefer to use four +spaces, a good compromise. + Since a is eight spaces and you want to use an indent of four spaces, +you can't use a character to make your indent. There are two ways to +handle this: + +1. Use a mix of and space characters. Since a takes the place of + eight spaces, you have fewer characters in your file. Inserting a + is quicker than eight spaces. Backspacing works faster as well. + +2. Use spaces only. This avoids the trouble with programs that use a + different tabstop value. + +Fortunately, Vim supports both methods quite well. + + +SPACES AND TABS + +If you are using a combination of tabs and spaces, you just edit normally. +The Vim defaults do a fine job of handling things. + You can make life a little easier by setting the 'softtabstop' option. +This option tells Vim to make the key look and feel as if tabs were set +at the value of 'softtabstop', but actually use a combination of tabs and +spaces. + After you execute the following command, every time you press the key +the cursor moves to the next 4-column boundary: > + + :set softtabstop=4 + +When you start in the first column and press , you get 4 spaces inserted +in your text. The second time, Vim takes out the 4 spaces and puts in a +(thus taking you to column 8). Thus Vim uses as many s as possible, and +then fills up with spaces. + When backspacing it works the other way around. A will always delete +the amount specified with 'softtabstop'. Then s are used as many as +possible and spaces to fill the gap. + The following shows what happens pressing a few times, and then using +. A "." stands for a space and "------->" for a . + + type result ~ + .... + -------> + ------->.... + -------> + .... + +An alternative is to use the 'smarttab' option. When it's set, Vim uses +'shiftwidth' for a typed in the indent of a line, and a real when +typed after the first non-blank character. However, doesn't work like +with 'softtabstop'. + + +JUST SPACES + +If you want absolutely no tabs in your file, you can set the 'expandtab' +option: > + + :set expandtab + +When this option is set, the key inserts a series of spaces. Thus you +get the same amount of white space as if a character was inserted, but +there isn't a real character in your file. + The backspace key will delete each space by itself. Thus after typing one + you have to press the key up to eight times to undo it. If you are +in the indent, pressing CTRL-D will be a lot quicker. + + +CHANGING TABS IN SPACES (AND BACK) + +Setting 'expandtab' does not affect any existing tabs. In other words, any +tabs in the document remain tabs. If you want to convert tabs to spaces, use +the ":retab" command. Use these commands: > + + :set expandtab + :%retab + +Now Vim will have changed all indents to use spaces instead of tabs. However, +all tabs that come after a non-blank character are kept. If you want these to +be converted as well, add a !: > + + :%retab! + +This is a little bit dangerous, because it can also change tabs inside a +string. To check if these exist, you could use this: > + + /"[^"\t]*\t[^"]*" + +It's recommended not to use hard tabs inside a string. Replace them with +"\t" to avoid trouble. + +The other way around works just as well: > + + :set noexpandtab + :%retab! + +============================================================================== +*30.6* Formatting comments + +One of the great things about Vim is that it understands comments. You can +ask Vim to format a comment and it will do the right thing. + Suppose, for example, that you have the following comment: + + /* ~ + * This is a test ~ + * of the text formatting. ~ + */ ~ + +You then ask Vim to format it by positioning the cursor at the start of the +comment and type: > + + gq]/ + +"gq" is the operator to format text. "]/" is the motion that takes you to the +end of a comment. The result is: + + /* ~ + * This is a test of the text formatting. ~ + */ ~ + +Notice that Vim properly handled the beginning of each line. + An alternative is to select the text that is to be formatted in Visual mode +and type "gq". + +To add a new line to the comment, position the cursor on the middle line and +press "o". The result looks like this: + + /* ~ + * This is a test of the text formatting. ~ + * ~ + */ ~ + +Vim has automatically inserted a star and a space for you. Now you can type +the comment text. When it gets longer than 'textwidth', Vim will break the +line. Again, the star is inserted automatically: + + /* ~ + * This is a test of the text formatting. ~ + * Typing a lot of text here will make Vim ~ + * break ~ + */ ~ + +For this to work some flags must be present in 'formatoptions': + + r insert the star when typing in Insert mode + o insert the star when using "o" or "O" in Normal mode + c break comment text according to 'textwidth' + +See |fo-table| for more flags. + + +DEFINING A COMMENT + +The 'comments' option defines what a comment looks like. Vim distinguishes +between a single-line comment and a comment that has a different start, end +and middle part. + Many single-line comments start with a specific character. In C++ // is +used, in Makefiles #, in Vim scripts ". For example, to make Vim understand +C++ comments: > + + :set comments=:// + +The colon separates the flags of an item from the text by which the comment is +recognized. The general form of an item in 'comments' is: + + {flags}:{text} + +The {flags} part can be empty, as in this case. + Several of these items can be concatenated, separated by commas. This +allows recognizing different types of comments at the same time. For example, +let's edit an e-mail message. When replying, the text that others wrote is +preceded with ">" and "!" characters. This command would work: > + + :set comments=n:>,n:! + +There are two items, one for comments starting with ">" and one for comments +that start with "!". Both use the flag "n". This means that these comments +nest. Thus a line starting with ">" may have another comment after the ">". +This allows formatting a message like this: + + > ! Did you see that site? ~ + > ! It looks really great. ~ + > I don't like it. The ~ + > colors are terrible. ~ + What is the URL of that ~ + site? ~ + +Try setting 'textwidth' to a different value, e.g., 80, and format the text by +Visually selecting it and typing "gq". The result is: + + > ! Did you see that site? It looks really great. ~ + > I don't like it. The colors are terrible. ~ + What is the URL of that site? ~ + +You will notice that Vim did not move text from one type of comment to +another. The "I" in the second line would have fit at the end of the first +line, but since that line starts with "> !" and the second line with ">", Vim +knows that this is a different kind of comment. + + +A THREE PART COMMENT + +A C comment starts with "/*", has "*" in the middle and "*/" at the end. The +entry in 'comments' for this looks like this: > + + :set comments=s1:/*,mb:*,ex:*/ + +The start is defined with "s1:/*". The "s" indicates the start of a +three-piece comment. The colon separates the flags from the text by which the +comment is recognized: "/*". There is one flag: "1". This tells Vim that the +middle part has an offset of one space. + The middle part "mb:*" starts with "m", which indicates it is a middle +part. The "b" flag means that a blank must follow the text. Otherwise Vim +would consider text like "*pointer" also to be the middle of a comment. + The end part "ex:*/" has the "e" for identification. The "x" flag has a +special meaning. It means that after Vim automatically inserted a star, +typing / will remove the extra space. + +For more details see |format-comments|. + +============================================================================== + +Next chapter: |usr_31.txt| Exploiting the GUI + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime_tos/doc/usr_31.txt b/runtime_tos/doc/usr_31.txt new file mode 100644 index 00000000000000..550564e10c2cca --- /dev/null +++ b/runtime_tos/doc/usr_31.txt @@ -0,0 +1,272 @@ +*usr_31.txt* For Vim version 7.4. Last change: 2007 May 08 + + VIM USER MANUAL - by Bram Moolenaar + + Exploiting the GUI + + +Vim works well in a terminal, but the GUI has a few extra items. A file +browser can be used for commands that use a file. A dialog to make a choice +between alternatives. Use keyboard shortcuts to access menu items quickly. + +|31.1| The file browser +|31.2| Confirmation +|31.3| Menu shortcuts +|31.4| Vim window position and size +|31.5| Various + + Next chapter: |usr_32.txt| The undo tree + Previous chapter: |usr_30.txt| Editing programs +Table of contents: |usr_toc.txt| + +============================================================================== +*31.1* The file browser + +When using the File/Open... menu you get a file browser. This makes it easier +to find the file you want to edit. But what if you want to split a window to +edit another file? There is no menu entry for this. You could first use +Window/Split and then File/Open..., but that's more work. + Since you are typing most commands in Vim, opening the file browser with a +typed command is possible as well. To make the split command use the file +browser, prepend "browse": > + + :browse split + +Select a file and then the ":split" command will be executed with it. If you +cancel the file dialog nothing happens, the window isn't split. + You can also specify a file name argument. This is used to tell the file +browser where to start. Example: > + + :browse split /etc + +The file browser will pop up, starting in the directory "/etc". + +The ":browse" command can be prepended to just about any command that opens a +file. + If no directory is specified, Vim will decide where to start the file +browser. By default it uses the same directory as the last time. Thus when +you used ":browse split" and selected a file in "/usr/local/share", the next +time you use a ":browse" it will start in "/usr/local/share" again. + This can be changed with the 'browsedir' option. It can have one of three +values: + + last Use the last directory browsed (default) + buffer Use the same directory as the current buffer + current use the current directory + +For example, when you are in the directory "/usr", editing the file +"/usr/local/share/readme", then the command: > + + :set browsedir=buffer + :browse edit + +Will start the browser in "/usr/local/share". Alternatively: > + + :set browsedir=current + :browse edit + +Will start the browser in "/usr". + + Note: + To avoid using the mouse, most file browsers offer using key presses + to navigate. Since this is different for every system, it is not + explained here. Vim uses a standard browser when possible, your + system documentation should contain an explanation on the keyboard + shortcuts somewhere. + +When you are not using the GUI version, you could use the file explorer window +to select files like in a file browser. However, this doesn't work for the +":browse" command. See |netrw-browse|. + +============================================================================== +*31.2* Confirmation + +Vim protects you from accidentally overwriting a file and other ways to lose +changes. If you do something that might be a bad thing to do, Vim produces an +error message and suggests appending ! if you really want to do it. + To avoid retyping the command with the !, you can make Vim give you a +dialog. You can then press "OK" or "Cancel" to tell Vim what you want. + For example, you are editing a file and made changes to it. You start +editing another file with: > + + :confirm edit foo.txt + +Vim will pop up a dialog that looks something like this: + + +-----------------------------------+ + | | + | ? Save changes to "bar.txt"? | + | | + | YES NO CANCEL | + +-----------------------------------+ + +Now make your choice. If you do want to save the changes, select "YES". If +you want to lose the changes for ever: "NO". If you forgot what you were +doing and want to check what really changed use "CANCEL". You will be back in +the same file, with the changes still there. + +Just like ":browse", the ":confirm" command can be prepended to most commands +that edit another file. They can also be combined: > + + :confirm browse edit + +This will produce a dialog when the current buffer was changed. Then it will +pop up a file browser to select the file to edit. + + Note: + In the dialog you can use the keyboard to select the choice. + Typically the key and the cursor keys change the choice. + Pressing selects the choice. This depends on the system + though. + +When you are not using the GUI, the ":confirm" command works as well. Instead +of popping up a dialog, Vim will print the message at the bottom of the Vim +window and ask you to press a key to make a choice. > + + :confirm edit main.c +< Save changes to "Untitled"? ~ + [Y]es, (N)o, (C)ancel: ~ + +You can now press the single key for the choice. You don't have to press +, unlike other typing on the command line. + +============================================================================== +*31.3* Menu shortcuts + +The keyboard is used for all Vim commands. The menus provide a simple way to +select commands, without knowing what they are called. But you have to move +your hand from the keyboard and grab the mouse. + Menus can often be selected with keys as well. This depends on your +system, but most often it works this way. Use the key in combination +with the underlined letter of a menu. For example, ( and w) pops +up the Window menu. + In the Window menu, the "split" item has the p underlined. To select it, +let go of the key and press p. + +After the first selection of a menu with the key, you can use the cursor +keys to move through the menus. selects a submenu and closes +it. also closes a menu. selects a menu item. + +There is a conflict between using the key to select menu items, and +using key combinations for mappings. The 'winaltkeys' option tells Vim +what it should do with the key. + The default value "menu" is the smart choice: If the key combination is a +menu shortcut it can't be mapped. All other keys are available for mapping. + The value "no" doesn't use any keys for the menus. Thus you must use +the mouse for the menus, and all keys can be mapped. + The value "yes" means that Vim will use any keys for the menus. Some + key combinations may also do other things than selecting a menu. + +============================================================================== +*31.4* Vim window position and size + +To see the current Vim window position on the screen use: > + + :winpos + +This will only work in the GUI. The output may look like this: + + Window position: X 272, Y 103 ~ + +The position is given in screen pixels. Now you can use the numbers to move +Vim somewhere else. For example, to move it to the left a hundred pixels: > + + :winpos 172 103 +< + Note: + There may be a small offset between the reported position and where + the window moves. This is because of the border around the window. + This is added by the window manager. + +You can use this command in your startup script to position the window at a +specific position. + +The size of the Vim window is computed in characters. Thus this depends on +the size of the font being used. You can see the current size with this +command: > + + :set lines columns + +To change the size set the 'lines' and/or 'columns' options to a new value: > + + :set lines=50 + :set columns=80 + +Obtaining the size works in a terminal just like in the GUI. Setting the size +is not possible in most terminals. + +You can start the X-Windows version of gvim with an argument to specify the +size and position of the window: > + + gvim -geometry {width}x{height}+{x_offset}+{y_offset} + +{width} and {height} are in characters, {x_offset} and {y_offset} are in +pixels. Example: > + + gvim -geometry 80x25+100+300 + +============================================================================== +*31.5* Various + +You can use gvim to edit an e-mail message. In your e-mail program you must +select gvim to be the editor for messages. When you try that, you will +see that it doesn't work: The mail program thinks that editing is finished, +while gvim is still running! + What happens is that gvim disconnects from the shell it was started in. +That is fine when you start gvim in a terminal, so that you can do other work +in that terminal. But when you really want to wait for gvim to finish, you +must prevent it from disconnecting. The "-f" argument does this: > + + gvim -f file.txt + +The "-f" stands for foreground. Now Vim will block the shell it was started +in until you finish editing and exit. + + +DELAYED START OF THE GUI + +On Unix it's possible to first start Vim in a terminal. That's useful if you +do various tasks in the same shell. If you are editing a file and decide you +want to use the GUI after all, you can start it with: > + + :gui + +Vim will open the GUI window and no longer use the terminal. You can continue +using the terminal for something else. The "-f" argument is used here to run +the GUI in the foreground. You can also use ":gui -f". + + +THE GVIM STARTUP FILE + +When gvim starts, it reads the gvimrc file. That's similar to the vimrc file +used when starting Vim. The gvimrc file can be used for settings and commands +that are only to be used when the GUI is going to be started. For example, +you can set the 'lines' option to set a different window size: > + + :set lines=55 + +You don't want to do this in a terminal, since its size is fixed (except for +an xterm that supports resizing). + The gvimrc file is searched for in the same locations as the vimrc file. +Normally its name is "~/.gvimrc" for Unix and "$VIM/_gvimrc" for MS-Windows. +The $MYGVIMRC environment variable is set to it, thus you can use this command +to edit the file, if you have one: > + + :edit $MYGVIMRC +< + If for some reason you don't want to use the normal gvimrc file, you can +specify another one with the "-U" argument: > + + gvim -U thisrc ... + +That allows starting gvim for different kinds of editing. You could set +another font size, for example. + To completely skip reading a gvimrc file: > + + gvim -U NONE ... + +============================================================================== + +Next chapter: |usr_32.txt| The undo tree + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime_tos/doc/usr_32.txt b/runtime_tos/doc/usr_32.txt new file mode 100644 index 00000000000000..fd58f2d5177b8c --- /dev/null +++ b/runtime_tos/doc/usr_32.txt @@ -0,0 +1,180 @@ +*usr_32.txt* For Vim version 7.4. Last change: 2010 Jul 20 + + VIM USER MANUAL - by Bram Moolenaar + + The undo tree + + +Vim provides multi-level undo. If you undo a few changes and then make a new +change you create a branch in the undo tree. This text is about moving +through the branches. + +|32.1| Undo up to a file write +|32.2| Numbering changes +|32.3| Jumping around the tree +|32.4| Time travelling + + Next chapter: |usr_40.txt| Make new commands + Previous chapter: |usr_31.txt| Exploiting the GUI +Table of contents: |usr_toc.txt| + +============================================================================== +*32.1* Undo up to a file write + +Sometimes you make several changes, and then discover you want to go back to +when you have last written the file. You can do that with this command: > + + :earlier 1f + +The "f" stands for "file" here. + +You can repeat this command to go further back in the past. Or use a count +different from 1 to go back faster. + +If you go back too far, go forward again with: > + + :later 1f + +Note that these commands really work in time sequence. This matters if you +made changes after undoing some changes. It's explained in the next section. + +Also note that we are talking about text writes here. For writing the undo +information in a file see |undo-persistence|. + +============================================================================== +*32.2* Numbering changes + +In section |02.5| we only discussed one line of undo/redo. But it is also +possible to branch off. This happens when you undo a few changes and then +make a new change. The new changes become a branch in the undo tree. + +Let's start with the text "one". The first change to make is to append +" too". And then move to the first 'o' and change it into 'w'. We then have +two changes, numbered 1 and 2, and three states of the text: + + one ~ + | + change 1 + | + one too ~ + | + change 2 + | + one two ~ + +If we now undo one change, back to "one too", and change "one" to "me" we +create a branch in the undo tree: + + one ~ + | + change 1 + | + one too ~ + / \ + change 2 change 3 + | | + one two me too ~ + +You can now use the |u| command to undo. If you do this twice you get to +"one". Use |CTRL-R| to redo, and you will go to "one too". One more |CTRL-R| +takes you to "me too". Thus undo and redo go up and down in the tree, using +the branch that was last used. + +What matters here is the order in which the changes are made. Undo and redo +are not considered changes in this context. After each change you have a new +state of the text. + +Note that only the changes are numbered, the text shown in the tree above has +no identifier. They are mostly referred to by the number of the change above +it. But sometimes by the number of one of the changes below it, especially +when moving up in the tree, so that you know which change was just undone. + +============================================================================== +*32.3* Jumping around the tree + +So how do you get to "one two" now? You can use this command: > + + :undo 2 + +The text is now "one two", you are below change 2. You can use the |:undo| +command to jump to below any change in the tree. + +Now make another change: change "one" to "not": + + one ~ + | + change 1 + | + one too ~ + / \ + change 2 change 3 + | | + one two me too ~ + | + change 4 + | + not two ~ + +Now you change your mind and want to go back to "me too". Use the |g-| +command. This moves back in time. Thus it doesn't walk the tree upwards or +downwards, but goes to the change made before. + +You can repeat |g-| and you will see the text change: + me too ~ + one two ~ + one too ~ + one ~ + +Use |g+| to move forward in time: + one ~ + one too ~ + one two ~ + me too ~ + not two ~ + +Using |:undo| is useful if you know what change you want to jump to. |g-| and +|g+| are useful if you don't know exactly what the change number is. + +You can type a count before |g-| and |g+| to repeat them. + +============================================================================== +*32.4* Time travelling + +When you have been working on text for a while the tree grows to become big. +Then you may want to go to the text of some minutes ago. + +To see what branches there are in the undo tree use this command: > + + :undolist +< number changes time ~ + 3 2 16 seconds ago + 4 3 5 seconds ago + +Here you can see the number of the leaves in each branch and when the change +was made. Assuming we are below change 4, at "not two", you can go back ten +seconds with this command: > + + :earlier 10s + +Depending on how much time you took for the changes you end up at a certain +position in the tree. The |:earlier| command argument can be "m" for minutes, +"h" for hours and "d" for days. To go all the way back use a big number: > + + :earlier 100d + +To travel forward in time again use the |:later| command: > + + :later 1m + +The arguments are "s", "m" and "h", just like with |:earlier|. + +If you want even more details, or want to manipulate the information, you can +use the |undotree()| function. To see what it returns: > + + :echo undotree() + +============================================================================== + +Next chapter: |usr_40.txt| Make new commands + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime_tos/doc/usr_40.txt b/runtime_tos/doc/usr_40.txt new file mode 100644 index 00000000000000..9d706481df138e --- /dev/null +++ b/runtime_tos/doc/usr_40.txt @@ -0,0 +1,657 @@ +*usr_40.txt* For Vim version 7.4. Last change: 2013 Aug 05 + + VIM USER MANUAL - by Bram Moolenaar + + Make new commands + + +Vim is an extensible editor. You can take a sequence of commands you use +often and turn it into a new command. Or redefine an existing command. +Autocommands make it possible to execute commands automatically. + +|40.1| Key mapping +|40.2| Defining command-line commands +|40.3| Autocommands + + Next chapter: |usr_41.txt| Write a Vim script + Previous chapter: |usr_32.txt| The undo tree +Table of contents: |usr_toc.txt| + +============================================================================== +*40.1* Key mapping + +A simple mapping was explained in section |05.3|. The principle is that one +sequence of key strokes is translated into another sequence of key strokes. +This is a simple, yet powerful mechanism. + The simplest form is that one key is mapped to a sequence of keys. Since +the function keys, except , have no predefined meaning in Vim, these are +good choices to map. Example: > + + :map GoDate: :read !datekJ + +This shows how three modes are used. After going to the last line with "G", +the "o" command opens a new line and starts Insert mode. The text "Date: " is +inserted and takes you out of insert mode. + Notice the use of special keys inside <>. This is called angle bracket +notation. You type these as separate characters, not by pressing the key +itself. This makes the mappings better readable and you can copy and paste +the text without problems. + The ":" character takes Vim to the command line. The ":read !date" command +reads the output from the "date" command and appends it below the current +line. The is required to execute the ":read" command. + At this point of execution the text looks like this: + + Date: ~ + Fri Jun 15 12:54:34 CEST 2001 ~ + +Now "kJ" moves the cursor up and joins the lines together. + To decide which key or keys you use for mapping, see |map-which-keys|. + + +MAPPING AND MODES + +The ":map" command defines remapping for keys in Normal mode. You can also +define mappings for other modes. For example, ":imap" applies to Insert mode. +You can use it to insert a date below the cursor: > + + :imap Date: :read !datekJ + +It looks a lot like the mapping for in Normal mode, only the start is +different. The mapping for Normal mode is still there. Thus you can map +the same key differently for each mode. + Notice that, although this mapping starts in Insert mode, it ends in Normal +mode. If you want it to continue in Insert mode, append an "a" to the +mapping. + +Here is an overview of map commands and in which mode they work: + + :map Normal, Visual and Operator-pending + :vmap Visual + :nmap Normal + :omap Operator-pending + :map! Insert and Command-line + :imap Insert + :cmap Command-line + +Operator-pending mode is when you typed an operator character, such as "d" or +"y", and you are expected to type the motion command or a text object. Thus +when you type "dw", the "w" is entered in operator-pending mode. + +Suppose that you want to define so that the command d deletes a C +program block (text enclosed in curly braces, {}). Similarly y would yank +the program block into the unnamed register. Therefore, what you need to do +is to define to select the current program block. You can do this with +the following command: > + + :omap a{ + +This causes to perform a select block "a{" in operator-pending mode, just +like you typed it. This mapping is useful if typing a { on your keyboard is a +bit difficult. + + +LISTING MAPPINGS + +To see the currently defined mappings, use ":map" without arguments. Or one +of the variants that include the mode in which they work. The output could +look like this: + + _g :call MyGrep(1) ~ + v :s/^/> /:noh`` ~ + n :.,$s/^/> /:noh`` ~ + + + + +The first column of the list shows in which mode the mapping is effective. +This is "n" for Normal mode, "i" for Insert mode, etc. A blank is used for a +mapping defined with ":map", thus effective in both Normal and Visual mode. + One useful purpose of listing the mapping is to check if special keys in <> +form have been recognized (this only works when color is supported). For +example, when is displayed in color, it stands for the escape character. +When it has the same color as the other text, it is five characters. + + +REMAPPING + +The result of a mapping is inspected for other mappings in it. For example, +the mappings for above could be shortened to: > + + :map G + :imap + :map oDate: :read !datekJ + +For Normal mode is mapped to go to the last line, and then behave like + was pressed. In Insert mode stops Insert mode with and then +also uses . Then is mapped to do the actual work. + +Suppose you hardly ever use Ex mode, and want to use the "Q" command to format +text (this was so in old versions of Vim). This mapping will do it: > + + :map Q gq + +But, in rare cases you need to use Ex mode anyway. Let's map "gQ" to Q, so +that you can still go to Ex mode: > + + :map gQ Q + +What happens now is that when you type "gQ" it is mapped to "Q". So far so +good. But then "Q" is mapped to "gq", thus typing "gQ" results in "gq", and +you don't get to Ex mode at all. + To avoid keys to be mapped again, use the ":noremap" command: > + + :noremap gQ Q + +Now Vim knows that the "Q" is not to be inspected for mappings that apply to +it. There is a similar command for every mode: + + :noremap Normal, Visual and Operator-pending + :vnoremap Visual + :nnoremap Normal + :onoremap Operator-pending + :noremap! Insert and Command-line + :inoremap Insert + :cnoremap Command-line + + +RECURSIVE MAPPING + +When a mapping triggers itself, it will run forever. This can be used to +repeat an action an unlimited number of times. + For example, you have a list of files that contain a version number in the +first line. You edit these files with "vim *.txt". You are now editing the +first file. Define this mapping: > + + :map ,, :s/5.1/5.2/:wnext,, + +Now you type ",,". This triggers the mapping. It replaces "5.1" with "5.2" +in the first line. Then it does a ":wnext" to write the file and edit the +next one. The mapping ends in ",,". This triggers the same mapping again, +thus doing the substitution, etc. + This continues until there is an error. In this case it could be a file +where the substitute command doesn't find a match for "5.1". You can then +make a change to insert "5.1" and continue by typing ",," again. Or the +":wnext" fails, because you are in the last file in the list. + When a mapping runs into an error halfway, the rest of the mapping is +discarded. CTRL-C interrupts the mapping (CTRL-Break on MS-Windows). + + +DELETE A MAPPING + +To remove a mapping use the ":unmap" command. Again, the mode the unmapping +applies to depends on the command used: + + :unmap Normal, Visual and Operator-pending + :vunmap Visual + :nunmap Normal + :ounmap Operator-pending + :unmap! Insert and Command-line + :iunmap Insert + :cunmap Command-line + +There is a trick to define a mapping that works in Normal and Operator-pending +mode, but not in Visual mode. First define it for all three modes, then +delete it for Visual mode: > + + :map /---> + :vunmap + +Notice that the five characters "" stand for the single key CTRL-A. + +To remove all mappings use the |:mapclear| command. You can guess the +variations for different modes by now. Be careful with this command, it can't +be undone. + + +SPECIAL CHARACTERS + +The ":map" command can be followed by another command. A | character +separates the two commands. This also means that a | character can't be used +inside a map command. To include one, use (five characters). Example: +> + :map :write !checkin %:S + +The same problem applies to the ":unmap" command, with the addition that you +have to watch out for trailing white space. These two commands are different: +> + :unmap a | unmap b + :unmap a| unmap b + +The first command tries to unmap "a ", with a trailing space. + +When using a space inside a mapping, use (seven characters): > + + :map W + +This makes the spacebar move a blank-separated word forward. + +It is not possible to put a comment directly after a mapping, because the " +character is considered to be part of the mapping. You can use |", this +starts a new, empty command with a comment. Example: > + + :map W| " Use spacebar to move forward a word + + +MAPPINGS AND ABBREVIATIONS + +Abbreviations are a lot like Insert mode mappings. The arguments are handled +in the same way. The main difference is the way they are triggered. An +abbreviation is triggered by typing a non-word character after the word. A +mapping is triggered when typing the last character. + Another difference is that the characters you type for an abbreviation are +inserted in the text while you type them. When the abbreviation is triggered +these characters are deleted and replaced by what the abbreviation produces. +When typing the characters for a mapping, nothing is inserted until you type +the last character that triggers it. If the 'showcmd' option is set, the +typed characters are displayed in the last line of the Vim window. + An exception is when a mapping is ambiguous. Suppose you have done two +mappings: > + + :imap aa foo + :imap aaa bar + +Now, when you type "aa", Vim doesn't know if it should apply the first or the +second mapping. It waits for another character to be typed. If it is an "a", +the second mapping is applied and results in "bar". If it is a space, for +example, the first mapping is applied, resulting in "foo", and then the space +is inserted. + + +ADDITIONALLY... + +The