From 6dbd4cdc6b5226609420066ad0739fce3230072a Mon Sep 17 00:00:00 2001 From: Glen Stampoultzis Date: Fri, 29 Mar 2002 11:06:05 +0000 Subject: [PATCH] Documentation updates git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@352295 13f79535-47bb-0310-9956-ffa450edef68 --- src/documentation/xdocs/changes.xml | 95 ++++++++-- src/documentation/xdocs/hssf/how-to.xml | 187 +++++-------------- src/documentation/xdocs/livesites.xml | 53 +++--- src/documentation/xdocs/plan/POI10Vision.xml | 4 +- src/documentation/xdocs/plan/POI20Vision.xml | 6 +- src/documentation/xdocs/todo.xml | 33 +++- src/documentation/xdocs/who.xml | 4 +- 7 files changed, 188 insertions(+), 194 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 @@ - + - - - - - - - - - - - New project build. - - - New project documentation system based on Cocoon. - - + + + + + + + + + + New project build. + New project documentation system based on Cocoon. + Package rename + Various bug fixes + Early stages of HSF development (not ready for development) + Initial low level record support for charting (not complete) + + + Created new event model + Optimizations made to HSSF including aggregate records for + values, rows, etc. + predictive sizing, offset based writing (instead of lots of + array copies) + minor re-factoring and bug fixes. + + + Minor documentation updates. + + + Added DataFormat helper class and exposed set and get format + on HSSFCellStyle + Fixed column width apis (unit wise) and various javadoc on + the subject + Fix for Dimensions record (again)... (one of these days I'll + write a unit test for this ;-p). + Some optimization on sheet creation. + + + + + + Added MulBlank, Blank, ColInfo + Added log4j facility and removed all sys.out type logging + Added support for adding font's, styles and corresponding + high level api for styling cells + added support for changing row height, cell width and default + row height/cell width. + Added fixes for internationalization (UTF-16 should work now + from HSSFCell.setStringValue, etc when the encoding is set) + added support for adding/removing and naming sheets. + + + Bugfix release. We were throwing an exception when reading + RKRecord objects. + + + Got continuation records to work (read/write) + Added various pre-support for formulas + Massive API reorganization, repackaging. + BiffViewer class added for validating HSSF & POI and/or + HSSF Output. + Better API support for modification. + + + Added encoding flag to high and low level api to use utf-16 + when needed (HSSFCell.setEncoding()) + added read only support for Label records (which are + reinterpreted as LabelSST when written) + Broken continuation record implementation (oops) + BiffViewer class added for validating HSSF & POI and/or + HSSF Output. + + + Support for read/write and modify. + Read only support for MulRK records (converted to Number when + writing) + + 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 @@ -

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 +

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.

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.

@@ -57,10 +58,8 @@ org.apache.poi.hssf.usermodel.HSSFWorkbook.

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,"SheetName").

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.

An example of this can be seen in -org.apache.poi.hssf.dev.HSSF.

+org.apache.poi.hssf.dev.HSSF.

@@ -438,34 +437,46 @@ most likely fail. No big deal. -

HSSF now has a logging facility (using log4j - thanks jakarta!) +

HSSF now has a logging facility (using + commons logging) 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 "/" -(or "\\" 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.

-

Here is an example hssflog.properties (actually its not an example -its mine): -# 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

- +down problems. +

+

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) +

+

Here's the problem, as I see it. +

+

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. +

+

+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. +

+

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. +

+

+Refer to the commons logging package level javadoc for more information concerning how to +configure commons logging. +

 @@ -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?

-

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 "gut" feeling is to aim for -around March and have at least the first three items.

-

Current list of priorities:

-
    -
  1. Helper class for fonts, etc.
    2. -
  2. Add Formulas.
    3. -
  3. Implement more record types (for other things ... not sure - what this will mean yet).
    4. -
  4. Add more dummy checks (for when API user's do things they - "can't" do)
    5. -
  5. Add support for embedded graphics and stuff like that.
    6. -
  6. Create new adapter object for handling MulBlank, MulRk, Rk - records.
    7. -
 - - -
    -
  1. Created new event model
    2. -
  2. Optimizations made to HSSF including aggregate records for - values, rows, etc.
    3. -
  3. predictive sizing, offset based writing (instead of lots of - array copies)
    4. -
  4. minor re-factoring and bug fixes.
    5. -
- - - -
    -
  1. Minor documentation updates.
    2. -
- - -
    -
      -
    1. Added DataFormat helper class and exposed set and get format - on HSSFCellStyle
      2. -
    2. Fixed column width apis (unit wise) and various javadoc on - the subject
      3. -
    3. Fix for Dimensions record (again)... (one of these days I'll - write a unit test for this ;-p).
      4. -
    4. Some optimization on sheet creation.
      5. -
    -
- - -

- NO WAY!

- - -
    -
  1. Added MulBlank, Blank, ColInfo
    2. -
  2. Added log4j facility and removed all sys.out type logging
    3. -
  3. Added support for adding font's, styles and corresponding - high level api for styling cells
    4. -
  4. added support for changing row height, cell width and default - row height/cell width.
    5. -
  5. Added fixes for internationalization (UTF-16 should work now - from HSSFCell.setStringValue, etc when the encoding is set)
    6. -
  6. added support for adding/removing and naming sheets.
    7. -
- - -
    -
  1. Bugfix release. We were throwing an exception when reading - RKRecord objects.
    2. -
- - -
    -
  1. Got continuation records to work (read/write)
    2. -
  2. Added various pre-support for formulas
    3. -
  3. Massive API reorganization, repackaging.
    4. -
  4. BiffViewer class added for validating HSSF & POI and/or - HSSF Output.
    5. -
  5. Better API support for modification.
    6. -
- - -
    -
  1. Added encoding flag to high and low level api to use utf-16 - when needed (HSSFCell.setEncoding())
    2. -
  2. added read only support for Label records (which are - reinterpreted as LabelSST when written)
    3. -
  3. Broken continuation record implementation (oops)
    4. -
  4. BiffViewer class added for validating HSSF & POI and/or - HSSF Output.
    5. -
- - -
    -
  1. Support for read/write and modify.
    2. -
  2. Read only support for MulRK records (converted to Number when - writing) -
    3. -
- - 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 @@ -
- Live Sites using Poi - - - - - - -
- - -

Here is a list of some of the web sites that are proudly using Poi 1.X (in no particular order): -

- -

- If you do not find your site here, make sure you tell us - (use the word "Livesites" 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 :-) -

- - +
+ Live Sites using Poi + + + + + + + +
+ + + +

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. +

+ + + 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.

  1. @@ -110,7 +110,7 @@
  2. 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.
    3. 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.

    This document was created before the POI components for @@ -275,10 +275,10 @@ 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 @@ - + - + @@ -15,14 +15,39 @@ - do it + Finish HDF + + + Finish Charts + + + Add Formulas. - do it + Expose functionality in low level records in higher level API + + + Implement more record types (for other things ... not sure + what this will mean yet). + + + Implement more record types (for other things ... not sure + what this will mean yet). + + + Add more dummy checks (for when API user's do things they + "can't" do) + + + Add support for embedded graphics and stuff like that. + + + Create new adapter object for handling MulBlank, MulRk, Rk + records. 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 @@
  3. Andrew C. Oliver (acoliver at apache dot org)
  4. Marc Johnson (mjohnson at apache dot org)
  5. Glen Stampoultzis (glens at apache.org)
    6. -
  6. Rainer Klute (klute at apache dot org)
    7. +
  7. Rainer Klute (klute at apache dot org)
    8. +
  8. Nicola Ken Barozzi (barozzi at nicolaken dot com)
      9. -
    • Nicola Ken Barozzi (barozzi at nicolaken dot com)
    • Ryan Ackley (sackley at cfl dot rr dot com)
    - Benefit + Benefit - Supporting Features + Supporting Features