cmd: update formatting of usage messages

R=golang-dev, r, minux.ma
CC=golang-dev
https://golang.org/cl/5738045

src/cmd/cgo/doc.go

@@ -6,7 +6,8 @@
 
 Cgo enables the creation of Go packages that call C code.
 
-Usage: go tool cgo [compiler options] file.go
+Usage:
+	go tool cgo [compiler options] file.go
 
 The compiler options are passed through uninterpreted when
 invoking gcc to compile the C parts of the package.

src/cmd/cov/doc.go

@@ -6,12 +6,14 @@
 
 Cov is a rudimentary code coverage tool.
 
+Usage:
+	go tool cov [-lsv] [-g substring] [-m minlines] [6.out args]
+
 Given a command to run, it runs the command while tracking which
 sections of code have been executed.  When the command finishes,
 cov prints the line numbers of sections of code in the binary that
 were not executed.   With no arguments it assumes the command "6.out".
 
-Usage: go tool cov [-lsv] [-g substring] [-m minlines] [6.out args]
 
 The options are:
 

src/cmd/go/doc.go

@@ -5,7 +5,9 @@
 /*
 Go is a tool for managing Go source code.
 
-Usage: go command [arguments]
+Usage:
+
+	go command [arguments]
 
 The commands are:
 
@@ -49,11 +51,13 @@ If the arguments are a list of .go files, build treats them as a list
 of source files specifying a single package.
 
 When the command line specifies a single main package,
-build writes the resulting executable to output (default a.out).
+build writes the resulting executable to output.
 Otherwise build compiles the packages but discards the results,
 serving only as a check that the packages can be built.
 
-The -o flag specifies the output file name.
+The -o flag specifies the output file name.  If not specified, the
+name is packagename.a (for a non-main package) or the base
+name of the first source file (for a main package).
 
 The build flags are shared by the build, install, run, and test commands:
 
@@ -389,6 +393,9 @@ See also: go fmt, go fix.
 
 GOPATH environment variable
 
+The Go path is used to resolve import statements.
+It is implemented by and documented in the go/build package.
+
 The GOPATH environment variable lists places to look for Go code.
 On Unix, the value is a colon-separated string.
 On Windows, the value is a semicolon-separated string.
@@ -472,7 +479,7 @@ An import path is a pattern if it includes one or more "..." wildcards,
 each of which can match any string, including the empty string and
 strings containing slashes.  Such a pattern expands to all package
 directories found in the GOPATH trees with names matching the
-patterns.  For example, encoding/... expands to all package
+patterns.  For example, encoding/... expands to all packages
 in subdirectories of the encoding tree, while net... expands to
 net and all its subdirectories.
 

src/cmd/go/main.go

@@ -141,7 +141,9 @@ func main() {
 
 var usageTemplate = `Go is a tool for managing Go source code.
 
-Usage: go command [arguments]
+Usage:
+
+	go command [arguments]
 
 The commands are:
 {{range .}}{{if .Runnable}}

src/cmd/pack/doc.go

@@ -12,7 +12,8 @@ It adds a special Go-specific section __.PKGDEF that collects all the
 Go type information from the files in the archive; that section is
 used by the compiler when importing the package during compilation.
 
-Usage: go tool pack [uvnbailogS][mrxtdpq][P prefix] archive files ...
+Usage:
+	go tool pack [uvnbailogS][mrxtdpq][P prefix] archive files ...
 
 The new option 'g' causes pack to maintain the __.PKGDEF section
 as files are added to the archive.

src/cmd/prof/doc.go

@@ -16,8 +16,8 @@ the program's state even when it is not running, such as when it is
 asleep or waiting for I/O.  Each thread contributes equally to the
 statistics.
 
-
+Usage:
-Usage: prof -p pid [-t total_secs] [-d delta_msec] [6.out args ...]
+	go tool prof -p pid [-t total_secs] [-d delta_msec] [6.out args ...]
 
 The output modes (default -h) are:
 

src/cmd/yacc/doc.go

@@ -4,10 +4,13 @@
 
 /*
 
-Yacc is a version of yacc for Go. It is run with the command
+Yacc is a version of yacc for Go.
-	go tool yacc args...
 It is written in Go and generates parsers written in Go.
 
+Usage:
+
+	go tool yacc args...
+
 It is largely transliterated from the Inferno version written in Limbo
 which in turn was largely transliterated from the Plan 9 version
 written in C and documented at