Customize default --help message

[GoogleCodeExporter]

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

Original issue reported on code.google.com by pablo.c...@gmail.com on 7 Jan 2010 at 4:01

[GoogleCodeExporter]

} 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.

Original comment by csilv...@gmail.com on 8 Jan 2010 at 4:06

• Added labels: Type-Enhancement
• Removed labels: Type-Defect

[GoogleCodeExporter]

}} 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). 

Original comment by pablo.c...@gmail.com on 8 Jan 2010 at 11:16

[GoogleCodeExporter]

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.

Original comment by csilv...@gmail.com on 8 Jan 2010 at 3:51

[GoogleCodeExporter]

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.

Original comment by expor...@gmail.com on 1 Apr 2010 at 3:43

[GoogleCodeExporter]

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.

Original comment by csilv...@gmail.com on 3 Apr 2010 at 2:02

[GoogleCodeExporter]

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.

Original comment by csilv...@gmail.com on 14 Oct 2010 at 1:31

[GoogleCodeExporter]

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!

Original comment by toniloCo...@gmail.com on 15 Jan 2011 at 9:36

[GoogleCodeExporter]

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.

Original comment by csilv...@gmail.com on 20 Jan 2011 at 1:06

[GoogleCodeExporter]

I've been working recently on flag categories (issue 38), with the hope they 
could be used to clean up the --help output.  I'm getting some pushback from 
some relevant folks (big users inside google), who are not convinced of the 
complexity/benefit trade-off.

I agree --help output is a bit of a mess right now, and would like to make it 
better.  I don't think there's general agreement how to do that, though.  I'll 
keep this bug open while we figure it out.

Original comment by csilv...@gmail.com on 25 Aug 2011 at 11:53

[GoogleCodeExporter]

Note to self: Look into suggestion of "key" flags as also possible in case of 
the python-gflags library. Additional to the custom categorization/grouping of 
flags, this could help be considered for the --helpshort output.

Original comment by andreas....@gmail.com on 20 Mar 2014 at 4:06

• Added labels: Milestone-v2.2

[GoogleCodeExporter]

Could you guys maybe just change the visibility of 
ShowUsageWithFlagsMatching()? It's pretty easy to wire up a less 'wordy' help 
message using it.  Attaching a trivial patch in case it's interesting. I've 
been hijacking the default help message with this patch applied, using 
something like this:

void parse_options(int argc, char* argv[])
{
    if (argc > 1 && std::string(argv[1]) == "--help")
    {
        // Any files defining commandline flags should be listed here so
        // they show up in the help message
        std::vector<std::string> flags_files {
            "main.cpp",
            "HardwareInterface.cpp"
        };

        gflags::ShowUsageWithFlagsMatching(argv[0], flags_files);
        exit(0);
    }

    else
    {
        bool const removeFlags = false;
        gflags::ParseCommandLineFlags(&argc, &argv, removeFlags);
    }
}

I'd be *very* interested to know if there are simpler alternatives I've missed. 
In particular, there's a tantalizing hint about a STRIP_FLAG_HELP macro that, 
if defined, removes a bunch of (gflags-internal?) flags from the help output. I 
tried doing:

#define STRIP_FLAG_HELP 1
#include <gflags/gflags.h>

but this did not seem to change the default '--help' output at all. (Maybe I 
did something wrong, or didn't do enough?)

Oh, and in case it's still not clear what the issue is: running a gflags-aware 
app with --help generates a *ton* of output that our users aren't interested 
in. 'Our' flags (i.e., the ones our application defines, not the flags defined 
by the gflags library itself) kind of get 'lost in the noise'.  From a 
non-googler's perspective, it seems a little unfortunate that the behavior of 
'--help' isn't more like '--helpshort'. It seems natural to keep the output for 
'--hello' short/terse, and require '--helpfull' if users really want to see 
*all* flags.

Just my $0.02. It's not a big deal, I figured out how to make it do what I 
want, anyway, just thought you guys might appreciate the feedback. Thanks for a 
great library! The locality of reference is awesome, and I love not having to 
pass argc/argv (or an Options object) all over my applications any more. Total 
slam dunk...

Original comment by evadef...@gmail.com on 11 Apr 2014 at 8:09

Attachments:

• gflags-2.1.1-make-ShowUsageWithFlagsMatching-public.patch

[GoogleCodeExporter]

Thanks for your feedback and example use of ShowUsageWithFlagsMatching. I agree 
that the help output of gflags still leaves some user friendliness to desire. 
The goal is to address this with the next milestone and give the developer more 
freedom to customize the output without having to implement all over again (you 
can always provide your own implementations of what gflags_reporting.cc 
contains). Removing some of the standard gflags library flags from the default 
help output sounds reasonable. I will consider it when making the help output 
related changes.

STRIP_FLAG_HELP is supposed to simply discard all help strings from the binary 
to reduce its file size (i.e., any string literals passed on as arguments to 
the DEFINE_* macros are discarded by the preprocessor). It is intended for 
deploying binaries whose help output you don't need because they are not (or no 
longer) called by a (human) directly or just to strip the help of certain flags 
defined in some modules. Maybe also partially for obfuscation purposes (just 
guessing what else it could be useful for).

P.S.: The gflags library is since 2.0 in "public" hands. I have no affiliation 
with Google other than being a user of their services myself. In other words, I 
am not restricted by the demands and interests of those "relevant folks (big 
users inside google)" Craig mentioned in his last comment. I suspect that 
Google anyway has its own internal fork and is not interested in any additional 
features. That said, its now up to the Open Source community how the gflags 
library will evolve further.

Original comment by andreas....@gmail.com on 12 Apr 2014 at 12:05