[cfe-dev] scan-build man page

[Ted Kremenek]

(my apologies for breaking up your email with multiple responses, but I find it a bit cleaner so that specific issues can be isolated from one another)

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
> 
> given that they produce exactly the same thing?
> 
> (Please, let the answer not include the verb "typing".)  

To clarify my position, the usage of git I was referring to was:

$ git help <command>

When I type "git" on my machine, I see:

$ 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>]

The most commonly used git commands are:
   add        Add file contents to the index
   bisect     Find by binary search the change that introduced a bug
   branch     List, create, or delete branches
   checkout   Checkout a branch or paths to the working tree
   clone      Clone a repository into a new directory
   commit     Record changes to the repository
   diff       Show changes between commits, commit and working tree, etc
   fetch      Download objects and refs from another repository
   grep       Print lines matching a pattern
   init       Create an empty git repository or reinitialize an existing one
   log        Show commit logs
   merge      Join two or more development histories together
   mv         Move or rename a file, a directory, or a symlink
   pull       Fetch from and merge with another repository or a local branch
   push       Update remote refs along with associated objects
   rebase     Forward-port local commits to the updated upstream head
   reset      Reset current HEAD to the specified state
   rm         Remove files from the working tree and from the index
   show       Show various types of objects
   status     Show the working tree status
   tag        Create, list, delete or verify a tag object signed with GPG

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


To me this is awesome.  I see a short table of contents of things I can drill down into, with instructions on how to get there.  I can then do (as suggested):

$ git help pull

and I get even more precise documentation.  I don't need to know the specific command this maps to, because it doesn't matter.  I really like that fact that the 'git' executable is a one stop shop for getting all my functionality out of git.  I don't have to memorize a hundred different commands, or figure out how they map to a man page.

> 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?  

That's an excellent argument, and the only reason I would say do it a different way is if it provided significant increased value to the users.  For me the workflow I described above is awesome.  That doesn't mean that I don't think a man page for git isn't useful, but it inherently maps you into a different universe where you have reason about each command separately (otherwise, how else would you be able to look up the man page information for that specific bit of functionality)?

Now scan-build isn't git.  The options are fairly simple, and most of them exist today because of stupid limitations in its current implementation.  The only thing I see changing quickly is the list of checkers, which was my main point of contention in my original email.  Should those be included in the man page, and if so, how much information?  It's not like the current documentation on the existing checkers is adequate.  Where should that information go?  In the man page?  If so, do we enter a place where the man page gets ridiculously long and lacks focus?  After the discussion on this thread, my current inclination is that the documentation on specific checkers should go elsewhere (e.g., the website).  Perhaps these are bike shed questions, but they are important.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20120510/f5fa00ef/attachment.html>