GNOME Bugzilla – Bug 556706
Inconsistent help arguments -h, -?
Last modified: 2009-06-28 01:00:59 UTC
GOptionContext has built-in 'help' output, that can optionall be enabled. If you enable it, it recognizes -? and --help switches. Consequently, glib and gtk applications typically support those switches. Au contraire, this is not consistently supported by command line tools within the Gtk+ stack as a whole. For comparison: glib-genmarshal: --help, -h glib-gettextize: --help glib-mkenums: --help, -h, -? (-? is missing in the --help output) pango-querymodules: --help, -h gdk-pixbuf-csource: --help, -h gdk-pixbuf-query-loaders: none at all gtk-builder-convert: --help, -h, -? (-? is missing in the --help output) gtk-query-immodules-2.0: none at all gtk-demo: none at all gtk-update-icon-cache: --help, -? (no line break after error on -h) I suggest to unify the use of help switches and also consistenly provide them for all supported tools. With regard to the short name of --help it is not clear what the obvious preferred choice should be. On a personal note, I always use --help in favour of any short switch, with any tool I use, unless of course it doesn't work. To me the sole point is consistency. I propose, we choose a pair, let's say "-h, --help", as the recommendation, and this should also be displayed in all --help outputs including what GOptionContext does. Further more "-?" be also supported, but not visible anywhere, as an exception from normal short/ long pairs. Note that I picked "-h" because it is the first letter of "--help", and it's common practise to do so, that's it. Incidentally, several popular GNU tools only understand --help and no short help switches at all, so I did not try to make an empirical judgement. As for compatibility with GOptionContext users, I propose any existing uses of "-h" should implicitly override the help output. That way, nothing breaks.
Also note that descriptions in help output are not consistent with regard to the case. So I further propose to start descriptions with a captial letter and use normal sentence capitalization otherwise. That's the widely preferred way, unlike starting with a lower case letter as some of the Gtk+ tools do.
Created attachment 120788 [details] [review] Display 'h' by default, accept 'h' and '?' This change leads the built-in help output of GOptionContext to display 'h' instead of '?' and accepts both 'h' and '?'.
Created attachment 120789 [details] [review] Fix help output and recognize ? This fixes the help output to match the output of GOptionContext and lets glib-genmarshal accept '?' as well.
Created attachment 120791 [details] [review] Adjust mkenums help output and accept ? This changes glib-mkenums to produce output that matches GOptionContext and it will also accept '?'. I also reindented the help strings to fit in an 80 column terminal.
Created attachment 120794 [details] [review] Adjust mkenums help output, accept ?, Capitalize Now with capitalization of descriptions
Created attachment 120795 [details] [review] Adjust genmarshal help output, accept ?, Capitalize Now with capitalization of descriptions
Created attachment 121573 [details] [review] Display 'h' by default, accept 'h' and '?', revised Revised patch, this version is supposed to let '-h' pass through if an application already handles it, as proposed initially. Note that there's a flaw in my changes and context_has_h_entry doesn't ever seem to return TRUE. I just can't find my mistake. Somebody please have a look.
(In reply to comment #5) > Created an attachment (id=120794) [edit] > Adjust mkenums help output, accept ?, Capitalize > > Now with capitalization of descriptions > Looks like the patch checks for -h twice, and not for -? Other than that, looks fine to me.
> Note that there's a flaw in my changes and context_has_h_entry doesn't ever > seem to return TRUE. I just can't find my mistake. Somebody please have a look. > context_has_h_entry fails to check the main_group. Also, if (context->help_enabled && (arg[j] == '?' || (arg[j] == 'h' && context_has_h_entry (context)))) print_help (context, TRUE, NULL); is missing a ! Lastly, I'd pull the context_has_h_entry call out of all those nested loops in g_option_context_parse, to avoid doing this check over and over.
Created attachment 137419 [details] [review] Display 'h' by default, accept 'h' and '?' #3 (In reply to comment #9) > > Note that there's a flaw in my changes and context_has_h_entry doesn't ever > > seem to return TRUE. I just can't find my mistake. Somebody please have a look. > > context_has_h_entry fails to check the main_group. > > Also, > if (context->help_enabled && (arg[j] == '?' || > (arg[j] == 'h' && context_has_h_entry (context)))) > print_help (context, TRUE, NULL); > > is missing a ! > > Lastly, I'd pull the context_has_h_entry call out of all those nested loops in > g_option_context_parse, to avoid doing this check over and over. Thanks a lot for the suggestions, I fixed all in this updated patch. And I updated the examplary --help output in the documentation to say --help, -h. It works as expected now when testing with gedit and rsvg-convert (which uses -h as --height).
Looks ok to me now, thanks.
Committed to master.