GNOME Bugzilla – Bug 336085
g_option_context_new parameter lacks better explanation
Last modified: 2011-02-18 15:49:28 UTC
Everyone is using this parameter in different ways. Some modules in GNOME CVS are using it to put the application name, others put there the application name preceeded by a dash, and others are simply not using it. I myself believe that this parameter is intended to put the application arguments (if any) in a clear way, ie, for a glib written cp command context = g_option_context ("SOURCE DEST"); will produce a "cp --help" output of usage: cp [OPTIONS ...] SOURCE DEST but am not 100% confident about this. It would be nice if the documentation would explain better this, before everyone starts using it in an incorrect defacto standard. Examples of different usages of it are in: gnome-keyring-manager patch: http://bugzilla.gnome.org/attachment.cgi?id=62037&action=view evolution patch: http://bugzilla.gnome.org/attachment.cgi?id=61990&action=view
Here is what I added to the documentation, I hope it makes things clearer. I think both of the examples you show are kind of missing the point... * The @parameter_text 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 * collecting "rest" arguments, GLib handles this automatically by * using the @arg_description of the corresponding #GOptionEntry in * the usage summary.) * * Another common usage is to give a summary of the program * functionality. This can be a short summary on the same line, * like " - frob the strings", or a longer description in a paragraph * below the usage summary. In this case, @parameter_string should start * with two newlines, to separate the description from the usage summary: * "\n\nA program to frob strings, which will..."