<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [

<!ENTITY GsfInput		SYSTEM "xml/input.xml">
<!ENTITY GsfOutput		SYSTEM "xml/output.xml">
<!ENTITY GsfInfile		SYSTEM "xml/infile.xml">
<!ENTITY GsfOutfile		SYSTEM "xml/outfile.xml">

<!ENTITY GsfStdio		SYSTEM "xml/stdio.xml">
<!ENTITY GsfMemory		SYSTEM "xml/memory.xml">
<!ENTITY GsfIOChannel		SYSTEM "xml/iochannel.xml">
<!ENTITY GsfGnomevfs		SYSTEM "xml/gnome-vfs.xml">
<!ENTITY GsfBonobo		SYSTEM "xml/bonobo.xml">

<!ENTITY GsfMetadata		SYSTEM "xml/metadata.xml">
<!ENTITY GsfMsole		SYSTEM "xml/msole.xml">
<!ENTITY GsfBlobs		SYSTEM "xml/blobs.xml">
<!ENTITY GsfClipData		SYSTEM "xml/clip-data.xml">
<!ENTITY GsfCompression		SYSTEM "xml/compression.xml">
<!ENTITY GsfZip			SYSTEM "xml/zip.xml">
<!ENTITY GsfXml			SYSTEM "xml/xml.xml">
<!ENTITY GsfText		SYSTEM "xml/text.xml">
<!ENTITY GsfOpenDocument	SYSTEM "xml/opendoc.xml">

<!ENTITY GsfUtils		SYSTEM "xml/utils.xml">
<!ENTITY TreeIndex		SYSTEM "xml/tree_index.sgml">
]>

<book id="index">
  <bookinfo>
    <title>GSF Reference Manual</title>
  </bookinfo>

  <part id="intro">
    <title>GSF: Introduction</title>
    <partintro id="gsf-into">
    <para>
The GNOME Structured File Library (GSF) is an I/O abstraction for
reading/writing compound files.  GSF is released under the GNU <ulink
url="http://www.fsf.org/licensing/licenses/lgpl.html">Lesser General Public
License</ulink> (GNU LGPL), which allows for flexible licensing of client
applications.
    </para>
    </partintro>
  </part>

  <part id="history">
    <title>GSF: History</title>
    <partintro id="gsf-history">
    <para>
GSF was written as part of the Gnumeric project. It started in 2002 as a
replacement for libole2 which Gnumeric was using to handle the Microsoft
<trademark class='registered'>Excel</trademark> file format, as libole2's
code had become difficult to maintain and was difficult to generalize. GSF
was designed to be a more general library for dealing with a number of
different types of structured data files and streams.
    </para>
    <para>
With the release of Gnumeric 1.1.6 (July 2002), Gnumeric used GSF and
libole2 was orphaned.
    </para>
    </partintro>
  </part>

  <part id="dependencies">
    <title>GSF: Dependencies</title>
    <para>
GSF depends on the following libraries:
<variablelist>

<varlistentry>
<term><link linkend="glib" title="GLib">GLib</link></term>
<listitem><para>
A general-purpose utility library, not specific to graphical user interfaces.
GLib provides many useful data types, macros, type conversions,
string utilities, file utilities, a main loop abstraction, and so on.
</para></listitem>
</varlistentry>

<varlistentry>
<term>Libxml2</term>
<listitem><para>
A library that provides a parser and toolkit for XML, the <ulink
url="http://en.wikipedia.org/wiki/XML">Extensible Markup Language</ulink>.
XML is a metalanguage used to define markup languages (text languages where
structure and semantics are added to the content using extra "markup"
information).
</para></listitem>
</varlistentry>

</variablelist>

The core GSF library can be built to also utilize the following libraries:
<variablelist>

<varlistentry>
<term><ulink url="http://en.wikipedia.org/wiki/Zlib">zlib</ulink></term>
<listitem><para>
A data
compression library that implements the DEFLATE algorithm used in gzip.
</para></listitem>
</varlistentry>

<varlistentry>
<term><ulink url="http://en.wikipedia.org/wiki/Bzip2">libbz2</ulink></term>
<listitem><para>
A data compression library that implements the algorithm used in bzip2.
</para></listitem>
</varlistentry>

</variablelist>

A separate GSF library can be built that offers additional functionality for
use in the GNOME desktop environment. That library has the following
additional requirements:
<variablelist>

<varlistentry>
<term>libbonobo-2.0</term>
<listitem><para>
<ulink
url="http://developer.gnome.org/arch/component/bonobo.html">Bonobo</ulink>
is the GNOME architecture for creating reusable software components and
compound documents.
</para></listitem>
</varlistentry>

<varlistentry>
<term>gnome-vfs-2.0</term>
<listitem><para>
<ulink
url="http://developer.gnome.org/doc/API/2.0/gnome-vfs-2.0/">GnomeVFS</ulink>
is a filesystem abstraction library that allows applications plugable
transparent access to a variety of "real" filesystems, including networked
filesystems like WebDAV, storage on devices like digital cameras, to the
local filesystem.
</para></listitem>
</varlistentry>

</variablelist>

    </para>
</part>

<part id="gsf-users">
  <title>Projects using GSF</title>
  <partintro id="gsf-projects">
  <para>
GSF is now also being used by other projects than Gnumeric, including
<variablelist>
<varlistentry>
<term><ulink url="http://www.koffice.org/kword/">KWord</ulink></term>
<listitem><para>
The word processor application of <ulink
url="http://www.koffice.org">KOffice</ulink>, the integrated office suite for
<ulink url="http://www.kde.org">KDE</ulink>, the K Desktop Environment.
</para></listitem>
</varlistentry>

<varlistentry>
<term><ulink url="http://librsvg.sourceforge.net/">librsvg</ulink></term>
<listitem><para>
A library to support the <ulink
url="http://www.w3.org/Graphics/SVG/">SVG</ulink> scalable vector graphics
format.
</para></listitem>
</varlistentry>

<varlistentry>
<term><ulink url="http://libwpd.sourceforge.net">libwpd</ulink></term>
<listitem><para>
A library for importing <trademark
class='registered'>WordPerfect</trademark> documents.
</para></listitem>
</varlistentry>

<varlistentry>
<term><ulink url="http://planner.imendio.org/">planner</ulink></term>
<listitem><para>
A project management application.
</para></listitem>
</varlistentry>

</variablelist>

  </para>
  </partintro>
</part>

<part id="api">
  <title>API Reference</title>
    <partintro id="gsf-api-ref">
      <para>
The core of GSF's API deals with basic I/O, an abstraction layer that
provides a uniform interface to several mechanisms that provide streams of
data and a set of parsers for various structured types of data streams.
      </para>
    </partintro>
  <chapter id="io">
    <title>Basic Input/Output</title>
    &GsfInput;
    &GsfOutput;
  </chapter>
  <chapter id="sources">
    <title>Stream Sources</title>
    &GsfInfile;
    &GsfOutfile;
    &GsfStdio;
    &GsfMemory;
    &GsfIOChannel;
    &GsfGnomevfs;
    &GsfBonobo;
  </chapter>
  <chapter id="parsers">
    <title>Stream Parsers</title>
    &GsfText;
    &GsfXml;
    &GsfZip;
    &GsfCompression;
    &GsfMsole;
    &GsfMetadata;
    &GsfOpenDocument;
    &GsfBlobs;
    &GsfClipData;
  </chapter>
  <chapter id="misc">
    <title>Miscellaneous</title>
    &GsfUtils;
  </chapter>
 </part>
<index id="gsf-index">
&TreeIndex;
</index>
</book>
