Created attachment 62045 [details] [review]
a patch along these lines would be fine

Kinda cruddy patch - basically, it just exports the internal print_help() method under a new name.

Do you need the full print_help() api, or would a simpler 
g_option_context_print_help (GOptionContext *context);
that does the equivalent of --help-all be enough ? 

Created attachment 62058 [details] [review]
Patch that only does --help-all

Having the equivalent of --help-all would probably be good enough.

I'm of the opposite opinion actually: IMHO the equivalent of --help is enough (the output of --help-all will be too large e.g. when using gnome-program so you don't see the relevant options in all the libraries' options).

I have my doubts on this. Dom mentioned two usecases on irc:

1) automatic help support has been disabled, and you want to implement
   --help yourself
2) print out help if you meet an invalid argument

But for 1), one could just say "Why ?", and for 2), it would probably
better to not dump the whole screenful of --help-all output to the screen,
but rather just a more narrow explanation of the possible values for the
one invalid argument.

Leaving this bug open for now, to see if there is broad demand.

One reason I may want to disable automatic help is that in a simple program with a few options, by default glib separates --help into its own "Help Options" group, while the rest go into "Application Options".   That doesn't make much sense.  That's another problem though.

I would propose that thats simply a bug, and the --help option should be included
with "Application Options" if there are no groups. Every GTK+ app has at least
a "GTK+ options" group though...

I would like this too but i have an additional request/idea.

Would it be possible to add non-option arguments to the parser. It's not that important for argument handling (would be nice though) but especially for the help output. Most command line tools print the non-option arguments in the help output too. 

Now i should probably open another feature request but this is exactly the reason i came here because i do the argument handling after the parse step and when i miss the filename argument to my program i'd like to print out the help. But it would be even better if this help included the arguments which the user should still provide.

Joost, that is what the parameter_string is for. If you  make it "FILES..."
you get 

Usage:
   foo [OPTIONS...] FILES...

Thanks Matthias. I didn't catch that in the docs, my fault. 

This does however make a strong case for adding this print_help() function available. If the user doesn't give this argument i'd like to print out the help.

I don't know the difference between the --help and --help-all options (there is no difference in my simple program) but i would prefer something which is equal to what is printed when there is an error in the options.

*** Bug 338242 has been marked as a duplicate of this bug. ***

Matthias, this would be really cool if we could have it :) 

One of the most common use cases for me are test cases where I test varying aspects of an API. In this case I tend to use an argument for different parts of the API I will test. Using no arguments usually to shows the "use --help for more information..." and I would rather it just printed the help with no arguments.

As far as the --help or --help-all print out is concerned, I think it should print just the --help statement and not the --help-all statement. How many times do you need to know about 3rd party options in comparison to this app's options?

You could remedy the --help-all by simply including it in the normal help statement, e.g.:

Help Options:
  -?, --help                       Show help options
      --help-all                   Show help for 3rd party software


Or something to that effect, it is only one line instead of ALL the lines the user would see if we defaulted to --help-all.

Yet another use-case: nearly to all software written by me uses '-h' option for help.  With current g_option_* API it is impossible to simulate such behavior.

Posibility to add some strings before "Usage: prog..." (e.g. version and copyright), and some strings after all options (e.g. 2-3 lines long explanation of the iteraction of some options) is very usefull too.  But it ts impossible also (at least with glib-2.8.6).

About '--help' vs. '--help-all': Just need to provide two functions: one for '--help' and one for '--help-all'.  This will put out flame about apples vs. oranges.

Also: for avoiding flame stdout vs. stderr, this functions should return string and it will be  user's/caller's responsiblity to use stream appropriate for his task.

> Posibility to add some strings before "Usage: prog..." (e.g. version and
> copyright), and some strings after all options (e.g. 2-3 lines long explanation
> of the iteraction of some options) is very usefull too.  But it ts impossible
> also (at least with glib-2.8.6).


This has been added in 2.11

I pretty much agree that there should be a way to bind -h to --help.

As for stdout vs. stderr, flexibility is indeed needed, as according to GNU conding standards, --help output should go to stdout, while if that's triggered by an error, it should go to stderr.

So, one way to make everybody happy (except for those who want simple apis) would be to go back to Dom's initial patch that just exports print_help(), and add a
boolean print_to_stderr argument. 

Matthias, that sounds good enough to me :)

Sounds good to me as well.

2007-04-24  Matthias Clasen  <mclasen@redhat.com>

        * glib/glib.symbols:
        * glib/goption.h:
        * glib/goption.c (g_option_context_get_help): New function to
        get the formatted help string.  (#336089, Dom Lachowicz)

Matthis, which glib version have the patch (comment #20). I am missing poptPrintUsage(context,stdout,0); equivalent in GOption. It looks like this is what has been added.

it is in 2.13