Merge lp:~zorba-coders/zorba/data-converters-module-doc into lp:~zorba-coders/zorba/data-converters-module

[William Candillon]

Minor documentation improvements.

Minor documentation improvements.

[Sorin Marian Nasoi (sorin.marian.nasoi)]

Please note that these changes work only in the new XQDoc generator that is not yet merged into the trunk.

review: Approve

[William Candillon (wcandillon)]

review: Approve

=== modified file 'src/com/zorba-xquery/www/modules/converters/csv.xq'
--- src/com/zorba-xquery/www/modules/converters/csv.xq	2011-08-17 23:28:43 +0000
+++ src/com/zorba-xquery/www/modules/converters/csv.xq	2012-09-28 12:53:22 +0000
@@ -21,7 +21,7 @@
  : The functions are optimized to work with large amounts of data, in a streaming way.
  :
  : @author Daniel Turcanu
- : @project data processing/data converters
+ : @project Zorba/Data Converters/CSV
  :)
 module namespace csv = "http://www.zorba-xquery.com/modules/converters/csv";
 
@@ -40,32 +40,24 @@
 
 (:~
  : Parse a CSV or fixed size text and convert to XML.<br/>
- : By default each line is converted to a &lt;row> element, and each field to a &lt;column> element inside &lt;row>.<br/>
+ : By default each line is converted to a <code>row</code> element, and each field to a <code>column</code> element inside <code>row</code>.<br/>
  : The format of the param $options is:<br/>
- :    &lt;csv-options:options><br/>
- :        &lt;csv  [separator="default comma ,"] ? <br/>
- :          [quote-char="default double quotes &amp;quote;"]? <br/>
- :          [quote-escape="default double double quotes &amp;quote;&amp;quote;"]? /> <br/>
- :        <br/>
- :        or<br/>
- :        &lt;column-widths><br/>
- :          &lt;column-width><i>[column fixed width, unsigned int]</i>&lt;column-width>*<br/>
- :		  	&lt;/column-widths><br/>
- :        <br/>
- :        or<br/>
- :        &lt;column-positions><br/>
- :          &lt;column-position><i>[column position on line, unsigned int]</i>&lt;column-position>*<br/>
- :		  	&lt;/column-positions><br/>
- :        <br/>
- :        &lt;first-row-is-header [line="<i>first_line[-last_line]?</i>"]?/>?<br/>
- :        &lt;start-from-row line="<i>first_line[-last_line]?</i>"/>?<br/>
- :        &lt;add-last-void-columns/>?<br/>
- :        &lt;xml-nodes><br/>
- :          [&lt;<i>row-name</i>><br/>
- :            [&lt;<i>column-name/</i>>]?<br/>
- :          &lt;/<i>row-name</i>>]?<br/>
- :        &lt;/xml-nodes>?<br/>
- :    &lt;/csv-options:options><br/>
+ : <pre class="ace-static" ace-mode="xquery"><![CDATA[<csv-options:options>
+ :   <csv  [separator="default comma ,"]?
+ :         [quote-char="default double quotes &quote;"]?
+ :         [quote-escape="default double double quotes &quote;&quote;"]? />
+ :     <column-widths>
+ :       <column-width>[(column fixed width | column fixed width), unsigned int]<column-width>*
+ :		 </column-widths>
+ :     <first-row-is-header [line="<i>first_line[-last_line]?</i>"]?/>?
+ :     <start-from-row line="<i>first_line[-last_line]?</i>"/>?
+ :     <add-last-void-columns/>?
+ :     <xml-nodes>
+ :     [<row-name>
+ :       [<column-name/>]?
+ :      <row-name />]?
+ :     </xml-nodes>?
+ : </csv-options:options>]]></pre>
  :    <br/>
  :    All the parameters are optional and can appear in any order.<br/>
  :    All the parameters are case sensitive. The namespace used is "http://www.zorba-xquery.com/modules/converters/csv-options".<br/>
@@ -113,11 +105,11 @@
  :        1,John,student</i><br/>
  :        <br/>
  :        is parsed into<br/>
- :        <i>&lt;row><br/>
- :        &lt;ID>1&lt;/ID><br/>
- :        &lt;Name>John&lt;/Name><br/>
- :        &lt;Occupation>student&lt;/Occupation><br/>
- :        &lt;/row></i><br/>
+ :        <pre class="ace-static" ace-mode="xquery"><![CDATA[<row>
+ :   <ID>1</ID>
+ :   <Name>John</Name>
+ :   <Occupation>student</Occupation>
+ : </row>]]></pre>
  :			  <br/>
  :        If the header names contain characters that cannot be used in a QName, they are replaced with underscore '_'.<br/>
  :        The namespace for the header QNames is taken from the column name specified in xml-nodes parameter, or from
@@ -134,14 +126,14 @@
  :        1,John,Howard,student</i><br/>
  :				<br/>
  :        is parsed into<br/>
- :        <i>&lt;row><br/>
- :        &lt;ID>1&lt;/ID><br/>
- :        &lt;Name><br/>
- :          &lt;First_Name>John&lt;/First_Name><br/>
- :          &lt;Last_Name>Howard&lt;/Last_Name><br/>
- :        &lt;/Name><br/>
- :        &lt;Occupation>student&lt;/Occupation><br/>
- :        &lt;/row></i><br/>
+ :        <pre class="ace-static" ace-mode="xquery"><![CDATA[<row>
+ :   <ID>1</ID>
+ :   <Name>
+ :     <First_Name>John</First_Name>
+ :     <Last_Name>Howard</Last_Name>
+ :   </Name>
+ :   <Occupation>student</Occupation>
+ : </row>]]></pre>
  :        <br/>
  :        This element can have an attribute "accept-all-lines" with values "false" or "true" (default "false").
  :        When set to true it tells the parser to not report lines that do not have the same number of items as 
@@ -165,18 +157,18 @@
  :        that enclose the fields in the output xml if there is no header. <br/>
  :        If the csv has a header, only the namespace is used from the column element.<br/>
  :        For example, with parameter:<br/>
- :        <i>&lt;xml-nodes><br/>
- :        &lt;r><br/>
- :          &lt;c/><br/>
- :        &lt;/r><br/>
- :        &lt;/xml-nodes></i><br/>
+ :        <pre class="ace-static" ace-mode="xquery"><![CDATA[<xml-nodes>
+ :   <r>
+ :     <c />
+ :   </r>
+ : </xml-nodes>]]></pre>
  :        <br/>
  :        the output for each line will look like<br/>
- :        <i>&lt;r><br/>
- :          &lt;c>field1&lt;/c><br/>
- :          &lt;c>field2&lt;/c><br/>
- :          .......<br/>
- :        &lt;/r></i><br/>        
+ :        <pre class="ace-static" ace-mode="xquery"><![CDATA[<r>
+ :   <c>field1</c>
+ :   <c>field2</c>
+ :   ......
+ : </r>]]></pre>
  :     </dd>
  :    </dl>
  : @param $csv the string containing the csv or fixed size text.
@@ -220,34 +212,29 @@
  :
  : Note: if you want to serialize out the result, make sure that the serializer method is set to "text". 
  : For example, in zorba command line, you have to set the param --serialize-text.
- : When using the <pre>file:write(...)</pre> function, you have to set the
+ : When using the <code>file:write(...)</code> function, you have to set the
  : method serialization parameter to "text":
- : <pre>
- : &lt;output:serialization-parameters&lt;
- :   &lt;output:method value="text"/&lt;
- : &lt;/output:serialization-parameters&lt;
- : </pre>
+ : <pre class="ace-static" ace-mode="xquery"><![CDATA[<output:serialization-parameters>
+ :   <output:method value="text"/>
+ : </output:serialization-parameters>]]></pre>
  :
- : The <pre>$options</pre> parameter must have the following format:
- : <pre>
- :    &lt;csv-options:options><br/>
- :        &lt;csv  [separator="default comma ,"] ? <br/>
- :          [quote-char="default double quotes &amp;quote;"]? <br/>
- :          [quote-escape="default double double quotes &amp;quote;&amp;quote;"]? /> <br/>
- :        <br/>
- :        or<br/>
- :        &lt;column-widths [align="left|right"]?><br/>
- :          &lt;column-width [align="left|right"]?><i>[column fixed width, unsigned int]</i>&lt;column-width>*<br/>
- :		  	&lt;/column-widths><br/>
- :        <br/>
- :        or<br/>
- :        &lt;column-positions [align="left|right"]?><br/>
- :          &lt;column-position [align="left|right"]?><i>[column position on line, unsigned int]</i>&lt;column-position>*<br/>
- :		  	&lt;/column-positions><br/>
- :        <br/>
- :        &lt;first-row-is-header/>?<br/>
- :    &lt;/csv-options:options>
- : </pre>
+ : The <code>$options</code> parameter must have the following format:
+ : <pre class="ace-static" ace-mode="xquery"><![CDATA[<csv-options:options>
+ :   <csv  [separator="default comma ,"]?
+ :         [quote-char="default double quotes &quote;"]?
+ :         [quote-escape="default double double quotes &quote;&quote;"]? />
+ :     <column-widths>
+ :       <column-width>[(column fixed width | column fixed width), unsigned int]<column-width>*
+ :		 </column-widths>
+ :     <first-row-is-header [line="<i>first_line[-last_line]?</i>"]?/>?
+ :     <start-from-row line="<i>first_line[-last_line]?</i>"/>?
+ :     <add-last-void-columns/>?
+ :     <xml-nodes>
+ :     [<row-name>
+ :       [<column-name/>]?
+ :      <row-name />]?
+ :     </xml-nodes>?
+ : </csv-options:options>]]></pre>
  :
  : All the parameters are optional and can appear in any order.<br/>
  : All the parameters are case sensitive. The namespace used is "http://www.zorba-xquery.com/modules/converters/csv-options".<br/>
@@ -292,11 +279,11 @@
  :     <dd>The presence of this element indicates that the first row will contain the header, that is, the names of
  :        the column elements. Only the column names from the first row element are taken into account.<br/>
  :        For example, the row xml:<br/>
- :        <i>&lt;row><br/>
- :        &lt;ID>1&lt;/ID><br/>
- :        &lt;Name>John&lt;/Name><br/>
- :        &lt;Occupation>student&lt;/Occupation><br/>
- :        &lt;/row></i><br/>
+ :        <pre class="ace-static" ace-mode="xquery"><![CDATA[<row>
+ :   <ID>1</ID>
+ :   <Name>John</Name>
+ :   <Occupation>student</Occupation>
+ : </row>]]></pre>
  :        <br/>
  :        is converted to<br/>
  :        <i>ID,Name,Occupation<br/>
@@ -309,15 +296,14 @@
  :        When generating the subheaders, the non-whitespace text nodes are also taken into account, 
  :        and a separate column is generated for them too.<br/>
  :        For example, the xml row element:<br/>
- :        <i>&lt;row><br/>
- :        &lt;ID>1&lt;/ID><br/>
- :        &lt;Name><br/>
- :          Mr.<br/>
- :          &lt;First_Name>John&lt;/First_Name><br/>
- :          &lt;Last_Name>Howard&lt;/Last_Name><br/>
- :        &lt;/Name><br/>
- :        &lt;Occupation>student&lt;/Occupation><br/>
- :        &lt;/row></i><br/>
+ :        <pre class="ace-static" ace-mode="xquery"><![CDATA[<row>
+ :   <ID>1</ID>
+ :   <Name>
+ :     <First_Name>John</First_Name>
+ :     <Last_Name>Howard</Last_Name>
+ :   </Name>
+ :   <Occupation>student</Occupation>
+ : </row>]]></pre>
  :        is converted to<br/>
  :        <i>ID,Name,,Occupation<br/>
  :        ,,First Name,Last Name,<br/>

=== modified file 'src/com/zorba-xquery/www/modules/converters/html.xq'
--- src/com/zorba-xquery/www/modules/converters/html.xq	2011-08-18 23:42:49 +0000
+++ src/com/zorba-xquery/www/modules/converters/html.xq	2012-09-28 12:53:22 +0000
@@ -26,7 +26,7 @@
  :
  : @author Sorin Nasoi
  : @library <a href="http://tidy.sourceforge.net/">Tidy C++ Library</a>
- : @project data processing/data converters
+ : @project Zorba/Data Converters/HTML
  :
  :)
 module namespace html = "http://www.zorba-xquery.com/modules/converters/html";