Wish: An option to show more descriptions

[T o n g]

Hi

Allow me to elaborate my wish a bit before coming to the real request.

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.

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

What the format would be? I think Pod::Usage's format for parameter details
in the standard format. It's ok if you don't have Pod::Usage or know how to
use it. "keychain -h" produces the same format as well. Don't have keychain?
I really recommend installing it if you need to ssh to somewhere else.

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

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




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

[Lorenzo Bettini]

T wrote:

> Hi
>
> Allow me to elaborate my wish a bit before coming to the real request.
>
> 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.
>
> So I wish that gengetopt can have another option to show help for parameters
> in details (say, --usage).

that would be great!
probably --usage wouldn't be the best name?
how does Pod::Usage call such an option?
This would require to add also another field in the option in the .ggo
file (for instance details="<very long help description>")

>
> What the format would be? I think Pod::Usage's format for parameter details
> in the standard format. It's ok if you don't have Pod::Usage or know how to
> use it. "keychain -h" produces the same format as well. Don't have keychain?
> I really recommend installing it if you need to ssh to somewhere else.
>
> 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?
Because I'd really love to add it!

hope to hear from you soon
cheers
        Lorenzo

--
+-----------------------------------------------------+
| Lorenzo Bettini          ICQ# lbetto, 16080134      |
| PhD in Computer Science, DSI, Univ. di Firenze      |
| Florence - Italy        (GNU/Linux User # 158233)   |
| http://www.lorenzobettini.it                        |
| http://tronprog.blogspot.com  BLOG                  |
| http://www.purplesucker.com Deep Purple Cover Band  |
| http://www.gnu.org/software/src-highlite            |
| http://www.gnu.org/software/gengetopt               |
| http://www.lorenzobettini.it/software/gengen        |
| http://www.lorenzobettini.it/software/doublecpp     |
+-----------------------------------------------------+



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

[T o n g]

On Fri, 13 Oct 2006 10:36:11 +0200, Lorenzo Bettini wrote:

>> So I wish that gengetopt can have another option to show help for parameters
>> in details (say, --usage).
>
> that would be great!

Oh, THANK YOU!

> probably --usage wouldn't be the best name?

No, that's only the result of 1 sec thinking. :-)

> how does Pod::Usage call such an option?

hm..., actually, it doesn't have an name for it. so feel free to coin your
own. :-)

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

I knew, that's why I put wish. I never thought it might be on the todo
list. :-)

>> What the format would be? I think Pod::Usage's format for parameter
>> details in the standard format. It's ok if you don't have Pod::Usage or
>> know how to use it. "keychain -h" produces the same format as well.
>> Don't have keychain? I really recommend installing it if you need to
>> ssh to somewhere else.
>>
>> 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?

color or the format?

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

Having this feature, it won't be far away from automatically generating a
man page. But I don't recommend going that far to do the man generation
from scratch. Let me recommend asciidoc. It can help generating man page,
html files, DocBook (articles, books and refentry documents) and LinuxDoc.

For a quick AsciiDoc Markup Syntax summary, check out

http://xpt.sourceforge.net/techdocs/nix/asciidoc-syn/

> Because I'd really love to add it!

THANK YOU!

A side note, I've done an extensive search about code generation for
option parameter handling automation. To be honest, gengetopt was not my
top pick, because I thought, hmm, since I have to learn one, why not
something that can do more just one language. Luckily, the one that I
picked was not friendly to newcomers, at least to me. I said luckily
because I really meant it. I'm so happy to have chosen gengetopt.

Thanks a lot Lorenzo, you make me, a newcomer, feel so at home.

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




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

[T o n g]

[instigated by your welcome attitude]

On Fri, 13 Oct 2006 10:36:11 +0200, Lorenzo Bettini wrote:

>> So I wish that gengetopt can have another option to show help for parameters
>> in details ...
>
> ...
> This would require to add also another field in the option in the .ggo
> file (for instance details="<very long help description>")

hold the thought, don't finalize the UI yet please, because I think the
current approach is not the best way to allow user to specify detail helps
like this:

---------------------
    -k --stop which
        Kill currently running agent processes. The following values are
        valid for "which":

        all      Kill all agent processes and quit keychain immediately.
                 Prior to keychain-2.5.0, this was the behavior of the bare
                 "--stop" option.

        others   Kill agent processes other than the one keychain is
                 providing. Prior to keychain-2.5.0, keychain would do this
                 automatically. The new behavior requires that you specify
                 it explicitly if you want it.

        mine     Kill keychain's agent processes, leaving other agents
                 alone.
---------------------

It sure can, but just not that easy. To address the problem, allow me to
share my envision of future gengetopt first.

IMHO, there is still one road block for gengetopt to be widely
adopted. Currently the options are presented to users like a snapshot --
the dynamic is lost. I.e., the order the options are passed are lost.

For example, the option for the 'sort' program, allows user to sort this
fields numerically, but that field alphabetically. It all depends on the
order of -k and -n passed to the program. What other programs care about the
order of the options? Lots, ffmpeg, transcode, xmlstarlet, to name a few.

Further, there are programs that one option is a synonym for a lot of
options. E.g., -a for 'cp' and rsync, 'stty sane', 'ffmpeg -target', &
'transcode -export_profile'...

I'm thinking, the only way for users to handle complicated requirements like
above, is to allow them to specify their own add-on code during options
processing.

This again, requires users to specify multi-line nicely formatted text
in gengetopt configuration file. IMHO, the best way to handle this, is
to use a brand new format -- use xml.

I'm proposing, something like this:

------------------------------------------------
<options package="sample1" version="2.0"
        purpose="this is just a test program for gengetopt" >
 <item type="option" long="str-opt" short="s"
  desc="A string option, for a filename"
  argtype="string" typestr="filename"
  required="optional" >
   <details>
very long help description

more lines

here
   </details>
 </item>
 <item type="option" long="int-opt" short="i" desc="A int option" argtype="int" required="required" />
 <item type="option" long="my-opt" short="m" desc="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\nrequire a line break" argtype="int" required="optional" />

<item type="section" name="more involved options" desc="the following options\nare more complex" />
 <item type="text" text="" />
 <item type="option" long="test-opt" short="t" desc="A string option" argtype="string" required="optional" argoptional="1" default="abc" />
 <item type="option" long="flag1" short="-" desc="A normal flag option" required="optional" />
 <item type="flag" long="flag2" short="-" desc="A toggle flag option" onoff="off" />

<item type="section" name="last option section" />
 <item type="option" long="long-opt" short="-" desc="A long option" argtype="long" required="required" argoptional="1" />

 <item type="text" text="\nAn ending text." />
</options>
------------------------------------------------

As you can see, it almost identical to the .ggo format, just everything is
wrapped in xml.

The idea sounds horrific at first, but it will actually simplify the
gengetopt configuration file parsing. It will befit the users too, because
their configuration file will looks nicer, no longer having those
extremely-long lines, are more easy for version control.

What do you think? You can freeze the .ggo format syntax & parsing and
introduce the xml as an alternative configuration file format for new
features, then deprecate .ggo format later.

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




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

[Lorenzo Bettini]

Hi there

you probably won't believe but I finally made it to answer this email of
yours :-)

here follow my answer...

T wrote:

>>> So I wish that gengetopt can have another option to show help for parameters
>>> in details ...
>> ...
>> This would require to add also another field in the option in the .ggo
>> file (for instance details="<very long help description>")
>
> hold the thought, don't finalize the UI yet please, because I think the
> current approach is not the best way to allow user to specify detail helps
> like this:
>
> ---------------------
>     -k --stop which
>         Kill currently running agent processes. The following values are
>         valid for "which":
>
>         all      Kill all agent processes and quit keychain immediately.
>                  Prior to keychain-2.5.0, this was the behavior of the bare
>                  "--stop" option.
>
>         others   Kill agent processes other than the one keychain is
>                  providing. Prior to keychain-2.5.0, keychain would do this
>                  automatically. The new behavior requires that you specify
>                  it explicitly if you want it.
>
>         mine     Kill keychain's agent processes, leaving other agents
>                  alone.
> ---------------------
>
> It sure can, but just not that easy. To address the problem, allow me to
> share my envision of future gengetopt first.

yes probably it wouldn't be that easy with details, but only because
you'd have to format the text yourself?

probably I didn't understand, but the following does not suggest a
solution for the details problem does it?  Or probably I missed something...

>
> IMHO, there is still one road block for gengetopt to be widely
> adopted. Currently the options are presented to users like a snapshot --
> the dynamic is lost. I.e., the order the options are passed are lost.
>
> For example, the option for the 'sort' program, allows user to sort this
> fields numerically, but that field alphabetically. It all depends on the
> order of -k and -n passed to the program. What other programs care about the
> order of the options? Lots, ffmpeg, transcode, xmlstarlet, to name a few.

yes, that's a good point!  Actually you still have all the options in
the original argv array (notice that getopt might rearrange the orders,
but only of the options without names - the unamed options).

What would you think could be a way to allow the programmer access the
order?

>
> Further, there are programs that one option is a synonym for a lot of
> options. E.g., -a for 'cp' and rsync, 'stty sane', 'ffmpeg -target', &
> 'transcode -export_profile'...

yes that's another good point!
It's in my to do list, and hope to implement it as soon as possible!

>
> I'm thinking, the only way for users to handle complicated requirements like
> above, is to allow them to specify their own add-on code during options
> processing.

you mean insert code in the .ggo file?  code snippets?

>
> This again, requires users to specify multi-line nicely formatted text
> in gengetopt configuration file. IMHO, the best way to handle this, is
> to use a brand new format -- use xml.
>
> I'm proposing, something like this:
>
> ------------------------------------------------
> <options package="sample1" version="2.0"
> purpose="this is just a test program for gengetopt" >
>  <item type="option" long="str-opt" short="s"
>   desc="A string option, for a filename"
>   argtype="string" typestr="filename"
>   required="optional" >
>    <details>
> very long help description
>
> more lines
>
> here
>    </details>
>  </item>
>  <item type="option" long="int-opt" short="i" desc="A int option" argtype="int" required="required" />
>  <item type="option" long="my-opt" short="m" desc="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\nrequire a line break" argtype="int" required="optional" />
>
> <item type="section" name="more involved options" desc="the following options\nare more complex" />
>  <item type="text" text="" />
>  <item type="option" long="test-opt" short="t" desc="A string option" argtype="string" required="optional" argoptional="1" default="abc" />
>  <item type="option" long="flag1" short="-" desc="A normal flag option" required="optional" />
>  <item type="flag" long="flag2" short="-" desc="A toggle flag option" onoff="off" />
>
> <item type="section" name="last option section" />
>  <item type="option" long="long-opt" short="-" desc="A long option" argtype="long" required="required" argoptional="1" />
>
>  <item type="text" text="\nAn ending text." />
> </options>
> ------------------------------------------------
>
> As you can see, it almost identical to the .ggo format, just everything is
> wrapped in xml.
>
> The idea sounds horrific at first, but it will actually simplify the
> gengetopt configuration file parsing. It will befit the users too, because
> their configuration file will looks nicer, no longer having those
> extremely-long lines, are more easy for version control.

I've just realized that probably this is not well documented: option
description in the .ggo file can span more lines:

option  "foo"        i
        "foo option"
        int
        optional

I should explicitly document this and also update the examples probably.
Thanks for rising this issue!

As for xml, well... I think it's really a great technology for data
exchange, truly great!  But it's far from human readability.  Probably
this is only my opinion (actually shared also by others as far as I
know); e.g., I find the xml code above more unreadable than the original
configuration code (just like as I prefer write a Makefile rather than
an ant file).

But as I said, this is only my opinion so I think that add an xml syntax
for configuration files is a very good idea.  I would keep both versions
though (i.e., not make the original one deprecate), since I'll still
prefer the non xml syntax ;-)

having said this, I'd really need help on the xml point: at the moment I
couldn't work on this (I'd concentrate on other parts), so is there
anyone with xml experience that could help on this? (well, yes, I don't
have a big experience with xml... have I already said I don't like
writing xml code? ;-)

also propose a library for xml that could be used.

>
> What do you think? You can freeze the .ggo format syntax & parsing and
> introduce the xml as an alternative configuration file format for new
> features, then deprecate .ggo format later.
>

as I said, introducing xml would be another option for configuration
files, and the other format would still exist (for the reasons above).

For the moment I could introduce the "details" part anyway... however, I
didn't understand your solution about this part... and moreover, how
would this be different from the "desc" part of an option?  I mean,
would there be cases where the "details" part would not be shown?

hope to hear from you soon (I promise I'd be more promptly responsive
this time ;-)

cheers
        Lorenzo

--
Lorenzo Bettini, PhD in Computer Science, DSI, Univ. di Firenze
ICQ# lbetto, 16080134     (GNU/Linux User # 158233)
HOME: http://www.lorenzobettini.it MUSIC: http://www.purplesucker.com
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

[T o n g]

Sorry for responding late... was busy last 2 weeks.

On Sat, 17 Feb 2007 19:23:59 +0100, Lorenzo Bettini wrote:

>>>> So I wish that gengetopt can have another option to show help for
>>>> parameters in details ...
>>> ...
>>> This would require to add also another field in the option in the .ggo
>>> file (for instance details="<very long help description>")
>>
>> hold the thought, don't finalize the UI yet please, because I think the
>> current approach is not the best way to allow user to specify detail helps
>> like this:
>>  [...]
>> This again, requires users to specify multi-line nicely formatted text
>> in gengetopt configuration file. IMHO, the best way to handle this, is
>> to use a brand new format -- use xml.
>
> I've just realized that probably this is not well documented: option
> description in the .ggo file can span more lines:
>
> option  "foo"        i
> "foo option"
> int
> optional
> [...]
>
> As for xml, well... I think it's really a great technology for data
> exchange, truly great!  But it's far from human readability.  Probably
> this is only my opinion (actually shared also by others as far as I
> know); e.g., I find the xml code above more unreadable than the original
> configuration code (just like as I prefer write a Makefile rather than
> an ant file).

gengetopt really grows very fast. Looking back on my request that's several
months ago, and looking at the current feature in gengetopt that allows
nicely formatted multi-line text, the xml format is not a must any more.

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.

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 pages as well!

The beauty of generating man pages is that we don't need to fiddle with man
page format ourselves. There is already a good tools for it -- AsciiDoc
http://www.methods.co.nz/asciidoc/

I've been using asciidoc for quite a while and highly recommend it.  You
just format plain text file according to its simple and clear format, it
will handle the rest of html/manpage generation for you. If you want to skim
through what it is capable of, check out my

AsciiDoc Markup Syntax Quick Summary
http://xpt.sourceforge.net/techdocs/nix/asciidoc-syn/ascs01-AsciiDocMarkupSyntaxQuickSummary/

The actually reason that I requested xml format config file is that, I was
hoping that gengetopt to be the de-factor all purpose program doc generation
tool. I.e., not only to generate getopt code and man pages for C program,
but all other programs as well --

Currently, the .ggo format is "proprietary" to gengetopt. Forgive me not
being able to choose a better word, I mean, if we use xml format config
file, all the other language can use the file as well, e.g., Perl, Python.

For example, if the config file is in xml format, then an experienced Perl
programmer can write a script to generate code to use Getopt::Long in less
than half a day. And I can adapt such script to generate shell script that
use gnu getopt in less than half a day as well. Generating asciidoc format
file for manpage generation will be less than an hour. I believe the same
time frame applies to Python too, but I don't know Python myself.

Well, that's my ambitious goal. But if there is no such request currently,
there is no point maintaining two interfaces now.

However, if one day when you do think it is time for the xml format config
file, post to mlist and cc my sourceforge.net account @suntong001. I'd like
to help. I had experience with parsing xml in c code before, using the
existing c lib. It's quite trivial. I bet doing it again with apache's C++
lib would be even more simpler.

Cheers

Tong

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



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

[T o n g]

[Maybe the thread I was following up was too old,
trying again]

Sorry for responding late... was busy last 2 weeks.

On Sat, 17 Feb 2007 19:23:59 +0100, Lorenzo Bettini
wrote:

>>>> So I wish that gengetopt can have another option
to show help for
>>>> parameters in details ...
>>> ...
>>> This would require to add also another field in
the option in the .ggo
>>> file (for instance details="<very long help
description>")
>>
>> hold the thought, don't finalize the UI yet please,
because I think the
>> current approach is not the best way to allow user
to specify detail helps
>> like this:
>>  [...]
>> This again, requires users to specify multi-line
nicely formatted text
>> in gengetopt configuration file. IMHO, the best way
to handle this, is
>> to use a brand new format -- use xml.
>
> I've just realized that probably this is not well
documented: option
> description in the .ggo file can span more lines:
>
> option  "foo"        i
> "foo option"
> int
> optional
> [...]
>
> As for xml, well... I think it's really a great
technology for data
> exchange, truly great!  But it's far from human
readability.  Probably
> this is only my opinion (actually shared also by
others as far as I
> know); e.g., I find the xml code above more
unreadable than the original
> configuration code (just like as I prefer write a
Makefile rather than
> an ant file).

gengetopt really grows very fast. Looking back on my
request that's several
months ago, and looking at the current feature in
gengetopt that allows
nicely formatted multi-line text, the xml format is
not a must any more.

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.

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 pages
as well!

The beauty of generating man pages is that we don't
need to fiddle with man
page format ourselves. There is already a good tools
for it -- AsciiDoc
http://www.methods.co.nz/asciidoc/

I've been using asciidoc for quite a while and highly
recommend it.  You
just format plain text file according to its simple
and clear format, it
will handle the rest of html/manpage generation for
you. If you want to skim
through what it is capable of, check out my

AsciiDoc Markup Syntax Quick Summary
http://xpt.sourceforge.net/techdocs/nix/asciidoc-syn/ascs01-AsciiDocMarkupSyntaxQuickSummary/

The actually reason that I requested xml format config
file is that, I was
hoping that gengetopt to be the de-factor all purpose
program doc generation
tool. I.e., not only to generate getopt code and man
pages for C program,
but all other programs as well --

Currently, the .ggo format is "proprietary" to
gengetopt. Forgive me not
being able to choose a better word, I mean, if we use
xml format config
file, all the other language can use the file as well,
e.g., Perl, Python.

For example, if the config file is in xml format, then
an experienced Perl
programmer can write a script to generate code to use
Getopt::Long in less
than half a day. And I can adapt such script to
generate shell script that
use gnu getopt in less than half a day as well.
Generating asciidoc format
file for manpage generation will be less than an hour.
I believe the same
time frame applies to Python too, but I don't know
Python myself.

Well, that's my ambitious goal. But if there is no
such request currently,
there is no point maintaining two interfaces now.

However, if one day when you do think it is time for
the xml format config
file, post to mlist and cc my sourceforge.net account
<at> suntong001. I'd like
to help. I had experience with parsing xml in c code
before, using the
existing c lib. It's quite trivial. I bet doing it
again with apache's C++
lib would be even more simpler.

Cheers

Tong

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

__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around
http://mail.yahoo.com 


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

[Lorenzo Bettini]

Tong Sun wrote:
> [Maybe the thread I was following up was too old,
> trying again]
>

hi there

I received your email, but I haven't got time to read it yet, hope to do
it asap :-)

cheers
        Lorenzo

--
Lorenzo Bettini, PhD in Computer Science, DSI, Univ. di Firenze
ICQ# lbetto, 16080134     (GNU/Linux User # 158233)
HOME: http://www.lorenzobettini.it MUSIC: http://www.purplesucker.com
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

[Lorenzo Bettini]

- Tong - wrote:
> Sorry for responding late... was busy last 2 weeks.

no problem: I was late too when answering your previous post ;-)

> gengetopt really grows very fast. Looking back on my request that's several
> months ago, and looking at the current feature in gengetopt that allows
> nicely formatted multi-line text, the xml format is not a must any more.
>

happy to hear that :-)

> 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

Moreover, where would the detailed output be best put?

 --option            "description............"

                     "long description"

or

 --option            "description............"

   "long description"

?

> 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 pages 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).

> The beauty of generating man pages is that we don't need to fiddle with man
> page format ourselves. There is already a good tools for it -- AsciiDoc
> http://www.methods.co.nz/asciidoc/
>
> I've been using asciidoc for quite a while and highly recommend it.  You
> just format plain text file according to its simple and clear format, it
> will handle the rest of html/manpage generation for you. If you want to skim
> through what it is capable of, check out my
>
> AsciiDoc Markup Syntax Quick Summary
> http://xpt.sourceforge.net/techdocs/nix/asciidoc-syn/ascs01-AsciiDocMarkupSyntaxQuickSummary/
>

I don't know about asciidoc; so you'd use this one to get the man page?
 From gengetopt --help option?  In case, you'd need to format the
description part of gengetopt options according to its syntax?  But
then, those asciidoc syntax parts should be removed from --help output?
 Or am I missing something?

> The actually reason that I requested xml format config file is that, I was
> hoping that gengetopt to be the de-factor all purpose program doc generation
> tool. I.e., not only to generate getopt code and man pages for C program,
> but all other programs as well --
>
> Currently, the .ggo format is "proprietary" to gengetopt. Forgive me not
> being able to choose a better word, I mean, if we use xml format config
> file, all the other language can use the file as well, e.g., Perl, Python.
>
> For example, if the config file is in xml format, then an experienced Perl
> programmer can write a script to generate code to use Getopt::Long in less
> than half a day. And I can adapt such script to generate shell script that
> use gnu getopt in less than half a day as well. Generating asciidoc format
> file for manpage generation will be less than an hour. I believe the same
> time frame applies to Python too, but I don't know Python myself.
>
> Well, that's my ambitious goal. But if there is no such request currently,
> there is no point maintaining two interfaces now.
>

I think I'm getting the point!

However, one current possible "easy" solution is to let gengetopt
generate xml code from the .ggo file?

Furthermore, I'd like gengetopt to generate code for other languages
too, e.g., Java, and other languages I don't actually know, e.g. Perl
and Python that you cited.

> However, if one day when you do think it is time for the xml format config
> file, post to mlist and cc my sourceforge.net account @suntong001. I'd like
> to help. I had experience with parsing xml in c code before, using the
> existing c lib. It's quite trivial. I bet doing it again with apache's C++
> lib would be even more simpler.

what do you think about the possibility of letting gengetopt generate
xml code from the .ggo file?

I hope to hear from you soon
cheers
        Lorenzo

--
Lorenzo Bettini, PhD in Computer Science, DSI, Univ. di Firenze
ICQ# lbetto, 16080134     (GNU/Linux User # 158233)
HOME: http://www.lorenzobettini.it MUSIC: http://www.purplesucker.com
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

[TM-7]

Hi Lorenzo,

I've come across a bug in gengetopt version 2.19.2 when option
include-getopt' is used. I attach a small project to demonstrate the issue.

Basically, if there are 2 options Q and W and the program is invoked as:
   prog -Q -W
everything is fine. However, if the program is invoked as:
   prog -QW
gengetopt generates an error message and terminates the program.

I am using Microsoft Visual Studio to compile the project. However, up
to and including version 2.19.1 I have used a version of getopt taken
from glibc and never had any such problems. I believe that this is a bug
in the implementation of getopt that was added to version 2.19.2 of
gengetopt.

Thanks
TM


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

[Lorenzo Bettini]

TM wrote:

> Hi Lorenzo,
>
> I've come across a bug in gengetopt version 2.19.2 when option
> include-getopt' is used. I attach a small project to demonstrate the issue.
>
> Basically, if there are 2 options Q and W and the program is invoked as:
>   prog -Q -W
> everything is fine. However, if the program is invoked as:
>   prog -QW
> gengetopt generates an error message and terminates the program.
>
> I am using Microsoft Visual Studio to compile the project. However, up
> to and including version 2.19.1 I have used a version of getopt taken
> from glibc and never had any such problems. I believe that this is a bug
> in the implementation of getopt that was added to version 2.19.2 of
> gengetopt.
>
> Thanks
> TM

thanks for the report!

I'll take a look at the problem

hope to a fix quite soon
cheers
        Lorenzo

--
Lorenzo Bettini, PhD in Computer Science, DSI, Univ. di Firenze
ICQ# lbetto, 16080134     (GNU/Linux User # 158233)
HOME: http://www.lorenzobettini.it MUSIC: http://www.purplesucker.com
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

[Lorenzo Bettini]

TM wrote:

> Hi Lorenzo,
>
> I've come across a bug in gengetopt version 2.19.2 when option
> include-getopt' is used. I attach a small project to demonstrate the issue.
>
> Basically, if there are 2 options Q and W and the program is invoked as:
>   prog -Q -W
> everything is fine. However, if the program is invoked as:
>   prog -QW
> gengetopt generates an error message and terminates the program.
>
> I am using Microsoft Visual Studio to compile the project. However, up
> to and including version 2.19.1 I have used a version of getopt taken
> from glibc and never had any such problems. I believe that this is a bug
> in the implementation of getopt that was added to version 2.19.2 of
> gengetopt.
>

Hi there

(you're Tiago Menezes aren't you?)

you were right about the bug!

the wrong code line is this one

if (d->custom_optind == 1 || d->custom_optind == 0 || !d->initialized) {

which must be changed into

if (d->custom_optind == 0 || !d->initialized) {

I've uploaded this fixed temporary release here

http://rap.dsi.unifi.it/~bettini/gengetopt-2.20.tar.gz

hope to hear from you soon
cheers
        Lorenzo

--
Lorenzo Bettini, PhD in Computer Science, DSI, Univ. di Firenze
ICQ# lbetto, 16080134     (GNU/Linux User # 158233)
HOME: http://www.lorenzobettini.it MUSIC: http://www.purplesucker.com
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