<?xml version="1.0"?>
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
                      'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<book lang="en" id="gsf" xmlns:xi="http://www.w3.org/2003/XInclude">

  <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>gio-2.0</term>
<listitem><para>
<ulink
url="http://library.gnome.org/devel/gio/2.16/ch01.html">GIO</ulink>
is striving to provide a modern, easy-to-use VFS API that sits at the right
level in the library stack. The goal is to overcome the shortcomings of 
GnomeVFS and provide an API that is so good that developers prefer it over
raw POSIX calls. Among other things that means using GObject. It also means
not cloning the POSIX API, but providing higher-level, document-centric interfaces.
</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>
    <xi:include href="xml/input.xml"/>
    <xi:include href="xml/output.xml"/>
  </chapter>
  <chapter id="sources">
    <title>Stream Sources</title>
    <xi:include href="xml/infile.xml"/>
    <xi:include href="xml/outfile.xml"/>
    <xi:include href="xml/stdio.xml"/>
    <xi:include href="xml/memory.xml"/>
    <xi:include href="xml/iochannel.xml"/>
    <xi:include href="xml/gio.xml"/>
  </chapter>
  <chapter id="parsers">
    <title>Stream Parsers</title>
    <xi:include href="xml/text.xml"/>
    <xi:include href="xml/xml.xml"/>
    <xi:include href="xml/zip.xml"/>
    <xi:include href="xml/compression.xml"/>
    <xi:include href="xml/msole.xml"/>
    <xi:include href="xml/metadata.xml"/>
    <xi:include href="xml/opendoc.xml"/>
    <xi:include href="xml/blobs.xml"/>
    <xi:include href="xml/clip-data.xml"/>
  </chapter>
  <chapter id="misc">
    <title>Miscellaneous</title>
    <xi:include href="xml/utils.xml"/>
  </chapter>
 </part>
<index id="gsf-index">
    <title id="index-all">Index</title>
<xi:include href="xml/tree_index.sgml"/>
</index>

<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>

</book>
