Flesh out the docs

svn path=/trunk/; revision=6150

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index b237d45a3609222e1ce7512c5b734686e1118af7..a74ac1ffccce565a1c01545fa82cc54eb9ecef09 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,7 @@
+2007-12-17  Matthias Clasen <mclasen@redhat.com>
+
+       * gio: Flesh out the overview and migration docs.
+
 2007-12-17  Matthias Clasen <mclasen@redhat.com>
 
        * gio/migration.xml: Stub of a migration chapter

diff --git a/docs/reference/gio/Makefile.am b/docs/reference/gio/Makefile.am
index 88afc47a789271b858c7f9963a7305c26043c1a6..9aad48f1b5b93a07b0afcfeb722f838e331b85c4 100644 (file)
--- a/docs/reference/gio/Makefile.am
+++ b/docs/reference/gio/Makefile.am
@@ -92,6 +92,11 @@ HTML_IMAGES =                        \
 
 content_files =                \
        version.xml             \
+       overview.xml            \
+       migrating.xml
+
+expand_content_files =         \
+       overview.xml            \
        migrating.xml
 
 extra_files =                  \

diff --git a/docs/reference/gio/gio-docs.xml b/docs/reference/gio/gio-docs.xml
index 9b778a45ff428f367fa6d2e42a0e08a83b6ae3bb..fa8ae2137b8ae4242b6ee3765ddab3bef1b048e9 100644 (file)
--- a/docs/reference/gio/gio-docs.xml
+++ b/docs/reference/gio/gio-docs.xml
@@ -10,7 +10,7 @@
     <releaseinfo>for GIO &version;</releaseinfo>
   </bookinfo>
 
-  <xi:include href="overview.xml"/>
+  <xi:include href="xml/overview.xml"/>
 
   <part>
   <title>API Reference</title>
@@ -96,7 +96,7 @@
     </chapter>
   </part>
 
-  <xi:include href="migrating.xml"/>
+  <xi:include href="xml/migrating.xml"/>
 
   <chapter id="gio-hierarchy">
     <title>Object Hierarchy</title>

diff --git a/docs/reference/gio/gio-sections.txt b/docs/reference/gio/gio-sections.txt
index 97f8580d4883264c47df518e10f6a126316acc20..4a45d3548b67149d19f8ce1cf71f76b3dda8c467 100644 (file)
--- a/docs/reference/gio/gio-sections.txt
+++ b/docs/reference/gio/gio-sections.txt
@@ -1091,6 +1091,7 @@ g_filename_completer_get_type
 <TITLE>Unix Mounts</TITLE>
 GUnixMount
 GUnixMountPoint
+GUnixMountEntry
 GUnixMountMonitor
 g_unix_mount_free
 g_unix_mount_point_free
@@ -1135,13 +1136,6 @@ G_TYPE_UNIX_MOUNT
 g_unix_mount_monitor_get_type
 </SECTION>
 
-<SECTION>
-<FILE>gunixmountentry</FILE>
-<TITLE>GUnixMountEntry</TITLE>
-GUnixMountEntry
-<SUBSECTION Standard>
-</SECTION>
-
 <SECTION>
 <FILE>gdesktopappinfo</FILE>
 <TITLE>Desktop file based GAppInfo</TITLE>

diff --git a/docs/reference/gio/migrating.xml b/docs/reference/gio/migrating.xml
index b1be946744fd02789dfe69a8bcd3d57b217300d0..86c63e5ae05460f03316da4ee09b015a72b2dc44 100644 (file)
--- a/docs/reference/gio/migrating.xml
+++ b/docs/reference/gio/migrating.xml
@@ -1,30 +1,47 @@
-<chapter id="migrating">
+<part id="migrating">
   <title>Migrating to GIO</title>
 
-  <para>
-    This chapter explains how to port applications from POSIX I/O or
-    gnome-vfs to GIO.
-  </para>
+  <chapter>
+    <title>Migrating from POSIX to GIO</title>
+  
+    <table id="posix-vs-gio">
+      <title>Comparison of POSIX and GIO concepts</title>
+      <tgroup cols="2">
+        <thead>
+          <row><entry>POSIX</entry><entry>GIO</entry></row>
+        </thead>
+        <tbody>
+          <row><entry>char *path</entry><entry>GFile *file</entry></row>
+          <row><entry>struct stat *buf</entry><entry>GFileInfo *info</entry></row>
+          <row><entry>struct statvfs *buf</entry><entry>GFileInfo *info</entry></row>
+          <row><entry morerows="1">int fd</entry><entry>GInputStream *in</entry></row>
+          <row><entry>GOutputStream *out</entry></row>
+          <row><entry>DIR *</entry><entry>GFileEnumerator *enum</entry></row>
+          <row><entry>fstab entry</entry><entry>GUnixMountPoint *mount_point</entry></row>
+          <row><entry>mtab entry</entry><entry>GUnixMountEntry *mount_entry</entry></row>
+        </tbody>
+      </tgroup>
+    </table>  
 
-  <table id="posix-vs-gio">
-    <title>Comparison of POSIX and GIO concepts</title>
-    <tgroup cols="2">
-      <thead>
-        <row><entry>POSIX</entry><entry>GIO</entry></row>
-      </thead>
-      <tbody>
-        <row><entry>char *path</entry><entry>GFile *file</entry></row>
-        <row><entry>struct stat *buf</entry><entry>GFileInfo *info</entry></row>
-        <row><entry>struct statvfs *buf</entry><entry>GFileInfo *info</entry></row>
-        <row><entry morerows="1">int fd</entry><entry>GInputStream *in</entry></row>
-        <row><entry>GOutputStream *out</entry></row>
-        <row><entry>DIR *</entry><entry>GFileEnumerator *enum</entry></row>
-        <row><entry>fstab entry</entry><entry>GUnixMountPoint *mount_point</entry></row>
-        <row><entry>mtab entry</entry><entry>GUnixMountEntry *mount_entry</entry></row>
-      </tbody>
-    </tgroup>
- </table>  
+  </chapter>
 
-  <!-- FIXME now explain ! -->
+  <chapter>
+    <title>Migrating from GnomeVFS to GIO</title>
 
-</chapter>
+    <table id="gnome-vfs-vs-gio">
+      <title>Comparison of GnomeVFS and GIO concepts</title>
+      <tgroup cols="2">
+        <thead>
+          <row><entry>GnomeVFS</entry><entry>GIO</entry></row>
+        </thead>
+        <tbody>
+          <row><entry>GnomeVFSVolume</entry><entry>GMount</entry></row>
+          <row><entry>GnomeVFSDrive</entry><entry>GVolume</entry></row>
+          <row><entry>-</entry><entry>GDrive</entry></row>
+        </tbody>
+      </tgroup>
+    </table>
+
+  </chapter>
+
+</part>

diff --git a/docs/reference/gio/overview.xml b/docs/reference/gio/overview.xml
index 18d6e79cd0d2a124537a4b1e0e8e9d29f4269fd6..5f3d5045ba45efc87f929299c46c0743547e9673 100644 (file)
--- a/docs/reference/gio/overview.xml
+++ b/docs/reference/gio/overview.xml
@@ -1,13 +1,16 @@
 <part>
   <title>GIO Overview</title>
 
+  <chapter> 
+    <title>Introduction</title>
+
   <para>
-    GIO is striving to provide a modern, easy-to-use VFS api that sits
+    GIO 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 gnome-vfs and provide an api that is so good that
+    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 a higher-level, document-centric interfaces.
+    API, but providing a higher-level, document-centric interfaces.
   </para>
 
   <para>
@@ -68,31 +71,29 @@
        </varlistentry>
     </variablelist>
     Beyond these, GIO provides facilities for file monitoring,
-    asynchronous I/O and filename completion.  In addition to the 
+    asynchronous I/O and filename completion. In addition to the 
     interfaces, GIO provides implementations for the local case. 
     Implementations for various network file systems are provided 
     by the GVFS package as loadable modules.
   </para>
 
   <para>
-    Other design choices which consciously break with the gnome-vfs
+    Other design choices which consciously break with the GnomeVFS
     design are to move backends out-of-process, which minimizes the
     dependency bloat and makes the whole system more robust. The backends
-    are not included in GIO, but in the separate GVFS package. GVFS 
-    also contains the GVFS daemon, which spawn further mount daemons 
-    for each individual connection.
+    are not included in GIO, but in the separate GVFS package. The GVFS 
+    package also contains the GVFS daemon, which spawn further mount 
+    daemons for each individual connection.
   </para>
 
-  <para>
-    <figure id="mainloop-states">
-      <title>GIO in the GTK+ library stack</title>
-      <graphic fileref="gvfs-overview.png" format="PNG"></graphic>
-    </figure>
-  </para>
+  <figure id="gvfs-overview">
+    <title>GIO in the GTK+ library stack</title>
+    <graphic fileref="gvfs-overview.png" format="PNG"></graphic>
+  </figure>
 
   <para>
     The GIO model of I/O is stateful: if an application establishes e.g. 
-    a sftp connection to a server, it becomes available to all applications 
+    a SFTP connection to a server, it becomes available to all applications 
     in the session; the user does not have to enter his password over 
     and over again.
   </para>
@@ -100,5 +101,27 @@
     One of the big advantages of putting the VFS in the GLib layer 
     is that GTK+ can directly use it, e.g. in the filechooser.
   </para>
+  </chapter>
+
+  <chapter>
+    <title>Compiling GIO applications</title>
+
+    <para>
+      GIO comes with a <filename>gio-2.0.pc</filename> file that you
+      should use together with <literal>pkg-config</literal> to obtain
+      the necessary information about header files and libraries. See
+      the <literal>pkg-config</literal> man page or the GLib documentation 
+      for more information on how to use <literal>pkg-config</literal> 
+      to compile your application.
+    </para>
+
+    <para>
+      If you are using GIO on UNIX-like systems, you may want to use
+      UNIX-specific GIO interfaces such as #GUnixInputStream, 
+      #GUnixOutputStream, #GUnixMount or #GDesktopAppInfo. 
+      To do so, use the <filename>gio-unix-2.0.pc</filename> file 
+      instead of <filename>gio-2.0.pc</filename>
+    </para>
+  </chapter>
 
 </part>