[cfe-dev] scan-build man page

[James K. Lowden]

On Thu, 10 May 2012 11:57:32 -0700
Ted Kremenek <kremenek at apple.com> wrote:
> On May 10, 2012, at 11:32 AM, "James K. Lowden"
> <jklowden at schemamania.org> wrote:
> 
> > Ted, no, really.  How can you disagree?  How is 
> > 
> > 	$ git checkout --help 
> > 
> > "a degree more powerful" than 
> > 
> > 	$ man git-checkout
>
> To clarify my position, the usage of git I was referring to was:
> 
> $ git help <command>

I see.  We're taking different lessons from the same interface.  Let's
talk git for a bit.  I'll leave how it applies to scan-build for
another message.  

> $ git
> usage: git [--version] [--exec-path[=<path>]] [--html-path]
> [--man-path] [--info-path] [-p|--paginate|--no-pager]
> [--no-replace-objects] [--bare] [--git-dir=<path>]
> [--work-tree=<path>] [--namespace=<name>] [-c name=value] [--help]
>            <command> [<args>]

I would be almost OK with this if it stopped there.  I'm sure you agree
that it's nice if a command typed without arguments does something
useful with its defaults.  Sometimes there are no defaults:

$ rm
usage: rm [-f|-i] [-dPRrvW] file ...

but git has many choices.  Splatting the table of contents on the
screen is not a good one.  A repository status summary would be.  

Why do I object?  Good choices afford greater convenience with
increasing experience.  After I've used git for a week, I don't need a
one-line explanation of add, clone, pull, push, diff, and commit.  I
definitely don't need to be reminded to 

> See 'git help <command>' for more information on a specific command.

with its gratuitous blank line before.  

git has chosen to use the smallest possible command to print a
beginner's introduction.  It assumes the screen is 30 lines high and
that the user hasn't used -h and --help before.  And it's completely
redundant with "git help".  Doesn't that strike you as just a little
condescending?  

Now pretend it did this instead:

$ git
100 files in 7 directories
4 modified
17 unknown

$ git -h
add bisect branch checkout clone commit diff fetch grep help 
init log merge mv pull push rebase reset rm show status tag

Those are two things man(1) can't do, both useful to the experienced
user.  

Hmm.  We're a little off-topic here.  I should submit this to git
list.  But one battle at a time.  ;-) 

> I can then do (as suggested):
> 
> $ git help pull
... 
> I don't have to memorize a
> hundred different commands, or figure out how they map to a man page.

Are you sure you want to hang your hat on that?  These three commands do
exactly the same thing:

	$ git help pull
	$ git pull --help
	$ man git-pull

You can count on one hand the synapses devoted to mapping "git help
pull" to "man git-pull"!  How is one easier to remember than the
others?  More consistent?  

> I don't need to know the specific command this maps to, because it
> doesn't matter.  

Yes it does matter.  How does "git help" lead you from "git pull" to
"git clone" or whatever?  You have to know what you're looking for.
"git help foo" won't find it for you.  ("git apropos foo" would be
useful, though.)  

The only innovation I see in this interface worth emulation, if
anything, is that --help invokes the man(1) instead of just scrolling
plain text off the screen.  I have that filed under "lessons learned
from Subversion."  

A separate and interesting question is how to document scan-build's
checkers.  Let me go there next.  

--jkl