RPM Community Forums

Mailing List Message of <popt-devel>

Re: Disallowing args

From: Jeff Johnson <n3npq@mac.com>
Date: Sat 05 Jun 2010 - 19:42:04 CEST
Message-id: <01D03C97-E0CD-4D35-8D30-EB085B919D23@mac.com>

On Jun 5, 2010, at 12:42 PM, Danny Sung wrote:

> On 06/05/2010 8:56 AM, Jeff Johnson wrote:
> 
>> (aside)
>> Anything you want to see in POPT 2.0? I'm collecting features ...
>> 
> 
> Since you're collecting features... =)
> 
> One thing I'd like is to extend the help/usage capability just a little.
> 

Well reworking --help is one of the primary motivations for POPT 2.0.

Hysterically, encoding was rammed into POPT by GNOME way back when.
While the scheme is workable, the original change _HAD_ to be done
as an addition to preserve ABI, and so all of the i18n for --help
is rather awkwardly done.

To make matters worse, another patch from GNOME wanted POPT to undertake
localization transforms from UTF8 to whatever was in LC_ALL etc.

While iconv(3) makes the character encoding transform as "trivial" as deciding
the to <-> from locales, its hardly trivial to make that decision reliably
based solely on a desired LC_ALL environment variable (the from locale cannot
be determined reliably, and hackery like trying various from locales like
glib does is hardly sound engineering).

The killer is that the data needed to find --help alignment reproducers is application resident,
and application chosen, and the GNOME developers who forced the iconv(3) into
POPT just aren't helping with reproducers. I have no interest in supporting
POPT functionality that noone is willing to help maintain any more.

So the short answer is:
	All of the --help handling needs to be scrapped and reworked in POPT 2.0.

For starters, 30-40% of the code is --help related, and _ALL_ of the bug reports
I've heard for years are
	But --help columns don't align!

Enough already ... bring on the --help bulldozers!

> So I'd like to be able to have more descriptive usage parameters (eg. to cover left-over arguments).  I addition it'd be nice to have a little description/summary of what the program to do.  I realize you can do this with a custom help function.  But it'd be nice if these were standard elements.
> 
> Other niceties might be:
> - a way to indicate parameters enabled by default (eg. having a '*' next to them in the help)

There is already
	#define POPT_ARGFLAG_SHOW_DEFAULT 0x00800000U /*!< show default value in --help */
as well as
	#define POPT_ARGFLAG_OPTIONAL   0x10000000U  /*!< arg may be missing */
wired into --help output.

> 
> - An additional structure that could provide detailed help on argDescription elements.  For example, rpm has an option:
>      --queryformat=QUERYFORMAT        use the following query format
>   It'd be nice if there were a section of help that could describe what QUERYFORMAT could be.  So obviously it's not going to be a full man page, but perhaps it could just show supported % format options or something like that.

This is a different issue. There is already the 6th/7th fields in POPT tables,
the problem is really "information overload" from --help. At some point man(1)
or info(1) is a better approach than --help, particularly for RPM which has
an entire eco-system of option processing and far too many options
to be reasonably displayed with --help (because the info is not very helpful).

(aside)
Note that RPM is _ROUTINELY adding
	#define POPT_ARGFLAG_DOC_HIDDEN 0x40000000U /*!< don't show in help/usage */ 
there's zillions of options in RPM that noone knows about. My guess is that there's
more "hidden" than displayed options these days, usually disablers that noone ever
really needs to use.

>   I use something like this in my code, but I have specific keys like "[replaceme]" that I convert.  And I put just the acceptable keys in the help cause I just need a quick reminder of what they are.  But it clutters the option help a little.  I'd be fine with specifying "FORMATSTRING" in the option help.  Then have perhaps an arg help down below that shows what values FORMATSTRING understands.
> 
> 
> I'm not sure exactly how you could support these without breaking compatability with existing apps.  Perhaps a new datatype something like:
> 

FYI: POPT 2.0 is all about breaking compatibility. There's only so much
that can be done with obscure overloadings of the existing 7-tuple in
popt table entries.

> enum poptOptionType {
>   POPT_OPTION,
>   POPT_ARG,
>   POPT_USAGE,
> };
> 
> union poptDetailedOption {
>   poptOptionType optType;
>   struct poptShortOption;
>   struct poptArgHelp;
>   struct poptUsageHelp;
> }
> 
> struct poptShortOption {  /* same as poptOption but with a type field */
>    poptOptionType optType;
>    const char * longName;
>    char shortName;
>    int argInfo;
>    void * arg;
>    int val;
>    const char * descrip;
>    const char * argDescrip;
> };
> 
> 
> I'm not sure this would give the desired effect.. but the thought would be that it'd turn your options table to something like this:
> 
> poptDetailedOption optionsTable[] = {
>        { POPT_OPTION, "bps", 'b', POPT_ARG_INT, &speed, 0,
>        "signaling rate in bits-per-second", "BPS" },
>        { POPT_ARG, "FORMATSTRING", "Possible formatting options are [foo] [bar]" },
> 	{ POPT_USAGE, "infile [outfile]" },
>        { POPT_SUMMARY, "This program converts your data to something...." },
> 
> 
> 
> I don't think the union will allow it to look exactly like that.  In fact it may not even be possible to initialize it that way(?)  Maybe we'd have to do something wonky with macros to make it look nice.  But you get the idea.
> 
> If you wanted to get really fancy the "POPT_USAGE" example I gave could be separated into something like this:
>  { POPT_EXTRAARG,
>        "infile",
>        1 /* required */,
>        "specify input filename",
>        "stdin" /* default value */
>  },
>  { POPT_EXTRAARG,
>        "outfile",
>        0 /* optional */,
>        "file to output" /* description */
>        "stdout" /* default value */
>  }
> 
> This would allow the autohelp to generate "standard" extra arg displays (eg. [] for optional parameters, etc.).
> 
> Admittedly this feature may be a bit questionable as many programs may have rather complex "extra args".  But I think a lot of programs fall into this simple category as well.
> 
> 
> Anyway, just a few thoughts...
> 

If interested, send along some code and I will try to integrate. I have
no problems adding code under some
	#ifdef WEIRD_EXOTIC_ENABLING_FEATURE
if necessary, as long as I don't have to "support" busted crap (like --help
column alignments and i18n encoding transforms).

And I will try to integrate whatever you send.

Hint: I'd like POPT to continue to be "lean-and-mean". I'm horrified at
the crapola with option grouping, and --help table sorting, and ... that I
see implemented using GNU getopt_long in cpio/tar. Wotta mess imho. YMMV.

73 de Jeff
> 
> ______________________________________________________________________
> POPT Library                                           http://rpm5.org
> Developer Communication List                       popt-devel@rpm5.org
Received on Sat Jun 5 19:42:49 2010
Driven by Jeff Johnson and the RPM project team.
Hosted by OpenPKG and Ralf S. Engelschall.
Powered by FreeBSD and OpenPKG.