Gengetopt 2.22 and --show-detailed-help

[T o n g]

Hi Lorenzo,

Congratulation on the new Gengetopt v2.22, although the congratulation
comes late :-). It's really a polished release. I like the new features
like -no-help, --no-version, and especially --show-detailed-help.

I'd like to make a suggestion regarding the format of --show-detailed-help:

Current practice (from gengetopt --detailed-help) will produce help like
this:

  -s, --str-opt=filename  A string option, for a filename
  -m, --my-opt=INT        Another integer option, this time the description of
                            the option should be quite long to require
                            wrapping... possibly more than one wrapping :-)
                            especially if I
                            require a line break
  -i, --int-opt=INT       A int option
  -F, --funct-opt         A function option

  A function option is basically an option with no argument.  It can be
  used, e.g., to specify a specific behavior for a program.

  Well, this further explanation is quite useless, but it's only to show an
  example of an option with details, which will be printed only when

  --detailed-help is given at the command line.
      --flag-opt          A flag option  (default=off)
      --long-opt=LONG     A long option
      --def-opt=STRING    A string option with default  (default=`Hello')
      --enum-opt=STRING   A string option with list of values  (possible
                            values="foo", "bar", "hello", "bye"
                            default=`hello')
  -S, --secret=INT        hidden option will not appear in --help
  -D, --dependant=INT     option that depends on str-opt

I.e., if the details is used sparely, the extra spaces around the detailed
helps don't coherent with other no-space options.

However, if we remove the spaces, it will look like this:

  -s, --str-opt=filename  A string option, for a filename
  -m, --my-opt=INT        Another integer option, this time the description of
                            the option should be quite long to require
                            wrapping... possibly more than one wrapping :-)
                            especially if I
                            require a line break
  -i, --int-opt=INT       A int option
  -F, --funct-opt         A function option
  A function option is basically an option with no argument.  It can be used,
  e.g., to specify a specific behavior for a program.

  Well, this further explanation is quite useless, but it's only to show an
  example of an option with details, which will be printed only when
  --detailed-help is given at the command line.
      --flag-opt          A flag option  (default=off)
      --long-opt=LONG     A long option
      --def-opt=STRING    A string option with default  (default=`Hello')
      --enum-opt=STRING   A string option with list of values  (possible
                            values="foo", "bar", "hello", "bye"
                            default=`hello')
  -S, --secret=INT        hidden option will not appear in --help
  -D, --dependant=INT     option that depends on str-opt

I.e., visually it is not quite obvious that the detailed help goes with
the -F option.

So, I'm wondering if we could change the format to look like this:

  -s, --str-opt=filename  A string option, for a filename
  -m, --my-opt=INT        Another integer option, this time the description of
                            the option should be quite long to require
                            wrapping... possibly more than one wrapping :-)
                            especially if I
                            require a line break
  -i, --int-opt=INT       A int option
  -F, --funct-opt         A function option
        A function option is basically an option with no argument.  It can
        be used, e.g., to specify a specific behavior for a program.

        Well, this further explanation is quite useless, but it's only to
        show an example of an option with details, which will be printed
        only when --detailed-help is given at the command line.
      --flag-opt          A flag option  (default=off)
      --long-opt=LONG     A long option
      --def-opt=STRING    A string option with default  (default=`Hello')
      --enum-opt=STRING   A string option with list of values  (possible
                            values="foo", "bar", "hello", "bye"
                            default=`hello')
  -S, --secret=INT        hidden option will not appear in --help
  -D, --dependant=INT     option that depends on str-opt

I.e., make it is a bit obvious visually that the detailed help goes
with the -F option, and it won't hurt if all options detailed help
have extra spaces around them.

What do you think?

Thanks

--
Tong (remove underscore(s) to reply)
  http://xpt.sourceforge.net/techdocs/
  http://xpt.sourceforge.net/tools/



_______________________________________________
Help-gengetopt mailing list
Help-gengetopt@...
http://lists.gnu.org/mailman/listinfo/help-gengetopt

[Lorenzo Bettini]

Hi there

nice to hear from you!

I think I've used a standard format for help output (e.g., it can be
used by help2man).  But I'm not sure about that... any clue anyone?

cheers
        Lorenzo

T o n g wrote:

> Hi Lorenzo,
>
> Congratulation on the new Gengetopt v2.22, although the congratulation
> comes late :-). It's really a polished release. I like the new features
> like -no-help, --no-version, and especially --show-detailed-help.
>
> I'd like to make a suggestion regarding the format of --show-detailed-help:
>
> Current practice (from gengetopt --detailed-help) will produce help like
> this:
>
>   -s, --str-opt=filename  A string option, for a filename
>   -m, --my-opt=INT        Another integer option, this time the description of
>                             the option should be quite long to require
>                             wrapping... possibly more than one wrapping :-)
>                             especially if I
>                             require a line break
>   -i, --int-opt=INT       A int option
>   -F, --funct-opt         A function option
>
>   A function option is basically an option with no argument.  It can be
>   used, e.g., to specify a specific behavior for a program.
>
>   Well, this further explanation is quite useless, but it's only to show an
>   example of an option with details, which will be printed only when
>
>   --detailed-help is given at the command line.
>       --flag-opt          A flag option  (default=off)
>       --long-opt=LONG     A long option
>       --def-opt=STRING    A string option with default  (default=`Hello')
>       --enum-opt=STRING   A string option with list of values  (possible
>                             values="foo", "bar", "hello", "bye"
>                             default=`hello')
>   -S, --secret=INT        hidden option will not appear in --help
>   -D, --dependant=INT     option that depends on str-opt
>
> I.e., if the details is used sparely, the extra spaces around the detailed
> helps don't coherent with other no-space options.
>
> However, if we remove the spaces, it will look like this:
>
>   -s, --str-opt=filename  A string option, for a filename
>   -m, --my-opt=INT        Another integer option, this time the description of
>                             the option should be quite long to require
>                             wrapping... possibly more than one wrapping :-)
>                             especially if I
>                             require a line break
>   -i, --int-opt=INT       A int option
>   -F, --funct-opt         A function option
>   A function option is basically an option with no argument.  It can be used,
>   e.g., to specify a specific behavior for a program.
>
>   Well, this further explanation is quite useless, but it's only to show an
>   example of an option with details, which will be printed only when
>   --detailed-help is given at the command line.
>       --flag-opt          A flag option  (default=off)
>       --long-opt=LONG     A long option
>       --def-opt=STRING    A string option with default  (default=`Hello')
>       --enum-opt=STRING   A string option with list of values  (possible
>                             values="foo", "bar", "hello", "bye"
>                             default=`hello')
>   -S, --secret=INT        hidden option will not appear in --help
>   -D, --dependant=INT     option that depends on str-opt
>
> I.e., visually it is not quite obvious that the detailed help goes with
> the -F option.
>
> So, I'm wondering if we could change the format to look like this:
>
>   -s, --str-opt=filename  A string option, for a filename
>   -m, --my-opt=INT        Another integer option, this time the description of
>                             the option should be quite long to require
>                             wrapping... possibly more than one wrapping :-)
>                             especially if I
>                             require a line break
>   -i, --int-opt=INT       A int option
>   -F, --funct-opt         A function option
>         A function option is basically an option with no argument.  It can
>         be used, e.g., to specify a specific behavior for a program.
>
>         Well, this further explanation is quite useless, but it's only to
>         show an example of an option with details, which will be printed
>         only when --detailed-help is given at the command line.
>       --flag-opt          A flag option  (default=off)
>       --long-opt=LONG     A long option
>       --def-opt=STRING    A string option with default  (default=`Hello')
>       --enum-opt=STRING   A string option with list of values  (possible
>                             values="foo", "bar", "hello", "bye"
>                             default=`hello')
>   -S, --secret=INT        hidden option will not appear in --help
>   -D, --dependant=INT     option that depends on str-opt
>
> I.e., make it is a bit obvious visually that the detailed help goes
> with the -F option, and it won't hurt if all options detailed help
> have extra spaces around them.
>
> What do you think?
>
> Thanks
>

--
Lorenzo Bettini, PhD in Computer Science, DI, Univ. Torino
ICQ# lbetto, 16080134     (GNU/Linux User # 158233)
HOME: http://www.lorenzobettini.it MUSIC: http://www.purplesucker.com
http://www.myspace.com/supertrouperabba
BLOGS: http://tronprog.blogspot.com  http://longlivemusic.blogspot.com
http://www.gnu.org/software/src-highlite
http://www.gnu.org/software/gengetopt
http://www.gnu.org/software/gengen http://doublecpp.sourceforge.net


_______________________________________________
Help-gengetopt mailing list
Help-gengetopt@...
http://lists.gnu.org/mailman/listinfo/help-gengetopt

[Tim Post-3]

On Thu, 2008-03-13 at 08:51 +0100, Lorenzo Bettini wrote:
> Hi there
>
> nice to hear from you!
>
> I think I've used a standard format for help output (e.g., it can be
> used by help2man).  But I'm not sure about that... any clue anyone?

I ran gengetopt specifying the function to be main() so I could just run
it, then passed it through help2man just to be sure and it worked
without any problem.

I would think breaking that could be bad, especially for something using
gengetopt and gengen, where the gengetopt infile is also written by
another program (i.e. autoconf influenced).

This is interesting however for programs that have dozens of options,
help for those is often hard to read. I've never used the grouping
feature in gengetopt (I'm about to play with it soon), does that also
permit a ./prog --help [groupname] display?

Cheers,
--Tim




_______________________________________________
Help-gengetopt mailing list
Help-gengetopt@...
http://lists.gnu.org/mailman/listinfo/help-gengetopt

[Lorenzo Bettini]

Tim Post wrote:

> On Thu, 2008-03-13 at 08:51 +0100, Lorenzo Bettini wrote:
>> Hi there
>>
>> nice to hear from you!
>>
>> I think I've used a standard format for help output (e.g., it can be
>> used by help2man).  But I'm not sure about that... any clue anyone?
>
> I ran gengetopt specifying the function to be main() so I could just run
> it, then passed it through help2man just to be sure and it worked
> without any problem.
>
> I would think breaking that could be bad, especially for something using
> gengetopt and gengen, where the gengetopt infile is also written by
> another program (i.e. autoconf influenced).
>
> This is interesting however for programs that have dozens of options,
> help for those is often hard to read. I've never used the grouping
> feature in gengetopt (I'm about to play with it soon), does that also
> permit a ./prog --help [groupname] display?
>

so you're saying that the current output should be standard, aren't you?

it looks like that to me... as far as I could see from other programs'
output... Tong, are you referring to the output of a program that you saw?

cheers
        Lorenzo


--
Lorenzo Bettini, PhD in Computer Science, DI, Univ. Torino
ICQ# lbetto, 16080134     (GNU/Linux User # 158233)
HOME: http://www.lorenzobettini.it MUSIC: http://www.purplesucker.com
http://www.myspace.com/supertrouperabba
BLOGS: http://tronprog.blogspot.com  http://longlivemusic.blogspot.com
http://www.gnu.org/software/src-highlite
http://www.gnu.org/software/gengetopt
http://www.gnu.org/software/gengen http://doublecpp.sourceforge.net



_______________________________________________
Help-gengetopt mailing list
Help-gengetopt@...
http://lists.gnu.org/mailman/listinfo/help-gengetopt

[Tim Post-3]

On Fri, 2008-03-14 at 17:10 +0100, Lorenzo Bettini wrote:
> so you're saying that the current output should be standard, aren't you?

Yes. Just to check I ran some of the more complex GNU programs through
help2man just to see, gcc has the same style output. Since gengetopt is
a GNU program, its output should probably behave the same :)

Programs with many, many options do produce help that is very difficult
to read, especially on a dumb terminal / local console without scroll
back capabilities. I really don't think much can be done in gengetopt's
output to cure that to any effective degree, hence the usefulness of
man/info/help2man (and all the more reason to keep it standard).

Cheers,
--Tim



_______________________________________________
Help-gengetopt mailing list
Help-gengetopt@...
http://lists.gnu.org/mailman/listinfo/help-gengetopt

[Lorenzo Bettini]

Tim Post wrote:

> On Fri, 2008-03-14 at 17:10 +0100, Lorenzo Bettini wrote:
>> so you're saying that the current output should be standard, aren't you?
>
> Yes. Just to check I ran some of the more complex GNU programs through
> help2man just to see, gcc has the same style output. Since gengetopt is
> a GNU program, its output should probably behave the same :)
>
> Programs with many, many options do produce help that is very difficult
> to read, especially on a dumb terminal / local console without scroll
> back capabilities. I really don't think much can be done in gengetopt's
> output to cure that to any effective degree, hence the usefulness of
> man/info/help2man (and all the more reason to keep it standard).
>

Thanks for the information Tim :-)

I seemed to remember that the current output is standard, but I wanted
to be sure...

Tong, the initial spaces can still be inserted manually (but remember
that also wrapping should be taken care of manually).

cheers
        Lorenzo

--
Lorenzo Bettini, PhD in Computer Science, DI, Univ. Torino
ICQ# lbetto, 16080134     (GNU/Linux User # 158233)
HOME: http://www.lorenzobettini.it MUSIC: http://www.purplesucker.com
http://www.myspace.com/supertrouperabba
BLOGS: http://tronprog.blogspot.com  http://longlivemusic.blogspot.com
http://www.gnu.org/software/src-highlite
http://www.gnu.org/software/gengetopt
http://www.gnu.org/software/gengen http://doublecpp.sourceforge.net


_______________________________________________
Help-gengetopt mailing list
Help-gengetopt@...
http://lists.gnu.org/mailman/listinfo/help-gengetopt