Documentation updates

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

7 files changed, 189 insertions, 195 deletions

diff --git a/src/documentation/xdocs/changes.xml b/src/documentation/xdocs/changes.xml
index 1962c9b85d..78dbd6068e 100644
--- a/src/documentation/xdocs/changes.xml
+++ b/src/documentation/xdocs/changes.xml
@@ -1,24 +1,85 @@
 <?xml version="1.0"?>
 
-<!DOCTYPE changes PUBLIC "-//APACHE//DTD Changes V1.0//EN" "src/documentation/xdocs/dtd/changes-v10.dtd">
+<!DOCTYPE changes PUBLIC "-//APACHE//DTD Changes V1.0//EN" "dtd/changes-v10.dtd">
 
 <changes title="History of Changes">
 
- <devs>
-  <!-- in strict alphabetical order -->
-  <person id="AO"  name="Andrew C. Oliver"   email="acoliver2@users.sourceforge.net"/>
-  <person id="GS"  name="Glen Stampoultzis"  email="gstamp@iprimus.com.au"/>  
-  <person id="MJ"  name="Marc Johnson"       email="mjohnson@apache.org"/>
-  <person id="NKB" name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
-  <person id="open" name="Poi Developers"    email="poi-dev@jakarta.apache.org"/>
- </devs>
- <release version="@version@" date="@date@">
-  <action dev="NKB" type="update">
-    New project build.
-  </action>
-  <action dev="NKB" type="update">
-    New project documentation system based on Cocoon.
-  </action>
- </release>
+    <devs>
+        <!-- in strict alphabetical order -->
+        <person id="AO"  name="Andrew C. Oliver"   email="acoliver2@users.sourceforge.net"/>
+        <person id="GJS"  name="Glen Stampoultzis" email="glens@apache.org"/>
+        <person id="MJ"  name="Marc Johnson"       email="mjohnson@apache.org"/>
+        <person id="NKB" name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
+        <person id="POI-DEVELOPERS" name="Poi Developers"    email="poi-dev@jakarta.apache.org"/>
+    </devs>
+    <release version="@version@" date="@date@">
+        <action dev="NKB" type="update">New project build.</action>
+        <action dev="NKB" type="update">New project documentation system based on Cocoon.</action>
+        <action dev="POI-DEVELOPERS" type="update">Package rename</action>
+        <action dev="POI-DEVELOPERS" type="fix">Various bug fixes</action>
+        <action dev="POI-DEVELOPERS" type="add">Early stages of HSF development (not ready for development)</action>
+        <action dev="POI-DEVELOPERS" type="add">Initial low level record support for charting (not complete)</action>
+    </release>
+    <release version="1.1.0" date="">
+        <action dev="POI-DEVELOPERS">Created new event model</action>
+        <action dev="POI-DEVELOPERS">Optimizations made to HSSF including aggregate records for
+        values, rows, etc.</action>
+        <action dev="POI-DEVELOPERS">predictive sizing, offset based writing (instead of lots of
+        array copies)</action>
+        <action dev="POI-DEVELOPERS">minor re-factoring and bug fixes.</action>
+    </release>
+    <release version="1.0.0" date="???">
+        <action dev="POI-DEVELOPERS">Minor documentation updates.</action>
+    </release>
+    <release version="0.14.0" date="???">
+        <action dev="POI-DEVELOPERS">Added DataFormat helper class and exposed set and get format
+        on HSSFCellStyle</action>
+        <action dev="POI-DEVELOPERS">Fixed column width apis (unit wise) and various javadoc on
+        the subject</action>
+        <action dev="POI-DEVELOPERS">Fix for Dimensions record (again)... (one of these days I'll
+        write a unit test for this ;-p).</action>
+        <action dev="POI-DEVELOPERS">Some optimization on sheet creation.</action>
+    </release>
+    <release version="0.13.0" date="???">
+
+    </release>
+    <release version="0.12.0" date="???">
+        <action dev="POI-DEVELOPERS">Added MulBlank, Blank, ColInfo</action>
+        <action dev="POI-DEVELOPERS">Added log4j facility and removed all sys.out type logging</action>
+        <action dev="POI-DEVELOPERS">Added support for adding font's, styles and corresponding
+        high level api for styling cells</action>
+        <action dev="POI-DEVELOPERS">added support for changing row height, cell width and default
+        row height/cell width.</action>
+        <action dev="POI-DEVELOPERS">Added fixes for internationalization (UTF-16 should work now
+        from HSSFCell.setStringValue, etc when the encoding is set)</action>
+        <action dev="POI-DEVELOPERS">added support for adding/removing and naming sheets.</action>
+    </release>
+    <release version="0.11.0" date="???">
+        <action dev="POI-DEVELOPERS">Bugfix release. We were throwing an exception when reading
+        RKRecord objects.</action>
+    </release>
+    <release version="0.10.0" date="???">
+        <action dev="POI-DEVELOPERS">Got continuation records to work (read/write)</action>
+        <action dev="POI-DEVELOPERS">Added various pre-support for formulas</action>
+        <action dev="POI-DEVELOPERS">Massive API reorganization, repackaging.</action>
+        <action dev="POI-DEVELOPERS">BiffViewer class added for validating HSSF &amp; POI and/or
+        HSSF Output.</action>
+        <action dev="POI-DEVELOPERS">Better API support for modification.</action>
+    </release>
+    <release version="0.7 (and interim releases)" date="???">
+        <action dev="POI-DEVELOPERS">Added encoding flag to high and low level api to use utf-16
+        when needed (HSSFCell.setEncoding())</action>
+        <action dev="POI-DEVELOPERS">added read only support for Label records (which are
+        reinterpreted as LabelSST when written)</action>
+        <action dev="POI-DEVELOPERS">Broken continuation record implementation (oops)</action>
+        <action dev="POI-DEVELOPERS">BiffViewer class added for validating HSSF &amp; POI and/or
+        HSSF Output.</action>
+    </release>
+    <release version="0.6 (release)" date="???">
+        <action dev="POI-DEVELOPERS">Support for read/write and modify.</action>
+        <action dev="POI-DEVELOPERS">Read only support for MulRK records (converted to Number when
+        writing)
+        </action>
+    </release>
 
 </changes>
diff --git a/src/documentation/xdocs/hssf/how-to.xml b/src/documentation/xdocs/hssf/how-to.xml
index 98b785406c..01d59232d0 100644
--- a/src/documentation/xdocs/hssf/how-to.xml
+++ b/src/documentation/xdocs/hssf/how-to.xml
@@ -19,16 +19,17 @@
     </s2>  
 
     <s2 title="Capabilities">
-    <p>This release of the how-to outlines functionality included in a
-	development build of HSSF.  Those looking for information on the
-	release edition should look in the poi-src for the release or at a
+    <p>This release of the how-to outlines functionality for 1.5.
+    Those looking for information on the release edition should
+    look in the poi-src for the release or at a
 	previous edition in CVS tagged for that release.</p>
   <p>
 	This release allows numeric and string cell values to be written to
-	or read from an XLS file. Also in this release is row and column
-	sizing, cell styling (bold, italics, borders,etc), and support for
-	built-in data formats.  New to this release is an event-based API
-	for reading XLS files.  It differs greatly from the read/write API
+	or read from an XLS file as well as reading and writing dates. Also
+    in this release is row and column sizing, cell styling (bold,
+    italics, borders,etc), and support for built-in data formats.  New
+    to this release is an event-based API for reading XLS files.
+    It differs greatly from the read/write API
 	and is intended for intermediate developers who need a smaller
 	memory footprint.  It will also serve as the basis for the HSSF
 	Generator.</p>
@@ -57,10 +58,8 @@ org.apache.poi.hssf.usermodel.HSSFWorkbook.
 </p>
 <p>Sheets are created by calling createSheet() from an existing
 instance of HSSFWorkbook, the created sheet is automatically added in
-sequence to the workbook. In this release there will always be at
-least three sheets generated regardless of whether you have three
-sheets. More than three sheets is probably not supported. Sheets do
-not in themselves have a sheet name (the tab at the bottom); you set
+sequence to the workbook. Sheets do not in themselves have a sheet
+name (the tab at the bottom); you set
 the name associated with a sheet by calling
 HSSFWorkbook.setSheetName(sheetindex,&quot;SheetName&quot;).</p>
 <p>Rows are created by calling createRow(rowNumber) from an existing
@@ -242,7 +241,7 @@ method (sheet.removeRow(hssfrow)) and create objects just as you
 would if creating a new xls. When you are done modifying cells just
 call workbook.write(outputstream) just as you did above.</p>
 <p>An example of this can be seen in
-<link href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/poi/poi/production/src/net/sourceforge/poi/hssf/dev/HSSF.java?rev=HEAD&amp;content-type=text/plain">org.apache.poi.hssf.dev.HSSF</link>.</p>
+<link href="http://cvs.apache.org/viewcvs/~checkout~/jakarta-poi/src/java/org/apache/poi/hssf/dev/HSSF.java?rev=1.1">org.apache.poi.hssf.dev.HSSF</link>.</p>
          </s4>       </s3>
                 <s3 title="Event API">
 
@@ -438,34 +437,46 @@ most likely fail.  No big deal.  </code></li>
 </ul>
      </s3>
                 <s3 title="HSSF Logging facility">
-<p>HSSF now has a logging facility (using log4j - thanks jakarta!)
+<p>HSSF now has a logging facility (using
+ <link href="http://jakarta.apache.org/commons/logging.html">commons logging</link>)
 that will record massive amounts of debugging information. Its mostly
 useful to us hssf-developing geeks, but might be useful in tracking
-down problems. By default we turn this off because it results in
-unnecessary performance degradation when fully turned on! Using it is
-simple. You need an hssflog.properties file (example listed below,
-those familiar with log4j can customize this as they wish). You can
-either put this in your home directory (or wherever the default
-directory is on windows which I suspect is c:\windows) or you can put
-it wherever you want and set the HSSF.log to the path ending in &quot;/&quot;
-(or &quot;\\&quot; on windows). If for any reason HSSF can't find it,
-you get no logging. If the log configuration dictates the logging be
-turned off, you get no logging.</p>
-<p>Here is an example hssflog.properties (actually its not an example
-its mine):
-<source># Set root category priority to DEBUG and its only appender to A1.
-log4j.rootCategory=DEBUG, A1
-  
-# A1 is set to be a ConsoleAppender. 
-log4j.appender.A1=org.apache.log4j.ConsoleAppender
-  
-# A1 uses PatternLayout.
-log4j.appender.A1.layout=org.apache.log4j.PatternLayout
-log4j.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n
-#uncomment below to change the level to WARN to disable debugging information.  This effectively turns off logging.
-#the default level is DEBUG (and changing it to DEBUG is the basically the same thing as leaving it commented out).
-#log4j.category.org.apache.poi=WARN</source></p>
-
+down problems.
+</p>
+<p>So Why use commons logging rather than log4j? Well the following discussion from
+the jakarta-general mailing list sums it up pretty well.  (Thanks Morgan)
+</p>
+<p>Here's the problem, as I see it.
+</p>
+<p><em>Suppose Commons component A decides to adopt Log4J, Commons component B
+decides to adopt LogKit, and Commons component C adopts JDK1.4 logging.
+They will all minimally function with the right jars in the classpath.
+However you (the end-user) are left with maintaining configuration for 3
+different logging APIs, which is tedious at best.  When you take into
+account cool features like variable log levels, Log4J appenders and the
+like, you're pretty much guaranteed to swallow up useful configuration
+options because sophisticated configurations are too difficult to maintain
+over mutiple logging implementations.</em>
+</p>
+<p>
+<em>Contrarily, if all three Commons components use a logging facade, you can
+focus all your configuration efforts on one logging implementation.  Sure,
+there is a trade-off; you don't have access to all the features, and the
+interface between the facade and the implementation must be maintained.  But
+the benefits are not just political; they potentially make the end-users
+configuration much easier.</em>
+</p>
+<p><em>Even if all Commons components used the same logging implementation (Log4J
+for example), other projects in Jakarta-land may choose otherwise.  If you
+add enough Jakarta projects to your environment, you eventually end up with
+the scenario described above.  It's a worthwhile effort to attempt a logging
+solution that plays well with the Jakarta community at large.  I think in
+many cases the Commons Logging component can fill that role.</em>
+</p>
+<p>
+Refer to the commons logging package level javadoc for more information concerning how to
+<link href="http://jakarta.apache.org/commons/logging/api/index.html">configure commons logging.</link>
+</p>
      </s3>
                 <s3 title="HSSF Developer's tools">
 
@@ -523,108 +534,8 @@ As a general principal, HSSF's goal is to support HSSF-Serializer
 are you using HSSF/POIFS? How would you like to use it? What features
 are most important first? 
 </p>
-<p>This release is near feature freeze for the 1.0-beta. All
-priorities refer to things we'll be adding in the next release
-(probably 2.0). The 1.0-beta is scheduled for release in the mid to
-late December timeframe. While it's way to early to say when the
-2.0-beta will be released, my &quot;gut&quot; feeling is to aim for
-around March and have at least the first three items.</p>
-<p>Current list of priorities:</p>
-<ol>
-	<li>Helper class for fonts, etc.</li>
-	<li>Add Formulas.</li>
-	<li>Implement more record types (for other things ... not sure
-	what this will mean yet).</li>
-	<li>Add more dummy checks (for when API user's do things they
-	&quot;can't&quot; do)</li>
-	<li>Add support for embedded graphics and stuff like that.</li>
-	<li>Create new adapter object for handling MulBlank, MulRk, Rk
-	records.</li>
-</ol>
      </s3>
-                <s3 title="Changes">
-                                <s4 title="1.1.0">
-
-<ol>
-	<li>Created new event model</li>
-	<li>Optimizations made to HSSF including aggregate records for
-	values, rows, etc.</li>
-	<li>predictive sizing, offset based writing (instead of lots of
-	array copies)</li>
-	<li>minor re-factoring and bug fixes.</li>
-</ol>
-</s4>
-<s4 title="1.0.0">
-
-<ol>
-	<li>Minor documentation updates.</li>
-</ol>
-</s4>
-<s4 title="0.14.0">
-<ol>
-	<ol>
-		<li>Added DataFormat helper class and exposed set and get format
-		on HSSFCellStyle</li>
-		<li>Fixed column width apis (unit wise) and various javadoc on
-		the subject</li>
-		<li>Fix for Dimensions record (again)... (one of these days I'll
-		write a unit test for this ;-p).</li>
-		<li>Some optimization on sheet creation.</li>
-	</ol>
-</ol>
-</s4>
-<s4 title="0.13.0">
-<p>- NO WAY!</p>
-</s4>
-<s4 title="0.12.0">
-<ol>
-	<li>Added MulBlank, Blank, ColInfo</li>
-	<li>Added log4j facility and removed all sys.out type logging</li>
-	<li>Added support for adding font's, styles and corresponding
-	high level api for styling cells</li>
-	<li>added support for changing row height, cell width and default
-	row height/cell width.</li>
-	<li>Added fixes for internationalization (UTF-16 should work now
-	from HSSFCell.setStringValue, etc when the encoding is set)</li>
-	<li>added support for adding/removing and naming sheets.</li>
-</ol>
-</s4>
-<s4 title="0.11.0">
-<ol>
-	<li>Bugfix release. We were throwing an exception when reading
-	RKRecord objects.</li>
-</ol>
-</s4>
-<s4 title="0.10.0">
-<ol>
-	<li>Got continuation records to work (read/write)</li>
-	<li>Added various pre-support for formulas</li>
-	<li>Massive API reorganization, repackaging.</li>
-	<li>BiffViewer class added for validating HSSF &amp; POI and/or
-	HSSF Output.</li>
-	<li>Better API support for modification.</li>
-</ol>
-</s4>
-<s4 title="0.7 (and interim releases)">
-<ol>
-	<li>Added encoding flag to high and low level api to use utf-16
-	when needed (HSSFCell.setEncoding())</li>
-	<li>added read only support for Label records (which are
-	reinterpreted as LabelSST when written)</li>
-	<li>Broken continuation record implementation (oops)</li>
-	<li>BiffViewer class added for validating HSSF &amp; POI and/or
-	HSSF Output.</li>
-</ol>
-</s4>
-<s4 title="0.6 (release)">
-<ol>
-	<li>Support for read/write and modify.</li>
-	<li>Read only support for MulRK records (converted to Number when
-	writing) 
-	</li>
-</ol>
-</s4>
-</s3>
+
 </s2>
 
 </s1>
diff --git a/src/documentation/xdocs/livesites.xml b/src/documentation/xdocs/livesites.xml
index dcd55fc672..ef07060246 100644
--- a/src/documentation/xdocs/livesites.xml
+++ b/src/documentation/xdocs/livesites.xml
@@ -2,32 +2,29 @@
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
 
 <document>
- <header>
-  <title>Live Sites using Poi</title>
-  <authors>
-   <person name="Donald Ball" email="balld@webslingerZ.com"/>
-   <person name="Stefano Mazzocchi" email="stefano@apache.org"/>
-   <person name="Robin Green" email="greenrd@hotmail.com"/>
-   <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
-  </authors>
- </header>
- 
- <body><s1 title="Live Sites using Poi">
-   <p>Here is a list of some of the web sites that are proudly using Poi 1.X (in no particular order):
-   </p>
-   <!--
-   <ul>
-    <li><link href=""></link></li>
-   </ul>
-  </s1>
-   -->
-  <p>
-    If you do not find your site here, make sure you tell us
-    (use the word &quot;Livesites&quot; in the email subject, confirm that
-    you want to be listed publicly, say which version of Poi, and do not
-    forget to tell us the URL).
-    We would like to see this list grow bigger every day :-)
-   </p>
-  </s1>
- </body>
+    <header>
+        <title>Live Sites using Poi</title>
+        <authors>
+            <person name="Donald Ball" email="balld@webslingerZ.com"/>
+            <person name="Stefano Mazzocchi" email="stefano@apache.org"/>
+            <person name="Robin Green" email="greenrd@hotmail.com"/>
+            <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
+            <person name="Glen Stampoultzis" email="glens@apache.org"/>
+        </authors>
+    </header>
+
+    <body>
+        <s1 title="Live Sites using Poi">
+            <p>Currently we don't have any sites listed that use Poi, but we're sure they're out there.
+            Help us change this.  If you've
+            written a site that utilises Poi let us know.
+            </p>
+            <!--
+            <ul>
+             <li><link href=""></link></li>
+            </ul>
+           </s1>
+            -->
+        </s1>
+    </body>
 </document>
diff --git a/src/documentation/xdocs/plan/POI10Vision.xml b/src/documentation/xdocs/plan/POI10Vision.xml
index 8868f14f64..c49d7b39a5 100644
--- a/src/documentation/xdocs/plan/POI10Vision.xml
+++ b/src/documentation/xdocs/plan/POI10Vision.xml
@@ -99,7 +99,7 @@
 		solution for outputting Office Document formats often involves
 		actually manipulating the software as an OLE Server. This method
 		provides extremely low performance, extremely high overhead and is
-		only capable of handing one document at a time. 
+		only capable of handling one document at a time.
 	</p>
 	<ol>
 		<li>
@@ -110,7 +110,7 @@
 		<li>
 		Our intended audience for the HSSF
 		library portion of this project is ourselves as we are developing
-		the serializer and anyone who needs to write to Excel spreadsheets
+		the Serializer and anyone who needs to write to Excel spreadsheets
 		in a non-XML Java environment or who has specific needs not
 		addressed by the Serializer.
 		</li>
diff --git a/src/documentation/xdocs/plan/POI20Vision.xml b/src/documentation/xdocs/plan/POI20Vision.xml
index c744f15e2e..94e7065c12 100644
--- a/src/documentation/xdocs/plan/POI20Vision.xml
+++ b/src/documentation/xdocs/plan/POI20Vision.xml
@@ -22,7 +22,7 @@
                 changed a bit.  We're not going to change the vision document to
                 reflect this (however proper that may be) because it would only
                 involve deletion.  There is no purpose in providing less
-                information provded we give clarification.
+                information provided we give clarification.
         </p>
         <p>
                 This document was created before the POI components for 
@@ -275,10 +275,10 @@
 	<table>
 		<tr>
 			<td>
-				Benefit
+				<b>Benefit</b>
 			</td>
 			<td>
-				Supporting Features
+				<b>Supporting Features</b>
 			</td>
 		</tr>
 		<tr>
diff --git a/src/documentation/xdocs/todo.xml b/src/documentation/xdocs/todo.xml
index aa30377ffb..a9dc9b13f0 100644
--- a/src/documentation/xdocs/todo.xml
+++ b/src/documentation/xdocs/todo.xml
@@ -1,13 +1,13 @@
 <?xml version="1.0" encoding="utf-8"?>
 
-<!DOCTYPE todo PUBLIC "-//APACHE//DTD Todo V1.0//EN" "src/documentation/xdocs/dtd/todo-v10.dtd">
+<!DOCTYPE todo PUBLIC "-//APACHE//DTD Todo V1.0//EN" "dtd/todo-v10.dtd">
 
 <todo title="Things To Do for Poi">
 
  <devs>
   <!-- in strict alphabetical order -->
   <person id="AO"  name="Andrew C. Oliver"   email="acoliver2@users.sourceforge.net"/>
-  <person id="GS"  name="Glen Stampoultzis"  email="gstamp@iprimus.com.au"/>  
+  <person id="GS"  name="Glen Stampoultzis"  email="gstamp@iprimus.com.au"/>
   <person id="MJ"  name="Marc Johnson"       email="mjohnson at apache dot org"/>
   <person id="NKB" name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
   <person id="open" name="Poi Developers"    email="poi-dev@jakarta.apache.org"/>
@@ -15,14 +15,39 @@
 
  <actions priority="high">
   <action context="code" assigned-to="NKB">
-    do it
+    Finish HDF
+  </action>
+  <action context="code" assigned-to="NKB">
+    Finish Charts
+  </action>
+  <action context="code">
+    Add Formulas.
   </action>
 
  </actions>
 
  <actions priority="medium">
   <action context="code">
-   do it
+	Expose functionality in low level records in higher level API
+  </action>
+  <action context="code">
+	Implement more record types (for other things ... not sure
+	what this will mean yet).
+  </action>
+  <action context="code">
+	Implement more record types (for other things ... not sure
+	what this will mean yet).
+  </action>
+  <action context="code">
+	Add more dummy checks (for when API user's do things they
+	&quot;can't&quot; do)
+  </action>
+  <action context="code">
+        Add support for embedded graphics and stuff like that.
+  </action>
+  <action context="code">
+	Create new adapter object for handling MulBlank, MulRk, Rk
+	records.
   </action>
  </actions>
 
diff --git a/src/documentation/xdocs/who.xml b/src/documentation/xdocs/who.xml
index 41c406df3b..1c632dac0e 100644
--- a/src/documentation/xdocs/who.xml
+++ b/src/documentation/xdocs/who.xml
@@ -43,12 +43,12 @@
       <li><link href="http://trilug.org/~acoliver">Andrew C. Oliver</link> (acoliver at apache dot org)</li>
       <li><link href="http://www.marcj.com">Marc Johnson</link> (mjohnson at apache dot org)</li>
       <li>Glen Stampoultzis (glens at apache.org)</li>
-      <li><link href="http://www.rainer-klute.de/">Rainer Klute</link> (klute at apache dot org)</li>      
+      <li><link href="http://www.rainer-klute.de/">Rainer Klute</link> (klute at apache dot org)</li>
+      <li>Nicola Ken Barozzi (barozzi at nicolaken dot com)</li>
     </ul>
   </s2>
   <s2 title="Developers">
     <ul>
-      <li>Nicola Ken Barozzi (barozzi at nicolaken dot com)</li>
       <li>Ryan Ackley (sackley at cfl dot rr dot com)</li>
     </ul>
   </s2>