[cfe-dev] scan-build man page

[James K. Lowden]

On Mon, 07 May 2012 16:20:54 -0700
Ted Kremenek <kremenek at apple.com> wrote:

> > I would remove the help text from scan-build.  You don't need it
> > anymore.  "man scan-build" is easier to use, and everyone knows how.
> 
> I disagree.  One of the things I like about git is "git help
> <command>".  I find that interactive help wonderful, and a degree
> more powerful than a static man page.  

Ted, no, really.  How can you disagree?  How is 

	$ git checkout --help 

"a degree more powerful" than 

	$ man git-checkout

given that they produce exactly the same thing?

(Please, let the answer not include the verb "typing".)  

I don't like the idea that everyone needs to learn each utility's
idiosyncratic way to view documentation.  We have man(1).  Why the
complication of N ways to do 1 thing?  

Here's a rule of thumb for you: -h or --help should, for any command,
produce at *most* 2 lines of help  If you need more than that, you
should be reading the documentation, not asking for help.  

$ ls --help
ls: unknown option -- -
usage: ls [-AaBbCcdFfghikLlmnopqRrSsTtuWwx1] [file ...]

A good man utility can extract just the synopsis.  On my
system today, I can do this: 

$ man -h scan-build
scan-build [-ohkvV] [-analyze-headers] [-enable-checker [checker_name]]
[-disable-checker [checker_name]] [--help]
[--html-title [=title]] [--keep-going] [--plist]
[--plist-html] [--status-bugs] [--use-c++ [=compiler_path]]
[--use-cc [=compiler_path]] [--view] [-constraints [model]]
[-maxloop N] [-no-failure-reports] [-stats] [-store [model]]
build_command [build_options]

Isn't that nice?  Even better: it's *standard*.  

I would change scan-build to behave thus:

	$ scan-build --help
	See "man scan-build" for documentation. 

	$ scan-build
	scan-build: fatal error: no input files
	analysis terminated.

(You want this behavior for automated batch processing, to
detect invocations that fail to provide command-line arguments.)  

We could add one more:

	$ scan-build --man

to call exec(3) with /usr/bin/man.  That way we can claim to have
invented something.  

> The last thing I want to do is every time I roll a new
> checker build that I need to manually check if the list of checkers
> in the man page is up-to-date.

OK, but that's orthogonal to how the documentation is
maintained.  Better to check the documentation than to generate it.  

First, let's not exaggerate.  If there are N checkers and you add one,
you have to check the man page for 1, not N.  At release time, the
primary focus should be not counting checkers, but ensuring that the
documentation is coherent and accurate.  No machine can do that.  

Second, you will find, in practice, that editing the man page
"manually" is in fact easier and produces better results. Why?  Checker
descriptions require markup.  Markup is a domain of knowledge. The
people who know that domain best are not necessarily the ones adding
the checkers.  Requiring markup in some tiny doc-fragment in Options.td
-- which itself uses *other* markup -- by someone who doesn't know or
care about markup is a recipe for inconsistency and error.  Requiring
the person taking care of the man page to grovel around in some other
file is a good way to encourage him to find something better to do with
his time.  

Third and last, to verify that the checker list and the documentation
are in sync doesn't require the documentation be generated.  It requires
only that they be verified.  If TableGen (or whatever) produced a simple
ASCII list of checkers, a tiny shell script could scrape through the
man page to make sure they're all present and accounted for.  Here,
let me help:

$ sed -ne '/Sh..*CHECKER/,$p' scan-build.1 \
	| awk  '/^\.It/ {print$2}'
core.AdjustedReturnValue
core.AttributeNonNull
core.CallAndMessage
core.DivideZero
core.NullDereference
core.StackAddressEscape
core.UndefinedBinaryOperatorResult
core.VLASize
core.builtin.BuiltinFunctions
core.builtin.NoReturnFunctions
....

Let me know when TableGen is ready.  

But let me make one more point about time and how it's spent, now that
we're friends.  Creating the man page for scan-build from scratch took
an hour or so. The best and most appropriate response, not that I
expected it, would have been Thank You.  The answer instead, on this
list and off, has been that a machine could have done it.  The shortest
and best answer to that might be: Show me.  

But I'm not that smart, so I engaged in a discussion, which discussion
has so far taken me -- because I have to articulate my arguments
carefully, in public, to people whose backgrounds I don't know -- about
six hours.  And we're not done, and whatever system build fu we're
going to have is also not done.  How much better those hours might have
been spent creating other man pages instead!  

To you and the others who object on theoretical grounds, I say: Peace!
Don't let's create a new problem to solve.  You didn't have a proper
man page, and some guy in a time machine parachutes one in for you.
Is it a puppy?  No!  Cool.  "svn add"!  Maybe he'll do another!  What's
the worst case? A few hours over a few years dealing with -mdoc.  If
that really turns into a hassle, you can go and build your
doc-generator and "svn rm". Meanwhile, work deferred is time bought for
something productive. What's not to like?  

Regards, 

--jkl