cvs: peardoc /en preface.xml

From: Date: Fri, 09 May 2003 06:15:30 +0000
Subject: cvs: peardoc /en preface.xml
Groups: php.pear.doc 
Request: Send a blank email to pear-doc+get-755@lists.php.net to get a copy of this message
philip Fri May 9 02:15:30 2003 EDT Modified files: /peardoc/en preface.xml Log: General rewrite including additional information and proper english. Index: peardoc/en/preface.xml diff -u peardoc/en/preface.xml:1.3 peardoc/en/preface.xml:1.4 --- peardoc/en/preface.xml:1.3 Wed Apr 30 18:47:54 2003 +++ peardoc/en/preface.xml Fri May 9 02:15:30 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1" ?> -<!-- $Revision: 1.3 $ --> +<!-- $Revision: 1.4 $ --> <preface id="preface"> <title>Preface</title> @@ -26,16 +26,17 @@ </para> <para> - It is based on the great work, the PHP documentation group has - done in the past. + The basic structure is based on the great work already done by the PHP + documentation group. Read <ulink link="&url.php.manual.about;">About + the PHP manual</ulink> for more details. </para> </sect1> <sect1 id="structure"> <title>The structure of the Manual</title> <para> - The manual is divided into five parts. Take a look on - the here-mentioned describtion to find the wanted information - as fast as possible. + This guide explains the general structure, layout, and conventions used + in the PEAR manual. The manual is divided into five main parts, they + are: </para> <para> <itemizedlist> @@ -44,9 +45,10 @@ <link linkend="about-pear">About PEAR</link> </para> <para> - General information about installing and using PEAR. - If you don't know what PEAR is, this section is your starting - point. + This section contains a gentle introduction to what PEAR is and has + to offer. Included is general information about installing and using + PEAR, support options, and answers to frequently asked PEAR related + questions. </para> </listitem> <listitem> @@ -54,45 +56,39 @@ <link linkend="core">Core components</link> </para> <para> - This section contains documentation about the - PEAR classes providing the basics for the - administration and using of PEAR. As a PEAR user, - you should take a look on the docs of the - &class.pear; base class and the &class.pear-error; object. - </para> - <para> - The here documented classes should be generally shipped - with every regular PHP distribution. - </para> + This section contains documentation about the core PEAR classes. + These core components are the base to every PEAR class and + understanding the basics will allow general use of the PEAR library. + Topics include the &class.pear; base, PEAR administration, error + handling through use of the &class.pear-error; object, and system + commands. These classes are generally shipped with every source + PHP distribution. </listitem> <listitem> <para> <link linkend="packages">Packages</link> </para> <para> - This section covers the documentation for every - regular PEAR Package. Most of them are probably - not installed on your system by default. See the - <link linkend="installation">Installation chapter - </link> for an install how-to. - </para> - <para> - A package reference page contains at least a documentation - about the available public functions. In addition it may contain - an introduction section about general use of the class - (<parameter>'Introduction'</parameter>) and - a section about constants provided by this package - (<parameter>'Constants'</parameter>). Some - references may contain an <parameter>'Example'</parameter> - part for bigger and/or more complex examples. + There are many PEAR packages with the number growing every day. Most + every package is documented and most are not installed by default. + For information on installing PEAR classes on your system, be sure to + read the <link linkend="installation">Installation chapter</link>. + </para> + <para> + Each documented class contains basic documentation about the packages + publically available functions. There may also be additional + information like an introduction, list of available constants, and + example uses of the given package. Additional information may also + exist within the package source files themselves. </para> <para> - The description of a function can contain the following parts + The description of each function may contain some or all of the + following parts: <itemizedlist> <listitem> <para>Synopsis</para> <para> - Shows the structure of the functions. + Shows the structure and prototype of the function. </para> </listitem> <listitem> @@ -104,7 +100,8 @@ <listitem> <para>Parameter</para> <para> - Describes the required and optional parameters + Describes each parameter for the function along with the paramater + types and names. Both required and optional parameters are listed. </para> </listitem> <listitem> @@ -118,13 +115,14 @@ <para>Throws</para> <para> Describes the returned <classname>PEAR_Error</classname> - objects, if the function fails + objects, if the function fails. </para> </listitem> <listitem> <para>Note</para> <para> - Additional information about the function. + Additional notes and information about the function. An example + note would be if the function can be called statically. </para> </listitem> <listitem> @@ -136,7 +134,7 @@ <listitem> <para>Example</para> <para> - A small function related example. + An example use of the function or class. </para> </listitem> </itemizedlist>

« previous php.pear.doc (#755) next »