[help-gengetopt] Re: Another Wish

[- Tong -]

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/