[cfe-dev] scan-build man page
kremenek at apple.com
Thu May 10 11:57:32 PDT 2012
(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:
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]
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...
More information about the cfe-dev