Issue 32 in google-gflags: Customize default --help message
google...@googlecode.com
Owner: ----
Labels: Type-Defect Priority-Medium
New issue 32 by pablo.cael: Customize default --help message
http://code.google.com/p/google-gflags/issues/detail?id=32
Hi all,
is there any way of improving/customizing the regular --help message? The
default --help shows the help message for all flags, including the gflags
flags, and plus, it separates the flags for modules, as in the example
below:
Flags from /home/user/Main.cpp:
-a (some description) type:...
-f ....
So, if i'm using only one module is look strange..
Is there any way of making help printing only my flags independent from
which modules the flags are? And plus, the usage message comes before the
help message.. is there any way of making it to come after?
I couldn't find anything to help on those issues looking at gflags.h and
in the gflags help...
thanks...
Pablo
--
You received this message because you are listed in the owner
or CC fields of this issue, or because you starred this issue.
You may adjust your issue notification preferences at:
http://code.google.com/hosting/settings
google...@googlecode.com
Labels: -Type-Defect Type-Enhancement
Comment #1 on issue 32 by csilvers: Customize default --help message
http://code.google.com/p/google-gflags/issues/detail?id=32
} So, if i'm using only one module is look strange..
Is your suggestion to not say "Flags from /home/user/Main.cpp" if that's
the only
module that defines any flags? I can see the argument, but I admit it
doesn't seem
like that big an issue to me. I can also see an argument for always
showing it, for
consistency.
} Is there any way of making help printing only my flags independent from
} which modules the flags are?
I don't think I understand what you're asking, exactly. What do you mean
by "my
flags"? -- what other flags are there? Maybe you can give a specific
example of what
--help prints now, and what you want it to print. Is --helpshort what
you're asking for?
} And plus, the usage message comes before the
} help message.. is there any way of making it to come after?
Hmm, interesting. You could definitely just modify the source code. Most
help
systems show the usage message first, since the flags often don't make any
sense
without the usage first.
One thing we could do is print usage both before and after, but that won't
work well
if the usage message is very long, which sometimes it can be.
I'm not sure there's a good thing we can do here generally. I think you'd
probably
be better off just doing --helpshort or something else to make it so the
flags don't
take up as much space.
google...@googlecode.com
Comment #2 on issue 32 by pablo.cael: Customize default --help message
http://code.google.com/p/google-gflags/issues/detail?id=32
}} Is your suggestion to not say "Flags from /home/user/Main.cpp" if that's
the only
}} module that defines any flags? I can see the argument, but I admit it
doesn't
}} seem
}} like that big an issue to me. I can also see an argument for always
showing it,
}} for
}} consistency.
Well, from the users point of view, I don't see the point in showing which
module the
flag comes from. I can see a point from the programmers point of view, for
sure.. but
the programmer can easily check it from the code... So, if I'm not missing
something
here (since I don't have your knowledge about the issue), wouldn't it be
nice at
least to have the flexibility to customize the module name? (default is the
real
module as it is now, but one can set to "" or to other name).
For example, if I use google glog and google gflags, glog makes available a
set of
flags for me (to customize log level and etc)... But, when I use --help in
my app, a
lot of google log help is shown separated by modules that I (as a
programmer) don't
need to know (specially the user!).
I really haven't figured out the best solution here... but from my point of
view, the
--help should work as any other app under linux for example, it shows all
flags in a
single list, not separated my misterious modules.
}} I don't think I understand what you're asking, exactly. What do you
mean by "my
}} flags"? -- what other flags are there? Maybe you can give a specific
example of
}} what
}} --help prints now, and what you want it to print. Is --helpshort what
you're
}} asking for?
Sorry, I may not have explained well.. By "my" flags I mean the flags that
I have
declared (not gflags flags).
google...@googlecode.com
Comment #3 on issue 32 by csilvers: Customize default --help message
http://code.google.com/p/google-gflags/issues/detail?id=32
I think different users have different experiences. It depends a lot on
what the
program looks like. Personally, I find it helpful to know the name of the
file a
flag is defined in, because it's another clue as to what the flag does. It
can also
help me determine which flags are likely unimportant to me, and which I
should look
at more closely.
I get the impression that your applications have only one or two
compilation units
(.cc files) with flags defined. Inside google, our apps often link in
dozens of
compilation units, and the sorting by compilation unit is extremely
helpful, as is
the ability to use --helpshort, --helpmodule, etc.
} Sorry, I may not have explained well.. By "my" flags I mean the flags
that I have
} declared (not gflags flags).
Let's say your project uses both gflags and glog. Would the flags defined
by glog be
'your' flags too? It seems to me it's not really a well-defined concept.
I think it could be possible to customize gflags more, but the API is
already wider
than I would like. gflags will be overkill for some types of flag usage
(often those
where getopt would work ok) and maybe not a good fit for other kinds (where
the order
of the flags is important, say). We've aimed for a spot that fills a
previously
unfilled need, that has proven useful in practice, but I can't claim it
will be
perfect for every commandline-flags need.
google...@googlecode.com
Comment #4 on issue 32 by exportfs: Customize default --help message
http://code.google.com/p/google-gflags/issues/detail?id=32
Darn, I understand both the OPs and your POV. When folks who use my apps
type ./app
--help, they are going to get a lot of help info which buries the flags
that they are
most interested in. Because - and here is the kicker for me - I wrote a
library that
my apps call, and the flags are defined in that library, just like glog and
gflags
which also spew their useful but distracting flags on the output.
--helpshort doesn't help me (pun not intended but funny still, eh?),
because the apps
that define main don't declare/define the flags - they are in the lib.
--helpmatch isn't useful for the users because how would they know what the
module
was called that defines the flags:
$ ./src/insertTrapCount --helpmatch=Logger
insertTrapCount: test message
Flags from ../../gmasklib/GmaskLogger.cc:
-debug (enable debug support) type: bool default: false
-devel (enable devel MySQL server) type: bool default: false
-dsn (output DSN and exit) type: bool default: false
-host (MySQL server host) type: string default: "gr-icads3"
-port (MySQL server port) type: int32 default: 3306
-trace (enable tracing support) type: bool default: false
$
You can imagine what that looks like using --help.
I guess the real problem is that it is un-unix-y to put flags into a
library. But
even then --help IMHO should only be an alias to --helpshort and not
--helpfull
Then if I had a way to specify what --helpshort meant. Maybe a vector with
a list of
modules that I specify instead of using ProgramInvocationShortName().
Not sure what to do, but fortunately I can punt this for a bit.
-jim
As an aside, I think --help is more useful to folks who know a lot about
programming
and computers rather then most folks who actually run the apps to get some
small part
of their job done and may not be all that conversant in programming or
computers, and
I'm talking about engineers.
google...@googlecode.com
Comment #5 on issue 32 by csilvers: Customize default --help message
http://code.google.com/p/google-gflags/issues/detail?id=32
We have some vague idea of a good solution for this problem, which is to
let users
identify 'key' flags, and have --help show only those by default (with a
pointer to a
new --helpall flag). Or maybe we can allow the programmer to identify
flags that are
required, vs widely useful, vs occassionally useful, vs expert only, etc.
All of
these would require more work by the programmer, and we haven't really
figured out
which would give the most benefit for the effort (if any), but we may try
to do
something like this for a future release.
google...@googlecode.com
Comment #6 on issue 32 by csilvers: Customize default --help message
http://code.google.com/p/google-gflags/issues/detail?id=32
I think the plan in issue 38 will be the best way of addressing this
issue. You should be able to use categories to get flags displayed in a
way more to your liking (I'm hoping!). Of course, we'll have to wait to
see how the design turns out to see if it really addresses the needs here.
google...@googlecode.com
Comment #7 on issue 32 by toniloCo...@gmail.com: Customize default --help
message
http://code.google.com/p/google-gflags/issues/detail?id=32
What a developer! A user of your code ask you for a problem with your code
and you treat him as if he were a fool.
Ask for help to any utility and see how clear and concise is the help it
gives you.
I also want my programs to be intuitive and that, when my user asks for
help, it be clear and concise. I'm not a fool, I put myself in the scene of
my user, which is what you are not doing when answering Pablo in that way.
If I include the directive STRIP_FLAG_HELP 1 (before the #include
gflags.h), when compiling it gives me an error about a missing
kStrippedFlagHelp declaration.
If I call my program with -helpShort it tells me that he can't find the
module, even when everything about GFLAGS is defined in the unique module,
which contains the function main(), and -help flag get a bunch of spaghetti
text that the user has to read to find, at the end, my help on the only 2
parameters that I have defined, and which are the only ones that concern to
him.
But when a user asks you for help with this, you treat him like a fool
(What do you mean by "my flags"?). Fantastic!
google...@googlecode.com
Comment #8 on issue 32 by csilv...@gmail.com: Customize default --help
message
http://code.google.com/p/google-gflags/issues/detail?id=32
Parsing out the contentful part of your message, it seems you're reporting
two bugs:
1) A compile error when STRIP_FLAG_HELP is set
2) Some sort of problem with --helpshort
Each of these should really be its own bug report ('issue' in google code
terminology). Please say exactly what you did, and exactly what the
compiler/program output was. It also is helpful to know what compiler you
used, on what OS.