cvs: peardoc /en preface.xml
| From: | Philip Olson | 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>