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

Modified: pear/peardoc/trunk/en/package/php/php-uml/api.xml
===================================================================
--- pear/peardoc/trunk/en/package/php/php-uml/api.xml	2011-09-20 00:48:53 UTC (rev 317033)
+++ pear/peardoc/trunk/en/package/php/php-uml/api.xml	2011-09-20 01:50:04 UTC (rev 317034)
@@ -16,7 +16,7 @@
     </listitem>
     <listitem>
      <simpara>
-      The <literal>Input</literal> package, where the PHP parser resides
+      The <literal>Input</literal> package, where the PHP and XMI parser reside (they are the <literal>Importer</literal> objects).
      </simpara>
     </listitem>
     <listitem>
@@ -26,14 +26,16 @@
     </listitem>
      <listitem>
      	<simpara>
-     	The <literal>Output</literal> package, which contains all the stuff to transform a metamodel stored into memory into an output format (like XMI, HTML, or PHP)
+     	The <literal>Output</literal> package, which contains all the objects (called <literal>Exporter</literal>) to transform the UML model stored into memory into an output format (like XMI, HTML, or PHP)
      	</simpara>
     </listitem>
    </itemizedlist>
   </para>
   <para>
-   Unless you want to develop your own output format, the only single class you need to know about is <literal>PHP_UML</literal>.
-   Since the first release of PHP_UML, the API of that class has changed, and you might find several methods doing more or less the same job.
+   If the default settings suit your needs, the only single class you need to know about is <literal>PHP_UML</literal>.
+   For more advanced operations, you must use the <literal>Importer</literal> and <literal>Exporter</literal> hierarchies of objects,
+   whose roles, respectively, are to import
+   data into the UML model, and export data out from the UML model.
   </para>
  </refsection>

@@ -48,9 +50,8 @@

 $uml = new PHP_UML();
 $uml->setInput('test.php');
-$uml->parse('foo');           // parses, and sets the name of the root package
-$uml->generateXMI(1);         // generates XMI in version 1
-$uml->saveXMI('test.xmi');
+$uml->parse('foo');                 // parses, and sets the name of the root package
+$uml->export('xmi', 'test.xmi');    // first param is the format (html, php, htmlnew or xmi), second param is the output folder
 ?>
 ]]>
    </programlisting>
@@ -79,13 +80,47 @@
 <?php
 require_once 'PHP/UML.php';

-$uml = new PHP_UML();
-$uml->xmiExporter->readXMIFile('foo.xmi');
-$uml->export('php', 'C:\Inetpub\foo');
+$uml = new PHP_UML();
+
+$uml->setInput('foo.xmi');
+
+$uml->setImporter(new PHP_UML_Input_XMI_FileScanner());   // by default, PHP_UML uses a PHP_UML_Input_PHP_FileScanner
+
+$uml->parse();
+
+$exporter = new PHP_UML_Output_Php_Exporter();
+$exporter->setModel($uml->getModel());
+$exporter->export('./');
 ?>
 ]]>
    </programlisting>
   </example>
+
+  <example><info><title>Parsing of a PHP directory, followed by an XMI generation, without relying on a PHP_UML object</title></info>
+   <programlisting role="php">
+<![CDATA[
+<?php
+require_once 'PHP/UML.php';
+
+$importer = new PHP_UML_Input_PHP_FileScanner();
+$importer->setDirectories(array('somewhere/'));
+$importer->import();
+
+$exporter = new PHP_UML_Output_Xmi_Exporter();
+$exporter->setModel($importer->getModel());
+$exporter->setXmiVersion(1);
+$exporter->setEncoding('utf-8');
+$exporter->setDeploymentView(true);
+$exporter->setComponentView(true);
+$exporter->export('somewhere/else/');
+?>
+]]>
+   </programlisting>
+  </example>
+  <para>Note how the model is transfered from the importer object to the exporter object, with the
+  methods <literal>getModel()</literal> and <literal>setModel()</literal>.</para>
+  <para>You can use the factory method <literal>PHP_UML_Output_Exporter::getInstance($format)</literal> to get an exporter object given a format name,
+  instead of instantiating the objects by yourself.</para>

  </refsection>
 </refentry>

Modified: pear/peardoc/trunk/en/package/php/php-uml/command-line.xml
===================================================================
--- pear/peardoc/trunk/en/package/php/php-uml/command-line.xml	2011-09-20 00:48:53 UTC (rev 317033)
+++ pear/peardoc/trunk/en/package/php/php-uml/command-line.xml	2011-09-20 01:50:04 UTC (rev 317034)
@@ -13,7 +13,21 @@

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

-  <para>To specify the PHP files/directories to scan, pass them as main arguments:
+  <para>PHP_UML converts data into another kind of data. This can be summarized with:
+  <programlisting role="text">
+     <![CDATA[
+$ phpuml [INPUT] -o [OUTPUT LOCATION] -f [OUTPUT FORMAT]
+     ]]>
+   </programlisting>
+	 <itemizedlist>
+    <listitem>
+     <simpara>[INPUT] can be PHP files, or XMI files.</simpara>
+     <simpara>[OUTPUT FORMAT] can be PHP files, XMI files, or HTML files.</simpara>
+    </listitem>
+   </itemizedlist>
+  </para>
+
+  <para>In other words, to specify the files/directories to scan, pass them as main arguments:
     <programlisting role="text">
       <![CDATA[
 $ phpuml /var/www/foo
@@ -92,6 +106,8 @@
      ]]>
    </programlisting>
    This will read the XMI code contained in <filename>myFile.xmi</filename>, and generate the PHP code templates in <filename>/var/tmp/</filename>.
+   Note that with the command line tool, you cannot both read an XMI file and parse PHP files: you will have to use the API if you need to build
+   a UML model by merging inputs from XMI and PHP simultaneously.
   </para>
 	</example>


Modified: pear/peardoc/trunk/en/package/php/php-uml/extension.xml
===================================================================
--- pear/peardoc/trunk/en/package/php/php-uml/extension.xml	2011-09-20 00:48:53 UTC (rev 317033)
+++ pear/peardoc/trunk/en/package/php/php-uml/extension.xml	2011-09-20 01:50:04 UTC (rev 317034)
@@ -7,24 +7,26 @@

  <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 the program's structure (namespaces, classes, functions...), PHP_UML can not only interface with design tools, it
-   can also produce other output formats, via XSL transformations (this is how the format "html" is generated).
+   As we said in the
+   <link linkend="package.php.php-uml.command-line">Command Line</link> section,
+   <classname>PHP_UML</classname> converts programming data from one format to another format. Between
+   the two, it builds a UML model.
   </para>
+
+  <para>At the current moment, PHP_UML can read XMI and PHP, and can generate XMI, PHP and HTML.</para>
+
   <para>
-  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>).
+   If you want to write your own input format, you
+   can program your own implementation
+   of <literal>PHP_UML_Input_ImporterFileScanner</literal>.
   </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>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 additional output formats is to program a process that exploits the metamodel
-   that the parser has built.
-   This is how the exportation formats <literal>htmlnew</literal> and <literal>xmi</literal> work. If you want to write your own format, you
-   will have to program your own implementation
-   class of PHP_UML_Output_ExporterAPI, and put it into a new folder, under the folder Output (beside the folders HtmlNew and Xmi).
+   If you want to write your own output format, you
+   can program your own implementation
+   of <literal>PHP_UML_Output_Exporter</literal> (either by traversing the model, like the "HtmlNew" implementation does, either by XSLT applied on XMI, like the implementation "Html" does).
   </para>
+
   <para>
    For a better understanding of the program's guts, see its class diagram, available in the docs folder (PHP_UML_simplified_class_diagram.png).
   </para>

Modified: pear/peardoc/trunk/en/package/php/php-uml/intro.xml
===================================================================
--- pear/peardoc/trunk/en/package/php/php-uml/intro.xml	2011-09-20 00:48:53 UTC (rev 317033)
+++ pear/peardoc/trunk/en/package/php/php-uml/intro.xml	2011-09-20 01:50:04 UTC (rev 317034)
@@ -7,10 +7,12 @@

  <refsection><info><title>Description</title></info>
   <para>
+   <classname>PHP_UML</classname> converts programming data from one format (PHP or XMI) to another (PHP, XMI or HTML).
+   In other words,
    <classname>PHP_UML</classname> is a reverse-engineering tool, and an API documentation tool.
   </para>
   <para>
-   It can parse PHP files, and immediately generate:
+   It can parse PHP files, and generate:
   </para>
   <para>
    <itemizedlist>
@@ -38,11 +40,11 @@

  <refsection><info><title>Features</title></info>
   <para>
-   <classname>PHP_UML</classname> is able to 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 annotations: <literal>@package</literal>, <literal>@var</literal>, <literal>@param</literal>
+   <classname>PHP_UML</classname> is able to parse the following PHP elements: namespaces, classes, interfaces, properties, and functions. It can also retrieve information from the inline comments, via the annotations: <literal>@package</literal>, <literal>@var</literal>, <literal>@param</literal>
    <itemizedlist>
     <listitem>
      <simpara>
-      <literal>@param</literal> and <literal>@var</literal> learn PHP_UML about the expected types of a parameter or a property.
+      <literal>@param</literal> and <literal>@var</literal> learn PHP_UML about the expected types of a parameter or a property (when type hinting is not present).
      </simpara>
     </listitem>
     <listitem>