document the gc go compilers.

fix the usage message.

R=rsc
CC=go-dev
http://go/go-review/1016033

src/cmd/5g/doc.go

@@ -0,0 +1,15 @@
+// Copyright 2009 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/*
+
+5g is the version of the gc compiler for the ARM,
+referred to by these tools as arm.
+
+It reads .go files and outputs .5 files. The flags are documented in ../gc/doc.go.
+
+There is no instruction optimizer, so the -N flag is a no-op.
+
+*/
+package documentation

src/cmd/5l/doc.go

@@ -9,6 +9,8 @@
 	http://plan9.bell-labs.com/magic/man2html/1/2l
 
 Its target architecture is the ARM, referred to by these tools as arm.
+It reads files in .5 format generated by 5g, 5c, and 5a and emits
+a binary called 5.out by default.
 
 Major changes include:
 	- support for segmented stacks (this feature is implemented here, not in the compilers).

src/cmd/6g/doc.go

@@ -0,0 +1,13 @@
+// Copyright 2009 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/*
+
+6g is the version of the gc compiler for the x86-64,
+referred to by these tools as amd64.
+
+It reads .go files and outputs .6 files. The flags are documented in ../gc/doc.go.
+
+*/
+package documentation

src/cmd/6l/doc.go

@@ -9,6 +9,8 @@
 	http://plan9.bell-labs.com/magic/man2html/1/2l
 
 Its target architecture is the x86-64, referred to by these tools as amd64.
+It reads files in .6 format generated by 6g, 6c, and 6a and emits
+a binary called 6.out by default.
 
 Major changes include:
 	- support for ELF and Mach-O binary files 

src/cmd/8g/doc.go

@@ -0,0 +1,15 @@
+// Copyright 2009 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/*
+
+8g is the version of the gc compiler for the x86,
+referred to by these tools for historical reasons as 386.
+
+It reads .go files and outputs .8 files. The flags are documented in ../gc/doc.go.
+
+There is no instruction optimizer, so the -N flag is a no-op.
+
+*/
+package documentation

src/cmd/8l/doc.go

@@ -9,6 +9,8 @@
 	http://plan9.bell-labs.com/magic/man2html/1/2l
 
 Its target architecture is the x86, referred to by these tools for historical reasons as 386.
+It reads files in .8 format generated by 8g, 8c, and 8a and emits
+a binary called 8.out by default.
 
 Major changes include:
 	- support for ELF and Mach-O binary files 

src/cmd/gc/doc.go

@@ -0,0 +1,46 @@
+// Copyright 2009 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/*
+
+The name gc is the generic label given to the family of Go compilers
+that function as part of the (modified) Plan 9 tool chain.  The C compiler
+documentation at
+
+	http://plan9.bell-labs.com/sys/doc/comp.pdf     (Tools overview)
+	http://plan9.bell-labs.com/sys/doc/compiler.pdf (C compiler architecture)
+
+gives the overall design of the tool chain.  Aside from a few adapted pieces,
+such as the optimizer, the Go compilers are wholly new programs.
+
+The compiler reads in a set of Go files, typically suffixed ".go".  They
+must all be part of one package.  The output is a single intermediate file
+representing the "binary assembly" of the compiled package, ready as input
+for the linker (6l, etc.).
+
+The generated files contain type information about the symbols exported by
+the package and about types used by symbols imported by the package from
+other packages. It is therefore not necessary when compiling client C of
+package P to read the files of P's dependencies, only the compiled output
+of P.
+
+Usage: 6g [flags] *.go  (or 8g or 5g)
+
+Flags:
+	-o file
+		output file, default 6.out for 6g, etc.
+	-e
+		normally the compiler quits after 10 errors; -e prints all errors
+	-I dir1 -I dir2
+		add dir1 and dir2 to the list of paths to check for imported packages
+	-N
+		disable optimization
+	-S
+		write assembly language text to standard output
+
+There are also a number of debugging flags; run the command with no arguments
+to get a usage message.
+
+*/
+package documentation

src/cmd/gc/lex.c

@@ -141,7 +141,7 @@ usage:
 	print("  -h panic on an error\n");
 	print("  -k name specify package name\n");
 	print("  -o file specify output file\n");
-	print("  -p print the assembly language\n");
+	print("  -S print the assembly language\n");
 	print("  -w print the parse tree after typing\n");
 	print("  -x print lex tokens\n");
 	exit(0);