From 22f120333f274bf1ae45127f36c4473177bd90c3 Mon Sep 17 00:00:00 2001 From: Jehan Date: Thu, 27 Jul 2023 22:59:51 +0200 Subject: [PATCH] Issue #9655: both @blurb and @help arguments should be localized. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Looking further, the @help is only used in gimp_proc_view_new() so far (for the Procedure Browser) where the blurb and argument descriptions are already localized. It makes no sense to only keep this in English. So let's ask to have both arguments translated. Now clearly we should not ask for @help to be mandatory. Very often, it makes no sense to have a longer help string (the small blurb and the few arguments may be very self-explanatory). So I make this argument nullable. There is only the @help_id which I wonder if we could not have a simpler function gimp_procedure_set_documentation_uri(). Indeed while having a unified infrastructure with a XML summary and help IDs and whatelse makes sense for GIMP as a whole, I think that many third-party plug-ins would work much better with a very simple direct URL. Or it could even be a GFile to a local file (for plug-ins which want to embed their documentation in the plug-in folder for instance). To be continued… --- libgimp/gimpprocedure.c | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/libgimp/gimpprocedure.c b/libgimp/gimpprocedure.c index 9780fb482c..2a692d963f 100644 --- a/libgimp/gimpprocedure.c +++ b/libgimp/gimpprocedure.c @@ -1031,21 +1031,24 @@ gimp_procedure_get_icon_pixbuf (GimpProcedure *procedure) /** * gimp_procedure_set_documentation: - * @procedure: A #GimpProcedure. - * @blurb: The @procedure's blurb. - * @help: The @procedure's help text. - * @help_id: The @procedure's help ID. + * @procedure: A #GimpProcedure. + * @blurb: The @procedure's blurb. + * @help: (nullable): The @procedure's help text. + * @help_id: (nullable): The @procedure's help ID. * - * @blurb is used as the @procedure's tooltip when represented in the UI, - * for example as a menu entry. + * Sets various documentation strings on @procedure: + * + * * @blurb is used for instance as the @procedure's tooltip when represented in + * the UI such as a menu entry. + * * @help is a free-form text that's meant as additional documentation for + * developers of scripts and plug-ins. If the @blurb and the argument names + * and descriptions are enough for a quite self-explanatory procedure, you may + * set @help to %NULL, rather than setting an uninformative @help (avoid + * setting the same text as @blurb or redundant information). * * Plug-ins are responsible for their own translations. You are expected to send - * localized strings to GIMP if your plug-in is internationalized. - * - * @help is a free-form text that's meant as documentation for - * developers of scripts and plug-ins. - * - * Sets various documentation strings on @procedure. + * localized strings of @blurb and @help to GIMP if your plug-in is + * internationalized. * * Since: 3.0 **/