helphelp.txt (Vim Reference Manual)

ヘルプの使ひ方

*helphelp.txt*	For Vim バージョン 8.1.  Last change: 2019 Oct 18


		  VIMリファレンスマニュアル    by Bram Moolenaar

ヘルプのヘルプ

\|online-help\|	ヘルプコマンド
\|help-translated\|	飜譯ヘルプ
\|help-writing\|	ヘルプファイルの書き方

ヘルプコマンド

<Help> または

:h[elp]

新しいウィンドウを作成し、ヘルプファイルを讀み込み專用で開きます。ヘルプウィンドウがすでに開いてゐるときはそのウィンドウを使ひます。カレントウィンドウの幅がスクリーンと同じか、80 文字分以上のときにはヘルプウィンドウはカレントウィンドウのすぐ上に作成されます。さうでないときには、ヘルプウィンドウは最上部に作成されます。

複數言語のヘルプが利用可能なときは、言語を選擇するために、オプション ’helplang’ が參照されます。

:h[elp] {subject}

":help" と同じですが、加へて、{subject} へタグジャンプします。例へば:

:help options

{subject} には "*", "?"、"[a-z]" といつたワイルドカードも指定できます。

:help z?	"z" コマンドのいづれかのヘルプを開く
:help z.	"z." のヘルプを開く

ですが、タグが存在するときは、文字通りにとられます。

:help :?

":?" のヘルプを開く

パターンに完全に一致する項目が無かつた場合、または、複數の項目が一致した場合には、"最善" の一致が選擇されます。洗煉されたアルゴリズムで最善な項目が決定されます。次のやうな優先順位が使はれます:

大小文字が一致したはうが、しない時よりも良い
非英數字のあとにマッチするはうが、單語の眞ん中にマッチするものよりも良い。
タグ名の先頭でマッチするか、なるべく先頭に近いほうが、さうでないものよりも良い。
より多くの英數字がマッチするはうが良い。
短いマッチが良い。

{subject} のヘルプが複數の言語にある場合には、言語を選擇するために、オプション ’helplang’ が參照されます。言語を指定してタグを檢索するには {subject} に "@ab" を付加します。"ab" は 2 文字の言語コードです。|help-translated| を參照。

長い {subject} を與へても、より短いものにマッチすることもあります。この動作はコマンドラインの補完を考へるとわかりやすいでせう (":help subject" の後で CTRL-D をタイプしてみてください |c_CTRL-D|)。

複數の候補がある場合には、CTRL-D を押すことで一覽を見ることができます。例:

:help cont<Ctrl-D>

例へば CTRL-V のヘルプを引くときに ":help CTRL-V" とタイプする代はりに次のやうにすることもできます:

:help ^V

これは他の文字付きでも機能します。例へば插入モードの CTRL-V の動作を調べるには次のやうにします:

:help i^V

まず ":help" を實行し、その後、ヘルプウィンドウで ":tag {pattern}" を實行することもできます。":tnext" コマンドでその他の項目へ移動することができ、":tselect" でマッチした候補の一覽から選擇することができます。

:help index
:tselect /.*mode

引數が指定されてゐない場合は "help" にマッチするものが表示されます (すべての候補にマッチしてしまふのを防ぐため。そのやうな處理は時閒がかかります)。

マッチした候補は最大で 300 件まで表示されます。

‘:help‘ コマンドの後ろには ’|’ で他のコマンドを續けることができます。しかし、’|’ のヘルプを引くのに ’|’ をエスケープする必要はありません。したがつて、次の例はどちらも正しく機能します:

:help |
:help k| only

Note:
’|’ の直前の空白があると ":help" コマンドの引數の一部として解釋されてしまひます。

ヘルプコマンドと續くコマンドを區切るには <LF> と <CR> も使へます。<LF> や <CR> を入力するには、CTRL-V を使ひます。例:
:help so<C-V><CR>only

:h[elp]! [subject]

":help" と同じですが、非英語のヘルプファイルを開いてゐるときには、それと同じ言語を優先します。|help-translated|も參照。

:helpc[lose]

ヘルプウィンドウがあれば、1 つ閉ぢます。

Vim は、ウィンドウレイアウト (カーソル位置を含む) を、最初にヘルプウィンドウを開く前と同じレイアウトに復元しようとします。これにより、いくつかの自動コマンドがトリガーされる場合があります。

:helpg[rep] {pattern}[@xx]

すべてのヘルプファイルから {pattern} を檢索して、マッチした行の一覽を作成します。そして最初にマッチした行へジャンプします。[@xx] を指定した場合は、言語 "xx" のヘルプのみマッチします。

{pattern} には Vim の正規表現 |pattern| を使用できます。’ignorecase’ は影響しません。大文字と小文字を區別しないためには "\c" を使つてください。

大文字と小文字を區別して檢索する例:

:helpgrep Uganda

區別しない例:

:helpgrep uganda\c

フランス語のヘルプを檢索:

:helpgrep backspace@fr

改行を含むパターンはサポートされてゐません。1 行內でマッチするやうにしてください。代はりに |:grep| を使用することもできますが、その場合は、どうにかして檢索結果からヘルプファイルの一覽を取得する必要があります。

他のコマンドを後ろに續けることはできません。すべての文字はパターンの一部として解釋されます。必要なら |:execute| を使つてコマンドを竝べることができます。壓縮されたヘルプファイルは檢索されません (Fedora はヘルプファイルを壓縮します)。

:lh[elpgrep] {pattern}[@xx]

":helpgrep" と同じですが、quickfix リストではなく、ロケーションリストを使ひます。ヘルプウィンドウがすでに開いてゐる場合は、そのウィンドウのロケーションリストを使ひます。開いてゐない場合は、新しいヘルプウィンドウを作成し、そのウィンドウのロケーションリストをセットします。その時にカレントウィンドウのロケーションリストは變更されません。

:exu[sage]

Ex コマンドのヘルプを表示します。Nvi との互換性のため追加されました。

:viu[sage]

ノーマルモードコマンドのヘルプを表示します。Nvi との互換性のため追加されました。

|:help| に引數を指定しなかつた場合には ’helpfile’ に設定されたファイルが開かれます。引數を與へた場合には ’runtimepath’ に設定されたすべてのディレクトリの "doc/tags" から檢索されます。

ヘルプウィンドウの高さの初期値は ’helpheight’ で設定できます (標準設定: 20)。

ある項目へジャンプするにはタグを使ひます。これには2つの方法があります:

オプションやコマンド名にカーソルをあはせて "CTRL-]" コマンド使ふ。これはタグがキーワードの時にだけ使用できます。"<C-Leftmouse>" と "g<LeftMouse>" は "CTRL-]" と同じ動作をします。
":ta {subject}" コマンドを使ふ。これはどのやうな文字でも使用できます。

ジャンプ先から戾るには CTRL-T か CTRL-O を使ひます。

ヘルプウィンドウを閉ぢるには ":q" を使ひます。

探してゐるものが複數の項目にマッチする場合には、次のやうにして各項目にジャンプできます:

ヘルプウィンドウを開く
調べるタグにスラッシュを付けて ":tag" コマンドを實行する。例:
```
:tag /min
```
":tnext" を實行してマッチした次の項目へジャンプする。

プラグインなどのために、ヘルプを追加できます。そのために、配布されてゐるヘルプファイルに變更を加へる必要はありません。|add-local-help| を參照。

ローカルヘルプファイルを書くには |write-local-help| を參照。

Note:
ローカルヘルプファイルのタイトル行 (1 行目) は自動的にヘルプファイル "help.txt" のセクション "LOCAL ADDITIONS" に追加されます |local-additions|。これは Vim でファイルを開いたときに追加されるので、ヘルプファイル自體は變更されません。すべてのヘルプファイルの 1 行目が "LOCAL ADDITIONS" に追加されますが、$VIMRUNTIME/docにあるファイルは對象外です。

他の xterm ウィンドウでヘルプを表示するには、このコマンドを使つてください:

:!xterm -e vim +help &

:helpf[ind]

|:help| と同じですが、引數を入力するためのダイアログを使ひます。後方互換性のために殘されてゐます。現在は組み込みのダイアログを使用せず、メニューの ToolBar.FindHelp を使ひます。{|+GUI_GTK| が有效な場合のみ利用できます}

:helpt[ags] [++t] {dir}

ディレクトリ {dir} のヘルプタグファイルを作成します。{dir} が ALL なら ’runtimepath’ 內の全ての "doc" ディレクトリが對象となります。

指定されたディレクトリとそのサブディレクトリの "*.txt" と "*.??x" といふファイルがスキャンされ、スター (*) で圍まれたタグ定義が檢索されます。"*.??x" といふファイルは飜譯ヘルプです。"tags-??" といふタグファイルが生成されます。|help-translated| を參照。作成されたタグファイルはソートされます。

タグの重複があるときはエラーメッセージが表示されます。すでにあるタグファイルは警告なしに上書きされます。

"++t" 引數を指定すると "help-tags" タグが强制的に追加されます。これは、{dir} が $VIMRUNTIME/doc と等しいときにも同樣にタグが追加されます。

ランタイムディレクトリのヘルプタグファイルを作成し直すには次のやうにします (ファイルの書き込み權限が必要):

:helptags $VIMRUNTIME/doc

飜譯ヘルプ

飜譯ヘルプを追加し、英語のヘルプファイルと共存させることができます。’runtimepath’ の "doc" ディレクトリにあるすべてのヘルプが檢索對象になります。|+multi_lang| が有效な場合のみ利用できます。

今のところ、以下の飜譯が利用可能です:

Chinese	共同飜譯
French	飜譯者 David Blanchet
Italian	飜譯者 Antonio Colombo
Japanese	共同飜譯
Polish	飜譯者 Mikolaj Machowski
Russian	飜譯者 Vassily Ragosin

詳しくは Vim のウェブサイトを參照してください:

http://www.vim.org/translations.php

飜譯ヘルプファイルの名前は次のやうになつてます:

help.abx
howto.abx
...
tags-ab

"ab" は 2 文字の言語コードです。例へばイタリア語なら次のやうな名前になります:

help.itx
howto.itx
...
tags-it

{譯注: 日本語の言語コードは ja です。help.jax}

オプション ’helplang’ に言語の優先順位を指定できます。初期設定は環境から自動的に設定されます。ヘルプを檢索するときはまづ、優先の高い言語からタグが檢索されます。見つからなかつた場合は、英語のヘルプが使はれます。

言語を指定してタグを檢索するには "@ab" をタグ名に付け加へます。"ab" は 2 文字の言語コードです。例:

:he user-manual@it
:he user-manual@en

最初の例は、’helplang’ が未設定の場合でも、イタリア語のユーザーマニュアルを檢索します。2 番目の例は、’helplang’ が "it" に設定されてゐる場合でも、英語のユーザーマニュアルを檢索します。

":help" コマンドでコマンドライン補完をするとき、複數の言語でタグが見つかつた場合には "@en" が付加されます。タグが英語だけにある場合には、"@en" は省略されます。1 番目の候補が "@ab" 擴張子を持ち、’helplang’ の 1 番目の言語とも一致するなら、"@ab" も同樣に省略されます。

飜譯ヘルプで |CTRL-]| や ":help!" を使ふと、同じ言語のタグが檢索されます。見つからなかつた場合は、言語を選擇するために ’helplang’ が參照されます。

ヘルプファイルのエンコーディングは latin1 か utf-8 にしてください。非 ASCII 文字が 1 行目にある場合、そのヘルプファイルは utf-8 であると判斷されます。ヘッダーの "For Vim version" を飜譯しておくとよいでせう。

1 つのディレクトリの 1 つの言語のヘルプファイルはすべて同じエンコーディングを使つてください。別の言語なら別のエンコーディングを使用できます。ディレクトリを分けた場合は、同じ言語で別のエンコーディングを使用できます。

飜譯のヒント:

タグは飜譯しない。さうすれば ’helplang’ を使つて言語の優先順位を指定できます。言語用の新しいタグを追加するのは構ひません。
ファイルの一部を飜譯しない場合は、英語のままタグを追加し、"tag@en" 表記を使へるやうしてください。
ヘルプファイルとタグファイルをまとめてダウンロードできるやうにしてください。さうすれば、ユーザーはそれを "doc" ディレクトリにコピーするだけで使へます。www.vim.org からリンクしたいので、Bram に聯絡してください。
タグファイルを作成するには |:helptags| を使ひます。指定したディレクトリのすべての言語のファイルが處理されます。

ヘルプファイルの書き方

プラグインのヘルプファイルは Vim の標準のヘルプファイルと同じ書式で書かれてゐると便利です。あなたが新しいヘルプファイルを書くときは、既存のファイルをコピーしてそれをテンプレートとして使用するといいでせう。

ヘルプファイルの 1 行目は次のやうに書きます:

*helpfile_name.txt*    For Vim version 7.3    Last change: 2010 June 4

最初のフィールドはヘルプファイル名へのリンクです。2 つめのフィールドは對應してゐる Vim のバージョンを說明してゐます。最後のフィールドはファイルの最終更新日です。それぞれのフィールドはタブ文字で區切られます。

ファイルの末尾には Vim のモードラインを書いて ’textwidth’ オプションと ’tabstop’ オプションを設定し、’filetype’ を "help" に設定します。モードラインでグローバルオプションを設定しないでください。そのヘルプを讀んだ人に望ましくない結果をもたらします。

ヘルプタグを定義するには、名前をアスタリスクで挾みます (*tag-name*)。tag-name は他のすべての Vim ヘルプのタグ名とは違ふ名前になつてゐて、プラグインの名前で始まつてゐるのが理想的です。タグ名は普通は右寄せで書きます。

既存のヘルプタグに言及してそのタグへのリンクを作成するには、名前をバー (|) で挾みます。例: |help-writing|

Vim コマンドに言及してそのコマンドへのリンクを作成するには、コマンド名をバッククォートで圍みます。例: ‘:filetype‘ の中。これはコードブロックのやうにコマンドとしてハイライトされて見えるでせう (下を參照)。

Vim オプションについて言及するときは、オプション名をシングルクォートで圍みます。例: ’statusline’

ハイライト表示

列見出しを定義するにはチルダ文字を行末に付けます。チルダを付けると列見出しが別の色で表示されます。例:

列見出し

ヘルプファイルを節 (section) で區切るときは、’=’ 文字を 1 列目から連續して書きます。節區切り行は別の色でハイライトされます。

Ex コマンドのブロックを例示するときは、大なり記號 (>) をその直前のブロックの行末に書き、小なり記號 (<) をその後ろのブロックの前の最初の非空白文字として書きます。テキストが 1 列目から始まつてゐる行があると、Ex コマンドのブロックはその直前で暗默的に終了となります。例:

function Example_Func()
echo "Example"
endfunction

Vim ヘルプファイルでは以下のものがそれぞれハイライトされます:

特殊キーの名前。<PageDown> のやうな <> 表記で書かれたものと、CTRL-X のやうに書かれた制禦文字。
{braces} で圍まれた文字。例: {lhs} と {rhs}

"Note" や "Notes" などの單語もそれぞれハイライトされます。次のやうな表示もあります:

*Todo	something to do
*Error	something wrong

詳細は $VIMRUNTIME/syntax/help.vim を見てください。