updated the docs

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

src/documentation/content/xdocs/changes.xml

@@ -37,6 +37,7 @@
 
 		<!-- Don't forget to update status.xml too! -->
         <release version="3.0.3-beta1" date="2008-04-??">
+           <action dev="POI-DEVELOPERS" type="add">HSLF: Support for getting embedded sounds from slide show </action>
            <action dev="POI-DEVELOPERS" type="add">HSLF: Initial support for rendering slides into images</action>
            <action dev="POI-DEVELOPERS" type="add">HSLF: Support for getting OLE object data from slide show </action>
            <action dev="POI-DEVELOPERS" type="add">HSLF: Implemented more methods in PPGraphics2D</action>

src/documentation/content/xdocs/hslf/how-to-shapes.xml

@@ -42,6 +42,7 @@
                     <li><link href="#Tables">Tables</link></li>
                     <li><link href="#RemoveShape">How to remove shapes</link></li>
                     <li><link href="#OLE">How to retrieve embedded OLE objects</link></li>
+                    <li><link href="#Sound">How to retrieve embedded sounds</link></li>
                     <li><link href="#Freeform">How to create shapes of arbitrary geometry</link></li>
                     <li><link href="#Graphics2D">Shapes and Graphics2D</link></li>
                     <li><link href="#Render">How to convert slides into images</link></li>
@@ -474,6 +475,26 @@
                     </source>
                   </section>
 
+                <anchor id="Sound"/>
+                <section><title>How to retrieve embedded sounds</title>
+                  <source>
+
+        FileInputStream is = new FileInputStream(args[0]);
+        SlideShow ppt = new SlideShow(is);
+        is.close();
+
+        SoundData[] sound = ppt.getSoundData();
+        for (int i = 0; i &lt; sound.length; i++) {
+            //save *WAV sounds on disk
+            if(sound[i].getSoundType().equals(".WAV")){
+                FileOutputStream out = new FileOutputStream(sound[i].getSoundName());
+                out.write(sound[i].getData());
+                out.close();
+            }
+        }
+                    </source>
+                  </section>
+                  
                 <anchor id="Freeform"/>
                 <section><title>How to create shapes of arbitrary geometry</title>
                   <source>
@@ -556,7 +577,7 @@
                   <p>
                     HSLF provides a way to export slides into images. You can capture slides into java.awt.Graphics2D object (or any other) 
                     and serialize it into a PNG or JPEG format. Please note, although HSLF attempts to render slides as close to PowerPoint as possible, 
-                    the output might look differently from PowerPoint due to the following reasons: 
+                    the output may look differently from PowerPoint due to the following reasons: 
                   </p>
             <ul>
               <li>Java2D renders fonts differently vs PowerPoint. There are always some differences in the way the font glyphs are painted</li>   

src/documentation/content/xdocs/hslf/index.xml

@@ -26,6 +26,7 @@
         <authors>
             <person name="Avik Sengupta" email="avik at apache dot org"/>
             <person name="Nick Burch" email="nick at apache dot org"/>
+            <person name="Yegor Kozlov" email="yegor at apache dot org"/>
         </authors>
     </header>
 
@@ -37,9 +38,12 @@
 			Powerpoint '97(-2007) file format. It <em>does not</em> support
 			the new PowerPoint 2007 .pptx file format, which is not OLE2 
 			based.</p>
-            <p>HSLF provides a way to read powerpoint presentations, and extract text from it.
+    <p>HSLF provides a way to read, create or modify PowerPoint  presentations. In particular, it provides:
-            It also provides some (currently limited) edit capabilities.
             </p>
+            <ul>
+                <li>api for data extraction (text, pictures, embedded objects, sounds)</li>
+                <li>usermodel api for creating, reading and modifying ppt files</li>
+            </ul>
             <note> 
                 This code currently lives the 
                 <link href="http://svn.apache.org/viewcvs.cgi/poi/trunk/src/scratchpad/">scratchpad area</link> 

src/documentation/content/xdocs/index.xml

@@ -150,8 +150,7 @@
         </section>
         <section><title>HSLF for PowerPoint Documents</title>
 	<p>HSLF is our port of the Microsoft PowerPoint 97(-2003) file format to pure
-	  Java. It supports read and write capabilities of some, but not yet all
+	  Java. It supports read and write capabilities. Please see <link
-      of the core records. Please see <link
 	    href="./hslf/index.html">the HSLF project page for more
 	    information</link>.</p>
         </section>

src/documentation/content/xdocs/poifs/embeded.xml

@@ -61,9 +61,9 @@
        <section><title>Files embeded in PowerPoint</title>
          <p>PowerPoint does not normally store embeded files
          in the OLE2 layer. Instead, they are held within records
-         of the main PowerPoint file. To get at them, you need to
+         of the main PowerPoint file. 
-         find the appropriate data within the PowerPoint stream,
+         <br/>See the <link href="./../hslf/how-to-shapes.html#OLE">HSLF Tutorial</link> 
-         and work from that.</p>
+         for how to retrieve embedded OLE objects from a presentation</p>
        </section>
     </section>
 

src/documentation/content/xdocs/status.xml

@@ -34,6 +34,7 @@
 	<!-- Don't forget to update changes.xml too! -->
     <changes>
         <release version="3.0.3-beta1" date="2008-04-??">
+           <action dev="POI-DEVELOPERS" type="add">HSLF: Support for getting embedded sounds from slide show </action>
            <action dev="POI-DEVELOPERS" type="add">HSLF: Initial support for rendering slides into images</action>
            <action dev="POI-DEVELOPERS" type="add">HSLF: Support for getting OLE object data from slide show </action>
            <action dev="POI-DEVELOPERS" type="add">HSLF: Implemented more methods in PPGraphics2D</action>