はじめに
Vim プラグインを使う際、ヘルプを見ることがあると思いますが、フォーマットが整っていますよね。
その中で、自分でヘルプを書くときにはどのようにフォーマットに則ればいいのかがわからなかったので、調べてみました。
フォーマットサンプル
:help write-local-helpに、フォーマットサンプルが載っています。typecorr という
以下、引用します。こちらを参考に説明します。
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.
ヘルプの書き方
:help help-writingに説明がありましたので、かいつまんで紹介します。
1行目にヘルプファイル名を記載する
1行目の行頭に、 *typecorr.txt*というヘルプファイル名へのリンクを記載します。
これで、:help typecorr.txtというふうに検索したら、準備したヘルプにジャンプしてくれます。
行末に Vim モードラインを書く
ファイルの見た目を制御するVim モードラインを定義することで、ヘルプファイルの体裁を整えます。
vim-go のドキュメントファイルには以下のように記載されていました。
vim: ft=help tw=78 et ts=2 sw=2 sts=2 norl
ft=help:filetypeをhelpにtw=78:textwidth、テキスト最大幅を 78 にet:expandtab、タブを指定数の空白文字にts=2:tabstop、2文字分の空白文字をタブとして認識させるsw=2:shiftwidth、インデント時に使用される空白文字の数を2文字にsts=2:softtabstop、タブを押下したときに使用する空白の数norl:norightleft: 画面表示の方向を左から右に
適切にヘルプタグを付ける
アスタリスク *を指定することで、ヘルプタグをつけることができます。プラグイン名から始めるのが理想的とのこと。<plugin-name>-hogehogeみたいな感じですね。
また既存のヘルプタグにリンクするときは|で囲みます。
適切にシンタックスハイライトを使う
よりヘルプを読みやすくするために、シンタックスハイライトを適用します。いくつか紹介します。
- コマンドブロック：
>をブロック直前に、<をブロック直後に - 列見出し：
~を行末に - セクション区切り：
=をテキスト最大幅まで使う
おわりに
今回調べたことでヘルプの書き方の概要はざっくりつかめました。あとは他の Vim プラグインのヘルプファイルを参考に書いていこうと思います。