Re: [help-gengetopt] Another Wish

[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