diff --git a/doc/go_tutorial.html b/doc/go_tutorial.html index 4f3f6b94b34..822f9626ee7 100644 --- a/doc/go_tutorial.html +++ b/doc/go_tutorial.html @@ -26,14 +26,14 @@ cleanliness, blank lines remain blank.

Let's start in the usual way:

-

 
-05    package main
+
package main
 
-07    import fmt "fmt"  // Package implementing formatted I/O.
+import fmt "fmt"  // Package implementing formatted I/O.
 
-09    func main() {
-10        fmt.Printf("Hello, world; or Καλημέρα κόσμε; or こんにちは 世界\n")
-11    }
+func main() {
+    fmt.Printf("Hello, world; or Καλημέρα κόσμε; or こんにちは 世界\n")
+}
 

 

 Every Go source file declares, using a package statement, which package it's part of.
@@ -51,8 +51,8 @@ String constants can contain Unicode characters, encoded in UTF-8.
 The comment convention is the same as in C++:
 

 
-    /* ... */
-    // ...
+/* ... */
+// ...
 

 

 Later we'll have much more to say about printing.
@@ -96,67 +96,67 @@ a more robust run-time system although gccgo is catching up.
 Here's how to compile and run our program.  With 6g, say,
 

 
-    $ 6g helloworld.go  # compile; object goes into helloworld.6
-    $ 6l helloworld.6   # link; output goes into 6.out
-    $ 6.out
-    Hello, world; or Καλημέρα κόσμε; or こんにちは 世界
-    $
+$ 6g helloworld.go  # compile; object goes into helloworld.6
+$ 6l helloworld.6   # link; output goes into 6.out
+$ 6.out
+Hello, world; or Καλημέρα κόσμε; or こんにちは 世界
+$
 

 

 With gccgo it looks a little more traditional.
 

 
-    $ gccgo helloworld.go
-    $ a.out
-    Hello, world; or Καλημέρα κόσμε; or こんにちは 世界
-    $
+$ gccgo helloworld.go
+$ a.out
+Hello, world; or Καλημέρα κόσμε; or こんにちは 世界
+$
 

 

 
Echo

 

 Next up, here's a version of the Unix utility echo(1):
 

-
 
-05    package main
+
package main
 
-07    import (
-08        "os"
-09        "flag"  // command line option parser
-10    )
+import (
+    "os"
+    "flag"  // command line option parser
+)
 
-12    var omitNewline = flag.Bool("n", false, "don't print final newline")
+var omitNewline = flag.Bool("n", false, "don't print final newline")
 
-14    const (
-15        Space = " "
-16        Newline = "\n"
-17    )
+const (
+    Space = " "
+    Newline = "\n"
+)
 
-19    func main() {
-20        flag.Parse()   // Scans the arg list and sets up flags
-21        var s string = ""
-22        for i := 0; i < flag.NArg(); i++ {
-23            if i > 0 {
-24                s += Space
-25            }
-26            s += flag.Arg(i)
-27        }
-28        if !*omitNewline {
-29            s += Newline
-30        }
-31        os.Stdout.WriteString(s)
-32    }
+func main() {
+    flag.Parse()   // Scans the arg list and sets up flags
+    var s string = ""
+    for i := 0; i < flag.NArg(); i++ {
+        if i > 0 {
+            s += Space
+        }
+        s += flag.Arg(i)
+    }
+    if !*omitNewline {
+        s += Newline
+    }
+    os.Stdout.WriteString(s)
+}
 

 

 This program is small but it's doing a number of new things.  In the last example,
 we saw func introduce a function.  The keywords var, const, and type
 (not used yet) also introduce declarations, as does import.
 Notice that we can group declarations of the same sort into
-parenthesized lists, one item per line, as on lines 7-10 and 14-17.
+parenthesized lists, one item per line, as in the import and const clauses here.
 But it's not necessary to do so; we could have said
 

 
-    const Space = " "
-    const Newline = "\n"
+const Space = " "
+const Newline = "\n"
 

 

 This program imports the "os" package to access its Stdout variable, of type
@@ -186,7 +186,7 @@ string variable we will use to build the output.
 The declaration statement has the form
 

 
-    var s string = ""
+var s string = ""
 

 

 This is the var keyword, followed by the name of the variable, followed by
@@ -197,20 +197,20 @@ string constant is of type string, we don't have to tell the compiler that.
 We could write
 

 
-    var s = ""
+var s = ""
 

 

 or we could go even shorter and write the idiom
 

 
-    s := ""
+s := ""
 

 

 The := operator is used a lot in Go to represent an initializing declaration.
 There's one in the for clause on the next line:
 

-
 
-22        for i := 0; i < flag.NArg(); i++ {
+
    for i := 0; i < flag.NArg(); i++ {
 

 

 The flag package has parsed the arguments and left the non-flag arguments
@@ -231,7 +231,7 @@ It's defined that way.  Falling off the end of main.main means
 ''success''; if you want to signal an erroneous return, call
 

 
-    os.Exit(1)
+os.Exit(1)
 

 

 The os package contains other essentials for getting
@@ -259,20 +259,20 @@ Once you've built a string value, you can't change it, although
 of course you can change a string variable simply by
 reassigning it.  This snippet from strings.go is legal code:
 

-
 
-10        s := "hello"
-11        if s[1] != 'e' { os.Exit(1) }
-12        s = "good bye"
-13        var p *string = &s
-14        *p = "ciao"
+
    s := "hello"
+    if s[1] != 'e' { os.Exit(1) }
+    s = "good bye"
+    var p *string = &s
+    *p = "ciao"
 

 

 However the following statements are illegal because they would modify
 a string value:
 

 
-    s[0] = 'x'
-    (*p)[1] = 'y'
+s[0] = 'x'
+(*p)[1] = 'y'
 

 

 In C++ terms, Go strings are a bit like const strings, while pointers
@@ -284,7 +284,7 @@ read on.
 Arrays are declared like this:
 

 
-    var arrayOfInt [10]int
+var arrayOfInt [10]int
 

 

 Arrays, like strings, are values, but they are mutable. This differs
@@ -315,7 +315,7 @@ expression formed
 from a type followed by a brace-bounded expression like this:
 

 
-    [3]int{1,2,3}
+[3]int{1,2,3}
 

 

 In this case the constructor builds an array of 3 ints.
@@ -330,14 +330,14 @@ will slice the whole array.
 

 Using slices one can write this function (from sum.go):
 

-
 
-09    func sum(a []int) int { // returns an int
-10        s := 0
-11        for i := 0; i < len(a); i++ {
-12            s += a[i]
-13        }
-14        return s
-15    }
+
func sum(a []int) int { // returns an int
+    s := 0
+    for i := 0; i < len(a); i++ {
+        s += a[i]
+    }
+    return s
+}
 

 

 Note how the return type (int) is defined for sum by stating it
@@ -348,14 +348,14 @@ a simpler way in a moment) constructs
 an array and slices it:
 

 
-    s := sum([3]int{1,2,3}[:])
+s := sum([3]int{1,2,3}[:])
 

 

 If you are creating a regular array but want the compiler to count the
 elements for you, use ... as the array size:
 

 
-    s := sum([...]int{1,2,3}[:])
+s := sum([...]int{1,2,3}[:])
 

 

 That's fussier than necessary, though.
@@ -363,13 +363,13 @@ In practice, unless you're meticulous about storage layout within a
 data structure, a slice itself—using empty brackets with no size—is all you need:
 

 
-    s := sum([]int{1,2,3})
+s := sum([]int{1,2,3})
 

 

 There are also maps, which you can initialize like this:
 

 
-    m := map[string]int{"one":1 , "two":2}
+m := map[string]int{"one":1 , "two":2}
 

 

 The built-in function len, which returns number of elements,
@@ -380,13 +380,13 @@ By the way, another thing that works on strings, arrays, slices, maps
 and channels is the range clause on for loops.  Instead of writing
 

 
-    for i := 0; i < len(a); i++ { ... }
+for i := 0; i < len(a); i++ { ... }
 

 

 to loop over the elements of a slice (or map or ...) , we could write
 

 
-    for i, v := range a { ... }
+for i, v := range a { ... }
 

 

 This assigns i to the index and v to the value of the successive
@@ -404,14 +404,14 @@ To allocate a new variable, use the built-in function new, which
 returns a pointer to the allocated storage.
 

 
-    type T struct { a, b int }
-    var t *T = new(T)
+type T struct { a, b int }
+var t *T = new(T)
 

 

 or the more idiomatic
 

 
-    t := new(T)
+t := new(T)
 

 

 Some types—maps, slices, and channels (see below)—have reference semantics.
@@ -420,14 +420,14 @@ referencing the same underlying data will see the modification.  For these three
 types you want to use the built-in function make:
 

 
-    m := make(map[string]int)
+m := make(map[string]int)
 

 

 This statement initializes a new map ready to store entries.
 If you just declare the map, as in
 

 
-    var m map[string]int
+var m map[string]int
 

 

 it creates a nil reference that cannot hold anything. To use the map,
@@ -448,20 +448,20 @@ can overflow only when they are assigned to an integer variable with
 too little precision to represent the value.
 

 
-    const hardEight = (1 << 100) >> 97  // legal
+const hardEight = (1 << 100) >> 97  // legal
 

 

 There are nuances that deserve redirection to the legalese of the
 language specification but here are some illustrative examples:
 

 
-    var a uint64 = 0  // a has type uint64, value 0
-    a := uint64(0)    // equivalent; uses a "conversion"
-    i := 0x1234       // i gets default type: int
-    var j int = 1e6   // legal - 1000000 is representable in an int
-    x := 1.5          // a float64, the default type for floating constants
-    i3div2 := 3/2     // integer division - result is 1
-    f3div2 := 3./2.   // floating-point division - result is 1.5
+var a uint64 = 0  // a has type uint64, value 0
+a := uint64(0)    // equivalent; uses a "conversion"
+i := 0x1234       // i gets default type: int
+var j int = 1e6   // legal - 1000000 is representable in an int
+x := 1.5          // a float64, the default type for floating constants
+i3div2 := 3/2     // integer division - result is 1
+f3div2 := 3./2.   // floating-point division - result is 1.5
 

 

 Conversions only work for simple cases such as converting ints of one
@@ -476,18 +476,18 @@ assigned to a variable.
 Next we'll look at a simple package for doing file I/O with an
 open/close/read/write interface.  Here's the start of file.go:
 

-
 
-05    package file
+
package file
 
-07    import (
-08        "os"
-09        "syscall"
-10    )
+import (
+    "os"
+    "syscall"
+)
 
-12    type File struct {
-13        fd   int    // file descriptor number
-14        name string // file name at Open time
-15    }
+type File struct {
+    fd   int    // file descriptor number
+    name string // file name at Open time
+}
 

 

 The first few lines declare the name of the
@@ -518,13 +518,13 @@ will soon give it some exported, upper-case methods.
 

 First, though, here is a factory to create a File:
 

-
 
-17    func newFile(fd int, name string) *File {
-18        if fd < 0 {
-19            return nil
-20        }
-21        return &File{fd, name}
-22    }
+
func newFile(fd int, name string) *File {
+    if fd < 0 {
+        return nil
+    }
+    return &File{fd, name}
+}
 

 

 This returns a pointer to a new File structure with the file descriptor and name
@@ -533,10 +533,10 @@ the ones used to build maps and arrays, to construct a new heap-allocated
 object.  We could write
 

 
-    n := new(File)
-    n.fd = fd
-    n.name = name
-    return n
+n := new(File)
+n.fd = fd
+n.name = name
+return n
 

 

 but for simple structures like File it's easier to return the address of a 
@@ -544,25 +544,26 @@ composite literal, as is done here on line 21.
 

 We can use the factory to construct some familiar, exported variables of type *File:
 

-
 
-24    var (
-25        Stdin  = newFile(syscall.Stdin, "/dev/stdin")
-26        Stdout = newFile(syscall.Stdout, "/dev/stdout")
-27        Stderr = newFile(syscall.Stderr, "/dev/stderr")
-28    )
+
var (
+    Stdin  = newFile(syscall.Stdin, "/dev/stdin")
+    Stdout = newFile(syscall.Stdout, "/dev/stdout")
+    Stderr = newFile(syscall.Stderr, "/dev/stderr")
+)
+
 

 

 The newFile function was not exported because it's internal. The proper,
 exported factory to use is OpenFile (we'll explain that name in a moment):
 

-
 
-30    func OpenFile(name string, mode int, perm uint32) (file *File, err os.Error) {
-31        r, e := syscall.Open(name, mode, perm)
-32        if e != 0 {
-33            err = os.Errno(e)
-34        }
-35        return newFile(r, name), err
-36    }
+
func OpenFile(name string, mode int, perm uint32) (file *File, err os.Error) {
+    r, e := syscall.Open(name, mode, perm)
+    if e != 0 {
+        err = os.Errno(e)
+    }
+    return newFile(r, name), err
+}
 

 

 There are a number of new things in these few lines.  First, OpenFile returns
@@ -593,23 +594,23 @@ the implementation of our Open and Create; they're tri
 wrappers that eliminate common errors by capturing
 the tricky standard arguments to open and, especially, to create a file:
 

-
 
-38    const (
-39        O_RDONLY = syscall.O_RDONLY
-40        O_RDWR   = syscall.O_RDWR
-41        O_CREATE = syscall.O_CREAT
-42        O_TRUNC  = syscall.O_TRUNC
-43    )
+
const (
+    O_RDONLY = syscall.O_RDONLY
+    O_RDWR   = syscall.O_RDWR
+    O_CREATE = syscall.O_CREAT
+    O_TRUNC  = syscall.O_TRUNC
+)
 
-45    func Open(name string) (file *File, err os.Error) {
-46        return OpenFile(name, O_RDONLY, 0)
-47    }
+func Open(name string) (file *File, err os.Error) {
+    return OpenFile(name, O_RDONLY, 0)
+}
 

 

-
 
-49    func Create(name string) (file *File, err os.Error) {
-50        return OpenFile(name, O_RDWR|O_CREATE|O_TRUNC, 0666)
-51    }
+
func Create(name string) (file *File, err os.Error) {
+    return OpenFile(name, O_RDWR|O_CREATE|O_TRUNC, 0666)
+}
 

 

 Back to our main story.
@@ -619,44 +620,44 @@ of that type, placed
 in parentheses before the function name. Here are some methods for *File,
 each of which declares a receiver variable file.
 

-
 
-53    func (file *File) Close() os.Error {
-54        if file == nil {
-55            return os.EINVAL
-56        }
-57        e := syscall.Close(file.fd)
-58        file.fd = -1 // so it can't be closed again
-59        if e != 0 {
-60            return os.Errno(e)
-61        }
-62        return nil
-63    }
+
func (file *File) Close() os.Error {
+    if file == nil {
+        return os.EINVAL
+    }
+    e := syscall.Close(file.fd)
+    file.fd = -1 // so it can't be closed again
+    if e != 0 {
+        return os.Errno(e)
+    }
+    return nil
+}
 
-65    func (file *File) Read(b []byte) (ret int, err os.Error) {
-66        if file == nil {
-67            return -1, os.EINVAL
-68        }
-69        r, e := syscall.Read(file.fd, b)
-70        if e != 0 {
-71            err = os.Errno(e)
-72        }
-73        return int(r), err
-74    }
+func (file *File) Read(b []byte) (ret int, err os.Error) {
+    if file == nil {
+        return -1, os.EINVAL
+    }
+    r, e := syscall.Read(file.fd, b)
+    if e != 0 {
+        err = os.Errno(e)
+    }
+    return int(r), err
+}
 
-76    func (file *File) Write(b []byte) (ret int, err os.Error) {
-77        if file == nil {
-78            return -1, os.EINVAL
-79        }
-80        r, e := syscall.Write(file.fd, b)
-81        if e != 0 {
-82            err = os.Errno(e)
-83        }
-84        return int(r), err
-85    }
+func (file *File) Write(b []byte) (ret int, err os.Error) {
+    if file == nil {
+        return -1, os.EINVAL
+    }
+    r, e := syscall.Write(file.fd, b)
+    if e != 0 {
+        err = os.Errno(e)
+    }
+    return int(r), err
+}
 
-87    func (file *File) String() string {
-88        return file.name
-89    }
+func (file *File) String() string {
+    return file.name
+}
 

 

 There is no implicit this and the receiver variable must be used to access
@@ -674,24 +675,24 @@ set of such error values.
 

 We can now use our new package:
 

-
 
-05    package main
+
package main
 
-07    import (
-08        "./file"
-09        "fmt"
-10        "os"
-11    )
+import (
+    "./file"
+    "fmt"
+    "os"
+)
 
-13    func main() {
-14        hello := []byte("hello, world\n")
-15        file.Stdout.Write(hello)
-16        f, err := file.Open("/does/not/exist")
-17        if f == nil {
-18            fmt.Printf("can't open file; err=%s\n",  err.String())
-19            os.Exit(1)
-20        }
-21    }
+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.String())
+        os.Exit(1)
+    }
+}
 

 

 The ''./'' in the import of ''./file'' tells the compiler
@@ -703,13 +704,13 @@ package.)
 Now we can compile and run the program. On Unix, this would be the result:
 

 
-    $ 6g file.go                       # compile file package
-    $ 6g helloworld3.go                # compile main package
-    $ 6l -o helloworld3 helloworld3.6  # link - no need to mention "file"
-    $ helloworld3
-    hello, world
-    can't open file; err=No such file or directory
-    $
+$ 6g file.go                       # compile file package
+$ 6g helloworld3.go                # compile main package
+$ 6l -o helloworld3 helloworld3.6  # link - no need to mention "file"
+$ helloworld3
+hello, world
+can't open file; err=No such file or directory
+$
 

 

 
Rotting cats

@@ -717,56 +718,56 @@ Now we can compile and run the program. On Unix, this would be the result:
 Building on the file package, here's a simple version of the Unix utility cat(1),
 progs/cat.go:
 

-
 
-05    package main
+
package main
 
-07    import (
-08        "./file"
-09        "flag"
-10        "fmt"
-11        "os"
-12    )
+import (
+    "./file"
+    "flag"
+    "fmt"
+    "os"
+)
 
-14    func cat(f *file.File) {
-15        const NBUF = 512
-16        var buf [NBUF]byte
-17        for {
-18            switch nr, er := f.Read(buf[:]); true {
-19            case nr < 0:
-20                fmt.Fprintf(os.Stderr, "cat: error reading from %s: %s\n", f.String(), er.String())
-21                os.Exit(1)
-22            case nr == 0: // EOF
-23                return
-24            case nr > 0:
-25                if nw, ew := file.Stdout.Write(buf[0:nr]); nw != nr {
-26                    fmt.Fprintf(os.Stderr, "cat: error writing from %s: %s\n", f.String(), ew.String())
-27                    os.Exit(1)
-28                }
-29            }
-30        }
-31    }
+func cat(f *file.File) {
+    const NBUF = 512
+    var buf [NBUF]byte
+    for {
+        switch nr, er := f.Read(buf[:]); true {
+        case nr < 0:
+            fmt.Fprintf(os.Stderr, "cat: error reading from %s: %s\n", f.String(), er.String())
+            os.Exit(1)
+        case nr == 0: // EOF
+            return
+        case nr > 0:
+            if nw, ew := file.Stdout.Write(buf[0:nr]); nw != nr {
+                fmt.Fprintf(os.Stderr, "cat: error writing from %s: %s\n", f.String(), ew.String())
+                os.Exit(1)
+            }
+        }
+    }
+}
 
-33    func main() {
-34        flag.Parse() // Scans the arg list and sets up flags
-35        if flag.NArg() == 0 {
-36            cat(file.Stdin)
-37        }
-38        for i := 0; i < flag.NArg(); i++ {
-39            f, err := file.Open(flag.Arg(i))
-40            if f == nil {
-41                fmt.Fprintf(os.Stderr, "cat: can't open %s: error %s\n", flag.Arg(i), err)
-42                os.Exit(1)
-43            }
-44            cat(f)
-45            f.Close()
-46        }
-47    }
+func main() {
+    flag.Parse() // Scans the arg list and sets up flags
+    if flag.NArg() == 0 {
+        cat(file.Stdin)
+    }
+    for i := 0; i < flag.NArg(); i++ {
+        f, err := file.Open(flag.Arg(i))
+        if f == nil {
+            fmt.Fprintf(os.Stderr, "cat: can't open %s: error %s\n", flag.Arg(i), err)
+            os.Exit(1)
+        }
+        cat(f)
+        f.Close()
+    }
+}
 

 

 By now this should be easy to follow, but the switch statement introduces some
 new features.  Like a for loop, an if or switch can include an
-initialization statement.  The switch on line 18 uses one to create variables
-nr and er to hold the return values from the call to f.Read.  (The if on line 25
+initialization statement.  The switch statement in cat uses one to create variables
+nr and er to hold the return values from the call to f.Read.  (The if a few lines later
 has the same idea.)  The switch statement is general: it evaluates the cases
 from  top to bottom looking for the first case that matches the value; the
 case expressions don't need to be constants or even integers, as long as
@@ -778,7 +779,7 @@ in a for statement, a missing value means true.  In fa
 is a form of if-else chain. While we're here, it should be mentioned that in
 switch statements each case has an implicit break.
 

-Line 25 calls Write by slicing the incoming buffer, which is itself a slice.
+The argument to file.Stdout.Write is created by slicing the array buf.
 Slices provide the standard Go way to handle I/O buffers.
 

 Now let's make a variant of cat that optionally does rot13 on its input.
@@ -789,11 +790,11 @@ The cat subroutine uses only two methods of f: R
 so let's start by defining an interface that has exactly those two methods.
 Here is code from progs/cat_rot13.go:
 

-
 
-26    type reader interface {
-27        Read(b []byte) (ret int, err os.Error)
-28        String() string
-29    }
+
type reader interface {
+    Read(b []byte) (ret int, err os.Error)
+    String() string
+}
 

 

 Any type that has the two methods of reader—regardless of whatever
@@ -806,68 +807,68 @@ existing reader and does rot13 on the data. To do this
 the type and implement the methods and with no other bookkeeping,
 we have a second implementation of the reader interface.
 

-
 
-31    type rotate13 struct {
-32        source reader
-33    }
+
type rotate13 struct {
+    source reader
+}
 
-35    func newRotate13(source reader) *rotate13 {
-36        return &rotate13{source}
-37    }
+func newRotate13(source reader) *rotate13 {
+    return &rotate13{source}
+}
 
-39    func (r13 *rotate13) Read(b []byte) (ret int, err os.Error) {
-40        r, e := r13.source.Read(b)
-41        for i := 0; i < r; i++ {
-42            b[i] = rot13(b[i])
-43        }
-44        return r, e
-45    }
+func (r13 *rotate13) Read(b []byte) (ret int, err os.Error) {
+    r, e := r13.source.Read(b)
+    for i := 0; i < r; i++ {
+        b[i] = rot13(b[i])
+    }
+    return r, e
+}
 
-47    func (r13 *rotate13) String() string {
-48        return r13.source.String()
-49    }
-50    // end of rotate13 implementation
+func (r13 *rotate13) String() string {
+    return r13.source.String()
+}
+// end of rotate13 implementation
 

 

-(The rot13 function called on line 42 is trivial and not worth reproducing here.)
+(The rot13 function called in Read is trivial and not worth reproducing here.)
 

 To use the new feature, we define a flag:
 

-
 
-14    var rot13Flag = flag.Bool("rot13", false, "rot13 the input")
+
var rot13Flag = flag.Bool("rot13", false, "rot13 the input")
 

 

 and use it from within a mostly unchanged cat function:
 

-
 
-52    func cat(r reader) {
-53        const NBUF = 512
-54        var buf [NBUF]byte
+
func cat(r reader) {
+    const NBUF = 512
+    var buf [NBUF]byte
 
-56        if *rot13Flag {
-57            r = newRotate13(r)
-58        }
-59        for {
-60            switch nr, er := r.Read(buf[:]); {
-61            case nr < 0:
-62                fmt.Fprintf(os.Stderr, "cat: error reading from %s: %s\n", r.String(), er.String())
-63                os.Exit(1)
-64            case nr == 0: // EOF
-65                return
-66            case nr > 0:
-67                nw, ew := file.Stdout.Write(buf[0:nr])
-68                if nw != nr {
-69                    fmt.Fprintf(os.Stderr, "cat: error writing from %s: %s\n", r.String(), ew.String())
-70                    os.Exit(1)
-71                }
-72            }
-73        }
-74    }
+    if *rot13Flag {
+        r = newRotate13(r)
+    }
+    for {
+        switch nr, er := r.Read(buf[:]); {
+        case nr < 0:
+            fmt.Fprintf(os.Stderr, "cat: error reading from %s: %s\n", r.String(), er.String())
+            os.Exit(1)
+        case nr == 0: // EOF
+            return
+        case nr > 0:
+            nw, ew := file.Stdout.Write(buf[0:nr])
+            if nw != nr {
+                fmt.Fprintf(os.Stderr, "cat: error writing from %s: %s\n", r.String(), ew.String())
+                os.Exit(1)
+            }
+        }
+    }
+}
 

 

 (We could also do the wrapping in main and leave cat mostly alone, except
 for changing the type of the argument; consider that an exercise.)
-Lines 56 through 58 set it all up: If the rot13 flag is true, wrap the reader
+The if at the top of cat sets it all up: If the rot13 flag is true, wrap the reader
 we received into a rotate13 and proceed.  Note that the interface variables
 are values, not pointers: the argument is of type reader, not *reader,
 even though under the covers it holds a pointer to a struct.
@@ -875,11 +876,11 @@ even though under the covers it holds a pointer to a struct.
 Here it is in action:
 

 
-    $ echo abcdefghijklmnopqrstuvwxyz | ./cat
-    abcdefghijklmnopqrstuvwxyz
-    $ echo abcdefghijklmnopqrstuvwxyz | ./cat --rot13
-    nopqrstuvwxyzabcdefghijklm
-    $
+$ echo abcdefghijklmnopqrstuvwxyz | ./cat
+abcdefghijklmnopqrstuvwxyz
+$ echo abcdefghijklmnopqrstuvwxyz | ./cat --rot13
+nopqrstuvwxyzabcdefghijklm
+$
 

 

 Fans of dependency injection may take cheer from how easily interfaces
@@ -895,7 +896,7 @@ implement a writer, or any other interface built from its methods t
 fits the current situation. Consider the empty interface
 

 
-    type Empty interface {}
+type Empty interface {}
 

 

 Every type implements the empty interface, which makes it
@@ -910,36 +911,36 @@ same interface variable.
 

 As an example, consider this simple sort algorithm taken from progs/sort.go:
 

-
 
-13    func Sort(data Interface) {
-14        for i := 1; i < data.Len(); i++ {
-15            for j := i; j > 0 && data.Less(j, j-1); j-- {
-16                data.Swap(j, j-1)
-17            }
-18        }
-19    }
+
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)
+        }
+    }
+}
 

 

 The code needs only three methods, which we wrap into sort's Interface:
 

-
 
-07    type Interface interface {
-08        Len() int
-09        Less(i, j int) bool
-10        Swap(i, j int)
-11    }
+
type Interface interface {
+    Len() int
+    Less(i, j int) bool
+    Swap(i, j int)
+}
 

 

 We can apply Sort to any type that implements Len, Less, and Swap.
 The sort package includes the necessary methods to allow sorting of
 arrays of integers, strings, etc.; here's the code for arrays of int
 

-
 
-33    type IntSlice []int
+
type IntSlice []int
 
-35    func (p IntSlice) Len() int            { return len(p) }
-36    func (p IntSlice) Less(i, j int) bool  { return p[i] < p[j] }
-37    func (p IntSlice) Swap(i, j int)       { p[i], p[j] = p[j], p[i] }
+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] }
 

 

 Here we see methods defined for non-struct types.  You can define methods
@@ -949,34 +950,34 @@ And now a routine to test it out, from progs/sortmain.go.  This
 uses a function in the sort package, omitted here for brevity,
 to test that the result is sorted.
 

-
 
-12    func ints() {
-13        data := []int{74, 59, 238, -784, 9845, 959, 905, 0, 0, 42, 7586, -5467984, 7586}
-14        a := sort.IntSlice(data)
-15        sort.Sort(a)
-16        if !sort.IsSorted(a) {
-17            panic("fail")
-18        }
-19    }
+
func ints() {
+    data := []int{74, 59, 238, -784, 9845, 959, 905, 0, 0, 42, 7586, -5467984, 7586}
+    a := sort.IntSlice(data)
+    sort.Sort(a)
+    if !sort.IsSorted(a) {
+        panic("fail")
+    }
+}
 

 

 If we have a new type we want to be able to sort, all we need to do is
 to implement the three methods for that type, like this:
 

-
 
-30    type day struct {
-31        num        int
-32        shortName  string
-33        longName   string
-34    }
+
type day struct {
+    num        int
+    shortName  string
+    longName   string
+}
 
-36    type dayArray struct {
-37        data []*day
-38    }
+type dayArray struct {
+    data []*day
+}
 
-40    func (p *dayArray) Len() int            { return len(p.data) }
-41    func (p *dayArray) Less(i, j int) bool  { return p.data[i].num < p.data[j].num }
-42    func (p *dayArray) Swap(i, j int)       { p.data[i], p.data[j] = p.data[j], p.data[i] }
+func (p *dayArray) Len() int            { return len(p.data) }
+func (p *dayArray) Less(i, j int) bool  { return p.data[i].num < p.data[j].num }
+func (p *dayArray) Swap(i, j int)       { p.data[i], p.data[j] = p.data[j], p.data[i] }
 

 

 

@@ -990,7 +991,7 @@ implements Printf, Fprintf, and so on.
 Within the fmt package, Printf is declared with this signature:
 

 
-    Printf(format string, v ...interface{}) (n int, errno os.Error)
+Printf(format string, v ...interface{}) (n int, errno os.Error)
 

 

 The token ... introduces a variable-length argument list that in C would
@@ -1011,34 +1012,34 @@ argument.  It's easier in many cases in Go.  Instead of %llud you
 can just say %d; Printf knows the size and signedness of the
 integer and can do the right thing for you.  The snippet
 

-
 
-10        var u64 uint64 = 1<<64-1
-11        fmt.Printf("%d %d\n", u64, int64(u64))
+
    var u64 uint64 = 1<<64-1
+    fmt.Printf("%d %d\n", u64, int64(u64))
 

 

 prints
 

 
-    18446744073709551615 -1
+18446744073709551615 -1
 

 

 In fact, if you're lazy the format %v will print, in a simple
 appropriate style, any value, even an array or structure.  The output of
 

-
 
-14        type T struct {
-15            a int
-16            b string
-17        }
-18        t := T{77, "Sunset Strip"}
-19        a := []int{1, 2, 3, 4}
-20        fmt.Printf("%v %v %v\n", u64, t, a)
+
    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)
 

 

 is
 

 
-    18446744073709551615 {77 Sunset Strip} [1 2 3 4]
+18446744073709551615 {77 Sunset Strip} [1 2 3 4]
 

 

 You can drop the formatting altogether if you use Print or Println
@@ -1048,9 +1049,9 @@ of %v while Println inserts spaces between arguments
 and adds a newline.  The output of each of these two lines is identical
 to that of the Printf call above.
 

-
 
-21        fmt.Print(u64, " ", t, " ", a, "\n")
-22        fmt.Println(u64, t, a)
+
    fmt.Print(u64, " ", t, " ", a, "\n")
+    fmt.Println(u64, t, a)
 

 

 If you have your own type you'd like Printf or Print to format,
@@ -1059,27 +1060,27 @@ routines will examine the value to inquire whether it implements
 the method and if so, use it rather than some other formatting.
 Here's a simple example.
 

-
 
-09    type testType struct {
-10        a int
-11        b string
-12    }
+
type testType struct {
+    a int
+    b string
+}
 
-14    func (t *testType) String() string {
-15        return fmt.Sprint(t.a) + " " + t.b
-16    }
+func (t *testType) String() string {
+    return fmt.Sprint(t.a) + " " + t.b
+}
 
-18    func main() {
-19        t := &testType{77, "Sunset Strip"}
-20        fmt.Println(t)
-21    }
+func main() {
+    t := &testType{77, "Sunset Strip"}
+    fmt.Println(t)
+}
 

 

 Since *testType has a String method, the
 default formatter for that type will use it and produce the output
 

 
-    77 Sunset Strip
+77 Sunset Strip
 

 

 Observe that the String method calls Sprint (the obvious Go
@@ -1101,18 +1102,18 @@ Schematically, given a value v, it does this:
 

 

 
-    type Stringer interface {
-        String() string
-    }
+type Stringer interface {
+    String() string
+}
 

 

 
-    s, ok := v.(Stringer)  // Test whether v implements "String()"
-    if ok {
-        result = s.String()
-    } else {
-        result = defaultOutput(v)
-    }
+s, ok := v.(Stringer)  // Test whether v implements "String()"
+if ok {
+    result = s.String()
+} else {
+    result = defaultOutput(v)
+}
 

 

 The code uses a ``type assertion'' (v.(Stringer)) to test if the value stored in
@@ -1133,9 +1134,9 @@ not a file.  Instead, it is a variable of type io.Writer, which is
 interface type defined in the io library:
 

 
-    type Writer interface {
-        Write(p []byte) (n int, err os.Error)
-    }
+type Writer interface {
+    Write(p []byte) (n int, err os.Error)
+}
 

 

 (This interface is another conventional name, this time for Write; there are also
@@ -1178,13 +1179,13 @@ coordinates the communication; as with maps and slices, use
 

 Here is the first function in progs/sieve.go:
 

-
 
-09    // Send the sequence 2, 3, 4, ... to channel 'ch'.
-10    func generate(ch chan int) {
-11        for i := 2; ; i++ {
-12            ch <- i  // Send 'i' to channel 'ch'.
-13        }
-14    }
+
// 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'.
+    }
+}
 

 

 The generate function sends the sequence 2, 3, 4, 5, ... to its
@@ -1197,17 +1198,17 @@ channel, and a prime number.  It copies values from the input to the
 output, discarding anything divisible by the prime.  The unary communications
 operator <- (receive) retrieves the next value on the channel.
 

-
 
-16    // Copy the values from channel 'in' to channel 'out',
-17    // removing those divisible by 'prime'.
-18    func filter(in, out chan int, prime int) {
-19        for {
-20            i := <-in  // Receive value of new variable 'i' from 'in'.
-21            if i % prime != 0 {
-22                out <- i  // Send 'i' to channel 'out'.
-23            }
-24        }
-25    }
+
// Copy the values from channel 'in' to channel 'out',
+// removing those divisible by 'prime'.
+func filter(in, out chan int, prime int) {
+    for {
+        i := <-in  // Receive value of new variable 'i' from 'in'.
+        if i % prime != 0 {
+            out <- i  // Send 'i' to channel 'out'.
+        }
+    }
+}
 

 

 The generator and filters execute concurrently.  Go has
@@ -1219,37 +1220,37 @@ this starts the function running in parallel with the current
 computation but in the same address space:
 

 
-    go sum(hugeArray) // calculate sum in the background
+go sum(hugeArray) // calculate sum in the background
 

 

 If you want to know when the calculation is done, pass a channel
 on which it can report back:
 

 
-    ch := make(chan int)
-    go sum(hugeArray, ch)
-    // ... do something else for a while
-    result := <-ch  // wait for, and retrieve, result
+ch := make(chan int)
+go sum(hugeArray, ch)
+// ... do something else for a while
+result := <-ch  // wait for, and retrieve, result
 

 

 Back to our prime sieve.  Here's how the sieve pipeline is stitched
 together:
 

-
 
-28    func main() {
-29        ch := make(chan int)  // Create a new channel.
-30        go generate(ch)  // Start generate() as a goroutine.
-31        for i := 0; i < 100; i++ { // Print the first hundred primes.
-32            prime := <-ch
-33            fmt.Println(prime)
-34            ch1 := make(chan int)
-35            go filter(ch, ch1, prime)
-36            ch = ch1
-37        }
-38    }
+
func main() {
+    ch := make(chan int)  // Create a new channel.
+    go generate(ch)  // Start generate() as a goroutine.
+    for i := 0; i < 100; i++ { // Print the first hundred primes.
+        prime := <-ch
+        fmt.Println(prime)
+        ch1 := make(chan int)
+        go filter(ch, ch1, prime)
+        ch = ch1
+    }
+}
 

 

-Line 29 creates the initial channel to pass to generate, which it
+The first line of main creates the initial channel to pass to generate, which it
 then starts up.  As each prime pops out of the channel, a new filter
 is added to the pipeline and its output becomes the new value
 of ch.
@@ -1258,16 +1259,16 @@ The sieve program can be tweaked to use a pattern common
 in this style of programming.  Here is a variant version
 of generate, from progs/sieve1.go:
 

-
 
-10    func generate() chan int {
-11        ch := make(chan int)
-12        go func(){
-13            for i := 2; ; i++ {
-14                ch <- i
-15            }
-16        }()
-17        return ch
-18    }
+
func generate() chan int {
+    ch := make(chan int)
+    go func(){
+        for i := 2; ; i++ {
+            ch <- i
+        }
+    }()
+    return ch
+}
 

 

 This version does all the setup internally. It creates the output
@@ -1275,54 +1276,54 @@ channel, launches a goroutine running a function literal, and
 returns the channel to the caller.  It is a factory for concurrent
 execution, starting the goroutine and returning its connection.
 

-The function literal notation (lines 12-16) allows us to construct an
+The function literal notation used in the go statement allows us to construct an
 anonymous function and invoke it on the spot. Notice that the local
 variable ch is available to the function literal and lives on even
 after generate returns.
 

 The same change can be made to filter:
 

-
 
-21    func filter(in chan int, prime int) chan int {
-22        out := make(chan int)
-23        go func() {
-24            for {
-25                if i := <-in; i % prime != 0 {
-26                    out <- i
-27                }
-28            }
-29        }()
-30        return out
-31    }
+
func filter(in chan int, prime int) chan int {
+    out := make(chan int)
+    go func() {
+        for {
+            if i := <-in; i % prime != 0 {
+                out <- i
+            }
+        }
+    }()
+    return out
+}
 

 

 The sieve function's main loop becomes simpler and clearer as a
 result, and while we're at it let's turn it into a factory too:
 

-
 
-33    func sieve() chan int {
-34        out := make(chan int)
-35        go func() {
-36            ch := generate()
-37            for {
-38                prime := <-ch
-39                out <- prime
-40                ch = filter(ch, prime)
-41            }
-42        }()
-43        return out
-44    }
+
func sieve() chan int {
+    out := make(chan int)
+    go func() {
+        ch := generate()
+        for {
+            prime := <-ch
+            out <- prime
+            ch = filter(ch, prime)
+        }
+    }()
+    return out
+}
 

 

 Now main's interface to the prime sieve is a channel of primes:
 

-
 
-46    func main() {
-47        primes := sieve()
-48        for i := 0; i < 100; i++ { // Print the first hundred primes.
-49            fmt.Println(<-primes)
-50        }
-51    }
+
func main() {
+    primes := sieve()
+    for i := 0; i < 100; i++ { // Print the first hundred primes.
+        fmt.Println(<-primes)
+    }
+}
 

 

 
Multiplexing

@@ -1334,102 +1335,102 @@ A realistic client-server program is a lot of code, so here is a very simple sub
 to illustrate the idea.  It starts by defining a request type, which embeds a channel
 that will be used for the reply.
 

-
 
-09    type request struct {
-10        a, b    int
-11        replyc  chan int
-12    }
+
type request struct {
+    a, b    int
+    replyc  chan int
+}
 

 

 The server will be trivial: it will do simple binary operations on integers.  Here's the
 code that invokes the operation and responds to the request:
 

-
 
-14    type binOp func(a, b int) int
+
type binOp func(a, b int) int
 
-16    func run(op binOp, req *request) {
-17        reply := op(req.a, req.b)
-18        req.replyc <- reply
-19    }
+func run(op binOp, req *request) {
+    reply := op(req.a, req.b)
+    req.replyc <- reply
+}
 

 

-Line 14 defines the name binOp to be a function taking two integers and
+The type declaration makes binOp represent a function taking two integers and
 returning a third.
 

 The server routine loops forever, receiving requests and, to avoid blocking due to
 a long-running operation, starting a goroutine to do the actual work.
 

-
 
-21    func server(op binOp, service chan *request) {
-22        for {
-23            req := <-service
-24            go run(op, req)  // don't wait for it
-25        }
-26    }
+
func server(op binOp, service chan *request) {
+    for {
+        req := <-service
+        go run(op, req)  // don't wait for it
+    }
+}
 

 

 We construct a server in a familiar way, starting it and returning a channel
 connected to it:
 

-
 
-28    func startServer(op binOp) chan *request {
-29        req := make(chan *request)
-30        go server(op, req)
-31        return req
-32    }
+
func startServer(op binOp) chan *request {
+    req := make(chan *request)
+    go server(op, req)
+    return req
+}
 

 

 Here's a simple test.  It starts a server with an addition operator and sends out
 N requests without waiting for the replies.  Only after all the requests are sent
 does it check the results.
 

-
 
-34    func main() {
-35        adder := startServer(func(a, b int) int { return a + b })
-36        const N = 100
-37        var reqs [N]request
-38        for i := 0; i < N; i++ {
-39            req := &reqs[i]
-40            req.a = i
-41            req.b = i + N
-42            req.replyc = make(chan int)
-43            adder <- req
-44        }
-45        for i := N-1; i >= 0; i-- {   // doesn't matter what order
-46            if <-reqs[i].replyc != N + 2*i {
-47                fmt.Println("fail at", i)
-48            }
-49        }
-50        fmt.Println("done")
-51    }
+
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")
+}
 

 

 One annoyance with this program is that it doesn't shut down the server cleanly; when main returns
 there are a number of lingering goroutines blocked on communication.  To solve this,
 we can provide a second, quit channel to the server:
 

-
 
-32    func startServer(op binOp) (service chan *request, quit chan bool) {
-33        service = make(chan *request)
-34        quit = make(chan bool)
-35        go server(op, service, quit)
-36        return service, quit
-37    }
+
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
+}
 

 

 It passes the quit channel to the server function, which uses it like this:
 

-
 
-21    func server(op binOp, service chan *request, quit chan bool) {
-22        for {
-23            select {
-24            case req := <-service:
-25                go run(op, req)  // don't wait for it
-26            case <-quit:
-27                return
-28            }
-29        }
-30    }
+
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
+        }
+    }
+}
 

 

 Inside server, the select statement chooses which of the multiple communications
@@ -1442,12 +1443,12 @@ returns, terminating its execution.
 All that's left is to strobe the quit channel
 at the end of main:
 

-
 
-40        adder, quit := startServer(func(a, b int) int { return a + b })
+
    adder, quit := startServer(func(a, b int) int { return a + b })
 

 ...
-
 
-55        quit <- true
+
    quit <- true
 

 

 There's a lot more to Go programming and concurrent programming in general but this
diff --git a/doc/go_tutorial.txt b/doc/go_tutorial.txt
index 7e2bc7c4b97..17ef6eee930 100644
--- a/doc/go_tutorial.txt
+++ b/doc/go_tutorial.txt
@@ -28,7 +28,7 @@ Hello, World
 
 Let's start in the usual way:
 
---PROG progs/helloworld.go /package/ END
+!src progs/helloworld.go /package/ $
 
 Every Go source file declares, using a "package" statement, which package it's part of.
 It may also import other packages to use their facilities.
@@ -107,13 +107,13 @@ Echo
 
 Next up, here's a version of the Unix utility "echo(1)":
 
---PROG progs/echo.go /package/ END
+!src progs/echo.go /package/ $
 
 This program is small but it's doing a number of new things.  In the last example,
 we saw "func" introduce a function.  The keywords "var", "const", and "type"
 (not used yet) also introduce declarations, as does "import".
 Notice that we can group declarations of the same sort into
-parenthesized lists, one item per line, as on lines 7-10 and 14-17.
+parenthesized lists, one item per line, as in the "import" and "const" clauses here.
 But it's not necessary to do so; we could have said
 
 	const Space = " "
@@ -163,7 +163,7 @@ or we could go even shorter and write the idiom
 The ":=" operator is used a lot in Go to represent an initializing declaration.
 There's one in the "for" clause on the next line:
 
---PROG  progs/echo.go /for/
+!src  progs/echo.go /for/
 
 The "flag" package has parsed the arguments and left the non-flag arguments
 in a list that can be iterated over in the obvious way.
@@ -210,7 +210,7 @@ Once you've built a string value, you can't change it, although
 of course you can change a string variable simply by
 reassigning it.  This snippet from "strings.go" is legal code:
 
---PROG progs/strings.go /hello/ /ciao/
+!src progs/strings.go /hello/ /ciao/
 
 However the following statements are illegal because they would modify
 a "string" value:
@@ -269,7 +269,7 @@ will slice the whole array.
 
 Using slices one can write this function (from "sum.go"):
 
---PROG progs/sum.go /sum/ /^}/
+!src progs/sum.go /sum/ /^}/
 
 Note how the return type ("int") is defined for "sum" by stating it
 after the parameter list.
@@ -386,7 +386,7 @@ An I/O Package
 Next we'll look at a simple package for doing file I/O with an
 open/close/read/write interface.  Here's the start of "file.go":
 
---PROG progs/file.go /package/ /^}/
+!src progs/file.go /package/ /^}/
 
 The first few lines declare the name of the
 package—"file"—and then import two packages.  The "os"
@@ -416,7 +416,7 @@ will soon give it some exported, upper-case methods.
 
 First, though, here is a factory to create a "File":
 
---PROG progs/file.go /newFile/ /^}/
+!src progs/file.go /newFile/ /^}/
 
 This returns a pointer to a new "File" structure with the file descriptor and name
 filled in.  This code uses Go's notion of a ''composite literal'', analogous to
@@ -433,12 +433,12 @@ composite literal, as is done here on line 21.
 
 We can use the factory to construct some familiar, exported variables of type "*File":
 
---PROG progs/file.go /var/ /^.$/
+!src progs/file.go /var/ /^.$/
 
 The "newFile" function was not exported because it's internal. The proper,
 exported factory to use is "OpenFile" (we'll explain that name in a moment):
 
---PROG progs/file.go /func.OpenFile/ /^}/
+!src progs/file.go /func.OpenFile/ /^}/
 
 There are a number of new things in these few lines.  First, "OpenFile" returns
 multiple values, a "File" and an error (more about errors in a moment).
@@ -468,9 +468,9 @@ the implementation of our "Open" and "Create"; they're trivial
 wrappers that eliminate common errors by capturing
 the tricky standard arguments to open and, especially, to create a file:
 
---PROG progs/file.go /^const/ /^}/
+!src progs/file.go /^const/ /^}/
 
---PROG progs/file.go /func.Create/ /^}/
+!src progs/file.go /func.Create/ /^}/
 
 Back to our main story.
 Now that we can build "Files", we can write methods for them. To declare
@@ -479,7 +479,7 @@ of that type, placed
 in parentheses before the function name. Here are some methods for "*File",
 each of which declares a receiver variable "file".
 
---PROG progs/file.go /Close/ END
+!src progs/file.go /Close/ $
 
 There is no implicit "this" and the receiver variable must be used to access
 members of the structure.  Methods are not declared within
@@ -496,7 +496,7 @@ set of such error values.
 
 We can now use our new package:
 
---PROG progs/helloworld3.go /package/ END
+!src progs/helloworld3.go /package/ $
 
 The ''"./"'' in the import of ''"./file"'' tells the compiler
 to use our own package rather than
@@ -520,12 +520,12 @@ Rotting cats
 Building on the "file" package, here's a simple version of the Unix utility "cat(1)",
 "progs/cat.go":
 
---PROG progs/cat.go /package/ END
+!src progs/cat.go /package/ $
 
 By now this should be easy to follow, but the "switch" statement introduces some
 new features.  Like a "for" loop, an "if" or "switch" can include an
-initialization statement.  The "switch" on line 18 uses one to create variables
-"nr" and "er" to hold the return values from the call to "f.Read".  (The "if" on line 25
+initialization statement.  The "switch" statement in "cat" uses one to create variables
+"nr" and "er" to hold the return values from the call to "f.Read".  (The "if" a few lines later
 has the same idea.)  The "switch" statement is general: it evaluates the cases
 from  top to bottom looking for the first case that matches the value; the
 case expressions don't need to be constants or even integers, as long as
@@ -537,7 +537,7 @@ in a "for" statement, a missing value means "true".  In fact, such a "switch"
 is a form of "if-else" chain. While we're here, it should be mentioned that in
 "switch" statements each "case" has an implicit "break".
 
-Line 25 calls "Write" by slicing the incoming buffer, which is itself a slice.
+The argument to "file.Stdout.Write" is created by slicing the array "buf".
 Slices provide the standard Go way to handle I/O buffers.
 
 Now let's make a variant of "cat" that optionally does "rot13" on its input.
@@ -548,7 +548,7 @@ The "cat" subroutine uses only two methods of "f": "Read" and "String",
 so let's start by defining an interface that has exactly those two methods.
 Here is code from "progs/cat_rot13.go":
 
---PROG progs/cat_rot13.go /type.reader/ /^}/
+!src progs/cat_rot13.go /type.reader/ /^}/
 
 Any type that has the two methods of "reader"—regardless of whatever
 other methods the type may also have—is said to implement the
@@ -560,34 +560,32 @@ existing "reader" and does "rot13" on the data. To do this, we just define
 the type and implement the methods and with no other bookkeeping,
 we have a second implementation of the "reader" interface.
 
---PROG progs/cat_rot13.go /type.rotate13/ /end.of.rotate13/
+!src progs/cat_rot13.go /type.rotate13/ /end.of.rotate13/
 
-(The "rot13" function called on line 42 is trivial and not worth reproducing here.)
+(The "rot13" function called in "Read" is trivial and not worth reproducing here.)
 
 To use the new feature, we define a flag:
 
---PROG progs/cat_rot13.go /rot13Flag/
+!src progs/cat_rot13.go /rot13Flag/
 
 and use it from within a mostly unchanged "cat" function:
 
---PROG progs/cat_rot13.go /func.cat/ /^}/
+!src progs/cat_rot13.go /func.cat/ /^}/
 
 (We could also do the wrapping in "main" and leave "cat" mostly alone, except
 for changing the type of the argument; consider that an exercise.)
-Lines 56 through 58 set it all up: If the "rot13" flag is true, wrap the "reader"
+The "if" at the top of "cat" sets it all up: If the "rot13" flag is true, wrap the "reader"
 we received into a "rotate13" and proceed.  Note that the interface variables
 are values, not pointers: the argument is of type "reader", not "*reader",
 even though under the covers it holds a pointer to a "struct".
 
 Here it is in action:
 
-
 	$ echo abcdefghijklmnopqrstuvwxyz | ./cat
 	abcdefghijklmnopqrstuvwxyz
 	$ echo abcdefghijklmnopqrstuvwxyz | ./cat --rot13
 	nopqrstuvwxyzabcdefghijklm
 	$
-

 
 Fans of dependency injection may take cheer from how easily interfaces
 allow us to substitute the implementation of a file descriptor.
@@ -601,9 +599,7 @@ as we saw with "rot13".  The type "file.File" implements "reader"; it could also
 implement a "writer", or any other interface built from its methods that
 fits the current situation. Consider the empty interface
 
-
 	type Empty interface {}
-

 
 Every type implements the empty interface, which makes it
 useful for things like containers.
@@ -618,17 +614,17 @@ same interface variable.
 
 As an example, consider this simple sort algorithm taken from "progs/sort.go":
 
---PROG progs/sort.go /func.Sort/ /^}/
+!src progs/sort.go /func.Sort/ /^}/
 
 The code needs only three methods, which we wrap into sort's "Interface":
 
---PROG progs/sort.go /interface/ /^}/
+!src progs/sort.go /interface/ /^}/
 
 We can apply "Sort" to any type that implements "Len", "Less", and "Swap".
 The "sort" package includes the necessary methods to allow sorting of
 arrays of integers, strings, etc.; here's the code for arrays of "int"
 
---PROG progs/sort.go /type.*IntSlice/ /Swap/
+!src progs/sort.go /type.*IntSlice/ /Swap/
 
 Here we see methods defined for non-"struct" types.  You can define methods
 for any type you define and name in your package.
@@ -637,12 +633,12 @@ And now a routine to test it out, from "progs/sortmain.go".  This
 uses a function in the "sort" package, omitted here for brevity,
 to test that the result is sorted.
 
---PROG progs/sortmain.go /func.ints/ /^}/
+!src progs/sortmain.go /func.ints/ /^}/
 
 If we have a new type we want to be able to sort, all we need to do is
 to implement the three methods for that type, like this:
 
---PROG progs/sortmain.go /type.day/ /Swap/
+!src progs/sortmain.go /type.day/ /Swap/
 
 
 Printing
@@ -675,7 +671,7 @@ argument.  It's easier in many cases in Go.  Instead of "%llud" you
 can just say "%d"; "Printf" knows the size and signedness of the
 integer and can do the right thing for you.  The snippet
 
---PROG progs/print.go 'NR==10' 'NR==11'
+!src progs/print.go 10 11
 
 prints
 
@@ -684,7 +680,7 @@ prints
 In fact, if you're lazy the format "%v" will print, in a simple
 appropriate style, any value, even an array or structure.  The output of
 
---PROG progs/print.go 'NR==14' 'NR==20'
+!src progs/print.go 14 20
 
 is
 
@@ -697,7 +693,7 @@ of "%v" while "Println" inserts spaces between arguments
 and adds a newline.  The output of each of these two lines is identical
 to that of the "Printf" call above.
 
---PROG progs/print.go 'NR==21' 'NR==22'
+!src progs/print.go 21 22
 
 If you have your own type you'd like "Printf" or "Print" to format,
 just give it a "String" method that returns a string.  The print
@@ -705,7 +701,7 @@ routines will examine the value to inquire whether it implements
 the method and if so, use it rather than some other formatting.
 Here's a simple example.
 
---PROG progs/print_string.go 'NR==9' END
+!src progs/print_string.go 9 $
 
 Since "*testType" has a "String" method, the
 default formatter for that type will use it and produce the output
@@ -803,7 +799,7 @@ coordinates the communication; as with maps and slices, use
 
 Here is the first function in "progs/sieve.go":
 
---PROG progs/sieve.go /Send/ /^}/
+!src progs/sieve.go /Send/ /^}/
 
 The "generate" function sends the sequence 2, 3, 4, 5, ... to its
 argument channel, "ch", using the binary communications operator "<-".
@@ -815,7 +811,7 @@ channel, and a prime number.  It copies values from the input to the
 output, discarding anything divisible by the prime.  The unary communications
 operator "<-" (receive) retrieves the next value on the channel.
 
---PROG progs/sieve.go /Copy.the/ /^}/
+!src progs/sieve.go /Copy.the/ /^}/
 
 The generator and filters execute concurrently.  Go has
 its own model of process/threads/light-weight processes/coroutines,
@@ -838,9 +834,9 @@ on which it can report back:
 Back to our prime sieve.  Here's how the sieve pipeline is stitched
 together:
 
---PROG progs/sieve.go /func.main/ /^}/
+!src progs/sieve.go /func.main/ /^}/
 
-Line 29 creates the initial channel to pass to "generate", which it
+The first line of "main" creates the initial channel to pass to "generate", which it
 then starts up.  As each prime pops out of the channel, a new "filter"
 is added to the pipeline and its output becomes the new value
 of "ch".
@@ -849,30 +845,30 @@ The sieve program can be tweaked to use a pattern common
 in this style of programming.  Here is a variant version
 of "generate", from "progs/sieve1.go":
 
---PROG progs/sieve1.go /func.generate/ /^}/
+!src progs/sieve1.go /func.generate/ /^}/
 
 This version does all the setup internally. It creates the output
 channel, launches a goroutine running a function literal, and
 returns the channel to the caller.  It is a factory for concurrent
 execution, starting the goroutine and returning its connection.
 
-The function literal notation (lines 12-16) allows us to construct an
+The function literal notation used in the "go" statement allows us to construct an
 anonymous function and invoke it on the spot. Notice that the local
 variable "ch" is available to the function literal and lives on even
 after "generate" returns.
 
 The same change can be made to "filter":
 
---PROG progs/sieve1.go /func.filter/ /^}/
+!src progs/sieve1.go /func.filter/ /^}/
 
 The "sieve" function's main loop becomes simpler and clearer as a
 result, and while we're at it let's turn it into a factory too:
 
---PROG progs/sieve1.go /func.sieve/ /^}/
+!src progs/sieve1.go /func.sieve/ /^}/
 
 Now "main"'s interface to the prime sieve is a channel of primes:
 
---PROG progs/sieve1.go /func.main/ /^}/
+!src progs/sieve1.go /func.main/ /^}/
 
 Multiplexing
 ----
@@ -884,41 +880,41 @@ A realistic client-server program is a lot of code, so here is a very simple sub
 to illustrate the idea.  It starts by defining a "request" type, which embeds a channel
 that will be used for the reply.
 
---PROG progs/server.go /type.request/ /^}/
+!src progs/server.go /type.request/ /^}/
 
 The server will be trivial: it will do simple binary operations on integers.  Here's the
 code that invokes the operation and responds to the request:
 
---PROG progs/server.go /type.binOp/ /^}/
+!src progs/server.go /type.binOp/ /^}/
 
-Line 14 defines the name "binOp" to be a function taking two integers and
+The type declaration makes "binOp" represent a function taking two integers and
 returning a third.
 
 The "server" routine loops forever, receiving requests and, to avoid blocking due to
 a long-running operation, starting a goroutine to do the actual work.
 
---PROG progs/server.go /func.server/ /^}/
+!src progs/server.go /func.server/ /^}/
 
 We construct a server in a familiar way, starting it and returning a channel
 connected to it:
 
---PROG progs/server.go /func.startServer/ /^}/
+!src progs/server.go /func.startServer/ /^}/
 
 Here's a simple test.  It starts a server with an addition operator and sends out
 "N" requests without waiting for the replies.  Only after all the requests are sent
 does it check the results.
 
---PROG progs/server.go /func.main/ /^}/
+!src progs/server.go /func.main/ /^}/
 
 One annoyance with this program is that it doesn't shut down the server cleanly; when "main" returns
 there are a number of lingering goroutines blocked on communication.  To solve this,
 we can provide a second, "quit" channel to the server:
 
---PROG progs/server1.go /func.startServer/ /^}/
+!src progs/server1.go /func.startServer/ /^}/
 
 It passes the quit channel to the "server" function, which uses it like this:
 
---PROG progs/server1.go /func.server/ /^}/
+!src progs/server1.go /func.server/ /^}/
 
 Inside "server", the "select" statement chooses which of the multiple communications
 listed by its cases can proceed.  If all are blocked, it waits until one can proceed; if
@@ -930,9 +926,9 @@ returns, terminating its execution.
 All that's left is to strobe the "quit" channel
 at the end of main:
 
---PROG progs/server1.go /adder,.quit/
+!src progs/server1.go /adder,.quit/
 ...
---PROG progs/server1.go /quit....true/
+!src progs/server1.go /quit....true/
 
 There's a lot more to Go programming and concurrent programming in general but this
 quick tour should give you some of the basics.
diff --git a/doc/htmlgen.go b/doc/htmlgen.go
index 3a8feb8bc2f..5318a07dcd0 100644
--- a/doc/htmlgen.go
+++ b/doc/htmlgen.go
@@ -2,46 +2,80 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Process plain text into HTML.
+// If --html is set, process plain text into HTML.
 //	- h2's are made from lines followed by a line "----\n"
-//	- tab-indented blocks become 
 blocks
+//	- tab-indented blocks become 
 blocks with the first tab deleted
 //	- blank lines become 
 marks (except inside 
 tags)
 //	- "quoted strings" become quoted strings
 
+// Lines beginning !src define pieces of program source to be
+// extracted from other files and injected as 
 blocks.
+// The syntax is simple: 1, 2, or 3 space-separated arguments:
+//
+// Whole file:
+//	!src foo.go
+// One line (here the signature of main):
+//	!src foo.go /^func.main/
+// Block of text, determined by start and end (here the body of main):
+// !src foo.go /^func.main/ /^}/
+//
+// Patterns can be /regular.expression/, a decimal number, or $
+// to signify the end of the file.
+// TODO: the regular expression cannot contain spaces; does this matter?
+
 package main
 
 import (
 	"bufio"
 	"bytes"
+	"flag"
+	"fmt"
+	"io/ioutil"
 	"log"
 	"os"
+	"regexp"
+	"strconv"
+	"strings"
+	"template"
 )
 
 var (
-	lines = make([][]byte, 0, 2000) // probably big enough; grows if not
+	html = flag.Bool("html", true, "process text into HTML")
+)
+
+var (
+	// lines holds the input and is reworked in place during processing.
+	lines = make([][]byte, 0, 20000)
 
 	empty   = []byte("")
 	newline = []byte("\n")
 	tab     = []byte("\t")
 	quote   = []byte(`"`)
-	indent  = []byte{' ', ' ', ' ', ' '}
+	indent  = []byte("    ")
 
 	sectionMarker = []byte("----\n")
 	preStart      = []byte("
")
 	preEnd        = []byte("
\n")
 	pp            = []byte("
\n")
+
+	srcPrefix = []byte("!src")
 )
 
 func main() {
+	flag.Parse()
 	read()
-	headings()
-	coalesce(preStart, foldPre)
-	coalesce(tab, foldTabs)
-	paragraphs()
-	quotes()
+	programs()
+	if *html {
+		headings()
+		coalesce(preStart, foldPre)
+		coalesce(tab, foldTabs)
+		paragraphs()
+		quotes()
+	}
 	write()
 }
 
+// read turns standard input into a slice of lines.
 func read() {
 	b := bufio.NewReader(os.Stdin)
 	for {
@@ -56,6 +90,7 @@ func read() {
 	}
 }
 
+// write puts the result on standard output.
 func write() {
 	b := bufio.NewWriter(os.Stdout)
 	for _, line := range lines {
@@ -64,8 +99,104 @@ func write() {
 	b.Flush()
 }
 
-// each time prefix is found on a line, call fold and replace
-// line with return value from fold.
+// programs injects source code from !src invocations.
+func programs() {
+	nlines := make([][]byte, 0, len(lines)*3/2)
+	for _, line := range lines {
+		if bytes.HasPrefix(line, srcPrefix) {
+			line = trim(line)[len(srcPrefix):]
+			prog := srcCommand(string(line))
+			if *html {
+				nlines = append(nlines, []byte(fmt.Sprintf("
", line)))
+			}
+			for _, l := range prog {
+				nlines = append(nlines, htmlEscape(l))
+			}
+			if *html {
+				nlines = append(nlines, preEnd)
+			}
+		} else {
+			nlines = append(nlines, line)
+		}
+	}
+	lines = nlines
+}
+
+// srcCommand processes one !src invocation.
+func srcCommand(command string) [][]byte {
+	// TODO: quoted args so we can have 'a b'?
+	args := strings.Fields(command)
+	if len(args) == 0 || len(args) > 3 {
+		log.Fatal("bad syntax for src command: %s", command)
+	}
+	file := args[0]
+	lines := bytes.SplitAfter(readFile(file), newline)
+	// File plus zero args: whole file:
+	//	!src file.go
+	if len(args) == 1 {
+		return lines
+	}
+	start := match(file, 0, lines, string(args[1]))
+	// File plus one arg: one line:
+	//	!src file.go /foo/
+	if len(args) == 2 {
+		return [][]byte{lines[start]}
+	}
+	// File plus two args: range:
+	//	!src file.go /foo/ /^}/
+	end := match(file, start, lines, string(args[2]))
+	return lines[start : end+1] // +1 to include matched line.
+}
+
+// htmlEscape makes sure input is HTML clean, if necessary.
+func htmlEscape(input []byte) []byte {
+	if !*html || bytes.IndexAny(input, `&"<>`) < 0 {
+		return input
+	}
+	var b bytes.Buffer
+	template.HTMLEscape(&b, input)
+	return b.Bytes()
+}
+
+// readFile reads and returns a file as part of !src processing.
+func readFile(name string) []byte {
+	file, err := ioutil.ReadFile(name)
+	if err != nil {
+		log.Fatal(err)
+	}
+	return file
+}
+
+// match identifies the input line that matches the pattern in a !src invocation.
+// If start>0, match lines starting there rather than at the beginning.
+func match(file string, start int, lines [][]byte, pattern string) int {
+	// $ matches the end of the file.
+	if pattern == "$" {
+		return len(lines) - 1
+	}
+	// Number matches the line.
+	if i, err := strconv.Atoi(pattern); err == nil {
+		return i - 1 // Lines are 1-indexed.
+	}
+	// /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.Match(lines[i]) {
+				return i
+			}
+		}
+		log.Fatalf("%s: no match for %s", file, pattern)
+	}
+	log.Fatalf("unrecognized pattern: %s", pattern)
+	return 0
+}
+
+// coalesce combines lines. Each time prefix is found on a line,
+// it calls fold and replaces the line with return value from fold.
 func coalesce(prefix []byte, fold func(i int) (n int, line []byte)) {
 	j := 0 // output line number goes up by one each loop
 	for i := 0; i < len(lines); {
@@ -82,7 +213,7 @@ func coalesce(prefix []byte, fold func(i int) (n int, line []byte)) {
 	lines = lines[0:j]
 }
 
-// return the 
 block as a single slice
+// foldPre returns the 
 block as a single slice.
 func foldPre(i int) (n int, line []byte) {
 	buf := new(bytes.Buffer)
 	for i < len(lines) {
@@ -96,7 +227,7 @@ func foldPre(i int) (n int, line []byte) {
 	return n, buf.Bytes()
 }
 
-// return the tab-indented block as a single 
-bounded slice
+// foldTabs returns the tab-indented block as a single 
-bounded slice.
 func foldTabs(i int) (n int, line []byte) {
 	buf := new(bytes.Buffer)
 	buf.WriteString("
\n")
@@ -104,7 +235,7 @@ func foldTabs(i int) (n int, line []byte) {
 		if !bytes.HasPrefix(lines[i], tab) {
 			break
 		}
-		buf.Write(lines[i])
+		buf.Write(lines[i][1:]) // delete leading tab.
 		n++
 		i++
 	}
@@ -112,6 +243,7 @@ func foldTabs(i int) (n int, line []byte) {
 	return n, buf.Bytes()
 }
 
+// headings turns sections into HTML sections.
 func headings() {
 	b := bufio.NewWriter(os.Stdout)
 	for i, l := range lines {
@@ -123,6 +255,7 @@ func headings() {
 	b.Flush()
 }
 
+// paragraphs turns blank lines into paragraph marks.
 func paragraphs() {
 	for i, l := range lines {
 		if bytes.Equal(l, newline) {
@@ -131,12 +264,14 @@ func paragraphs() {
 	}
 }
 
+// quotes turns "x" in the file into x.
 func quotes() {
 	for i, l := range lines {
 		lines[i] = codeQuotes(l)
 	}
 }
 
+// quotes turns "x" in the line into x.
 func codeQuotes(l []byte) []byte {
 	if bytes.HasPrefix(l, preStart) {
 		return l
@@ -162,7 +297,7 @@ func codeQuotes(l []byte) []byte {
 	return buf.Bytes()
 }
 
-// drop trailing newline
+// trim drops the trailing newline, if present.
 func trim(l []byte) []byte {
 	n := len(l)
 	if n > 0 && l[n-1] == '\n' {
@@ -171,7 +306,7 @@ func trim(l []byte) []byte {
 	return l
 }
 
-// expand tabs to spaces. don't worry about columns.
+// expandTabs expands tabs to spaces. It doesn't worry about columns.
 func expandTabs(l []byte) []byte {
 	return bytes.Replace(l, tab, indent, -1)
 }
diff --git a/doc/makehtml b/doc/makehtml
index c9ac0c8e8dd..1b8caed696c 100755
--- a/doc/makehtml
+++ b/doc/makehtml
@@ -7,7 +7,6 @@ set -e
 
 TXT=${1:-go_tutorial.txt}		# input file
 HTML=$(basename $TXT .txt).html		# output file (basename)
-TMP=TEMP.txt				# input to htmlgen
 
 if ! test -w $HTML
 then
@@ -15,17 +14,4 @@ then
 	exit 1
 fi
 
-if grep -q '^--PROG' $TXT
-then
-	echo >&2 makehtml: processing PROG sections
-	<$TXT >$TMP awk '
-		/^--PROG/ { system("sh ./prog.sh "$2" "$3" "$4" "); getline }
-		/^/ {print}
-	'
-else
-	cp $TXT $TMP
-fi
-
-make htmlgen && ./htmlgen < $TMP > $HTML
-
-rm -f $TMP
+make htmlgen && ./htmlgen < $TXT > $HTML
diff --git a/doc/prog.sh b/doc/prog.sh
deleted file mode 100755
index 6a540980aad..00000000000
--- a/doc/prog.sh
+++ /dev/null
@@ -1,72 +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.
-
-# generate HTML for a program excerpt.
-# first arg is file name
-# second arg is awk pattern to match start line
-# third arg is awk pattern to stop processing
-#
-# missing third arg means print one line
-# third arg "END" means proces rest of file
-# missing second arg means process whole file
-#
-# examples:
-#
-#	prog.sh foo.go                       # whole file
-#	prog.sh foo.go "/^func.main/"        # signature of main
-#	prog.sh foo.go "/^func.main/" "/^}/  # body of main
-#
-# non-blank lines are annotated with line number in file
-
-# line numbers are printed %.2d to make them equal-width for nice formatting.
-# the format gives a leading 0.  the format %2d gives a leading space but
-# that appears to confuse sanjay's makehtml formatter into bungling quotes
-# because it makes some lines look indented.
-
-echo "
 "
-
-case $# in
-3)
-	if test "$3" = "END"  # $2 to end of file
-	then
-		awk '
-			function LINE() { printf("%.2d\t%s\n", NR, $0) }
-			BEGIN { printing = 0 }
-			'$2' { printing = 1; LINE(); getline }
-			printing { if($0 ~ /./) { LINE() } else { print "" } }
-		'
-	else	# $2 through $3
-		awk '
-			function LINE() { printf("%.2d\t%s\n", NR, $0) }
-			BEGIN { printing = 0 }
-			'$2' { printing = 1; LINE(); getline }
-			'$3' && printing { if(printing) {printing = 0; LINE(); exit} }
-			printing { if($0 ~ /./) { LINE() } else { print "" } }
-		'
-	fi
-	;;
-2)	# one line
-	awk '
-		function LINE() { printf("%.2d\t%s\n", NR, $0) }
-		'$2' { LINE(); getline; exit }
-	'
-	;;
-1)	# whole file
-	awk '
-		function LINE() { printf("%.2d\t%s\n", NR, $0) }
-		{ if($0 ~ /./) { LINE() } else { print "" } }
-	'
-	;;
-*)
-	echo >&2 usage: prog.sh file.go /func.main/ /^}/
-esac <$1 |
-sed '
-	s/&/\&/g
-	s/"/\"/g
-	s//\>/g
-'
-
-echo '
'