svn: pear/peardoc/trunk/en/package/php/php-uml/ command-line.xml intro.xml

Modified: pear/peardoc/trunk/en/package/php/php-uml/command-line.xml
===================================================================
--- pear/peardoc/trunk/en/package/php/php-uml/command-line.xml	2009-07-22 21:32:58 UTC (rev 284625)
+++ pear/peardoc/trunk/en/package/php/php-uml/command-line.xml	2009-07-22 21:53:30 UTC (rev 284626)
@@ -13,7 +13,7 @@

  <refsection><info><title>Arguments</title></info>

-  <para>Pass the files and/or the directories to parse as arguments:
+  <para>Pass the files and/or the directories to parse as the main arguments:
     <programlisting role="text">
       <![CDATA[
 $ phpuml /var/www/foo
@@ -55,9 +55,10 @@
   <para>The option <literal>-o</literal> also accepts a file name, instead of a directory path.</para>
   </example>

-  <example><info><title>Generating PHP code or HTML API documentation</title></info>
+  <example><info><title>Generating an API's documentation in HTML, or some PHP code</title></info>
   <para>In addition to <emphasis>xmi</emphasis>, 2 output formats are also available: <emphasis>html</emphasis>, and <emphasis>php</emphasis>.
-	They work by applying an XSL transformation to the XMI data (in UML version 2).</para>
+  The HTML documentation produced is very similar to a Javadoc API, and offers many navigation possibilities.
+	</para>
   <para>Use the option <literal>-f</literal> to specify which format you want <literal>phpuml</literal> to generate.
     <programlisting role="text">
       <![CDATA[
@@ -68,7 +69,7 @@
    </para>

   <para>
-  If you need to provide your own XMI file, instead of parsing existing files, simply pass it as argument.
+  If you need to provide your own XMI file (instead of parsing existing PHP files), simply pass it as argument.
    <programlisting role="text">
      <![CDATA[
 $ phpuml myFile.xmi -f php -o /var/tmp/
@@ -90,13 +91,13 @@
   </example>

  <example><info><title>Converting from UML/XMI version 1 to 2</title></info>
- <para><literal>phpuml</literal> automatically converts UML/XMI data in version 1.4 to version 2.1.
+ <para><literal>phpuml</literal> can automatically convert UML/XMI data from version 1.4 to version 2.1.
    <programlisting role="text">
       <![CDATA[
 $ phpuml foo1.xmi -o foo2.xmi
       ]]>
     </programlisting>
-This will read <filename>foo1.xmi</filename>, and, if its XMI content is in version 1, converts it to version 2, and stores it in <filename>foo2.xmi</filename>.
+This will read <filename>foo1.xmi</filename>, and, if its XMI content is in version 1.x, converts it to version 2, and stores it in <filename>foo2.xmi</filename>.
 Note that this is an ad hoc conversion, inspired on what Rationale Rose, Argouml and Umbrello generate. It does not convert all of the UML entities, and it does not interpret all of the various XMI dialects.
  </para>
  </example>
@@ -112,7 +113,7 @@
   </para>
  </example>

-  <para>Other options are available (like an option to exclude certain files or directories to parse). You will discover them all by asking for <emphasis role="bold">help</emphasis>, like this:
+  <para>Other options are available (like an option to exclude certain files or directories from parsing). You will discover them by asking for <emphasis role="bold">help</emphasis>, like this:
     <programlisting role="text">
       <![CDATA[
 $ phpuml -h

Modified: pear/peardoc/trunk/en/package/php/php-uml/intro.xml
===================================================================
--- pear/peardoc/trunk/en/package/php/php-uml/intro.xml	2009-07-22 21:32:58 UTC (rev 284625)
+++ pear/peardoc/trunk/en/package/php/php-uml/intro.xml	2009-07-22 21:53:30 UTC (rev 284626)
@@ -7,16 +7,16 @@

  <refsection><info><title>Description</title></info>
   <para>
-   <classname>PHP_UML</classname> is a reverse-engineering tool, and a documentation tool.
+   <classname>PHP_UML</classname> is a reverse-engineering tool, and an API's documentation tool.
   </para>
   <para>
-   It can parse PHP files and directories, and generate:
+   It can parse PHP files, and immediately generate:
   </para>
   <para>
    <itemizedlist>
     <listitem>
      <simpara>
-      An XMI file, reflecting the object structure of the code parsed; you can then import that file into a CASE tool (such as Rational Rose)
+      An XMI file, that reflects the object structure of the code parsed (you can then import it into a CASE tool, such as Rational Rose)
      </simpara>
     </listitem>
     <listitem>
@@ -38,7 +38,7 @@

  <refsection><info><title>Features</title></info>
   <para>
-   Like <link linkend="package.php.phpdocumentor">PhpDocumentor</link>, <classname>PHP_UML</classname> can parse the following PHP elements: namespaces, classes, interfaces, properties, and functions. It can also retrieve information from the inline comments, via the docblocks: <literal>@package</literal>, <literal>@var</literal>, <literal>@param</literal>
+   Like <link linkend="package.php.phpdocumentor">PhpDocumentor</link>, <classname>PHP_UML</classname> can parse the following PHP elements: <emphasis role="bold">namespaces</emphasis>, classes, interfaces, properties, and functions. It can also retrieve information from the inline comments, via the docblocks: <literal>@package</literal>, <literal>@var</literal>, <literal>@param</literal>
    <itemizedlist>
     <listitem>
      <simpara>
@@ -66,7 +66,7 @@

  <refsection><info><title>Usage</title></info>

- <para>You can use PHP_UML either from <link linkend="package.php.php-uml.command-line">command line</link>, or by writing a piece of code that will exploit the API.</para>
+ <para>You can use PHP_UML either from <link linkend="package.php.php-uml.command-line">command line</link>, or by writing a piece of code that will rely on PHP_UML.</para>
   <example><info><title>Parsing a single file <filename>test.php</filename>, and generating its XMI file:</title></info>
    <programlisting role="php">
 <![CDATA[
@@ -92,16 +92,23 @@

  <refsection><info><title>Extension</title></info>
   <para>
-   <classname>PHP_UML</classname> is designed with evolution in mind. By choosing XMI as the pivot format for representing object oriented program structures, PHP_UML can not only interface with many design tools.
-   It can also be transformed, through XSLT, into many other formats, like the HTML API documentation generator, included in <classname>PHP_UML</classname>.
+   <classname>PHP_UML</classname> is designed with evolution in mind. By choosing XMI as the pivot format for representing the program's structure (namespaces, classes, functions...), PHP_UML can not only interface with many design tools.
+   It can also produce other output formats, via XSL transformations (this is how the HTML documentation is generated).
   </para>
   <para>
-   To start your own transformation, create a folder under <filename>/Output</filename>, and create a <filename>main.xsl</filename> file inside (you can copy the one in <filename>/Output/html</filename>). Run the method <literal>PHP_UML->export()</literal>, passing the name of your format as the first parameter.
+  If you only need to customize a bit the look and feel of the HTML doc, just modify the stylesheet (in <filename>/UML/Output/html/resources/style.css</filename>).
   </para>
+  <para>But if you need deeper changes, you will have to create your own XSL transformation.
+   For that, start with a new folder under <filename>/UML/Output/</filename>, and put a <filename>main.xsl</filename> file inside (you can copy the one in <filename>/Output/html/</filename>). Write all your XSLT stuff in <filename>main.xsl</filename>, or split it among multiple template files (that's how PHP_UML does). Then run the method <literal>PHP_UML->export("newFormat")</literal>, by passing the name of your transformation as the first parameter.
+  </para>
   <para>
-   Instead of transforming XMI code, another way to create new output formats is to write a PHP class that will directly exploit the metamodel that the parser has built, exactly like the package <literal>XMI</literal> does.
+   Instead of transforming XMI code, another way to create additional output formats would be to write a PHP class that would directly exploit the metamodel that the parser has built, exactly like the package <literal>XMI</literal>'s classes do.
+   That dedicated class should implement <literal>PHP_UML_XMI_Builder</literal>.
   </para>
   <para>
+   For a better understanding of the program's guts, see its class diagram, available in the docs folder (PHP_UML_class_diagram.png).
+  </para>
+  <para>
    If you are interested by the PHP_UML project, and want to participate, do not hesitate to contact me.
   </para>
  </refsection>