diff options
author | Glen Stampoultzis <glens@apache.org> | 2002-03-09 01:41:01 +0000 |
---|---|---|
committer | Glen Stampoultzis <glens@apache.org> | 2002-03-09 01:41:01 +0000 |
commit | 90c3f2ec1aa973dc29c4a00b31e47c74a01bd7d3 (patch) | |
tree | 76ea1865d8c66357c7df72d5331ba6153457a4b8 /src/documentation | |
parent | b10b2d2963b2bbbd983a40ccea50ec9f442d0d3d (diff) | |
download | poi-90c3f2ec1aa973dc29c4a00b31e47c74a01bd7d3.tar.gz poi-90c3f2ec1aa973dc29c4a00b31e47c74a01bd7d3.zip |
Documented (a bit) the record generator.
git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@352161 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'src/documentation')
-rw-r--r-- | src/documentation/xdocs/hssf/book.xml | 1 | ||||
-rw-r--r-- | src/documentation/xdocs/hssf/record-generator.xml | 98 |
2 files changed, 99 insertions, 0 deletions
diff --git a/src/documentation/xdocs/hssf/book.xml b/src/documentation/xdocs/hssf/book.xml index be8d03b214..d3f5fd4782 100644 --- a/src/documentation/xdocs/hssf/book.xml +++ b/src/documentation/xdocs/hssf/book.xml @@ -12,6 +12,7 @@ <menu label="HSSF"> <menu-item label="HOWTO" href="how-to.html"/> <menu-item label="Use Case" href="use-case.html"/> + <menu-item label="Record Generator" href="record-generator.html"/> </menu> </book>
\ No newline at end of file diff --git a/src/documentation/xdocs/hssf/record-generator.xml b/src/documentation/xdocs/hssf/record-generator.xml new file mode 100644 index 0000000000..2b2aba6a10 --- /dev/null +++ b/src/documentation/xdocs/hssf/record-generator.xml @@ -0,0 +1,98 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../dtd/document-v10.dtd"> + +<document> + <header> + <title>Record Generator HOWTO</title> + <authors> + <person email="glens@apache.org" name="Glen Stampoultzis" id="glens"/> + </authors> + </header> + <body> + <s1 title="How to Use the Record Generator"> + + <s2 title="History"> + <p> + The record generator was born from my frustration with translating + the Excel records to Java classes. Doing this manually is a time + consuming process. It's also very easy to make mistakes. + </p> + <p> + I wanted something that would take the defintition of what a + record looked like and do all the boring stuff for me. Thus the + record generator was born. + </p> + </s2> + + <s2 title="Capabilities"> + <p> + The record generator takes XML as input and produced 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> + </ul> + </p> + </s2> + <s2 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. + </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 around the displayed text of a chart.</description> + <author>Glen Stampoultzis (glens at apache.org)</author> + <fields> + <field type="int" size="2" name="border type"> + <const name="regular" value="0" description="regular rectangle or no border"/> + <const name="shadow" value="1" description="rectangle with shadow"/> + </field> + <field type="int" size="2" name="options"> + <bit number="0" name="auto size" description="excel calculates the size automatically if true"/> + <bit number="1" name="auto position" description="excel calculates the position automatically"/> + </field> + </fields> + </record> + ]]></source> + <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 not already exist. What this means is that you may change + test stubs but not the generated records. + </p> + </s2> + <s2 title="How it Works"> + <p> + TODO: Fill this out more + </p> + <p> + See record.xsl, record_test.xsl, FieldIterator.java, RecordUtil.java, RecordGenerator.java + </p> + <p> + </p> + </s2> + <s2 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. + </p> + <p> + Currently the record generator is optimized to create Excel records. It could be adapted to create + Word records with a little poking around. + </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 + currently quite messy with minimal comments. Sorry, I wrote it as a proof-of-concept and just went + too far. + </p> + </s2> +</s1> +</body> +</document> |