読者です 読者をやめる 読者になる 読者になる

README.mdをVimのヘルプファイルから生成する

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に含めたいところをビジュアル行選択(“概要”や“使い方”などを選択すると良いでしょう)して、

f:id:leafcage:20131106074914p:plain

:HelpIntoMarkdownを実行すると、

f:id:leafcage:20131106074933p:plain

そのヘルプファイルの上にあるREADME.mdファイルが開かれます。*2

f:id:leafcage:20131106074944p:plain

ここでPすると、先ほど行選択されたテキストがmarkdown形式に変換されてputされます。(README.mdを初めて作成するときにはプラグイン名と説明もhelpファイルの第1行目から生成されます。)
手直しした後、:writeしましょう。
:HelpIntoMarkdownはアンダースコア(_)のエスケープには対応していません*3。自力で対応させて下さい。

f:id:leafcage:20131106075002p:plain

もしもヘルプファイルを改修したときには改修した箇所をビジュアル行選択して:HelpIntoMarkdownして下さい。その部分の変換結果がレジスタにセットされるのでREADME.mdにて貼り付けて手直しして下さい。

これでヘルプファイルとREADME.mdを管理する手間を大幅に減らすことが出来ました。

:VimHelpGeneratorVirtualでヘルプを仮想バッファに出力する

vimhelpgeneratorには、:VimHelpGeneratorVirtualというコマンドも加わっています。
:VimHelpGeneratorが生成したバッファをそのまま書き込むのに対し、:VimHelpGeneratorVirtualは仮想バッファに出力します。

これにより、vimhelpgeneratorの、ヘルプファイルを初めて作るときにしか使えなかったという欠点を解消しました。
プラグインに機能を追加するなどしてヘルプの改修の必要性が生じたとき、:VimHelpGeneratorVirtualを実行して、出力された仮想バッファ内で必要な部分だけを、既存のヘルプファイルにコピーペースト(Vim風に言うとヤンクプット)すれば良いのです。
単純にVimHelpGeneratorの出力を確認したいときにも利用できます。

:VimHelpGeneratorを実行したときにすでにヘルプファイルが存在している場合もこのモードで出力されます。

*1:これに伴い、:VimHelpGenerator実行時に吐き出していた、クソの役にも立たないREADME.mdを生成させる機能はオミットされました。

*2:ファイルが存在しなくてもOK

*3:技術的に難しかったので