code review 5906043: doc/reference-cmd.html: new introduction

doc/reference-cmd.html: new introduction
Compare and explain go, go cmd, and go tool cmd.
The situation is not concisely explained elsewhere in the main docs.

[r, 2012-03-23 22:09:59]

Hello golang-dev@googlegroups.com,

I'd like you to review this change to
https://code.google.com/p/go/

[bradfitz, 2012-03-23 22:12:58]

LGTM
 On Mar 23, 2012 3:10 PM, <r@golang.org> wrote:

> Reviewers: golang-dev_googlegroups.com,
>
> Message:
> Hello golang-dev@googlegroups.com,
>
> I'd like you to review this change to
> https://code.google.com/p/go/
>
>
> Description:
> doc/reference-cmd.html: new introduction
> Compare and explain go, go cmd, and go tool cmd.
> The situation is not concisely explained elsewhere in the main docs.
>
> Please review this at
http://codereview.appspot.com/**5906043/<http://codereview.appspot.com/5906043/>
>
> Affected files:
>  M doc/reference-cmd.html
>
>
> Index: doc/reference-cmd.html
> ==============================**==============================**=======
> --- a/doc/reference-cmd.html
> +++ b/doc/reference-cmd.html
> @@ -4,7 +4,38 @@
>  }-->
>
>  <p>
> -Click on the links for more documentation and usage messages.
> +There is a suite of programs to build and process Go source code.
> +Instead of being run directly, programs in the suite are usually invoked
> +by the <a href="/cmd/go/">go</a> program.
> +</p>
> +
> +<p>
> +The most common way to run these programs is as a subcommand of the go
> +program,
> +for instance as "go fmt". Run like this, the command operates on complete
> +packages of Go source code, with the go program invoking the underlying
> binary
> +with arguments appropriate to package-level invocation.
> +</p>
> +
> +<p>
> +The programs can also be run as stand-alone binaries, with unmodified
> arguments,
> +using the go tool subcommand, such as "go tool fmt".
> +This style of invocation allows, for instance, reformatting a single
> source file rather than
> +an entire package: "go tool fmt myprogram.go" as compared to
> +"go fmt mypackage".
> +Some of the commands, such as prof and yacc, are accessible
> +only through the go tool subcommand.
> +</p>
> +
> +<p>
> +Finally, two of the commands, fmt and
> +doc, are also installed as regular binaries called
> +gofmt and godoc
> +because they are so often referenced.
> +</p>
> +
> +<p>
> +Click on the links for more documentation, invocation methods, and usage
> details.
>  </p>
>
>  <table class="dir">
> @@ -18,10 +49,9 @@
>  <td><a href="/cmd/go/">go</a></td>
>  <td>&nbsp;&nbsp;&nbsp;&nbsp;</**td>
>  <td>
> -Go is a tool for managing Go source code.
> -<br>
> -Besides compiling and running Go programs, the go command is also used to
> -invoke the other commands listed below. See the command docs for usage
> +The <code>go</code> program manages Go source code and runs the other
> +commands listed here.
> +See the command docs for usage
>  details.
>  <br><br>
>  </td>
> @@ -76,7 +106,7 @@
>  <tr>
>  <td><a href="/cmd/yacc/">yacc</a></**td>
>  <td>&nbsp;&nbsp;&nbsp;&nbsp;</**td>
> -<td>Yacc is a version of yacc for Go.</td>
> +<td>Yacc is a version of yacc that generates parsers implemented in
> Go.</td>
>  </tr>
>
>  </table>
>
>
>

[r, 2012-03-23 22:29:14]

*** Submitted as http://code.google.com/p/go/source/detail?r=99d6ee77a7fd ***

doc/reference-cmd.html: new introduction
Compare and explain go, go cmd, and go tool cmd.
The situation is not concisely explained elsewhere in the main docs.

R=golang-dev, bradfitz
CC=golang-dev
http://codereview.appspot.com/5906043

[minux1, 2012-03-24 06:17:26]

http://codereview.appspot.com/5906043/diff/4001/doc/reference-cmd.html
File doc/reference-cmd.html (right):

http://codereview.appspot.com/5906043/diff/4001/doc/reference-cmd.html#newcode22
doc/reference-cmd.html:22: using the go tool subcommand, such as "go tool fmt".
sorry, but we can't invoke gofmt with 'go tool fmt'
I think this example could be better made with 'go tool vet'.