From bebb750ac2135e1f1a1d1d6f6dec7904de857115 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <matthiasc@src.gnome.org>
Date: Thu, 24 Jan 2008 05:35:33 +0000
Subject: [PATCH] Updates

svn path=/trunk/; revision=6362
---
 docs/reference/ChangeLog         |  5 ++++
 docs/reference/gio/migrating.xml | 50 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index c9c063f..c33f7f2 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,5 +1,10 @@
 2008-01-23  Matthias Clasen  <mclasen@redhat.com>
 
+	* gio/migration.xml: Add something on trash handling
+	and some very sketchy information on gnome_vfs_xfer
+
+2008-01-23  Matthias Clasen  <mclasen@redhat.com>
+
 	* gio/overview.xml: Document environment
 	variables used by GIO.
 
diff --git a/docs/reference/gio/migrating.xml b/docs/reference/gio/migrating.xml
index a321afe..8b1b254 100644
--- a/docs/reference/gio/migrating.xml
+++ b/docs/reference/gio/migrating.xml
@@ -52,6 +52,56 @@
       </tgroup>
     </table>
 
+    <section>
+      <title>Trash handling</title>
+
+      <para>
+        The handling of trashed files has been changed in GIO, compared
+        to gnome-vfs. gnome-vfs has a home-grown trash implementation that 
+        predates the freedesktop.org <ulink url="http://www.freedesktop.org/wiki/Specifications/trash-spec">Desktop Trash Can</ulink> specification
+        that is implemented in GIO.
+      </para>
+      <para>
+        Both systems support a the <filename>trash://</filename> scheme to
+        access a merged view of all trashed files, but the location for 
+        storing trashed files has changed from <filename>$HOME/.Trash</filename>
+        to <filename>$HOME/.local/share/Trash</filename> (or more correctly
+         <filename>$XDG_DATA_HOME/Trash</filename>), which means that 
+        there is a need for migrating files that have been trashed by 
+        gnome-vfs to the new location.
+      </para>
+      <para>
+        GIO exposes some useful metadata about trashed files. There are
+        trash::orig-path and tash::deletion-date attributes. The 
+        standard::icon attribute of the <filename>trash://</filename> 
+        itself provides a suitable icon for displaying the trash can on 
+        the desktop. If you are using this icon, make sure to monitor
+        this attribute for changes, since the icon may be updated to
+        reflect that state of the trash can.
+      </para>
+      <para>
+	Moving a file to the trash is much simpler with GIO. Instead of
+        using gnome_vfs_find_directory() with %GNOME_VFS_DIRECTORY_KIND_TRASH 
+        to find out where to move the trashed file, just use the g_file_trash()
+        function.
+      </para>
+    </section>
+
+    <section>
+      <title>Operations on multiple files</title>
+
+      <para>
+        gnome-vfs has the dreaded gnome_vfs_xfer_uri_list() function which
+        has tons of options and offers the equivalent of cp, mv, ln, mkdir
+        and rm at the same time. 
+      </para>
+      <para>
+        GIO offers a much simpler I/O scheduler functionality instead, that
+        lets you schedule a function to be called in a separate thread. 
+        See g_io_scheduler_push_job(). 
+      </para>
+
+    </section>
   </chapter>
 
 </part>
-- 
2.7.4