反省はしても後悔はしない

Vim とか備忘録とか。それと関数型言語勉強中

はじめてプラグインを作ってみた。それとhelpの書き方など

Vim

この記事は Vim Advent Calendar 2012 の 124 日目の記事です。
昨日は @supermomonga さんの vimprocでRubyでプロセス通信・ソケット通信しよう でした。

はじめに

Vim にはもともと colorcolumn という機能があります。
たとえば

setlocal colorcolumn=4

という設定を打ち込むと、下のようになります。

4桁目がハイライトで表示されるようになります。桁位置を綺麗に揃えたいときにたまに役に立ちます。

この colorcolumn を現在のカーソル位置から即座に設定出来れば便利そうだと思い、今回はじめてプラグインを作ってみることにしました。

Vim の colorcolumn の機能を簡単に使うためのプラグインを作ってみた

easy-colorcolumn

インストールは例によって NeoBundle で行います。

NeoBundle 'cohama/easy-colorcolumn'

このプラグインはデフォルトではキーマッピングを提供しないので、.vimrc にこういう設定を書いておきます。(一例です)

nmap <Space>c <Plug>(easy-colorcolumn-toggle)
xmap <Space>c <Plug>(easy-colorcolumn-toggle)
nmap <Space>C <Plug>(easy-colorcolumn-clear)

この設定により、おもむろに <Space>c を押せばカーソル位置の桁が colorcolumn によりハイライトされます。
さらに、ビジュアルモードと合わせて使うと、複数の列を一気に設定できたりもします。わーい(棒

消すときは <Space>C です。現在のバージョンだとプラグイン以外で設定したもの(モードラインや.vimrcに set colorcolumn=.. と書いたもの)も問答無用で消します。余力があれば将来のバージョンで直すかも知れません。

ドキュメント(help)書くときのはなし

プラグインの書き方は @osyo-manga さんの Vim プラグインを github で公開するまで がとても参考になりました。
しかし、この記事ではドキュメントの書き方については言及されていません。
なので、自分なりにまとめます。

まずは doc フォルダを作ってその中に {プラグイン名}.txt というファイルを作ります。

中身を編集していきます。ファイルの1行目に*で囲ったプラグイン名と簡単な説明を書きます。*で囲むとその単語がタグとして認識されるので、:help コマンドで検索できるようになります。その隣の説明は引数なしで:helpしたときに表示されるようになるので書いておくと良いと思います。あと、最後の行にモードラインを書いておきます。ちなみにこの説明は vim のヘルプにあります(:help help-writing)。

 *easy-colorcolumn.txt*  easy to use a |colorcolumn| feature

 vim:tw=78:ts=8:ft=help:norl:noet:fen:fdl=0:

書いたら :e して filetype を help にします。色がつきます。
tw (textwidth) を78に設定するのがデフォルトっぽいです。書くときは1行の文字数が78を超えないようにしましょう。基本的には Vim が自動でフォーマットしてくれますが、追記したりすると超えることがあります。その時は gq コマンドを使いましょう。

それと、@thinca さんの Vim プラグインのヘルプを書く人がするべき設定 にある設定をしとくと良いと思います。
あとは help の中身を書いていきます。まずは最初にAuthor (作者) と License を書いて自己主張しておきましょう。
その後は

  • Contents (目次)
  • Introduction (概要)
  • Install (インストール方法)
  • Mapping
  • Usage (使い方)
  • などなど

を書いていきます。
これらは適宜セクション区切り(====)で区切ります。また、セクションのはじめにヘルプタグを付けておくようにします。既存のタグと被らないように {プラグイン名}-introduction などとします。

==============================================================================
INTRODUCTION                                   *easy-colorcolumn-introduction*

なんとかかんとかの概要です。

最後にContents(目次)のところにセクションのはじめに書いたタグを集めます。

Contents *easy-colorcolumn-contents*

Introduction    |easy-colorcolumn-introduction|
Mappings        |easy-colorcolumn-mappings|
....


完成！

正直プラグインのヘルプ書くときは他の人の書いたものを真似すればすぐ書けます。

まとめ

  • プラグインを作るのは思ったより簡単
  • ドキュメント書くまでがプラグイン
  • でもドキュメント書くのも簡単

今回のことでプラグイン書くのも面白いなと思ったので、今後も思いついたらいろいろ作って行きたいと思います。
cohama の今後の活躍にご期待ください。


次回は @deris0126 さんです。