Apache
/
poi
mirror of https://github.com/apache/poi.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

edits and additions 

git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@352072 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Andrew C. Oliver 2002-02-01 17:25:00 +00:00
parent e8b42223fb
commit f8e3aa6179
5 changed files with 84 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
src/documentation/xdocs/book.xml
View File

@ -17,7 +17,6 @@
<menu-item label="Download" href="http://sourceforge.net/project/showfiles.php?group_id=32701"/>
<menu-item label="Design" href="plan/POI10Vision.html"/>
<menu-item label="Who we are" href="who.html"/>
<menu-item label="FAQ File" href="faq.html"/>
<menu-item label="Changes" href="changes.html"/>
<menu-item label="Todo" href="todo.html"/>
</menu>

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

@ -9,6 +9,7 @@
<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"/>
<person name="Andrew C. Oliver" email="acoliver@apache.org"/>
</authors>
</header>
@ -33,19 +34,18 @@
</p>
<p>You can get your local working copy of the
<link href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/POI">latest and
<link href="http://jakarta.apache.org/site/cvsindex.html">latest and
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 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.)
the CVS code repository. 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.)
</p>
<p>
Document writers are usually the most wanted people so if
you like to help but you're not familiar with the innermost technical details, don't worry:
we have work for you!
we have work for you! And we'll be very available to you for any questions!
</p>
</s1>
@ -68,7 +68,7 @@
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
You should have a strong "fluency" in Java and a basic understanding of
the POI architecture - don't just say "it should have XYZ" without reading anything first -
because chances are, someone's already thought of that feature!)</li>
<li>Packaging easy-to-install packages (such as RPMs) for the myriad of possible configurations out
@ -226,7 +226,10 @@
<code>build docs</code> process to find them. Do not expect POI
or the build system to detect the validation errors for you - they can
do it, but that is not their purpose. (Anyway, nsgmls validation error
messages are more informative.)
messages are more informative.). Andy wishes it to be known he uses
<link href="http://www.sourceforge.net/projects/jedit">jEdit</link>. For
his XML editing. (That is when he's not hacking it in 'vi' the true editor
and light of the text editing world!).
</li>
<li>
Remember that most people are participating in development on a

29
src/documentation/xdocs/faq.xml
View File

@ -4,25 +4,26 @@
<faqs title="Frequently Asked Questions">
<faq>
<question>
Why does nothing happen?
What is the HSSF "eventmodel"?
</question>
<question>
When will all the documentation be ported to the new site?
</question>
<answer>
<p>
You might want to check a few things:
The HSSF eventmodel package is a new API for reading XLS files more efficiently. It does
require more knowledge on the part of the user, but reduces memory consumption by more than
tenfold. It is based on the AWT event model in combination with SAX. If you need read-only
access to a given XLS file, this is the best way to do it.
</p>
<ul>
<li>
one
</li>
<li>
two
</li>
<li>
three
</li>
</ul>
<note>This is a note.</note>
<!-- <note>This is a note.</note>-->
</answer>
<answer>
<p>
Soon, very soon.
</p>
</answer>
</faq>
</faqs>

44
src/documentation/xdocs/index.xml
View File

@ -11,9 +11,13 @@
<body>
<s1 title="Purpose">
<p>The POI project aims to provide both the framework for porting and actual ports of file
formats based on Microsoft's OLE 2 Compound Document Format (tm) to pure Java (tm).
This includes all post-1997 MS Office (tm) file formats.
<p>
The POI project consists of APIs for manipulating various file formats
based upon Microsoft's OLE 2 Compound Document format using pure Java.
</p>
<p>
OLE 2 Compound Document Format based files include most Microsoft Office
files such as XLS and DOC.
</p>
<p>
As a general policy we try to collaborate as much as possible with other projects to
@ -25,29 +29,39 @@
</p>
<s2 title="Why/when would I use POI">
<p>
We'll tackle this on a component level. POI refers to the whole project.
We'll tackle this on a component level. POI refers to the whole project.
</p>
<p>
So why should you use POIFS or HSSF?
So why should you use POIFS or HSSF?
</p>
<p>
You'd use POIFS if you had a document written in OLE 2 Compound Document Format, probably written using MFC, that you needed to read in Java. Alternatively, you'd use POI to write OLE 2 Compound Document Format if you needed to inter-operate with software running on the Windows platform. We are not just bragging when we say that POIFS is the most complete and correct port of this file format to date!
You'd use POIFS if you had a document written in OLE 2 Compound Document Format, probably written using
MFC, that you needed to read in Java. Alternatively, you'd use POI to write OLE 2 Compound Document Format
if you needed to inter-operate with software running on the Windows platform. We are not just bragging when
we say that POIFS is the most complete and correct port of this file format to date!
</p>
<p>
You'd use HSSF if you needed to read or write an XLS (Excel) file using Java. You can also read and modify spreadsheets using this API, although right now writing is more mature.
You'd use HSSF if you needed to read or write an XLS (Excel) file using Java. You can also read and modify
spreadsheets using this API, although right now writing is more mature.
</p>
</s2>
<s2 title="What does POI stand for?">
<p>
POI stands for Poor Obfuscation Implementation. Why would we name our project such a derogatory name? Well, Microsoft's OLE 2 Compound Document Format is a poorly conceived thing. It is essentially an archive structured much like the old DOS FAT filesystem. Redmond chose, instead of using tar, gzip, zip or arc, to invent their own archive format that does not provide any standard encryption or compression, is not very appendable and is prone to fragmentation.
POI stands for Poor Obfuscation Implementation. Why would we name our project such a derogatory name? Well,
Microsoft's OLE 2 Compound Document Format is a poorly conceived thing. It is essentially an archive structured
much like the old DOS FAT filesystem. Redmond chose, instead of using tar, gzip, zip or arc, to invent their own
archive format that does not provide any standard encryption or compression, is not very appendable and is prone
to fragmentation.
</p>
<p>
Poi is also a Hawaiian delicacy that <link href="http://www.m-w.com">Merriam Webster's dictionary</link> defines as: "A Hawaiian food of taro root cooked, pounded, and kneaded to a paste and often allowed to ferment." This seemed strangely descriptive of the file format.
Poi is also a Hawaiian delicacy that <link href="http://www.m-w.com">Merriam Webster's dictionary</link> defines as:
"A Hawaiian food of taro root cooked, pounded, and kneaded to a paste and often allowed to ferment." This seemed
strangely descriptive of the file format.
</p>
<p>
So if you like acronyms, then POI is an acronym. If you hate them, then we just used the name of the food for our project. If
you wish to signify your love or hate for acronyms, use POI or Poi to refer to the project respectively.
So if you like acronyms, then POI is an acronym. If you hate them, then we just used the name of the food for our
project. If you wish to signify your love or hate for acronyms, use POI or Poi to refer to the project respectively.
</p>
</s2>
@ -84,7 +98,13 @@ you wish to signify your love or hate for acronyms, use POI or Poi to refer to t
</s1>
<s1 title="Contributing ">
<p>So you'd like to contribute to the project? Great! We need enthusiastic, hard-working, talented folks to help us on the project in several areas. The first is bug reports and feature requests! The second is documentation - we'll be at your every beck and call if you've got a critique or you'd like to contribute or otherwise improve the documentation. We could especially use some help documenting the HSSF file format! Last, but not least, we could use some binary crunching Java coders to chew through the convolution that characterizes Microsoft's file formats and help us port new ones to a superior Java platform!
<p>
So you'd like to contribute to the project? Great! We need enthusiastic, hard-working, talented folks to help
us on the project in several areas. The first is bug reports and feature requests! The second is documentation -
we'll be at your every beck and call if you've got a critique or you'd like to contribute or otherwise improve
the documentation. We could especially use some help documenting the HSSF file format! Last, but not least, we
could use some binary crunching Java coders to chew through the convolution that characterizes Microsoft's file
formats and help us port new ones to a superior Java platform!
</p>
<p>So if you're motivated, ready, and have the time, join the mail lists and we'll be happy to help you get started on the
project!

24
src/documentation/xdocs/poifs/index.xml
View File

@ -15,6 +15,30 @@
<s1 title="Overview">
<p>POIFS is a pure Java implementation of the OLE 2 Compound Document format.</p>
<p>
By very definition, all APIs developed by the POI project are based somehow
on the POIFS API.
</p>
<p>
A common confusion is on just what POIFS buys you or what OLE 2 Compound
Document format IS exactly. POIFS does not buy you DOC, or XLS
but is necessary to generate DOCs or XLS files. You see all file
formats based on the OLE 2 Compound Document Format have a common
structure. The OLE 2 Compound Document Format is essentially a
convoluted archive format. Think of POIFS as a "zip" library. So once
you can get at the data in a zip file you still need to interperate the
data. As a general rule, while all of our formats USE POIFS, most of
them attempt to abstract you from it. There are some circumstances
where this is not possible, but as a general rule this is ture.
</p>
<p>
If you're an enduser type just looking to generate XLS files, then you'd
be looking for HSSF not POIFS; however, if you have legacy code that
uses MFC property sets. POIFS is for you! Regarless, you may or may
not need to know how to use POIFS but ultimately if you use technologies
that come from the POI project, you're using POIFS underneith. Perhaps
we should have a branding campaign "POIFS Inside!". ;-)
</p>
<p> TODO: copy POIFS docs and port to XML. For now please reference <link href="http://poi.sourceforge.net">old site</link>.
</p>
</s1>