PHP

PHPマニュアルの「導入」を「はじめに」に変えていただいた

変更前 (2017-09-02) 現在
「導入」リンクがある 「はじめに」リンクがある

変更を提案した理由

PHPのモジュールを追加する際、公式サイトのマニュアルを参照してサーバへの導入方法を確認することがよくある。

このとき、誤って「導入」リンクをたどってしまい、モジュールの説明しか確認できずに、がっかりすることもよくあった。

学ばないぼくも悪いのだが、そもそも「導入」なのが混乱の元なのではないだろうか。ためしにTwitterで検索してみると、同様の意見が見つかった。

ツイートにあるとおり、「導入」は「Introduction」の訳語であり、誤訳というわけではない。ただ、「サーバへの導入」という表現が日本語にはあるので、ほかの訳語をあてるのが適切だと考えた。


提案の流れ

とはいえ、ぼくの独断でマニュアルの表現を変えるわけにはいかない。「マニュアルについて」→「ドキュメントの改善を手助けするには」→「PHP Manual Contribution Guide」→「Joining the team」と読み進め、そこで推奨されているように、まずはメーリングリストで相談することにした。投稿したのが下記のメールだ。

2日ほど待ったが、とくにレスポンスはなかった。このときどう考えるかは人によるだろうが、ぼくは「反対者がいないのでチャンスだ」と受け止めた。パッチを作れば取り込んでもらえるかもしれない。


パッチ作成の準備

パッチを作るには、ソースファイルの変更箇所を理解する必要がある。また、変更後のマニュアルを実際に眺めてみて、違和感がないかどうかも確認すべきだ。

まずやるべきことは、ビルドツールであるPhDの入手だ。参考にしたのは、mumumuさんの「PHP manual generate HOWTO (version 2013-06-29)」だった。

試行錯誤の結果、ぼくの環境では下記のコマンドでPhDがインストールできた。

$ sudo yum install php-xml
$ sudo pear install doc.php.net/PhD doc.php.net/PhD_PHP doc.php.net/PhD_PEAR doc.php.net/PhD_IDE-1.1.1

続いて、ソースファイルを取得する。

$ svn co http://svn.php.net/repository/phpdoc/modules/doc-ja

変更箇所を理解するため、ソースをgrepする。

$ grep -rn '>導入' ./

「導入」を「はじめに」に変更後、ビルドしてみる。

$ php doc-base/configure.php --with-lang=ja --enable-xml-details
$ phd -d doc-base/.manual.xml -f xhtml -P PHP

ビルドされたマニュアルを確認し、違和感のないことが確認できた。


パッチの作成

ここまでくれば、オンラインのドキュメントエディタでパッチが作れる。ローカルで試したのと同じ要領でファイルを編集し、パッチを作った。

その後、メーリングリストにパッチのレビュー依頼メールを投稿した。


公式マニュアルへの適用

ほどなく、前述のmumumuさんから、svnにコミットした旨のリプライがあった。(ありがとうございます!)

そして本日、公式サイトのマニュアルに変更点が適用された。ちなみにこのマニュアルは毎日13時ごろ(日本時間)に更新されているようだ。


以上のような次第で、混乱せずにPHPマニュアルが読めるようになった。

余談だが、今回の件を通じて、未翻訳のファイルが3000以上あることを知った。今後はそちらの翻訳にも挑戦してみたい。

PHP4.4.9のパッチを頼まれて書いた話

3月上旬、あるドイツ人から「PHP4.4.9のパッチを書いてくれないか」という相談メールが届いた。「2週間以内にPHPのあるバグをふさがなければならないのだが、Cの知識がないので、バグ報告者であるiwamotにパッチを書いてほしい」というのだ。

「私だってCの知識はないし、PHPのコーディングを工夫すればバグをふさぐ必要もない」などと返したのだが、どうしても書いてくれというので、「うまく書けるかどうか保証はできないし、そもそも期日に間に合うかどうかわからない」と断ったうえで、トライすることにした。どこの馬の骨だかわからない私に頼るぐらいだから、そうとう切羽詰まっているのだろう。

パッチはなんとか書けたので、先方に送り、テストしてもらった。「意図どおりに動いているので、これを使うことに決めた」との返事が来た。

先方はずいぶん喜んでくれたようで、「報酬としてiPadを送ろうか、iPad 2がいいか、それともGalaxy Tab 10.1Nにするか」などと提案してくれた。だが、私は「今度ドイツに行ったときにランチをおごってくれるだけでいいよ」と冗談めかして返した。正直にいえば、住所を教えるのが怖かったのだ。

「そのかわり、パッチを公開していいか?」と聞いたら、「6週間待ってくれ、そして自分の素性は明かさないでくれ」との返事だった。それで今日書いたのがこの記事である。

プロフィール
Web開発者。現在の関心事はシステム品質の改善(特に性能効率性と保守性)。JAPAN MENSA会員。
カテゴリ別アーカイブ
記事検索