cvs: peardoc /en/package/php/php-uml command-line.xml intro.xml

baptiste750		Sat Jan 24 18:09:16 2009 UTC

  Modified files:              
    /peardoc/en/package/php/php-uml	command-line.xml intro.xml 
  Log:
  Updated information regarding XMI conversion from vresion 1 to 2 (from PHP_UML 5.2)
  Added subtitles for the options of the command line
  
  
http://cvs.php.net/viewvc.cgi/peardoc/en/package/php/php-uml/command-line.xml?r1=1.3&r2=1.4&diff_format=u
Index: peardoc/en/package/php/php-uml/command-line.xml
diff -u peardoc/en/package/php/php-uml/command-line.xml:1.3 peardoc/en/package/php/php-uml/command-line.xml:1.4
--- peardoc/en/package/php/php-uml/command-line.xml:1.3	Thu Jan  8 23:41:49 2009
+++ peardoc/en/package/php/php-uml/command-line.xml	Sat Jan 24 18:09:15 2009
@@ -32,6 +32,7 @@
 
  <refsection><info><title>Options</title></info>
 
+	<example><info><title>Renaming the UML model name</title></info>
   <para>By default, the root package of a UML model is named <emphasis>default</emphasis>. To rename it, use the option <literal>-n</literal>:
     <programlisting role="text">
       <![CDATA[
@@ -39,8 +40,10 @@
       ]]>
     </programlisting>
    </para>
+ </example>
  
-  <para>To save the result in a particular place, instead of printing it on the screen, use <literal>-o</literal>:
+ 	<example><info><title>Saving to a file</title></info>
+  <para>To save the XMI data in a particular place, instead of printing it on the screen, use <literal>-o</literal>:
     <programlisting role="text">
       <![CDATA[
 $ phpuml /var/www/foo -n MyProject -o /var/tmp/
@@ -48,10 +51,11 @@
     </programlisting>
     This will parse <filename>/var/www/foo</filename>, and save the XMI data to <filename>/var/tmp/MyProject.xmi</filename>.
     Use the dot to save to the current directory: <literal>-o .</literal>
-  </para>
-  
+  </para>  
   <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>
   <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>
   <para>Use the option <literal>-f</literal> to specify which format you want <literal>phpuml</literal> to generate.
@@ -71,9 +75,10 @@
      ]]>
    </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 your file must be in version 2 (not 1) of the UML/XMI standard, if you intend to generate data in format <emphasis>html</emphasis> or <emphasis>php</emphasis>.
   </para>
+	</example>
 
+	<example><info><title>Selecting the UML/XMI version</title></info>
 	<para>To select which version of the UML/XMI standards you want your XMI to be written in, use the option <literal>-x</literal>:
     <programlisting role="text">
       <![CDATA[
@@ -82,8 +87,22 @@
     </programlisting>
 Note that Argouml accepts XMI code only in version 1, while the Eclipse plugins (Ecore standard) only in version 2.
   </para>
-  
-	<para>By default, <literal>phpuml</literal> will parse only files with the extension <filename>.php</filename>. To modify this file pattern, use the <literal>- m</literal> selector:
+  </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.
+   <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>.
+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>
+ 
+ <example><info><title>Filtering the files to parse</title></info>
+ 	<para>By default, <literal>phpuml</literal> will parse only files with the extension <filename>.php</filename>. To modify this file pattern, use the <literal>- m</literal> selector:
     <programlisting role="text">
       <![CDATA[
 $ phpuml /var/www/foo -m *.php *.txt
@@ -91,8 +110,9 @@
     </programlisting>
 This will parse all <filename>php</filename> <emphasis>and</emphasis> <filename>txt</filename> files.
   </para>
+ </example>
  
-  <para>Other options are available. You will discover them by asking for help, like this:
+  <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:
     <programlisting role="text">
       <![CDATA[
 $ phpuml -h
http://cvs.php.net/viewvc.cgi/peardoc/en/package/php/php-uml/intro.xml?r1=1.5&r2=1.6&diff_format=u
Index: peardoc/en/package/php/php-uml/intro.xml
diff -u peardoc/en/package/php/php-uml/intro.xml:1.5 peardoc/en/package/php/php-uml/intro.xml:1.6
--- peardoc/en/package/php/php-uml/intro.xml:1.5	Tue Jan  6 00:42:57 2009
+++ peardoc/en/package/php/php-uml/intro.xml	Sat Jan 24 18:09:15 2009
@@ -56,7 +56,11 @@
    So the more documented your PHP code is, the more precise your XMI file, or your API documentation, will be.
   </para>
   <para>
-   At the current time, the UML/XMI standards exist in two different versions, 1.4 and 2.1. PHP_UML can generate XMI in both versions. Be warned, though, that some UML tools might not interpret accurately the data contained in your XMI file. For example, the link between a UML artifact (a source file) and the classes defined inside that artifact is only available from version 2 of UML.
+   At the current time, the UML/XMI standards exist in two distinct families of versions, 1.x and 2.x. PHP_UML can generate XMI in version <emphasis role="bold">1.4</emphasis>, as well as in version <emphasis role="bold">2.1</emphasis>.
+   Be warned, though, that some UML tools might not interpret accurately the data contained in your XMI file. For example, the link between a UML artifact (a source file) and the classes defined inside that artifact is only available from version 2 of UML.
+  </para>
+  <para>
+  PHP_UML can also convert existing UML/XMI data from version 1.4 to version 2 (simple conversion).
   </para>
  </refsection>
 
@@ -82,7 +86,7 @@
  <refsection><info><title>Compatibility of XMI</title></info>
  <para>Your UML/XMI code might be interpreted differently by the modeling tool you are going to use along with PHP_UML.
 This is particularly true for the version 2 of UML/XMI.
-For instance, the Eclipse plug-ins (EMF, Papyrus) only accept a particular flavour of XMI, called "ecore", which is only partly compatible with the one you will get with <literal>PHP_UML</literal>.
+For instance, the Eclipse plug-ins (EMF, Papyrus) only accept a particular flavour of XMI, called <emphasis>ecore</emphasis>, which is only partly compatible with the one you will get with <literal>PHP_UML</literal>.
  </para>
  </refsection>