After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 336085 - g_option_context_new parameter lacks better explanation
g_option_context_new parameter lacks better explanation
Status: RESOLVED FIXED
Product: glib
Classification: Platform
Component: docs
2.10.x
Other Linux
: Normal minor
: ---
Assigned To: gtk-bugs
gtk-bugs
Depends on:
Blocks: 335967 336065 336077
 
 
Reported: 2006-03-26 14:21 UTC by Claudio Saavedra
Modified: 2011-02-18 15:49 UTC
See Also:
GNOME target: ---
GNOME version: ---



Description Claudio Saavedra 2006-03-26 14:21:45 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
Comment 1 Matthias Clasen 2006-03-26 20:12:35 UTC
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..."