cvs: peardoc /en language-defs.ent /en/guide/users concepts.xml /en/guide/users/concepts filerole.xml filetasks.xml /en/pyrus/differences customroles.xml /en/pyrus/plugins role.xml task.xml

http://cvs.php.net/viewvc.cgi/peardoc/en/language-defs.ent?r1=1.13&r2=1.14&diff_format=u
Index: peardoc/en/language-defs.ent
diff -u peardoc/en/language-defs.ent:1.13 peardoc/en/language-defs.ent:1.14
--- peardoc/en/language-defs.ent:1.13	Sat Jun 27 05:18:05 2009
+++ peardoc/en/language-defs.ent	Wed Jul  1 19:12:43 2009
@@ -1,4 +1,4 @@
-<!-- $Revision: 1.13 $ -->
+<!-- $Revision: 1.14 $ -->
 
 <!ENTITY PEARManual        "PEAR Manual">
 <!ENTITY Translatedby      "Translated by">
@@ -10,7 +10,7 @@
 <!ENTITY Channels          "Channels: distributing your packages">
 <!ENTITY UsersGuide        "User Guide">
 <!ENTITY NewMaintainersGuide   "Becoming a PEAR developer: how to get involved">
-<!ENTITY ChangesInPear14   "PEAR Installer: customizing packages">
+<!ENTITY ChangesInPear14   "PEAR Installer: customizing the installer itself">
 <!ENTITY Features          "Features">
 <!ENTITY PEAR              "PEAR: the PHP Extension and Application Repository">
 <!ENTITY PEAR2Packages     "PEAR2 Packages">
http://cvs.php.net/viewvc.cgi/peardoc/en/guide/users/concepts.xml?r1=1.1&r2=1.2&diff_format=u
Index: peardoc/en/guide/users/concepts.xml
diff -u peardoc/en/guide/users/concepts.xml:1.1 peardoc/en/guide/users/concepts.xml:1.2
--- peardoc/en/guide/users/concepts.xml:1.1	Sat Jun 27 05:18:06 2009
+++ peardoc/en/guide/users/concepts.xml	Wed Jul  1 19:12:43 2009
@@ -17,4 +17,6 @@
   &guide.users.concepts.version;
   &guide.users.concepts.abstractpackage;
   &guide.users.concepts.channel;
+  &guide.users.concepts.filerole;
+  &guide.users.concepts.filetasks;
  </chapter>
http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/differences/customroles.xml?r1=1.2&r2=1.3&diff_format=u
Index: peardoc/en/pyrus/differences/customroles.xml
diff -u peardoc/en/pyrus/differences/customroles.xml:1.2 peardoc/en/pyrus/differences/customroles.xml:1.3
--- peardoc/en/pyrus/differences/customroles.xml:1.2	Fri Jun 26 03:25:48 2009
+++ peardoc/en/pyrus/differences/customroles.xml	Wed Jul  1 19:12:43 2009
@@ -50,7 +50,7 @@
     <![CDATA[
 <role version="2.0" xmlns="http://pear2.php.net/dtd/customrole-2.0">
  <name>php</name>
- <classprefix>PEAR2_Pyrus_Installer_Role</classprefix>
+ <class>PEAR2_Pyrus_Installer_Role_Php</class>
  <releasetypes>php</releasetypes>
  <releasetypes>extsrc</releasetypes>
  <releasetypes>extbin</releasetypes>
@@ -60,9 +60,7 @@
  <locationconfig>php_dir</locationconfig>
  <honorsbaseinstall>1</honorsbaseinstall>
  <unusualbaseinstall />
- <phpfile>1</phpfile>
  <executable />
- <phpextension />
 </role>
     ]]>
    </programlisting>
@@ -70,10 +68,12 @@
   <para>
    The most obvious difference is that Pyrus now includes the name of the role,
    PEAR extracts the role name from the name of the file (which in the
-   example above was <literal>Php.xml</literal>).
+   example above was <literal>Php.xml</literal>).  In addition, the
+   <literal>&lt;phpfile&gt;</literal> and <literal>&lt;phpextension&gt;</literal>
+   elements have been removed.
   </para>
   <para>
-   The details of new tags like &lt;classprefix&gt; and &lt;autoloadpath&gt; are
+   The details of new tags like &lt;class&gt; and &lt;autoloadpath&gt; are
    documented in the full documentation of custom roles
    <link linkend="pyrus.plugins.role">here</link>.
   </para>
http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/plugins/role.xml?r1=1.1&r2=1.2&diff_format=u
Index: peardoc/en/pyrus/plugins/role.xml
diff -u peardoc/en/pyrus/plugins/role.xml:1.1 peardoc/en/pyrus/plugins/role.xml:1.2
--- peardoc/en/pyrus/plugins/role.xml:1.1	Thu Jun 18 04:50:40 2009
+++ peardoc/en/pyrus/plugins/role.xml	Wed Jul  1 19:12:43 2009
@@ -1,9 +1,184 @@
 <?xml version="1.0" encoding="utf-8"?>
-<section xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="pyrus.plugins.role">
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="lillet"
+         xml:id="pyrus.plugins.role">
  <info><title>Pyrus plugins: custom file roles</title></info>
 
  <section xml:id="pyrus.plugins.role.intro">
   <info><title>Introduction</title></info>
-  <para>This is a work in progress.</para>
+  <para>
+   If you are not familiar with how file roles install, read the
+   <link linkend="guide.users.concepts.filerole">introduction to file roles</link>
+   first.  This segment of the documentation assumes you are familiar with
+   concepts such as <literal>baseinstalldir</literal> and with what a file
+   role means in terms of installation location.
+  </para>
+  <para>
+   Custom file roles can implement a single role, and are defined by
+   an xml file that is noted in package.xml with the <literal>customrole</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/customrole-2.0.xsd">customrole-2.0.xsd</link>
+   XSchema file.
+  </para>
+  <para>
+   Here is a human-readable custom file role xml file definition.
+   Optional elements are enclosed in [brackets], and if there is a choice of
+   values, they are delimited with a vertical bar <literal>|</literal> and
+   enclosed in (parentheses).
+  </para>
+  <programlisting role="xml">
+   <![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<role version="2.0" xmlns="http://pear2.php.net/dtd/customrole-2.0">
+ <name>rolename</name>
+ <class>MyPlugin_Rolename</class>
+[<validationmethod>validate</validationmethod>]
+[<autoloadpath>relative/path/to/MyPlugin</autoloadpath>]
+(<releasetype>php</releasetype>|<releasetype>extsrc</releasetype>|
+ <releasetype>extbin</releasetype>|<releasetype>zendextsrc</releasetype>|
+ <releasetype>zendextbin</releasetype>)
+ <installable>(1|0)</installable>
+ <locationconfig>config_var</locationconfig>
+ <honorsbaseinstall>(1|0)</honorsbaseinstall>
+ <unusualbaseinstall>(1|0)</unusualbaseinstall>
+ <executable>(1|0)</executable>
+[<configvar>
+  <name>config_name</name>
+  <type>string</type>
+  <default>
+   <![CDATA[
+    <?php $default = 'hi'; ?>
+   ]]]]><![CDATA[>
+  </default>
+  <doc>Extensive, multi-line documentation</doc>
+ [<validset>val1</validset><validset>val2</validset>...]
+  <prompt>summary documentation</prompt>
+  <group>Custom</group>
+  <configtype>(system|user|channel-specific)</configtype>
+ </configvar>]*
+</role>
+   ]]>
+  </programlisting>
+ </section>
+ <section xml:id="pyrus.plugins.role.autoload">
+  <title>Telling Pyrus how to load your role: &lt;class&gt; and &lt;autoloadpath&gt;</title>
+  <para>
+   This is the same method used for all plugins, and is documented
+   <link linkend="pyrus.plugins.autoload">here</link>.
+  </para>
+ </section>
+ <section xml:id="pyrus.plugins.role.packagetimevalidation">
+  <title>Validating your custom role at packaging time</title>
+  <para>
+   Some roles benefit from the ability to validate the files they represent
+   at packaging time.  For instance, a <literal>customcommand</literal> file
+   is checked to ensure it conforms to its XML schema, so that a custom command
+   with invalid XML cannot be distributed by mistake.
+  </para>
+  <para>
+   By convention, a validation method should be named <literal>validate</literal>,
+   although the xml supports any name.  The method name should be placed in
+   the <literal>&lt;validationmethod</literal> tag, and the method itself should
+   have the same method signature as this example from Pyrus's
+   <literal>customrole</literal> validation:
+  </para>
+  <programlisting role="php">
+   <![CDATA[
+    function validate(PEAR2_Pyrus_IPackage $package, array $file)
+    {
+        $parser = new PEAR2_Pyrus_XMLParser;
+        $schemapath = PEAR2_Pyrus::getDataPath();
+        if (!file_exists(PEAR2_Pyrus::getDataPath() . '/customrole-2.0.xsd')) {
+            $schemapath = realpath(__DIR__ . '/../../../../data');
+        }
+        $taskschema = $schemapath . '/customrole-2.0.xsd';
+        try {
+            $taskinfo = $parser->parse($package->getFilePath($file['attribs']['name']), $taskschema);
+        } catch (\Exception $e) {
+            throw new PEAR2_Pyrus_Installer_Role_Exception('Invalid custom role definition file,' .
+                                                           ' file does not conform to the schema', $e);
+        }
+    }
+   ]]>
+  </programlisting>
+  <para>
+   A custom file role package-time validator should throw a
+   <literal>PEAR2_Pyrus_Installer_Role_Exception</literal> exception object
+   with an error message describing the reason for validation failure, or simply
+   return on success.
+  </para>
+ </section>
+ <section xml:id="pyrus.plugins.role.releasetype">
+  <title>Release Types and file roles</title>
+  <para>
+   The <literal>&lt;releasetype&gt;</literal> element is used to tell Pyrus
+   which releases can contain a file with this role.  For instance, the
+   <literal>src</literal> role only has meaning in a PHP extension source release,
+   and is only allowed in <literal>extsrc</literal> and <literal>zendextsrc</literal>
+   release types.
+  </para>
+  <para>
+   There are 5 release types that Pyrus recognizes:
+   <itemizedlist>
+    <listitem><para><literal>php</literal> - this is for PEAR-style packages distributing PHP code</para></listitem>
+    <listitem><para><literal>extsrc</literal> - this is for PHP extension source packages</para></listitem>
+    <listitem><para><literal>extbin</literal> - this is for PHP extension binary packages</para></listitem>
+    <listitem><para><literal>zendextsrc</literal> - this is for PHP Zend extension source packages</para></listitem>
+    <listitem><para><literal>zendextbin</literal> - this is for PHP Zend extension binary packages</para></listitem>
+   </itemizedlist>
+  </para>
+ </section>
+ <section xml:id="pyrus.plugins.role.installable">
+  <title>&lt;installable&gt;</title>
+  <para>
+   If set to <literal>0</literal>, the file will not actually be installed onto
+   the system.  Most file roles should set this to <literal>1</literal>.
+  </para>
+ </section>
+ <section xml:id="pyrus.plugins.role.locationconfig">
+  <title>&lt;locationconfig&gt;</title>
+  <para>
+   This element is used to tell Pyrus which configuration variable should be
+   used to determine where to install the file.  This can be a
+   <link linkend="pyrus.plugins.role.configvar">custom configuration variable</link>.
+  </para>
+ </section>
+ <section xml:id="pyrus.plugins.role.baseinstall">
+  <title>&lt;honorsbaseinstall&gt; and &lt;unusualbaseinstall&gt;</title>
+  <para>
+   The <literal>&lt;honorsbaseinstall&gt;</literal> element tells Pyrus to
+   honor the <literal>baseinstalldir</literal> attribute (documentation on
+   baseinstalldir is <link linkend="guide.users.concepts.filerole.baseinstalldir">here</link>)
+   for roles like <literal>php</literal>.
+  </para>
+  <para>
+   The <literal>&lt;unusualbaseinstall&gt;</literal> element tells Pyrus to
+   honor the <literal>baseinstalldir</literal> attribute for roles like
+   <literal>data</literal> that also prepend channel/package name to the
+   installation location.
+  </para>
+ </section>
+ <section xml:id="pyrus.plugins.role.executable">
+  <title>&lt;executable&gt;</title>
+  <para>
+   If <literal>&lt;executable&gt;</literal> is set to <literal>1</literal>,
+   Pyrus will make the installed file an executable file on unix systems
+   (the equivalent of <screen>chmod +x filename</screen>).
+  </para>
+ </section>
+ <section xml:id="pyrus.plugins.role.configvar">
+  <title>Defining custom configuration variables</title>
+  <para>
+   A custom file role can optionally define a single or multiple custom
+   configuration variables.  There are 3 kinds of configuration variables
+   that Pyrus supports, <literal>system</literal>, <literal>user</literal> and
+   <literal>channel-specific</literal>.  Documentation on configuration is
+   available <link linkend="pyrus.configuration">here</link>.  Read that before
+   continuing in order to understand how different configuration variables work.
+  </para>
+  <para>
+   Pyrus supports one type of configuration variable: <literal>string</literal>.
+   The values can be restricted to a specific set of values with the
+   <literal>&lt;validset&gt;</literal> element.
+  </para>
  </section>
 </section>
http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/plugins/task.xml?r1=1.1&r2=1.2&diff_format=u
Index: peardoc/en/pyrus/plugins/task.xml
diff -u peardoc/en/pyrus/plugins/task.xml:1.1 peardoc/en/pyrus/plugins/task.xml:1.2
--- peardoc/en/pyrus/plugins/task.xml:1.1	Thu Jun 18 04:50:40 2009
+++ peardoc/en/pyrus/plugins/task.xml	Wed Jul  1 19:12:43 2009
@@ -1,9 +1,209 @@
 <?xml version="1.0" encoding="utf-8"?>
-<section xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="pyrus.plugins.task">
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="lillet"
+         xml:id="pyrus.plugins.task">
  <info><title>Pyrus plugins: custom file tasks</title></info>
 
  <section xml:id="pyrus.plugins.task.intro">
   <info><title>Introduction</title></info>
-  <para>This is a work in progress.</para>
+  <para>
+   If you are not familiar with how file tasks work, read the
+   <link linkend="guide.users.concepts.filetasks">introduction to file tasks</link>
+   first.
+  </para>
+  <para>
+   Custom file tasks can implement a single task, and are defined by
+   an xml file that is noted in package.xml with the <literal>customtask</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/customtask-2.0.xsd">customtask-2.0.xsd</link>
+   XSchema file.
+  </para>
+  <para>
+   Here is a human-readable custom file task xml file definition.
+   Optional elements are enclosed in [brackets].
+  </para>
+  <programlisting role="xml">
+   <![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<task version="2.0" xmlns="http://pear2.php.net/dtd/customtask-2.0">
+ <name>taskname</name>
+ <class>MyPlugin_Taskname</class>
+[<autoloadpath>relative/path/to/MyPlugin</autoloadpath>]
+</task>
+   ]]>
+  </programlisting>
+ </section>
+ <section xml:id="pyrus.plugins.task.autoload">
+  <title>Telling Pyrus how to load your task: &lt;class&gt; and &lt;autoloadpath&gt;</title>
+  <para>
+   This is the same method used for all plugins, and is documented
+   <link linkend="pyrus.plugins.autoload">here</link>.
+  </para>
+ </section>
+ <section xml:id="pyrus.plugins.task.taskclass">
+  <title>Defining the task: the task class</title>
+  <para>
+   A custom file task must extend the <literal>PEAR2_Pyrus_Task_Common</literal>
+   class, and must implement a few methods:
+   <itemizedlist>
+    <listitem><simpara><function>validateXml</function></simpara></listitem>
+    <listitem><simpara><function>startSession</function></simpara></listitem>
+   </itemizedlist>
+  </para>
+  <para>
+   Optionally, <function>__construct</function> may be used to do special
+   pre-processing, storing of information or other setup tasks.
+  </para>
+  <para>
+   A task must also define two class constants, <constant>TYPE</constant>
+   and <constant>PHASE</constant>.  <constant>TYPE</constant> should be one of
+   <literal>'simple'</literal> or
+   <literal>'script'</literal>.  <literal>'script'</literal> tasks are
+   post-install scripts, and are executed by the
+   <link linkend="pyrus.commands.runscripts">run-scripts</link> command.
+   <literal>'simple'</literal> tasks are executed while installation is
+   in progress.
+  </para>
+  <para>
+   <constant>PHASE</constant> should be one of:
+   <itemizedlist>
+    <listitem><simpara><constant>PEAR2_Pyrus_Task_Common::PACKAGE</constant></simpara></listitem>
+    <listitem><simpara><constant>PEAR2_Pyrus_Task_Common::INSTALL</constant></simpara></listitem>
+    <listitem><simpara><constant>PEAR2_Pyrus_Task_Common::PACKAGEANDINSTALL</constant></simpara></listitem>
+    <listitem><simpara><constant>PEAR2_Pyrus_Task_Common::POSTINSTALL</constant></simpara></listitem>
+   </itemizedlist>
+   <constant>PEAR2_Pyrus_Task_Common::POSTINSTALL</constant> is only used by
+   post-install scripts, the other 3 are used to determine at what time the
+   task should be called.  If your custom task only works at installation-time,
+   use <constant>PEAR2_Pyrus_Task_Common::INSTALL</constant>.  If the task can
+   perform only at package time (this is exceedingly rare), use
+   <constant>PEAR2_Pyrus_Task_Common::PACKAGE</constant>.  Most tasks should use
+   <constant>PEAR2_Pyrus_Task_Common::PACKAGEANDINSTALL</constant>.  If your task
+   can perform its task at packaging time, then you should override the
+   <function>isPreProcessed</function> method and return true.  Some tasks, such
+   as the <literal>replace</literal> task, perform some of their actions at
+   package time, and the rest at install time.  The <function>isPreProcessed</function>
+   method should only return true if the XML of the specific task could be
+   processed at package time.
+  </para>
+  <para>
+   The <function>startSession</function> method is used to actually execute the
+   task, and is passed a read/write file resource that is set to the beginning
+   of the file being installed.  The full path of the file's final installation
+   location is also passed in, and can be used for throwing exceptions.  All
+   errors should be handled by throwing a <literal>PEAR2_Pyrus_Task_Exception</literal>
+   or one of its descendants.
+  </para>
+  <para>
+   The <function>validateXml</function> method should validate the XML as
+   represented in an array format.  The array uses associative arrays for tags,
+   the <literal>attribs</literal> index for attributes, and for a tag with both
+   attributes and content, the <literal>_content</literal> index contains the
+   content.  If present, the <literal>tasks:</literal> namespace is removed
+   from the tags prior to passing to <function>validateXml</function>.  On
+   encountering validation errors, the method should throw one of the four
+   exceptions in the example below.
+  </para>
+ </section>
+ <section xml:id="pyrus.plugins.task.example">
+  <title>Example Custom Task</title>
+  <programlisting role="php">
+   <![CDATA[
+<?php
+class MyPlugin_Taskname extends PEAR2_Pyrus_Task_Common
+{
+    const TYPE = 'simple';
+    const PHASE = PEAR2_Pyrus_Task_Common::PACKAGEANDINSTALL;
+
+    /**
+     * Initialize a task instance with the parameters
+     * @param array raw, parsed xml
+     * @param array attributes from the <file> tag containing this task
+     * @param string|null last installed version of this package
+     */
+    function __construct($pkg, $phase, $xml, $attribs, $lastversion)
+    {
+        parent::__construct($pkg, $phase, $xml, $attribs, $lastversion);
+        // do any special parsing of attributes/contents here
+        // phase is one of PEAR2_Pyrus_Task_Common::PACKAGE,
+        // PEAR2_Pyrus_Task_Common::INSTALL, or
+        // PEAR2_Pyrus_Task_Common::POSTINSTALL
+    }
+
+    /**
+     * Validate the basic contents of a <taskname> tag
+     * @param PEAR_Pyrus_IPackageFile
+     * @param array
+     * @param array the entire parsed <file> tag
+     * @param string the filename of the package.xml
+     * @throws PEAR2_Pyrus_Task_Exception_InvalidTask
+     * @throws PEAR2_Pyrus_Task_Exception_NoAttributes
+     * @throws PEAR2_Pyrus_Task_Exception_MissingAttribute
+     * @throws PEAR2_Pyrus_Task_Exception_WrongAttributeValue
+     */
+    static function validateXml(PEAR2_Pyrus_IPackage $pkg, $xml, $fileXml, $file)
+    {
+        if (!isset($xml['attribs'])) {
+            throw new PEAR2_Pyrus_Task_Exception_NoAttributes('taskname', $file);
+        }
+        if (!isset($xml['attribs']['attributename'])) {
+            throw new PEAR2_Pyrus_Task_Exception_MissingAttribute('taskname',
+                                                                  $attrib, $file);
+        }
+        if ($xml['attribs']['attributename'] != 'hi'
+            && $xml['attribs']['attributename'] != 'bye') {
+            throw new PEAR2_Pyrus_Task_Exception_WrongAttributeValue('taskname',
+                                                                     'attributename',
+                                                                     $xml['attribs']['attributename'],
+                                                                     $file,
+                                                                     array('hi', 'bye'));
+            }
+        }
+        if (MyPlugin_Other_Class::somecondition()) {
+            throw new PEAR2_Pyrus_Task_Exception_InvalidTask(
+                'general validation errors should use this exception');
+        }
+        return true;
+    }
+
+    /**
+     * Perform the taskname task
+     * @param PEAR2_Pyrus_IPackage
+     * @param resource open file pointer, set to the beginning of the file
+     * @param string the eventual final file location (informational only)
+     * @return string|false
+     */
+    function startSession($fp, $dest)
+    {
+        // use PEAR2_Pyrus_Log::log() to send messages to the user
+        PEAR2_Pyrus_Log::log(3, 'doing stuff');
+        PEAR2_Pyrus_Log::log(0, 'doing more important stuff');
+        // operate directly on the file pointer
+        $contents = stream_get_contents($fp);
+        $contents .= 'hi';
+        rewind($fp);
+        ftruncate($fp, 0);
+        fwrite($fp, $contents);
+        return true;
+    }
+
+    /**
+     * This is used to tell the installer to skip a task that has already been
+     * executed.
+     *
+     * For example, package-info replacement tasks are performed at packaging
+     * time, and do not need to be re-applied on installation
+     * @return bool true if task has already been executed on the file at
+     *              packaging time
+     */
+    function isPreProcessed()
+    {
+        // do not implement this method unless your task does its processing
+        // at package-time!
+        return true;
+    }
+}
+?>
+   ]]>
+  </programlisting>
  </section>
 </section>

http://cvs.php.net/viewvc.cgi/peardoc/en/guide/users/concepts/filerole.xml?view=markup&rev=1.1
Index: peardoc/en/guide/users/concepts/filerole.xml
+++ peardoc/en/guide/users/concepts/filerole.xml
<?xml version="1.0" encoding="utf-8"?>
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="lillet"
         xml:id="guide.users.concepts.filerole">
 <info><title>File roles</title></info>

 <para>
  Pyrus and The PEAR Installer categorize file types by their <literal>role</literal>.
  A file role is equivalent to the web's concept of <literal>MIME type</literal>,
  a concept that allows web browsers to determine how a file should be displayed
  or processed.  A file role allows Pyrus and the PEAR Installer to determine
  where a file should be installed, the conditions under which the role can be
  used, and even whether the file should be installed at all.  A file may only
  have one role in a package.
 </para>
 <para>
  Generally speaking, each file role has its own installation location.  For
  example, <literal>php</literal> files (files whose file role is
  <literal>php</literal>) are installed into the location specified by the
  <literal>php_dir</literal> configuration variable, <literal>data</literal>
  files (files whose file role is <literal>data</literal>) are installed into
  the location specified by the <literal>data_dir</literal> configuration
  variable.  Some file roles do not have a direct mapping of role name
  to configuration variable, such as Pyrus's <literal>customcommand</literal>
  file role.  This file role is installed into the location specified by the
  <literal>data_dir</literal> configuration variable.
 </para>
 <para>
  File roles also control how package.xml attributes are handled.  The
  <literal>php</literal> file role installs files into the exact
  relative path as specified in package.xml.  The <literal>data</literal>
  file role always installs files into a subdirectory containing the package name
  for PEAR packages, and both the channel and package name for packages designed
  to be installed by Pyrus.
 </para>
 <para>
  Here is an example of the same file path in package.mxl as <literal>php</literal>
  role and as <literal>data</literal> role.  All examples assume this is a
  package named <literal>PackageName</literal> in the <literal>pear2.php.net</literal>
  channel.
 </para>
 <programlisting role="xml">
  <![CDATA[
  <contents>
   <dir name="\">
    <dir name="base">
     <file name="foo" role="php">
    </dir>
   </dir>
  </contents>
  ]]>
 </programlisting>
 <para>
  This installs as <literal>base/foo</literal> in the location specified
  by <literal>php_dir</literal>.
 </para>
 <programlisting role="xml">
  <![CDATA[
  <contents>
   <dir name="\">
    <dir name="base">
     <file name="foo" role="data">
    </dir>
   </dir>
  </contents>
  ]]>
 </programlisting>
 <para>
  For PEAR Installer packages, this installs as <literal>PackageName/base/foo</literal>
  in the location specified by <literal>php_dir</literal>.  For Pyrus packages,
  this installs as <literal>pear2.php.net/PackageName/base/foo</literal>.
 </para>
 <section xml:id="guide.users.concepts.filerole.baseinstalldir">
  <title>How the baseinstalldir attribute is handled by different file roles</title>
  <para>
   The <literal>baseinstalldir</literal> (base installation directory) attribute
   is a tool that can be used to install a file into a different directory than
   its location in the source repository.
  </para>
  <para>
   As an example, the path in the subversion repository to the file
   <literal>PEAR2\Foo.php</literal> is at
   <literal>Foo.php</literal>.  To inform the installer to install this
   package into the <literal>PEAR2</literal> directory, we would use a baseinstalldir
   attribute:
  </para>
  <programlisting role="xml">
   <![CDATA[
   <contents>
    <dir name="\">
     <file name="Foo.php" role="php" baseinstalldir="PEAR2">
    </dir>
   </contents>
   ]]>
  </programlisting>
  <para>
   The attribute can also be used on <literal>&lt;dir&gt;</literal> tags to apply
   the base installation directory to all files within the directory:
  </para>
  <programlisting role="xml">
   <![CDATA[
   <contents>
    <dir name="\" baseinstalldir="PEAR2">
     <file name="Foo.php" role="php">
    </dir>
   </contents>
   ]]>
  </programlisting>
  <para>
   The <literal>baseinstalldir</literal> role can also be used to inform
   the PEAR Installer or Pyrus to strip all relative paths by using
   <literal>/</literal> as the base installation directory.  Here is an
   example from the PEAR package:
  </para>
  <programlisting role="xml">
   <![CDATA[
   <dir name="scripts" baseinstalldir="/">
    <file name="pear.bat" role="script"/>
   ]]>
  </programlisting>
  <para>
   This file would be installed as <literal>scripts/pear.bat</literal>, but
   the <literal>baseinstalldir</literal> attribute of <literal>/</literal>
   informs the installer to instead install it to <literal>pear.bat</literal>.
  </para>
  <para>
   Each file role reacts differently to the <literal>baseinstalldir</literal>
   attribute.  Packages designed to be installed by the PEAR Installer also
   handle them differently from packages designed for installation by Pyrus.
   The <literal>php</literal>, <literal>script</literal> and <literal>www</literal>
   file roles react the
   same way as documented above.  In packages designed for the PEAR Installer,
   the other file roles do not honor the
   <literal>baseinstalldir</literal> attribute, meaning they ignore it.  For
   example:
  </para>
  <programlisting role="xml">
   <![CDATA[
   <contents>
    <dir name="\" baseinstalldir="PEAR2">
     <file name="Foo.dat" role="data">
    </dir>
   </contents>
   ]]>
  </programlisting>
  <para>
   installs <literal>Foo.dat</literal> into the <literal>PackageName/Foo.dat</literal>
   directory.  The same XML in a package designed for installation by Pyrus
   will install the file into <literal>pear2.php.net/PackageName/PEAR2/Foo.dat</literal>.
  </para>
 </section>
</section>

http://cvs.php.net/viewvc.cgi/peardoc/en/guide/users/concepts/filetasks.xml?view=markup&rev=1.1
Index: peardoc/en/guide/users/concepts/filetasks.xml
+++ peardoc/en/guide/users/concepts/filetasks.xml
<?xml version="1.0" encoding="utf-8"?>
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="lillet"
         xml:id="guide.users.concepts.filetasks">
 <info><title>File tasks</title></info>

 <para>
  Pyrus allows special handling of files through tasks.  File tasks can perform
  any action necessary both when installing a package and when creating a
  package.  Both Pyrus and the PEAR Installer ship with 4 built-in tasks,
  <literal>replace</literal>, <literal>windowseol</literal>,
  <literal>unixeol</literal>, and <literal>postinstallscript</literal>.
 </para>
 <para>
  The built-in tasks are documented <link linkend="guide.developers.package2.tasks">here</link>.
  The documentation also describes how to create custom tasks for the
  PEAR Installer.  Custom tasks for Pyrus are documented
  <link linkend="pyrus.plugins.task">here</link>.
 </para>
 <para>
  Tasks are specifically designed to allow customization of an installation, and
  particularly modification of a specific file's contents.  The
  <literal>unixeol</literal> task, for instance, transforms line endings to
  UNIX <literal>\n</literal> and is useful for shell scripts that must have
  the proper line endings.  The <literal>replace</literal> task can be used
  to update the version of a package directly in the source code, or to
  automatically set up the path to a PEAR Installation in a shell script.
 </para>
 <para>
  Tasks are defined using the XML namespace
  <literal>http://pear.php.net/dtd/tasks-1.0</literal>.  Most often, this
  is declared using <literal>tasks</literal> as the namespace prefix, as in
  <literal><![CDATA[xmlns:tasks="http://pear.php.net/dtd/tasks-1.0"]]></literal>.
  More than one task can be used for a single file, as shown by this example from
  the PEAR package:
 </para>
 <programlisting role="xml">
  <![CDATA[
    <file name="pearcmd.php" role="php">
     <tasks:replace from="@php_bin@" to="php_bin" type="pear-config" />
     <tasks:replace from="@php_dir@" to="php_dir" type="pear-config" />
     <tasks:replace from="@pear_version@" to="version" type="package-info" />
     <tasks:replace from="@include_path@" to="php_dir" type="pear-config" />
    </file>
  ]]>
 </programlisting>
</section>