Allow optional summary and description texts before and after the option

2006-05-13  Matthias Clasen  <mclasen@redhat.com>

	* glib/glib.symbols:
	* glib/goption.h:
	* glib/goption.c: Allow optional summary and description
	texts before and after the option descriptions, and add
	a way to translate them.  (#336120, Behdad Esfahbod)

ChangeLog

@@ -1,3 +1,11 @@
+2006-05-13  Matthias Clasen  <mclasen@redhat.com>
+
+	* glib/glib.symbols: 
+	* glib/goption.h: 
+	* glib/goption.c: Allow optional summary and description
+	texts before and after the option descriptions, and add
+	a way to translate them.  (#336120, Behdad Esfahbod)
+
 2006-05-12  Tor Lillqvist  <tml@novell.com>
 
 	* glib/giowin32.c (g_io_win32_sock_set_flags): Implement

ChangeLog.pre-2-12

@@ -1,3 +1,11 @@
+2006-05-13  Matthias Clasen  <mclasen@redhat.com>
+
+	* glib/glib.symbols: 
+	* glib/goption.h: 
+	* glib/goption.c: Allow optional summary and description
+	texts before and after the option descriptions, and add
+	a way to translate them.  (#336120, Behdad Esfahbod)
+
 2006-05-12  Tor Lillqvist  <tml@novell.com>
 
 	* glib/giowin32.c (g_io_win32_sock_set_flags): Implement

docs/reference/ChangeLog

@@ -1,3 +1,7 @@
+2006-05-13  Matthias Clasen  <mclasen@redhat.com>
+
+	* glib/glib-sections.txt: Document new api.
+
 2006-05-11  Bastien Nocera  <hadess@hadess.net>
 
 	* glib/tmpl/option.sgml: add documentation for G_OPTION_ARG_INT64

docs/reference/glib/glib-sections.txt

@@ -954,6 +954,13 @@ G_OPTION_ERROR
 GOptionArgFunc
 GOptionContext
 g_option_context_new
+g_option_context_set_summary
+g_option_context_get_summary
+g_option_context_set_description
+g_option_context_get_description
+GTranslateFunc
+g_option_context_set_translate_func
+g_option_context_set_translation_domain
 g_option_context_free
 g_option_context_parse
 g_option_context_set_help_enabled
@@ -976,7 +983,6 @@ GOptionParseFunc
 g_option_group_set_parse_hooks
 GOptionErrorFunc
 g_option_group_set_error_hook
-GTranslateFunc
 g_option_group_set_translate_func
 g_option_group_set_translation_domain
 <SUBSECTION Private>

glib/glib.symbols

@@ -745,14 +745,20 @@ g_option_context_add_group
 g_option_context_add_main_entries
 g_option_error_quark
 g_option_context_free
+g_option_context_get_description
 g_option_context_get_help_enabled
 g_option_context_get_ignore_unknown_options
 g_option_context_get_main_group
+g_option_context_get_summary
 g_option_context_new
 g_option_context_parse
+g_option_context_set_description
 g_option_context_set_help_enabled
 g_option_context_set_ignore_unknown_options
 g_option_context_set_main_group
+g_option_context_set_summary
+g_option_context_set_translate_func
+g_option_context_set_translation_domain
 g_option_group_add_entries
 g_option_group_free
 g_option_group_new

glib/goption.c

@@ -72,39 +72,45 @@ typedef struct
 
 struct _GOptionContext
 {
-  GList *groups;
+  GList           *groups;
 
-  gchar *parameter_string;
+  gchar           *parameter_string;
+  gchar           *summary;
+  gchar           *description;
 
-  gboolean help_enabled;
+  GTranslateFunc   translate_func;
-  gboolean ignore_unknown;
+  GDestroyNotify   translate_notify;
+  gpointer	   translate_data;
+
+  guint            help_enabled   : 1;
+  guint            ignore_unknown : 1;
   
-  GOptionGroup *main_group;
+  GOptionGroup    *main_group;
 
   /* We keep a list of change so we can revert them */
-  GList *changes;
+  GList           *changes;
   
-  /* We also keep track of all argv elements that should be NULLed or
+  /* We also keep track of all argv elements 
-   * modified.
+   * that should be NULLed or modified.
    */
-  GList *pending_nulls;
+  GList           *pending_nulls;
 };
 
 struct _GOptionGroup
 {
-  gchar *name;
+  gchar           *name;
-  gchar *description;
+  gchar           *description;
-  gchar *help_description;
+  gchar           *help_description;
 
-  GDestroyNotify  destroy_notify;
+  GDestroyNotify   destroy_notify;
-  gpointer        user_data;
+  gpointer         user_data;
 
-  GTranslateFunc  translate_func;
+  GTranslateFunc   translate_func;
-  GDestroyNotify  translate_notify;
+  GDestroyNotify   translate_notify;
-  gpointer	  translate_data;
+  gpointer	   translate_data;
 
-  GOptionEntry *entries;
+  GOptionEntry    *entries;
-  gint         n_entries;
+  gint             n_entries;
 
   GOptionParseFunc pre_parse_func;
   GOptionParseFunc post_parse_func;
@@ -131,20 +137,22 @@ g_option_error_quark (void)
  *
  * Creates a new option context. 
  *
- * The @parameter_text can serve multiple purposes. It can be used
+ * The @parameter_string can serve multiple purposes. It can be used
  * to add descriptions for "rest" arguments, which are not parsed by
  * the #GOptionContext, typically something like "FILES" or
- * "FILE1 FILE2...". (If you are using #G_OPTION_REMAINING for
+ * "FILE1 FILE2...". If you are using #G_OPTION_REMAINING for
  * collecting "rest" arguments, GLib handles this automatically by
  * using the @arg_description of the corresponding #GOptionEntry in
- * the usage summary.)
+ * the usage summary.
  *
- * Another common usage is to give a summary of the program
+ * Another usage is to give a short summary of the program
- * functionality. This can be a short summary on the same line,  
+ * functionality, like " - frob the strings", which will be displayed
- * like " - frob the strings", or a longer description in a paragraph  
+ * in the same line as the usage. For a longer description of the
- * below the usage summary. In this case, @parameter_string should start  
+ * program functionality that should be displayed as a paragraph
- * with two newlines, to separate the description from the usage summary:  
+ * below the usage line, use g_option_context_set_summary().
- * "\n\nA program to frob strings, which will..."
+ *
+ * Note that the @parameter_string is translated (see 
+ * g_option_context_set_translate_func()).
  *
  * Returns: a newly created #GOptionContext, which must be
  *    freed with g_option_context_free() after use.
@@ -189,7 +197,12 @@ void g_option_context_free (GOptionContext *context)
   free_pending_nulls (context, FALSE);
   
   g_free (context->parameter_string);
+  g_free (context->summary);
+  g_free (context->description);
   
+  if (context->translate_notify)
+    (* context->translate_notify) (context->translate_data);
+
   g_free (context);
 }
 
@@ -466,23 +479,27 @@ print_help (GOptionContext *context,
   rest_description = NULL;
   if (context->main_group)
     {
+
       for (i = 0; i < context->main_group->n_entries; i++)
 	{
 	  entry = &context->main_group->entries[i];
 	  if (entry->long_name[0] == 0)
 	    {
-	      rest_description = entry->arg_description;
+	      rest_description = TRANSLATE (context->main_group, entry->arg_description);
 	      break;
 	    }
 	}
     }
-  
+
   g_print ("%s\n  %s %s%s%s%s%s\n\n", 
 	   _("Usage:"), g_get_prgname(), _("[OPTION...]"),
 	   rest_description ? " " : "",
 	   rest_description ? rest_description : "",
 	   context->parameter_string ? " " : "",
-	   context->parameter_string ? context->parameter_string : "");
+	   context->parameter_string ? TRANSLATE (context, context->parameter_string) : "");
+
+  if (context->summary)
+    g_print ("%s\n\n", TRANSLATE (context, context->summary));
 
   memset (seen, 0, sizeof (gboolean) * 256);
   shadow_map = g_hash_table_new (g_str_hash, g_str_equal);
@@ -643,7 +660,10 @@ print_help (GOptionContext *context,
 
       g_print ("\n");
     }
-  
+ 
+  if (context->description)
+    g_print ("%s\n", TRANSLATE (context, context->description));
+ 
   exit (0);
 }
 
@@ -1894,5 +1914,153 @@ g_option_group_set_translation_domain (GOptionGroup *group,
 				     g_free);
 } 
 
+/**
+ * g_option_context_set_translate_func:
+ * @context: a #GOptionContext
+ * @func: the #GTranslateFunc, or %NULL 
+ * @data: user data to pass to @func, or %NULL
+ * @destroy_notify: a function which gets called to free @data, or %NULL
+ * 
+ * Sets the function which is used to translate the contexts 
+ * user-visible strings, for <option>--help</option> output. 
+ * If @func is %NULL, strings are not translated.
+ *
+ * Note that option groups have their own translation functions, 
+ * this function only affects the @parameter_string (see g_option_context_nex()), 
+ * the summary (see g_option_context_set_summary()) and the description 
+ * (see g_option_context_set_description()).
+ *
+ * If you are using gettext(), you only need to set the translation
+ * domain, see g_context_group_set_translation_domain().
+ *
+ * Since: 2.12
+ **/
+void
+g_option_context_set_translate_func (GOptionContext *context,
+				     GTranslateFunc func,
+				     gpointer       data,
+				     GDestroyNotify destroy_notify)
+{
+  g_return_if_fail (context != NULL);
+  
+  if (context->translate_notify)
+    context->translate_notify (context->translate_data);
+      
+  context->translate_func = func;
+  context->translate_data = data;
+  context->translate_notify = destroy_notify;
+}
+
+/**
+ * g_option_context_set_translation_domain:
+ * @context: a #GOptionContext
+ * @domain: the domain to use
+ * 
+ * A convenience function to use gettext() for translating
+ * user-visible strings. 
+ * 
+ * Since: 2.12
+ **/
+void
+g_option_context_set_translation_domain (GOptionContext *context,
+					 const gchar     *domain)
+{
+  g_return_if_fail (context != NULL);
+
+  g_option_context_set_translate_func (context, 
+				       (GTranslateFunc)dgettext_swapped,
+				       g_strdup (domain),
+				       g_free);
+}
+
+/**
+ * g_option_context_set_summary:
+ * @context: a #GOptionContext
+ * @summary: a string to be shown in <option>--help</option> output 
+ *  before the list of options, or %NULL
+ * 
+ * Adds a string to be displayed in <option>--help</option> output
+ * before the list of options. This is typically a summary of the
+ * program functionality. 
+ *
+ * Note that the summary is translated (see 
+ * g_option_context_set_translate_func()).
+ *
+ * Since: 2.12
+ */
+void
+g_option_context_set_summary (GOptionContext *context,
+			      const gchar    *summary)
+{
+  g_return_if_fail (context != NULL);
+
+  g_free (context->summary);
+  context->summary = g_strdup (summary);
+}
+
+
+/**
+ * g_option_context_get_summary:
+ * @context: a #GOptionContext
+ * 
+ * Returns the summary. See g_option_context_set_summary().
+ *
+ * Returns: the summary
+ *
+ * Since: 2.12
+ */
+G_CONST_RETURN gchar *
+g_option_context_get_summary (GOptionContext *context)
+{
+  g_return_val_if_fail (context != NULL, NULL);
+
+  return context->summary;
+}
+
+/**
+ * g_option_context_set_description:
+ * @context: a #GOptionContext
+ * @description: a string to be shown in <option>--help</option> output 
+ *   after the list of options, or %NULL
+ * 
+ * Adds a string to be displayed in <option>--help</option> output
+ * after the list of options. This text often includes a bug reporting
+ * address.
+ *
+ * Note that the summary is translated (see 
+ * g_option_context_set_translate_func()).
+ *
+ * Since: 2.12
+ */
+void
+g_option_context_set_description (GOptionContext *context,
+			          const gchar    *description)
+{
+  g_return_if_fail (context != NULL);
+
+  g_free (context->description);
+  context->description = g_strdup (description);
+}
+
+
+/**
+ * g_option_context_get_description:
+ * @context: a #GOptionContext
+ * 
+ * Returns the description. See g_option_context_set_description().
+ *
+ * Returns: the description
+ *
+ * Since: 2.12
+ */
+G_CONST_RETURN gchar *
+g_option_context_get_description (GOptionContext *context)
+{
+  g_return_val_if_fail (context != NULL, NULL);
+
+  return context->description;
+}
+
+
 #define __G_OPTION_C__
 #include "galiasdef.c"

glib/goption.h

@@ -97,6 +97,12 @@ struct _GOptionEntry
 #define G_OPTION_REMAINING ""
 
 GOptionContext *g_option_context_new              (const gchar         *parameter_string);
+void            g_option_context_set_summary      (GOptionContext      *context,
+                                                   const gchar         *summary);
+G_CONST_RETURN gchar *g_option_context_get_summary (GOptionContext     *context);
+void            g_option_context_set_description  (GOptionContext      *context,
+                                                   const gchar         *description);
+G_CONST_RETURN gchar *g_option_context_get_description (GOptionContext     *context);
 void            g_option_context_free             (GOptionContext      *context);
 void		g_option_context_set_help_enabled (GOptionContext      *context,
 						   gboolean		help_enabled);
@@ -112,9 +118,15 @@ gboolean        g_option_context_parse            (GOptionContext      *context,
 						   gint                *argc,
 						   gchar             ***argv,
 						   GError             **error);
+void            g_option_context_set_translate_func (GOptionContext     *context,
+						     GTranslateFunc      func,
+						     gpointer            data,
+						     GDestroyNotify      destroy_notify);
+void            g_option_context_set_translation_domain (GOptionContext  *context,
+							 const gchar     *domain);
 
-void          g_option_context_add_group      (GOptionContext *context,
+void            g_option_context_add_group      (GOptionContext *context,
-					       GOptionGroup   *group);
+						 GOptionGroup   *group);
 void          g_option_context_set_main_group (GOptionContext *context,
 					       GOptionGroup   *group);
 GOptionGroup *g_option_context_get_main_group (GOptionContext *context);