[help-gengetopt] Re: Another Wish

[Tong Sun]

[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