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 0x0080U /*! show default value
in --help */
as well as
#define POPT_ARGFLAG_OPTIONAL 0x1000U /*! 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=QUERYFORMATuse 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 0x4000U /*! 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
