From a9a824ae24ee75a58414c9652e84028f645c2c20 Mon Sep 17 00:00:00 2001 From: Avik Sengupta <avik@apache.org> Date: Sat, 28 May 2005 19:28:22 +0000 Subject: [PATCH] documentation for powerpoint support git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@353702 13f79535-47bb-0310-9956-ffa450edef68 --- src/documentation/content/xdocs/book.xml | 3 +- src/documentation/content/xdocs/hslf/book.xml | 18 ++++++ .../content/xdocs/hslf/index.xml | 33 +++++++++++ .../content/xdocs/hslf/quick-guide.xml | 58 +++++++++++++++++++ 4 files changed, 111 insertions(+), 1 deletion(-) create mode 100644 src/documentation/content/xdocs/hslf/book.xml create mode 100755 src/documentation/content/xdocs/hslf/index.xml create mode 100644 src/documentation/content/xdocs/hslf/quick-guide.xml diff --git a/src/documentation/content/xdocs/book.xml b/src/documentation/content/xdocs/book.xml index c803b12d6e..13538d3e9c 100644 --- a/src/documentation/content/xdocs/book.xml +++ b/src/documentation/content/xdocs/book.xml @@ -21,7 +21,8 @@ <menu-item label="HSSF" href="hssf/index.html"/> <menu-item label="HWPF" href="hwpf/index.html"/> <menu-item label="HPSF" href="hpsf/index.html"/> - <menu-item label="POI-Ruby" href="poi-ruby.html"/> + <menu-item label="HSLF" href="hslf/index.html"/> + <menu-item label="POI-Ruby" href="poi-ruby.html"/> <menu-item label="POI-Utils" href="utils/index.html"/> <menu-item label="Download" href="ext:download"/> </menu> diff --git a/src/documentation/content/xdocs/hslf/book.xml b/src/documentation/content/xdocs/hslf/book.xml new file mode 100644 index 0000000000..cc92cdb1c7 --- /dev/null +++ b/src/documentation/content/xdocs/hslf/book.xml @@ -0,0 +1,18 @@ +<?xml version="1.0"?> +<!-- Copyright (C) 2005 The Apache Software Foundation. All rights reserved. --> +<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../dtd/book-cocoon-v10.dtd"> + +<book software="POI Project" + title="HSSF" + copyright="@year@ POI Project"> + + <menu label="Jakarta POI"> + <menu-item label="Top" href="../index.html"/> + </menu> + + <menu label="HSLF"> + <menu-item label="Overview" href="index.html"/> + <menu-item label="Quick Guide" href="quick-guide.html"/> + </menu> + +</book> diff --git a/src/documentation/content/xdocs/hslf/index.xml b/src/documentation/content/xdocs/hslf/index.xml new file mode 100755 index 0000000000..5d176fa8c3 --- /dev/null +++ b/src/documentation/content/xdocs/hslf/index.xml @@ -0,0 +1,33 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- Copyright (C) 2004 The Apache Software Foundation. All rights reserved. --> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd"> + +<document> + <header> + <title>POI-HSLF - Java API To Access Microsoft Powerpoint Format Files</title> + <subtitle>Overview</subtitle> + <authors> + <person name="Avik Sengupta" email="avik at apache dot org"/> + </authors> + </header> + + <body> + <section> + <title>Overview</title> + + <p>HSLF is the POI Project's pure Java implementation of the Powerpoint file format.</p> + <p>HSSF provides a way to read powerpoint presentations, and extract text from it. + It also provides some (currently limited) edit capabilities. + </p> + <note> This code currently lives the scratchpad area of the POI CVS repository. + Ensure that you have the scratchpad jar or the scratchpad build area in your + classpath before experimenting with this code. + </note> + <p>The <link href="./quick-guide.html">quick guide</link> documentation provides + information on using this API. Comments and fixes gratefully accepted on the POI + dev mailing lists.</p> + + + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/hslf/quick-guide.xml b/src/documentation/content/xdocs/hslf/quick-guide.xml new file mode 100644 index 0000000000..5f6525232c --- /dev/null +++ b/src/documentation/content/xdocs/hslf/quick-guide.xml @@ -0,0 +1,58 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- Copyright (C) 2004 The Apache Software Foundation. All rights reserved. --> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd"> + +<document> + <header> + <title>POI-HSLF - A Quick Guide</title> + <subtitle>Overview</subtitle> + <authors> + <person name="Nick Burch" email="nick at torchbox dot com"/> + </authors> + </header> + + <body> + <section><title>Basic Text Extraction</title> + <p>For basic text extraction, make use of +<code>org.apache.poi.extractor.PowerPointExtractor</code>. It accepts a file or an input +stream. The <code>getText()</code> method can be used to get the text from the slides, +from the notes, or from both. + </p> + </section> + + <section><title>Specific Text Extraction</title> + <p>To get specific bits of text, first create a <code>org.apache.poi.usermodel.SlideShow</code> +(from a <code>org.apache.poi.HSLFSlideShow</code>, which accepts a file or an input +stream). Use <code>getSlides()</code> and <code>getNotes()</code> to get the slides and notes. +These can be queried to get their page ID (though they should be returned +in the right order). You can also call <code>getTextRuns()</code> on these, to get their +blocks of text. From the <code>TextRun</code>, you can extract the text, and check +what type of text it is (eg Body, Title) + </p> + </section> + + <section><title>Changing Text</title> + <p>It is possible to change the text via <code>TextRun.setText(String)</code>. However, if +the length of the text is changed, things will break because PowerPoint has +internal file references in byte offsets, which are not yet all updated when +the size changes. + </p> + </section> + + <section><title>Guide to key classes</title> + <ul> + <li><code>org.apache.poi.hslf.HSLFSlideShow</code> + Handles reading in and writing out files. Generates a tree of the records + in the file + </li> + <li><code>org.apache.poi.hslf.usermode.SlideShow</code> + Builds up model entries from the records, and presents a user facing + view of the file + </li> + <li><code>org.apache.poi.hslf.extractor.PowerPointExtractor</code> + Uses the model code to allow extraction of text from files + </li> + </ul> + </section> + </body> +</document> \ No newline at end of file