archived-doc-ja/appendices/about.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: e8ac70bf549a723cb36465667a6109d9933b8619 Maintainer: hirokawa Status: ready -->
<!-- CREDITS: takagi,mumumu -->

 <appendix xml:id="about" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>マニュアルについて</title>
  
  <sect1 xml:id="about.formats">
   <title>フォーマット</title>
   <para>
    PHP のマニュアルはいくつかのフォーマットで提供されています。
    大まかに言うとフォーマットには2つの種類があります。オンラインで
    読むことのできるフォーマットとダウンロード可能なパッケージです。
   </para>
   <note>
    <para>
    いくつかの出版社は印刷されたマニュアルを提供しています。私たち
    としてはそれらをお勧めすることは出来ません。何故ならそういった
    ものはすぐに古いものになってしまいがちだからです。
    </para>
   </note>
   <para>
    オンラインマニュアルは <link xlink:href="&url.php;">PHP.net Web サイト
    </link>
    で読むことができます。
    オンライン版の PHP
    マニュアルには、現在二種類の <acronym>CSS</acronym>
    スタイルシートが提供されています。それぞれ、
    ウェブでの閲覧に適したものと、プリンタでの印刷に適したものです。
   </para>
   <para>
    オンラインマニュアルがオフライン版より優れている点は、
    <link linkend="about.notes">ユーザーノート</link>と
    見たいマニュアルのページを速やかに入手できる
    <link xlink:href="&url.php.urlhowto;">URL ショートカット</link>が
    統合されていることでしょう。不利な点は、当然ですがマニュアルを見るためには
    常にオンラインでいる必要があることです。
   </para>
   <para>
    オフラインフォーマットにはいくつかのタイプがあるので、使用している
    OS や読み方にあわせて最適なものを選択してください。これらの異なった
    フォーマットのドキュメントをどのように生成しているかという
    情報については、この付録の<link linkend="about.generate">
    各種フォーマットを生成する方法</link>の項を読んでください。
   </para>
   <para>
    最もプラットフォーム依存性が少いマニュアルのフォーマットは HTML
    版です。このマニュアルは、一つのファイルにまとめられたものと、
    章ごとに分割されたファイルのパッケージ
    (その結果、総数は数千にもなっています)の両方があります。
    これらの HTML 版は圧縮された状態で提供されているため、
    アーカイブの中のファイルを取得するには解凍用ユーティリティ
    が必要です。
   </para>
  <!--
   PDF バージョンの PHP マニュアルは「現在は」存在しません。
   いつの日か出来上がるでしょう。
   <para>
    PDF(またの名をAdobe Acrobat)もまたクロスプラットフォームな
    フォーマットで、印刷するのに最適です。しかし、勢い込んで
    このフォーマットをダウンロードして印刷ボタンを押す前に、
    このマニュアルは2000ページ以上の長さを持ち、常に更新されて
    いる、ということについてよく考えてみてください。
   </para>
   <note>
    <para>
     PDFファイルを閲覧するプログラムには、<link
     xlink:href="&url.adobe.acrobat;">Adobe Acrobat Reader</link>
     など多くのものがあります。
    </para>
   </note>
  -->
   <para>
    Windows 上では、<productname>Windows HTML Help</productname> で
    <productname>Windows HTML Help</productname>
    版のマニュアルを使用すると非常に便利です。このバージョンは全文検索、完全な目次、
    そしてブックマーク機能を提供します。多くの有名な Windows 上での
    PHP 開発環境ではこのバージョンのマニュアルを統合する機能を備えていて、
    間単にアクセスすることが出来ます。Linux デスクトップ用の CHM ビューワも
    利用可能です。
    <link xlink:href="&url.xchm;">xCHM</link> または
    <link xlink:href="&url.gnochm;">GnoCHM</link> を参照ください。
   </para>

   <para>
    <link xlink:href="&url.php.echm;">拡張 CHM 版</link>も使用可能です。
    その更新頻度はより少なくなっていますが、より多くの追加機能があります。
    これは、ヘルプページを構築する際に使用される技術のために
    <productname>Microsoft Windows</productname> でのみ動作します。
   </para>
  </sect1>
  
  <sect1 xml:id="about.notes">
   <title>ユーザーノートについて</title>
   <para>
    ユーザーノートは PHP マニュアルを作成していく上で重要な役割を
    持っています。マニュアルの読者が実例、警告そしてさらに詳しい
    説明をブラウザから提供できるようにすることで、そうした
    フィードバックをマニュアルの本文に取り込むことが出来るのです。
    そして記事が本文に取り入れられるまでの間は、その内容をオンライン、
    もしくはいくつかのオフラインフォーマットで参照できるでしょう。
   </para>
   <para>
    ユーザーノートが PHP のサイトに表示される際に、何らかの
    査閲がされているわけではない、ということに注意してください。
    従って、そこに書かれた内容、実例の質については保証
    されません(とはいえ、マニュアルの本文そのものの
    質が保証されない、ということではありません)。
   </para>
   <note>
    <para>
     著作権の適用範囲として、ユーザーノートは PHP マニュアルの一部と見なされます。
     それゆえ、このドキュメンテーションのライセンス(現状は Creative Commons Attribution
     License)が適用されます。
     詳細は <link linkend="copyright">Manual's Copyright</link> をご覧ください。
    </para>
   </note>
  </sect1>
  
  <sect1 xml:id="about.prototypes">
    <title>関数の定義(プロトタイプ)を読むには</title>
    <para>
     各関数についてクイックリファレンスが記述されているので、
     マニュアルを読み理解するノウハウは PHP の利用をより簡単にしてくれます。
     例示やカットアンドペーストに頼るより、関数の定義（プロトタイプ）を
     読む方法を覚えるべきです。やってみましょう:
    </para>
    <note>
     <title>
      前提条件: <link linkend="language.types">型</link>の基本的な理解
     </title>
     <para>
      PHP は型についてルーズな言語ですが、重要な意味があるので、
      <link linkend="language.types">型</link>の基本を理解することは重要です。
     </para>
    </note>
    <para>
     関数の定義には<link linkend="functions.returning-values">戻り値</link>が
     どんな型であるかが示されています。最初の例として、
     <function>strlen</function>の定義を考えてみましょう。
    </para>
    <para>
    <screen role="html">
<![CDATA[
strlen ( string $string ) : int
 
(PHP 4, PHP 5, PHP 7)
 strlen -- 文字列の長さを得る
 
 説明
int strlen ( string $string )
 
指定した文字列の長さを返します
]]>
     </screen>
    </para>
    <para>
     <table>
      <title>関数の定義の説明</title>
       <tgroup cols="2">
        <thead>
         <row>
          <entry>Part</entry>
          <entry>説明</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry>
           strlen
          </entry>
          <entry>
           関数の名前
          </entry>
         </row>
       <row>
        <entry>
          (PHP 4, PHP 5, PHP 7)
        </entry>
        <entry>
         strlen()は PHP 4 と PHP 5、そして PHP 7 のすべてのバージョンで使用できる
        </entry>
       </row>
       <row>
        <entry>
          ( string $string )
        </entry>
        <entry>
         strlen() 関数の最初の（この場合は唯一の）引数が
         <parameter>string</parameter>という名前であり
         それは文字列(<type>string</type>)である
        </entry>
       </row>
       <row>
        <entry>
         int
        </entry>
        <entry>
         関数が戻す値の型。ここでは整数型
         (文字列の長さが数字で数えられている)
        </entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </para>
   <para>
    上の関数定義は、一般的な書き方では以下のようにも書けます。
   </para>
   <para>
    <screen>
<![CDATA[
     function name    ( parameter type   parameter name ) : returned type
]]>
    </screen>
   </para>
   <para>
    多くの関数は複数の引数を取ります。例えば <function>in_array</function>。
    このプロトタイプは次のようになります:
   </para>
   <para>
    <screen>    
<![CDATA[
      in_array ( mixed $needle, array $haystack , bool $strict = false ) : bool
]]>
    </screen>
   </para>
   <para>
    これは何を意味しているのでしょう？ in_array() は
    <link linkend="language.types.boolean">boolean</link> の値を返します。
    成功した場合は &true;(<parameter>needle</parameter> が
      <parameter>haystack</parameter> の中にある場合)、&return.falseforfailure;
      (<parameter>needle</parameter> が <parameter>haystack</parameter>
      の中にない場合)。最初の引数は <parameter>needle</parameter>
      と名づけられており、それは多くの違った<link linkend="language.types">
      型</link>をとることができます。その場合"<emphasis>mixed</emphasis>"と
      呼ばれます。
      <parameter>needle</parameter> (我々が探しているもの)はスカラー値（文字列,整数,
      又は <link linkend="language.types.float">float</link>)でも、
      <link linkend="language.types.array">配列</link>でもかまいません。
      <parameter>haystack</parameter> (対象を探す配列)は二番目の引数です。
      三番目の<emphasis>オプション</emphasis>の引数は <parameter>strict</parameter>
      と名づけられています。全てのオプション引数はデフォルト値を持ちます。
      デフォルト値が不明な場合、<literal>?</literal> と表示されます。
      <parameter>strict</parameter> パラメータはデフォルトでは boolean の
      &false; であるとマニュアルに述べられています。機能の詳細については
      各関数のマニュアルをご覧ください。
   </para>
    <para> 
     さらに、&amp; (アンパサンド) 記号を関数のパラメータの前につけると、
     そのパラメータを<link linkend="language.references.pass">リファレンス渡し</link>にすることができます。
    </para>
    <para>
     <screen> 
<![CDATA[
       preg_match ( string $pattern , string $subject , array &$matches = null,
       int $flags = 0 , int $offset = 0 ) : int|false
]]>
     </screen>
    </para>
    <para>
     この例では、三番目のオプションのパラメータ <parameter>&amp;$matches</parameter>
     がリファレンス渡しとなります。
    </para>
   <para>
    より複雑なバージョンとの関係を有する関数もあります。以下が
    <function>html_entity_decode</function> の例です。
   </para>
   <para>
    <screen>    
     (PHP 4 >= 4.3.0, PHP 5, PHP 7)
    </screen>
   </para>
   <para>
    これは、この関数が
    PHP 4.3.0 以降のバージョンでのみ利用可能であることを意味します。
   </para>
  </sect1>
  
 <sect1 xml:id="about.phpversions">
  <title>本マニュアルに記載された PHP のバージョン</title>
  <para>
   このマニュアルに含まれている情報は、過去や現在のバージョンの PHP
   だけでなく将来のバージョンの PHP に関するものもあります。
   バージョン間での変更内容は「注意」や「更新履歴」
   あるいはマニュアルの本文の中で説明しています。
   このドキュメントでは、PHP 7.0.0 以降のバージョンを扱っています。
  </para>
  <para>
   最新の (まだリリースされていない) 開発版に関するドキュメントには
   "Git 版のみ" や "開発版" といった記述があります。
   これらの変更は予定通りに進むのが普通ですが、まれに予定が変更されることもあります。
  </para>
  <para>
   開発はすべて Git で進められており、
   <link xlink:href="&url.php.anongit;">匿名での Git
   へのアクセス</link> のページに書かれている方法でチェックアウトすることができます。
  </para>
  <para>
   マニュアルでは、PHP のバージョンをメジャー、マイナー、ポイントの三つで表します。
   たとえば PHP <literal>7.3.1</literal> を例にとると、<emphasis>7</emphasis>
   がメジャーリリースで <emphasis>3</emphasis> がマイナーリリース、
   そして <emphasis>1</emphasis> がポイントリリースとなります。
   通常 PHP では、新機能の追加はメジャーリリースやマイナーリリースでしか行いません。
   しかし、この決まりが常に守られるとは限りません。
  </para>
  <para>
   また、PHP のマニュアルは現在形で書かれていることに注意しましょう。
   たとえその機能がまだ搭載されていなくても、未来形にはなりません。
   マニュアルは長く使い続けられるものです。
   PHP のリリースのたびに時制の変更を繰り返すのは退屈な作業なので、そのようにしました。
  </para>
  <para>
   PHP のマニュアルでは、多くの項目で「デフォルト値」を記載しています。
   これらの値は、設定ファイル &php.ini; がないときの PHP の挙動にもとづいています。
   そのため、同梱の設定ファイル
   <filename>php.ini-development</filename> や <filename>php.ini-production</filename>
   に書かれている内容とは異なる可能性があります。
   これらの値は最新版の PHP にもとづくものですが、
   過去の値についても更新履歴に記載しています。
   これらの値や変更履歴についての詳細は
   <link linkend="ini.list">PHP ディレクティブのリスト</link>
   を参照ください。
  </para>
 </sect1>

  <sect1 xml:id="about.more">
   <title>PHP に関する更なる情報を得るには</title>
   <para>
    このマニュアルは一般的なプログラミングの解説を提供しよう
    としているわけではありません。従って、もしあなたが全く初めて
    プログラミングを行う、もしくはほとんど初心者である、と言う場合は
    このマニュアルだけを使って、PHP のプログラミングを習得するのは
    難しいでしょう。そうした場合には初心者向けの本を探したほうが
    よいかもしれません。
   </para>
   <para>
    PHP に関する様々な側面について活発に議論しているメーリングリストも
    多数あります。もし問題にぶつかったら、これらのメーリングリストの
    利用を考えてください。メーリングリストを含むサポート情報は
    <link xlink:href="&url.php.support;">PHP.net サポートページ</link>
    にあります。
   </para>
  </sect1>
  
  <sect1 xml:id="about.howtohelp">
   <title>ドキュメントの改善を手助けするには</title>
   <para>
    ドキュメントを改善していくには 複数のやり方があります。
   </para>
   <para>
    もし(どの言語でかかれたものでも)マニュアルに間違いが見つかったら
    <link xlink:href="&url.php.git;">&url.php.git;</link> にある、各言語の issue tracker を使って問題を報告して下さい。
    たとえば、日本語版のマニュアルについては、
    <link xlink:href="&url.php.git;doc-ja/issues">&url.php.git;doc-ja/issues</link> になります。
    マニュアルのフォーマットを含め、
    ドキュメントに関する問題はすべてここから送信してください。
   </para>
   <note>
    <para>
     issue tracker に助けを要求することでシステムを無駄に使用しないでください。
     かわりに、たくさんの<link xlink:href="&url.php.support;">サポートオプション</link>
     の中のひとつを利用してください。
    </para>
   </note>
   <para>
    各ページに注釈をつけることで、原文に実例、警告等の更なる説明を
    追加することが出来ます。とはいえ、この注釈システムを使って
    バグレポートを送信しないでください。ユーザーノートの詳細については、
    <link linkend="about.notes">ユーザーノートについて</link>の
    項を読んでください。
   </para>
   <para>
    <link xlink:href="&url.php.git.mirror;doc-ja">PHP マニュアルのリポジトリのミラー</link> 経由で Pull Request を送信することもできます。
   </para>
   <para>
    PHP マニュアルは多くの言語に翻訳されています。英語とその他の外国語が
    わかる方なら、翻訳チームを手伝うことで PHP マニュアルの改善に協力できます。
    新しく翻訳を始めたい場合や、現在翻訳されているバージョンを手伝おうと
    思ったら、<link xlink:href="&url.php.dochowto;">&url.php.dochowto;</link>
    を是非読んでください。
   </para>
   <para>
    PHP ドキュメント作成プロジェクトの IRC チャネルには、マニュアルの
    作者の多くが参加しています。<literal>irc.efnet.org</literal>
    の <literal>#php.doc</literal> で、PHP ドキュメントを改善する方法に
    ついて議論しましょう。
   </para>
  </sect1>
  
  <sect1 xml:id="about.generate">
   <title>各種フォーマットを生成する方法</title>
   <para>
   このマニュアルは、<link
   xlink:href="&url.docbook.xml;">DocBook XML DTD</link>
   を用いて <acronym>XML</acronym> で記述されています。
   また、<link
   xlink:href="&url.phd;"><acronym>PhD</acronym></link> (The [PH]P based 
   [D]ocBook renderer) を用いて保守やフォーマットを行います。
   </para>
   <para>
    <acronym>XML</acronym> をソースファイルのフォーマットとして
    使用することで、一つのソースファイルを管理するだけで、
    多くの出力形式を生成することができるようになっています。
    オンライン版のマニュアルを作成する際には <link
    xlink:href="&url.phd;">PhD</link> を使用しています。
    <productname>Windows HTML Help</productname> 形式のマニュアルを作成するためには
    <link xlink:href="&url.winhelp;">Microsoft HTML Help Workshop</link>
    を使用しています。またちょっとした変換処理やフォーマットの
    処理にはもちろん PHP を使っています。
   </para>
   <para>
    PHP マニュアルは多くの言語とフォーマットで作成されています。詳しい
    情報は <link xlink:href="&url.php.docs;">&url.php.docs;</link> を参照ください。
    このドキュメントの <acronym>XML</acronym> ソースコードは、
    <link xlink:href="&url.php.git.mirror;doc-ja">&url.php.git.mirror;doc-ja</link> からダウンロードしたり、閲覧したりできます。
   </para>
  </sect1>
  
  <sect1 xml:id="about.translations">
   <title>翻訳</title>
   <para>
    PHP マニュアルはさまざまな形式で読めるだけでなく、さまざまな言語で
    読むことができます。マニュアルの文章はまず最初に英語で書かれ、
    その後世界中のチームによってそれぞれの母国語に翻訳されます。
    もし特定の関数や章がまだ翻訳されていない場合、マニュアル生成システム
    はその英語版を自動的に挿入します。
   </para>
   <para>
    翻訳に携わる人は <link xlink:href="&url.php.git.mirror;doc-en">&url.php.git.mirror;doc-en</link> から
    アクセスできる <acronym>XML</acronym> ソースコードを母国語に
    翻訳することから始めます。生成されたバージョン（<acronym>HTML</acronym>
    やプレーンテキストなど）を扱うことは<emphasis>ありません</emphasis>。
    <acronym>XML</acronym>を人間が読める形式に変換する処理をしてくれるのが
    ビルドシステムです。
   </para>
   <note>
    <para>
     もしドキュメントをあなたの母国語に翻訳することを手伝いたいと思ったら、
     phpdocメーリングリストに加入してドキュメント／翻訳チームと連絡を取ってください。
     <link xlink:href="mailto:&email.php.doc.subscribe;">&email.php.doc.subscribe;</link>
     に空のメールを送るだけです。
     メーリングリストのアドレスは <literal>&email.php.doc;</literal> です。
     マニュアルの翻訳に関心があることをメッセージに書いてください。
     誰かから返事をもらって新しい言語への翻訳をスタートする手助けをしてもらうか、
     あるいは、その言語について既に活動している翻訳チームと連絡が取れます。
    </para>    
   </note>
   <para>
    現在のところ、10 以上の言語において全て又は一部のマニュアルが利用できます。
   </para>
   <para>
    これらはすべて、<link xlink:href="&url.php.docs;">&url.php.docs;</link>
    からダウンロードできます。
   </para>
  </sect1>

 </appendix>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->