edits and additions

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

src/documentation/xdocs/book.xml

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

src/documentation/xdocs/contrib.xml

@@ -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.
+   the CVS code repository.   Review the <link href="todo.html">todo</link> list and 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, 
-   (or perhaps you have noticed something that needs patching). Make the
+   generate a patch, and post to the dev mailing list. (Do not worry - the process is easy and
-   changes, do the testing, generate a patch, and post to the dev
+   explained below.)
-   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

src/documentation/xdocs/faq.xml

@@ -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>
+<!--    <note>This is a note.</note>-->
-      <li>
-        one
-      </li>
-      <li>
-        two
-      </li>
-      <li>
-        three
-      </li>
-    </ul>
-    <note>This is a note.</note>
   </answer>
+  <answer>
+    <p>
+      Soon, very soon.
+    </p>
+  </answer>
+
 </faq>
 
 </faqs>

src/documentation/xdocs/index.xml

@@ -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 
+      <p>
-            formats based on Microsoft's OLE 2 Compound Document Format (tm) to pure Java (tm). 
+      The POI project consists of APIs for manipulating various file formats
-           This includes all post-1997 MS Office (tm) 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
+		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
-you wish to signify your love or hate for acronyms, use POI or Poi to refer to the project respectively.  
+		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!

src/documentation/xdocs/poifs/index.xml

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