Imported Upstream version 2012.03.22upstream-weekly/2012.03.22

114 files changed, 4181 insertions, 8359 deletions

diff --git a/doc/Makefile b/doc/Makefile
index ff69bc775..da29e600b 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -2,18 +2,24 @@
 # Use of this source code is governed by a BSD-style
 # license that can be found in the LICENSE file.
 
-HTML=\
-	articles/defer_panic_recover.html\
-	articles/error_handling.html\
-	articles/slices_usage_and_internals.html\
-	articles/laws_of_reflection.html\
-	effective_go.html\
-	go1.html\
+RAWHTML=\
+	articles/defer_panic_recover.rawhtml\
+	articles/error_handling.rawhtml\
+	articles/slices_usage_and_internals.rawhtml\
+	articles/laws_of_reflection.rawhtml\
+	articles/c_go_cgo.rawhtml\
+	articles/go_concurrency_patterns_timing_out_moving_on.rawhtml\
+	articles/godoc_documenting_go_code.rawhtml\
+	articles/gobs_of_data.rawhtml\
+	articles/json_and_go.rawhtml\
+	articles/image_draw.rawhtml\
+	effective_go.rawhtml\
+	go1.rawhtml\
 
-all: tmpltohtml $(HTML)
+all: $(RAWHTML)
 
-tmpltohtml: tmpltohtml.go
-	go build tmpltohtml.go
+%.rawhtml: %.html
+	godoc -url /doc/$< >$@
 
-%.html: %.tmpl tmpltohtml
-	./makehtml $*.tmpl
+clean:
+	rm -f $(RAWHTML)
diff --git a/doc/articles/c_go_cgo.html b/doc/articles/c_go_cgo.html
new file mode 100644
index 000000000..ac6bb29a2
--- /dev/null
+++ b/doc/articles/c_go_cgo.html
@@ -0,0 +1,180 @@
+<!--{
+"Title": "C? Go? Cgo!",
+"Template": true
+}-->
+
+<p>
+Cgo lets Go packages call C code. Given a Go source file written with some
+special features, cgo outputs Go and C files that can be combined into a
+single Go package.
+</p>
+
+<p>
+To lead with an example, here's a Go package that provides two functions -
+<code>Random</code> and <code>Seed</code> - that wrap C's <code>random</code>
+and <code>srandom</code> functions.
+</p>
+
+{{code "/doc/progs/cgo1.go" `/package rand/` `/END/`}}
+
+<p>
+Let's look at what's happening here, starting with the import statement.
+</p>
+
+<p>
+The <code>rand</code> package imports <code>"C"</code>, but you'll find there's
+no such package in the standard Go library. That's because <code>C</code> is a
+"pseudo-package", a special name interpreted by cgo as a reference to C's
+name space.
+</p>
+
+<p>
+The <code>rand</code> package contains four references to the <code>C</code>
+package: the calls to <code>C.random</code> and <code>C.srandom</code>, the
+conversion <code>C.uint(i)</code>, and the <code>import</code> statement.
+</p>
+
+<p>
+The <code>Random</code> function calls the standard C library's <code>random</code>
+function and returns the result.  In C, <code>random</code> returns a value of the
+C type <code>long</code>, which cgo represents as the type <code>C.long</code>.
+It must be converted to a Go type before it can be used by Go code outside this
+package, using an ordinary Go type conversion:
+</p>
+
+{{code "/doc/progs/cgo1.go" `/func Random/` `/STOP/`}}
+
+<p>
+Here's an equivalent function that uses a temporary variable to illustrate
+the type conversion more explicitly:
+</p>
+
+{{code "/doc/progs/cgo2.go" `/func Random/` `/STOP/`}}
+
+<p>
+The <code>Seed</code> function does the reverse, in a way. It takes a
+regular Go <code>int</code>, converts it to the C <code>unsigned int</code>
+type, and passes it to the C function <code>srandom</code>.
+</p>
+
+{{code "/doc/progs/cgo1.go" `/func Seed/` `/END/`}}
+
+<p>
+Note that cgo knows the <code>unsigned int</code> type as <code>C.uint</code>;
+see the <a href="/cmd/cgo">cgo documentation</a> for a complete list of
+these numeric type names.
+</p>
+
+<p>
+The one detail of this example we haven't examined yet is the comment
+above the <code>import</code> statement.
+</p>
+
+{{code "/doc/progs/cgo1.go" `/\/\*/` `/STOP/`}}
+
+<p>
+Cgo recognizes this comment.  Any lines starting
+with <code>#cgo</code>
+followed
+by a space character are removed; these become directives for cgo.
+The remaining lines are used as a header when compiling the C parts of
+the package.  In this case those lines are just a
+single <code>#include</code>
+statement, but they can be almost any C code.  The <code>#cgo</code>
+directives are
+used to provide flags for the compiler and linker when building the C
+parts of the package.
+</p>
+
+<p>
+There is a limitation: if your program uses any <code>//export</code>
+directives, then the C code in the comment may only include declarations
+(<code>extern int f();</code>), not definitions (<code>int f() {
+return 1; }</code>).  You can use <code>//export</code> directives to
+make Go functions accessible to C code.
+</p>
+
+<p>
+The <code>#cgo</code> and <code>//export</code> directives are
+documented in
+the <a href="/cmd/cgo/">cgo documentation</a>.
+</p>
+
+<p>
+<b>Strings and things</b>
+</p>
+
+<p>
+Unlike Go, C doesn't have an explicit string type. Strings in C are
+represented by a zero-terminated array of chars.
+</p>
+
+<p>
+Conversion between Go and C strings is done with the
+<code>C.CString</code>, <code>C.GoString</code>, and
+<code>C.GoStringN</code> functions. These conversions make a copy of the
+string data.
+</p>
+
+<p>
+This next example implements a <code>Print</code> function that writes a
+string to standard output using C's <code>fputs</code> function from the
+<code>stdio</code> library:
+</p>
+
+{{code "/doc/progs/cgo3.go" `/package print/` `/END/`}}
+
+<p>
+Memory allocations made by C code are not known to Go's memory manager.
+When you create a C string with <code>C.CString</code> (or any C memory
+allocation) you must remember to free the memory when you're done with it
+by calling <code>C.free</code>.
+</p>
+
+<p>
+The call to <code>C.CString</code> returns a pointer to the start of the
+char array, so before the function exits we convert it to an
+<a href="/pkg/unsafe/#Pointer"><code>unsafe.Pointer</code></a> and release
+the memory allocation with <code>C.free</code>. A common idiom in cgo programs
+is to <a href="/doc/articles/defer_panic_recover.html"><code>defer</code></a>
+the free immediately after allocating (especially when the code that follows
+is more complex than a single function call), as in this rewrite of
+<code>Print</code>:
+</p>
+
+{{code "/doc/progs/cgo4.go" `/func Print/` `/END/`}}
+
+<p>
+<b>Building cgo packages</b>
+</p>
+
+<p>
+To build cgo packages, just use <a href="/cmd/go/#Compile_packages_and_dependencies">"
+<code>go build</code>"</a> or
+<a href="/cmd/go/#Compile_and_install_packages_and_dependencies">"<code>go install</code>
+"</a> as usual. The go tool recognizes the special <code>"C"</code> import and automatically
+uses cgo for those files.
+</p>
+
+<p>
+<b>More cgo resources</b>
+</p>
+
+<p>
+The <a href="/cmd/cgo/">cgo command</a> documentation has more detail about
+the C pseudo-package and the build process. The <a href="/misc/cgo/">cgo examples</a>
+in the Go tree demonstrate more advanced concepts.
+</p>
+
+<p>
+For a simple, idiomatic example of a cgo-based package, see Russ Cox's <a
+href="http://code.google.com/p/gosqlite/source/browse/sqlite/sqlite.go">gosqlite</a>.
+Also, the Go Project Dashboard lists <a
+href="https://godashboard.appspot.com/project?tag=cgo">several other
+cgo packages</a>.
+</p>
+
+<p>
+Finally, if you're curious as to how all this works internally, take a look
+at the introductory comment of the runtime package's <a href="/src/pkg/runtime/cgocall.c">cgocall.c</a>.
+</p>
diff --git a/doc/articles/concurrency_patterns.html b/doc/articles/concurrency_patterns.html
new file mode 100644
index 000000000..63c8cd59e
--- /dev/null
+++ b/doc/articles/concurrency_patterns.html
@@ -0,0 +1,79 @@
+<!--{
+"Title": "Go Concurrency Patterns: Timing out, moving on",
+"Template": true
+}-->
+
+<p>
+Concurrent programming has its own idioms. A good example is timeouts. Although
+Go's channels do not support them directly, they are easy to implement. Say we
+want to receive from the channel <code>ch</code>, but want to wait at most one
+second for the value to arrive. We would start by creating a signalling channel
+and launching a goroutine that sleeps before sending on the channel:
+</p>
+
+{{code "/doc/progs/timeout1.go" `/timeout :=/` `/STOP/`}}
+
+<p>
+We can then use a <code>select</code> statement to receive from either
+<code>ch</code> or <code>timeout</code>. If nothing arrives on <code>ch</code>
+after one second, the timeout case is selected and the attempt to read from
+<cde>ch</cde> is abandoned.
+</p>
+
+{{code "/doc/progs/timeout1.go" `/select {/` `/STOP/`}}
+
+<p>
+The <code>timeout</code> channel is buffered with space for 1 value, allowing
+the timeout goroutine to send to the channel and then exit. The goroutine
+doesn't know (or care) whether the value is received. This means the goroutine
+won't hang around forever if the <code>ch</code> receive happens before the
+timeout is reached. The <code>timeout</code> channel will eventually be
+deallocated by the garbage collector.
+</p>
+
+<p>
+(In this example we used <code>time.Sleep</code> to demonstrate the mechanics
+of goroutines and channels. In real programs you should use <code>
+<a href="/pkg/time/#After">time.After</a></code>, a function that returns
+a channel and sends on that channel after the specified duration.)
+</p>
+
+<p>
+Let's look at another variation of this pattern. In this example we have a
+program that reads from multiple replicated databases simultaneously. The
+program needs only one of the answers, and it should accept the answer that
+arrives first.
+</p>
+
+<p>
+The function <code>Query</code> takes a slice of database connections and a
+<code>query</code> string. It queries each of the databases in parallel and
+returns the first response it receives:
+</p>
+
+{{code "/doc/progs/timeout2.go" `/func Query/` `/STOP/`}}
+
+<p>
+In this example, the closure does a non-blocking send, which it achieves by
+using the send operation in <code>select</code> statement with a
+<code>default</code> case. If the send cannot go through immediately the
+default case will be selected. Making the send non-blocking guarantees that
+none of the goroutines launched in the loop will hang around. However, if the
+result arrives before the main function has made it to the receive, the send
+could fail since no one is ready.
+</p>
+
+<p>
+This problem is a textbook of example of what is known as a
+<a href="https://en.wikipedia.org/wiki/Race_condition">race condition</a>, but
+the fix is trivial. We just make sure to buffer the channel <code>ch</code> (by
+adding the buffer length as the second argument to <a href="/pkg/builtin/#make">make</a>),
+guaranteeing that the first send has a place to put the value. This ensures the
+send will always succeed, and the first value to arrive will be retrieved
+regardless of the order of execution.
+</p>
+
+<p>
+These two examples demonstrate the simplicity with which Go can express complex
+interactions between goroutines.
+</p>
diff --git a/doc/articles/defer_panic_recover.html b/doc/articles/defer_panic_recover.html
index be97045dd..206b836d8 100644
--- a/doc/articles/defer_panic_recover.html
+++ b/doc/articles/defer_panic_recover.html
@@ -1,10 +1,7 @@
 <!--{
-	"Title": "Defer, Panic, and Recover"
+	"Title": "Defer, Panic, and Recover",
+	"Template": true
 }-->
-<!--
-  DO NOT EDIT: created by
-    tmpltohtml articles/defer_panic_recover.tmpl
--->
 
 <p>
 Go has the usual mechanisms for control flow: if, for, switch, goto.  It also
@@ -23,23 +20,7 @@ For example, let's look at a function that opens two files and copies the
 contents of one file to the other:
 </p>
  
-<pre><!--{{code "progs/defer.go" `/func CopyFile/` `/STOP/`}}
--->func CopyFile(dstName, srcName string) (written int64, err error) {
-    src, err := os.Open(srcName)
-    if err != nil {
-        return
-    }
-
-    dst, err := os.Create(dstName)
-    if err != nil {
-        return
-    }
-
-    written, err = io.Copy(dst, src)
-    dst.Close()
-    src.Close()
-    return
-}</pre>
+{{code "/doc/progs/defer.go" `/func CopyFile/` `/STOP/`}}
 
 <p>
 This works, but there is a bug. If the call to os.Create fails, the
@@ -50,22 +31,7 @@ noticed and resolved. By introducing defer statements we can ensure that the
 files are always closed:
 </p>
  
-<pre><!--{{code "progs/defer2.go" `/func CopyFile/` `/STOP/`}}
--->func CopyFile(dstName, srcName string) (written int64, err error) {
-    src, err := os.Open(srcName)
-    if err != nil {
-        return
-    }
-    defer src.Close()
-
-    dst, err := os.Create(dstName)
-    if err != nil {
-        return
-    }
-    defer dst.Close()
-
-    return io.Copy(dst, src)
-}</pre>
+{{code "/doc/progs/defer2.go" `/func CopyFile/` `/STOP/`}}
 
 <p>
 Defer statements allow us to think about closing each file right after opening
@@ -88,13 +54,7 @@ In this example, the expression "i" is evaluated when the Println call is
 deferred. The deferred call will print "0" after the function returns.
 </p>
  
-<pre><!--{{code "progs/defer.go" `/func a/` `/STOP/`}}
--->func a() {
-    i := 0
-    defer fmt.Println(i)
-    i++
-    return
-}</pre>
+{{code "/doc/progs/defer.go" `/func a/` `/STOP/`}}
 
 <p>
 2. <i>Deferred function calls are executed in Last In First Out order
@@ -105,12 +65,7 @@ deferred. The deferred call will print "0" after the function returns.
 This function prints "3210":
 </p>
 
-<pre><!--{{code "progs/defer.go" `/func b/` `/STOP/`}}
--->func b() {
-    for i := 0; i &lt; 4; i++ {
-        defer fmt.Print(i)
-    }
-}</pre>
+{{code "/doc/progs/defer.go" `/func b/` `/STOP/`}}
  
 <p>
 3. <i>Deferred functions may read and assign to the returning function's named
@@ -122,11 +77,7 @@ In this example, a deferred function increments the return value i <i>after</i>
 the surrounding function returns. Thus, this function returns 2:
 </p>
 
-<pre><!--{{code "progs/defer.go" `/func c/` `/STOP/`}}
--->func c() (i int) {
-    defer func() { i++ }()
-    return 1
-}</pre>
+{{code "/doc/progs/defer.go" `/func c/` `/STOP/`}}
  
 <p>
 This is convenient for modifying the error return value of a function; we will
@@ -156,36 +107,7 @@ to panic and resume normal execution.
 Here's an example program that demonstrates the mechanics of panic and defer:
 </p>
 
-<pre><!--{{code "progs/defer2.go" `/package main/` `/STOP/`}}
--->package main
-
-import &#34;fmt&#34;
-
-func main() {
-    f()
-    fmt.Println(&#34;Returned normally from f.&#34;)
-}
-
-func f() {
-    defer func() {
-        if r := recover(); r != nil {
-            fmt.Println(&#34;Recovered in f&#34;, r)
-        }
-    }()
-    fmt.Println(&#34;Calling g.&#34;)
-    g(0)
-    fmt.Println(&#34;Returned normally from g.&#34;)
-}
-
-func g(i int) {
-    if i &gt; 3 {
-        fmt.Println(&#34;Panicking!&#34;)
-        panic(fmt.Sprintf(&#34;%v&#34;, i))
-    }
-    defer fmt.Println(&#34;Defer in g&#34;, i)
-    fmt.Println(&#34;Printing in g&#34;, i)
-    g(i + 1)
-}</pre>
+{{code "/doc/progs/defer2.go" `/package main/` `/STOP/`}}
  
 <p>
 The function g takes the int i, and panics if i is greater than 3, or else it
diff --git a/doc/articles/defer_panic_recover.tmpl b/doc/articles/defer_panic_recover.tmpl
deleted file mode 100644
index 5f48c6ef4..000000000
--- a/doc/articles/defer_panic_recover.tmpl
+++ /dev/null
@@ -1,195 +0,0 @@
-<!--{
-	"Title": "Defer, Panic, and Recover"
-}-->
-{{donotedit}}
-<p>
-Go has the usual mechanisms for control flow: if, for, switch, goto.  It also
-has the go statement to run code in a separate goroutine.  Here I'd like to
-discuss some of the less common ones: defer, panic, and recover.
-</p>
- 
-<p>
-A <b>defer statement</b> pushes a function call onto a list. The list of saved
-calls is executed after the surrounding function returns. Defer is commonly
-used to simplify functions that perform various clean-up actions.
-</p>
- 
-<p>
-For example, let's look at a function that opens two files and copies the
-contents of one file to the other:
-</p>
- 
-{{code "progs/defer.go" `/func CopyFile/` `/STOP/`}}
-
-<p>
-This works, but there is a bug. If the call to os.Create fails, the
-function will return without closing the source file. This can be easily
-remedied by putting a call to src.Close() before the second return statement,
-but if the function were more complex the problem might not be so easily
-noticed and resolved. By introducing defer statements we can ensure that the
-files are always closed:
-</p>
- 
-{{code "progs/defer2.go" `/func CopyFile/` `/STOP/`}}
-
-<p>
-Defer statements allow us to think about closing each file right after opening
-it, guaranteeing that, regardless of the number of return statements in the
-function, the files <i>will</i> be closed.
-</p>
- 
-<p>
-The behavior of defer statements is straightforward and predictable. There are
-three simple rules:
-</p>
- 
-<p>
-1. <i>A deferred function's arguments are evaluated when the defer statement is
-evaluated.</i> 
-</p>
- 
-<p>
-In this example, the expression "i" is evaluated when the Println call is
-deferred. The deferred call will print "0" after the function returns.
-</p>
- 
-{{code "progs/defer.go" `/func a/` `/STOP/`}}
-
-<p>
-2. <i>Deferred function calls are executed in Last In First Out order
-</i>after<i> the surrounding function returns.</i> 
-</p>
- 
-<p>
-This function prints "3210":
-</p>
-
-{{code "progs/defer.go" `/func b/` `/STOP/`}}
- 
-<p>
-3. <i>Deferred functions may read and assign to the returning function's named
-return values.</i> 
-</p>
- 
-<p>
-In this example, a deferred function increments the return value i <i>after</i>
-the surrounding function returns. Thus, this function returns 2:
-</p>
-
-{{code "progs/defer.go" `/func c/` `/STOP/`}}
- 
-<p>
-This is convenient for modifying the error return value of a function; we will
-see an example of this shortly.
-</p>
- 
-<p>
-<b>Panic</b> is a built-in function that stops the ordinary flow of control and
-begins <i>panicking</i>. When the function F calls panic, execution of F stops,
-any deferred functions in F are executed normally, and then F returns to its
-caller. To the caller, F then behaves like a call to panic. The process
-continues up the stack until all functions in the current goroutine have
-returned, at which point the program crashes. Panics can be initiated by
-invoking panic directly. They can also be caused by runtime errors, such as
-out-of-bounds array accesses.
-</p>
- 
-<p>
-<b>Recover</b> is a built-in function that regains control of a panicking
-goroutine. Recover is only useful inside deferred functions. During normal
-execution, a call to recover will return nil and have no other effect. If the
-current goroutine is panicking, a call to recover will capture the value given
-to panic and resume normal execution.
-</p>
- 
-<p>
-Here's an example program that demonstrates the mechanics of panic and defer:
-</p>
-
-{{code "progs/defer2.go" `/package main/` `/STOP/`}}
- 
-<p>
-The function g takes the int i, and panics if i is greater than 3, or else it
-calls itself with the argument i+1. The function f defers a function that calls
-recover and prints the recovered value (if it is non-nil). Try to picture what
-the output of this program might be before reading on.
-</p>
- 
-<p>
-The program will output:
-</p>
- 
-<pre>Calling g.
-Printing in g 0
-Printing in g 1
-Printing in g 2
-Printing in g 3
-Panicking!
-Defer in g 3
-Defer in g 2
-Defer in g 1
-Defer in g 0
-Recovered in f 4
-Returned normally from f.</pre> 
-
-<p>
-If we remove the deferred function from f the panic is not recovered and
-reaches the top of the goroutine's call stack, terminating the program. This
-modified program will output:
-</p>
- 
-<pre>Calling g.
-Printing in g 0
-Printing in g 1
-Printing in g 2
-Printing in g 3
-Panicking!
-Defer in g 3
-Defer in g 2
-Defer in g 1
-Defer in g 0
-panic: 4
- 
-panic PC=0x2a9cd8
-[stack trace omitted]</pre> 
-
-<p>
-For a real-world example of <b>panic</b> and <b>recover</b>, see the
-<a href="/pkg/encoding/json/">json package</a> from the Go standard library.
-It decodes JSON-encoded data with a set of recursive functions.
-When malformed JSON is encountered, the parser calls panic to unwind the
-stack to the top-level function call, which recovers from the panic and returns
-an appropriate error value (see the 'error' and 'unmarshal' functions in
-<a href="/src/pkg/encoding/json/decode.go">decode.go</a>).
-</p>
-
-<p>
-The convention in the Go libraries is that even when a package uses panic
-internally, its external API still presents explicit error return values.
-</p>
- 
-<p>
-Other uses of <b>defer</b> (beyond the file.Close() example given earlier)
-include releasing a mutex:
-</p>
-
-<pre>mu.Lock()
-defer mu.Unlock()</pre> 
-
-<p>
-printing a footer:
-</p>
- 
-<pre>printHeader()
-defer printFooter()</pre> 
-
-<p>
-and more.
-</p>
- 
-<p>
-In summary, the defer statement (with or without panic and recover) provides an
-unusual and powerful mechanism for control flow.  It can be used to model a
-number of features implemented by special-purpose structures in other
-programming languages. Try it out.
-</p>
diff --git a/doc/articles/error_handling.html b/doc/articles/error_handling.html
index ac33f1dab..8f4fffb48 100644
--- a/doc/articles/error_handling.html
+++ b/doc/articles/error_handling.html
@@ -1,10 +1,7 @@
 <!--{
-	"Title": "Error Handling and Go"
+	"Title": "Error Handling and Go",
+	"Template": true
 }-->
-<!--
-  DO NOT EDIT: created by
-    tmpltohtml articles/error_handling.tmpl
--->
 
 <p>
 If you have written any Go code you have probably encountered the built-in
@@ -13,20 +10,14 @@ indicate an abnormal state. For example, the <code>os.Open</code> function
 returns a non-nil <code>error</code> value when it fails to open a file.
 </p>
 
-<pre><!--{{code "progs/error.go" `/func Open/`}}
--->func Open(name string) (file *File, err error)</pre>
+{{code "/doc/progs/error.go" `/func Open/`}}
 
 <p>
 The following code uses <code>os.Open</code> to open a file. If an error
 occurs it calls <code>log.Fatal</code> to print the error message and stop.
 </p>
 
-<pre><!--{{code "progs/error.go" `/func openFile/` `/STOP/`}}
--->    f, err := os.Open(&#34;filename.ext&#34;)
-    if err != nil {
-        log.Fatal(err)
-    }
-    // do something with the open *File f</pre>
+{{code "/doc/progs/error.go" `/func openFile/` `/STOP/`}}
 
 <p>
 You can get a lot done in Go knowing just this about the <code>error</code>
@@ -59,15 +50,7 @@ The most commonly-used <code>error</code> implementation is the
 <a href="/pkg/errors/">errors</a> package's unexported <code>errorString</code> type.
 </p>
 
-<pre><!--{{code "progs/error.go" `/errorString/` `/STOP/`}}
--->// errorString is a trivial implementation of error.
-type errorString struct {
-    s string
-}
-
-func (e *errorString) Error() string {
-    return e.s
-}</pre>
+{{code "/doc/progs/error.go" `/errorString/` `/STOP/`}}
 
 <p>
 You can construct one of these values with the <code>errors.New</code>
@@ -75,23 +58,13 @@ function. It takes a string that it converts to an <code>errors.errorString</cod
 and returns as an <code>error</code> value.
 </p>
 
-<pre><!--{{code "progs/error.go" `/New/` `/STOP/`}}
--->// New returns an error that formats as the given text.
-func New(text string) error {
-    return &amp;errorString{text}
-}</pre>
+{{code "/doc/progs/error.go" `/New/` `/STOP/`}}
 
 <p>
 Here's how you might use <code>errors.New</code>:
 </p>
 
-<pre><!--{{code "progs/error.go" `/func Sqrt/` `/STOP/`}}
--->func Sqrt(f float64) (float64, error) {
-    if f &lt; 0 {
-        return 0, errors.New(&#34;math: square root of negative number&#34;)
-    }
-    // implementation
-}</pre>
+{{code "/doc/progs/error.go" `/func Sqrt/` `/STOP/`}}
 
 <p>
 A caller passing a negative argument to <code>Sqrt</code> receives a non-nil
@@ -101,11 +74,7 @@ A caller passing a negative argument to <code>Sqrt</code> receives a non-nil
 <code>Error</code> method, or by just printing it:
 </p>
 
-<pre><!--{{code "progs/error.go" `/func printErr/` `/STOP/`}}
--->    f, err := Sqrt(-1)
-    if err != nil {
-        fmt.Println(err)
-    }</pre>
+{{code "/doc/progs/error.go" `/func printErr/` `/STOP/`}}
 
 <p>
 The <a href="/pkg/fmt/">fmt</a> package formats an <code>error</code> value
@@ -126,10 +95,7 @@ rules and returns it as an <code>error</code> created by
 <code>errors.New</code>.
 </p>
 
-<pre><!--{{code "progs/error.go" `/fmtError/` `/STOP/`}}
--->    if f &lt; 0 {
-        return 0, fmt.Errorf(&#34;math: square root of negative number %g&#34;, f)
-    }</pre>
+{{code "/doc/progs/error.go" `/fmtError/` `/STOP/`}}
 
 <p>
 In many cases <code>fmt.Errorf</code> is good enough, but since
@@ -143,12 +109,7 @@ argument passed to <code>Sqrt</code>. We can enable that by defining a new
 error implementation instead of using <code>errors.errorString</code>:
 </p>
 
-<pre><!--{{code "progs/error.go" `/type NegativeSqrtError/` `/STOP/`}}
--->type NegativeSqrtError float64
-
-func (f NegativeSqrtError) Error() string {
-    return fmt.Sprintf(&#34;math: square root of negative number %g&#34;, float64(f))
-}</pre>
+{{code "/doc/progs/error.go" `/type NegativeSqrtError/` `/STOP/`}}
 
 <p>
 A sophisticated caller can then use a
@@ -164,13 +125,7 @@ As another example, the <a href="/pkg/encoding/json/">json</a> package specifies
 returns when it encounters a syntax error parsing a JSON blob.
 </p>
 
-<pre><!--{{code "progs/error.go" `/type SyntaxError/` `/STOP/`}}
--->type SyntaxError struct {
-    msg    string // description of error
-    Offset int64  // error occurred after reading Offset bytes
-}
-
-func (e *SyntaxError) Error() string { return e.msg }</pre>
+{{code "/doc/progs/error.go" `/type SyntaxError/` `/STOP/`}}
 
 <p>
 The <code>Offset</code> field isn't even shown in the default formatting of the
@@ -178,14 +133,7 @@ error, but callers can use it to add file and line information to their error
 messages:
 </p>
 
-<pre><!--{{code "progs/error.go" `/func decodeError/` `/STOP/`}}
--->    if err := dec.Decode(&amp;val); err != nil {
-        if serr, ok := err.(*json.SyntaxError); ok {
-            line, col := findLine(f, serr.Offset)
-            return fmt.Errorf(&#34;%s:%d:%d: %v&#34;, f.Name(), line, col, err)
-        }
-        return err
-    }</pre>
+{{code "/doc/progs/error.go" `/func decodeError/` `/STOP/`}}
 
 <p>
 (This is a slightly simplified version of some
@@ -217,14 +165,7 @@ web crawler might sleep and retry when it encounters a temporary error and give
 up otherwise.
 </p>
 
-<pre><!--{{code "progs/error.go" `/func netError/` `/STOP/`}}
--->        if nerr, ok := err.(net.Error); ok &amp;&amp; nerr.Temporary() {
-            time.Sleep(1e9)
-            continue
-        }
-        if err != nil {
-            log.Fatal(err)
-        }</pre>
+{{code "/doc/progs/error.go" `/func netError/` `/STOP/`}}
 
 <p>
 <b>Simplifying repetitive error handling</b>
@@ -244,23 +185,7 @@ application with an HTTP handler that retrieves a record from the datastore and
 formats it with a template.
 </p>
 
-<pre><!--{{code "progs/error2.go" `/func init/` `/STOP/`}}
--->func init() {
-    http.HandleFunc(&#34;/view&#34;, viewRecord)
-}
-
-func viewRecord(w http.ResponseWriter, r *http.Request) {
-    c := appengine.NewContext(r)
-    key := datastore.NewKey(c, &#34;Record&#34;, r.FormValue(&#34;id&#34;), 0, nil)
-    record := new(Record)
-    if err := datastore.Get(c, key, record); err != nil {
-        http.Error(w, err.Error(), 500)
-        return
-    }
-    if err := viewTemplate.Execute(w, record); err != nil {
-        http.Error(w, err.Error(), 500)
-    }
-}</pre>
+{{code "/doc/progs/error2.go" `/func init/` `/STOP/`}}
 
 <p>
 This function handles errors returned by the <code>datastore.Get</code>
@@ -276,23 +201,13 @@ To reduce the repetition we can define our own HTTP <code>appHandler</code>
 type that includes an <code>error</code> return value:
 </p>
 
-<pre><!--{{code "progs/error3.go" `/type appHandler/`}}
--->type appHandler func(http.ResponseWriter, *http.Request) error</pre>
+{{code "/doc/progs/error3.go" `/type appHandler/`}}
 
 <p>
 Then we can change our <code>viewRecord</code> function to return errors:
 </p>
 
-<pre><!--{{code "progs/error3.go" `/func viewRecord/` `/STOP/`}}
--->func viewRecord(w http.ResponseWriter, r *http.Request) error {
-    c := appengine.NewContext(r)
-    key := datastore.NewKey(c, &#34;Record&#34;, r.FormValue(&#34;id&#34;), 0, nil)
-    record := new(Record)
-    if err := datastore.Get(c, key, record); err != nil {
-        return err
-    }
-    return viewTemplate.Execute(w, record)
-}</pre>
+{{code "/doc/progs/error3.go" `/func viewRecord/` `/STOP/`}}
 
 <p>
 This is simpler than the original version, but the <a
@@ -302,12 +217,7 @@ To fix this we can implement the <code>http.Handler</code> interface's
 <code>ServeHTTP</code> method on <code>appHandler</code>:
 </p>
 
-<pre><!--{{code "progs/error3.go" `/ServeHTTP/` `/STOP/`}}
--->func (fn appHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
-    if err := fn(w, r); err != nil {
-        http.Error(w, err.Error(), 500)
-    }
-}</pre>
+{{code "/doc/progs/error3.go" `/ServeHTTP/` `/STOP/`}}
 
 <p>
 The <code>ServeHTTP</code> method calls the <code>appHandler</code> function
@@ -323,10 +233,7 @@ Now when registering <code>viewRecord</code> with the http package we use the
 <code>http.HandlerFunc</code>). 
 </p>
 
-<pre><!--{{code "progs/error3.go" `/func init/` `/STOP/`}}
--->func init() {
-    http.Handle(&#34;/view&#34;, appHandler(viewRecord))
-}</pre>
+{{code "/doc/progs/error3.go" `/func init/` `/STOP/`}}
 
 <p>
 With this basic error handling infrastructure in place, we can make it more
@@ -341,24 +248,19 @@ To do this we create an <code>appError</code> struct containing an
 <code>error</code> and some other fields:
 </p>
 
-<pre><!--{{code "progs/error4.go" `/type appError/` `/STOP/`}}
--->type appError struct {
-    Error   error
-    Message string
-    Code    int
-}</pre>
+{{code "/doc/progs/error4.go" `/type appError/` `/STOP/`}}
 
 <p>
 Next we modify the appHandler type to return <code>*appError</code> values:
 </p>
 
-<pre><!--{{code "progs/error4.go" `/type appHandler/`}}
--->type appHandler func(http.ResponseWriter, *http.Request) *appError</pre>
+{{code "/doc/progs/error4.go" `/type appHandler/`}}
 
 <p>
 (It's usually a mistake to pass back the concrete type of an error rather than
-<code>error</code>, for reasons to be discussed in another article, but
-it's the right thing to do here because <code>ServeHTTP</code> is the only
+<code>error</code>,
+for reasons discussed in <a href="/doc/go_faq.html#nil_error">the Go FAQ</a>,
+but it's the right thing to do here because <code>ServeHTTP</code> is the only
 place that sees the value and uses its contents.)
 </p>
 
@@ -369,33 +271,14 @@ status <code>Code</code> and log the full <code>Error</code> to the developer
 console:
 </p>
 
-<pre><!--{{code "progs/error4.go" `/ServeHTTP/` `/STOP/`}}
--->func (fn appHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
-    if e := fn(w, r); e != nil { // e is *appError, not os.Error.
-        c := appengine.NewContext(r)
-        c.Errorf(&#34;%v&#34;, e.Error)
-        http.Error(w, e.Message, e.Code)
-    }
-}</pre>
+{{code "/doc/progs/error4.go" `/ServeHTTP/` `/STOP/`}}
 
 <p>
 Finally, we update <code>viewRecord</code> to the new function signature and
 have it return more context when it encounters an error: 
 </p>
 
-<pre><!--{{code "progs/error4.go" `/func viewRecord/` `/STOP/`}}
--->func viewRecord(w http.ResponseWriter, r *http.Request) *appError {
-    c := appengine.NewContext(r)
-    key := datastore.NewKey(c, &#34;Record&#34;, r.FormValue(&#34;id&#34;), 0, nil)
-    record := new(Record)
-    if err := datastore.Get(c, key, record); err != nil {
-        return &amp;appError{err, &#34;Record not found&#34;, 404}
-    }
-    if err := viewTemplate.Execute(w, record); err != nil {
-        return &amp;appError{err, &#34;Can&#39;t display record&#34;, 500}
-    }
-    return nil
-}</pre>
+{{code "/doc/progs/error4.go" `/func viewRecord/` `/STOP/`}}
 
 <p>
 This version of <code>viewRecord</code> is the same length as the original, but
diff --git a/doc/articles/error_handling.tmpl b/doc/articles/error_handling.tmpl
deleted file mode 100644
index 56b7fb309..000000000
--- a/doc/articles/error_handling.tmpl
+++ /dev/null
@@ -1,314 +0,0 @@
-<!--{
-	"Title": "Error Handling and Go"
-}-->
-{{donotedit}}
-<p>
-If you have written any Go code you have probably encountered the built-in
-<code>error</code> type. Go code uses <code>error</code> values to
-indicate an abnormal state. For example, the <code>os.Open</code> function
-returns a non-nil <code>error</code> value when it fails to open a file.
-</p>
-
-{{code "progs/error.go" `/func Open/`}}
-
-<p>
-The following code uses <code>os.Open</code> to open a file. If an error
-occurs it calls <code>log.Fatal</code> to print the error message and stop.
-</p>
-
-{{code "progs/error.go" `/func openFile/` `/STOP/`}}
-
-<p>
-You can get a lot done in Go knowing just this about the <code>error</code>
-type, but in this article we'll take a closer look at <code>error</code> and
-discuss some good practices for error handling in Go.
-</p>
-
-<p>
-<b>The error type</b>
-</p>
-
-<p>
-The <code>error</code> type is an interface type. An <code>error</code>
-variable represents any value that can describe itself as a string. Here is the
-interface's declaration:
-</p>
-
-<pre>type error interface {
-    Error() string
-}</pre>
-
-<p>
-The <code>error</code> type, as with all built in types, is
-<a href="/doc/go_spec.html#Predeclared_identifiers">predeclared</a> in the
-<a href="/doc/go_spec.html#Blocks">universe block</a>.
-</p>
-
-<p>
-The most commonly-used <code>error</code> implementation is the
-<a href="/pkg/errors/">errors</a> package's unexported <code>errorString</code> type.
-</p>
-
-{{code "progs/error.go" `/errorString/` `/STOP/`}}
-
-<p>
-You can construct one of these values with the <code>errors.New</code>
-function. It takes a string that it converts to an <code>errors.errorString</code>
-and returns as an <code>error</code> value.
-</p>
-
-{{code "progs/error.go" `/New/` `/STOP/`}}
-
-<p>
-Here's how you might use <code>errors.New</code>:
-</p>
-
-{{code "progs/error.go" `/func Sqrt/` `/STOP/`}}
-
-<p>
-A caller passing a negative argument to <code>Sqrt</code> receives a non-nil
-<code>error</code> value (whose concrete representation is an
-<code>errors.errorString</code> value). The caller can access the error string
-("math: square root of...") by calling the <code>error</code>'s
-<code>Error</code> method, or by just printing it:
-</p>
-
-{{code "progs/error.go" `/func printErr/` `/STOP/`}}
-
-<p>
-The <a href="/pkg/fmt/">fmt</a> package formats an <code>error</code> value
-by calling its <code>Error() string</code> method.
-</p>
-
-<p>
-It is the error implementation's responsibility to summarize the context.
-The error returned by <code>os.Open</code> formats as "open /etc/passwd:
-permission denied," not just "permission denied."  The error returned by our
-<code>Sqrt</code> is missing information about the invalid argument.
-</p>
-
-<p>
-To add that information, a useful function is the <code>fmt</code> package's
-<code>Errorf</code>. It formats a string according to <code>Printf</code>'s
-rules and returns it as an <code>error</code> created by
-<code>errors.New</code>.
-</p>
-
-{{code "progs/error.go" `/fmtError/` `/STOP/`}}
-
-<p>
-In many cases <code>fmt.Errorf</code> is good enough, but since
-<code>error</code> is an interface, you can use arbitrary data structures as
-error values, to allow callers to inspect the details of the error.
-</p>
-
-<p>
-For instance, our hypothetical callers might want to recover the invalid
-argument passed to <code>Sqrt</code>. We can enable that by defining a new
-error implementation instead of using <code>errors.errorString</code>:
-</p>
-
-{{code "progs/error.go" `/type NegativeSqrtError/` `/STOP/`}}
-
-<p>
-A sophisticated caller can then use a
-<a href="/doc/go_spec.html#Type_assertions">type assertion</a> to check for a
-<code>NegativeSqrtError</code> and handle it specially, while callers that just
-pass the error to <code>fmt.Println</code> or <code>log.Fatal</code> will see
-no change in behavior.
-</p>
-
-<p>
-As another example, the <a href="/pkg/encoding/json/">json</a> package specifies a
-<code>SyntaxError</code> type that the <code>json.Decode</code> function
-returns when it encounters a syntax error parsing a JSON blob.
-</p>
-
-{{code "progs/error.go" `/type SyntaxError/` `/STOP/`}}
-
-<p>
-The <code>Offset</code> field isn't even shown in the default formatting of the
-error, but callers can use it to add file and line information to their error
-messages:
-</p>
-
-{{code "progs/error.go" `/func decodeError/` `/STOP/`}}
-
-<p>
-(This is a slightly simplified version of some
-<a href="http://camlistore.org/code/?p=camlistore.git;a=blob;f=lib/go/camli/jsonconfig/eval.go#l68">actual code</a>
-from the <a href="http://camlistore.org">Camlistore</a> project.)
-</p>
-
-<p>
-The <code>error</code> interface requires only a <code>Error</code> method;
-specific error implementations might have additional methods. For instance, the
-<a href="/pkg/net/">net</a> package returns errors of type
-<code>error</code>, following the usual convention, but some of the error
-implementations have additional methods defined by the <code>net.Error</code>
-interface:
-</p>
-
-<pre>package net
-
-type Error interface {
-    error
-    Timeout() bool   // Is the error a timeout?
-    Temporary() bool // Is the error temporary?
-}</pre>
-
-<p>
-Client code can test for a <code>net.Error</code> with a type assertion and
-then distinguish transient network errors from permanent ones. For instance, a
-web crawler might sleep and retry when it encounters a temporary error and give
-up otherwise.
-</p>
-
-{{code "progs/error.go" `/func netError/` `/STOP/`}}
-
-<p>
-<b>Simplifying repetitive error handling</b>
-</p>
-
-<p>
-In Go, error handling is important. The language's design and conventions
-encourage you to explicitly check for errors where they occur (as distinct from
-the convention in other languages of throwing exceptions and sometimes catching
-them). In some cases this makes Go code verbose, but fortunately there are some
-techniques you can use to minimize repetitive error handling.
-</p>
-
-<p>
-Consider an <a href="http://code.google.com/appengine/docs/go/">App Engine</a>
-application with an HTTP handler that retrieves a record from the datastore and
-formats it with a template.
-</p>
-
-{{code "progs/error2.go" `/func init/` `/STOP/`}}
-
-<p>
-This function handles errors returned by the <code>datastore.Get</code>
-function and <code>viewTemplate</code>'s <code>Execute</code> method. In both
-cases, it presents a simple error message to the user with the HTTP status code
-500 ("Internal Server Error"). This looks like a manageable amount of code, but
-add some more HTTP handlers and you quickly end up with many copies of
-identical error handling code.
-</p>
-
-<p>
-To reduce the repetition we can define our own HTTP <code>appHandler</code>
-type that includes an <code>error</code> return value:
-</p>
-
-{{code "progs/error3.go" `/type appHandler/`}}
-
-<p>
-Then we can change our <code>viewRecord</code> function to return errors:
-</p>
-
-{{code "progs/error3.go" `/func viewRecord/` `/STOP/`}}
-
-<p>
-This is simpler than the original version, but the <a
-href="/pkg/net/http/">http</a> package doesn't understand functions that return
-<code>error</code>.
-To fix this we can implement the <code>http.Handler</code> interface's
-<code>ServeHTTP</code> method on <code>appHandler</code>:
-</p>
-
-{{code "progs/error3.go" `/ServeHTTP/` `/STOP/`}}
-
-<p>
-The <code>ServeHTTP</code> method calls the <code>appHandler</code> function
-and displays the returned error (if any) to the user.  Notice that the method's
-receiver, <code>fn</code>, is a function. (Go can do that!) The method invokes
-the function by calling the receiver in the expression <code>fn(w, r)</code>.
-</p>
-
-<p>
-Now when registering <code>viewRecord</code> with the http package we use the
-<code>Handle</code> function (instead of <code>HandleFunc</code>) as
-<code>appHandler</code> is an <code>http.Handler</code> (not an
-<code>http.HandlerFunc</code>). 
-</p>
-
-{{code "progs/error3.go" `/func init/` `/STOP/`}}
-
-<p>
-With this basic error handling infrastructure in place, we can make it more
-user friendly. Rather than just displaying the error string, it would be better
-to give the user a simple error message with an appropriate HTTP status code,
-while logging the full error to the App Engine developer console for debugging
-purposes.
-</p>
-
-<p>
-To do this we create an <code>appError</code> struct containing an
-<code>error</code> and some other fields:
-</p>
-
-{{code "progs/error4.go" `/type appError/` `/STOP/`}}
-
-<p>
-Next we modify the appHandler type to return <code>*appError</code> values:
-</p>
-
-{{code "progs/error4.go" `/type appHandler/`}}
-
-<p>
-(It's usually a mistake to pass back the concrete type of an error rather than
-<code>error</code>, for reasons to be discussed in another article, but
-it's the right thing to do here because <code>ServeHTTP</code> is the only
-place that sees the value and uses its contents.)
-</p>
-
-<p>
-And make <code>appHandler</code>'s <code>ServeHTTP</code> method display the
-<code>appError</code>'s <code>Message</code> to the user with the correct HTTP
-status <code>Code</code> and log the full <code>Error</code> to the developer
-console:
-</p>
-
-{{code "progs/error4.go" `/ServeHTTP/` `/STOP/`}}
-
-<p>
-Finally, we update <code>viewRecord</code> to the new function signature and
-have it return more context when it encounters an error: 
-</p>
-
-{{code "progs/error4.go" `/func viewRecord/` `/STOP/`}}
-
-<p>
-This version of <code>viewRecord</code> is the same length as the original, but
-now each of those lines has specific meaning and we are providing a friendlier
-user experience.
-</p>
-
-<p>
-It doesn't end there; we can further improve the error handling in our
-application. Some ideas:
-</p>
-
-<ul>
-<li>give the error handler a pretty HTML template,
-<li>make debugging easier by writing the stack trace to the HTTP response when
-the user is an administrator,
-<li>write a constructor function for <code>appError</code> that stores the
-stack trace for easier debugging, 
-<li>recover from panics inside the <code>appHandler</code>, logging the error
-to the console as "Critical," while telling the user "a serious error
-has occurred." This is a nice touch to avoid exposing the user to inscrutable
-error messages caused by programming errors.
-See the <a href="defer_panic_recover.html">Defer, Panic, and Recover</a>
-article for more details.
-</ul>
-
-<p>
-<b>Conclusion</b>
-</p>
-
-<p>
-Proper error handling is an essential requirement of good software. By
-employing the techniques described in this post you should be able to write
-more reliable and succinct Go code.
-</p>
diff --git a/doc/articles/go_command.html b/doc/articles/go_command.html
new file mode 100644
index 000000000..1e9e70fd8
--- /dev/null
+++ b/doc/articles/go_command.html
@@ -0,0 +1,265 @@
+<!--{
+	"title": "About the go command"
+}-->
+
+<p>The Go distribution includes a command, named
+"<code><a href="/cmd/go/">go</a></code>", that
+automates the downloading, building, installation, and testing of Go packages
+and commands.  This document talks about why we wrote a new command, what it
+is, what it's not, and how to use it.</p>
+
+<h2>Motivation</h2>
+
+<p>You might have seen early Go talks in which Rob Pike jokes that the idea
+for Go arose while waiting for a large Google server to compile.  That
+really was the motivation for Go: to build a language that worked well
+for building the large software that Google writes and runs. It was
+clear from the start that such a language must provide a way to
+express dependencies between code libraries clearly, hence the package
+grouping and the explicit import blocks.  It was also clear from the
+start that you might want arbitrary syntax for describing the code
+being imported; this is why import paths are string literals.</p>
+
+<p>An explicit goal for Go from the beginning was to be able to build Go
+code using only the information found in the source itself, not
+needing to write a makefile or one of the many modern replacements for
+makefiles.  If Go needed a configuration file to explain how to build
+your program, then Go would have failed.</p>
+
+<p>At first, there was no Go compiler, and the initial development
+focused on building one and then building libraries for it. For
+expedience, we postponed the automation of building Go code by using
+make and writing makefiles.  When compiling a single package involved
+multiple invocations of the Go compiler, we even used a program to
+write the makefiles for us.  You can find it if you dig through the
+repository history.</p>
+
+<p>The purpose of the new go command is our return to this ideal, that Go
+programs should compile without configuration or additional effort on
+the part of the developer beyond writing the necessary import
+statements.</p>
+
+<h2>Configuration versus convention</h2>
+
+<p>The way to achieve the simplicity of a configuration-free system is to
+establish conventions. The system works only to the extent that those conventions
+are followed. When we first launched Go, many people published packages that
+had to be installed in certain places, under certain names, using certain build
+tools, in order to be used. That's understandable: that's the way it works in
+most other languages. Over the last few years we consistently reminded people
+about the <code>goinstall</code> command
+(now replaced by <a href="/cmd/go/#Download_and_install_packages_and_dependencies"><code>go get</code></a>)
+and its conventions: first, that the import path is derived in a known way from
+the URL of the source code; second, that that the place to store the sources in
+the local file system is derived in a known way from the import path; third,
+that each directory in a source tree corresponds to a single package; and
+fourth, that the package is built using only information in the source code.
+Today, the vast majority of packages follow these conventions.
+The Go ecosystem is simpler and more powerful as a result.</p>
+
+<p>We received many requests to allow a makefile in a package directory to
+provide just a little extra configuration beyond what's in the source code.
+But that would have introduced new rules. Because we did not accede to such
+requests, we were able to write the go command and eliminate our use of make
+or any other build system.</p>
+
+<p>It is important to understand that the go command is not a general
+build tool. It cannot be configured and it does not attempt to build
+anything but Go packages.  These are important simplifying
+assumptions: they simplify not only the implementation but also, more
+important, the use of the tool itself.</p>
+
+<h2>Go's conventions</h2>
+
+<p>The <code>go</code> command requires that code adheres to a few key,
+well-established conventions.</p>
+
+<p>First, the import path is derived in an known way from the URL of the
+source code.  For Bitbucket, GitHub, Google Code, and Launchpad, the
+root directory of the repository is identified by the repository's
+main URL, without the <code>http://</code> prefix.  Subdirectories are named by
+adding to that path.  For example, the supplemental networking
+libraries for Go are obtained by running</p>
+
+<pre>
+hg clone http://code.google.com/p/go.net
+</pre>
+
+<p>and thus the import path for the root directory of that repository is
+"<code>code.google.com/p/go.net</code>".  The websocket package is stored in a
+subdirectory, so its import path is
+"<code>code.google.com/p/go.net/websocket</code>".</p>
+
+<p>These paths are on the long side, but in exchange we get an
+automatically managed name space for import paths and the ability for
+a tool like the go command to look at an unfamiliar import path and
+deduce where to obtain the source code.</p>
+
+<p>Second, the place to store sources in the local file system is derived
+in a known way from the import path.  Specifically, the first choice
+is <code>$GOPATH/src/&lt;import-path&gt;</code>.  If <code>$GOPATH</code> is
+unset, the go command will fall back to storing source code alongside the
+standard Go packages, in <code>$GOROOT/src/pkg/&lt;import-path&gt;</code>.
+If <code>$GOPATH</code> is set to a list of paths, the go command tries
+<code>&lt;dir&gt;/src/&lt;import-path&gt;</code> for each of the directories in
+that list.</p>
+
+<p>Each of those trees contains, by convention, a top-level directory named
+"<code>bin</code>", for holding compiled executables, and a top-level directory
+named "<code>pkg</code>", for holding compiled packages that can be imported,
+and the "<code>src</code>" directory, for holding package source files.
+Imposing this structure lets us keep each of these directory trees
+self-contained: the compiled form and the sources are always near each
+other.</p>
+
+<p>These naming conventions also let us work in the reverse direction,
+from a directory name to its import path. This mapping is important
+for many of the go command's subcommands, as we'll see below.</p>
+
+<p>Third, each directory in a source tree corresponds to a single
+package. By restricting a directory to a single package, we don't have
+to create hybrid import paths that specify first the directory and
+then the package within that directory.  Also, most file management
+tools and UIs work on  directories as fundamental units.  Tying the
+fundamental Go unit&mdash;the package&mdash;to file system structure means
+that file system tools become Go package tools.  Copying, moving, or
+deleting a package corresponds to copying, moving, or deleting a
+directory.</p>
+
+<p>Fourth, each package is built using only the information present in
+the source files.  This makes it much more likely that the tool will
+be able to adapt to changing build environments and conditions. For
+example, if we allowed extra configuration such as compiler flags or
+command line recipes, then that configuration would need to be updated
+each time the build tools changed; it would also be inherently tied
+to the use of a specific tool chain.</p>
+
+<h2>Getting started with the go command</h2>
+
+<p>Finally, a quick tour of how to use the go command, to supplement
+the information in <a href="/doc/code.html">How to Write Go Code</a>,
+which you might want to read first.  Assuming you want
+to keep your source code separate from the Go distribution source
+tree, the first step is to set <code>$GOPATH</code>, the one piece of global
+configuration that the go command needs.  The <code>$GOPATH</code> can be a
+list of directories, but by far the most common usage should be to set it to a
+single directory.  In particular, you do not need a separate entry in
+<code>$GOPATH</code> for each of your projects.  One <code>$GOPATH</code> can
+support many projects.</p>
+
+<p>Here’s an example.  Let’s say we decide to keep our Go code in the directory
+<code>$HOME/mygo</code>.  We need to create that directory and set
+<code>$GOPATH</code> accordingly.</p>
+
+<pre>
+$ mkdir $HOME/mygo
+$ export GOPATH=$HOME/mygo
+$
+</pre>
+
+<p>Into this directory, we now add some source code.  Suppose we want to use
+the indexing library from the codesearch project along with a left-leaning
+red-black tree.  We can install both with the "<code>go get</code>"
+subcommand:</p>
+
+<pre>
+$ go get code.google.com/p/codesearch/index
+$ go get github.com/petar/GoLLRB/llrb
+$
+</pre>
+
+<p>Both of these projects are now downloaded and installed into our
+<code>$GOPATH</code> directory. The one tree now contains the two directories
+<code>src/code.google.com/p/codesearch/index/</code> and
+<code>src/github.com/petar/GoLLRB/llrb/</code>, along with the compiled
+packages (in <code>pkg/</code>) for those libraries and their dependencies.</p>
+
+<p>Because we used version control systems (Mercurial and Git) to check
+out the sources, the source tree also contains the other files in the
+corresponding repositories, such as related packages. The "<code>go list</code>"
+subcommand lists the import paths corresponding to its arguments, and
+the pattern "<code>./...</code>" means start in the current directory
+("<code>./</code>") and find all packages below that directory
+("<code>...</code>"):</p>
+
+<pre>
+$ go list ./...
+code.google.com/p/codesearch/cmd/cgrep
+code.google.com/p/codesearch/cmd/cindex
+code.google.com/p/codesearch/cmd/csearch
+code.google.com/p/codesearch/index
+code.google.com/p/codesearch/regexp
+code.google.com/p/codesearch/sparse
+github.com/petar/GoLLRB/example
+github.com/petar/GoLLRB/llrb
+$
+</pre>
+
+<p>We can also test those packages:</p>
+
+<pre>
+$ go test ./...
+?       code.google.com/p/codesearch/cmd/cgrep   [no test files]
+?       code.google.com/p/codesearch/cmd/cindex  [no test files]
+?       code.google.com/p/codesearch/cmd/csearch [no test files]
+ok      code.google.com/p/codesearch/index       0.239s
+ok      code.google.com/p/codesearch/regexp      0.021s
+?       code.google.com/p/codesearch/sparse      [no test files]
+?       github.com/petar/GoLLRB/example          [no test files]
+ok      github.com/petar/GoLLRB/llrb             0.231s
+$
+</pre>
+
+<p>If a go subcommand is invoked with no paths listed, it operates on the
+current directory:</p>
+
+<pre>
+$ cd $GOPATH/src/code.google.com/p/codesearch/regexp
+$ go list
+code.google.com/p/codesearch/regexp
+$ go test -v
+=== RUN TestNstateEnc
+--- PASS: TestNstateEnc (0.00 seconds)
+=== RUN TestMatch
+--- PASS: TestMatch (0.01 seconds)
+=== RUN TestGrep
+--- PASS: TestGrep (0.00 seconds)
+PASS
+ok      code.google.com/p/codesearch/regexp     0.021s
+$ go install
+$
+</pre>
+
+<p>That "<code>go install</code>" subcommand installs the latest copy of the
+package into the pkg directory. Because the go command can analyze the
+dependency graph, "<code>go install</code>" also installs any packages that
+this package imports but that are out of date, recursively.</p>
+
+<p>Notice that "<code>go install</code>" was able to determine the name of the
+import path for the package in the current directory, because of the convention
+for directory naming.  It would be a little more convenient if we could pick
+the name of the directory where we kept source code, and we probably wouldn't
+pick such a long name, but that ability would require additional configuration
+and complexity in the tool. Typing an extra directory name or two is a small
+price to pay for the increased simplicity and power.</p>
+
+<p>As the example shows, it’s fine to work with packages from many different
+projects at once within a single <code>$GOPATH</code> root directory.</p>
+
+<h2>Limitations</h2>
+
+<p>As mentioned above, the go command is not a general-purpose build
+tool. In particular, it does not have any facility for generating Go
+source files during a build.  Instead, if you want to use a tool like
+yacc or the protocol buffer compiler, you will need to write a
+makefile (or a configuration file for the build tool of your choice)
+to generate the Go files and then check those generated source files
+into your repository. This is more work for you, the package author,
+but it is significantly less work for your users, who can use
+"<code>go get</code>" without needing to obtain and build
+any additional tools.</p>
+
+<h2>More information</h2>
+
+<p>For more information, read <a href="/doc/code.html">How to Write Go Code</a>
+and see the <a href="/cmd/go/">go command documentation</a>.</p>
diff --git a/doc/articles/gobs_of_data.html b/doc/articles/gobs_of_data.html
new file mode 100644
index 000000000..6b836b2c3
--- /dev/null
+++ b/doc/articles/gobs_of_data.html
@@ -0,0 +1,315 @@
+<!--{
+"Title": "Gobs of data",
+"Template": true
+}-->
+
+<p>
+To transmit a data structure across a network or to store it in a file, it must
+be encoded and then decoded again. There are many encodings available, of
+course: <a href="http://www.json.org/">JSON</a>,
+<a href="http://www.w3.org/XML/">XML</a>, Google's
+<a href="http://code.google.com/p/protobuf">protocol buffers</a>, and more.
+And now there's another, provided by Go's <a href="/pkg/encoding/gob/">gob</a>
+package.
+</p>
+
+<p>
+Why define a new encoding? It's a lot of work and redundant at that. Why not
+just use one of the existing formats? Well, for one thing, we do! Go has
+<a href="/pkg/">packages</a> supporting all the encodings just mentioned (the
+<a href="http://code.google.com/p/goprotobuf">protocol buffer package</a> is in
+a separate repository but it's one of the most frequently downloaded). And for
+many purposes, including communicating with tools and systems written in other
+languages, they're the right choice.
+</p>
+
+<p>
+But for a Go-specific environment, such as communicating between two servers
+written in Go, there's an opportunity to build something much easier to use and
+possibly more efficient.
+</p>
+
+<p>
+Gobs work with the language in a way that an externally-defined,
+language-independent encoding cannot. At the same time, there are lessons to be
+learned from the existing systems.
+</p>
+
+<p>
+<b>Goals</b>
+</p>
+
+<p>
+The gob package was designed with a number of goals in mind.
+</p>
+
+<p>
+First, and most obvious, it had to be very easy to use. First, because Go has
+reflection, there is no need for a separate interface definition language or
+"protocol compiler". The data structure itself is all the package should need
+to figure out how to encode and decode it. On the other hand, this approach
+means that gobs will never work as well with other languages, but that's OK:
+gobs are unashamedly Go-centric.
+</p>
+
+<p>
+Efficiency is also important. Textual representations, exemplified by XML and
+JSON, are too slow to put at the center of an efficient communications network.
+A binary encoding is necessary.
+</p>
+
+<p>
+Gob streams must be self-describing. Each gob stream, read from the beginning,
+contains sufficient information that the entire stream can be parsed by an
+agent that knows nothing a priori about its contents. This property means that
+you will always be able to decode a gob stream stored in a file, even long
+after you've forgotten what data it represents.
+</p>
+
+<p>
+There were also some things to learn from our experiences with Google protocol
+buffers.
+</p>
+
+<p>
+<b>Protocol buffer misfeatures</b>
+</p>
+
+<p>
+Protocol buffers had a major effect on the design of gobs, but have three
+features that were deliberately avoided. (Leaving aside the property that
+protocol buffers aren't self-describing: if you don't know the data definition
+used to encode a protocol buffer, you might not be able to parse it.)
+</p>
+
+<p>
+First, protocol buffers only work on the data type we call a struct in Go. You
+can't encode an integer or array at the top level, only a struct with fields
+inside it. That seems a pointless restriction, at least in Go. If all you want
+to send is an array of integers, why should you have to put it into a
+struct first?
+</p>
+
+<p>
+Next, a protocol buffer definition may specify that fields <code>T.x</code> and
+<code>T.y</code> are required to be present whenever a value of type
+<code>T</code> is encoded or decoded.  Although such required fields may seem
+like a good idea, they are costly to implement because the codec must maintain a
+separate data structure while encoding and decoding, to be able to report when
+required fields are missing.  They're also a maintenance problem. Over time, one
+may want to modify the data definition to remove a required field, but that may
+cause existing clients of the data to crash. It's better not to have them in the
+encoding at all.  (Protocol buffers also have optional fields. But if we don't
+have required fields, all fields are optional and that's that. There will be
+more to say about optional fields a little later.)
+</p>
+
+<p>
+The third protocol buffer misfeature is default values. If a protocol buffer
+omits the value for a "defaulted" field, then the decoded structure behaves as
+if the field were set to that value. This idea works nicely when you have
+getter and setter methods to control access to the field, but is harder to
+handle cleanly when the container is just a plain idiomatic struct. Required
+fields are also tricky to implement: where does one define the default values,
+what types do they have (is text UTF-8? uninterpreted bytes? how many bits in a
+float?) and despite the apparent simplicity, there were a number of
+complications in their design and implementation for protocol buffers. We
+decided to leave them out of gobs and fall back to Go's trivial but effective
+defaulting rule: unless you set something otherwise, it has the "zero value"
+for that type - and it doesn't need to be transmitted.
+</p>
+
+<p>
+So gobs end up looking like a sort of generalized, simplified protocol buffer.
+How do they work?
+</p>
+
+<p>
+<b>Values</b>
+</p>
+
+<p>
+The encoded gob data isn't about <code>int8</code>s and <code>uint16</code>s.
+Instead, somewhat analogous to constants in Go, its integer values are abstract,
+sizeless numbers, either signed or unsigned. When you encode an
+<code>int8</code>, its value is transmitted as an unsized, variable-length
+integer. When you encode an <code>int64</code>, its value is also transmitted as
+an unsized, variable-length integer. (Signed and unsigned are treated
+distinctly, but the same unsized-ness applies to unsigned values too.) If both
+have the value 7, the bits sent on the wire will be identical. When the receiver
+decodes that value, it puts it into the receiver's variable, which may be of
+arbitrary integer type. Thus an encoder may send a 7 that came from an
+<code>int8</code>, but the receiver may store it in an <code>int64</code>. This
+is fine: the value is an integer and as a long as it fits, everything works. (If
+it doesn't fit, an error results.) This decoupling from the size of the variable
+gives some flexibility to the encoding: we can expand the type of the integer
+variable as the software evolves, but still be able to decode old data.
+</p>
+
+<p>
+This flexibility also applies to pointers. Before transmission, all pointers are
+flattened. Values of type <code>int8</code>, <code>*int8</code>,
+<code>**int8</code>, <code>****int8</code>, etc. are all transmitted as an
+integer value, which may then be stored in <code>int</code> of any size, or
+<code>*int</code>, or <code>******int</code>, etc. Again, this allows for
+flexibility.
+</p>
+
+<p>
+Flexibility also happens because, when decoding a struct, only those fields
+that are sent by the encoder are stored in the destination. Given the value
+</p>
+
+{{code "/doc/progs/gobs1.go" `/type T/` `/STOP/`}}
+
+<p>
+the encoding of <code>t</code> sends only the 7 and 8. Because it's zero, the
+value of <code>Y</code> isn't even sent; there's no need to send a zero value.
+</p>
+
+<p>
+The receiver could instead decode the value into this structure:
+</p>
+
+{{code "/doc/progs/gobs1.go" `/type U/` `/STOP/`}}
+
+<p>
+and acquire a value of <code>u</code> with only <code>X</code> set (to the
+address of an <code>int8</code> variable set to 7); the <code>Z</code> field is
+ignored - where would you put it? When decoding structs, fields are matched by
+name and compatible type, and only fields that exist in both are affected. This
+simple approach finesses the "optional field" problem: as the type
+<code>T</code> evolves by adding fields, out of date receivers will still
+function with the part of the type they recognize. Thus gobs provide the
+important result of optional fields - extensibility - without any additional
+mechanism or notation.
+</p>
+
+<p>
+From integers we can build all the other types: bytes, strings, arrays, slices,
+maps, even floats. Floating-point values are represented by their IEEE 754
+floating-point bit pattern, stored as an integer, which works fine as long as
+you know their type, which we always do. By the way, that integer is sent in
+byte-reversed order because common values of floating-point numbers, such as
+small integers, have a lot of zeros at the low end that we can avoid
+transmitting.
+</p>
+
+<p>
+One nice feature of gobs that Go makes possible is that they allow you to define
+your own encoding by having your type satisfy the
+<a href="/pkg/encoding/gob/#GobEncoder">GobEncoder</a> and
+<a href="/pkg/encoding/gob/#GobDecoder">GobDecoder</a> interfaces, in a manner
+analogous to the <a href="/pkg/encoding/json/">JSON</a> package's
+<a href="/pkg/encoding/json/#Marshaler">Marshaler</a> and
+<a href="/pkg/encoding/json/#Unmarshaler">Unmarshaler</a> and also to the
+<a href="/pkg/fmt/#Stringer">Stringer</a> interface from
+<a href="/pkg/fmt/">package fmt</a>. This facility makes it possible to
+represent special features, enforce constraints, or hide secrets when you
+transmit data. See the <a href="/pkg/encoding/gob/">documentation</a> for
+details.
+</p>
+
+<p>
+<b>Types on the wire</b>
+</p>
+
+<p>
+The first time you send a given type, the gob package includes in the data
+stream a description of that type. In fact, what happens is that the encoder is
+used to encode, in the standard gob encoding format, an internal struct that
+describes the type and gives it a unique number. (Basic types, plus the layout
+of the type description structure, are predefined by the software for
+bootstrapping.) After the type is described, it can be referenced by its type
+number.
+</p>
+
+<p>
+Thus when we send our first type <code>T</code>, the gob encoder sends a
+description of <code>T</code> and tags it with a type number, say 127. All
+values, including the first, are then prefixed by that number, so a stream of
+<code>T</code> values looks like:
+</p>
+
+<pre>
+("define type id" 127, definition of type T)(127, T value)(127, T value), ...
+</pre>
+
+<p>
+These type numbers make it possible to describe recursive types and send values
+of those types. Thus gobs can encode types such as trees:
+</p>
+
+{{code "/doc/progs/gobs1.go" `/type Node/` `/STOP/`}}
+
+<p>
+(It's an exercise for the reader to discover how the zero-defaulting rule makes
+this work, even though gobs don't represent pointers.)
+</p>
+
+<p>
+With the type information, a gob stream is fully self-describing except for the
+set of bootstrap types, which is a well-defined starting point.
+</p>
+
+<p>
+<b>Compiling a machine</b>
+</p>
+
+<p>
+The first time you encode a value of a given type, the gob package builds a
+little interpreted machine specific to that data type. It uses reflection on
+the type to construct that machine, but once the machine is built it does not
+depend on reflection. The machine uses package unsafe and some trickery to
+convert the data into the encoded bytes at high speed. It could use reflection
+and avoid unsafe, but would be significantly slower. (A similar high-speed
+approach is taken by the protocol buffer support for Go, whose design was
+influenced by the implementation of gobs.) Subsequent values of the same type
+use the already-compiled machine, so they can be encoded right away.
+</p>
+
+<p>
+Decoding is similar but harder. When you decode a value, the gob package holds
+a byte slice representing a value of a given encoder-defined type to decode,
+plus a Go value into which to decode it. The gob package builds a machine for
+that pair: the gob type sent on the wire crossed with the Go type provided for
+decoding. Once that decoding machine is built, though, it's again a
+reflectionless engine that uses unsafe methods to get maximum speed.
+</p>
+
+<p>
+<b>Use</b>
+</p>
+
+<p>
+There's a lot going on under the hood, but the result is an efficient,
+easy-to-use encoding system for transmitting data. Here's a complete example
+showing differing encoded and decoded types. Note how easy it is to send and
+receive values; all you need to do is present values and variables to the
+<a href="/pkg/encoding/gob/">gob package</a> and it does all the work.
+</p>
+
+{{code "/doc/progs/gobs2.go" `/package main/` `$`}}
+
+<p>
+You can compile and run this example code in the
+<a href="http://play.golang.org/p/_-OJV-rwMq">Go Playground</a>.
+</p>
+
+<p>
+The <a href="/pkg/net/rpc/">rpc package</a> builds on gobs to turn this
+encode/decode automation into transport for method calls across the network.
+That's a subject for another article.
+</p>
+
+<p>
+<b>Details</b>
+</p>
+
+<p>
+The <a href="/pkg/encoding/gob/">gob package documentation</a>, especially the
+file <a href="/src/pkg/encoding/gob/doc.go">doc.go</a>, expands on many of the
+details described here and includes a full worked example showing how the
+encoding represents data. If you are interested in the innards of the gob
+implementation, that's a good place to start.
+</p>
diff --git a/doc/articles/godoc_documenting_go_code.html b/doc/articles/godoc_documenting_go_code.html
new file mode 100644
index 000000000..ca66076ad
--- /dev/null
+++ b/doc/articles/godoc_documenting_go_code.html
@@ -0,0 +1,139 @@
+<!--{
+"Title": "Godoc: documenting Go code",
+"Template": true
+}-->
+
+<p>
+The Go project takes documentation seriously. Documentation is a huge part of
+making software accessible and maintainable. Of course it must be well-written
+and accurate, but it also must be easy to write and to maintain. Ideally, it
+should be coupled to the code itself so the documentation evolves along with the
+code. The easier it is for programmers to produce good documentation, the better
+for everyone.
+</p>
+
+<p>
+To that end, we have developed the <a href="/cmd/godoc/">godoc</a> documentation
+tool. This article describes godoc's approach to documentation, and explains how
+you can use our conventions and tools to write good documentation for your own
+projects.
+</p>
+
+<p>
+Godoc parses Go source code - including comments - and produces documentation as
+HTML or plain text. The end result is documentation tightly coupled with the
+code it documents. For example, through godoc's web interface you can navigate
+from a function's <a href="/pkg/strings/#HasPrefix">documentation</a> to its
+<a href="/src/pkg/strings/strings.go?#L312">implementation</a> with one click.
+</p>
+
+<p>
+Godoc is conceptually related to Python's
+<a href="http://www.python.org/dev/peps/pep-0257/">Docstring</a> and Java's
+<a href="http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html">Javadoc</a>,
+but its design is simpler. The comments read by godoc are not language
+constructs (as with Docstring) nor must they have their own machine-readable
+syntax (as with Javadoc). Godoc comments are just good comments, the sort you
+would want to read even if godoc didn't exist.
+</p>
+
+<p>
+The convention is simple: to document a type, variable, constant, function, or
+even a package, write a regular comment directly preceding its declaration, with
+no intervening blank line. Godoc will then present that comment as text
+alongside the item it documents. For example, this is the documentation for the
+<code>fmt</code> package's <a href="/pkg/fmt/#Fprint"><code>Fprint</code></a>
+function:
+</p>
+
+{{code "/src/pkg/fmt/print.go" `/Fprint formats using the default/` `/func Fprint/`}}
+
+<p>
+Notice this comment is a complete sentence that begins with the name of the
+element it describes. This important convention allows us to generate
+documentation in a variety of formats, from plain text to HTML to UNIX man
+pages, and makes it read better when tools truncate it for brevity, such as when
+they extract the first line or sentence.
+</p>
+
+<p>
+Comments on package declarations should provide general package documentation.
+These comments can be short, like the <a href="/pkg/sort/"><code>sort</code></a>
+package's brief description:
+</p>
+
+{{code "/src/pkg/sort/sort.go" `/Package sort provides/` `/package sort/`}}
+
+<p>
+They can also be detailed like the <a href="/pkg/encoding/gob/">gob package</a>'s
+overview. That package uses another convention for packages
+that need large amounts of introductory documentation: the package comment is
+placed in its own file, <a href="/src/pkg/encoding/gob/doc.go">doc.go</a>, which
+contains only those comments and a package clause.
+</p>
+
+<p>
+When writing package comments of any size, keep in mind that their first
+sentence will appear in godoc's <a href="/pkg/">package list</a>.
+</p>
+
+<p>
+Comments that are not adjacent to a top-level declaration are omitted from
+godoc's output, with one notable exception. Top-level comments that begin with
+the word <code>"BUG(who)”</code> are recognized as known bugs, and included in
+the "Bugs” section of the package documentation. The "who” part should be the
+user name of someone who could provide more information. For example, this is a
+known issue from the <a href="/pkg/bytes/#bugs">bytes package</a>:
+</p>
+
+<pre>
+// BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly.
+</pre>
+
+<p>
+Godoc treats executable commands somewhat differently. Instead of inspecting the
+command source code, it looks for a Go source file belonging to the special
+package "documentation”. The comment on the "package documentation” clause is
+used as the command's documentation. For example, see the
+<a href="/cmd/godoc/">godoc documentation</a> and its corresponding
+<a href="/src/cmd/godoc/doc.go">doc.go</a> file.
+</p>
+
+<p>
+There are a few formatting rules that Godoc uses when converting comments to
+HTML:
+</p>
+
+<ul>
+<li>
+Subsequent lines of text are considered part of the same paragraph; you must
+leave a blank line to separate paragraphs.
+</li>
+<li>
+Pre-formatted text must be indented relative to the surrounding comment text
+(see gob's <a href="/src/pkg/encoding/gob/doc.go">doc.go</a> for an example).
+</li>
+<li>
+URLs will be converted to HTML links; no special markup is necessary.
+</li>
+</ul>
+
+<p>
+Note that none of these rules requires you to do anything out of the ordinary.
+</p>
+
+<p>
+In fact, the best thing about godoc's minimal approach is how easy it is to use.
+As a result, a lot of Go code, including all of the standard library, already
+follows the conventions.
+</p>
+
+<p>
+Your own code can present good documentation just by having comments as
+described above. Any Go packages installed inside <code>$GOROOT/src/pkg</code>
+and any <code>GOPATH</code> work spaces will already be accessible via godoc's
+command-line and HTTP interfaces, and you can specify additional paths for
+indexing via the <code>-path</code> flag or just by running <code>"godoc ."</code>
+in the source directory. See the <a href="/cmd/godoc/">godoc documentation</a>
+for more details.
+</p>
diff --git a/doc/articles/gos_declaration_syntax.html b/doc/articles/gos_declaration_syntax.html
new file mode 100644
index 000000000..455cced1d
--- /dev/null
+++ b/doc/articles/gos_declaration_syntax.html
@@ -0,0 +1,348 @@
+<!--{
+"Title": "Go's Declaration Syntax"
+}-->
+
+<p>
+Newcomers to Go wonder why the declaration syntax is different from the
+tradition established in the C family. In this post we'll compare the
+two approaches and explain why Go's declarations look as they do.
+</p>
+
+<p>
+<b>C syntax</b>
+</p>
+
+<p>
+First, let's talk about C syntax. C took an unusual and clever approach
+to declaration syntax. Instead of describing the types with special
+syntax, one writes an expression involving the item being declared, and
+states what type that expression will have. Thus
+</p>
+
+<pre>
+int x;
+</pre>
+
+<p>
+declares x to be an int: the expression 'x' will have type int. In
+general, to figure out how to write the type of a new variable, write an
+expression involving that variable that evaluates to a basic type, then
+put the basic type on the left and the expression on the right.
+</p>
+
+<p>
+Thus, the declarations
+</p>
+
+<pre>
+int *p;
+int a[3];
+</pre>
+
+<p>
+state that p is a pointer to int because '*p' has type int, and that a
+is an array of ints because a[3] (ignoring the particular index value,
+which is punned to be the size of the array) has type int.
+</p>
+
+<p>
+What about functions? Originally, C's function declarations wrote the
+types of the arguments outside the parens, like this:
+</p>
+
+<pre>
+int main(argc, argv)
+    int argc;
+    char *argv[];
+{ /* ... */ }
+</pre>
+
+<p>
+Again, we see that main is a function because the expression main(argc,
+argv) returns an int. In modern notation we'd write
+</p>
+
+<pre>
+int main(int argc, char *argv[]) { /* ... */ }
+</pre>
+
+<p>
+but the basic structure is the same.
+</p>
+
+<p>
+This is a clever syntactic idea that works well for simple types but can
+get confusing fast. The famous example is declaring a function pointer.
+Follow the rules and you get this:
+</p>
+
+<pre>
+int (*fp)(int a, int b);
+</pre>
+
+<p>
+Here, fp is a pointer to a function because if you write the expression
+(*fp)(a, b) you'll call a function that returns int. What if one of fp's
+arguments is itself a function?
+</p>
+
+<pre>
+int (*fp)(int (*ff)(int x, int y), int b)
+</pre>
+
+<p>
+That's starting to get hard to read.
+</p>
+
+<p>
+Of course, we can leave out the name of the parameters when we declare a
+function, so main can be declared
+</p>
+
+<pre>
+int main(int, char *[])
+</pre>
+
+<p>
+Recall that argv is declared like this,
+</p>
+
+<pre>
+char *argv[]
+</pre>
+
+<p>
+so you drop the name from the <em>middle</em> of its declaration to construct
+its type. It's not obvious, though, that you declare something of type
+char *[] by putting its name in the middle.
+</p>
+
+<p>
+And look what happens to fp's declaration if you don't name the
+parameters:
+</p>
+
+<pre>
+int (*fp)(int (*)(int, int), int)
+</pre>
+
+<p>
+Not only is it not obvious where to put the name inside
+</p>
+
+<pre>
+int (*)(int, int)
+</pre>
+
+<p>
+it's not exactly clear that it's a function pointer declaration at all.
+And what if the return type is a function pointer?
+</p>
+
+<pre>
+int (*(*fp)(int (*)(int, int), int))(int, int)
+</pre>
+
+<p>
+It's hard even to see that this declaration is about fp.
+</p>
+
+<p>
+You can construct more elaborate examples but these should illustrate
+some of the difficulties that C's declaration syntax can introduce.
+</p>
+
+<p>
+There's one more point that needs to be made, though. Because type and
+declaration syntax are the same, it can be difficult to parse
+expressions with types in the middle. This is why, for instance, C casts
+always parenthesize the type, as in
+</p>
+
+<pre>
+(int)M_PI
+</pre>
+
+<p>
+<b>Go syntax</b>
+</p>
+
+<p>
+Languages outside the C family usually use a distinct type syntax in
+declarations. Although it's a separate point, the name usually comes
+first, often followed by a colon. Thus our examples above become
+something like (in a fictional but illustrative language)
+</p>
+
+<pre>
+x: int
+p: pointer to int
+a: array[3] of int
+</pre>
+
+<p>
+These declarations are clear, if verbose - you just read them left to
+right. Go takes its cue from here, but in the interests of brevity it
+drops the colon and removes some of the keywords:
+</p>
+
+<pre>
+x int
+p *int
+a [3]int
+</pre>
+
+<p>
+There is no direct correspondence between the look of [3]int and how to
+use a in an expression. (We'll come back to pointers in the next
+section.) You gain clarity at the cost of a separate syntax.
+</p>
+
+<p>
+Now consider functions. Let's transcribe the declaration for main, even
+though the main function in Go takes no arguments:
+</p>
+
+<pre>
+func main(argc int, argv *[]byte) int
+</pre>
+
+<p>
+Superficially that's not much different from C, but it reads well from
+left to right:
+</p>
+
+<p>
+<em>function main takes an int and a pointer to a slice of bytes and returns an int.</em>
+</p>
+
+<p>
+Drop the parameter names and it's just as clear - they're always first
+so there's no confusion.
+</p>
+
+<pre>
+func main(int, *[]byte) int
+</pre>
+
+<p>
+One value of this left-to-right style is how well it works as the types
+become more complex. Here's a declaration of a function variable
+(analogous to a function pointer in C):
+</p>
+
+<pre>
+f func(func(int,int) int, int) int
+</pre>
+
+<p>
+Or if f returns a function:
+</p>
+
+<pre>
+f func(func(int,int) int, int) func(int, int) int
+</pre>
+
+<p>
+It still reads clearly, from left to right, and it's always obvious
+which name is being declared - the name comes first.
+</p>
+
+<p>
+The distinction between type and expression syntax makes it easy to
+write and invoke closures in Go:
+</p>
+
+<pre>
+sum := func(a, b int) int { return a+b } (3, 4)
+</pre>
+
+<p>
+<b>Pointers</b>
+</p>
+
+<p>
+Pointers are the exception that proves the rule. Notice that in arrays
+and slices, for instance, Go's type syntax puts the brackets on the left
+of the type but the expression syntax puts them on the right of the
+expression:
+</p>
+
+<pre>
+var a []int
+x = a[1]
+</pre>
+
+<p>
+For familiarity, Go's pointers use the * notation from C, but we could
+not bring ourselves to make a similar reversal for pointer types. Thus
+pointers work like this
+</p>
+
+<pre>
+var p *int
+x = *p
+</pre>
+
+<p>
+We couldn't say
+</p>
+
+<pre>
+var p *int
+x = p*
+</pre>
+
+<p>
+because that postfix * would conflate with multiplication. We could have
+used the Pascal ^, for example:
+</p>
+
+<pre>
+var p ^int
+x = p^
+</pre>
+
+<p>
+and perhaps we should have (and chosen another operator for xor),
+because the prefix asterisk on both types and expressions complicates
+things in a number of ways. For instance, although one can write
+</p>
+
+<pre>
+[]int("hi")
+</pre>
+
+<p>
+as a conversion, one must parenthesize the type if it starts with a *:
+</p>
+
+<pre>
+(*int)(nil)
+</pre>
+
+<p>
+Had we been willing to give up * as pointer syntax, those parentheses
+would be unnecessary.
+</p>
+
+<p>
+So Go's pointer syntax is tied to the familiar C form, but those ties
+mean that we cannot break completely from using parentheses to
+disambiguate types and expressions in the grammar.
+</p>
+
+<p>
+Overall, though, we believe Go's type syntax is easier to understand
+than C's, especially when things get complicated.
+</p>
+
+<p>
+<b>Notes</b>
+</p>
+
+<p>
+Go's declarations read left to right. It's been pointed out that C's
+read in a spiral! See <a href="http://c-faq.com/decl/spiral.anderson.html">
+The "Clockwise/Spiral Rule"</a> by David Anderson.
+</p>
diff --git a/doc/articles/image-20.png b/doc/articles/image-20.png
new file mode 100644
index 000000000..063e43064
--- /dev/null
+++ b/doc/articles/image-20.png
diff --git a/doc/articles/image-2a.png b/doc/articles/image-2a.png
new file mode 100644
index 000000000..3f1c0afff
--- /dev/null
+++ b/doc/articles/image-2a.png
diff --git a/doc/articles/image-2b.png b/doc/articles/image-2b.png
new file mode 100644
index 000000000..32b247011
--- /dev/null
+++ b/doc/articles/image-2b.png
diff --git a/doc/articles/image-2c.png b/doc/articles/image-2c.png
new file mode 100644
index 000000000..f9abce5b5
--- /dev/null
+++ b/doc/articles/image-2c.png
diff --git a/doc/articles/image-2d.png b/doc/articles/image-2d.png
new file mode 100644
index 000000000..ed0a9f92c
--- /dev/null
+++ b/doc/articles/image-2d.png
diff --git a/doc/articles/image-2e.png b/doc/articles/image-2e.png
new file mode 100644
index 000000000..483b208e3
--- /dev/null
+++ b/doc/articles/image-2e.png
diff --git a/doc/articles/image-2f.png b/doc/articles/image-2f.png
new file mode 100644
index 000000000..3dce02d5f
--- /dev/null
+++ b/doc/articles/image-2f.png
diff --git a/doc/articles/image_draw.html b/doc/articles/image_draw.html
new file mode 100644
index 000000000..848b65982
--- /dev/null
+++ b/doc/articles/image_draw.html
@@ -0,0 +1,222 @@
+<!--{
+	"Title": "The Go image/draw package",
+	"Template": true
+}-->
+
+<p>
+<a href="http://golang.org/pkg/image/draw/">Package image/draw</a> defines
+only one operation: drawing a source image onto a destination
+image, through an optional mask image. This one operation is
+surprisingly versatile and can perform a number of common image
+manipulation tasks elegantly and efficiently.  
+</p>
+
+<p>
+Composition is performed pixel by pixel in the style of the Plan 9
+graphics library and the X Render extension. The model is based on
+the classic "Compositing Digital Images" paper by Porter and Duff,
+with an additional mask parameter: <code>dst = (src IN mask) OP dst</code>.
+For a fully opaque mask, this reduces to the original Porter-Duff
+formula: <code>dst = src OP dst</code>. In Go, a nil mask image is equivalent
+to an infinitely sized, fully opaque mask image.
+</p>
+
+<p>
+The Porter-Duff paper presented
+<a href="http://www.w3.org/TR/SVGCompositing/examples/compop-porterduff-examples.png">12 different composition operators</a>,
+but with an explicit mask, only 2 of these are needed in practice:
+source-over-destination and source. In Go, these operators are
+represented by the <code>Over</code> and <code>Src</code> constants. The <code>Over</code> operator
+performs the natural layering of a source image over a destination
+image: the change to the destination image is smaller where the
+source (after masking) is more transparent (that is, has lower
+alpha). The <code>Src</code> operator merely copies the source (after masking)
+with no regard for the destination image's original content. For
+fully opaque source and mask images, the two operators produce the
+same output, but the <code>Src</code> operator is usually faster.
+</p>
+
+<p><b>Geometric Alignment</b></p>
+
+<p>  
+Composition requires associating destination pixels with source and
+mask pixels. Obviously, this requires destination, source and mask
+images, and a composition operator, but it also requires specifying
+what rectangle of each image to use. Not every drawing should write
+to the entire destination: when updating an animating image, it is
+more efficient to only draw the parts of the image that have
+changed. Not every drawing should read from the entire source: when
+using a sprite that combines many small images into one large one,
+only a part of the image is needed. Not every drawing should read
+from the entire mask: a mask image that collects a font's glyphs is
+similar to a sprite. Thus, drawing also needs to know three
+rectangles, one for each image. Since each rectangle has the same
+width and height, it suffices to pass a destination rectangle `r`
+and two points <code>sp</code> and <code>mp</code>: the source rectangle is equal to <code>r</code>
+translated so that <code>r.Min</code> in the destination image aligns with 
+<code>sp</code> in the source image, and similarly for <code>mp</code>. The effective
+rectangle is also clipped to each image's bounds in their
+respective co-ordinate space.
+</p>
+
+<p>
+<img src="image-20.png">
+</p>
+
+<p>
+The <a href="http://golang.org/pkg/image/draw/#DrawMask"><code>DrawMask</code></a>
+function takes seven arguments, but an explicit mask and mask-point
+are usually unnecessary, so the
+<a href="http://golang.org/pkg/image/draw/#Draw"><code>Draw</code></a> function takes five:
+</p>
+
+<pre>
+// Draw calls DrawMask with a nil mask.
+func Draw(dst Image, r image.Rectangle, src image.Image, sp image.Point, op Op)
+func DrawMask(dst Image, r image.Rectangle, src image.Image, sp image.Point,
+	mask image.Image, mp image.Point, op Op)
+</pre>
+
+<p>
+The destination image must be mutable, so the image/draw package
+defines a <a href="http://golang.org/pkg/image/draw/#Image"><code>draw.Image</code></a>
+interface which has a <code>Set</code> method.
+</p>
+
+{{code "../src/pkg/image/draw/draw.go" `/type Image/` `/}/`}}
+  
+<p><b>Filling a Rectangle</b></p>
+
+<p>
+To fill a rectangle with a solid color, use an <code>image.Uniform</code>
+source. The <code>ColorImage</code> type re-interprets a <code>Color</code> as a
+practically infinite-sized <code>Image</code> of that color. For those
+familiar with the design of Plan 9's draw library, there is no need
+for an explicit "repeat bit" in Go's slice-based image types; the
+concept is subsumed by <code>Uniform</code>.
+</p>
+
+{{code "/doc/progs/image_draw.go" `/ZERO/` `/STOP/`}}
+
+<p>
+To initialize a new image to all-blue:
+</p>
+
+{{code "/doc/progs/image_draw.go" `/BLUE/` `/STOP/`}}
+
+<p>
+To reset an image to transparent (or black, if the destination
+image's color model cannot represent transparency), use
+<code>image.Transparent</code>, which is an <code>image.Uniform</code>:
+</p>
+
+{{code "/doc/progs/image_draw.go" `/RESET/` `/STOP/`}}
+  
+<p>
+<img src="image-2a.png">
+</p>
+
+ 
+<p><b>Copying an Image</b></p>
+
+<p>
+To copy from a rectangle <code>sr</code> in the source image to a rectangle
+starting at a point <code>dp</code> in the destination, convert the source
+rectangle into the destination image's co-ordinate space:
+</p>
+
+{{code "/doc/progs/image_draw.go" `/RECT/` `/STOP/`}}
+  
+<p>
+Alternatively:
+</p>
+
+{{code "/doc/progs/image_draw.go" `/RECT2/` `/STOP/`}}
+  
+<p>
+To copy the entire source image, use <code>sr = src.Bounds()</code>.
+</p>
+  
+<p>
+<img src="image-2b.png">
+</p>
+ 
+<p><b>Scrolling an Image</b></p>
+
+<p>
+Scrolling an image is just copying an image to itself, with
+different destination and source rectangles. Overlapping
+destination and source images are perfectly valid, just as Go's
+built-in copy function can handle overlapping destination and
+source slices. To scroll an image m by 20 pixels:
+</p>
+
+{{code "/doc/progs/image_draw.go" `/SCROLL/` `/STOP/`}}
+  
+<p><img src="image-2c.png"></p>
+ 
+<p><b>Converting an Image to RGBA</b></p>
+
+<p>
+The result of decoding an image format might not be an
+<code>image.RGBA</code>: decoding a GIF results in an <code>image.Paletted</code>,
+decoding a JPEG results in a <code>ycbcr.YCbCr</code>, and the result of
+decoding a PNG depends on the image data. To convert any image to
+an <code>image.RGBA</code>:
+</p>
+
+{{code "/doc/progs/image_draw.go" `/CONV/` `/STOP/`}}
+  
+<p>
+<img src="image-2d.png">
+</p>
+
+<p><b>Drawing Through a Mask</b></p>
+
+<p>
+To draw an image through a circular mask with center <code>p</code> and radius
+<code>r</code>:
+</p>
+
+{{code "/doc/progs/image_draw.go" `/CIRCLE/` `/STOP/`}}
+{{code "/doc/progs/image_draw.go" `/CIRCLE2/` `/STOP/`}}
+  
+<p>
+<img src="image-2e.png">
+</p>
+
+<p><b>Drawing Font Glyphs</b></p>
+
+<p> 
+To draw a font glyph in blue starting from a point <code>p</code>, draw with
+an <code>image.ColorImage</code> source and an <code>image.Alpha mask</code>. For
+simplicity, we aren't performing any sub-pixel positioning or
+rendering, or correcting for a font's height above a baseline.
+</p>
+
+{{code "/doc/progs/image_draw.go" `/GLYPH/` `/STOP/`}}
+
+<p>
+<img src="image-2f.png">
+</p>
+  
+<p><b>Performance</b></p>
+
+<p>
+The image/draw package implementation demonstrates how to provide
+an image manipulation function that is both general purpose, yet
+efficient for common cases. The <code>DrawMask</code> function takes arguments
+of interface types, but immediately makes type assertions that its
+arguments are of specific struct types, corresponding to common
+operations like drawing one <code>image.RGBA</code> image onto another, or
+drawing an <code>image.Alpha</code> mask (such as a font glyph) onto an
+<code>image.RGBA</code> image. If a type assertion succeeds, that type
+information is used to run a specialized implementation of the
+general algorithm. If the assertions fail, the fallback code path
+uses the generic <code>At</code> and <code>Set</code> methods. The fast-paths are purely
+a performance optimization; the resultant destination image is the
+same either way. In practice, only a small number of special cases
+are necessary to support typical applications.  
+</p>
+
+
diff --git a/doc/articles/json_and_go.html b/doc/articles/json_and_go.html
new file mode 100644
index 000000000..af7776c0a
--- /dev/null
+++ b/doc/articles/json_and_go.html
@@ -0,0 +1,356 @@
+<!--{
+"Title": "JSON and Go",
+"Template": true
+}-->
+
+<p>
+JSON (JavaScript Object Notation) is a simple data interchange format.
+Syntactically it resembles the objects and lists of JavaScript. It is most
+commonly used for communication between web back-ends and JavaScript programs
+running in the browser, but it is used in many other places, too. Its home page,
+<a href="http://json.org">json.org</a>, provides a wonderfully clear and concise
+definition of the standard.
+</p>
+
+<p>
+With the <a href="/pkg/encoding/json/">json package</a> it's a snap to read and
+write JSON data from your Go programs.
+</p>
+
+<p>
+<b>Encoding</b>
+</p>
+
+<p>
+To encode JSON data we use the
+<a href="/pkg/encoding/json/#Marshal"><code>Marshal</code></a> function.
+</p>
+
+<pre>
+func Marshal(v interface{}) ([]byte, error)
+</pre>
+
+<p>
+Given the Go data structure, <code>Message</code>,
+</p>
+
+{{code "/doc/progs/json1.go" `/type Message/` `/STOP/`}}
+
+<p>
+and an instance of <code>Message</code>
+</p>
+
+{{code "/doc/progs/json1.go" `/m :=/`}}
+
+<p>
+we can marshal a JSON-encoded version of m using <code>json.Marshal</code>:
+</p>
+
+{{code "/doc/progs/json1.go" `/b, err :=/`}}
+
+<p>
+If all is well, <code>err</code> will be <code>nil</code> and <code>b</code>
+will be a <code>[]byte</code> containing this JSON data:
+</p>
+
+<pre>
+b == []byte(`{"Name":"Alice","Body":"Hello","Time":1294706395881547000}`)
+</pre>
+
+<p>
+Only data structures that can be represented as valid JSON will be encoded:
+</p>
+
+<ul>
+<li>
+JSON objects only support strings as keys; to encode a Go map type it must be
+of the form <code>map[string]T</code> (where <code>T</code> is any Go type
+supported by the json package).
+</li>
+<li>
+Channel, complex, and function types cannot be encoded.
+</li>
+<li>
+Cyclic data structures are not supported; they will cause <code>Marshal</code>
+to go into an infinite loop.
+</li>
+<li>
+Pointers will be encoded as the values they point to (or 'null' if the pointer
+is <code>nil</code>).
+</li>
+</ul>
+
+<p>
+The json package only accesses the exported fields of struct types (those that
+begin with an uppercase letter). Therefore only the the exported fields of a
+struct will be present in the JSON output.
+</p>
+
+<p>
+<b>Decoding</b>
+</p>
+
+<p>
+To decode JSON data we use the
+<a href="/pkg/encoding/json/#Unmarshal"><code>Unmarshal</code></a> function.
+</p>
+
+<pre>
+func Unmarshal(data []byte, v interface{}) error
+</pre>
+
+<p>
+We must first create a place where the decoded data will be stored
+</p>
+
+{{code "/doc/progs/json1.go" `/var m Message/`}}
+
+<p>
+and call <code>json.Unmarshal</code>, passing it a <code>[]byte</code> of JSON
+data and a pointer to <code>m</code>
+</p>
+
+{{code "/doc/progs/json1.go" `/err := json.Unmarshal/`}}
+
+<p>
+If <code>b</code> contains valid JSON that fits in <code>m</code>, after the
+call <code>err</code> will be <code>nil</code> and the data from <code>b</code>
+will have been stored in the struct <code>m</code>, as if by an assignment
+like:
+</p>
+
+{{code "/doc/progs/json1.go" `/m = Message/` `/STOP/`}}
+
+<p>
+How does <code>Unmarshal</code> identify the fields in which to store the
+decoded data? For a given JSON key <code>"Foo"</code>, <code>Unmarshal</code>
+will look through the destination struct's fields to find (in order of
+preference):
+</p>
+
+<ul>
+<li>
+An exported field with a tag of <code>"Foo"</code> (see the
+<a href="/ref/spec#Struct_types">Go spec</a> for more on struct tags),
+</li>
+<li>
+An exported field named <code>"Foo"</code>, or
+</li>
+<li>
+An exported field named <code>"FOO"</code> or <code>"FoO"</code> or some other
+case-insensitive match of <code>"Foo"</code>.
+</li>
+</ul>
+
+<p>
+What happens when the structure of the JSON data doesn't exactly match the Go
+type?
+</p>
+
+{{code "/doc/progs/json1.go" `/"Food":"Pickle"/` `/STOP/`}}
+
+<p>
+<code>Unmarshal</code> will decode only the fields that it can find in the
+destination type.  In this case, only the Name field of m will be populated,
+and the Food field will be ignored. This behavior is particularly useful when
+you wish to pick only a few specific fields out of a large JSON blob. It also
+means that any unexported fields in the destination struct will be unaffected
+by <code>Unmarshal</code>.
+</p>
+
+<p>
+But what if you don't know the structure of your JSON data beforehand?
+</p>
+
+<p>
+<b>Generic JSON with interface{}</b>
+</p>
+
+<p>
+The <code>interface{}</code> (empty interface) type describes an interface with
+zero methods.  Every Go type implements at least zero methods and therefore
+satisfies the empty interface.
+</p>
+
+<p>
+The empty interface serves as a general container type:
+</p>
+
+{{code "/doc/progs/json2.go" `/var i interface{}/` `/STOP/`}}
+
+<p>
+A type assertion accesses the underlying concrete type:
+</p>
+
+{{code "/doc/progs/json2.go" `/r := i/` `/STOP/`}}
+
+<p>
+Or, if the underlying type is unknown, a type switch determines the type:
+</p>
+
+{{code "/doc/progs/json2.go" `/switch v/` `/STOP/`}}
+
+
+The json package uses <code>map[string]interface{}</code> and
+<code>[]interface{}</code> values to store arbitrary JSON objects and arrays;
+it will happily unmarshal any valid JSON blob into a plain
+<code>interface{}</code> value.  The default concrete Go types are:
+
+<ul>
+<li>
+<code>bool</code> for JSON booleans,
+</li>
+<li>
+<code>float64</code> for JSON numbers,
+</li>
+<li>
+<code>string</code> for JSON strings, and
+</li>
+<li>
+<code>nil</code> for JSON null.
+</li>
+</ul>
+
+<p>
+<b>Decoding arbitrary data</b>
+</p>
+
+<p>
+Consider this JSON data, stored in the variable <code>b</code>:
+</p>
+
+{{code "/doc/progs/json3.go" `/b :=/`}}
+
+<p>
+Without knowing this data's structure, we can decode it into an
+<code>interface{}</code> value with <code>Unmarshal</code>:
+</p>
+
+{{code "/doc/progs/json3.go" `/var f interface/` `/STOP/`}}
+
+<p>
+At this point the Go value in <code>f</code> would be a map whose keys are
+strings and whose values are themselves stored as empty interface values:
+</p>
+
+{{code "/doc/progs/json3.go" `/f = map/` `/STOP/`}}
+
+<p>
+To access this data we can use a type assertion to access <code>f</code>'s
+underlying <code>map[string]interface{}</code>:
+</p>
+
+{{code "/doc/progs/json3.go" `/m := f/`}}
+
+<p>
+We can then iterate through the map with a range statement and use a type switch
+to access its values as their concrete types:
+</p>
+
+{{code "/doc/progs/json3.go" `/for k, v/` `/STOP/`}}
+
+<p>
+In this way you can work with unknown JSON data while still enjoying the
+benefits of type safety.
+</p>
+
+<p>
+<b>Reference Types</b>
+</p>
+
+<p>
+Let's define a Go type to contain the data from the previous example:
+</p>
+
+{{code "/doc/progs/json4.go" `/type FamilyMember/` `/STOP/`}}
+
+{{code "/doc/progs/json4.go" `/var m FamilyMember/` `/STOP/`}}
+
+<p>
+Unmarshaling that data into a <code>FamilyMember</code> value works as
+expected, but if we look closely we can see a remarkable thing has happened.
+With the var statement we allocated a <code>FamilyMember</code> struct, and
+then provided a pointer to that value to <code>Unmarshal</code>, but at that
+time the <code>Parents</code> field was a <code>nil</code> slice value. To
+populate the <code>Parents</code> field, <code>Unmarshal</code> allocated a new
+slice behind the scenes. This is typical of how <code>Unmarshal</code> works
+with the supported reference types (pointers, slices, and maps).
+</p>
+
+<p>
+Consider unmarshaling into this data structure:
+</p>
+
+<pre>
+type Foo struct {
+    Bar *Bar
+}
+</pre>
+
+<p>
+If there were a <code>Bar</code> field in the JSON object,
+<code>Unmarshal</code> would allocate a new <code>Bar</code> and populate it.
+If not, <code>Bar</code> would be left as a <code>nil</code> pointer.
+</p>
+
+<p>
+From this a useful pattern arises: if you have an application that receives a
+few distinct message types, you might define "receiver" structure like
+</p>
+
+<pre>
+type IncomingMessage struct {
+    Cmd *Command
+    Msg *Message
+}
+</pre>
+
+<p>
+and the sending party can populate the <code>Cmd</code> field and/or the
+<code>Msg</code> field of the top-level JSON object, depending on the type of
+message they want to communicate. <code>Unmarshal</code>, when decoding the
+JSON into an <code>IncomingMessage</code> struct, will only allocate the data
+structures present in the JSON data. To know which messages to process, the
+programmer need simply test that either <code>Cmd</code> or <code>Msg</code> is
+not <code>nil</code>.
+</p>
+
+<p>
+<b>Streaming Encoders and Decoders</b>
+</p>
+
+<p>
+The json package provides <code>Decoder</code> and <code>Encoder</code> types
+to support the common operation of reading and writing streams of JSON data.
+The <code>NewDecoder</code> and <code>NewEncoder</code> functions wrap the
+<a href="/pkg/io/#Reader"><code>io.Reader</code></a> and
+<a href="/pkg/io/#Writer"><code>io.Writer</code></a> interface types.
+</p>
+
+<pre>
+func NewDecoder(r io.Reader) *Decoder
+func NewEncoder(w io.Writer) *Encoder
+</pre>
+
+<p>
+Here's an example program that reads a series of JSON objects from standard
+input, removes all but the <code>Name</code> field from each object, and then
+writes the objects to standard output:
+</p>
+
+{{code "/doc/progs/json5.go" `/package main/` `$`}}
+
+<p>
+Due to the ubiquity of Readers and Writers, these <code>Encoder</code> and
+<code>Decoder</code> types can be used in a broad range of scenarios, such as
+reading and writing to HTTP connections, WebSockets, or files.
+</p>
+
+<p>
+<b>References</b>
+</p>
+
+<p>
+For more information see the <a href="/pkg/encoding/json/">json package documentation</a>. For an example usage of
+json see the source files of the <a href="/pkg/net/rpc/jsonrpc/">jsonrpc package</a>.
+</p>
diff --git a/doc/articles/laws_of_reflection.html b/doc/articles/laws_of_reflection.html
index 4df70e0d2..a6175f73c 100644
--- a/doc/articles/laws_of_reflection.html
+++ b/doc/articles/laws_of_reflection.html
@@ -1,11 +1,7 @@
 <!--{
-	"Title": "The Laws of Reflection"
+	"Title": "The Laws of Reflection",
+	"Template": true
 }-->
-<!--
-  DO NOT EDIT: created by
-    tmpltohtml articles/laws_of_reflection.tmpl
--->
-
 
 <p>
 Reflection in computing is the
@@ -36,11 +32,7 @@ exactly one type known and fixed at compile time: <code>int</code>,
 and so on. If we declare
 </p>
 
-<pre><!--{{code "progs/interface.go" `/type MyInt/` `/STOP/`}}
--->type MyInt int
-
-var i int
-var j MyInt</pre>
+{{code "/doc/progs/interface.go" `/type MyInt/` `/STOP/`}}
 
 <p>
 then <code>i</code> has type <code>int</code> and <code>j</code>
@@ -60,16 +52,7 @@ interface's methods. A well-known pair of examples is
 "http://golang.org/pkg/io/">io package</a>:
 </p>
 
-<pre><!--{{code "progs/interface.go" `/// Reader/` `/STOP/`}}
--->// Reader is the interface that wraps the basic Read method.
-type Reader interface {
-    Read(p []byte) (n int, err error)
-}
-
-// Writer is the interface that wraps the basic Write method.
-type Writer interface {
-    Write(p []byte) (n int, err error)
-}</pre>
+{{code "/doc/progs/interface.go" `/// Reader/` `/STOP/`}}
 
 <p>
 Any type that implements a <code>Read</code> (or
@@ -80,12 +63,7 @@ purposes of this discussion, that means that a variable of type
 <code>Read</code> method:
 </p>
 
-<pre><!--{{code "progs/interface.go" `/func readers/` `/STOP/`}}
--->    var r io.Reader
-    r = os.Stdin
-    r = bufio.NewReader(r)
-    r = new(bytes.Buffer)
-    // and so on</pre>
+{{code "/doc/progs/interface.go" `/func readers/` `/STOP/`}}
 
 <p>
 It's important to be clear that whatever concrete value
@@ -138,13 +116,7 @@ that implements the interface and the type describes the full type
 of that item. For instance, after
 </p>
 
-<pre><!--{{code "progs/interface.go" `/func typeAssertions/` `/STOP/`}}
--->    var r io.Reader
-    tty, err := os.OpenFile(&#34;/dev/tty&#34;, os.O_RDWR, 0)
-    if err != nil {
-        return nil, err
-    }
-    r = tty</pre>
+{{code "/doc/progs/interface.go" `/func typeAssertions/` `/STOP/`}}
 
 <p>
 <code>r</code> contains, schematically, the (value, type) pair,
@@ -156,9 +128,7 @@ the type information about that value. That's why we can do things
 like this:
 </p>
 
-<pre><!--{{code "progs/interface.go" `/var w io.Writer/` `/STOP/`}}
--->    var w io.Writer
-    w = r.(io.Writer)</pre>
+{{code "/doc/progs/interface.go" `/var w io.Writer/` `/STOP/`}}
 
 <p>
 The expression in this assignment is a type assertion; what it
@@ -176,9 +146,7 @@ methods.
 Continuing, we can do this:
 </p>
 
-<pre><!--{{code "progs/interface.go" `/var empty interface{}/` `/STOP/`}}
--->    var empty interface{}
-    empty = w</pre>
+{{code "/doc/progs/interface.go" `/var empty interface{}/` `/STOP/`}}
 
 <p>
 and our empty interface value <code>e</code> will again contain
@@ -216,7 +184,7 @@ At the basic level, reflection is just a mechanism to examine the
 type and value pair stored inside an interface variable. To get
 started, there are two types we need to know about in
 <a href="http://golang.org/pkg/reflect">package reflect</a>:
-<a href="http://golang.org/pkg/reflect/#Type">Type</a>and
+<a href="http://golang.org/pkg/reflect/#Type">Type</a> and
 <a href="http://golang.org/pkg/reflect/#Value">Value</a>. Those two types
 give access to the contents of an interface variable, and two
 simple functions, called <code>reflect.TypeOf</code> and
@@ -232,18 +200,7 @@ now.)
 Let's start with <code>TypeOf</code>:
 </p>
 
-<pre><!--{{code "progs/interface2.go" `/package main/` `/STOP main/`}}
--->package main
-
-import (
-    &#34;fmt&#34;
-    &#34;reflect&#34;
-)
-
-func main() {
-    var x float64 = 3.4
-    fmt.Println(&#34;type:&#34;, reflect.TypeOf(x))
-}</pre>
+{{code "/doc/progs/interface2.go" `/package main/` `/STOP main/`}}
 
 <p>
 This program prints
@@ -281,9 +238,7 @@ value (from here on we'll elide the boilerplate and focus just on
 the executable code):
 </p>
 
-<pre><!--{{code "progs/interface2.go" `/var x/` `/STOP/`}}
--->    var x float64 = 3.4
-    fmt.Println(&#34;type:&#34;, reflect.TypeOf(x))</pre>
+{{code "/doc/progs/interface2.go" `/START f9/` `/STOP/`}}
 
 <p>
 prints
@@ -307,12 +262,7 @@ on. Also methods on <code>Value</code> with names like
 <code>int64</code> and <code>float64</code>) stored inside:
 </p>
 
-<pre><!--{{code "progs/interface2.go" `/START f1/` `/STOP/`}}
--->    var x float64 = 3.4
-    v := reflect.ValueOf(x)
-    fmt.Println(&#34;type:&#34;, v.Type())
-    fmt.Println(&#34;kind is float64:&#34;, v.Kind() == reflect.Float64)
-    fmt.Println(&#34;value:&#34;, v.Float())</pre>
+{{code "/doc/progs/interface2.go" `/START f1/` `/STOP/`}}
 
 <p>
 prints
@@ -342,12 +292,7 @@ instance. That is, the <code>Int</code> method of
 necessary to convert to the actual type involved:
 </p>
 
-<pre><!--{{code "progs/interface2.go" `/START f2/` `/STOP/`}}
--->    var x uint8 = &#39;x&#39;
-    v := reflect.ValueOf(x)
-    fmt.Println(&#34;type:&#34;, v.Type())                            // uint8.
-    fmt.Println(&#34;kind is uint8: &#34;, v.Kind() == reflect.Uint8) // true.
-    x = uint8(v.Uint())                                       // v.Uint returns a uint64.</pre>
+{{code "/doc/progs/interface2.go" `/START f2/` `/STOP/`}}
 
 <p>
 The second property is that the <code>Kind</code> of a reflection
@@ -356,10 +301,7 @@ reflection object contains a value of a user-defined integer type,
 as in
 </p>
 
-<pre><!--{{code "progs/interface2.go" `/START f3/` `/START/`}}
--->    type MyInt int
-    var x MyInt = 7
-    v := reflect.ValueOf(x)</pre>
+{{code "/doc/progs/interface2.go" `/START f3/` `/STOP/`}}
 
 <p>
 the <code>Kind</code> of <code>v</code> is still
@@ -395,9 +337,7 @@ func (v Value) Interface() interface{}
 As a consequence we can say
 </p>
 
-<pre><!--{{code "progs/interface2.go" `/START f3b/` `/START/`}}
--->    y := v.Interface().(float64) // y will have type float64.
-    fmt.Println(y)</pre>
+{{code "/doc/progs/interface2.go" `/START f3b/` `/STOP/`}}
 
 <p>
 to print the <code>float64</code> value represented by the
@@ -415,8 +355,7 @@ the <code>Interface</code> method to the formatted print
 routine:
 </p>
 
-<pre><!--{{code "progs/interface2.go" `/START f3c/` `/START/`}}
--->    fmt.Println(v.Interface())</pre>
+{{code "/doc/progs/interface2.go" `/START f3c/` `/STOP/`}}
 
 <p>
 (Why not <code>fmt.Println(v)</code>? Because <code>v</code> is a
@@ -425,8 +364,7 @@ Since our value is a <code>float64</code>, we can even use a
 floating-point format if we want:
 </p>
 
-<pre><!--{{code "progs/interface2.go" `/START f3d/` `/STOP/`}}
--->    fmt.Printf(&#34;value is %7.1e\n&#34;, v.Interface())</pre>
+{{code "/doc/progs/interface2.go" `/START f3d/` `/STOP/`}}
 
 <p>
 and get in this case
@@ -467,10 +405,7 @@ enough to understand if we start from first principles.
 Here is some code that does not work, but is worth studying.
 </p>
 
-<pre><!--{{code "progs/interface2.go" `/START f4/` `/STOP/`}}
--->    var x float64 = 3.4
-    v := reflect.ValueOf(x)
-    v.SetFloat(7.1) // Error: will panic.</pre>
+{{code "/doc/progs/interface2.go" `/START f4/` `/STOP/`}}
 
 <p>
 If you run this code, it will panic with the cryptic message
@@ -492,10 +427,7 @@ The <code>CanSet</code> method of <code>Value</code> reports the
 settability of a <code>Value</code>; in our case,
 </p>
 
-<pre><!--{{code "progs/interface2.go" `/START f5/` `/STOP/`}}
--->    var x float64 = 3.4
-    v := reflect.ValueOf(x)
-    fmt.Println(&#34;settability of v:&#34;, v.CanSet())</pre>
+{{code "/doc/progs/interface2.go" `/START f5/` `/STOP/`}}
 
 <p>
 prints
@@ -518,9 +450,7 @@ determined by whether the reflection object holds the original
 item. When we say
 </p>
 
-<pre><!--{{code "progs/interface2.go" `/START f6/` `/START/`}}
--->    var x float64 = 3.4
-    v := reflect.ValueOf(x)</pre>
+{{code "/doc/progs/interface2.go" `/START f6/` `/STOP/`}}
 
 <p>
 we pass a <em>copy</em> of <code>x</code> to
@@ -530,8 +460,7 @@ argument to <code>reflect.ValueOf</code> is a <em>copy</em> of
 statement
 </p>
 
-<pre><!--{{code "progs/interface2.go" `/START f6b/` `/STOP/`}}
--->    v.SetFloat(7.1)</pre>
+{{code "/doc/progs/interface2.go" `/START f6b/` `/STOP/`}}
 
 <p>
 were allowed to succeed, it would not update <code>x</code>, even
@@ -577,11 +506,7 @@ and then create a reflection value that points to it, called
 <code>p</code>.
 </p>
 
-<pre><!--{{code "progs/interface2.go" `/START f7/` `/START/`}}
--->    var x float64 = 3.4
-    p := reflect.ValueOf(&amp;x) // Note: take the address of x.
-    fmt.Println(&#34;type of p:&#34;, p.Type())
-    fmt.Println(&#34;settability of p:&#34;, p.CanSet())</pre>
+{{code "/doc/progs/interface2.go" `/START f7/` `/STOP/`}}
 
 <p>
 The output so far is
@@ -601,9 +526,7 @@ and save the result in a reflection <code>Value</code> called
 <code>v</code>:
 </p>
 
-<pre><!--{{code "progs/interface2.go" `/START f7b/` `/START/`}}
--->    v := p.Elem()
-    fmt.Println(&#34;settability of v:&#34;, v.CanSet())</pre>
+{{code "/doc/progs/interface2.go" `/START f7b/` `/STOP/`}}
 
 <p>
 Now <code>v</code> is a settable reflection object, as the output
@@ -620,10 +543,7 @@ and since it represents <code>x</code>, we are finally able to use
 <code>x</code>:
 </p>
 
-<pre><!--{{code "progs/interface2.go" `/START f7c/` `/STOP/`}}
--->    v.SetFloat(7.1)
-    fmt.Println(v.Interface())
-    fmt.Println(x)</pre>
+{{code "/doc/progs/interface2.go" `/START f7c/` `/STOP/`}}
 
 <p>
 The output, as expected, is
@@ -664,22 +584,7 @@ but the fields themselves are regular <code>reflect.Value</code>
 objects.
 </p>
 
-<pre><!--{{code "progs/interface2.go" `/START f8/` `/STOP/`}}
--->    type T struct {
-        A int
-        B string
-    }
-    t := T{23, &#34;skidoo&#34;}
-    s := reflect.ValueOf(&amp;t).Elem()
-    typeOfT := s.Type()
-    for i := 0; i &lt; s.NumField(); i++ {
-        f := s.Field(i)
-        fmt.Printf(&#34;%d: %s %s = %v\n&#34;, i,
-            typeOfT.Field(i).Name, f.Type(), f.Interface())
-    }
-    s.Field(0).SetInt(77)
-    s.Field(1).SetString(&#34;Sunset Strip&#34;)
-    fmt.Println(&#34;t is now&#34;, t)</pre>
+{{code "/doc/progs/interface2.go" `/START f8/` `/STOP/`}}
 
 <p>
 The output of this program is
@@ -702,10 +607,7 @@ Because <code>s</code> contains a settable reflection object, we
 can modify the fields of the structure.
 </p>
 
-<pre><!--{{code "progs/interface2.go" `/START f8b/` `/STOP/`}}
--->    s.Field(0).SetInt(77)
-    s.Field(1).SetString(&#34;Sunset Strip&#34;)
-    fmt.Println(&#34;t is now&#34;, t)</pre>
+{{code "/doc/progs/interface2.go" `/START f8b/` `/STOP/`}}
 
 <p>
 And here's the result:
@@ -749,4 +651,4 @@ sending and receiving on channels, allocating memory, using slices
 and maps, calling methods and functions &mdash; but this post is
 long enough. We'll cover some of those topics in a later
 article.
-</p>
\ No newline at end of file
+</p>
diff --git a/doc/articles/laws_of_reflection.tmpl b/doc/articles/laws_of_reflection.tmpl
deleted file mode 100644
index 7db5d6d3b..000000000
--- a/doc/articles/laws_of_reflection.tmpl
+++ /dev/null
@@ -1,654 +0,0 @@
-<!--{
-	"Title": "The Laws of Reflection"
-}-->
-{{donotedit}}
-
-<p>
-Reflection in computing is the
-ability of a program to examine its own structure, particularly
-through types; it's a form of metaprogramming. It's also a great
-source of confusion.
-</p>
-
-<p>
-In this article we attempt to clarify things by explaining how
-reflection works in Go. Each language's reflection model is
-different (and many languages don't support it at all), but
-this article is about Go, so for the rest of this article the word
-"reflection" should be taken to mean "reflection in Go".
-</p>
-
-<p><b>Types and interfaces</b></p>
-
-<p>
-Because reflection builds on the type system, let's start with a
-refresher about types in Go.
-</p>
-
-<p>
-Go is statically typed. Every variable has a static type, that is,
-exactly one type known and fixed at compile time: <code>int</code>,
-<code>float32</code>, <code>*MyType</code>, <code>[]byte</code>,
-and so on. If we declare
-</p>
-
-{{code "progs/interface.go" `/type MyInt/` `/STOP/`}}
-
-<p>
-then <code>i</code> has type <code>int</code> and <code>j</code>
-has type <code>MyInt</code>. The variables <code>i</code> and
-<code>j</code> have distinct static types and, although they have
-the same underlying type, they cannot be assigned to one another
-without a conversion.
-</p>
-
-<p>
-One important category of type is interface types, which represent
-fixed sets of methods. An interface variable can store any concrete
-(non-interface) value as long as that value implements the
-interface's methods. A well-known pair of examples is
-<code>io.Reader</code> and <code>io.Writer</code>, the types
-<code>Reader</code> and <code>Writer</code> from the <a href=
-"http://golang.org/pkg/io/">io package</a>:
-</p>
-
-{{code "progs/interface.go" `/// Reader/` `/STOP/`}}
-
-<p>
-Any type that implements a <code>Read</code> (or
-<code>Write</code>) method with this signature is said to implement
-<code>io.Reader</code> (or <code>io.Writer</code>). For the
-purposes of this discussion, that means that a variable of type
-<code>io.Reader</code> can hold any value whose type has a
-<code>Read</code> method:
-</p>
-
-{{code "progs/interface.go" `/func readers/` `/STOP/`}}
-
-<p>
-It's important to be clear that whatever concrete value
-<code>r</code> may hold, <code>r</code>'s type is always
-<code>io.Reader</code>: Go is statically typed and the static type
-of <code>r</code> is <code>io.Reader</code>.</p>
-
-<p>
-An extremely important example of an interface type is the empty
-interface:
-</p>
-
-<pre>
-interface{}
-</pre>
-
-<p>
-It represents the empty set of methods and is satisfied by any
-value at all, since any value has zero or more methods.
-</p>
-
-<p>
-Some people say that Go's interfaces are dynamically typed, but
-that is misleading. They are statically typed: a variable of
-interface type always has the same static type, and even though at
-run time the value stored in the interface variable may change
-type, that value will always satisfy the interface.
-</p>
-
-<p>
-We need to be precise about all this because reflection and
-interfaces are closely related.
-</p>
-
-<p><b>The representation of an interface</b></p>
-
-<p>
-Russ Cox has written a <a href=
-"http://research.swtch.com/2009/12/go-data-structures-interfaces.html">
-detailed blog post</a> about the representation of interface values
-in Go. It's not necessary to repeat the full story here, but a
-simplified summary is in order.
-</p>
-
-<p>
-A variable of interface type stores a pair: the concrete value
-assigned to the variable, and that value's type descriptor.
-To be more precise, the value is the underlying concrete data item
-that implements the interface and the type describes the full type
-of that item. For instance, after
-</p>
-
-{{code "progs/interface.go" `/func typeAssertions/` `/STOP/`}}
-
-<p>
-<code>r</code> contains, schematically, the (value, type) pair,
-(<code>tty</code>, <code>*os.File</code>). Notice that the type
-<code>*os.File</code> implements methods other than
-<code>Read</code>; even though the interface value provides access
-only to the <code>Read</code> method, the value inside carries all
-the type information about that value. That's why we can do things
-like this:
-</p>
-
-{{code "progs/interface.go" `/var w io.Writer/` `/STOP/`}}
-
-<p>
-The expression in this assignment is a type assertion; what it
-asserts is that the item inside <code>r</code> also implements
-<code>io.Writer</code>, and so we can assign it to <code>w</code>.
-After the assignment, <code>w</code> will contain the pair
-(<code>tty</code>, <code>*os.File</code>). That's the same pair as
-was held in <code>r</code>. The static type of the interface
-determines what methods may be invoked with an interface variable,
-even though the concrete value inside may have a larger set of
-methods.
-</p>
-
-<p>
-Continuing, we can do this:
-</p>
-
-{{code "progs/interface.go" `/var empty interface{}/` `/STOP/`}}
-
-<p>
-and our empty interface value <code>e</code> will again contain
-that same pair, (<code>tty</code>, <code>*os.File</code>). That's
-handy: an empty interface can hold any value and contains all the
-information we could ever need about that value.
-</p>
-
-<p>
-(We don't need a type assertion here because it's known statically
-that <code>w</code> satisfies the empty interface. In the example
-where we moved a value from a <code>Reader</code> to a
-<code>Writer</code>, we needed to be explicit and use a type
-assertion because <code>Writer</code>'s methods are not a
-subset of <code>Reader</code>'s.)
-</p>
-
-<p>
-One important detail is that the pair inside an interface always
-has the form (value, concrete type) and cannot have the form
-(value, interface type). Interfaces do not hold interface
-values.
-</p>
-
-<p>
-Now we're ready to reflect.
-</p>
-
-<p><b>The first law of reflection</b></p>
-
-<p><b>1. Reflection goes from interface value to reflection object.</b></p>
-
-<p>
-At the basic level, reflection is just a mechanism to examine the
-type and value pair stored inside an interface variable. To get
-started, there are two types we need to know about in
-<a href="http://golang.org/pkg/reflect">package reflect</a>:
-<a href="http://golang.org/pkg/reflect/#Type">Type</a>and
-<a href="http://golang.org/pkg/reflect/#Value">Value</a>. Those two types
-give access to the contents of an interface variable, and two
-simple functions, called <code>reflect.TypeOf</code> and
-<code>reflect.ValueOf</code>, retrieve <code>reflect.Type</code>
-and <code>reflect.Value</code> pieces out of an interface value.
-(Also, from the <code>reflect.Value</code> it's easy to get
-to the <code>reflect.Type</code>, but let's keep the
-<code>Value</code> and <code>Type</code> concepts separate for
-now.)
-</p>
-
-<p>
-Let's start with <code>TypeOf</code>:
-</p>
-
-{{code "progs/interface2.go" `/package main/` `/STOP main/`}}
-
-<p>
-This program prints
-</p>
-
-<pre>
-type: float64
-</pre>
-
-<p>
-You might be wondering where the interface is here, since the
-program looks like it's passing the <code>float64</code>
-variable <code>x</code>, not an interface value, to
-<code>reflect.TypeOf</code>. But it's there; as <a href=
-"http://golang.org/pkg/reflect/#Type.TypeOf">godoc reports</a>, the
-signature of <code>reflect.TypeOf</code> includes an empty
-interface:
-</p>
-
-<pre>
-// TypeOf returns the reflection Type of the value in the interface{}.
-func TypeOf(i interface{}) Type
-</pre>
-
-<p>
-When we call <code>reflect.TypeOf(x)</code>, <code>x</code> is
-first stored in an empty interface, which is then passed as the
-argument; <code>reflect.TypeOf</code> unpacks that empty interface
-to recover the type information.
-</p>
-
-<p>
-The <code>reflect.ValueOf</code> function, of course, recovers the
-value (from here on we'll elide the boilerplate and focus just on
-the executable code):
-</p>
-
-{{code "progs/interface2.go" `/var x/` `/STOP/`}}
-
-<p>
-prints
-</p>
-
-<pre>
-value: &lt;float64 Value&gt;
-</pre>
-
-<p>
-Both <code>reflect.Type</code> and <code>reflect.Value</code> have
-lots of methods to let us examine and manipulate them. One
-important example is that <code>Value</code> has a
-<code>Type</code> method that returns the <code>Type</code> of a
-<code>reflect.Value</code>. Another is that both <code>Type</code>
-and <code>Value</code> have a <code>Kind</code> method that returns
-a constant indicating what sort of item is stored:
-<code>Uint</code>, <code>Float64</code>, <code>Slice</code>, and so
-on. Also methods on <code>Value</code> with names like
-<code>Int</code> and <code>Float</code> let us grab values (as
-<code>int64</code> and <code>float64</code>) stored inside:
-</p>
-
-{{code "progs/interface2.go" `/START f1/` `/STOP/`}}
-
-<p>
-prints
-</p>
-
-<pre>
-type: float64
-kind is float64: true
-value: 3.4
-</pre>
-
-<p>
-There are also methods like <code>SetInt</code> and
-<code>SetFloat</code> but to use them we need to understand
-settability, the subject of the third law of reflection, discussed
-below.
-</p>
-
-<p>
-The reflection library has a couple of properties worth singling
-out. First, to keep the API simple, the "getter" and "setter"
-methods of <code>Value</code> operate on the largest type that can
-hold the value: <code>int64</code> for all the signed integers, for
-instance. That is, the <code>Int</code> method of
-<code>Value</code> returns an <code>int64</code> and the
-<code>SetInt</code> value takes an <code>int64</code>; it may be
-necessary to convert to the actual type involved:
-</p>
-
-{{code "progs/interface2.go" `/START f2/` `/STOP/`}}
-
-<p>
-The second property is that the <code>Kind</code> of a reflection
-object describes the underlying type, not the static type. If a
-reflection object contains a value of a user-defined integer type,
-as in
-</p>
-
-{{code "progs/interface2.go" `/START f3/` `/START/`}}
-
-<p>
-the <code>Kind</code> of <code>v</code> is still
-<code>reflect.Int</code>, even though the static type of
-<code>x</code> is <code>MyInt</code>, not <code>int</code>. In
-other words, the <code>Kind</code> cannot discriminate an int from
-a <code>MyInt</code> even though the <code>Type</code> can.
-</p>
-
-<p><b>The second law of reflection</b></p>
-
-<p><b>2. Reflection goes from reflection object to interface
-value.</b></p>
-
-<p>
-Like physical reflection, reflection in Go generates its own
-inverse.
-</p>
-
-<p>
-Given a <code>reflect.Value</code> we can recover an interface
-value using the <code>Interface</code> method; in effect the method
-packs the type and value information back into an interface
-representation and returns the result:
-</p>
-
-<pre>
-// Interface returns v's value as an interface{}.
-func (v Value) Interface() interface{}
-</pre>
-
-<p>
-As a consequence we can say
-</p>
-
-{{code "progs/interface2.go" `/START f3b/` `/START/`}}
-
-<p>
-to print the <code>float64</code> value represented by the
-reflection object <code>v</code>.
-</p>
-
-<p>
-We can do even better, though. The arguments to
-<code>fmt.Println</code>, <code>fmt.Printf</code> and so on are all
-passed as empty interface values, which are then unpacked by the
-<code>fmt</code> package internally just as we have been doing in
-the previous examples. Therefore all it takes to print the contents
-of a <code>reflect.Value</code> correctly is to pass the result of
-the <code>Interface</code> method to the formatted print
-routine:
-</p>
-
-{{code "progs/interface2.go" `/START f3c/` `/START/`}}
-
-<p>
-(Why not <code>fmt.Println(v)</code>? Because <code>v</code> is a
-<code>reflect.Value</code>; we want the concrete value it holds.)
-Since our value is a <code>float64</code>, we can even use a
-floating-point format if we want:
-</p>
-
-{{code "progs/interface2.go" `/START f3d/` `/STOP/`}}
-
-<p>
-and get in this case
-</p>
-
-<pre>
-3.4e+00
-</pre>
-
-<p>
-Again, there's no need to type-assert the result of
-<code>v.Interface()</code> to <code>float64</code>; the empty
-interface value has the concrete value's type information inside
-and <code>Printf</code> will recover it.
-</p>
-
-<p>
-In short, the <code>Interface</code> method is the inverse of the
-<code>ValueOf</code> function, except that its result is always of
-static type <code>interface{}</code>.
-</p>
-
-<p>
-Reiterating: Reflection goes from interface values to reflection
-objects and back again.
-</p>
-
-<p><b>The third law of reflection</b></p>
-
-<p><b>3. To modify a reflection object, the value must be settable.</b></p>
-
-<p>
-The third law is the most subtle and confusing, but it's easy
-enough to understand if we start from first principles.
-</p>
-
-<p>
-Here is some code that does not work, but is worth studying.
-</p>
-
-{{code "progs/interface2.go" `/START f4/` `/STOP/`}}
-
-<p>
-If you run this code, it will panic with the cryptic message
-</p>
-
-<pre>
-panic: reflect.Value.SetFloat using unaddressable value
-</pre>
-
-<p>
-The problem is not that the value <code>7.1</code> is not
-addressable; it's that <code>v</code> is not settable. Settability
-is a property of a reflection <code>Value</code>, and not all
-reflection <code>Values</code> have it.
-</p>
-
-<p>
-The <code>CanSet</code> method of <code>Value</code> reports the
-settability of a <code>Value</code>; in our case,
-</p>
-
-{{code "progs/interface2.go" `/START f5/` `/STOP/`}}
-
-<p>
-prints
-</p>
-
-<pre>
-settability of v: false
-</pre>
-
-<p>
-It is an error to call a <code>Set</code> method on an non-settable
-<code>Value</code>. But what is settability?
-</p>
-
-<p>
-Settability is a bit like addressability, but stricter. It's the
-property that a reflection object can modify the actual storage
-that was used to create the reflection object. Settability is
-determined by whether the reflection object holds the original
-item. When we say
-</p>
-
-{{code "progs/interface2.go" `/START f6/` `/START/`}}
-
-<p>
-we pass a <em>copy</em> of <code>x</code> to
-<code>reflect.ValueOf</code>, so the interface value created as the
-argument to <code>reflect.ValueOf</code> is a <em>copy</em> of
-<code>x</code>, not <code>x</code> itself. Thus, if the
-statement
-</p>
-
-{{code "progs/interface2.go" `/START f6b/` `/STOP/`}}
-
-<p>
-were allowed to succeed, it would not update <code>x</code>, even
-though <code>v</code> looks like it was created from
-<code>x</code>. Instead, it would update the copy of <code>x</code>
-stored inside the reflection value and <code>x</code> itself would
-be unaffected. That would be confusing and useless, so it is
-illegal, and settability is the property used to avoid this
-issue.
-</p>
-
-<p>
-If this seems bizarre, it's not. It's actually a familiar situation
-in unusual garb. Think of passing <code>x</code> to a
-function:
-</p>
-
-<pre>
-f(x)
-</pre>
-
-<p>
-We would not expect <code>f</code> to be able to modify
-<code>x</code> because we passed a copy of <code>x</code>'s value,
-not <code>x</code> itself. If we want <code>f</code> to modify
-<code>x</code> directly we must pass our function the address of
-<code>x</code> (that is, a pointer to <code>x</code>):</p>
-
-<p>
-<code>f(&amp;x)</code>
-</p>
-
-<p>
-This is straightforward and familiar, and reflection works the same
-way. If we want to modify <code>x</code> by reflection, we must
-give the reflection library a pointer to the value we want to
-modify.
-</p>
-
-<p>
-Let's do that. First we initialize <code>x</code> as usual
-and then create a reflection value that points to it, called
-<code>p</code>.
-</p>
-
-{{code "progs/interface2.go" `/START f7/` `/START/`}}
-
-<p>
-The output so far is
-</p>
-
-<pre>
-type of p: *float64
-settability of p: false
-</pre>
-
-<p>
-The reflection object <code>p</code> isn't settable, but it's not
-<code>p</code> we want to set, it's (in effect) <code>*p</code>. To
-get to what <code>p</code> points to, we call the <code>Elem</code>
-method of <code>Value</code>, which indirects through the pointer,
-and save the result in a reflection <code>Value</code> called
-<code>v</code>:
-</p>
-
-{{code "progs/interface2.go" `/START f7b/` `/START/`}}
-
-<p>
-Now <code>v</code> is a settable reflection object, as the output
-demonstrates,
-</p>
-
-<pre>
-settability of v: true
-</pre>
-
-<p>
-and since it represents <code>x</code>, we are finally able to use
-<code>v.SetFloat</code> to modify the value of
-<code>x</code>:
-</p>
-
-{{code "progs/interface2.go" `/START f7c/` `/STOP/`}}
-
-<p>
-The output, as expected, is
-</p>
-
-<pre>
-7.1
-7.1
-</pre>
-
-<p>
-Reflection can be hard to understand but it's doing exactly what
-the language does, albeit through reflection <code>Types</code> and
-<code>Values</code> that can disguise what's going on. Just keep in
-mind that reflection Values need the address of something in order
-to modify what they represent.
-</p>
-
-<p><b>Structs</b></p>
-
-<p>
-In our previous example <code>v</code> wasn't a pointer itself, it
-was just derived from one. A common way for this situation to arise
-is when using reflection to modify the fields of a structure. As
-long as we have the address of the structure, we can modify its
-fields.
-</p>
-
-<p>
-Here's a simple example that analyzes a struct value,
-<code>t</code>. We create the reflection object with the address of
-the struct because we'll want to modify it later. Then we set
-<code>typeOfT</code> to its type and iterate over the fields using
-straightforward method calls (see 
-<a href="http://golang.org/pkg/reflect/">package reflect</a> for details).
-Note that we extract the names of the fields from the struct type,
-but the fields themselves are regular <code>reflect.Value</code>
-objects.
-</p>
-
-{{code "progs/interface2.go" `/START f8/` `/STOP/`}}
-
-<p>
-The output of this program is
-</p>
-
-<pre>
-0: A int = 23
-1: B string = skidoo
-</pre>
-
-<p>
-There's one more point about settability introduced in
-passing here: the field names of <code>T</code> are upper case
-(exported) because only exported fields of a struct are
-settable.
-</p>
-
-<p>
-Because <code>s</code> contains a settable reflection object, we
-can modify the fields of the structure.
-</p>
-
-{{code "progs/interface2.go" `/START f8b/` `/STOP/`}}
-
-<p>
-And here's the result:
-</p>
-
-<pre>
-t is now {77 Sunset Strip}
-</pre>
-
-<p>
-If we modified the program so that <code>s</code> was created from
-<code>t</code>, not <code>&amp;t</code>, the calls to
-<code>SetInt</code> and <code>SetString</code> would fail as the
-fields of <code>t</code> would not be settable.
-</p>
-
-<p><b>Conclusion</b></p>
-
-<p>
-Here again are the laws of reflection:
-</p>
-
-<ol>
-<li>Reflection goes from interface value to reflection
-object.</li>
-<li>Reflection goes from reflection object to interface
-value.</li>
-<li>To modify a reflection object, the value must be settable.</li>
-</ol>
-
-<p>
-Once you understand these laws reflection in Go becomes much easier
-to use, although it remains subtle. It's a powerful tool that
-should be used with care and avoided unless strictly
-necessary.
-</p>
-
-<p>
-There's plenty more to reflection that we haven't covered &mdash;
-sending and receiving on channels, allocating memory, using slices
-and maps, calling methods and functions &mdash; but this post is
-long enough. We'll cover some of those topics in a later
-article.
-</p>
\ No newline at end of file
diff --git a/doc/articles/slices_usage_and_internals.html b/doc/articles/slices_usage_and_internals.html
index c10dfe0ca..810b0a41f 100644
--- a/doc/articles/slices_usage_and_internals.html
+++ b/doc/articles/slices_usage_and_internals.html
@@ -1,11 +1,7 @@
 <!--{
-	"Title": "Slices: usage and internals"
+	"Title": "Slices: usage and internals",
+	"Template": true
 }-->
-<!--
-  DO NOT EDIT: created by
-    tmpltohtml articles/slices_usage_and_internals.tmpl
--->
-
 
 <p>
 Go's slice type provides a convenient and efficient means of working with
@@ -326,20 +322,7 @@ appends byte elements to a slice of bytes, growing the slice if necessary, and
 returns the updated slice value:
 </p>
 
-<pre><!--{{code "progs/slices.go" `/AppendByte/` `/STOP/`}}
--->func AppendByte(slice []byte, data ...byte) []byte {
-    m := len(slice)
-    n := m + len(data)
-    if n &gt; cap(slice) { // if necessary, reallocate
-        // allocate double what&#39;s needed, for future growth.
-        newSlice := make([]byte, (n+1)*2)
-        copy(newSlice, slice)
-        slice = newSlice
-    }
-    slice = slice[0:n]
-    copy(slice[m:n], data)
-    return slice
-}</pre>
+{{code "/doc/progs/slices.go" `/AppendByte/` `/STOP/`}}
 
 <p>
 One could use <code>AppendByte</code> like this:
@@ -398,18 +381,7 @@ Since the zero value of a slice (<code>nil</code>) acts like a zero-length
 slice, you can declare a slice variable and then append to it in a loop:
 </p>
 
-<pre><!--{{code "progs/slices.go" `/Filter/` `/STOP/`}}
--->// Filter returns a new slice holding only
-// the elements of s that satisfy f()
-func Filter(s []int, fn func(int) bool) []int {
-    var p []int // == nil
-    for _, i := range s {
-        if fn(i) {
-            p = append(p, i)
-        }
-    }
-    return p
-}</pre>
+{{code "/doc/progs/slices.go" `/Filter/` `/STOP/`}}
 
 <p>
 <b>A possible "gotcha"</b>
@@ -428,13 +400,7 @@ searches it for the first group of consecutive numeric digits, returning them
 as a new slice.
 </p>
 
-<pre><!--{{code "progs/slices.go" `/digit/` `/STOP/`}}
--->var digitRegexp = regexp.MustCompile(&#34;[0-9]+&#34;)
-
-func FindDigits(filename string) []byte {
-    b, _ := ioutil.ReadFile(filename)
-    return digitRegexp.Find(b)
-}</pre>
+{{code "/doc/progs/slices.go" `/digit/` `/STOP/`}}
 
 <p>
 This code behaves as advertised, but the returned <code>[]byte</code> points
@@ -449,14 +415,7 @@ To fix this problem one can copy the interesting data to a new slice before
 returning it:
 </p>
 
-<pre><!--{{code "progs/slices.go" `/CopyDigits/` `/STOP/`}}
--->func CopyDigits(filename string) []byte {
-    b, _ := ioutil.ReadFile(filename)
-    b = digitRegexp.Find(b)
-    c := make([]byte, len(b))
-    copy(c, b)
-    return c
-}</pre>
+{{code "/doc/progs/slices.go" `/CopyDigits/` `/STOP/`}}
 
 <p>
 A more concise version of this function could be constructed by using
diff --git a/doc/articles/slices_usage_and_internals.tmpl b/doc/articles/slices_usage_and_internals.tmpl
deleted file mode 100644
index d2f8fb7f5..000000000
--- a/doc/articles/slices_usage_and_internals.tmpl
+++ /dev/null
@@ -1,438 +0,0 @@
-<!--{
-	"Title": "Slices: usage and internals"
-}-->
-{{donotedit}}
-
-<p>
-Go's slice type provides a convenient and efficient means of working with
-sequences of typed data. Slices are analogous to arrays in other languages, but
-have some unusual properties. This article will look at what slices are and how
-they are used.
-</p>
-
-<p>
-<b>Arrays</b>
-</p>
-
-<p>
-The slice type is an abstraction built on top of Go's array type, and so to
-understand slices we must first understand arrays.
-</p>
-
-<p>
-An array type definition specifies a length and an element type. For example,
-the type <code>[4]int</code> represents an array of four integers. An array's
-size is fixed; its length is part of its type (<code>[4]int</code> and
-<code>[5]int</code> are distinct, incompatible types). Arrays can be indexed in
-the usual way, so the expression <code>s[n]</code> accesses the <i>n</i>th
-element:
-</p>
-
-<pre>
-var a [4]int
-a[0] = 1
-i := a[0]
-// i == 1
-</pre>
-
-<p>
-Arrays do not need to be initialized explicitly; the zero value of an array is
-a ready-to-use array whose elements are themselves zeroed:
-</p>
-
-<pre>
-// a[2] == 0, the zero value of the int type
-</pre>
-
-<p>
-The in-memory representation of <code>[4]int</code> is just four integer values laid out sequentially:
-</p>
-
-<p>
-<img src="slice-array.png">
-</p>
-
-<p>
-Go's arrays are values. An array variable denotes the entire array; it is not a
-pointer to the first array element (as would be the case in C).  This means
-that when you assign or pass around an array value you will make a copy of its
-contents. (To avoid the copy you could pass a <i>pointer</i> to the array, but
-then that's a pointer to an array, not an array.) One way to think about arrays
-is as a sort of struct but with indexed rather than named fields: a fixed-size
-composite value.
-</p>
-
-<p>
-An array literal can be specified like so:
-</p>
-
-<pre>
-b := [2]string{"Penn", "Teller"}
-</pre>
-
-<p>
-Or, you can have the compiler count the array elements for you:
-</p>
-
-<pre>
-b := [...]string{"Penn", "Teller"}
-</pre>
-
-<p>
-In both cases, the type of <code>b</code> is <code>[2]string</code>.
-</p>
-
-<p>
-<b>Slices</b>
-</p>
-
-<p>
-Arrays have their place, but they're a bit inflexible, so you don't see them
-too often in Go code. Slices, though, are everywhere. They build on arrays to
-provide great power and convenience.
-</p>
-
-<p>
-The type specification for a slice is <code>[]T</code>, where <code>T</code> is
-the type of the elements of the slice. Unlike an array type, a slice type has
-no specified length.
-</p>
-
-<p>
-A slice literal is declared just like an array literal, except you leave out
-the element count:
-</p>
-
-<pre>
-letters := []string{"a", "b", "c", "d"}
-</pre>
-
-<p>
-A slice can be created with the built-in function called <code>make</code>,
-which has the signature,
-</p>
-
-<pre>
-func make([]T, len, cap) []T
-</pre>
-
-<p>
-where T stands for the element type of the slice to be created. The
-<code>make</code> function takes a type, a length, and an optional capacity.
-When called, <code>make</code> allocates an array and returns a slice that
-refers to that array.
-</p>
-
-<pre>
-var s []byte
-s = make([]byte, 5, 5)
-// s == []byte{0, 0, 0, 0, 0}
-</pre>
-
-<p>
-When the capacity argument is omitted, it defaults to the specified length.
-Here's a more succinct version of the same code:
-</p>
-
-<pre>
-s := make([]byte, 5)
-</pre>
-
-<p>
-The length and capacity of a slice can be inspected using the built-in
-<code>len</code> and <code>cap</code> functions.
-</p>
-
-<pre>
-len(s) == 5
-cap(s) == 5
-</pre>
-
-<p>
-The next two sections discuss the relationship between length and capacity.
-</p>
-
-<p>
-The zero value of a slice is <code>nil</code>. The <code>len</code> and
-<code>cap</code> functions will both return 0 for a nil slice.
-</p>
-
-<p>
-A slice can also be formed by "slicing" an existing slice or array. Slicing is
-done by specifying a half-open range with two indices separated by a colon. For
-example, the expression <code>b[1:4]</code> creates a slice including elements
-1 through 3 of <code>b</code> (the indices of the resulting slice will be 0
-through 2).
-</p>
-
-<pre>
-b := []byte{'g', 'o', 'l', 'a', 'n', 'g'}
-// b[1:4] == []byte{'o', 'l', 'a'}, sharing the same storage as b
-</pre>
-
-<p>
-The start and end indices of a slice expression are optional; they default to zero and the slice's length respectively:
-</p>
-
-<pre>
-// b[:2] == []byte{'g', 'o'}
-// b[2:] == []byte{'l', 'a', 'n', 'g'}
-// b[:] == b
-</pre>
-
-<p>
-This is also the syntax to create a slice given an array:
-</p>
-
-<pre>
-x := [3]string{"Лайка", "Белка", "Стрелка"}
-s := x[:] // a slice referencing the storage of x
-</pre>
-
-<p>
-<b>Slice internals</b>
-</p>
-
-<p>
-A slice is a descriptor of an array segment. It consists of a pointer to the
-array, the length of the segment, and its capacity (the maximum length of the
-segment).
-</p>
-
-<p>
-<img src="slice-struct.png">
-</p>
-
-<p>
-Our variable <code>s</code>, created earlier by <code>make([]byte, 5)</code>,
-is structured like this:
-</p>
-
-<p>
-<img src="slice-1.png">
-</p>
-
-<p>
-The length is the number of elements referred to by the slice. The capacity is
-the number of elements in the underlying array (beginning at the element
-referred to by the slice pointer). The distinction between length and capacity
-will be made clear as we walk through the next few examples.
-</p>
-
-<p>
-As we slice <code>s</code>, observe the changes in the slice data structure and
-their relation to the underlying array:
-</p>
-
-<pre>
-s = s[2:4]
-</pre>
-
-<p>
-<img src="slice-2.png">
-</p>
-
-<p>
-Slicing does not copy the slice's data. It creates a new slice value that
-points to the original array. This makes slice operations as efficient as
-manipulating array indices. Therefore, modifying the <i>elements</i> (not the
-slice itself) of a re-slice modifies the elements of the original slice:
-</p>
-
-<pre>
-d := []byte{'r', 'o', 'a', 'd'}
-e := d[2:] 
-// e == []byte{'a', 'd'}
-e[1] == 'm'
-// e == []byte{'a', 'm'}
-// d == []byte{'r', 'o', 'a', 'm'}
-</pre>
-
-<p>
-Earlier we sliced <code>s</code> to a length shorter than its capacity. We can
-grow s to its capacity by slicing it again:
-</p>
-
-<pre>
-s = s[:cap(s)]
-</pre>
-
-<p>
-<img src="slice-3.png">
-</p>
-
-<p>
-A slice cannot be grown beyond its capacity. Attempting to do so will cause a
-runtime panic, just as when indexing outside the bounds of a slice or array.
-Similarly, slices cannot be re-sliced below zero to access earlier elements in
-the array.
-</p>
-
-<p>
-<b>Growing slices (the copy and append functions)</b>
-</p>
-
-<p>
-To increase the capacity of a slice one must create a new, larger slice and
-copy the contents of the original slice into it. This technique is how dynamic
-array implementations from other languages work behind the scenes. The next
-example doubles the capacity of <code>s</code> by making a new slice,
-<code>t</code>, copying the contents of <code>s</code> into <code>t</code>, and
-then assigning the slice value <code>t</code> to <code>s</code>:
-</p>
-
-<pre>
-t := make([]byte, len(s), (cap(s)+1)*2) // +1 in case cap(s) == 0
-for i := range s {
-        t[i] = s[i]
-}
-s = t
-</pre>
-
-<p>
-The looping piece of this common operation is made easier by the built-in copy
-function. As the name suggests, copy copies data from a source slice to a
-destination slice. It returns the number of elements copied.
-</p>
-
-<pre>
-func copy(dst, src []T) int
-</pre>
-
-<p>
-The <code>copy</code> function supports copying between slices of different
-lengths (it will copy only up to the smaller number of elements). In addition,
-<code>copy</code> can handle source and destination slices that share the same
-underlying array, handling overlapping slices correctly.
-</p>
-
-<p>
-Using <code>copy</code>, we can simplify the code snippet above:
-</p>
-
-<pre>
-t := make([]byte, len(s), (cap(s)+1)*2)
-copy(t, s)
-s = t
-</pre>
-
-<p>
-A common operation is to append data to the end of a slice. This function
-appends byte elements to a slice of bytes, growing the slice if necessary, and
-returns the updated slice value:
-</p>
-
-{{code "progs/slices.go" `/AppendByte/` `/STOP/`}}
-
-<p>
-One could use <code>AppendByte</code> like this:
-</p>
-
-<pre>
-p := []byte{2, 3, 5}
-p = AppendByte(p, 7, 11, 13)
-// p == []byte{2, 3, 5, 7, 11, 13}
-</pre>
-
-<p>
-Functions like <code>AppendByte</code> are useful because they offer complete
-control over the way the slice is grown. Depending on the characteristics of
-the program, it may be desirable to allocate in smaller or larger chunks, or to
-put a ceiling on the size of a reallocation.
-</p>
-
-<p>
-But most programs don't need complete control, so Go provides a built-in
-<code>append</code> function that's good for most purposes; it has the
-signature
-</p>
-
-<pre>
-func append(s []T, x ...T) []T 
-</pre>
-
-<p>
-The <code>append</code> function appends the elements <code>x</code> to the end
-of the slice <code>s</code>, and grows the slice if a greater capacity is
-needed.
-</p>
-
-<pre>
-a := make([]int, 1)
-// a == []int{0}
-a = append(a, 1, 2, 3)
-// a == []int{0, 1, 2, 3}
-</pre>
-
-<p>
-To append one slice to another, use <code>...</code> to expand the second
-argument to a list of arguments.
-</p>
-
-<pre>
-a := []string{"John", "Paul"}
-b := []string{"George", "Ringo", "Pete"}
-a = append(a, b...) // equivalent to "append(a, b[0], b[1], b[2])"
-// a == []string{"John", "Paul", "George", "Ringo", "Pete"}
-</pre>
-
-<p>
-Since the zero value of a slice (<code>nil</code>) acts like a zero-length
-slice, you can declare a slice variable and then append to it in a loop:
-</p>
-
-{{code "progs/slices.go" `/Filter/` `/STOP/`}}
-
-<p>
-<b>A possible "gotcha"</b>
-</p>
-
-<p>
-As mentioned earlier, re-slicing a slice doesn't make a copy of the underlying
-array. The full array will be kept in memory until it is no longer referenced.
-Occasionally this can cause the program to hold all the data in memory when
-only a small piece of it is needed.
-</p>
-
-<p>
-For example, this <code>FindDigits</code> function loads a file into memory and
-searches it for the first group of consecutive numeric digits, returning them
-as a new slice.
-</p>
-
-{{code "progs/slices.go" `/digit/` `/STOP/`}}
-
-<p>
-This code behaves as advertised, but the returned <code>[]byte</code> points
-into an array containing the entire file. Since the slice references the
-original array, as long as the slice is kept around the garbage collector can't
-release the array; the few useful bytes of the file keep the entire contents in
-memory.
-</p>
-
-<p>
-To fix this problem one can copy the interesting data to a new slice before
-returning it:
-</p>
-
-{{code "progs/slices.go" `/CopyDigits/` `/STOP/`}}
-
-<p>
-A more concise version of this function could be constructed by using
-<code>append</code>. This is left as an exercise for the reader.
-</p>
-
-<p>
-<b>Further Reading</b>
-</p>
-
-<p>
-<a href="/doc/effective_go.html">Effective Go</a> contains an
-in-depth treatment of <a href="/doc/effective_go.html#slices">slices</a>
-and <a href="/doc/effective_go.html#arrays">arrays</a>, 
-and the Go <a href="/doc/go_spec.html">language specification</a>
-defines <a href="/doc/go_spec.html#Slice_types">slices</a> and their
-<a href="/doc/go_spec.html#Length_and_capacity">associated</a>
-<a href="/doc/go_spec.html#Making_slices_maps_and_channels">helper</a>
-<a href="/doc/go_spec.html#Appending_and_copying_slices">functions</a>.
-</p>
diff --git a/doc/articles/wiki/test.sh b/doc/articles/wiki/test.bash
index 58b218a78..5c2cb60dc 100755
--- a/doc/articles/wiki/test.sh
+++ b/doc/articles/wiki/test.bash
@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+# Copyright 2010 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.
 
 set -e
 wiki_pid=
@@ -8,10 +11,10 @@ cleanup() {
 }
 trap cleanup 0 INT
 
-make get.bin
+go build -o get.bin get.go
 addr=$(./get.bin -addr)
 sed s/:8080/$addr/ < final.go > final-test.go
-make final-test.bin
+go build -o final-test.bin final-test.go
 (./final-test.bin) &
 wiki_pid=$!
 
diff --git a/doc/button_background.png b/doc/button_background.png
deleted file mode 100644
index 86a3b3086..000000000
--- a/doc/button_background.png
+++ /dev/null
diff --git a/doc/code.html b/doc/code.html
index 768a9995a..238cb0643 100644
--- a/doc/code.html
+++ b/doc/code.html
@@ -245,7 +245,7 @@ $ go install
 </pre>
 
 <p>
-The resulting workspace directory tree (assuimg we're running Linux on a 64-bit
+The resulting workspace directory tree (assuming we're running Linux on a 64-bit
 system) looks like this:
 </p>
 
diff --git a/doc/codewalk/markov.xml b/doc/codewalk/markov.xml
index 81df1289c..085ead7bc 100644
--- a/doc/codewalk/markov.xml
+++ b/doc/codewalk/markov.xml
@@ -155,7 +155,7 @@ Prefix               Map key
 	<br/><br/>
 	For more information about the <code>append</code> function and slices
 	in general see the
-	<a href="http://blog.golang.org/2011/01/go-slices-usage-and-internals.html">Slices: usage and internals</a> article.
+	<a href="/doc/articles/slices_usage_and_internals.html">Slices: usage and internals</a> article.
 </step>
 
 <step title="Pushing the suffix onto the prefix" src="doc/codewalk/markov.go:/p\.Shift/">
@@ -275,16 +275,15 @@ p[len(p)-1] = suffix
 </step>
 
 <step title="Using this program" src="doc/codewalk/markov.go">
-	To use this program, first compile and link it.
-	If you are using <code>6g</code> as your compiler, the command
-	would look something like this:
+	To use this program, first build it with the
+	<a href="/cmd/go/">go</a> command:
 	<pre>
-$ 6g markov.go &amp;&amp; 6l -o markov markov.6</pre>
+$ go build markov.go</pre>
 	And then execute it while piping in some input text:
 	<pre>
-$ echo "a man a plan a canal panama" | ./markov -prefix=1
-a plan a man a plan a canal panama
-	</pre>
+$ echo "a man a plan a canal panama" \
+	| ./markov -prefix=1
+a plan a man a plan a canal panama</pre>
 	Here's a transcript of generating some text using the Go distribution's
 	README file as source material:
 	<pre>
diff --git a/doc/contrib.html b/doc/contrib.html
index 76cee1ffd..b4bd47e96 100644
--- a/doc/contrib.html
+++ b/doc/contrib.html
@@ -3,6 +3,8 @@
 	"Path": "/project/"
 }-->
 
+<img class="gopher" src="/doc/gopher/project.png" />
+
 <div id="manual-nav"></div>
 
 <p>
@@ -15,6 +17,15 @@ Go is an open source project developed by a team at
 Go is distributed under a <a href="/LICENSE">BSD-style license</a>.
 </p>
 
+<h3 id="announce"><a href="http://groups.google.com/group/golang-announce">Announcements Mailing List</a></h3>
+<p>
+A low traffic mailing list for important announcements, such as new releases.
+</p>
+<p>
+We encourage all Go users to subscribe to
+<a href="http://groups.google.com/group/golang-announce">golang-announce</a>.
+</p>
+
 <h2 id="resources">Developer Resources</h2>
 
 <h3 id="source"><a href="https://code.google.com/p/go/source">Source Code</a></h3>
diff --git a/doc/contribute.html b/doc/contribute.html
index 73233c588..e1f39ae7e 100644
--- a/doc/contribute.html
+++ b/doc/contribute.html
@@ -404,7 +404,7 @@ $ hg mail -r golang-dev@googlegroups.com --cc math-nuts@swtch.com 99999
 
 <p>
 Running <code>hg mail</code> will send an email to you and the reviewers
-asking them to visit the issue's URL and make coments on the change.
+asking them to visit the issue's URL and make comments on the change.
 When done, the reviewer clicks &ldquo;Publish and Mail comments&rdquo;
 to send comments back.
 </p>
diff --git a/doc/debugging_with_gdb.html b/doc/debugging_with_gdb.html
index 43977b777..1ac1c1fd8 100644
--- a/doc/debugging_with_gdb.html
+++ b/doc/debugging_with_gdb.html
@@ -4,22 +4,23 @@
 }-->
 
 <p><i>
-This applies to the 6g toolchain. Gccgo has native gdb support. Besides this
-overview you might want to consult the
+This applies to the <code>gc</code> toolchain. Gccgo has native gdb support.
+Besides this overview you might want to consult the
 <a href="http://sourceware.org/gdb/current/onlinedocs/gdb/">GDB manual</a>.
 </i></p>
 
 <h2 id="Introduction">Introduction</h2>
 
 <p>
-When you compile and link your Go programs with the 6g/6l or 8g/8l toolchains
-on Linux, Mac OSX or FreeBSD, the resulting binaries contain DWARFv3
-debugging information that recent versions (>7.1) of the GDB debugger can
+When you compile and link your Go programs with the <code>gc</code> toolchain
+on Linux, Mac OS X or FreeBSD, the resulting binaries contain DWARFv3
+debugging information that recent versions (&gt;7.1) of the GDB debugger can
 use to inspect a live process or a core dump.
 </p>
 
 <p>
-Pass the <code>'-s'</code> flag to the linker to omit the debug information.
+Pass the <code>'-s'</code> flag to the linker to omit the debug information
+(for example, <code>go build -ldflags "-s" prog.go</code>).
 </p>
 
 
@@ -28,7 +29,7 @@ Pass the <code>'-s'</code> flag to the linker to omit the debug information.
 <ul>
 <li>
 Show file and line number for code 
-and set breakpoints:
+, set breakpoints and disassemble:
 <pre>(gdb) <b>list</b>
 (gdb) <b>list <i>line</i></b>
 (gdb) <b>list <i>file.go</i>:<i>line</i></b>
@@ -37,7 +38,7 @@ and set breakpoints:
 (gdb) <b>disas</b></pre>
 </li>
 <li>
-Unwind stack frames:
+Show backtraces and unwind stack frames:
 <pre>(gdb) <b>bt</b>
 (gdb) <b>frame <i>n</i></b></pre>
 </li>
@@ -101,7 +102,7 @@ the Go source distribution. It depends on some special magic types
 <code>runtime.g</code>) that the linker
 (<a href="/src/cmd/ld/dwarf.c">src/cmd/ld/dwarf.c</a>) ensures are described in
 the DWARF code.
-</ines
+</p>
 
 <p>
 If you're interested in what the debugging information looks like, run
@@ -128,26 +129,26 @@ the form <code>pkg.(*MyType).Meth</code>.
 <p>
 In this tutorial we will inspect the binary of the
 <a href="/pkg/regexp/">regexp</a> package's unit tests. To build the binary,
-change to <code>$GOROOT/src/pkg/regexp</code> and run <code>gotest</code>.
-This should produce an executable file named <code>6.out</code>.
+change to <code>$GOROOT/src/pkg/regexp</code> and run <code>go test -c</code>.
+This should produce an executable file named <code>regexp.test</code>.
 </p>
 
 
 <h3 id="Getting_Started">Getting Started</h3>
 
 <p>
-Launch GDB, debugging <code>6.out</code>:
+Launch GDB, debugging <code>regexp.test</code>:
 </p>
 
 <pre>
-$ <b>gdb 6.out</b>
+$ <b>gdb regexp.test</b>
 GNU gdb (GDB) 7.2-gg8
 Copyright (C) 2010 Free Software Foundation, Inc.
 License GPLv  3+: GNU GPL version 3 or later &lt;http://gnu.org/licenses/gpl.html&gt;
 Type "show copying" and "show warranty" for licensing/warranty details.
 This GDB was configured as "x86_64-linux".
 
-Reading symbols from  /home/user/go/src/pkg/regexp/6.out...
+Reading symbols from  /home/user/go/src/pkg/regexp/regexp.test...
 done.
 Loading Go Runtime support.
 (gdb) 
@@ -164,7 +165,7 @@ pass your <code>$GOROOT</code> with the <code>'-d'</code> flag:
 </p>
 
 <pre>
-$ <b>gdb 6.out -d $GOROOT</b>
+$ <b>gdb regexp.test -d $GOROOT</b>
 </pre>
 
 <p>
@@ -217,14 +218,13 @@ package is known to GDB as <code>'regexp.Compile'</code>.
 
 <p>
 Methods must be qualified with the name of their receiver types. For example,
-the <code>*Regexp</code> type’s <code>doParse</code> method is known as
-<code>'regexp.*Regexp.doParse'</code>. (Note that the second dot is a "middot,"
-an artifact of Go’s internal representation of methods.)
+the <code>*Regexp</code> type’s <code>String</code> method is known as
+<code>'regexp.(*Regexp).String'</code>.
 </p>
 
 <p>
 Variables that shadow other variables are magically suffixed with a number in the debug info.
-Variables referenced by closures will appear as pointers magically prefixed with '&amp'.
+Variables referenced by closures will appear as pointers magically prefixed with '&amp;'.
 </p>
 
 <h3 id="Setting_breakpoints">Setting breakpoints</h3>
@@ -244,7 +244,7 @@ Run the program:
 
 <pre>
 (gdb) <b>run</b>
-Starting program: /home/lvd/g/src/pkg/regexp/6.out 
+Starting program: /home/user/go/src/pkg/regexp/regexp.test
 
 Breakpoint 1, regexp.TestFind (t=0xf8404a89c0) at /home/user/go/src/pkg/regexp/find_test.go:148
 148	func TestFind(t *testing.T) {
@@ -287,16 +287,18 @@ The other goroutine, number 1, is stuck in <code>runtime.gosched</code>, blocked
 
 <pre>
 (gdb) <b>goroutine 1 bt</b>
-#0  0x000000000040facb in runtime.gosched () at /home/lvd/g/src/pkg/runtime/proc.c:873
+#0  0x000000000040facb in runtime.gosched () at /home/user/go/src/pkg/runtime/proc.c:873
 #1  0x00000000004031c9 in runtime.chanrecv (c=void, ep=void, selected=void, received=void)
- at  /home/lvd/g/src/pkg/runtime/chan.c:342
-#2  0x0000000000403299 in runtime.chanrecv1 (t=void, c=void) at/home/lvd/g/src/pkg/runtime/chan.c:423
-#3  0x000000000043075b in testing.RunTests (matchString={void (struct string, struct string, bool *, error *)} 0x7ffff7f9ef60, tests=  []testing.InternalTest = {...}) at /home/lvd/g/src/pkg/testing/testing.go:201
-#4  0x00000000004302b1 in testing.Main (matchString={void (struct string, struct string, bool *, error *)} 0x7ffff7f9ef80, tests= []testing.InternalTest = {...}, benchmarks= []testing.InternalBenchmark = {...})
-    at /home/lvd/g/src/pkg/testing/testing.go:168
-#5  0x0000000000400dc1 in main.main () at /home/lvd/g/src/pkg/regexp/_testmain.go:98
-#6  0x00000000004022e7 in runtime.mainstart () at /home/lvd/g/src/pkg/runtime/amd64/asm.s:78
-#7  0x000000000040ea6f in runtime.initdone () at /home/lvd/g/src/pkg/runtime/proc.c:243
+ at  /home/user/go/src/pkg/runtime/chan.c:342
+#2  0x0000000000403299 in runtime.chanrecv1 (t=void, c=void) at/home/user/go/src/pkg/runtime/chan.c:423
+#3  0x000000000043075b in testing.RunTests (matchString={void (struct string, struct string, bool *, error *)}
+ 0x7ffff7f9ef60, tests=  []testing.InternalTest = {...}) at /home/user/go/src/pkg/testing/testing.go:201
+#4  0x00000000004302b1 in testing.Main (matchString={void (struct string, struct string, bool *, error *)} 
+ 0x7ffff7f9ef80, tests= []testing.InternalTest = {...}, benchmarks= []testing.InternalBenchmark = {...})
+at /home/user/go/src/pkg/testing/testing.go:168
+#5  0x0000000000400dc1 in main.main () at /home/user/go/src/pkg/regexp/_testmain.go:98
+#6  0x00000000004022e7 in runtime.mainstart () at /home/user/go/src/pkg/runtime/amd64/asm.s:78
+#7  0x000000000040ea6f in runtime.initdone () at /home/user/go/src/pkg/runtime/proc.c:243
 #8  0x0000000000000000 in ?? ()
 </pre>
 
@@ -307,7 +309,7 @@ The stack frame shows we’re currently executing the <code>regexp.TestFind</cod
 <pre>
 (gdb) <b>info frame</b>
 Stack level 0, frame at 0x7ffff7f9ff88:
- rip = 0x425530 in regexp.TestFind (/home/lvd/g/src/pkg/regexp/find_test.go:148); 
+ rip = 0x425530 in regexp.TestFind (/home/user/go/src/pkg/regexp/find_test.go:148); 
     saved rip 0x430233
  called by frame at 0x7ffff7f9ffa8
  source language minimal.
@@ -346,12 +348,12 @@ $1 = (struct testing.T *) 0xf840688b60
 $1 = (struct testing.T *) 0xf840688b60
 (gdb) p *t
 $2 = {errors = "", failed = false, ch = 0xf8406f5690}
-(gdb) p *t->ch
-$3 = struct hchan<*testing.T>
+(gdb) p *t-&gt;ch
+$3 = struct hchan&lt;*testing.T&gt;
 </pre>
 
 <p>
-That <code>struct hchan<*testing.T></code> is the runtime-internal represntation of a channel.  It is currently empty, or gdb would have pretty-printed it's contents.
+That <code>struct hchan&lt;*testing.T&gt;</code> is the runtime-internal representation of a channel.  It is currently empty, or gdb would have pretty-printed it's contents.
 </p>
 
 <p>
@@ -384,7 +386,7 @@ We can step into the <code>String</code>function call with <code>"s"</code>:
 
 <pre>
 (gdb) <b>s</b>
-regexp.(*Regexp).String (re=0xf84068d070, noname=void) at /home/lvd/g/src/pkg/regexp/regexp.go:97
+regexp.(*Regexp).String (re=0xf84068d070, noname=void) at /home/user/go/src/pkg/regexp/regexp.go:97
 97      func (re *Regexp) String() string {
 </pre>
 
@@ -394,14 +396,13 @@ Get a stack trace to see where we are:
 
 <pre>
 (gdb) <b>bt</b>
-(gdb) bt
 #0  regexp.(*Regexp).String (re=0xf84068d070, noname=void)
-    at /home/lvd/g/src/pkg/regexp/regexp.go:97
+    at /home/user/go/src/pkg/regexp/regexp.go:97
 #1  0x0000000000425615 in regexp.TestFind (t=0xf840688b60)
-    at /home/lvd/g/src/pkg/regexp/find_test.go:151
+    at /home/user/go/src/pkg/regexp/find_test.go:151
 #2  0x0000000000430233 in testing.tRunner (t=0xf840688b60, test=0x5747b8)
-    at /home/lvd/g/src/pkg/testing/testing.go:156
-#3  0x000000000040ea6f in runtime.initdone () at /home/lvd/g/src/pkg/runtime/proc.c:243
+    at /home/user/go/src/pkg/testing/testing.go:156
+#3  0x000000000040ea6f in runtime.initdone () at /home/user/go/src/pkg/runtime/proc.c:243
 ....
 </pre>
 
@@ -442,7 +443,7 @@ you can look inside the runtime representation to do that (tab completion helps
 
 (gdb) <b>p slc</b>
 $11 =  []int = {0, 0}
-(gdb) <b>p slc-&gt</b><i>&ltTAB&gt</i>
+(gdb) <b>p slc-&gt;</b><i>&lt;TAB&gt;</i>
 array  slc    len    
 (gdb) <b>p slc->array</b>
 $12 = (int *) 0xf84057af00
@@ -463,7 +464,7 @@ $24 = 4
 </pre>
 
 <p>
-Channels and maps are 'reference' types, which gdb shows as pointers to C++-like types <code>hash&ltint,string&gt*</code>.  Dereferencing will trigger prettyprinting
+Channels and maps are 'reference' types, which gdb shows as pointers to C++-like types <code>hash&lt;int,string&gt;*</code>.  Dereferencing will trigger prettyprinting
 </p>
 
 <p>
diff --git a/doc/devel/weekly.html b/doc/devel/weekly.html
index ba88c3625..4c4b52e44 100644
--- a/doc/devel/weekly.html
+++ b/doc/devel/weekly.html
@@ -14,6 +14,254 @@ hg pull
 hg update weekly.<i>YYYY-MM-DD</i>
 </pre>
 
+<h2 id="2012-03-22">2012-03-22 (Go 1 Release Candidate 2)</h2>
+
+<pre>
+As with last week's snapshot, this snapshot is another Go 1 release candidate.
+A notable change in this snapshot are Windows installer fixes.
+
+Changes in this snapshot:
+* 5l, 6l, 8l: fix stack split logic for stacks near default segment size.
+* archive/zip: move r.zip off disk, into reader_test.go.
+* build: catch API changes during build,
+	do more during windows build (thanks Alex Brainman),
+	lengthen timeout for the lengthy runtime test (thanks Shenghou Ma),
+	unset GOPATH before tests (thanks Shenghou Ma).
+* cmd/cgo: add support for function export for gccgo (thanks Rémy Oudompheng),
+	fix handling of errno for gccgo.
+* cmd/go: add -fno-common by default on Darwin (thanks Shenghou Ma),
+	don't add detail to errPrintedOutput,
+	fix directory->import path conversion,
+	make build errors more visible,
+	use .o, not .{5,6,8}, for gccgo created object files,
+	work around occasional ETXTBSY running cgo.
+* cmd/godoc: add toys, tour button to playground,
+	inform users that the playground doesn't work via local godoc,
+	style example headings like links,
+	use *goroot as base path in zip file,
+	use FormatText for formating code in html template,
+	use shorter titles for tabs.
+* cmd/gofmt: show ascii in usage (thanks Yasuhiro Matsumoto).
+* cmd/pack: also recognize '\\' as path separator in filenames (thanks Shenghou Ma).
+* crypto/tls: always send a Certificate message if one was requested.
+* doc/install: remove reference to "Go Tutorial" (thanks Shenghou Ma).
+* doc/play: use []rune instead of []int (thanks Yasuhiro Matsumoto).
+* doc: add Go Concurrency Patterns: Timing out, moving on article (thanks Francisco Souza),
+	add Go image/draw package article and convert code snippets to Go1,
+	add Gobs of data article (thanks Francisco Souza),
+	add Godoc: documenting Go code article (thanks Francisco Souza),
+	add JSON and Go article (thanks Francisco Souza),
+	general update of gccgo installation instructions,
+	minor updates to most docs.
+* flag: add examples.
+* gc: fix struct and array comparisons for new bool rules (thanks Anthony Martin),
+	use quoted string format in import error,
+	when expanding append inline, preserve arguments.
+* go/build: clarify why we exclude files starting with '_' or '.' (thanks Shenghou Ma),
+	clearer argument name for Import (src -> srcDir),
+	do not report Target for local imports,
+	fix match.
+* go/printer, gofmt: fix multi-line logic.
+* html/template: add Templates and XXXEscape functions,
+	fix nil pointer bug,
+	fix panic on Clone.
+* io/ioutil: fix crash when Stat fails.
+* make.bat: fix for old files (thanks Christopher Redden),
+	don't show error message if old generated files do not exist (thanks Shenghou Ma),
+	properly handle directories with spaces (thanks Alex Brainman).
+* misc/cgo/gmp: update for Go 1 (thanks Shenghou Ma).
+* misc/dashboard: remove old python package dashboard.
+* misc/dist: don't ship cmd/cov or cmd/prof,
+	force modes to 0755 or 0644 in tarballs,
+	remove exp and old before building.
+* misc/vim: restore fileencodings (thanks Yasuhiro Matsumoto).
+* net/http: couple more triv.go modernizations,
+	ensure triv.go compiles and runs (thanks Robert Hencke).
+* net: drop unnecessary type assertions and fix leak in test (thanks Mikio Hara).
+* os: IsNotExist() should also consider ERROR_PATH_NOT_FOUND on Windows (thanks Shenghou Ma),
+	do not assume syscall.Write will write everything,
+	remove document duplication in error predicate functions (thanks Shenghou Ma),
+	return some invented data from Stat(DevNull) on windows (thanks Alex Brainman).
+* path/filepath: implement Match and Glob on windows (thanks Alex Brainman).
+* reflect: document PkgPath, Method, StructField,
+	panic if MakeSlice is given bad len/cap arguments.
+* run.bat: disable test in test\bench\go1 to fix build (thanks Alex Brainman).
+* runtime/cgo: darwin signal masking (thanks Mikio Hara),
+	linux signal masking (thanks Mikio Hara).
+* runtime: do not handle signals before configuring handler,
+	manage stack by ourselves for badcallback on windows/amd64 (thanks Shenghou Ma),
+	remove unused goc2c.c (thanks Shenghou Ma).
+* sort: add time complexity to doc (thanks Stefan Nilsson),
+	fix computation of maxDepth to avoid infinite loop (thanks Stefan Nilsson).
+* spec: delete references to unsafe.Reflect,Typeof,Unreflect.
+* syscall: Test SCM_CREDENTIALS, SO_PASSCRED on Linux (thanks Albert Strasheim),
+	add a test for passing an fd over a unix socket,
+	delete passfd_test.go.
+* test: use testlib in a few more cases (thanks Shenghou Ma).
+* text/template: fix a couple of parse bugs around identifiers,
+	variables do not take arguments.
+</pre>
+
+<h2 id="2012-03-13">2012-03-13 (Go 1 Release Candidate 1)</h2>
+
+<pre>
+This weekly snapshot is very close to what we expect will be the contents of
+the Go 1 release. There are still a few minor documentation issues to resolve,
+and a handful of bugs that should be addressed before the release, but the vast
+majority of Go programs should be completely unaffected by any changes we make
+between now and the full release.
+
+If you're interested in helping us test, eager to try out Go 1, or just
+curious, this weekly snapshot is the one to try. We'll issue a new App Engine
+Go 1 beta SDK very soon, so if you're an App Engine user you can try it there
+too.
+
+To help us focus on any remaining bugs and avoid introducing new ones, we will
+restrict our attention to critical fixes and issues marked Go1-Must in the
+issue tracker. Everything non-essential will be held until after the Go 1
+release is cut and in the field for a while.
+
+Changes in this snapshot:
+* archive/zip: verify CRC32s in non-streamed files,
+	write data descriptor signature for OS X; fix bugs reading it.
+* build: build correct cmd/dist matching GOHOSTARCH (thanks Shenghou Ma),
+	re-enable some broken tests in run.bash (thanks Shenghou Ma),
+	remove some references to Make.inc etc.
+	use run.go for running tests.
+* builder: use short test for subrepos (thanks Shenghou Ma).
+* cgo, runtime: diagnose callback on non-Go thread.
+* cmd/api: set compiler for all build contexts,
+	work on Windows again, and make gccgo files work a bit more.
+* cmd/cgo: document CGO_LDFLAGS and CGO_CFLAGS,
+	silence const warnings.
+* cmd/dist, cmd/go: move CGO_ENABLED from 'go tool dist env' to 'go env' (thanks Shenghou Ma).
+* cmd/dist: fix build for Linux/ARM (thanks Shenghou Ma),
+	use correct hg tag for go version (thanks Alex Brainman).
+* cmd/fix: add rules for net/http -> net/http/httputil renames.
+* cmd/gc: allow ~ in import paths,
+	delete old map delete in walk,
+	do not confuse unexported methods of same name,
+	if $GOROOT_FINAL is set, rewrite file names in object files,
+	implement len(array) / cap(array) rule,
+	import path cannot start with slash on Windows (thanks Shenghou Ma),
+	must not inline panic, recover,
+	show duplicate key in error,
+	unnamed struct types can have methods.
+* cmd/go: add -compiler,
+	add env command, use to fix misc/cgo/testso,
+	allow go get with arbitrary URLs,
+	allow ssh tunnelled bzr, git and svn (thanks Ingo Oeser),
+	always provide .exe suffix on windows (thanks Shenghou Ma),
+	document import path meta tag discovery in go help remote,
+	honor buildflags in run, test (thanks Rémy Oudompheng),
+	local import fixes,
+	make go get new.code/... work,
+	rebuild external test package dependencies,
+	respect $GOBIN always,
+	support -compiler for go list, fix isStale for gccgo (thanks Rémy Oudompheng).
+* cmd/godoc: add support for serving templates.
+	fix codewalk handler (thanks Francisco Souza).
+	remove extra / in paths (thanks Ugorji Nwoke),
+	support $GOPATH, simplify file system code,
+	switch on +1 buttons.
+* cmd/gofmt: fix race in long test (thanks Mikio Hara).
+* codereview: fix for Mercurial 2.1.
+* crypto/x509: allow server gated crypto in windows systemVerify (thanks Mikkel Krautz),
+	do not forget to free cert context (thanks Alex Brainman),
+	don't include empty additional primes in PKCS#1 private key,
+	enforce path length constraint,
+	new home for root fetchers; build chains using Windows API (thanks Mikkel Krautz).
+* csv: clarify what a negative FieldsPerRecord means.
+* database/sql: add docs about connection state, pooling,
+	ensure Stmts are correctly closed (thanks Gwenael Treguier),
+	fix double connection free on Stmt.Query error,
+	fix typo bug resulting in double-Prepare.
+* database/sql: add ErrBadConn.
+* doc/go1: template packages have changed since r60.
+* doc/go_mem: init-created goroutine behavior changes for Go 1 (thanks Shenghou Ma).
+* doc/gopher: flip frontpage gopher's eyes.
+* doc: add "About the go command" article,
+	add C? Go? Cgo! article (thanks Francisco Souza),
+	add Go's declaration syntax article (thanks Francisco Souza),
+	add more gophers,
+	add note about import . to Go 1 compatibility notes,
+	several doc fixes and improvements,
+	update Effective Go init section,
+	update progs/run (thanks Shenghou Ma),
+	update reference gopher,
+	web site tweaks.
+* encoding/asn1: handle UTCTime before the year 2000.
+* encoding/binary: improve package comment (thanks Stefan Nilsson).
+* encoding/gob: fix memory corruption.
+* encoding/json: document that nil slice encodes as `null`.
+* exp/wingui: moved to code.google.com/p/gowingui.
+* expvar: add locking to String, and use RWMutex properly throughout,
+	add missing locking in String methods.
+* fmt, log: stop using unicode.
+* fmt: minor tweak of package doc to show headings in godoc (thanks Volker Dobler).
+* go/build, cmd/go: add support for .syso files.
+* go/build: add NoGoError,
+	add dependency test,
+	do not parse .syso files (thanks Alex Brainman).
+* go/parser: avoid endless loop in case of internal error,
+	better error synchronization.
+* go/printer, gofmt: nicer formatting of multi-line returns.
+* go/printer: example for Fprint.
+* go/scanner: better panic diagnostic.
+* go spec: no known implementation differences anymore,
+	fix inaccuracy in type identity definition.
+* io: better document WriterAt.
+* misc/dashboard: remove obsolete package builder code.
+* misc/dist: add source archive support,
+	add windows installer and zip support,
+	minimum target requirement is 10.6 for Darwin (thanks Shenghou Ma).
+* misc/emacs: fix extra indentation after comments that end with a period.
+* misc/xcode: example install of language spec for Xcode 4.x (thanks Emil Hessman).
+* net, net/rpc, reflect, time: document concurrency guarantees.
+* net/http: fix crash with Transport.CloseIdleConnections,
+	return appropriate errors from ReadRequest.
+* net: add skip message to test (thanks Mikio Hara),
+	disable use of external listen along with other external network uses,
+	do not use reflect for DNS messages (thanks Rémy Oudompheng),
+	document ReadMsgUnix, WriteMsgUnix,
+	fix TestDialTimeout on windows builder,
+	improve server and file tests (thanks Mikio Hara),
+	make Dial and Listen behavior consistent across over platforms (thanks Mikio Hara),
+	remove dependence on bytes, fmt, strconv,
+	silence another epoll print,
+	use IANA reserved port to test dial timeout (thanks Mikio Hara).
+* os: document FileInfo.Size as system-dependent for irregular files,
+	fix SameFile to work for directories on windows (thanks Alex Brainman).
+* path/filepath/path_test.go: repair and enable TestAbs.
+* path/filepath: disable AbsTest on windows,
+	retrieve real file name in windows EvalSymlinks (thanks Alex Brainman).
+* runtime/pprof: disable test on Leopard 64-bit.
+* runtime: add Compiler,
+	fix windows/amd64 exception handler (thanks Alex Brainman),
+	inline calls to notok,
+	move runtime.write back to C,
+	print error on receipt of signal on non-Go thread,
+	remove unused runtime·signame and runtime·newError,
+	try extending arena size in 32-bit allocator (thanks Rémy Oudompheng),
+	wait for main goroutine before setting GOMAXPROCS (thanks Rémy Oudompheng).
+* strconv: add table-based isPrint, remove dependence on bytes, unicode, and strings.
+* sync/atomic: disable store and load test on a single processor machine (thanks Mikio Hara).
+* syscall: fix mkall.sh, mksyscall_linux.pl, and regen for Linux/ARM (thanks Shenghou Ma).
+* test/run: use all available cores on ARM system (thanks Shenghou Ma).
+* test: actually run them on windows (thanks Alex Brainman),
+	add inherited interface test to ddd.go,
+	enable method expression tests in ddd.go,
+	invoke go command in run.go,
+	match gccgo error messages for bug388.go,
+	skip . files in directory.
+* testing: do not print 'no tests' when there are examples.
+* time: during short test, do not bother tickers take longer than expected (thanks Shenghou Ma),
+	mention receiver in Unix, UnixNano docs.
+* unicode/utf16: remove dependence on package unicode.
+* unicode/utf8: remove dependence on unicode.
+* windows: make background of gopher icon transparent (thanks Volker Dobler).
+</pre>
+
 <h2 id="2012-03-04">2012-03-04</h2>
 
 <pre>
diff --git a/doc/docs.html b/doc/docs.html
index 52ec28edb..709c08152 100644
--- a/doc/docs.html
+++ b/doc/docs.html
@@ -31,6 +31,8 @@ libraries.
 
 <h2 id="learning">Learning Go</h2>
 
+<img class="gopher" src="/doc/gopher/doc.png"/>
+
 <h3 id="go_tour"><a href="http://tour.golang.org/">A Tour of Go</a></h3>
 <p>
 An interactive introduction to Go in three sections.
@@ -68,13 +70,26 @@ Answers to common questions about Go.
 <h3 id="wiki"><a href="http://code.google.com/p/go-wiki/wiki">Go Language Community Wiki</a></h3>
 <p>A wiki maintained by the Go community.</p>
 
+<h2 id="go1">Go version 1</h2>
+
+<h3 id="go1notes"><a href="/doc/go1.html">Go 1 Release Notes</a></h3>
+<p>
+A guide for updating your code to work with Go 1.
+</p>
+
+<h3 id="go1compat"><a href="/doc/go1compat.html">Go 1 and the Future of Go Programs</a></h3>
+<p>
+What Go 1 defines and the backwards-compatibility guarantees one can expect as
+Go 1 matures.
+</p>
+
 <h2 id="articles">Go Articles</h2>
 
 <h3 id="blog"><a href="http://blog.golang.org/">The Go Blog</a></h3>
 <p>The official blog of the Go project, featuring news and in-depth articles by
 the Go team and guests.</p>
 
-<h3>Codewalks</h3>
+<h4>Codewalks</h4>
 <p>
 Guided tours of Go programs. 
 </p>
@@ -85,38 +100,38 @@ Guided tours of Go programs.
 <li><a href="/doc/articles/wiki/">Writing Web Applications</a> - building a simple web application.</li>
 </ul>
 
-<h3>Language</h3>
-
+<h4>Language</h4>
 <ul>
 <li><a href="http://blog.golang.org/2010/04/json-rpc-tale-of-interfaces.html">JSON-RPC: a tale of interfaces</a></li>
-<li><a href="http://blog.golang.org/2010/07/gos-declaration-syntax.html">Go's Declaration Syntax</a></li>
+<li><a href="/doc/articles/gos_declaration_syntax.html">Go's Declaration Syntax</a></li>
 <li><a href="/doc/articles/defer_panic_recover.html">Defer, Panic, and Recover</a></li>
-<li><a href="http://blog.golang.org/2010/09/go-concurrency-patterns-timing-out-and.html">Go Concurrency Patterns: Timing out, moving on</a></li>
+<li><a href="/doc/articles/concurrency_patterns.html">Go Concurrency Patterns: Timing out, moving on</a></li>
 <li><a href="/doc/articles/slices_usage_and_internals.html">Go Slices: usage and internals</a></li>
 <li><a href="http://blog.golang.org/2011/05/gif-decoder-exercise-in-go-interfaces.html">A GIF decoder: an exercise in Go interfaces</a></li>
 <li><a href="/doc/articles/error_handling.html">Error Handling and Go</a></li>
 </ul>
 
-<h3>Packages</h3>
-
+<h4>Packages</h4>
 <ul>
-<li><a href="http://blog.golang.org/2011/01/json-and-go.html">JSON and Go</a> - using the <a href="/pkg/encoding/json/">json</a> package.</li>
-<li><a href="http://blog.golang.org/2011/03/gobs-of-data.html">Gobs of data</a> - the design and use of the <a href="/pkg/encoding/gob/">gob</a> package.</li>
+<li><a href="/doc/articles/json_and_go.html">JSON and Go</a> - using the <a href="/pkg/encoding/json/">json</a> package.</li>
+<li><a href="/doc/articles/gobs_of_data.html">Gobs of data</a> - the design and use of the <a href="/pkg/encoding/gob/">gob</a> package.</li>
 <li><a href="/doc/articles/laws_of_reflection.html">The Laws of Reflection</a> - the fundamentals of the <a href="/pkg/reflect/">reflect</a> package.</li>
 <li><a href="http://blog.golang.org/2011/09/go-image-package.html">The Go image package</a> - the fundamentals of the <a href="/pkg/image/">image</a> package.</li>
-<li><a href="http://blog.golang.org/2011/09/go-imagedraw-package.html">The Go image/draw package</a> - the fundamentals of the <a href="/pkg/image/draw/">image/draw</a> package.</li>
+<li><a href="/doc/articles/image_draw.html">The Go image/draw package</a> - the fundamentals of the <a href="/pkg/image/draw/">image/draw</a> package.</li>
 </ul>
 
-<h3>Tools</h3>
-
+<h4>Tools</h4>
 <ul>
-<li><a href="http://blog.golang.org/2011/03/c-go-cgo.html">C? Go? Cgo!</a> - linking against C code with <a href="/cmd/cgo/">cgo</a>.</li>
-<li><a href="http://blog.golang.org/2011/03/godoc-documenting-go-code.html">Godoc: documenting Go code</a> - writing good documentation for <a href="/cmd/godoc/">godoc</a>.</li>
+<li><a href="/doc/articles/go_command.html">About the Go command</a> - why we wrote it, what it is, what it's not, and how to use it.</li>
+<li><a href="/doc/articles/c_go_cgo.html">C? Go? Cgo!</a> - linking against C code with <a href="/cmd/cgo/">cgo</a>.</li>
+<li><a href="/doc/articles/godoc_documenting_go_code.html">Godoc: documenting Go code</a> - writing good documentation for <a href="/cmd/godoc/">godoc</a>.</li>
 <li><a href="http://blog.golang.org/2011/06/profiling-go-programs.html">Profiling Go Programs</a></li>
 </ul>
 
 <h2 id="talks">Talks</h2>
 
+<img class="gopher" src="/doc/gopher/talks.png"/>
+
 <p>
 The talks marked with a red asterisk (<font color="red">*</font>) were written
 before Go 1 and contain some examples that are no longer correct, but they are
@@ -162,7 +177,7 @@ the simple example of an URL shortening service.
 See the <a href="http://wh3rd.net/practical-go/">presentation slides</a>.
 </p>
 
-<h3 id="talks_more">More</h3>
+<h4 id="talks_more">More</h4>
 <p>
 See the <a href="http://code.google.com/p/go-wiki/wiki/GoTalks">GoTalks
 page</a> at the <a href="http://code.google.com/p/go-wiki/wiki">Go Wiki</a> for
@@ -179,6 +194,8 @@ documentation.
 
 <h2 id="community">The Go Community</h2>
 
+<img class="gopher" src="/doc/gopher/project.png"/>
+
 <h3 id="mailinglist"><a href="http://groups.google.com/group/golang-nuts">Go Nuts Mailing List</a></h3>
 <p>The <a href="http://groups.google.com/group/golang-nuts">golang-nuts</a> 
 mailing list is for general Go discussion.</p>
diff --git a/doc/effective_go.html b/doc/effective_go.html
index b9e62b6db..80b285183 100644
--- a/doc/effective_go.html
+++ b/doc/effective_go.html
@@ -1,11 +1,7 @@
 <!--{
-	"Title": "Effective Go"
+	"Title": "Effective Go",
+	"Template": true
 }-->
-<!--
-  DO NOT EDIT: created by
-    tmpltohtml effective_go.tmpl
--->
-
 
 <h2 id="introduction">Introduction</h2>
 
@@ -775,7 +771,7 @@ error code secreted away in a volatile location.
 In Go, <code>Write</code>
 can return a count <i>and</i> an error: &ldquo;Yes, you wrote some
 bytes but not all of them because you filled the device&rdquo;.
-The signature of <code>*File.Write</code> in package <code>os</code> is:
+The signature of <code>File.Write</code> in package <code>os</code> is:
 </p>
 
 <pre>
@@ -1331,9 +1327,9 @@ values of different types.
 The key can be of any type for which the equality operator is defined,
 such as integers,
 floating point and complex numbers,
-strings, pointers, and interfaces (as long as the dynamic type
-supports equality).  Structs, arrays and slices cannot be used as map keys,
-because equality is not defined on those types.
+strings, pointers, interfaces (as long as the dynamic type
+supports equality), structs and arrays. Slices cannot be used as map keys,
+because equality is not defined on them.
 Like slices, maps are a reference type. If you pass a map to a function
 that changes the contents of the map, the changes will be visible
 in the caller.
@@ -1456,7 +1452,7 @@ fmt.Println(fmt.Sprint("Hello ", 23))
 </pre>
 <p>
 As mentioned in
-the <a href="http://code.google.com/p/go-tour/">Tour</a>, <code>fmt.Fprint</code>
+the <a href="http://tour.golang.org">Tour</a>, <code>fmt.Fprint</code>
 and friends take as a first argument any object
 that implements the <code>io.Writer</code> interface; the variables <code>os.Stdout</code>
 and <code>os.Stderr</code> are familiar instances.
@@ -1693,47 +1689,13 @@ enumerator.  Since <code>iota</code> can be part of an expression and
 expressions can be implicitly repeated, it is easy to build intricate
 sets of values.
 </p>
-<pre><!--{{code "progs/eff_bytesize.go" `/^type ByteSize/` `/^\)/`}}
--->type ByteSize float64
-
-const (
-    _           = iota // ignore first value by assigning to blank identifier
-    KB ByteSize = 1 &lt;&lt; (10 * iota)
-    MB
-    GB
-    TB
-    PB
-    EB
-    ZB
-    YB
-)</pre>
+{{code "/doc/progs/eff_bytesize.go" `/^type ByteSize/` `/^\)/`}}
 <p>
 The ability to attach a method such as <code>String</code> to a
 type makes it possible for such values to format themselves
 automatically for printing, even as part of a general type.
 </p>
-<pre><!--{{code "progs/eff_bytesize.go" `/^func.*ByteSize.*String/` `/^}/`}}
--->func (b ByteSize) String() string {
-    switch {
-    case b &gt;= YB:
-        return fmt.Sprintf(&#34;%.2fYB&#34;, float64(b/YB))
-    case b &gt;= ZB:
-        return fmt.Sprintf(&#34;%.2fZB&#34;, float64(b/ZB))
-    case b &gt;= EB:
-        return fmt.Sprintf(&#34;%.2fEB&#34;, float64(b/EB))
-    case b &gt;= PB:
-        return fmt.Sprintf(&#34;%.2fPB&#34;, float64(b/PB))
-    case b &gt;= TB:
-        return fmt.Sprintf(&#34;%.2fTB&#34;, float64(b/TB))
-    case b &gt;= GB:
-        return fmt.Sprintf(&#34;%.2fGB&#34;, float64(b/GB))
-    case b &gt;= MB:
-        return fmt.Sprintf(&#34;%.2fMB&#34;, float64(b/MB))
-    case b &gt;= KB:
-        return fmt.Sprintf(&#34;%.2fKB&#34;, float64(b/KB))
-    }
-    return fmt.Sprintf(&#34;%.2fB&#34;, float64(b))
-}</pre>
+{{code "/doc/progs/eff_bytesize.go" `/^func.*ByteSize.*String/` `/^}/`}}
 <p>
 (The <code>float64</code> conversions prevent <code>Sprintf</code> 
 from recurring back through the <code>String</code> method for 
@@ -1761,10 +1723,7 @@ var (
 <p>
 Finally, each source file can define its own niladic <code>init</code> function to
 set up whatever state is required.  (Actually each file can have multiple
-<code>init</code> functions.) The only restriction is that, although
-goroutines can be launched during initialization, they will not begin
-execution until it completes; initialization always runs as a single thread
-of execution.
+<code>init</code> functions.)
 And finally means finally: <code>init</code> is called after all the
 variable declarations in the package have evaluated their initializers,
 and those are evaluated only after all the imported packages have been
@@ -1882,32 +1841,7 @@ by the routines in package <code>sort</code> if it implements
 and it could also have a custom formatter.
 In this contrived example <code>Sequence</code> satisfies both.
 </p>
-<pre><!--{{code "progs/eff_sequence.go" `/^type/` "$"}}
--->type Sequence []int
-
-// Methods required by sort.Interface.
-func (s Sequence) Len() int {
-    return len(s)
-}
-func (s Sequence) Less(i, j int) bool {
-    return s[i] &lt; s[j]
-}
-func (s Sequence) Swap(i, j int) {
-    s[i], s[j] = s[j], s[i]
-}
-
-// Method for printing - sorts the elements before printing.
-func (s Sequence) String() string {
-    sort.Sort(s)
-    str := &#34;[&#34;
-    for i, elem := range s {
-        if i &gt; 0 {
-            str += &#34; &#34;
-        }
-        str += fmt.Sprint(elem)
-    }
-    return str + &#34;]&#34;
-}</pre>
+{{code "/doc/progs/eff_sequence.go" `/^type/` "$"}}
 
 <h3 id="conversions">Conversions</h3>
 
@@ -1986,7 +1920,7 @@ A similar approach allows the streaming cipher algorithms
 in the various <code>crypto</code> packages to be
 separated from the block ciphers they chain together.
 The <code>Block</code> interface
-in the <code>crypto/cipher</code>package specifies the
+in the <code>crypto/cipher</code> package specifies the
 behavior of a block cipher, which provides encryption
 of a single block of data.
 Then, by analogy with the <code>bufio</code> package,
@@ -2397,7 +2331,7 @@ it can also be seen as a type-safe generalization of Unix pipes.
 They're called <em>goroutines</em> because the existing
 terms&mdash;threads, coroutines, processes, and so on&mdash;convey
 inaccurate connotations.  A goroutine has a simple model: it is a
-function executing in parallel with other goroutines in the same
+function executing concurrently with other goroutines in the same
 address space.  It is lightweight, costing little more than the
 allocation of stack space.
 And the stacks start small, so they are cheap, and grow
@@ -2418,12 +2352,12 @@ exits, silently.  (The effect is similar to the Unix shell's
 background.)
 </p>
 <pre>
-go list.Sort()  // run list.Sort in parallel; don't wait for it. 
+go list.Sort()  // run list.Sort concurrently; don't wait for it. 
 </pre>
 <p>
 A function literal can be handy in a goroutine invocation.
 <pre>
-func Announce(message string, delay int64) {
+func Announce(message string, delay time.Duration) {
     go func() {
         time.Sleep(delay)
         fmt.Println(message)
@@ -2763,8 +2697,8 @@ it is much more informative than the plain
 <p>
 When feasible, error strings should identify their origin, such as by having
 a prefix naming the package that generated the error.  For example, in package
-image, the string representation for a decoding error due to an unknown format
-is "image: unknown format".
+<code>image</code>, the string representation for a decoding error due to an
+unknown format is "image: unknown format".
 </p>
 
 <p>
@@ -2777,11 +2711,11 @@ field for recoverable failures.
 
 <pre>
 for try := 0; try &lt; 2; try++ {
-    file, err = os.Open(filename)
+    file, err = os.Create(filename)
     if err == nil {
         return
     }
-    if e, ok := err.(*os.PathError); ok &amp;&amp; e.Err == os.ENOSPC {
+    if e, ok := err.(*os.PathError); ok &amp;&amp; e.Err == syscall.ENOSPC {
         deleteTempFiles()  // Recover some space.
         continue
     }
@@ -3013,53 +2947,7 @@ for instance, a URL, saving you typing the URL into the phone's tiny keyboard.
 Here's the complete program.
 An explanation follows.
 </p>
-<pre><!--{{code "progs/eff_qr.go"}}
--->package main
-
-import (
-    &#34;flag&#34;
-    &#34;log&#34;
-    &#34;net/http&#34;
-    &#34;text/template&#34;
-)
-
-var addr = flag.String(&#34;addr&#34;, &#34;:1718&#34;, &#34;http service address&#34;) // Q=17, R=18
-
-var templ = template.Must(template.New(&#34;qr&#34;).Parse(templateStr))
-
-func main() {
-    flag.Parse()
-    http.Handle(&#34;/&#34;, http.HandlerFunc(QR))
-    err := http.ListenAndServe(*addr, nil)
-    if err != nil {
-        log.Fatal(&#34;ListenAndServe:&#34;, err)
-    }
-}
-
-func QR(w http.ResponseWriter, req *http.Request) {
-    templ.Execute(w, req.FormValue(&#34;s&#34;))
-}
-
-const templateStr = `
-&lt;html&gt;
-&lt;head&gt;
-&lt;title&gt;QR Link Generator&lt;/title&gt;
-&lt;/head&gt;
-&lt;body&gt;
-{{if .}}
-&lt;img src=&#34;http://chart.apis.google.com/chart?chs=300x300&amp;cht=qr&amp;choe=UTF-8&amp;chl={{urlquery .}}&#34; /&gt;
-&lt;br&gt;
-{{html .}}
-&lt;br&gt;
-&lt;br&gt;
-{{end}}
-&lt;form action=&#34;/&#34; name=f method=&#34;GET&#34;&gt;&lt;input maxLength=1024 size=70
-name=s value=&#34;&#34; title=&#34;Text to QR Encode&#34;&gt;&lt;input type=submit
-value=&#34;Show QR&#34; name=qr&gt;
-&lt;/form&gt;
-&lt;/body&gt;
-&lt;/html&gt;
-`</pre>
+{{code "/doc/progs/eff_qr.go"}}
 <p>
 The pieces up to <code>main</code> should be easy to follow.
 The one flag sets a default HTTP port for our server.  The template
@@ -3085,19 +2973,19 @@ from data items passed to <code>templ.Execute</code>, in this case the
 form value.  
 Within the template text (<code>templateStr</code>),
 double-brace-delimited pieces denote template actions.
-The piece from <code>{{if .}}</code>
-to <code>{{end}}</code> executes only if the value of the current data item, called <code>.</code> (dot),
+The piece from <code>{{html "{{if .}}"}}</code>
+to <code>{{html "{{end}}"}}</code> executes only if the value of the current data item, called <code>.</code> (dot),
 is non-empty.
 That is, when the string is empty, this piece of the template is suppressed.
 </p>
 <p>
-The snippet <code>{{urlquery .}}</code> says to process the data with the function
+The snippet <code>{{html "{{urlquery .}}"}}</code> says to process the data with the function
 <code>urlquery</code>, which sanitizes the query string
 for safe display on the web page.
 </p>
 <p>
 The rest of the template string is just the HTML to show when the page loads.
-If this is too quick an explanation, see the <a href="/pkg/template/">documentation</a>
+If this is too quick an explanation, see the <a href="/pkg/text/template/">documentation</a>
 for the template package for a more thorough discussion.
 </p>
 <p>
diff --git a/doc/effective_go.tmpl b/doc/effective_go.tmpl
deleted file mode 100644
index 9a0333dba..000000000
--- a/doc/effective_go.tmpl
+++ /dev/null
@@ -1,3011 +0,0 @@
-<!--{
-	"Title": "Effective Go"
-}-->
-{{donotedit}}
-
-<h2 id="introduction">Introduction</h2>
-
-<p>
-Go is a new language.  Although it borrows ideas from
-existing languages,
-it has unusual properties that make effective Go programs
-different in character from programs written in its relatives.
-A straightforward translation of a C++ or Java program into Go
-is unlikely to produce a satisfactory result&mdash;Java programs
-are written in Java, not Go.
-On the other hand, thinking about the problem from a Go
-perspective could produce a successful but quite different
-program.
-In other words,
-to write Go well, it's important to understand its properties
-and idioms.
-It's also important to know the established conventions for
-programming in Go, such as naming, formatting, program
-construction, and so on, so that programs you write
-will be easy for other Go programmers to understand.
-</p>
-
-<p>
-This document gives tips for writing clear, idiomatic Go code.
-It augments the <a href="/ref/spec">language specification</a>,
-the <a href="http://tour.golang.org/">Tour of Go</a>,
-and <a href="/doc/code.html">How to Write Go Code</a>,
-all of which you
-should read first.
-</p>
-
-<h3 id="examples">Examples</h3>
-
-<p>
-The <a href="/src/pkg/">Go package sources</a>
-are intended to serve not
-only as the core library but also as examples of how to
-use the language.
-If you have a question about how to approach a problem or how something
-might be implemented, they can provide answers, ideas and
-background.
-</p>
-
-
-<h2 id="formatting">Formatting</h2>
-
-<p>
-Formatting issues are the most contentious
-but the least consequential.
-People can adapt to different formatting styles
-but it's better if they don't have to, and
-less time is devoted to the topic
-if everyone adheres to the same style.
-The problem is how to approach this Utopia without a long
-prescriptive style guide.
-</p>
-
-<p>
-With Go we take an unusual
-approach and let the machine
-take care of most formatting issues.
-The <code>gofmt</code> program
-(also available as <code>go fmt</code>, which
-operates at the package level rather than source file level)
-reads a Go program
-and emits the source in a standard style of indentation
-and vertical alignment, retaining and if necessary
-reformatting comments.
-If you want to know how to handle some new layout
-situation, run <code>gofmt</code>; if the answer doesn't
-seem right, rearrange your program (or file a bug about <code>gofmt</code>),
-don't work around it.
-</p>
-
-<p>
-As an example, there's no need to spend time lining up
-the comments on the fields of a structure.
-<code>Gofmt</code> will do that for you.  Given the
-declaration
-</p>
-
-<pre>
-type T struct {
-    name string // name of the object
-    value int // its value
-}
-</pre>
-
-<p>
-<code>gofmt</code> will line up the columns:
-</p>
-
-<pre>
-type T struct {
-    name    string // name of the object
-    value   int    // its value
-}
-</pre>
-
-<p>
-All Go code in the standard packages has been formatted with <code>gofmt</code>.
-</p>
-
-
-<p>
-Some formatting details remain.  Very briefly,
-</p>
-
-<dl>
-    <dt>Indentation</dt>
-    <dd>We use tabs for indentation and <code>gofmt</code> emits them by default.
-    Use spaces only if you must.
-    </dd>
-    <dt>Line length</dt>
-    <dd>
-    Go has no line length limit.  Don't worry about overflowing a punched card.
-    If a line feels too long, wrap it and indent with an extra tab.
-    </dd>
-    <dt>Parentheses</dt>
-    <dd>
-    Go needs fewer parentheses: control structures (<code>if</code>,
-    <code>for</code>, <code>switch</code>) do not have parentheses in
-    their syntax.
-    Also, the operator precedence hierarchy is shorter and clearer, so
-<pre>
-x&lt;&lt;8 + y&lt;&lt;16
-</pre>
-    means what the spacing implies.
-    </dd>
-</dl>
-
-<h2 id="commentary">Commentary</h2>
-
-<p>
-Go provides C-style <code>/* */</code> block comments
-and C++-style <code>//</code> line comments.
-Line comments are the norm;
-block comments appear mostly as package comments and
-are also useful to disable large swaths of code.
-</p>
-
-<p>
-The program—and web server—<code>godoc</code> processes
-Go source files to extract documentation about the contents of the
-package.
-Comments that appear before top-level declarations, with no intervening newlines,
-are extracted along with the declaration to serve as explanatory text for the item.
-The nature and style of these comments determines the
-quality of the documentation <code>godoc</code> produces.
-</p>
-
-<p>
-Every package should have a <i>package comment</i>, a block
-comment preceding the package clause.
-For multi-file packages, the package comment only needs to be
-present in one file, and any one will do.
-The package comment should introduce the package and
-provide information relevant to the package as a whole.
-It will appear first on the <code>godoc</code> page and
-should set up the detailed documentation that follows.
-</p>
-
-<pre>
-/*
-    Package regexp implements a simple library for
-    regular expressions.
-
-    The syntax of the regular expressions accepted is:
-
-    regexp:
-        concatenation { '|' concatenation }
-    concatenation:
-        { closure }
-    closure:
-        term [ '*' | '+' | '?' ]
-    term:
-        '^'
-        '$'
-        '.'
-        character
-        '[' [ '^' ] character-ranges ']'
-        '(' regexp ')'
-*/
-package regexp
-</pre>
-
-<p>
-If the package is simple, the package comment can be brief.
-</p>
-
-<pre>
-// Package path implements utility routines for
-// manipulating slash-separated filename paths.
-</pre>
-
-<p>
-Comments do not need extra formatting such as banners of stars.
-The generated output may not even be presented in a fixed-width font, so don't depend
-on spacing for alignment&mdash;<code>godoc</code>, like <code>gofmt</code>,
-takes care of that.
-The comments are uninterpreted plain text, so HTML and other
-annotations such as <code>_this_</code> will reproduce <i>verbatim</i> and should
-not be used.
-Depending on the context, <code>godoc</code> might not even
-reformat comments, so make sure they look good straight up:
-use correct spelling, punctuation, and sentence structure,
-fold long lines, and so on.
-</p>
-
-<p>
-Inside a package, any comment immediately preceding a top-level declaration
-serves as a <i>doc comment</i> for that declaration.
-Every exported (capitalized) name in a program should
-have a doc comment.
-</p>
-
-<p>
-Doc comments work best as complete sentences, which allow
-a wide variety of automated presentations.
-The first sentence should be a one-sentence summary that
-starts with the name being declared.
-</p>
-
-<pre>
-// Compile parses a regular expression and returns, if successful, a Regexp
-// object that can be used to match against text.
-func Compile(str string) (regexp *Regexp, err error) {
-</pre>
-
-<p>
-Go's declaration syntax allows grouping of declarations.
-A single doc comment can introduce a group of related constants or variables.
-Since the whole declaration is presented, such a comment can often be perfunctory.
-</p>
-
-<pre>
-// Error codes returned by failures to parse an expression.
-var (
-    ErrInternal      = errors.New("regexp: internal error")
-    ErrUnmatchedLpar = errors.New("regexp: unmatched '('")
-    ErrUnmatchedRpar = errors.New("regexp: unmatched ')'")
-    ...
-)
-</pre>
-
-<p>
-Even for private names, grouping can also indicate relationships between items,
-such as the fact that a set of variables is protected by a mutex.
-</p>
-
-<pre>
-var (
-    countLock   sync.Mutex
-    inputCount  uint32
-    outputCount uint32
-    errorCount  uint32
-)
-</pre>
-
-<h2 id="names">Names</h2>
-
-<p>
-Names are as important in Go as in any other language.
-In some cases they even have semantic effect: for instance,
-the visibility of a name outside a package is determined by whether its
-first character is upper case.
-It's therefore worth spending a little time talking about naming conventions
-in Go programs.
-</p>
-
-
-<h3 id="package-names">Package names</h3>
-
-<p>
-When a package is imported, the package name becomes an accessor for the
-contents.  After
-</p>
-
-<pre>
-import "bytes"
-</pre>
-
-<p>
-the importing package can talk about <code>bytes.Buffer</code>.  It's
-helpful if everyone using the package can use the same name to refer to
-its contents, which implies that the package name should be good:
-short, concise, evocative.  By convention, packages are given
-lower case, single-word names; there should be no need for underscores
-or mixedCaps.
-Err on the side of brevity, since everyone using your
-package will be typing that name.
-And don't worry about collisions <i>a priori</i>.
-The package name is only the default name for imports; it need not be unique
-across all source code, and in the rare case of a collision the
-importing package can choose a different name to use locally.
-In any case, confusion is rare because the file name in the import
-determines just which package is being used.
-</p>
-
-<p>
-Another convention is that the package name is the base name of
-its source directory;
-the package in <code>src/pkg/encoding/base64</code>
-is imported as <code>"encoding/base64"</code> but has name <code>base64</code>,
-not <code>encoding_base64</code> and not <code>encodingBase64</code>.
-</p>
-
-<p>
-The importer of a package will use the name to refer to its contents
-(the <code>import .</code> notation is intended mostly for tests and other
-unusual situations and should be avoided unless necessary),
-so exported names in the package can use that fact
-to avoid stutter.
-For instance, the buffered reader type in the <code>bufio</code> package is called <code>Reader</code>,
-not <code>BufReader</code>, because users see it as <code>bufio.Reader</code>,
-which is a clear, concise name.
-Moreover,
-because imported entities are always addressed with their package name, <code>bufio.Reader</code>
-does not conflict with <code>io.Reader</code>.
-Similarly, the function to make new instances of <code>ring.Ring</code>&mdash;which
-is the definition of a <em>constructor</em> in Go&mdash;would
-normally be called <code>NewRing</code>, but since
-<code>Ring</code> is the only type exported by the package, and since the
-package is called <code>ring</code>, it's called just <code>New</code>,
-which clients of the package see as <code>ring.New</code>.
-Use the package structure to help you choose good names.
-</p>
-
-<p>
-Another short example is <code>once.Do</code>;
-<code>once.Do(setup)</code> reads well and would not be improved by
-writing <code>once.DoOrWaitUntilDone(setup)</code>.
-Long names don't automatically make things more readable.
-If the name represents something intricate or subtle, it's usually better
-to write a helpful doc comment than to attempt to put all the information
-into the name.
-</p>
-
-<h3 id="Getters">Getters</h3>
-
-<p>
-Go doesn't provide automatic support for getters and setters.
-There's nothing wrong with providing getters and setters yourself,
-and it's often appropriate to do so, but it's neither idiomatic nor necessary
-to put <code>Get</code> into the getter's name.  If you have a field called
-<code>owner</code> (lower case, unexported), the getter method should be
-called <code>Owner</code> (upper case, exported), not <code>GetOwner</code>.
-The use of upper-case names for export provides the hook to discriminate
-the field from the method.
-A setter function, if needed, will likely be called <code>SetOwner</code>.
-Both names read well in practice:
-</p>
-<pre>
-owner := obj.Owner()
-if owner != user {
-    obj.SetOwner(user)
-}
-</pre>
-
-<h3 id="interface-names">Interface names</h3>
-
-<p>
-By convention, one-method interfaces are named by
-the method name plus the -er suffix: <code>Reader</code>,
-<code>Writer</code>, <code>Formatter</code> etc.
-</p>
-
-<p>
-There are a number of such names and it's productive to honor them and the function
-names they capture.
-<code>Read</code>, <code>Write</code>, <code>Close</code>, <code>Flush</code>,
-<code>String</code> and so on have
-canonical signatures and meanings.  To avoid confusion,
-don't give your method one of those names unless it
-has the same signature and meaning.
-Conversely, if your type implements a method with the
-same meaning as a method on a well-known type,
-give it the same name and signature;
-call your string-converter method <code>String</code> not <code>ToString</code>.
-</p>
-
-<h3 id="mixed-caps">MixedCaps</h3>
-
-<p>
-Finally, the convention in Go is to use <code>MixedCaps</code>
-or <code>mixedCaps</code> rather than underscores to write
-multiword names.
-</p>
-
-<h2 id="semicolons">Semicolons</h2>
-
-<p>
-Like C, Go's formal grammar uses semicolons to terminate statements;
-unlike C, those semicolons do not appear in the source.
-Instead the lexer uses a simple rule to insert semicolons automatically
-as it scans, so the input text is mostly free of them.
-</p>
-
-<p>
-The rule is this. If the last token before a newline is an identifier
-(which includes words like <code>int</code> and <code>float64</code>),
-a basic literal such as a number or string constant, or one of the
-tokens
-</p>
-<pre>
-break continue fallthrough return ++ -- ) }
-</pre>
-<p>
-the lexer always inserts a semicolon after the token.
-This could be summarized as, &ldquo;if the newline comes
-after a token that could end a statement, insert a semicolon&rdquo;.
-</p>
-
-<p>
-A semicolon can also be omitted immediately before a closing brace,
-so a statement such as
-</p>
-<pre>
-    go func() { for { dst &lt;- &lt;-src } }()
-</pre>
-<p>
-needs no semicolons.
-Idiomatic Go programs have semicolons only in places such as
-<code>for</code> loop clauses, to separate the initializer, condition, and
-continuation elements.  They are also necessary to separate multiple
-statements on a line, should you write code that way.
-</p>
-
-<p>
-One caveat. You should never put the opening brace of a
-control structure (<code>if</code>, <code>for</code>, <code>switch</code>,
-or <code>select</code>) on the next line.  If you do, a semicolon
-will be inserted before the brace, which could cause unwanted
-effects.  Write them like this
-</p>
-
-<pre>
-if i &lt; f() {
-    g()
-}
-</pre>
-<p>
-not like this
-</p>
-<pre>
-if i &lt; f()  // wrong!
-{           // wrong!
-    g()
-}
-</pre>
-
-
-<h2 id="control-structures">Control structures</h2>
-
-<p>
-The control structures of Go are related to those of C but differ
-in important ways.
-There is no <code>do</code> or <code>while</code> loop, only a
-slightly generalized
-<code>for</code>;
-<code>switch</code> is more flexible;
-<code>if</code> and <code>switch</code> accept an optional
-initialization statement like that of <code>for</code>;
-and there are new control structures including a type switch and a
-multiway communications multiplexer, <code>select</code>.
-The syntax is also slightly different:
-there are no parentheses
-and the bodies must always be brace-delimited.
-</p>
-
-<h3 id="if">If</h3>
-
-<p>
-In Go a simple <code>if</code> looks like this:
-</p>
-<pre>
-if x &gt; 0 {
-    return y
-}
-</pre>
-
-<p>
-Mandatory braces encourage writing simple <code>if</code> statements
-on multiple lines.  It's good style to do so anyway,
-especially when the body contains a control statement such as a
-<code>return</code> or <code>break</code>.
-</p>
-
-<p>
-Since <code>if</code> and <code>switch</code> accept an initialization
-statement, it's common to see one used to set up a local variable.
-</p>
-
-<pre>
-if err := file.Chmod(0664); err != nil {
-    log.Print(err)
-    return err
-}
-</pre>
-
-<p id="else">
-In the Go libraries, you'll find that
-when an <code>if</code> statement doesn't flow into the next statement—that is,
-the body ends in <code>break</code>, <code>continue</code>,
-<code>goto</code>, or <code>return</code>—the unnecessary
-<code>else</code> is omitted.
-</p>
-
-<pre>
-f, err := os.Open(name)
-if err != nil {
-    return err
-}
-codeUsing(f)
-</pre>
-
-<p>
-This is an example of a common situation where code must guard against a
-sequence of error conditions.  The code reads well if the
-successful flow of control runs down the page, eliminating error cases
-as they arise.  Since error cases tend to end in <code>return</code>
-statements, the resulting code needs no <code>else</code> statements.
-</p>
-
-<pre>
-f, err := os.Open(name)
-if err != nil {
-    return err
-}
-d, err := f.Stat()
-if err != nil {
-    f.Close()
-    return err
-}
-codeUsing(f, d)
-</pre>
-
-
-<h3 id="redeclaration">Redeclaration</h3>
-
-<p>
-An aside: The last example in the previous section demonstrates a detail of how the
-<code>:=</code> short declaration form works.
-The declaration that calls <code>os.Open</code> reads,
-</p>
-
-<pre>
-f, err := os.Open(name)
-</pre>
-
-<p>
-This statement declares two variables, <code>f</code> and <code>err</code>.
-A few lines later, the call to <code>f.Stat</code> reads,
-</p>
-
-<pre>
-d, err := f.Stat()
-</pre>
-
-<p>
-which looks as if it declares <code>d</code> and <code>err</code>.
-Notice, though, that <code>err</code> appears in both statements.
-This duplication is legal: <code>err</code> is declared by the first statement,
-but only <em>re-assigned</em> in the second.
-This means that the call to <code>f.Stat</code> uses the existing
-<code>err</code> variable declared above, and just gives it a new value.
-</p>
-
-<p>
-In a <code>:=</code> declaration a variable <code>v</code> may appear even
-if it has already been declared, provided:
-</p>
-
-<ul>
-<li>this declaration is in the same scope as the existing declaration of <code>v</code>
-(if <code>v</code> is already declared in an outer scope, the declaration will create a new variable),</li>
-<li>the corresponding value in the initialization is assignable to <code>v</code>, and</li>
-<li>there is at least one other variable in the declaration that is being declared anew.</li>
-</ul>
-
-<p>
-This unusual property is pure pragmatism,
-making it easy to use a single <code>err</code> value, for example,
-in a long <code>if-else</code> chain.
-You'll see it used often.
-</p>
-
-<h3 id="for">For</h3>
-
-<p>
-The Go <code>for</code> loop is similar to&mdash;but not the same as&mdash;C's.
-It unifies <code>for</code>
-and <code>while</code> and there is no <code>do-while</code>.
-There are three forms, only one of which has semicolons.
-</p>
-<pre>
-// Like a C for
-for init; condition; post { }
-
-// Like a C while
-for condition { }
-
-// Like a C for(;;)
-for { }
-</pre>
-
-<p>
-Short declarations make it easy to declare the index variable right in the loop.
-</p>
-<pre>
-sum := 0
-for i := 0; i &lt; 10; i++ {
-    sum += i
-}
-</pre>
-
-<p>
-If you're looping over an array, slice, string, or map,
-or reading from a channel, a <code>range</code> clause can
-manage the loop.
-</p>
-<pre>
-var m map[string]int
-sum := 0
-for _, value := range m {  // key is unused
-    sum += value
-}
-</pre>
-
-<p>
-For strings, the <code>range</code> does more work for you, breaking out individual
-Unicode characters by parsing the UTF-8.
-Erroneous encodings consume one byte and produce the
-replacement rune U+FFFD. The loop
-</p>
-<pre>
-for pos, char := range "日本語" {
-    fmt.Printf("character %c starts at byte position %d\n", char, pos)
-}
-</pre>
-<p>
-prints
-</p>
-<pre>
-character 日 starts at byte position 0
-character 本 starts at byte position 3
-character 語 starts at byte position 6
-</pre>
-
-<p>
-Finally, Go has no comma operator and <code>++</code> and <code>--</code>
-are statements not expressions.
-Thus if you want to run multiple variables in a <code>for</code>
-you should use parallel assignment.
-</p>
-<pre>
-// Reverse a
-for i, j := 0, len(a)-1; i &lt; j; i, j = i+1, j-1 {
-    a[i], a[j] = a[j], a[i]
-}
-</pre>
-
-<h3 id="switch">Switch</h3>
-
-<p>
-Go's <code>switch</code> is more general than C's.
-The expressions need not be constants or even integers,
-the cases are evaluated top to bottom until a match is found,
-and if the <code>switch</code> has no expression it switches on
-<code>true</code>.
-It's therefore possible&mdash;and idiomatic&mdash;to write an
-<code>if</code>-<code>else</code>-<code>if</code>-<code>else</code>
-chain as a <code>switch</code>.
-</p>
-
-<pre>
-func unhex(c byte) byte {
-    switch {
-    case '0' &lt;= c &amp;&amp; c &lt;= '9':
-        return c - '0'
-    case 'a' &lt;= c &amp;&amp; c &lt;= 'f':
-        return c - 'a' + 10
-    case 'A' &lt;= c &amp;&amp; c &lt;= 'F':
-        return c - 'A' + 10
-    }
-    return 0
-}
-</pre>
-
-<p>
-There is no automatic fall through, but cases can be presented
-in comma-separated lists.
-<pre>
-func shouldEscape(c byte) bool {
-    switch c {
-    case ' ', '?', '&amp;', '=', '#', '+', '%':
-        return true
-    }
-    return false
-}
-</pre>
-
-<p>
-Here's a comparison routine for byte arrays that uses two
-<code>switch</code> statements:
-<pre>
-// Compare returns an integer comparing the two byte arrays
-// lexicographically.
-// The result will be 0 if a == b, -1 if a &lt; b, and +1 if a &gt; b
-func Compare(a, b []byte) int {
-    for i := 0; i &lt; len(a) &amp;&amp; i &lt; len(b); i++ {
-        switch {
-        case a[i] &gt; b[i]:
-            return 1
-        case a[i] &lt; b[i]:
-            return -1
-        }
-    }
-    switch {
-    case len(a) &lt; len(b):
-        return -1
-    case len(a) &gt; len(b):
-        return 1
-    }
-    return 0
-}
-</pre>
-
-<p>
-A switch can also be used to discover the dynamic type of an interface
-variable.  Such a <em>type switch</em> uses the syntax of a type
-assertion with the keyword <code>type</code> inside the parentheses.
-If the switch declares a variable in the expression, the variable will
-have the corresponding type in each clause.
-</p>
-<pre>
-switch t := interfaceValue.(type) {
-default:
-    fmt.Printf("unexpected type %T", t)  // %T prints type
-case bool:
-    fmt.Printf("boolean %t\n", t)
-case int:
-    fmt.Printf("integer %d\n", t)
-case *bool:
-    fmt.Printf("pointer to boolean %t\n", *t)
-case *int:
-    fmt.Printf("pointer to integer %d\n", *t)
-}
-</pre>
-
-<h2 id="functions">Functions</h2>
-
-<h3 id="multiple-returns">Multiple return values</h3>
-
-<p>
-One of Go's unusual features is that functions and methods
-can return multiple values.  This form can be used to
-improve on a couple of clumsy idioms in C programs: in-band
-error returns (such as <code>-1</code> for <code>EOF</code>)
-and modifying an argument.
-</p>
-
-<p>
-In C, a write error is signaled by a negative count with the
-error code secreted away in a volatile location.
-In Go, <code>Write</code>
-can return a count <i>and</i> an error: &ldquo;Yes, you wrote some
-bytes but not all of them because you filled the device&rdquo;.
-The signature of <code>*File.Write</code> in package <code>os</code> is:
-</p>
-
-<pre>
-func (file *File) Write(b []byte) (n int, err error)
-</pre>
-
-<p>
-and as the documentation says, it returns the number of bytes
-written and a non-nil <code>error</code> when <code>n</code>
-<code>!=</code> <code>len(b)</code>.
-This is a common style; see the section on error handling for more examples.
-</p>
-
-<p>
-A similar approach obviates the need to pass a pointer to a return
-value to simulate a reference parameter.
-Here's a simple-minded function to
-grab a number from a position in a byte array, returning the number
-and the next position.
-</p>
-
-<pre>
-func nextInt(b []byte, i int) (int, int) {
-    for ; i &lt; len(b) &amp;&amp; !isDigit(b[i]); i++ {
-    }
-    x := 0
-    for ; i &lt; len(b) &amp;&amp; isDigit(b[i]); i++ {
-        x = x*10 + int(b[i])-'0'
-    }
-    return x, i
-}
-</pre>
-
-<p>
-You could use it to scan the numbers in an input array <code>a</code> like this:
-</p>
-
-<pre>
-    for i := 0; i &lt; len(a); {
-        x, i = nextInt(a, i)
-        fmt.Println(x)
-    }
-</pre>
-
-<h3 id="named-results">Named result parameters</h3>
-
-<p>
-The return or result "parameters" of a Go function can be given names and
-used as regular variables, just like the incoming parameters.
-When named, they are initialized to the zero values for their types when
-the function begins; if the function executes a <code>return</code> statement
-with no arguments, the current values of the result parameters are
-used as the returned values.
-</p>
-
-<p>
-The names are not mandatory but they can make code shorter and clearer:
-they're documentation.
-If we name the results of <code>nextInt</code> it becomes
-obvious which returned <code>int</code>
-is which.
-</p>
-
-<pre>
-func nextInt(b []byte, pos int) (value, nextPos int) {
-</pre>
-
-<p>
-Because named results are initialized and tied to an unadorned return, they can simplify
-as well as clarify.  Here's a version
-of <code>io.ReadFull</code> that uses them well:
-</p>
-
-<pre>
-func ReadFull(r Reader, buf []byte) (n int, err error) {
-    for len(buf) &gt; 0 &amp;&amp; err == nil {
-        var nr int
-        nr, err = r.Read(buf)
-        n += nr
-        buf = buf[nr:]
-    }
-    return
-}
-</pre>
-
-<h3 id="defer">Defer</h3>
-
-<p>
-Go's <code>defer</code> statement schedules a function call (the
-<i>deferred</i> function) to be run immediately before the function
-executing the <code>defer</code> returns.  It's an unusual but
-effective way to deal with situations such as resources that must be
-released regardless of which path a function takes to return.  The
-canonical examples are unlocking a mutex or closing a file.
-</p>
-
-<pre>
-// Contents returns the file's contents as a string.
-func Contents(filename string) (string, error) {
-    f, err := os.Open(filename)
-    if err != nil {
-        return "", err
-    }
-    defer f.Close()  // f.Close will run when we're finished.
-
-    var result []byte
-    buf := make([]byte, 100)
-    for {
-        n, err := f.Read(buf[0:])
-        result = append(result, buf[0:n]...) // append is discussed later.
-        if err != nil {
-            if err == io.EOF {
-                break
-            }
-            return "", err  // f will be closed if we return here.
-        }
-    }
-    return string(result), nil // f will be closed if we return here.
-}
-</pre>
-
-<p>
-Deferring a call to a function such as <code>Close</code> has two advantages.  First, it
-guarantees that you will never forget to close the file, a mistake
-that's easy to make if you later edit the function to add a new return
-path.  Second, it means that the close sits near the open,
-which is much clearer than placing it at the end of the function.
-</p>
-
-<p>
-The arguments to the deferred function (which include the receiver if
-the function is a method) are evaluated when the <i>defer</i>
-executes, not when the <i>call</i> executes.  Besides avoiding worries
-about variables changing values as the function executes, this means
-that a single deferred call site can defer multiple function
-executions.  Here's a silly example.
-</p>
-
-<pre>
-for i := 0; i &lt; 5; i++ {
-    defer fmt.Printf("%d ", i)
-}
-</pre>
-
-<p>
-Deferred functions are executed in LIFO order, so this code will cause
-<code>4 3 2 1 0</code> to be printed when the function returns.  A
-more plausible example is a simple way to trace function execution
-through the program.  We could write a couple of simple tracing
-routines like this:
-</p>
-
-<pre>
-func trace(s string)   { fmt.Println("entering:", s) }
-func untrace(s string) { fmt.Println("leaving:", s) }
-
-// Use them like this:
-func a() {
-    trace("a")
-    defer untrace("a")
-    // do something....
-}
-</pre>
-
-<p>
-We can do better by exploiting the fact that arguments to deferred
-functions are evaluated when the <code>defer</code> executes.  The
-tracing routine can set up the argument to the untracing routine.
-This example:
-</p>
-
-<pre>
-func trace(s string) string {
-    fmt.Println("entering:", s)
-    return s
-}
-
-func un(s string) {
-    fmt.Println("leaving:", s)
-}
-
-func a() {
-    defer un(trace("a"))
-    fmt.Println("in a")
-}
-
-func b() {
-    defer un(trace("b"))
-    fmt.Println("in b")
-    a()
-}
-
-func main() {
-    b()
-}
-</pre>
-
-<p>
-prints
-</p>
-
-<pre>
-entering: b
-in b
-entering: a
-in a
-leaving: a
-leaving: b
-</pre>
-
-<p>
-For programmers accustomed to block-level resource management from
-other languages, <code>defer</code> may seem peculiar, but its most
-interesting and powerful applications come precisely from the fact
-that it's not block-based but function-based.  In the section on
-<code>panic</code> and <code>recover</code> we'll see another
-example of its possibilities.
-</p>
-
-<h2 id="data">Data</h2>
-
-<h3 id="allocation_new">Allocation with <code>new</code></h3>
-
-<p>
-Go has two allocation primitives, the built-in functions
-<code>new</code> and <code>make</code>.
-They do different things and apply to different types, which can be confusing,
-but the rules are simple.
-Let's talk about <code>new</code> first.
-It's a built-in function that allocates memory, but unlike its namesakes
-in some other languages it does not <em>initialize</em> the memory,
-it only <em>zeroes</em> it.
-That is,
-<code>new(T)</code> allocates zeroed storage for a new item of type
-<code>T</code> and returns its address, a value of type <code>*T</code>.
-In Go terminology, it returns a pointer to a newly allocated zero value of type
-<code>T</code>.
-</p>
-
-<p>
-Since the memory returned by <code>new</code> is zeroed, it's helpful to arrange
-when designing your data structures that the
-zero value of each type can be used without further initialization.  This means a user of
-the data structure can create one with <code>new</code> and get right to
-work.
-For example, the documentation for <code>bytes.Buffer</code> states that
-"the zero value for <code>Buffer</code> is an empty buffer ready to use."
-Similarly, <code>sync.Mutex</code> does not
-have an explicit constructor or <code>Init</code> method.
-Instead, the zero value for a <code>sync.Mutex</code>
-is defined to be an unlocked mutex.
-</p>
-
-<p>
-The zero-value-is-useful property works transitively. Consider this type declaration.
-</p>
-
-<pre>
-type SyncedBuffer struct {
-    lock    sync.Mutex
-    buffer  bytes.Buffer
-}
-</pre>
-
-<p>
-Values of type <code>SyncedBuffer</code> are also ready to use immediately upon allocation
-or just declaration.  In the next snippet, both <code>p</code> and <code>v</code> will work
-correctly without further arrangement.
-</p>
-
-<pre>
-p := new(SyncedBuffer)  // type *SyncedBuffer
-var v SyncedBuffer      // type  SyncedBuffer
-</pre>
-
-<h3 id="composite_literals">Constructors and composite literals</h3>
-
-<p>
-Sometimes the zero value isn't good enough and an initializing
-constructor is necessary, as in this example derived from
-package <code>os</code>.
-</p>
-
-<pre>
-func NewFile(fd int, name string) *File {
-    if fd &lt; 0 {
-        return nil
-    }
-    f := new(File)
-    f.fd = fd
-    f.name = name
-    f.dirinfo = nil
-    f.nepipe = 0
-    return f
-}
-</pre>
-
-<p>
-There's a lot of boiler plate in there.  We can simplify it
-using a <i>composite literal</i>, which is
-an expression that creates a
-new instance each time it is evaluated.
-</p>
-
-<pre>
-func NewFile(fd int, name string) *File {
-    if fd &lt; 0 {
-        return nil
-    }
-    f := File{fd, name, nil, 0}
-    return &amp;f
-}
-</pre>
-
-<p>
-Note that, unlike in C, it's perfectly OK to return the address of a local variable;
-the storage associated with the variable survives after the function
-returns.
-In fact, taking the address of a composite literal
-allocates a fresh instance each time it is evaluated,
-so we can combine these last two lines.
-</p>
-
-<pre>
-    return &amp;File{fd, name, nil, 0}
-</pre>
-
-<p>
-The fields of a composite literal are laid out in order and must all be present.
-However, by labeling the elements explicitly as <i>field</i><code>:</code><i>value</i>
-pairs, the initializers can appear in any
-order, with the missing ones left as their respective zero values.  Thus we could say
-</p>
-
-<pre>
-    return &amp;File{fd: fd, name: name}
-</pre>
-
-<p>
-As a limiting case, if a composite literal contains no fields at all, it creates
-a zero value for the type.  The expressions <code>new(File)</code> and <code>&amp;File{}</code> are equivalent.
-</p>
-
-<p>
-Composite literals can also be created for arrays, slices, and maps,
-with the field labels being indices or map keys as appropriate.
-In these examples, the initializations work regardless of the values of <code>Enone</code>,
-<code>Eio</code>, and <code>Einval</code>, as long as they are distinct.
-</p>
-
-<pre>
-a := [...]string   {Enone: "no error", Eio: "Eio", Einval: "invalid argument"}
-s := []string      {Enone: "no error", Eio: "Eio", Einval: "invalid argument"}
-m := map[int]string{Enone: "no error", Eio: "Eio", Einval: "invalid argument"}
-</pre>
-
-<h3 id="allocation_make">Allocation with <code>make</code></h3>
-
-<p>
-Back to allocation.
-The built-in function <code>make(T, </code><i>args</i><code>)</code> serves
-a purpose different from <code>new(T)</code>.
-It creates slices, maps, and channels only, and it returns an <em>initialized</em>
-(not <em>zeroed</em>)
-value of type <code>T</code> (not <code>*T</code>).
-The reason for the distinction
-is that these three types are, under the covers, references to data structures that
-must be initialized before use.
-A slice, for example, is a three-item descriptor
-containing a pointer to the data (inside an array), the length, and the
-capacity, and until those items are initialized, the slice is <code>nil</code>.
-For slices, maps, and channels,
-<code>make</code> initializes the internal data structure and prepares
-the value for use.
-For instance,
-</p>
-
-<pre>
-make([]int, 10, 100)
-</pre>
-
-<p>
-allocates an array of 100 ints and then creates a slice
-structure with length 10 and a capacity of 100 pointing at the first
-10 elements of the array.
-(When making a slice, the capacity can be omitted; see the section on slices
-for more information.)
-In contrast, <code>new([]int)</code> returns a pointer to a newly allocated, zeroed slice
-structure, that is, a pointer to a <code>nil</code> slice value.
-
-<p>
-These examples illustrate the difference between <code>new</code> and
-<code>make</code>.
-</p>
-
-<pre>
-var p *[]int = new([]int)       // allocates slice structure; *p == nil; rarely useful
-var v  []int = make([]int, 100) // the slice v now refers to a new array of 100 ints
-
-// Unnecessarily complex:
-var p *[]int = new([]int)
-*p = make([]int, 100, 100)
-
-// Idiomatic:
-v := make([]int, 100)
-</pre>
-
-<p>
-Remember that <code>make</code> applies only to maps, slices and channels
-and does not return a pointer.
-To obtain an explicit pointer allocate with <code>new</code>.
-</p>
-
-<h3 id="arrays">Arrays</h3>
-
-<p>
-Arrays are useful when planning the detailed layout of memory and sometimes
-can help avoid allocation, but primarily
-they are a building block for slices, the subject of the next section.
-To lay the foundation for that topic, here are a few words about arrays.
-</p>
-
-<p>
-There are major differences between the ways arrays work in Go and C.
-In Go,
-</p>
-<ul>
-<li>
-Arrays are values. Assigning one array to another copies all the elements.
-</li>
-<li>
-In particular, if you pass an array to a function, it
-will receive a <i>copy</i> of the array, not a pointer to it.
-<li>
-The size of an array is part of its type.  The types <code>[10]int</code>
-and <code>[20]int</code> are distinct.
-</li>
-</ul>
-
-<p>
-The value property can be useful but also expensive; if you want C-like behavior and efficiency,
-you can pass a pointer to the array.
-</p>
-
-<pre>
-func Sum(a *[3]float64) (sum float64) {
-    for _, v := range *a {
-        sum += v
-    }
-    return
-}
-
-array := [...]float64{7.0, 8.5, 9.1}
-x := Sum(&amp;array)  // Note the explicit address-of operator
-</pre>
-
-<p>
-But even this style isn't idiomatic Go.  Slices are.
-</p>
-
-<h3 id="slices">Slices</h3>
-
-<p>
-Slices wrap arrays to give a more general, powerful, and convenient
-interface to sequences of data.  Except for items with explicit
-dimension such as transformation matrices, most array programming in
-Go is done with slices rather than simple arrays.
-</p>
-<p>
-Slices are <i>reference types</i>, which means that if you assign one
-slice to another, both refer to the same underlying array.  For
-instance, if a function takes a slice argument, changes it makes to
-the elements of the slice will be visible to the caller, analogous to
-passing a pointer to the underlying array.  A <code>Read</code>
-function can therefore accept a slice argument rather than a pointer
-and a count; the length within the slice sets an upper
-limit of how much data to read.  Here is the signature of the
-<code>Read</code> method of the <code>File</code> type in package
-<code>os</code>:
-</p>
-<pre>
-func (file *File) Read(buf []byte) (n int, err error)
-</pre>
-<p>
-The method returns the number of bytes read and an error value, if
-any.  To read into the first 32 bytes of a larger buffer
-<code>b</code>, <i>slice</i> (here used as a verb) the buffer.
-</p>
-<pre>
-    n, err := f.Read(buf[0:32])
-</pre>
-<p>
-Such slicing is common and efficient.  In fact, leaving efficiency aside for
-the moment, this snippet would also read the first 32 bytes of the buffer.
-</p>
-<pre>
-    var n int
-    var err error
-    for i := 0; i &lt; 32; i++ {
-        nbytes, e := f.Read(buf[i:i+1])  // Read one byte.
-        if nbytes == 0 || e != nil {
-            err = e
-            break
-        }
-        n += nbytes
-    }
-</pre>
-<p>
-The length of a slice may be changed as long as it still fits within
-the limits of the underlying array; just assign it to a slice of
-itself.  The <i>capacity</i> of a slice, accessible by the built-in
-function <code>cap</code>, reports the maximum length the slice may
-assume.  Here is a function to append data to a slice.  If the data
-exceeds the capacity, the slice is reallocated.  The
-resulting slice is returned.  The function uses the fact that
-<code>len</code> and <code>cap</code> are legal when applied to the
-<code>nil</code> slice, and return 0.
-</p>
-<pre>
-func Append(slice, data[]byte) []byte {
-    l := len(slice)
-    if l + len(data) &gt; cap(slice) {  // reallocate
-        // Allocate double what's needed, for future growth.
-        newSlice := make([]byte, (l+len(data))*2)
-        // The copy function is predeclared and works for any slice type.
-        copy(newSlice, slice)
-        slice = newSlice
-    }
-    slice = slice[0:l+len(data)]
-    for i, c := range data {
-        slice[l+i] = c
-    }
-    return slice
-}
-</pre>
-<p>
-We must return the slice afterwards because, although <code>Append</code>
-can modify the elements of <code>slice</code>, the slice itself (the run-time data
-structure holding the pointer, length, and capacity) is passed by value.
-<p>
-The idea of appending to a slice is so useful it's captured by the
-<code>append</code> built-in function.  To understand that function's
-design, though, we need a little more information, so we'll return
-to it later.
-</p>
-
-
-<h3 id="maps">Maps</h3>
-
-<p>
-Maps are a convenient and powerful built-in data structure to associate
-values of different types.
-The key can be of any type for which the equality operator is defined,
-such as integers,
-floating point and complex numbers,
-strings, pointers, and interfaces (as long as the dynamic type
-supports equality).  Structs, arrays and slices cannot be used as map keys,
-because equality is not defined on those types.
-Like slices, maps are a reference type. If you pass a map to a function
-that changes the contents of the map, the changes will be visible
-in the caller.
-</p>
-<p>
-Maps can be constructed using the usual composite literal syntax
-with colon-separated key-value pairs,
-so it's easy to build them during initialization.
-</p>
-<pre>
-var timeZone = map[string] int {
-    "UTC":  0*60*60,
-    "EST": -5*60*60,
-    "CST": -6*60*60,
-    "MST": -7*60*60,
-    "PST": -8*60*60,
-}
-</pre>
-<p>
-Assigning and fetching map values looks syntactically just like
-doing the same for arrays except that the index doesn't need to
-be an integer.
-</p>
-<pre>
-offset := timeZone["EST"]
-</pre>
-<p>
-An attempt to fetch a map value with a key that
-is not present in the map will return the zero value for the type
-of the entries
-in the map.  For instance, if the map contains integers, looking
-up a non-existent key will return <code>0</code>.
-A set can be implemented as a map with value type <code>bool</code>.
-Set the map entry to <code>true</code> to put the value in the set, and then
-test it by simple indexing.
-</p>
-<pre>
-attended := map[string] bool {
-    "Ann": true,
-    "Joe": true,
-    ...
-}
-
-if attended[person] { // will be false if person is not in the map
-    fmt.Println(person, "was at the meeting")
-}
-</pre>
-<p>
-Sometimes you need to distinguish a missing entry from
-a zero value.  Is there an entry for <code>"UTC"</code>
-or is that zero value because it's not in the map at all?
-You can discriminate with a form of multiple assignment.
-</p>
-<pre>
-var seconds int
-var ok bool
-seconds, ok = timeZone[tz]
-</pre>
-<p>
-For obvious reasons this is called the &ldquo;comma ok&rdquo; idiom.
-In this example, if <code>tz</code> is present, <code>seconds</code>
-will be set appropriately and <code>ok</code> will be true; if not,
-<code>seconds</code> will be set to zero and <code>ok</code> will
-be false.
-Here's a function that puts it together with a nice error report:
-</p>
-<pre>
-func offset(tz string) int {
-    if seconds, ok := timeZone[tz]; ok {
-        return seconds
-    }
-    log.Println("unknown time zone:", tz)
-    return 0
-}
-</pre>
-<p>
-To test for presence in the map without worrying about the actual value,
-you can use the <em>blank identifier</em>, a simple underscore (<code>_</code>).
-The blank identifier can be assigned or declared with any value of any type, with the
-value discarded harmlessly.  For testing just presence in a map, use the blank
-identifier in place of the usual variable for the value.
-</p>
-<pre>
-_, present := timeZone[tz]
-</pre>
-<p>
-To delete a map entry, use the <code>delete</code>
-built-in function, whose arguments are the map and the key to be deleted.
-It's safe to do this this even if the key is already absent
-from the map.
-</p>
-<pre>
-delete(timeZone, "PDT")  // Now on Standard Time
-</pre>
-
-<h3 id="printing">Printing</h3>
-
-<p>
-Formatted printing in Go uses a style similar to C's <code>printf</code>
-family but is richer and more general. The functions live in the <code>fmt</code>
-package and have capitalized names: <code>fmt.Printf</code>, <code>fmt.Fprintf</code>,
-<code>fmt.Sprintf</code> and so on.  The string functions (<code>Sprintf</code> etc.)
-return a string rather than filling in a provided buffer.
-</p>
-<p>
-You don't need to provide a format string.  For each of <code>Printf</code>,
-<code>Fprintf</code> and <code>Sprintf</code> there is another pair
-of functions, for instance <code>Print</code> and <code>Println</code>.
-These functions do not take a format string but instead generate a default
-format for each argument. The <code>Println</code> versions also insert a blank
-between arguments and append a newline to the output while
-the <code>Print</code> versions add blanks only if the operand on neither side is a string.
-In this example each line produces the same output.
-</p>
-<pre>
-fmt.Printf("Hello %d\n", 23)
-fmt.Fprint(os.Stdout, "Hello ", 23, "\n")
-fmt.Println("Hello", 23)
-fmt.Println(fmt.Sprint("Hello ", 23))
-</pre>
-<p>
-As mentioned in
-the <a href="http://code.google.com/p/go-tour/">Tour</a>, <code>fmt.Fprint</code>
-and friends take as a first argument any object
-that implements the <code>io.Writer</code> interface; the variables <code>os.Stdout</code>
-and <code>os.Stderr</code> are familiar instances.
-</p>
-<p>
-Here things start to diverge from C.  First, the numeric formats such as <code>%d</code>
-do not take flags for signedness or size; instead, the printing routines use the
-type of the argument to decide these properties.
-</p>
-<pre>
-var x uint64 = 1&lt;&lt;64 - 1
-fmt.Printf("%d %x; %d %x\n", x, x, int64(x), int64(x))
-</pre>
-<p>
-prints
-</p>
-<pre>
-18446744073709551615 ffffffffffffffff; -1 -1
-</pre>
-<p>
-If you just want the default conversion, such as decimal for integers, you can use
-the catchall format <code>%v</code> (for &ldquo;value&rdquo;); the result is exactly
-what <code>Print</code> and <code>Println</code> would produce.
-Moreover, that format can print <em>any</em> value, even arrays, structs, and
-maps.  Here is a print statement for the time zone map defined in the previous section.
-</p>
-<pre>
-fmt.Printf("%v\n", timeZone)  // or just fmt.Println(timeZone)
-</pre>
-<p>
-which gives output
-</p>
-<pre>
-map[CST:-21600 PST:-28800 EST:-18000 UTC:0 MST:-25200]
-</pre>
-<p>
-For maps the keys may be output in any order, of course.
-When printing a struct, the modified format <code>%+v</code> annotates the
-fields of the structure with their names, and for any value the alternate
-format <code>%#v</code> prints the value in full Go syntax.
-</p>
-<pre>
-type T struct {
-    a int
-    b float64
-    c string
-}
-t := &amp;T{ 7, -2.35, "abc\tdef" }
-fmt.Printf("%v\n", t)
-fmt.Printf("%+v\n", t)
-fmt.Printf("%#v\n", t)
-fmt.Printf("%#v\n", timeZone)
-</pre>
-<p>
-prints
-</p>
-<pre>
-&amp;{7 -2.35 abc   def}
-&amp;{a:7 b:-2.35 c:abc     def}
-&amp;main.T{a:7, b:-2.35, c:"abc\tdef"}
-map[string] int{"CST":-21600, "PST":-28800, "EST":-18000, "UTC":0, "MST":-25200}
-</pre>
-<p>
-(Note the ampersands.)
-That quoted string format is also available through <code>%q</code> when
-applied to a value of type <code>string</code> or <code>[]byte</code>;
-the alternate format <code>%#q</code> will use backquotes instead if possible.
-Also, <code>%x</code> works on strings and arrays of bytes as well as on integers,
-generating a long hexadecimal string, and with
-a space in the format (<code>%&nbsp;x</code>) it puts spaces between the bytes.
-</p>
-<p>
-Another handy format is <code>%T</code>, which prints the <em>type</em> of a value.
-<pre>
-fmt.Printf(&quot;%T\n&quot;, timeZone)
-</pre>
-<p>
-prints
-</p>
-<pre>
-map[string] int
-</pre>
-<p>
-If you want to control the default format for a custom type, all that's required is to define
-a method with the signature <code>String() string</code> on the type.
-For our simple type <code>T</code>, that might look like this.
-</p>
-<pre>
-func (t *T) String() string {
-    return fmt.Sprintf("%d/%g/%q", t.a, t.b, t.c)
-}
-fmt.Printf("%v\n", t)
-</pre>
-<p>
-to print in the format
-</p>
-<pre>
-7/-2.35/"abc\tdef"
-</pre>
-<p>
-(If you need to print <em>values</em> of type <code>T</code> as well as pointers to <code>T</code>,
-the receiver for <code>String</code> must be of value type; this example used a pointer because
-that's more efficient and idiomatic for struct types.
-See the section below on <a href="#pointers_vs_values">pointers vs. value receivers</a> for more information.)
-</p>
-<p>
-Our <code>String</code> method is able to call <code>Sprintf</code> because the
-print routines are fully reentrant and can be used recursively.
-We can even go one step further and pass a print routine's arguments directly to another such routine.
-The signature of <code>Printf</code> uses the type <code>...interface{}</code>
-for its final argument to specify that an arbitrary number of parameters (of arbitrary type)
-can appear after the format.
-</p>
-<pre>
-func Printf(format string, v ...interface{}) (n int, err error) {
-</pre>
-<p>
-Within the function <code>Printf</code>, <code>v</code> acts like a variable of type
-<code>[]interface{}</code> but if it is passed to another variadic function, it acts like
-a regular list of arguments.
-Here is the implementation of the
-function <code>log.Println</code> we used above. It passes its arguments directly to
-<code>fmt.Sprintln</code> for the actual formatting.
-</p>
-<pre>
-// Println prints to the standard logger in the manner of fmt.Println.
-func Println(v ...interface{}) {
-    std.Output(2, fmt.Sprintln(v...))  // Output takes parameters (int, string)
-}
-</pre>
-<p>
-We write <code>...</code> after <code>v</code> in the nested call to <code>Sprintln</code> to tell the
-compiler to treat <code>v</code> as a list of arguments; otherwise it would just pass
-<code>v</code> as a single slice argument.
-<p>
-There's even more to printing than we've covered here.  See the <code>godoc</code> documentation
-for package <code>fmt</code> for the details.
-</p>
-<p>
-By the way, a <code>...</code> parameter can be of a specific type, for instance <code>...int</code>
-for a min function that chooses the least of a list of integers:
-</p>
-<pre>
-func Min(a ...int) int {
-    min := int(^uint(0) >> 1)  // largest int
-    for _, i := range a {
-        if i &lt; min {
-            min = i
-        }
-    }
-    return min
-}
-</pre>
-
-<h3 id="append">Append</h3>
-<p>
-Now we have the missing piece we needed to explain the design of
-the <code>append</code> built-in function.  The signature of <code>append</code>
-is different from our custom <code>Append</code> function above.
-Schematically, it's like this:
-</p>
-<pre>
-func append(slice []<i>T</i>, elements...T) []<i>T</i>
-</pre>
-<p>
-where <i>T</i> is a placeholder for any given type.  You can't
-actually write a function in Go where the type <code>T</code>
-is determined by the caller.
-That's why <code>append</code> is built in: it needs support from the
-compiler.
-</p>
-<p>
-What <code>append</code> does is append the elements to the end of
-the slice and return the result.  The result needs to be returned
-because, as with our hand-written <code>Append</code>, the underlying
-array may change.  This simple example
-</p>
-<pre>
-x := []int{1,2,3}
-x = append(x, 4, 5, 6)
-fmt.Println(x)
-</pre>
-<p>
-prints <code>[1 2 3 4 5 6]</code>.  So <code>append</code> works a
-little like <code>Printf</code>, collecting an arbitrary number of
-arguments.
-</p>
-<p>
-But what if we wanted to do what our <code>Append</code> does and
-append a slice to a slice?  Easy: use <code>...</code> at the call
-site, just as we did in the call to <code>Output</code> above.  This
-snippet produces identical output to the one above.
-</p>
-<pre>
-x := []int{1,2,3}
-y := []int{4,5,6}
-x = append(x, y...)
-fmt.Println(x)
-</pre>
-<p>
-Without that <code>...</code>, it wouldn't compile because the types
-would be wrong; <code>y</code> is not of type <code>int</code>.
-</p>
-
-<h2 id="initialization">Initialization</h2>
-
-<p>
-Although it doesn't look superficially very different from
-initialization in C or C++, initialization in Go is more powerful.
-Complex structures can be built during initialization and the ordering
-issues between initialized objects in different packages are handled
-correctly.
-</p>
-
-<h3 id="constants">Constants</h3>
-
-<p>
-Constants in Go are just that&mdash;constant.
-They are created at compile time, even when defined as
-locals in functions,
-and can only be numbers, strings or booleans.
-Because of the compile-time restriction, the expressions
-that define them must be constant expressions,
-evaluatable by the compiler.  For instance,
-<code>1&lt;&lt;3</code> is a constant expression, while
-<code>math.Sin(math.Pi/4)</code> is not because
-the function call to <code>math.Sin</code> needs
-to happen at run time.
-</p>
-
-<p>
-In Go, enumerated constants are created using the <code>iota</code>
-enumerator.  Since <code>iota</code> can be part of an expression and
-expressions can be implicitly repeated, it is easy to build intricate
-sets of values.
-</p>
-{{code "progs/eff_bytesize.go" `/^type ByteSize/` `/^\)/`}}
-<p>
-The ability to attach a method such as <code>String</code> to a
-type makes it possible for such values to format themselves
-automatically for printing, even as part of a general type.
-</p>
-{{code "progs/eff_bytesize.go" `/^func.*ByteSize.*String/` `/^}/`}}
-<p>
-(The <code>float64</code> conversions prevent <code>Sprintf</code> 
-from recurring back through the <code>String</code> method for 
-<code>ByteSize</code>.)
-The expression <code>YB</code> prints as <code>1.00YB</code>,
-while <code>ByteSize(1e13)</code> prints as <code>9.09TB</code>.
-</p>
-
-<h3 id="variables">Variables</h3>
-
-<p>
-Variables can be initialized just like constants but the
-initializer can be a general expression computed at run time.
-</p>
-<pre>
-var (
-    HOME = os.Getenv("HOME")
-    USER = os.Getenv("USER")
-    GOROOT = os.Getenv("GOROOT")
-)
-</pre>
-
-<h3 id="init">The init function</h3>
-
-<p>
-Finally, each source file can define its own niladic <code>init</code> function to
-set up whatever state is required.  (Actually each file can have multiple
-<code>init</code> functions.) The only restriction is that, although
-goroutines can be launched during initialization, they will not begin
-execution until it completes; initialization always runs as a single thread
-of execution.
-And finally means finally: <code>init</code> is called after all the
-variable declarations in the package have evaluated their initializers,
-and those are evaluated only after all the imported packages have been
-initialized.
-</p>
-<p>
-Besides initializations that cannot be expressed as declarations,
-a common use of <code>init</code> functions is to verify or repair
-correctness of the program state before real execution begins.
-</p>
-
-<pre>
-func init() {
-    if USER == "" {
-        log.Fatal("$USER not set")
-    }
-    if HOME == "" {
-        HOME = "/usr/" + USER
-    }
-    if GOROOT == "" {
-        GOROOT = HOME + "/go"
-    }
-    // GOROOT may be overridden by --goroot flag on command line.
-    flag.StringVar(&amp;GOROOT, "goroot", GOROOT, "Go root directory")
-}
-</pre>
-
-<h2 id="methods">Methods</h2>
-
-<h3 id="pointers_vs_values">Pointers vs. Values</h3>
-<p>
-Methods can be defined for any named type that is not a pointer or an interface;
-the receiver does not have to be a struct.
-<p>
-In the discussion of slices above, we wrote an <code>Append</code>
-function.  We can define it as a method on slices instead.  To do
-this, we first declare a named type to which we can bind the method, and
-then make the receiver for the method a value of that type.
-</p>
-<pre>
-type ByteSlice []byte
-
-func (slice ByteSlice) Append(data []byte) []byte {
-    // Body exactly the same as above
-}
-</pre>
-<p>
-This still requires the method to return the updated slice.  We can
-eliminate that clumsiness by redefining the method to take a
-<i>pointer</i> to a <code>ByteSlice</code> as its receiver, so the
-method can overwrite the caller's slice.
-</p>
-<pre>
-func (p *ByteSlice) Append(data []byte) {
-    slice := *p
-    // Body as above, without the return.
-    *p = slice
-}
-</pre>
-<p>
-In fact, we can do even better.  If we modify our function so it looks
-like a standard <code>Write</code> method, like this,
-</p>
-<pre>
-func (p *ByteSlice) Write(data []byte) (n int, err error) {
-    slice := *p
-    // Again as above.
-    *p = slice
-    return len(data), nil
-}
-</pre>
-<p>
-then the type <code>*ByteSlice</code> satisfies the standard interface
-<code>io.Writer</code>, which is handy.  For instance, we can
-print into one.
-</p>
-<pre>
-    var b ByteSlice
-    fmt.Fprintf(&amp;b, "This hour has %d days\n", 7)
-</pre>
-<p>
-We pass the address of a <code>ByteSlice</code>
-because only <code>*ByteSlice</code> satisfies <code>io.Writer</code>.
-The rule about pointers vs. values for receivers is that value methods
-can be invoked on pointers and values, but pointer methods can only be
-invoked on pointers.  This is because pointer methods can modify the
-receiver; invoking them on a copy of the value would cause those
-modifications to be discarded.
-</p>
-<p>
-By the way, the idea of using <code>Write</code> on a slice of bytes
-is implemented by <code>bytes.Buffer</code>.
-</p>
-
-<h2 id="interfaces_and_types">Interfaces and other types</h2>
-
-<h3 id="interfaces">Interfaces</h3>
-<p>
-Interfaces in Go provide a way to specify the behavior of an
-object: if something can do <em>this</em>, then it can be used
-<em>here</em>.  We've seen a couple of simple examples already;
-custom printers can be implemented by a <code>String</code> method
-while <code>Fprintf</code> can generate output to anything
-with a <code>Write</code> method.
-Interfaces with only one or two methods are common in Go code, and are
-usually given a name derived from the method, such as <code>io.Writer</code>
-for something that implements <code>Write</code>.
-</p>
-<p>
-A type can implement multiple interfaces.
-For instance, a collection can be sorted
-by the routines in package <code>sort</code> if it implements
-<code>sort.Interface</code>, which contains <code>Len()</code>,
-<code>Less(i, j int) bool</code>, and <code>Swap(i, j int)</code>,
-and it could also have a custom formatter.
-In this contrived example <code>Sequence</code> satisfies both.
-</p>
-{{code "progs/eff_sequence.go" `/^type/` "$"}}
-
-<h3 id="conversions">Conversions</h3>
-
-<p>
-The <code>String</code> method of <code>Sequence</code> is recreating the
-work that <code>Sprint</code> already does for slices.  We can share the
-effort if we convert the <code>Sequence</code> to a plain
-<code>[]int</code> before calling <code>Sprint</code>.
-</p>
-<pre>
-func (s Sequence) String() string {
-    sort.Sort(s)
-    return fmt.Sprint([]int(s))
-}
-</pre>
-<p>
-The conversion causes <code>s</code> to be treated as an ordinary slice
-and therefore receive the default formatting.
-Without the conversion, <code>Sprint</code> would find the
-<code>String</code> method of <code>Sequence</code> and recur indefinitely.
-Because the two types (<code>Sequence</code> and <code>[]int</code>)
-are the same if we ignore the type name, it's legal to convert between them.
-The conversion doesn't create a new value, it just temporarily acts
-as though the existing value has a new type.
-(There are other legal conversions, such as from integer to floating point, that
-do create a new value.)
-</p>
-<p>
-It's an idiom in Go programs to convert the
-type of an expression to access a different
-set of methods. As an example, we could use the existing
-type <code>sort.IntSlice</code> to reduce the entire example
-to this:
-</p>
-<pre>
-type Sequence []int
-
-// Method for printing - sorts the elements before printing
-func (s Sequence) String() string {
-    sort.IntSlice(s).Sort()
-    return fmt.Sprint([]int(s))
-}
-</pre>
-<p>
-Now, instead of having <code>Sequence</code> implement multiple
-interfaces (sorting and printing), we're using the ability of a data item to be
-converted to multiple types (<code>Sequence</code>, <code>sort.IntSlice</code>
-and <code>[]int</code>), each of which does some part of the job.
-That's more unusual in practice but can be effective.
-</p>
-
-<h3 id="generality">Generality</h3>
-<p>
-If a type exists only to implement an interface
-and has no exported methods beyond that interface,
-there is no need to export the type itself.
-Exporting just the interface makes it clear that
-it's the behavior that matters, not the implementation,
-and that other implementations with different properties
-can mirror the behavior of the original type.
-It also avoids the need to repeat the documentation
-on every instance of a common method.
-</p>
-<p>
-In such cases, the constructor should return an interface value
-rather than the implementing type.
-As an example, in the hash libraries
-both <code>crc32.NewIEEE</code> and <code>adler32.New</code>
-return the interface type <code>hash.Hash32</code>.
-Substituting the CRC-32 algorithm for Adler-32 in a Go program
-requires only changing the constructor call;
-the rest of the code is unaffected by the change of algorithm.
-</p>
-<p>
-A similar approach allows the streaming cipher algorithms
-in the various <code>crypto</code> packages to be
-separated from the block ciphers they chain together.
-The <code>Block</code> interface
-in the <code>crypto/cipher</code>package specifies the
-behavior of a block cipher, which provides encryption
-of a single block of data.
-Then, by analogy with the <code>bufio</code> package,
-cipher packages that implement this interface
-can be used to construct streaming ciphers, represented
-by the <code>Stream</code> interface, without
-knowing the details of the block encryption.
-</p>
-<p>
-The  <code>crypto/cipher</code> interfaces look like this:
-</p>
-<pre>
-type Block interface {
-    BlockSize() int
-    Encrypt(src, dst []byte)
-    Decrypt(src, dst []byte)
-}
-
-type Stream interface {
-    XORKeyStream(dst, src []byte)
-}
-</pre>
-
-<p>
-Here's the definition of the counter mode (CTR) stream,
-which turns a block cipher into a streaming cipher; notice
-that the block cipher's details are abstracted away:
-</p>
-
-<pre>
-// NewCTR returns a Stream that encrypts/decrypts using the given Block in
-// counter mode. The length of iv must be the same as the Block's block size.
-func NewCTR(block Block, iv []byte) Stream
-</pre>
-<p>
-<code>NewCTR</code> applies not
-just to one specific encryption algorithm and data source but to any
-implementation of the <code>Block</code> interface and any
-<code>Stream</code>.  Because they return
-interface values, replacing CTR
-encryption with other encryption modes is a localized change.  The constructor
-calls must be edited, but because the surrounding code must treat the result only
-as a <code>Stream</code>, it won't notice the difference.
-</p>
-
-<h3 id="interface_methods">Interfaces and methods</h3>
-<p>
-Since almost anything can have methods attached, almost anything can
-satisfy an interface.  One illustrative example is in the <code>http</code>
-package, which defines the <code>Handler</code> interface.  Any object
-that implements <code>Handler</code> can serve HTTP requests.
-</p>
-<pre>
-type Handler interface {
-    ServeHTTP(ResponseWriter, *Request)
-}
-</pre>
-<p>
-<code>ResponseWriter</code> is itself an interface that provides access
-to the methods needed to return the response to the client.
-Those methods include the standard <code>Write</code> method, so an
-<code>http.ResponseWriter</code> can be used wherever an <code>io.Writer</code>
-can be used.
-<code>Request</code> is a struct containing a parsed representation
-of the request from the client.
-<p>
-For brevity, let's ignore POSTs and assume HTTP requests are always
-GETs; that simplification does not affect the way the handlers are
-set up.  Here's a trivial but complete implementation of a handler to
-count the number of times the
-page is visited.
-</p>
-<pre>
-// Simple counter server.
-type Counter struct {
-    n int
-}
-
-func (ctr *Counter) ServeHTTP(w http.ResponseWriter, req *http.Request) {
-    ctr.n++
-    fmt.Fprintf(w, "counter = %d\n", ctr.n)
-}
-</pre>
-<p>
-(Keeping with our theme, note how <code>Fprintf</code> can print to an
-<code>http.ResponseWriter</code>.)
-For reference, here's how to attach such a server to a node on the URL tree.
-<pre>
-import "net/http"
-...
-ctr := new(Counter)
-http.Handle("/counter", ctr)
-</pre>
-<p>
-But why make <code>Counter</code> a struct?  An integer is all that's needed.
-(The receiver needs to be a pointer so the increment is visible to the caller.)
-</p>
-<pre>
-// Simpler counter server.
-type Counter int
-
-func (ctr *Counter) ServeHTTP(w http.ResponseWriter, req *http.Request) {
-    *ctr++
-    fmt.Fprintf(w, "counter = %d\n", *ctr)
-}
-</pre>
-<p>
-What if your program has some internal state that needs to be notified that a page
-has been visited?  Tie a channel to the web page.
-</p>
-<pre>
-// A channel that sends a notification on each visit.
-// (Probably want the channel to be buffered.)
-type Chan chan *http.Request
-
-func (ch Chan) ServeHTTP(w http.ResponseWriter, req *http.Request) {
-    ch &lt;- req
-    fmt.Fprint(w, "notification sent")
-}
-</pre>
-<p>
-Finally, let's say we wanted to present on <code>/args</code> the arguments
-used when invoking the server binary.
-It's easy to write a function to print the arguments.
-</p>
-<pre>
-func ArgServer() {
-    for _, s := range os.Args {
-        fmt.Println(s)
-    }
-}
-</pre>
-<p>
-How do we turn that into an HTTP server?  We could make <code>ArgServer</code>
-a method of some type whose value we ignore, but there's a cleaner way.
-Since we can define a method for any type except pointers and interfaces,
-we can write a method for a function.
-The <code>http</code> package contains this code:
-</p>
-<pre>
-// The HandlerFunc type is an adapter to allow the use of
-// ordinary functions as HTTP handlers.  If f is a function
-// with the appropriate signature, HandlerFunc(f) is a
-// Handler object that calls f.
-type HandlerFunc func(ResponseWriter, *Request)
-
-// ServeHTTP calls f(c, req).
-func (f HandlerFunc) ServeHTTP(w ResponseWriter, req *Request) {
-    f(w, req)
-}
-</pre>
-<p>
-<code>HandlerFunc</code> is a type with a method, <code>ServeHTTP</code>,
-so values of that type can serve HTTP requests.  Look at the implementation
-of the method: the receiver is a function, <code>f</code>, and the method
-calls <code>f</code>.  That may seem odd but it's not that different from, say,
-the receiver being a channel and the method sending on the channel.
-</p>
-<p>
-To make <code>ArgServer</code> into an HTTP server, we first modify it
-to have the right signature.
-</p>
-<pre>
-// Argument server.
-func ArgServer(w http.ResponseWriter, req *http.Request) {
-    for _, s := range os.Args {
-        fmt.Fprintln(w, s)
-    }
-}
-</pre>
-<p>
-<code>ArgServer</code> now has same signature as <code>HandlerFunc</code>,
-so it can be converted to that type to access its methods,
-just as we converted <code>Sequence</code> to <code>IntSlice</code>
-to access <code>IntSlice.Sort</code>.
-The code to set it up is concise:
-</p>
-<pre>
-http.Handle("/args", http.HandlerFunc(ArgServer))
-</pre>
-<p>
-When someone visits the page <code>/args</code>,
-the handler installed at that page has value <code>ArgServer</code>
-and type <code>HandlerFunc</code>.
-The HTTP server will invoke the method <code>ServeHTTP</code>
-of that type, with <code>ArgServer</code> as the receiver, which will in turn call
-<code>ArgServer</code> (via the invocation <code>f(c, req)</code>
-inside <code>HandlerFunc.ServeHTTP</code>).
-The arguments will then be displayed.
-</p>
-<p>
-In this section we have made an HTTP server from a struct, an integer,
-a channel, and a function, all because interfaces are just sets of
-methods, which can be defined for (almost) any type.
-</p>
-
-<h2 id="embedding">Embedding</h2>
-
-<p>
-Go does not provide the typical, type-driven notion of subclassing,
-but it does have the ability to &ldquo;borrow&rdquo; pieces of an
-implementation by <em>embedding</em> types within a struct or
-interface.
-</p>
-<p>
-Interface embedding is very simple.
-We've mentioned the <code>io.Reader</code> and <code>io.Writer</code> interfaces before;
-here are their definitions.
-</p>
-<pre>
-type Reader interface {
-    Read(p []byte) (n int, err error)
-}
-
-type Writer interface {
-    Write(p []byte) (n int, err error)
-}
-</pre>
-<p>
-The <code>io</code> package also exports several other interfaces
-that specify objects that can implement several such methods.
-For instance, there is <code>io.ReadWriter</code>, an interface
-containing both <code>Read</code> and <code>Write</code>.
-We could specify <code>io.ReadWriter</code> by listing the
-two methods explicitly, but it's easier and more evocative
-to embed the two interfaces to form the new one, like this:
-</p>
-<pre>
-// ReadWriter is the interface that combines the Reader and Writer interfaces.
-type ReadWriter interface {
-    Reader
-    Writer
-}
-</pre>
-<p>
-This says just what it looks like: A <code>ReadWriter</code> can do
-what a <code>Reader</code> does <em>and</em> what a <code>Writer</code>
-does; it is a union of the embedded interfaces (which must be disjoint
-sets of methods).
-Only interfaces can be embedded within interfaces.
-<p>
-The same basic idea applies to structs, but with more far-reaching
-implications.  The <code>bufio</code> package has two struct types,
-<code>bufio.Reader</code> and <code>bufio.Writer</code>, each of
-which of course implements the analogous interfaces from package
-<code>io</code>.
-And <code>bufio</code> also implements a buffered reader/writer,
-which it does by combining a reader and a writer into one struct
-using embedding: it lists the types within the struct
-but does not give them field names.
-</p>
-<pre>
-// ReadWriter stores pointers to a Reader and a Writer.
-// It implements io.ReadWriter.
-type ReadWriter struct {
-    *Reader  // *bufio.Reader
-    *Writer  // *bufio.Writer
-}
-</pre>
-<p>
-The embedded elements are pointers to structs and of course
-must be initialized to point to valid structs before they
-can be used.
-The <code>ReadWriter</code> struct could be written as
-</p>
-<pre>
-type ReadWriter struct {
-    reader *Reader
-    writer *Writer
-}
-</pre>
-<p>
-but then to promote the methods of the fields and to
-satisfy the <code>io</code> interfaces, we would also need
-to provide forwarding methods, like this:
-</p>
-<pre>
-func (rw *ReadWriter) Read(p []byte) (n int, err error) {
-    return rw.reader.Read(p)
-}
-</pre>
-<p>
-By embedding the structs directly, we avoid this bookkeeping.
-The methods of embedded types come along for free, which means that <code>bufio.ReadWriter</code>
-not only has the methods of <code>bufio.Reader</code> and <code>bufio.Writer</code>,
-it also satisfies all three interfaces:
-<code>io.Reader</code>,
-<code>io.Writer</code>, and
-<code>io.ReadWriter</code>.
-</p>
-<p>
-There's an important way in which embedding differs from subclassing.  When we embed a type,
-the methods of that type become methods of the outer type,
-but when they are invoked the receiver of the method is the inner type, not the outer one.
-In our example, when the <code>Read</code> method of a <code>bufio.ReadWriter</code> is
-invoked, it has exactly the same effect as the forwarding method written out above;
-the receiver is the <code>reader</code> field of the <code>ReadWriter</code>, not the
-<code>ReadWriter</code> itself.
-</p>
-<p>
-Embedding can also be a simple convenience.
-This example shows an embedded field alongside a regular, named field.
-</p>
-<pre>
-type Job struct {
-    Command string
-    *log.Logger
-}
-</pre>
-<p>
-The <code>Job</code> type now has the <code>Log</code>, <code>Logf</code>
-and other
-methods of <code>*log.Logger</code>.  We could have given the <code>Logger</code>
-a field name, of course, but it's not necessary to do so.  And now, once
-initialized, we can
-log to the <code>Job</code>:
-</p>
-<pre>
-job.Log("starting now...")
-</pre>
-<p>
-The <code>Logger</code> is a regular field of the struct and we can initialize
-it in the usual way with a constructor,
-</p>
-<pre>
-func NewJob(command string, logger *log.Logger) *Job {
-    return &amp;Job{command, logger}
-}
-</pre>
-<p>
-or with a composite literal,
-</p>
-<pre>
-job := &amp;Job{command, log.New(os.Stderr, "Job: ", log.Ldate)}
-</pre>
-<p>
-If we need to refer to an embedded field directly, the type name of the field,
-ignoring the package qualifier, serves as a field name.  If we needed to access the
-<code>*log.Logger</code> of a <code>Job</code> variable <code>job</code>,
-we would write <code>job.Logger</code>.
-This would be useful if we wanted to refine the methods of <code>Logger</code>.
-</p>
-<pre>
-func (job *Job) Logf(format string, args ...interface{}) {
-    job.Logger.Logf("%q: %s", job.Command, fmt.Sprintf(format, args))
-}
-</pre>
-<p>
-Embedding types introduces the problem of name conflicts but the rules to resolve
-them are simple.
-First, a field or method <code>X</code> hides any other item <code>X</code> in a more deeply
-nested part of the type.
-If <code>log.Logger</code> contained a field or method called <code>Command</code>, the <code>Command</code> field
-of <code>Job</code> would dominate it.
-</p>
-<p>
-Second, if the same name appears at the same nesting level, it is usually an error;
-it would be erroneous to embed <code>log.Logger</code> if the <code>Job</code> struct
-contained another field or method called <code>Logger</code>.
-However, if the duplicate name is never mentioned in the program outside the type definition, it is OK.
-This qualification provides some protection against changes made to types embedded from outside; there
-is no problem if a field is added that conflicts with another field in another subtype if neither field
-is ever used.
-</p>
-
-
-<h2 id="concurrency">Concurrency</h2>
-
-<h3 id="sharing">Share by communicating</h3>
-
-<p>
-Concurrent programming is a large topic and there is space only for some
-Go-specific highlights here.
-</p>
-<p>
-Concurrent programming in many environments is made difficult by the
-subtleties required to implement correct access to shared variables.  Go encourages
-a different approach in which shared values are passed around on channels
-and, in fact, never actively shared by separate threads of execution.
-Only one goroutine has access to the value at any given time.
-Data races cannot occur, by design.
-To encourage this way of thinking we have reduced it to a slogan:
-</p>
-<blockquote>
-Do not communicate by sharing memory;
-instead, share memory by communicating.
-</blockquote>
-<p>
-This approach can be taken too far.  Reference counts may be best done
-by putting a mutex around an integer variable, for instance.  But as a
-high-level approach, using channels to control access makes it easier
-to write clear, correct programs.
-</p>
-<p>
-One way to think about this model is to consider a typical single-threaded
-program running on one CPU. It has no need for synchronization primitives.
-Now run another such instance; it too needs no synchronization.  Now let those
-two communicate; if the communication is the synchronizer, there's still no need
-for other synchronization.  Unix pipelines, for example, fit this model
-perfectly.  Although Go's approach to concurrency originates in Hoare's
-Communicating Sequential Processes (CSP),
-it can also be seen as a type-safe generalization of Unix pipes.
-</p>
-
-<h3 id="goroutines">Goroutines</h3>
-
-<p>
-They're called <em>goroutines</em> because the existing
-terms&mdash;threads, coroutines, processes, and so on&mdash;convey
-inaccurate connotations.  A goroutine has a simple model: it is a
-function executing in parallel with other goroutines in the same
-address space.  It is lightweight, costing little more than the
-allocation of stack space.
-And the stacks start small, so they are cheap, and grow
-by allocating (and freeing) heap storage as required.
-</p>
-<p>
-Goroutines are multiplexed onto multiple OS threads so if one should
-block, such as while waiting for I/O, others continue to run.  Their
-design hides many of the complexities of thread creation and
-management.
-</p>
-<p>
-Prefix a function or method call with the <code>go</code>
-keyword to run the call in a new goroutine.
-When the call completes, the goroutine
-exits, silently.  (The effect is similar to the Unix shell's
-<code>&amp;</code> notation for running a command in the
-background.)
-</p>
-<pre>
-go list.Sort()  // run list.Sort in parallel; don't wait for it. 
-</pre>
-<p>
-A function literal can be handy in a goroutine invocation.
-<pre>
-func Announce(message string, delay int64) {
-    go func() {
-        time.Sleep(delay)
-        fmt.Println(message)
-    }()  // Note the parentheses - must call the function.
-}
-</pre>
-<p>
-In Go, function literals are closures: the implementation makes
-sure the variables referred to by the function survive as long as they are active.
-<p>
-These examples aren't too practical because the functions have no way of signaling
-completion.  For that, we need channels.
-</p>
-
-<h3 id="channels">Channels</h3>
-
-<p>
-Like maps, channels are a reference type and are allocated with <code>make</code>.
-If an optional integer parameter is provided, it sets the buffer size for the channel.
-The default is zero, for an unbuffered or synchronous channel.
-</p>
-<pre>
-ci := make(chan int)            // unbuffered channel of integers
-cj := make(chan int, 0)         // unbuffered channel of integers
-cs := make(chan *os.File, 100)  // buffered channel of pointers to Files
-</pre>
-<p>
-Channels combine communication&mdash;the exchange of a value&mdash;with
-synchronization&mdash;guaranteeing that two calculations (goroutines) are in
-a known state.
-</p>
-<p>
-There are lots of nice idioms using channels.  Here's one to get us started.
-In the previous section we launched a sort in the background. A channel
-can allow the launching goroutine to wait for the sort to complete.
-</p>
-<pre>
-c := make(chan int)  // Allocate a channel.
-// Start the sort in a goroutine; when it completes, signal on the channel.
-go func() {
-    list.Sort()
-    c &lt;- 1  // Send a signal; value does not matter. 
-}()
-doSomethingForAWhile()
-&lt;-c   // Wait for sort to finish; discard sent value.
-</pre>
-<p>
-Receivers always block until there is data to receive.
-If the channel is unbuffered, the sender blocks until the receiver has
-received the value.
-If the channel has a buffer, the sender blocks only until the
-value has been copied to the buffer; if the buffer is full, this
-means waiting until some receiver has retrieved a value.
-</p>
-<p>
-A buffered channel can be used like a semaphore, for instance to
-limit throughput.  In this example, incoming requests are passed
-to <code>handle</code>, which sends a value into the channel, processes
-the request, and then receives a value from the channel.
-The capacity of the channel buffer limits the number of
-simultaneous calls to <code>process</code>.
-</p>
-<pre>
-var sem = make(chan int, MaxOutstanding)
-
-func handle(r *Request) {
-    sem &lt;- 1    // Wait for active queue to drain.
-    process(r)  // May take a long time.
-    &lt;-sem       // Done; enable next request to run.
-}
-
-func Serve(queue chan *Request) {
-    for {
-        req := &lt;-queue
-        go handle(req)  // Don't wait for handle to finish.
-    }
-}
-</pre>
-<p>
-Here's the same idea implemented by starting a fixed
-number of <code>handle</code> goroutines all reading from the request
-channel.
-The number of goroutines limits the number of simultaneous
-calls to <code>process</code>.
-This <code>Serve</code> function also accepts a channel on which
-it will be told to exit; after launching the goroutines it blocks
-receiving from that channel.
-</p>
-<pre>
-func handle(queue chan *Request) {
-    for r := range queue {
-        process(r)
-    }
-}
-
-func Serve(clientRequests chan *clientRequests, quit chan bool) {
-    // Start handlers
-    for i := 0; i &lt; MaxOutstanding; i++ {
-        go handle(clientRequests)
-    }
-    &lt;-quit  // Wait to be told to exit.
-}
-</pre>
-
-<h3 id="chan_of_chan">Channels of channels</h3>
-<p>
-One of the most important properties of Go is that
-a channel is a first-class value that can be allocated and passed
-around like any other.  A common use of this property is
-to implement safe, parallel demultiplexing.
-<p>
-In the example in the previous section, <code>handle</code> was
-an idealized handler for a request but we didn't define the
-type it was handling.  If that type includes a channel on which
-to reply, each client can provide its own path for the answer.
-Here's a schematic definition of type <code>Request</code>.
-</p>
-<pre>
-type Request struct {
-    args        []int
-    f           func([]int) int
-    resultChan  chan int
-}
-</pre>
-<p>
-The client provides a function and its arguments, as well as
-a channel inside the request object on which to receive the answer.
-</p>
-<pre>
-func sum(a []int) (s int) {
-    for _, v := range a {
-        s += v
-    }
-    return
-}
-
-request := &amp;Request{[]int{3, 4, 5}, sum, make(chan int)}
-// Send request
-clientRequests &lt;- request
-// Wait for response.
-fmt.Printf("answer: %d\n", &lt;-request.resultChan)
-</pre>
-<p>
-On the server side, the handler function is the only thing that changes.
-</p>
-<pre>
-func handle(queue chan *Request) {
-    for req := range queue {
-        req.resultChan &lt;- req.f(req.args)
-    }
-}
-</pre>
-<p>
-There's clearly a lot more to do to make it realistic, but this
-code is a framework for a rate-limited, parallel, non-blocking RPC
-system, and there's not a mutex in sight.
-</p>
-
-<h3 id="parallel">Parallelization</h3>
-<p>
-Another application of these ideas is to parallelize a calculation
-across multiple CPU cores.  If the calculation can be broken into
-separate pieces, it can be parallelized, with a channel to signal
-when each piece completes.
-</p>
-<p>
-Let's say we have an expensive operation to perform on a vector of items,
-and that the value of the operation on each item is independent,
-as in this idealized example.
-</p>
-<pre>
-type Vector []float64
-
-// Apply the operation to v[i], v[i+1] ... up to v[n-1].
-func (v Vector) DoSome(i, n int, u Vector, c chan int) {
-    for ; i &lt; n; i++ {
-        v[i] += u.Op(v[i])
-    }
-    c &lt;- 1    // signal that this piece is done
-}
-</pre>
-<p>
-We launch the pieces independently in a loop, one per CPU.
-They can complete in any order but it doesn't matter; we just
-count the completion signals by draining the channel after
-launching all the goroutines.
-</p>
-<pre>
-const NCPU = 4  // number of CPU cores
-
-func (v Vector) DoAll(u Vector) {
-    c := make(chan int, NCPU)  // Buffering optional but sensible.
-    for i := 0; i &lt; NCPU; i++ {
-        go v.DoSome(i*len(v)/NCPU, (i+1)*len(v)/NCPU, u, c)
-    }
-    // Drain the channel.
-    for i := 0; i &lt; NCPU; i++ {
-        &lt;-c    // wait for one task to complete
-    }
-    // All done.
-}
-
-</pre>
-
-<p>
-The current implementation of <code>gc</code> (<code>6g</code>, etc.)
-will not parallelize this code by default.
-It dedicates only a single core to user-level processing.  An
-arbitrary number of goroutines can be blocked in system calls, but
-by default only one can be executing user-level code at any time.
-It should be smarter and one day it will be smarter, but until it
-is if you want CPU parallelism you must tell the run-time
-how many goroutines you want executing code simultaneously.  There
-are two related ways to do this.  Either run your job with environment
-variable <code>GOMAXPROCS</code> set to the number of cores to use
-or import the <code>runtime</code> package and call
-<code>runtime.GOMAXPROCS(NCPU)</code>.
-A helpful value might be <code>runtime.NumCPU()</code>, which reports the number
-of logical CPUs on the local machine.
-Again, this requirement is expected to be retired as the scheduling and run-time improve.
-</p>
-
-<h3 id="leaky_buffer">A leaky buffer</h3>
-
-<p>
-The tools of concurrent programming can even make non-concurrent
-ideas easier to express.  Here's an example abstracted from an RPC
-package.  The client goroutine loops receiving data from some source,
-perhaps a network.  To avoid allocating and freeing buffers, it keeps
-a free list, and uses a buffered channel to represent it.  If the
-channel is empty, a new buffer gets allocated.
-Once the message buffer is ready, it's sent to the server on
-<code>serverChan</code>.
-</p>
-<pre>
-var freeList = make(chan *Buffer, 100)
-var serverChan = make(chan *Buffer)
-
-func client() {
-    for {
-        var b *Buffer
-        // Grab a buffer if available; allocate if not.
-        select {
-        case b = &lt;-freeList:
-            // Got one; nothing more to do.
-        default:
-            // None free, so allocate a new one.
-            b = new(Buffer)
-        }
-        load(b)              // Read next message from the net.
-        serverChan &lt;- b      // Send to server.
-    }
-}
-</pre>
-<p>
-The server loop receives each message from the client, processes it,
-and returns the buffer to the free list.
-</p>
-<pre>
-func server() {
-    for {
-        b := &lt;-serverChan    // Wait for work.
-        process(b)
-        // Reuse buffer if there's room.
-        select {
-        case freeList &lt;- b:
-            // Buffer on free list; nothing more to do.
-        default:
-            // Free list full, just carry on.
-        }
-    }
-}
-</pre>
-<p>
-The client attempts to retrieve a buffer from <code>freeList</code>;
-if none is available, it allocates a fresh one.
-The server's send to <code>freeList</code> puts <code>b</code> back
-on the free list unless the list is full, in which case the
-buffer is dropped on the floor to be reclaimed by
-the garbage collector.
-(The <code>default</code> clauses in the <code>select</code>
-statements execute when no other case is ready,
-meaning that the <code>selects</code> never block.)
-This implementation builds a leaky bucket free list
-in just a few lines, relying on the buffered channel and
-the garbage collector for bookkeeping.
-</p>
-
-<h2 id="errors">Errors</h2>
-
-<p>
-Library routines must often return some sort of error indication to
-the caller.  As mentioned earlier, Go's multivalue return makes it
-easy to return a detailed error description alongside the normal
-return value.  By convention, errors have type <code>error</code>,
-a simple built-in interface.
-</p>
-<pre>
-type error interface {
-    Error() string
-}
-</pre>
-<p>
-A library writer is free to implement this interface with a
-richer model under the covers, making it possible not only
-to see the error but also to provide some context.
-For example, <code>os.Open</code> returns an <code>os.PathError</code>.
-</p>
-<pre>
-// PathError records an error and the operation and
-// file path that caused it.
-type PathError struct {
-    Op string    // "open", "unlink", etc.
-    Path string  // The associated file.
-    Err error    // Returned by the system call.
-}
-
-func (e *PathError) Error() string {
-    return e.Op + " " + e.Path + ": " + e.Err.Error()
-}
-</pre>
-<p>
-<code>PathError</code>'s <code>Error</code> generates
-a string like this:
-</p>
-<pre>
-open /etc/passwx: no such file or directory
-</pre>
-<p>
-Such an error, which includes the problematic file name, the
-operation, and the operating system error it triggered, is useful even
-if printed far from the call that caused it;
-it is much more informative than the plain
-"no such file or directory".
-</p>
-
-<p>
-When feasible, error strings should identify their origin, such as by having
-a prefix naming the package that generated the error.  For example, in package
-image, the string representation for a decoding error due to an unknown format
-is "image: unknown format".
-</p>
-
-<p>
-Callers that care about the precise error details can
-use a type switch or a type assertion to look for specific
-errors and extract details.  For <code>PathErrors</code>
-this might include examining the internal <code>Err</code>
-field for recoverable failures.
-</p>
-
-<pre>
-for try := 0; try &lt; 2; try++ {
-    file, err = os.Open(filename)
-    if err == nil {
-        return
-    }
-    if e, ok := err.(*os.PathError); ok &amp;&amp; e.Err == os.ENOSPC {
-        deleteTempFiles()  // Recover some space.
-        continue
-    }
-    return
-}
-</pre>
-
-<p>
-The second <code>if</code> statement here is idiomatic Go.
-The type assertion <code>err.(*os.PathError)</code> is
-checked with the "comma ok" idiom (mentioned <a href="#maps">earlier</a>
-in the context of examining maps).
-If the type assertion fails, <code>ok</code> will be false, and <code>e</code>
-will be <code>nil</code>.
-If it succeeds,  <code>ok</code> will be true, which means the
-error was of type <code>*os.PathError</code>, and then so is <code>e</code>,
-which we can examine for more information about the error.
-</p>
-
-<h3 id="panic">Panic</h3>
-
-<p>
-The usual way to report an error to a caller is to return an
-<code>error</code> as an extra return value.  The canonical
-<code>Read</code> method is a well-known instance; it returns a byte
-count and an <code>error</code>.  But what if the error is
-unrecoverable?  Sometimes the program simply cannot continue.
-</p>
-
-<p>
-For this purpose, there is a built-in function <code>panic</code>
-that in effect creates a run-time error that will stop the program
-(but see the next section).  The function takes a single argument
-of arbitrary type&mdash;often a string&mdash;to be printed as the
-program dies.  It's also a way to indicate that something impossible has
-happened, such as exiting an infinite loop.  In fact, the compiler
-recognizes a <code>panic</code> at the end of a function and
-suppresses the usual check for a <code>return</code> statement.
-</p>
-
-
-<pre>
-// A toy implementation of cube root using Newton's method.
-func CubeRoot(x float64) float64 {
-    z := x/3   // Arbitrary initial value
-    for i := 0; i &lt; 1e6; i++ {
-        prevz := z
-        z -= (z*z*z-x) / (3*z*z)
-        if veryClose(z, prevz) {
-            return z
-        }
-    }
-    // A million iterations has not converged; something is wrong.
-    panic(fmt.Sprintf("CubeRoot(%g) did not converge", x))
-}
-</pre>
-
-<p>
-This is only an example but real library functions should
-avoid <code>panic</code>.  If the problem can be masked or worked
-around, it's always better to let things continue to run rather
-than taking down the whole program.  One possible counterexample
-is during initialization: if the library truly cannot set itself up,
-it might be reasonable to panic, so to speak.
-</p>
-
-<pre>
-var user = os.Getenv("USER")
-
-func init() {
-    if user == "" {
-        panic("no value for $USER")
-    }
-}
-</pre>
-
-<h3 id="recover">Recover</h3>
-
-<p>
-When <code>panic</code> is called, including implicitly for run-time
-errors such as indexing an array out of bounds or failing a type
-assertion, it immediately stops execution of the current function
-and begins unwinding the stack of the goroutine, running any deferred
-functions along the way.  If that unwinding reaches the top of the
-goroutine's stack, the program dies.  However, it is possible to
-use the built-in function <code>recover</code> to regain control
-of the goroutine and resume normal execution.
-</p>
-
-<p>
-A call to <code>recover</code> stops the unwinding and returns the
-argument passed to <code>panic</code>.  Because the only code that
-runs while unwinding is inside deferred functions, <code>recover</code>
-is only useful inside deferred functions.
-</p>
-
-<p>
-One application of <code>recover</code> is to shut down a failing goroutine
-inside a server without killing the other executing goroutines.
-</p>
-
-<pre>
-func server(workChan &lt;-chan *Work) {
-    for work := range workChan {
-        go safelyDo(work)
-    }
-}
-
-func safelyDo(work *Work) {
-    defer func() {
-        if err := recover(); err != nil {
-            log.Println("work failed:", err)
-        }
-    }()
-    do(work)
-}
-</pre>
-
-<p>
-In this example, if <code>do(work)</code> panics, the result will be
-logged and the goroutine will exit cleanly without disturbing the
-others.  There's no need to do anything else in the deferred closure;
-calling <code>recover</code> handles the condition completely.
-</p>
-
-<p>
-Because <code>recover</code> always returns <code>nil</code> unless called directly
-from a deferred function, deferred code can call library routines that themselves
-use <code>panic</code> and <code>recover</code> without failing.  As an example,
-the deferred function in <code>safelyDo</code> might call a logging function before
-calling <code>recover</code>, and that logging code would run unaffected
-by the panicking state.
-</p>
-
-<p>
-With our recovery pattern in place, the <code>do</code>
-function (and anything it calls) can get out of any bad situation
-cleanly by calling <code>panic</code>.  We can use that idea to
-simplify error handling in complex software.  Let's look at an
-idealized excerpt from the <code>regexp</code> package, which reports
-parsing errors by calling <code>panic</code> with a local
-error type.  Here's the definition of <code>Error</code>,
-an <code>error</code> method, and the <code>Compile</code> function.
-</p>
-
-<pre>
-// Error is the type of a parse error; it satisfies the error interface.
-type Error string
-func (e Error) Error() string {
-    return string(e)
-}
-
-// error is a method of *Regexp that reports parsing errors by
-// panicking with an Error.
-func (regexp *Regexp) error(err string) {
-    panic(Error(err))
-}
-
-// Compile returns a parsed representation of the regular expression.
-func Compile(str string) (regexp *Regexp, err error) {
-    regexp = new(Regexp)
-    // doParse will panic if there is a parse error.
-    defer func() {
-        if e := recover(); e != nil {
-            regexp = nil    // Clear return value.
-            err = e.(Error) // Will re-panic if not a parse error.
-        }
-    }()
-    return regexp.doParse(str), nil
-}
-</pre>
-
-<p>
-If <code>doParse</code> panics, the recovery block will set the
-return value to <code>nil</code>&mdash;deferred functions can modify
-named return values.  It then will then check, in the assignment
-to <code>err</code>, that the problem was a parse error by asserting
-that it has the local type <code>Error</code>.
-If it does not, the type assertion will fail, causing a run-time error
-that continues the stack unwinding as though nothing had interrupted
-it.  This check means that if something unexpected happens, such
-as an array index out of bounds, the code will fail even though we
-are using <code>panic</code> and <code>recover</code> to handle
-user-triggered errors.
-</p>
-
-<p>
-With error handling in place, the <code>error</code> method
-makes it easy to report parse errors without worrying about unwinding
-the parse stack by hand.
-</p>
-
-<p>
-Useful though this pattern is, it should be used only within a package.
-<code>Parse</code> turns its internal <code>panic</code> calls into
-<code>error</code> values; it does not expose <code>panics</code>
-to its client.  That is a good rule to follow.
-</p>
-
-<p>
-By the way, this re-panic idiom changes the panic value if an actual
-error occurs.  However, both the original and new failures will be
-presented in the crash report, so the root cause of the problem will
-still be visible.  Thus this simple re-panic approach is usually
-sufficient&mdash;it's a crash after all&mdash;but if you want to
-display only the original value, you can write a little more code to
-filter unexpected problems and re-panic with the original error.
-That's left as an exercise for the reader.
-</p>
-
-
-<h2 id="web_server">A web server</h2>
-
-<p>
-Let's finish with a complete Go program, a web server.
-This one is actually a kind of web re-server.
-Google provides a service at
-<a href="http://chart.apis.google.com">http://chart.apis.google.com</a>
-that does automatic formatting of data into charts and graphs.
-It's hard to use interactively, though,
-because you need to put the data into the URL as a query.
-The program here provides a nicer interface to one form of data: given a short piece of text,
-it calls on the chart server to produce a QR code, a matrix of boxes that encode the
-text.
-That image can be grabbed with your cell phone's camera and interpreted as,
-for instance, a URL, saving you typing the URL into the phone's tiny keyboard.
-</p>
-<p>
-Here's the complete program.
-An explanation follows.
-</p>
-{{code "progs/eff_qr.go"}}
-<p>
-The pieces up to <code>main</code> should be easy to follow.
-The one flag sets a default HTTP port for our server.  The template
-variable <code>templ</code> is where the fun happens. It builds an HTML template
-that will be executed by the server to display the page; more about
-that in a moment.
-</p>
-<p>
-The <code>main</code> function parses the flags and, using the mechanism
-we talked about above, binds the function <code>QR</code> to the root path
-for the server.  Then <code>http.ListenAndServe</code> is called to start the
-server; it blocks while the server runs.
-</p>
-<p>
-<code>QR</code> just receives the request, which contains form data, and
-executes the template on the data in the form value named <code>s</code>.
-</p>
-<p>
-The template package is powerful;
-this program just touches on its capabilities.
-In essence, it rewrites a piece of text on the fly by substituting elements derived
-from data items passed to <code>templ.Execute</code>, in this case the
-form value.  
-Within the template text (<code>templateStr</code>),
-double-brace-delimited pieces denote template actions.
-The piece from <code>{{html "{{if .}}"}}</code>
-to <code>{{html "{{end}}"}}</code> executes only if the value of the current data item, called <code>.</code> (dot),
-is non-empty.
-That is, when the string is empty, this piece of the template is suppressed.
-</p>
-<p>
-The snippet <code>{{html "{{urlquery .}}"}}</code> says to process the data with the function
-<code>urlquery</code>, which sanitizes the query string
-for safe display on the web page.
-</p>
-<p>
-The rest of the template string is just the HTML to show when the page loads.
-If this is too quick an explanation, see the <a href="/pkg/template/">documentation</a>
-for the template package for a more thorough discussion.
-</p>
-<p>
-And there you have it: a useful webserver in a few lines of code plus some
-data-driven HTML text.
-Go is powerful enough to make a lot happen in a few lines.
-</p>
-
-<!--
-TODO
-<pre>
-verifying implementation
-type Color uint32
-    
-// Check that Color implements image.Color and image.Image
-var _ image.Color = Black
-var _ image.Image = Black
-</pre>
--->
-
diff --git a/doc/gccgo_install.html b/doc/gccgo_install.html
index ae359437a..a8d7396e5 100644
--- a/doc/gccgo_install.html
+++ b/doc/gccgo_install.html
@@ -4,36 +4,59 @@
 }-->
 
 <p>
-This document explains how to use <code>gccgo</code>, a compiler for
-the Go language.  The <code>gccgo</code> compiler is a new frontend
-for <code>gcc</code>, the widely used GNU compiler.  Although the
-frontend itself is under a BSD-style license, <code>gccgo</code> is
-normally used as part of <code>gcc</code> and is then covered by
+This document explains how to use gccgo, a compiler for
+the Go language.  The gccgo compiler is a new frontend
+for GCC, the widely used GNU compiler.  Although the
+frontend itself is under a BSD-style license, gccgo is
+normally used as part of GCC and is then covered by
 the <a href="http://www.gnu.org/licenses/gpl.html">GNU General Public
-License</a>.
+License</a> (the license covers gccgo itself as part of GCC; it
+does not cover code generated by gccgo).
 </p>
 
 <p>
-Note that <code>gccgo</code> is not the <code>6g</code> compiler; see
-the <a href="/doc/install">Installing Go</a> instructions for that
+Note that gccgo is not the <code>gc</code> compiler; see
+the <a href="/doc/install.html">Installing Go</a> instructions for that
 compiler.
 </p>
 
+<h2 id="Releases">Releases</h2>
+
+<p>
+The simplest way to install gccgo is to install a GCC binary release
+built to include Go support.  GCC binary releases are available from
+<a href="http://gcc.gnu.org/install/binaries.html">various
+websites</a> and are typically included as part of GNU/Linux
+distributions.  We expect that most people who build these binaries
+will include Go support.
+</p>
+
+<p>
+The GCC 4.7.0 release includes Go support that is very close to
+<a href="/doc/go1.html">Go 1</a>.  Due to release timing it will not
+include the last few changes to the Go 1 libraries.  The GCC 4.7.1
+release should include a complete Go 1 compiler and libraries.
+</p>
+
 <h2 id="Source_code">Source code</h2>
 
 <p>
-The <code>gccgo</code> source code is accessible via Subversion.  The
-<code>gcc</code> web site
+If you cannot use a release, or prefer to build gccgo for
+yourself, 
+the gccgo source code is accessible via Subversion.  The
+GCC web site
 has <a href="http://gcc.gnu.org/svn.html">instructions for getting the
-<code>gcc</code> source code</a>.  The <code>gccgo</code> source code
-is a branch of the main <code>gcc</code> code
+GCC source code</a>.  The gccgo source code is included.  As a
+convenience, a stable version of the Go support is available in
+a branch of the main GCC code
 repository: <code>svn://gcc.gnu.org/svn/gcc/branches/gccgo</code>.
+This branch is periodically updated with stable Go compiler sources.
 </p>
 
 <p>
 Note that although <code>gcc.gnu.org</code> is the most convenient way
-to get the source code for the compiler, that is not where the master
-sources live.  If you want to contribute changes to the gccgo
+to get the source code for the Go frontend, it is not where the master
+sources live.  If you want to contribute changes to the Go frontend
 compiler, see <a href="/doc/gccgo_contribute.html">Contributing to
 gccgo</a>.
 </p>
@@ -42,29 +65,37 @@ gccgo</a>.
 <h2 id="Building">Building</h2>
 
 <p>
-Building <code>gccgo</code> is just like building <code>gcc</code>
+Building gccgo is just like building GCC
 with one or two additional options.  See
 the <a href="http://gcc.gnu.org/install/">instructions on the gcc web
 site</a>.  When you run <code>configure</code>, add the
 option <code>--enable-languages=c,c++,go</code> (along with other
 languages you may want to build).  If you are targeting a 32-bit x86,
-then you will want to build <code>gccgo</code> to default to
+then you will want to build gccgo to default to
 supporting locked compare and exchange instructions; do this by also
 using the <code>configure</code> option <code>--with-arch=i586</code>
 (or a newer architecture, depending on where you need your programs to
-run).
+run).  If you are targeting a 64-bit x86, but sometimes want to use
+the <code>-m32</code> option, then use the <code>configure</code>
+option <code>--with-arch-32=i586</code>.
 </p>
 
+<h3 id="Gold">Gold</h3>
+
 <p>
-On x86 GNU/Linux systems the <code>gccgo</code> compiler is able to
+On x86 GNU/Linux systems the gccgo compiler is able to
 use a small discontiguous stack for goroutines.  This permits programs
 to run many more goroutines, since each goroutine can use a relatively
-small stack.  Doing this requires using a development version of
-the <code>gold</code> linker.  The easiest way to do this is to build
-the GNU binutils, using <code>--enable-gold=default</code> when you run
-the <code>configure</code> script, and to
-use <code>--with-ld=GOLD_BINARY</code> when you
-configure <code>gccgo</code>.  A typical sequence would look like
+small stack.  Doing this requires using the gold linker version 2.22
+or later.  You can either install GNU binutils 2.22 or later, or you
+can build gold yourself.
+</p>
+
+<p>
+To build gold yourself, build the GNU binutils,
+using <code>--enable-gold=default</code> when you run
+the <code>configure</code> script.  Before building, you must install
+the flex and bison packages.  A typical sequence would look like
 this (you can replace <code>/opt/gold</code> with any directory to
 which you have write access):
 </p>
@@ -72,6 +103,7 @@ which you have write access):
 <pre>
 cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src login
 [password is "anoncvs"]
+[The next command will create a directory named src, not binutils]
 cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src co binutils
 mkdir binutils-objdir
 cd binutils-objdir
@@ -81,29 +113,69 @@ make install
 </pre>
 
 <p>
-A number of prerequisites are required to build <code>gcc</code>, as
-described on the <a href="http://gcc.gnu.org/">gcc web site</a>.  If
-those are all available, then a typical build and install sequence
-would look like this (only use the <code>--with-ld</code> option if
-you built and installed the gold linker as described above):
+However you install gold, when you configure gccgo, use the
+option <code>--with-ld=<var>GOLD_BINARY</var></code>.
+</p>
+
+<h3 id="Prerequisites">Prerequisites</h3>
+
+<p>
+A number of prerequisites are required to build GCC, as
+described on
+the <a href="http://gcc.gnu.org/install/prerequisites.html">gcc web
+site</a>.  It is important to install all the prerequisites before
+running the gcc <code>configure</code> script.
+
+<h3 id="Build_commands">Build commands</h3>
+
+<p>
+Once all the prerequisites are installed, then a typical build and
+install sequence would look like this (only use
+the <code>--with-ld</code> option if you are using the gold linker as
+described above):
 </p>
 
 <pre>
 svn checkout svn://gcc.gnu.org/svn/gcc/branches/gccgo gccgo
 mkdir objdir
 cd objdir
-../gccgo/configure --enable-languages=c,c++,go --with-ld=/opt/gold/bin/ld
+../gccgo/configure --prefix=/opt/gccgo --enable-languages=c,c++,go --with-ld=/opt/gold/bin/ld
 make
 make install
 </pre>
 
+<h3 id="Ubuntu">A note on Ubuntu</h3>
+
+<p>
+Current versions of Ubuntu and current versions of gcc disagree on
+where system libraries and header files are found.  This is not a
+gccgo issue, and we hope this will be resolved soon.  Until it is,
+setting these environment variables while configuring and building
+gccgo may fix the problem.
+</p>
+
+<pre>
+LIBRARY_PATH=/usr/lib/x86_64-linux-gnu
+C_INCLUDE_PATH=/usr/include/x86_64-linux-gnu
+CPLUS_INCLUDE_PATH=/usr/include/x86_64-linux-gnu
+export LIBRARY_PATH C_INCLUDE_PATH CPLUS_INCLUDE_PATH
+</pre>
+
 <h2 id="Using_gccgo">Using gccgo</h2>
 
 <p>
-The <code>gccgo</code> compiler works like other gcc frontends.
+The gccgo compiler works like other gcc frontends.  The gccgo
+installation does not currently include a version of
+the <code>go</code> command.  However if you have the <code>go</code>
+command from an installation of the <code>gc</code> compiler, you can
+use it with gccgo by passing the option <code>-compiler gccgo</code>
+to <code>go build</code> or <code>go install</code> or <code>go
+test</code>.
+</p>
 
 <p>
-To compile a file:
+To compile a file without using the <code>go</code> command:
+</p>
 
 <pre>
 gccgo -c file.go
@@ -112,6 +184,7 @@ gccgo -c file.go
 <p>
 That produces <code>file.o</code>. To link files together to form an
 executable:
+</p>
 
 <pre>
 gccgo -o file file.o
@@ -119,44 +192,68 @@ gccgo -o file file.o
 
 <p>
 To run the resulting file, you will need to tell the program where to
-find the compiled Go packages. This can be done either by setting
-<code>LD_LIBRARY_PATH</code> in your environment:
+find the compiled Go packages.  There are a few ways to do this:
+</p>
+
+<ul>
+<li>
+<p>
+Set the <code>LD_LIBRARY_PATH</code> environment variable:
+</p>
 
 <pre>
-LD_LIBRARY_PATH=/usr/lib/gcc/MACHINE/VERSION
+LD_LIBRARY_PATH=${prefix}/lib/gcc/MACHINE/VERSION
+[or]
+LD_LIBRARY_PATH=${prefix}/lib64/gcc/MACHINE/VERSION
+export LD_LIBRARY_PATH
 </pre>
 
 <p>
-or by passing a <code>-Wl,-R</code> option when you link:
+Here <code>${prefix}</code> is the <code>--prefix</code> option used
+when building gccgo.  For a binary install this is
+normally <code>/usr</code>.  Whether to use <code>lib</code>
+or <code>lib64</code> depends on the target.
+Typically <code>lib64</code> is correct for x86_64 systems,
+and <code>lib</code> is correct for other systems.  The idea is to
+name the directory where <code>libgo.so</code> is found.
+</p>
 
-<pre>
-gccgo -o file file.o -Wl,-R,/usr/lib/gcc/MACHINE/VERSION
-</pre>
+</li>
 
+<li>
 <p>
-or you can use the <code>-static-libgo</code> link-time option to link
-statically against libgo, or you can do a fully static link (static
-linking is the default for the <code>6l</code> Go linker).  On most
-systems, a static link will look something like:
+Passing a <code>-Wl,-R</code> option when you link:
+</p>
 
 <pre>
-gccgo -o file file.o -static -L /usr/lib/nptl -lgobegin -lgo -lpthread
+gccgo -o file file.o -Wl,-R,${prefix}/lib/gcc/MACHINE/VERSION
+[or]
+gccgo -o file file.o -Wl,-R,${prefix}/lib64/gcc/MACHINE/VERSION
 </pre>
+</li>
 
+<li>
 <p>
-You may get a warning about not creating an <code>.eh_frame_hdr</code>
-section; this has nothing to do with Go, and may be ignored. In the
-future the requirement of explicitly specifying
-<code>-L /usr/lib/nptl -lgobegin -lgo -lpthread</code>
-may be removed.
+Use the <code>-static-libgo</code> option to link statically against
+the compiled packages.
+</p>
+</li>
 
+<li>
+<p>
+Use the <code>-static</code> option to do a fully static link (the
+default for the <code>gc</code> compiler).
+</p>
+</li>
+</ul>
 
 <h2 id="Options">Options</h2>
 
 <p>
-The <code>gccgo</code> compiler supports all <code>gcc</code> options
+The gccgo compiler supports all GCC options
 that are language independent, notably the <code>-O</code>
 and <code>-g</code> options.
+</p>
 
 <p>
 The <code>-fgo-prefix=PREFIX</code> option may be used to set a unique
@@ -165,28 +262,24 @@ use with large programs that contain many packages, in order to allow
 multiple packages to use the same identifier as the package name.
 The <code>PREFIX</code> may be any string; a good choice for the
 string is the directory where the package will be installed.
-
-<p>
-The <code>-fno-require-return-statement</code> option may be used to
-disable the compiler error about functions missing return statements.
-Note that there is no way to disable this error in <code>6g</code>.
+</p>
 
 <p>
 The <code>-I</code> and <code>-L</code> options, which are synonyms
 for the compiler, may be used to set the search path for finding
 imports.
-
+</p>
 
 <h2 id="Imports">Imports</h2>
 
 <p>
-When you compile a file which exports something, the export
-information will be stored directly in the object file. When
-you import a package, you must tell <code>gccgo</code> how to
+When you compile a file that exports something, the export
+information will be stored directly in the object file.  When
+you import a package, you must tell gccgo how to
 find the file.
 
 <p>
-When you import the package <var>FILE</var> with <code>gccgo</code>,
+When you import the package <var>FILE</var> with gccgo,
 it will look for the import data in the following files, and use the
 first one that it finds.
 
@@ -201,21 +294,25 @@ first one that it finds.
 <code><var>FILE</var>.gox</code>, when used, will typically contain
 nothing but export data. This can be generated from
 <code><var>FILE</var>.o</code> via
+</p>
 
 <pre>
 objcopy -j .go_export FILE.o FILE.gox
 </pre>
 
 <p>
-The <code>gccgo</code> compiler will look in the current
-directory for import files. In more complex scenarios you
+The gccgo compiler will look in the current
+directory for import files.  In more complex scenarios you
 may pass the <code>-I</code> or <code>-L</code> option to
-<code>gccgo</code>. Both options take directories to search. The
+gccgo.  Both options take directories to search. The
 <code>-L</code> option is also passed to the linker.
+</p>
 
-The <code>gccgo</code> compiler does not currently (2009-11-06) record
+<p>
+The gccgo compiler does not currently (2012-03-20) record
 the file name of imported packages in the object file. You must
 arrange for the imported data to be linked into the program.
+</p>
 
 <pre>
 gccgo -c mypackage.go              # Exports mypackage
@@ -223,48 +320,41 @@ gccgo -c main.go                   # Imports mypackage
 gccgo -o main main.o mypackage.o   # Explicitly links with mypackage.o
 </pre>
 
-<h2 id="Unimplemented">Unimplemented</h2>
-
-<p>
-Some Go features are not yet implemented in <code>gccgo</code>.  As of
-2010-08-23, the following are not implemented:
-
-<ul>
-<li>goroutines are implemented as NPTL threads.  If you can not use
-    the gold linker as described above, they are created with a fixed
-    stack size, and the number of goroutines that may be created at
-    one time is limited.
-</ul>
-
 <h2 id="Debugging">Debugging</h2>
 
 <p>
 If you use the <code>-g</code> option when you compile, you can run
-<code>gdb</code> on your executable.  The debugger doesn't (yet)
-know anything about Go. However, you can set breakpoints, single-step,
+<code>gdb</code> on your executable.  The debugger has only limited
+knowledge about Go.  You can set breakpoints, single-step,
 etc.  You can print variables, but they will be printed as though they
-had C/C++ types. For numeric types this doesn't matter. Go strings
-will show up as pointers to structures; to see the value
-<code>print *stringvar</code>. In general Go strings, maps, channels
-and interfaces are always represented as C pointers.
+had C/C++ types.  For numeric types this doesn't matter.  Go strings
+and interfaces will show up as two-element structures.  Go
+maps and channels are always represented as C pointers to run-time
+structures.
+</p>
 
 <h2 id="C_Interoperability">C Interoperability</h2>
 
 <p>
-When using <code>gccgo</code> there is limited interoperability with C,
+When using gccgo there is limited interoperability with C,
 or with C++ code compiled using <code>extern "C"</code>.
+</p>
 
 <h3 id="Types">Types</h3>
 
 <p>
 Basic types map directly: an <code>int</code> in Go is an <code>int</code>
-in C, etc. Go <code>byte</code> is equivalent to C <code>unsigned char</code>.
+in C, an <code>int32</code> is an <code>int32_t</code>,
+etc.  Go <code>byte</code> is equivalent to C <code>unsigned
+char</code>.
 Pointers in Go are pointers in C. A Go <code>struct</code> is the same as C
 <code>struct</code> with the same fields and types.
+</p>
 
 <p>
 The Go <code>string</code> type is currently defined as a two-element
 structure (this is <b style="color: red;">subject to change</b>):
+</p>
 
 <pre>
 struct __go_string {
@@ -279,10 +369,12 @@ array in Go is equivalent to a C pointer to the
 equivalent of the element type.
 For example, Go <code>*[10]int</code> is equivalent to C <code>int*</code>,
 assuming that the C pointer does point to 10 elements.
+</p>
 
 <p>
 A slice in Go is a structure.  The current definition is
 (this is <b style="color: red;">subject to change</b>):
+</p>
 
 <pre>
 struct __go_slice {
@@ -294,9 +386,10 @@ struct __go_slice {
 
 <p>
 The type of a Go function with no receiver is equivalent to a C function
-whose parameter types are equivalent. When a Go function returns more
-than one value, the C function returns a struct. For example, these
+whose parameter types are equivalent.  When a Go function returns more
+than one value, the C function returns a struct.  For example, these
 functions have equivalent types:
+</p>
 
 <pre>
 func GoFunction(int) (int, float64)
@@ -305,7 +398,9 @@ struct { int i; float64 f; } CFunction(int)
 
 <p>
 A pointer to a Go function is equivalent to a pointer to a C function
-when the functions have equivalent types.
+when the functions have equivalent types (this is
+<b style="color: red;">subject to change</b>).
+</p>
 
 <p>
 Go <code>interface</code>, <code>channel</code>, and <code>map</code>
@@ -317,6 +412,7 @@ which one is difficult to predict in general; use a cast. C <code>union</code>
 types have no corresponding Go type. C <code>struct</code> types containing
 bitfields have no corresponding Go type. C++ <code>class</code> types have
 no corresponding Go type.
+</p>
 
 <p>
 Memory allocation is completely different between C and Go, as Go uses
@@ -328,33 +424,38 @@ while the Go side still has a copy the program will fail. When passing a
 pointer from Go to C, the Go function must retain a visible copy of it in
 some Go variable. Otherwise the Go garbage collector may delete the
 pointer while the C function is still using it.
+</p>
 
 <h3 id="Function_names">Function names</h3>
 
 <p>
 Go code can call C functions directly using a Go extension implemented
-in <code>gccgo</code>: a function declaration may be followed by
-<code>__asm__("NAME")</code>. For example, here is how the C function
+in gccgo: a function declaration may be preceded by
+<code>//extern NAME</code>.  For example, here is how the C function
 <code>open</code> can be declared in Go:
+</p>
 
 <pre>
-func c_open(name *byte, mode int, perm int) int __asm__ ("open");
+//extern open
+func c_open(name *byte, mode int, perm int) int
 </pre>
 
 <p>
-The C function naturally expects a nul terminated string, which in
+The C function naturally expects a NUL-terminated string, which in
 Go is equivalent to a pointer to an array (not a slice!) of
 <code>byte</code> with a terminating zero byte. So a sample call
-from Go would look like (after importing the <code>os</code> package):
+from Go would look like (after importing the <code>syscall</code> package):
+</p>
 
 <pre>
 var name = [4]byte{'f', 'o', 'o', 0};
-i := c_open(&amp;name[0], os.O_RDONLY, 0);
+i := c_open(&amp;name[0], syscall.O_RDONLY, 0);
 </pre>
 
 <p>
 (this serves as an example only, to open a file in Go please use Go's
 <code>os.Open</code> function instead).
+</p>
 
 <p>
 The name of Go functions accessed from C is subject to change. At present
@@ -363,8 +464,8 @@ the name of a Go function that does not have a receiver is
 the <code>-fgo-prefix</code> option used when the package is compiled;
 if the option is not used, the default is <code>go</code>.
 To call the function from C you must set the name using
-a <code>gcc</code> extension similar to the <code>gccgo</code>
-extension.
+a GCC extension.
+</p>
 
 <pre>
 extern int go_function(int) __asm__ ("myprefix.mypackage.Function");
@@ -374,37 +475,35 @@ extern int go_function(int) __asm__ ("myprefix.mypackage.Function");
 Automatic generation of Go declarations from C source code</h3>
 
 <p>
-The Go version of <code>gcc</code> supports automatically generating
-Go declarations from C code. The facility is rather awkward at present,
-and a better mechanism is under development.
+The Go version of GCC supports automatically generating
+Go declarations from C code. The facility is rather awkward, and most
+users should use the <a href="/cmd/cgo">cgo</a> program with
+the <code>-gccgo</code> option instead.
+</p>
 
 <p>
-Compile your C code as usual, but replace <code>-c</code> with
-<code>-S&nbsp;-ggo</code>. The result will be an assembler file
-with a <code>.s</code> extension. This assembler file will contain
-comments beginning with #GO. Those comments are declarations in the Go
-language for the C types, variables and functions declared in the C code.
-C types which can not be represented in Go will contain the string INVALID.
-Unsupported macro definitions will be recorded as <code>unknowndefine</code>,
-and uses of <code>#undef</code> will be recorded as <code>undef</code>.
-So it is very approximately possible to get Go code by running
-
-<pre>
-gcc -S -ggo foo.c
-grep '#GO' foo.s | grep -v INVALID | grep -v unknowndefine | grep -v undef > foo.go
-</pre>
+Compile your C code as usual, and add the option
+<code>-fdump-go-spec=<var>FILENAME</var></code>.  This will create the
+file <code><var>FILENAME</var></code> as a side effect of the
+compilation.  This file will contain Go declarations for the types,
+variables and functions declared in the C code.  C types that can not
+be represented in Go will be recorded as comments in the Go code.  The
+generated file will not have a <code>package</code> declaration, but
+can otherwise be compiled directly by gccgo.
+</p>
 
 <p>
 This procedure is full of unstated caveats and restrictions and we make no
 guarantee that it will not change in the future. It is more useful as a
 starting point for real Go code than as a regular procedure.
+</p>
 
 <h2 id="RTEMS_Port">RTEMS Port</h2>
 <p>
-The <code>gccgo</code> compiler has been ported to <a href="http://www.rtems.com/">
+The gccgo compiler has been ported to <a href="http://www.rtems.com/">
 <code>RTEMS</code></a>. <code>RTEMS</code> is a real-time executive
 that provides a high performance environment for embedded applications
-on a range of processors and embedded hardware. The current <code>gccgo</code>
+on a range of processors and embedded hardware. The current gccgo
 port is for x86. The goal is to extend the port to most of the
 <a href="http://www.rtems.org/wiki/index.php/SupportedCPUs">
 architectures supported by <code>RTEMS</code></a>. For more information on the port,
diff --git a/doc/go-logo-black.png b/doc/go-logo-black.png
index 29be31943..3077ebdad 100644
--- a/doc/go-logo-black.png
+++ b/doc/go-logo-black.png
diff --git a/doc/go-logo-blue.png b/doc/go-logo-blue.png
index b9eac2727..8d43a5677 100644
--- a/doc/go-logo-blue.png
+++ b/doc/go-logo-blue.png
diff --git a/doc/go-logo-white.png b/doc/go-logo-white.png
index 4011069eb..fa29169fa 100644
--- a/doc/go-logo-white.png
+++ b/doc/go-logo-white.png
diff --git a/doc/go1.html b/doc/go1.html
index 8b67cd3aa..dcc3300d3 100644
--- a/doc/go1.html
+++ b/doc/go1.html
@@ -1,11 +1,7 @@
 <!--{
-	"Title": "Go 1 Release Notes"
+	"Title": "Go 1 Release Notes",
+	"Template": true
 }-->
-<!--
-  DO NOT EDIT: created by
-    tmpltohtml go1.tmpl
--->
-
 
 <h2 id="introduction">Introduction to Go 1</h2>
 
@@ -64,9 +60,7 @@ However, <code>append</code> did not provide a way to append a string to a <code
 which is another common case.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/greeting := ..byte/` `/append.*hello/`}}
--->    greeting := []byte{}
-    greeting = append(greeting, []byte(&#34;hello &#34;)...)</pre>
+{{code "/doc/progs/go1.go" `/greeting := ..byte/` `/append.*hello/`}}
 
 <p>
 By analogy with the similar property of <code>copy</code>, Go 1
@@ -75,8 +69,7 @@ slice, reducing the friction between strings and byte slices.
 The conversion is no longer necessary:
 </p>
 
-<pre><!--{{code "progs/go1.go" `/append.*world/`}}
--->    greeting = append(greeting, &#34;world&#34;...)</pre>
+{{code "/doc/progs/go1.go" `/append.*world/`}}
 
 <p>
 <em>Updating</em>:
@@ -126,35 +119,7 @@ type specification for the elements' initializers if they are of pointer type.
 All four of the initializations in this example are legal; the last one was illegal before Go 1.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/type Date struct/` `/STOP/`}}
--->    type Date struct {
-        month string
-        day   int
-    }
-    // Struct values, fully qualified; always legal.
-    holiday1 := []Date{
-        Date{&#34;Feb&#34;, 14},
-        Date{&#34;Nov&#34;, 11},
-        Date{&#34;Dec&#34;, 25},
-    }
-    // Struct values, type name elided; always legal.
-    holiday2 := []Date{
-        {&#34;Feb&#34;, 14},
-        {&#34;Nov&#34;, 11},
-        {&#34;Dec&#34;, 25},
-    }
-    // Pointers, fully qualified, always legal.
-    holiday3 := []*Date{
-        &amp;Date{&#34;Feb&#34;, 14},
-        &amp;Date{&#34;Nov&#34;, 11},
-        &amp;Date{&#34;Dec&#34;, 25},
-    }
-    // Pointers, type name elided; legal in Go 1.
-    holiday4 := []*Date{
-        {&#34;Feb&#34;, 14},
-        {&#34;Nov&#34;, 11},
-        {&#34;Dec&#34;, 25},
-    }</pre>
+{{code "/doc/progs/go1.go" `/type Date struct/` `/STOP/`}}
 
 <p>
 <em>Updating</em>:
@@ -183,14 +148,7 @@ In Go 1, code that uses goroutines can be called from
 without introducing a deadlock.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/PackageGlobal/` `/^}/`}}
--->var PackageGlobal int
-
-func init() {
-    c := make(chan int)
-    go initializationFunction(c)
-    PackageGlobal = &lt;-c
-}</pre>
+{{code "/doc/progs/go1.go" `/PackageGlobal/` `/^}/`}}
 
 <p>
 <em>Updating</em>:
@@ -231,14 +189,7 @@ when appropriate. For instance, the functions <code>unicode.ToLower</code> and
 relatives now take and return a <code>rune</code>.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/STARTRUNE/` `/ENDRUNE/`}}
--->    delta := &#39;δ&#39; // delta has type rune.
-    var DELTA rune
-    DELTA = unicode.ToUpper(delta)
-    epsilon := unicode.ToLower(DELTA + 1)
-    if epsilon != &#39;δ&#39;+1 {
-        log.Fatal(&#34;inconsistent casing for Greek&#34;)
-    }</pre>
+{{code "/doc/progs/go1.go" `/STARTRUNE/` `/ENDRUNE/`}}
 
 <p>
 <em>Updating</em>:
@@ -287,8 +238,7 @@ In Go 1, that syntax has gone; instead there is a new built-in
 function, <code>delete</code>.  The call
 </p>
 
-<pre><!--{{code "progs/go1.go" `/delete\(m, k\)/`}}
--->    delete(m, k)</pre>
+{{code "/doc/progs/go1.go" `/delete\(m, k\)/`}}
 
 <p>
 will delete the map entry retrieved by the expression <code>m[k]</code>.
@@ -327,12 +277,7 @@ This change means that code that depends on iteration order is very likely to br
 Just as important, it allows the map implementation to ensure better map balancing even when programs are using range loops to select an element from a map.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/Sunday/` `/^	}/`}}
--->    m := map[string]int{&#34;Sunday&#34;: 0, &#34;Monday&#34;: 1}
-    for name, value := range m {
-        // This loop should not assume Sunday will be visited first.
-        f(name, value)
-    }</pre>
+{{code "/doc/progs/go1.go" `/Sunday/` `/^	}/`}}
 
 <p>
 <em>Updating</em>:
@@ -367,17 +312,7 @@ proceed in left-to-right order.
 These examples illustrate the behavior.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/sa :=/` `/then sc.0. = 2/`}}
--->    sa := []int{1, 2, 3}
-    i := 0
-    i, sa[i] = 1, 2 // sets i = 1, sa[0] = 2
-
-    sb := []int{1, 2, 3}
-    j := 0
-    sb[j], j = 2, 1 // sets sb[0] = 2, j = 1
-
-    sc := []int{1, 2, 3}
-    sc[0], sc[0] = 1, 2 // sets sc[0] = 1, then sc[0] = 2 (so sc[0] = 2 at end)</pre>
+{{code "/doc/progs/go1.go" `/sa :=/` `/then sc.0. = 2/`}}
 
 <p>
 <em>Updating</em>:
@@ -504,18 +439,7 @@ provided they are composed from elements for which equality is also defined,
 using element-wise comparison.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/type Day struct/` `/Printf/`}}
--->    type Day struct {
-        long  string
-        short string
-    }
-    Christmas := Day{&#34;Christmas&#34;, &#34;XMas&#34;}
-    Thanksgiving := Day{&#34;Thanksgiving&#34;, &#34;Turkey&#34;}
-    holiday := map[Day]bool{
-        Christmas:    true,
-        Thanksgiving: true,
-    }
-    fmt.Printf(&#34;Christmas is a holiday: %t\n&#34;, holiday[Christmas])</pre>
+{{code "/doc/progs/go1.go" `/type Day struct/` `/Printf/`}}
 
 <p>
 Second, Go 1 removes the definition of equality for function values,
@@ -734,7 +658,7 @@ Code that uses the other packages (there should be almost zero) will need to be
 <h3 id="subrepo">Packages moving to subrepositories</h3>
 
 <p>
-Go 1 has moved a number of packages into sub-repositories of
+Go 1 has moved a number of packages into other repositories, usually sub-repositories of
 <a href="http://code.google.com/p/go/">the main Go repository</a>.
 This table lists the old and new import paths:
 
@@ -779,6 +703,10 @@ This table lists the old and new import paths:
 </tr>
 <tr><td>encoding/git85</td> <td>code.google.com/p/go.codereview/git85</tr>
 <tr><td>patch</td> <td>code.google.com/p/go.codereview/patch</tr>
+<tr>
+<td colspan="2"><hr></td>
+</tr>
+<tr><td>exp/wingui</td> <td>code.google.com/p/gowingui</tr>
 </table>
 
 <p>
@@ -827,16 +755,7 @@ The <code>fmt</code> library automatically invokes <code>Error</code>, as it alr
 does for <code>String</code>, for easy printing of error values.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/START ERROR EXAMPLE/` `/END ERROR EXAMPLE/`}}
--->type SyntaxError struct {
-    File    string
-    Line    int
-    Message string
-}
-
-func (se *SyntaxError) Error() string {
-    return fmt.Sprintf(&#34;%s:%d: %s&#34;, se.File, se.Line, se.Message)
-}</pre>
+{{code "/doc/progs/go1.go" `/START ERROR EXAMPLE/` `/END ERROR EXAMPLE/`}}
 
 <p>
 All standard packages have been updated to use the new interface; the old <code>os.Error</code> is gone.
@@ -854,8 +773,7 @@ func New(text string) error
 to turn a string into an error. It replaces the old <code>os.NewError</code>.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/ErrSyntax/`}}
--->    var ErrSyntax = errors.New(&#34;syntax error&#34;)</pre>
+{{code "/doc/progs/go1.go" `/ErrSyntax/`}}
 		
 <p>
 <em>Updating</em>:
@@ -879,7 +797,7 @@ This behavior was unpleasant and unportable.
 In Go 1, the
 <a href="/pkg/syscall/"><code>syscall</code></a>
 package instead returns an <code>error</code> for system call errors.
-On Unix, the implementation is done by a 
+On Unix, the implementation is done by a
 <a href="/pkg/syscall/#Errno"><code>syscall.Errno</code></a> type
 that satisfies <code>error</code> and replaces the old <code>os.Errno</code>.
 </p>
@@ -906,7 +824,7 @@ and no distinction between absolute times and durations.
 
 <p>
 One of the most sweeping changes in the Go 1 library is therefore a
-complete redesign of the 
+complete redesign of the
 <a href="/pkg/time/"><code>time</code></a> package.
 Instead of an integer number of nanoseconds as an <code>int64</code>,
 and a separate <code>*time.Time</code> type to deal with human
@@ -945,17 +863,7 @@ returns a <code>time.Time</code> value rather than, in the old
 API, an integer nanosecond count since the Unix epoch.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/sleepUntil/` `/^}/`}}
--->// sleepUntil sleeps until the specified time. It returns immediately if it&#39;s too late.
-func sleepUntil(wakeup time.Time) {
-    now := time.Now() // A Time.
-    if !wakeup.After(now) {
-        return
-    }
-    delta := wakeup.Sub(now) // A Duration.
-    fmt.Printf(&#34;Sleeping for %.3fs\n&#34;, delta.Seconds())
-    time.Sleep(delta)
-}</pre>
+{{code "/doc/progs/go1.go" `/sleepUntil/` `/^}/`}}
 
 <p>
 The new types, methods, and constants have been propagated through
@@ -1103,7 +1011,7 @@ to be implemented in the future.
 No changes will be needed.
 </p>
 
-<h3 id="encoding_binary">The encoding/binary package</h3>               
+<h3 id="encoding_binary">The encoding/binary package</h3>
 
 <p>
 In Go 1, the <code>binary.TotalSize</code> function has been replaced by
@@ -1192,8 +1100,7 @@ Values for such flags must be given units, just as <code>time.Duration</code>
 formats them: <code>10s</code>, <code>1h30m</code>, etc.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/timeout/`}}
--->var timeout = flag.Duration(&#34;timeout&#34;, 30*time.Second, &#34;how long to wait for completion&#34;)</pre>
+{{code "/doc/progs/go1.go" `/timeout/`}}
 
 <p>
 <em>Updating</em>:
@@ -1249,7 +1156,7 @@ The <a href="/pkg/go/printer/"><code>go/printer</code></a> package supports an a
 configuration mode <a href="/pkg/go/printer/#Mode"><code>SourcePos</code></a>;
 if set, the printer will emit <code>//line</code> comments such that the generated
 output contains the original source code position information. The new type
-<a href="/pkg/go/printer/#CommentedNode"><code>CommentedNode</code></a> can be  
+<a href="/pkg/go/printer/#CommentedNode"><code>CommentedNode</code></a> can be
 used to provide comments associated with an arbitrary
 <a href="/pkg/go/ast/#Node"><code>ast.Node</code></a> (until now only
 <a href="/pkg/go/ast/#File"><code>ast.File</code></a> carried comment information).
@@ -1316,7 +1223,7 @@ to run-time errors.
 
 <p>
 In Go 1, the definition of <a href="/pkg/hash/#Hash"><code>hash.Hash</code></a> includes
-a new method, <code>BlockSize</code>.  This new method is used primarily in the 
+a new method, <code>BlockSize</code>.  This new method is used primarily in the
 cryptographic libraries.
 </p>
 
@@ -1502,7 +1409,7 @@ Running <code>go</code> <code>fix</code> will update almost all code affected by
 <h3 id="log_syslog">The log/syslog package</h3>
 
 <p>
-In Go 1, the <a href="/pkg/log/syslog/#NewLogger"><code>syslog.NewLogger</code></a>     
+In Go 1, the <a href="/pkg/log/syslog/#NewLogger"><code>syslog.NewLogger</code></a>
 function returns an error as well as a <code>log.Logger</code>.
 </p>
 
@@ -1517,7 +1424,7 @@ What little code is affected will be caught by the compiler and must be updated
 In Go 1, the <a href="/pkg/mime/#FormatMediaType"><code>FormatMediaType</code></a> function
 of the <code>mime</code> package has  been simplified to make it
 consistent with
-<a href="/pkg/mime/#ParseMediaType"><code>ParseMediaType</code></a>. 
+<a href="/pkg/mime/#ParseMediaType"><code>ParseMediaType</code></a>.
 It now takes <code>"text/html"</code> rather than <code>"text"</code> and <code>"html"</code>.
 </p>
 
@@ -1531,9 +1438,9 @@ What little code is affected will be caught by the compiler and must be updated
 <p>
 In Go 1, the various <code>SetTimeout</code>,
 <code>SetReadTimeout</code>, and <code>SetWriteTimeout</code> methods
-have been replaced with 
+have been replaced with
 <a href="/pkg/net/#IPConn.SetDeadline"><code>SetDeadline</code></a>,
-<a href="/pkg/net/#IPConn.SetReadDeadline"><code>SetReadDeadline</code></a>, and 
+<a href="/pkg/net/#IPConn.SetReadDeadline"><code>SetReadDeadline</code></a>, and
 <a href="/pkg/net/#IPConn.SetWriteDeadline"><code>SetWriteDeadline</code></a>,
 respectively.  Rather than taking a timeout value in nanoseconds that
 apply to any activity on the connection, the new methods set an
@@ -1707,11 +1614,7 @@ and
 <a href="/pkg/os/#IsPermission"><code>IsPermission</code></a>.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/os\.Open/` `/}/`}}
--->    f, err := os.OpenFile(name, os.O_RDWR|os.O_CREATE|os.O_EXCL, 0600)
-    if os.IsExist(err) {
-        log.Printf(&#34;%s already exists&#34;, name)
-    }</pre>
+{{code "/doc/progs/go1.go" `/os\.Open/` `/}/`}}
 
 <p>
 <em>Updating</em>:
@@ -1777,21 +1680,7 @@ If a directory's contents are to be skipped,
 the function should return the value <a href="/pkg/path/filepath/#variables"><code>filepath.SkipDir</code></a>
 </p>
 
-<pre><!--{{code "progs/go1.go" `/STARTWALK/` `/ENDWALK/`}}
--->    markFn := func(path string, info os.FileInfo, err error) error {
-        if path == &#34;pictures&#34; { // Will skip walking of directory pictures and its contents.
-            return filepath.SkipDir
-        }
-        if err != nil {
-            return err
-        }
-        log.Println(path)
-        return nil
-    }
-    err := filepath.Walk(&#34;.&#34;, markFn)
-    if err != nil {
-        log.Fatal(err)
-    }</pre>
+{{code "/doc/progs/go1.go" `/STARTWALK/` `/ENDWALK/`}}
 
 <p>
 <em>Updating</em>:
@@ -1804,7 +1693,7 @@ The compiler will catch code using the old interface.
 
 <p>
 The <a href="/pkg/regexp/"><code>regexp</code></a> package has been rewritten.
-It has the same interface but the specification of the regular expressions 
+It has the same interface but the specification of the regular expressions
 it supports has changed from the old "egrep" form to that of
 <a href="http://code.google.com/p/re2/">RE2</a>.
 </p>
@@ -1949,6 +1838,38 @@ a cast that must be added by hand; the <code>go</code> <code>fix</code> tool wil
 </p>
 
 
+<h3 id="templates">The template packages</h3>
+
+<p>
+The <code>template</code> and <code>exp/template/html</code> packages have moved to 
+<a href="/pkg/text/template/"><code>text/template</code></a> and
+<a href="/pkg/html/template/"><code>html/template</code></a>.
+More significant, the interface to these packages has been simplified.
+The template language is the same, but the concept of "template set" is gone
+and the functions and methods of the packages have changed accordingly,
+often by elimination.
+</p>
+
+<p>
+Instead of sets, a <code>Template</code> object
+may contain multiple named template definitions,
+in effect constructing
+name spaces for template invocation.
+A template can invoke any other template associated with it, but only those
+templates associated with it.
+The simplest way to associate templates is to parse them together, something
+made easier with the new structure of the packages.
+</p>
+
+<p>
+<em>Updating</em>:
+The imports will be updated by fix tool.
+Single-template uses will be otherwise be largely unaffected.
+Code that uses multiple templates in concert will need to be updated by hand.
+The <a href="/pkg/text/template/#examples">examples</a> in
+the documentation for <code>text/template</code> can provide guidance.
+</p>
+
 <h3 id="testing">The testing package</h3>
 
 <p>
@@ -1957,20 +1878,7 @@ In Go 1, <code>B</code> has new methods, analogous to those of <code>T</code>, e
 logging and failure reporting.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/func.*Benchmark/` `/^}/`}}
--->func BenchmarkSprintf(b *testing.B) {
-    // Verify correctness before running benchmark.
-    b.StopTimer()
-    got := fmt.Sprintf(&#34;%x&#34;, 23)
-    const expect = &#34;17&#34;
-    if expect != got {
-        b.Fatalf(&#34;expected %q; got %q&#34;, expect, got)
-    }
-    b.StartTimer()
-    for i := 0; i &lt; b.N; i++ {
-        fmt.Sprintf(&#34;%x&#34;, 23)
-    }
-}</pre>
+{{code "/doc/progs/go1.go" `/func.*Benchmark/` `/^}/`}}
 
 <p>
 <em>Updating</em>:
@@ -2083,7 +1991,25 @@ The semantic changes make it difficult for the fix tool to update automatically.
 <h2 id="cmd_go">The go command</h2>
 
 <p>
-TODO: Write this.
+Go 1 introduces the <a href="/cmd/go/">go command</a>, a tool for fetching,
+building, and installing Go packages and commands. The <code>go</code> command
+does away with makefiles, instead using Go source code to find dependencies and
+determine build conditions. Most existing Go programs will no longer require
+makefiles to be built.
+</p>
+
+<p>
+See <a href="/doc/code.html">How to Write Go Code</a> for a primer on the
+<code>go</code> command and the <a href="/cmd/go/">go command documentation</a>
+for the full details.
+</p>
+
+<p>
+<em>Updating</em>:
+Projects that depend on the Go project's old makefile-based build
+infrastructure (<code>Make.pkg</code>, <code>Make.cmd</code>, and so on) should
+switch to using the <code>go</code> command for building Go code and, if
+necessary, rewrite their makefiles to perform any auxiliary build tasks.
 </p>
 
 <h2 id="cmd_cgo">The cgo command</h2>
diff --git a/doc/go1.tmpl b/doc/go1.tmpl
deleted file mode 100644
index e5f161e82..000000000
--- a/doc/go1.tmpl
+++ /dev/null
@@ -1,1975 +0,0 @@
-<!--{
-	"Title": "Go 1 Release Notes"
-}-->
-{{donotedit}}
-
-<h2 id="introduction">Introduction to Go 1</h2>
-
-<p>
-Go version 1, Go 1 for short, defines a language and a set of core libraries
-that provide a stable foundation for creating reliable products, projects, and
-publications.
-</p>
-
-<p>
-The driving motivation for Go 1 is stability for its users. People should be able to
-write Go programs and expect that they will continue to compile and run without
-change, on a time scale of years, including in production environments such as
-Google App Engine. Similarly, people should be able to write books about Go, be
-able to say which version of Go the book is describing, and have that version
-number still be meaningful much later.
-</p>
-
-<p>
-Code that compiles in Go 1 should, with few exceptions, continue to compile and
-run throughout the lifetime of that version, even as we issue updates and bug
-fixes such as Go version 1.1, 1.2, and so on. Other than critical fixes, changes
-made to the language and library for subsequent releases of Go 1 may
-add functionality but will not break existing Go 1 programs.
-<a href="go1compat.html">The Go 1 compatibility document</a>
-explains the compatibility guidelines in more detail.
-</p>
-
-<p>
-Go 1 is a representation of Go as it used today, not a wholesale rethinking of
-the language. We avoided designing new features and instead focused on cleaning
-up problems and inconsistencies and improving portability. There are a number
-changes to the Go language and packages that we had considered for some time and
-prototyped but not released primarily because they are significant and
-backwards-incompatible. Go 1 was an opportunity to get them out, which is
-helpful for the long term, but also means that Go 1 introduces incompatibilities
-for old programs. Fortunately, the <code>go</code> <code>fix</code> tool can
-automate much of the work needed to bring programs up to the Go 1 standard.
-</p>
-
-<p>
-This document outlines the major changes in Go 1 that will affect programmers
-updating existing code; its reference point is the prior release, r60 (tagged as
-r60.3). It also explains how to update code from r60 to run under Go 1.
-</p>
-
-<h2 id="language">Changes to the language</h2>
-
-<h3 id="append">Append</h3>
-
-<p>
-The <code>append</code> predeclared variadic function makes it easy to grow a slice
-by adding elements to the end.
-A common use is to add bytes to the end of a byte slice when generating output.
-However, <code>append</code> did not provide a way to append a string to a <code>[]byte</code>,
-which is another common case.
-</p>
-
-{{code "progs/go1.go" `/greeting := ..byte/` `/append.*hello/`}}
-
-<p>
-By analogy with the similar property of <code>copy</code>, Go 1
-permits a string to be appended (byte-wise) directly to a byte
-slice, reducing the friction between strings and byte slices.
-The conversion is no longer necessary:
-</p>
-
-{{code "progs/go1.go" `/append.*world/`}}
-
-<p>
-<em>Updating</em>:
-This is a new feature, so existing code needs no changes.
-</p>
-
-<h3 id="close">Close</h3>
-
-<p>
-The <code>close</code> predeclared function provides a mechanism
-for a sender to signal that no more values will be sent.
-It is important to the implementation of <code>for</code> <code>range</code>
-loops over channels and is helpful in other situations.
-Partly by design and partly because of race conditions that can occur otherwise,
-it is intended for use only by the goroutine sending on the channel,
-not by the goroutine receiving data.
-However, before Go 1 there was no compile-time checking that <code>close</code>
-was being used correctly.
-</p>
-
-<p>
-To close this gap, at least in part, Go 1 disallows <code>close</code> on receive-only channels.
-Attempting to close such a channel is a compile-time error.
-</p>
-
-<pre>
-    var c chan int
-    var csend chan&lt;- int = c
-    var crecv &lt;-chan int = c
-    close(c)     // legal
-    close(csend) // legal
-    close(crecv) // illegal
-</pre>
-
-<p>
-<em>Updating</em>:
-Existing code that attempts to close a receive-only channel was
-erroneous even before Go 1 and should be fixed.  The compiler will
-now reject such code.
-</p>
-
-<h3 id="literals">Composite literals</h3>
-
-<p>
-In Go 1, a composite literal of array, slice, or map type can elide the
-type specification for the elements' initializers if they are of pointer type.
-All four of the initializations in this example are legal; the last one was illegal before Go 1.
-</p>
-
-{{code "progs/go1.go" `/type Date struct/` `/STOP/`}}
-
-<p>
-<em>Updating</em>:
-This change has no effect on existing code, but the command
-<code>gofmt</code> <code>-s</code> applied to existing source
-will, among other things, elide explicit element types wherever permitted.
-</p>
-
-
-<h3 id="init">Goroutines during init</h3>
-
-<p>
-The old language defined that <code>go</code> statements executed during initialization created goroutines but that they did not begin to run until initialization of the entire program was complete.
-This introduced clumsiness in many places and, in effect, limited the utility
-of the <code>init</code> construct:
-if it was possible for another package to use the library during initialization, the library
-was forced to avoid goroutines.
-This design was done for reasons of simplicity and safety but,
-as our confidence in the language grew, it seemed unnecessary.
-Running goroutines during initialization is no more complex or unsafe than running them during normal execution.
-</p>
-
-<p>
-In Go 1, code that uses goroutines can be called from
-<code>init</code> routines and global initialization expressions
-without introducing a deadlock.
-</p>
-
-{{code "progs/go1.go" `/PackageGlobal/` `/^}/`}}
-
-<p>
-<em>Updating</em>:
-This is a new feature, so existing code needs no changes,
-although it's possible that code that depends on goroutines not starting before <code>main</code> will break.
-There was no such code in the standard repository.
-</p>
-
-<h3 id="rune">The rune type</h3>
-
-<p>
-The language spec allows the <code>int</code> type to be 32 or 64 bits wide, but current implementations set <code>int</code> to 32 bits even on 64-bit platforms.
-It would be preferable to have <code>int</code> be 64 bits on 64-bit platforms.
-(There are important consequences for indexing large slices.)
-However, this change would waste space when processing Unicode characters with
-the old language because the <code>int</code> type was also used to hold Unicode code points: each code point would waste an extra 32 bits of storage if <code>int</code> grew from 32 bits to 64.
-</p>
-
-<p>
-To make changing to 64-bit <code>int</code> feasible,
-Go 1 introduces a new basic type, <code>rune</code>, to represent
-individual Unicode code points.
-It is an alias for <code>int32</code>, analogous to <code>byte</code>
-as an alias for <code>uint8</code>.
-</p>
-
-<p>
-Character literals such as <code>'a'</code>, <code>'語'</code>, and <code>'\u0345'</code>
-now have default type <code>rune</code>,
-analogous to <code>1.0</code> having default type <code>float64</code>.
-A variable initialized to a character constant will therefore
-have type <code>rune</code> unless otherwise specified.
-</p>
-
-<p>
-Libraries have been updated to use <code>rune</code> rather than <code>int</code>
-when appropriate. For instance, the functions <code>unicode.ToLower</code> and
-relatives now take and return a <code>rune</code>.
-</p>
-
-{{code "progs/go1.go" `/STARTRUNE/` `/ENDRUNE/`}}
-
-<p>
-<em>Updating</em>:
-Most source code will be unaffected by this because the type inference from
-<code>:=</code> initializers introduces the new type silently, and it propagates
-from there.
-Some code may get type errors that a trivial conversion will resolve.
-</p>
-
-<h3 id="error">The error type</h3>
-
-<p>
-Go 1 introduces a new built-in type, <code>error</code>, which has the following definition:
-</p>
-
-<pre>
-    type error interface {
-        Error() string
-    }
-</pre>
-
-<p>
-Since the consequences of this type are all in the package library,
-it is discussed <a href="#errors">below</a>.
-</p>
-
-<h3 id="delete">Deleting from maps</h3>
-
-<p>
-In the old language, to delete the entry with key <code>k</code> from map <code>m</code>, one wrote the statement,
-</p>
-
-<pre>
-    m[k] = value, false
-</pre>
-
-<p>
-This syntax was a peculiar special case, the only two-to-one assignment.
-It required passing a value (usually ignored) that is evaluated but discarded,
-plus a boolean that was nearly always the constant <code>false</code>.
-It did the job but was odd and a point of contention.
-</p>
-
-<p>
-In Go 1, that syntax has gone; instead there is a new built-in
-function, <code>delete</code>.  The call
-</p>
-
-{{code "progs/go1.go" `/delete\(m, k\)/`}}
-
-<p>
-will delete the map entry retrieved by the expression <code>m[k]</code>.
-There is no return value. Deleting a non-existent entry is a no-op.
-</p>
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will convert expressions of the form <code>m[k] = value,
-false</code> into <code>delete(m, k)</code> when it is clear that
-the ignored value can be safely discarded from the program and
-<code>false</code> refers to the predefined boolean constant.
-The fix tool
-will flag other uses of the syntax for inspection by the programmer.
-</p>
-
-<h3 id="iteration">Iterating in maps</h3>
-
-<p>
-The old language specification did not define the order of iteration for maps,
-and in practice it differed across hardware platforms.
-This caused tests that iterated over maps to be fragile and non-portable, with the
-unpleasant property that a test might always pass on one machine but break on another.
-</p>
-
-<p>
-In Go 1, the order in which elements are visited when iterating
-over a map using a <code>for</code> <code>range</code> statement
-is defined to be unpredictable, even if the same loop is run multiple
-times with the same map.
-Code should not assume that the elements are visited in any particular order.
-</p>
-
-<p>
-This change means that code that depends on iteration order is very likely to break early and be fixed long before it becomes a problem.
-Just as important, it allows the map implementation to ensure better map balancing even when programs are using range loops to select an element from a map.
-</p>
-
-{{code "progs/go1.go" `/Sunday/` `/^	}/`}}
-
-<p>
-<em>Updating</em>:
-This is one change where tools cannot help.  Most existing code
-will be unaffected, but some programs may break or misbehave; we
-recommend manual checking of all range statements over maps to
-verify they do not depend on iteration order. There were a few such
-examples in the standard repository; they have been fixed.
-Note that it was already incorrect to depend on the iteration order, which
-was unspecified. This change codifies the unpredictability.
-</p>
-
-<h3 id="multiple_assignment">Multiple assignment</h3>
-
-<p>
-The language specification has long guaranteed that in assignments
-the right-hand-side expressions are all evaluated before any left-hand-side expressions are assigned.
-To guarantee predictable behavior,
-Go 1 refines the specification further.
-</p>
-
-<p>
-If the left-hand side of the assignment
-statement contains expressions that require evaluation, such as
-function calls or array indexing operations, these will all be done
-using the usual left-to-right rule before any variables are assigned
-their value.  Once everything is evaluated, the actual assignments
-proceed in left-to-right order.
-</p>
-
-<p>
-These examples illustrate the behavior.
-</p>
-
-{{code "progs/go1.go" `/sa :=/` `/then sc.0. = 2/`}}
-
-<p>
-<em>Updating</em>:
-This is one change where tools cannot help, but breakage is unlikely.
-No code in the standard repository was broken by this change, and code
-that depended on the previous unspecified behavior was already incorrect.
-</p>
-
-<h3 id="shadowing">Returns and shadowed variables</h3>
-
-<p>
-A common mistake is to use <code>return</code> (without arguments) after an assignment to a variable that has the same name as a result variable but is not the same variable.
-This situation is called <em>shadowing</em>: the result variable has been shadowed by another variable with the same name declared in an inner scope.
-</p>
-
-<p>
-In functions with named return values,
-the Go 1 compilers disallow return statements without arguments if any of the named return values is shadowed at the point of the return statement.
-(It isn't part of the specification, because this is one area we are still exploring;
-the situation is analogous to the compilers rejecting functions that do not end with an explicit return statement.)
-</p>
-
-<p>
-This function implicitly returns a shadowed return value and will be rejected by the compiler:
-</p>
-
-<pre>
-    func Bug() (i, j, k int) {
-        for i = 0; i &lt; 5; i++ {
-            for j := 0; j &lt; 5; j++ { // Redeclares j.
-                k += i*j
-                if k > 100 {
-                    return // Rejected: j is shadowed here.
-                }
-            }
-        }
-        return // OK: j is not shadowed here.
-    }
-</pre>
-
-<p>
-<em>Updating</em>:
-Code that shadows return values in this way will be rejected by the compiler and will need to be fixed by hand.
-The few cases that arose in the standard repository were mostly bugs.
-</p>
-
-<h3 id="unexported">Copying structs with unexported fields</h3>
-
-<p>
-The old language did not allow a package to make a copy of a struct value containing unexported fields belonging to a different package.
-There was, however, a required exception for a method receiver;
-also, the implementations of <code>copy</code> and <code>append</code> have never honored the restriction.
-</p>
-
-<p>
-Go 1 will allow packages to copy struct values containing unexported fields from other packages.
-Besides resolving the inconsistency,
-this change admits a new kind of API: a package can return an opaque value without resorting to a pointer or interface.
-The new implementations of <code>time.Time</code> and
-<code>reflect.Value</code> are examples of types taking advantage of this new property.
-</p>
-
-<p>
-As an example, if package <code>p</code> includes the definitions,
-</p>
-
-<pre>
-    type Struct struct {
-        Public int
-        secret int
-    }
-    func NewStruct(a int) Struct {  // Note: not a pointer.
-        return Struct{a, f(a)}
-    }
-    func (s Struct) String() string {
-        return fmt.Sprintf("{%d (secret %d)}", s.Public, s.secret)
-    }
-</pre>
-
-<p>
-a package that imports <code>p</code> can assign and copy values of type
-<code>p.Struct</code> at will.
-Behind the scenes the unexported fields will be assigned and copied just
-as if they were exported,
-but the client code will never be aware of them. The code
-</p>
-
-<pre>
-    import "p"
-
-    myStruct := p.NewStruct(23)
-    copyOfMyStruct := myStruct
-    fmt.Println(myStruct, copyOfMyStruct)
-</pre>
-
-<p>
-will show that the secret field of the struct has been copied to the new value.
-</p>
-
-<p>
-<em>Updating</em>:
-This is a new feature, so existing code needs no changes.
-</p>
-
-<h3 id="equality">Equality</h3>
-
-<p>
-Before Go 1, the language did not define equality on struct and array values.
-This meant,
-among other things, that structs and arrays could not be used as map keys.
-On the other hand, Go did define equality on function and map values.
-Function equality was problematic in the presence of closures
-(when are two closures equal?)
-while map equality compared pointers, not the maps' content, which was usually
-not what the user would want.
-</p>
-
-<p>
-Go 1 addressed these issues.
-First, structs and arrays can be compared for equality and inequality
-(<code>==</code> and <code>!=</code>),
-and therefore be used as map keys,
-provided they are composed from elements for which equality is also defined,
-using element-wise comparison.
-</p>
-
-{{code "progs/go1.go" `/type Day struct/` `/Printf/`}}
-
-<p>
-Second, Go 1 removes the definition of equality for function values,
-except for comparison with <code>nil</code>.
-Finally, map equality is gone too, also except for comparison with <code>nil</code>.
-</p>
-
-<p>
-Note that equality is still undefined for slices, for which the
-calculation is in general infeasible.  Also note that the ordered
-comparison operators (<code>&lt;</code> <code>&lt;=</code>
-<code>&gt;</code> <code>&gt;=</code>) are still undefined for
-structs and arrays.
-
-<p>
-<em>Updating</em>:
-Struct and array equality is a new feature, so existing code needs no changes.
-Existing code that depends on function or map equality will be
-rejected by the compiler and will need to be fixed by hand.
-Few programs will be affected, but the fix may require some
-redesign.
-</p>
-
-<h2 id="packages">The package hierarchy</h2>
-
-<p>
-Go 1 addresses many deficiencies in the old standard library and
-cleans up a number of packages, making them more internally consistent
-and portable.
-</p>
-
-<p>
-This section describes how the packages have been rearranged in Go 1.
-Some have moved, some have been renamed, some have been deleted.
-New packages are described in later sections.
-</p>
-
-<h3 id="hierarchy">The package hierarchy</h3>
-
-<p>
-Go 1 has a rearranged package hierarchy that groups related items
-into subdirectories. For instance, <code>utf8</code> and
-<code>utf16</code> now occupy subdirectories of <code>unicode</code>.
-Also, <a href="#subrepo">some packages</a> have moved into
-subrepositories of
-<a href="http://code.google.com/p/go"><code>code.google.com/p/go</code></a>
-while <a href="#deleted">others</a> have been deleted outright.
-</p>
-
-<table class="codetable" frame="border" summary="Moved packages">
-<colgroup align="left" width="60%"></colgroup>
-<colgroup align="left" width="40%"></colgroup>
-<tr>
-<th align="left">Old path</th>
-<th align="left">New path</th>
-</tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>asn1</td> <td>encoding/asn1</td></tr>
-<tr><td>csv</td> <td>encoding/csv</td></tr>
-<tr><td>gob</td> <td>encoding/gob</td></tr>
-<tr><td>json</td> <td>encoding/json</td></tr>
-<tr><td>xml</td> <td>encoding/xml</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>exp/template/html</td> <td>html/template</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>big</td> <td>math/big</td></tr>
-<tr><td>cmath</td> <td>math/cmplx</td></tr>
-<tr><td>rand</td> <td>math/rand</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>http</td> <td>net/http</td></tr>
-<tr><td>http/cgi</td> <td>net/http/cgi</td></tr>
-<tr><td>http/fcgi</td> <td>net/http/fcgi</td></tr>
-<tr><td>http/httptest</td> <td>net/http/httptest</td></tr>
-<tr><td>http/pprof</td> <td>net/http/pprof</td></tr>
-<tr><td>mail</td> <td>net/mail</td></tr>
-<tr><td>rpc</td> <td>net/rpc</td></tr>
-<tr><td>rpc/jsonrpc</td> <td>net/rpc/jsonrpc</td></tr>
-<tr><td>smtp</td> <td>net/smtp</td></tr>
-<tr><td>url</td> <td>net/url</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>exec</td> <td>os/exec</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>scanner</td> <td>text/scanner</td></tr>
-<tr><td>tabwriter</td> <td>text/tabwriter</td></tr>
-<tr><td>template</td> <td>text/template</td></tr>
-<tr><td>template/parse</td> <td>text/template/parse</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>utf8</td> <td>unicode/utf8</td></tr>
-<tr><td>utf16</td> <td>unicode/utf16</td></tr>
-</table>
-
-<p>
-Note that the package names for the old <code>cmath</code> and
-<code>exp/template/html</code> packages have changed to <code>cmplx</code>
-and <code>template</code>.
-</p>
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will update all imports and package renames for packages that
-remain inside the standard repository.  Programs that import packages
-that are no longer in the standard repository will need to be edited
-by hand.
-</p>
-
-<h3 id="exp">The package tree exp</h3>
-
-<p>
-Because they are not standardized, the packages under the <code>exp</code> directory will not be available in the
-standard Go 1 release distributions, although they will be available in source code form
-in <a href="http://code.google.com/p/go/">the repository</a> for
-developers who wish to use them.
-</p>
-
-<p>
-Several packages have moved under <code>exp</code> at the time of Go 1's release:
-</p>
-
-<ul>
-<li><code>ebnf</code></li>
-<li><code>html</code><sup>&#8224;</sup></li>
-<li><code>go/types</code></li>
-</ul>
-
-<p>
-(<sup>&#8224;</sup>The <code>EscapeString</code> and <code>UnescapeString</code> types remain
-in package <code>html</code>.)
-</p>
-
-<p>
-All these packages are available under the same names, with the prefix <code>exp/</code>: <code>exp/ebnf</code> etc.
-</p>
-
-<p>
-Also, the <code>utf8.String</code> type has been moved to its own package, <code>exp/utf8string</code>.
-</p>
-
-<p>
-Finally, the <code>gotype</code> command now resides in <code>exp/gotype</code>, while
-<code>ebnflint</code> is now in <code>exp/ebnflint</code>.
-If they are installed, they now reside in <code>$GOROOT/bin/tool</code>.
-</p>
-
-<p>
-<em>Updating</em>:
-Code that uses packages in <code>exp</code> will need to be updated by hand,
-or else compiled from an installation that has <code>exp</code> available.
-The <code>go</code> <code>fix</code> tool or the compiler will complain about such uses.
-</p>
-
-<h3 id="old">The package tree old</h3>
-
-<p>
-Because they are deprecated, the packages under the <code>old</code> directory will not be available in the
-standard Go 1 release distributions, although they will be available in source code form for
-developers who wish to use them.
-</p>
-
-<p>
-The packages in their new locations are:
-</p>
-
-<ul>
-<li><code>old/netchan</code></li>
-<li><code>old/regexp</code></li>
-<li><code>old/template</code></li>
-</ul>
-
-<p>
-<em>Updating</em>:
-Code that uses packages now in <code>old</code> will need to be updated by hand,
-or else compiled from an installation that has <code>old</code> available.
-The <code>go</code> <code>fix</code> tool will warn about such uses.
-</p>
-
-<h3 id="deleted">Deleted packages</h3>
-
-<p>
-Go 1 deletes several packages outright:
-</p>
-
-<ul>
-<li><code>container/vector</code></li>
-<li><code>exp/datafmt</code></li>
-<li><code>go/typechecker</code></li>
-<li><code>try</code></li>
-</ul>
-
-<p>
-and also the command <code>gotry</code>.
-</p>
-
-<p>
-<em>Updating</em>:
-Code that uses <code>container/vector</code> should be updated to use
-slices directly.  See
-<a href="http://code.google.com/p/go-wiki/wiki/SliceTricks">the Go
-Language Community Wiki</a> for some suggestions.
-Code that uses the other packages (there should be almost zero) will need to be rethought.
-</p>
-
-<h3 id="subrepo">Packages moving to subrepositories</h3>
-
-<p>
-Go 1 has moved a number of packages into sub-repositories of
-<a href="http://code.google.com/p/go/">the main Go repository</a>.
-This table lists the old and new import paths:
-
-<table class="codetable" frame="border" summary="Sub-repositories">
-<colgroup align="left" width="40%"></colgroup>
-<colgroup align="left" width="60%"></colgroup>
-<tr>
-<th align="left">Old</th>
-<th align="left">New</th>
-</tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>crypto/bcrypt</td> <td>code.google.com/p/go.crypto/bcrypt</tr>
-<tr><td>crypto/blowfish</td> <td>code.google.com/p/go.crypto/blowfish</tr>
-<tr><td>crypto/cast5</td> <td>code.google.com/p/go.crypto/cast5</tr>
-<tr><td>crypto/md4</td> <td>code.google.com/p/go.crypto/md4</tr>
-<tr><td>crypto/ocsp</td> <td>code.google.com/p/go.crypto/ocsp</tr>
-<tr><td>crypto/openpgp</td> <td>code.google.com/p/go.crypto/openpgp</tr>
-<tr><td>crypto/openpgp/armor</td> <td>code.google.com/p/go.crypto/openpgp/armor</tr>
-<tr><td>crypto/openpgp/elgamal</td> <td>code.google.com/p/go.crypto/openpgp/elgamal</tr>
-<tr><td>crypto/openpgp/errors</td> <td>code.google.com/p/go.crypto/openpgp/errors</tr>
-<tr><td>crypto/openpgp/packet</td> <td>code.google.com/p/go.crypto/openpgp/packet</tr>
-<tr><td>crypto/openpgp/s2k</td> <td>code.google.com/p/go.crypto/openpgp/s2k</tr>
-<tr><td>crypto/ripemd160</td> <td>code.google.com/p/go.crypto/ripemd160</tr>
-<tr><td>crypto/twofish</td> <td>code.google.com/p/go.crypto/twofish</tr>
-<tr><td>crypto/xtea</td> <td>code.google.com/p/go.crypto/xtea</tr>
-<tr><td>exp/ssh</td> <td>code.google.com/p/go.crypto/ssh</tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>image/bmp</td> <td>code.google.com/p/go.image/bmp</tr>
-<tr><td>image/tiff</td> <td>code.google.com/p/go.image/tiff</tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>net/dict</td> <td>code.google.com/p/go.net/dict</tr>
-<tr><td>net/websocket</td> <td>code.google.com/p/go.net/websocket</tr>
-<tr><td>exp/spdy</td> <td>code.google.com/p/go.net/spdy</tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>encoding/git85</td> <td>code.google.com/p/go.codereview/git85</tr>
-<tr><td>patch</td> <td>code.google.com/p/go.codereview/patch</tr>
-</table>
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will update imports of these packages to use the new import paths.
-Installations that depend on these packages will need to install them using
-a <code>go install</code> command.
-</p>
-
-<h2 id="major">Major changes to the library</h2>
-
-<p>
-This section describes significant changes to the core libraries, the ones that
-affect the most programs.
-</p>
-
-<h3 id="errors">The error type and errors package</h3>
-
-<p>
-The placement of <code>os.Error</code> in package <code>os</code> is mostly historical: errors first came up when implementing package <code>os</code>, and they seemed system-related at the time.
-Since then it has become clear that errors are more fundamental than the operating system.  For example, it would be nice to use <code>Errors</code> in packages that <code>os</code> depends on, like <code>syscall</code>.
-Also, having <code>Error</code> in <code>os</code> introduces many dependencies on <code>os</code> that would otherwise not exist.
-</p>
-
-<p>
-Go 1 solves these problems by introducing a built-in <code>error</code> interface type and a separate <code>errors</code> package (analogous to <code>bytes</code> and <code>strings</code>) that contains utility functions.
-It replaces <code>os.NewError</code> with
-<a href="/pkg/errors/#New"><code>errors.New</code></a>,
-giving errors a more central place in the environment.
-</p>
-
-<p>
-So the widely-used <code>String</code> method does not cause accidental satisfaction
-of the <code>error</code> interface, the <code>error</code> interface uses instead
-the name <code>Error</code> for that method:
-</p>
-
-<pre>
-    type error interface {
-        Error() string
-    }
-</pre>
-
-<p>
-The <code>fmt</code> library automatically invokes <code>Error</code>, as it already
-does for <code>String</code>, for easy printing of error values.
-</p>
-
-{{code "progs/go1.go" `/START ERROR EXAMPLE/` `/END ERROR EXAMPLE/`}}
-
-<p>
-All standard packages have been updated to use the new interface; the old <code>os.Error</code> is gone.
-</p>
-
-<p>
-A new package, <a href="/pkg/errors/"><code>errors</code></a>, contains the function
-</p>
-
-<pre>
-func New(text string) error
-</pre>
-
-<p>
-to turn a string into an error. It replaces the old <code>os.NewError</code>.
-</p>
-
-{{code "progs/go1.go" `/ErrSyntax/`}}
-		
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will update almost all code affected by the change.
-Code that defines error types with a <code>String</code> method will need to be updated
-by hand to rename the methods to <code>Error</code>.
-</p>
-
-<h3 id="errno">System call errors</h3>
-
-<p>
-The old <code>syscall</code> package, which predated <code>os.Error</code>
-(and just about everything else),
-returned errors as <code>int</code> values.
-In turn, the <code>os</code> package forwarded many of these errors, such
-as <code>EINVAL</code>, but using a different set of errors on each platform.
-This behavior was unpleasant and unportable.
-</p>
-
-<p>
-In Go 1, the
-<a href="/pkg/syscall/"><code>syscall</code></a>
-package instead returns an <code>error</code> for system call errors.
-On Unix, the implementation is done by a 
-<a href="/pkg/syscall/#Errno"><code>syscall.Errno</code></a> type
-that satisfies <code>error</code> and replaces the old <code>os.Errno</code>.
-</p>
-
-<p>
-The changes affecting <code>os.EINVAL</code> and relatives are
-described <a href="#os">elsewhere</a>.
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will update almost all code affected by the change.
-Regardless, most code should use the <code>os</code> package
-rather than <code>syscall</code> and so will be unaffected.
-</p>
-
-<h3 id="time">Time</h3>
-
-<p>
-Time is always a challenge to support well in a programming language.
-The old Go <code>time</code> package had <code>int64</code> units, no
-real type safety,
-and no distinction between absolute times and durations.
-</p>
-
-<p>
-One of the most sweeping changes in the Go 1 library is therefore a
-complete redesign of the 
-<a href="/pkg/time/"><code>time</code></a> package.
-Instead of an integer number of nanoseconds as an <code>int64</code>,
-and a separate <code>*time.Time</code> type to deal with human
-units such as hours and years,
-there are now two fundamental types:
-<a href="/pkg/time/#Time"><code>time.Time</code></a>
-(a value, so the <code>*</code> is gone), which represents a moment in time;
-and <a href="/pkg/time/#Duration"><code>time.Duration</code></a>,
-which represents an interval.
-Both have nanosecond resolution.
-A <code>Time</code> can represent any time into the ancient
-past and remote future, while a <code>Duration</code> can
-span plus or minus only about 290 years.
-There are methods on these types, plus a number of helpful
-predefined constant durations such as <code>time.Second</code>.
-</p>
-
-<p>
-Among the new methods are things like
-<a href="/pkg/time/#Time.Add"><code>Time.Add</code></a>,
-which adds a <code>Duration</code> to a <code>Time</code>, and
-<a href="/pkg/time/#Time.Sub"><code>Time.Sub</code></a>,
-which subtracts two <code>Times</code> to yield a <code>Duration</code>.
-</p>
-
-<p>
-The most important semantic change is that the Unix epoch (Jan 1, 1970) is now
-relevant only for those functions and methods that mention Unix:
-<a href="/pkg/time/#Unix"><code>time.Unix</code></a>
-and the <a href="/pkg/time/#Time.Unix"><code>Unix</code></a>
-and <a href="/pkg/time/#Time.UnixNano"><code>UnixNano</code></a> methods
-of the <code>Time</code> type.
-In particular,
-<a href="/pkg/time/#Now"><code>time.Now</code></a>
-returns a <code>time.Time</code> value rather than, in the old
-API, an integer nanosecond count since the Unix epoch.
-</p>
-
-{{code "progs/go1.go" `/sleepUntil/` `/^}/`}}
-
-<p>
-The new types, methods, and constants have been propagated through
-all the standard packages that use time, such as <code>os</code> and
-its representation of file time stamps.
-</p>
-
-<p>
-<em>Updating</em>:
-The <code>go</code> <code>fix</code> tool will update many uses of the old <code>time</code> package to use the new
-types and methods, although it does not replace values such as <code>1e9</code>
-representing nanoseconds per second.
-Also, because of type changes in some of the values that arise,
-some of the expressions rewritten by the fix tool may require
-further hand editing; in such cases the rewrite will include
-the correct function or method for the old functionality, but
-may have the wrong type or require further analysis.
-</p>
-
-<h2 id="minor">Minor changes to the library</h2>
-
-<p>
-This section describes smaller changes, such as those to less commonly
-used packages or that affect
-few programs beyond the need to run <code>go</code> <code>fix</code>.
-This category includes packages that are new in Go 1.
-Collectively they improve portability, regularize behavior, and
-make the interfaces more modern and Go-like.
-</p>
-
-<h3 id="archive_zip">The archive/zip package</h3>
-
-<p>
-In Go 1, <a href="/pkg/archive/zip/#Writer"><code>*zip.Writer</code></a> no
-longer has a <code>Write</code> method. Its presence was a mistake.
-</p>
-
-<p>
-<em>Updating</em>:
-What little code is affected will be caught by the compiler and must be updated by hand.
-</p>
-
-<h3 id="bufio">The bufio package</h3>
-
-<p>
-In Go 1, <a href="/pkg/bufio/#NewReaderSize"><code>bufio.NewReaderSize</code></a>
-and
-<a href="/pkg/bufio/#NewWriterSize"><code>bufio.NewWriterSize</code></a>
-functions no longer return an error for invalid sizes.
-If the argument size is too small or invalid, it is adjusted.
-</p>
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will update calls that assign the error to _.
-Calls that aren't fixed will be caught by the compiler and must be updated by hand.
-</p>
-
-<h3 id="compress">The compress/flate, compress/gzip and compress/zlib packages</h3>
-
-<p>
-In Go 1, the <code>NewWriterXxx</code> functions in
-<a href="/pkg/compress/flate"><code>compress/flate</code></a>,
-<a href="/pkg/compress/gzip"><code>compress/gzip</code></a> and
-<a href="/pkg/compress/zlib"><code>compress/zlib</code></a>
-all return <code>(*Writer, error)</code> if they take a compression level,
-and <code>*Writer</code> otherwise. Package <code>gzip</code>'s
-<code>Compressor</code> and <code>Decompressor</code> types have been renamed
-to <code>Writer</code> and <code>Reader</code>. Package <code>flate</code>'s
-<code>WrongValueError</code> type has been removed.
-</p>
-
-<p>
-<em>Updating</em>
-Running <code>go</code> <code>fix</code> will update old names and calls that assign the error to _.
-Calls that aren't fixed will be caught by the compiler and must be updated by hand.
-</p>
-
-<h3 id="crypto_aes_des">The crypto/aes and crypto/des packages</h3>
-
-<p>
-In Go 1, the <code>Reset</code> method has been removed. Go does not guarantee
-that memory is not copied and therefore this method was misleading.
-</p>
-
-<p>
-The cipher-specific types <code>*aes.Cipher</code>, <code>*des.Cipher</code>,
-and <code>*des.TripleDESCipher</code> have been removed in favor of
-<code>cipher.Block</code>.
-</p>
-
-<p>
-<em>Updating</em>:
-Remove the calls to Reset. Replace uses of the specific cipher types with
-cipher.Block.
-</p>
-
-<h3 id="crypto_elliptic">The crypto/elliptic package</h3>
-
-<p>
-In Go 1, <a href="/pkg/crypto/elliptic/#Curve"><code>elliptic.Curve</code></a>
-has been made an interface to permit alternative implementations. The curve
-parameters have been moved to the
-<a href="/pkg/crypto/elliptic/#CurveParams"><code>elliptic.CurveParams</code></a>
-structure.
-</p>
-
-<p>
-<em>Updating</em>:
-Existing users of <code>*elliptic.Curve</code> will need to change to
-simply <code>elliptic.Curve</code>. Calls to <code>Marshal</code>,
-<code>Unmarshal</code> and <code>GenerateKey</code> are now functions
-in <code>crypto/elliptic</code> that take an <code>elliptic.Curve</code>
-as their first argument.
-</p>
-
-<h3 id="crypto_hmac">The crypto/hmac package</h3>
-
-<p>
-In Go 1, the hash-specific functions, such as <code>hmac.NewMD5</code>, have
-been removed from <code>crypto/hmac</code>. Instead, <code>hmac.New</code> takes
-a function that returns a <code>hash.Hash</code>, such as <code>md5.New</code>.
-</p>
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will perform the needed changes.
-</p>
-
-<h3 id="crypto_x509">The crypto/x509 package</h3>
-
-<p>
-In Go 1, the
-<a href="/pkg/crypto/x509/#CreateCertificate"><code>CreateCertificate</code></a>
-and
-<a href="/pkg/crypto/x509/#CreateCRL"><code>CreateCRL</code></a>
-functions in <code>crypto/x509</code> have been altered to take an
-<code>interface{}</code> where they previously took a <code>*rsa.PublicKey</code>
-or <code>*rsa.PrivateKey</code>. This will allow other public key algorithms
-to be implemented in the future.
-</p>
-
-<p>
-<em>Updating</em>:
-No changes will be needed.
-</p>
-
-<h3 id="encoding_binary">The encoding/binary package</h3>               
-
-<p>
-In Go 1, the <code>binary.TotalSize</code> function has been replaced by
-<a href="/pkg/encoding/binary/#Size"><code>Size</code></a>,
-which takes an <code>interface{}</code> argument rather than
-a <code>reflect.Value</code>.
-</p>
-
-<p>
-<em>Updating</em>:
-What little code is affected will be caught by the compiler and must be updated by hand.
-</p>
-
-<h3 id="encoding_xml">The encoding/xml package</h3>
-
-<p>
-In Go 1, the <a href="/pkg/encoding/xml/"><code>xml</code></a> package
-has been brought closer in design to the other marshaling packages such
-as <a href="/pkg/encoding/gob/"><code>encoding/gob</code></a>.
-</p>
-
-<p>
-The old <code>Parser</code> type is renamed
-<a href="/pkg/encoding/xml/#Decoder"><code>Decoder</code></a> and has a new
-<a href="/pkg/encoding/xml/#Decoder.Decode"><code>Decode</code></a> method. An
-<a href="/pkg/encoding/xml/#Encoder"><code>Encoder</code></a> type was also introduced.
-</p>
-
-<p>
-The functions <a href="/pkg/encoding/xml/#Marshal"><code>Marshal</code></a>
-and <a href="/pkg/encoding/xml/#Unmarshal"><code>Unmarshal</code></a>
-work with <code>[]byte</code> values now. To work with streams,
-use the new <a href="/pkg/encoding/xml/#Encoder"><code>Encoder</code></a>
-and <a href="/pkg/encoding/xml/#Decoder"><code>Decoder</code></a> types.
-</p>
-
-<p>
-When marshaling or unmarshaling values, the format of supported flags in
-field tags has changed to be closer to the
-<a href="/pkg/encoding/json"><code>json</code></a> package
-(<code>`xml:"name,flag"`</code>). The matching done between field tags, field
-names, and the XML attribute and element names is now case-sensitive.
-The <code>XMLName</code> field tag, if present, must also match the name
-of the XML element being marshaled.
-</p>
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will update most uses of the package except for some calls to
-<code>Unmarshal</code>. Special care must be taken with field tags,
-since the fix tool will not update them and if not fixed by hand they will
-misbehave silently in some cases. For example, the old
-<code>"attr"</code> is now written <code>",attr"</code> while plain
-<code>"attr"</code> remains valid but with a different meaning.
-</p>
-
-<h3 id="expvar">The expvar package</h3>
-
-<p>
-In Go 1, the <code>RemoveAll</code> function has been removed.
-The <code>Iter</code> function and Iter method on <code>*Map</code> have
-been replaced by
-<a href="/pkg/expvar/#Do"><code>Do</code></a>
-and
-<a href="/pkg/expvar/#Map.Do"><code>(*Map).Do</code></a>.
-</p>
-
-<p>
-<em>Updating</em>:
-Most code using <code>expvar</code> will not need changing. The rare code that used
-<code>Iter</code> can be updated to pass a closure to <code>Do</code> to achieve the same effect.
-</p>
-
-<h3 id="flag">The flag package</h3>
-
-<p>
-In Go 1, the interface <a href="/pkg/flag/#Value"><code>flag.Value</code></a> has changed slightly.
-The <code>Set</code> method now returns an <code>error</code> instead of
-a <code>bool</code> to indicate success or failure.
-</p>
-
-<p>
-There is also a new kind of flag, <code>Duration</code>, to support argument
-values specifying time intervals.
-Values for such flags must be given units, just as <code>time.Duration</code>
-formats them: <code>10s</code>, <code>1h30m</code>, etc.
-</p>
-
-{{code "progs/go1.go" `/timeout/`}}
-
-<p>
-<em>Updating</em>:
-Programs that implement their own flags will need minor manual fixes to update their
-<code>Set</code> methods.
-The <code>Duration</code> flag is new and affects no existing code.
-</p>
-
-
-<h3 id="go">The go/* packages</h3>
-
-<p>
-Several packages under <code>go</code> have slightly revised APIs.
-</p>
-
-<p>
-A concrete <code>Mode</code> type was introduced for configuration mode flags
-in the packages
-<a href="/pkg/go/scanner/"><code>go/scanner</code></a>,
-<a href="/pkg/go/parser/"><code>go/parser</code></a>,
-<a href="/pkg/go/printer/"><code>go/printer</code></a>, and
-<a href="/pkg/go/doc/"><code>go/doc</code></a>.
-</p>
-
-<p>
-The modes <code>AllowIllegalChars</code> and <code>InsertSemis</code> have been removed
-from the <a href="/pkg/go/scanner/"><code>go/scanner</code></a> package. They were mostly
-useful for scanning text other then Go source files. Instead, the
-<a href="/pkg/text/scanner/"><code>text/scanner</code></a> package should be used
-for that purpose.
-</p>
-
-<p>
-The <a href="/pkg/go/scanner/#ErrorHandler"><code>ErrorHandler</code></a> provided
-to the scanner's <a href="/pkg/go/scanner/#Scanner.Init"><code>Init</code></a> method is
-now simply a function rather than an interface. The <code>ErrorVector</code> type has
-been removed in favor of the (existing) <a href="/pkg/go/scanner/#ErrorList"><code>ErrorList</code></a>
-type, and the <code>ErrorVector</code> methods have been migrated. Instead of embedding
-an <code>ErrorVector</code> in a client of the scanner, now a client should maintain
-an <code>ErrorList</code>.
-</p>
-
-<p>
-The set of parse functions provided by the <a href="/pkg/go/parser/"><code>go/parser</code></a>
-package has been reduced to the primary parse function
-<a href="/pkg/go/parser/#ParseFile"><code>ParseFile</code></a>, and a couple of
-convenience functions <a href="/pkg/go/parser/#ParseDir"><code>ParseDir</code></a>
-and <a href="/pkg/go/parser/#ParseExpr"><code>ParseExpr</code></a>.
-</p>
-
-<p>
-The <a href="/pkg/go/printer/"><code>go/printer</code></a> package supports an additional
-configuration mode <a href="/pkg/go/printer/#Mode"><code>SourcePos</code></a>;
-if set, the printer will emit <code>//line</code> comments such that the generated
-output contains the original source code position information. The new type
-<a href="/pkg/go/printer/#CommentedNode"><code>CommentedNode</code></a> can be  
-used to provide comments associated with an arbitrary
-<a href="/pkg/go/ast/#Node"><code>ast.Node</code></a> (until now only
-<a href="/pkg/go/ast/#File"><code>ast.File</code></a> carried comment information).
-</p>
-
-<p>
-The type names of the <a href="/pkg/go/doc/"><code>go/doc</code></a> package have been
-streamlined by removing the <code>Doc</code> suffix: <code>PackageDoc</code>
-is now <code>Package</code>, <code>ValueDoc</code> is <code>Value</code>, etc.
-Also, all types now consistently have a <code>Name</code> field (or <code>Names</code>,
-in the case of type <code>Value</code>) and <code>Type.Factories</code> has become
-<code>Type.Funcs</code>.
-Instead of calling <code>doc.NewPackageDoc(pkg, importpath)</code>,
-documentation for a package is created with:
-</p>
-
-<pre>
-    doc.New(pkg, importpath, mode)
-</pre>
-
-<p>
-where the new <code>mode</code> parameter specifies the operation mode:
-if set to <a href="/pkg/go/doc/#AllDecls"><code>AllDecls</code></a>, all declarations
-(not just exported ones) are considered.
-The function <code>NewFileDoc</code> was removed, and the function
-<code>CommentText</code> has become the method
-<a href="/pkg/go/ast/#Text"><code>Text</code></a> of
-<a href="/pkg/go/ast/#CommentGroup"><code>ast.CommentGroup</code></a>.
-</p>
-
-<p>
-In package <a href="/pkg/go/token/"><code>go/token</code></a>, the
-<a href="/pkg/go/token/#FileSet"><code>token.FileSet</code></a> method <code>Files</code>
-(which originally returned a channel of <code>*token.File</code>s) has been replaced
-with the iterator <a href="/pkg/go/token/#FileSet.Iterate"><code>Iterate</code></a> that
-accepts a function argument instead.
-</p>
-
-<p>
-In package <a href="/pkg/go/build/"><code>go/build</code></a>, the API
-has been nearly completely replaced.
-The package still computes Go package information
-but it does not run the build: the <code>Cmd</code> and <code>Script</code>
-types are gone.
-(To build code, use the new
-<a href="/cmd/go/"><code>go</code></a> command instead.)
-The <code>DirInfo</code> type is now named
-<a href="/pkg/go/build/#Package"><code>Package</code></a>.
-<code>FindTree</code> and <code>ScanDir</code> are replaced by
-<a href="/pkg/go/build/#Import"><code>Import</code></a>
-and
-<a href="/pkg/go/build/#ImportDir"><code>ImportDir</code></a>.
-</p>
-
-<p>
-<em>Updating</em>:
-Code that uses packages in <code>go</code> will have to be updated by hand; the
-compiler will reject incorrect uses. Templates used in conjunction with any of the
-<code>go/doc</code> types may need manual fixes; the renamed fields will lead
-to run-time errors.
-</p>
-
-<h3 id="hash">The hash package</h3>
-
-<p>
-In Go 1, the definition of <a href="/pkg/hash/#Hash"><code>hash.Hash</code></a> includes
-a new method, <code>BlockSize</code>.  This new method is used primarily in the 
-cryptographic libraries.
-</p>
-
-<p>
-The <code>Sum</code> method of the
-<a href="/pkg/hash/#Hash"><code>hash.Hash</code></a> interface now takes a
-<code>[]byte</code> argument, to which the hash value will be appended.
-The previous behavior can be recreated by adding a <code>nil</code> argument to the call.
-</p>
-
-<p>
-<em>Updating</em>:
-Existing implementations of <code>hash.Hash</code> will need to add a
-<code>BlockSize</code> method.  Hashes that process the input one byte at
-a time can implement <code>BlockSize</code> to return 1.
-Running <code>go</code> <code>fix</code> will update calls to the <code>Sum</code> methods of the various
-implementations of <code>hash.Hash</code>.
-</p>
-
-<p>
-<em>Updating</em>:
-Since the package's functionality is new, no updating is necessary.
-</p>
-
-<h3 id="http">The http package</h3>
-
-<p>
-In Go 1 the <a href="/pkg/net/http/"><code>http</code></a> package is refactored,
-putting some of the utilities into a
-<a href="/pkg/net/httputil/"><code>httputil</code></a> subdirectory.
-These pieces are only rarely needed by HTTP clients.
-The affected items are:
-</p>
-
-<ul>
-<li>ClientConn</li>
-<li>DumpRequest</li>
-<li>DumpRequest</li>
-<li>DumpRequestOut</li>
-<li>DumpResponse</li>
-<li>NewChunkedReader</li>
-<li>NewChunkedWriter</li>
-<li>NewClientConn</li>
-<li>NewProxyClientConn</li>
-<li>NewServerConn</li>
-<li>NewSingleHostReverseProxy</li>
-<li>ReverseProxy</li>
-<li>ServerConn</li>
-</ul>
-
-<p>
-The <code>Request.RawURL</code> field has been removed; it was a
-historical artifact.
-</p>
-
-<p>
-The <code>Handle</code> and <code>HandleFunc</code>
-functions, and the similarly-named methods of <code>ServeMux</code>,
-now panic if an attempt is made to register the same pattern twice.
-</p>
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will update the few programs that are affected except for
-uses of <code>RawURL</code>, which must be fixed by hand.
-</p>
-
-<h3 id="image">The image package</h3>
-
-<p>
-The <a href="/pkg/image/"><code>image</code></a> package has had a number of
-minor changes, rearrangements and renamings.
-</p>
-
-<p>
-Most of the color handling code has been moved into its own package,
-<a href="/pkg/image/color/"><code>image/color</code></a>.
-For the elements that moved, a symmetry arises; for instance,
-each pixel of an
-<a href="/pkg/image/#RGBA"><code>image.RGBA</code></a>
-is a
-<a href="/pkg/image/color/#RGBA"><code>color.RGBA</code></a>.
-</p>
-
-<p>
-The old <code>image/ycbcr</code> package has been folded, with some
-renamings, into the
-<a href="/pkg/image/"><code>image</code></a>
-and
-<a href="/pkg/image/color/"><code>image/color</code></a>
-packages.
-</p>
-
-<p>
-The old <code>image.ColorImage</code> type is still in the <code>image</code>
-package but has been renamed
-<a href="/pkg/image/#Uniform"><code>image.Uniform</code></a>,
-while <code>image.Tiled</code> has been removed.
-</p>
-
-<p>
-This table lists the renamings.
-</p>
-
-<table class="codetable" frame="border" summary="image renames">
-<colgroup align="left" width="50%"></colgroup>
-<colgroup align="left" width="50%"></colgroup>
-<tr>
-<th align="left">Old</th>
-<th align="left">New</th>
-</tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>image.Color</td> <td>color.Color</td></tr>
-<tr><td>image.ColorModel</td> <td>color.Model</td></tr>
-<tr><td>image.ColorModelFunc</td> <td>color.ModelFunc</td></tr>
-<tr><td>image.PalettedColorModel</td> <td>color.Palette</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>image.RGBAColor</td> <td>color.RGBA</td></tr>
-<tr><td>image.RGBA64Color</td> <td>color.RGBA64</td></tr>
-<tr><td>image.NRGBAColor</td> <td>color.NRGBA</td></tr>
-<tr><td>image.NRGBA64Color</td> <td>color.NRGBA64</td></tr>
-<tr><td>image.AlphaColor</td> <td>color.Alpha</td></tr>
-<tr><td>image.Alpha16Color</td> <td>color.Alpha16</td></tr>
-<tr><td>image.GrayColor</td> <td>color.Gray</td></tr>
-<tr><td>image.Gray16Color</td> <td>color.Gray16</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>image.RGBAColorModel</td> <td>color.RGBAModel</td></tr>
-<tr><td>image.RGBA64ColorModel</td> <td>color.RGBA64Model</td></tr>
-<tr><td>image.NRGBAColorModel</td> <td>color.NRGBAModel</td></tr>
-<tr><td>image.NRGBA64ColorModel</td> <td>color.NRGBA64Model</td></tr>
-<tr><td>image.AlphaColorModel</td> <td>color.AlphaModel</td></tr>
-<tr><td>image.Alpha16ColorModel</td> <td>color.Alpha16Model</td></tr>
-<tr><td>image.GrayColorModel</td> <td>color.GrayModel</td></tr>
-<tr><td>image.Gray16ColorModel</td> <td>color.Gray16Model</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>ycbcr.RGBToYCbCr</td> <td>color.RGBToYCbCr</td></tr>
-<tr><td>ycbcr.YCbCrToRGB</td> <td>color.YCbCrToRGB</td></tr>
-<tr><td>ycbcr.YCbCrColorModel</td> <td>color.YCbCrModel</td></tr>
-<tr><td>ycbcr.YCbCrColor</td> <td>color.YCbCr</td></tr>
-<tr><td>ycbcr.YCbCr</td> <td>image.YCbCr</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>ycbcr.SubsampleRatio444</td> <td>image.YCbCrSubsampleRatio444</td></tr>
-<tr><td>ycbcr.SubsampleRatio422</td> <td>image.YCbCrSubsampleRatio422</td></tr>
-<tr><td>ycbcr.SubsampleRatio420</td> <td>image.YCbCrSubsampleRatio420</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>image.ColorImage</td> <td>image.Uniform</td></tr>
-</table>
-
-<p>
-The image package's <code>New</code> functions
-(<a href="/pkg/image/#NewRGBA"><code>NewRGBA</code></a>,
-<a href="/pkg/image/#NewRGBA64"><code>NewRGBA64</code></a>, etc.)
-take an <a href="/pkg/image/#Rectangle"><code>image.Rectangle</code></a> as an argument
-instead of four integers.
-</p>
-
-<p>
-Finally, there are new predefined <code>color.Color</code> variables
-<a href="/pkg/image/color/#Black"><code>color.Black</code></a>,
-<a href="/pkg/image/color/#White"><code>color.White</code></a>,
-<a href="/pkg/image/color/#Opaque"><code>color.Opaque</code></a>
-and
-<a href="/pkg/image/color/#Transparent"><code>color.Transparent</code></a>.
-</p>
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will update almost all code affected by the change.
-</p>
-
-<h3 id="log_syslog">The log/syslog package</h3>
-
-<p>
-In Go 1, the <a href="/pkg/log/syslog/#NewLogger"><code>syslog.NewLogger</code></a>     
-function returns an error as well as a <code>log.Logger</code>.
-</p>
-
-<p>
-<em>Updating</em>:
-What little code is affected will be caught by the compiler and must be updated by hand.
-</p>
-
-<h3 id="mime">The mime package</h3>
-
-<p>
-In Go 1, the <a href="/pkg/mime/#FormatMediaType"><code>FormatMediaType</code></a> function
-of the <code>mime</code> package has  been simplified to make it
-consistent with
-<a href="/pkg/mime/#ParseMediaType"><code>ParseMediaType</code></a>. 
-It now takes <code>"text/html"</code> rather than <code>"text"</code> and <code>"html"</code>.
-</p>
-
-<p>
-<em>Updating</em>:
-What little code is affected will be caught by the compiler and must be updated by hand.
-</p>
-
-<h3 id="net">The net package</h3>
-
-<p>
-In Go 1, the various <code>SetTimeout</code>,
-<code>SetReadTimeout</code>, and <code>SetWriteTimeout</code> methods
-have been replaced with 
-<a href="/pkg/net/#IPConn.SetDeadline"><code>SetDeadline</code></a>,
-<a href="/pkg/net/#IPConn.SetReadDeadline"><code>SetReadDeadline</code></a>, and 
-<a href="/pkg/net/#IPConn.SetWriteDeadline"><code>SetWriteDeadline</code></a>,
-respectively.  Rather than taking a timeout value in nanoseconds that
-apply to any activity on the connection, the new methods set an
-absolute deadline (as a <code>time.Time</code> value) after which
-reads and writes will time out and no longer block.
-</p>
-
-<p>
-There are also new functions
-<a href="/pkg/net/#DialTimeout"><code>net.DialTimeout</code></a>
-to simplify timing out dialing a network address and
-<a href="/pkg/net/#ListenMulticastUDP"><code>net.ListenMulticastUDP</code></a>
-to allow multicast UDP to listen concurrently across multiple listeners.
-The <code>net.ListenMulticastUDP</code> function replaces the old
-<code>JoinGroup</code> and <code>LeaveGroup</code> methods.
-</p>
-
-<p>
-<em>Updating</em>:
-Code that uses the old methods will fail to compile and must be updated by hand.
-The semantic change makes it difficult for the fix tool to update automatically.
-</p>
-
-<h3 id="os">The os package</h3>
-
-<p>
-The <code>Time</code> function has been removed; callers should use
-the <a href="/pkg/time/#Time"><code>Time</code></a> type from the
-<code>time</code> package.
-</p>
-
-<p>
-The <code>Exec</code> function has been removed; callers should use
-<code>Exec</code> from the <code>syscall</code> package, where available.
-</p>
-
-<p>
-The <code>ShellExpand</code> function has been renamed to <a
-href="/pkg/os/#ExpandEnv"><code>ExpandEnv</code></a>.
-</p>
-
-<p>
-The <a href="/pkg/os/#NewFile"><code>NewFile</code></a> function
-now takes a <code>uintptr</code> fd, instead of an <code>int</code>.
-The <a href="/pkg/os/#File.Fd"><code>Fd</code></a> method on files now
-also returns a <code>uintptr</code>.
-</p>
-
-<p>
-There are no longer error constants such as <code>EINVAL</code>
-in the <code>os</code> package, since the set of values varied with
-the underlying operating system. There are new portable functions like
-<a href="/pkg/os/#IsPermission"><code>IsPermission</code></a>
-to test common error properties, plus a few new error values
-with more Go-like names, such as
-<a href="/pkg/os/#ErrPermission"><code>ErrPermission</code></a>
-and
-<a href="/pkg/os/#ErrNoEnv"><code>ErrNoEnv</code></a>.
-</p>
-
-<p>
-The <code>Getenverror</code> function has been removed. To distinguish
-between a non-existent environment variable and an empty string,
-use <a href="/pkg/os/#Environ"><code>os.Environ</code></a> or
-<a href="/pkg/syscall/#Getenv"><code>syscall.Getenv</code></a>.
-</p>
-
-
-<p>
-The <a href="/pkg/os/#Process.Wait"><code>Process.Wait</code></a> method has
-dropped its option argument and the associated constants are gone
-from the package.
-Also, the function <code>Wait</code> is gone; only the method of
-the <code>Process</code> type persists.
-</p>
-
-<p>
-The <code>Waitmsg</code> type returned by
-<a href="/pkg/os/#Process.Wait"><code>Process.Wait</code></a>
-has been replaced with a more portable
-<a href="/pkg/os/#ProcessState"><code>ProcessState</code></a>
-type with accessor methods to recover information about the
-process.
-Because of changes to <code>Wait</code>, the <code>ProcessState</code>
-value always describes an exited process.
-Portability concerns simplified the interface in other ways, but the values returned by the
-<a href="/pkg/os/#ProcessState.Sys"><code>ProcessState.Sys</code></a> and
-<a href="/pkg/os/#ProcessState.SysUsage"><code>ProcessState.SysUsage</code></a>
-methods can be type-asserted to underlying system-specific data structures such as
-<a href="/pkg/syscall/#WaitStatus"><code>syscall.WaitStatus</code></a> and
-<a href="/pkg/syscall/#Rusage"><code>syscall.Rusage</code></a> on Unix.
-</p>
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will drop a zero argument to <code>Process.Wait</code>.
-All other changes will be caught by the compiler and must be updated by hand.
-</p>
-
-<h4 id="os_fileinfo">The os.FileInfo type</h4>
-
-<p>
-Go 1 redefines the <a href="/pkg/os/#FileInfo"><code>os.FileInfo</code></a> type,
-changing it from a struct to an interface:
-</p>
-
-<pre>
-    type FileInfo interface {
-        Name() string       // base name of the file
-        Size() int64        // length in bytes
-        Mode() FileMode     // file mode bits
-        ModTime() time.Time // modification time
-        IsDir() bool        // abbreviation for Mode().IsDir()
-        Sys() interface{}   // underlying data source (can return nil)
-    }
-</pre>
-
-<p>
-The file mode information has been moved into a subtype called
-<a href="/pkg/os/#FileMode"><code>os.FileMode</code></a>,
-a simple integer type with <code>IsDir</code>, <code>Perm</code>, and <code>String</code>
-methods.
-</p>
-
-<p>
-The system-specific details of file modes and properties such as (on Unix)
-i-number have been removed from <code>FileInfo</code> altogether.
-Instead, each operating system's <code>os</code> package provides an
-implementation of the <code>FileInfo</code> interface, which
-has a <code>Sys</code> method that returns the
-system-specific representation of file metadata.
-For instance, to discover the i-number of a file on a Unix system, unpack
-the <code>FileInfo</code> like this:
-</p>
-
-<pre>
-    fi, err := os.Stat("hello.go")
-    if err != nil {
-        log.Fatal(err)
-    }
-    // Check that it's a Unix file.
-    unixStat, ok := fi.Sys().(*syscall.Stat_t)
-    if !ok {
-        log.Fatal("hello.go: not a Unix file")
-    }
-    fmt.Printf("file i-number: %d\n", unixStat.Ino)
-</pre>
-
-<p>
-Assuming (which is unwise) that <code>"hello.go"</code> is a Unix file,
-the i-number expression could be contracted to
-</p>
-
-<pre>
-    fi.Sys().(*syscall.Stat_t).Ino
-</pre>
-
-<p>
-The vast majority of uses of <code>FileInfo</code> need only the methods
-of the standard interface.
-</p>
-
-<p>
-The <code>os</code> package no longer contains wrappers for the POSIX errors
-such as <code>ENOENT</code>.
-For the few programs that need to verify particular error conditions, there are
-now the boolean functions
-<a href="/pkg/os/#IsExist"><code>IsExist</code></a>,
-<a href="/pkg/os/#IsNotExist"><code>IsNotExist</code></a>
-and
-<a href="/pkg/os/#IsPermission"><code>IsPermission</code></a>.
-</p>
-
-{{code "progs/go1.go" `/os\.Open/` `/}/`}}
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will update code that uses the old equivalent of the current <code>os.FileInfo</code>
-and <code>os.FileMode</code> API.
-Code that needs system-specific file details will need to be updated by hand.
-Code that uses the old POSIX error values from the <code>os</code> package
-will fail to compile and will also need to be updated by hand.
-</p>
-
-<h3 id="os_signal">The os/signal package</h3>
-
-<p>
-The <code>os/signal</code> package in Go 1 replaces the
-<code>Incoming</code> function, which returned a channel
-that received all incoming signals,
-with the selective <code>Notify</code> function, which asks
-for delivery of specific signals on an existing channel.
-</p>
-
-<p>
-<em>Updating</em>:
-Code must be updated by hand.
-A literal translation of
-</p>
-<pre>
-c := signal.Incoming()
-</pre>
-<p>
-is
-</p>
-<pre>
-c := make(chan os.Signal)
-signal.Notify(c) // ask for all signals
-</pre>
-<p>
-but most code should list the specific signals it wants to handle instead:
-</p>
-<pre>
-c := make(chan os.Signal)
-signal.Notify(c, syscall.SIGHUP, syscall.SIGQUIT)
-</pre>
-
-<h3 id="path_filepath">The path/filepath package</h3>
-
-<p>
-In Go 1, the <a href="/pkg/path/filepath/#Walk"><code>Walk</code></a> function of the
-<code>path/filepath</code> package
-has been changed to take a function value of type
-<a href="/pkg/path/filepath/#WalkFunc"><code>WalkFunc</code></a>
-instead of a <code>Visitor</code> interface value.
-<code>WalkFunc</code> unifies the handling of both files and directories.
-</p>
-
-<pre>
-    type WalkFunc func(path string, info os.FileInfo, err error) error
-</pre>
-
-<p>
-The <code>WalkFunc</code> function will be called even for files or directories that could not be opened;
-in such cases the error argument will describe the failure.
-If a directory's contents are to be skipped,
-the function should return the value <a href="/pkg/path/filepath/#variables"><code>filepath.SkipDir</code></a>
-</p>
-
-{{code "progs/go1.go" `/STARTWALK/` `/ENDWALK/`}}
-
-<p>
-<em>Updating</em>:
-The change simplifies most code but has subtle consequences, so affected programs
-will need to be updated by hand.
-The compiler will catch code using the old interface.
-</p>
-
-<h3 id="regexp">The regexp package</h3>
-
-<p>
-The <a href="/pkg/regexp/"><code>regexp</code></a> package has been rewritten.
-It has the same interface but the specification of the regular expressions 
-it supports has changed from the old "egrep" form to that of
-<a href="http://code.google.com/p/re2/">RE2</a>.
-</p>
-
-<p>
-<em>Updating</em>:
-Code that uses the package should have its regular expressions checked by hand.
-</p>
-
-<h3 id="runtime">The runtime package</h3>
-
-<p>
-In Go 1, much of the API exported by package
-<code>runtime</code> has been removed in favor of
-functionality provided by other packages.
-Code using the <code>runtime.Type</code> interface
-or its specific concrete type implementations should
-now use package <a href="/pkg/reflect/"><code>reflect</code></a>.
-Code using <code>runtime.Semacquire</code> or <code>runtime.Semrelease</code>
-should use channels or the abstractions in package <a href="/pkg/sync/"><code>sync</code></a>.
-The <code>runtime.Alloc</code>, <code>runtime.Free</code>,
-and <code>runtime.Lookup</code> functions, an unsafe API created for
-debugging the memory allocator, have no replacement.
-</p>
-
-<p>
-Before, <code>runtime.MemStats</code> was a global variable holding
-statistics about memory allocation, and calls to <code>runtime.UpdateMemStats</code>
-ensured that it was up to date.
-In Go 1, <code>runtime.MemStats</code> is a struct type, and code should use
-<a href="/pkg/runtime/#ReadMemStats"><code>runtime.ReadMemStats</code></a>
-to obtain the current statistics.
-</p>
-
-<p>
-The package adds a new function,
-<a href="/pkg/runtime/#NumCPU"><code>runtime.NumCPU</code></a>, that returns the number of CPUs available
-for parallel execution, as reported by the operating system kernel.
-Its value can inform the setting of <code>GOMAXPROCS</code>.
-The <code>runtime.Cgocalls</code> and <code>runtime.Goroutines</code> functions
-have been renamed to <code>runtime.NumCgoCall</code> and <code>runtime.NumGoroutine</code>.
-</p>
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will update code for the function renamings.
-Other code will need to be updated by hand.
-</p>
-
-<h3 id="strconv">The strconv package</h3>
-
-<p>
-In Go 1, the
-<a href="/pkg/strconv/"><code>strconv</code></a>
-package has been significantly reworked to make it more Go-like and less C-like,
-although <code>Atoi</code> lives on (it's similar to
-<code>int(ParseInt(x, 10, 0))</code>, as does
-<code>Itoa(x)</code> (<code>FormatInt(int64(x), 10)</code>).
-There are also new variants of some of the functions that append to byte slices rather than
-return strings, to allow control over allocation.
-</p>
-
-<p>
-This table summarizes the renamings; see the
-<a href="/pkg/strconv/">package documentation</a>
-for full details.
-</p>
-
-<table class="codetable" frame="border" summary="strconv renames">
-<colgroup align="left" width="50%"></colgroup>
-<colgroup align="left" width="50%"></colgroup>
-<tr>
-<th align="left">Old call</th>
-<th align="left">New call</th>
-</tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>Atob(x)</td> <td>ParseBool(x)</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>Atof32(x)</td> <td>ParseFloat(x, 32)§</td></tr>
-<tr><td>Atof64(x)</td> <td>ParseFloat(x, 64)</td></tr>
-<tr><td>AtofN(x, n)</td> <td>ParseFloat(x, n)</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>Atoi(x)</td> <td>Atoi(x)</td></tr>
-<tr><td>Atoi(x)</td> <td>ParseInt(x, 10, 0)§</td></tr>
-<tr><td>Atoi64(x)</td> <td>ParseInt(x, 10, 64)</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>Atoui(x)</td> <td>ParseUint(x, 10, 0)§</td></tr>
-<tr><td>Atoi64(x)</td> <td>ParseInt(x, 10, 64)</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>Btoi64(x, b)</td> <td>ParseInt(x, b, 64)</td></tr>
-<tr><td>Btoui64(x, b)</td> <td>ParseUint(x, b, 64)</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>Btoa(x)</td> <td>FormatBool(x)</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>Ftoa32(x, f, p)</td> <td>FormatFloat(float64(x), f, p, 32)</td></tr>
-<tr><td>Ftoa64(x, f, p)</td> <td>FormatFloat(x, f, p, 64)</td></tr>
-<tr><td>FtoaN(x, f, p, n)</td> <td>FormatFloat(x, f, p, n)</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>Itoa(x)</td> <td>Itoa(x)</td></tr>
-<tr><td>Itoa(x)</td> <td>FormatInt(int64(x), 10)</td></tr>
-<tr><td>Itoa64(x)</td> <td>FormatInt(x, 10)</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>Itob(x, b)</td> <td>FormatInt(int64(x), b)</td></tr>
-<tr><td>Itob64(x, b)</td> <td>FormatInt(x, b)</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>Uitoa(x)</td> <td>FormatUint(uint64(x), 10)</td></tr>
-<tr><td>Uitoa64(x)</td> <td>FormatUint(x, 10)</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>Uitob(x, b)</td> <td>FormatUint(uint64(x), b)</td></tr>
-<tr><td>Uitob64(x, b)</td> <td>FormatUint(x, b)</td></tr>
-</table>
-		
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will update almost all code affected by the change.
-<br>
-§ <code>Atoi</code> persists but <code>Atoui</code> and <code>Atof32</code> do not, so
-they may require
-a cast that must be added by hand; the <code>go</code> <code>fix</code> tool will warn about it.
-</p>
-
-
-<h3 id="testing">The testing package</h3>
-
-<p>
-The testing package has a type, <code>B</code>, passed as an argument to benchmark functions.
-In Go 1, <code>B</code> has new methods, analogous to those of <code>T</code>, enabling
-logging and failure reporting.
-</p>
-
-{{code "progs/go1.go" `/func.*Benchmark/` `/^}/`}}
-
-<p>
-<em>Updating</em>:
-Existing code is unaffected, although benchmarks that use <code>println</code>
-or <code>panic</code> should be updated to use the new methods.
-</p>
-
-<h3 id="testing_script">The testing/script package</h3>
-
-<p>
-The testing/script package has been deleted. It was a dreg.
-</p>
-
-<p>
-<em>Updating</em>:
-No code is likely to be affected.
-</p>
-
-<h3 id="unsafe">The unsafe package</h3>
-
-<p>
-In Go 1, the functions
-<code>unsafe.Typeof</code>, <code>unsafe.Reflect</code>,
-<code>unsafe.Unreflect</code>, <code>unsafe.New</code>, and
-<code>unsafe.NewArray</code> have been removed;
-they duplicated safer functionality provided by
-package <a href="/pkg/reflect/"><code>reflect</code></a>.
-</p>
-
-<p>
-<em>Updating</em>:
-Code using these functions must be rewritten to use
-package <a href="/pkg/reflect/"><code>reflect</code></a>.
-The changes to <a href="http://code.google.com/p/go/source/detail?r=2646dc956207">encoding/gob</a> and the <a href="http://code.google.com/p/goprotobuf/source/detail?r=5340ad310031">protocol buffer library</a>
-may be helpful as examples.
-</p>
-
-<h3 id="url">The url package</h3>
-
-<p>
-In Go 1 several fields from the <a href="/pkg/net/url/#URL"><code>url.URL</code></a> type
-were removed or replaced.
-</p>
-
-<p>
-The <a href="/pkg/net/url/#URL.String"><code>String</code></a> method now
-predictably rebuilds an encoded URL string using all of <code>URL</code>'s
-fields as necessary. The resulting string will also no longer have
-passwords escaped.
-</p>
-
-<p>
-The <code>Raw</code> field has been removed. In most cases the <code>String</code>
-method may be used in its place.
-</p>
-
-<p>
-The old <code>RawUserinfo</code> field is replaced by the <code>User</code>
-field, of type <a href="/pkg/net/url/#Userinfo"><code>*net.Userinfo</code></a>.
-Values of this type may be created using the new <a href="/pkg/net/url/#User"><code>net.User</code></a>
-and <a href="/pkg/net/url/#UserPassword"><code>net.UserPassword</code></a>
-functions. The <code>EscapeUserinfo</code> and <code>UnescapeUserinfo</code>
-functions are also gone.
-</p>
-
-<p>
-The <code>RawAuthority</code> field has been removed. The same information is
-available in the <code>Host</code> and <code>User</code> fields.
-</p>
-
-<p>
-The <code>RawPath</code> field and the <code>EncodedPath</code> method have
-been removed. The path information in rooted URLs (with a slash following the
-schema) is now available only in decoded form in the <code>Path</code> field.
-Occasionally, the encoded data may be required to obtain information that
-was lost in the decoding process. These cases must be handled by accessing
-the data the URL was built from.
-</p>
-
-<p>
-URLs with non-rooted paths, such as <code>"mailto:dev@golang.org?subject=Hi"</code>,
-are also handled differently. The <code>OpaquePath</code> boolean field has been
-removed and a new <code>Opaque</code> string field introduced to hold the encoded
-path for such URLs. In Go 1, the cited URL parses as:
-</p>
-
-<pre>
-    URL{
-        Scheme: "mailto",
-        Opaque: "dev@golang.org",
-        RawQuery: "subject=Hi",
-    }
-</pre>
-
-<p>
-A new <a href="/pkg/net/url/#URL.RequestURI"><code>RequestURI</code></a> method was
-added to <code>URL</code>.
-</p>
-
-<p>
-The <code>ParseWithReference</code> function has been renamed to <code>ParseWithFragment</code>.
-</p>
-
-<p>
-<em>Updating</em>:
-Code that uses the old fields will fail to compile and must be updated by hand.
-The semantic changes make it difficult for the fix tool to update automatically.
-</p>
-
-<h2 id="cmd_go">The go command</h2>
-
-<p>
-TODO: Write this.
-</p>
-
-<h2 id="cmd_cgo">The cgo command</h2>
-
-<p>
-In Go 1, the <a href="/cmd/cgo">cgo command</a>
-uses a different <code>_cgo_export.h</code>
-file, which is generated for packages containing <code>//export</code> lines.
-The <code>_cgo_export.h</code> file now begins with the C preamble comment,
-so that exported function definitions can use types defined there.
-This has the effect of compiling the preamble multiple times, so a
-package using <code>//export</code> must not put function definitions
-or variable initializations in the C preamble.
-</p>
-
-<h2 id="releases">Packaged releases</h2>
-
diff --git a/doc/go1compat.html b/doc/go1compat.html
index 3804634f5..1dfd382c2 100644
--- a/doc/go1compat.html
+++ b/doc/go1compat.html
@@ -94,6 +94,15 @@ We therefore recommend that composite literals whose type is defined
 in a separate package should use the tagged notation.
 </li>
 
+<li>
+Dot imports. If a program imports a standard package
+using <code>import . "path"</code>, additional names defined in the
+imported package in future releases may conflict with other names
+defined in the program.  We do not recommend the use of <code>import .</code>
+outside of tests, and using it may cause a program to fail
+to compile in future releases.
+</li>
+
 </ul>
 
 <p>
diff --git a/doc/go_faq.html b/doc/go_faq.html
index d95da0f6f..b5b7cc656 100644
--- a/doc/go_faq.html
+++ b/doc/go_faq.html
@@ -76,20 +76,6 @@ The logo and mascot are covered by the
 license.
 </p>
 
-<h3 id="What_kind_of_a_name_is_6g">
-What kind of a name is 6g?</h3>
-
-<p>
-The <code>6g</code> (and <code>8g</code> and <code>5g</code>) compiler is named in the
-tradition of the Plan 9 C compilers, described in
-<a href="http://plan9.bell-labs.com/sys/doc/compiler.html">
-http://plan9.bell-labs.com/sys/doc/compiler.html</a>
-(see the table in section 2).
-
-<code>6</code> is the architecture letter for amd64 (or x86-64, if you prefer), while
-<code>g</code> stands for Go.
-</p>
-
 <h3 id="history">
 What is the history of the project?</h3>
 <p>
@@ -201,8 +187,8 @@ document server running in a production configuration on
 Do Go programs link with C/C++ programs?</h3>
 
 <p>
-There are two Go compiler implementations, <code>6g</code> and friends, 
-generically called <code>gc</code>, and <code>gccgo</code>.
+There are two Go compiler implementations, <code>gc</code>
+(the <code>6g</code> program and friends) and <code>gccgo</code>.
 <code>Gc</code> uses a different calling convention and linker and can
 therefore only be linked with C programs using the same convention.
 There is such a C compiler but no C++ compiler. 
@@ -320,10 +306,9 @@ exceptional.
 <p>
 Go takes a different approach.  For plain error handling, Go's multi-value
 returns make it easy to report an error without overloading the return value.
-<a href="http://blog.golang.org/2011/07/error-handling-and-go.html">A
-canonical error type, coupled
-with Go's other features</a>, makes error
-handling pleasant but quite different from that in other languages.
+<a href="/doc/articles/error_handling.html">A canonical error type, coupled
+with Go's other features</a>, makes error handling pleasant but quite different
+from that in other languages.
 </p>
 
 <p>
@@ -336,7 +321,7 @@ when used well, can result in clean error-handling code.
 </p>
 
 <p>
-See the <a href="http://blog.golang.org/2010/08/defer-panic-and-recover.html">Defer, Panic, and Recover</a> article for details.
+See the <a href="/doc/articles/defer_panic_recover.html">Defer, Panic, and Recover</a> article for details.
 </p>
 
 <h3 id="assertions">
@@ -1009,7 +994,7 @@ Why is <code>int</code> 32 bits on 64 bit machines?</h3>
 <p>
 The sizes of <code>int</code> and <code>uint</code> are implementation-specific
 but the same as each other on a given platform.
-The 64 bit Go compilers (both 6g and gccgo) use a 32 bit representation for
+The 64 bit Go compilers (both gc and gccgo) use a 32 bit representation for
 <code>int</code>.  Code that relies on a particular
 size of value should use an explicitly sized type, like <code>int64</code>.
 On the other hand, floating-point scalars and complex
@@ -1317,8 +1302,7 @@ table-driven, iterating over a list of inputs and outputs defined
 in a data structure (Go has excellent support for data structure literals).
 The work to write a good test and good error messages will then be amortized over many
 test cases. The standard Go library is full of illustrative examples, such as in
-<a href="http://golang.org/src/pkg/fmt/fmt_test.go">the formatting
-tests for the <code>fmt</code> package</a>.
+<a href="/src/pkg/fmt/fmt_test.go">the formatting tests for the <code>fmt</code> package</a>.
 </p>
 
 
@@ -1333,21 +1317,21 @@ standard GCC back end. <code>Gc</code> is written in C using
 <code>yacc</code>/<code>bison</code> for the parser.
 Although it's a new program, it fits in the Plan 9 C compiler suite
 (<a href="http://plan9.bell-labs.com/sys/doc/compiler.html">http://plan9.bell-labs.com/sys/doc/compiler.html</a>)
-and uses a variant of the Plan 9 loader to generate ELF binaries.
+and uses a variant of the Plan 9 loader to generate ELF/Mach-O/PE binaries.
 </p>
 
 <p>
-We considered writing <code>6g</code>, the original Go compiler, in Go itself but
+We considered writing <code>gc</code>, the original Go compiler, in Go itself but
 elected not to do so because of the difficulties of bootstrapping and
 especially of open source distribution&mdash;you'd need a Go compiler to
 set up a Go environment. <code>Gccgo</code>, which came later, makes it possible to
 consider writing a compiler in Go, which might well happen. (Go would be a
 fine language in which to implement a compiler; a native lexer and
-parser are already available in <a href="/pkg/go/"><code>/pkg/go</code></a>.)
+parser are already available in the <a href="/pkg/go/"><code>go</code></a> package.)
 </p>
 
 <p>
-We also considered using LLVM for <code>6g</code> but we felt it was too large and
+We also considered using LLVM for <code>gc</code> but we felt it was too large and
 slow to meet our performance goals.
 </p>
 
@@ -1377,9 +1361,11 @@ type checks, reflection, and even panic-time stack traces.
 </p>
 
 <p>
-A trivial C "hello, world" program compiled and linked statically using gcc
-on Linux is around 750 kB.  An equivalent Go program using <code>fmt.Printf</code>
-is around 1.3 MB, but
+A simple C "hello, world" program compiled and linked statically using gcc
+on Linux is around 750 kB,
+including an implementation of <code>printf</code>.
+An equivalent Go program using <code>fmt.Printf</code>
+is around 1.2 MB, but
 that includes more powerful run-time support.
 </p>
 
@@ -1538,7 +1524,7 @@ and <code>chan</code> keep things clear.
 
 <p>
 See the article about
-<a href="http://blog.golang.org/2010/07/gos-declaration-syntax.html">Go's Declaration Syntax</a>
+<a href="/doc/articles/gos_declaration_syntax.html">Go's Declaration Syntax</a>
 for more details.
 </p>
 
@@ -1588,7 +1574,7 @@ appear on a line by itself.
 Some have argued that the lexer should do lookahead to permit the
 brace to live on the next line.  We disagree.  Since Go code is meant
 to be formatted automatically by
-<a href="http://golang.org/cmd/gofmt/"><code>gofmt</code></a>,
+<a href="/cmd/gofmt/"><code>gofmt</code></a>,
 <i>some</i> style must be chosen.  That style may differ from what
 you've used in C or Java, but Go is a new language and
 <code>gofmt</code>'s style is as good as any other.  More
diff --git a/doc/go_mem.html b/doc/go_mem.html
index a00324158..ece230638 100644
--- a/doc/go_mem.html
+++ b/doc/go_mem.html
@@ -1,6 +1,6 @@
 <!--{
 	"Title": "The Go Memory Model",
-	"Subtitle": "Version of June 10, 2011",
+	"Subtitle": "Version of March 6, 2012",
 	"Path": "/ref/mem"
 }-->
 
@@ -107,9 +107,9 @@ unspecified order.
 <h3>Initialization</h3>
 
 <p>
-Program initialization runs in a single goroutine and
-new goroutines created during initialization do not
-start running until initialization ends.
+Program initialization runs in a single goroutine,
+but that goroutine may create other goroutines,
+which run concurrently.
 </p>
 
 <p class="rule">
@@ -122,11 +122,6 @@ The start of the function <code>main.main</code> happens after
 all <code>init</code> functions have finished.
 </p>
 
-<p class="rule">
-The execution of any goroutines created during <code>init</code>
-functions happens after all <code>init</code> functions have finished.
-</p>
-
 <h3>Goroutine creation</h3>
 
 <p class="rule">
@@ -288,7 +283,7 @@ The <code>sync</code> package implements two lock data types,
 
 <p class="rule">
 For any <code>sync.Mutex</code> or <code>sync.RWMutex</code> variable <code>l</code> and <i>n</i> &lt; <i>m</i>,
-the <i>n</i>'th call to <code>l.Unlock()</code> happens before the <i>m</i>'th call to <code>l.Lock()</code> returns.
+call <i>n</i> of <code>l.Unlock()</code> happens before call <i>m</i> of <code>l.Lock()</code> returns.
 </p>
 
 <p>
@@ -321,9 +316,9 @@ which happens before the <code>print</code>.
 
 <p class="rule">
 For any call to <code>l.RLock</code> on a <code>sync.RWMutex</code> variable <code>l</code>,
-there is an <i>n</i> such that the <code>l.RLock</code> happens (returns) after the <i>n</i>'th call to
+there is an <i>n</i> such that the <code>l.RLock</code> happens (returns) after call <i>n</i> to
 <code>l.Unlock</code> and the matching <code>l.RUnlock</code> happens
-before the <i>n</i>+1'th call to <code>l.Lock</code>.
+before call <i>n</i>+1 to <code>l.Lock</code>.
 </p>
 
 <h3>Once</h3>
diff --git a/doc/go_spec.html b/doc/go_spec.html
index ebd79bb80..2c905c723 100644
--- a/doc/go_spec.html
+++ b/doc/go_spec.html
@@ -1,6 +1,6 @@
 <!--{
 	"Title": "The Go Programming Language Specification",
-	"Subtitle": "Version of March 1, 2012",
+	"Subtitle": "Version of March 17, 2012",
 	"Path": "/ref/spec"
 }-->
 
@@ -75,7 +75,7 @@ double quotes <code>""</code> or back quotes <code>``</code>.
 <p>
 The form <code>a … b</code> represents the set of characters from
 <code>a</code> through <code>b</code> as alternatives. The horizontal
-ellipis <code>…</code> is also used elsewhere in the spec to informally denote various
+ellipsis <code>…</code> is also used elsewhere in the spec to informally denote various
 enumerations or code snippets that are not further specified. The character <code>…</code>
 (as opposed to the three characters <code>...</code>) is not a token of the Go
 language.
@@ -1321,7 +1321,7 @@ Two types are either <i>identical</i> or <i>different</i>.
 
 <p>
 Two named types are identical if their type names originate in the same
-type <a href="#Declarations_and_scope">declaration</a>.
+<a href="#Type_declarations">TypeSpec</a>.
 A named and an unnamed type are always different. Two unnamed types are identical
 if the corresponding type literals are identical, that is, if they have the same
 literal structure and corresponding components have identical types. In detail:
@@ -5403,10 +5403,6 @@ type Pointer *ArbitraryType
 func Alignof(variable ArbitraryType) uintptr
 func Offsetof(selector ArbitraryType) uinptr
 func Sizeof(variable ArbitraryType) uintptr
-
-func Reflect(val interface{}) (typ runtime.Type, addr uintptr)
-func Typeof(val interface{}) (typ interface{})
-func Unreflect(typ runtime.Type, addr uintptr) interface{}
 </pre>
 
 <p>
@@ -5446,23 +5442,6 @@ Calls to <code>Alignof</code>, <code>Offsetof</code>, and
 <code>Sizeof</code> are compile-time constant expressions of type <code>uintptr</code>.
 </p>
 <p>
-The functions <code>unsafe.Typeof</code>,
-<code>unsafe.Reflect</code>,
-and <code>unsafe.Unreflect</code> allow access at run time to the dynamic
-types and values stored in interfaces.
-<code>Typeof</code> returns a representation of
-<code>val</code>'s
-dynamic type as a <code>runtime.Type</code>.
-<code>Reflect</code> allocates a copy of
-<code>val</code>'s dynamic
-value and returns both the type and the address of the copy.
-<code>Unreflect</code> inverts <code>Reflect</code>,
-creating an
-interface value from a type and address.
-The <a href="/pkg/reflect/"><code>reflect</code> package</a> built on these primitives
-provides a safe, more convenient way to inspect interface values.
-</p>
-
 
 <h3 id="Size_and_alignment_guarantees">Size and alignment guarantees</h3>
 
@@ -5499,9 +5478,3 @@ The following minimal alignment properties are guaranteed:
 <p>
 A struct or array type has size zero if it contains no fields (or elements, respectively) that have a size greater than zero. Two distinct zero-size variables may have the same address in memory.
 </p>
-
-
-<h2 id="Implementation_differences">Implementation differences - TODO</h2>
-<ul>
-	<li><span class="alert"><code>len(x)</code> is only a constant if <code>x</code> is a (qualified) identifier denoting an array or pointer to an array.</span></li>
-</ul>
diff --git a/doc/godocs.js b/doc/godocs.js
index cc96cf674..37573136a 100644
--- a/doc/godocs.js
+++ b/doc/godocs.js
@@ -18,13 +18,6 @@ function bindEvent(el, e, fn) {
     el.attachEvent('on'+e, fn);
   }
 }
-bindEvent(window, 'load', godocs_onload);
-
-function godocs_onload() {
-  godocs_bindSearchEvents();
-  godocs_generateTOC();
-  godocs_bindExamples();
-}
 
 function godocs_bindSearchEvents() {
   var search = document.getElementById('search');
@@ -39,7 +32,7 @@ function godocs_bindSearchEvents() {
     }
   }
   function restoreInactive() {
-    if (search.value != "") {
+    if (search.value !== "") {
       return;
     }
     if (search.type != "search") {
@@ -52,6 +45,26 @@ function godocs_bindSearchEvents() {
   bindEvent(search, 'blur', restoreInactive);
 }
 
+/* Returns the "This sweet header" from <h2>This <i>sweet</i> header</h2>.
+ * Takes a node, returns a string.
+ */
+function godocs_nodeToText(node) {
+  var TEXT_NODE = 3; // Defined in Mozilla but not MSIE :(
+
+  var text = '';
+  for (var j = 0; j != node.childNodes.length; j++) {
+    var child = node.childNodes[j];
+    if (child.nodeType == TEXT_NODE) {
+      if (child.nodeValue != '[Top]') { //ok, that's a hack, but it works.
+        text = text + child.nodeValue;
+      }
+    } else {
+      text = text + godocs_nodeToText(child);
+    }
+  }
+  return text;
+}
+
 /* Generates a table of contents: looks for h2 and h3 elements and generates
  * links.  "Decorates" the element with id=="nav" with this table of contents.
  */
@@ -138,56 +151,59 @@ function godocs_generateTOC() {
   tocCell.appendChild(dl2);
 }
 
-/* Returns the "This sweet header" from <h2>This <i>sweet</i> header</h2>.
- * Takes a node, returns a string.
- */
-function godocs_nodeToText(node) {
-  var TEXT_NODE = 3; // Defined in Mozilla but not MSIE :(
-
-  var text = '';
-  for (var j = 0; j != node.childNodes.length; j++) {
-    var child = node.childNodes[j];
-    if (child.nodeType == TEXT_NODE) {
-      if (child.nodeValue != '[Top]') { //ok, that's a hack, but it works.
-        text = text + child.nodeValue;
-      }
-    } else {
-      text = text + godocs_nodeToText(child);
+function getElementsByClassName(base, clazz) {
+  if (base.getElementsByClassName) {
+    return base.getElementsByClassName(clazz);
+  }
+  var elements = base.getElementsByTagName('*'), foundElements = [];
+  for (var n in elements) {
+    if (clazz == elements[n].className) {
+      foundElements.push(elements[n]);
     }
   }
-  return text;
+  return foundElements;
 }
 
-function godocs_bindExamples() {
-  var examples = document.getElementsByClassName("example");
-  for (var i = 0; i < examples.length; i++) {
-    godocs_bindExampleToggle(examples[i]);
-  }
-  var links = document.getElementsByClassName("exampleLink");
-  for (var i = 0; i < links.length; i++) {
-    godocs_bindExampleLink(links[i]);
-  }
-}
 function godocs_bindExampleToggle(eg) {
-  var heading = eg.getElementsByClassName("exampleHeading");
+  var heading = getElementsByClassName(eg, "exampleHeading");
+  var callback = function() {
+    if (eg.className == "example") {
+      eg.className = "exampleVisible";
+    } else {
+      eg.className = "example";
+    }
+  };
   for (var i = 0; i < heading.length; i++) {
-    bindEvent(heading[i], "click", function() {
-      if (eg.className == "example") {
-        eg.className = "exampleVisible";
-      } else {
-        eg.className = "example";
-      }
-    });
+    bindEvent(heading[i], "click", callback);
   }
 }
 function godocs_bindExampleLink(l) {
   var prefix = "example_";
   bindEvent(l, "click", function() {
     var i = l.href.indexOf("#"+prefix);
-    if (i < 0)
+    if (i < 0) {
       return;
+    }
     var id = prefix + l.href.slice(i+1+prefix.length);
     var eg = document.getElementById(id);
     eg.className = "exampleVisible";
   });
 }
+function godocs_bindExamples() {
+  var examples = getElementsByClassName(document, "example");
+  for (var i = 0; i < examples.length; i++) {
+    godocs_bindExampleToggle(examples[i]);
+  }
+  var links = getElementsByClassName(document, "exampleLink");
+  for (i = 0; i < links.length; i++) {
+    godocs_bindExampleLink(links[i]);
+  }
+}
+
+function godocs_onload() {
+  godocs_bindSearchEvents();
+  godocs_generateTOC();
+  godocs_bindExamples();
+}
+
+bindEvent(window, 'load', godocs_onload);
diff --git a/doc/gopher/bumper.png b/doc/gopher/bumper.png
index 6b41c1fd0..b357cdf47 100644
--- a/doc/gopher/bumper.png
+++ b/doc/gopher/bumper.png
diff --git a/doc/gopher/bumper192x108.png b/doc/gopher/bumper192x108.png
index 470a74df5..925474e76 100644
--- a/doc/gopher/bumper192x108.png
+++ b/doc/gopher/bumper192x108.png
diff --git a/doc/gopher/bumper320x180.png b/doc/gopher/bumper320x180.png
index 5b31b5d31..611c417c4 100644
--- a/doc/gopher/bumper320x180.png
+++ b/doc/gopher/bumper320x180.png
diff --git a/doc/gopher/bumper480x270.png b/doc/gopher/bumper480x270.png
index 621f51b65..cf187151f 100644
--- a/doc/gopher/bumper480x270.png
+++ b/doc/gopher/bumper480x270.png
diff --git a/doc/gopher/bumper640x360.png b/doc/gopher/bumper640x360.png
index 9c898d0c7..a5073e0d1 100644
--- a/doc/gopher/bumper640x360.png
+++ b/doc/gopher/bumper640x360.png
diff --git a/doc/gopher/doc.png b/doc/gopher/doc.png
new file mode 100644
index 000000000..e15a3234d
--- /dev/null
+++ b/doc/gopher/doc.png
diff --git a/doc/gopher/frontpage.png b/doc/gopher/frontpage.png
index ed1f49b05..1eb81f0be 100644
--- a/doc/gopher/frontpage.png
+++ b/doc/gopher/frontpage.png
diff --git a/doc/gopher/gopherbw.png b/doc/gopher/gopherbw.png
index 48a08cc61..3bfe85dc1 100644
--- a/doc/gopher/gopherbw.png
+++ b/doc/gopher/gopherbw.png
diff --git a/doc/gopher/gophercolor.png b/doc/gopher/gophercolor.png
index b48ffba37..b5f8d01ff 100644
--- a/doc/gopher/gophercolor.png
+++ b/doc/gopher/gophercolor.png
diff --git a/doc/gopher/gophercolor16x16.png b/doc/gopher/gophercolor16x16.png
index 48854ff3b..ec7028cc1 100644
--- a/doc/gopher/gophercolor16x16.png
+++ b/doc/gopher/gophercolor16x16.png
diff --git a/doc/gopher/help.png b/doc/gopher/help.png
new file mode 100644
index 000000000..6ee523898
--- /dev/null
+++ b/doc/gopher/help.png
diff --git a/doc/gopher/pkg.png b/doc/gopher/pkg.png
new file mode 100644
index 000000000..ac96551b5
--- /dev/null
+++ b/doc/gopher/pkg.png
diff --git a/doc/gopher/project.png b/doc/gopher/project.png
new file mode 100644
index 000000000..24603f306
--- /dev/null
+++ b/doc/gopher/project.png
diff --git a/doc/gopher/ref.png b/doc/gopher/ref.png
index 26530a3a0..0508f6ec6 100644
--- a/doc/gopher/ref.png
+++ b/doc/gopher/ref.png
diff --git a/doc/gopher/run.png b/doc/gopher/run.png
new file mode 100644
index 000000000..eb690e3f2
--- /dev/null
+++ b/doc/gopher/run.png
diff --git a/doc/gopher/talks.png b/doc/gopher/talks.png
new file mode 100644
index 000000000..589db470a
--- /dev/null
+++ b/doc/gopher/talks.png
diff --git a/doc/help.html b/doc/help.html
index 2efda4e30..fadf80a03 100644
--- a/doc/help.html
+++ b/doc/help.html
@@ -3,6 +3,8 @@
 	"Path": "/help/"
 }-->
 
+<img class="gopher" src="/doc/gopher/help.png"/>
+
 <p>
 Need help with Go? Try these resources.
 </p>
diff --git a/doc/install-source.html b/doc/install-source.html
index 5a17844b2..82ff8e740 100644
--- a/doc/install-source.html
+++ b/doc/install-source.html
@@ -97,7 +97,9 @@ If you want to build 32-bit binaries on a 64-bit system you'll also need the
 </p>
 
 <p>
-<font color="red">TODO: add Windows compiler info</font>
+On Windows, install <code>gcc</code> with
+<a href="http://www.mingw.org/">MinGW</a>.
+(Make sure you add its <code>bin</code> subdirectory to your <code>PATH</code>.)
 </p>
 
 <h2 id="mercurial">Install Mercurial, if needed</h2>
@@ -105,7 +107,7 @@ If you want to build 32-bit binaries on a 64-bit system you'll also need the
 <p>
 To perform the next step you must have Mercurial installed. (Check that you
 have an <code>hg</code> command.) This suffices to install Mercurial on most
-systems:
+Unix systems:
 </p>
 
 <pre>
@@ -113,8 +115,7 @@ sudo easy_install mercurial==2.0
 </pre>
 
 <p>
-On Ubuntu/Debian, 
-the Mercurial in your distribution's
+On Ubuntu/Debian, the Mercurial in your distribution's
 package repository is most likely old and broken.
 You might try this first:
 </p>
@@ -122,7 +123,7 @@ You might try this first:
 <pre>apt-get install python-setuptools python-dev build-essential</pre>
 
 <p>
-If that fails, try installing manually from the
+If that fails, or if you use Windows, install manually from the
 <a href="http://mercurial.selenic.com/wiki/Download">Mercurial Download</a>
 page.
 </p>
@@ -254,22 +255,13 @@ Bugs can be reported using the <a href="http://code.google.com/p/go/issues/list"
 <h2 id="releases">Keeping up with releases</h2>
 
 <p>
-XXX TODO XXX
-</p>
-
-<p>
 The Go project maintains two stable tags in its Mercurial repository:
 <code>release</code> and <code>weekly</code>.
-The <code>weekly</code> tag is updated about once a week, and should be used by
-those who want to track the project's development.
-The <code>release</code> tag is given, less often, to those weekly releases
-that have proven themselves to be robust.
 </p>
 
 <p>
-Most Go users will want to keep their Go installation at the latest
-<code>release</code> tag.
-New releases are announced on the
+The <code>release</code> tag refers to the current stable release of Go.
+Most Go users should use this version. New releases are announced on the
 <a href="http://groups.google.com/group/golang-announce">golang-announce</a>
 mailing list.
 </p>
@@ -286,6 +278,8 @@ $ ./all.bash
 </pre>
 
 <p>
+The <code>weekly</code> tag is updated about once a week, and should be used 
+only by those who are actively working on the Go core.
 To use the <code>weekly</code> tag run <code>hg update weekly</code> instead.
 </p>
 
@@ -298,143 +292,123 @@ The Go compilation environment can be customized by environment variables.
 to override the defaults.
 </p>
 
-<dl>
-<dt>
-	<code>$GOROOT</code>
-</dt>
-<dd>
-	<p>
-	XXX FONT IS WRONG IN THESE ENTRIES XXX
-	XXX I NEED SOME SPAN THING XXX
-	The root of the Go tree, often <code>$HOME/go</code>.
-	Its value is built into the tree when it is compiled, and
-	defaults to the parent of the directory where <code>all.bash</code> was run.
-	There is no need to set this unless you want to switch between multiple
-	local copies of the repository.
-	</p>
-</dd>
-
-<dt>
-	<code>$GOROOT_FINAL</code>
-</dt>
-<dd>
-	<p>
-	The value assumed by installed binaries and scripts when
-	<code>$GOROOT</code> is not set explicitly.
-	It defaults to the value of <code>$GOROOT</code>.
-	If you want to build the Go tree in one location
-	but move it elsewhere after the build, set 
-	<code>$GOROOT_FINAL</code> to the eventual location.
-	</p>
-</dd>
-
-<dt>
-<code>$GOOS</code> and <code>$GOARCH</code>
-</dt>
-<dd>
-	<p>
-	The name of the target operating system and compilation architecture.
-	These default to the values of <code>$GOHOSTOS</code> and
-	<code>$GOHOSTARCH</code> respectively (described below).
-
-	<p>
-	Choices for <code>$GOOS</code> are
-	<code>darwin</code> (Mac OS X 10.5 and above), <code>freebsd</code>,
-	<code>linux</code>, <code>netbsd</code>, <code>openbsd</code>, 
-	<code>plan9</code>, and <code>windows</code>.
-	Choices for <code>$GOARCH</code> are
-	<code>amd64</code> (64-bit x86, the most mature port),
-	<code>386</code> (32-bit x86), and <code>arm</code> (32-bit ARM).
-	The valid combinations of <code>$GOOS</code> and <code>$GOARCH</code> are:
-	<table cellpadding="0">
-	<tr>
-	<th width="50"><th align="left" width="100"><code>$GOOS</code></th> <th align="left" width="100"><code>$GOARCH</code></th> <th align="left"></th>
-	</tr>
-	<tr>
-	<td></td><td><code>darwin</code></td> <td><code>386</code></td>
-	</tr>
-	<tr>
-	<td></td><td><code>darwin</code></td> <td><code>amd64</code></td>
-	</tr>
-	<tr>
-	<td></td><td><code>freebsd</code></td> <td><code>386</code></td>
-	</tr>
-	<tr>
-	<td></td><td><code>freebsd</code></td> <td><code>amd64</code></td>
-	</tr>
-	<tr>
-	<td></td><td><code>linux</code></td> <td><code>386</code></td>
-	</tr>
-	<tr>
-	<td></td><td><code>linux</code></td> <td><code>amd64</code></td>
-	</tr>
-	<tr>
-	<td></td><td><code>linux</code></td> <td><code>arm</code></td>
-	</tr>
-	<tr>
-	<td></td><td><code>netbsd</code></td> <td><code>386</code></td>
-	</tr>
-	<tr>
-	<td></td><td><code>netbsd</code></td> <td><code>amd64</code></td>
-	</tr>
-	<tr>
-	<td></td><td><code>openbsd</code></td> <td><code>386</code></td>
-	</tr>
-	<tr>
-	<td></td><td><code>openbsd</code></td> <td><code>amd64</code></td>
-	</tr>
-	<tr>
-	<td></td><td><code>plan9</code></td> <td><code>386</code></td>
-	</tr>
-	<tr>
-	<td></td><td><code>windows</code></td> <td><code>386</code></td>
-	</tr>
-	<tr>
-	<td></td><td><code>windows</code></td> <td><code>amd64</code></td>
-	</tr>
-	</table>
-</dd>
-
-<dt>
-<code>$GOHOSTOS</code> and <code>$GOHOSTARCH</code>
-</dt>
-<dd>
-	<p>
-	The name of the host operating system and compilation architecture.
-	These default to the local system's operating system and
-	architecture.
-
-	<p>
-	Valid choices are the same as for <code>$GOOS</code> and
-	<code>$GOARCH</code>, listed above.
-	The specified values must be compatible with the local system.
-	For example, you should not set <code>$GOHOSTARCH</code> to 
-	<code>arm</code> on an x86 system.
-</dd>
-
-<dt>
-<code>$GOBIN</code>
-</dt>
-<dd>
-	<p>
-	The location where binaries from the main repository will be installed.
-	XXX THIS MAY CHANGE TO BE AN OVERRIDE EVEN FOR GOPATH ENTRIES XXX
-	The default is <code>$GOROOT/bin</code>.
-	After installing, you will want to arrange to add this
-	directory to your <code>$PATH</code>, so you can use the tools.
-</dd>
-
-<dt>
-<code>$GOARM</code> (arm, default=6)
-</dt>
-<dd>
-	<p>
-	The ARM architecture version the run-time libraries should target.
-	Setting <code>$GOARM</code> to 5 causes the linker to emit calls
-	to a software floating point implementation instead of using
-	hardware floating point support.
-</dd>
-</dl>
+<blockquote>
+
+<p><code>$GOROOT</code></p>
+<p>
+The root of the Go tree, often <code>$HOME/go</code>.
+Its value is built into the tree when it is compiled, and
+defaults to the parent of the directory where <code>all.bash</code> was run.
+There is no need to set this unless you want to switch between multiple
+local copies of the repository.
+</p>
+
+<p><code>$GOROOT_FINAL</code></p>
+<p>
+The value assumed by installed binaries and scripts when
+<code>$GOROOT</code> is not set explicitly.
+It defaults to the value of <code>$GOROOT</code>.
+If you want to build the Go tree in one location
+but move it elsewhere after the build, set 
+<code>$GOROOT_FINAL</code> to the eventual location.
+</p>
+
+<p><code>$GOOS</code> and <code>$GOARCH</code></p>
+<p>
+The name of the target operating system and compilation architecture.
+These default to the values of <code>$GOHOSTOS</code> and
+<code>$GOHOSTARCH</code> respectively (described below).
+
+<p>
+Choices for <code>$GOOS</code> are
+<code>darwin</code> (Mac OS X 10.6 and above), <code>freebsd</code>,
+<code>linux</code>, <code>netbsd</code>, <code>openbsd</code>, 
+<code>plan9</code>, and <code>windows</code>.
+Choices for <code>$GOARCH</code> are
+<code>amd64</code> (64-bit x86, the most mature port),
+<code>386</code> (32-bit x86), and <code>arm</code> (32-bit ARM).
+The valid combinations of <code>$GOOS</code> and <code>$GOARCH</code> are:
+<table cellpadding="0">
+<tr>
+<th width="50"><th align="left" width="100"><code>$GOOS</code></th> <th align="left" width="100"><code>$GOARCH</code></th> <th align="left"></th>
+</tr>
+<tr>
+<td></td><td><code>darwin</code></td> <td><code>386</code></td>
+</tr>
+<tr>
+<td></td><td><code>darwin</code></td> <td><code>amd64</code></td>
+</tr>
+<tr>
+<td></td><td><code>freebsd</code></td> <td><code>386</code></td>
+</tr>
+<tr>
+<td></td><td><code>freebsd</code></td> <td><code>amd64</code></td>
+</tr>
+<tr>
+<td></td><td><code>linux</code></td> <td><code>386</code></td>
+</tr>
+<tr>
+<td></td><td><code>linux</code></td> <td><code>amd64</code></td>
+</tr>
+<tr>
+<td></td><td><code>linux</code></td> <td><code>arm</code></td>
+</tr>
+<tr>
+<td></td><td><code>netbsd</code></td> <td><code>386</code></td>
+</tr>
+<tr>
+<td></td><td><code>netbsd</code></td> <td><code>amd64</code></td>
+</tr>
+<tr>
+<td></td><td><code>openbsd</code></td> <td><code>386</code></td>
+</tr>
+<tr>
+<td></td><td><code>openbsd</code></td> <td><code>amd64</code></td>
+</tr>
+<tr>
+<td></td><td><code>plan9</code></td> <td><code>386</code></td>
+</tr>
+<tr>
+<td></td><td><code>windows</code></td> <td><code>386</code></td>
+</tr>
+<tr>
+<td></td><td><code>windows</code></td> <td><code>amd64</code></td>
+</tr>
+</table>
+
+<p><code>$GOHOSTOS</code> and <code>$GOHOSTARCH</code></p>
+<p>
+The name of the host operating system and compilation architecture.
+These default to the local system's operating system and
+architecture.
+</p>
+
+<p>
+Valid choices are the same as for <code>$GOOS</code> and
+<code>$GOARCH</code>, listed above.
+The specified values must be compatible with the local system.
+For example, you should not set <code>$GOHOSTARCH</code> to 
+<code>arm</code> on an x86 system.
+</p>
+
+<p><code>$GOBIN</code>
+<p>
+The location where binaries from the main repository will be installed.
+XXX THIS MAY CHANGE TO BE AN OVERRIDE EVEN FOR GOPATH ENTRIES XXX
+The default is <code>$GOROOT/bin</code>.
+After installing, you will want to arrange to add this
+directory to your <code>$PATH</code>, so you can use the tools.
+</p>
+
+<p><code>$GOARM</code> (arm, default=6)</p>
+<p>
+The ARM architecture version the run-time libraries should target.
+Setting <code>$GOARM</code> to 5 causes the linker to emit calls
+to a software floating point implementation instead of using
+hardware floating point support.
+</p>
+
+</blockquote>
 
 <p>
 Note that <code>$GOARCH</code> and <code>$GOOS</code> identify the
diff --git a/doc/install.html b/doc/install.html
index 4f2bb1c99..c8b1cf4cf 100644
--- a/doc/install.html
+++ b/doc/install.html
@@ -35,7 +35,7 @@ your operating system and processor architecture.
 
 <p>
 Official binary distributions are available
-for the FreeBSD, Linux, Mac OS X, and Windows operating systems
+for the FreeBSD, Linux, Mac OS X (Snow Leopard/Lion), and Windows operating systems
 and the 32-bit (<code>386</code>) and 64-bit (<code>amd64</code>)
 x86 processor architectures.
 </p>
@@ -51,7 +51,8 @@ OS/arch combination you may want to try
 
 <p>
 The Go binary distributions assume they will be installed in
-<code>/usr/local/go</code>, but it is possible to install them in a different
+<code>/usr/local/go</code> (or <code>c:\Go</code> under Windows),
+but it is possible to install them in a different
 location. If you do this, you will need to set the <code>GOROOT</code>
 environment variable to that directory when using the Go tools.
 </p>
@@ -66,6 +67,11 @@ export GOROOT=$HOME/go
 export PATH=$PATH:$GOROOT/bin
 </pre>
 
+<p>
+Windows users should read the section about <a href="#windows_env">setting
+environment variables under Windows</a>.
+</p>
+
 <h3 id="freebsd_linux">FreeBSD and Linux</h3>
 
 <p>
@@ -114,7 +120,48 @@ Terminal sessions for the change to take effect.
 <h3 id="windows">Windows</h3>
 
 <p>
-<font color="red">TODO: windows installation instructions.</font>
+The Go project provides two installation options for Windows users
+(besides <a href="/doc/install/source">installing from source</a>):
+an MSI installer that configures your installation automatically,
+and a zip archive that requires you to set some environment variables.
+</p>
+
+<h4 id="windows_msi">MSI installer</h3>
+
+<p>
+Open the <code>.msi</code> file and follow the prompts to install the Go tools.
+By default, the installer puts the Go distribution in <code>c:\Go</code>.
+</p>
+
+<p>
+The installer should put the <code>c:\Go\bin</code> directory in your
+<code>PATH</code> environment variable. You may need to restart any open
+command prompts for the change to take effect.
+</p>
+
+<h4 id="windows_zip">Zip archive</h3>
+
+<p>
+Extract the <code>.zip</code> file to the directory of your choice (we
+suggest <code>c:\Go</code>).
+</p>
+
+<p>
+If you chose a directory other than <code>c:\Go</code>, you must set
+the <code>GOROOT</code> environment variable to your chosen path.
+</p>
+
+<p>
+Add the <code>bin</code> subdirectory of your Go root (for example, <code>c:\Go\bin</code>) to to your <code>PATH</code> environment variable.
+</p>
+
+<h4 id="windows_env">Setting environment variables under Windows</h4>
+
+<p>
+Under Windows, you may set environment variables through the "Environment
+Variables" button on the "Advanced" tab of the "System" control panel. Some
+versions of Windows provide this control panel through the "Advanced System
+Settings" option inside the "System" control panel.
 </p>
 
 <h2 id="testing">Testing your installation</h2>
@@ -153,8 +200,7 @@ If you see the "hello, world" message then your Go installation is working.
 <h2 id="next">What's next</h2>
 
 <p>
-Start by taking <a href="http://code.google.com/p/go-tour/">A Tour of Go</a>
-or reading the <a href="/doc/go_tutorial.html">Go Tutorial</a>.
+Start by taking <a href="http://code.google.com/p/go-tour/">A Tour of Go</a>.
 </p>
 
 <p>
@@ -173,8 +219,13 @@ idiomatic Go code.
 </p>
 
 <p>
-For the full story, consult Go's extensive 
-<a href="/doc/">documentation</a>.
+For the full story, consult Go's extensive <a href="/doc/">documentation</a>.
+</p>
+
+<p>
+Subscribe to the
+<a href="http://groups.google.com/group/golang-announce">golang-announce</a>
+mailing list to be notified when a new stable version of Go is released.
 </p>
 
 
diff --git a/doc/logo-153x55.png b/doc/logo-153x55.png
index 4a2446ce7..8ec22aa6d 100644
--- a/doc/logo-153x55.png
+++ b/doc/logo-153x55.png
diff --git a/doc/logo.png b/doc/logo.png
deleted file mode 100644
index 076ce398e..000000000
--- a/doc/logo.png
+++ /dev/null
diff --git a/doc/makehtml b/doc/makehtml
deleted file mode 100755
index f6f601e3b..000000000
--- a/doc/makehtml
+++ /dev/null
@@ -1,17 +0,0 @@
-#!/bin/sh
-# 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.
-
-set -e
-
-TMPL=${1:-effective_go.tmpl}                        # input file
-HTML=$(dirname $TMPL)/$(basename $TMPL .tmpl).html # output file
-
-if ! test -w $HTML
-then
-	echo 1>&2 makehtml: cannot open $HTML for write
-	exit 1
-fi
-
-make tmpltohtml && ./tmpltohtml $TMPL > $HTML
diff --git a/doc/play/fib.go b/doc/play/fib.go
new file mode 100644
index 000000000..42da9ce82
--- /dev/null
+++ b/doc/play/fib.go
@@ -0,0 +1,17 @@
+package main
+
+// fib returns a function that returns
+// successive Fibonacci numbers.
+func fib() func() int {
+	a, b := 0, 1
+	return func() int {
+		a, b = b, a+b
+		return a
+	}
+}
+
+func main() {
+	f := fib()
+	// Function calls are evaluated left-to-right.
+	println(f(), f(), f(), f(), f())
+}
diff --git a/doc/play/hello.go b/doc/play/hello.go
new file mode 100644
index 000000000..078ddff8f
--- /dev/null
+++ b/doc/play/hello.go
@@ -0,0 +1,7 @@
+package main
+
+import "fmt"
+
+func main() {
+	fmt.Println("Hello, 世界")
+}
diff --git a/doc/play/peano.go b/doc/play/peano.go
new file mode 100644
index 000000000..c1ee5ad45
--- /dev/null
+++ b/doc/play/peano.go
@@ -0,0 +1,88 @@
+// Peano integers are represented by a linked
+// list whose nodes contain no data
+// (the nodes are the data).
+// http://en.wikipedia.org/wiki/Peano_axioms
+
+// This program demonstrates the power of Go's
+// segmented stacks when doing massively
+// recursive computations.
+
+package main
+
+import "fmt"
+
+// Number is a pointer to a Number
+type Number *Number
+
+// The arithmetic value of a Number is the
+// count of the nodes comprising the list.
+// (See the count function below.)
+
+// -------------------------------------
+// Peano primitives
+
+func zero() *Number {
+	return nil
+}
+
+func isZero(x *Number) bool {
+	return x == nil
+}
+
+func add1(x *Number) *Number {
+	e := new(Number)
+	*e = x
+	return e
+}
+
+func sub1(x *Number) *Number {
+	return *x
+}
+
+func add(x, y *Number) *Number {
+	if isZero(y) {
+		return x
+	}
+	return add(add1(x), sub1(y))
+}
+
+func mul(x, y *Number) *Number {
+	if isZero(x) || isZero(y) {
+		return zero()
+	}
+	return add(mul(x, sub1(y)), x)
+}
+
+func fact(n *Number) *Number {
+	if isZero(n) {
+		return add1(zero())
+	}
+	return mul(fact(sub1(n)), n)
+}
+
+// -------------------------------------
+// Helpers to generate/count Peano integers
+
+func gen(n int) *Number {
+	if n > 0 {
+		return add1(gen(n - 1))
+	}
+	return zero()
+}
+
+func count(x *Number) int {
+	if isZero(x) {
+		return 0
+	}
+	return count(sub1(x)) + 1
+}
+
+// -------------------------------------
+// Print i! for i in [0,9]
+
+func main() {
+	for i := 0; i <= 9; i++ {
+		f := count(fact(gen(i)))
+		fmt.Println(i, "! =", f)
+	}
+}
diff --git a/doc/play/pi.go b/doc/play/pi.go
new file mode 100644
index 000000000..f2f5dca74
--- /dev/null
+++ b/doc/play/pi.go
@@ -0,0 +1,34 @@
+// Concurrent computation of pi.
+// See http://goo.gl/ZuTZM.
+//
+// This demonstrates Go's ability to handle
+// large numbers of concurrent processes.
+// It is an unreasonable way to calculate pi.
+package main
+
+import (
+	"fmt"
+	"math"
+)
+
+func main() {
+	fmt.Println(pi(5000))
+}
+
+// pi launches n goroutines to compute an
+// approximation of pi.
+func pi(n int) float64 {
+	ch := make(chan float64)
+	for k := 0; k <= n; k++ {
+		go term(ch, float64(k))
+	}
+	f := 0.0
+	for k := 0; k <= n; k++ {
+		f += <-ch
+	}
+	return f
+}
+
+func term(ch chan float64, k float64) {
+	ch <- 4 * math.Pow(-1, k) / (2*k + 1)
+}
diff --git a/doc/play/playground.js b/doc/play/playground.js
index e060e203c..947f8a4ec 100644
--- a/doc/play/playground.js
+++ b/doc/play/playground.js
@@ -12,6 +12,7 @@
 // 	preCompile - callback to mutate request data before compiling
 // 	postCompile - callback to read response data after compiling
 //      simple - use plain textarea instead of CodeMirror.
+//      toysEl - select element with a list of toys.
 function playground(opts) {
 	var simple = opts['simple'];
 	var code = $(opts['codeEl']);
@@ -109,6 +110,16 @@ function playground(opts) {
 		}
 		return $(opts['codeEl']).val();
 	}
+	function setBody(text) {
+		if (editor) {
+			editor.setValue(text);
+			return;
+		}
+		$(opts['codeEl']).val(text);
+	}
+	function origin(href) {
+		return (""+href).split("/").slice(0, 3).join("/");
+	}
 
 	var seq = 0;
 	function run() {
@@ -155,52 +166,69 @@ function playground(opts) {
 				}
 				pre.text(out);
 			},
-			error: function() {
-				output.addClass("error").text(
-					"Error communicating with remote server."
-				);
+			error: function(xhr) {
+				var text = "Error communicating with remote server.";
+				console.log(xhr.status);
+				if (xhr.status == 501) {
+					text = xhr.responseText;
+				}
+				output.addClass("error").text(text);
 			}
 		});
 	}
 	$(opts['runEl']).click(run);
 
-	if (opts['shareEl'] == null || (opts['shareURLEl'] == null && opts['shareRedirect'] == null)) {
-		return editor;
-	}
-
-	function origin(href) {
-		return (""+href).split("/").slice(0, 3).join("/");
+	if (opts['shareEl'] != null && (opts['shareURLEl'] != null || opts['shareRedirect'] != null)) {
+		var shareURL;
+		if (opts['shareURLEl']) {
+			shareURL = $(opts['shareURLEl']).hide();
+		}
+		var sharing = false;
+		$(opts['shareEl']).click(function() {
+			if (sharing) return;
+			sharing = true;
+			$.ajax("/share", {
+				processData: false,
+				data: body(),
+				type: "POST",
+				complete: function(xhr) {
+					sharing = false;
+					if (xhr.status == 501) {
+						alert(xhr.responseText);
+						return;
+					}
+					if (xhr.status != 200) {
+						alert("Server error; try again.");
+						return;
+					}
+					if (opts['shareRedirect']) {
+						window.location = opts['shareRedirect'] + xhr.responseText;
+					}
+					if (shareURL) {
+						var url = origin(window.location) + "/p/" + xhr.responseText;
+						shareURL.show().val(url).focus().select();
+					}
+				}
+			});
+		});
 	}
 
-	var shareURL;
-	if (opts['shareURLEl']) {
-		shareURL = $(opts['shareURLEl']).hide();
-	}
-	var sharing = false;
-	$(opts['shareEl']).click(function() {
-		if (sharing) return;
-		sharing = true;
-		$.ajax("/share", {
-			processData: false,
-			data: body(),
-			type: "POST",
-			complete: function(xhr) {
-				sharing = false;
-				if (xhr.status != 200) {
-					alert("Server error; try again.");
-					return;
-				}
-				if (opts['shareRedirect']) {
-					window.location = opts['shareRedirect'] + xhr.responseText;
-				}
-				if (shareURL) {
-					var url = origin(window.location) + "/p/" +
-						xhr.responseText;
-					shareURL.show().val(url).focus().select();
+	if (opts['toysEl'] != null) {
+		$(opts['toysEl']).bind('change', function() {
+			var toy = $(this).val();
+			$.ajax("/doc/play/"+toy, {
+				processData: false,
+				type: "GET",
+				complete: function(xhr) {
+					if (xhr.status != 200) {
+						alert("Server error; try again.")
+						return;
+					}
+					setBody(xhr.responseText);
 				}
-			}
+			});
 		});
-	});
+	}
 
 	return editor;
 }
diff --git a/doc/play/sieve.go b/doc/play/sieve.go
new file mode 100644
index 000000000..585507ac4
--- /dev/null
+++ b/doc/play/sieve.go
@@ -0,0 +1,34 @@
+// A concurrent prime sieve
+
+package main
+
+// Send the sequence 2, 3, 4, ... to channel 'ch'.
+func Generate(ch chan<- int) {
+	for i := 2; ; i++ {
+		ch <- i // Send 'i' to channel 'ch'.
+	}
+}
+
+// Copy the values from channel 'in' to channel 'out',
+// removing those divisible by 'prime'.
+func Filter(in <-chan int, out chan<- int, prime int) {
+	for {
+		i := <-in // Receive value from 'in'.
+		if i%prime != 0 {
+			out <- i // Send 'i' to 'out'.
+		}
+	}
+}
+
+// The prime sieve: Daisy-chain Filter processes.
+func main() {
+	ch := make(chan int) // Create a new channel.
+	go Generate(ch)      // Launch Generate goroutine.
+	for i := 0; i < 10; i++ {
+		prime := <-ch
+		print(prime, "\n")
+		ch1 := make(chan int)
+		go Filter(ch, ch1, prime)
+		ch = ch1
+	}
+}
diff --git a/doc/play/solitaire.go b/doc/play/solitaire.go
new file mode 100644
index 000000000..759d54281
--- /dev/null
+++ b/doc/play/solitaire.go
@@ -0,0 +1,117 @@
+// This program solves the (English) peg
+// solitaire board game.
+// http://en.wikipedia.org/wiki/Peg_solitaire
+
+package main
+
+import "fmt"
+
+const N = 11 + 1 // length of a row (+1 for \n)
+
+// The board must be surrounded by 2 illegal
+// fields in each direction so that move()
+// doesn't need to check the board boundaries.
+// Periods represent illegal fields,
+// ● are pegs, and ○ are holes.
+
+var board = []rune(
+	`...........
+...........
+....●●●....
+....●●●....
+..●●●●●●●..
+..●●●○●●●..
+..●●●●●●●..
+....●●●....
+....●●●....
+...........
+...........
+`)
+
+// center is the position of the center hole if 
+// there is a single one; otherwise it is -1.
+var center int
+
+func init() {
+	n := 0
+	for pos, field := range board {
+		if field == '○' {
+			center = pos
+			n++
+		}
+	}
+	if n != 1 {
+		center = -1 // no single hole
+	}
+}
+
+var moves int // number of times move is called
+
+// move tests if there is a peg at position pos that 
+// can jump over another peg in direction dir. If the
+// move is valid, it is executed and move returns true.
+// Otherwise, move returns false.
+func move(pos, dir int) bool {
+	moves++
+	if board[pos] == '●' && board[pos+dir] == '●' && board[pos+2*dir] == '○' {
+		board[pos] = '○'
+		board[pos+dir] = '○'
+		board[pos+2*dir] = '●'
+		return true
+	}
+	return false
+}
+
+// unmove reverts a previously executed valid move.
+func unmove(pos, dir int) {
+	board[pos] = '●'
+	board[pos+dir] = '●'
+	board[pos+2*dir] = '○'
+}
+
+// solve tries to find a sequence of moves such that 
+// there is only one peg left at the end; if center is 
+// >= 0, that last peg must be in the center position.
+// If a solution is found, solve prints the board after
+// each move in a backward fashion (i.e., the last 
+// board position is printed first, all the way back to
+// the starting board position).
+func solve() bool {
+	var last, n int
+	for pos, field := range board {
+		// try each board position
+		if field == '●' {
+			// found a peg
+			for _, dir := range [...]int{-1, -N, +1, +N} {
+				// try each direction
+				if move(pos, dir) {
+					// a valid move was found and executed,
+					// see if this new board has a solution
+					if solve() {
+						unmove(pos, dir)
+						println(string(board))
+						return true
+					}
+					unmove(pos, dir)
+				}
+			}
+			last = pos
+			n++
+		}
+	}
+	// tried each possible move
+	if n == 1 && (center < 0 || last == center) {
+		// there's only one peg left
+		println(string(board))
+		return true
+	}
+	// no solution found for this board
+	return false
+}
+
+func main() {
+	if !solve() {
+		fmt.Println("no solution found")
+	}
+	fmt.Println(moves, "moves tried")
+}
diff --git a/doc/play/tree.go b/doc/play/tree.go
new file mode 100644
index 000000000..5bcbf05a8
--- /dev/null
+++ b/doc/play/tree.go
@@ -0,0 +1,100 @@
+// Go's concurrency primitives make it easy to
+// express concurrent concepts, such as
+// this binary tree comparison.
+//
+// Trees may be of different shapes, 
+// but have the same contents. For example:
+//
+//        4               6
+//      2   6          4     7
+//     1 3 5 7       2   5
+//                  1 3
+//
+// This program compares a pair of trees by
+// walking each in its own goroutine,
+// sending their contents through a channel
+// to a third goroutine that compares them.
+
+package main
+
+import (
+	"fmt"
+	"math/rand"
+)
+
+// A Tree is a binary tree with integer values.
+type Tree struct {
+	Left  *Tree
+	Value int
+	Right *Tree
+}
+
+// Walk traverses a tree depth-first, 
+// sending each Value on a channel.
+func Walk(t *Tree, ch chan int) {
+	if t == nil {
+		return
+	}
+	Walk(t.Left, ch)
+	ch <- t.Value
+	Walk(t.Right, ch)
+}
+
+// Walker launches Walk in a new goroutine,
+// and returns a read-only channel of values.
+func Walker(t *Tree) <-chan int {
+	ch := make(chan int)
+	go func() {
+		Walk(t, ch)
+		close(ch)
+	}()
+	return ch
+}
+
+// Compare reads values from two Walkers
+// that run simultaneously, and returns true
+// if t1 and t2 have the same contents.
+func Compare(t1, t2 *Tree) bool {
+	c1, c2 := Walker(t1), Walker(t2)
+	for {
+		v1, ok1 := <-c1
+		v2, ok2 := <-c2
+		if !ok1 || !ok2 {
+			return ok1 == ok2
+		}
+		if v1 != v2 {
+			break
+		}
+	}
+	return false
+}
+
+// New returns a new, random binary tree
+// holding the values 1k, 2k, ..., nk.
+func New(n, k int) *Tree {
+	var t *Tree
+	for _, v := range rand.Perm(n) {
+		t = insert(t, (1+v)*k)
+	}
+	return t
+}
+
+func insert(t *Tree, v int) *Tree {
+	if t == nil {
+		return &Tree{nil, v, nil}
+	}
+	if v < t.Value {
+		t.Left = insert(t.Left, v)
+		return t
+	}
+	t.Right = insert(t.Right, v)
+	return t
+}
+
+func main() {
+	t1 := New(100, 1)
+	fmt.Println(Compare(t1, New(100, 1)), "Same Contents")
+	fmt.Println(Compare(t1, New(99, 1)), "Differing Sizes")
+	fmt.Println(Compare(t1, New(100, 2)), "Differing Values")
+	fmt.Println(Compare(t1, New(101, 2)), "Dissimilar")
+}
diff --git a/doc/play_overlay.png b/doc/play_overlay.png
deleted file mode 100644
index 20ef7f399..000000000
--- a/doc/play_overlay.png
+++ /dev/null
diff --git a/doc/playground.html b/doc/playground.html
deleted file mode 100644
index 746b29c86..000000000
--- a/doc/playground.html
+++ /dev/null
@@ -1,29 +0,0 @@
-<!--{
-	"Title": "About the Go Playground"
-}-->
-
-<div class="left-column">
-<p>
-The Go Playground is a web service that runs on 
-<a href="http://golang.org/">golang.org</a>'s servers.
-The service receives a Go program, compiles, links, and runs the program inside 
-a sandbox, then returns the output.
-</p>
-
-<p>
-There are limitations to the programs that can be run in the Playground.
-They must be single-threaded (but they may use many goroutines).
-There are also limits on execution time, and CPU and memory usage.
-The Playground can access only a subset of the standard library
-(notably absent are network and file system access).
-Therefore, the only communication a Playground program has to the outside world
-is via standard output.
-</div>
-
-<div class="right-column">
-<script src="http://www.google.com/jsapi" type="text/javascript"></script>
-<div id="playground" class="small"></div>
-<script src="/doc/play/playground.js"></script>
-</div>
-
-<div class="end-columns"></div>
diff --git a/doc/progs/cgo1.go b/doc/progs/cgo1.go
new file mode 100644
index 000000000..b79ee368a
--- /dev/null
+++ b/doc/progs/cgo1.go
@@ -0,0 +1,21 @@
+// Copyright 2012 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.
+package rand
+
+/*
+#include <stdlib.h>
+*/
+import "C"
+
+// STOP OMIT
+func Random() int {
+	return int(C.random())
+}
+
+// STOP OMIT
+func Seed(i int) {
+	C.srandom(C.uint(i))
+}
+
+// END OMIT
diff --git a/doc/progs/cgo2.go b/doc/progs/cgo2.go
new file mode 100644
index 000000000..f38473b13
--- /dev/null
+++ b/doc/progs/cgo2.go
@@ -0,0 +1,21 @@
+// Copyright 2012 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.
+package rand2
+
+/*
+#include <stdlib.h>
+*/
+import "C"
+
+func Random() int {
+	var r C.long = C.random()
+	return int(r)
+}
+
+// STOP OMIT
+func Seed(i int) {
+	C.srandom(C.uint(i))
+}
+
+// END OMIT
diff --git a/doc/progs/cgo3.go b/doc/progs/cgo3.go
new file mode 100644
index 000000000..435fd0402
--- /dev/null
+++ b/doc/progs/cgo3.go
@@ -0,0 +1,17 @@
+// Copyright 2012 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.
+package print
+
+// #include <stdio.h>
+// #include <stdlib.h>
+import "C"
+import "unsafe"
+
+func Print(s string) {
+	cs := C.CString(s)
+	C.fputs(cs, (*C.FILE)(C.stdout))
+	C.free(unsafe.Pointer(cs))
+}
+
+// END OMIT
diff --git a/doc/progs/cgo4.go b/doc/progs/cgo4.go
new file mode 100644
index 000000000..3808d6217
--- /dev/null
+++ b/doc/progs/cgo4.go
@@ -0,0 +1,17 @@
+// Copyright 2012 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.
+package print
+
+// #include <stdio.h>
+// #include <stdlib.h>
+import "C"
+import "unsafe"
+
+func Print(s string) {
+	cs := C.CString(s)
+	defer C.free(unsafe.Pointer(cs))
+	C.fputs(cs, (*C.FILE)(C.stdout))
+}
+
+// END OMIT
diff --git a/doc/progs/gobs1.go b/doc/progs/gobs1.go
new file mode 100644
index 000000000..7077ca159
--- /dev/null
+++ b/doc/progs/gobs1.go
@@ -0,0 +1,22 @@
+// Copyright 2011 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.
+
+package gobs1
+
+type T struct{ X, Y, Z int } // Only exported fields are encoded and decoded.
+var t = T{X: 7, Y: 0, Z: 8}
+
+// STOP OMIT
+
+type U struct{ X, Y *int8 } // Note: pointers to int8s
+var u U
+
+// STOP OMIT
+
+type Node struct {
+	Value       int
+	Left, Right *Node
+}
+
+// STOP OMIT
diff --git a/doc/progs/gobs2.go b/doc/progs/gobs2.go
new file mode 100644
index 000000000..85bb41cdc
--- /dev/null
+++ b/doc/progs/gobs2.go
@@ -0,0 +1,43 @@
+// Copyright 2011 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.
+
+package main
+
+import (
+	"bytes"
+	"encoding/gob"
+	"fmt"
+	"log"
+)
+
+type P struct {
+	X, Y, Z int
+	Name    string
+}
+
+type Q struct {
+	X, Y *int32
+	Name string
+}
+
+func main() {
+	// Initialize the encoder and decoder.  Normally enc and dec would be
+	// bound to network connections and the encoder and decoder would
+	// run in different processes.
+	var network bytes.Buffer        // Stand-in for a network connection
+	enc := gob.NewEncoder(&network) // Will write to network.
+	dec := gob.NewDecoder(&network) // Will read from network.
+	// Encode (send) the value.
+	err := enc.Encode(P{3, 4, 5, "Pythagoras"})
+	if err != nil {
+		log.Fatal("encode error:", err)
+	}
+	// Decode (receive) the value.
+	var q Q
+	err = dec.Decode(&q)
+	if err != nil {
+		log.Fatal("decode error:", err)
+	}
+	fmt.Printf("%q: {%d,%d}\n", q.Name, *q.X, *q.Y)
+}
diff --git a/doc/progs/helloworld.go b/doc/progs/helloworld.go
deleted file mode 100644
index 8185038d9..000000000
--- a/doc/progs/helloworld.go
+++ /dev/null
@@ -1,11 +0,0 @@
-// 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.
-
-package main
-
-import fmt "fmt" // Package implementing formatted I/O.
-
-func main() {
-	fmt.Printf("Hello, world; or Καλημέρα κόσμε; or こんにちは 世界\n")
-}
diff --git a/doc/progs/helloworld3.go b/doc/progs/helloworld3.go
deleted file mode 100644
index 05d26df1c..000000000
--- a/doc/progs/helloworld3.go
+++ /dev/null
@@ -1,21 +0,0 @@
-// 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.
-
-package main
-
-import (
-	"./file"
-	"fmt"
-	"os"
-)
-
-func main() {
-	hello := []byte("hello, world\n")
-	file.Stdout.Write(hello)
-	f, err := file.Open("/does/not/exist")
-	if f == nil {
-		fmt.Printf("can't open file; err=%s\n", err.Error())
-		os.Exit(1)
-	}
-}
diff --git a/doc/progs/image_draw.go b/doc/progs/image_draw.go
new file mode 100644
index 000000000..f3400b601
--- /dev/null
+++ b/doc/progs/image_draw.go
@@ -0,0 +1,142 @@
+// Copyright 2012 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.
+
+// This file contains the code snippets included in "The Go image/draw package."
+
+package main
+
+import (
+	"image"
+	"image/color"
+	"image/draw"
+)
+
+func main() {
+	Color()
+	Rect()
+	RectAndScroll()
+	ConvAndCircle()
+	Glyph()
+}
+
+func Color() {
+	c := color.RGBA{255, 0, 255, 255}
+	r := image.Rect(0, 0, 640, 480)
+	dst := image.NewRGBA(r)
+
+	// ZERO OMIT
+	// image.ZP is the zero point -- the origin.
+	draw.Draw(dst, r, &image.Uniform{c}, image.ZP, draw.Src)
+	// STOP OMIT
+
+	// BLUE OMIT
+	m := image.NewRGBA(image.Rect(0, 0, 640, 480))
+	blue := color.RGBA{0, 0, 255, 255}
+	draw.Draw(m, m.Bounds(), &image.Uniform{blue}, image.ZP, draw.Src)
+	// STOP OMIT
+
+	// RESET OMIT
+	draw.Draw(m, m.Bounds(), image.Transparent, image.ZP, draw.Src)
+	// STOP OMIT
+}
+
+func Rect() {
+	dst := image.NewRGBA(image.Rect(0, 0, 640, 480))
+	sr := image.Rect(0, 0, 200, 200)
+	src := image.Black
+	dp := image.Point{100, 100}
+
+	// RECT OMIT
+	r := image.Rectangle{dp, dp.Add(sr.Size())}
+	draw.Draw(dst, r, src, sr.Min, draw.Src)
+	// STOP OMIT
+}
+
+func RectAndScroll() {
+	dst := image.NewRGBA(image.Rect(0, 0, 640, 480))
+	sr := image.Rect(0, 0, 200, 200)
+	src := image.Black
+	dp := image.Point{100, 100}
+
+	// RECT2 OMIT
+	r := sr.Sub(sr.Min).Add(dp)
+	draw.Draw(dst, r, src, sr.Min, draw.Src)
+	// STOP OMIT
+
+	m := dst
+
+	// SCROLL OMIT
+	b := m.Bounds()
+	p := image.Pt(0, 20)
+	// Note that even though the second argument is b,
+	// the effective rectangle is smaller due to clipping.
+	draw.Draw(m, b, m, b.Min.Add(p), draw.Src)
+	dirtyRect := b.Intersect(image.Rect(b.Min.X, b.Max.Y-20, b.Max.X, b.Max.Y))
+	// STOP OMIT
+
+	_ = dirtyRect // noop
+}
+
+func ConvAndCircle() {
+	src := image.NewRGBA(image.Rect(0, 0, 640, 480))
+	dst := image.NewRGBA(image.Rect(0, 0, 640, 480))
+
+	// CONV OMIT
+	b := src.Bounds()
+	m := image.NewRGBA(image.Rect(0, 0, b.Dx(), b.Dy()))
+	draw.Draw(m, m.Bounds(), src, b.Min, draw.Src)
+	// STOP OMIT
+
+	p := image.Point{100, 100}
+	r := 50
+
+	// CIRCLE2 OMIT
+	draw.DrawMask(dst, dst.Bounds(), src, image.ZP, &circle{p, r}, image.ZP, draw.Over)
+	// STOP OMIT
+}
+
+func theGlyphImageForAFont() image.Image {
+	return image.NewRGBA(image.Rect(0, 0, 640, 480))
+}
+
+func theBoundsFor(index int) image.Rectangle {
+	return image.Rect(0, 0, 32, 32)
+}
+
+func Glyph() {
+	p := image.Point{100, 100}
+	dst := image.NewRGBA(image.Rect(0, 0, 640, 480))
+	glyphIndex := 42
+
+	// GLYPH OMIT
+	src := &image.Uniform{color.RGBA{0, 0, 255, 255}}
+	mask := theGlyphImageForAFont()
+	mr := theBoundsFor(glyphIndex)
+	draw.DrawMask(dst, mr.Sub(mr.Min).Add(p), src, image.ZP, mask, mr.Min, draw.Over)
+	// STOP OMIT
+}
+
+//CIRCLE OMIT
+type circle struct {
+	p image.Point
+	r int
+}
+
+func (c *circle) ColorModel() color.Model {
+	return color.AlphaModel
+}
+
+func (c *circle) Bounds() image.Rectangle {
+	return image.Rect(c.p.X-c.r, c.p.Y-c.r, c.p.X+c.r, c.p.Y+c.r)
+}
+
+func (c *circle) At(x, y int) color.Color {
+	xx, yy, rr := float64(x-c.p.X)+0.5, float64(y-c.p.Y)+0.5, float64(c.r)
+	if xx*xx+yy*yy < rr*rr {
+		return color.Alpha{255}
+	}
+	return color.Alpha{0}
+}
+
+//STOP
diff --git a/doc/progs/interface.go b/doc/progs/interface.go
index 91145401e..c2925d590 100644
--- a/doc/progs/interface.go
+++ b/doc/progs/interface.go
@@ -1,3 +1,9 @@
+// Copyright 2012 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.
+
+// This file contains the code snippets included in "The Laws of Reflection."
+
 package main
 
 import (
diff --git a/doc/progs/interface2.go b/doc/progs/interface2.go
index e2716cf16..a541d94e4 100644
--- a/doc/progs/interface2.go
+++ b/doc/progs/interface2.go
@@ -1,3 +1,9 @@
+// Copyright 2012 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.
+
+// This file contains the code snippets included in "The Laws of Reflection."
+
 package main
 
 import (
@@ -39,11 +45,14 @@ func f3() {
 	type MyInt int
 	var x MyInt = 7
 	v := reflect.ValueOf(x)
+	// STOP OMIT
 	// START f3b OMIT
 	y := v.Interface().(float64) // y will have type float64.
 	fmt.Println(y)
+	// STOP OMIT
 	// START f3c OMIT
 	fmt.Println(v.Interface())
+	// STOP OMIT
 	// START f3d OMIT
 	fmt.Printf("value is %7.1e\n", v.Interface())
 	// STOP OMIT
@@ -69,6 +78,7 @@ func f6() {
 	// START f6 OMIT
 	var x float64 = 3.4
 	v := reflect.ValueOf(x)
+	// STOP OMIT
 	// START f6b OMIT
 	v.SetFloat(7.1)
 	// STOP OMIT
@@ -80,9 +90,11 @@ func f7() {
 	p := reflect.ValueOf(&x) // Note: take the address of x.
 	fmt.Println("type of p:", p.Type())
 	fmt.Println("settability of p:", p.CanSet())
+	// STOP OMIT
 	// START f7b OMIT
 	v := p.Elem()
 	fmt.Println("settability of v:", v.CanSet())
+	// STOP OMIT
 	// START f7c OMIT
 	v.SetFloat(7.1)
 	fmt.Println(v.Interface())
@@ -104,9 +116,17 @@ func f8() {
 		fmt.Printf("%d: %s %s = %v\n", i,
 			typeOfT.Field(i).Name, f.Type(), f.Interface())
 	}
+	// STOP OMIT
 	// START f8b OMIT
 	s.Field(0).SetInt(77)
 	s.Field(1).SetString("Sunset Strip")
 	fmt.Println("t is now", t)
 	// STOP OMIT
 }
+
+func f9() {
+	// START f9 OMIT
+	var x float64 = 3.4
+	fmt.Println("value:", reflect.ValueOf(x))
+	// STOP OMIT
+}
diff --git a/doc/progs/json1.go b/doc/progs/json1.go
new file mode 100644
index 000000000..9e10f4743
--- /dev/null
+++ b/doc/progs/json1.go
@@ -0,0 +1,88 @@
+// Copyright 2012 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.
+
+package main
+
+import (
+	"encoding/json"
+	"log"
+	"reflect"
+)
+
+type Message struct {
+	Name string
+	Body string
+	Time int64
+}
+
+// STOP OMIT
+
+func Encode() {
+	m := Message{"Alice", "Hello", 1294706395881547000}
+	b, err := json.Marshal(m)
+
+	if err != nil {
+		panic(err)
+	}
+
+	expected := []byte(`{"Name":"Alice","Body":"Hello","Time":1294706395881547000}`)
+	if !reflect.DeepEqual(b, expected) {
+		log.Panicf("Error marshalling %q, expected %q, got %q.", m, expected, b)
+	}
+
+}
+
+func Decode() {
+	b := []byte(`{"Name":"Alice","Body":"Hello","Time":1294706395881547000}`)
+	var m Message
+	err := json.Unmarshal(b, &m)
+
+	if err != nil {
+		panic(err)
+	}
+
+	expected := Message{
+		Name: "Alice",
+		Body: "Hello",
+		Time: 1294706395881547000,
+	}
+
+	if !reflect.DeepEqual(m, expected) {
+		log.Panicf("Error unmarshalling %q, expected %q, got %q.", b, expected, m)
+	}
+
+	m = Message{
+		Name: "Alice",
+		Body: "Hello",
+		Time: 1294706395881547000,
+	}
+
+	// STOP OMIT
+}
+
+func PartialDecode() {
+	b := []byte(`{"Name":"Bob","Food":"Pickle"}`)
+	var m Message
+	err := json.Unmarshal(b, &m)
+
+	// STOP OMIT
+
+	if err != nil {
+		panic(err)
+	}
+
+	expected := Message{
+		Name: "Bob",
+	}
+
+	if !reflect.DeepEqual(expected, m) {
+		log.Panicf("Error unmarshalling %q, expected %q, got %q.", b, expected, m)
+	}
+}
+
+func main() {
+	Encode()
+	Decode()
+	PartialDecode()
+}
diff --git a/doc/progs/json2.go b/doc/progs/json2.go
new file mode 100644
index 000000000..6089ae671
--- /dev/null
+++ b/doc/progs/json2.go
@@ -0,0 +1,42 @@
+// Copyright 2012 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.
+
+package main
+
+import (
+	"fmt"
+	"math"
+)
+
+func InterfaceExample() {
+	var i interface{}
+	i = "a string"
+	i = 2011
+	i = 2.777
+
+	// STOP OMIT
+
+	r := i.(float64)
+	fmt.Println("the circle's area", math.Pi*r*r)
+
+	// STOP OMIT
+
+	switch v := i.(type) {
+	case int:
+		fmt.Println("twice i is", v*2)
+	case float64:
+		fmt.Println("the reciprocal of i is", 1/v)
+	case string:
+		h := len(v) / 2
+		fmt.Println("i swapped by halves is", v[h:]+v[:h])
+	default:
+		// i isn't one of the types above
+	}
+
+	// STOP OMIT
+}
+
+func main() {
+	InterfaceExample()
+}
diff --git a/doc/progs/json3.go b/doc/progs/json3.go
new file mode 100644
index 000000000..a04fdfa50
--- /dev/null
+++ b/doc/progs/json3.go
@@ -0,0 +1,73 @@
+// Copyright 2012 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.
+
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"log"
+	"reflect"
+)
+
+func Decode() {
+	b := []byte(`{"Name":"Wednesday","Age":6,"Parents":["Gomez","Morticia"]}`)
+
+	var f interface{}
+	err := json.Unmarshal(b, &f)
+
+	// STOP OMIT
+
+	if err != nil {
+		panic(err)
+	}
+
+	expected := map[string]interface{}{
+		"Name": "Wednesday",
+		"Age":  float64(6),
+		"Parents": []interface{}{
+			"Gomez",
+			"Morticia",
+		},
+	}
+
+	if !reflect.DeepEqual(f, expected) {
+		log.Panicf("Error unmarshalling %q, expected %q, got %q", b, expected, f)
+	}
+
+	f = map[string]interface{}{
+		"Name": "Wednesday",
+		"Age":  6,
+		"Parents": []interface{}{
+			"Gomez",
+			"Morticia",
+		},
+	}
+
+	// STOP OMIT
+
+	m := f.(map[string]interface{})
+
+	for k, v := range m {
+		switch vv := v.(type) {
+		case string:
+			fmt.Println(k, "is string", vv)
+		case int:
+			fmt.Println(k, "is int", vv)
+		case []interface{}:
+			fmt.Println(k, "is an array:")
+			for i, u := range vv {
+				fmt.Println(i, u)
+			}
+		default:
+			fmt.Println(k, "is of a type I don't know how to handle")
+		}
+	}
+
+	// STOP OMIT
+}
+
+func main() {
+	Decode()
+}
diff --git a/doc/progs/json4.go b/doc/progs/json4.go
new file mode 100644
index 000000000..492630220
--- /dev/null
+++ b/doc/progs/json4.go
@@ -0,0 +1,45 @@
+// Copyright 2012 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.
+
+package main
+
+import (
+	"encoding/json"
+	"log"
+	"reflect"
+)
+
+type FamilyMember struct {
+	Name    string
+	Age     int
+	Parents []string
+}
+
+// STOP OMIT
+
+func Decode() {
+	b := []byte(`{"Name":"Bob","Age":20,"Parents":["Morticia", "Gomez"]}`)
+	var m FamilyMember
+	err := json.Unmarshal(b, &m)
+
+	// STOP OMIT
+
+	if err != nil {
+		panic(err)
+	}
+
+	expected := FamilyMember{
+		Name:    "Bob",
+		Age:     20,
+		Parents: []string{"Morticia", "Gomez"},
+	}
+
+	if !reflect.DeepEqual(expected, m) {
+		log.Panicf("Error unmarshalling %q, expected %q, got %q", b, expected, m)
+	}
+}
+
+func main() {
+	Decode()
+}
diff --git a/doc/progs/json5.go b/doc/progs/json5.go
new file mode 100644
index 000000000..6d7a4ca8c
--- /dev/null
+++ b/doc/progs/json5.go
@@ -0,0 +1,31 @@
+// Copyright 2012 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.
+
+package main
+
+import (
+	"encoding/json"
+	"log"
+	"os"
+)
+
+func main() {
+	dec := json.NewDecoder(os.Stdin)
+	enc := json.NewEncoder(os.Stdout)
+	for {
+		var v map[string]interface{}
+		if err := dec.Decode(&v); err != nil {
+			log.Println(err)
+			return
+		}
+		for k := range v {
+			if k != "Name" {
+				delete(v, k)
+			}
+		}
+		if err := enc.Encode(&v); err != nil {
+			log.Println(err)
+		}
+	}
+}
diff --git a/doc/progs/print.go b/doc/progs/print.go
deleted file mode 100644
index 8f44ba8c6..000000000
--- a/doc/progs/print.go
+++ /dev/null
@@ -1,23 +0,0 @@
-// 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.
-
-package main
-
-import "fmt"
-
-func main() {
-	var u64 uint64 = 1<<64 - 1
-	fmt.Printf("%d %d\n", u64, int64(u64))
-
-	// harder stuff
-	type T struct {
-		a int
-		b string
-	}
-	t := T{77, "Sunset Strip"}
-	a := []int{1, 2, 3, 4}
-	fmt.Printf("%v %v %v\n", u64, t, a)
-	fmt.Print(u64, " ", t, " ", a, "\n")
-	fmt.Println(u64, t, a)
-}
diff --git a/doc/progs/print_string.go b/doc/progs/print_string.go
deleted file mode 100644
index 46ab1d91a..000000000
--- a/doc/progs/print_string.go
+++ /dev/null
@@ -1,21 +0,0 @@
-// 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.
-
-package main
-
-import "fmt"
-
-type testType struct {
-	a int
-	b string
-}
-
-func (t *testType) String() string {
-	return fmt.Sprint(t.a) + " " + t.b
-}
-
-func main() {
-	t := &testType{77, "Sunset Strip"}
-	fmt.Println(t)
-}
diff --git a/doc/progs/run b/doc/progs/run
index e3d5c128c..8348a33e5 100755
--- a/doc/progs/run
+++ b/doc/progs/run
@@ -5,6 +5,8 @@
 
 set -e
 
+goos=$(go env GOOS)
+
 defer_panic_recover="
 	defer
 	defer2
@@ -23,14 +25,48 @@ error_handling="
 	error4
 "
 
-all=$(echo $defer_panic_recover  $effective_go $error_handling slices go1)
+law_of_reflection="
+	interface
+	interface2
+"
+
+c_go_cgo="
+	cgo1
+	cgo2
+	cgo3
+	cgo4
+"
+# cgo1 and cgo2 don't run on freebsd, srandom has a different signature
+if [ "$goos" == "freebsd" ]; then
+	c_go_cgo="cgo3 cgo4"
+fi
+
+timeout="
+	timeout1
+	timeout2
+"
+
+gobs="
+	gobs1
+	gobs2
+"
+
+json="
+	json1
+	json2
+	json3
+	json4
+	json5
+"
+
+all=$(echo $defer_panic_recover $effective_go $error_handling $law_of_reflection $c_go_cgo $timeout $gobs $json slices go1)
 
 for i in $all; do
 	go build $i.go
 done
 
 # Write to temporary file to avoid mingw bash bug.
-TMPFILE="/tmp/gotest3.$USER"
+TMPFILE="${TMPDIR:-/tmp}/gotest3.$USER"
 
 function testit {
 	./$1 >"$TMPFILE" 2>&1 || true
@@ -50,4 +86,10 @@ testit eff_sequence '^\[-1 2 6 16 44\]$'
 
 testit go1 '^Christmas is a holiday: true Sleeping for 0.123s.*go1.go already exists$'
 
+testit interface2 "^type: float64$"
+testit json1 "^$"
+testit json2 "the reciprocal of i is"
+testit json3 "Age is int 6"
+testit json4 "^$"
+
 rm -f $all "$TMPFILE"
diff --git a/doc/progs/server.go b/doc/progs/server.go
deleted file mode 100644
index 4d8409b80..000000000
--- a/doc/progs/server.go
+++ /dev/null
@@ -1,51 +0,0 @@
-// 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.
-
-package main
-
-import "fmt"
-
-type request struct {
-	a, b   int
-	replyc chan int
-}
-
-type binOp func(a, b int) int
-
-func run(op binOp, req *request) {
-	reply := op(req.a, req.b)
-	req.replyc <- reply
-}
-
-func server(op binOp, service <-chan *request) {
-	for {
-		req := <-service
-		go run(op, req) // don't wait for it
-	}
-}
-
-func startServer(op binOp) chan<- *request {
-	req := make(chan *request)
-	go server(op, req)
-	return req
-}
-
-func main() {
-	adder := startServer(func(a, b int) int { return a + b })
-	const N = 100
-	var reqs [N]request
-	for i := 0; i < N; i++ {
-		req := &reqs[i]
-		req.a = i
-		req.b = i + N
-		req.replyc = make(chan int)
-		adder <- req
-	}
-	for i := N - 1; i >= 0; i-- { // doesn't matter what order
-		if <-reqs[i].replyc != N+2*i {
-			fmt.Println("fail at", i)
-		}
-	}
-	fmt.Println("done")
-}
diff --git a/doc/progs/server1.go b/doc/progs/server1.go
deleted file mode 100644
index 39e3dde5d..000000000
--- a/doc/progs/server1.go
+++ /dev/null
@@ -1,56 +0,0 @@
-// 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.
-
-package main
-
-import "fmt"
-
-type request struct {
-	a, b   int
-	replyc chan int
-}
-
-type binOp func(a, b int) int
-
-func run(op binOp, req *request) {
-	reply := op(req.a, req.b)
-	req.replyc <- reply
-}
-
-func server(op binOp, service <-chan *request, quit <-chan bool) {
-	for {
-		select {
-		case req := <-service:
-			go run(op, req) // don't wait for it
-		case <-quit:
-			return
-		}
-	}
-}
-
-func startServer(op binOp) (service chan *request, quit chan bool) {
-	service = make(chan *request)
-	quit = make(chan bool)
-	go server(op, service, quit)
-	return service, quit
-}
-
-func main() {
-	adder, quit := startServer(func(a, b int) int { return a + b })
-	const N = 100
-	var reqs [N]request
-	for i := 0; i < N; i++ {
-		req := &reqs[i]
-		req.a = i
-		req.b = i + N
-		req.replyc = make(chan int)
-		adder <- req
-	}
-	for i := N - 1; i >= 0; i-- { // doesn't matter what order
-		if <-reqs[i].replyc != N+2*i {
-			fmt.Println("fail at", i)
-		}
-	}
-	quit <- true
-}
diff --git a/doc/progs/sort.go b/doc/progs/sort.go
deleted file mode 100644
index 894693f0d..000000000
--- a/doc/progs/sort.go
+++ /dev/null
@@ -1,59 +0,0 @@
-// 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.
-
-package sort
-
-type Interface interface {
-	Len() int
-	Less(i, j int) bool
-	Swap(i, j int)
-}
-
-func Sort(data Interface) {
-	for i := 1; i < data.Len(); i++ {
-		for j := i; j > 0 && data.Less(j, j-1); j-- {
-			data.Swap(j, j-1)
-		}
-	}
-}
-
-func IsSorted(data Interface) bool {
-	n := data.Len()
-	for i := n - 1; i > 0; i-- {
-		if data.Less(i, i-1) {
-			return false
-		}
-	}
-	return true
-}
-
-// Convenience types for common cases
-
-type IntSlice []int
-
-func (p IntSlice) Len() int           { return len(p) }
-func (p IntSlice) Less(i, j int) bool { return p[i] < p[j] }
-func (p IntSlice) Swap(i, j int)      { p[i], p[j] = p[j], p[i] }
-
-type Float64Slice []float64
-
-func (p Float64Slice) Len() int           { return len(p) }
-func (p Float64Slice) Less(i, j int) bool { return p[i] < p[j] }
-func (p Float64Slice) Swap(i, j int)      { p[i], p[j] = p[j], p[i] }
-
-type StringSlice []string
-
-func (p StringSlice) Len() int           { return len(p) }
-func (p StringSlice) Less(i, j int) bool { return p[i] < p[j] }
-func (p StringSlice) Swap(i, j int)      { p[i], p[j] = p[j], p[i] }
-
-// Convenience wrappers for common cases
-
-func SortInts(a []int)         { Sort(IntSlice(a)) }
-func SortFloat64s(a []float64) { Sort(Float64Slice(a)) }
-func SortStrings(a []string)   { Sort(StringSlice(a)) }
-
-func IntsAreSorted(a []int) bool         { return IsSorted(IntSlice(a)) }
-func Float64sAreSorted(a []float64) bool { return IsSorted(Float64Slice(a)) }
-func StringsAreSorted(a []string) bool   { return IsSorted(StringSlice(a)) }
diff --git a/doc/progs/strings.go b/doc/progs/strings.go
deleted file mode 100644
index e6739b385..000000000
--- a/doc/progs/strings.go
+++ /dev/null
@@ -1,17 +0,0 @@
-// 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.
-
-package main
-
-import "os"
-
-func main() {
-	s := "hello"
-	if s[1] != 'e' {
-		os.Exit(1)
-	}
-	s = "good bye"
-	var p *string = &s
-	*p = "ciao"
-}
diff --git a/doc/progs/sum.go b/doc/progs/sum.go
deleted file mode 100644
index 0f316bc01..000000000
--- a/doc/progs/sum.go
+++ /dev/null
@@ -1,21 +0,0 @@
-// 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.
-
-package main
-
-import "fmt"
-
-func sum(a []int) int { // returns an int
-	s := 0
-	for i := 0; i < len(a); i++ {
-		s += a[i]
-	}
-	return s
-}
-
-func main() {
-	x := [3]int{1, 2, 3}
-	s := sum(x[:]) // a slice of the array is passed to sum
-	fmt.Print(s, "\n")
-}
diff --git a/doc/progs/timeout1.go b/doc/progs/timeout1.go
new file mode 100644
index 000000000..5221770ec
--- /dev/null
+++ b/doc/progs/timeout1.go
@@ -0,0 +1,28 @@
+// Copyright 2012 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.
+package timeout
+
+import (
+	"time"
+)
+
+func Timeout() {
+	ch := make(chan bool, 1)
+	timeout := make(chan bool, 1)
+	go func() {
+		time.Sleep(1 * time.Second)
+		timeout <- true
+	}()
+
+	// STOP OMIT
+
+	select {
+	case <-ch:
+		// a read from ch has occurred
+	case <-timeout:
+		// the read from ch has timed out
+	}
+
+	// STOP OMIT
+}
diff --git a/doc/progs/timeout2.go b/doc/progs/timeout2.go
new file mode 100644
index 000000000..7145bc93e
--- /dev/null
+++ b/doc/progs/timeout2.go
@@ -0,0 +1,27 @@
+// Copyright 2012 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.
+package query
+
+type Conn string
+
+func (c Conn) DoQuery(query string) Result {
+	return Result("result")
+}
+
+type Result string
+
+func Query(conns []Conn, query string) Result {
+	ch := make(chan Result, 1)
+	for _, conn := range conns {
+		go func(c Conn) {
+			select {
+			case ch <- c.DoQuery(query):
+			default:
+			}
+		}(conn)
+	}
+	return <-ch
+}
+
+// STOP OMIT
diff --git a/doc/reference.html b/doc/reference.html
index 12a6ef96d..0eddc2352 100644
--- a/doc/reference.html
+++ b/doc/reference.html
@@ -1,9 +1,9 @@
 <!--{
 	"Title": "References",
-	"Path":  "/ref/"
+    "Path":  "/ref/"
 }-->
 
-<img src="/doc/gopher/ref.png" align="right"/>
+<img class="gopher" src="/doc/gopher/ref.png" />
 
 <p>Good bedtime reading.</p>
 
@@ -42,18 +42,34 @@ same variable in a different goroutine.
 Using GDB to debug Go programs.
 </p>
 
-<h3 id="articles">Articles</h2>
+<h4 id="subrepos">Sub-repositories</h4>
+
+<p>
+These packages are part of the Go Project but outside the main Go tree.
+They are developed under looser <a href="/doc/go1compat.html">compatibility
+requirements</a> than the Go core.
+Install them with "<code><a href="/cmd/go/#Download_and_install_packages_and_dependencies">go get</a></code>".
+</p>
+
+<ul>
+<li><a href="http://code.google.com/p/go/source/browse?repo=codereview"><code>code.google.com/p/go.codereview</code></a> [<a href="http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.codereview">docs</a>]
+<li><a href="http://code.google.com/p/go/source/browse?repo=crypto"><code>code.google.com/p/go.crypto</code></a> [<a href="http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.crypto">docs</a>]
+<li><a href="http://code.google.com/p/go/source/browse?repo=image"><code>code.google.com/p/go.image</code></a> [<a href="http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.image">docs</a>]
+<li><a href="http://code.google.com/p/go/source/browse?repo=net"><code>code.google.com/p/go.net</code></a> [<a href="http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.net">docs</a>]
+</ul>
+
+<h4 id="articles">Articles</h4>
 
 <ul>
-<li><a href="http://blog.golang.org/2011/03/c-go-cgo.html">C? Go? Cgo!</a> - linking against C code with <a href="/cmd/cgo/">cgo</a>.</li>
+<li><a href="/doc/articles/c_go_cgo.html">C? Go? Cgo!</a> - linking against C code with <a href="/cmd/cgo/">cgo</a>.</li>
 <li><a href="/doc/articles/defer_panic_recover.html">Defer, Panic, and Recover</a></li>
 <li><a href="/doc/articles/slices_usage_and_internals.html">Go Slices: usage and internals</a></li>
-<li><a href="http://blog.golang.org/2011/03/godoc-documenting-go-code.html">Godoc: documenting Go code</a> - writing good documentation for <a href="/cmd/godoc/">godoc</a>.</li>
+<li><a href="/doc/articles/godoc_documenting_go_code.html">Godoc: documenting Go code</a> - writing good documentation for <a href="/cmd/godoc/">godoc</a>.</li>
 <li><a href="http://blog.golang.org/2011/06/profiling-go-programs.html">Profiling Go Programs</a></li>
 </ul>
 
 <p>
-See the <a href=/doc/#articles">documentation page</a> for more articles.
+See the <a href="/doc/#articles">documentation page</a> for more articles.
 </p>
 
 </div>
diff --git a/doc/root.html b/doc/root.html
index 2029d4c6d..3b92229cb 100644
--- a/doc/root.html
+++ b/doc/root.html
@@ -5,9 +5,10 @@
 <div class="left">
 
 <div id="learn">
+<img class="icon share" src="/doc/share.png" alt="View full screen" title="View full screen">
 <div class="rootHeading">Try Go</div>
 <div class="input">
-<textarea spellcheck="false" id="code">// You can edit this code!
+<textarea spellcheck="false" class="code">// You can edit this code!
 // Click here and start typing.
 package main
 
@@ -17,14 +18,26 @@ func main() {
 	fmt.Println("Hello, 世界")
 }</textarea>
 </div>
-<div class="output" id="output">
+<div class="output">
 <pre>
 Hello, 世界
 </pre>
 </div>
 <div class="buttons">
-<a id="run" href="#">Run</a>
-<a id="share" href="#">Share</a>
+<a class="run" href="#" title="Run this code [shift-enter]">Run</a>
+<a class="share" href="#" title="Share this code">Share</a>
+<a class="tour" href="http://tour.golang.org/" title="Learn Go from your browser">Tour</a>
+</div>
+<div class="toys">
+<select>
+	<option value="hello.go">Hello, World!</option>
+	<option value="fib.go">Fibonacci Closure</option>
+	<option value="peano.go">Peano Integers</option>
+	<option value="pi.go">Concurrent pi</option>
+	<option value="sieve.go">Concurrent Prime Sieve</option>
+	<option value="solitaire.go">Peg Solitaire Solver</option>
+	<option value="tree.go">Tree Comparison</option>
+</select>
 </div>
 </div>
 
@@ -39,7 +52,7 @@ simple, reliable, and efficient software.
 
 <div id="gopher"></div>
 
-<a href="/install/" id="start">
+<a href="/doc/install" id="start">
 <div class="big">Download Go</div>
 <div class="desc">
 Binary distributions available for<br>
@@ -72,8 +85,6 @@ Linux, Mac OS X, Windows, and more.
 
 <div style="clear: both;"></div>
 
-<div id="plusoneRoot"><g:plusone annotation="none"></g:plusone></div>
-
 <script type="text/javascript" src="https://www.google.com/jsapi"></script>
 <script type="text/javascript" src="/doc/play/playground.js"></script>
 <script type="text/javascript">
@@ -114,11 +125,12 @@ function init() {
 	// Set up playground.
 	playground({
 		"simple":        true,
-		"codeEl":        "#code",
-		"outputEl":      "#output",
-		"runEl":         "#run",
-		"shareEl":       "#share",
-		"shareRedirect": "http://play.golang.org/p/"
+		"codeEl":        "#learn .code",
+		"outputEl":      "#learn .output",
+		"runEl":         "#learn .run",
+		"shareEl":       "#learn .share",
+		"shareRedirect": "http://play.golang.org/p/",
+		"toysEl":        "#learn .toys select"
 	});
 }
 
diff --git a/doc/share.png b/doc/share.png
new file mode 100644
index 000000000..c04f0c71a
--- /dev/null
+++ b/doc/share.png
diff --git a/doc/style.css b/doc/style.css
index b180a615d..53f5e18cd 100644
--- a/doc/style.css
+++ b/doc/style.css
@@ -18,11 +18,11 @@ pre .highlight,
 pre .highlight-comment,
 pre .selection-highlight,
 pre .selection-highlight-comment {
-    background: #FFFF00;
+	background: #FFFF00;
 }
 pre .selection,
 pre .selection-comment {
-    background: #FF9632;
+	background: #FF9632;
 }
 pre .ln {
 	color: #999;
@@ -30,10 +30,15 @@ pre .ln {
 body {
 	color: #222;
 }
-a {
+a,
+.exampleHeading .text {
 	color: #375EAB;
 	text-decoration: none;
 }
+a:hover,
+.exampleHeading .text:hover {
+	text-decoration: underline;
+}
 p,
 pre,
 ul,
@@ -68,7 +73,7 @@ h2 {
 	padding: 2px 5px;
 }
 h3 {
-	font-size: 18px;
+	font-size: 20px;
 }
 h3,
 h4 {
@@ -82,13 +87,6 @@ h4 {
 	margin: 0;
 }
 
-h1 a,
-h2 a,
-h3 a,
-h4 a {
-	text-decoration: underline;
-}
-
 dl {
 	margin: 20px;
 }
@@ -129,23 +127,26 @@ div#heading a {
 
 div#topbar {
 	background: #E0EBF5;
+	height: 64px;
 }
 
 body {
 	text-align: center;
 }
 div#page,
-div#topbar .container {
+div#topbar > .container {
 	clear: both;
 	text-align: left;
 	margin-left: auto;
 	margin-right: auto;
+	padding: 0 20px;
 	width: 900px;
 }
-div#plusone {
-	float: right;
+div#page.wide,
+div#topbar > .wide {
+	width: auto;
 }
-div#plusoneRoot {
+div#plusone {
 	float: right;
 }
 
@@ -185,6 +186,8 @@ div#blog .read a {
 }
 
 div#menu {
+	float: right;
+	min-width: 590px;
 	padding: 10px 0;
 	text-align: right;
 }
@@ -257,6 +260,10 @@ a#start .desc {
 	margin-top: 5px;
 }
 
+div#learn .icon {
+	float: right;
+	cursor: pointer;
+}
 div#learn pre,
 div#learn textarea {
 	padding: 0;
@@ -315,21 +322,21 @@ div#learn .output {
 	border: 1px solid #375EAB;
 }
 div#learn .buttons {
+	float: right;
 	padding: 20px 0 10px 0;
 	text-align: right;
 }
 div#learn .buttons a {
 	height: 16px;
 	margin-left: 5px;
-
 	padding: 10px;
 }
-div#learn .buttons .tour {
-	float: right;
+div#learn .toys {
+	margin-top: 8px;
 }
-div#learn .buttons .tour a {
-	margin-right: 0;
-	font-weight: bold;
+div#learn .toys select {
+	border: 1px solid #375EAB;
+	margin: 0;
 }
 
 div#blog,
@@ -346,8 +353,6 @@ div#video > h2 {
 }
 div#blog .title,
 div#video .title {
-	color: #222;
-	text-decoration: none;
 	display: block;
 	font-size: 20px;
 }
@@ -367,3 +372,20 @@ div#blog .read {
 
 table.codetable { margin-left: auto; margin-right: auto; border-style: none; }
 hr { border-style: none; border-top: 1px solid black; }
+
+img.gopher {
+	float: right;
+	margin-left: 10px;
+	margin-bottom: 10px;
+}
+.pkgGopher {
+	text-align: right;
+}
+.pkgGopher .gopher {
+	float: none;
+	position: relative;
+	top: -40px;
+	margin-bottom: -120px;
+}
+h2 { clear: right; }
+
diff --git a/doc/tmpltohtml.go b/doc/tmpltohtml.go
deleted file mode 100644
index 70745f4dd..000000000
--- a/doc/tmpltohtml.go
+++ /dev/null
@@ -1,199 +0,0 @@
-// Copyright 2011 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 template uses the function "code" to inject program
-// source into the output by extracting code from files and
-// injecting them as HTML-escaped <pre> blocks.
-//
-// The syntax is simple: 1, 2, or 3 space-separated arguments:
-//
-// Whole file:
-//	{{code "foo.go"}}
-// One line (here the signature of main):
-//	{{code "foo.go" `/^func.main/`}}
-// Block of text, determined by start and end (here the body of main):
-//	{{code "foo.go" `/^func.main/` `/^}/`
-//
-// Patterns can be `/regular expression/`, a decimal number, or "$"
-// to signify the end of the file. In multi-line matches,
-// lines that end with the four characters
-//	OMIT
-// are omitted from the output, making it easy to provide marker
-// lines in the input that will not appear in the output but are easy
-// to identify by pattern.
-
-package main
-
-import (
-	"flag"
-	"fmt"
-	"io/ioutil"
-	"log"
-	"os"
-	"path/filepath"
-	"regexp"
-	"strings"
-	"text/template"
-)
-
-func Usage() {
-	fmt.Fprintf(os.Stderr, "usage: tmpltohtml file\n")
-	os.Exit(2)
-}
-
-var templateFuncs = template.FuncMap{
-	"code":      code,
-	"donotedit": donotedit,
-}
-
-func main() {
-	flag.Usage = Usage
-	flag.Parse()
-	if len(flag.Args()) != 1 {
-		Usage()
-	}
-
-	// Read and parse the input.
-	name := flag.Arg(0)
-	tmpl := template.New(filepath.Base(name)).Funcs(templateFuncs)
-	if _, err := tmpl.ParseFiles(name); err != nil {
-		log.Fatal(err)
-	}
-
-	// Execute the template.
-	if err := tmpl.Execute(os.Stdout, 0); err != nil {
-		log.Fatal(err)
-	}
-}
-
-// contents reads a file by name and returns its contents as a string.
-func contents(name string) string {
-	file, err := ioutil.ReadFile(name)
-	if err != nil {
-		log.Fatal(err)
-	}
-	return string(file)
-}
-
-// format returns a textual representation of the arg, formatted according to its nature.
-func format(arg interface{}) string {
-	switch arg := arg.(type) {
-	case int:
-		return fmt.Sprintf("%d", arg)
-	case string:
-		if len(arg) > 2 && arg[0] == '/' && arg[len(arg)-1] == '/' {
-			return fmt.Sprintf("%#q", arg)
-		}
-		return fmt.Sprintf("%q", arg)
-	default:
-		log.Fatalf("unrecognized argument: %v type %T", arg, arg)
-	}
-	return ""
-}
-
-func donotedit() string {
-	// No editing please.
-	return fmt.Sprintf("<!--\n  DO NOT EDIT: created by\n    tmpltohtml %s\n-->\n", flag.Args()[0])
-}
-
-func code(file string, arg ...interface{}) (string, error) {
-	text := contents(file)
-	var command string
-	switch len(arg) {
-	case 0:
-		// text is already whole file.
-		command = fmt.Sprintf("code %q", file)
-	case 1:
-		command = fmt.Sprintf("code %q %s", file, format(arg[0]))
-		text = oneLine(file, text, arg[0])
-	case 2:
-		command = fmt.Sprintf("code %q %s %s", file, format(arg[0]), format(arg[1]))
-		text = multipleLines(file, text, arg[0], arg[1])
-	default:
-		return "", fmt.Errorf("incorrect code invocation: code %q %q", file, arg)
-	}
-	// Trim spaces from output.
-	text = strings.Trim(text, "\n")
-	// Replace tabs by spaces, which work better in HTML.
-	text = strings.Replace(text, "\t", "    ", -1)
-	// Escape the program text for HTML.
-	text = template.HTMLEscapeString(text)
-	// Include the command as a comment.
-	text = fmt.Sprintf("<pre><!--{{%s}}\n-->%s</pre>", command, text)
-	return text, nil
-}
-
-// parseArg returns the integer or string value of the argument and tells which it is.
-func parseArg(arg interface{}, file string, max int) (ival int, sval string, isInt bool) {
-	switch n := arg.(type) {
-	case int:
-		if n <= 0 || n > max {
-			log.Fatalf("%q:%d is out of range", file, n)
-		}
-		return n, "", true
-	case string:
-		return 0, n, false
-	}
-	log.Fatalf("unrecognized argument %v type %T", arg, arg)
-	return
-}
-
-// oneLine returns the single line generated by a two-argument code invocation.
-func oneLine(file, text string, arg interface{}) string {
-	lines := strings.SplitAfter(contents(file), "\n")
-	line, pattern, isInt := parseArg(arg, file, len(lines))
-	if isInt {
-		return lines[line-1]
-	}
-	return lines[match(file, 0, lines, pattern)-1]
-}
-
-// multipleLines returns the text generated by a three-argument code invocation.
-func multipleLines(file, text string, arg1, arg2 interface{}) string {
-	lines := strings.SplitAfter(contents(file), "\n")
-	line1, pattern1, isInt1 := parseArg(arg1, file, len(lines))
-	line2, pattern2, isInt2 := parseArg(arg2, file, len(lines))
-	if !isInt1 {
-		line1 = match(file, 0, lines, pattern1)
-	}
-	if !isInt2 {
-		line2 = match(file, line1, lines, pattern2)
-	} else if line2 < line1 {
-		log.Fatalf("lines out of order for %q: %d %d", text, line1, line2)
-	}
-	for k := line1 - 1; k < line2; k++ {
-		if strings.HasSuffix(lines[k], "OMIT\n") {
-			lines[k] = ""
-		}
-	}
-	return strings.Join(lines[line1-1:line2], "")
-}
-
-// match identifies the input line that matches the pattern in a code invocation.
-// If start>0, match lines starting there rather than at the beginning.
-// The return value is 1-indexed.
-func match(file string, start int, lines []string, pattern string) int {
-	// $ matches the end of the file.
-	if pattern == "$" {
-		if len(lines) == 0 {
-			log.Fatalf("%q: empty file", file)
-		}
-		return len(lines)
-	}
-	// /regexp/ matches the line that matches the regexp.
-	if len(pattern) > 2 && pattern[0] == '/' && pattern[len(pattern)-1] == '/' {
-		re, err := regexp.Compile(pattern[1 : len(pattern)-1])
-		if err != nil {
-			log.Fatal(err)
-		}
-		for i := start; i < len(lines); i++ {
-			if re.MatchString(lines[i]) {
-				return i + 1
-			}
-		}
-		log.Fatalf("%s: no match for %#q", file, pattern)
-	}
-	log.Fatalf("unrecognized pattern: %q", pattern)
-	return 0
-}
diff --git a/doc/video-001.png b/doc/video-001.png
deleted file mode 100644
index d3468bbe8..000000000
--- a/doc/video-001.png
+++ /dev/null
diff --git a/doc/video-002.png b/doc/video-002.png
deleted file mode 100644
index 4f7c5d184..000000000
--- a/doc/video-002.png
+++ /dev/null
diff --git a/doc/video-003.png b/doc/video-003.png
deleted file mode 100644
index 3dff68602..000000000
--- a/doc/video-003.png
+++ /dev/null
diff --git a/doc/video-004.png b/doc/video-004.png
deleted file mode 100644
index 92144549a..000000000
--- a/doc/video-004.png
+++ /dev/null
diff --git a/doc/video-005.jpg b/doc/video-005.jpg
deleted file mode 100644
index 32371581f..000000000
--- a/doc/video-005.jpg
+++ /dev/null