cvs: peardoc /en/pyrus about.xml /en/pyrus/commands make.xml pickle.xml

http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/about.xml?r1=1.3&r2=1.4&diff_format=u
Index: peardoc/en/pyrus/about.xml
diff -u peardoc/en/pyrus/about.xml:1.3 peardoc/en/pyrus/about.xml:1.4
--- peardoc/en/pyrus/about.xml:1.3	Fri Jun 26 05:22:01 2009
+++ peardoc/en/pyrus/about.xml	Thu Jul  2 15:45:12 2009
@@ -7,10 +7,10 @@
   </info>
 
   <para>
-   This documentation is organized
-   with progressive complexity in mind.  If you are new to Pyrus, then you should
-   start with the <link linkend="pyrus.commands">Pyrus commands</link> section
-   to familiarize yourself with the commands available for users of Pyrus.
+   This documentation is organized with progressive complexity in mind.  If
+   you are new to PEAR, you should read the
+   <link linkend="guide.users.concepts">PEAR Concepts</link> section of the
+   manual first, and then return to learn more about Pyrus.
   </para>
   <para>
    If you are migrating from using the PEAR installer, it will be helpful to
@@ -18,8 +18,24 @@
    from PEAR</link>.
   </para>
   <para>
-   If you wish to extend Pyrus, read the section on <link
-   linkend="pyrus.plugins">plugins</link>.
+   To get started with information on the features available in Pyrus,
+   start with the <link linkend="pyrus.commands">Pyrus commands</link> section
+   to familiarize yourself with the commands available for users of Pyrus,
+   then read about the <link linkend="pyrus.configuration">configuration options</link>
+   available in Pyrus.
+  </para>
+  <para>
+   If you wish to extend Pyrus's functionality, read the section on <link
+   linkend="pyrus.plugins">plugins</link>.  Finally, if you are inspired to
+   distribute your own software using Pyrus, you can either apply for a PEAR
+   developer account (<link linkend="developers-newmaint">information here</link>)
+   or read the section on releasing packages through your own channel
+   <link linkend="channels.scs">here</link>.
+  </para>
+  <para>
+   PEAR, PEAR2 and PECL developers should read the documentation on how to use
+   Pyrus to manage your existing or new packages
+   <link linkend="pyrus.developers">here</link>.
   </para>
 
  &pyrus.about.whatis;
http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/commands/make.xml?r1=1.2&r2=1.3&diff_format=u
Index: peardoc/en/pyrus/commands/make.xml
diff -u peardoc/en/pyrus/commands/make.xml:1.2 peardoc/en/pyrus/commands/make.xml:1.3
--- peardoc/en/pyrus/commands/make.xml:1.2	Sat Jun 27 05:18:06 2009
+++ peardoc/en/pyrus/commands/make.xml	Thu Jul  2 15:45:12 2009
@@ -26,6 +26,7 @@
     <listitem><simpara><literal>CREDITS</literal></simpara></listitem>
     <listitem><simpara><literal>README</literal></simpara></listitem>
     <listitem><simpara><literal>RELEASE-X.Y.Z</literal> (where X.Y.Z is the release version)</simpara></listitem>
+    <listitem><simpara><literal>API-X.Y.Z</literal> (where X.Y.Z is the API version)</simpara></listitem>
    </itemizedlist>
 
    and for a standard directory layout of
@@ -109,6 +110,11 @@
    of the file (<literal>RELEASE-1.2.3</literal> in our example) as the release
    notes.
   </para>
+  <para>
+   <literal>API-X.Y.Z</literal> is used as notes about the
+   <link linkend="guide.users.concepts.api">API</link> and the version
+   <literal>X.Y.Z</literal> is used as the API version.
+  </para>
  </section>
  <section xml:id="pyrus.commands.make.packagexmlsetup">
   <title>--packagexmlsetup</title>
http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/commands/pickle.xml?r1=1.1&r2=1.2&diff_format=u
Index: peardoc/en/pyrus/commands/pickle.xml
diff -u peardoc/en/pyrus/commands/pickle.xml:1.1 peardoc/en/pyrus/commands/pickle.xml:1.2
--- peardoc/en/pyrus/commands/pickle.xml:1.1	Fri Jun 26 18:10:52 2009
+++ peardoc/en/pyrus/commands/pickle.xml	Thu Jul  2 15:45:12 2009
@@ -4,6 +4,127 @@
 
  <section xml:id="pyrus.commands.pickle.intro">
   <info><title>Introduction</title></info>
-  <para>This is a work in progress.</para>
+  <para>
+   The pickle command is designed to make the creation of an extension for
+   <acronym>PECL</acronym> developers very easy.  It scans a CVS checkout
+   of a PECL package directory, generates package.xml, and packages a
+   release in one step.
+  </para>
+  <para>
+   The pickle command looks for these standard files:
+
+   <itemizedlist>
+    <listitem><simpara>CREDITS</simpara></listitem>
+    <listitem><simpara>README</simpara></listitem>
+    <listitem><simpara>RELEASE-X.Y.Z (where X.Y.Z is the release version)</simpara></listitem>
+    <listitem><simpara>API-X.Y.Z (where X.Y.Z is the API version)</simpara></listitem>
+   </itemizedlist>
+
+   and for a standard directory layout of
+
+<screen>
+/                Extension source files
+data/            Data files
+tests/           Test files
+doc/             Documentation files
+examples/        Example files (documentation)
+</screen>
+
+   The CREDITS file must have this format for the pickle command to recognize it:
+
+<screen>
+ <![CDATA[
+;; extensionname
+Maintainer One [handle1] <[email protected]> (role)
+Maintainer Two [handle2] <[email protected]> (role)
+ ]]>
+</screen>
+
+   Where role is one of lead, developer, contributor, helper.
+
+   The first line of README is used as the summary of the package.
+   RELEASE-X.Y.Z is used as the release notes.
+  </para>
+  <para>
+   <literal>X.Y.Z</literal> in the filename <literal>RELEASE-X.Y.Z</literal> is
+   also used to automatically calculate the stability, and
+   <literal>X.Y.Z</literal> in the filename <literal>API-X.Y.Z</literal> is used
+   to calculate the API stability.  The formula is relatively simple: if X is
+   <literal>0</literal>, the stability is set to <literal>alpha</literal>.
+   Otherwise, if X is <literal>1</literal> or greater, the following methods are
+   used to calculate the stability.
+   <itemizedlist>
+    <listitem>
+     <para>
+      If Z contains <literal>a</literal> as in the version <literal>1.0.0a1</literal>
+      the stability is set to <literal>alpha</literal>
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      If Z contains <literal>b</literal> as in the version <literal>1.0.0b1</literal>
+      the stability is set to <literal>beta</literal>
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      If Z contains <literal>RC</literal> as in the version <literal>1.0.0RC1</literal>
+      the stability is set to <literal>beta</literal>
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      Otherwise, stability is set to <literal>stable</literal>.
+     </para>
+    </listitem>
+   </itemizedlist>
+  </para>
+ </section>
+ <section xml:id="pyrus.commands.pickle.args">
+  <title>Arguments to the pickle command</title>
+  <para>
+   The pickle command has 4 arguments:
+   <screen>php pyrus.phar pickle extname channelname /path/to/packagedir extensions...</screen>
+  </para>
+  <para>
+   <literal>/path/to/packagedir</literal> specifies the location in which to
+   package up the release.  If not present, it defaults to the current working
+   directory.  The pickle command usually should be executed from that directory,
+   this argument is present to allow batch creation of package.xml files for
+   multiple extensions with a single shell script.
+  </para>
+  <para>
+   If <literal>package.xml</literal> does not exist in the location packaging
+   will take place, then the first argument is required.  The first argument
+   is the name of the package, which is usually the same name as the extension,
+   and the second argument is the channel name.  If not specified, the package
+   is assumed to be in the <literal>pecl.php.net</literal> channel.
+  </para>
+  <para>
+   The final argument, <literal>extensions</literal> is a list of file extensions
+   that should be considered source files.  By default, the file extensions
+   recognized as source files are:
+
+   <itemizedlist>
+    <listitem><simpara>c</simpara></listitem>
+    <listitem><simpara>cc</simpara></listitem>
+    <listitem><simpara>h</simpara></listitem>
+    <listitem><simpara>m4</simpara></listitem>
+    <listitem><simpara>w32</simpara></listitem>
+    <listitem><simpara>re</simpara></listitem>
+    <listitem><simpara>y</simpara></listitem>
+    <listitem><simpara>l</simpara></listitem>
+    <listitem><simpara>frag</simpara></listitem>
+   </itemizedlist>
+  </para>
+ </section>
+ <section xml:id="pyrus.commands.pickle.donotpackage">
+  <title>--donotpackage</title>
+  <para>
+   If <literal>--donotpackage</literal> or <literal>-n</literal> is specified,
+   then the pickle command will only generate package.xml, and will not
+   package up a release.  The <link linkend="pyrus.commands.package">package</link>
+   command can be used to build the release after reviewing package.xml.
+  </para>
  </section>
 </section>