[gimp] app, libgimp, pdb: update gimpfile PDB functions' documentation.

[Jehan <jehanp src gnome org>]

commit ea0cc27c01a50605c9bbf2e7ae5fb4127cefd565
Author: Jehan <jehan girinstud io>
Date:   Mon Apr 13 20:25:32 2020 +0200

    app, libgimp, pdb: update gimpfile PDB functions' documentation.
    
    All file-related functions now uses a single GimpFile as argument.
    Comments regarding path as entered vs full pathname are now obsolete.

 app/pdb/file-cmds.c    |  8 ++++----
 libgimp/gimpfile_pdb.c | 21 ++++++---------------
 pdb/groups/file.pdb    | 31 +++++++++++--------------------
 3 files changed, 21 insertions(+), 39 deletions(-)
---
diff --git a/app/pdb/file-cmds.c b/app/pdb/file-cmds.c
index 63ab5b6572..b6fa86a33e 100644
--- a/app/pdb/file-cmds.c
+++ b/app/pdb/file-cmds.c
@@ -362,7 +362,7 @@ register_file_procs (GimpPDB *pdb)
                                "gimp-file-load");
   gimp_procedure_set_static_help (procedure,
                                   "Loads an image file by invoking the right load handler.",
-                                  "This procedure invokes the correct file load handler using magic if 
possible, and falling back on the file's extension and/or prefix if not. The name of the file to load is 
typically a full pathname, and the name entered is what the user actually typed before prepending a directory 
path. The reason for this is that if the user types https://www.gimp.org/foo.png he wants to fetch a URL, and 
the full pathname will not look like a URL.",
+                                  "This procedure invokes the correct file load handler using magic if 
possible, and falling back on the file's extension and/or prefix if not.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Josh MacDonald",
@@ -494,7 +494,7 @@ register_file_procs (GimpPDB *pdb)
                                "gimp-file-save");
   gimp_procedure_set_static_help (procedure,
                                   "Saves a file by extension.",
-                                  "This procedure invokes the correct file save handler according to the 
file's extension and/or prefix. The name of the file to save is typically a full pathname, and the name 
entered is what the user actually typed before prepending a directory path. The reason for this is that if 
the user types https://www.gimp.org/foo.png she wants to fetch a URL, and the full pathname will not look 
like a URL.",
+                                  "This procedure invokes the correct file save handler according to the 
file's extension and/or prefix.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Josh MacDonald",
@@ -536,7 +536,7 @@ register_file_procs (GimpPDB *pdb)
                                "gimp-file-load-thumbnail");
   gimp_procedure_set_static_help (procedure,
                                   "Loads the thumbnail for a file.",
-                                  "This procedure tries to load a thumbnail that belongs to the file with 
the given file. This name is a full pathname. The returned data is an array of colordepth 3 (RGB), regardless 
of the image type. Width and height of the thumbnail are also returned. Don't use this function if you need a 
thumbnail of an already opened image, use 'gimp-image-thumbnail' instead.",
+                                  "This procedure tries to load a thumbnail that belongs to the given file. 
The returned data is an array of colordepth 3 (RGB), regardless of the image type. Width and height of the 
thumbnail are also returned. Don't use this function if you need a thumbnail of an already opened image, use 
'gimp-image-thumbnail' instead.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Adam D. Moss, Sven Neumann",
@@ -582,7 +582,7 @@ register_file_procs (GimpPDB *pdb)
                                "gimp-file-save-thumbnail");
   gimp_procedure_set_static_help (procedure,
                                   "Saves a thumbnail for the given image",
-                                  "This procedure saves a thumbnail for the given image according to the 
Free Desktop Thumbnail Managing Standard. The thumbnail is saved so that it belongs to the file with the 
given filen. This means you have to save the image under this name first, otherwise this procedure will fail. 
This procedure may become useful if you want to explicitly save a thumbnail with a file.",
+                                  "This procedure saves a thumbnail for the given image according to the 
Free Desktop Thumbnail Managing Standard. The thumbnail is saved so that it belongs to the given file. This 
means you have to save the image under this name first, otherwise this procedure will fail. This procedure 
may become useful if you want to explicitly save a thumbnail with a file.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Josh MacDonald",
diff --git a/libgimp/gimpfile_pdb.c b/libgimp/gimpfile_pdb.c
index 91d3b3c76d..a2a08db2f8 100644
--- a/libgimp/gimpfile_pdb.c
+++ b/libgimp/gimpfile_pdb.c
@@ -43,11 +43,7 @@
  *
  * This procedure invokes the correct file load handler using magic if
  * possible, and falling back on the file's extension and/or prefix if
- * not. The name of the file to load is typically a full pathname, and
- * the name entered is what the user actually typed before prepending a
- * directory path. The reason for this is that if the user types
- * https://www.gimp.org/foo.png he wants to fetch a URL, and the full
- * pathname will not look like a URL.
+ * not.
  *
  * Returns: (transfer none): The output image.
  **/
@@ -186,12 +182,7 @@ gimp_file_load_layers (GimpRunMode  run_mode,
  * Saves a file by extension.
  *
  * This procedure invokes the correct file save handler according to
- * the file's extension and/or prefix. The name of the file to save is
- * typically a full pathname, and the name entered is what the user
- * actually typed before prepending a directory path. The reason for
- * this is that if the user types https://www.gimp.org/foo.png she
- * wants to fetch a URL, and the full pathname will not look like a
- * URL.
+ * the file's extension and/or prefix.
  *
  * Returns: TRUE on success.
  **/
@@ -233,10 +224,10 @@ gimp_file_save (GimpRunMode   run_mode,
  *
  * This procedure saves a thumbnail for the given image according to
  * the Free Desktop Thumbnail Managing Standard. The thumbnail is saved
- * so that it belongs to the file with the given filen. This means you
- * have to save the image under this name first, otherwise this
- * procedure will fail. This procedure may become useful if you want to
- * explicitly save a thumbnail with a file.
+ * so that it belongs to the given file. This means you have to save
+ * the image under this name first, otherwise this procedure will fail.
+ * This procedure may become useful if you want to explicitly save a
+ * thumbnail with a file.
  *
  * Returns: TRUE on success.
  **/
diff --git a/pdb/groups/file.pdb b/pdb/groups/file.pdb
index 09ef89fafb..5c8c6de0c2 100644
--- a/pdb/groups/file.pdb
+++ b/pdb/groups/file.pdb
@@ -23,11 +23,7 @@ sub file_load {
     $help = <<'HELP';
 This procedure invokes the correct file load handler using magic if
 possible, and falling back on the file's extension and/or prefix if
-not. The name of the file to load is typically a full pathname, and
-the name entered is what the user actually typed before prepending a
-directory path. The reason for this is that if the user types
-https://www.gimp.org/foo.png he wants to fetch a URL, and the full
-pathname will not look like a URL.
+not.
 HELP
 
     &josh_pdb_misc('1997');
@@ -225,11 +221,7 @@ sub file_save {
 
     $help = <<'HELP';
 This procedure invokes the correct file save handler according to the
-file's extension and/or prefix. The name of the file to save is
-typically a full pathname, and the name entered is what the user
-actually typed before prepending a directory path. The reason for this
-is that if the user types https://www.gimp.org/foo.png she wants to
-fetch a URL, and the full pathname will not look like a URL.
+file's extension and/or prefix.
 HELP
 
     &josh_pdb_misc('1997');
@@ -307,12 +299,11 @@ sub file_load_thumbnail {
     $blurb = 'Loads the thumbnail for a file.';
 
     $help = <<'HELP';
-This procedure tries to load a thumbnail that belongs to the file with
-the given file. This name is a full pathname. The returned data is 
-an array of colordepth 3 (RGB), regardless of the image type. Width and 
-height of the thumbnail are also returned. Don't use this function if 
-you need a thumbnail of an already opened image, use gimp_image_thumbnail()
-instead.
+This procedure tries to load a thumbnail that belongs to the given file.
+The returned data is an array of colordepth 3 (RGB), regardless of the
+image type. Width and height of the thumbnail are also returned. Don't
+use this function if you need a thumbnail of an already opened image,
+use gimp_image_thumbnail() instead.
 HELP
 
     $author = $copyright = 'Adam D. Moss, Sven Neumann';
@@ -362,10 +353,10 @@ sub file_save_thumbnail {
     $help = <<'HELP';
 This procedure saves a thumbnail for the given image according to the
 Free Desktop Thumbnail Managing Standard. The thumbnail is saved so
-that it belongs to the file with the given filen. This means you
-have to save the image under this name first, otherwise this procedure
-will fail.  This procedure may become useful if you want to
-explicitly save a thumbnail with a file.
+that it belongs to the given file. This means you have to save the image
+under this name first, otherwise this procedure will fail.  This
+procedure may become useful if you want to explicitly save a thumbnail
+with a file.
 HELP
 
     &josh_pdb_misc('1997');