diff --git a/.gitignore b/.gitignore index 5ec825d0c..64789e88d 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,3 @@ doc/tags-ja +target +tmp diff --git a/Makefile b/Makefile new file mode 100644 index 000000000..990f58cf3 --- /dev/null +++ b/Makefile @@ -0,0 +1,19 @@ +.PHONY: all html htmlbatch clean + +all: + +html: + vim -u tools/buildhtml.vim + +htmlbatch: + git show-branch devel || git branch -t devel origin/devel + git show-branch gh-pages || git branch -t gh-pages origin/gh-pages + vim -u tools/buildhtml.vim -e -s -- --batch + cd html && git push .. + +deploy: + sh ./tools/update-master.sh + sh ./tools/update-gh-pages.sh + +clean: + rm -rf target diff --git a/README.md b/README.md index bc91bce4a..2ac0a9959 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ Vimの付属ドキュメントを日本語に翻訳するためのプロジェ 間違いを見つけたらメーリングリストかissueトラッカーでお知らせください。 - Gitリポジトリ https://github.com/vim-jp/vimdoc-ja -- Web版 http://vim-jp.org/vimdoc-ja/ +- HTML版 http://vim-jp.org/vimdoc-ja/ - issueトラッカー https://github.com/vim-jp/vimdoc-ja/issues - メーリングリスト http://groups.google.com/group/vimdoc-ja +- Wiki https://github.com/vim-jp/vimdoc-ja/wiki diff --git a/catchup-7.4.1194.md b/catchup-7.4.1194.md new file mode 100644 index 000000000..94ba2a241 --- /dev/null +++ b/catchup-7.4.1194.md @@ -0,0 +1,72 @@ +# 7.4.1194 に追いつくプロジェクト + +ここらでいっちょ最新に追いつこうぜ、というプロジェクト。最低限、新機能のド +キュメントを未翻訳のままでも、日本語ファイルに組み入れてしまう。 + +最近Vim本体の更新が激しいので、多少のズレはでてしまうが、まずは気にせず1194を +ターゲットにする。 + +## 流れ + +1. 英語ファイルを全部更新 (終わった!) +2. 1の差分を見ながら、日本語ファイルに英文のまま反映 (最低限の目標:終わった!) +3. 2の差分を翻訳 (できたらココまでやりたい) +4. このファイルを削除 + +## ファイル一覧 + +### 英文だけは反映済み + +以上は変更点が100行未満なので、翻訳しやすいはず。 + + doc/change.jax + doc/if_lua.jax # 100行超えたけど、内容的に大したことない + doc/insert.jax + doc/netbeans.jax + doc/quickref.jax + doc/repeat.jax + doc/spell.jax + doc/tagsrch.jax + doc/term.jax + doc/usr_02.jax # 行数は多いけど、まとまった書き換えで、楽そう + doc/usr_03.jax + doc/various.jax + doc/pi_logipat.jax + +こっから先は100行超えるので、嫌。 + + doc/eval.jax + doc/options.jax + doc/pi_netrw.jax # 地獄 + doc/syntax.jax + doc/windows.jax + +### 完訳! + + doc/autocmd.jax + doc/cmdline.jax + doc/develop.jax + doc/editing.jax + doc/filetype.jax + doc/fold.jax + doc/hangulin.jax + doc/help.jax + doc/if_tcl.jax + doc/if_perl.jax + doc/if_pyth.jax + doc/if_ruby.jax + doc/if_mzsch.jax + doc/index.jax + doc/map.jax + doc/mlang.jax + doc/os_os2.jax + doc/pattern.jax + doc/quickfix.jax + doc/usr_29.jax + doc/usr_43.jax + doc/usr_41.jax + doc/vi_diff.jax + +### その他/深い事情があって断念したもの + +まだない diff --git a/doc/arabic.jax b/doc/arabic.jax index c44188af8..40f15d714 100644 --- a/doc/arabic.jax +++ b/doc/arabic.jax @@ -34,7 +34,7 @@ Presentation Form-B (U+FE70-U+FEFF) のフォントも必要です。これら ISO-10646-1 フォントのサブセットです。 コマンド、プロンプト、ヘルプファイルはアラビア語にはなりません。したがってユー -ザーインターフェースは標準の Vi インターフェースのままです。 +ザーインターフェイスは標準の Vi インターフェイスのままです。 特徴 diff --git a/doc/autocmd.jax b/doc/autocmd.jax index f8e6842f9..29c920a2a 100644 --- a/doc/autocmd.jax +++ b/doc/autocmd.jax @@ -1,4 +1,4 @@ -*autocmd.txt* For Vim バージョン 7.4. Last change: 2013 May 19 +*autocmd.txt* For Vim バージョン 7.4. Last change: 2015 Dec 05 VIMリファレンスマニュアル by Bram Moolenaar @@ -267,6 +267,7 @@ Vimは以下のイベントを認識する。イベント名が大文字か小 |Syntax| オプション'syntax'がセットされたとき |EncodingChanged| オプション'encoding'が変更された後 |TermChanged| オプション'term'が変更された後 +|OptionSet| オプションが設定された後 起動と終了 |VimEnter| 全ての起動処理が終わった後 @@ -286,6 +287,8 @@ Vimは以下のイベントを認識する。イベント名が大文字か小 |ShellCmdPost| シェルコマンドを実行した後 |ShellFilterPost| シェルコマンドでフィルタをかけた後 +|CmdUndefined| 呼び出そうとしたユーザー定義コマンドが定義されていな + かったとき |FuncUndefined| 呼び出そうとしたユーザー定義関数が定義されていなかった とき |SpellFileMissing| スペリングファイルを使おうとしたが見つからなかったとき @@ -313,6 +316,9 @@ Vimは以下のイベントを認識する。イベント名が大文字か小 |InsertCharPre| 挿入モードで文字が入力されたとき、その文字が挿入される 前 +|TextChanged| ノーマルモードでテキストが変更された後 +|TextChangedI| 挿入モードでテキストが変更された後 + |ColorScheme| カラースキームを読み込んだ後 |RemoteReply| Vimサーバーからの返答を受け取ったとき @@ -348,7 +354,7 @@ BufDelete バッファリストからバッファを削除する前。(バッ た直前にも使われる。 NOTE: このイベントで自動コマンドが実行された ときは、"%" で表されるカレントバッファと - "" と "" で表される解放されるバッ + "" と "" で表される削除されるバッ ファとは異なるかもしれないことに注意。 他のバッファに切り替えないこと。もしすると問題 が発生するだろう。 @@ -384,7 +390,7 @@ BufNew 新しいバッファを作った直後。バッファがリネーム トに追加されると、イベント BufAdd も発生する。 NOTE: このイベントで自動コマンドが実行された ときは、"%" で表されるカレントバッファと - "" で表される解放されるバッファとは異な + "" で表される作成されるバッファとは異な るかもしれないことに注意。 *BufNewFile* BufNewFile 存在しないファイルの編集を始めたとき。スケルト @@ -457,7 +463,7 @@ BufWipeout バッファを完全に削除する前。イベント BufUnload も)。 NOTE: このイベントで自動コマンドが実行された ときは、"%" で表されるカレントバッファと - "" で表される解放されるバッファとは異な + "" で表される削除されるバッファとは異な るかもしれないことに注意。 *BufWrite* *BufWritePre* BufWrite or BufWritePre バッファ全体をファイルに書き込む前。 @@ -474,6 +480,17 @@ BufWriteCmd バッファ全体をファイルに書き込む前。ファイル BufWritePost バッファ全体をファイルに書き込んだ後 (イベント BufWritePre によるコマンドをアンドゥする役目を 果たす)。 + *CmdUndefined* +CmdUndefined ユーザー定義コマンドが使われたが、定義されてい + なかったとき。必要なときのみコマンドを定義する + のに便利である。パターンはコマンド名に対して照 + 合される。 と の両方ともコマン + ド名に設定される。 + NOTE: 未定義のコマンドに対して自動補完は機能し + ない。このイベントを使う代わりにユーザー定義コ + マンドを常に定義するようにしてそのコマンドから + autoload 関数を呼び出すようにするという方法も + ある。|autoload| 参照。 *CmdwinEnter* CmdwinEnter Command-lineウィンドウに入った後。この特殊な ウィンドウに対してのみオプションを設定するのに @@ -490,9 +507,15 @@ CmdwinLeave Command-lineウィンドウから出る前。イベント 定される。 |cmdwin-char| *ColorScheme* ColorScheme カラースキームを読み込んだ後。 |:colorscheme| + パターンはカラースキーム名にマッチする。 + はこのオプションを設定したファイルの名 + 前になる。 はカラースキーム名になる。 + *CompleteDone* CompleteDone 挿入モード補完が完了したとき。補完が実行されて も中止されても発行される。 |ins-completion| + 変数 |v:completed_item| には補完された候補につい + ての情報が含まれている。 *CursorHold* CursorHold 'updatetime' の時間の間、ユーザーがキーを押さ @@ -507,7 +530,13 @@ CursorHold 'updatetime' の時間の間、ユーザーがキーを押さ の後の移動コマンド入力待ち状態のときは発生しな い。 レコーディングの最中にはCursorHoldイベントは発 - 生しない。|q| + 生しない。|q| + ** + この自動コマンドは内部的に キーが + 引き金になっている。式による指定のマッピング内 + では |getchar()| によってこの文字が取得されること + がある。 + Note: このイベントには対話的なコマンドは使えな いことに注意。「続けるには」プロンプトは現れず、 スクリーンは必要に応じて直接更新される。 @@ -522,9 +551,9 @@ CursorHold 'updatetime' の時間の間、ユーザーがキーを押さ CursorHoldI CursorHoldと同様だが、挿入モードのとき発生す る。 *CursorMoved* -CursorMoved ノーマルモードでカーソルが移動した後。カーソル - 行のテキストが変更されたときにも発生する - (例: "x", "rx", "p"などで)。 +CursorMoved ノーマルモードかビジュアルモードでカーソルが移 + 動した後。カーソル行のテキストが変更されたとき + にも発生する(例: "x", "rx", "p"などで)。 先行入力があったりオペレータが実行待ちになって いる場合は発生しない。 |match-parens|の例を参照。 @@ -560,11 +589,14 @@ FileChangedRO 読み込み専用ファイルに最初の変更を加える前 ここで他のバッファに変更をしてはならない。バッ ファを再読み込みするとはよいが、他のバッファを 編集してはならない。 + *E881* + 行数が変化した場合 undo のための保存は失敗し、 + その変更は中止されるだろう。 *FileChangedShell* FileChangedShell ファイルのタイムスタンプが、ファイルの編集が始 まってから変更されたことを発見したとき。 - ファイルの属性が変更されたときにも使われる。 - |timestamp| + ファイルの属性やファイルサイズが変更されたとき + にも使われる。|timestamp| 大抵はシェルコマンドの実行後に発生する。またコ マンド |:checktime| の実行後や、Vimが入力フォー カスを一度失い、再び得たときにも発生する。 @@ -578,7 +610,7 @@ FileChangedShell ファイルのタイムスタンプが、ファイルの編 かを指示できる。 NOTE: このイベントで自動コマンドが実行された ときは、"%" で表されるカレントバッファと - "" で表される解放されるバッファとは異な + "" で表される変更されたバッファとは異な るかもしれないことに注意。 NOTE: この自動コマンドはカレントバッファを変 更したり、別のバッファにジャンプしたり、バッ @@ -655,7 +687,10 @@ FuncUndefined ユーザー定義関数が使われたが、定義されてい たとき。必要なときのみ関数を定義するのに便利で ある。パターンは関数名に対して照合される。 と の両方とも関数名に設定され - る。|autoload-functions|を参照。 + る。 + NOTE: Vim スクリプトを書くときには autoload 関 + 数を使う方がよい。 + |autoload-functions|を参照。 *GUIEnter* GUIEnter GUI の開始に成功し、ウィンドウを開いた後。 gvim を使ったときは、VimEnter の前に発生する。 @@ -703,6 +738,26 @@ MenuPopup (マウス右ボタンで)ポップアップメニューを表示す o オペレータ実行待ち i 挿入 c コマンドライン + *OptionSet* +OptionSet オプションが設定された後。パターンは長い(短縮 + しない)オプション名に対してマッチする。 + 変数 |v:option_old| に変更前の値が格納され、 + |v:option_new| には新しく設定された値が格納さ + れ、 |v:option_type| にはオプションの変更のス + コープがグローバルかローカルかが格納される。 + || は対象のオプション名が設定される。 + + 'key' の変更の際にはあえてイベントが発生しない + ようにしている。 + + 使用例: 'backupdir' や 'undodir' で指定された + ディレクトリが存在しているかチェックし、もしな + ければディレクトリを作成する。 + + Note: この自動コマンド中でオプションの値をリセ + ットするのは、プラグインの挙動を破壊するため、 + 良くない。この自動コマンドの実行は `:noa` を使 + うことで抑制することができる。 *QuickFixCmdPre* QuickFixCmdPre QuickFixコマンドが実行される前 (|:make|, |:lmake|, |:grep|, |:lgrep|, |:grepadd|, @@ -834,9 +889,9 @@ TextChanged ノーマルモードでカレントバッファのテキストが れるとき。 未処理のキー入力がまだあるとき、またはオペレー ターを待機しているときは、発生しない。 - 注意: このイベントは頻繁に発生するので、ユーザー - が予期しないことや時間のかかる処理は行わないこ - と。 + 注意: このイベントは頻繁に発生するので、ユー + ザーが予期しないことや時間のかかる処理は行わな + いこと。 *TextChangedI* TextChangedI 挿入モードでカレントバッファのテキストが変更さ れたとき。 @@ -895,6 +950,13 @@ WinLeave ウィンドウを離れる前。次に入るウィンドウで他の ============================================================================== 6. パターン *autocmd-patterns* *{pat}* +引数 {pat} にはコンマ区切りのリストを指定することができる。これによりコマンドは +指定されたそれぞれのパターンについて実行される。例えばこのコマンド: > + :autocmd BufRead *.txt,*.info set et +は下記と等しくなる: + :autocmd BufRead *.txt set et + :autocmd BufRead *.info set et + ファイルパターン {pat} がファイル名とマッチするかどうかは、2通りの方法で調べら れる。 1. パターンに '/' が含まれないとき: Vimはファイル名の後ろの部分からのみマッチ @@ -929,7 +991,7 @@ Note: パスの途中だけにマッチさせ、ルートディレクトリに のように展開される。 > /usr/root/main.py イベント FileReadCmd 等を使うときにはこれに注意すること。 の値が、ユー -ザの予期するものと違うかもしれない。 +ザーの予期するものと違うかもしれない。 パターンの中で環境変数を使うこともできる。 > @@ -943,7 +1005,7 @@ Note: パスの途中だけにマッチさせ、ルートディレクトリに *file-pattern* パターンの解釈方法は、ファイル名の解釈方法と大体同じである。 - * はあらゆる文字の列にマッチ + * はあらゆる文字の列にマッチ。注意: パス区切り文字も含まれる。 ? はあらゆる1文字にマッチ \? は '?' にマッチ . は '.' にマッチ @@ -952,6 +1014,9 @@ Note: パスの途中だけにマッチさせ、ルートディレクトリに \, は ',' にマッチ { } は |pattern| の \( \) と同様 , ('{' '}' の内側では) |pattern| の \| と同様 + \} リテラルの } + \{ リテラルの { + \\\{n,m\} |pattern| の \{n,m} と同様 \ は |pattern| で使われるものと同様の特別な意味を持つ [ch] は 'c' または 'h' にマッチ [^ch] は 'c' と 'h' 以外の文字にマッチ @@ -995,7 +1060,7 @@ Note: パスの途中だけにマッチさせ、ルートディレクトリに 例: > :au CursorHold echo 'hold' :au CursorHold echo 'hold' - :au CursorHold echo 'hold' + :au BufNewFile * au CursorHold echo 'hold' 自動コマンドに対するコマンドは全てバッファローカルな自動コマンドに対しても機能 する。パターンの代わりに特別な文字列を使う。例: > @@ -1054,6 +1119,9 @@ Note: パスの途中だけにマッチさせ、ルートディレクトリに :aug[roup] {name} 後に続くコマンド ":autocmd" のためのグループ名 を定義する。{name} を "end" や "END" にすると 既定のグループが選ばれる。 + 混乱を避けるため、既存の {event} の名前とは違う + 名前をつけるべきである。これはたいてい意図しな + い動作を引き起こす。 *:augroup-delete* *E367* :aug[roup]! {name} 自動コマンドのグループ {name} を削除する。その @@ -1064,7 +1132,7 @@ Note: パスの途中だけにマッチさせ、ルートディレクトリに 特定のグループとして自動コマンドを定義するには、次の手順に従うこと。 1. ":augroup {name}" によってグループを選択する。 2. ":au!" によって古い自動コマンドを全て消去する。 -3.自動コマンドを定義する。 +3. 自動コマンドを定義する。 4. ":augroup END" によって既定のグループに戻る。 例: > @@ -1101,12 +1169,11 @@ NOTE オプション 'eventignore' はここにも適用されることに注意 < 無限の循環に陥らないよう注意すること。また |autocmd-nested| を参照すること。 - 引数 [group] が省かれると、全てのグループの - 自動コマンドが実行される。 [group] が指定されると、そ - れにマッチするグループの自動コマンドのみが実行される。 - NOTE 定義されていないグループ名を使うと、エラーメッ - セージが表示される。 - + 引数 [group] が省かれると、全てのグループの自動コマン + ドが実行される。 [group] が指定されると、それにマッチ + するグループの自動コマンドのみが実行される。NOTE 定義 + されていないグループ名を使うと、エラーメッセージが表示 + される。 ** 自動コマンドを適用した後にモードラインが処理される。 ファイルを編集するときと同じように、自動コマンドでなさ diff --git a/doc/change.jax b/doc/change.jax index 26dbfece4..3414eb944 100644 --- a/doc/change.jax +++ b/doc/change.jax @@ -1,4 +1,4 @@ -*change.txt* For Vim バージョン 7.4. Last change: 2013 Mar 19 +*change.txt* For Vim バージョン 7.4. Last change: 2016 Jan 19 VIMリファレンスマニュアル by Bram Moolenaar @@ -71,9 +71,21 @@ アルモードでは、"D" はビジュアル選択されたテキストと行 末までの全てのテキストを削除する。 {Vi にはない} - *:d* *:de* *:del* *:delete* *:dl* + *:d* *:de* *:del* *:delete* *:dl* *:dp* :[range]d[elete] [x] [range] 行 (既定値: 現在行) を [レジスタ x に入れ] 削 除する。 + Note これらの変な短縮入力: + :dl delete と list + :dell 同上 + :delel 同上 + :deletl 同上 + :deletel 同上 + :dp delete と print + :dep 同上 + :delp 同上 + :delep 同上 + :deletp 同上 + :deletep 同上 :[range]d[elete] [x] {count} [range] 行目 (既定: 現在行 |cmdline-ranges|) から @@ -134,6 +146,9 @@ gJ [count] 行を連結する (最低は 2 行)。空白の挿入や削除を 'formatoptions' のフラグ 'M' と 'B' は、マルチバイト文字の前後に空白を挿入する ときの動作を変更する |fo-table|。 +'[ マークは連結前の最初の行の末尾に設定される。'] マークは連結後の行の末尾に設 +定される。 + ============================================================================== 2. 削除と挿入 *delete-insert* *replacing* @@ -260,17 +275,17 @@ r{char} カーソル下の文字を {char} に置き換える。 う。これは置き換えるべき文字を削除した後 "i" を実行したような動作になる。 {char} はダイグラフでもよい |digraph-arg|。 - |:lmap| のマッピングは {char} に適用される。Inlertモー - ドでは、コマンド CTRL-^ を使ってマッピングを切り替えら - れる |i_CTRL-^|。オプション 'encoding' がUnicodeの一種 - のときに composing character を使うことについては + |:lmap| のマッピングは {char} に適用される。挿入モード + では、コマンド CTRL-^ を使ってマッピングを切り替えられ + る |i_CTRL-^|。オプション 'encoding' がUnicodeの一種の + ときに composing character を使うことについては |utf-8-char-arg| を参照。 *gr* gr{char} カーソル下の仮想文字を {char} に置き換える。このコマン - ドはファイル上の空白ではなく、画面上の空白を置き換える。 - 詳細は |gR| と |Virtual-Replace-mode| を参照。|r| と同 - 様、回数を指定できる。 + ドはファイル上の文字単位ではなく、画面上の文字幅単位で + 置き換える。詳細は |gR| と |Virtual-Replace-mode| を参 + 照。|r| と同様、回数を指定できる。 {char} の入力方法は |r| と同様である。 {Vimが |+vreplace| 機能付きでコンパイルされたときのみ 有効} @@ -349,15 +364,54 @@ g?? 現在行をRot13エンコードする。 {Vi にはない} 加算と減算 ~ *CTRL-A* -CTRL-A カーソルの下または後の数またはアルファベットに [count] - を加える。 {Vi にはない} +CTRL-A カーソルの下または後の数字またはアルファベットに + [count] を加える。 {Vi にはない} + + *v_CTRL-A* +{Visual}CTRL-A ビジュアル選択されたテキスト中の数字またはアル + ファベットに [count] を加える。{Vi にはない} + + *v_g_CTRL-A* +{Visual}g CTRL-A ビジュアル選択されたテキスト中の数字またはアル + ファベットに [count] を加える。複数行がビジュアル選択 + されている場合、各行は付加された [count] ごとに増やさ + れる (そのため効果的に [count] ごとに増加する配列を作 + ることができる)。 {Vi にはない} + 例えば、このような数字のリストがあるとする: + 1. ~ + 1. ~ + 1. ~ + 1. ~ + 2番目の "1." に移動し3行をビジュアル選択してから g + CTRL-A を押すと、このようになる: + 1. ~ + 2. ~ + 3. ~ + 4. ~ *CTRL-X* -CTRL-X カーソルの下または後の数またはアルファベットから +CTRL-X カーソルの下または後の数字またはアルファベットから [count] を減じる。 {Vi にはない} -コマンド CTRL-A と CTRL-X は(符号付)10進数と符号なし8進／16進数、アルファベッ -トに対し機能する。この動作はオプション 'nrformats' に依存する。 + *v_CTRL-X* +{Visual}CTRL-X ビジュアル選択されたテキスト中の数字またはアル + ファベットから [count] を減じる。 {Vi にはない} + + *v_g_CTRL-X* +{Visual}g CTRL-X ビジュアル選択されたテキスト中の数字またはアル + ファベットから [count] を減じる。複数行がビジュアル選 + 択されている場合、各値は付加された [count] ごとに減ら + される (そのため効果的に [count] ごとに減少する配列を + 作ることができる)。 {Vi にはない} + +The CTRL-A and CTRL-X commands can work for: +- signed and unsigned decimal numbers +- unsigned binary, octal and hexadecimal numbers +- alphabetic characters + +This depends on the 'nrformats' option: +- When 'nrformats' includes "bin", Vim assumes numbers starting with '0b' or + '0B' are binary. - 'nrformats' が "octal" を含むときは、Vimは '0' で始まり、'8' や '9' を含まな い数字を8進数として取り扱う。他の数は10進数とみなされ、マイナス符号が付いて もよい。カーソルが数の上にあれば、コマンドはその数に適用される。そうでなけれ @@ -370,6 +424,10 @@ CTRL-X カーソルの下または後の数またはアルファベットか を変更する。これはアルファベットのインデックスつきのリストを作るときに便利で ある。 +10進数では先頭の負の符号は増加/減少に対して考慮される。しかし2進数、8進数およ +び16進数では考慮されない。符号を無視するには CTRL-A または CTRL-X を使う前に数 +字をビジュアル選択する。 + ゼロから始まる数 (全ての8進数、16進数を含む) に対して、Vimはできる限りその数の 文字数を保とうとする。"0077" 上で CTRL-A を使うと "0100" となり、"0x100" 上で CTRL-X を使うと "0x0ff" となる。 @@ -380,6 +438,10 @@ CTRL-X を使うと "0x0ff" となる。 Note: 'nrformats' が "octal" を含んでいるとき、0で始まる10進数は、8進数と区別 しづらいため、意図しない結果になる可能性がある。 +Note similarly, when 'nrformats' includes "bin", binary numbers with a leading +'0x' or '0X' can be interpreted as hexadecimal rather than binary since '0b' +are valid hexadecimal digits. + コマンド CTRL-A はマクロ内でたいへん便利である。例: 番号付きリストを作るには、 次の方法を使う。 @@ -446,9 +508,9 @@ Note: 'nrformats' が "octal" を含んでいるとき、0で始まる10進数 'shiftround' がオンのとき、インデントは 'shiftwidth' の倍数に丸められる。 -'shiftwidth' がオンのとき、あるいは 'cindent' がオンで 'cinkeys' が '#' を含む -とき、右方向へのシフトは '#' で始まる行に適用されない (これらの行は、行の最初 -に位置すべきCプリプロセッサ指令であると考えられる)。 +'shiftwidth' がオンのとき、あるいは 'cindent' がオンで 'cinkeys' が値 0 の '#' +を含むとき、右方向へのシフトは '#' で始まる行に適用されない (これらの行は、行 +の最初に位置すべきCプリプロセッサ指令であると考えられる)。 'expandtab' がオフ (既定値) のとき、Vimはインデントにできる限り多くの を 使う。">><<" によって、空白のみで構成されたインデントを、 (と必要ならばい @@ -474,8 +536,8 @@ Vimは空白のみを使う。">><<" によって、インデント内の Cのプログラムを整形する "indent" (ただし、フィルタ機能を持ったバージョンが必要。 全てのバージョンでできるわけではない) などがある。オプション 'shell' は、Vimが フィルタコマンドを実行するときに使うシェルを指定する ('shelltype' も参照)。フィ -ルタコマンドはコマンド "." で繰り返せる。Vimは `:!` の後のコメント ('"' で始ま -る行) を認識しない。 +ルタコマンドはコマンド "." で繰り返せる。Vimは `:!` の後の ('"' で始まる) コメ +ントを認識しない。 *!* !{motion}{filter} {motion} のテキストを外部プログラム {filter} でフィル @@ -562,9 +624,9 @@ MS-Windows ではシステム関数 GetTempFileName() が使われる。 (|:s_flags|を参照)。 Note `:substitute` の後ではフラグ '&' は使えないことに 注意。パターンの区切り文字だと認識されてしまう。 - `:substitute` とフラグ 'c', 'g', 'r' の間の空白は必要 - 不可欠ではない。しかしスクリプト内では、混乱しないよう - に空白を入れておくのはよい考えである。 + `:substitute` とフラグ 'c', 'g', 'i', 'I', 'r' の間の + 空白は必要不可欠ではない。しかしスクリプト内では、混乱 + しないように空白を入れておくのはよい考えである。 :[range]~[&][flags] [count] *:~* 最後の置換を同じ置換文字列で、最後の検索パターン {訳注: @@ -708,7 +770,7 @@ Viとの互換性のため、これら2つの例外が許される。 *sub-replace-special* *:s\=* {string} が "\=" で始まるときは、それは式として評価される。 -|sub-replace-expression|　を参照のこと。複雑な置換や特殊な文字を使うことができ +|sub-replace-expression| を参照のこと。複雑な置換や特殊な文字を使うことができ る。そうでなければ、{string} の中のこれらの文字は特別な意味を持つ: *:s%* @@ -784,8 +846,38 @@ NOTE: 以前のバージョンでは CTRL-V が特別に扱われていた。こ :s/\([ab]\)\|\([cd]\)/\1x/g "a b c d" を "ax bx x x" に置換 < + *:sc* *:sce* *:scg* *:sci* *:scI* *:scl* *:scp* *:sg* *:sgc* + *:sge* *:sgi* *:sgI* *:sgl* *:sgn* *:sgp* *:sgr* *:sI* *:si* + *:sic* *:sIc* *:sie* *:sIe* *:sIg* *:sIl* *:sin* *:sIn* *:sIp* + *:sip* *:sIr* *:sir* *:sr* *:src* *:srg* *:sri* *:srI* *:srl* + *:srn* *:srp* +2-letter and 3-letter :substitute commands ~ + + List of :substitute commands + | c e g i I n p l r + | c :sc :sce :scg :sci :scI :scn :scp :scl --- + | e + | g :sgc :sge :sg :sgi :sgI :sgn :sgp :sgl :sgr + | i :sic :sie --- :si :siI :sin :sip --- :sir + | I :sIc :sIe :sIg :sIi :sI :sIn :sIp :sIl :sIr + | n + | p + | l + | r :src --- :srg :sri :srI :srn :srp :srl :sr + +Exceptions: + :scr is `:scriptnames` + :se is `:set` + :sig is `:sign` + :sil is `:silent` + :sn is `:snext` + :sp is `:split` + :sl is `:sleep` + :sre is `:srewind` + + 式で置換する *sub-replace-expression* - *sub-replace-\=* + *sub-replace-\=* *s/\=* 置換文字列が "\=" で始まるとき、それ以降の文字列は式として解釈される。これは再 帰的に機能しない。その式の中での |substitute()| では置換文字列に "\=" を使うこ @@ -887,7 +979,7 @@ NOTE: 以前のバージョンでは CTRL-V が特別に扱われていた。こ :reg[isters] {arg} {arg} に指定された名前付きレジスタおよび番号付きレジス タを表示する。例: > - :dis 1a + :reg 1a < レジスタ '1' と 'a' が表示される。{arg} の中では空白を 用いてよい。 {Vi にはない} @@ -1017,15 +1109,19 @@ NOTE: 以前のバージョンでは CTRL-V が特別に扱われていた。こ *put-Visual-mode* *v_p* *v_P* ビジュアルモードで |p| や |P| 等の貼り付けコマンドを使ったとき、Vimは選択さ れたテキストをレジスタの中身で置き換えようとする。これがうまく動作するかどう -かは、選択領域の種類とレジスタ内のテキストの種類による。ブロック指向の選択で -は、ブロックのサイズと、選択領域の角が既存の文字上にあるかどうかにもよる。 -(実装上の詳細:実際の動作は、まずレジスタの中身を選択領域の後に貼り付け、その -後で選択領域を削除するようになっている) +かは、選択領域の種類とレジスタ内のテキストの種類による。矩形選択では、ブロッ +クのサイズと、選択領域の角が既存の文字上にあるかどうかにもよる。(実装上の詳 +細:実際の動作は、まずレジスタの中身を選択領域の後に貼り付け、その後で選択領 +域を削除するようになっている) それまで選択されていたテキストが無名レジスタに保存される。同じテキストを複数 のビジュアル選択領域にプットしたい場合は、ほかのレジスタを使う必要がある。例 えば、コピーしたいテキストをヤンクして、選択したテキストを "0p で置き換える。 これを好きなだけ繰り返す。このとき、無名レジスタはプットするたびに変わる。 +矩形ビジュアルモードで一行のみをヤンクしたとき、それをビジュアル選択した範囲に +貼り付けると、選択範囲にその一行が貼り付けされる (つまり貼り付けた行のブロック +によって矩形選択範囲が置換される)。 + *blockwise-register* 矩形ビジュアルモードで、レジスタにテキストを蓄えるコマンドを使うと、テキストの ブロックはカーソルの前 ("P" のとき) または後 ("p" のとき) から、現在行と引き続 @@ -1045,16 +1141,17 @@ Note 文字単位のコピーコマンドの後、コピーされたテキスト 行単位のコピーコマンドではカーソルは選択の最初の行に置かれるが、カラムは変更さ れない。なのでその位置はコピーされた最初の文字の上ではないかもしれない。 -レジスタには 9 種類ある: *registers* *E354* +レジスタには 10 種類ある: *registers* *E354* 1. 無名レジスタ "" 2. 10個の番号付きレジスタ "0 から "9 3. 小削除用レジスタ "- 4. 26個の名前付きレジスタ "a から "z または "A から "Z -5. 4個の読み取り専用レジスタ ": と ". と "% と "# -6. expression 用レジスタ "= -7. 選択領域用レジスタ "* と "+ と "~ -8. 消去専用レジスタ "_ -9. 最終検索パターン用レジスタ "/ +5. 3個の読み取り専用レジスタ ": と ". と "% +6. 代替バッファ用レジスタ "# +7. expression 用レジスタ "= +8. 選択領域用レジスタ "* と "+ と "~ +9. 消去専用レジスタ "_ +10. 最終検索パターン用レジスタ "/ 1. 無名レジスタ "" *quote_quote* *quotequote* このレジスタには、コマンド "d", "c", "s", "x" 等で削除されたテキストや、"y" 等 @@ -1082,9 +1179,10 @@ Note 文字単位のコピーコマンドの後、コピーされたテキスト は、以下の移動コマンドと削除コマンドを組み合わせたときである。|%|, |(|, |)|, |`|, |/|, |?|, |n|, |N|, |{|, |}|。このときは必ずレジスタ "1 が使われる (これ はVi互換の動作である)。削除や変更したテキストが1行以下だったときは、レジスタ -"- も使われる。削除や変更が行われるたびに、レジスタ 1 の内容はレジスタ 2 に、 -レジスタ 2 の内容はレジスタ 3 に、という風にずれていく。レジスタ 9 の内容は失 -われる。 +"- も使われる。 Note: これらの文字はマップ可能である。例: |%| は matchit プラ +グインによってマップされている。 +削除や変更が行われるたびに、レジスタ 1 の内容はレジスタ 2 に、レジスタ 2 の内 +容はレジスタ 3 に、という風にずれていく。レジスタ 9 の内容は失われる。 {Vi では番号付きレジスタの内容はファイルを変更する際に失われる。レジスタ 0 は ない} @@ -1100,7 +1198,7 @@ Note 文字単位のコピーコマンドの後、コピーされたテキスト 容の後ろに新しいテキストを付け加える。'cpoptions' にフラグ '>' が入っていると、 新しいテキストの前に改行が挿入される。 -5. 読みとり専用レジスタ ": と ". と "% と "# +5. 読みとり専用レジスタ ": と ". と "% 読みとり専用レジスタには '%' と '#' と ':' と '.' がある。コマンド "p", "P", ":put" および CTRL-R でのみ使うことができる。 {Vi にはない} *quote_.* *quote.* *E29* @@ -1112,8 +1210,6 @@ Note 文字単位のコピーコマンドの後、コピーされたテキスト する)。 *quote_%* *quote%* "% カレントファイルの名前が蓄えられる。 - *quote_#* *quote#* - "# 代替ファイルの名前が蓄えられる。 *quote_:* *quote:* *E30* ": 一番最近に実行されたコマンドラインの内容が蓄えられる。例: 前回 のコマンドラインによるコマンドを実行するには、"@:" が使える。 @@ -1123,15 +1219,33 @@ Note 文字単位のコピーコマンドの後、コピーされたテキスト 変化はない。 {Vimが |+cmdline_hist| 機能付きでコンパイルされたときのみ有効} -6. Expression レジスタ "= *quote_=* *quote=* *@=* + *quote_#* *quote#* +6. 代替ファイルレジスタ "# +カレントウィンドウの代替ファイルの名前を含む。これは |CTRL-^| コマンドがどのよ +うに働くかを変更する。 +このレジスタは書き込み可能で、主にプラグインがこのレジスタを変更した後で元に戻 +すためである。バッファ番号を許容する: > + let altbuf = bufnr(@#) + ... + let @# = altbuf +バッファ番号が越えるあるいはそのバッファが存在しない場合はエラー |E86| を返 +す。 +また存在するバッファ名でのマッチングを許容する: > + let @# = 'buffer_name' +与えられた名前にマッチしたバッファが1つより多い場合はエラー |E93| を、与えられ +た名前にマッチするバッファがない場合は |E94| を返す。 + +7. Expression レジスタ "= *quote_=* *quote=* *@=* これは、本当はテキストを蓄えるレジスタではないが、レジスタを使うコマンドで式 -を評価するために使える。この expression レジスタは読み取り専用である。 -これにはテキストをコピーできない。'=' を打ち込むと、カーソルはコマンド行に移 -動し、あらゆる式を入力することができる (|expression| を参照)。コマンドライン -から入力できる普通の編集用コマンドは、式用の特別履歴も含め、全て使用可能であ -る。 を打ち込んでコマンドライン入力を終了させると、式の結果が計算される。 - を打ち込んで終了させると、式は破棄される。式が入力されないときは、(コ -マンド "/" と同様) 前回の式が使われる。 +を評価するために使える。この expression レジスタは読み取り/書き込み可能であ +る。 + +" または CTRL-R の後に '=' を打ち込むと、カーソルはコマンド行に移動し、あらゆ +る式を入力することができる (|expression| を参照)。コマンドラインから入力できる +普通の編集用コマンドは、式用の特別履歴も含め、全て使用可能である。 を打ち +込んでコマンドライン入力を終了させると、式の結果が計算される。を打ち込ん +で終了させると、式は破棄される。式が入力されないときは、(コマンド"/" と同様) +前回の式が使われる。 式を評価した結果は文字列でなければならない。評価した結果が数値なら、文字列に 変換される。"p" と ":put" コマンドの場合、結果が浮動小数点数なら文字列に変換 @@ -1142,7 +1256,7 @@ Note 文字単位のコピーコマンドの後、コピーされたテキスト --改行} の所で分割される。文字列が で終わっていたら、これは行単位のレジ スタと見なされる。 {Vi にはない} -7. 選択範囲レジスタ "* と "+ +8. 選択範囲レジスタ "* と "+ と "~ これらのレジスタは、GUIで、選択されたテキストを蓄えたり取り出すために使われる。 |quotestar| と |quoteplus| を参照。クリップボードが利用できないときは、無名レ ジスタが代わりに使われる。 Unixでは|+xterm_clipboard|が有効になっているときだ @@ -1160,15 +1274,15 @@ Note "* と "+ に区別があるのは X11 システムのみであることに {Vi にはない} {|+dnd|付きでコンパイルされたときのみ有効。現在はGTK GUIでのみ使える。} -Note: "~ レジスタはプレインテキストをVimにドロップしたときのみ使われる。URI +Note: "~ レジスタはプレーンテキストをVimにドロップしたときのみ使われる。URI のリストは内部で扱われる。 -8. 消去専用レジスタ "_ *quote_* +9. 消去専用レジスタ "_ *quote_* このレジスタを指定してテキストを削除しても、{訳注: レジスタには} 何も起こらな い。そのため、普通のレジスタに影響を与えずに削除が行える。このレジスタから貼り 付けようとしても、何も出てこない。 {Vi にはない} -9. 最終検索パターン用レジスタ "/ *quote_/* *quote/* +10. 最終検索パターン用レジスタ "/ *quote_/* *quote/* 最後に使われた検索パターンが蓄えられる。これはコマンド "n" やオプション 'hlsearch' による強調表示に使われる。 このレジスタは `:let` で変更できるので、'hlsearch' による強調表示を、実際に検 @@ -1230,7 +1344,7 @@ gq{motion} {motion} の行を整形する。整形は3種類の方法のうち 3番目の場合は、オプション 'textwidth' が整形された各行 の長さを制御する (後述)。'textwidth' が 0 なら、整形さ - れた行の長さは画面の幅となる (ただし、最大で79)。 + れた行の長さは画面の幅となる (ただし、最大で79)。 'formatoptions' は、整形の仕方を制御する |fo-table|。 カーソルは最後に整形された行の最初の非空白文字の上に置 かれる。 @@ -1569,11 +1683,11 @@ autocommand と連携して、クールに振舞うはずである。 ============================================================================== 7. テキストのソート *sorting* -Vimはソート関数とソートコマンドを備えている。ソート関数については|sort()|を参 -照。 +Vimはソート関数とソートコマンドを備えている。ソート関数については |sort()|、 +|uniq()| を参照。 *:sor* *:sort* -:[range]sor[t][!] [i][u][r][n][x][o] [/{pattern}/] +:[range]sor[t][!] [b][f][i][n][o][r][u][x] [/{pattern}/] [range]の行をソートする。範囲が指定されない場合は全行 をソートする。 @@ -1581,10 +1695,18 @@ Vimはソート関数とソートコマンドを備えている。ソート関 [i]をつけると大文字・小文字を区別しない。 + Options [n][f][x][o][b] are mutually exclusive. + [n]をつけると行の({pattern}のマッチの後ろまたは内側 の)最初の10進数の数字でソートする。 数字が '-' で始まる場合、マイナスとみなされる。 + With [f] sorting is done on the Float in the line. + The value of Float is determined similar to passing + the text (after or inside a {pattern} match) to + str2float() function. This option is available only + if Vim was compiled with Floating point support. + [x]をつけると行の({pattern}のマッチの後ろまたは内側 の)最初の16進数の数字でソートする。"0x" と "0X" は無視 される。 @@ -1593,10 +1715,13 @@ Vimはソート関数とソートコマンドを備えている。ソート関 [o]をつけると行の({pattern}のマッチの後ろまたは内側 の)最初の8進数の数字でソートする。 - [u]をつけると連続する同一行の最初の行だけを残す。 - ([i]がつくと大文字・小文字を無視する) - このフラグがつかない場合、連続する同一行はそのままの順 - 序で残される。 + With [b] sorting is done on the first binary number in + the line (after or inside a {pattern} match). + + [u]をつけると (u は unique=「一意の」という意味に基づ + く) 連続する同一行の最初の行だけを残す。([i]がつくと大 + 文字・小文字を無視する) このフラグがつかない場合、連続 + する同一行はそのままの順序で残される。 Note: 行頭に行末の空白があると異なる行とみなされる。 /pattern/が指定され、フラグ[r]がない場合は{pattern}に @@ -1604,7 +1729,7 @@ Vimはソート関数とソートコマンドを備えている。ソート関 マッチの後に来るテキストでソートできる。 スラッシュの代わりにどんなnon-letterでも使うことができ る。 - 例えば、カンマで区切られた2番目のフィールドでソートす + 例えば、コンマで区切られた2番目のフィールドでソートす るには: > :sort /[^,]*,/ < 画面上の10桁目でソートするには(そのためタブとスペース @@ -1632,8 +1757,9 @@ Vimはソート関数とソートコマンドを備えている。ソート関 Note: `:global` といっしょに `:sort` を使ってもマッチする行をソートすることに はならない。これはまったく無意味である。 -ソートの詳細は使っているライブラリ関数による。ソートが「安定」であるとか現在の -ロケールに従うという保証はない。それを調べるには実行してみるしかない。 +ソートの詳細は使っているライブラリ関数による。ソートが現在のロケールに従うとい +う保証はない。それを調べるには実行してみるしかない。ソートは「安定」ソートであ +る。 ソートは中断することができる。しかし中断するのが遅いと行が重複してしまうかもし れない。これも使っているシステムのライブラリ関数による。 diff --git a/doc/channel.jax b/doc/channel.jax new file mode 100644 index 000000000..86a066f2b --- /dev/null +++ b/doc/channel.jax @@ -0,0 +1,223 @@ +*channel.txt* For Vim バージョン 7.4. Last change: 2016 Jan 28 + + + VIMリファレンスマニュアル by Bram Moolenaar + + + プロセス間通信 *channel* + +ドラフト ドラフト ドラフト ドラフト ドラフト ドラフト ドラフト + +Vimは別のプロセスと通信するのにチャンネルを用います。 +チャンネルはソケットを用います。 *socket-interface* + +現在のところVimは同時に10個までのチャンネルをサポートします。 +Netbeansインターフェースもチャンネルを使っています。 |netbeans| + +1. デモ |channel-demo| +2. チャンネルを開く |channel-open| +3. JSONチャンネルを使う |channel-use| +4. Vimコマンド |channel-commands| +5. rawチャンネルを使う |channel-use| +6. ジョブ制御 |job-control| + +{Vi にはこれらの機能はありません} +{|+channel| 機能付きでコンパイルされたときのみ利用可能} + +============================================================================== +1. デモ *channel-demo* + +デモにはPythonが必要です。デモプログラムは次の場所にあります。 +$VIMRUNTIME/tools/demoserver.py +それをあるターミナルで実行しましょう。そのターミナルをT1と呼びます。 + +次に別のターミナルでVimを実行します。そして以下のコマンドでサーバーに接続しま +す: > + let handle = connect('localhost:8765', 'json') + +T1の中に次のように表示されます: + === socket opened === ~ + +ついにサーバーにメッセージを送信できます: > + echo sendexpr(handle, 'hello!') + +このメッセージはT1で受信され、Vimには応答が送り返されます。 +T1ではVimが送った生のメッセージを確認できます: + [1,"hello!"] ~ +そしてレスポンスはこうなります: + [1,"got it"] ~ +この数値はメッセージを送るたびに増加していきます。 + +サーバーはVimにコマンドを送信できます。T1に於いて、次のように正確に(引用符を含 +めて文字通りに)タイプしてください: > + ま　だ　実　装　さ　れ　て　い　ま　せ　ん + ["ex","echo 'hi there'"] +するとそのメッセージがVimに表示されます。 + +非同期通信を取り扱うためにはコールバック(以下ハンドラー)が必要です: > + func MyHandler(handle, msg) + echo "from the handler: " . a:msg + endfunc + call sendexpr(handle, 'hello!', "MyHandler") + +sendを呼ぶたびに毎回コールバックを指定する代わりに、チャンネルを開く際に指定す +ることもできます: > + call disconnect(handle) + let handle = connect('localhost:8765', 'json', "MyHandler") + call sendexpr(handle, 'hello!', 0) + +============================================================================== +2. チャンネルを開く *channel-open* + +チャンネルを開くには次のようにします: > + let handle = connect({address}, {mode}, {callback}) + +{address} は "ホスト名:ポート番号" の形式です。 例:"localhost:8765" + +{mode} でモード(通信フォーマット)を指定します: *channel-mode* + "json" - JSONを使う(詳しくは下記を参照。もっとも使いやすい方法) + "raw" - rawメッセージを使う + + *channel-callback* +{callback} はメッセージ受信時に他のハンドラーで扱われない時に呼ばれます。 +これはチャンネルのハンドルと、受信したメッセージの2つの引数を取ります。例: > + func Handle(handle, msg) + echo '受信した: ' . a:msg + endfunc + let handle = connect("localhost:8765", 'json', "Handle") + + +{mode} が "json" の時には、"msg" 引数は受信したメッセージの本文で、Vimの型に変 +換されています。 +一方 {mode} が "raw" の時には、 "msg" 引数はメッセージ全体を格納した文字列で +す。 + +{mode} が "json" の時には {callback} はオプションです。これを省略した場合、 +メッセージを1つ受信するにはメッセージを1つ送信する必要があります。 + +ハンドラーは後から追加したり、変更したりできます: > + call sethandler(handle, {callback}) +{callback} が空の場合 (一度も指定しないか、空文字列を指定した場合) ハンドラー +は削除されます。 + +チャンネルを使い終わったら、以下のように切断してください: > + call disconnect(handle) + +============================================================================== +3. JSONチャンネルを使う *channel-use* + +{mode} が "json" 場合は、以下のようにメッセージを同期的に送信できます: > + let response = sendexpr(handle, {expr}) +これは通信相手から応答があるまで待ち合わせます。 + +応答を処理する必要が無いのであれば、以下のように送れます: > + call sendexpr(handle, {expr}, 0) + +メッセージを送信し、応答を特別な関数で非同期的に処理する場合には、このようにし +ます: > + call sendexpr(handle, {expr}, {callback}) + +{expr} は JSON に変換され、配列で包まれます。{expr} として文字列 "hello" を送 +信した場合に、通信相手が受け取るメッセージの例は次のようになります: + [12,"hello"] ~ + +送信されるJSONのフォーマットはこのようになっています: + [{number},{expr}] + +{number} には毎回異なる値が入ります。これは応答(があるならば)、必ず使われま +す: + + [{number},{response}] + +このようにして、受信したメッセージがどの送信メッセージに対応するかを知ることが +でき、正しいハンドラーを呼び出すことができます。これによって応答メッセージの到 +着順序を気にしなくても良くなります。 + +送信側はかならず有効なJSONをVimへ送らなければなりません。VimはJSONとして解釈す +ることで、受信メッセージの終端をチェックします。終端を受信することが、 +メッセージを受理する唯一の方法です。 + +サーバープロセスがVimからのメッセージを受信すること無く、メッセージを送信する +には、数値に 0 を使う必要があります。 + [0,{response}] + +するとチャンネルのハンドラーが {response} をVimの方に変換したものを受け取るで +しょう。チャンネルにハンドラーが関連付けられていない場合には、メッセージは破棄 +されます。 + +読み込みエラーが発生した場合や |disconnect()| した場合には、可能であるなら文字 +列 "DETACH" が送られます。チャンネルはそれから非アクティブになります。 + +============================================================================== +4. Vimコマンド *channel-commands* + +ま　だ　実　装　さ　れ　て　い　ま　せ　ん + +"json" チャンネルを使用すると、サーバープロセス側はVimへコマンドを送信できま +す。そのコマンドはチャンネルのハンドラーを介さずに、Vimの内部で実行されます。 + +実行可能なコマンドは以下のとおりです: > + ["ex", {Ex コマンド}] + ["normal", {ノーマルモードコマンド}] + ["eval", {数値}, {式}] + ["expr", {式}] + +これらを使うときは、これらのコマンドが何をするかに十分気をつけてください! +ユーザーが何をしているかによっては容易に干渉してしまいます。トラブルを避けるに +は |mode()| を使い、エディタが期待した状態にあるかチェックしてください。例え +ば、コマンド実行ではなくテキストとして入力させたい文字列を送るには、以下のよう +にします: > + ["ex","if mode() == 'i' | call feedkeys('ClassName') | endif"] + +"ex" コマンドは Ex コマンドを実行します。完了やエラーの応答はありませ +ん。|autoload| スクリプトの中の関数を使えます。何かを入力するのに |feedkeys()| +を実行することもできます。 + +"normal" コマンドは |:normal| のように実行されます。 + +"eval" コマンドは式の評価結果を以下の様に返信します: > + [{数値}, {result}] +{数値} は、リクエストに指定したのと同じものです。 + +"expr" コマンドはそれに近いのですが、応答を返信しません。例: > + ["expr","setline('$', ['one', 'two', 'three'])"] + +============================================================================== +5. rawチャンネルを使う *channel-raw* + +{mode} が "raw" の場合には、以下のようにしてメッセージを送信します: + let response = sendraw(handle, {string}) +{string} はそのまま送信されます。受信した応答メッセージは直ちにチャンネルから +読み込み可能になります。この時、Vimにはメッセージの終了をどう判断するかがわか +りませんから、あなた自身が面倒を見る必要があります。 + +応答を必要としないメッセージを送信するには以下のようにします: > + call sendraw(handle, {string}, 0) +プロセス(訳注:サーバーのこと)はレスポンスを返し、チャンネルのハンドラーに渡さ +れます。 + +メッセージを送信し、レスポンスを特定の関数で非同期的に取り扱うには以下のように +します: > + call sendraw(handle, {string}, {callback}) + +この {string} はJSONにもできます。その場合 |jsonencode()| それを作成し +|jsondecode()| で受信したJSONメッセージを取り扱います。 + +============================================================================== +6. ジョブ制御 *job-control* + +ま　だ　実　装　さ　れ　て　い　ま　せ　ん + +別のプロセスを開始するには: > + call startjob({command}) + +これは {command} の終了を待ちません。 + +TODO: + + let handle = startjob({command}, 's') # 標準入出力を使う + let handle = startjob({command}, '', {address}) # ソケットを使う + let handle = startjob({command}, 'd', {address}) # 接続に失敗したら開始 + + + vim:tw=78:ts=8:ft=help:norl: diff --git a/doc/cmdline.jax b/doc/cmdline.jax index ca782a4df..c3b76458d 100644 --- a/doc/cmdline.jax +++ b/doc/cmdline.jax @@ -1,4 +1,4 @@ -*cmdline.txt* For Vim バージョン 7.4. Last change: 2013 Mar 16 +*cmdline.txt* For Vim バージョン 7.4. Last change: 2015 Dec 17 VIMリファレンスマニュアル by Bram Moolenaar @@ -52,7 +52,7 @@ Note キーボードに有効なカーソルキーまたは他の特殊なキー - インプット行 (関数 |input()| に対して入力されたテキスト) 用 - デバッグモードコマンド用 これらは全く別のものである。それぞれの履歴は同種の入力をしたときだけ使用できる。 -オプション 'history' で保存されるコマンド数を設定できる (既定値: 20)。 +オプション 'history' で保存されるコマンド数を設定できる (既定値: 50)。 NOTE: - 以前と全く同じコマンドを打ち込んだときは、古い方の記録が消される (繰り返され たコマンドが古いコマンドの履歴を追い出して消すのを避けるため)。 @@ -95,6 +95,11 @@ CTRL-E または *c_CTRL-E* *c_* *c_End* *c_* カーソルをマウスでクリックした所へ移動する + *c_* + クリップボード(X11 ではプライマリ選択)の内容を貼り付ける。これ + は CTRL-R * を使った動作に似ているが、行間に CR は挿入されな + い。 + CTRL-H *c_* *c_CTRL-H* *c_BS* カーソル前の文字を削除する ( キーが思い通り働かないときは |:fixdel| を参照)。 @@ -336,6 +341,9 @@ CTRL-] 文字を挿入することなく短縮入力を展開する。{Vi に 全履歴の最近の5項目を一覧表示する。 > :history all -5, +:keepp[atterns] {command} *:keepp* *:keeppatterns* + 検索履歴に何も加えずに、{command} を実行する。 + ============================================================================== 2. コマンドラインの補完 *cmdline-completion* @@ -424,7 +432,7 @@ tcshのautolist補完が好みなら、オプション 'wildmode' を使って ".bak,~,.o,.h,.info,.swp" であり、これは ".bak", "~", ".o", ".h", ".info", ".swp" で終わるファイルが無視されることがあるということである。 -空の項目(つまり2つの連続するカンマ)は "." を含まないファイル名(つまり拡張子を +空の項目(つまり2つの連続するコンマ)は "." を含まないファイル名(つまり拡張子を 持たない)にマッチする。これは "prog" を無視させ、かつ "prog.c" にマッチさせた いときに便利である。 @@ -483,6 +491,8 @@ Exコマンドはいくつかの特徴を持っている。 :argdo :autocmd :bufdo + :cdo + :cfdo :command :cscope :debug @@ -493,6 +503,8 @@ Exコマンドはいくつかの特徴を持っている。 :help :helpfind :lcscope + :ldo + :lfdo :make :normal :perl @@ -568,7 +580,7 @@ Amigaでは、引数がファイル名1個になるはずのとき、空白を コマンドで特別な文字 '"', '|' を使いたいとき、あるいはファイル名に '%', '#' を 使いたいときは、'\' を前に置く。範囲指定やコマンド ":substitute" では '\' は必 -要ない。 +要ない。|`=| も参照のこと。 *:_!* Exコマンドの後に文字 '!' (bang) を置くと、コマンドの動作方法が変わる。'!' はコ @@ -633,7 +645,7 @@ Exコマンドには、その前に行単位の範囲を指定できるものが |:pop| 等) では確かに 0 として使われる。0 を「先頭行の前」として解釈するコマン ドもある (|:read|, 検索パターン等)。 -Examples: > +例: > .+3 カーソルの3行下 /that/+1 次行より下の、"that" を含む行 .,$ 現在行からファイル末尾まで @@ -709,12 +721,13 @@ Note: 以下はコマンドラインの実行における特別な文字であ 表す。CTRL-R %とするとその場に現在のファイル名を挿入する。|c_CTRL-R|を参照。 Note: Vim スクリプト内で特別な文字をエスケープするには |fnameescape()| を使う -とよいかもしれない。 +とよいかもしれない。|`=| も参照のこと。 Exコマンドの、ファイル名が使えるところでは、以下の文字は特別な意味を持つ。これ らは式や関数 |expand()| 内でも使うことができる。 % カレントファイル名に置き換えられる。 *:_%* *c_%* # 代替ファイル名に置き換えられる。 *:_#* *c_#* + これはウィンドウごとに記憶される。 #n (ここで n は数) バッファ n のファイル名に置き *:_#0* *:_#n* 換えられる。"#0" は "#" と同じ。 *c_#n* ## 引数リスト内の全てのファイル名を、空白で区切って *:_##* *c_##* @@ -749,6 +762,7 @@ Note: "#* *:* *:* ** *:* ** *:* ** @@ -766,21 +780,22 @@ Note: これらは文字通りに打ち込まれる、これらは特別なキ ない) 自動コマンドの実行時、この自動コマンドが実行されたときのマッ チに置き換えられる。そのファイル名がマッチの検索に使われて - いないときのみ、 と違う値になる (イベント FileType - や Syntax、SpellFileMissing 用)。 + いないときのみ、 と違う値になる (イベント FileType、 + Syntax、SpellFileMissing 用)。 コマンド ":source" の実行時、取り込まれたファイルのファイル - 名に置き換えられる。 *E498* - 関数の実行時、"関数 {関数名}" に置き換えられる。関数呼び出 - しのネスト (入れ子状態) はこのように表される: - "関数 {関数名1}..{関数名2}"。 Note: 関数内で が使わ - れている場合、ファイル名修飾子は無効になることに注意。 - コマンド ":source" の実行時、行番号に置き換えられる。 - *E842* + 名に置き換えられる。 *E498* + 関数の実行時はこのように置き換えられる: + "function {関数名}[{行番号}]" + 関数呼び出しのネスト (入れ子状態) はこのように表される: + "function {関数名1}[{行番号}]..{関数名2}[{行番号}]" + Note 関数内で が使われている場合、ファイル名修飾子 + は無効になることに注意。 + コマンド ":source" の実行時、行番号に置き換えられる。*E842* 関数の中では、関数の先頭からの相対的な行番号になる。 *filename-modifiers* - *:_%:* *::8* *::p* *::.* *::~* *::h* *::t* *::r* *::e* *::s* *::gs* - *%:8* *%:p* *%:.* *%:~* *%:h* *%:t* *%:r* *%:e* *%:s* *%:gs* +*:_%:* *::8* *::p* *::.* *::~* *::h* *::t* *::r* *::e* *::s* *::gs* *::S* + *%:8* *%:p* *%:.* *%:~* *%:h* *%:t* *%:r* *%:e* *%:s* *%:gs* *%:S* ファイル名修飾子は "%", "#", "#n", "", "", "", "" の後で使うことができる。これらは関数 |fnamemodify()| と使うこともできる。Vim が |+modify_fname| 機能付きでコンパイルされていなければ、これらの修飾子を使う @@ -792,7 +807,7 @@ Note: これらは文字通りに打ち込まれる、これらは特別なキ レクトリ名に展開されるならば、パスの区切り文字が末尾に追加され る。これが付けられたものが、ディスク上に存在せず絶対パスを持た ないファイルに展開されるときは、結果は予期できない。MS-Windows - では 8.3 形式のファイル名はロングファイル名に展開されます。 + では 8.3 形式のファイル名はロングファイル名に展開される。 :8 パスを短い8.3形式に変換する (現在のところ MS-Windows 版での み)。パスの内、実際に存在する部分に対して機能する。 :~ ファイル名をホームディレクトリについて相対的な名前に (可能なら @@ -833,6 +848,10 @@ Note: これらは文字通りに打ち込まれる、これらは特別なキ :gs?pat?sub? "pat" に一致したものを全て "sub" に置き換える。その他の点では ":s" と同様に機能する。 + :S シェルコマンドで利用できるように特別な文字をエスケープする。 + (|shellescape()|を参照)。最後でなければならない。例: > + :!dir :S + :call system('chmod +w -- ' . expand('%:S')) ファイル名が "src/version.c"、カレントディレクトリが "/home/mool/vim" のときの 例: > @@ -882,9 +901,8 @@ Vim version 3.0 との下位互換性のために残されており、":r" 形 Note: ファイル名が来る筈の所では、ワイルドカードの展開が行われる。Unixでは展開 にはシェルが使われる。ただしVim内部でできない展開だけである (スピードのため)。 -バッククォート '`' も次のように使える。 > +|restricted-mode| でなければ、バッククォート '`' も次のように使える。 > :n `echo *.c` -(バッククォートの展開は |restricted-mode| ではできない) しかし展開は、'%' や '#' 等が展開される前にワイルドカードが存在したときにのみ 行われる。これはファイル名に含まれるワイルドカードを展開しないためである。 の結果を展開したいときは、ワイルドカードの文字を追加すればよい。 @@ -895,6 +913,7 @@ Note: ファイル名が来る筈の所では、ワイルドカードの展開 :e #.* :e {"?readme?.*" にマッチしたファイル全て} :cd :cd {カーソル下のファイル名} :cd * :cd {カーソル下のファイル名に "*" を加え展開したもの} +|`=| も参照のこと。 展開された後のコマンド引数に "!" に含まれていて、それがシェルコマンドに使われ る (":!cmd", ":r !cmd" や ":w !cmd") とき、"!" は '\' でエスケープされ、前回の @@ -919,6 +938,8 @@ Note: ファイル名が来る筈の所では、ワイルドカードの展開 /\$home ルートディレクトリのファイル "$home" \\$home "\\" の後に $home の値を付け加えた名前のファイル +|`=| も参照のこと。 + ============================================================================== 7. コマンドラインウィンドウ *cmdline-window* *cmdwin* *command-line-window* @@ -1031,6 +1052,9 @@ Note: ノーマルモードで を打ち込むと、カーソルの次の ドウ自身のステータスラインはドラッグできる。上向きにずっとドラッグすると、直上 のウィンドウのステータスラインも動き、コマンドラインウィンドウがさらに広くなる。 +|getcmdwintype()| 関数は開いているコマンドラインの種類を返す。値の説明は +|cmdwin-char| 参照。 + 自動コマンド の 適 用 diff --git a/doc/debug.jax b/doc/debug.jax index 39fa0f3e1..e36ff911c 100644 --- a/doc/debug.jax +++ b/doc/debug.jax @@ -80,7 +80,7 @@ Microsoft Visual C++ コンパイラを使って自分で実行ファイルを 他の方法もあります。ソースファイルを入手し、Visual Studio のワークスペースに Make_ivc.mak を取り込んでください。そして、デバッグの設定を選択し、ビルドして -ください。ブレイクポイントの設定や変数の監視など、すべてのデバッグ機能が使えま +ください。ブレークポイントの設定や変数の監視など、すべてのデバッグ機能が使えま す。 Visual Studio を持っている場合はそれを使ってください。VC Toolkit と WinDbg は diff --git a/doc/debugger.jax b/doc/debugger.jax index 3fd82aca7..29d19c6b9 100644 --- a/doc/debugger.jax +++ b/doc/debugger.jax @@ -104,7 +104,7 @@ XmNballoonEvalBackground, XmNballoonEvalForeground)。 2. Vimのコンパイルオプション *debugger-compilation* デバッガ機能はSunの「Visual WorkShop Integrated Programming Environment」(ipe) -と一緒に使うために明示的に加えられた。しかし、それらのSunのipeと供に使用する機 +と一緒に使うために明示的に加えられた。しかし、それらのSunのipeと共に使用する機 能は他のデバッガも一部もしくは全部を使うことができるように、可能な限り一般的な 様式で実現されている。 diff --git a/doc/develop.jax b/doc/develop.jax index 6eca032cc..29bf62342 100644 --- a/doc/develop.jax +++ b/doc/develop.jax @@ -1,4 +1,4 @@ -*develop.txt* For Vim バージョン 7.4. Last change: 2013 Apr 27 +*develop.txt* For Vim バージョン 7.4. Last change: 2016 Jan 19 VIMリファレンスマニュアル by Bram Moolenaar @@ -168,13 +168,30 @@ Vimのソースコードに変更を加える際、守るべきルールがあ MAKING CHANGES *style-changes* コードに変更を加える基本的なステップは: -1. ドキュメントを調整する。最初にこれをやることで、あなたの行う変更がユーザー +1. GitHub からコードを取得する。これによりあなたが変更したコードをメインのコー + ドベースに同期するのがより簡単になる (あなたの変更がメインのコードベースに含 + まれるようになるまで少しかかるかもしれない) 。いくらか時間を費やして git に + ついて学ぶ必要がある。git はあまりユーザーフレンドリーなツールではない。 +2. ドキュメントを調整する。最初にこれをやることで、あなたの行う変更がユーザー に与える影響について、おおまかな印象をもつことができる。 -2. ソースコードに変更を加える。 -3. 変更がリストされた項目に影響を与えていないか、../doc/todo.txtをチェックす +3. ソースコードに変更を加える。 +4. 変更がリストされた項目に影響を与えていないか、../doc/todo.txtをチェックす る。 -4. 無修正のコードとドキュメントに対するパッチを、"diff -c" によって得る。 -5. 変更に関する注意書きを作り、パッチに含める。 +5. "git diff" でパッチを作成する。GitHub でプルリクエストを作成しても良いが、重 + 要なのはその diff である。 +6. 何が変更されたかのノートを作成する。問題点とその解決策について書かれている + のが望ましい。vim-dev のメーリングリストに説明と diff を含めたメールを送るか + GitHub でプルリクエストを作成する。 + + +C COMPILER *style-compiler* + +サポートされている最小の C コンパイラのバージョンは C89 (ANSI C とも呼ばれてい +る) である。C89 以降の標準規格にはあまり多くの機能追加が無く C89 はもっとも普及 +している。 + +この項目が暗に示している制限の1つとして、 // コメントではなく /* コメント */ を +使わなければならない。 USE OF COMMON FUNCTIONS *style-functions* @@ -200,7 +217,7 @@ NAMES *style-names* 関数の名前に31文字より長い名前は使えない。(VMSのために) -"delete" という名前の変数を使わないこと。C++で問題となる。 +"delete" や "this" という名前の変数を使わないこと。C++で問題となる。 Vimができる限り多くのシステム上で走るという必要上、システムによってすでに定義 されている名前を使うことは避けねばならない。これは、問題となることが知られて @@ -290,6 +307,25 @@ OK: do a = 1; while (cond); +間違い: if (cond) { + cmd; + cmd; + } else { + cmd; + cmd; + } + +OK: if (cond) + { + cmd; + cmd; + } + else + { + cmd; + cmd; + } + 関数は次のようにして始める: @@ -303,9 +339,9 @@ OK: /* * 戻り値の説明。 */ int - function_name(arg1, arg2) - int arg1; /* short comment about arg1 */ - int arg2; /* short comment about arg2 */ + function_name( + int arg1, /* short comment about arg1 */ + int arg2) /* short comment about arg2 */ { int local; /* comment about local */ @@ -327,7 +363,7 @@ if、while、switchなどの後には、スペースを入れること。 間違い: if(arg) for(;;) OK: if (arg) for (;;) -カンマ、セミコロンの後にはスペースを入れること: +コンマ、セミコロンの後にはスペースを入れること: 間違い: func(arg1,arg2); for (i = 0;i < 2;++i) OK: func(arg1, arg2); for (i = 0; i < 2; ++i) diff --git a/doc/diff.jax b/doc/diff.jax index b6429c233..18eb82023 100644 --- a/doc/diff.jax +++ b/doc/diff.jax @@ -1,4 +1,4 @@ -*diff.txt* For Vim バージョン 7.4. Last change: 2012 Sep 05 +*diff.txt* For Vim バージョン 7.4. Last change: 2015 Nov 01 VIMリファレンスマニュアル by Bram Moolenaar @@ -93,7 +93,7 @@ Vimが各ファイルについてウィンドウを開く時に起こること :difft[his] 現在のウィンドウを差分ウィンドウの1つにする。これにより "vimdiff" と同じオプションが設定される。 -:diffp[atch] {patchfile} *E816* *:diffp* *:diffpatch* +:diffp[atch] {patchfile} *E816* *:diffp* *:diffpatch* {patchfile}内の差分情報を現在のバッファへ適用し、結果を新しく 作成したバッファへ出力する。オプションは "vimdiff" と同様に設 定される。 @@ -122,14 +122,20 @@ Vimが各ファイルについてウィンドウを開く時に起こること また同じファイルへ戻って再び差分モードを継続することができる。 *:diffo* *:diffoff* -:diffo[ff] カレントウィンドウの差分モードを終了する。 +:diffo[ff] カレントウィンドウの差分モードを終了する。'diff' が設定されて + いてもいなくても、関連オプションはリセットされる。 :diffo[ff]! カレントウィンドウとカレントタブページのすべてのウィンドウの差 - 分モードを終了する。 + 分モードを終了する。'diff' が設定されているウィンドウのみ、関 + 連オプションがリセットされる。カレントウィンドウの 'diff' オプ + ションが設定されていない場合は、そのウィンドウの関連オプション + は変更されない。 -コマンド ":diffoff" は関連するオプションをデフォルト値に戻す。 -これは差分モードが開始する前の値とは異なるかもしれない。その古い値は記憶され -ていない。 +コマンド `:diffoff` は関連するオプションを差分モード実行前の設定値に戻す。それ +は `:diffsplit`、`:diffpatch`、`:diffthis` を実行したときの設定値、または Vim +を差分モードで起動したときの設定値である。`:diffoff` を2回実行したときは最後に +保存された値が復元される。 +それ以外の場合はデフォルト値に戻す: 'diff' off 'scrollbind' off @@ -174,8 +180,8 @@ Vimが各ファイルについてウィンドウを開く時に起こること 閉じることができる。そのときバッファを差分対象から外したいならば、隠れバッファ にする前に ":set nodiff" をする。 - *:diffu* *:diffupdate* -:diffu[pdate][!] 差分の強調と折り畳みを更新する。 + *:dif* *:diffupdate* +:dif[fupdate][!] 差分の強調と折り畳みを更新する。 テキストを変更した時には、Vimは差分情報を最新に保とうと試みる。これの大部分は 挿入と削除をされた行 (複数も可) に着目して行われる。1行内で行われた変更、及び @@ -257,13 +263,17 @@ Vimは片方のウィンドウには存在しないがもう一方には存在 [range]については以下を参照。 *do* -do 引数と範囲のない ":diffget" と同じ。"o" は "obtain" の意味 - ("dgg" と区別できないので、"dg" は使えない)。 - Note: これはビジュアルモードでは機能しない。 +[count]do 範囲のない ":diffget" と同じ。"o" は "obtain" の意味 ("dgg" と + 区別できないので、"dg" は使えない)。Note: これはビジュアル + モードでは機能しない。 + [count] を与えた場合、それは ":diffget" に対して [bufspec]引数 + として用いられる。 *dp* -dp 引数と範囲のない ":diffput" と同じ。 - Note: これはビジュアルモードでは機能しない。 +[count]dp 範囲のない ":diffput" と同じ。Note: これはビジュアルモードでは + 機能しない。 + [count] を与えた場合、それは ":diffput" に対して [bufspec]引数 + として用いられる。 [range]が与えられない場合にはカーソルの位置かその上の差分が適用される。[range] @@ -301,6 +311,19 @@ dp 引数と範囲のない ":diffput" と同じ。 |'diffopt'| と |'fillchars'| の "diff" 項目も参照。 + *diff-slow* *diff_translations* +行がとても長いと diff 構文ハイライトが遅くなるかもしれない。その場合は特にたく +さんの異なったローカライゼーションをマッチしようと試みるからである。ローカライ +ゼーションを無効化して構文ハイライトを高速化するには、グローバル変数 +g:diff_translations を 0 に設定する: > + + let g:diff_translations = 0 +< +この変数を設定した後、構文スクリプトを再読み込みする: > + + set syntax=diff +< + 差分を発見する *diff-diffexpr* diff --git a/doc/digraph.jax b/doc/digraph.jax index e64b11e6f..cc21bc253 100644 --- a/doc/digraph.jax +++ b/doc/digraph.jax @@ -1,4 +1,4 @@ -*digraph.txt* For Vim バージョン 7.4. Last change: 2011 Jan 15 +*digraph.txt* For Vim バージョン 7.4. Last change: 2014 Jun 19 VIMリファレンスマニュアル by Bram Moolenaar @@ -144,7 +144,7 @@ Vimには標準のダイグラフキャラクタがある。それらを見る Two 2 Hook Nine 9 Horn - Equals = Cyrillic + Equals = Cyrillic (= used as second char) Asterisk * Greek Percent sign % Greek/Cyrillic special Plus + smalls: Arabic, capitals: Hebrew @@ -166,6 +166,11 @@ Vimには標準のダイグラフキャラクタがある。それらを見る (iso-8859-15) ではダイグラフ =e がユーロ記号になっている。どちらでもその文字 は 164, 0xa4 である。zsh との互換性のために、Eu でもユーロ記号になる。 +ルーブル + +ルーブル記号は 2014 年に 0x20bd として追加された。Vim はダイグラフ =R と =P と +してそれをサポートしている。Note: R= と P= は別の文字である。 + *digraph-table* char digraph hex dec official name ~ ^@ NU 0x00 0 NULL (NUL) @@ -963,6 +968,8 @@ char digraph hex dec official name ~ ₧ Pt 20A7 8359 PESETA SIGN ₩ W= 20A9 8361 WON SIGN € Eu 20AC 8364 EURO SIGN +₽ =R 20BD 8381 ROUBLE SIGN +₽ =P 20BD 8381 ROUBLE SIGN ℃ oC 2103 8451 DEGREE CELSIUS ℅ co 2105 8453 CARE OF ℉ oF 2109 8457 DEGREE FAHRENHEIT @@ -1074,7 +1081,7 @@ char digraph hex dec official name ~ ⊥ -T 22A5 8869 UP TACK ⋅ .P 22C5 8901 DOT OPERATOR ⋮ :3 22EE 8942 VERTICAL ELLIPSIS -⋯ .3 22EF 8943 MIDLINE HORIZONTAL ELLIPSIS +⋯ .3 22EF 8943 MIDLINE HORIZONTAL ELLIPSIS ⌂ Eh 2302 8962 HOUSE ⌈ <7 2308 8968 LEFT CEILING ⌉ >7 2309 8969 RIGHT CEILING diff --git a/doc/editing.jax b/doc/editing.jax index bbc1ff810..e14211d2f 100644 --- a/doc/editing.jax +++ b/doc/editing.jax @@ -1,4 +1,4 @@ -*editing.txt* For Vim バージョン 7.4. Last change: 2013 Aug 03 +*editing.txt* For Vim バージョン 7.4. Last change: 2016 Jan 17 VIMリファレンスマニュアル by Bram Moolenaar @@ -34,22 +34,22 @@ コマンドラインでは "%" で表せる。|:_%| *alternate-file* -カレントファイル名が既に存在したときは、前の方は「オルタネートファイル名」にな -る。これはコマンドラインでは "#" で表され|:_#|、|CTRL-^|を使うとカレントファイル -とオルタネートファイルを切り替えることが出来る。ただし|:keepalt|を使ったときは -オルタネートファイル名は変わらない。 +カレントファイル名が既に存在したときは、前の方は「代替ファイル名」になる。これ +はコマンドラインでは "#" で表され|:_#|、|CTRL-^|を使うとカレントファイルと代替 +ファイルを切り替えることが出来る。ただし|:keepalt|を使ったときは代替ファイル名 +は変わらない。代替ファイル名はウィンドウごとに記憶される。 *:keepalt* *:keepa* -:keepalt {cmd} 現在のオルタネートファイル名を変えずに{cmd}を実行する。 - Note 間接的に呼び出されるコマンド(例えば関数によって) - はオルタネートファイル名を変えてしまう。{Vi にはない} +:keepalt {cmd} 現在の代替ファイル名を変えずに{cmd}を実行する。Note 間 + 接的に呼び出されるコマンド(例えば関数によって)は代替 + ファイル名を変えてしまう。{Vi にはない} 全てのファイル名はバッファリストに記憶される。編集 (例えば ":e filename") や保 存(例えば ":w filename") のためにファイル名を入力すると、そのファイル名がリス トに追加される。このリストを使えば、どのファイルを編集したかを覚えておいたり、 コマンド CTRL-^ によってあるファイルから別のファイルへ素早く移行できる (例えば テキストをコピーするとき)。まずファイルの番号を、次に CTRL-^ を打ち込む。{Vi: -オルタネートファイル名は1個だけ使える} +代替ファイル名は1個だけ使える} CTRL-G または *CTRL-G* *:f* *:fi* *:file* :f[ile] カレントファイル名 (これは ":cd" が使われたとき以外は @@ -78,6 +78,7 @@ g CTRL-G カーソルの現在の位置を、列、行、単語、文字、バ 例えば、タブ幅 'tabstop' が8のとき、行頭の の次 では「実際」の列番号は2、画面上の列番号は9となり、 "1-8" と表示される}。オプション 'ruler' も参照。 + オプション 'ruler' と |wordcount()| 関数も参照。 {Vi にはない} *v_g_CTRL-G* @@ -91,7 +92,7 @@ g CTRL-G カーソルの現在の位置を、列、行、単語、文字、バ *:file_f* :f[ile][!] {name} カレントファイル名を {name} に設定する。!をつけると |:file|のようにメッセージを切り詰めなくなる。 - バッファが名前を持つならその名前がオルタネートファイル名 + バッファが名前を持つならその名前が代替ファイル名 |alternate-file|になる。元の名前を保持するためにリスト されない(unlisted)バッファが作成される。 *:0file* @@ -226,8 +227,8 @@ Vim はバッファが変更されたかどうかを記憶していて、変更 :e[dit] [++opt] [+cmd] #[count] [count] 番目のバッファ (コマンド |:files| で表示される もの) を開く。このコマンドは [count] CTRL-^ と同じであ - る。しかしオルタネートバッファがファイル名を持たないと - ":e #" は機能しないが、CTRL-^ はそのときも機能する。 + る。しかし代替バッファがファイル名を持たないと":e #" + は機能しないが、CTRL-^ はそのときも機能する。 |++opt| と |+cmd| も参照。 {Vi: ++opt は使えない} @@ -278,19 +279,18 @@ Vim はバッファが変更されたかどうかを記憶していて、変更 してオプション 'readonly' をオンにする。{Vi にはない} *CTRL-^* *CTRL-6* -CTRL-^ オルタネートファイルを編集する。たいていの場合、オルタ - ネートファイルは前に編集したファイルである。これを使う - と2つのファイル間を素早く切り替えることができる。これ - は ":e #" と同じだが、対象のファイル名が無い場合も機能 - する。 - オプション 'autowrite' か 'autowriteall' がオンならば、 - バッファを移動するときに書き込みをする。 +CTRL-^ 代替ファイルを編集する。たいていの場合、代替ファイルは + 前に編集したファイルである。これを使うと2つのファイル + 間を素早く切り替えることができる。これは ":e #" と同じ + だが、対象のファイル名が無い場合も機能する。 + オプション 'autowrite' か 'autowriteall' がオンなら + ば、バッファを移動するときに書き込みをする。 たいていは "^" と "6" は同じキーである。CTRL を押しな がら 6 のキーを押せば CTRL-^ を押したのと同じ効果を得 られる。しかし英語配列でないキーボードでは他のキーが割 り当てられる。 -[count]CTRL-^ [count] 番目のオルタネートファイルを編集する (コマンド +[count]CTRL-^ [count] 番目の代替ファイルを編集する (コマンド ":e #[count]" と同じ)。[count] が指定されないと、前に 編集したファイルを編集する。これを使うと2つ (かそれ以 上) のファイル間を素早く行き来できる。 @@ -305,7 +305,8 @@ CTRL-^ オルタネートファイルを編集する。たいていの場合 覚え方: "goto file"。 オプション 'isfname' により、どの文字がファイル名に使 われるはずなのかを調べる。ファイル名に続く句読点の - ".,:;!" は無視される。 + ".,:;!" は無視される。エスケープされた複数のスペース + "\ " は1つのスペースに減らされる。 'path' により、ファイルを探すディレクトリ名のリストを 調べる。カレントファイルに対して相対的なファイルも探 される。 @@ -324,7 +325,7 @@ CTRL-^ オルタネートファイルを編集する。たいていの場合 うにする。 > :map gf :e < カーソル下のファイル名が "type://machine/path" のよう - なハイパーテキスト・リンクであるならば、プラグイン + なハイパーテキストリンクであるならば、プラグイン |netrw| が必要になる。 Unixでは、文字 '~' は "~user/file" のように展開される。 環境変数も展開される |expand-env|。 @@ -409,23 +410,33 @@ Note: いくつかのコマンドでは、この挙動が少し異なる。|file /usr/include/sys/types.h /usr/inc_old/types.h *backtick-expansion* *`-expansion* -Unix などではファイル名にバッククォート '`' も使える。例: > - :e `find . -name ver\\*.c -print` +Unix などではファイル名の引数にバッククォート '`' も使える。例: > + :next `find . -name ver\\*.c -print` + :view `ls -t *.patch \| head -n1` アスタリスク '*' の前の '\' は、シェルが find を実行する前に "ver*.c" を展開し -てしまうのを防ぐために必要となる。 +てしまうのを防ぐために必要となる。シェルのパイプ記号 "|" の前のバックスラッシ +ュは Vim がコマンドの終わりとしてパースするのを防ぐ。 これは、必ず項目全体がバッククォートで括られているという制限付きで、他の多くの システムでも機能する。最初のバッククォートの直前や最後のバッククォートの直後に 文字列を書くことはできない。 *`=* バッククォート内を、外部コマンドとしてではなく Vim の式として展開させることも -できる。そのためには `={expr}` という構文を使えばよい。例: > +できる。そのためには初めのバッククォートのすぐ後に等号を置けばよい。例: > :e `=tempname()` この式はほとんど何を含んでもよい。そのため、これを使って '"', '|', '%', '#' の 特別な意味を打ち消すこともできる。ただし、他のワイルドカードと同様に 'wildignore' は適用される。 + +この式の中の環境変数は式が評価される時に展開される。したがってこれは機能する: > + :e `=$HOME . '/.vimrc'` +これは機能しない。$HOME は文字列内にあり、文字通りに用いられる: > + :e `='$HOME' . '/.vimrc'` + 式が文字列を返したときは名前は改行で区切られる。式の結果がリスト (|List|) のと きは各要素が名前として扱われる。改行によっても名前は区切られる。 +Note そのような式はファイル名が Ex コマンドの引数として期待される場所でのみサ +ポートされる。 *++opt* *[++opt]* 引数のうち [++opt] はオプション 'fileformat', 'fileencoding' または @@ -604,8 +615,10 @@ Vim の開始時に複数のファイル名を与えると、それらは引数 |++opt| と |+cmd| も参照。 {Vi にはない} -:[count]arga[dd] {name} .. *:arga* *:argadd* - 引数リストに {name} を追加する。 +:[count]arga[dd] {name} .. *:arga* *:argadd* *E479* +:[count]arga[dd] + 引数リストに {name} を追加する。{name} が省略された時 + は引数リストに現在のバッファ名を追加する。 [count] が省かれると {name} は引数リストの現在の項目の 次に挿入される。指定されると [count] 番目の項目の次に 挿入される。引数リストが "a b c" で "b" が現在の引数の @@ -614,7 +627,9 @@ Vim の開始時に複数のファイル名を与えると、それらは引数 :argadd x a b x c :0argadd x x a b c :1argadd x a x b c - :99argadd x a b c x + :$argadd x a b c x + 最後の1つの後に: + :+2argadd y a b c x y 重複検査はないので、1個のファイルを引数リストに2回加え ることもできる。 現在編集中のファイルは変更されない。 @@ -636,11 +651,19 @@ Vim の開始時に複数のファイル名を与えると、それらは引数 < {Vi にはない} {Vimが |+listcmds| 機能付きでコンパイル されたときのみ有効} -:{range}argd[elete] 引数リストから {range} の範囲のファイルを削除する。 +:[range]argd[elete] 引数リストから {range} の範囲のファイルを削除する。 + 例: > + :10,$argdel +< 10以降が削除され、1から9は残る。 > + :$argd +< 最後の引数を削除する。 > + :argd + :.argd +< 現在の引数を削除する。 > + :%argd +< 引数リストから全てのファイルを削除する。 範囲の上限が大きすぎるときは、最後の引数までが削除され - る。例: > - :10,1000argdel -< とすると10以降が削除され、1から9は残る。 + る。 {Vi にはない} {Vimが |+listcmds| 機能付きでコンパイル されたときのみ有効} @@ -772,8 +795,8 @@ Unix およびその他いくつかのシステムではバッククォートも *arglist-position* 引数リストがあるときは、ウィンドウのタイトル (それがあって、オプション 'title' -オンならば) やコマンド CTRL-G で出るファイル・メッセージで編集しているファイル -を知ることができる。次のようなものが表示されるだろう。 +オンならば) やコマンド CTRL-G で出るファイルメッセージで編集しているファイルを +知ることができる。次のようなものが表示されるだろう。 (file 4 of 11) オプション 'shortmess' の値が 'f' を含んでいるときは以下のようになる。 (4 of 11) @@ -820,8 +843,9 @@ Unix およびその他いくつかのシステムではバッククォートも 引数リストを使う *:argdo* -:argdo[!] {cmd} 引数リスト内の全てのファイルで {cmd} を実行する。 - 以下と同様の動作になる。 > +:[range]argdo[!] {cmd} 引数リスト内の全てのファイルで {cmd} を実行する。また + は [range] が指定された場合、その範囲内の引数のみで実 + 行する。以下と同様の動作になる。 > :rewind :{cmd} :next @@ -841,7 +865,8 @@ Unix およびその他いくつかのシステムではバッククォートも になる。 {Vi にはない} {Vimが |+listcmds| 機能付きでコンパイル されたときのみ有効} - コマンド |:windo| や |:bufdo| も参照。 + |:windo|、|:tabdo|、|:bufdo|、|:cdo|、|:ldo|、|:cfdo|、 + |:lfdo|も参照。 例: > :args *.c @@ -911,16 +936,16 @@ Note: オプション 'write' がオフのときは、どのファイルも書 グに依存する。"+" が含まれている場合は、バッファがまだ元のファイルと異なってい たとしても、書き込みコマンドによって 'modified' フラグがオフになる。 -":w" にファイル名が与えられるとそれがオルタネートファイルになる。これは例えば -書き込みに失敗した後に ":w #" でもう一度試したいときに使える。オプション -'cpoptions' からフラグ 'A' を取り除くとこれを無効化できる。 +":w" にファイル名が与えられるとそれが代替ファイルになる。これは例えば書き込み +に失敗した後に ":w #" でもう一度試したいときに使える。オプション'cpoptions' か +らフラグ 'A' を取り除くとこれを無効化できる。 *:sav* *:saveas* :sav[eas][!] [++opt] {file} カレントファイルをファイル名 {file} として保存し、カレ ントバッファのファイル名を {file} に変える。それまでの - カレントファイルの名前はオルタネートファイルの名前にな - る。既存のファイルを上書きするには [!] が必要になる。 + カレントファイルの名前は代替ファイルの名前になる。既存 + のファイルを上書きするには [!] が必要になる。 'filetype' が空の場合、保存の前に新しいファイル名に対 してファイルタイプ検出が行われる。 保存が成功すると 'readonly' がオフになる。 @@ -1060,10 +1085,10 @@ MS-DOSとMS-Windowsでは、デバイスは名前から判断される: 5. 書き込みと終了 *write-quit* *:q* *:quit* -:q[uit] カレントウィンドウを閉じる。最後のウィンドウで使うとを +:q[uit] カレントウィンドウを閉じる。最後のウィンドウで使うと Vimを終了させる。変更点があってVimがカレントバッファを - 放棄 |abandon| しようとしないときや、引数リスト内で末 - 尾にないファイルを編集しているときには失敗する。 + 放棄 |abandon| しようとしないときや、引数リストの最後 + のファイルが編集されていないときは失敗する。 他のタブページが存在するとき、カレントタブページ内の最 後のウィンドウを閉じるとカレントタブページが閉じられる。 |tab-page| @@ -1074,9 +1099,12 @@ MS-DOSとMS-Windowsでは、デバイスは名前から判断される: コマンド |:confirm| やオプション 'confirm' を参照。 {Vi にはない} -:q[uit]! 可視なバッファに変更点があっても書き込みをせずに終了す - る。隠れバッファに変更点があると終了しない。必ず終了す - るにはコマンド ":qall!" を使うこと。 +:q[uit]! 現在のバッファに変更点があっても、書き込まずにVimを終 + 了する。そのウィンドウが最後の1つで、変更点のある隠し + バッファがある場合には、終了せずにカレントバッファを破 + 棄したあとで、最初の変更点がある隠しバッファを新たな現 + 在のバッファとする。 + 必ず終了するにはコマンド ":qall!" を使うこと。 :cq[uit] 書き込みをせずに必ず終了し、エラーコードを返す。コマン ド |:cq| を参照。Manx の QuickFix モードで使われる @@ -1236,7 +1264,7 @@ b:browsefilter はファイルタイププラグインで設定することが きる道を残すことだ。 Vim が browsefilter をサポートしていないときにそれを設定しないようにするには、 -has("browsefilter") が使えます: > +has("browsefilter") が使える: > if has("browsefilter") let g:browsefilter = "whatever" @@ -1350,12 +1378,24 @@ Vimはファイルを暗号化して保存し、再び読み取ることがで {Vimが |+cryptv| 機能付きでコンパイルされたときのみ有効} *E833* スワップファイルやアンドゥファイル内のテキストも暗号化される。 *E843* +しかしながら、これはブロック単位で実行されるので、より少ない時間でパスワードが +クラックされる可能性がある。スワップファイルを無効化することもできるが、クラッ +シュ時には作業内容が失われることになる。アンドゥファイルは無効化してもそれほど +の不利益はない。 > + :set noundofile + :noswapfile edit secrets Note: メモリ内のテキストは暗号化されない。ユーザーがテキストを編集している間、 システム管理者はそれを見ることができる。":!filter" や ":w !command" によって -フィルタに通しているときはテキストは暗号化されておらず、他人に見られる可能性が +フィルタに通しているときもテキストは暗号化されておらず、他人に見られる可能性が ある。'viminfo' ファイルは暗号化されない。 +機密テキストを編集するときは次のように設定するという手もある: > + :set noundofile viminfo= + :noswapfile edit secrets.txt +スワップファイルを無効化するとクラッシュまたは停電の時に編集内容が失われてしま +うので注意。 + 警告: 鍵の入力時にタイプミスをしてファイルを保存し、Vimを終了すると、テキスト は失われてしまう！ @@ -1378,23 +1418,38 @@ Note: メモリ内のテキストは暗号化されない。ユーザーがテ 暗号化を無効にするには、オプション 'key' に空の値を入れてリセットする。 > :set key= -'cryptmethod' オプションを設定することで暗号化メソッドを選択できる。次のうち -一つを使うこと: > - :setlocal cm=zip " 弱いメソッド。後方互換。 - :setlocal cm=blowfish " 強いメソッド。 +'cryptmethod' オプションを設定することで暗号化メソッドを選択できる。次の中から +選択できる: > + :setlocal cm=zip " 弱いメソッド。後方互換。 + :setlocal cm=blowfish " 脆弱性ありのメソッド + :setlocal cm=blowfish2 " 中強度のメソッド ファイルを保存する前に設定する。暗号化されたファイルを読み込んだとき、このオプ ションは自動的にファイル保存時に使われたメソッドに設定される。ファイルを保存す る前に 'cryptmethod' を変更することで使用するメソッドを変更できる。 + 新しいファイルに使われるデフォルトのメソッドを設定したい場合は |vimrc| ファイ -ルで次のどちらかを設定すること: > - set cm=zip - set cm=blowfish +ルで次を設定すること: > + set cm=blowfish2 +"blowfish2" の使用が強く推奨される。"blowfish2" をサポートしていない古いバージ +ョンの Vim を使わなければならない場合のみ、他のメソッドを使用する。 + ファイルを読み込んだり書き込んだりしたとき、zip なら "[crypted]"、blowfish な ら "[blowfish]" とメッセージが表示される。 アンドゥファイルが保存されるとき、同じキーとメソッドがアンドゥファイル内のテキ ストに適用される。|persistent-undo|。 +"blowfish" をサポートしているかどうかテストするには下記の条件を使う: > + has('crypt-blowfish') + has('crypt-blowfish2') +上記の条件が利用できるのは Vim 7.4.1099 からであるが、"blowfish" のサポート自体 +はより古くからある。 +よって上記の条件が偽になったとしても "blowfish" をサポートしていることがある。 +"blowfish" を使えるかどうかは次の条件でテストできる: > + v:version >= 703 +また "blowfish2" については次の条件でテストできる: > + v:version > 704 || (v:version == 704 && has('patch401')) +< *E817* *E818* *E819* *E820* 暗号化が正しく機能しないと、保存したファイルが後で読めなくなってしまう。そのた め、暗号化が期待したとおりに機能しているかどうかを確認するための検査が実行され @@ -1423,7 +1478,7 @@ Note: メモリ内のテキストは暗号化されない。ユーザーがテ 0 string VimCrypt~ Vim encrypted file >9 string 01 - "zip" cryptmethod >9 string 02 - "blowfish" cryptmethod - + >9 string 03 - "blowfish2" cryptmethod Note: - オプション 'charconvert' でコード変換をしているときには暗号化はできない。 @@ -1447,20 +1502,25 @@ Note: - Pkzip は 'cryptmethod' の "zip" と同じ暗号化を用いており、合衆国政府はその輸 出に対して異議を唱えていない。Pkzipの公開ファイル APPNOTE.TXT にはこのアルゴ リズムが詳細に記述されている。 +- 'cryptmethod' の "blowfish" の実装には脆弱性がある。ファイルの最初の 64 バイ + ト (条件によってはもっと) はクラック可能である。これの使用は推奨されないが、 + Vim 7.3 と 7.4 でサポートされている中ではそれが一番強度のあるメソッドであ + る。"zip" メソッドはさらに弱い。 - Vimはオランダに起源を持つ。そこがソースの出処である。従って、暗号化コードは アメリカ合衆国から輸出されてはいない。 ============================================================================== 10. タイムスタンプ *timestamp* *timestamps* -Vimは編集を始めたときのファイルの修正タイムスタンプを覚えている。これは同じ -ファイルの別のバージョンを (知らずに) 作ってしまうのを防ぐためである。 +Vimは編集を始めたときのファイルの修正タイムスタンプとモードとサイズを覚えてい +る。これは同じファイルの別のバージョンを (知らずに) 作ってしまうのを防ぐためで +ある。 シェルコマンド (|:!cmd| |suspend| |:read!| |K|) の実行後、ウィンドウ内の全ての -バッファでタイムスタンプが比較される。Vimは変更を受けたファイルに関して、イベ -ント |FileChangedShell| に関連付けられた任意の自動コマンドを実行するか、警告を -表示する。GUIを使っているときは、それらはVimに入力フォーカスが戻ってきたときに -行われる。 +バッファでタイムスタンプとファイルモードとファイルサイズが比較される。Vimは変 +更を受けたファイルに関して、イベント |FileChangedShell| に関連付けられた任意の +自動コマンドを実行するか、警告を表示する。GUIを使っているときは、それらはVimに +入力フォーカスが戻ってきたときに行われる。 *E321* *E462* ファイルがVimの外部で変更を受けたときに自動的に読み直して欲しいなら、オプショ @@ -1562,7 +1622,7 @@ Win32 でサマータイムが始まる日である。Win32 ライブラリに '**' はもっとすばらしい。 - これはディレクトリのみにマッチする。 - これはデフォルトで 30 段階までの深さのディレクトリにマッチするので、ディ - レクトリ・ツリー全体の検索に使える。 + レクトリツリー全体の検索に使える。 - マッチする深さの最大値は '**' の後に数字を付け加えて指定できる。 だから '/usr/**2' は下のようにマッチする。 > /usr diff --git a/doc/eval.jax b/doc/eval.jax index b3c6a1935..8a963561d 100644 --- a/doc/eval.jax +++ b/doc/eval.jax @@ -1,4 +1,4 @@ -*eval.txt* For Vim バージョン 7.4. Last change: 2013 May 21 +*eval.txt* For Vim バージョン 7.4. Last change: 2016 Jan 28 VIMリファレンスマニュアル by Bram Moolenaar @@ -6,18 +6,18 @@ Vimスクリプト *expression* *expr* *E15* *eval* -Vimスクリプトの利用についてはユーザーマニュアルの41章|usr_41.txt|でも解説されて -いる。 +Vimスクリプトの利用についてはユーザーマニュアルの41章|usr_41.txt|でも解説され +ている。 注意:Vimスクリプトはコンパイル時に無効化できる。もしそうなっているとこのドキュ メントに書かれている事は有効ではない。|+eval|と|no-eval-feature|を参照。 1. 変数 |variables| 1.1 変数の型 - 1.2 関数への参照 |Funcref| - 1.3 リスト |Lists| - 1.4 辞書 |Dictionaries| - 1.5 変数について補足 |more-variables| + 1.2 関数への参照 |Funcref| + 1.3 リスト |Lists| + 1.4 辞書 |Dictionaries| + 1.5 変数について補足 |more-variables| 2. 式の文法 |expression-syntax| 3. 内部変数 |internal-variables| 4. 組み込み関数 |functions| @@ -66,12 +66,14 @@ Funcref 関数への参照 |Funcref|。 数値 -1 --> 文字列 "-1" ~ *octal* 文字列から数値への変換は最初の数字を用いて数値に変換する。16進表記 "0xf9" や -8進表記 "017" も認識される。文字列が数字で始まらない場合結果は0となる。例: +8進表記 "017"、2進数表記の "0b10" も認識される。文字列が数字で始まらない場合結 +果は0となる。例: 文字列 "456" --> 数値 456 ~ 文字列 "6bar" --> 数値 6 ~ 文字列 "foo" --> 数値 0 ~ 文字列 "0xf1" --> 数値 241 ~ 文字列 "0100" --> 数値 64 ~ + String "0b101" --> Number 5 ~ 文字列 "-8" --> 数値 -8 ~ 文字列 "+8" --> 数値 0 ~ @@ -97,6 +99,9 @@ empty()を使用して次のようにする。 > 動的な変換は存在しない。文字列から浮動小数点数へは str2float() を使い、浮動小 数点数から文字列へは printf() を、浮動小数点数から数値へは float2nr() を使う。 + *E891* *E892* *E893* *E894* +When expecting a Float a Number can also be used, but nothing else. + *E706* *sticky-type-checking* 変数の型を変えようとするとエラーになる。このエラーを避けるには、まず|:unlet|す る必要がある。しかし文字列と数値は同値であると見なされる。同じく、浮動小数点数 @@ -117,7 +122,8 @@ empty()を使用して次のようにする。 > :echo Fn() < *E704* *E705* *E707* 関数参照の変数名は、大文字、"s:"、"w:"、"t:"、"b:" のいずれかで始めなければな -らない。関数参照と参照先の関数の名前を同じにすることはできない。 +らない。"g:" も使えるが、次に述べる名前は大文字で始めなければならない。関数参 +照と参照先の関数の名前を同じにすることはできない。 関数を定義して、それへの参照を直接辞書に入れるための特別な形式がある。例: > :function dict.init() dict @@ -139,7 +145,7 @@ empty()を使用して次のようにする。 > 1.3 リスト ~ - *List* *Lists* *E686* + *list* *List* *Lists* *E686* リストとは順序を保つ要素の列である。要素はどんな型でもよい。要素へはインデック ス番号を使ってアクセスする。列の任意の位置に要素を追加したり削除することができ る。 @@ -309,6 +315,7 @@ Note リストの比較について注意: 2つのリストは、同じ長さを 要素の順番を変更する: > :call sort(list) " リストをアルファベット順にソート :call reverse(list) " 要素の順序を反転させる + :call uniq(sort(list)) " ソートして重複を削除する for ループ ~ @@ -374,7 +381,7 @@ Note リストの全要素が同じ型でなければならない。そうでな 1.4 辞書 ~ - *Dictionaries* *Dictionary* + *dict* *Dictionaries* *Dictionary* 辞書とは連想配列である。各要素はキーと値を持つ。要素はキーによって特定できる。 要素は特に順序を持たずに保持される。 @@ -499,7 +506,7 @@ Note 辞書の要素間に順序は定まっていない。そのため ":echo a 関数に名前をつける必要をなくすために、関数を定義して直接辞書に代入することがで きる: > :let mydict = {'data': [0, 1, 2, 3]} - :function mydict.len() dict + :function mydict.len() : return len(self.data) :endfunction :echo mydict.len() @@ -834,9 +841,9 @@ expr8 がマルチバイト文字列である場合、この値は単なるバ とはならないかもしれないことに注意。マルチバイト文字列に対する代替方法は |byteidx()| を参照。 -インデックスが0の場合、先頭のキャラクタが得られることに注意。これはC言語のよう -に働く。注意:カラム番号は1から始まる。例えばカーソルの下の文字を得るためには、 -次のようにする必要がある: > +インデックスが0の場合、先頭のバイトが得られることに注意。これはC言語のように働 +く。注意:カラム番号は1から始まる。例えばカーソルの下のバイトを得るためには、次 +のようにする必要がある: > :let c = getline(".")[col(".") - 1] 文字列の長さよりも大きなインデックスが指定された場合、結果は空文字列になる。負 @@ -883,6 +890,11 @@ expr8がリストならば、インデックスexpr1aとexpr1bの間の要素か |Funcref|に対してexpr8[expr1]やexpr8[expr1a : expr1b]を使うとエラーになる。 +Watch out for confusion between a namespace and a variable followed by a colon +for a sublist: > + mylist[n:] " uses variable n + mylist[s:] " uses namespace s:, error! + expr8.name 辞書|Dictionary|の要素 *expr-entry* @@ -921,7 +933,7 @@ number 数定数 *expr-number* 浮動小数点数は次の2つの形式で書ける: [-+]{N}.{M} - [-+]{N}.{M}e[-+]{exp} + [-+]{N}.{M}[eE][-+]{exp} ここで {N} と {M} は数値である。{N} と {M} の両方とも省略してはならず、数値の みを含めることができる。 @@ -966,13 +978,13 @@ number 数定数 *expr-number* -文字列 *expr-string* *E114* +文字列 *string* *String* *expr-string* *E114* ------ "string" 文字列定数 *expr-quote* ダブルクォートが使われていることに注意。 -文字列定数には以下の特殊文字が使用できる: +文字列定数には以下の特殊文字が使用できる: \... 3桁の8進数字 (例 "\316") \.. 2桁の8進数字 (非数字が続かなければならない) \. 1桁の8進数字 (非数字が続かなければならない) @@ -982,7 +994,7 @@ number 数定数 *expr-number* \X. \x.に同じ \u.... 文字を4桁の16進数で表現したもので、実際の値は現在の 'encoding' の値に 依存する (例えば "\u02a4") -\U.... \u....に同じ +\U.... \u と同じだが8桁までの16進数が使える \b バックスペース \e エスケープ \f フォームフィード @@ -1002,7 +1014,7 @@ Note "\000" と "\x00" は強制的に文字列の終端として扱われる。 リテラル文字列 *literal-string* *E115* ---------------- +-------------- 'string' 文字列定数 *expr-'* Note シングルクォートが使われていることに注意。 @@ -1018,7 +1030,7 @@ Note シングルクォートが使われていることに注意。 オプション *expr-option* *E112* *E113* ------- +--------- &option オプション変数、ローカルなものが優先 &g:option グローバルオプション変数 &l:option ローカルオプション変数 @@ -1050,7 +1062,7 @@ Note シングルクォートが使われていることに注意。 環境変数 *expr-env* --------------------- +-------- $VAR 環境変数 環境変数の文字列。定義されていない環境変数を指定した場合、結果は空文字列。 @@ -1060,20 +1072,20 @@ Note $VARを直接使用した場合とexpand("$VAR")を使用した場合では れるだけである。expand()を使用した場合、まず最初にVimのセッション中で既知の値 に展開される。それが失敗した場合、変数の展開にシェルが使用されることになる。こ れは遅くはなるが、シェルの知りうる全ての変数を展開することができる。例: > - :echo $version - :echo expand("$version") -最初の一つは恐らく何も返ってこず、2つ目は$versionの値が返ってくるだろう(貴方の -シェルがサポートしていたとして) + :echo $shell + :echo expand("$shell") +最初の一つは恐らく何も返ってこず、2つ目は $shell の値が返ってくるだろう (貴方 +のシェルがそれをサポートしているなら) 内部変数 *expr-variable* ------------------ +-------- variable 内部変数 以下の|internal-variables|を参照。 関数呼出 *expr-function* *E116* *E118* *E119* *E120* -------------- +-------- function(expr1, ...) 関数呼出 以下の|functions|を参照。 @@ -1282,6 +1294,12 @@ v:cmdbang v:cmdargと同じく読み書きコマンドを実行したとき設 0となる。Note オートコマンドの中でのみ利用可能なことに注意。 ユーザー定義コマンドでは||を使えば同じことができる。 + *v:completed_item* *completed_item-variable* +v:completed_item + |Dictionary| containing the |complete-items| for the most + recently completed word after |CompleteDone|. The + |Dictionary| is empty if the completion failed. + *v:count* *count-variable* v:count 最後に実行されたノーマルモードコマンドに渡されたコマンドの実行 回数を返す。読出し専用。使用例: > @@ -1325,6 +1343,15 @@ v:errmsg 最後に表示されたエラーメッセージ。この変数は代 : ... < また "errmsg" は、以前の版のVimとの互換性の為に動作する。 + *v:errors* *errors-variable* +v:errors Errors found by assert functions, such as |assert_true()|. + This is a list of strings. + The assert functions append an item when an assert fails. + To remove old results make it empty: > + :let v:errors = [] +< If v:errors is set to anything but a list it is made an empty + list by the assert function. + *v:exception* *exception-variable* v:exception 最も直近に捕捉され、まだ終了していない例外の値。 |v:throwpoint|と|throw-variables|を参照。 @@ -1336,6 +1363,13 @@ v:exception 最も直近に捕捉され、まだ終了していない例外の :endtry < 出力: "caught oops". + *v:false* *false-variable* +v:false A Number with value zero. Used to put "false" in JSON. See + |jsonencode()|. + When used as a string this evaluates to "false". > + echo v:false +< false ~ + *v:fcs_reason* *fcs_reason-variable* v:fcs_reason |FileChangedShell|イベントが発生した理由。オートコマンドの中で 何をすべきかやv:fcs_choiceに何を代入すべきかを決めるために使う。 @@ -1409,6 +1443,16 @@ v:foldend 'foldtext' 用。閉じた折り畳みの最後の行。 v:foldstart 'foldtext' 用。閉じた折り畳みの最初の行。 サンドボックス|sandbox|の中では読出し専用。|fold-foldtext| + *v:hlsearch* *hlsearch-variable* +v:hlsearch 検索による強調表示がオンになっているかどうかを示す変数。 + 設定は |+extra_search| 機能が必要な 'hlsearch' が有効になって + いる時のみ意味をなす。この変数を0に設定することは、 + |:nohlsearch|コマンドを実行することと同様に働き、1に設定するこ + とは以下と同様に働く > + let &hlsearch = &hlsearch +< Note that the value is restored when returning from a + function. |function-search-undo|. + *v:insertmode* *insertmode-variable* v:insertmode オートコマンドイベント|InsertEnter|と|InsertChange|用。 値は次のどれか: @@ -1458,16 +1502,43 @@ v:mouse_col |getchar()|でマウスクリックイベントを取得したとき 桁番号が代入されている。|virtcol()|と同じく画面上の桁番号。マ ウスがクリックされていないときは0となる。 + *v:none* *none-variable* +v:none An empty String. Used to put an empty item in JSON. See + |jsonencode()|. + When used as a number this evaluates to zero. + When used as a string this evaluates to "none". > + echo v:none +< none ~ + + *v:null* *null-variable* +v:null An empty String. Used to put "null" in JSON. See + |jsonencode()|. + When used as a number this evaluates to zero. + When used as a string this evaluates to "null". > + echo v:null +< null ~ + *v:oldfiles* *oldfiles-variable* v:oldfiles 起動時に |viminfo| から読み込まれたファイルの名前のリスト。 これらはマークを記憶しているファイルである。リストの長さの上限 はオプション 'viminfo' の引数 ' によって決まる(既定では 100)。 + |viminfo| ファイルが使われていない時、リストは空となる。 |:oldfiles| と |c_#<| を参照。 このリストは変更可能であるが、後で |viminfo| ファイルに書き込ま れるものには影響しない。文字列以外の値を使うと問題を引き起こす だろう。 {|+viminfo| 機能つきでコンパイルされたときのみ有効} + *v:option_new* +v:option_new オプションに設定された新しい値。自動コマンド |OptionSet| を実 + 行している間のみ有効。 + *v:option_old* +v:option_old オプションの以前の値。自動コマンド |OptionSet| を実行している + 間のみ有効。 + *v:option_type* +v:option_type set コマンドのスコープ。自動コマンド |OptionSet| を実行している + 間のみ有効。"global" もしくは "local" のどちらかとなる。 + *v:operator* *operator-variable* v:operator ノーマルモードにおいて最後に実行したオペレータコマンド。基本的 に1文字である。例外は や で始まるコマンドで、その場合 @@ -1497,6 +1568,15 @@ v:profiling 通常時は0。":profile start" を実行すると1が代入され v:progname Vimを起動したときのプログラム名(パスは除かれる)。|view|、 |evim| などの名前やシンボリックリンクなどで起動した場合に特別な 初期化を行うのに便利。 + 読出し専用。 + + *v:progpath* *progpath-variable* +v:progpath Vim を起動したときのコマンド (パスを含む)。|--remote-expr| で + Vim サーバーにメッセージを送信するときに便利。 + フルパスを得るには: > + echo exepath(v:progpath) +< NOTE: これはコマンドが相対パスで、カレントディレクトリが変更さ + れたときは機能しない。 読出し専用。 *v:register* *register-variable* @@ -1602,20 +1682,26 @@ v:throwpoint 最も直近に捕捉されてまだ終了していない例外が :endtry < 出力: "Exception from test.vim, line 2" + *v:true* *true-variable* +v:true A Number with value one. Used to put "true" in JSON. See + |jsonencode()|. + When used as a string this evaluates to "true". > + echo v:true +< true ~ *v:val* *val-variable* v:val 辞書|Dictionary|の現在の要素の値。|map()|と|filter()|で使わ れる式を評価している最中のみ有効。 読出し専用。 - *v:version* *version-variable* + *v:version* *version-variable* v:version Vimのバージョン番号。メジャーバージョン番号は100倍され、マイ ナーバージョン番号と足されている。Version 5.0は500。Version 5.1 (5.01)は501となる。読出し専用。また "version" は、以前の版 のVimとの互換性の為に動作する。 特定のパッチが適用されているかを調べるには|has()|を使う。例: > - if has("patch123") -< 5.0と5.1には両方ともパッチ123が存在しているが、バージョンが違 - えば番号は同じでもパッチの内容は全く異なっている。 + if has("patch-7.4.123") +< Note 5.0と5.1には両方ともパッチ123が存在しているが、バージョン + が違えば番号は同じでもパッチの内容は全く異なっている。 *v:warningmsg* *warningmsg-variable* v:warningmsg 最後に表示された警告メッセージ。この変数は代入することが許され @@ -1633,19 +1719,31 @@ v:windowid X11 ベースの GUI を使っているとき、もしくは端末の ============================================================================== 4. 組み込み関数 *functions* -(関数名の上でCTRL-]を使うことで、詳細な説明へ飛ぶことができる) +機能別に分類された一覧は |function-list| を参照のこと。 + +(関数名の上でCTRL-]を使うことで、詳細な説明へ飛ぶことができる。) 使用法 結果 説明 ~ abs( {expr}) 浮動小数点数または数値 {expr}の絶対値 acos( {expr}) 浮動小数点数 {expr}のアークコサイン add( {list}, {item}) リスト {item}をリスト{list}に追加する +alloc_fail( {id}, {countdown}, {repeat}) + none make memory allocation fail and( {expr}, {expr}) 数値 ビット論理積 append( {lnum}, {string}) 数値 {string}を{lnum}行目に付け加える append( {lnum}, {list}) 数値 行{list}を{lnum}行目に付け加える argc() 数値 引数内のファイルの数 +argidx() 数値 引数リスト内の現在のインデックス +arglistid( [{winnr} [, {tabnr}]]) + 数値 引数リストID argv( {nr}) 文字列 引数の第{nr}番目 argv( ) リスト 引数リスト +assert_equal( {exp}, {act} [, {msg}]) none assert {exp} equals {act} +assert_exception({error} [, {msg}]) none assert {error} is in v:exception +assert_fails( {cmd} [, {error}]) none assert {cmd} fails +assert_false( {actual} [, {msg}]) none assert {actual} is false +assert_true( {actual} [, {msg}]) none assert {actual} is true asin( {expr}) 浮動小数点数 {expr}のアークサイン atan( {expr}) 浮動小数点数 {expr}のアークタンジェント atan2( {expr}, {expr}) 浮動小数点数 {expr1} / {expr2} のアークタン @@ -1657,10 +1755,11 @@ bufexists( {expr}) 数値 バッファ{expr}が存在すればTRUE buflisted( {expr}) 数値 バッファ{expr}がリストにあるならTRUE bufloaded( {expr}) 数値 バッファ{expr}がロード済みならTRUE bufname( {expr}) 文字列 バッファ{expr}の名前 -bufnr( {expr}) 数値 バッファ{expr}の番号 +bufnr( {expr} [, {create}]) 数値 バッファ{expr}の番号 bufwinnr( {nr}) 数値 バッファ{nr}のウィンドウ番号 byte2line( {byte}) 数値 {byte}番目のバイトの行番号 byteidx( {expr}, {nr}) 数値 {expr}の{nr}文字目のバイトインデックス +byteidxcomp( {expr}, {nr}) 数値 {expr}の{nr}文字目のバイトインデックス call( {func}, {arglist} [, {dict}]) 任意 引数{arglist}をつけて{func}を呼ぶ ceil( {expr}) 浮動小数点数 {expr} を切り上げる @@ -1673,20 +1772,22 @@ complete( {startcol}, {matches}) なし 挿入モード補完を設定する complete({startcol}, {matches}) 文字列 挿入モード補完の結果を設定する complete_add( {expr}) 数値 補完候補を追加する complete_check() 数値 補完中に押されたキーをチェックする -confirm( {msg}, {choices} [, {default} [, {type}]]) +confirm( {msg} [, {choices} [, {default} [, {type}]]]) 数値 ユーザーへの選択肢と番号 +connect( {address}, {mode} [, {callback}]) + Number open a channel copy( {expr}) 任意 {expr}の浅いコピーを作る cos( {expr}) 浮動小数点数 {expr} の余弦(コサイン) cosh( {expr}) 浮動小数点数 {expr}のハイパボリックコサイン -count( {list}, {expr} [, {start} [, {ic}]]) +count( {list}, {expr} [, {ic} [, {start}]]) 数値 {list}中に{expr}が何個現れるか数える cscope_connection( [{num} , {dbpath} [, {prepend}]]) 数値 cscope接続の存在を判定する -cursor( {lnum}, {col} [, {coladd}]) - 数値 カーソルを{lnum}, {col}, {coladd}へ移動 +cursor( {lnum}, {col} [, {off}]) + 数値 カーソルを{lnum}, {col}, {off}へ移動 cursor( {list}) 数値 カーソルを{list}の位置へ移動 -deepcopy( {expr}) 任意 {expr}の完全なコピーを作る -delete( {fname}) 数値 ファイル{fname}を消す +deepcopy( {expr} [, {noref}]) 任意 {expr}の完全なコピーを作る +delete( {fname} [, {flags}]) 数値 ファイルやディレクトリ{fname}を消す did_filetype() 数値 FileTypeのautocommandが実行されたか? diff_filler( {lnum}) 数値 差分モードで{lnum}に挿入された行 diff_hlID( {lnum}, {col}) 数値 差分モードで{lnum}/{col}位置の強調 @@ -1695,6 +1796,7 @@ escape( {string}, {chars}) 文字列 {string}内の{chars}を '\' でエスケ eval( {string}) 任意 {string}を評価し、値を得る eventhandler( ) 数値 イベントハンドラの内側ならTRUE executable( {expr}) 数値 実行可能な{expr}が存在するなら1 +exepath( {expr}) 文字列 コマンド {expr} のフルパス exists( {var}) 数値 変数{var}が存在したらTRUE extend( {expr1}, {expr2} [, {expr3}]) リスト/辞書 {expr1}に{expr2}の要素を挿入 @@ -1731,13 +1833,18 @@ getbufline( {expr}, {lnum} [, {end}]) リスト バッファ{expr}の{lnum}から{end}行目 getbufvar( {expr}, {varname} [, {def}]) 任意 バッファ{expr}の変数 {varname} +getchar( [expr]) Number get one character from the user +getcharmod( ) Number modifiers for the last typed character +getcharsearch() Dict last character search getcmdline() 文字列 現在のコマンドラインを取得 getcmdpos() 数値 コマンドラインのカーソル位置を取得 getcmdtype() 文字列 現在のコマンドラインの種類を取得 -getcwd() 文字列 現在の作業ディレクトリ +getcmdwintype() 文字列 現在のコマンドラインウィンドウの種類 +getcurpos() リスト カーソルの位置 +getcwd( [{winnr} [, {tabnr}]]) 文字列 現在の作業ディレクトリを取得 +getfontname( [{name}]) 文字列 使用しているフォントの名前 getfperm( {fname}) 文字列 ファイル{fname}の許可属性を取得 getfsize( {fname}) 数値 ファイル{fname}のバイト数を取得 -getfontname( [{name}]) 文字列 使用しているフォントの名前 getftime( {fname}) 数値 ファイルの最終更新時間 getftype( {fname}) 文字列 ファイル{fname}の種類の説明 getline( {lnum}) 文字列 現在のバッファから行の内容を取得 @@ -1747,7 +1854,8 @@ getmatches() リスト 現在のマッチのリスト getpid() 数値 Vim のプロセス ID getpos( {expr}) リスト カーソル・マークなどの位置を取得 getqflist() リスト quickfixリストの要素のリスト -getreg( [{regname} [, 1]]) 文字列 レジスタの中身を取得 +getreg( [{regname} [, 1 [, {list}]]]) + 文字列/リスト レジスタの中身を取得 getregtype( [{regname}]) 文字列 レジスタの種類を取得 gettabvar( {nr}, {varname} [, {def}]) 任意 タブ{nr}の変数{varname}または{def} @@ -1757,14 +1865,16 @@ getwinposx() 数値 GUI vim windowのX座標 getwinposy() 数値 GUI vim windowのY座標 getwinvar( {nr}, {varname} [, {def}]) 文字列 ウィンドウ{nr}の変数{varname} -glob( {expr} [, {nosuf} [, {list}]]) +glob( {expr} [, {nosuf} [, {list} [, {alllinks}]]]) 任意 {expr}内のfile wildcardを展開 -globpath( {path}, {expr} [, {flag}]) +glob2regpat( {expr}) 文字列 globパターンを検索パターンに変換 +globpath( {path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]]) 文字列 {path}の全ディレクトリに対し glob({expr})を行う has( {feature}) 数値 機能{feature}がサポートならばTRUE has_key( {dict}, {key}) 数値 {dict}が要素{key}を持つならTRUE -haslocaldir() 数値 現在のウィンドウで|:lcd|が実行された +haslocaldir( [{winnr} [, {tabnr}]]) + 数値 現在のウィンドウで|:lcd|が実行された ならTRUE hasmapto( {what} [, {mode} [, {abbr}]]) 数値 {what}へのマッピングが存在するならTRUE @@ -1792,6 +1902,8 @@ isdirectory( {directory}) 数値 {directory}がディレクトリならばTRUE islocked( {expr}) 数値 {expr}がロックされているならTRUE items( {dict}) リスト {dict}のキーと値のペアを取得 join( {list} [, {sep}]) 文字列 {list}の要素を連結して文字列にする +jsondecode( {string}) any decode JSON +jsonencode( {expr}) String encode JSON keys( {dict}) リスト {dict}のキーを取得 len( {expr}) 数値 {expr}の長さを取得 libcall( {lib}, {func}, {arg} 文字列 ライブラリ{lib}の関数{func}をコール @@ -1807,6 +1919,8 @@ luaeval( {expr}[, {expr}]) 任意 |Lua| の式を評価する map( {expr}, {string}) リスト/辞書 {expr}の各要素を{expr}に変える matchadd( {group}, {pattern}[, {priority}[, {id}]]) 数値 {pattern} を {group} で強調表示する +matchaddpos( {group}, {list}[, {priority}[, {id}]]) + 数値 位置を {group} で強調表示する maparg( {name}[, {mode} [, {abbr} [, {dict}]]]) 文字列/辞書 モード{mode}でのマッピング{name}の値 @@ -1832,6 +1946,7 @@ nextnonblank( {lnum}) 数値 {lnum}行目以降で空行でない行の行番 nr2char( {expr}[, {utf8}]) 文字列 ASCII/UTF8コード{expr}で示される文字 or( {expr}, {expr}) 数値 ビット論理和 pathshorten( {expr}) 文字列 path内の短縮したディレクトリ名 +perleval( {expr}) any evaluate |Perl| expression pow( {x}, {y}) 浮動小数点数 {x} の {y} 乗 prevnonblank( {lnum}) 数値 {lnum}行目以前の空行でない行の行番号 printf( {fmt}, {expr1}...) 文字列 文字列を組み立てる @@ -1859,6 +1974,8 @@ repeat( {expr}, {count}) 文字列 {expr}を{count}回繰り返す resolve( {filename}) 文字列 ショートカットが指す先のファイル名 reverse( {list}) 文字列 {list}をその場で反転させる round( {expr}) 浮動小数点数 {expr} を四捨五入する +screenattr( {row}, {col}) 数値 スクリーン位置の属性 +screenchar( {row}, {col}) 数値 スクリーン位置の文字 screencol() 数値 現在のカーソル列 screenrow() 数値 現在のカーソル行 search( {pattern} [, {flags} [, {stopline} [, {timeout}]]]) @@ -1871,11 +1988,16 @@ searchpairpos( {start}, {middle}, {end} [, {flags} [, {skip} [...]]]) リスト 開始/終端のペアの他方を検索 searchpos( {pattern} [, {flags} [, {stopline} [, {timeout}]]]) リスト {pattern}を検索 +sendexpr( {handle}, {expr} [, {callback}]) + any send {expr} over JSON channel {handle} +sendraw( {handle}, {string} [, {callback}]) + any send {string} over raw channel {handle} server2client( {clientid}, {string}) 数値 返信文字列を送信する serverlist() 文字列 利用可能なサーバーのリストを取得 setbufvar( {expr}, {varname}, {val}) バッファ{expr}内の変数{varname}に{val} をセット +setcharsearch( {dict}) Dict set character search from {dict} setcmdpos( {pos}) 数値 コマンドライン内のカーソル位置を設定 setline( {lnum}, {line}) 数値 行{lnum}に{line}(文字列)をセット setloclist( {nr}, {list}[, {action}]) @@ -1910,7 +2032,7 @@ split( {expr} [, {pat} [, {keepempty}]]) sqrt( {expr}) 浮動小数点数 {expr} の平方根 str2float( {expr}) 浮動小数点数 文字列を浮動小数点数に変換する str2nr( {expr} [, {base}]) 数値 文字列を数値に変換する -strchars( {expr}) 数値 文字列{expr}の文字の数 +strchars( {expr} [, {skipcc}]) 数値 文字列{expr}の文字の数 strdisplaywidth( {expr} [, {col}]) 数値 文字列{expr}の表示幅 strftime( {format}[, {time}]) 文字列 指定されたフォーマットでの時刻 stridx( {haystack}, {needle}[, {start}]) @@ -1924,7 +2046,8 @@ strridx( {haystack}, {needle} [, {start}]) クス strtrans( {expr}) 文字列 文字列を表示可能に変更 strwidth( {expr}) 数値 文字列{expr}の表示セル幅 -submatch( {nr}) 文字列 ":s" やsubstitute()における特定のマッチ +submatch( {nr}[, {list}]) 文字列/リスト + ":s" やsubstitute()における特定のマッチ substitute( {expr}, {pat}, {sub}, {flags}) 文字列 {expr}の{pat}を{sub}に置換え synID( {line}, {col}, {trans}) 数値 {line}と{col}のsyntax IDを取得 @@ -1935,6 +2058,7 @@ synconcealed( {lnum}, {col}) リスト Conceal の情報 synstack( {lnum}, {col}) リスト {lnum}行{col}列目における構文IDの スタック system( {expr} [, {input}]) 文字列 シェルコマンド{expr}の出力結果 +systemlist( {expr} [, {input}]) リスト シェルコマンド{expr}の出力結果 tabpagebuflist( [{arg}]) リスト タブページ内のバッファ番号のリスト tabpagenr( [{arg}]) 数値 現在または最後のタブページの番号 tabpagewinnr( {tabarg}[, {arg}]) @@ -1953,6 +2077,8 @@ trunc( {expr}) 浮動小数点数 浮動小数点数{expr}を切り詰める type( {name}) 数値 変数{name}の型 undofile( {name}) 文字列 {name}に対するアンドゥファイルの名前 undotree() リスト アンドゥファイルツリー +uniq( {list} [, {func} [, {dict}]]) + リスト リストから隣接した重複を削除 values( {dict}) リスト {dict}の値のリスト virtcol( {expr}) 数値 カーソルのスクリーンカラム位置 visualmode( [expr]) 文字列 最後に使われたビジュアルモード @@ -1966,7 +2092,8 @@ winrestcmd() 文字列 ウィンドウサイズを復元するコマンド winrestview( {dict}) なし 現在のウィンドウのビューを復元 winsaveview() 辞書 現在のウィンドウのビューを保存 winwidth( {nr}) 数値 ウィンドウ{nr}の幅を取得 -writefile( {list}, {fname} [, {binary}]) +wordcount() Dict get byte/char/word statistics +writefile( {list}, {fname} [, {flags}]) 数値 行のリストをファイル{fname}に書き込む xor( {expr}, {expr}) 数値 ビット排他的論理和 @@ -2035,6 +2162,18 @@ argc() カレントウィンドウの引数リスト内の、ファイルの数 argidx() 引数リスト内の現在のインデックスを返す。最初のファイルは0とな る。argc() - 1が最後のファイルとなる。|arglist|を参照。 + *arglistid()* +arglistid([{winnr}, [ {tabnr} ]]) + 引数リストの ID を返す。値は引数リストを区別するための数値であ + る。ゼロはグローバル引数リストを意味する。 |arglist| 参照。 + 引数が無効な場合は -1 を返す。 + + 引数を指定しなかった場合はカレントウィンドウが使われる。 + {winnr} を指定した場合はカレントタブページ内のウィンドウが使わ + れる。 + {winnr} と {tabnr} を指定した場合は指定したタブページ内のウィ + ンドウが使われる。 + *argv()* argv([{nr}]) 結果は引数リスト内の、{nr}番目のファイル。|arglist|を参照。 "argv(0)" は一番最初のファイルを示す。例: > @@ -2047,6 +2186,55 @@ argv([{nr}]) 結果は引数リスト内の、{nr}番目のファイル。|argli < 引数{nr}が指定されなかった場合は、引数リスト|arglist|全体を 返す。 + *assert_equal()* +assert_equal({expected}, {actual} [, {msg}]) + When {expected} and {actual} are not equal an error message is + added to |v:errors|. + There is no automatic conversion, the String "4" is different + from the Number 4. And the number 4 is different from the + Float 4.0. The value of 'ignorecase' is not used here, case + always matters. + When {msg} is omitted an error in the form "Expected + {expected} but got {actual}" is produced. + Example: > + assert_equal('foo', 'bar') +< Will result in a string to be added to |v:errors|: + test.vim line 12: Expected 'foo' but got 'bar' ~ + +assert_exception({error} [, {msg}]) *assert_exception()* + When v:exception does not contain the string {error} an error + message is added to |v:errors|. + This can be used to assert that a command throws an exception. + Using the error number, followed by a colon, avoids problems + with translations: > + try + commandthatfails + call assert_false(1, 'command should have failed') + catch + call assert_exception('E492:') + endtry + +assert_fails({cmd} [, {error}]) *assert_fails()* + Run {cmd} and add an error message to |v:errors| if it does + NOT produce an error. + When {error} is given it must match |v:errmsg|. + +assert_false({actual} [, {msg}]) *assert_false()* + When {actual} is not false an error message is added to + |v:errors|, like with |assert_equal()|. + A value is false when it is zero. When "{actual}" is not a + number the assert fails. + When {msg} is omitted an error in the form "Expected False but + got {actual}" is produced. + +assert_true({actual} [, {msg}]) *assert_true()* + When {actual} is not true an error message is added to + |v:errors|, like with |assert_equal()|. + A value is true when it is a non-zero number. When {actual} + is not a number the assert fails. + When {msg} is omitted an error in the form "Expected True but + got {actual}" is produced. + asin({expr}) *asin()* {expr} の逆正弦 (アークサイン) をラジアンで返す。 値は [-pi/2, pi/2] の範囲の浮動小数点数 (|Float|)。 @@ -2215,7 +2403,10 @@ byteidx({expr}, {nr}) *byteidx()* 文字列{expr}の{nr}番目の文字のバイトインデックスを返す。 最初の文字の{nr}は0であり、戻り値は0となる。この関数はマルチバ イト文字が存在するときのみ有用であり、そうでなければこの関数が - 返す値は{nr}に等しい。合成文字は別々の文字と数えられる。 + 返す値は{nr}に等しい。 + 合成文字はまとめて計算される。合成文字のバイト数はそれが合成さ + れているベース文字のバイト数に合算される。合成文字を別々に数え + るには |byteidxcomp()| を参照。 例 : > echo matchstr(str, ".", byteidx(str, 3)) < は4文字目を表示する。次も同じことをする: > @@ -2224,6 +2415,17 @@ byteidx({expr}, {nr}) *byteidx()* < {expr}が{nr}文字以下の場合は-1を返す。 {expr}がちょうど{nr}文字の場合は文字列の長さ(バイト単位)を返す。 +byteidxcomp({expr}, {nr}) *byteidxcomp()* + byteidx() と同じだが、合成文字は個別にカウントされる。例: > + let s = 'e' . nr2char(0x301) + echo byteidx(s, 1) + echo byteidxcomp(s, 1) + echo byteidxcomp(s, 2) +< 1 番目と 3 番目は 3 が出力される ('e' の長さと合成文字の長さを + 足すと 3 バイト)。2 番目は 1 が出力される ('e' は 1 バイト)。 + 'encoding' にユニコードが設定されているときのみ byteidx() と違 + う動作になる。 + call({func}, {arglist} [, {dict}]) *call()* *E699* リスト|List|{arglist}の要素を引数として関数{func}を呼ぶ。 {func}は|Funcref|でも関数の名前でもよい。 @@ -2284,6 +2486,9 @@ col({expr}) . 現在の位置 $ カレント行の末尾(カレント行のバイト数+1を返す) 'x マークxの位置(マークが設定されていない場合0) + v ビジュアルモードでは: ビジュアル選択領域の開始行 + (カーソルがその端)。ビジュアルモード以外ではカーソ + ル位置を返す。すぐに更新される点が |'<| と違う。 さらに {expr} は [lnum, col] という行番号と桁番号のリストで あってもよい。col に "$" を指定して、ある行の最後の桁を取得す るのにとても便利である。"lnum" か "col" が範囲外である場合は @@ -2349,7 +2554,7 @@ complete_check() *complete_check()* 'completefunc' で指定された関数の中でのみ使われる。 *confirm()* -confirm({msg}, {choices} [, {default} [, {type}]]) +confirm({msg} [, {choices} [, {default} [, {type}]]]) confirm()はユーザーに選択させるためのダイアログを提供する。戻 り値は選択した番号になる。最初の選択肢が1である。 Note: confirm()は、ダイアログサポートを有効にしてコンパイルし @@ -2374,7 +2579,7 @@ confirm({msg}, {choices} [, {default} [, {type}]]) 省略可能な引数{default}はキーを叩いた時に選択される選択肢 の番号を指定する。最初の選択肢をデフォルトにするならば1を使用 する。デフォルトを設定したくないのならば0を使用する。 - {default}を省略した場合、0が使用される。 + {default}を省略した場合、1が使用される。 省略可能な引数{type}はダイアログの種類を指定する。これは GTK, Mac, Motif, Win32 の GUI でアイコンを指定するのに使われる。 @@ -2401,6 +2606,18 @@ confirm({msg}, {choices} [, {default} [, {type}]]) は、垂直配置が使われる。幾つかのシステムでは常に水平配置が使わ れる。 +connect({address}, {mode} [, {callback}]) *connect()* + Open a channel to {address}. See |channel|. + + {address} has the form "hostname:port", e.g., + "localhost:8765". + + {mode} is either "json" or "raw". See |channel-mode| for the + meaning. + + {callback} is a function that handles received messages on the + channel. See |channel-callback|. + *copy()* copy({expr}) {expr}のコピーを作る。数値と文字列の場合は、{expr}そのものとコ ピーの間に違いはない。 @@ -2484,15 +2701,23 @@ cursor({lnum}, {col} [, {off}]) *cursor()* cursor({list}) {lnum}行目の{col}桁目(バイトで数える)にカーソルを移動させる。 桁番号{col}は1から始まる。 - 引数が1個の場合は、{lnum}, {col}, {off}からなる、2個または3個 - の要素を持つリスト|List|でなければならない。これは|getpos()|の - 戻り値と似ているが、1個目の要素がない点が異なる。 + + 引数に {list} が 1 つだけ指定された場合は、それは要素が 2 個か + 3 個、または 4 個の |List| として解釈される: + [{lnum}, {col}, {off}] + [{lnum}, {col}, {off}, {curswant}] + これは |getpos()| や |getcurpos()| の返り値とほぼ同じである。 + 違いは最初の要素がないこと。 + この関数を呼んでもジャンプリストは変更されない。 {lnum}がバッファの行数よりも大きい場合は、最後の行へ移動する。 {lnum}が0の場合はカレント行に留まる。 {col}がその行のバイト数より大きい場合は、その行の最後の文字へ 移動する。 {col}が0の場合は、カレント桁に留まる。 + {curswant} が与えられた場合は、縦方向移動の優先的列番号として + 使われる。指定がない場合は {col} が使われる。 + 'virtualedit' が有効のとき、{off}は文字の先頭からの画面上のオ フセットを指定する。例えば、の中の位置や最後の文字より後 などへも移動できる。 @@ -2514,10 +2739,20 @@ deepcopy({expr}[, {noref}]) *deepcopy()* *E698* 要素があると、{noref}が1の場合は失敗する。 |copy()|も参照。 -delete({fname}) *delete()* - {fname}という名前のファイルを削除する。戻り値は数値で、削除に - 成功したら0、失敗したら0以外が返る。 - リスト|List|から要素を削除するには|remove()|を使う。 +delete({fname} [, {flags}]) *delete()* + Without {flags} or with {flags} empty: Deletes the file by the + name {fname}. This also works when {fname} is a symbolic link. + + When {flags} is "d": Deletes the directory by the name + {fname}. This fails when directory {fname} is not empty. + + When {flags} is "rf": Deletes the directory by the name + {fname} and everything in it, recursively. BE CAREFUL! + A symbolic link itself is deleted, not what it points to. + + The result is a Number, which is 0 if the delete operation was + successful and -1 when the deletion failed or partly failed. + バッファから行を削除するには|:delete|を使う。行番号が変数に入っ ている場合は|:exe|を使う。 @@ -2552,6 +2787,7 @@ empty({expr}) *empty()* {expr}が空なら1を、そうでなければ0を返す。 リスト|List|または辞書|Dictionary|は要素を1個も持たないとき空 とみなされる。数値は値が0のとき空とみなされる。 + |v:false|, |v:none| and |v:null| are empty, |v:true| is not. 長いリストに対しては長さを0と比較するよりこちらの方がずっと高 速である。 @@ -2598,6 +2834,15 @@ executable({expr}) *executable()* 0 存在しない -1 このシステム上では実装されていない +exepath({expr}) *exepath()* + {expr} が実行ファイルで、それが絶対パス、相対パス、または + $PATH の中に存在する場合は、そのフルパスを返す。 + Note: {expr} が "./" で開始している場合はカレントディレクトリ + が使われる。Vim のパスを得る場合に問題になるかもしれない: > + echo exepath(v:progpath) +< {expr} が $PATH の中に見つからないか、それが実行ファイルではな + かった場合は空文字列が返る。 + *exists()* exists({expr}) 結果は数値で、変数{expr}が存在すれば1となり、そうでなければ0と なる。引数{expr}は文字列で次のうちいずれかである。 @@ -2607,7 +2852,9 @@ exists({expr}) 結果は数値で、変数{expr}が存在すれば1となり、 $ENVNAME 環境変数(空文字列と比較することでも判 定できる) *funcname 組み込み関数(|functions|参照)かユーザー - が定義した関数(|user-functions|参照) + が定義した関数(|user-functions|参照)。 + また Funcref である変数に対しても動作 + する。 varname 内部変数(|internal-variables|) |curly-braces-names|, |Dictionary|の要 素、|List|の要素などに対しても動作する。 @@ -2698,8 +2945,9 @@ expand({expr} [, {nosuf} [, {list}]]) *expand()* 5.0 では空白文字が用いられ、スペースを含むファイル名について問 題を引き起こしていた] - 展開が失敗した場合、結果は空文字列となる。また存在しないファイ - ル名というのは、結果の文字列には含まれない。 + 展開が失敗した場合、結果は空文字列となる。{expr} が '%'、'#'、 + '<' で始まらない限り、存在しないファイル名というのは、結果の文 + 字列には含まれない。下記を参照のこと。 {expr} が '%' か '#' か '<' で始まる場合には、展開は |cmdline-special|のように、変換子を受け付け、それらに関連付け @@ -2711,7 +2959,7 @@ expand({expr} [, {nosuf} [, {list}]]) *expand()* カーソルの下のファイル名 autocmdのファイル名 autocmdのバッファ名 - 取り込み(source)中のファイル名 + 取り込み(source)中のファイル名、関数名 取り込み(source)中の行番号 カーソル下の単語(word) カーソル下の単語(WORD) @@ -2751,12 +2999,13 @@ expand({expr} [, {nosuf} [, {list}]]) *expand()* とディレクトリツリーを検索できる。例えば、カレントディレクトリ 以下にある全ての "README" を見つけるには次のようにする: > :echo expand("**/README") -< - expand()は、シェルの持っている変数や環境変数を展開することがで - きる。しかしシェルを起動しなければならないので、遅くなる。 - |expr-env-expand|を参照。展開された変数はファイル名のリストの - ように扱われる。環境変数を展開できないときはそのままになる。よっ - て ":echo expand('$FOOBAR')" の結果は "$FOOBAR" となる。 +< + expand() はシェルの持っている変数や環境変数を展開できる。しか + し展開のためにシェルを起動するかもしれないので速度が遅くなるこ + とがある。|expr-env-expand| 参照。 + 展開された変数はファイル名のリストのように扱われる。環境変数を + 展開できないときはそのままになる。よって、 + ":echo expand('$FOOBAR')" の結果は "$FOOBAR" となる。 存在するファイルを探すには|glob()|を参照。外部コマンドの「生 の」実行結果を扱うには|system()|を参照。 @@ -2793,15 +3042,19 @@ extend({expr1}, {expr2} [, {expr3}]) *extend()* {expr2}が空でないならば{expr1}が変更される。必要ならば最初に {expr1}のコピーを作ること。 {expr2}は変更されない。 + {expr1} がロックされていて、かつ {expr2} が空でない場合は操作 + は失敗する。 {expr1}を返す。 feedkeys({string} [, {mode}]) *feedkeys()* {string}中の各文字を、あたかもマッピングまたはユーザーによって - タイプされたかのように、処理キューに入れる。 これらの文字は先 - 行入力バッファの末尾に付け足される。そのためマッピングを展開し - ている途中であれば、これらの文字はマッピングを展開した後に来る - ことになる。 + タイプされたかのように、処理キューに入れる。デフォルトではこれ + らの文字は先行入力バッファの末尾に付け足される。そのためマッピ + ングを展開している途中であれば、これらの文字はマッピングを展開 + した後に来ることになる。他の文字の前に挿入するには、'i' フラグ + を使用する。それらはマッピングからの任意の文字の前の挿入の次に + 実行される。 この関数は、{string}中の文字が処理されるまでは待たない。 特殊なキーを{string}に含めるにはダブルクォートと "\..." 記法を 使う(|expr-quote|を参照)。例えば、feedkeys("\")は @@ -2814,6 +3067,12 @@ feedkeys({string} [, {mode}]) *feedkeys()* 't' キーをタイプされたかのように扱う。そうでない場合は マッピングから展開されたかのように扱われる。これは undoや折り畳みの展開などで違いが現れる。 + 'i' 追加する代わりに文字を挿入する。(上記参照) + 'x' Execute commands until typeahead is empty. This is + similar to using ":normal!". You can call feedkeys() + several times without 'x' and then one time with 'x' + (possibly with an empty {string}) to execute all the + typeahead. 戻り値は常に0。 *filereadable()* @@ -3078,23 +3337,27 @@ getbufvar({expr}, {varname} [, {def}]) *getbufvar()* < getchar([expr]) *getchar()* ユーザーまたは入力ストリームから1文字を取得する。 - [expr]が省略されたときは1文字を取得できるまで待つ。 - [expr]が0のときは1文字を取得できる場合のみ取得する。取得できな - ければ0を返す。 - [expr]が1のときは1文字を取得できるか判定し、実際には取得しない。 - 取得できないときは0を返す。 - - {expr}が省略されたときや{expr}が0のときは、文字全体または特殊 - キーを返す。それが8ビット文字なら戻り値は数値である。これを文 - 字列に戻すにはnr2char()を使う。8ビット文字でないならばエンコー - ドして文字列にして返す。 + [expr] が省略されたときは1文字を取得できるまで待つ。 + [expr] が0のときは1文字を取得できる場合のみ取得する。取得でき + なければ0を返す。 + [expr] が1のときは1文字を取得できるか判定し、実際には取得しな + い。取得できないときは0を返す。 + + [expr] が省略されたときや [expr] が0のときは、文字全体または特 + 殊キーを返す。それが8ビット文字なら戻り値は数値である。これを + 文字列に戻すにはnr2char()を使う。8ビット文字でないならばエン + コードして文字列にして返す。 特殊キーとは0x80(10進数で128)で始まるバイト列である。これは 文字列 "\" と同じ値である(例: "\")。戻り値は文字列 であり、修飾キー(shift, control, alt)は含まれない。 - {expr}が1のときは最初のバイトだけを返す。1バイト文字の場合、こ - れはその文字そのものを表す数値である。これを文字列に変換するに - はnr2char()を使う。 + [expr] が0や Esc が入力された場合は、これがエスケープシーケン + スの始まりであるかどうかをVimが知るために待つ間、短い遅延があ + るだろう。 + + [expr] が1のときは最初のバイトだけを返す。1バイト文字の場合、 + これはその文字そのものを表す数値である。これを文字列に変換する + にはnr2char()を使う。 修飾キーを取得するには getcharmod() を使う。 @@ -3130,6 +3393,17 @@ getchar([expr]) *getchar()* : endif : endwhile :endfunction +< + あなたは||のような合成文字も取得するかもしれない。 + 多くの場合、あなたはこれを無視して別の文字を取得することにな + る: > + :function GetKey() + : let c = getchar() + : while c == "\" + : let c = getchar() + : endwhile + : return c + :endfunction getcharmod() *getcharmod()* 最後にgetchar()などで得た文字に対する修飾キーの状態を表す数値 @@ -3145,6 +3419,26 @@ getcharmod() *getcharmod()* 文字自身に含まれていない修飾キーのみ取得できる。つまり、 Shift-aは修飾キーなしの "A" となる。 +getcharsearch() *getcharsearch()* + Return the current character search information as a {dict} + with the following entries: + + char character previously used for a character + search (|t|, |f|, |T|, or |F|); empty string + if no character search has been performed + forward direction of character search; 1 for forward, + 0 for backward + until type of character search; 1 for a |t| or |T| + character search, 0 for an |f| or |F| + character search + + This can be useful to always have |;| and |,| search + forward/backward regardless of the direction of the previous + character search: > + :nnoremap ; getcharsearch().forward ? ';' : ',' + :nnoremap , getcharsearch().forward ? ',' : ';' +< Also see |setcharsearch()|. + getcmdline() *getcmdline()* 現在のコマンドラインの内容を取得する。コマンドラインを編集して いるときのみ動作する。つまり|c_CTRL-\_e|または|c_CTRL-R_=|を使っ @@ -3168,13 +3462,38 @@ getcmdtype() *getcmdtype()* ? 後方検索コマンド @ |input()| コマンド - |:insert| または |:append| コマンド + = |i_CTRL-R_=| コマンドラインを編集しているときのみ動作する。つまり |c_CTRL-\_e|または|c_CTRL-R_=|または式マッピングを使っていると きのみ有効。そうでないときは空文字列を返す。 |getcmdpos()|, |setcmdpos()|, |getcmdline()|も参照。 +getcmdwintype() *getcmdwintype()* + 現在のコマンドラインウィンドウ (|command-line-window|) の種類 + を返す。返り値の意味は |getcmdtype()| と同じ。コマンドライン + ウィンドウでなければ空文字列を返す。 + + *getcurpos()* +getcurpos() カーソルの位置を返す。これは getpos('.') に似ているが、追加の + 情報を含む: + [bufnum, lnum, col, off, curswant] ~ + "curswant" は縦方向移動の優先的列番号である。 + 次のようにしてカーソル位置の保存と復元ができる: > + let save_cursor = getcurpos() + MoveTheCursorAround + call setpos('.', save_cursor) +< *getcwd()* -getcwd() 結果は文字列で、現在のディレクトリ名。 +getcwd([{winnr} [, {tabnr}]]) + The result is a String, which is the name of the current + working directory. + Without arguments, for the current window. + + With {winnr} return the local current directory of this window + in the current tab page. + With {winnr} and {tabnr} return the local current directory of + the window in the specified tab page. + Return an empty string if the arguments are invalid. getfsize({fname}) *getfsize()* 結果は数値で、{fname}で指定されるファイルのサイズをバイト単位 @@ -3233,6 +3552,8 @@ getftype({fname}) *getftype()* getftype("/home") < Note "link" などの種別はそれをサポートしているシステムでのみ返 される。"dir" と "file" しか返らないシステムもある。 + On MS-Windows a symbolic link to a + directory returns "dir" instead of "link". *getline()* getline({lnum} [, {end}]) @@ -3286,6 +3607,32 @@ getmatches() *getmatches()* 'pattern': 'FIXME', 'priority': 10, 'id': 2}] > :unlet m < + *getpid()* +getpid() Vim のプロセス ID を数値で返す。Unix と MS-Windows では Vim が + 終了するまでこれは一意な数値である。MS-DOS では常にゼロである。 + + *getpos()* +getpos({expr}) {expr}の位置を返す。{expr}として指定できる値については + |line()|を参照。カーソル位置を得るには |getcurpos()| を参照。 + 結果は次の4個の要素を持つリスト|List|: + [bufnum, lnum, col, off] + "bufnum" は、'0 や 'A のようなマークが指定されたときは、その + マークのバッファ番号となる。それ以外では0となる。 + "lnum" と "col" はバッファ中の位置。桁番号は1から始まる。 + "off" の値は、'virtualedit' がオフのときは常に0で、オンのとき + はその文字の始点からの画面上の桁のオフセットである。つまり、 + カーソルがの中や、その行の最後の文字より後にあるとき意味 + を持つ。 + Note: ビジュアルモードの '< と '> について: ビジュアルモードが + "V" (行選択モード) のとき、'< の桁番号はゼロ、'> の桁番号は大 + きな値になる。 + この関数はマークの位置を保存し、復元するために使われる: > + let save_a_mark = getpos("'a") + ... + call setpos("'a", save_a_mark) +< |getcurpos()| と |setpos()|も参照。 + + getqflist() *getqflist()* 現在の全quickfixエラーのリストを返す。リストの各要素は辞書で、 以下の要素を持つ: @@ -3312,7 +3659,7 @@ getqflist() *getqflist()* : echo bufname(d.bufnr) ':' d.lnum '=' d.text :endfor -getreg([{regname} [, 1]]) *getreg()* +getreg([{regname} [, 1 [, {list}]]]) *getreg()* レジスタ{regname}の中身を文字列にして返す。例: > :let cliptext = getreg('*') < getreg('=')は最後に評価した式レジスタの値を返す。(マップの中で @@ -3320,16 +3667,21 @@ getreg([{regname} [, 1]]) *getreg()* getreg('=', 1)はその式そのものを返す。これを使って|setreg()|で 復元することができる。他のレジスタの場合は、この引数は無視され るので、常に指定していても害はない。 + {list} が指定され、その値が非ゼロのときは、返り値はリスト + (|List|) になる。リストの各要素はテキスト 1 行である。これはレ + ジスタの中に値ゼロのバイトが含まれる場合に使用する。{list} を + 指定しなかった場合は NL 文字と値ゼロのバイトは両方とも NL 文字 + として扱われる (|NL-used-for-Nul| 参照)。 {regname}を指定しないときは|v:register|が使われる。 getregtype([{regname}]) *getregtype()* レジスタ{regname}の種類を表す文字列を返す。 戻り値は次のいずれかとなる: - "v" 文字指向|characterwise|の場合 - "V" 行指向|linewise|の場合 - "{width}" 矩形指向|blockwise-visual|の場合 - 0 空、または未知のレジスタの場合 + "v" 文字単位|characterwise|の場合 + "V" 行単位|linewise|の場合 + "{width}" 矩形|blockwise-visual|の場合 + "" 空、または未知のレジスタの場合 は値0x16の1文字である。 {regname}を指定しないときは|v:register|が使われる。 @@ -3337,6 +3689,7 @@ gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()* タブページ {tabnr} のタブローカル変数 {varname} を取得する。 |t:var| タブの番号は 1 から始まる。 + {varname} が空のときは全タブローカル変数からなる辞書を返す。 Note: 指定する変数名は "t:" を除いた名前。 タブや変数が存在しないときは{def}または空文字列を返し、エラー メッセージは表示されない。 @@ -3376,7 +3729,7 @@ getwinvar({winnr}, {varname} [, {def}]) *getwinvar()* :let list_is_on = getwinvar(2, '&list') :echo "myvar = " . getwinvar(1, 'myvar') < -glob({expr} [, {nosuf} [, {list}]]) *glob()* +glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()* {expr}内のファイル名のワイルドカードを展開する。特殊文字につい ては|wildcards|を参照。 @@ -3391,9 +3744,12 @@ glob({expr} [, {nosuf} [, {list}]]) *glob()* そうでない場合は結果は文字列で返される。その場合、複数のマッチ があるときはそれらは文字 で区切られる。 - 展開が失敗した場合、空の文字列またはリストが返される。存在しな - いファイル名は結果に含まれない。シンボリックリンクは、それが存 - 在するファイルを指す場合のみ含まれる。 + 展開が失敗した場合、空の文字列またはリストが返される。 + + 存在しないファイル名は結果に含まれない。シンボリックリンクは、 + それが存在するファイルを指す場合のみ含まれる。 + ただし、{alllinks} 引数が存在し、それが非ゼロである場合はすべ + てのシンボリックリンクが含まれる。 多くのシステムではバッククォート(「`」という文字のこと)を、外 部コマンドの実行結果からファイル名を取得するために使用できる。 @@ -3406,11 +3762,20 @@ glob({expr} [, {nosuf} [, {list}]]) *glob()* 特殊なVimの変数を展開するためには|expand()|を参照。外部コマン ドの生の出力を得るためには|system()|を参照。 -globpath({path}, {expr} [, {flag}]) *globpath()* +glob2regpat({expr}) *glob2regpat()* + glob()に使われるファイルパターンを検索パターンに変換する。 + 結果はファイル名の文字列とのマッチに使用できる。例えば、 > + if filename =~ glob2regpat('Make*.mak') +< 上記は次と同じである: > + if filename =~ '^Make.*\.mak$' +< + *globpath()* +globpath({path}, {expr} [, {nosuf} [, {list} [, {allinks}]]]) {path}の中の全ディレクトリに対して|glob()|を実行し、結果を連結 する。例: > :echo globpath(&rtp, "syntax/c.vim") -< {path}はコンマ区切りのディレクトリのリスト。各ディレクトリを +< + {path}はコンマ区切りのディレクトリのリスト。各ディレクトリを {expr}の前に付加し、glob()と同様にそれを展開する。必要に応じて パスの区切り文字が挿入される。 ディレクトリ名の中にコンマを含めるには、バックスラッシュでエス @@ -3419,10 +3784,20 @@ globpath({path}, {expr} [, {flag}]) *globpath()* スケープと見なされてしまうので、バックスラッシュは削除すること。 どれかのディレクトリに対して展開が失敗してもエラーメッセージは 表示されない。 - {flag} に非零が指定されない限り、オプション 'wildignore' が適 + + {nosuf} に非零が指定されない限り、オプション 'wildignore' が適 用される。つまり、'wildignore' のパターンにマッチする名前はス キップされる。 + {list} が指定され、その値が非ゼロなら、マッチしたすべてのファ + イルがリストとして返る。リストとして受け取る利点は、改行文字を + 含んだファイル名も正しく扱えることである。{list} を指定しな + かった場合は、返り値は文字列であり、マッチした複数のファイル名 + は 文字で連結されてしまう。例: > + :echo globpath(&rtp, "syntax/c.vim", 0, 1) +< + {allinks} は|glob()|の場合と同様に扱われる。 + "**" を使ってディレクトリツリーを再帰的に検索することができる。 例えば、'runtimepath' とそれ以下のディレクトリから全ての "README.txt" を探すには次のようにする: > @@ -3440,10 +3815,15 @@ has_key({dict}, {key}) *has_key()* 結果は数値で、辞書|Dictionary| {dict}がキー{key}の要素を持つな ら1、持たないなら0となる。 -haslocaldir() *haslocaldir()* - 結果は数値でカレントウィンドウが|:lcd|によってローカルなカレン - トディレクトリを持つようセットされているなら1、そうでないなら - 0となる。 +haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()* + 結果は数値でウィンドウが|:lcd|によってローカルなカレントディレ + クトリを持つようセットされているなら1、そうでないなら0となる。 + + Without arguments use the current window. + With {winnr} use this window in the current tab page. + With {winnr} and {tabnr} use the window in the specified tab + page. + Return 0 if the arguments are invalid. hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()* 結果は数値。右辺側(マップした先)の一部分に{what}を含むマッピン @@ -3760,6 +4140,48 @@ join({list} [, {sep}]) *join()* |string()|を使ったときと同じようにして文字列に変換される。 この逆を行う関数は|split()|である。 +jsondecode({string}) *jsondecode()* + This parses a JSON formatted string and returns the equivalent + in Vim values. See |jsonencode()| for the relation between + JSON and Vim values. + The decoding is permissive: + - A trailing comma in an array and object is ignored. + - An empty item in an array, two commas with nothing or white + space in between, results in v:none. + - When an object member name is not a string it is converted + to a string. E.g. the number 123 is used as the string + "123". + - More floating point numbers are recognized, e.g. "1." for + "1.0". + The result must be a valid Vim type: + - An empty object member name is not allowed. + - Duplicate object member names are not allowed. + +jsonencode({expr}) *jsonencode()* + Encode {expr} as JSON and return this as a string. + The encoding is specified in: + https://tools.ietf.org/html/rfc7159.html + Vim values are converted as follows: + Number decimal number + Float floating point number + String in double quotes (possibly null) + Funcref not possible, error + List as an array (possibly null); when + used recursively: [] + Dict as an object (possibly null); when + used recursively: {} + v:false "false" + v:true "true" + v:none nothing + v:null "null" + Note that using v:none is permitted, although the JSON + standard does not allow empty items. This can be useful for + omitting items in an array: + [0,,,,,5] ~ + This is much more efficient than: + [0,null,null,null,null,5] ~ + But a strict JSON parser will not accept it. + keys({dict}) *keys()* {dict}の全キーからなるリストを返す。リストの順序は不定である。 @@ -3849,8 +4271,7 @@ line({expr}) 結果は数値で、{expr}で与えられた位置のファイル されている時にのみ有効である: > :au BufReadPost * if line("'\"") > 1 && line("'\"") <= line("$") | exe "normal! g`\"" | endif - *line2byte()* -line2byte({lnum}) +line2byte({lnum}) *line2byte()* バッファの先頭から、{lnum}行目までのバイト数を返す。これには現 在のバッファのオプション 'fileformat' に従った、end-of-line(行 終端)文字も含まれている。最初の行においては1が返る。バイト数は @@ -3976,6 +4397,7 @@ maparg({name}[, {mode} [, {abbr} [, {dict}]]]) *maparg()* "!" 挿入、コマンドラインモード (|mapmode-ic|) "sid" マッピングで使用されるスクリプトローカルID (||)。 + "nowait" 他の長いマッピングを待たない。(|:map-|)。 まずカレントバッファにローカルなマッピングを探し、次のグローバ ルマッピングを探す。 @@ -4070,11 +4492,16 @@ match({expr}, {pat}[, {start}[, {count}]]) *match()* 'magic' をオン、'cpoptions' を空にした状態で行われる。 *matchadd()* *E798* *E799* *E801* -matchadd({group}, {pattern}[, {priority}[, {id}]]) +matchadd({group}, {pattern}[, {priority}[, {id} [, {dict}]]]) カレントウィンドウで強調表示するパターンを定義する。このパター ンのことを「マッチ」と呼ぶ。構文グループ {group}で強調する。戻 り値は、マッチを識別する ID である。|matchdelete()|でこの ID を指定してマッチを削除することができる。 + パターンは大文字小文字を区別し、magic (|/magic|) として解釈さ + れる ({pattern} の中で明示的に変更しない限り)。オプションの + 'magic'、'smartcase'、'ignorecase' は使用されない。 + The "Conceal" value is special, it causes the match to be + concealed. 省略可能な引数 {priority} はマッチの優先度を指定する。優先度が 高いマッチは、より低いマッチの強調を上書きする。優先度は整数で @@ -4088,8 +4515,17 @@ matchadd({group}, {pattern}[, {priority}[, {id}]]) すでに使われていたら、エラーメッセージが表示され、そのマッチは 登録されない。ID は正の整数を指定する(ゼロは除く)。ID 1, 2, 3 は |:match|, |:2match|, |:3match| 用に予約されている。{id} が - 指定されないときは、|matchadd()| が自動的に空いている ID を取 - 得する。 + 指定されないか -1 のときは、|matchadd()| が自動的に空いている + ID を取得する。 + + The optional {dict} argument allows for further custom + values. Currently this is used to specify a match specific + conceal character that will be shown for |hl-Conceal| + highlighted matches. The dict can have the following members: + + conceal Special character to show instead of the + match (only for |hl-Conceal| highlighed + matches, see |:syn-cchar|) コマンド |:match| と異なり、マッチの個数に上限はない。 @@ -4103,6 +4539,41 @@ matchadd({group}, {pattern}[, {priority}[, {id}]]) |getmatches()| で取得できる。全てのマッチを削除するのは |clearmatches()| 一発でできる。 +matchaddpos({group}, {pos}[, {priority}[, {id}[, {dict}]]]) *matchaddpos()* + |matchadd()| と同じだが、パターンを指定するのではなく、位置の + リスト {pos} を指定する。このコマンドは正規表現を扱う必要もな + く、画面更新のためにバッファ行の境界を設定するため、 + |matchadd()| よりも速い。これは、例えば括弧の対応を強調表示す + るような、マッチの追加と削除を高速に実行したい状況を想定してい + る。 + + リスト {pos} は以下のいずれかの値を要素として持つことができる: + - 数値。指定した行全体が強調表示される。最初の行の行番号は 1 + である。 + - 数値を 1 つ持ったリスト。例 [23]。指定した行全体が強調表示さ + れる。 + - 数値を 2 つ持ったリスト。例 [23, 11]。最初の数値は行番号、2 + 番目の数値は列番号である (最初の列は 1 である。値は |col()| + の返り値と同じようにバイト単位である)。指定した位置の文字が + 強調表示される。 + - 数値を 3 つ持ったリスト。例 [23, 11, 3]。数値 2 つの場合と同 + じだが、3 つ目に強調表示する文字の長さ (バイト単位) を指定す + る。 + + 指定できる位置は最大で 8 個である。 + + 例: > + :highlight MyGroup ctermbg=green guibg=green + :let m = matchaddpos("MyGroup", [[23, 24], 34]) +< パターンの削除: > + :call matchdelete(m) + +< |matchaddpos()| で追加されたマッチは |getmatches()| で取得する + 際には "pos1"、"pos2"、... という項目を持つ。それぞれの値は + {pos} で指定された値である。 + これらのマッチは |setmatches()| で設定することはできない。ただ + し、|clearmatches()| で削除することはできる。 + matcharg({nr}) *matcharg()* |:match|、|:2match|、|:3match|によって設定されているマッチパター ンの情報を返す。{nr}が1のときは|:match|の情報、2のときは @@ -4202,12 +4673,12 @@ mode([expr]) 現在のモードを示す文字列を返す。 n ノーマル no オペレータ待機 - v 文字指向ビジュアル - V 行指向ビジュアル - CTRL-V 矩形指向ビジュアル - s 文字指向選択 - S 行指向選択 - CTRL-S 矩形指向選択 + v 文字単位ビジュアル + V 行単位ビジュアル + CTRL-V 矩形ビジュアル + s 文字単位選択 + S 行単位選択 + CTRL-S 矩形選択 i 挿入 R 置換 |R| Rv 仮想置換 |gR| @@ -4260,28 +4731,6 @@ nr2char({expr}[, {utf8}]) *nr2char()* る。nr2char(0)は真のNUL文字(文字列の終端)となるので、空文字列 を返す。 - *getpid()* -getpid() Vim のプロセス ID を数値で返す。Unix と MS-Windows では Vim が - 終了するまでこれは一意な数値である。MS-DOS では常にゼロである。 - - *getpos()* -getpos({expr}) {expr}の位置を返す。{expr}として指定できる値については - |line()|を参照。 - 結果は次の4個の要素を持つリスト|List|: - [bufnum, lnum, col, off] - "bufnum" は、'0 や 'A のようなマークが指定されたときは、その - マークのバッファ番号となる。それ以外では0となる。 - "lnum" と "col" はバッファ中の位置。桁番号は1から始まる。 - "off" の値は、'virtualedit' がオフのときは常に0で、オンのとき - はその文字の始点からの画面上の桁のオフセットである。つまり、 - カーソルがの中や、その行の最後の文字より後にあるとき意味 - を持つ。 - この関数はカーソル位置を保存し、復元するために使われる: > - let save_cursor = getpos(".") - MoveTheCursorAround - call setpos('.', save_cursor) -< |setpos()|も参照。 - or({expr}, {expr}) *or()* 二つの引数のビット論理和。引数は数値に変換される。リスト、辞 書、浮動小数点数を指定するとエラーになる。 @@ -4297,6 +4746,17 @@ pathshorten({expr}) *pathshorten()* < ~/.v/a/myfile.vim ~ パスが実際に存在するかどうかは関係ない。 +perleval({expr}) *perleval()* + Evaluate Perl expression {expr} in scalar context and return + its result converted to Vim data structures. If value can't be + converted, it is returned as a string Perl representation. + Note: If you want an array or hash, {expr} must return a + reference to it. + Example: > + :echo perleval('[1 .. 4]') +< [1, 2, 3, 4] + {only available when compiled with the |+perl| feature} + pow({x}, {y}) *pow()* {x} の {y} 乗を |Float| で返す。{x} と {y} は |Float| または |Number| に評価されなければならない。 @@ -4421,6 +4881,7 @@ printf({fmt}, {expr1} ...) *printf()* *printf-s* s 引数の文字列を出力する。精度を指定した場合、その数値以 下のバイト数のみを書き出す。 + *printf-S* S 引数の文字列を出力する。精度を指定した場合、その数値以 下の表示幅のみを書き出す。|+multi_byte| 機能がない場合 は 's' と同じ動作になる。 @@ -4515,7 +4976,7 @@ readfile({fname} [, {binary} [, {max}]]) 行はNL文字で終わるものとする。改行文字がCRであるMacintoshのファ イルは単一の長い行となる(どこかにNLが現れない限り)。 すべての NUL 文字は NL 文字に置換される。 - {binary}が "b" に等しい場合、次のようにバイナリモードになる: + {binary}が "b" を含む場合、次のようにバイナリモードになる: - 最後の行がNLで終わるときは、リストの末尾に余分な空文字列が追 加される。 - CR文字を除去しない。 @@ -4708,6 +5169,19 @@ round({expr}) *round()* < -5.0 {|+float| 機能つきでコンパイルされたときのみ有効} +screenattr(row, col) *screenattr()* + screenchar() と同様だが、属性を返す。これは他の位置の属性と比 + 較するのに利用できるだけの適当な数値である。 + +screenchar(row, col) *screenchar()* + スクリーン上の位置 [row, col] の文字を数値で返す。これは全ての + スクリーン位置、ステータスライン、ウィンドウセパレータ、コマン + ドラインで機能する。左上の位置は行番号が1、列番号が1である。文 + 字は合成文字を除く。2バイトのエンコーディングでは最初のバイト + だけであるかもしれない。 + この関数は主にテスト用に使われる。 + row か col が範囲外である場合は -1 を返す。 + screencol() *screencol()* 現在のカーソルのスクリーン列を数値で返す。一番左の列番号は 1。 この関数は主にテスト用。 @@ -4735,13 +5209,14 @@ search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()* {flags} は以下のフラグ文字からなる文字列 'b' 後方(上方)に検索する - 'c' カーソル位置のマッチを受け入れる + 'c' カーソル位置のマッチを受け入れる 'e' マッチの末尾へ移動する 'n' カーソルを移動させない 'p' 部分パターン(後述)のマッチの番号を返す 's' 以前のカーソル位置をマーク ' に記録する 'w' ファイルの末尾で循環する 'W' ファイルの末尾で循環しない + 'z' start searching at the cursor column instead of zero 'w' と 'W' の両方とも指定されない場合は 'wrapscan' が適用され る。 @@ -4750,6 +5225,12 @@ search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()* 'ignorecase', 'smartcase', 'magic' が適用される。 + When the 'z' flag is not given, searching always starts in + column zero and then matches before the cursor are skipped. + When the 'c' flag is present in 'cpo' the next search starts + after the match. Without the 'c' flag the next search starts + one column further. + 引数{stopline}が指定されたときはこの行を検索した後で検索を停止 する。これは検索する行を制限するために有用である。例: > let match = search('(', 'b', line("w0")) @@ -4924,6 +5405,23 @@ searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *searchpos()* < この例において、"submatch" は小文字|/\l|が見つかったとき2とな り、大文字|/\u|が見つかったとき3となる。 +sendexpr({handle}, {expr} [, {callback}]) *sendexpr()* + Send {expr} over JSON channel {handle}. See |channel-use|. + + When {callback} is given returns immediately. Without + {callback} waits for a JSON response and returns the decoded + expression. When there is an error or timeout returns an + empty string. + + When {callback} is zero no response is expected. + Otherwise {callback} must be a Funcref or the name of a + function. It is called when the response is received. See + |channel-callback|. + +sendraw({handle}, {string} [, {callback}]) *sendraw()* + Send {string} over raw channel {handle}. See |channel-raw|. + Works like |sendexpr()|, but does not decode the response. + server2client( {clientid}, {string}) *server2client()* {clientid}に返信文字列を送る。最後に文字列を送った{clientid}は expand("")で取得できる。 @@ -4957,6 +5455,26 @@ setbufvar({expr}, {varname}, {val}) *setbufvar()* :call setbufvar("todo", "myvar", "foobar") < サンドボックスの中ではこの関数は使用できない。 +setcharsearch({dict}) *setcharsearch()* + Set the current character search information to {dict}, + which contains one or more of the following entries: + + char character which will be used for a subsequent + |,| or |;| command; an empty string clears the + character search + forward direction of character search; 1 for forward, + 0 for backward + until type of character search; 1 for a |t| or |T| + character search, 0 for an |f| or |F| + character search + + This can be useful to save/restore a user's character search + from a script: > + :let prevsearch = getcharsearch() + :" Perform a command which clobbers user's search + :call setcharsearch(prevsearch) +< Also see |getcharsearch()|. + setcmdpos({pos}) *setcmdpos()* コマンドラインの{pos}バイトの位置へカーソルを移動する。 {pos}は1から始まる。 @@ -5007,8 +5525,9 @@ setpos({expr}, {list}) . カーソル位置 'x マーク x - {list}は次の4個の要素を持つリスト|List|でなければならない: + {list} は 4 個か 5 個の要素を持つリスト|List|である: [bufnum, lnum, col, off] + [bufnum, lnum, col, off, curswant] "bufnum" はバッファ番号。0にするとカレントバッファを表す。カー ソル位置の設定はカレントバッファに対してのみ可能。他のバッファ @@ -5024,13 +5543,23 @@ setpos({expr}, {list}) 開始位置からの画面上の桁のオフセットとなる。例えば、の中、 または最後の文字より後に設定したいときに使う。 + "curswant" はカーソル位置を設定するときのみ使われる。これは縦 + 方向移動の優先的列番号である。 "curswant" を指定しなかった場合 + は優先値は設定されない。マークの位置を設定するときに + "curswant" を指定した場合はその値は使用されない。 + + Note: '< と '> の行番号を変更した場合は '< が '> の手前にくる + ように位置が交換される。 + 位置をセットできたときは 0 を、そうでなければ -1 を返す。 {expr} が無効なときはエラーメッセージが出る。 - |getpos()|も参照。 + |getpos()| と |getcurpos()| も参照。 - 縦方向に移動するときの望ましい桁を復元しない。それには - |winrestview()|を参照。 + 縦方向移動の優先的列番号は復元されない。しかしカーソル位置を設 + 定するときにこの値を設定した場合は、|j| や |k| で移動すると以 + 前の列にジャンプようになるだろう。優先的列番号の設定については + |cursor()| も参照。|winrestview()| の "curswant" キーも参照。 setqflist({list} [, {action}]) *setqflist()* @@ -5079,6 +5608,8 @@ setqflist({list} [, {action}]) *setqflist()* *setreg()* setreg({regname}, {value} [,{options}]) レジスタ{regname}に{value}をセットする。 + {value} には |getreg()| の返り値ならどんな値でも (リストでも) + 指定できる。 {options}が "a" を含んでいるとき、または{regname}が大文字のと きは、その値に追加する。 {options}は以下のレジスタの種類指定を含んでもよい: @@ -5089,19 +5620,27 @@ setreg({regname}, {value} [,{options}]) 幅となる。これを指定しない場合、選択範囲の幅は一番長い行の文字 数となる(は1文字と数えられる)。 - {options}にレジスタの設定が何も含まれていないとき、{value}が - で終わっていない限り、デフォルトの文字指向モードが使われる。 - レジスタ '=' の値を設定することはできないが、これが使える: > - :let @= = var_expr -< 成功なら0、失敗なら非0を返す。 + {options} にレジスタの設定が何も含まれていないときのデフォルト + 値は文字モードである。ただし、{value} が文字列で末尾が の + 場合や {value} がリストの場合は行モードになる。矩形モードは明 + 示的に指定しない限り選択されない。 + 成功なら0、失敗なら非0を返す。 + + *E883* + Note: 検索レジスタや式レジスタを設定するときは複数の要素を含ん + だリスト (|List|) を指定することはできない。空のリストは + 空文字列と同様に扱われる。 例: > :call setreg(v:register, @*) :call setreg('*', @%, 'ac') :call setreg('a', "1\n2\n3", 'b5') -< 次の例は、この関数を使ってレジスタを退避・復元する例である。 > - :let var_a = getreg('a', 1) +< 次の例は、この関数を使ってレジスタを退避・復元する例である + (note: |getreg()| の 3 番目の引数を使用せずにレジスタの内容を + 完全に復元することはできない。改行文字と Nul 文字がどちらも改 + 行文字として表現されてしまうため。|NL-used-for-Nul| 参照)。 + :let var_a = getreg('a', 1, 1) :let var_amode = getregtype('a') .... :call setreg('a', var_a, var_amode) @@ -5167,22 +5706,14 @@ shellescape({string} [, {special}]) *shellescape()* < これはカーソル下のファイルを dir コマンドで表示する。 |system()| を使う場合の例: > :call system("chmod +w -- " . shellescape(expand("%"))) +< |::S| も参照のこと。 shiftwidth() *shiftwidth()* 実際に使用される 'shiftwidth' の値を返す。'shiftwidth' がゼロ 以外の場合はその値が返る。ゼロの場合は 'tabstop' の値が返る。 - インデントプラグインで後方互換性を保つには次のようにする: > - if exists('*shiftwidth') - func s:sw() - return shiftwidth() - endfunc - else - func s:sw() - return &sw - endfunc - endif -< そして、&sw の代わりに s:sw() を使う。 + この関数は2012年のパッチ 7.3.694 で導入されたので、現在では皆 + 使えるようになっているに違いない。 simplify({filename}) *simplify()* @@ -5225,19 +5756,43 @@ sinh({expr}) *sinh()* sort({list} [, {func} [, {dict}]]) *sort()* *E702* - {list}の要素をその場で(in-place)ソートする。{list}を返す。リス - トを変更したくない場合は、最初にコピーを作っておくこと: > + {list}の要素をその場で(in-place)ソートする。{list}を返す。 + + リストを変更したくない場合は、最初にコピーを作っておくこと: > :let sortedlist = sort(copy(mylist)) -< ソートの際には、各要素の文字列表現を使う。 - 数値は文字列より後になり、リストは数値より後になる。 - カレントバッファのテキストをソートするには|:sort|を使うこと。 - {func}に1を指定すると、大文字・小文字を区別しなくなる。 - {dict} は "dict" 属性付きの関数と一緒に使う。値はローカル変数 - "self" として使われる。 |Dictionary-function| +< {func} が省略されたか空かゼロの場合は、各項目の文字列表現を + 使ってソートする。数値は文字列より後になり、リストは数値より後 + になる。カレントバッファのテキストをソートするには |:sort| を + 使う。 + + {func} が '1' か 'i' なら大文字小文字は区別されない。 + + {func} が 'n' ならすべての要素は数値順にソートされる (実装詳 + 細: 数値の読み込みには strtod() 関数が使われる。文字列、リス + ト、辞書、関数参照は 0 として扱われる)。 + + When {func} is given and it is 'N' then all items will be + sorted numerical. This is like 'n' but a string containing + digits will be used as the number they represent. + + When {func} is given and it is 'f' then all items will be + sorted numerical. All values must be a Number or a Float. + {func}に|Funcref|または関数名を指定すると、その関数を使って要 素を比較する。その関数は2つの要素を引数として受け取り、それら が等しいときは0、1番目の引数を2番目より後にするなら1以上、1番 - 目の方を前にするなら-1以下を返す。例: > + 目の方を前にするなら-1以下を返す。 + + {dict} は "dict" 属性付きの関数と一緒に使う。値はローカル変数 + "self" として使われる。 |Dictionary-function| + + ソートは安定である。(数値または文字列として) 等価な要素は元の + 順序関係が保持される。例えば数値としてソートした場合、文字列は + 元の順番通りに隣り合って並ぶ。 + + |uniq()| も参照のこと。 + + 例: > func MyCompare(i1, i2) return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1 endfunc @@ -5250,12 +5805,13 @@ sort({list} [, {func} [, {dict}]]) *sort()* *E702* < *soundfold()* soundfold({word}) - {word}と同値でsound-foldされた単語を返す。カレントウィンドウの - 'spelllang' で設定された言語のうち、soundfoldingに対応する最初 - の言語が使用される。'spell' がオンでなければならない。 - soundfoldingができない場合、{word}がそのまま返される。 - この関数はスペリング候補を作るために使われる。Note この方法は - とても遅くなる可能性がある。 + {word} の soundfold 値を返す。カレントウィンドウの 'spelllang' + で設定された言語のうち、soundfold に対応している最初の言語が使 + 用される。'spell' がオンでなければならない。soundfold ができな + い場合は {word} がそのまま返される。 + この関数はスペル修正候補の作成に使える。Note この方法はとても + 遅くなる可能性がある。 + {訳注: phonetic algorithm の一種} *spellbadword()* spellbadword([{sentence}]) @@ -5321,7 +5877,7 @@ split({expr} [, {pattern} [, {keepempty}]]) *split()* < 文字列を各文字に分割するには: > :for c in split(mystring, '\zs') < 区切り文字を削除せず、そのままにしておきたい場合は、'\zs' を - 使えばよい: > + パターンの最後で使う: > :echo split('abc:def:ghi', ':\zs') < ['abc:', 'def:', 'ghi'] ~ 最初の要素が空であるかもしれないテーブルを分割するには: > @@ -5352,28 +5908,52 @@ str2float( {expr}) *str2float()* 数値の後ろにある文字列は黙って無視される。 小数点数はロケールの設定に関わらず常に '.' である。コンマを発 見すると、そこで数値は終わりになる。つまり "12,345.67" は 12.0 - に変換される。3桁ごとのカンマ区切りを取り除くには + に変換される。3桁ごとのコンマ区切りを取り除くには |substitute()| が使える: > let f = str2float(substitute(text, ',', '', 'g')) < {|+float| 機能つきでコンパイルされたときのみ有効} str2nr( {expr} [, {base}]) *str2nr()* 文字列{expr}を数値に変換する。 - {base}は変換の底。8、10、16のいずれか。 + {base}は変換の底。2、8、10、16のいずれか。 {base}を省略すると10となる。そのため、文字列の先頭に0があると き、デフォルトの文字列・数値変換とは異なり、8進数とは解釈され ない。 {base}が16のとき、文字列の先頭の "0x" と "0X" は無視される。そ - れ以外の底の場合は0となる。 + れ以外の底の場合は0となる。 Similarly, when + {base} is 8 a leading "0" is ignored, and when {base} is 2 a + leading "0b" or "0B" is ignored. 数値の後のテキストは暗黙に無視される。 -strchars({expr}) *strchars()* - 文字列 {expr} 内の文字の数を返す。合成文字は別々にカウントされ - る。 +strchars({expr} [, {skipcc}]) *strchars()* + 結果は数値で、文字列 {expr} の文字の数を返す。 + {skipcc} を省略またはゼロを指定すると、合成文字は別々にカウン + トされる。 + {skipcc} に 1 を指定すると、合成文字は無視される。 + {訳注: 基底文字と結合文字をまとめて1としてカウントする} |strlen()|, |strdisplaywidth()|, |strwidth()| も参照。 + + {skipcc} is only available after 7.4.755. For backward + compatibility, you can define a wrapper function: > + if has("patch-7.4.755") + function s:strchars(str, skipcc) + return strchars(a:str, a:skipcc) + endfunction + else + function s:strchars(str, skipcc) + if a:skipcc + return strlen(substitute(a:str, ".", "x", "g")) + else + return strchars(a:str) + endif + endfunction + endif +< + strdisplaywidth({expr}[, {col}]) *strdisplaywidth()* - 文字列 {expr} のスクリーン上での表示セル幅を返す。 + 結果は数値で、文字列 {expr} が {col} で始まる時のスクリーン上 + での表示セル幅を返す。 {col} が省略されたときはゼロが使われる。{col} には計算を開始す るスクリーン上の列の位置を指定する。これはタブ文字の幅の計算に 影響する。 @@ -5438,20 +6018,13 @@ string({expr}) {expr}を文字列に変換して返す。{expr}が数値、浮 |strtrans()|も参照。 *strlen()* -strlen({expr}) 結果は数値で、文字列{expr}の長さ。 - マルチバイト文字の個数を数えるには次のようなことをする(合成文 - 字は数えない): > - - :let len = strlen(substitute(str, ".", "x", "g")) -< +strlen({expr}) 結果は数値で、文字列{expr}のバイト単位での長さ。 引数が数値の場合は、まず文字列に変換される。 それ以外の型の場合はエラーとなる。 - |len()|, |strchars()|, |strdisplaywidth()|, |strwidth()| も参 - 照。 - + マルチバイト文字の数を数える場合は|strchars()|を使用する。 + |len()|, |strdisplaywidth()|, |strwidth()| も参照。 - *strpart()* -strpart({src}, {start}, {len}) +strpart({src}, {start}[, {len}]) *strpart()* 結果は文字列で、{src}の{start}番目の文字から始まる、長さ{len} の部分文字列。存在しない文字を含むように範囲を指定しても、エ ラーにはならない。単に文字が省略されるだけである。 @@ -5491,18 +6064,28 @@ strtrans({expr}) 表示する。 strwidth({expr}) *strwidth()* - 文字列 {expr} のスクリーン上での表示セル幅を返す。タブ文字の幅 - は 1 として数えられる (タブ文字の幅も考慮したい場合は - |strdisplaywidth()| を使うこと)。 + 結果は数値で、文字列 {expr} のスクリーン上での表示セル幅を返 + す。タブ文字の幅は 1 として数えられる (タブ文字の幅も考慮した + い場合は|strdisplaywidth()| を使うこと)。 {expr} に幅が曖昧 (Ambiguous) な東アジアの文字が含まれていると きは、文字幅は 'ambiwidth' の設定に依存する。 |strlen()|, |strdisplaywidth()|, |strchars()| も参照。 -submatch({nr}) *submatch()* +submatch({nr}[, {list}]) *submatch()* |:substitute| や substitute() 関数の中の式でのみ使われる。 マッチしたテキストの{nr} 番目の部分マッチを返す。{nr}が0のとき はマッチしたテキスト全体を返す。 + Note: 文字列中の NL 文字は複数行マッチにおける改行文字か、NUL + 文字のどちらかである。 |sub-replace-expression| も参照。 + + {list} に非ゼロの値が指定されたときは submatch() は文字列のリ + ストを返す。|getline()| に 2 つの引数を指定したときの返り値と + 同じである。テキスト中の NL 文字は NUL 文字を表す。 + |:substitute| で使われたときのみ複数要素のリストを返す。 + |substitute()| では、実際の改行はそこにはないので、リストは常 + に 0 または 1 つの要素である。 + 例: > :s/\d\+/\=submatch(0) + 1/ < この例は、行の中で最初の数値を検索し、それに1を加える。改行は @@ -5552,6 +6135,9 @@ synID({lnum}, {col}, {trans}) *synID()* 最左のカラムを指定するには{col}に1を、最初の行を指定するには {line}に1を指定する。'synmaxcol' が適用され、長すぎる行では0が 返ってくる。 + Note that when the position is after the last character, + that's where the cursor can be in Insert mode, synID() returns + zero. {trans}が非ゼロならば、透過属性のアイテムは省略され、実際に表 示されているアイテムが評価対象になる。これは実際に有効になって @@ -5633,30 +6219,49 @@ synstack({lnum}, {col}) *synstack()* 最後の文字の一つ後ろと空行の一番目の列は有効な位置である。 system({expr} [, {input}]) *system()* *E677* - シェルコマンド{expr}の実行結果を得る。 - {input}が与えられた場合は、この文字列はファイルに書き出され、 - コマンドの標準入力として渡される。この文字列はそのまま(as-is) - 書き出され、正しい改行文字を使うよう自分自身で気を付けなければ - ならない。パイプは使われない。 - Note: |shellescape()| を使ってコマンドの引数をエスケープするこ - と。{expr}内に改行が含まれるとコマンドが失敗する可能性がある。 - 'shellquote' と 'shellxquote' に入っている文字は問題を引き起こ - すかもしれない。 + シェルコマンド {expr} の実行結果を文字列として得る。リストとし + て受け取るには |systemlist()| を参照。 + + {input} に文字列が指定された場合、その文字列はファイルに書き出 + され、コマンドの標準入力として渡される。この文字列はそのまま + (as-is) 書き出されるので、正しい改行文字を使うよう自分自身で気 + を付けなければならない。 + {input} にリスト (|List|) が指定された場合は、|writefile()| の + {binary} に "b" を指定したのと同様にファイルに書き出される (つ + まり、リストの各要素は改行文字で連結され、要素内の改行文字は + NUL 文字に変換される)。 + パイプは使用されない。 + + |:silent| が前置されたときは、シェルは cooked モードには設定さ + れない。これはユーザー入力を必要としないコマンドを使用すること + を意味する。これは画面に不要な文字が表示されるのを防ぐ + (|CTRL-L| でそれをクリアする必要がなくなる)。 > + :silent let f = system('ls *.vim') +< + Note: コマンドの引数をエスケープするには、 |shellescape()|、 + |expand()| の |::S|、または |fnamemodify()| を使用する。{expr} + 内に改行文字があるとコマンドは失敗するだろう。'shellquote' や + 'shellxquote' 内にある文字も問題を起こすかもしれない。 対話的なコマンドを使用することはできない。 + 戻り値は文字列。例: > :let files = system("ls " . shellescape(expand('%:h'))) + :let files = system('ls ' . expand('%:h:S')) < システムに依存しないような戻り値にするために、シェルの出力を フィルタリングし、マッキントッシュにおいてはをに変換 し、DOS系のシステムにおいてはをに変換している。 実行されるコマンドはいくつかのオプションを適用して構成される: + 文字列が NUL 文字で切れるのを防ぐため、すべての NUL 文字は SOH + (0x01) に置換される。 + 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote' ({tmp}は自動的に生成されるファイル名) UnixとOS/2ではコマンドの連結ができるように{expr}の両側に波括弧 が置かれる。 - コマンドは「coocked」モードで実行される。そのためCTRL-Cでコマ - ンドを中断できる(少なくともUnixでは)。 + コマンドは「cooked」モードで実行される。そのためCTRL-Cでコマン + ドを中断できる(少なくともUnixでは)。 エラーコードは|v:shell_error|に格納される。 この関数は|restricted-mode|では失敗する。 @@ -5668,6 +6273,14 @@ system({expr} [, {input}]) *system()* *E677* い。 明示的にチェックさせるには|:checktime|を使う。 +systemlist({expr} [, {input}]) *systemlist()* + |system()| と同じだが行のリスト (|List|) を返す。行は NL 文字 + で区切られ、NUL 文字は NL 文字に変換される。出力は + |readfile()| の {binary} 引数に "b" を指定したのと同様である。 + + エラー時には空文字列が返るので |E706| エラーに注意。 + + tabpagebuflist([{arg}]) *tabpagebuflist()* カレントタブページ内の各ウィンドウに表示されているバッファの番 号を要素とするリスト|List|を返す。{arg}は対象とするタブページ @@ -5690,16 +6303,16 @@ tabpagenr([{arg}]) *tabpagenr()* この番号はコマンド|:tab|で指定できるものと同じである。 -tabpagewinnr({tabarg}, [{arg}]) *tabpagewinnr()* +tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()* |winnr()|と同様だが、タブページ{tabarg}を対象とする。 {tabarg}は対象とするタブページの番号を指定する。 {arg}は|winnr()|の場合と同じように扱われる。すなわち: - 省略するとカレントウィンドウの番号を返す。これは、このタブペー ジに入るとき使われるウィンドウである。 - - "$" とするとウィンドウ番号を返す。 + - "$" とするとウィンドウの個数を返す。 - "#" とすると前のウィンドウ番号を返す。 役に立つ例: > - tabpagewinnr(1) " タブぺージ1のカレントウィンドウ + tabpagewinnr(1) " タブページ1のカレントウィンドウ tabpagewinnr(4, '$') " タブページ4内のウィンドウの個数 < {tabarg}が無効なときは0を返す。 @@ -5807,7 +6420,6 @@ trunc({expr}) *trunc()* {expr} をゼロ方向に切りつめた整数を |Float| で返す。 {expr} は |Float| または |Number| に評価されなければならない。 例: > - Examples: > echo trunc(1.456) < 1.0 > echo trunc(-5.456) @@ -5824,6 +6436,8 @@ type({expr}) {expr}の型を示す数値を返す: リスト: 3 辞書: 4 浮動小数点数: 5 + Boolean: 6 (v:false and v:true) + None 7 (v:null and v:none) マジックナンバーを使わずに、次のような使い方をすべきである: > :if type(myvar) == type(0) :if type(myvar) == type("") @@ -5831,6 +6445,8 @@ type({expr}) {expr}の型を示す数値を返す: :if type(myvar) == type([]) :if type(myvar) == type({}) :if type(myvar) == type(0.0) + :if type(myvar) == type(v:false) + :if type(myvar) == type(v:none undofile({name}) *undofile()* {name} という名前のファイルの保存時に使用されるアンドゥファイ @@ -5885,6 +6501,14 @@ undotree() *undotree()* が入れ子にされている。それぞれのアイテムはさら に "alt" アイテムを持っていることがある。 +uniq({list} [, {func} [, {dict}]]) *uniq()* *E882* + {list} 内の隣接する同じ値の要素の 2 個目以降をその場で + (in-place) 削除する。{list} を返す。リストを変更したくない場合 + は事前にコピーする: > + :let newlist = uniq(copy(mylist)) +< デフォルトの比較関数は各要素の文字列表現を使う。{func} と + {dict} については |sort()| 参照。 + values({dict}) *values()* {dict}の全ての値からなるリスト|List|を返す。このリストの順序は 不定である。 @@ -5911,6 +6535,9 @@ virtcol({expr}) *virtcol()* +1となる) 'x マークxの位置(マークが設定されていない場合、0が返 る) + v ビジュアルモードでは: ビジュアル選択領域の開始行 + (カーソルがその端)。ビジュアルモード以外ではカーソ + ル位置を返す。すぐに更新される点が |'<| と違う。 現在のファイルに対して設定されているマークだけが使用可能なこと に注意。 例: > @@ -5926,7 +6553,7 @@ visualmode([expr]) *visualmode()* ドを教えてくれる。初期状態では単に空文字列を返すだけだが、一度 でもビジュアルモードが使われた場合、その種類によって "v" か "V" か "" (CTRL-Vの文字が1文字で) 返される。これはそれ - ぞれ文字選択、行選択、ブロック選択を意味している。 + ぞれ文字選択、行選択、矩形選択を意味している。 例: > exe "normal " . visualmode() < これは最後に使われたのと同じビジュアルモードに入る。また、スク @@ -6010,6 +6637,16 @@ winrestcmd() 現在のウィンドウサイズを復元するための一連の| winrestview({dict}) |winsaveview()|が返す辞書|Dictionary|を使ってカレントウィンド ウの表示状態を復元する。 + Note: {dict} は |winsaveview()| の返り値に含まれる値をすべて + 持っていなくても構わない。値がない場合はその設定は復元されな + い。次のようにできる: > + :call winrestview({'curswant': 4}) +< + これは curswant 値 (縦方向移動でカーソルの移動先として使われる + 列番号) を列番号 5 に設定する (はいそのとおり。5 です)。ほかの + 設定値は変更されない。これはカーソル位置を手動で設定したい場合 + に便利である。 + この値を手動で変更した場合、結果は予測できない。 ウィンドウサイズが変更されていると、結果は必ずしも元通りになら ない。 @@ -6022,10 +6659,11 @@ winsaveview() カレントウィンドウの表示状態を復元するための る。 折り畳み情報は保存しない。オプション 'foldenable' によって一時 的に折り畳みをオフにし、移動中に折り畳みが開かれないようにする - こと。 + こと。これは副作用があるかもしれない。 戻り値は以下のキーを持つ: lnum カーソルの行番号 - col カーソルの桁番号 + col カーソルの桁番号 (Note: getpos() とは + 異なり最初の桁番号はゼロ) coladd カーソル位置の桁オフセット。 'virtualedit' がオンのとき使われる。 curswant 垂直移動するときの桁 @@ -6046,14 +6684,40 @@ winwidth({nr}) *winwidth()* : exe "normal 50\|" :endif < +wordcount() *wordcount()* + The result is a dictionary of byte/chars/word statistics for + the current buffer. This is the same info as provided by + |g_CTRL-G| + The return value includes: + bytes Number of bytes in the buffer + chars Number of chars in the buffer + words Number of words in the buffer + cursor_bytes Number of bytes before cursor position + (not in Visual mode) + cursor_chars Number of chars before cursor position + (not in Visual mode) + cursor_words Number of words before cursor position + (not in Visual mode) + visual_bytes Number of bytes visually selected + (only in Visual mode) + visual_chars Number of chars visually selected + (only in Visual mode) + visual_words Number of chars visually selected + (only in Visual mode) + *writefile()* -writefile({list}, {fname} [, {binary}]) +writefile({list}, {fname} [, {flags}]) |List| {list}をファイル{fname}に書き込む。リストの各要素は改行 文字(NL)で区切られる。各要素は文字列か数値でなければならない。 - {binary}が "b" のときはバイナリモードとなり、最後の要素の後に - NLが追加されない。最後の要素が空であると、ファイルの最後の行が - NLで終わるようになる。 - NL文字はNUL文字に置換される。 + {flags}が "b" を含むときはバイナリモードとなり、最後の要素の後 + にNLが追加されない。最後の要素が空であると、ファイルの最後の行 + がNLで終わるようになる。 + {flags}が "a" を含むときは追記モードとなり、ファイルに行が追記 + される。 > + :call writefile(["foo"], "event.log", "a") + :call writefile(["bar"], "event.log", "a") +> +< NL文字はNUL文字に置換される。 CR文字を加えるには、{list}をwritefile()に渡す前に行わねばなら ない。 既存のファイルは上書きされる(上書き可能ならば)。 @@ -6074,18 +6738,28 @@ xor({expr}, {expr}) *xor()* < *feature-list* -機能は大別して3つの系統に分けられる: +機能は大別して 4 つの系統に分けられる: 1. コンパイル時に|+feature-list|とした時にだけサポートされる機能。例: > :if has("cindent") 2. ある状態の時にだけサポートされる機能。例: > :if has("gui_running") < *has-patch* -3. 適用済みパッチ。最初に|v:version|によってVimのバージョンを確認する。 - 機能 "patch123" はパッチ123が適用されていることを示す。例 (バージョン - 6.2.148以降であることを確認する): > +3. 適用済みパッチ。"patch123" はパッチ 123 が適用されていることを示す。Note: + この形式は Vim のバージョンをチェックしない。あなたは |v:version| を解析す + る必要がある。 + 例 (6.2.148 以降かどうかを確認する): > :if v:version > 602 || v:version == 602 && has("patch148") -< Note 148が適用されていても、147が抜けていることもありうるので注意。 +< Note: 148 が適用されていても、147 が抜けていることもありうるので注意。 +4. 特定のバージョン以降であるか、またはバージョンが同じで特定のパッチが含まれ + ているかどうか。"patch-7.4.237" は、Vim のバージョンが 7.5 以降か、または + 7.4 でパッチ 237 を含んでいるかどうかを示す。 + Note: これはパッチ 7.4.237 以降でのみ機能する。それ以前では上述のように + v:version を確認する必要がある。例: > + :if has("patch-7.4.248") +< Note: 148 が適用されていても、147 が抜けていることもありうるので注意。 + +acl |ACL| をサポート all_builtin_terms 全ての組込みターミナルを有効にしてコンパイル amiga AMIGAバージョン arabic アラビア語をサポート |Arabic| @@ -6094,7 +6768,7 @@ autocmd オートコマンドをサポート |autocommand| balloon_eval |balloon-eval| をサポート balloon_multiline 複数行バルーンをサポート beos BeOSバージョン -browse |:browse|をサポートし、browseが恐らく動作する +browse |:browse|をサポートし、browse()が動作する browsefilter |browsefilter| をサポート builtin_terms 幾つかの組込みターミナルが有効 byte_offset 'statusline' において 'o' がサポートされる @@ -6113,6 +6787,7 @@ dialog_con コンソールダイアログのサポート dialog_gui GUIダイアログのサポート diff |vimdiff| と 'diff' のサポート digraphs ダイグラフをサポート +directx Direct-X と 'renderoptions' をサポート dnd レジスタ "~ をサポート |quote_~| dos16 16ビットDOSバージョン dos32 32ビットDOSバージョン (DJGPP) @@ -6151,12 +6826,13 @@ jumplist |jumplist| をサポート keymap 'keymap' をサポート langmap 'langmap' サポート libcall |libcall()| をサポート -linebreak 'linebreak', 'breakat' そして 'showbreak' をサポート +linebreak 'linebreak'、'breakat'、'showbreak'、'breakindent' を + サポート lispindent lisp式のインデントをサポート listcmds バッファリスト用のコマンド|:files|と引数リスト用のコマ ンド|arglist|をサポート localmap ローカルなマッピングと短縮入力をサポート|:map-local| -lua Lua インターフェースをサポート |Lua| +lua Lua インターフェイスをサポート |Lua| mac マッキントッシュバージョン macunix Unixファイル用のマッキントッシュバージョン(OS-X) menu |:menu|をサポート @@ -6187,8 +6863,8 @@ persistent_undo 永続アンドゥをサポート postscript PostScriptファイルの印刷をサポート printer |:hardcopy| をサポート profile |:profile| をサポート -python Python 2.x インターフェースをサポート |has-python| -python3 Python 3.x インターフェースをサポート |has-python| +python Python 2.x インターフェイスをサポート |has-python| +python3 Python 3.x インターフェイスをサポート |has-python| qnx QNXバージョン quickfix |quickfix|をサポート reltime |reltime()|をサポート @@ -6210,7 +6886,7 @@ system fork()/exec()の代わりにsystem()が使用されている tag_binary タグファイル内のバイナリサーチ |tag-binary-search| tag_old_static 旧式の静的tagsをサポート |tag-old-static| tag_any_white タグファイル内の空白文字をサポート |tag-any-white| -tcl TCLインターフェースをサポート +tcl TCLインターフェイスをサポート terminfo termcapの代わりにterminfoをサポート termresponse |t_RV|と|v:termresponse|をサポート textobjects |text-objects|をサポート @@ -6239,7 +6915,9 @@ windows 複数ウィンドウをサポート writebackup オプション 'writebackup' が起動時にonになる xfontset X fontsetをサポート |xfontset| xim XIMをサポート |xim| -xpm_w32 Win32 で pixmap をサポート +xpm pixmap をサポート +xpm_w32 Win32 で pixmap をサポート(後方互換性のためのみ。 + 代わりに "xpm" を使用せよ。) xsmp Xセッションマネージメントをサポート xsmp_interact 対話的Xセッションマネージメントをサポート xterm_clipboard xtermのクリップボードサポート @@ -6286,6 +6964,8 @@ x11 X11をサポート ユーザー定義コマンド、オートコマンドからしか呼ぶことができない。そのスクリプト 内で定義されたマッピングにより呼ぶこともできるが、スクリプトの外部でマッピング が展開された場合は "s:" の代わりに || をつけなければならない。 +ローカル関数はスクリプトローカル関数だけである。バッファローカル関数やウィンド +ウローカル関数というものはない。 *:fu* *:function* *E128* *E129* *E123* :fu[nction] 全ての関数と、その引数を表示する。 @@ -6309,12 +6989,15 @@ x11 X11をサポート < より詳しくは|:verbose-cmd|を参照。 - *E124* *E125* *E853* + *E124* *E125* *E853* *E884* :fu[nction][!] {name}([arguments]) [range] [abort] [dict] {name}という名前で新しい関数を定義する。関数名はアル ファベットと数字と '_' からなり、通常の関数はアルファ ベットの大文字、スクリプトローカル関数は "s:" で始まら - なければならない。 + なければならない。Note: "b:" や "g:" は使用できない + (7.4.260 からは関数名にコロンが含まれる場合は E884 エ + ラーが発生する。例 "foo:bar()"。このパッチ以前はエラー + にはならない)。 {name}は辞書|Dictionary|の要素の|Funcref|であってもよ い: > @@ -6333,7 +7016,7 @@ x11 X11をサポート 引数{arguments}については|function-argument|を参照。 - *a:firstline* *a:lastline* + *:func-range* *a:firstline* *a:lastline* 引数[range]を追加した場合、関数は「範囲」を管理するこ とができる。「範囲」は "a:firstline" と "a:lastline" によって渡される。[range]がなかった場合、 @@ -6342,10 +7025,10 @@ x11 X11をサポート を呼び出すことになる。|function-range-example|を参照。 他の Ex コマンドと同様に、カーソルは選択範囲の最初の行 に移動される。 - + *:func-abort* 引数[abort]を追加すると、関数の実行中にエラーに遭遇し 次第、即関数は中断される。 - + *:func-dict* 引数[dict]を追加すると、この関数は辞書|Dictionary|の要 素を通してしか呼べなくなる。そしてその辞書にローカル変 数 "self" が定義される。|Dictionary-function|を参照。 @@ -6385,7 +7068,7 @@ x11 X11をサポート 引数は、与えられた名前によって定義される。関数のなかでは "a:name" ("a:" を引数 に接頭)のようにして参照することができる。 *a:0* *a:1* *a:000* *E740* *...* -引数はカンマで区切ることで、最大20まで与えることができる。最後の引数を "..." +引数はコンマで区切ることで、最大20まで与えることができる。最後の引数を "..." にすることで、可変長の引数を使用できる。関数の中では "a:1" や "a:2" のようにし て可変長の引数にアクセスできる。"a:0" は可変長引数が幾つあるかを示している (0 であること、つまり引数がそれ以上ないこともある)。"a:000" は全引数を持つリスト @@ -6423,7 +7106,7 @@ a: のスコープとこの変数は固定されており、変更できない let lines = Table("Table", "line1", "line2") let lines = Table("Empty Table") -一つ以上の値を返したい場合には、グローバル変数の名前を渡すようにする: > +一つ以上の値を返したい場合には、リスト|List|を返すようにする: > :function Compute(n1, n2) : if a:n2 == 0 : return ["fail", 0] @@ -6602,7 +7285,7 @@ Vimはこれを見つけると、まず波括弧の中の式を評価し、そ ============================================================================== 7. コマンド *expression-commands* -:let {var-name} = {expr1} *:let* +:let {var-name} = {expr1} *:let* *E18* 内部変数{var-name}に式{expr1}の結果をセットする。変数 の型は{expr1}によって決定される。{var-name}という変数 がまだ存在しない場合、新たに作成される。 @@ -6649,8 +7332,7 @@ Vimはこれを見つけると、まず波括弧の中の式を評価し、そ 無しレジスタとして使用でき、"@/" はサーチパターンとし て使用できる。 {expr1}の結果がかで終了していた場合、レジスタ - は行単位で設定され、そうでなければキャラクタ単位で設定 - される。 + は行単位で設定され、そうでなければ文字単位で設定される。 次のコマンドにより最後に検索したパターンをクリアするこ とができる: > :let @/ = "" @@ -6710,7 +7392,7 @@ Vimはこれを見つけると、まず波括弧の中の式を評価し、そ :let i = 0 :let [i, x[i]] = [1, 2] :echo x -< 子の結果は[0, 2]となる。 +< この結果は[0, 2]となる。 :let [{name1}, {name2}, ...] .= {expr1} :let [{name1}, {name2}, ...] += {expr1} @@ -6776,7 +7458,7 @@ Vimはこれを見つけると、まず波括弧の中の式を評価し、そ :unlet v < *E741* ロックされた変数を変更しようとするとエラーメッセージ - "E741: Value of {name} is locked" が表示される。 + "E741: Value is locked: {name}" が表示される。 [depth]はリスト|List|や辞書|Dictionary|をロックすると きに意味がある。どれだけ深くロックするかを指定する: @@ -6812,7 +7494,7 @@ Vimはこれを見つけると、まず波括弧の中の式を評価し、そ 内部変数{name}をアンロックする。|:lockvar|の逆を行う。 -:if {expr1} *:if* *:endif* *:en* +:if {expr1} *:if* *:endif* *:en* *E171* *E579* *E580* :en[dif] {expr1}が非ゼロと評価された場合に、対応する ":else" か ":endif" までの命令を実行する。 @@ -6927,8 +7609,8 @@ Vimはこれを見つけると、まず波括弧の中の式を評価し、そ エラーや割り込みが検出された場合、後に|:finally|コマン ドがあるならば、":finally" の後から実行が継続される。 - そうでければ、または ":endtry" に達した後は次の動的に - 囲んでいる ":try" に対応する ":finally" などが探され + そうでなければ、または ":endtry" に達した後は次の動的 + に囲んでいる ":try" に対応する ":finally" などが探され る。その後スクリプトは実行を停止する。(関数定義に引数 "abort" がついているかどうかは関係ない) 例: > @@ -6972,6 +7654,8 @@ Vimはこれを見つけると、まず波括弧の中の式を評価し、そ {pattern}を囲むのに/以外の文字を使うことができる。ただ しその文字は特別な意味(例: '|' や '"' など)を持ってい てはならず、{pattern}の内側に現れてはならない。 + 例外の情報は |v:exception| で得られる。 + |throw-variables| も参照。 NOTE: エラーメッセージの本文によって ":catch" すること は確実ではない。メッセージはロケールによって異なるから である。 @@ -7110,13 +7794,22 @@ Vimはこれを見つけると、まず波括弧の中の式を評価し、そ 与えるときは |shellescape()| を使う。 例: > :execute "e " . fnameescape(filename) - :execute "!ls " . shellescape(expand('%:h'), 1) + :execute "!ls " . shellescape(filename, 1) < - Note: executeに渡す文字列としては、"while" や "for" - や "if" コマンドが始まったり終ったりするだけのようなも - のは不適格である。よって次のような例は認められない: > - :execute 'while i > 5' - :execute 'echo "test" | break' + Note: execute に渡す文字列はいかなるコマンドでも構わな + いが、"if" や "while"、"for" の開始や終了は常に機能す + るとは限らない。なぜならコマンドをスキップするときには + ":execute" は解釈されないので Vim はブロックの開始や終 + 了を認識することができない。"break" と "continue" も + ":execute" で実行すべきではない。 + 次の例は機能しない。":execute" は評価されず、Vim は + "while" を認識しないので、":endwhile" を見つけたときに + エラーが発生する: > + :if 0 + : execute 'while i > 5' + : echo "test" + : endwhile + :endif < 文字列の中に完全な "while" や "if" コマンドが含まれる ことが求められる: > @@ -7596,7 +8289,7 @@ finally節におけるエラーにより、割り込みが正しく動作しな :function nofunc と > :delfunction nofunc -は両方とも次のエラーメッセージを表示する。 +は両方とも次のエラーメッセージを表示する。 > E128: Function name must start with a capital: nofunc これはtry条件節の中では例外に変換される。それぞれ > Vim(function):E128: Function name must start with a capital: nofunc @@ -8251,11 +8944,11 @@ Vimの現在の処理を混乱させたり破壊してしまうような動作 起こりうる。 テキストロックが有効になっているときは、以下の事が禁止される: - - バッファの変更 + - バッファのテキスト変更 - 他のバッファやウィンドウへの移動 - 他のファイルを開く - - ウィンドウを閉じる。Vimを終了する。 - - など。 + - ウィンドウを閉じたりVimを終了したり + - その他 vim:tw=78:ts=8:ft=help:norl: diff --git a/doc/evim-ja.UTF-8.1 b/doc/evim-ja.UTF-8.1 deleted file mode 100644 index 1b7a657eb..000000000 --- a/doc/evim-ja.UTF-8.1 +++ /dev/null @@ -1,51 +0,0 @@ -.TH EVIM 1 "2002 February 16" -.SH 名前 -evim \- easy Vim, モードレスエディタ Vim -.SH 書式 -.br -.B evim -[options] [file ..] -.br -.B eview -.SH 説明 -.B eVim -は -.B Vim -を起動して、モードレスエディタとして動作するためのオプションを設定します。 -Vim の動作が point-and-click エディタのような動作になります。 -MS-Windows のメモ帳のような動作です。 -.B eVim -は常に GUI で起動し、メニューとツールバーを表示します。 -.PP -どうしても Vim の操作に馴染めない場合に使ってください。 -編集効率は下がります。 -.PP -.B eview -は同様に、読み込み専用モードで起動します。evim \-R と同じです。 -.PP -引数や Vim についての詳細は vim(1) を参照してください。 -.PP -オプション 'insertmode' が設定され、テキストを直接、入力できるようになりま -す。 -.br -コピーとペーストのキー操作が MS-Windows と同じになるように、マップが設定され -ます。 -CTRL-X が切り取り、CTRL-C がコピー、CTRL-V がペーストです。 -標準の CTRL-V の操作は CTRL-Q に割り当てられます。 -.SH オプション -vim(1) を参照してください。 -.SH ファイル -.TP 15 -/usr/local/lib/vim/evim.vim -eVim の初期化スクリプト。 -.SH 別名 -evim は "gumbies のための Vim" とも呼ばれています。 -evim を使っているあなたはきっと、頭にハンカチをかぶっているのです。 -(訳注: gumbies は Monty Python に登場するおもしろ集団。ハンカチをかぶっ -ている。) -.SH 関連項目 -vim(1) -.SH 著者 -.B Vim -のほとんどの機能は Bram Moolenaar が開発し、多くの人が協力しました。 -メニューの Help/Credits を参照してください。 diff --git a/doc/farsi.jax b/doc/farsi.jax index 20d1e93cc..f1cecd520 100644 --- a/doc/farsi.jax +++ b/doc/farsi.jax @@ -1,4 +1,4 @@ -*farsi.txt* For Vim バージョン 7.4. Last change: 2010 Aug 07 +*farsi.txt* For Vim バージョン 7.4. Last change: 2015 Aug 29 VIMリファレンスマニュアル by Mortaza Ghassab Shiran @@ -21,7 +21,7 @@ 語のメモ書きなどをするときにとても便利です。 コマンド、プロンプト、ヘルプファイルなどはペルシア語ではないため、ユーザーイン -ターフェースは Vi 標準のインターフェースと変わりません。 +ターフェイスは Vi 標準のインターフェイスと変わりません。 特色 @@ -55,7 +55,7 @@ o ペルシア語の ISIR-3342 標準エンコーディングと Vim Farsi は ンキーで切り替えられます。これは、右横書きのテキストに対してのみ意味をなす ので、右横書きモードでのみ利用できます。 -ペルシア語フォント *farsi fonts* +ペルシア語フォント *farsi-fonts* ------------------ 次のファイルは '$VIM/farsi/fonts' ディレクトリ以下にあります: diff --git a/doc/filetype.jax b/doc/filetype.jax index 26728e396..7a8fc8f30 100644 --- a/doc/filetype.jax +++ b/doc/filetype.jax @@ -1,4 +1,4 @@ -*filetype.txt* For Vim バージョン 7.4. Last change: 2013 May 25 +*filetype.txt* For Vim バージョン 7.4. Last change: 2015 Dec 06 VIMリファレンスマニュアル by Bram Moolenaar @@ -124,7 +124,7 @@ NOTE: Vi互換とは全てのオプションがグローバルであることを filetype detection:ON plugin:ON indent:OFF ファイル形式は構文強調にも利用される。":syntax on" コマンドが使用されると、ファ -イル形式検出もインストールされる。":filetype on" の後に ":syntax on" を実行す +イル形式検出もインストールされる。":syntax on" の後に ":filetype on" を実行す る必要はない。 特定のファイル形式を無効にするには、自分のファイル形式ファイルに1行追加する。 @@ -258,8 +258,8 @@ D. ファイル形式がファイルの内容を調べる事によってのみ 3. これだけで検出は正しく動作し、Vimを再起動する必要は無い。 新しく作成したscripts.vimはデフォルトのファイル形式チェックの前に読み込まれ - ので、$VIMRUNTIME/scripts.vimに書かれたデフォルトの判定規則を上書することが - できる。 + るので、$VIMRUNTIME/scripts.vimに書かれたデフォルトの判定規則を上書きするこ + とができる。 *remove-filetype* ファイル形式が誤って検出されたならば、(上を参考に)それを補正するfiletype.vimか @@ -297,7 +297,7 @@ OSによる「形式」を利用するには自動実行コマンドの検出パ はVimのバージョン(稼動しているOS)によって定義される。未知の形式は適合しない とみなされる。 -「形式」とパターンを同時に指定することもできる (そのような場合には、両方供マッ +「形式」とパターンを同時に指定することもできる (そのような場合には、両方共マッ チする必要がある): > :au BufRead <&fff>diff* @@ -347,7 +347,7 @@ OSによる「形式」を利用するには自動実行コマンドの検出パ ともあり得る。幾つかこれを回避する方法がある: 1. "maplocalleader" にキーマップの先頭に使用するキーシーケンスを設定する。例: > :let maplocalleader = "," -< デフォルトのバックスラッシュ(\ 記号)に替えてカンマが全てのマップの始まりの +< デフォルトのバックスラッシュ(\ 記号)に替えてコンマが全てのマップの始まりの キーになる。||も参照。 2. 独自のマップを定義する。例: > @@ -451,20 +451,22 @@ g:changelog_new_date_format %% 一つの '%' が入る %d 上記で定義した日付 %u 上記で定義したユーザーの名前 + %p b:changelog_entry_prefix の結果 %c 作成後のカーソルの位置 - デフォルトは "%d %u\n\n\5* %c\n\n"。これは次のように - なる ( | はカーソルの位置を示している。しかし、行頭 + デフォルトは "%d %u\n\n\t* %p%c\n\n"。これは次のよう + になる ( | はカーソルの位置を示している。しかし、行頭 の | は行の始まりを表す) > |2003-01-14 Full Name | - | * | + | * prefix| < g:changelog_new_entry_format アイテムを作成するときの書式。 次の特別な文字が使える: + %p b:changelog_entry_prefix の結果 %c 作成後のカーソルの位置 デフォルトは "\t*\c"。これは次のようになる > - | * | + | * prefix| < g:changelog_date_entry_search 日付エントリを探すための検索パターン。 @@ -532,8 +534,8 @@ GIT COMMIT *ft-gitcommit-plugin* ラーメッセージの原因となる可能性を排除するために、モード行はオ フになる。 'textwidth' 72に設定する。e-mailでは良く推奨される値。 -'formatoptions' テキストを折返し、新しい行ではコメントリーダを繰り返すように設 - 定。引用記号の ">" が繰り返される。 +'formatoptions' テキストを折返し、新しい行ではコメントリーダーを繰り返すように + 設定。引用記号の ">" が繰り返される。 これにより|gq|で引用文を整形できる。 ローカルキーマップ: @@ -542,7 +544,7 @@ GIT COMMIT *ft-gitcommit-plugin* 位置からファイル末端までのテキストを引用する。これは全ての行に "> " が 挿入されることを意味している。 -MAN *ft-man-plugin* *:Man* +MAN *ft-man-plugin* *:Man* *man.vim* マニュアルページを洗練された方法で表示する。ユーザーマニュアルの |find-manpage|も参照のこと。 @@ -568,6 +570,13 @@ Man {number} {name} ローカルキーマップ: CTRL-] カーソルの下の単語についてのマニュアルページへ移動する。 CTRL-T 直前のマニュアルページへ戻る。 +q ":quit" と同じ + +折畳を有効にするにはこの変数を使う: > + let g:ft_man_folding_enable = 1 +もしデフォルトの折畳が好みではないのなら、代わりに autocommand を使って望んだ +折畳スタイルを追加できる。例: > + autocmd FileType man setlocal foldmethod=indent foldenable PDF *ft-pdf-plugin* @@ -599,7 +608,7 @@ TEX *ft-tex-plugin* *g:tex_flavor* *.tex ファイルの最初の行が次のような形なら > %& -ファイルタイプは次のどれかになる: plaintex (プレイン TeX), context (ConTeXt), +ファイルタイプは次のどれかになる: plaintex (プレーン TeX), context (ConTeXt), tex (LaTeX)。そうでなければ context か tex かを決定するためにファイル内から キーワードを検索する。もしキーワードが見つからなければ既定値として plaintex に なる。この既定値は、変数 g:tex_flavor を定義すれば変更することができる。次のど diff --git a/doc/fold.jax b/doc/fold.jax index 084a3bf3a..a48d0fb6b 100644 --- a/doc/fold.jax +++ b/doc/fold.jax @@ -1,4 +1,4 @@ -*fold.txt* For Vim バージョン 7.4. Last change: 2010 May 13 +*fold.txt* For Vim バージョン 7.4. Last change: 2016 Jan 02 VIMリファレンスマニュアル by Bram Moolenaar @@ -94,8 +94,10 @@ Cではプリプロセッサ行を無視するために "#" を使用する。 -1 折畳レベルを未定義とし、対象行の直前か直後の行のうち低 い方を、対象行のレベルとする。 "=" 直前の行と同じレベルを使用する - "a1", "a2", .. 直前の行のレベルを+1, +2して設定する - "s1", "s2", .. 直前の行のレベルを-1, -2して設定する + "a1", "a2", .. 直前の行のレベルを+1, +2して、結果を現在の行に適用す + る。 + "s1", "s2", .. 直前の行のレベルを-1, -2して、結果を現在の行に適用す + る。 "<1", "<2", .. 指定したレベルの折畳を対象行で終了する ">1", ">2", .. 指定したレベルの折畳を対象行から開始する @@ -117,6 +119,18 @@ NOTE: 各行について式評価が実行されるので、この折畳方式 折畳レベルが定義された行が見つかるまで戻って、幾度も検索を行わなければならない からだ。これは動作が遅くなることがある。 +"a1" と "s1" の使用例: C 言語の複数行コメントを折りたたむ場合、"/*" を含む行で +は "a1" を返してその開始位置を、"*/" を含む行では "s1" を返してその終了位置を示 +す: > + if match(thisline, '/\*') >= 0 + return 'a1' + elseif match(thisline, '\*/') >= 0 + return 's1' + else + return '=' + endif +ただし、単一行コメント内、文字列リテラル内などではこれは正しく機能しない。 + フォールドレベルを調べるには|foldlevel()|を使うのが便利である。レベルがわから ないときは-1を返すことに注意すること。フォールドがその行で終わっているときには 行頭のレベルを返す。 @@ -273,8 +287,9 @@ zF [count]行を折畳として作成する。"zf" と同じように動作す zd カーソルの位置にある折畳を1つ削除する。カーソルが折畳になって いる行にある場合には、その折畳が削除される。入れ子になった折畳 は1レベル分が削除される。ビジュアルモードでは選択された範囲の - 全ての折畳(partially)が削除される。注意: これは期待したよりも - 余計に折畳を削除し易く、またアンドゥもできないので注意が必要。 + 全ての折畳(partially)の1レベル分が削除される。 + 注意: これは期待したよりも余計に折畳を削除し易く、また手動折畳 + に対してはアンドゥもできないので注意が必要。 'foldmethod' が "manual" か "marker" の時だけ動作する。 |fold-delete-marker|も参照。 @@ -350,8 +365,8 @@ zX 手動で行った折畳の開閉操作をアンドゥする: 'foldlevel' 折畳の計算を強制するのにも使える (|zx| と同様)。 *zm* -zm 折畳をより閉じる: 'foldlevel' を1減少させる。'foldlevel' が既 - に0ならば何も起こらない。 +zm 折畳をより閉じる: 'foldlevel' を |v:count1| 減少させる。 + 'foldlevel' が既に0ならば何も起こらない。 'foldenable' がセット(有効化)される。 *zM* @@ -359,7 +374,7 @@ zM 全ての折畳を閉じる: 'foldlevel' に0を設定する。 'foldenable' がセット(有効化)される。 *zr* -zr 折畳をより開く: 'foldlevel' を1増加させる。 +zr 折畳をより開く: 'foldlevel' を |v:count1| 増加させる。 *zR* zR 全ての折畳を開く: 'foldlevel' に最大の折畳レベルを設定する。 @@ -554,11 +569,11 @@ zk カーソルより上方の折畳へ移動する。閉じられた折畳が1 オペレータを使用したときには、閉じた折畳は全体が含まれる。だから "dl" はカーソ ルの下の閉じた折畳の全体を削除してしまう。 -Exコマンドでは、開始位置と終了位置が折畳のそれに常に合わせられてしまう。 -だから次のコマンド: > +バッファの行に作用するExコマンドの作用範囲は、開始位置と終了位置ともに閉じられ +た折畳のそれらへ、それぞれ補正される。よって以下のコマンドを: > :s/foo/bar/g -カーソルを閉じた折畳に置いて実行すると、折畳内の全ての行にある "foo" が "bar" -へ置き換えられてしまう。 +閉じた折畳へカーソルを合わせて実行すると、折畳内の全ての行にある "foo" が +"bar"へ置き換えられてしまう。 これは|:folddoopen|と|:folddoclosed|に対してはあてはまらない。 (同一セッション中で)以前に編集したバッファに対しては、最後の折畳設定が再び使用 diff --git a/doc/ft_ada.jax b/doc/ft_ada.jax index 0e326fdba..37a549227 100644 --- a/doc/ft_ada.jax +++ b/doc/ft_ada.jax @@ -110,8 +110,8 @@ NOTE: "gnat xref -v" はとてもトリッキーで診断情報をほとんど xref -v -aI../Include adacl.ads" を使うこと。 3) "gnat xref -v -aI../Include *.ad?" はうまく動かないので、代わりに "cd ../Include" と "gnat xref -v *.ad?" を使うこと。 -4) プロジェクトマネージャ対応は完全に壊れている。"gnat xref -Padacl.gpr" と試 - してみるのもいけない。 +4) プロジェクトマネージャー対応は完全に壊れている。"gnat xref -Padacl.gpr" と + 試してみるのもいけない。 5) タグファイルがソートされているとVimは高速に検索できるので、"sort --unique --ignore-case --output=tags tags" とすること。 6) タグファイルがソートされていることを示すために、1行目に "!_TAG_FILE_SORTED @@ -496,7 +496,8 @@ matchit.vim taglist.vim http://www.vim.org/scripts/script.php?script_id=273 - ソースコードエクスプローラサイドバー。Adaで利用可能にするパッチがある。 + ソースコードエクスプローラーサイドバー。Adaで利用可能にするパッチがあ + る。 GNU Adaプロジェクトが配布するVimは以上を全て含んでいる。 diff --git a/doc/ft_sql.jax b/doc/ft_sql.jax index 6698f6757..369d3bff0 100644 --- a/doc/ft_sql.jax +++ b/doc/ft_sql.jax @@ -101,12 +101,12 @@ SQL ファイルを編集するとき、以下のノーマルモード|Normal| 1.3 SQL 独自のオブジェクト単位移動 *sql-predefined-objects* ----------------------------- ほとんどのリレーショナルデータベースはテーブル、インデックス、トリガー、ストア -ドプロシージャなど様々な標準的な機能を備えています。また、ベンダごとに様々な独 -自オブジェクトがあります。次のマップたちはこれらのオブジェクト間を移動するため -に作られています。お使いのデータベースによってオブジェクトのリストを調整できる -ようでなればなりません。このファイルタイププラグインは標準オブジェクトのほとん -どと、多くの追加的なオブジェクトを定義しています。これを可能な限りフレキシブル -にするために、|vimrc| でオブジェクトのリストを上書きできるようになっています。 +ドプロシージャなど様々な標準的な機能を備えています。また、ベンダーごとに様々な +独自オブジェクトがあります。次のマップたちはこれらのオブジェクト間を移動するた +めに作られています。お使いのデータベースによってオブジェクトのリストを調整でき +るようでなればなりません。このファイルタイププラグインは標準オブジェクトのほと +んどと、多くの追加的なオブジェクトを定義しています。これを可能な限りフレキシブ +ルにするために、|vimrc| でオブジェクトのリストを上書きできるようになっています。 次のようにします: > let g:ftplugin_sql_objects = 'function,procedure,event,table,trigger' . \ ',schema,service,publication,database,datatype,domain' . @@ -213,25 +213,25 @@ Vim の機能に対応しています: > 定値の指定、プロシージャ言語(ストアドプロシージャとトリガー)を備えています。 標準の Vim ディストリビューションには Oracle の PL/SQL に基づいた構文ハイライ -トが付属しています。SQL インデントスクリプトは Oracle と SQL Anywhere -用に動作します。ファイルタイププラグインはすべてのベンダ用に動作し、ベンダ中立 -を保ちつつも拡張可能であるべきです。 +トが付属しています。SQL インデントスクリプトは Oracle と SQL Anywhere 用に動作 +します。ファイルタイププラグインはすべてのベンダー用に動作し、ベンダー中立を保 +ちつつも拡張可能であるべきです。 -現在様々なベンダに対応しています。これは構文スクリプトを通して実現しています。 +現在様々なベンダーに対応しています。これは構文スクリプトを通して実現しています。 残念なことに、複数の構文ルールを切り替えるには以下のどれかを作成しなければなり ません: 1. 新しいファイルタイプ 2. 独自のオートコマンド 3. コマンド手動実行 -大多数の人は1つのベンダのデータベース製品しか扱わないため、|vimrc| で既定値を -設定しておくとよいでしょう。 +大多数の人は1つのベンダーのデータベース製品しか扱わないため、|vimrc| で既定値 +を設定しておくとよいでしょう。 2.1 SQLSetType *sqlsettype* *SQLSetType* -------------- 複数のデータベースを扱っている人々にとっては、バッファごとまたは任意のタイミン -グでベンダのルール(インデント、構文)を切り替えられるとよいでしょう。 +グでベンダーのルール(インデント、構文)を切り替えられるとよいでしょう。 ftplugin/sql.vim では次のコマンドが定義されています: > SQLSetType @@ -541,13 +541,13 @@ SQL 文を動的に組み立てる方法を見ていきましょう。select 文 < 1. SELECT と入力してから t を押すとテーブルのリストが表示されます。 2. カラムリストを表示したいテーブルにカーソルを合わせます。 3. を押してテーブルを選択します。 - 4. l を押してそのテーブル内の全カラムのカンマ区切りのリストを表示 + 4. l を押してそのテーブル内の全カラムのコンマ区切りのリストを表示 させます。 5. ステップ 3 で選んだテーブル名に基づいてプラグインは妥当なテーブルエ イリアスを決定します。ここでそのエイリアスを受け入れるかどうかプロ ンプトが表示されます。OK を押してください。 6. するとテーブル名が消え、代わりにそのテーブルのカラムリスト(各カラム - 名の前にエイリアスがつき、カンマ区切りになったもの)が挿入されます。 + 名の前にエイリアスがつき、コンマ区切りになったもの)が挿入されます。 7. L を押すとステップ 3 と 4 を同時に実行できます。これは、リス トの中で現在選ばれているテーブルで決定するためにマップの中に を埋め込んでいます。 @@ -593,7 +593,7 @@ select 文を書くための特別な機能があります。 次の文を書く > omni_sql_use_tbl_alias < - 既定値: a - - この設定はカンマ区切りのカラムリストを生成するときに参照されます。 + - この設定はコンマ区切りのカラムリストを生成するときに参照されます。 既定ではカラムリストを生成するマップは l です。カラムリストを 生成するときに各カラムの前にエイリアスがつきます。例えば: e.emp_id, e.emp_name。このオプションには 3 種類の値を設定できます: > @@ -673,9 +673,9 @@ dynamic モードのマップ c < - 指定テーブルのカラムのリストを表示します。 > l -< - 指定テーブルのカラムのリストをカンマ区切りで表示します。 > +< - 指定テーブルのカラムのリストをコンマ区切りで表示します。 > L -< - 指定テーブルのカラムのリストをカンマ区切りで表示します。 +< - 指定テーブルのカラムのリストをコンマ区切りで表示します。 補完ウィンドウがアクティブなときだけ使用できます。 > < - 現在補完リストでカーソルが指しているテーブルのカラムリストを表示しま diff --git a/doc/gui.jax b/doc/gui.jax index 2a5583fab..d704d9701 100644 --- a/doc/gui.jax +++ b/doc/gui.jax @@ -1,10 +1,10 @@ -*gui.txt* For Vim バージョン 7.4. Last change: 2011 Jul 22 +*gui.txt* For Vim バージョン 7.4. Last change: 2014 Mar 08 VIMリファレンスマニュアル by Bram Moolenaar -Vimのグラフィカルユーザーインタフェース *gui* *GUI* +Vimのグラフィカルユーザーインターフェイス *gui* *GUI* 1. GUIの開始 |gui-start| 2. スクロールバー |gui-scrollbars| @@ -92,10 +92,14 @@ GUIウィンドウを開いた直後にいくつかのコマンドを実行し 初期化をするために、gvimrcファイルを使用することができる。 ユーザーの個人的なGUI初期化ファイルを置くのに推奨される場所: - Unix $HOME/.gvimrc - OS/2 $HOME/.gvimrcあるいは$VIM/.gvimrc - MS-DOSとWin32 $HOME/_gvimrcあるいは$VIM/_gvimrc - Amiga s:.gvimrcあるいは$VIM/.gvimrc + Unix $HOME/.gvimrc、$HOME/.vim/gvimrc + OS/2 $HOME/.gvimrc、$HOME/vimfiles/gvimrc、$VIM/.gvimrc + MS-DOSとWin32 $HOME/_gvimrc、$HOME/vimfiles/gvimrc、$VIM/_gvimrc + Amiga s:.gvimrc、home:.gvimrc、home:vimfiles:gvimrc、 + $VIM/.gvimrc + +個人的な初期化ファイルは上記の順に検索され、最初に見つかったものだけが読み込ま +れる。 GUI版のVimでだけ意味を持つオプションがある。'guicursor'、'guifont'、'guipty'、 'guioptions' である。それらは他の全てのオプションと共に|options.txt|で説明され @@ -126,6 +130,7 @@ Vimは起動時に、スクリーンに合わせてウィンドウの位置を :winp[os] GUI vimウィンドウの左上隅の現在の位置をピクセルで表示する。全 てのバージョンで機能する訳ではない。 + |getwinposx()| と |getwinposy()| も参照のこと。 :winp[os] {X} {Y} *E466* 与えられた{X}と{Y}の座標にGUI vimウィンドウを移動する。座標は @@ -139,13 +144,16 @@ Vimは起動時に、スクリーンに合わせてウィンドウの位置を *:win* *:winsize* *E465* :win[size] {width} {height} {width}(幅)と{height}(高さ)を指定してウィンドウの大きさを設定 - する。このコマンドは古いコマンド(Obsolate)なので、 + する。このコマンドは古いコマンド(Obsolete)なので、 ":set lines=11 columns=22" を使用するようにすること。 期待したよりも高さが低くなるなら、'guiheadroom' オプションを確 認すること。 -X Window Systemでは、このコマンドでVimのウィンドウの情報を得ることができる: > +X Window Systemでは、これらのコマンドでVimのウィンドウの情報を得られる: > :!xwininfo -id $WINDOWID + :!xprop -id $WINDOWID + :execute '!xwininfo -id ' . v:windowid + :execute '!xprop -id ' . v:windowid < *gui-IME* *iBus* X で各国の文字を入力するためのインプットメソッドで XIM フレームワークに依るも @@ -443,9 +451,9 @@ X11でこのレジスタを使うには、|x11-selection|も参照。これは スタについても説明している。 あるVimから他の独立したVimにテキストを貼り付けたいときには、選択のタイプ(文 -字、行あるいはブロック)もコピーされることに注意する。他のアプリケーションにつ -いては、タイプは常に文字である。|x11-cut-buffer|を介して得たテキストでも、その -選択のタイプは常に失われる。 +字、行あるいは矩形)もコピーされることに注意する。他のアプリケーションについて +は、タイプは常に文字である。|x11-cut-buffer|を介して得たテキストでも、その選択 +のタイプは常に失われる。 'clipboard' オプションに "unnamed" 文字列が含まれているときには、無名レジスタ は "* レジスタと同じである。したがってコマンドの前に "* を付けずに選択をコピー @@ -567,7 +575,7 @@ Win32 GUIバージョンはMotifの切取りメニューをエミュレートす ビジュアルモード 挿入モード コマンドラインモード - 演算子未解決モード + オペレータ待機モード 後ろに付加されるCTRL-\ CTRL-Gは 'insertmode' が設定されているときには挿入モー ドに戻る。|CTRL-\_CTRL-G|を参照。 @@ -651,7 +659,7 @@ Note: コマンドラインモードでのはマッピングで使用され メニューの「Help」の項目は、それをサポートしているシステム(MotifとGTK+)では、 メニューバーの右端に寄せて置かれる。GTK+ 2では、メニューのHelpを右端に寄せるの -は今のところユーザーインターフェースデザインの妨げになっているので、もはやサ +は今のところユーザーインターフェイスデザインの妨げになっているので、もはやサ ポートされない。 ヘルプメニューの後ろに置くために、9999より高い優先度を使用することができるが、 @@ -673,7 +681,7 @@ Note: コマンドラインモードでのはマッピングで使用され メニューの優先度はメニューを新しく生成するときだけ用いられる。すでにあるとき、 例えば、別のモードで定義されていたときには、優先度は変更されない。したがって、 優先度はメニューを最初に定義するときだけ与える必要がある。 -例外はポップアップメニューである。各モード(ノーマルモード、演算子未解決モー +例外はポップアップメニューである。各モード(ノーマルモード、オペレータ待機モー ド、ビジュアルモード、挿入モード、コマンドラインモード)に別々のメニューがあ る。これらのメニューは順序が異なってもよい。これはメニューバーのメニューとは異 なる。メニューバーのメニューは全てのモードで同じ順序である。 diff --git a/doc/gui_w16.jax b/doc/gui_w16.jax index ad894cb4b..5bfedf537 100644 --- a/doc/gui_w16.jax +++ b/doc/gui_w16.jax @@ -4,7 +4,7 @@ VIMリファレンスマニュアル by Bram Moolenaar -Vimのグラフィカルユーザーインターフェース *gui-w16* *win16-gui* +Vimのグラフィカルユーザーインターフェイス *gui-w16* *win16-gui* 1. GUIを始める |win16-start| 2. デフォルトエディタVim |win16-default-editor| @@ -31,7 +31,7 @@ Win16バージョンのVimはWindows 3.1以降で動作する。3.0ではテス 1) 再描画を高速化しリソース使用量を減らすために、太字と斜体のテキストは利用で きない。(MSWIN16_FASTTEXTを定義しないでコンパイルすれば利用可能) 2) メニューの切り取りはエミュレーションしていない。 -3) OLEインターフェースが無い。 +3) OLEインターフェイスが無い。 4) (あたり前だが)長いファイル名には対応しない。 5) ツールバーのボタンにツールチップが無い - その代わりにメニューの項目が行うよ うにコマンドラインへ表示する。 @@ -125,7 +125,7 @@ Gray, Grey, LightYellow, SeaGreen, Orange, Purple, SlateBlue, Violet, *win16-dialogs* 6. ダイアログとブラウズ -コンソールバージョンから受け継がれる伝統的なインターフェースはもちろん、さらに +コンソールバージョンから受け継がれる伝統的なインターフェイスはもちろん、さらに Win16 GUIでは幾つかの操作に見慣れたWindowsのコンポーネントを使用することができ る。 diff --git a/doc/gui_w32.jax b/doc/gui_w32.jax index e7169e07d..9f8dd6ad6 100644 --- a/doc/gui_w32.jax +++ b/doc/gui_w32.jax @@ -1,10 +1,10 @@ -*gui_w32.txt* For Vim バージョン 7.4. Last change: 2011 Jul 23 +*gui_w32.txt* For Vim バージョン 7.4. Last change: 2014 Dec 20 VIMリファレンスマニュアル by Bram Moolenaar -Win32でのVimのグラフィカルユーザーインターフェース *gui-w32* *win32-gui* +Win32でのVimのグラフィカルユーザーインターフェイス *gui-w32* *win32-gui* 1. GUIを始める |gui-w32-start| 2. デフォルトエディタVim |vim-default-editor| @@ -66,7 +66,7 @@ Vim をプラグインとして使う *gui-w32-windowid* 2. デフォルトエディタVim *vim-default-editor* Vimをあるファイルタイプのデフォルトエディタにするには: -1. Windowsのエクスプローラを起動する +1. Windowsのエクスプローラーを起動する 2. ツール/フォルダオプション -> ファイルタイプ (W2K + IE5.5) 3. Vimを使用したい全てのファイルタイプに対して、gvimのパスを設定する。(拡張子 の無いファイルタイプに対しては、ファイルタイプを指定するフィールドに3つのス @@ -97,7 +97,7 @@ Vimを全画面で起動したい時には、openのアクションとして次 *send-to-menu* *sendto* Vimを "送る" メニューに追加することもできる: -1. Windowsのエクスプローラを起動する。 +1. Windowsのエクスプローラーを起動する。 2. "送る" のためのディレクトリに移動する: Windows 95: %windir%\sendto (e.g. "c:\windows\sendto") Windows NT: %windir%\profiles\%user%\sendto (e.g. @@ -175,24 +175,24 @@ HKLM\Software\Vim\Gvim に DisableEditWithExisting という名前のエント "アプリケーションの追加と削除" のリストの、エントリを使うことも出来る。 このエントリがファイルタイプの関連付けを抑制してしまうことに気が付いたら、手動 -で関連付けをやり直す(上記を参考に、Windowsのエクスプローラを使って)。これは +で関連付けをやり直す(上記を参考に、Windowsのエクスプローラーを使って)。これは Windows NTの幾つかのバージョンでだけ起こるらしい(Windowsのバグ?)。手続き: 1. ファイルタイプの名前を見つける。これはレジストリエディタを起動し、 \\HKEY_CLASSES_ROOTで拡張子を探すことで行える。 -2. Windowsエクスプローラでは、表示→オプション→ファイルタイプ。リストの中から - ファイルタイプを探し出し "編集" をクリック。アクションのリストで、デフォル - トとして使用したいものを選択し(通常は "開く" アクション)、"標準" ボタンをク - リックする。 +2. Windowsエクスプローラーでは、表示→オプション→ファイルタイプ。リストの中か + らファイルタイプを探し出し "編集" をクリック。アクションのリストで、デフォ + ルトとして使用したいものを選択し(通常は "開く" アクション)、"標準" ボタンを + クリックする。 "アプリケーションから開く" コンテキストメニュー *win32-open-with-menu* ("Open With...") -Vimのインストーラを使うならエクスプローラのメニューの "アプリケーションから開 -く" にVimを加えるか選択することができる。これはVimでいろんなファイルを編集する -なら重要である。(不明瞭な理由で)全てのファイルには使えない。したがって "Edit +Vimのインストーラを使うならエクスプローラーのメニューの "アプリケーションから +開く" にVimを加えるか選択することができる。これはVimでいろんなファイルを編集す +るなら重要である。(不明瞭な理由で)全てのファイルには使えない。したがって "Edit with Vim" メニューの方が使いやすい。 -これを追加する理由の一つがインターネットエクスプローラから直接ファイルを編集 +これを追加する理由の一つがインターネットエクスプローラーから直接ファイルを編集 できるようにするためである。これを有効にするには "Tools" メニューから "Internet Options..." を選択し、出てきたダイアログウィンドウの "Programs" タ ブの "HTML editor" にVimを選択する。そこにVimがなければインストールは完了し @@ -290,7 +290,7 @@ Windows 95では、実行されるコマンドのウィンドウは、DOSとの もしも外部プログラムを使用したときに、"このプログラムはMS-DOSモードで起動しま す…" のようなダイアログが表示されたならば、関連付けられたショートカットのプロ パティを変更することでこれを解消することができる: -- Windowsエクスプローラを使用して使用されたcommand.comを探す。恐らく +- Windowsエクスプローラーを使用して使用されたcommand.comを探す。恐らく c:\command.com、c:\dos\command.com、c:\windows\command.comなどのどれか。 - マウスの右ボタンで、command.comのプロパティを選択。 - プログラムタブの "詳細設定" を選択。 @@ -359,7 +359,7 @@ $VIMRUNTIMEディレクトリに置く。だから "$VIMRUNTIME/rgb.txt" にフ ============================================================================== 6. ダイアログとブラウズ *gui-w32-dialogs* *dialog* -コンソールバージョンから受け継がれる伝統的なインターフェースはもちろん、さらに +コンソールバージョンから受け継がれる伝統的なインターフェイスはもちろん、さらに Win32 GUIでは幾つかの操作に見慣れたWindowsのコンポーネントを使用することができ る。 @@ -456,9 +456,10 @@ Vimでは多くのMS Windows標準の機能をサポートしている。それ Vimのウィンドウに1つもしくは複数のファイルをドラッグ&ドロップすることができ、 それらは普通に開かれる。|drag-n-drop|を参照。 - *:simalt* *:si* -:si[malt] {key} Alt と {key} の同時押しをシミュレートする。 + *:simalt* *:sim* +:sim[alt] {key} Alt と {key} の同時押しをシミュレートする。 {Vi にはない} {Win32バージョンだけの機能} + Note: ":si" は "i" フラグ付きの ":s" になる。 通常、Vimでは使用可能なマッピングを増やすために、Alt-の全ての組み合わせを 使うことができる。これはメニューにアクセスするためのAltキーの標準的な使い方と diff --git a/doc/gui_x11.jax b/doc/gui_x11.jax index 323d3554c..b852fefe3 100644 --- a/doc/gui_x11.jax +++ b/doc/gui_x11.jax @@ -1,10 +1,10 @@ -*gui_x11.txt* For Vim バージョン 7.4. Last change: 2011 Sep 14 +*gui_x11.txt* For Vim バージョン 7.4. Last change: 2014 Mar 08 VIMリファレンスマニュアル by Bram Moolenaar -Vimのグラフィカルユーザーインタフェース *gui-x11* *GUI-X11* +Vimのグラフィカルユーザーインターフェイス *gui-x11* *GUI-X11* *Athena* *Motif* 1. X11 GUIの開始 |gui-x11-start| 2. GUIリソース |gui-resources| @@ -261,18 +261,19 @@ geometry引数の例: > MotifあるいはAthenaでコンパイルされたときには、Vimはデフォルトで白黒のアイコン を用いる。色付きのVimアイコンは$VIMRUNTIME/vim32x32.xpmとして含まれる。GTK+に ついては、組み込みのアイコンが用いられる。不幸にも、どのようにしてそれをインス -トールするかはあなたのウィンドウマネージャに依存する。これを使用するときには、 -白黒のアイコンを取り除くために、'guioptions' から 'i' フラグを取り除くとよい: > +トールするかは、あなたのウィンドウマネージャーに依存する。これを使用するときに +は、白黒のアイコンを取り除くために、'guioptions' から 'i' フラグを取り除くとよ +い: > :set guioptions-=i -fvwm*ファミリのウィンドウマネージャの1つを使用するならば、単にあなたの.fvwm2rc -構成ファイルにこの行を追加するとよい: > +fvwm*ファミリのウィンドウマネージャーの 1 つを使用するならば、単にあなたの +.fvwm2rc 構成ファイルにこの行を追加するとよい: > Style "vim" Icon vim32x32.xpm -アイコンファイルの場所がウィンドウマネージャのImagePath文と一致することを確か -めなくてはならない。あなたの.fvwm2rcを修正するか、あるいは事前に定義されたディ -レクトリの1つにアイコンをドロップするとよい。 > +アイコンファイルの場所がウィンドウマネージャーのImagePath文と一致することを確 +かめなくてはならない。あなたの.fvwm2rcを修正するか、あるいは事前に定義された +ディレクトリの1つにアイコンをドロップするとよい。 > ImagePath /usr/X11R6/include/X11/pixmaps:/usr/X11R6/include/X11/bitmaps @@ -281,7 +282,7 @@ Note: 古いバージョンのfvwmでは "ImagePath" ではなく "IconPath" を CDE "dtwm" (Motifから派生)については、.Xdefaultsにこの行を追加するとよい: > Dtwm*Vim*iconImage: /usr/local/share/vim/vim32x32.xpm -"mwm" (Motifウィンドウマネージャ)については、その行はこうなるだろう: > +"mwm" (Motifウィンドウマネージャー)については、その行はこうなるだろう: > Mwm*Vim*iconImage: /usr/local/share/vim/vim32x32.xpm X11で利用できるマウスポインタ *X11_mouse_shapes* @@ -314,7 +315,7 @@ X11に組み込まれたポインタを使うことができる。 GUIのGTKバージョンはほんの少し異なった動作をする。 -GTKは従来のXのリソース設定に使＿わない＿。したがって、~/.Xdefaultsや +GTKは従来のXのリソース設定を使＿わない＿。したがって、~/.Xdefaultsや app-defaultsは使われない。 伝統的なXコマンドの引数はサポートされない。(例えば -bg, -fg, などの要素)。サ ポートされているのは: @@ -383,7 +384,7 @@ Vimのコマンドラインオプションに '--socketid' と10進数や16進 Vimは通常のGtkWindowを使わず、指定された値を使いGtkPlugウィジェットを作成す る。これはVimがGTK+プラグインとして振る舞うことを可能にする。 -これはプログラマ向けのインターフェースであり、それをサポートするアプリケーショ +これはプログラマ向けのインターフェイスであり、それをサポートするアプリケーショ ン無しではまったく役に立たない。GTK+ソケットについての詳細は次のURLを参考にす ること。 http://www.gtk.org/api/ @@ -396,7 +397,7 @@ Note この機能は最新バージョンのGTKを必要とする。GTK 1.2.10 GNOME GUI は GTK+ バージョンと同じように機能する。どのように動作するかは上述 の |GTK+| を参照。しかし若干の違いがあり、素の GTK+ GUI では利用できない重要 -な機能が 1 つ実装されている。それはセッションマネージャとの相互作用である。 +な機能が 1 つ実装されている。それはセッションマネージャーとの相互作用である。 |gui-gnome-session| 見た目の違い: @@ -419,8 +420,8 @@ GNOME セッションサポート *gui-gnome-session* *gnome-session* そうしなかった場合は、現在のセッションが |:mksession| コマンドを使ってディス クに保存され、次回のログオン時に復元される。 -GNOME セッションサポートはおそらく KDE セッションマネージャでも機能する。も -しあなたが何かの問題に直面したらバグレポートを彼らに送っていただきたい。 +GNOME セッションサポートはおそらく KDE セッションマネージャーでも機能する。 +もしあなたが何かの問題に直面したらバグレポートを彼らに送っていただきたい。 Note: 自動的なセッションの保存はあなたのセッションファイルやスクリプト、オー トコマンドの衝突を避けるために実に適切に働く。その手段としては: @@ -431,7 +432,7 @@ Note: 自動的なセッションの保存はあなたのセッションファ - 内部変数の |v:this_session| はセッションの保存で変更されない。さらに、再び ログインしたときに元の値に復元される。 -GUI ウィンドウの位置とサイズは保存されない、それはウィンドウマネージャの仕事 +GUI ウィンドウの位置とサイズは保存されない、それはウィンドウマネージャーの仕事 である。しかし、GTK+ 2 サポートを有効にしてコンパイルされていると、Vim はウィ ンドウの役目を復元して WM がウィンドウを識別するのを補佐する (コマンドライン引 数の|--role| を使う)。 @@ -442,7 +443,7 @@ GUI ウィンドウの位置とサイズは保存されない、それはウィ KDE バージョンの Vim は存在しない。Qt ツールキットを使って移植する作業が行われ ていたが、ちゃんと動かなかったので、今は放棄されている。作業は Yzis で継続され -ている: www.yzis.org +ている: https://github.com/chrizel/Yzis ============================================================================== 8. コンパイル *gui-x11-compiling* @@ -487,11 +488,11 @@ Motif 2.0とX11R6はOKである。Motif 1.1とX11R4は動作するかもしれ LessTifの最新リリースも問題なく動作すると報告を受けている。 *gui-x11-athena* -AthenaバージョンはデフォルトでXaw ウィジットセットを用いる。3Dバージョンを持っ -ているならば、代わりにXaw3dでリンクしたいかもしれない。これはメニューを少しよ -く見せるかもしれない。Makefileを編集して、"XAW_LIB" を見に行くようにするとよ -い。スクロールバーは、Vimは既に3Dのそれ自体を持っているので(実際には、それらは -もっとMotifのように見える)、同じままだろう。 +AthenaバージョンはデフォルトでXaw ウィジェットセットを用いる。3Dバージョンを +持っているならば、代わりにXaw3dでリンクしたいかもしれない。これはメニューを少 +しよく見せるかもしれない。Makefileを編集して、"XAW_LIB" を見に行くようにすると +よい。スクロールバーは、Vimは既に3Dのそれ自体を持っているので(実際には、それら +はもっとMotifのように見える)、同じままだろう。 *gui-x11-neXtaw* neXtawバージョンについては、異なるウィジェットを使うだけでほとんどAthenaと変わ @@ -562,8 +563,8 @@ Vim のものであるときに、それが書き込まれる。 む。 Note これによってテキストが CUT_BUFFER0 にコピーされるときは、セレクションの -型情報 (文字、行、ブロック) は常に失われる。後にそれをペーストするのが Vim -であっても。 +型情報 (文字、行、矩形) は常に失われる。後にそれをペーストするのが Vim であっ +ても。 通常、Xterm は、選択したものをプライマリと CUT_BUFFER0 の両方に書き込む。 ペースト時には、利用可能であればプライマリが使われ、それができなければ diff --git a/doc/hangulin.jax b/doc/hangulin.jax index 39580447b..f6934cdf3 100644 --- a/doc/hangulin.jax +++ b/doc/hangulin.jax @@ -1,10 +1,7 @@ -*hangulin.txt* For Vim バージョン 7.4. Last change: 2009 Jun 24 +*hangulin.txt* For Vim バージョン 7.4. Last change: 2015 Nov 24 - VIMリファレンスマニュアル by Chi-Deok Hwang and Sung-Hyun Nam - -NOTE: |+hangul_input| 機能は削除されることが予定されています。これの存続を望む -方は Vim ユーザーメーリングリストにメッセージを送ってください。 + VIMリファレンスマニュアル by Chi-Deok Hwang and Sung-Hyun Nam イントロダクション *hangul* @@ -18,7 +15,8 @@ NOTE: |+hangul_input| 機能は削除されることが予定されています 次のオプションは最低限の指定であり、他の configure オプションを追加することも できます。 > - ./configure -with-x --enable-multibyte --enable-fontset --enable-hangulinput + ./configure --with-x --enable-multibyte --enable-hangulinput \ + --disable-xim そして、|+hangul_input| 機能が configure によって有効になっているかどうか、 feature.h をチェックすべきです。そして、他のオプションも選択することができます。 @@ -28,18 +26,21 @@ feature.h をチェックすべきです。そして、他のオプションも #define HANGUL_DEFAULT_KEYBOARD 2 #define ESC_CHG_TO_ENG_MODE /* #define X_LOCALE */ - /* #define SLOW_XSERVER */ 環境変数 -------- -LANG 変数を、ko や ko_KR.euc のような韓国語ロケールに指定する必要があります。 +LANG 変数を、ko, ko_KR.euckR および ko_KR.UTF-8 のような韓国語ロケールに指定す +る必要があります。 LC_ALL 変数をセットしている場合は、それも韓国語ロケールである必要があります。 VIM リソース ------------ -次の行を vimrc ($HOME/.vimrc) に加えてください。 > +'encoding' と 'fileencodings' をセットしたいかもしれません。 +例: > - :set fileencoding=korea + :set encoding=euc-kr + :set encoding=utf-8 + :set fileencodings=ucs-bom,utf-8,cp949,euc-kr,latin1 キーボード ---------- @@ -55,9 +56,18 @@ VIM_KEYBOARD か HANGUL_KEYBOARD_TYPE 環境変数を使うことによって、 ハングル・フォント ------------------ -$HOME/.Xdefaults か、ユーザーの .gvimrc でテキストのフォントを設定することがで -きます。しかし、ハングルを使うには、vimrc で 'guifontset' を設定する必要があり -ます。 +GTK バージョンの GVIM を使用している場合は 'guifont' と 'guifontwide' をセット +するべきです。 +例: > + set guifont=Courier\ 12 + set guifontwide=NanumGothicCoding\ 12 + +Motif もしくは Athena バージョンの GVIM を使用している場合は vimrc 内で +'guifontset' をセットするべきです。フォントセットは .Xdefaults ファイル内で指定 +できます。 + +$HOME/.gvimrc: > + set guifontset=english_font,hangul_font $HOME/.Xdefaults: > Vim.font: english_font @@ -70,18 +80,16 @@ $HOME/.Xdefaults: > *international: True Vim*fontList: english_font;hangul_font: -$HOME/.gvimrc: > - set guifontset=english_font,hangul_font - 注意! , (コンマ) か ; (セミコロン)です。 そして ':set guifont' が設定されていてはいけません。もし設定されていると GVim -は ':set guifontset' を無視します。つまり、Vim がフォント・セットのサポートな -しで動作することになり、英語の文字だけが見えることになり、ハングルは正しくは表 -示されなくなります。 +は ':set guifontset' を無視します。つまり、Vim がフォントセットのサポートなし +で動作することになり、英語の文字だけが見えることになり、ハングルは正しくは表示 +されなくなります。 -'fontset' 機能が有効にされた後では、Vim では 'font' は使えなくなります。例えば、 -もし .gvimrc で次のようにしている場合は: > +'fontset' 機能が有効になった後、シンタックス定義での 'font' 設定でのみ英語のフ +ォントを使うことはできなくなります。 +例えば、もし .gvimrc で次のようにしている場合は: > :set guifontset=eng_font,your_font 構文ハイライトの指定では次のようにする必要があります: > :hi Comment guifg=Cyan font=another_eng_font,another_your_font @@ -93,17 +101,18 @@ $HOME/.gvimrc: > サポートされていない機能 ------------------------ -Johab フォントはサポートされていませんし、予定もありません。どうしても johab -フォントが使いたい場合は、gau パッケージの hanguldraw.c を使うことができます。 +Johab フォントはサポートしていません。 +Hanja フォントはサポートしていません。 +それらをサポートする予定は一切ありません。 -Hanja 入力はまだサポートされていませんし、予定もありません。どうしても Hanja -を入力したい場合は、hanterm で Vim を使ってください。 +もしも本当にそれらの機能が必要ならば、それらをサポートした端末エミュレータ上で +コンソールバージョンのVimを使ってください。 バグ・コメント -------------- コメント、パッチ、提案などはこちらに: - Chi-Deok Hwang SungHyun Nam + Chi-Deok Hwang <...> vim:tw=78:ts=8:ft=help:norl: diff --git a/doc/help.jax b/doc/help.jax index 3343ca72d..474902d90 100644 --- a/doc/help.jax +++ b/doc/help.jax @@ -1,4 +1,4 @@ -*help.txt* For Vim バージョン 7.4. Last change: 2012 Dec 06 +*help.txt* For Vim バージョン 7.4. Last change: 2016 Jan 10 VIM - メインヘルプファイル k @@ -11,19 +11,23 @@ マウスでジャンプ: ":set mouse=a" と入力してマウスを有効にしてください (xterm or GUI で利用可)。タグ (例: |bars|) をマウスの左ボ タンでダブルクリックすると、項目にジャンプできます。 - 元の場所に戻る: CTRL-T or CTRL-O を押す。 + 元の場所に戻る: CTRL-T or CTRL-O を押す。繰り返すと更に戻れます。 項目を指定する: |:help| コマンドに項目を指定することで、その項目を直ちに - 表示できます。調べたい項目の種類を指定することもできます。 - *help-context* + 表示できます。修飾子を先行入力することで、調べたい項目の種 + 類を指定することもできます: *help-context* + 種類 修飾子 例 ~ - ノーマルモードコマンド (無し) :help x + ノーマルモードコマンド :help x ビジュアルモードコマンド v_ :help v_u 挿入モードコマンド i_ :help i_ コマンドラインコマンド : :help :quit コマンドライン編集 c_ :help c_ Vim の起動引数 - :help -r オプション ' :help 'textwidth' + 正規表現 / :help /[ + その他の種類については |help-summary| を参照してください。 + ヘルプを検索する: ":help word" とタイプしてから CTRL-D を押すと "word" に マッチするヘルプ項目の一覧が表示されます。 もしくは ":helpgrep word" を使ってください。 |:helpgrep| @@ -89,7 +93,7 @@ VIM は Vi IMproved の略です。VIM の大部分は Bram Moolenaar によっ リファレンスマニュアルでは Vim の詳細を説明します。 *reference_toc* 一般事項 ~ -|intro.txt| Vimについての前書き。と、ヘルプの表記について +|intro.txt| Vimについての前書き、ヘルプの表記について |help.txt| 全体説明とクイックリファレンス (今見ているファイル) |helphelp.txt| ヘルプの使い方 |index.txt| 全コマンド一覧。アルファベット順 @@ -104,7 +108,7 @@ VIM は Vi IMproved の略です。VIM の大部分は Bram Moolenaar によっ |uganda.txt| Vimの配布条件と、あなたが支払ったお金の使い道について 基本的な編集 ~ -|starting.txt| Vimの起動。起動引数や初期化に関して +|starting.txt| Vimの起動、起動引数や初期化に関して |editing.txt| ファイルの編集と保存 |motion.txt| 移動コマンド |scroll.txt| ウィンドウのスクロール @@ -128,10 +132,10 @@ VIM は Vi IMproved の略です。VIM の大部分は Bram Moolenaar によっ |tabpage.txt| タブページを操作するコマンド |syntax.txt| 構文強調 |spell.txt| スペルチェック -|diff.txt| バージョン違いのファイルの編集。差分モード +|diff.txt| バージョン違いのファイルの編集 (差分モード) |autocmd.txt| イベントに応じて自動的にコマンドを実行する |filetype.txt| ファイルタイプ別の設定 -|eval.txt| 式の評価。条件式。 (Vim スクリプトリファレンス) +|eval.txt| 式の評価、条件式 (Vim スクリプトリファレンス) |fold.txt| ある範囲を隠す (折り畳む) 特定機能 ~ @@ -151,24 +155,24 @@ VIM は Vi IMproved の略です。VIM の大部分は Bram Moolenaar によっ |rileft.txt| 右横書き (書字方向が右から左になるモード) GUI ~ -|gui.txt| グラフィカルユーザーインターフェース (GUI) +|gui.txt| グラフィカルユーザーインターフェイス (GUI) |gui_w16.txt| Windows 3.1 GUI |gui_w32.txt| Win32 GUI |gui_x11.txt| X11 GUI -拡張インターフェース ~ +拡張インターフェイス ~ |if_cscop.txt| cscopeを使う -|if_lua.txt| Lua インターフェース -|if_mzsch.txt| MzScheme インターフェース -|if_perl.txt| Perl インターフェース -|if_pyth.txt| Python インターフェース -|if_sniff.txt| SNiFF+ インターフェース -|if_tcl.txt| Tcl インターフェース +|if_lua.txt| Lua インターフェイス +|if_mzsch.txt| MzScheme インターフェイス +|if_perl.txt| Perl インターフェイス +|if_pyth.txt| Python インターフェイス +|if_sniff.txt| SNiFF+ インターフェイス +|if_tcl.txt| Tcl インターフェイス |if_ole.txt| Win32のOLEオートメーション -|if_ruby.txt| Ruby インターフェース -|debugger.txt| デバッガ用のインターフェース -|workshop.txt| Sun Visual Workshop インターフェース -|netbeans.txt| NetBeans External Editor インターフェース +|if_ruby.txt| Ruby インターフェイス +|debugger.txt| デバッガ用のインターフェイス +|workshop.txt| Sun Visual Workshop インターフェイス +|netbeans.txt| NetBeans External Editor インターフェイス |sign.txt| デバッグ用の目印 バージョン情報 ~ @@ -196,11 +200,12 @@ GUI ~ 標準プラグイン ~ |pi_getscript.txt| Vim スクリプトの最新版をダウンロードする |pi_gzip.txt| 圧縮ファイルの読み書き +|pi_logipat.txt| パターンにおける論理演算子 |pi_netrw.txt| ネットワークファイルの読み書き |pi_paren.txt| 対括弧の強調表示 -|pi_tar.txt| Tar ファイルエクスプローラ +|pi_tar.txt| Tar ファイルエクスプローラー |pi_vimball.txt| Vim スクリプトインストーラを作成する -|pi_zip.txt| Zip アーカイブエクスプローラ +|pi_zip.txt| Zip アーカイブエクスプローラー その他 ~ |vim_faq.txt| FAQ diff --git a/doc/helphelp.jax b/doc/helphelp.jax index 9e3ff9733..9a9ea3d17 100644 --- a/doc/helphelp.jax +++ b/doc/helphelp.jax @@ -1,4 +1,4 @@ -*helphelp.txt* For Vim バージョン 7.4. Last change: 2012 Nov 28 +*helphelp.txt* For Vim バージョン 7.4. Last change: 2014 Sep 19 VIMリファレンスマニュアル by Bram Moolenaar @@ -95,6 +95,9 @@ るときには、それと同じ言語を優先します。 |help-translated|も参照。 + *:helpc* *:helpclose* +:helpc[lose] ヘルプウィンドウがあれば、1つ閉じます。 + *:helpg* *:helpgrep* :helpg[rep] {pattern}[@xx] すべてのヘルプファイルから {pattern} を検索して、マッ diff --git a/doc/howto.jax b/doc/howto.jax index 74d7eb5bb..9e50514d2 100644 --- a/doc/howto.jax +++ b/doc/howto.jax @@ -15,7 +15,7 @@ How to ... *howdoi* *how-do-i* *howto* *how-to* |07.4| 上書きするときにバックアップファイルを作っておく |usr_07.txt| ファイルを編集する -|23.4| バイナリーファイルを編集する +|23.4| バイナリファイルを編集する |usr_24.txt| テキストを挿入する |deleting| テキストを削除する |usr_04.txt| テキストを変更する diff --git a/doc/if_cscop.jax b/doc/if_cscop.jax index 366608115..d2b1af7b7 100644 --- a/doc/if_cscop.jax +++ b/doc/if_cscop.jax @@ -5,7 +5,7 @@ *cscope* *Cscope* -この文章はVimにおけるcscopeインターフェースの使い方について述べている。 +この文章はVimにおけるcscopeインターフェイスの使い方について述べている。 cscopeはctagsのようなツールであるが、ctagsよりも多くの機能が提供されるので ctagsの代わりとみなせる。Vimではタグにジャンプするように、cscopeクエリの結果へ @@ -32,7 +32,7 @@ ctagsの代わりとみなせる。Vimではタグにジャンプするように cscopeは貴方を助けるインタラクティブなスクリーン指向のツールです: - いつ終わるかわからない厚いソースリストのぺージをめくることなく、Cプログ + いつ終わるかわからない厚いソースリストのページをめくることなく、Cプログ ラムがどのように働くかを知る。 プログラム全体を知らなくても、バグを修正するために変更すべきコードの位 @@ -73,12 +73,12 @@ ctagsの代わりとみなせる。Vimではタグにジャンプするように ファイルを編集するためのエディタを指定してあると、普段viでCtrl-]や:tagコマンド でやっているようなタグからタグへの単純なジャンプはできなくなる。 -Vimのcscopeインターフェースはcscopeの行指向インターフェースを利用することでこ +Vimのcscopeインターフェイスはcscopeの行指向インターフェイスを利用することでこ れを行い、実クエリに対する出力を解釈する。cscopeのクエリの結果は最終的に通常の tagsのようになるので、普通のタグのようなジャンプ操作 (Ctrl-]や:tag) を行うこと ができ、タグスタックをCtrl-Tで逆に辿ることも可能になる。(しかしキーマップの再 定義やコマンドやオプションの設定をしないで、まったく単純にCtrl-]や:tagと同じよ -うにジャンプできるわけではないことに注意して欲しい。cscopeインターフェースがど +うにジャンプできるわけではないことに注意して欲しい。cscopeインターフェイスがど のように働くのか、どういう使い方が提案されているのかは残りのセクションを参 照。) @@ -114,7 +114,7 @@ tagsのようになるので、普通のタグのようなジャンプ操作 (Ct 使用法 :cs find {querytype} {name} - {querytype}は実際のcscopeのラインインターフェース + {querytype}は実際のcscopeのラインインターフェイス の番号(デフォルトのnviコマンド)に対応する: 0 or s: Cのシンボルを検索 @@ -443,7 +443,7 @@ http://cscope.sourceforge.net でダウンロードできる、 DJGPP でビル まだcscopeを持っていない(あなたのコンパイラのライセンスやOSのディストリビュー ションに含まれてない)のならば、次の場所から無料で入手できる: http://cscope.sourceforge.net/ -cscopeはSCOによりBSDラインセンスの基づいて配布されている。 +cscopeはSCOによりBSDライセンスに基づいて配布されている。 より新しいバージョンのcscopeを入手したいのならば、恐らく購入する必要があるだろ う。(古い)nviのドキュメントによれば: @@ -451,7 +451,7 @@ cscopeはSCOによりBSDラインセンスの基づいて配布されている バージョン13.3の無制限ライセンス付きのソースコードが、AT&Tソフトウェア ソリューション(電話番号+1-800-462-8146)から400ドルで購入できる。 -また cscope 13.x や mlcscope 14.x (他国後バージョンのcscopeで、C, C++, Java, +また cscope 13.x や mlcscope 14.x (多言語バージョンのcscopeで、C, C++, Java, lex, yacc, breakpoint listing, Ingres, and SDL をサポートしている) を次のサイ トからダウンロードできる。 World-Wide Exptools Open Source packages page: @@ -468,9 +468,9 @@ SGIの開発者もまた入手可能である。このページからCscopeを 古いcscopeのクローン("cs" という名)のソースコードがネットで入手可能である。た だし様々な理由で、これはVimではサポートされない。 -オリジナルのcscopeインターフェース/サポートはAndy Kahn に +オリジナルのcscopeインターフェイス/サポートはAndy Kahn に よって書かれた。元となった構造(かなり小さいコードだった)はnviのcscopeインター -フェースから改作された。問題、提案、パッチそのほか何でも、Vimでcscopeを使うの +フェイスから改作された。問題、提案、パッチそのほか何でも、Vimでcscopeを使うの に何か持っているものがあれば彼に送って欲しい。 {訳注: もちろん日本語では送らないで下さい} *cscope-win32* diff --git a/doc/if_lua.jax b/doc/if_lua.jax index 9c2123c04..83e4755d6 100644 --- a/doc/if_lua.jax +++ b/doc/if_lua.jax @@ -1,22 +1,24 @@ -*if_lua.txt* For Vim バージョン 7.4. Last change: 2012 Jun 29 +*if_lua.txt* For Vim バージョン 7.4. Last change: 2015 Oct 16 VIMリファレンスマニュアル by Luis Carvalho -Vim の Lua インターフェース *lua* *Lua* +Vim の Lua インターフェイス *lua* *Lua* 1. コマンド |lua-commands| 2. vim モジュール |lua-vim| 3. List ユーザーデータ |lua-list| 4. Dict ユーザーデータ |lua-dict| -5. バッファユーザーデータ |lua-buffer| -6. ウィンドウユーザーデータ |lua-window| -7. luaeval 関数 |lua-luaeval| +5. Funcref userdata |lua-funcref| +6. バッファユーザーデータ |lua-buffer| +7. ウィンドウユーザーデータ |lua-window| +8. luaeval 関数 |lua-luaeval| +9. Dynamic loading |lua-dynamic| {Vi にはこれらのコマンドはありません} -Lua インターフェースは Vim が |+lua| 機能付きでコンパイルされたときのみ利用で +Lua インターフェイスは Vim が |+lua| 機能付きでコンパイルされたときのみ利用で きます。 ============================================================================== @@ -110,9 +112,31 @@ Lua からは "vim" モジュールを使って Vim を操作します。範囲 バッファ操作、ウィンドウ操作、現在行の取得、Vim 式評価、Vim コマンド実行、など のルーチンが含まれています。 - vim.list() 空のリストを返す (|List| 参照)。 - - vim.dict() 空の辞書を返す (|Dictionary| 参照)。 + vim.list([arg]) Returns an empty list or, if "arg" is a Lua + table with numeric keys 1, ..., n (a + "sequence"), returns a list l such that l[i] = + arg[i] for i = 1, ..., n (see |List|). + Non-numeric keys are not used to initialize + the list. See also |lua-eval| for conversion + rules. Example: > + :lua t = {math.pi, false, say = 'hi'} + :echo luaeval('vim.list(t)') + :" [3.141593, 0], 'say' is ignored +< + vim.dict([arg]) Returns an empty dictionary or, if "arg" is a + Lua table, returns a dict d such that d[k] = + arg[k] for all string keys k in "arg" (see + |Dictionary|). Number keys are converted to + strings. Keys that are not strings are not + used to initialize the dictionary. See also + |lua-eval| for conversion rules. Example: > + :lua t = {math.pi, false, say = 'hi'} + :echo luaeval('vim.dict(t)') + :" {'say': 'hi'}, numeric keys ignored +< + vim.funcref({name}) Returns a Funcref to function {name} (see + |Funcref|). It is equivalent to Vim's + "function". NOT IMPLEMENTED YET vim.buffer([arg]) "arg" が数値ならバッファリストの "arg" 番の バッファを返す。"arg" が文字列ならフルパスか @@ -131,9 +155,9 @@ Lua からは "vim" モジュールを使って Vim を操作します。範囲 vim.type({arg}) {arg} の型を返す。これは Lua の "type" 関数と 同じようなものですが、{arg} がリスト、辞書、 - バッファ、ウィンドウのときに、 "list"、 - "dict"、"buffer"、"window" をそれぞれ返しま - す。例: > + 関数参照、バッファ、ウィンドウのときに、 + "list"、"dict"、"funcref"、"buffer"、"window" + をそれぞれ返します。例: > :lua l = vim.list() :lua print(type(l), vim.type(l)) :" userdata list @@ -226,7 +250,40 @@ list ユーザーデータと同様、dict ユーザーデータは vim の辞 < ============================================================================== -5. バッファユーザーデータ *lua-buffer* +5. Funcref userdata *lua-funcref* + +Funcref userdata represent funcref variables in Vim. Funcrefs that were +defined with a "dict" attribute need to be obtained as a dictionary key +in order to have "self" properly assigned to the dictionary (see examples +below.) A funcref "f" has the following properties: + +Properties +---------- + o "#f" is the name of the function referenced by "f" + o "f(...)" calls the function referenced by "f" (with arguments) + +Examples: +> + :function I(x) + : return a:x + : endfunction + :let R = function('I') + :lua i1 = vim.funcref('I') + :lua i2 = vim.eval('R') + :lua print(#i1, #i2) -- both 'I' + :lua print(i1, i2, #i2(i1) == #i1(i2)) + :function Mylen() dict + : return len(self.data) + : endfunction + :let mydict = {'data': [0, 1, 2, 3]} + :lua d = vim.eval('mydict'); d.len = vim.funcref('Mylen') + :echo mydict.len() + :lua l = d.len -- assign d as 'self' + :lua print(l()) +< + +============================================================================== +6. バッファユーザーデータ *lua-buffer* バッファユーザーデータは Vim のバッファを表します。バッファユーザーデータ "b" は以下のプロパティとメソッドを持っています: @@ -277,7 +334,7 @@ list ユーザーデータと同様、dict ユーザーデータは vim の辞 < ============================================================================== -6. ウィンドウユーザーデータ *lua-window* +7. ウィンドウユーザーデータ *lua-window* ウィンドウオブジェクトは Vim のウィンドウを表します。ウィンドウユーザーデータ "w" は以下のプロパティとメソッドを持っています: @@ -309,7 +366,7 @@ list ユーザーデータと同様、dict ユーザーデータは vim の辞 < ============================================================================== -7. luaeval 関数 *lua-luaeval* *lua-eval* +8. luaeval 関数 *lua-luaeval* *lua-eval* "luaeval" は "vim.eval" と対となる関数で Lua の値を Vim に渡すことができます。 "luaeval" は式文字列と任意の引数を受け取り、式の結果を返します。意味的には次の @@ -321,7 +378,13 @@ Lua コードと同じです: return chunk(arg) -- return typval end < -Note "_A" には "luaeval" の引数が渡されます。例: > +Note "_A" には "luaeval" の引数が渡されます。 Lua numbers, strings, and +list, dict, and funcref userdata are converted to their Vim respective types, +while Lua booleans are converted to numbers. An error is thrown if conversion +of any of the remaining Lua types, including userdata other than lists, dicts, +and funcrefs, is attempted. + +例: > :echo luaeval('math.pi') :lua a = vim.list():add('newlist') @@ -333,5 +396,24 @@ Note "_A" には "luaeval" の引数が渡されます。例: > :echo Rand(1,10) +============================================================================== +9. Dynamic loading *lua-dynamic* + +On MS-Windows and Unix the Lua library can be loaded dynamically. The +|:version| output then includes |+lua/dyn|. + +This means that Vim will search for the Lua DLL or shared library file only +when needed. When you don't use the Lua interface you don't need it, thus +you can use Vim without this file. + +On MS-Windows to use the Lua interface the Lua DLL must be in your search path. +In a console window type "path" to see what directories are used. The version +of the DLL must match the Lua version Vim was compiled with. + +On Unix the 'luadll' option can be used to specify the Lua shared library file +instead of DYNAMIC_LUA_DLL file what was specified at compile time. The +version of the shared library must match the Lua version Vim was compiled with. + + ============================================================================== vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/doc/if_mzsch.jax b/doc/if_mzsch.jax index 826d9e4c8..81fd631dc 100644 --- a/doc/if_mzsch.jax +++ b/doc/if_mzsch.jax @@ -1,4 +1,4 @@ -*if_mzsch.txt* For Vim バージョン 7.4. Last change: 2012 Dec 17 +*if_mzsch.txt* For Vim バージョン 7.4. Last change: 2016 Jan 24 VIMリファレンスマニュアル by Sergey Khorev @@ -13,6 +13,7 @@ Vim の MzScheme インターフェイス *mzscheme* *MzScheme* 5. mzeval() Vim 関数 |mzscheme-mzeval| 6. 関数参照を使う |mzscheme-funcref| 7. 動的ローディング |mzscheme-dynamic| +8. MzSchemeのセットアップ |mzscheme-setup| {Vi にはこれらのコマンドはありません} @@ -215,7 +216,7 @@ NOTE 入される。 (curr-buff) カレントバッファ(オブジェクト)を取得する。 バッファを変更するには他の MzScheme イン - ターフェース手続きを使う。 + ターフェイス手続きを使う。 (buff-count) バッファの総数を取得する。 (get-next-buff [buffer]) 次のバッファを取得する (get-prev-buff [buffer]) 前のバッファを取得する。それ以上前が存在し @@ -254,7 +255,7 @@ MzScheme の式を評価してその結果を VimL の値に変換したもの ============================================================================== 6. 関数参照を使う *mzscheme-funcref* -MzScheme インターフェースでは関数参照 (|Funcref|) が使えます。Vim の関数を +MzScheme インターフェイスでは関数参照 (|Funcref|) が使えます。Vim の関数を Scheme から直接呼び出せます。例: > function! MyAdd2(arg) return a:arg + 2 @@ -268,7 +269,7 @@ Scheme から直接呼び出せます。例: > < ============================================================================== -7. 動的ローディング *mzscheme-dynamic* *E815* +7. 動的ローディング *mzscheme-dynamic* *E815* MS-Windows では MzScheme ライブラリを動的に読み込むことが可能です。これを行う と |:version| の出力に |+mzscheme/dyn| が含まれるようになります。 @@ -276,6 +277,9 @@ MS-Windows では MzScheme ライブラリを動的に読み込むことが可 この場合、Vim は必要なときだけ MzScheme の DLL ファイルを検索するようになりま す。MzScheme インターフェイスを使わないときは DLL を必要としないので、DLL な しで Vim を使うことができます。 +NOTE: 比較的新しいバージョンの MzScheme (Racket) は scheme_main_setup によるト +ランポリンを用いた事前初期化処理を必要とします。そのために Vim は可能であれば常 +に MzScheme の DLL を初期化時に読み込みます。 MzScheme インターフェイスを使うには MzScheme の DLL が検索パス内に存在しなけ ればなりません。コンソールウィンドウで "path" とタイプすると、どのディレクト @@ -287,5 +291,25 @@ DLL の名前は Vim をコンパイルした時の MzScheme のバージョン を見て、コンパイル情報から -DDYNAMIC_MZSCH_DLL="なんらか" と -DDYNAMIC_MZGC_DLL="なんらか" を探してください。 +例えば、MzScheme (Racket) が C:\Racket63 にインストールされている場合、次のよう +に環境変数を設定する必要があるかもしれません: > + + PATH=%PATH%;C:\Racket63\lib + PLTCOLLECTS=C:\Racket63\collects + PLTCONFIGDIR=C:\Racket63\etc +< +============================================================================== +8. MzScheme setup *mzscheme-setup* *E895* + +Vim は if_mzsch のコアモジュールとして "racket/base" (もし存在しなければ +"scheme/base" にフォールバックします) を、テストのために "r5rs" モジュールを、 +そして Vim のビルド時に必要な "raco ctool" コマンドを要求します。MzScheme がそ +れらを持っていなかった場合は MzScheme の raco コマンドで次のようにインストール +できます: +> + raco pkg install scheme-lib # scheme/base module + raco pkg install r5rs-lib # r5rs module + raco pkg install cext-lib # raco ctool command + ====================================================================== vim:tw=78:ts=8:sts=4:ft=help:norl: diff --git a/doc/if_ole.jax b/doc/if_ole.jax index 9fdb9013c..a4ed6e5e5 100644 --- a/doc/if_ole.jax +++ b/doc/if_ole.jax @@ -86,7 +86,7 @@ Eval(expr) 式(expr)を実行する。 照)。戻り値は、その式を評価した結果の文字列である。リスト |List| は文字列に変 換される。そのとき各要素の間に改行が挿入され、連結される。 -Examples (Visual Basic の文法で) > +例 (Visual Basic の文法で) > Line20 = Vim.Eval("getline(20)") Twelve = Vim.Eval("6 + 6") ' これが文字列であることに注意 Font = Vim.Eval("&guifont") diff --git a/doc/if_perl.jax b/doc/if_perl.jax index 7b6dcae7a..d5959f185 100644 --- a/doc/if_perl.jax +++ b/doc/if_perl.jax @@ -1,4 +1,4 @@ -*if_perl.txt* For Vim バージョン 7.4. Last change: 2012 Oct 25 +*if_perl.txt* For Vim バージョン 7.4. Last change: 2015 Oct 16 VIMリファレンスマニュアル by Sven Verdoolaege @@ -6,14 +6,14 @@ Perl と Vim *perl* *Perl* -1. Perl のファイルを編集する |perl-editing| -2. Perl インタフェイス付きのコンパイル |perl-compiling| -3. Perl インタフェイスを使う |perl-using| -4. 動的ローディング |perl-dynamic| +1. Perl のファイルを編集する |perl-editing| +2. Perl インターフェイス付きのコンパイル |perl-compiling| +3. Perl インターフェイスを使う |perl-using| +4. 動的ローディング |perl-dynamic| {Vi にはこれらのコマンドはありません} -Perl インタフェイスは、Vim を |+perl| 機能付きでコンパイルしている場合にのみ +Perl インターフェイスは、Vim を |+perl| 機能付きでコンパイルしている場合にのみ 利用できます。 ============================================================================== @@ -33,13 +33,13 @@ Perl スクリプトの "pltags.pl" を使うこともできます。これは $ ディレクトリにあります。これは今のところ最新のctagsよりも高機能です。 ============================================================================== -2. Perl インタフェイス付きのコンパイル *perl-compiling* +2. Perl インターフェイス付きのコンパイル *perl-compiling* -Perl インタフェイス付きで Vim をコンパイルするには、5.004 もしくはそれ以上のバー -ジョンの Perl が必要です。Perl は Vim をコンパイルする前にインストールしておか -なければなりません。Vim の Perl インタフェイスは、公式にリリースされたバージョ -ンである Perl 5.003 では動作しません! Perl 5.003_05 もしくはそれ以上であれば、 -たぶん動作するでしょう。 +Perl インターフェイス付きで Vim をコンパイルするには、5.004 もしくはそれ以上の +バージョンの Perl が必要です。Perl は Vim をコンパイルする前にインストールして +おかなければなりません。Vim の Perl インターフェイスは、公式にリリースされた +バージョンである Perl 5.003 では動作しません! Perl 5.003_05 もしくはそれ以上で +あれば、たぶん動作するでしょう。 Vim への Perl パッチは、次の方によって作成されました: Sven Verdoolaege @@ -50,7 +50,7 @@ http://www.perl.com/ ActiveState のものも動作するでしょう。 ============================================================================== -3. Perl インタフェイスを使う *perl-using* +3. Perl インターフェイスを使う *perl-using* *:perl* *:pe* :pe[rl] {cmd} Perl コマンド {cmd} を実行します。現在のパッケージは @@ -115,7 +115,7 @@ Perl で使える関数の一覧です: > :perl VIM::SetOption("ai") # Vim のオプションをセットします :perl $nbuf = VIM::Buffers() # 全てのバッファ数を返す :perl @buflist = VIM::Buffers() # 全てのバッファの配列を返す - :perl $mybuf = (VIM::Buffers('qq.c'))[0] # 'qq.c' のバッファ・オブジェクト + :perl $mybuf = (VIM::Buffers('qq.c'))[0] # 'qq.c' のバッファオブジェクト # を返す :perl @winlist = VIM::Windows() # 全てのウィンドウの配列を返す :perl $nwin = VIM::Windows() # ウィンドウ数を返す @@ -128,7 +128,7 @@ Perl で使える関数の一覧です: > :perl @pos = (10, 10) :perl $curwin->Cursor(@pos) # カーソルを @pos にセットします :perl $curwin->Cursor(10,10) # カーソルを10行10列目にセットします - :perl $mybuf = $curwin->Buffer() # ウィンドウのバッファ・オブジェクトを + :perl $mybuf = $curwin->Buffer() # ウィンドウのバッファオブジェクトを # 返す :perl $curbuf->Name() # バッファ名を返します :perl $curbuf->Number() # returns buffer number @@ -296,6 +296,13 @@ DLLの名前はVimをコンパイルした時のPerlのバージョンに一致 現在その名前は "perl512.dll" です。これはPerl5.12用です。これを確かめるには、 "gvim.exe" を開き、"perl\d*.dll\c" を検索してください。 -============================================================================== +Unix ~ + +コンパイル時に DYNAMIC_PERL_DLL で指定されたファイルの代わりに 'perldll' オプシ +ョンで使用する Perl の共有ライブラリのファイルを指定するのに使えます。共有ライ +ブラリのバージョンは Vim と共にコンパイルされた Perl のバージョンと一致していな +ければなりません。 + +============================================================================== vim:tw=78:ts=8:ft=help:norl: diff --git a/doc/if_pyth.jax b/doc/if_pyth.jax index a7f110dbf..cfbfbf12f 100644 --- a/doc/if_pyth.jax +++ b/doc/if_pyth.jax @@ -1,4 +1,4 @@ -*if_pyth.txt* For Vim バージョン 7.4. Last change: 2013 May 25 +*if_pyth.txt* For Vim バージョン 7.4. Last change: 2015 Nov 10 VIMリファレンスマニュアル by Paul Moore @@ -23,11 +23,12 @@ Python 2.x インターフェイスは Vim が |+python| 機能付きでコン のみ利用できます。 Python 3 インターフェイスは Vim が |+python3| 機能付きでコンパイルされたときの み利用できます。 +両方を同時に利用することはできますが、|python-2-and-3| をお読みください。 ============================================================================== 1. コマンド *python-commands* - *:python* *:py* + *:python* *:py* *E263* *E264* *E887* :[range]py[thon] {stmt} Pythonのステートメント{stmt}を実行します。`:python` コ マンドが機能するか簡単にチェックするには: > @@ -172,6 +173,22 @@ vim.bindeval(str) *python-bindeval* や辞書 (|Dictionary|) を変更したり、Vim の関数 (|Funcref|) を呼び出し たりできます。 +vim.strwidth(str) *python-strwidth* + |strwidth()| と同じ。str の画面上の幅を数値で返す。タブ文字は 1 幅とし + てカウントされる。 + +vim.foreach_rtp(callable) *python-foreach_rtp* + 'runtimepath' の各パスについてコーラブル (callable) を呼び出す。コーラ + ブルが None 以外の値を返すか、例外が発生するか、パスの最後まで処理が進 + むと停止する。コーラブルが None 以外の値を返して停止した場合は、 + vim.foreach_rtp 関数はその値を返す。 + +vim.chdir(*args, **kwargs) *python-chdir* +vim.fchdir(*args, **kwargs) *python-fchdir* + os.chdir、os.fchdir を実行し、Vim にそのことを通知する。 + Note: これらの関数は直接は使用しない。代わりに os.chdir と os.fchdir + を使う。os.fchdir が存在しない場合の vim.fchdir の動作は未定義。 + "vim" モジュールのエラーオブジェクト vim.error *python-error* @@ -207,7 +224,7 @@ vim.windows *python-windows* オブジェクトに結びつけられて、常にそのタブページのウィンドウを参照しま す (タブページが削除されていたときは vim.error 例外が発生します)。vim モジュールや |python-tabpage| オブジェクトへの参照を維持しなくても、参 - 照は保持されます。プロパティーも失われません。 + 照は保持されます。プロパティも失われません。 vim.tabpages *python-tabpages* Vim のタブページの一覧へのアクセスを提供するシーケンスオブジェクト。 @@ -281,6 +298,86 @@ Pythonからの出力 *python-output* ず、プログラムをクラッシュさせる可能性があります。これはたぶん修正され るべき問題です。 + *python2-directory* *python3-directory* *pythonx-directory* +Python における 'runtimepath' の処理 *python-special-path* + +Python では、'runtimepath' のパスのリストを使う代わりに、vim.VIM_SPECIAL_PATH +という特別なディレクトリが使われます。このディレクトリが sys.path 内で使われる +とき、そして vim.path_hooks が sys.path_hooks 内で使われるとき、'runtimepath' +の各パス {rtp} に対して {rtp}/python2 (or python3) と {rtp}/pythonx (両バー +ジョンで読み込まれる) のモジュールがロードされます。 + +実装は以下のようになっています。ただし実際は C で書かれています: > + + from imp import find_module, load_module + import vim + import sys + + class VimModuleLoader(object): + def __init__(self, module): + self.module = module + + def load_module(self, fullname, path=None): + return self.module + + def _find_module(fullname, oldtail, path): + idx = oldtail.find('.') + if idx > 0: + name = oldtail[:idx] + tail = oldtail[idx+1:] + fmr = find_module(name, path) + module = load_module(fullname[:-len(oldtail)] + name, *fmr) + return _find_module(fullname, tail, module.__path__) + else: + fmr = find_module(fullname, path) + return load_module(fullname, *fmr) + + # It uses vim module itself in place of VimPathFinder class: it does not + # matter for python which object has find_module function attached to as + # an attribute. + class VimPathFinder(object): + @classmethod + def find_module(cls, fullname, path=None): + try: + return VimModuleLoader(_find_module(fullname, fullname, path or vim._get_paths())) + except ImportError: + return None + + @classmethod + def load_module(cls, fullname, path=None): + return _find_module(fullname, fullname, path or vim._get_paths()) + + def hook(path): + if path == vim.VIM_SPECIAL_PATH: + return VimPathFinder + else: + raise ImportError + + sys.path_hooks.append(hook) + +vim.VIM_SPECIAL_PATH *python-VIM_SPECIAL_PATH* + Vim のパスフックに関連付けられた文字列定数。Vim によって設定されたパス + フックが vim.VIM_SPECIAL_PATH 定数以外のパスに対して呼び出された場合は + ImportError が発生します。そうでなければ特殊ローダが使用されます。 + + Note: この定数の値を直接使用しないこと。常に vim.VIM_SPECIAL_PATH オブ + ジェクトを使用してください。 + +vim.find_module(...) *python-find_module* +vim.path_hook(path) *python-path_hook* + 上述のパスフックの実装に使われるメソッドとオブジェクト。sys.meta_path + で vim.path_hook を使って何かをするようなことがなければ、これらを直接 + 使用することはないでしょう。これらのオブジェクトが Vim の将来のバー + ジョンでも存在するかどうかは保証されません。 + +vim._get_paths *python-_get_paths* + パスフックで検索されるパスのリストを返すメソッド。将来のバージョンのこ + とを考えるならこのメソッドに依存すべきではありません。デバッグなどに使 + います。 + + 'runtimepath' の各パスに対して {rtp}/python2 (or {rtp}/python3) と + {rtp}/pythonx ディレクトリのリストを返します。 + ============================================================================== 3. バッファオブジェクト *python-buffer* @@ -323,6 +420,8 @@ Pythonからの出力 *python-output* |BufFilePre| と |BufFilePost| イベントが発生します。 b.number バッファ番号。|python-buffers| のキーとして使えます。 読み込み専用。 + b.valid True または False。 関連バッファが破棄されるとバッファ + オブジェクトは無効となる。 バッファオブジェクトのメソッドは次の通りです: b.append(str) バッファに行を追加 @@ -426,6 +525,8 @@ Range オブジェクトの型は vim モジュールの "Range" 属性で取得 row, col (読み専用) スクリーン上でのウィンドウの表示位置。値は 0 から始まります。 tabpage (読み専用) ウィンドウのタブページ。 + valid (read-write) True または False。 関連ウィンドウが閉じられる + とウィンドウオブジェクトは無効になる。 heightはスクリーンが水平方向に分割されているときのみ書き込み可能です。 widthはスクリーンが垂直方向に分割されているときのみ書き込み可能です。 @@ -487,9 +588,9 @@ vim.Dictionary オブジェクト *python-Dictionary* 辞書からキーを取り除き、その値を返す。キーが存在しない場合 は、default が指定されていたらその値を返す。指定されていな ければ KeyError 例外が発生する。 - popitem(key) - 辞書からキーを取り除き、そのキーと値のペアを返す。返される - キーは新しいオブジェクトである。 + popitem() + 辞書からランダムにキーを取り除き (key, value) のペアを返 + す。 has_key(key) 辞書がキーを持っているかを確認する。`key in dict` と同じ。 @@ -560,27 +661,34 @@ vim.Function オブジェクト *python-Function* ============================================================================== 8. Vim 関数 pyeval() と py3eval() *python-pyeval* -双方向インターフェースを容易にするため、|pyeval()| 関数と |py3eval()| 関数を +双方向インターフェイスを容易にするため、|pyeval()| 関数と |py3eval()| 関数を 使って Python の式を評価して、その値を VimL に渡すことができます。 ============================================================================== 9. 動的ローディング *python-dynamic* -MS-WindowsではPythonライブラリを動的に読み込むことが可能です。これを行うと -|:version| の出力に |+python/dyn| が含まれるようになります。 +MS-Windows と UNIX では Python ライブラリを動的に読み込むことが可能です。これ +を行うと |:version| の出力に |+python/dyn| もしくは |+python3/dyn| が含まれる +ようになります。 -この場合、Vimは必要なときだけPythonのDLLファイルを検索します。Pythonインター -フェイスを使わないときはDLLを必要としないので、DLLなしでVimを使うことができま -す。 +この場合、Vimは必要なときだけPythonのDLLファイル、もしくは共有ライブラリファイ +ルを検索します。Pythonインターフェイスを使わないときはDLLを必要としないので、 +DLLなしでVimを使うことができます。 -Pythonインターフェイスを使うにはPythonのDLLが検索パス内に存在しなければなりま -せん。コンソールウィンドウで "path" とタイプすると、どのディレクトリが検索パス -となるか表示することができます。 +WindowsでPythonインターフェイスを使うには、PythonのDLLが検索パス内に存在しなけ +ればなりません。コンソールウィンドウで "path" とタイプすると、どのディレクトリ +が検索パスとなるか表示することができます。 DLLの名前はVimをコンパイルした時のPythonのバージョンに一致しなければなりませ ん。現在その名前は "python24.dll" です。これはPython2.4用です。これを確かめる には、"gvim.exe" を開き、"python\d*.dll\c" を検索してください。 +Unix ではコンパイル時に DYNAMIC_PYTHON_DLL もしくは DYNAMIC_PYTHON3_DLL で指定 +されたファイルの代わりに 'pythondll' もしくは 'pythonthreedll' オプションで使用 +する Python の共有ライブラリのファイルを指定するのに使えます。共有ライブラリの +バージョンは Vim をコンパイルする時に用いた Python 2.x または Python 3 のバージ +ョンと一致していなければなりません。 + ============================================================================== 10. Python 3 *python3* @@ -600,7 +708,7 @@ Vim のビルドは 4 種類あります (:version の出力): 3. Python 3 サポートのみ (-python, +python3 or +python3/dyn) 4. Python 2 と 3 のサポート (+python/dyn, +python3/dyn) -特殊ケース 4 に付いてもう少し詳細に説明します: +特殊ケース 4 に付いてもう少し詳細に説明します: *python-2-and-3* Python 2 と Python 3 をサポートするにはそれらを動的ロードする必要があります。 @@ -628,6 +736,11 @@ Vim の動作はコンフィグを実行したシステムに依存します。P 3. コンフィグ実行後に auto/config.h の PY_NO_RTLD_GLOBAL の定義を削除する。こ れは Vim がクラッシュするようになるでしょう。 + *E880* +Python 内で SystemExit 例外を発生させても Vim は終了しない。次のようにする: > + :py vim.command("qall!") +< + *has-python* どのバージョンの Python が利用可能になっているかは次のコマンドで確認できます: > diff --git a/doc/if_ruby.jax b/doc/if_ruby.jax index 187145ffe..8f59c0861 100644 --- a/doc/if_ruby.jax +++ b/doc/if_ruby.jax @@ -1,4 +1,4 @@ -*if_ruby.txt* For Vim バージョン 7.4. Last change: 2012 Aug 02 +*if_ruby.txt* For Vim バージョン 7.4. Last change: 2015 Dec 03 VIM リファレンスマニュアル by Shugo Maeda @@ -7,9 +7,9 @@ Rubyインターフェイス *ruby* *Ruby* 1. コマンド |ruby-commands| -2. VIMモジュール |ruby-vim| -3. VIM::Buffer オブジェクト |ruby-buffer| -4. VIM::Window オブジェクト |ruby-window| +2. Vimモジュール |ruby-vim| +3. Vim::Buffer オブジェクト |ruby-buffer| +4. Vim::Window オブジェクト |ruby-window| 5. グローバル変数 |ruby-globals| 6. 動的ローディング |ruby-dynamic| @@ -48,7 +48,7 @@ Vimスクリプトの例: > ruby << EOF class Garnet def initialize(s) - @buffer = VIM::Buffer.current + @buffer = Vim::Buffer.current vimputs(s) end def vimputs(s) @@ -74,19 +74,19 @@ Vimスクリプトの例: > |sandbox|環境内ではRubyコマンドを実行できない。 ============================================================================== -2. VIMモジュール *ruby-vim* +2. Vimモジュール *ruby-vim* -Rubyのコードは全てのVimへのアクセスをVIMモジュール経由で行う。 +Rubyのコードは全てのVimへのアクセスをVimモジュール経由で行う。 概要 > print "Hello" # メッセージを表示する - VIM.command(cmd) # Exコマンドを実行する - num = VIM::Window.count # ウィンドウ数を取得する - w = VIM::Window[n] # ウィンドウ n を取得する - cw = VIM::Window.current # 現在のウィンドウを取得する - num = VIM::Buffer.count # バッファ数を取得する - b = VIM::Buffer[n] # バッファ n を取得する - cb = VIM::Buffer.current # 現在のバッファを取得する + Vim.command(cmd) # Exコマンドを実行する + num = Vim::Window.count # ウィンドウ数を取得する + w = Vim::Window[n] # ウィンドウ n を取得する + cw = Vim::Window.current # 現在のウィンドウを取得する + num = Vim::Buffer.count # バッファ数を取得する + b = Vim::Buffer[n] # バッファ n を取得する + cb = Vim::Buffer.current # 現在のバッファを取得する w.height = lines # ウィンドウの高さ(行数)を設定する w.cursor = [row, col] # ウィンドウのカーソル位置を設定する pos = w.cursor # カーソルの位置を配列で受け取る @@ -96,37 +96,42 @@ Rubyのコードは全てのVimへのアクセスをVIMモジュール経由で b[n] = str # バッファの行の内容を変更する b.delete(n) # 行を削除する b.append(n, str) # n行目の直後に行を追加する - line = VIM::Buffer.current.line # カレント行を取得する - num = VIM::Buffer.current.line_number # カレント行の行番号を取得する - VIM::Buffer.current.line = "test" # カレント行を設定する + line = Vim::Buffer.current.line # カレント行を取得する + num = Vim::Buffer.current.line_number # カレント行の行番号を取得する + Vim::Buffer.current.line = "test" # カレント行を設定する < モジュール関数: *ruby-message* -VIM::message({msg}) +Vim::message({msg}) メッセージ{msg}を表示する。 *ruby-set_option* -VIM::set_option({arg}) +Vim::set_option({arg}) Vimのオプションを設定する。{arg}は ":set" コマンドが受け付けるものであ れば何でも良い。引数の中では空白文字が使えないことに注意。|:set|を参 照。 *ruby-command* -VIM::command({cmd}) +Vim::command({cmd}) Exコマンド{cmd}を実行する。 *ruby-evaluate* -VIM::evaluate({expr}) +Vim::evaluate({expr}) Vim内部の実行エンジンを使ってスクリプト{expr}を実行評価する - (|expression|参照)。実行結果は文字列で返される。 - |List|は文字列に変換される。各要素が連結され、間に改行が挿入される。 + (|expression|参照)。実行結果は次のように返される: + - Vimの実行結果が number の場合は Integer + - Vimの実行結果が float の場合は Float + - Vimの実行結果が string の場合は String + - Vimの実行結果がVimの list の場合は Array + - Vimの実行結果がVimの dictionary の場合は Hash + 辞書とリストは再帰的に展開される。 ============================================================================== -3. VIM::Buffer オブジェクト *ruby-buffer* +3. Vim::Buffer オブジェクト *ruby-buffer* -オブジェクトVIM::BufferはVimのバッファを表す。 +オブジェクトVim::BufferはVimのバッファを表す。 クラスメソッド: @@ -151,9 +156,9 @@ line = {str} そのバッファがアクティブなら、カレント行を line_number そのバッファがアクティブなら、カレント行の行番号を返す。 ============================================================================== -4. VIM::Window オブジェクト *ruby-window* +4. Vim::Window オブジェクト *ruby-window* -VIM::Window オブジェクトはVimのウィンドウを表現している。 +Vim::Window オブジェクトはVimのウィンドウを表現している。 クラスメソッド: @@ -190,6 +195,8 @@ MS-WindowsとUnixではRubyライブラリを動的に読み込むことが可 る。Rubyインターフェイスを使わないのであればそれらは必要ではないので、ライブラ リファイルがシステムに無くてもVimを使うことができる。 +MS-Windows ~ + これが動作するためには Ruby の適切なバージョンがインストールされている必要があ る。次の場所からパッケージをダウンロードできる: http://www.garbagecollect.jp/ruby/mswin32/en/download/release.html @@ -208,5 +215,12 @@ _MSC_VER のチェックをコメントアウトする必要があるだろう また、インクルードディレクトリの名前をバージョンと同じ名前に変更する必要もある かもしれない。不思議なことに Ruby 1.9.3 のディレクトリは 1.9.1 となっている。 +Unix ~ + +コンパイル時に DYNAMIC_RUBY_DLL で指定されたファイルの代わりに、 'rubydll' オプ +ションを使って Ruby の共有ライブラリファイルを指定するのに使える。共有ライブラ +リのバージョンは Vim をコンパイルする時に用いた Ruby のバージョンと一致してい +なければならない。 + ============================================================================== vim:tw=78:ts=8:ft=help:norl: diff --git a/doc/if_sniff.jax b/doc/if_sniff.jax index 2466e5e46..e8b808999 100644 --- a/doc/if_sniff.jax +++ b/doc/if_sniff.jax @@ -9,12 +9,12 @@ SNiFF+ と Vim *sniff* 1. イントロダクション |sniff-intro| 2. コマンド |sniff-commands| -3. SNiFF+ インタフェイス付きコンパイル |sniff-compiling| +3. SNiFF+ インターフェイス付きコンパイル |sniff-compiling| {Vi にはこれらのコマンドはありません} *E275* *E274* *E276* *E278* *E279* -SNiFF+ インタフェイスは、|+sniff| 機能つきでコンパイルしていた場合にのみ有効で -す。 +SNiFF+ インターフェイスは、|+sniff| 機能つきでコンパイルしていた場合にのみ有効 +です。 ============================================================================== 1. イントロダクション *sniff-intro* @@ -33,9 +33,9 @@ Vim で SNiFF+ を使うには 4. Vim を起動します。 5. SNiFF+ に接続します。(:sniff 接続) -いったん接続が確立されると、SNiFF+ は、ソース・コードを表示したり、編集した -りする全てのリクエストで Vim を使います。一方、:sniff コマンドで SNiFF+ にク -エリーを送ることができます。 +いったん接続が確立されると、SNiFF+ は、ソースコードを表示したり、編集したりす +る全てのリクエストで Vim を使います。一方、:sniff コマンドで SNiFF+ にクエリを +送ることができます。 ============================================================================== 2. コマンド *sniff-commands* @@ -70,13 +70,13 @@ goto-symbol sg symbol の定義もしくは実装に飛びます。 hierarchy sh 階層ブラウザーに symbol を読み込みます。 restr-hier sH 上と同じですが、関連する class のみを表示しま す。 -xref-to sxt symbol に関する refers-to クエリーを開始し、結 - 果をクロス・リファレンサーに読み込む。 -xref-by sxb symbol に関する referred-by クエリーを開始する。 +xref-to sxt symbol に関する refers-to クエリを開始し、結果 + をクロス・リファレンサーに読み込む。 +xref-by sxb symbol に関する referred-by クエリを開始する。 xref-has sxh symbol に関する refers-to コンポーネント・クエ - リーを開始する。 + リを開始する。 xref-used-by sxu symbol に関して、コンポーネントとして - referred-by クエリーを開始する。 + referred-by クエリを開始する。 show-docu sd symbol のドキュメントを表示する。 gen-docu sD symbol のドキュメントを生成する。 @@ -85,10 +85,10 @@ gen-docu sD symbol のドキュメントを生成する。 続するときには、常に読み込まれます。 ============================================================================== -3. SNiFF+ インタフェイス付きコンパイル *sniff-compiling* +3. SNiFF+ インターフェイス付きコンパイル *sniff-compiling* Vim を SNiFF+ サポートつきでコンパイルするには、extra アーカイブに含まれる2つ -のソース・ファイルが必要になります: if_sniff.c と if_sniff.h。 +のソースファイルが必要になります: if_sniff.c と if_sniff.h。 Unix 上: Makefile を編集して "--enable-sniff" の行のコメントを外します。もしく は "--enable-sniff" を指定してconfigureを実行してください。 NT 上: make コマンドで SNIFF=yes を指定します。 diff --git a/doc/if_tcl.jax b/doc/if_tcl.jax index f6127ede2..cd8b63fbb 100644 --- a/doc/if_tcl.jax +++ b/doc/if_tcl.jax @@ -1,4 +1,4 @@ -*if_tcl.txt* For Vim バージョン 7.4. Last change: 2012 Aug 02 +*if_tcl.txt* For Vim バージョン 7.4. Last change: 2016 Jan 01 VIMリファレンスマニュアル by Ingo Wilken @@ -489,7 +489,7 @@ stdinからの入力は、今のところサポートされていない。 :tcl set n 1 :[range]tcldo set line "$n\t$line" ; incr n -このプロシージャは、各バッファでexコマンドを走らせる(Ron Aaron氏のアイディア): +このプロシージャは、各バッファでexコマンドを走らせる(Ron Aaron氏のアイデア): proc eachbuf { cmd } { foreach b [::vim::buffer list] { $b command $cmd @@ -511,11 +511,14 @@ Unixマシンでは "~/.vimrc.tcl" など)に入れておき、スタートア ============================================================================== 9. 動的ローディング *tcl-dynamic* -MS-WindowsではTclライブラリを動的に読み込むことが可能である。これを行うと -|:version|の出力に|+tcl/dyn|が含まれるようになる。 +MS-WindowsとUNIXではTclライブラリを動的に読み込むことが可能である。これを行う +と |:version| の出力に |+tcl/dyn| が含まれるようになる。 -この場合、Vimは必要なときだけTclのDLLファイルを検索する。Tclインターフェ -イスを使わないときはDLLを必要としないので、DLLなしでVimを使うことができる。 +この場合、Vimは必要なときだけTclのDLLファイルや共有ライブラリファイルを検索す +る。Tclインターフェイスを使わないときはこれらは不要なので、それらのファイルが +無くてもVimを使うことができる。 + +MS-Windows ~ Tclインターフェイスを使うにはTclのDLLが検索パス内に存在しなければならない。 コンソールウィンドウで "path" とタイプすると、どのディレクトリが検索パスとなる @@ -525,5 +528,13 @@ DLLの名前はVimをコンパイルした時のTclのバージョンに一致 現在その名前は "tcl83.dll" である。これはTcl8.3用である。これを確かめるには、 "gvim.exe" を開き、"tcl\d*.dll\c" を検索する。 + +Unix ~ + +コンパイル時に DYNAMIC_TCL_DLL で指定されたファイルの代わりに 'tcldll' オプショ +ンで使用する Tcl の共有ライブラリのファイルを指定するのに使える。共有ライブラリ +のバージョンは Vim をコンパイルする時に用いた Tcl のバージョンと一致していなけ +ればならない。 + ============================================================================== vim:tw=78:ts=8:ft=help:norl: diff --git a/doc/indent.jax b/doc/indent.jax index 83c23b1b6..461e83828 100644 --- a/doc/indent.jax +++ b/doc/indent.jax @@ -1,4 +1,4 @@ -*indent.txt* For Vim バージョン 7.4. Last change: 2013 May 20 +*indent.txt* For Vim バージョン 7.4. Last change: 2014 Dec 06 VIMリファレンスマニュアル by Bram Moolenaar @@ -545,9 +545,12 @@ CTRL-TやCTRL-Dを使用してインデントを変更した後では、Vimは (省略値 70行) *cino-#* - #N N がゼロでないときは '#' で始まるshell/Perlのコメントを認識する。 - N の既定値はゼロであり、'#' のコメントを認識しない。'#' で始まる - 行はプリプロセッサ行としても認識されることに注意。 + #N N がゼロでないときは '#' で始まる shell/Perl のコメントを認識す + る。プリプロセッサ行は認識されない。"#" で始まる行を右シフトでき + るようになる。 + N がゼロのとき (初期設定): '#' コメントを認識しない。プリプロ + セッサ行は認識される。"#" で始まる行に対する右シフトは機能しな + い。 省略値を全て並べるとこうなる: @@ -555,7 +558,7 @@ CTRL-TやCTRL-Dを使用してインデントを変更した後では、Vimは c3,C0,/0,(2s,us,U0,w0,W0,k0,m0,j0,J0,)20,*70,#0 次のような場合にはVimは行頭を1列目に持っていく: -- 'cinkeys' が '#' を含み行が '#' (プリプロセッサ命令)で始まる場合 +- 'cinkeys' が '#0' を含み行が '#' (プリプロセッサ命令)で始まる場合 - 行がラベル ("case" と "default" 以外のキーワードの後に ':' があるもの) で始 まり、'cinoptions' に正数を持った 'L' フラグがない場合。 - インデントの組合わせの結果、その行のインデント量が0以下になった場合。 @@ -591,12 +594,11 @@ searchpairpos() による検索の最大範囲を設定する。大きな値を " 初期設定 let g:clojure_maxlines = 100 < - *g:clojure_fuzzy_indent* *g:clojure_fuzzy_indent_patterns* *g:clojure_fuzzy_indent_blacklist* -'lispwords' オプションはカンマ区切りの単語のリストで、サブフォームをスペース 2 +'lispwords' オプションはコンマ区切りの単語のリストで、サブフォームをスペース 2 個でインデントする特別なフォームを指定する。 例: @@ -642,10 +644,9 @@ Clojure のいくつかのフォームは、'lispwords' に依らず、すべて let g:clojure_special_indent_words = \ 'deftype,defrecord,reify,proxy,extend-type,extend-protocol,letfn' < - *g:clojure_align_multiline_strings* -複数行文字列を、クオート文字と同じ列で揃えるのではなく、クオート文字の一つ後ろ +複数行文字列を、クォート文字と同じ列で揃えるのではなく、クォート文字の一つ後ろ の列で整列させる。 例: @@ -667,8 +668,28 @@ Clojure のいくつかのフォームは、'lispwords' に依らず、すべて " 初期設定 let g:clojure_align_multiline_strings = 0 < + *g:clojure_align_subforms* - +初期設定では、括弧で囲まれた関数呼び出しのような形でその最初の subform が括弧 +と同じ行にあるとき、そのうしろの subform は最初の括弧からスペース 2 つ分インデ +ントされる: +> + (foo + bar + baz) +< +このオプションを設定すると、clojure-mode.el のデフォルトの振る舞いのように、す +べての subform を同じカラムに揃えることができる: +> + (foo + bar + baz) +< +このオプションは初期設定ではオフになっている。 +> + " 初期設定 + let g:clojure_align_subforms = 0 +< FORTRAN *ft-fortran-indent* Block if、select case、where、forall 構造がインデントされる。さらに type、 @@ -695,7 +716,7 @@ Tidyのようなプログラムは構造化do/continueループをdo/enddo形式 let fortran_do_enddo=1 -このようなすればdoループはインデントされる。例えば拡張子が.f90 であるファイル +このようにすればdoループはインデントされる。例えば拡張子が.f90 であるファイル の中にある全てのループがdo/enddoタイプだけならば、このようなautocommandを使っ てのバッファフラグを設定することができる: > @@ -718,6 +739,48 @@ Tidyのようなプログラムは構造化do/continueループをdo/enddo形式 let b:fortran_indent_less=1 +HTML *ft-html-indent* *html-indent* *html-indenting* + +これらの変数を vimrc で設定することで HTML のインデントをカスタマイズできる。 + + + +See |mysyntaxfile-add| for installing script languages permanently. + + +APACHE *apache.vim* *ft-apache-syntax* + +The apache syntax file provides syntax highlighting depending on Apache HTTP +server version, by default for 1.3.x. Set "apache_version" to Apache version +(as a string) to get highlighting for another version. Example: > + + :let apache_version = "2.0" +< + + *asm.vim* *asmh8300.vim* *nasm.vim* *masm.vim* *asm68k* +ASSEMBLY *ft-asm-syntax* *ft-asmh8300-syntax* *ft-nasm-syntax* + *ft-masm-syntax* *ft-asm68k-syntax* *fasm.vim* + +Files matching "*.i" could be Progress or Assembly. If the automatic detection +doesn't work for you, or you don't edit Progress at all, use this in your +startup vimrc: > + :let filetype_i = "asm" +Replace "asm" with the type of assembly you use. + +There are many types of assembly languages that all use the same file name +extensions. Therefore you will have to select the type yourself, or add a +line in the assembly file that Vim will recognize. Currently these syntax +files are included: + asm GNU assembly (the default) + asm68k Motorola 680x0 assembly + asmh8300 Hitachi H-8300 version of GNU assembly + ia64 Intel Itanium 64 + fasm Flat assembly (http://flatassembler.net) + masm Microsoft assembly (probably works for any 80x86) + nasm Netwide assembly + tasm Turbo Assembly (with opcodes 80x86 up to Pentium, and + MMX) + pic PIC assembly (currently for PIC16F84) + +The most flexible is to add a line in your assembly file containing: > + asmsyntax=nasm +Replace "nasm" with the name of the real assembly syntax. This line must be +one of the first five lines in the file. No non-white text must be +immediately before or after this text. Note that specifying asmsyntax=foo is +equivalent to setting ft=foo in a |modeline|, and that in case of a conflict +between the two settings the one from the modeline will take precedence (in +particular, if you have ft=asm in the modeline, you will get the GNU syntax +highlighting regardless of what is specified as asmsyntax). + +The syntax type can always be overruled for a specific buffer by setting the +b:asmsyntax variable: > + :let b:asmsyntax = "nasm" + +If b:asmsyntax is not set, either automatically or by hand, then the value of +the global variable asmsyntax is used. This can be seen as a default assembly +language: > + :let asmsyntax = "nasm" + +As a last resort, if nothing is defined, the "asm" syntax is used. + + +Netwide assembler (nasm.vim) optional highlighting ~ + +To enable a feature: > + :let {variable}=1|set syntax=nasm +To disable a feature: > + :unlet {variable} |set syntax=nasm + +Variable Highlight ~ +nasm_loose_syntax unofficial parser allowed syntax not as Error + (parser dependent; not recommended) +nasm_ctx_outside_macro contexts outside macro not as Error +nasm_no_warn potentially risky syntax not as ToDo + + +ASPPERL and ASPVBS *ft-aspperl-syntax* *ft-aspvbs-syntax* + +*.asp and *.asa files could be either Perl or Visual Basic script. Since it's +hard to detect this you can set two global variables to tell Vim what you are +using. For Perl script use: > + :let g:filetype_asa = "aspperl" + :let g:filetype_asp = "aspperl" +For Visual Basic use: > + :let g:filetype_asa = "aspvbs" + :let g:filetype_asp = "aspvbs" + + +BAAN *baan.vim* *baan-syntax* + +The baan.vim gives syntax support for BaanC of release BaanIV upto SSA ERP LN +for both 3 GL and 4 GL programming. Large number of standard defines/constants +are supported. + +Some special violation of coding standards will be signalled when one specify +in ones |.vimrc|: > + let baan_code_stds=1 + +*baan-folding* + +Syntax folding can be enabled at various levels through the variables +mentioned below (Set those in your |.vimrc|). The more complex folding on +source blocks and SQL can be CPU intensive. + +To allow any folding and enable folding at function level use: > + let baan_fold=1 +Folding can be enabled at source block level as if, while, for ,... The +indentation preceding the begin/end keywords has to match (spaces are not +considered equal to a tab). > + let baan_fold_block=1 +Folding can be enabled for embedded SQL blocks as SELECT, SELECTDO, +SELECTEMPTY, ... The indentation preceding the begin/end keywords has to +match (spaces are not considered equal to a tab). > + let baan_fold_sql=1 +Note: Block folding can result in many small folds. It is suggested to |:set| +the options 'foldminlines' and 'foldnestmax' in |.vimrc| or use |:setlocal| in +.../after/syntax/baan.vim (see |after-directory|). Eg: > + set foldminlines=5 + set foldnestmax=6 + + +BASIC *basic.vim* *vb.vim* *ft-basic-syntax* *ft-vb-syntax* + +Both Visual Basic and "normal" basic use the extension ".bas". To detect +which one should be used, Vim checks for the string "VB_Name" in the first +five lines of the file. If it is not found, filetype will be "basic", +otherwise "vb". Files with the ".frm" extension will always be seen as Visual +Basic. + + +C *c.vim* *ft-c-syntax* + +A few things in C highlighting are optional. To enable them assign any value +to the respective variable. Example: > + :let c_comment_strings = 1 +To disable them use ":unlet". Example: > + :unlet c_comment_strings + +Variable Highlight ~ +c_gnu GNU gcc specific items +c_comment_strings strings and numbers inside a comment +c_space_errors trailing white space and spaces before a +c_no_trail_space_error ... but no trailing spaces +c_no_tab_space_error ... but no spaces before a +c_no_bracket_error don't highlight {}; inside [] as errors +c_no_curly_error don't highlight {}; inside [] and () as errors; + except { and } in first column +c_curly_error highlight a missing }; this forces syncing from the + start of the file, can be slow +c_no_ansi don't do standard ANSI types and constants +c_ansi_typedefs ... but do standard ANSI types +c_ansi_constants ... but do standard ANSI constants +c_no_utf don't highlight \u and \U in strings +c_syntax_for_h for *.h files use C syntax instead of C++ and use objc + syntax instead of objcpp +c_no_if0 don't highlight "#if 0" blocks as comments +c_no_cformat don't highlight %-formats in strings +c_no_c99 don't highlight C99 standard items +c_no_c11 don't highlight C11 standard items + +When 'foldmethod' is set to "syntax" then /* */ comments and { } blocks will +become a fold. If you don't want comments to become a fold use: > + :let c_no_comment_fold = 1 +"#if 0" blocks are also folded, unless: > + :let c_no_if0_fold = 1 + +If you notice highlighting errors while scrolling backwards, which are fixed +when redrawing with CTRL-L, try setting the "c_minlines" internal variable +to a larger number: > + :let c_minlines = 100 +This will make the syntax synchronization start 100 lines before the first +displayed line. The default value is 50 (15 when c_no_if0 is set). The +disadvantage of using a larger number is that redrawing can become slow. + +When using the "#if 0" / "#endif" comment highlighting, notice that this only +works when the "#if 0" is within "c_minlines" from the top of the window. If +you have a long "#if 0" construct it will not be highlighted correctly. + +To match extra items in comments, use the cCommentGroup cluster. +Example: > + :au Syntax c call MyCadd() + :function MyCadd() + : syn keyword cMyItem contained Ni + : syn cluster cCommentGroup add=cMyItem + : hi link cMyItem Title + :endfun + +ANSI constants will be highlighted with the "cConstant" group. This includes +"NULL", "SIG_IGN" and others. But not "TRUE", for example, because this is +not in the ANSI standard. If you find this confusing, remove the cConstant +highlighting: > + :hi link cConstant NONE + +If you see '{' and '}' highlighted as an error where they are OK, reset the +highlighting for cErrInParen and cErrInBracket. + +If you want to use folding in your C files, you can add these lines in a file +in the "after" directory in 'runtimepath'. For Unix this would be +~/.vim/after/syntax/c.vim. > + syn sync fromstart + set foldmethod=syntax + +CH *ch.vim* *ft-ch-syntax* + +C/C++ interpreter. Ch has similar syntax highlighting to C and builds upon +the C syntax file. See |c.vim| for all the settings that are available for C. + +By setting a variable you can tell Vim to use Ch syntax for *.h files, instead +of C or C++: > + :let ch_syntax_for_h = 1 + + +CHILL *chill.vim* *ft-chill-syntax* + +Chill syntax highlighting is similar to C. See |c.vim| for all the settings +that are available. Additionally there is: + +chill_space_errors like c_space_errors +chill_comment_string like c_comment_strings +chill_minlines like c_minlines + + +CHANGELOG *changelog.vim* *ft-changelog-syntax* + +ChangeLog supports highlighting spaces at the start of a line. +If you do not like this, add following line to your .vimrc: > + let g:changelog_spacing_errors = 0 +This works the next time you edit a changelog file. You can also use +"b:changelog_spacing_errors" to set this per buffer (before loading the syntax +file). + +You can change the highlighting used, e.g., to flag the spaces as an error: > + :hi link ChangelogError Error +Or to avoid the highlighting: > + :hi link ChangelogError NONE +This works immediately. + + +CLOJURE *ft-clojure-syntax* + +Setting *g:clojure_fold* enables folding Clojure code via the syntax engine. +Any list, vector, or map that extends over more than one line can be folded +using the standard Vim |fold-commands|. + +Please note that this option does not work with scripts that redefine the +bracket syntax regions, such as rainbow-parentheses plugins. + +This option is off by default. +> + " Default + let g:clojure_fold = 0 +< + +COBOL *cobol.vim* *ft-cobol-syntax* + +COBOL highlighting has different needs for legacy code than it does for fresh +development. This is due to differences in what is being done (maintenance +versus development) and other factors. To enable legacy code highlighting, +add this line to your .vimrc: > + :let cobol_legacy_code = 1 +To disable it again, use this: > + :unlet cobol_legacy_code + + +COLD FUSION *coldfusion.vim* *ft-coldfusion-syntax* + +The ColdFusion has its own version of HTML comments. To turn on ColdFusion +comment highlighting, add the following line to your startup file: > + + :let html_wrong_comments = 1 + +The ColdFusion syntax file is based on the HTML syntax file. + + +CPP *cpp.vim* *ft-cpp-syntax* + +Most of things are same as |ft-c-syntax|. + +Variable Highlight ~ +cpp_no_cpp11 don't highlight C++11 standard items +cpp_no_cpp14 don't highlight C++14 standard items + + +CSH *csh.vim* *ft-csh-syntax* + +This covers the shell named "csh". Note that on some systems tcsh is actually +used. + +Detecting whether a file is csh or tcsh is notoriously hard. Some systems +symlink /bin/csh to /bin/tcsh, making it almost impossible to distinguish +between csh and tcsh. In case VIM guesses wrong you can set the +"filetype_csh" variable. For using csh: *g:filetype_csh* +> + :let g:filetype_csh = "csh" + +For using tcsh: > + + :let g:filetype_csh = "tcsh" + +Any script with a tcsh extension or a standard tcsh filename (.tcshrc, +tcsh.tcshrc, tcsh.login) will have filetype tcsh. All other tcsh/csh scripts +will be classified as tcsh, UNLESS the "filetype_csh" variable exists. If the +"filetype_csh" variable exists, the filetype will be set to the value of the +variable. + + +CYNLIB *cynlib.vim* *ft-cynlib-syntax* + +Cynlib files are C++ files that use the Cynlib class library to enable +hardware modelling and simulation using C++. Typically Cynlib files have a .cc +or a .cpp extension, which makes it very difficult to distinguish them from a +normal C++ file. Thus, to enable Cynlib highlighting for .cc files, add this +line to your .vimrc file: > + + :let cynlib_cyntax_for_cc=1 + +Similarly for cpp files (this extension is only usually used in Windows) > + + :let cynlib_cyntax_for_cpp=1 + +To disable these again, use this: > + + :unlet cynlib_cyntax_for_cc + :unlet cynlib_cyntax_for_cpp +< + +CWEB *cweb.vim* *ft-cweb-syntax* + +Files matching "*.w" could be Progress or cweb. If the automatic detection +doesn't work for you, or you don't edit Progress at all, use this in your +startup vimrc: > + :let filetype_w = "cweb" + + +DESKTOP *desktop.vim* *ft-desktop-syntax* + +Primary goal of this syntax file is to highlight .desktop and .directory files +according to freedesktop.org standard: +http://standards.freedesktop.org/desktop-entry-spec/latest/ +But actually almost none implements this standard fully. Thus it will +highlight all Unix ini files. But you can force strict highlighting according +to standard by placing this in your vimrc file: > + :let enforce_freedesktop_standard = 1 + + +DIFF *diff.vim* + +The diff highlighting normally finds translated headers. This can be slow if +there are very long lines in the file. To disable translations: > + + :let diff_translations = 0 + +Also see |diff-slow|. + + +DIRCOLORS *dircolors.vim* *ft-dircolors-syntax* + +The dircolors utility highlighting definition has one option. It exists to +provide compatibility with the Slackware GNU/Linux distributions version of +the command. It adds a few keywords that are generally ignored by most +versions. On Slackware systems, however, the utility accepts the keywords and +uses them for processing. To enable the Slackware keywords add the following +line to your startup file: > + let dircolors_is_slackware = 1 + + +DOCBOOK *docbk.vim* *ft-docbk-syntax* *docbook* +DOCBOOK XML *docbkxml.vim* *ft-docbkxml-syntax* +DOCBOOK SGML *docbksgml.vim* *ft-docbksgml-syntax* + +There are two types of DocBook files: SGML and XML. To specify what type you +are using the "b:docbk_type" variable should be set. Vim does this for you +automatically if it can recognize the type. When Vim can't guess it the type +defaults to XML. +You can set the type manually: > + :let docbk_type = "sgml" +or: > + :let docbk_type = "xml" +You need to do this before loading the syntax file, which is complicated. +Simpler is setting the filetype to "docbkxml" or "docbksgml": > + :set filetype=docbksgml +or: > + :set filetype=docbkxml + +You can specify the DocBook version: > + :let docbk_ver = 3 +When not set 4 is used. + + +DOSBATCH *dosbatch.vim* *ft-dosbatch-syntax* + +There is one option with highlighting DOS batch files. This covers new +extensions to the Command Interpreter introduced with Windows 2000 and +is controlled by the variable dosbatch_cmdextversion. For Windows NT +this should have the value 1, and for Windows 2000 it should be 2. +Select the version you want with the following line: > + + :let dosbatch_cmdextversion = 1 + +If this variable is not defined it defaults to a value of 2 to support +Windows 2000. + +A second option covers whether *.btm files should be detected as type +"dosbatch" (MS-DOS batch files) or type "btm" (4DOS batch files). The latter +is used by default. You may select the former with the following line: > + + :let g:dosbatch_syntax_for_btm = 1 + +If this variable is undefined or zero, btm syntax is selected. + + +DOXYGEN *doxygen.vim* *doxygen-syntax* + +Doxygen generates code documentation using a special documentation format +(similar to Javadoc). This syntax script adds doxygen highlighting to c, cpp, +idl and php files, and should also work with java. + +There are a few of ways to turn on doxygen formatting. It can be done +explicitly or in a modeline by appending '.doxygen' to the syntax of the file. +Example: > + :set syntax=c.doxygen +or > + // vim:syntax=c.doxygen + +It can also be done automatically for C, C++, C#, IDL and PHP files by setting +the global or buffer-local variable load_doxygen_syntax. This is done by +adding the following to your .vimrc. > + :let g:load_doxygen_syntax=1 + +There are a couple of variables that have an effect on syntax highlighting, and +are to do with non-standard highlighting options. + +Variable Default Effect ~ +g:doxygen_enhanced_color +g:doxygen_enhanced_colour 0 Use non-standard highlighting for + doxygen comments. + +doxygen_my_rendering 0 Disable rendering of HTML bold, italic + and html_my_rendering underline. + +doxygen_javadoc_autobrief 1 Set to 0 to disable javadoc autobrief + colour highlighting. + +doxygen_end_punctuation '[.]' Set to regexp match for the ending + punctuation of brief + +There are also some hilight groups worth mentioning as they can be useful in +configuration. + +Highlight Effect ~ +doxygenErrorComment The colour of an end-comment when missing + punctuation in a code, verbatim or dot section +doxygenLinkError The colour of an end-comment when missing the + \endlink from a \link section. + + +DTD *dtd.vim* *ft-dtd-syntax* + +The DTD syntax highlighting is case sensitive by default. To disable +case-sensitive highlighting, add the following line to your startup file: > + + :let dtd_ignore_case=1 + +The DTD syntax file will highlight unknown tags as errors. If +this is annoying, it can be turned off by setting: > + + :let dtd_no_tag_errors=1 + +before sourcing the dtd.vim syntax file. +Parameter entity names are highlighted in the definition using the +'Type' highlighting group and 'Comment' for punctuation and '%'. +Parameter entity instances are highlighted using the 'Constant' +highlighting group and the 'Type' highlighting group for the +delimiters % and ;. This can be turned off by setting: > + + :let dtd_no_param_entities=1 + +The DTD syntax file is also included by xml.vim to highlight included dtd's. + + +EIFFEL *eiffel.vim* *ft-eiffel-syntax* + +While Eiffel is not case-sensitive, its style guidelines are, and the +syntax highlighting file encourages their use. This also allows to +highlight class names differently. If you want to disable case-sensitive +highlighting, add the following line to your startup file: > + + :let eiffel_ignore_case=1 + +Case still matters for class names and TODO marks in comments. + +Conversely, for even stricter checks, add one of the following lines: > + + :let eiffel_strict=1 + :let eiffel_pedantic=1 + +Setting eiffel_strict will only catch improper capitalization for the +five predefined words "Current", "Void", "Result", "Precursor", and +"NONE", to warn against their accidental use as feature or class names. + +Setting eiffel_pedantic will enforce adherence to the Eiffel style +guidelines fairly rigorously (like arbitrary mixes of upper- and +lowercase letters as well as outdated ways to capitalize keywords). + +If you want to use the lower-case version of "Current", "Void", +"Result", and "Precursor", you can use > + + :let eiffel_lower_case_predef=1 + +instead of completely turning case-sensitive highlighting off. + +Support for ISE's proposed new creation syntax that is already +experimentally handled by some compilers can be enabled by: > + + :let eiffel_ise=1 + +Finally, some vendors support hexadecimal constants. To handle them, add > + + :let eiffel_hex_constants=1 + +to your startup file. + + +EUPHORIA *euphoria3.vim* *euphoria4.vim* *ft-euphoria-syntax* + +Two syntax highlighting files exists for Euphoria. One for Euphoria +version 3.1.1, which is the default syntax highlighting file, and one for +Euphoria version 4.0.5 or later. + +Euphoria version 3.1.1 (http://www.rapideuphoria.com/) is still necessary +for developing applications for the DOS platform, which Euphoria version 4 +(http://www.openeuphoria.org/) does not support. + +The following file extensions are auto-detected as Euphoria file type: + + *.e, *.eu, *.ew, *.ex, *.exu, *.exw + *.E, *.EU, *.EW, *.EX, *.EXU, *.EXW + +To select syntax highlighting file for Euphoria, as well as for +auto-detecting the *.e and *.E file extensions as Euphoria file type, +add the following line to your startup file: > + + :let filetype_euphoria="euphoria3" + + or + + :let filetype_euphoria="euphoria4" + + +ERLANG *erlang.vim* *ft-erlang-syntax* + +Erlang is a functional programming language developed by Ericsson. Files with +the following extensions are recognized as Erlang files: erl, hrl, yaws. + +The BIFs (built-in functions) are highlighted by default. To disable this, +put the following line in your vimrc: > + + :let g:erlang_highlight_bifs = 0 + +To enable highlighting some special atoms, put this in your vimrc: > + + :let g:erlang_highlight_special_atoms = 1 + + +FLEXWIKI *flexwiki.vim* *ft-flexwiki-syntax* + +FlexWiki is an ASP.NET-based wiki package available at http://www.flexwiki.com +NOTE: this site currently doesn't work, on Wikipedia is mentioned that +development stopped in 2009. + +Syntax highlighting is available for the most common elements of FlexWiki +syntax. The associated ftplugin script sets some buffer-local options to make +editing FlexWiki pages more convenient. FlexWiki considers a newline as the +start of a new paragraph, so the ftplugin sets 'tw'=0 (unlimited line length), +'wrap' (wrap long lines instead of using horizontal scrolling), 'linebreak' +(to wrap at a character in 'breakat' instead of at the last char on screen), +and so on. It also includes some keymaps that are disabled by default. + +If you want to enable the keymaps that make "j" and "k" and the cursor keys +move up and down by display lines, add this to your .vimrc: > + :let flexwiki_maps = 1 + + +FORM *form.vim* *ft-form-syntax* + +The coloring scheme for syntax elements in the FORM file uses the default +modes Conditional, Number, Statement, Comment, PreProc, Type, and String, +following the language specifications in 'Symbolic Manipulation with FORM' by +J.A.M. Vermaseren, CAN, Netherlands, 1991. + +If you want include your own changes to the default colors, you have to +redefine the following syntax groups: + + - formConditional + - formNumber + - formStatement + - formHeaderStatement + - formComment + - formPreProc + - formDirective + - formType + - formString + +Note that the form.vim syntax file implements FORM preprocessor commands and +directives per default in the same syntax group. + +A predefined enhanced color mode for FORM is available to distinguish between +header statements and statements in the body of a FORM program. To activate +this mode define the following variable in your vimrc file > + + :let form_enhanced_color=1 + +The enhanced mode also takes advantage of additional color features for a dark +gvim display. Here, statements are colored LightYellow instead of Yellow, and +conditionals are LightBlue for better distinction. + + +FORTRAN *fortran.vim* *ft-fortran-syntax* + +Default highlighting and dialect ~ +Highlighting appropriate for Fortran 2008 is used by default. This choice +should be appropriate for most users most of the time because Fortran 2008 is +almost a superset of previous versions (Fortran 2003, 95, 90, and 77). + +Fortran source code form ~ +Fortran code can be in either fixed or free source form. Note that the +syntax highlighting will not be correct if the form is incorrectly set. + +When you create a new fortran file, the syntax script assumes fixed source +form. If you always use free source form, then > + :let fortran_free_source=1 +in your .vimrc prior to the :syntax on command. If you always use fixed source +form, then > + :let fortran_fixed_source=1 +in your .vimrc prior to the :syntax on command. + +If the form of the source code depends, in a non-standard way, upon the file +extension, then it is most convenient to set fortran_free_source in a ftplugin +file. For more information on ftplugin files, see |ftplugin|. Note that this +will work only if the "filetype plugin indent on" command precedes the "syntax +on" command in your .vimrc file. + +When you edit an existing fortran file, the syntax script will assume free +source form if the fortran_free_source variable has been set, and assumes +fixed source form if the fortran_fixed_source variable has been set. If +neither of these variables have been set, the syntax script attempts to +determine which source form has been used by examining the file extension +using conventions common to the ifort, gfortran, Cray, NAG, and PathScale +compilers (.f, .for, .f77 for fixed-source, .f90, .f95, .f03, .f08 for +free-source). If none of this works, then the script examines the first five +columns of the first 500 lines of your file. If no signs of free source form +are detected, then the file is assumed to be in fixed source form. The +algorithm should work in the vast majority of cases. In some cases, such as a +file that begins with 500 or more full-line comments, the script may +incorrectly decide that the fortran code is in fixed form. If that happens, +just add a non-comment statement beginning anywhere in the first five columns +of the first twenty five lines, save (:w) and then reload (:e!) the file. + +Tabs in fortran files ~ +Tabs are not recognized by the Fortran standards. Tabs are not a good idea in +fixed format fortran source code which requires fixed column boundaries. +Therefore, tabs are marked as errors. Nevertheless, some programmers like +using tabs. If your fortran files contain tabs, then you should set the +variable fortran_have_tabs in your .vimrc with a command such as > + :let fortran_have_tabs=1 +placed prior to the :syntax on command. Unfortunately, the use of tabs will +mean that the syntax file will not be able to detect incorrect margins. + +Syntax folding of fortran files ~ +If you wish to use foldmethod=syntax, then you must first set the variable +fortran_fold with a command such as > + :let fortran_fold=1 +to instruct the syntax script to define fold regions for program units, that +is main programs starting with a program statement, subroutines, function +subprograms, block data subprograms, interface blocks, and modules. If you +also set the variable fortran_fold_conditionals with a command such as > + :let fortran_fold_conditionals=1 +then fold regions will also be defined for do loops, if blocks, and select +case constructs. If you also set the variable +fortran_fold_multilinecomments with a command such as > + :let fortran_fold_multilinecomments=1 +then fold regions will also be defined for three or more consecutive comment +lines. Note that defining fold regions can be slow for large files. + +If fortran_fold, and possibly fortran_fold_conditionals and/or +fortran_fold_multilinecomments, have been set, then vim will fold your file if +you set foldmethod=syntax. Comments or blank lines placed between two program +units are not folded because they are seen as not belonging to any program +unit. + +More precise fortran syntax ~ +If you set the variable fortran_more_precise with a command such as > + :let fortran_more_precise=1 +then the syntax coloring will be more precise but slower. In particular, +statement labels used in do, goto and arithmetic if statements will be +recognized, as will construct names at the end of a do, if, select or forall +construct. + +Non-default fortran dialects ~ +The syntax script supports two Fortran dialects: f08 and F. You will probably +find the default highlighting (f08) satisfactory. A few legacy constructs +deleted or declared obsolescent in the 2008 standard are highlighted as todo +items. + +If you use F, the advantage of setting the dialect appropriately is that +other legacy features excluded from F will be highlighted as todo items and +that free source form will be assumed. + +The dialect can be selected in various ways. If all your fortran files use +the same dialect, set the global variable fortran_dialect in your .vimrc prior +to your syntax on statement. The case-sensitive, permissible values of +fortran_dialect are "f08" or "F". Invalid values of fortran_dialect are +ignored. + +If the dialect depends upon the file extension, then it is most convenient to +set a buffer-local variable in a ftplugin file. For more information on +ftplugin files, see |ftplugin|. For example, if all your fortran files with +an .f90 extension are written in the F subset, your ftplugin file should +contain the code > + let s:extfname = expand("%:e") + if s:extfname ==? "f90" + let b:fortran_dialect="F" + else + unlet! b:fortran_dialect + endif +Note that this will work only if the "filetype plugin indent on" command +precedes the "syntax on" command in your .vimrc file. + +Finer control is necessary if the file extension does not uniquely identify +the dialect. You can override the default dialect, on a file-by-file basis, +by including a comment with the directive "fortran_dialect=xx" (where xx=F or +f08) in one of the first three lines in your file. For example, your older .f +files may be legacy code but your newer ones may be F codes, and you would +identify the latter by including in the first three lines of those files a +Fortran comment of the form > + ! fortran_dialect=F + +For previous versions of the syntax, you may have set fortran_dialect to the +now-obsolete values "f77", "f90", "f95", or "elf". Such settings will be +silently handled as "f08". Users of "elf" may wish to experiment with "F" +instead. + +The syntax/fortran.vim script contains embedded comments that tell you how to +comment and/or uncomment some lines to (a) activate recognition of some +non-standard, vendor-supplied intrinsics and (b) to prevent features deleted +or declared obsolescent in the 2008 standard from being highlighted as todo +items. + +Limitations ~ +Parenthesis checking does not catch too few closing parentheses. Hollerith +strings are not recognized. Some keywords may be highlighted incorrectly +because Fortran90 has no reserved words. + +For further information related to fortran, see |ft-fortran-indent| and +|ft-fortran-plugin|. + + +FVWM CONFIGURATION FILES *fvwm.vim* *ft-fvwm-syntax* + +In order for Vim to recognize Fvwm configuration files that do not match +the patterns *fvwmrc* or *fvwm2rc* , you must put additional patterns +appropriate to your system in your myfiletypes.vim file. For these +patterns, you must set the variable "b:fvwm_version" to the major version +number of Fvwm, and the 'filetype' option to fvwm. + +For example, to make Vim identify all files in /etc/X11/fvwm2/ +as Fvwm2 configuration files, add the following: > + + :au! BufNewFile,BufRead /etc/X11/fvwm2/* let b:fvwm_version = 2 | + \ set filetype=fvwm + +If you'd like Vim to highlight all valid color names, tell it where to +find the color database (rgb.txt) on your system. Do this by setting +"rgb_file" to its location. Assuming your color database is located +in /usr/X11/lib/X11/, you should add the line > + + :let rgb_file = "/usr/X11/lib/X11/rgb.txt" + +to your .vimrc file. + + +GSP *gsp.vim* *ft-gsp-syntax* + +The default coloring style for GSP pages is defined by |html.vim|, and +the coloring for java code (within java tags or inline between backticks) +is defined by |java.vim|. The following HTML groups defined in |html.vim| +are redefined to incorporate and highlight inline java code: + + htmlString + htmlValue + htmlEndTag + htmlTag + htmlTagN + +Highlighting should look fine most of the places where you'd see inline +java code, but in some special cases it may not. To add another HTML +group where you will have inline java code where it does not highlight +correctly, just copy the line you want from |html.vim| and add gspJava +to the contains clause. + +The backticks for inline java are highlighted according to the htmlError +group to make them easier to see. + + +GROFF *groff.vim* *ft-groff-syntax* + +The groff syntax file is a wrapper for |nroff.vim|, see the notes +under that heading for examples of use and configuration. The purpose +of this wrapper is to set up groff syntax extensions by setting the +filetype from a |modeline| or in a personal filetype definitions file +(see |filetype.txt|). + + +HASKELL *haskell.vim* *lhaskell.vim* *ft-haskell-syntax* + +The Haskell syntax files support plain Haskell code as well as literate +Haskell code, the latter in both Bird style and TeX style. The Haskell +syntax highlighting will also highlight C preprocessor directives. + +If you want to highlight delimiter characters (useful if you have a +light-coloured background), add to your .vimrc: > + :let hs_highlight_delimiters = 1 +To treat True and False as keywords as opposed to ordinary identifiers, +add: > + :let hs_highlight_boolean = 1 +To also treat the names of primitive types as keywords: > + :let hs_highlight_types = 1 +And to treat the names of even more relatively common types as keywords: > + :let hs_highlight_more_types = 1 +If you want to highlight the names of debugging functions, put in +your .vimrc: > + :let hs_highlight_debug = 1 + +The Haskell syntax highlighting also highlights C preprocessor +directives, and flags lines that start with # but are not valid +directives as erroneous. This interferes with Haskell's syntax for +operators, as they may start with #. If you want to highlight those +as operators as opposed to errors, put in your .vimrc: > + :let hs_allow_hash_operator = 1 + +The syntax highlighting for literate Haskell code will try to +automatically guess whether your literate Haskell code contains +TeX markup or not, and correspondingly highlight TeX constructs +or nothing at all. You can override this globally by putting +in your .vimrc > + :let lhs_markup = none +for no highlighting at all, or > + :let lhs_markup = tex +to force the highlighting to always try to highlight TeX markup. +For more flexibility, you may also use buffer local versions of +this variable, so e.g. > + :let b:lhs_markup = tex +will force TeX highlighting for a particular buffer. It has to be +set before turning syntax highlighting on for the buffer or +loading a file. + + +HTML *html.vim* *ft-html-syntax* + +The coloring scheme for tags in the HTML file works as follows. + +The <> of opening tags are colored differently than the of a closing tag. +This is on purpose! For opening tags the 'Function' color is used, while for +closing tags the 'Type' color is used (See syntax.vim to check how those are +defined for you) + +Known tag names are colored the same way as statements in C. Unknown tag +names are colored with the same color as the <> or respectively which +makes it easy to spot errors + +Note that the same is true for argument (or attribute) names. Known attribute +names are colored differently than unknown ones. + +Some HTML tags are used to change the rendering of text. The following tags +are recognized by the html.vim syntax coloring file and change the way normal +text is shown: ( is used as an alias for , +while as an alias for ),

-

, , and <A>, but +only if used as a link (that is, it must include a href as in +<A href="somefile.html">). + +If you want to change how such text is rendered, you must redefine the +following syntax groups: + + - htmlBold + - htmlBoldUnderline + - htmlBoldUnderlineItalic + - htmlUnderline + - htmlUnderlineItalic + - htmlItalic + - htmlTitle for titles + - htmlH1 - htmlH6 for headings + +To make this redefinition work you must redefine them all with the exception +of the last two (htmlTitle and htmlH[1-6], which are optional) and define the +following variable in your vimrc (this is due to the order in which the files +are read during initialization) > + :let html_my_rendering=1 + +If you'd like to see an example download mysyntax.vim at +http://www.fleiner.com/vim/download.html + +You can also disable this rendering by adding the following line to your +vimrc file: > + :let html_no_rendering=1 + +HTML comments are rather special (see an HTML reference document for the +details), and the syntax coloring scheme will highlight all errors. +However, if you prefer to use the wrong style (starts with <!-- and +ends with -->) you can define > + :let html_wrong_comments=1 + +JavaScript and Visual Basic embedded inside HTML documents are highlighted as +'Special' with statements, comments, strings and so on colored as in standard +programming languages. Note that only JavaScript and Visual Basic are currently +supported, no other scripting language has been added yet. + +Embedded and inlined cascading style sheets (CSS) are highlighted too. + +There are several html preprocessor languages out there. html.vim has been +written such that it should be trivial to include it. To do so add the +following two lines to the syntax coloring file for that language +(the example comes from the asp.vim file): + + runtime! syntax/html.vim + syn cluster htmlPreproc add=asp + +Now you just need to make sure that you add all regions that contain +the preprocessor language to the cluster htmlPreproc. + + +HTML/OS (by Aestiva) *htmlos.vim* *ft-htmlos-syntax* + +The coloring scheme for HTML/OS works as follows: + +Functions and variable names are the same color by default, because VIM +doesn't specify different colors for Functions and Identifiers. To change +this (which is recommended if you want function names to be recognizable in a +different color) you need to add the following line to either your ~/.vimrc: > + :hi Function term=underline cterm=bold ctermfg=LightGray + +Of course, the ctermfg can be a different color if you choose. + +Another issues that HTML/OS runs into is that there is no special filetype to +signify that it is a file with HTML/OS coding. You can change this by opening +a file and turning on HTML/OS syntax by doing the following: > + :set syntax=htmlos + +Lastly, it should be noted that the opening and closing characters to begin a +block of HTML/OS code can either be << or [[ and >> or ]], respectively. + + +IA64 *ia64.vim* *intel-itanium* *ft-ia64-syntax* + +Highlighting for the Intel Itanium 64 assembly language. See |asm.vim| for +how to recognize this filetype. + +To have *.inc files be recognized as IA64, add this to your .vimrc file: > + :let g:filetype_inc = "ia64" + + +INFORM *inform.vim* *ft-inform-syntax* + +Inform highlighting includes symbols provided by the Inform Library, as +most programs make extensive use of it. If do not wish Library symbols +to be highlighted add this to your vim startup: > + :let inform_highlight_simple=1 + +By default it is assumed that Inform programs are Z-machine targeted, +and highlights Z-machine assembly language symbols appropriately. If +you intend your program to be targeted to a Glulx/Glk environment you +need to add this to your startup sequence: > + :let inform_highlight_glulx=1 + +This will highlight Glulx opcodes instead, and also adds glk() to the +set of highlighted system functions. + +The Inform compiler will flag certain obsolete keywords as errors when +it encounters them. These keywords are normally highlighted as errors +by Vim. To prevent such error highlighting, you must add this to your +startup sequence: > + :let inform_suppress_obsolete=1 + +By default, the language features highlighted conform to Compiler +version 6.30 and Library version 6.11. If you are using an older +Inform development environment, you may with to add this to your +startup sequence: > + :let inform_highlight_old=1 + +IDL *idl.vim* *idl-syntax* + +IDL (Interface Definition Language) files are used to define RPC calls. In +Microsoft land, this is also used for defining COM interfaces and calls. + +IDL's structure is simple enough to permit a full grammar based approach to +rather than using a few heuristics. The result is large and somewhat +repetitive but seems to work. + +There are some Microsoft extensions to idl files that are here. Some of them +are disabled by defining idl_no_ms_extensions. + +The more complex of the extensions are disabled by defining idl_no_extensions. + +Variable Effect ~ + +idl_no_ms_extensions Disable some of the Microsoft specific + extensions +idl_no_extensions Disable complex extensions +idlsyntax_showerror Show IDL errors (can be rather intrusive, but + quite helpful) +idlsyntax_showerror_soft Use softer colours by default for errors + + +JAVA *java.vim* *ft-java-syntax* + +The java.vim syntax highlighting file offers several options: + +In Java 1.0.2 it was never possible to have braces inside parens, so this was +flagged as an error. Since Java 1.1 this is possible (with anonymous +classes), and therefore is no longer marked as an error. If you prefer the old +way, put the following line into your vim startup file: > + :let java_mark_braces_in_parens_as_errors=1 + +All identifiers in java.lang.* are always visible in all classes. To +highlight them use: > + :let java_highlight_java_lang_ids=1 + +You can also highlight identifiers of most standard Java packages if you +download the javaid.vim script at http://www.fleiner.com/vim/download.html. +If you prefer to only highlight identifiers of a certain package, say java.io +use the following: > + :let java_highlight_java_io=1 +Check the javaid.vim file for a list of all the packages that are supported. + +Function names are not highlighted, as the way to find functions depends on +how you write Java code. The syntax file knows two possible ways to highlight +functions: + +If you write function declarations that are always indented by either +a tab, 8 spaces or 2 spaces you may want to set > + :let java_highlight_functions="indent" +However, if you follow the Java guidelines about how functions and classes are +supposed to be named (with respect to upper and lowercase), use > + :let java_highlight_functions="style" +If both options do not work for you, but you would still want function +declarations to be highlighted create your own definitions by changing the +definitions in java.vim or by creating your own java.vim which includes the +original one and then adds the code to highlight functions. + +In Java 1.1 the functions System.out.println() and System.err.println() should +only be used for debugging. Therefore it is possible to highlight debugging +statements differently. To do this you must add the following definition in +your startup file: > + :let java_highlight_debug=1 +The result will be that those statements are highlighted as 'Special' +characters. If you prefer to have them highlighted differently you must define +new highlightings for the following groups.: + Debug, DebugSpecial, DebugString, DebugBoolean, DebugType +which are used for the statement itself, special characters used in debug +strings, strings, boolean constants and types (this, super) respectively. I +have opted to chose another background for those statements. + +Javadoc is a program that takes special comments out of Java program files and +creates HTML pages. The standard configuration will highlight this HTML code +similarly to HTML files (see |html.vim|). You can even add Javascript +and CSS inside this code (see below). There are four differences however: + 1. The title (all characters up to the first '.' which is followed by + some white space or up to the first '@') is colored differently (to change + the color change the group CommentTitle). + 2. The text is colored as 'Comment'. + 3. HTML comments are colored as 'Special' + 4. The special Javadoc tags (@see, @param, ...) are highlighted as specials + and the argument (for @see, @param, @exception) as Function. +To turn this feature off add the following line to your startup file: > + :let java_ignore_javadoc=1 + +If you use the special Javadoc comment highlighting described above you +can also turn on special highlighting for Javascript, visual basic +scripts and embedded CSS (stylesheets). This makes only sense if you +actually have Javadoc comments that include either Javascript or embedded +CSS. The options to use are > + :let java_javascript=1 + :let java_css=1 + :let java_vb=1 + +In order to highlight nested parens with different colors define colors +for javaParen, javaParen1 and javaParen2, for example with > + :hi link javaParen Comment +or > + :hi javaParen ctermfg=blue guifg=#0000ff + +If you notice highlighting errors while scrolling backwards, which are fixed +when redrawing with CTRL-L, try setting the "java_minlines" internal variable +to a larger number: > + :let java_minlines = 50 +This will make the syntax synchronization start 50 lines before the first +displayed line. The default value is 10. The disadvantage of using a larger +number is that redrawing can become slow. + + +LACE *lace.vim* *ft-lace-syntax* + +Lace (Language for Assembly of Classes in Eiffel) is case insensitive, but the +style guide lines are not. If you prefer case insensitive highlighting, just +define the vim variable 'lace_case_insensitive' in your startup file: > + :let lace_case_insensitive=1 + + +LEX *lex.vim* *ft-lex-syntax* + +Lex uses brute-force synchronizing as the "^%%$" section delimiter +gives no clue as to what section follows. Consequently, the value for > + :syn sync minlines=300 +may be changed by the user if s/he is experiencing synchronization +difficulties (such as may happen with large lex files). + + +LIFELINES *lifelines.vim* *ft-lifelines-syntax* + +To highlight deprecated functions as errors, add in your .vimrc: > + + :let g:lifelines_deprecated = 1 +< + +LISP *lisp.vim* *ft-lisp-syntax* + +The lisp syntax highlighting provides two options: > + + g:lisp_instring : if it exists, then "(...)" strings are highlighted + as if the contents of the string were lisp. + Useful for AutoLisp. + g:lisp_rainbow : if it exists and is nonzero, then differing levels + of parenthesization will receive different + highlighting. +< +The g:lisp_rainbow option provides 10 levels of individual colorization for +the parentheses and backquoted parentheses. Because of the quantity of +colorization levels, unlike non-rainbow highlighting, the rainbow mode +specifies its highlighting using ctermfg and guifg, thereby bypassing the +usual colorscheme control using standard highlighting groups. The actual +highlighting used depends on the dark/bright setting (see |'bg'|). + + +LITE *lite.vim* *ft-lite-syntax* + +There are two options for the lite syntax highlighting. + +If you like SQL syntax highlighting inside Strings, use this: > + + :let lite_sql_query = 1 + +For syncing, minlines defaults to 100. If you prefer another value, you can +set "lite_minlines" to the value you desire. Example: > + + :let lite_minlines = 200 + + +LPC *lpc.vim* *ft-lpc-syntax* + +LPC stands for a simple, memory-efficient language: Lars Pensj| C. The +file name of LPC is usually *.c. Recognizing these files as LPC would bother +users writing only C programs. If you want to use LPC syntax in Vim, you +should set a variable in your .vimrc file: > + + :let lpc_syntax_for_c = 1 + +If it doesn't work properly for some particular C or LPC files, use a +modeline. For a LPC file: + + // vim:set ft=lpc: + +For a C file that is recognized as LPC: + + // vim:set ft=c: + +If you don't want to set the variable, use the modeline in EVERY LPC file. + +There are several implementations for LPC, we intend to support most widely +used ones. Here the default LPC syntax is for MudOS series, for MudOS v22 +and before, you should turn off the sensible modifiers, and this will also +assert the new efuns after v22 to be invalid, don't set this variable when +you are using the latest version of MudOS: > + + :let lpc_pre_v22 = 1 + +For LpMud 3.2 series of LPC: > + + :let lpc_compat_32 = 1 + +For LPC4 series of LPC: > + + :let lpc_use_lpc4_syntax = 1 + +For uLPC series of LPC: +uLPC has been developed to Pike, so you should use Pike syntax +instead, and the name of your source file should be *.pike + + +LUA *lua.vim* *ft-lua-syntax* + +The Lua syntax file can be used for versions 4.0, 5.0, 5.1 and 5.2 (5.2 is +the default). You can select one of these versions using the global variables +lua_version and lua_subversion. For example, to activate Lua +5.1 syntax highlighting, set the variables like this: + + :let lua_version = 5 + :let lua_subversion = 1 + + +MAIL *mail.vim* *ft-mail.vim* + +Vim highlights all the standard elements of an email (headers, signatures, +quoted text and URLs / email addresses). In keeping with standard conventions, +signatures begin in a line containing only "--" followed optionally by +whitespaces and end with a newline. + +Vim treats lines beginning with ']', '}', '|', '>' or a word followed by '>' +as quoted text. However Vim highlights headers and signatures in quoted text +only if the text is quoted with '>' (optionally followed by one space). + +By default mail.vim synchronises syntax to 100 lines before the first +displayed line. If you have a slow machine, and generally deal with emails +with short headers, you can change this to a smaller value: > + + :let mail_minlines = 30 + + +MAKE *make.vim* *ft-make-syntax* + +In makefiles, commands are usually highlighted to make it easy for you to spot +errors. However, this may be too much coloring for you. You can turn this +feature off by using: > + + :let make_no_commands = 1 + + +MAPLE *maple.vim* *ft-maple-syntax* + +Maple V, by Waterloo Maple Inc, supports symbolic algebra. The language +supports many packages of functions which are selectively loaded by the user. +The standard set of packages' functions as supplied in Maple V release 4 may be +highlighted at the user's discretion. Users may place in their .vimrc file: > + + :let mvpkg_all= 1 + +to get all package functions highlighted, or users may select any subset by +choosing a variable/package from the table below and setting that variable to +1, also in their .vimrc file (prior to sourcing +$VIMRUNTIME/syntax/syntax.vim). + + Table of Maple V Package Function Selectors > + mv_DEtools mv_genfunc mv_networks mv_process + mv_Galois mv_geometry mv_numapprox mv_simplex + mv_GaussInt mv_grobner mv_numtheory mv_stats + mv_LREtools mv_group mv_orthopoly mv_student + mv_combinat mv_inttrans mv_padic mv_sumtools + mv_combstruct mv_liesymm mv_plots mv_tensor + mv_difforms mv_linalg mv_plottools mv_totorder + mv_finance mv_logic mv_powseries + + +MATHEMATICA *mma.vim* *ft-mma-syntax* *ft-mathematica-syntax* + +Empty *.m files will automatically be presumed to be Matlab files unless you +have the following in your .vimrc: > + + let filetype_m = "mma" + + +MOO *moo.vim* *ft-moo-syntax* + +If you use C-style comments inside expressions and find it mangles your +highlighting, you may want to use extended (slow!) matches for C-style +comments: > + + :let moo_extended_cstyle_comments = 1 + +To disable highlighting of pronoun substitution patterns inside strings: > + + :let moo_no_pronoun_sub = 1 + +To disable highlighting of the regular expression operator '%|', and matching +'%(' and '%)' inside strings: > + + :let moo_no_regexp = 1 + +Unmatched double quotes can be recognized and highlighted as errors: > + + :let moo_unmatched_quotes = 1 + +To highlight builtin properties (.name, .location, .programmer etc.): > + + :let moo_builtin_properties = 1 + +Unknown builtin functions can be recognized and highlighted as errors. If you +use this option, add your own extensions to the mooKnownBuiltinFunction group. +To enable this option: > + + :let moo_unknown_builtin_functions = 1 + +An example of adding sprintf() to the list of known builtin functions: > + + :syn keyword mooKnownBuiltinFunction sprintf contained + + +MSQL *msql.vim* *ft-msql-syntax* + +There are two options for the msql syntax highlighting. + +If you like SQL syntax highlighting inside Strings, use this: > + + :let msql_sql_query = 1 + +For syncing, minlines defaults to 100. If you prefer another value, you can +set "msql_minlines" to the value you desire. Example: > + + :let msql_minlines = 200 + + +NCF *ncf.vim* *ft-ncf-syntax* + +There is one option for NCF syntax highlighting. + +If you want to have unrecognized (by ncf.vim) statements highlighted as +errors, use this: > + + :let ncf_highlight_unknowns = 1 + +If you don't want to highlight these errors, leave it unset. + + +NROFF *nroff.vim* *ft-nroff-syntax* + +The nroff syntax file works with AT&T n/troff out of the box. You need to +activate the GNU groff extra features included in the syntax file before you +can use them. + +For example, Linux and BSD distributions use groff as their default text +processing package. In order to activate the extra syntax highlighting +features for groff, add the following option to your start-up files: > + + :let b:nroff_is_groff = 1 + +Groff is different from the old AT&T n/troff that you may still find in +Solaris. Groff macro and request names can be longer than 2 characters and +there are extensions to the language primitives. For example, in AT&T troff +you access the year as a 2-digit number with the request \(yr. In groff you +can use the same request, recognized for compatibility, or you can use groff's +native syntax, \[yr]. Furthermore, you can use a 4-digit year directly: +\[year]. Macro requests can be longer than 2 characters, for example, GNU mm +accepts the requests ".VERBON" and ".VERBOFF" for creating verbatim +environments. + +In order to obtain the best formatted output g/troff can give you, you should +follow a few simple rules about spacing and punctuation. + +1. Do not leave empty spaces at the end of lines. + +2. Leave one space and one space only after an end-of-sentence period, + exclamation mark, etc. + +3. For reasons stated below, it is best to follow all period marks with a + carriage return. + +The reason behind these unusual tips is that g/n/troff have a line breaking +algorithm that can be easily upset if you don't follow the rules given above. + +Unlike TeX, troff fills text line-by-line, not paragraph-by-paragraph and, +furthermore, it does not have a concept of glue or stretch, all horizontal and +vertical space input will be output as is. + +Therefore, you should be careful about not using more space between sentences +than you intend to have in your final document. For this reason, the common +practice is to insert a carriage return immediately after all punctuation +marks. If you want to have "even" text in your final processed output, you +need to maintain regular spacing in the input text. To mark both trailing +spaces and two or more spaces after a punctuation as an error, use: > + + :let nroff_space_errors = 1 + +Another technique to detect extra spacing and other errors that will interfere +with the correct typesetting of your file, is to define an eye-catching +highlighting definition for the syntax groups "nroffDefinition" and +"nroffDefSpecial" in your configuration files. For example: > + + hi def nroffDefinition term=italic cterm=italic gui=reverse + hi def nroffDefSpecial term=italic,bold cterm=italic,bold + \ gui=reverse,bold + +If you want to navigate preprocessor entries in your source file as easily as +with section markers, you can activate the following option in your .vimrc +file: > + + let b:preprocs_as_sections = 1 + +As well, the syntax file adds an extra paragraph marker for the extended +paragraph macro (.XP) in the ms package. + +Finally, there is a |groff.vim| syntax file that can be used for enabling +groff syntax highlighting either on a file basis or globally by default. + + +OCAML *ocaml.vim* *ft-ocaml-syntax* + +The OCaml syntax file handles files having the following prefixes: .ml, +.mli, .mll and .mly. By setting the following variable > + + :let ocaml_revised = 1 + +you can switch from standard OCaml-syntax to revised syntax as supported +by the camlp4 preprocessor. Setting the variable > + + :let ocaml_noend_error = 1 + +prevents highlighting of "end" as error, which is useful when sources +contain very long structures that Vim does not synchronize anymore. + + +PAPP *papp.vim* *ft-papp-syntax* + +The PApp syntax file handles .papp files and, to a lesser extend, .pxml +and .pxsl files which are all a mixture of perl/xml/html/other using xml +as the top-level file format. By default everything inside phtml or pxml +sections is treated as a string with embedded preprocessor commands. If +you set the variable: > + + :let papp_include_html=1 + +in your startup file it will try to syntax-hilight html code inside phtml +sections, but this is relatively slow and much too colourful to be able to +edit sensibly. ;) + +The newest version of the papp.vim syntax file can usually be found at +http://papp.plan9.de. + + +PASCAL *pascal.vim* *ft-pascal-syntax* + +Files matching "*.p" could be Progress or Pascal. If the automatic detection +doesn't work for you, or you don't edit Progress at all, use this in your +startup vimrc: > + + :let filetype_p = "pascal" + +The Pascal syntax file has been extended to take into account some extensions +provided by Turbo Pascal, Free Pascal Compiler and GNU Pascal Compiler. +Delphi keywords are also supported. By default, Turbo Pascal 7.0 features are +enabled. If you prefer to stick with the standard Pascal keywords, add the +following line to your startup file: > + + :let pascal_traditional=1 + +To switch on Delphi specific constructions (such as one-line comments, +keywords, etc): > + + :let pascal_delphi=1 + + +The option pascal_symbol_operator controls whether symbol operators such as +, +*, .., etc. are displayed using the Operator color or not. To colorize symbol +operators, add the following line to your startup file: > + + :let pascal_symbol_operator=1 + +Some functions are highlighted by default. To switch it off: > + + :let pascal_no_functions=1 + +Furthermore, there are specific variables for some compilers. Besides +pascal_delphi, there are pascal_gpc and pascal_fpc. Default extensions try to +match Turbo Pascal. > + + :let pascal_gpc=1 + +or > + + :let pascal_fpc=1 + +To ensure that strings are defined on a single line, you can define the +pascal_one_line_string variable. > + + :let pascal_one_line_string=1 + +If you dislike <Tab> chars, you can set the pascal_no_tabs variable. Tabs +will be highlighted as Error. > + + :let pascal_no_tabs=1 + + + +PERL *perl.vim* *ft-perl-syntax* + +There are a number of possible options to the perl syntax highlighting. + +Inline POD highlighting is now turned on by default. If you don't wish +to have the added complexity of highlighting POD embedded within Perl +files, you may set the 'perl_include_pod' option to 0: > + + :let perl_include_pod = 0 + +To reduce the complexity of parsing (and increase performance) you can switch +off two elements in the parsing of variable names and contents. > + +To handle package references in variable and function names not differently +from the rest of the name (like 'PkgName::' in '$PkgName::VarName'): > + + :let perl_no_scope_in_variables = 1 + +(In Vim 6.x it was the other way around: "perl_want_scope_in_variables" +enabled it.) + +If you do not want complex things like '@{${"foo"}}' to be parsed: > + + :let perl_no_extended_vars = 1 + +(In Vim 6.x it was the other way around: "perl_extended_vars" enabled it.) + +The coloring strings can be changed. By default strings and qq friends will be +highlighted like the first line. If you set the variable +perl_string_as_statement, it will be highlighted as in the second line. + + "hello world!"; qq|hello world|; + ^^^^^^^^^^^^^^NN^^^^^^^^^^^^^^^N (unlet perl_string_as_statement) + S^^^^^^^^^^^^SNNSSS^^^^^^^^^^^SN (let perl_string_as_statement) + +(^ = perlString, S = perlStatement, N = None at all) + +The syncing has 3 options. The first two switch off some triggering of +synchronization and should only be needed in case it fails to work properly. +If while scrolling all of a sudden the whole screen changes color completely +then you should try and switch off one of those. Let me know if you can figure +out the line that causes the mistake. + +One triggers on "^\s*sub\s*" and the other on "^[$@%]" more or less. > + + :let perl_no_sync_on_sub + :let perl_no_sync_on_global_var + +Below you can set the maximum distance VIM should look for starting points for +its attempts in syntax highlighting. > + + :let perl_sync_dist = 100 + +If you want to use folding with perl, set perl_fold: > + + :let perl_fold = 1 + +If you want to fold blocks in if statements, etc. as well set the following: > + + :let perl_fold_blocks = 1 + +Subroutines are folded by default if 'perl_fold' is set. If you do not want +this, you can set 'perl_nofold_subs': > + + :let perl_nofold_subs = 1 + +Anonymous subroutines are not folded by default; you may enable their folding +via 'perl_fold_anonymous_subs': > + + :let perl_fold_anonymous_subs = 1 + +Packages are also folded by default if 'perl_fold' is set. To disable this +behavior, set 'perl_nofold_packages': > + + :let perl_nofold_packages = 1 + +PHP3 and PHP4 *php.vim* *php3.vim* *ft-php-syntax* *ft-php3-syntax* + +[note: previously this was called "php3", but since it now also supports php4 +it has been renamed to "php"] + +There are the following options for the php syntax highlighting. + +If you like SQL syntax highlighting inside Strings: > + + let php_sql_query = 1 + +For highlighting the Baselib methods: > + + let php_baselib = 1 + +Enable HTML syntax highlighting inside strings: > + + let php_htmlInStrings = 1 + +Using the old colorstyle: > + + let php_oldStyle = 1 + +Enable highlighting ASP-style short tags: > + + let php_asp_tags = 1 + +Disable short tags: > + + let php_noShortTags = 1 + +For highlighting parent error ] or ): > + + let php_parent_error_close = 1 + +For skipping a php end tag, if there exists an open ( or [ without a closing +one: > + + let php_parent_error_open = 1 + +Enable folding for classes and functions: > + + let php_folding = 1 + +Selecting syncing method: > + + let php_sync_method = x + +x = -1 to sync by search (default), +x > 0 to sync at least x lines backwards, +x = 0 to sync from start. + + +PLAINTEX *plaintex.vim* *ft-plaintex-syntax* + +TeX is a typesetting language, and plaintex is the file type for the "plain" +variant of TeX. If you never want your *.tex files recognized as plain TeX, +see |ft-tex-plugin|. + +This syntax file has the option > + + let g:plaintex_delimiters = 1 + +if you want to highlight brackets "[]" and braces "{}". + + +PPWIZARD *ppwiz.vim* *ft-ppwiz-syntax* + +PPWizard is a preprocessor for HTML and OS/2 INF files + +This syntax file has the options: + +- ppwiz_highlight_defs : determines highlighting mode for PPWizard's + definitions. Possible values are + + ppwiz_highlight_defs = 1 : PPWizard #define statements retain the + colors of their contents (e.g. PPWizard macros and variables) + + ppwiz_highlight_defs = 2 : preprocessor #define and #evaluate + statements are shown in a single color with the exception of line + continuation symbols + + The default setting for ppwiz_highlight_defs is 1. + +- ppwiz_with_html : If the value is 1 (the default), highlight literal + HTML code; if 0, treat HTML code like ordinary text. + + +PHTML *phtml.vim* *ft-phtml-syntax* + +There are two options for the phtml syntax highlighting. + +If you like SQL syntax highlighting inside Strings, use this: > + + :let phtml_sql_query = 1 + +For syncing, minlines defaults to 100. If you prefer another value, you can +set "phtml_minlines" to the value you desire. Example: > + + :let phtml_minlines = 200 + + +POSTSCRIPT *postscr.vim* *ft-postscr-syntax* + +There are several options when it comes to highlighting PostScript. + +First which version of the PostScript language to highlight. There are +currently three defined language versions, or levels. Level 1 is the original +and base version, and includes all extensions prior to the release of level 2. +Level 2 is the most common version around, and includes its own set of +extensions prior to the release of level 3. Level 3 is currently the highest +level supported. You select which level of the PostScript language you want +highlighted by defining the postscr_level variable as follows: > + + :let postscr_level=2 + +If this variable is not defined it defaults to 2 (level 2) since this is +the most prevalent version currently. + +Note, not all PS interpreters will support all language features for a +particular language level. In particular the %!PS-Adobe-3.0 at the start of +PS files does NOT mean the PostScript present is level 3 PostScript! + +If you are working with Display PostScript, you can include highlighting of +Display PS language features by defining the postscr_display variable as +follows: > + + :let postscr_display=1 + +If you are working with Ghostscript, you can include highlighting of +Ghostscript specific language features by defining the variable +postscr_ghostscript as follows: > + + :let postscr_ghostscript=1 + +PostScript is a large language, with many predefined elements. While it +useful to have all these elements highlighted, on slower machines this can +cause Vim to slow down. In an attempt to be machine friendly font names and +character encodings are not highlighted by default. Unless you are working +explicitly with either of these this should be ok. If you want them to be +highlighted you should set one or both of the following variables: > + + :let postscr_fonts=1 + :let postscr_encodings=1 + +There is a stylistic option to the highlighting of and, or, and not. In +PostScript the function of these operators depends on the types of their +operands - if the operands are booleans then they are the logical operators, +if they are integers then they are binary operators. As binary and logical +operators can be highlighted differently they have to be highlighted one way +or the other. By default they are treated as logical operators. They can be +highlighted as binary operators by defining the variable +postscr_andornot_binary as follows: > + + :let postscr_andornot_binary=1 +< + + *ptcap.vim* *ft-printcap-syntax* +PRINTCAP + TERMCAP *ft-ptcap-syntax* *ft-termcap-syntax* + +This syntax file applies to the printcap and termcap databases. + +In order for Vim to recognize printcap/termcap files that do not match +the patterns *printcap*, or *termcap*, you must put additional patterns +appropriate to your system in your |myfiletypefile| file. For these +patterns, you must set the variable "b:ptcap_type" to either "print" or +"term", and then the 'filetype' option to ptcap. + +For example, to make Vim identify all files in /etc/termcaps/ as termcap +files, add the following: > + + :au BufNewFile,BufRead /etc/termcaps/* let b:ptcap_type = "term" | + \ set filetype=ptcap + +If you notice highlighting errors while scrolling backwards, which +are fixed when redrawing with CTRL-L, try setting the "ptcap_minlines" +internal variable to a larger number: > + + :let ptcap_minlines = 50 + +(The default is 20 lines.) + + +PROGRESS *progress.vim* *ft-progress-syntax* + +Files matching "*.w" could be Progress or cweb. If the automatic detection +doesn't work for you, or you don't edit cweb at all, use this in your +startup vimrc: > + :let filetype_w = "progress" +The same happens for "*.i", which could be assembly, and "*.p", which could be +Pascal. Use this if you don't use assembly and Pascal: > + :let filetype_i = "progress" + :let filetype_p = "progress" + + +PYTHON *python.vim* *ft-python-syntax* + +There are six options to control Python syntax highlighting. + +For highlighted numbers: > + :let python_no_number_highlight = 1 + +For highlighted builtin functions: > + :let python_no_builtin_highlight = 1 + +For highlighted standard exceptions: > + :let python_no_exception_highlight = 1 + +For highlighted doctests and code inside: > + :let python_no_doctest_highlight = 1 +or > + :let python_no_doctest_code_highlight = 1 +(first option implies second one). + +For highlighted trailing whitespace and mix of spaces and tabs: > + :let python_space_error_highlight = 1 + +If you want all possible Python highlighting (the same as setting the +preceding last option and unsetting all other ones): > + :let python_highlight_all = 1 + +Note: only existence of these options matter, not their value. You can replace + 1 above with anything. + + +QUAKE *quake.vim* *ft-quake-syntax* + +The Quake syntax definition should work for most any FPS (First Person +Shooter) based on one of the Quake engines. However, the command names vary +a bit between the three games (Quake, Quake 2, and Quake 3 Arena) so the +syntax definition checks for the existence of three global variables to allow +users to specify what commands are legal in their files. The three variables +can be set for the following effects: + +set to highlight commands only available in Quake: > + :let quake_is_quake1 = 1 + +set to highlight commands only available in Quake 2: > + :let quake_is_quake2 = 1 + +set to highlight commands only available in Quake 3 Arena: > + :let quake_is_quake3 = 1 + +Any combination of these three variables is legal, but might highlight more +commands than are actually available to you by the game. + + +READLINE *readline.vim* *ft-readline-syntax* + +The readline library is primarily used by the BASH shell, which adds quite a +few commands and options to the ones already available. To highlight these +items as well you can add the following to your |vimrc| or just type it in the +command line before loading a file with the readline syntax: > + let readline_has_bash = 1 + +This will add highlighting for the commands that BASH (version 2.05a and +later, and part earlier) adds. + + +RESTRUCTURED TEXT *rst.vim* *ft-rst-syntax* + +You may set what syntax definitions should be used for code blocks via + let rst_syntax_code_list = ['vim', 'lisp', ...] + + +REXX *rexx.vim* *ft-rexx-syntax* + +If you notice highlighting errors while scrolling backwards, which are fixed +when redrawing with CTRL-L, try setting the "rexx_minlines" internal variable +to a larger number: > + :let rexx_minlines = 50 +This will make the syntax synchronization start 50 lines before the first +displayed line. The default value is 10. The disadvantage of using a larger +number is that redrawing can become slow. + +Vim tries to guess what type a ".r" file is. If it can't be detected (from +comment lines), the default is "r". To make the default rexx add this line to +your .vimrc: *g:filetype_r* +> + :let g:filetype_r = "r" + + +RUBY *ruby.vim* *ft-ruby-syntax* + +There are a number of options to the Ruby syntax highlighting. + +By default, the "end" keyword is colorized according to the opening statement +of the block it closes. While useful, this feature can be expensive; if you +experience slow redrawing (or you are on a terminal with poor color support) +you may want to turn it off by defining the "ruby_no_expensive" variable: > + + :let ruby_no_expensive = 1 +< +In this case the same color will be used for all control keywords. + +If you do want this feature enabled, but notice highlighting errors while +scrolling backwards, which are fixed when redrawing with CTRL-L, try setting +the "ruby_minlines" variable to a value larger than 50: > + + :let ruby_minlines = 100 +< +Ideally, this value should be a number of lines large enough to embrace your +largest class or module. + +Highlighting of special identifiers can be disabled by removing the +rubyIdentifier highlighting: > + + :hi link rubyIdentifier NONE +< +This will prevent highlighting of special identifiers like "ConstantName", +"$global_var", "@@class_var", "@instance_var", "| block_param |", and +":symbol". + +Significant methods of Kernel, Module and Object are highlighted by default. +This can be disabled by defining "ruby_no_special_methods": > + + :let ruby_no_special_methods = 1 +< +This will prevent highlighting of important methods such as "require", "attr", +"private", "raise" and "proc". + +Ruby operators can be highlighted. This is enabled by defining +"ruby_operators": > + + :let ruby_operators = 1 +< +Whitespace errors can be highlighted by defining "ruby_space_errors": > + + :let ruby_space_errors = 1 +< +This will highlight trailing whitespace and tabs preceded by a space character +as errors. This can be refined by defining "ruby_no_trail_space_error" and +"ruby_no_tab_space_error" which will ignore trailing whitespace and tabs after +spaces respectively. + +Folding can be enabled by defining "ruby_fold": > + + :let ruby_fold = 1 +< +This will set the 'foldmethod' option to "syntax" and allow folding of +classes, modules, methods, code blocks, heredocs and comments. + +Folding of multiline comments can be disabled by defining +"ruby_no_comment_fold": > + + :let ruby_no_comment_fold = 1 +< + +SCHEME *scheme.vim* *ft-scheme-syntax* + +By default only R5RS keywords are highlighted and properly indented. + +MzScheme-specific stuff will be used if b:is_mzscheme or g:is_mzscheme +variables are defined. + +Also scheme.vim supports keywords of the Chicken Scheme->C compiler. Define +b:is_chicken or g:is_chicken, if you need them. + + +SDL *sdl.vim* *ft-sdl-syntax* + +The SDL highlighting probably misses a few keywords, but SDL has so many +of them it's almost impossibly to cope. + +The new standard, SDL-2000, specifies that all identifiers are +case-sensitive (which was not so before), and that all keywords can be +used either completely lowercase or completely uppercase. To have the +highlighting reflect this, you can set the following variable: > + :let sdl_2000=1 + +This also sets many new keywords. If you want to disable the old +keywords, which is probably a good idea, use: > + :let SDL_no_96=1 + + +The indentation is probably also incomplete, but right now I am very +satisfied with it for my own projects. + + +SED *sed.vim* *ft-sed-syntax* + +To make tabs stand out from regular blanks (accomplished by using Todo +highlighting on the tabs), define "highlight_sedtabs" by putting > + + :let highlight_sedtabs = 1 + +in the vimrc file. (This special highlighting only applies for tabs +inside search patterns, replacement texts, addresses or text included +by an Append/Change/Insert command.) If you enable this option, it is +also a good idea to set the tab width to one character; by doing that, +you can easily count the number of tabs in a string. + +Bugs: + + The transform command (y) is treated exactly like the substitute + command. This means that, as far as this syntax file is concerned, + transform accepts the same flags as substitute, which is wrong. + (Transform accepts no flags.) I tolerate this bug because the + involved commands need very complex treatment (95 patterns, one for + each plausible pattern delimiter). + + +SGML *sgml.vim* *ft-sgml-syntax* + +The coloring scheme for tags in the SGML file works as follows. + +The <> of opening tags are colored differently than the </> of a closing tag. +This is on purpose! For opening tags the 'Function' color is used, while for +closing tags the 'Type' color is used (See syntax.vim to check how those are +defined for you) + +Known tag names are colored the same way as statements in C. Unknown tag +names are not colored which makes it easy to spot errors. + +Note that the same is true for argument (or attribute) names. Known attribute +names are colored differently than unknown ones. + +Some SGML tags are used to change the rendering of text. The following tags +are recognized by the sgml.vim syntax coloring file and change the way normal +text is shown: <varname> <emphasis> <command> <function> <literal> +<replaceable> <ulink> and <link>. + +If you want to change how such text is rendered, you must redefine the +following syntax groups: + + - sgmlBold + - sgmlBoldItalic + - sgmlUnderline + - sgmlItalic + - sgmlLink for links + +To make this redefinition work you must redefine them all and define the +following variable in your vimrc (this is due to the order in which the files +are read during initialization) > + let sgml_my_rendering=1 + +You can also disable this rendering by adding the following line to your +vimrc file: > + let sgml_no_rendering=1 + +(Adapted from the html.vim help text by Claudio Fleiner <claudio@fleiner.com>) + + +SH *sh.vim* *ft-sh-syntax* *ft-bash-syntax* *ft-ksh-syntax* + +This covers the "normal" Unix (Bourne) sh, bash and the Korn shell. + +Vim attempts to determine which shell type is in use by specifying that +various filenames are of specific types: > + + ksh : .kshrc* *.ksh + bash: .bashrc* bashrc bash.bashrc .bash_profile* *.bash +< +If none of these cases pertain, then the first line of the file is examined +(ex. /bin/sh /bin/ksh /bin/bash). If the first line specifies a shelltype, +then that shelltype is used. However some files (ex. .profile) are known to +be shell files but the type is not apparent. Furthermore, on many systems +sh is symbolically linked to "bash" (Linux, Windows+cygwin) or "ksh" (Posix). + +One may specify a global default by instantiating one of the following three +variables in your <.vimrc>: + + ksh: > + let g:is_kornshell = 1 +< posix: (using this is the same as setting is_kornshell to 1) > + let g:is_posix = 1 +< bash: > + let g:is_bash = 1 +< sh: (default) Bourne shell > + let g:is_sh = 1 + +If there's no "#! ..." line, and the user hasn't availed himself/herself of a +default sh.vim syntax setting as just shown, then syntax/sh.vim will assume +the Bourne shell syntax. No need to quote RFCs or market penetration +statistics in error reports, please -- just select the default version of the +sh your system uses in your <.vimrc>. + +The syntax/sh.vim file provides several levels of syntax-based folding: > + + let g:sh_fold_enabled= 0 (default, no syntax folding) + let g:sh_fold_enabled= 1 (enable function folding) + let g:sh_fold_enabled= 2 (enable heredoc folding) + let g:sh_fold_enabled= 4 (enable if/do/for folding) +> +then various syntax items (HereDocuments and function bodies) become +syntax-foldable (see |:syn-fold|). You also may add these together +to get multiple types of folding: > + + let g:sh_fold_enabled= 3 (enables function and heredoc folding) + +If you notice highlighting errors while scrolling backwards which are fixed +when one redraws with CTRL-L, try setting the "sh_minlines" internal variable +to a larger number. Example: > + + let sh_minlines = 500 + +This will make syntax synchronization start 500 lines before the first +displayed line. The default value is 200. The disadvantage of using a larger +number is that redrawing can become slow. + +If you don't have much to synchronize on, displaying can be very slow. To +reduce this, the "sh_maxlines" internal variable can be set. Example: > + + let sh_maxlines = 100 +< +The default is to use the twice sh_minlines. Set it to a smaller number to +speed up displaying. The disadvantage is that highlight errors may appear. + + *g:sh_isk* *g:sh_noisk* +The shell languages appear to let "." be part of words, commands, etc; +consequently it should be in the isk for sh.vim. As of v116 of syntax/sh.vim, +syntax/sh.vim will append the "." to |'iskeyword'| by default; you may control +this behavior with: > + let g:sh_isk = '..whatever characters you want as part of iskeyword' + let g:sh_noisk= 1 " otherwise, if this exists, the isk will NOT chg +< + *sh-embed* *sh-awk* + Sh: EMBEDDING LANGUAGES~ + +You may wish to embed languages into sh. I'll give an example courtesy of +Lorance Stinson on how to do this with awk as an example. Put the following +file into $HOME/.vim/after/syntax/sh/awkembed.vim: > + + " AWK Embedding: {{{1 + " ============== + " Shamelessly ripped from aspperl.vim by Aaron Hope. + if exists("b:current_syntax") + unlet b:current_syntax + endif + syn include @AWKScript syntax/awk.vim + syn region AWKScriptCode matchgroup=AWKCommand start=+[=\\]\@<!'+ skip=+\\'+ end=+'+ contains=@AWKScript contained + syn region AWKScriptEmbedded matchgroup=AWKCommand start=+\<awk\>+ skip=+\\$+ end=+[=\\]\@<!'+me=e-1 contains=@shIdList,@shExprList2 nextgroup=AWKScriptCode + syn cluster shCommandSubList add=AWKScriptEmbedded + hi def link AWKCommand Type +< +This code will then let the awk code in the single quotes: > + awk '...awk code here...' +be highlighted using the awk highlighting syntax. Clearly this may be +extended to other languages. + + +SPEEDUP *spup.vim* *ft-spup-syntax* +(AspenTech plant simulator) + +The Speedup syntax file has some options: + +- strict_subsections : If this variable is defined, only keywords for + sections and subsections will be highlighted as statements but not + other keywords (like WITHIN in the OPERATION section). + +- highlight_types : Definition of this variable causes stream types + like temperature or pressure to be highlighted as Type, not as a + plain Identifier. Included are the types that are usually found in + the DECLARE section; if you defined own types, you have to include + them in the syntax file. + +- oneline_comments : this value ranges from 1 to 3 and determines the + highlighting of # style comments. + + oneline_comments = 1 : allow normal Speedup code after an even + number of #s. + + oneline_comments = 2 : show code starting with the second # as + error. This is the default setting. + + oneline_comments = 3 : show the whole line as error if it contains + more than one #. + +Since especially OPERATION sections tend to become very large due to +PRESETting variables, syncing may be critical. If your computer is +fast enough, you can increase minlines and/or maxlines near the end of +the syntax file. + + +SQL *sql.vim* *ft-sql-syntax* + *sqlinformix.vim* *ft-sqlinformix-syntax* + *sqlanywhere.vim* *ft-sqlanywhere-syntax* + +While there is an ANSI standard for SQL, most database engines add their own +custom extensions. Vim currently supports the Oracle and Informix dialects of +SQL. Vim assumes "*.sql" files are Oracle SQL by default. + +Vim currently has SQL support for a variety of different vendors via syntax +scripts. You can change Vim's default from Oracle to any of the current SQL +supported types. You can also easily alter the SQL dialect being used on a +buffer by buffer basis. + +For more detailed instructions see |ft_sql.txt|. + + +TCSH *tcsh.vim* *ft-tcsh-syntax* + +This covers the shell named "tcsh". It is a superset of csh. See |csh.vim| +for how the filetype is detected. + +Tcsh does not allow \" in strings unless the "backslash_quote" shell variable +is set. If you want VIM to assume that no backslash quote constructs exist add +this line to your .vimrc: > + + :let tcsh_backslash_quote = 0 + +If you notice highlighting errors while scrolling backwards, which are fixed +when redrawing with CTRL-L, try setting the "tcsh_minlines" internal variable +to a larger number: > + + :let tcsh_minlines = 1000 + +This will make the syntax synchronization start 1000 lines before the first +displayed line. If you set "tcsh_minlines" to "fromstart", then +synchronization is done from the start of the file. The default value for +tcsh_minlines is 100. The disadvantage of using a larger number is that +redrawing can become slow. + + +TEX *tex.vim* *ft-tex-syntax* *latex-syntax* + + Tex Contents~ + Tex: Want Syntax Folding? |tex-folding| + Tex: No Spell Checking Wanted |g:tex_nospell| + Tex: Don't Want Spell Checking In Comments? |tex-nospell| + Tex: Want Spell Checking in Verbatim Zones? |tex-verb| + Tex: Run-on Comments or MathZones |tex-runon| + Tex: Slow Syntax Highlighting? |tex-slow| + Tex: Want To Highlight More Commands? |tex-morecommands| + Tex: Excessive Error Highlighting? |tex-error| + Tex: Need a new Math Group? |tex-math| + Tex: Starting a New Style? |tex-style| + Tex: Taking Advantage of Conceal Mode |tex-conceal| + Tex: Selective Conceal Mode |g:tex_conceal| + Tex: Controlling iskeyword |g:tex_isk| + Tex: Fine Subscript and Superscript Control |tex-supersub| + + *tex-folding* *g:tex_fold_enabled* + Tex: Want Syntax Folding? ~ + +As of version 28 of <syntax/tex.vim>, syntax-based folding of parts, chapters, +sections, subsections, etc are supported. Put > + let g:tex_fold_enabled=1 +in your <.vimrc>, and :set fdm=syntax. I suggest doing the latter via a +modeline at the end of your LaTeX file: > + % vim: fdm=syntax +If your system becomes too slow, then you might wish to look into > + https://vimhelp.appspot.com/vim_faq.txt.html#faq-29.7 +< + *g:tex_nospell* + Tex: No Spell Checking Wanted~ + +If you don't want spell checking anywhere in your LaTeX document, put > + let g:tex_nospell=1 +into your .vimrc. If you merely wish to suppress spell checking inside +comments only, see |g:tex_comment_nospell|. + + *tex-nospell* *g:tex_comment_nospell* + Tex: Don't Want Spell Checking In Comments? ~ + +Some folks like to include things like source code in comments and so would +prefer that spell checking be disabled in comments in LaTeX files. To do +this, put the following in your <.vimrc>: > + let g:tex_comment_nospell= 1 +If you want to suppress spell checking everywhere inside your LaTeX document, +see |g:tex_nospell|. + + *tex-verb* *g:tex_verbspell* + Tex: Want Spell Checking in Verbatim Zones?~ + +Often verbatim regions are used for things like source code; seldom does +one want source code spell-checked. However, for those of you who do +want your verbatim zones spell-checked, put the following in your <.vimrc>: > + let g:tex_verbspell= 1 +< + *tex-runon* *tex-stopzone* + Tex: Run-on Comments or MathZones ~ + +The <syntax/tex.vim> highlighting supports TeX, LaTeX, and some AmsTeX. The +highlighting supports three primary zones/regions: normal, texZone, and +texMathZone. Although considerable effort has been made to have these zones +terminate properly, zones delineated by $..$ and $$..$$ cannot be synchronized +as there's no difference between start and end patterns. Consequently, a +special "TeX comment" has been provided > + %stopzone +which will forcibly terminate the highlighting of either a texZone or a +texMathZone. + + *tex-slow* *tex-sync* + Tex: Slow Syntax Highlighting? ~ + +If you have a slow computer, you may wish to reduce the values for > + :syn sync maxlines=200 + :syn sync minlines=50 +(especially the latter). If your computer is fast, you may wish to +increase them. This primarily affects synchronizing (i.e. just what group, +if any, is the text at the top of the screen supposed to be in?). + +Another cause of slow highlighting is due to syntax-driven folding; see +|tex-folding| for a way around this. + + *g:tex_fast* + +Finally, if syntax highlighting is still too slow, you may set > + + :let g:tex_fast= "" + +in your .vimrc. Used this way, the g:tex_fast variable causes the syntax +highlighting script to avoid defining any regions and associated +synchronization. The result will be much faster syntax highlighting; the +price: you will no longer have as much highlighting or any syntax-based +folding, and you will be missing syntax-based error checking. + +You may decide that some syntax is acceptable; you may use the following table +selectively to enable just some syntax highlighting: > + + b : allow bold and italic syntax + c : allow texComment syntax + m : allow texMatcher syntax (ie. {...} and [...]) + M : allow texMath syntax + p : allow parts, chapter, section, etc syntax + r : allow texRefZone syntax (nocite, bibliography, label, pageref, eqref) + s : allow superscript/subscript regions + S : allow texStyle syntax + v : allow verbatim syntax + V : allow texNewEnv and texNewCmd syntax +< +As an example, let g:tex_fast= "M" will allow math-associated highlighting +but suppress all the other region-based syntax highlighting. +(also see: |g:tex_conceal| and |tex-supersub|) + + *tex-morecommands* *tex-package* + Tex: Want To Highlight More Commands? ~ + +LaTeX is a programmable language, and so there are thousands of packages full +of specialized LaTeX commands, syntax, and fonts. If you're using such a +package you'll often wish that the distributed syntax/tex.vim would support +it. However, clearly this is impractical. So please consider using the +techniques in |mysyntaxfile-add| to extend or modify the highlighting provided +by syntax/tex.vim. Please consider uploading any extensions that you write, +which typically would go in $HOME/after/syntax/tex/[pkgname].vim, to +http://vim.sf.net/. + + *tex-error* *g:tex_no_error* + Tex: Excessive Error Highlighting? ~ + +The <tex.vim> supports lexical error checking of various sorts. Thus, +although the error checking is ofttimes very useful, it can indicate +errors where none actually are. If this proves to be a problem for you, +you may put in your <.vimrc> the following statement: > + let g:tex_no_error=1 +and all error checking by <syntax/tex.vim> will be suppressed. + + *tex-math* + Tex: Need a new Math Group? ~ + +If you want to include a new math group in your LaTeX, the following +code shows you an example as to how you might do so: > + call TexNewMathZone(sfx,mathzone,starform) +You'll want to provide the new math group with a unique suffix +(currently, A-L and V-Z are taken by <syntax/tex.vim> itself). +As an example, consider how eqnarray is set up by <syntax/tex.vim>: > + call TexNewMathZone("D","eqnarray",1) +You'll need to change "mathzone" to the name of your new math group, +and then to the call to it in .vim/after/syntax/tex.vim. +The "starform" variable, if true, implies that your new math group +has a starred form (ie. eqnarray*). + + *tex-style* *b:tex_stylish* + Tex: Starting a New Style? ~ + +One may use "\makeatletter" in *.tex files, thereby making the use of "@" in +commands available. However, since the *.tex file doesn't have one of the +following suffices: sty cls clo dtx ltx, the syntax highlighting will flag +such use of @ as an error. To solve this: > + + :let b:tex_stylish = 1 + :set ft=tex + +Putting "let g:tex_stylish=1" into your <.vimrc> will make <syntax/tex.vim> +always accept such use of @. + + *tex-cchar* *tex-cole* *tex-conceal* + Tex: Taking Advantage of Conceal Mode~ + +If you have |'conceallevel'| set to 2 and if your encoding is utf-8, then a +number of character sequences can be translated into appropriate utf-8 glyphs, +including various accented characters, Greek characters in MathZones, and +superscripts and subscripts in MathZones. Not all characters can be made into +superscripts or subscripts; the constraint is due to what utf-8 supports. +In fact, only a few characters are supported as subscripts. + +One way to use this is to have vertically split windows (see |CTRL-W_v|); one +with |'conceallevel'| at 0 and the other at 2; and both using |'scrollbind'|. + + *g:tex_conceal* + Tex: Selective Conceal Mode~ + +You may selectively use conceal mode by setting g:tex_conceal in your +<.vimrc>. By default, g:tex_conceal is set to "admgs" to enable concealment +for the following sets of characters: > + + a = accents/ligatures + b = bold and italic + d = delimiters + m = math symbols + g = Greek + s = superscripts/subscripts +< +By leaving one or more of these out, the associated conceal-character +substitution will not be made. + + *g:tex_isk* *g:tex_stylish* + Tex: Controlling iskeyword~ + +Normally, LaTeX keywords support 0-9, a-z, A-z, and 192-255 only. Latex +keywords don't support the underscore - except when in *.sty files. The +syntax highlighting script handles this with the following logic: + + * If g:tex_stylish exists and is 1 + then the file will be treated as a "sty" file, so the "_" + will be allowed as part of keywords + (irregardless of g:tex_isk) + * Else if the file's suffix is sty, cls, clo, dtx, or ltx, + then the file will be treated as a "sty" file, so the "_" + will be allowed as part of keywords + (irregardless of g:tex_isk) + + * If g:tex_isk exists, then it will be used for the local 'iskeyword' + * Else the local 'iskeyword' will be set to 48-57,a-z,A-Z,192-255 + + *tex-supersub* *g:tex_superscripts* *g:tex_subscripts* + Tex: Fine Subscript and Superscript Control~ + + See |tex-conceal| for how to enable concealed character replacement. + + See |g:tex_conceal| for selectively concealing accents, bold/italic, + math, Greek, and superscripts/subscripts. + + One may exert fine control over which superscripts and subscripts one + wants syntax-based concealment for (see |:syn-cchar|). Since not all + fonts support all characters, one may override the + concealed-replacement lists; by default these lists are given by: > + + let g:tex_superscripts= "[0-9a-zA-W.,:;+-<>/()=]" + let g:tex_subscripts= "[0-9aehijklmnoprstuvx,+-/().]" +< + For example, I use Luxi Mono Bold; it doesn't support subscript + characters for "hklmnpst", so I put > + let g:tex_subscripts= "[0-9aeijoruvx,+-/().]" +< in ~/.vim/ftplugin/tex/tex.vim in order to avoid having inscrutable + utf-8 glyphs appear. + + +TF *tf.vim* *ft-tf-syntax* + +There is one option for the tf syntax highlighting. + +For syncing, minlines defaults to 100. If you prefer another value, you can +set "tf_minlines" to the value you desire. Example: > + + :let tf_minlines = your choice +< +VIM *vim.vim* *ft-vim-syntax* + *g:vimsyn_minlines* *g:vimsyn_maxlines* +There is a trade-off between more accurate syntax highlighting versus screen +updating speed. To improve accuracy, you may wish to increase the +g:vimsyn_minlines variable. The g:vimsyn_maxlines variable may be used to +improve screen updating rates (see |:syn-sync| for more on this). > + + g:vimsyn_minlines : used to set synchronization minlines + g:vimsyn_maxlines : used to set synchronization maxlines +< + (g:vim_minlines and g:vim_maxlines are deprecated variants of + these two options) + + *g:vimsyn_embed* +The g:vimsyn_embed option allows users to select what, if any, types of +embedded script highlighting they wish to have. > + + g:vimsyn_embed == 0 : don't support any embedded scripts + g:vimsyn_embed =~ 'l' : support embedded lua + g:vimsyn_embed =~ 'm' : support embedded mzscheme + g:vimsyn_embed =~ 'p' : support embedded perl + g:vimsyn_embed =~ 'P' : support embedded python + g:vimsyn_embed =~ 'r' : support embedded ruby + g:vimsyn_embed =~ 't' : support embedded tcl +< +By default, g:vimsyn_embed is a string supporting interpreters that your vim +itself supports. Concatenate multiple characters to support multiple types +of embedded interpreters; ie. g:vimsyn_embed= "mp" supports embedded mzscheme +and embedded perl. + *g:vimsyn_folding* + +Some folding is now supported with syntax/vim.vim: > + + g:vimsyn_folding == 0 or doesn't exist: no syntax-based folding + g:vimsyn_folding =~ 'a' : augroups + g:vimsyn_folding =~ 'f' : fold functions + g:vimsyn_folding =~ 'l' : fold lua script + g:vimsyn_folding =~ 'm' : fold mzscheme script + g:vimsyn_folding =~ 'p' : fold perl script + g:vimsyn_folding =~ 'P' : fold python script + g:vimsyn_folding =~ 'r' : fold ruby script + g:vimsyn_folding =~ 't' : fold tcl script +< + *g:vimsyn_noerror* +Not all error highlighting that syntax/vim.vim does may be correct; VimL is a +difficult language to highlight correctly. A way to suppress error +highlighting is to put the following line in your |vimrc|: > + + let g:vimsyn_noerror = 1 +< + + +XF86CONFIG *xf86conf.vim* *ft-xf86conf-syntax* + +The syntax of XF86Config file differs in XFree86 v3.x and v4.x. Both +variants are supported. Automatic detection is used, but is far from perfect. +You may need to specify the version manually. Set the variable +xf86conf_xfree86_version to 3 or 4 according to your XFree86 version in +your .vimrc. Example: > + :let xf86conf_xfree86_version=3 +When using a mix of versions, set the b:xf86conf_xfree86_version variable. + +Note that spaces and underscores in option names are not supported. Use +"SyncOnGreen" instead of "__s yn con gr_e_e_n" if you want the option name +highlighted. + + +XML *xml.vim* *ft-xml-syntax* + +Xml namespaces are highlighted by default. This can be inhibited by +setting a global variable: > + + :let g:xml_namespace_transparent=1 +< + *xml-folding* +The xml syntax file provides syntax |folding| (see |:syn-fold|) between +start and end tags. This can be turned on by > + + :let g:xml_syntax_folding = 1 + :set foldmethod=syntax + +Note: syntax folding might slow down syntax highlighting significantly, +especially for large files. + + +X Pixmaps (XPM) *xpm.vim* *ft-xpm-syntax* + +xpm.vim creates its syntax items dynamically based upon the contents of the +XPM file. Thus if you make changes e.g. in the color specification strings, +you have to source it again e.g. with ":set syn=xpm". + +To copy a pixel with one of the colors, yank a "pixel" with "yl" and insert it +somewhere else with "P". + +Do you want to draw with the mouse? Try the following: > + :function! GetPixel() + : let c = getline(".")[col(".") - 1] + : echo c + : exe "noremap <LeftMouse> <LeftMouse>r".c + : exe "noremap <LeftDrag> <LeftMouse>r".c + :endfunction + :noremap <RightMouse> <LeftMouse>:call GetPixel()<CR> + :set guicursor=n:hor20 " to see the color beneath the cursor +This turns the right button into a pipette and the left button into a pen. +It will work with XPM files that have one character per pixel only and you +must not click outside of the pixel strings, but feel free to improve it. + +It will look much better with a font in a quadratic cell size, e.g. for X: > + :set guifont=-*-clean-medium-r-*-*-8-*-*-*-*-80-* + + +YAML *yaml.vim* *ft-yaml-syntax* + + *g:yaml_schema* *b:yaml_schema* +A YAML schema is a combination of a set of tags and a mechanism for resolving +non-specific tags. For user this means that YAML parser may, depending on +plain scalar contents, treat plain scalar (which can actually be only string +and nothing else) as a value of the other type: null, boolean, floating-point, +integer. `g:yaml_schema` option determines according to which schema values +will be highlighted specially. Supported schemas are + +Schema Description ~ +failsafe No additional highlighting. +json Supports JSON-style numbers, booleans and null. +core Supports more number, boolean and null styles. +pyyaml In addition to core schema supports highlighting timestamps, + but there are some differences in what is recognized as + numbers and many additional boolean values not present in core + schema. + +Default schema is `core`. + +Note that schemas are not actually limited to plain scalars, but this is the +only difference between schemas defined in YAML specification and the only +difference defined in the syntax file. + +============================================================================== +5. Defining a syntax *:syn-define* *E410* + +Vim understands three types of syntax items: + +1. Keyword + It can only contain keyword characters, according to the 'iskeyword' + option. It cannot contain other syntax items. It will only match with a + complete word (there are no keyword characters before or after the match). + The keyword "if" would match in "if(a=b)", but not in "ifdef x", because + "(" is not a keyword character and "d" is. + +2. Match + This is a match with a single regexp pattern. + +3. Region + This starts at a match of the "start" regexp pattern and ends with a match + with the "end" regexp pattern. Any other text can appear in between. A + "skip" regexp pattern can be used to avoid matching the "end" pattern. + +Several syntax ITEMs can be put into one syntax GROUP. For a syntax group +you can give highlighting attributes. For example, you could have an item +to define a "/* .. */" comment and another one that defines a "// .." comment, +and put them both in the "Comment" group. You can then specify that a +"Comment" will be in bold font and have a blue color. You are free to make +one highlight group for one syntax item, or put all items into one group. +This depends on how you want to specify your highlighting attributes. Putting +each item in its own group results in having to specify the highlighting +for a lot of groups. + +Note that a syntax group and a highlight group are similar. For a highlight +group you will have given highlight attributes. These attributes will be used +for the syntax group with the same name. + +In case more than one item matches at the same position, the one that was +defined LAST wins. Thus you can override previously defined syntax items by +using an item that matches the same text. But a keyword always goes before a +match or region. And a keyword with matching case always goes before a +keyword with ignoring case. + + +PRIORITY *:syn-priority* + +When several syntax items may match, these rules are used: + +1. When multiple Match or Region items start in the same position, the item + defined last has priority. +2. A Keyword has priority over Match and Region items. +3. An item that starts in an earlier position has priority over items that + start in later positions. + + +DEFINING CASE *:syn-case* *E390* + +:sy[ntax] case [match | ignore] + This defines if the following ":syntax" commands will work with + matching case, when using "match", or with ignoring case, when using + "ignore". Note that any items before this are not affected, and all + items until the next ":syntax case" command are affected. + + +SPELL CHECKING *:syn-spell* + +:sy[ntax] spell [toplevel | notoplevel | default] + This defines where spell checking is to be done for text that is not + in a syntax item: + + toplevel: Text is spell checked. + notoplevel: Text is not spell checked. + default: When there is a @Spell cluster no spell checking. + + For text in syntax items use the @Spell and @NoSpell clusters + |spell-syntax|. When there is no @Spell and no @NoSpell cluster then + spell checking is done for "default" and "toplevel". + + To activate spell checking the 'spell' option must be set. + +SYNTAX ISKEYWORD SETTING *:syn-iskeyword* + +:sy[ntax] iskeyword [clear | {option}] + This defines the keyword characters. It's like the 'iskeyword' option + for but only applies to syntax highlighting. + + clear: Syntax specific iskeyword setting is disabled and the + buffer-local 'iskeyword' setting is used. + {option} Set the syntax 'iskeyword' option to a new value. + + Example: > + :syntax iskeyword @,48-57,192-255,$,_ +< + This would set the syntax specific iskeyword option to include all + alphabetic characters, plus the numeric characters, all accented + characters and also includes the "_" and the "$". + + If no argument is given, the current value will be output. + + Setting this option influences what |/\k| matches in syntax patterns + and also determines where |:syn-keyword| will be checked for a new + match. + + It is recommended when writing syntax files, to use this command + to the correct value for the specific syntax language and not change + the 'iskeyword' option. + +DEFINING KEYWORDS *:syn-keyword* + +:sy[ntax] keyword {group-name} [{options}] {keyword} .. [{options}] + + This defines a number of keywords. + + {group-name} Is a syntax group name such as "Comment". + [{options}] See |:syn-arguments| below. + {keyword} .. Is a list of keywords which are part of this group. + + Example: > + :syntax keyword Type int long char +< + The {options} can be given anywhere in the line. They will apply to + all keywords given, also for options that come after a keyword. + These examples do exactly the same: > + :syntax keyword Type contained int long char + :syntax keyword Type int long contained char + :syntax keyword Type int long char contained +< *E789* *E890* + When you have a keyword with an optional tail, like Ex commands in + Vim, you can put the optional characters inside [], to define all the + variations at once: > + :syntax keyword vimCommand ab[breviate] n[ext] +< + Don't forget that a keyword can only be recognized if all the + characters are included in the 'iskeyword' option. If one character + isn't, the keyword will never be recognized. + Multi-byte characters can also be used. These do not have to be in + 'iskeyword'. + See |:syn-iskeyword| for defining syntax specific iskeyword settings. + + A keyword always has higher priority than a match or region, the + keyword is used if more than one item matches. Keywords do not nest + and a keyword can't contain anything else. + + Note that when you have a keyword that is the same as an option (even + one that isn't allowed here), you can not use it. Use a match + instead. + + The maximum length of a keyword is 80 characters. + + The same keyword can be defined multiple times, when its containment + differs. For example, you can define the keyword once not contained + and use one highlight group, and once contained, and use a different + highlight group. Example: > + :syn keyword vimCommand tag + :syn keyword vimSetting contained tag +< When finding "tag" outside of any syntax item, the "vimCommand" + highlight group is used. When finding "tag" in a syntax item that + contains "vimSetting", the "vimSetting" group is used. + + +DEFINING MATCHES *:syn-match* + +:sy[ntax] match {group-name} [{options}] [excludenl] {pattern} [{options}] + + This defines one match. + + {group-name} A syntax group name such as "Comment". + [{options}] See |:syn-arguments| below. + [excludenl] Don't make a pattern with the end-of-line "$" + extend a containing match or region. Must be + given before the pattern. |:syn-excludenl| + {pattern} The search pattern that defines the match. + See |:syn-pattern| below. + Note that the pattern may match more than one + line, which makes the match depend on where + Vim starts searching for the pattern. You + need to make sure syncing takes care of this. + + Example (match a character constant): > + :syntax match Character /'.'/hs=s+1,he=e-1 +< + +DEFINING REGIONS *:syn-region* *:syn-start* *:syn-skip* *:syn-end* + *E398* *E399* +:sy[ntax] region {group-name} [{options}] + [matchgroup={group-name}] + [keepend] + [extend] + [excludenl] + start={start_pattern} .. + [skip={skip_pattern}] + end={end_pattern} .. + [{options}] + + This defines one region. It may span several lines. + + {group-name} A syntax group name such as "Comment". + [{options}] See |:syn-arguments| below. + [matchgroup={group-name}] The syntax group to use for the following + start or end pattern matches only. Not used + for the text in between the matched start and + end patterns. Use NONE to reset to not using + a different group for the start or end match. + See |:syn-matchgroup|. + keepend Don't allow contained matches to go past a + match with the end pattern. See + |:syn-keepend|. + extend Override a "keepend" for an item this region + is contained in. See |:syn-extend|. + excludenl Don't make a pattern with the end-of-line "$" + extend a containing match or item. Only + useful for end patterns. Must be given before + the patterns it applies to. |:syn-excludenl| + start={start_pattern} The search pattern that defines the start of + the region. See |:syn-pattern| below. + skip={skip_pattern} The search pattern that defines text inside + the region where not to look for the end + pattern. See |:syn-pattern| below. + end={end_pattern} The search pattern that defines the end of + the region. See |:syn-pattern| below. + + Example: > + :syntax region String start=+"+ skip=+\\"+ end=+"+ +< + The start/skip/end patterns and the options can be given in any order. + There can be zero or one skip pattern. There must be one or more + start and end patterns. This means that you can omit the skip + pattern, but you must give at least one start and one end pattern. It + is allowed to have white space before and after the equal sign + (although it mostly looks better without white space). + + When more than one start pattern is given, a match with one of these + is sufficient. This means there is an OR relation between the start + patterns. The last one that matches is used. The same is true for + the end patterns. + + The search for the end pattern starts right after the start pattern. + Offsets are not used for this. This implies that the match for the + end pattern will never overlap with the start pattern. + + The skip and end pattern can match across line breaks, but since the + search for the pattern can start in any line it often does not do what + you want. The skip pattern doesn't avoid a match of an end pattern in + the next line. Use single-line patterns to avoid trouble. + + Note: The decision to start a region is only based on a matching start + pattern. There is no check for a matching end pattern. This does NOT + work: > + :syn region First start="(" end=":" + :syn region Second start="(" end=";" +< The Second always matches before the First (last defined pattern has + higher priority). The Second region then continues until the next + ';', no matter if there is a ':' before it. Using a match does work: > + :syn match First "(\_.\{-}:" + :syn match Second "(\_.\{-};" +< This pattern matches any character or line break with "\_." and + repeats that with "\{-}" (repeat as few as possible). + + *:syn-keepend* + By default, a contained match can obscure a match for the end pattern. + This is useful for nesting. For example, a region that starts with + "{" and ends with "}", can contain another region. An encountered "}" + will then end the contained region, but not the outer region: + { starts outer "{}" region + { starts contained "{}" region + } ends contained "{}" region + } ends outer "{} region + If you don't want this, the "keepend" argument will make the matching + of an end pattern of the outer region also end any contained item. + This makes it impossible to nest the same region, but allows for + contained items to highlight parts of the end pattern, without causing + that to skip the match with the end pattern. Example: > + :syn match vimComment +"[^"]\+$+ + :syn region vimCommand start="set" end="$" contains=vimComment keepend +< The "keepend" makes the vimCommand always end at the end of the line, + even though the contained vimComment includes a match with the <EOL>. + + When "keepend" is not used, a match with an end pattern is retried + after each contained match. When "keepend" is included, the first + encountered match with an end pattern is used, truncating any + contained matches. + *:syn-extend* + The "keepend" behavior can be changed by using the "extend" argument. + When an item with "extend" is contained in an item that uses + "keepend", the "keepend" is ignored and the containing region will be + extended. + This can be used to have some contained items extend a region while + others don't. Example: > + + :syn region htmlRef start=+<a>+ end=+</a>+ keepend contains=htmlItem,htmlScript + :syn match htmlItem +<[^>]*>+ contained + :syn region htmlScript start=+<script+ end=+</script[^>]*>+ contained extend + +< Here the htmlItem item does not make the htmlRef item continue + further, it is only used to highlight the <> items. The htmlScript + item does extend the htmlRef item. + + Another example: > + :syn region xmlFold start="<a>" end="</a>" fold transparent keepend extend +< This defines a region with "keepend", so that its end cannot be + changed by contained items, like when the "</a>" is matched to + highlight it differently. But when the xmlFold region is nested (it + includes itself), the "extend" applies, so that the "</a>" of a nested + region only ends that region, and not the one it is contained in. + + *:syn-excludenl* + When a pattern for a match or end pattern of a region includes a '$' + to match the end-of-line, it will make a region item that it is + contained in continue on the next line. For example, a match with + "\\$" (backslash at the end of the line) can make a region continue + that would normally stop at the end of the line. This is the default + behavior. If this is not wanted, there are two ways to avoid it: + 1. Use "keepend" for the containing item. This will keep all + contained matches from extending the match or region. It can be + used when all contained items must not extend the containing item. + 2. Use "excludenl" in the contained item. This will keep that match + from extending the containing match or region. It can be used if + only some contained items must not extend the containing item. + "excludenl" must be given before the pattern it applies to. + + *:syn-matchgroup* + "matchgroup" can be used to highlight the start and/or end pattern + differently than the body of the region. Example: > + :syntax region String matchgroup=Quote start=+"+ skip=+\\"+ end=+"+ +< This will highlight the quotes with the "Quote" group, and the text in + between with the "String" group. + The "matchgroup" is used for all start and end patterns that follow, + until the next "matchgroup". Use "matchgroup=NONE" to go back to not + using a matchgroup. + + In a start or end pattern that is highlighted with "matchgroup" the + contained items of the region are not used. This can be used to avoid + that a contained item matches in the start or end pattern match. When + using "transparent", this does not apply to a start or end pattern + match that is highlighted with "matchgroup". + + Here is an example, which highlights three levels of parentheses in + different colors: > + :sy region par1 matchgroup=par1 start=/(/ end=/)/ contains=par2 + :sy region par2 matchgroup=par2 start=/(/ end=/)/ contains=par3 contained + :sy region par3 matchgroup=par3 start=/(/ end=/)/ contains=par1 contained + :hi par1 ctermfg=red guifg=red + :hi par2 ctermfg=blue guifg=blue + :hi par3 ctermfg=darkgreen guifg=darkgreen +< + *E849* +The maximum number of syntax groups is 19999. + +============================================================================== +6. :syntax arguments *:syn-arguments* + +The :syntax commands that define syntax items take a number of arguments. +The common ones are explained here. The arguments may be given in any order +and may be mixed with patterns. + +Not all commands accept all arguments. This table shows which arguments +can not be used for all commands: + *E395* + contains oneline fold display extend concealends~ +:syntax keyword - - - - - - +:syntax match yes - yes yes yes - +:syntax region yes yes yes yes yes yes + +These arguments can be used for all three commands: + conceal + cchar + contained + containedin + nextgroup + transparent + skipwhite + skipnl + skipempty + +conceal *conceal* *:syn-conceal* + +When the "conceal" argument is given, the item is marked as concealable. +Whether or not it is actually concealed depends on the value of the +'conceallevel' option. The 'concealcursor' option is used to decide whether +concealable items in the current line are displayed unconcealed to be able to +edit the line. +Another way to conceal text with with |matchadd()|. + +concealends *:syn-concealends* + +When the "concealends" argument is given, the start and end matches of +the region, but not the contents of the region, are marked as concealable. +Whether or not they are actually concealed depends on the setting on the +'conceallevel' option. The ends of a region can only be concealed separately +in this way when they have their own highlighting via "matchgroup" + +cchar *:syn-cchar* + *E844* +The "cchar" argument defines the character shown in place of the item +when it is concealed (setting "cchar" only makes sense when the conceal +argument is given.) If "cchar" is not set then the default conceal +character defined in the 'listchars' option is used. The character cannot be +a control character such as Tab. Example: > + :syntax match Entity "&" conceal cchar=& +See |hl-Conceal| for highlighting. + +contained *:syn-contained* + +When the "contained" argument is given, this item will not be recognized at +the top level, but only when it is mentioned in the "contains" field of +another match. Example: > + :syntax keyword Todo TODO contained + :syntax match Comment "//.*" contains=Todo + + +display *:syn-display* + +If the "display" argument is given, this item will be skipped when the +detected highlighting will not be displayed. This will speed up highlighting, +by skipping this item when only finding the syntax state for the text that is +to be displayed. + +Generally, you can use "display" for match and region items that meet these +conditions: +- The item does not continue past the end of a line. Example for C: A region + for a "/*" comment can't contain "display", because it continues on the next + line. +- The item does not contain items that continue past the end of the line or + make it continue on the next line. +- The item does not change the size of any item it is contained in. Example + for C: A match with "\\$" in a preprocessor match can't have "display", + because it may make that preprocessor match shorter. +- The item does not allow other items to match that didn't match otherwise, + and that item may extend the match too far. Example for C: A match for a + "//" comment can't use "display", because a "/*" inside that comment would + match then and start a comment which extends past the end of the line. + +Examples, for the C language, where "display" can be used: +- match with a number +- match with a label + + +transparent *:syn-transparent* + +If the "transparent" argument is given, this item will not be highlighted +itself, but will take the highlighting of the item it is contained in. This +is useful for syntax items that don't need any highlighting but are used +only to skip over a part of the text. + +The "contains=" argument is also inherited from the item it is contained in, +unless a "contains" argument is given for the transparent item itself. To +avoid that unwanted items are contained, use "contains=NONE". Example, which +highlights words in strings, but makes an exception for "vim": > + :syn match myString /'[^']*'/ contains=myWord,myVim + :syn match myWord /\<[a-z]*\>/ contained + :syn match myVim /\<vim\>/ transparent contained contains=NONE + :hi link myString String + :hi link myWord Comment +Since the "myVim" match comes after "myWord" it is the preferred match (last +match in the same position overrules an earlier one). The "transparent" +argument makes the "myVim" match use the same highlighting as "myString". But +it does not contain anything. If the "contains=NONE" argument would be left +out, then "myVim" would use the contains argument from myString and allow +"myWord" to be contained, which will be highlighted as a Constant. This +happens because a contained match doesn't match inside itself in the same +position, thus the "myVim" match doesn't overrule the "myWord" match here. + +When you look at the colored text, it is like looking at layers of contained +items. The contained item is on top of the item it is contained in, thus you +see the contained item. When a contained item is transparent, you can look +through, thus you see the item it is contained in. In a picture: + + look from here + + | | | | | | + V V V V V V + + xxxx yyy more contained items + .................... contained item (transparent) + ============================= first item + +The 'x', 'y' and '=' represent a highlighted syntax item. The '.' represent a +transparent group. + +What you see is: + + =======xxxx=======yyy======== + +Thus you look through the transparent "....". + + +oneline *:syn-oneline* + +The "oneline" argument indicates that the region does not cross a line +boundary. It must match completely in the current line. However, when the +region has a contained item that does cross a line boundary, it continues on +the next line anyway. A contained item can be used to recognize a line +continuation pattern. But the "end" pattern must still match in the first +line, otherwise the region doesn't even start. + +When the start pattern includes a "\n" to match an end-of-line, the end +pattern must be found in the same line as where the start pattern ends. The +end pattern may also include an end-of-line. Thus the "oneline" argument +means that the end of the start pattern and the start of the end pattern must +be within one line. This can't be changed by a skip pattern that matches a +line break. + + +fold *:syn-fold* + +The "fold" argument makes the fold level increase by one for this item. +Example: > + :syn region myFold start="{" end="}" transparent fold + :syn sync fromstart + :set foldmethod=syntax +This will make each {} block form one fold. + +The fold will start on the line where the item starts, and end where the item +ends. If the start and end are within the same line, there is no fold. +The 'foldnestmax' option limits the nesting of syntax folds. +{not available when Vim was compiled without |+folding| feature} + + + *:syn-contains* *E405* *E406* *E407* *E408* *E409* +contains={group-name},.. + +The "contains" argument is followed by a list of syntax group names. These +groups will be allowed to begin inside the item (they may extend past the +containing group's end). This allows for recursive nesting of matches and +regions. If there is no "contains" argument, no groups will be contained in +this item. The group names do not need to be defined before they can be used +here. + +contains=ALL + If the only item in the contains list is "ALL", then all + groups will be accepted inside the item. + +contains=ALLBUT,{group-name},.. + If the first item in the contains list is "ALLBUT", then all + groups will be accepted inside the item, except the ones that + are listed. Example: > + :syntax region Block start="{" end="}" ... contains=ALLBUT,Function + +contains=TOP + If the first item in the contains list is "TOP", then all + groups will be accepted that don't have the "contained" + argument. +contains=TOP,{group-name},.. + Like "TOP", but excluding the groups that are listed. + +contains=CONTAINED + If the first item in the contains list is "CONTAINED", then + all groups will be accepted that have the "contained" + argument. +contains=CONTAINED,{group-name},.. + Like "CONTAINED", but excluding the groups that are + listed. + + +The {group-name} in the "contains" list can be a pattern. All group names +that match the pattern will be included (or excluded, if "ALLBUT" is used). +The pattern cannot contain white space or a ','. Example: > + ... contains=Comment.*,Keyw[0-3] +The matching will be done at moment the syntax command is executed. Groups +that are defined later will not be matched. Also, if the current syntax +command defines a new group, it is not matched. Be careful: When putting +syntax commands in a file you can't rely on groups NOT being defined, because +the file may have been sourced before, and ":syn clear" doesn't remove the +group names. + +The contained groups will also match in the start and end patterns of a +region. If this is not wanted, the "matchgroup" argument can be used +|:syn-matchgroup|. The "ms=" and "me=" offsets can be used to change the +region where contained items do match. Note that this may also limit the +area that is highlighted + + +containedin={group-name}... *:syn-containedin* + +The "containedin" argument is followed by a list of syntax group names. The +item will be allowed to begin inside these groups. This works as if the +containing item has a "contains=" argument that includes this item. + +The {group-name}... can be used just like for "contains", as explained above. + +This is useful when adding a syntax item afterwards. An item can be told to +be included inside an already existing item, without changing the definition +of that item. For example, to highlight a word in a C comment after loading +the C syntax: > + :syn keyword myword HELP containedin=cComment contained +Note that "contained" is also used, to avoid that the item matches at the top +level. + +Matches for "containedin" are added to the other places where the item can +appear. A "contains" argument may also be added as usual. Don't forget that +keywords never contain another item, thus adding them to "containedin" won't +work. + + +nextgroup={group-name},.. *:syn-nextgroup* + +The "nextgroup" argument is followed by a list of syntax group names, +separated by commas (just like with "contains", so you can also use patterns). + +If the "nextgroup" argument is given, the mentioned syntax groups will be +tried for a match, after the match or region ends. If none of the groups have +a match, highlighting continues normally. If there is a match, this group +will be used, even when it is not mentioned in the "contains" field of the +current group. This is like giving the mentioned group priority over all +other groups. Example: > + :syntax match ccFoobar "Foo.\{-}Bar" contains=ccFoo + :syntax match ccFoo "Foo" contained nextgroup=ccFiller + :syntax region ccFiller start="." matchgroup=ccBar end="Bar" contained + +This will highlight "Foo" and "Bar" differently, and only when there is a +"Bar" after "Foo". In the text line below, "f" shows where ccFoo is used for +highlighting, and "bbb" where ccBar is used. > + + Foo asdfasd Bar asdf Foo asdf Bar asdf + fff bbb fff bbb + +Note the use of ".\{-}" to skip as little as possible until the next Bar. +when ".*" would be used, the "asdf" in between "Bar" and "Foo" would be +highlighted according to the "ccFoobar" group, because the ccFooBar match +would include the first "Foo" and the last "Bar" in the line (see |pattern|). + + +skipwhite *:syn-skipwhite* +skipnl *:syn-skipnl* +skipempty *:syn-skipempty* + +These arguments are only used in combination with "nextgroup". They can be +used to allow the next group to match after skipping some text: + skipwhite skip over space and tab characters + skipnl skip over the end of a line + skipempty skip over empty lines (implies a "skipnl") + +When "skipwhite" is present, the white space is only skipped if there is no +next group that matches the white space. + +When "skipnl" is present, the match with nextgroup may be found in the next +line. This only happens when the current item ends at the end of the current +line! When "skipnl" is not present, the nextgroup will only be found after +the current item in the same line. + +When skipping text while looking for a next group, the matches for other +groups are ignored. Only when no next group matches, other items are tried +for a match again. This means that matching a next group and skipping white +space and <EOL>s has a higher priority than other items. + +Example: > + :syn match ifstart "\<if.*" nextgroup=ifline skipwhite skipempty + :syn match ifline "[^ \t].*" nextgroup=ifline skipwhite skipempty contained + :syn match ifline "endif" contained +Note that the "[^ \t].*" match matches all non-white text. Thus it would also +match "endif". Therefore the "endif" match is put last, so that it takes +precedence. +Note that this example doesn't work for nested "if"s. You need to add +"contains" arguments to make that work (omitted for simplicity of the +example). + +IMPLICIT CONCEAL *:syn-conceal-implicit* + +:sy[ntax] conceal [on|off] + This defines if the following ":syntax" commands will define keywords, + matches or regions with the "conceal" flag set. After ":syn conceal + on", all subsequent ":syn keyword", ":syn match" or ":syn region" + defined will have the "conceal" flag set implicitly. ":syn conceal + off" returns to the normal state where the "conceal" flag must be + given explicitly. + +============================================================================== +7. Syntax patterns *:syn-pattern* *E401* *E402* + +In the syntax commands, a pattern must be surrounded by two identical +characters. This is like it works for the ":s" command. The most common to +use is the double quote. But if the pattern contains a double quote, you can +use another character that is not used in the pattern. Examples: > + :syntax region Comment start="/\*" end="\*/" + :syntax region String start=+"+ end=+"+ skip=+\\"+ + +See |pattern| for the explanation of what a pattern is. Syntax patterns are +always interpreted like the 'magic' option is set, no matter what the actual +value of 'magic' is. And the patterns are interpreted like the 'l' flag is +not included in 'cpoptions'. This was done to make syntax files portable and +independent of 'compatible' and 'magic' settings. + +Try to avoid patterns that can match an empty string, such as "[a-z]*". +This slows down the highlighting a lot, because it matches everywhere. + + *:syn-pattern-offset* +The pattern can be followed by a character offset. This can be used to +change the highlighted part, and to change the text area included in the +match or region (which only matters when trying to match other items). Both +are relative to the matched pattern. The character offset for a skip +pattern can be used to tell where to continue looking for an end pattern. + +The offset takes the form of "{what}={offset}" +The {what} can be one of seven strings: + +ms Match Start offset for the start of the matched text +me Match End offset for the end of the matched text +hs Highlight Start offset for where the highlighting starts +he Highlight End offset for where the highlighting ends +rs Region Start offset for where the body of a region starts +re Region End offset for where the body of a region ends +lc Leading Context offset past "leading context" of pattern + +The {offset} can be: + +s start of the matched pattern +s+{nr} start of the matched pattern plus {nr} chars to the right +s-{nr} start of the matched pattern plus {nr} chars to the left +e end of the matched pattern +e+{nr} end of the matched pattern plus {nr} chars to the right +e-{nr} end of the matched pattern plus {nr} chars to the left +{nr} (for "lc" only): start matching {nr} chars right of the start + +Examples: "ms=s+1", "hs=e-2", "lc=3". + +Although all offsets are accepted after any pattern, they are not always +meaningful. This table shows which offsets are actually used: + + ms me hs he rs re lc ~ +match item yes yes yes yes - - yes +region item start yes - yes - yes - yes +region item skip - yes - - - - yes +region item end - yes - yes - yes yes + +Offsets can be concatenated, with a ',' in between. Example: > + :syn match String /"[^"]*"/hs=s+1,he=e-1 +< + some "string" text + ^^^^^^ highlighted + +Notes: +- There must be no white space between the pattern and the character + offset(s). +- The highlighted area will never be outside of the matched text. +- A negative offset for an end pattern may not always work, because the end + pattern may be detected when the highlighting should already have stopped. +- Before Vim 7.2 the offsets were counted in bytes instead of characters. + This didn't work well for multi-byte characters, so it was changed with the + Vim 7.2 release. +- The start of a match cannot be in a line other than where the pattern + matched. This doesn't work: "a\nb"ms=e. You can make the highlighting + start in another line, this does work: "a\nb"hs=e. + +Example (match a comment but don't highlight the /* and */): > + :syntax region Comment start="/\*"hs=e+1 end="\*/"he=s-1 +< + /* this is a comment */ + ^^^^^^^^^^^^^^^^^^^ highlighted + +A more complicated Example: > + :syn region Exa matchgroup=Foo start="foo"hs=s+2,rs=e+2 matchgroup=Bar end="bar"me=e-1,he=e-1,re=s-1 +< + abcfoostringbarabc + mmmmmmmmmmm match + sssrrreee highlight start/region/end ("Foo", "Exa" and "Bar") + +Leading context *:syn-lc* *:syn-leading* *:syn-context* + +Note: This is an obsolete feature, only included for backwards compatibility +with previous Vim versions. It's now recommended to use the |/\@<=| construct +in the pattern. + +The "lc" offset specifies leading context -- a part of the pattern that must +be present, but is not considered part of the match. An offset of "lc=n" will +cause Vim to step back n columns before attempting the pattern match, allowing +characters which have already been matched in previous patterns to also be +used as leading context for this match. This can be used, for instance, to +specify that an "escaping" character must not precede the match: > + + :syn match ZNoBackslash "[^\\]z"ms=s+1 + :syn match WNoBackslash "[^\\]w"lc=1 + :syn match Underline "_\+" +< + ___zzzz ___wwww + ^^^ ^^^ matches Underline + ^ ^ matches ZNoBackslash + ^^^^ matches WNoBackslash + +The "ms" offset is automatically set to the same value as the "lc" offset, +unless you set "ms" explicitly. + + +Multi-line patterns *:syn-multi-line* + +The patterns can include "\n" to match an end-of-line. Mostly this works as +expected, but there are a few exceptions. + +When using a start pattern with an offset, the start of the match is not +allowed to start in a following line. The highlighting can start in a +following line though. Using the "\zs" item also requires that the start of +the match doesn't move to another line. + +The skip pattern can include the "\n", but the search for an end pattern will +continue in the first character of the next line, also when that character is +matched by the skip pattern. This is because redrawing may start in any line +halfway a region and there is no check if the skip pattern started in a +previous line. For example, if the skip pattern is "a\nb" and an end pattern +is "b", the end pattern does match in the second line of this: > + x x a + b x x +Generally this means that the skip pattern should not match any characters +after the "\n". + + +External matches *:syn-ext-match* + +These extra regular expression items are available in region patterns: + + */\z(* */\z(\)* *E50* *E52* *E879* + \z(\) Marks the sub-expression as "external", meaning that it can be + accessed from another pattern match. Currently only usable in + defining a syntax region start pattern. + + */\z1* */\z2* */\z3* */\z4* */\z5* + \z1 ... \z9 */\z6* */\z7* */\z8* */\z9* *E66* *E67* + Matches the same string that was matched by the corresponding + sub-expression in a previous start pattern match. + +Sometimes the start and end patterns of a region need to share a common +sub-expression. A common example is the "here" document in Perl and many Unix +shells. This effect can be achieved with the "\z" special regular expression +items, which marks a sub-expression as "external", in the sense that it can be +referenced from outside the pattern in which it is defined. The here-document +example, for instance, can be done like this: > + :syn region hereDoc start="<<\z(\I\i*\)" end="^\z1$" + +As can be seen here, the \z actually does double duty. In the start pattern, +it marks the "\(\I\i*\)" sub-expression as external; in the end pattern, it +changes the \z1 back-reference into an external reference referring to the +first external sub-expression in the start pattern. External references can +also be used in skip patterns: > + :syn region foo start="start \(\I\i*\)" skip="not end \z1" end="end \z1" + +Note that normal and external sub-expressions are completely orthogonal and +indexed separately; for instance, if the pattern "\z(..\)\(..\)" is applied +to the string "aabb", then \1 will refer to "bb" and \z1 will refer to "aa". +Note also that external sub-expressions cannot be accessed as back-references +within the same pattern like normal sub-expressions. If you want to use one +sub-expression as both a normal and an external sub-expression, you can nest +the two, as in "\(\z(...\)\)". + +Note that only matches within a single line can be used. Multi-line matches +cannot be referred to. + +============================================================================== +8. Syntax clusters *:syn-cluster* *E400* + +:sy[ntax] cluster {cluster-name} [contains={group-name}..] + [add={group-name}..] + [remove={group-name}..] + +This command allows you to cluster a list of syntax groups together under a +single name. + + contains={group-name}.. + The cluster is set to the specified list of groups. + add={group-name}.. + The specified groups are added to the cluster. + remove={group-name}.. + The specified groups are removed from the cluster. + +A cluster so defined may be referred to in a contains=.., containedin=.., +nextgroup=.., add=.. or remove=.. list with a "@" prefix. You can also use +this notation to implicitly declare a cluster before specifying its contents. + +Example: > + :syntax match Thing "# [^#]\+ #" contains=@ThingMembers + :syntax cluster ThingMembers contains=ThingMember1,ThingMember2 + +As the previous example suggests, modifications to a cluster are effectively +retroactive; the membership of the cluster is checked at the last minute, so +to speak: > + :syntax keyword A aaa + :syntax keyword B bbb + :syntax cluster AandB contains=A + :syntax match Stuff "( aaa bbb )" contains=@AandB + :syntax cluster AandB add=B " now both keywords are matched in Stuff + +This also has implications for nested clusters: > + :syntax keyword A aaa + :syntax keyword B bbb + :syntax cluster SmallGroup contains=B + :syntax cluster BigGroup contains=A,@SmallGroup + :syntax match Stuff "( aaa bbb )" contains=@BigGroup + :syntax cluster BigGroup remove=B " no effect, since B isn't in BigGroup + :syntax cluster SmallGroup remove=B " now bbb isn't matched within Stuff +< + *E848* +The maximum number of clusters is 9767. + +============================================================================== +9. Including syntax files *:syn-include* *E397* + +It is often useful for one language's syntax file to include a syntax file for +a related language. Depending on the exact relationship, this can be done in +two different ways: + + - If top-level syntax items in the included syntax file are to be + allowed at the top level in the including syntax, you can simply use + the |:runtime| command: > + + " In cpp.vim: + :runtime! syntax/c.vim + :unlet b:current_syntax + +< - If top-level syntax items in the included syntax file are to be + contained within a region in the including syntax, you can use the + ":syntax include" command: + +:sy[ntax] include [@{grouplist-name}] {file-name} + + All syntax items declared in the included file will have the + "contained" flag added. In addition, if a group list is specified, + all top-level syntax items in the included file will be added to + that list. > + + " In perl.vim: + :syntax include @Pod <sfile>:p:h/pod.vim + :syntax region perlPOD start="^=head" end="^=cut" contains=@Pod +< + When {file-name} is an absolute path (starts with "/", "c:", "$VAR" + or "<sfile>") that file is sourced. When it is a relative path + (e.g., "syntax/pod.vim") the file is searched for in 'runtimepath'. + All matching files are loaded. Using a relative path is + recommended, because it allows a user to replace the included file + with his own version, without replacing the file that does the ":syn + include". + + *E847* +The maximum number of includes is 999. + +============================================================================== +10. Synchronizing *:syn-sync* *E403* *E404* + +Vim wants to be able to start redrawing in any position in the document. To +make this possible it needs to know the syntax state at the position where +redrawing starts. + +:sy[ntax] sync [ccomment [group-name] | minlines={N} | ...] + +There are four ways to synchronize: +1. Always parse from the start of the file. + |:syn-sync-first| +2. Based on C-style comments. Vim understands how C-comments work and can + figure out if the current line starts inside or outside a comment. + |:syn-sync-second| +3. Jumping back a certain number of lines and start parsing there. + |:syn-sync-third| +4. Searching backwards in the text for a pattern to sync on. + |:syn-sync-fourth| + + *:syn-sync-maxlines* *:syn-sync-minlines* +For the last three methods, the line range where the parsing can start is +limited by "minlines" and "maxlines". + +If the "minlines={N}" argument is given, the parsing always starts at least +that many lines backwards. This can be used if the parsing may take a few +lines before it's correct, or when it's not possible to use syncing. + +If the "maxlines={N}" argument is given, the number of lines that are searched +for a comment or syncing pattern is restricted to N lines backwards (after +adding "minlines"). This is useful if you have few things to sync on and a +slow machine. Example: > + :syntax sync maxlines=500 ccomment +< + *:syn-sync-linebreaks* +When using a pattern that matches multiple lines, a change in one line may +cause a pattern to no longer match in a previous line. This means has to +start above where the change was made. How many lines can be specified with +the "linebreaks" argument. For example, when a pattern may include one line +break use this: > + :syntax sync linebreaks=1 +The result is that redrawing always starts at least one line before where a +change was made. The default value for "linebreaks" is zero. Usually the +value for "minlines" is bigger than "linebreaks". + + +First syncing method: *:syn-sync-first* +> + :syntax sync fromstart + +The file will be parsed from the start. This makes syntax highlighting +accurate, but can be slow for long files. Vim caches previously parsed text, +so that it's only slow when parsing the text for the first time. However, +when making changes some part of the text needs to be parsed again (worst +case: to the end of the file). + +Using "fromstart" is equivalent to using "minlines" with a very large number. + + +Second syncing method: *:syn-sync-second* *:syn-sync-ccomment* + +For the second method, only the "ccomment" argument needs to be given. +Example: > + :syntax sync ccomment + +When Vim finds that the line where displaying starts is inside a C-style +comment, the last region syntax item with the group-name "Comment" will be +used. This requires that there is a region with the group-name "Comment"! +An alternate group name can be specified, for example: > + :syntax sync ccomment javaComment +This means that the last item specified with "syn region javaComment" will be +used for the detected C comment region. This only works properly if that +region does have a start pattern "\/*" and an end pattern "*\/". + +The "maxlines" argument can be used to restrict the search to a number of +lines. The "minlines" argument can be used to at least start a number of +lines back (e.g., for when there is some construct that only takes a few +lines, but it hard to sync on). + +Note: Syncing on a C comment doesn't work properly when strings are used +that cross a line and contain a "*/". Since letting strings cross a line +is a bad programming habit (many compilers give a warning message), and the +chance of a "*/" appearing inside a comment is very small, this restriction +is hardly ever noticed. + + +Third syncing method: *:syn-sync-third* + +For the third method, only the "minlines={N}" argument needs to be given. +Vim will subtract {N} from the line number and start parsing there. This +means {N} extra lines need to be parsed, which makes this method a bit slower. +Example: > + :syntax sync minlines=50 + +"lines" is equivalent to "minlines" (used by older versions). + + +Fourth syncing method: *:syn-sync-fourth* + +The idea is to synchronize on the end of a few specific regions, called a +sync pattern. Only regions can cross lines, so when we find the end of some +region, we might be able to know in which syntax item we are. The search +starts in the line just above the one where redrawing starts. From there +the search continues backwards in the file. + +This works just like the non-syncing syntax items. You can use contained +matches, nextgroup, etc. But there are a few differences: +- Keywords cannot be used. +- The syntax items with the "sync" keyword form a completely separated group + of syntax items. You can't mix syncing groups and non-syncing groups. +- The matching works backwards in the buffer (line by line), instead of + forwards. +- A line continuation pattern can be given. It is used to decide which group + of lines need to be searched like they were one line. This means that the + search for a match with the specified items starts in the first of the + consecutive that contain the continuation pattern. +- When using "nextgroup" or "contains", this only works within one line (or + group of continued lines). +- When using a region, it must start and end in the same line (or group of + continued lines). Otherwise the end is assumed to be at the end of the + line (or group of continued lines). +- When a match with a sync pattern is found, the rest of the line (or group of + continued lines) is searched for another match. The last match is used. + This is used when a line can contain both the start end the end of a region + (e.g., in a C-comment like /* this */, the last "*/" is used). + +There are two ways how a match with a sync pattern can be used: +1. Parsing for highlighting starts where redrawing starts (and where the + search for the sync pattern started). The syntax group that is expected + to be valid there must be specified. This works well when the regions + that cross lines cannot contain other regions. +2. Parsing for highlighting continues just after the match. The syntax group + that is expected to be present just after the match must be specified. + This can be used when the previous method doesn't work well. It's much + slower, because more text needs to be parsed. +Both types of sync patterns can be used at the same time. + +Besides the sync patterns, other matches and regions can be specified, to +avoid finding unwanted matches. + +[The reason that the sync patterns are given separately, is that mostly the +search for the sync point can be much simpler than figuring out the +highlighting. The reduced number of patterns means it will go (much) +faster.] + + *syn-sync-grouphere* *E393* *E394* + :syntax sync match {sync-group-name} grouphere {group-name} "pattern" .. + + Define a match that is used for syncing. {group-name} is the + name of a syntax group that follows just after the match. Parsing + of the text for highlighting starts just after the match. A region + must exist for this {group-name}. The first one defined will be used. + "NONE" can be used for when there is no syntax group after the match. + + *syn-sync-groupthere* + :syntax sync match {sync-group-name} groupthere {group-name} "pattern" .. + + Like "grouphere", but {group-name} is the name of a syntax group that + is to be used at the start of the line where searching for the sync + point started. The text between the match and the start of the sync + pattern searching is assumed not to change the syntax highlighting. + For example, in C you could search backwards for "/*" and "*/". If + "/*" is found first, you know that you are inside a comment, so the + "groupthere" is "cComment". If "*/" is found first, you know that you + are not in a comment, so the "groupthere" is "NONE". (in practice + it's a bit more complicated, because the "/*" and "*/" could appear + inside a string. That's left as an exercise to the reader...). + + :syntax sync match .. + :syntax sync region .. + + Without a "groupthere" argument. Define a region or match that is + skipped while searching for a sync point. + + *syn-sync-linecont* + :syntax sync linecont {pattern} + + When {pattern} matches in a line, it is considered to continue in + the next line. This means that the search for a sync point will + consider the lines to be concatenated. + +If the "maxlines={N}" argument is given too, the number of lines that are +searched for a match is restricted to N. This is useful if you have very +few things to sync on and a slow machine. Example: > + :syntax sync maxlines=100 + +You can clear all sync settings with: > + :syntax sync clear + +You can clear specific sync patterns with: > + :syntax sync clear {sync-group-name} .. + +============================================================================== +11. Listing syntax items *:syntax* *:sy* *:syn* *:syn-list* + +This command lists all the syntax items: > + + :sy[ntax] [list] + +To show the syntax items for one syntax group: > + + :sy[ntax] list {group-name} + +To list the syntax groups in one cluster: *E392* > + + :sy[ntax] list @{cluster-name} + +See above for other arguments for the ":syntax" command. + +Note that the ":syntax" command can be abbreviated to ":sy", although ":syn" +is mostly used, because it looks better. + +============================================================================== +12. Highlight command *:highlight* *:hi* *E28* *E411* *E415* + +There are three types of highlight groups: +- The ones used for specific languages. For these the name starts with the + name of the language. Many of these don't have any attributes, but are + linked to a group of the second type. +- The ones used for all syntax languages. +- The ones used for the 'highlight' option. + *hitest.vim* +You can see all the groups currently active with this command: > + :so $VIMRUNTIME/syntax/hitest.vim +This will open a new window containing all highlight group names, displayed +in their own color. + + *:colo* *:colorscheme* *E185* +:colo[rscheme] Output the name of the currently active color scheme. + This is basically the same as > + :echo g:colors_name +< In case g:colors_name has not been defined :colo will + output "default". When compiled without the |+eval| + feature it will output "unknown". + +:colo[rscheme] {name} Load color scheme {name}. This searches 'runtimepath' + for the file "colors/{name}.vim". The first one that + is found is loaded. + To see the name of the currently active color scheme: > + :colo +< The name is also stored in the g:colors_name variable. + Doesn't work recursively, thus you can't use + ":colorscheme" in a color scheme script. + After the color scheme has been loaded the + |ColorScheme| autocommand event is triggered. + For info about writing a colorscheme file: > + :edit $VIMRUNTIME/colors/README.txt + +:hi[ghlight] List all the current highlight groups that have + attributes set. + +:hi[ghlight] {group-name} + List one highlight group. + +:hi[ghlight] clear Reset all highlighting to the defaults. Removes all + highlighting for groups added by the user! + Uses the current value of 'background' to decide which + default colors to use. + +:hi[ghlight] clear {group-name} +:hi[ghlight] {group-name} NONE + Disable the highlighting for one highlight group. It + is _not_ set back to the default colors. + +:hi[ghlight] [default] {group-name} {key}={arg} .. + Add a highlight group, or change the highlighting for + an existing group. + See |highlight-args| for the {key}={arg} arguments. + See |:highlight-default| for the optional [default] + argument. + +Normally a highlight group is added once when starting up. This sets the +default values for the highlighting. After that, you can use additional +highlight commands to change the arguments that you want to set to non-default +values. The value "NONE" can be used to switch the value off or go back to +the default value. + +A simple way to change colors is with the |:colorscheme| command. This loads +a file with ":highlight" commands such as this: > + + :hi Comment gui=bold + +Note that all settings that are not included remain the same, only the +specified field is used, and settings are merged with previous ones. So, the +result is like this single command has been used: > + :hi Comment term=bold ctermfg=Cyan guifg=#80a0ff gui=bold +< + *:highlight-verbose* +When listing a highlight group and 'verbose' is non-zero, the listing will +also tell where it was last set. Example: > + :verbose hi Comment +< Comment xxx term=bold ctermfg=4 guifg=Blue ~ + Last set from /home/mool/vim/vim7/runtime/syntax/syncolor.vim ~ + +When ":hi clear" is used then the script where this command is used will be +mentioned for the default values. See |:verbose-cmd| for more information. + + *highlight-args* *E416* *E417* *E423* +There are three types of terminals for highlighting: +term a normal terminal (vt100, xterm) +cterm a color terminal (MS-DOS console, color-xterm, these have the "Co" + termcap entry) +gui the GUI + +For each type the highlighting can be given. This makes it possible to use +the same syntax file on all terminals, and use the optimal highlighting. + +1. highlight arguments for normal terminals + + *bold* *underline* *undercurl* + *inverse* *italic* *standout* +term={attr-list} *attr-list* *highlight-term* *E418* + attr-list is a comma separated list (without spaces) of the + following items (in any order): + bold + underline + undercurl not always available + reverse + inverse same as reverse + italic + standout + NONE no attributes used (used to reset it) + + Note that "bold" can be used here and by using a bold font. They + have the same effect. + "undercurl" is a curly underline. When "undercurl" is not possible + then "underline" is used. In general "undercurl" is only available in + the GUI. The color is set with |highlight-guisp|. + +start={term-list} *highlight-start* *E422* +stop={term-list} *term-list* *highlight-stop* + These lists of terminal codes can be used to get + non-standard attributes on a terminal. + + The escape sequence specified with the "start" argument + is written before the characters in the highlighted + area. It can be anything that you want to send to the + terminal to highlight this area. The escape sequence + specified with the "stop" argument is written after the + highlighted area. This should undo the "start" argument. + Otherwise the screen will look messed up. + + The {term-list} can have two forms: + + 1. A string with escape sequences. + This is any string of characters, except that it can't start with + "t_" and blanks are not allowed. The <> notation is recognized + here, so you can use things like "<Esc>" and "<Space>". Example: + start=<Esc>[27h;<Esc>[<Space>r; + + 2. A list of terminal codes. + Each terminal code has the form "t_xx", where "xx" is the name of + the termcap entry. The codes have to be separated with commas. + White space is not allowed. Example: + start=t_C1,t_BL + The terminal codes must exist for this to work. + + +2. highlight arguments for color terminals + +cterm={attr-list} *highlight-cterm* + See above for the description of {attr-list} |attr-list|. + The "cterm" argument is likely to be different from "term", when + colors are used. For example, in a normal terminal comments could + be underlined, in a color terminal they can be made Blue. + Note: Many terminals (e.g., DOS console) can't mix these attributes + with coloring. Use only one of "cterm=" OR "ctermfg=" OR "ctermbg=". + +ctermfg={color-nr} *highlight-ctermfg* *E421* +ctermbg={color-nr} *highlight-ctermbg* + The {color-nr} argument is a color number. Its range is zero to + (not including) the number given by the termcap entry "Co". + The actual color with this number depends on the type of terminal + and its settings. Sometimes the color also depends on the settings of + "cterm". For example, on some systems "cterm=bold ctermfg=3" gives + another color, on others you just get color 3. + + For an xterm this depends on your resources, and is a bit + unpredictable. See your xterm documentation for the defaults. The + colors for a color-xterm can be changed from the .Xdefaults file. + Unfortunately this means that it's not possible to get the same colors + for each user. See |xterm-color| for info about color xterms. + + The MSDOS standard colors are fixed (in a console window), so these + have been used for the names. But the meaning of color names in X11 + are fixed, so these color settings have been used, to make the + highlighting settings portable (complicated, isn't it?). The + following names are recognized, with the color number used: + + *cterm-colors* + NR-16 NR-8 COLOR NAME ~ + 0 0 Black + 1 4 DarkBlue + 2 2 DarkGreen + 3 6 DarkCyan + 4 1 DarkRed + 5 5 DarkMagenta + 6 3 Brown, DarkYellow + 7 7 LightGray, LightGrey, Gray, Grey + 8 0* DarkGray, DarkGrey + 9 4* Blue, LightBlue + 10 2* Green, LightGreen + 11 6* Cyan, LightCyan + 12 1* Red, LightRed + 13 5* Magenta, LightMagenta + 14 3* Yellow, LightYellow + 15 7* White + + The number under "NR-16" is used for 16-color terminals ('t_Co' + greater than or equal to 16). The number under "NR-8" is used for + 8-color terminals ('t_Co' less than 16). The '*' indicates that the + bold attribute is set for ctermfg. In many 8-color terminals (e.g., + "linux"), this causes the bright colors to appear. This doesn't work + for background colors! Without the '*' the bold attribute is removed. + If you want to set the bold attribute in a different way, put a + "cterm=" argument AFTER the "ctermfg=" or "ctermbg=" argument. Or use + a number instead of a color name. + + The case of the color names is ignored. + Note that for 16 color ansi style terminals (including xterms), the + numbers in the NR-8 column is used. Here '*' means 'add 8' so that Blue + is 12, DarkGray is 8 etc. + + Note that for some color terminals these names may result in the wrong + colors! + + You can also use "NONE" to remove the color. + + *:hi-normal-cterm* + When setting the "ctermfg" or "ctermbg" colors for the Normal group, + these will become the colors used for the non-highlighted text. + Example: > + :highlight Normal ctermfg=grey ctermbg=darkblue +< When setting the "ctermbg" color for the Normal group, the + 'background' option will be adjusted automatically. This causes the + highlight groups that depend on 'background' to change! This means + you should set the colors for Normal first, before setting other + colors. + When a colorscheme is being used, changing 'background' causes it to + be reloaded, which may reset all colors (including Normal). First + delete the "g:colors_name" variable when you don't want this. + + When you have set "ctermfg" or "ctermbg" for the Normal group, Vim + needs to reset the color when exiting. This is done with the "op" + termcap entry |t_op|. If this doesn't work correctly, try setting the + 't_op' option in your .vimrc. + *E419* *E420* + When Vim knows the normal foreground and background colors, "fg" and + "bg" can be used as color names. This only works after setting the + colors for the Normal group and for the MS-DOS console. Example, for + reverse video: > + :highlight Visual ctermfg=bg ctermbg=fg +< Note that the colors are used that are valid at the moment this + command are given. If the Normal group colors are changed later, the + "fg" and "bg" colors will not be adjusted. + + +3. highlight arguments for the GUI + +gui={attr-list} *highlight-gui* + These give the attributes to use in the GUI mode. + See |attr-list| for a description. + Note that "bold" can be used here and by using a bold font. They + have the same effect. + Note that the attributes are ignored for the "Normal" group. + +font={font-name} *highlight-font* + font-name is the name of a font, as it is used on the system Vim + runs on. For X11 this is a complicated name, for example: > + font=-misc-fixed-bold-r-normal--14-130-75-75-c-70-iso8859-1 +< + The font-name "NONE" can be used to revert to the default font. + When setting the font for the "Normal" group, this becomes the default + font (until the 'guifont' option is changed; the last one set is + used). + The following only works with Motif and Athena, not with other GUIs: + When setting the font for the "Menu" group, the menus will be changed. + When setting the font for the "Tooltip" group, the tooltips will be + changed. + All fonts used, except for Menu and Tooltip, should be of the same + character size as the default font! Otherwise redrawing problems will + occur. + +guifg={color-name} *highlight-guifg* +guibg={color-name} *highlight-guibg* +guisp={color-name} *highlight-guisp* + These give the foreground (guifg), background (guibg) and special + (guisp) color to use in the GUI. "guisp" is used for undercurl. + There are a few special names: + NONE no color (transparent) + bg use normal background color + background use normal background color + fg use normal foreground color + foreground use normal foreground color + To use a color name with an embedded space or other special character, + put it in single quotes. The single quote cannot be used then. + Example: > + :hi comment guifg='salmon pink' +< + *gui-colors* + Suggested color names (these are available on most systems): + Red LightRed DarkRed + Green LightGreen DarkGreen SeaGreen + Blue LightBlue DarkBlue SlateBlue + Cyan LightCyan DarkCyan + Magenta LightMagenta DarkMagenta + Yellow LightYellow Brown DarkYellow + Gray LightGray DarkGray + Black White + Orange Purple Violet + + In the Win32 GUI version, additional system colors are available. See + |win32-colors|. + + You can also specify a color by its Red, Green and Blue values. + The format is "#rrggbb", where + "rr" is the Red value + "gg" is the Green value + "bb" is the Blue value + All values are hexadecimal, range from "00" to "ff". Examples: > + :highlight Comment guifg=#11f0c3 guibg=#ff00ff +< + *highlight-groups* *highlight-default* +These are the default highlighting groups. These groups are used by the +'highlight' option default. Note that the highlighting depends on the value +of 'background'. You can see the current settings with the ":highlight" +command. + *hl-ColorColumn* +ColorColumn used for the columns set with 'colorcolumn' + *hl-Conceal* +Conceal placeholder characters substituted for concealed + text (see 'conceallevel') + *hl-Cursor* +Cursor the character under the cursor + *hl-CursorIM* +CursorIM like Cursor, but used when in IME mode |CursorIM| + *hl-CursorColumn* +CursorColumn the screen column that the cursor is in when 'cursorcolumn' is + set + *hl-CursorLine* +CursorLine the screen line that the cursor is in when 'cursorline' is + set + *hl-Directory* +Directory directory names (and other special names in listings) + *hl-DiffAdd* +DiffAdd diff mode: Added line |diff.txt| + *hl-DiffChange* +DiffChange diff mode: Changed line |diff.txt| + *hl-DiffDelete* +DiffDelete diff mode: Deleted line |diff.txt| + *hl-DiffText* +DiffText diff mode: Changed text within a changed line |diff.txt| + *hl-ErrorMsg* +ErrorMsg error messages on the command line + *hl-VertSplit* +VertSplit the column separating vertically split windows + *hl-Folded* +Folded line used for closed folds + *hl-FoldColumn* +FoldColumn 'foldcolumn' + *hl-SignColumn* +SignColumn column where |signs| are displayed + *hl-IncSearch* +IncSearch 'incsearch' highlighting; also used for the text replaced with + ":s///c" + *hl-LineNr* +LineNr Line number for ":number" and ":#" commands, and when 'number' + or 'relativenumber' option is set. + *hl-CursorLineNr* +CursorLineNr Like LineNr when 'cursorline' or 'relativenumber' is set for + the cursor line. + *hl-MatchParen* +MatchParen The character under the cursor or just before it, if it + is a paired bracket, and its match. |pi_paren.txt| + + *hl-ModeMsg* +ModeMsg 'showmode' message (e.g., "-- INSERT --") + *hl-MoreMsg* +MoreMsg |more-prompt| + *hl-NonText* +NonText '~' and '@' at the end of the window, characters from + 'showbreak' and other characters that do not really exist in + the text (e.g., ">" displayed when a double-wide character + doesn't fit at the end of the line). + *hl-Normal* +Normal normal text + *hl-Pmenu* +Pmenu Popup menu: normal item. + *hl-PmenuSel* +PmenuSel Popup menu: selected item. + *hl-PmenuSbar* +PmenuSbar Popup menu: scrollbar. + *hl-PmenuThumb* +PmenuThumb Popup menu: Thumb of the scrollbar. + *hl-Question* +Question |hit-enter| prompt and yes/no questions + *hl-Search* +Search Last search pattern highlighting (see 'hlsearch'). + Also used for highlighting the current line in the quickfix + window and similar items that need to stand out. + *hl-SpecialKey* +SpecialKey Meta and special keys listed with ":map", also for text used + to show unprintable characters in the text, 'listchars'. + Generally: text that is displayed differently from what it + really is. + *hl-SpellBad* +SpellBad Word that is not recognized by the spellchecker. |spell| + This will be combined with the highlighting used otherwise. + *hl-SpellCap* +SpellCap Word that should start with a capital. |spell| + This will be combined with the highlighting used otherwise. + *hl-SpellLocal* +SpellLocal Word that is recognized by the spellchecker as one that is + used in another region. |spell| + This will be combined with the highlighting used otherwise. + *hl-SpellRare* +SpellRare Word that is recognized by the spellchecker as one that is + hardly ever used. |spell| + This will be combined with the highlighting used otherwise. + *hl-StatusLine* +StatusLine status line of current window + *hl-StatusLineNC* +StatusLineNC status lines of not-current windows + Note: if this is equal to "StatusLine" Vim will use "^^^" in + the status line of the current window. + *hl-TabLine* +TabLine tab pages line, not active tab page label + *hl-TabLineFill* +TabLineFill tab pages line, where there are no labels + *hl-TabLineSel* +TabLineSel tab pages line, active tab page label + *hl-Title* +Title titles for output from ":set all", ":autocmd" etc. + *hl-Visual* +Visual Visual mode selection + *hl-VisualNOS* +VisualNOS Visual mode selection when vim is "Not Owning the Selection". + Only X11 Gui's |gui-x11| and |xterm-clipboard| supports this. + *hl-WarningMsg* +WarningMsg warning messages + *hl-WildMenu* +WildMenu current match in 'wildmenu' completion + + *hl-User1* *hl-User1..9* *hl-User9* +The 'statusline' syntax allows the use of 9 different highlights in the +statusline and ruler (via 'rulerformat'). The names are User1 to User9. + +For the GUI you can use the following groups to set the colors for the menu, +scrollbars and tooltips. They don't have defaults. This doesn't work for the +Win32 GUI. Only three highlight arguments have any effect here: font, guibg, +and guifg. + + *hl-Menu* +Menu Current font, background and foreground colors of the menus. + Also used for the toolbar. + Applicable highlight arguments: font, guibg, guifg. + + NOTE: For Motif and Athena the font argument actually + specifies a fontset at all times, no matter if 'guifontset' is + empty, and as such it is tied to the current |:language| when + set. + + *hl-Scrollbar* +Scrollbar Current background and foreground of the main window's + scrollbars. + Applicable highlight arguments: guibg, guifg. + + *hl-Tooltip* +Tooltip Current font, background and foreground of the tooltips. + Applicable highlight arguments: font, guibg, guifg. + + NOTE: For Motif and Athena the font argument actually + specifies a fontset at all times, no matter if 'guifontset' is + empty, and as such it is tied to the current |:language| when + set. + +============================================================================== +13. Linking groups *:hi-link* *:highlight-link* *E412* *E413* + +When you want to use the same highlighting for several syntax groups, you +can do this more easily by linking the groups into one common highlight +group, and give the color attributes only for that group. + +To set a link: + + :hi[ghlight][!] [default] link {from-group} {to-group} + +To remove a link: + + :hi[ghlight][!] [default] link {from-group} NONE + +Notes: *E414* +- If the {from-group} and/or {to-group} doesn't exist, it is created. You + don't get an error message for a non-existing group. +- As soon as you use a ":highlight" command for a linked group, the link is + removed. +- If there are already highlight settings for the {from-group}, the link is + not made, unless the '!' is given. For a ":highlight link" command in a + sourced file, you don't get an error message. This can be used to skip + links for groups that already have settings. + + *:hi-default* *:highlight-default* +The [default] argument is used for setting the default highlighting for a +group. If highlighting has already been specified for the group the command +will be ignored. Also when there is an existing link. + +Using [default] is especially useful to overrule the highlighting of a +specific syntax file. For example, the C syntax file contains: > + :highlight default link cComment Comment +If you like Question highlighting for C comments, put this in your vimrc file: > + :highlight link cComment Question +Without the "default" in the C syntax file, the highlighting would be +overruled when the syntax file is loaded. + +============================================================================== +14. Cleaning up *:syn-clear* *E391* + +If you want to clear the syntax stuff for the current buffer, you can use this +command: > + :syntax clear + +This command should be used when you want to switch off syntax highlighting, +or when you want to switch to using another syntax. It's normally not needed +in a syntax file itself, because syntax is cleared by the autocommands that +load the syntax file. +The command also deletes the "b:current_syntax" variable, since no syntax is +loaded after this command. + +If you want to disable syntax highlighting for all buffers, you need to remove +the autocommands that load the syntax files: > + :syntax off + +What this command actually does, is executing the command > + :source $VIMRUNTIME/syntax/nosyntax.vim +See the "nosyntax.vim" file for details. Note that for this to work +$VIMRUNTIME must be valid. See |$VIMRUNTIME|. + +To clean up specific syntax groups for the current buffer: > + :syntax clear {group-name} .. +This removes all patterns and keywords for {group-name}. + +To clean up specific syntax group lists for the current buffer: > + :syntax clear @{grouplist-name} .. +This sets {grouplist-name}'s contents to an empty list. + + *:syntax-reset* *:syn-reset* +If you have changed the colors and messed them up, use this command to get the +defaults back: > + + :syntax reset + +This doesn't change the colors for the 'highlight' option. + +Note that the syntax colors that you set in your vimrc file will also be reset +back to their Vim default. +Note that if you are using a color scheme, the colors defined by the color +scheme for syntax highlighting will be lost. + +What this actually does is: > + + let g:syntax_cmd = "reset" + runtime! syntax/syncolor.vim + +Note that this uses the 'runtimepath' option. + + *syncolor* +If you want to use different colors for syntax highlighting, you can add a Vim +script file to set these colors. Put this file in a directory in +'runtimepath' which comes after $VIMRUNTIME, so that your settings overrule +the default colors. This way these colors will be used after the ":syntax +reset" command. + +For Unix you can use the file ~/.vim/after/syntax/syncolor.vim. Example: > + + if &background == "light" + highlight comment ctermfg=darkgreen guifg=darkgreen + else + highlight comment ctermfg=green guifg=green + endif + + *E679* +Do make sure this syncolor.vim script does not use a "syntax on", set the +'background' option or uses a "colorscheme" command, because it results in an +endless loop. + +Note that when a color scheme is used, there might be some confusion whether +your defined colors are to be used or the colors from the scheme. This +depends on the color scheme file. See |:colorscheme|. + + *syntax_cmd* +The "syntax_cmd" variable is set to one of these values when the +syntax/syncolor.vim files are loaded: + "on" ":syntax on" command. Highlight colors are overruled but + links are kept + "enable" ":syntax enable" command. Only define colors for groups that + don't have highlighting yet. Use ":syntax default". + "reset" ":syntax reset" command or loading a color scheme. Define all + the colors. + "skip" Don't define colors. Used to skip the default settings when a + syncolor.vim file earlier in 'runtimepath' has already set + them. + +============================================================================== +15. Highlighting tags *tag-highlight* + +If you want to highlight all the tags in your file, you can use the following +mappings. + + <F11> -- Generate tags.vim file, and highlight tags. + <F12> -- Just highlight tags based on existing tags.vim file. +> + :map <F11> :sp tags<CR>:%s/^\([^ :]*:\)\=\([^ ]*\).*/syntax keyword Tag \2/<CR>:wq! tags.vim<CR>/^<CR><F12> + :map <F12> :so tags.vim<CR> + +WARNING: The longer the tags file, the slower this will be, and the more +memory Vim will consume. + +Only highlighting typedefs, unions and structs can be done too. For this you +must use Exuberant ctags (found at http://ctags.sf.net). + +Put these lines in your Makefile: + +# Make a highlight file for types. Requires Exuberant ctags and awk +types: types.vim +types.vim: *.[ch] + ctags --c-kinds=gstu -o- *.[ch] |\ + awk 'BEGIN{printf("syntax keyword Type\t")}\ + {printf("%s ", $$1)}END{print ""}' > $@ + +And put these lines in your .vimrc: > + + " load the types.vim highlighting file, if it exists + autocmd BufRead,BufNewFile *.[ch] let fname = expand('<afile>:p:h') . '/types.vim' + autocmd BufRead,BufNewFile *.[ch] if filereadable(fname) + autocmd BufRead,BufNewFile *.[ch] exe 'so ' . fname + autocmd BufRead,BufNewFile *.[ch] endif + +============================================================================== +16. Window-local syntax *:ownsyntax* + +Normally all windows on a buffer share the same syntax settings. It is +possible, however, to set a particular window on a file to have its own +private syntax setting. A possible example would be to edit LaTeX source +with conventional highlighting in one window, while seeing the same source +highlighted differently (so as to hide control sequences and indicate bold, +italic etc regions) in another. The 'scrollbind' option is useful here. + +To set the current window to have the syntax "foo", separately from all other +windows on the buffer: > + :ownsyntax foo +< *w:current_syntax* +This will set the "w:current_syntax" variable to "foo". The value of +"b:current_syntax" does not change. This is implemented by saving and +restoring "b:current_syntax", since the syntax files do set +"b:current_syntax". The value set by the syntax file is assigned to +"w:current_syntax". +Note: This resets the 'spell', 'spellcapcheck' and 'spellfile' options. + +Once a window has its own syntax, syntax commands executed from other windows +on the same buffer (including :syntax clear) have no effect. Conversely, +syntax commands executed from that window do not affect other windows on the +same buffer. + +A window with its own syntax reverts to normal behavior when another buffer +is loaded into that window or the file is reloaded. +When splitting the window, the new window will use the original syntax. + +============================================================================== +17. Color xterms *xterm-color* *color-xterm* + +Most color xterms have only eight colors. If you don't get colors with the +default setup, it should work with these lines in your .vimrc: > + :if &term =~ "xterm" + : if has("terminfo") + : set t_Co=8 + : set t_Sf=<Esc>[3%p1%dm + : set t_Sb=<Esc>[4%p1%dm + : else + : set t_Co=8 + : set t_Sf=<Esc>[3%dm + : set t_Sb=<Esc>[4%dm + : endif + :endif +< [<Esc> is a real escape, type CTRL-V <Esc>] + +You might want to change the first "if" to match the name of your terminal, +e.g. "dtterm" instead of "xterm". + +Note: Do these settings BEFORE doing ":syntax on". Otherwise the colors may +be wrong. + *xiterm* *rxvt* +The above settings have been mentioned to work for xiterm and rxvt too. +But for using 16 colors in an rxvt these should work with terminfo: > + :set t_AB=<Esc>[%?%p1%{8}%<%t25;%p1%{40}%+%e5;%p1%{32}%+%;%dm + :set t_AF=<Esc>[%?%p1%{8}%<%t22;%p1%{30}%+%e1;%p1%{22}%+%;%dm +< + *colortest.vim* +To test your color setup, a file has been included in the Vim distribution. +To use it, execute this command: > + :runtime syntax/colortest.vim + +Some versions of xterm (and other terminals, like the Linux console) can +output lighter foreground colors, even though the number of colors is defined +at 8. Therefore Vim sets the "cterm=bold" attribute for light foreground +colors, when 't_Co' is 8. + + *xfree-xterm* +To get 16 colors or more, get the newest xterm version (which should be +included with XFree86 3.3 and later). You can also find the latest version +at: > + http://invisible-island.net/xterm/xterm.html +Here is a good way to configure it. This uses 88 colors and enables the +termcap-query feature, which allows Vim to ask the xterm how many colors it +supports. > + ./configure --disable-bold-color --enable-88-color --enable-tcap-query +If you only get 8 colors, check the xterm compilation settings. +(Also see |UTF8-xterm| for using this xterm with UTF-8 character encoding). + +This xterm should work with these lines in your .vimrc (for 16 colors): > + :if has("terminfo") + : set t_Co=16 + : set t_AB=<Esc>[%?%p1%{8}%<%t%p1%{40}%+%e%p1%{92}%+%;%dm + : set t_AF=<Esc>[%?%p1%{8}%<%t%p1%{30}%+%e%p1%{82}%+%;%dm + :else + : set t_Co=16 + : set t_Sf=<Esc>[3%dm + : set t_Sb=<Esc>[4%dm + :endif +< [<Esc> is a real escape, type CTRL-V <Esc>] + +Without |+terminfo|, Vim will recognize these settings, and automatically +translate cterm colors of 8 and above to "<Esc>[9%dm" and "<Esc>[10%dm". +Colors above 16 are also translated automatically. + +For 256 colors this has been reported to work: > + + :set t_AB=<Esc>[48;5;%dm + :set t_AF=<Esc>[38;5;%dm + +Or just set the TERM environment variable to "xterm-color" or "xterm-16color" +and try if that works. + +You probably want to use these X resources (in your ~/.Xdefaults file): + XTerm*color0: #000000 + XTerm*color1: #c00000 + XTerm*color2: #008000 + XTerm*color3: #808000 + XTerm*color4: #0000c0 + XTerm*color5: #c000c0 + XTerm*color6: #008080 + XTerm*color7: #c0c0c0 + XTerm*color8: #808080 + XTerm*color9: #ff6060 + XTerm*color10: #00ff00 + XTerm*color11: #ffff00 + XTerm*color12: #8080ff + XTerm*color13: #ff40ff + XTerm*color14: #00ffff + XTerm*color15: #ffffff + Xterm*cursorColor: Black + +[Note: The cursorColor is required to work around a bug, which changes the +cursor color to the color of the last drawn text. This has been fixed by a +newer version of xterm, but not everybody is using it yet.] + +To get these right away, reload the .Xdefaults file to the X Option database +Manager (you only need to do this when you just changed the .Xdefaults file): > + xrdb -merge ~/.Xdefaults +< + *xterm-blink* *xterm-blinking-cursor* +To make the cursor blink in an xterm, see tools/blink.c. Or use Thomas +Dickey's xterm above patchlevel 107 (see above for where to get it), with +these resources: + XTerm*cursorBlink: on + XTerm*cursorOnTime: 400 + XTerm*cursorOffTime: 250 + XTerm*cursorColor: White + + *hpterm-color* +These settings work (more or less) for an hpterm, which only supports 8 +foreground colors: > + :if has("terminfo") + : set t_Co=8 + : set t_Sf=<Esc>[&v%p1%dS + : set t_Sb=<Esc>[&v7S + :else + : set t_Co=8 + : set t_Sf=<Esc>[&v%dS + : set t_Sb=<Esc>[&v7S + :endif +< [<Esc> is a real escape, type CTRL-V <Esc>] + + *Eterm* *enlightened-terminal* +These settings have been reported to work for the Enlightened terminal +emulator, or Eterm. They might work for all xterm-like terminals that use the +bold attribute to get bright colors. Add an ":if" like above when needed. > + :set t_Co=16 + :set t_AF=^[[%?%p1%{8}%<%t3%p1%d%e%p1%{22}%+%d;1%;m + :set t_AB=^[[%?%p1%{8}%<%t4%p1%d%e%p1%{32}%+%d;1%;m +< + *TTpro-telnet* +These settings should work for TTpro telnet. Tera Term Pro is a freeware / +open-source program for MS-Windows. > + set t_Co=16 + set t_AB=^[[%?%p1%{8}%<%t%p1%{40}%+%e%p1%{32}%+5;%;%dm + set t_AF=^[[%?%p1%{8}%<%t%p1%{30}%+%e%p1%{22}%+1;%;%dm +Also make sure TTpro's Setup / Window / Full Color is enabled, and make sure +that Setup / Font / Enable Bold is NOT enabled. +(info provided by John Love-Jensen <eljay@Adobe.COM>) + + +============================================================================== +18. When syntax is slow *:syntime* + +This is aimed at authors of a syntax file. + +If your syntax causes redrawing to be slow, here are a few hints on making it +faster. To see slowness switch on some features that usually interfere, such +as 'relativenumber' and |folding|. + +Note: this is only available when compiled with the |+profile| feature. +You many need to build Vim with "huge" features. + +To find out what patterns are consuming most time, get an overview with this +sequence: > + :syntime on + [ redraw the text at least once with CTRL-L ] + :syntime report + +This will display a list of syntax patterns that were used, sorted by the time +it took to match them against the text. + +:syntime on Start measuring syntax times. This will add some + overhead to compute the time spent on syntax pattern + matching. + +:syntime off Stop measuring syntax times. + +:syntime clear Set all the counters to zero, restart measuring. + +:syntime report Show the syntax items used since ":syntime on" in the + current window. Use a wider display to see more of + the output. + + The list is sorted by total time. The columns are: + TOTAL Total time in seconds spent on + matching this pattern. + COUNT Number of times the pattern was used. + MATCH Number of times the pattern actually + matched + SLOWEST The longest time for one try. + AVERAGE The average time for one try. + NAME Name of the syntax item. Note that + this is not unique. + PATTERN The pattern being used. + +Pattern matching gets slow when it has to try many alternatives. Try to +include as much literal text as possible to reduce the number of ways a +pattern does NOT match. + +When using the "\@<=" and "\@<!" items, add a maximum size to avoid trying at +all positions in the current and previous line. For example, if the item is +literal text specify the size of that text (in bytes): + +"<\@<=span" Matches "span" in "<span". This tries matching with "<" in + many places. +"<\@1<=span" Matches the same, but only tries one byte before "span". + + + vim:tw=78:sw=4:ts=8:ft=help:norl: diff --git a/en/tabpage.txt b/en/tabpage.txt new file mode 100644 index 000000000..b98c18b02 --- /dev/null +++ b/en/tabpage.txt @@ -0,0 +1,434 @@ +*tabpage.txt* For Vim version 7.4. Last change: 2015 Jan 04 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Editing with windows in multiple tab pages. *tab-page* *tabpage* + +The commands which have been added to use multiple tab pages are explained +here. Additionally, there are explanations for commands that work differently +when used in combination with more than one tab page. + +1. Introduction |tab-page-intro| +2. Commands |tab-page-commands| +3. Other items |tab-page-other| +4. Setting 'tabline' |setting-tabline| +5. Setting 'guitablabel' |setting-guitablabel| + +{Vi does not have any of these commands} +{not able to use multiple tab pages when the |+windows| feature was disabled +at compile time} + +============================================================================== +1. Introduction *tab-page-intro* + +A tab page holds one or more windows. You can easily switch between tab +pages, so that you have several collections of windows to work on different +things. + +Usually you will see a list of labels at the top of the Vim window, one for +each tab page. With the mouse you can click on the label to jump to that tab +page. There are other ways to move between tab pages, see below. + +Most commands work only in the current tab page. That includes the |CTRL-W| +commands, |:windo|, |:all| and |:ball| (when not using the |:tab| modifier). +The commands that are aware of other tab pages than the current one are +mentioned below. + +Tabs are also a nice way to edit a buffer temporarily without changing the +current window layout. Open a new tab page, do whatever you want to do and +close the tab page. + +============================================================================== +2. Commands *tab-page-commands* + +OPENING A NEW TAB PAGE: + +When starting Vim "vim -p filename ..." opens each file argument in a separate +tab page (up to 'tabpagemax'). See |-p| + +A double click with the mouse in the non-GUI tab pages line opens a new, empty +tab page. It is placed left of the position of the click. The first click +may select another tab page first, causing an extra screen update. + +This also works in a few GUI versions, esp. Win32 and Motif. But only when +clicking right of the labels. + +In the GUI tab pages line you can use the right mouse button to open menu. +|tabline-menu|. + +:[count]tabe[dit] *:tabe* *:tabedit* *:tabnew* +:[count]tabnew + Open a new tab page with an empty window, after the current + tab page. If [count] is given the new tab page appears after + the tab page [count] otherwise the new tab page will appear + after the current one. > + :tabnew " opens tabpage after the current one + :.tabnew " as above + :+tabnew " opens tabpage after the next tab page + " note: it is one further than :tabnew + :-tabnew " opens tabpage before the current one + :0tabnew " opens tabpage before the first one + :$tabnew " opens tabpage after the last one + +:[count]tabe[dit] [++opt] [+cmd] {file} +:[count]tabnew [++opt] [+cmd] {file} + Open a new tab page and edit {file}, like with |:edit|. + For [count] see |:tabnew| above. + +:[count]tabf[ind] [++opt] [+cmd] {file} *:tabf* *:tabfind* + Open a new tab page and edit {file} in 'path', like with + |:find|. For [count] see |:tabnew| above. + {not available when the |+file_in_path| feature was disabled + at compile time} + +:[count]tab {cmd} *:tab* + Execute {cmd} and when it opens a new window open a new tab + page instead. Doesn't work for |:diffsplit|, |:diffpatch|, + |:execute| and |:normal|. + When [count] is omitted the tab page appears after the current + one. + When [count] is specified the new tab page comes after tab + page [count]. Use ":0tab cmd" to get the new tab page as the + first one. + Examples: > + :tab split " opens current buffer in new tab page + :tab help gt " opens tab page with help for "gt" + +CTRL-W gf Open a new tab page and edit the file name under the cursor. + See |CTRL-W_gf|. + +CTRL-W gF Open a new tab page and edit the file name under the cursor + and jump to the line number following the file name. + See |CTRL-W_gF|. + +CLOSING A TAB PAGE: + +Closing the last window of a tab page closes the tab page too, unless there is +only one tab page. + +Using the mouse: If the tab page line is displayed you can click in the "X" at +the top right to close the current tab page. A custom |'tabline'| may show +something else. + + *:tabc* *:tabclose* +:tabc[lose][!] Close current tab page. + This command fails when: + - There is only one tab page on the screen. *E784* + - When 'hidden' is not set, [!] is not used, a buffer has + changes, and there is no other window on this buffer. + Changes to the buffer are not written and won't get lost, so + this is a "safe" command. > + :tabclose " close the current tab page + +:{count}tabc[lose][!] +:tabc[lose][!] {count} + Close tab page {count}. Fails in the same way as `:tabclose` + above. > + :-tabclose " close the previous tab page + :+tabclose " close the next tab page + :1tabclose " close the first tab page + :$tabclose " close the last tab page +< + *:tabo* *:tabonly* +:tabo[nly][!] Close all other tab pages. + When the 'hidden' option is set, all buffers in closed windows + become hidden. + When 'hidden' is not set, and the 'autowrite' option is set, + modified buffers are written. Otherwise, windows that have + buffers that are modified are not removed, unless the [!] is + given, then they become hidden. But modified buffers are + never abandoned, so changes cannot get lost. > + :tabonly " close all tab pages except the current + +:{count}tabo[nly][!] + Close all tab pages except the {count}th one. > + :.tabonly " one + :-tabonly " close all tab pages except the previous + " one + :+tabonly " close all tab pages except the next one + :1tabonly " close all tab pages except the first one + :$tabonly " close all tab pages except the last one + + +SWITCHING TO ANOTHER TAB PAGE: + +Using the mouse: If the tab page line is displayed you can click in a tab page +label to switch to that tab page. Click where there is no label to go to the +next tab page. |'tabline'| + +:tabn[ext] *:tabn* *:tabnext* *gt* +<C-PageDown> *CTRL-<PageDown>* *<C-PageDown>* +gt *i_CTRL-<PageDown>* *i_<C-PageDown>* + Go to the next tab page. Wraps around from the last to the + first one. + +:tabn[ext] {count} +{count}<C-PageDown> +{count}gt Go to tab page {count}. The first tab page has number one. + + +:tabp[revious] *:tabp* *:tabprevious* *gT* *:tabN* +:tabN[ext] *:tabNext* *CTRL-<PageUp>* +<C-PageUp> *<C-PageUp>* *i_CTRL-<PageUp>* *i_<C-PageUp>* +gT Go to the previous tab page. Wraps around from the first one + to the last one. + +:tabp[revious] {count} +:tabN[ext] {count} +{count}<C-PageUp> +{count}gT Go {count} tab pages back. Wraps around from the first one + to the last one. + +:tabr[ewind] *:tabfir* *:tabfirst* *:tabr* *:tabrewind* +:tabfir[st] Go to the first tab page. + + *:tabl* *:tablast* +:tabl[ast] Go to the last tab page. + + +Other commands: + *:tabs* +:tabs List the tab pages and the windows they contain. + Shows a ">" for the current window. + Shows a "+" for modified buffers. + + +REORDERING TAB PAGES: + +:tabm[ove] [N] *:tabm* *:tabmove* +:[N]tabm[ove] + Move the current tab page to after tab page N. Use zero to + make the current tab page the first one. Without N the tab + page is made the last one. > + :.tabmove " do nothing + :-tabmove " move the tab page to the left + :+tabmove " move the tab page to the right + :0tabmove " move the tab page to the beginning of the tab + " list + :tabmove 0 " as above + :tabmove " move the tab page to the last + :$tabmove " as above + :tabmove $ " as above + +:tabm[ove] +[N] +:tabm[ove] -[N] + Move the current tab page N places to the right (with +) or to + the left (with -). > + :tabmove - " move the tab page to the left + :tabmove -1 " as above + :tabmove + " move the tab page to the right + :tabmove +1 " as above + + +Note that although it is possible to move a tab behind the N-th one by using +:Ntabmove. And move it by N places by using :+Ntabmove. For clarification what ++N means in this context see |[range]|. + + +LOOPING OVER TAB PAGES: + + *:tabd* *:tabdo* +:[range]tabd[o] {cmd} + Execute {cmd} in each tab page or if [range] is given only in + tab pages which tab page number is in the [range]. It works + like doing this: > + :tabfirst + :{cmd} + :tabnext + :{cmd} + etc. +< This only operates in the current window of each tab page. + When an error is detected on one tab page, further tab pages + will not be visited. + The last tab page (or where an error occurred) becomes the + current tab page. + {cmd} can contain '|' to concatenate several commands. + {cmd} must not open or close tab pages or reorder them. + {not in Vi} {not available when compiled without the + |+listcmds| feature} + Also see |:windo|, |:argdo|, |:bufdo|, |:cdo|, |:ldo|, |:cfdo| + and |:lfdo| + +============================================================================== +3. Other items *tab-page-other* + + *tabline-menu* +The GUI tab pages line has a popup menu. It is accessed with a right click. +The entries are: + Close Close the tab page under the mouse pointer. The + current one if there is no label under the mouse + pointer. + New Tab Open a tab page, editing an empty buffer. It appears + to the left of the mouse pointer. + Open Tab... Like "New Tab" and additionally use a file selector to + select a file to edit. + +Diff mode works per tab page. You can see the diffs between several files +within one tab page. Other tab pages can show differences between other +files. + +Variables local to a tab page start with "t:". |tabpage-variable| + +Currently there is only one option local to a tab page: 'cmdheight'. + +The TabLeave and TabEnter autocommand events can be used to do something when +switching from one tab page to another. The exact order depends on what you +are doing. When creating a new tab page this works as if you create a new +window on the same buffer and then edit another buffer. Thus ":tabnew" +triggers: + WinLeave leave current window + TabLeave leave current tab page + WinEnter enter window in new tab page + TabEnter enter new tab page + BufLeave leave current buffer + BufEnter enter new empty buffer + +When switching to another tab page the order is: + BufLeave + WinLeave + TabLeave + TabEnter + WinEnter + BufEnter + +============================================================================== +4. Setting 'tabline' *setting-tabline* + +The 'tabline' option specifies what the line with tab pages labels looks like. +It is only used when there is no GUI tab line. + +You can use the 'showtabline' option to specify when you want the line with +tab page labels to appear: never, when there is more than one tab page or +always. + +The highlighting of the tab pages line is set with the groups TabLine +TabLineSel and TabLineFill. |hl-TabLine| |hl-TabLineSel| |hl-TabLineFill| + +A "+" will be shown for a tab page that has a modified window. The number of +windows in a tabpage is also shown. Thus "3+" means three windows and one of +them has a modified buffer. + +The 'tabline' option allows you to define your preferred way to tab pages +labels. This isn't easy, thus an example will be given here. + +For basics see the 'statusline' option. The same items can be used in the +'tabline' option. Additionally, the |tabpagebuflist()|, |tabpagenr()| and +|tabpagewinnr()| functions are useful. + +Since the number of tab labels will vary, you need to use an expression for +the whole option. Something like: > + :set tabline=%!MyTabLine() + +Then define the MyTabLine() function to list all the tab pages labels. A +convenient method is to split it in two parts: First go over all the tab +pages and define labels for them. Then get the label for each tab page. > + + function MyTabLine() + let s = '' + for i in range(tabpagenr('$')) + " select the highlighting + if i + 1 == tabpagenr() + let s .= '%#TabLineSel#' + else + let s .= '%#TabLine#' + endif + + " set the tab page number (for mouse clicks) + let s .= '%' . (i + 1) . 'T' + + " the label is made by MyTabLabel() + let s .= ' %{MyTabLabel(' . (i + 1) . ')} ' + endfor + + " after the last tab fill with TabLineFill and reset tab page nr + let s .= '%#TabLineFill#%T' + + " right-align the label to close the current tab page + if tabpagenr('$') > 1 + let s .= '%=%#TabLine#%999Xclose' + endif + + return s + endfunction + +Now the MyTabLabel() function is called for each tab page to get its label. > + + function MyTabLabel(n) + let buflist = tabpagebuflist(a:n) + let winnr = tabpagewinnr(a:n) + return bufname(buflist[winnr - 1]) + endfunction + +This is just a simplistic example that results in a tab pages line that +resembles the default, but without adding a + for a modified buffer or +truncating the names. You will want to reduce the width of labels in a +clever way when there is not enough room. Check the 'columns' option for the +space available. + +============================================================================== +5. Setting 'guitablabel' *setting-guitablabel* + +When the GUI tab pages line is displayed, 'guitablabel' can be used to +specify the label to display for each tab page. Unlike 'tabline', which +specifies the whole tab pages line at once, 'guitablabel' is used for each +label separately. + +'guitabtooltip' is very similar and is used for the tooltip of the same label. +This only appears when the mouse pointer hovers over the label, thus it +usually is longer. Only supported on some systems though. + +See the 'statusline' option for the format of the value. + +The "%N" item can be used for the current tab page number. The |v:lnum| +variable is also set to this number when the option is evaluated. +The items that use a file name refer to the current window of the tab page. + +Note that syntax highlighting is not used for the option. The %T and %X +items are also ignored. + +A simple example that puts the tab page number and the buffer name in the +label: > + :set guitablabel=%N\ %f + +An example that resembles the default 'guitablabel': Show the number of +windows in the tab page and a '+' if there is a modified buffer: > + + function GuiTabLabel() + let label = '' + let bufnrlist = tabpagebuflist(v:lnum) + + " Add '+' if one of the buffers in the tab page is modified + for bufnr in bufnrlist + if getbufvar(bufnr, "&modified") + let label = '+' + break + endif + endfor + + " Append the number of windows in the tab page if more than one + let wincount = tabpagewinnr(v:lnum, '$') + if wincount > 1 + let label .= wincount + endif + if label != '' + let label .= ' ' + endif + + " Append the buffer name + return label . bufname(bufnrlist[tabpagewinnr(v:lnum) - 1]) + endfunction + + set guitablabel=%{GuiTabLabel()} + +Note that the function must be defined before setting the option, otherwise +you get an error message for the function not being known. + +If you want to fall back to the default label, return an empty string. + +If you want to show something specific for a tab page, you might want to use a +tab page local variable. |t:var| + + + vim:tw=78:ts=8:ft=help:norl: diff --git a/en/tagsrch.txt b/en/tagsrch.txt new file mode 100644 index 000000000..86a00f409 --- /dev/null +++ b/en/tagsrch.txt @@ -0,0 +1,842 @@ +*tagsrch.txt* For Vim version 7.4. Last change: 2013 Oct 01 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Tags and special searches *tags-and-searches* + +See section |29.1| of the user manual for an introduction. + +1. Jump to a tag |tag-commands| +2. Tag stack |tag-stack| +3. Tag match list |tag-matchlist| +4. Tags details |tag-details| +5. Tags file format |tags-file-format| +6. Include file searches |include-search| + +============================================================================== +1. Jump to a tag *tag-commands* + + *tag* *tags* +A tag is an identifier that appears in a "tags" file. It is a sort of label +that can be jumped to. For example: In C programs each function name can be +used as a tag. The "tags" file has to be generated by a program like ctags, +before the tag commands can be used. + +With the ":tag" command the cursor will be positioned on the tag. With the +CTRL-] command, the keyword on which the cursor is standing is used as the +tag. If the cursor is not on a keyword, the first keyword to the right of the +cursor is used. + +The ":tag" command works very well for C programs. If you see a call to a +function and wonder what that function does, position the cursor inside of the +function name and hit CTRL-]. This will bring you to the function definition. +An easy way back is with the CTRL-T command. Also read about the tag stack +below. + + *:ta* *:tag* *E426* *E429* +:[count]ta[g][!] {ident} + Jump to the definition of {ident}, using the + information in the tags file(s). Put {ident} in the + tag stack. See |tag-!| for [!]. + {ident} can be a regexp pattern, see |tag-regexp|. + When there are several matching tags for {ident}, jump + to the [count] one. When [count] is omitted the + first one is jumped to. See |tag-matchlist| for + jumping to other matching tags. + +g<LeftMouse> *g<LeftMouse>* +<C-LeftMouse> *<C-LeftMouse>* *CTRL-]* +CTRL-] Jump to the definition of the keyword under the + cursor. Same as ":tag {ident}", where {ident} is the + keyword under or after cursor. + When there are several matching tags for {ident}, jump + to the [count] one. When no [count] is given the + first one is jumped to. See |tag-matchlist| for + jumping to other matching tags. + {Vi: identifier after the cursor} + + *v_CTRL-]* +{Visual}CTRL-] Same as ":tag {ident}", where {ident} is the text that + is highlighted. {not in Vi} + + *telnet-CTRL-]* +CTRL-] is the default telnet escape key. When you type CTRL-] to jump to a +tag, you will get the telnet prompt instead. Most versions of telnet allow +changing or disabling the default escape key. See the telnet man page. You +can 'telnet -E {Hostname}' to disable the escape character, or 'telnet -e +{EscapeCharacter} {Hostname}' to specify another escape character. If +possible, try to use "ssh" instead of "telnet" to avoid this problem. + + *tag-priority* +When there are multiple matches for a tag, this priority is used: +1. "FSC" A full matching static tag for the current file. +2. "F C" A full matching global tag for the current file. +3. "F " A full matching global tag for another file. +4. "FS " A full matching static tag for another file. +5. " SC" An ignore-case matching static tag for the current file. +6. " C" An ignore-case matching global tag for the current file. +7. " " An ignore-case matching global tag for another file. +8. " S " An ignore-case matching static tag for another file. + +Note that when the current file changes, the priority list is mostly not +changed, to avoid confusion when using ":tnext". It is changed when using +":tag {ident}". + +The ignore-case matches are not found for a ":tag" command when the +'ignorecase' option is off and 'tagcase' is "followic" or when 'tagcase' is +"match". They are found when a pattern is used (starting with a "/") and for +":tselect", also when 'ignorecase' is off and 'tagcase' is "followic" or when +'tagcase' is "match". Note that using ignore-case tag searching disables +binary searching in the tags file, which causes a slowdown. This can be +avoided by fold-case sorting the tag file. See the 'tagbsearch' option for an +explanation. + +============================================================================== +2. Tag stack *tag-stack* *tagstack* *E425* + +On the tag stack is remembered which tags you jumped to, and from where. +Tags are only pushed onto the stack when the 'tagstack' option is set. + +g<RightMouse> *g<RightMouse>* +<C-RightMouse> *<C-RightMouse>* *CTRL-T* +CTRL-T Jump to [count] older entry in the tag stack + (default 1). {not in Vi} + + *:po* *:pop* *E555* *E556* +:[count]po[p][!] Jump to [count] older entry in tag stack (default 1). + See |tag-!| for [!]. {not in Vi} + +:[count]ta[g][!] Jump to [count] newer entry in tag stack (default 1). + See |tag-!| for [!]. {not in Vi} + + *:tags* +:tags Show the contents of the tag stack. The active + entry is marked with a '>'. {not in Vi} + +The output of ":tags" looks like this: + + # TO tag FROM line in file/text + 1 1 main 1 harddisk2:text/vim/test + > 2 2 FuncA 58 i = FuncA(10); + 3 1 FuncC 357 harddisk2:text/vim/src/amiga.c + +This list shows the tags that you jumped to and the cursor position before +that jump. The older tags are at the top, the newer at the bottom. + +The '>' points to the active entry. This is the tag that will be used by the +next ":tag" command. The CTRL-T and ":pop" command will use the position +above the active entry. + +Below the "TO" is the number of the current match in the match list. Note +that this doesn't change when using ":pop" or ":tag". + +The line number and file name are remembered to be able to get back to where +you were before the tag command. The line number will be correct, also when +deleting/inserting lines, unless this was done by another program (e.g. +another instance of Vim). + +For the current file, the "file/text" column shows the text at the position. +An indent is removed and a long line is truncated to fit in the window. + +You can jump to previously used tags with several commands. Some examples: + + ":pop" or CTRL-T to position before previous tag + {count}CTRL-T to position before {count} older tag + ":tag" to newer tag + ":0tag" to last used tag + +The most obvious way to use this is while browsing through the call graph of +a program. Consider the following call graph: + + main ---> FuncA ---> FuncC + ---> FuncB + +(Explanation: main calls FuncA and FuncB; FuncA calls FuncC). +You can get from main to FuncA by using CTRL-] on the call to FuncA. Then +you can CTRL-] to get to FuncC. If you now want to go back to main you can +use CTRL-T twice. Then you can CTRL-] to FuncB. + +If you issue a ":ta {ident}" or CTRL-] command, this tag is inserted at the +current position in the stack. If the stack was full (it can hold up to 20 +entries), the oldest entry is deleted and the older entries shift one +position up (their index number is decremented by one). If the last used +entry was not at the bottom, the entries below the last used one are +deleted. This means that an old branch in the call graph is lost. After the +commands explained above the tag stack will look like this: + + # TO tag FROM line in file/text + 1 1 main 1 harddisk2:text/vim/test + 2 1 FuncB 59 harddisk2:text/vim/src/main.c + + *E73* +When you try to use the tag stack while it doesn't contain anything you will +get an error message. + +============================================================================== +3. Tag match list *tag-matchlist* *E427* *E428* + +When there are several matching tags, these commands can be used to jump +between them. Note that these commands don't change the tag stack, they keep +the same entry. + + *:ts* *:tselect* +:ts[elect][!] [ident] List the tags that match [ident], using the + information in the tags file(s). + When [ident] is not given, the last tag name from the + tag stack is used. + With a '>' in the first column is indicated which is + the current position in the list (if there is one). + [ident] can be a regexp pattern, see |tag-regexp|. + See |tag-priority| for the priorities used in the + listing. {not in Vi} + Example output: + +> + nr pri kind tag file + 1 F f mch_delay os_amiga.c + mch_delay(msec, ignoreinput) + > 2 F f mch_delay os_msdos.c + mch_delay(msec, ignoreinput) + 3 F f mch_delay os_unix.c + mch_delay(msec, ignoreinput) + Enter nr of choice (<CR> to abort): +< + See |tag-priority| for the "pri" column. Note that + this depends on the current file, thus using + ":tselect xxx" can produce different results. + The "kind" column gives the kind of tag, if this was + included in the tags file. + The "info" column shows information that could be + found in the tags file. It depends on the program + that produced the tags file. + When the list is long, you may get the |more-prompt|. + If you already see the tag you want to use, you can + type 'q' and enter the number. + + *:sts* *:stselect* +:sts[elect][!] [ident] Does ":tselect[!] [ident]" and splits the window for + the selected tag. {not in Vi} + + *g]* +g] Like CTRL-], but use ":tselect" instead of ":tag". + {not in Vi} + + *v_g]* +{Visual}g] Same as "g]", but use the highlighted text as the + identifier. {not in Vi} + + *:tj* *:tjump* +:tj[ump][!] [ident] Like ":tselect", but jump to the tag directly when + there is only one match. {not in Vi} + + *:stj* *:stjump* +:stj[ump][!] [ident] Does ":tjump[!] [ident]" and splits the window for the + selected tag. {not in Vi} + + *g_CTRL-]* +g CTRL-] Like CTRL-], but use ":tjump" instead of ":tag". + {not in Vi} + + *v_g_CTRL-]* +{Visual}g CTRL-] Same as "g CTRL-]", but use the highlighted text as + the identifier. {not in Vi} + + *:tn* *:tnext* +:[count]tn[ext][!] Jump to [count] next matching tag (default 1). See + |tag-!| for [!]. {not in Vi} + + *:tp* *:tprevious* +:[count]tp[revious][!] Jump to [count] previous matching tag (default 1). + See |tag-!| for [!]. {not in Vi} + + *:tN* *:tNext* +:[count]tN[ext][!] Same as ":tprevious". {not in Vi} + + *:tr* *:trewind* +:[count]tr[ewind][!] Jump to first matching tag. If [count] is given, jump + to [count]th matching tag. See |tag-!| for [!]. {not + in Vi} + + *:tf* *:tfirst* +:[count]tf[irst][!] Same as ":trewind". {not in Vi} + + *:tl* *:tlast* +:tl[ast][!] Jump to last matching tag. See |tag-!| for [!]. {not + in Vi} + + *:lt* *:ltag* +:lt[ag][!] [ident] Jump to tag [ident] and add the matching tags to a new + location list for the current window. [ident] can be + a regexp pattern, see |tag-regexp|. When [ident] is + not given, the last tag name from the tag stack is + used. The search pattern to locate the tag line is + prefixed with "\V" to escape all the special + characters (very nomagic). The location list showing + the matching tags is independent of the tag stack. + See |tag-!| for [!]. + {not in Vi} + +When there is no other message, Vim shows which matching tag has been jumped +to, and the number of matching tags: > + tag 1 of 3 or more +The " or more" is used to indicate that Vim didn't try all the tags files yet. +When using ":tnext" a few times, or with ":tlast", more matches may be found. + +When you didn't see this message because of some other message, or you just +want to know where you are, this command will show it again (and jump to the +same tag as last time): > + :0tn +< + *tag-skip-file* +When a matching tag is found for which the file doesn't exist, this match is +skipped and the next matching tag is used. Vim reports this, to notify you of +missing files. When the end of the list of matches has been reached, an error +message is given. + + *tag-preview* +The tag match list can also be used in the preview window. The commands are +the same as above, with a "p" prepended. +{not available when compiled without the |+quickfix| feature} + + *:pts* *:ptselect* +:pts[elect][!] [ident] Does ":tselect[!] [ident]" and shows the new tag in a + "Preview" window. See |:ptag| for more info. + {not in Vi} + + *:ptj* *:ptjump* +:ptj[ump][!] [ident] Does ":tjump[!] [ident]" and shows the new tag in a + "Preview" window. See |:ptag| for more info. + {not in Vi} + + *:ptn* *:ptnext* +:[count]ptn[ext][!] ":tnext" in the preview window. See |:ptag|. + {not in Vi} + + *:ptp* *:ptprevious* +:[count]ptp[revious][!] ":tprevious" in the preview window. See |:ptag|. + {not in Vi} + + *:ptN* *:ptNext* +:[count]ptN[ext][!] Same as ":ptprevious". {not in Vi} + + *:ptr* *:ptrewind* +:[count]ptr[ewind][!] ":trewind" in the preview window. See |:ptag|. + {not in Vi} + + *:ptf* *:ptfirst* +:[count]ptf[irst][!] Same as ":ptrewind". {not in Vi} + + *:ptl* *:ptlast* +:ptl[ast][!] ":tlast" in the preview window. See |:ptag|. + {not in Vi} + +============================================================================== +4. Tags details *tag-details* + + *static-tag* +A static tag is a tag that is defined for a specific file. In a C program +this could be a static function. + +In Vi jumping to a tag sets the current search pattern. This means that +the "n" command after jumping to a tag does not search for the same pattern +that it did before jumping to the tag. Vim does not do this as we consider it +to be a bug. You can still find the tag search pattern in the search history. +If you really want the old Vi behavior, set the 't' flag in 'cpoptions'. + + *tag-binary-search* +Vim uses binary searching in the tags file to find the desired tag quickly +(when enabled at compile time |+tag_binary|). But this only works if the +tags file was sorted on ASCII byte value. Therefore, if no match was found, +another try is done with a linear search. If you only want the linear search, +reset the 'tagbsearch' option. Or better: Sort the tags file! + +Note that the binary searching is disabled when not looking for a tag with a +specific name. This happens when ignoring case and when a regular expression +is used that doesn't start with a fixed string. Tag searching can be a lot +slower then. The former can be avoided by case-fold sorting the tags file. +See 'tagbsearch' for details. + + *tag-regexp* +The ":tag" and ":tselect" commands accept a regular expression argument. See +|pattern| for the special characters that can be used. +When the argument starts with '/', it is used as a pattern. If the argument +does not start with '/', it is taken literally, as a full tag name. +Examples: > + :tag main +< jumps to the tag "main" that has the highest priority. > + :tag /^get +< jumps to the tag that starts with "get" and has the highest priority. > + :tag /norm +< lists all the tags that contain "norm", including "id_norm". +When the argument both exists literally, and match when used as a regexp, a +literal match has a higher priority. For example, ":tag /open" matches "open" +before "open_file" and "file_open". +When using a pattern case is ignored. If you want to match case use "\C" in +the pattern. + + *tag-!* +If the tag is in the current file this will always work. Otherwise the +performed actions depend on whether the current file was changed, whether a ! +is added to the command and on the 'autowrite' option: + + tag in file autowrite ~ +current file changed ! option action ~ +----------------------------------------------------------------------------- + yes x x x goto tag + no no x x read other file, goto tag + no yes yes x abandon current file, read other file, goto + tag + no yes no on write current file, read other file, goto + tag + no yes no off fail +----------------------------------------------------------------------------- + +- If the tag is in the current file, the command will always work. +- If the tag is in another file and the current file was not changed, the + other file will be made the current file and read into the buffer. +- If the tag is in another file, the current file was changed and a ! is + added to the command, the changes to the current file are lost, the other + file will be made the current file and read into the buffer. +- If the tag is in another file, the current file was changed and the + 'autowrite' option is on, the current file will be written, the other + file will be made the current file and read into the buffer. +- If the tag is in another file, the current file was changed and the + 'autowrite' option is off, the command will fail. If you want to save + the changes, use the ":w" command and then use ":tag" without an argument. + This works because the tag is put on the stack anyway. If you want to lose + the changes you can use the ":tag!" command. + + *tag-security* +Note that Vim forbids some commands, for security reasons. This works like +using the 'secure' option for exrc/vimrc files in the current directory. See +|trojan-horse| and |sandbox|. +When the {tagaddress} changes a buffer, you will get a warning message: + "WARNING: tag command changed a buffer!!!" +In a future version changing the buffer will be impossible. All this for +security reasons: Somebody might hide a nasty command in the tags file, which +would otherwise go unnoticed. Example: > + :$d|/tag-function-name/ +{this security prevention is not present in Vi} + +In Vi the ":tag" command sets the last search pattern when the tag is searched +for. In Vim this is not done, the previous search pattern is still remembered, +unless the 't' flag is present in 'cpoptions'. The search pattern is always +put in the search history, so you can modify it if searching fails. + + *emacs-tags* *emacs_tags* *E430* +Emacs style tag files are only supported if Vim was compiled with the +|+emacs_tags| feature enabled. Sorry, there is no explanation about Emacs tag +files here, it is only supported for backwards compatibility :-). + +Lines in Emacs tags files can be very long. Vim only deals with lines of up +to about 510 bytes. To see whether lines are ignored set 'verbose' to 5 or +higher. + + *tags-option* +The 'tags' option is a list of file names. Each of these files is searched +for the tag. This can be used to use a different tags file than the default +file "tags". It can also be used to access a common tags file. + +The next file in the list is not used when: +- A matching static tag for the current buffer has been found. +- A matching global tag has been found. +This also depends on whether case is ignored. Case is ignored when +'ignorecase' is set and 'tagcase' is "followic", or when 'tagcase' is +"ignore". If case is not ignored, and the tags file only has a match without +matching case, the next tags file is searched for a match with matching case. +If no tag with matching case is found, the first match without matching case +is used. If case is ignored, and a matching global tag with or without +matching case is found, this one is used, no further tags files are searched. + +When a tag file name starts with "./", the '.' is replaced with the path of +the current file. This makes it possible to use a tags file in the directory +where the current file is (no matter what the current directory is). The idea +of using "./" is that you can define which tag file is searched first: In the +current directory ("tags,./tags") or in the directory of the current file +("./tags,tags"). + +For example: > + :set tags=./tags,tags,/home/user/commontags + +In this example the tag will first be searched for in the file "tags" in the +directory where the current file is. Next the "tags" file in the current +directory. If it is not found there, then the file "/home/user/commontags" +will be searched for the tag. + +This can be switched off by including the 'd' flag in 'cpoptions', to make +it Vi compatible. "./tags" will then be the tags file in the current +directory, instead of the tags file in the directory where the current file +is. + +Instead of the comma a space may be used. Then a backslash is required for +the space to be included in the string option: > + :set tags=tags\ /home/user/commontags + +To include a space in a file name use three backslashes. To include a comma +in a file name use two backslashes. For example, use: > + :set tags=tag\\\ file,/home/user/common\\,tags + +for the files "tag file" and "/home/user/common,tags". The 'tags' option will +have the value "tag\ file,/home/user/common\,tags". + +If the 'tagrelative' option is on (which is the default) and using a tag file +in another directory, file names in that tag file are relative to the +directory where the tag file is. + +============================================================================== +5. Tags file format *tags-file-format* *E431* + + *ctags* *jtags* +A tags file can be created with an external command, for example "ctags". It +will contain a tag for each function. Some versions of "ctags" will also make +a tag for each "#defined" macro, typedefs, enums, etc. + +Some programs that generate tags files: +ctags As found on most Unix systems. Only supports C. Only + does the basic work. + *Exuberant_ctags* +exuberant ctags This a very good one. It works for C, C++, Java, + Fortran, Eiffel and others. It can generate tags for + many items. See http://ctags.sourceforge.net. +etags Connected to Emacs. Supports many languages. +JTags For Java, in Java. It can be found at + http://www.fleiner.com/jtags/. +ptags.py For Python, in Python. Found in your Python source + directory at Tools/scripts/ptags.py. +ptags For Perl, in Perl. It can be found at + http://www.eleves.ens.fr:8080/home/nthiery/Tags/. +gnatxref For Ada. See http://www.gnuada.org/. gnatxref is + part of the gnat package. + + +The lines in the tags file must have one of these three formats: + +1. {tagname} {TAB} {tagfile} {TAB} {tagaddress} +2. {tagfile}:{tagname} {TAB} {tagfile} {TAB} {tagaddress} +3. {tagname} {TAB} {tagfile} {TAB} {tagaddress} {term} {field} .. + +The first is a normal tag, which is completely compatible with Vi. It is the +only format produced by traditional ctags implementations. This is often used +for functions that are global, also referenced in other files. + +The lines in the tags file can end in <LF> or <CR><LF>. On the Macintosh <CR> +also works. The <CR> and <NL> characters can never appear inside a line. + + *tag-old-static* +The second format is for a static tag only. It is obsolete now, replaced by +the third format. It is only supported by Elvis 1.x and Vim and a few +versions of ctags. A static tag is often used for functions that are local, +only referenced in the file {tagfile}. Note that for the static tag, the two +occurrences of {tagfile} must be exactly the same. Also see |tags-option| +below, for how static tags are used. + +The third format is new. It includes additional information in optional +fields at the end of each line. It is backwards compatible with Vi. It is +only supported by new versions of ctags (such as Exuberant ctags). + +{tagname} The identifier. Normally the name of a function, but it can + be any identifier. It cannot contain a <Tab>. +{TAB} One <Tab> character. Note: previous versions allowed any + white space here. This has been abandoned to allow spaces in + {tagfile}. It can be re-enabled by including the + |+tag_any_white| feature at compile time. *tag-any-white* +{tagfile} The file that contains the definition of {tagname}. It can + have an absolute or relative path. It may contain environment + variables and wildcards (although the use of wildcards is + doubtful). It cannot contain a <Tab>. +{tagaddress} The Ex command that positions the cursor on the tag. It can + be any Ex command, although restrictions apply (see + |tag-security|). Posix only allows line numbers and search + commands, which are mostly used. +{term} ;" The two characters semicolon and double quote. This is + interpreted by Vi as the start of a comment, which makes the + following be ignored. This is for backwards compatibility + with Vi, it ignores the following fields. +{field} .. A list of optional fields. Each field has the form: + + <Tab>{fieldname}:{value} + + The {fieldname} identifies the field, and can only contain + alphabetical characters [a-zA-Z]. + The {value} is any string, but cannot contain a <Tab>. + These characters are special: + "\t" stands for a <Tab> + "\r" stands for a <CR> + "\n" stands for a <NL> + "\\" stands for a single '\' character + + There is one field that doesn't have a ':'. This is the kind + of the tag. It is handled like it was preceded with "kind:". + See the documentation of ctags for the kinds it produces. + + The only other field currently recognized by Vim is "file:" + (with an empty value). It is used for a static tag. + +The first lines in the tags file can contain lines that start with + !_TAG_ +These are sorted to the first lines, only rare tags that start with "!" can +sort to before them. Vim recognizes two items. The first one is the line +that indicates if the file was sorted. When this line is found, Vim uses +binary searching for the tags file: + !_TAG_FILE_SORTED<Tab>1<Tab>{anything} ~ + +A tag file may be case-fold sorted to avoid a linear search when case is +ignored. (Case is ignored when 'ignorecase' is set and 'tagcase' is +"followic", or when 'tagcase' is "ignore".) See 'tagbsearch' for details. +The value '2' should be used then: + !_TAG_FILE_SORTED<Tab>2<Tab>{anything} ~ + +The other tag that Vim recognizes, but only when compiled with the +|+multi_byte| feature, is the encoding of the tags file: + !_TAG_FILE_ENCODING<Tab>utf-8<Tab>{anything} ~ +Here "utf-8" is the encoding used for the tags. Vim will then convert the tag +being searched for from 'encoding' to the encoding of the tags file. And when +listing tags the reverse happens. When the conversion fails the unconverted +tag is used. + + *tag-search* +The command can be any Ex command, but often it is a search command. +Examples: + tag1 file1 /^main(argc, argv)/ ~ + tag2 file2 108 ~ + +The command is always executed with 'magic' not set. The only special +characters in a search pattern are "^" (begin-of-line) and "$" (<EOL>). +See |pattern|. Note that you must put a backslash before each backslash in +the search text. This is for backwards compatibility with Vi. + + *E434* *E435* +If the command is a normal search command (it starts and ends with "/" or +"?"), some special handling is done: +- Searching starts on line 1 of the file. + The direction of the search is forward for "/", backward for "?". + Note that 'wrapscan' does not matter, the whole file is always searched. (Vi + does use 'wrapscan', which caused tags sometimes not be found.) {Vi starts + searching in line 2 of another file. It does not find a tag in line 1 of + another file when 'wrapscan' is not set} +- If the search fails, another try is done ignoring case. If that fails too, + a search is done for: + "^tagname[ \t]*(" + (the tag with '^' prepended and "[ \t]*(" appended). When using function + names, this will find the function name when it is in column 0. This will + help when the arguments to the function have changed since the tags file was + made. If this search also fails another search is done with: + "^[#a-zA-Z_].*\<tagname[ \t]*(" + This means: A line starting with '#' or an identifier and containing the tag + followed by white space and a '('. This will find macro names and function + names with a type prepended. {the extra searches are not in Vi} + +============================================================================== +6. Include file searches *include-search* *definition-search* + *E387* *E388* *E389* + +These commands look for a string in the current file and in all encountered +included files (recursively). This can be used to find the definition of a +variable, function or macro. If you only want to search in the current +buffer, use the commands listed at |pattern-searches|. + +These commands are not available when the |+find_in_path| feature was disabled +at compile time. + +When a line is encountered that includes another file, that file is searched +before continuing in the current buffer. Files included by included files are +also searched. When an include file could not be found it is silently +ignored. Use the |:checkpath| command to discover which files could not be +found, possibly your 'path' option is not set up correctly. Note: the +included file is searched, not a buffer that may be editing that file. Only +for the current file the lines in the buffer are used. + +The string can be any keyword or a defined macro. For the keyword any match +will be found. For defined macros only lines that match with the 'define' +option will be found. The default is "^#\s*define", which is for C programs. +For other languages you probably want to change this. See 'define' for an +example for C++. The string cannot contain an end-of-line, only matches +within a line are found. + +When a match is found for a defined macro, the displaying of lines continues +with the next line when a line ends in a backslash. + +The commands that start with "[" start searching from the start of the current +file. The commands that start with "]" start at the current cursor position. + +The 'include' option is used to define a line that includes another file. The +default is "\^#\s*include", which is for C programs. Note: Vim does not +recognize C syntax, if the 'include' option matches a line inside +"#ifdef/#endif" or inside a comment, it is searched anyway. The 'isfname' +option is used to recognize the file name that comes after the matched +pattern. + +The 'path' option is used to find the directory for the include files that +do not have an absolute path. + +The 'comments' option is used for the commands that display a single line or +jump to a line. It defines patterns that may start a comment. Those lines +are ignored for the search, unless [!] is used. One exception: When the line +matches the pattern "^# *define" it is not considered to be a comment. + +If you want to list matches, and then select one to jump to, you could use a +mapping to do that for you. Here is an example: > + + :map <F4> [I:let nr = input("Which one: ")<Bar>exe "normal " . nr ."[\t"<CR> +< + *[i* +[i Display the first line that contains the keyword + under the cursor. The search starts at the beginning + of the file. Lines that look like a comment are + ignored (see 'comments' option). If a count is given, + the count'th matching line is displayed, and comment + lines are not ignored. {not in Vi} + + *]i* +]i like "[i", but start at the current cursor position. + {not in Vi} + + *:is* *:isearch* +:[range]is[earch][!] [count] [/]pattern[/] + Like "[i" and "]i", but search in [range] lines + (default: whole file). + See |:search-args| for [/] and [!]. {not in Vi} + + *[I* +[I Display all lines that contain the keyword under the + cursor. Filenames and line numbers are displayed + for the found lines. The search starts at the + beginning of the file. {not in Vi} + + *]I* +]I like "[I", but start at the current cursor position. + {not in Vi} + + *:il* *:ilist* +:[range]il[ist][!] [/]pattern[/] + Like "[I" and "]I", but search in [range] lines + (default: whole file). + See |:search-args| for [/] and [!]. {not in Vi} + + *[_CTRL-I* +[ CTRL-I Jump to the first line that contains the keyword + under the cursor. The search starts at the beginning + of the file. Lines that look like a comment are + ignored (see 'comments' option). If a count is given, + the count'th matching line is jumped to, and comment + lines are not ignored. {not in Vi} + + *]_CTRL-I* +] CTRL-I like "[ CTRL-I", but start at the current cursor + position. {not in Vi} + + *:ij* *:ijump* +:[range]ij[ump][!] [count] [/]pattern[/] + Like "[ CTRL-I" and "] CTRL-I", but search in + [range] lines (default: whole file). + See |:search-args| for [/] and [!]. {not in Vi} + +CTRL-W CTRL-I *CTRL-W_CTRL-I* *CTRL-W_i* +CTRL-W i Open a new window, with the cursor on the first line + that contains the keyword under the cursor. The + search starts at the beginning of the file. Lines + that look like a comment line are ignored (see + 'comments' option). If a count is given, the count'th + matching line is jumped to, and comment lines are not + ignored. {not in Vi} + + *:isp* *:isplit* +:[range]isp[lit][!] [count] [/]pattern[/] + Like "CTRL-W i" and "CTRL-W i", but search in + [range] lines (default: whole file). + See |:search-args| for [/] and [!]. {not in Vi} + + *[d* +[d Display the first macro definition that contains the + macro under the cursor. The search starts from the + beginning of the file. If a count is given, the + count'th matching line is displayed. {not in Vi} + + *]d* +]d like "[d", but start at the current cursor position. + {not in Vi} + + *:ds* *:dsearch* +:[range]ds[earch][!] [count] [/]string[/] + Like "[d" and "]d", but search in [range] lines + (default: whole file). + See |:search-args| for [/] and [!]. {not in Vi} + + *[D* +[D Display all macro definitions that contain the macro + under the cursor. Filenames and line numbers are + displayed for the found lines. The search starts + from the beginning of the file. {not in Vi} + + *]D* +]D like "[D", but start at the current cursor position. + {not in Vi} + + *:dli* *:dlist* +:[range]dli[st][!] [/]string[/] + Like `[D` and `]D`, but search in [range] lines + (default: whole file). + See |:search-args| for [/] and [!]. {not in Vi} + Note that `:dl` works like `:delete` with the "l" + flag, not `:dlist`. + + *[_CTRL-D* +[ CTRL-D Jump to the first macro definition that contains the + keyword under the cursor. The search starts from + the beginning of the file. If a count is given, the + count'th matching line is jumped to. {not in Vi} + + *]_CTRL-D* +] CTRL-D like "[ CTRL-D", but start at the current cursor + position. {not in Vi} + + *:dj* *:djump* +:[range]dj[ump][!] [count] [/]string[/] + Like "[ CTRL-D" and "] CTRL-D", but search in + [range] lines (default: whole file). + See |:search-args| for [/] and [!]. {not in Vi} + +CTRL-W CTRL-D *CTRL-W_CTRL-D* *CTRL-W_d* +CTRL-W d Open a new window, with the cursor on the first + macro definition line that contains the keyword + under the cursor. The search starts from the + beginning of the file. If a count is given, the + count'th matching line is jumped to. {not in Vi} + + *:dsp* *:dsplit* +:[range]dsp[lit][!] [count] [/]string[/] + Like "CTRL-W d", but search in [range] lines + (default: whole file). + See |:search-args| for [/] and [!]. {not in Vi} + + *:che* *:checkpath* +:che[ckpath] List all the included files that could not be found. + {not in Vi} + +:che[ckpath]! List all the included files. {not in Vi} + + *:search-args* +Common arguments for the commands above: +[!] When included, find matches in lines that are recognized as comments. + When excluded, a match is ignored when the line is recognized as a + comment (according to 'comments'), or the match is in a C comment (after + "//" or inside /* */). Note that a match may be missed if a line is + recognized as a comment, but the comment ends halfway the line. + And if the line is a comment, but it is not recognized (according to + 'comments') a match may be found in it anyway. Example: > + /* comment + foobar */ +< A match for "foobar" is found, because this line is not recognized as a + comment (even though syntax highlighting does recognize it). + Note: Since a macro definition mostly doesn't look like a comment, the + [!] makes no difference for ":dlist", ":dsearch" and ":djump". +[/] A pattern can be surrounded by '/'. Without '/' only whole words are + matched, using the pattern "\<pattern\>". Only after the second '/' a + next command can be appended with '|'. Example: > + :isearch /string/ | echo "the last one" +< For a ":djump", ":dsplit", ":dlist" and ":dsearch" command the pattern + is used as a literal string, not as a search pattern. + + vim:tw=78:ts=8:ft=help:norl: diff --git a/en/term.txt b/en/term.txt new file mode 100644 index 000000000..a56813ac0 --- /dev/null +++ b/en/term.txt @@ -0,0 +1,889 @@ +*term.txt* For Vim version 7.4. Last change: 2015 Nov 24 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Terminal information *terminal-info* + +Vim uses information about the terminal you are using to fill the screen and +recognize what keys you hit. If this information is not correct, the screen +may be messed up or keys may not be recognized. The actions which have to be +performed on the screen are accomplished by outputting a string of +characters. Special keys produce a string of characters. These strings are +stored in the terminal options, see |terminal-options|. + +NOTE: Most of this is not used when running the |GUI|. + +1. Startup |startup-terminal| +2. Terminal options |terminal-options| +3. Window size |window-size| +4. Slow and fast terminals |slow-fast-terminal| +5. Using the mouse |mouse-using| + +============================================================================== +1. Startup *startup-terminal* + +When Vim is started a default terminal type is assumed. For the Amiga this is +a standard CLI window, for MS-DOS the pc terminal, for Unix an ansi terminal. +A few other terminal types are always available, see below |builtin-terms|. + +You can give the terminal name with the '-T' Vim argument. If it is not given +Vim will try to get the name from the TERM environment variable. + + *termcap* *terminfo* *E557* *E558* *E559* +On Unix the terminfo database or termcap file is used. This is referred to as +"termcap" in all the documentation. At compile time, when running configure, +the choice whether to use terminfo or termcap is done automatically. When +running Vim the output of ":version" will show |+terminfo| if terminfo is +used. Also see |xterm-screens|. + +On non-Unix systems a termcap is only available if Vim was compiled with +TERMCAP defined. + + *builtin-terms* *builtin_terms* +Which builtin terminals are available depends on a few defines in feature.h, +which need to be set at compile time: + define output of ":version" terminals builtin ~ +NO_BUILTIN_TCAPS -builtin_terms none +SOME_BUILTIN_TCAPS +builtin_terms most common ones (default) +ALL_BUILTIN_TCAPS ++builtin_terms all available + +You can see a list of available builtin terminals with ":set term=xxx" (when +not running the GUI). Also see |+builtin_terms|. + +If the termcap code is included Vim will try to get the strings for the +terminal you are using from the termcap file and the builtin termcaps. Both +are always used, if an entry for the terminal you are using is present. Which +one is used first depends on the 'ttybuiltin' option: + +'ttybuiltin' on 1: builtin termcap 2: external termcap +'ttybuiltin' off 1: external termcap 2: builtin termcap + +If an option is missing in one of them, it will be obtained from the other +one. If an option is present in both, the one first encountered is used. + +Which external termcap file is used varies from system to system and may +depend on the environment variables "TERMCAP" and "TERMPATH". See "man +tgetent". + +Settings depending on terminal *term-dependent-settings* + +If you want to set options or mappings, depending on the terminal name, you +can do this best in your .vimrc. Example: > + + if &term == "xterm" + ... xterm maps and settings ... + elseif &term =~ "vt10." + ... vt100, vt102 maps and settings ... + endif +< + *raw-terminal-mode* +For normal editing the terminal will be put into "raw" mode. The strings +defined with 't_ti' and 't_ks' will be sent to the terminal. Normally this +puts the terminal in a state where the termcap codes are valid and activates +the cursor and function keys. When Vim exits the terminal will be put back +into the mode it was before Vim started. The strings defined with 't_te' and +'t_ke' will be sent to the terminal. On the Amiga, with commands that execute +an external command (e.g., "!!"), the terminal will be put into Normal mode +for a moment. This means that you can stop the output to the screen by +hitting a printing key. Output resumes when you hit <BS>. + + *cs7-problem* +Note: If the terminal settings are changed after running Vim, you might have +an illegal combination of settings. This has been reported on Solaris 2.5 +with "stty cs8 parenb", which is restored as "stty cs7 parenb". Use +"stty cs8 -parenb -istrip" instead, this is restored correctly. + +Some termcap entries are wrong in the sense that after sending 't_ks' the +cursor keys send codes different from the codes defined in the termcap. To +avoid this you can set 't_ks' (and 't_ke') to empty strings. This must be +done during initialization (see |initialization|), otherwise it's too late. + +Some termcap entries assume that the highest bit is always reset. For +example: The cursor-up entry for the Amiga could be ":ku=\E[A:". But the +Amiga really sends "\233A". This works fine if the highest bit is reset, +e.g., when using an Amiga over a serial line. If the cursor keys don't work, +try the entry ":ku=\233A:". + +Some termcap entries have the entry ":ku=\E[A:". But the Amiga really sends +"\233A". On output "\E[" and "\233" are often equivalent, on input they +aren't. You will have to change the termcap entry, or change the key code with +the :set command to fix this. + +Many cursor key codes start with an <Esc>. Vim must find out if this is a +single hit of the <Esc> key or the start of a cursor key sequence. It waits +for a next character to arrive. If it does not arrive within one second a +single <Esc> is assumed. On very slow systems this may fail, causing cursor +keys not to work sometimes. If you discover this problem reset the 'timeout' +option. Vim will wait for the next character to arrive after an <Esc>. If +you want to enter a single <Esc> you must type it twice. Resetting the +'esckeys' option avoids this problem in Insert mode, but you lose the +possibility to use cursor and function keys in Insert mode. + +On the Amiga the recognition of window resizing is activated only when the +terminal name is "amiga" or "builtin_amiga". + +Some terminals have confusing codes for the cursor keys. The televideo 925 is +such a terminal. It sends a CTRL-H for cursor-left. This would make it +impossible to distinguish a backspace and cursor-left. To avoid this problem +CTRL-H is never recognized as cursor-left. + + *vt100-cursor-keys* *xterm-cursor-keys* +Other terminals (e.g., vt100 and xterm) have cursor keys that send <Esc>OA, +<Esc>OB, etc. Unfortunately these are valid commands in insert mode: Stop +insert, Open a new line above the new one, start inserting 'A', 'B', etc. +Instead of performing these commands Vim will erroneously recognize this typed +key sequence as a cursor key movement. To avoid this and make Vim do what you +want in either case you could use these settings: > + :set notimeout " don't timeout on mappings + :set ttimeout " do timeout on terminal key codes + :set timeoutlen=100 " timeout after 100 msec +This requires the key-codes to be sent within 100 msec in order to recognize +them as a cursor key. When you type you normally are not that fast, so they +are recognized as individual typed commands, even though Vim receives the same +sequence of bytes. + + *vt100-function-keys* *xterm-function-keys* +An xterm can send function keys F1 to F4 in two modes: vt100 compatible or +not. Because Vim may not know what the xterm is sending, both types of keys +are recognized. The same happens for the <Home> and <End> keys. + normal vt100 ~ + <F1> t_k1 <Esc>[11~ <xF1> <Esc>OP *<xF1>-xterm* + <F2> t_k2 <Esc>[12~ <xF2> <Esc>OQ *<xF2>-xterm* + <F3> t_k3 <Esc>[13~ <xF3> <Esc>OR *<xF3>-xterm* + <F4> t_k4 <Esc>[14~ <xF4> <Esc>OS *<xF4>-xterm* + <Home> t_kh <Esc>[7~ <xHome> <Esc>OH *<xHome>-xterm* + <End> t_@7 <Esc>[4~ <xEnd> <Esc>OF *<xEnd>-xterm* + +When Vim starts, <xF1> is mapped to <F1>, <xF2> to <F2> etc. This means that +by default both codes do the same thing. If you make a mapping for <xF2>, +because your terminal does have two keys, the default mapping is overwritten, +thus you can use the <F2> and <xF2> keys for something different. + + *xterm-shifted-keys* +Newer versions of xterm support shifted function keys and special keys. Vim +recognizes most of them. Use ":set termcap" to check which are supported and +what the codes are. Mostly these are not in a termcap, they are only +supported by the builtin_xterm termcap. + + *xterm-modifier-keys* +Newer versions of xterm support Alt and Ctrl for most function keys. To avoid +having to add all combinations of Alt, Ctrl and Shift for every key a special +sequence is recognized at the end of a termcap entry: ";*X". The "X" can be +any character, often '~' is used. The ";*" stands for an optional modifier +argument. ";2" is Shift, ";3" is Alt, ";5" is Ctrl and ";9" is Meta (when +it's different from Alt). They can be combined. Examples: > + :set <F8>=^[[19;*~ + :set <Home>=^[[1;*H +Another speciality about these codes is that they are not overwritten by +another code. That is to avoid that the codes obtained from xterm directly +|t_RV| overwrite them. + *xterm-scroll-region* +The default termcap entry for xterm on Sun and other platforms does not +contain the entry for scroll regions. Add ":cs=\E[%i%d;%dr:" to the xterm +entry in /etc/termcap and everything should work. + + *xterm-end-home-keys* +On some systems (at least on FreeBSD with XFree86 3.1.2) the codes that the +<End> and <Home> keys send contain a <Nul> character. To make these keys send +the proper key code, add these lines to your ~/.Xdefaults file: + +*VT100.Translations: #override \n\ + <Key>Home: string("0x1b") string("[7~") \n\ + <Key>End: string("0x1b") string("[8~") + + *xterm-8bit* *xterm-8-bit* +Xterm can be run in a mode where it uses 8-bit escape sequences. The CSI code +is used instead of <Esc>[. The advantage is that an <Esc> can quickly be +recognized in Insert mode, because it can't be confused with the start of a +special key. +For the builtin termcap entries, Vim checks if the 'term' option contains +"8bit" anywhere. It then uses 8-bit characters for the termcap entries, the +mouse and a few other things. You would normally set $TERM in your shell to +"xterm-8bit" and Vim picks this up and adjusts to the 8-bit setting +automatically. +When Vim receives a response to the |t_RV| (request version) sequence and it +starts with CSI, it assumes that the terminal is in 8-bit mode and will +convert all key sequences to their 8-bit variants. + +============================================================================== +2. Terminal options *terminal-options* *termcap-options* *E436* + +The terminal options can be set just like normal options. But they are not +shown with the ":set all" command. Instead use ":set termcap". + +It is always possible to change individual strings by setting the +appropriate option. For example: > + :set t_ce=^V^[[K (CTRL-V, <Esc>, [, K) + +{Vi: no terminal options. You have to exit Vi, edit the termcap entry and +try again} + +The options are listed below. The associated termcap code is always equal to +the last two characters of the option name. Only one termcap code is +required: Cursor motion, 't_cm'. + +The options 't_da', 't_db', 't_ms', 't_xs', 't_xn' represent flags in the +termcap. When the termcap flag is present, the option will be set to "y". +But any non-empty string means that the flag is set. An empty string means +that the flag is not set. 't_CS' works like this too, but it isn't a termcap +flag. + +OUTPUT CODES + option meaning ~ + + t_AB set background color (ANSI) *t_AB* *'t_AB'* + t_AF set foreground color (ANSI) *t_AF* *'t_AF'* + t_AL add number of blank lines *t_AL* *'t_AL'* + t_al add new blank line *t_al* *'t_al'* + t_bc backspace character *t_bc* *'t_bc'* + t_cd clear to end of screen *t_cd* *'t_cd'* + t_ce clear to end of line *t_ce* *'t_ce'* + t_cl clear screen *t_cl* *'t_cl'* + t_cm cursor motion (required!) *E437* *t_cm* *'t_cm'* + t_Co number of colors *t_Co* *'t_Co'* + t_CS if non-empty, cursor relative to scroll region *t_CS* *'t_CS'* + t_cs define scrolling region *t_cs* *'t_cs'* + t_CV define vertical scrolling region *t_CV* *'t_CV'* + t_da if non-empty, lines from above scroll down *t_da* *'t_da'* + t_db if non-empty, lines from below scroll up *t_db* *'t_db'* + t_DL delete number of lines *t_DL* *'t_DL'* + t_dl delete line *t_dl* *'t_dl'* + t_fs set window title end (from status line) *t_fs* *'t_fs'* + t_ke exit "keypad transmit" mode *t_ke* *'t_ke'* + t_ks start "keypad transmit" mode *t_ks* *'t_ks'* + t_le move cursor one char left *t_le* *'t_le'* + t_mb blinking mode *t_mb* *'t_mb'* + t_md bold mode *t_md* *'t_md'* + t_me Normal mode (undoes t_mr, t_mb, t_md and color) *t_me* *'t_me'* + t_mr reverse (invert) mode *t_mr* *'t_mr'* + *t_ms* *'t_ms'* + t_ms if non-empty, cursor can be moved in standout/inverse mode + t_nd non destructive space character *t_nd* *'t_nd'* + t_op reset to original color pair *t_op* *'t_op'* + t_RI cursor number of chars right *t_RI* *'t_RI'* + t_Sb set background color *t_Sb* *'t_Sb'* + t_Sf set foreground color *t_Sf* *'t_Sf'* + t_se standout end *t_se* *'t_se'* + t_so standout mode *t_so* *'t_so'* + t_sr scroll reverse (backward) *t_sr* *'t_sr'* + t_te out of "termcap" mode *t_te* *'t_te'* + t_ti put terminal in "termcap" mode *t_ti* *'t_ti'* + t_ts set window title start (to status line) *t_ts* *'t_ts'* + t_ue underline end *t_ue* *'t_ue'* + t_us underline mode *t_us* *'t_us'* + t_Ce undercurl end *t_Ce* *'t_Ce'* + t_Cs undercurl mode *t_Cs* *'t_Cs'* + t_ut clearing uses the current background color *t_ut* *'t_ut'* + t_vb visual bell *t_vb* *'t_vb'* + t_ve cursor visible *t_ve* *'t_ve'* + t_vi cursor invisible *t_vi* *'t_vi'* + t_vs cursor very visible *t_vs* *'t_vs'* + *t_xs* *'t_xs'* + t_xs if non-empty, standout not erased by overwriting (hpterm) + *t_xn* *'t_xn'* + t_xn if non-empty, writing a character at the last screen cell + does not cause scrolling + t_ZH italics mode *t_ZH* *'t_ZH'* + t_ZR italics end *t_ZR* *'t_ZR'* + +Added by Vim (there are no standard codes for these): + t_IS set icon text start *t_IS* *'t_IS'* + t_IE set icon text end *t_IE* *'t_IE'* + t_WP set window position (Y, X) in pixels *t_WP* *'t_WP'* + t_WS set window size (height, width) in characters *t_WS* *'t_WS'* + t_SI start insert mode (bar cursor shape) *t_SI* *'t_SI'* + t_SR start replace mode (underline cursor shape) *t_SR* *'t_SR'* + t_EI end insert or replace mode (block cursor shape) *t_EI* *'t_EI'* + |termcap-cursor-shape| + t_RV request terminal version string (for xterm) *t_RV* *'t_RV'* + |xterm-8bit| |v:termresponse| |'ttymouse'| |xterm-codes| + t_u7 request cursor position (for xterm) *t_u7* *'t_u7'* + see |'ambiwidth'| + t_RB request terminal background color *t_RB* *'t_RB'* + see |'ambiwidth'| + +KEY CODES +Note: Use the <> form if possible + + option name meaning ~ + + t_ku <Up> arrow up *t_ku* *'t_ku'* + t_kd <Down> arrow down *t_kd* *'t_kd'* + t_kr <Right> arrow right *t_kr* *'t_kr'* + t_kl <Left> arrow left *t_kl* *'t_kl'* + <xUp> alternate arrow up *<xUp>* + <xDown> alternate arrow down *<xDown>* + <xRight> alternate arrow right *<xRight>* + <xLeft> alternate arrow left *<xLeft>* + <S-Up> shift arrow up + <S-Down> shift arrow down + t_%i <S-Right> shift arrow right *t_%i* *'t_%i'* + t_#4 <S-Left> shift arrow left *t_#4* *'t_#4'* + t_k1 <F1> function key 1 *t_k1* *'t_k1'* + <xF1> alternate F1 *<xF1>* + t_k2 <F2> function key 2 *<F2>* *t_k2* *'t_k2'* + <xF2> alternate F2 *<xF2>* + t_k3 <F3> function key 3 *<F3>* *t_k3* *'t_k3'* + <xF3> alternate F3 *<xF3>* + t_k4 <F4> function key 4 *<F4>* *t_k4* *'t_k4'* + <xF4> alternate F4 *<xF4>* + t_k5 <F5> function key 5 *<F5>* *t_k5* *'t_k5'* + t_k6 <F6> function key 6 *<F6>* *t_k6* *'t_k6'* + t_k7 <F7> function key 7 *<F7>* *t_k7* *'t_k7'* + t_k8 <F8> function key 8 *<F8>* *t_k8* *'t_k8'* + t_k9 <F9> function key 9 *<F9>* *t_k9* *'t_k9'* + t_k; <F10> function key 10 *<F10>* *t_k;* *'t_k;'* + t_F1 <F11> function key 11 *<F11>* *t_F1* *'t_F1'* + t_F2 <F12> function key 12 *<F12>* *t_F2* *'t_F2'* + t_F3 <F13> function key 13 *<F13>* *t_F3* *'t_F3'* + t_F4 <F14> function key 14 *<F14>* *t_F4* *'t_F4'* + t_F5 <F15> function key 15 *<F15>* *t_F5* *'t_F5'* + t_F6 <F16> function key 16 *<F16>* *t_F6* *'t_F6'* + t_F7 <F17> function key 17 *<F17>* *t_F7* *'t_F7'* + t_F8 <F18> function key 18 *<F18>* *t_F8* *'t_F8'* + t_F9 <F19> function key 19 *<F19>* *t_F9* *'t_F9'* + <S-F1> shifted function key 1 + <S-xF1> alternate <S-F1> *<S-xF1>* + <S-F2> shifted function key 2 *<S-F2>* + <S-xF2> alternate <S-F2> *<S-xF2>* + <S-F3> shifted function key 3 *<S-F3>* + <S-xF3> alternate <S-F3> *<S-xF3>* + <S-F4> shifted function key 4 *<S-F4>* + <S-xF4> alternate <S-F4> *<S-xF4>* + <S-F5> shifted function key 5 *<S-F5>* + <S-F6> shifted function key 6 *<S-F6>* + <S-F7> shifted function key 7 *<S-F7>* + <S-F8> shifted function key 8 *<S-F8>* + <S-F9> shifted function key 9 *<S-F9>* + <S-F10> shifted function key 10 *<S-F10>* + <S-F11> shifted function key 11 *<S-F11>* + <S-F12> shifted function key 12 *<S-F12>* + t_%1 <Help> help key *t_%1* *'t_%1'* + t_&8 <Undo> undo key *t_&8* *'t_&8'* + t_kI <Insert> insert key *t_kI* *'t_kI'* + t_kD <Del> delete key *t_kD* *'t_kD'* + t_kb <BS> backspace key *t_kb* *'t_kb'* + t_kB <S-Tab> back-tab (shift-tab) *<S-Tab>* *t_kB* *'t_kB'* + t_kh <Home> home key *t_kh* *'t_kh'* + t_#2 <S-Home> shifted home key *<S-Home>* *t_#2* *'t_#2'* + <xHome> alternate home key *<xHome>* + t_@7 <End> end key *t_@7* *'t_@7'* + t_*7 <S-End> shifted end key *<S-End>* *t_star7* *'t_star7'* + <xEnd> alternate end key *<xEnd>* + t_kP <PageUp> page-up key *t_kP* *'t_kP'* + t_kN <PageDown> page-down key *t_kN* *'t_kN'* + t_K1 <kHome> keypad home key *t_K1* *'t_K1'* + t_K4 <kEnd> keypad end key *t_K4* *'t_K4'* + t_K3 <kPageUp> keypad page-up key *t_K3* *'t_K3'* + t_K5 <kPageDown> keypad page-down key *t_K5* *'t_K5'* + t_K6 <kPlus> keypad plus key *<kPlus>* *t_K6* *'t_K6'* + t_K7 <kMinus> keypad minus key *<kMinus>* *t_K7* *'t_K7'* + t_K8 <kDivide> keypad divide *<kDivide>* *t_K8* *'t_K8'* + t_K9 <kMultiply> keypad multiply *<kMultiply>* *t_K9* *'t_K9'* + t_KA <kEnter> keypad enter key *<kEnter>* *t_KA* *'t_KA'* + t_KB <kPoint> keypad decimal point *<kPoint>* *t_KB* *'t_KB'* + t_KC <k0> keypad 0 *<k0>* *t_KC* *'t_KC'* + t_KD <k1> keypad 1 *<k1>* *t_KD* *'t_KD'* + t_KE <k2> keypad 2 *<k2>* *t_KE* *'t_KE'* + t_KF <k3> keypad 3 *<k3>* *t_KF* *'t_KF'* + t_KG <k4> keypad 4 *<k4>* *t_KG* *'t_KG'* + t_KH <k5> keypad 5 *<k5>* *t_KH* *'t_KH'* + t_KI <k6> keypad 6 *<k6>* *t_KI* *'t_KI'* + t_KJ <k7> keypad 7 *<k7>* *t_KJ* *'t_KJ'* + t_KK <k8> keypad 8 *<k8>* *t_KK* *'t_KK'* + t_KL <k9> keypad 9 *<k9>* *t_KL* *'t_KL'* + <Mouse> leader of mouse code *<Mouse>* + +Note about t_so and t_mr: When the termcap entry "so" is not present the +entry for "mr" is used. And vice versa. The same is done for "se" and "me". +If your terminal supports both inversion and standout mode, you can see two +different modes. If your terminal supports only one of the modes, both will +look the same. + + *keypad-comma* +The keypad keys, when they are not mapped, behave like the equivalent normal +key. There is one exception: if you have a comma on the keypad instead of a +decimal point, Vim will use a dot anyway. Use these mappings to fix that: > + :noremap <kPoint> , + :noremap! <kPoint> , +< *xterm-codes* +There is a special trick to obtain the key codes which currently only works +for xterm. When |t_RV| is defined and a response is received which indicates +an xterm with patchlevel 141 or higher, Vim uses special escape sequences to +request the key codes directly from the xterm. The responses are used to +adjust the various t_ codes. This avoids the problem that the xterm can +produce different codes, depending on the mode it is in (8-bit, VT102, +VT220, etc.). The result is that codes like <xF1> are no longer needed. +Note: This is only done on startup. If the xterm options are changed after +Vim has started, the escape sequences may not be recognized anymore. + + *xterm-resize* +Window resizing with xterm only works if the allowWindowOps resource is +enabled. On some systems and versions of xterm it's disabled by default +because someone thought it would be a security issue. It's not clear if this +is actually the case. + +To overrule the default, put this line in your ~/.Xdefaults or +~/.Xresources: +> + XTerm*allowWindowOps: true + +And run "xrdb -merge .Xresources" to make it effective. You can check the +value with the context menu (right mouse button while CTRL key is pressed), +there should be a tick at allow-window-ops. + + *termcap-colors* +Note about colors: The 't_Co' option tells Vim the number of colors available. +When it is non-zero, the 't_AB' and 't_AF' options are used to set the color. +If one of these is not available, 't_Sb' and 't_Sf' are used. 't_me' is used +to reset to the default colors. + + *termcap-cursor-shape* *termcap-cursor-color* +When Vim enters Insert mode the 't_SI' escape sequence is sent. When Vim +enters Replace mode the 't_SR' escape sequence is sent if it is set, otherwise +'t_SI' is sent. When leaving Insert mode or Replace mode 't_EI' is used. This +can be used to change the shape or color of the cursor in Insert or Replace +mode. These are not standard termcap/terminfo entries, you need to set them +yourself. +Example for an xterm, this changes the color of the cursor: > + if &term =~ "xterm" + let &t_SI = "\<Esc>]12;purple\x7" + let &t_SR = "\<Esc>]12;red\x7" + let &t_EI = "\<Esc>]12;blue\x7" + endif +NOTE: When Vim exits the shape for Normal mode will remain. The shape from +before Vim started will not be restored. +{not available when compiled without the |+cursorshape| feature} + + *termcap-title* +The 't_ts' and 't_fs' options are used to set the window title if the terminal +allows title setting via sending strings. They are sent before and after the +title string, respectively. Similar 't_IS' and 't_IE' are used to set the +icon text. These are Vim-internal extensions of the Unix termcap, so they +cannot be obtained from an external termcap. However, the builtin termcap +contains suitable entries for xterm and iris-ansi, so you don't need to set +them here. + *hpterm* +If inversion or other highlighting does not work correctly, try setting the +'t_xs' option to a non-empty string. This makes the 't_ce' code be used to +remove highlighting from a line. This is required for "hpterm". Setting the +'weirdinvert' option has the same effect as making 't_xs' non-empty, and vice +versa. + + *scroll-region* +Some termcaps do not include an entry for 'cs' (scroll region), although the +terminal does support it. For example: xterm on a Sun. You can use the +builtin_xterm or define t_cs yourself. For example: > + :set t_cs=^V^[[%i%d;%dr +Where ^V is CTRL-V and ^[ is <Esc>. + +The vertical scroll region t_CV is not a standard termcap code. Vim uses it +internally in the GUI. But it can also be defined for a terminal, if you can +find one that supports it. The two arguments are the left and right column of +the region which to restrict the scrolling to. Just like t_cs defines the top +and bottom lines. Defining t_CV will make scrolling in vertically split +windows a lot faster. Don't set t_CV when t_da or t_db is set (text isn't +cleared when scrolling). + +Unfortunately it is not possible to deduce from the termcap how cursor +positioning should be done when using a scrolling region: Relative to the +beginning of the screen or relative to the beginning of the scrolling region. +Most terminals use the first method. A known exception is the MS-DOS console +(pcterm). The 't_CS' option should be set to any string when cursor +positioning is relative to the start of the scrolling region. It should be +set to an empty string otherwise. It defaults to "yes" when 'term' is +"pcterm". + +Note for xterm users: The shifted cursor keys normally don't work. You can + make them work with the xmodmap command and some mappings in Vim. + + Give these commands in the xterm: + xmodmap -e "keysym Up = Up F13" + xmodmap -e "keysym Down = Down F16" + xmodmap -e "keysym Left = Left F18" + xmodmap -e "keysym Right = Right F19" + + And use these mappings in Vim: + :map <t_F3> <S-Up> + :map! <t_F3> <S-Up> + :map <t_F6> <S-Down> + :map! <t_F6> <S-Down> + :map <t_F8> <S-Left> + :map! <t_F8> <S-Left> + :map <t_F9> <S-Right> + :map! <t_F9> <S-Right> + +Instead of, say, <S-Up> you can use any other command that you want to use the +shift-cursor-up key for. (Note: To help people that have a Sun keyboard with +left side keys F14 is not used because it is confused with the undo key; F15 +is not used, because it does a window-to-front; F17 is not used, because it +closes the window. On other systems you can probably use them.) + +============================================================================== +3. Window size *window-size* + +[This is about the size of the whole window Vim is using, not a window that is +created with the ":split" command.] + +If you are running Vim on an Amiga and the terminal name is "amiga" or +"builtin_amiga", the amiga-specific window resizing will be enabled. On Unix +systems three methods are tried to get the window size: + +- an ioctl call (TIOCGSIZE or TIOCGWINSZ, depends on your system) +- the environment variables "LINES" and "COLUMNS" +- from the termcap entries "li" and "co" + +If everything fails a default size of 24 lines and 80 columns is assumed. If +a window-resize signal is received the size will be set again. If the window +size is wrong you can use the 'lines' and 'columns' options to set the +correct values. + +One command can be used to set the screen size: + + *:mod* *:mode* *E359* *E362* +:mod[e] [mode] + +Without argument this only detects the screen size and redraws the screen. +With MS-DOS it is possible to switch screen mode. [mode] can be one of these +values: + "bw40" 40 columns black&white + "c40" 40 columns color + "bw80" 80 columns black&white + "c80" 80 columns color (most people use this) + "mono" 80 columns monochrome + "c4350" 43 or 50 lines EGA/VGA mode + number mode number to use, depends on your video card + +============================================================================== +4. Slow and fast terminals *slow-fast-terminal* + *slow-terminal* + +If you have a fast terminal you may like to set the 'ruler' option. The +cursor position is shown in the status line. If you are using horizontal +scrolling ('wrap' option off) consider setting 'sidescroll' to a small +number. + +If you have a slow terminal you may want to reset the 'showcmd' option. +The command characters will not be shown in the status line. If the terminal +scrolls very slowly, set the 'scrolljump' to 5 or so. If the cursor is moved +off the screen (e.g., with "j") Vim will scroll 5 lines at a time. Another +possibility is to reduce the number of lines that Vim uses with the command +"z{height}<CR>". + +If the characters from the terminal are arriving with more than 1 second +between them you might want to set the 'timeout' and/or 'ttimeout' option. +See the "Options" chapter |options|. + +If your terminal does not support a scrolling region, but it does support +insert/delete line commands, scrolling with multiple windows may make the +lines jump up and down. If you don't want this set the 'ttyfast' option. +This will redraw the window instead of scroll it. + +If your terminal scrolls very slowly, but redrawing is not slow, set the +'ttyscroll' option to a small number, e.g., 3. This will make Vim redraw the +screen instead of scrolling, when there are more than 3 lines to be scrolled. + +If you are using a color terminal that is slow, use this command: > + hi NonText cterm=NONE ctermfg=NONE +This avoids that spaces are sent when they have different attributes. On most +terminals you can't see this anyway. + +If you are using Vim over a slow serial line, you might want to try running +Vim inside the "screen" program. Screen will optimize the terminal I/O quite +a bit. + +If you are testing termcap options, but you cannot see what is happening, +you might want to set the 'writedelay' option. When non-zero, one character +is sent to the terminal at a time (does not work for MS-DOS). This makes the +screen updating a lot slower, making it possible to see what is happening. + +============================================================================== +5. Using the mouse *mouse-using* + +This section is about using the mouse on a terminal or a terminal window. How +to use the mouse in a GUI window is explained in |gui-mouse|. For scrolling +with a mouse wheel see |scroll-mouse-wheel|. + +Don't forget to enable the mouse with this command: > + :set mouse=a +Otherwise Vim won't recognize the mouse in all modes (See 'mouse'). + +Currently the mouse is supported for Unix in an xterm window, in a *BSD +console with |sysmouse|, in a Linux console (with GPM |gpm-mouse|), for +MS-DOS and in a Windows console. +Mouse clicks can be used to position the cursor, select an area and paste. + +These characters in the 'mouse' option tell in which situations the mouse will +be used by Vim: + n Normal mode + v Visual mode + i Insert mode + c Command-line mode + h all previous modes when in a help file + a all previous modes + r for |hit-enter| prompt + +The default for 'mouse' is empty, the mouse is not used. Normally you would +do: > + :set mouse=a +to start using the mouse (this is equivalent to setting 'mouse' to "nvich"). +If you only want to use the mouse in a few modes or also want to use it for +the two questions you will have to concatenate the letters for those modes. +For example: > + :set mouse=nv +Will make the mouse work in Normal mode and Visual mode. > + :set mouse=h +Will make the mouse work in help files only (so you can use "g<LeftMouse>" to +jump to tags). + +Whether the selection that is started with the mouse is in Visual mode or +Select mode depends on whether "mouse" is included in the 'selectmode' +option. + +In an xterm, with the currently active mode included in the 'mouse' option, +normal mouse clicks are used by Vim, mouse clicks with the shift or ctrl key +pressed go to the xterm. With the currently active mode not included in +'mouse' all mouse clicks go to the xterm. + + *xterm-clipboard* +In the Athena and Motif GUI versions, when running in a terminal and there is +access to the X-server (DISPLAY is set), the copy and paste will behave like +in the GUI. If not, the middle mouse button will insert the unnamed register. +In that case, here is how you copy and paste a piece of text: + +Copy/paste with the mouse and Visual mode ('mouse' option must be set, see +above): +1. Press left mouse button on first letter of text, move mouse pointer to last + letter of the text and release the button. This will start Visual mode and + highlight the selected area. +2. Press "y" to yank the Visual text in the unnamed register. +3. Click the left mouse button at the insert position. +4. Click the middle mouse button. + +Shortcut: If the insert position is on the screen at the same time as the +Visual text, you can do 2, 3 and 4 all in one: Click the middle mouse button +at the insert position. + +Note: When the |-X| command line argument is used, Vim will not connect to the +X server and copy/paste to the X clipboard (selection) will not work. Use the +shift key with the mouse buttons to let the xterm do the selection. + + *xterm-command-server* +When the X-server clipboard is available, the command server described in +|x11-clientserver| can be enabled with the --servername command line argument. + + *xterm-copy-paste* +NOTE: In some (older) xterms, it's not possible to move the cursor past column +95 or 223. This is an xterm problem, not Vim's. Get a newer xterm +|color-xterm|. Also see |'ttymouse'|. + +Copy/paste in xterm with (current mode NOT included in 'mouse'): +1. Press left mouse button on first letter of text, move mouse pointer to last + letter of the text and release the button. +2. Use normal Vim commands to put the cursor at the insert position. +3. Press "a" to start Insert mode. +4. Click the middle mouse button. +5. Press ESC to end Insert mode. +(The same can be done with anything in 'mouse' if you keep the shift key +pressed while using the mouse.) + +Note: if you lose the 8th bit when pasting (special characters are translated +into other characters), you may have to do "stty cs8 -istrip -parenb" in your +shell before starting Vim. + +Thus in an xterm the shift and ctrl keys cannot be used with the mouse. Mouse +commands requiring the CTRL modifier can be simulated by typing the "g" key +before using the mouse: + "g<LeftMouse>" is "<C-LeftMouse> (jump to tag under mouse click) + "g<RightMouse>" is "<C-RightMouse> ("CTRL-T") + + *mouse-mode-table* *mouse-overview* +A short overview of what the mouse buttons do, when 'mousemodel' is "extend": + +Normal Mode: +event position selection change action ~ + cursor window ~ +<LeftMouse> yes end yes +<C-LeftMouse> yes end yes "CTRL-]" (2) +<S-LeftMouse> yes no change yes "*" (2) *<S-LeftMouse>* +<LeftDrag> yes start or extend (1) no *<LeftDrag>* +<LeftRelease> yes start or extend (1) no +<MiddleMouse> yes if not active no put +<MiddleMouse> yes if active no yank and put +<RightMouse> yes start or extend yes +<A-RightMouse> yes start or extend blockw. yes *<A-RightMouse>* +<S-RightMouse> yes no change yes "#" (2) *<S-RightMouse>* +<C-RightMouse> no no change no "CTRL-T" +<RightDrag> yes extend no *<RightDrag>* +<RightRelease> yes extend no *<RightRelease>* + +Insert or Replace Mode: +event position selection change action ~ + cursor window ~ +<LeftMouse> yes (cannot be active) yes +<C-LeftMouse> yes (cannot be active) yes "CTRL-O^]" (2) +<S-LeftMouse> yes (cannot be active) yes "CTRL-O*" (2) +<LeftDrag> yes start or extend (1) no like CTRL-O (1) +<LeftRelease> yes start or extend (1) no like CTRL-O (1) +<MiddleMouse> no (cannot be active) no put register +<RightMouse> yes start or extend yes like CTRL-O +<A-RightMouse> yes start or extend blockw. yes +<S-RightMouse> yes (cannot be active) yes "CTRL-O#" (2) +<C-RightMouse> no (cannot be active) no "CTRL-O CTRL-T" + +In a help window: +event position selection change action ~ + cursor window ~ +<2-LeftMouse> yes (cannot be active) no "^]" (jump to help tag) + +When 'mousemodel' is "popup", these are different: + +Normal Mode: +event position selection change action ~ + cursor window ~ +<S-LeftMouse> yes start or extend (1) no +<A-LeftMouse> yes start or extend blockw. no *<A-LeftMouse>* +<RightMouse> no popup menu no + +Insert or Replace Mode: +event position selection change action ~ + cursor window ~ +<S-LeftMouse> yes start or extend (1) no like CTRL-O (1) +<A-LeftMouse> yes start or extend blockw. no +<RightMouse> no popup menu no + +(1) only if mouse pointer moved since press +(2) only if click is in same buffer + +Clicking the left mouse button causes the cursor to be positioned. If the +click is in another window that window is made the active window. When +editing the command-line the cursor can only be positioned on the +command-line. When in Insert mode Vim remains in Insert mode. If 'scrolloff' +is set, and the cursor is positioned within 'scrolloff' lines from the window +border, the text is scrolled. + +A selection can be started by pressing the left mouse button on the first +character, moving the mouse to the last character, then releasing the mouse +button. You will not always see the selection until you release the button, +only in some versions (GUI, MS-DOS, WIN32) will the dragging be shown +immediately. Note that you can make the text scroll by moving the mouse at +least one character in the first/last line in the window when 'scrolloff' is +non-zero. + +In Normal, Visual and Select mode clicking the right mouse button causes the +Visual area to be extended. When 'mousemodel' is "popup", the left button has +to be used while keeping the shift key pressed. When clicking in a window +which is editing another buffer, the Visual or Select mode is stopped. + +In Normal, Visual and Select mode clicking the right mouse button with the alt +key pressed causes the Visual area to become blockwise. When 'mousemodel' is +"popup" the left button has to be used with the alt key. Note that this won't +work on systems where the window manager consumes the mouse events when the +alt key is pressed (it may move the window). + + *double-click* +Double, triple and quadruple clicks are supported when the GUI is active, +for MS-DOS and Win32, and for an xterm (if the gettimeofday() function is +available). For selecting text, extra clicks extend the selection: + click select ~ + double word or % match *<2-LeftMouse>* + triple line *<3-LeftMouse>* + quadruple rectangular block *<4-LeftMouse>* +Exception: In a Help window a double click jumps to help for the word that is +clicked on. +A double click on a word selects that word. 'iskeyword' is used to specify +which characters are included in a word. A double click on a character +that has a match selects until that match (like using "v%"). If the match is +an #if/#else/#endif block, the selection becomes linewise. +For MS-DOS and xterm the time for double clicking can be set with the +'mousetime' option. For the other systems this time is defined outside of +Vim. +An example, for using a double click to jump to the tag under the cursor: > + :map <2-LeftMouse> :exe "tag ". expand("<cword>")<CR> + +Dragging the mouse with a double click (button-down, button-up, button-down +and then drag) will result in whole words to be selected. This continues +until the button is released, at which point the selection is per character +again. + + *gpm-mouse* +The GPM mouse is only supported when the |+mouse_gpm| feature was enabled at +compile time. The GPM mouse driver (Linux console) does not support quadruple +clicks. + +In Insert mode, when a selection is started, Vim goes into Normal mode +temporarily. When Visual or Select mode ends, it returns to Insert mode. +This is like using CTRL-O in Insert mode. Select mode is used when the +'selectmode' option contains "mouse". + *sysmouse* +The sysmouse is only supported when the |+mouse_sysmouse| feature was enabled +at compile time. The sysmouse driver (*BSD console) does not support keyboard +modifiers. + + *drag-status-line* +When working with several windows, the size of the windows can be changed by +dragging the status line with the mouse. Point the mouse at a status line, +press the left button, move the mouse to the new position of the status line, +release the button. Just clicking the mouse in a status line makes that window +the current window, without moving the cursor. If by selecting a window it +will change position or size, the dragging of the status line will look +confusing, but it will work (just try it). + + *<MiddleRelease>* *<MiddleDrag>* +Mouse clicks can be mapped. The codes for mouse clicks are: + code mouse button normal action ~ + <LeftMouse> left pressed set cursor position + <LeftDrag> left moved while pressed extend selection + <LeftRelease> left released set selection end + <MiddleMouse> middle pressed paste text at cursor position + <MiddleDrag> middle moved while pressed - + <MiddleRelease> middle released - + <RightMouse> right pressed extend selection + <RightDrag> right moved while pressed extend selection + <RightRelease> right released set selection end + <X1Mouse> X1 button pressed - *X1Mouse* + <X1Drag> X1 moved while pressed - *X1Drag* + <X1Release> X1 button release - *X1Release* + <X2Mouse> X2 button pressed - *X2Mouse* + <X2Drag> X2 moved while pressed - *X2Drag* + <X2Release> X2 button release - *X2Release* + +The X1 and X2 buttons refer to the extra buttons found on some mice. The +'Microsoft Explorer' mouse has these buttons available to the right thumb. +Currently X1 and X2 only work on Win32 and X11 environments. + +Examples: > + :noremap <MiddleMouse> <LeftMouse><MiddleMouse> +Paste at the position of the middle mouse button click (otherwise the paste +would be done at the cursor position). > + + :noremap <LeftRelease> <LeftRelease>y +Immediately yank the selection, when using Visual mode. + +Note the use of ":noremap" instead of "map" to avoid a recursive mapping. +> + :map <X1Mouse> <C-O> + :map <X2Mouse> <C-I> +Map the X1 and X2 buttons to go forwards and backwards in the jump list, see +|CTRL-O| and |CTRL-I|. + + *mouse-swap-buttons* +To swap the meaning of the left and right mouse buttons: > + :noremap <LeftMouse> <RightMouse> + :noremap <LeftDrag> <RightDrag> + :noremap <LeftRelease> <RightRelease> + :noremap <RightMouse> <LeftMouse> + :noremap <RightDrag> <LeftDrag> + :noremap <RightRelease> <LeftRelease> + :noremap g<LeftMouse> <C-RightMouse> + :noremap g<RightMouse> <C-LeftMouse> + :noremap! <LeftMouse> <RightMouse> + :noremap! <LeftDrag> <RightDrag> + :noremap! <LeftRelease> <RightRelease> + :noremap! <RightMouse> <LeftMouse> + :noremap! <RightDrag> <LeftDrag> + :noremap! <RightRelease> <LeftRelease> +< + vim:tw=78:ts=8:ft=help:norl: diff --git a/en/tips.txt b/en/tips.txt new file mode 100644 index 000000000..90aa20e8b --- /dev/null +++ b/en/tips.txt @@ -0,0 +1,534 @@ +*tips.txt* For Vim version 7.4. Last change: 2009 Nov 07 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Tips and ideas for using Vim *tips* + +These are just a few that we thought would be helpful for many users. +You can find many more tips on the wiki. The URL can be found on +http://www.vim.org + +Don't forget to browse the user manual, it also contains lots of useful tips +|usr_toc.txt|. + +Editing C programs |C-editing| +Finding where identifiers are used |ident-search| +Switching screens in an xterm |xterm-screens| +Scrolling in Insert mode |scroll-insert| +Smooth scrolling |scroll-smooth| +Correcting common typing mistakes |type-mistakes| +Counting words, lines, etc. |count-items| +Restoring the cursor position |restore-position| +Renaming files |rename-files| +Change a name in multiple files |change-name| +Speeding up external commands |speed-up| +Useful mappings |useful-mappings| +Compressing the help files |gzip-helpfile| +Executing shell commands in a window |shell-window| +Hex editing |hex-editing| +Using <> notation in autocommands |autocmd-<>| +Highlighting matching parens |match-parens| + +============================================================================== +Editing C programs *C-editing* + +There are quite a few features in Vim to help you edit C program files. Here +is an overview with tags to jump to: + +|usr_29.txt| Moving through programs chapter in the user manual. +|usr_30.txt| Editing programs chapter in the user manual. +|C-indenting| Automatically set the indent of a line while typing + text. +|=| Re-indent a few lines. +|format-comments| Format comments. + +|:checkpath| Show all recursively included files. +|[i| Search for identifier under cursor in current and + included files. +|[_CTRL-I| Jump to match for "[i" +|[I| List all lines in current and included files where + identifier under the cursor matches. +|[d| Search for define under cursor in current and included + files. + +|CTRL-]| Jump to tag under cursor (e.g., definition of a + function). +|CTRL-T| Jump back to before a CTRL-] command. +|:tselect| Select one tag out of a list of matching tags. + +|gd| Go to Declaration of local variable under cursor. +|gD| Go to Declaration of global variable under cursor. + +|gf| Go to file name under the cursor. + +|%| Go to matching (), {}, [], /* */, #if, #else, #endif. +|[/| Go to previous start of comment. +|]/| Go to next end of comment. +|[#| Go back to unclosed #if, #ifdef, or #else. +|]#| Go forward to unclosed #else or #endif. +|[(| Go back to unclosed '(' +|])| Go forward to unclosed ')' +|[{| Go back to unclosed '{' +|]}| Go forward to unclosed '}' + +|v_ab| Select "a block" from "[(" to "])", including braces +|v_ib| Select "inner block" from "[(" to "])" +|v_aB| Select "a block" from "[{" to "]}", including brackets +|v_iB| Select "inner block" from "[{" to "]}" + +============================================================================== +Finding where identifiers are used *ident-search* + +You probably already know that |tags| can be used to jump to the place where a +function or variable is defined. But sometimes you wish you could jump to all +the places where a function or variable is being used. This is possible in +two ways: +1. Using the |:grep| command. This should work on most Unix systems, + but can be slow (it reads all files) and only searches in one directory. +2. Using ID utils. This is fast and works in multiple directories. It uses a + database to store locations. You will need some additional programs for + this to work. And you need to keep the database up to date. + +Using the GNU id-tools: + +What you need: +- The GNU id-tools installed (mkid is needed to create ID and lid is needed to + use the macros). +- An identifier database file called "ID" in the current directory. You can + create it with the shell command "mkid file1 file2 ..". + +Put this in your .vimrc: > + map _u :call ID_search()<Bar>execute "/\\<" . g:word . "\\>"<CR> + map _n :n<Bar>execute "/\\<" . g:word . "\\>"<CR> + + function! ID_search() + let g:word = expand("<cword>") + let x = system("lid --key=none ". g:word) + let x = substitute(x, "\n", " ", "g") + execute "next " . x + endfun + +To use it, place the cursor on a word, type "_u" and vim will load the file +that contains the word. Search for the next occurrence of the word in the +same file with "n". Go to the next file with "_n". + +This has been tested with id-utils-3.2 (which is the name of the id-tools +archive file on your closest gnu-ftp-mirror). + +[the idea for this comes from Andreas Kutschera] + +============================================================================== +Switching screens in an xterm *xterm-screens* *xterm-save-screen* + +(From comp.editors, by Juergen Weigert, in reply to a question) + +:> Another question is that after exiting vim, the screen is left as it +:> was, i.e. the contents of the file I was viewing (editing) was left on +:> the screen. The output from my previous like "ls" were lost, +:> ie. no longer in the scrolling buffer. I know that there is a way to +:> restore the screen after exiting vim or other vi like editors, +:> I just don't know how. Helps are appreciated. Thanks. +: +:I imagine someone else can answer this. I assume though that vim and vi do +:the same thing as each other for a given xterm setup. + +They not necessarily do the same thing, as this may be a termcap vs. +terminfo problem. You should be aware that there are two databases for +describing attributes of a particular type of terminal: termcap and +terminfo. This can cause differences when the entries differ AND when of +the programs in question one uses terminfo and the other uses termcap +(also see |+terminfo|). + +In your particular problem, you are looking for the control sequences +^[[?47h and ^[[?47l. These switch between xterms alternate and main screen +buffer. As a quick workaround a command sequence like > + echo -n "^[[?47h"; vim ... ; echo -n "^[[?47l" +may do what you want. (My notation ^[ means the ESC character, further down +you'll see that the databases use \E instead). + +On startup, vim echoes the value of the termcap variable ti (terminfo: +smcup) to the terminal. When exiting, it echoes te (terminfo: rmcup). Thus +these two variables are the correct place where the above mentioned control +sequences should go. + +Compare your xterm termcap entry (found in /etc/termcap) with your xterm +terminfo entry (retrieved with "infocmp -C xterm"). Both should contain +entries similar to: > + :te=\E[2J\E[?47l\E8:ti=\E7\E[?47h: + +PS: If you find any difference, someone (your sysadmin?) should better check + the complete termcap and terminfo database for consistency. + +NOTE 1: If you recompile Vim with FEAT_XTERM_SAVE defined in feature.h, the +builtin xterm will include the mentioned "te" and "ti" entries. + +NOTE 2: If you want to disable the screen switching, and you don't want to +change your termcap, you can add these lines to your .vimrc: > + :set t_ti= t_te= + +============================================================================== +Scrolling in Insert mode *scroll-insert* + +If you are in insert mode and you want to see something that is just off the +screen, you can use CTRL-X CTRL-E and CTRL-X CTRL-Y to scroll the screen. + |i_CTRL-X_CTRL-E| + +To make this easier, you could use these mappings: > + :inoremap <C-E> <C-X><C-E> + :inoremap <C-Y> <C-X><C-Y> +(Type this literally, make sure the '<' flag is not in 'cpoptions'). +You then lose the ability to copy text from the line above/below the cursor +|i_CTRL-E|. + +Also consider setting 'scrolloff' to a larger value, so that you can always see +some context around the cursor. If 'scrolloff' is bigger than half the window +height, the cursor will always be in the middle and the text is scrolled when +the cursor is moved up/down. + +============================================================================== +Smooth scrolling *scroll-smooth* + +If you like the scrolling to go a bit smoother, you can use these mappings: > + :map <C-U> <C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y> + :map <C-D> <C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E> + +(Type this literally, make sure the '<' flag is not in 'cpoptions'). + +============================================================================== +Correcting common typing mistakes *type-mistakes* + +When there are a few words that you keep on typing in the wrong way, make +abbreviations that correct them. For example: > + :ab teh the + :ab fro for + +============================================================================== +Counting words, lines, etc. *count-items* + +To count how often any pattern occurs in the current buffer use the substitute +command and add the 'n' flag to avoid the substitution. The reported number +of substitutions is the number of items. Examples: > + + :%s/./&/gn characters + :%s/\i\+/&/gn words + :%s/^//n lines + :%s/the/&/gn "the" anywhere + :%s/\<the\>/&/gn "the" as a word + +You might want to reset 'hlsearch' or do ":nohlsearch". +Add the 'e' flag if you don't want an error when there are no matches. + +An alternative is using |v_g_CTRL-G| in Visual mode. + +If you want to find matches in multiple files use |:vimgrep|. + + *count-bytes* +If you want to count bytes, you can use this: + + Visually select the characters (block is also possible) + Use "y" to yank the characters + Use the strlen() function: > + :echo strlen(@") +A line break is counted for one byte. + +============================================================================== +Restoring the cursor position *restore-position* + +Sometimes you want to write a mapping that makes a change somewhere in the +file and restores the cursor position, without scrolling the text. For +example, to change the date mark in a file: > + :map <F2> msHmtgg/Last [cC]hange:\s*/e+1<CR>"_D"=strftime("%Y %b %d")<CR>p'tzt`s + +Breaking up saving the position: + ms store cursor position in the 's' mark + H go to the first line in the window + mt store this position in the 't' mark + +Breaking up restoring the position: + 't go to the line previously at the top of the window + zt scroll to move this line to the top of the window + `s jump to the original position of the cursor + +For something more advanced see |winsaveview()| and |winrestview()|. + +============================================================================== +Renaming files *rename-files* + +Say I have a directory with the following files in them (directory picked at +random :-): + +buffer.c +charset.c +digraph.c +... + +and I want to rename *.c *.bla. I'd do it like this: > + + $ vim + :r !ls *.c + :%s/\(.*\).c/mv & \1.bla + :w !sh + :q! + +============================================================================== +Change a name in multiple files *change-name* + +Example for using a script file to change a name in several files: + + Create a file "subs.vim" containing substitute commands and a :update + command: > + :%s/Jones/Smith/g + :%s/Allen/Peter/g + :update +< + Execute Vim on all files you want to change, and source the script for + each argument: > + + vim *.let + argdo source subs.vim + +See |:argdo|. + +============================================================================== +Speeding up external commands *speed-up* + +In some situations, execution of an external command can be very slow. This +can also slow down wildcard expansion on Unix. Here are a few suggestions to +increase the speed. + +If your .cshrc (or other file, depending on the shell used) is very long, you +should separate it into a section for interactive use and a section for +non-interactive use (often called secondary shells). When you execute a +command from Vim like ":!ls", you do not need the interactive things (for +example, setting the prompt). Put the stuff that is not needed after these +lines: > + + if ($?prompt == 0) then + exit 0 + endif + +Another way is to include the "-f" flag in the 'shell' option, e.g.: > + + :set shell=csh\ -f + +(the backslash is needed to include the space in the option). +This will make csh completely skip the use of the .cshrc file. This may cause +some things to stop working though. + +============================================================================== +Useful mappings *useful-mappings* + +Here are a few mappings that some people like to use. + + *map-backtick* > + :map ' ` +Make the single quote work like a backtick. Puts the cursor on the column of +a mark, instead of going to the first non-blank character in the line. + + *emacs-keys* +For Emacs-style editing on the command-line: > + " start of line + :cnoremap <C-A> <Home> + " back one character + :cnoremap <C-B> <Left> + " delete character under cursor + :cnoremap <C-D> <Del> + " end of line + :cnoremap <C-E> <End> + " forward one character + :cnoremap <C-F> <Right> + " recall newer command-line + :cnoremap <C-N> <Down> + " recall previous (older) command-line + :cnoremap <C-P> <Up> + " back one word + :cnoremap <Esc><C-B> <S-Left> + " forward one word + :cnoremap <Esc><C-F> <S-Right> + +NOTE: This requires that the '<' flag is excluded from 'cpoptions'. |<>| + + *format-bullet-list* +This mapping will format any bullet list. It requires that there is an empty +line above and below each list entry. The expression commands are used to +be able to give comments to the parts of the mapping. > + + :let m = ":map _f :set ai<CR>" " need 'autoindent' set + :let m = m . "{O<Esc>" " add empty line above item + :let m = m . "}{)^W" " move to text after bullet + :let m = m . "i <CR> <Esc>" " add space for indent + :let m = m . "gq}" " format text after the bullet + :let m = m . "{dd" " remove the empty line + :let m = m . "5lDJ" " put text after bullet + :execute m |" define the mapping + +(<> notation |<>|. Note that this is all typed literally. ^W is "^" "W", not +CTRL-W. You can copy/paste this into Vim if '<' is not included in +'cpoptions'.) + +Note that the last comment starts with |", because the ":execute" command +doesn't accept a comment directly. + +You also need to set 'textwidth' to a non-zero value, e.g., > + :set tw=70 + +A mapping that does about the same, but takes the indent for the list from the +first line (Note: this mapping is a single long line with a lot of spaces): > + :map _f :set ai<CR>}{a <Esc>WWmmkD`mi<CR><Esc>kkddpJgq}'mJO<Esc>j +< + *collapse* +These two mappings reduce a sequence of empty (;b) or blank (;n) lines into a +single line > + :map ;b GoZ<Esc>:g/^$/.,/./-j<CR>Gdd + :map ;n GoZ<Esc>:g/^[ <Tab>]*$/.,/[^ <Tab>]/-j<CR>Gdd + +============================================================================== +Compressing the help files *gzip-helpfile* + +For those of you who are really short on disk space, you can compress the help +files and still be able to view them with Vim. This makes accessing the help +files a bit slower and requires the "gzip" program. + +(1) Compress all the help files: "gzip doc/*.txt". + +(2) Edit "doc/tags" and change the ".txt" to ".txt.gz": > + :%s=\(\t.*\.txt\)\t=\1.gz\t= + +(3) Add this line to your vimrc: > + set helpfile={dirname}/help.txt.gz + +Where {dirname} is the directory where the help files are. The |gzip| plugin +will take care of decompressing the files. +You must make sure that $VIMRUNTIME is set to where the other Vim files are, +when they are not in the same location as the compressed "doc" directory. See +|$VIMRUNTIME|. + +============================================================================== +Executing shell commands in a window *shell-window* + +There have been questions for the possibility to execute a shell in a window +inside Vim. The answer: you can't! Including this would add a lot of code to +Vim, which is a good reason not to do this. After all, Vim is an editor, it +is not supposed to do non-editing tasks. However, to get something like this, +you might try splitting your terminal screen or display window with the +"splitvt" program. You can probably find it on some ftp server. The person +that knows more about this is Sam Lantinga <slouken@cs.ucdavis.edu>. +An alternative is the "window" command, found on BSD Unix systems, which +supports multiple overlapped windows. Or the "screen" program, found at +www.uni-erlangen.de, which supports a stack of windows. + +============================================================================== +Hex editing *hex-editing* *using-xxd* + +See section |23.4| of the user manual. + +If one has a particular extension that one uses for binary files (such as exe, +bin, etc), you may find it helpful to automate the process with the following +bit of autocmds for your <.vimrc>. Change that "*.bin" to whatever +comma-separated list of extension(s) you find yourself wanting to edit: > + + " vim -b : edit binary using xxd-format! + augroup Binary + au! + au BufReadPre *.bin let &bin=1 + au BufReadPost *.bin if &bin | %!xxd + au BufReadPost *.bin set ft=xxd | endif + au BufWritePre *.bin if &bin | %!xxd -r + au BufWritePre *.bin endif + au BufWritePost *.bin if &bin | %!xxd + au BufWritePost *.bin set nomod | endif + augroup END + +============================================================================== +Using <> notation in autocommands *autocmd-<>* + +The <> notation is not recognized in the argument of an :autocmd. To avoid +having to use special characters, you could use a self-destroying mapping to +get the <> notation and then call the mapping from the autocmd. Example: + + *map-self-destroy* > + " This is for automatically adding the name of the file to the menu list. + " It uses a self-destroying mapping! + " 1. use a line in the buffer to convert the 'dots' in the file name to \. + " 2. store that in register '"' + " 3. add that name to the Buffers menu list + " WARNING: this does have some side effects, like overwriting the + " current register contents and removing any mapping for the "i" command. + " + autocmd BufNewFile,BufReadPre * nmap i :nunmap i<CR>O<C-R>%<Esc>:.g/\./s/\./\\./g<CR>0"9y$u:menu Buffers.<C-R>9 :buffer <C-R>%<C-V><CR><CR> + autocmd BufNewFile,BufReadPre * normal i + +Another method, perhaps better, is to use the ":execute" command. In the +string you can use the <> notation by preceding it with a backslash. Don't +forget to double the number of existing backslashes and put a backslash before +'"'. +> + autocmd BufNewFile,BufReadPre * exe "normal O\<C-R>%\<Esc>:.g/\\./s/\\./\\\\./g\<CR>0\"9y$u:menu Buffers.\<C-R>9 :buffer \<C-R>%\<C-V>\<CR>\<CR>" + +For a real buffer menu, user functions should be used (see |:function|), but +then the <> notation isn't used, which defeats using it as an example here. + +============================================================================== +Highlighting matching parens *match-parens* + +This example shows the use of a few advanced tricks: +- using the |CursorMoved| autocommand event +- using |searchpairpos()| to find a matching paren +- using |synID()| to detect whether the cursor is in a string or comment +- using |:match| to highlight something +- using a |pattern| to match a specific position in the file. + +This should be put in a Vim script file, since it uses script-local variables. +It skips matches in strings or comments, unless the cursor started in string +or comment. This requires syntax highlighting. + +A slightly more advanced version is used in the |matchparen| plugin. +> + let s:paren_hl_on = 0 + function s:Highlight_Matching_Paren() + if s:paren_hl_on + match none + let s:paren_hl_on = 0 + endif + + let c_lnum = line('.') + let c_col = col('.') + + let c = getline(c_lnum)[c_col - 1] + let plist = split(&matchpairs, ':\|,') + let i = index(plist, c) + if i < 0 + return + endif + if i % 2 == 0 + let s_flags = 'nW' + let c2 = plist[i + 1] + else + let s_flags = 'nbW' + let c2 = c + let c = plist[i - 1] + endif + if c == '[' + let c = '\[' + let c2 = '\]' + endif + let s_skip ='synIDattr(synID(line("."), col("."), 0), "name") ' . + \ '=~? "string\\|comment"' + execute 'if' s_skip '| let s_skip = 0 | endif' + + let [m_lnum, m_col] = searchpairpos(c, '', c2, s_flags, s_skip) + + if m_lnum > 0 && m_lnum >= line('w0') && m_lnum <= line('w$') + exe 'match Search /\(\%' . c_lnum . 'l\%' . c_col . + \ 'c\)\|\(\%' . m_lnum . 'l\%' . m_col . 'c\)/' + let s:paren_hl_on = 1 + endif + endfunction + + autocmd CursorMoved,CursorMovedI * call s:Highlight_Matching_Paren() + autocmd InsertEnter * match none +< + + vim:tw=78:ts=8:ft=help:norl: diff --git a/en/uganda.txt b/en/uganda.txt new file mode 100644 index 000000000..167f1baed --- /dev/null +++ b/en/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 <Bram@vim.org>. If this + changes it will be announced in appropriate places (most likely + vim.sf.net, www.vim.org and/or comp.editors). When it is completely + impossible to contact the maintainer, the obligation to send him + your changes ceases. Once the maintainer has confirmed that he has + received your changes they will not have to be sent again. + b) If you have received a modified Vim that was distributed as + mentioned under a) you are allowed to further distribute it + unmodified, as mentioned at I). If you make additional changes the + text under a) applies to those changes. + c) Provide all the changes, including source code, with every copy of + the modified Vim you distribute. This may be done in the form of a + context diff. You can choose what license to use for new code you + add. The changes and their license must not restrict others from + making their own changes to the official version of Vim. + d) When you have a modified Vim which includes changes as mentioned + under c), you can distribute it without the source code for the + changes if the following three conditions are met: + - The license that applies to the changes permits you to distribute + the changes to the Vim maintainer without fee or restriction, and + permits the Vim maintainer to include the changes in the official + version of Vim without fee or restriction. + - You keep the changes for at least three years after last + distributing the corresponding modified Vim. When the maintainer + or someone who you distributed the modified Vim to asks you (in + any way) for the changes within this period, you must make them + available to him. + - You clearly describe in the distribution how to contact you. This + contact information must remain valid for at least three years + after last distributing the corresponding modified Vim, or as long + as possible. + e) When the GNU General Public License (GPL) applies to the changes, + you can distribute the modified Vim under the GNU GPL version 2 or + any later version. + 3) A message must be added, at least in the output of the ":version" + command and in the intro screen, such that the user of the modified Vim + is able to see that it was modified. When distributing as mentioned + under 2)e) adding the message is only required for as far as this does + not conflict with the license used for the changes. + 4) The contact information as required under 2)a) and 2)d) must not be + removed or changed, except that the person himself can make + corrections. + +III) If you distribute a modified version of Vim, you are encouraged to use + the Vim license for your changes and make them available to the + maintainer, including the source code. The preferred way to do this is + by e-mail or by uploading the files to a server and e-mailing the URL. + If the number of changes is small (e.g., a modified Makefile) e-mailing a + context diff will do. The e-mail address to be used is + <maintainer@vim.org> + +IV) It is not allowed to remove this license from the distribution of the Vim + sources, parts of it or from a modified version. You may use this + license for previous Vim releases instead of the license that they came + with, at your option. + +=== end of license === + +Note: + +- If you are happy with Vim, please express that by reading the rest of this + file and consider helping needy children in Uganda. + +- If you want to support further Vim development consider becoming a + |sponsor|. 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. Furthermore, 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: <Bram@vim.org>. + +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/en/undo.txt b/en/undo.txt new file mode 100644 index 000000000..46469b353 --- /dev/null +++ b/en/undo.txt @@ -0,0 +1,406 @@ +*undo.txt* For Vim version 7.4. Last change: 2014 May 24 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Undo and redo *undo-redo* + +The basics are explained in section |02.5| of the user manual. + +1. Undo and redo commands |undo-commands| +2. Two ways of undo |undo-two-ways| +3. Undo blocks |undo-blocks| +4. Undo branches |undo-branches| +5. Undo persistence |undo-persistence| +6. Remarks about undo |undo-remarks| + +============================================================================== +1. Undo and redo commands *undo-commands* + +<Undo> or *undo* *<Undo>* *u* +u Undo [count] changes. {Vi: only one level} + + *:u* *:un* *:undo* +:u[ndo] Undo one change. {Vi: only one level} + *E830* +:u[ndo] {N} Jump to after change number {N}. See |undo-branches| + for the meaning of {N}. {not in Vi} + + *CTRL-R* +CTRL-R Redo [count] changes which were undone. {Vi: redraw + screen} + + *:red* *:redo* *redo* +:red[o] Redo one change which was undone. {Vi: no redo} + + *U* +U Undo all latest changes on one line, the line where + the latest change was made. |U| itself also counts as + a change, and thus |U| undoes a previous |U|. + {Vi: while not moved off of the last modified line} + +The last changes are remembered. You can use the undo and redo commands above +to revert the text to how it was before each change. You can also apply the +changes again, getting back the text before the undo. + +The "U" command is treated by undo/redo just like any other command. Thus a +"u" command undoes a "U" command and a 'CTRL-R' command redoes it again. When +mixing "U", "u" and 'CTRL-R' you will notice that the "U" command will +restore the situation of a line to before the previous "U" command. This may +be confusing. Try it out to get used to it. +The "U" command will always mark the buffer as changed. When "U" changes the +buffer back to how it was without changes, it is still considered changed. +Use "u" to undo changes until the buffer becomes unchanged. + +============================================================================== +2. Two ways of undo *undo-two-ways* + +How undo and redo commands work depends on the 'u' flag in 'cpoptions'. +There is the Vim way ('u' excluded) and the Vi-compatible way ('u' included). +In the Vim way, "uu" undoes two changes. In the Vi-compatible way, "uu" does +nothing (undoes an undo). + +'u' excluded, the Vim way: +You can go back in time with the undo command. You can then go forward again +with the redo command. If you make a new change after the undo command, +the redo will not be possible anymore. + +'u' included, the Vi-compatible way: +The undo command undoes the previous change, and also the previous undo command. +The redo command repeats the previous undo command. It does NOT repeat a +change command, use "." for that. + +Examples Vim way Vi-compatible way ~ +"uu" two times undo no-op +"u CTRL-R" no-op two times undo + +Rationale: Nvi uses the "." command instead of CTRL-R. Unfortunately, this + is not Vi compatible. For example "dwdwu." in Vi deletes two + words, in Nvi it does nothing. + +============================================================================== +3. Undo blocks *undo-blocks* + +One undo command normally undoes a typed command, no matter how many changes +that command makes. This sequence of undo-able changes forms an undo block. +Thus if the typed key(s) call a function, all the commands in the function are +undone together. + +If you want to write a function or script that doesn't create a new undoable +change but joins in with the previous change use this command: + + *:undoj* *:undojoin* *E790* +:undoj[oin] Join further changes with the previous undo block. + Warning: Use with care, it may prevent the user from + properly undoing changes. Don't use this after undo + or redo. + {not in Vi} + +This is most useful when you need to prompt the user halfway through a change. +For example in a function that calls |getchar()|. Do make sure that there was +a related change before this that you must join with. + +This doesn't work by itself, because the next key press will start a new +change again. But you can do something like this: > + + :undojoin | delete + +After this an "u" command will undo the delete command and the previous +change. + +To do the opposite, break a change into two undo blocks, in Insert mode use +CTRL-G u. This is useful if you want an insert command to be undoable in +parts. E.g., for each sentence. |i_CTRL-G_u| +Setting the value of 'undolevels' also breaks undo. Even when the new value +is equal to the old value. + +============================================================================== +4. Undo branches *undo-branches* *undo-tree* + +Above 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 undone changes become a branch. You can go to that branch with +the following commands. + +This is explained in the user manual: |usr_32.txt|. + + *:undol* *:undolist* +:undol[ist] List the leafs in the tree of changes. Example: + number changes when saved ~ + 88 88 2010/01/04 14:25:53 + 108 107 08/07 12:47:51 + 136 46 13:33:01 7 + 166 164 3 seconds ago + + The "number" column is the change number. This number + continuously increases and can be used to identify a + specific undo-able change, see |:undo|. + The "changes" column is the number of changes to this + leaf from the root of the tree. + The "when" column is the date and time when this + change was made. The four possible formats are: + N seconds ago + HH:MM:SS hour, minute, seconds + MM/DD HH:MM:SS idem, with month and day + YYYY/MM/DD HH:MM:SS idem, with year + The "saved" column specifies, if this change was + written to disk and which file write it was. This can + be used with the |:later| and |:earlier| commands. + For more details use the |undotree()| function. + + *g-* +g- Go to older text state. With a count repeat that many + times. {not in Vi} + *:ea* *:earlier* +:earlier {count} Go to older text state {count} times. +:earlier {N}s Go to older text state about {N} seconds before. +:earlier {N}m Go to older text state about {N} minutes before. +:earlier {N}h Go to older text state about {N} hours before. +:earlier {N}d Go to older text state about {N} days before. + +:earlier {N}f Go to older text state {N} file writes before. + When changes were made since the last write + ":earlier 1f" will revert the text to the state when + it was written. Otherwise it will go to the write + before that. + When at the state of the first file write, or when + the file was not written, ":earlier 1f" will go to + before the first change. + + *g+* +g+ Go to newer text state. With a count repeat that many + times. {not in Vi} + *:lat* *:later* +:later {count} Go to newer text state {count} times. +:later {N}s Go to newer text state about {N} seconds later. +:later {N}m Go to newer text state about {N} minutes later. +:later {N}h Go to newer text state about {N} hours later. +:later {N}d Go to newer text state about {N} days later. + +:later {N}f Go to newer text state {N} file writes later. + When at the state of the last file write, ":later 1f" + will go to the newest text state. + + +Note that text states will become unreachable when undo information is cleared +for 'undolevels'. + +Don't be surprised when moving through time shows multiple changes to take +place at a time. This happens when moving through the undo tree and then +making a new change. + +EXAMPLE + +Start with this text: + one two three ~ + +Delete the first word by pressing "x" three times: + ne two three ~ + e two three ~ + two three ~ + +Now undo that by pressing "u" three times: + e two three ~ + ne two three ~ + one two three ~ + +Delete the second word by pressing "x" three times: + one wo three ~ + one o three ~ + one three ~ + +Now undo that by using "g-" three times: + one o three ~ + one wo three ~ + two three ~ + +You are now back in the first undo branch, after deleting "one". Repeating +"g-" will now bring you back to the original text: + e two three ~ + ne two three ~ + one two three ~ + +Jump to the last change with ":later 1h": + one three ~ + +And back to the start again with ":earlier 1h": + one two three ~ + + +Note that using "u" and CTRL-R will not get you to all possible text states +while repeating "g-" and "g+" does. + +============================================================================== +5. Undo persistence *undo-persistence* *persistent-undo* + +When unloading a buffer Vim normally destroys the tree of undos created for +that buffer. By setting the 'undofile' option, Vim will automatically save +your undo history when you write a file and restore undo history when you edit +the file again. + +The 'undofile' option is checked after writing a file, before the BufWritePost +autocommands. If you want to control what files to write undo information +for, you can use a BufWritePre autocommand: > + au BufWritePre /tmp/* setlocal noundofile + +Vim saves undo trees in a separate undo file, one for each edited file, using +a simple scheme that maps filesystem paths directly to undo files. Vim will +detect if an undo file is no longer synchronized with the file it was written +for (with a hash of the file contents) and ignore it when the file was changed +after the undo file was written, to prevent corruption. An undo file is also +ignored if its owner differs from the owner of the edited file, except when +the owner of the undo file is the current user. Set 'verbose' to get a +message about that when opening a file. + +Undo files are normally saved in the same directory as the file. This can be +changed with the 'undodir' option. + +When the file is encrypted, the text in the undo file is also crypted. The +same key and method is used. |encryption| + +You can also save and restore undo histories by using ":wundo" and ":rundo" +respectively: + *:wundo* *:rundo* +:wundo[!] {file} + Write undo history to {file}. + When {file} exists and it does not look like an undo file + (the magic number at the start of the file is wrong), then + this fails, unless the ! was added. + If it exists and does look like an undo file it is + overwritten. If there is no undo-history, nothing will be + written. + Implementation detail: Overwriting happens by first deleting + the existing file and then creating a new file with the same + name. So it is not possible to overwrite an existing undofile + in a write-protected directory. + {not in Vi} + +:rundo {file} Read undo history from {file}. + {not in Vi} + +You can use these in autocommands to explicitly specify the name of the +history file. E.g.: > + + au BufReadPost * call ReadUndo() + au BufWritePost * call WriteUndo() + func ReadUndo() + if filereadable(expand('%:h'). '/UNDO/' . expand('%:t')) + rundo %:h/UNDO/%:t + endif + endfunc + func WriteUndo() + let dirname = expand('%:h') . '/UNDO' + if !isdirectory(dirname) + call mkdir(dirname) + endif + wundo %:h/UNDO/%:t + endfunc + +You should keep 'undofile' off, otherwise you end up with two undo files for +every write. + +You can use the |undofile()| function to find out the file name that Vim would +use. + +Note that while reading/writing files and 'undofile' is set most errors will +be silent, unless 'verbose' is set. With :wundo and :rundo you will get more +error messages, e.g., when the file cannot be read or written. + +NOTE: undo files are never deleted by Vim. You need to delete them yourself. + +Reading an existing undo file may fail for several reasons: +*E822* It cannot be opened, because the file permissions don't allow it. +*E823* The magic number at the start of the file doesn't match. This usually + means it is not an undo file. +*E824* The version number of the undo file indicates that it's written by a + newer version of Vim. You need that newer version to open it. Don't + write the buffer if you want to keep the undo info in the file. +"File contents changed, cannot use undo info" + The file text differs from when the undo file was written. This means + the undo file cannot be used, it would corrupt the text. This also + happens when 'encoding' differs from when the undo file was written. +*E825* The undo file does not contain valid contents and cannot be used. +*E826* The undo file is encrypted but decryption failed. +*E827* The undo file is encrypted but this version of Vim does not support + encryption. Open the file with another Vim. +*E832* The undo file is encrypted but 'key' is not set, the text file is not + encrypted. This would happen if the text file was written by Vim + encrypted at first, and later overwritten by not encrypted text. + You probably want to delete this undo file. +"Not reading undo file, owner differs" + The undo file is owned by someone else than the owner of the text + file. For safety the undo file is not used. + +Writing an undo file may fail for these reasons: +*E828* The file to be written cannot be created. Perhaps you do not have + write permissions in the directory. +"Cannot write undo file in any directory in 'undodir'" + None of the directories in 'undodir' can be used. +"Will not overwrite with undo file, cannot read" + A file exists with the name of the undo file to be written, but it + cannot be read. You may want to delete this file or rename it. +"Will not overwrite, this is not an undo file" + A file exists with the name of the undo file to be written, but it + does not start with the right magic number. You may want to delete + this file or rename it. +"Skipping undo file write, nothing to undo" + There is no undo information to be written, nothing has been changed + or 'undolevels' is negative. +*E829* An error occurred while writing the undo file. You may want to try + again. + +============================================================================== +6. Remarks about undo *undo-remarks* + +The number of changes that are remembered is set with the 'undolevels' option. +If it is zero, the Vi-compatible way is always used. If it is negative no +undo is possible. Use this if you are running out of memory. + + *clear-undo* +When you set 'undolevels' to -1 the undo information is not immediately +cleared, this happens at the next change. To force clearing the undo +information you can use these commands: > + :let old_undolevels = &undolevels + :set undolevels=-1 + :exe "normal a \<BS>\<Esc>" + :let &undolevels = old_undolevels + :unlet old_undolevels + +Marks for the buffer ('a to 'z) are also saved and restored, together with the +text. {Vi does this a little bit different} + +When all changes have been undone, the buffer is not considered to be changed. +It is then possible to exit Vim with ":q" instead of ":q!" {not in Vi}. Note +that this is relative to the last write of the file. Typing "u" after ":w" +actually changes the buffer, compared to what was written, so the buffer is +considered changed then. + +When manual |folding| is being used, the folds are not saved and restored. +Only changes completely within a fold will keep the fold as it was, because +the first and last line of the fold don't change. + +The numbered registers can also be used for undoing deletes. Each time you +delete text, it is put into register "1. The contents of register "1 are +shifted to "2, etc. The contents of register "9 are lost. You can now get +back the most recent deleted text with the put command: '"1P'. (also, if the +deleted text was the result of the last delete or copy operation, 'P' or 'p' +also works as this puts the contents of the unnamed register). You can get +back the text of three deletes ago with '"3P'. + + *redo-register* +If you want to get back more than one part of deleted text, you can use a +special feature of the repeat command ".". It will increase the number of the +register used. So if you first do ""1P", the following "." will result in a +'"2P'. Repeating this will result in all numbered registers being inserted. + +Example: If you deleted text with 'dd....' it can be restored with + '"1P....'. + +If you don't know in which register the deleted text is, you can use the +:display command. An alternative is to try the first register with '"1P', and +if it is not what you want do 'u.'. This will remove the contents of the +first put, and repeat the put command for the second register. Repeat the +'u.' until you got what you want. + + vim:tw=78:ts=8:ft=help:norl: diff --git a/en/usr_01.txt b/en/usr_01.txt new file mode 100644 index 000000000..11fa2173d --- /dev/null +++ b/en/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/en/usr_02.txt b/en/usr_02.txt new file mode 100644 index 000000000..a3e9bf3c8 --- /dev/null +++ b/en/usr_02.txt @@ -0,0 +1,701 @@ +*usr_02.txt* For Vim version 7.4. Last change: 2016 Jan 16 + + VIM USER MANUAL - by Bram Moolenaar + + The first steps in Vim + + +This chapter provides just enough information to edit a file with Vim. Not +well or fast, but you can edit. Take some time to practice with these +commands, they form the base for what follows. + +|02.1| Running Vim for the First Time +|02.2| Inserting text +|02.3| Moving around +|02.4| Deleting characters +|02.5| Undo and Redo +|02.6| Other editing commands +|02.7| Getting out +|02.8| Finding help + + Next chapter: |usr_03.txt| Moving around + Previous chapter: |usr_01.txt| About the manuals +Table of contents: |usr_toc.txt| + +============================================================================== +*02.1* Running Vim for the First Time + +To start Vim, enter this command: > + + gvim file.txt + +In UNIX you can type this at any command prompt. If you are running Microsoft +Windows, open an MS-DOS prompt window and enter the command. + In either case, Vim starts editing a file called file.txt. Because this +is a new file, you get a blank window. This is what your screen will look +like: + + +---------------------------------------+ + |# | + |~ | + |~ | + |~ | + |~ | + |"file.txt" [New file] | + +---------------------------------------+ + ('#" is the cursor position.) + +The tilde (~) lines indicate lines not in the file. In other words, when Vim +runs out of file to display, it displays tilde lines. At the bottom of the +screen, a message line indicates the file is named file.txt and shows that you +are creating a new file. The message information is temporary and other +information overwrites it. + + +THE VIM COMMAND + +The gvim command causes the editor to create a new window for editing. If you +use this command: > + + vim file.txt + +the editing occurs inside your command window. In other words, if you are +running inside an xterm, the editor uses your xterm window. If you are using +an MS-DOS command prompt window under Microsoft Windows, the editing occurs +inside this window. The text in the window will look the same for both +versions, but with gvim you have extra features, like a menu bar. More about +that later. + +============================================================================== +*02.2* Inserting text + +The Vim editor is a modal editor. That means that the editor behaves +differently, depending on which mode you are in. The two basic modes are +called Normal mode and Insert mode. In Normal mode the characters you type +are commands. In Insert mode the characters are inserted as text. + Since you have just started Vim it will be in Normal mode. To start Insert +mode you type the "i" command (i for Insert). Then you can enter +the text. It will be inserted into the file. Do not worry if you make +mistakes; you can correct them later. To enter the following programmer's +limerick, this is what you type: > + + iA very intelligent turtle + Found programming UNIX a hurdle + +After typing "turtle" you press the <Enter> key to start a new line. Finally +you press the <Esc> key to stop Insert mode and go back to Normal mode. You +now have two lines of text in your Vim window: + + +---------------------------------------+ + |A very intelligent turtle | + |Found programming UNIX a hurdle | + |~ | + |~ | + | | + +---------------------------------------+ + + +WHAT IS THE MODE? + +To be able to see what mode you are in, type this command: > + + :set showmode + +You will notice that when typing the colon Vim moves the cursor to the last +line of the window. That's where you type colon commands (commands that start +with a colon). Finish this command by pressing the <Enter> key (all commands +that start with a colon are finished this way). + Now, if you type the "i" command Vim will display --INSERT-- at the bottom +of the window. This indicates you are in Insert mode. + + +---------------------------------------+ + |A very intelligent turtle | + |Found programming UNIX a hurdle | + |~ | + |~ | + |-- INSERT -- | + +---------------------------------------+ + +If you press <Esc> to go back to Normal mode the last line will be made blank. + + +GETTING OUT OF TROUBLE + +One of the problems for Vim novices is mode confusion, which is caused by +forgetting which mode you are in or by accidentally typing a command that +switches modes. To get back to Normal mode, no matter what mode you are in, +press the <Esc> key. Sometimes you have to press it twice. If Vim beeps back +at you, you already are in Normal mode. + +============================================================================== +*02.3* Moving around + +After you return to Normal mode, you can move around by using these keys: + + h left *hjkl* + j down + k up + l right + +At first, it may appear that these commands were chosen at random. After all, +who ever heard of using l for right? But actually, there is a very good +reason for these choices: Moving the cursor is the most common thing you do in +an editor, and these keys are on the home row of your right hand. In other +words, these commands are placed where you can type them the fastest +(especially when you type with ten fingers). + + Note: + You can also move the cursor by using the arrow keys. If you do, + however, you greatly slow down your editing because to press the arrow + keys, you must move your hand from the text keys to the arrow keys. + Considering that you might be doing it hundreds of times an hour, this + can take a significant amount of time. + Also, there are keyboards which do not have arrow keys, or which + locate them in unusual places; therefore, knowing the use of the hjkl + keys helps in those situations. + +One way to remember these commands is that h is on the left, l is on the +right and j points down. In a picture: > + + k + h l + j + +The best way to learn these commands is by using them. Use the "i" command to +insert some more lines of text. Then use the hjkl keys to move around and +insert a word somewhere. Don't forget to press <Esc> to go back to Normal +mode. The |vimtutor| is also a nice way to learn by doing. + +For Japanese users, Hiroshi Iwatani suggested using this: + + Komsomolsk + ^ + | + Huan Ho <--- ---> Los Angeles + (Yellow river) | + v + Java (the island, not the programming language) + +============================================================================== +*02.4* Deleting characters + +To delete a character, move the cursor over it and type "x". (This is a +throwback to the old days of the typewriter, when you deleted things by typing +xxxx over them.) Move the cursor to the beginning of the first line, for +example, and type xxxxxxx (seven x's) to delete "A very ". The result should +look like this: + + +---------------------------------------+ + |intelligent turtle | + |Found programming UNIX a hurdle | + |~ | + |~ | + | | + +---------------------------------------+ + +Now you can insert new text, for example by typing: > + + iA young <Esc> + +This begins an insert (the i), inserts the words "A young", and then exits +insert mode (the final <Esc>). The result: + + +---------------------------------------+ + |A young intelligent turtle | + |Found programming UNIX a hurdle | + |~ | + |~ | + | | + +---------------------------------------+ + + +DELETING A LINE + +To delete a whole line use the "dd" command. The following line will +then move up to fill the gap: + + +---------------------------------------+ + |Found programming UNIX a hurdle | + |~ | + |~ | + |~ | + | | + +---------------------------------------+ + + +DELETING A LINE BREAK + +In Vim you can join two lines together, which means that the line break +between them is deleted. The "J" command does this. + Take these two lines: + + A young intelligent ~ + turtle ~ + +Move the cursor to the first line and press "J": + + A young intelligent turtle ~ + +============================================================================== +*02.5* Undo and Redo + +Suppose you delete too much. Well, you can type it in again, but an easier +way exists. The "u" command undoes the last edit. Take a look at this in +action: After using "dd" to delete the first line, "u" brings it back. + Another one: Move the cursor to the A in the first line: + + A young intelligent turtle ~ + +Now type xxxxxxx to delete "A young". The result is as follows: + + intelligent turtle ~ + +Type "u" to undo the last delete. That delete removed the g, so the undo +restores the character. + + g intelligent turtle ~ + +The next u command restores the next-to-last character deleted: + + ng intelligent turtle ~ + +The next u command gives you the u, and so on: + + ung intelligent turtle ~ + oung intelligent turtle ~ + young intelligent turtle ~ + young intelligent turtle ~ + A young intelligent turtle ~ + + Note: + If you type "u" twice, and the result is that you get the same text + back, you have Vim configured to work Vi compatible. Look here to fix + this: |not-compatible|. + This text assumes you work "The Vim Way". You might prefer to use + the good old Vi way, but you will have to watch out for small + differences in the text then. + + +REDO + +If you undo too many times, you can press CTRL-R (redo) to reverse the +preceding command. In other words, it undoes the undo. To see this in +action, press CTRL-R twice. The character A and the space after it disappear: + + young intelligent turtle ~ + +There's a special version of the undo command, the "U" (undo line) command. +The undo line command undoes all the changes made on the last line that was +edited. Typing this command twice cancels the preceding "U". + + A very intelligent turtle ~ + xxxx Delete very + + A intelligent turtle ~ + xxxxxx Delete turtle + + A intelligent ~ + Restore line with "U" + A very intelligent turtle ~ + Undo "U" with "u" + A intelligent ~ + +The "U" command is a change by itself, which the "u" command undoes and CTRL-R +redoes. This might be a bit confusing. Don't worry, with "u" and CTRL-R you +can go to any of the situations you had. 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!!!<Esc> + +to append three exclamation points after the e in turtle: + + and that's not saying much for the turtle!!! ~ + + +OPENING UP A NEW LINE + +The "o" command creates a new, empty line below the cursor and puts Vim in +Insert mode. Then you can type the text for the new line. + Suppose the cursor is somewhere in the first of these two lines: + + A very intelligent turtle ~ + Found programming UNIX a hurdle ~ + +If you now use the "o" command and type new text: > + + oThat liked using Vim<Esc> + +The result is: + + A very intelligent turtle ~ + That liked using Vim ~ + Found programming UNIX a hurdle ~ + +The "O" command (uppercase) opens a line above the cursor. + + +USING A COUNT + +Suppose you want to move up nine lines. You can type "kkkkkkkkk" or you can +enter the command "9k". In fact, you can precede many commands with a number. +Earlier in this chapter, for instance, you added three exclamation points to +the end of a line by typing "a!!!<Esc>". Another way to do this is to use the +command "3a!<Esc>". The count of 3 tells the command that follows to triple +its effect. Similarly, to delete three characters, use the command "3x". The +count always comes before the command it applies to. + +============================================================================== +*02.7* Getting out + +To exit, use the "ZZ" command. This command writes the file and exits. + + Note: + Unlike many other editors, Vim does not automatically make a backup + file. If you type "ZZ", your changes are committed and there's no + turning back. You can configure the Vim editor to produce backup + files, see |07.4|. + + +DISCARDING CHANGES + +Sometimes you will make a sequence of changes and suddenly realize you were +better off before you started. Not to worry; Vim has a +quit-and-throw-things-away command. It is: > + + :q! + +Don't forget to press <Enter> to finish the command. + +For those of you interested in the details, the three parts of this command +are the colon (:), which enters Command-line mode; the q command, which tells +the editor to quit; and the override command modifier (!). + The override command modifier is needed because Vim is reluctant to throw +away changes. If you were to just type ":q", Vim would display an error +message and refuse to exit: + + E37: No write since last change (use ! to override) ~ + +By specifying the override, you are in effect telling Vim, "I know that what +I'm doing looks stupid, but I'm a big boy and really want to do this." + +If you want to continue editing with Vim: The ":e!" command reloads the +original version of the file. + +============================================================================== +*02.8* Finding help + +Everything you always wanted to know can be found in the Vim help files. +Don't be afraid to ask! + +If you know what you are looking for, it is usually easier to search for it +using the help system, instead of using Google. Because the subjects follow +a certain style guide. + +Also the help has the advantage of belonging to your particular Vim version. +You won't see help for commands added later. These would not work for you. + +To get generic help use this command: > + + :help + +You could also use the first function key <F1>. If your keyboard has a <Help> +key it might work as well. + If you don't supply a subject, ":help" displays the general help window. +The creators of Vim did something very clever (or very lazy) with the help +system: They made the help window a normal editing window. You can use all +the normal Vim commands to move through the help information. Therefore h, j, +k, and l move left, down, up and right. + To get out of the help window, use the same command you use to get out of +the editor: "ZZ". This will only close the help window, not exit Vim. + +As you read the help text, you will notice some text enclosed in vertical bars +(for example, |help|). This indicates a hyperlink. If you position the +cursor anywhere between the bars and press CTRL-] (jump to tag), the help +system takes you to the indicated subject. (For reasons not discussed here, +the Vim terminology for a hyperlink is tag. So CTRL-] jumps to the location +of the tag given by the word under the cursor.) + After a few jumps, you might want to go back. CTRL-T (pop tag) takes you +back to the preceding position. CTRL-O (jump to older position) also works +nicely here. + At the top of the help screen, there is the notation *help.txt*. This name +between "*" characters is used by the help system to define a tag (hyperlink +destination). + See |29.1| for details about using tags. + +To get help on a given subject, use the following command: > + + :help {subject} + +To get help on the "x" command, for example, enter the following: > + + :help x + +To find out how to delete text, use this command: > + + :help deleting + +To get a complete index of all Vim commands, use the following command: > + + :help index + +When you need to get help for a control character command (for example, +CTRL-A), you need to spell it with the prefix "CTRL-". > + + :help CTRL-A + +The Vim editor has many different modes. By default, the help system displays +the normal-mode commands. For example, the following command displays help +for the normal-mode CTRL-H command: > + + :help CTRL-H + +To identify other modes, use a mode prefix. If you want the help for the +insert-mode version of a command, use "i_". For CTRL-H this gives you the +following command: > + + :help i_CTRL-H + +When you start the Vim editor, you can use several command-line arguments. +These all begin with a dash (-). To find what the -t argument does, for +example, use the command: > + + :help -t + +The Vim editor has a number of options that enable you to configure and +customize the editor. If you want help for an option, you need to enclose it +in single quotation marks. To find out what the 'number' option does, for +example, use the following command: > + + :help 'number' + +The table with all mode prefixes can be found below: |help-summary|. + +Special keys are enclosed in angle brackets. To find help on the up-arrow key +in Insert mode, for instance, use this command: > + + :help i_<Up> + +If you see an error message that you don't understand, for example: + + E37: No write since last change (use ! to override) ~ + +You can use the error ID at the start to find help about it: > + + :help E37 + + +Summary: *help-summary* > + +1) Use Ctrl-D after typing a topic and let Vim show all available topics. + Or press Tab to complete: > + :help some<Tab> +< More information on how to use the help: > + :help helphelp + +2) Follow the links in bars to related help. You can go from the detailed + help to the user documentation, which describes certain commands more from + a user perspective and less detailed. E.g. after: > + :help pattern.txt +< You can see the user guide topics |03.9| and |usr_27.txt| in the + introduction. + +3) Options are enclosed in single apostrophes. To go to the help topic for the + list option: > + :help 'list' +< If you only know you are looking for a certain option, you can also do: > + :help options.txt +< to open the help page which describes all option handling and then search + using regular expressions, e.g. textwidth. + Certain options have their own namespace, e.g.: > + :help cpo-<letter> +< for the corresponding flag of the 'cpoptions' settings, substitute <letter> + by a specific flag, e.g.: > + :help cpo-; +< And for the guioption flags: > + :help go-<letter> + +4) Normal mode commands do not have a prefix. To go to the help page for the + "gt" command: > + :help gt + +5) Insert mode commands start with i_. Help for deleting a word: > + :help i_CTRL-W + +6) Visual mode commands start with v_. Help for jumping to the other side of + the Visual area: > + :help v_o + +7) Command line editing and arguments start with c_. Help for using the + command argument %: > + :help c_% + +8) Ex-commands always start with ":", so to go to the :s command help: > + :help :s + +9) Commands specifically for debugging start with ">". To go to to the help + for the "cont" debug command: > + :help >cont + +10) Key combinations. They usually start with a single letter indicating + the mode for which they can be used. E.g.: > + :help i_CTRL-X +< takes you to the family of Ctrl-X commands for insert mode which can be + used to auto complete different things. Note, that certain keys will + always be written the same, e.g. Control will always be CTRL. + For normal mode commands there is no prefix and the topic is available at + :h CTRL-<Letter>. E.g. > + :help CTRL-W +< In contrast > + :help c_CTRL-R +< will describe what the Ctrl-R does when entering commands in the Command + line and > + :help v_Ctrl-A +< talks about incrementing numbers in visual mode and > + :help g_CTRL-A +< talks about the g<C-A> command (e.g. you have to press "g" then <Ctrl-A>). + Here the "g" stand for the normal command "g" which always expects a second + key before doing something similar to the commands starting with "z" + +11) Regexp items always start with /. So to get help for the "\+" quantifier + in Vim regexes: > + :help /\+ +< If you need to know everything about regular expressions, start reading + at: > + :help pattern.txt + +12) Registers always start with "quote". To find out about the special ":" + register: > + :help quote: + +13) Vim Script (VimL) is available at > + :help eval.txt +< Certain aspects of the language are available at :h expr-X where "X" is a + single letter. E.g. > + :help expr-! +< will take you to the topic describing the "!" (Not) operator for + VimScript. + Also important is > + :help function-list +< to find a short description of all functions available. Help topics for + VimL functions always include the "()", so: > + :help append() +< talks about the append VimL function rather than how to append text in the + current buffer. + +14) Mappings are talked about in the help page :h |map.txt|. Use > + :help mapmode-i +< to find out about the |:imap| command. Also use :map-topic + to find out about certain subtopics particular for mappings. e.g: > + :help :map-local +< for buffer-local mappings or > + :help map-bar +< for how the '|' is handled in mappings. + +15) Command definitions are talked about :h command-topic, so use > + :help command-bar +< to find out about the '!' argument for custom commands. + +16) Window management commands always start with CTRL-W, so you find the + corresponding help at :h CTRL-W_letter. E.g. > + :help CTRL-W_p +< for moving the previous accessed window. You can also access > + :help windows.txt +< and read your way through if you are looking for window handling + commands. + +17) Use |:helpgrep| to search in all help pages (and also of any installed + plugins). See |:helpgrep| for how to use it. + To search for a topic: > + :helpgrep topic +< This takes you to the first match. To go to the next one: > + :cnext +< All matches are available in the quickfix window which can be opened + with: > + :copen +< Move around to the match you like and press Enter to jump to that help. + +18) The user manual. This describes help topics for beginners in a rather + friendly way. Start at |usr_toc.txt| to find the table of content (as you + might have guessed): > + :help usr_toc.txt +< Skim over the contents to find interesting topics. The "Digraphs" and + "Entering special characters" items are in chapter 24, so to go to that + particular help page: > + :help usr_24.txt +< Also if you want to access a certain chapter in the help, the chapter + number can be accessed directly like this: > + :help 10.1 +< goes to chapter 10.1 in |usr_10.txt| and talks about recording macros. + +19) Highlighting groups. Always start with hl-groupname. E.g. > + :help hl-WarningMsg +< talks about the WarningMsg highlighting group. + +20) Syntax highlighting is namespaced to :syn-topic e.g. > + :help :syn-conceal +< talks about the conceal argument for the :syn command. + +21) Quickfix commands usually start with :c while location list commands + usually start with :l + +22) Autocommand events can be found by their name: > + :help BufWinLeave +< To see all possible events: > + :help autocommands-events + +23) Command-line switches always start with "-". So for the help of the -f + command switch of Vim use: > + :help -f + +24) Optional features always start with "+". To find out about the + conceal feature use: > + :help +conceal + +25) Documentation for included filetype specific functionality is usually + available in the form ft-<filetype>-<functionality>. So > + :help ft-c-syntax +< talks about the C syntax file and the option it provides. Sometimes, + additional sections for omni completion > + :help ft-php-omni +< or filetype plugins > + :help ft-tex-plugin +< are available. + +26) Error and Warning codes can be looked up directly in the help. So > + :help E297 +< takes you exactly to the description of the swap error message and > + :help W10 +< talks about the warning "Changing a readonly file". + Sometimes however, those error codes are not described, but rather are + listed at the Vim command that usually causes this. So: > + :help E128 +< takes you to the |:function| command + + +============================================================================== + +Next chapter: |usr_03.txt| Moving around + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/en/usr_03.txt b/en/usr_03.txt new file mode 100644 index 000000000..4f72214bb --- /dev/null +++ b/en/usr_03.txt @@ -0,0 +1,657 @@ +*usr_03.txt* For Vim version 7.4. Last change: 2016 Jan 05 + + 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. If you try this +out in the help directly, 'iskeyword' needs to be reset for the examples to +work: > + :set iskeyword& +It is also possible to move by white-space separated WORDs. This is not a +word in the normal sense, that's why the uppercase is used. The commands for +moving by WORDs are also uppercase, as this figure shows: + + ge b w e + <- <- ---> ---> + This is-a line, with special/separated/words (and some more). ~ + <----- <----- --------------------> -----> + gE B W E + +With this mix of lowercase and uppercase commands, you can quickly move +forward and backward through a paragraph. + +============================================================================== +*03.2* Moving to the start or end of a line + +The "$" command moves the cursor to the end of a line. If your keyboard has +an <End> key it will do the same thing. + +The "^" command moves to the first non-blank character of the line. The "0" +command (zero) moves to the very first character of the line. The <Home> key +does the same thing. In a picture: + + ^ + <------------ + .....This is a line with example text ~ + <----------------- ---------------> + 0 $ + +(the "....." indicates blanks here) + + The "$" command takes a count, like most movement commands. But moving to +the end of the line several times doesn't make sense. Therefore it causes the +editor to move to the end of another line. For example, "1$" moves you to +the end of the first line (the one you're on), "2$" to the end of the next +line, and so on. + The "0" command doesn't take a count argument, because the "0" would be +part of the count. Unexpectedly, using a count with "^" doesn't have any +effect. + +============================================================================== +*03.3* Moving to a character + +One of the most useful movement commands is the single-character search +command. The command "fx" searches forward in the line for the single +character x. Hint: "f" stands for "Find". + For example, you are at the beginning of the following line. Suppose you +want to go to the h of human. Just execute the command "fh" and the cursor +will be positioned over the h: + + To err is human. To really foul up you need a computer. ~ + ---------->---------------> + fh fy + +This also shows that the command "fy" moves to the end of the word really. + You can specify a count; therefore, you can go to the "l" of "foul" with +"3fl": + + To err is human. To really foul up you need a computer. ~ + ---------------------> + 3fl + +The "F" command searches to the left: + + To err is human. To really foul up you need a computer. ~ + <--------------------- + Fh + +The "tx" command works like the "fx" command, except it stops one character +before the searched character. Hint: "t" stands for "To". The backward +version of this command is "Tx". + + To err is human. To really foul up you need a computer. ~ + <------------ -------------> + Th tn + +These four commands can be repeated with ";". "," repeats in the other +direction. The cursor is never moved to another line. Not even when the +sentence continues. + +Sometimes you will start a search, only to realize that you have typed the +wrong command. You type "f" to search backward, for example, only to realize +that you really meant "F". To abort a search, press <Esc>. So "f<Esc>" is an +aborted forward search and doesn't do anything. Note: <Esc> cancels most +operations, not just searches. + +============================================================================== +*03.4* Matching a 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 <BS>) to make corrections. Use +the <Left> and <Right> cursor keys when necessary. + Pressing <Enter> 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 <Enter>. If +you press <Up> (the cursor key), Vim puts "/three" on the command line. +Pressing <Enter> at this point searches for three. If you do not press +<Enter>, but press <Up> instead, Vim changes the prompt to "/two". Another +press of <Up> moves you to "/one". + You can also use the <Down> cursor key to move through the history of +search commands in the other direction. + +If you know what a previously used pattern starts with, and you want to use it +again, type that character before pressing <Up>. With the previous example, +you can type "/o<Up>" and Vim will put "/one" on the command line. + +The commands starting with ":" also have a history. That allows you to recall +a previous command and execute it again. These two histories are separate. + + +SEARCHING FOR A WORD IN THE TEXT + +Suppose you see the word "TheLongFunctionName" in the text and you want to +find the next occurrence of it. You could type "/TheLongFunctionName", but +that's a lot of typing. And when you make a mistake Vim won't find it. + There is an easier way: Position the cursor on the word and use the "*" +command. Vim will grab the word under the cursor and use it as the search +string. + The "#" command does the same in the other direction. You can prepend a +count: "3*" searches for the third occurrence of the word under the cursor. + + +SEARCHING FOR WHOLE WORDS + +If you type "/the" it will also match "there". To only find words that end +in "the" use: > + + /the\> + +The "\>" item is a special marker that only matches at the end of a word. +Similarly "\<" only matches at the beginning of a word. Thus to search for +the word "the" only: > + + /\<the\> + +This does not match "there" or "soothe". Notice that the "*" and "#" commands +use these start-of-word and end-of-word markers to only find whole words (you +can use "g*" and "g#" to match partial words). + + +HIGHLIGHTING MATCHES + +While editing a program you see a variable called "nr". You want to check +where it's used. You could move the cursor to "nr" and use the "*" command +and press "n" to go along all the matches. + There is another way. Type this command: > + + :set hlsearch + +If you now search for "nr", Vim will highlight all matches. That is a very +good way to see where the variable is used, without the need to type commands. + To switch this off: > + + :set nohlsearch + +Then you need to switch it on again if you want to use it for the next search +command. If you only want to remove the highlighting, use this command: > + + :nohlsearch + +This doesn't reset the option. Instead, it disables the highlighting. As +soon as you execute a search command, the highlighting will be used again. +Also for the "n" and "N" commands. + + +TUNING SEARCHES + +There are a few options that change how searching works. These are the +essential ones: +> + :set incsearch + +This makes Vim display the match for the string while you are still typing it. +Use this to check if the right match will be found. Then press <Enter> to +really jump to that location. Or type more to change the search string. +> + :set nowrapscan + +This stops the search at the end of the file. Or, when you are searching +backwards, at the start of the file. The 'wrapscan' option is on by default, +thus searching wraps around the end of the file. + + +INTERMEZZO + +If you like one of the options mentioned before, and set it each time you use +Vim, you can put the command in your Vim startup file. + Edit the file, as mentioned at |not-compatible|. Or use this command to +find out where it is: > + + :scriptnames + +Edit the file, for example with: > + + :edit ~/.vimrc + +Then add a line with the command to set the option, just like you typed it in +Vim. Example: > + + Go:set hlsearch<Esc> + +"G" moves to the end of the file. "o" starts a new line, where you type the +":set" command. You end insert mode with <Esc>. Then write the file: > + + ZZ + +If you now start Vim again, the 'hlsearch' option will already be set. + +============================================================================== +*03.9* Simple search patterns + +The Vim editor uses regular expressions to specify what to search for. +Regular expressions are an extremely powerful and compact way to specify a +search pattern. Unfortunately, this power comes at a price, because regular +expressions are a bit tricky to specify. + In this section we mention only a few essential ones. More about search +patterns and commands in chapter 27 |usr_27.txt|. You can find the full +explanation here: |pattern|. + + +BEGINNING AND END OF A LINE + +The ^ character matches the beginning of a line. On an English-US keyboard +you find it above the 6. The pattern "include" matches the word include +anywhere on the line. But the pattern "^include" matches the word include +only if it is at the beginning of a line. + The $ character matches the end of a line. Therefore, "was$" matches the +word was only if it is at the end of a line. + +Let's mark the places where "the" matches in this example line with "x"s: + + the solder holding one of the chips melted and the ~ + xxx xxx xxx + +Using "/the$" we find this match: + + the solder holding one of the chips melted and the ~ + xxx + +And with "/^the" we find this one: + the solder holding one of the chips melted and the ~ + xxx + +You can try searching with "/^the$", it will only match a single line +consisting of "the". White space does matter here, thus if a line contains a +space after the word, like "the ", the pattern will not match. + + +MATCHING ANY SINGLE CHARACTER + +The . (dot) character matches any existing character. For example, the +pattern "c.m" matches a string whose first character is a c, whose second +character is anything, and whose third character is m. Example: + + We use a computer that became the cummin winter. ~ + xxx xxx xxx + + +MATCHING SPECIAL CHARACTERS + +If you really want to match a dot, you must avoid its special meaning by +putting a backslash before it. + If you search for "ter.", you will find these matches: + + We use a computer that became the cummin winter. ~ + xxxx xxxx + +Searching for "ter\." only finds the second match. + +============================================================================== +*03.10* Using marks + +When you make a jump to a position with the "G" command, Vim remembers the +position from before this jump. This position is called a mark. To go back +where you came from, use this command: > + + `` + +This ` is a backtick or open single-quote character. + If you use the same command a second time you will jump back again. That's +because the ` command is a jump itself, and the position from before this jump +is remembered. + +Generally, every time you do a command that can move the cursor further than +within the same line, this is called a jump. This includes the search +commands "/" and "n" (it doesn't matter how far away the match is). But not +the character searches with "fx" and "tx" or the word movements "w" and "e". + Also, "j" and "k" are not considered to be a jump. Even when you use a +count to make them move the cursor quite a long way away. + +The `` command jumps back and forth, between two points. The CTRL-O command +jumps to older positions (Hint: O for older). CTRL-I then jumps back to newer +positions (Hint: I is just next to O on the keyboard). Consider this sequence +of commands: > + + 33G + /^The + CTRL-O + +You first jump to line 33, then search for a line that starts with "The". +Then with CTRL-O you jump back to line 33. Another CTRL-O takes you back to +where you started. If you now use CTRL-I you jump to line 33 again. And +to the match for "The" with another CTRL-I. + + + | example text ^ | + 33G | example text | CTRL-O | CTRL-I + | example text | | + V line 33 text ^ V + | example text | | + /^The | example text | CTRL-O | CTRL-I + V There you are | V + example text + + Note: + CTRL-I is the same as <Tab>. + +The ":jumps" command gives a list of positions you jumped to. The entry which +you used last is marked with a ">". + + +NAMED MARKS *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/en/usr_04.txt b/en/usr_04.txt new file mode 100644 index 000000000..5f24c8c6f --- /dev/null +++ b/en/usr_04.txt @@ -0,0 +1,514 @@ +*usr_04.txt* For Vim version 7.4. Last change: 2014 Aug 29 + + VIM USER MANUAL - by Bram Moolenaar + + Making small changes + + +This chapter shows you several ways of making corrections and moving text +around. It teaches you the three basic ways to change text: operator-motion, +Visual mode and text objects. + +|04.1| Operators and motions +|04.2| Changing text +|04.3| Repeating a change +|04.4| Visual mode +|04.5| Moving text +|04.6| Copying text +|04.7| Using the clipboard +|04.8| Text objects +|04.9| Replace mode +|04.10| Conclusion + + Next chapter: |usr_05.txt| Set your settings + Previous chapter: |usr_03.txt| Moving around +Table of contents: |usr_toc.txt| + +============================================================================== +*04.1* Operators and motions + +In chapter 2 you learned the "x" command to delete a single character. And +using a count: "4x" deletes four characters. + The "dw" command deletes a word. You may recognize the "w" command as the +move word command. In fact, the "d" command may be followed by any motion +command, and it deletes from the current location to the place where the +cursor winds up. + The "4w" command, for example, moves the cursor over four words. The d4w +command deletes four words. + + To err is human. To really foul up you need a computer. ~ + ------------------> + d4w + + To err is human. you need a computer. ~ + +Vim only deletes up to the position where the motion takes the cursor. That's +because Vim knows that you probably don't want to delete the first character +of a word. If you use the "e" command to move to the end of a word, Vim +guesses that you do want to include that last character: + + To err is human. you need a computer. ~ + --------> + d2e + + To err is human. a computer. ~ + +Whether the character under the cursor is included depends on the command you +used to move to that character. The reference manual calls this "exclusive" +when the character isn't included and "inclusive" when it is. + +The "$" command moves to the end of a line. The "d$" command deletes from the +cursor to the end of the line. This is an inclusive motion, thus the last +character of the line is included in the delete operation: + + To err is human. a computer. ~ + ------------> + d$ + + To err is human ~ + +There is a pattern here: operator-motion. You first type an operator command. +For example, "d" is the delete operator. Then you type a motion command like +"4l" or "w". This way you can operate on any text you can move over. + +============================================================================== +*04.2* Changing text + +Another operator is "c", change. It acts just like the "d" operator, except +it leaves you in Insert mode. For example, "cw" changes a word. Or more +specifically, it deletes a word and then puts you in Insert mode. + + To err is human ~ + -------> + c2wbe<Esc> + + To be human ~ + +This "c2wbe<Esc>" contains these bits: + + c the change operator + 2w move two words (they are deleted and Insert mode started) + be insert this text + <Esc> back to Normal mode + +If you have paid attention, you will have noticed something strange: The space +before "human" isn't deleted. There is a saying that for every problem there +is an answer that is simple, clear, and wrong. That is the case with the +example used here for the "cw" command. The c operator works just like the +d operator, with one exception: "cw". It actually works like "ce", change to +end of word. Thus the space after the word isn't included. This is an +exception that dates back to the old Vi. Since many people are used to it +now, the inconsistency has remained in Vim. + + +MORE CHANGES + +Like "dd" deletes a whole line, "cc" changes a whole line. It keeps the +existing indent (leading white space) though. + +Just like "d$" deletes until the end of the line, "c$" changes until the end +of the line. It's like doing "d$" to delete the text and then "a" to start +Insert mode and append new text. + + +SHORTCUTS + +Some operator-motion commands are used so often that they have been given a +single letter command: + + x stands for dl (delete character under the cursor) + X stands for dh (delete character left of the cursor) + D stands for d$ (delete to end of the line) + C stands for c$ (change to end of the line) + s stands for cl (change one character) + S stands for cc (change a whole line) + + +WHERE TO PUT THE COUNT + +The commands "3dw" and "d3w" delete three words. If you want to get really +picky about things, the first command, "3dw", deletes one word three times; +the command "d3w" deletes three words once. This is a difference without a +distinction. You can actually put in two counts, however. For example, +"3d2w" deletes two words, repeated three times, for a total of six words. + + +REPLACING WITH ONE CHARACTER + +The "r" command is not an operator. It waits for you to type a character, and +will replace the character under the cursor with it. You could do the same +with "cl" or with the "s" command, but with "r" you don't have to press <Esc> + + there is somerhing grong here ~ + rT rt rw + + There is something wrong here ~ + +Using a count with "r" causes that many characters to be replaced with the +same character. Example: + + There is something wrong here ~ + 5rx + + There is something xxxxx here ~ + +To replace a character with a line break use "r<Enter>". This deletes one +character and inserts a line break. Using a count here only applies to the +number of characters deleted: "4r<Enter>" replaces four characters with one +line break. + +============================================================================== +*04.3* Repeating a change + +The "." command is one of the most simple yet powerful commands in Vim. It +repeats the last change. For instance, suppose you are editing an HTML file +and want to delete all the <B> tags. You position the cursor on the first < +and delete the <B> with the command "df>". You then go to the < of the next +</B> and kill it using the "." command. The "." command executes the last +change command (in this case, "df>"). To delete another tag, position the +cursor on the < and use the "." command. + + To <B>generate</B> a table of <B>contents ~ + f< find first < ---> + df> delete to > --> + f< find next < ---------> + . repeat df> ---> + f< find next < -------------> + . repeat df> --> + +The "." command works for all changes you make, except for the "u" (undo), +CTRL-R (redo) and commands that start with a colon (:). + +Another example: You want to change the word "four" to "five". It appears +several times in your text. You can do this quickly with this sequence of +commands: + + /four<Enter> find the first string "four" + cwfive<Esc> change the word to "five" + n find the next "four" + . repeat the change to "five" + n find the next "four" + . repeat the change + etc. + +============================================================================== +*04.4* Visual mode + +To delete simple items the operator-motion changes work quite well. But often +it's not so easy to decide which command will move over the text you want to +change. Then you can use Visual mode. + +You start Visual mode by pressing "v". You move the cursor over the text you +want to work on. While you do this, the text is highlighted. Finally type +the operator command. + For example, to delete from halfway one word to halfway another word: + + This is an examination sample of visual mode ~ + ----------> + velllld + + This is an example of visual mode ~ + +When doing this you don't really have to count how many times you have to +press "l" to end up in the right position. You can immediately see what text +will be deleted when you press "d". + +If at any time you decide you don't want to do anything with the highlighted +text, just press <Esc> and Visual mode will stop without doing anything. + + +SELECTING LINES + +If you want to work on whole lines, use "V" to start Visual mode. You will +see right away that the whole line is highlighted, without moving around. +When you move left or right nothing changes. When you move up or down the +selection is extended whole lines at a time. + For example, select three lines with "Vjj": + + +------------------------+ + | text more text | + >> | more text more text | | + selected lines >> | text text text | | Vjj + >> | text more | V + | more text more | + +------------------------+ + + +SELECTING BLOCKS + +If you want to work on a rectangular block of characters, use CTRL-V to start +Visual mode. This is very useful when working on tables. + + name Q1 Q2 Q3 + pierre 123 455 234 + john 0 90 39 + steve 392 63 334 + +To delete the middle "Q2" column, move the cursor to the "Q" of "Q2". Press +CTRL-V to start blockwise Visual mode. Now move the cursor three lines down +with "3j" and to the next word with "w". You can see the first character of +the last column is included. To exclude it, use "h". Now press "d" and the +middle column is gone. + + +GOING TO THE OTHER SIDE + +If you have selected some text in Visual mode, and discover that you need to +change the other end of the selection, use the "o" command (Hint: o for other +end). The cursor will go to the other end, and you can move the cursor to +change where the selection starts. Pressing "o" again brings you back to the +other end. + +When using blockwise selection, you have four corners. "o" only takes you to +one of the other corners, diagonally. Use "O" to move to the other corner in +the same line. + +Note that "o" and "O" in Visual mode work very 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 <Esc>. + In this example you start Replace mode on the first "t" of "text": + + This is text. ~ + Rinteresting.<Esc> + + This is interesting. ~ + +You may have noticed that this command replaced 5 characters in the line with +twelve others. The "R" command automatically extends the line if it runs out +of characters to replace. It will not continue on the next line. + +You can switch between Insert mode and Replace mode with the <Insert> key. + +When you use <BS> (backspace) to make correction, you will notice that the +old text is put back. Thus it works like an undo command for the last typed +character. + +============================================================================== +*04.10* Conclusion + +The operators, movement commands and text objects give you the possibility to +make lots of combinations. Now that you know how it works, you can use N +operators with M movement commands to make N * M commands! + +You can find a list of operators here: |operator| + +For example, there are many other ways to delete pieces of text. Here are a +few often used ones: + +x delete character under the cursor (short for "dl") +X delete character before the cursor (short for "dh") +D delete from cursor to end of line (short for "d$") +dw delete from cursor to next start of word +db delete from cursor to previous start of word +diw delete word under the cursor (excluding white space) +daw delete word under the cursor (including white space) +dG delete until the end of the file +dgg delete until the start of the file + +If you use "c" instead of "d" they become change commands. And with "y" you +yank the text. And so forth. + + +There are a few often used commands to make changes that didn't fit somewhere +else: + + ~ change case of the character under the cursor, and move the + cursor to the next character. This is not an operator (unless + 'tildeop' is set), thus you can't use it with a motion + command. It does 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/en/usr_05.txt b/en/usr_05.txt new file mode 100644 index 000000000..f71cf42cf --- /dev/null +++ b/en/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 <BS> is allowed to delete the +character in front of the cursor. The three items, separated by commas, tell +Vim to delete the white space at the start of the line, a line break and the +character before where Insert mode started. +> + + set autoindent + +This makes Vim use the indent of the previous line for a newly created line. +Thus there is the same amount of white space before the new line. For example +when pressing <Enter> in Insert mode, and when using the "o" command to open a +new line. +> + + if has("vms") + set nobackup + else + set backup + endif + +This tells Vim to keep a backup copy of a file when overwriting it. But not +on the VMS system, since it keeps old versions of files already. The backup +file will have the same name as the original file with "~" added. See |07.4| +> + + set history=50 + +Keep 50 commands and 50 search patterns in the history. Use another number if +you want to remember fewer or more lines. +> + + set ruler + +Always display the current cursor position in the lower right corner of the +Vim window. + +> + set showcmd + +Display an incomplete command in the lower right corner of the Vim window, +left of the ruler. For example, when you type "2f", Vim is waiting for you to +type the character to find and "2f" is displayed. When you press "w" next, +the "2fw" command is executed and the displayed "2f" is removed. + + +-------------------------------------------------+ + |text in the Vim window | + |~ | + |~ | + |-- VISUAL -- 2f 43,8 17% | + +-------------------------------------------------+ + ^^^^^^^^^^^ ^^^^^^^^ ^^^^^^^^^^ + 'showmode' 'showcmd' 'ruler' + +> + set incsearch + +Display the match for a search pattern when halfway typing it. + +> + map Q gq + +This defines a key mapping. More about that in the next section. This +defines the "Q" command to do formatting with the "gq" operator. This is how +it worked before Vim 5.0. Otherwise the "Q" command starts Ex mode, but you +will not need it. + +> + vnoremap _g y:exe "grep /" . escape(@", '\\/') . "/ *.c *.h"<CR> + +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 <F5> i{<Esc>ea}<Esc> +< + Note: + When entering this command, you must enter <F5> by typing four + characters. Similarly, <Esc> is not entered by pressing the <Esc> + key, but by typing five characters. Watch out for this difference + when reading the manual! + +Let's break this down: + <F5> The F5 function key. This is the trigger key that causes the + command to be executed as the key is pressed. + + i{<Esc> Insert the { character. The <Esc> key ends Insert mode. + + e Move to the end of the word. + + a}<Esc> Append the } to the word. + +After you execute the ":map" command, all you have to do to put {} around a +word is to put the cursor on the first character and press F5. + +In this example, the trigger is a single key; it can be any string. But when +you use an existing Vim command, that command will no longer be available. +You better avoid that. + One key that can be used with mappings is the backslash. Since you +probably want to define more than one mapping, add another character. You +could map "\p" to add parentheses around a word, and "\c" to add curly braces, +for example: > + + :map \p i(<Esc>ea)<Esc> + :map \c i{<Esc>ea}<Esc> + +You need to type the \ and the p quickly after another, so that Vim knows they +belong together. + +The ":map" command (with no arguments) lists your current mappings. At +least the ones for Normal mode. More about mappings in section |40.1|. + +============================================================================== +*05.4* Adding a plugin *add-plugin* *plugin* + +Vim's functionality can be extended by adding plugins. A plugin is nothing +more than a Vim script file that is loaded automatically when Vim starts. You +can add a plugin very easily by dropping it in your plugin directory. +{not available when Vim was compiled without the |+eval| feature} + +There are two types of plugins: + + global plugin: Used for all kinds of files + filetype plugin: Only used for a specific type of file + +The global plugins will be discussed first, then the filetype ones +|add-filetype-plugin|. + + +GLOBAL PLUGINS *standard-plugin* + +When you start Vim, it will automatically load a number of global plugins. +You don't have to do anything for this. They add functionality that most +people will want to use, but which was implemented as a Vim script instead of +being compiled into Vim. You can find them listed in the help index +|standard-plugin-list|. Also see |load-plugins|. + + *add-global-plugin* +You can add a global plugin to add functionality that will always be present +when you use Vim. There are only two steps for adding a global plugin: +1. Get a copy of the plugin. +2. Drop it in the right directory. + + +GETTING A GLOBAL PLUGIN + +Where can you find plugins? +- Some come with Vim. You can find them in the directory $VIMRUNTIME/macros + and its sub-directories. +- Download from the net. 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/<filetype>.vim + ftplugin/<filetype>_<name>.vim + ftplugin/<filetype>/<name>.vim + +Here "<name>" can be any name that you prefer. +Examples for the "stuff" filetype on Unix: > + + ~/.vim/ftplugin/stuff.vim + ~/.vim/ftplugin/stuff_def.vim + ~/.vim/ftplugin/stuff/header.vim + +The <filetype> part is the name of the filetype the plugin is to be used for. +Only files of this filetype will use the settings from the plugin. The <name> +part of the plugin file doesn't matter, you can use it to have several plugins +for the same filetype. Note that it must end in ".vim". + + +Further reading: +|filetype-plugins| Documentation for the filetype plugins and information + about how to avoid that mappings cause problems. +|load-plugins| When the global plugins are loaded during startup. +|ftplugin-overrule| Overruling the settings from a global plugin. +|write-plugin| How to write a plugin script. +|plugin-details| For more information about using plugins or when your + plugin doesn't work. +|new-filetype| How to detect a new file type. + +============================================================================== +*05.5* Adding a help file *add-local-help* *matchit-install* + +If you are lucky, the plugin you installed also comes with a help file. We +will explain how to install the help file, so that you can easily find help +for your new plugin. + Let us use the "matchit.vim" plugin as an example (it is included with +Vim). This plugin makes the "%" command jump to matching HTML tags, +if/else/endif in Vim scripts, etc. Very useful, although it's not backwards +compatible (that's why it is not enabled by default). + This plugin comes with documentation: "matchit.txt". Let's first copy the +plugin to the right directory. This time we will do it from inside Vim, so +that we can use $VIMRUNTIME. (You may skip some of the "mkdir" commands if +you already have the directory.) > + + :!mkdir ~/.vim + :!mkdir ~/.vim/plugin + :!cp $VIMRUNTIME/macros/matchit.vim ~/.vim/plugin + +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 +<Enter> to jump there. Press <Enter> again to jump back. Or use CTRL-O. + +You can change the value of an option. For example, move to the "displaying +text" subject. Then move the cursor down to this line: + + set wrap nowrap ~ + +When you hit <Enter>, the line will change to: + + set nowrap wrap ~ + +The option has now been switched off. + +Just above this line is a short description of the 'wrap' option. Move the +cursor one line up to place it in this line. Now hit <Enter> and you jump to +the full help on the 'wrap' option. + +For options that take a number or string argument you can edit the value. +Then press <Enter> to apply the new value. For example, move the cursor a few +lines up to this line: + + set so=0 ~ + +Position the cursor on the zero with "$". Change it into a five with "r5". +Then press <Enter> to apply the new value. When you now move the cursor +around you will notice that the text starts scrolling before you reach the +border. This is what the 'scrolloff' option does, it specifies an offset +from the window border where scrolling starts. + +============================================================================== +*05.7* Often used options + +There are an awful lot of options. Most of them you will hardly ever use. +Some of the more useful ones will be mentioned here. Don't forget you can +find more help on these options with the ":help" command, with single quotes +before and after the option name. For example: > + + :help 'wrap' + +In case you have messed up an option value, you can set it back to the +default by putting 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 <BS> key, when used in the first position of a line, to move +the cursor to the end of the previous line. And the <Space> key moves from +the end of a line to the start of the next one. + +To allow the cursor keys <Left> and <Right> to also wrap, use this command: > + + :set whichwrap=b,s,<,> + +This is still only for Normal mode. To let <Left> and <Right> do this in +Insert mode as well: > + + :set whichwrap=b,s,<,>,[,] + +There are a few other flags that can be added, see 'whichwrap'. + + +VIEWING TABS + +When there are tabs in a file, you cannot see where they are. To make them +visible: > + + :set list + +Now every tab is displayed as ^I. And a $ is displayed at the end of each +line, so that you can spot trailing spaces that would otherwise go unnoticed. + A disadvantage is that this looks ugly when there are many Tabs in a file. +If you have a color terminal, or are using the GUI, Vim can show the spaces +and tabs as highlighted characters. Use the 'listchars' option: > + + :set listchars=tab:>-,trail:- + +Now every tab will be displayed as ">---" (with more or less "-") and trailing +white space as "-". Looks a lot better, doesn't it? + + +KEYWORDS + +The 'iskeyword' option specifies which characters can appear in a word: > + + :set iskeyword +< iskeyword=@,48-57,_,192-255 ~ + +The "@" stands for all alphabetic letters. "48-57" stands for ASCII +characters 48 to 57, which are the numbers 0 to 9. "192-255" are the +printable latin characters. + Sometimes you will want to include a dash in keywords, so that commands +like "w" consider "upper-case" to be one word. You can do it like this: > + + :set iskeyword+=- + :set iskeyword +< iskeyword=@,48-57,_,192-255,- ~ + +If you look at the new value, you will see that Vim has added a comma for you. + To remove a character use "-=". For example, to remove the underscore: > + + :set iskeyword-=_ + :set iskeyword +< iskeyword=@,48-57,192-255,- ~ + +This time a comma is automatically deleted. + + +ROOM FOR MESSAGES + +When Vim starts there is one line at the bottom that is used for messages. +When a message is long, it is either truncated, thus you can only see part of +it, or the text scrolls and you have to press <Enter> to continue. + You can set the 'cmdheight' option to the number of lines used for +messages. Example: > + + :set cmdheight=3 + +This does mean there is less room to edit text, thus it's a compromise. + +============================================================================== + +Next chapter: |usr_06.txt| Using syntax highlighting + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/en/usr_06.txt b/en/usr_06.txt new file mode 100644 index 000000000..5e3c7726d --- /dev/null +++ b/en/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/en/usr_07.txt b/en/usr_07.txt new file mode 100644 index 000000000..8a0600b84 --- /dev/null +++ b/en/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/en/usr_08.txt b/en/usr_08.txt new file mode 100644 index 000000000..ef26b46eb --- /dev/null +++ b/en/usr_08.txt @@ -0,0 +1,601 @@ +*usr_08.txt* For Vim version 7.4. Last change: 2014 Jul 06 + + 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 +each other, 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/en/usr_09.txt b/en/usr_09.txt new file mode 100644 index 000000000..68575f518 --- /dev/null +++ b/en/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. <S-Left> (shifted cursor left key) moves the cursor left. The +selected text is changed like in Visual mode. The other shifted cursor keys +do what you expect. <S-End> and <S-Home> also work. + +You can tune the way Select mode works with the 'selectmode' option. + +============================================================================== + +Next chapter: |usr_10.txt| Making big changes + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/en/usr_10.txt b/en/usr_10.txt new file mode 100644 index 000000000..4398c4d64 --- /dev/null +++ b/en/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 "<Esc> Insert the string #include " at the beginning + of the line. + $ Move to the end of the line. + a"<Esc> Append the character double quotation mark (") + to the end of the line. + j Go to the next line. + q Stop recording the macro. + +Now that you have done the work once, you can repeat the change by typing the +command "@a" three times. + The "@a" command can be preceded by a count, which will cause the macro to +be executed that number of times. In this case you would type: > + + 3@a + + +MOVE AND EXECUTE + +You might have the lines you want to change in various places. Just move the +cursor to each location and use the "@a" command. If you have done that once, +you can do it again with "@@". That's a bit easier to type. If you now +execute register b with "@b", the next "@@" will use register b. + If you compare the playback method with using ".", there are several +differences. First of all, "." can only repeat one change. As seen in the +example above, "@a" can do several changes, and move around as well. +Secondly, "." can only remember the last change. Executing a register allows +you to make any changes and then still use "@a" to replay the recorded +commands. Finally, you can use 26 different registers. Thus you can remember +26 different command sequences to execute. + + +USING REGISTERS + +The registers used for recording are the same ones you used for yank and +delete commands. This allows you to mix recording with other commands to +manipulate the registers. + Suppose you have recorded a few commands in register n. When you execute +this with "@n" you notice you did something wrong. You could try recording +again, but perhaps you will make another mistake. Instead, use this trick: + + G Go to the end of the file. + o<Esc> Create an empty line. + "np Put the text from the n register. You now see + the commands you typed as text in the file. + {edits} Change the commands that were wrong. This is + just like editing text. + 0 Go to the start of the line. + "ny$ Yank the corrected commands into the n + register. + dd Delete the scratch line. + +Now you can execute the corrected commands with "@n". (If your recorded +commands include line breaks, adjust the last two items in the example to +include all the lines.) + + +APPENDING TO A REGISTER + +So far we have used a lowercase letter for the register name. To append to a +register, use an uppercase letter. + Suppose you have recorded a command to change a word to register c. It +works properly, but you would like to add a search for the next word to +change. This can be done with: > + + qC/word<Enter>q + +You start with "qC", which records to the c register and appends. Thus +writing to an uppercase register name means to append to the register with +the same letter, but lowercase. + +This works both with recording and with yank and delete commands. For +example, you want to collect a sequence of lines into the a register. Yank +the first line with: > + + "aY + +Now move to the second line, and type: > + + "AY + +Repeat this command for all lines. The a register now contains all those +lines, in the order you yanked them. + +============================================================================== +*10.2* Substitution *find-replace* + +The ":substitute" command enables you to perform string replacements on a +whole range of lines. The general form of this command is as follows: > + + :[range]substitute/from/to/[flags] + +This command changes the "from" string to the "to" string in the lines +specified with [range]. For example, you can change "Professor" to "Teacher" +in all lines with the following command: > + + :%substitute/Professor/Teacher/ +< + Note: + The ":substitute" command is almost never spelled out completely. + Most of the time, people use the abbreviated version ":s". From here + on the abbreviation will be used. + +The "%" before the command specifies the command works on all lines. Without +a range, ":s" only works on the current line. More about ranges in the next +section |10.3|. + +By default, the ":substitute" command changes only the first occurrence on +each line. For example, the preceding command changes the line: + + Professor Smith criticized Professor Johnson today. ~ + +to: + + Teacher Smith criticized Professor Johnson today. ~ + +To change every occurrence on the line, you need to add the g (global) flag. +The command: > + + :%s/Professor/Teacher/g + +results in (starting with the original line): + + Teacher Smith criticized Teacher Johnson today. ~ + +Other flags include p (print), which causes the ":substitute" command to print +out 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}<Esc>" inserts the text {string} in each line, just +left of the visual block. You start by pressing CTRL-V to enter visual block +mode. Now you move the cursor to define your block. Next you type I to enter +Insert mode, followed by the text to insert. As you type, the text appears on +the first line only. + After you press <Esc> to end the insert, the text will magically be +inserted in the rest of the lines contained in the visual selection. Example: + + include one ~ + include two ~ + include three ~ + include four ~ + +Move the cursor to the "o" of "one" and press CTRL-V. Move it down with "3j" +to "four". You now have a block selection that spans four lines. Now type: > + + Imain.<Esc> + +The result: + + include main.one ~ + include main.two ~ + include main.three ~ + include main.four ~ + +If the block spans short lines that do not extend into the block, the text is +not inserted in that line. For example, make a Visual block selection that +includes the word "long" in the first and last line of this text, and thus has +no text selected in the second line: + + This is a long line ~ + short ~ + Any other long line ~ + + ^^^^ selected block + +Now use the command "Ivery <Esc>". The result is: + + This is a very long line ~ + short ~ + Any other very long line ~ + +In the short line no text was inserted. + +If the string you insert contains a newline, the "I" acts just like a Normal +insert command and affects only the first line of the block. + +The "A" command works the same way, except that it appends after the right +side of the block. 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<Esc>, you get +this result: + + This is a long line XXX ~ + short XXX ~ + Any other long line XXX ~ + +This really requires using the "$" command. Vim remembers that it was used. +Making the same selection by moving the cursor to the end of the longest line +with other movement commands will not have the same result. + + +CHANGING TEXT + +The Visual block "c" command deletes the block and then throws you into Insert +mode to enable you to type in a string. The string will be inserted in each +line in the block. + Starting with the same selection of the "long" words as above, then typing +"c_LONG_<Esc>", you get this: + + This is a _LONG_ line ~ + short ~ + Any other _LONG_ line ~ + +Just like with "I" the short line is not changed. Also, you can't enter a +newline in the new text. + +The "C" command deletes text from the left edge of the block to the end of +line. It then puts you in Insert mode so that you can type in a string, +which is added to the end of each line. + Starting with the same text again, and typing "Cnew text<Esc>" you get: + + This is a new text ~ + short ~ + Any other new text ~ + +Notice that, even though only the "long" word was selected, the text after it +is deleted as well. Thus only the location of the left edge of the visual +block really matters. + Again, short lines that do not reach into the block are excluded. + +Other commands that change the characters in the block: + + ~ swap case (a -> A and A -> a) + U make uppercase (a -> A and A -> A) + u make lowercase (a -> a and A -> a) + + +FILLING WITH A CHARACTER + +To fill the whole block with one character, use the "r" command. Again, +starting with the same example text from above, and then typing "rx": + + This is a xxxx line ~ + short ~ + Any other xxxx line ~ + + + Note: + If you want to include characters beyond the end of the line in the + block, check out the 'virtualedit' feature in chapter 25. + + +SHIFTING + +The command ">" shifts the selected text to the right one shift amount, +inserting whitespace. The starting point for this shift is the left edge of +the visual block. + With the same example again, ">" gives this result: + + This is a long line ~ + short ~ + Any other long line ~ + +The shift amount is specified with the 'shiftwidth' option. To change it to +use 4 spaces: > + + :set shiftwidth=4 + +The "<" command removes one shift amount of whitespace at the left +edge of the block. This command is limited by the amount of text that is +there; so if there is less than a shift amount of whitespace available, it +removes what it can. + + +JOINING LINES + +The "J" command joins all selected lines together into one line. Thus it +removes the line breaks. Actually, the line break, leading white space and +trailing white space is replaced by one space. Two spaces are used after a +line ending (that can be changed with the 'joinspaces' option). + Let's use the example that we got so familiar with now. The result of +using the "J" command: + + This is a long line short Any other long line ~ + +The "J" command doesn't require a blockwise selection. It works with "v" and +"V" selection in exactly the same way. + +If you don't want the white space to be changed, use the "gJ" command. + +============================================================================== +*10.6* Reading and writing part of a file + +When you are writing an e-mail message, you may want to include another file. +This can be done with the ":read {filename}" command. The text of the file is +put below the cursor line. + Starting with this text: + + Hi John, ~ + Here is the diff that fixes the bug: ~ + Bye, Pierre. ~ + +Move the cursor to the second line and type: > + + :read patch + +The file named "patch" will be inserted, with this result: + + Hi John, ~ + Here is the diff that fixes the bug: ~ + 2c2 ~ + < for (i = 0; i <= length; ++i) ~ + --- ~ + > for (i = 0; i < length; ++i) ~ + Bye, Pierre. ~ + +The ":read" command accepts a range. The file will be put below the last line +number of this range. Thus ":$r patch" appends the file "patch" at the end of +the file. + What if you want to read the file above the first line? This can be done +with the line number zero. This line doesn't really exist, you will get an +error message when using it with most commands. But this command is allowed: +> + :0read patch + +The file "patch" will be put above the first line of the file. + + +WRITING A RANGE OF LINES + +To write a range of lines to a file, the ":write" command can be used. +Without a range it writes the whole file. With a range only the specified +lines are written: > + + :.,$write tempo + +This writes the lines from the cursor until the end of the file into the file +"tempo". If this file already exists you will get an error message. Vim +protects you from accidentally overwriting an existing file. If you know what +you are doing and want to overwrite the file, append !: > + + :.,$write! tempo + +CAREFUL: The ! must follow the ":write" command immediately, without white +space. Otherwise it becomes a filter command, which is explained later in +this chapter. + + +APPENDING TO A FILE + +In the first section of this chapter was explained how to collect a number of +lines into a register. The same can be done to collect lines in a file. +Write the first line with this command: > + + :.write collection + +Now move the cursor to the second line you want to collect, and type this: > + + :.write >>collection + +The ">>" tells Vim the "collection" file is not to be written as a new file, +but the line must be appended at the end. You can repeat this as many times +as you like. + +============================================================================== +*10.7* Formatting text + +When you are typing plain text, it's nice if the length of each line is +automatically trimmed to fit in the window. To make this happen while +inserting text, set the 'textwidth' option: > + + :set textwidth=72 + +You might remember that in the example vimrc file this command was used for +every text file. Thus if you are using that vimrc file, you were already +using it. To check the current value of 'textwidth': > + + :set textwidth + +Now lines will be broken to take only up to 72 characters. But when you +insert text halfway a line, or when you delete a few words, the lines will get +too long or too short. Vim doesn't automatically reformat the text. + To tell Vim to format the current paragraph: > + + gqap + +This starts with the "gq" command, which is an operator. Following is "ap", +the text object that stands for "a paragraph". A paragraph is separated from +the next paragraph by an empty line. + + Note: + A blank line, which contains white space, does NOT separate + paragraphs. This is hard to notice! + +Instead of "ap" you could use any motion or text object. If your paragraphs +are properly separated, you can use this command to format the whole file: > + + gggqG + +"gg" takes you to the first line, "gq" is the format operator and "G" the +motion that jumps to the last line. + +In case your paragraphs aren't clearly defined, you can format just the lines +you manually select. Move the cursor to the first line you want to format. +Start with the command "gqj". This formats the current line and the one below +it. If the first line was short, words from the next line will be appended. +If it was too long, words will be moved to the next line. The cursor moves to +the second line. Now you can use "." to repeat the command. Keep doing this +until you are at the end of the text you want to format. + +============================================================================== +*10.8* Changing case + +You have text with section headers in lowercase. You want to make the word +"section" all uppercase. Do this with the "gU" operator. Start with the +cursor in the first column: > + + gUw +< section header ----> SECTION header + +The "gu" operator does exactly the opposite: > + + guw +< SECTION header ----> section header + +You can also use "g~" to swap case. All these are operators, thus they work +with any motion command, with text objects and in Visual mode. + To make an operator work on lines you double it. The delete operator is +"d", thus to delete a line you use "dd". Similarly, "gugu" makes a whole line +lowercase. This can be shortened to "guu". "gUgU" is shortened to "gUU" and +"g~g~" to "g~~". Example: > + + g~~ +< Some GIRLS have Fun ----> sOME girls HAVE fUN ~ + +============================================================================== +*10.9* Using an external program + +Vim has a very powerful set of commands, it can do anything. But there may +still be something that an external command can do better or faster. + The command "!{motion}{program}" takes a block of text and filters it +through an external program. In other words, it runs the system command +represented by {program}, giving it the block of text represented by {motion} +as input. The output of this command then replaces the selected block. + Because this summarizes badly if you are unfamiliar with UNIX filters, take +a look at an example. The sort command sorts a file. If you execute the +following command, the unsorted file input.txt will be sorted and written to +output.txt. (This works on both UNIX and Microsoft Windows.) > + + sort <input.txt >output.txt + +Now do the same thing in Vim. You want to sort lines 1 through 5 of a file. +You start by putting the cursor on line 1. Next you execute the following +command: > + + !5G + +The "!" tells Vim that you are performing a filter operation. The Vim editor +expects a motion command to follow, indicating which part of the file to +filter. The "5G" command tells Vim to go to line 5, so it now knows that it +is to filter lines 1 (the current line) through 5. + In anticipation of the filtering, the cursor drops to the bottom of the +screen and a ! prompt displays. You can now type in the name of the filter +program, in this case "sort". Therefore, your full command is as follows: > + + !5Gsort<Enter> + +The result is that the sort program is run on the first 5 lines. The output +of the program replaces these lines. + + line 55 line 11 + line 33 line 22 + line 11 --> line 33 + line 22 line 44 + line 44 line 55 + last line last line + +The "!!" command filters the current line through a filter. In Unix the "date" +command prints the current time and date. "!!date<Enter>" replaces the current +line with the output of "date". This is useful to add a timestamp to a file. + + +WHEN IT DOESN'T WORK + +Starting a shell, sending it text and capturing the output requires that Vim +knows how the shell works exactly. When you have problems with filtering, +check the values of these options: + + 'shell' specifies the program that Vim uses to execute + external programs. + 'shellcmdflag' argument to pass a command to the shell + 'shellquote' quote to be used around the command + 'shellxquote' quote to be used around the command and redirection + 'shelltype' kind of shell (only for the Amiga) + 'shellslash' use forward slashes in the command (only for + MS-Windows and alikes) + 'shellredir' string used to write the command output into a file + +On Unix this is hardly ever a problem, because there are two kinds of shells: +"sh" like and "csh" like. Vim checks the 'shell' option and sets related +options automatically, depending on whether it sees "csh" somewhere in +'shell'. + On MS-Windows, however, there are many different shells and you might have +to tune the options to make filtering work. Check the help for the options +for more information. + + +READING COMMAND OUTPUT + +To read the contents of the current directory into the file, use this: + +on Unix: > + :read !ls +on MS-Windows: > + :read !dir + +The output of the "ls" or "dir" command is captured and inserted in the text, +below the cursor. This is similar to reading a file, except that the "!" is +used to tell Vim that a command follows. + The command may have arguments. And a range can be used to tell where Vim +should put the lines: > + + :0read !date -u + +This inserts the current time and date in UTC format at the top of the file. +(Well, if you have a date command that accepts the "-u" argument.) Note the +difference with using "!!date": that replaced a line, while ":read !date" will +insert a line. + + +WRITING TEXT TO A COMMAND + +The Unix command "wc" counts words. To count the words in the current file: > + + :write !wc + +This is the same write command as before, but instead of a file name the "!" +character is used and the name of an external command. The written text will +be passed to the specified command as its standard input. The output could +look like this: + + 4 47 249 ~ + +The "wc" command isn't verbose. This means you have 4 lines, 47 words and 249 +characters. + +Watch out for this mistake: > + + :write! wc + +This will write the file "wc" in the current directory, with force. White +space is important here! + + +REDRAWING THE SCREEN + +If the external command produced an error message, the display may have been +messed up. Vim is very efficient and only redraws those parts of the screen +that it knows need redrawing. But it can't know about what another program +has written. To tell Vim to redraw the screen: > + + CTRL-L + +============================================================================== + +Next chapter: |usr_11.txt| Recovering from a crash + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/en/usr_11.txt b/en/usr_11.txt new file mode 100644 index 000000000..9935ded48 --- /dev/null +++ b/en/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/en/usr_12.txt b/en/usr_12.txt new file mode 100644 index 000000000..fba1b5327 --- /dev/null +++ b/en/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/\<four/4/g + +Obviously, this still goes wrong on "fourteen". Use "\>" to match the end of +a word: > + + :%s/\<four\>/4/g + +If you are programming, you might want to replace "four" in comments, but not +in the code. Since this is difficult to specify, add the "c" flag to have the +substitute command prompt you for each replacement: > + + + :%s/\<four\>/4/gc + + +REPLACING IN SEVERAL FILES + +Suppose you want to replace a word in more than one file. You could edit each +file and type the command manually. It's a lot faster to use record and +playback. + Let's assume you have a directory with C++ files, all ending in ".cpp". +There is a function called "GetResp" that you want to rename to "GetAnswer". + + vim *.cpp Start Vim, defining the argument list to + contain all the C++ files. You are now in the + first file. + qq Start recording into the q register + :%s/\<GetResp\>/GetAnswer/g + Do the replacements in the first file. + :wnext Write this file and move to the next one. + q Stop recording. + @q Execute the q register. This will replay the + substitution and ":wnext". You can verify + that this doesn't produce an error message. + 999@q Execute the q register on the remaining files. + +At the last file you will get an error message, because ":wnext" cannot move +to the next file. This stops the execution, and everything is done. + + Note: + When playing back a recorded sequence, an error stops the execution. + Therefore, make sure you don't get an error message when recording. + +There is one catch: If one of the .cpp files does not contain the word +"GetResp", you will get an error and replacing will stop. To avoid this, add +the "e" flag to the substitute command: > + + :%s/\<GetResp\>/GetAnswer/ge + +The "e" flag tells ":substitute" that not finding a match is not an error. + +============================================================================== +*12.2* Change "Last, First" to "First Last" + +You have a list of names in this form: + + Doe, John ~ + Smith, Peter ~ + +You want to change that to: + + John Doe ~ + Peter Smith ~ + +This can be done with just one command: > + + :%s/\([^,]*\), \(.*\)/\2 \1/ + +Let's break this down in parts. Obviously it starts with a substitute +command. The "%" is the line range, which stands for the whole file. Thus +the substitution is done in every line in the file. + The arguments for the substitute command are "/from/to/". The slashes +separate the "from" pattern and the "to" string. This is what the "from" +pattern contains: + \([^,]*\), \(.*\) ~ + + The first part between \( \) matches "Last" \( \) + match anything but a comma [^,] + any number of times * + matches ", " literally , + The second part between \( \) matches "First" \( \) + any character . + any number of times * + +In the "to" part we have "\2" and "\1". These are called backreferences. +They refer to the text matched by the "\( \)" parts in the pattern. "\2" +refers to the text matched by the second "\( \)", which is the "First" name. +"\1" refers to the first "\( \)", which is the "Last" name. + You can use up to nine backreferences in the "to" part of a substitute +command. "\0" stands for the whole matched pattern. There are a few more +special items in a substitute command, see |sub-replace-special|. + +============================================================================== +*12.3* Sort a list + +In a Makefile you often have a list of files. For example: + + OBJS = \ ~ + version.o \ ~ + pch.o \ ~ + getopt.o \ ~ + util.o \ ~ + getopt1.o \ ~ + inp.o \ ~ + patch.o \ ~ + backup.o ~ + +To sort this list, filter the text through the external sort command: > + + /^OBJS + j + :.,/^$/-1!sort + +This goes to the first line, where "OBJS" is the first thing in the line. +Then it goes one line down and filters the lines until the next empty line. +You could also select the lines in Visual mode and then use "!sort". That's +easier to type, but more work when there are many lines. + The result is this: + + OBJS = \ ~ + backup.o ~ + getopt.o \ ~ + getopt1.o \ ~ + inp.o \ ~ + patch.o \ ~ + pch.o \ ~ + util.o \ ~ + version.o \ ~ + + +Notice that a backslash at the end of each line is used to indicate the line +continues. After sorting, this is wrong! The "backup.o" line that was at +the end didn't have a backslash. Now that it sorts to another place, it +must have a backslash. + The simplest solution is to add the backslash with "A \<Esc>". You can +keep the backslash in the last line, if you make sure an empty line comes +after it. That way you don't have this problem again. + +============================================================================== +*12.4* Reverse line order + +The |:global| command can be combined with the |:move| command to move all the +lines before the first line, resulting in a reversed file. The command is: > + + :global/^/m 0 + +Abbreviated: > + + :g/^/m 0 + +The "^" regular expression matches the beginning of the line (even if the line +is blank). The |:move| command moves the matching line to after the mythical +zeroth line, so the current matching line becomes the first line of the file. +As the |:global| command is not confused by the changing line numbering, +|:global| proceeds to match all remaining lines of the file and puts each as +the first. + +This also works on a range of lines. First move to above the first line and +mark it with "mt". Then move the cursor to the last line in the range and +type: > + + :'t+1,.g/^/m 't + +============================================================================== +*12.5* Count words + +Sometimes you have to write a text with a maximum number of words. Vim can +count the words for you. + When the whole file is what you want to count the words in, use this +command: > + + g CTRL-G + +Do not type a space after the g, this is just used here to make the command +easy to read. + The output looks like this: + + Col 1 of 0; Line 141 of 157; Word 748 of 774; Byte 4489 of 4976 ~ + +You can see on which word you are (748), and the total number of words in the +file (774). + +When the text is only part of a file, you could move to the start of the text, +type "g CTRL-G", move to the end of the text, type "g CTRL-G" again, and then +use your brain to compute the difference in the word position. That's a good +exercise, but there is an easier way. With Visual mode, select the text you +want to count words in. Then type g CTRL-G. The result: + + Selected 5 of 293 Lines; 70 of 1884 Words; 359 of 10928 Bytes ~ + +For other ways to count words, lines and other items, see |count-items|. + +============================================================================== +*12.6* Find a man page *find-manpage* + +While editing a shell script or C program, you are using a command or function +that you want to find the man page for (this is on Unix). Let's first use a +simple way: Move the cursor to the word you want to find help on and press > + + K + +Vim will run the external "man" program on the word. If the man page is +found, it is displayed. This uses the normal pager to scroll through the text +(mostly the "more" program). When you get to the end pressing <Enter> will +get you back into Vim. + +A disadvantage is that you can't see the man page and the text you are working +on at the same time. There is a trick to make the man page appear in a Vim +window. First, load the man filetype plugin: > + + :runtime! ftplugin/man.vim + +Put this command in your vimrc file if you intend to do this often. Now you +can use the ":Man" command to open a window on a man page: > + + :Man csh + +You can scroll around and the text is highlighted. This allows you to find +the help you were looking for. Use CTRL-W w to jump to the window with the +text you were working on. + To find a man page in a specific section, put the section number first. +For example, to look in section 3 for "echo": > + + :Man 3 echo + +To jump to another man page, which is in the text with the typical form +"word(1)", press CTRL-] on it. Further ":Man" commands will use the same +window. + +To display a man page for the word under the cursor, use this: > + + \K + +(If you redefined the <Leader>, use it instead of the backslash). +For example, you want to know the return value of "strstr()" while editing +this line: + + if ( strstr (input, "aap") == ) ~ + +Move the cursor to somewhere on "strstr" and type "\K". A window will open +to display the man page for strstr(). + +============================================================================== +*12.7* Trim blanks + +Some people find spaces and tabs at the end of a line useless, wasteful, and +ugly. To remove whitespace at the end of every line, execute the following +command: > + + :%s/\s\+$// + +The line range "%" is used, thus this works on the whole file. The pattern +that the ":substitute" command matches with is "\s\+$". This finds white +space characters (\s), 1 or more of them (\+), before the end-of-line ($). +Later will be explained how you write patterns like this |usr_27.txt|. + The "to" part of the substitute command is empty: "//". Thus it replaces +with nothing, effectively deleting the matched white space. + +Another wasteful use of spaces is placing them before a tab. Often these can +be deleted without changing the amount of white space. But not always! +Therefore, you can best do this manually. Use this search command: > + + / + +You cannot see it, but there is a space before a tab in this command. Thus +it's "/<Space><Tab>". Now use "x" to delete the space and check that the +amount of white space doesn't change. You might have to insert a tab if it +does change. Type "n" to find the next match. Repeat this until no more +matches can be found. + +============================================================================== +*12.8* Find where a word is used + +If you are a UNIX user, you can use a combination of Vim and the grep command +to edit all the files that contain a given word. This is extremely useful if +you are working on a program and want to view or edit all the files that +contain a specific variable. + For example, suppose you want to edit all the C program files that contain +the word "frame_counter". To do this you use the command: > + + vim `grep -l frame_counter *.c` + +Let's look at this command in detail. The grep command searches through a set +of files for a given word. Because the -l argument is specified, the command +will only list the files containing the word and not print the matching lines. +The word it is searching for is "frame_counter". Actually, this can be any +regular expression. (Note: What grep uses for regular expressions is not +exactly the same as what Vim uses.) + The entire command is enclosed in backticks (`). This tells the UNIX shell +to run this command and pretend that the results were typed on the command +line. So what happens is that the grep command is run and produces a list of +files, these files are put on the Vim command line. This results in Vim +editing the file list that is the output of grep. You can then use commands +like ":next" and ":first" to browse through the files. + + +FINDING EACH LINE + +The above command only finds the files in which the word is found. You still +have to find the word within the files. + Vim has a built-in command that you can use to search a set of files for a +given string. If you want to find all occurrences of "error_string" in all C +program files, for example, enter the following command: > + + :grep error_string *.c + +This causes Vim to search for the string "error_string" in all the specified +files (*.c). The editor will now open the first file where a match is found +and position the cursor on the first matching line. To go to the next +matching line (no matter in what 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/en/usr_20.txt b/en/usr_20.txt new file mode 100644 index 000000000..5f0a66018 --- /dev/null +++ b/en/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 <BS> key. +This erases the character before the cursor. To erase another character, +typed earlier, first move the cursor with the cursor keys. + For example, you have typed this: > + + :s/col/pig/ + +Before you hit <Enter>, you notice that "col" should be "cow". To correct +this, you type <Left> five times. The cursor is now just after "col". Type +<BS> and "w" to correct: > + + :s/cow/pig/ + +Now you can press <Enter> directly. You don't have to move the cursor to the +end of the line before executing the command. + +The most often used keys to move around in the command line: + + <Left> one character left + <Right> one character right + <S-Left> or <C-Left> one word left + <S-Right> or <C-Right> one word right + CTRL-B or <Home> to begin of command line + CTRL-E or <End> to end of command line + + Note: + <S-Left> (cursor left key with Shift key pressed) and <C-Left> (cursor + left key with Control pressed) will not work on all keyboards. Same + for the other Shift and Control combinations. + +You can also use the mouse to move the cursor. + + +DELETING + +As mentioned, <BS> deletes the character before the cursor. To delete a whole +word use CTRL-W. + + /the fine pig ~ + + CTRL-W + + /the fine ~ + +CTRL-U removes all text, thus allows you to start all over again. + + +OVERSTRIKE + +The <Insert> key toggles between inserting characters and replacing the +existing ones. Start with this text: + + /the fine pig ~ + +Move the cursor to the start of "fine" with <S-Left> twice (or <Left> eight +times, if <S-Left> doesn't work). Now press <Insert> to switch to overstrike +and type "great": + + /the greatpig ~ + +Oops, we lost the space. Now, don't use <BS>, because it would delete the +"t" (this is different from Replace mode). Instead, press <Insert> to switch +from overstrike to inserting, and type the space: + + /the great pig ~ + + +CANCELLING + +You thought of executing a : or / command, but changed your mind. To get rid +of what you already typed, without executing it, press CTRL-C or <Esc>. + + Note: + <Esc> is the universal "get out" key. Unfortunately, in the good old + Vi pressing <Esc> in a command line executed the command! Since that + might be considered to be a bug, Vim uses <Esc> to cancel the command. + But with the 'cpoptions' option it can be made Vi compatible. And + when using a mapping (which might be written for Vi) <Esc> also works + Vi compatible. Therefore, using CTRL-C is a method that always works. + +If you are at the start of the command line, pressing <BS> will cancel the +command. It's like deleting the ":" or "/" that the line starts with. + +============================================================================== +*20.2* Command line abbreviations + +Some of the ":" commands are really long. We already mentioned that +":substitute" can be abbreviated to ":s". This is a generic mechanism, all +":" commands can be abbreviated. + +How short can a command get? There are 26 letters, and many more commands. +For example, ":set" also starts with ":s", but ":s" doesn't start a ":set" +command. Instead ":set" can be abbreviated to ":se". + When the shorter form of a command could be used for two commands, it +stands for only one of them. There is no logic behind which one, you have to +learn them. In the help files the shortest form that works is mentioned. For +example: > + + :s[ubstitute] + +This means that the shortest form of ":substitute" is ":s". The following +characters are optional. Thus ":su" and ":sub" also work. + +In the user manual we will either use the full name of command, or a short +version that is still readable. For example, ":function" can be abbreviated +to ":fu". But since most people don't understand what that stands for, we +will use ":fun". (Vim doesn't have a ":funny" command, otherwise ":fun" would +be confusing too.) + +It is recommended that in Vim scripts you write the full command name. That +makes it easier to read back when you make later changes. Except for some +often used commands like ":w" (":write") and ":r" (":read"). + A particularly confusing one is ":end", which could stand for ":endif", +":endwhile" or ":endfunction". Therefore, always use the full name. + + +SHORT OPTION NAMES + +In the user manual the long version of the option names is used. Many options +also have a short name. Unlike ":" commands, there is only one short name +that works. For example, the short name of 'autoindent' is 'ai'. Thus these +two commands do the same thing: > + + :set autoindent + :set ai + +You can find the full list of long and short names here: |option-list|. + +============================================================================== +*20.3* Command line completion + +This is one of those Vim features that, by itself, is a reason to switch from +Vi to Vim. Once you have used this, you can't do without. + +Suppose you have a directory that contains these files: + + info.txt + intro.txt + bodyofthepaper.txt + +To edit the last one, you use the command: > + + :edit bodyofthepaper.txt + +It's easy to type this wrong. A much quicker way is: > + + :edit b<Tab> + +Which will result in the same command. What happened? The <Tab> key does +completion of the word before the cursor. In this case "b". Vim looks in the +directory and finds only one file that starts with a "b". That must be the +one you are looking for, thus Vim completes the file name for you. + +Now type: > + + :edit i<Tab> + +Vim will beep, and give you: > + + :edit info.txt + +The beep means that Vim has found more than one match. It then uses the first +match it found (alphabetically). If you press <Tab> again, you get: > + + :edit intro.txt + +Thus, if the first <Tab> doesn't give you the file you were looking for, press +it again. If there are more matches, you will see them all, one at a time. + If you press <Tab> on the last matching entry, you will go back to what you +first typed: > + + :edit i + +Then it starts all over again. Thus Vim cycles through the list of matches. +Use CTRL-P to go through the list in the other direction: + + <------------------- <Tab> -------------------------+ + | + <Tab> --> <Tab> --> + :edit i :edit info.txt :edit intro.txt + <-- CTRL-P <-- CTRL-P + | + +---------------------- CTRL-P ------------------------> + + +CONTEXT + +When you type ":set i" instead of ":edit i" and press <Tab> you get: > + + :set icon + +Hey, why didn't you get ":set info.txt"? That's because Vim has context +sensitive completion. The kind of words Vim will look for depends on the +command before it. Vim knows that you cannot use a file name just after a +":set" command, but you can use an option name. + Again, if you repeat typing the <Tab>, Vim will cycle through all matches. +There are quite a few, it's better to type more characters first: > + + :set isk<Tab> + +Gives: > + + :set iskeyword + +Now type "=" and press <Tab>: > + + :set iskeyword=@,48-57,_,192-255 + +What happens here is that Vim inserts the old value of the option. Now you +can edit it. + What is completed with <Tab> is what Vim expects in that place. Just try +it out to see how it works. In some situations you will not get what you +want. That's either because Vim doesn't know what you want, or because +completion was not implemented for that situation. In that case you will get +a <Tab> inserted (displayed as ^I). + + +LIST MATCHES + +When there are many matches, you would like to see an overview. Do this by +pressing CTRL-D. For example, pressing CTRL-D after: > + + :set is + +results in: > + + :set is + incsearch isfname isident iskeyword isprint + :set is + +Vim lists the matches and then comes back with the text you typed. You can +now check the list for the item you wanted. If it isn't there, you can use +<BS> to correct the word. If there are many matches, type a few more +characters before pressing <Tab> to complete the rest. + If you have watched carefully, you will have noticed that "incsearch" +doesn't start with "is". In this case "is" stands for the short name of +"incsearch". (Many options have a short and a long name.) Vim is clever +enough to know that you might have wanted to expand the short name of the +option into the long name. + + +THERE IS MORE + +The CTRL-L command completes the word to the longest unambiguous string. If +you type ":edit i" and there are files "info.txt" and "info_backup.txt" you +will get ":edit info". + +The 'wildmode' option can be used to change the way completion works. +The 'wildmenu' option can be used to get a menu-like list of matches. +Use the 'suffixes' option to specify files that are less important and appear +at the end of the list of files. +The 'wildignore' option specifies files that are not listed at all. + +More about all of this here: |cmdline-completion| + +============================================================================== +*20.4* Command line history + +In chapter 3 we briefly mentioned the history. The basics are that you can +use the <Up> key to recall an older command line. <Down> then takes you back +to newer commands. + +There are actually four histories. The ones we will mention here are for ":" +commands and for "/" and "?" search commands. The "/" and "?" commands share +the same history, because they are both search commands. The two other +histories are for expressions and input lines for the input() function. +|cmdline-history| + +Suppose you have done a ":set" command, typed ten more colon commands and then +want to repeat that ":set" command again. You could press ":" and then ten +times <Up>. There is a quicker way: > + + :se<Up> + +Vim will now go back to the previous command that started with "se". You have +a good chance that this is the ":set" command you were looking for. At least +you should not have to press <Up> very often (unless ":set" commands is all +you have done). + +The <Up> key will use the text typed so far and compare it with the lines in +the history. Only matching lines will be used. + If you do not find the line you were looking for, use <Down> to go back to +what you typed and correct that. Or use CTRL-U to start all over again. + +To see all the lines in the history: > + + :history + +That's the history of ":" commands. The search history is displayed with this +command: > + + :history / + +CTRL-P will work like <Up>, except that it doesn't matter what you already +typed. Similarly for CTRL-N and <Down>. CTRL-P stands for previous, CTRL-N +for next. + +============================================================================== +*20.5* Command line window + +Typing the text in the command line works different from typing text in Insert +mode. It doesn't allow many commands to change the text. For most commands +that's OK, but sometimes you have to type a complicated command. That's where +the command line window is useful. + +Open the command line window with this command: > + + q: + +Vim now opens a (small) window at the bottom. It contains the command line +history, and an empty line at the end: + + +-------------------------------------+ + |other window | + |~ | + |file.txt=============================| + |:e c | + |:e config.h.in | + |:set path=.,/usr/include,, | + |:set iskeyword=@,48-57,_,192-255 | + |:set is | + |:q | + |: | + |command-line=========================| + | | + +-------------------------------------+ + +You are now in Normal mode. You can use the "hjkl" keys to move around. For +example, move up with "5k" to the ":e config.h.in" line. Type "$h" to go to +the "i" of "in" and type "cwout". Now you have changed the line to: + + :e config.h.out ~ + +Now press <Enter> and this command will be executed. The command line window +will close. + The <Enter> command will execute the line under the cursor. It doesn't +matter whether Vim is in Insert mode or in Normal mode. + Changes in the command line window are lost. They do not result in the +history to be changed. Except that the command you execute will be added to +the end of the history, like with all executed commands. + +The command line window is very useful when you want to have overview of the +history, lookup a similar command, change it a bit and execute it. A search +command can be used to find something. + In the previous example the "?config" search command could have been used +to find the previous command that contains "config". It's a bit strange, +because you are using a command line to search in the command line window. +While typing that search command you can't open another command line window, +there can be only one. + +============================================================================== + +Next chapter: |usr_21.txt| Go away and come back + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/en/usr_21.txt b/en/usr_21.txt new file mode 100644 index 000000000..450d39433 --- /dev/null +++ b/en/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 +<Enter>. This allows you to have a look at the output from the command before +returning to the text you were editing. + The "!" is also used in other places where a program is run. Let's take +a look at an overview: + + :!{program} execute {program} + :r !{program} execute {program} and read its output + :w !{program} execute {program} and send text to its input + :[range]!{program} filter text through {program} + +Notice that the 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 <Enter> (empty cancels): ~ + +Type "2" and press <Enter> 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/en/usr_22.txt b/en/usr_22.txt new file mode 100644 index 000000000..cff8e9db1 --- /dev/null +++ b/en/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: <F1>: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 <F1> 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 <Enter>; 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 <Enter> 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 <Enter> on the first directory "../" moves you one level +higher. Pressing "-" does the same thing, without the need to move to the +"../" item first. + +You can press <F1> 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 + <F1>.............Help.......................................|netrw-help| + <cr>.............Browsing...................................|netrw-cr| + <del>............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| + <c-h>............Edit File/Directory Hiding List............|netrw-ctrl-h| + i................Change Listing Style.......................|netrw-i| + <c-l>............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 <F1> 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) + + <enter> 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/en/usr_23.txt b/en/usr_23.txt new file mode 100644 index 000000000..63cbc612d --- /dev/null +++ b/en/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, <CR>), another to move the paper up (line feed, <LF>). + When computers came out, storage was expensive. Some people decided that +they did not need two characters for end-of-line. The UNIX people decided +they could use <Line Feed> only for end-of-line. The Apple people +standardized on <CR>. The MS-DOS (and Microsoft Windows) folks decided to +keep the old <CR><LF>. + This means that if you try to move a file from one system to another, you +have line-break problems. The Vim editor automatically recognizes the +different file formats and handles things properly behind your back. + The option 'fileformats' contains the various formats that will be tried +when a new file is edited. The following command, for example, tells Vim to +try UNIX format first and MS-DOS format second: > + + :set fileformats=unix,dos + +You will notice the format in the message you get when editing a file. You +don't see anything if you edit a native file format. Thus editing a Unix file +on Unix won't result in a remark. But when you edit a dos file, Vim will +notify you of this: + + "/tmp/test" [dos] 3L, 71C ~ + +For a Mac file you would see "[mac]". + The detected file format is stored in the 'fileformat' option. To see +which format you have, execute the following command: > + + :set fileformat? + +The three names that Vim uses are: + + unix <LF> + dos <CR><LF> + mac <CR> + + +USING THE MAC FORMAT + +On Unix, <LF> is used to break a line. It's not unusual to have a <CR> +character halfway a line. Incidentally, this happens quite often in Vi (and +Vim) scripts. + On the Macintosh, where <CR> is the line break character, it's possible to +have a <LF> character halfway a line. + The result is that it's not possible to be 100% sure whether a file +containing both <CR> and <LF> characters is a Mac or a Unix file. Therefore, +Vim assumes that on Unix you probably won't edit a Mac file, and doesn't check +for this type of file. To check for this format anyway, add "mac" to +'fileformats': > + + :set fileformats+=mac + +Then Vim will take a guess at the file format. Watch out for situations where +Vim guesses wrong. + + +OVERRULING THE FORMAT + +If you use the good old Vi and try to edit an MS-DOS format file, you will +find that each line ends with a ^M character. (^M is <CR>). The automatic +detection avoids this. Suppose you do want to edit the file that way? Then +you need to overrule the format: > + + :edit ++ff=unix file.txt + +The "++" string is an item that tells Vim that an option name follows, which +overrules the default for this single command. "++ff" is used for +'fileformat'. You could also use "++ff=mac" or "++ff=dos". + This doesn't work for any option, only "++ff" and "++enc" are currently +implemented. The full names "++fileformat" and "++encoding" also work. + + +CONVERSION + +You can use the 'fileformat' option to convert from one file format to +another. Suppose, for example, that you have an MS-DOS file named README.TXT +that you want to convert to UNIX format. Start by editing the MS-DOS format +file: > + vim README.TXT + +Vim will recognize this as a dos format file. Now change the file format to +UNIX: > + + :set fileformat=unix + :write + +The file is written in Unix format. + +============================================================================== +*23.2* Files on the internet + +Someone sends you an e-mail message, which refers to a file by its URL. For +example: + + You can find the information here: ~ + ftp://ftp.vim.org/pub/vim/README ~ + +You could start a program to download the file, save it on your local disk and +then start Vim to edit it. + There is a much simpler way. Move the cursor to any character of the URL. +Then use this command: > + + gf + +With a bit of luck, Vim will figure out which program to use for downloading +the file, download it and edit the copy. To open the file in a new window use +CTRL-W f. + If something goes wrong you will get an error message. It's possible that +the URL is wrong, you don't have permission to read it, the network connection +is down, etc. Unfortunately, it's hard to tell the cause of the error. You +might want to try the manual way of downloading the file. + +Accessing files over the internet works with the netrw plugin. Currently URLs +with these formats are recognized: + + ftp:// uses ftp + rcp:// uses rcp + scp:// uses scp + http:// uses wget (reading only) + +Vim doesn't do the communication itself, it relies on the mentioned programs +to be available on your computer. On most Unix systems "ftp" and "rcp" will +be present. "scp" and "wget" might need to be installed. + +Vim detects these URLs for each command that starts editing a new file, also +with ":edit" and ":split", for example. Write commands also work, except for +http://. + +For more information, also about passwords, see |netrw|. + +============================================================================== +*23.3* Encryption + +Some information you prefer to keep to yourself. For example, when writing +a test on a computer that students also use. You don't want clever students +to figure out a way to read the questions before the exam starts. Vim can +encrypt the file for you, which gives you some protection. + To start editing a new file with encryption, use the "-x" argument to start +Vim. Example: > + + vim -x exam.txt + +Vim prompts you for a key used for encrypting and decrypting the file: + + Enter encryption key: ~ + +Carefully type the secret key now. You cannot see the characters you type, +they will be replaced by stars. To avoid the situation that a typing mistake +will cause trouble, Vim asks you to enter the key again: + + Enter same key again: ~ + +You can now edit this file normally and put in all your secrets. When you +finish editing the file and tell Vim to exit, the file is encrypted and +written. + When you edit the file with Vim, it will ask you to enter the same key +again. You don't need to use the "-x" argument. You can also use the normal +":edit" command. Vim adds a magic string to the file by which it recognizes +that the file was encrypted. + If you try to view this file using another program, all you get is garbage. +Also, if you edit the file with Vim and enter the wrong key, you get garbage. +Vim does not have a mechanism to check if the key is the right one (this makes +it much harder to break the key). + + +SWITCHING ENCRYPTION ON AND OFF + +To disable the encryption of a file, set the 'key' option to an empty string: +> + :set key= + +The next time you write the file this will be done without encryption. + Setting the 'key' option to enable encryption is not a good idea, because +the password appears in the clear. Anyone shoulder-surfing can read your +password. + To avoid this problem, the ":X" command was created. It asks you for an +encryption key, just like the "-x" argument did: > + + :X + Enter encryption key: ****** + Enter same key again: ****** + + +LIMITS ON ENCRYPTION + +The encryption algorithm used by Vim is weak. It is good enough to keep out +the casual prowler, but not good enough to keep out a cryptology expert with +lots of time on his hands. Also you should be aware that the swap file is not +encrypted; so while you are editing, people with superuser privileges can read +the unencrypted text from this file. + One way to avoid letting people read your swap file is to avoid using one. +If the -n argument is supplied on the command line, no swap file is used +(instead, Vim puts everything in memory). For example, to edit the encrypted +file "file.txt" without a swap file use the following command: > + + vim -x -n file.txt + +When already editing a file, the swapfile can be disabled with: > + + :setlocal noswapfile + +Since there is no swapfile, recovery will be impossible. Save the file a bit +more often to avoid the risk of losing your changes. + +While the file is in memory, it is in plain text. Anyone with privilege can +look in the editor's memory and discover the contents of the file. + If you use a viminfo file, be aware that the contents of text registers are +written out in the clear as well. + If you really want to secure the contents of a file, edit it only on a +portable computer not connected to a network, use good encryption tools, and +keep the computer locked up in a big safe when not in use. + +============================================================================== +*23.4* Binary files + +You can edit binary files with Vim. Vim wasn't really made for this, thus +there are a few restrictions. But you can read a file, change a character and +write it back, with the result that only that one character was changed and +the file is identical otherwise. + To make sure that Vim does not use its clever tricks in the wrong way, add +the "-b" argument when starting Vim: > + + vim -b datafile + +This sets the 'binary' option. The effect of this is that unexpected side +effects are turned off. For example, 'textwidth' is set to zero, to avoid +automatic formatting of lines. And files are always read in Unix file format. + +Binary mode can be used to change a message in a program. Be careful not to +insert or delete any characters, it would stop the program from working. Use +"R" to enter replace mode. + +Many characters in the file will be unprintable. To see them in Hex format: > + + :set display=uhex + +Otherwise, the "ga" command can be used to see the value of the character +under the cursor. The output, when the cursor is on an <Esc>, looks like +this: + + <^[> 27, Hex 1b, Octal 033 ~ + +There might not be many line breaks in the file. To get some overview switch +the 'wrap' option off: > + + :set nowrap + + +BYTE POSITION + +To see on which byte you are in the file use this command: > + + g CTRL-G + +The output is verbose: + + Col 9-16 of 9-16; Line 277 of 330; Word 1806 of 2058; Byte 10580 of 12206 ~ + +The last two numbers are the byte position in the file and the total number of +bytes. This takes into account how 'fileformat' changes the number of bytes +that a line break uses. + To move to a specific byte in the file, use the "go" command. For +example, to move to byte 2345: > + + 2345go + + +USING XXD + +A real binary editor shows the text in two ways: as it is and in hex format. +You can do this in Vim by first converting the file with the "xxd" program. +This comes with Vim. + First edit the file in binary mode: > + + vim -b datafile + +Now convert the file to a hex dump with xxd: > + + :%!xxd + +The text will look like this: + + 0000000: 1f8b 0808 39d7 173b 0203 7474 002b 4e49 ....9..;..tt.+NI ~ + 0000010: 4b2c 8660 eb9c ecac c462 eb94 345e 2e30 K,.`.....b..4^.0 ~ + 0000020: 373b 2731 0b22 0ca6 c1a2 d669 1035 39d9 7;'1.".....i.59. ~ + +You can now view and edit the text as you like. Vim treats the information as +ordinary text. Changing the hex does not cause the printable character to be +changed, or the other way around. + Finally convert it back with: +> + :%!xxd -r + +Only changes in the hex part are used. Changes in the printable text part on +the right are ignored. + +See the manual page of xxd for more information. + +============================================================================== +*23.5* Compressed files + +This is easy: You can edit a compressed file just like any other file. The +"gzip" plugin takes care of decompressing the file when you edit it. And +compressing it again when you write it. + These compression methods are currently supported: + + .Z compress + .gz gzip + .bz2 bzip2 + +Vim uses the mentioned programs to do the actual compression and +decompression. You might need to install the programs first. + +============================================================================== + +Next chapter: |usr_24.txt| Inserting quickly + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/en/usr_24.txt b/en/usr_24.txt new file mode 100644 index 000000000..46a22c683 --- /dev/null +++ b/en/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 <BS> key was already mentioned. It deletes the character just before the +cursor. The <Del> key does the same for the character under (after) the +cursor. + When you typed a whole word wrong, use CTRL-W: + + The horse had fallen to the sky ~ + CTRL-W + The horse had fallen to the ~ + +If you really messed up a line and want to start over, use CTRL-U to delete +it. This keeps the text after the cursor and the indent. Only the text from +the first non-blank to the cursor is deleted. With the cursor on the "f" of +"fallen" in the next line pressing CTRL-U does this: + + The horse had fallen to the ~ + CTRL-U + fallen to the ~ + +When you spot a mistake a few words back, you need to move the cursor there to +correct it. For example, you typed this: + + The horse had follen to the ground ~ + +You need to change "follen" to "fallen". With the cursor at the end, you +would type this to correct it: > + + <Esc>4blraA + +< get out of Insert mode <Esc> + four words back 4b + move on top of the "o" l + replace with "a" ra + restart Insert mode A + +Another way to do this: > + + <C-Left><C-Left><C-Left><C-Left><Right><Del>a<End> + +< four words back <C-Left><C-Left><C-Left><C-Left> + move on top of the "o" <Right> + delete the "o" <Del> + insert an "a" a + go to end of the line <End> + +This uses special keys to move around, while remaining in Insert mode. This +resembles what you would do in a modeless editor. It's easier to remember, +but takes more time (you have to move your hand from the letters to the cursor +keys, and the <End> key is hard to press without looking at the keyboard). + These special keys are most useful when writing a mapping that doesn't +leave Insert mode. The extra typing doesn't matter then. + An overview of the keys you can use in Insert mode: + + <C-Home> to start of the file + <PageUp> a whole screenful up + <Home> to start of line + <S-Left> one word left + <C-Left> one word left + <S-Right> one word right + <C-Right> one word right + <End> to end of the line + <PageDown> a whole screenful down + <C-End> to end of the file + +There are a few more, see |ins-special-special|. + +============================================================================== +*24.2* Showing matches + +When you type a ) it would be nice to see with which ( it matches. To make +Vim do that use this command: > + + :set showmatch + +When you now type a text like "(example)", as soon as you type the ) Vim will +briefly move the cursor to the matching (, keep it there for half a second, +and move back to where you were typing. + In case there is 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"<Enter> to finish the line: + + + #include "file.h" ~ + #include "main.h" ~ + /* Main program begins */ ~ + +The CTRL-@ command does a CTRL-A and then exits Insert mode. That's a quick +way of doing exactly the same insertion again. + +============================================================================== +*24.5* Copying from another line + +The CTRL-Y command inserts the character above the cursor. This is useful +when you are duplicating a previous line. For example, you have this line of +C code: + + b_array[i]->s_next = a_array[i]->s_next; ~ + +Now you need to type the same line, but with "s_prev" instead of "s_next". +Start the new line, and press CTRL-Y 14 times, until you are at the "n" of +"next": + + b_array[i]->s_next = a_array[i]->s_next; ~ + b_array[i]->s_ ~ + +Now you type "prev": + + b_array[i]->s_next = a_array[i]->s_next; ~ + b_array[i]->s_prev ~ + +Continue pressing CTRL-Y until the following "next": + + b_array[i]->s_next = a_array[i]->s_next; ~ + b_array[i]->s_prev = a_array[i]->s_ ~ + +Now type "prev;" to finish it off. + +The CTRL-E command acts like CTRL-Y except it inserts the character below the +cursor. + +============================================================================== +*24.6* Inserting a register + +The command CTRL-R {register} inserts the contents of the register. This is +useful to avoid having to type a long word. For example, you need to type +this: + + r = VeryLongFunction(a) + VeryLongFunction(b) + VeryLongFunction(c) ~ + +The function name is defined in a different file. Edit that file and move the +cursor on top of the function name there, and yank it into register v: > + + "vyiw + +"v is the register specification, "yiw" is yank-inner-word. Now edit the file +where the new line is to be inserted, and type the first letters: + + r = ~ + +Now use CTRL-R v to insert the function name: + + r = VeryLongFunction ~ + +You continue to type the characters in between the function name, and use +CTRL-R v two times more. + You could have done the same with completion. Using a register is useful +when there are many words that start with the same characters. + +If the register contains characters such as <BS> or other special characters, +they are interpreted as if they had been typed from the keyboard. If you do +not want this to happen (you really want the <BS> to be inserted in the text), +use the command CTRL-R CTRL-R {register}. + +============================================================================== +*24.7* Abbreviations + +An abbreviation is a short word that takes the place of a long one. For +example, "ad" stands for "advertisement". Vim enables you to type an +abbreviation and then will automatically expand it for you. + To tell Vim to expand "ad" into "advertisement" every time you insert it, +use the following command: > + + :iabbrev ad advertisement + +Now, when you type "ad", the whole word "advertisement" will be inserted into +the text. This is triggered by typing a character that can't be part of a +word, for example a space: + + What Is Entered What You See + I saw the a I saw the a ~ + I saw the ad I saw the ad ~ + I saw the ad<Space> I saw the advertisement<Space> ~ + +The expansion doesn't happen when typing just "ad". That allows you to type a +word like "add", which will not get expanded. Only whole words are checked +for abbreviations. + + +ABBREVIATING SEVERAL WORDS + +It is possible to define an abbreviation that results in multiple words. For +example, to define "JB" as "Jack Benny", use the following command: > + + :iabbrev JB Jack Benny + +As a programmer, I use two rather unusual abbreviations: > + + :iabbrev #b /**************************************** + :iabbrev #e <Space>****************************************/ + +These are used for creating boxed comments. The comment starts with #b, which +draws the top line. I then type the comment text and use #e to draw the +bottom line. + Notice that the #e abbreviation begins with a space. In other words, the +first two characters are space-star. Usually Vim ignores spaces between the +abbreviation and the expansion. To avoid that problem, I spell space as seven +characters: <, S, p, a, c, e, >. + + Note: + ":iabbrev" is a long word to type. ":iab" works just as well. + That's abbreviating the abbreviate command! + + +FIXING TYPING MISTAKES + +It's very common to make the same typing mistake every time. For example, +typing "teh" instead of "the". You can fix this with an abbreviation: > + + :abbreviate teh the + +You can add a whole list of these. Add one each time you discover a common +mistake. + + +LISTING ABBREVIATIONS + +The ":abbreviate" command lists the abbreviations: + + :abbreviate + i #e ****************************************/ + i #b /**************************************** + i JB Jack Benny + i ad advertisement + ! teh the + +The "i" in the first column indicates Insert mode. These abbreviations are +only active in Insert mode. Other possible characters are: + + c Command-line mode :cabbrev + ! both Insert and Command-line mode :abbreviate + +Since abbreviations are not often useful in Command-line mode, you will mostly +use the ":iabbrev" command. That avoids, for example, that "ad" gets expanded +when typing a command like: > + + :edit ad + + +DELETING ABBREVIATIONS + +To get rid of an abbreviation, use the ":unabbreviate" command. Suppose you +have the following abbreviation: > + + :abbreviate @f fresh + +You can remove it with this command: > + + :unabbreviate @f + +While you type this, you will notice that @f is expanded to "fresh". Don't +worry about this, Vim understands it anyway (except when you have an +abbreviation for "fresh", but that's very unlikely). + To remove all the abbreviations: > + + :abclear + +":unabbreviate" and ":abclear" also come in the variants for Insert mode +(":iunabbreviate and ":iabclear") and Command-line mode (":cunabbreviate" and +":cabclear"). + + +REMAPPING ABBREVIATIONS + +There is one thing to watch out for when defining an abbreviation: The +resulting string should not be mapped. For example: > + + :abbreviate @a adder + :imap dd disk-door + +When you now type @a, you will get "adisk-doorer". That's not what you want. +To avoid this, use the ":noreabbrev" command. It does the same as +":abbreviate", but avoids that the resulting string is used for mappings: > + + :noreabbrev @a adder + +Fortunately, it's unlikely that the result of an abbreviation is mapped. + +============================================================================== +*24.8* Entering special characters + +The CTRL-V command is used to insert the next character literally. In other +words, any special meaning the character has, it will be ignored. For +example: > + + CTRL-V <Esc> + +Inserts an escape character. Thus you don't leave Insert mode. (Don't type +the space after CTRL-V, it's only to make this easier to read). + + Note: + On MS-Windows CTRL-V is used to paste text. Use CTRL-Q instead of + CTRL-V. On Unix, on the other hand, CTRL-Q does not work on some + terminals, because it has a special meaning. + +You can also use the command CTRL-V {digits} to insert a character with the +decimal number {digits}. For example, the character number 127 is the <Del> +character (but not necessarily the <Del> key!). To insert <Del> type: > + + CTRL-V 127 + +You can enter characters up to 255 this way. When you type fewer than two +digits, a non-digit will terminate the command. To avoid the need of typing a +non-digit, prepend one or two zeros to make three digits. + All the next commands insert a <Tab> and then a dot: + + CTRL-V 9. + CTRL-V 09. + CTRL-V 009. + +To enter a character in hexadecimal, use an "x" after the CTRL-V: > + + CTRL-V x7f + +This also goes up to character 255 (CTRL-V xff). You can use "o" to type a +character as an octal number and two more methods allow you to type up to +a 16 bit and a 32 bit number (e.g., for a Unicode character): > + + CTRL-V o123 + CTRL-V u1234 + CTRL-V U12345678 + +============================================================================== +*24.9* Digraphs + +Some characters are not on the keyboard. For example, the copyright character +(). To type these characters in Vim, you use digraphs, where two characters +represent one. To enter a , for example, you press three keys: > + + CTRL-K Co + +To find out what digraphs are available, use the following command: > + + :digraphs + +Vim will display the digraph table. Here are three lines of it: + + AC ~_ 159 NS | 160 !I 161 Ct 162 Pd 163 Cu 164 Ye 165 ~ + BB 166 SE 167 ': 168 Co 169 -a 170 << 171 NO 172 ~ + -- 173 Rg 174 'm 175 DG 176 +- 177 2S 178 3S 179 ~ + +This shows, for example, that the digraph you get by typing CTRL-K Pd is the +character (). This is character number 163 (decimal). + Pd is short for Pound. Most digraphs are selected to give you a hint about +the character they will produce. If you look through the list you will +understand the logic. + You can exchange the first and second character, if there is no digraph for +that combination. Thus CTRL-K dP also works. Since there is no digraph for +"dP" Vim will also search for a "Pd" digraph. + + Note: + The digraphs depend on the character set that Vim assumes you are + using. On MS-DOS they are different from MS-Windows. Always use + ":digraphs" to find out which digraphs are currently available. + +You can define your own digraphs. Example: > + + :digraph a" + +This defines that CTRL-K a" inserts an character. You can also specify the +character with a decimal number. This defines the same digraph: > + + :digraph a" 228 + +More information about digraphs here: |digraphs| + Another way to insert special characters is with a keymap. More about that +here: |45.5| + +============================================================================== +*24.10* Normal mode commands + +Insert mode offers a limited number of commands. In Normal mode you have many +more. When you want to use one, you usually leave Insert mode with <Esc>, +execute the Normal mode command, and re-enter Insert mode with "i" or "a". + There is a quicker way. With CTRL-O {command} you can execute any Normal +mode command from Insert mode. For example, to delete from the cursor to the +end of the line: > + + CTRL-O D + +You can execute only one Normal mode command this way. But you can specify a +register or a count. A more complicated example: > + + CTRL-O "g3dw + +This deletes up to the third word into register g. + +============================================================================== + +Next chapter: |usr_25.txt| Editing formatted text + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/en/usr_25.txt b/en/usr_25.txt new file mode 100644 index 000000000..23d76a8b0 --- /dev/null +++ b/en/usr_25.txt @@ -0,0 +1,578 @@ +*usr_25.txt* For Vim version 7.4. Last change: 2014 Oct 29 + + 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 <Enter> 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, <Enter>, 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 <Enter> 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 <Tab> you still get 8 spaces worth of indent. To change this, +set the 'softtabstop' option: > + + :set softtabstop=4 + +This will make the <Tab> key insert 4 spaces worth of indent. If there are +already four spaces, a <Tab> 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 <Up> gk + :map <Down> gj + + +TURNING A PARAGRAPH INTO ONE LINE *edit-paragraph-join* + +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/en/usr_26.txt b/en/usr_26.txt new file mode 100644 index 000000000..cc2395962 --- /dev/null +++ b/en/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_cnt\>/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 "\<x_cnt\>". 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 <Enter>. 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/en/usr_27.txt b/en/usr_27.txt new file mode 100644 index 000000000..fb096593f --- /dev/null +++ b/en/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 <Esc> + \t <Tab> + \r <CR> + \b <BS> + +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 [ ] (<Tab> and <Space>) + \S non-white characters [^ ] (not <Tab> and <Space>) + \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\@<!\h\w*\w\@! +< + This checks if "\w" does not match before or after the identifier. + See |/\@<!| and |/\@!|. + +============================================================================== + +Next chapter: |usr_28.txt| Folding + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/en/usr_28.txt b/en/usr_28.txt new file mode 100644 index 000000000..46db1b90a --- /dev/null +++ b/en/usr_28.txt @@ -0,0 +1,426 @@ +*usr_28.txt* For Vim version 7.4. Last change: 2008 Jun 14 + + VIM USER MANUAL - by Bram Moolenaar + + Folding + + +Structured text can be separated in sections. And sections in sub-sections. +Folding allows you to display a section as one line, providing an overview. +This chapter explains the different ways this can be done. + +|28.1| What is folding? +|28.2| Manual folding +|28.3| Working with folds +|28.4| Saving and restoring folds +|28.5| Folding by indent +|28.6| Folding with markers +|28.7| Folding by syntax +|28.8| Folding by expression +|28.9| Folding unchanged lines +|28.10| Which fold method to use? + + Next chapter: |usr_29.txt| Moving through programs + Previous chapter: |usr_27.txt| Search commands and patterns +Table of contents: |usr_toc.txt| + +============================================================================== +*28.1* What is folding? + +Folding is used to show a range of lines in the buffer as a single line on the +screen. Like a piece of paper which is folded to make it shorter: + + +------------------------+ + | line 1 | + | line 2 | + | line 3 | + |_______________________ | + \ \ + \________________________\ + / folded lines / + /________________________/ + | line 12 | + | line 13 | + | line 14 | + +------------------------+ + +The text is still in the buffer, unchanged. Only the way lines are displayed +is affected by folding. + +The advantage of folding is that you can get a better overview of the +structure of text, by folding lines of a section and replacing it with a line +that indicates that there is a section. + +============================================================================== +*28.2* Manual folding + +Try it out: Position the cursor in a paragraph and type: > + + 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=<Tab> + +Where <Tab> 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/en/usr_29.txt b/en/usr_29.txt new file mode 100644 index 000000000..dc71e71dd --- /dev/null +++ b/en/usr_29.txt @@ -0,0 +1,614 @@ +*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 (<CR> 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 <Tab>: > + + :tag write_<Tab> + +You will get the first match. If it's not the one you want, press <Tab> 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 <Tab>. 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 <buffer> <CR> 0ye<C-W>w:tag <C-R>"<CR> + +Move the cursor to the line that contains the function you want to go to. +Now press <Enter>. Vim will go to the other window and jump to the selected +function. + + +RELATED ITEMS + +To make case in tag names be ignored, you can set 'ignorecase' while leaving +'tagcase' as "followic", or set 'tagcase' to "ignore". + +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 --- ~ + <io.h> ~ + vim.h --> ~ + <functions.h> ~ + <clib/exec_protos.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: > + + [<Tab> + +You can also use "[ CTRL-I", since CTRL-I is the same as pressing <Tab>. + +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[<Tab> + +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/en/usr_30.txt b/en/usr_30.txt new file mode 100644 index 000000000..b2be51298 --- /dev/null +++ b/en/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 <Enter>, 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, <Enter> 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, <Enter> and the third line. This time +the indent is OK. Then <Enter> 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 <Tab> is eight spaces and you want to use an indent of four spaces, +you can't use a <Tab> character to make your indent. There are two ways to +handle this: + +1. Use a mix of <Tab> and space characters. Since a <Tab> takes the place of + eight spaces, you have fewer characters in your file. Inserting a <Tab> + 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 <Tab> 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 <Tab> key +the cursor moves to the next 4-column boundary: > + + :set softtabstop=4 + +When you start in the first column and press <Tab>, you get 4 spaces inserted +in your text. The second time, Vim takes out the 4 spaces and puts in a <Tab> +(thus taking you to column 8). Thus Vim uses as many <Tab>s as possible, and +then fills up with spaces. + When backspacing it works the other way around. A <BS> will always delete +the amount specified with 'softtabstop'. Then <Tab>s are used as many as +possible and spaces to fill the gap. + The following shows what happens pressing <Tab> a few times, and then using +<BS>. A "." stands for a space and "------->" for a <Tab>. + + type result ~ + <Tab> .... + <Tab><Tab> -------> + <Tab><Tab><Tab> ------->.... + <Tab><Tab><Tab><BS> -------> + <Tab><Tab><Tab><BS><BS> .... + +An alternative is to use the 'smarttab' option. When it's set, Vim uses +'shiftwidth' for a <Tab> typed in the indent of a line, and a real <Tab> when +typed after the first non-blank character. However, <BS> 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 <Tab> key inserts a series of spaces. Thus you +get the same amount of white space as if a <Tab> character was inserted, but +there isn't a real <Tab> character in your file. + The backspace key will delete each space by itself. Thus after typing one +<Tab> you have to press the <BS> 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 <Enter> 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/en/usr_31.txt b/en/usr_31.txt new file mode 100644 index 000000000..550564e10 --- /dev/null +++ b/en/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 <Tab> key and the cursor keys change the choice. + Pressing <Enter> 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 +<Enter>, 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 <Alt> key in combination +with the underlined letter of a menu. For example, <A-w> (<Alt> 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 <Alt> key and press p. + +After the first selection of a menu with the <Alt> key, you can use the cursor +keys to move through the menus. <Right> selects a submenu and <left> closes +it. <Esc> also closes a menu. <Enter> selects a menu item. + +There is a conflict between using the <Alt> key to select menu items, and +using <Alt> key combinations for mappings. The 'winaltkeys' option tells Vim +what it should do with the <Alt> 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 <Alt> keys for the menus. Thus you must use +the mouse for the menus, and all <Alt> keys can be mapped. + The value "yes" means that Vim will use any <Alt> keys for the menus. Some +<Alt> 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/en/usr_32.txt b/en/usr_32.txt new file mode 100644 index 000000000..fd58f2d51 --- /dev/null +++ b/en/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/en/usr_40.txt b/en/usr_40.txt new file mode 100644 index 000000000..9d706481d --- /dev/null +++ b/en/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 <F1>, have no predefined meaning in Vim, these are +good choices to map. Example: > + + :map <F2> GoDate: <Esc>:read !date<CR>kJ + +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 <Esc> 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 <CR> 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 <F2> <CR>Date: <Esc>:read !date<CR>kJ + +It looks a lot like the mapping for <F2> in Normal mode, only the start is +different. The <F2> 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 <F7> so that the command d<F7> deletes a C +program block (text enclosed in curly braces, {}). Similarly y<F7> would yank +the program block into the unnamed register. Therefore, what you need to do +is to define <F7> to select the current program block. You can do this with +the following command: > + + :omap <F7> a{ + +This causes <F7> 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)<CR> ~ + v <F2> :s/^/> /<CR>:noh<CR>`` ~ + n <F2> :.,$s/^/> /<CR>:noh<CR>`` ~ + <xHome> <Home> + <xEnd> <End> + + +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 <Esc> 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 <F2> above could be shortened to: > + + :map <F2> G<F3> + :imap <F2> <Esc><F3> + :map <F3> oDate: <Esc>:read !date<CR>kJ + +For Normal mode <F2> is mapped to go to the last line, and then behave like +<F3> was pressed. In Insert mode <F2> stops Insert mode with <Esc> and then +also uses <F3>. Then <F3> 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/<CR>:wnext<CR>,, + +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 <C-A> /---><CR> + :vunmap <C-A> + +Notice that the five characters "<C-A>" 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 <Bar> (five characters). Example: +> + :map <F8> :write <Bar> !checkin %:S<CR> + +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 <Space> (seven characters): > + + :map <Space> 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 <Space> 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 <script> keyword can be used to make a mapping local to a script. See +|:map-<script>|. + +The <buffer> keyword can be used to make a mapping local to a specific buffer. +See |:map-<buffer>| + +The <unique> keyword can be used to make defining a new mapping fail when it +already exists. Otherwise a new mapping simply overwrites the old one. See +|:map-<unique>|. + +To make a key do nothing, map it to <Nop> (five characters). This will make +the <F7> key do nothing at all: > + + :map <F7> <Nop>| map! <F7> <Nop> + +There must be no space after <Nop>. + +============================================================================== +*40.2* Defining command-line commands + +The Vim editor enables you to define your own commands. You execute these +commands just like any other Command-line mode command. + To define a command, use the ":command" command, as follows: > + + :command DeleteFirst 1delete + +Now when you execute the command ":DeleteFirst" Vim executes ":1delete", which +deletes the first line. + + Note: + User-defined commands must start with a capital letter. You cannot + use ":X", ":Next" and ":Print". The underscore cannot be used! You + can use digits, but this is discouraged. + +To list the user-defined commands, execute the following command: > + + :command + +Just like with the builtin commands, the user defined commands can be +abbreviated. You need to type just enough to distinguish the command from +another. Command line completion can be used to get the full name. + + +NUMBER OF ARGUMENTS + +User-defined commands can take a series of arguments. The number of arguments +must be specified by the -nargs option. For instance, the example +:DeleteFirst command takes no arguments, so you could have defined it as +follows: > + + :command -nargs=0 DeleteFirst 1delete + +However, because zero arguments is the default, you do not need to add +"-nargs=0". The other values of -nargs are as follows: + + -nargs=0 No arguments + -nargs=1 One argument + -nargs=* Any number of arguments + -nargs=? Zero or one argument + -nargs=+ One or more arguments + + +USING THE ARGUMENTS + +Inside the command definition, the arguments are represented by the +<args> keyword. For example: > + + :command -nargs=+ Say :echo "<args>" + +Now when you type > + + :Say Hello World + +Vim echoes "Hello World". However, if you add a double quote, it won't work. +For example: > + + :Say he said "hello" + +To get special characters turned into a string, properly escaped to use as an +expression, use "<q-args>": > + + :command -nargs=+ Say :echo <q-args> + +Now the above ":Say" command will result in this to be executed: > + + :echo "he said \"hello\"" + +The <f-args> keyword contains the same information as the <args> keyword, +except in a format suitable for use as function call arguments. For example: +> + :command -nargs=* DoIt :call AFunction(<f-args>) + :DoIt a b c + +Executes the following command: > + + :call AFunction("a", "b", "c") + + +LINE RANGE + +Some commands take a range as their argument. To tell Vim that you are +defining such a command, you need to specify a -range option. The values for +this option are as follows: + + -range Range is allowed; default is the current line. + -range=% Range is allowed; default is the whole file. + -range={count} Range is allowed; the last number in it is used as a + single number whose default is {count}. + +When a range is specified, the keywords <line1> and <line2> get the values of +the first and last line in the range. For example, the following command +defines the SaveIt command, which writes out the specified range to the file +"save_file": > + + :command -range=% SaveIt :<line1>,<line2>write! save_file + + +OTHER OPTIONS + +Some of the other options and keywords are as follows: + + -count={number} The command can take a count whose default is + {number}. The resulting count can be used + through the <count> keyword. + -bang You can use a !. If present, using <bang> will + result in a !. + -register You can specify a register. (The default is + the unnamed register.) + The register specification is available as + <reg> (a.k.a. <register>). + -complete={type} Type of command-line completion used. See + |:command-completion| for the list of possible + values. + -bar The command can be followed by | and another + command, or " and a comment. + -buffer The command is only available for the current + buffer. + +Finally, you have the <lt> keyword. It stands for the character <. Use this +to escape the special meaning of the <> items mentioned. + + +REDEFINING AND DELETING + +To redefine the same command use the ! argument: > + + :command -nargs=+ Say :echo "<args>" + :command! -nargs=+ Say :echo <q-args> + +To delete a user command use ":delcommand". It takes a single argument, which +is the name of the command. Example: > + + :delcommand SaveIt + +To delete all the user commands: > + + :comclear + +Careful, this can't be undone! + +More details about all this in the reference manual: |user-commands|. + +============================================================================== +*40.3* Autocommands + +An autocommand is a command that is executed automatically in response to some +event, such as a file being read or written or a buffer change. Through the +use of autocommands you can train Vim to edit compressed files, for example. +That is used in the |gzip| plugin. + Autocommands are very powerful. Use them with care and they will help you +avoid typing many commands. Use them carelessly and they will cause a lot of +trouble. + +Suppose you want to replace a datestamp on the end of a file every time it is +written. First you define a function: > + + :function DateInsert() + : $delete + : read !date + :endfunction + +You want this function to be called each time, just before a buffer is written +to a file. This will make that happen: > + + :autocmd BufWritePre * call DateInsert() + +"BufWritePre" is the event for which this autocommand is triggered: Just +before (pre) writing a buffer to a file. The "*" is a pattern to match with +the file name. In this case it matches all files. + With this command enabled, when you do a ":write", Vim checks for any +matching BufWritePre autocommands and executes them, and then it +performs the ":write". + The general form of the :autocmd command is as follows: > + + :autocmd [group] {events} {file_pattern} [nested] {command} + +The [group] name is optional. It is used in managing and calling the commands +(more on this later). The {events} parameter is a list of events (comma +separated) that trigger the command. + {file_pattern} is a filename, usually with wildcards. For example, using +"*.txt" makes the autocommand be used for all files whose name end in ".txt". +The optional [nested] flag allows for nesting of autocommands (see below), and +finally, {command} is the command to be executed. + + +EVENTS + +One of the most useful events is BufReadPost. It is triggered after a new +file is being edited. It is commonly used to set option values. For example, +you know that "*.gsm" files are GNU assembly language. To get the syntax file +right, define this autocommand: > + + :autocmd BufReadPost *.gsm set filetype=asm + +If Vim is able to detect the type of file, it will set the 'filetype' option +for you. This triggers the Filetype event. Use this to do something when a +certain type of file is edited. For example, to load a list of abbreviations +for text files: > + + :autocmd Filetype text source ~/.vim/abbrevs.vim + +When starting to edit a new file, you could make Vim insert a skeleton: > + + :autocmd BufNewFile *.[ch] 0read ~/skeletons/skel.c + +See |autocmd-events| for a complete list of events. + + +PATTERNS + +The {file_pattern} argument can actually be a comma-separated list of file +patterns. For example: "*.c,*.h" matches files ending in ".c" and ".h". + The usual file wildcards can be used. Here is a summary of the most often +used ones: + + * Match any character any number of times + ? Match any character once + [abc] Match the character a, b or c + . Matches a dot + a{b,c} Matches "ab" and "ac" + +When the pattern includes a slash (/) Vim will compare directory names. +Without the slash only the last part of a file name is used. For example, +"*.txt" matches "/home/biep/readme.txt". The pattern "/home/biep/*" would +also match it. But "home/foo/*.txt" wouldn't. + When including a slash, Vim matches the pattern against both the full path +of the file ("/home/biep/readme.txt") and the relative path (e.g., +"biep/readme.txt"). + + Note: + When working on a system that uses a backslash as file separator, such + as MS-Windows, you still use forward slashes in autocommands. This + makes it easier to write the pattern, since a backslash has a special + meaning. It also makes the autocommands portable. + + +DELETING + +To delete an autocommand, use the same command as what it was defined with, +but leave out the {command} at the end and use a !. Example: > + + :autocmd! FileWritePre * + +This will delete all autocommands for the "FileWritePre" event that use the +"*" pattern. + + +LISTING + +To list all the currently defined autocommands, use this: > + + :autocmd + +The list can be very long, especially when filetype detection is used. To +list only part of the commands, specify the group, event and/or pattern. For +example, to list all BufNewFile autocommands: > + + :autocmd BufNewFile + +To list all autocommands for the pattern "*.c": > + + :autocmd * *.c + +Using "*" for the event will list all the events. To list all autocommands +for the cprograms group: > + + :autocmd cprograms + + +GROUPS + +The {group} item, used when defining an autocommand, groups related autocommands +together. This can be used to delete all the autocommands in a certain group, +for example. + When defining several autocommands for a certain group, use the ":augroup" +command. For example, let's define autocommands for C programs: > + + :augroup cprograms + : autocmd BufReadPost *.c,*.h :set sw=4 sts=4 + : autocmd BufReadPost *.cpp :set sw=3 sts=3 + :augroup END + +This will do the same as: > + + :autocmd cprograms BufReadPost *.c,*.h :set sw=4 sts=4 + :autocmd cprograms BufReadPost *.cpp :set sw=3 sts=3 + +To delete all autocommands in the "cprograms" group: > + + :autocmd! cprograms + + +NESTING + +Generally, commands executed as the result of an autocommand event will not +trigger any new events. If you read a file in response to a FileChangedShell +event, it will not trigger the autocommands that would set the syntax, for +example. To make the events triggered, add the "nested" argument: > + + :autocmd FileChangedShell * nested edit + + +EXECUTING AUTOCOMMANDS + +It is possible to trigger an autocommand by pretending an event has occurred. +This is useful to have one autocommand trigger another one. Example: > + + :autocmd BufReadPost *.new execute "doautocmd BufReadPost " . expand("<afile>:r") + +This defines an autocommand that is triggered when a new file has been edited. +The file name must end in ".new". The ":execute" command uses expression +evaluation to form a new command and execute it. When editing the file +"tryout.c.new" the executed command will be: > + + :doautocmd BufReadPost tryout.c + +The expand() function takes the "<afile>" argument, which stands for the file +name the autocommand was executed for, and takes the root of the file name +with ":r". + +":doautocmd" executes on the current buffer. The ":doautoall" command works +like "doautocmd" except it executes on all the buffers. + + +USING NORMAL MODE COMMANDS + +The commands executed by an autocommand are Command-line commands. If you +want to use a Normal mode command, the ":normal" command can be used. +Example: > + + :autocmd BufReadPost *.log normal G + +This will make the cursor jump to the last line of *.log files when you start +to edit it. + Using the ":normal" command is a bit tricky. First of all, make sure its +argument is a complete command, including all the arguments. When you use "i" +to go to Insert mode, there must also be a <Esc> to leave Insert mode again. +If you use a "/" to start a search pattern, there must be a <CR> to execute +it. + The ":normal" command uses all the text after it as commands. Thus there +can be no | and another command following. To work around this, put the +":normal" command inside an ":execute" command. This also makes it possible +to pass unprintable characters in a convenient way. Example: > + + :autocmd BufReadPost *.chg execute "normal ONew entry:\<Esc>" | + \ 1read !date + +This also shows the use of a backslash to break a long command into more +lines. This can be used in Vim scripts (not at the command line). + +When you want the autocommand do something complicated, which involves jumping +around in the file and then returning to the original position, you may want +to restore the view on the file. See |restore-position| for an example. + + +IGNORING EVENTS + +At times, you will not want to trigger an autocommand. The 'eventignore' +option contains a list of events that will be totally ignored. For example, +the following causes events for entering and leaving a window to be ignored: > + + :set eventignore=WinEnter,WinLeave + +To ignore all events, use the following command: > + + :set eventignore=all + +To set it back to the normal behavior, make 'eventignore' empty: > + + :set eventignore= + +============================================================================== + +Next chapter: |usr_41.txt| Write a Vim script + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/en/usr_41.txt b/en/usr_41.txt new file mode 100644 index 000000000..9f2442e9b --- /dev/null +++ b/en/usr_41.txt @@ -0,0 +1,2491 @@ +*usr_41.txt* For Vim version 7.4. Last change: 2016 Jan 28 + + VIM USER MANUAL - by Bram Moolenaar + + Write a Vim script + + +The Vim script language is used for the startup vimrc file, syntax files, and +many other things. This chapter explains the items that can be used in a Vim +script. There are a lot of them, thus this is a long chapter. + +|41.1| Introduction +|41.2| Variables +|41.3| Expressions +|41.4| Conditionals +|41.5| Executing an expression +|41.6| Using functions +|41.7| Defining a function +|41.8| Lists and Dictionaries +|41.9| Exceptions +|41.10| Various remarks +|41.11| Writing a plugin +|41.12| Writing a filetype plugin +|41.13| Writing a compiler plugin +|41.14| Writing a plugin that loads quickly +|41.15| Writing library scripts +|41.16| Distributing Vim scripts + + Next chapter: |usr_42.txt| Add new menus + Previous chapter: |usr_40.txt| Make new commands +Table of contents: |usr_toc.txt| + +============================================================================== +*41.1* Introduction *vim-script-intro* *script* + +Your first experience with Vim scripts is the vimrc file. Vim reads it when +it starts up and executes the commands. You can set options to values you +prefer. And you can use any colon command in it (commands that start with a +":"; these are sometimes referred to as Ex commands or command-line commands). + Syntax files are also Vim scripts. As are files that set options for a +specific file type. A complicated macro can be defined by a separate Vim +script file. You can think of other uses yourself. + +Let's start with a simple example: > + + :let i = 1 + :while i < 5 + : echo "count is" i + : let i += 1 + :endwhile +< + Note: + The ":" characters are not really needed here. You only need to use + them when you type a command. In a Vim script file they can be left + out. We will use them here anyway to make clear these are colon + commands and make them stand out from Normal mode commands. + Note: + You can try out the examples by yanking the lines from the text here + and executing them with :@" + +The output of the example code is: + + count is 1 ~ + count is 2 ~ + count is 3 ~ + count is 4 ~ + +In the first line the ":let" command assigns a value to a variable. The +generic form is: > + + :let {variable} = {expression} + +In this case the variable name is "i" and the expression is a simple value, +the number one. + The ":while" command starts a loop. The generic form is: > + + :while {condition} + : {statements} + :endwhile + +The statements until the matching ":endwhile" are executed for as long as the +condition is true. The condition used here is the expression "i < 5". This +is true when the variable i is smaller than five. + Note: + If you happen to write a while loop that keeps on running, you can + interrupt it by pressing CTRL-C (CTRL-Break on MS-Windows). + +The ":echo" command prints its arguments. In this case the string "count is" +and the value of the variable i. Since i is one, this will print: + + count is 1 ~ + +Then there is the ":let i += 1" command. This does the same thing as +":let i = i + 1". This adds one to the variable i and assigns the new value +to the same variable. + +The example was given to explain the commands, but would you really want to +make such a loop it can be written much more compact: > + + :for i in range(1, 4) + : echo "count is" i + :endfor + +We won't explain how |:for| and |range()| work until later. Follow the links +if you are impatient. + + +THREE KINDS OF NUMBERS + +Numbers can be decimal, hexadecimal or octal. A hexadecimal number starts +with "0x" or "0X". For example "0x1f" is decimal 31. An octal number starts +with a zero. "017" is decimal 15. Careful: don't put a zero before a decimal +number, it will be interpreted as an octal number! + The ":echo" command always prints decimal numbers. Example: > + + :echo 0x7f 036 +< 127 30 ~ + +A number is made negative with a minus sign. This also works for hexadecimal +and octal numbers. A minus sign is also used for subtraction. Compare this +with the previous example: > + + :echo 0x7f -036 +< 97 ~ + +White space in an expression is ignored. However, it's recommended to use it +for separating items, to make the expression easier to read. For example, to +avoid the confusion with a negative number above, put a space between the +minus sign and the following number: > + + :echo 0x7f - 036 + +============================================================================== +*41.2* Variables + +A variable name consists of ASCII letters, digits and the underscore. It +cannot start with a digit. Valid variable names are: + + counter + _aap3 + very_long_variable_name_with_underscores + FuncLength + LENGTH + +Invalid names are "foo+bar" and "6var". + These variables are global. To see a list of currently defined variables +use this command: > + + :let + +You can use global variables everywhere. This also means that when the +variable "count" is used in one script file, it might also be used in another +file. This leads to confusion at least, and real problems at worst. To avoid +this, you can use a variable local to a script file by prepending "s:". For +example, one script contains this code: > + + :let s:count = 1 + :while s:count < 5 + : source other.vim + : let s:count += 1 + :endwhile + +Since "s:count" is local to this script, you can be sure that sourcing the +"other.vim" script will not change this variable. If "other.vim" also uses an +"s:count" variable, it will be a different copy, local to that script. More +about script-local variables here: |script-variable|. + +There are more kinds of variables, see |internal-variables|. The most often +used ones are: + + b:name variable local to a buffer + w:name variable local to a window + g:name global variable (also in a function) + v:name variable predefined by Vim + + +DELETING VARIABLES + +Variables take up memory and show up in the output of the ":let" command. To +delete a variable use the ":unlet" command. Example: > + + :unlet s:count + +This deletes the script-local variable "s:count" to free up the memory it +uses. If you are not sure if the variable exists, and don't want an error +message when it doesn't, append !: > + + :unlet! s:count + +When a script finishes, the local variables used there will not be +automatically freed. The next time the script executes, it can still use the +old value. Example: > + + :if !exists("s:call_count") + : let s:call_count = 0 + :endif + :let s:call_count = s:call_count + 1 + :echo "called" s:call_count "times" + +The "exists()" function checks if a variable has already been defined. Its +argument is the name of the variable you want to check. Not the variable +itself! If you would do this: > + + :if !exists(s:call_count) + +Then the value of s:call_count will be used as the name of the variable that +exists() checks. That's not what you want. + The exclamation mark ! negates a value. When the value was true, it +becomes false. When it was false, it becomes true. You can read it as "not". +Thus "if !exists()" can be read as "if not exists()". + What Vim calls true is anything that is not zero. Zero is false. + Note: + Vim automatically converts a string to a number when it is looking for + a number. When using a string that doesn't start with a digit the + resulting number is zero. Thus look out for this: > + :if "true" +< The "true" will be interpreted as a zero, thus as false! + + +STRING VARIABLES AND CONSTANTS + +So far only numbers were used for the variable value. Strings can be used as +well. Numbers and strings are the basic types of variables that Vim supports. +The type is dynamic, it is set each time when assigning a value to the +variable with ":let". More about types in |41.8|. + To assign a string value to a variable, you need to use a string constant. +There are two types of these. First the string in double quotes: > + + :let name = "peter" + :echo name +< peter ~ + +If you want to include a double quote inside the string, put a backslash in +front of it: > + + :let name = "\"peter\"" + :echo name +< "peter" ~ + +To avoid the need for a backslash, you can use a string in single quotes: > + + :let name = '"peter"' + :echo name +< "peter" ~ + +Inside a single-quote string all the characters are as they are. Only the +single quote itself is special: you need to use two to get one. A backslash +is taken literally, thus you can't use it to change the meaning of the +character after it. + In double-quote strings it is possible to use special characters. Here are +a few useful ones: + + \t <Tab> + \n <NL>, line break + \r <CR>, <Enter> + \e <Esc> + \b <BS>, backspace + \" " + \\ \, backslash + \<Esc> <Esc> + \<C-W> CTRL-W + +The last two are just examples. The "\<name>" form can be used to include +the special key "name". + See |expr-quote| for the full list of special items in a string. + +============================================================================== +*41.3* Expressions + +Vim has a rich, yet simple way to handle expressions. You can read the +definition here: |expression-syntax|. Here we will show the most common +items. + The numbers, strings and variables mentioned above are expressions by +themselves. Thus everywhere an expression is expected, you can use a number, +string or variable. Other basic items in an expression are: + + $NAME environment variable + &name option + @r register + +Examples: > + + :echo "The value of 'tabstop' is" &ts + :echo "Your home directory is" $HOME + :if @a > 5 + +The &name form can be used to save an option value, set it to a new value, +do something and restore the old value. Example: > + + :let save_ic = &ic + :set noic + :/The Start/,$delete + :let &ic = save_ic + +This makes sure the "The Start" pattern is used with the 'ignorecase' option +off. Still, it keeps the value that the user had set. (Another way to do +this would be to add "\C" to the pattern, see |/\C|.) + + +MATHEMATICS + +It becomes more interesting if we combine these basic items. Let's start with +mathematics on numbers: + + a + b add + a - b subtract + a * b multiply + a / b divide + a % b modulo + +The usual precedence is used. Example: > + + :echo 10 + 5 * 2 +< 20 ~ + +Grouping is done with parentheses. No surprises here. Example: > + + :echo (10 + 5) * 2 +< 30 ~ + +Strings can be concatenated with ".". Example: > + + :echo "foo" . "bar" +< foobar ~ + +When the ":echo" command gets multiple arguments, it separates them with a +space. In the example the argument is a single expression, thus no space is +inserted. + +Borrowed from the C language is the conditional expression: + + a ? b : c + +If "a" evaluates to true "b" is used, otherwise "c" is used. Example: > + + :let i = 4 + :echo i > 5 ? "i is big" : "i is small" +< i is small ~ + +The three parts of the constructs are always evaluated first, thus you could +see it work as: + + (a) ? (b) : (c) + +============================================================================== +*41.4* Conditionals + +The ":if" commands executes the following statements, until the matching +":endif", only when a condition is met. The generic form is: + + :if {condition} + {statements} + :endif + +Only when the expression {condition} evaluates to true (non-zero) will the +{statements} be executed. These must still be valid commands. If they +contain garbage, Vim won't be able to find the ":endif". + You can also use ":else". The generic form for this is: + + :if {condition} + {statements} + :else + {statements} + :endif + +The second {statements} is only executed if the first one isn't. + Finally, there is ":elseif": + + :if {condition} + {statements} + :elseif {condition} + {statements} + :endif + +This works just like using ":else" and then "if", but without the need for an +extra ":endif". + A useful example for your vimrc file is checking the 'term' option and +doing something depending upon its value: > + + :if &term == "xterm" + : " Do stuff for xterm + :elseif &term == "vt100" + : " Do stuff for a vt100 terminal + :else + : " Do something for other terminals + :endif + + +LOGIC OPERATIONS + +We already used some of them in the examples. These are the most often used +ones: + + a == b equal to + a != b not equal to + a > b greater than + a >= b greater than or equal to + a < b less than + a <= b less than or equal to + +The result is one if the condition is met and zero otherwise. An example: > + + :if v:version >= 700 + : echo "congratulations" + :else + : echo "you are using an old version, upgrade!" + :endif + +Here "v:version" is a variable defined by Vim, which has the value of the Vim +version. 600 is for version 6.0. Version 6.1 has the value 601. This is +very useful to write a script that works with multiple versions of Vim. +|v:version| + +The logic operators work both for numbers and strings. When comparing two +strings, the mathematical difference is used. This compares byte values, +which may not be right for some languages. + When comparing a string with a number, the string is first converted to a +number. This is a bit tricky, because when a string doesn't look like a +number, the number zero is used. Example: > + + :if 0 == "one" + : echo "yes" + :endif + +This will echo "yes", because "one" doesn't look like a number, thus it is +converted to the number zero. + +For strings there are two more items: + + a =~ b matches with + a !~ b does not match with + +The left item "a" is used as a string. The right item "b" is used as a +pattern, like what's used for searching. Example: > + + :if str =~ " " + : echo "str contains a space" + :endif + :if str !~ '\.$' + : echo "str does not end in a full stop" + :endif + +Notice the use of a single-quote string for the pattern. This is useful, +because backslashes would need to be doubled in a double-quote string and +patterns tend to contain many backslashes. + +The 'ignorecase' option is used when comparing strings. When you don't want +that, append "#" to match case and "?" to ignore case. Thus "==?" compares +two strings to be equal while ignoring case. And "!~#" checks if a pattern +doesn't match, also checking the case of letters. For the full table see +|expr-==|. + + +MORE LOOPING + +The ":while" command was already mentioned. Two more statements can be used +in between the ":while" and the ":endwhile": + + :continue Jump back to the start of the while loop; the + loop continues. + :break Jump forward to the ":endwhile"; the loop is + discontinued. + +Example: > + + :while counter < 40 + : call do_something() + : if skip_flag + : continue + : endif + : if finished_flag + : break + : endif + : sleep 50m + :endwhile + +The ":sleep" command makes Vim take a nap. The "50m" specifies fifty +milliseconds. Another example is ":sleep 4", which sleeps for four seconds. + +Even more looping can be done with the ":for" command, see below in |41.8|. + +============================================================================== +*41.5* Executing an expression + +So far the commands in the script were executed by Vim directly. The +":execute" command allows executing the result of an expression. This is a +very powerful way to build commands and execute them. + An example is to jump to a tag, which is contained in a variable: > + + :execute "tag " . tag_name + +The "." is used to concatenate the string "tag " with the value of variable +"tag_name". Suppose "tag_name" has the value "get_cmd", then the command that +will be executed is: > + + :tag get_cmd + +The ":execute" command can only execute colon commands. The ":normal" command +executes Normal mode commands. However, its argument is not an expression but +the literal command characters. Example: > + + :normal gg=G + +This jumps to the first line and formats all lines with the "=" operator. + To make ":normal" work with an expression, combine ":execute" with it. +Example: > + + :execute "normal " . normal_commands + +The variable "normal_commands" must contain the Normal mode commands. + Make sure that the argument for ":normal" is a complete command. Otherwise +Vim will run into the end of the argument and abort the command. For example, +if you start Insert mode, you must leave Insert mode as well. This works: > + + :execute "normal Inew text \<Esc>" + +This inserts "new text " in the current line. Notice the use of the special +key "\<Esc>". This avoids having to enter a real <Esc> character in your +script. + +If you don't want to execute a string but evaluate it to get its expression +value, you can use the eval() function: > + + :let optname = "path" + :let optval = eval('&' . optname) + +A "&" character is prepended to "path", thus the argument to eval() is +"&path". The result will then be the value of the 'path' option. + The same thing can be done with: > + :exe 'let optval = &' . optname + +============================================================================== +*41.6* Using functions + +Vim defines many functions and provides a large amount of functionality that +way. A few examples will be given in this section. You can find the whole +list here: |functions|. + +A function is called with the ":call" command. The parameters are passed in +between parentheses separated by commas. Example: > + + :call search("Date: ", "W") + +This calls the search() function, with arguments "Date: " and "W". The +search() function uses its first argument as a search pattern and the second +one as flags. The "W" flag means the search doesn't wrap around the end of +the file. + +A function can be called in an expression. Example: > + + :let line = getline(".") + :let repl = substitute(line, '\a', "*", "g") + :call setline(".", repl) + +The getline() function obtains a line from the current buffer. Its argument +is a specification of the line number. In this case "." is used, which means +the line where the cursor is. + The substitute() function does something similar to the ":substitute" +command. The first argument is the string on which to perform the +substitution. The second argument is the pattern, the third the replacement +string. Finally, the last arguments are the flags. + The setline() function sets the line, specified by the first argument, to a +new string, the second argument. In this example the line under the cursor is +replaced with the result of the substitute(). Thus the effect of the three +statements is equal to: > + + :substitute/\a/*/g + +Using the functions becomes more interesting when you do more work before and +after the substitute() call. + + +FUNCTIONS *function-list* + +There are many functions. We will mention them here, grouped by what they are +used for. You can find an alphabetical list here: |functions|. Use CTRL-] on +the function name to jump to detailed help on it. + +String manipulation: *string-functions* + nr2char() get a character by its ASCII value + char2nr() get ASCII value of a character + str2nr() convert a string to a Number + str2float() convert a string to a Float + printf() format a string according to % items + escape() escape characters in a string with a '\' + shellescape() escape a string for use with a shell command + fnameescape() escape a file name for use with a Vim command + tr() translate characters from one set to another + strtrans() translate a string to make it printable + tolower() turn a string to lowercase + toupper() turn a string to uppercase + match() position where a pattern matches in a string + matchend() position where a pattern match ends in a string + matchstr() match of a pattern in a string + matchlist() like matchstr() and also return submatches + stridx() first index of a short string in a long string + strridx() last index of a short string in a long string + strlen() length of a string in bytes + strchars() length of a string in characters + strwidth() size of string when displayed + strdisplaywidth() size of string when displayed, deals with tabs + substitute() substitute a pattern match with a string + submatch() get a specific match in ":s" and substitute() + strpart() get part of a string + expand() expand special keywords + iconv() convert text from one encoding to another + byteidx() byte index of a character in a string + byteidxcomp() like byteidx() but count composing characters + repeat() repeat a string multiple times + eval() evaluate a string expression + +List manipulation: *list-functions* + get() get an item without error for wrong index + len() number of items in a List + empty() check if List is empty + insert() insert an item somewhere in a List + add() append an item to a List + extend() append a List to a List + remove() remove one or more items from a List + copy() make a shallow copy of a List + deepcopy() make a full copy of a List + filter() remove selected items from a List + map() change each List item + sort() sort a List + reverse() reverse the order of a List + uniq() remove copies of repeated adjacent items + split() split a String into a List + join() join List items into a String + range() return a List with a sequence of numbers + string() String representation of a List + call() call a function with List as arguments + index() index of a value in a List + max() maximum value in a List + min() minimum value in a List + count() count number of times a value appears in a List + repeat() repeat a List multiple times + +Dictionary manipulation: *dict-functions* + get() get an entry without an error for a wrong key + len() number of entries in a Dictionary + has_key() check whether a key appears in a Dictionary + empty() check if Dictionary is empty + remove() remove an entry from a Dictionary + extend() add entries from one Dictionary to another + filter() remove selected entries from a Dictionary + map() change each Dictionary entry + keys() get List of Dictionary keys + values() get List of Dictionary values + items() get List of Dictionary key-value pairs + copy() make a shallow copy of a Dictionary + deepcopy() make a full copy of a Dictionary + string() String representation of a Dictionary + max() maximum value in a Dictionary + min() minimum value in a Dictionary + count() count number of times a value appears + +Floating point computation: *float-functions* + float2nr() convert Float to Number + abs() absolute value (also works for Number) + round() round off + ceil() round up + floor() round down + trunc() remove value after decimal point + fmod() remainder of division + exp() exponential + log() natural logarithm (logarithm to base e) + log10() logarithm to base 10 + pow() value of x to the exponent y + sqrt() square root + sin() sine + cos() cosine + tan() tangent + asin() arc sine + acos() arc cosine + atan() arc tangent + atan2() arc tangent + sinh() hyperbolic sine + cosh() hyperbolic cosine + tanh() hyperbolic tangent + +Other computation: *bitwise-function* + and() bitwise AND + invert() bitwise invert + or() bitwise OR + xor() bitwise XOR + sha256() SHA-256 hash + +Variables: *var-functions* + type() type of a variable + islocked() check if a variable is locked + function() get a Funcref for a function name + getbufvar() get a variable value from a specific buffer + setbufvar() set a variable in a specific buffer + getwinvar() get a variable from specific window + gettabvar() get a variable from specific tab page + gettabwinvar() get a variable from specific window & tab page + setwinvar() set a variable in a specific window + settabvar() set a variable in a specific tab page + settabwinvar() set a variable in a specific window & tab page + garbagecollect() possibly free memory + +Cursor and mark position: *cursor-functions* *mark-functions* + col() column number of the cursor or a mark + virtcol() screen column of the cursor or a mark + line() line number of the cursor or mark + wincol() window column number of the cursor + winline() window line number of the cursor + cursor() position the cursor at a line/column + screencol() get screen column of the cursor + screenrow() get screen row of the cursor + getcurpos() get position of the cursor + getpos() get position of cursor, mark, etc. + setpos() set position of cursor, mark, etc. + byte2line() get line number at a specific byte count + line2byte() byte count at a specific line + diff_filler() get the number of filler lines above a line + screenattr() get attribute at a screen line/row + screenchar() get character code at a screen line/row + +Working with text in the current buffer: *text-functions* + getline() get a line or list of lines from the buffer + setline() replace a line in the buffer + append() append line or list of lines in the buffer + indent() indent of a specific line + cindent() indent according to C indenting + lispindent() indent according to Lisp indenting + nextnonblank() find next non-blank line + prevnonblank() find previous non-blank line + search() find a match for a pattern + searchpos() find a match for a pattern + searchpair() find the other end of a start/skip/end + searchpairpos() find the other end of a start/skip/end + searchdecl() search for the declaration of a name + + *system-functions* *file-functions* +System functions and manipulation of files: + glob() expand wildcards + globpath() expand wildcards in a number of directories + findfile() find a file in a list of directories + finddir() find a directory in a list of directories + resolve() find out where a shortcut points to + fnamemodify() modify a file name + pathshorten() shorten directory names in a path + simplify() simplify a path without changing its meaning + executable() check if an executable program exists + exepath() full path of an executable program + filereadable() check if a file can be read + filewritable() check if a file can be written to + getfperm() get the permissions of a file + getftype() get the kind of a file + isdirectory() check if a directory exists + getfsize() get the size of a file + getcwd() get the current working directory + haslocaldir() check if current window used |:lcd| + tempname() get the name of a temporary file + mkdir() create a new directory + delete() delete a file + rename() rename a file + system() get the result of a shell command as a string + systemlist() get the result of a shell command as a list + hostname() name of the system + readfile() read a file into a List of lines + writefile() write a List of lines into a file + +Date and Time: *date-functions* *time-functions* + getftime() get last modification time of a file + localtime() get current time in seconds + strftime() convert time to a string + reltime() get the current or elapsed time accurately + reltimestr() convert reltime() result to a string + + *buffer-functions* *window-functions* *arg-functions* +Buffers, windows and the argument list: + argc() number of entries in the argument list + argidx() current position in the argument list + arglistid() get id of the argument list + argv() get one entry from the argument list + bufexists() check if a buffer exists + buflisted() check if a buffer exists and is listed + bufloaded() check if a buffer exists and is loaded + bufname() get the name of a specific buffer + bufnr() get the buffer number of a specific buffer + tabpagebuflist() return List of buffers in a tab page + tabpagenr() get the number of a tab page + tabpagewinnr() like winnr() for a specified tab page + winnr() get the window number for the current window + bufwinnr() get the window number of a specific buffer + winbufnr() get the buffer number of a specific window + getbufline() get a list of lines from the specified buffer + +Command line: *command-line-functions* + getcmdline() get the current command line + getcmdpos() get position of the cursor in the command line + setcmdpos() set position of the cursor in the command line + getcmdtype() return the current command-line type + getcmdwintype() return the current command-line window type + +Quickfix and location lists: *quickfix-functions* + getqflist() list of quickfix errors + setqflist() modify a quickfix list + getloclist() list of location list items + setloclist() modify a location list + +Insert mode completion: *completion-functions* + complete() set found matches + complete_add() add to found matches + complete_check() check if completion should be aborted + pumvisible() check if the popup menu is displayed + +Folding: *folding-functions* + foldclosed() check for a closed fold at a specific line + foldclosedend() like foldclosed() but return the last line + foldlevel() check for the fold level at a specific line + foldtext() generate the line displayed for a closed fold + foldtextresult() get the text displayed for a closed fold + +Syntax and highlighting: *syntax-functions* *highlighting-functions* + clearmatches() clear all matches defined by |matchadd()| and + the |:match| commands + getmatches() get all matches defined by |matchadd()| and + the |:match| commands + hlexists() check if a highlight group exists + hlID() get ID of a highlight group + synID() get syntax ID at a specific position + synIDattr() get a specific attribute of a syntax ID + synIDtrans() get translated syntax ID + synstack() get list of syntax IDs at a specific position + synconcealed() get info about concealing + diff_hlID() get highlight ID for diff mode at a position + matchadd() define a pattern to highlight (a "match") + matchaddpos() define a list of positions to highlight + matcharg() get info about |:match| arguments + matchdelete() delete a match defined by |matchadd()| or a + |:match| command + setmatches() restore a list of matches saved by + |getmatches()| + +Spelling: *spell-functions* + spellbadword() locate badly spelled word at or after cursor + spellsuggest() return suggested spelling corrections + soundfold() return the sound-a-like equivalent of a word + +History: *history-functions* + histadd() add an item to a history + histdel() delete an item from a history + histget() get an item from a history + histnr() get highest index of a history list + +Interactive: *interactive-functions* + browse() put up a file requester + browsedir() put up a directory requester + confirm() let the user make a choice + getchar() get a character from the user + getcharmod() get modifiers for the last typed character + feedkeys() put characters in the typeahead queue + input() get a line from the user + inputlist() let the user pick an entry from a list + inputsecret() get a line from the user without showing it + inputdialog() get a line from the user in a dialog + inputsave() save and clear typeahead + inputrestore() restore typeahead + +GUI: *gui-functions* + getfontname() get name of current font being used + getwinposx() X position of the GUI Vim window + getwinposy() Y position of the GUI Vim window + +Vim server: *server-functions* + serverlist() return the list of server names + remote_send() send command characters to a Vim server + remote_expr() evaluate an expression in a Vim server + server2client() send a reply to a client of a Vim server + remote_peek() check if there is a reply from a Vim server + remote_read() read a reply from a Vim server + foreground() move the Vim window to the foreground + remote_foreground() move the Vim server window to the foreground + +Window size and position: *window-size-functions* + winheight() get height of a specific window + winwidth() get width of a specific window + winrestcmd() return command to restore window sizes + winsaveview() get view of current window + winrestview() restore saved view of current window + +Mappings: *mapping-functions* + hasmapto() check if a mapping exists + mapcheck() check if a matching mapping exists + maparg() get rhs of a mapping + wildmenumode() check if the wildmode is active + +Testing: *test-functions* + assert_equal() assert that two expressions values are equal + assert_false() assert that an expression is false + assert_true() assert that an expression is true + +Inter-process communication: + connect() open a channel + disconnect() close a channel + sendexpr() send a JSON message over a channel + sendraw() send a raw message over a channel + jsonencode() encode an expression to a JSON string + jsondecode() decode a JSON string to Vim types + +Various: *various-functions* + mode() get current editing mode + visualmode() last visual mode used + exists() check if a variable, function, etc. exists + has() check if a feature is supported in Vim + changenr() return number of most recent change + cscope_connection() check if a cscope connection exists + did_filetype() check if a FileType autocommand was used + eventhandler() check if invoked by an event handler + getpid() get process ID of Vim + + libcall() call a function in an external library + libcallnr() idem, returning a number + + undofile() get the name of the undo file + undotree() return the state of the undo tree + + getreg() get contents of a register + getregtype() get type of a register + setreg() set contents and type of a register + + shiftwidth() effective value of 'shiftwidth' + + taglist() get list of matching tags + tagfiles() get a list of tags files + + luaeval() evaluate Lua expression + mzeval() evaluate |MzScheme| expression + perleval() evaluate Perl expression (|+perl|) + py3eval() evaluate Python expression (|+python3|) + pyeval() evaluate Python expression (|+python|) + wordcount() get byte/word/char count of buffer + +============================================================================== +*41.7* Defining a function + +Vim enables you to define your own functions. The basic function declaration +begins as follows: > + + :function {name}({var1}, {var2}, ...) + : {body} + :endfunction +< + Note: + Function names must begin with a capital letter. + +Let's define a short function to return the smaller of two numbers. It starts +with this line: > + + :function Min(num1, num2) + +This tells Vim that the function is named "Min" and it takes two arguments: +"num1" and "num2". + The first thing you need to do is to check to see which number is smaller: + > + : if a:num1 < a:num2 + +The special prefix "a:" tells Vim that the variable is a function argument. +Let's assign the variable "smaller" the value of the smallest number: > + + : if a:num1 < a:num2 + : let smaller = a:num1 + : else + : let smaller = a:num2 + : endif + +The variable "smaller" is a local variable. Variables used inside a function +are local unless prefixed by something like "g:", "a:", or "s:". + + Note: + To access a global variable from inside a function you must prepend + "g:" to it. Thus "g:today" inside a function is used for the global + variable "today", and "today" is another variable, local to the + function. + +You now use the ":return" statement to return the smallest number to the user. +Finally, you end the function: > + + : return smaller + :endfunction + +The complete function definition is as follows: > + + :function Min(num1, num2) + : if a:num1 < a:num2 + : let smaller = a:num1 + : else + : let smaller = a:num2 + : endif + : return smaller + :endfunction + +For people who like short functions, this does the same thing: > + + :function Min(num1, num2) + : if a:num1 < a:num2 + : return a:num1 + : endif + : return a:num2 + :endfunction + +A user defined function is called in exactly the same way as a built-in +function. Only the name is different. The Min function can be used like +this: > + + :echo Min(5, 8) + +Only now will the function be executed and the lines be interpreted by Vim. +If there are mistakes, like using an undefined variable or function, you will +now get an error message. When defining the function these errors are not +detected. + +When a function reaches ":endfunction" or ":return" is used without an +argument, the function returns zero. + +To redefine a function that already exists, use the ! for the ":function" +command: > + + :function! Min(num1, num2, num3) + + +USING A RANGE + +The ":call" command can be given a line range. This can have one of two +meanings. When a function has been defined with the "range" keyword, it will +take care of the line range itself. + The function will be passed the variables "a:firstline" and "a:lastline". +These will have the line numbers from the range the function was called with. +Example: > + + :function Count_words() range + : let lnum = a:firstline + : let n = 0 + : while lnum <= a:lastline + : let n = n + len(split(getline(lnum))) + : let lnum = lnum + 1 + : endwhile + : echo "found " . n . " words" + :endfunction + +You can call this function with: > + + :10,30call Count_words() + +It will be executed once and echo the number of words. + The other way to use a line range is by defining a function without the +"range" keyword. The function will be called once for every line in the +range, with the cursor in that line. Example: > + + :function Number() + : echo "line " . line(".") . " contains: " . getline(".") + :endfunction + +If you call this function with: > + + :10,15call Number() + +The function will be called six times. + + +VARIABLE NUMBER OF ARGUMENTS + +Vim enables you to define functions that have a variable number of arguments. +The following command, for instance, defines a function that must have 1 +argument (start) and can have up to 20 additional arguments: > + + :function Show(start, ...) + +The variable "a:1" contains the first optional argument, "a:2" the second, and +so on. The variable "a:0" contains the number of extra arguments. + For example: > + + :function Show(start, ...) + : echohl Title + : echo "start is " . a:start + : echohl None + : let index = 1 + : while index <= a:0 + : echo " Arg " . index . " is " . a:{index} + : let index = index + 1 + : endwhile + : echo "" + :endfunction + +This uses the ":echohl" command to specify the highlighting used for the +following ":echo" command. ":echohl None" stops it again. The ":echon" +command works like ":echo", but doesn't output a line break. + +You can also use the a:000 variable, it is a List of all the "..." arguments. +See |a:000|. + + +LISTING FUNCTIONS + +The ":function" command lists the names and arguments of all user-defined +functions: > + + :function +< function Show(start, ...) ~ + function GetVimIndent() ~ + function SetSyn(name) ~ + +To see what a function does, use its name as an argument for ":function": > + + :function SetSyn +< 1 if &syntax == '' ~ + 2 let &syntax = a:name ~ + 3 endif ~ + endfunction ~ + + +DEBUGGING + +The line number is useful for when you get an error message or when debugging. +See |debug-scripts| about debugging mode. + You can also set the 'verbose' option to 12 or higher to see all function +calls. Set it to 15 or higher to see every executed line. + + +DELETING A FUNCTION + +To delete the Show() function: > + + :delfunction Show + +You get an error when the function doesn't exist. + + +FUNCTION REFERENCES + +Sometimes it can be useful to have a variable point to one function or +another. You can do it with the function() function. It turns the name of a +function into a reference: > + + :let result = 0 " or 1 + :function! Right() + : return 'Right!' + :endfunc + :function! Wrong() + : return 'Wrong!' + :endfunc + : + :if result == 1 + : let Afunc = function('Right') + :else + : let Afunc = function('Wrong') + :endif + :echo call(Afunc, []) +< Wrong! ~ + +Note that the name of a variable that holds a function reference must start +with a capital. Otherwise it could be confused with the name of a builtin +function. + The way to invoke a function that a variable refers to is with the call() +function. Its first argument is the function reference, the second argument +is a List with arguments. + +Function references are most useful in combination with a Dictionary, as is +explained in the next section. + +============================================================================== +*41.8* Lists and Dictionaries + +So far we have used the basic types String and Number. Vim also supports two +composite types: List and Dictionary. + +A List is an ordered sequence of things. The things can be any kind of value, +thus you can make a List of numbers, a List of Lists and even a List of mixed +items. To create a List with three strings: > + + :let alist = ['aap', 'mies', 'noot'] + +The List items are enclosed in square brackets and separated by commas. To +create an empty List: > + + :let alist = [] + +You can add items to a List with the add() function: > + + :let alist = [] + :call add(alist, 'foo') + :call add(alist, 'bar') + :echo alist +< ['foo', 'bar'] ~ + +List concatenation is done with +: > + + :echo alist + ['foo', 'bar'] +< ['foo', 'bar', 'foo', 'bar'] ~ + +Or, if you want to extend a List directly: > + + :let alist = ['one'] + :call extend(alist, ['two', 'three']) + :echo alist +< ['one', 'two', 'three'] ~ + +Notice that using add() will have a different effect: > + + :let alist = ['one'] + :call add(alist, ['two', 'three']) + :echo alist +< ['one', ['two', 'three']] ~ + +The second argument of add() is added as a single item. + + +FOR LOOP + +One of the nice things you can do with a List is iterate over it: > + + :let alist = ['one', 'two', 'three'] + :for n in alist + : echo n + :endfor +< one ~ + two ~ + three ~ + +This will loop over each element in List "alist", assigning the value to +variable "n". The generic form of a for loop is: > + + :for {varname} in {listexpression} + : {commands} + :endfor + +To loop a certain number of times you need a List of a specific length. The +range() function creates one for you: > + + :for a in range(3) + : echo a + :endfor +< 0 ~ + 1 ~ + 2 ~ + +Notice that the first item of the List that range() produces is zero, thus the +last item is one less than the length of the list. + You can also specify the maximum value, the stride and even go backwards: > + + :for a in range(8, 4, -2) + : echo a + :endfor +< 8 ~ + 6 ~ + 4 ~ + +A more useful example, looping over lines in the buffer: > + + :for line in getline(1, 20) + : if line =~ "Date: " + : echo matchstr(line, 'Date: \zs.*') + : endif + :endfor + +This looks into lines 1 to 20 (inclusive) and echoes any date found in there. + + +DICTIONARIES + +A Dictionary stores key-value pairs. You can quickly lookup a value if you +know the key. A Dictionary is created with curly braces: > + + :let uk2nl = {'one': 'een', 'two': 'twee', 'three': 'drie'} + +Now you can lookup words by putting the key in square brackets: > + + :echo uk2nl['two'] +< twee ~ + +The generic form for defining a Dictionary is: > + + {<key> : <value>, ...} + +An empty Dictionary is one without any keys: > + + {} + +The possibilities with Dictionaries are numerous. There are various functions +for them as well. For example, you can obtain a list of the keys and loop +over them: > + + :for key in keys(uk2nl) + : echo key + :endfor +< three ~ + one ~ + two ~ + +You will notice the keys are not ordered. You can sort the list to get a +specific order: > + + :for key in sort(keys(uk2nl)) + : echo key + :endfor +< one ~ + three ~ + two ~ + +But you can never get back the order in which items are defined. For that you +need to use a List, it stores items in an ordered sequence. + + +DICTIONARY FUNCTIONS + +The items in a Dictionary can normally be obtained with an index in square +brackets: > + + :echo uk2nl['one'] +< een ~ + +A method that does the same, but without so many punctuation characters: > + + :echo uk2nl.one +< een ~ + +This only works for a key that is made of ASCII letters, digits and the +underscore. You can also assign a new value this way: > + + :let uk2nl.four = 'vier' + :echo uk2nl +< {'three': 'drie', 'four': 'vier', 'one': 'een', 'two': 'twee'} ~ + +And now for something special: you can directly define a function and store a +reference to it in the dictionary: > + + :function uk2nl.translate(line) dict + : return join(map(split(a:line), 'get(self, v:val, "???")')) + :endfunction + +Let's first try it out: > + + :echo uk2nl.translate('three two five one') +< drie twee ??? een ~ + +The first special thing you notice is the "dict" at the end of the ":function" +line. This marks the function as being used from a Dictionary. The "self" +local variable will then refer to that Dictionary. + Now let's break up the complicated return command: > + + split(a:line) + +The split() function takes a string, chops it into whitespace separated words +and returns a list with these words. Thus in the example it returns: > + + :echo split('three two five one') +< ['three', 'two', 'five', 'one'] ~ + +This list is the first argument to the map() function. This will go through +the list, evaluating its second argument with "v:val" set to the value of each +item. This is a shortcut to using a for loop. This command: > + + :let alist = map(split(a:line), 'get(self, v:val, "???")') + +Is equivalent to: > + + :let alist = split(a:line) + :for idx in range(len(alist)) + : let alist[idx] = get(self, alist[idx], "???") + :endfor + +The get() function checks if a key is present in a Dictionary. If it is, then +the value is retrieved. If it isn't, then the default value is returned, in +the example it's '???'. This is a convenient way to handle situations where a +key may not be present and you don't want an error message. + +The join() function does the opposite of split(): it joins together a list of +words, putting a space in between. + This combination of split(), map() and join() is a nice way to filter a line +of words in a very compact way. + + +OBJECT ORIENTED PROGRAMMING + +Now that you can put both values and functions in a Dictionary, you can +actually use a Dictionary like an object. + Above we used a Dictionary for translating Dutch to English. We might want +to do the same for other languages. Let's first make an object (aka +Dictionary) that has the translate function, but no words to translate: > + + :let transdict = {} + :function transdict.translate(line) dict + : return join(map(split(a:line), 'get(self.words, v:val, "???")')) + :endfunction + +It's slightly different from the function above, using 'self.words' to lookup +word translations. But we don't have a self.words. Thus you could call this +an abstract class. + +Now we can instantiate a Dutch translation object: > + + :let uk2nl = copy(transdict) + :let uk2nl.words = {'one': 'een', 'two': 'twee', 'three': 'drie'} + :echo uk2nl.translate('three one') +< drie een ~ + +And a German translator: > + + :let uk2de = copy(transdict) + :let uk2de.words = {'one': 'ein', 'two': 'zwei', 'three': 'drei'} + :echo uk2de.translate('three one') +< drei ein ~ + +You see that the copy() function is used to make a copy of the "transdict" +Dictionary and then the copy is changed to add the words. The original +remains the same, of course. + +Now you can go one step further, and use your preferred translator: > + + :if $LANG =~ "de" + : let trans = uk2de + :else + : let trans = uk2nl + :endif + :echo trans.translate('one two three') +< een twee drie ~ + +Here "trans" refers to one of the two objects (Dictionaries). No copy is +made. More about List and Dictionary identity can be found at |list-identity| +and |dict-identity|. + +Now you might use a language that isn't supported. You can overrule the +translate() function to do nothing: > + + :let uk2uk = copy(transdict) + :function! uk2uk.translate(line) + : return a:line + :endfunction + :echo uk2uk.translate('three one wladiwostok') +< three one wladiwostok ~ + +Notice that a ! was used to overwrite the existing function reference. Now +use "uk2uk" when no recognized language is found: > + + :if $LANG =~ "de" + : let trans = uk2de + :elseif $LANG =~ "nl" + : let trans = uk2nl + :else + : let trans = uk2uk + :endif + :echo trans.translate('one two three') +< one two three ~ + +For further reading see |Lists| and |Dictionaries|. + +============================================================================== +*41.9* Exceptions + +Let's start with an example: > + + :try + : read ~/templates/pascal.tmpl + :catch /E484:/ + : echo "Sorry, the Pascal template file cannot be found." + :endtry + +The ":read" command will fail if the file does not exist. Instead of +generating an error message, this code catches the error and gives the user a +nice message. + +For the commands in between ":try" and ":endtry" errors are turned into +exceptions. An exception is a string. In the case of an error the string +contains the error message. And every error message has a number. In this +case, the error we catch contains "E484:". This number is guaranteed to stay +the same (the text may change, e.g., it may be translated). + +When the ":read" command causes another error, the pattern "E484:" will not +match in it. Thus this exception will not be caught and result in the usual +error message. + +You might be tempted to do this: > + + :try + : read ~/templates/pascal.tmpl + :catch + : echo "Sorry, the Pascal template file cannot be found." + :endtry + +This means all errors are caught. But then you will not see errors that are +useful, such as "E21: Cannot make changes, 'modifiable' is off". + +Another useful mechanism is the ":finally" command: > + + :let tmp = tempname() + :try + : exe ".,$write " . tmp + : exe "!filter " . tmp + : .,$delete + : exe "$read " . tmp + :finally + : call delete(tmp) + :endtry + +This filters the lines from the cursor until the end of the file through the +"filter" command, which takes a file name argument. No matter if the +filtering works, something goes wrong in between ":try" and ":finally" or the +user cancels the filtering by pressing CTRL-C, the "call delete(tmp)" is +always executed. This makes sure you don't leave the temporary file behind. + +More information about exception handling can be found in the reference +manual: |exception-handling|. + +============================================================================== +*41.10* Various remarks + +Here is a summary of items that apply to Vim scripts. They are also mentioned +elsewhere, but form a nice checklist. + +The end-of-line character depends on the system. For Unix a single <NL> +character is used. For MS-DOS, Windows, OS/2 and the like, <CR><LF> is used. +This is important when using mappings that end in a <CR>. See |:source_crnl|. + + +WHITE SPACE + +Blank lines are allowed and ignored. + +Leading whitespace characters (blanks and TABs) are always ignored. The +whitespaces between parameters (e.g. between the 'set' and the 'cpoptions' in +the example below) are reduced to one blank character and plays the role of a +separator, the whitespaces after the last (visible) character may or may not +be ignored depending on the situation, see below. + +For a ":set" command involving the "=" (equal) sign, such as in: > + + :set cpoptions =aABceFst + +the whitespace immediately before the "=" sign is ignored. But there can be +no whitespace after the "=" sign! + +To include a whitespace character in the value of an option, it must be +escaped by a "\" (backslash) as in the following example: > + + :set tags=my\ nice\ file + +The same example written as: > + + :set tags=my nice file + +will issue an error, because it is interpreted as: > + + :set tags=my + :set nice + :set file + + +COMMENTS + +The character " (the double quote mark) starts a comment. Everything after +and including this character until the end-of-line is considered a comment and +is ignored, except for commands that don't consider comments, as shown in +examples below. A comment can start on any character position on the line. + +There is a little "catch" with comments for some commands. Examples: > + + :abbrev dev development " shorthand + :map <F3> o#include " insert include + :execute cmd " do it + :!ls *.c " list C files + +The abbreviation 'dev' will be expanded to 'development " shorthand'. The +mapping of <F3> will actually be the whole line after the 'o# ....' including +the '" insert include'. The "execute" command will give an error. The "!" +command will send everything after it to the shell, causing an error for an +unmatched '"' character. + There can be no comment after ":map", ":abbreviate", ":execute" and "!" +commands (there are a few more commands with this restriction). For the +":map", ":abbreviate" and ":execute" commands there is a trick: > + + :abbrev dev development|" shorthand + :map <F3> o#include|" insert include + :execute cmd |" do it + +With the '|' character the command is separated from the next one. And that +next command is only a comment. For the last command you need to do two +things: |:execute| and use '|': > + :exe '!ls *.c' |" list C files + +Notice that there is no white space before the '|' in the abbreviation and +mapping. For these commands, any character until the end-of-line or '|' is +included. As a consequence of this behavior, you don't always see that +trailing whitespace is included: > + + :map <F4> o#include + +To spot these problems, you can set the 'list' option when editing vimrc +files. + +For Unix there is one special way to comment a line, that allows making a Vim +script executable: > + #!/usr/bin/env vim -S + echo "this is a Vim script" + quit + +The "#" command by itself lists a line with the line number. Adding an +exclamation mark changes it into doing nothing, so that you can add the shell +command to execute the rest of the file. |:#!| |-S| + + +PITFALLS + +Even bigger problem arises in the following example: > + + :map ,ab o#include + :unmap ,ab + +Here the unmap command will not work, because it tries to unmap ",ab ". This +does not exist as a mapped sequence. An error will be issued, which is very +hard to identify, because the ending whitespace character in ":unmap ,ab " is +not visible. + +And this is the same as what happens when one uses a comment after an 'unmap' +command: > + + :unmap ,ab " comment + +Here the comment part will be ignored. However, Vim will try to unmap +',ab ', which does not exist. Rewrite it as: > + + :unmap ,ab| " comment + + +RESTORING THE VIEW + +Sometimes you want to make a change and go back to where the cursor was. +Restoring the relative position would also be nice, so that the same line +appears at the top of the window. + This example yanks the current line, puts it above the first line in the +file and then restores the view: > + + map ,p ma"aYHmbgg"aP`bzt`a + +What this does: > + ma"aYHmbgg"aP`bzt`a +< ma set mark a at cursor position + "aY yank current line into register a + Hmb go to top line in window and set mark b there + gg go to first line in file + "aP put the yanked line above it + `b go back to top line in display + zt position the text in the window as before + `a go back to saved cursor position + + +PACKAGING + +To avoid your function names to interfere with functions that you get from +others, use this scheme: +- Prepend a unique string before each function name. I often use an + abbreviation. For example, "OW_" is used for the option window functions. +- Put the definition of your functions together in a file. Set a global + variable to indicate that the functions have been loaded. When sourcing the + file again, first unload the functions. +Example: > + + " This is the XXX package + + if exists("XXX_loaded") + delfun XXX_one + delfun XXX_two + endif + + function XXX_one(a) + ... body of function ... + endfun + + function XXX_two(b) + ... body of function ... + endfun + + let XXX_loaded = 1 + +============================================================================== +*41.11* Writing a plugin *write-plugin* + +You can write a Vim script in such a way that many people can use it. This is +called a plugin. Vim users can drop your script in their plugin directory and +use its features right away |add-plugin|. + +There are actually two types of plugins: + + global plugins: For all types of files. +filetype plugins: Only for files of a specific type. + +In this section the first type is explained. Most items are also relevant for +writing filetype plugins. The specifics for filetype plugins are in the next +section |write-filetype-plugin|. + + +NAME + +First of all you must choose a name for your plugin. The features provided +by the plugin should be clear from its name. And it should be unlikely that +someone else writes a plugin with the same name but which does something +different. And please limit the name to 8 characters, to avoid problems on +old Windows systems. + +A script that corrects typing mistakes could be called "typecorr.vim". We +will use it here as an example. + +For the plugin to work for everybody, it should follow a few guidelines. This +will be explained step-by-step. The complete example plugin is at the end. + + +BODY + +Let's start with the body of the plugin, the lines that do the actual work: > + + 14 iabbrev teh the + 15 iabbrev otehr other + 16 iabbrev wnat want + 17 iabbrev synchronisation + 18 \ synchronization + 19 let s:count = 4 + +The actual list should be much longer, of course. + +The line numbers have only been added to explain a few things, don't put them +in your plugin file! + + +HEADER + +You will probably add new corrections to the plugin and soon have several +versions lying around. And when distributing this file, people will want to +know who wrote this wonderful plugin and where they can send remarks. +Therefore, put a header at the top of your plugin: > + + 1 " Vim global plugin for correcting typing mistakes + 2 " Last Change: 2000 Oct 15 + 3 " Maintainer: Bram Moolenaar <Bram@vim.org> + +About copyright and licensing: Since plugins are very useful and it's hardly +worth restricting their distribution, please consider making your plugin +either public domain or use the Vim |license|. A short note about this near +the top of the plugin should be sufficient. Example: > + + 4 " License: This file is placed in the public domain. + + +LINE CONTINUATION, AVOIDING SIDE EFFECTS *use-cpo-save* + +In line 18 above, the line-continuation mechanism is used |line-continuation|. +Users with 'compatible' set will run into trouble here, they will get an error +message. We can't just reset 'compatible', because that has a lot of side +effects. To avoid this, we will set the 'cpoptions' option to its Vim default +value and restore it later. That will allow the use of line-continuation and +make the script work for most people. It is done like this: > + + 11 let s:save_cpo = &cpo + 12 set cpo&vim + .. + 42 let &cpo = s:save_cpo + 43 unlet s:save_cpo + +We first store the old value of 'cpoptions' in the s:save_cpo variable. At +the end of the plugin this value is restored. + +Notice that a script-local variable is used |s:var|. A global variable could +already be in use for something else. Always use script-local variables for +things that are only used in the script. + + +NOT LOADING + +It's possible that a user doesn't always want to load this plugin. Or the +system administrator has dropped it in the system-wide plugin directory, but a +user has his own plugin he wants to use. Then the user must have a chance to +disable loading this specific plugin. This will make it possible: > + + 6 if exists("g:loaded_typecorr") + 7 finish + 8 endif + 9 let g:loaded_typecorr = 1 + +This also avoids that when the script is loaded twice it would cause error +messages for redefining functions and cause trouble for autocommands that are +added twice. + +The name is recommended to start with "loaded_" and then the file name of the +plugin, literally. The "g:" is prepended just to avoid mistakes when using +the variable in a function (without "g:" it would be a variable local to the +function). + +Using "finish" stops Vim from reading the rest of the file, it's much quicker +than using if-endif around the whole file. + + +MAPPING + +Now let's make the plugin more interesting: We will add a mapping that adds a +correction for the word under the cursor. We could just pick a key sequence +for this mapping, but the user might already use it for something else. To +allow the user to define which keys a mapping in a plugin uses, the <Leader> +item can be used: > + + 22 map <unique> <Leader>a <Plug>TypecorrAdd + +The "<Plug>TypecorrAdd" thing will do the work, more about that further on. + +The user can set the "mapleader" variable to the key sequence that he wants +this mapping to start with. Thus if the user has done: > + + let mapleader = "_" + +the mapping will define "_a". If the user didn't do this, the default value +will be used, which is a backslash. Then a map for "\a" will be defined. + +Note that <unique> is used, this will cause an error message if the mapping +already happened to exist. |:map-<unique>| + +But what if the user wants to define his own key sequence? We can allow that +with this mechanism: > + + 21 if !hasmapto('<Plug>TypecorrAdd') + 22 map <unique> <Leader>a <Plug>TypecorrAdd + 23 endif + +This checks if a mapping to "<Plug>TypecorrAdd" already exists, and only +defines the mapping from "<Leader>a" if it doesn't. The user then has a +chance of putting this in his vimrc file: > + + map ,c <Plug>TypecorrAdd + +Then the mapped key sequence will be ",c" instead of "_a" or "\a". + + +PIECES + +If a script gets longer, you often want to break up the work in pieces. You +can use functions or mappings for this. But you don't want these functions +and mappings to interfere with the ones from other scripts. For example, you +could define a function Add(), but another script could try to define the same +function. To avoid this, we define the function local to the script by +prepending it with "s:". + +We will define a function that adds a new typing correction: > + + 30 function s:Add(from, correct) + 31 let to = input("type the correction for " . a:from . ": ") + 32 exe ":iabbrev " . a:from . " " . to + .. + 36 endfunction + +Now we can call the function s:Add() from within this script. If another +script also defines s:Add(), it will be local to that script and can only +be called from the script it was defined in. There can also be a global Add() +function (without the "s:"), which is again another function. + +<SID> can be used with mappings. It generates a script ID, which identifies +the current script. In our typing correction plugin we use it like this: > + + 24 noremap <unique> <script> <Plug>TypecorrAdd <SID>Add + .. + 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR> + +Thus when a user types "\a", this sequence is invoked: > + + \a -> <Plug>TypecorrAdd -> <SID>Add -> :call <SID>Add() + +If another script would also map <SID>Add, it would get another script ID and +thus define another mapping. + +Note that instead of s:Add() we use <SID>Add() here. That is because the +mapping is typed by the user, thus outside of the script. The <SID> is +translated to the script ID, so that Vim knows in which script to look for +the Add() function. + +This is a bit complicated, but it's required for the plugin to work together +with other plugins. The basic rule is that you use <SID>Add() in mappings and +s:Add() in other places (the script itself, autocommands, user commands). + +We can also add a menu entry to do the same as the mapping: > + + 26 noremenu <script> Plugin.Add\ Correction <SID>Add + +The "Plugin" menu is recommended for adding menu items for plugins. In this +case only one item is used. When adding more items, creating a submenu is +recommended. For example, "Plugin.CVS" could be used for a plugin that offers +CVS operations "Plugin.CVS.checkin", "Plugin.CVS.checkout", etc. + +Note that in line 28 ":noremap" is used to avoid that any other mappings cause +trouble. Someone may have remapped ":call", for example. In line 24 we also +use ":noremap", but we do want "<SID>Add" to be remapped. This is why +"<script>" is used here. This only allows mappings which are local to the +script. |:map-<script>| The same is done in line 26 for ":noremenu". +|:menu-<script>| + + +<SID> AND <Plug> *using-<Plug>* + +Both <SID> and <Plug> are used to avoid that mappings of typed keys interfere +with mappings that are only to be used from other mappings. Note the +difference between using <SID> and <Plug>: + +<Plug> is visible outside of the script. It is used for mappings which the + user might want to map a key sequence to. <Plug> is a special code + that a typed key will never produce. + To make it very unlikely that other plugins use the same sequence of + characters, use this structure: <Plug> scriptname mapname + In our example the scriptname is "Typecorr" and the mapname is "Add". + This results in "<Plug>TypecorrAdd". Only the first character of + scriptname and mapname is uppercase, so that we can see where mapname + starts. + +<SID> is the script ID, a unique identifier for a script. + Internally Vim translates <SID> to "<SNR>123_", where "123" can be any + number. Thus a function "<SID>Add()" will have a name "<SNR>11_Add()" + in one script, and "<SNR>22_Add()" in another. You can see this if + you use the ":function" command to get a list of functions. The + translation of <SID> in mappings is exactly the same, that's how you + can call a script-local function from a mapping. + + +USER COMMAND + +Now let's add a user command to add a correction: > + + 38 if !exists(":Correct") + 39 command -nargs=1 Correct :call s:Add(<q-args>, 0) + 40 endif + +The user command is defined only if no command with the same name already +exists. Otherwise we would get an error here. Overriding the existing user +command with ":command!" is not a good idea, this would probably make the user +wonder why the command he defined himself doesn't work. |:command| + + +SCRIPT VARIABLES + +When a variable starts with "s:" it is a script variable. It can only be used +inside a script. Outside the script it's not visible. This avoids trouble +with using the same variable name in different scripts. The variables will be +kept as long as Vim is running. And the same variables are used when sourcing +the same script again. |s:var| + +The fun is that these variables can also be used in functions, autocommands +and user commands that are defined in the script. In our example we can add +a few lines to count the number of corrections: > + + 19 let s:count = 4 + .. + 30 function s:Add(from, correct) + .. + 34 let s:count = s:count + 1 + 35 echo s:count . " corrections now" + 36 endfunction + +First s:count is initialized to 4 in the script itself. When later the +s:Add() function is called, it increments s:count. It doesn't matter from +where the function was called, since it has been defined in the script, it +will use the local variables from this script. + + +THE RESULT + +Here is the resulting complete example: > + + 1 " Vim global plugin for correcting typing mistakes + 2 " Last Change: 2000 Oct 15 + 3 " Maintainer: Bram Moolenaar <Bram@vim.org> + 4 " License: This file is placed in the public domain. + 5 + 6 if exists("g:loaded_typecorr") + 7 finish + 8 endif + 9 let g:loaded_typecorr = 1 + 10 + 11 let s:save_cpo = &cpo + 12 set cpo&vim + 13 + 14 iabbrev teh the + 15 iabbrev otehr other + 16 iabbrev wnat want + 17 iabbrev synchronisation + 18 \ synchronization + 19 let s:count = 4 + 20 + 21 if !hasmapto('<Plug>TypecorrAdd') + 22 map <unique> <Leader>a <Plug>TypecorrAdd + 23 endif + 24 noremap <unique> <script> <Plug>TypecorrAdd <SID>Add + 25 + 26 noremenu <script> Plugin.Add\ Correction <SID>Add + 27 + 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR> + 29 + 30 function s:Add(from, correct) + 31 let to = input("type the correction for " . a:from . ": ") + 32 exe ":iabbrev " . a:from . " " . to + 33 if a:correct | exe "normal viws\<C-R>\" \b\e" | endif + 34 let s:count = s:count + 1 + 35 echo s:count . " corrections now" + 36 endfunction + 37 + 38 if !exists(":Correct") + 39 command -nargs=1 Correct :call s:Add(<q-args>, 0) + 40 endif + 41 + 42 let &cpo = s:save_cpo + 43 unlet s:save_cpo + +Line 33 wasn't explained yet. It applies the new correction to the word under +the cursor. The |:normal| command is used to use the new abbreviation. Note +that mappings and abbreviations are expanded here, even though the function +was called from a mapping defined with ":noremap". + +Using "unix" for the 'fileformat' option is recommended. The Vim scripts will +then work everywhere. Scripts with 'fileformat' set to "dos" do not work on +Unix. Also see |:source_crnl|. To be sure it is set right, do this before +writing the file: > + + :set fileformat=unix + + +DOCUMENTATION *write-local-help* + +It's a good idea to also write some documentation for your plugin. Especially +when its behavior can be changed by the user. See |add-local-help| for how +they are installed. + +Here is a simple example for a plugin help file, called "typecorr.txt": > + + 1 *typecorr.txt* Plugin for correcting typing mistakes + 2 + 3 If you make typing mistakes, this plugin will have them corrected + 4 automatically. + 5 + 6 There are currently only a few corrections. Add your own if you like. + 7 + 8 Mappings: + 9 <Leader>a or <Plug>TypecorrAdd + 10 Add a correction for the word under the cursor. + 11 + 12 Commands: + 13 :Correct {word} + 14 Add a correction for {word}. + 15 + 16 *typecorr-settings* + 17 This plugin doesn't have any settings. + +The first line is actually the only one for which the format matters. It will +be extracted from the help file to be put in the "LOCAL ADDITIONS:" section of +help.txt |local-additions|. The first "*" must be in the first column of the +first line. After adding your help file do ":help" and check that the entries +line up nicely. + +You can add more tags inside ** in your help file. But be careful not to use +existing help tags. You would probably use the name of your plugin in most of +them, like "typecorr-settings" in the example. + +Using references to other parts of the help in || is recommended. This makes +it easy for the user to find associated help. + + +FILETYPE DETECTION *plugin-filetype* + +If your filetype is not already detected by Vim, you should create a filetype +detection snippet in a separate file. It is usually in the form of an +autocommand that sets the filetype when the file name matches a pattern. +Example: > + + au BufNewFile,BufRead *.foo set filetype=foofoo + +Write this single-line file as "ftdetect/foofoo.vim" in the first directory +that appears in 'runtimepath'. For Unix that would be +"~/.vim/ftdetect/foofoo.vim". The convention is to use the name of the +filetype for the script name. + +You can make more complicated checks if you like, for example to inspect the +contents of the file to recognize the language. Also see |new-filetype|. + + +SUMMARY *plugin-special* + +Summary of special things to use in a plugin: + +s:name Variables local to the script. + +<SID> Script-ID, used for mappings and functions local to + the script. + +hasmapto() Function to test if the user already defined a mapping + for functionality the script offers. + +<Leader> Value of "mapleader", which the user defines as the + keys that plugin mappings start with. + +:map <unique> Give a warning if a mapping already exists. + +:noremap <script> Use only mappings local to the script, not global + mappings. + +exists(":Cmd") Check if a user command already exists. + +============================================================================== +*41.12* Writing a filetype plugin *write-filetype-plugin* *ftplugin* + +A filetype plugin is like a global plugin, except that it sets options and +defines mappings for the current buffer only. See |add-filetype-plugin| for +how this type of plugin is used. + +First read the section on global plugins above |41.11|. All that is said there +also applies to filetype plugins. There are a few extras, which are explained +here. The essential thing is that a filetype plugin should only have an +effect on the current buffer. + + +DISABLING + +If you are writing a filetype plugin to be used by many people, they need a +chance to disable loading it. Put this at the top of the plugin: > + + " Only do this when not done yet for this buffer + if exists("b:did_ftplugin") + finish + endif + let b:did_ftplugin = 1 + +This also needs to be used to avoid that the same plugin is executed twice for +the same buffer (happens when using an ":edit" command without arguments). + +Now users can disable loading the default plugin completely by making a +filetype plugin with only this line: > + + let b:did_ftplugin = 1 + +This does require that the filetype plugin directory comes before $VIMRUNTIME +in 'runtimepath'! + +If you do want to use the default plugin, but overrule one of the settings, +you can write the different setting in a script: > + + setlocal textwidth=70 + +Now write this in the "after" directory, so that it gets sourced after the +distributed "vim.vim" ftplugin |after-directory|. For Unix this would be +"~/.vim/after/ftplugin/vim.vim". Note that the default plugin will have set +"b:did_ftplugin", but it is ignored here. + + +OPTIONS + +To make sure the filetype plugin only affects the current buffer use the > + + :setlocal + +command to set options. And only set options which are local to a buffer (see +the help for the option to check that). When using |:setlocal| for global +options or options local to a window, the value will change for many buffers, +and that is not what a filetype plugin should do. + +When an option has a value that is a list of flags or items, consider using +"+=" and "-=" to keep the existing value. Be aware that the user may have +changed an option value already. First resetting to the default value and +then changing it is often a good idea. Example: > + + :setlocal formatoptions& formatoptions+=ro + + +MAPPINGS + +To make sure mappings will only work in the current buffer use the > + + :map <buffer> + +command. This needs to be combined with the two-step mapping explained above. +An example of how to define functionality in a filetype plugin: > + + if !hasmapto('<Plug>JavaImport') + map <buffer> <unique> <LocalLeader>i <Plug>JavaImport + endif + noremap <buffer> <unique> <Plug>JavaImport oimport ""<Left><Esc> + +|hasmapto()| is used to check if the user has already defined a map to +<Plug>JavaImport. If not, then the filetype plugin defines the default +mapping. This starts with |<LocalLeader>|, which allows the user to select +the key(s) he wants filetype plugin mappings to start with. The default is a +backslash. +"<unique>" is used to give an error message if the mapping already exists or +overlaps with an existing mapping. +|:noremap| is used to avoid that any other mappings that the user has defined +interferes. You might want to use ":noremap <script>" to allow remapping +mappings defined in this script that start with <SID>. + +The user must have a chance to disable the mappings in a filetype plugin, +without disabling everything. Here is an example of how this is done for a +plugin for the mail filetype: > + + " Add mappings, unless the user didn't want this. + if !exists("no_plugin_maps") && !exists("no_mail_maps") + " Quote text by inserting "> " + if !hasmapto('<Plug>MailQuote') + vmap <buffer> <LocalLeader>q <Plug>MailQuote + nmap <buffer> <LocalLeader>q <Plug>MailQuote + endif + vnoremap <buffer> <Plug>MailQuote :s/^/> /<CR> + nnoremap <buffer> <Plug>MailQuote :.,$s/^/> /<CR> + endif + +Two global variables are used: +no_plugin_maps disables mappings for all filetype plugins +no_mail_maps disables mappings for a specific filetype + + +USER COMMANDS + +To add a user command for a specific file type, so that it can only be used in +one buffer, use the "-buffer" argument to |:command|. Example: > + + :command -buffer Make make %:r.s + + +VARIABLES + +A filetype plugin will be sourced for each buffer of the type it's for. Local +script variables |s:var| will be shared between all invocations. Use local +buffer variables |b:var| if you want a variable specifically for one buffer. + + +FUNCTIONS + +When defining a function, this only needs to be done once. But the filetype +plugin will be sourced every time a file with this filetype will be opened. +This construct makes sure the function is only defined once: > + + :if !exists("*s:Func") + : function s:Func(arg) + : ... + : endfunction + :endif +< + +UNDO *undo_ftplugin* + +When the user does ":setfiletype xyz" the effect of the previous filetype +should be undone. Set the b:undo_ftplugin variable to the commands that will +undo the settings in your filetype plugin. Example: > + + let b:undo_ftplugin = "setlocal fo< com< tw< commentstring<" + \ . "| unlet b:match_ignorecase b:match_words b:match_skip" + +Using ":setlocal" with "<" after the option name resets the option to its +global value. That is mostly the best way to reset the option value. + +This does require removing the "C" flag from 'cpoptions' to allow line +continuation, as mentioned above |use-cpo-save|. + + +FILE NAME + +The filetype must be included in the file name |ftplugin-name|. Use one of +these three forms: + + .../ftplugin/stuff.vim + .../ftplugin/stuff_foo.vim + .../ftplugin/stuff/bar.vim + +"stuff" is the filetype, "foo" and "bar" are arbitrary names. + + +SUMMARY *ftplugin-special* + +Summary of special things to use in a filetype plugin: + +<LocalLeader> Value of "maplocalleader", which the user defines as + the keys that filetype plugin mappings start with. + +:map <buffer> Define a mapping local to the buffer. + +:noremap <script> Only remap mappings defined in this script that start + with <SID>. + +:setlocal Set an option for the current buffer only. + +:command -buffer Define a user command local to the buffer. + +exists("*s:Func") Check if a function was already defined. + +Also see |plugin-special|, the special things used for all plugins. + +============================================================================== +*41.13* Writing a compiler plugin *write-compiler-plugin* + +A compiler plugin sets options for use with a specific compiler. The user can +load it with the |:compiler| command. The main use is to set the +'errorformat' and 'makeprg' options. + +Easiest is to have a look at examples. This command will edit all the default +compiler plugins: > + + :next $VIMRUNTIME/compiler/*.vim + +Use |:next| to go to the next plugin file. + +There are two special items about these files. First is a mechanism to allow +a user to overrule or add to the default file. The default files start with: > + + :if exists("current_compiler") + : finish + :endif + :let current_compiler = "mine" + +When you write a compiler file and put it in your personal runtime directory +(e.g., ~/.vim/compiler for Unix), you set the "current_compiler" variable to +make the default file skip the settings. + *:CompilerSet* +The second mechanism is to use ":set" for ":compiler!" and ":setlocal" for +":compiler". Vim defines the ":CompilerSet" user command for this. However, +older Vim versions don't, thus your plugin should define it then. This is an +example: > + + if exists(":CompilerSet") != 2 + command -nargs=* CompilerSet setlocal <args> + endif + CompilerSet errorformat& " use the default 'errorformat' + CompilerSet makeprg=nmake + +When you write a compiler plugin for the Vim distribution or for a system-wide +runtime directory, use the mechanism mentioned above. When +"current_compiler" was already set by a user plugin nothing will be done. + +When you write a compiler plugin to overrule settings from a default plugin, +don't check "current_compiler". This plugin is supposed to be loaded +last, thus it should be in a directory at the end of 'runtimepath'. For Unix +that could be ~/.vim/after/compiler. + +============================================================================== +*41.14* Writing a plugin that loads quickly *write-plugin-quickload* + +A plugin may grow and become quite long. The startup delay may become +noticeable, while you hardly ever use the plugin. Then it's time for a +quickload plugin. + +The basic idea is that the plugin is loaded twice. The first time user +commands and mappings are defined that offer the functionality. The second +time the functions that implement the functionality are defined. + +It may sound surprising that quickload means loading a script twice. What we +mean is that it loads quickly the first time, postponing the bulk of the +script to the second time, which only happens when you actually use it. When +you always use the functionality it actually gets slower! + +Note that since Vim 7 there is an alternative: use the |autoload| +functionality |41.15|. + +The following example shows how it's done: > + + " Vim global plugin for demonstrating quick loading + " Last Change: 2005 Feb 25 + " Maintainer: Bram Moolenaar <Bram@vim.org> + " License: This file is placed in the public domain. + + if !exists("s:did_load") + command -nargs=* BNRead call BufNetRead(<f-args>) + map <F19> :call BufNetWrite('something')<CR> + + let s:did_load = 1 + exe 'au FuncUndefined BufNet* source ' . expand('<sfile>') + finish + endif + + function BufNetRead(...) + echo 'BufNetRead(' . string(a:000) . ')' + " read functionality here + endfunction + + function BufNetWrite(...) + echo 'BufNetWrite(' . string(a:000) . ')' + " write functionality here + endfunction + +When the script is first loaded "s:did_load" is not set. The commands between +the "if" and "endif" will be executed. This ends in a |:finish| command, thus +the rest of the script is not executed. + +The second time the script is loaded "s:did_load" exists and the commands +after the "endif" are executed. This defines the (possible long) +BufNetRead() and BufNetWrite() functions. + +If you drop this script in your plugin directory Vim will execute it on +startup. This is the sequence of events that happens: + +1. The "BNRead" command is defined and the <F19> key is mapped when the script + is sourced at startup. A |FuncUndefined| autocommand is defined. The + ":finish" command causes the script to terminate early. + +2. The user types the BNRead command or presses the <F19> key. The + BufNetRead() or BufNetWrite() function will be called. + +3. Vim can't find the function and triggers the |FuncUndefined| autocommand + event. Since the pattern "BufNet*" matches the invoked function, the + command "source fname" will be executed. "fname" will be equal to the name + of the script, no matter where it is located, because it comes from + expanding "<sfile>" (see |expand()|). + +4. The script is sourced again, the "s:did_load" variable exists and the + functions are defined. + +Notice that the functions that are loaded afterwards match the pattern in the +|FuncUndefined| autocommand. You must make sure that no other plugin defines +functions that match this pattern. + +============================================================================== +*41.15* Writing library scripts *write-library-script* + +Some functionality will be required in several places. When this becomes more +than a few lines you will want to put it in one script and use it from many +scripts. We will call that one script a library script. + +Manually loading a library script is possible, so long as you avoid loading it +when it's already done. You can do this with the |exists()| function. +Example: > + + if !exists('*MyLibFunction') + runtime library/mylibscript.vim + endif + call MyLibFunction(arg) + +Here you need to know that MyLibFunction() is defined in a script +"library/mylibscript.vim" in one of the directories in 'runtimepath'. + +To make this a bit simpler Vim offers the autoload mechanism. Then the +example looks like this: > + + call mylib#myfunction(arg) + +That's a lot simpler, isn't it? Vim will recognize the function name and when +it's not defined search for the script "autoload/mylib.vim" in 'runtimepath'. +That script must define the "mylib#myfunction()" function. + +You can put many other functions in the mylib.vim script, you are free to +organize your functions in library scripts. But you must use function names +where the part before the '#' matches the script name. Otherwise Vim would +not know what script to load. + +If you get really enthusiastic and write lots of library scripts, you may +want to use subdirectories. Example: > + + call netlib#ftp#read('somefile') + +For Unix the library script used for this could be: + + ~/.vim/autoload/netlib/ftp.vim + +Where the function is defined like this: > + + function netlib#ftp#read(fname) + " Read the file fname through ftp + endfunction + +Notice that the name the function is defined with is exactly the same as the +name used for calling the function. And the part before the last '#' +exactly matches the subdirectory and script name. + +You can use the same mechanism for variables: > + + let weekdays = dutch#weekdays + +This will load the script "autoload/dutch.vim", which should contain something +like: > + + let dutch#weekdays = ['zondag', 'maandag', 'dinsdag', 'woensdag', + \ 'donderdag', 'vrijdag', 'zaterdag'] + +Further reading: |autoload|. + +============================================================================== +*41.16* Distributing Vim scripts *distribute-script* + +Vim users will look for scripts on the Vim website: http://www.vim.org. +If you made something that is useful for others, share it! + +Vim scripts can be used on any system. There might not be a tar or gzip +command. If you want to pack files together and/or compress them the "zip" +utility is recommended. + +For utmost portability use Vim itself to pack scripts together. This can be +done with the Vimball utility. See |vimball|. + +It's good if you add a line to allow automatic updating. See |glvs-plugins|. + +============================================================================== + +Next chapter: |usr_42.txt| Add new menus + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/en/usr_42.txt b/en/usr_42.txt new file mode 100644 index 000000000..1d16112aa --- /dev/null +++ b/en/usr_42.txt @@ -0,0 +1,365 @@ +*usr_42.txt* For Vim version 7.4. Last change: 2008 May 05 + + VIM USER MANUAL - by Bram Moolenaar + + Add new menus + + +By now you know that Vim is very flexible. This includes the menus used in +the GUI. You can define your own menu entries to make certain commands easily +accessible. This is for mouse-happy users only. + +|42.1| Introduction +|42.2| Menu commands +|42.3| Various +|42.4| Toolbar and popup menus + + Next chapter: |usr_43.txt| Using filetypes + Previous chapter: |usr_41.txt| Write a Vim script +Table of contents: |usr_toc.txt| + +============================================================================== +*42.1* Introduction + +The menus that Vim uses are defined in the file "$VIMRUNTIME/menu.vim". If +you want to write your own menus, you might first want to look through that +file. + To define a menu item, use the ":menu" command. The basic form of this +command is as follows: > + + :menu {menu-item} {keys} + +The {menu-item} describes where on the menu to put the item. A typical +{menu-item} is "File.Save", which represents the item "Save" under the +"File" menu. A dot is used to separate the names. Example: > + + :menu File.Save :update<CR> + +The ":update" command writes the file when it was modified. + You can add another level: "Edit.Settings.Shiftwidth" defines a submenu +"Settings" under the "Edit" menu, with an item "Shiftwidth". You could use +even deeper levels. Don't use this too much, you need to move the mouse quite +a bit to use such an item. + The ":menu" command is very similar to the ":map" command: the left side +specifies how the item is triggered and the right hand side defines the +characters that are executed. {keys} are characters, they are used just like +you would have typed them. Thus in Insert mode, when {keys} is plain text, +that text is inserted. + + +ACCELERATORS + +The ampersand character (&) is used to indicate an accelerator. For instance, +you can use Alt-F to select "File" and S to select "Save". (The 'winaltkeys' +option may disable this though!). Therefore, the {menu-item} looks like +"&File.&Save". The accelerator characters will be underlined in the menu. + You must take care that each key is used only once in each menu. Otherwise +you will not know which of the two will actually be used. Vim doesn't warn +you for this. + + +PRIORITIES + +The actual definition of the File.Save menu item is as follows: > + + :menu 10.340 &File.&Save<Tab>:w :confirm w<CR> + +The number 10.340 is called the priority number. It is used by the editor to +decide where it places the menu item. The first number (10) indicates the +position on the menu bar. Lower numbered menus are positioned to the left, +higher numbers to the right. + These are the priorities used for the standard menus: + + 10 20 40 50 60 70 9999 + + +------------------------------------------------------------+ + | File Edit Tools Syntax Buffers Window Help | + +------------------------------------------------------------+ + +Notice that the Help menu is given a very high number, to make it appear on +the far right. + The second number (340) determines the location of the item within the +pull-down menu. Lower numbers go on top, higher number on the bottom. These +are the priorities in the File menu: + + +-----------------+ + 10.310 |Open... | + 10.320 |Split-Open... | + 10.325 |New | + 10.330 |Close | + 10.335 |---------------- | + 10.340 |Save | + 10.350 |Save As... | + 10.400 |---------------- | + 10.410 |Split Diff with | + 10.420 |Split Patched By | + 10.500 |---------------- | + 10.510 |Print | + 10.600 |---------------- | + 10.610 |Save-Exit | + 10.620 |Exit | + +-----------------+ + +Notice that there is room in between the numbers. This is where you can +insert your own items, if you really want to (it's often better to leave the +standard menus alone and add a new menu for your own items). + When you create a submenu, you can add another ".number" to the priority. +Thus each name in {menu-item} has its priority number. + + +SPECIAL CHARACTERS + +The {menu-item} in this example is "&File.&Save<Tab>:w". This brings up an +important point: {menu-item} must be one word. If you want to put a dot, +space or tabs in the name, you either use the <> notation (<Space> and <Tab>, +for instance) or use the backslash (\) escape. > + + :menu 10.305 &File.&Do\ It\.\.\. :exit<CR> + +In this example, the name of the menu item "Do It..." contains a space and the +command is ":exit<CR>". + +The <Tab> character in a menu name is used to separate the part that defines +the menu name from the part that gives a hint to the user. The part after the +<Tab> is displayed right aligned in the menu. In the File.Save menu the name +used is "&File.&Save<Tab>:w". Thus the menu name is "File.Save" and the hint +is ":w". + + +SEPARATORS + +The separator lines, used to group related menu items together, can be defined +by using a name that starts and ends in a '-'. For example "-sep-". When +using several separators the names must be different. Otherwise the names +don't matter. + The command from a separator will never be executed, but you have to define +one anyway. A single colon will do. Example: > + + :amenu 20.510 Edit.-sep3- : + +============================================================================== +*42.2* Menu commands + +You can define menu items that exist for only certain modes. This works just +like the variations on the ":map" command: + + :menu Normal, Visual and Operator-pending mode + :nmenu Normal mode + :vmenu Visual mode + :omenu Operator-pending mode + :menu! Insert and Command-line mode + :imenu Insert mode + :cmenu Command-line mode + :amenu All modes + +To avoid that the commands of a menu item are being mapped, use the command +":noremenu", ":nnoremenu", ":anoremenu", etc. + + +USING :AMENU + +The ":amenu" command is a bit different. It assumes that the {keys} you +give are to be executed in Normal mode. When Vim is in Visual or Insert mode +when the menu is used, Vim first has to go back to Normal mode. ":amenu" +inserts a CTRL-C or CTRL-O for you. For example, if you use this command: +> + :amenu 90.100 Mine.Find\ Word * + +Then the resulting menu commands will be: + + Normal mode: * + Visual mode: CTRL-C * + Operator-pending mode: CTRL-C * + Insert mode: CTRL-O * + Command-line mode: CTRL-C * + +When in Command-line mode the CTRL-C will abandon the command typed so far. +In Visual and Operator-pending mode CTRL-C will stop the mode. The CTRL-O in +Insert mode will execute the command and then return to Insert mode. + CTRL-O only works for one command. If you need to use two or more +commands, put them in a function and call that function. Example: > + + :amenu Mine.Next\ File :call <SID>NextFile()<CR> + :function <SID>NextFile() + : next + : 1/^Code + :endfunction + +This menu entry goes to the next file in the argument list with ":next". Then +it searches for the line that starts with "Code". + The <SID> before the function name is the script ID. This makes the +function local to the current Vim script file. This avoids problems when a +function with the same name is defined in another script file. See |<SID>|. + + +SILENT MENUS + +The menu executes the {keys} as if you typed them. For a ":" command this +means you will see the command being echoed on the command line. If it's a +long command, the hit-Enter prompt will appear. That can be very annoying! + To avoid this, make the menu silent. This is done with the <silent> +argument. For example, take the call to NextFile() in the previous example. +When you use this menu, you will see this on the command line: + + :call <SNR>34_NextFile() ~ + +To avoid this text on the command line, insert "<silent>" as the first +argument: > + + :amenu <silent> Mine.Next\ File :call <SID>NextFile()<CR> + +Don't use "<silent>" too often. It is not needed for short commands. If you +make a menu for someone else, being able the see the executed command will +give him a hint about what he could have typed, instead of using the mouse. + + +LISTING MENUS + +When a menu command is used without a {keys} part, it lists the already +defined menus. You can specify a {menu-item}, or part of it, to list specific +menus. Example: > + + :amenu + +This lists all menus. That's a long list! Better specify the name of a menu +to get a shorter list: > + + :amenu Edit + +This lists only the "Edit" menu items for all modes. To list only one +specific menu item for Insert mode: > + + :imenu Edit.Undo + +Take care that you type exactly the right name. Case matters here. But the +'&' for accelerators can be omitted. The <Tab> and what comes after it can be +left out as well. + + +DELETING MENUS + +To delete a menu, the same command is used as for listing, but with "menu" +changed to "unmenu". Thus ":menu" becomes, ":unmenu", ":nmenu" becomes +":nunmenu", etc. To delete the "Tools.Make" item for Insert mode: > + + :iunmenu Tools.Make + +You can delete a whole menu, with all its items, by using the menu name. +Example: > + + :aunmenu Syntax + +This deletes the Syntax menu and all the items in it. + +============================================================================== +*42.3* Various + +You can change the appearance of the menus with flags in 'guioptions'. In the +default value they are all included, except "M". You can remove a flag with a +command like: > + + :set guioptions-=m +< + m When removed the menubar is not displayed. + + M When added the default menus are not loaded. + + g When removed the inactive menu items are not made grey + but are completely removed. (Does not work on all + systems.) + + t When removed the tearoff feature is not enabled. + +The dotted line at the top of a menu is not a separator line. When you select +this item, the menu is "teared-off": It is displayed in a separate window. +This is called a tearoff menu. This is useful when you use the same menu +often. + +For translating menu items, see |:menutrans|. + +Since the mouse has to be used to select a menu item, it is a good idea to use +the ":browse" command for selecting a file. And ":confirm" to get a dialog +instead of an error message, e.g., when the current buffer contains changes. +These two can be combined: > + + :amenu File.Open :browse confirm edit<CR> + +The ":browse" makes a file browser appear to select the file to edit. The +":confirm" will pop up a dialog when the current buffer has changes. You can +then select to save the changes, throw them away or cancel the command. + For more complicated items, the confirm() and inputdialog() functions can +be used. The default menus contain a few examples. + +============================================================================== +*42.4* Toolbar and popup menus + +There are two special menus: ToolBar and PopUp. Items that start with these +names do not appear in the normal menu bar. + + +TOOLBAR + +The toolbar appears only when the "T" flag is included in the 'guioptions' +option. + The toolbar uses icons rather than text to represent the command. For +example, the {menu-item} named "ToolBar.New" causes the "New" icon to appear +on the toolbar. + The Vim editor has 28 built-in icons. You can find a table here: +|builtin-tools|. Most of them are used in the default toolbar. You can +redefine what these items do (after the default menus are setup). + You can add another bitmap for a toolbar item. Or define a new toolbar +item with a bitmap. For example, define a new toolbar item with: > + + :tmenu ToolBar.Compile Compile the current file + :amenu ToolBar.Compile :!cc %:S -o %:r:S<CR> + +Now you need to create the icon. For MS-Windows it must be in bitmap format, +with the name "Compile.bmp". For Unix XPM format is used, the file name is +"Compile.xpm". The size must be 18 by 18 pixels. On MS-Windows other sizes +can be used as well, but it will look ugly. + Put the bitmap in the directory "bitmaps" in one of the directories from +'runtimepath'. E.g., for Unix "~/.vim/bitmaps/Compile.xpm". + +You can define tooltips for the items in the toolbar. A tooltip is a short +text that explains what a toolbar item will do. For example "Open file". It +appears when the mouse pointer is on the item, without moving for a moment. +This is very useful if the meaning of the picture isn't that obvious. +Example: > + + :tmenu ToolBar.Make Run make in the current directory +< + Note: + Pay attention to the case used. "Toolbar" and "toolbar" are different + from "ToolBar"! + +To remove a tooltip, use the |:tunmenu| command. + +The 'toolbar' option can be used to display text instead of a bitmap, or both +text and a bitmap. Most people use just the bitmap, since the text takes +quite a bit of space. + + +POPUP MENU + +The popup menu pops up where the mouse pointer is. On MS-Windows you activate +it by clicking the right mouse button. Then you can select an item with the +left mouse button. On Unix the popup menu is used by pressing and holding the +right mouse button. + The popup menu only appears when the 'mousemodel' has been set to "popup" +or "popup_setpos". The difference between the two is that "popup_setpos" +moves the cursor to the mouse pointer position. When clicking inside a +selection, the selection will be used unmodified. When there is a selection +but you click outside of it, the selection is removed. + There is a separate popup menu for each mode. Thus there are never grey +items like in the normal menus. + +What is the meaning of life, the universe and everything? *42* +Douglas Adams, the only person who knew what this question really was about is +now dead, unfortunately. So now you might wonder what the meaning of death +is... + +============================================================================== + +Next chapter: |usr_43.txt| Using filetypes + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/en/usr_43.txt b/en/usr_43.txt new file mode 100644 index 000000000..8f0820fbf --- /dev/null +++ b/en/usr_43.txt @@ -0,0 +1,179 @@ +*usr_43.txt* For Vim version 7.4. Last change: 2015 Oct 23 + + VIM USER MANUAL - by Bram Moolenaar + + Using filetypes + + +When you are editing a file of a certain type, for example a C program or a +shell script, you often use the same option settings and mappings. You +quickly get tired of manually setting these each time. This chapter explains +how to do it automatically. + +|43.1| Plugins for a filetype +|43.2| Adding a filetype + + Next chapter: |usr_44.txt| Your own syntax highlighted + Previous chapter: |usr_42.txt| Add new menus +Table of contents: |usr_toc.txt| + +============================================================================== +*43.1* Plugins for a filetype *filetype-plugin* + +How to start using filetype plugins has already been discussed here: +|add-filetype-plugin|. But you probably are not satisfied with the default +settings, because they have been kept minimal. Suppose that for C files you +want to set the 'softtabstop' option to 4 and define a mapping to insert a +three-line comment. You do this with only two steps: + + *your-runtime-dir* +1. Create your own runtime directory. On Unix this usually is "~/.vim". In + this directory create the "ftplugin" directory: > + + mkdir ~/.vim + mkdir ~/.vim/ftplugin +< + When you are not on Unix, check the value of the 'runtimepath' option to + see where Vim will look for the "ftplugin" directory: > + + set runtimepath + +< You would normally use the first directory name (before the first comma). + You might want to prepend a directory name to the 'runtimepath' option in + your |vimrc| file if you don't like the default value. + +2. Create the file "~/.vim/ftplugin/c.vim", with the contents: > + + setlocal softtabstop=4 + noremap <buffer> <LocalLeader>c o/**************<CR><CR>/<Esc> + let b:undo_ftplugin = "setl softtabstop< | unmap <buffer> <LocalLeader>c" + +Try editing a C file. You should notice that the 'softtabstop' option is set +to 4. But when you edit another file it's reset to the default zero. That is +because the ":setlocal" command was used. This sets the 'softtabstop' option +only locally to the buffer. As soon as you edit another buffer, it will be +set to the value set for that buffer. For a new buffer it will get the +default value or the value from the last ":set" command. + +Likewise, the mapping for "\c" will disappear when editing another buffer. +The ":map <buffer>" command creates a mapping that is local to the current +buffer. This works with any mapping command: ":map!", ":vmap", etc. The +|<LocalLeader>| in the mapping is replaced with the value of the +"maplocalleader" variable. + +The line to set b:undo_ftplugin is for when the filetype is set to another +value. In that case you will want to undo your preferences. The +b:undo_ftplugin variable is executed as a command. Watch out for characters +with a special meaning inside a string, such as a backslash. + +You can find examples for filetype plugins in this directory: > + + $VIMRUNTIME/ftplugin/ + +More details about writing a filetype plugin can be found here: +|write-plugin|. + +============================================================================== +*43.2* Adding a filetype + +If you are using a type of file that is not recognized by Vim, this is how to +get it recognized. You need a runtime directory of your own. See +|your-runtime-dir| above. + +Create a file "filetype.vim" which contains an autocommand for your filetype. +(Autocommands were explained in section |40.3|.) Example: > + + augroup filetypedetect + au BufNewFile,BufRead *.xyz setf xyz + augroup END + +This will recognize all files that end in ".xyz" as the "xyz" filetype. The +":augroup" commands put this autocommand in the "filetypedetect" group. This +allows removing all autocommands for filetype detection when doing ":filetype +off". The "setf" command will set the 'filetype' option to its argument, +unless it was set already. This will make sure that 'filetype' isn't set +twice. + +You can use many different patterns to match the name of your file. Directory +names can also be included. See |autocmd-patterns|. For example, the files +under "/usr/share/scripts/" are all "ruby" files, but don't have the expected +file name extension. Adding this to the example above: > + + augroup filetypedetect + au BufNewFile,BufRead *.xyz setf xyz + au BufNewFile,BufRead /usr/share/scripts/* setf ruby + augroup END + +However, if you now edit a file /usr/share/scripts/README.txt, this is not a +ruby file. The danger of a pattern ending in "*" is that it quickly matches +too many files. To avoid trouble with this, put the filetype.vim file in +another directory, one that is at the end of 'runtimepath'. For Unix for +example, you could use "~/.vim/after/filetype.vim". + You now put the detection of text files in ~/.vim/filetype.vim: > + + augroup filetypedetect + au BufNewFile,BufRead *.txt setf text + augroup END + +That file is found in 'runtimepath' first. Then use this in +~/.vim/after/filetype.vim, which is found last: > + + augroup filetypedetect + au BufNewFile,BufRead /usr/share/scripts/* setf ruby + augroup END + +What will happen now is that Vim searches for "filetype.vim" files in each +directory in 'runtimepath'. First ~/.vim/filetype.vim is found. The +autocommand to catch *.txt files is defined there. Then Vim finds the +filetype.vim file in $VIMRUNTIME, which is halfway 'runtimepath'. Finally +~/.vim/after/filetype.vim is found and the autocommand for detecting ruby +files in /usr/share/scripts is added. + When you now edit /usr/share/scripts/README.txt, the autocommands are +checked in the order in which they were defined. The *.txt pattern matches, +thus "setf text" is executed to set the filetype to "text". The pattern for +ruby matches too, and the "setf ruby" is executed. But since 'filetype' was +already set to "text", nothing happens here. + When you edit the file /usr/share/scripts/foobar the same autocommands are +checked. Only the one for ruby matches and "setf ruby" sets 'filetype' to +ruby. + + +RECOGNIZING BY CONTENTS + +If your file cannot be recognized by its file name, you might be able to +recognize it by its contents. For example, many script files start with a +line like: + + #!/bin/xyz ~ + +To recognize this script create a file "scripts.vim" in your runtime directory +(same place where filetype.vim goes). It might look like this: > + + if did_filetype() + finish + endif + if getline(1) =~ '^#!.*[/\\]xyz\>' + setf xyz + endif + +The first check with did_filetype() is to avoid that you will check the +contents of files for which the filetype was already detected by the file +name. That avoids wasting time on checking the file when the "setf" command +won't do anything. + The scripts.vim file is sourced by an autocommand in the default +filetype.vim file. Therefore, the order of checks is: + + 1. filetype.vim files before $VIMRUNTIME in 'runtimepath' + 2. first part of $VIMRUNTIME/filetype.vim + 3. all scripts.vim files in 'runtimepath' + 4. remainder of $VIMRUNTIME/filetype.vim + 5. filetype.vim files after $VIMRUNTIME in 'runtimepath' + +If this is not sufficient for you, add an autocommand that matches all files +and sources a script or executes a function to check the contents of the file. + +============================================================================== + +Next chapter: |usr_44.txt| Your own syntax highlighted + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/en/usr_44.txt b/en/usr_44.txt new file mode 100644 index 000000000..48f661eb0 --- /dev/null +++ b/en/usr_44.txt @@ -0,0 +1,719 @@ +*usr_44.txt* For Vim version 7.4. Last change: 2008 Dec 28 + + VIM USER MANUAL - by Bram Moolenaar + + Your own syntax highlighted + + +Vim comes with highlighting for a couple of hundred different file types. If +the file you are editing isn't included, read this chapter to find out how to +get this type of file highlighted. Also see |:syn-define| in the reference +manual. + +|44.1| Basic syntax commands +|44.2| Keywords +|44.3| Matches +|44.4| Regions +|44.5| Nested items +|44.6| Following groups +|44.7| Other arguments +|44.8| Clusters +|44.9| Including another syntax file +|44.10| Synchronizing +|44.11| Installing a syntax file +|44.12| Portable syntax file layout + + Next chapter: |usr_45.txt| Select your language + Previous chapter: |usr_43.txt| Using filetypes +Table of contents: |usr_toc.txt| + +============================================================================== +*44.1* Basic syntax commands + +Using an existing syntax file to start with will save you a lot of time. Try +finding a syntax file in $VIMRUNTIME/syntax for a language that is similar. +These files will also show you the normal layout of a syntax file. To +understand it, you need to read the following. + +Let's start with the basic arguments. Before we start defining any new +syntax, we need to clear out any old definitions: > + + :syntax clear + +This isn't required in the final syntax file, but very useful when +experimenting. + +There are more simplifications in this chapter. If you are writing a syntax +file to be used by others, read all the way through the end to find out the +details. + + +LISTING DEFINED ITEMS + +To check which syntax items are currently defined, use this command: > + + :syntax + +You can use this to check which items have actually been defined. Quite +useful when you are experimenting with a new syntax file. It also shows the +colors used for each item, which helps to find out what is what. + To list the items in a specific syntax group use: > + + :syntax list {group-name} + +This also can be used to list clusters (explained in |44.8|). Just include +the @ in the name. + + +MATCHING CASE + +Some languages are not case sensitive, such as Pascal. Others, such as C, are +case sensitive. You need to tell which type you have with the following +commands: > + :syntax case match + :syntax case ignore + +The "match" argument means that Vim will match the case of syntax elements. +Therefore, "int" differs from "Int" and "INT". If the "ignore" argument is +used, the following are equivalent: "Procedure", "PROCEDURE" and "procedure". + The ":syntax case" commands can appear anywhere in a syntax file and affect +the syntax definitions that follow. In most cases, you have only one ":syntax +case" command in your syntax file; if you work with an unusual language that +contains both case-sensitive and non-case-sensitive elements, however, you can +scatter the ":syntax case" command throughout the file. + +============================================================================== +*44.2* Keywords + +The most basic syntax elements are keywords. To define a keyword, use the +following form: > + + :syntax keyword {group} {keyword} ... + +The {group} is the name of a syntax group. With the ":highlight" command you +can assign colors to a {group}. The {keyword} argument is an actual keyword. +Here are a few examples: > + + :syntax keyword xType int long char + :syntax keyword xStatement if then else endif + +This example uses the group names "xType" and "xStatement". By convention, +each group name is prefixed by the filetype for the language being defined. +This example defines syntax for the x language (eXample language without an +interesting name). In a syntax file for "csh" scripts the name "cshType" +would be used. Thus the prefix is equal to the value of 'filetype'. + These commands cause the words "int", "long" and "char" to be highlighted +one way and the words "if", "then", "else" and "endif" to be highlighted +another way. Now you need to connect the x group names to standard Vim +names. You do this with the following commands: > + + :highlight link xType Type + :highlight link xStatement Statement + +This tells Vim to highlight "xType" like "Type" and "xStatement" like +"Statement". See |group-name| for the standard names. + + +UNUSUAL KEYWORDS + +The characters used in a keyword must be in the 'iskeyword' option. If you +use another character, the word will never match. Vim doesn't give a warning +message for this. + The x language uses the '-' character in keywords. This is how it's done: +> + :setlocal iskeyword+=- + :syntax keyword xStatement when-not + +The ":setlocal" command is used to change 'iskeyword' only for the current +buffer. Still it does change the behavior of commands like "w" and "*". If +that is not wanted, don't define a keyword but use a match (explained in the +next section). + +The x language allows for abbreviations. For example, "next" can be +abbreviated to "n", "ne" or "nex". You can define them by using this command: +> + :syntax keyword xStatement n[ext] + +This doesn't match "nextone", keywords always match whole words only. + +============================================================================== +*44.3* Matches + +Consider defining something a bit more complex. You want to match ordinary +identifiers. To do this, you define a match syntax item. This one matches +any word consisting of only lowercase letters: > + + :syntax match xIdentifier /\<\l\+\>/ +< + Note: + Keywords overrule any other syntax item. Thus the keywords "if", + "then", etc., will be keywords, as defined with the ":syntax keyword" + commands above, even though they also match the pattern for + xIdentifier. + +The part at the end is a pattern, like it's used for searching. The // is +used to surround the pattern (like how it's done in a ":substitute" command). +You can use any other character, like a plus or a quote. + +Now define a match for a comment. In the x language it is anything from # to +the end of a line: > + + :syntax match xComment /#.*/ + +Since you can use any search pattern, you can highlight very complex things +with a match item. See |pattern| for help on search patterns. + +============================================================================== +*44.4* Regions + +In the example x language, strings are enclosed in double quotation marks ("). +To highlight strings you define a region. You need a region start (double +quote) and a region end (double quote). The definition is as follows: > + + :syntax region xString start=/"/ end=/"/ + +The "start" and "end" directives define the patterns used to find the start +and end of the region. But what about strings that look like this? + + "A string with a double quote (\") in it" ~ + +This creates a problem: The double quotation marks in the middle of the string +will end the region. You need to tell Vim to skip over any escaped double +quotes in the string. Do this with the skip keyword: > + + :syntax region xString start=/"/ skip=/\\"/ end=/"/ + +The double backslash matches a single backslash, since the backslash is a +special character in search patterns. + +When to use a region instead of a match? The main difference is that a match +item is a single pattern, which must match as a whole. A region starts as +soon as the "start" pattern matches. Whether the "end" pattern is found or +not doesn't matter. Thus when the item depends on the "end" pattern to match, +you cannot use a region. Otherwise, regions are often simpler to define. And +it is easier to use nested items, as is explained in the next section. + +============================================================================== +*44.5* Nested items + +Take a look at this comment: + + %Get input TODO: Skip white space ~ + +You want to highlight TODO in big yellow letters, even though it is in a +comment that is highlighted blue. To let Vim know about this, you define the +following syntax groups: > + + :syntax keyword xTodo TODO contained + :syntax match xComment /%.*/ contains=xTodo + +In the first line, the "contained" argument tells Vim that this keyword can +exist only inside another syntax item. The next line has "contains=xTodo". +This indicates that the xTodo syntax element is inside it. The result is that +the comment line as a whole is matched with "xComment" and made blue. The +word TODO inside it is matched by xTodo and highlighted yellow (highlighting +for xTodo was setup for this). + + +RECURSIVE NESTING + +The x language defines code blocks in curly braces. And a code block may +contain other code blocks. This can be defined this way: > + + :syntax region xBlock start=/{/ end=/}/ contains=xBlock + +Suppose you have this text: + + while i < b { ~ + if a { ~ + b = c; ~ + } ~ + } ~ + +First a xBlock starts at the { in the first line. In the second line another +{ is found. Since we are inside a xBlock item, and it contains itself, a +nested xBlock item will start here. Thus the "b = c" line is inside the +second level xBlock region. Then a } is found in the next line, which matches +with the end pattern of the region. This ends the nested xBlock. Because the +} is included in the nested region, it is hidden from the first xBlock region. +Then at the last } the first xBlock region ends. + + +KEEPING THE END + +Consider the following two syntax items: > + + :syntax region xComment start=/%/ end=/$/ contained + :syntax region xPreProc start=/#/ end=/$/ contains=xComment + +You define a comment as anything from % to the end of the line. A +preprocessor directive is anything from # to the end of the line. Because you +can have a comment on a preprocessor line, the preprocessor definition +includes a "contains=xComment" argument. Now look what happens with this +text: + + #define X = Y % Comment text ~ + int foo = 1; ~ + +What you see is that the second line is also highlighted as xPreProc. The +preprocessor directive should end at the end of the line. That is why +you have used "end=/$/". So what is going wrong? + The problem is the contained comment. The comment starts with % and ends +at the end of the line. After the comment ends, the preprocessor syntax +continues. This is after the end of the line has been seen, so the next +line is included as well. + To avoid this problem and to avoid a contained syntax item eating a needed +end of line, use the "keepend" argument. This takes care of +the double end-of-line matching: > + + :syntax region xComment start=/%/ end=/$/ contained + :syntax region xPreProc start=/#/ end=/$/ contains=xComment keepend + + +CONTAINING MANY ITEMS + +You can use the contains argument to specify that everything can be contained. +For example: > + + :syntax region xList start=/\[/ end=/\]/ contains=ALL + +All syntax items will be contained in this one. It also contains itself, but +not at the same position (that would cause an endless loop). + You can specify that some groups are not contained. Thus contain all +groups but the ones that are listed: +> + :syntax region xList start=/\[/ end=/\]/ contains=ALLBUT,xString + +With the "TOP" item you can include all items that don't have a "contained" +argument. "CONTAINED" is used to only include items with a "contained" +argument. See |:syn-contains| for the details. + +============================================================================== +*44.6* Following groups + +The x language has statements in this form: + + if (condition) then ~ + +You want to highlight the three items differently. But "(condition)" and +"then" might also appear in other places, where they get different +highlighting. This is how you can do this: > + + :syntax match xIf /if/ nextgroup=xIfCondition skipwhite + :syntax match xIfCondition /([^)]*)/ contained nextgroup=xThen skipwhite + :syntax match xThen /then/ contained + +The "nextgroup" argument specifies which item can come next. This is not +required. If none of the items that are specified are found, nothing happens. +For example, in this text: + + if not (condition) then ~ + +The "if" is matched by xIf. "not" doesn't match the specified nextgroup +xIfCondition, thus only the "if" is highlighted. + +The "skipwhite" argument tells Vim that white space (spaces and tabs) may +appear in between the items. Similar arguments are "skipnl", which allows a +line break in between the items, and "skipempty", which allows empty lines. +Notice that "skipnl" doesn't skip an empty line, something must match after +the line break. + +============================================================================== +*44.7* Other arguments + +MATCHGROUP + +When you define a region, the entire region is highlighted according to the +group name specified. To highlight the text enclosed in parentheses () with +the group xInside, for example, use the following command: > + + :syntax region xInside start=/(/ end=/)/ + +Suppose, that you want to highlight the parentheses differently. You can do +this with a lot of convoluted region statements, or you can use the +"matchgroup" argument. This tells Vim to highlight the start and end of a +region with a different highlight group (in this case, the xParen group): > + + :syntax region xInside matchgroup=xParen start=/(/ end=/)/ + +The "matchgroup" argument applies to the start or end match that comes after +it. In the previous example both start and end are highlighted with xParen. +To highlight the end with xParenEnd: > + + :syntax region xInside matchgroup=xParen start=/(/ + \ matchgroup=xParenEnd end=/)/ + +A side effect of using "matchgroup" is that contained items will not match in +the start or end of the region. The example for "transparent" uses this. + + +TRANSPARENT + +In a C language file you would like to highlight the () text after a "while" +differently from the () text after a "for". In both of these there can be +nested () items, which should be highlighted in the same way. You must make +sure the () highlighting stops at the matching ). This is one way to do this: +> + :syntax region cWhile matchgroup=cWhile start=/while\s*(/ end=/)/ + \ contains=cCondNest + :syntax region cFor matchgroup=cFor start=/for\s*(/ end=/)/ + \ contains=cCondNest + :syntax region cCondNest start=/(/ end=/)/ contained transparent + +Now you can give cWhile and cFor different highlighting. The cCondNest item +can appear in either of them, but take over the highlighting of the item it is +contained in. The "transparent" argument causes this. + Notice that the "matchgroup" argument has the same group as the item +itself. Why define it then? Well, the side effect of using a matchgroup is +that contained items are not found in the match with the start item then. +This avoids that the cCondNest group matches the ( just after the "while" or +"for". If this would happen, it would span the whole text until the matching +) and the region would continue after it. Now cCondNest only matches after +the match with the start pattern, thus after the first (. + + +OFFSETS + +Suppose you want to define a region for the text between ( and ) after an +"if". But you don't want to include the "if" or the ( and ). You can do this +by specifying offsets for the patterns. Example: > + + :syntax region xCond start=/if\s*(/ms=e+1 end=/)/me=s-1 + +The offset for the start pattern is "ms=e+1". "ms" stands for Match Start. +This defines an offset for the start of the match. Normally the match starts +where the pattern matches. "e+1" means that the match now starts at the end +of the pattern match, and then one character further. + The offset for the end pattern is "me=s-1". "me" stands for Match End. +"s-1" means the start of the pattern match and then one character back. The +result is that in this text: + + if (foo == bar) ~ + +Only the text "foo == bar" will be highlighted as xCond. + +More about offsets here: |:syn-pattern-offset|. + + +ONELINE + +The "oneline" argument indicates that the region does not cross a line +boundary. For example: > + + :syntax region xIfThen start=/if/ end=/then/ oneline + +This defines a region that starts at "if" and ends at "then". But if there is +no "then" after the "if", the region doesn't match. + + Note: + When using "oneline" the region doesn't start if the end pattern + doesn't match in the same line. Without "oneline" Vim does _not_ + check if there is a match for the end pattern. The region starts even + when the end pattern doesn't match in the rest of the file. + + +CONTINUATION LINES AND AVOIDING THEM + +Things now become a little more complex. Let's define a preprocessor line. +This starts with a # in the first column and continues until the end of the +line. A line that ends with \ makes the next line a continuation line. The +way you handle this is to allow the syntax item to contain a continuation +pattern: > + + :syntax region xPreProc start=/^#/ end=/$/ contains=xLineContinue + :syntax match xLineContinue "\\$" contained + +In this case, although xPreProc normally matches a single line, the group +contained in it (namely xLineContinue) lets it go on for more than one line. +For example, it would match both of these lines: + + #define SPAM spam spam spam \ ~ + bacon and spam ~ + +In this case, this is what you want. If it is not what you want, you can call +for the region to be on a single line by adding "excludenl" to the contained +pattern. For example, you want to highlight "end" in xPreProc, but only at +the end of the line. To avoid making the xPreProc continue on the next line, +like xLineContinue does, use "excludenl" like this: > + + :syntax region xPreProc start=/^#/ end=/$/ + \ contains=xLineContinue,xPreProcEnd + :syntax match xPreProcEnd excludenl /end$/ contained + :syntax match xLineContinue "\\$" contained + +"excludenl" must be placed before the pattern. Since "xLineContinue" doesn't +have "excludenl", a match with it will extend xPreProc to the next line as +before. + +============================================================================== +*44.8* Clusters + +One of the things you will notice as you start to write a syntax file is that +you wind up generating a lot of syntax groups. Vim enables you to define a +collection of syntax groups called a cluster. + Suppose you have a language that contains for loops, if statements, while +loops, and functions. Each of them contains the same syntax elements: numbers +and identifiers. You define them like this: > + + :syntax match xFor /^for.*/ contains=xNumber,xIdent + :syntax match xIf /^if.*/ contains=xNumber,xIdent + :syntax match xWhile /^while.*/ contains=xNumber,xIdent + +You have to repeat the same "contains=" every time. If you want to add +another contained item, you have to add it three times. Syntax clusters +simplify these definitions by enabling you to have one cluster stand for +several syntax groups. + To define a cluster for the two items that the three groups contain, use +the following command: > + + :syntax cluster xState contains=xNumber,xIdent + +Clusters are used inside other syntax items just like any syntax group. +Their names start with @. Thus, you can define the three groups like this: > + + :syntax match xFor /^for.*/ contains=@xState + :syntax match xIf /^if.*/ contains=@xState + :syntax match xWhile /^while.*/ contains=@xState + +You can add new group names to this cluster with the "add" argument: > + + :syntax cluster xState add=xString + +You can remove syntax groups from this list as well: > + + :syntax cluster xState remove=xNumber + +============================================================================== +*44.9* Including another syntax file + +The C++ language syntax is a superset of the C language. Because you do not +want to write two syntax files, you can have the C++ syntax file read in the +one for C by using the following command: > + + :runtime! syntax/c.vim + +The ":runtime!" command searches 'runtimepath' for all "syntax/c.vim" files. +This makes the C parts of the C++ syntax be defined like for C files. If you +have replaced the c.vim syntax file, or added items with an extra file, these +will be loaded as well. + After loading the C syntax items the specific C++ items can be defined. +For example, add keywords that are not used in C: > + + :syntax keyword cppStatement new delete this friend using + +This works just like in any other syntax file. + +Now consider the Perl language. A Perl script consists of two distinct parts: +a documentation section in POD format, and a program written in Perl itself. +The POD section starts with "=head" and ends with "=cut". + You want to define the POD syntax in one file, and use it from the Perl +syntax file. The ":syntax include" command reads in a syntax file and stores +the elements it defined in a syntax cluster. For Perl, the statements are as +follows: > + + :syntax include @Pod <sfile>:p:h/pod.vim + :syntax region perlPOD start=/^=head/ end=/^=cut/ contains=@Pod + +When "=head" is found in a Perl file, the perlPOD region starts. In this +region the @Pod cluster is contained. All the items defined as top-level +items in the pod.vim syntax files will match here. When "=cut" is found, the +region ends and we go back to the items defined in the Perl file. + The ":syntax include" command is clever enough to ignore a ":syntax clear" +command in the included file. And an argument such as "contains=ALL" will +only contain items defined in the included file, not in the file that includes +it. + The "<sfile>:p:h/" part uses the name of the current file (<sfile>), +expands it to a full path (:p) and then takes the head (:h). This results in +the directory name of the file. This causes the pod.vim file in the same +directory to be included. + +============================================================================== +*44.10* Synchronizing + +Compilers have it easy. They start at the beginning of a file and parse it +straight through. Vim does not have it so easy. It must start in the middle, +where the editing is being done. So how does it tell where it is? + The secret is the ":syntax sync" command. This tells Vim how to figure out +where it is. For example, the following command tells Vim to scan backward +for the beginning or end of a C-style comment and begin syntax coloring from +there: > + + :syntax sync ccomment + +You can tune this processing with some arguments. The "minlines" argument +tells Vim the minimum number of lines to look backward, and "maxlines" tells +the editor the maximum number of lines to scan. + For example, the following command tells Vim to look at least 10 lines +before the top of the screen: > + + :syntax sync ccomment minlines=10 maxlines=500 + +If it cannot figure out where it is in that space, it starts looking farther +and farther back until it figures out what to do. But it looks no farther +back than 500 lines. (A large "maxlines" slows down processing. A small one +might cause synchronization to fail.) + To make synchronizing go a bit faster, tell Vim which syntax items can be +skipped. Every match and region that only needs to be used when actually +displaying text can be given the "display" argument. + By default, the comment to be found will be colored as part of the Comment +syntax group. If you want to color things another way, you can specify a +different syntax group: > + + :syntax sync ccomment xAltComment + +If your programming language does not have C-style comments in it, you can try +another method of synchronization. The simplest way is to tell Vim to space +back a number of lines and try to figure out things from there. The following +command tells Vim to go back 150 lines and start parsing from there: > + + :syntax sync minlines=150 + +A large "minlines" value can make Vim slower, especially when scrolling +backwards in the file. + Finally, you can specify a syntax group to look for by using this command: +> + :syntax sync match {sync-group-name} + \ grouphere {group-name} {pattern} + +This tells Vim that when it sees {pattern} the syntax group named {group-name} +begins just after the pattern given. The {sync-group-name} is used to give a +name to this synchronization specification. For example, the sh scripting +language begins an if statement with "if" and ends it with "fi": + + if [ --f file.txt ] ; then ~ + echo "File exists" ~ + fi ~ + +To define a "grouphere" directive for this syntax, you use the following +command: > + + :syntax sync match shIfSync grouphere shIf "\<if\>" + +The "groupthere" argument tells Vim that the pattern ends a group. For +example, the end of the if/fi group is as follows: > + + :syntax sync match shIfSync groupthere NONE "\<fi\>" + +In this example, the NONE tells Vim that you are not in any special syntax +region. In particular, you are not inside an if block. + +You also can define matches and regions that are with no "grouphere" or +"groupthere" arguments. These groups are for syntax groups skipped during +synchronization. For example, the following skips over anything inside {}, +even if it would normally match another synchronization method: > + + :syntax sync match xSpecial /{.*}/ + +More about synchronizing in the reference manual: |:syn-sync|. + +============================================================================== +*44.11* Installing a syntax file + +When your new syntax file is ready to be used, drop it in a "syntax" directory +in 'runtimepath'. For Unix that would be "~/.vim/syntax". + The name of the syntax file must be equal to the file type, with ".vim" +added. Thus for the x language, the full path of the file would be: + + ~/.vim/syntax/x.vim ~ + +You must also make the file type be recognized. See |43.2|. + +If your file works well, you might want to make it available to other Vim +users. First read the next section to make sure your file works well for +others. Then e-mail it to the Vim maintainer: <maintainer@vim.org>. Also +explain how the filetype can be detected. With a bit of luck your file will +be included in the next Vim version! + + +ADDING TO AN EXISTING SYNTAX FILE + +We were assuming you were adding a completely new syntax file. When an existing +syntax file works, but is missing some items, you can add items in a separate +file. That avoids changing the distributed syntax file, which will be lost +when installing a new version of Vim. + Write syntax commands in your file, possibly using group names from the +existing syntax. For example, to add new variable types to the C syntax file: +> + :syntax keyword cType off_t uint + +Write the file with the same name as the original syntax file. In this case +"c.vim". Place it in a directory near the end of 'runtimepath'. This makes +it loaded after the original syntax file. For Unix this would be: + + ~/.vim/after/syntax/c.vim ~ + +============================================================================== +*44.12* Portable syntax file layout + +Wouldn't it be nice if all Vim users exchange syntax files? To make this +possible, the syntax file must follow a few guidelines. + +Start with a header that explains what the syntax file is for, who maintains +it and when it was last updated. Don't include too much information about +changes history, not many people will read it. Example: > + + " Vim syntax file + " Language: C + " Maintainer: Bram Moolenaar <Bram@vim.org> + " Last Change: 2001 Jun 18 + " Remark: Included by the C++ syntax. + +Use the same layout as the other syntax files. Using an existing syntax file +as an example will save you a lot of time. + +Choose a good, descriptive name for your syntax file. Use lowercase letters +and digits. Don't make it too long, it is used in many places: The name of +the syntax file "name.vim", 'filetype', b:current_syntax and the start of each +syntax group (nameType, nameStatement, nameString, etc). + +Start with a check for "b:current_syntax". If it is defined, some other +syntax file, earlier in 'runtimepath' was already loaded: > + + if exists("b:current_syntax") + finish + endif + +To be compatible with Vim 5.8 use: > + + if version < 600 + syntax clear + elseif exists("b:current_syntax") + finish + endif + +Set "b:current_syntax" to the name of the syntax at the end. Don't forget +that included files do this too, you might have to reset "b:current_syntax" if +you include two files. + +If you want your syntax file to work with Vim 5.x, add a check for v:version. +See yacc.vim for an example. + +Do not include anything that is a user preference. Don't set 'tabstop', +'expandtab', etc. These belong in a filetype plugin. + +Do not include mappings or abbreviations. Only include setting 'iskeyword' if +it is really necessary for recognizing keywords. + +To allow users select their own preferred colors, make a different group name +for every kind of highlighted item. Then link each of them to one of the +standard highlight groups. That will make it work with every color scheme. +If you select specific colors it will look bad with some color schemes. And +don't forget that some people use a different background color, or have only +eight colors available. + +For the linking use "hi def link", so that the user can select different +highlighting before your syntax file is loaded. Example: > + + hi def link nameString String + hi def link nameNumber Number + hi def link nameCommand Statement + ... etc ... + +Add the "display" argument to items that are not used when syncing, to speed +up scrolling backwards and CTRL-L. + +============================================================================== + +Next chapter: |usr_45.txt| Select your language + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/en/usr_45.txt b/en/usr_45.txt new file mode 100644 index 000000000..828ea6fe2 --- /dev/null +++ b/en/usr_45.txt @@ -0,0 +1,419 @@ +*usr_45.txt* For Vim version 7.4. Last change: 2008 Nov 15 + + VIM USER MANUAL - by Bram Moolenaar + + Select your language + + +The messages in Vim can be given in several languages. This chapter explains +how to change which one is used. Also, the different ways to work with files +in various languages is explained. + +|45.1| Language for Messages +|45.2| Language for Menus +|45.3| Using another encoding +|45.4| Editing files with a different encoding +|45.5| Entering language text + + Next chapter: |usr_90.txt| Installing Vim + Previous chapter: |usr_44.txt| Your own syntax highlighted +Table of contents: |usr_toc.txt| + +============================================================================== +*45.1* Language for Messages + +When you start Vim, it checks the environment to find out what language you +are using. Mostly this should work fine, and you get the messages in your +language (if they are available). To see what the current language is, use +this command: > + + :language + +If it replies with "C", this means the default is being used, which is +English. + + Note: + Using different languages only works when Vim was compiled to handle + it. To find out if it works, use the ":version" command and check the + output for "+gettext" and "+multi_lang". If they are there, you are + OK. If you see "-gettext" or "-multi_lang" you will have to find + another Vim. + +What if you would like your messages in a different language? There are +several ways. Which one you should use depends on the capabilities of your +system. + The first way is to set the environment to the desired language before +starting Vim. Example for Unix: > + + env LANG=de_DE.ISO_8859-1 vim + +This only works if the language is available on your system. The advantage is +that all the GUI messages and things in libraries will use the right language +as well. A disadvantage is that you must do this before starting Vim. If you +want to change language while Vim is running, you can use the second method: > + + :language fr_FR.ISO_8859-1 + +This way you can try out several names for your language. You will get an +error message when it's not supported on your system. You don't get an error +when translated messages are not available. Vim will silently fall back to +using English. + To find out which languages are supported on your system, find the +directory where they are listed. On my system it is "/usr/share/locale". On +some systems it's in "/usr/lib/locale". The manual page for "setlocale" +should give you a hint where it is found on your system. + Be careful to type the name exactly as it should be. Upper and lowercase +matter, and the '-' and '_' characters are easily confused. + +You can also set the language separately for messages, edited text and the +time format. See |:language|. + + +DO-IT-YOURSELF MESSAGE TRANSLATION + +If translated messages are not available for your language, you could write +them yourself. To do this, get the source code for Vim and the GNU gettext +package. After unpacking the sources, instructions can be found in the +directory src/po/README.txt. + It's not too difficult to do the translation. You don't need to be a +programmer. You must know both English and the language you are translating +to, of course. + When you are satisfied with the translation, consider making it available +to others. Upload it at vim-online (http://vim.sf.net) or e-mail it to +the Vim maintainer <maintainer@vim.org>. Or both. + +============================================================================== +*45.2* Language for Menus + +The default menus are in English. To be able to use your local language, they +must be translated. Normally this is automatically done for you if the +environment is set for your language, just like with messages. You don't need +to do anything extra for this. But it only works if translations for the +language are available. + Suppose you are in Germany, with the language set to German, but prefer to +use "File" instead of "Datei". You can switch back to using the English menus +this way: > + + :set langmenu=none + +It is also possible to specify a language: > + + :set langmenu=nl_NL.ISO_8859-1 + +Like above, differences between "-" and "_" matter. However, upper/lowercase +differences are ignored here. + The 'langmenu' option must be set before the menus are loaded. Once the +menus have been defined changing 'langmenu' has no direct effect. Therefore, +put the command to set 'langmenu' in your vimrc file. + If you really want to switch menu language while running Vim, you can do it +this way: > + + :source $VIMRUNTIME/delmenu.vim + :set langmenu=de_DE.ISO_8859-1 + :source $VIMRUNTIME/menu.vim + +There is one drawback: All menus that you defined yourself will be gone. You +will need to redefine them as well. + + +DO-IT-YOURSELF MENU TRANSLATION + +To see which menu translations are available, look in this directory: + + $VIMRUNTIME/lang ~ + +The files are called menu_{language}.vim. If you don't see the language you +want to use, you can do your own translations. The simplest way to do this is +by copying one of the existing language files, and change it. + First find out the name of your language with the ":language" command. Use +this name, but with all letters made lowercase. Then copy the file to your +own runtime directory, as found early in 'runtimepath'. For example, for Unix +you would do: > + + :!cp $VIMRUNTIME/lang/menu_ko_kr.euckr.vim ~/.vim/lang/menu_nl_be.iso_8859-1.vim + +You will find hints for the translation in "$VIMRUNTIME/lang/README.txt". + +============================================================================== +*45.3* Using another encoding + +Vim guesses that the files you are going to edit are encoded for your +language. For many European languages this is "latin1". Then each byte is +one character. That means there are 256 different characters possible. For +Asian languages this is not sufficient. These mostly use a double-byte +encoding, providing for over ten thousand possible characters. This still +isn't enough when a text is to contain several different languages. This is +where Unicode comes in. It was designed to include all characters used in +commonly used languages. This is the "Super encoding that replaces all +others". But it isn't used that much yet. + Fortunately, Vim supports these three kinds of encodings. And, with some +restrictions, you can use them even when your environment uses another +language than the text. + Nevertheless, when you only edit files that are in the encoding of your +language, the default should work fine and you don't need to do anything. The +following is only relevant when you want to edit different languages. + + Note: + Using different encodings only works when Vim was compiled to handle + it. To find out if it works, use the ":version" command and check the + output for "+multi_byte". If it's there, you are OK. If you see + "-multi_byte" you will have to find another Vim. + + +USING UNICODE IN THE GUI + +The nice thing about Unicode is that other encodings can be converted to it +and back without losing information. When you make Vim use Unicode +internally, you will be able to edit files in any encoding. + Unfortunately, the number of systems supporting Unicode is still limited. +Thus it's unlikely that your language uses it. You need to tell Vim you want +to use Unicode, and how to handle interfacing with the rest of the system. + Let's start with the GUI version of Vim, which is able to display Unicode +characters. This should work: > + + :set encoding=utf-8 + :set guifont=-misc-fixed-medium-r-normal--18-120-100-100-c-90-iso10646-1 + +The 'encoding' option tells Vim the encoding of the characters that you use. +This applies to the text in buffers (files you are editing), registers, Vim +script files, etc. You can regard 'encoding' as the setting for the internals +of Vim. + This example assumes you have this font on your system. The name in the +example is for the X Window System. This font is in a package that is used to +enhance xterm with Unicode support. If you don't have this font, you might +find it here: + + http://www.cl.cam.ac.uk/~mgk25/download/ucs-fonts.tar.gz ~ + +For MS-Windows, some fonts have a limited number of Unicode characters. Try +using the "Courier New" font. You can use the Edit/Select Font... menu to +select and try out the fonts available. Only fixed-width fonts can be used +though. Example: > + + :set guifont=courier_new:h12 + +If it doesn't work well, try getting a fontpack. If Microsoft didn't move it, +you can find it here: + + http://www.microsoft.com/typography/fonts/default.aspx ~ + +Now you have told Vim to use Unicode internally and display text with a +Unicode font. Typed characters still arrive in the encoding of your original +language. This requires converting them to Unicode. Tell Vim the language +from which to convert with the 'termencoding' option. You can do it like +this: > + + :let &termencoding = &encoding + :set encoding=utf-8 + +This assigns the old value of 'encoding' to 'termencoding' before setting +'encoding' to utf-8. You will have to try out if this really works for your +setup. It should work especially well when using an input method for an Asian +language, and you want to edit Unicode text. + + +USING UNICODE IN A UNICODE TERMINAL + +There are terminals that support Unicode directly. The standard xterm that +comes with XFree86 is one of them. Let's use that as an example. + First of all, the xterm must have been compiled with Unicode support. See +|UTF8-xterm| how to check that and how to compile it when needed. + Start the xterm with the "-u8" argument. You might also need so specify a +font. Example: > + + xterm -u8 -fn -misc-fixed-medium-r-normal--18-120-100-100-c-90-iso10646-1 + +Now you can run Vim inside this terminal. Set 'encoding' to "utf-8" as +before. That's all. + + +USING UNICODE IN AN ORDINARY TERMINAL + +Suppose you want to work with Unicode files, but don't have a terminal with +Unicode support. You can do this with Vim, although characters that are not +supported by the terminal will not be displayed. The layout of the text +will be preserved. > + + :let &termencoding = &encoding + :set encoding=utf-8 + +This is the same as what was used for the GUI. But it works differently: Vim +will convert the displayed text before sending it to the terminal. That +avoids that the display is messed up with strange characters. + For this to work the conversion between 'termencoding' and 'encoding' must +be possible. Vim will convert from latin1 to Unicode, thus that always works. +For other conversions the |+iconv| feature is required. + Try editing a file with Unicode characters in it. You will notice that Vim +will put a question mark (or underscore or some other character) in places +where a character should be that the terminal can't display. Move the cursor +to a question mark and use this command: > + + ga + +Vim will display a line with the code of the character. This gives you a hint +about what character it is. You can look it up in a Unicode table. You could +actually view a file that way, if you have lots of time at hand. + + Note: + Since 'encoding' is used for all text inside Vim, changing it makes + all non-ASCII text invalid. You will notice this when using registers + and the 'viminfo' file (e.g., a remembered search pattern). It's + recommended to set 'encoding' in your vimrc file, and leave it alone. + +============================================================================== +*45.4* Editing files with a different encoding + +Suppose you have setup Vim to use Unicode, and you want to edit a file that is +in 16-bit Unicode. Sounds simple, right? Well, Vim actually uses utf-8 +encoding internally, thus the 16-bit encoding must be converted, since there +is a difference between the character set (Unicode) and the encoding (utf-8 or +16-bit). + Vim will try to detect what kind of file you are editing. It uses the +encoding names in the 'fileencodings' option. When using Unicode, the default +value is: "ucs-bom,utf-8,latin1". This means that Vim checks the file to see +if it's one of these encodings: + + ucs-bom File must start with a Byte Order Mark (BOM). This + allows detection of 16-bit, 32-bit and utf-8 Unicode + encodings. + utf-8 utf-8 Unicode. This is rejected when a sequence of + bytes is illegal in utf-8. + latin1 The good old 8-bit encoding. Always works. + +When you start editing that 16-bit Unicode file, and it has a BOM, Vim will +detect this and convert the file to utf-8 when reading it. The 'fileencoding' +option (without s at the end) is set to the detected value. In this case it +is "utf-16le". That means it's Unicode, 16-bit and little-endian. This +file format is common on MS-Windows (e.g., for registry files). + When writing the file, Vim will compare 'fileencoding' with 'encoding'. If +they are different, the text will be converted. + An empty value for 'fileencoding' means that no conversion is to be done. +Thus the text is assumed to be encoded with 'encoding'. + +If the default 'fileencodings' value is not good for you, set it to the +encodings you want Vim to try. Only when a value is found to be invalid will +the next one be used. Putting "latin1" first doesn't work, because it is +never illegal. An example, to fall back to Japanese when the file doesn't +have a BOM and isn't utf-8: > + + :set fileencodings=ucs-bom,utf-8,sjis + +See |encoding-values| for suggested values. Other values may work as well. +This depends on the conversion available. + + +FORCING AN ENCODING + +If the automatic detection doesn't work you must tell Vim what encoding the +file is. Example: > + + :edit ++enc=koi8-r russian.txt + +The "++enc" part specifies the name of the encoding to be used for this file +only. Vim will convert the file from the specified encoding, Russian in this +example, to 'encoding'. 'fileencoding' will also be set to the specified +encoding, so that the reverse conversion can be done when writing the file. + The same argument can be used when writing the file. This way you can +actually use Vim to convert a file. Example: > + + :write ++enc=utf-8 russian.txt +< + Note: + Conversion may result in lost characters. Conversion from an encoding + to Unicode and back is mostly free of this problem, unless there are + illegal characters. Conversion from Unicode to other encodings often + loses information when there was more than one language in the file. + +============================================================================== +*45.5* Entering language text + +Computer keyboards don't have much more than a hundred keys. Some languages +have thousands of characters, Unicode has over hundred thousand. So how do +you type these characters? + First of all, when you don't use too many of the special characters, you +can use digraphs. This was already explained in |24.9|. + When you use a language that uses many more characters than keys on your +keyboard, you will want to use an Input Method (IM). This requires learning +the translation from typed keys to resulting character. When you need an IM +you probably already have one on your system. It should work with Vim like +with other programs. For details see |mbyte-XIM| for the X Window system and +|mbyte-IME| for MS-Windows. + + +KEYMAPS + +For some languages the character set is different from latin, but uses a +similar number of characters. It's possible to map keys to characters. Vim +uses keymaps for this. + Suppose you want to type Hebrew. You can load the keymap like this: > + + :set keymap=hebrew + +Vim will try to find a keymap file for you. This depends on the value of +'encoding'. If no matching file was found, you will get an error message. + +Now you can type Hebrew in Insert mode. In Normal mode, and when typing a ":" +command, Vim automatically switches to English. You can use this command to +switch between Hebrew and English: > + + CTRL-^ + +This only works in Insert mode and Command-line mode. In Normal mode it does +something completely different (jumps to alternate file). + The usage of the keymap is indicated in the mode message, if you have the +'showmode' option set. In the GUI Vim will indicate the usage of keymaps with +a different cursor color. + You can also change the usage of the keymap with the 'iminsert' and +'imsearch' options. + +To see the list of mappings, use this command: > + + :lmap + +To find out which keymap files are available, in the GUI you can use the +Edit/Keymap menu. Otherwise you can use this command: > + + :echo globpath(&rtp, "keymap/*.vim") + + +DO-IT-YOURSELF KEYMAPS + +You can create your own keymap file. It's not very difficult. Start with +a keymap file that is similar to the language you want to use. Copy it to the +"keymap" directory in your runtime directory. For example, for Unix, you +would use the directory "~/.vim/keymap". + The name of the keymap file must look like this: + + keymap/{name}.vim ~ +or + keymap/{name}_{encoding}.vim ~ + +{name} is the name of the keymap. Chose a name that is obvious, but different +from existing keymaps (unless you want to replace an existing keymap file). +{name} cannot contain an underscore. Optionally, add the encoding used after +an underscore. Examples: + + keymap/hebrew.vim ~ + keymap/hebrew_utf-8.vim ~ + +The contents of the file should be self-explanatory. Look at a few of the +keymaps that are distributed with Vim. For the details, see |mbyte-keymap|. + + +LAST RESORT + +If all other methods fail, you can enter any character with CTRL-V: + + encoding type range ~ + 8-bit CTRL-V 123 decimal 0-255 + 8-bit CTRL-V x a1 hexadecimal 00-ff + 16-bit CTRL-V u 013b hexadecimal 0000-ffff + 31-bit CTRL-V U 001303a4 hexadecimal 00000000-7fffffff + +Don't type the spaces. See |i_CTRL-V_digit| for the details. + +============================================================================== + +Next chapter: |usr_90.txt| Installing Vim + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/en/usr_90.txt b/en/usr_90.txt new file mode 100644 index 000000000..38e5886fa --- /dev/null +++ b/en/usr_90.txt @@ -0,0 +1,498 @@ +*usr_90.txt* For Vim version 7.4. Last change: 2008 Sep 10 + + VIM USER MANUAL - by Bram Moolenaar + + Installing Vim + + *install* +Before you can use Vim you have to install it. Depending on your system it's +simple or easy. This chapter gives a few hints and also explains how +upgrading to a new version is done. + +|90.1| Unix +|90.2| MS-Windows +|90.3| Upgrading +|90.4| Common installation issues +|90.5| Uninstalling Vim + + Previous chapter: |usr_45.txt| Select your language +Table of contents: |usr_toc.txt| + +============================================================================== +*90.1* Unix + +First you have to decide if you are going to install Vim system-wide or for a +single user. The installation is almost the same, but the directory where Vim +is installed in differs. + For a system-wide installation the base directory "/usr/local" is often +used. But this may be different for your system. Try finding out where other +packages are installed. + When installing for a single user, you can use your home directory as the +base. The files will be placed in subdirectories like "bin" and "shared/vim". + + +FROM A PACKAGE + +You can get precompiled binaries for many different UNIX systems. There is a +long list with links on this page: + + http://www.vim.org/binaries.html ~ + +Volunteers maintain the binaries, so they are often out of date. It is a +good idea to compile your own UNIX version from the source. Also, creating +the editor from the source allows you to control which features are compiled. +This does require a compiler though. + +If you have a Linux distribution, the "vi" program is probably a minimal +version of Vim. It doesn't do syntax highlighting, for example. Try finding +another Vim package in your distribution, or search on the web site. + + +FROM SOURCES + +To compile and install Vim, you will need the following: + + - A C compiler (GCC preferred) + - The GZIP program (you can get it from www.gnu.org) + - The Vim source and runtime archives + +To get the Vim archives, look in this file for a mirror near you, this should +provide the fastest download: + + ftp://ftp.vim.org/pub/vim/MIRRORS ~ + +Or use the home site ftp.vim.org, if you think it's fast enough. Go to the +"unix" directory and you'll find a list of files there. The version number is +embedded in the file name. You will want to get the most recent version. + You can get the files for Unix in two ways: One big archive that contains +everything, or four smaller ones that each fit on a floppy disk. For version +6.1 the single big one is called: + + vim-6.1.tar.bz2 ~ + +You need the bzip2 program to uncompress it. If you don't have it, get the +four smaller files, which can be uncompressed with gzip. For Vim 6.1 they are +called: + + vim-6.1-src1.tar.gz ~ + vim-6.1-src2.tar.gz ~ + vim-6.1-rt1.tar.gz ~ + vim-6.1-rt2.tar.gz ~ + + +COMPILING + +First create a top directory to work in, for example: > + + mkdir ~/vim + cd ~/vim + +Then unpack the archives there. If you have the one big archive, you unpack +it like this: > + + bzip2 -d -c path/vim-6.1.tar.bz2 | tar xf - + +Change "path" to where you have downloaded the file. > + + gzip -d -c path/vim-6.1-src1.tar.gz | tar xf - + gzip -d -c path/vim-6.1-src2.tar.gz | tar xf - + gzip -d -c path/vim-6.1-rt1.tar.gz | tar xf - + gzip -d -c path/vim-6.1-rt2.tar.gz | tar xf - + +If you are satisfied with getting the default features, and your environment +is setup properly, you should be able to compile Vim with just this: > + + cd vim61/src + make + +The make program will run configure and compile everything. Further on we +will explain how to compile with different features. + If there are errors while compiling, carefully look at the error messages. +There should be a hint about what went wrong. Hopefully you will be able to +correct it. You might have to disable some features to make Vim compile. +Look in the Makefile for specific hints for your system. + + +TESTING + +Now you can check if compiling worked OK: > + + make test + +This will run a sequence of test scripts to verify that Vim works as expected. +Vim will be started many times and all kinds of text and messages flash by. +If it is alright you will finally see: + + test results: ~ + ALL DONE ~ + +If you get "TEST FAILURE" some test failed. If there are one or two messages +about failed tests, Vim might still work, but not perfectly. If you see a lot +of error messages or Vim doesn't finish until the end, there must be something +wrong. Either try to find out yourself, or find someone who can solve it. +You could look in the |maillist-archive| for a solution. If everything else +fails, you could ask in the vim |maillist| if someone can help you. + + +INSTALLING + *install-home* +If you want to install in your home directory, edit the Makefile and search +for a line: + + #prefix = $(HOME) ~ + +Remove the # at the start of the line. + When installing for the whole system, Vim has most likely already selected +a good installation directory for you. You can also specify one, see below. +You need to become root for the following. + +To install Vim do: > + + make install + +That should move all the relevant files to the right place. Now you can try +running vim to verify that it works. Use two simple tests to check if Vim can +find its runtime files: > + + :help + :syntax enable + +If this doesn't work, use this command to check where Vim is looking for the +runtime files: > + + :echo $VIMRUNTIME + +You can also start Vim with the "-V" argument to see what happens during +startup: > + + vim -V + +Don't forget that the user manual assumes you Vim in a certain way. After +installing Vim, follow the instructions at |not-compatible| to make Vim work +as assumed in this manual. + + +SELECTING FEATURES + +Vim has many ways to select features. One of the simple ways is to edit the +Makefile. There are many directions and examples. Often you can enable or +disable a feature by uncommenting a line. + An alternative is to run "configure" separately. This allows you to +specify configuration options manually. The disadvantage is that you have to +figure out what exactly to type. + Some of the most interesting configure arguments follow. These can also be +enabled from the Makefile. + + --prefix={directory} Top directory where to install Vim. + + --with-features=tiny Compile with many features disabled. + --with-features=small Compile with some features disabled. + --with-features=big Compile with more features enabled. + --with-features=huge Compile with most features enabled. + See |+feature-list| for which feature + is enabled in which case. + + --enable-perlinterp Enable the Perl interface. There are + similar arguments for ruby, python and + tcl. + + --disable-gui Do not compile the GUI interface. + --without-x Do not compile X-windows features. + When both of these are used, Vim will + not connect to the X server, which + makes startup faster. + +To see the whole list use: > + + ./configure --help + +You can find a bit of explanation for each feature, and links for more +information here: |feature-list|. + For the adventurous, edit the file "feature.h". You can also change the +source code yourself! + +============================================================================== +*90.2* MS-Windows + +There are two ways to install the Vim program for Microsoft Windows. You can +uncompress several archives, or use a self-installing big archive. Most users +with fairly recent computers will prefer the second method. For the first +one, you will need: + + - An archive with binaries for Vim. + - The Vim runtime archive. + - A program to unpack the zip files. + +To get the Vim archives, look in this file for a mirror near you, this should +provide the fastest download: + + ftp://ftp.vim.org/pub/vim/MIRRORS ~ + +Or use the home site ftp.vim.org, if you think it's fast enough. Go to the +"pc" directory and you'll find a list of files there. The version number is +embedded in the file name. You will want to get the most recent version. +We will use "61" here, which is version 6.1. + + gvim61.exe The self-installing archive. + +This is all you need for the second method. Just launch the executable, and +follow the prompts. + +For the first method you must chose one of the binary archives. These are +available: + + gvim61.zip The normal MS-Windows GUI version. + gvim61ole.zip The MS-Windows GUI version with OLE support. + Uses more memory, supports interfacing with + other OLE applications. + vim61w32.zip 32 bit MS-Windows console version. For use in + a Win NT/2000/XP console. Does not work well + on Win 95/98. + vim61d32.zip 32 bit MS-DOS version. For use in the + Win 95/98 console window. + vim61d16.zip 16 bit MS-DOS version. Only for old systems. + Does not support long filenames. + +You only need one of them. Although you could install both a GUI and a +console version. You always need to get the archive with runtime files. + + vim61rt.zip The runtime files. + +Use your un-zip program to unpack the files. For example, using the "unzip" +program: > + + cd c:\ + unzip path\gvim61.zip + unzip path\vim61rt.zip + +This will unpack the files in the directory "c:\vim\vim61". If you already +have a "vim" directory somewhere, you will want to move to the directory just +above it. + Now change to the "vim\vim61" directory and run the install program: > + + install + +Carefully look through the messages and select the options you want to use. +If you finally select "do it" the install program will carry out the actions +you selected. + The install program doesn't move the runtime files. They remain where you +unpacked them. + +In case you are not satisfied with the features included in the supplied +binaries, you could try compiling Vim yourself. Get the source archive from +the same location as where the binaries are. You need a compiler for which a +makefile exists. Microsoft Visual C works, but is expensive. The Free +Borland command-line compiler 5.5 can be used, as well as the free MingW and +Cygwin compilers. Check the file src/INSTALLpc.txt for hints. + +============================================================================== +*90.3* Upgrading + +If you are running one version of Vim and want to install another, here is +what to do. + + +UNIX + +When you type "make install" the runtime files will be copied to a directory +which is specific for this version. Thus they will not overwrite a previous +version. This makes it possible to use two or more versions next to +each other. + The executable "vim" will overwrite an older version. If you don't care +about keeping the old version, running "make install" will work fine. You can +delete the old runtime files manually. Just delete the directory with the +version number in it and all files below it. Example: > + + rm -rf /usr/local/share/vim/vim58 + +There are normally no changed files below this directory. If you did change +the "filetype.vim" file, for example, you better merge the changes into the +new version before deleting it. + +If you are careful and want to try out the new version for a while before +switching to it, install the new version under another name. You need to +specify a configure argument. For example: > + + ./configure --with-vim-name=vim6 + +Before running "make install", you could use "make -n install" to check that +no valuable existing files are overwritten. + When you finally decide to switch to the new version, all you need to do is +to rename the binary to "vim". For example: > + + mv /usr/local/bin/vim6 /usr/local/bin/vim + + +MS-WINDOWS + +Upgrading is mostly equal to installing a new version. Just unpack the files +in the same place as the previous version. A new directory will be created, +e.g., "vim61", for the files of the new version. Your runtime files, vimrc +file, viminfo, etc. will be left alone. + If you want to run the new version next to the old one, you will have to do +some handwork. Don't run the install program, it will overwrite a few files +of the old version. Execute the new binaries by specifying the full path. +The program should be able to automatically find the runtime files for the +right version. However, this won't work if you set the $VIMRUNTIME variable +somewhere. + If you are satisfied with the upgrade, you can delete the files of the +previous version. See |90.5|. + +============================================================================== +*90.4* Common installation issues + +This section describes some of the common problems that occur when installing +Vim and suggests some solutions. It also contains answers to many +installation questions. + + +Q: I Do Not Have Root Privileges. How Do I Install Vim? (Unix) + +Use the following configuration command to install Vim in a directory called +$HOME/vim: > + + ./configure --prefix=$HOME + +This gives you a personal copy of Vim. You need to put $HOME/bin in your +path to execute the editor. Also see |install-home|. + + +Q: The Colors Are Not Right on My Screen. (Unix) + +Check your terminal settings by using the following command in a shell: > + + echo $TERM + +If the terminal type listed is not correct, fix it. For more hints, see +|06.2|. Another solution is to always use the GUI version of Vim, called +gvim. This avoids the need for a correct terminal setup. + + +Q: My Backspace And Delete Keys Don't Work Right + +The definition of what key sends what code is very unclear for backspace <BS> +and Delete <Del> keys. First of all, check your $TERM setting. If there is +nothing wrong with it, try this: > + + :set t_kb=^V<BS> + :set t_kD=^V<Del> + +In the first line you need to press CTRL-V and then hit the backspace key. +In the second line you need to press CTRL-V and then hit the Delete key. +You can put these lines in your vimrc file, see |05.1|. A disadvantage is +that it won't work when you use another terminal some day. Look here for +alternate solutions: |:fixdel|. + + +Q: I Am Using RedHat Linux. Can I Use the Vim That Comes with the System? + +By default RedHat installs a minimal version of Vim. Check your RPM packages +for something named "Vim-enhanced-version.rpm" and install that. + + +Q: How Do I Turn Syntax Coloring On? How do I make plugins work? + +Use the example vimrc script. You can find an explanation on how to use it +here: |not-compatible|. + +See chapter 6 for information about syntax highlighting: |usr_06.txt|. + + +Q: What Is a Good vimrc File to Use? + +See the www.vim.org Web site for several good examples. + + +Q: Where Do I Find a Good Vim Plugin? + +See the Vim-online site: http://vim.sf.net. Many users have uploaded useful +Vim scripts and plugins there. + + +Q: Where Do I Find More Tips? + +See the Vim-online site: http://vim.sf.net. There is an archive with hints +from Vim users. You might also want to search in the |maillist-archive|. + +============================================================================== +*90.5* Uninstalling Vim + +In the unlikely event you want to uninstall Vim completely, this is how you do +it. + + +UNIX + +When you installed Vim as a package, check your package manager to find out +how to remove the package again. + If you installed Vim from sources you can use this command: > + + make uninstall + +However, if you have deleted the original files or you used an archive that +someone supplied, you can't do this. Do delete the files manually, here is an +example for when "/usr/local" was used as the root: > + + rm -rf /usr/local/share/vim/vim61 + rm /usr/local/bin/eview + rm /usr/local/bin/evim + rm /usr/local/bin/ex + rm /usr/local/bin/gview + rm /usr/local/bin/gvim + rm /usr/local/bin/gvim + rm /usr/local/bin/gvimdiff + rm /usr/local/bin/rgview + rm /usr/local/bin/rgvim + rm /usr/local/bin/rview + rm /usr/local/bin/rvim + rm /usr/local/bin/rvim + rm /usr/local/bin/view + rm /usr/local/bin/vim + rm /usr/local/bin/vimdiff + rm /usr/local/bin/vimtutor + rm /usr/local/bin/xxd + rm /usr/local/man/man1/eview.1 + rm /usr/local/man/man1/evim.1 + rm /usr/local/man/man1/ex.1 + rm /usr/local/man/man1/gview.1 + rm /usr/local/man/man1/gvim.1 + rm /usr/local/man/man1/gvimdiff.1 + rm /usr/local/man/man1/rgview.1 + rm /usr/local/man/man1/rgvim.1 + rm /usr/local/man/man1/rview.1 + rm /usr/local/man/man1/rvim.1 + rm /usr/local/man/man1/view.1 + rm /usr/local/man/man1/vim.1 + rm /usr/local/man/man1/vimdiff.1 + rm /usr/local/man/man1/vimtutor.1 + rm /usr/local/man/man1/xxd.1 + + +MS-WINDOWS + +If you installed Vim with the self-installing archive you can run +the "uninstall-gui" program located in the same directory as the other Vim +programs, e.g. "c:\vim\vim61". You can also launch it from the Start menu if +installed the Vim entries there. This will remove most of the files, menu +entries and desktop shortcuts. Some files may remain however, as they need a +Windows restart before being deleted. + You will be given the option to remove the whole "vim" directory. It +probably contains your vimrc file and other runtime files that you created, so +be careful. + +Else, if you installed Vim with the zip archives, the preferred way is to use +the "uninstal" program (note the missing l at the end). You can find it in +the same directory as the "install" program, e.g., "c:\vim\vim61". This +should also work from the usual "install/remove software" page. + However, this only removes the registry entries for Vim. You have to +delete the files yourself. Simply select the directory "vim\vim61" and delete +it recursively. There should be no files there that you changed, but you +might want to check that first. + The "vim" directory probably contains your vimrc file and other runtime +files that you created. You might want to keep that. + +============================================================================== + +Table of contents: |usr_toc.txt| + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/en/usr_toc.txt b/en/usr_toc.txt new file mode 100644 index 000000000..d98a999aa --- /dev/null +++ b/en/usr_toc.txt @@ -0,0 +1,354 @@ +*usr_toc.txt* For Vim version 7.4. Last change: 2010 Jul 20 + + VIM USER MANUAL - by Bram Moolenaar + + Table Of Contents *user-manual* + +============================================================================== +Overview ~ + +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 + + +Reference manual +|reference_toc| More detailed information for all commands + +The user manual is available as a single, ready to print HTML and PDF file +here: + http://vimdoc.sf.net + +============================================================================== +Getting Started ~ + +Read this from start to end to learn the essential commands. + +|usr_01.txt| About the manuals + |01.1| Two manuals + |01.2| Vim installed + |01.3| Using the Vim tutor + |01.4| Copyright + +|usr_02.txt| The first steps in Vim + |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 + +|usr_03.txt| Moving around + |03.1| Word movement + |03.2| Moving to the start or end of a line + |03.3| Moving to a character + |03.4| Matching a paren + |03.5| Moving to a specific line + |03.6| Telling where you are + |03.7| Scrolling around + |03.8| Simple searches + |03.9| Simple search patterns + |03.10| Using marks + +|usr_04.txt| Making small changes + |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 + +|usr_05.txt| Set your settings + |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 + +|usr_06.txt| Using syntax highlighting + |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 + +|usr_07.txt| Editing more than one file + |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 + +|usr_08.txt| Splitting 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 + +|usr_09.txt| Using the GUI + |09.1| Parts of the GUI + |09.2| Using the mouse + |09.3| The clipboard + |09.4| Select mode + +|usr_10.txt| Making big changes + |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 + +|usr_11.txt| Recovering from a crash + |11.1| Basic recovery + |11.2| Where is the swap file? + |11.3| Crashed or not? + |11.4| Further reading + +|usr_12.txt| Clever tricks + |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 + +============================================================================== +Editing Effectively ~ + +Subjects that can be read independently. + +|usr_20.txt| Typing command-line commands quickly + |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 + +|usr_21.txt| Go away and come back + |21.1| Suspend and resume + |21.2| Executing shell commands + |21.3| Remembering information; viminfo + |21.4| Sessions + |21.5| Views + |21.6| Modelines + +|usr_22.txt| Finding the file to edit + |22.1| The file explorer + |22.2| The current directory + |22.3| Finding a file + |22.4| The buffer list + +|usr_23.txt| Editing other files + |23.1| DOS, Mac and Unix files + |23.2| Files on the internet + |23.3| Encryption + |23.4| Binary files + |23.5| Compressed files + +|usr_24.txt| Inserting quickly + |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 + +|usr_25.txt| Editing formatted text + |25.1| Breaking lines + |25.2| Aligning text + |25.3| Indents and tabs + |25.4| Dealing with long lines + |25.5| Editing tables + +|usr_26.txt| Repeating + |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 + +|usr_27.txt| Search commands and patterns + |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 + +|usr_28.txt| Folding + |28.1| What is folding? + |28.2| Manual folding + |28.3| Working with folds + |28.4| Saving and restoring folds + |28.5| Folding by indent + |28.6| Folding with markers + |28.7| Folding by syntax + |28.8| Folding by expression + |28.9| Folding unchanged lines + |28.10| Which fold method to use? + +|usr_29.txt| Moving through programs + |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 + +|usr_30.txt| Editing programs + |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 + +|usr_31.txt| Exploiting the GUI + |31.1| The file browser + |31.2| Confirmation + |31.3| Menu shortcuts + |31.4| Vim window position and size + |31.5| Various + +|usr_32.txt| The undo tree + |32.1| Undo up to a file write + |32.2| Numbering changes + |32.3| Jumping around the tree + |32.4| Time travelling + +============================================================================== +Tuning Vim ~ + +Make Vim work as you like it. + +|usr_40.txt| Make new commands + |40.1| Key mapping + |40.2| Defining command-line commands + |40.3| Autocommands + +|usr_41.txt| Write a Vim script + |41.1| Introduction + |41.2| Variables + |41.3| Expressions + |41.4| Conditionals + |41.5| Executing an expression + |41.6| Using functions + |41.7| Defining a function + |41.8| Lists and Dictionaries + |41.9| Exceptions + |41.10| Various remarks + |41.11| Writing a plugin + |41.12| Writing a filetype plugin + |41.13| Writing a compiler plugin + |41.14| Writing a plugin that loads quickly + |41.15| Writing library scripts + |41.16| Distributing Vim scripts + +|usr_42.txt| Add new menus + |42.1| Introduction + |42.2| Menu commands + |42.3| Various + |42.4| Toolbar and popup menus + +|usr_43.txt| Using filetypes + |43.1| Plugins for a filetype + |43.2| Adding a filetype + +|usr_44.txt| Your own syntax highlighted + |44.1| Basic syntax commands + |44.2| Keywords + |44.3| Matches + |44.4| Regions + |44.5| Nested items + |44.6| Following groups + |44.7| Other arguments + |44.8| Clusters + |44.9| Including another syntax file + |44.10| Synchronizing + |44.11| Installing a syntax file + |44.12| Portable syntax file layout + +|usr_45.txt| Select your language + |45.1| Language for Messages + |45.2| Language for Menus + |45.3| Using another encoding + |45.4| Editing files with a different encoding + |45.5| Entering language text + +============================================================================== +Making Vim Run ~ + +Before you can use Vim. + +|usr_90.txt| Installing Vim + |90.1| Unix + |90.2| MS-Windows + |90.3| Upgrading + |90.4| Common installation issues + |90.5| Uninstalling Vim + +============================================================================== + +Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: diff --git a/en/various.txt b/en/various.txt new file mode 100644 index 000000000..d338d9b96 --- /dev/null +++ b/en/various.txt @@ -0,0 +1,678 @@ +*various.txt* For Vim version 7.4. Last change: 2016 Jan 27 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Various commands *various* + +1. Various commands |various-cmds| +2. Using Vim like less or more |less| + +============================================================================== +1. Various commands *various-cmds* + + *CTRL-L* +CTRL-L Clear and redraw the screen. The redraw may happen + later, after processing typeahead. + + *:redr* *:redraw* +:redr[aw][!] Redraw the screen right now. When ! is included it is + cleared first. + Useful to update the screen halfway executing a script + or function. Also when halfway a mapping and + 'lazyredraw' is set. + + *:redraws* *:redrawstatus* +:redraws[tatus][!] Redraw the status line of the current window. When ! + is included all status lines are redrawn. + Useful to update the status line(s) when 'statusline' + includes an item that doesn't cause automatic + updating. + + *N<Del>* +<Del> When entering a number: Remove the last digit. + Note: if you like to use <BS> for this, add this + mapping to your .vimrc: > + :map CTRL-V <BS> CTRL-V <Del> +< See |:fixdel| if your <Del> key does not do what you + want. + +:as[cii] or *ga* *:as* *:ascii* +ga Print the ascii value of the character under the + cursor in decimal, hexadecimal and octal. For + example, when the cursor is on a 'R': + <R> 82, Hex 52, Octal 122 ~ + When the character is a non-standard ASCII character, + but printable according to the 'isprint' option, the + non-printable version is also given. When the + character is larger than 127, the <M-x> form is also + printed. For example: + <~A> <M-^A> 129, Hex 81, Octal 201 ~ + <p> <|~> <M-~> 254, Hex fe, Octal 376 ~ + (where <p> is a special character) + The <Nul> character in a file is stored internally as + <NL>, but it will be shown as: + <^@> 0, Hex 00, Octal 000 ~ + If the character has composing characters these are + also shown. The value of 'maxcombine' doesn't matter. + Mnemonic: Get Ascii value. {not in Vi} + + *g8* +g8 Print the hex values of the bytes used in the + character under the cursor, assuming it is in |UTF-8| + encoding. This also shows composing characters. The + value of 'maxcombine' doesn't matter. + Example of a character with two composing characters: + e0 b8 81 + e0 b8 b9 + e0 b9 89 ~ + {not in Vi} {only when compiled with the |+multi_byte| + feature} + + *8g8* +8g8 Find an illegal UTF-8 byte sequence at or after the + cursor. This works in two situations: + 1. when 'encoding' is any 8-bit encoding + 2. when 'encoding' is "utf-8" and 'fileencoding' is + any 8-bit encoding + Thus it can be used when editing a file that was + supposed to be UTF-8 but was read as if it is an 8-bit + encoding because it contains illegal bytes. + Does not wrap around the end of the file. + Note that when the cursor is on an illegal byte or the + cursor is halfway a multi-byte character the command + won't move the cursor. + {not in Vi} {only when compiled with the |+multi_byte| + feature} + + *:p* *:pr* *:print* *E749* +:[range]p[rint] [flags] + Print [range] lines (default current line). + Note: If you are looking for a way to print your text + on paper see |:hardcopy|. In the GUI you can use the + File.Print menu entry. + See |ex-flags| for [flags]. + +:[range]p[rint] {count} [flags] + Print {count} lines, starting with [range] (default + current line |cmdline-ranges|). + See |ex-flags| for [flags]. + + *:P* *:Print* +:[range]P[rint] [count] [flags] + Just as ":print". Was apparently added to Vi for + people that keep the shift key pressed too long... + Note: A user command can overrule this command. + See |ex-flags| for [flags]. + + *:l* *:list* +:[range]l[ist] [count] [flags] + Same as :print, but display unprintable characters + with '^' and put $ after the line. This can be + further changed with the 'listchars' option. + See |ex-flags| for [flags]. + + *:nu* *:number* +:[range]nu[mber] [count] [flags] + Same as :print, but precede each line with its line + number. (See also 'highlight' and 'numberwidth' + option). + See |ex-flags| for [flags]. + + *:#* +:[range]# [count] [flags] + synonym for :number. + + *:#!* +:#!{anything} Ignored, so that you can start a Vim script with: > + #!vim -S + echo "this is a Vim script" + quit +< + *:z* *E144* +:{range}z[+-^.=]{count} Display several lines of text surrounding the line + specified with {range}, or around the current line + if there is no {range}. If there is a {count}, that's + how many lines you'll see; if there is only one window + then twice the value of the 'scroll' option is used, + otherwise the current window height minus 3 is used. + + If there is a {count} the 'window' option is set to + its value. + + :z can be used either alone or followed by any of + several punctuation marks. These have the following + effect: + + mark first line last line new cursor line ~ + ---- ---------- --------- ------------ + + current line 1 scr forward 1 scr forward + - 1 scr back current line current line + ^ 2 scr back 1 scr back 1 scr back + . 1/2 scr back 1/2 scr fwd 1/2 scr fwd + = 1/2 scr back 1/2 scr fwd current line + + Specifying no mark at all is the same as "+". + If the mark is "=", a line of dashes is printed + around the current line. + +:{range}z#[+-^.=]{count} *:z#* + Like ":z", but number the lines. + {not in all versions of Vi, not with these arguments} + + *:=* +:= [flags] Print the last line number. + See |ex-flags| for [flags]. + +:{range}= [flags] Prints the last line number in {range}. For example, + this prints the current line number: > + :.= +< See |ex-flags| for [flags]. + +:norm[al][!] {commands} *:norm* *:normal* + Execute Normal mode commands {commands}. This makes + it possible to execute Normal mode commands typed on + the command-line. {commands} are executed like they + are typed. For undo all commands are undone together. + Execution stops when an error is encountered. + + If the [!] is given, mappings will not be used. + Without it, when this command is called from a + non-remappable mapping (|:noremap|), the argument can + be mapped anyway. + + {commands} should be a complete command. If + {commands} does not finish a command, the last one + will be aborted as if <Esc> or <C-C> was typed. + This implies that an insert command must be completed + (to start Insert mode, see |:startinsert|). A ":" + command must be completed as well. And you can't use + "Q" or "gQ" to start Ex mode. + + The display is not updated while ":normal" is busy. + + {commands} cannot start with a space. Put a count of + 1 (one) before it, "1 " is one space. + + The 'insertmode' option is ignored for {commands}. + + This command cannot be followed by another command, + since any '|' is considered part of the command. + + This command can be used recursively, but the depth is + limited by 'maxmapdepth'. + + An alternative is to use |:execute|, which uses an + expression as argument. This allows the use of + printable characters to represent special characters. + + Example: > + :exe "normal \<c-w>\<c-w>" +< {not in Vi, of course} + {not available when the |+ex_extra| feature was + disabled at compile time} + +:{range}norm[al][!] {commands} *:normal-range* + Execute Normal mode commands {commands} for each line + in the {range}. Before executing the {commands}, the + cursor is positioned in the first column of the range, + for each line. Otherwise it's the same as the + ":normal" command without a range. + {not in Vi} + {not available when |+ex_extra| feature was disabled + at compile time} + + *:sh* *:shell* *E371* +:sh[ell] This command starts a shell. When the shell exits + (after the "exit" command) you return to Vim. The + name for the shell command comes from 'shell' option. + *E360* + Note: This doesn't work when Vim on the Amiga was + started in QuickFix mode from a compiler, because the + compiler will have set stdin to a non-interactive + mode. + + *:!cmd* *:!* *E34* +:!{cmd} Execute {cmd} with the shell. See also the 'shell' + and 'shelltype' option. + + Any '!' in {cmd} is replaced with the previous + external command (see also 'cpoptions'). But not when + there is a backslash before the '!', then that + backslash is removed. Example: ":!ls" followed by + ":!echo ! \! \\!" executes "echo ls ! \!". + + A '|' in {cmd} is passed to the shell, you cannot use + it to append a Vim command. See |:bar|. + + If {cmd} contains "%" it is expanded to the current + file name. Special characters are not escaped, use + quotes to avoid their special meaning: > + :!ls "%" +< If the file name contains a "$" single quotes might + work better (but a single quote causes trouble): > + :!ls '%' +< This should always work, but it's more typing: > + :exe "!ls " . shellescape(expand("%")) +< + A newline character ends {cmd}, what follows is + interpreted as a following ":" command. However, if + there is a backslash before the newline it is removed + and {cmd} continues. It doesn't matter how many + backslashes are before the newline, only one is + removed. + + On Unix the command normally runs in a non-interactive + shell. If you want an interactive shell to be used + (to use aliases) set 'shellcmdflag' to "-ic". + For Win32 also see |:!start|. + + After the command has been executed, the timestamp and + size of the current file is checked |timestamp|. + + Vim redraws the screen after the command is finished, + because it may have printed any text. This requires a + hit-enter prompt, so that you can read any messages. + To avoid this use: > + :silent !{cmd} +< The screen is not redrawn then, thus you have to use + CTRL-L or ":redraw!" if the command did display + something. + Also see |shell-window|. + + *:!!* +:!! Repeat last ":!{cmd}". + + *:ve* *:version* +:ve[rsion] Print the version number of the editor. If the + compiler used understands "__DATE__" the compilation + date is mentioned. Otherwise a fixed release-date is + shown. + The following lines contain information about which + features were enabled when Vim was compiled. When + there is a preceding '+', the feature is included, + when there is a '-' it is excluded. To change this, + you have to edit feature.h and recompile Vim. + To check for this in an expression, see |has()|. + Here is an overview of the features. + The first column shows the smallest version in which + they are included: + T tiny + S small + N normal + B big + H huge + m manually enabled or depends on other features + (none) system dependent + Thus if a feature is marked with "N", it is included + in the normal, big and huge versions of Vim. + + *+feature-list* + *+acl* |ACL| support included + *+ARP* Amiga only: ARP support included +B *+arabic* |Arabic| language support +N *+autocmd* |:autocmd|, automatic commands +m *+balloon_eval* |balloon-eval| support. Included when compiling with + supported GUI (Motif, GTK, GUI) and either + Netbeans/Sun Workshop integration or |+eval| feature. +N *+browse* |:browse| command +N *+builtin_terms* some terminals builtin |builtin-terms| +B *++builtin_terms* maximal terminals builtin |builtin-terms| +N *+byte_offset* support for 'o' flag in 'statusline' option, "go" + and ":goto" commands. +m *+channel* inter process communication |channel| +N *+cindent* |'cindent'|, C indenting +N *+clientserver* Unix and Win32: Remote invocation |clientserver| + *+clipboard* |clipboard| support +N *+cmdline_compl* command line completion |cmdline-completion| +N *+cmdline_hist* command line history |cmdline-history| +N *+cmdline_info* |'showcmd'| and |'ruler'| +N *+comments* |'comments'| support +B *+conceal* "conceal" support, see |conceal| |:syn-conceal| etc. +N *+cryptv* encryption support |encryption| +B *+cscope* |cscope| support +m *+cursorbind* |'cursorbind'| support +m *+cursorshape* |termcap-cursor-shape| support +m *+debug* Compiled for debugging. +N *+dialog_gui* Support for |:confirm| with GUI dialog. +N *+dialog_con* Support for |:confirm| with console dialog. +N *+dialog_con_gui* Support for |:confirm| with GUI and console dialog. +N *+diff* |vimdiff| and 'diff' +N *+digraphs* |digraphs| *E196* +m *+directx* Win32 GUI only: DirectX and |'renderoptions'| + *+dnd* Support for DnD into the "~ register |quote_~|. +B *+emacs_tags* |emacs-tags| files +N *+eval* expression evaluation |eval.txt| +N *+ex_extra* Vim's extra Ex commands: |:center|, |:left|, + |:normal|, |:retab| and |:right| +N *+extra_search* |'hlsearch'| and |'incsearch'| options. +B *+farsi* |farsi| language +N *+file_in_path* |gf|, |CTRL-W_f| and |<cfile>| +N *+find_in_path* include file searches: |[I|, |:isearch|, + |CTRL-W_CTRL-I|, |:checkpath|, etc. +N *+folding* |folding| + *+footer* |gui-footer| + *+fork* Unix only: |fork| shell commands + *+float* Floating point support +N *+gettext* message translations |multi-lang| + *+GUI_Athena* Unix only: Athena |GUI| + *+GUI_neXtaw* Unix only: neXtaw |GUI| + *+GUI_GTK* Unix only: GTK+ |GUI| + *+GUI_Motif* Unix only: Motif |GUI| + *+GUI_Photon* QNX only: Photon |GUI| +m *+hangul_input* Hangul input support |hangul| + *+iconv* Compiled with the |iconv()| function + *+iconv/dyn* Likewise |iconv-dynamic| |/dyn| +N *+insert_expand* |insert_expand| Insert mode completion +N *+jumplist* |jumplist| +B *+keymap* |'keymap'| +B *+langmap* |'langmap'| +N *+libcall* |libcall()| +N *+linebreak* |'linebreak'|, |'breakat'| and |'showbreak'| +N *+lispindent* |'lisp'| +N *+listcmds* Vim commands for the list of buffers |buffer-hidden| + and argument list |:argdelete| +N *+localmap* Support for mappings local to a buffer |:map-local| +m *+lua* |Lua| interface +m *+lua/dyn* |Lua| interface |/dyn| +N *+menu* |:menu| +N *+mksession* |:mksession| +N *+modify_fname* |filename-modifiers| +N *+mouse* Mouse handling |mouse-using| +N *+mouseshape* |'mouseshape'| +B *+mouse_dec* Unix only: Dec terminal mouse handling |dec-mouse| +N *+mouse_gpm* Unix only: Linux console mouse handling |gpm-mouse| +N *+mouse_jsbterm* JSB mouse handling |jsbterm-mouse| +B *+mouse_netterm* Unix only: netterm mouse handling |netterm-mouse| +N *+mouse_pterm* QNX only: pterm mouse handling |qnx-terminal| +N *+mouse_sysmouse* Unix only: *BSD console mouse handling |sysmouse| +B *+mouse_sgr* Unix only: sgr mouse handling |sgr-mouse| +B *+mouse_urxvt* Unix only: urxvt mouse handling |urxvt-mouse| +N *+mouse_xterm* Unix only: xterm mouse handling |xterm-mouse| +N *+multi_byte* 16 and 32 bit characters |multibyte| + *+multi_byte_ime* Win32 input method for multibyte chars |multibyte-ime| +N *+multi_lang* non-English language support |multi-lang| +m *+mzscheme* Mzscheme interface |mzscheme| +m *+mzscheme/dyn* Mzscheme interface |mzscheme-dynamic| |/dyn| +m *+netbeans_intg* |netbeans| +m *+ole* Win32 GUI only: |ole-interface| +N *+path_extra* Up/downwards search in 'path' and 'tags' +m *+perl* Perl interface |perl| +m *+perl/dyn* Perl interface |perl-dynamic| |/dyn| +N *+persistent_undo* Persistent undo |undo-persistence| + *+postscript* |:hardcopy| writes a PostScript file +N *+printer* |:hardcopy| command +H *+profile* |:profile| command +m *+python* Python 2 interface |python| +m *+python/dyn* Python 2 interface |python-dynamic| |/dyn| +m *+python3* Python 3 interface |python| +m *+python3/dyn* Python 3 interface |python-dynamic| |/dyn| +N *+quickfix* |:make| and |quickfix| commands +N *+reltime* |reltime()| function, 'hlsearch'/'incsearch' timeout, + 'redrawtime' option +B *+rightleft* Right to left typing |'rightleft'| +m *+ruby* Ruby interface |ruby| +m *+ruby/dyn* Ruby interface |ruby-dynamic| |/dyn| +N *+scrollbind* |'scrollbind'| +B *+signs* |:sign| +N *+smartindent* |'smartindent'| +m *+sniff* SniFF interface |sniff| +N *+startuptime* |--startuptime| argument +N *+statusline* Options 'statusline', 'rulerformat' and special + formats of 'titlestring' and 'iconstring' +m *+sun_workshop* |workshop| +N *+syntax* Syntax highlighting |syntax| + *+system()* Unix only: opposite of |+fork| +N *+tag_binary* binary searching in tags file |tag-binary-search| +N *+tag_old_static* old method for static tags |tag-old-static| +m *+tag_any_white* any white space allowed in tags file |tag-any-white| +m *+tcl* Tcl interface |tcl| +m *+tcl/dyn* Tcl interface |tcl-dynamic| |/dyn| + *+terminfo* uses |terminfo| instead of termcap +N *+termresponse* support for |t_RV| and |v:termresponse| +N *+textobjects* |text-objects| selection + *+tgetent* non-Unix only: able to use external termcap +N *+title* Setting the window 'title' and 'icon' +N *+toolbar* |gui-toolbar| +N *+user_commands* User-defined commands. |user-commands| +N *+viminfo* |'viminfo'| +N *+vertsplit* Vertically split windows |:vsplit| +N *+virtualedit* |'virtualedit'| +S *+visual* Visual mode |Visual-mode| Always enabled since 7.4.200. +N *+visualextra* extra Visual mode commands |blockwise-operators| +N *+vreplace* |gR| and |gr| +N *+wildignore* |'wildignore'| +N *+wildmenu* |'wildmenu'| +S *+windows* more than one window +m *+writebackup* |'writebackup'| is default on +m *+xim* X input method |xim| + *+xfontset* X fontset support |xfontset| + *+xpm* pixmap support +m *+xpm_w32* Win32 GUI only: pixmap support |w32-xpm-support| + *+xsmp* XSMP (X session management) support + *+xsmp_interact* interactive XSMP (X session management) support +N *+xterm_clipboard* Unix only: xterm clipboard handling +m *+xterm_save* save and restore xterm screen |xterm-screens| +N *+X11* Unix only: can restore window title |X11| + + */dyn* *E370* *E448* + To some of the features "/dyn" is added when the + feature is only available when the related library can + be dynamically loaded. + +:ve[rsion] {nr} Is now ignored. This was previously used to check the + version number of a .vimrc file. It was removed, + because you can now use the ":if" command for + version-dependent behavior. {not in Vi} + + *:redi* *:redir* +:redi[r][!] > {file} Redirect messages to file {file}. The messages which + are the output of commands are written to that file, + until redirection ends. The messages are also still + shown on the screen. When [!] is included, an + existing file is overwritten. When [!] is omitted, + and {file} exists, this command fails. + Only one ":redir" can be active at a time. Calls to + ":redir" will close any active redirection before + starting redirection to the new target. + To stop the messages and commands from being echoed to + the screen, put the commands in a function and call it + with ":silent call Function()". + An alternative is to use the 'verbosefile' option, + this can be used in combination with ":redir". + {not in Vi} + +:redi[r] >> {file} Redirect messages to file {file}. Append if {file} + already exists. {not in Vi} + +:redi[r] @{a-zA-Z} +:redi[r] @{a-zA-Z}> Redirect messages to register {a-z}. Append to the + contents of the register if its name is given + uppercase {A-Z}. The ">" after the register name is + optional. {not in Vi} +:redi[r] @{a-z}>> Append messages to register {a-z}. {not in Vi} + +:redi[r] @*> +:redi[r] @+> Redirect messages to the selection or clipboard. For + backward compatibility, the ">" after the register + name can be omitted. See |quotestar| and |quoteplus|. + {not in Vi} +:redi[r] @*>> +:redi[r] @+>> Append messages to the selection or clipboard. + {not in Vi} + +:redi[r] @"> Redirect messages to the unnamed register. For + backward compatibility, the ">" after the register + name can be omitted. {not in Vi} +:redi[r] @">> Append messages to the unnamed register. {not in Vi} + +:redi[r] => {var} Redirect messages to a variable. If the variable + doesn't exist, then it is created. If the variable + exists, then it is initialized to an empty string. + The variable will remain empty until redirection ends. + Only string variables can be used. After the + redirection starts, if the variable is removed or + locked or the variable type is changed, then further + command output messages will cause errors. {not in Vi} + +:redi[r] =>> {var} Append messages to an existing variable. Only string + variables can be used. {not in Vi} + +:redi[r] END End redirecting messages. {not in Vi} + + *:sil* *:silent* +:sil[ent][!] {command} Execute {command} silently. Normal messages will not + be given or added to the message history. + When [!] is added, error messages will also be + skipped, and commands and mappings will not be aborted + when an error is detected. |v:errmsg| is still set. + When [!] is not used, an error message will cause + further messages to be displayed normally. + Redirection, started with |:redir|, will continue as + usual, although there might be small differences. + This will allow redirecting the output of a command + without seeing it on the screen. Example: > + :redir >/tmp/foobar + :silent g/Aap/p + :redir END +< To execute a Normal mode command silently, use the + |:normal| command. For example, to search for a + string without messages: > + :silent exe "normal /path\<CR>" +< ":silent!" is useful to execute a command that may + fail, but the failure is to be ignored. Example: > + :let v:errmsg = "" + :silent! /^begin + :if v:errmsg != "" + : ... pattern was not found +< ":silent" will also avoid the hit-enter prompt. When + using this for an external command, this may cause the + screen to be messed up. Use |CTRL-L| to clean it up + then. + ":silent menu ..." defines a menu that will not echo a + Command-line command. The command will still produce + messages though. Use ":silent" in the command itself + to avoid that: ":silent menu .... :silent command". + + *:uns* *:unsilent* +:uns[ilent] {command} Execute {command} not silently. Only makes a + difference when |:silent| was used to get to this + command. + Use this for giving a message even when |:silent| was + used. In this example |:silent| is used to avoid the + message about reading the file and |:unsilent| to be + able to list the first line of each file. > + :silent argdo unsilent echo expand('%') . ": " . getline(1) +< + + *:verb* *:verbose* +:[count]verb[ose] {command} + Execute {command} with 'verbose' set to [count]. If + [count] is omitted one is used. ":0verbose" can be + used to set 'verbose' to zero. + The additional use of ":silent" makes messages + generated but not displayed. + The combination of ":silent" and ":verbose" can be + used to generate messages and check them with + |v:statusmsg| and friends. For example: > + :let v:statusmsg = "" + :silent verbose runtime foobar.vim + :if v:statusmsg != "" + : " foobar.vim could not be found + :endif +< When concatenating another command, the ":verbose" + only applies to the first one: > + :4verbose set verbose | set verbose +< verbose=4 ~ + verbose=0 ~ + For logging verbose messages in a file use the + 'verbosefile' option. + + *:verbose-cmd* +When 'verbose' is non-zero, listing the value of a Vim option or a key map or +an abbreviation or a user-defined function or a command or a highlight group +or an autocommand will also display where it was last defined. If it was +defined manually then there will be no "Last set" message. When it was +defined while executing a function, user command or autocommand, the script in +which it was defined is reported. +{not available when compiled without the |+eval| feature} + + *K* +K Run a program to lookup the keyword under the + cursor. The name of the program is given with the + 'keywordprg' (kp) option (default is "man"). The + keyword is formed of letters, numbers and the + characters in 'iskeyword'. The keyword under or + right of the cursor is used. The same can be done + with the command > + :!{program} {keyword} +< There is an example of a program to use in the tools + directory of Vim. It is called 'ref' and does a + simple spelling check. + Special cases: + - If 'keywordprg' is empty, the ":help" command is + used. It's a good idea to include more characters + in 'iskeyword' then, to be able to find more help. + - When 'keywordprg' is equal to "man", a count before + "K" is inserted after the "man" command and before + the keyword. For example, using "2K" while the + cursor is on "mkdir", results in: > + !man 2 mkdir +< - When 'keywordprg' is equal to "man -s", a count + before "K" is inserted after the "-s". If there is + no count, the "-s" is removed. + {not in Vi} + + *v_K* +{Visual}K Like "K", but use the visually highlighted text for + the keyword. Only works when the highlighted text is + not more than one line. {not in Vi} + +[N]gs *gs* *:sl* *:sleep* +:[N]sl[eep] [N] [m] Do nothing for [N] seconds. When [m] is included, + sleep for [N] milliseconds. The count for "gs" always + uses seconds. The default is one second. > + :sleep "sleep for one second + :5sleep "sleep for five seconds + :sleep 100m "sleep for a hundred milliseconds + 10gs "sleep for ten seconds +< Can be interrupted with CTRL-C (CTRL-Break on MS-DOS). + "gs" stands for "goto sleep". + While sleeping the cursor is positioned in the text, + if at a visible position. {not in Vi} + Also process the received netbeans messages. {only + available when compiled with the |+netbeans_intg| + feature} + + + *g_CTRL-A* +g CTRL-A Only when Vim was compiled with MEM_PROFILING defined + (which is very rare): print memory usage statistics. + Only useful for debugging Vim. + For incrementing in Visual mode see |v_g_CTRL-A|. + +============================================================================== +2. Using Vim like less or more *less* + +If you use the less or more program to view a file, you don't get syntax +highlighting. Thus you would like to use Vim instead. You can do this by +using the shell script "$VIMRUNTIME/macros/less.sh". + +This shell script uses the Vim script "$VIMRUNTIME/macros/less.vim". It sets +up mappings to simulate the commands that less supports. Otherwise, you can +still use the Vim commands. + +This isn't perfect. For example, when viewing a short file Vim will still use +the whole screen. But it works good enough for most uses, and you get syntax +highlighting. + +The "h" key will give you a short overview of the available commands. + +If you want to set options differently when using less, define the +LessInitFunc in your vimrc, for example: > + + func LessInitFunc() + set nocursorcolumn nocursorline + endfunc +< + + vim:tw=78:ts=8:ft=help:norl: diff --git a/en/version4.txt b/en/version4.txt new file mode 100644 index 000000000..6b791be88 --- /dev/null +++ b/en/version4.txt @@ -0,0 +1,355 @@ +*version4.txt* For Vim version 7.4. Last change: 2006 Apr 24 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +This document lists the incompatible differences between Vim 3.0 and Vim 4.0. +Although 4.0 is mentioned here, this is also for version 4.1, 4.2, etc.. + +This file is important for everybody upgrading from Vim 3.0. Read it +carefully to avoid unexpected problems. + +'backup' option default changed |backup-changed| +Extension for backup file changed |backup-extension| +Structure of swap file changed |swapfile-changed| +"-w scriptout" argument changed |scriptout-changed| +Backspace and Delete keys |backspace-delete| +Escape for | changed |escape-bar| +Key codes changed |key-codes-changed| +Terminal options changed |termcap-changed| +'errorformat' option changed |errorformat-changed| +'graphic' option gone |graphic-option-gone| +'yankendofline' option gone |ye-option-gone| +'icon' and 'title' default value changed |icon-changed| +'highlight' option changed |highlight-changed| +'tildeop' and 'weirdinvert' short names changed |short-name-changed| +Use of "v", "V" and "CTRL-V" in Visual mode |use-visual-cmds| +CTRL-B in Insert mode removed |toggle-revins| + + +'backup' option default changed *backup-changed* +------------------------------- + +The default value for 'backup' used to be on. This resulted in a backup file +being made when the original file was overwritten. + +Now the default for 'backup' is off. As soon as the writing of the file has +successfully finished, the backup file is deleted. If you want to keep the +backup file, set 'backup' on in your vimrc. The reason for this change is +that many people complained that leaving a backup file behind is not +Vi-compatible. |'backup'| + + +Extension for backup file changed *backup-extension* +--------------------------------- + +The extension for the backup file used to be ".bak". Since other programs +also use this extension and some users make copies with this extension, it was +changed to the less obvious "~". Another advantage is that this takes less +space, which is useful when working on a system with short file names. For +example, on MS-DOS the backup files for "longfile.c" and "longfile.h" would +both become "longfile.bak"; now they will be "longfile.c~" and "longfile.h~". + +If you prefer to use ".bak", you can set the 'backupext' option: > + :set bex=.bak + + +Structure of swap file changed *swapfile-changed* +------------------------------ + +The contents of the swap file were extended with several parameters. Vim +stores the user name and other information about the edited file to make +recovery more easy and to be able to know where the swap file comes from. The +first part of the swap file can now be understood on a machine with a +different byte order or sizeof(int). When you try to recover a file on such a +machine, you will get an error message that this is not possible. + +Because of this change, swap files cannot be exchanged between 3.0 and 4.0. +If you have a swap file from a crashed session with 3.0, use Vim 3.0 to +recover the file---don't use 4.0. |swap-file| + + +"-w scriptout" argument changed *scriptout-changed* +------------------------------- + +"vim -w scriptout" used to append to the scriptout file. Since this was +illogical, it now creates a new file. An existing file is not overwritten +(to avoid destroying an existing file for those who rely on the appending). +[This was removed again later] |-w| + + +Backspace and Delete keys *backspace-delete* +------------------------- + +In 3.0 both the delete key and the backspace key worked as a backspace in +insert mode; they deleted the character to the left of the cursor. In 4.0 the +delete key has a new function: it deletes the character under the cursor, just +like it does on the command-line. If the cursor is after the end of the line +and 'bs' is set, two lines are joined. |<Del>| |i_<Del>| + +In 3.0 the backspace key was always defined as CTRL-H and delete as CTRL-?. +In 4.0 the code for the backspace and delete key is obtained from termcap or +termlib, and adjusted for the "stty erase" value on Unix. This helps people +who define the erase character according to the keyboard they are working on. + |<BS>| |i_<BS>| + +If you prefer backspace and delete in Insert mode to have the old behavior, +put this line in your vimrc: + + inoremap ^? ^H + +And you may also want to add these, to fix the values for <BS> and <Del>: + + set t_kb=^H + set t_kD=^? + +(Enter ^H with CTRL-V CTRL-H and ^? with CTRL-V CTRL-? or <Del>.) + +If the value for t_kb is correct, but the t_kD value is not, use the ":fixdel" +command. It will set t_kD according to the value of t_kb. This is useful if +you are using several different terminals. |:fixdel| + +When ^H is not recognized as <BS> or <Del>, it is used like a backspace. + + +Escape for | changed *escape-bar* +-------------------- + +When the 'b' flag is present in 'cpoptions', the backslash cannot be used to +escape '|' in mapping and abbreviate commands, only CTRL-V can. This is +Vi-compatible. If you work in Vi-compatible mode and had used "\|" to include +a bar in a mapping, this needs to be replaced by "^V|". See |:bar|. + + +Key codes changed *key-codes-changed* +----------------- + +The internal representation of key codes has changed dramatically. In 3.0 a +one-byte code was used to represent a key. This caused problems with +different characters sets that also used these codes. In 4.0 a three-byte +code is used that cannot be confused with a character. |key-notation| + +If you have used the single-byte key codes in your vimrc for mappings, you +will have to replace them with the 4.0 codes. Instead of using the three-byte +code directly, you should use the symbolic representation for this in <>. See +the table below. The table also lists the old name, as it was used in the 3.0 +documentation. + +The key names in <> can be used in mappings directly. This makes it possible +to copy/paste examples or type them literally. The <> notation has been +introduced for this |<>|. The 'B' and '<' flags must not be present in +'cpoptions' to enable this to work |'cpoptions'|. + +old name new name old code old MS-DOS code ~ + hex dec hex dec ~ +<ESC> <Esc> +<TAB> <Tab> +<LF> <NL> <NewLine> <LineFeed> +<SPACE> <Space> +<NUL> <Nul> +<BELL> <Bell> +<BS> <BS> <BackSpace> +<INSERT> <Insert> +<DEL> <Del> <Delete> +<HOME> <Home> +<END> <End> +<PAGE_UP> <PageUp> +<PAGE_DOWN> <PageDown> + +<C_UP> <Up> 0x80 128 0xb0 176 +<C_DOWN> <Down> 0x81 129 0xb1 177 +<C_LEFT> <Left> 0x82 130 0xb2 178 +<C_RIGHT> <Right> 0x83 131 0xb3 179 +<SC_UP> <S-Up> 0x84 132 0xb4 180 +<SC_DOWN> <S-Down> 0x85 133 0xb5 181 +<SC_LEFT> <S-Left> 0x86 134 0xb6 182 +<SC_RIGHT> <S-Right> 0x87 135 0xb7 183 + +<F1> <F1> 0x88 136 0xb8 184 +<F2> <F2> 0x89 137 0xb9 185 +<F3> <F3> 0x8a 138 0xba 186 +<F4> <F4> 0x8b 139 0xbb 187 +<F5> <F5> 0x8c 140 0xbc 188 +<F6> <F6> 0x8d 141 0xbd 189 +<F7> <F7> 0x8e 142 0xbe 190 +<F8> <F8> 0x8f 143 0xbf 191 +<F9> <F9> 0x90 144 0xc0 192 +<F10> <F10> 0x91 145 0xc1 193 + +<SF1> <S-F1> 0x92 146 0xc2 194 +<SF2> <S-F2> 0x93 147 0xc3 195 +<SF3> <S-F3> 0x94 148 0xc4 196 +<SF4> <S-F4> 0x95 149 0xc5 197 +<SF5> <S-F5> 0x96 150 0xc6 198 +<SF6> <S-F6> 0x97 151 0xc7 199 +<SF7> <S-F7> 0x98 152 0xc8 200 +<SF8> <S-F8> 0x99 153 0xc9 201 +<SF9> <S-F9> 0x9a 154 0xca 202 +<SF10> <S-F10> 0x9b 155 0xcb 203 + +<HELP> <Help> 0x9c 156 0xcc 204 +<UNDO> <Undo> 0x9d 157 0xcd 205 + + (not used) 0x9e 158 0xce 206 + (not used) 0x9f 159 0xcf 207 + + +Terminal options changed *termcap-changed* +------------------------ + +The names of the terminal options have been changed to match the termcap names +of these options. All terminal options now have the name t_xx, where xx is +the termcap name. Normally these options are not used, unless you have a +termcap entry that is wrong or incomplete, or you have set the highlight +options to a different value. |terminal-options| + +Note that for some keys there is no termcap name. Use the <> type of name +instead, which is a good idea anyway. + +Note that "t_ti" has become "t_mr" (invert/reverse output) and "t_ts" has +become "t_ti" (init terminal mode). Be careful when you use "t_ti"! + +old name new name meaning ~ +t_cdl t_DL delete number of lines *t_cdl* +t_ci t_vi cursor invisible *t_ci* +t_cil t_AL insert number of lines *t_cil* +t_cm t_cm move cursor +t_cri t_RI cursor number of chars right *t_cri* +t_cv t_ve cursor visible *t_cv* +t_cvv t_vs cursor very visible *t_cvv* +t_dl t_dl delete line +t_cs t_cs scroll region +t_ed t_cl clear display *t_ed* +t_el t_ce clear line *t_el* +t_il t_al insert line *t_il* + t_da display may be retained above the screen + t_db display may be retained below the screen +t_ke t_ke put terminal out of keypad transmit mode +t_ks t_ks put terminal in keypad transmit mode +t_ms t_ms save to move cursor in highlight mode +t_se t_se normal mode (undo t_so) +t_so t_so shift out (standout) mode +t_ti t_mr reverse highlight +t_tb t_md bold mode *t_tb* +t_tp t_me highlight end *t_tp* +t_sr t_sr scroll reverse +t_te t_te out of termcap mode +t_ts t_ti into termcap mode *t_ts_old* +t_vb t_vb visual bell +t_csc t_CS cursor is relative to scroll region *t_csc* + +t_ku t_ku <Up> arrow up +t_kd t_kd <Down> arrow down +t_kr t_kr <Right> arrow right +t_kl t_kl <Left> arrow left +t_sku <S-Up> shifted arrow up *t_sku* +t_skd <S-Down> shifted arrow down *t_skd* +t_skr t_%i <S-Right> shifted arrow right *t_skr* +t_skl t_#4 <S-Left> shifted arrow left *t_skl* +t_f1 t_k1 <F1> function key 1 *t_f1* +t_f2 t_k2 <F2> function key 2 *t_f2* +t_f3 t_k3 <F3> function key 3 *t_f3* +t_f4 t_k4 <F4> function key 4 *t_f4* +t_f5 t_k5 <F5> function key 5 *t_f5* +t_f6 t_k6 <F6> function key 6 *t_f6* +t_f7 t_k7 <F7> function key 7 *t_f7* +t_f8 t_k8 <F8> function key 8 *t_f8* +t_f9 t_k9 <F9> function key 9 *t_f9* +t_f10 t_k; <F10> function key 10 *t_f10* +t_sf1 <S-F1> shifted function key 1 *t_sf1* +t_sf2 <S-F2> shifted function key 2 *t_sf2* +t_sf3 <S-F3> shifted function key 3 *t_sf3* +t_sf4 <S-F4> shifted function key 4 *t_sf4* +t_sf5 <S-F5> shifted function key 5 *t_sf5* +t_sf6 <S-F6> shifted function key 6 *t_sf6* +t_sf7 <S-F7> shifted function key 7 *t_sf7* +t_sf8 <S-F8> shifted function key 8 *t_sf8* +t_sf9 <S-F9> shifted function key 9 *t_sf9* +t_sf10 <S-F10> shifted function key 10 *t_sf10* +t_help t_%1 <Help> help key *t_help* +t_undo t_&8 <Undo> undo key *t_undo* + + +'errorformat' option changed *errorformat-changed* +---------------------------- + +'errorformat' can now contain several formats, separated by commas. The first +format that matches is used. The default values have been adjusted to catch +the most common formats. |errorformat| + +If you have a format that contains a comma, it needs to be preceded with a +backslash. Type two backslashes, because the ":set" command will eat one. + + +'graphic' option gone *graphic-option-gone* +--------------------- + +The 'graphic' option was used to make the characters between <~> and 0xa0 +display directly on the screen. Now the 'isprint' option takes care of this +with many more possibilities. The default setting is the same; you only need +to look into this if you previously set the 'graphic' option in your vimrc. + |'isprint'| + + +'yankendofline' option gone *ye-option-gone* +--------------------------- + +The 'yankendofline' option has been removed. Instead you can just use + :map Y y$ + + +'icon' and 'title' default value changed *icon-changed* +---------------------------------------- + +The 'title' option is now only set by default if the original title can be +restored. Avoids "Thanks for flying Vim" titles. If you want them anyway, +put ":set title" in your vimrc. |'title'| + +The default for 'icon' now depends on the possibility of restoring the +original value, just like 'title'. If you don't like your icon titles to be +changed, add this line to your vimrc: |'icon'| + :set noicon + + +'highlight' option changed *highlight-changed* +-------------------------- + +The 'i' flag now means italic highlighting, instead of invert. The 'r' flag +is used for reverse highlighting, which is what 'i' used to be. Normally you +won't see the difference, because italic mode is not supported on most +terminals and reverse mode is used as a fallback. |'highlight'| + +When an occasion is not present in 'highlight', use the mode from the default +value for 'highlight', instead of reverse mode. + + +'tildeop' and 'weirdinvert' short names changed *short-name-changed* +----------------------------------------------- + +Renamed 'to' (abbreviation for 'tildeop') to 'top'. |'tildeop'| +Renamed 'wi' (abbreviation for 'weirdinvert') to 'wiv'. |'weirdinvert'| + +This was done because Vi uses 'wi' as the short name for 'window' and 'to' as +the short name for 'timeout'. This means that if you try setting these +options, you won't get an error message, but the effect will be different. + + +Use of "v", "V" and "CTRL-V" in Visual mode *use-visual-cmds* +------------------------------------------- + +In Visual mode, "v", "V", and "CTRL-V" used to end Visual mode. Now this +happens only if the Visual mode was in the corresponding type. Otherwise the +type of Visual mode is changed. Now only ESC can be used in all circumstances +to end Visual mode without doing anything. |v_V| + + +CTRL-B in Insert mode removed *toggle-revins* +----------------------------- + +CTRL-B in Insert mode used to toggle the 'revins' option. If you don't know +this and accidentally hit CTRL-B, it is very difficult to find out how to undo +it. Since hardly anybody uses this feature, it is disabled by default. If +you want to use it, define RIGHTLEFT in feature.h before compiling. |'revins'| + + vim:tw=78:ts=8:ft=help:norl: diff --git a/en/vi_diff.txt b/en/vi_diff.txt new file mode 100644 index 000000000..2a7bbe467 --- /dev/null +++ b/en/vi_diff.txt @@ -0,0 +1,1012 @@ +*vi_diff.txt* For Vim version 7.4. Last change: 2015 Nov 01 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Differences between Vim and Vi *vi-differences* + +Throughout the help files differences between Vim and Vi/Ex are given in +curly braces, like "{not in Vi}". This file only lists what has not been +mentioned in other files and gives an overview. + +Vim is mostly POSIX 1003.2-1 compliant. The only command known to be missing +is ":open". There are probably a lot of small differences (either because Vim +is missing something or because Posix is beside the mark). + +1. Simulated command |simulated-command| +2. Missing options |missing-options| +3. Limits |limits| +4. The most interesting additions |vim-additions| +5. Other vim features |other-features| +6. Command-line arguments |cmdline-arguments| +7. POSIX compliance |posix-compliance| + +============================================================================== +1. Simulated command *simulated-command* + +This command is in Vi, but Vim only simulates it: + + *:o* *:op* *:open* +:[range]o[pen] Works like |:visual|: end Ex mode. + {Vi: start editing in open mode} + +:[range]o[pen] /pattern/ As above, additionally move the cursor to the + column where "pattern" matches in the cursor + line. + +Vim does not support open mode, since it's not really useful. For those +situations where ":open" would start open mode Vim will leave Ex mode, which +allows executing the same commands, but updates the whole screen instead of +only one line. + +============================================================================== +2. Missing options *missing-options* + +These options are in the Unix Vi, but not in Vim. If you try to set one of +them you won't get an error message, but the value is not used and cannot be +printed. + +autoprint (ap) boolean (default on) *'autoprint'* *'ap'* +beautify (bf) boolean (default off) *'beautify'* *'bf'* +flash (fl) boolean (default ??) *'flash'* *'fl'* +graphic (gr) boolean (default off) *'graphic'* *'gr'* +hardtabs (ht) number (default 8) *'hardtabs'* *'ht'* + number of spaces that a <Tab> moves on the display +mesg boolean (default on) *'mesg'* +novice boolean (default off) *'novice'* +open boolean (default on) *'open'* +optimize (op) boolean (default off) *'optimize'* *'op'* +redraw boolean (default off) *'redraw'* +slowopen (slow) boolean (default off) *'slowopen'* *'slow'* +sourceany boolean (default off) *'sourceany'* +w300 number (default 23) *'w300'* +w1200 number (default 23) *'w1200'* +w9600 number (default 23) *'w9600'* + +============================================================================== +3. Limits *limits* + +Vim has only a few limits for the files that can be edited {Vi: can not handle +<Nul> characters and characters above 128, has limited line length, many other +limits}. + *E340* +Maximum line length On machines with 16-bit ints (Amiga and MS-DOS real + mode): 32767, otherwise 2147483647 characters. + Longer lines are split. +Maximum number of lines 2147483647 lines. +Maximum file size 2147483647 bytes (2 Gbyte) when a long integer is + 32 bits. Much more for 64 bit longs. Also limited + by available disk space for the |swap-file|. + *E75* +Length of a file path Unix and Win32: 1024 characters, otherwise 256 + characters (or as much as the system supports). +Length of an expanded string option + Unix and Win32: 1024 characters, otherwise 256 + characters +Maximum display width Unix and Win32: 1024 characters, otherwise 255 + characters +Maximum lhs of a mapping 50 characters. +Number of different highlighting types: over 30000 +Range of a Number variable: -2147483648 to 2147483647 (might be more on 64 + bit systems) +Maximum length of a line in a tags file: 512 bytes. + +Information for undo and text in registers is kept in memory, thus when making +(big) changes the amount of (virtual) memory available limits the number of +undo levels and the text that can be kept in registers. Other things are also +kept in memory: Command-line history, error messages for Quickfix mode, etc. + +Memory usage limits +------------------- + +The option 'maxmem' ('mm') is used to set the maximum memory used for one +buffer (in kilobytes). 'maxmemtot' is used to set the maximum memory used for +all buffers (in kilobytes). The defaults depend on the system used. For the +Amiga and MS-DOS, 'maxmemtot' is set depending on the amount of memory +available. +These are not hard limits, but tell Vim when to move text into a swap file. +If you don't like Vim to swap to a file, set 'maxmem' and 'maxmemtot' to a +very large value. The swap file will then only be used for recovery. If you +don't want a swap file at all, set 'updatecount' to 0, or use the "-n" +argument when starting Vim. + +============================================================================== +4. The most interesting additions *vim-additions* + +Vi compatibility. |'compatible'| + Although Vim is 99% Vi compatible, some things in Vi can be + considered to be a bug, or at least need improvement. But still, Vim + starts in a mode which behaves like the "real" Vi as much as possible. + To make Vim behave a little bit better, try resetting the 'compatible' + option: + :set nocompatible + Or start Vim with the "-N" argument: + vim -N + Vim starts with 'nocompatible' automatically if you have a .vimrc + file. See |startup|. + The 'cpoptions' option can be used to set Vi compatibility on/off for + a number of specific items. + +Support for different systems. + Vim can be used on: + - All Unix systems (it works on all systems it was tested on, although + the GUI and Perl interface may not work everywhere). + - Amiga (500, 1000, 1200, 2000, 3000, 4000, ...). + - MS-DOS in real-mode (no additional drivers required). + - In protected mode on Windows 3.1 and MS-DOS (DPMI driver required). + - Windows 95 and Windows NT, with support for long file names. + - OS/2 (needs emx.dll) + - Atari MiNT + - VMS + - BeOS + - Macintosh + - Risc OS + - IBM OS/390 + Note that on some systems features need to be disabled to reduce + resource usage, esp. on MS-DOS. For some outdated systems you need to + use an older Vim version. + +Multi level undo. |undo| + 'u' goes backward in time, 'CTRL-R' goes forward again. Set option + 'undolevels' to the number of changes to be remembered (default 1000). + Set 'undolevels' to 0 for a Vi-compatible one level undo. Set it to + -1 for no undo at all. + When all changes in a buffer have been undone, the buffer is not + considered changed anymore. You can exit it with :q, without <!>. + When undoing a few changes and then making a new change Vim will + create a branch in the undo tree. This means you can go back to any + state of the text, there is no risk of a change causing text to be + lost forever. |undo-tree| + +Graphical User Interface (GUI). |gui| + Included support for GUI: menu's, mouse, scrollbars, etc. You can + define your own menus. Better support for CTRL/SHIFT/ALT keys in + combination with special keys and mouse. Supported for various + platforms, such as X11 (with Motif and Athena interfaces), GTK, Win32 + (Windows 95 and later), BeOS, Amiga and Macintosh. + +Multiple windows and buffers. |windows.txt| + Vim can split the screen into several windows, each editing a + different buffer or the same buffer at a different location. Buffers + can still be loaded (and changed) but not displayed in a window. This + is called a hidden buffer. Many commands and options have been added + for this facility. + Vim can also use multiple tab pages, each with one or more windows. A + line with tab labels can be used to quickly switch between these pages. + |tab-page| + +Syntax highlighting. |:syntax| + Vim can highlight keywords, patterns and other things. This is + defined by a number of |:syntax| commands, and can be made to + highlight most languages and file types. A number of files are + included for highlighting the most common languages, like C, C++, + Java, Pascal, Makefiles, shell scripts, etc. The colors used for + highlighting can be defined for ordinary terminals, color terminals + and the GUI with the |:highlight| command. A convenient way to do + this is using a |:colorscheme| command. + The highlighted text can be exported as HTML. |convert-to-HTML| + Other items that can be highlighted are matches with the search string + |'hlsearch'|, matching parens |matchparen| and the cursor line and + column |'cursorline'| |'cursorcolumn'|. + +Spell checking. |spell| + When the 'spell' option is set Vim will highlight spelling mistakes. + About 50 languages are currently supported, selected with the + 'spelllang' option. In source code only comments and strings are + checked for spelling. + +Folding. |folding| + A range of lines can be shown as one "folded" line. This allows + overviewing a file and moving blocks of text around quickly. + Folds can be created manually, from the syntax of the file, by indent, + etc. + +Diff mode. |diff| + Vim can show two versions of a file with the differences highlighted. + Parts of the text that are equal are folded away. Commands can be + used to move text from one version to the other. + +Plugins. |add-plugin| + The functionality can be extended by dropping a plugin file in the + right directory. That's an easy way to start using Vim scripts + written by others. Plugins can be for all kind of files, or + specifically for a filetype. + +Repeat a series of commands. |q| + "q{c}" starts recording typed characters into named register {c}. + A subsequent "q" stops recording. The register can then be executed + with the "@{c}" command. This is very useful to repeat a complex + action. + +Flexible insert mode. |ins-special-special| + The arrow keys can be used in insert mode to move around in the file. + This breaks the insert in two parts as far as undo and redo is + concerned. + + CTRL-O can be used to execute a single Normal mode command. This is + almost the same as hitting <Esc>, typing the command and doing |a|. + +Visual mode. |Visual-mode| + Visual mode can be used to first highlight a piece of text and then + give a command to do something with it. This is an (easy to use) + alternative to first giving the operator and then moving to the end of + the text to be operated upon. + |v| and |V| are used to start Visual mode. |v| works on characters + and |V| on lines. Move the cursor to extend the Visual area. It is + shown highlighted on the screen. By typing "o" the other end of the + Visual area can be moved. The Visual area can be affected by an + operator: + d delete + c change + y yank + > or < insert or delete indent + ! filter through external program + = filter through indent + : start |:| command for the Visual lines. + gq format text to 'textwidth' columns + J join lines + ~ swap case + u make lowercase + U make uppercase + +Block operators. |visual-block| + With Visual mode a rectangular block of text can be selected. Start + Visual mode with CTRL-V. The block can be deleted ("d"), yanked ("y") + or its case can be changed ("~", "u" and "U"). A deleted or yanked + block can be put into the text with the "p" and "P" commands. + +Help system. |:help| + Help is displayed in a window. The usual commands can be used to + move around, search for a string, etc. Tags can be used to jump + around in the help files, just like hypertext links. The |:help| + command takes an argument to quickly jump to the info on a subject. + <F1> is the quick access to the help system. The name of the help + index file can be set with the 'helpfile' option. + +Command-line editing and history. |cmdline-editing| + You can insert or delete at any place in the command-line using the + cursor keys. The right/left cursor keys can be used to move + forward/backward one character. The shifted right/left cursor keys + can be used to move forward/backward one word. CTRL-B/CTRL-E can be + used to go to the begin/end of the command-line. + |cmdline-history| + The command-lines are remembered. The up/down cursor keys can be used + to recall previous command-lines. The 'history' option can be set to + the number of lines that will be remembered. There is a separate + history for commands and for search patterns. + +Command-line completion. |cmdline-completion| + While entering a command-line (on the bottom line of the screen) + <Tab> can be typed to complete + what example ~ + - command :e<Tab> + - tag :ta scr<Tab> + - option :set sc<Tab> + - option value :set hf=<Tab> + - file name :e ve<Tab> + - etc. + + If there are multiple matches, CTRL-N (next) and CTRL-P (previous) + will walk through the matches. <Tab> works like CTRL-N, but wraps + around to the first match. + + The 'wildchar' option can be set to the character for command-line + completion, <Tab> is the default. CTRL-D can be typed after an + (incomplete) wildcard; all matches will be listed. CTRL-A will insert + all matches. CTRL-L will insert the longest common part of the + matches. + +Insert-mode completion. |ins-completion| + In Insert mode the CTRL-N and CTRL-P keys can be used to complete a + word that appears elsewhere. |i_CTRL-N| + With CTRL-X another mode is entered, through which completion can be + done for: + |i_CTRL-X_CTRL-F| file names + |i_CTRL-X_CTRL-K| words from 'dictionary' files + |i_CTRL-X_CTRL-T| words from 'thesaurus' files + |i_CTRL-X_CTRL-I| words from included files + |i_CTRL-X_CTRL-L| whole lines + |i_CTRL-X_CTRL-]| words from the tags file + |i_CTRL-X_CTRL-D| definitions or macros + |i_CTRL-X_CTRL-O| Omni completion: clever completion + specifically for a file type + etc. + +Long line support. |'wrap'| |'linebreak'| + If the 'wrap' option is off, long lines will not wrap and only part + of them will be shown. When the cursor is moved to a part that is not + shown, the screen will scroll horizontally. The minimum number of + columns to scroll can be set with the 'sidescroll' option. The |zh| + and |zl| commands can be used to scroll sideways. + Alternatively, long lines are broken in between words when the + 'linebreak' option is set. This allows editing a single-line + paragraph conveniently (e.g. when the text is later read into a DTP + program). Move the cursor up/down with the |gk| and |gj| commands. + +Text formatting. |formatting| + The 'textwidth' option can be used to automatically limit the line + length. This supplements the 'wrapmargin' option of Vi, which was not + very useful. The |gq| operator can be used to format a piece of text + (for example, |gqap| formats the current paragraph). Commands for + text alignment: |:center|, |:left| and |:right|. + +Extended search patterns. |pattern| + There are many extra items to match various text items. Examples: + A "\n" can be used in a search pattern to match a line break. + "x\{2,4}" matches "x" 2 to 4 times. + "\s" matches a white space character. + +Directory, remote and archive browsing. |netrw| + Vim can browse the file system. Simply edit a directory. Move around + in the list with the usual commands and press <Enter> to go to the + directory or file under the cursor. + This also works for remote files over ftp, http, ssh, etc. + Zip and tar archives can also be browsed. |tar| |zip| + +Edit-compile-edit speedup. |quickfix| + The |:make| command can be used to run the compilation and jump to the + first error. A file with compiler error messages is interpreted. Vim + jumps to the first error. + + Each line in the error file is scanned for the name of a file, line + number and error message. The 'errorformat' option can be set to a + list of scanf-like strings to handle output from many compilers. + + The |:cn| command can be used to jump to the next error. + |:cl| lists all the error messages. Other commands are available. + The 'makeef' option has the name of the file with error messages. + The 'makeprg' option contains the name of the program to be executed + with the |:make| command. + The 'shellpipe' option contains the string to be used to put the + output of the compiler into the errorfile. + +Finding matches in files. |:vimgrep| + Vim can search for a pattern in multiple files. This uses the + advanced Vim regexp pattern, works on all systems and also works to + search in compressed files. + +Improved indenting for programs. |'cindent'| + When the 'cindent' option is on the indent of each line is + automatically adjusted. C syntax is mostly recognized. The indent + for various styles can be set with 'cinoptions'. The keys to trigger + indenting can be set with 'cinkeys'. + + Comments can be automatically formatted. The 'comments' option can be + set to the characters that start and end a comment. This works best + for C code, but also works for e-mail (">" at start of the line) and + other types of text. The |=| operator can be used to re-indent + lines. + + For many other languages an indent plugin is present to support + automatic indenting. |30.3| + +Searching for words in included files. |include-search| + The |[i| command can be used to search for a match of the word under + the cursor in the current and included files. The 'include' option + can be set to a pattern that describes a command to include a file + (the default is for C programs). + The |[I| command lists all matches, the |[_CTRL-I| command jumps to + a match. + The |[d|, |[D| and |[_CTRL-D| commands do the same, but only for + lines where the pattern given with the 'define' option matches. + +Automatic commands. |autocommand| + Commands can be automatically executed when reading a file, writing a + file, jumping to another buffer, etc., depending on the file name. + This is useful to set options and mappings for C programs, + documentation, plain text, e-mail, etc. This also makes it possible + to edit compressed files. + +Scripts and Expressions. |expression| + Commands have been added to form up a powerful script language. + |:if| Conditional execution, which can be used for example + to set options depending on the value of $TERM. + |:while| Repeat a number of commands. + |:for| Loop over a list. + |:echo| Print the result of an expression. + |:let| Assign a value to an internal variable, option, etc. + Variable types are Number, String, List and Dictionary. + |:execute| Execute a command formed by an expression. + |:try| Catch exceptions. + etc., etc. See |eval|. + Debugging and profiling are supported. |debug-scripts| |profile| + If this is not enough, an interface is provided to |Python|, |Ruby|, + |Tcl|, |Lua|, |Perl| and |MzScheme|. + +Viminfo. |viminfo-file| + The command-line history, marks and registers can be stored in a file + that is read on startup. This can be used to repeat a search command + or command-line command after exiting and restarting Vim. It is also + possible to jump right back to where the last edit stopped with |'0|. + The 'viminfo' option can be set to select which items to store in the + .viminfo file. This is off by default. + +Printing. |printing| + The |:hardcopy| command sends text to the printer. This can include + syntax highlighting. + +Mouse support. |mouse-using| + The mouse is supported in the GUI version, in an xterm for Unix, for + BSDs with sysmouse, for Linux with gpm, for MS-DOS, and Win32. It + can be used to position the cursor, select the visual area, paste a + register, etc. + +Usage of key names. |<>| |key-notation| + Special keys now all have a name like <Up>, <End>, etc. + This name can be used in mappings, to make it easy to edit them. + +Editing binary files. |edit-binary| + Vim can edit binary files. You can change a few characters in an + executable file, without corrupting it. Vim doesn't remove NUL + characters (they are represented as <NL> internally). + |-b| command-line argument to start editing a binary file + |'binary'| Option set by |-b|. Prevents adding an <EOL> for the + last line in the file. + +Multi-language support. |multi-lang| + Files in double-byte or multi-byte encodings can be edited. There is + UTF-8 support to be able to edit various languages at the same time, + without switching fonts. |UTF-8| + Messages and menus are available in different languages. + +Move cursor beyond lines. + When the 'virtualedit' option is set the cursor can move all over the + screen, also where there is no text. This is useful to edit tables + and figures easily. + +============================================================================== +5. Other vim features *other-features* + +A random collection of nice extra features. + + +When Vim is started with "-s scriptfile", the characters read from +"scriptfile" are treated as if you typed them. If end of file is reached +before the editor exits, further characters are read from the console. + +The "-w" option can be used to record all typed characters in a script file. +This file can then be used to redo the editing, possibly on another file or +after changing some commands in the script file. + +The "-o" option opens a window for each argument. "-o4" opens four windows. + +Vi requires several termcap entries to be able to work full-screen. Vim only +requires the "cm" entry (cursor motion). + + +In command mode: + +When the 'showcmd' option is set, the command characters are shown in the last +line of the screen. They are removed when the command is finished. + +If the 'ruler' option is set, the current cursor position is shown in the +last line of the screen. + +"U" still works after having moved off the last changed line and after "u". + +Characters with the 8th bit set are displayed. The characters between '~' and +0xa0 are displayed as "~?", "~@", "~A", etc., unless they are included in the +'isprint' option. + +"][" goes to the next ending of a C function ('}' in column 1). +"[]" goes to the previous ending of a C function ('}' in column 1). + +"]f", "[f" and "gf" start editing the file whose name is under the cursor. +CTRL-W f splits the window and starts editing the file whose name is under +the cursor. + +"*" searches forward for the identifier under the cursor, "#" backward. +"K" runs the program defined by the 'keywordprg' option, with the identifier +under the cursor as argument. + +"%" can be preceded with a count. The cursor jumps to the line that +percentage down in the file. The normal "%" function to jump to the matching +brace skips braces inside quotes. + +With the CTRL-] command, the cursor may be in the middle of the identifier. + +The used tags are remembered. Commands that can be used with the tag stack +are CTRL-T, ":pop" and ":tag". ":tags" lists the tag stack. + +The 'tags' option can be set to a list of tag file names. Thus multiple +tag files can be used. For file names that start with "./", the "./" is +replaced with the path of the current file. This makes it possible to use a +tags file in the same directory as the file being edited. + +Previously used file names are remembered in the alternate file name list. +CTRL-^ accepts a count, which is an index in this list. +":files" command shows the list of alternate file names. +"#<N>" is replaced with the <N>th alternate file name in the list. +"#<" is replaced with the current file name without extension. + +Search patterns have more features. The <NL> character is seen as part of the +search pattern and the substitute string of ":s". Vi sees it as the end of +the command. + +Searches can put the cursor on the end of a match and may include a character +offset. + +Count added to "~", ":next", ":Next", "n" and "N". + +The command ":next!" with 'autowrite' set does not write the file. In vi the +file was written, but this is considered to be a bug, because one does not +expect it and the file is not written with ":rewind!". + +In Vi when entering a <CR> in replace mode deletes a character only when 'ai' +is set (but does not show it until you hit <Esc>). Vim always deletes a +character (and shows it immediately). + +Added :wnext command. Same as ":write" followed by ":next". + +The ":w!" command always writes, also when the file is write protected. In Vi +you would have to do ":!chmod +w %:S" and ":set noro". + +When 'tildeop' has been set, "~" is an operator (must be followed by a +movement command). + +With the "J" (join) command you can reset the 'joinspaces' option to have only +one space after a period (Vi inserts two spaces). + +"cw" can be used to change white space formed by several characters (Vi is +confusing: "cw" only changes one space, while "dw" deletes all white space). + +"o" and "O" accept a count for repeating the insert (Vi clears a part of +display). + +Flags after Ex commands not supported (no plans to include it). + +On non-UNIX systems ":cd" command shows current directory instead of going to +the home directory (there isn't one). ":pwd" prints the current directory on +all systems. + +After a ":cd" command the file names (in the argument list, opened files) +still point to the same files. In Vi ":cd" is not allowed in a changed file; +otherwise the meaning of file names change. + +":source!" command reads Vi commands from a file. + +":mkexrc" command writes current modified options and mappings to a ".exrc" +file. ":mkvimrc" writes to a ".vimrc" file. + +No check for "tail recursion" with mappings. This allows things like +":map! foo ^]foo". + +When a mapping starts with number, vi loses the count typed before it (e.g. +when using the mapping ":map g 4G" the command "7g" goes to line 4). This is +considered a vi bug. Vim concatenates the counts (in the example it becomes +"74G"), as most people would expect. + +The :put! command inserts the contents of a register above the current line. + +The "p" and "P" commands of vi cannot be repeated with "." when the putted +text is less than a line. In Vim they can always be repeated. + +":noremap" command can be used to enter a mapping that will not be remapped. +This is useful to exchange the meaning of two keys. ":cmap", ":cunmap" and +":cnoremap" can be used for mapping in command-line editing only. ":imap", +":iunmap" and ":inoremap" can be used for mapping in insert mode only. +Similar commands exist for abbreviations: ":noreabbrev", ":iabbrev" +":cabbrev", ":iunabbrev", ":cunabbrev", ":inoreabbrev", ":cnoreabbrev". + +In Vi the command ":map foo bar" would remove a previous mapping +":map bug foo". This is considered a bug, so it is not included in Vim. +":unmap! foo" does remove ":map! bug foo", because unmapping would be very +difficult otherwise (this is vi compatible). + +The ':' register contains the last command-line. +The '%' register contains the current file name. +The '.' register contains the last inserted text. + +":dis" command shows the contents of the yank registers. + +CTRL-O/CTRL-I can be used to jump to older/newer positions. These are the +same positions as used with the '' command, but may be in another file. The +":jumps" command lists the older positions. + +If the 'shiftround' option is set, an indent is rounded to a multiple of +'shiftwidth' with ">" and "<" commands. + +The 'scrolljump' option can be set to the minimum number of lines to scroll +when the cursor gets off the screen. Use this when scrolling is slow. + +The 'scrolloff' option can be set to the minimum number of lines to keep +above and below the cursor. This gives some context to where you are +editing. When set to a large number the cursor line is always in the middle +of the window. + +Uppercase marks can be used to jump between files. The ":marks" command lists +all currently set marks. The commands "']" and "`]" jump to the end of the +previous operator or end of the text inserted with the put command. "'[" and +"`[" do jump to the start. + +The 'shelltype' option can be set to reflect the type of shell used on the +Amiga. + +The 'highlight' option can be set for the highlight mode to be used for +several commands. + +The CTRL-A (add) and CTRL-X (subtract) commands are new. The count to the +command (default 1) is added to/subtracted from the number at or after the +cursor. That number may be decimal, octal (starts with a '0') or hexadecimal +(starts with '0x'). Very useful in macros. + +With the :set command the prefix "inv" can be used to invert boolean options. + +In both Vi and Vim you can create a line break with the ":substitute" command +by using a CTRL-M. For Vi this means you cannot insert a real CTRL-M in the +text. With Vim you can put a real CTRL-M in the text by preceding it with a +CTRL-V. + + +In Insert mode: + +If the 'revins' option is set, insert happens backwards. This is for typing +Hebrew. When inserting normal characters the cursor will not be shifted and +the text moves rightwards. Backspace, CTRL-W and CTRL-U will also work in +the opposite direction. CTRL-B toggles the 'revins' option. In replace mode +'revins' has no effect. Only when enabled at compile time. + +The backspace key can be used just like CTRL-D to remove auto-indents. + +You can backspace, CTRL-U and CTRL-W over line breaks if the 'backspace' (bs) +option includes "eol". You can backspace over the start of insert if the +'backspace' option includes "start". + +When the 'paste' option is set, a few options are reset and mapping in insert +mode and abbreviation are disabled. This allows for pasting text in windowing +systems without unexpected results. When the 'paste' option is reset, the old +option values are restored. + +CTRL-T/CTRL-D always insert/delete an indent in the current line, no matter +what column the cursor is in. + +CTRL-@ (insert previously inserted text) works always (Vi: only when typed as +first character). + +CTRL-A works like CTRL-@ but does not leave insert mode. + +CTRL-R {0-9a-z..} can be used to insert the contents of a register. + +When the 'smartindent' option is set, C programs will be better auto-indented. +With 'cindent' even more. + +CTRL-Y and CTRL-E can be used to copy a character from above/below the +current cursor position. + +After CTRL-V you can enter a three digit decimal number. This byte value is +inserted in the text as a single character. Useful for international +characters that are not on your keyboard. + +When the 'expandtab' (et) option is set, a <Tab> is expanded to the +appropriate number of spaces. + +The window always reflects the contents of the buffer (Vi does not do this +when changing text and in some other cases). + +If Vim is compiled with DIGRAPHS defined, digraphs are supported. A set of +normal digraphs is included. They are shown with the ":digraph" command. +More can be added with ":digraph {char1}{char2} {number}". A digraph is +entered with "CTRL-K {char1} {char2}" or "{char1} BS {char2}" (only when +'digraph' option is set). + +When repeating an insert, e.g. "10atest <Esc>" vi would only handle wrapmargin +for the first insert. Vim does it for all. + +A count to the "i" or "a" command is used for all the text. Vi uses the count +only for one line. "3iabc<NL>def<Esc>" would insert "abcabcabc<NL>def" in Vi +but "abc<NL>defabc<NL>defabc<NL>def" in Vim. + + +In Command-line mode: + +<Esc> terminates the command-line without executing it. In vi the command +line would be executed, which is not what most people expect (hitting <Esc> +should always get you back to command mode). To avoid problems with some +obscure macros, an <Esc> in a macro will execute the command. If you want a +typed <Esc> to execute the command like vi does you can fix this with + ":cmap ^V<Esc> ^V<CR>" + +General: + +The 'ttimeout' option is like 'timeout', but only works for cursor and +function keys, not for ordinary mapped characters. The 'timeoutlen' option +gives the number of milliseconds that is waited for. If the 'esckeys' option +is not set, cursor and function keys that start with <Esc> are not recognized +in insert mode. + +There is an option for each terminal string. Can be used when termcap is not +supported or to change individual strings. + +The 'fileformat' option can be set to select the <EOL>: "dos" <CR><NL>, "unix" +<NL> or "mac" <CR>. +When the 'fileformats' option is not empty, Vim tries to detect the type of +<EOL> automatically. The 'fileformat' option is set accordingly. + +On systems that have no job control (older Unix systems and non-Unix systems) +the CTRL-Z, ":stop" or ":suspend" command starts a new shell. + +If Vim is started on the Amiga without an interactive window for output, a +window is opened (and :sh still works). You can give a device to use for +editing with the |-d| argument, e.g. "-d con:20/20/600/150". + +The 'columns' and 'lines' options are used to set or get the width and height +of the display. + +Option settings are read from the first and last few lines of the file. +Option 'modelines' determines how many lines are tried (default is 5). Note +that this is different from the Vi versions that can execute any Ex command +in a modeline (a major security problem). |trojan-horse| + +If the 'insertmode' option is set (e.g. in .exrc), Vim starts in insert mode. +And it comes back there, when pressing <Esc>. + +Undo information is kept in memory. Available memory limits the number and +size of change that can be undone. This may be a problem with MS-DOS, is +hardly a problem on the Amiga and almost never with Unix and Win32. + +If the 'backup' or 'writebackup' option is set: Before a file is overwritten, +a backup file (.bak) is made. If the "backup" option is set it is left +behind. + +Vim creates a file ending in ".swp" to store parts of the file that have been +changed or that do not fit in memory. This file can be used to recover from +an aborted editing session with "vim -r file". Using the swap file can be +switched off by setting the 'updatecount' option to 0 or starting Vim with +the "-n" option. Use the 'directory' option for placing the .swp file +somewhere else. + +Vim is able to work correctly on filesystems with 8.3 file names, also when +using messydos or crossdos filesystems on the Amiga, or any 8.3 mounted +filesystem under Unix. See |'shortname'|. + +Error messages are shown at least one second (Vi overwrites error messages). + +If Vim gives the |hit-enter| prompt, you can hit any key. Characters other +than <CR>, <NL> and <Space> are interpreted as the (start of) a command. (Vi +only accepts a command starting with ':'). + +The contents of the numbered and unnamed registers is remembered when +changing files. + +The "No lines in buffer" message is a normal message instead of an error +message, since that may cause a mapping to be aborted. + +The AUX: device of the Amiga is supported. + +============================================================================== +6. Command-line arguments *cmdline-arguments* + +Different versions of Vi have different command-line arguments. This can be +confusing. To help you, this section gives an overview of the differences. + +Five variants of Vi will be considered here: + Elvis Elvis version 2.1b + Nvi Nvi version 1.79 + Posix Posix 1003.2 + Vi Vi version 3.7 (for Sun 4.1.x) + Vile Vile version 7.4 (incomplete) + Vim Vim version 5.2 + +Only Vim is able to accept options in between and after the file names. + ++{command} Elvis, Nvi, Posix, Vi, Vim: Same as "-c {command}". + +- Nvi, Posix, Vi: Run Ex in batch mode. + Vim: Read file from stdin (use -s for batch mode). + +-- Vim: End of options, only file names are following. + +--cmd {command} Vim: execute {command} before sourcing vimrc files. + +--echo-wid Vim: GTK+ echoes the Window ID on stdout + +--help Vim: show help message and exit. + +--literal Vim: take file names literally, don't expand wildcards. + +--nofork Vim: same as |-f| + +--noplugin[s] Vim: Skip loading plugins. + +--remote Vim: edit the files in another Vim server + +--remote-expr {expr} Vim: evaluate {expr} in another Vim server + +--remote-send {keys} Vim: send {keys} to a Vim server and exit + +--remote-silent {file} Vim: edit the files in another Vim server if possible + +--remote-wait Vim: edit the files in another Vim server and wait for it + +--remote-wait-silent Vim: like --remote-wait, no complaints if not possible + +--role {role} Vim: GTK+ 2: set role of main window + +--serverlist Vim: Output a list of Vim servers and exit + +--servername {name} Vim: Specify Vim server name + +--socketid {id} Vim: GTK window socket to run Vim in + +--windowid {id} Vim: Win32 window ID to run Vim in + +--version Vim: show version message and exit. + +-? Vile: print usage summary and exit. + +-a Elvis: Load all specified file names into a window (use -o for + Vim). + +-A Vim: Start in Arabic mode (when compiled with Arabic). + +-b {blksize} Elvis: Use {blksize} blocksize for the session file. +-b Vim: set 'binary' mode. + +-C Vim: Compatible mode. + +-c {command} Elvis, Nvi, Posix, Vim: run {command} as an Ex command after + loading the edit buffer. + Vim: allow up to 10 "-c" arguments + +-d {device} Vim: Use {device} for I/O (Amiga only). {only when compiled + without the |+diff| feature} +-d Vim: start with 'diff' set. |vimdiff| + +-dev {device} Vim: Use {device} for I/O (Amiga only). + +-D Vim: debug mode. + +-e Elvis, Nvi, Vim: Start in Ex mode, as if the executable is + called "ex". + +-E Vim: Start in improved Ex mode |gQ|, like "exim". + +-f Vim: Run GUI in foreground (Amiga: don't open new window). +-f {session} Elvis: Use {session} as the session file. + +-F Vim: Start in Farsi mode (when compiled with Farsi). + Nvi: Fast start, don't read the entire file when editing + starts. + +-G {gui} Elvis: Use the {gui} as user interface. + +-g Vim: Start GUI. +-g N Vile: start editing at line N + +-h Vim: Give help message. + Vile: edit the help file + +-H Vim: start Hebrew mode (when compiled with it). + +-i Elvis: Start each window in Insert mode. +-i {viminfo} Vim: Use {viminfo} for viminfo file. + +-L Vim: Same as "-r" (also in some versions of Vi). + +-l Nvi, Vi, Vim: Set 'lisp' and 'showmatch' options. + +-m Vim: Modifications not allowed to be written, resets 'write' + option. + +-M Vim: Modifications not allowed, resets 'modifiable' and the + 'write' option. + +-N Vim: No-compatible mode. + +-n Vim: No swap file used. + +-nb[args] Vim: open a NetBeans interface connection + +-O[N] Vim: Like -o, but use vertically split windows. + +-o[N] Vim: Open [N] windows, or one for each file. + +-p[N] Vim: Open [N] tab pages, or one for each file. + +-P {parent-title} Win32 Vim: open Vim inside a parent application window + +-q {name} Vim: Use {name} for quickfix error file. +-q{name} Vim: Idem. + +-R Elvis, Nvi, Posix, Vile, Vim: Set the 'readonly' option. + +-r Elvis, Nvi, Posix, Vi, Vim: Recovery mode. + +-S Nvi: Set 'secure' option. +-S {script} Vim: source script after starting up. + +-s Nvi, Posix, Vim: Same as "-" (silent mode), when in Ex mode. + Elvis: Sets the 'safer' option. +-s {scriptin} Vim: Read from script file {scriptin}; only when not in Ex + mode. +-s {pattern} Vile: search for {pattern} + +-t {tag} Elvis, Nvi, Posix, Vi, Vim: Edit the file containing {tag}. +-t{tag} Vim: Idem. + +-T {term} Vim: Set terminal name to {term}. + +-u {vimrc} Vim: Read initializations from {vimrc} file. + +-U {gvimrc} Vim: Read GUI initializations from {gvimrc} file. + +-v Nvi, Posix, Vi, Vim: Begin in Normal mode (visual mode, in Vi + terms). + Vile: View mode, no changes possible. + +-V Elvis, Vim: Verbose mode. +-V{nr} Vim: Verbose mode with specified level. + +-w {size} Elvis, Posix, Nvi, Vi, Vim: Set value of 'window' to {size}. +-w{size} Nvi, Vi: Same as "-w {size}". +-w {name} Vim: Write to script file {name} (must start with non-digit). + +-W {name} Vim: Append to script file {name}. + +-x Vi, Vim: Ask for encryption key. See |encryption|. + +-X Vim: Don't connect to the X server. + +-y Vim: Start in easy mode, like |evim|. + +-Z Vim: restricted mode + +@{cmdfile} Vile: use {cmdfile} as startup file. + +============================================================================== +7. POSIX compliance *posix* *posix-compliance* + +In 2005 the POSIX test suite was run to check the compatibility of Vim. Most +of the test was executed properly. There are the few things where Vim +is not POSIX compliant, even when run in Vi compatibility mode. + +Set the $VIM_POSIX environment variable to have 'cpoptions' include the POSIX +flags when Vim starts up. This makes Vim run as POSIX as it can. That's +a bit different from being Vi compatible. + +This is where Vim does not behave as POSIX specifies and why: + + *posix-screen-size* + The $COLUMNS and $LINES environment variables are ignored by Vim if + the size can be obtained from the terminal in a more reliable way. + Add the '|' flag to 'cpoptions' to have $COLUMNS and $LINES overrule + sizes obtained in another way. + + The "{" and "}" commands don't stop at a "{" in the original Vi, but + POSIX specifies it does. Add the '{' flag to 'cpoptions' if you want + it the POSIX way. + + The "D", "o" and "O" commands accept a count. Also when repeated. + Add the '#' flag to 'cpoptions' if you want to ignore the count. + + The ":cd" command fails if the current buffer is modified when the '.' + flag is present in 'cpoptions'. + + There is no ATTENTION message, the "A" flag is added to 'shortmess'. + +These are remarks about running the POSIX test suite: +- vi test 33 sometimes fails for unknown reasons +- vi test 250 fails; behavior will be changed in a new revision + http://www.opengroup.org/austin/mailarchives/ag-review/msg01710.html + (link no longer works, perhaps it's now: + https://www.opengroup.org/sophocles/show_mail.tpl?CALLER=show_archive.tpl&source=L&listname=austin-review-l&id=1711) +- vi test 310 fails; exit code non-zero when any error occurred? +- ex test 24 fails because test is wrong. Changed between SUSv2 and SUSv3. +- ex tests 47, 48, 49, 72, 73 fail because .exrc file isn't read in silent + mode and $EXINIT isn't used. +- ex tests 76, 78 fail because echo is used instead of printf. (fixed) + Also: problem with \s not changed to space. +- ex test 355 fails because 'window' isn't used for "30z". +- ex test 368 fails because shell command isn't echoed in silent mode. +- ex test 394 fails because "=" command output isn't visible in silent mode. +- ex test 411 fails because test file is wrong, contains stray ':'. +- ex test 475 and 476 fail because reprint output isn't visible in silent mode. +- ex test 480 and 481 fail because the tags file has spaces instead of a tab. +- ex test 502 fails because .exrc isn't read in silent mode. +- ex test 509 fails because .exrc isn't read in silent mode. and exit code is + 1 instead of 2. +- ex test 534 fails because .exrc isn't read in silent mode. + + + vim:tw=78:ts=8:ft=help:norl: diff --git a/en/visual.txt b/en/visual.txt new file mode 100644 index 000000000..fe47e996a --- /dev/null +++ b/en/visual.txt @@ -0,0 +1,540 @@ +*visual.txt* For Vim version 7.4. Last change: 2014 Mar 23 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Visual mode *Visual* *Visual-mode* *visual-mode* + +Visual mode is a flexible and easy way to select a piece of text for an +operator. It is the only way to select a block of text. + +This is introduced in section |04.4| of the user manual. + +1. Using Visual mode |visual-use| +2. Starting and stopping Visual mode |visual-start| +3. Changing the Visual area |visual-change| +4. Operating on the Visual area |visual-operators| +5. Blockwise operators |blockwise-operators| +6. Repeating |visual-repeat| +7. Examples |visual-examples| +8. Select mode |Select-mode| + +{Vi has no Visual mode, the name "visual" is used for Normal mode, to +distinguish it from Ex mode} +{Since Vim 7.4.200 the |+visual| feature is always included} + +============================================================================== +1. Using Visual mode *visual-use* + +Using Visual mode consists of three parts: +1. Mark the start of the text with "v", "V" or CTRL-V. + The character under the cursor will be used as the start. +2. Move to the end of the text. + The text from the start of the Visual mode up to and including the + character under the cursor is highlighted. +3. Type an operator command. + The highlighted characters will be operated upon. + +The 'highlight' option can be used to set the display mode to use for +highlighting in Visual mode. +The 'virtualedit' option can be used to allow positioning the cursor to +positions where there is no actual character. + +The highlighted text normally includes the character under the cursor. +However, when the 'selection' option is set to "exclusive" and the cursor is +after the Visual area, the character under the cursor is not included. + +With "v" the text before the start position and after the end position will +not be highlighted. However, all uppercase and non-alpha operators, except +"~" and "U", will work on whole lines anyway. See the list of operators +below. + + *visual-block* +With CTRL-V (blockwise Visual mode) the highlighted text will be a rectangle +between start position and the cursor. However, some operators work on whole +lines anyway (see the list below). The change and substitute operators will +delete the highlighted text and then start insertion at the top left +position. + +============================================================================== +2. Starting and stopping Visual mode *visual-start* + + *v* *characterwise-visual* +[count]v Start Visual mode per character. + With [count] select the same number of characters or + lines as used for the last Visual operation, but at + the current cursor position, multiplied by [count]. + When the previous Visual operation was on a block both + the width and height of the block are multiplied by + [count]. + When there was no previous Visual operation [count] + characters are selected. This is like moving the + cursor right N * [count] characters. One less when + 'selection' is not "exclusive". + + *V* *linewise-visual* +[count]V Start Visual mode linewise. + With [count] select the same number of lines as used + for the last Visual operation, but at the current + cursor position, multiplied by [count]. When there + was no previous Visual operation [count] lines are + selected. + + *CTRL-V* *blockwise-visual* +[count]CTRL-V Start Visual mode blockwise. Note: Under Windows + CTRL-V could be mapped to paste text, it doesn't work + to start Visual mode then, see |CTRL-V-alternative|. + [count] is used as with `v` above. + +If you use <Esc>, click the left mouse button or use any command that +does a jump to another buffer while in Visual mode, the highlighting stops +and no text is affected. Also when you hit "v" in characterwise Visual mode, +"CTRL-V" in blockwise Visual mode or "V" in linewise Visual mode. If you hit +CTRL-Z the highlighting stops and the editor is suspended or a new shell is +started |CTRL-Z|. + + new mode after typing: *v_v* *v_CTRL-V* *v_V* +old mode "v" "CTRL-V" "V" ~ + +Normal Visual blockwise Visual linewise Visual +Visual Normal blockwise Visual linewise Visual +blockwise Visual Visual Normal linewise Visual +linewise Visual Visual blockwise Visual Normal + + *gv* *v_gv* *reselect-Visual* +gv Start Visual mode with the same area as the previous + area and the same mode. + In Visual mode the current and the previous Visual + area are exchanged. + After using "p" or "P" in Visual mode the text that + was put will be selected. + + *gn* *v_gn* +gn Search forward for the last used search pattern, like + with `n`, and start Visual mode to select the match. + If the cursor is on the match, visually selects it. + If an operator is pending, operates on the match. + E.g., "dgn" deletes the text of the next match. + If Visual mode is active, extends the selection + until the end of the next match. + + *gN* *v_gN* +gN Like |gn| but searches backward, like with `N`. + + *<LeftMouse>* +<LeftMouse> Set the current cursor position. If Visual mode is + active it is stopped. Only when 'mouse' option is + contains 'n' or 'a'. If the position is within 'so' + lines from the last line on the screen the text is + scrolled up. If the position is within 'so' lines from + the first line on the screen the text is scrolled + down. + + *<RightMouse>* +<RightMouse> Start Visual mode if it is not active. The text from + the cursor position to the position of the click is + highlighted. If Visual mode was already active move + the start or end of the highlighted text, which ever + is closest, to the position of the click. Only when + 'mouse' option contains 'n' or 'a'. + + Note: when 'mousemodel' is set to "popup", + <S-LeftMouse> has to be used instead of <RightMouse>. + + *<LeftRelease>* +<LeftRelease> This works like a <LeftMouse>, if it is not at + the same position as <LeftMouse>. In an older version + of xterm you won't see the selected area until the + button is released, unless there is access to the + display where the xterm is running (via the DISPLAY + environment variable or the -display argument). Only + when 'mouse' option contains 'n' or 'a'. + +If Visual mode is not active and the "v", "V" or CTRL-V is preceded with a +count, the size of the previously highlighted area is used for a start. You +can then move the end of the highlighted area and give an operator. The type +of the old area is used (character, line or blockwise). +- Linewise Visual mode: The number of lines is multiplied with the count. +- Blockwise Visual mode: The number of lines and columns is multiplied with + the count. +- Normal Visual mode within one line: The number of characters is multiplied + with the count. +- Normal Visual mode with several lines: The number of lines is multiplied + with the count, in the last line the same number of characters is used as + in the last line in the previously highlighted area. +The start of the text is the Cursor position. If the "$" command was used as +one of the last commands to extend the highlighted text, the area will be +extended to the rightmost column of the longest line. + +If you want to highlight exactly the same area as the last time, you can use +"gv" |gv| |v_gv|. + + *v_<Esc>* +<Esc> In Visual mode: Stop Visual mode. + + *v_CTRL-C* +CTRL-C In Visual mode: Stop Visual mode. When insert mode is + pending (the mode message shows + "-- (insert) VISUAL --"), it is also stopped. + +============================================================================== +3. Changing the Visual area *visual-change* + + *v_o* +o Go to Other end of highlighted text: The current + cursor position becomes the start of the highlighted + text and the cursor is moved to the other end of the + highlighted text. The highlighted area remains the + same. + + *v_O* +O Go to Other end of highlighted text. This is like + "o", but in Visual block mode the cursor moves to the + other corner in the same line. When the corner is at + a character that occupies more than one position on + the screen (e.g., a <Tab>), the highlighted text may + change. + + *v_$* +When the "$" command is used with blockwise Visual mode, the right end of the +highlighted text will be determined by the longest highlighted line. This +stops when a motion command is used that does not move straight up or down. + +For moving the end of the block many commands can be used, but you cannot +use Ex commands, commands that make changes or abandon the file. Commands +(starting with) ".", "&", CTRL-^, "Z", CTRL-], CTRL-T, CTRL-R, CTRL-I +and CTRL-O cause a beep and Visual mode continues. + +When switching to another window on the same buffer, the cursor position in +that window is adjusted, so that the same Visual area is still selected. This +is especially useful to view the start of the Visual area in one window, and +the end in another. You can then use <RightMouse> (or <S-LeftMouse> when +'mousemodel' is "popup") to drag either end of the Visual area. + +============================================================================== +4. Operating on the Visual area *visual-operators* + +The operators that can be used are: + ~ switch case |v_~| + d delete |v_d| + c change (4) |v_c| + y yank |v_y| + > shift right (4) |v_>| + < shift left (4) |v_<| + ! filter through external command (1) |v_!| + = filter through 'equalprg' option command (1) |v_=| + gq format lines to 'textwidth' length (1) |v_gq| + +The objects that can be used are: + aw a word (with white space) |v_aw| + iw inner word |v_iw| + aW a WORD (with white space) |v_aW| + iW inner WORD |v_iW| + as a sentence (with white space) |v_as| + is inner sentence |v_is| + ap a paragraph (with white space) |v_ap| + ip inner paragraph |v_ip| + ab a () block (with parenthesis) |v_ab| + ib inner () block |v_ib| + aB a {} block (with braces) |v_aB| + iB inner {} block |v_iB| + at a <tag> </tag> block (with tags) |v_at| + it inner <tag> </tag> block |v_it| + a< a <> block (with <>) |v_a<| + i< inner <> block |v_i<| + a[ a [] block (with []) |v_a[| + i[ inner [] block |v_i[| + a" a double quoted string (with quotes) |v_aquote| + i" inner double quoted string |v_iquote| + a' a single quoted string (with quotes) |v_a'| + i' inner simple quoted string |v_i'| + a` a string in backticks (with backticks) |v_a`| + i` inner string in backticks |v_i`| + +Additionally the following commands can be used: + : start Ex command for highlighted lines (1) |v_:| + r change (4) |v_r| + s change |v_s| + C change (2)(4) |v_C| + S change (2) |v_S| + R change (2) |v_R| + x delete |v_x| + D delete (3) |v_D| + X delete (2) |v_X| + Y yank (2) |v_Y| + p put |v_p| + J join (1) |v_J| + U make uppercase |v_U| + u make lowercase |v_u| + ^] find tag |v_CTRL-]| + I block insert |v_b_I| + A block append |v_b_A| + +(1): Always whole lines, see |:visual_example|. +(2): Whole lines when not using CTRL-V. +(3): Whole lines when not using CTRL-V, delete until the end of the line when + using CTRL-V. +(4): When using CTRL-V operates on the block only. + +Note that the ":vmap" command can be used to specifically map keys in Visual +mode. For example, if you would like the "/" command not to extend the Visual +area, but instead take the highlighted text and search for that: > + :vmap / y/<C-R>"<CR> +(In the <> notation |<>|, when typing it you should type it literally; you +need to remove the 'B' and '<' flags from 'cpoptions'.) + +If you want to give a register name using the """ command, do this just before +typing the operator character: "v{move-around}"xd". + +If you want to give a count to the command, do this just before typing the +operator character: "v{move-around}3>" (move lines 3 indents to the right). + + *{move-around}* +The {move-around} is any sequence of movement commands. Note the difference +with {motion}, which is only ONE movement command. + +Another way to operate on the Visual area is using the |/\%V| item in a +pattern. For example, to replace all '(' in the Visual area with '#': > + + :'<,'>s/\%V(/#/g + +Note that the "'<,'>" will appear automatically when you press ":" in Visual +mode. + +============================================================================== +5. Blockwise operators *blockwise-operators* + +{not available when compiled without the |+visualextra| feature} + +Reminder: Use 'virtualedit' to be able to select blocks that start or end +after the end of a line or halfway a tab. + +Visual-block Insert *v_b_I* +With a blockwise selection, I{string}<ESC> will insert {string} at the start +of block on every line of the block, provided that the line extends into the +block. Thus lines that are short will remain unmodified. TABs are split to +retain visual columns. +See |v_b_I_example|. + +Visual-block Append *v_b_A* +With a blockwise selection, A{string}<ESC> will append {string} to the end of +block on every line of the block. There is some differing behavior where the +block RHS is not straight, due to different line lengths: + +1. Block was created with <C-v>$ + In this case the string is appended to the end of each line. +2. Block was created with <C-v>{move-around} + In this case the string is appended to the end of the block on each line, + and whitespace is inserted to pad to the end-of-block column. +See |v_b_A_example|. +Note: "I" and "A" behave differently for lines that don't extend into the +selected block. This was done intentionally, so that you can do it the way +you want. + +Visual-block change *v_b_c* +All selected text in the block will be replaced by the same text string. When +using "c" the selected text is deleted and Insert mode started. You can then +enter text (without a line break). When you hit <Esc>, the same string is +inserted in all previously selected lines. + +Visual-block Change *v_b_C* +Like using "c", but the selection is extended until the end of the line for +all lines. + + *v_b_<* +Visual-block Shift *v_b_>* +The block is shifted by 'shiftwidth'. The RHS of the block is irrelevant. The +LHS of the block determines the point from which to apply a right shift, and +padding includes TABs optimally according to 'ts' and 'et'. The LHS of the +block determines the point upto which to shift left. +See |v_b_>_example|. +See |v_b_<_example|. + +Visual-block Replace *v_b_r* +Every screen char in the highlighted region is replaced with the same char, ie +TABs are split and the virtual whitespace is replaced, maintaining screen +layout. +See |v_b_r_example|. + + +============================================================================== +6. Repeating *visual-repeat* + +When repeating a Visual mode operator, the operator will be applied to the +same amount of text as the last time: +- Linewise Visual mode: The same number of lines. +- Blockwise Visual mode: The same number of lines and columns. +- Normal Visual mode within one line: The same number of characters. +- Normal Visual mode with several lines: The same number of lines, in the + last line the same number of characters as in the last line the last time. +The start of the text is the Cursor position. If the "$" command was used as +one of the last commands to extend the highlighted text, the repeating will +be applied up to the rightmost column of the longest line. + + +============================================================================== +7. Examples *visual-examples* + + *:visual_example* +Currently the ":" command works on whole lines only. When you select part of +a line, doing something like ":!date" will replace the whole line. If you +want only part of the line to be replaced you will have to make a mapping for +it. In a future release ":" may work on partial lines. + +Here is an example, to replace the selected text with the output of "date": > + :vmap _a <Esc>`>a<CR><Esc>`<i<CR><Esc>!!date<CR>kJJ + +(In the <> notation |<>|, when typing it you should type it literally; you +need to remove the 'B' and '<' flags from 'cpoptions') + +What this does is: +<Esc> stop Visual mode +`> go to the end of the Visual area +a<CR><Esc> break the line after the Visual area +`< jump to the start of the Visual area +i<CR><Esc> break the line before the Visual area +!!date<CR> filter the Visual text through date +kJJ Join the lines back together + + *visual-search* +Here is an idea for a mapping that makes it possible to do a search for the +selected text: > + :vmap X y/<C-R>"<CR> + +(In the <> notation |<>|, when typing it you should type it literally; you +need to remove the 'B' and '<' flags from 'cpoptions') + +Note that special characters (like '.' and '*') will cause problems. + +Visual-block Examples *blockwise-examples* +With the following text, I will indicate the commands to produce the block and +the results below. In all cases, the cursor begins on the 'a' in the first +line of the test text. +The following modeline settings are assumed ":ts=8:sw=4:". + +It will be helpful to +:set hls +/<TAB> +where <TAB> is a real TAB. This helps visualise the operations. + +The test text is: + +abcdefghijklmnopqrstuvwxyz +abc defghijklmnopqrstuvwxyz +abcdef ghi jklmnopqrstuvwxyz +abcdefghijklmnopqrstuvwxyz + +1. fo<C-v>3jISTRING<ESC> *v_b_I_example* + +abcdefghijklmnSTRINGopqrstuvwxyz +abc STRING defghijklmnopqrstuvwxyz +abcdef ghi STRING jklmnopqrstuvwxyz +abcdefghijklmnSTRINGopqrstuvwxyz + +2. fo<C-v>3j$ASTRING<ESC> *v_b_A_example* + +abcdefghijklmnopqrstuvwxyzSTRING +abc defghijklmnopqrstuvwxyzSTRING +abcdef ghi jklmnopqrstuvwxyzSTRING +abcdefghijklmnopqrstuvwxyzSTRING + +3. fo<C-v>3j3l<.. *v_b_<_example* + +abcdefghijklmnopqrstuvwxyz +abc defghijklmnopqrstuvwxyz +abcdef ghi jklmnopqrstuvwxyz +abcdefghijklmnopqrstuvwxyz + +4. fo<C-v>3j>.. *v_b_>_example* + +abcdefghijklmn opqrstuvwxyz +abc defghijklmnopqrstuvwxyz +abcdef ghi jklmnopqrstuvwxyz +abcdefghijklmn opqrstuvwxyz + +5. fo<C-v>5l3jrX *v_b_r_example* + +abcdefghijklmnXXXXXXuvwxyz +abc XXXXXXhijklmnopqrstuvwxyz +abcdef ghi XXXXXX jklmnopqrstuvwxyz +abcdefghijklmnXXXXXXuvwxyz + +============================================================================== +8. Select mode *Select* *Select-mode* + +Select mode looks like Visual mode, but the commands accepted are quite +different. This resembles the selection mode in Microsoft Windows. +When the 'showmode' option is set, "-- SELECT --" is shown in the last line. + +Entering Select mode: +- Using the mouse to select an area, and 'selectmode' contains "mouse". + 'mouse' must also contain a flag for the current mode. +- Using a non-printable movement command, with the Shift key pressed, and + 'selectmode' contains "key". For example: <S-Left> and <S-End>. 'keymodel' + must also contain "startsel". +- Using "v", "V" or CTRL-V command, and 'selectmode' contains "cmd". +- Using "gh", "gH" or "g_CTRL-H" command in Normal mode. +- From Visual mode, press CTRL-G. *v_CTRL-G* + +Commands in Select mode: +- Printable characters, <NL> and <CR> cause the selection to be deleted, and + Vim enters Insert mode. The typed character is inserted. +- Non-printable movement commands, with the Shift key pressed, extend the + selection. 'keymodel' must include "startsel". +- Non-printable movement commands, with the Shift key NOT pressed, stop Select + mode. 'keymodel' must include "stopsel". +- ESC stops Select mode. +- CTRL-O switches to Visual mode for the duration of one command. *v_CTRL-O* +- CTRL-G switches to Visual mode. + +Otherwise, typed characters are handled as in Visual mode. + +When using an operator in Select mode, and the selection is linewise, the +selected lines are operated upon, but like in characterwise selection. For +example, when a whole line is deleted, it can later be pasted halfway a line. + + +Mappings and menus in Select mode. *Select-mode-mapping* + +When mappings and menus are defined with the |:vmap| or |:vmenu| command they +work both in Visual mode and in Select mode. When these are used in Select +mode Vim automatically switches to Visual mode, so that the same behavior as +in Visual mode is effective. If you don't want this use |:xmap| or |:smap|. + +Users will expect printable characters to replace the selected area. +Therefore avoid mapping printable characters in Select mode. Or use +|:sunmap| after |:map| and |:vmap| to remove it for Select mode. + +After the mapping or menu finishes, the selection is enabled again and Select +mode entered, unless the selected area was deleted, another buffer became +the current one or the window layout was changed. + +When a character was typed that causes the selection to be deleted and Insert +mode started, Insert mode mappings are applied to this character. This may +cause some confusion, because it means Insert mode mappings apply to a +character typed in Select mode. Language mappings apply as well. + + *gV* *v_gV* +gV Avoid the automatic reselection of the Visual area + after a Select mode mapping or menu has finished. + Put this just before the end of the mapping or menu. + At least it should be after any operations on the + selection. + + *gh* +gh Start Select mode, characterwise. This is like "v", + but starts Select mode instead of Visual mode. + Mnemonic: "get highlighted". + + *gH* +gH Start Select mode, linewise. This is like "V", + but starts Select mode instead of Visual mode. + Mnemonic: "get Highlighted". + + *g_CTRL-H* +g CTRL-H Start Select mode, blockwise. This is like CTRL-V, + but starts Select mode instead of Visual mode. + Mnemonic: "get Highlighted". + + vim:tw=78:ts=8:ft=help:norl: diff --git a/en/windows.txt b/en/windows.txt new file mode 100644 index 000000000..f6e0a1fd0 --- /dev/null +++ b/en/windows.txt @@ -0,0 +1,1284 @@ +*windows.txt* For Vim version 7.4. Last change: 2015 Nov 14 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Editing with multiple windows and buffers. *windows* *buffers* + +The commands which have been added to use multiple windows and buffers are +explained here. Additionally, there are explanations for commands that work +differently when used in combination with more than one window. + +The basics are explained in chapter 7 and 8 of the user manual |usr_07.txt| +|usr_08.txt|. + +1. Introduction |windows-intro| +2. Starting Vim |windows-starting| +3. Opening and closing a window |opening-window| +4. Moving cursor to other windows |window-move-cursor| +5. Moving windows around |window-moving| +6. Window resizing |window-resize| +7. Argument and buffer list commands |buffer-list| +8. Do a command in all buffers or windows |list-repeat| +9. Tag or file name under the cursor |window-tag| +10. The preview window |preview-window| +11. Using hidden buffers |buffer-hidden| +12. Special kinds of buffers |special-buffers| + +{Vi does not have any of these commands} +{not able to use multiple windows when the |+windows| feature was disabled at +compile time} +{not able to use vertically split windows when the |+vertsplit| feature was +disabled at compile time} + +============================================================================== +1. Introduction *windows-intro* *window* + +Summary: + A buffer is the in-memory text of a file. + A window is a viewport on a buffer. + A tab page is a collection of windows. + +A window is a viewport onto a buffer. You can use multiple windows on one +buffer, or several windows on different buffers. + +A buffer is a file loaded into memory for editing. The original file remains +unchanged until you write the buffer to the file. + +A buffer can be in one of three states: + + *active-buffer* +active: The buffer is displayed in a window. If there is a file for this + buffer, it has been read into the buffer. The buffer may have been + modified since then and thus be different from the file. + *hidden-buffer* +hidden: The buffer is not displayed. If there is a file for this buffer, it + has been read into the buffer. Otherwise it's the same as an active + buffer, you just can't see it. + *inactive-buffer* +inactive: The buffer is not displayed and does not contain anything. Options + for the buffer are remembered if the file was once loaded. It can + contain marks from the |viminfo| file. But the buffer doesn't + contain text. + +In a table: + +state displayed loaded ":buffers" ~ + in window shows ~ +active yes yes 'a' +hidden no yes 'h' +inactive no no ' ' + +Note: All CTRL-W commands can also be executed with |:wincmd|, for those +places where a Normal mode command can't be used or is inconvenient. + +The main Vim window can hold several split windows. There are also tab pages +|tab-page|, each of which can hold multiple windows. + +============================================================================== +2. Starting Vim *windows-starting* + +By default, Vim starts with one window, just like Vi. + +The "-o" and "-O" arguments to Vim can be used to open a window for each file +in the argument list. The "-o" argument will split the windows horizontally; +the "-O" argument will split the windows vertically. If both "-o" and "-O" +are given, the last one encountered will be used to determine the split +orientation. For example, this will open three windows, split horizontally: > + vim -o file1 file2 file3 + +"-oN", where N is a decimal number, opens N windows split horizontally. If +there are more file names than windows, only N windows are opened and some +files do not get a window. If there are more windows than file names, the +last few windows will be editing empty buffers. Similarly, "-ON" opens N +windows split vertically, with the same restrictions. + +If there are many file names, the windows will become very small. You might +want to set the 'winheight' and/or 'winwidth' options to create a workable +situation. + +Buf/Win Enter/Leave |autocommand|s are not executed when opening the new +windows and reading the files, that's only done when they are really entered. + + *status-line* +A status line will be used to separate windows. The 'laststatus' option tells +when the last window also has a status line: + 'laststatus' = 0 never a status line + 'laststatus' = 1 status line if there is more than one window + 'laststatus' = 2 always a status line + +You can change the contents of the status line with the 'statusline' option. +This option can be local to the window, so that you can have a different +status line in each window. + +Normally, inversion is used to display the status line. This can be changed +with the 's' character in the 'highlight' option. For example, "sb" sets it to +bold characters. If no highlighting is used for the status line ("sn"), the +'^' character is used for the current window, and '=' for other windows. If +the mouse is supported and enabled with the 'mouse' option, a status line can +be dragged to resize windows. + +Note: If you expect your status line to be in reverse video and it isn't, +check if the 'highlight' option contains "si". In version 3.0, this meant to +invert the status line. Now it should be "sr", reverse the status line, as +"si" now stands for italic! If italic is not available on your terminal, the +status line is inverted anyway; you will only see this problem on terminals +that have termcap codes for italics. + +============================================================================== +3. Opening and closing a window *opening-window* *E36* + +CTRL-W s *CTRL-W_s* +CTRL-W S *CTRL-W_S* +CTRL-W CTRL-S *CTRL-W_CTRL-S* +:[N]sp[lit] [++opt] [+cmd] [file] *:sp* *:split* + Split current window in two. The result is two viewports on + the same file. + + Make the new window N high (default is to use half the height + of the current window). Reduces the current window height to + create room (and others, if the 'equalalways' option is set, + 'eadirection' isn't "hor", and one of them is higher than the + current or the new window). + + If [file] is given it will be edited in the new window. If it + is not loaded in any buffer, it will be read. Else the new + window will use the already loaded buffer. + + Note: CTRL-S does not work on all terminals and might block + further input, use CTRL-Q to get going again. + Also see |++opt| and |+cmd|. + +CTRL-W CTRL-V *CTRL-W_CTRL-V* +CTRL-W v *CTRL-W_v* +:[N]vs[plit] [++opt] [+cmd] [file] *:vs* *:vsplit* + Like |:split|, but split vertically. The windows will be + spread out horizontally if + 1. a width was not specified, + 2. 'equalalways' is set, + 3. 'eadirection' isn't "ver", and + 4. one of the other windows is wider than the current or new + window. + Note: In other places CTRL-Q does the same as CTRL-V, but here + it doesn't! + +CTRL-W n *CTRL-W_n* +CTRL-W CTRL_N *CTRL-W_CTRL-N* +:[N]new [++opt] [+cmd] *:new* + Create a new window and start editing an empty file in it. + Make new window N high (default is to use half the existing + height). Reduces the current window height to create room (and + others, if the 'equalalways' option is set and 'eadirection' + isn't "hor"). + Also see |++opt| and |+cmd|. + If 'fileformats' is not empty, the first format given will be + used for the new buffer. If 'fileformats' is empty, the + 'fileformat' of the current buffer is used. This can be + overridden with the |++opt| argument. + Autocommands are executed in this order: + 1. WinLeave for the current window + 2. WinEnter for the new window + 3. BufLeave for the current buffer + 4. BufEnter for the new buffer + This behaves like a ":split" first, and then an ":enew" + command. + +:[N]vne[w] [++opt] [+cmd] [file] *:vne* *:vnew* + Like |:new|, but split vertically. If 'equalalways' is set + and 'eadirection' isn't "ver" the windows will be spread out + horizontally, unless a width was specified. + +:[N]new [++opt] [+cmd] {file} +:[N]sp[lit] [++opt] [+cmd] {file} *:split_f* + Create a new window and start editing file {file} in it. This + behaves like a ":split" first, and then an ":e" command. + If [+cmd] is given, execute the command when the file has been + loaded |+cmd|. + Also see |++opt|. + Make new window N high (default is to use half the existing + height). Reduces the current window height to create room + (and others, if the 'equalalways' option is set). + +:[N]sv[iew] [++opt] [+cmd] {file} *:sv* *:sview* *splitview* + Same as ":split", but set 'readonly' option for this buffer. + +:[N]sf[ind] [++opt] [+cmd] {file} *:sf* *:sfind* *splitfind* + Same as ":split", but search for {file} in 'path' like in + |:find|. Doesn't split if {file} is not found. + +CTRL-W CTRL-^ *CTRL-W_CTRL-^* *CTRL-W_^* +CTRL-W ^ Does ":split #", split window in two and edit alternate file. + When a count is given, it becomes ":split #N", split window + and edit buffer N. + +Note that the 'splitbelow' and 'splitright' options influence where a new +window will appear. + + *:vert* *:vertical* +:vert[ical] {cmd} + Execute {cmd}. If it contains a command that splits a window, + it will be split vertically. + Doesn't work for |:execute| and |:normal|. + +:lefta[bove] {cmd} *:lefta* *:leftabove* +:abo[veleft] {cmd} *:abo* *:aboveleft* + Execute {cmd}. If it contains a command that splits a window, + it will be opened left (vertical split) or above (horizontal + split) the current window. Overrules 'splitbelow' and + 'splitright'. + Doesn't work for |:execute| and |:normal|. + +:rightb[elow] {cmd} *:rightb* *:rightbelow* +:bel[owright] {cmd} *:bel* *:belowright* + Execute {cmd}. If it contains a command that splits a window, + it will be opened right (vertical split) or below (horizontal + split) the current window. Overrules 'splitbelow' and + 'splitright'. + Doesn't work for |:execute| and |:normal|. + + *:topleft* *E442* +:to[pleft] {cmd} + Execute {cmd}. If it contains a command that splits a window, + it will appear at the top and occupy the full width of the Vim + window. When the split is vertical the window appears at the + far left and occupies the full height of the Vim window. + Doesn't work for |:execute| and |:normal|. + + *:botright* +:bo[tright] {cmd} + Execute {cmd}. If it contains a command that splits a window, + it will appear at the bottom and occupy the full width of the + Vim window. When the split is vertical the window appears at + the far right and occupies the full height of the Vim window. + Doesn't work for |:execute| and |:normal|. + +These command modifiers can be combined to make a vertically split window +occupy the full height. Example: > + :vertical topleft split tags +Opens a vertically split, full-height window on the "tags" file at the far +left of the Vim window. + + +Closing a window +---------------- + +:q[uit] +:{count}q[uit] +CTRL-W q *CTRL-W_q* +CTRL-W CTRL-Q *CTRL-W_CTRL-Q* + Without {count}: Quit the current window. If {count} is + given quit the {count} window. + + When quitting the last window (not counting a help window), + exit Vim. + + When 'hidden' is set, and there is only one window for the + current buffer, it becomes hidden. When 'hidden' is not set, + and there is only one window for the current buffer, and the + buffer was changed, the command fails. + + (Note: CTRL-Q does not work on all terminals). + + If [count] is greater than the last window number the last + window will be closed: > + :1quit " quit the first window + :$quit " quit the last window + :9quit " quit the last window + " if there are less than 9 windows opened + :-quit " quit the previews window + :+quit " quit the next window + :+2quit " quit the second next window +< +:q[uit]! +:{count}q[uit]! + Without {count}: Quit the current window. If {count} is + given quit the {count} window. + + If this was the last window for a buffer, any changes to that + buffer are lost. When quitting the last window (not counting + help windows), exit Vim. The contents of the buffer are lost, + even when 'hidden' is set. + +:clo[se][!] +:{count}clo[se][!] +CTRL-W c *CTRL-W_c* *:clo* *:close* + Without {count}: Close the current window. If {count} is + given close the {count} window. + + When the 'hidden' option is set, or when the buffer was + changed and the [!] is used, the buffer becomes hidden (unless + there is another window editing it). + + When there is only one window in the current tab page and + there is another tab page, this closes the current tab page. + |tab-page|. + + This command fails when: *E444* + - There is only one window on the screen. + - When 'hidden' is not set, [!] is not used, the buffer has + changes, and there is no other window on this buffer. + Changes to the buffer are not written and won't get lost, so + this is a "safe" command. + +CTRL-W CTRL-C *CTRL-W_CTRL-C* + You might have expected that CTRL-W CTRL-C closes the current + window, but that does not work, because the CTRL-C cancels the + command. + + *:hide* +:hid[e] +:{count}hid[e] + Quit the current window, unless it is the last window on the + screen. For {count} see |:quit| command. + + The buffer becomes hidden (unless there is another window + editing it or 'bufhidden' is "unload", "delete" or "wipe"). + If the window is the last one in the current tab page the tab + page is closed. |tab-page| + + The value of 'hidden' is irrelevant for this command. Changes + to the buffer are not written and won't get lost, so this is a + "safe" command. + +:hid[e] {cmd} Execute {cmd} with 'hidden' is set. The previous value of + 'hidden' is restored after {cmd} has been executed. + Example: > + :hide edit Makefile +< This will edit "Makefile", and hide the current buffer if it + has any changes. + +:on[ly][!] +:{count}on[ly][!] +CTRL-W o *CTRL-W_o* *E445* +CTRL-W CTRL-O *CTRL-W_CTRL-O* *:on* *:only* + Make the current window the only one on the screen. All other + windows are closed. For {count} see |:quit| command. + + When the 'hidden' option is set, all buffers in closed windows + become hidden. + + When 'hidden' is not set, and the 'autowrite' option is set, + modified buffers are written. Otherwise, windows that have + buffers that are modified are not removed, unless the [!] is + given, then they become hidden. But modified buffers are + never abandoned, so changes cannot get lost. + +============================================================================== +4. Moving cursor to other windows *window-move-cursor* + +CTRL-W <Down> *CTRL-W_<Down>* +CTRL-W CTRL-J *CTRL-W_CTRL-J* *CTRL-W_j* +CTRL-W j Move cursor to Nth window below current one. Uses the cursor + position to select between alternatives. + +CTRL-W <Up> *CTRL-W_<Up>* +CTRL-W CTRL-K *CTRL-W_CTRL-K* *CTRL-W_k* +CTRL-W k Move cursor to Nth window above current one. Uses the cursor + position to select between alternatives. + +CTRL-W <Left> *CTRL-W_<Left>* +CTRL-W CTRL-H *CTRL-W_CTRL-H* +CTRL-W <BS> *CTRL-W_<BS>* *CTRL-W_h* +CTRL-W h Move cursor to Nth window left of current one. Uses the + cursor position to select between alternatives. + +CTRL-W <Right> *CTRL-W_<Right>* +CTRL-W CTRL-L *CTRL-W_CTRL-L* *CTRL-W_l* +CTRL-W l Move cursor to Nth window right of current one. Uses the + cursor position to select between alternatives. + +CTRL-W w *CTRL-W_w* *CTRL-W_CTRL-W* +CTRL-W CTRL-W Without count: move cursor to window below/right of the + current one. If there is no window below or right, go to + top-left window. + With count: go to Nth window (windows are numbered from + top-left to bottom-right). To obtain the window number see + |bufwinnr()| and |winnr()|. When N is larger than the number + of windows go to the last window. + + *CTRL-W_W* +CTRL-W W Without count: move cursor to window above/left of current + one. If there is no window above or left, go to bottom-right + window. With count: go to Nth window, like with CTRL-W w. + +CTRL-W t *CTRL-W_t* *CTRL-W_CTRL-T* +CTRL-W CTRL-T Move cursor to top-left window. + +CTRL-W b *CTRL-W_b* *CTRL-W_CTRL-B* +CTRL-W CTRL-B Move cursor to bottom-right window. + +CTRL-W p *CTRL-W_p* *CTRL-W_CTRL-P* +CTRL-W CTRL-P Go to previous (last accessed) window. + + *CTRL-W_P* *E441* +CTRL-W P Go to preview window. When there is no preview window this is + an error. + {not available when compiled without the |+quickfix| feature} + +If Visual mode is active and the new window is not for the same buffer, the +Visual mode is ended. If the window is on the same buffer, the cursor +position is set to keep the same Visual area selected. + + *:winc* *:wincmd* +These commands can also be executed with ":wincmd": + +:[count]winc[md] {arg} + Like executing CTRL-W [count] {arg}. Example: > + :wincmd j +< Moves to the window below the current one. + This command is useful when a Normal mode cannot be used (for + the |CursorHold| autocommand event). Or when a Normal mode + command is inconvenient. + The count can also be a window number. Example: > + :exe nr . "wincmd w" +< This goes to window "nr". + +============================================================================== +5. Moving windows around *window-moving* + +CTRL-W r *CTRL-W_r* *CTRL-W_CTRL-R* *E443* +CTRL-W CTRL-R Rotate windows downwards/rightwards. The first window becomes + the second one, the second one becomes the third one, etc. + The last window becomes the first window. The cursor remains + in the same window. + This only works within the row or column of windows that the + current window is in. + + *CTRL-W_R* +CTRL-W R Rotate windows upwards/leftwards. The second window becomes + the first one, the third one becomes the second one, etc. The + first window becomes the last window. The cursor remains in + the same window. + This only works within the row or column of windows that the + current window is in. + +CTRL-W x *CTRL-W_x* *CTRL-W_CTRL-X* +CTRL-W CTRL-X Without count: Exchange current window with next one. If there + is no next window, exchange with previous window. + With count: Exchange current window with Nth window (first + window is 1). The cursor is put in the other window. + When vertical and horizontal window splits are mixed, the + exchange is only done in the row or column of windows that the + current window is in. + +The following commands can be used to change the window layout. For example, +when there are two vertically split windows, CTRL-W K will change that in +horizontally split windows. CTRL-W H does it the other way around. + + *CTRL-W_K* +CTRL-W K Move the current window to be at the very top, using the full + width of the screen. This works like closing the current + window and then creating another one with ":topleft split", + except that the current window contents is used for the new + window. + + *CTRL-W_J* +CTRL-W J Move the current window to be at the very bottom, using the + full width of the screen. This works like closing the current + window and then creating another one with ":botright split", + except that the current window contents is used for the new + window. + + *CTRL-W_H* +CTRL-W H Move the current window to be at the far left, using the + full height of the screen. This works like closing the + current window and then creating another one with + ":vert topleft split", except that the current window contents + is used for the new window. + {not available when compiled without the |+vertsplit| feature} + + *CTRL-W_L* +CTRL-W L Move the current window to be at the far right, using the full + height of the screen. This works like closing the + current window and then creating another one with + ":vert botright split", except that the current window + contents is used for the new window. + {not available when compiled without the |+vertsplit| feature} + + *CTRL-W_T* +CTRL-W T Move the current window to a new tab page. This fails if + there is only one window in the current tab page. + When a count is specified the new tab page will be opened + before the tab page with this index. Otherwise it comes after + the current tab page. + +============================================================================== +6. Window resizing *window-resize* + + *CTRL-W_=* +CTRL-W = Make all windows (almost) equally high and wide, but use + 'winheight' and 'winwidth' for the current window. + Windows with 'winfixheight' set keep their height and windows + with 'winfixwidth' set keep their width. + +:res[ize] -N *:res* *:resize* *CTRL-W_-* +CTRL-W - Decrease current window height by N (default 1). + If used after |:vertical|: decrease width by N. + +:res[ize] +N *CTRL-W_+* +CTRL-W + Increase current window height by N (default 1). + If used after |:vertical|: increase width by N. + +:res[ize] [N] +CTRL-W CTRL-_ *CTRL-W_CTRL-_* *CTRL-W__* +CTRL-W _ Set current window height to N (default: highest possible). + +z{nr}<CR> Set current window height to {nr}. + + *CTRL-W_<* +CTRL-W < Decrease current window width by N (default 1). + + *CTRL-W_>* +CTRL-W > Increase current window width by N (default 1). + +:vertical res[ize] [N] *:vertical-resize* *CTRL-W_bar* +CTRL-W | Set current window width to N (default: widest possible). + +You can also resize a window by dragging a status line up or down with the +mouse. Or by dragging a vertical separator line left or right. This only +works if the version of Vim that is being used supports the mouse and the +'mouse' option has been set to enable it. + +The option 'winheight' ('wh') is used to set the minimal window height of the +current window. This option is used each time another window becomes the +current window. If the option is '0', it is disabled. Set 'winheight' to a +very large value, e.g., '9999', to make the current window always fill all +available space. Set it to a reasonable value, e.g., '10', to make editing in +the current window comfortable. + +The equivalent 'winwidth' ('wiw') option is used to set the minimal width of +the current window. + +When the option 'equalalways' ('ea') is set, all the windows are automatically +made the same size after splitting or closing a window. If you don't set this +option, splitting a window will reduce the size of the current window and +leave the other windows the same. When closing a window, the extra lines are +given to the window above it. + +The 'eadirection' option limits the direction in which the 'equalalways' +option is applied. The default "both" resizes in both directions. When the +value is "ver" only the heights of windows are equalized. Use this when you +have manually resized a vertically split window and want to keep this width. +Likewise, "hor" causes only the widths of windows to be equalized. + +The option 'cmdheight' ('ch') is used to set the height of the command-line. +If you are annoyed by the |hit-enter| prompt for long messages, set this +option to 2 or 3. + +If there is only one window, resizing that window will also change the command +line height. If there are several windows, resizing the current window will +also change the height of the window below it (and sometimes the window above +it). + +The minimal height and width of a window is set with 'winminheight' and +'winminwidth'. These are hard values, a window will never become smaller. + +============================================================================== +7. Argument and buffer list commands *buffer-list* + + args list buffer list meaning ~ +1. :[N]argument [N] 11. :[N]buffer [N] to arg/buf N +2. :[N]next [file ..] 12. :[N]bnext [N] to Nth next arg/buf +3. :[N]Next [N] 13. :[N]bNext [N] to Nth previous arg/buf +4. :[N]previous [N] 14. :[N]bprevious [N] to Nth previous arg/buf +5. :rewind / :first 15. :brewind / :bfirst to first arg/buf +6. :last 16. :blast to last arg/buf +7. :all 17. :ball edit all args/buffers + 18. :unhide edit all loaded buffers + 19. :[N]bmod [N] to Nth modified buf + + split & args list split & buffer list meaning ~ +21. :[N]sargument [N] 31. :[N]sbuffer [N] split + to arg/buf N +22. :[N]snext [file ..] 32. :[N]sbnext [N] split + to Nth next arg/buf +23. :[N]sNext [N] 33. :[N]sbNext [N] split + to Nth previous arg/buf +24. :[N]sprevious [N] 34. :[N]sbprevious [N] split + to Nth previous arg/buf +25. :srewind / :sfirst 35. :sbrewind / :sbfirst split + to first arg/buf +26. :slast 36. :sblast split + to last arg/buf +27. :sall 37. :sball edit all args/buffers + 38. :sunhide edit all loaded buffers + 39. :[N]sbmod [N] split + to Nth modified buf + +40. :args list of arguments +41. :buffers list of buffers + +The meaning of [N] depends on the command: + [N] is number of buffers to go forward/backward on ?2, ?3, and ?4 + [N] is an argument number, defaulting to current argument, for 1 and 21 + [N] is a buffer number, defaulting to current buffer, for 11 and 31 + [N] is a count for 19 and 39 + +Note: ":next" is an exception, because it must accept a list of file names +for compatibility with Vi. + + +The argument list and multiple windows +-------------------------------------- + +The current position in the argument list can be different for each window. +Remember that when doing ":e file", the position in the argument list stays +the same, but you are not editing the file at that position. To indicate +this, the file message (and the title, if you have one) shows +"(file (N) of M)", where "(N)" is the current position in the file list, and +"M" the number of files in the file list. + +All the entries in the argument list are added to the buffer list. Thus, you +can also get to them with the buffer list commands, like ":bnext". + +:[N]al[l][!] [N] *:al* *:all* *:sal* *:sall* +:[N]sal[l][!] [N] + Rearrange the screen to open one window for each argument. + All other windows are closed. When a count is given, this is + the maximum number of windows to open. + With the |:tab| modifier open a tab page for each argument. + When there are more arguments than 'tabpagemax' further ones + become split windows in the last tab page. + When the 'hidden' option is set, all buffers in closed windows + become hidden. + When 'hidden' is not set, and the 'autowrite' option is set, + modified buffers are written. Otherwise, windows that have + buffers that are modified are not removed, unless the [!] is + given, then they become hidden. But modified buffers are + never abandoned, so changes cannot get lost. + [N] is the maximum number of windows to open. 'winheight' + also limits the number of windows opened ('winwidth' if + |:vertical| was prepended). + Buf/Win Enter/Leave autocommands are not executed for the new + windows here, that's only done when they are really entered. + +:[N]sa[rgument][!] [++opt] [+cmd] [N] *:sa* *:sargument* + Short for ":split | argument [N]": split window and go to Nth + argument. But when there is no such argument, the window is + not split. Also see |++opt| and |+cmd|. + +:[N]sn[ext][!] [++opt] [+cmd] [file ..] *:sn* *:snext* + Short for ":split | [N]next": split window and go to Nth next + argument. But when there is no next file, the window is not + split. Also see |++opt| and |+cmd|. + +:[N]spr[evious][!] [++opt] [+cmd] [N] *:spr* *:sprevious* +:[N]sN[ext][!] [++opt] [+cmd] [N] *:sN* *:sNext* + Short for ":split | [N]Next": split window and go to Nth + previous argument. But when there is no previous file, the + window is not split. Also see |++opt| and |+cmd|. + + *:sre* *:srewind* +:sre[wind][!] [++opt] [+cmd] + Short for ":split | rewind": split window and go to first + argument. But when there is no argument list, the window is + not split. Also see |++opt| and |+cmd|. + + *:sfir* *:sfirst* +:sfir[st] [++opt] [+cmd] + Same as ":srewind". + + *:sla* *:slast* +:sla[st][!] [++opt] [+cmd] + Short for ":split | last": split window and go to last + argument. But when there is no argument list, the window is + not split. Also see |++opt| and |+cmd|. + + *:dr* *:drop* +:dr[op] [++opt] [+cmd] {file} .. + Edit the first {file} in a window. + - If the file is already open in a window change to that + window. + - If the file is not open in a window edit the file in the + current window. If the current buffer can't be |abandon|ed, + the window is split first. + The |argument-list| is set, like with the |:next| command. + The purpose of this command is that it can be used from a + program that wants Vim to edit another file, e.g., a debugger. + When using the |:tab| modifier each argument is opened in a + tab page. The last window is used if it's empty. + Also see |++opt| and |+cmd|. + {only available when compiled with a GUI} + +============================================================================== +8. Do a command in all buffers or windows *list-repeat* + + *:windo* +:[range]windo {cmd} Execute {cmd} in each window or if [range] is given + only in windows for which the window number lies in + the [range]. It works like doing this: > + CTRL-W t + :{cmd} + CTRL-W w + :{cmd} + etc. +< This only operates in the current tab page. + When an error is detected on one window, further + windows will not be visited. + The last window (or where an error occurred) becomes + the current window. + {cmd} can contain '|' to concatenate several commands. + {cmd} must not open or close windows or reorder them. + {not in Vi} {not available when compiled without the + |+listcmds| feature} + Also see |:tabdo|, |:argdo|, |:bufdo|, |:cdo|, |:ldo|, + |:cfdo| and |:lfdo| + + *:bufdo* +:[range]bufdo[!] {cmd} Execute {cmd} in each buffer in the buffer list or if + [range] is given only for buffers for which their + buffer numer is in the [range]. It works like doing + this: > + :bfirst + :{cmd} + :bnext + :{cmd} + etc. +< When the current file can't be |abandon|ed and the [!] + is not present, the command fails. + When an error is detected on one buffer, further + buffers will not be visited. + Unlisted buffers are skipped. + The last buffer (or where an error occurred) becomes + the current buffer. + {cmd} can contain '|' to concatenate several commands. + {cmd} must not delete buffers or add buffers to the + buffer list. + Note: While this command is executing, the Syntax + autocommand event is disabled by adding it to + 'eventignore'. This considerably speeds up editing + each buffer. + {not in Vi} {not available when compiled without the + |+listcmds| feature} + Also see |:tabdo|, |:argdo|, |:windo|, |:cdo|, |:ldo|, + |:cfdo| and |:lfdo| + +Examples: > + + :windo set nolist nofoldcolumn | normal zn + +This resets the 'list' option and disables folding in all windows. > + + :bufdo set fileencoding= | update + +This resets the 'fileencoding' in each buffer and writes it if this changed +the buffer. The result is that all buffers will use the 'encoding' encoding +(if conversion works properly). + +============================================================================== +9. Tag or file name under the cursor *window-tag* + + *:sta* *:stag* +:sta[g][!] [tagname] + Does ":tag[!] [tagname]" and splits the window for the found + tag. See also |:tag|. + +CTRL-W ] *CTRL-W_]* *CTRL-W_CTRL-]* +CTRL-W CTRL-] Split current window in two. Use identifier under cursor as a + tag and jump to it in the new upper window. + In Visual mode uses the Visually selected text as a tag. + Make new window N high. + + *CTRL-W_g]* +CTRL-W g ] Split current window in two. Use identifier under cursor as a + tag and perform ":tselect" on it in the new upper window. + In Visual mode uses the Visually selected text as a tag. + Make new window N high. + + *CTRL-W_g_CTRL-]* +CTRL-W g CTRL-] Split current window in two. Use identifier under cursor as a + tag and perform ":tjump" on it in the new upper window. + In Visual mode uses the Visually selected text as a tag. + Make new window N high. + +CTRL-W f *CTRL-W_f* *CTRL-W_CTRL-F* +CTRL-W CTRL-F Split current window in two. Edit file name under cursor. + Like ":split gf", but window isn't split if the file does not + exist. + Uses the 'path' variable as a list of directory names where to + look for the file. Also the path for current file is + used to search for the file name. + If the name is a hypertext link that looks like + "type://machine/path", only "/path" is used. + If a count is given, the count'th matching file is edited. + {not available when the |+file_in_path| feature was disabled + at compile time} + +CTRL-W F *CTRL-W_F* + Split current window in two. Edit file name under cursor and + jump to the line number following the file name. See |gF| for + details on how the line number is obtained. + {not available when the |+file_in_path| feature was disabled + at compile time} + +CTRL-W gf *CTRL-W_gf* + Open a new tab page and edit the file name under the cursor. + Like "tab split" and "gf", but the new tab page isn't created + if the file does not exist. + {not available when the |+file_in_path| feature was disabled + at compile time} + +CTRL-W gF *CTRL-W_gF* + Open a new tab page and edit the file name under the cursor + and jump to the line number following the file name. Like + "tab split" and "gF", but the new tab page isn't created if + the file does not exist. + {not available when the |+file_in_path| feature was disabled + at compile time} + +Also see |CTRL-W_CTRL-I|: open window for an included file that includes +the keyword under the cursor. + +============================================================================== +10. The preview window *preview-window* + +The preview window is a special window to show (preview) another file. It is +normally a small window used to show an include file or definition of a +function. +{not available when compiled without the |+quickfix| feature} + +There can be only one preview window (per tab page). It is created with one +of the commands below. The 'previewheight' option can be set to specify the +height of the preview window when it's opened. The 'previewwindow' option is +set in the preview window to be able to recognize it. The 'winfixheight' +option is set to have it keep the same height when opening/closing other +windows. + + *:pta* *:ptag* +:pta[g][!] [tagname] + Does ":tag[!] [tagname]" and shows the found tag in a + "Preview" window without changing the current buffer or cursor + position. If a "Preview" window already exists, it is re-used + (like a help window is). If a new one is opened, + 'previewheight' is used for the height of the window. See + also |:tag|. + See below for an example. |CursorHold-example| + Small difference from |:tag|: When [tagname] is equal to the + already displayed tag, the position in the matching tag list + is not reset. This makes the CursorHold example work after a + |:ptnext|. + +CTRL-W z *CTRL-W_z* +CTRL-W CTRL-Z *CTRL-W_CTRL-Z* *:pc* *:pclose* +:pc[lose][!] Close any "Preview" window currently open. When the 'hidden' + option is set, or when the buffer was changed and the [!] is + used, the buffer becomes hidden (unless there is another + window editing it). The command fails if any "Preview" buffer + cannot be closed. See also |:close|. + + *:pp* *:ppop* +:[count]pp[op][!] + Does ":[count]pop[!]" in the preview window. See |:pop| and + |:ptag|. {not in Vi} + +CTRL-W } *CTRL-W_}* + Use identifier under cursor as a tag and perform a :ptag on + it. Make the new Preview window (if required) N high. If N is + not given, 'previewheight' is used. + +CTRL-W g } *CTRL-W_g}* + Use identifier under cursor as a tag and perform a :ptjump on + it. Make the new Preview window (if required) N high. If N is + not given, 'previewheight' is used. + + *:ped* *:pedit* +:ped[it][!] [++opt] [+cmd] {file} + Edit {file} in the preview window. The preview window is + opened like with |:ptag|. The current window and cursor + position isn't changed. Useful example: > + :pedit +/fputc /usr/include/stdio.h +< + *:ps* *:psearch* +:[range]ps[earch][!] [count] [/]pattern[/] + Works like |:ijump| but shows the found match in the preview + window. The preview window is opened like with |:ptag|. The + current window and cursor position isn't changed. Useful + example: > + :psearch popen +< Like with the |:ptag| command, you can use this to + automatically show information about the word under the + cursor. This is less clever than using |:ptag|, but you don't + need a tags file and it will also find matches in system + include files. Example: > + :au! CursorHold *.[ch] nested exe "silent! psearch " . expand("<cword>") +< Warning: This can be slow. + +Example *CursorHold-example* > + + :au! CursorHold *.[ch] nested exe "silent! ptag " . expand("<cword>") + +This will cause a ":ptag" to be executed for the keyword under the cursor, +when the cursor hasn't moved for the time set with 'updatetime'. The "nested" +makes other autocommands be executed, so that syntax highlighting works in the +preview window. The "silent!" avoids an error message when the tag could not +be found. Also see |CursorHold|. To disable this again: > + + :au! CursorHold + +A nice addition is to highlight the found tag, avoid the ":ptag" when there +is no word under the cursor, and a few other things: > + + :au! CursorHold *.[ch] nested call PreviewWord() + :func PreviewWord() + : if &previewwindow " don't do this in the preview window + : return + : endif + : let w = expand("<cword>") " get the word under cursor + : if w =~ '\a' " if the word contains a letter + : + : " Delete any existing highlight before showing another tag + : silent! wincmd P " jump to preview window + : if &previewwindow " if we really get there... + : match none " delete existing highlight + : wincmd p " back to old window + : endif + : + : " Try displaying a matching tag for the word under the cursor + : try + : exe "ptag " . w + : catch + : return + : endtry + : + : silent! wincmd P " jump to preview window + : if &previewwindow " if we really get there... + : if has("folding") + : silent! .foldopen " don't want a closed fold + : endif + : call search("$", "b") " to end of previous line + : let w = substitute(w, '\\', '\\\\', "") + : call search('\<\V' . w . '\>') " position cursor on match + : " Add a match highlight to the word at this position + : hi previewWord term=bold ctermbg=green guibg=green + : exe 'match previewWord "\%' . line(".") . 'l\%' . col(".") . 'c\k*"' + : wincmd p " back to old window + : endif + : endif + :endfun + +============================================================================== +11. Using hidden buffers *buffer-hidden* + +A hidden buffer is not displayed in a window, but is still loaded into memory. +This makes it possible to jump from file to file, without the need to read or +write the file every time you get another buffer in a window. +{not available when compiled without the |+listcmds| feature} + + *:buffer-!* +If the option 'hidden' ('hid') is set, abandoned buffers are kept for all +commands that start editing another file: ":edit", ":next", ":tag", etc. The +commands that move through the buffer list sometimes make the current buffer +hidden although the 'hidden' option is not set. This happens when a buffer is +modified, but is forced (with '!') to be removed from a window, and +'autowrite' is off or the buffer can't be written. + +You can make a hidden buffer not hidden by starting to edit it with any +command. Or by deleting it with the ":bdelete" command. + +The 'hidden' is global, it is used for all buffers. The 'bufhidden' option +can be used to make an exception for a specific buffer. It can take these +values: + <empty> Use the value of 'hidden'. + hide Hide this buffer, also when 'hidden' is not set. + unload Don't hide but unload this buffer, also when 'hidden' + is set. + delete Delete the buffer. + + *hidden-quit* +When you try to quit Vim while there is a hidden, modified buffer, you will +get an error message and Vim will make that buffer the current buffer. You +can then decide to write this buffer (":wq") or quit without writing (":q!"). +Be careful: there may be more hidden, modified buffers! + +A buffer can also be unlisted. This means it exists, but it is not in the +list of buffers. |unlisted-buffer| + + +:files[!] [flags] *:files* +:buffers[!] [flags] *:buffers* *:ls* +:ls[!] [flags] + Show all buffers. Example: + + 1 #h "/test/text" line 1 ~ + 2u "asdf" line 0 ~ + 3 %a + "version.c" line 1 ~ + + When the [!] is included the list will show unlisted buffers + (the term "unlisted" is a bit confusing then...). + + Each buffer has a unique number. That number will not change, + thus you can always go to a specific buffer with ":buffer N" + or "N CTRL-^", where N is the buffer number. + + Indicators (chars in the same column are mutually exclusive): + u an unlisted buffer (only displayed when [!] is used) + |unlisted-buffer| + % the buffer in the current window + # the alternate buffer for ":e #" and CTRL-^ + a an active buffer: it is loaded and visible + h a hidden buffer: It is loaded, but currently not + displayed in a window |hidden-buffer| + - a buffer with 'modifiable' off + = a readonly buffer + + a modified buffer + x a buffer with read errors + + [flags] can be a combination of the following characters, + which restrict the buffers to be listed: + + modified buffers + - buffers with 'modifiable' off + = readonly buffers + a active buffers + u unlisted buffers (overrides the "!") + h hidden buffers + x buffers with a read error + % current buffer + # alternate buffer + Combining flags means they are "and"ed together, e.g.: + h+ hidden buffers which are modified + a+ active buffers which are modified + + *:bad* *:badd* +:bad[d] [+lnum] {fname} + Add file name {fname} to the buffer list, without loading it. + If "lnum" is specified, the cursor will be positioned at that + line when the buffer is first entered. Note that other + commands after the + will be ignored. + +:[N]bd[elete][!] *:bd* *:bdel* *:bdelete* *E516* +:bd[elete][!] [N] + Unload buffer [N] (default: current buffer) and delete it from + the buffer list. If the buffer was changed, this fails, + unless when [!] is specified, in which case changes are lost. + The file remains unaffected. Any windows for this buffer are + closed. If buffer [N] is the current buffer, another buffer + will be displayed instead. This is the most recent entry in + the jump list that points into a loaded buffer. + Actually, the buffer isn't completely deleted, it is removed + from the buffer list |unlisted-buffer| and option values, + variables and mappings/abbreviations for the buffer are + cleared. Examples: > + :.,$-bdelete " delete buffers from the current one to + " last but one + :%bdelete " delete all buffers +< + +:bdelete[!] {bufname} *E93* *E94* + Like ":bdelete[!] [N]", but buffer given by name. Note that a + buffer whose name is a number cannot be referenced by that + name; use the buffer number instead. Insert a backslash + before a space in a buffer name. + +:bdelete[!] N1 N2 ... + Do ":bdelete[!]" for buffer N1, N2, etc. The arguments can be + buffer numbers or buffer names (but not buffer names that are + a number). Insert a backslash before a space in a buffer + name. + +:N,Mbdelete[!] Do ":bdelete[!]" for all buffers in the range N to M + |inclusive|. + +:[N]bw[ipeout][!] *:bw* *:bwipe* *:bwipeout* *E517* +:bw[ipeout][!] {bufname} +:N,Mbw[ipeout][!] +:bw[ipeout][!] N1 N2 ... + Like |:bdelete|, but really delete the buffer. Everything + related to the buffer is lost. All marks in this buffer + become invalid, option settings are lost, etc. Don't use this + unless you know what you are doing. Examples: > + :.+,$bwipeout " wipe out all buffers after the current + " one + :%bwipeout " wipe out all buffers +< + +:[N]bun[load][!] *:bun* *:bunload* *E515* +:bun[load][!] [N] + Unload buffer [N] (default: current buffer). The memory + allocated for this buffer will be freed. The buffer remains + in the buffer list. + If the buffer was changed, this fails, unless when [!] is + specified, in which case the changes are lost. + Any windows for this buffer are closed. If buffer [N] is the + current buffer, another buffer will be displayed instead. + This is the most recent entry in the jump list that points + into a loaded buffer. + +:bunload[!] {bufname} + Like ":bunload[!] [N]", but buffer given by name. Note that a + buffer whose name is a number cannot be referenced by that + name; use the buffer number instead. Insert a backslash + before a space in a buffer name. + +:N,Mbunload[!] Do ":bunload[!]" for all buffers in the range N to M + |inclusive|. + +:bunload[!] N1 N2 ... + Do ":bunload[!]" for buffer N1, N2, etc. The arguments can be + buffer numbers or buffer names (but not buffer names that are + a number). Insert a backslash before a space in a buffer + name. + +:[N]b[uffer][!] [+cmd] [N] *:b* *:bu* *:buf* *:buffer* *E86* + Edit buffer [N] from the buffer list. If [N] is not given, + the current buffer remains being edited. See |:buffer-!| for + [!]. This will also edit a buffer that is not in the buffer + list, without setting the 'buflisted' flag. + Also see |+cmd|. + +:[N]b[uffer][!] [+cmd] {bufname} + Edit buffer for {bufname} from the buffer list. See + |:buffer-!| for [!]. This will also edit a buffer that is not + in the buffer list, without setting the 'buflisted' flag. + Also see |+cmd|. + +:[N]sb[uffer] [+cmd] [N] *:sb* *:sbuffer* + Split window and edit buffer [N] from the buffer list. If [N] + is not given, the current buffer is edited. Respects the + "useopen" setting of 'switchbuf' when splitting. This will + also edit a buffer that is not in the buffer list, without + setting the 'buflisted' flag. + Also see |+cmd|. + +:[N]sb[uffer] [+cmd] {bufname} + Split window and edit buffer for {bufname} from the buffer + list. This will also edit a buffer that is not in the buffer + list, without setting the 'buflisted' flag. + Note: If what you want to do is split the buffer, make a copy + under another name, you can do it this way: > + :w foobar | sp # +< Also see |+cmd|. + +:[N]bn[ext][!] [+cmd] [N] *:bn* *:bnext* *E87* + Go to [N]th next buffer in buffer list. [N] defaults to one. + Wraps around the end of the buffer list. + See |:buffer-!| for [!]. + Also see |+cmd|. + If you are in a help buffer, this takes you to the next help + buffer (if there is one). Similarly, if you are in a normal + (non-help) buffer, this takes you to the next normal buffer. + This is so that if you have invoked help, it doesn't get in + the way when you're browsing code/text buffers. The next three + commands also work like this. + + + *:sbn* *:sbnext* +:[N]sbn[ext] [+cmd] [N] + Split window and go to [N]th next buffer in buffer list. + Wraps around the end of the buffer list. Uses 'switchbuf' + Also see |+cmd|. + +:[N]bN[ext][!] [+cmd] [N] *:bN* *:bNext* *:bp* *:bprevious* *E88* +:[N]bp[revious][!] [+cmd] [N] + Go to [N]th previous buffer in buffer list. [N] defaults to + one. Wraps around the start of the buffer list. + See |:buffer-!| for [!] and 'switchbuf'. + Also see |+cmd|. + +:[N]sbN[ext] [+cmd] [N] *:sbN* *:sbNext* *:sbp* *:sbprevious* +:[N]sbp[revious] [+cmd] [N] + Split window and go to [N]th previous buffer in buffer list. + Wraps around the start of the buffer list. + Uses 'switchbuf'. + Also see |+cmd|. + +:br[ewind][!] [+cmd] *:br* *:brewind* + Go to first buffer in buffer list. If the buffer list is + empty, go to the first unlisted buffer. + See |:buffer-!| for [!]. + +:bf[irst] [+cmd] *:bf* *:bfirst* + Same as |:brewind|. + Also see |+cmd|. + +:sbr[ewind] [+cmd] *:sbr* *:sbrewind* + Split window and go to first buffer in buffer list. If the + buffer list is empty, go to the first unlisted buffer. + Respects the 'switchbuf' option. + Also see |+cmd|. + +:sbf[irst] [+cmd] *:sbf* *:sbfirst* + Same as ":sbrewind". + +:bl[ast][!] [+cmd] *:bl* *:blast* + Go to last buffer in buffer list. If the buffer list is + empty, go to the last unlisted buffer. + See |:buffer-!| for [!]. + +:sbl[ast] [+cmd] *:sbl* *:sblast* + Split window and go to last buffer in buffer list. If the + buffer list is empty, go to the last unlisted buffer. + Respects 'switchbuf' option. + +:[N]bm[odified][!] [+cmd] [N] *:bm* *:bmodified* *E84* + Go to [N]th next modified buffer. Note: this command also + finds unlisted buffers. If there is no modified buffer the + command fails. + +:[N]sbm[odified] [+cmd] [N] *:sbm* *:sbmodified* + Split window and go to [N]th next modified buffer. + Respects 'switchbuf' option. + Note: this command also finds buffers not in the buffer list. + +:[N]unh[ide] [N] *:unh* *:unhide* *:sun* *:sunhide* +:[N]sun[hide] [N] + Rearrange the screen to open one window for each loaded buffer + in the buffer list. When a count is given, this is the + maximum number of windows to open. + +:[N]ba[ll] [N] *:ba* *:ball* *:sba* *:sball* +:[N]sba[ll] [N] Rearrange the screen to open one window for each buffer in + the buffer list. When a count is given, this is the maximum + number of windows to open. 'winheight' also limits the number + of windows opened ('winwidth' if |:vertical| was prepended). + Buf/Win Enter/Leave autocommands are not executed for the new + windows here, that's only done when they are really entered. + When the |:tab| modifier is used new windows are opened in a + new tab, up to 'tabpagemax'. + +Note: All the commands above that start editing another buffer, keep the +'readonly' flag as it was. This differs from the ":edit" command, which sets +the 'readonly' flag each time the file is read. + +============================================================================== +12. Special kinds of buffers *special-buffers* + +Instead of containing the text of a file, buffers can also be used for other +purposes. A few options can be set to change the behavior of a buffer: + 'bufhidden' what happens when the buffer is no longer displayed + in a window. + 'buftype' what kind of a buffer this is + 'swapfile' whether the buffer will have a swap file + 'buflisted' buffer shows up in the buffer list + +A few useful kinds of a buffer: + +quickfix Used to contain the error list or the location list. See + |:cwindow| and |:lwindow|. This command sets the 'buftype' + option to "quickfix". You are not supposed to change this! + 'swapfile' is off. + +help Contains a help file. Will only be created with the |:help| + command. The flag that indicates a help buffer is internal + and can't be changed. The 'buflisted' option will be reset + for a help buffer. + +directory Displays directory contents. Can be used by a file explorer + plugin. The buffer is created with these settings: > + :setlocal buftype=nowrite + :setlocal bufhidden=delete + :setlocal noswapfile +< The buffer name is the name of the directory and is adjusted + when using the |:cd| command. + +scratch Contains text that can be discarded at any time. It is kept + when closing the window, it must be deleted explicitly. + Settings: > + :setlocal buftype=nofile + :setlocal bufhidden=hide + :setlocal noswapfile +< The buffer name can be used to identify the buffer, if you + give it a meaningful name. + + *unlisted-buffer* +unlisted The buffer is not in the buffer list. It is not used for + normal editing, but to show a help file, remember a file name + or marks. The ":bdelete" command will also set this option, + thus it doesn't completely delete the buffer. Settings: > + :setlocal nobuflisted +< + + vim:tw=78:ts=8:ft=help:norl: diff --git a/en/workshop.txt b/en/workshop.txt new file mode 100644 index 000000000..5514f9ebb --- /dev/null +++ b/en/workshop.txt @@ -0,0 +1,98 @@ +*workshop.txt* For Vim version 7.4. Last change: 2013 Jul 06 + + + VIM REFERENCE MANUAL by Gordon Prieur + + +Sun Visual WorkShop Features *workshop* *workshop-support* + +1. Introduction |workshop-intro| +2. Commands |workshop-commands| +3. Compiling vim/gvim for WorkShop |workshop-compiling| +4. Configuring gvim for a WorkShop release tree |workshop-configure| +5. Obtaining the latest version of the XPM library |workshop-xpm| + +{Vi does not have any of these features} +{only available when compiled with the |+sun_workshop| feature} + +============================================================================== +1. Introduction *workshop-intro* + +Sun Visual WorkShop has an "Editor of Choice" feature designed to let users +debug using their favorite editors. For the 6.0 release we have added support +for gvim. A workshop debug session will have a debugging window and an editor +window (possibly others as well). The user can do many debugging operations +from the editor window, minimizing the need to switch from window to window. + +The version of vim shipped with Sun Visual WorkShop 6 (also called Forte +Developer 6) is vim 5.3. The features in this release are much more reliable +than the vim/gvim shipped with Visual WorkShop. VWS users wishing to use vim +as their editor should compile these sources and install them in their +workshop release tree. + +============================================================================== +2. Commands *workshop-commands* + + *:ws* *:wsverb* +:ws[verb] verb Pass the verb to the verb executor + +Pass the verb to a workshop function which gathers some arguments and +sends the verb and data to workshop over an IPC connection. + +============================================================================== +3. Compiling vim/gvim for WorkShop *workshop-compiling* + +Compiling vim with FEAT_SUN_WORKSHOP turns on all compile time flags necessary +for building a vim to work with Visual WorkShop. The features required for VWS +have been built and tested using the Sun compilers from the VWS release. They +have not been built or tested using Gnu compilers. This does not mean the +features won't build and run if compiled with gcc, just that nothing is +guaranteed with gcc! + +============================================================================== +4. Configuring gvim for a WorkShop release tree *workshop-configure* + +There are several assumptions which must be met in order to compile a gvim for +use with Sun Visual WorkShop 6. + + o You should use the compiler in VWS rather than gcc. We have neither + built nor tested with gcc and cannot guarantee it will build properly. + + o You must supply your own XPM library. See |workshop-xpm| below for + details on obtaining the latest version of XPM. + + o Edit the Makefile in the src directory and uncomment the lines for Sun + Visual WorkShop. You can easily find these by searching for the string + FEAT_SUN_WORKSHOP + + o We also suggest you use Motif for your gui. This will provide gvim with + the same look-and-feel as the rest of Sun Visual WorkShop. + +The following configuration line can be used to configure vim to build for use +with Sun Visual WorkShop: + + $ CC=cc configure --enable-workshop --enable-gui=motif \ + -prefix=<VWS-install-dir>/contrib/contrib6/<vim-version> + +The VWS-install-dir should be the base directory where your Sun Visual WorkShop +was installed. By default this is /opt/SUNWspro. It will normally require +root permissions to install the vim release. You will also need to change the +symlink <VWS-install-dir>/bin/gvim to point to the vim in your newly installed +directory. The <vim-version> should be a unique version string. I use "vim" +concatenated with the equivalent of version.h's VIM_VERSION_SHORT. + +============================================================================== +5. Obtaining the latest version of the XPM library *workshop-xpm* + +The XPM library is required to show images within Vim with Motif or Athena. +Without it the toolbar and signs will be disabled. + +The XPM library is provided by Arnaud Le Hors of the French National Institute +for Research in Computer Science and Control. It can be downloaded from +http://cgit.freedesktop.org/xorg/lib/libXpm. The current release, as of this +writing, is xpm-3.4k-solaris.tgz, which is a gzip'ed tar file. If you create +the directory /usr/local/xpm and untar the file there you can use the +uncommented lines in the Makefile without changing them. If you use another +xpm directory you will need to change the XPM_DIR in src/Makefile. + + vim:tw=78:ts=8:ft=help:norl: diff --git a/tools/buildhtml.vim b/tools/buildhtml.vim new file mode 100644 index 000000000..27ad6f421 --- /dev/null +++ b/tools/buildhtml.vim @@ -0,0 +1,87 @@ +#!gvim -u + +set nocompatible +set nomore +set encoding=utf-8 +set fileencodings=utf-8 +syntax on +colorscheme delek + +enew! + +runtime plugin/tohtml.vim + +source <sfile>:h/makehtml.vim + +function! s:main() + " for ja custom syntax + let &runtimepath .= ',' . expand('<sfile>:p:h') + call s:BuildHtml() +endfunction + +function! s:BuildHtml() + + " generate tags + try + helptags . + catch + echo v:exception + endtry + + enew + + " + " generate html + " + set foldlevel=1000 + call MakeHtmlAll() + " add header and footer + tabnew + " XXX: modeline may cause error. + " 2html.vim escape modeline. But it doesn't escape /^vim:/. + set nomodeline + args *.html + argdo call s:PostEdit() | update! +endfunction + +function! s:system(cmd) + call system(a:cmd) + if v:shell_error + throw 'system() failed: ' . a:cmd + endif +endfunction + +function! s:rmdir(path) + if executable('rm') + call s:system('rm -rf ' . shellescape(a:path)) + else + call s:system('rmdir /s /q ' . shellescape(a:path)) + endif +endfunction + +function! s:PostEdit() + set fileformat=unix + call s:ToJekyll() +endfunction + +function! s:ToJekyll() + let helpname = expand('%:t:r') + if helpname == 'index' + let helpname = 'help' + endif + " remove header + 1,/^<hr>/delete _ + " remove footer + /^<hr>/,$delete _ + " escape jekyll tags + %s/{\{2,}\|{%/{{ "\0" }}/ge + " YAML front matter + call append(0, [ + \ '---', + \ 'layout: vimdoc', + \ printf("helpname: '%s'", helpname), + \ '---', + \ ]) +endfunction + +call s:main() diff --git a/tools/makehtml.vim b/tools/makehtml.vim new file mode 100644 index 000000000..9cdea1637 --- /dev/null +++ b/tools/makehtml.vim @@ -0,0 +1,298 @@ +" makehtml.vim +" +" Description: +" Convert help file to HTML file. +" +" When there are other language files, multi-language HTML are +" created. (1) HTML files are named with "help.ab.html" (but +" "help.txt" => "help.html"). (2) Header and Footer have links to +" other language. Otherwise single language HTML files are created +" (named with "help.html" and no language links). +" +" Usage: +" :cd doc +" :helptags . +" :source mkhtml.vim +" :call MakeHtmlAll() + +function! MakeHtmlAll() + if bufname("%") != "" || &modified + new + endif + let s:log = [] + call MakeTagsFile() + let files = split(glob('*.??[tx]'), '\n') + for i in range(len(files)) + call append('$', printf("%d/%d %s -> %s", i+1, len(files), files[i], s:HtmlName(files[i]))) + endfor + silent 1delete _ + for i in range(len(files)) + call cursor(i+1, 1) + redraw! " show progress + let file = files[i] + call MakeHtml(file) + call setline(i+1, getline(i+1) . ' *DONE*') + endfor + if s:log != [] + new + call append(0, s:log) + endif +endfunction + +function! MakeHtmlAllBatch() + call MakeTagsFile() + let files = split(glob('*.??[tx]'), '\n') + for i in range(len(files)) + call MakeHtml(files[i]) + endfor +endfunction + +function! MakeTagsFile() + let files = split(glob('tags'), '\n') + let files += split(glob('tags-??'), '\n') + for file in files + let lang = matchstr(file, 'tags-\zs..$') + if lang == "" + let fname = "tags.txt" + else + let fname = printf("tags.%sx", lang) + endif + new `=fname` + silent %delete _ + let tags = s:GetTags(lang) + for tagname in sort(keys(tags)) + if tagname == "help-tags" + continue + endif + call append('$', printf("|%s|\t\t%s", tagname, tags[tagname]["filename"])) + endfor + call append('$', ' vim:ft=help:') + silent 1delete _ + wq! + endfor +endfunction + +function! MakeHtml(fname) + let r = MakeHtml2(a:fname, s:HtmlName(a:fname)) + quit! + return r +endfunction + +function! MakeHtml2(src, dst) + new `=a:src` + + " 2html options + let g:html_use_css = 1 + let g:html_no_pre = 1 + " set dumy highlight to keep syntax identity + if !exists("s:attr_save") + let s:attr_save = {} + for name in ["helpStar", "helpBar", "helpHyperTextEntry", "helpHyperTextJump", "helpOption", "helpExample"] + let s:attr_save[name] = synIDattr(synIDtrans(hlID(name)), "name") + execute printf("hi %s term=bold cterm=bold gui=bold", name) + endfor + endif + + silent! %foldopen! + TOhtml + + let lang = s:GetLang(a:src) + silent %s@<span class="\(helpHyperTextEntry\|helpHyperTextJump\|helpOption\)">\([^<]*\)</span>@\=s:MakeLink(lang, submatch(1), submatch(2))@ge + silent %s@^<span class="Ignore"><</span>\ze @\ @ge + silent %s@<span class="\(helpStar\|helpBar\|Ignore\)">[^<]*</span>@@ge + call s:TranslateHelpExampleBlock() + " remove style + g/^\.\(helpBar\|helpStar\|helpHyperTextEntry\|helpHyperTextJump\|helpOption\)/silent delete _ + + call s:Header() + call s:Footer() + + wq! `=a:dst` +endfunction + +" <span>...</span> -> <div>... +" <span>...</span> ...</div> +function! s:TranslateHelpExampleBlock() + let mx = '^<span class="helpExample">\zs.*\ze</span><br>$' + let i = 1 + while i <= line('$') + if getline(i) =~ mx + let start = i + while i <= line('$') && getline(i) =~ mx + call setline(i, matchstr(getline(i), mx) . '<br>') + let i += 1 + endwhile + let end = i - 1 + call setline(start, '<div class="helpExample">' . getline(start)) + call setline(end, matchstr(getline(end), '.*\ze<br>') . '</div>') + else + let i += 1 + endif + endwhile +endfunction + +function! s:Header() + let name = fnamemodify(bufname("%"), ":r:r") + let indexfile = s:GetIndexFile(bufname("%")) + let title = printf("<title>Vim documentation: %s", name) + call setline(search('^

Vim documentation: %s

', name), + \ printf('main help file', indexfile), + \ '
', + \ ] + call append(search('^', + \ printf('top - main help file
', indexfile), + \ s:MakeLangLinks(bufname("%")), + \ ] + call append(search('^', 'g') + let tagname = substitute(tagname, '&', '\&', 'g') + if a:hlname == "helpHyperTextEntry" + let sep = "*" + elseif a:hlname == "helpHyperTextJump" + let sep = "|" + elseif a:hlname == "helpOption" + let sep = "" + endif + let tags = s:GetTags(a:lang) + if has_key(tags, tagname) + let href = tags[tagname]["html"] + if tagname !~ '\.txt$' && tagname != "help-tags" + let href .= '#' . tagname + endif + if a:hlname == "helpHyperTextEntry" + let res = printf('%s%s%s', s:attr_save[a:hlname], href, a:tagname, sep, a:tagname, sep) + else + let res = printf('%s%s%s', s:attr_save[a:hlname], href, sep, a:tagname, sep) + endif + elseif has_key(tags, ":" . tagname) + let href = tags[":" . tagname]["html"] + let href .= '#:' . tagname + if a:hlname == "helpHyperTextEntry" + let res = printf('%s%s%s', s:attr_save[a:hlname], href, a:tagname, sep, a:tagname, sep) + else + let res = printf('%s%s%s', s:attr_save[a:hlname], href, sep, a:tagname, sep) + endif + else + " missing tag or not translated or typo. use English if possible. + call s:Log("%s: tag error: %s", bufname("%"), tagname) + let tags = s:GetTags("") + if has_key(tags, tagname) + let href = tags[tagname]["html"] + if tagname !~ '\.txt$' + let href .= '#' . tagname + endif + let res = printf('%s%s%s', href, sep, a:tagname, sep) + else + let res = printf('%s%s%s', sep, a:tagname, sep) + endif + endif + return res +endfunction + +function! s:GetTags(lang) + if !exists("s:tags_" . a:lang) + let &l:tags = (a:lang == "") ? "./tags" : "./tags-" . a:lang + let tags = {} + for item in taglist(".*") + let item["html"] = s:HtmlName(item["filename"]) + let tags[item["name"]] = item + endfor + " for help-tags + let item = {} + let item["name"] = "help-tags" + if s:IsSingleMode() + let item["html"] = "tags.html" + else + let item["html"] = printf("tags%s.html", (a:lang == "") ? "" : "." . a:lang) + endif + let tags[item["name"]] = item + let s:tags_{a:lang} = tags + endif + return s:tags_{a:lang} +endfunction + +function! s:IsSingleMode() + " if there is one language files, do not append language identifier + " (use "help.html" instead of "help.ab.html"). + if !exists("s:single_mode") + let files = split(glob('tags'), '\n') + let files += split(glob('tags-??'), '\n') + let s:single_mode = (len(files) == 1) + endif + return s:single_mode +endfunction + +function! s:HtmlName(helpfile) + " help.txt => "help.html" + " help.jax => "help.ja.html" + let lang = s:GetLang(a:helpfile) + let base = fnamemodify(a:helpfile, ":r") + if base == "help" + let base = "index" + elseif base == "index" + let base = "vimindex" + endif + if s:IsSingleMode() + return printf("%s.html", base) + endif + return printf("%s%s.html", base, (lang == "") ? "" : "." . lang) +endfunction + +function! s:GetLang(fname) + " help.txt => "" + " help.jax => "ja" + " help.jax.html => "ja" + return matchstr(a:fname, '^.*\.\zs..\zex\%(.html\)\?$') +endfunction + +function! s:GetIndexFile(fname) + if s:IsSingleMode() + return "index.html" + endif + let lang = s:GetLang(a:fname) + return printf("index%s.html", (lang == "") ? "" : "." . lang) +endfunction + +function! s:MakeLangLinks(htmlfile) + if s:IsSingleMode() + return "" + endif + let base = fnamemodify(a:htmlfile, ':r:r') + let files = split(glob(base . '.??x'), '\n') + let res = printf('Language: en', base) + for name in files + let lang = s:GetLang(name) + let res .= printf(' %s', s:HtmlName(name), lang) + endfor + return res +endfunction + +function! s:Log(fmt, ...) + if exists("s:log") + if len(a:000) == 0 + call add(s:log, a:fmt) + else + call add(s:log, call("printf", [a:fmt] + a:000)) + endif + endif +endfunction + diff --git a/tools/update-config.sh b/tools/update-config.sh new file mode 100644 index 000000000..85c2c3c63 --- /dev/null +++ b/tools/update-config.sh @@ -0,0 +1,3 @@ +GIT_REPO="git@github.com:vim-jp/vimdoc-ja.git" +GIT_NAME="vimdoc-ja system" +GIT_EMAIL="vimdoc-ja@vim-jp.org" diff --git a/tools/update-gh-pages.sh b/tools/update-gh-pages.sh new file mode 100644 index 000000000..d4c304063 --- /dev/null +++ b/tools/update-gh-pages.sh @@ -0,0 +1,23 @@ +#!/bin/sh +# vim:set sts=2 sw=2 tw=0 et: + +. `dirname $0`/update-lib.sh + +setup "gh-pages" + +# Convert *.jax files to *.html. +TOHTML_DIR="target/to_html" +if [ -e "${TOHTML_DIR}" ] ; then + rm -rf "${TOHTML_DIR}" +fi +if [ ! -e "${TOHTML_DIR}" ] ; then + mkdir -p "${TOHTML_DIR}/doc" +fi +cp -R syntax "${TOHTML_DIR}" +cp doc/*.jax vim_faq/*.jax "${TOHTML_DIR}/doc" +cp tools/buildhtml.vim tools/makehtml.vim "${TOHTML_DIR}" +( cd "${TOHTML_DIR}/doc" && vim -esu ../buildhtml.vim -c "qall!") > /dev/null + +rsync -rlptD --delete-after "${TOHTML_DIR}"/doc/*.html "${BRANCHDIR}/" + +teardown "vim-jp/vimdoc-ja@" diff --git a/tools/update-lib.sh b/tools/update-lib.sh new file mode 100644 index 000000000..99ecea2f6 --- /dev/null +++ b/tools/update-lib.sh @@ -0,0 +1,61 @@ +CONFIGFILE=`dirname $0`/update-config.sh + +. "${CONFIGFILE}" + +if [ x"${GIT_REPO}" = "x" ] ; then + echo "GIT_REPO is missing in \"${CONFIGFILE}\"" && exit 1 +fi +if [ x"${GIT_NAME}" = "x" ] ; then + echo "GIT_NAME is missing in \"${CONFIGFILE}\"" && exit 1 +fi +if [ x"${GIT_EMAIL}" = "x" ] ; then + echo "GIT_EMAIL is missing in \"${CONFIGFILE}\"" && exit 1 +fi + +setup() { + GIT_BRANCH="$1" ; shift + if [ x"${GIT_BRANCH}" = "x" ] ; then + echo "GIT_BRANCH is required" + exit 1 + fi + + WORKDIR="target" + BRANCHDIR="${WORKDIR}/${GIT_BRANCH}" + + # FIXME: exit if failed. + SHA1HASH=`git show --pretty="format:%H" | head -1` + + # Prepare and clean up working directories. + if [ ! -e "${WORKDIR}" ] ; then + mkdir -p "${WORKDIR}" + fi + if [ -e "${BRANCHDIR}" ] ; then + rm -rf "${BRANCHDIR}" + fi + + # Checkout a target branch. + echo "Checking out \"${GIT_BRANCH}\" from \"${GIT_REPO}\"" + git clone -q -b "${GIT_BRANCH}" --depth 5 "${GIT_REPO}" "${BRANCHDIR}" || exit 1 + + echo "Make changes in \"${BRANCHDIR}\"" + PARENTDIR=`pwd` + cd "${BRANCHDIR}" + CHILDDIR=`pwd` + cd "${PARENTDIR}" +} + +teardown() { + HASH_PREFIX=$1 ; shift + cd "${CHILDDIR}" + git config user.name "${GIT_NAME}" + git config user.email "${GIT_EMAIL}" + git add --all . + if ! git diff --quiet HEAD ; then + echo "Register changes and push it to \"${GIT_REPO}\"" + commit_message="Deployed ${HASH_PREFIX}${SHA1HASH} by `hostname`" + git commit -m "${commit_message}" + git push || exit 1 + else + echo "No changes" + fi +} diff --git a/tools/update-master.sh b/tools/update-master.sh new file mode 100644 index 000000000..ffa21f276 --- /dev/null +++ b/tools/update-master.sh @@ -0,0 +1,13 @@ +#!/bin/sh +# vim:set sts=2 sw=2 tw=0 et: + +. `dirname $0`/update-lib.sh + +setup "master" + +# Copy files. +rsync -rlptD --delete-after doc/ ${BRANCHDIR}/doc +rsync -rlptD --delete-after syntax/ ${BRANCHDIR}/syntax +rsync -rlptD --delete-after README.md ${BRANCHDIR}/README.md + +teardown "vim-jp/vimdoc-ja@" diff --git a/tools/upload.vim b/tools/upload.vim new file mode 100644 index 000000000..6904b31fa --- /dev/null +++ b/tools/upload.vim @@ -0,0 +1,161 @@ +#!vim -u +" FIXME: + +set nocompatible +set nomore + +" TODO: argument parser +enew! +let g:argv = argv() +silent! argdelete * + +function! s:github_repos_downloads_list(user, repos) + let url = printf('https://api.github.com/repos/%s/%s/downloads', a:user, a:repos) + let cmd = printf('curl --silent %s', shellescape(url)) + let res = system(cmd) + if v:shell_error + throw 'fails to list downloads' + endif + let downloads = webapi#json#decode(res) + if type(downloads) == type({}) && has_key(downloads, 'message') + throw 'fails to list downloads: ' . downloads.message + endif + return downloads +endfunction + +function! s:github_repos_downloads_get(user, repos, id) + let url = printf('https://api.github.com/repos/%s/%s/downloads/%s', a:user, a:repos, a:id) + let cmd = printf('curl --silent %s', shellescape(url)) + let res = system(cmd) + if v:shell_error + throw 'fails to get download' + endif + let download = webapi#json#decode(res) + if has_key(download, 'message') + throw 'fails to get download: ' . download.message + endif + return download +endfunction + +function! s:github_repos_downloads_create(auth_user, auth_password, user, repos, file, name, description, content_type) + " create download + let url = printf('https://api.github.com/repos/%s/%s/downloads', a:user, a:repos) + let data = {} + let data.name = a:name + let data.size = getfsize(a:file) + if a:description != '' + let data.description = a:description + endif + if a:content_type != '' + let data.content_type = a:content_type + endif + let cmd = printf('curl --silent --user %s --data %s %s', shellescape(a:auth_user . ':' . a:auth_password), shellescape(webapi#json#encode(data)), shellescape(url)) + let res = system(cmd) + if v:shell_error + throw 'fails to create new download' + endif + let download = webapi#json#decode(res) + if has_key(download, 'message') + throw 'fails to create new download: ' . download.message + endif + + " upload file + let cmd = 'curl --silent' + \ . ' -F ' . shellescape('key=' . download.path) + \ . ' -F ' . shellescape('acl=' . download.acl) + \ . ' -F ' . shellescape('success_action_status=201') + \ . ' -F ' . shellescape('Filename=' . download.name) + \ . ' -F ' . shellescape('AWSAccessKeyId=' . download.accesskeyid) + \ . ' -F ' . shellescape('Policy=' . download.policy) + \ . ' -F ' . shellescape('Signature=' . download.signature) + \ . ' -F ' . shellescape('Content-Type=' . download.content_type) + \ . ' -F ' . shellescape('file=@' . a:file) + \ . ' ' . shellescape(download.s3_url) + let res = system(cmd) + if v:shell_error + throw 'fails to upload file' + endif + + return download +endfunction + +function! s:github_repos_downloads_delete(auth_user, auth_password, user, repos, id) + let url = printf('https://api.github.com/repos/%s/%s/downloads/%s', a:user, a:repos, a:id) + let cmd = printf('curl --silent --request DELETE --user %s %s', shellescape(a:auth_user . ':' . a:auth_password), shellescape(url)) + let res = system(cmd) + if v:shell_error + throw 'fails to delete download' + endif + if res != '' + let err = webapi#json#decode(res) + throw 'fails to delete download: ' . err.message + endif +endfunction + +function! s:github_repos_downloads_get_by_name(user, repos, name) + let downloads = s:github_repos_downloads_list(a:user, a:repos) + for download in downloads + if download.name ==# a:name + return download + endif + endfor + throw 'Not Found' +endfunction + +function! s:github_repos_downloads_replace(auth_user, auth_password, user, repos, file, name, description, content_type) + try + let download = s:github_repos_downloads_get_by_name(a:user, a:repos, a:name) + catch /Not Found/ + let download = {} + endtry + if !empty(download) + call s:github_repos_downloads_delete(a:auth_user, a:auth_password, a:user, a:repos, download.id) + endif + call s:github_repos_downloads_create(a:auth_user, a:auth_password, a:user, a:repos, a:file, a:name, a:description, a:content_type) +endfunction + +function! s:main() + if isdirectory('vimdoc-ja') + call s:rmdir('vimdoc-ja') + endif + if filereadable('vimdoc-ja.zip') + call delete('vimdoc-ja.zip') + endif + if filereadable('vimdoc-ja.tar.gz') + call delete('vimdoc-ja.tar.gz') + endif + call s:system('git clone -b master . vimdoc-ja') + call s:rmdir('vimdoc-ja/.git') + silent! helptags vimdoc-ja/doc + call s:system('zip -r vimdoc-ja.zip vimdoc-ja') + call s:system('tar czf vimdoc-ja.tar.gz vimdoc-ja') + echo 'Please enter github user/password to upload package to vim-jp/vimdoc-ja project.' + let auth_user = input('user: ') + let auth_password = inputsecret('password: ') + call s:github_repos_downloads_replace(auth_user, auth_password, 'vim-jp', 'vimdoc-ja', 'vimdoc-ja.zip', 'vimdoc-ja.zip', '', '') + call s:github_repos_downloads_replace(auth_user, auth_password, 'vim-jp', 'vimdoc-ja', 'vimdoc-ja.tar.gz', 'vimdoc-ja.tar.gz', '', '') +endfunction + +function! s:system(cmd) + call system(a:cmd) + if v:shell_error + throw 'system() failed: ' . a:cmd + endif +endfunction + +function! s:rmdir(path) + if executable('rm') + call s:system('rm -rf ' . shellescape(a:path)) + else + call s:system('rmdir /s /q ' . shellescape(a:path)) + endif +endfunction + +try + call s:main() + qall +catch + echo v:exception + sleep 2 + cquit +endtry diff --git a/tutor/tutor b/tutor/tutor new file mode 100644 index 000000000..64a27d1c0 --- /dev/null +++ b/tutor/tutor @@ -0,0 +1,970 @@ +=============================================================================== += W e l c o m e t o t h e V I M T u t o r - Version 1.7 = +=============================================================================== + + Vim is a very powerful editor that has many commands, too many to + explain in a tutor such as this. This tutor is designed to describe + enough of the commands that you will be able to easily use Vim as + an all-purpose editor. + + The approximate time required to complete the tutor is 25-30 minutes, + depending upon how much time is spent with experimentation. + + ATTENTION: + The commands in the lessons will modify the text. Make a copy of this + file to practise on (if you started "vimtutor" this is already a copy). + + It is important to remember that this tutor is set up to teach by + use. That means that you need to execute the commands to learn them + properly. If you only read the text, you will forget the commands! + + Now, make sure that your Shift-Lock key is NOT depressed and press + the j key enough times to move the cursor so that Lesson 1.1 + completely fills the screen. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 1.1: MOVING THE CURSOR + + + ** To move the cursor, press the h,j,k,l keys as indicated. ** + ^ + k Hint: The h key is at the left and moves left. + < h l > The l key is at the right and moves right. + j The j key looks like a down arrow. + v + 1. Move the cursor around the screen until you are comfortable. + + 2. Hold down the down key (j) until it repeats. + Now you know how to move to the next lesson. + + 3. Using the down key, move to Lesson 1.2. + +NOTE: If you are ever unsure about something you typed, press to place + you in Normal mode. Then retype the command you wanted. + +NOTE: The cursor keys should also work. But using hjkl you will be able to + move around much faster, once you get used to it. Really! + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 1.2: EXITING VIM + + + !! NOTE: Before executing any of the steps below, read this entire lesson!! + + 1. Press the key (to make sure you are in Normal mode). + + 2. Type: :q! . + This exits the editor, DISCARDING any changes you have made. + + 3. Get back here by executing the command that got you into this tutor. That + might be: vimtutor + + 4. If you have these steps memorized and are confident, execute steps + 1 through 3 to exit and re-enter the editor. + +NOTE: :q! discards any changes you made. In a few lessons you + will learn how to save the changes to a file. + + 5. Move the cursor down to Lesson 1.3. + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 1.3: TEXT EDITING - DELETION + + + ** Press x to delete the character under the cursor. ** + + 1. Move the cursor to the line below marked --->. + + 2. To fix the errors, move the cursor until it is on top of the + character to be deleted. + + 3. Press the x key to delete the unwanted character. + + 4. Repeat steps 2 through 4 until the sentence is correct. + +---> The ccow jumpedd ovverr thhe mooon. + + 5. Now that the line is correct, go on to Lesson 1.4. + +NOTE: As you go through this tutor, do not try to memorize, learn by usage. + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 1.4: TEXT EDITING - INSERTION + + + ** Press i to insert text. ** + + 1. Move the cursor to the first line below marked --->. + + 2. To make the first line the same as the second, move the cursor on top + of the first character AFTER where the text is to be inserted. + + 3. Press i and type in the necessary additions. + + 4. As each error is fixed press to return to Normal mode. + Repeat steps 2 through 4 to correct the sentence. + +---> There is text misng this . +---> There is some text missing from this line. + + 5. When you are comfortable inserting text move to lesson 1.5. + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 1.5: TEXT EDITING - APPENDING + + + ** Press A to append text. ** + + 1. Move the cursor to the first line below marked --->. + It does not matter on what character the cursor is in that line. + + 2. Press A and type in the necessary additions. + + 3. As the text has been appended press to return to Normal mode. + + 4. Move the cursor to the second line marked ---> and repeat + steps 2 and 3 to correct this sentence. + +---> There is some text missing from th + There is some text missing from this line. +---> There is also some text miss + There is also some text missing here. + + 5. When you are comfortable appending text move to lesson 1.6. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 1.6: EDITING A FILE + + ** Use :wq to save a file and exit. ** + + !! NOTE: Before executing any of the steps below, read this entire lesson!! + + 1. Exit this tutor as you did in lesson 1.2: :q! + Or, if you have access to another terminal, do the following there. + + 2. At the shell prompt type this command: vim tutor + 'vim' is the command to start the Vim editor, 'tutor' is the name of the + file you wish to edit. Use a file that may be changed. + + 3. Insert and delete text as you learned in the previous lessons. + + 4. Save the file with changes and exit Vim with: :wq + + 5. If you have quit vimtutor in step 1 restart the vimtutor and move down to + the following summary. + + 6. After reading the above steps and understanding them: do it. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 1 SUMMARY + + + 1. The cursor is moved using either the arrow keys or the hjkl keys. + h (left) j (down) k (up) l (right) + + 2. To start Vim from the shell prompt type: vim FILENAME + + 3. To exit Vim type: :q! to trash all changes. + OR type: :wq to save the changes. + + 4. To delete the character at the cursor type: x + + 5. To insert or append text type: + i type inserted text insert before the cursor + A type appended text append after the line + +NOTE: Pressing will place you in Normal mode or will cancel + an unwanted and partially completed command. + +Now continue with Lesson 2. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 2.1: DELETION COMMANDS + + + ** Type dw to delete a word. ** + + 1. Press to make sure you are in Normal mode. + + 2. Move the cursor to the line below marked --->. + + 3. Move the cursor to the beginning of a word that needs to be deleted. + + 4. Type dw to make the word disappear. + + NOTE: The letter d will appear on the last line of the screen as you type + it. Vim is waiting for you to type w . If you see another character + than d you typed something wrong; press and start over. + +---> There are a some words fun that don't belong paper in this sentence. + + 5. Repeat steps 3 and 4 until the sentence is correct and go to Lesson 2.2. + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 2.2: MORE DELETION COMMANDS + + + ** Type d$ to delete to the end of the line. ** + + 1. Press to make sure you are in Normal mode. + + 2. Move the cursor to the line below marked --->. + + 3. Move the cursor to the end of the correct line (AFTER the first . ). + + 4. Type d$ to delete to the end of the line. + +---> Somebody typed the end of this line twice. end of this line twice. + + + 5. Move on to Lesson 2.3 to understand what is happening. + + + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 2.3: ON OPERATORS AND MOTIONS + + + Many commands that change text are made from an operator and a motion. + The format for a delete command with the d delete operator is as follows: + + d motion + + Where: + d - is the delete operator. + motion - is what the operator will operate on (listed below). + + A short list of motions: + w - until the start of the next word, EXCLUDING its first character. + e - to the end of the current word, INCLUDING the last character. + $ - to the end of the line, INCLUDING the last character. + + Thus typing de will delete from the cursor to the end of the word. + +NOTE: Pressing just the motion while in Normal mode without an operator will + move the cursor as specified. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 2.4: USING A COUNT FOR A MOTION + + + ** Typing a number before a motion repeats it that many times. ** + + 1. Move the cursor to the start of the line marked ---> below. + + 2. Type 2w to move the cursor two words forward. + + 3. Type 3e to move the cursor to the end of the third word forward. + + 4. Type 0 (zero) to move to the start of the line. + + 5. Repeat steps 2 and 3 with different numbers. + +---> This is just a line with words you can move around in. + + 6. Move on to Lesson 2.5. + + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 2.5: USING A COUNT TO DELETE MORE + + + ** Typing a number with an operator repeats it that many times. ** + + In the combination of the delete operator and a motion mentioned above you + insert a count before the motion to delete more: + d number motion + + 1. Move the cursor to the first UPPER CASE word in the line marked --->. + + 2. Type d2w to delete the two UPPER CASE words + + 3. Repeat steps 1 and 2 with a different count to delete the consecutive + UPPER CASE words with one command + +---> this ABC DE line FGHI JK LMN OP of words is Q RS TUV cleaned up. + + + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 2.6: OPERATING ON LINES + + + ** Type dd to delete a whole line. ** + + Due to the frequency of whole line deletion, the designers of Vi decided + it would be easier to simply type two d's to delete a line. + + 1. Move the cursor to the second line in the phrase below. + 2. Type dd to delete the line. + 3. Now move to the fourth line. + 4. Type 2dd to delete two lines. + +---> 1) Roses are red, +---> 2) Mud is fun, +---> 3) Violets are blue, +---> 4) I have a car, +---> 5) Clocks tell time, +---> 6) Sugar is sweet +---> 7) And so are you. + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 2.7: THE UNDO COMMAND + + + ** Press u to undo the last commands, U to fix a whole line. ** + + 1. Move the cursor to the line below marked ---> and place it on the + first error. + 2. Type x to delete the first unwanted character. + 3. Now type u to undo the last command executed. + 4. This time fix all the errors on the line using the x command. + 5. Now type a capital U to return the line to its original state. + 6. Now type u a few times to undo the U and preceding commands. + 7. Now type CTRL-R (keeping CTRL key pressed while hitting R) a few times + to redo the commands (undo the undo's). + +---> Fiix the errors oon thhis line and reeplace them witth undo. + + 8. These are very useful commands. Now move on to the Lesson 2 Summary. + + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 2 SUMMARY + + + 1. To delete from the cursor up to the next word type: dw + 2. To delete from the cursor to the end of a line type: d$ + 3. To delete a whole line type: dd + + 4. To repeat a motion prepend it with a number: 2w + 5. The format for a change command is: + operator [number] motion + where: + operator - is what to do, such as d for delete + [number] - is an optional count to repeat the motion + motion - moves over the text to operate on, such as w (word), + $ (to the end of line), etc. + + 6. To move to the start of the line use a zero: 0 + + 7. To undo previous actions, type: u (lowercase u) + To undo all the changes on a line, type: U (capital U) + To undo the undo's, type: CTRL-R + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 3.1: THE PUT COMMAND + + + ** Type p to put previously deleted text after the cursor. ** + + 1. Move the cursor to the first ---> line below. + + 2. Type dd to delete the line and store it in a Vim register. + + 3. Move the cursor to the c) line, ABOVE where the deleted line should go. + + 4. Type p to put the line below the cursor. + + 5. Repeat steps 2 through 4 to put all the lines in correct order. + +---> d) Can you learn too? +---> b) Violets are blue, +---> c) Intelligence is learned, +---> a) Roses are red, + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 3.2: THE REPLACE COMMAND + + + ** Type rx to replace the character at the cursor with x . ** + + 1. Move the cursor to the first line below marked --->. + + 2. Move the cursor so that it is on top of the first error. + + 3. Type r and then the character which should be there. + + 4. Repeat steps 2 and 3 until the first line is equal to the second one. + +---> Whan this lime was tuoed in, someone presswd some wrojg keys! +---> When this line was typed in, someone pressed some wrong keys! + + 5. Now move on to Lesson 3.3. + +NOTE: Remember that you should be learning by doing, not memorization. + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 3.3: THE CHANGE OPERATOR + + + ** To change until the end of a word, type ce . ** + + 1. Move the cursor to the first line below marked --->. + + 2. Place the cursor on the u in lubw. + + 3. Type ce and the correct word (in this case, type ine ). + + 4. Press and move to the next character that needs to be changed. + + 5. Repeat steps 3 and 4 until the first sentence is the same as the second. + +---> This lubw has a few wptfd that mrrf changing usf the change operator. +---> This line has a few words that need changing using the change operator. + +Notice that ce deletes the word and places you in Insert mode. + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 3.4: MORE CHANGES USING c + + + ** The change operator is used with the same motions as delete. ** + + 1. The change operator works in the same way as delete. The format is: + + c [number] motion + + 2. The motions are the same, such as w (word) and $ (end of line). + + 3. Move to the first line below marked --->. + + 4. Move the cursor to the first error. + + 5. Type c$ and type the rest of the line like the second and press . + +---> The end of this line needs some help to make it like the second. +---> The end of this line needs to be corrected using the c$ command. + +NOTE: You can use the Backspace key to correct mistakes while typing. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 3 SUMMARY + + + 1. To put back text that has just been deleted, type p . This puts the + deleted text AFTER the cursor (if a line was deleted it will go on the + line below the cursor). + + 2. To replace the character under the cursor, type r and then the + character you want to have there. + + 3. The change operator allows you to change from the cursor to where the + motion takes you. eg. Type ce to change from the cursor to the end of + the word, c$ to change to the end of a line. + + 4. The format for change is: + + c [number] motion + +Now go on to the next lesson. + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 4.1: CURSOR LOCATION AND FILE STATUS + + ** Type CTRL-G to show your location in the file and the file status. + Type G to move to a line in the file. ** + + NOTE: Read this entire lesson before executing any of the steps!! + + 1. Hold down the Ctrl key and press g . We call this CTRL-G. + A message will appear at the bottom of the page with the filename and the + position in the file. Remember the line number for Step 3. + +NOTE: You may see the cursor position in the lower right corner of the screen + This happens when the 'ruler' option is set (see :help 'ruler' ) + + 2. Press G to move you to the bottom of the file. + Type gg to move you to the start of the file. + + 3. Type the number of the line you were on and then G . This will + return you to the line you were on when you first pressed CTRL-G. + + 4. If you feel confident to do this, execute steps 1 through 3. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 4.2: THE SEARCH COMMAND + + + ** Type / followed by a phrase to search for the phrase. ** + + 1. In Normal mode type the / character. Notice that it and the cursor + appear at the bottom of the screen as with the : command. + + 2. Now type 'errroor' . This is the word you want to search for. + + 3. To search for the same phrase again, simply type n . + To search for the same phrase in the opposite direction, type N . + + 4. To search for a phrase in the backward direction, use ? instead of / . + + 5. To go back to where you came from press CTRL-O (Keep Ctrl down while + pressing the letter o). Repeat to go back further. CTRL-I goes forward. + +---> "errroor" is not the way to spell error; errroor is an error. +NOTE: When the search reaches the end of the file it will continue at the + start, unless the 'wrapscan' option has been reset. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 4.3: MATCHING PARENTHESES SEARCH + + + ** Type % to find a matching ),], or } . ** + + 1. Place the cursor on any (, [, or { in the line below marked --->. + + 2. Now type the % character. + + 3. The cursor will move to the matching parenthesis or bracket. + + 4. Type % to move the cursor to the other matching bracket. + + 5. Move the cursor to another (,),[,],{ or } and see what % does. + +---> This ( is a test line with ('s, ['s ] and {'s } in it. )) + + +NOTE: This is very useful in debugging a program with unmatched parentheses! + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 4.4: THE SUBSTITUTE COMMAND + + + ** Type :s/old/new/g to substitute 'new' for 'old'. ** + + 1. Move the cursor to the line below marked --->. + + 2. Type :s/thee/the . Note that this command only changes the + first occurrence of "thee" in the line. + + 3. Now type :s/thee/the/g . Adding the g flag means to substitute + globally in the line, change all occurrences of "thee" in the line. + +---> thee best time to see thee flowers is in thee spring. + + 4. To change every occurrence of a character string between two lines, + type :#,#s/old/new/g where #,# are the line numbers of the range + of lines where the substitution is to be done. + Type :%s/old/new/g to change every occurrence in the whole file. + Type :%s/old/new/gc to find every occurrence in the whole file, + with a prompt whether to substitute or not. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 4 SUMMARY + + + 1. CTRL-G displays your location in the file and the file status. + G moves to the end of the file. + number G moves to that line number. + gg moves to the first line. + + 2. Typing / followed by a phrase searches FORWARD for the phrase. + Typing ? followed by a phrase searches BACKWARD for the phrase. + After a search type n to find the next occurrence in the same direction + or N to search in the opposite direction. + CTRL-O takes you back to older positions, CTRL-I to newer positions. + + 3. Typing % while the cursor is on a (,),[,],{, or } goes to its match. + + 4. To substitute new for the first old in a line type :s/old/new + To substitute new for all 'old's on a line type :s/old/new/g + To substitute phrases between two line #'s type :#,#s/old/new/g + To substitute all occurrences in the file type :%s/old/new/g + To ask for confirmation each time add 'c' :%s/old/new/gc + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 5.1: HOW TO EXECUTE AN EXTERNAL COMMAND + + + ** Type :! followed by an external command to execute that command. ** + + 1. Type the familiar command : to set the cursor at the bottom of the + screen. This allows you to enter a command-line command. + + 2. Now type the ! (exclamation point) character. This allows you to + execute any external shell command. + + 3. As an example type ls following the ! and then hit . This + will show you a listing of your directory, just as if you were at the + shell prompt. Or use :!dir if ls doesn't work. + +NOTE: It is possible to execute any external command this way, also with + arguments. + +NOTE: All : commands must be finished by hitting + From here on we will not always mention it. + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 5.2: MORE ON WRITING FILES + + + ** To save the changes made to the text, type :w FILENAME. ** + + 1. Type :!dir or :!ls to get a listing of your directory. + You already know you must hit after this. + + 2. Choose a filename that does not exist yet, such as TEST. + + 3. Now type: :w TEST (where TEST is the filename you chose.) + + 4. This saves the whole file (the Vim Tutor) under the name TEST. + To verify this, type :!dir or :!ls again to see your directory. + +NOTE: If you were to exit Vim and start it again with vim TEST , the file + would be an exact copy of the tutor when you saved it. + + 5. Now remove the file by typing (MS-DOS): :!del TEST + or (Unix): :!rm TEST + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 5.3: SELECTING TEXT TO WRITE + + + ** To save part of the file, type v motion :w FILENAME ** + + 1. Move the cursor to this line. + + 2. Press v and move the cursor to the fifth item below. Notice that the + text is highlighted. + + 3. Press the : character. At the bottom of the screen :'<,'> will appear. + + 4. Type w TEST , where TEST is a filename that does not exist yet. Verify + that you see :'<,'>w TEST before you press . + + 5. Vim will write the selected lines to the file TEST. Use :!dir or :!ls + to see it. Do not remove it yet! We will use it in the next lesson. + +NOTE: Pressing v starts Visual selection. You can move the cursor around + to make the selection bigger or smaller. Then you can use an operator + to do something with the text. For example, d deletes the text. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 5.4: RETRIEVING AND MERGING FILES + + + ** To insert the contents of a file, type :r FILENAME ** + + 1. Place the cursor just above this line. + +NOTE: After executing Step 2 you will see text from Lesson 5.3. Then move + DOWN to see this lesson again. + + 2. Now retrieve your TEST file using the command :r TEST where TEST is + the name of the file you used. + The file you retrieve is placed below the cursor line. + + 3. To verify that a file was retrieved, cursor back and notice that there + are now two copies of Lesson 5.3, the original and the file version. + +NOTE: You can also read the output of an external command. For example, + :r !ls reads the output of the ls command and puts it below the + cursor. + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 5 SUMMARY + + + 1. :!command executes an external command. + + Some useful examples are: + (MS-DOS) (Unix) + :!dir :!ls - shows a directory listing. + :!del FILENAME :!rm FILENAME - removes file FILENAME. + + 2. :w FILENAME writes the current Vim file to disk with name FILENAME. + + 3. v motion :w FILENAME saves the Visually selected lines in file + FILENAME. + + 4. :r FILENAME retrieves disk file FILENAME and puts it below the + cursor position. + + 5. :r !dir reads the output of the dir command and puts it below the + cursor position. + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 6.1: THE OPEN COMMAND + + + ** Type o to open a line below the cursor and place you in Insert mode. ** + + 1. Move the cursor to the line below marked --->. + + 2. Type the lowercase letter o to open up a line BELOW the cursor and place + you in Insert mode. + + 3. Now type some text and press to exit Insert mode. + +---> After typing o the cursor is placed on the open line in Insert mode. + + 4. To open up a line ABOVE the cursor, simply type a capital O , rather + than a lowercase o. Try this on the line below. + +---> Open up a line above this by typing O while the cursor is on this line. + + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 6.2: THE APPEND COMMAND + + + ** Type a to insert text AFTER the cursor. ** + + 1. Move the cursor to the start of the line below marked --->. + + 2. Press e until the cursor is on the end of li . + + 3. Type an a (lowercase) to append text AFTER the cursor. + + 4. Complete the word like the line below it. Press to exit Insert + mode. + + 5. Use e to move to the next incomplete word and repeat steps 3 and 4. + +---> This li will allow you to pract appendi text to a line. +---> This line will allow you to practice appending text to a line. + +NOTE: a, i and A all go to the same Insert mode, the only difference is where + the characters are inserted. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 6.3: ANOTHER WAY TO REPLACE + + + ** Type a capital R to replace more than one character. ** + + 1. Move the cursor to the first line below marked --->. Move the cursor to + the beginning of the first xxx . + + 2. Now press R and type the number below it in the second line, so that it + replaces the xxx . + + 3. Press to leave Replace mode. Notice that the rest of the line + remains unmodified. + + 4. Repeat the steps to replace the remaining xxx. + +---> Adding 123 to xxx gives you xxx. +---> Adding 123 to 456 gives you 579. + +NOTE: Replace mode is like Insert mode, but every typed character deletes an + existing character. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 6.4: COPY AND PASTE TEXT + + + ** Use the y operator to copy text and p to paste it ** + + 1. Go to the line marked with ---> below and place the cursor after "a)". + + 2. Start Visual mode with v and move the cursor to just before "first". + + 3. Type y to yank (copy) the highlighted text. + + 4. Move the cursor to the end of the next line: j$ + + 5. Type p to put (paste) the text. Then type: a second . + + 6. Use Visual mode to select " item.", yank it with y , move to the end of + the next line with j$ and put the text there with p . + +---> a) this is the first item. + b) + + NOTE: you can also use y as an operator; yw yanks one word. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 6.5: SET OPTION + + + ** Set an option so a search or substitute ignores case ** + + 1. Search for 'ignore' by entering: /ignore + Repeat several times by pressing n . + + 2. Set the 'ic' (Ignore case) option by entering: :set ic + + 3. Now search for 'ignore' again by pressing n + Notice that Ignore and IGNORE are now also found. + + 4. Set the 'hlsearch' and 'incsearch' options: :set hls is + + 5. Now type the search command again and see what happens: /ignore + + 6. To disable ignoring case enter: :set noic + +NOTE: To remove the highlighting of matches enter: :nohlsearch +NOTE: If you want to ignore case for just one search command, use \c + in the phrase: /ignore\c +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 6 SUMMARY + + 1. Type o to open a line BELOW the cursor and start Insert mode. + Type O to open a line ABOVE the cursor. + + 2. Type a to insert text AFTER the cursor. + Type A to insert text after the end of the line. + + 3. The e command moves to the end of a word. + + 4. The y operator yanks (copies) text, p puts (pastes) it. + + 5. Typing a capital R enters Replace mode until is pressed. + + 6. Typing ":set xxx" sets the option "xxx". Some options are: + 'ic' 'ignorecase' ignore upper/lower case when searching + 'is' 'incsearch' show partial matches for a search phrase + 'hls' 'hlsearch' highlight all matching phrases + You can either use the long or the short option name. + + 7. Prepend "no" to switch an option off: :set noic + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 7.1: GETTING HELP + + + ** Use the on-line help system ** + + Vim has a comprehensive on-line help system. To get started, try one of + these three: + - press the key (if you have one) + - press the key (if you have one) + - type :help + + Read the text in the help window to find out how the help works. + Type CTRL-W CTRL-W to jump from one window to another. + Type :q to close the help window. + + You can find help on just about any subject, by giving an argument to the + ":help" command. Try these (don't forget pressing ): + + :help w + :help c_CTRL-D + :help insert-index + :help user-manual +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 7.2: CREATE A STARTUP SCRIPT + + + ** Enable Vim features ** + + Vim has many more features than Vi, but most of them are disabled by + default. To start using more features you have to create a "vimrc" file. + + 1. Start editing the "vimrc" file. This depends on your system: + :e ~/.vimrc for Unix + :e $VIM/_vimrc for MS-Windows + + 2. Now read the example "vimrc" file contents: + :r $VIMRUNTIME/vimrc_example.vim + + 3. Write the file with: + :w + + The next time you start Vim it will use syntax highlighting. + You can add all your preferred settings to this "vimrc" file. + For more information type :help vimrc-intro + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 7.3: COMPLETION + + + ** Command line completion with CTRL-D and ** + + 1. Make sure Vim is not in compatible mode: :set nocp + + 2. Look what files exist in the directory: :!ls or :!dir + + 3. Type the start of a command: :e + + 4. Press CTRL-D and Vim will show a list of commands that start with "e". + + 5. Press and Vim will complete the command name to ":edit". + + 6. Now add a space and the start of an existing file name: :edit FIL + + 7. Press . Vim will complete the name (if it is unique). + +NOTE: Completion works for many commands. Just try pressing CTRL-D and + . It is especially useful for :help . + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Lesson 7 SUMMARY + + + 1. Type :help or press or to open a help window. + + 2. Type :help cmd to find help on cmd . + + 3. Type CTRL-W CTRL-W to jump to another window + + 4. Type :q to close the help window + + 5. Create a vimrc startup script to keep your preferred settings. + + 6. When typing a : command, press CTRL-D to see possible completions. + Press to use one completion. + + + + + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + This concludes the Vim Tutor. It was intended to give a brief overview of + the Vim editor, just enough to allow you to use the editor fairly easily. + It is far from complete as Vim has many many more commands. Read the user + manual next: ":help user-manual". + + For further reading and studying, this book is recommended: + Vim - Vi Improved - by Steve Oualline + Publisher: New Riders + The first book completely dedicated to Vim. Especially useful for beginners. + There are many examples and pictures. + See http://iccf-holland.org/click5.html + + This book is older and more about Vi than Vim, but also recommended: + Learning the Vi Editor - by Linda Lamb + Publisher: O'Reilly & Associates Inc. + It is a good book to get to know almost anything you want to do with Vi. + The sixth edition also includes information on Vim. + + This tutorial was written by Michael C. Pierce and Robert K. Ware, + Colorado School of Mines using ideas supplied by Charles Smith, + Colorado State University. E-mail: bware@mines.colorado.edu. + + Modified for Vim by Bram Moolenaar. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/tutor/tutor.ja b/tutor/tutor.ja new file mode 100644 index 000000000..99cc7d463 --- /dev/null +++ b/tutor/tutor.ja @@ -0,0 +1,976 @@ +=============================================================================== += V I M 教 本 (チュートリアル) へ よ う こ そ - Version 1.7 = +=============================================================================== + + Vim は、このチュートリアルで説明するには多すぎる程のコマンドを備えた非常 + に強力なエディターです。このチュートリアルは、あなたが Vim を万能エディ + ターとして使いこなせるようになるのに十分なコマンドについて説明をするよう + なっています。 + + チュートリアルを完了するのに必要な時間は、覚えたコマンドを試すのにどれだ + け時間を使うのかにもよりますが、およそ25から30分です。 + + ATTENTION: + 以下の練習用コマンドにはこの文章を変更するものもあります。練習を始める前 + にコピーを作成しましょう("vimtutor"したならば、既にコピーされています)。 + + このチュートリアルが、使うことで覚えられる仕組みになっていることを、心し + ておかなければなりません。正しく学習するにはコマンドを実際に試さなければ + ならないのです。文章を読んだだけならば、きっと忘れてしまいます!。 + + さぁ、Capsロック(Shift-Lock)キーが押されていないことを確認した後、画面に + レッスン1.1 が全部表示されるところまで、j キーを押してカーソルを移動しま + しょう。 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 1.1: カーソルの移動 + + + ** カーソルを移動するには、示される様に h,j,k,l を押します ** + ^ + k ヒント: h キーは左方向に移動します。 + < h l > l キーは右方向に移動します。 + j j キーは下矢印キーのようなキーです。 + v + 1. 移動に慣れるまで、スクリーンでカーソル移動させましょう。 + + 2. 下へのキー(j)を押しつづけると、連続して移動できます。 + これで次のレッスンに移動する方法がわかりましたね。 + + 3. 下へのキーを使って、レッスン1.2 に移動しましょう。 + +NOTE: 何をタイプしているか判らなくなったら、を押してノーマルモードにし + ます。それから入力しようとしていたコマンドを再入力しましょう。 + +NOTE: カーソルキーでも移動できます。しかし hjkl に一度慣れてしまえば、はるか + に速く移動することができるでしょう。いやマジで! + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 1.2: VIM の起動と終了 + + + !! NOTE: 以下のあらゆるステップを行う前に、このレッスンを読みましょう!! + + 1. キーを押しましょう。(確実にノーマルモードにするため) + + 2. 次のようにタイプ: :q! + これにより編集した内容を保存せずにエディタが終了します。 + + 3. このチュートリアルを始める為のコマンドを実行すると、ここに戻れます。 + そのコマンドは: vimtutor + + 4. これまでのステップを覚え自信がついたならば、ステップ 1 から 3 までを実 + 際に試して、Vim を1度終了してから再び起動しましょう。 + +NOTE: :q! は全ての変更を破棄します。レッスンにて変更をファイルに保 + 存する方法についても勉強していきましょう。 + + 5. 1.3までカーソルを移動させましょう。 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 1.3: テキスト編集 - 削除 + + + ** ノーマルモードにてカーソルの下の文字を削除するには x を押します ** + + 1. 以下の ---> と示された行にカーソルを移動しましょう。 + + 2. 間違いを修正するために、削除する最初の文字までカーソルを移動します。 + + 3. 不必要な文字を x を押して削除しましょう。 + + 4. 文が正しくなるまで ステップ 2 から 4 を繰り返しましょう。 + +---> その ううさぎ は つつきき を こええてて とびはねたた + + 5. 行が正しくなったら、レッスン 1.4 へ進みましょう。 + +NOTE: 全てのレッスンを通じて、覚えようとするのではなく実際にやってみましょう。 + + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 1.4: テキスト編集 - 挿入 + + + ** ノーマルモードにてテキストを挿入するには i を押します ** + + 1. 以下の ---> と示された最初の行にカーソルを移動しましょう。 + + 2. 1行目を2行目と同じ様にするために、テキストを挿入しなければならない位置 + の次の文字にカーソルを移動します。 + + 3. i キーを押してから、追加が必要な文字をタイプしましょう。 + + 4. 間違いを修正したら を押してコマンドモードに戻り、正しい文になる様 + にステップ 2 から 4 を繰り返しましょう。 + +---> この には 足りない テキスト ある。 +---> この 行 には 幾つか 足りない テキスト が ある。 + + 5. 挿入の方法がわかったらレッスン 1.5 へ進みましょう。 + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 1.5: テキスト編集 - 追加 + + + ** テキストを追加するには A を押しましょう ** + + 1. 以下の ---> と示された最初の行にカーソルを移動しましょう。 + カーソルがその文字上にあってもかまいません。 + + 2. 追加が必要な場所で A をタイプしましょう。 + + 3. テキストを追加し終えたら、 を押してノーマルモードに戻りましょう。 + + 4. 2行目の ---> と示された場所へ移動し、ステップ 2 から 3 を繰り返して文法 + を修正しましょう。 + +---> ここには間違ったテキストがあり + ここには間違ったテキストがあります。 +---> ここにも間違ったテキス + ここにも間違ったテキストがあります。 + + 5. テキストの追加が軽快になってきたらレッスン 1.6 へ進みましょう。 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 1.6: ファイルの編集 + + + ** ファイルを保存して終了するには :wq とタイプします ** + + !! NOTE: 以下のステップを実行する前に、まず全体を読んでください!! + + 1. レッスン 1.2 でやったように :q! をタイプして、このチュートリアルを終了 + します。あるいは、別の端末がある場合はそこで以下の内容を行ってもかまい + ません。 + + 2. シェルプロンプトでこのコマンドをタイプします: vim tutor + 'vim'が Vim エディタを起動するコマンド、'tutor' は編集したいファイルの + 名前です。変更してもよいファイルを使いましょう。 + + 3. 前のレッスンで学んだように、テキストを挿入、削除します。 + + 4. 変更をファイルに保存します: :wq + + 5. ステップ 1 で vimtutuor を終了した場合は vimtutor を再度起動し、以下の + 要約へ進みましょう。 + + 6. 以上のステップを読んで理解した上でこれを実行しましょう。 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 1 要約 + + + 1. カーソルは矢印キーもしくは hjkl キーで移動します。 + h (左) j (下) k (上) l (右) + + 2. Vim を起動するにはプロンプトから vim ファイル名 とタイプします。 + + 3. Vim を終了するには :q! とタイプします(変更を破棄)。 + もしくは :wq とタイプします(変更を保存)。 + + 4. カーソルの下の文字を削除するには、ノーマルモードで x とタイプします。 + + 5. カーソルの位置に文字を挿入するには、ノーマルモードで i とタイプします。 + i テキストのタイプ カーソル位置に追加 + A テキストの追加 行末に追加 + +NOTE: キーを押すとノーマルモードに移行します。その際、間違ったり入力途 + 中のコマンドを取り消すことができます。 + +さて、続けてレッスン 2 を始めましょう。 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 2.1: 削除コマンド + + + ** 単語の末尾までを削除するには dw とタイプしましょう ** + + 1. ノーマルモードであることを確認するために を押しましょう。 + + 2. 以下の ---> と示された行にカーソルを移動しましょう。 + + 3. 消したい単語の先頭にカーソルを移動しましょう。 + + 4. 単語を削除するために dw とタイプしましょう。 + + NOTE: タイプすると、dw という文字がスクリーンの最下行に現われます。 + タイプを間違ってしまった時には を押してやり直しましょう。 + +---> この 文 紙 には いくつかの たのしい 必要のない 単語 が 含まれて います。 + + 5. 3 から 4 までを文が正しくなるまで繰り返し、レッスン 2.2 へ進みましょう。 + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 2.2: その他の削除コマンド + + + ** 行の末尾までを削除するには d$ とタイプしましょう ** + + 1. ノーマルモードであることを確認するのに を押しましょう。 + + 2. 以下の ---> と示された行にカーソルを移動しましょう。 + + 3. 正しい文の末尾へカーソルを移動しましょう(最初の 。 の後です)。 + + 4. 行末まで削除するのに d$ とタイプしましょう。 + +---> 誰かがこの行の最後を2度タイプしました。 2度タイプしました。 + + + 5. どういうことか理解するために、レッスン 2.3 へ進みましょう。 + + + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 2.3: オペレータとモーション + + + 多くのコマンドはオペレータとモーションからテキストに変更を加えます。 + 削除コマンド d のオペレータは次の様になっています: + + d モーション + + それぞれ: + d - 削除コマンド。 + モーション - 何に対して働きかけるか(以下に挙げます)。 + + オペレータの一部一覧: + w - カーソル位置から空白を含む単語の末尾まで。 + e - カーソル位置から空白を含まない単語の末尾まで。 + $ - カーソル位置から行末まで。 + + つまり de とタイプすると、カーソル位置から単語の終わりまでを削除します。 + +NOTE: 冒険したい人は、ノーマルモードにてコマンドなしにモーションを押して + みましょう。カーソルが目的語一覧で示される位置に移動するはずです。 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 2.4: モーションにカウントを使用する + + + ** 何回も行いたい繰り返しのモーションの前に数値をタイプします。 ** + + 1. 以下の ---> と示された行の先頭にカーソルを移動します。 + + 2. 2w をタイプして単語2つ分前に移動します。 + + 3. 3e をタイプして3つ目の単語の終端に移動します。 + + 4. 0 (ゼロ)をタイプして行頭に移動します。 + + 5. ステップ 2 と 3 を違う数値を使って繰り返します。 + +---> This is just a line with words you can move around in. + + 6. レッスン 2.5 に進みましょう。 + + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 2.5: より多くを削除するためにカウントを使用する + + + ** オペレータとカウントをタイプすると、その操作が複数回繰り返されます。 ** + + 既述の削除のオペレータとモーションの組み合わせにカウントを追加することで、 + より多くの削除が行えます: + d 数値 モーション + + 1. ---> と示された行の行頭部分にカーソルを移動しましょう。 + + 2. UPPER CASE の単語2つを d2w とタイプして削除します。 + + 3. UPPER CASE という連続した単語を、1つのコマンドと異なるカウントを指定し、 + ステップ 1 と 2 を繰り返します。 + +---> このABC DE行のFGHI JK LMN OP単語はQ RS TUV綺麗になった。 + +NOTE: オペレータ d とモーションの間にカウントを使った場合、オペレータのない + 場合のモーションのように動作します。 + 例: 3dw と d3w は同等で、3w を削除します。 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 2.6: 行の操作 + + + ** 行全体を削除するには dd とタイプします ** + + 行全体を削除する頻度が多いので、Viのデザイナーは行の削除を d の2回タイプと + いう簡単なものに決めました。 + + 1. 以下の句の2行目にカーソルを移動します。 + 2. dd とタイプして行を削除します。 + 3. さらに4行目に移動します。 + 4. 2dd とタイプして2行を削除します。 + +---> 1) バラは赤い、 +---> 2) つまらないものは楽しい、 +---> 3) スミレは青い、 +---> 4) 私は車をもっている、 +---> 5) 時計が時刻を告げる、 +---> 6) 砂糖は甘い +---> 7) オマエモナー + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 2.7: やり直しコマンド + + + ** 最後のコマンドを取り消すには u を押します。U は行全体の取消です。 ** + + 1. 以下の ---> と示された行にカーソルを移動し、最初の間違いにカーソル + を移動しましょう。 + 2. x をタイプしていらない先頭の文字を削除しましょう。 + 3. さぁ、u をタイプして最後に実行したコマンドを取り消しましょう。 + 4. 今度は、x を使用して誤りを全て修正しましょう。 + 5. 大文字の U をタイプして、行を元の状態に戻しましょう。 + 6. u をタイプして直前の U コマンドを取消しましょう。 + 7. ではコマンドを再実行するのに CTRL-R (CTRL を押したまま R を打つ)を数回 + タイプしてみましょう(取消の取消)。 + +---> このの行のの間違いを修正々し、後でそれらの修正をを取消しまますす。 + + 8. これはとても便利なコマンドです。さぁレッスン 2 要約へ進みましょう。 + + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 2 要約 + + + 1. カーソル位置から単語の末尾までを削除するには dw とタイプします。 + 2. カーソル位置から行の末尾までを削除するには d$ とタイプします。 + 3. 行全体を削除するには dd とタイプします。 + + 4. モーションを繰り返すには数値を付与します: 2w + 5. 変更に用いるコマンドの形式は + オペレータ [数値] モーション + + それぞれ: + オペレータ - 削除 d の類で何をするか。 + 数値 - そのコマンドを何回繰り返すか。 + モーション - w (単語)や $ (行末)などの類で、テキストの何に対して働きか + けるか。 + + 6. 行の先頭に移動するにはゼロを使用します: 0 + + 7. 前回の動作を取消す: u (小文字 u) + 行全体の変更を取消す: U (大文字 U) + 取消しの取消し: CTRL-R +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 3.1: 貼り付けコマンド + + + ** 最後に削除された行をカーソルの後に貼り付けるには p をタイプします ** + + 1. 以下の段落の最初の行にカーソルを移動しましょう。 + + 2. dd とタイプして行を削除し、Vim のバッファに格納しましょう。 + + 3. 削除した行が本来あるべき位置の上の行まで、カーソルを移動させましょう。 + + 4. ノーマルモードで p をタイプして格納した行を画面に戻します。 + + 5. 順番が正しくなる様にステップ 2 から 4 を繰り返しましょう。 + + d) 貴方も学ぶことができる? + b) スミレは青い、 + c) 知恵とは学ぶもの、 + a) バラは赤い、 + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 3.2: 置き換えコマンド + + + ** カーソルの下の文字を置き換えるには r をタイプします ** + + 1. 以下の ---> と示された最初の行にカーソルを移動しましょう。 + + 2. 最初の間違いの先頭にカーソルを移動しましょう。 + + 3. r とタイプし、間違っている文字を置き換える、正しい文字をタイプしましょう。 + + 4. 最初の行が正しくなるまでステップ 2 から 3 を繰り返しましょう。 + +---> この合を人力した時ね、その人は幾つか問違ったキーを押しもした! +---> この行を入力した時に、その人は幾つか間違ったキーを押しました! + + 5. さぁ、レッスン 3.3 へ進みましょう。 + +NOTE: 実際に試しましょう。決して覚えるだけにはしないこと。 + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 3.3: 変更コマンド + + + ** 単語の一部、もしくは全体を変更するには cw とタイプします ** + + 1. 以下の ---> と示された最初の行にカーソルを移動しましょう。 + + 2. lubw の u の位置にカーソルを移動しましょう。 + + 3. cw とタイプし、正しい単語をタイプしましょう(この場合 'ine' とタイプ)。 + + 4. 次の間違い(変更すべき文字の先頭)に移動するために をタイプします。 + + 5. 最初の行が次の行の様になるまでステップ 3 と 4 を繰り返します。 + +---> This lubw has a few wptfd that mrrf changing usf the change operator. +---> This line has a few words that need changing using the change operator. + +cw は単語を変更するだけでなく、挿入も行えることに注意しましょう。 + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 3.4: c を使用したその他の変更 + + + ** 変更コマンドは、削除コマンドと同じ様にオブジェクトを使用します ** + + 1. 変更コマンドは、削除コマンドと同じような動作をします。その形式は + + c [数値] モーション + + 2. オブジェクトも同じで、w は単語、 $ は行末などといったものです。 + + 3. 以下の ---> と示された行にカーソルを移動しましょう。 + + 4. 最初の間違いへカーソルを移動しましょう。 + + 5. c$ とタイプして行の残りを２行目の様にし、 を押しましょう。 + +---> The end of this line needs some help to make it like the second. +---> The end of this line needs to be corrected using the c$ command. + +NOTE: タイプ中の間違いはバックスペースキーを使って直すこともできます。 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 3 要約 + + + 1. 既に削除されたテキストを再配置するには、p をタイプします。これは削除さ + れたテキストをカーソルの後に挿入します(行単位で削除されたのならば、カー + ソルのある次の行に挿入されます)。 + + 2. カーソルの下の文字を置き換えるには、r をタイプした後、それを置き換える + 文字をタイプします。 + + 3. 変更コマンドではカーソル位置から特定のモーションで指定される終端までを変 + 更することが可能です。例えば cw ならばカーソル位置から単語の終わりまで、 + c$ ならば行の終わりまでを変更します。 + + 4. 変更コマンドの形式は + + c [数値] モーション + +さぁ、次のレッスンへ進みましょう。 + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 4.1: 位置とファイルの情報 + + ** ファイル内での位置とファイルの状態を表示するには CTRL-G をタイプします。 + ファイル内のある行に移動するには G をタイプします ** + + NOTE: ステップを実行する前に、このレッスン全てに目を通しましょう!! + + 1. CTRL を押したまま g を押しましょう。この操作を CTRL-G と呼んでいます。 + ページの一番下にファイル名と行番号が表示されるはずです。 ステップ 3のため + に行番号を覚えておきましょう。 + +NOTE: 画面の右下隅にカーソルの位置が表示されているかもしれません。これは + 'ruler' オプション(:help 'ruler' を参照)を設定することで表示されます。 + + 2. 最下行に移動するために G をタイプしましょう。 + ファイルの先頭に移動するには gg とタイプしましょう。 + + 3. 先ほどの行の番号をタイプし G をタイプしましょう。最初に CTRL-G を押した行 + に戻って来るはずです。 + + 4. 自信が持てたらステップ 1 から 3 を実行しましょう。 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 4.2: 検索コマンド + + + ** 語句を検索するには / と、前方検索する語句をタイプします。** + + 1. ノーマルモードで / という文字をタイプします。画面一番下に : コマンドと + 同じ様に / が現れることに気づくでしょう。 + + 2. では、'errroor' とタイプしましょう。これが検索したい単語です。 + + 3. 同じ語をもう一度検索するときは 単に n をタイプします。 + 逆方向に語句を検索するときは N をタイプします。 + + 4. 逆方向に語句を検索する場合は、/ の代わりに ? コマンドを使用します。 + + 5. 元の場所に戻るには CTRL-O (Ctrl を押し続けながら o 文字タイプ)をタイプし + ます。さらに戻るにはこれを繰り返します。CTRL-I は前方向です。 + +---> "errroor" は error とスペルが違います; errroor はいわゆる error です。 +NOTE: 検索がファイルの終わりに達すると、オプション 'wrapscan' が設定されている + 場合は、ファイルの先頭から検索を続行します。 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 4.3: 対応する括弧を検索 + + + ** 対応する ),] や } を検索するには % をタイプします ** + + 1. 下の ---> で示された行で (,[ か { のどれかにカーソルを移動しましょう。 + + 2. そこで % とタイプしましょう。 + + 3. カーソルは対応する括弧に移動するはずです。 + + 4. 最初の括弧に移動するには % とタイプしましょう。 + + 5. 他の (,),[,],{ や } でカーソルを移動し、% が何をしているか確認しましょう。 + +---> This ( is a test line with ('s, ['s ] and {'s } in it. )) + + +NOTE: この機能は括弧が一致していないプログラムをデバッグするのにとても役立ち + ます。 + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 4.4: 間違いを変更する方法 + + + ** 'old' を 'new' に置換するには :s/old/new/g とタイプします ** + + 1. 以下の ---> と示された行にカーソルを移動しましょう。 + + 2. :s/thee/the とタイプしましょう。このコマンドはその行で最初に見 + つかったものにだけ行なわれることに気をつけましょう。 + + 3. では :s/thee/the/g とタイプしましょう。行全体を置換することを意味します。 + この変更はその行で見つかった全ての箇所に対して行なわれます。 + +---> thee best time to see thee flowers is in thee spring. + + 4. 複数行から見つかる文字を変更するには + :#,#s/old/new/g #,# には置き換える範囲の開始と終了の行番号を指定しま + す。 + :%s/old/new/g ファイル全体で見つかるものに対して変更する。 + :%s/old/new/gc ファイル全体で見つかるものに対して、1つ1つ確認をとりな + がら変更する。 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 4 要約 + + + 1. CTRL-G はファイルでの位置とファイルの詳細を表示します。 + G はファイルの最下行に移動します。 + 数値 G はその行に移動します。 + gg は先頭行に移動します。 + + 2. / の後に語句をタイプすると前方に語句を検索します。 + ? の後に語句をタイプすると後方に語句を検索します。 + 検索の後の n は同じ方向の次の検索を、N は逆方向の検索をします。 + CTRL-O は場所を前に移し、CTRL-I は場所を次に移動します。 + + 3. (,),[,],{, もしくは } 上にカーソルがある状態で % をタイプすると対になる文 + 字へ移動します。 + + 4. 現在行の最初の old を new に置換する。 :s/old/new + 現在行の全ての old を new に置換する。 :s/old/new/g + 2つの # 間で語句を置換する。 :#,#s/old/new/g + ファイルの中の全ての検索語句を置換する。 :%s/old/new/g + 'c' を加えると置換の度に確認を求める。 :%s/old/new/gc + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 5.1: 外部コマンドを実行する方法 + + + ** :! の後に実行する外部コマンドをタイプします ** + + 1. 画面の最下部にカーソルが移動するよう、慣れ親しんだ : をタイプしましょう。 + これでコマンドがタイプできる様になります。 + + 2. ここで ! という文字(感嘆符)をタイプしましょう。 + これで外部シェルコマンドが実行できる様になります。 + + 3. 例として ! に続けて ls とタイプし を押しましょう。 + シェルプロンプトのようにディレクトリの一覧が表示されるはずです。 + もしくは ls が動かないならば :!dir を使用しましょう。 + +NOTE: この方法によってあらゆるコマンドが実行することができます。もちろん引数 + も与えられます。 + +NOTE: 全ての : コマンドは を押して終了しなければなりません。 + 以降ではこのことに言及しません。 + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 5.2: その他のファイルへ書き込み + + + ** ファイルへ変更を保存するには :w ファイル名 とタイプします ** + + 1. ディレクトリの一覧を得るために :!dir もしくは :!ls とタイプしましょう。 + このあと を押すのは既にご存知ですね。 + + 2. TEST のように、そのディレクトリに無いファイル名を一つ選びます。 + + 3. では :w TEST とタイプしましょう (TEST は、選んだファイル名です)。 + + 4. これによりファイル全体が TEST という名前で保存されます。 + もう一度 :!dir もしくは :!ls とタイプして確認してみましょう。 + +NOTE: ここで Vim を終了し、ファイル名 TEST と共に起動すると、保存した時の + チュートリアルの複製ができ上がるはずです。 + + 5. さらに、次のようにタイプしてファイルを消しましょう(MS-DOS): :!del TEST + もしくは(Unix): :!rm TEST + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 5.3: 選択した書き込み + + +** ファイルの位置を保存するには、v モーションと :w FILENAME をタイプします。 ** + + 1. この行にカーソルを移動します。 + + 2. v を押し、以下の第5項目にカーソルを移動します。テキストが強調表示されるの + に注目して下さい。 + + 3. 文字 : を押すと、画面の最下部に :'<,'> が現れます。 + + 4. w TEST (TEST は存在しないファイル名)をタイプします。 + を押す前に :'<,'>w TEST となっていることを確認して下さい。 + + 5. Vim は TEST というファイルに選択された行を書き込むでしょう。 + !dir もしくは !ls でそれを確認します。 + それは削除しないでおいて下さい。次のレッスンで使用します。 + +NOTE: v を押すと、Visual 選択が始まります。カーソルを動かすことで、選択範囲を + 大きくも小さくもできます。さらに、その選択範囲に対してオペレータを適用 + きます。例えば d はテキストを削除します。 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 5.4: ファイルの取込と合併 + + + ** ファイルの中身を挿入するには :r ファイル名 とタイプします ** + + 1. カーソルを以下の行に合わせます。 + +NOTE: ステップ 2 の実行後、レッスン 5.3 のテキストが現れます。下に下がってこ + のレッスンに移動しましょう。 + + 2. では TEST というファイルを :r TEST というコマンドで読み込みましょう。 + ここでいう TEST は使うファイルの名前のことです。 + 読み込まれたファイルは、カーソル行の下にあります。 + + 3. 取込んだファイルを確認してみましょう。カーソルを戻すと、レッスン5.3 の + オリジナルとファイルによるものの2つがあることがわかります。 + +NOTE: 外部コマンドの出力を読み込むことも出来ます。例えば、 + :r !ls は ls コマンドの出力をカーソル以下に読み込みます。 + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 5 要約 + + + 1. :!command によって 外部コマンドを実行します。 + + よく使う例: + (MS-DOS) (Unix) + :!dir :!ls - ディレクトリ内の一覧を見る。 + :!del FILENAME :!rm FILENAME - ファイルを削除する。 + + 2. :w ファイル名 によってファイル名というファイルがディスクに書き込まれる。 + + 3. v モーションで :w FILENAME とすると、ビジュアル選択行がファイルに保存さ + れる。 + + 4. :r ファイル名 によりファイル名というファイルがディスクより取込まれ、 + カーソル位置の下に挿入される。 + + 5. :r !dir は dir コマンドの出力をカーソル位置以下に読み込む。 + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 6.1: オープンコマンド + + + ** o をタイプすると、カーソルの下の行が開き、挿入モードに入ります ** + + 1. 以下の ---> と示された行にカーソルを移動しましょう。 + + 2. o (小文字) をタイプして、カーソルの下の行を開き、挿入モードに入ります。 + + 3. さらに挿入モードを終了する為に をタイプします。 + +---> o をタイプするとカーソルは開いた行へ移動し挿入モードに入ります。 + + 4. カーソルの上の行に挿入するには、小文字の o ではなく、単純に大文字の O + をタイプします。次の行で試してみましょう。 + +---> この行の上へ挿入するには、この行へカーソルを置いて O をタイプします。 + + + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 6.2: 追加コマンド + + + ** カーソルの次の位置からテキストを追加するには a とタイプします ** + + 1. カーソルを ---> で示された行へ移動しましょう。 + + 2. e を押して li の終端部までカーソルを移動します。 + + 3. カーソルの後ろにテキストを追加するために a (小文字) をタイプします。 + + 4. その下の行のような単語に完成させます。挿入モードを抜ける為に を押 + します。 + + 5. e を使って次の不完全な単語へ移動し、ステップ 3 と 4 を繰り返します。 + +---> This li will allow you to pract appendi text to a line. +---> This line will allow you to practice appending text to a line. + +NOTE: a, i と A は同じ挿入モードへ移りますが、文字が挿入される位置だけが異なり + ます。 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 6.3: その他の置換方法 + + + ** 1文字以上を置き換えるには大文字の R とタイプしましょう ** + + 1. 以下の ---> と示された行にカーソルを移動します。最初の xxx の先頭に移動し + ます。 + + 2. R を押して、2行目の数値をタイプすることで、xxx が置換されます。 + + 3. 置換モードを抜けるには を押します。行の残りが変更されていないままに + なることに注意してください。 + + 4. 残った xxx をステップを繰り返して置換しましょう。 + +---> Adding 123 to xxx gives you xxx. +---> Adding 123 to 456 gives you 579. + +NOTE: 置換モードは挿入モードに似ていますが、全てのタイプされた文字は既存の文字 + を削除します。 + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 6.4: テキストのコピーとペースト + + + ** テキストのコピーにはオペレータ y を、ペーストには p を使います ** + + 1. ---> と示された行へ移動し、カーソルを "a)" の後に置いておきます。 + + 2. v でビジュアルモードを開始し、"first"の手前までカーソルを移動します。 + + 3. y をタイプして強調表示されたテキストを yank (コピー)します。 + + 4. 次の行の行末までカーソルを移動します: j$ + + 5. p を押して貼り付け(put)てから、次をタイプします: a second + + 6. ビジュアルモードで " item." を選択し、y でヤンク、次の行の行末まで j$ で + 移動し、 p でテキストをそこに put します。 + +---> a) this is the first item. + b) + + NOTE: 単語を1つ yank するのに y をオペレータとして yw とすることも出来ます。 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 6.5: オプションの設定 + + + ** 検索や置換の際に大文字/小文字を無視するには、オプションを設定します ** + + 1. 次の様に入力して 'ignore' を検索しましょう: /ignore + n を押して何度か検索を繰り返します。 + + 2. 次の様に入力して 'ic' (Ignore Case の略) オプションを設定します: :set ic + + 3. では n によってもう1度 'ignore' を検索します。 + n を押してさらに数回検索を繰り返しましょう。 + + 4. 'hlsearch' と 'incsearch' オプションを設定しましょう: :set hls is + + 5. 検索コマンドを再入力して、何が起こるか見てみましょう: /ignore + + 6. 大文字小文字の区別を無効にするには次の様に入力します: :set noic + +NOTE: マッチの強調表示をやめるには次の様に入力します: :nohlsearch +NOTE: 1つの検索コマンドだけ大文字小文字の区別をやめたいならば、フレーズに \c + を使用します: /ignore\c +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 6 要約 + + 1. o をタイプするとカーソルの下の行を開けて、そこで挿入モードになる。 + O (大文字) をタイプするとカーソルの上の行で挿入モードになる。 + + 2. カーソル上の文字の次からテキストを追加するには a とタイプする。 + 行末に自動でテキストを挿入するには大文字 A をタイプする。 + + 3. e コマンドは単語の終端部カーソルを移動する。 + + 4. y オペレータはテキストを yank (コピー)し、p はそれを put (ペースト)する。 + + 5. 大文字の R をタイプすると置換モードに入り、を押すと抜ける。 + + 6. ":set xxx" とタイプするとオプション "xxx" が設定される。 + 'ic' 'ignorecase' 検索時に大文字小文字の区別しない + 'is' 'incsearch' 検索フレーズに部分マッチしている部分を表示する + 'hls' 'hlsearch' マッチするすべを強調表示する + 長い方、短い方、どちらのオプション名でも使用できます。 + + 7. "no" を付与し、オプションを無効にします: :set noic + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 7.1: オンラインヘルプコマンド + + + ** オンラインヘルプを使用しましょう ** + + Vim には広範にわたるオンラインヘルプシステムがあります。 + ヘルプを開始するには、これら3つのどれか1つを試してみましょう: + - ヘルプキー を押す(もしあるならば)。 + - キーを押す(もしあるならば)。 + - :help とタイプする。 + + ヘルプウィンドウのテキストを読むと、ヘルプの動作が理解できます。 + CTRL-W CTRL-W とタイプすると ヘルプウィンドウへジャンプします。 + :q とタイプすると ヘルプウィンドウが閉じられます。 + + ":help" コマンドに引数を与えることにより、あらゆる題名のヘルプを見つけること + ができます。これらを試してみましょう( をタイプし忘れないように): + + :help w + :help c_CTRL-D + :help insert-index + :help user-manual +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 7.2: 起動スクリプトの作成 + + ** Vim の特徴を発揮する ** + + Vim には Vi よりも多くの特徴を踏まえていますが、そのほとんどは初期状態にて + 使用不可となっています。より多くの特徴を使いはじめるには "vimrc" ファイル + を作成します。 + + 1. "vimrc" ファイルの編集を開始する。これはシステムに依存します。 + :edit ~/.vimrc UNIX 向け + :edit $VIM/_vimrc MS-Windows 向け + + 2. ここでサンプルの "vimrc" を読み込みます。 + :read $VIMRUNTIME/vimrc_example.vim + + 3. 以下のようにファイルへ書き込みます。 + :write + + 次回 Vim を起動すると、色づけ構文が使えるようになるでしょう。 + この "vimrc" ファイルへ、お好みの設定を追加することができます。 + より多くの情報を得るには :help vimrc-intro とタイプします。 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 7.3: 補完 + + + ** CTRL-D と でコマンドラインを補完する ** + + 1. 互換モードでないことを確認します: :set nocp + + 2. 現在のディレクトリに在るファイルを :!ls か :!dir で確認します。 + + 3. コマンドの開始をタイプします: :e + + 4. CTRL-D を押すと Vim は "e" から始まるコマンドの一覧を表示します。 + + 5. を押すと Vim は ":edit" というコマンド名を補完します。 + + 6. さらに空白と、既存のファイル名の始まりを加えます: :edit FIL + + 7. を押すと Vim は名前を補完します。(もし一つしか無かった場合) + +NOTE: 補完は多くのコマンドで動作します。そして CTRL-D と 押してみてくだ + さい。特に :help の際に役立ちます。 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + レッスン 7 要約 + + + 1. ヘルプウィンドウを開くには :help とするか もしくは を押す。 + + 2. コマンド(cmd)のヘルプを検索するには :help cmd とタイプする。 + + 3. 別のウィンドウへジャンプするには CTRL-W CTRL-W とタイプする。 + + 4. ヘルプウィンドウを閉じるには :q とタイプする。 + + 5. お好みの設定を保つには vimrc 起動スクリプトを作成する。 + + 6. : command で可能な補完を見るには CTRL-D をタイプする。 + 補完を使用するには を押す。 + + + + + + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + これにて Vim のチュートリアルを終わります。エディタを簡単に、しかも充分に + 使うことができるようにと、Vim の持つ概念の要点のみを伝えようとしました。 + Vim にはさらに多くのコマンドがあり、ここで全てを説明することはできません。 + 以降はユーザーマニュアルを参照ください: ":help user-manual" + + これ以後の学習のために、次の本を推薦します。 + Vim - Vi Improved - by Steve Oualline + 出版社: New Riders + 最初の本は完全に Vim のために書かれました。とりわけ初心者にはお奨めです。 + 多くの例題や図版が掲載されています。 + 次のURLを参照して下さい http://iccf-holland.org/click5.html + + 次は Vim よりも Vi について書かれた古い本ですが推薦します: + Learning the Vi Editor - by Linda Lamb + 出版社: O'Reilly & Associates Inc. + Vi でやりたいと思うことほぼ全てを知ることができる良書です。 + 第6版では、Vim についての情報も含まれています。 + + このチュートリアルは Colorado State University の Charles Smith のアイデア + を基に、Colorado School of Mines の Michael C. Pierce と Robert K. Ware の + 両名によって書かれました。 E-mail: bware@mines.colorado.edu. + + Modified for Vim by Bram Moolenaar. + + 日本語訳 松本 泰弘 + 監修 村岡 太郎 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + vi:set ts=8 sts=4 sw=4 tw=78: diff --git a/vim_faq/README b/vim_faq/README new file mode 100644 index 000000000..b6e357de9 --- /dev/null +++ b/vim_faq/README @@ -0,0 +1,5 @@ +[vim_faq : The Vim-FAQ from vimdoc.sourceforge.net] +http://www.vim.org/scripts/script.php?script_id=3298 + +[chrisbra/vim_faq - GitHub] +https://github.com/chrisbra/vim_faq diff --git a/vim_faq/vim_faq.jax b/vim_faq/vim_faq.jax new file mode 100644 index 000000000..22ee69d91 --- /dev/null +++ b/vim_faq/vim_faq.jax @@ -0,0 +1,7152 @@ +*vim_faq.txt* よく訊かれる質問 + +このファイルをインストールする方法については、vim内で > + :help add-local-help +とタイプしてください。 + +Last updated on: 17 October 2004 + + VIM リファレンスマニュアル by: Yegappan Lakshmanan + +Frequently Asked Questions *faq* *FAQ* + +このVim FAQは、vim@vim.orgメーリングリストとcomp.editorsニューズグループに投稿 +された質問とその答から作られました。Vimにおいて問題を解決する方法はいくつかあ +ります。このFAQを読めば、その数種類の可能性のうちの1つが得られます。このFAQ中 +の情報とリンクを使って他の方法を探すこともできます。このFAQの答に対するクレ +ジットはPeppe, Benji, Charles Campbellと他多数の人々に帰属します。 + + *faq-index* +目次 + *faq-general-information* +SECTION 1 - 一般的な情報 +|faq-1.1| Vimとは何ですか？ +|faq-1.2| 誰が Vim を書いたんですか？ +|faq-1.3| Vim は Vi と互換性がありますか？ +|faq-1.4| Vim が Vi よりも向上している点は何ですか？ +|faq-1.5| Vim は無料ですか？ + *faq-resources* +SECTION 2 - 情報源 +|faq-2.1| どこに行けば Vim についてもっと学べるでしょうか？ +|faq-2.2| メーリングリストはありますか？ +|faq-2.3| メーリングリストのアーカイブはありますか？ +|faq-2.4| HTML/PDF/PS形式のVimユーザーマニュアルはどこで手に入りますか？ +|faq-2.5| ある問題が発生しました。それが私の設定によるものか、Vimそのものの + 問題かはどうすればわかりますか？ +|faq-2.6| どこでバグ報告をすればいいですか？ +|faq-2.7| FAQはどこで見つけられますか？ +|faq-2.8| このFAQに答えが見つからなかった時、どうすればいいですか？ +|faq-2.9| Vimに機能を追加するパッチを持っています。これをどこへ送ればいいで + すか？ +|faq-2.10| Vimのtipを持っていたり新しいsyntax/indent/filetype/compilerプラグ + インを開発したり、新しいスクリプトやカラースキームを開発しました。 + これをアップロードできる公開のウェブサイトはありますか？ + *faq-availability* +SECTION 3 - 入手 +|faq-3.1| Vim の最新のバージョンは何ですか？ +|faq-3.2| どこで Vim の最新版を見つけられますか？ +|faq-3.3| どのプラットフォーム上で実行できるんですか？ +|faq-3.4| どこでVimのランタイムファイルの最新バージョンをダウンロードできま + すか？ + *faq-help* +SECTION 4 - ヘルプ +|faq-4.1| どうやってヘルプファイルを利用するんですか？ +|faq-4.2| どうやってVimヘルプファイル中のキーワードを探すんですか？ +|faq-4.3| エラーメッセージE123が出ました。なにがまずいのでしょうか？ +|faq-4.4| Vimの様々なモードについては何を読めばいいですか？ +|faq-4.5| 新しいVimヘルプファイルを追加した後、どうすればVimのヘルプタグファ + イルを生成することができますか？ +|faq-4.6| 圧縮したヘルプファイルを使うことはできますか？ + *faq-editing-a-file* +SECTION 5 - ファイルの編集 +|faq-5.1| ファイルを編集用に読み込むには？ +|faq-5.2| 現在のファイルを別な名前で保存(save as)して新しいファイルを編集す + るには？ +|faq-5.3| カレントディレクトリを現在のファイルのディレクトリにするには？ +|faq-5.4| ファイルの末尾に改行文字(EOL)をつけずにファイルを書き込むには？ +|faq-5.5| ファイルを最後に編集した場所から開くようにするには？ +|faq-5.6| Vimでファイルを編集中にそのファイルが他のアプリケーションによって + 変更されたとき、Vimは変更が検出されるたびに警告ウィンドウ(確認ダイ + アログのような)を開きます。この警告を無効にするには？ +|faq-5.7| カーソル下のファイル名のファイルを開くには？ +|faq-5.8| 現在のファイルを再読み込みするには？ +|faq-5.9| ファイルを定期的に自動保存するには？ +|faq-5.10| ファイルを読み取り専用モードで開くには？ + *faq-editing-multiple-files* +SECTION 6 - 複数のファイルを編集する +|faq-6.1| Vim内で同時に複数のファイルを開くには？ +|faq-6.2| 複数のファイル・バッファを切り替えるには？ +|faq-6.3| それぞれのファイルを別ウィンドウで開くには？ +|faq-6.4| 「ワークセット」や「プロジェクト」のように自動的に複数のファイルを + 同時に読み込ませるようにするには？ +|faq-6.5| Neditやemacsのように単一のVimインスタンスで複数のトップレベルウィ + ンドウを開くことはできますか？ +|faq-6.6| Vim内でディレクトリをブラウズするには？ +|faq-6.7| ftp/scp/rcp/httpでネットワークごしにファイルを編集するには？ + *faq-backup* +SECTION 7 - バックアップ +|faq-7.1| ファイルを保存したとき元のファイル名の末尾に"~"という文字をつけた + ファイルが作られます。このファイルを作成するのを止めさせるには？ + (または)バックアップ機能を無効にするには？ +|faq-7.2| 全てのバックアップファイルを特定のディレクトリに保存するように設定 + するには？ +|faq-7.3| ファイルを保存するとファイルパーミッションが変更されます。ファイル + パーミッションを変更せずにファイルを保存するよう設定するには？ + *faq-buffers* +SECTION 8 - バッファ +|faq-8.1| バッファに対して変更を加えました。変更されたバッファを保存せずに、 + かつ変更を失うことなく他のバッファを編集するには？ +|faq-8.2| バッファを切り替えるときに自動的に保存するよう設定するには？ +|faq-8.3| カレントウィンドウのバッファを空バッファにするには？ +|faq-8.4| バッファ番号を指定してバッファを読み込むショートカットキーはありま + すか？ +|faq-8.5| 読み込んでいるバッファをそれぞれ別のウィンドウで開くには？ +|faq-8.6| Vimを終了することなくバッファを閉じる(削除する)には？ +|faq-8.7| :e filenameでいくつかのファイルを開きました。Vimを終了することなく + そのバッファのうちの1つを閉じるには？ +|faq-8.8| ":%bd"コマンドで全バッファを削除しようとしても、全てのバッファが + 削除されません。なぜ？ +|faq-8.9| カレントバッファ/ファイルのバッファ番号を表示するには？ +|faq-8.10| ウィンドウを閉じることなくバッファを削除するには？ +|faq-8.11| Tabキーで全バッファを巡回するようにマップするには？ + *faq-windows* +SECTION 9 - ウィンドウ +|faq-9.1| ウィンドウとバッファの違いは？ +|faq-9.2| ウィンドウの幅を広げるには？ +|faq-9.3| ウィンドウをズームイン・ズームアウトするには？ +|faq-9.4| 全バッファまたは全ウィンドウ、引数リスト中の全ファイルに対してex + コマンドを実行するには？ + *faq-motion* +SECTION 10 - モーション +|faq-10.1| ファイルの先頭や末尾に移動するには？ +|faq-10.2| 挿入モードでキーを押してノーマルモードに移行すると、カーソル + が1文字左へ移動します(カーソルが行の最初の文字の上にあるときを除い + て)。この動作を変更し、カーソルがその桁の上に残るようにできますか？ +|faq-10.3| 、などのキーを押してスクロールしたときカーソル + 位置の桁を保つように設定することはできますか？ +|faq-10.4| ファイル中のある行の長さが画面の幅を越えており、折り返されていま + す。ここでj, kキーを使うと画面上の次行(物理行)でなくファイルの次行 + (論理行)に移動します。画面上の次行に移動するには？ +|faq-10.5| Vimにおける文、段落、セクションの定義は？ +|faq-10.6| 文、段落、セクションの先頭と末尾に移動するには？ +|faq-10.7| 画面の右端を越えて続いている行があります。右側にスクロールして画面 + 外に出ているテキストを表示するには？ +|faq-10.8| 2個以上のバッファを同時にスクロールさせるには？ +|faq-10.9| 矢印キーを使うとモードが変わり、バッファに変な文字が挿入され、カー + ソルが適切に移動しません。どうなっているのですか？ +|faq-10.10| カーソルが行頭にあるとき左矢印キーを押すと前行の行末に移動するよう + にするには？ +|faq-10.11| 常に挿入モードに留まるようにするには？(モードレスな編集をするに + は？) +|faq-10.12| テキストをスクロールするとき、前後の行を表示するには？ +|faq-10.13| 以前のカーソル位置に戻るには？ + *faq-searching-text* +SECTION 11 - テキストを検索する +|faq-11.1| テキストを検索した後、マッチしたテキストが全て強調されます。この強 + 調を一時的/永続的に無効にするには？ +|faq-11.2| 検索パターンにキャリッジリターン文字を含めるには？ +|faq-11.3| 文字^Mを検索するには？ +|faq-11.4| '~R', '~S'などと表示される文字を検索・置換するには？ +|faq-11.5| ファイル中の印字不能文字を全て強調するには？ +|faq-11.6| 単語に完全に一致するテキストを検索するには？ +|faq-11.7| カーソル下の単語を検索するには？ +|faq-11.8| 大文字・小文字を区別せず検索するには？ +|faq-11.9| 2回続けて現れる単語を検索するには？ +|faq-11.10| ある単語がバッファ中に何回現れるか数えるには？ +|faq-11.11| 検索時にカーソルをマッチした単語の末尾に移動させるには？ +|faq-11.12| 空行を検索するには？ +|faq-11.13| 1つの文字だけを含む行を検索するには？ +|faq-11.14| 複数のファイルから文字列を検索し、置換するには？ +|faq-11.15| マップ中で置換コマンド":s"を使っています。検索が失敗したときマップ + が途切れてしまいます。置換が失敗したときにもマップの次のコマンドを + 続けてほしいのですが、どうすればできますか？ +|faq-11.16| 行からある文字がn回目に現れる箇所を検索するには？ +|faq-11.17| タブ(やその他の文字)を改行文字で置換するには？ +|faq-11.18| ASCIIコードで検索する文字を指定するには？ +|faq-11.19| 長い行を見つけるには？ +|faq-11.20| カレントバッファ内の指定したパターンを含む行を全て表示するには？ +|faq-11.21| 複数行にわたる文字列を検索するには？ +|faq-11.22| バッファの指定した範囲内から検索するには？ + *faq-changing-text* +SECTION 12 - テキストを変更する +|faq-12.1| 行末の空白文字(スペースとタブ)を全て削除するには？ +|faq-12.2| 連続する空白文字を1個のスペースに置換するには？ +|faq-12.3| 連続する空行を1行だけに圧縮するには？ +|faq-12.4| ファイル中の空行を全て削除するには？空白文字だけを含む行を全て削除 + するには？ +|faq-12.5| カーソル下の単語をコピー/ヤンクするには？ +|faq-12.6| 行全体ではなく、行内のある位置からある位置までをヤンクするには？ +|faq-12.7| 現在のレジスタの中身に追加ヤンクするには？ +|faq-12.8| 複数行にわたる文全体をヤンクするには？ +|faq-12.9| あるパターンを含む行全てをヤンクするには？ +|faq-12.10| あるパターンを含まない行全てを削除するには？ +|faq-12.11| "pattern"を含む全ての行の前に行を追加するには？ +|faq-12.12| 前の行が特定のパターンを含んでいる行に対して操作を行うには？ +|faq-12.13| あるパターンを含む行全てに対してコマンドを実行するには？ +|faq-12.14| カーソル位置の1文字上の文字をカーソル位置にコピーするには？ +|faq-12.15| 挿入モードに入らずに現在行の前/後に空行を挿入するには？ +|faq-12.16| カレントファイルの名前をカレントバッファに挿入するには？ +|faq-12.17| レジスタの中身をカレントバッファに挿入するには？ +|faq-12.18| 行末を越えてカーソルを移動し、テキストを挿入するには？ +|faq-12.19| カーソル下の単語(例えばjunk)を"foojunkbar"に置き換えるには？ +|faq-12.20| ディレクトリ中の全てのファイルに対して特定のテキストを置換する + には？ +|faq-12.21| ファイル中に数字が書かれています。これを増加・減少させるには？ +|faq-12.22| ":substitute"で最後に検索したパターンを再利用するには？ +|faq-12.23| ":substitute"を使って大文字・小文字を入れかえるには？ +|faq-12.24| キーボード上に無い文字を入力するには？ +|faq-12.25| ダイグラフのどれか、または全てを削除するコマンドはありますか？ +|faq-12.26| 挿入モードでバックスペースキーを押すと、今回の挿入モードで入力した + 文字が消されるだけです。バックスペースキーで前回の挿入モードで入力 + した文字を消すには？ +|faq-12.27| 72文字より長くて"+"で終わり、次行に折り返されている行があります。 + このような行をすばやく連結させるには？ +|faq-12.28| 文字単位でヤンクされたテキストを新しい行にペーストするには？ +|faq-12.29| 単語・文字・テキストのブロックの大文字小文字を入れかえるには？ +|faq-12.30| キーボード上にないASCII文字を入力するには？ +|faq-12.31| ファイル中の印字不能文字を置換するには？ +|faq-12.32| バッファから重複した行を削除するには？ +|faq-12.33| ファイル中の全ての行の前に行番号をつけるには？ +|faq-12.34| 2つの文字・単語・行を入れ換えるには？ + *faq-completion-in-insert-mode* +SECTION 13 - 挿入モードでの補完 +|faq-13.1| 挿入モードで単語や行を補完するには？ +|faq-13.2| 挿入モードでファイル名を補完するには？ +|faq-13.3| 挿入モードで単語を補完するのにCTRL-P/CTRL-Nを使っています。 + 今補完した単語の後に現れる単語を補完するには？ + *faq-text-formatting* +SECTION 14 - テキストの整形 +|faq-14.1| 折り返された行の末尾に改行を挿入するには？ +|faq-14.2| 1行がn文字以下になるように長い行を整形するには？ +|faq-14.3| 短い行を連結して段落を形成するには？ +|faq-14.4| 箇条書きや番号つきリストを整形するには？ +|faq-14.5| 挿入モードで行をインデントするには？ +|faq-14.6| ファイル全体を整形・インデントするには？ +|faq-14.7| 現在のファイルのインデントを増やす/減らすには？ +|faq-14.8| ブロックまたは行のグループをインデントするには？ +|faq-14.9| >または<キーで行をインデントすると、'tabstop'で設定した値でなく、 + 標準的なタブストップ値の8が使われます。なぜですか？ +|faq-14.10| オートインデントを無効にするには？ +|faq-14.11| メールを編集するときは自動的に'textwidth'オプションをある値にする + ようにするには？ +|faq-14.12| 自動的に改行を挿入させることはできますか？ +|faq-14.13| ファイル中に^Mという記号がたくさん表示されます。'fileformat'を + 'dos'にしたり'unix'にしたり'mac'にしたりしてみましたが、改善できま + せん。これらの記号を表示させなくするには？ +|faq-14.14| 他のアプリケーションからVimのバッファへテキストを貼り付けたとき、 + 挿入されたテキストの桁(インデント)が狂ってしまいます。 + これを直すには？ +|faq-14.15| 'wrap'をオンにしていて、とても長い行が折り返されて画面に収まりきら + ないとき、まったく何も表示されません。折り返された行の代わりに'@' + という記号で始まる空の行が表示されます。行が収まるように画面をスク + ロールすると'@'は消え、行が表示されるようになります。この挙動の設 + 定はどうやるのですか？ +|faq-14.16| ファイル中の全てのタブ文字をスペースに変換するには？ +|faq-14.17| 後でワードプロセッサに送るテキストを編集するためのオプションは？ + *faq-visual-mode* +SECTION 15 - ビジュアルモード +|faq-15.1| 矩形範囲をコピーするには？ +|faq-15.2| ファイルの特定の列を削除・変更するには？ +|faq-15.3| ビジュアル選択した行に対してexコマンドを適用するには？ +|faq-15.4| 矩形選択した範囲に対してexコマンドを適用するには？ +|faq-15.5| ビジュアルモードでファイル全体を選択するには？ +|faq-15.6| ビジュアル選択してから>キーを押してインデントすると、選択が解除さ + れます。この範囲に対して操作を続けるため選択したままにするには？ + (または)最後に選択された範囲を再選択するには？ +|faq-15.7| ビジュアル選択した範囲の先頭/末尾へ移動するには？ +|faq-15.8| マウスでテキストを選択してからexコマンドを実行しようと:キーを押す + と選択された範囲が文字:で置換されてしまいます。マウスで選択したと + きもビジュアル選択したときのようにテキストに対してexコマンドを実行 + するには？ +|faq-15.9| マウスでテキストを選択するとビジュアルモードでなく選択モードに入っ + てしまいます。なぜですか？ +|faq-15.10| 最後にコピー/ペーストされたテキストをビジュアル選択するには？ + *faq-command-line-mode* +SECTION 16 - コマンドラインモード +|faq-16.1| コマンドモードまたはexコマンドモードでカレントファイル名を使うには？ +|faq-16.2| Vimのコマンドラインで効率的にテキストを編集するには？ +|faq-16.3| ViモードからExモードに移行するには？ +|faq-16.4| exコマンドの出力をバッファにコピーするには？ +|faq-16.5| コマンドモードでファイル名を補完しようとタブキーを押します。マッチ + するファイル名が複数ある時、Vimは最初にマッチするファイル名を補完 + し、マッチしたファイル名全てのリストを表示します。マッチしたファイ + ル名全てを表示するだけで、最初の候補を補完しないようにするには？ +|faq-16.6| バッファからコマンドラインにテキストをコピーしたり、コマンドライン + からバッファにテキストをコピーするには？ +|faq-16.7| あるコマンドを実行することなくコマンド履歴に入れるには？ +|faq-16.8| コマンドラインの高さを上げるには？ + *faq-viminfo* +SECTION 17 - VIMINFO +|faq-17.1| Vimを起動したときviminfoファイルに不正な文字があるとエラーメッセー + ジが出ます。このメッセージを出なくさせるには？ +|faq-17.2| viminfo機能を無効にするには？ +|faq-17.3| Vimのセッションをまたいでマークを保存し、使用するには？ + *faq-remote-editing* +SECTION 18 - リモート編集 +|faq-18.1| 既に起動しているgvimでファイルを開くには？ Vim 5.xの + OpenWithVim.exeとSendToVim.exeはどうなりました？ +|faq-18.2| vimサーバーに全てのバッファをディスクに保存するようなコマンドを送 + るには？ +|faq-18.3| Vimのリモートサーバー機能についてのドキュメントはどこで手に入りま + すか？ + *faq-options* +SECTION 19 - オプション +|faq-19.1| Vimを設定する簡単な方法は？ +|faq-19.2| オプションの値をトグルするには？ +|faq-19.3| 現在のバッファ/ウィンドウに対してだけ効果を及ぼすようにオプション + を設定するには？ +|faq-19.4| オプションの値にスペースを含めるには？ +|faq-19.5| オプション設定をファイルに埋め込むには？ +|faq-19.6| ファイル中の全ての行の行番号を表示するには？ +|faq-19.7| 'number'オプションで表示される行番号の幅を変えるには？ +|faq-19.8| スペース、タブ、改行などの不可視文字を表示するには？ +|faq-19.9| 常に現在行と桁番号を表示するようにするには？ +|faq-19.10| 現在のモードを表示するようにするには？ +|faq-19.11| ステータスラインに入力途中のコマンドを表示するようにするには？ +|faq-19.12| ステータスラインに異なる設定・値を表示するようにするには？ +|faq-19.13| 常にステータスラインを表示するようにするには？ +|faq-19.14| Vimを再起動しても設定が永続するようにするには？ +|faq-19.15| なぜエスケープキーを押すと約1秒後にビープが鳴る(画面がフラッシュす + る)のですか？ +|faq-19.16| 'c'と's'を使ったときに変更する文字を削除するのでなく'$'を表示する + ようにするには？ +|faq-19.17| 1回の":set"コマンドでオプションから複数のフラグを除去するには？ + *faq-mapping-keys* +SECTION 20 - キーマップ +|faq-20.1| キーがどうマップされているかを知るには？ +|faq-20.2| ユーザー定義のキーマッピングをリストするには？ +|faq-20.3| キーマップを解除するには？ +|faq-20.4| キーへマッピングができません。なにがまずいのですか？ +|faq-20.5| テンキーにマップするには？ +|faq-20.6| ビジュアルモードでのみ機能するマッピングを作成するには？ +|faq-20.7| Vimスクリプト中で、すでに使われているキーと衝突しないようにどの + キーを使うべきかを知るには？ +|faq-20.8| エスケープキーにマップするには？ +|faq-20.9| あるキーをなにもしないようにマップするには？ +|faq-20.10| Tabキーでテキストのブロックをインデントし、Shift-Tabでテキストのブ + ロックをアンインデントするようにしたいです。このようなマップを作る + には？この挙動はtextpadやVisual Studioなどに似ています。 +|faq-20.11| 私のマッピングにおいてのような特殊文字が認識されません。 + 特殊文字を認識するように設定するには？ +|faq-20.12| マップ中で'|'を使って複数のコマンドを区切るには？ +|faq-20.13| その最後が他のマッピング/短縮入力の始まりとなっているマッピング/短 + 縮入力があります。最初のものを入力したとき、2番目のが展開しないよ + うにするには？ +|faq-20.14| ときどきキーが処理されるのに1秒程度かかるのはなぜですか？ +|faq-20.15| ビジュアル選択したテキストに対して外部コマンドを実行するマッピング + を作るには？ +|faq-20.16| キーの機能を保ったままCtrl-Iにマッピングするには？ + *faq-abbreviations* +SECTION 21 - 短縮入力 +|faq-21.1| スペリングを間違えた単語を自動的に修正するには？ +|faq-21.2| 複数行の短縮入力を作るには？ +|faq-21.3| 短縮入力が展開されたとき、展開されたテキストの末尾に余計なスペース + が入ってしまいます。これを防ぐには？ +|faq-21.4| 現在の日付・時刻を挿入するには？ +|faq-21.5| 挿入モードで短縮入力が展開されるのを防ぐには？ + *faq-record-and-playback* +SECTION 22 - レコーディングと繰り返し +|faq-22.1| 編集操作(挿入、削除、ペースト等)を繰り返すには？ +|faq-22.2| キーシーケンスを記録し、繰り返すには？ +|faq-22.3| 記録したキーシーケンスを編集するには？ +|faq-22.4| 記録したキーシーケンスをファイルに保存するには？ +|faq-22.5| レジスタ0にキーシーケンスを保存しています(つまり q0 .... q)。 + 記録したキーシーケンスの中でテキストをヤンクしています。一度その + キーシーケンスを再生すると、もうそれを再現することができません。 + *faq-autocommands* +SECTION 23 - 自動コマンド +|faq-23.1| 読み込み専用ファイルを修正しようとしたときにコマンドを実行するには？ +|faq-23.2| あるバッファに入るときに毎回コマンドを実行するには？ +|faq-23.3| あるウィンドウに入るときに毎回コマンドを実行するには？ +|faq-23.4| autocmd中でその自動コマンドが実行されているファイルの名前やバッ + ファ番号を知るには？ +|faq-23.5| Vimがフォーカスを失ったとき、変更されたバッファ全てを自動的に保存 + するには？ +|faq-23.6| Vimを終了するときにクリーンアップ用の関数を実行するには？ + *faq-syntax-highlight* +SECTION 24 - 構文強調 +|faq-24.1| 構文強調をオン・オフにするには？ +|faq-24.2| 背景色と文字色を変えるには？ +|faq-24.3| 暗い/明るい背景色に合うように色を変えるには？ +|faq-24.4| ":set number"をしたときに表示される行番号の色を変えるには？ +|faq-24.5| ビジュアルモードで選択された範囲の背景色を変えるには？ +|faq-24.6| オプション'list'で表示した特殊文字(タブ、行末の空白、行末など)に色 + をつけるには？ +|faq-24.7| 毎回同じカラースキームを使うように.vimrc/.gvimrcで設定するには？ +|faq-24.8| 正しく構文強調されません。ファイルの一部が強調されなかったり、間 + 違って強調されてしまいます。 +|faq-24.9| 対応する括弧を強調する組み込みの関数はありますか？ +|faq-24.10| Cのコメントの構文強調をオフにするには？ +|faq-24.11| Vimに付属する標準の構文ファイルに私自身の構文拡張を加えるには？ +|faq-24.12| Vimに付属の標準の構文ファイルを独自の構文ファイルで置き換えるには？ +|faq-24.13| 特定の桁以降の全ての文字を強調するには？ +|faq-24.14| ソースファイル(.c, .hなど)を構文強調つきでHTMLファイルに変換するに + は？ +|faq-24.15| 現在の強調グループ定義を全て表示するには？ + *faq-vim-script-writing* +SECTION 25 - VIMスクリプトを書く +|faq-25.1| 読み込まれているスクリプトを全て表示するには？ +|faq-25.2| Vimスクリプトをデバッグするには？ +|faq-25.3| あるオプションを設定したスクリプト/プラグインを探すには？ +|faq-25.4| (おそらくスクリプトを実行中に)エラーやメッセージが出るのですが、す + ぐに消えてしまいます。このメッセージをもう一度表示するには？ +|faq-25.5| プラグイン固有の情報を保存し、Vimを再起動したときそれを復元するに + は？ +|faq-25.6| 関数の中から挿入モードを開始するには？ +|faq-25.7| 関数の中でカーソル位置を動かすには？ +|faq-25.8| .vimrcファイルの中で環境変数の値をチェックするには？ +|faq-25.9| 環境変数が定義されているかどうかをチェックするには？ +|faq-25.10| Vimの組み込み関数を呼ぶには？ +|faq-25.11| Vimスクリプト中でノーマルコマンドを使っています。そのコマンドに対 + してユーザー定義のマッピングが働くのを防ぎ、そのノーマルモードコマ + ンドがVimの標準の機能を果たすようにするには？ +|faq-25.12| ビジュアルモードで現在選択されているテキストを変数やレジスタに入れ + るには？ +|faq-25.13| 変数'myvar'にテキストが入っています。この変数を":s"中で使って + 'mytext'というテキストを置換したいのですが、どうすればいいですか？ +|faq-25.14| 変数"bno"がバッファ番号を保持しています。この変数を使って対応する + バッファを開くには？ +|faq-25.15| オプションの値を変数に保存するには？ +|faq-25.16| 関数の中でテキストをコピーし、バッファに挿入しました。関数の中で + そのテキストをインデントするには？ +|faq-25.17| Vimスクリプト中でカーソル下の文字を取得するには？ +|faq-25.18| 拡張子を除いたカレントファイル名を取得するには？ +|faq-25.19| カレントファイルのベース名(basename)を取得するには？ +|faq-25.20| 関数の結果をカレントバッファに挿入するには？ +|faq-25.21| 関数の中で外部プログラムを呼ぶには？ +|faq-25.22| ":!"で実行したプログラムが返すステータス値を取得するには？ +|faq-25.23| カレントバッファが変更されているかどうかを知るには？ +|faq-25.24| スクリプト中でノーマルコマンドの中に改行文字を使いたいです。改行文 + 字を指定するには？ +|faq-25.25| スクリプト中で長い行を次行に継続するには？ +|faq-25.26| "execute 'echo Myfunc()'"として自作の関数を呼ぼうとすると、カーソ + ルがカレントバッファの先頭に移動してしまいます。なぜ？ +|faq-25.27| レジスタの中身を実行するには？ +|faq-25.28| 関数やマップを呼んだ後に'u'キーを押してアンドゥするとその関数/ + マップによってなされた変更全てをアンドゥします。なぜ？ +|faq-25.29| s:つきで定義された関数(スクリプトローカル関数)を別のスクリプト/ + プラグインから呼ぶには？ +|faq-25.30| 読み込んだスクリプトをun-sourceするには？言い替えると、スクリプト + を読み込んだことによって実行されたコマンドを全て戻すには？ + *faq-plugins* +SECTION 26 - プラグイン +|faq-26.1| ファイル形式ごとに異なるオプションを設定するには？ +|faq-26.2| プラグイン/構文ファイル/インデントファイル/カラースキーム/ファイル + タイププラグインをダウンロードしました。Vimがこれらのファイルを読 + み込むようにするには、どこにコピーすればいいですか？ +|faq-26.3| 既存のファイル形式別プラグインを拡張するには？ +|faq-26.4| プラグインの読み込みをオフにするには？ +|faq-26.5| ファイル形式別プラグインの読み込みをオフにするには？ +|faq-26.6| 全てのファイル形式に対し、グローバルのファイル形式別プラグインで + なされる設定を上書きするには？ +|faq-26.7| Vimのディレクトリブラウザプラグインを無効にするには？ +|faq-26.8| 特定のパターンにマッチする名前のファイルや拡張子に応じてファイル + タイプオプションを設定するには？ + + *faq-editing-program-files* +SECTION 27 - プログラムファイルを編集する +|faq-27.1| C/C++のファイルに対してオートインデントを有効化するには？ +|faq-27.2| C/C++のファイルに対するインデントをカスタマイズするには？ +|faq-27.3| オートインデント機能を無効化するには？ +|faq-27.4| オートインデントの際に挿入されるスペースの数を変えるには？ +|faq-27.5| Cプログラムを編集しています。マクロ定義や変数を表示するには？ +|faq-27.6| Cプログラムを編集しています。ブロックの内側から、そのブロックの開 + 始位置や終了位置にジャンプするには？ +|faq-27.7| C++ファイルで"//"コメントが自動的に挿入されるのを止めさせるには？ +|faq-27.8| 一連の行の行頭にコメント文字'#'をつけ加えるには？ +|faq-27.9| Cのソースファイルに対応する名前のヘッダファイルを開くには？ +|faq-27.10| コメントを入力しているとき、自動的にコメント文字を挿入するには？ + *faq-quickfix* +SECTION 28 - QuickFix +|faq-28.1| Vimの中からプログラムをビルドするには？ +|faq-28.2| Vim中からmakeコマンドを起動すると、コンパイラがプログラムをコンパ + イルしてエラーメッセージを出力します。しかしコンパイルが終わると表 + 示が消えてしまい、エラーメッセージをもう一度見るには :clist としな + ければなりません。このエラーメッセージを見るのに他の方法はありませ + んか？ + *faq-folding* +SECTION 29 - 折り畳み +|faq-29.1| 折り畳みの機能を拡張するには？ +|faq-29.2| 'foldmethod'をセットして折り畳みを有効化すると、全ての折り畳みが閉 + じてしまいます。これを防ぐには？ +|faq-29.3| ファイルの編集を開始したときにいくつの折り畳みが開かれた状態にする + かをコントロールするには？ +|faq-29.4| マウスを使って折り畳みを開閉するには？ +|faq-29.5| 閉じた折り畳みの表示に使われるテキストを変更するには？ +|faq-29.6| Vimを終了・再起動するとき、手動で作った折り畳みを保存・復元するに + は？ + *faq-vim-with-external-applications* +SECTION 30 - 外部プログラムとの連携 +|faq-30.1| Vimのウィンドウの中でシェルを起動することはできますか？ +|faq-30.2| カーソル下の単語を外部プログラムに渡すには？ +|faq-30.3| シェルコマンドの出力をVimのバッファに取り込むには？ +|faq-30.4| カレントバッファの中身を外部プログラムにパイプで渡して、そのプログ + ラムの出力でバッファを置き換えるには？ +|faq-30.5| ファイル中のあるセクションをソートするには？ +|faq-30.6| Vimとslrnといっしょに使うステップ・バイ・ステップガイドはあります + か？ +|faq-30.7| Vimをページャとして使うには？ +|faq-30.8| Vimの中でUnixのmanページを見るには？ +|faq-30.9| Vimのdiff機能で使われるdiffコマンドを変更するには？ +|faq-30.10| 折り畳みなしで差分モードを使うには？ + *faq-gui-vim* +SECTION 31 - GUIのVIM +|faq-31.1| バッファ固有のメニューを作るには？ +|faq-31.2| GUIのVimで使われるフォントを変更するには？ +|faq-31.3| GUIのVimが起動したときのウィンドウの位置を指定するには？ +|faq-31.4| GVimに水平スクロールバーをつけるには？ +|faq-31.5| スクロールバーをデフォルトで左側に表示するようにするには？ +|faq-31.6| メニューバーを消すには？ +|faq-31.7| GVimを使っています。ALTキーと文字キーを押すとその文字で始まるメ + ニューが選択されます。ALT-の組合せを使いたいので、この挙動は + やめてほしいです。どうすればいいですか？ +|faq-31.8| スクロールバーをドラッグしたとき、カーソル位置を動かさずにテキスト + をスクロールさせることは可能ですか？ +|faq-31.9| ":browse"を使ったときに特定のディレクトリから始めるようにするには？ +|faq-31.10| ファイルがVimの外部で変更されたときなど、問い合わせがあるとき、GUI + のダイアログボックスが表示されます。コンソールのダイアログボック + スが出るようにするには？ +|faq-31.11| GVimをアプリケーションxxx用のエディタとして使っています。アプリ + ケーションxxxがGVimを起動すると、コントロールがすぐにアプリケー + ションxxxに戻ってしまいます。Vimを終了したとき初めてアプリケーショ + ンxxxにコントロールが戻るようにGVimを起動するには？ +|faq-31.12| なぜ、システムにインストールされているフォント全てが「フォントを + 選ぶ」ダイアログに現れないのですか？ +|faq-31.13| コマンドラインモードでマウスを使うには？ +|faq-31.14| テキストをスクロールしようとマウスの中央ボタンを押すと、最後にコ + ピーしたテキストがペーストされてしまいます。この挙動を無効にするに + は？ +|faq-31.15| GVimウィンドウの位置とサイズを変更するには？ + *faq-vim-on-unix* +SECTION 32 - UNIX上のVim +|faq-32.1| xtermでVimを実行しています。CTRL-Sを押すとVimがフリーズします。 + どうすればいいですか？ +|faq-32.2| 画面の更新について奇妙な問題があります。これを解決するには？ +|faq-32.3| Vimのターミナル/コンソール版を使っています。挿入モードでバックス + ペースキーを押してもカーソルの前の文字が消えません。どう設定すれば + 良いですか？ +|faq-32.4| xtermでVimを使っています。Vimを終了すると画面が元の状態に復元され + ます。これを無効化するには？ +|faq-32.5| Vimの起動にかなり時間がかかります。起動時間を最小化するには？ +|faq-32.6| Unixのgvimでカーソルの点滅を止めるには？ +|faq-32.7| GTK Vimのメニューのフォントを変えるには？ +|faq-32.8| Vimがでサスペンドするのを防ぐには？ +|faq-32.9| Vimを実行しているxtermをkillすると、Vimのプロセスが生き残り、多大 + なCPU時間(99%)を食ってしまいます。なぜこうなるのですか？ +|faq-32.10| Unixターミナルで構文強調を使うには？ + *faq-vim-on-ms-windows* +SECTION 33 - MS-Windows上のVim +|faq-33.1| MS-Windows上でCTRL-Vを押してもビジュアル矩形モードが始まりません。 + どうなっているのですか？ +|faq-33.2| CTRL-Yキーを押すとCTRL-Rのような動作をします。CTRL-YをCTRL-Yとして + 扱うように設定するには？ +|faq-33.3| 常にGVimのウィンドウを最大化して起動するには？ +|faq-33.4| なんらかの編集操作をするとVimがフリーズします。カーソルは空の四角 + 形になります。全然文字が入力できません。どうなっているのですか？ +|faq-33.5| Windows XPを使っています。最大化したGVimの表示速度がとても遅いで + す。表示の更新を早くするには？ +|faq-33.6| VimをCygwin上で使うにあたって推奨される設定は？ +|faq-33.7| 差分モードでGNU diffを使おうとしています。コマンドラインからdiffを + 使うとうまく動くのですが、Vim内で使おうとすると動きません。どうす + れば？ +|faq-33.8| Outlookで外部エディタにVimを使うことはできますか？ +|faq-33.9| HTMLファイルを編集するのにVimを使っています。現在開いているHTML + ファイルをインターネットエクスプローラーでプレビューするには？ +|faq-33.10| VimをMicrosoft Visual Studioといっしょに使いたいです。どうすれば？ +|faq-33.11| どこに_vimrcと_gvimrcを置けばいいですか？ +|faq-33.12| ファイルを保存する度に、そのファイルがVimの外部で変更されていると + 警告が出ます。なぜですか？ + *faq-printing* +SECTION 34 - 印刷 +|faq-34.1| 全ての行に行番号をつけて印刷するには？ +|faq-34.2| 構文強調の色をつけてファイルを印刷するには？ + *faq-building-vim-from-source* +SECTION 35 - Vimをソースからビルドする +|faq-35.1| Unixシステム上でVimをソースからビルドするには？ +|faq-35.2| Unixでホームディレクトリなど、デフォルトのディレクトリ以外にVimを + インストールするには？ +|faq-35.3| MS-Windowsシステム上でVimをソースからビルドするには？ +|faq-35.4| 私がインストールしたVimにはヘルプ、構文ファイル、インデントファイ + ルが欠けています。それらのファイルをインストールするには？ +|faq-35.5| Vimをソースからビルドして"make install"でインストールしました。Vim + のソースディレクトリを残しておく必要はありますか？ +|faq-35.6| ある機能がコンパイル時に有効化されているかどうかを知るには？ +|faq-35.7| GUI機能なしでVimをビルドすることはできますか？ +|faq-35.8| Unixシステム上でVimをビルドするとき、"undefined reference to + term_set_winsize"というエラーが出ます。これを解決するには？ +|faq-35.9| GTK 2.03を使おうとしているのですが、Vimのconfigureがgtk-configがな + いとのメッセージを出します。しかしGTK2は一般的なpkg-configを使うよ + うになったので、これは正しいのです。gtk用のインクルードファイルと + ライブラリのリストを出力するpkg-configならありますが、なぜか + configureスクリプトはこれを使ってくれません。 + *faq-various* +SECTION 36 - 様々な事柄 +|faq-36.1| Vimでバイナリフィルを編集するには？ +|faq-36.2| ビジュアルエラーフラッシュとエラービープを無効にするには？ +|faq-36.3| バッファに表示されている文字のASCIIコードを表示するには？ +|faq-36.4| コマンドのカウントとして0を使うことはできますか？ +|faq-36.5| Vimの起動時の画面を表示させなくするには？ +|faq-36.6| "hit enter to continue"プロンプトを避けるには？ +|faq-36.7| コマンドラインからVimを起動して一連のファイルに対して一連のコマン + ドを実行するには？ +|faq-36.8| 挿入モードから抜けることなくノーマルモードコマンドを実行するには？ + *faq-unicode* +SECTION 37 - Unicode +|faq-37.1| VimでUnicodeのファイルを作ることはできますか？ +|faq-37.2| Unicodeのファイルを編集するにあたって特に重要な設定は？ +|faq-37.3| オプション'encoding'とは何ですか？ +|faq-37.4| Vimでは様々なUnicodeエンコーディングをどう表記しますか？ +|faq-37.5| バイト順マークの有無を指定するには？ +|faq-37.6| オプション'fileencoding'とは何ですか？ +|faq-37.7| オプション'fileencodings'とは何ですか？ +|faq-37.8| オプション'termencoding'とは何ですか？ +|faq-37.9| オプション'bomb'とは何ですか？ +|faq-37.10| これらのオプションの典型的な例はどこにありますか？ +|faq-37.11| Unicodeの文字を挿入するには？ +|faq-37.12| どのダイグラフがどの文字に定義されているかを知るには？ + +============================================================================= + *faq-1* +SECTION 1 - 一般的な情報 + + *faq-1.1* +1.1. Vimとは何ですか？ + +Vim とは Vi IMproved を表します。かつては Vi IMitation の略でしたが、あまりに +多くの改良があったため名前の変更は適切なものでした。Vim は、Unix プログラムの +"Vi" のほとんど全てのコマンドや、多くの新しいコマンドを含んだテキストエディタ +です。全てのコマンドはキーボードで与えることができます。これには、指はキーボー +ドに置いたまま、目はスクリーンに向けておけるという利点があります。望む人には、 +マウスサポートや、スクロールバーとメニューのついた GUI 版もあります。 + +Vim はエディタであって、ワードプロセッサではありません。ワードプロセッサは主に +テキストのレイアウトを行うのに使われます。つまり、位置決めや、表示時の見え方を +変えたり、ということです。たいてい最終的なドキュメントは他の人に満足いくように +見せるため、印刷したり活字に組んだりなどするよう意図されます。ワードプロセッサ +の例は、Microsoft Word、WordPerfect、FrameMaker、AmiPro です。 + +エディタは単純にテキストを入力するためのものです。ドキュメントの植字やレイアウ +トは二次的なものです。エディタにおいて、主な関心事はテキスト入力であり、テキス +トを良く見せることではありません。Vim や Vi 以外のエディタの例は、Emacs、 +Crisp、Brief、xedit です。そして Notepad も。 + +さらなる情報については以下を参照してください。 > + + :help intro +< + *faq-1.2* +1.2. 誰が Vim を書いたんですか？ + +Vim のほとんどは Bram Moolenaar によって書かれましたが、他に貢献した人々の名前 +はここでは多すぎて触れられません。完全なリストは ":h credits" を見てください。 + +Vim は、Tim Thompson、Tony Andrews、G.R. (Fred) Walter らによって開発された +Stevie に基づいています。 + +さらなる情報については以下を参照してください。 > + + :help author +< + *faq-1.3* +1.3. Vim は Vi と互換性がありますか？ + +非常に。コマンドラインフラグ"-C"を使えばVimをVi互換モードで起動することが +できます: > + + $ vim -C +< +また、 > + + $ vim -u NONE +< +ともできます。'compatible'オプションをセットすればViとの互換を有効化できます: > + + :set compatible +< +さらなる情報については以下を参照してください。 > + + :help -C + :help 'compatible' + :help compatible-default +< + *faq-1.4* +1.4. Vim が Vi よりも向上している点は何ですか？ + +ここにあるのは短い要約です。以下のリストは Vim が徹底して現代的で、機能がぎゅっ +と詰め込まれたエディタであることを示すものです。今日のエディタの標準的な機能は +実装されており、一般的なパワーユーザーやプログラマ向けの機能にも重点が置かれて +います。 + +Vi を現代化する機能: + + 多段階アンドゥ + ファイルバッファにおける変更を元に戻す回数を設定することができます。アン + ドゥされた変更をリドゥすることもできます。 + 複数ウィンドウとバッファ + それぞれのファイルはそれ自身のウィンドウに表示することができます。一つの + ウィンドウから別のウィンドウへ簡単に移動することができます。それぞれの開 + かれたファイルは Vim のセッション中関連付けられたバッファを保有し、バッ + ファ間を簡単に移動することができます。 + 柔軟な挿入モード + Vim では挿入モードにある間矢印キーでファイル内を移動することができます。 + を押し、移動して、`i' や `a' を押す、といったことはしなくて済みま + す。 + マクロ + Vim には、連続してタイプされた文字を記録し、後で何度でも繰り返すことので + きる機能があります。 + ビジュアルモード + テキストの一部分をハイライトさせ、その部分にだけ操作を実行することができ + ます。 + ブロック・オペレーター + テキストを長方形のブロック状に選択、ハイライトさせ、その部分に対し特定の + 操作を行うことができます。 + オンラインヘルプシステム + どんな Vim 使用の局面であれ、容易に答えを探すことができます。ヘルプはそれ + 自身のウィンドウに表示されます。 + コマンドライン編集と履歴 + 履歴を利用すると、矢印キーで既にタイプされたコマンドを繰り返したり探した + りできます。コマンドの先頭を、履歴バッファにある別の似たコマンドの先頭に + マッチさせることができます。コマンドを編集してタイプミスを訂正したり、い + くつか値を変更することも出来ます。 + コマンドライン補完 + キーを使うと、コマンドやオプション、ファイル名などを必要に応じて補 + うことができます。 + 水平スクロール + 長い行は水平にスクロールできます(GUI の有る、無しにかかわらず)。 + +先進的なユーザー機能: + + テキスト整形 + 2 キーストロークで、外部プログラムを使わずに長いテキストを整形できます。 + 挿入モードでの単語補完 + Vim は、現在の単語とファイル内の似た単語とをマッチすることにより、タイピ + ング中に単語補完を行うことができます。 + タグ・ジャンプ + ウェブ・ブラウザーと同じように、以前編集していた箇所に戻ったり、また元に + 復帰することができます。なので、あなたの頭脳は自由にナビゲート、ではなく + 編集をすることができます。 + 自動コマンド + ファイルを読み書きする時や、他のバッファに移動する時などに自動的に実行さ + れるコマンドです。 + Viminfo + 起動時に読み込まれるコマンドライン履歴やファイル内のマーク、レジスタを記 + 憶しておくことができます。したがって、以前の検索パターンや、マクロなどを、 + 新しい Vim セッションで呼び出すことができます。 + マウスサポート + マウスは xterm や MS-DOS でサポートされています。カーソル位置を設定した + り、ビジュアル領域を選択したり、レジスタを貼り付けたり、等のことができま + す。 + グラフィカルユーザーインターフェイス(GUI) + 他の昨今のエディタと同様です。その上、独自のメニューを追加することも非常 + に簡単です。もちろん、コンソール版の Vim も今なおサポートされており、幅広 + く利用されています。 + スクリプト言語 + Vim は強力なスクリプト言語を備えており、新しいコマンドを作ることができま + す。また、同じことをするのに Perl、Python、TCL、それに Ruby を使うことも + できます。 + プラグイン + Vim コマンドによって実装された拡張機能で、起動時に自動的にロードされます。 + 例: ファイルエクスプローラー、ネットワーク編集。更に多くのものが + VimOnline にて常に開発、共有されています。 + 多数のプログラミング言語に対応した構文強調 + 数百ものプログラミング言語に対応した構文強調があります。他の言語への対応 + を追加することができます。 + 拡張正規表現 + 機能性がPerlの正規表現に似ている拡張正規表現をサポートしています。 + +プログラミング効率に関する機能: + + 編集―コンパイル―編集のスピードアップ + Vim 内部からコンパイルを行い、自動的にソースコードのエラーの箇所にジャン + プすることができます。 + 多数のプログラミング言語の字下げ + C、C++、Java、Perl、XML その他多くの言語で、タイプ中に自動的に字下げが行 + われます。他の言語へのサポートも追加可能です。 + インクルードファイル内の単語を検索 + カーソルの下の単語とのマッチを、現在のファイルとインクルードされるファイ + ル内で検索することができます。 + 先進的なテキストオブジェクト + ( と ) や、{ と } や、< と > 、また [ と ] の間の全てのテキストに対して、 + また単語、文、段落に対して、一瞬で選択したり、削除やコピーをしたり、字下 + げ、整形、大文字小文字の変換、等々を行うことができます。非常に強力です。 + フォールディング + テキストのある部分を「フォールド」(折り畳み)してしまうことができます。 + 最も良い例は関数の中身の部分です。コードの概観を見渡して、それから詳細を + 見たい関数のフォールドを開くことができます。 + ctags と cscope との統合 + これらの強力なプログラムを使うと、関数の呼び出し部分からその定義部分へジ + ャンプしたり、他の技術を使ってソースコードを行き来することができます。 + +さらなる情報については以下を参照してください。 > + + :help vi-differences +< + *faq-1.5* +1.5. Vim は無料ですか？ + +Vim はチャリティーウェアです。Vim の使用や複製に関しては何ら制限はありませんが、 +著者は慈善事業に寄付をするよう奨励しています。その方法を説明するドキュメントが +ディストリビューションの中に含まれています。 +さらなる情報については以下を参照してください。 > + + :help copyright +< + +============================================================================= + *faq-2* +SECTION 2 - 情報源 + + *faq-2.1* +2.1. どこに行けば Vim についてもっと学べるでしょうか？ + +Vimの質問は vim@vim.org メーリングリストに投稿できます。Vimの開発に関する質問 +は vim-dev@vim.org メーリングリストに投稿できます。Vim にはそれ自身のための +ニュースグループがありません。しかし comp.editors は投稿するのに適しています。 + +"VimOnline" は vim のデファクト・ホームページの役割を果たしているウェブ・ペー +ジですが、その主な目的はチップやスクリプトをいたる所から集積することにありま +す。ぜひ参加してください。URL は vim.sourceforge.net または vim.sf.net です。 + +最後に、Vi FAQ を読んでください: > + + http://www.faqs.org/faqs/editor-faq/vi/part1/index.html +< +この FAQ の第 5 節に、こちらの FAQ についてのより詳しい情報があります。 > + + :help mail-list + :help internet +< + *faq-2.2* +2.2. メーリングリストはありますか？ + +いくつか存在します: > + + 名前 説明 +< + vim-announce 新しいリリースの発表 + vim 一般的な議論 + vim-dev パッチ、バグ報告、開発議論 + vim-mac マッキントッシュに関する議論 + vim-fr フランス語による一般的な議論 + vim-multibyte マルチバイト関連の開発の問題 + vim-vms VMS上での開発について + +これらのうち、vim と vim-dev だけが一般的な興味を引くものです。vim-announce は +ほとんどの人にとってはリードオンリーですし、そのメッセージは他のリストにも送信 +されます。他の 4 つは非常に通信量が少ないです。 + +購読するには: <名前>-subscribe@vim.org にメールを送ってください。 +購読を中止するには: <名前>-unsubscribe@vim.org にメールを送ってください。 +ヘルプを得るには: <名前>-help@vim.org にメールを送ってください。 + + *faq-2.3* +2.3. メーリングリストのアーカイブはありますか？ + +あります。http://www.yahoogroups.com/list/<名前> を訪ねてみてください。<名前> +の所には次の + vimannounce, vim, vimdev, vim-fr, vim-mac, vim-multibyte, vim-vms +のどれかが入ります。 + +もしくは、www.gmane.org に行って GMANE について調べてみてください。これはメー +リングリストに、あたかもニュースグループのような感覚でアクセスすることができる +ものです。履歴をざっと眺めたり、現在のスレッドを気軽に見ることができて便利です。 + + *faq-2.4* +2.4. HTML/PDF/PS形式のVimユーザーマニュアルはどこで手に入りますか？ + +HTML/PDF/PS形式のVimユーザーマニュアルは以下からダウンロードできます。 > + + http://vimdoc.sourceforge.net/ +< + *faq-2.5* +2.5. ある問題が発生しました。それが私の設定によるものか、Vimそのものの + 問題かはどうすればわかりますか？ + +まず、その問題があなたの.vimrcや.gvimrc、システムのvimrc、あなたのプラグイン +ファイル、その他あなたの設定ファイルによるものかを調べなければなりません。その +ために > + + $ vim -N -u NONE -U NONE +< +としてください。これはVimを'nocompatible'モードで起動し、あなたの個人的な +.vimrcや.gvimrcファイルを読み込みません。あなたの個人的なプラグインも読み込み +ません。これでVimを起動し、問題の再現を試みてください。もしこれで問題が再現で +きなければ、その問題はあなたの設定ファイルやプラグイン中の設定に関係していま +す。設定ファイル中の問題の場所をつきとめるには、試行錯誤と設定ファイル中の1行 +１行をコメントアウトしてみなければなりません。Vimにコマンドライン引数-Vをつけ +て起動するとデバッグ情報が得られ、問題を分析することができます: > + + $ vim -V2 +< +-V引数に渡す値を増やせば、さらに詳しいデバッグ情報が得られます。 + +さらなる情報については以下を参照してください。 > + + :help -u + :help -U + :help -N + :help -V + :help 'verbose' + :help :verbose + :help set-verbose +< + *faq-2.6* +2.6. どこでバグ報告をすればいいですか？ + +最初に次のコマンドを使って必要な情報を集めてください: > + + :source $VIMRUNTIME/bugreport.vim +< +そして上のコマンドで得られたテキストをbugs@vim.orgメールアドレスに送ってくださ +い。 + +Vim 開発のメーリングリスト(上を見てください)は通常のバグについて議論するのにふ +さわしい場所です。あなたの見つけたバグがシンタックスハイライティングやその他の +「付加的な機能」(つまり、直接 vim にプログラムされていないもの)に関するもので +あれば、その機能のメンテナに報告してみてください。 + +さらなる情報については以下を参照してください。 > + + :help bug-reports +< + *faq-2.7* +2.7. FAQ はどこで見つけられますか？ + +VimOnline (vim.sf.net) で手に入ります。将来的には他の場所も加えられるでしょう。 + + *faq-2.8* +2.8. この FAQ に答えが見つからなかった時、どうすればいいですか？ + +この FAQ は主に Vim に特有の質問を扱います。ほとんどの Vi クローン向きの情報に +ついては Vi FAQ を読めば見つかるでしょう。これは comp.editors で定期的に投稿さ +れています。下記の場所にもそのコピーがあります。 > + + http://www.faqs.org/faqs/editor-faq/vi/part1/index.html +< +また、Vim は過去数年間で非常に多くの機能を集積してきたため、よくある質問をここ +で申し分なく記述することは不可能に近い作業です。これを可能にするために、もし良 +い質問をお持ちならメンテナにメールで知らせてください。良い質問とは、自分で答え +を出そうとして(Vim は素晴らしいドキュメントを備えていることを思い出してくださ +い)非常に苦労した質問のことです。 + + *faq-2.9* +2.9. Vimに機能を追加するパッチを持っています。これをどこへ送ればいいですか？ + +Vim開発者メーリングリストvim-dev@vim.orgにパッチを送ってください。 + +さらなる情報については以下を参照してください。 > + + :help vim-dev +< + *faq-2.10* +2.10. Vimのtipを持っていたり新しいsyntax/indent/filetype/compilerプラグインを + 開発したり、新しいスクリプトやカラースキームを開発しました。これをアップ + ロードできる公開のウェブサイトはありますか？ + +あります。Vim Onlineウェブサイトにプラグイン・スクリプト、カラースキーム、 +ティップスなどをアップロードすることができます。そのサイトは +http://vim.sourceforge.netにあります。 + +============================================================================= + *faq-3* +SECTION 3 - 入手 + + *faq-3.1* +3.1. Vim の最新のバージョンは何ですか？ + +Vim の最新バージョンは2004年6月8日にリリースされた 6.3 です。 + +Vimのリリース履歴は以下の通りです: + +Version 6.3 8th June 2004 +Version 6.2 1st June 2003 +Version 6.1 24th March 2002 +Version 6.0 27th September, 2001 +Version 5.8 31st May, 2001 +Version 5.7 24th June, 2000 +Version 5.6 16th January, 2000 +Version 5.5 21st September, 1999 +Version 5.4 26th July, 1999 +Version 5.3 31st August, 1998 +Version 5.2 24th August, 1998 +Version 5.1 7th April, 1998 +Version 5.0 19th February, 1998 +Version 4.6 13th March,1997 +Version 4.5 17th October, 1996 +Version 4.2 5th July,1996 +Version 4.0 21st May, 1996 +Version 3.0 16th August, 1994 +Version 2.0 21st December, 1993 +Version 1.27 23rd April, 1993 +Version 1.17 21st April, 1992 + + *faq-3.2* +3.2. どこで Vim の最新版を見つけられますか？ + +VimOnlineからVimの最新バージョンのソースがダウンロードできます。URLは +http://vim.sourceforge.net/download.php +です。 + + *faq-3.3* +3.3. どのプラットフォーム上で実行できるんですか？ + +全ての Unix プラットフォーム。 +全ての Windows プラットフォーム。 +Amiga、Atari、BeOS、DOS、Macintosh、MachTen、OS/2、RiscOS、VMS です。 + + *faq-3.4* +3.4. どこでVimのランタイムファイルの最新バージョンをダウンロードできますか？ + +Vimランタイムファイル(構文ファイル、ファイル形式別プラグイン、コンパイラプラ +グイン、カラースキーム、ドキュメント、インデントファイル、キーマップ)はVim +ftpサイトのftp://ftp.vim.org/pub/vim/runtimeディレクトリでダウンロードできま +す。 + +============================================================================= + *faq-4* +SECTION 4 - ヘルプ + + *faq-4.1* +4.1. どうやってヘルプファイルを利用するんですか？ + +Vim の全ての機能にヘルプがあります。それを利用するには、":h" を使ってください。 +そうするとメインのヘルプページを見ることができます。この最初のページで、どう +やって動き回るかの説明があると思います。基本的にはリードオンリーのドキュメント +内を動き回るのと同じ仕方でヘルプ内を移動します。特定のテーマへジャンプするには +タグを使うことができます。これは二通りの方法で行えます: + + * コマンドやオプションの上で "" コマンドを使う。これはタグがキー + ワードである場合にのみ有効です。"" や "g" も + "" と同じように機能します。 + * ":ta subject" コマンドを使う。これはどんな文字であっても利用できます。 + +以前のヘルプファイルの場所へ戻るには "" を使ってください。ヘルプを閉じ +るには ":q" を使ってください。 + +ヘルプページのある特定のテーマへジャンプしたければ ":h {subject}" を使ってくだ +さい。何を探せば良いか分からなければ、 ":h index" で全ての利用可能なテーマの一 +覧を得ることができます。標準の検索語を使って欲しい情報を見つけてください。 +":help"コマンドは":h"と短縮することができます。 + +さらなる情報については以下を参照してください。 > + + :help online-help +< + *faq-4.2* +4.2. どうやってVimヘルプファイル中のキーワードを探すんですか？ + +ヘルプキーワードをタイプした後にCTRL-Dを押すとそのパターンを含む全てのヘルプ +キーワードのリストが得られます。*, \+などのメタ文字を使ってヘルプの検索パター +ンを指定することもできます: > + + :help init + :help str*() + :help '*indent +< +ヘルプキーワードの一部をタイプした後にTabキーを押すと、マッチするキーワードに +展開することができます。Tabキーを押しつづけると他のマッチするキーワードに変わっ +ていきます。 + +ヘルプウィンドウでは":tag"コマンドを使ってキーワードを検索することができます。 +例えば、 > + + :tselect /window +< +このコマンドはテキスト"window"を含むヘルプキーワード全てをリスト表示します。そ +のリストの中から1つを選んでそこへジャンプすることができます。 + +":helpgrep"コマンドを使って全てのヘルプファイル中から与えられたテキストを検索 +することができます。QuickFixウィンドウが開き、全てのマッチする行が表示されま +す。 + +さらなる情報については以下を参照してください。 > + + :help c_CTRL-D + :help c_ + :help :tselect + :help :help + :help :helpgrep +< + *faq-4.3* +4.3. エラーメッセージE123が出ました。なにがまずいのでしょうか？ + +以下を行うと、エラーとエラーメッセージについてより詳しい情報が得られます: > + + :help E123 +< +さらなる情報については以下を参照してください。 > + + :help error-messages +< + *faq-4.4* +4.4. Vimの様々なモードについては何を読めばいいですか？ + +Vimにおけるモードの違いについては、以下を読めば情報を得られます。 > + + :help vim-modes +< + *faq-4.5* +4.5. 新しいVimヘルプファイルを追加した後、どうすればVimのヘルプタグファイルを + 生成することができますか？ + +":helptags"コマンドを使えばVimのヘルプタグファイルを再生成することができます。 +例えば: > + + :cd $VIMRUNTIME/doc + :helptags . +< +さらなる情報については以下を参照してください。 > + + :help :helptags + :help add-local-help +< + *faq-4.6* +4.6. 圧縮したヘルプファイルを使うことはできますか？ + +できます。ヘルプファイルを圧縮し、それをVimで表示することもできます。これを行 +うとヘルプファイルにアクセスするのが少し遅くなり、"gzip"ユーティリティが必要に +なります。圧縮したVimヘルプファイルを使うには、以下のステップを行ってください。 + + +- "gzip doc/*.txt"として全てのヘルプファイルを圧縮する。 + +- "doc/tags"ファイルを編集し、以下のコマンドを実行して".txt"を".txt.gz"に変更 + する。 + :%s=\(\t.*\.txt\)\t=\1.gz\t= + +- 次の行をあなたのvimrcに追加する: + set helpfile={dirname}/help.txt.gz + +{dirname}はヘルプファイルがあるディレクトリです。標準Vimディストリビューション +に同梱のgzip.vimプラグインがファイルの展開をしてくれます。他のVimファイルが圧 +縮された"doc"ディレクトリと別な場所にある場合は、$VIMRUNTIMEが他のVimファイル +のある場所に設定されていなければなりません。 + +さらなる情報については以下を参照してください。 > + + :help gzip-helpfile + :help 'helpfile' + :help gzip + :help $VIMRUNTIME +< + +============================================================================= + *faq-5* +SECTION 5 - ファイルの編集 + + *faq-5.1* +5.1. ファイルを編集用に読み込むには？ + +ファイルを編集用に読み込むにはいくつかの方法があります。もっとも単純な方法は +":e" (:edit)コマンドを使うことです: > + + :e +< +":n" (:next)コマンドを使ってファイルをVimに読み込ませることもできます: > + + :n +< +":args"コマンドを使ってファイルをVimに読み込ませることもできます: > + + :args +< +さらなる情報については以下を参照してください。 > + + :help usr_07 + :help edit-files + :help :edit + :help :next_f + :help :args_f +< + *faq-5.2* +5.2. 現在のファイルを別な名前で保存(save as)して新しいファイルを編集するには？ + +":saveas"コマンドを使えば現在のファイルを別な名前で保存することができます: > + + :saveas +< +別な方法としては、以下のコマンドを使うこともできます: > + + :w + :edit # +< +":file"コマンドと":w"コマンドを使うこともできます: > + + :file + :w +< +さらなる情報については以下を参照してください。 > + + :help 07.7 + :help :saveas + :help :file_f + :help :w +< + *faq-5.3* +5.3. カレントディレクトリを現在のファイルのディレクトリにするには？ + +次のコマンドでカレントディレクトリを現在のファイルのディレクトリにできます: > + + :cd %:p:h +< +自動的にカレントディレクトリを現在のファイルのディレクトリにするには、次の +autocmdを使います: > + + :autocmd BufEnter * cd %:p:h +< +さらなる情報については以下を参照してください。 > + + :help :cd + :help :lcd + :help filename-modifiers + :help autocommand +< + *faq-5.4* +5.4. ファイルの末尾に改行文字(EOL)をつけずにファイルを書き込むには？ + +'eol'オプションをオフにして'binary'オプションをオンにすればファイルの末尾に +EOLをつけずにファイルを書き込むことができます: > + + :set binary + :set noeol + :w +< +さらなる情報については以下を参照してください。 > + + :help 'endofline' + :help 'binary' + :help 23.4 +< + *faq-5.5* +5.5. ファイルを最後に編集した場所から開くようにするには？ + +Vimは各バッファに対して最後に編集した場所のカーソル位置を'"'レジスタに保存しま +す。次のautocmdを.vimrcまたは.gvimrcに書けば、ファイルを最後に編集した場所から +開くようにできます: > + + au BufReadPost * if line("'\"") > 0 && line("'\"") <= line("$") | + \ exe "normal g'\"" | endif +< +さらなる情報については以下を参照してください。 > + + :help '" + :help last-position-jump +< + *faq-5.6* +5.6. Vimでファイルを編集中にそのファイルが他のアプリケーションによって変更され + たとき、Vimは変更が検出されるたびに警告ウィンドウ(確認ダイアログのような) + を開きます。この警告を無効にするには？ + +'autoread'オプションをセットすると、Vimの外部でファイルが変更されたとき、自動 +的に読み直すようにできます: > + + :set autoread +< +次のautocommandを使うこともできます: > + + autocmd FileChangedShell * + \ echohl WarningMsg | + \ echo "File has been changed outside of vim." | + \ echohl None +< +さらなる情報については以下を参照してください。 > + + :help 'autoread' + :help FileChangedShell + :help timestamp + :help :checktime +< + *faq-5.7* +5.7. カーソル下のファイル名のファイルを開くには？ + +gfコマンドでカーソル下のファイル名のファイルを開くことができます。CTRL-W fコマ +ンドでそのファイルを新しいウィンドウで開くことができます。 + +さらなる情報については以下を参照してください。 > + + :help gf + :help CTRL-W_f + :help 'isfname' + :help 'path' + :help 'suffixesadd' + :help 'includeexpr' +< + *faq-5.8* +5.8. 現在のファイルを再読み込みするには？ + +ファイル名を指定せずに":edit"コマンドを行えば、現在のファイルを再読み込みする +ことができます。ファイルに変更をしてある場合は、":edit!"とすれば強制的に現在の +ファイルを再読み込みすることができます(変更は失われます)。 + +さらなる情報については以下を参照してください。 > + + :help :edit + :help :edit! + :help 'confirm' +< + *faq-5.9* +5.9. ファイルを定期的に自動保存するには？ + +Vimにはファイルを定期的に自動保存する機能はありません。 + +さらなる情報については以下を参照してください。 > + + :help 'updatetime' + :help CursorHold + :help swap-file +< + *faq-5.10* +5.10 ファイルを読み取り専用モードで開くには？ + +ファイルを読み取り専用モードで開くには":view"コマンドを使います: > + + :view +< +このコマンドは開いたバッファに'readonly'オプションをセットします。また、コマン +ドラインオプション"-R"をつければファイルを読み取り専用モードで開くことができま +す: > + + $ vim -R +< +また、コマンドラインからシンボリックリンク実行ファイル"view"を使ってもファイル +を読み取り専用モードで開くことができます: > + + $ view +< +さらなる情報については以下を参照してください。 > + + :help 07.6 + :help 'readonly' + :help 'modifiable' + :help :view + :help :sview + :help view + :help -R + :help -M +< + +============================================================================= + *faq-6* +SECTION 6 - 複数のファイルを編集する + + *faq-6.1* +6.1. Vim内で同時に複数のファイルを開くには？ + +Vim内で同時に複数のファイルを開くにはいくつかの方法があります。":next"コマンド +を使うとファイルのグループを指定することができます: > + + :next f1.txt f2.txt + :next *.c +< +:argsコマンドを使うとファイルのグループを引数に指定することができます: > + + :args f1.txt f2.txt + :args *.c +< +ファイルを読み込んだら、":next"と":prev"コマンドでファイルを切り替えることがで +きます。 + +さらなる情報については以下を参照してください。 > + + :help 07.2 + :help :next + :help :args_f + :help argument-list +< + *faq-6.2* +6.2. 複数のファイル・バッファを切り替えるには？ + +複数のファイルを切り替えるにはいくつかの方法があります。":buffer"コマンドを使 +うと複数のファイルを切り替えることができます。例えば、 > + + :buffer file1 + :buffer file2 +< +CTRL-^を使ってバッファを切り替えることもできます。キーの前にカウントを指定する +とその番号のバッファを編集することができます。カウントを指定しないでCTRL-^を押 +すと代替バッファを編集します。 + +":e #"コマンドでも特定のバッファを編集することができます: > + + :e #5 +< +さらなる情報については以下を参照してください。 > + + :help edit-files + :help :buffer + :help CTRL-^ + :help alternate-file + :help 22.4 + :help 07.3 +< + *faq-6.3* +6.3. それぞれのファイルを別ウィンドウで開くには？ + +コマンドライン引数-oと-Oを指定すると複数のファイルを水平または垂直に分割した +ウィンドウで開くことができます。例えば: > + + $ vim -o3 f1.txt f2.txt f3.txt +< +上のコマンドはファイルf1.txt、f2.txt、f3.txtを3つに水平に分割したウィンドウで +開きます。 > + + $ vim -O3 f1.txt f2.txt f3.txt +< +上のコマンドはファイルf1.txt、f2.txt、f3.txtを3つに垂直に分割したウィンドウで +開きます。 > + +さらなる情報については以下を参照してください。 > + + :help -o + :help -O + :help startup-options +< + *faq-6.4* +6.4. 「ワークセット」や「プロジェクト」のように自動的に複数のファイルを同時に + 読み込ませるようにするには？ + +自動的に複数のファイルを読み込ませるようにするには":mksesion"と":mkview"を使い +ます。 + +":mksession"コマンドは現在編集中のセッションを復元するVimスクリプトを生成しま +す。このmksessionコマンドで作られたファイルは":source"コマンドで読み込むことが +できます。 + +":mkview"コマンドは現在のウィンドウの中身を復元するVimスクリプトを生成します。 +現在のファイルのviewを読み込むには":loadview"コマンドを使います。 + +さらなる情報については以下を参照してください。 > + + :help 21.4 + :help 21.5 + :help views-sessions + :help 'sessionoptions' + :help :mksession + :help :source + :help v:this_session + :help :mkview + :help :loadview + :help 'viewdir' + :help buffers +< + *faq-6.5* +6.5. Neditやemacsのように単一のVimインスタンスで複数のトップレベルウィンドウを + 開くことはできますか？ + +できません。単一のVimインスタンスで複数のトップレベルウィンドウを開くことは現 +在は不可能です。この機能はtodoリストの中にあります。 + + *faq-6.6* +6.6. Vim内でディレクトリをブラウズするには？ + +標準Vimディストリビューションに同梱のexplorer.vimプラグインを使えばVim内でディ +レクトリをブラウズすることができます。以下のコマンドのうちどれかでファイルエク +スプローラーを起動することができます: > + + :e + :Explore + :SExplore +< +ファイルエクスプローラーではディレクトリをブラウズし、ファイルをリネーム、 +削除、編集することができます。 + +さらなる情報については以下を参照してください。 > + + :help file-explorer + :help 22.1 +< + *faq-6.7* +6.7. ftp/scp/rcp/httpでネットワークごしにファイルを編集するには？ + +標準Vimディストリビューションに同梱のnetrw.vimを使えばftp/scp/rcp/httpでネット +ワークごしにファイルを編集することができます。このプラグインを使うと、Vimは +ftp/scp/rcp/httpごしのファイルを透過的に読み込み、保存します。例えば、ftpごし +にファイルを編集するには、以下のコマンドを使います: > + + $ vim ftp://machine/path +< +さらなる情報については以下を参照してください。 > + + :help netrw.vim +< + +============================================================================= + *faq-7* +SECTION 7 - バックアップ + + *faq-7.1* +7.1. ファイルを保存したとき元のファイル名の末尾に"~"という文字をつけたファイル + が作られます。このファイルを作成するのを止めさせるには？(または)バック + アップ機能を無効にするには？ + +あなたは'backup'オプションをセットしているので、Vimは元のファイルを保存すると +きにバックアップを作ります。このバックアップファイルを作るのを止めさせるには、 +このオプションをクリアします: > + + :set nobackup +< +Note デフォルトではこのオプションはオフにされています。初期設定ファイルのどこ +かで明示的に'backup'オプションが有効化されています。'writebackup'オプションも +オフにするとよいかもしれません: > + + :set nowritebackup +< +さらなる情報については以下を参照してください。 > + + :help 07.4 + :help backup-table + :help 'backup' + :help 'writebackup' + :help 'backupskip' + :help 'backupdir' + :help 'backupext' + :help 'backupcopy' + :help backup +< + *faq-7.2* +7.2. 全てのバックアップファイルを特定のディレクトリに保存するように設定するに + は？ +'backupdir'オプションを使えば全てのバックアップファイルを特定のディレクトリに +保存するように設定できます。例えば、全てのバックアップファイルを~/backupディレ +クトリに保存するには、次のコマンドを使います: > + + :set backupdir=~/backup +< +さらなる情報については以下を参照してください。 > + + :help 07.4 + :help 'backupdir' + :help backup +< + *faq-7.3* +7.3. ファイルを保存するとファイルパーミッションが変更されます。ファイルパー + ミッションを変更せずにファイルを保存するよう設定するには？ + +これは'backupcopy'が'no'または'auto'に設定されていると起こりえます。Note この +オプションのデフォルト値はほとんどの場合に正しく動作するように設定されていま +す。もしそのデフォルト値が正しく機能しないなら、'backupcopy'オプションを'yes' +にすればファイル保存時にパーミッションをそのままにすることができます: > + + :set backupcopy=yes +< +これはファイルを上書きするときは必ずバックアップを作るように設定したときだけ適 +用されます。デフォルトではVimはバックアップファイルを作りません。 + +さらなる情報については以下を参照してください。 > + + :help 'backupcopy' + :help backup + :help 'backup' + :help 'writebackup' +< + +============================================================================= + *faq-8* +SECTION 8 - バッファ + + *faq-8.1* +8.1. バッファに対して変更を加えました。変更されたバッファを保存せずに、かつ変 + 更を失うことなく他のバッファを編集するには？ + +'hidden'オプションをセットすれば現在のファイルに対する変更を失うことなく他の +ファイルを編集することができます: > + + :set hidden +< +'hidden'オプションをセットすると、バッファに対する変更履歴(アンドゥ履歴)も保 +存されます。そうでないと、ファイルを切り替えたときにアンドゥ履歴が失われてしま +うでしょう。 + +さらなる情報については以下を参照してください。 > + + :help 'hidden' + :help hidden-quit + :help :hide +< + *faq-8.2* +8.2. バッファを切り替えるときに自動的に保存するよう設定するには？ + +'autowrite'オプションをセットすると、他のバッファに切り替えるとき変更された +バッファを自動保存します: > + + :set autowrite +< +さらなる情報については以下を参照してください。 > + + :help 'autowrite' + :help 'autowriteall' + :help 'hidden' +< + *faq-8.3* +8.3. カレントウィンドウのバッファを空バッファにするには？ + +":enew"コマンドを使うとカレントウィンドウのバッファに換わって空バッファを読み +込みます。 + +さらなる情報については以下を参照してください。 > + + :help :enew +< + *faq-8.4* +8.4. バッファ番号を指定してバッファを読み込むショートカットキーはありますか？ + +CTRL-^コマンドを使うとバッファ番号を指定してバッファを読み込むことができます。 +例えばバッファ番号5を読み込むには5 CTRL-^とします。 + +さらなる情報については以下を参照してください。 > + + :help CTRL-^ +< + *faq-8.5* +8.5. 読み込んでいるバッファをそれぞれ別のウィンドウで開くには？ + +":ball"または":sball"コマンドでバッファリスト中の全てのバッファを開くことがで +きます: > + + :ball +< +さらなる情報については以下を参照してください。 > + + :help :ball +< + *faq-8.6* +8.6. Vimを終了することなくバッファを閉じる(削除する)には？ + +":bdelete"コマンドでVimを終了することなくバッファを削除できます。 +例: > + + :bdelete file1 +< +さらなる情報については以下を参照してください。 > + + :help :bdelete + :help :bwipeout +< + *faq-8.7* + +8.7. :e filenameでいくつかのファイルを開きました。Vimを終了することなくそのバッ + ファのうちの1つを閉じるには？ + +":bdelete "コマンドでバッファを閉じることができます。 + +さらなる情報については以下を参照してください。 > + + :help :bdelelete + :help :bunload + :help :bwipeout +< + *faq-8.8* +8.8. ":%bd"コマンドで全バッファを削除しようとしても、全てのバッファが削除され + ません。なぜ？ + +":%bd"コマンドにおいて範囲'%'はカレントバッファの開始行と終端行で置き換えられ +ます。範囲として'%'を使わず、番号を指定しなければなりません。例えば、 +":1,9999bd"とすれば全バッファを削除できます。 + +さらなる情報については以下を参照してください。 > + + :help :bd +< + *faq-8.9* +8.9. カレントバッファ/ファイルのバッファ番号を表示するには？ + +2コマンドでカレントバッファ/ファイルのバッファ番号を表示できます。 +CTRL-Gの前にカウントを指定することに注意してください。カウントが1より大きい場 +合、バッファ番号が表示されます。 + +カレントバッファを表示するのに以下のコマンドを使うこともできます: > + + :echo bufnr("%") +< +また、'statusline'オプションにフィールド"%n"を含めるとステータスラインにバッ +ファ番号が表示されます。 + +さらなる情報については以下を参照してください。 > + + :help CTRL-G + :help bufnr() + :help :echo + :help 'statusline' +< + *faq-8.10* +8.10. ウィンドウを閉じることなくバッファを削除するには？ + +次のコマンドで現在のバッファを削除し、次のバッファを開くことができます: > + + :bnext | bdelete # +< +さらなる情報については以下を参照してください。 > + + :help :bnext + :help :bdelete + :help :buffers +< + *faq-8.11* +8.11. Tabキーで全バッファを巡回するようにマップするには？ + +次の2つのマップコマンドを使うと、CTRL-Tabで次のバッファを開き、CTRL-SHIFT-Tab +で前のバッファを開くようにマップできます: > + + :nnoremap :bnext + :nnoremap :bprevious +< +さらなる情報については以下を参照してください。 > + + :help :bnext + :help :previous +< + +============================================================================= + *faq-9* +SECTION 9 - ウィンドウ + + *faq-9.1* +9.1. ウィンドウとバッファの違いは？ + +バッファとは編集用にメモリに読み込まれたファイルです。元のファイルはあなたが +バッファをファイルに書き込むまでは変更されないままです。ウィンドウとはバッファ +を表示する領域です。1つのバッファを複数のウィンドウで表示することもできます +し、異なるバッファを複数のウィンドウで表示することもできます。 + +さらなる情報については以下を参照してください。 > + + :help usr_08.txt + :help 22.4 + :help windows-intro + :help Q_wi +< + *faq-9.2* +9.2. ウィンドウの幅を広げるには？ + +以下のコマンドのどれか1つでウィンドウの幅を広げることができます: > + + :vert resize +N + :vert resize -N + :vert resize N +< +CTRL-W <、CTRL-W >、CTRL-W | コマンドを使うこともできます。 + +さらなる情報については以下を参照してください。 > + + :help vertical-resize + :help CTRL-W_> + :help CTRL-W_< + :help window-resize +< + *faq-9.3* +9.3. ウィンドウをズームイン・ズームアウトするには？ + +ウィンドウをズームするには(カレントウィンドウ以外の全ウィンドウを閉じるには) +"CTRL-W o" またはexコマンド ":only" を使います。 + +"CTRL-W _" またはexコマンド ":resize" を使うと、他のウィンドウを閉じずに可能な +限りウィンドウの高さを広げることができます。 + +"CTRL-W |" またはexコマンド ":vertical resize" を使うと、他のウィンドウを閉じ +ずに可能な限りウィンドウの幅を広げることができます。 + +"CTRL-W =" コマンドを使うと全ウィンドウの高さと幅を等しくすることができます。 + +以下のオプションをセットすると、上記のコマンドを行うのと同じ結果が得られます。 + +方法1: +'winminheight'オプションを0にする: > + + :set winminheight=0 +< +デフォルトではこのオプションは1に設定されています。 +このオプションはアクティブでない(カレントウィンドウでない)ウィンドウの最小の +高さをコントロールします。'winminheight'が0に設定されていると、アクティブでな +いウィンドウにはステータスラインだけが表示されます。 + +方法2: +'noequalalways'オプションをセットし、'winheight'オプションを大きな値(99999な +ど)に設定する: > + + :set noequalalways + :set winheight=99999 +< +こうするとアクティブウィンドウが常に最大サイズで開かれます。他のウィンドウは表 +示されますが、ステータスラインのように小さく縮みます。 + +以上の方法のどれにおいても、いったんウィンドウをズームしてしまうと、ウィンドウ +配置を復元することはできません。ウィンドウ配置を復元したいならばZoomWinプラグ +インを使うことができます。このプラグインはVim onlineからダウンロードできます。 + +http://vim.sourceforge.net/scripts/script.php?script_id=508 + +さらなる情報については以下を参照してください。 > + + :help CTRL-W_o + :help window-resize + :help 'winminheight' + :help 'equalalways' + :help 'winheight' + :help 08.3 +< + *faq-9.4* +9.4. 全バッファまたは全ウィンドウ、引数リスト中の全ファイルに対してexコマンド + を実行するには？ + +":bufdo"コマンドを使うと全バッファに対してexコマンドを実行することができます。 +":windo"コマンドを使うと全ウィンドウに対してexコマンドを実行することができま +す。":argdo"コマンドを使うと引数リスト中の全ファイルに対してexコマンドを実行す +ることができます。 + +さらなる情報については以下を参照してください。 > + + :help :windo + :help :bufdo + :help :argdo + :help 26.3 +< + +============================================================================= + *faq-10* +SECTION 10 - モーション + + *faq-10.1* +10.1. ファイルの先頭や末尾に移動するには？ + +'G'でファイルの最終行へ移動でき、'gg'で先頭行へ移動できます。 + +さらなる情報については以下を参照してください。 > + + :help G + :help gg +< + *faq-10.2* +10.2. 挿入モードでキーを押してノーマルモードに移行すると、カーソルが1文字 + 左へ移動します(カーソルが行の最初の文字の上にあるときを除いて)。この動作 + を変更し、カーソルがその桁の上に残るようにできますか？ + +この動作を変更することはできません。カーソルは「常に」有効な文字の上に置かれま +す(仮想編集モードを有効にしていない限り)。そのため、行の末尾にテキストを追加し +ていてノーマルモードに戻るときには、カーソルは必ず最後に入力された文字の上に戻 +らねばなりません。一貫性のためにカーソルはどこにあっても1文字戻るようになって +います。たとえ行の真ん中であっても。 + +挿入モードでCTRL-Oを使うと、カーソル位置を動かすことなくexコマンドを1つ実行し +て挿入モードに戻ることができます。 + +さらなる情報については以下を参照してください。 > + + :help 'virtual' + :help i_CTRL-O +< + *faq-10.3* +10.3. 、などのキーを押してスクロールしたときカーソル位置の + 桁を保つように設定することはできますか？ + +'startofline'オプションをオフにするとテキストをスクロールしたときカーソル位置 +の桁を保つことができます: > + + :set nostartofline +< +さらなる情報については以下を参照してください。 > + + :help 'startofline' +< + *faq-10.4* +10.4. ファイル中のある行の長さが画面の幅を越えており、折り返されています。ここ + でj, kキーを使うと画面上の次行(物理行)でなくファイルの次行(論理行)に + 移動します。画面上の次行に移動するには？ + +gjとgkコマンドを使うと画面上の次行・前行に移動できます。jとkはファイルの次行・ +前行に移動します。'wrap'オプションをオフにすると行の折り返しをやめさせることが +できます: > + + :set nowrap +< +さらなる情報については以下を参照してください。 > + + :help gj + :help gk + :help 'wrap' +< +以下のマッピングを使ってもよいでしょう: > + + :map gk + :imap gk + :map gj + :imap gj +< + *faq-10.5* +10.5. Vimにおける文、段落、セクションの定義は？ + +文(sentence)は後ろに行末・(1個または2個の)スペース・タブが続く'.'、'!'、'?' +で終わると定義されます。文の終端を構成する文字とスペースの個数は'joinspaces'と +'cpoptions'オプションによって決まります。 + +段落(paragraph)は空行の後から始まります。また、'paragraph'オプション中の文字の +ペアによって指定される段落マクロも段落の始まりとみなされます。 + +セクションは1桁目のフォームフィード()から始まります。また、'sections'オプ +ション中の文字のペアによって指定される段落マクロも段落の始まりとみなされます。 + +さらなる情報については以下を参照してください。 > + + :help sentence + :help 'joinspaces' + :help 'cpoptions' | /^\s*j\> + :help paragraph + :help section + :help word +< + *faq-10.6* +10.6. 文、段落、セクションの先頭と末尾に移動するには？ + +以下のコマンドを使うと文、段落、セクションの先頭と末尾に移動することができます +: > + + motion 位置 どこの + ( 先頭 現在の文 + ) 末尾 現在の文 + { 先頭 現在の段落 + } 末尾 現在の段落 + [] 末尾 前のセクション + [[ 先頭 現在のセクション + ][ 末尾 現在のセクション + ]] 先頭 次のセクション +< +これらの移動コマンドの前に番号を指定すると、移動を前方(または後方)に拡大する +ことができます。 + +さらなる情報については以下を参照してください。 > + + :help object-motions +< + *faq-10.7* +10.7. 画面の右端を越えて続いている行があります。右側にスクロールして画面外に出 + ているテキストを表示するには？ + +以下のコマンドのどれか1つで画面を左右にスクロールすることができます: > + + zl - 左へスクロール + zh - 右へスクロール + zL - 左へ画面半分の幅スクロール + zH - 右へ画面半分の幅スクロール + zs - カーソル位置が画面左端に来るようにスクロール + ze - カーソル位置が画面右端に来るようにスクロール +< +g0コマンドでカーソルを画面上最初の文字へ、g$コマンドで画面上最後の文字へ、画面 +をスクロールせずに移動することができます。 + +さらなる情報については以下を参照してください。 > + + :help scroll-horizontal +< + *faq-10.8* +10.8. 2個以上のバッファを同時にスクロールさせるには？ + +それぞれのバッファに対して"scrollbind"オプションをセットすると、それらを同時に +スクロールできるようになります。 + +さらなる情報については以下を参照してください。 > + + :help 'scrollbind' + :help scroll-binding + :help 'scrollopt' +< + *faq-10.9* +10.9. 矢印キーを使うとモードが変わり、バッファに変な文字が挿入され、カーソルが + 適切に移動しません。どうなっているのですか？ + +そうなるのには2つの事が考えられます。遅い回線上でVimを使っているか、キーボード +が生成するキーシーケンスをVimが理解していないかです。 + +もし遅い回線(2400bpsモデムのような)上で使用しているなら、'timeout'や +'ttimeout'オプションを設定してみてください。これらのオプションを'timeoutlen'と +'ttimeoutlen'オプションと組み合わせれば問題が解決するかもしれません。 + +もしあなたのターミナルが送るキーコードをVimが理解しなければ、そのコマンドは正 +しく動きません。この場合、最良の選択肢はそのキーシーケンスをカーソル移動コマ +ンドにマップして、そのマッピングをファイルに保存しておくことです。そしてその +ターミナル上で使うときは常にそのファイルを":source"します。 + +さらなる情報については以下を参照してください。 > + + :help 'timeout' + :help 'ttimeout' + :help 'timeoutlen' + :help 'ttimeoutlen' + :help :map + :help vt100-cursor-keys +< + *faq-10.10* +10.10. カーソルが行頭にあるとき左矢印キーを押すと前行の行末に移動するようにす + るには？ + +カーソルが行頭にあるとき左矢印キーを押すと前行の行末に移動するようにするには +'whichwrap'オプションに'<'フラグを加えます: > + + :set whichwrap+=< +< +同様に、カーソルが行末にあるとき右矢印キーを押すと次行の行頭に移動するようにす +るには'whichwrap'オプションに'>'フラグを加えます: > + + :set whichwrap+=> +< +これらはノーマルモードとビジュアルモードでのみ機能します。挿入モードと置換モー +ドでも使えるようにするには、それぞれ '[' と ']' フラグを加えます。 + +さらなる情報については以下を参照してください。 > + + :help 'whichwrap' + :help 05.7 +< + *faq-10.11* +10.11. 常に挿入モードに留まるようにするには？(モードレスな編集をするには？) + +常に挿入モードに留まるようにするには'insertmode'オプションを使います: +> + + :set insertmode +< +このオプションをセットするとVimをモードレスエディタとして使えるようになります。 +キーを押してもノーマルモードに移行しません。ノーマルモードコマンドを1つ +だけ実行するにはCTRL-Oを押してからノーマルモードコマンドをタイプします。1つ以 +上のノーマルモードコマンドを実行するにはCTRL-Lに続けてそのコマンドをタイプしま +す。挿入モードに戻るにはキーを押します。このオプションを無効にするには +'insertmode'オプションをオフにします: > + + :set noinsertmode +< +"evim"コマンドまたは"vim -y"を使ってもVimをモードレスエディタとして使用できま +す。 + +さらなる情報については以下を参照してください。 > + + :help 'insertmode' + :help i_CTRL-O + :help i_CTRL-L + :help evim + :help evim-keys +< + *faq-10.12* +10.12. テキストをスクロールするとき、前後の行を表示するには？ + +'scrolloff'オプションをセットすると画面に表示されるカーソルの前後の行の最小数 +を設定できます。 > + + :set scrolloff=10 +< +さらなる情報については以下を参照してください。 > + + :help 'scrolloff' + :help 'sidescrolloff' +< + *faq-10.13* +10.13. 以前のカーソル位置に戻るには？ + +''または``コマンドを使うと最後のジャンプの前にいた位置へカーソルを戻すことがで +きます。CTRL-Oでも以前のカーソル位置に戻ることができ、CTRL-Iでジャンプリスト中 +のより新しい位置へ移動できます。 + +さらなる情報については以下を参照してください。 > + + :help 03.10 + :help mark-motions + :help jump-motions +< + +============================================================================= + *faq-11* +SECTION 11 - テキストを検索する + + *faq-11.1* +11.1. テキストを検索した後、マッチしたテキストが全て強調されます。この強調を一 + 時的/永続的に無効にするには？ + +最後に検索したパターンにマッチする文字列を強調するかは'hlsearch'オプションで決 +まります。デフォルトではこのオプションは無効になっています。このオプションがシ +ステムレベルのvimrcファイルでセットされているならば、次のコマンドを使ってこの +強調を無効にできます: > + + :set nohlsearch +< +一時的にこの強調を消すには次のようにします: > + + :nohlsearch +< +また、カレントファイルに存在しないパターンを検索することによってもこの強調をク +リアすることができます(例えば'asdf'を検索する)。 + +さらなる情報については以下を参照してください。 > + + :help 'hlsearch' + :help :nohlsearch +< + *faq-11.2* +11.2. 検索パターンにキャリッジリターン文字を含めるには？ + +'\r'を使うかを使えばパターンにキャリッジリターンを含めることが +できます。Vimスクリプト中では'\r'を使う方がよいでしょう。 + +さらなる情報については以下を参照してください。 > + + :help sub-replace-special +< + *faq-11.3* +11.3. 文字^Mを検索するには？ + +検索コマンド中にCTRL-Vを押して次にCTRL-Mを押せば^M文字を挿入することができま +す。 +> + + /^V^M +< +"\r"文字を使うこともできます。Vimスクリプト中では"\r"を使う方がよいでしょう。 + +さらなる情報については以下を参照してください。 > + + :help c_CTRL-V + :help using_CTRL-V + :help /\r +< + *faq-11.4* +11.4. '~R', '~S'などと表示される文字を検索・置換するには？ + +'ga'で特殊文字のASCIIコードを表示することができます。例えばASCIIコードが142で +あるなら、次のコマンドでその特殊文字を検索することができます: > + + /^V142 +< +ここで^VはCTRL-Vを押して挿入します。 + +さらなる情報については以下を参照してください。 > + + :help ga + :help using_CTRL_V + :help 24.8 +< + *faq-11.5* +11.5. ファイル中の印字不能文字を全て強調するには？ + +次のコマンドと検索パターンを使えばファイル中の印字不能文字を全て強調することが +できます: > + + :set hlsearch + /\(\p\|$\)\@!. +< +さらなる情報については以下を参照してください。 > + + :help /\p + :help /bar + :help /$ + :help /\( + :help /\@! + :help 'hlsearch' +< + *faq-11.6* +11.6. 単語に完全に一致するテキストを検索するには？ + +アトム\<と\>を使えば単語に完全に一致するテキストを検索できます。例えば: > + + /\ +< +アトム\<は単語の先頭にマッチし、アトム\>は単語の末尾にマッチします。 + +さらなる情報については以下を参照してください。 > + + :help /\< + :help /\> +< + *faq-11.7* +11.7. カーソル下の単語を検索するには？ + +*キーを押せばカーソル下の単語を前方に検索することができます。後方に検索するに +は#キーを押します。これらのコマンドを使うとキーワードに完全に一致するものだけ +が検索されます。 + +さらなる情報については以下を参照してください。 > + + :help star + :help # + :help g* + :help g# + :help 03.8 + :help search-commands +< + *faq-11.8* +11.8. 大文字・小文字を区別せず検索するには？ + +常に大文字・小文字を区別しないようにするには'ignorecase'をセットします: > + + :set ignorecase +< +あるパターンを検索するときだけ区別しないようにするには、特別なディレクティブ +\cを使います: > + + /\c +< +さらなる情報については以下を参照してください。 > + + :help 'ignorecase' + :help /ignorecase + :help /\c +< + *faq-11.9* +11.9. 2回続けて現れる単語を検索するには？ + +次の検索コマンドのどれかを使えば、2回続けて現れる単語を探すことができます: > + + /\(\<\w\+\)\_s\+\1\> + /\(\<\k\+\)\_s\+\1\> +< +主な違いは'\w'と'\k'の使用です。後者は'iskeyword'に基づき、アクセントつきの文 +字や他の言語固有の文字を含むこともできます。 + +さらなる情報については以下を参照してください。 > + + :help /\1 + :help /\( + :help /\) + :help /\< + :help /\> + :help /\w + :help /\k + :help /\+ + :help /\_x + :help 'iskeyword' +< + *faq-11.10* +11.10. ある単語がバッファ中に何回現れるか数えるには？ + +以下の一連のコマンドを行うと、ある単語がバッファ中に何回現れるかを数えることが +できます: > + + :let cnt=0 + :g/\/let cnt=cnt+1 + :echo cnt +< +上のコマンドは単語を含む行の数を数えるだけです。以下のコマンドを使うこともでき +ます: > + + :%s/\/&/g +< +{訳注: :%s/\//ng というようにnフラグをつけると、実際には置換を行わず、 + 何箇所置換されるかを知ることができます。} + +ファイル中のアルファベットだけからなる単語を数えるにはこうします。 > + + :%s/\a\+/&/g +< +非空白文字だけからなる単語を数えるにはこうします。 > + + :%s/\S\+/&/g +< +さらなる情報については以下を参照してください。 > + + :help count-items + :help word-count + :help v_g_CTRL-G + :help 12.5 +< + *faq-11.11* +11.11. 検索時にカーソルをマッチした単語の末尾に移動させるには？ + +検索コマンドにオフセット'e'を指定すると、カーソルをマッチした単語の末尾へ移動 +させることができます。例 > + + /mypattern/e +< +さらなる情報については以下を参照してください。 > + + :help search-offset + :help / +< + *faq-11.12* +11.12. 空行を検索するには？ + +次のコマンドを使うと空行を検索することができます: > + + /^$ +< + または > + + /^\s*$ +< +さらなる情報については以下を参照してください。 > + + :help /^ + :help /$ + :help /\s + :help /* + :help search-commands +< + *faq-11.13* +11.13. 1つの文字だけを含む行を検索するには？ + +1つの文字だけを含む行を検索するにはこうします: > + + /^\s*\a\s*$ +< +さらなる情報については以下を参照してください。 > + + :help /^ + :help /\a + :help /\s + :help /* + :help /$ +< + *faq-11.14* +11.14. 複数のファイルから文字列を検索し、置換するには？ + +":argdo", ":bufdo", ":windo"コマンドを使うと複数のファイルに対してexコマンドを +実行することができます。例: > + + :argdo %s/foo/bar/g +< +さらなる情報については以下を参照してください。 > + + :help :argdo + :help :bufdo + :help :windo +< + *faq-11.15* +11.15. マップ中で置換コマンド":s"を使っています。検索が失敗したときマップが途 + 切れてしまいます。置換が失敗したときにもマップの次のコマンドを続けてほ + しいのですが、どうすればできますか？ + +置換コマンドに対して'e'フラグを指定すると、パターンが見つからなかったときも +マップの他のコマンドを続行します。 + +さらなる情報については以下を参照してください。 > + + :help :s_flags +< + *faq-11.16* +11.16. 行からある文字がn回目に現れる箇所を検索するには？ + +行中からある文字がn回目に現れる箇所を検索するには、'f'コマンドにプリフィックス +をつけます。例えば、文字@が5回目に現れる箇所を検索するには、5f@とします。ただ +しカーソルが行頭にあるものとします。また、1桁目の文字が検索する文字ではないも +のとします。 + +さらなる情報については以下を参照してください。 > + + :help f + :help F + :help t + :help T + :help ; + :help , +< + *faq-11.17* +11.17. タブ(やその他の文字)を改行文字で置換するには？ + +タブ(やその他の文字)を改行文字で置換するには、次のコマンドを使います: > + + :s/\t/\r/ +< +上のコマンドで\rでなく\nを使うと改行文字には置換されないので注意してください。 + +さらなる情報については以下を参照してください。 > + + :help sub-replace-special + :help NL-used-for-Nul + :help CR-used-for-NL +< + *faq-11.18* +11.18. ASCIIコードで検索する文字を指定するには？ + +"/"コマンド中で、CTRL-Vに続いて10進、16進、8進の値を入力すると、ASCIIコードで +その値を持つ文字を検索することができます。ある文字のASCIIコードを知るには +":ascii"や"ga"コマンドが使えます。 + +さらなる情報については以下を参照してください。 > + + :help i_CTRL-V_digit + :help :ascii + :help ga +< + *faq-11.19* +11.19. 長い行を見つけるには？ + +検索コマンドで正規表現を使えば長い行、または指定した数以上の文字を含む行を検索 +することができます。例えば、80文字以上を含む行を検索するには、このようにします +: > + + /^.\{80}.*$ + /^.*\%80c.*$ +< +さらなる情報については以下を参照してください。 > + + :help /\{ + :help /\%c +< + *faq-11.20* +11.20. カレントバッファ内の指定したパターンを含む行を全て表示するには？ + +次のコマンドを使うとカレントバッファ内の指定したパターンを含む行を全て表示する +ことができます: > + + :g//p +< +例えば、次のコマンドはカレントバッファ内の"vim"を含む行を全て表示します: > + + :g/vim/p +< +行番号もいっしょに表示したいならば次のコマンドが使えます: > + + :g//# +< +さらなる情報については以下を参照してください。 > + + :help :global + :help :print + :help :number +< + *faq-11.21* +11.21. 複数行にわたる文字列を検索するには？ + +正規表現のアトム\_xを使えば、複数行にわたる文字列を検索することができます。例 +えば、文字列"Hello World"を検索するには次のコマンドを使います: > + + /Hello\_sWorld +< +これは、単語"Hello"とそれに続く改行文字、そして次行の行頭の単語"World"にマッチ +します。またこれは"Hello"、スペース、"World"にもマッチします。行頭と行末の空白 +を含めて文字列"Hello World"を検索するには、次のコマンドを使います: > + + /Hello\_s\+World +< +さらなる情報については以下を参照してください。 > + + :help 27.8 + :help pattern-atoms + :help /\_ + :help pattern-searches +< + *faq-11.22* +11.22. バッファの指定した範囲内から検索するには？ + +正規表現のアトム\%>lと\% + + /white\%>10l\%<20l +< +さらなる情報については以下を参照してください。 > + + :help /\%l +< + +============================================================================= + *faq-12* +SECTION 12 - テキストを変更する + + *faq-12.1* +12.1. 行末の空白文字(スペースとタブ)を全て削除するには？ + +":substitute"コマンドを使ってファイル中から行末の空白文字を全て削除することが +できます: > + + :%s/\s\+$// +< +さらなる情報については以下を参照してください。 > + + :help :% + :help :s + :help /\s + :help /\+ + :help /$ +< + *faq-12.2* +12.2. 連続する空白文字を1個のスペースに置換するには？ + +次のコマンドで連続する空白文字を1個のスペースに置換することができます: > + + :%s/ \{2,}/ /g +< +さらなる情報については以下を参照してください。 > + + :help :% + :help :s + :help /\{ + :help :s_flags +< + *faq-12.3* +12.3. 連続する空行を1行だけに圧縮するには？ + +次のコマンドで連続する空行を1行だけに圧縮することができます: > + + :v/./.,/./-1join +< +このコマンドの説明は以下の通りです: > + + :v/./ 後に続くコマンドを、1文字も含まない行(空行)を除く全ての行 + に対して実行する。 + ., 現在行を範囲の開始位置に指定する。 + /./ 1文字を含む行を範囲の終端に指定する。 + -1 終端を1行前に調整する。 + j 範囲内の行を連結する。 +< +空行がファイルの末尾にある場合、これはエラーメッセージを出します。それを避ける +には、一時的な行をファイルの末尾に追加し、このコマンドを実行してから一時的な行 +を削除します。 + +さらなる情報については以下を参照してください。 > + + :help :v + :help :join + :help cmdline-ranges + :help collapse +< + *faq-12.4* +12.4. ファイル中の空行を全て削除するには？空白文字だけを含む行を全て削除するに + は？ + +空行を全て削除するには、次のコマンドを使います: > + + :g/^$/d +< +空白文字(スペースとタブ)だけからなる行を削除するには、次のコマンドを使います: +> + + :g/^\s\+$/d +< +空行、または空白だけからなる行を全て削除するには、次のコマンドを使います: > + + :g/^\s*$/d +< + *faq-12.5* +12.5. カーソル下の単語をコピー/ヤンクするには？ + +"yiw" (yank inner word without whitespace) または "yaw" (yank a word with +whitespace)でカーソル下の単語をコピー/ヤンクできます。 + +さらなる情報については以下を参照してください。 > + + :help 04.6 + :help 04.8 + :help iw + :help yank + :help text-objects + :help objects +< + *faq-12.6* +12.6. 行全体ではなく、行内のある位置からある位置までをヤンクするには？ + +ヤンクオペレータ(y)に移動コマンドを指定すれば、行内のある位置から別の位置まで +をヤンクすることができます。例えば、現在のカーソル位置から次のxという文字まで +をヤンクするにはyfx, Fx, tx, Txのどれかを使います。n桁目までをヤンクするには +n|を使います。次に'word'が現れる場所までをヤンクするには/wordとします。別の行 +のn桁目までをヤンクするには、まず'ma'で位置をマークし、ヤンク開始位置まで移動 +してt`a(バッククォートであることに注意)でマークまでをヤンクします。 + +さらなる情報については以下を参照してください。 > + + :help yank + :help motion.txt + :help 4.6 +< + *faq-12.7* +12.7. 現在のレジスタの中身に追加ヤンクするには？ + +レジスタを指定するときに大文字を使うと現在のレジスタに追加ヤンクされます。例え +ば、レジスタ"a"になにかテキストが入っているとします。新しいテキストをここに追 +加するには、レジスタ名"A"を使います。レジスタ名に小文字を使うと、レジスタの中 +身は新しいテキストで上書きされてしまいます。 + +さらなる情報については以下を参照してください。 > + + :help quote + :help quote_alpha + :help 10.1 +< + *faq-12.8* +12.8. 複数行にわたる文全体をヤンクするには？ + +複数行にわたる文全体をヤンクするには、ヤンクオペレータの後に移動コマンドを続け +ます。例: > + + y) +< +文の内側にいるときは'yi)'で文をヤンクすることができます。 + +さらなる情報については以下を参照してください。 > + + :help yank + :help {motion} + :help object-motions + :help 4.6 +< + *faq-12.9* +12.9. あるパターンを含む行全てをヤンクするには？ + +":global"を使えばあるパターンを含む行全てをヤンクし、その後そのレジスタの中身 +をバッファにペーストすることができます: > + + :let @a='' + :g/mypattern/y A +< +最初のコマンドはレジスタ"a"の中身をクリアします。2番目のコマンドは"mypattern" +を含む行全てをレジスタ"a"にコピーします。大文字"A"を使ってマッチした行を追加し +ていることに注意してください。そして"apコマンドでレジスタ"a"の中身をバッファに +ペーストすることができます。 + +さらなる情報については以下を参照してください。 > + + :help :g + :help :y + :help let-register + :help quote_alpha + :help put + :help registers + :help :registers +< + *faq-12.10* +12.10. あるパターンを含まない行全てを削除するには？ + +":v"コマンドを使えば、あるパターンを含まない行全てを削除することができます: > + + :v/pattern/d +< +または > + + :g!/pattern/d +< +さらなる情報については以下を参照してください。 > + + :help :v + :help :g +< + *faq-12.11* +12.11. "pattern"を含む全ての行の前に行を追加するには？ + +以下のコマンドを使うと、"pattern"を含む行全ての前に行を追加することができま +す: > + + :g/pattern/normal Oi +< +または追加する行をYでヤンクし、次のコマンドでそれを追加することができます: > + + :g/pattern/put! +< +さらなる情報については以下を参照してください。 > + + :help :g + :help :put + :help insert + :help 0 +< + *faq-12.12* +12.12. 前の行が特定のパターンを含んでいる行に対して操作を行うには？ + +":global"を使えば、前の行が特定のパターンを含んでいる行に対して操作を行うこと +ができます: > + + :g//+{cmd} +< +さらなる情報については以下を参照してください。 > + + :help :g + :help :range +< + *faq-12.13* +12.13. あるパターンを含む行全てに対してコマンドを実行するには？ + +":global"(:g)コマンドを使えば、あるパターンを含む行全てに対してコマンドを実行 +することができます。 > + + :g/my pattern/d +< +Exコマンドでないコマンドを使いたければ、":normal"を使うことができます: > + + :g/my pattern/normal {command} +< +ノーマルモードコマンドの再帰マッピングを避けたければ代わりに":normal!"を使いま +す("!"に注意)。 + +さらなる情報については以下を参照してください。 > + + :help :global + :help :v + :help :normal +< + *faq-12.14* +12.14. カーソル位置の1文字上の文字をカーソル位置にコピーするには？ + +挿入モードでとするとカーソル位置の1文字上の文字をコピーすることができ +ます。同じようにで1文字下の文字をコピーすることができます。 + +さらなる情報については以下を参照してください。 > + + :help i_CTRL-Y + :help i_CTRL-E +< + *faq-12.15* +12.15. 挿入モードに入らずに現在行の前/後に空行を挿入するには？ + +":put"を使えば空行を挿入できます。例えば、次を実行してみてください: > + + :put ='' + :put! ='' +< +さらなる情報については以下を参照してください。 > + + :help :put +< + *faq-12.16* +12.16. カレントファイルの名前をカレントバッファに挿入するには？ + +カレントファイルの名前をカレントバッファに挿入するにはいくつかの方法がありま +す。挿入モードでは%または=expand("%")でできます。ノーマルモードでは +":put =@%"でできます。 + +さらなる情報については以下を参照してください。 > + + :help i_CTRL-R + :help expand() + :help !! +< + *faq-12.17* +12.17. レジスタの中身をカレントバッファに挿入するには？ + +挿入モードではでの中身を挿入することができます。例え +ば、aでレジスタ"a"の中身をカレントバッファに挿入できます。 + +ノーマルモードでは":put "での中身を挿入できます。例えば、 +":put d"でレジスタ"d"の中身をカレントバッファに挿入できます。 + +さらなる情報については以下を参照してください。 > + + :help i_CTRL-R + :help :put +< + *faq-12.18* +12.18. 行末を越えてカーソルを移動し、テキストを挿入するには？ + +オプション"virtualedit"をセットすれば行末を越えてカーソルを移動し、行末の先に +文字を追加することができます。仮想モードを開始するにはこうします。 > + + :set virtualedit=all +< +さらなる情報については以下を参照してください。 > + + :help 'virtualedit' +< + *faq-12.19* +12.19. カーソル下の単語(例えばjunk)を"foojunkbar"に置き換えるには？ + +いくつかの方法があります。その行の中でその単語が現れる最初の箇所なら、こうしま +す: > + + :exe "s/".expand("")."/foo&bar/" +< +よりマッチを限定させるには、このようなより複雑な置換コマンドを使います: > + + :exe 's/\<'.expand("").'\%>'.(col(".")-1).'c\>/foo&bar/' +< +またはciwfoo"barとしてもできます。 + +さらなる情報については以下を参照してください。 > + + :help :substitute + :help expand() + :help col() + :help /\%c +< + *faq-12.20* +12.20. ディレクトリ中の全てのファイルに対して特定のテキストを置換するには？ + +"argdo"を使えば、引数として指定されたファイル全てに対して置換コマンドを実行す +ることができます: > + + :args * + :argdo %s///ge | update +< +さらなる情報については以下を参照してください。 > + + :help :args_f + :help :argdo + :help :s_flags +< + *faq-12.21* +12.21. ファイル中に数字が書かれています。これを増加・減少させるには？ + +CTRL-Aで数字を増加、CTRL-Xで減少させることができます。また、カウントを指定すれ +ば増加・減少させる数を指定することができます。この機能は10進、8進、16進の数字 +に対して適用することができます。 + +さらなる情報については以下を参照してください。 > + + :help CTRL-A + :help CTRL-X + :help 'nrformats' +< + + *faq-12.22* +12.22. ":substitute"で最後に検索したパターンを再利用するには？ + +":substitute"で検索パターンを指定しなければ、最後に検索したパターンを再利用す +ることができます: > + + :s/pattern/newtext/ + :s//sometext/ +< +2回目の":s"では、検索パターンが指定されていないので、最初の":s"のパターンが使 +われます。 + +検索パターンは変えたいが、置換語を同じものにしたい場合は、チルダ文字を使いま +す: > + + :s/newpattern/~/ +< +さらなる情報については以下を参照してください。 > + + :help :s + :help :& + :help :~ + :help & + :help sub-replace-special +< + *faq-12.23* +12.23. ":substitute"を使って大文字・小文字を入れかえるには？ + +":substitute"の置換文字列に特殊文字を使えば、マッチした文字列の大文字・小文字 +を入れかえることができます。例えば、文字列"MyString"を全て大文字にするには、以 +下のコマンドを使うことができます: > + + :%s/MyString/\U&/g +< +小文字にするには、次のコマンドを使います: > + + :%s/MyString/\L&/g +< +現在行の全ての単語の最初の文字を大文字にするには、次のコマンドを使います: > + + :s/\<\(.\)\(\k*\)\>/\u\1\L\2/g +< +さらなる情報については以下を参照してください。 > + + :help sub-replace-special + :help :substitute + :help \U + :help \L + :help \u +< + *faq-12.24* +12.24. キーボード上に無い文字を入力するには？ + +ダイグラフを使えば、キーボード上に無い文字を入力することができます。現在定義さ +れているダイグラフを全て表示するには":digraphs"を使います。":digraphs"を使えば +リストに新しいダイグラフを追加できます。 + +さらなる情報については以下を参照してください。 > + + :help digraphs + :help 'digraphs' + :help 24.9 +< + *faq-12.25* +12.25. ダイグラフのどれか、または全てを削除するコマンドはありますか？ + +ありません。ダイグラフテーブルはコンパイル時に定義されます。できるのは新しいダ +イグラフを追加することだけです。ダイグラフを削除するコマンドを追加するという事 +はTODOリストにはありません。 + + *faq-12.26* +12.26. 挿入モードでバックスペースキーを押すと、今回の挿入モードで入力した文字 + が消されるだけです。バックスペースキーで前回の挿入モードで入力した文字 + を消すには？ + +'backspace'をセットすれば挿入モードで前回入力した文字を削除することができます: > + + :set backspace=indent,eol,start +< +さらなる情報については以下を参照してください。 > + + :help 'backspace' +< + *faq-12.27* +12.27. 72文字より長くて"+"で終わり、次行に折り返されている行があります。このよ + うな行をすばやく連結させるには？ + +":global"を使えばそのような行を検索・連結できます: > + + :g/+$/j +< +しかしこれは2行ごとに連結するだけです。連続する"+"で終わる行を連結する、より複 +雑な2つの例が以下の通りです: > + + :g/*$/,/\(^\|[^+]\)$/j + :g/+$/mark a | .,/\(^\|[^+]\)$/s/+$// | 'a,.j +< +{訳注: 1番目の例は :g/+$/,/\(^\|[^+]\)$/j の間違いだと思う。} + +さらなる情報については以下を参照してください。 > + + :help :g + :help :j + :help :mark +< + *faq-12.28* +12.28. 文字単位でヤンクされたテキストを新しい行にペーストするには？ + +":put"を使えば文字単位でヤンクされたテキストを新しい行にペーストできます: > + + :put =@" +< +さらなる情報については以下を参照してください。 > + + :help :put + :help quote_= +< + *faq-12.29* +12.29. 単語・文字・テキストのブロックの大文字小文字を入れかえるには？ + +"~"を使えば文字の大文字・小文字を入れかえることができます。 + +カーソル下の単語を大文字にするには"gUiw"または"viwU"、小文字にするには"guiw"ま +たは"viwu"とすればできます。 + +カーソル下の単語の大文字・小文字を入れかえるには"viw~"または"g~iw"とします。 + +"gUgU"とすれば現在行を大文字にでき、"gugu"とすれば現在行を小文字にできます。 + +"g~g~"とすれば現在行の大文字・小文字を入れかえることができます。"g~{motion}"ま +たは"{Visual}~"とすればテキストのブロックの大文字・小文字を入れかえることがで +きます。 + +さらなる情報については以下を参照してください。 > + + :help case +< + *faq-12.30* +12.30. キーボード上にないASCII文字を入力するには？ + +キーボード上にないASCII文字を入力するには、CTRL-Vを押してからそのASCIIコードを +入力します。特別なASCII文字を入力するのにダイグラフを使うこともできます。 + +さらなる情報については以下を参照してください。 > + + :help i_CTRL-V_digit + :help digraphs + :help 45.5 +< + *faq-12.31* +12.31. ファイル中の印字不能文字を置換するには？ + +印字不能文字を置換するには、まずその文字のASCIIコードを知らなければなりませ +ん。exコマンド":ascii"またはノーマルモードコマンド"ga"を使ってカーソル下の文字 +のASCIIコードを知ることができます。 + +CTRL-Vに続けて10進の数字1-255(最初に0をつけてばならない)またはxと16進の数字 +00-FF、または8進の数字0-0377(最初に0をつける)またはuと16進の数字0-FFFFまたは +Uと16進の数字0-7FFFFFFFを入力すれば、印字不能文字を入力することができます。 + +別の方法としては、":digraphs"を使って、全文字に対するダイグラフと共にそれらの +10進値プラスアルファを表示することです。CTRL-Kに続けて英数字を2つ(ダイグラフ) +を入力すれば印字不能文字を入力することができます。 + +さらなる情報については以下を参照してください。 > + + :help :ascii + :help i_CTRL-V + :help i_CTRL-V_digit + :help :digraphs +< + *faq-12.32* +12.32. バッファから重複した行を削除するには？ + +次のユーザー定義コマンドを使えばバッファから重複した行を全て削除することができ +ます: > + + :command -range=% Uniq ,g/^\%<l\(.*\)\n\1$/d +< +上のコマンドを.vimrcに追加し、":Uniq"を実行すると重複した行が削除されます。 + + *faq-12.33* +12.33. ファイル中の全ての行の前に行番号をつけるには？ + +行番号をつけるにはいくつかの方法があります。以下はその例です: > + + :%s/^/\=line('.'). ' ' + :%s/^/\=strpart(line(".")." ", 0, 5) + :g/^/exec "s/^/".strpart(line(".")." ", 0, 4) +< +さらなる情報については以下を参照してください。 > + + :help sub-replace-special + :help line() + :help expr6 + :help strpart() + :help :execute + :help :global +< + *faq-12.34* +12.34. 2つの文字・単語・行を入れ換えるには？ + +"xp"で2つの文字を入れ換えることができます。'x'でカーソル下の文字を削除し、'p' +で削除された文字をカーソル下の文字の後ろにペーストします。その結果、2つの文字 +が入れ換わります。 + +2つの単語を入れ換えるには"deep"とします(最初の単語の前の空白にカーソルをおいて +実行します)。 + +2つの行を入れ換えるには"ddp"とします。'dd'で現在行を削除し、'p'で現在行の後ろ +に削除された行をペーストします。その結果、2つの行が入れ換わります。 + +以上の操作はどれも無名レジスタ"の中身を変更します。 + +":m +"とすると無名レジスタの中身を変更することなく2つの行を入れ換えることがで +きます。 + +さらなる情報については以下を参照してください。 > + + :help x + :help p + :help dd + :help d + :help e + :help linewise-register + :help quotequote + :help :move +< + +============================================================================= +SECTION 13 - 挿入モードでの補完 + + *faq-13.1* +13.1. 挿入モードで単語や行を補完するには？ + +挿入モードでCTRL-PまたはCTRL-Nを使うと単語を補完することができます。 +CTRL-Nは次の候補を前方から検索します。 +CTRL-Pは次の候補を後方から検索します。 + +挿入モードでCTRL-X CTRL-Lを使うと現在行のカーソル以前の文字列で始まる行を補完 +します。次のマッチする行を取得するにはCTRL-PまたはCTRL-Nを使います。挿入モード +で単語を補完する方法・キーは他にもたくさんあります。 + +Vimは以下の要素の補完をサポートしています: > + + CTRL-X CTRL-F ファイル名 + CTRL-X CTRL-L 行全体 + CTRL-X CTRL-D マクロ定義 (インクルードファイル中のものも) + CTRL-X CTRL-I カレントファイルとインクルードファイル + CTRL-X CTRL-K 辞書中の単語 + CTRL-X CTRL-T シソーラス中の単語 + CTRL-X CTRL-] タグ + CTRL-X CTRL-V Vimコマンドライン +< +さらなる情報については以下を参照してください > + + :help 24.3 + :help ins-completion +< + *faq-13.2* +13.2. 挿入モードでファイル名を補完するには？ + +挿入モードでCTRL-X CTRL-Fを使うとカレント行のカーソルの前の文字列で始まるファ +イル名を補完することができます。 + +さらなる情報については以下を参照してください > + + :help compl-filename +< + *faq-13.3* +13.3. 挿入モードで単語を補完するのにCTRL-P/CTRL-Nを使っています。 + 今補完した単語の後に現れる単語を補完するには？ + +CTRL-X CTRL-NとCTRL-X CTRL-Pを使うと今補完した単語の後に続く単語を補完すること +ができます。 + +さらなる情報については以下を参照してください > + + :help i_CTRL-X_CTRL-P + :help i_CTRL-X_CTRL-N + :help ins-completion +< + +============================================================================= + *faq-14* +SECTION 14 - テキストの整形 + + *faq-14.1* +14.1. 折り返された行の末尾に改行を挿入するには？ + +'gq'コマンドを使うと段落を整形することができます。これは現在の'textwidth'の設 +定にしたがってテキストを整形します。 + +オペレータgqは移動コマンドと組み合わせて、テキストの範囲に対して実行できます。 +例: > + + gqgq - 現在行を整形する + gqap - 現在の段落を整形する + gq3j - 現在行と下3行を整形する +< +さらなる情報については以下を参照してください > + + :help gq + :help formatting + :help usr_25.txt + :help motion.txt +< + *faq-14.2* +14.2. 1行がn文字以下になるように長い行を整形するには？ + +まず'textwidth'を望みの値に設定します: > + + set textwidth=70 +< +そして、'textwidth'で設定された長さで行を折り返すにはこうします > + + :g/./normal gqq +< +さらなる情報については以下を参照してください > + + :help gq +< + *faq-14.3* +14.3. 短い行を連結して段落を形成するには？ + +まず、'textwidth'を大きな値に設定します: > + + :set textwidth=99999 +< +続いて、以下のコマンドで短い行を連結して段落を形成します: > + + 1GgqG +< +このコマンドはファイル全体に作用します。指定した範囲内の全段落に対して整形を行 +うにはこうします: > + + :'a,'bg/\S/normal gq} +< +さらなる情報については以下を参照してください > + + :help gq + :help G + :help gqq +< + *faq-14.4* +14.4. 箇条書きや番号つきリストを整形するには？ + +'formatoptions'によって箇条書きや番号つきリストを整形するように設定することが +できます。例えば、以下のフォーマットのリストを整形することができます: + + - this is a test. this is a test. this is a test. this is a test. + this is a test. + +これがこのような形式になります。 + + - this is a test. this is a test. this is a test. this is a test. + this is a test. + +'formatoptions'に'n'フラグをつけると、テキストの桁をそろえることができます。 > + + :set fo+=n +< +このオプションを設定してテキストを整形すると、Vimは番号つきリストを認識しま +す。このオプションを機能させるためには、'autoindent'をセットしなければなりませ +ん。 + +さらなる情報については以下を参照してください > + + :help 'formatoptions' + :help fo-table +< + *faq-14.5* +14.5. 挿入モードで行をインデントするには？ + +挿入モードでCTRL-Tを押すと現在行の行頭にshiftwidth分のインデントを挿入すること +ができます。挿入モードでCTRL-Dを押すと現在行の行頭のshiftwidth分のインデントを +削除することができます。また、CTRL-O >>とCTRL-O <<でも挿入モード中に現在行をイ +ンデントすることができます。 + +さらなる情報については以下を参照してください > + + :help i_CTRL-T + :help i_CTRL-D + :help i_0_CTRL-D + :help i_CTRL-O + :help >> + :help << +< + *faq-14.6* +14.6. ファイル全体を整形・インデントするには？ + +gg=Gでファイル全体を整形・インデントすることができます。ここで、 > + + gg - ファイルの先頭に移動 + = - インデントを適用 + G - ファイルの末尾まで +< +という意味になります。 +さらなる情報については以下を参照してください > + + :help gg + :help = + :help G + :help 'formatprg' + :help C-indenting +< + *faq-14.7* +14.7. 現在のファイルのインデントを増やす/減らすには？ + +'>>'と'<<'で現在行のインデントを増やしたり減らすことができます。 + +さらなる情報については以下を参照してください > + + :help shift-left-right + :help >> + :help << + :help 'shiftwidth' +< + *faq-14.8* +14.8. ブロックまたは行のグループをインデントするには？ + +ビジュアルモードで行を選択して>または<を押すと選択した行をインデント・アンイ +ンデントすることができます。次のexコマンドを使っても行をインデントすることがで +きます > + + :10,20> +< +さらなる情報については以下を参照してください > + + :help shift-left-right + :help v_> + :help v_< + :help :< + :help :> +< + *faq-14.9* +14.9. >または<キーで行をインデントすると、'tabstop'で設定した値でなく、標準的 + なタブストップ値の8が使われます。なぜですか？ + +オペレータ">"でインデントしたとき挿入されるスペースの数は'shiftwidth'オプショ +ンで決まります。'tabstop'の設定はインデントには適用されません。インデントで挿 +入されるスペースの数を変更するには、こうします: > + + :set shiftwidth=4 +< +さらなる情報については以下を参照してください > + + :help 'shiftwidth' + :help >> + :help 'softtabstop' +< + *faq-14.10* +14.10. オートインデントを無効にするには？ + +デフォルトではオートインデントは無効になっています。設定ファイル(.vimrc, +.gvimrc)のインデントに関する設定を確認してください。":filetype indent on"が行 +われていないことを確かめてください。もし行われていたなら、これを削除してくださ +い。また、好みに応じて'autoindent', 'smartindent', 'cindent', 'indentexpr'の値 +を確かめ、これらをオフにしてもよいでしょう。 + +さらなる情報については以下を参照してください > + + :help :filetype-indent-off + :help 'autoindent' + :help 'smartindent' + :help 'cindent' + :help 'indentexpr' +< + *faq-14.11* +14.11. メールを編集するときは自動的に'textwidth'オプションをある値にするように + するには？ + +'FileType'オートコマンドを使えば'textwidth'を設定することができます: > + + autocmd FileType mail set tw= +< +さらなる情報については以下を参照してください > + + :help :autocmd + :help FileType + :help usr_43.txt +< + *faq-14.12* +14.12. 自動的に改行を挿入させることはできますか？ + +できます。'textwidth'を好きな行の長さに設定します。すると新しい行を挿入すると +きに自動的に改行が挿入されます。例: > + + :set textwidth=75 +< +さらなる情報については以下を参照してください > + + :help textwidth + :help ins-textwidth + :help 'formatoptions' + :help fo-table + :help formatting +< + *faq-14.13* +14.13. ファイル中に^Mという記号がたくさん表示されます。'fileformat'を'dos'にし + たり'unix'にしたり'mac'にしたりしてみましたが、改善できません。これらの + 記号を表示させなくするには？ + +ファイルを読み込むとき、そのファイルのフォーマットは以下のようにして決定されま +す: + +- 全ての行が改行文字()で終わっていればファイルフォーマットは'unix'です。 +- 全ての行がキャリッジリターン文字()に続く改行文字()で終わっていれば + ファイルフォーマットは'dos'です。 +- 全ての行がキャリッジリターン文字()で終わっていればファイルフォーマットは + 'mac'です。 + +一部の行がで終わっていて、一部の行がに続くで終わっているとき、ファ +イルフォーマットは'unix'になります。 + +カレントファイルのフォーマットを変更するには、'fileformat'を変更し、ファイルを +保存します: > + + :set fileformat=dos + :w +< +カレントファイルのフォーマットを表示するにはこうします > + + :set fileformat? +< +以上の動作は'fileformats'によっても変わります。次のコマンドを試してみてくださ +い: > +さらなる情報については以下を参照してください > + + :help 'fileformats' + :help 'fileformat' + :help file-formats + :help DOS-format-write + :help Unix-format-write + :help Mac-format-write + :help dos-file-formats + :help 23.1 +< + *faq-14.14* +14.14. 他のアプリケーションからVimのバッファへテキストを貼り付けたとき、挿入さ + れたテキストの桁(インデント)が狂ってしまいます。これを直すには？ + +テキストのインデントが狂うのはインデントに関する様々なオプション(autoindent, +smartindent, textwidth)によります。テキストをVimに貼り付ける前に'paste'をセッ +トしてください: > + + :set paste +< +テキストをペーストしたらこのオプションをオフにします: > + + :set paste! +< +レジスタ*によってクリップボードを使用できる場合はCTRL-R CTRL-O *とするとインデ +ントなしでテキストを貼り付けることができます。 + +さらなる情報については以下を参照してください > + + :help 'paste' + :help 'pastetoggle' + :help i_CTRL-R_CTRL_O + :help clipboard + :help xterm-clipboard + :help gui-clipboard +< + *faq-14.15* +14.15. 'wrap'をオンにしていて、とても長い行が折り返されて画面に収まりきらない + とき、まったく何も表示されません。折り返された行の代わりに'@'という記号 + で始まる空の行が表示されます。行が収まるように画面をスクロールする + と'@'は消え、行が表示されるようになります。この挙動の設定はどうやるので + すか？ + +'display'オプションを'lastline'に設定すると、'@'を表示する代わりに可能な限り最 +後の行を表示するようになります。 > + + :set display=lastline +< +さらなる情報については以下を参照してください > + + :help 'display' +< + *faq-14.16* +14.16. ファイル中の全てのタブ文字をスペースに変換するには？ + +":retab"を使うとカレントファイル中の全てのタブ文字を'expandtab'と'tabstop'の設 +定にしたがって変換することができます。例えば、全てのタブをスペースに変換するに +はこのようにします > + + :set expandtab + :retab +< +さらなる情報については以下を参照してください > + + :help :retab + :help 'expandtab' + :help 'tabstop' + :help 25.3 +< + *faq-14.17* +14.17. 後でワードプロセッサに送るテキストを編集するためのオプションは？ + +後でワードプロセッサに送るテキストを編集するためには以下のオプションを設定する +ことができます: > + + :set wrap + :set linebreak + :set textwidth=0 + :set showbreak=>>> +< +'gk'と'gj'を使うと画面上の行(物理行)単位で上下に移動できます。 +さらなる情報については以下を参照してください > + + :help 'wrap' + :help 'linebreak' + :help 'textwidth' + :help 'showbreak' + :help gk + :help gj +< + +============================================================================= + *faq-15* +SECTION 15 - ビジュアルモード + + *faq-15.1* +15.1. 矩形範囲をコピーするには？ + +矩形選択モードを使えば矩形範囲をコピーすることができます。矩形選択モードを開始 +するにはCTRL-Vキーを押します。移動コマンドを使ってカーソルを動かし、yを押すと +選択したテキストがヤンクされます。 + +CTRL-Vが期待通りに機能しない場合は、スクリプトmswin.vimによってこの機能が +CTRL-Qにマップされているかもしれません。Windowsマシン上では他のプログラムに共 +通のショートカットを真似するため、しばしばvimrcによってこのスクリプトがsource +されています。 + +さらなる情報については以下を参照してください > + + :help 04.4 + :help blockwise-visual + :help visual-mode + :help Q_vi +< + *faq-15.2* +15.2. ファイルの特定の列を削除・変更するには？ + +矩形選択モードを使えば特定の列を選択してオペレータコマンド(変更・削除・コピー) +を適用することができます。 + +さらなる情報については以下を参照してください > + + :help visual-block + :help visual-operators +< + *faq-15.3* +15.3. ビジュアル選択した行に対してexコマンドを適用するには？ + +ビジュアルモードで行を選択すると、レジスタ<が選択範囲の開始位置にセットされ、 +レジスタ>が選択範囲の終端にセットされます。これらのレジスタを使えばexコマンド +の範囲を指定できます。行をビジュアル選択してから":"を押すとコマンドモードに移 +行します。自動的に選択範囲を示す'<,'>が挿入されます。選択範囲に対してどんなex +コマンドでも実行することができます。 + +さらなる情報については以下を参照してください > + + :help v_: + :help '< + :help '> +< + *faq-15.4* +15.4. 矩形選択した範囲に対してexコマンドを適用するには？ + +exコマンドは全て行全体に対してのみ実行されます。テキストを矩形選択してexコマン +ドを実行しようとすると、(選択した列だけでなく)選択した行全体に対して実行されて +しまいます。http://vim.sourceforge.net から入手できるプラグインvis.vimを使えば +矩形範囲に対してexコマンドを適用することができます。 + +さらなる情報については以下を参照してください > + + :help cmdline-ranges + :help 10.3 + :help cmdline-lines +< + *faq-15.5* +15.5. ビジュアルモードでファイル全体を選択するには？ + +ggVGでファイル全体をビジュアル選択することができます。 > + + gg - ファイルの先頭へ移動 + V - 行単位ビジュアル選択を開始 + G - ファイルの末尾へ移動 +< +さらなる情報については以下を参照してください > + + :help gg + :help linewise-visual + :help G +< + *faq-15.6* +15.6. ビジュアル選択してから>キーを押してインデントすると、選択が解除されま + す。この範囲に対して操作を続けるため選択したままにするには？(または)最後 + に選択された範囲を再選択するには？ + +'gv'で最後に選択された範囲を再選択できます。またマーク'<と'>を使うと最後に選択 +された範囲の開始位置と終端に移動することができます。 + +さらなる情報については以下を参照してください > + + :help gv + :help '< + :help '> +< + *faq-15.7* +15.7. ビジュアル選択した範囲の先頭/末尾へ移動するには？ + +(ビジュアルモードにおいて)'o'コマンドでビジュアル選択した範囲の先頭/末尾へ移動 +できます。 + +さらなる情報については以下を参照してください > + + :help v_o +< + *faq-15.8* +15.8. マウスでテキストを選択してからexコマンドを実行しようと:キーを押すと選択 + された範囲が文字:で置換されてしまいます。マウスで選択したときもビジュア + ル選択したときのようにテキストに対してexコマンドを実行するには？ + +これは'selectmode'でビジュアルモードでなく選択モードを使うように設定していると +き起こります。このオプションの値を確認してください: > + + :set selectmode? +< +このモードは選択モードといい、ビジュアルモードに似ています。"behave mswin"コマ +ンドを使うと、このオプションも自動的にセットされます。選択モードはビジュアル +モードと同じように見えますが、MS-Windowsの選択モードに似ています。 + +さらなる情報については以下を参照してください > + + :help Select-mode + :help 'selectmode' + :help 9.4 + :help :behave +< + *faq-15.9* +15.9. マウスでテキストを選択するとビジュアルモードでなく選択モードに入ってしま + います。なぜですか？ + +マウスでテキストを選択したとき選択モードになるかどうかは'selectmode'オプション +によって決まります。ビジュアルモードが始まるようにするには、'selectmode'から +'mouse'の値を除きます: > + + :set selectmode-=mouse +< +デフォルトでは'selectmode'は空になっていて、常にビジュアルモードが使われるよう +になっています。 + +さらなる情報については以下を参照してください > + + :help 'selectmode' + :help Select-mode + :help :behave +< + *faq-15.10* +15.10. 最後にコピー/ペーストされたテキストをビジュアル選択するには？ + +マーク'['と']を使うと最後にコピー/ペーストされたテキストを選択することができ +ます。マーク'[は最後に変更/ヤンクされたテキストの先頭にセットされ、']はその末 +尾にセットされます。この範囲をビジュアル選択するには、'[v']とします。 + +さらなる情報については以下を参照してください > + + :help '[ + :help '] + :help `a + :help v +< + +============================================================================= + *faq-16* +SECTION 16 - コマンドラインモード + + *faq-16.1* +16.1. コマンドモードまたはexコマンドモードでカレントファイル名を使うには？ + +コマンドモードでは文字'%'がカレントファイルの名前を表します。いくつかのコマン +ドにおいてはファイル名を取得するためにexpand("%")を使わねばなりません: > + + :!perl % +< +さらなる情報については以下を参照してください。 > + + :help :_% + :help cmdline-special + :help expand() +< + *faq-16.2* +16.2. Vimのコマンドラインで効率的にテキストを編集するには？ + +Vimのコマンドラインテキストを編集するのにコマンドラインウィンドウを使うことが +できます。コマンドラインウィンドウを開くにはノーマルモードで"q:"とします。コマ +ンドラインモード中からはCTRL-Fを使います。このウィンドウにはコマンドラインの履 +歴が表示されます。通常のVimのキー・コマンドを使って以前の・新しいコマンドライ +ンを編集することができます。コマンドラインを実行するにはエンター/リターンキー +を押します。 + +同様に、検索履歴を"q/"と"q?"で編集することができます。 + +さらなる情報については以下を参照してください。 > + + :help cmdline-window +< + *faq-16.3* +16.3. ViモードからExモードに移行するには？ + +QでViモードからExモードに移行できます。ExモードからViモードに移行するには :vi +を使います。 + +さらなる情報については以下を参照してください。 > + + :help Q + :help gQ + :help Ex-mode + :help :vi +< + *faq-16.4* +16.4. exコマンドの出力をバッファにコピーするには？ + +exコマンドの出力をバッファにコピーするには、まずそのコマンドの出力をレジスタに +入れます。":redir"で出力をレジスタに入れることができます。例 > + + :redir @a + :g/HelloWord/p + :redir END +< +するとレジスタ'a'がexコマンド"g/HelloWord/p"の出力を保持します。ここでレジスタ +'a'の中身をバッファにペーストすることができます。'redir'を使ってexコマンドの出 +力をファイルに送ったり、追加することもできます。 + +":global"の前に":silent"を付けると、その行が画面に表示されるのを避けることがで +きます。 + +exコマンドの出力をファイルにリダイレクトするには、次の一連のコマンドを使うこと +ができます: > + + :redir > myfile + :g/HelloWord/p + :redir END +< +さらなる情報については以下を参照してください。 > + + :help :redir + :help :silent +< + *faq-16.5* +16.5. コマンドモードでファイル名を補完しようとタブキーを押します。マッチする + ファイル名が複数ある時、Vimは最初にマッチするファイル名を補完し、マッチ + したファイル名全てのリストを表示します。マッチしたファイル名全てを表示す + るだけで、最初の候補を補完しないようにするには？ + +'wildmode'を設定すればコマンドモードでのファイル名補完をカスタマイズすること +ができます。この場合は'wildmode'を'list'にすればよいでしょう: > + + :set wildmode=list +< +さらなる情報については以下を参照してください。 > + + :help 'wildmode' +< + *faq-16.6* +16.6. バッファからコマンドラインにテキストをコピーしたり、コマンドラインから + バッファにテキストをコピーするには？ + +バッファからコマンドラインにテキストをコピーするには、バッファからテキストをヤ +ンクした後にコマンドラインでCtrl-R 0を押せばペーストすることができます。また、 +CTRL-R を使って特定のレジスタにヤンクしてからコマンドラインにペース +トすることもできます。CTRL-R CTRL-Wを使うとカーソル下の単語をコマンドラインに +ペーストすることができます。 + +コマンドラインからバッファにテキストをコピーするには、":pとしてレジスタ:の中身 +をペーストすればできます。最後に実行されたコマンドラインがレジスタ:に保存され +ています。 + +コマンドラインへテキストをコピー＆ペーストする別の方法は、ノーマルモードでq:を +押すかまたはコマンドラインモードでCTRL-Fを押してコマンドラインウィンドウを開く +ことです。このコマンドラインウィンドウではVimの全てのコマンドを使ってコマンド +ラインを編集することができます。 + +さらなる情報については以下を参照してください。 > + + :help c_CTRL-R + :help quote_: + :help cmdline-window +< + *faq-16.7* +16.7. あるコマンドを実行することなくコマンド履歴に入れるには？ + +あるコマンドを実行することなくコマンド履歴に入れるには、キーを押してその +コマンドをキャンセルします。 + +さらなる情報については以下を参照してください。 > + + :help c_ +< + *faq-16.8* +16.8. コマンドラインの高さを上げるには？ + +'cmdheight'を変更すればコマンドラインの高さを上げることができます: > + + :set cmdheight=2 +< +さらなる情報については以下を参照してください。 > + + :help 'cmdheight' + :help hit-enter + :help 05.7 +< + +============================================================================= + *faq-17* +SECTION 17 - VIMINFO + *faq-17.1* + +17.1. Vimを起動したときviminfoファイルに不正な文字があるとエラーメッセージが出 + ます。このメッセージを出なくさせるには？ + +$HOME/.viminfoまたは$HOME/_viminfoファイルを削除すればこのメッセージは出なくな +ります。 + +さらなる情報については以下を参照してください。 > + + :help viminfo-errors + :help viminfo-file-name + :help viminfo + :help 21.3 +< + *faq-17.2* +17.2. viminfo機能を無効にするには？ + +デフォルトではviminfo機能は無効になっています。もしシステムレベルのvimrcによっ +てviminfo機能が有効化されているなら、ユーザーのローカルな.vimrcで'viminfo'に空 +文字列を設定すれば、viminfo機能が無効になります: > + + :set viminfo="" +< +さらなる情報については以下を参照してください。 > + + :help 'viminfo' +< + *faq-17.3* +17.3. Vimのセッションをまたいでマークを保存し、使用するには？ + +viminfoを使えばVimのセッションをまたいでマークを保存し、復元することができま +す。viminfoファイルを使うには'viminfo'オプションが空でないことを確かめてくださ +い。Vimのマークを保存し、復元するには、'viminfo'オプションに'f'フラグが入って +いないか、'f'に対する値が0より大きくなっていなければなりません。 + +さらなる情報については以下を参照してください。 > + + :help 21.3 + :help viminfo + :help 'viminfo' + :help :wviminfo + :help :rviminfo +< + +============================================================================= + *faq-18* +SECTION 18 - リモート編集 + + *faq-18.1* +18.1. 既に起動しているgvimでファイルを開くには？ Vim 5.xのOpenWithVim.exeと + SendToVim.exeはどうなりました？ + +Vim6からOpenWithVim.exeとSendToVim.exeユーティリティのOLE版はクライアント-サー +バー機能によってとって替わられました。ファイルj.txtを既に起動している +gvim(MyVim) で開くにはこのようにします: > + + $ gvim --servername MyVim --remote-silent j.txt +< +現在起動しているVim全てのサーバー名をリストするにはこうします: > + + $ vim --serverlist +< +クライアント-サーバー機能についてのさらなる情報は以下を参照してください。 > + + :help client-server +< + *faq-18.2* +18.2. vimサーバーに全てのバッファをディスクに保存するようなコマンドを送るには？ + +それにはVimのリモートサーバー機能を使うことができます: > + + $ gvim --servername myVIM --remote-send ":wall" +< +さらなる情報については以下を参照してください。 > + + :help client-server + :help CTRL-\_CTRL-N + :help :wall +< + *faq-18.3* +18.3. Vimのリモートサーバー機能についてのドキュメントはどこで手に入りますか？ + +Vimのリモートサーバー機能についての情報はこれを読めば得られます > + + :help client-server +< + +============================================================================= + *faq-19* +SECTION 19 - オプション + + *faq-19.1* +19.1. Vimを設定する簡単な方法は？ + +":options"でオプションウィンドウを開くことができます: > + + :options +< +このウィンドウで全オプションを見て、設定することができます。 + +さらなる情報については以下を参照してください。 > + + :help :options +< + *faq-19.2* +19.2. オプションの値をトグルするには？ + +オプションの前に"inv"をつけると、その値をトグルすることができます: > + + :set invignorecase + :set invhlsearch +< +オプションの後ろに"!"をつけてもその値をトグルすることができます: > + + :set ignorecase! + :set hlsearch! +< +さらなる情報については以下を参照してください。 > + + :help set-option +< + *faq-19.3* +19.3. 現在のバッファ/ウィンドウに対してだけ効果を及ぼすようにオプションを設定 + するには？ + +":setlocal"を使うと現在のバッファ/ウィンドウに対してだけ効果を及ぼすようにオ +プションを設定できます: > + + :setlocal textwidth=70 +< +全てのオプションがローカルな値を持つわけではないことに注意してください。そのオ +プションがローカルな値を持てる場合だけ、":setlocal"でバッファ/ウィンドウにロ +ーカルに設定できます。 + +また、次のコマンドでもオプションをローカルに設定できます: > + + :let &l:{option-name} = +< + *faq-19.4* +19.4. オプションの値にスペースを含めるには？ + +オプション値にスペースを含めるには、スペースをエスケープしなければなりません。 +例: > + + :set tags=tags\ /usr/tags +< +さらなる情報については以下を参照してください。 > + + :help option-backslash +< + *faq-19.5* +19.5. オプション設定をファイルに埋め込むには？ + +モードラインを使えばオプション設定をファイル中に埋め込むことができます。例え +ば、Cのファイルでファイルの先頭または末尾に次の行を埋め込むことができます: > + + /* vim:sw=4: */ +< +こうするとそのCファイルを編集するとき'shiftwidth'が4に設定されます。これが機能 +するためには、'modeline'オプションをセットしなければなりません。デフォルトで +'modeline'は設定されています。'modelines'はチェックされる行数を指定します。 + +さらなる情報については以下を参照してください。 > + + :help 21.6 + :help modeline + :help auto-setting + :help 'modeline' + :help 'modelines' +< + *faq-19.6* +19.6. ファイル中の全ての行の行番号を表示するには？ + +'number'オプションをセットすれば、全行に対して行番号が表示されます。 > + + :set number +< +さらなる情報については以下を参照してください。 > + + :help 'number' +< + *faq-19.7* +19.7. 'number'オプションで表示される行番号の幅を変えるには？ + +'number'オプションで表示される行番号の幅はVimのソース中にハードコードされてい +ます。なにかオプションを設定することによってこの幅を変更することは不可能です。 + +行番号の幅を変えるオプションの要望とパッチはVimのTODOリスト中にあります: > + + "Add an option to set the width of the 'number' column. Eight + positions is often more than needed. Or adjust the width to the length + of the file? + Add patch that adds 'numberlen' option. (James Harvey) + Other patch with min and max from Emmanuel Renieris (2002 Jul 24) + Other patch without an option by Gilles Roy (2002 Jul 25)" +< +{訳注: Vim7でオプション'numberwidth'が導入された。} + + *faq-19.8* +19.8. スペース、タブ、改行などの不可視文字を表示するには？ + +'list'オプションをセットすれば、ファイル中の不可視文字を表示することができま +す。 > + + :set list +< +このオプションをセットすると、スペース、タブ、改行、行末のスペース、折り返され +た行を表示することができます。 + +不可視文字を表示しなくするには(これがデフォルトです)、'list'をオフにします: > + + :set nolist + (or) + :set list! +< +":set list!"とすると現在の'list'の設定をトグルします。 + +'listchars'オプションを変更すれば表示される不可視文字とその表示のされかたを設 +定することができます。例えば、次のコマンドは行末のスペースを'.'で表示するよう +にします。 > + + :set listchars=trail:. +< +さらなる情報については以下を参照してください。 > + + :help 'listchars' + :help 'list' +< + *faq-19.9* +19.9. 常に現在行と桁番号を表示するようにするには？ + +'ruler'をセットすれば現在の行と桁番号をステータスラインに表示するようになりま +す: > + + :set ruler +< +さらなる情報については以下を参照してください。 > + + :help 'ruler' +< + *faq-19.10* +19.10. 現在のモードを表示するようにするには？ + +'showmode'オプションをセットすれば現在のVimのモードを表示するようになります。 +挿入、置換、ビジュアルモードにおいて、最後の行に現在のモードを表示するようにな +ります。 > + + :set showmode +< +さらなる情報については以下を参照してください。 > + + :help 'showmode' +< + *faq-19.11* +19.11. ステータスラインに入力途中のコマンドを表示するようにするには？ + +'showcmd'をセットすればステータスラインに入力途中のコマンドを表示するようにな +ります: > + + :set showcmd +< +さらなる情報については以下を参照してください。 > + + :help 'showcmd' +< + *faq-19.12* +19.12. ステータスラインに異なる設定・値を表示するようにするには？ + +'statusline'をセットすれば異なる設定・値をステータスラインに表示するようになり +ます。 + +さらなる情報については以下を参照してください。 > + + :help 'statusline' + :help 'laststatus' + :help 'rulerformat' + :help 'ruler' +< + *faq-19.13* +19.13. 常にステータスラインを表示するようにするには？ + +'laststatus'を2にすれば常にステータスラインを表示するようになります。 > + + :set laststatus=2 +< +さらなる情報については以下を参照してください。 > + + :help 'laststatus' +< + *faq-19.14* +19.14. Vimを再起動しても設定が永続するようにするには？ + +Vimを再起動しても設定が永続するようにするには、その設定を.vimrcまたは.gvimrc +ファイルに追加します。":mkvimrc"コマンドを使うと現在の設定をもとにvimrcファイ +ルを生成することもできます。 + +さらなる情報については以下を参照してください。 > + + :help save-settings + :help vimrc + :help gvimrc + :help vimrc-intro + :help :mkvimrc + :help initialization +< + *faq-19.15* +19.15. なぜエスケープキーを押すと約1秒後にビープが鳴る(画面がフラッシュする)の + ですか？ + +これは通常の動作です。画面がフラッシュするのなら、ビジュアルベルが発生していま +す。そうでなければビープが鳴ります。 + +Vimは普通のエスケープとカーソルキーのシーケンスなどを区別するために、タイムア +ウトを必要とします。ノーマルモードでキーを押すと(挿入モードでさえも)、そしてそ +のキーがマッピングの始まりであると、Vimはマッピングの残りのシーケンスが後に続 +くがどうかを見るために一定時間待ちます。もしタイムアウトする前にマッピングシー +ケンスが最後まで入力されればそのキーシーケンスのマッピングが発動します。もし +マッピングを中断すれば、そのキーに割り当てられた普通の動作を実行します。 + +例えば、":imap vvv Vim is great!!"と定義されたマッピングがあるとし、"vvv"をす +ばやく入力するとします。すると"Vim is great!!"がテキストに挿入されます。 +しかし"vv v"と入力すると、それがテキストに挿入されます。これは"vvv"をとても遅 +く入力したときも同じになります。ここで"とても遅く"とはタイムアウトオプションで +設定された値よりも長いという意味です。タイムアウトオプションを大きな値に設定す +ると、遅い回線上でファンクションキーを使うときに現れる問題を解決することができ +ます。 + +さらなる情報については以下を参照してください。 > + + :help ttimeout +< + *faq-19.16* +19.16. 'c'と's'を使ったときに変更する文字を削除するのでなく'$'を表示するように + するには？ + +'c'と's'で変更する文字を削除するのでなく'$'を表示するようにするには、 +'cpoptions'にフラグ$を追加します: > + + :set cpoptions+=$ +< +さらなる情報については以下を参照してください。 > + + :help 'cpoptions' +< + *faq-19.17* +19.17. 1回の":set"コマンドでオプションから複数のフラグを除去するには？ + +1回の":set"コマンドでオプションから複数のフラグを除去するには、それらのフラグ +がオプション中に現れるのと正確に同じ順序でフラグを指定します。例えば、次のコマ +ンドで'formatoptions'からフラグ't'と'n'を除去しようとしたとします: > + + :set formatoptions-=tn +< +すると、'formatoptions'がこれらのフラグをこの'tn'という順序で保持していた場合 +のみ、フラグ't'と'n'が除去されます。そうでなければフラグは除去されません。 +この問題を避けるには、フラグを1つ1つ除去します: > + + :set formatoptions-=t formatoptions-=n +< +さらなる情報については以下を参照してください。 > + + :help :set-= +< + +============================================================================= + *faq-20* +SECTION 20 - キーマップ + + *faq-20.1* +20.1. キーがどうマップされているかを知るには？ + +キーがどうマップされているかを知るには、次のコマンドを使うことができます: > + + :map + :map! +< +また、特定のモードでのマッピングを確認するには":cmap", ":nmap", ":vmap", +":imap", ":omap"などのコマンドを使うことができます。 + +さらなる情報については以下を参照してください。 > + + :help map-listing + :help map-overview +< + *faq-20.2* +20.2. ユーザー定義のキーマッピングをリストするには？ + +ユーザー定義のキーマッピングをリストするにはこうします: > + + :map +< +さらなる情報については以下を参照してください。 > + + :help map-listing +< + *faq-20.3* +20.3. キーマップを解除するには？ + +キーマップを解除するには":unmap"を使います: > + + :unmap + :unmap! +< +モード指定のマッピングには、":nunmap/:vunmap/:ounmap/:iunmap/:lunmap/:cunmap" +のどれかを使います。 + +次のコマンドではバッファローカルなマップを解除できません: > + + :unmap +< +バッファローカルなキーマップを解除するには、キーワードを使わなければ +なりません: > + + :unmap + :unmap! +< +さらなる情報については以下を参照してください。 > + + :help :unmap + :help map-modes + :help map-local + :help 'mapleader' +< + *faq-20.4* +20.4. キーへマッピングができません。なにがまずいのですか？ + +最初にそのキーがVimが渡っているかどうか確認してください。挿入モードで CTRL-Vに +続けてそのキーを押してください。そのキーに対応するキーコードが表示されるでしょ +う。ここでそのキーコードが表示されたら、以下のコマンドでそのキーに対するマッピ +ングを作成することができます: > + + :map +< +さらなる情報については以下を参照してください。 > + + :help map-keys-fails + :help :map-special-keys + :help key-codes +< + *faq-20.5* +20.5. テンキーにマップするには？ + +最初にテンキーのキーがVimに渡っているかどうかを確認してください。そして次の +コマンドでテンキーのキーに対してマップすることができます: > + + :map +< +ここでにはkHome, kEnd, kPageUp, kPageDown, kPlus, kMinus, +kDivide, kMultiply, kEnterなどが使えます。 + +さらなる情報については以下を参照してください。 > + + :help key-codes + :help terminal-options +< + *faq-20.6* +20.6. ビジュアルモードでのみ機能するマッピングを作成するには？ + +特定のモード(ノーマル、コマンド、挿入、ビジュアル等)でのみ機能するマッピングを +作成することができます。ビジュアルモードでのみ機能するマッピングを作るには、 +":vmap"を使います: > + + :vmap +< +さらなる情報については以下を参照してください。 > + + :help :vmap + :help map-modes + :help 40.1 +< + *faq-20.7* +20.7. Vimスクリプト中で、すでに使われているキーと衝突しないようにどのキーを + 使うべきかを知るには？ + +Vimはキーボードのほとんどのキーを使います。mapにプリフィックスを使うと +Vimのキーと重ならないようにキーを定義することができます。例: > + + :map S s + :map j j + :map k k +< +ここでデフォルトのはバックスラッシュ(\)で置き換えられます。そのため +ユーザーはこれらのマッピングを発動させるのに > + \s + \j + \k +< +を押すことになります。マップリーダーを好きな物に変えることができます: > + + :let mapleader = "," +< +プラグインなどのスクリプトを書くときは、いつも以上に :map でなく :noremap を使 +い、ユーザー定義マッピングの副作用を避けることが推奨されます。 + +さらなる情報については以下を参照してください。 > + + :help + :help + :help write-plugin +< + *faq-20.8* +20.8. エスケープキーにマップするには？ + +":map"コマンドでエスケープキーを他のキーにマップすることができます。例えば、次 +のコマンドはエスケープキーをCTRL-Oにマップします。 > + + :map +< + *faq-20.9* +20.9. あるキーをなにもしないようにマップするには？ + +キーをにマップすると、そのキーを押したときに何も起こらないようにすること +ができます。例えば、次のマッピングでが押されたとき何もしないようにすること +ができます。 > + + :map + :map! +< +さらなる情報については以下を参照してください。 > + + :help + :help :map + :help :map! + :help map-modes +< + *faq-20.10* +20.10. Tabキーでテキストのブロックをインデントし、Shift-Tabでテキストのブロッ + クをアンインデントするようにしたいです。このようなマップを作るには？ + この挙動はtextpadやVisual Studioなどに似ています。 + +以下のマッピングを使ってください: > + + :inoremap + :nnoremap >> + :nnoremap + :vnoremap > + :vnoremap +< +注意: のマッピングはVimが正しいキーシーケンスを受け取るときのみ機能しま +す。これはGUIのVimの場合はたいてい当てはまります。 + +さらなる情報については以下を参照してください。 > + + :help :inoremap + :help :nnoremap + :help :vnoremap + :help + :help i_CTRL-O + :help >> + :help << + :help +< + *faq-20.11* +20.11. 私のマッピングにおいてのような特殊文字が認識されません。 + 特殊文字を認識するように設定するには？ + +'cpoptions'の値を確認してください: > + + :set cpoptions? +< +このオプションがフラグ'<'を含んでいると、マッピングにおいて特殊文字が認識され +ません。'cpoptions'からフラグ'<'を除去してください: > + + :set cpo-=< +< +また、'compatible'の値も確認してください: > + + :se compatible? +< +'compatible'はオフになっていなければなりません: > + + :se nocompatible +< +さらなる情報については以下を参照してください。 > + + :help 'cpoptions' + :help 'compatible' +< + *faq-20.12* +20.12. マップ中で'|'を使って複数のコマンドを区切るには？ + +マップ中で'|'を使うにはバックスラッシュ(\)で'|'をエスケープします。 > + + :map _l :!ls \| more +< +次のコマンドも試してみてください: > + + :map _l :!ls more +< +他の方法もあります。 + +さらなる情報については以下を参照してください。 > + + :help map_bar +< + *faq-20.13* +20.13. その最後が他のマッピング/短縮入力の始まりとなっているマッピング/短縮 + 入力があります。最初のものを入力したとき、2番目のが展開しないようにする + には？ + +":map lhs rhs"でなく":noremap lhs rhs"を使ってください。短縮入力については +"noreabbrev lhs rhs"です。プリフィックス"nore"はマッピングや短縮入力が再帰的に +展開されるのを防ぎます。 + +さらなる情報については以下を参照してください。 > + + :help :noremap + :help :noreabbrev +< + *faq-20.14* +20.14. ときどきキーが処理されるのに1秒程度かかるのはなぜですか？ + +そのキーに対してマッピングが定義されていないことを次のコマンドで確かめてくださ +い: > + + :map +< +もしこのキーにマッピングが定義されていて、マッピングが1文字以上を含んでいるな +ら、Vimはそれがマッピングの一部かどうかを判定するために、次の文字が押されるの +を待ちます。例えば、"ab"というマッピングをしているとします。そして"a"を押すと +Vimは次のキーが押されるのを待ちます。次のキーが"b"ならvimはこのマッピングを実 +行します。そうでなければvimは"a"とその次のキーを通常どおりに処理します。 +'timeout'がオンになっていると(それがデフォルトです)、Vimは'timeoutlen'で指定さ +れた時間(デフォルトは1秒)だけ待ったのちタイムアウトします。 + +さらなる情報については以下を参照してください。 > + + :help map-typing + :help 'timeoutlen' + :help 'ttimeoutlen' + :help 'timeout' + :help 'ttimeout' + :help vt100-cursor-keys + :help slow-fast-terminal +< + *faq-20.15* +20.15. ビジュアル選択したテキストに対して外部コマンドを実行するマッピングを作 + るには？ + +":vmap"コマンドでビジュアルモードでのマッピングを作ることができます。マップの +コマンドシーケンスの中で、最初にそのテキストをヤンクしなければなりません。ヤン +クされたテキストはレジスタ"で取得できます。そしてこのレジスタの中身を使って外 +部コマンドを実行することができます。例えば、外部コマンド"perldoc"を選択された +テキストに対して実行するには、次のマッピングを使います: > + + :vmap y:!exec "!perldoc '" . @" . "'" +< +選択されたテキストでなく、ビジュアルモード中でマッピングを実行したいなら次のコ +マンドを使います: > + + :vmap :!perldoc +< +このマッピングは選択されたテキストでなく、カーソル下の単語を使います。外部コマ +ンド"perldoc"を実行する前にとしてることに注意してください。このはビ +ジュアルモードで選択されたテキストの範囲がコマンドラインに表示されているのを消 +すために使われています。を使って選択範囲を消さないと、外部コマンドの出力 +が選択されたテキストを置き換えてしまいます。 + +さらなる情報については以下を参照してください。 > + + :help :vmap + :help quote_quote + :help let-register + :help c_CTRL-U + :help :!cmd +< + *faq-20.16* +20.16. キーの機能を保ったままCtrl-Iにマッピングするには？ + +Ctrl-Iとは同じキーコードを生成します。そのため、VimはCtrl-Iとを区別 +することができません。Ctrl-Iにマッピングすると、キーにも同様にマッピング +されます(逆も同様です)。これと同じ制限がCtrl-[とにも適用されます。 + +さらなる情報については以下を参照してください。 > + + :help keycodes +< + +============================================================================= + *faq-21* +SECTION 21 - 短縮入力 + + *faq-21.1* +21.1. スペリングを間違えた単語を自動的に修正するには？ + +短縮入力を使ってスペリングを間違えた単語を自動的に修正することができます。例え +ば、次の短縮入力で"teh"を"the"に修正することができます: > + + :abbreviate teh the +< +挿入モード、置換モード、コマンドラインモードで短縮入力が利用できます。 + +さらなる情報については以下を参照してください。 > + + :help 24.7 + :help abbreviations + :help Q_ab +< + *faq-21.2* +21.2. 複数行の短縮入力を作るには？ + +キーコード""を埋め込めば、複数行の短縮入力を作ることができます: > + + iabbrev #c ---------------- Date:----------- +< +この短縮入力によって、#cとタイプすると次のテキストに展開されます: + +-------------- +-- Date: +-- +--------- + +さらなる情報については以下を参照してください。 > + + :help abbreviations +< + *faq-21.3* +21.3. 短縮入力が展開されたとき、展開されたテキストの末尾に余計なスペースが入っ + てしまいます。これを防ぐには？ + +短縮入力をCTRL-]を押して展開すれば、展開されたテキストの末尾に余計なスペースが +入るのを防ぐことができます。 + +別の方法としては、次の関数とコマンドを使うことができます: + +function! Eatchar(pat) + let c = nr2char(getchar()) + return (c =~ a:pat) ? '' : c +endfunction +command! -nargs=+ Iabbr execute "iabbr" . "=Eatchar('\\s')" + +こうしておいて、組み込みの"iabbrev"の代わりに新しいコマンド"Iabbr"を使って短縮 +入力を定義します。このコマンドを使うと、テキストを展開した後、次に入力された文 +字が捨てられます。 + +さらなる情報については以下を参照してください。 > + + :help abbreviations +< + *faq-21.4* +21.4. 現在の日付・時刻を挿入するには？ + +strftime()を使えば現在の日付・時刻のタイムスタンプを挿入することができます。例 +えば、次の短縮入力を使います: > + + iabbrev dts =strftime("%y/%m/%d %H:%M") +< +この短縮入力を使うと、挿入モードでdtsと入力するとそれがタイムスタンプに展開さ +れます。 + +この短縮入力の別の形を以下に列挙します: > + + iabbrev mdyl =strftime("%a %d %b %Y") + iabbrev mdys =strftime("%y%m%d") + iabbrev mdyc =strftime("%c") + iabbrev hml =strftime("%d/%m/%y %H:%M:%S") + iabbrev hms =strftime("%H:%M:%S") +< +さらなる情報については以下を参照してください。 > + + :help strftime() + :help i_CTRL-R +< + *faq-21.5* +21.5. 挿入モードで短縮入力が展開されるのを防ぐには？ + +短縮された単語の後にCTRL-Vを押してから次の文字を入力すれば、それが展開されるの +を防ぐことができます。 + +さらなる情報については以下を参照してください。 > + + :help abbreviations +< + +============================================================================= + *faq-22* +SECTION 22 - レコーディングと繰り返し + + *faq-22.1* +22.1. 編集操作(挿入、削除、ペースト等)を繰り返すには？ + +'.'を使えば最後の編集操作を繰り返すことができます。これは挿入、削除、変更、 +ペーストなどの単純な変更を繰り返します。 + +さらなる情報については以下を参照してください。 > + + :help 04.3 + :help single-repeat + :help Q_re +< + + *faq-22.2* +22.2. キーシーケンスを記録し、繰り返すには？ + +ノーマルモードで'q'を使うとキーシーケンスを記録し、それをレジスタに保存するこ +とができます。例えば、ノーマルモードでqを押し、続けてレジスタ名{0-9a-bA-Z"}を +押すとレコーディングが始まります。レコーディングを終了するには、もう一度qを押 +します。記録されたキーシーケンスを再生するには、@に続けてレジスタ名を押しま +す。例. @a。 + +別の方法としてはコマンドライン引数"-w"をつけてVimを起動します。 > + + $ vim -w +< +するとVimはこのセッション中にタイプされた文字全てを指定されたファイル +"file_name"に記録します。コマンドライン引数"-s"でそのファイルを指定すると、そ +れを再生することができます: > + + $ vim -s +< +さらなる情報については以下を参照してください。 > + + :help 10.1 + :help recording + :help -w + :help -s +< + *faq-22.3* +22.3. 記録したキーシーケンスを編集するには？ + +記録したキーシーケンスはレジスタに保存されます。そのレジスタの中身をバッファに +ペーストし、そのテキストを編集して最後レジスタにヤンクすることができます。 +また、":let"でもレジスタを修正することができます。例: > + + :let @a = "iHello World\" +< +さらなる情報については以下を参照してください。 > + + :help recording + :help 10.1 + :help let-register + :help <> + :help 'cpoptions' +< + *faq-22.4* +22.4. 記録したキーシーケンスをファイルに保存するには？ + +記録されたキーシーケンスはレジスタに保存されます。そのレジスタの中身をバッファ +にペーストすることができます。そしてそのバッファをファイルに保存します。ペース +トしたテキストを修正して再度レジスタにヤンクして記録したキーシーケンスを修正す +ることもできます。例えば、qa ..... qとしてキーシーケンスを記録したとします。 +記録したキーシーケンスはレジスタ'a'に保存されます。"apとするとレジスタ'a'の中 +身をペーストすることができます。 + +さらなる情報については以下を参照してください。 > + + :help recording + :help 10.1 +< + *faq-22.5* +22.5. レジスタ0にキーシーケンスを保存しています(つまり q0 .... q)。 + 記録したキーシーケンスの中でテキストをヤンクしています。一度そのキーシー + ケンスを再生すると、もうそれを再現することができません。 + +レジスタ0は最後のヤンクしたテキストを保持します。記録したキーシーケンス中でヤ +ンクが行われたとき、レジスタ0はそのテキストで上書きされます。そのためレジスタ +0に記録したキーシーケンスは失われます。何か他のレジスタを使わねばなりません。 + +さらなる情報については以下を参照してください。 > + + :help registers +< + +============================================================================= + *faq-23* +SECTION 23 - 自動コマンド + + *faq-23.1* +23.1. 読み込み専用ファイルを修正しようとしたときにコマンドを実行するには？ + +自動コマンドFileChangedROを使えば、読み込み専用ファイルが修正されたときにコマ +ンドを実行できます。例えば、このイベントを使って読み込み専用ファイルをチェック +アウトすることができます: > + + :autocmd FileChangedRO * call MyCheckoutFunction() +< +さらなる情報については以下を参照してください。 > + + :help FileChangedRO +< + *faq-23.2* +23.2. あるバッファに入るときに毎回コマンドを実行するには？ + +自動コマンドイベントBufEnterを使うと、あるバッファに入る度にコマンドを実行する +ことができます。例: > + + :autocmd BufEnter *.c set formatoptions=croqt +< +さらなる情報については以下を参照してください。 > + + :help BufEnter +< + + *faq-23.3* +23.3. あるウィンドウに入るときに毎回コマンドを実行するには？ + +自動コマンドイベントWinEnterを使えば、あるウィンドウに入る度にコマンドを実行す +ることができます。例: > + + :autocmd WinEnter *.c call MyFunction() +< +さらなる情報については以下を参照してください。 > + + :help WinEnter +< + *faq-23.4* +23.4. autocmd中でその自動コマンドが実行されているファイルの名前やバッファ番号 + を知るには？ + +特殊な単語またはを使えばautocmd中でその自動コマンドが実行されてい +るファイル名やバッファ番号を取得することができます。 + +さらなる情報については以下を参照してください。 > + + :help : + :help : + :help : +< + *faq-23.5* +23.5. Vimがフォーカスを失ったとき、変更されたバッファ全てを自動的に保存する + には？ + +FocusLostイベントに対して自動コマンドを定義すれば、Vimがフォーカスを失う度に変 +更されたバッファ全てを保存することができます: > + + :autocmd FocusLost * wall +< +さらなる情報については以下を参照してください。 > + + :help FocusLost + :help :wall +< + *faq-23.6* +23.6. Vimを終了するときにクリーンアップ用の関数を実行するには？ + +VimLeaveイベントを使えば、Vimが終了する直前に関数を実行することができます。 +例 > + + :autocmd VimLeave * call MyCleanupFunction() +< +さらなる情報については以下を参照してください。 > + + :help VimLeave +< + +============================================================================= + *faq-24* +SECTION 24 - 構文強調 + + *faq-24.1* +24.1. 構文強調をオン・オフにするには？ + +デフォルトでは構文強調はオフにされています。構文強調をオンにするには次のコマン +ドのどれかを使います: > + + :syntax enable +< +または > + + :syntax on +< +構文強調を無効にするには、次のコマンドを使います: > + + :syntax off +< +さらなる情報については以下を参照してください。 > + + :help 06.1 + :help 06.4 + :help :syntax-enable + :help :syntax-on + :help :syn-clear +< + *faq-24.2* +24.2. 背景色と文字色を変えるには？ + +背景色と文字色には強調グループ"Normal"が使われます。文字色・背景色を変える +には、強調グループ"Normal"を変更しなければなりません。例えば、背景色を青に、 +文字色を白にするには、次のようにします: > + + :highlight Normal ctermbg=blue ctermfg=white guibg=blue guifg=white +< +もしMotifまたはAthena版のGVimを使っているなら、.Xdefaultsファイル中の文字色と +背景色のリソース名を変更してもよいでしょう: > + + Vim.foreground: Black + Vim.backround: Wheat + {訳注: Vim.background の間違い} +< +また、コマンドライン引数"-foreground"と"-background"を指定して文字色と背景色 +を指定することもできます。これらの引数はMotifとAthena版でだけサポートされてい +ます: > + + $ gvim -foreground Black -background Wheat +< +さらなる情報については以下を参照してください。 > + + :help :highlight + :help .Xdefaults + :help -gui +< + *faq-24.3* +24.3. 暗い/明るい背景色に合うように色を変えるには？ + +'background'を'dark'か'light'に変えれば、それぞれ暗い/明るい背景に合うように +強調色を変えることができます: > + + :set background=dark +< +さらなる情報については以下を参照してください。 > + + :help 'background' + :help 6.2 +< + *faq-24.4* +24.4. ":set number"をしたときに表示される行番号の色を変えるには？ + +行番号の表示には強調グループLineNrが使われます。現在設定されている色を表示する +にはこうします > + + :hi LineNr +< +この色を変えるには、強調グループLineNrを変更します。例: > + + :hi linenr guifg=red guibg=black +< +こうするとGVimでは黒い背景の上に赤い数字で表示されるようになります。 + +さらなる情報については以下を参照してください。 > + + :help :highlight +< + *faq-24.5* +24.5. ビジュアルモードで選択された範囲の背景色を変えるには？ + +強調グループ'Visual'を変更すれば、ビジュアルモードで選択された範囲の色を変える +ことができます: > + + :highlight Visual guibg=red +< +さらなる情報については以下を参照してください。 > + + :help :highlight + :help hl-Visual +< + *faq-24.6* +24.6. オプション'list'で表示した特殊文字(タブ、行末の空白、行末など)に色をつけ + るには？ + +強調グループ"NonText"と"SpecialKey"を変えれば'list'によって表示された特殊文字 +に色をつけることができます: > + + :highlight NonText guibg=red + :highlight SpecialKey guibg=green +< +オプション'listchars'中の"eol", "extend", "precedes"に対しては"NonText"が使わ +れます。"tab"と"trail"には"SpecialKey"が使われます。 + +さらなる情報については以下を参照してください。 > + + :help 'listchars' + :help hl-NonText + :help hl-SpecialKey +< + *faq-24.7* +24.7. 毎回同じカラースキームを使うように.vimrc/.gvimrcで設定するには？ + +.vimrcや.gvimrc中で":colorscheme"を使えばカラースキームを指定することができま +す: > + + colorschme evening +< +さらなる情報については以下を参照してください。 > + + :help :colorscheme +< + *faq-24.8* +24.8. 正しく構文強調されません。ファイルの一部が強調されなかったり、間違って強 + 調されてしまいます。 + +Vimは構文強調する際にファイル全体をパースすることはしません。表示してされてい +る場所からパースが始まります。これによって多大な時間が節約できますが、ときどき +間違って色づけされることもあります。これを修正する単純な方法は、CTRL-Lを押して +画面を再描画することです。または少し上にスクロールしてから下に戻ってきます。 +このコマンドを使うこともできます: > + + :syntax sync fromstart +< +注意: これを実行すとスクリーンの描画が相当遅くなります。 + +さらなる情報については以下を参照してください。 > + + :help :syn-sync + :help :syn-sync-first +< + *faq-24.9* +24.9. 対応する括弧を強調する組み込みの関数はありますか？ + +ありません。Vimには対応する括弧を強調する機能はありません。Charles Campbellが +作ったプラグインを試してみてもよいでしょう: > + + http://vim.sourceforge.net/tips/tip.php?tip_id=177 +< +対応する括弧には'%'キーを使えばジャンプできます。挿入モードで一時的に対応する +括弧にジャンプするには'showmatch'をセットします。 + +{訳注: Vim7からはmatchparen.vimが付属し、カーソルが括弧の上に乗ると、自動的に + 対応する括弧が強調されるようになった。 + :h matchparen} + +さらなる情報については以下を参照してください。 > + + :help % + :help 'showmatch' + :help 'matchtime' + :help 'matchpairs' +< + *faq-24.10* +24.10. Cのコメントの構文強調をオフにするには？ + +次のコマンドを使うとCのコメントの構文強調をオフにすることができます: > + + :highlight clear comment +< +さらなる情報については以下を参照してください。 > + + :help c-syntax +< + *faq-24.11* +24.11. Vimに付属する標準の構文ファイルに私自身の構文拡張を加えるには？ + +あなたの拡張を追加する場合、Vimに付属の構文ファイルそのものを修正するべきでは +ありません。次のVimのバージョンをインストールしたとき、その変更が失われてしま +います。代わりに、~/.vim/after/syntaxディレクトリに元の構文ファイルと同名の +ファイルを作り、そこにあなたの拡張を加えるべきです。 + +さらなる情報については以下を参照してください。 > + + :help mysyntaxfile-add + :help 'runtimepath' +< + *faq-24.12* +24.12. Vimに付属の標準の構文ファイルを独自の構文ファイルで置き換えるには？ + +元の構文ファイルと同名のファイルを作成し、ランタイムの構文ディレクトリに置けば +標準の構文ファイルに置き換えることができます。例えば、Unixシステムにおいて構文 +ファイルc.vimを置き換えるには、新しいc.vimを~/.vim/syntaxに置きます。 +MS-Windowsシステムにおいては新しい構文ファイルを$HOME/vimfiles/syntaxまたは +$VIM/vimfiles/syntaxディレクトリに置きます。 + +さらなる情報については以下を参照してください。 > + + :help mysyntaxfile-replace + :help 44.11 + :help mysyntaxfile +< + *faq-24.13* +24.13. 特定の桁以降の全ての文字を強調するには？ + +":match"を使えば特定の桁以降の全ての文字を強調することができます: > + + :match Todo '\%>75v.\+' +< +これは75桁目以降の全ての文字を強調します。 + +さらなる情報については以下を参照してください。 > + + :help :match + :help /\%v + :help /\+ + :help /. +< + *faq-24.14* +24.14. ソースファイル(.c, .hなど)を構文強調つきでHTMLファイルに変換するには？ + +2html.vimを使えばソースファイルを構文強調つきでHTMLファイルに変換することがで +きます。次のコマンドを実行してください: > + + :runtime! syntax/2html.vim +< +さらなる情報については以下を参照してください。 > + + :help convert-to-HTML +< + *faq-24.15* +24.15. 現在の強調グループ定義を全て表示するには？ + +現在の強調グループ定義を全て表示するには":highlight"を(引数無しで)実行します。 + +さらなる情報については以下を参照してください。 > + + :help :highlight +< + +============================================================================= + *faq-25* +SECTION 25 - VIMスクリプトを書く + + *faq-25.1* +25.1. 読み込まれているスクリプトを全て表示するには？ + +":scriptnames"を使えば読み込まれているスクリプトを全て表示することができ +ます: > + + :scriptnames +< +さらなる情報については以下を参照してください。 > + + :help :scriptnames +< + *faq-25.2* +25.2. Vimスクリプトをデバッグするには？ + +VimはVimプラグインやスクリプトをデバッグするための原始的なデバッガを備えていま +す。このデバッガを使うとブレークポイントを設定したり、プラグインの関数をステッ +プ実行できます。 + +さらなる情報については以下を参照してください。 > + + :help debug-scripts + :help -D +< + *faq-25.3* +25.3. あるオプションを設定したスクリプト/プラグインを探すには？ + +":verbose"を使えば最後にあるオプションを設定したプラグイン/スクリプトを探すこ +とができます。例: > + + :verbose set textwidth? +< +さらなる情報については以下を参照してください。 > + + :help :set-verbose + :help :verbose +< + *faq-25.4* +25.4. (おそらくスクリプトを実行中に)エラーやメッセージが出るのですが、すぐに消 + えてしまいます。このメッセージをもう一度表示するには？ + +":messages"を使えば以前のメッセージを表示することができます。 > + + :messages +< +さらなる情報については以下を参照してください。 > + + :help :messages + :help :echoerr + :help :echomsg + :help message-history +< + *faq-25.5* +25.5. プラグイン固有の情報を保存し、Vimを再起動したときそれを復元するには？ + +Vimは大文字で始まり、小文字を含まないグローバル変数を保存し、復元します。この +機能を有効化するには、'viminfo'がフラグ'!'を含んでいなければなりません。Vimは +これらの変数をviminfoファイルに保存します。 + +さらなる情報については以下を参照してください。 > + + :help 'viminfo' + :help viminfo-file + :help variables +< + *faq-25.6* +25.6. 関数の中から挿入モードを開始するには？ + +":startinsert"を使えば関数の中から挿入モードを開始することができます。 + +さらなる情報については以下を参照してください。 > + + :help :startinsert +< + *faq-25.7* +25.7. 関数の中でカーソル位置を動かすには？ + +関数cursor()を使えばカーソルを動かすことができます。 > + + call cursor(lnum, col) +< +次のコマンドを使ってもカーソル位置を変えることができます: > + + exe "normal! " . lnum . "G" . col . "|" +< +さらなる情報については以下を参照してください。 > + + :help cursor() + :help bar +< + *faq-25.8* +25.8. .vimrcファイルの中で環境変数の値をチェックするには？ + +Vimスクリプト/関数の中で環境変数を使うには、環境変数名の前に'$'をつけます: > + + if $EDITOR == 'vi' + endif +< +さらなる情報については以下を参照してください。 > + + :help expr-env +< + *faq-25.9* +25.9. 環境変数が定義されているかどうかをチェックするには？ + +exists()を使えば環境変数の存在をチェックすることができます。 > + + if exists("$MY_ENV_VAR") + endif +< +さらなる情報については以下を参照してください。 > + + :help exists() + :help expr-env +< + *faq-25.10* +25.10. Vimの組み込み関数を呼ぶには？ + +":call"コマンドを使えばVimの組み込み関数を呼び出すことができます: > + + :call cursor(10,20) +< +":echo"を使えば関数の戻り値を表示することができます: > + + :echo char2nr('a') +< +":let"を使えば関数の戻り値を変数に代入することができます: > + + :let a = getline('.') +< +関数の戻り値をレジスタに保存するには、次のようにします: > + + :let @a = system('ls') +< +上のコマンドは'ls'コマンドの戻り値をレジスタ'a'に保存します。 + +{訳注: 上のコマンドは外部プログラム'ls'の標準出力への出力をレジスタに保存す + る。} + +さらなる情報については以下を参照してください。 > + + :help :call + :help :echo + :help :let + :help :let-register + :help user-functions + :help usr_41.txt +< + *faq-25.11* +25.11. Vimスクリプト中でノーマルコマンドを使っています。そのコマンドに対して + ユーザー定義のマッピングが働くのを防ぎ、そのノーマルモードコマンドが + Vim の標準の機能を果たすようにするには？ + +スクリプト中でノーマルモードコマンドを使うときは"normal!"を使えばよいでし +ょう。これはノーマルモードコマンドの標準の機能を使い、ユーザー定義マッピングは +作用しません。 + +さらなる情報については以下を参照してください。 > + + :help :normal +< + *faq-25.12* +25.12. ビジュアルモードで現在選択されているテキストを変数やレジスタに入れるに + は？ + +ビジュアルモードで選択されているテキストを変数に取得するには、そのテキストをレ +ジスタにヤンクし、その後そのレジスタの中身を変数に代入します: > + + :normal! gvy + :let myvar = @" +< +上のコマンドはビジュアルモードで選択されたテキストを変数"myvar"にコピーします。 + +次のコマンドを使うこともできます: > + + :normal! gv"*y +< +上のコマンドは、gvで最後にビジュアルモードで選択されたテキストを選択し、コマン +ドの残りの部分で選択されたテキストをレジスタ*(クリップボード)にコピーします。 +別の方法としては、'guioptions'にフラグ'a'をセットして、選択されたテキストを自 +動的にレジスタ*に入れるようにしてもよいでしょう。 +これをマップの一部分として実行するには、以下のようなコマンドを使います: > + + :vmap "*y:call ... +< +さらなる情報については以下を参照してください。 > + + :help gv + :help :normal + :help let-@ + :help quotestar + :help clipboard + :help registers +< + *faq-25.13* +25.13. 変数'myvar'にテキストが入っています。この変数を":s"中で使って'mytext' + というテキストを置換したいのですが、どうすればいいですか？ + +"execute"コマンドを使えば変数を評価することができます: > + + :execute '%s/mytext/' . myvar . '/' +< +さらなる情報については以下を参照してください。 > + + :help :execute +< +置換コマンド中で変数を評価するには"\="を使うこともできます: > + + :%s/mytext/\=myvar/ +< +さらなる情報については以下を参照してください。 > + + :help sub-replace-special +< + *faq-25.14* +25.14. 変数"bno"がバッファ番号を保持しています。この変数を使って対応するバッ + ファを開くには？ + +":buffer"は変数名を受け付けません。このコマンドはバッファ番号かバッファ名のみ +を受け付けます。変数を評価して対応する値にするために":execute"を使わねばなりま +せん。例: > + + :execute "buffer " . bno +< +さらなる情報については以下を参照してください。 > + + :help :execute +< + *faq-25.15* +25.15. オプションの値を変数に保存するには？ + +オプション名の前に'&'をつけると、"let"でそのオプションの値を変数に代入すること +ができます。例えば、オプション'textwidth'の値を変数"old_tw"に保存するには次の +コマンドを使います: > + + :let old_tw = &tw +< +その逆、つまり'textwidth'に"old_tw"に保存された値をセットするには次のコマンド +を使います: > + + :let &tw = old_tw +< +さらなる情報については以下を参照してください。 > + + :help expr-option + :help let-option +< + *faq-25.16* +25.16. 関数の中でテキストをコピーし、バッファに挿入しました。関数の中でそのテ + キストをインデントするには？ + +次のコマンドを使えば、たった今挿入したテキストを整形することができます: > + + :normal '[='] +< +さらなる情報については以下を参照してください。 > + + :help '[ + :help '] + :help = + :help :normal +< + *faq-25.17* +25.17. Vimスクリプト中でカーソル下の文字を取得するには？ + +getline()と文字列のインデックス[]を使います: > + + :echo getline(".")[col(".") - 1] +< +上のコマンドにおいてgetline(".")は現在行のテキストを返します。文字列のインデッ +クスは0から始まり、"string[index]" という記法で文字列中からインデックスを指定 +して1つの文字を取得できます。col(".")はカーソル位置の桁を返します。ここでは文 +字列中の目的の文字を取得するために調整されています。 + +別の方法としては、以下の一連のコマンドによってもカーソル下の文字を取得でき +ます: > + + normal! vy + let ch=@" +< +注意: 上のコマンドはマーク '< と '> を変更します。 + +さらなる情報については以下を参照してください。 > + + :help getline() + :help col() + :help expr-[] +< + *faq-25.18* +25.18. 拡張子を除いたカレントファイル名を取得するには？ + +拡張子を除いたカレントファイル名を取得するにはこうします: > + + :echo expand("%:r") +< +いくつかのコマンドでは、ファイル名の修飾子を直接使うことができます: > + + :cd %:p:h + :!gcc -o %:r.o % +< +さらなる情報については以下を参照してください。 > + + :help filename-modifiers + :help expand() + :help cmdline-special + :help fnamemodify() +< + *faq-25.19* +25.19. カレントファイルのベース名(basename)を取得するには？ + +ファイル名修飾子 :t を使えばカレントファイルのベース名(basename)を取得すること +ができます: > + + :echo expand("%:t") +< +さらなる情報については以下を参照してください。 > + + :help filename-modifiers +< + *faq-25.20* +25.20. 関数の結果をカレントバッファに挿入するには？ + +挿入モードにおいて次のコマンドで関数の戻り値を挿入することができます: > + + =MyFunc() +< +注意: これは関数の戻り値を挿入するだけです。 + +さらなる情報については以下を参照してください > + :help i_CTRL-R + :help i_CTRL-R_CTRL-R + :help i_CTRL-R_CTRL-O + :help expression +< + *faq-25.21* +25.21. 関数の中で外部プログラムを呼ぶには？ + +関数の中で外部プログラムを呼ぶにはいくつかの方法があります。組み込み関数 +system()を使うと、外部コマンドを起動し、出力を取得することができます: > + + :let output = system("ls") +< +また、exコマンド"!"を使って外部コマンドを実行することもできます。 + +さらなる情報については以下を参照してください。 > + + :help system() + :help :! + :help 10.9 +< + *faq-25.22* +25.22. ":!"で実行したプログラムが返すステータス値を取得するには？ + +組み込み変数v:shell_errorを使えば最後に実行したシェルコマンドが返すステータス +値を取得することができます。 + +さらなる情報については以下を参照してください。 > + + :help v:shell_error +< + *faq-25.23* +25.23. カレントバッファが変更されているかどうかを知るには？ + +オプション'modified'の値を見ればカレントバッファが変更されているかどうかを知る +ことができます: > + + :set modified? +< +スクリプト中でも'modified'の値を知ることができます: > + + if &modified + echo "File is modified" + endif +< +さらなる情報については以下を参照してください。 > + + :help 'modified' +< + *faq-25.24* +25.24. スクリプト中でノーマルコマンドの中に改行文字を使いたいです。改行文字を + 指定するには？ + +":execute"を使えばノーマルモードコマンド中で特殊文字を使うことができます: > + + :execute "normal \" + :execute "normal ixxx\" +< +さらなる情報については以下を参照してください。 > + + :help :execute + :help expr-quote +< + *faq-25.25* +25.25. スクリプト中で長い行を次行に継続するには？ + +スクリプト中で長い行を継続するには、次行の最初にバックスラッシュ("\")をつけま +す。例: > + :set comments=sr:/*,mb:*,el:*/, + \://, + \b:#, + \:%, + \n:>, + \fb:- +< +{訳注: 原文には例が入っていなかったので :help からコピペしてきた。} + +さらなる情報については以下を参照してください。 > + + :help line-continuation +< + *faq-25.26* +25.26. "execute 'echo Myfunc()'"として自作の関数を呼ぼうとすると、カーソルがカ + レントバッファの先頭に移動してしまいます。なぜ？ + +":execute"は引数で指定されたノーマルコマンドを実行します。次のコマンドでは: > + + :execute "echo Myfunc()" +< +"echo Myfunc()"は0を返します。":execute"コマンドはノーマルモードコマンドの"0" +を実行します。これはカーソルをファイルの先頭に移動させます。関数を呼ぶには +":execute"でなく":call"を使ってください: > + + :call Myfunc() +< + +{訳注: このQ&Aは間違っている？ + :executeはexコマンドを実行する。 + 1番目のコマンドはMyfunc()を呼んでその戻り値をechoするはず。} + +さらなる情報については以下を参照してください。 > + + :help :call + :help :execute + :help :echo + :help user-functions + :help 41.5 + :help 41.6 +< + *faq-25.27* +25.27. レジスタの中身を実行するには？ + +レジスタ(例えばレジスタ'a'とする)にVimのコマンドをヤンクしてある場合、そのレジ +スタの中身を次のコマンドで実行することができます: > + + :@a +< +または > + :exe @a +< + +さらなる情報については以下を参照してください。 > + + :help :@ +< + *faq-25.28* +25.28. 関数やマップを呼んだ後に'u'キーを押してアンドゥするとその関数/マップに + よってなされた変更全てをアンドゥします。なぜ？ + +関数やマップを呼ぶと、その関数/マップによってなされた操作は1つの操作として扱 +われます。'u'を押して最後の操作をアンドゥすると、関数/マップによってなされた +変更は全て元に戻ります。 + +さらなる情報については以下を参照してください。 > + + :help undo-redo + :help map-undo +< + *faq-25.29* +25.29. s:つきで定義された関数(スクリプトローカル関数)を別のスクリプト/プラグ + インから呼ぶには？ + +関数名へのプリフィックス s: は関数をスクリプトローカルにするために使われます。 +スクリプトローカル関数はそのスクリプト中からのみ呼ぶことができ、他のスクリプト +からは呼び出せません。他のプラグイン/スクリプトから呼び出せる関数を定義するに +は、s: をつけずに関数を定義します。 + +さらなる情報については以下を参照してください。 > + + :help script-variable + :help script-local + :help :scriptnames +< + *faq-25.30* +25.30. 読み込んだスクリプトをun-sourceするには？言い替えると、スクリプトを読み + 込んだことによって実行されたコマンドを全て戻すには？ + +スクリプトを読み込んだことによって実行されたコマンドを全て戻すことはできませ +ん。 + +さらなる情報については以下を参照してください。 > + + :help :source +< + +============================================================================= + *faq-26* +SECTION 26 - プラグイン + + *faq-26.1* +26.1. ファイル形式ごとに異なるオプションを設定するには？ + +ファイル形式別プラグインを作れば、ファイル形式ごとに異なるオプションを設定する +ことができます。まず最初に次のコマンドでファイル形式別プラグインを有効にしてく +ださい: > + + :filetype plugin on +< +ファイル形式別プラグインは、Vimでその形式のファイルを作成したり開く度に読み込 +まれるVimスクリプトです。例えば、Cプログラム(ファイル形式'c')を編集するとき +は常に'textwidth'を80にするには、次のファイルのどれかを作ります: > + + ~/.vim/ftplugin/c.vim (Unix) + %HOME%\vimfiles\ftplugin\c.vim (Windows) +< +そしてその中に次のテキストを書いておきます: > + + setlocal textwidth=80 +< +自動コマンドを使っても特定のファイル形式を編集するときに特定のオプションを設定 +することができます。例えば、*.txtファイルを編集するときだけ'textwidth'を75に設 +定するには次のコマンドを使います: > + + autocmd BufRead *.txt setlocal textwidth=80 +< +さらなる情報については以下を参照してください。 > + + :help filetype-plugin + :help add-filetype-plugin + :help autocmd + :help 40.3 +< + + *faq-26.2* +26.2. プラグイン/構文ファイル/インデントファイル/カラースキーム/ファイルタイプ + プラグインをダウンロードしました。Vimがこれらのファイルを読み込むように + するには、どこにコピーすればいいですか？ + +ランタイムファイル(プラグイン、構文ファイル、インデントファイル、カラースキー +ム、ファイル形式別プラグインなど)は'runtimepath'で指定されたディレクトリのうち +どれかの下に置きます。'runtimepath'の現在の値を知るには次のコマンドを使います +: > + + :set runtimepath +< +Unixシステムでは、通常これは"$HOME/.vim"ディレクトリになります。MS-Windowsシス +テムでは、通常これは$VIM\vimfilesまたは$HOME\vimfilesディレクトリになります。 +ランタイムファイルはその種類によって、ランタイムディレクトリ下の決まったディレ +クトリに置かねばなりません。そのディレクトリの名前は以下のとおりです: > + + colors/ - カラースキームファイル + compiler/ - コンパイラファイル + doc/ - ドキュメント + ftplugin/ - ファイル形式別プラグイン + indent/ - インデントスクリプト + keymap/ - キーマップファイル + lang/ - メニューの翻訳 + plugin/ - プラグインスクリプト + syntax/ - 構文ファイル + tutor/ - vimtutorのファイル +< +さらなる情報については以下を参照してください。 > + + :help your-runtime-dir + :help 'runtimepath' + :help :runtime +< + *faq-26.3* +26.3. 既存のファイル形式別プラグインを拡張するには？ + +ディレクトリ$VIMRUNTIME/after/ftpluginまたは$VIMRUNTIME/ftpluginの下にファイル +を作ることによって、既存のファイル形式別プラグインを拡張することができます。 +そのファイルの名前は既存のファイル形式別プラグインの名前と同じにすべきです。 +この新しいファイルにあなたの拡張を書き加えます。 + +そのファイルをafter/ftpluginディレクトリに置くと、Vimはまず既存のファイルタイ +ププラグインを読み込み、その後にその新しいファイルを読み込みます。そのファイル +を$VIMRUNTIME/ftpluginディレクトリに置くと、Vimはまずその新しいファイルを読み +込み、その後に既存のファイル形式別プラグインを読み込みます。 + +さらなる情報については以下を参照してください。 > + + :help ftplugin-overrule + :help filetype-plugin + :help add-filetype-plugin + :help 'runtimepath' +< + *faq-26.4* +26.4. プラグインの読み込みをオフにするには？ + +'loadplugins'をオフにすればプラグインを読み込まなくすることができます: > + + :set noloadplugins +< +コマンドライン引数"--noplugin"を指定してもプラグインの読み込みを止めさせること +ができます: > + + $ vim --noplugin +< +さらなる情報については以下を参照してください。 > + + :help 'loadplugins' + :help --noplugin + :help load-plugins +< + *faq-26.5* +26.5. ファイル形式別プラグインの読み込みをオフにするには？ + +デフォルトではvimはファイル形式別プラグインを読み込みません。ファイル形式別プ +ラグインを読み込むように設定するには次のコマンドを使います: > + + filetype plugin on +< +ファイル形式別プラグインの読み込みをオフにするにはこうします: > + + filetype plugin off +< +さらなる情報については以下を参照してください。 > + + :help filetype-plugin-on + :help filetype-plugin-off + :help :filetype +< + *faq-26.6* +26.6. 全てのファイル形式に対し、グローバルのファイル形式別プラグインでなされる + 設定を上書きするには？ + +ファイル形式イベントで引き起こされる自動コマンドを使います: > + + au Filetype * set formatoptions=xyz +< +これは少なくともあなたのvimrc中の"filetype on"以降に行わねばなりません。あなた +の"myfiletypefile"ファイル中で行うのがベストです。そうすればこれは必ず最後に実 +行されるようになります。 + +特定のファイル形式に対して設定を上書きしたいなら、~/.vim/after/ftpluginに元 +のファイルと同名のファイルを作ります。例えば、ファイル形式別プラグインc.vimの +設定を上書きするには、~/.vim/after/ftpluginにc.vimを作り、そこに好みの設定を書 +き込みます。 + +さらなる情報については以下を参照してください。 > + + :help ftplugin-overrule + :help ftplugins + :help myfiletypefile +< + *faq-26.7* +26.7. Vimのディレクトリブラウザプラグインを無効にするには？ + +ディレクトリブラウザプラグインを無効にするには、次の行を.vimrcに加えます: > + + let loaded_explorer = 1 +< +さらなる情報については以下を参照してください。 > + + :help file-explorer +< + *faq-26.8* +26.8. 特定のパターンにマッチする名前のファイルや拡張子に応じてファイル形式オ + プションを設定するには？ + +特定のパターンにマッチする名前のファイルに対しては、自動コマンドを使って +'filetype'を設定します。例えば、拡張子'.x'を持つファイル全てに対して +'filetype'を'c'にするには次の自動コマンドを使います: > + + autocmd! BufRead,BufNewFile *.x setfiletype c +< +よりよい方法は、filetype.vimファイルを~/.vimディレクトリ(または'runtimepath'で +指定されたディレクトリのどれか)に作ることです。そして次の行を書き加えます: > + + " my filetype file + if exists("did_load_filetypes") + finish + endif + augroup filetypedetect + au! BufRead,BufNewFile *.x setfiletype c + augroup END +< +さらなる情報については以下を参照してください。 > + + :help new-filetype + :help 43.2 + :help :setfiletype +< + +============================================================================= + *faq-27* +SECTION 27 - プログラムファイルを編集する + + *faq-27.1* +27.1. C/C++のファイルに対してオートインデントを有効化するには？ + +ファイル形式に基づくインデントを有効化するには次を実行します: > + + :filetype indent on +< +自動Cインデントだけを有効化したいならこうします: > + + :set cindent +< +さらなる情報については以下を参照してください。 > + + :help 'cindent' + :help C-indenting + :help filetype +< + *faq-27.2* +27.2. C/C++のファイルに対するインデントをカスタマイズするには？ + +'cinoptions', 'cinkeys', 'cinwords'の値を変えれば、Cインデントをカスタマイズす +ることができます。 + +さらなる情報については以下を参照してください。 > + + :help 'cindent' + :help 'cinoptions' + :help 'cinkeys' + :help 'cinwords' + :help C-indenting + :help cinoptions-values + :help 'smartindent' +< + *faq-27.3* +27.3. オートインデント機能を無効化するには？ + +デフォルトではオートインデントは無効になっています。.vimrcか.gvimrcでオートイ +ンデントを有効化したのでしょう。オートインデントを無効化するには、 > + + :filetype indent off +< +または > + + :set nocindent +< +とします。また、以下のオプションの設定を確認してください: > + + :set autoindent? + :set smartindent? + :set indentexpr? +< +さらなる情報については以下を参照してください。 > + + :help 'cindent' + :help filetype-indent-off + :help 'autoindent' + :help 'smartindent' + :help 'indentexpr' +< + *faq-27.4* +27.4. オートインデントの際に挿入されるスペースの数を変えるには？ + +'shiftwidth'オプションを変えると、オートインデントに使われるスペースの数を変え +ることができます: > + + :set shiftwidth=4 +< +さらなる情報については以下を参照してください。 > + + :help 'shiftwidth' +< + *faq-27.5* +27.5. Cプログラムを編集しています。マクロ定義や変数を表示するには？ + +コマンド[dでマクロ定義を表示でき、[iで変数定義を表示することができます。 + +さらなる情報については以下を参照してください。 > + + :help [d + :help [i + :help include-search + :help 29.4 + :help 29.5 +< + *faq-27.6* +27.6. Cプログラムを編集しています。ブロックの内側から、そのブロックの開始位置 + や終了位置にジャンプするには？ + +コマンド[{でそのブロックの始まりにジャンプし、]}でそのブロックの終わりにジャン +プします。 + +さらなる情報については以下を参照してください。 > + + :help [{ + :help ]} + :help various-motions +< + *faq-27.7* +27.7. C++ファイルで"//"コメントが自動的に挿入されるのを止めさせるには？ + +オプション'comments'の値を修正すればC++のコメント文字("//")が自動的に挿入され +るのを止めさせることができます。例: > + + :set comments=sr:/*,mb:*,el:*/ +< +さらなる情報については以下を参照してください。 > + + :help 'comments' + :help format-comments +< + *faq-27.8* +27.8. 一連の行の行頭にコメント文字'#'をつけ加えるには？ + +最初にビジュアル矩形モードを使って(CTRL-V)その行を全て選択します。'I'を押して +行頭に文字の挿入を開始します。コメント文字を挿入し、を押して挿入モードを +終了します。すると入力された文字が選択された全ての行の行頭に挿入されます。 + +さらなる情報については以下を参照してください。 > + + :help visual-block + :help blockwise-operators + :help v_b_I +< + *faq-27.9* +27.9. Cのソースファイルに対応する名前のヘッダファイルを開くには？ + +次のコマンドを使うと、Cソースファイルに対応する名前のヘッダファイルを開くこと +ができます: > + + :e %:t:r.h +< +次のコマンドで、そのファイルを分割したウィンドウで開くこともできます: > + + :sp %:t:r.h +< +上のコマンドで、パーセント記号はカレントファイルの名前に展開されます。修飾子 +":t"はファイル名の末尾(tail)に変換します。修飾子":r"はファイル名のルート(root) +に変換します。そして.hをつけて、最終的にヘッダファイル名が得られます。 + +別のアプローチとしては、次のコマンドを使います: > + + :sfind %:t:r.h +< +このコマンドはヘッダファイルを'path'で指定されたディレクトリの中から探します。 + +さらなる情報については以下を参照してください。 > + + :help cmdline-special + :help filename-modifiers + :help :sfind + :help 'path' +< + *faq-27.10* +27.10. コメントを入力しているとき、自動的にコメント文字を挿入するには？ + +コメントを入力しているとき自動的にコメント文字を挿入するには、'formatoptions' +にフラグ'r'と'o'を加えます。 > + + :set formatoptions+=ro +< +コメントを'textwidth'によって自動的に折り返すためにフラグ'c'をつけたり、コメン +トを"gq"コマンドで成形するためにフラグ'q'をつけてもよいでしょう: > + + :set formatoptions=croq +< +さらなる情報については以下を参照してください。 > + + :help 30.6 + :help format-comments + :help 'comments' + :help fo-table +< + +============================================================================= + *faq-28* +SECTION 28 - QuickFix + + *faq-28.1* +28.1. Vimの中からプログラムをビルドするには？ + +":make"を使うとVim中からプログラムをビルドすることができます。":make"は +'makeprg'で指定されたプログラムを起動します。 + +さらなる情報については以下を参照してください。 > + + :help 30.1 + :help make_makeprg + :help 'makeprg' + :help 'makeef' + :help :make + :help quickfix + *faq-28.2* +28.2. Vim中からmakeコマンドを起動すると、コンパイラがプログラムをコンパイル + してエラーメッセージを出力します。しかしコンパイルが終わると表示が消え + てしまい、エラーメッセージをもう一度見るには :clist としなければなりま + せん。このエラーメッセージを見るのに他の方法はありませんか？ + +":copen"や":cwindow"を使うと、コンパイラの出力を保持しているQuickFixウィンド +ウを開くことができます。そのウィンドウの中でエラーの行を選択すると、ソースコー +ド中の対応する行にジャンプすることができます。 + +さらなる情報については以下を参照してください。 > + + :help :copen + :help :cwindow + :help quickfix +< + +============================================================================= + *faq-29* +SECTION 29 - 折り畳み + + *faq-29.1* +29.1. 折り畳みの機能を拡張するには？ + +'foldexpr'を使えばユーザー指定の関数を使って折り畳みを作ることができます。 +例えば、以下の形のサブルーチンを1行に折り畳むには: > + + sub foo { + my $barf; + $barf = 3; + return $barf; + } +< +次のコマンドを使うことができます: > + + set foldmethod=expr + set foldexpr=MyFoldExpr(v:lnum) + fun! MyFoldExpr(line) + let str = getline(a:line) + if str =~ '^sub\>' + return '1' + elseif str =~ '^}' + return '<1' + else + return foldlevel(a:line - 1) + endif + endfun +< +さらなる情報については以下を参照してください。 > + + :help 'foldexpr' + :help fold-expr +< + *faq-29.2* +29.2. 'foldmethod'をセットして折り畳みを有効化すると、全ての折り畳みが閉じてし + まいます。これを防ぐには？ + +'foldlevelstart'をある値にセットすると、折り畳みがその値以上になったときのみ閉 +じさせることができます。 > + + :set foldlevelstart=99 +< +さらなる情報については以下を参照してください。 > + + :help 'foldlevelstart' + :help 'foldlevel' + :help fold-foldlevel +< + *faq-29.3* +29.3. ファイルの編集を開始したときにいくつの折り畳みが開かれた状態にするかをコ + ントロールするには？ + +'foldlevelstart'を修正すれば、ファイルの編集を開始したときにいくつの折り畳みを +開くかをコントロールすることができます。全ての折り畳みを閉じた状態で編集を開始 +するにはこうします: > + + :set foldlevelstart=0 +< +さらなる情報については以下を参照してください。 > + + :help 'foldlevelstart' +< + *faq-29.4* +29.4. マウスを使って折り畳みを開閉するには？ + +折り畳みを開閉するには、一番左の桁に表示された+と-という文字をクリックします。 +それが機能するためには'foldcolumn'を0より大きい値に設定していなければなりませ +ん: > + + :set foldcolumn=2 +< +さらなる情報については以下を参照してください。 > + + :help 'foldcolumn' +< + *faq-29.5* +29.5. 閉じた折り畳みの表示に使われるテキストを変更するには？ + +'foldtext'によって閉じた折り畳みの表示に使われるテキストを変更することができま +す。 + +さらなる情報については以下を参照してください。 > + + :help 'foldtext' + :help fold-foldtext + :help 'fillchars' +< + *faq-29.6* +29.6. Vimを終了・再起動するとき、手動で作った折り畳みを保存・復元するには？ + +":mkview"を使えば手動で作った折り畳みを保存することができます。その後、 +":loadview"でその折り畳みを復元することができます。これが機能するためには +'viewoptions'が"folds"を含んでいなければなりません。 + +さらなる情報については以下を参照してください。 > + + :help 28.4 + :help :mkview + :help :loadview + :help 'viewoptions' + :help 'viewdir' + :help :mksession + :help 'sessionoptions' +< + +============================================================================= + *faq-30* +SECTION 30 - 外部プログラムとの連携 + + *faq-30.1* +30.1. Vimのウィンドウの中でシェルを起動することはできますか？ + +現在のところ、Vimにはウィンドウの中でシェルや外部プログラムを実行する機能はあ +りません。 + +さらなる情報については以下を参照してください。 > + + :help shell-window +< +代替手段としては、Unixの"screen"ユーティリティか"splitvt"プログラムを試してみ +てもよいでしょう。 + +また、Brian Sturkによるvimshプラグインを使うとVimウィンドウの中でシェルを起動 +することができます。これを使うためには、VimをPythonインターフェイス機能つきで +ビルドしなければなりません。さらなる情報については以下のURLを訪れてください: > + + http://vim.sourceforge.net/scripts/script.php?script_id=165 +< + *faq-30.2* +30.2. カーソル下の単語を外部プログラムに渡すには？ + +特別なキーワードを使うと、カーソル下の単語を外部コマンドに渡すことがで +きます。例: > + + :!dict +< +さらなる情報については以下を参照してください。 > + + :help +< + *faq-30.3* +30.3. シェルコマンドの出力をVimのバッファに取り込むには？ + +":r !"を使えばシェルコマンドの出力をVimのバッファに取り込むことができます: > + + :r !ls +< +さらなる情報については以下を参照してください。 > + + :help :r! +< + *faq-30.4* +30.4. カレントバッファの中身を外部プログラムにパイプで渡して、そのプログラムの + 出力でバッファを置き換えるには？ + +:!を使えばカレントバッファの中身を外部プログラムにパイプで渡して、そのコマンド +の出力でバッファの中身を置き換えることができます。例えば、Unixのソートコマンド +を使ってカレントバッファの中身をソートするには、次のようにします: > + + :%!sort +< +10から20行目だけををソートするなら次のコマンドを使います: > + + :10,20!sort +< +また、バッファを外部プログラムにパイプしたいが、バッファを出力で書き換えたくな +い場合はこうします: > + + :w !sort +< +上のコマンドはバッファ全体をsortコマンドにパイプします。 +注意: 'w'と'!'の間のスペースは必ず必要です。ある範囲の行だけをパイプするにはこ +うします: > + + :10,20w !sort +< +上のコマンドは10から20行目をsortコマンドにパイプします。 + +さらなる情報については以下を参照してください。 > + + :help :range! + :help 10.9 + :help :w_c +< + *faq-30.5* +30.5. ファイル中のあるセクションをソートするには？ + +あるセクションをUnixの"sort"ユーティリティにパイプしてそのファイルをソートする +ことができます。例: > + + :5,100!sort +< + +ビジュアルモードで選択した矩形範囲だけをソートするには、次のVim onlineのtipを +参照してください: + +http://vim.sourceforge.net/tips/tip.php?tip_id=588 + + *faq-30.6* +30.6. Vimとslrnといっしょに使うステップ・バイ・ステップガイドはありますか？ + +VimとSlrnをいっしょに使うための情報については、以下のリンクを参照してください: +> + + http://thingy.apana.org.au/~fun/slrn/ +< + *faq-30.7* +30.7. Vimをページャとして使うには？ + +シェルスクリプト$VIMRUNTIME/macros/less.shを使うとVimをページャとして使うこと +ができます。これはVimの標準ディストリビューションの一部として同梱されていま +す。このシェルスクリプトは、lessライクなキーバインディングを実現するために +Vimスクリプト$VIMRUNTIME/macros/less.vimを使用しています。 + +さらなる情報については以下を参照してください。 > + + :help less +< + *faq-30.8* +30.8. Vimの中でUnixのmanページを見るには？ + +Vim標準ディストリビューションに同梱のman.vimを使えば、Vimの中でUnixのmanページ +を見ることができます。このプラグインを使うには、以下の行をvimrcファイルに追加 +してください: > + + runtime ftplugin/man.vim +< +また、Kキーを押すと、カーソル下のキーワードとともに'keywordprg'で指定された +プログラムを起動することができます。デフォルトでは'keywordprg'はカーソル下の +キーワードのmanを起動するように設定されています。 + +さらなる情報については以下を参照してください。 > + + :help man-plugin + :help K + :help 'keywordprg' +< + *faq-30.9* +30.9. Vimのdiff機能で使われるdiffコマンドを変更するには？ + +デフォルトではVimのdiff機能は'diff'コマンドを使います。'diffexpr'オプションを +変更すればこれを変えることができます。 + +さらなる情報については以下を参照してください。 > + + :help diff-diffexpr + :help 'diffexpr' +< + *faq-30.10* +30.10. 折り畳みなしで差分モードを使うには？ + +次のコマンドラインを実行すると、2つのファイル名とともに起動し、折り畳み +なしで差分モードに入ります: > + + $ vim -o file1 file2 "+windo set diff scrollbind scrollopt+=hor nowrap" +< +垂直ウィンドウ分割の方がいいなら、"-o"を"-O"に置き換えてください。 + +さらなる情報については以下を参照してください。 > + + :help vimdiff +< + +============================================================================= + *faq-31* +SECTION 31 - GUIのVIM + + *faq-31.1* +31.1. バッファ固有のメニューを作るには？ + +バッファ固有のメニューという機能はVimのTODOリストにあります。今のところは、 +Michael Geddesのプラグインbuffermenu.vimを試してみてください: > + + http://vim.sourceforge.net/scripts/script.php?script_id=246 +< + *faq-31.2* +31.2. GUIのVimで使われるフォントを変更するには？ + +'guifont'を変更すればGUIのVimで使われるフォントを変更することができます。この +オプションの現在の値を表示するにはこうします > + + :set guifont? +< +ここで表示された値を.vimrcに書いておけば、Vimを再起動しても同じフォントを使う +ことができます。例えば、次の行を.vimrcに書くとAndale Monoフォントを使うように +なります。 > + + set guifont=Andale_Mono:h10:cANSI +< +Win32, GTK, Photon版のVimでは、次のコマンドでguifontを変える際に便利なダイアロ +グを起動することができます: > + + :set guifont=* +< +Vimのコマンドライン引数に-fontを使うと通常のテキストに使われるフォントを指定す +ることができます。 + +さらなる情報については以下を参照してください。 > + + :help 'guifont' + :help 'guifontset' + :help 'guifontwide' + :help font-sizes + :help -font + :help -boldfont + :help -italicfont + :help -menufont + :help -menufontset +< + *faq-31.3* +31.3. GUIのVimが起動したときのウィンドウの位置を指定するには？ + +コマンドライン引数"-geometry"を指定すれば、GUIのVimのウィンドウの位置を指定す +ることができます。例: > + + $ gvim -geometry 80x25+100+300 +< +さらなる情報については以下を参照してください。 > + + :help 31.4 + :help -geom +< + *faq-31.4* +31.4. GVimに水平スクロールバーをつけるには？ + +'guioptions'を修正すれば水平スクロールバーを有効化することができます: > + + :set guioptions+=b +< +さらなる情報については以下を参照してください。 > + + :help 'guioptions' + :help gui-horiz-scroll +< + *faq-31.5* +31.5. スクロールバーをデフォルトで左側に表示するようにするには？ + +'guioptions'にフラグ'l'をつけるとスクロールバーが左側に出るようになります。 > + + :set guioptions+=l + :set guioptions-=r +< +さらなる情報については以下を参照してください。 > + + :help 'guioptions' + :help gui-scrollbars +< + *faq-31.6* +31.6. メニューバーを消すには？ + +'guioptions'からフラグ'm'を除くとメニューバーが消えます: > + + :set guioptions-=m +< +さらなる情報については以下を参照してください。 > + + :help 'guioptions' +< + + *faq-31.7* +31.7. GVimを使っています。ALTキーと文字キーを押すとその文字で始まるメニューが + 選択されます。ALT-の組合せを使いたいので、この挙動はやめてほしいで + す。どうすればいいですか？ + +'winaltkeys'を使えばALTキーでメニュー項目を選択するのを無効にすることができま +す: > + + :set winaltkeys=no +< +さらなる情報については以下を参照してください。 > + + :help 'winaltkeys' + :help :simalt +< + *faq-31.8* +31.8. スクロールバーをドラッグしたとき、カーソル位置を動かさずにテキストをスク + ロールさせることは可能ですか？ + +Vimの設計では、ノーマル・ビジュアル・選択・挿入モードにおいてカーソル位置は表 +示されている位置になければなりません。これはVimの修正なしには変更できません。 +スクロールバーを使うと、カーソル位置は常に表示されている範囲に入るように移動し +ます。この問題を解決する別のアプローチはVimのマークを使うことです。maで現在の +カーソル位置をマークします。テキストをスクロールしたら`aで元の位置に戻ります。 +Vim Onlineに投稿された次の提案も試してみてください: > + + http://www.vim.org/tip_view.php?tip_id=320 +< +さらなる情報については以下を参照してください。 > + + :help mark-motions +< + *faq-31.9* +31.9. ":browse"を使ったときに特定のディレクトリから始めるようにするには？ + +'browsedir'を設定すれば":browse"コマンドのデフォルトディレクトリを設定できま +す。 > + + :set browsedir='' +< +さらなる情報については以下を参照してください。 > + + :help 'browsedir' +< + *faq-31.10* +31.10. ファイルがVimの外部で変更されたときなど、問い合わせがあるとき、GUIのダ + イアログボックスが表示されます。コンソールのダイアログボックスが出るよ + うにするには？ + +'guioptions'にフラグ'c'を含めれば、GUIダイアログの代わりにコンソールダイアログ +を使うようになります: > + + :set guioptions+=c +< +さらなる情報については以下を参照してください。 > + + :help 'guioptions' +< + *faq-31.11* +31.11. GVimをアプリケーションxxx用のエディタとして使っています。アプリケーショ + ンxxxがGVimを起動すると、コントロールがすぐにアプリケーションxxxに戻っ + てしまいます。Vimを終了したとき初めてアプリケーションxxxにコントロール + が戻るようにGVimを起動するには？ + +コマンドラインオプション'-f' (foreground)をつけてGVimを起動します: > + + $ gvim -f +< +デフォルトではGVimはそれを起動したプログラムから切り離されます。'-f'をつけると +GVimはそれを起動したプログラムから切り離されなくなります。 + +さらなる情報については以下を参照してください。 > + + :help gui-fork + :help -f +< + *faq-31.12* +31.12. なぜ、システムにインストールされているフォント全てが「フォントを選ぶ」 + ダイアログに現れないのですか？ + +Vimは等幅フォントのみサポートしています。プロポーショナルフォントはサポートし +ていません。「フォントを選ぶ」ダイアログには等幅フォントだけが表示されます。 + +さらなる情報については以下を参照してください。 > + + :help font-sizes + :help 'guifont' +< + *faq-31.13* +31.13. コマンドラインモードでマウスを使うには？ + +コマンドラインモードでマウスを使うには、オプション'mouse'にフラグ'c'をつけま +す: > + + :set mouse+=c +< +さらなる情報については以下を参照してください。 > + + :help mouse-using + :help gui-mouse + :help 09.2 +< + *faq-31.14* +31.14. テキストをスクロールしようとマウスの中央ボタンを押すと、最後にコピーし + たテキストがペーストされてしまいます。この挙動を無効にするには？ + +マウスの中央ボタンにをマップすると中央ボタンを無効化できます: > + + :map + :map! +< +さらなる情報については以下を参照してください。 > + + :help gui-mouse-mapping + :help +< + *faq-31.15* +31.15. GVimウィンドウの位置とサイズを変更するには？ + +コマンド"winpos"を使えばVimウィンドウの位置を変えることができます。ウィンドウ +のサイズを変えるには、オプション"lines"と"columns"を変更します。 + +例えば、次のコマンドはGVimウィンドウのX,Y座標を50,50に、行数を50に、桁数を80に +セットします。 > + + :winpos 50 50 + :set lines=50 + :set columns=80 +< +":winpos"への引数はVimウィンドウのピクセル座標を指定します。オプション'lines' +と'columns'は行数と文字数を指定してウィンドウの高さと幅を設定します。 + +さらなる情報については以下を参照してください。 > + + :help 31.4 + :help :winpos + :help 'lines' + :help 'columns' + :help GUIEnter +< + +============================================================================= +SECTION 32 - UNIX上のVim + + *faq-32.1* +32.1. xtermでVimを実行しています。CTRL-Sを押すとVimがフリーズします。 + どうすればいいですか？ + +多くのターミナルエミュレータと本物のターミナルドライバはCTRL-Sを受け取るとデー +タの受信を停止します。早すぎて見えない画面のスクロールを止めるためです(昔の端 +末で、バッファがオーバーフローしないようにコンピュータを遅くするためでもありま +した)。CTRL-Qを押すと出力を再開します。 + +CTRL-Sを押すとターミナルドライバは出力データの送信を停止します。結果としてVim +がハングしたように見えます。CTRL-Qを押すと全て通常に戻るでしょう。 + +'stty'コマンドを使うとターミナルドライバのフローコントロールをオフにすることが +できます: > + + $ stty -ixon -ixoff +< +または、次のコマンドでターミナルのフローコントロールに使うキーを変更することが +できます: > + + $ stty stop + $ stty start +< + *faq-32.2* +32.2. 画面の更新について奇妙な問題があります。これを解決するには？ + +xtermのような適切なターミナルエミュレータと正しいTERM設定(TERM=xterm)と正しい +terminfo/termcapファイルを使わねばなりません。 +さらなる情報については以下を参照してください。 > + + :help 'term' +< + *faq-32.3* +32.3. Vimのターミナル/コンソール版を使っています。挿入モードでバックスペース + キーを押してもカーソルの前の文字が消えません。どう設定すれば良いですか？ + +Vimが正しいバックスペースのキーコードを受け取っているかどうか確かめてください。 +次のコマンドを試してみてください: > + + :fixdel +< +環境変数TERMが正しくターミナルの名前に設定されているかを確かめてください。 +'stty'コマンドを試してみてください: > + + $ stty erase ^H +< +ここで、^Hの文字を入力するにはCTRL-VとCTRL-Hを押してください。 + +さらなる情報については以下を参照してください。 > + + :help :fixdel + :help Linux-backspace + :help NetBSD-backspace +< + *faq-32.4* +32.4. xtermでVimを使っています。Vimを終了すると画面が元の状態に復元されます。 + これを無効化するには？ + +xtermは「代替スクリーン」("alternate screen")という機能を持っています。この機 +能が有効になっていると、Vimは起動時と終了時にこの代替スクリーンに切り替えま +す。そのため、元の画面が復元されます。この機能を無効にするには次の行を.vimrcに +加えてください: > + + :set t_ti= t_te= +< +さらなる情報については以下を参照してください。 > + + :help restorescreen + :help xterm-screens +< + *faq-32.5* +32.5. Vimの起動にかなり時間がかかります。起動時間を最小化するには？ + +これはおそらくVimがxtermのタイトルとXのクリップボードのためにXディスプレイを開 +いていることに関係しています。環境変数DISPLAYが正しいホストを指していることを +確認してください。次のコマンドを試してみてください: > + + $ vim -X +< +こうするとXディスプレイを開かなくなります。このコマンドラインオプションをつけ +るとXのクリップボードが使えなくなり、xtermのタイトルを変えられなくなります。 + +オプション'clipboard'を次のように変更することもできます: > + + :set clipboard=exclude:.* +< +こうするとコマンドライン引数-Xを使うのと同じ効果があります。 + +さらなる情報については以下を参照してください。 > + + :help -X + :help 'clipboard' +< + + *faq-32.6* +32.6. Unixのgvimでカーソルの点滅を止めるには？ + +オプション'guicursor'を変更すればカーソルの点滅を止めることができます。 +例: > + + :set guicursor=a:blinkon0 +< +さらなる情報については以下を参照してください。 > + + :help 'guicursor' +< + *faq-32.7* +32.7. GTK Vimのメニューのフォントを変えるには？ + +~/.gtkrcを修正すればGTK Vimのメニューのフォントを変更できます。例: > + + style "default" + { font ="smooth09" } + class "*" style "default" +< +最後の行が全てのウィジェットのフォントを変えています。 + +さらなる情報については以下を参照してください。 > + + :help gui-gtk +< + *faq-32.8* +32.8. Vimがでサスペンドするのを防ぐには？ + + をマップすればサスペンドするのを防げます。いくつかの提案を示します: + +- でなにもしないようにする: > + + :map +< +- でシェルが起動するようにする: > + + :map :shell +< +- でエラーメッセージが出るようにする: > + + :map :"suspending disabled +< +最後の例において、ダブルクォートはメッセージをステータスライン上に残すために必 +要になります。 + + *faq-32.9* +32.9. Vimを実行しているxtermをkillすると、Vimのプロセスが生き残り、多大なCPU時 + 間(99%)を食ってしまいます。なぜこうなるのですか？ + +VimがPythonインターフェイスつきでビルドされるとこの問題が起こります。これは +PythonスレッドライブラリとVimに関する既知の問題です。この問題を解決するには、 +PythonインターフェイスなしでビルドされたVimを使用してください。 + +さらなる情報については以下を参照してください。 > + + :help +python + :help python +< + + *faq-32.10* +32.10. Unixターミナルで構文強調を使うには？ + +構文強調を使う最も簡単で単純な方法はVimのGUI版(GVim)を使うことです。Vimのコン +ソール/ターミナル版で構文強調を使うには、カラー表示をサポートしているターミ +ナルエミュレータ(Xfree86 xtermやrxvtやdttermのようなもの)を使わねばなりませ +ん。ターミナルエミュレータが背景色と文字色を変えられるからといって、それが色を +変えるためのANSIエスケープシーケンスをサポートしているとは限りません。最新の +Xfree86 xtermはhttp://dickey.his.com/xterm/xterm.htmlからダウンロードできます。 +最新のrxvtはhttp://www.rxvt.orgからダウンロードできます。そのターミナルエミュ +レータ用の色をサポートしているterminfo/termcapをインストールしなければなりま +せん。また、環境変数TERMをそのターミナルの正しい名前に設定します。 + +色設定をテストするにはVimランタイムパッケージに付属のcolortest.vimスクリプトを +使うことができます。このスクリプトを使うには次のようにします: > + + :e $VIMRUNTIME/syntax/colortest.vim + :source % +< +さらなる情報については以下を参照してください。 > + + :help 06.2 + :help terminal-colors + :help termcap-colors + :help startup-terminal + :help xterm-color + :help colortest.vim +< + +============================================================================= + *faq-33* +SECTION 33 - MS-Windows上のVim + + *faq-33.1* +33.1. MS-Windows上でCTRL-Vを押してもビジュアル矩形モードが始まりません。どう + なっているのですか？ + +mswin.vimプラグインは、VimがMS-Windowsアプリケーションに似た挙動をするように +キーマッピングとオプションを設定します。そのキーマップの一つがCTRL-Vで、これは +MS-Windowsアプリケーションではテキストをペーストします。このためCTRL-Vでビジュ +アル矩形モードが始まらないようになっています。mswin.vimではビジュアル矩形モー +ドの開始がCTRL-Qにマップされています。ですのでCTRL-Vの代わりにCTRL-Qを使ってく +ださい。 + +さらなる情報については以下を参照してください > + + :help CTRL-V + :help CTRl-V-alternative + :help CTRL-Q + :help 10.5 +< + *faq-33.2* +33.2. CTRL-Yキーを押すとCTRL-Rのような動作をします。CTRL-YをCTRL-Yとして扱うよ + うに設定するには？ + +CTRL-YからCTRL-Rへのマップはmswin.vim内で行われています。mswin.vimは標準の +MS-Windowsアプリケーションと同じ挙動になるようにCTRL-Yをマップします。これ +は":help CTRL-Y"で説明されています。mswin.vim中のCTRL-Yをマップしている行をコ +メントアウトするか、.vimrc中でmswin.vimを読み込んでいる行を削除すればよいで +しょう。 + + + *faq-33.3* +33.3. 常にGVimのウィンドウを最大化して起動するには？ + +"simalt"コマンドを使えばVimのウィンドウを最大化することができます。GUIEnter自 +動コマンドを使えば、起動時にVimのウィンドウを最大化することができます: > + + autocmd GUIEnter * simalt ~x +< +さらなる情報については以下を参照してください: > + + :help :simalt + :help GUIEnter + :help gui-win32-maximized +< + *faq-33.4* +33.4. なんらかの編集操作をするとVimがフリーズします。カーソルは空の四角形にな + ります。全然文字が入力できません。どうなっているのですか？ + +もっとも考えられるのは、テキストをスクロールさせようとマウスホイールを使ったこ +とです。Vimでインテリマウスホイールを使うと問題が起こることが知られています。 +これを回避するには、ユニバーサルスクロール機能を無効にすることです。 + +さらなる情報については以下を参照してください > + + :help intellimouse-wheel-problems +< + + *faq-33.5* +33.5. Windows XPを使っています。最大化したGVimの表示速度がとても遅いです。表示 + の更新を早くするには？ + +これは画面のプロパティの "スクリーン フォントの縁を滑らかにする" を有効化して +いるために起こっている可能性があります。フォントスムージングをオフにするか、ス +ムージング方法を "標準" にしてください。 + +{訳注: コントロールパネル[パフォーマンスオプション]の[スクリーンフォントの縁を + 滑らかにする]のことだと思う。} + + *faq-33.6* +33.6. VimをCygwin上で使うにあたって推奨される設定は？ + +シェル関連の設定を次のようにするとよいかもしれません: > + + :set shellcmdflag=-c + :set shellquote= + :set shellslash " 展開に(バックスラッシュでなく)スラッシュを使う + :set shellxquote=\" + :set shell=d:\cygwin\bin\bash.exe " bashをシェルに使う + :set shellpipe=2>&1| tee + :set shellredir=>%s 2>&1 +< + *faq-33.7* +33.7. 差分モードでGNU diffを使おうとしています。コマンドラインからdiffを使うと + うまく動くのですが、Vim内で使おうとすると動きません。どうすれば？ + +VimでGNU diffを使うには問題があります。次のリンクにあるRon Aaronがビルドした +GNU diff.exeを使ってみてください: > + + http://www.mossbayeng.com/~ron/vim/builds.html +< + *faq-33.8* +33.8. Outlookで外部エディタにVimを使うことはできますか？ + +COMアドイン"cubiclevim"を使えば、OutlookでVimを外部エディタとして使うことがで +きます。さらなる情報については以下のリンクを訪れてください: > + + http://sourceforge.net/projects/cubiclevim +< +注意: 現在これはMS-Office 2000とXPのみで動作します。 + + *faq-33.9* +33.9. HTMLファイルを編集するのにVimを使っています。現在開いているHTMLファイル + をインターネットエクスプローラーでプレビューするには？ + +以下のコマンドでできます: > + + :!start c:\progra~1\intern~1\iexplore.exe file://%:p +< + *faq-33.10* +33.10. VimをMicrosoft Visual Studioといっしょに使いたいです。どうすれば？ + +VimのOLE版(例: gvim61ole.zip)をダウンロードして使用しなければなりません。 +このファイルはVimをVisual Studioといっしょに使うための手順を書いたファイルも含 +んでいます。 + +さらなる情報については以下を参照してください > + + :help MSVisualStudio +< + *faq-33.11* +33.11. どこに_vimrcと_gvimrcを置けばいいですか？ + +_vimrcと_gvimrcは環境変数VIMで指定されたディレクトリの下に置きます。もし他のユ +ーザとシステムを共有しているなら、環境変数HOMEに設定したディレクトリに置くとよ +いでしょう。 + +さらなる情報については以下を参照してください > + + :help $HOME-use + :help _vimrc +< + *faq-33.12* +33.12. ファイルを保存する度に、そのファイルがVimの外部で変更されていると警告が + 出ます。なぜですか？ + +ファイルを保存する際に毎回以下の警告メッセージが出るなら: > + + WARNING: The file has been changed since reading it!!! + Do you really want to write to it (y/n)? +< + +MS-Windowsでのサマータイム(daylight saving time)が始まる日についてのバグに関係 +している可能性があります。Vimはファイルを書き込んだ後にそのタイムスタンプを記 +憶しています。そして次の書き込みの直前に再びタイムスタンプを取得し、Vimの外部 +でファイルが変更されているかチェックします。これはサマータイムが始まる日を除け +ば正しく機能します。 + +この問題はサマータイムが始まる日の次の日には解消されます。 + +さらなる情報については以下を参照してください > + + :help W11 +< + +============================================================================= + *faq-34* +SECTION 34 - 印刷 + + *faq-34.1* +34.1. 全ての行に行番号をつけて印刷するには？ + +'printoptions'をセットして":hardcopy"を使えばファイルを印刷できます: > + + :set printoptions=number:y + :hardcopy +< +さらなる情報については以下を参照してください > + + :help 'printoptions' + :help :hardcopy +< + *faq-34.2* +34.2. 構文強調の色をつけてファイルを印刷するには？ + +":hardcopy"で構文強調の色をつけてファイルを印刷することができます。また、 +2html.vimスクリプトでファイルをHTMLをファイルに変換し、そのHTMLファイルを印刷 +することもできます。 + +さらなる情報については以下を参照してください > + + :help syntax-printing + :help 2html.vim + :help :hardcopy + :help printing +< + +============================================================================= + *faq-35* +SECTION 35 - Vimをソースからビルドする + + *faq-35.1* +35.1. Unixシステム上でVimをソースからビルドするには？ + +UnixシステムでVimをソースからビルドするには、次のステップに従ってください: + +- ftp://ftp.vim.org/pub/vim/unixからソースとランタイムファイルのアーカイブ + (vim-##.tar.bz2)をダウンロードします。 +- bzip2とtarを使ってアーカイブを展開します: > + + $ bunzip2 -c | tar -xf - +< +- 'make'を実行してVimをデフォルト設定で調整し、ビルドします。 +- 'make install'してVimをデフォルトのディレクトリにインストールします。 + +Vimの様々な機能を有効/無効にするには、'make'を実行する前に'configure'コマンド +でフラグを設定します。'configure'で指定できるオプションのリストを次のコマンド +で表示することができます: > + + $ configure -help +< +{訳注: --help の間違い？} + +さらなる情報については以下を参照してください > + + :help install +< + *faq-35.2* +35.2. Unixでホームディレクトリなど、デフォルトのディレクトリ以外にVimをインス + トールするには？ + +デフォルトのインストールディレクトリ以外にインストールするには、configureスク +リプトを実行する際に--prefixオプションでディレクトリを指定します。 > + + $ ./configure --prefix=/users/xyz +< +configureスクリプトに様々な引数を与えることによって、Vimの色々な機能を有効/無 +効にできます。それらのオプションについてのさらなる情報については、次を実行して +ください。 > + + $ ./configure --help +< +さらなる情報については以下を参照してください > + + :help install-home + :help install +< + *faq-35.3* +35.3. MS-Windowsシステム上でVimをソースからビルドするには？ + +MS-Windowsシステム上では、Visual C++またはBorland C++またはMing GCCコンパイラ +またはcygwin gccコンパイラのどれかを使ってVimをビルドすることができます。 +MS-Windows用にVimをソースからビルドするには次のステップに従ってください: + +- ソース(vim##src.zip)、ランタイム(vim##rt.zip)とその他(vim-##-extra.tar.gz)の + アーカイブをftp://ftp.vim.org/pub/vim/pcからダウンロードします。 + +{訳注: 2006年8月現在、Vim7のソースとランタイムはまとめて1つのアーカイブ + (vim-7.0.tar.bz2)にして公開されている。} + +- アーカイブをディレクトリ(例: c:\vimsrc)に展開します。 +- コンパイラに応じたMakefileを使います。Visual C++用にはMake_mvc.mak、Borland + C++用にはMake_bc5.mak、Ming GCC用にはMake_ming.mak、cygwin gcc用には + Make_cyg.makを使います。 + +VimのGUI版とコンソール版のどちらをビルドしたいかによって、Makefileに異なる引数 +を与えなければなりません。ソースのビルドに成功したら、vim.exeやgvim.exeをラン +タイムファイルとともに望みのディレクトリにコピーできます。 + +MS-Windowsシステムで様々なコンパイラを使ってVimをビルドするための情報について +は、以下のサイトを訪れてください: > + + http://mywebpage.netscape.com/SharpPeople/vim/howto/index.html +< +さらなる情報については以下を参照してください > + + :help install +< + *faq-35.4* +35.4. 私がインストールしたVimにはヘルプ、構文ファイル、インデントファイルが欠 + けています。それらのファイルをインストールするには？ + +Vimのヘルプ、構文ファイル、インデントファイルやそのほかのランタイムファイルは +Vimランタイムパッケージの一部です。Vimランタイムパッケージをダウンロードしてイ +ンストールする必要があります。例えば、MS-Windows用のVim6.1ランタイムパッケージ +の名前はvim61rt.zipです。 + +{訳注: 2006年8月現在、Vim7のソースとランタイムはまとめて1つのアーカイブ + (vim-7.0.tar.bz2)にして公開されている。} + +さらなる情報については以下を参照してください > + + :help install +< + *faq-35.5* +35.5. Vimをソースからビルドして"make install"でインストールしました。Vimのソー + スディレクトリを残しておく必要はありますか？ + +その必要はありません。一度Vimをビルドして元のソースディレクトリ以外のどこか +(例えば/usr/binや/usr/local/bin)にインストールしたら、ソースディレクトリは削除 +してもかまいません。 + + *faq-35.6* +35.6. ある機能がコンパイル時に有効化されているかどうかを知るには？ + +":version"を使えば、ある機能がコンパイル時に有効化されているかどうかを知ること +ができます。有効化されている機能の前には"+"がつきます。有効化されていない機能 +の前には"-"がつきます。 + +スクリプトの中で、ある機能の存在を判定したい場合は、関数has()を使います: > + + if has("menu") + " Set up some menus + endif +< +さらなる情報については以下を参照してください > + + :help :version + :help +feature-list + :help has() +< + *faq-35.7* +35.7. GUI機能なしでVimをビルドすることはできますか？ + +できます。GUI機能を含めて、Vimの機能の多くは任意に有効化/無効化してビルドする +ことができます。 + +さらなる情報については以下を参照してください > + + :help install +< + *faq-35.8* +35.8. Unixシステム上でVimをビルドするとき、"undefined reference to + term_set_winsize"というエラーが出ます。これを解決するには？ + +ビルド処理がtermlibまたはtermcapまたはncursesライブラリを見つけられないときこ +のエラーが出ます。このエラーを解決するには、ncurses-devパッケージをインストー +ルしなければなりません。 + + *faq-35.9* +35.9. GTK 2.03を使おうとしているのですが、Vimのconfigureがgtk-configがないとの + メッセージを出します。しかしGTK2は一般的なpkg-configを使うようになったの + で、これは正しいのです。gtk用のインクルードファイルとライブラリのリスト + を出力するpkg-configならありますが、なぜかconfigureスクリプトはこれを + 使ってくれません。 + +次のシェルスクリプトにgtk-configと名前をつけて使ってください: > + + #!/bin/sh + pkg-config gtk+-2.0 $1 $2 +< + +============================================================================= + *faq-36* +SECTION 36 - 様々な事柄 + + *faq-36.1* +36.1. Vimでバイナリフィルを編集するには？ + +以下のオプションを設定すればVimでバイナリファイルを編集することができます: > + + :set binary + :set display=uhex +< +コマンドラインオプション"-b"を使ってもバイナリファイルを編集することができます +: > + + $ vim -b +< +また、バイナリファイルを編集するのにxxdユーティリティ(Vimのディストリビュー +ションの一部)を使うこともできます。 + +さらなる情報については以下を参照してください > + + :help 23.4 + :help edit-binary + :help hex-editing + :help -b + :help 'binary' + :help 'endofline' + :help 'display' +< + *faq-36.2* +36.2. ビジュアルエラーフラッシュとエラービープを無効にするには？ + +次のコマンドを使うと、ビジュアルエラーフラッシュとエラービープを両方無効にする +ことができます: > + + :set visualbell t_vb= +< +さらなる情報については以下を参照してください > + + :help 'visualbell' + :help 'errorbells' + :help t_vb +< + *faq-36.3* +36.3. バッファに表示されている文字のASCIIコードを表示するには？ + +'ga'コマンドを使うと、表示されている文字のASCIIコードを表示することができます。 + + +さらなる情報については以下を参照してください > + + :help ga + :help :ascii +< + *faq-36.4* +36.4. コマンドのカウントとして0を使うことはできますか？ + +"0"はそれ自身がコマンドであるため(現在行の1桁目に移動する)、コマンドのカウント +として使うことはできません。 + +さらなる情報については以下を参照してください > + + :help 0 + :help count +< + *faq-36.5* +36.5. Vimの起動時の画面を表示させなくするには？ + +Vimの起動時の画面を表示させなくするには、'shortmess'にフラグ'I'を追加します: > + + :set shortmess+=I +< +さらなる情報については以下を参照してください > + + :help :intro + :help 'shortmess' +< + *faq-36.6* +36.6. "hit enter to continue"プロンプトを避けるには？ + +あなたに読んでほしいメッセージがあるのに画面が再描画されようとしているとき、 +"hit enter to continue"プロンプトが出ます。'shortmess'にフラグ'T'を加えると、 +全てのメッセージを短縮することができます。するとhit-enterプロンプトを避けるこ +とができます: > + + :set shortmess+=T +< +また、'cmdheight'を設定するとコマンドラインの高さを上げることができます: > + + :set cmdheight=2 +< +さらなる情報については以下を参照してください > + + :help hit-enter + :help avoid-hit-enter + :help 'shortmess' + :help 'cmdheight' +< + *faq-36.7* +36.7. コマンドラインからVimを起動して一連のファイルに対して一連のコマンドを + 実行するには？ + +コマンドラインからVimを起動して一連のファイルに対して一連のコマンドを実行する +にはいくつかの方法があります。コマンドラインオプション"-c"でコマンドを指定する +ことができます: > + + $ vim -c "" -c "" *.txt +< +コマンドラインオプション"-c"で指定されたexコマンドは順番に1つずつ実行されま +す。また、exコマンドを"|"で区切れば1つの"-c"で指定することもできます: > + + $ vim -c " | " *.txt +< +上のコマンドでexコマンドが失敗した場合は残りのexコマンドは全て実行されません。 + +例えば、コマンドラインからファイル中の"ABC"を"DEF"で置換するには次のコマンドを +使います: > + + $ vim -c "%s/ABC/DEF/ge | update" myfile.txt +< +コマンドラインから複数のファイル中の"ABC"を"DEF"で置換するには次のコマンドを使 +います: > + + $ vim -c "argdo %s/ABC/DEF/ge | update" *.txt +< +一連のコマンドをファイルに保存しておき、コマンドラインオプション"-s"を使って +ファイルに対してそのコマンドを実行することもできます。例えば、mycmds.txtに一連 +のコマンドを保存してあるとします。このとき次のようにできます: > + + $ vim -s mycmds.txt *.pl +< +さらなる情報については以下を参照してください > + + :help -c + :help -s +< + *faq-36.8* +36.8. 挿入モードから抜けることなくノーマルモードコマンドを実行するには？ + +CTRL-Oに続けてノーマルモードコマンドを1つ入力すると、挿入モードから抜けること +なくノーマルモードコマンドを実行することができます。 + +1つ以上のノーマルモードコマンドを実行するにはCTRL-Lを押し、続けて任意個のノー +マルモードコマンドをタイプします。挿入モードに抜けるにはを押します。 + +{訳注: CTRL-Lを使うにはオプション'insertmode'をオンにしていなければならない。} + +さらなる情報については以下を参照してください > + + :help i_CTRL-O + :help i_CTRL-L +< + +============================================================================= + *faq-37* +SECTION 37 - Unicode +Author: Tony Mechelynck + + *faq-37.1* +37.1. VimでUnicodeのファイルを作ることはできますか？ + +できます。あなたが利用できるキーボードとフォントによって多少複雑になるかもしれ +ませんが、常にどんなUnicodeコードポイントでも(中には不正なものも)エンコードす +ることができます。Unicodeのファイルを作成するには、Vimをコンパイル時オプション +"+multi_byte"つきでコンパイルしていなければなりません。Unicodeについてのさらな +る情報は以下のサイトから入手できます: > + + http://www.unicode.org + http://www.cl.cam.ac.uk/~mgk25/unicode.html +< +さらなる情報については以下を参照してください > + + :help multibyte + :help usr_45.txt +< + *faq-37.2* +37.2. Unicodeのファイルを編集するにあたって特に重要な設定は？ + +最も重要なのは様々な"encoding"のオプションです。つまり、'encoding', +'fileencoding', 'fileencodings', 'termencoding'です。ブール値のオプション +'bomb'も重要です。 + +さらなる情報については以下を参照してください > + + :help 'encoding' + :help 'fileencoding' + :help 'fileencodings' + :help 'termencoding' + :help 'bomb' +< + *faq-37.3* +37.3. オプション'encoding'とは何ですか？ + +基本的にオプション'encoding'はVimがデータを内部的にどう表現するかを定義します。 +しかし、Unicodeエンコーディングは全て内部的にはutf-8で表現され、(必要ならば)読 +み書きの際に変換されます。 + +さらなる情報については以下を参照してください > + + :help 'encoding' +< + *faq-37.4* +37.4. Vimでは様々なUnicodeエンコーディングをどう表記しますか？ + +Utf-8はutf-8またはutf8と書きます。utf-16はucs-2またはucs2と書きます。utf-32は +ucs-4またはucs4と書きます。エンディアンを指定することもできます(utf-8はエンディ +アンによらないのでそれ以外)。末尾に"le"をつけるとリトルエンディアンになり、 +"be"をつけるとビッグエンディアンになります。エンディアンの指定なしにucs-2や +ucs-4のエンコーディングでファイルを作成すると、Vimはあなたのマシンに応じて適切 +な方を選択します。 + +さらなる情報については以下を参照してください > + + :help encoding-names + :help encoding-values + :help encoding-table +< + *faq-37.5* +37.5. バイト順マークの有無を指定するには？ + +'fileencodings'が"ucs-bom"を含む場合、ファイルを読み込むときにバイト順マークの +チェックが行われます。オプション'bomb'がオンなら、ファイルを書き込むときに、そ +のファイルのエンコーディングを保証するバイト順マークを書き込みます。 + +さらなる情報については以下を参照してください > + + :help 'fileencodings' + :help 'bomb' +< + *faq-37.6* +37.6. オプション'fileencoding'とは何ですか？ + +オプション'fileencoding'はファイルを書き込むときに使うエンコーディングを定義し +ます。これが空の場合は、'encoding'の値が使われます。 + +さらなる情報については以下を参照してください > + + :help 'fileencoding' +< + *faq-37.7* +37.7. オプション'fileencodings'とは何ですか？ + +オプション'fileencodings'はVimが既存のファイルを開くときに使う検査方法を定義し +ます。このオプションはコンマで区切られたエンコーディングのリストです。特別な名 +前"ucs-bom"を含めると、バイト順マークの存在をチェックするようになります。 +しかし、これが"utf-8"の後に来ると認識されなくなります。通常は、"ucs-bom"を含め +るならば、リストの最初に書くべきです。 + +Vimはファイルを開くとき、そのファイルを'fileencodings'内にリストされたエンコー +ディングに対してチェックします。もしここでマッチするものがなければ +'fileencoding'が空文字列に設定されます。つまり、'encoding'の値が使われます。 + +さらなる情報については以下を参照してください > + + :help 'fileencodings' + :help 'encoding' +< + *faq-37.8* +37.8. オプション'termencoding'とは何ですか？ + +オプション'termencoding'は、あなたがタイプしたデータをキーボードがどのようにエ +ンコードするかを定義します。これが空の場合は'encoding'と同じ値であるとされま +す。通常、このオプションはあなたのロカールに合うように設定するべきです。 + +さらなる情報については以下を参照してください > + + :help 'termencoding' + :help locale +< + *faq-37.9* +37.9. オプション'bomb'とは何ですか？ + +'fileencodings'に"ucs-bom"が含まれているときファイルを読み込むと、そのファイル +の先頭にバイト順マークがあるかどうかによって'bomb'がオン/オフに設定されます。 +'bomb'がオンになっていると、ファイル書き込み時に、バイト順マークが書き込まれま +す。このバイト順マーク書き込みを手動で設定することもできます。 + +さらなる情報については以下を参照してください > + + :help 'bomb' +< + *faq-37.10* +37.10. これらのオプションの典型的な例はどこにありますか？ + +これらを別な言葉で例をつけて説明した"tip"がここにあります。 +http://vim.sourceforge.net/tip_view.php?tip_id=246 + + *faq-37.11* +37.11. Unicodeの文字を挿入するには？ + +いくつかの方法があります: + +- キーボード上にある文字は普通にタイプできます。フランスのキーボードの曲線ア + クセント記号のように"dead-key"プリフィックスが必要なものもです。 +- ダイグラフが定義されている文字は、に続けて2つの文字をタイプすること + で入力できます。 +- オプション'digraph'がセットされていると、ダイグラフが定義されている文字は + のようにして入力できます。 +- どんな文字もプリフィックスを使えば入力できます(がクリップボ + ードからペーストするようにマップされている場合はです)。 + +さらなる情報については以下を参照してください。 > + + :help digraphs + :help 'digraph' + :help i_CTRL-V_digit +< + *faq-37.12* +37.12. どのダイグラフがどの文字に定義されているかを知るには？ + +まず'encoding'を適切に(例えばutf-8に)設定してください。それから :digraphs を +使って現在定義されているダイグラフを表示します。 + +さらなる情報については以下を参照してください。 > + + :help :digraphs + :help 'encoding' +< + +============================================================================= + vim:tw=78:ts=8:ft=help:norl: diff --git a/vim_faq/vim_faq.txt b/vim_faq/vim_faq.txt new file mode 100644 index 000000000..fe19704fc --- /dev/null +++ b/vim_faq/vim_faq.txt @@ -0,0 +1,7569 @@ +*vim_faq.txt* Frequently Asked Questions + +For instructions on installing this file, type > + :help add-local-help +inside Vim. + +Last updated on: 17 October 2004 + + VIM REFERENCE MANUAL by: Yegappan Lakshmanan + +Frequently Asked Questions *faq* *FAQ* + +This Vim FAQ is created from the questions and answers posted to the +vim@vim.org user mailing list and the comp.editors newsgroup. There are +several ways to solve a problem in Vim. This FAQ gives one of those several +possibilities. You can explore the other ways using the information and +links given in this FAQ. The credit for the answers in this FAQ goes to +Peppe, Benji, Charles Campbell and numerous others. + *faq-index* +INDEX + *faq-general-information* +SECTION 1 - GENERAL INFORMATION +|faq-1.1| What is Vim? +|faq-1.2| Who wrote Vim? +|faq-1.3| Is Vim compatible with Vi? +|faq-1.4| What are some of the improvements of Vim over Vi? +|faq-1.5| Is Vim free? + *faq-resources* +SECTION 2 - RESOURCES +|faq-2.1| Where can I learn more about Vim? +|faq-2.2| Is there a mailing list available? +|faq-2.3| Is there an archive available for the Vim mailing lists? +|faq-2.4| Where can I get the Vim user manual in HTML/PDF/PS format? +|faq-2.5| I have a "xyz" (some) problem with Vim. How do I determine it is a + problem with my setup or with Vim? +|faq-2.6| Where can I report bugs? +|faq-2.7| Where can the FAQ be found? +|faq-2.8| What if I don't find an answer in this FAQ? +|faq-2.9| I have a patch for implementing a Vim feature. Where do I send the + patch? +|faq-2.10| I have a Vim tip or developed a new Vim + syntax/indent/filetype/compiler plugin or developed a new script + or a colorscheme. Is there a public website where I can upload + this? + *faq-availability* +SECTION 3 - AVAILABILITY +|faq-3.1| What is the latest version of Vim? +|faq-3.2| Where can I find the latest version of Vim? +|faq-3.3| What platforms does it run on? +|faq-3.4| Where can I download the latest version of the Vim runtime files? + *faq-help* +SECTION 4 - HELP +|faq-4.1| How do I use the help files? +|faq-4.2| How do I search for a keyword in the Vim help files? +|faq-4.3| I am getting an error message E123, what did I do wrong? +|faq-4.4| Where can I read about the various modes in Vim? +|faq-4.5| How do I generate the Vim help tags file after adding a new Vim + help file? +|faq-4.6| Can I use compressed versions of the help files? + *faq-editing-a-file* +SECTION 5 - EDITING A FILE +|faq-5.1| How do I load a file in Vim for editing? +|faq-5.2| How do I save the current file in another name (save as) and edit + a new file? +|faq-5.3| How do I change the current directory to the directory of the + current file? +|faq-5.4| How do I write a file without the line feed (EOL) at the end of + the file? +|faq-5.5| How do I configure Vim to open a file at the last edited location? +|faq-5.6| When editing a file in Vim, which is being changed by an external + application, Vim opens a warning window (like the confirm dialog) + each time a change is detected. How do I disable this warning? +|faq-5.7| How do I edit a file whose name is under the cursor? +|faq-5.8| How do I reload/re-edit the current file? +|faq-5.9| How do I autosave a file periodically? +|faq-5.10| How do I open a file in read-only mode? + *faq-editing-multiple-files* +SECTION 6 - EDITING MULTIPLE FILES +|faq-6.1| How do I open multiple files at once from within Vim? +|faq-6.2| How do I switch between multiple files/buffers in Vim? +|faq-6.3| How do I open several files in Vim, with each file in a separate + window? +|faq-6.4| How do I configure Vim to autoload several files at once similar + to "work-sets" or "projects"? +|faq-6.5| Is it possible to open multiple top level windows in a single + instance of Vim similar to Nedit or emacs? +|faq-6.6| How do I browse/explore directories from within Vim? +|faq-6.7| How do I edit files over a network using ftp/scp/rcp/http? + *faq-backup* +SECTION 7 - BACKUP +|faq-7.1| When I edit and save files, Vim creates a file with the same name + as the original file and a "~" character at the end. How do I stop + Vim from creating this file (or) How do I disable the Vim backup + file feature? +|faq-7.2| How do I configure Vim to store all the backup files in a + particular directory? +|faq-7.3| When I save a file with Vim, the file permissions are changed. + How do I configure Vim to save a file without changing the file + permissions? + *faq-buffers* +SECTION 8 - BUFFERS +|faq-8.1| I have made some modifications to a buffer. How do I edit another + buffer without saving the modified buffer and also without losing + the modifications? +|faq-8.2| How do I configure Vim to auto-save a modified buffer when + switching to another buffer? +|faq-8.3| How do I replace the buffer in the current window with a blank + buffer? +|faq-8.4| Is there a keyboard shortcut to load a buffer by the buffer + number? +|faq-8.5| How do I open all the current buffers in separate windows? +|faq-8.6| How do I close (delete) a buffer without exiting Vim? +|faq-8.7| I have several buffers opened with ":e filename". How do I close + one of the buffers without exiting Vim? +|faq-8.8| When I use the command ":%bd" to delete all the buffers, not all + the buffers are deleted. Why? +|faq-8.9| How do I display the buffer number of the current buffer/file? +|faq-8.10| How do I delete a buffer without closing the window in which the + buffer is displayed? +|faq-8.11| How do I map the tab key to cycle through and open all the + buffers? + *faq-windows* +SECTION 9 - WINDOWS +|faq-9.1| What is the difference between a Vim window and a buffer? +|faq-9.2| How do I increase the width of a Vim window? +|faq-9.3| How do I zoom into or out of a window? +|faq-9.4| How do I execute an ex command on all the open buffers or open + windows or all the files in the argument list? + *faq-motion* +SECTION 10 - MOTION +|faq-10.1| How do I jump to the beginning (first line) or end (last line) of + a file? +|faq-10.2| In insert mode, when I press the key to go to command mode, + the cursor moves one character to the left (except when the cursor + is on the first character of the line). Is it possible to change + this behavior to keep the cursor at the same column? +|faq-10.3| How do I configure Vim to maintain the horizontal cursor position + when scrolling with the , , etc keys? +|faq-10.4| Some lines in a file are more than the screen width and they are + all wrapped. When I use the j, k keys to move from one line to the + next, the cursor is moved to the next line in the file instead of + the next line on the screen. How do I move from one screen line to + the next? +|faq-10.5| What is the definition of a sentence, paragraph and section in + Vim? +|faq-10.6| How do I jump to beginning or end of a sentence, paragraph or a + section? +|faq-10.7| I have lines in a file that extends beyond the right extent of the + screen. How do I move the Vim view to the right to see the text + off the screen? +|faq-10.8| How do I scroll two or more buffers simultaneously? +|faq-10.9| When I use my arrow keys, Vim changes modes, inserts weird + characters in my document but doesn't move the cursor properly. + What's going on? +|faq-10.10| How do I configure Vim to move the cursor to the end of the + previous line, when the left arrow key is pressed and the cursor + is currently at the beginning of a line? +|faq-10.11| How do I configure Vim to stay only in insert mode (modeless + editing)? +|faq-10.12| How do I display some context lines when scrolling text? +|faq-10.13| How do I go back to previous cursor locations? + *faq-searching-text* +SECTION 11 - SEARCHING TEXT +|faq-11.1| After I searched for a text with a pattern, all the matched text + stays highlighted. How do I turn off the highlighting + temporarily/permanently? +|faq-11.2| How do I enter a carriage return character in a search pattern? +|faq-11.3| How do I search for the character ^M? +|faq-11.4| How can I search/replace characters that display as '~R', '~S', + etc.? +|faq-11.5| How do I highlight all the non-printable characters in a file? +|faq-11.6| How do I search for whole words in a file? +|faq-11.7| How do I search for the current word under the cursor? +|faq-11.8| How do I search for a word without regard to the case (uppercase + or lowercase)? +|faq-11.9| How do I search for words that occur twice consecutively? +|faq-11.10| How do I count the number of times a particular word occurs in a + buffer? +|faq-11.11| How do I place the cursor at the end of the matched word when + searching for a pattern? +|faq-11.12| How do I search for an empty line? +|faq-11.13| How do I search for a line containing only a single character? +|faq-11.14| How do I search and replace a string in multiple files? +|faq-11.15| I am using the ":s" substitute command in a mapping. When a + search for a pattern fails, the map terminates. I would like the + map to continue processing the next command, even if the + substitute command fails. How do I do this? +|faq-11.16| How do I search for the n-th occurrence of a character in a + line? +|faq-11.17| How do I replace a tab (or any other character) with a hard + return (newline) character? +|faq-11.18| How do I search for a character by its ASCII value? +|faq-11.19| How do I search for long lines? +|faq-11.20| How do I display all the lines in the current buffer that + contain a specified pattern? +|faq-11.21| How do I search for a text string that spans multiple lines? +|faq-11.22| How do I search for a pattern only within a range of lines + in a buffer? + *faq-changing-text* +SECTION 12 - CHANGING TEXT +|faq-12.1| How do I delete all the trailing white space characters (SPACE + and TAB) at the end of all the lines in a file? +|faq-12.2| How do I replace all the occurrences of multiple consecutive + space characters to a single space? +|faq-12.3| How do I reduce a range of empty lines into one line only? +|faq-12.4| How do I delete all blank lines in a file? How do I remove all + the lines containing only space characters? +|faq-12.5| How do I copy/yank the current word? +|faq-12.6| How do I yank text from one position to another position within a + line, without yanking the entire line? +|faq-12.7| When I yank some text into a register, how do I append the text + to the current contents of the register? +|faq-12.8| How do I yank a complete sentence that spans over more than one + line? +|faq-12.9| How do I yank all the lines containing a pattern into a buffer? +|faq-12.10| How do I delete all the lines in a file that does not contain a + pattern? +|faq-12.11| How do I add a line before each line with "pattern" in it? +|faq-12.12| Is there a way to operate on a line if the previous line + contains a particular pattern? +|faq-12.13| How do I execute a command on all the lines containing a + pattern? +|faq-12.14| Can I copy the character above the cursor to the current cursor + position? +|faq-12.15| How do I insert a blank line above/below the current line + without entering insert mode? +|faq-12.16| How do I insert the name of current file into the current + buffer? +|faq-12.17| How do I insert the contents of a Vim register into the current + buffer? +|faq-12.18| How do I move the cursor past the end of line and insert some + characters at some columns after the end of the line? +|faq-12.19| How to replace the word under the cursor (say: junk) with + "foojunkbar" in Vim? +|faq-12.20| How do I replace a particular text in all the files in a + directory? +|faq-12.21| I have some numbers in a file. How do I increment or decrement + the numbers in the file? +|faq-12.22| How do I reuse the last used search pattern in a ":substitute" + command? +|faq-12.23| How do I change the case of a string using the ":substitute" + command? +|faq-12.24| How do I enter characters that are not present in the keyboard? +|faq-12.25| Is there a command to remove any or all digraphs? +|faq-12.26| In insert mode, when I press the backspace key, it erases only + the characters entered in this instance of insert mode. How do I + erase previously entered characters in insert mode using the + backspace key? +|faq-12.27| I have a file which has lines longer than 72 characters + terminated with "+" and wrapped to the next line. How can I + quickly join the lines? +|faq-12.28| How do I paste characterwise yanked text into separate lines? +|faq-12.29| How do I change the case (uppercase, lowercase) of a word or + a character or a block of text? +|faq-12.30| How do I enter ASCII characters that are not present in the + keyboard? +|faq-12.31| How do I replace non-printable characters in a file? +|faq-12.32| How do I remove duplicate lines from a buffer? +|faq-12.33| How do I prefix all the lines in a file with the corresponding + line numbers? +|faq-12.34| How do I exchange (swap) two characters or words or lines? + *faq-completion-in-insert-mode* +SECTION 13 - COMPLETION IN INSERT MODE +|faq-13.1| How do I complete words or lines in insert mode? +|faq-13.2| How do I complete file names in insert mode? +|faq-13.3| I am using CTRL-P/CTRL-N to complete words in insert mode. How do + I complete words that occur after the just completed word? + *faq-text-formatting* +SECTION 14 - TEXT FORMATTING +|faq-14.1| How do I format a text paragraph so that a new line is inserted + at the end of each wrapped line? +|faq-14.2| How do I format long lines in a file so that each line contains + less than 'n' characters? +|faq-14.3| How do I join short lines to the form a paragraph? +|faq-14.4| How do I format bulleted and numbered lists? +|faq-14.5| How do I indent lines in insert mode? +|faq-14.6| How do I format/indent an entire file? +|faq-14.7| How do I increase or decrease the indentation of the current + line? +|faq-14.8| How do I indent a block/group of lines? +|faq-14.9| When I indent lines using the > or < key, the standard 8-tabstops + are used instead of the current 'tabstop' setting. Why? +|faq-14.10| How do I turn off the automatic indentation of text? +|faq-14.11| How do I configure Vim to automatically set the 'textwidth' + option to a particular value when I edit mails? +|faq-14.12| Is there a way to make Vim auto-magically break lines? +|faq-14.13| I am seeing a lot of ^M symbols in my file. I tried setting the + 'fileformat' option to 'dos' and then 'unix' and then 'mac'. + None of these helped. How can I hide these symbols? +|faq-14.14| When I paste some text into a Vim buffer from another + application, the alignment (indentation) of the new text is + messed up. How do I fix this? +|faq-14.15| When there is a very long wrapped line (wrap is "on") and a line + doesn't fit entirely on the screen it is not displayed at all. + There are blank lines beginning with '@' symbol instead of + wrapped line. If I scroll the screen to fit the line the '@' + symbols disappear and the line is displayed again. What Vim + setting control this behavior? +|faq-14.16| How do I convert all the tab characters in a file to space + characters? +|faq-14.17| What Vim options can I use to edit text that will later go to a + word processor? + *faq-visual-mode* +SECTION 15 - VISUAL MODE +|faq-15.1| How do I do rectangular block copying? +|faq-15.2| How do I delete or change a column of text in a file? +|faq-15.3| How do I apply an ex-command on a set of visually selected lines? +|faq-15.4| How do I execute an ex command on a column of text selected in + Visual block mode? +|faq-15.5| How do I select the entire file in visual mode? +|faq-15.6| When I visually select a set of lines and press the > key to + indent the selected lines, the visual mode ends. How can I + reselect the region for further operation? (or) How do I + re-select the last selected visual area again? +|faq-15.7| How do I jump to the beginning/end of a visually selected region? +|faq-15.8| When I select text with mouse and then press : to enter an ex + command, the selected text is replaced with the : character. How + do I execute an ex command on a text selected using the mouse + similar to the text selected using the visual mode? +|faq-15.9| When I select a block of text using the mouse, Vim goes into + selection mode instead of Visual mode. Why? + *faq-command-line-mode* +SECTION 16 - COMMAND-LINE MODE +|faq-16.1| How do I use the name of the current file in the command mode or + an ex command line? +|faq-16.2| How do I edit the text in the Vim command-line effectively? +|faq-16.3| How do I switch from Vi mode to Ex mode? +|faq-16.4| How do I copy the output from an ex-command into a buffer? +|faq-16.5| When I press the tab key to complete the name of a file in the + command mode, if there are more than one matching file names, + then Vim completes the first matching file name and displays a + list of all matching filenames. How do I configure Vim to only + display the list of all the matching filenames and not complete + the first one? +|faq-16.6| How do I copy text from a buffer to the command line and from the + command line to a buffer? +|faq-16.7| How do I put a command onto the command history without executing + it? +|faq-16.8| How do I increase the height of the command-line? + *faq-viminfo* +SECTION 17 - VIMINFO +|faq-17.1| When I invoke Vim, I get error messages about illegal characters + in the viminfo file. What should I do to get rid of these + messages? +|faq-17.2| How do I disable the viminfo feature? +|faq-17.3| How do I save and use Vim marks across Vim sessions? + *faq-remote-editing* +SECTION 18 - REMOTE EDITING +|faq-18.1| How do I open a file with existing instance of gvim? What + happened to the Vim 5.x OpenWithVim.exe and SendToVim.exe files? +|faq-18.2| How do I send a command to a Vim server to write all buffers to + disk? +|faq-18.3| Where can I get the documentation about the Vim remote server + functionality? + *faq-options* +SECTION 19 - OPTIONS +|faq-19.1| How do I configure Vim in a simple way? +|faq-19.2| How do I toggle the value of an option? +|faq-19.3| How do I set an option that affects only the current + buffer/window? +|faq-19.4| How do I use space characters for a Vim option value? +|faq-19.5| Can I add (embed) Vim option settings to the contents of a file? +|faq-19.6| How do I display the line numbers of all the lines in a file? +|faq-19.7| How do I change the width of the line numbers displayed using the + "number" option? +|faq-19.8| How do I display (view) all the invisible characters like space, + tabs and newlines in a file? +|faq-19.9| How do I configure Vim to always display the current line and + column number? +|faq-19.10| How do I display the current Vim mode? +|faq-19.11| How do I configure Vim to show pending/partial commands on the + status line? +|faq-19.12| How do I configure the Vim status line to display different + settings/values? +|faq-19.13| How do I configure Vim to display status line always? +|faq-19.14| How do I make a Vim setting persistent across different Vim + invocations/instances/sessions? +|faq-19.15| Why do I hear a beep (why does my window flash) about 1 second + after I hit the Escape key? +|faq-19.16| How do I make the 'c' and 's' commands display a '$' instead of + deleting the characters I'm changing? +|faq-19.17| How do I remove more than one flag using a single ":set" command + from a Vim option? + *faq-mapping-keys* +SECTION 20 - MAPPING KEYS +|faq-20.1| How do I know what a key is mapped to? +|faq-20.2| How do list all the user-defined key mappings? +|faq-20.3| How do I unmap a key? +|faq-20.4| I am not able to create a mapping for the key. What is + wrong? +|faq-20.5| How do I map the numeric keypad keys? +|faq-20.6| How do I create a mapping that works only in visual mode? +|faq-20.7| In a Vim script, how do I know which keys to use for my mappings, + so that the mapped key will not collide with an already used key? +|faq-20.8| How do I map the escape key? +|faq-20.9| How do I map a key to perform nothing? +|faq-20.10| I want to use the Tab key to indent a block of text and + Shift-Tab key to unindent a block of text. How do I map the keys + to do this? This behavior is similar to textpad, visual studio, + etc. +|faq-20.11| In my mappings the special characters like are not + recognized. How can I configure Vim to recognize special + characters? +|faq-20.12| How do I use the '|' to separate multiple commands in a map? +|faq-20.13| If I have a mapping/abbreviation whose ending is the beginning of + another mapping/abbreviation, how do I keep the first from + expanding into the second one? +|faq-20.14| Why does it take a second or more for Vim to process a key, + sometimes when I press a key? +|faq-20.15| How do I map a key to run an external command using a visually + selected text? +|faq-20.16| How do I map the Ctrl-I key while still retaining the + functionality of the key? + *faq-abbreviations* +SECTION 21 - ABBREVIATIONS +|faq-21.1| How do I auto correct misspelled words? +|faq-21.2| How do I create multi-line abbreviations? +|faq-21.3| When my abbreviations are expanded, an additional space character + is added at the end of the expanded text. How do I avoid this + character? +|faq-21.4| How do I insert the current date/time stamp into the file? +|faq-21.5| How do I prevent an abbreviation from expanding in insert mode? + *faq-record-and-playback* +SECTION 22 - RECORD AND PLAYBACK +|faq-22.1| How do I repeat an editing operation (insertion, deletion, paste, + etc)? +|faq-22.2| How I record and repeat a set of key sequences? +|faq-22.3| How do I edit/modify a recorded set of key sequences? +|faq-22.4| How do I write recorded key sequences to a file? +|faq-22.5| I am using register 0 to record my key sequences (i.e. q0 .... + q). In the recorded key sequences, I am yanking some text. After + the first replay of the recorded key sequence, I am no longer + able to play it back. + *faq-autocommands* +SECTION 23 - AUTOCOMMANDS +|faq-23.1| How do I execute a command when I try to modify a read-only file? +|faq-23.2| How do I execute a command every time when entering a buffer? +|faq-23.3| How do I execute a command every time when entering a window? +|faq-23.4| From an autocmd, how can I determine the name of the file or the + buffer number for which the autocommand is executed? +|faq-23.5| How do I automatically save all the changed buffers whenever Vim + loses focus? +|faq-23.6| How do I execute/run a function when Vim exits to do some + cleanup? + *faq-syntax-highlight* +SECTION 24 - SYNTAX HIGHLIGHT +|faq-24.1| How do I turn off/on syntax highlighting? +|faq-24.2| How do I change the background and foreground colors used by Vim? +|faq-24.3| How do I change the highlight colors to suit a dark/light + background? +|faq-24.4| How do I change the color of the line numbers displayed when the + ":set number" command is used? +|faq-24.5| How do I change the background color used for a Visually selected + block? +|faq-24.6| How do I highlight the special characters (tabs, trailing spaces, + end of line, etc) displayed by the 'list' option? +|faq-24.7| How do I specify a colorscheme in my .vimrc/.gvimrc file, so that + Vim uses the specified colorscheme everytime? +|faq-24.8| Vim syntax highlighting is broken. When I am editing a file, some + parts of the file is not syntax highlighted or syntax highlighted + incorrectly. +|faq-24.9| Is there a built-in function to syntax-highlight the + corresponding matching bracket? +|faq-24.10| How do I turn off the C comment syntax highlighting? +|faq-24.11| How do I add my own syntax extensions to the standard syntax + files supplied with Vim? +|faq-24.12| How do I replace a standard syntax file that comes with the Vim + distribution with my own syntax file? +|faq-24.13| How do I highlight all the characters after a particular column? +|faq-24.14| How do I convert a source file (.c, .h, etc) with the Vim syntax + highlighting into a HTML file? +|faq-24.15| How do I list the definition of all the current highlight + groups? + *faq-vim-script-writing* +SECTION 25 - VIM SCRIPT WRITING +|faq-25.1| How do I list the names of all the scripts sourced by Vim? +|faq-25.2| How do I debug Vim scripts? +|faq-25.3| How do I locate the script/plugin which sets a Vim option? +|faq-25.4| I am getting some error/informational messages from Vim (possibly + when running a script), the messages are cleared immediately. How + do I display the messages again? +|faq-25.5| How do I save and restore a plugin specific information across + Vim invocations? +|faq-25.6| How do I start insert mode from a Vim function? +|faq-25.7| How do I change the cursor position from within a Vim function? +|faq-25.8| How do I check the value of an environment variable in the .vimrc + file? +|faq-25.9| How do I check whether an environment variable is set or not from + a Vim function? +|faq-25.10| How do I call/use the Vim built-in functions? +|faq-25.11| I am using some normal mode commands in my Vim script. How do I + avoid using the user-defined mappings for these normal mode + commands and use the standard Vim functionality for these normal + mode commands? +|faq-25.12| How do I get a visually selected text into a Vim variable or + register? +|faq-25.13| I have some text in a Vim variable 'myvar'. I would like to use + this variable in a ":s" substitute command to replace a text + 'mytext'. How do I do this? +|faq-25.14| A Vim variable (bno) contains a buffer number. How do I use this + variable to open the corresponding buffer? +|faq-25.15| How do I store the value of a Vim option into a Vim variable? +|faq-25.16| I have copied and inserted some text into a buffer from a Vim + function. How do I indent the inserted text from the Vim + function? +|faq-25.17| How do I get the character under the cursor from a Vim script? +|faq-25.18| How do I get the name of the current file without the extension? +|faq-25.19| How do I get the basename of the current file? +|faq-25.20| How do I get the output from a Vim function into the current + buffer? +|faq-25.21| How do I call external programs from a Vim function? +|faq-25.22| How do I get the return status of a program executed using the + ":!" command? +|faq-25.23| How do I determine whether the current buffer is modified or + not? +|faq-25.24| I would like to use the carriage return character in a normal + command from a Vim script. How do I specify the carriage return + character? +|faq-25.25| How do I split long lines in a Vim script? +|faq-25.26| When I try to "execute" my function using the "execute 'echo + Myfunc()'" command, the cursor is moved to the top of the + current buffer. Why? +|faq-25.27| How do I source/execute the contents of a register? +|faq-25.28| After calling a Vim function or a mapping, when I press the 'u' + key to undo the last change, Vim undoes all the changes made by + the mapping/function. Why? +|faq-25.29| How can I call a function defined with s: (script local + function) from another script/plugin? +|faq-25.30| Is it possible to un-source a sourced script? In otherwords, + reverse all the commands executed by sourcing a script. + *faq-plugins* +SECTION 26 - PLUGINS +|faq-26.1| How do I set different options for different types of files? +|faq-26.2| I have downloaded a Vim plugin or a syntax file or a indent file, + or a color scheme or a filetype plugin from the web. Where should + I copy these files so that Vim will find them? +|faq-26.3| How do I extend an existing filetype plugin? +|faq-26.4| How do I turn off loading the Vim plugins? +|faq-26.5| How do I turn on/off loading the filetype plugins? +|faq-26.6| How do I override settings made in a file type plugin in the + global ftplugin directory for all the file types? +|faq-26.7| How do I disable the Vim directory browser plugin? +|faq-26.8| How do I set the filetype option for files with names matching a + particular pattern or depending on the file extension? + *faq-editing-program-files* +SECTION 27 - EDITING PROGRAM FILES +|faq-27.1| How do I enable automatic indentation for C/C++ files? +|faq-27.2| How do I configure the indentation used for C/C++ files? +|faq-27.3| How do I turn off the automatic indentation feature? +|faq-27.4| How do I change the number of space characters used for the + automatic indentation? +|faq-27.5| I am editing a C program using Vim. How do I display the + definition of a macro or a variable? +|faq-27.6| I am editing a C program using Vim. How do I jump to the + beginning or end of a code block from within the block? +|faq-27.7| Is there a way to turn off the "//" comment auto-insertion + behavior for C++ files? If I'm sitting on a line beginning with + "//", then I open a new line above or below it, Vim automatically + inserts new "//" chars. +|faq-27.8| How do I add the comment character '#' to a set of lines at the + beginning of each line? +|faq-27.9| How do I edit a header file with the same name as the + corresponding C source file? +|faq-27.10| How do I automatically insert comment leaders while typing + comments? + *faq-quickfix* +SECTION 28 - QUICKFIX +|faq-28.1| How do I build programs from Vim? +|faq-28.2| When I run the make command in Vim I get the errors listed as the + compiler compiles the program. When it finishes this list + disappears and I have to use the :clist command to see the error + message again. Is there any other way to see these error + messages? + *faq-folding* +SECTION 29 - FOLDING +|faq-29.1| How do I extend the Vim folding support? +|faq-29.2| When I enable folding by setting the 'foldmethod' option, all the + folds are closed. How do I prevent this? +|faq-29.3| How do I control how many folds will be opened when I start + editing a file? +|faq-29.4| How do I open and close folds using the mouse? +|faq-29.5| How do I change the text displayed for a closed fold? +|faq-29.6| How do I store and restore manually created folds across + different Vim invocations? + *faq-vim-with-external-applications* +SECTION 30 - VIM WITH EXTERNAL APPLICATIONS +|faq-30.1| Can I run a shell inside a Vim window? +|faq-30.2| How do I pass the word under the cursor to an external command? +|faq-30.3| How do I get the output of a shell command into a Vim buffer? +|faq-30.4| How do I pipe the contents of the current buffer to an external + command and replace the contents of the buffer with the output + from the command? +|faq-30.5| How do I sort a section of my file? +|faq-30.6| Is there a step-by-step guide for using Vim with slrn? +|faq-30.7| How do I use Vim as a pager? +|faq-30.8| How do I view Unix man pages from inside Vim? +|faq-30.9| How do I change the diff command used by the Vim diff support? +|faq-30.10| How do I use the Vim diff mode without folding? + *faq-gui-vim* +SECTION 31 - GUI VIM +|faq-31.1| How do I create buffer specific menus? +|faq-31.2| How do I change the font used by GUI Vim? +|faq-31.3| When starting GUI Vim, how do I specify the location of the GVIM + window? +|faq-31.4| How do I add a horizontal scrollbar in GVim? +|faq-31.5| How do I make the scrollbar appear in the left side by default? +|faq-31.6| How do I remove the Vim menubar? +|faq-31.7| I am using GUI Vim. When I press the ALT key and a letter, the + menu starting with that letter is selected. I don't want this + behavior as I want to map the ALT- combination. How do I do + this? +|faq-31.8| Is it possible to scroll the text by dragging the scrollbar so + that the cursor stays in the original location? +|faq-31.9| How do I get gvim to start browsing files in a particular + directory when using the ":browse" command? +|faq-31.10| For some questions, like when a file is changed outside of Vim, + Vim displays a GUI dialog box. How do I replace this GUI dialog + box with a console dialog box? +|faq-31.11| I am trying to use GUI Vim as the editor for my xxx application. + When the xxx application launches GUI Vim to edit a file, the + control immediately returns to the xxx application. How do I + start GUI Vim, so that the control returns to the xxx + application only after I quit Vim? +|faq-31.12| Why does the "Select Font" dialog doesn't show all the fonts + installed in my system? +|faq-31.13| How do I use the mouse in Vim command-line mode? +|faq-31.14| When I use the middle mouse button to scroll text, it pastes the + last copied text. How do I disable this behavior? +|faq-31.15| How do I change the location and size of a GUI Vim window? + *faq-vim-on-unix* +SECTION 32 - VIM ON UNIX +|faq-32.1| I am running Vim in a xterm. When I press the CTRL-S key, Vim + freezes. What should I do now? +|faq-32.2| I am seeing weird screen update problems in Vim. What can I do to + solve this screen/display update problems? +|faq-32.3| I am using the terminal/console version of Vim. In insertmode, + When I press the backspace key, the character before the cursor + is not erased. How do I configure Vim to do this? +|faq-32.4| I am using Vim in a xterm. When I quit Vim, the screen contents + are restored back to the original contents. How do I disable + this? +|faq-32.5| When I start Vim, it takes quite a few seconds to start. How do I + minimize the startup time? +|faq-32.6| How can I make the cursor in gvim in unix stop blinking? +|faq-32.7| How do I change the menu font on GTK Vim? +|faq-32.8| How do I prevent from suspending Vim? +|faq-32.9| When I kill the xterm running Vim, the Vim process continues to + run and takes up a lot of CPU (99%) time. Why is this happening? +|faq-32.10| How do I get the Vim syntax highlighting to work in a Unix + terminal? + *faq-vim-on-ms-windows* +SECTION 33 - VIM ON MS-WINDOWS +|faq-33.1| In MS-Windows, CTRL-V doesn't start the blockwise visual mode. + What happened? +|faq-33.2| When I press the CTRL-Y key, it acts like the CTRL-R key. How do + I configure Vim to treat CTRL-Y as CTRL-Y? +|faq-33.3| How do I start GUI Vim in a maximized window always? +|faq-33.4| After doing some editing operations, Vim freezes. The cursor + becomes an empty rectangle. I am not able enter any characters. + What is happening? +|faq-33.5| I am using Windows XP, the display speed of maximized GVim is + very slow. What can I do to speed the display updates? +|faq-33.6| What are the recommended settings for using Vim with cygwin? +|faq-33.7| I am trying to use GNU diff with Vim diff mode. When I run the + diff from command line, it works. When I try to use the diff with + Vim it doesn't work. What should I do now? +|faq-33.8| Is it possible to use Vim as an external editor for MS-Windows + Outlook email client? +|faq-33.9| I am using Vim to edit HTML files. How do I start internet + explorer with the current file to preview the HTML file? +|faq-33.10| I would like to use Vim with Microsoft Visual Studio. How do I + do this? +|faq-33.11| Where do I place the _vimrc and _gvimrc files? +|faq-33.12| Everytime I save a file, Vim warns about the file being changed + outside of Vim. Why? + *faq-printing* +SECTION 34 - PRINTING +|faq-34.1| How do I print a file along with line numbers for all the lines? +|faq-34.2| How do I print a file with the Vim syntax highlighting colors? + *faq-building-vim-from-source* +SECTION 35 - BUILDING VIM FROM SOURCE +|faq-35.1| How do I build Vim from the sources on a Unix system? +|faq-35.2| How do I install Vim in my home directory or a directory other + than the default installation directory in Unix? +|faq-35.3| How do I build Vim from the sources on a MS-Windows system? +|faq-35.4| The Vim help, syntax, indent files are missing from my Vim + installation. How do I install these files? +|faq-35.5| I have built Vim from the source and installed the Vim package + using "make install". Do I need to keep the Vim source directory? +|faq-35.6| How do I determine the Vim features which are enabled at compile + time? +|faq-35.7| Can I build Vim without the GUI support? +|faq-35.8| When building Vim on a Unix system, I am getting "undefined + reference to term_set_winsize' error. How do I resolve this + error? +|faq-35.9| Vim configure keeps complaining about the lack of gtk-config + while trying to use GTK 2.03. This is correct, since in GTK 2 + they moved to using the generic pkg-config. I can get pkg-config + to list the various includes and libs for gtk, but for some + reason the configure script still isn't picking this up. + *faq-various* +SECTION 36 - VARIOUS +|faq-36.1| How do I edit binary files with Vim? +|faq-36.2| How do I disable the visual error flash and the error beep? +|faq-36.3| How do I display the ascii value of a character displayed in a + buffer? +|faq-36.4| Can I use zero as a count for a Vim command? +|faq-36.5| How do I disable the Vim welcome screen? +|faq-36.6| How do I avoid the "hit enter to continue" prompt? +|faq-36.7| How do I invoke Vim from command line to run a group of commands + on a group of files? +|faq-36.8| How do I use a normal mode command from insert mode without + leaving the insert mode? + *faq-unicode* +SECTION 37 - UNICODE +|faq-37.1| Is it possible to create Unicode files using Vim? +|faq-37.2| Which Vim settings are particularly important for editing Unicode + files? +|faq-37.3| What is the 'encoding' option? +|faq-37.4| How does Vim name the various Unicode encodings? +|faq-37.5| How does Vim specify the presence or absence of a byte-order + mark? +|faq-37.6| What is the 'fileencoding' option? +|faq-37.7| What is the 'fileencodings' option? +|faq-37.8| What is the 'termencoding' option? +|faq-37.9| What is the 'bomb' option? +|faq-37.10| Where can I find an example of a typical use of all these + options? +|faq-37.11| How can I insert Unicode characters into a file using Vim? +|faq-37.12| How can I know which digraphs are defined and for which + characters? + +============================================================================= + *faq-1* +SECTION 1 - GENERAL INFORMATION + + *faq-1.1* +1.1. What is Vim? + +Vim stands for Vi IMproved. It used to be Vi IMitation, but there are so +many improvements that a name change was appropriate. Vim is a text editor +which includes almost all the commands from the Unix program "Vi" and a lot +of new ones. All commands can be given with the keyboard. This has the +advantage that you can keep your fingers on the keyboard and your eyes on +the screen. For those who want it, there is mouse support and a GUI version +with scrollbars and menus. + +Vim is an editor, not a word processor. A word processor is used mainly to +do layout of text. This means positioning it, changing the way it appears +on output. More often than not, the final document is meant to be printed +or typeset or what have you, in order to present it in a pleasing manner to +others. Examples of word processors are Microsoft Word, WordPerfect, +FrameMaker, and AmiPro. + +An editor is simply for entering text. Any typesetting or laying out of the +document is secondary. With an editor, one's main concern is entering text, +not making the text look good. Examples of editors other than Vim and Vi +are Emacs, Crisp, Brief, and xedit. And Notepad. + +For more information, read > + + :help intro +< + *faq-1.2* +1.2. Who wrote Vim? + +Most of Vim was written by Bram Moolenar, with contributions from too many +people to mention here. See ":h credits" for a complete list. + +Vim is based on Stevie, worked on by Tim Thompson, Tony Andrews and G.R. +(Fred) Walter. + +For more information, read > + + :help author +< + *faq-1.3* +1.3. Is Vim compatible with Vi? + +Yes. Vim is very much compatible with Vi. You can use the "-C" +command-line flag to start Vim in Vi compatible mode: > + + $ vim -C +< +You can also use: > + + $ vim -u NONE +< +You can also set the 'compatible' option to enable Vi compatibility: > + + :set compatible +< +For more information, read > + + :help -C + :help 'compatible' + :help compatible-default +< + *faq-1.4* +1.4. What are some of the improvements of Vim over Vi? + +A short summary of the improvements of Vim over vi is listed below. The +list shows that Vim is a thoroughly modern and feature-packed editor. +Standard features of modern editors are implemented, and there is an equal +emphasis on general power-user features and features for programmers. + +Features to modernise Vi: + + Multi-level undo + Allows you to set the number of times you can undo your changes in a + file buffer. You can also redo an undone change. + Multiple windows and buffers + Each file can be displayed in its own window. You can move easily from + one window to another. Each file opened during a Vim session also has + an associated buffer and you can easily jump from one to the other. + Flexible insert mode + Vim allows you to use the arrow keys while in insert mode to move + around in the file. No more hitting , moving around, then hitting + `i' or `a'. + Macros + Vim has a facility which allows you to record a sequence of typed + characters and repeat them any number of times. + Visual mode + You can highlight sections of text and execute operations on this + section of text only. + Block operators + Allow selection and highlighting of rectangular blocks of text in + order do execute specific operations on them. + Online help system + You can easily find help on any aspect of using Vim. Help is displayed + in its own window. + Command-line editing and history + History allows you to use the arrow keys to repeat or search for a + command that has already been typed. Allows you to match the beginning + of a command with the beginning of another similar command in the + history buffer. You can also edit a command to correct typos or change + a few values. + Command line completion. + Using the key, you can complete commands, options, filenames, + etc. as needed. + Horizontal scrolling. + Long lines can be scrolled horizontally (with or without the GUI). + +Advanced user features: + + Text formatting. + With two keystrokes, you can format large sections of text, without + the use of external programs. + Word completion in Insert mode + Vim can complete words while you are typing, by matching the current + word with other similar words in the file. + Jump tags + Just like in an internet browser, you can jump back to previous parts + of the text you were editing, and then forward again. Your brain is + thus free to edit instead of navigate. + Automatic commands + Commands automatically executed when reading or writing a file, + jumping to another buffer, etc. + Viminfo + Allows storing of the command line history, marks and registers in a + file to be read on startup. Therefore, you can recall old search + patterns, macros, etc., in a new Vim session. + Mouse support + The mouse is supported in an xterm and for MS-DOS. It can be used to + position the cursor, select the visual area, paste a register, etc. + Graphical User Interface (GUI) + Just like any modern editor. Also, it's very easy to add your own + menus. Of course, console vim is still supported, and very widely + used. + Scripting language + Vim has a powerful scripting language so new commands can be created. + You can also use Perl, Python, TCL and Ruby to achieve the same thing! + Plugins + Extra functionality implemented via vim commands (regular commands or + the scripting language) that is automatically loaded on startup. + Examples: file explorer, network editing. More are being developed + and shared on VimOnline all the time. + Syntax highlighting for many programming languages + Syntax highlighting for hundreds of programming languages is + supported. Support for others can be added. + Extended regular expressions + Vim supports extended regular expressions which are similar in + functionality to that of perl regular expressions. + +Programming performance features: + + Edit-compile-edit speedup + You can compile within Vim and automatically jump to the location of + errors in the source code. + Indenting for many programming languages + C, C++, Java, Perl, XML and many other languages can be automatically + indented by vim while you type. Support for others can be added. + Searching for words in include files + Vim allows you to search for a match of the word under the cursor in + the current and included files. + Advance text objects + Instantly select, or delete, or copy, or indent, or format, or change + case, or ... to all the text between ( and ), or { and }, or < and >, + or [ and ]. Or a word, sentence, or paragraph. Very powerful. + Folding + Certain parts of the text can be "folded" away. The best example is + the body of a function. You can get an overview of the code, and then + open the fold of the function whose detail you need to see. + ctags and cscope integration + Using these two powerful programs, you can jump to a definition of a + function from a calling instance of it, and use other tricks to + navigate source code. + +For more information, read > + + :help vi-differences +< + *faq-1.5* +1.5. Is Vim free? + +Vim is Charityware. There are no restrictions on using or copying Vim, but +the author encourages you to make a donation to charity. A document +explaining how to do so is included in the distribution. + +For more information, read > + + :help copyright +< + +============================================================================= + *faq-2* +SECTION 2 - RESOURCES + + *faq-2.1* +2.1. Where can I learn more about Vim? + +You can post your Vim questions to the vim@vim.org mailing list. You can +post your Vim development related questions to the vim-dev@vim.org mailing +list. Vim does not have a newsgroup of its own. But the appropriate +newsgroup to post to is comp.editors. + +"VimOnline" is a web page that serves as a de facto homepage for vim, +although the main purpose of it is to gather tips and scripts from +everywhere. Get involved! The URL is vim.sourceforge.net or vim.sf.net. + +Finally, read the Vi FAQ: > + + http://www.faqs.org/faqs/editor-faq/vi/part1/index.html +< +For more information, read > + + :help mail-list + :help internet +< + *faq-2.2* +2.2. Is there a mailing list available? + +There are several: > + + NAME DESCRIPTION +< + vim-announce Announcements of new releases + vim General discussion + vim-dev Patches, bug reports, development discussions + vim-mac Macintosh discussion + vim-fr General discussion in French + vim-multibyte Multibyte development issues + vim-vms Development on VMS + +Of these, only vim and vim-dev are of general interest. vim-announce is +read-only to most people, and its messages are sent to the other lists as +well. The remaining four are very low volume. + +To subscribe: send an email to -subscribe@vim.org +To unsubscribe: send an email to -unsubscribe@vim.org +To get help: send an email to -help@vim.org + + *faq-2.3* +2.3. Is there an archive available for the Vim mailing lists? + +Yes. Visit http://www.yahoogroups.com/list/, where name is one of: +vimannounce, vim, vimdev, vim-fr, vim-mac, vim-multibyte, vim-vms. + +Alternatively, visit www.gmane.org to find out about GMANE, which allows +you to access the mailing lists as though they were newsgroups. This +offers some convenience to those who wish to browse the history or casually +observe the current threads. + + *faq-2.4* +2.4. Where can I get the Vim user manual in HTML/PDF/PS format? + +You can download the HTML/PDF/PS format of the Vim user manual from: > + + http://vimdoc.sourceforge.net/ +< + *faq-2.5* +2.5. I have a "xyz" (some) problem with Vim. How do I determine it is a + problem with my setup or with Vim? + +First, you have to determine that the problem is not with your .vimrc or +.gvimrc or system vimrc or your personal plugin files or in any of your +setup files. To do this, use > + + $ vim -N -u NONE -U NONE +< +This will start Vim in 'nocompatible" mode and will not source your +personal .vimrc and .gvimrc files. It will also not load your personal +plugins. In this invocation of Vim, try to reproduce your problem. If you +are not able to reproduce the problem, then the problem is related to some +setting in one of your local setup files or plugins. To locate the problem +in your setup files, you have to use trial and error and try commenting out +the lines in your setup files one by one. You can also use the -V command +line argument to Vim to get more debug information and analyze the problem: > + + $ vim -V2 +< +You can increase the value passed to the -V argument to get more debug +information. + +For more information, read > + + :help -u + :help -U + :help -N + :help -V + :help 'verbose' + :help :verbose + :help set-verbose +< + *faq-2.6* +2.6. Where can I report bugs? + +First collect the required information using the following command: > + + :source $VIMRUNTIME/bugreport.vim +< +Now send the resulting text from the above command to the bugs@vim.org +e-mail address. + +The Vim Development mailing list (see above) is a good place to discuss +general bugs. If the bug you find is with syntax highlighting or some +other "added feature" (i.e. not directly programmed into vim), attempt to +inform the maintainer of that feature. + +For more information, read > + + :help bug-reports +< + *faq-2.7* +2.7. Where can the FAQ be found? + +The FAQ can be found at VimOnline (vim.sf.net). Other places will be +decided in the future. + + *faq-2.8* +2.8. What if I don't find an answer in this FAQ? + +This FAQ covers mainly Vim-specific questions. You may find more +information suitable for most Vi clones by reading the Vi FAQ. It is posted +regularly on comp.editors. You can also find a copy at > + + http://www.faqs.org/faqs/editor-faq/vi/part1/index.html +< +Also, since Vim has gathered so many features in the last few years, +successfully documenting the frequently asked questions here is a +near-impossible task. To make it possible, please email the maintainer if +you have a good question. A good question is one that you've tried to +answer yourself (remember, Vim has great documentation) but struggled. + + *faq-2.9* +2.9. I have a patch for implementing a Vim feature. Where can I send this + patch? + +You can send your patches to the Vim developer mailing list +vim-dev@vim.org. + +For more information, read > + + :help vim-dev +< + *faq-2.10* +2.10. I have a Vim tip or developed a new Vim + syntax/indent/filetype/compiler plugin or developed a new script or a + colorscheme. Is there a public website where I can upload this? + +Yes. You can use the Vim Online website to upload your plugins/scripts, +colorschemes, tips, etc. The site is at http://vim.sourceforge.net + +============================================================================= + *faq-3* +SECTION 3 - AVAILABILITY + + *faq-3.1* +3.1. What is the latest version of Vim? + +The latest version of Vim is 6.3 released on 8th June 2004. + +The release-history of different versions of Vim is below: + +Version 6.3 8th June 2004 +Version 6.2 1st June 2003 +Version 6.1 24th March 2002 +Version 6.0 27th September, 2001 +Version 5.8 31st May, 2001 +Version 5.7 24th June, 2000 +Version 5.6 16th January, 2000 +Version 5.5 21st September, 1999 +Version 5.4 26th July, 1999 +Version 5.3 31st August, 1998 +Version 5.2 24th August, 1998 +Version 5.1 7th April, 1998 +Version 5.0 19th February, 1998 +Version 4.6 13th March,1997 +Version 4.5 17th October, 1996 +Version 4.2 5th July,1996 +Version 4.0 21st May, 1996 +Version 3.0 16th August, 1994 +Version 2.0 21st December, 1993 +Version 1.27 23rd April, 1993 +Version 1.17 21st April, 1992 + + *faq-3.2* +3.2. Where can I find the latest version of Vim? + +You can download the sources for the latest version of Vim from the +VimOnline website. The URL for this site is +http://vim.sourceforge.net/download.php. + + *faq-3.3* +3.3. What platforms does it run on? + +All Unix platforms. +All Windows platforms. +Amiga, Atari, BeOS, DOS, Macintosh, MachTen, OS/2, RiscOS, VMS. + + *faq-3.4* +3.4. Where can I download the latest version of the Vim runtime files? + +You can download the latest version of the Vim runtime files (syntax files, +filetype plugins, compiler files, color schemes, documentation, indentation +files and keymaps) from the Vim ftp site from the +ftp://ftp.vim.org/pub/vim/runtime directory. + +============================================================================= + *faq-4* +SECTION 4 - HELP + + *faq-4.1* +4.1. How do I use the help files? + +Help can be found for all functions of Vim. In order to use it, use the +":help" command. This will bring you to the main help page. On that first +page, you will find explanations on how to move around. Basically, you move +around in the help pages the same way you would in a read-only document. +You can jump to specific subjects by using tags. This can be done in two +ways: + + * Use the "" command while standing on the name of a command or + option. This only works when the tag is a keyword. "" + and "g" work just like "". + * use the ":tag " command. This works with all characters. + +Use "" to jump back to previous positions in the help files. Use +":q" to close the help window. + +If you want to jump to a specific subject on the help pages, use ":help +{subject}". If you don't know what to look for, try ":help index" to get a +list of all available subjects. Use the standard search keys to locate the +information you want. You can abbreviate the ":help" command as ":h". + +For more information, read > + + :help online-help +< + *faq-4.2* +4.2. How do I search for a keyword in the Vim help files? + +You can press the CTRL-D key after typing the help keyword to get a list of +all the help keywords containing the supplied pattern. You can also use the +meta characters like *, \+, etc to specify the help search pattern: > + + :help init + :help str*() + :help '*indent +< +You can press the Tab key after typing a partial help keyword to expand to +the matching keyword. You can continue to press the Tab key to see other +keyword matches. + +From the help window, you can use the ":tag" command to search for +keywords. For example, > + + :tselect /window +< +This command will list all the help keywords containing the text "window". +You can select one from the list and jump to it. + +You can use the ":helpgrep" command to search for the given text in all the +help files. The quickfix window will be opened with all the matching lines. + +For more information, read > + + :help c_CTRL-D + :help c_ + :help :tselect + :help :help + :help :helpgrep +< + *faq-4.3* +4.3. I am getting an error message E123, what did I do wrong? + +You can get more information about the error and the error message using: > + + :help E123 +< +For more information, read > + + :help error-messages +< + *faq-4.4* +4.4. Where can I read about the various modes in Vim? + +You can get information about the different modes in Vim by reading > + + :help vim-modes +< + *faq-4.5* +4.5. How do I generate the Vim help tags file after adding a new Vim help + file? + +You can use the ":helptags" command to regenerate the Vim help tag file. +For example: > + + :cd $VIMRUNTIME/doc + :helptags . +< +For more information, read > + + :help :helptags + :help add-local-help +< + *faq-4.6* +4.6. Can I use compressed versions of the help files? + +Yes. You can compress the help files and still be able to view them with +Vim. This makes accessing the help files a bit slower and requires the +"gzip" utility. Follow these steps to compress and use the Vim help files: + +- Compress all the help files using "gzip ddoc/*.txt". + +- Edit the "doc/tags" file and change the "".txt" to ".txt.gz" using + :%s=\(\t.*\.txt\)\t=\1.gz\t= + +- Add the following line to your vimrc: + set helpfile={dirname}/help.txt.gz + +Where {dirname} is the directory where the help files are. The gzip.vim +plugin supplied with the standard Vim distribution will take care of +decompressing the files. You must make sure that $VIMRUNTIME is set to +where the other Vim files are, when they are not in the same location as +the compressed "doc" directory. + +For more information, read > + + :help gzip-helpfile + :help 'helpfile' + :help gzip + :help $VIMRUNTIME +< + +============================================================================= + *faq-5* +SECTION 5 - EDITING A FILE + + *faq-5.1* +5.1. How do I load a file in Vim for editing? + +There are several ways to load a file for editing. The simplest is to +use the ":e" (:edit) command: > + + :e +< +You can also use the ":n" (:next) command to load files into Vim: > + + :n +< +You can also use the ":args" command to load files into Vim: > + + :args +< +For more information, read > + + :help usr_07 + :help edit-files + :help :edit + :help :next_f + :help :args_f +< + *faq-5.2* +5.2. How do I save the current file in another name (save as) and edit a + new file? + +You can use the ":saveas" command to save the current file in another name: > + + :saveas +< +Alternatively, you can also use the following commands: > + + :w + :edit # +< +You can also use the ":file" command, followed by ":w" command: > + + :file + :w +< +For more information, read > + + :help 07.7 + :help :saveas + :help :file_f + :help :w +< + *faq-5.3* +5.3. How do I change the current directory to the directory of the current + file? + +You can use the following command to change the current directory to the +directory of the current file: > + + :cd %:p:h +< +To automatically change the current directory to the directory of the +current file, use the following autocmd: > + + :autocmd BufEnter * cd %:p:h +< +For more information, read > + + :help :cd + :help :lcd + :help filename-modifiers + :help autocommand +< + *faq-5.4* +5.4. How do I write a file without the line feed (EOL) at the end of the + file? + +You can turn off the 'eol' option and turn on the 'binary' option to write +a file without the EOL at the end of the file: > + + :set binary + :set noeol + :w +< +For more information, read > + + :help 'endofline' + :help 'binary' + :help 23.4 +< + *faq-5.5* +5.5. How do I configure Vim to open a file at the last edited location? + +Vim stores the cursor position of the last edited location for each buffer +in the '"' register. You can use the following autocmd in your .vimrc or +.gvimrc file to open a file at the last edited location: > + + au BufReadPost * if line("'\"") > 0 && line("'\"") <= line("$") | + \ exe "normal g'\"" | endif +< +For more information, read > + + :help '" + :help last-position-jump +< + *faq-5.6* +5.6. When editing a file in Vim, which is being changed by an external + application, Vim opens a warning window (like the confirm dialog) each + time a change is detected. How do I disable this warning? + +You can set the Vim 'autoread' option to automatically read the file again +when it is changed outside of Vim: > + + :set autoread +< +You can also use the following autocommand: > + + autocmd FileChangedShell * + \ echohl WarningMsg | + \ echo "File has been changed outside of vim." | + \ echohl None +< +For more information, read > + + :help 'autoread' + :help FileChangedShell + :help timestamp + :help :checktime +< + *faq-5.7* +5.7. How do I edit a file whose name is under the cursor? + +You can use the gf command to edit a file whose name is under the cursor. +You can use the CTRL-W f command to edit the file in a new window. + +For more information, read > + + :help gf + :help CTRL-W_f + :help 'isfname' + :help 'path' + :help 'suffixesadd' + :help 'includeexpr' +< + *faq-5.8* +5.8. How do I reload/re-edit the current file? + +You can use the ":edit" command, without specifying a file name, to reload +the current file. If you have made modifications to the file, you can use +":edit!" to force the reload of the current file (you will lose your +modifications). + +For more information, read > + + :help :edit + :help :edit! + :help 'confirm' +< + *faq-5.9* +5.9. How do I autosave a file periodically? + +Vim doesn't support auto-saving a file periodically. + +For more information, read > + + :help 'updatetime' + :help CursorHold + :help swap-file +< + *faq-5.10* +5.10. How do I open a file in read-only mode? + +You can open a file in read-only mode using the ":view" command: > + + :view +< +This command sets the 'readonly' option for the opened buffer. You can also +use the "-R" command-line option to open a file in read-only mode: > + + $ vim -R +< +You can also use the symbolic link executable "view" to open a file in +read-only mode from the command-line: > + + $ view +< +For more information, read > + + :help 07.6 + :help 'readonly' + :help 'modifiable' + :help :view + :help :sview + :help view + :help -R + :help -M +< + +============================================================================= + *faq-6* +SECTION 6 - EDITING MULTIPLE FILES + + *faq-6.1* +6.1. How do I open multiple files at once from within Vim? + +There are several ways to open multiple files at once from within Vim. You +can use the ":next" command to specify a group of files: > + + :next f1.txt f2.txt + :next *.c +< +You can use the :args command to specify a group of files as arguments: > + + :args f1.txt f2.txt + :args *.c +< +After loading the files, you can use the ":next" and ":prev" command to +switch between the files. + +For more information, read > + + :help 07.2 + :help :next + :help :args_f + :help argument-list +< + *faq-6.2* +6.2. How do I switch between multiple files/buffers in Vim? + +There are several ways to switch between multiple files. You can use the +":buffer" command to switch between multiple files. For example, > + + :buffer file1 + :buffer file2 +< +You can also use the CTRL-^ key to switch between buffers. By specifying a +count before pressing the key, you can edit the buffer with that number. +Without the count, you can edit the alternate buffer by pressing CTRL-^ + +You can also use the ":e #" command to edit a particular buffer: > + + :e #5 +< +For more information, read > + + :help edit-files + :help :buffer + :help CTRL-^ + :help alternate-file + :help 22.4 + :help 07.3 +< + *faq-6.3* +6.3. How do I open several files in Vim, with each file in a separate + window? + +You can use the -o and -O Vim command line arguments to open multiple files +in separate horizontally or vertically split Vim windows. For example: > + + $ vim -o3 f1.txt f2.txt f3.txt +< +The above command will open the files f1.txt, f2.txt and f3.txt in three +separate horizontally split Vim windows. > + + $ vim -O3 f1.txt f2.txt f3.txt +< +The above command will open the files f1.txt, f2.txt and f3.txt in three +separate vertically split Vim windows. + +For more information, read > + + :help -o + :help -O + :help startup-options +< + *faq-6.4* +6.4. How do I configure Vim to autoload several files at once similar to + "work-sets" or "projects"? + +You can use the ":mksession" and the ":mkview" commands to autoload several +files in Vim. + +The ":mksession" command creates a Vim script that restores the current +editing session. You can use the ":source" command to source the file +produced by the mksession command. + +The ":mkview" command creates a Vim script that restores the contents of +the current window. You can use the ":loadview" command to load the view +for the current file. + +For more information, read > + + :help 21.4 + :help 21.5 + :help views-sessions + :help 'sessionoptions' + :help :mksession + :help :source + :help v:this_session + :help :mkview + :help :loadview + :help 'viewdir' + :help buffers +< + *faq-6.5* +6.5. Is it possible to open multiple top level windows in a single instance + of Vim similar to Nedit or emacs? + +No. It is currently not possible to open multiple top-level windows in a +single instance of Vim. This feature is in the todo list. + + *faq-6.6* +6.6. How do I browse/explore directories from within Vim? + +You can use the explorer.vim plugin, supplied with the standard Vim +installation, to browse/explore directories from within Vim. You can start +the file explorer using one of the following commands: > + + :e + :Explore + :SExplore +< +From the file explorer, you can browse through directories, rename, delete +and edit files. + +For more information, read > + + :help file-explorer + :help 22.1 +< + *faq-6.7* +6.7. How do I edit files over a network using ftp/scp/rcp/http? + +You can use the netrw.vim plugin, supplied with the standard Vim package, +to edit files over a network using ftp/scp/rcp/http. Using this plugin, Vim +will transparently load and save the files over ftp/scp/rcp/http. For +example, to edit a file over ftp, you can use the following command: > + + $ vim ftp://machine/path +< +For more information, read > + + :help netrw.vim +< + +============================================================================= + *faq-7* +SECTION 7 - BACKUP + + *faq-7.1* +7.1. When I edit and save files, Vim creates a file with the same name as + the original file and a "~" character at the end. How do I stop Vim + from creating this file? (or) How do I disable the Vim backup file + feature? + +You have set the 'backup' option, so Vim creates a backup file when saving +the original file. You can stop Vim from creating the backup file, by +clearing the option: > + + :set nobackup +< +Note that, by default this option is turned off. You have explicitly +enabled the 'backup' option in one of the initialization files. You may +also have to turn off the 'writebackup' option: > + + :set nowritebackup +< +For more information, read > + + :help 07.4 + :help backup-table + :help 'backup' + :help 'writebackup' + :help 'backupskip' + :help 'backupdir' + :help 'backupext' + :help 'backupcopy' + :help backup +< + *faq-7.2* +7.2. How do I configure Vim to store all the backup files in a particular + directory? + +You can configure Vim to store all the backup files in a particular +directory using the 'backupdir' option. For example, to store all the +backup files in the ~/backup directory, you can use the following command: > + + :set backupdir=~/backup +< +For more information, read > + + :help 07.4 + :help 'backupdir' + :help backup +< + *faq-7.3* +7.3. When I save a file with Vim, the file permissions are changed. + How do I configure Vim to save a file without changing the file + permissions? + +This may happen, if the 'backupcopy' option is set to 'no' or 'auto'. Note +that the default value for this option is set in such a way that this will +correctly work in most of the cases. If the default doesn't work for you, +try setting the 'backupcopy' option to 'yes' to keep the file permission +when saving a file: > + + :set backupcopy=yes +< +This applies, only if you have configured Vim to make a backup whenever +overwriting a file. By default, Vim will not backup files. + +For more information, read > + + :help 'backupcopy' + :help backup + :help 'backup' + :help 'writebackup' +< + +============================================================================= + *faq-8* +SECTION 8 - BUFFERS + + *faq-8.1* +8.1. I have made some modifications to a buffer. How do I edit another + buffer without saving the modified buffer and also without losing the + modifications? + +You can set the 'hidden' option to edit a file without losing modifications +to the current file: > + + :set hidden +< +By setting the 'hidden' option, you can also save the modification history +(undo-history) for the buffer. Otherwise, as you switch between files, the +undo-history will be lost. + +For more information, read > + + :help 'hidden' + :help hidden-quit + :help :hide +< + *faq-8.2* +8.2. How do I configure Vim to auto-save a modified buffer when switching + to another buffer? + +You can set the 'autowrite' option to auto-save a modified buffer when +switching to another buffer: > + + :set autowrite +< +For more information, read > + + :help 'autowrite' + :help 'autowriteall' + :help 'hidden' +< + *faq-8.3* +8.3. How do I replace the buffer in the current window with a blank buffer? + +You can use the ":enew" command to load an empty buffer in place of the +buffer in the current window. + +For more information, read > + + :help :enew +< + *faq-8.4* +8.4. Is there a keyboard shortcut to load a buffer by the buffer number? + +You can use the CTRL-^ command to load a buffer by specifying the buffer +number. For example, to load buffer number 5, you have to use the 5 CTRL-^ +command. + +For more information, read > + + :help CTRL-^ +< + *faq-8.5* +8.5. How do I open all the current buffers in separate windows? + +You can use the ":ball" or ":sball" commands to open all the buffers +in the buffer list: > + + :ball +< +For more information, read > + + :help :ball +< + *faq-8.6* +8.6. How do I close (delete) a buffer without exiting Vim? + +You can use the ":bdelete" command to delete a buffer without exiting Vim. +For example: > + + :bdelete file1 +< +For more information, read > + + :help :bdelete + :help :bwipeout +< + *faq-8.7* +8.7. I have several buffers opened with :e filename. How do I close one of + the buffers without exiting Vim? + +You can use the ":bdelete " command to close the buffer. + +For more information, read > + + :help :bdelelete + :help :bunload + :help :bwipeout +< + *faq-8.8* +8.8. When I use the command ":%bd" to delete all the buffers, not all the + buffers are deleted. Why? + +In the ":%bd" command, the '%' range will be replaced with the starting and +ending line numbers in the current buffer. Instead of using '%' as the +range, you should specify numbers for the range. For example, to delete all +the buffers, you can use the command ":1,9999bd". + +For more information, read > + + :help :bd +< + *faq-8.9* +8.9. How do I display the buffer number of the current buffer/file? + +You can use 2 command to display the buffer number for the current +file/buffer. Note the use of count before the CTRL-G command. If the count +is greater than 1, then Vim will display the buffer number. + +You can also use the following command to display the current buffer +number: > + + :echo bufnr("%") +< +You can also include the "%n" field to the 'statusline' option to display +the current buffer number on the statusline. + +For more information read, > + + :help CTRL-G + :help bufnr() + :help :echo + :help 'statusline' +< + *faq-8.10* +8.10. How do I delete a buffer without closing the window in which the + buffer is displayed? + +You can use the following command to open the next buffer and delete +the current buffer. > + + :bnext | bdelete # +< +For more information read, > + + :help :bnext + :help :bdelete + :help :buffers +< + *faq-8.11* +8.11. How do I map the tab key to cycle through and open all the buffers? + +You can use the following two map commands, to map the CTRL-Tab key to open +the next buffer and the CTRL-SHIFT-Tab key to open the previous buffer: > + + :nnoremap :bnext + :nnoremap :bprevious +< +For more information read, > + + :help :bnext + :help :previous +< + +============================================================================= + *faq-9* +SECTION 9 - WINDOWS + + *faq-9.1* +9.1. What is the difference between a Vim window and a buffer? + +A Vim buffer is a file loaded into memory for editing. The original file +remains unchanged until you write the buffer to the file. A Vim window is a +viewport onto a buffer. You can use multiple windows on one buffer or +several windows on different buffers. + +For more information, read > + + :help usr_08.txt + :help 22.4 + :help windows-intro + :help Q_wi +< + *faq-9.2* +9.2. How do I increase the width of a Vim window? + +You can increase the width of a Vim window using one of the following +commands: > + + :vert resize +N + :vert resize -N + :vert resize N +< +You can also use CTRL-W < or CTRL-W > or CTRL-W | commands. + +For more information, read > + + :help vertical-resize + :help CTRL-W_> + :help CTRL-W_< + :help window-resize +< + *faq-9.3* +9.3. How do I zoom into or out of a window? + +You can zoom into a window (close all the windows except the current +window) using the "CTRL-W o" command or the ":only" ex command. + +You can use the "CTRL-W _" command or the ":resize" ex command to increase +the current window height to the highest possible without closing other +windows. + +You can use the "CTRL-W |" command or the ":vertical resize" ex command to +increase the current window width to the highest possible without closing +other windows. + +You can use the "CTRL-W =" command to make the height and width of all the +windows equal. + +You can also set the following options to get better results with the above +commands: + +Method 1: +Set the 'winminheight' option to 0: > + + :set winminheight=0 +< +By default, this option is set to 1. +This option controls the minimum height of an inactive window (when it is +not the current window). When the 'winminheight' option is set to 0, only +the status line will be displayed for inactive windows. + +Method 2: +Set the 'noequalalways' option and set the 'winheight' option to a large +value (like 99999): > + + :set noequalalways + :set winheight=99999 +< +Now, the active window will always open to its maximum size, while the +other windows will stay present, but shrunken to just a status line. + +With any of the above mentioned methods, you cannot restore the window +layout after zooming into a window. If you want to restore the Vim window +layout after zooming into a window, you can use the ZoomWin plugin. You can +download this plugin from the Vim online website at: + +http://vim.sourceforge.net/scripts/script.php?script_id=508 + +For more information, read > + + :help CTRL-W_o + :help window-resize + :help 'winminheight' + :help 'equalalways' + :help 'winheight' + :help 08.3 +< + *faq-9.4* +9.4. How do I execute an ex command on all the open buffers or open windows + or all the files in the argument list? + +You can use the ":bufdo" command to execute an ex command on all the open +buffers. You can use the ":windo" command to execute an ex command on all +the open windows. You can use the ":argdo" command to execute an ex +command on all the files specified in the argument list. + +For more information, read > + + :help :windo + :help :bufdo + :help :argdo + :help 26.3 +< + +============================================================================= + *faq-10* +SECTION 10 - MOTION + + *faq-10.1* +10.1. How do I jump to the beginning (first line) or end (last line) of a + file? + +You can use 'G' command to jump to the last line in the file and the 'gg' +command to jump to the first line in the file. + +For more information, read > + + :help G + :help gg +< + *faq-10.2* +10.2. In insert mode, when I press the key to go to command mode, the + cursor moves one character to the left (except when the cursor is on + the first character of the line). Is it possible to change this + behavior to keep the cursor at the same column? + +No. It is not possible to change this behavior. The cursor is *always* +positioned on a valid character (unless you have virtual-edit mode +enabled). So, if you are appending text to the end of a line, when you +return to command mode the cursor *must* drop back onto the last character +you typed. For consistency sake, the cursor drops back everywhere, even if +you are in the middle of a line. + +You can use the CTRL-O command in insert mode to execute a single ex +command and return back to insert mode without moving the cursor column. + +For more information, read > + + :help 'virtual' + :help i_CTRL-O +< + *faq-10.3* +10.3. How do I configure Vim to maintain the horizontal cursor position when + scrolling with the , , etc keys? + +You can reset the 'startofline' option to keep the cursor at the same +horizontal location when scrolling text: > + + :set nostartofline +< +For more information, read > + + :help 'startofline' +< + *faq-10.4* +10.4. Some lines in a file are more than the screen width and they are all + wrapped. When I use the j, k keys to move from one line to the next, + the cursor is moved to the next line in the file instead of the next + line on the screen. How do I move from one screen line to the next? + +You can use the gj and gk commands to move from one screen line to the +next/previous screen line. The j and k commands move the cursor from one +file line to the next file line. You can also avoid the line wrapping by +resetting the 'wrap' option: > + + :set nowrap +< +For more information, read > + + :help gj + :help gk + :help 'wrap' +< +You can use the following mappings: > + + :map gk + :imap gk + :map gj + :imap gj +< + *faq-10.5* +10.5. What is the definition of a sentence, paragraph and section in Vim? + +A sentence is defined as ending at a '.', '!' or '?' followed by either the +end of a line, or by a space (or two) or tab. Which characters and the +number of spaces needed to constitute a sentence ending is determined by +the 'joinspaces' and 'cpoptions' options. + +A paragraph begins after each empty line, and also at each of a set of +paragraph macros, specified by the pairs of characters in the 'paragraphs' +option. + +A section begins after a form-feed () in the first column and at each +of a set of section macros, specified by the pairs of characters in the +'sections' option. + +For more information, read > + + :help sentence + :help 'joinspaces' + :help 'cpoptions' | /^\s*j\> + :help paragraph + :help section + :help word +< + *faq-10.6* +10.6. How do I jump to beginning or end of a sentence, paragraph or a + section? + +You can use the following motion commands to jump to the beginning or end +of a sentence or a paragraph or a section: > + + motion position where + ( beginning current sentence + ) end current sentence + { beginning current paragraph + } end current paragraph + [] end previous section + [[ beginning current section + ][ end current section + ]] beginning next section +< +Each of these motions can be preceded by a number which will extend the +jump forward (or backward). + +For more information, read > + + :help object-motions +< + *faq-10.7* +10.7. I have lines in a file that extends beyond the right extent of the + screen. How do I move the Vim view to the right to see the text off + the screen? + +You can use one of the following commands to horizontally scroll the screen +to the left or right: > + + zl - scroll to the left + zh - scroll to the right + zL - scroll half a screenwidth to the left + zH - scroll half a screenwidth to the right + zs - scroll to position the cursor at the start of the screen + ze - scroll to position the cursor at the end of the screen +< +You can use the g0 command to move the cursor to the first character of the +screen line and the g$ command to move the cursor to the last character of +the screen line without scrolling the screen. + +For more information, read > + + :help scroll-horizontal +< + *faq-10.8* +10.8. How do I scroll two or more buffers simultaneously? + +You can set the "scrollbind" option for each of the buffer to scroll them +simultaneously. + +For more information, read > + + :help 'scrollbind' + :help scroll-binding + :help 'scrollopt' +< + *faq-10.9* +10.9. When I use my arrow keys, Vim changes modes, inserts weird characters + in my document but doesn't move the cursor properly. What's going on? + +There are a couple of things that could be going on: either you are using +Vim over a slow connection or Vim doesn't understand the key sequence that +your keyboard is generating. + +If you are working over a slow connection (such as a 2400 bps modem), you +can try to set the 'timeout' or 'ttimeout' option. These options, combined +with the 'timeoutlen' and 'ttimeoutlen' options, may fix the problem. + +The preceding procedure will not work correctly if your terminal sends key +codes that Vim does not understand. In this situation, your best option is +to map your key sequence to a matching cursor movement command and save +these mappings in a file. You can then ":source" the file whenever you work +from that terminal. + +For more information, read > + + :help 'timeout' + :help 'ttimeout' + :help 'timeoutlen' + :help 'ttimeoutlen' + :help :map + :help vt100-cursor-keys +< + *faq-10.10* +10.10. How do I configure Vim to move the cursor to the end of the previous + line, when the left arrow key is pressed and the cursor is currently + at the beginning of a line? + +You can add the '<' flag to the 'whichwrap' option to configure Vim to move +the cursor to the end of the previous line, when the left arrow key is +pressed and the cursor is currently at the beginning of a line: > + + :set whichwrap+=< +< +Similarly, to move the cursor the beginning of the next line, when the +right arrow key is pressed and the cursor is currently at the end of a +line, add the '>' flag to the 'whichwrap' option: > + + :set whichwrap+=> +< +The above will work only in normal and visual modes. To use this in insert +and replace modes, add the '[' and ']' flags respectively. + +For more information, read > + + :help 'whichwrap' + :help 05.7 +< + *faq-10.11* +10.11. How do I configure Vim to stay only in insert mode (modeless + editing)? + +You can set the 'insertmode' option to configure Vim to stay only in insert +mode: > + + :set insertmode +< +By setting this option, you can use Vim as a modeless editor. If you press +the key, Vim will not go to the normal mode. To execute a single +normal mode command, you can press CTRL-O followed by the normal mode +command. To execute more than one normal command, you can use CTRL-L +followed by the commands. To return to insert mode, press the key. To +disable this option, reset the 'insertmode' option: > + + :set noinsertmode +< +You can also start vim using the "evim" command or you can use "vim -y" to +use Vim as a modeless editor. + +For more information, read > + + :help 'insertmode' + :help i_CTRL-O + :help i_CTRL-L + :help evim + :help evim-keys +< + *faq-10.12* +10.12. How do I display some context lines when scrolling text? + +You can set the 'scrolloff' option to display a minimal number of screen +lines (context) above and below the cursor. > + + :set scrolloff=10 +< +For more information, read > + + :help 'scrolloff' + :help 'sidescrolloff' +< + *faq-10.13* +10.13. How do I go back to previous cursor locations? + +You can go back to the cursor location before the latest jump using the '' +or `` command. You can use the CTRL-O command to go back to older cursor +positions and the CTRL-I command to go to the newer cursor positions in the +jump list. + +For more information, read > + + :help 03.10 + :help mark-motions + :help jump-motions +< + +============================================================================= + *faq-11* +SECTION 11 - SEARCHING TEXT + + *faq-11.1* +11.1. After I searched for a text with a pattern, all the matched text + stays highlighted. How do I turn off the highlighting + temporarily/permanently? + +The 'hlsearch' option controls whether all the matches for the last +searched pattern are highlighted or not. By default, this option is not +enabled. If this option is set in a system-wide vimrc file, then you can +turn off the search highlighting by using the following command: > + + :set nohlsearch +< +To temporarily turn off the search highlighting, use > + + :nohlsearch +< +You can also clear the search highlighting, by searching for a pattern that +is not in the current file (for example, search for the pattern 'asdf'). + +For more information, read > + + :help 'hlsearch' + :help :nohlsearch +< + *faq-11.2* +11.2. How do I enter a carriage return character in a search pattern? + +You can either use '\r' or to enter a carriage return +character in a pattern. In Vim scripts, it is better to use '\r' for the +carriage return character. + +For more information, read > + + :help sub-replace-special +< + *faq-11.3* +11.3. How do I search for the character ^M? + +You can enter the ^M character in a search command by first pressing the +CTRL-V key and then pressing the CTRL-M key. > + + /^V^M +< +You can also use the "\r" character. In Vim scripts, "\r" is preferred. + +For more information, read > + + :help c_CTRL-V + :help using_CTRL-V + :help /\r +< + *faq-11.4* +11.4. How can I search/replace characters that display as '~R', '~S', etc.? + +You can use the 'ga' command to display the ASCII value/code for the +special character. For example, let us say the ASCII value is 142. Then you +can use the following command to search for the special character: > + + /^V142 +< +where, ^V is entered by pressing CTRL-V. + +For more information, read > + + :help ga + :help using_CTRL_V + :help 24.8 +< + *faq-11.5* +11.5. How do I highlight all the non-printable characters in a file? + +You can use the following commands and search pattern to highlight all the +non-printable characters in a file: > + + :set hlsearch + /\(\p\|$\)\@!. +< +For more information, read > + + :help /\p + :help /bar + :help /$ + :help /\( + :help /\@! + :help 'hlsearch' +< + *faq-11.6* +11.6. How do I search for whole words in a file? + +You can search for whole words in a file using the \< and \> atoms. For +example: > + + /\ +< +The \< atom matches the beginning of the word and the \> atom matches the +end of the word. + +For more information, read > + + :help /\< + :help /\> +< + *faq-11.7* +11.7. How do I search for the current word under the cursor? + +You can press the * key to search forward for the current word under the +cursor. To search backward, you can press the # key. Note that only whole +keywords will be searched using these commands. + +For more information, read > + + :help star + :help # + :help g* + :help g# + :help 03.8 + :help search-commands +< + *faq-11.8* +11.8. How do I search for a word without regard to the case (uppercase or + lowercase)? + +To always ignore case while searching for a pattern, set the 'ignorecase' +option: > + + :set ignorecase +< +To ignore case only when searching a particular pattern, use the special \c +directive: > + + /\c +< +For more information, read > + + :help 'ignorecase' + :help /ignorecase + :help /\c +< + *faq-11.9* +11.9. How do I search for words that occur twice consecutively? + +You can use one of the following search commands to locate words that occur +twice consecutively: > + + /\(\<\w\+\)\_s\+\1\> + /\(\<\k\+\)\_s\+\1\> +< +The main difference is the use of '\w' and '\k', where the latter is based +on the 'iskeyword' option which may include accented and other language +specific characters. + +For more information, read > + + :help /\1 + :help /\( + :help /\) + :help /\< + :help /\> + :help /\w + :help /\k + :help /\+ + :help /\_x + :help 'iskeyword' +< + *faq-11.10* +11.10. How do I count the number of times a particular word occurs in a + buffer? + +You can use the following set of commands to count the number of times a +particular word occurs in a buffer: > + + :let cnt=0 + :g/\/let cnt=cnt+1 + :echo cnt +< +This only counts the number of lines where the word occurs. You can also +use the following command: > + + :%s/\/&/g +< +To count the number of alphabetic words in a file, you can use > + + :%s/\a\+/&/g +< +To count the number of words made up of non-space characters, you can use > + + :%s/\S\+/&/g +< +For more information, read > + + :help count-items + :help word-count + :help v_g_CTRL-G + :help 12.5 +< + *faq-11.11* +11.11. How do I place the cursor at the end of the matched word when + searching for a pattern? + +You can use the 'e' offset to the search command to place the cursor at the +end of the matched word. For example > + + /mypattern/e +< +For more information about search offsets, read > + + :help search-offset + :help / +< + *faq-11.12* +11.12. How do I search for an empty line? + +You can search for an empty line using: > + + /^$ +< + or > + + /^\s*$ +< +For more information, read > + + :help /^ + :help /$ + :help /\s + :help /* + :help search-commands +< + *faq-11.13* +11.13. How do I search for a line containing only a single character? + +You can search for a line containing only a single character using: > + + /^\s*\a\s*$ +< +For more information, read > + + :help /^ + :help /\a + :help /\s + :help /* + :help /$ +< + *faq-11.14* +11.14. How do I search and replace a string in multiple files? + +You can use the 'argdo' or 'bufdo' or 'windo' commands to execute an ex +command on multiple files. For example: > + + :argdo %s/foo/bar/g +< +For more information, read > + + :help :argdo + :help :bufdo + :help :windo +< + *faq-11.15* +11.15. I am using the ":s" substitute command in a mapping. When a search + for a pattern fails, the map terminates. I would like the map to + continue processing the next command, even if the substitute command + fails. How do I do this? + +You can use the 'e' flag to the substitute command to continue processing +other commands in a map, when a pattern is not found. + +For more information, read > + + :help :s_flags +< + *faq-11.16* +11.16. How do I search for the n-th occurrence of a character in a line? + +To search for the n-th occurrence of a character in a line, you can prefix +the 'f' command with a number. For example, to search for the 5th +occurrence of the character @ in a line, you can use the command 5f@. This +assumes the cursor is at the beginning of the line - and that this first +character is not the one your are looking for. + +For more information, read > + + :help f + :help F + :help t + :help T + :help ; + :help , +< + *faq-11.17* +11.17. How do I replace a tab (or any other character) with a hard return + (newline) character? + +You can replace a tab (or any other character) with a hard return (newline) +character using the following command: > + + :s/\t/\r/ +< +Note that in the above command, if you use \n instead of \r, then the tab +characters will not be replaced by a new-line character. + +For more information, read > + + :help sub-replace-special + :help NL-used-for-Nul + :help CR-used-for-NL +< + *faq-11.18* +11.18. How do I search for a character by its ASCII value? + +You can search for a character by its ASCII value by pressing CTRL-V +followed by the decimal or hexadecimal or octal value of that character in +the search "/" command. To determine the ASCII value of a character you +can use the ":ascii" or the "ga" command. + +For more information, read > + + :help i_CTRL-V_digit + :help :ascii + :help ga +< + *faq-11.19* +11.19. How do I search for long lines? + +You can search for long lines or lines containing more than a specific +number of characters using the Vim regular-expressions in the search +command. For example, to search for all the lines containing more than 80 +characters, you can use one of the following commands: > + + /^.\{80}.*$ + /^.*\%80c.*$ +< +For more information, read > + + :help /\{ + :help /\%c +< + *faq-11.20* +11.20. How do I display all the lines in the current buffer that contain a + specified pattern? + +You can use the following command to display all the lines in the current +buffer that contain a specified pattern: > + + :g//p +< +For example, the following command will display all the lines in the +current buffer that contain "vim": > + + :g/vim/p +< +If you also want the corresponding line numbers, then you can use the +following command: > + + :g//# +< +For more information, read > + + :help :global + :help :print + :help :number +< + *faq-11.21* +11.21. How do I search for a text string that spans multiple lines? + +You can search for a text string that spans multiple lines using the \_x +regular expression atom. For example, to search for the text string "Hello +World", you can use the following search command: > + + /Hello\_sWorld +< +This will match the word "Hello" followed by a newline character and then +the word "World" at the beginning of the next line. This will also match +the word "Hello" immediately followed by a space character and then the +word "World". When searching for the "Hello World" string, to include the +space characters at the end and beginning of the line, you can use the +following search command: > + + /Hello\_s\+World +< +For more information, read > + + :help 27.8 + :help pattern-atoms + :help /\_ + :help pattern-searches +< + *faq-11.22* +11.22. How do I search for a pattern within the specified range of lines + in a buffer? + +You can search for a pattern within a range of lines using the \%>l +and \% + + /white\%>10l\%<20l +< +For more information, read > + + :help /\%l +< + +============================================================================= + *faq-12* +SECTION 12 - CHANGING TEXT + + *faq-12.1* +12.1. How do I delete all the trailing white space characters (SPACE and + TAB) at the end of all the lines in a file? + +You can use the ":substitute" command on the entire file to search and +remove all the trailing white space characters: > + + :%s/\s\+$// +< +For more information, read > + + :help :% + :help :s + :help /\s + :help /\+ + :help /$ +< + *faq-12.2* +12.2. How do I replace all the occurrences of multiple consecutive space + characters to a single space? + +You can use the following command to replace all the occurrences of +multiple consecutive space characters to a single space: > + + :%s/ \{2,}/ /g +< +For more information, read > + + :help :% + :help :s + :help /\{ + :help :s_flags +< + *faq-12.3* +12.3. How do I reduce a range of empty lines into one line only? + +You can use the following command to reduce a range of empty lines into one +line only: > + + :v/./.,/./-1join +< +The explanation for this command is below: > + + :v/./ Execute the following command for all lines not + containing a character (empty lines). + ., Use the current line as the start of the range of + lines. + /./ Use the line containing a character as the last line. + -1 Adjust the range of lines to end with the line before + the last line. + j Join the lines in the range. +< +Note that this will give an error message if the empty lines are at the end +of the file. To correct this, you have to add a temporary line at the end +of the file, execute the command and then remove the temporary line. + +For more information, read > + + :help :v + :help :join + :help cmdline-ranges + :help collapse +< + *faq-12.4* +12.4. How do I delete all blank lines in a file? How do I remove all the + lines containing only space characters? + +To remove all blank lines, use the following command: > + + :g/^$/d +< +To remove all lines with only whitespace (spaces or tabs) in them, use the +following command: > + + :g/^\s\+$/d +< +To remove all the lines with only whitespace, if anything, use the +following command: > + + :g/^\s*$/d +< + *faq-12.5* +12.5. How do I copy/yank the current word? + +You can use the "yiw" (yank inner word without whitespace) command or the +"yaw" (yank a word with whitespace) command to copy/yank the current +word. + +For more information, read > + + :help 04.6 + :help 04.8 + :help iw + :help yank + :help text-objects + :help objects +< + *faq-12.6* +12.6. How do I yank text from one position to another position within a + line, without yanking the entire line? + +You can specify a motion command with the yank operator (y) to yank text +from one position to another position within a line. For example, to yank +from the current cursor position till the next letter x, use yfx or Fx or +tx or Tx. To yank till the nth column, use n|. To yank till the next +occurrence of a 'word', use /word. To do a yank till the nth column on +another line, first mark the position using the 'ma' command, go to the +start of the yank position, and then yank till the mark using y`a (note the +direction of the quote) + +For more information, read > + + :help yank + :help motion.txt + :help 4.6 +< + *faq-12.7* +12.7. When I yank some text into a register, how do I append the text to + the current contents of the register? + +When you specify the register for some operation, if you use the upper-case +for the register name, then the new text will be appended to the existing +contents. For example, if you have some text in the register "a". If you +want to append some new text to this, you have to use the "A" register +name. If you use the lowercase register name, then the contents of the +register will be overwritten with the new text. + +For more information, read > + + :help quote + :help quote_alpha + :help 10.1 +< + *faq-12.8* +12.8. How do I yank a complete sentence that spans over more than one line? + +To yank a complete sentence that spans over more than one line you have to +use the yank operator followed by a motion command. For example: > + + y) +< +From inside the sentence you can use 'yi)' to yank the sentence. + +For more information, read > + + :help yank + :help {motion} + :help object-motions + :help 4.6 +< + *faq-12.9* +12.9. How do I yank all the lines containing a pattern into a buffer? + +You can use the ":global" command to yank all the lines containing the +pattern into a register and then paste the contents of the register into +the buffer: > + + :let @a='' + :g/mypattern/y A +< +The first command, clears the contents of the register "a". The second +command copies all the lines containing "mypattern" into the register "a". +Note that the capital letter "A" is used to append the matched lines. Now +you can paste the contents of register "a" to a buffer using "ap command. +For more information, read > + + :help :g + :help :y + :help let-register + :help quote_alpha + :help put + :help registers + :help :registers +< + *faq-12.10* +12.10. How do I delete all the lines in a file that does not contain a + pattern? + +You can use ":v" command to delete all the lines that does not contain a +pattern: > + + :v/pattern/d +< +or > + + :g!/pattern/d +< +For more information, read > + + :help :v + :help :g +< + *faq-12.11* +12.11. How do I add a line before each line with "pattern" in it? + +You can use the following command to add a line before each line with +"pattern" in it: > + + :g/pattern/normal Oi +< +Alternatively you can yank the line using the Y command and then insert the +line using the following command: > + + :g/pattern/put! +< +For more information, read > + + :help :g + :help :put + :help insert + :help 0 +< + *faq-12.12* +12.12. Is there a way to operate on a line if the previous line contains a + particular pattern? + +You can use the ":global" command to operate on a line, if the previous +line contains a particular pattern: > + + :g//+{cmd} +< +For more information, read > + + :help :g + :help :range +< + *faq-12.13* +12.13. How do I execute a command on all the lines containing a pattern? + +You can use the ":global" (:g) command to execute a command on all the +lines containing a pattern. > + + :g/my pattern/d +< +If you want to use a non-Ex command, then you can use the ":normal" +command: > + + :g/my pattern/normal {command} +< +Unless you want the normal mode commands to be remapped, consider using a +":normal!" command instead (note the "!"). + +For more information, read > + + :help :global + :help :v + :help :normal +< + *faq-12.14* +12.14. Can I copy the character above the cursor to the current cursor + position? + +In Insert mode, you can copy the character above the cursor to the current +cursor position by typing . The same can be done with the +characters below the cursor by typing . + +For more information, read > + + :help i_CTRL-Y + :help i_CTRL-E +< + *faq-12.15* +12.15. How do I insert a blank line above/below the current line without + entering insert mode? + +You can use the ":put" ex command to insert blank lines. For example, try > + + :put ='' + :put! ='' +< +For more information, read > + + :help :put +< + *faq-12.16* +12.16. How do I insert the name of current file into the current buffer? + +There are several ways to insert the name of the current file into the +current buffer. In insert mode, you can use the % or the +=expand("%") command. In normal mode, you can use the ":put =@%" +command. + +For more information, read > + + :help i_CTRL-R + :help expand() + :help !! +< + *faq-12.17* +12.17. How do I insert the contents of a Vim register into the current + buffer? + +In insert mode, you can use the command to insert the +contents of . For example, use a to insert the contents +of register "a" into the current buffer. + +In normal mode, you can use the ":put " command to insert the +contents of . For example, use the ":put d" command to insert +the contents of register "d" into the current buffer. + +For more information, read > + + :help i_CTRL-R + :help :put +< + *faq-12.18* +12.18. How do I move the cursor past the end of line and insert some + characters at some columns after the end of the line? + +You can set the "virtualedit" option to move the cursor past the +end-of-line and insert characters in a column after the end-of-line. To +start the virtual mode, use > + + :set virtualedit=all +< +For more information, read > + + :help 'virtualedit' +< + *faq-12.19* +12.19. How to replace the word under the cursor (say: junk) with + "foojunkbar" in Vim? + +There are several ways to do this. If the word is the first such word on +the line, use the following command: > + + :exe "s/".expand("")."/foo&bar/" +< +Too match specifically you could use a more complex substitution like this: > + + :exe 's/\<'.expand("").'\%>'.(col(".")-1).'c\>/foo&bar/' +< +You can also use the command: ciwfoo"bar + +For more information, read > + + :help :substitute + :help expand() + :help col() + :help /\%c +< + *faq-12.20* +12.20. How do I replace a particular text in all the files in a directory? + +You can use the "argdo" command to execute the substitute command on all +the files specified as arguments: > + + :args * + :argdo %s///ge | update +< +For more information, read > + + :help :args_f + :help :argdo + :help :s_flags +< + *faq-12.21* +12.21. I have some numbers in a file. How do I increment or decrement the + numbers in the file? + +You can use the CTRL-A key to increment the number and the CTRL-X key to +decrement the number. You can also specify the number to +increment/decrement from the number by specifying a count to the key. This +works for decimal, octal and hexadecimal numbers. + +For more information, read > + + :help CTRL-A + :help CTRL-X + :help 'nrformats' +< + *faq-12.22* +12.22. How do I reuse the last used search pattern in a ":substitute" + command? + +To reuse the last used search pattern in a ":substitute" command, don't +specify a new search pattern: > + + :s/pattern/newtext/ + :s//sometext/ +< +In the second ":s" command, as a search pattern is not specified, the +pattern specified in the first ":s" command 'pattern' will be used. + +If you want to change the search pattern but repeat the substitution +pattern you can use the special right hand side, you can use the tilde +character: > + + :s/newpattern/~/ +< +For more information, read > + + :help :s + :help :& + :help :~ + :help & + :help sub-replace-special +< + *faq-12.23* +12.23. How do I change the case of a string using the ":substitute" + command? + +You can use special characters in the replacement string for a +":substitute" command to change the case of the matched string. For +example, to change the case of the string "MyString" to all uppercase, you +can use the following command: > + + :%s/MyString/\U&/g +< +To change the case to lowercase, you can use the following command: > + + :%s/MyString/\L&/g +< +To change the case of the first character in all the words in the current +line to uppercase, you can use the following command: > + + :s/\<\(.\)\(\k*\)\>/\u\1\L\2/g +< +For more information, read > + + :help sub-replace-special + :help :substitute + :help \U + :help \L + :help \u +< + *faq-12.24* +12.24. How do I enter characters that are not present in the keyboard? + +You can use digraphs to enter characters that are not present in the +keyboard. You can use the ":digraphs" command to display all the currently +defined digraphs. You can add a new digraph to the list using the +":digraphs" command. + +For more information, read > + + :help digraphs + :help 'digraphs' + :help 24.9 +< + *faq-12.25* +12.25. Is there a command to remove any or all digraphs? + +No. The digraphs table is defined at compile time. You can only add new +ones. Adding a command to remove digraphs is on the todo list. + + *faq-12.26* +12.26. In insert mode, when I press the backspace key, it erases only the + characters entered in this instance of insert mode. How do I erase + previously entered characters in insert mode using the backspace + key? + +You can set the 'backspace' option to erase previously entered characters +in insert mode: > + + :set backspace=indent,eol,start +< +For more information, read > + + :help 'backspace' +< + *faq-12.27* +12.27. I have a file which has lines longer than 72 characters terminated + with "+" and wrapped to the next line. How can I quickly join the + lines? + +You can use the ":global" command to search and join the lines: > + + :g/+$/j +< +This will, however, only join every second line. A couple of more complex +examples which will join all consecutive lines with a "+" at the end are: > + + :g/*$/,/\(^\|[^+]\)$/j + :g/+$/mark a | .,/\(^\|[^+]\)$/s/+$// | 'a,.j +< +For more information, read > + + :help :g + :help :j + :help :mark +< + *faq-12.28* +12.28. How do I paste characterwise yanked text into separate lines? + +You can use the ":put" command to paste characterwise yanked text into new +lines: > + + :put =@" +< +For more information, read > + + :help :put + :help quote_= +< + *faq-12.29* +12.29. How do I change the case (uppercase, lowercase) of a word or a + character or a block of text? + +You can use the "~" command to switch the case of a character. + +You can change the case of the word under the cursor to uppercase using the +"gUiw" or "viwU" command and to lowercase using the "guiw" or "viwu" +command. + +You can switch the case (upper case to lower case and vice versa) of the +word under the cursor using the "viw~" or "g~iw" command. + +You can use the "gUgU" command to change the current line to uppercase and +the "gugu" command to change the current line to lowercase. + +You can use the "g~g~" command to switch the case of the current line. You +can use the "g~{motion}" or "{Visual}~" commands to switch the case of a +block of text. + +For more information, read > + + :help case +< + *faq-12.30* +12.30. How do I enter ASCII characters that are not present in the + keyboard? + +You can enter ASCII characters that are not present in the keyboard by +pressing CTRL-V and then the ASCII character number. You can also use +digraphs to enter special ASCII characters. + +For more information, read > + + :help i_CTRL-V_digit + :help digraphs + :help 45.5 +< + *faq-12.31* +12.31. How do I replace non-printable characters in a file? + +To replace a non-printable character, you have to first determine the ASCII +value for the character. You can use the ":ascii" ex command or the "ga" +normal-mode command to display the ASCII value of the character under the +cursor. + +You can enter the non-printable character by entering CTRL-V followed by +the decimal number 1-255 (with no leading zero), or by x and a hex number +00-FF, or by an octal number 0-0377 (with leading zero), or by u and a hex +number 0-FFFF, or by U and a hex number 0-7FFFFFFF + +Another alternative is to use the ":digraphs" ex command to display the +digraphs for all characters, together with their value in decimal and +alpha. You can enter a non-printable character by entering CTRL-K followed +by two alphanumeric characters (a digraph). + +For more information, read > + + :help :ascii + :help i_CTRL-V + :help i_CTRL-V_digit + :help :digraphs +< + *faq-12.32* +12.32. How do I remove duplicate lines from a buffer? + +You can use the following user-defined command to remove all the duplicate +lines from a buffer: + +:command -range=% Uniq ,g/^\%<l\(.*\)\n\1$/d + +Add the above command to your .vimrc file and invoke ":Uniq" to remove all +the duplicate lines. + + *faq-12.33* +12.33. How do I prefix all the lines in a file with the corresponding line + numbers? + +You can prefix the lines with the corresponding line number in several +ways. Some of them are listed below: > + + :%s/^/\=line('.'). ' ' + :%s/^/\=strpart(line(".")." ", 0, 5) + :g/^/exec "s/^/".strpart(line(".")." ", 0, 4) +< +For more information, read > + + :help sub-replace-special + :help line() + :help expr6 + :help strpart() + :help :execute + :help :global +< + *faq-12.34* +12.34. How do I exchange (swap) two characters or words or lines? + +You can exchange two characters with the "xp" command sequence. The 'x' +will delete the character under the cursor and 'p' will paste the just +deleted character after the character under the cursor. This will result +in exchanging the two characters. + +You can exchange two words with the "deep" command sequence (start with the +cursor in the blank space before the first word). + +You can exchange two lines with the "ddp" command sequence. The 'dd' will +delete the current line and 'p' will paste the just deleted line after the +current line. This will result in exchanging the two lines. + +All of the above operations will change the " unnamed register. + +You can use the ":m +" ex command to exchange two lines without changing the +unnamed register. + +For more information, read > + + :help x + :help p + :help dd + :help d + :help e + :help linewise-register + :help quotequote + :help :move +< + +============================================================================= + *faq-13* +SECTION 13 - COMPLETION IN INSERT MODE + + *faq-13.1* +13.1. How do I complete words or lines in insert mode? + +In insert mode, you can complete words using the CTRL-P and CTRL-N keys. +The CTRL-N command searches forward for the next matching keyword. +The CTRL-P command searches backwards for the next matching keyword. + +In insert mode, you can use the CTRL-X CTRL-L command sequence to complete +lines that starts with the same characters as in the current line before +the cursor. To get the next matching line, press the CTRL-P or CTRL-N keys. +There are a lot of other keys/ways available to complete words in insert +mode. + +Vim supports completion of the following items: > + + 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 +< +For more information, read > + + :help 24.3 + :help ins-completion +< + *faq-13.2* +13.2. How do I complete file names in insert mode? + +In insert mode, you can use the CTRL-X CTRL-F command sequence to complete +filenames that start with the same characters as in the current line before +the cursor. + +For more information, read > + + :help compl-filename +< + *faq-13.3* +13.3. I am using CTRL-P/CTRL-N to complete words in insert mode. How do I + complete words that occur after the just completed word? + +You can use CTRL-X CTRL-N and CTRL-X CTRL-P keys to complete words that are +present after the just completed word. + +For more information, read > + + :help i_CTRL-X_CTRL-P + :help i_CTRL-X_CTRL-N + :help ins-completion +< + +============================================================================= + *faq-14* +SECTION 14 - TEXT FORMATTING + + *faq-14.1* +14.1. How do I format a text paragraph so that a new line is inserted at + the end of each wrapped line? + +You can use the 'gq' command to format a paragraph. This will format the +text according to the current 'textwidth' setting. + +Note that the gq operator can be used with a motion command to operate on a +range of text. For example: > + + gqgq - Format the current line + gqap - Format current paragraph + gq3j - Format the current and the next 3 lines +< +For more information, read > + + :help gq + :help formatting + :help usr_25.txt + :help motion.txt +< + *faq-14.2* +14.2. How do I format long lines in a file so that each line contains less + than 'n' characters? + +First set the 'textwidth' option to the desired value: > + + set textwidth=70 +< +Now to break the long lines to the length defined by the 'textwidth' +option, use > + + :g/./normal gqq +< +For more information, read > + + :help gq +< + *faq-14.3* +14.3. How do I join short lines to form a paragraph? + +First, make sure the 'textwidth' option is set to a high value: > + + :set textwidth=99999 +< +Next, join the short lines to form a paragraph using the command: > + + 1GgqG +< +The above command will operate on the entire file. To do the formatting on +all paragraphs in a specific range, use: > + + :'a,'bg/\S/normal gq} +< +For more information, read > + + :help gq + :help G + :help gqq +< + *faq-14.4* +14.4. How do I format bulleted and numbered lists? + +You can configure Vim to format bulleted and numbered lists using the +'formatoptions' option. For example, you can format the list of the +following format: + + - this is a test. this is a test. this is a test. this is a test. + this is a test. + +into this format: + + - this is a test. this is a test. this is a test. this is a test. + this is a test. + +You can use the 'n' flag in the 'formatoptions' to align the text. > + + :set fo+=n +< +With this option, when formatting text, Vim will recognize numbered lists. +For this option to work, the 'autoindent' option also must be set. + +For more information, read > + + :help 'formatoptions' + :help fo-table +< + *faq-14.5* +14.5. How do I indent lines in insert mode? + +In insert mode, you can press the CTRL-T key to insert one shiftwidth of +indent at the start of the current line. In insert mode, you can use the +CTRL-D key to delete on shiftwidth of indent at the start of the current +line. You can also use the CTRL-O >> and CTRL-O << commands to indent the +current line in insert mode. + +For more information, read > + + :help i_CTRL-T + :help i_CTRL-D + :help i_0_CTRL-D + :help i_CTRL-O + :help >> + :help << +< + *faq-14.6* +14.6. How do I format/indent an entire file? + +You can format/indent an entire file using the gg=G command, where > + + gg - Goto the beginning of the file + = - apply indentation + G - till end of file +< +For more information, read > + + :help gg + :help = + :help G + :help 'formatprg' + :help C-indenting +< + *faq-14.7* +14.7. How do I increase or decrease the indentation of the current line? + +You can use the '>>' and '<<' commands to increase or decrease the +indentation of the current line. + +For more information, read > + + :help shift-left-right + :help >> + :help << + :help 'shiftwidth' +< + *faq-14.8* +14.8. How do I indent a block/group of lines? + +You can visually select the group of lines and press the > or < key to +indent/unindent the lines. You can also use the following ex-command to +indent the lines > + + :10,20> +< +For more information, read > + + :help shift-left-right + :help v_> + :help v_< + :help :< + :help :> +< + *faq-14.9* +14.9. When I indent lines using the > or < key, the standard 8-tabstops are + used instead of the current 'tabstop' setting. Why? + +The number of spaces used when lines are indented using the ">" operator is +controlled by the 'shiftwidth' option. The 'tabstop' setting is not used +for indentation. To change the amount of spaces used for indentation, use +the command: > + + :set shiftwidth=4 +< +For more information, read > + + :help 'shiftwidth' + :help >> + :help 'softtabstop' +< + *faq-14.10* +14.10. How do I turn off the automatic indentation of text? + +By default, the automatic indentation of text is not turned on. Check the +configuration files (.vimrc, .gvimrc) for settings related to indentation. +Make sure the ":filetype indent on" command is not present. If it is +present, remove it. Also, depending on your preference, you may also want +to check the value of the 'autoindent', 'smartindent', 'cindent' and +'indentexpr' options and turn them off as needed. + +For more information, read > + + :help :filetype-indent-off + :help 'autoindent' + :help 'smartindent' + :help 'cindent' + :help 'indentexpr' +< + *faq-14.11* +14.11. How do I configure Vim to automatically set the 'textwidth' option + to a particular value when I edit mails? + +You can use the 'FileType' autocommand to set the 'textwidth' option: > + + autocmd FileType mail set tw= +< +For more information, read > + + :help :autocmd + :help FileType + :help usr_43.txt +< + *faq-14.12* +14.12. Is there a way to make Vim auto-magically break lines? + +Yes. Set the 'textwidth' option to the preferred length for a line. Then +Vim will auto-magically break the newly entered lines. For example: > + + :set textwidth=75 +< +For more information, read > + + :help textwidth + :help ins-textwidth + :help 'formatoptions' + :help fo-table + :help formatting +< + *faq-14.13* +14.13. I am seeing a lot of ^M symbols in my file. I tried setting the + 'fileformat' option to 'dos' and then 'unix' and then 'mac'. None of + these helped. How can I hide these symbols? + +When a file is loaded in Vim, the format of the file is determined as +below: + +- If all the lines end with a new line (), then the fileformat is + 'unix'. +- If all the lines end with a carriage retuurn () followed by a new line + (), then the fileformat is 'dos'. +- If all the lines end with carriage returnn (), then the fileformat is + 'mac'. + +If the file has some lines ending with and some lines ending with +followed by a , then the fileformat is set to 'unix'. + +You can change the format of the current file, by modifying the +'fileformat' option and then saving the file: > + + :set fileformat=dos + :w +< +To display the format of the current file, use > + + :set fileformat? +< +The above behavior is also controlled by the 'fileformats' option. You can +try the following commands: > + + :set fileformats+=unix + :e + :set fileformat=unix + :w +< +For more information, read > + + :help 'fileformats' + :help 'fileformat' + :help file-formats + :help DOS-format-write + :help Unix-format-write + :help Mac-format-write + :help dos-file-formats + :help 23.1 +< + *faq-14.14* +14.14. When I paste some text into a Vim buffer from another application, + the alignment (indentation) of the new text is messed up. How do I + fix this? + +The indentation of the text is messed up due to various Vim settings +related to indentation (like autoindent, smartindent, textwidth etc). +Before pasting text into Vim, you can set the 'paste' option: > + + :set paste +< +After pasting the text, you can turn off the option using: > + + :set nopaste +< +You can also toggle the paste option using: > + + :set paste! +< +If you can access the clipboard through the * register, then you can paste +the text without indentation using CTRL-R CTRL-O *. + +For more information, read > + + :help 'paste' + :help 'pastetoggle' + :help i_CTRL-R_CTRL_O + :help clipboard + :help xterm-clipboard + :help gui-clipboard +< + *faq-14.15* +14.15. When there is a very long wrapped line (wrap is "on") and a line + doesn't fit entirely on the screen it is not displayed at all. There + are blank lines beginning with '@' symbol instead of wrapped line. If + I scroll the screen to fit the line the '@' symbols disappear and the + line is displayed again. What Vim setting control this behavior? + +You can set the 'display' option to 'lastline' to display as much as +possible of the last line in a window instead of displaying the '@' +symbols. > + + :set display=lastline +< +For more information, read > + + :help 'display' +< + *faq-14.16* +14.16. How do I convert all the tab characters in a file to space + characters? + +You can use the ":retab" command to update all the tab characters in the +current file with the current setting of 'expandtab' and 'tabstop'. For +example, to convert all the tabs to white spaces, use > + + :set expandtab + :retab +< +For more information, read > + + :help :retab + :help 'expandtab' + :help 'tabstop' + :help 25.3 +< + *faq-14.17* +14.17. What Vim options can I use to edit text that will later go to a word + processor? + +You can set the following options to edit text that will later go into a +word processor: > + + :set wrap + :set linebreak + :set textwidth=0 + :set showbreak=>>> +< +You can use the 'gk' and 'gj' commands to move one screen line up and down. +For more information, read > + + :help 'wrap' + :help 'linebreak' + :help 'textwidth' + :help 'showbreak' + :help gk + :help gj +< + +============================================================================= + *faq-15* +SECTION 15 - VISUAL MODE + + *faq-15.1* +15.1. How do I do rectangular block copying? + +You can do rectangular block copying in Vim using the blockwise visual +mode. To start blockwise visual mode use the CTRL-V key. Move the cursor +using any of the motion commands and then use the y operator to yank to +visually selected text. + +If CTRL-V does not work as expected, it may have been remapped to CTRL-Q by +the mswin.vim script which is often sourced by a vimrc on Windows machines +to mimic some common short cuts from other programs. + +For more information, read > + + :help 04.4 + :help blockwise-visual + :help visual-mode + :help Q_vi +< + *faq-15.2* +15.2. How do I delete or change a column of text in a file? + +You can use the Vim block-wise visual mode to select the column of text and +apply an operator (delete, change, copy, etc) on it. + +For more information, read > + + :help visual-block + :help visual-operators +< + *faq-15.3* +15.3. How do I apply an ex-command on a set of visually selected lines? + +When you select a range of lines in visual mode, the < register is set to +the start of the visual region and the > register is set to the end of the +visual region. You can use these registers to specify the range for an ex +command. After visually selecting the lines, press ":" to go to the command +mode. Vim will automatically insert the visual range '<,'>. You can run +any ex-command on the visual range. + +For more information, read > + + :help v_: + :help '< + :help '> +< + *faq-15.4* +15.4. How do I execute an ex command on a column of text selected in Visual + block mode? + +All the ex commands operate on whole lines only. If you try to execute an +ex command on a column of text selected in visual block mode, Vim will +operate on all the selected lines (instead of the selected columns). You +can use the vis.vim plugin script from http://vim.sourceforge.net scripts +archive to do this. + +For more information, read > + + :help cmdline-ranges + :help 10.3 + :help cmdline-lines +< + *faq-15.5* +15.5. How do I select the entire file in visual mode? + +You can select the entire file in visual mode using ggVG. > + + gg - go to the beginning of the file. + V - Start linewise visual mode + G - goto the end of the file. +< +For more information, read > + + :help gg + :help linewise-visual + :help G +< + *faq-15.6* +15.6. When I visually select a set of lines and press the > key to indent + the selected lines, the visual mode ends. How can I reselect the + region for further operation? (or) How do I re-select the last + selected visual area again? + +You can use the 'gv' command to reselect the last selected visual area. You +can also use the marks '< and '> to jump to the beginning or the end of the +last selected visual area. + +For more information, read > + + :help gv + :help '< + :help '> +< + *faq-15.7* +15.7. How do I jump to the beginning/end of a visually selected region? + +You can use the 'o' command to jump to the beginning/end of a visually +selected region. + +For more information, read > + + :help v_o +< + *faq-15.8* +15.8. When I select text with mouse and then press : to enter an ex + command, the selected text is replaced with the : character. How do I + execute an ex command on a text selected using the mouse similar to + the text selected using the visual mode? + +This will happen if you have configured Vim to use select mode instead of +Visual mode by setting the 'selectmode' option. Check the value of this +option: > + + :set selectmode? +< +This mode is known as selectmode and is similar to the visual mode. This +option is also automatically set when you use the "behave mswin" command. +Select mode looks like visual mode, but it is similar to the selection mode +in MS-Windows. + +For more information, read > + + :help Select-mode + :help 'selectmode' + :help 9.4 + :help :behave +< + *faq-15.9* +15.9. When I select a block of text using the mouse, Vim goes into + selection mode instead of Visual mode. Why? + +The 'selectmode' option controls whether Select mode will be started when +selecting a block of text using the mouse. To start Visual mode when +selecting text using mouse, remove the 'mouse' value from the 'selectmode' +option: > + + :set selectmode-=mouse +< +Note that by default, the 'selectmode' option will be set to empty, so that +always visual mode is used. + +For more information, read > + + :help 'selectmode' + :help Select-mode + :help :behave +< + *faq-15.10* +15.10. How do I visually select the last copy/pasted text? + +You can use the '[ and '] marks to visually select the last copy/pasted +text. The '[ mark is set to the beginning of the last changed/yanked text +and the '] mark is set to the end of the last changed/yanked text. To +visually select this block of text use the command '[v'] + +For more information, read > + + :help '[ + :help '] + :help `a + :help v +< + +============================================================================= + *faq-16* +SECTION 16 - COMMAND-LINE MODE + + *faq-16.1* +16.1. How do I use the name of the current file in the command mode or an + ex command line? + +In the command line, the '%' character represents the name of the current +file. In some commands, you have to use expand("%") to get the filename: > + + :!perl % +< +For more information, read > + + :help :_% + :help cmdline-special + :help expand() +< + *faq-16.2* +16.2. How do I edit the text in the Vim command-line effectively? + +You can use the command-line window for editing Vim command-line text. To +open the Vim command-line window use the "q:" command in normal mode. In +command-line mode, use the CTRL-F key. In this window, the command line +history will be displayed. You can use normal Vim keys/commands to edit any +previous/new command line. To execute a command line, press the +enter/return key. + +In a similar vain, the search history can be edited with "q/" and "q?" +commands. + +For more information, read > + + :help cmdline-window +< + *faq-16.3* +16.3. How do I switch from Vi mode to Ex mode? + +You can use the Q command to switch from Vi mode to Ex mode. To switch from +Ex mode back to the Vi mode, use the :vi command. + +For more information, read > + + :help Q + :help gQ + :help Ex-mode + :help :vi +< + *faq-16.4* +16.4. How do I copy the output from an ex-command into a buffer? + +To copy the output from an ex-command into a buffer, you have to first get +the command output into a register. You can use the ":redir" command to get +the output into a register. For example, > + + :redir @a + :g/HelloWord/p + :redir END +< +Now the register 'a' will contain the output from the ex command +"g/HelloWord/p". Now you can paste the contents of the register 'a' into a +buffer. You can also send or append the output of an ex-command into a file +using the 'redir' command. + +You can prefix the ":global" command with ":silent", to avoid having the +lines printed to the screen. + +To redirect the output from an ex-command to a file, you can use the +following set of commands: > + + :redir > myfile + :g/HelloWord/p + :redir END +< +For more information, read > + + :help :redir + :help :silent +< + *faq-16.5* +16.5. When I press the tab key to complete the name of a file in the + command mode, if there are more than one matching file names, then + Vim completes the first matching file name and displays a list of all + matching filenames. How do I configure Vim to only display the list + of all the matching filenames and not complete the first one? + +You can modify the 'wildmode' option to configure the way Vim completes +filenames in the command mode. In this case, you can set the 'wildmode' +option to 'list': > + + :set wildmode=list +< +For more information, read > + + :help 'wildmode' +< + *faq-16.6* +16.6. How do I copy text from a buffer to the command line and from the + command line to a buffer? + +To copy text from a buffer to the command line, after yanking the text from +the buffer, use Ctrl-R 0 in the command line to paste the text. You can +also yank the text to a specific register and use CTRL-R to +paste the text to the command line. You can use CTRL-R CTRL-W to paste the +word under the cursor in the command line. + +To copy text from the command line into a buffer, you can paste the +contents of the : register using the ":p command. The most recently +executed command line is stored in the : register. + +Another approach for copying and pasting text to and from the command line +is to open the command line window using q: from normal mode or CTRL-F from +the command-line mode. In the command line window you can use all the Vim +commands to edit the command line. + +For more information, read > + + :help c_CTRL-R + :help quote_: + :help cmdline-window +< + *faq-16.7* +16.7. How do I put a command onto the command history without executing it? + +To put a command onto the command history without executing it, press the + key to cancel the command. + +For more information, read > + + :help c_ +< + *faq-16.8* +16.8. How do I increase the height of the command-line? + +You can increase the height of the command-line by changing the 'cmdheight' +option: > + + :set cmdheight=2 +< +For more information, read > + + :help 'cmdheight' + :help hit-enter + :help 05.7 +< + +============================================================================= + *faq-17* +SECTION 17 - VIMINFO + + *faq-17.1* +17.1. When I invoke Vim, I get error messages about illegal characters in + the viminfo file. What should I do to get rid of these messages? + +You can remove the $HOME/.viminfo or the $HOME/_viminfo file to get rid of +these error messages. + +For more information, read > + + :help viminfo-errors + :help viminfo-file-name + :help viminfo + :help 21.3 +< + *faq-17.2* +17.2. How do I disable the viminfo feature? + +By default, the viminfo feature is disabled. If the viminfo feature is +enabled by a system-wide vimrc file, then you can disable the viminfo +feature by setting the 'viminfo' option to an empty string in your local +.vimrc file: > + + :set viminfo="" +< +For more information, read > + + :help 'viminfo' +< + *faq-17.3* +17.3. How do I save and use Vim marks across Vim sessions? + +You can save and restore Vim marks across Vim sessions using the viminfo +file. To use the viminfo file, make sure the 'viminfo' option is not empty. +To save and restore Vim marks, the 'viminfo' option should not contain the +'f' flag or should have a value greater than zero for the 'f' option. + +For more information, read > + + :help 21.3 + :help viminfo + :help 'viminfo' + :help :wviminfo + :help :rviminfo +< + +============================================================================= + *faq-18* +SECTION 18 - REMOTE EDITING + + *faq-18.1* +18.1. How do I open a file with existing instance of gvim? What happened to + the Vim 5.x OpenWithVim.exe and SendToVim.exe files? + +Starting with Vim6, the OLE version of OpenWithVim.exe and SendToVim.exe +Vim utilities are replaced by the new client-server feature. To open the +file j.txt with an existing instance of Gvim (MyVim), use: > + + $ gvim --servername MyVim --remote-silent j.txt +< +To list the server names of all the currently running Vim instances, use > + + $ vim --serverlist +< +To get more information about client-server feature, read > + + :help client-server +< + *faq-18.2* +18.2. How do I send a command to a Vim server to write all buffers to disk? + +You can use the Vim remote server functionality to do this: > + + $ gvim --servername myVIM --remote-send ":wall" +< +For more information, read > + + :help client-server + :help CTRL-\_CTRL-N + :help :wall +< + *faq-18.3* +18.3. Where can I get the documentation about the Vim remote server + functionality? + +You can get more information about the Vim remote server functionality by +reading > + + :help client-server +< + +============================================================================= + *faq-19* +SECTION 19 - OPTIONS + + *faq-19.1* +19.1. How do I configure Vim in a simple way? + +You can use the ":options" command to open the Vim option window: > + + :options +< +This window can be used for viewing and setting all the options. + +For more information, read > + + :help :options +< + *faq-19.2* +19.2. How do I toggle the value of an option? + +You can prefix the option with "inv" to toggle the value of the option: > + + :set invignorecase + :set invhlsearch +< +You can also suffix the option with "!" to toggle the value: > + + :set ignorecase! + :set hlsearch! +< +For more information, read > + + :help set-option +< + *faq-19.3* +19.3. How do I set an option that affects only the current buffer/window? + +You can use the ":setlocal" command to set an option that will affect only +the current file/buffer: > + + :setlocal textwidth=70 +< +Note that not all options can have a local value. You can use ":setlocal" +command to set an option locally to a buffer/window only if the option is +allowed to have a local value. + +You can also use the following command to set a option locally: > + + :let &l:{option-name} = +< +For more information, read > + + :help :setlocal + :help local-options +< + *faq-19.4* +19.4. How do I use space characters for a Vim option value? + +To use space characters in a Vim option value, you have to escape the space +character. For example: > + + :set tags=tags\ /usr/tags +< +For more information, read > + + :help option-backslash +< + *faq-19.5* +19.5. Can I add (embed) Vim option settings to the contents of a file? + +You can use modelines to add Vim option settings to the contents of a file. +For example, in a C file, you can add the following line to the top or the +bottom of the file: > + + /* vim:sw=4: */ +< +This will set the 'shiftwidth' option to 4, when editing that C file. +For this to work, the 'modeline' option should be set. By default, the +'modeline' option is set. The 'modelines' settings specifies the number of +lines that will be checked for the Vim set commands. + +For more information, read > + + :help 21.6 + :help modeline + :help auto-setting + :help 'modeline' + :help 'modelines' +< + *faq-19.6* +19.6. How do I display the line numbers of all the lines in a file? + +You can set the 'number' option to display the line numbers for all the +lines. > + + :set number +< +For more information, read > + + :help 'number' +< + *faq-19.7* +19.7. How do I change the width of the line numbers displayed using the + "number" option? + +The width used for displaying the line numbers for the 'number' option is +hard-coded in Vim. It is not possible to change this width by setting some +option. + +The request and the patch to add an option to change the number of columns +used for the 'number' option is in the Vim todo list: > + + "Add an option to set the width of the 'number' column. Eight + positions is often more than needed. Or adjust the width to the length + of the file? + Add patch that adds 'numberlen' option. (James Harvey) + Other patch with min and max from Emmanuel Renieris (2002 Jul 24) + Other patch without an option by Gilles Roy (2002 Jul 25)" +< + *faq-19.8* +19.8. How do I display (view) all the invisible characters like space, tabs + and newlines in a file? + +You can set the 'list' option to see all the invisible characters in your +file. > + + :set list +< +With this option set, you can view space characters, tabs, newlines, +trailing space characters and wrapped lines. + +To not display the invisible characters (which is the default), you have to +reset the 'list' option: > + + :set nolist + (or) + :set list! +< +The ":set list!" command will toggle the current setting of the boolean +'list' option. + +You can modify the 'listchars' option to configure how and which invisible +characters are displayed. For example, with the following command all the +trailing space characters will be displayed with a '.' character. > + + :set listchars=trail:. +< +For more information, read > + + :help 'listchars' + :help 'list' +< + *faq-19.9* +19.9. How do I configure Vim to always display the current line and column + number? + +You can set the 'ruler' option to display current column and line number in +the status line: > + + :set ruler +< +For more information, read > + + :help 'ruler' +< + *faq-19.10* +19.10. How do I display the current Vim mode? + +You can set the 'showmode' option to display the current Vim mode. In +Insert, Replace and Visual modes, Vim will display the current mode on the +last line. > + + :set showmode +< +For more information, read > + + :help 'showmode' +< + *faq-19.11* +19.11. How do I configure Vim to show pending/partial commands on the + status line? + +You can set the 'showcmd' option to display pending/partial commands in the +status line: > + + :set showcmd +< +For more information, read > + + :help 'showcmd' +< + *faq-19.12* +19.12. How do I configure the Vim status line to display different + settings/values? + +You can set the 'statusline' option to display different values/settings in +the Vim status line. + +For more information, read > + + :help 'statusline' + :help 'laststatus' + :help 'rulerformat' + :help 'ruler' +< + *faq-19.13* +19.13. How do I configure Vim to display status line always? + +You can set the 'laststatus' option to 2 to display the status line always. > + + :set laststatus=2 +< +For more information, read > + + :help 'laststatus' +< + *faq-19.14* +19.14. How do I make a Vim setting persistent across different Vim + invocations/instances/sessions? + +To make a Vim option setting persistent across different Vim instances, add +your setting to the .vimrc or .gvimrc file. You can also use the ":mkvimrc" +command to generate a vimrc file for the current settings. + +For more information, read > + + :help save-settings + :help vimrc + :help gvimrc + :help vimrc-intro + :help :mkvimrc + :help initialization +< + *faq-19.15* +19.15. Why do I hear a beep (why does my window flash) about 1 second after + I hit the Escape key? + +This is normal behavior. If your window flashes, then you've got the visual +bell on. Otherwise, you should hear a beep. + +Vim needs a timeout to tell the difference between a simple escape and, +say, a cursor key sequence. When you press a key in normal mode (and even +in insert mode) and that key is the beginning of a mapping, Vim waits a +certain amount of time to see if the rest of the mapping sequence follows. +If the mapping sequence is completed before a given timeout period, the +mapping for that sequence of keys is applied. If you interrupt the mapping, +the normal actions associated with the keys are executed. + +For example, if you have a mapping defined as ":imap vvv Vim is great!!" +and you type "vvv" quickly, the "Vim is great!!" will be inserted into your +text. But if you type "vv v" then that is what will put into your text. +This is also true if you type "vvv" too slowly where "too slowly" is longer +than the value for the timeout option. Setting the timeout option to a +larger value can help alleviate problems that appear when using function +keys over a slow line. + +For more information, read > + + :help ttimeout +< + *faq-19.16* +19.16. How do I make the 'c' and 's' commands display a '$' instead of + deleting the characters I'm changing? + +To make the 'c' and 's' commands display a '$' instead of deleting the +characters, add the $ flag to the 'cpoptions' option: > + + :set cpoptions+=$ +< +For more information, read > + + :help 'cpoptions' +< + *faq-19.17* +19.17. How do I remove more than one flag using a single ":set" command + from a Vim option? + +You can remove more than one flag from a Vim option using a single ":set" +command, by specifying the flags in exactly the same order as they appear +in the option. For example, if you use the following command to remove the +'t' and 'n' flags from the 'formatoptions' option: > + + :set formatoptions-=tn +< +The 't' and 'n' flags will be removed from the 'formatoptions' option, only +if the 'formatoptions' option contains these flags in this order: 'tn'. +Otherwise, it will not remove the flags. To avoid this problem, you can +remove the flags one by one: > + + :set formatoptions-=t formatoptions-=n +< +For more information, read > + + :help :set-= +< + +============================================================================= + *faq-20* +SECTION 20 - MAPPING KEYS + + *faq-20.1* +20.1. How do I know what a key is mapped to? + +To see what a key is mapped to, use the following commands: > + + :map + :map! +< +You can also check the mappings in a particular mode using one of the +":cmap", ":nmap", ":vmap", ":imap", ":omap", etc commands. + +For more information, read > + + :help map-listing + :help map-overview +< + *faq-20.2* +20.2. How do list all the user-defined key mappings? + +You can list all the user-defined key mappings using: > + + :map +< +For more information, read > + + :help map-listing +< + *faq-20.3* +20.3. How do I unmap a previously mapped key? + +You can unmap a previously mapped key using the ":unmap" command: > + + :unmap + :unmap! +< +For mode specific mappings, you can use one of the +":nunmap/:vunmap/:ounmap/:iunmap/:lunmap/:cunmap" commands. + +The following command will fail to unmap a buffer-local mapped key: > + + :unmap +< +To unmap a buffer-local mapped key, you have to use the keyword in +the unmap command: > + + :unmap + :unmap! +< +For more information, read > + + :help :unmap + :help map-modes + :help map-local + :help 'mapleader' +< + *faq-20.4* +20.4. I am not able to create a mapping for the key. What is wrong? + +First make sure that the key is passed to Vim. In insert mode, press CTRL-V +followed by the desired key. You should see the keycode corresponding to +the key . If you do see the keycode, then you can create a mapping for the +key using the following command: > + + :map +< +For more information, read > + + :help map-keys-fails + :help :map-special-keys + :help key-codes +< + *faq-20.5* +20.5. How do I map the numeric keypad keys? + +First make sure that the numeric keypad keys are passed to Vim. Next, you +can use the following command to map the numeric keypad keys: > + + :map +< +where, can be kHome, kEnd, kPageUp, kPageDown, kPlus, kMinus, +kDivide, kMultiply, kEnter, etc. + +For more information, read > + + :help key-codes + :help terminal-options +< + *faq-20.6* +20.6. How do I create a mapping that works only in visual mode? + +You can create mappings that work only in specific mode (normal, command, +insert, visual, etc). To create a mapping that works only in the visual +mode, use the ":vmap" command: > + + :vmap +< +For more information, read > + + :help :vmap + :help map-modes + :help 40.1 +< + *faq-20.7* +20.7. In a Vim script, how do I know which keys to use for my mappings, so + that the mapped key will not collide with an already used key? + +Vim uses most of the keys in the keyboard. You can use the prefix +in maps to define keys which will not overlap with Vim keys. For example: > + + :map S s + :map j j + :map k k +< +where by default gets substituted with a backslash (\), so the +user would enter > + + \s + \j + \k +< +to invoke the above map commands. The user can change the mapleader +variable to be whatever they wanted: > + + :let mapleader = "," +< +When writing a plugin or other script, more often than not, it is advisable +to use :noremap instead of :map to avoid side effects from user defined +mappings. + +For more information, read > + + :help + :help + :help write-plugin +< + *faq-20.8* +20.8. How do I map the escape key? + +You can map the Escape key to some other key using the ":map" command. For +example, the following command maps the escape key to CTRL-O. > + + :map +< + *faq-20.9* +20.9. How do I map a key to perform nothing? + +You can map a key to to perform nothing when the key is pressed. For +example, with the following mappings, the key will do nothing when +pressed. > + + :map + :map! +< +For more information, read > + + :help + :help :map + :help :map! + :help map-modes +< + *faq-20.10* +20.10. I want to use the Tab key to indent a block of text and Shift-Tab + key to unindent a block of text. How do I map the keys to do this? + This behavior is similar to textpad, visual studio, etc. + +Use the following mapping: > + + :inoremap + :nnoremap >> + :nnoremap + :vnoremap > + :vnoremap +< +Note that, the mapping will work only if Vim receives the correct +key sequence. This is mostly the case with GUI Vim. + +For more information, read > + + :help :inoremap + :help :nnoremap + :help :vnoremap + :help + :help i_CTRL-O + :help >> + :help << + :help +< + *faq-20.11* +20.11. In my mappings the special characters like are not recognized. + How can I configure Vim to recognize special characters? + +Check the value of the 'cpoptions' option: > + + :set cpoptions? +< +If this option contains the '<' flag, then special characters will not be +recognized in mappings. Remove the '<' flag from 'cpoptions' option: > + + :set cpo-=< +< +Also, check the value of the 'compatible' option: > + + :se compatible? +< +The 'compatible' option must be reset: > + + :se nocompatible +< +For more information, read > + + :help 'cpoptions' + :help 'compatible' +< + *faq-20.12* +20.12. How do I use the '|' to separate multiple commands in a map? + +You can escape the '|' character using backslash (\) to use '|' in a map. > + + :map _l :!ls \| more +< +You can also try the following command: > + + :map _l :!ls more +< +There are also other ways to do this. + +For more information, read > + + :help map_bar +< + *faq-20.13* +20.13. If I have a mapping/abbreviation whose ending is the beginning of + another mapping/abbreviation, how do I keep the first from expanding + into the second one? + +Instead of using the ":map lhs rhs" command, use the ":noremap lhs rhs" +command. For abbreviations, use "noreabbrev lhs rhs". The "nore" prefix +prevents the mapping or abbreviation from being expanded again. + +For more information, read > + + :help :noremap + :help :noreabbrev +< + *faq-20.14* +20.14. Why does it take a second or more for Vim to process a key, + sometimes when I press a key? + +Make sure you have not defined a mapping for this key using the following +command: > + + :map +< +If a mapping is defined for this key and the mapped key contains more than +one character, then Vim will wait for the next character to be pressed to +determine whether it is the mapped key or not. For example, if you have +mapped "ab", then if you press "a", Vim will wait for the next key to be +pressed. If the next key is "b", Vim will execute the mapped sequence. +Otherwise, Vim will proceed with the normal processing of "a" followed by +the next key. If the 'timeout' option is set (which is the default), then +Vim will timeout after waiting for the period specified with the +'timeoutlen' option (default is 1 second). + +For more information, read > + + :help map-typing + :help 'timeoutlen' + :help 'ttimeoutlen' + :help 'timeout' + :help 'ttimeout' + :help vt100-cursor-keys + :help slow-fast-terminal +< + *faq-20.15* +20.15. How do I map a key to run an external command using a visually + selected text? + +You can the ":vmap" command to map a key in the visual mode. In the mapped +command sequence, you have to first yank the text. The yanked text is +available in the '"' register. Now, you can use the contents of this +register to run the external command. For example, to run the external +command "perldoc" on a visually selected text, you can use the following +mapping: > + + :vmap y:!exec "!perldoc '" . @" . "'" +< +If you want the mapping to work in the visual mode, but not with the +highlighted text, you can use the following command: > + + :vmap :!perldoc +< +The above mapping will use the word under the cursor instead of the +highlighted text. Note the use of the before invoking the "perldoc" +external command. The is used to erase the range of text selected in +the visual mode and displayed on the command line. If the visual range is +not removed using , then the output from the external command will +replace the visually selected text. + +For more information, read > + + :help :vmap + :help quote_quote + :help let-register + :help c_CTRL-U + :help :!cmd +< + *faq-20.16* +20.16. How do I map the Ctrl-I key while still retaining the functionality + of the key? + +The Ctrl-I key and the key produce the same keycode, so Vim cannot +distinguish between the Ctrl-I and the key. When you map the Ctrl-I +key, the key is also mapped (and vice versa). The same restriction +applies for the Ctrl-[ key and the key. + +For more information, read > + + :help keycodes +< + +============================================================================= + *faq-21* +SECTION 21 - ABBREVIATIONS + + *faq-21.1* +21.1. How do I auto correct misspelled words? + +You can auto correct misspelled words using abbreviations. For example, the +following abbreviation can be used to correct "teh" with "the": > + + :abbreviate teh the +< +Vim supports abbreviations in insert mode, replace mode and command-line +mode. + +For more information, read > + + :help 24.7 + :help abbreviations + :help Q_ab +< + *faq-21.2* +21.2. How do I create multi-line abbreviations? + +You can create multi-line abbreviations by embedding the "" +key code in the text: > + + iabbrev #c ---------------- Date:----------- +< +With the above abbreviation, when you type #c, it will be expanded to +the following text: + +-------------- +-- Date: +-- +--------- + +For more information, read > + + :help abbreviations +< + *faq-21.3* +21.3. When my abbreviations are expanded, an additional space character is + added at the end of the expanded text. How do I avoid this character? + +To avoid an additional space character at the end of the expanded text, you +can expand the abbreviation by pressing the CTRL-] key. The abbreviation +will be expanded without adding a space character at the end. + +Another alternative is to use the following function and command: + +function! Eatchar(pat) + let c = nr2char(getchar()) + return (c =~ a:pat) ? '' : c +endfunction +command! -nargs=+ Iabbr execute "iabbr" . "=Eatchar('\\s')" + +Now, define your abbreviations using the new "Iabbr" command instead of the +builtin "iabbrev" command. With this command, after expanding the +abbreviated text, the next typed space character will be discarded. + +For more information, read > + + :help abbreviations +< + *faq-21.4* +21.4. How do I insert the current date/time stamp into the file? + +You can use the strftime() function to insert the current data/time stamp +in a file. For example, you can use the following abbreviation: > + + iabbrev dts =strftime("%y/%m/%d %H:%M") +< +With this abbreviation, when you type dts in insert mode, it will be +expanded to the date/time stamp. + +Some other forms of the above abbreviation are listed below: > + + iabbrev mdyl =strftime("%a %d %b %Y") + iabbrev mdys =strftime("%y%m%d") + iabbrev mdyc =strftime("%c") + iabbrev hml =strftime("%d/%m/%y %H:%M:%S") + iabbrev hms =strftime("%H:%M:%S") +< +For more information, read > + + :help strftime() + :help i_CTRL-R +< + *faq-21.5* +21.5. How do I prevent an abbreviation from expanding in insert mode? + +You can prevent an abbreviation from expanding in insert mode by typing +CTRL-V before the character after the abrreviated word. + +For more information, read > + + :help abbreviations +< + +============================================================================= + *faq-22* +SECTION 22 - RECORD AND PLAYBACK + + *faq-22.1* +22.1. How do I repeat an editing operation (insertion, deletion, paste, + etc)? + +You can repeat the last editing operation using the '.' command. This will +repeat the last simple change like a insert, delete, change, paste, etc. + +For more information, read > + + :help 04.3 + :help single-repeat + :help Q_re +< + *faq-22.2* +22.2. How I record and repeat a set of key sequences? + +You can use the 'q' command in normal mode to record a set of key sequences +and store it in a register. For example, in the normal mode you can press q +followed by a register name {0-9a-bA-Z"} to start the recording. To +end/stop the recording press q again. You can playback/repeat the recorded +key sequences by pressing @ followed by the register name. e.g. @a. + +Another approach is to start Vim with the "-w" command-line argument. > + + $ vim -w +< +Vim will record all the characters typed in the session in the +specified file "file_name". You can use the recorded file with the "-s" +command line argument to play it back: > + + $ vim -s +< +For more information, read > + + :help 10.1 + :help recording + :help -w + :help -s +< + *faq-22.3* +22.3. How do I edit/modify a recorded set of key sequences? + +The recorded key sequences are stored in a register. You can paste the +contents of the register into a Vim buffer, edit the pasted text and again +yank the text into the register. You can also use the ":let" command to +modify the register. For example: > + + :let @a = "iHello World\" +< +For more information, read > + + :help recording + :help 10.1 + :help let-register + :help <> + :help 'cpoptions' +< + *faq-22.4* +22.4. How do I write recorded key sequences to a file? + +The recorded key sequences are stored in a register. You can paste the +contents of the register into a Vim buffer. Now you can save the buffer +into a file. You can also modify the pasted text and again yank into the +register to modify the recorded key sequence. For example, if you record a +set of key sequences using qa ..... q. The recorded key sequences are +stored in the register 'a'. You can paste the contents of register 'a' +using "ap. + +For more information, read > + + :help recording + :help 10.1 +< + *faq-22.5* +22.5. I am using register 0 to record my key sequences (i.e. q0 .... q). + In the recorded key sequences, I am yanking some text. After the + first replay of the recorded key sequence, I am no longer able to + play it back. + +Register 0 contains the text from the last yank operation. In your recorded +key sequence, when the yank is performed, register 0 is overwritten with +the yanked text. So your recording stored in register 0 is lost. You have +to use some other register. + +For more information, read > + + :help registers +< + +============================================================================= + *faq-23* +SECTION 23 - AUTOCOMMANDS + + *faq-23.1* +23.1. How do I execute a command when I try to modify a read-only file? + +You can use the FileChangedRO autocommand event to execute a command when a +read-only file modified. For example, you can use this event to checkout a +read-only file: > + + :autocmd FileChangedRO * call MyCheckoutFunction() +< +For more information, read > + + :help FileChangedRO +< + *faq-23.2* +23.2. How do I execute a command every time when entering a buffer? + +You can use the BufEnter autocommand event to execute a command every time +when entering a buffer. For example: > + + :autocmd BufEnter *.c set formatoptions=croqt +< +For more information, read > + + :help BufEnter +< + *faq-23.3* +23.3. How do I execute a command every time when entering a window? + +You can use the WinEnter autocommand event to execute a command every time +when entering a window. For example: > + + :autocmd WinEnter *.c call MyFunction() +< +For more information, read > + + :help WinEnter +< + *faq-23.4* +23.4. From an autocmd, how can I determine the name of the file or the + buffer number for which the autocommand is executed? + +You can use the special words or in an autocmd to get the +name of the file or the buffer number for which the autocommand is +executed. + +For more information, read > + + :help : + :help : + :help : +< + *faq-23.5* +23.5. How do I automatically save all the changed buffers whenever Vim + loses focus? + +You can define an autocommand for the FocusLost event which will save all +the modified buffers whenever Vim loses focus: > + + :autocmd FocusLost * wall +< +For more information, read > + + :help FocusLost + :help :wall +< + *faq-23.6* +23.6. How do I execute/run a function when Vim exits to do some cleanup? + +You can use VimLeave autocmd event to execute a function just before Vim +exists. For example, > + + :autocmd VimLeave * call MyCleanupFunction() +< +For more information, read > + + :help VimLeave +< + +============================================================================= + *faq-24* +SECTION 24 - SYNTAX HIGHLIGHT + + *faq-24.1* +24.1. How do I turn off/on syntax highlighting? + +By default, the Vim syntax highlighting is turned off. To enable the syntax +highlighting, you can use one of the following commands: > + + :syntax enable +< + or > + + :syntax on +< +To disable the syntax highlighting, you can use the following command: > + + :syntax off +< +For more information, read > + + :help 06.1 + :help 06.4 + :help :syntax-enable + :help :syntax-on + :help :syn-clear +< + *faq-24.2* +24.2. How do I change the background and foreground colors used by Vim? + +Vim uses the "Normal" highlight group for the background and foreground +colors. To change the foreground/background colors, you have to modify the +"Normal" highlight group. For example, to set the background color to blue +and foreground color to white, you can use > + + :highlight Normal ctermbg=blue ctermfg=white guibg=blue guifg=white +< +If you are using the Motif or the Athena version of the GUI Vim, then you +can modify the foreground and background resource names in the .Xdefaults +files to change the colors: > + + Vim.foreground: Black + Vim.backround: Wheat +< +You can also use the "-foreground" and "-background" command-line arguments +to specify the foreground and background colors. These arguments are +supported only in the Motif or Athena versions: > + + $ gvim -foreground Black -background Wheat +< +For more information, read > + + :help :highlight + :help .Xdefaults + :help -gui +< + *faq-24.3* +24.3. How do I change the highlight colors to suit a dark/light background? + +You can set the 'background' option to either 'dark' or 'light' to change +the highlight colors to suit a dark/light background: > + + :set background=dark +< +For more information, read > + + :help 'background' + :help 6.2 +< + *faq-24.4* +24.4. How do I change the color of the line numbers displayed when the + ":set number" command is used? + +The line numbers displayed use the LineNr highlighting group. To display +the current colors used, use > + + :hi LineNr +< +To change the color modify the LineNr highlight group. For example: > + + :hi linenr guifg=red guibg=black +< +This will give red numbers on a black background in GVIM. + +For more information, read > + + :help :highlight +< + *faq-24.5* +24.5. How do I change the background color used for a Visually selected + block? + +You can modify the 'Visual' highlight group to change the color used for a +visually selected block: > + + :highlight Visual guibg=red +< +For more information, read > + + :help :highlight + :help hl-Visual +< + *faq-24.6* +24.6. How do I highlight the special characters (tabs, trailing spaces, end + of line, etc) displayed by the 'list' option? + +You can modify the "NonText" and "SpecialKey" highlight groups to highlight +the special characters displayed by the 'list' option: > + + :highlight NonText guibg=red + :highlight SpecialKey guibg=green +< +The "NonText" highlighting group is used for "eol", "extends" and +"precedes" settings in the "listchars" option. The "SpecialKey" +highlighting group is used for the "tab" and "trail" settings. + +For more information, read > + + :help 'listchars' + :help hl-NonText + :help hl-SpecialKey +< + *faq-24.7* +24.7. How do I specify a colorscheme in my .vimrc/.gvimrc file, so that Vim + uses the specified colorscheme everytime? + +You can specify the color scheme using the ":colorscheme" command in your +.vimrc or .gvimrc file: > + + colorschme evening +< +For more information, read > + + :help :colorscheme +< + *faq-24.8* +24.8. Vim syntax highlighting is broken. When I am editing a file, some + parts of the file is not syntax highlighted or syntax highlighted + incorrectly. + +Vim doesn't read the whole file to parse the text for syntax highlighting. +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 refreshing the +screen using the CTRL-L key. Or scroll back a bit and then forward again. +You can also use the command: > + + :syntax sync fromstart +< +Note that this might considerably slow down the screen refreshing. + +For more information, read > + + :help :syn-sync + :help :syn-sync-first +< + *faq-24.9* +24.9. Is there a built-in function to syntax-highlight the corresponding + matching bracket? + +No. Vim doesn't support syntax-highlighting matching brackets. You can try +using the plugin developed by Charles Campbell: > + + http://vim.sourceforge.net/tips/tip.php?tip_id=177 +< +You can jump to a matching bracket using the '%' key. You can set the +'showmatch' option to temporarily jump to a matching bracket when in insert +mode. + +For more information, read > + + :help % + :help 'showmatch' + :help 'matchtime' + :help 'matchpairs' +< + *faq-24.10* +24.10. How do I turn off the C comment syntax highlighting? + +You can use the following command to turn off C comment syntax +highlighting: > + + :highlight clear comment +< +For more information, read > + + :help c-syntax +< + *faq-24.11* +24.11. How do I add my own syntax extensions to the standard syntax files + supplied with Vim? + +You should not modify the syntax files supplied with Vim to add your +extensions. When you install the next version of Vim, you will lose your +changes. Instead you should create a file under the ~/.vim/after/syntax +directory with the same name as the original syntax file and add your +additions to this file. + +For more information, read > + + :help mysyntaxfile-add + :help 'runtimepath' +< + *faq-24.12* +24.12. How do I replace a standard syntax file that comes with the Vim + distribution with my own syntax file? + +You can replace a standary syntax file that comes with the Vim distribution +by creating a file with the same name as the original syntax file and +placing it in the vim runtime syntax (~/.vim/syntax) directory. For +example, to replace the c.vim syntax file in a Unix system, place the new +c.vim in the ~/.vim/syntax directory. In a MS-Windows system, place the new +syntax file in the $HOME/vimfiles/syntax or $VIM/vimfiles/syntax directory. + +For more information, read > + + :help mysyntaxfile-replace + :help 44.11 + :help mysyntaxfile +< + *faq-24.13* +24.13. How do I highlight all the characters after a particular column? + +You can use the ":match" command to highlight all the characters after a +particular column: > + + :match Todo '\%>75v.\+' +< +This will highlight all the characters after the 75th column. + +For more information, read > + + :help :match + :help /\%v + :help /\+ + :help /. +< + *faq-24.14* +24.14. How do I convert a source file (.c, .h, etc) with the Vim syntax + highlighting into a HTML file? + +You can use the 2html.vim script to convert a source file into a HTML file +with the Vim syntax highlighting. Use the following command: > + + :runtime! syntax/2html.vim +< +For more information, read > + + :help convert-to-HTML +< + *faq-24.15* +24.15. How do I list the definition of all the current highlight groups? + +You can list the definition of all the current highlight groups using the +":highlight" (without any arguments) ex command. + +For more information, read > + + :help :highlight +< + +============================================================================= + *faq-25* +SECTION 25 - VIM SCRIPT WRITING + + *faq-25.1* +25.1. How do I list the names of all the scripts sourced by Vim? + +You can use the ":scriptnames" command to list the names of all the scripts +sourced by Vim: > + + :scriptnames +< +For more information, read > + + :help :scriptnames +< + *faq-25.2* +25.2. How do I debug Vim scripts? + +Vim has built-in support for a primitive debugger to debug Vim plugins and +scripts. Using this debugger you can set breakpoints and step through the +plugin functions. + +For more information, read > + + :help debug-scripts + :help -D +< + *faq-25.3* +25.3. How do I locate the script/plugin which sets a Vim option? + +You can use the ":verbose" command to locate the plugin/script which last +modified a Vim option. For example: > + + :verbose set textwidth? +< +For more information, read > + + :help :set-verbose + :help :verbose +< + *faq-25.4* +25.4. I am getting some error/informational messages from Vim (possibly + when running a script), the messages are cleared immediately. How do + I display the messages again? + +You can use the ":messages" command to display the previous messages. > + + :messages +< +For more information, read > + + :help :messages + :help :echoerr + :help :echomsg + :help message-history +< + *faq-25.5* +25.5. How do I save and restore a plugin specific information across Vim + invocations? + +Vim will save and restore global variables that start with an uppercase +letter and don't contain a lower case letter. For this to work, the +'viminfo' option must contain the '!' flag. Vim will store the variables in +the viminfo file. + +For more information, read > + + :help 'viminfo' + :help viminfo-file + :help variables +< + *faq-25.6* +25.6. How do I start insert mode from a Vim function? + +You can use the ":startinsert" command to start the insert mode from inside +a Vim function. + +For more information, read > + + :help :startinsert +< + *faq-25.7* +25.7. How do I change the cursor position from within a Vim function? + +You can use the cursor() function to position the cursor. > + + call cursor(lnum, col) +< +You can also use the following command to change the cursor position: > + + exe "normal! " . lnum . "G" . col . "|" +< +For more information, read > + + :help cursor() + :help bar +< + *faq-25.8* +25.8. How do I check the value of an environment variable in the .vimrc + file? + +You can use prefix the environment variable name with the '$' character to +use it from a Vim script/function. You can refer to the value of an +environment variable using the $env_var syntax: > + + if $EDITOR == 'vi' + endif +< +For more information, read > + + :help expr-env +< + *faq-25.9* +25.9. How do I check whether an environment variable is set or not from a + Vim function? + +You can use the exists() function to check for the existence of a +environment variable. > + + if exists("$MY_ENV_VAR") + endif +< +For more information, read > + + :help exists() + :help expr-env +< + *faq-25.10* +25.10. How do I call/use the Vim built-in functions? + +You can use the ":call" command to invoke a Vim built-in function: > + + :call cursor(10,20) +< +You can use the ":echo" command to echo the value returned by a function: > + + :echo char2nr('a') +< +You can use the ":let" command to assign the value returned by a function +to a variable: > + + :let a = getline('.') +< +To store the return value from a function into a Vim register, you can use +the following command: > + + :let @a = system('ls') +< +The above command will store the return value from the 'ls' command into +the register 'a'. + +For more information, read > + + :help :call + :help :echo + :help :let + :help :let-register + :help user-functions + :help usr_41.txt +< + *faq-25.11* +25.11. I am using some normal mode commands in my Vim script. How do I + avoid using the user-defined mappings for these normal mode commands + and use the standard Vim functionality for these normal mode + commands? + +You can use the "normal!" command in your script to invoke a normal-mode +command. This will use the standard functionality of the normal mode +command and will not use the user-defined mapping. + +For more information, read > + + :help :normal +< + *faq-25.12* +25.12. How do I get the current visually selected text into a Vim variable + or register? + +You can get the current visually selected text into a Vim variable by +yanking the text into Vim register and then assigning the contents of the +register into the variable: > + + :normal! gvy + :let myvar = @" +< +The above command copies the visually selected text into the variable +"myvar". + +You can also use the command: > + + :normal! gv"*y +< +In the above command, gv reselects the last visually selected text and the +rest of the command copies the selected text into the * (clipboard) +register. Alternatively, you can set the 'a' flag in the 'guioptions' +option to automatically copy a visually selected text into the * register. +To do this as part of a visual map, you can use a command similar to the +one shown below: > + + :vmap "*y:call ... +< +For more information, read > + + :help gv + :help :normal + :help let-@ + :help quotestar + :help clipboard + :help registers +< + *faq-25.13* +25.13. I have some text in a Vim variable 'myvar'. I would like to use this + variable in a ":s" substitute command to replace a text 'mytext'. + How do I do this? + +You can use the 'execute' command to evaluate the variable: > + + :execute '%s/mytext/' . myvar . '/' +< +For more information, read > + + :help :execute +< +You can also use "\=" in the substitute command to evaluate the variable: > + + :%s/mytext/\=myvar/ +< +For more information, read > + + :help sub-replace-special +< + *faq-25.14* +25.14. A Vim variable (bno) contains a buffer number. How do I use this + variable to open the corresponding buffer? + +The :buffer command will not accept a variable name. It accepts only a +buffer number or buffer name. You have to use the ":execute" command to +evaluate the variable into the corresponding value. For example: > + + :execute "buffer " . bno +< +For more information, read > + + :help :execute +< + *faq-25.15* +25.15. How do I store the value of a Vim option into a Vim variable? + +You can prefix the option name with the '&' character and assign the option +value to a Vim variable using the "let" command. For example, to store the +value of the 'textwidth' option into the Vim variable "old_tw", you can use +the following command: > + + :let old_tw = &tw +< +To do the opposite, to set the 'textwidth' option with the value stored in +the 'old_tw' variable, you can use the following command: > + + :let &tw = old_tw +< +For more information, read > + + :help expr-option + :help let-option +< + *faq-25.16* +25.16. I have copied and inserted some text into a buffer from a Vim + function. How do I indent the inserted text from the Vim function? + +You can use the following command to format the just inserted text: > + + :normal '[='] +< +For more information, read > + + :help '[ + :help '] + :help = + :help :normal +< + *faq-25.17* +25.17. How do I get the character under the cursor from a Vim script? + +You can use the getline() function and use string index [] to get the +character: > + + :echo getline(".")[col(".") - 1] +< +In the above command, getline(".") returns the text in the current line. +The indexing of the string starts at zero, and you can get a single +character in a string by its index with the "string[index]" notation. The +col(".") returns the column of the cursor position; the adjustment is to +get the right character of the string. + +Alternatively, you can use the following sequence of commands to get the +character under the cursor: > + + normal! vy + let ch=@" +< +Note that the above commands will change the '< and '> marks. + +For more information, read > + + :help getline() + :help col() + :help expr-[] +< + *faq-25.18* +25.18. How do I get the name of the current file without the extension? + +You can get the name of the current file without the extension using: > + + :echo expand("%:r") +< +With some commands, you can use the file name modifiers directly: > + + :cd %:p:h + :!gcc -o %:r.o % +< +For more information, read > + + :help filename-modifiers + :help expand() + :help cmdline-special + :help fnamemodify() +< + *faq-25.19* +25.19. How do I get the basename of the current file? + +You can use the :t filename modifier to get the basename of the current +file: > + + :echo expand("%:t") +< +For more information, read > + + :help filename-modifiers +< + *faq-25.20* +25.20. How do I get the output from a Vim function into the current buffer? + +You can insert the return value from a function using the following command +in insert mode: > + + =MyFunc() +< +Note that this will only insert the return value of the function. + +For more information, read > + + :help i_CTRL-R + :help i_CTRL-R_CTRL-R + :help i_CTRL-R_CTRL-O + :help expression +< + *faq-25.21* +25.21. How do I call external programs from a Vim function? + +There are several ways to call external programs from a Vim function. You +can use the builtin system() function to invoke external programs and get +the result: > + + :let output = system("ls") +< +You can also use "!" ex-command to run an external command. + +For more information, read > + + :help system() + :help :! + :help 10.9 +< + *faq-25.22* +25.22. How do I get the return status of a program executed using the ":!" + command? + +You can use the predefined Vim v:shell_error variable to get the return +status of the last run shell command. + +For more information, read > + + :help v:shell_error +< + *faq-25.23* +25.23. How do I determine whether the current buffer is modified or not? + +You can check the value of the 'modified' option to determine whether the +current buffer is modified: > + + :set modified? +< +From a Vim script, you can check the value of the 'modified' option: > + + if &modified + echo "File is modified" + endif +< +For more information, read > + + :help 'modified' +< + *faq-25.24* +25.24. I would like to use the carriage return character in a normal + command from a Vim script. How do I specify the carriage return + character? + +You can use the ":execute" command to specify the special (control) +character in a normal mode command: > + + :execute "normal \" + :execute "normal ixxx\" +< +For more information, read > + + :help :execute + :help expr-quote +< + *faq-25.25* +25.25. How do I split long lines in a Vim script? + +You can split long lines in a Vim script by inserting the backslash +character ("\") at the start of the next line. For example, + +For more information, read > + + :help line-continuation +< + *faq-25.26* +25.26. When I try to "execute" my function using the "execute 'echo + Myfunc()'" command, the cursor is moved to the top of the current + buffer. Why? + +The ":execute" command runs the normal mode command specified by the +argument. In the case of the following command: > + + :execute "echo Myfunc()" +< +The call to "echo Myfunc()" will return 0. The ":execute" command will run +the normal mode command "0", which moves the cursor to the top of the file. +To call a Vim function, you should use the ":call" command instead of the +":execute" command: > + + :call Myfunc() +< +For more information, read > + + :help :call + :help :execute + :help :echo + :help user-functions + :help 41.5 + :help 41.6 +< + *faq-25.27* +25.27. How do I source/execute the contents of a register? + +If you have yanked a set of Vim commands into a Vim register (for example +register 'a'), then you can source the contents of the register using one +of the following commands: + + :@a +or + :exe @a + +For more information, read > + + :help :@ +< + *faq-25.28* +25.28. After calling a Vim function or a mapping, when I press the 'u' + key to undo the last change, Vim undoes all the changes made by + the mapping/function. Why? + +When you call a function or a mapping, all the operations performed by the +function/mapping are treated as one single operation. When you undo the +last operation by pressing 'u', all the changes made by the +function/mapping are reversed. + +For more information, read > + + :help undo-redo + :help map-undo +< + *faq-25.29* +25.29. How can I call a function defined with s: (script local function) + from another script/plugin? + +The s: prefix for a Vim function name is used to create a script local +function. A script local function can be called only from within that +script and cannot be called from other scripts. To define a function in a +script/plugin, so that it can be called from other plugins/scripts, define +the function without the s: prefix. + +For more information, read > + + :help script-variable + :help script-local + :help :scriptnames +< + *faq-25.30* +25.30. Is it possible to un-source a sourced script? In otherwords, reverse + all the commands executed by sourcing a script. + +No. It is not possible to reverse or undo all the commands executed by +sourcing a script. + +For more information, read > + + :help :source +< + +============================================================================= + *faq-26* +SECTION 26 - PLUGINS + + *faq-26.1* +26.1. How do I set different options for different types of files? + +You can create filetype plugins to set different options for different +types of files. You should first enable filetype plugins using the command: > + + :filetype plugin on +< +A filetype plugin is a vim script that is loaded whenever Vim opens or +creates a file of that type. For example, to ensure that the 'textwidth' +option is set to 80 when editing a C program (filetype 'c'), create one of +the following files: > + + ~/.vim/ftplugin/c.vim (Unix) + %HOME%\vimfiles\ftplugin\c.vim (Windows) +< +with the following text in it: > + + setlocal textwidth=80 +< +You can also use autocommands to set specific options when editing specific +type of files. For example, to set the 'textwidth' option to 75 for only +*.txt files, you can use the following autocmd: > + + autocmd BufRead *.txt setlocal textwidth=80 +< +For more information, read > + + :help filetype-plugin + :help add-filetype-plugin + :help autocmd + :help 40.3 +< + *faq-26.2* +26.2. I have downloaded a Vim plugin or a syntax file or a indent file, or + a color scheme or a filetype plugin from the web. Where should I copy + these files so that Vim will find them? + +You can place the Vim runtime files (plugins, syntax files, indent files, +color schemes, filetype plugins, etc) under one of the directories +specified in the 'runtimepath' option. To determine the current value of +the 'runtimepath' option, use the following command: > + + :set runtimepath +< +For Unix systems, this is usally the "$HOME/.vim" directory. For MS-Windows +systems, this is usually the $VIM\vimfiles or $HOME\vimfiles directory. +Depending on the type of the runtime file, you have to place it under a +specific directory under the above runtime directory. The names of the +directories are listed below: > + + colors/ - color scheme files + compiler/ - compiler files + doc/ - documentation + ftplugin/ - filetype plugins + indent/ - indent scripts + keymap/ - key mapping files + lang/ - menu translations + plugin/ - plugin scripts + syntax/ - syntax files + tutor/ - files for vimtutor +< +For more information, read > + + :help your-runtime-dir + :help 'runtimepath' + :help :runtime +< + *faq-26.3* +26.3. How do I extend an existing filetype plugin? + +You can extend an existing filetype plugin by creating a file under either +the $VIMRTUNTIME/after/ftplugin or the $VIMRTUNTIME/ftplugin directory. The +name of the file should be the same as the name of the existing filetype +plugin file. You can place your additions to the new file. + +If you placed the file in the after/ftplugin runtime directory, then Vim +will first source the existing filetype plugin file and then will source +the new file. If you placed the file in the $VIMRTUNTIME/ftplugin runtime +directory, then Vim will first source the new file and then will source the +existing filetype plugin file. + +For more information, read > + + :help ftplugin-overrule + :help filetype-plugin + :help add-filetype-plugin + :help 'runtimepath' +< + *faq-26.4* +26.4. How do I turn off loading the Vim plugins? + +You can reset the 'loadplugins' option to turn off loading the plugins: > + + :set noloadplugins +< +You can also specify the "--noplugin" command line argument to stop loading +the plugins: > + + $ vim --noplugin +< +For more information, read > + + :help 'loadplugins' + :help --noplugin + :help load-plugins +< + *faq-26.5* +26.5. How do I turn on/off loading the filetype plugins? + +By default, Vim will not load the filetype plugins. You can configure Vim +to load filetype plugins using the command: > + + filetype plugin on +< +You can turn off loading the filetype plugins using: > + + filetype plugin off +< +For more information, read > + + :help filetype-plugin-on + :help filetype-plugin-off + :help :filetype +< + *faq-26.6* +26.6. How do I override settings made in a file type plugin in the global + ftplugin directory for all the file types? + +You can use an autocommand triggered on the FileType event: > + + au Filetype * set formatoptions=xyz +< +This should at least be after "filetype on" in your vimrc. Best is to put +it in your "myfiletypefile" file, so that it's always last. + +If you want to override a setting for a particular filetype, then create a +file with the same name as the original filetype plugin in the +~/.vim/after/ftplugin directory For example, to override a setting in the +c.vim filetype plugin, create a c.vim file in the ~/.vim/after/ftplugin +directory and add your preferences in this file. + +For more information, read > + + :help ftplugin-overrule + :help ftplugins + :help myfiletypefile +< + *faq-26.7* +26.7. How do I disable the Vim directory browser plugin? + +To disable the directory browsing Vim plugin, add the following line to +your .vimrc file: > + + let loaded_explorer = 1 +< +For more information, read > + + :help file-explorer +< + *faq-26.8* +26.8. How do I set the filetype option for files with names matching a + particular pattern or depending on the file extension? + +You can set the 'filetype' option for files with names matching a +particular pattern using an autocmd. For example, to set the 'filetype' +option to 'c' for all files with extension '.x', you can use the following +autocmd: > + + autocmd! BufRead,BufNewFile *.x setfiletype c +< +A better alternative to the above approach is to create a filetype.vim file +in the ~/.vim directory (or in one of the directories specified in the +'runtimepath' option) and add the following lines: > + + " my filetype file + if exists("did_load_filetypes") + finish + endif + augroup filetypedetect + au! BufRead,BufNewFile *.x setfiletype c + augroup END +< +For more information, read > + + :help new-filetype + :help 43.2 + :help :setfiletype +< + +============================================================================= + *faq-27* +SECTION 27 - EDITING PROGRAM FILES + + *faq-27.1* +27.1. How do I enable automatic indentation for C/C++ files? + +You can enable file-type based indentation using: > + + :filetype indent on +< +If you want to only enable automatic C indentation, then use: > + + :set cindent +< +For more information, read > + + :help 'cindent' + :help C-indenting + :help filetype +< + *faq-27.2* +27.2. How do I configure the indentation used for C/C++ files? + +You can configure the Vim C indentation by modifying the value of the +'cinoptions', 'cinkeys' and 'cinwords' options. + +For more information, read > + + :help 'cindent' + :help 'cinoptions' + :help 'cinkeys' + :help 'cinwords' + :help C-indenting + :help cinoptions-values + :help 'smartindent' +< + *faq-27.3* +27.3. How do I turn off the automatic indentation feature? + +By default, the automatic indentation is not turned on. You must have +configured Vim to do automatic indentation in either .vimrc or .gvimrc +files. You can disable automatic indentation using either, > + + :filetype indent off +< +or > + + :set nocindent +< +Also, check the setting for the following options: > + + :set autoindent? + :set smartindent? + :set indentexpr? +< +For more information, read > + + :help 'cindent' + :help filetype-indent-off + :help 'autoindent' + :help 'smartindent' + :help 'indentexpr' +< + *faq-27.4* +27.4. How do I change the number of space characters used for the automatic + indentation? + +You can modify the 'shiftwidth' option to change the number of space +characters used for the automatic indentation: > + + :set shiftwidth=4 +< +For more information, read > + + :help 'shiftwidth' +< + *faq-27.5* +27.5. I am editing a C program using Vim. How do I display the definition + of a macro or a variable? + +You can use the [d command to display the definition of a macro and the [i +command to display the definition of a variable. + +For more information, read > + + :help [d + :help [i + :help include-search + :help 29.4 + :help 29.5 +< + *faq-27.6* +27.6. I am editing a C program using Vim. How do I jump to the beginning or + end of a code block from within the block? + +You can use '[{' command to jump to the beginning of the code block and ']} +to jump to the end of the code block from inside the block. + +For more information, read > + + :help [{ + :help ]} + :help various-motions +< + *faq-27.7* +27.7. Is there a way to turn off the "//" comment auto-insertion behavior + for C++ files? If I'm sitting on a line beginning with "//", then I + open a new line above or below it, Vim automatically inserts new "//" + chars. + +You can modify the value of the 'comments' option to stop Vim from +inserting the C++ comment character ("//") automatically. For example: > + + :set comments=sr:/*,mb:*,el:*/ +< +For more information, read > + + :help 'comments' + :help format-comments +< + *faq-27.8* +27.8. How do I add the comment character '#' to a set of lines at the + beginning of each line? + +First, select the first character in all the lines using visual block mode +(CTRL-V). Press 'I' to start inserting characters at the beginning of the +line. Enter the comment character and then stop the insert mode by pressing +. Vim will automatically insert the entered characters at the +beginning of all the selected lines. + +For more information, read > + + :help visual-block + :help blockwise-operators + :help v_b_I +< + *faq-27.9* +27.9. How do I edit a header file with the same name as the corresponding C + source file? + +You can use the following command to edit a header file with the same name +as the corresponding C source file: > + + :e %:t:r.h +< +You can use the following command to edit the file in a new split window: > + + :sp %:t:r.h +< +In the above commands, the percent sign expands to the name of the current +file. The ":t" modifier extracts the tail (last component) of the +filename. The ":r" modifier extracts the root of the filename. The .h is +appended to the resulting name to get the header filename. + +Another approach is to use the following command: > + + :sfind %:t:r.h +< +This command will search for the header file in the directories specified +in the 'path' option. + +For more information, read > + + :help cmdline-special + :help filename-modifiers + :help :sfind + :help 'path' +< + *faq-27.10* +27.10. How do I automatically insert comment leaders while typing comments? + +To automatically insert comment leaders while typing comments, add the 'r' +and 'o' flags to the 'formatoptions' option. > + + :set formatoptions+=ro +< +You may also want to add the 'c' flag to auto-wrap comments using the +'textwidth' option setting and the 'q' flag to format comments with the +"gq" command: > + + :set formatoptions=croq +< +For more information, read > + + :help 30.6 + :help format-comments + :help 'comments' + :help fo-table +< + +============================================================================= + *faq-28* +SECTION 28 - QUICKFIX + + *faq-28.1* +28.1. How do I build programs from Vim? + +You can use the ":make" command to build programs from Vim. The ":make" +command runs the program specified by the 'makeprg' option. + +For more information, read > + + :help 30.1 + :help make_makeprg + :help 'makeprg' + :help 'makeef' + :help :make + :help quickfix +< + *faq-28.2* +28.2. When I run the make command in Vim I get the errors listed as the + compiler compiles the program. When it finishes this list disappears + and I have to use the :clist command to see the error message again. + Is there any other way to see these error messages? + +You can use the ":copen" or ":cwindow" command to open the quickfix window +that contains the compiler output. You can select different error lines +from this window and jump to the corresponding line in the source code. + +For more information, read > + + :help :copen + :help :cwindow + :help quickfix +< + +============================================================================= + *faq-29* +SECTION 29 - FOLDING + + *faq-29.1* +29.1. How do I extend the Vim folding support? + +You can use the 'foldexpr' option to fold using an user specified function. +For example, to fold subroutines of the following form into a single line: > + + sub foo { + my $barf; + $barf = 3; + return $barf; + } +< +You can use the following commands: > + + set foldmethod=expr + set foldexpr=MyFoldExpr(v:lnum) + fun! MyFoldExpr(line) + let str = getline(a:line) + if str =~ '^sub\>' + return '1' + elseif str =~ '^}' + return '<1' + else + return foldlevel(a:line - 1) + endif + endfun +< +For more information, read > + + :help 'foldexpr' + :help fold-expr +< + *faq-29.2* +29.2. When I enable folding by setting the 'foldmethod' option, all the + folds are closed. How do I prevent this? + +You can set the 'foldlevelstart' option to a particular value to close only +folds above the specified value. > + + :set foldlevelstart=99 +< +For more information, read > + + :help 'foldlevelstart' + :help 'foldlevel' + :help fold-foldlevel +< + *faq-29.3* +29.3. How do I control how many folds will be opened when I start editing a + file? + +You can modify the 'foldlevelstart' option to control the number of folds +that will be opened when you start editing a file. To start editing with +all the folds closed: > + + :set foldlevelstart=0 +< +For more information, read > + + :help 'foldlevelstart' +< + *faq-29.4* +29.4. How do I open and close folds using the mouse? + +You can click on the + and - characters displayed at the leftmost column to +open and close fold. For this to work, you have to set the 'foldcolumn' +to a value greater than zero: > + + :set foldcolumn=2 +< +For more information, read > + + :help 'foldcolumn' +< + *faq-29.5* +29.5. How do I change the text displayed for a closed fold? + +You can use the 'foldtext' option to change the text displayed for a closed +fold. + +For more information, read > + + :help 'foldtext' + :help fold-foldtext + :help 'fillchars' +< + *faq-29.6* +29.6. How do I store and restore manually created folds across different + Vim invocations? + +You can use the ":mkview" command to store manually created folds. Later, +you can use the ":loadview" command to restore the folds. For this to work, +the 'viewoptions' must contain "folds". + +For more information, read > + + :help 28.4 + :help :mkview + :help :loadview + :help 'viewoptions' + :help 'viewdir' + :help :mksession + :help 'sessionoptions' +< + +============================================================================= + *faq-30* +SECTION 30 - VIM WITH EXTERNAL APPLICATIONS + + *faq-30.1* +30.1. Can I run a shell inside a Vim window? + +Currently Vim doesn't have support for running shell and other external +commands inside a Vim window. + +For more information, read > + + :help shell-window +< +Alternatively, you can try using the Unix "screen" utility or the 'splitvt' +program. + +You can also use the vimsh plugin by Brian Sturk to run a shell in a Vim +window. To use this you need to have Vim built with python support. For +more information visit the following URL: > + + http://vim.sourceforge.net/scripts/script.php?script_id=165 +< + *faq-30.2* +30.2. How do I pass the word under the cursor to an external command? + +You can use the special keyword to pass the word under the cursor +to an external command. For example: > + + :!dict +< +For more information, read > + + :help +< + *faq-30.3* +30.3. How do I get the output of a shell command into a Vim buffer? + +You can use the ":r !" command to get the output of a shell command into a +Vim buffer: > + + :r !ls +< +For more information, read > + + :help :r! +< + *faq-30.4* +30.4. How do I pipe the contents of the current buffer to an external + command and replace the contents of the buffer with the output from + the command? + +You can use the :! command to pipe the contents of the current buffer to a +external command and replace the contents of the buffer with the output +from the command. For example, to sort the contents of the current buffer, +using the Unix sort command, you can use the following command: > + + :%!sort +< +To sort only lines 10-20, you can use the following command > + + :10,20!sort +< +Also, if you want to pipe a buffer to an external command but not put the +results back in the buffer, you can use > + + :w !sort +< +The above command will pipe the entire buffer to the sort command. Note +that the space between the 'w' and the '!' is critical. To pipe only a +range of lines, you can use > + + :10,20w !sort +< +The above command will pipe the lines 10-20 to the sort command. + +For more information, read > + + :help :range! + :help 10.9 + :help :w_c +< + *faq-30.5* +30.5. How do I sort a section of my file? + +You can pipe a section of the file to the Unix "sort" utility to sort the +file. For example: > + + :5,100!sort +< +You can also use a visual block, and use the "!sort" command on the +selected block. + +To sort using visual blocks (sort based on a column or sort just the column +itself), read the following tip from the Vim online web page: + +http://vim.sourceforge.net/tips/tip.php?tip_id=588 + + *faq-30.6* +30.6. Is there a step-by-step guide for using Vim with slrn? + +Visit the following link to get information about using Vim with Slrn: > + + http://thingy.apana.org.au/~fun/slrn/ +< + *faq-30.7* +30.7. How do I use Vim as a pager? + +You can use Vim as a pager using the $VIMRUNTIME/macros/less.sh shell +script, supplied as part of the standard Vim distribution. This shell +script uses the $VIMRUNTIME/macros/less.vim Vim script to provide less like +key bindings. + +For more information, read > + + :help less +< + *faq-30.8* +30.8. How do I view Unix man pages from inside Vim? + +You can view Unix man pages, inside Vim, using the man.vim plugin supplied +as part of the standard Vim distribution. To use this plugin, add the +following line to your startup vimrc file: > + + runtime ftplugin/man.vim +< +You can also press the K key to run the program specified by the +'keywordprg' option with the keyword under the cursor. By default, +'keywordprg' is set to run man on the keyword under the cursor. + +For more information, read > + + :help man-plugin + :help K + :help 'keywordprg' +< + *faq-30.9* +30.9. How do I change the diff command used by the Vim diff support? + +By default, the Vim diff support uses the 'diff' command. You can change +this by changing the 'diffexpr' option. + +For more information, read > + + :help diff-diffexpr + :help 'diffexpr' +< + *faq-30.10* +30.10. How do I use the Vim diff mode without folding? + +You can use the following command-line to start Vim with two filenames +and use the diff mode without folding: > + + $ vim -o file1 file2 "+windo set diff scrollbind scrollopt+=hor nowrap" +< +If you like vertically split windows, then replace "-o" with "-O". + +For more information, read > + + :help vimdiff +< + +============================================================================= + *faq-31* +SECTION 31 - GUI VIM + + *faq-31.1* +31.1. How do I create buffer specific menus? + +Adding support for buffer specific menus is in the Vim TODO list. In the +mean time, you can try Michael Geddes's plugin, buffermenu.vim: > + + http://vim.sourceforge.net/scripts/script.php?script_id=246 +< + *faq-31.2* +31.2. How do I change the font used by GUI Vim? + +You can change the 'guifont' option to change the font used by GUI Vim. To +display the current value of this option, you can use > + + :set guifont? +< +You can add the displayed font name to the .vimrc file to use the font +across Vim sessions. For example, add the following line to the .vimrc file +to use Andale Mono font. > + + set guifont=Andale_Mono:h10:cANSI +< +For Win32, GTK and Photon version of Vim, you can use the following command +to bringup a dialog which will help you in changing the guifont: > + + :set guifont=* +< +You can also use the -font Vim command line option to specify the font used +for normal text. + +For more information, read > + + :help 'guifont' + :help 'guifontset' + :help 'guifontwide' + :help font-sizes + :help -font + :help -boldfont + :help -italicfont + :help -menufont + :help -menufontset +< + *faq-31.3* +31.3. When starting GUI Vim, how do I specify the location of the GVIM + window? + +You can use the "-geometry" command line argument to specify the location +of the GUI Vim window. For example: > + + $ gvim -geometry 80x25+100+300 +< +For more information, read > + + :help 31.4 + :help -geom +< + *faq-31.4* +31.4. How do I add a horizontal scrollbar in GVim? + +You can enable the horizontal scrollbar by modifying the 'guioptions' +option: > + + :set guioptions+=b +< +For more information, read > + + :help 'guioptions' + :help gui-horiz-scroll +< + *faq-31.5* +31.5. How do I make the scrollbar appear in the left side by default? + +You can add the 'l' flag to the 'guioptions' option to make the scrollbar +appear in the left side. > + + :set guioptions+=l + :set guioptions-=r +< +For more information, read > + + :help 'guioptions' + :help gui-scrollbars +< + *faq-31.6* +31.6. How do I remove the Vim menubar? + +You can remove the Vim menubar by removing the 'm' flag from the +'guioptions' option: > + + :set guioptions-=m +< +For more information, read > + + :help 'guioptions' +< + *faq-31.7* +31.7. I am using GUI Vim. When I press the ALT key and a letter, the menu + starting with that letter is selected. I don't want this behavior as + I want to map the ALT- combination. How do I do this? + +You can use the 'winaltkeys' option to disable the use of the ALT key to +select a menu item: > + + :set winaltkeys=no +< +For more information, read > + + :help 'winaltkeys' + :help :simalt +< + *faq-31.8* +31.8. Is it possible to scroll the text by dragging the scrollbar so that + the cursor stays in the original location? + +The way Vim is designed, the cursor position has to be in a visible spot in +normal, visual, select and insert mode. This cannot be changed without +modifying Vim. When the scrollbar is used, the cursor will be moved so that +it is always visible. Another approach to solving this problem is to use +the Vim marks. You can mark the current cursor position using ma. Then +scroll to a different part of the text and jump back to the old position +using `a. You can also try the following suggestion from the Vim Online +website: > + + http://www.vim.org/tip_view.php?tip_id=320 +< +For more information, read > + + :help mark-motions +< + *faq-31.9* +31.9. How do I get gvim to start browsing files in a particular directory + when using the ":browse" command? + +You can set the 'browsedir' option to the default directory to use for the +":browse" command. > + + :set browsedir='' +< +For more information, read > + + :help 'browsedir' +< + *faq-31.10* +31.10. For some questions, like when a file is changed outside of Vim, Vim + displays a GUI dialog box. How do I replace this GUI dialog box with + a console dialog box? + +You can set the 'c' flag in the 'guioptions' option to configure Vim to use +console dialogs instead of GUI dialogs: > + + :set guioptions+=c +< +For more information, read > + + :help 'guioptions' +< + *faq-31.11* +31.11. I am trying to use GUI Vim as the editor for my xxx application. + When the xxx application launches GUI Vim to edit a file, the + control immediately returns to the xxx application. How do I start + GUI Vim, so that the control returns to the xxx application only + after I quit Vim? + +You have to start GUI Vim with the '-f' (foreground) command line option: > + + $ gvim -f +< +By default, GUI Vim will disconnect from the program that started Vim. With +the '-f' option, GUI Vim will not disconnect from the program that started +it. + +For more information, read > + + :help gui-fork + :help -f +< + *faq-31.12* +31.12. Why does the "Select Font" dialog doesn't show all the fonts + installed in my system? + +Vim supports only fixed width (mono-spaced) fonts. Proportional fonts are +not supported. In the "Select Font" dialog, only fixed width fonts will be +displayed. + +For more information, read > + + :help font-sizes + :help 'guifont' +< + *faq-31.13* +31.13. How do I use the mouse in Vim command-line mode? + +You can set the 'c' flag in the 'mouse' option to use mouse in the Vim +command-line mode: > + + :set mouse+=c +< +For more information, read > + + :help mouse-using + :help gui-mouse + :help 09.2 +< + *faq-31.14* +31.14. When I use the middle mouse button to scroll text, it pastes the + last copied text. How do I disable this behavior? + +You can map the middle mouse button to to disable the middle mouse +button: > + + :map + :map! +< +For more information, read > + + :help gui-mouse-mapping + :help +< + *faq-31.15* +31.15. How do I change the location and size of a GUI Vim window? + +You can use the "winpos" command to change the Vim window position. To +change the size of the window, you can modify the "lines" and "columns" +options. + +For example, the following commands will position the GUI Vim window at the +X,Y co-ordinates 50,50 and set the number of lines to 50 and the number of +columsn to 80. > + + :winpos 50 50 + :set lines=50 + :set columns=80 +< +The arguments to the 'winpos' command specify the pixel co-ordinates of the +Vim window. The 'lines' and 'columns' options specify the number of lines +and characters to use for the height and the width of the window +respectively. + +For more information, read > + + :help 31.4 + :help :winpos + :help 'lines' + :help 'columns' + :help GUIEnter +< + +============================================================================= + *faq-32* +SECTION 32 - VIM ON UNIX + + *faq-32.1* +32.1. I am running Vim in a xterm. When I press the CTRL-S key, Vim + freezes. What should I do now? + +Many terminal emulators and real terminal drivers use the CTRL-S key to +stop the data from arriving so that you can stop a fast scrolling display +to look at it (also allowed older terminals to slow down the computer so +that it did not get buffer overflows). You can start the output again by +pressing the CTRL-Q key. + +When you press the CTRL-S key, the terminal driver will stop sending the +output data. As a result of this, it will look like Vim is hung. If you +press the CTRL-Q key, then everything will be back to normal. + +You can turn off the terminal driver flow control using the 'stty' command: > + + $ stty -ixon -ixoff +< +or, you can change the keys used for the terminal flow control, using the +following commands: > + + $ stty stop + $ stty start +< + *faq-32.2* +32.2. I am seeing weird screen update problems in Vim. What can I do to + solve this screen/display update problems? + +You have to use a proper terminal emulator like xterm with correct TERM +settings (TERM=xterm) and a correct terminfo/termcap file. +For more information, read > + + :help 'term' +< + *faq-32.3* +32.3. I am using the terminal/console version of Vim. In insertmode, When I + press the backspace key, the character before the cursor is not + erased. How do I configure Vim to do this? + +You have to make sure that Vim gets the correct keycode for the backpspace +key. You can try using the command: > + + :fixdel +< +Make sure the TERM environment variable is set to the correct terminal +name. You can try using the 'stty' command: > + + $ stty erase ^H +< +where, you have to enter the ^H character by pressing the CTRL-V key and +then the CTRL-H key. + +For more information, read > + + :help :fixdel + :help Linux-backspace + :help NetBSD-backspace +< + *faq-32.4* +32.4. I am using Vim in a xterm. When I quit Vim, the screen contents are + restored back to the original contents. How do I disable this? + +The xterm has a capability called "alternate screen". If this capability +is present, vim switches to that alternate screen upon startup and back on +exit, thus restoring the original screen contents. To disable this +feature, add the following line to your .vimrc file: > + + :set t_ti= t_te= +< +For more information, read > + + :help restorescreen + :help xterm-screens +< + *faq-32.5* +32.5. When I start Vim, it takes quite a few seconds to start. How do I + minimize the startup time? + +This may be related to Vim opening the X display for setting the xterm +title and using the X clipboard. Make sure the DISPLAY variable is set to +point to the correct host. Try using the command line: > + + $ vim -X +< +This will prevent Vim from opening the X display. With this command-line +option, the X clipboard cannot be used and also Vim will not be able to +change the xterm title. + +You can also set the 'clipboard' option to > + + :set clipboard=exclude:.* +< +This has the same effect as using the -X command-line argument. + +For more information, read > + + :help -X + :help 'clipboard' +< + *faq-32.6* +32.6. How can I make the cursor in gvim in unix stop blinking? + +You can modify the 'guicursor' option, to stop the cursor from blinking. +For example: > + + :set guicursor=a:blinkon0 +< +For more information, read > + + :help 'guicursor' +< + *faq-32.7* +32.7. How do I change the menu font on GTK Vim? + +You can modify the ~/.gtkrc file to change the menu font on GTK Vim. For +example: > + + style "default" + { font ="smooth09" } + class "*" style "default" +< +The last line changes the font of all widgets. + +For more information, read > + + :help gui-gtk +< + *faq-32.8* +32.8. How do I prevent from suspending Vim? + +You can map to prevent the suspending. Here are some suggestions: + +- Make do nothing: > + + :map +< +- Make start a shell: > + + :map :shell +< +- Make give an error message: > + + :map :"suspending disabled +< +For the last example, the double quote is necessary in order to keep the +message on the status line. + + *faq-32.9* +32.9. When I kill the xterm running Vim, the Vim process continues to run + and takes up a lot of CPU (99%) time. Why is this happening? + +When Vim is built with support for Python interface, you will have this +problem. This is a known problem with the python thread library and Vim. To +solve this problem, use a Vim binary built without the Python interface. + +For more information, read > + + :help +python + :help python +< + *faq-32.10* +32.10. How do I get the Vim syntax highlighting to work in a Unix terminal? + +The easiest and simplest way to get Vim syntax highlighting is to use the +GUI version of Vim (GVIM). To get syntax highlighting to work in the +console/terminal version of Vim, you have to run a terminal emulator (like +Xfree86 xterm or rxvt or dtterm) that supports color. Note that if a +terminal emulator supports changing the background and foreground colors, +that does not mean that it also supports ANSI escape sequences for changing +the color. You can download the latest version of Xfree86 xterm from +http://dickey.his.com/xterm/xterm.html. You can download the latest version +of rxvt from http://www.rxvt.org. You have to install the terminfo/termcap +file that supports colors for the terminal emulator. Also, set the TERM +environment variable to the correct name of the term that supports colors. + +You can use the colortest.vim script supplied with the Vim runtime +package to test the color setup. To use this script, follow these steps: > + + :e $VIMRUNTIME/syntax/colortest.vim + :source % +< +For more information, read > + + :help 06.2 + :help terminal-colors + :help termcap-colors + :help startup-terminal + :help xterm-color + :help colortest.vim +< + +============================================================================= + *faq-33* +SECTION 33 - VIM ON MS-WINDOWS + + *faq-33.1* +33.1. In MS-Windows, CTRL-V doesn't start the blockwise visual mode. What + happened? + +The mswin.vim script provides key mappings and options to make Vim behave +like a MS-Windows application. One of the keys mapped is CTRL-V which is +used for pasting text in MS-Windows applications. This will disable the use +of CTRL-V to start the blockwise visual mode. The mswin.vim script maps +CTRL-Q for staring the blockwise visual mode. So you can use CTRL-Q instead +of CTRL-V. + +For more information, read > + + :help CTRL-V + :help CTRl-V-alternative + :help CTRL-Q + :help 10.5 +< + *faq-33.2* +33.2. When I press the CTRL-Y key, it acts like the CTRL-R key. How do I + configure Vim to treat CTRL-Y as CTRL-Y? + +The mapping of the CTRL-Y key to the CTRL-R key is done by the mswin.vim +script. The mswin.vim script maps CTRL-Y to make Vim behave like a standard +MS-Windows application. This is explained in ":help CTRL-Y". You can either +comment out the line in mswin.vim that maps the CTRL-Y key or you can +remove the line in your .vimrc file that sources the mswin.vim script. + + *faq-33.3* +33.3. How do I start GUI Vim in a maximized window always? + +You can use the "simalt" command to maximize the Vim window. You can use +the GUIEnter autocmd to maximize the Vim window on startup: > + + autocmd GUIEnter * simalt ~x +< +For more information, read > + + :help :simalt + :help GUIEnter + :help gui-win32-maximized +< + *faq-33.4* +33.4. After doing some editing operations, Vim freezes. The cursor becomes + an empty rectangle. I am not able enter any characters. What is + happening? + +Most probably, you used the mouse wheel to scroll the text in Vim. There is +a known problem in using intellimouse mouse wheel with Vim. To avoid this +problem, disable Universal scrolling support for Vim. + +For more information, read > + + :help intellimouse-wheel-problems +< + *faq-33.5* +33.5. I am using Windows XP, the display speed of maximized GVim is very + slow. What can I do to speed the display updates? + +This may be due to the fact that you have enabled 'Smooth edges of screen +fonts' in the display properties. Try turning off font smoothing or try +changing the smoothing method to "Standard". + + *faq-33.6* +33.6. What are the recommended settings for using Vim with cygwin? + +You may want to set the following shell related Vim settings: > + + :set shellcmdflag=-c + :set shellquote= + :set shellslash " Use the forward slash for expansion. + :set shellxquote=\" + :set shell=d:\cygwin\bin\bash.exe " Use the bash shell + :set shellpipe=2>&1| tee + :set shellredir=>%s 2>&1 +< + *faq-33.7* +33.7. I am trying to use GNU diff with Vim diff mode. When I run the diff + from command line, it works. When I try to use the diff with Vim it + doesn't work. What should I do now? + +There is a problem with using GNU diff with Vim. You can try using the +GNU diff.exe built by Ron Aaron from the following link: > + + http://www.mossbayeng.com/~ron/vim/builds.html +< + *faq-33.8* +33.8. Is it possible to use Vim as an external editor for MS-Windows + Outlook email client? + +You can use the "cubiclevim" COM Add-In to use Vim as an external editor +for MS-Windows Outlook email client. Visit the following URL for more +information: > + + http://sourceforge.net/projects/cubiclevim +< +Note that currently this works only with MS-Office 2000 and XP. + + *faq-33.9* +33.9. I am using Vim to edit HTML files. How do I start internet explorer + with the current file to preview the HTML file? + +You can use the following command: > + + :!start c:\progra~1\intern~1\iexplore.exe file://%:p +< + *faq-33.10* +33.10. I would like to use Vim with Microsoft Visual Studio. How do I do + this? + +You have to download and use the OLE version of Vim (for example: +gvim61ole.zip). This file also contains instructions on how to use Vim with +Visual Studio. + +For more information, read > + + :help MSVisualStudio +< + *faq-33.11* +33.11. Where do I place the _vimrc and _gvimrc files? + +You can place the _vimrc and _gvimrc files under the directory pointed to +by the VIM environment variable. If you are sharing this system with other +users, then you can place the files in a directory and set the HOME +environment variable to this directory. + +For more information, read > + + :help $HOME-use + :help _vimrc +< + *faq-33.12* +33.12. Everytime I save a file, Vim warns about the file being changed + outside of Vim. Why? + +If you get the following warning message, everytime you save a file: > + + WARNING: The file has been changed since reading it!!! + Do you really want to write to it (y/n)? +< +then this problem could be related to a bug in MS-Windows on the day +daylight saving time starts. Vim remembers the timestamp of the file after +it was written. Just before the next write the timestamp is obtained again +to check if the file was changed outside of Vim. This works correctly, +except on the day daylight saving time starts. + +This problem will go away the next day after the day the daylight saving +time starts. + +For more information, read > + + :help W11 +< + +============================================================================= + *faq-34* +SECTION 34 - PRINTING + + *faq-34.1* +34.1. How do I print a file along with line numbers for all the lines? + +You can set the 'printoptions' option and use the ":hardcopy" command to +print your file: > + + :set printoptions=number:y + :hardcopy +< +For more information, read > + + :help 'printoptions' + :help :hardcopy +< + *faq-34.2* +34.2. How do I print a file with the Vim syntax highlighting colors? + +You can use the ":hardcopy" command to print a file with the Vim syntax +highlighting colors. You can also convert your file to a HTML file using +the 2html.vim script and print the HTML file. + +For more information, read > + + :help syntax-printing + :help 2html.vim + :help :hardcopy + :help printing +< + +============================================================================= + *faq-35* +SECTION 35 - BUILDING VIM FROM SOURCE + + *faq-35.1* +35.1. How do I build Vim from the sources on a Unix system? + +For a Unix system, follow these steps to build Vim from the sources: + +- Download the source and run-time files arrchive (vim-##.tar.bz2) from the + ftp://ftp.vim.org/pub/vim/unix directory. +- Extract the archive using the bzip2 and ttar utilities using the command: > + + $ bunzip2 -c | tar -xf - +< +- Run the 'make' command to configure and bbuild Vim with the default + configuration. +- Run 'make install' command to install Vimm in the default directory. + +To enable/disable various Vim features, before running the 'make' command +you can run the 'configure' command with different flags to include/exclude +the various Vim features. To list all the available options for the +'configure' command, use: > + + $ configure -help +< +For more information, read > + + :help install +< + *faq-35.2* +35.2. How do I install Vim in my home directory or a directory other + than the default installation directory in Unix? + +To install Vim in a directory other than the default installation +directory, you have to specify the directory using the --prefix option +while running the configure script. > + + $ ./configure --prefix=/users/xyz +< +You can enable/disable various Vim feature by supplying different arguments +to the configure script. For more information about all these options, run > + + $ ./configure --help +< +For more information, read > + + :help install-home + :help install +< + *faq-35.3* +35.3. How do I build Vim from the sources on a MS-Windows system? + +For a MS-Windows system, Vim can be built using either the Visual C++ +compiler or the Borland C++ compiler or the Ming GCC compiler or the cygwin +gcc compiler. Follow these steps to build Vim from the sources for +MS-Windows: + +- Download the source (vim##src.zip), runtiime (vim##rt.zip) and the extra + (vim-##-extra.tar.gz) archives from the ftp://ftp.vim.org/pub/vim/pc + directory. +- Extract the archives into a directory (foor example, c:\vimsrc) +- Depending on the installed compiler, you can use the corresponding + makefile to build the Vim sources. For Visual C++ use the Make_mvc.mak + makefile, for borland C++ use the Make_bc5.mak makefile, for ming GCC use + the Make_ming.mak makefile, for cygwin gcc use the Make_cyg.mak makefile. + +Depending on whether you want to build the GUI version of Vim or the +console version of Vim, you have to pass different arguments to the +makefiles. After successfully building the sources, you can copy the +vim.exe or gvim.exe file to the desired directory along with the files from +the runtime archive. + +You can visit the following site for extensive information about building +Vim on a MS-Windows system using the various compilers: > + + http://mywebpage.netscape.com/SharpPeople/vim/howto/index.html +< +For more information, read > + + :help install +< + *faq-35.4* +35.4. The Vim help, syntax, indent files are missing from my Vim + installation. How do I install these files? + +The Vim help, syntax, indent and other runtime files are part of the Vim +runtime package. You need to download and install the Vim runtime package. +For example, for MS-Windows, the name of the Vim 6.1 runtime package is +vim61rt.zip. + +For more information, read > + + :help install +< + *faq-35.5* +35.5. I have built Vim from the source and installed the Vim package using + "make install". Do I need to keep the Vim source directory? + +No. Once you have built and installed Vim in some directory other than the +original source directory (for example, /usr/bin or /usr/local/bin), then +you can remove the source directory. + + *faq-35.6* +35.6. How do I determine the Vim features which are enabled at compile + time? + +You can use the ":version" command to determine the Vim features that are +enabled at compile time. The features that are enabled will be prefixed +with a "+". The features that are not enabled will be prefixed with a "-". + +If you want to test for a feature in a script, you can use the has() +function: > + + if has("menu") + " Set up some menus + endif +< +For more information, read > + + :help :version + :help +feature-list + :help has() +< + *faq-35.7* +35.7. Can I build Vim without the GUI support? + +Yes. You can build Vim by optionally enabling/disabling many of the +features including GUI. + +For more information, read > + + :help install +< + *faq-35.8* +35.8. When building Vim on a Unix system, I am getting "undefined reference + to term_set_winsize' error. How do I resolve this error? + +You will get this error when the build process is not able to locate the +termlib, termcap or ncurses library. You have to install the ncurses-dev +package to resolve this error. + + *faq-35.9* +35.9. Vim configure keeps complaining about the lack of gtk-config while + trying to use GTK 2.03. This is correct, since in GTK 2 they moved to + using the generic pkg-config. I can get pkg-config to list the + various includes and libs for gtk, but for some reason the configure + script still isn't picking this up. + +Use the following shell script named gtk-config: > + + #!/bin/sh + pkg-config gtk+-2.0 $1 $2 +< + +============================================================================= + *faq-36* +SECTION 36 - VARIOUS + + *faq-36.1* +36.1. How do I edit binary files with Vim? + +You can set the following options to edit binary files in Vim: > + + :set binary + :set display=uhex +< +You can also use the "-b" command-line option to edit a binary file: > + + $ vim -b +< +You can also use the xxd utility (part of the Vim distribution) to edit +binary files. + +For more information, read > + + :help 23.4 + :help edit-binary + :help hex-editing + :help -b + :help 'binary' + :help 'endofline' + :help 'display' +< + *faq-36.2* +36.2. How do I disable the visual error flash and the error beep? + +You can disable both the visual error flash and the error beep using the +following command: > + + :set visualbell t_vb= +< +For more information, read > + + :help 'visualbell' + :help 'errorbells' + :help t_vb +< + *faq-36.3* +36.3. How do I display the ascii value of a character displayed in a + buffer? + +You can use the 'ga' command to display the ascii value of a displayed +character. + +For more information, read > + + :help ga + :help :ascii +< + *faq-36.4* +36.4. Can I use zero as a count for a Vim command? + +You cannot use zero as a count for a Vim command, as "0" is a command on +its own, moving to the first column of the line. + +For more information, read > + + :help 0 + :help count +< + *faq-36.5* +36.5. How do I disable the Vim welcome screen? + +You can disable the Vim welcome screen, by adding the 'I' flag to the +'shortmess' option: > + + :set shortmess+=I +< +For more information, read > + + :help :intro + :help 'shortmess' +< + *faq-36.6* +36.6. How do I avoid the "hit enter to continue" prompt? + +Vim will prompt you with the "hit enter to continue" prompt, if there are +some messages on the screen for you to read and the screen is about to be +redrawn. You can add the 'T' flag to the 'shortmess' option to truncate +all messages. This will help in avoiding the hit-enter prompt: > + + :set shortmess+=T +< +You can also increase the command height by setting the 'cmdheight' option: > + + :set cmdheight=2 +< +For more information, read > + + :help hit-enter + :help avoid-hit-enter + :help 'shortmess' + :help 'cmdheight' +< + *faq-36.7* +36.7. How do I invoke Vim from command line to run a group of commands on a + group of files? + +There are several ways to invoke Vim from command line to run a group of +commands on a group of files. You can use a set of "-c" command line +options to specify a group of commands: > + + $ vim -c "" -c "" *.txt +< +Each of the ex-command specified with the "-c" command line option is +executed one by one sequentially. You can also use a single "-c" command +line option and the "|" character to separate the ex commands: > + + $ vim -c " | " *.txt +< +In the above command, if an ex command fails, then all the remaining ex +commands will not be executed. + +For example, to replace "ABC" with "DEF" in a file from the command-line, +you can use the following command: > + + $ vim -c "%s/ABC/DEF/ge | update" myfile.txt +< +To replace "ABC" with "DEF" in multiple files from the command-line, +you can use the following command: > + + $ vim -c "argdo %s/ABC/DEF/ge | update" *.txt +< +You can store the group of commands into a file and use the "-s" command +line option to run the commands on a set of files. For example, if the +group of commands are stored in the file mycmds.txt, then you can use the +following command: > + + $ vim -s mycmds.txt *.pl +< +For more information, read > + + :help -c + :help -s +< + *faq-36.8* +36.8. How do I use a normal mode command from insert mode without leaving + the insert mode? + +You can use a normal command from insert mode, without leaving the insert +mode, by first pressing the CTRL-O key and then follow that with a single +normal mode command. + +To execute more than one normal mode command, press the CTRL-L key, +followed by any number of normal mode commands and then press to get +back to the insert mode. + +For more information, read > + + :help i_CTRL-O + :help i_CTRL-L +< + +============================================================================= + *faq-37* +SECTION 37 - UNICODE +Author: Tony Mechelynck + + *faq-37.1* +37.1. Is it possible to create Unicode files using Vim? + +Yes. It may be more or less complicated depending on the keyboard and fonts +available to you, but it is always possible to encode any possible Unicode +codepoint (and some illegal ones) into a file. To create a Unicode file +using Vim, you should have compiled Vim with the "+multi_byte" compile-time +option. You can get more information about Unicode from the following +sites: > + + http://www.unicode.org + http://www.cl.cam.ac.uk/~mgk25/unicode.html +< +For more information, read > + + :help multibyte + :help usr_45.txt +< + *faq-37.2* +37.2. Which Vim settings are particularly important for editing Unicode + files? + +The most important are the various "encoding" options, i.e., 'encoding', +'fileencoding', 'fileencodings' and 'termencoding'. The boolean option +'bomb' is also significant. + +For more information, read > + + :help 'encoding' + :help 'fileencoding' + :help 'fileencodings' + :help 'termencoding' + :help 'bomb' +< + *faq-37.3* +37.3. What is the 'encoding' option? + +Basically, the 'encoding' option defines how Vim will represent your data +internally. However, all Unicode encodings are represented internally as +utf-8 and converted (if necessary) when reading and writing. + +For more information, read > + + :help 'encoding' +< + *faq-37.4* +37.4. How does Vim name the various Unicode encodings? + +Utf-8 is called utf-8 or utf8; utf-16 is called ucs-2 or ucs2; utf-32 is +called ucs-4 or ucs4. Also, you may specify endianness (except for utf-8 +which does not vary for endianness) by appending le for little-endian or be +for big-endian. If you create a file with an encoding of ucs-2 or ucs-4 +without specifying endianness, Vim will use what is typical of your +machine. + +For more information, read > + + :help encoding-names + :help encoding-values + :help encoding-table +< + *faq-37.5* +37.5. How does Vim specify the presence or absence of a byte-order mark? + +When reading a file, if the 'fileencodings' option includes "ucs-bom", Vim +will check for a byte-order mark. When writing a file, if the 'bomb' option +is set, Vim will write a byte-order mark on files whose encoding warrants +it. + +For more information, read > + + :help 'fileencodings' + :help 'bomb' +< + *faq-37.6* +37.6. What is the 'fileencoding' option? + +The 'fileencoding' option defines the particular encoding which Vim will +use to write a file. If empty, then the value of the 'encoding' option is +the default. + +For more information, read > + + :help 'fileencoding' +< + *faq-37.7* +37.7. What is the 'fileencodings' option? + +The 'fileencodings' option defines the heuristics used by Vim when opening +an existing file. It is a comma separated list of encodings. A special +name, "ucs-bom" is used to indicate that Vim should check for the presence +of a byte-order mark; however, it will not be recognised if it comes after +"utf-8". Normally, "ucs-bom" (if present) should be first in the list. + +When Vim opens a file, it checks it against the encodings listed in +'fileencodings'. The first one that matches is used. If there is no match, +then Vim sets 'fileencoding' to the null string, i.e., the value of +'encoding' will be used. + +For more information, read > + + :help 'fileencodings' + :help 'encoding' +< + *faq-37.8* +37.8. What is the 'termencoding' option? + +The 'termencoding' option defines how your keyboard encodes the data you +type. If empty, Vim assumes that it has the same value as 'encoding'. +Usually it should be set to something that matches your locale. + +For more information, read > + + :help 'termencoding' + :help locale +< + *faq-37.9* +37.9. What is the 'bomb' option? + +When reading a file with "ucs-bom" present in the 'fileencodings' option, +Vim will set the 'bomb' option on or off depending on the presence or +absence of a byte-order mark at the start of the file. When writing, Vim +will write a byte-order mark if the 'bomb' option is set. You may set or +unset it manually do make Vim write, or not write, the b.o.m. + +For more information, read > + + :help 'bomb' +< + *faq-37.10* +37.10. Where can I find an example of a typical use of all these options? + +There is a "tip", with explains them in different words with an example, at +http://vim.sourceforge.net/tip_view.php?tip_id=246 . + + *faq-37.11* +37.11. How can I insert Unicode characters into a file using Vim? + +Several methods are available: + +- Characters present on your keyboard can bbe typed in the usual way, even + those which require a "dead-key" prefix, like (for instance) the + circumflex on French keyboards. +- Characters for which a digraph is definedd can be typed as two characters + prefixed by . +- If you have set the 'digraph' option, youu can enter the characters for + which a digrph is defined as . +- Any character can be entered by using a < prefix (or if + is remapped to paste from the clipboard). + +For more information, read > + + :help digraphs + :help 'digraph' + :help i_CTRL-V_digit +< + *faq-37.12* +37.12. How can I know which digraphs are defined and for which characters? + +First set the 'encoding' option properly (for instance, to utf-8), then use +the :digraphs command to list the currently defined digraphs. + +For more information, read > + + :help :digraphs + :help 'encoding' +< + +============================================================================= + vim:tw=78:ts=8:ft=help:norl: