[gimp] app, libgimp, pdb: change docs of _gimp_plug_in_domain_register().

[Jehan <jehanp src gnome org>]

commit bdd22cd95bb8796a184f2ac36dbdcbaf9bc26bdd
Author: Jehan <jehan girinstud io>
Date:   Sun Jun 5 00:12:11 2022 +0200

    app, libgimp, pdb: change docs of _gimp_plug_in_domain_register().
    
    We changed the logic of _gimp_plug_in_domain_register() which is now
    only called when a domain is explicitly registered (which is not the
    case by default anymore). Let's update the function documentation and
    also make it clear that third-party developers in particular should not
    play with it if they want their plug-ins to be properly localized.

 app/pdb/plug-in-cmds.c   |  3 ++-
 libgimp/gimpplugin_pdb.c | 15 +++++++--------
 pdb/groups/plug_in.pdb   | 16 ++++++++--------
 3 files changed, 17 insertions(+), 17 deletions(-)
---
diff --git a/app/pdb/plug-in-cmds.c b/app/pdb/plug-in-cmds.c
index 1ff9320858..cd3696341d 100644
--- a/app/pdb/plug-in-cmds.c
+++ b/app/pdb/plug-in-cmds.c
@@ -314,7 +314,8 @@ register_plug_in_procs (GimpPDB *pdb)
                                "gimp-plug-in-domain-register");
   gimp_procedure_set_static_help (procedure,
                                   "Registers a textdomain for localisation.",
-                                  "This procedure adds a textdomain to the list of domains Gimp searches for 
strings when translating its menu entries. There is no need to call this function for plug-ins that have 
their strings included in the 'gimp-std-plugins' domain as that is used by default. If the compiled message 
catalog is not in the standard location, you may specify an absolute path to another location. This procedure 
can only be called in the query function of a plug-in and it has to be called before any procedure is 
installed.",
+                                  "This procedure adds a textdomain to the list of domains GIMP searches for 
strings when translating its menu entries.\n"
+                                     "Only core plug-ins should call this function directly. Third-party 
plug-ins are expected instead to define a custom `set_i18n()` method returning their domain and a path 
relative to their folder. In other words, this should be considered an internal PDB function which should not 
be used except by core developers.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Sven Neumann <sven gimp org>",
diff --git a/libgimp/gimpplugin_pdb.c b/libgimp/gimpplugin_pdb.c
index 78ae928227..9e98bdc55d 100644
--- a/libgimp/gimpplugin_pdb.c
+++ b/libgimp/gimpplugin_pdb.c
@@ -34,14 +34,13 @@
  *
  * Registers a textdomain for localisation.
  *
- * This procedure adds a textdomain to the list of domains Gimp
- * searches for strings when translating its menu entries. There is no
- * need to call this function for plug-ins that have their strings
- * included in the 'gimp-std-plugins' domain as that is used by
- * default. If the compiled message catalog is not in the standard
- * location, you may specify an absolute path to another location. This
- * procedure can only be called in the query function of a plug-in and
- * it has to be called before any procedure is installed.
+ * This procedure adds a textdomain to the list of domains GIMP
+ * searches for strings when translating its menu entries.
+ * Only core plug-ins should call this function directly. Third-party
+ * plug-ins are expected instead to define a custom `set_i18n()` method
+ * returning their domain and a path relative to their folder. In other
+ * words, this should be considered an internal PDB function which
+ * should not be used except by core developers.
  *
  * Returns: TRUE on success.
  **/
diff --git a/pdb/groups/plug_in.pdb b/pdb/groups/plug_in.pdb
index de012e81d0..23fb0ad40c 100644
--- a/pdb/groups/plug_in.pdb
+++ b/pdb/groups/plug_in.pdb
@@ -61,14 +61,14 @@ sub plug_in_domain_register {
     $blurb = 'Registers a textdomain for localisation.';
 
     $help = <<'HELP';
-This procedure adds a textdomain to the list of domains Gimp searches 
-for strings when translating its menu entries. There is no need to 
-call this function for plug-ins that have their strings included in 
-the 'gimp-std-plugins' domain as that is used by default. If the compiled 
-message catalog is not in the standard location, you may specify an 
-absolute path to another location. This procedure can only be called 
-in the query function of a plug-in and it has to be called before any
-procedure is installed.
+This procedure adds a textdomain to the list of domains GIMP searches
+for strings when translating its menu entries.
+
+Only core plug-ins should call this function directly. Third-party
+plug-ins are expected instead to define a custom `set_i18n()` method
+returning their domain and a path relative to their folder. In other
+words, this should be considered an internal PDB function which should
+not be used except by core developers.
 HELP
 
     &neo_pdb_misc('2000');