cvs: peardoc /en/guide/developers/package2 dir.xml file.xml

http://cvs.php.net/viewvc.cgi/peardoc/en/guide/developers/package2/dir.xml?r1=1.3&r2=1.4&diff_format=u
Index: peardoc/en/guide/developers/package2/dir.xml
diff -u peardoc/en/guide/developers/package2/dir.xml:1.3 peardoc/en/guide/developers/package2/dir.xml:1.4
--- peardoc/en/guide/developers/package2/dir.xml:1.3	Thu Oct  9 15:16:18 2008
+++ peardoc/en/guide/developers/package2/dir.xml	Tue May  5 19:26:00 2009
@@ -1,19 +1,124 @@
 <?xml version="1.0" encoding="utf-8"?>
-<refentry xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="guide.developers.package2.dir">
- <refnamediv>
-  <refname>&lt;dir&gt;</refname>
-  <refpurpose>documenting a directory in the &lt;contents&gt; tag</refpurpose>
- </refnamediv>
- <refsection xml:id="guide.developers.package2.dir.purpose"><info><title>Documenting directories</title></info>
-  
-  <para>
-   The &lt;dir&gt; tag is identical to package.xml 1.0.  Required attributes are name and optional
-   attributes are baseinstalldir (the relative location where all files and subdirectories will
-   be installed)
-  </para>
-  <para>
-   Note that all files must be contained in a single top-level &lt;dir&gt; tag.  For simple packages,
-   simply use &lt;dir name=&quot;/&quot;&gt; as the directory name
-  </para>
- </refsection>
- </refentry>
+<refentry xmlns="http://docbook.org/ns/docbook"
+  version="lillet" xml:id="guide.developers.package2.dir"
+>
+  <refnamediv>
+    <refname>&lt;dir&gt;</refname>
+
+    <refpurpose>documenting a directory in the &lt;contents&gt;
+    tag</refpurpose>
+  </refnamediv>
+
+  <refsection xml:id="guide.developers.package2.dir.purpose">
+    <info>
+      <title>Documenting directories</title>
+    </info>
+
+    <para>
+     The <literal>&lt;dir&gt;</literal> tag describes a directory in the
+     package sources.
+     A <literal>&lt;dir&gt;</literal> tag may contain other
+     <literal>&lt;dir&gt;</literal> tags as well as
+     <link linkend="guide.developers.package2.file"><literal>&lt;file&gt;</literal></link>
+     tags.
+    </para>
+
+    <note>
+      <para>All files must be contained in a single top-level &lt;dir&gt; tag.
+      For simple packages, simply use &lt;dir name="/"&gt; as the directory
+      name.</para>
+    </note>
+  </refsection>
+
+  <refsection xml:id="guide.developers.package2.dir.attributes">
+    <info>
+      <title>Attributes</title>
+    </info>
+
+    <table xml:id="guide.developers.package2.dir.attributes.required">
+      <title>Required attributes</title>
+
+      <tgroup cols="2">
+        <thead>
+          <row>
+            <entry>Attribute name</entry>
+
+            <entry>Description</entry>
+          </row>
+        </thead>
+
+        <tbody>
+          <row>
+            <entry><literal>name</literal></entry>
+
+            <entry>Name of the directory in the sources</entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </table>
+
+    <table xml:id="guide.developers.package2.dir.attributes.optional">
+      <title>Optional attributes</title>
+
+      <tgroup cols="2">
+        <thead>
+          <row>
+            <entry>Attribute name</entry>
+
+            <entry>Description</entry>
+          </row>
+        </thead>
+
+        <tbody>
+          <row>
+            <entry><literal>baseinstalldir</literal></entry>
+
+            <entry>Relative location where all files and subdirectories will
+            be installed</entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </table>
+  </refsection>
+
+  <refsection xml:id="guide.developers.package2.dir.examples">
+    <info>
+      <title>Examples</title>
+    </info>
+
+    <para>An excerpt of the <literal>&lt;contents&gt;</literal> tag of a real
+    package.xml:</para>
+
+    <programlisting role="xml"><![CDATA[ <contents>
+  <dir name="/">
+   <dir name="examples">
+    <file name="authors.php" role="doc" />
+   </dir>
+   <dir name="HTML">
+    <dir name="Template">
+     <file name="PHPLIB.php" role="php" />
+     <dir name="PHPLIB">
+      <!-- more files -->
+     </dir>
+    </dir>
+  </dir>
+ </contents>]]></programlisting>
+
+    <para>
+     The <literal>baseinstalldir</literal> attribute is mostly used when
+     the directory structure in the package source tree does not match the
+     layout when installed (e.g. when the <filename>QuickForm/</filename>
+     directory needs to be installed as
+     <filename>HTML/QuickForm/</filename>:
+    </para>
+
+    <programlisting role="xml"><![CDATA[ <contents>
+  <dir name="/" baseinstalldir="HTML">
+   <dir name="QuickForm">
+    <file name="Element.php" role="php" />
+    <!-- would be installed as HTML/QuickForm/Element.php -->
+   </dir>
+  </dir>
+</contents>]]></programlisting>
+  </refsection>
+</refentry>
http://cvs.php.net/viewvc.cgi/peardoc/en/guide/developers/package2/file.xml?r1=1.6&r2=1.7&diff_format=u
Index: peardoc/en/guide/developers/package2/file.xml
diff -u peardoc/en/guide/developers/package2/file.xml:1.6 peardoc/en/guide/developers/package2/file.xml:1.7
--- peardoc/en/guide/developers/package2/file.xml:1.6	Mon Feb  9 20:33:47 2009
+++ peardoc/en/guide/developers/package2/file.xml	Tue May  5 19:26:00 2009
@@ -1,57 +1,258 @@
 <?xml version="1.0" encoding="utf-8"?>
-<refentry xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="guide.developers.package2.file">
- <refnamediv>
-  <refname>&lt;file&gt;</refname>
-  <refpurpose>documenting a file in the &lt;contents&gt; tag</refpurpose>
- </refnamediv>
- <refsection xml:id="guide.developers.package2.file.purpose"><info><title>Documenting files</title></info>
-  
-  <para>
-   The &lt;file&gt; tag is almost identical to package.xml 1.0.  Required 
-   attributes are name and <link linkend="developers.packagedef.roles">role</link>.  
-   Optional attributes are baseinstalldir and md5sum.  Optional attributes
-   platform and install-as have been replaced by the 
-   <link linkend="guide.developers.package2.release.purpose">release tags</link>.  
-   Specifically, &lt;install&gt; is used to specify install-as, and the
-   &lt;ignore&gt; tag can be used in conjunction with &lt;installconditions&gt; 
-   to exclude packages from being installed on particular platforms.
-  </para>
-  <para>
-   For those familiar with the platform attribute, the way to handle this example:
-  </para>
-  <para>
-   <![CDATA[<file name="scripts/foo.bat" role="script" install-as="foo.bat" platform="windows">]]>
-  </para>
-  <para>
-   is to in fact create two release sections.  The file tag would then look like:
-  </para>
-  <para>
-   <![CDATA[<file name="scripts/foo.bat" role="script">]]>
-  </para>
-  <para>
-   and the release section would look like this:
-  </para>
-  <para>
-   <![CDATA[
-<phprelease>
- <installconditions>
-  <os><name>windows</name></os>
- </installconditions>
- <filelist>
-  <install name="scripts/foo.bat" as="foo.bat"/>
- </filelist>
-</phprelease>
-<phprelease>
- <filelist>
-  <ignore name="scripts/foo.bat"/>
- </filelist>
-</phprelease>
-   ]]>
-  </para>
-  <para>
-   Note that the second &lt;phprelease&gt; tag could just as easily have had an &lt;installconditions&gt;
-   tag containing &lt;os&gt;unix&lt;/os&gt;, but this is unnecessary, as the second release will be
-   processed on any system that is not a windows system.
-  </para>
- </refsection>
- </refentry>
+<refentry xmlns="http://docbook.org/ns/docbook"
+  version="lillet" xml:id="guide.developers.package2.file"
+>
+  <refnamediv>
+    <refname><tag class="starttag">file</tag></refname>
+
+    <refpurpose>documenting a file in the &lt;contents&gt; tag</refpurpose>
+  </refnamediv>
+
+  <refsection xml:id="guide.developers.package2.file.purpose">
+    <info>
+      <title>Describing files</title>
+    </info>
+
+    <para>
+     The <tag class="starttag">file</tag> tag describes a file in a
+     directory in the package sources.
+     File tags may only occur as children of
+     <tag class="starttag"><link linkend="guide.developers.package2.dir">dir</link></tag>
+     tags.
+    </para>
+
+    <para>
+     <link linkend="guide.developers.package2.tasks">File Tasks</link>
+     can be used to modify files at package time or at installation.
+    </para>
+
+    <refsection xml:id="guide.developers.package2.file.attributes">
+      <info>
+        <title>Attributes</title>
+      </info>
+
+      <table xml:id="guide.developers.package2.file.attributes.required">
+        <title>Required attributes</title>
+
+        <tgroup cols="2">
+          <thead>
+            <row>
+              <entry>Attribute name</entry>
+
+              <entry>Description</entry>
+            </row>
+          </thead>
+
+          <tbody>
+            <row>
+              <entry><literal>name</literal></entry>
+
+              <entry>Name of the file in the sources</entry>
+            </row>
+
+            <row>
+              <entry><literal>role</literal></entry>
+
+              <entry>
+               Type of the file.
+               See <link linkend="guide.developers.package2.file.roles">roles</link>.
+              </entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+
+      <table xml:id="guide.developers.package2.file.attributes.optional">
+        <title>Optional attributes</title>
+
+        <tgroup cols="2">
+          <thead>
+            <row>
+              <entry>Attribute name</entry>
+
+              <entry>Description</entry>
+            </row>
+          </thead>
+
+          <tbody>
+            <row>
+              <entry><literal>baseinstalldir</literal></entry>
+
+              <entry>Relative location where all files and subdirectories will
+              be installed</entry>
+            </row>
+
+            <row>
+              <entry><literal>md5sum</literal></entry>
+
+              <entry>
+               MD5 hash about file contents.This is automatically
+               generated when executing <command>pear package</command>, so you
+               should never set it manually.
+              </entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+
+      <note>
+        <para>
+         Previous optional attributes (<filename>package.xml</filename> v1)
+         <tag class="attribute">platform</tag> and
+         <tag class="attribute">install-as</tag> have been replaced by the
+         <link linkend="guide.developers.package2.release.purpose">release tags</link>.
+        </para>
+
+        <para>
+         Specifically, <tag class="starttag">install</tag> is used to
+         specify <tag class="attribute">install-as</tag>, and the
+         <tag class="starttag">ignore</tag> tag can be used in conjunction
+         with <tag class="starttag">installconditions</tag> to exclude packages from
+         being installed on particular platforms.
+        </para>
+      </note>
+    </refsection>
+
+    <refsection xml:id="guide.developers.package2.file.roles">
+      <info>
+        <title>Roles</title>
+      </info>
+
+      <para>
+       The <tag class="attribute">role</tag> attribute in the
+       <tag class="starttag">file</tag> tag defines what type the file has and in
+       which location it should be installed.
+      </para>
+
+      <table>
+        <title>Possible values</title>
+
+        <tgroup cols="3">
+          <thead>
+            <row>
+              <entry>Role value</entry>
+
+              <entry>Description</entry>
+
+              <entry>Destination dir</entry>
+            </row>
+          </thead>
+
+          <tbody>
+            <row>
+              <entry><tag class="attvalue">php</tag></entry>
+
+              <entry>PHP source file</entry>
+
+              <entry><varname>$php_dir</varname> (your include path)</entry>
+            </row>
+
+            <row>
+              <entry><tag class="attvalue">doc</tag></entry>
+
+              <entry>Documentation or example file</entry>
+
+              <entry><filename>$doc_dir/Package_Name/</filename></entry>
+            </row>
+
+            <row>
+              <entry><tag class="attvalue">data</tag></entry>
+
+              <entry>Package related data files (graphics, data tables, CSS
+              etc.)</entry>
+
+              <entry><varname>$data_dir</varname><filename>/Package_Name/</filename></entry>
+            </row>
+
+            <row>
+              <entry><tag class="attvalue">www</tag></entry>
+
+              <entry>Files for the HTTPd document root</entry>
+
+              <entry><varname>$www_dir</varname><filename>/</filename></entry>
+            </row>
+
+            <row>
+              <entry><tag class="attvalue">test</tag></entry>
+
+              <entry>Package related test files (unit-tests etc)</entry>
+
+              <entry><varname>$test_dir</varname><filename>/Package_Name/</filename></entry>
+            </row>
+
+            <row>
+              <entry><tag class="attvalue">script</tag></entry>
+
+              <entry>Package related shell scripts</entry>
+
+              <entry>the PHP binary directory (<varname>$bin_dir</varname>) or
+              <constant>PHP_PEAR_BIN_DIR</constant> if defined</entry>
+            </row>
+
+            <row>
+              <entry><tag class="attvalue">ext</tag></entry>
+
+              <entry>Extension, dynamically loadable library</entry>
+
+              <entry>the PHP extension directory (<varname>$ext_dir</varname>)
+              or <constant>PHP_PEAR_EXTENSION_DIR</constant> if
+              defined</entry>
+            </row>
+
+            <row>
+              <entry><tag class="attvalue">src</tag> / <tag class="attvalue">extsrc</tag></entry>
+
+              <entry>C or C++ source code</entry>
+
+              <entry>not copied directly - used to build a extension</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+
+      <para>
+       Directory locations like <varname>$php_dir</varname> are
+       configurable in PEAR. You can use
+       <command>pear <link linkend="guide.users.commandline.config">config-show</link></command>
+       or
+       <command>pear <link linkend="guide.users.commandline.config">config-get</link> php_dir</command>
+       to retrieve their values.</para>
+    </refsection>
+
+    <refsection xml:id="guide.developers.package2.file.examples">
+      <info>
+        <title>Examples</title>
+      </info>
+
+      <programlisting><![CDATA[ <contents>
+  <dir name="/">
+   <dir name="examples">
+    <!-- gets installed as $doc_dir/Package_Name/examples/authors.php -->
+    <file name="authors.php" role="doc" />
+    <file name="authors.tpl" role="doc" />
+    <file name="README"      role="doc" />
+   </dir>
+
+   <dir name="HTML">
+    <dir name="Template">
+     <!-- gets installed as $php_dir/HTML/Template/PHPLIB.php -->
+     <file name="PHPLIB.php"     role="php" />
+     <dir  name="PHPLIB">
+      <file name="Generator.php" role="php" />
+      <file name="Helper.php"    role="php" />
+      <file name="Tool.php"      role="php" />
+      <file name="Validator.php" role="php" />
+     </dir>
+    </dir>
+   </dir>
+   <dir name="tests">
+    <file name="AllTests.php"      role="test" />
+    <file name="GeneratorTest.php" role="test" />
+    <file name="HelperTest.php"    role="test" />
+    <file name="ValidatorTest.php" role="test" />
+   </dir>
+  </dir>
+ </contents>]]></programlisting>
+    </refsection>
+  </refsection>
+</refentry>