[gtk+/bgo593793-filechooser-recent-folders] Update the docs with the policies for Save dialogs

[Federico Mena Quintero <federico src gnome org>]

commit 095eec84c038ea2c5f6ef4ec137f35491abb3063
Author: Federico Mena Quintero <federico gnome org>
Date:   Fri Jul 1 18:04:25 2011 -0500

    Update the docs with the policies for Save dialogs
    
    Basically, don't ever set the current folder, and only use
    gtk_file_chooser_set_filename() for 'File/Save As'.  This is so
    that the file chooser will be able to present its recently-used
    lists as appropriate, giving the user good suggestions by default.
    
    Signed-off-by: Federico Mena Quintero <federico gnome org>

 docs/reference/gtk/tmpl/gtkfilechooserdialog.sgml |   66 ++++++++++++++-
 gtk/gtkfilechooser.c                              |   93 +++++++++++----------
 2 files changed, 109 insertions(+), 50 deletions(-)
---
diff --git a/docs/reference/gtk/tmpl/gtkfilechooserdialog.sgml b/docs/reference/gtk/tmpl/gtkfilechooserdialog.sgml
index cc798bc..3f68f5a 100644
--- a/docs/reference/gtk/tmpl/gtkfilechooserdialog.sgml
+++ b/docs/reference/gtk/tmpl/gtkfilechooserdialog.sgml
@@ -66,14 +66,10 @@ dialog = gtk_file_chooser_dialog_new ("Save File",
 gtk_file_chooser_set_do_overwrite_confirmation (GTK_FILE_CHOOSER (dialog), TRUE);
 
 if (user_edited_a_new_document)
-  {
-    gtk_file_chooser_set_current_folder (GTK_FILE_CHOOSER (dialog), default_folder_for_saving);
-    gtk_file_chooser_set_current_name (GTK_FILE_CHOOSER (dialog), "Untitled document");
-  }
+  gtk_file_chooser_set_current_name (GTK_FILE_CHOOSER (dialog), "Untitled document");
 else
   gtk_file_chooser_set_filename (GTK_FILE_CHOOSER (dialog), filename_for_existing_document);
 
-
 if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT)
   {
     char *filename;
@@ -87,6 +83,66 @@ gtk_widget_destroy (dialog);
       </programlisting>
     </example>
 
+  <section id="gtkfilechooserdialog-setting-up">
+    <title>Setting up a file chooser dialog</title>
+
+    <para>
+      There are various cases in which you may need to use a
+      #GtkFileChooserDialog:
+    </para>
+
+    <itemizedlist>
+      <listitem>
+        <para>
+          To select a file for opening, as for a
+          <guimenuitem>File/Open</guimenuitem> command.  Use
+          #GTK_FILE_CHOOSER_ACTION_OPEN.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          To save a file for the first time, as for a
+          <guimenuitem>File/Save</guimenuitem> command.  Use
+          #GTK_FILE_CHOOSER_ACTION_SAVE, and suggest a name such as
+          "Untitled" with gtk_file_chooser_set_current_name().
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          To save a file under a different name, as for a
+          <guimenuitem>File/Save As</guimenuitem> command.  Use
+          #GTK_FILE_CHOOSER_ACTION_SAVE, and set the existing filename
+          with gtk_file_chooser_set_filename().
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+           To choose a folder instead of a file.  Use
+           #GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.
+        </para>
+      </listitem>
+    </itemizedlist>
+
+    <note>
+      <para>
+         Old versions of the file chooser's documentation suggested
+         using gtk_file_chooser_set_current_folder() in various
+         situations, with the intention of letting the application
+         suggest a reasonable default folder.  This is no longer
+         considered to be a good policy, as now the file chooser is
+         able to make good suggestions on its own.  In general, you
+         should only cause the file chooser to show a specific folder
+         when it is appropriate to use gtk_file_chooser_set_filename()
+         - i.e. when you are doing a <guimenuitem>File/Save
+         As</guimenuitem> command <emphasis>and</emphasis> you already
+         have a file saved somewhere.
+      </para>
+    </note>
+  </section>
+
   <section id="gtkfilechooserdialog-response-codes">
     <title>Response Codes</title>
 
diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index 19071fe..650b191 100644
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -1070,31 +1070,26 @@ gtk_file_chooser_get_filename (GtkFileChooser *chooser)
  * @chooser: a #GtkFileChooser
  * @filename: (type filename): the filename to set as current
  * 
- * Sets @filename as the current filename for the file chooser, by changing
- * to the file's parent folder and actually selecting the file in list.  If
- * the @chooser is in %GTK_FILE_CHOOSER_ACTION_SAVE mode, the file's base name
- * will also appear in the dialog's file name entry.
- *
- * If the file name isn't in the current folder of @chooser, then the current
- * folder of @chooser will be changed to the folder containing @filename. This
- * is equivalent to a sequence of gtk_file_chooser_unselect_all() followed by
- * gtk_file_chooser_select_filename().
+ * Sets @filename as the current filename for the file chooser, by changing to
+ * the file's parent folder and actually selecting the file in list; all other
+ * files will be unselected.  If the @chooser is in
+ * %GTK_FILE_CHOOSER_ACTION_SAVE mode, the file's base name will also appear in
+ * the dialog's file name entry.
  *
  * Note that the file must exist, or nothing will be done except
  * for the directory change.
  *
- * If you are implementing a <guimenuitem>File/Save As...</guimenuitem> dialog,
- * you should use this function if you already have a file name to which the 
- * user may save; for example, when the user opens an existing file and then 
- * does <guimenuitem>File/Save As...</guimenuitem> on it.  If you don't have 
- * a file name already &mdash; for example, if the user just created a new 
- * file and is saving it for the first time, do not call this function.  
- * Instead, use something similar to this:
+ * You should use this function only when implementing a <guimenuitem>File/Save
+ * As...</guimenuitem> dialog for which you already have a file name to which
+ * the user may save.  For example, when the user opens an existing file and
+ * then does <guimenuitem>File/Save As...</guimenuitem> on it to save a copy or
+ * a modified version.  If you don't have a file name already &mdash; for
+ * example, if the user just created a new file and is saving it for the first
+ * time, do not call this function.  Instead, use something similar to this:
  * |[
  * if (document_is_new)
  *   {
  *     /&ast; the user just created a new document &ast;/
- *     gtk_file_chooser_set_current_folder (chooser, default_folder_for_saving);
  *     gtk_file_chooser_set_current_name (chooser, "Untitled document");
  *   }
  * else
@@ -1103,9 +1098,12 @@ gtk_file_chooser_get_filename (GtkFileChooser *chooser)
  *     gtk_file_chooser_set_filename (chooser, existing_filename);
  *   }
  * ]|
+ *
+ * In the first case, the file chooser will present the user with useful suggestions
+ * as to where to save his new file.  In the second case, the file's existing location
+ * is already known, so the file chooser will use it.
  * 
- * Return value: %TRUE if both the folder could be changed and the file was
- * selected successfully, %FALSE otherwise.
+ * Return value: Not useful.
  *
  * Since: 2.4
  **/
@@ -1128,8 +1126,9 @@ gtk_file_chooser_set_filename (GtkFileChooser *chooser,
  * folder of @chooser, then the current folder of @chooser will
  * be changed to the folder containing @filename.
  *
- * Return value: %TRUE if both the folder could be changed and the file was
- * selected successfully, %FALSE otherwise.
+ * Return value: Not useful.
+ *
+ * See also: gtk_file_chooser_set_filename()
  *
  * Since: 2.4
  **/
@@ -1240,8 +1239,11 @@ gtk_file_chooser_get_filenames (GtkFileChooser *chooser)
  * The user will be shown the full contents of the current folder,
  * plus user interface elements for navigating to other folders.
  *
- * Return value: %TRUE if the folder could be changed successfully, %FALSE
- * otherwise.
+ * In general, you should not use this function.  See the <link
+ * linkend="gtkfilechooserdialog-setting-up">section on setting up a file
+ * chooser dialog</link> for the rationale behind this.
+ *
+ * Return value: Not useful.
  *
  * Since: 2.4
  **/
@@ -1312,7 +1314,8 @@ gtk_file_chooser_get_current_folder (GtkFileChooser *chooser)
  * Sets the current name in the file selector, as if entered
  * by the user. Note that the name passed in here is a UTF-8
  * string rather than a filename. This function is meant for
- * such uses as a suggested name in a "Save As..." dialog.
+ * such uses as a suggested name in a "Save As..." dialog.  You can
+ * pass "Untitled.doc" or a similarly suitable suggestion for the @name.
  *
  * If you want to preselect a particular existing file, you should use
  * gtk_file_chooser_set_filename() or gtk_file_chooser_set_uri() instead.
@@ -1375,25 +1378,20 @@ gtk_file_chooser_get_uri (GtkFileChooser *chooser)
  * list.  If the @chooser is %GTK_FILE_CHOOSER_ACTION_SAVE mode, the URI's base
  * name will also appear in the dialog's file name entry.
  *
- * If the URI isn't in the current folder of @chooser, then the current folder
- * of @chooser will be changed to the folder containing @uri. This is equivalent
- * to a sequence of gtk_file_chooser_unselect_all() followed by
- * gtk_file_chooser_select_uri().
- *
  * Note that the URI must exist, or nothing will be done except for the 
  * directory change.
- * If you are implementing a <guimenuitem>File/Save As...</guimenuitem> dialog,
- * you should use this function if you already have a file name to which the 
- * user may save; for example, when the user opens an existing file and then 
- * does <guimenuitem>File/Save As...</guimenuitem> on it.  If you don't have 
- * a file name already &mdash; for example, if the user just created a new 
- * file and is saving it for the first time, do not call this function.  
- * Instead, use something similar to this:
+ *
+ * You should use this function only when implementing a <guimenuitem>File/Save
+ * As...</guimenuitem> dialog for which you already have a file name to which
+ * the user may save.  For example, whenthe user opens an existing file and then
+ * does <guimenuitem>File/Save As...</guimenuitem> on it to save a copy or a
+ * modified version.  If you don't have a file name already &mdash; for example,
+ * if the user just created a new file and is saving it for the first time, do
+ * not call this function.  Instead, use something similar to this:
  * |[
  * if (document_is_new)
  *   {
  *     /&ast; the user just created a new document &ast;/
- *     gtk_file_chooser_set_current_folder_uri (chooser, default_folder_for_saving);
  *     gtk_file_chooser_set_current_name (chooser, "Untitled document");
  *   }
  * else
@@ -1403,8 +1401,12 @@ gtk_file_chooser_get_uri (GtkFileChooser *chooser)
  *   }
  * ]|
  *
- * Return value: %TRUE if both the folder could be changed and the URI was
- * selected successfully, %FALSE otherwise.
+ *
+ * In the first case, the file chooser will present the user with useful suggestions
+ * as to where to save his new file.  In the second case, the file's existing location
+ * is already known, so the file chooser will use it.
+ * 
+ * Return value: Not useful.
  *
  * Since: 2.4
  **/
@@ -1427,8 +1429,7 @@ gtk_file_chooser_set_uri (GtkFileChooser *chooser,
  * file in the current folder of @chooser, then the current folder of
  * @chooser will be changed to the folder containing @filename.
  *
- * Return value: %TRUE if both the folder could be changed and the URI was
- * selected successfully, %FALSE otherwise.
+ * Return value: Not useful.
  *
  * Since: 2.4
  **/
@@ -1545,6 +1546,10 @@ gtk_file_chooser_get_uris (GtkFileChooser *chooser)
  * The user will be shown the full contents of the current folder,
  * plus user interface elements for navigating to other folders.
  *
+ * In general, you should not use this function.  See the <link
+ * linkend="gtkfilechooserdialog-setting-up">section on setting up a file
+ * chooser dialog</link> for the rationale behind this.
+ *
  * Return value: %TRUE if the folder could be changed successfully, %FALSE
  * otherwise.
  *
@@ -1661,8 +1666,7 @@ gtk_file_chooser_get_current_folder_file (GtkFileChooser *chooser)
  * Selects the file referred to by @file. An internal function. See
  * _gtk_file_chooser_select_uri().
  *
- * Return value: %TRUE if both the folder could be changed and the path was
- * selected successfully, %FALSE otherwise.
+ * Return value: Not useful.
  *
  * Since: 2.14
  **/
@@ -1760,8 +1764,7 @@ gtk_file_chooser_get_files (GtkFileChooser *chooser)
  *   }
  * ]|
  *
- * Return value: %TRUE if both the folder could be changed and the file was
- * selected successfully, %FALSE otherwise.
+ * Return value: Not useful.
  *
  * Since: 2.14
  **/