- Compiling POI now includes the example classes.

- Javadoc now includes the example classes.
- Added usage instructions to the POI Browser documentation.
- Added references to the examples and the contributed software to the POI overview.
- Added a missing import to an HPSF example class.


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

3 files changed, 80 insertions, 3 deletions

diff --git a/src/contrib/src/org/apache/poi/contrib/poibrowser/package.html b/src/contrib/src/org/apache/poi/contrib/poibrowser/package.html
index 979e867ed1..ef4fbaa295 100644
--- a/src/contrib/src/org/apache/poi/contrib/poibrowser/package.html
+++ b/src/contrib/src/org/apache/poi/contrib/poibrowser/package.html
@@ -32,6 +32,10 @@
     (operating system) filenames. An internal file (i.e. a "stream" or a
     "document") is shown with its name, its size and a hexadecimal dump of its
     first bytes.</p>
+  </div>
+
+  <div>
+   <h3>Property Set Streams</h3>
 
    <p>The POI Browser pays special attention to property set streams. For
     example, the <tt>\005SummaryInformation</tt> stream  contains information
@@ -40,6 +44,49 @@
     not just its first bytes but analyses the whole stream and displays its
     contents in a more or less readable manner.</p>
   </div>
+
+  <div>
+   <h3>Running POI Browser</h3>
+
+   <p>Running the POI Browser requires you to start a Java Virtual Machine
+    (JVM) and to set up a valid classpath so that the JVM can find all the Java
+    classes it needs. These are the main POI classes and the "contrib" POI
+    classes.</p>
+
+   <p>The following instructions assume that you have set up your Java
+    enviromnent variables properly, i.e. the variable JAVA_HOME contains the
+    name of your Java installation directory and the variable PATH includes the
+    <var>bin</var> subdirectory of the Java installation directory. At the time
+   of this writing the current POI version was 2.5.1-final dating from August
+    4th, 2004. The example statements reflect version numbering and
+    date. Change the commands accordingly if you are running the POI Browser of
+   a later or earlier than this!</p>
+
+   <div>
+    <h4>Running POI Browser on Unix</h4>
+
+    <p>Suppose you have unpacked the POI&nbsp;2.5.1 release in the
+     <var>/opt/local/poi</var> directory of your Unix box. Then the following
+     command starts the POI Browser and displays the structure of the files
+     <var>MyWord.doc</var>, <var>MyExcel.xls</var> and
+     <var>MyPowerpoint.ppt</var>:</p>
+ 
+   <pre>java -classpath /opt/local/poi/poi-2.5.1-final-20040804.jar:/opt/local/poi/poi-contrib-2.5.1-final-20040804.jar org.apache.poi.contrib.poibrowser.POIBrowser MyWord.doc MyExcel.xls MyPowerpoint.ppt</pre>
+   </div>
+
+   <div>
+    <h4>Running POI Browser on Windows</h4>
+
+    <p>Suppose you have unpacked the POI&nbsp;2.5.1 release in the
+     <var>C:\Programs\POI</var> directory of your Windows box. Then the following
+     command starts the POI Browser and displays the structure of the files
+     <var>MyWord.doc</var>, <var>MyExcel.xls</var> and
+     <var>MyPowerpoint.ppt</var>:</p>
+ 
+   <pre>java -classpath C:\Programs\POI\poi-2.5.1-final-20040804.jar;C:\Programs\POI\poi-contrib-2.5.1-final-20040804.jar org.apache.poi.contrib.poibrowser.POIBrowser MyWord.doc MyExcel.xls MyPowerpoint.ppt</pre>
+   </div>
+
+  </div>
  </body>
 </html>
 
diff --git a/src/documentation/content/xdocs/overview.xml b/src/documentation/content/xdocs/overview.xml
index 7f69bda29f..987c1868f1 100644
--- a/src/documentation/content/xdocs/overview.xml
+++ b/src/documentation/content/xdocs/overview.xml
@@ -7,6 +7,7 @@
     <title>Overview</title>
     <authors>
       <person id="AO" name="Andrew C. Oliver" email="acoliver@apache.org"/>
+      <person id="RK" name="Rainer Klute" email="klute@apache.org"/>
     </authors>
   </header>
   
@@ -33,7 +34,7 @@
       <section><title>HSSF</title>
         <p>
           <link href="hssf/index.html">HSSF</link> is the set of APIs 
- 	  for reading and writing Microsoft Excel 97(-XP) spreadsheet using (only) Java.
+           for reading and writing Microsoft Excel 97(-XP) spreadsheet using (only) Java.
         </p>
       </section>
 
@@ -54,17 +55,45 @@
       <section><title>POI-Utils</title>
         <p>
           <link href="utils/index.html">POI-Utils</link> are general purpose artifacts
-	  from POI development that have not yet been implemented elsewhere.  We're 
+          from POI development that have not yet been implemented elsewhere.  We're 
           always looking to donate these and maintain them as part of a general library
           used in another project.  These are things we need to complete our mission but
           are generally outside of it.  
         </p>
       </section>
     </section>
+
+    <section>
+      <title>Examples</title>
+
+      <p>Small sample programs using the POI API are available in the
+        <em>src/examples</em> directory of the source distribution. Before
+        studying the source code you might want to have a look at the
+        "Examples" section of the <link
+          href="apidocs/overview-summary.html">POI API
+          documentation</link>.</p> 
+    </section>
+
+    <section><title>Contributed Software</title>
+      <p>Besides the "official" components outlined above there is some further
+      software distributed with POI. This is called "contributed" software. It
+        is not explicitly recommended or even maintained by the POI team, but
+        it might still be useful to you.</p>
+
+      <section>
+        <title>POI Browser</title>
+        <p>The POI Browser is a very simple Swing GUI tool that displays the
+          internal structure of a Microsoft Office file and especially the
+          property set streams. Further information and  instructions how to
+          execute it can be found in the <link
+            href="apidocs/org/apache/poi/contrib/poibrowser/package-summary.html#package_description">POI
+            Browser package description</link>.</p>
+      </section>
+    </section>
   </body>
   <footer>
     <legal>
-      Copyright (c) @year@ The POI Project All rights reserved.
+      Copyright 2005 The Apache Software Foundation or its licensors, as applicable.
       $Revision$ $Date$
     </legal>
   </footer>
diff --git a/src/examples/src/org/apache/poi/hpsf/examples/WriteAuthorAndTitle.java b/src/examples/src/org/apache/poi/hpsf/examples/WriteAuthorAndTitle.java
index e5e413b464..f9fe5e9344 100644
--- a/src/examples/src/org/apache/poi/hpsf/examples/WriteAuthorAndTitle.java
+++ b/src/examples/src/org/apache/poi/hpsf/examples/WriteAuthorAndTitle.java
@@ -34,6 +34,7 @@ import org.apache.poi.hpsf.MutableSection;
 import org.apache.poi.hpsf.NoPropertySetStreamException;
 import org.apache.poi.hpsf.PropertySet;
 import org.apache.poi.hpsf.PropertySetFactory;
+import org.apache.poi.hpsf.SummaryInformation;
 import org.apache.poi.hpsf.Util;
 import org.apache.poi.hpsf.Variant;
 import org.apache.poi.hpsf.WritingNotSupportedException;