README.mdをVimのヘルプファイルから生成する
この記事はVim Advent Calendar 2012の341日目の記事です。
前回（84日前）Vimプラグインのスクリプトファイルからヘルプファイルを生成するというのをやりました。
しかしGitHubではREADME.mdファイルがリポジトリの窓口であり、説明であり、これによってそのプラグインの概要を知り、それを導入するかどうかが判断されます。
README.mdを置いていないとプラグインの詳細を知るためには、リポジトリトップから2クリックもかかるdoc/xxx.txtを見に行かなければいけませんし、リポジトリトップにはGitHubがREADME.mdを置けと勧めてきます。
つまり我々はREADME.mdを書くことを暗に強いられているのです。
しかし、すでにhelpに概要含め色々書いているのにさらに別の場所で二重に概要を書かなければいけないなんて苦痛です。
なぜhelpに書いたことを改めて書かなければいけないのでしょうか。
そこでLeafCage/vimhelpgeneratorに:HelpIntoMarkdownというコマンドを追加しました。*1
ヘルプファイル内でREADME.mdに含めたいところをビジュアル行選択（“概要”や“使い方”などを選択すると良いでしょう）して、
:HelpIntoMarkdownを実行すると、
そのヘルプファイルの上にあるREADME.mdファイルが開かれます。*2
ここでPすると、先ほど行選択されたテキストがmarkdown形式に変換されてputされます。（README.mdを初めて作成するときにはプラグイン名と説明もhelpファイルの第1行目から生成されます。）
手直しした後、:writeしましょう。
:HelpIntoMarkdownはアンダースコア(_)のエスケープには対応していません*3。自力で対応させて下さい。
もしもヘルプファイルを改修したときには改修した箇所をビジュアル行選択して:HelpIntoMarkdownして下さい。その部分の変換結果がレジスタにセットされるのでREADME.mdにて貼り付けて手直しして下さい。
これでヘルプファイルとREADME.mdを管理する手間を大幅に減らすことが出来ました。
:VimHelpGeneratorVirtualでヘルプを仮想バッファに出力する
vimhelpgeneratorには、:VimHelpGeneratorVirtualというコマンドも加わっています。
:VimHelpGeneratorが生成したバッファをそのまま書き込むのに対し、:VimHelpGeneratorVirtualは仮想バッファに出力します。
これにより、vimhelpgeneratorの、ヘルプファイルを初めて作るときにしか使えなかったという欠点を解消しました。
プラグインに機能を追加するなどしてヘルプの改修の必要性が生じたとき、:VimHelpGeneratorVirtualを実行して、出力された仮想バッファ内で必要な部分だけを、既存のヘルプファイルにコピーペースト（Vim風に言うとヤンクプット）すれば良いのです。
単純にVimHelpGeneratorの出力を確認したいときにも利用できます。
:VimHelpGeneratorを実行したときにすでにヘルプファイルが存在している場合もこのモードで出力されます。
