Add long descriptions.

2006-04-17  Emmanuele Bassi  <ebassi@cvs.gnome.org>

	* gtk/tmpl/gtkrecent*.sgml: Add long descriptions.

docs/reference/ChangeLog

@@ -1,3 +1,7 @@
+2006-04-17  Emmanuele Bassi  <ebassi@cvs.gnome.org>
+
+	* gtk/tmpl/gtkrecent*.sgml: Add long descriptions.
+
 2006-04-16  Matthias Clasen  <mclasen@redhat.com>
 
 	* gtk/tmpl/gtkrecent*.sgml: Add short descriptions

docs/reference/gtk/tmpl/gtkrecentchooser.sgml

@@ -6,15 +6,20 @@ Interface implemented by GtkRecentChooserWidget, GtkRecentChooserMenu and GtkRec
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+#GtkRecentChooser is an interface that can be implemented by widgets
+displaying the list of recently used files.  In GTK+, the main objects
+that implement this interface are #GtkRecentChooserWidget,
+#GtkRecentChooserDialog and #GtkRecentChooserMenu.
 </para>
+
 <para>
 Recently used files are supported since GTK+ 2.10.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#GtkRecentManager, #GtkRecentChooserDialog, #GtkRecentChooserWidget,
+#GtkRecentChooserMenu
 </para>
 
 <!-- ##### SECTION Stability_Level ##### -->
@@ -47,20 +52,38 @@ Recently used files are supported since GTK+ 2.10.
 @item_activated: 
 @selection_changed: 
 
-<!-- ##### MACRO GTK_RECENT_CHOOSER_ERROR ##### -->
+
+<!-- ##### SIGNAL GtkRecentChooser::item-activated ##### -->
 <para>
 
 </para>
 
+@recentchooser: the object which received the signal.
+
+<!-- ##### SIGNAL GtkRecentChooser::selection-changed ##### -->
+<para>
+
+</para>
+
+@recentchooser: the object which received the signal.
+
+
+
+<!-- ##### MACRO GTK_RECENT_CHOOSER_ERROR ##### -->
+<para>
+Used to get the #GError quark for #GtkRecentChooser errors.
+</para>
+
 
 
 <!-- ##### ENUM GtkRecentChooserError ##### -->
 <para>
-
+These identify the various errors that can occur while calling
+#GtkRecentChooser functions.
 </para>
 
-@GTK_RECENT_CHOOSER_ERROR_NOT_FOUND: 
+@GTK_RECENT_CHOOSER_ERROR_NOT_FOUND: Indicates that a file does not exist
-@GTK_RECENT_CHOOSER_ERROR_INVALID_URI: 
+@GTK_RECENT_CHOOSER_ERROR_INVALID_URI: Indicates a malformed URI
 
 <!-- ##### FUNCTION gtk_recent_chooser_set_show_private ##### -->
 <para>

docs/reference/gtk/tmpl/gtkrecentchooserdialog.sgml

@@ -6,15 +6,55 @@ Displays recently used files in a dialog
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+#GtkRecentChooserDialog is a dialog box suitable for displaying the recently
+used documents.  This widgets works by putting a #GtkRecentChooserWidget inside
+a #GtkDialog.  It exposes the #GtkRecentChooserIface interface, so you can use
+all the #GtkRecentChooser functions on the recent chooser dialog as well as
+those for #GtkDialog.
 </para>
+
+<para>
+Note that #GtkRecentChooserDialog does not have any methods of its own.
+Instead, you should use the functions that work on a #GtkRecentChooser.
+</para>
+
+<example id="gtkrecentchooser-typical-usage">
+  <title>Typical usage</title>
+
+  <para>
+    In the simplest of cases, you can use the following code to use
+    a #GtkRecentChooserDialog to select a recently used file:
+  </para>
+
+  <programlisting>
+GtkWidget *dialog;
+
+dialog = gtk_recent_chooser_dialog_new ("Recent Documents",
+					parent_window,
+					GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
+					GTK_STOCK_OPEN, GTK_RESPONSE_ACCEPT,
+					NULL);
+					
+if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT)
+  {
+    GtkRecentInfo *info;
+
+    info = gtk_recent_chooser_get_current_item (GTK_RECENT_CHOOSER (dialog));
+    open_file (gtk_recent_info_get_uri (info));
+    gtk_recent_info_unref (info);
+  }
+
+gtk_widget_destroy (dialog);
+  </programlisting>
+</example>
+
 <para>
 Recently used files are supported since GTK+ 2.10.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#GtkRecentChooser, #GtkDialog
 </para>
 
 <!-- ##### SECTION Stability_Level ##### -->

docs/reference/gtk/tmpl/gtkrecentchoosermenu.sgml

@@ -6,15 +6,22 @@ Displays recently used files in a menu
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+#GtkRecentChooserMenu is a widget suitable for displaying recently used files
+inside a menu.  It can be used to set a sub-menu of a #GtkMenuItem using
+gtk_menu_item_set_submenu(), or as the menu of a #GtkMenuToolButton.
 </para>
+
+<para>
+Note that #GtkRecentChooserMenu does not have any methods of its own.  Instead,
+you should use the functions that work on a #GtkRecentChooser.
+
 <para>
 Recently used files are supported since GTK+ 2.10.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#GtkRecentChooser
 </para>
 
 <!-- ##### SECTION Stability_Level ##### -->

docs/reference/gtk/tmpl/gtkrecentchooserwidget.sgml

@@ -6,15 +6,23 @@ Displays recently used files
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+#GtkRecentChooserWidget is a widget suitable for selecting recently used
+files.  It is the main building block of a #GtkRecentChooserDialog.  Most
+applications will only need to use the latter; you can use
+#GtkRecentChooserWidget as part of a larger window if you have special needs.
 </para>
+
+<para>
+Note that #GtkRecentChooserWidget does not have any methods of its own.
+Instead, you should use the functions that work on a #GtkRecentChooser.
+
 <para>
 Recently used files are supported since GTK+ 2.10.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#GtkRecentChooser, #GtkRecentChooserDialog
 </para>
 
 <!-- ##### SECTION Stability_Level ##### -->

docs/reference/gtk/tmpl/gtkrecentfilter.sgml

@@ -2,19 +2,39 @@
 GtkRecentFilter
 
 <!-- ##### SECTION Short_Description ##### -->
-A filter for recently used files
+A filter for selecting a subset of recently used files
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+A #GtkRecentFilter can be used to restrict the files being shown
+in a #GtkRecentChooser.  Files can be filtered based on their name
+(with gtk_recent_filter_add_pattern()), on their mime type (with
+gtk_file_filter_add_mime_type()), on the application that has
+registered them (with gtk_recent_filter_add_application()), or by
+a custom filter function (with gtk_recent_filter_add_custom()).
 </para>
+
+<para>
+Filtering by mime type handles aliasing and subclassing of mime
+types; e.g. a filter for text/plain also matches a file with mime
+type application/rtf, since application/rtf is a subclass of text/plain.
+Note that #GtkRecentFilter allows wildcards for the subtype of a
+mime type, so you can e.g. filter for image/*.
+</para>
+
+<para>
+Normally, filters are used by adding them to a #GtkRecentChooser,
+see gtk_recent_chooser_add_filter(), but it is also possible to
+manually use a filter on a file with gtk_recent_filter_filter().
+</para>
+
 <para>
 Recently used files are supported since GTK+ 2.10.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#GtkRecentChooser
 </para>
 
 <!-- ##### SECTION Stability_Level ##### -->
@@ -22,43 +42,53 @@ Recently used files are supported since GTK+ 2.10.
 
 <!-- ##### STRUCT GtkRecentFilter ##### -->
 <para>
-
+The <structname>GtkRecentFilter</structname> struct contains
+only private fields and should not be directly accessed.
 </para>
 
 
 <!-- ##### STRUCT GtkRecentFilterInfo ##### -->
 <para>
-
+A <structname>GtkRecentFilterInfo</structname> struct is used
+to pass information about the tested file to gtk_recent_filter_filter().
 </para>
 
-@contains: 
+@contains: Flags indicating which of the following fields need
-@uri: 
+  are filled
-@display_name: 
+@uri: the URI of the file being tested
-@mime_type: 
+@display_name: the string that will be used to display the file
-@applications: 
+  in the recent chooser
-@groups: 
+@mime_type: the mime type of the file
-@age: 
+@applications: the list of applications that have registered the file
+@groups: the groups to which the file belongs to
+@age: the number of days elapsed since the file has been registered
 
 <!-- ##### ENUM GtkRecentFilterFlags ##### -->
 <para>
-
+These flags indicate what parts of a #GtkRecentFilterInfo struct
+are filled or need to be filled.
 </para>
 
-@GTK_RECENT_FILTER_URI: 
+@GTK_RECENT_FILTER_URI: the URI of the file being tested
-@GTK_RECENT_FILTER_DISPLAY_NAME: 
+@GTK_RECENT_FILTER_DISPLAY_NAME: the string that will be used to
-@GTK_RECENT_FILTER_MIME_TYPE: 
+  display the file in the recent chooser
-@GTK_RECENT_FILTER_APPLICATION: 
+@GTK_RECENT_FILTER_MIME_TYPE: the mime type of the file
-@GTK_RECENT_FILTER_GROUP: 
+@GTK_RECENT_FILTER_APPLICATION: the list of applications that have
-@GTK_RECENT_FILTER_AGE: 
+  registered the file
+@GTK_RECENT_FILTER_GROUP: the groups to which the file belongs to
+@GTK_RECENT_FILTER_AGE: the number of days elapsed since the file
+  has been registered
 
 <!-- ##### USER_FUNCTION GtkRecentFilterFunc ##### -->
 <para>
-
+The type of function that is used with custom filters,
+see gtk_recent_filter_add_custom().
 </para>
 
-@filter_info: 
+@filter_info: a #GtkRecentFilterInfo that is filled according
-@user_data: 
+  to the @needed flags passed to gtk_recent_filter_add_custom()
-@Returns: 
+@user_data: user data passed to gtk_recent_filter_add_custom()
+@Returns: %TRUE if the file should be displayed
 
 
 <!-- ##### FUNCTION gtk_recent_filter_new ##### -->

docs/reference/gtk/tmpl/gtkrecentmanager.sgml

@@ -6,9 +6,64 @@ Managing Recently Used Files
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+#GtkRecentManager provides a facility for adding, removing and
+looking up recently used files.  Each recently used file is
+identified by its URI, and has meta-data associated to it, like
+the names and command lines of the applications that have
+registered it, the number of time each application has registered
+the same file, the mime type of the file and whether the file
+should be displayed only by the applications that have
+registered it.
 </para>
 
+<para>
+The #GtkRecentManager acts like a database of all the recently
+used files.  You can create new #GtkRecentManager objects, but
+it is more efficient to use the standard recent manager for
+the #GdkScreen so that informations about the recently used
+files is shared with other people using them.  In case the
+default screen is being used, adding a new recently used
+file is as simple as:
+</para>
+
+<informalexample>
+  <programlisting>
+GtkRecentManager *manager;
+GError *error = NULL;
+
+manager = gtk_recent_manager_get_default ();
+gtk_recent_manager_add_item (manager, file_uri, &amp;error);
+if (error)
+  {
+    g_warning ("Could not add the file: &percnt;s", error-&gt;message);
+    g_error_free (error);
+  }
+  </programlisting>
+</informalexample>
+
+While looking up a recently used file is as simple as:
+
+<informalexample>
+  <programlisting>
+GtkRecentManager *manager;
+GtkRecentInfo *info;
+GError *error = NULL;
+
+manager = gtk_recent_manager_get_default ();
+info = gtk_recent_manager_lookup_item (manager, file_uri, &amp;error);
+if (error)
+  {
+    g_warning ("Could not find the file: &percnt;s", error-&gt;message);
+    g_error_free (error);
+  }
+else
+  {
+    /* Use the info object */
+    g_object_unref (info);
+  }
+  </programlisting>
+</informalexample>
+
 <para>
 Recently used files are supported since GTK+ 2.10.
 </para>
@@ -23,28 +78,39 @@ Recently used files are supported since GTK+ 2.10.
 
 <!-- ##### STRUCT GtkRecentManager ##### -->
 <para>
-
+Acts as a database of information about the list of recently
-</para>
+used files.  Normally, you retrieve the recent manager for a
+particular screen using gtk_recent_manager_get_for_screen()
+and it will contain information about current recent manager
+for that screen.</para>
 
 
 <!-- ##### STRUCT GtkRecentInfo ##### -->
 <para>
-
+Contains informations found when looking up an entry of the
+recently used files list.
 </para>
 
 
 <!-- ##### STRUCT GtkRecentData ##### -->
 <para>
-
+Meta-data passed to gtk_recent_manager_add_full().  You should
+use #GtkRecentData if you want to control the meta-data associated
+to an entry of the recently used files list when you are adding
+a new file to it.
 </para>
 
-@display_name: 
+@display_name: the string to be used when displaying the file
-@description: 
+  inside a #GtkRecentChooser
-@mime_type: 
+@description: a user readable description of the file
-@app_name: 
+@mime_type: the mime type of the file
-@app_exec: 
+@app_name: the name of the application that is registering
-@groups: 
+  the file
-@is_private: 
+@app_exec: the command line that should be used when launching
+  the file
+@groups: the list of group names to which the file belongs to
+@is_private: whether the file should be displayed only by
+  the applications that have registered it
 
 <!-- ##### MACRO GTK_RECENT_MANAGER_ERROR ##### -->
 <para>