ここでは、PHPを使うと必ず一度は目にするであろう PHPマニュアル について記していきます。 PHPマニュアルのメンテナンスの前提となる基本知識や、修正方法などについて記していきます。
mumumu です。PHPマニュアル のメンテナの一人です。
PHPマニュアル はPHP 7 系から現在 (このエントリが更新されている時の最新は 8.1.1) に至るまでの歴史が蓄積されており、非常に巨大なマニュアルです。これは DocBook を使って書かれており、それを適宜各ロケールの翻訳者がボランティアで英語以外の各国語に置き換えていっています。それが php.net のインフラでビルドされ、1日に1回 (正確には毎日午後3時 JST) 世界中に公開されていくという具合です。
Docbook は、SGML 由来であることによって文書構造が複雑であることや、タグの構造が壊れてしまうと即ビルドが失敗してしまうなどの欠点によって、他のフォーマットに置き換えようという話がこれまで出なかったわけではありません。ですが、DocBook の多彩な表現力にとってかわることと、現在までの巨大な蓄積を効率的に置き換えられる代替案を誰かが示せない限り、移行していくことはないでしょう。
PHPマニュアルは 長らく Subversion で管理されてきましたが、4年以上に渡る議論や作業の末、2020年末に git へ移行しました。その成果として、github 経由 でもバグ報告が可能になっています。
既に述べたとおり、PHP マニュアル はボランティアベースで作られているため、常に完全な翻訳を維持できているわけではありません。現在でもたくさんの未訳部分が残っていますし、人間がやるモノである以上、常に間違いが存在し得ます。
間違いを見つけた場合には、どこに問い合わせればよいでしょう？ 複数の選択肢がありますが、私のおすすめの順に以下に選択肢を示します。
修正内容はコードで語りたい、という方は、github がお勧めです。2020年12月末から、PHPマニュアル は git で管理されるようになり、github 経由でもバグ報告を行うことが可能になりました。
報告のやり方は、 github の CONTRIBUTING.md を参照して下さい。
リポジトリそのものは、下記にあります。
https://github.com/php/doc-ja
日本語でPHPの雑談をするための Slackチーム が存在します。そこに #phpmanual というチャンネルがあり、PHPマニュアル のメンテナも join しており、直接話すことが可能になっています。
メンテナが時々つぶやいたりもしていますし、間違いの指摘や、これを翻訳して欲しい！などの要望も日本語で可能です。
参加方法は Slackの更新招待リンク から join するか、日本語で PHP の話をする Slack のグループを作ったよ を参照して下さい。
日本 PHP ユーザー会 では php-doc ML というメーリングリストをホストしており、ここを通じて PHPマニュアルに関する問い合わせや間違いの指摘などを受け付けています。ここで頂く多くの情報が、PHP マニュアル 日本語版の質の向上に大きく寄与していることは言うまでもありませんし、初期の頃からの多くの方々の協力によって現在のマニュアルは存在し、かつ維持されています。
但し、現在は過疎っているのであまりお勧めできません...
PHPマニュアル は XHTML や Windows の標準的なヘルプ形式である chm に対応したフォーマットが公開されていますが、Docbook からこれらの形式をビルドするための PhD というツールが整備されています。
PhD を使えばHTML形式のビルドは行えるようになっていますが、chm 形式については、それをビルドするのに Windows マシンの助けが必要です。PHP マニュアル のビルド方法については、以下に纏めておいたので参考にしてください。
PHPマニュアルをいろいろ見ていくと、継続して改善すべきだというモチベーションが強まってくるかもしれません。Slack や PHP-doc ML で指摘しまくっていてそれにも飽き足らないという人は、コミット権限を得て自分で直すことも考えてもよいかもしれません。以下は、そういうモチベーションが高い人向けです。
PHPマニュアルのコミット権限を得るには、php.net のページで英語で申請をする 必要があります。これを php.net の中の人が見てコミット権限を与えるかを決めているわけですが、彼らは何回か patch を提出した実績か、もしくは既存のコミッタの推薦があることを求めて来ます。patch については日本語版の PHP マニュアル の patch でも問題ないはずです。
基本的には PHPユーザーズ Slack や php-doc ML に話を通してから申請し、既存の PHP マニュアル 日本語版のコミッタからの推薦を得た方が早く話が進むと思います (自分も php-doc ML 経由で 高木さん の推薦を貰いました) 。
尚、申請ページでは、最初から最後までちゃんと文章を読んでから申請フォームを埋めないと 必ず失敗するようになっています ので気を付けてください。
PHPマニュアルのコミット権限を得たら、DocBook を直接編集し、リポジトリにコミットすることが出来ます。
具体的な方法は、以下を参照して下さい。