<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.41 $ -->

<appendix id="about">
 <title>About the manual</title>

 <sect1 id="about.formats">
  <title>Formats</title>
  <para>
   The PHP manual is provided in several formats. These formats can be divided
   into two groups: online readable formats, and downloadable packages.
  </para>
  <note>
   <para>
    Some publishers have made available printed versions of this manual. We
    cannot recommend any of those, as they tend to become out-of-date very
    quickly.
   </para>
  </note>
  <para>
   You can read the manual online at the <ulink url="&url.php;">PHP.net website</ulink>
   and on the numerous mirror sites. For best performance, you should choose
   the mirror site closest to you. You can view the manual in either its plain
   (print-friendly) HTML format or an HTML format that integrates the manual
   into the look and feel of the PHP website itself.
  </para>
  <para>
   Two notable advantages of the online manual over most of the offline formats is the
   integration of <link linkend="about.notes">user-contributed
   notes</link> and the <ulink url="&url.php.urlhowto;">URL shortcuts</ulink> which you
   can use to get to the desired manual parts quickly. An obvious disadvantage is
   that you have to be online to view this edition of the manual.
  </para>
  <para>
   There are several offline formats of the manual, and the most appropriate
   format for you depends on what operating system you use and your personal
   reading style. For information on how the manual is generated in so many
   formats, read the <link linkend="about.generate">'How we generate the
   formats'</link> section of this appendix.
  </para>
  <para>
   The most cross-platform format of the manual is the HTML version. This
   is provided both as a single HTML file and as a package of individual files
   for each section (which results in a collection of several thousand files).
   We provide these versions compressed, you will need some sort of decompression
   utility to get the files contained in the archives.
  </para>
  <para>
   Another popular cross-platform format, and the format most suited to
   printing, is PDF (also known as Adobe Acrobat). But before you rush to
   download this format and hit the Print button, be warned that the manual is
   more than 2000 pages long, and constantly being revised.
  </para>
  <note>
   <para>
    If you do not already have a program capable of viewing PDF format
    files, you may need to download <ulink url="&url.adobe.acrobat;">Adobe
    Acrobat Reader</ulink>.
   </para>
  </note>
  <para>
   For Windows platforms, the <productname>Windows HTML Help</productname> 
   version of the manual soups up the HTML format for use with the 
   <productname>Windows HTML Help</productname> application. This
   version provides full-text search, a full index, and bookmarking. Many
   popular Windows PHP development environments also integrate with this
   version of the documentation to provide easy access. CHM viewers for
   Linux desktops are also available. Check out
   <ulink url="&url.xchm;">xCHM</ulink> or
   <ulink url="&url.gnochm;">GnoCHM</ulink>.
  </para>
  
  <para>
   There is also an <ulink url="&url.php.echm;">extended CHM version</ulink>
   available, which is updated less frequently, but provides much more
   features. It will only work on <productname>Microsoft Windows</productname>
   though, because of the technologies used to build up the help pages.
  </para>
 </sect1>
 
 <sect1 id="about.notes">
  <title>About user notes</title>
  <para>
   The user-contributed notes play an important role in the development of
   this manual. By allowing readers of the manual to contribute examples,
   caveats, and further clarifications from their browser, we are able to
   incorporate that feedback into the main text of the manual. And until the
   notes have been incorporated, they can be viewed in their submitted form
   online and in some of the offline formats.
  </para>
  <note>
   <para>
    The user-contributed notes are not moderated before they appear online, so
    the quality of the writing or code examples, and even the veracity of the
    contribution, cannot be guaranteed. (Not that there is any guarantee of
    the quality or accuracy of the manual text itself.)
   </para>
  </note>
  <note>
   <para>
    For the purposes of license coverage the user-contributed notes are
    considered part of the PHP manual, and are therefore covered by the
    same license that covers this documentation (Open Publication License
    at the moment). For
    more details see the <link linkend="copyright">Manual's Copyright</link>
    page.
   </para>
  </note>
 </sect1>

 <sect1 id="about.prototypes">
   <title>How to read a function definition (prototype)</title>
   <para>
    Each function in the manual is documented for quick reference. Knowing how 
    to read and understand the text will make learning PHP 
    much easier.  Rather than relying on examples or cut/paste, you will want 
    to know how to read function definitions (prototypes).  Let's begin:
   </para>
   <note>
    <title>
     Prerequisite: Basic understanding of <link linkend="language.types">types</link>
    </title>
    <para>
     Although PHP is a loosely typed language, it's important to have 
     a basic understanding of <link linkend="language.types">types</link> as 
     they have important meaning.
    </para>
   </note>
   <para>
    Function definitions tell us what 
    type of value is <link linkend="functions.returning-values">returned</link>.
    Let's use the definition for <function>strlen</function> as our first example:
   </para>
   <para>
    <screen role="html">
<![CDATA[
strlen

(PHP 3, PHP 4, PHP 5)
strlen -- Get string length

Description
int strlen ( string str )

Returns the length of string.
]]>
    </screen>
   </para>
   <para>
    <table>
     <title>Explanation of a function definition</title>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>Part</entry>
         <entry>Description</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>
          strlen
         </entry>
         <entry>
          The function name.
         </entry>
        </row>
        <row>
         <entry>
          (PHP 3, PHP 4, PHP 5)
         </entry>
         <entry>
          strlen() has been around in all versions of PHP 3, PHP 4 and PHP 5
         </entry>
        </row>
        <row>
         <entry>
          int
         </entry>
         <entry>
          Type of value this function returns, which is an 
          <type>integer</type> (i.e. the length of a string is measured in
          numbers). 
         </entry>
        </row>
        <row>
         <entry>
          ( string str )
         </entry>
         <entry>
          The first (and in this case the only) parameter/argument for this 
          function is named <parameter>str</parameter>, and it's a 
          <type>string</type>.
         </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
    <para>
     We could rewrite the above function definition in a generic way:
    </para>
    <para>
     <screen>
<![CDATA[
      returned type    function name    ( parameter type   parameter name )
]]>
     </screen>
    </para>
    <para>
     Many functions take on multiple parameters, such as <function>in_array</function>.
     Its prototype is as follows:
    </para>
    <para>
     <screen>    
<![CDATA[
      bool in_array ( mixed needle, array haystack [, bool strict])
]]>
     </screen>
    </para>
    <para>
     What does this mean?  in_array() returns a 
     <link linkend="language.types.boolean">boolean</link> value, &true; on 
     success (if the <parameter>needle</parameter> was found in the 
     <parameter>haystack</parameter>) or &false; on failure (if the 
     <parameter>needle</parameter> was not found in the 
     <parameter>haystack</parameter>).  The first parameter is named 
     <parameter>needle</parameter> and it can be of many different 
     <link linkend="language.types">types</link>, so we call it 
     "<emphasis>mixed</emphasis>".  This mixed <parameter>needle</parameter> 
     (what we're looking for) can be either a scalar value (string, integer, 
     or <link linkend="language.types.float">float</link>), or an
     <link linkend="language.types.array">array</link>.
     <parameter>haystack</parameter> (the array we're searching in) is the 
     second parameter.  The third <emphasis>optional</emphasis> parameter is 
     named <parameter>strict</parameter>.  All optional parameters are seen 
     in <emphasis>[</emphasis> brackets <emphasis>]</emphasis>.  The manual 
     states that the <parameter>strict</parameter> parameter defaults to 
     boolean &false;.  See the manual page on each function for details on 
     how they work.
    </para>
    <para>
     There are also functions with more complex PHP version information. Take
     <function>html_entity_decode</function> as an example:
    </para>
    <para>
     <screen>    
<![CDATA[
(PHP 4 >= 4.3.0, PHP 5)
]]>
     </screen>
    </para>
    <para>
     This means that this function was not available in PHP 3, and is only
     available in a released version since PHP 4.3.0. 
    </para>
 </sect1>
 
 <sect1 id="about.phpversions">
  <title>PHP versions documented in this manual</title>
  <para>
   This documentation contains information about both PHP 4 and PHP 5, with
   some added migration and compatibility notes regarding PHP 3. Behaviour,
   parameter, return value and other changes between different PHP
   versions are documented in notes and inline text in the manual.
  </para>
  <para>
   You may find documentation pieces for the CVS version of PHP, which
   always means the very latest development version available through
   the CVS version handling system. If you are not a developer of PHP
   itself, and you are not keen on using the very latest development
   version of PHP, features marked with the "available in CVS" wording
   are not accessible to you. These features, though, will probably be
   available in the next stable version of PHP. If you would like to
   download the CVS version, see the <ulink url="&url.php.anoncvs;">anonymous
   CVS access page</ulink>.
  </para>
  <para>
   You may also encounter documentation for a PHP version which is
   not released (something like PHP 5.0.0 while the latest stable version
   is 4.3.x). Most of the time, this is not an error in the documentation.
   Explanation is often added for features not available in the current
   PHP release, but which will be available in a known future PHP version.
   Typically, PHP only adds new features in major releases otherwise only bugs
   are fixed. Using the A.B.C versioning format, a major release increments A 
   or B whereas minor releases increment C. So for example it's not uncommon 
   for a feature to be documented as available in PHP x.1.x when the latest 
   release is PHP x.0.x. Also note that the manual is written in present 
   tense, not future tense.
  </para>
  <para>
   Many times the PHP manual lists "Default Values" for PHP directives. These 
   values are based on <filename>php.ini-dist</filename> and not 
   <filename>php.ini-recommended</filename>. They also refer to the latest  
   version of PHP. See the <link linkend="ini.list">PHP directive 
   appendix</link> for details on these values and changes.
  </para>
 </sect1>
   
 <sect1 id="about.more">
  <title>How to find more information about PHP</title>
  <para>
   This manual does not attempt to provide instruction about general
   programming practices. If you are a first-time - or even just a beginning -
   programmer, you may find it difficult to learn how to program in PHP using
   this manual only. You may want to seek out a text more oriented towards
   beginners. You can find a list of PHP-related books at <ulink
   url="&url.php.books;">&url.php.books;</ulink>.
  </para>
  <para>
   There are a number of active mailing lists for discussion of all aspects of
   programming with PHP. If you find yourself stuck on a problem for which you
   can't find your own solution, you may be able to get help from someone on
   these lists. You can find a list of the mailing lists at <ulink
   url="&url.php.support;">the PHP.net support page</ulink>, as well as links to
   the mailing list archives and other online support resources. Furthermore, at
   <ulink url="&url.php.links;">the PHP.net links page</ulink> there is a list of
   websites devoted to PHP articles, forums, and code galleries.
  </para>
 </sect1>

 <sect1 id="about.howtohelp">
  <title>How to help improve the documentation</title>
  <para>
   There are three ways you can help to improve this documentation.
  </para>
  <para>
   If you find errors in this manual, in any language, please report them
   using the bug system at <ulink url="&url.php.bugs;">&url.php.bugs;</ulink>.
   Classify the bug as "Documentation Problem". You can also submit problems
   related to specific manual formats there.
  </para>
  <note>
   <para>
    Please don't abuse the bug system by submitting requests for help. Use the
    mailing lists or community sites mentioned earlier, instead.
   </para>
  </note>
  <para>
   By contributing notes, you can provide additional examples, caveats, and
   clarifications for other readers. But please do not submit bug reports using the
   annotation system. You can read more about annotations in the <link
   linkend="about.notes">'About user notes'</link> section of this
   appendix.
  </para>
  <para>
   If you know English and some foreign language, you may also
   help out in the translations. If you would like to start a new
   translation, or help in a translation project, please read
   <ulink url="&url.php.dochowto;">&url.php.dochowto;</ulink>.
  </para>
  <para>
   The PHP Documentation Project has an IRC channel where you
   can come and talk with manual authors or find some aspect
   of the manual with which you might help. It's
   <literal>#phpdoc</literal> on <literal>irc.freenode.net</literal>.
  </para>
 </sect1>
 
 <sect1 id="about.generate">
  <title>How we generate the formats</title>
  <para>
   This manual is written in <acronym>XML</acronym> using the <ulink
   url="&url.docbook.xml;">DocBook XML DTD</ulink>, using <ulink
   url="&url.dsssl;"><acronym>DSSSL</acronym></ulink> (Document
   Style and Semantics Specification Language) for formatting, and
   experimentally the <ulink url="&url.xslt;"><acronym>XSLT</acronym></ulink> 
   (Extensible Stylesheet Language Transformations)
   for maintenance and formatting.
  </para>
  <para>
   Using <acronym>XML</acronym> as a source format gives us
   the ability to generate many output formats from the source
   files, while only maintaining one source document for all formats.
   The tools used for formatting <acronym>HTML</acronym> and
   <acronym>TeX</acronym> versions are
   <ulink url="&url.jade;">Jade</ulink>, written by <ulink
   url="&url.jclark;">James Clark</ulink>; and <ulink
   url="&url.dbstyle;">The Modular DocBook Stylesheets</ulink>,
   written by <ulink url="&url.nwalsh;">Norman Walsh</ulink>.
   We use <ulink url="&url.winhelp;">Microsoft HTML Help
   Workshop</ulink> to generate the Windows HTML Help format
   of the manual, and of course PHP itself to do some
   additional conversions and formatting.
  </para>
  <para>
   You can download the manual in various languages and
   formats, including plain <acronym>HTML</acronym>,
   <acronym>PDF</acronym>, PalmPilot DOC, PalmPilot iSilo, and
   Windows HTML Help, from
   <ulink url="&url.php.docs;">&url.php.docs;</ulink>.
   Note that due to technical reasons, some formats may
   be unavailable.
  </para>
  <para>
   You can find more information about downloading the
   <acronym>XML</acronym> source code of this documentation
   at <ulink url="&url.php.cvs;">&url.php.cvs;</ulink>. The
   documentation is stored in the <literal>phpdoc</literal> module.
  </para>
 </sect1>

 <sect1 id="about.translations">
  <title>Translations</title>
  <para>
   The PHP manual is available not only in various formats, but
   also in various languages. The text of the 
   manual is first written in English, then teams of people across 
   the world take care of translating it to their native languages.
   If a translation for a specified function or chapter has not yet
   been made, the manual's build system falls back to the 
   English version of it.
  </para>
  <para>
   People involved in the translations start from the <acronym>XML</acronym>
   source code available from <ulink url="&url.php.cvs;">&url.php.cvs;</ulink>
   and from it they translate to their mother language. They do 
   <emphasis>not use</emphasis> the <acronym>HTML</acronym>, the plain text, 
   or the <acronym>PDF</acronym> version. It is the build system which takes 
   care of the conversions from <acronym>XML</acronym> to human readable formats.
  </para>
  <note>
   <para>
    If you would like to help translate the documentation to your native 
    language, please get in touch with the translation/documentation team by
    subscribing to the phpdoc mailing list: send an empty mail to <ulink
    url="mailto:&email.php.doc.subscribe;">&email.php.doc.subscribe;</ulink>.
    The mailing list address is <literal>&email.php.doc;</literal>. State in the
    message that you are interested in translating the manual to a language 
    and someone will get back to you, helping you start a new language translation 
    or reach the already active documentation team for your language.
   </para>
  </note>
  <para>
   At the moment the manual is available, partly or not, in the following languages:
   Brazilian Portuguese, Chinese (Simplified), Chinese (Hong Kong Cantonese), Chinese (Traditional), Czech, 
   Dutch, Finnish, French, German, Greek, Hebrew, Hungarian, Italian, Japanese, 
   Korean, Polish, Romanian, Russian, Slovak, Slovenian, Spanish, Swedish, and
   Turkish.
  </para>
  <para>
   They can all be downloaded here: <ulink url="&url.php.docs;">&url.php.docs;</ulink>.
  </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:"../../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
-->