cvs: peardoc /en/pyrus/plugins command.xml

cellog		Mon Jun 29 18:04:00 2009 UTC

  Modified files:              
    /peardoc/en/pyrus/plugins	command.xml 
  Log:
  begin work on custom command plugins
  
http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/plugins/command.xml?r1=1.1&r2=1.2&diff_format=u
Index: peardoc/en/pyrus/plugins/command.xml
diff -u peardoc/en/pyrus/plugins/command.xml:1.1 peardoc/en/pyrus/plugins/command.xml:1.2
--- peardoc/en/pyrus/plugins/command.xml:1.1	Thu Jun 18 04:50:40 2009
+++ peardoc/en/pyrus/plugins/command.xml	Mon Jun 29 18:04:00 2009
@@ -1,9 +1,106 @@
 <?xml version="1.0" encoding="utf-8"?>
-<section xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="pyrus.plugins.command">
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="lillet" xml:id="pyrus.plugins.command">
  <info><title>Pyrus plugins: custom commands</title></info>
 
  <section xml:id="pyrus.plugins.command.intro">
   <info><title>Introduction</title></info>
-  <para>This is a work in progress.</para>
+  <para>
+   Custom commands add new functionality to pyrus.phar.  An example of a
+   plugin that implements custom commands is the
+   <literal>PEAR2_Pyrus_Developer</literal> package, which implements the
+   <link linkend="pyrus.commands.make">make</link>,
+   <link linkend="pyrus.commands.package">package</link>,
+   <link linkend="pyrus.commands.pickle">pickle</link>, and
+   <link linkend="pyrus.commands.runphpt">run-phpt</link> commands.
+  </para>
+  <para>
+   Custom command plugins can implement multiple commands, and are defined by
+   an xml file that is noted in package.xml with the <literal>customcommand</literal>
+   file role.  The XML format is defined and validated by pyrus with the
+   <link xlink:href="http://svn.pear.php.net/PEAR2/Pyrus/trunk/data/customcommand-2.0.xsd">customcommand.xsd</link>
+   XSchema file.
+  </para>
+  <section xml:id="pyrus.plugins.command.intro.args">
+   <title>Command Arguments and Options: a brief primer</title>
+   <para>
+    Commands can have arguments and options.  Here is an example of a command with
+    a single argument:
+   </para>
+   <screen>php pyrus.phar install PackageName</screen>
+   <para>
+    The command is <literal>install</literal>, and the argument is
+    <literal>PackageName</literal>.
+   </para>
+   <screen>php pyrus.phar install PackageName package.xml http://example.com/Foo.tgz</screen>
+   <para>
+    The command is <literal>install</literal>, and the arguments are
+    <literal>PackageName</literal>, <literal>package.xml</literal> and
+    <literal>http://example.com/Foo.tgz</literal>.
+   </para>
+   <para>
+    Here is an example of a command with multiple arguments:
+   </para>
+   <para>
+    The command is <literal>install</literal>, and its argument is <literal>PackageName</literal>.
+   </para>
+   <para>
+    An option is a special argument that is preceded by 1-2 dashes (<literal>-</literal> or
+    <literal>--</literal>).  Short arguments are single letters preceded by a dash,
+    and long arguments are words preceded by two dashes.  Here is an example
+    of a command with both a short and a long option
+   </para>
+   <screen>php pyrus.phar package -p --tar</screen>
+   <para>
+    The command is <literal>package</literal>, the short option is
+    <literal>-p</literal> and the long option is <literal>--tar</literal>.  Short
+    options are aliases for long options, thus the <literal>-p</literal> short
+    option is an alias to the <literal>--phar</literal> long option.
+   </para>
+   <para>
+    Options can also accept arguments in 2 formats.  If an option accepts
+    an argument, there are two ways of passing that argument.  Short options
+    consider the next argument to be their argument:
+   </para>
+   <screen>php pyrus.phar install -r /path/to/packagingroot PackageName</screen>
+   <para>
+    <literal>/path/to/packagingroot</literal> is the argument to the short
+    option <literal>-r</literal>, <literal>PackageName</literal> is the argument
+    to the <literal>install</literal> command.
+   </para>
+   <para>
+    Long options require an <literal>=</literal> sign in between the option and
+    the argument as in:
+   </para>
+   <screen>php pyrus.phar install --packagingroot=/path/to/packagingroot PackageName</screen>
+   <para>
+    <literal>/path/to/packagingroot</literal> is the argument to the long
+    option <literal>--packagingroot</literal>, <literal>PackageName</literal> is the argument
+    to the <literal>install</literal> command.
+   </para>
+  </section>
+ </section>
+ <section xml:id="pyrus.plugins.command.xmloverview">
+  <title>Overview of the Custom Command XML Format</title>
+  <para>Document is a work in progress.</para>
+ </section>
+ <section xml:id="pyrus.plugins.command.arguments">
+  <title>Defining arguments</title>
+  <para>Document is a work in progress.</para>
+ </section>
+ <section xml:id="pyrus.plugins.command.options">
+  <title>Defining options</title>
+  <para>Document is a work in progress.</para>
+ </section>
+ <section xml:id="pyrus.plugins.command.cli">
+  <title>Declaring CLI command method</title>
+  <para>Document is a work in progress.</para>
+ </section>
+ <section xml:id="pyrus.plugins.command.web">
+  <title>Declaring Web command method</title>
+  <para>Document is a work in progress.</para>
+ </section>
+ <section xml:id="pyrus.plugins.command.gtk">
+  <title>Declaring GTK command method</title>
+  <para>Document is a work in progress.</para>
  </section>
 </section>