[help-gengetopt] Revisit: the 'details' option to show more descriptions

[- Tong -]

Hi Lorenzo,

A while back ago, I posted here a request entitled 
"Wish: An option to show more descriptions", 
http://thread.gmane.org/gmane.comp.gnu.gengetopt.general/216/focus=262

I'd like to revisit the subject again, but since it has been a while, and I
bubbled my request with many irrelevant or outdated requests, I'm going to
re-summarize them below in one post. Note that the text prefixed with '> '
was your replies.

Background:
-----------

When programming in Perl, I use the Pod::Usage package to show the online
help. What's interesting in the Pod::Usage package is that it gives me
three level of details. One of them is to show the help for parameters
in details. 

In gengetopt, we've already have two level of details:

1. with the option --long-help
2. with the option --help/--show-full-help

But sometimes the one-line explanation from --help might not be enough 
to explain things in details. However, if we put too much info in it, 
the total --help would be too long, thus we'll loose our audience.

Request:
--------

So I wish that gengetopt can have another option to show help for parameters
in details (say, --show-detailed-help).

> This would require to add also another field in the option in the .ggo 
> file (for instance details="<very long help description>")

Sure. . . 

BTW, "keychain -h"'s color output is so cool. I wish we could have that
too. :-)

> COOOOOL!!! :-)
> I'm used to this format since I use Gentoo as well, and I love this output!
> Is it standard somehow?

I don't know. But the format seems so standard to me. it is almost the same
as what we see in man pages.

> Because I'd really love to add it!

Hope that we will have the 'details="<very long help description>"' option
soon. Please also add an option --show-detailed-help or something apart from
the --show-help option, so as to show such detailed help.

> OK, this sound reasonable; I assume that --show-detailed-help will also
> show hidden options, isn't it?  Otherwise we would end up with too many
> help options

Definitely. We want it to be full help that includes everything possible, in
like-man-page format, in text form.

> Moreover, where would the detailed output be best put?
> 
>  --option            "description............"
> 
>                      "long description"
> 
> or
> 
>  --option            "description............"
> 
>    "long description"

Either way are fine with me. Maybe we follow the manpage's format? It's
totally up to you. I fully believe you'll make good decision.

I'm really excited to anticipate that the "details" option be
implemented. Because, after that, the gengetopt will no longer generate
getopt code only any more -- it can generate man-page-formatted document
as well!

> at the moment you can already have a generated man page, by using the
> help output and help2man (see the automatically generated man page for
> gengetopt itself).

Where can I find more explanation on this help2man? My Debian release does
not contain such tool. Should I file a bug report for the maintainer?

thanks

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