doc/gsf-docs.sgml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
   4
   5 <!ENTITY GsfInput               SYSTEM "xml/input.xml">
   6 <!ENTITY GsfOutput              SYSTEM "xml/output.xml">
   7 <!ENTITY GsfInfile              SYSTEM "xml/infile.xml">
   8 <!ENTITY GsfOutfile             SYSTEM "xml/outfile.xml">
   9
  10 <!ENTITY GsfStdio               SYSTEM "xml/stdio.xml">
  11 <!ENTITY GsfMemory              SYSTEM "xml/memory.xml">
  12 <!ENTITY GsfIOChannel           SYSTEM "xml/iochannel.xml">
  13 <!ENTITY GsfGnomevfs            SYSTEM "xml/gnome-vfs.xml">
  14 <!ENTITY GsfGIO                 SYSTEM "xml/gio.xml">
  15 <!ENTITY GsfBonobo              SYSTEM "xml/bonobo.xml">
  16
  17 <!ENTITY GsfMetadata            SYSTEM "xml/metadata.xml">
  18 <!ENTITY GsfMsole               SYSTEM "xml/msole.xml">
  19 <!ENTITY GsfBlobs               SYSTEM "xml/blobs.xml">
  20 <!ENTITY GsfClipData            SYSTEM "xml/clip-data.xml">
  21 <!ENTITY GsfCompression         SYSTEM "xml/compression.xml">
  22 <!ENTITY GsfZip                 SYSTEM "xml/zip.xml">
  23 <!ENTITY GsfXml                 SYSTEM "xml/xml.xml">
  24 <!ENTITY GsfText                SYSTEM "xml/text.xml">
  25 <!ENTITY GsfOpenDocument        SYSTEM "xml/opendoc.xml">
  26
  27 <!ENTITY GsfUtils               SYSTEM "xml/utils.xml">
  28 <!ENTITY TreeIndex              SYSTEM "xml/tree_index.sgml">
  29 ]>
  30
  31 <book id="index">
  32   <bookinfo>
  33     <title>GSF Reference Manual</title>
  34   </bookinfo>
  35
  36   <part id="intro">
  37     <title>GSF: Introduction</title>
  38     <partintro id="gsf-into">
  39     <para>
  40 The GNOME Structured File Library (GSF) is an I/O abstraction for
  41 reading/writing compound files.  GSF is released under the GNU <ulink
  42 url="http://www.fsf.org/licensing/licenses/lgpl.html">Lesser General Public
  43 License</ulink> (GNU LGPL), which allows for flexible licensing of client
  44 applications.
  45     </para>
  46     </partintro>
  47   </part>
  48
  49   <part id="history">
  50     <title>GSF: History</title>
  51     <partintro id="gsf-history">
  52     <para>
  53 GSF was written as part of the Gnumeric project. It started in 2002 as a
  54 replacement for libole2 which Gnumeric was using to handle the Microsoft
  55 <trademark class='registered'>Excel</trademark> file format, as libole2's
  56 code had become difficult to maintain and was difficult to generalize. GSF
  57 was designed to be a more general library for dealing with a number of
  58 different types of structured data files and streams.
  59     </para>
  60     <para>
  61 With the release of Gnumeric 1.1.6 (July 2002), Gnumeric used GSF and
  62 libole2 was orphaned.
  63     </para>
  64     </partintro>
  65   </part>
  66
  67   <part id="dependencies">
  68     <title>GSF: Dependencies</title>
  69     <para>
  70 GSF depends on the following libraries:
  71 <variablelist>
  72
  73 <varlistentry>
  74 <term><link linkend="glib" title="GLib">GLib</link></term>
  75 <listitem><para>
  76 A general-purpose utility library, not specific to graphical user interfaces.
  77 GLib provides many useful data types, macros, type conversions,
  78 string utilities, file utilities, a main loop abstraction, and so on.
  79 </para></listitem>
  80 </varlistentry>
  81
  82 <varlistentry>
  83 <term>Libxml2</term>
  84 <listitem><para>
  85 A library that provides a parser and toolkit for XML, the <ulink
  86 url="http://en.wikipedia.org/wiki/XML">Extensible Markup Language</ulink>.
  87 XML is a metalanguage used to define markup languages (text languages where
  88 structure and semantics are added to the content using extra "markup"
  89 information).
  90 </para></listitem>
  91 </varlistentry>
  92
  93 </variablelist>
  94
  95 The core GSF library can be built to also utilize the following libraries:
  96 <variablelist>
  97
  98 <varlistentry>
  99 <term><ulink url="http://en.wikipedia.org/wiki/Zlib">zlib</ulink></term>
 100 <listitem><para>
 101 A data
 102 compression library that implements the DEFLATE algorithm used in gzip.
 103 </para></listitem>
 104 </varlistentry>
 105
 106 <varlistentry>
 107 <term><ulink url="http://en.wikipedia.org/wiki/Bzip2">libbz2</ulink></term>
 108 <listitem><para>
 109 A data compression library that implements the algorithm used in bzip2.
 110 </para></listitem>
 111 </varlistentry>
 112
 113 </variablelist>
 114
 115 A separate GSF library can be built that offers additional functionality for
 116 use in the GNOME desktop environment. That library has the following
 117 additional requirements:
 118 <variablelist>
 119
 120 <varlistentry>
 121 <term>libbonobo-2.0</term>
 122 <listitem><para>
 123 <ulink
 124 url="http://developer.gnome.org/arch/component/bonobo.html">Bonobo</ulink>
 125 is the GNOME architecture for creating reusable software components and
 126 compound documents.
 127 </para></listitem>
 128 </varlistentry>
 129
 130 <varlistentry>
 131 <term>gnome-vfs-2.0</term>
 132 <listitem><para>
 133 <ulink
 134 url="http://developer.gnome.org/doc/API/2.0/gnome-vfs-2.0/">GnomeVFS</ulink>
 135 is a filesystem abstraction library that allows applications plugable
 136 transparent access to a variety of "real" filesystems, including networked
 137 filesystems like WebDAV, storage on devices like digital cameras, to the
 138 local filesystem.
 139 </para></listitem>
 140 </varlistentry>
 141
 142 <varlistentry>
 143 <term>gio-2.0</term>
 144 <listitem><para>
 145 <ulink
 146 url="http://library.gnome.org/devel/gio/2.16/ch01.html">GIO</ulink>
 147 is striving to provide a modern, easy-to-use VFS API that sits at the right
 148 level in the library stack. The goal is to overcome the shortcomings of
 149 GnomeVFS and provide an API that is so good that developers prefer it over
 150 raw POSIX calls. Among other things that means using GObject. It also means
 151 not cloning the POSIX API, but providing higher-level, document-centric interfaces.
 152 </para></listitem>
 153 </varlistentry>
 154
 155 </variablelist>
 156
 157     </para>
 158 </part>
 159
 160 <part id="gsf-users">
 161   <title>Projects using GSF</title>
 162   <partintro id="gsf-projects">
 163   <para>
 164 GSF is now also being used by other projects than Gnumeric, including
 165 <variablelist>
 166 <varlistentry>
 167 <term><ulink url="http://www.koffice.org/kword/">KWord</ulink></term>
 168 <listitem><para>
 169 The word processor application of <ulink
 170 url="http://www.koffice.org">KOffice</ulink>, the integrated office suite for
 171 <ulink url="http://www.kde.org">KDE</ulink>, the K Desktop Environment.
 172 </para></listitem>
 173 </varlistentry>
 174
 175 <varlistentry>
 176 <term><ulink url="http://librsvg.sourceforge.net/">librsvg</ulink></term>
 177 <listitem><para>
 178 A library to support the <ulink
 179 url="http://www.w3.org/Graphics/SVG/">SVG</ulink> scalable vector graphics
 180 format.
 181 </para></listitem>
 182 </varlistentry>
 183
 184 <varlistentry>
 185 <term><ulink url="http://libwpd.sourceforge.net">libwpd</ulink></term>
 186 <listitem><para>
 187 A library for importing <trademark
 188 class='registered'>WordPerfect</trademark> documents.
 189 </para></listitem>
 190 </varlistentry>
 191
 192 <varlistentry>
 193 <term><ulink url="http://planner.imendio.org/">planner</ulink></term>
 194 <listitem><para>
 195 A project management application.
 196 </para></listitem>
 197 </varlistentry>
 198
 199 </variablelist>
 200
 201   </para>
 202   </partintro>
 203 </part>
 204
 205 <part id="api">
 206   <title>API Reference</title>
 207     <partintro id="gsf-api-ref">
 208       <para>
 209 The core of GSF's API deals with basic I/O, an abstraction layer that
 210 provides a uniform interface to several mechanisms that provide streams of
 211 data and a set of parsers for various structured types of data streams.
 212       </para>
 213     </partintro>
 214   <chapter id="io">
 215     <title>Basic Input/Output</title>
 216     &GsfInput;
 217     &GsfOutput;
 218   </chapter>
 219   <chapter id="sources">
 220     <title>Stream Sources</title>
 221     &GsfInfile;
 222     &GsfOutfile;
 223     &GsfStdio;
 224     &GsfMemory;
 225     &GsfIOChannel;
 226     &GsfGnomevfs;
 227     &GsfGIO;
 228     &GsfBonobo;
 229   </chapter>
 230   <chapter id="parsers">
 231     <title>Stream Parsers</title>
 232     &GsfText;
 233     &GsfXml;
 234     &GsfZip;
 235     &GsfCompression;
 236     &GsfMsole;
 237     &GsfMetadata;
 238     &GsfOpenDocument;
 239     &GsfBlobs;
 240     &GsfClipData;
 241   </chapter>
 242   <chapter id="misc">
 243     <title>Miscellaneous</title>
 244     &GsfUtils;
 245   </chapter>
 246  </part>
 247 <index id="gsf-index">
 248 &TreeIndex;
 249 </index>
 250 </book>