はじめに
開発用のマニュアル・リファレンス類を参照するのに便利な Dash というツールがあります。
Mac専用ですが、Windows / Linux 向けに Zeal や Velocity といったクローンも存在しており大変便利です。
Windows経験者であれば「CHMヘルプファイルを複数統合して拡張したようなもの」と言えばわかりやすいでしょうか。個人的にもCHMヘルプファイルは大変重宝していたので、代替として Dash / Zeal は手放せないツールです。
日本語のリファレンスが欲しい
熟読するマニュアル・リファレンスの類いは、内容を正確に把握するためにも母国語のものが欲しくなります。日本人ならお茶漬けやろ、というやつです（違
Dash は海外のツールですので日本語版の Docset（言語単位のリファレンスに相当）が公式サイトで公開されていません。先人の努力により日本語版を入手できる言語もいくつか存在しますが、PHPは現行の7.x系に対応しておらずリファレンスから最新の機能をキャッチアップできません。
無ければ作ろう！
という訳で、最新のPHP 7.x系に対応した日本語版の Docset を作る方法を考えました。
- オリジナルの英語版をベースにする（検索DBとファイル構成を継承する）
- 最新のマニュアルはPHP公式から入手したものをなるべく加工せずに差し替えたい
- 表示スタイルはなるべくPHP公式に寄せたい（見栄え、閲覧のしやすさ）
- 自分でビルドできる（ドキュメントのアップデートに追随しやすくする）
もっとも重視したのは「自分でビルドできる」ことです。
公式ドキュメントとDocsetの仕様が変わらない限り、メンテナーがいなくなっても各自が最新のマニュアルを使い続けられる環境が理想です。
システム要件とビルドツール
拙作の dash-phpdoc-ja を使用します。
Windows / MacOS でのビルドを想定しており、各環境の必須要件は次の通りです。
- MacOS
- PHP 5.4以上
- Git
- chmlib（CHMファイルの解凍に必要、Homebrewで導入可）
- Windows
- PHP 5.4以上
- Git for Windows
- hh.exe
- 基本的なUnixコマンドが動作する環境（MSYS / Cygwin / BoW など）
MacOS Sierra（Git / chmlibをHomebrewで導入）および Windows 10（MSYS環境）でビルド確認済みです。
ビルド手順
dash-phpdoc-ja を適当な場所に git clone してください。
基本的には、そのまま php generate-php.php するだけで必要なファイルのダウンロードとビルドが開始されます。
注意点として、多量のファイルを解凍・コピー・削除する関係からアンチウイルスソフトが動いていると「device busy」や「ファイルを削除できません」といったエラーの発生することがあります。この場合はアンチウイルスソフトの常駐をOFFにしてからビルドするとうまくいくはずです。
ビルド用のオプションを調整する必要がある場合は下記を参考にしてください。
-
Windowsでのビルド
Windows上でビルドする場合は
// Windows //$cfg_chm = 'hh -decompile %2$s %1$s'; // Mac, Linux $cfg_chm = 'extract_chmLib %1$s %2$s';の箇所を修正してください。
コメントアウトされている hh.exe の記述を有効にしてMac用の記述をコメントアウトすればOKです。
-
Open Sans フォントの扱い
Chromium の表示異常を招く場合がある（Windows での Zeal 使用時など）ため Open Sans フォントをデフォルトで無効にしています。有効にするには、
$cfg_nosans = true;を false に変更してください。
-
言語選択
デフォルトで ja に設定されており日本語の Docset を作成しますが、原理的には PHP の公式ドキュメントが対応している言語であれば指定可能です（ru / fr / de 等）。変更する場合は下記の箇所を編集してください。
$cfg_lang = 'ja'; $cfg_ver = '7.1';バージョン指定はメタデータ用です。
ビューワによっては、Docset のタイトル表示に用いられる場合があります。