[gimp-help/gimp-help-2-10] src: improve File Open dialog documentation

[Jacob Boerema <jboerema src gnome org>]

commit 0d79a80249500da04f918dad5b1b4052bbded655
Author: Jacob Boerema <jgboerema gmail com>
Date:   Thu Mar 24 16:53:28 2022 -0400

    src: improve File Open dialog documentation
    
    Also add the gimp-file-open-by-extension help id that was missing and
    causes a help page not found when pressing F1 in that specific case.
    
    Still needs more improvement and a new example image.
    
    (cherry picked from commit ff9914f868bf395e3a2b5f6a97ecf40824bcbca0)

 src/menus/file/open.xml | 106 +++++++++++++++++++++++++++++-------------------
 1 file changed, 65 insertions(+), 41 deletions(-)
---
diff --git a/src/menus/file/open.xml b/src/menus/file/open.xml
index 88754dfa7..e62d787ed 100644
--- a/src/menus/file/open.xml
+++ b/src/menus/file/open.xml
@@ -10,7 +10,7 @@
   2005/10/18 zh_CN removed by romanofski - missing translation
 -->
 <sect2 id="gimp-file-open">
-  <title>Open…</title>
+  <title>File Open…</title>
 
   <indexterm>
     <primary>Image</primary>
@@ -20,9 +20,9 @@
 
   <para>
     The <guimenuitem>Open…</guimenuitem> command activates a dialog that lets
-    you load an existing image from your hard-drive or an external medium.
-    For alternative, and sometimes more convenient, ways of opening files, see
-    the following commands (<xref linkend="gimp-file-open-as-layer"/> etc.).
+    you select an image to be loaded from your hard-drive or an external device.
+    For other ways of opening files, see the commands described on the next
+    pages (<xref linkend="gimp-file-open-as-layer"/> etc.).
   </para>
 
   <sect3>
@@ -32,7 +32,7 @@
       <listitem>
         <para>
           You can access the <guimenuitem>Open</guimenuitem> dialog
-          from an image window through:
+          from the menu through:
           <menuchoice>
             <guimenu>File</guimenu>
             <guimenuitem>Open…</guimenuitem>
@@ -63,19 +63,28 @@
     </figure>
 
     <para>
-      This browser looks like other browsers and it is mostly
-      self-explanatory. It has some particular features nevertheless.
+      This file browser should look familiar when you have worked with files
+      before. We will explain the details of this dialog below.
     </para>
     <orderedlist>
       <listitem><!--1-->
         <para>
-          The button <guibutton>Type a file name</guibutton> toggles between
-          add and remove the <guilabel>Location</guilabel> text box.
+          The <guibutton>Type a file name</guibutton> button toggles the
+          visibility of the <guilabel>Location</guilabel> text box.
+          By default this is hidden.
         </para>
         <para>
           The <keycombo><keycap>Ctrl</keycap><keycap>L</keycap></keycombo>
           key combination has the same action as this button.
         </para>
+        <note>
+          <para>
+            When <guilabel>Search</guilabel> or <guilabel>Recently Used</guilabel>
+            is selected in the <guilabel>Places</guilabel> list, it is not
+            possible to show the <guilabel>Location</guilabel> text box.
+            You will have to select another item from that list first.
+          </para>
+        </note>
       </listitem>
 
       <listitem><!--2-->
@@ -109,39 +118,47 @@
 
       <listitem><!--3-->
         <para>
-          The path to the current folder is displayed. You can navigate along
-          this path by clicking on an element.
+          The path to the current folder is displayed here. You can use this
+          to navigate to another folder by clicking on the desired part.
         </para>
       </listitem>
 
       <listitem><!--4-->
         <para>
-          With <guilabel>Search</guilabel> you can look for a file (or
-          directory), even if you don't know the exact name of that file.
-          Click on <guilabel>Search</guilabel>, type a file name or just a
-          part of a file name in the text box above, and press
-          <keycap>Enter</keycap>. Then the central frame (7) will list all
-          files and directories of your home directory with names containing
-          the text you typed in. Unfortunately you can't restrict the results
-          to files of a specified type (10). 
+          With <guilabel>Search</guilabel> you can look for a file or
+          directory, even if you don't know the exact name.
+          Click on <guilabel>Search</guilabel>, type a file name or even just a
+          part of a name in the search box, and press <keycap>Enter</keycap>.
+          The file display area (7) will then list all files and directories
+          of your home directory (user directory on Windows) with names
+          containing the text you searched for. Unfortunately you can't
+          restrict the results to files of a specified type (10).
         </para>
         <para>
-          <guilabel>Recently used</guilabel> is self-explanatory.
+          <guilabel>Recently used</guilabel> shows the list of files you
+          have recently opened.
         </para>
       </listitem>
 
       <listitem><!--5-->
         <para>
-          Here, you can access to your main folders and to your store devices.
+          This area gives you access to your main folders and your storage
+          devices.
         </para>
       </listitem>
 
       <listitem><!--6-->
         <para>
-          Here, you can add bookmarks to folders, by using the
-          <guibutton>Add</guibutton> or the <guilabel>Add to
-          Bookmarks</guilabel> option you get by right-clicking a folder in
-          the central panel, and also remove them.
+          This part of the list shows the folders that you have bookmarked.
+          You can add bookmarks by using the <guibutton>+</guibutton> (see 9),
+          or the <guilabel>Add to Bookmarks</guilabel> option that is shown
+          when you right-click a folder in the central panel.
+        </para>
+        <para>
+          You can remove a bookmark by clicking the <guibutton>-</guibutton>,
+          or the <guilabel>Remove</guilabel> option that is shown when you
+          right click on a bookmark. This right click menu can also be used
+          to <guilabel>Rename</guilabel> the bookmark.
         </para>
       </listitem>
 
@@ -150,7 +167,7 @@
           The contents of the selected folder is displayed here. Change your
           current folder by double left clicking on a folder in this
           panel. Select a file with a single left click. You can then open
-          the file you have selected by  clicking on the
+          the file you have selected by   clicking on the
           <guibutton>Open</guibutton> button.
           A double left click opens the file directly. Please note that you
           can open image files only.
@@ -180,41 +197,48 @@
 
         <tip>
           <para>
-            If your image has been modified by another program, click on the
-            Preview window to update it.
+            If your image has been modified by another program, you can click
+            on the Preview window to update the preview thumbnail.
           </para>
         </tip>
       </listitem>
 
       <listitem><!--9-->
         <para>
-          By clicking the <guibutton>Add</guibutton> button, you add the
+          By clicking the <guibutton>+</guibutton> button, you add the
           selected folder to bookmarks.
         </para>
         <para>
-          By clicking the <guibutton>Remove</guibutton>, you remove the
+          By clicking the <guibutton>-</guibutton>, you remove the
           selected bookmark from the list.
         </para>
       </listitem>
 
       <listitem><!--10-->
         <para>
-          You will generally prefer to display the names of
-          <guilabel>All images</guilabel>. You can also select
-          <guilabel>All files</guilabel>. You can also limit yourself to
-          a particular type of image (GIF, JPG, PNG ...).
+          This part does not exist anymore. To limit the shown images to
+          only a certain file type, select one from the list below.
         </para>
       </listitem>
 
       <listitem><!--11-->
         <para>
-          <guilabel>Select File Type</guilabel>: In most cases you
-          don't need to pay any attention to this, because
-          <acronym>GIMP</acronym> can determine the file type
-          automatically. In a few rare situations, neither the file
-          extension nor internal information in the file are enough to tell
-          <acronym>GIMP</acronym> the file type. If this happens,
-          you can set it by selecting it from the list.
+          <guilabel>Select File Type</guilabel> can be used to explicitly set
+          the image file format. In general you don't need to worry about this,
+          because in most cases <acronym>GIMP</acronym> can determine the file
+          type automatically.
+        </para>
+        <para>
+          <!-- Added the below anchor to make sure we don't get a help page
+               not found when pressing F1 in this part of the dialog. -->
+          <anchor id="gimp-file-open-by-extension"/>
+          The default is <guilabel>Automatically Detected</guilabel>, which
+          causes <acronym>GIMP</acronym> to try to automatically detect
+          the correct format.
+        </para>
+        <para>In the rare cases where neither the file extension nor internal
+          information in the file are enough to tell <acronym>GIMP</acronym>
+          the file type, you can set it by selecting it from this list.
         </para>
       </listitem>
     </orderedlist>