moparisthebest/poi
1
0
Fork 0
Code Issues Pull Requests Releases 1 Wiki Activity

minor (mostly) documentation cleanup

Browse Source 
git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@352069 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
mjohnson 2002-02-01 02:01:24 +00:00
parent 6fb358b88d
commit a71653a954
8 changed files with 176 additions and 110 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
src/documentation/xdocs/changes.xml
View File

@ -8,7 +8,7 @@
<!-- 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 at apache dot org"/>
<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-devel@lists.sourceforge.net"/>
</devs>

51
src/documentation/xdocs/contrib.xml
View File

@ -8,6 +8,7 @@
<person name="Robin Green" email="greenrd@hotmail.com"/>
<person name="Stefano Mazzocchi" email="stefano@apache.org"/>
<person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
<person name="Marc Johnson" email="mjohnson@apache.org"/>
</authors>
</header>
@ -20,22 +21,22 @@
volunteer project released under a very open license.
This means there are many ways to contribute to the project - either
with direct participation (coding, documenting, answering questions,
proposing ideas, reporting bugs, suggesting bug-fixes, etc..) or by resource
proposing ideas, reporting bugs, suggesting bug fixes, etc. ...) or by resource
donations (money, time, publicity, hardware, software, conference
presentations, speeches, etc...).
presentations, speeches, etc. ...).
</p>
<p>
To begin with, we suggest you to subscribe to the
To begin with, we suggest you subscribe to the
<link href="mail-lists.html">POI mailing lists</link>
(follow the link for information on how to subscribe and to access the mail
list archives). Listen-in for a while, to hear how others make contibutions.
list archives). Listen in for a while, to hear how others make contributions.
</p>
<p>You can get your local working copy of the
<link href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/POI">latest and
greatest code</link> (which you find in the POI module in
greatest code</link> (which you find in the jakarta-poi module in
the CVS code repository.
Review the <link href="todo.html">todo</link> list, choose a task
Review the <link href="todo.html">todo</link> list and choose a task
(or perhaps you have noticed something that needs patching). Make the
changes, do the testing, generate a patch, and post to the dev
mailing list. (Do not worry - the process is easy and explained below.)
@ -60,11 +61,11 @@
having too many questioners and not enough experts to respond to all the questions.</li>
<li>Testing POI (especially its less-frequently-used features) on various configurations
and reporting back.</li>
<li>Debugging - producing reproduceable test cases and/or finding causes of bugs. Some known bugs are informally listed on
<li>Debugging - producing reproducible test cases and/or finding causes of bugs. Some known bugs are informally listed on
<link href="todo.html">To Do</link>, and some are recorded in Bugzilla
(see <link href="#procedure">explanation below</link>).</li>
<li>Specifying/analysing/designing new features - and beyond. (If you wish to get involved
with this, please join <code>general POI mailing list</code>
<li>Specifying/analyzing/designing new features - and beyond. (If you wish to get involved
with this, please join the <code>general POI mailing list</code>
, install and try out POI
and read some of the <link href="mail-lists.html">mail archives</link>.
You should have a strong "fluency" in XML technologies, Java and a basic understanding of
@ -86,8 +87,8 @@
<s1 title="CVS Usage Precis">
<p>An overview of how to use CVS to participate in POI development.
Do not be afraid - you cannot accidently destroy the actual code repository,
because you are working with a local copy as an anonymous user. Therefore,
you do not have the system permissions to change anything. You can only
because you are working with a local copy as an anonymous user.
You do not have the system permissions to change anything. You can only
update your local repository and compare your revisions with the real
repository.
</p>
@ -134,7 +135,7 @@
is appropriate for a certain situation and how to go about it without
confusion. This section explains when to use the
<code>developer</code> <link href="mail-lists.html">mailing list</link>
the bug database.
and the bug database.
</p>
<p>
@ -155,9 +156,9 @@
Experienced developers use Bugzilla directly, as they are very sure
when they have found a bug and when not. However, less experienced users
should first discuss it on the user or developer mailing list (as
appropriate). Impatient people always enter everything into Bugzilla
without caring if it is a bug of POI or their own
installation/configuration mistake - please do not do this.
appropriate). Impatient people frequently enter everything into Bugzilla
without caring if it is a bug in POI or their own
installation/configuration mistake - please, do not do this.
</p>
<p>
@ -168,8 +169,8 @@
</p>
<p>
Perhaps you do not get any answer on your first reply, so just post
it again until you get one. (But please not every hour - allow a few
If you do not get any answer on your first attempt, post
your issue again until you get a reply. (But, please, not every hour - allow a few
days for the list to deal with it.) Do not be impatient - remember that
the whole world is busy, not just you. Bear in mind that other countries
will have holidays at different times to your country and that they are
@ -193,27 +194,27 @@
</li>
<li>
Use sensible and concise email subject headings. Search engines, and
humans trying to browse a voluminous list, will respond favourably to a
humans trying to browse a voluminous list, will respond favorably to a
descriptive title.
</li>
<li>Start new threads with new Subject for new topics, rather than
<li>Start new threads with new Subjects for new topics, rather than
re-using the previous Subject line.
</li>
<li>Keep each topic focussed. If some new topic arises then start a new
<li>Keep each topic focussed. If some new topic arises, start a new
discussion. This leaves the original topic to continue un-cluttered.
</li>
<li>Whenever you decide to start a new topic, then start with a fresh
new email message window. Do not use the &quot;Reply to&quot; button,
because threaded mail-readers get confused (they utilise the
<code>In-reply-to</code> header). If so, then your new topic will get
because threaded mail-readers get confused (they use the
<code>In-reply-to</code> header). Otherwise, your new topic will get
lost in the previous thread and go un-answered.
</li>
<li>
Prepend your email subject line with a marker when that is appropriate,
e.g. <code>[Patch]</code>, <code>[Proposal]</code>,
<code>[RT]</code> (Random Thought which quickly blossom into research
<code>[RT]</code> (Random Thought, these quickly blossom into research
topics :-), <code>[STATUS]</code> (development status of a certain
facility).
feature).
</li>
<li>
When making changes to XML documentation, or any XML document for that
@ -262,7 +263,7 @@
If an issue starts to get bogged down in list discussion, then it may
be appropriate to go into private off-list discussion with a few interested
other people. Spare the list from the gory details. Report a summary back
to the list to finalise the thread.
to the list to finalize the thread.
</li>
<li>
Become familiar with the mailing lists. As you browse and search, you will

110
src/documentation/xdocs/historyandfuture.xml
View File

@ -14,50 +14,112 @@
<s1 title="Brief Project History">
<p>The POI project was dreamed up back around April 2001, when Andy Oliver landed a short term contract to do Java-based reporting to Excel. He'd done this project a few times before and knew right were to look for the tools He needed. Ironically the API he used to use had skyrocketed from around $300 ($US) to around $10K ($US). He figured it would take two people around six months to write an Excel port so he recommended the client fork out the $10K.
<p>The POI project was dreamed up back around April 2001, when
Andy Oliver landed a short term contract to do Java-based
reporting to Excel. He'd done this project a few times before
and knew right where to look for the tools he needed.
Ironically, the API he used to use had skyrocketed from around
$300 ($US) to around $10K ($US). He figured it would take two
people around six months to write an Excel port so he
recommended the client fork out the $10K.
</p>
<p>Around July, he started thinking how great it would be to have an open source Java tool to do this and, while he had some spare time, he started on the project and learned about OLE 2 Compound Document Format. After hitting some real stumpers he realized he'd need help. He posted a message to his local Java User's Group (JUG) and asked if anyone else would be interested. He lucked out and the most talented Java programmer he'd ever met, Marc Johnson, joined the project. He ran rings around Andy at porting OLE 2 CDF and rewrote his skeletal code into a more sophisticated library. It took Marc a few iterations to get something they were happy with.
<p>Around June 2001, Andy started thinking how great it would
be to have an open source Java tool to do this and, while he
had some spare time, he started on the project and learned
about OLE 2 Compound Document Format. After hitting some real
stumpers he realized he'd need help. He posted a message to
his local Java User's Group (JUG) and asked if anyone else
would be interested. He lucked out and the most talented Java
programmer he'd ever met, Marc Johnson, joined the project. He
ran rings around Andy at porting OLE 2 CDF and rewrote his
skeletal code into a more sophisticated library. It took Marc
a few iterations to get something they were happy with.
</p>
<p>While Marc worked on that, Andy ported XLS to Java, based on Marc's library. Several users wrote in asking to read XLS (not just write as had originally been scoped) and one user had special requests for a different use for POIFS. Before long the project scope had tripled. POI 1.0 was released a month late, but with far more features. Marc quickly wrote the serializer framework and HSSF Serializer in record time and Andy banged out more documentation and worked on making people aware of the project
<p>While Marc worked on that, Andy ported XLS to Java, based
on Marc's library. Several users wrote in asking to read XLS
(not just write as had originally been planned) and one user
had special requests for a different use for POIFS. Before
long, the project scope had tripled. POI 1.0 was released a
month later than planned, but with far more features. Marc
quickly wrote the serializer framework and HSSF Serializer in
record time and Andy banged out more documentation and worked
on making people aware of the project
</p>
<p>
Shortly before the release POI was fortunate to come into contact with Nicola -Ken- Barrozzi who gave them samples
for the HSSF Serializer and help uncover its unfortunate bugs (which were promptly fixed). More recently Ken ported most of the
POI project documentation to XML from Andy's crappy HTML docs he wrote with Star Office :-p.
<p> Shortly before the release, POI was fortunate to come into
contact with Nicola -Ken- Barrozzi who gave them samples for
the HSSF Serializer and help uncover its unfortunate bugs
(which were promptly fixed). More recently, Ken ported most
of the POI project documentation to XML from Andy's crappy
HTML docs he wrote with Star Office.
</p>
<p>
Around the same time as the release, Glen Stampoultzis joined the project. Glen was ticked off at Andy's flippant
attitude towards adding graphing to HSSF. Glen got so ticked off he decided to gab a hammer and do it himself. Glen has
already become an integral part of the POI development community, his contributions to HSSF have already started making waves.
<p> Around the same time as the release, Glen Stampoultzis
joined the project. Glen was ticked off at Andy's flippant attitude
towards adding graphing to HSSF. Glen got so ticked off he decided to
grab a hammer and do it himself. Glen has already become an integral
part of the POI development community; his contributions to HSSF have
already started making waves.
</p>
<p>
Somewhere in there we decided to finally submit the project to
<link href="http://xml.apache.org/cocoon">The Apache Cocoon Project</link> only to discover the project had outgrown
fitting nicely into just Cocoon long ago. Furthermore, Andy started eyeing other projects he'd like to see POI
functionality added to. So it was decided to donate the Serializers and Generators to Cocoon, other POI integration
components to other projects, and the POI APIs would become part of Jakarta. It was a bumpy road but it looks like
everything turned out since you're reading this!
<p>Somewhere in there we decided to finally submit the project
to <link href="http://xml.apache.org/cocoon">The Apache
Cocoon Project</link>, only to discover the project had
outgrown fitting nicely into just Cocoon long ago.
Furthermore, Andy started eyeing other projects he'd like to
see POI functionality added to. So it was decided to donate
the Serializers and Generators to Cocoon, other POI
integration components to other projects, and the POI APIs
would become part of Jakarta. It was a bumpy road but it
looks like everything turned out since you're reading this!
</p>
</s1>
<s1 title="What's next for POI">
<p>First we'll tackle this from a project standpoint: Well, we made an offer to Microsoft and Actuate (tongue in cheek ... well mostly) that we'd quit the project and retire if they'd simply write us each a really large check. I've yet to get a phone call or email so I'm assuming they're not going to pay us to go away.
<p>First we'll tackle this from a project standpoint: Well, we
made an offer to Microsoft and Actuate (tongue in cheek
... well mostly) that we'd quit the project and retire if
they'd simply write us each a really large check. I've yet to
get a phone call or email so I'm assuming they're not going to
pay us to go away.
</p>
<p>Next, we've got some work to do here at Jakarta to finish integrating POI into the community. Furthermore, we're
<p>Next, we've got some work to do here at Jakarta to finish
integrating POI into the community. Furthermore, we're
still transitioning the Serializer to Cocoon.
</p>
<p>HSSF, during the 2.0 cycle, will undergo a few optimizations. We'll also be adding new features like a full implementation of Formulas and custom text formats. We're hoping to be able to generate smaller files by adding write-support for RK, MulRK and MulBlank records. I'm also going to work on a Cocoon 2 Generator. Currently, reading is not very efficient in HSSF. This is mainly because in order to write or modify, one needs to be able to update upstream pointers to downstream data. To do this you have to have everything between in memory. A Generator would allow SAX events to be processed instead. (This will be based on the low level structures). One of the great things about this is that, you'll not only have a more efficient way to read the file, you'll have a great way to use spreadsheets as XML data sources.
<p>HSSF, during the 2.0 cycle, will undergo a few
optimizations. We'll also be adding new features like a full
implementation of Formulas and custom text formats. We're
hoping to be able to generate smaller files by adding
write-support for RK, MulRK and MulBlank records. I'm also
going to work on a Cocoon 2 Generator. Currently, reading is
not very efficient in HSSF. This is mainly because in order to
write or modify, one needs to be able to update upstream
pointers to downstream data. To do this you have to have
everything between in memory. A Generator would allow SAX
events to be processed instead. (This will be based on the low
level structures). One of the great things about this is that,
you'll not only have a more efficient way to read the file,
you'll have a great way to use spreadsheets as XML data
sources.
</p>
<p>The HSSF Serializer, will further separate into a general framework for creating serializers for other formats and the HSSF Serializer specific implementation. (This is largely already true). We'll also be adding support for features already supported by HSSF (styles, fonts, text formats). We're hoping to add support for formulas during this cycle.
<p>The HSSF Serializer, will further separate into a general
framework for creating serializers for other formats and the
HSSF Serializer specific implementation. (This is largely
already true). We'll also be adding support for features
already supported by HSSF (styles, fonts, text formats). We're
hoping to add support for formulas during this cycle.
</p>
<p>We're beginning to expand our scope yet again. If we could do all of this for XLS files, what about Doc files or PPT files? We're thinking that our next component (HDF - Horrible Document Format) should follow the same pattern. We're hoping that new blood will join the team and allow us to tackle this even faster (in part because POIFS is already finished). But maybe what we need most is you!
</p>
<p>We're beginning to expand our scope yet again. If we could
do all of this for XLS files, what about Doc files or PPT
files? We're thinking that our next component (HDF - Horrible
Document Format) should follow the same pattern. We're hoping
that new blood will join the team and allow us to tackle this
even faster (in part because POIFS is already finished). But
maybe what we need most is you! </p>
</s1>
</body>

48
src/documentation/xdocs/hssf/how-to.xml
View File

@ -20,7 +20,7 @@
<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 the
development build of HSSF. 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>
@ -60,7 +60,7 @@ 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
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
@ -77,7 +77,7 @@ HSSFCell.CELL_TYPE_NUMERIC or HSSFCell.CELL_TYPE_STRING depending on
whether they contain a numeric or textual value. Cells must also have
a value set. Set the value by calling setCellValue with either a
String or double as a parameter. Individual cells do not have a
width, you must call setColumnWidth(colindex, width) (use units of
width; you must call setColumnWidth(colindex, width) (use units of
1/256th of a character) on the HSSFSheet object. (You can't do it on
an individual basis in the GUI either).</p>
<p>Cells are styled with HSSFCellStyle objects which in turn contain
@ -89,7 +89,7 @@ setFont(fontobj).
</p>
<p>Once you have generated your workbook, you can write it out by
calling write(outputStream) from your instance of Workbook, passing
it an OutputStream (for instance a FileOutputStream or
it an OutputStream (for instance, a FileOutputStream or
ServletOutputStream). You must close the OutputStream yourself. HSSF
does not close it for you.
</p>
@ -191,9 +191,9 @@ org.apache.poi.hssf.dev.HSSF test class):</p>
</s4>
<s4 title="Reading or modifying an existing file">
<p>Reading in a file is equally simple. To read in a file create a
new instance of org.apache.poi.poifs.Filesystem passing in the
filename of your XLS to the constructor. Construct a new instance of
<p>Reading in a file is equally simple. To read in a file, create a
new instance of org.apache.poi.poifs.Filesystem, passing in an open InputStream, such as a FileInputStream
for your XLS, to the constructor. Construct a new instance of
org.apache.poi.hssf.usermodel.HSSFWorkbook passing the
Filesystem instance to the constructor. From there you have access to
all of the high level model objects through their assessor methods
@ -218,7 +218,7 @@ learn). The advantage provided is that you can read an XLS with a
relatively small memory footprint.
</p>
<p>To use this API you construct an instance of
org.apache.poi.hssf.eventmodel.HSSFRequest register a class you
org.apache.poi.hssf.eventmodel.HSSFRequest. Register a class you
create that supports the
org.apache.poi.hssf.eventmodel.HSSFListener interface using the
HSSFRequest.addListener(yourlistener, recordsid). The recordsid
@ -226,20 +226,20 @@ should be a static reference number (such as BOFRecord.sid) contained
in the classes in org.apache.poi.hssf.record. The trick is you
have to know what these records are. Alternatively you can call
HSSFRequest.addListenerForAllRecords(mylistener). In order to learn
about these records you can either all of the javadoc in the
about these records you can either read all of the javadoc in the
org.apache.poi.hssf.record package or you can just hack up a
copy of org.apache.poi.hssf.dev.EFHSSF and adapt it to your
needs. TODO: better documentation on records.</p>
<p>Once you've registered your listeners in the HSSFRequest object
you can construct an instance of
org.apache.poi.poifs.filesystem.Filesystem (see POIFS howto) and
pass it your XLS file inputstream. You can either pass this along
with the request you constructed to an instance of HSSFEventFactory
org.apache.poi.poifs.filesystem.FileSystem (see POIFS howto) and
pass it your XLS file inputstream. You can either pass this, along
with the request you constructed, to an instance of HSSFEventFactory
via the HSSFEventFactory.processWorkbookEvents(request, Filesystem)
method or you can get an instance of DocumentInputStream from
method, or you can get an instance of DocumentInputStream from
Filesystem.createDocumentInputStream(&quot;Workbook&quot;) and pass
it to HSSFEventFactory.processEvents(request, inputStream). Once you
make this call the listeners that you constructed receive calls to
make this call, the listeners that you constructed receive calls to
their processRecord(Record) methods with each Record they are
registered to listen for until the file has been completely read.
</p>
@ -342,7 +342,7 @@ level API (and indirectly the low level support). The main body of
its code is repeated above. To run it:
</p>
<ul>
<li>download the poi-alpha build untar it (tar xvzf
<li>download the poi-alpha build and untar it (tar xvzf
tarball.tar.gz)
</li>
<li>set up your classpath as follows:
@ -356,7 +356,7 @@ export CLASSPATH=$CLASSPATH:$HSSFDIR/hssf.jar:$HSSFDIR/poi-poifs.jar:$HSSFDIR/po
<ul>
<li>Type:
<code>java org.apache.poi.hssf.dev.HSSF ~/input.xls output.xls
This is the read/write/modify test. It reads in the spreadsheet modifies a cell and writes it back out. Failing this test is not necessarily a bad thing. If HSSF tries to modify a non-existant sheet then this will most likely fail. Such is no big deal. </code></li>
This is the read/write/modify test. It reads in the spreadsheet, modifies a cell, and writes it back out. Failing this test is not necessarily a bad thing. If HSSF tries to modify a non-existant sheet then this will most likely fail. No big deal. </code></li>
</ul>
</s3>
<s3 title="HSSF Logging facility">
@ -364,7 +364,7 @@ This is the read/write/modify test. It reads in the spreadsheet modifies a cell
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
massive performance degradation when fully turned on! Using it is
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
@ -391,7 +391,7 @@ log4j.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n
</s3>
<s3 title="HSSF Developer's tools">
<p>HSSF has a number of tools useful for developer's to debug/develop
<p>HSSF has a number of tools useful for developers to debug/develop
stuff using HSSF (and more generally XLS files). We've already
discussed the app for testing HSSF read/write/modify capabilities;
now we'll talk a bit about BiffViewer. Early on in the development of
@ -407,8 +407,8 @@ you're doing enough to be thinking about this) with an xls file as a
parameter. It will give you a listing of all understood records with
their data and a list of not-yet-understood records with no data
(because it doesn't know how to interpret them). This listing is
useful for several things. For one you can look at the values and SEE
what is wrong in quasi-English. For two, you can send the output to a
useful for several things. First, you can look at the values and SEE
what is wrong in quasi-English. Second, you can send the output to a
file and compare it.
</p>
<p>The second function is &quot;big freakin dump&quot;, just pass a
@ -435,8 +435,8 @@ European languages for our first beta. We're more than happy to
accept help in supporting non-Western European languages if someone
who knows what they're doing in this area is willing to pitch in!
(There is next to no documentation on what is necessary to support
such a move and its really hard to support a language you don't even
know the alphabet too).</p>
such a move and its really hard to support a language when you don't even
know the alphabet).</p>
<p>This release of HSSF does not yet support Formulas. I've been
focusing on the requests I've gotten in. That being said, if we get
more user feedback on what is most useful first we'll aim for that.
@ -448,14 +448,14 @@ are most important first?
<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 its way to early to say when the
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
<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>

50
src/documentation/xdocs/hssf/use-case.xml
View File

@ -3,7 +3,7 @@
<document>
<header>
<title>The New Halloween Document</title>
<title>HSSF Use Cases</title>
<authors>
<person email="marc.johnson@yahoo.com" name="Marc Johnson" id="MJ"/>
</authors>
@ -20,7 +20,7 @@
<li>HSSF client- wants to read content
of HSSF file</li>
<li>HSSF - understands HSSF file</li>
<li>POI - understands underlying POI
<li>POIFS - understands underlying POI
file system</li>
</ul>
<p><strong>Precondition:</strong> None</p>
@ -30,15 +30,15 @@
<li>HSSF client requests HSSF to read
a HSSF file, providing an InputStream
containing HSSF file in question.</li>
<li>HSSF requests POI to read the HSSF
<li>HSSF requests POIFS to read the HSSF
file, passing the InputStream
object to POI (POI use case 1, read existing file system)</li>
object to POIFS (POIFS use case 1, read existing file system)</li>
<li>HSSF reads the &quot;Workbook&quot;
file (use case 4, read workbook entry)</li>
</ol>
<p><strong>Extensions:</strong></p>
<p>2a. Exceptions
thrown by POI will be passed on to the HSSF client.</p>
thrown by POIFS will be passed on to the HSSF client.</p>
</s2>
<s2 title="Use Case 2: Write HSSF file">
@ -51,7 +51,7 @@ thrown by POI will be passed on to the HSSF client.</p>
out.</li>
<li>HSSF - knows how to write file
out.</li>
<li>POI - knows how to write file
<li>POIFS - knows how to write file
system out.</li>
</ul>
<p><strong>Precondition:</strong></p>
@ -67,15 +67,15 @@ thrown by POI will be passed on to the HSSF client.</p>
provides an OutputStream to
write the file to.</li>
<li>HSSF writes
the &quot;Workbook&quot; to its associated POI file system (use case
the &quot;Workbook&quot; to its associated POIFS file system (use case
5, write workbook entry)</li>
<li>HSSF
requests POI to write its file system out, using the OutputStream
obtained from the HSSF client (POI use case 2, write file system).</li>
requests POIFS to write its file system out, using the OutputStream
obtained from the HSSF client (POIFS use case 2, write file system).</li>
</ol>
<p><strong>Extensions:</strong></p>
<p>3a. Exceptions
from POI are passed to the HSSF client.</p>
from POIFS are passed to the HSSF client.</p>
</s2>
<s2 title="Use Case 3:Create HSSF file">
@ -90,7 +90,7 @@ from POI are passed to the HSSF client.</p>
file.</li>
<li>HSSF - knows how to create a new
file.</li>
<li>POI - knows how to creat a new
<li>POIFS - knows how to creat a new
file system.</li>
</ul>
<p><strong>Precondition:</strong></p>
@ -98,7 +98,7 @@ from POI are passed to the HSSF client.</p>
<p><strong>Main Success Guarantee:</strong></p>
<ol>
<li>HSSF requests
POI to create a new file system (POI use case 3, create new file
POIFS to create a new file system (POIFS use case 3, create new file
system)</li>
</ol>
<p><strong>Extensions:</strong>
@ -114,7 +114,7 @@ None</p>
<ul>
<li>HSSF - knows how to read the
workbook entry</li>
<li>POI - knows how to manage the file
<li>POIFS - knows how to manage the file
system.</li>
</ul>
<p><strong>Precondition:</strong></p>
@ -129,17 +129,17 @@ Guarantee:</strong> None</p>
<p><strong>Main Success Guarantee:</strong></p>
<ol>
<li>
HSSF requests POI for the &quot;Workbook&quot; file</li>
<li>POI returns
HSSF requests POIFS for the &quot;Workbook&quot; file</li>
<li>POIFS returns
an InputStream for the file.</li>
<li>HSSF reads
from the InputStream provided by POI</li>
from the InputStream provided by POIFS</li>
<li>HSSF closes
the InputStream provided by POI</li>
the InputStream provided by POIFS</li>
</ol>
<p><strong>Extensions:</strong></p>
<p>3a. Exceptions
thrown by POI will be passed on</p>
thrown by POIFS will be passed on</p>
</s2>
<s2 title="Use Case 5: Write workbook entry">
@ -152,7 +152,7 @@ thrown by POI will be passed on</p>
<ul>
<li>HSSF - knows how to manage the
write the workbook entry.</li>
<li>POI - knows how to manage the file
<li>POIFS - knows how to manage the file
system.</li>
</ul>
<p><strong>Precondition:</strong>
@ -166,12 +166,12 @@ thrown by POI will be passed on</p>
<p><strong>Main Success Guarantee:</strong></p>
<ol>
<li>HSSF
checks the POI file system directory for the &quot;Workbook&quot;
file (POI use case 8, read file system directory)</li>
<li>If &quot;Workbook&quot; is in the directory, HSSF requests POI to
replace it with the new workbook entry (POI use case 4, replace file
in file system). Otherwise, HSSF requests POI to write the new
workbook file, with the name &quot;Workbook&quot; (POI use case 6,
checks the POIFS file system directory for the &quot;Workbook&quot;
file (POIFS use case 8, read file system directory)</li>
<li>If &quot;Workbook&quot; is in the directory, HSSF requests POIFS to
replace it with the new workbook entry (POIFS use case 4, replace file
in file system). Otherwise, HSSF requests POIFS to write the new
workbook file, with the name &quot;Workbook&quot; (POIFS use case 6,
write new file to file system)</li>
</ol>
<p><strong>Extensions:</strong>None</p>

12
src/documentation/xdocs/mail-lists.xml
View File

@ -50,11 +50,13 @@
XSL tutorial at Zvon.org</link>) or try the
<link href="http://www.mulberrytech.com/xsl/">Mulberrytech XSL list</link>.</p>
<p><strong>IMPORTANT:</strong> If you are posting about a problem you are having
(as most people do), it will aid in finding a speedy resolution if you provide
full configuration details (especially the <strong>version number</strong>,
but also your operating system, JDK version, and servlet engine), and full details
of any errors encountered (including full error messages and stack traces).</p>
<p><strong>IMPORTANT:</strong> If you are posting about a problem
you are having (as most people do), it will aid in finding a
speedy resolution if you provide full configuration details
(especially the <strong>version number</strong>, but also your
operating system, JDK version, etc.), and full details of any
errors encountered (including full error messages and stack
traces).</p>
<p>Please also have some consideration for the other users on the list - this is a
busy list and we do not appreciate getting the exact same message posted impatiently

9
src/documentation/xdocs/overview.xml
View File

@ -11,10 +11,11 @@
<body>
<s1 title="What is it?">
<p>The POI project is the master project for developing pure Java ports of those
file formats based on Microsoft's OLE 2 Compound Document Format. OLE 2
Compound Document Format is by Microsoft Office Documents, as well as
programs using MFC property sets to serialize their document objects.
<p>The POI project is the master project for developing pure
Java ports of file formats based on Microsoft's OLE 2 Compound
Document Format. OLE 2 Compound Document Format is used by
Microsoft Office Documents, as well as by programs using MFC
property sets to serialize their document objects.
</p>
</s1>
<s1 title="Sub-Projects">

4
src/documentation/xdocs/who.xml
View File

@ -24,7 +24,7 @@
We ask that you please do not send us emails privately asking for support.
We are non-paid volunteers who help out with the project and we do not
necessarily have the time or energy to help people on an individual basis.
Instead, we have setup mailing lists which often contain hundreds of
Instead, we have set up mailing lists which often contain hundreds of
individuals who will help answer detailed requests for help. The benefit of
using mailing lists over private communication is that it is a shared
resource where others can also learn from common mistakes and as a
@ -41,7 +41,7 @@
<s2 title="Committers">
<ul>
<li><link href="http://trilug.org/~acoliver">Andrew C. Oliver</link> (acoliver at apache dot org)</li>
<li>Marc Johnson (mjohnson at apache dot org)</li>
<li><link href="http://www.marcj.com">Marc Johnson</link> (mjohnson at apache dot org)</li>
</ul>
</s2>
<s2 title="Developers">