cvs: peardoc /en/pyrus/differences frompear.xml

cellog		Thu Jun 18 19:09:35 2009 UTC

  Modified files:              
    /peardoc/en/pyrus/differences	frompear.xml 
  Log:
  more Pyrus documentation
  # need help with phd:toc, it doesn't seem to work the way I'm using it
  
http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/differences/frompear.xml?r1=1.1&r2=1.2&diff_format=u
Index: peardoc/en/pyrus/differences/frompear.xml
diff -u peardoc/en/pyrus/differences/frompear.xml:1.1 peardoc/en/pyrus/differences/frompear.xml:1.2
--- peardoc/en/pyrus/differences/frompear.xml:1.1	Thu Jun 18 04:50:40 2009
+++ peardoc/en/pyrus/differences/frompear.xml	Thu Jun 18 19:09:35 2009
@@ -1,9 +1,125 @@
 <?xml version="1.0" encoding="utf-8"?>
-<section xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="pyrus.differences.frompear">
+<section xmlns="http://docbook.org/ns/docbook" xmlns:phd="http://www.php.net/ns/phd" version="lillet" xml:id="pyrus.differences.frompear">
  <info><title>Pyrus: Improvements from the PEAR Installer</title></info>
 
+ <phd:toc phd:element="pyrus.differences.frompear" phd:toc-depth="2"/>
  <section xml:id="pyrus.differences.frompear.overview">
   <info><title>Overview</title></info>
-  <para>This is a work in progress.</para>
+  <para>
+   Pyrus is a re-factored version of the PEAR installer, re-designed for new features
+   available in PHP 5.3 and newer.  As a result, Pyrus is more robust than PEAR
+   as well as faster.  Several of the subtle design flaws in the PEAR Installer
+   have been fixed, and so Pyrus is more stable than the PEAR Installer for
+   handling an existing PEAR repository.
+  </para>
+  <para>
+   Here is a brief summary of the differences from PEAR:
+  </para>
+  <section xml:id="pyrus.differences.frompear.overview.simpler">
+   <title>Simpler to use than PEAR</title>
+   <para>
+    Pyrus is distributed as a single file, pyrus.phar.  Because of PHP's new
+    phar extension, Pyrus does not need to be installed, and can run directly
+    from the file pyrus.phar.
+   </para>
+   <para>
+    Pyrus also simplifies the command-line options available, and provides a
+    far greater range of developer tools for creating, managing and
+    distributing packages through tools such as the simple channel server and
+    package.xml creation command <literal>make</literal>.
+   </para>
+  </section>
+  <section xml:id="pyrus.differences.frompear.overview.secure">
+   <title>More secure than PEAR</title>
+   <para>
+    Several security vulnerabilities in the design of PEAR were discovered due
+    to the particular Command Pattern implementation used to detect file roles,
+    commands, and other plugins.  Pyrus fixes this by requiring that all plugins
+    be installed into a centralized location separate from the actual PEAR
+    installation.  In addition, installation of plugins cannot happen at the same
+    time as installation of packages, thus the enforced separation ensures a level
+    of security that is much higher than PEAR supports, while preserving the
+    flexibility that extending the installer provides.
+   </para>
+  </section>
+  <section xml:id="pyrus.differences.frompear.overview.smaller">
+   <title>Smaller than PEAR</title>
+   <para>
+    Because Pyrus takes advantage of PHP 5.3's built in support for XML processing,
+    archive handling, and advanced structures through the simplexml, libxml2,
+    phar, sqlite3, and spl extensions, Pyrus is significantly smaller than PEAR, and
+    as a result consumes far less memory to accomplish its tasks.
+   </para>
+  </section>
+  <section xml:id="pyrus.differences.frompear.overview.faster">
+   <title>Faster than PEAR</title>
+   <para>
+    Pyrus is also faster than PEAR because of its reliance on built-in features
+    of PHP 5.3 and a more structured object-oriented design.
+   </para>
+  </section>
+  <section xml:id="pyrus.differences.frompear.overview.robust">
+   <title>More robust than PEAR</title>
+   <para>
+    Pyrus has redundant registries in XML and Sqlite3 database formats, as well
+    as support for the existing PEAR registry.  Reconstruction of a corrupted
+    registry is simple and fully supported.
+   </para>
+   <para>
+    In addition, all installation tasks
+    occur within an atomic transaction, including file installation and removal,
+    so that if an installation or uninstall command fails mid-stream, or something
+    as drastic as a power failure occurs, the PEAR installation will be not be
+    left in a half-installed state.
+   </para>
+  </section>
+  <section xml:id="pyrus.differences.frompear.overview.flexible">
+   <title>More flexible than PEAR</title>
+   <para>
+    Pyrus supports cascading installations, so that a system-wide installation
+    of core packages can be recognized.  By default, include_path is used to
+    detect PEAR installations, but a different location for a PEAR installation
+    can be passed directly to Pyrus as its first argument.
+   </para>
+   <para>
+    Convention over configuration allows packages constructed with the new PEAR2
+    coding standards to be installed simply by extracting the archive, and then
+    later upgraded using Pyrus without the intermediate step of using Pyrus to
+    install the packages.  For the first time, this allows a try-before-you-buy
+    approach to be possible.
+   </para>
+   <para>
+    The same principle also makes bundling a PEAR2 package in another package's
+    source repository possible, and Pyrus can be used to easily upgrade the
+    package or revert to a previous version.
+   </para>
+  </section>
+  <section xml:id="pyrus.differences.frompear.overview.tested">
+   <title>More tested than PEAR</title>
+   <para>
+    Pyrus has been developed with extensive unit testing and xdebug coverage
+    data has been used to verify that the code is being executed.  As a result,
+    the first alpha release of Pyrus has 10% higher code coverage than the most
+    recent stable version of the PEAR Installer.
+   </para>
+  </section>
+ </section>
+ <section xml:id="pyrus.differences.frompear.configuration">
+  <info><title>Configuration files</title></info>
+  <para>
+   work in progress.
+  </para>
+ </section>
+ <section xml:id="pyrus.differences.frompear.registry">
+  <info><title>Registries</title></info>
+  <para>
+   work in progress.
+  </para>
+ </section>
+ <section xml:id="pyrus.differences.frompear.plugins">
+  <info><title>Extending Pyrus: plugins</title></info>
+  <para>
+   work in progress.
+  </para>
  </section>
 </section>