<html><head><meta http-equiv="Content-Type" content="text/html charset=us-ascii"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; ">(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)<div><br><div><div>On May 10, 2012, at 11:32 AM, "James K. Lowden" <<a href="mailto:jklowden@schemamania.org">jklowden@schemamania.org</a>> wrote:</div><br class="Apple-interchange-newline"><blockquote type="cite"><span style="font-family: Helvetica; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; display: inline !important; float: none; ">Ted, no, really. How can you disagree? How is<span class="Apple-converted-space"> </span></span><br style="font-family: Helvetica; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; "><br style="font-family: Helvetica; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; "><span class="Apple-tab-span" style="font-family: Helvetica; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; white-space: pre; "> </span><span style="font-family: Helvetica; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; display: inline !important; float: none; ">$ git checkout --help<span class="Apple-converted-space"> </span></span><br style="font-family: Helvetica; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; "><br style="font-family: Helvetica; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; "><span style="font-family: Helvetica; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; display: inline !important; float: none; ">"a degree more powerful" than<span class="Apple-converted-space"> </span></span><br style="font-family: Helvetica; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; "><br style="font-family: Helvetica; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; "><span class="Apple-tab-span" style="font-family: Helvetica; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; white-space: pre; "> </span><span style="font-family: Helvetica; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; display: inline !important; float: none; ">$ man git-checkout</span><br style="font-family: Helvetica; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; "><br style="font-family: Helvetica; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; "><span style="font-family: Helvetica; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; display: inline !important; float: none; ">given that they produce exactly the same thing?</span><br style="font-family: Helvetica; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; "><br style="font-family: Helvetica; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; "><span style="font-family: Helvetica; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; display: inline !important; float: none; ">(Please, let the answer not include the verb "typing".) </span><br style="font-family: Helvetica; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; "></blockquote></div><br><div>To clarify my position, the usage of git I was referring to was:</div></div><div><br></div><div>$ git help <command></div><div><br></div><div>When I type "git" on my machine, I see:</div><div><br></div><div><div>$ git</div><div>usage: git [--version] [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]</div><div> [-p|--paginate|--no-pager] [--no-replace-objects] [--bare]</div><div> [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]</div><div> [-c name=value] [--help]</div><div> <command> [<args>]</div><div><br></div><div>The most commonly used git commands are:</div><div> add Add file contents to the index</div><div> bisect Find by binary search the change that introduced a bug</div><div> branch List, create, or delete branches</div><div> checkout Checkout a branch or paths to the working tree</div><div> clone Clone a repository into a new directory</div><div> commit Record changes to the repository</div><div> diff Show changes between commits, commit and working tree, etc</div><div> fetch Download objects and refs from another repository</div><div> grep Print lines matching a pattern</div><div> init Create an empty git repository or reinitialize an existing one</div><div> log Show commit logs</div><div> merge Join two or more development histories together</div><div> mv Move or rename a file, a directory, or a symlink</div><div> pull Fetch from and merge with another repository or a local branch</div><div> push Update remote refs along with associated objects</div><div> rebase Forward-port local commits to the updated upstream head</div><div> reset Reset current HEAD to the specified state</div><div> rm Remove files from the working tree and from the index</div><div> show Show various types of objects</div><div> status Show the working tree status</div><div> tag Create, list, delete or verify a tag object signed with GPG</div><div><br></div><div>See 'git help <command>' for more information on a specific command.</div></div><div><br></div><div><br></div><div>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):</div><div><br></div><div>$ git help pull</div><div><br></div><div>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.</div><div><br></div><div><blockquote type="cite">I don't like the idea that everyone needs to learn each utility's<br>idiosyncratic way to view documentation. We have man(1). Why the<br>complication of N ways to do 1 thing? </blockquote><br></div><div>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)?</div><div><br></div><div>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.</div><div><br></div></body></html>