【Windows11+gvim】vim-ref × Pandoc で、VimのウィンドウにPHPマニュアルを表示する

はじめに

PHPで開発しているときに、ちょっとマニュアルを見たいという時がよくあります。
ブラウザで見に行けばいいのですが、vim-refプラグインを使うとVimのウィンドウにマニュアルの内容を表示できて便利です。

Windows11の gvim¹での導入方法をまとめてみました。
vim-refは、Lynxなどのテキストブラウザを使う前提で実装されていますが、Windowsの環境では簡単にテキストブラウザが導入できそうになかった²ので、Pandocというドキュメント変換ツールを代わりに使用してマニュアルを表示させました。³

GitHub - thinca/vim-ref: Integrated reference viewer. · GitHub
https://github.com/thinca/vim-ref

Pandoc - Installing pandoc
https://pandoc.org/installing.html

1.vim-ref プラグインのインストール

まずは、vim-refプラグインを有効にします。
vim-jetpackでインストールしました。

.vimrc の vim-jetpackのプラグインを読み込んでいる箇所に、以下を追加して、:so%で再読み込みの上、:JetpackSync でインストールしました。

Jetpack 'thinca/vim-ref'

2. PHPマニュアルをローカルディレクトリへ配置

vim-refで、PHPマニュアルを表示するためには、マニュアルのhtmlファイルが必要になります。php.net の PHP: Download documentation の japanese の行の「tar.gz」をダウンロードします。ダウンロード先をコピーして curlで持ってきました。

curl -fLo php_manual_ja.tar.gz https://www.php.net/distributions/manual/php_manual_ja.tar.gz

次にダウンロードした tar.gzファイルを解凍・展開します。
最近の Windowsでは、tarコマンドが使えるので、コマンド上で実行しました。

tar -xzvf php_manual_ja.tar.gz

解凍・展開すると php-chunked-xhtml という名前のディレクトリができるので、Vim のインストールしたディレクトリ下に、vim-refディレクトリを作成し配置しました。
最後に .vimrc にPHPのマニュアルを置いたディレクトリを指定します

let g:ref_phpmanual_path = $VIM.'\vim-ref\php-chunked-xhtml'

Vimのインストールディレクトリ（ $VIM ）
├──vim-ref
│ ├── php-chunked-xhtml/
├──.vimrc
...

3 Pandoc のインストール

htmlのPHPマニュアルを参照してウィンドウへ表示できるように、Pandocをインストールします。
Pandoc は色々なドキュメントの形式を変換することができます。vim-refでは、htmlをプレーンテキストに変換する機能を使用します。

インストールする方法は色々とあるようですが、今回はインストーラーを使います。
以下の手順でインストールをしました。

1. 公式サイトの「Download the latest installer」をクリック
2. GitHubのページにリンクするので、下部の Assets の「 pandoc-3.12.1-windows-x86_64.msi 」を選択
3. ダウンロードした msiファイルをダブルクリックしてインストール開始、ポップアップが出てくるので、「I accept the terms in the License Agreement」にチェックをいれて「Install」をクリック
4. インストール完了後に、コマンドプロンプトを開いてバージョンを確認

>pandoc --version
pandoc 3.12.1
Features: +server +lua
Scripting engine: Lua 5.4
User data directory: ***********************************
Copyright (C) 2006-2025 John MacFarlane. Web:  https://pandoc.org
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.

4. htmlを表示するコマンドをPandocに変更する

Pandocが使えるようになったので、vim-refで、PHPマニュアルを表示するためのコマンドをPandoc のものに変更します。

.vimrcに以下を追記しました。
%s にvim-refで参照するPHPマニュアルのパスが入ります。pandocで、そのファイルをhtmlからプレーンテキストに変換するという意味になります。

let g:ref_phpmanual_cmd = 'pandoc -f html -t plain %s'

5. 文字化けの対処

ここまでで設定が完了したので、Vimを開きなおしてから、PHPのマニュアルを引いてみます。PHPファイルをVimで開いて、標準の関数名などにカーソルを合わせてKをタイプすると、そのキーワードに対応したPHPマニュアルのページが別ウィンドウで表示されます。
Kを押してみたところ、ウィンドウの表示は問題なくされましたが、日本語については文字化けしてしまいました。

原因を調べてみるとtermencoding を 「cp932」に設定されていたことにより、PHPマニュアルをウィンドウへ表示するときに、文字コード変換が発生していたようです。
以下の設定を行うことで解消しました。

set termencoding=

termencoding は、ターミナルに文字を送ったり受け取ったりするときに適切に文字コードを変換してくれる設定のようですが、Windowsではこの設定は無視されるということです。⁴

Vimの機能で文字コード変換が起きたのではなく、vim-refプラグインのプログラムの中で、ターミナルとVimの内部エンコードの差異を吸収する配慮があり、その判断に、termencoding を使っていました。termencoding を空に設定しておけば、このエンコードの変換は発生しません。

PHPファイルを開いて、改めてKを押すと文字化けせずにウィンドウが表示されました。

1. vim-jpさんの「Windowsへのインストール方法」( https://vim-jp.org/docs/install_windows.html ) の右上にある「バイナリダウンロード」の「Windows 64ビット」のからダウンロードした gvim(バージョン9.2)を使用。 ↩

2. Lynxはバイナリファイルが見つかるのですが、32ビット用のものでちゃんと動くか良く分かりませんでした、また、WSLを導入すればテキストブラウザを導入できそうでしたが、テキストブラウザのためだけに導入するのはどうかな...今のところ、他で使わないし...ということで、テキストブラウザをWindowsに導入するという方向性はやめました。テキストブラウザの代わりになる Pandocが、他の用途でも使えそうというのも理由の1つです。 ↩

3. 具体的には、Pandocでhtmlをプレーンテキストに変換して表示するというものになります。これはテキストブラウザでhtmlを解釈して表示するよりも表現力は落ち、みづらいかもしれませんが、充分に実用に足るレベルのものと考えています。 ↩

4. :h 'termencoding'に『Win32 GUIとコンソールでは 'termencoding' は使用されない。Win32では常に Unicode文字が渡されるからである。』とある。試しにgvim上で:echo has('win32')を実行すると 1 が返ってきて、実行環境が、Win32 であることが分かります。 ↩