Some changes to record generation

git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@352885 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 110 insertions, 30 deletions

diff --git a/src/documentation/xdocs/hssf/record-generator.xml b/src/documentation/xdocs/hssf/record-generator.xml
index 503a1599c1..df5b95f6b6 100644
--- a/src/documentation/xdocs/hssf/record-generator.xml
+++ b/src/documentation/xdocs/hssf/record-generator.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
+<!-- <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd"> -->
 
 <document>
   <header>
@@ -20,34 +20,37 @@
         </p>
         <p>
         A utility was needed to take the defintition of what a
-        record looked like and do all the boring stuff.  Thus the
-        record generator was born.
+        record looked like and do all the boring and repetitive work.
         </p>
     </section>
 
     <section title="Capabilities">
     <p>
-        The record generator takes XML as input and produced the following
+        The record generator takes XML as input and produces the following
         output:
         <ul>
             <li>A Java file capabile of decoding and encoding the record.</li>
-            <li>A test class with provides a fill-in-the-blanks implementation of a test case
-                for ensuring the record operates as designed.</li>
+            <li>A test class that provides a fill-in-the-blanks implementation
+                of a test case for ensuring the record operates as
+                designed.</li>
         </ul>
     </p>
     </section>
     <section title="Usage">
         <p>
-            The record generator is invoked as an Ant target (generate-records).  It goes
-            through looking for all files in src/records/defintitions ending with _record.xml.
-            It then creates two files; the Java record definition and the Java test case template.
+            The record generator is invoked as an Ant target
+            (generate-records).  It goes through looking for all files in
+            <code>src/records/defintitions</code> ending with _record.xml.
+            It then creates two files; the Java record definition and the
+            Java test case template.
         </p>
         <p>
             The records themselves have the following general layout:
         </p>
         <source><![CDATA[
-<record id="0x1032" name="Frame" package="org.apache.poi.hssf.record">
-    <description>The frame record indicates whether there is a border 
+<record id="0x1032" name="Frame" package="org.apache.poi.hssf.record"
+        excel-record-id="FRAME">
+    <description>The frame record indicates whether there is a border
                  around the displayed text of a chart.</description>
     <author>Glen Stampoultzis (glens at apache.org)</author>
     <fields>
@@ -56,22 +59,76 @@
             <const name="shadow" value="1" description="rectangle with shadow"/>
         </field>
         <field type="int" size="2" name="options">
-            <bit number="0" name="auto size" 
+            <bit number="0" name="auto size"
                description="excel calculates the size automatically if true"/>
-            <bit number="1" name="auto position" 
+            <bit number="1" name="auto position"
                description="excel calculates the position automatically"/>
         </field>
     </fields>
 </record>
         ]]></source>
         <p>
-            Currently the type can be of type int, float or string.  The 'int' 
-            type covers bytes, shorts and integers which is selected using a 
-            size of 1, 2 or 4.  An additional type called varword is used to 
-            represent a array of word values where the first short is the length
-            of the array.  The string type generation is only partially 
-            implemented.  If choosing string you must select a size of 'var'.
+            The following table details the allowable types and sizes for
+            the fields.
         </p>
+        <table>
+            <tr>
+                <th>Type</th>
+                <th>Size</th>
+                <th>Java Type</th>
+            </tr>
+            <tr>
+                <td>int</td>
+                <td>1</td>
+                <td>byte</td>
+            </tr>
+            <tr>
+                <td>int</td>
+                <td>2</td>
+                <td>short</td>
+            </tr>
+            <tr>
+                <td>int</td>
+                <td>4</td>
+                <td>int</td>
+            </tr>
+            <tr>
+                <td>int</td>
+                <td>8</td>
+                <td>long</td>
+            </tr>
+            <tr>
+                <td>int</td>
+                <td>varword</td>
+                <td>array of shorts</td>
+            </tr>
+            <tr>
+                <td>bits</td>
+                <td>1</td>
+                <td>A byte comprising of a bits (defined by the bit element)
+                    </td>
+            </tr>
+            <tr>
+                <td>bits</td>
+                <td>2</td>
+                <td>An short comprising of a bits</td>
+            </tr>
+            <tr>
+                <td>bits</td>
+                <td>4</td>
+                <td>A int comprising of a bits</td>
+            </tr>
+            <tr>
+                <td>float</td>
+                <td>8</td>
+                <td>double</td>
+            </tr>
+            <tr>
+                <td>hbstring</td>
+                <td>java expression</td>
+                <td>String</td>
+            </tr>
+        </table>
         <p>
             The Java records are regenerated each time the record generator is 
             run, however the test stubs are only created if the test stub does 
@@ -79,6 +136,29 @@
             stubs but not the generated records.
         </p>
     </section>
+    <section title="Custom Field Types">
+        <p>
+            Occationally the builtin types are not enough.  More control
+            over the encoding and decoding of the streams is required.  This
+            can be achieved using a custom type.
+        </p>
+        <p>
+            A custom type lets you escape to java to define the way in which
+            the field encodes and decodes.  To code a custom type you
+            declare your field like this:
+        </p>
+        <source><![CDATA[
+    <field type="custom:org.apache.poi.hssf.record.LinkedDataFormulaField"
+        size="var" name="formula of link" description="formula"/>
+        ]]></source>
+        <p>
+            Where the class name specified after <code>custom:</code> is a
+            class implementing the interface <code>CustomField</code>.
+        </p>
+        <p>
+            You can then implement the encoding yourself.
+        </p>
+    </section>
     <section title="How it Works">
         <p>
             The record generation works by taking an XML file and styling it 
@@ -89,23 +169,23 @@
             See record.xsl, record_test.xsl, FieldIterator.java, 
             RecordUtil.java, RecordGenerator.java
         </p>
-    </section>
-    <section title="Limitations">
         <p>
-            The record generator does not handle all possible record types and 
-            is not ment to.  Sometimes it's going to make more sense to generate
-            the records manually.  The main point of this thing is to  make the 
-            easy stuff simple.
+            There is a corresponding &quot;type&quot; generator for HDF.
+            See the HDF documentation for details.
         </p>
+    </section>
+    <section title="Limitations">
         <p>
-            Currently the record generator is optimized to create Excel records.  
-            It could be adapted to create Word records with a little poking 
-            around.
+            The record generator does not handle all possible record types and
+            goes not intend to perform this function.  When dealing with a
+            non-standard record sometimes the cost-benifit of coding the
+            record by hand will be greater than attempting modify the
+            generator.  The main point of the record generator is to save
+            time, so keep that in mind.
         </p>
         <p>
             Currently the the XSL file that generates the record calls out to 
-            Java objects.  This would have been better done as Javascript inside 
-            the XSL file itself.  The Java code for the record generation is
+            Java objects.  The Java code for the record generation is
             currently quite messy with minimal comments.  
         </p>
     </section>