[release-branch.r60] doc: document release.r60.3

««« CL 5267049 / eeca0d4a91a3
doc: document release.r60.3

R=golang-dev, dsymonds
CC=golang-dev
https://golang.org/cl/5267049
»»»

R=golang-dev, dsymonds
CC=golang-dev
https://golang.org/cl/5296041

.hgignore

@@ -41,6 +41,8 @@ src/cmd/gc/y1.tab.c
 src/cmd/gc/yerr.h
 src/cmd/goinstall/syslist.go
 src/pkg/Make.deps
+src/pkg/exp/norm/maketables
+src/pkg/exp/norm/maketesttables
 src/pkg/exp/ogle/ogle
 src/pkg/go/build/syslist.go
 src/pkg/os/signal/unix.go

.hgtags

@@ -62,6 +62,17 @@ d6903b7fbff40c13ee7ea3177c0ae54c7f89d2e6 weekly.2011-04-13
 2f0fa51fa2da6ab50fcebba526326153da8ed999 weekly.2011-04-27
 8493bb64e5592bd20c0e60e78e7f8052c1276fcf release.r57
 95d2ce135523c96c4cea049af94ce76dd8c7d981 release.r57.1
-95d2ce135523c96c4cea049af94ce76dd8c7d981 release
 c98449d685d2b6aa1df9bfd2e1cce9307efb6e00 weekly.2011-05-22
 3418f22c39eb8299053ae681199ee90f8cd29c6d weekly.2011-06-02
+c81944152e973a917797679055b8fcdc70fbc802 weekly.2011-06-09
+9d7967223815ef6415ff01aa0fe6ad38cdbc7810 release.r57.2
+dac76f0b1a18a5de5b54a1dc0b231aceaf1c8583 weekly.2011-06-16
+541c445d6c1353fbfa39df7dc4b0eb27558d1fc1 weekly.2011-06-23
+1b38d90eebcddefabb3901c5bb63c7e2b04a6ec5 release.r58
+16bfa562ba767aefd82e598da8b15ee4729e23b0 weekly.2011-07-07
+d292bc7886682d35bb391bf572be28656baee12d release.r58.1
+3c21f37b25a3f7a1726265c5339c8a7b0b329336 weekly.2011-07-19
+bb28251f6da4aca85658582c370c7df89d34efd4 weekly.2011-07-29
+d5785050f61d973fc36775f7bd2e26689529cb3e release.r59
+d5785050f61d973fc36775f7bd2e26689529cb3e release
+c17ce5ec06b4bd5cf6e7ff2ceb0a60c2e40e0b17 weekly.2011-08-10

AUTHORS

@@ -11,11 +11,13 @@
 Abhinav Gupta <abhinav.g90@gmail.com>
 Adrian O'Grady <elpollouk@gmail.com>
 Albert Strasheim <fullung@gmail.com>
+Aleksandar Dezelin <dezelin@gmail.com>
 Alex Brainman <alex.brainman@gmail.com>
 Alexander Orlov <alexander.orlov@loxal.net>
 Alexey Borzenkov <snaury@gmail.com>
 Amrut Joshi <amrut.joshi@gmail.com>
 Andrei Vieru <euvieru@gmail.com>
+Andrew Balholm <andybalholm@gmail.com>
 Andrew Skiba <skibaa@gmail.com>
 Andrey Mirtchovski <mirtchovski@gmail.com>
 Andy Davis <andy@bigandian.com>
@@ -27,6 +29,7 @@ Aron Nopanen <aron.nopanen@gmail.com>
 Arvindh Rajesh Tamilmani <art@a-30.net>
 Ben Olive <sionide21@gmail.com>
 Benny Siegert <bsiegert@gmail.com>
+Bobby Powers <bobbypowers@gmail.com>
 Caine Tighe <arctanofyourface@gmail.com>
 Charles L. Dorian <cldorian@gmail.com>
 Chris Dollin <ehog.hedge@gmail.com>
@@ -60,6 +63,7 @@ Fazlul Shahriar <fshahriar@gmail.com>
 Firmansyah Adiputra <frm.adiputra@gmail.com>
 Florian Uekermann <florian@uekermann-online.de>
 Gary Burd <gary@beagledreams.com>
+Gideon Jan-Wessel Redelinghuys <gjredelinghuys@gmail.com>
 Giles Lean <giles.lean@pobox.com>
 Google Inc.
 Graham Miller <graham.miller@gmail.com>
@@ -78,15 +82,18 @@ Jeff Hodges <jeff@somethingsimilar.com>
 Jeff R. Allen <jra@nella.org>
 Jim McGrath <jimmc2@gmail.com>
 Joe Poirier <jdpoirier@gmail.com>
+John Asmuth <jasmuth@gmail.com>
 Jonathan Mark <jhmark@xenops.com>
 Jonathan Wills <runningwild@gmail.com>
 Jose Luis Vázquez González <josvazg@gmail.com>
 Josh Goebel <dreamer3@gmail.com>
 Jukka-Pekka Kekkonen <karatepekka@gmail.com>
+Julian Phillips <julian@quantumfyre.co.uk>
 Kai Backman <kaib@golang.org>
 Kei Son <hey.calmdown@gmail.com>
 Keith Rarick <kr@xph.us>
 Ken Friedenbach <kenliz@cruzio.com>
+Ken Rockot <ken@oz.gs>
 Kevin Ballard <kevin@sb.org>
 Kyle Consalus <consalus@gmail.com>
 Kyle Lemons <kyle@kylelemons.net>
@@ -96,6 +103,7 @@ Luit van Drongelen <luitvd@gmail.com>
 Markus Duft <markus.duft@salomon.at>
 Martin Neubauer <m.ne@gmx.net>
 Mathieu Lonjaret <mathieu.lonjaret@gmail.com>
+Matthew Horsnell <matthew.horsnell@gmail.com>
 Micah Stetson <micah.stetson@gmail.com>
 Michael Elkins <michael.elkins@gmail.com>
 Michael Hoisie <hoisie@gmail.com>
@@ -105,6 +113,7 @@ Mikio Hara <mikioh.mikioh@gmail.com>
 Mikkel Krautz <mikkel@krautz.dk>
 Moriyoshi Koizumi <mozo@mozo.jp>
 Môshe van der Sterre <moshevds@gmail.com>
+ngmoco, LLC
 Nicholas Waples <nwaples@gmail.com>
 Nigel Kerr <nigel.kerr@gmail.com>
 Olivier Antoine <olivier.antoine@gmail.com>
@@ -140,6 +149,7 @@ Tor Andersson <tor.andersson@gmail.com>
 Vincent Ambo <tazjin@googlemail.com>
 Vincent Vanackere <vincent.vanackere@gmail.com>
 Vinu Rajashekhar <vinutheraj@gmail.com>
+Volker Dobler <dr.volker.dobler@gmail.com>
 Wei Guangjing <vcc.163@gmail.com>
 William Josephson <wjosephson@gmail.com>
 Yasuhiro Matsumoto <mattn.jp@gmail.com>

CONTRIBUTORS

@@ -35,11 +35,13 @@ Abhinav Gupta <abhinav.g90@gmail.com>
 Adam Langley <agl@golang.org>
 Adrian O'Grady <elpollouk@gmail.com>
 Albert Strasheim <fullung@gmail.com>
+Aleksandar Dezelin <dezelin@gmail.com>
 Alex Brainman <alex.brainman@gmail.com>
 Alexander Orlov <alexander.orlov@loxal.net>
 Alexey Borzenkov <snaury@gmail.com>
 Amrut Joshi <amrut.joshi@gmail.com>
 Andrei Vieru <euvieru@gmail.com>
+Andrew Balholm <andybalholm@gmail.com>
 Andrew Gerrand <adg@golang.org>
 Andrew Skiba <skibaa@gmail.com>
 Andrey Mirtchovski <mirtchovski@gmail.com>
@@ -58,6 +60,7 @@ Ben Olive <sionide21@gmail.com>
 Benny Siegert <bsiegert@gmail.com>
 Berengar Lehr <Berengar.Lehr@gmx.de>
 Bill Neubauer <wcn@golang.org> <wcn@google.com>
+Bobby Powers <bobbypowers@gmail.com>
 Brad Fitzpatrick <bradfitz@golang.org> <bradfitz@gmail.com>
 Brendan O'Dea <bod@golang.org>
 Caine Tighe <arctanofyourface@gmail.com>
@@ -77,6 +80,7 @@ Daniel Fleischman <danielfleischman@gmail.com>
 Daniel Nadasi <dnadasi@google.com>
 Daniel Theophanes <kardianos@gmail.com>
 Dave Cheney <dave@cheney.net>
+Dave Grijalva <dgrijalva@ngmoco.com>
 David Anderson <danderson@google.com>
 David Crawshaw <david.crawshaw@zentus.com>
 David Forsythe <dforsythe@gmail.com>
@@ -93,6 +97,7 @@ Eivind Uggedal <eivind@uggedal.com>
 Eoghan Sherry <ejsherry@gmail.com>
 Eric Clark <zerohp@gmail.com>
 Eric Eisner <eric.d.eisner@gmail.com>
+Evan Martin <evan.martin@gmail.com>
 Evan Shaw <chickencha@gmail.com>
 Fan Hongjian <fan.howard@gmail.com>
 Fazlul Shahriar <fshahriar@gmail.com>
@@ -100,6 +105,7 @@ Firmansyah Adiputra <frm.adiputra@gmail.com>
 Florian Uekermann <florian@uekermann-online.de> <f1@uekermann-online.de>
 Fumitoshi Ukai <ukai@google.com>
 Gary Burd <gary@beagledreams.com> <gary.burd@gmail.com>
+Gideon Jan-Wessel Redelinghuys <gjredelinghuys@gmail.com>
 Giles Lean <giles.lean@pobox.com>
 Graham Miller <graham.miller@gmail.com>
 Gustavo Niemeyer <gustavo@niemeyer.net> <n13m3y3r@gmail.com>
@@ -122,7 +128,9 @@ Jeff Hodges <jeff@somethingsimilar.com>
 Jeff R. Allen <jra@nella.org> <jeff.allen@gmail.com>
 Jim McGrath <jimmc2@gmail.com>
 Joe Poirier <jdpoirier@gmail.com>
+Joel Sing <jsing@google.com>
 Johan Euphrosine <proppy@google.com>
+John Asmuth <jasmuth@gmail.com>
 John DeNero <denero@google.com>
 Jonathan Allie <jonallie@google.com>
 Jonathan Mark <jhmark@xenops.com> <jhmark000@gmail.com>
@@ -131,25 +139,29 @@ Jos Visser <josv@google.com>
 Jose Luis Vázquez González <josvazg@gmail.com>
 Josh Goebel <dreamer3@gmail.com>
 Jukka-Pekka Kekkonen <karatepekka@gmail.com>
+Julian Phillips <julian@quantumfyre.co.uk>
 Kai Backman <kaib@golang.org>
 Kei Son <hey.calmdown@gmail.com>
 Keith Rarick <kr@xph.us>
 Ken Friedenbach <kenliz@cruzio.com>
+Ken Rockot <ken@oz.gs> <ken.rockot@gmail.com>
 Ken Thompson <ken@golang.org>
 Kevin Ballard <kevin@sb.org>
 Kirklin McDonald <kirklin.mcdonald@gmail.com>
 Kyle Consalus <consalus@gmail.com>
-Kyle Lemons <kyle@kylelemons.net> <etherealflaim@gmail.com>
+Kyle Lemons <kyle@kylelemons.net> <kevlar@google.com>
 Larry Hosken <lahosken@golang.org>
 Lorenzo Stoakes <lstoakes@gmail.com>
 Lucio De Re <lucio.dere@gmail.com>
 Luit van Drongelen <luitvd@gmail.com>
 Luuk van Dijk <lvd@golang.org> <lvd@google.com>
+Marcel van Lohuizen <mpvl@golang.org>
 Mark Zavislak <zavislak@google.com>
 Markus Duft <markus.duft@salomon.at>
 Martin Neubauer <m.ne@gmx.net>
 Mathieu Lonjaret <mathieu.lonjaret@gmail.com>
 Matt Jones <mrjones@google.com>
+Matthew Horsnell <matthew.horsnell@gmail.com>
 Maxim Ushakov <ushakov@google.com>
 Micah Stetson <micah.stetson@gmail.com>
 Michael Elkins <michael.elkins@gmail.com>
@@ -157,6 +169,8 @@ Michael Hoisie <hoisie@gmail.com>
 Michael T. Jones <mtj@google.com> <michael.jones@gmail.com>
 Miek Gieben <miek@miek.nl> <remigius.gieben@gmail.com>
 Mikael Tillenius <mikti42@gmail.com>
+Mike Samuel <mikesamuel@gmail.com>
+Mike Solomon <msolo@gmail.com>
 Mikio Hara <mikioh.mikioh@gmail.com>
 Mikkel Krautz <mikkel@krautz.dk> <krautz@gmail.com>
 Moriyoshi Koizumi <mozo@mozo.jp>
@@ -169,6 +183,7 @@ Padraig Kitterick <padraigkitterick@gmail.com>
 Paolo Giarrusso <p.giarrusso@gmail.com>
 Pascal S. de Kloe <pascal@quies.net>
 Patrick Gavlin <pgavlin@gmail.com>
+Paul Borman <borman@google.com>
 Petar Maymounkov <petarm@gmail.com>
 Peter Froehlich <peter.hans.froehlich@gmail.com>
 Peter McKenzie <petermck@google.com>
@@ -201,6 +216,7 @@ Spring Mc <heresy.mc@gmail.com>
 Stefan Nilsson <snilsson@nada.kth.se>
 Stephen Ma <stephenm@golang.org>
 Stephen Weinberg <stephen@q5comm.com>
+Sugu Sougoumarane <ssougou@gmail.com>
 Sven Almgren <sven@tras.se>
 Tarmigan Casebolt <tarmigan@gmail.com>
 Timo Savola <timo.savola@gmail.com>
@@ -211,6 +227,7 @@ Vincent Ambo <tazjin@googlemail.com>
 Vincent Vanackere <vincent.vanackere@gmail.com>
 Vinu Rajashekhar <vinutheraj@gmail.com>
 Vish Subramanian <vish@google.com>
+Volker Dobler <dr.volker.dobler@gmail.com>
 Wei Guangjing <vcc.163@gmail.com>
 William Chan <willchan@chromium.org>
 William Josephson <wjosephson@gmail.com>

doc/Makefile

@@ -4,8 +4,8 @@
 
 include ../src/Make.inc
 
-TARG=htmlgen
+TARG=tmpltohtml
 GOFILES=\
-	htmlgen.go\
+	tmpltohtml.go\
 
 include ../src/Make.cmd

doc/all.css

@@ -135,7 +135,6 @@ h1#title {
   clear: both;
 }
 #content h1 {
-  margin-bottom: -0em;
   padding: 0;
 }
 #content h2 {

doc/codelab/wiki/edit.html

@@ -1,6 +1,6 @@
-<h1>Editing {Title}</h1>
+<h1>Editing {{.Title |html}}</h1>
 
-<form action="/save/{Title}" method="POST">
-<div><textarea name="body" rows="20" cols="80">{Body|html}</textarea></div>
+<form action="/save/{{.Title |html}}" method="POST">
+<div><textarea name="body" rows="20" cols="80">{{printf "%s" .Body |html}}</textarea></div>
 <div><input type="submit" value="Save"></div>
 </form>

doc/codelab/wiki/final-noclosure.go

@@ -68,7 +68,7 @@ func saveHandler(w http.ResponseWriter, r *http.Request) {
 }
 
 func renderTemplate(w http.ResponseWriter, tmpl string, p *Page) {
-	t, err := template.ParseFile(tmpl+".html", nil)
+	t, err := template.ParseFile(tmpl+".html")
 	if err != nil {
 		http.Error(w, err.String(), http.StatusInternalServerError)
 		return

doc/codelab/wiki/final-noerror.go

@@ -34,14 +34,14 @@ func editHandler(w http.ResponseWriter, r *http.Request) {
 	if err != nil {
 		p = &Page{Title: title}
 	}
-	t, _ := template.ParseFile("edit.html", nil)
+	t, _ := template.ParseFile("edit.html")
 	t.Execute(w, p)
 }
 
 func viewHandler(w http.ResponseWriter, r *http.Request) {
 	title := r.URL.Path[lenPath:]
 	p, _ := loadPage(title)
-	t, _ := template.ParseFile("view.html", nil)
+	t, _ := template.ParseFile("view.html")
 	t.Execute(w, p)
 }
 

doc/codelab/wiki/final.go

@@ -59,7 +59,8 @@ var templates = make(map[string]*template.Template)
 
 func init() {
 	for _, tmpl := range []string{"edit", "view"} {
-		templates[tmpl] = template.MustParseFile(tmpl+".html", nil)
+		t := template.Must(template.ParseFile(tmpl+".html"))
+		templates[tmpl] = t
 	}
 }
 

doc/codelab/wiki/htmlify.go

@@ -1,12 +1,12 @@
 package main
 
 import (
-	"os"
 	"template"
+	"os"
 	"io/ioutil"
 )
 
 func main() {
 	b, _ := ioutil.ReadAll(os.Stdin)
-	template.HTMLFormatter(os.Stdout, "", b)
+	template.HTMLEscape(os.Stdout, b)
 }

doc/codelab/wiki/index.html

@@ -429,7 +429,9 @@ Of course, there is a better way.
 <h2>The <code>template</code> package</h2>
 
 <p>
-The <code>template</code> package is part of the Go standard library.  We can
+The <code>template</code> package is part of the Go standard library.
+(A new template package is coming; this code lab will be updated soon.)
+We can
 use <code>template</code> to keep the HTML in a separate file, allowing
 us to change the layout of our edit page without modifying the underlying Go
 code.
@@ -454,10 +456,10 @@ Open a new file named <code>edit.html</code>, and add the following lines:
 </p>
 
 <pre>
-&lt;h1&gt;Editing {Title}&lt;/h1&gt;
+&lt;h1&gt;Editing {{.Title |html}}&lt;/h1&gt;
 
-&lt;form action=&#34;/save/{Title}&#34; method=&#34;POST&#34;&gt;
-&lt;div&gt;&lt;textarea name=&#34;body&#34; rows=&#34;20&#34; cols=&#34;80&#34;&gt;{Body|html}&lt;/textarea&gt;&lt;/div&gt;
+&lt;form action=&#34;/save/{{.Title |html}}&#34; method=&#34;POST&#34;&gt;
+&lt;div&gt;&lt;textarea name=&#34;body&#34; rows=&#34;20&#34; cols=&#34;80&#34;&gt;{{printf &#34;%s&#34; .Body |html}}&lt;/textarea&gt;&lt;/div&gt;
 &lt;div&gt;&lt;input type=&#34;submit&#34; value=&#34;Save&#34;&gt;&lt;/div&gt;
 &lt;/form&gt;
 </pre>
@@ -474,7 +476,7 @@ func editHandler(w http.ResponseWriter, r *http.Request) {
 	if err != nil {
 		p = &amp;Page{Title: title}
 	}
-	t, _ := template.ParseFile(&#34;edit.html&#34;, nil)
+	t, _ := template.ParseFile(&#34;edit.html&#34;)
 	t.Execute(w, p)
 }
 </pre>
@@ -485,19 +487,21 @@ The function <code>template.ParseFile</code> will read the contents of
 </p>
 
 <p>
-The method <code>t.Execute</code> replaces all occurrences of 
-<code>{Title}</code> and <code>{Body}</code> with the values of 
-<code>p.Title</code> and <code>p.Body</code>, and writes the resultant
-HTML to the <code>http.ResponseWriter</code>.
+The method <code>t.Execute</code> executes the template, writing the
+generated HTML to the <code>http.ResponseWriter</code>.
+The <code>.Title</code> and <code>.Body</code> dotted identifiers refer to
+<code>p.Title</code> and <code>p.Body</code>.
 </p>
 
 <p>
-Note that we've used <code>{Body|html}</code> in the above template.  
-The <code>|html</code> part asks the template engine to pass the value
-<code>Body</code> through the <code>html</code> formatter before outputting it,
-which escapes HTML characters (such as replacing <code>&gt;</code> with 
-<code>&amp;gt;</code>). 
-This will prevent user data from corrupting the form HTML. 
+Template directives are enclosed in double curly braces.
+The <code>printf "%s" .Body</code> instruction is a function call
+that outputs <code>.Body</code> as a string instead of a stream of bytes,
+the same as a call to <code>fmt.Printf</code>.
+The <code>|html</code> part of each directive pipes the value through the
+<code>html</code> formatter before outputting it, which escapes HTML
+characters (such as replacing <code>&gt;</code> with <code>&amp;gt;</code>),
+preventing user data from corrupting the form HTML. 
 </p>
 
 <p>
@@ -511,11 +515,11 @@ While we're working with templates, let's create a template for our
 </p>
 
 <pre>
-&lt;h1&gt;{Title}&lt;/h1&gt;
+&lt;h1&gt;{{.Title |html}}&lt;/h1&gt;
 
-&lt;p&gt;[&lt;a href=&#34;/edit/{Title}&#34;&gt;edit&lt;/a&gt;]&lt;/p&gt;
+&lt;p&gt;[&lt;a href=&#34;/edit/{{.Title |html}}&#34;&gt;edit&lt;/a&gt;]&lt;/p&gt;
 
-&lt;div&gt;{Body}&lt;/div&gt;
+&lt;div&gt;{{printf &#34;%s&#34; .Body |html}}&lt;/div&gt;
 </pre>
 
 <p>
@@ -526,7 +530,7 @@ Modify <code>viewHandler</code> accordingly:
 func viewHandler(w http.ResponseWriter, r *http.Request) {
 	title := r.URL.Path[lenPath:]
 	p, _ := loadPage(title)
-	t, _ := template.ParseFile(&#34;view.html&#34;, nil)
+	t, _ := template.ParseFile(&#34;view.html&#34;)
 	t.Execute(w, p)
 }
 </pre>
@@ -706,16 +710,17 @@ var templates = make(map[string]*template.Template)
 <p>
 Then we create an <code>init</code> function, which will be called before
 <code>main</code> at program initialization. The function
-<code>template.MustParseFile</code> is a convenience wrapper around
-<code>ParseFile</code> that does not return an error code; instead, it panics
-if an error is encountered. A panic is appropriate here; if the templates can't
-be loaded the only sensible thing to do is exit the program.
+<code>template.Must</code> is a convenience wrapper that panics when passed a
+non-nil <code>os.Error</code> value, and otherwise returns the
+<code>*Template</code> unaltered. A panic is appropriate here; if the templates
+can't be loaded the only sensible thing to do is exit the program.
 </p>
 
 <pre>
 func init() {
 	for _, tmpl := range []string{&#34;edit&#34;, &#34;view&#34;} {
-		templates[tmpl] = template.MustParseFile(tmpl+&#34;.html&#34;, nil)
+		t := template.Must(template.ParseFile(tmpl + &#34;.html&#34;))
+		templates[tmpl] = t
 	}
 }
 </pre>
@@ -761,10 +766,9 @@ var titleValidator = regexp.MustCompile(&#34;^[a-zA-Z0-9]+$&#34;)
 <p>
 The function <code>regexp.MustCompile</code> will parse and compile the 
 regular expression, and return a <code>regexp.Regexp</code>. 
-<code>MustCompile</code>, like <code>template.MustParseFile</code>,
-is distinct from <code>Compile</code> in that it will panic if 
-the expression compilation fails, while <code>Compile</code> returns an 
-<code>os.Error</code> as a second parameter. 
+<code>MustCompile</code> is distinct from <code>Compile</code> in that it will
+panic if the expression compilation fails, while <code>Compile</code> returns
+an <code>os.Error</code> as a second parameter. 
 </p>
 
 <p>

doc/codelab/wiki/srcextract.go

@@ -8,8 +8,8 @@ import (
 	"go/ast"
 	"go/token"
 	"log"
-	"os"
 	"template"
+	"os"
 )
 
 var (

doc/codelab/wiki/view.html

@@ -1,5 +1,5 @@
-<h1>{Title}</h1>
+<h1>{{.Title |html}}</h1>
 
-<p>[<a href="/edit/{Title}">edit</a>]</p>
+<p>[<a href="/edit/{{.Title |html}}">edit</a>]</p>
 
-<div>{Body}</div>
+<div>{{printf "%s" .Body |html}}</div>

doc/codelab/wiki/wiki.html

@@ -369,7 +369,9 @@ Of course, there is a better way.
 <h2>The <code>template</code> package</h2>
 
 <p>
-The <code>template</code> package is part of the Go standard library.  We can
+The <code>template</code> package is part of the Go standard library.
+(A new template package is coming; this code lab will be updated soon.)
+We can
 use <code>template</code> to keep the HTML in a separate file, allowing
 us to change the layout of our edit page without modifying the underlying Go
 code.
@@ -412,19 +414,21 @@ The function <code>template.ParseFile</code> will read the contents of
 </p>
 
 <p>
-The method <code>t.Execute</code> replaces all occurrences of 
-<code>{Title}</code> and <code>{Body}</code> with the values of 
-<code>p.Title</code> and <code>p.Body</code>, and writes the resultant
-HTML to the <code>http.ResponseWriter</code>.
+The method <code>t.Execute</code> executes the template, writing the
+generated HTML to the <code>http.ResponseWriter</code>.
+The <code>.Title</code> and <code>.Body</code> dotted identifiers refer to
+<code>p.Title</code> and <code>p.Body</code>.
 </p>
 
 <p>
-Note that we've used <code>{Body|html}</code> in the above template.  
-The <code>|html</code> part asks the template engine to pass the value
-<code>Body</code> through the <code>html</code> formatter before outputting it,
-which escapes HTML characters (such as replacing <code>&gt;</code> with 
-<code>&amp;gt;</code>). 
-This will prevent user data from corrupting the form HTML. 
+Template directives are enclosed in double curly braces.
+The <code>printf "%s" .Body</code> instruction is a function call
+that outputs <code>.Body</code> as a string instead of a stream of bytes,
+the same as a call to <code>fmt.Printf</code>.
+The <code>|html</code> part of each directive pipes the value through the
+<code>html</code> formatter before outputting it, which escapes HTML
+characters (such as replacing <code>&gt;</code> with <code>&amp;gt;</code>),
+preventing user data from corrupting the form HTML. 
 </p>
 
 <p>
@@ -570,10 +574,10 @@ our <code>*Template</code> values, keyed by <code>string</code>
 <p>
 Then we create an <code>init</code> function, which will be called before
 <code>main</code> at program initialization. The function
-<code>template.MustParseFile</code> is a convenience wrapper around
-<code>ParseFile</code> that does not return an error code; instead, it panics
-if an error is encountered. A panic is appropriate here; if the templates can't
-be loaded the only sensible thing to do is exit the program.
+<code>template.Must</code> is a convenience wrapper that panics when passed a
+non-nil <code>os.Error</code> value, and otherwise returns the
+<code>*Template</code> unaltered. A panic is appropriate here; if the templates
+can't be loaded the only sensible thing to do is exit the program.
 </p>
 
 <pre>
@@ -616,10 +620,9 @@ Then we can create a global variable to store our validation regexp:
 <p>
 The function <code>regexp.MustCompile</code> will parse and compile the 
 regular expression, and return a <code>regexp.Regexp</code>. 
-<code>MustCompile</code>, like <code>template.MustParseFile</code>,
-is distinct from <code>Compile</code> in that it will panic if 
-the expression compilation fails, while <code>Compile</code> returns an 
-<code>os.Error</code> as a second parameter. 
+<code>MustCompile</code> is distinct from <code>Compile</code> in that it will
+panic if the expression compilation fails, while <code>Compile</code> returns
+an <code>os.Error</code> as a second parameter. 
 </p>
 
 <p>

doc/codewalk/markov.go

@@ -0,0 +1,130 @@
+// 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.
+
+/*
+Generating random text: a Markov chain algorithm
+
+Based on the program presented in the "Design and Implementation" chapter
+of The Practice of Programming (Kernighan and Pike, Addison-Wesley 1999).
+See also Computer Recreations, Scientific American 260, 122 - 125 (1989).
+
+A Markov chain algorithm generates text by creating a statistical model of
+potential textual suffixes for a given prefix. Consider this text:
+
+	I am not a number! I am a free man!
+
+Our Markov chain algorithm would arrange this text into this set of prefixes
+and suffixes, or "chain": (This table assumes a prefix length of two words.)
+
+	Prefix       Suffix
+
+	"" ""        I
+	"" I         am
+	I am         a
+	I am         not
+	a free       man!
+	am a         free
+	am not       a
+	a number!    I
+	number! I    am
+	not a        number!
+
+To generate text using this table we select an initial prefix ("I am", for
+example), choose one of the suffixes associated with that prefix at random
+with probability determined by the input statistics ("a"),
+and then create a new prefix by removing the first word from the prefix
+and appending the suffix (making the new prefix is "am a"). Repeat this process
+until we can't find any suffixes for the current prefix or we exceed the word
+limit. (The word limit is necessary as the chain table may contain cycles.)
+
+Our version of this program reads text from standard input, parsing it into a
+Markov chain, and writes generated text to standard output.
+The prefix and output lengths can be specified using the -prefix and -words
+flags on the command-line.
+*/
+package main
+
+import (
+	"bufio"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"rand"
+	"strings"
+	"time"
+)
+
+// Prefix is a Markov chain prefix of one or more words.
+type Prefix []string
+
+// String returns the Prefix as a string (for use as a map key).
+func (p Prefix) String() string {
+	return strings.Join(p, " ")
+}
+
+// Shift removes the first word from the Prefix and appends the given word.
+func (p Prefix) Shift(word string) {
+	copy(p, p[1:])
+	p[len(p)-1] = word
+}
+
+// Chain contains a map ("chain") of prefixes to a list of suffixes.
+// A prefix is a string of prefixLen words joined with spaces.
+// A suffix is a single word. A prefix can have multiple suffixes.
+type Chain struct {
+	chain     map[string][]string
+	prefixLen int
+}
+
+// NewChain returns a new Chain with prefixes of prefixLen words.
+func NewChain(prefixLen int) *Chain {
+	return &Chain{make(map[string][]string), prefixLen}
+}
+
+// Build reads text from the provided Reader and
+// parses it into prefixes and suffixes that are stored in Chain.
+func (c *Chain) Build(r io.Reader) {
+	br := bufio.NewReader(r)
+	p := make(Prefix, c.prefixLen)
+	for {
+		var s string
+		if _, err := fmt.Fscan(br, &s); err != nil {
+			break
+		}
+		key := p.String()
+		c.chain[key] = append(c.chain[key], s)
+		p.Shift(s)
+	}
+}
+
+// Generate returns a string of at most n words generated from Chain.
+func (c *Chain) Generate(n int) string {
+	p := make(Prefix, c.prefixLen)
+	var words []string
+	for i := 0; i < n; i++ {
+		choices := c.chain[p.String()]
+		if len(choices) == 0 {
+			break
+		}
+		next := choices[rand.Intn(len(choices))]
+		words = append(words, next)
+		p.Shift(next)
+	}
+	return strings.Join(words, " ")
+}
+
+func main() {
+	// Register command-line flags.
+	numWords := flag.Int("words", 100, "maximum number of words to print")
+	prefixLen := flag.Int("prefix", 2, "prefix length in words")
+
+	flag.Parse()                  // Parse command-line flags.
+	rand.Seed(time.Nanoseconds()) // Seed the random number generator.
+
+	c := NewChain(*prefixLen)     // Initialize a new Chain.
+	c.Build(os.Stdin)             // Build chains from standard input.
+	text := c.Generate(*numWords) // Generate text.
+	fmt.Println(text)             // Write text to standard output.
+}

doc/codewalk/markov.xml

@@ -0,0 +1,308 @@
+<!--
+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.
+-->
+
+<codewalk title="Generating arbitrary text: a Markov chain algorithm">
+
+<step title="Introduction" src="doc/codewalk/markov.go:/Generating/,/line\./">
+	This codewalk describes a program that generates random text using
+	a Markov chain algorithm. The package comment describes the algorithm
+	and the operation of the program. Please read it before continuing.
+</step>
+
+<step title="Modeling Markov chains" src="doc/codewalk/markov.go:/	chain/">
+	A chain consists of a prefix and a suffix. Each prefix is a set
+	number of words, while a suffix is a single word.
+	A prefix can have an arbitrary number of suffixes.
+	To model this data, we use a <code>map[string][]string</code>.
+	Each map key is a prefix (a <code>string</code>) and its values are
+	lists of suffixes (a slice of strings, <code>[]string</code>).
+	<br/><br/>
+	Here is the example table from the package comment
+	as modeled by this data structure:
+	<pre>
+map[string][]string{
+	" ":          {"I"},
+	" I":         {"am"},
+	"I am":       {"a", "not"},
+	"a free":     {"man!"},
+	"am a":       {"free"},
+	"am not":     {"a"},
+	"a number!":  {"I"},
+	"number! I":  {"am"},
+	"not a":      {"number!"},
+}</pre>
+	While each prefix consists of multiple words, we
+	store prefixes in the map as a single <code>string</code>.
+	It would seem more natural to store the prefix as a
+	<code>[]string</code>, but we can't do this with a map because the
+	key type of a map must implement equality (and slices do not).
+	<br/><br/>
+	Therefore, in most of our code we will model prefixes as a
+	<code>[]string</code> and join the strings together with a space
+	to generate the map key:
+	<pre>
+Prefix               Map key
+
+[]string{"", ""}     " "
+[]string{"", "I"}    " I"
+[]string{"I", "am"}  "I am"
+</pre>
+</step>
+
+<step title="The Chain struct" src="doc/codewalk/markov.go:/type Chain/,/}/">
+	The complete state of the chain table consists of the table itself and
+	the word length of the prefixes. The <code>Chain</code> struct stores
+	this data.
+</step>
+
+<step title="The NewChain constructor function" src="doc/codewalk/markov.go:/func New/,/}/">
+	The <code>Chain</code> struct has two unexported fields (those that
+	do not begin with an upper case character), and so we write a
+	<code>NewChain</code> constructor function that initializes the
+	<code>chain</code> map with <code>make</code> and sets the
+	<code>prefixLen</code> field.
+	<br/><br/>
+	This is constructor function is not strictly necessary as this entire
+	program is within a single package (<code>main</code>) and therefore
+	there is little practical difference between exported and unexported
+	fields. We could just as easily write out the contents of this function
+	when we want to construct a new Chain.
+	But using these unexported fields is good practice; it clearly denotes
+	that only methods of Chain and its constructor function should access
+	those fields. Also, structuring <code>Chain</code> like this means we
+	could easily move it into its own package at some later date.
+</step>
+
+<step title="The Prefix type" src="doc/codewalk/markov.go:/type Prefix/">
+	Since we'll be working with prefixes often, we define a
+	<code>Prefix</code> type with the concrete type <code>[]string</code>.
+	Defining a named type clearly allows us to be explicit when we are
+	working with a prefix instead of just a <code>[]string</code>.
+	Also, in Go we can define methods on any named type (not just structs),
+	so we can add methods that operate on <code>Prefix</code> if we need to.
+</step>
+
+<step title="The String method" src="doc/codewalk/markov.go:/func[^\n]+String/,/}/">
+	The first method we define on <code>Prefix</code> is
+	<code>String</code>. It returns a <code>string</code> representation
+	of a <code>Prefix</code> by joining the slice elements together with
+	spaces. We will use this method to generate keys when working with
+	the chain map.
+</step>
+
+<step title="Building the chain" src="doc/codewalk/markov.go:/func[^\n]+Build/,/\n}/">
+	The <code>Build</code> method reads text from an <code>io.Reader</code>
+	and parses it into prefixes and suffixes that are stored in the
+	<code>Chain</code>.
+	<br/><br/>
+	The <code><a href="/pkg/io/#Reader">io.Reader</a></code> is an
+	interface type that is widely used by the standard library and
+	other Go code. Our code uses the
+	<code><a href="/pkg/fmt/#Fscan">fmt.Fscan</a></code> function, which
+	reads space-separated values from an <code>io.Reader</code>.
+	<br/><br/>
+	The <code>Build</code> method returns once the <code>Reader</code>'s
+	<code>Read</code> method returns <code>os.EOF</code> (end of file)
+	or some other read error occurs.
+</step>
+
+<step title="Buffering the input" src="doc/codewalk/markov.go:/bufio\.NewReader/">
+	This function does many small reads, which can be inefficient for some
+	<code>Readers</code>. For efficiency we wrap the provided
+	<code>io.Reader</code> with
+	<code><a href="/pkg/bufio/">bufio.NewReader</a></code> to create a
+	new <code>io.Reader</code> that provides buffering.
+</step>
+
+<step title="The Prefix variable" src="doc/codewalk/markov.go:/make\(Prefix/">
+	At the top of the function we make a <code>Prefix</code> slice
+	<code>p</code> using the <code>Chain</code>'s <code>prefixLen</code>
+	field as its length.
+	We'll use this variable to hold the current prefix and mutate it with
+	each new word we encounter.
+</step>
+
+<step title="Scanning words" src="doc/codewalk/markov.go:/var s string/,/\n		}/">
+	In our loop we read words from the <code>Reader</code> into a
+	<code>string</code> variable <code>s</code> using
+	<code>fmt.Fscan</code>. Since <code>Fscan</code> uses space to
+	separate each input value, each call will yield just one word
+	(including punctuation), which is exactly what we need.
+	<br/><br/>
+	<code>Fscan</code> returns an error if it encounters a read error
+	(<code>os.EOF</code>, for example) or if it can't scan the requested
+	value (in our case, a single string). In either case we just want to
+	stop scanning, so we <code>break</code> out of the loop.
+</step>
+
+<step title="Adding a prefix and suffix to the chain" src="doc/codewalk/markov.go:/	key/,/key\], s\)">
+	The word stored in <code>s</code> is a new suffix. We add the new
+	prefix/suffix combination to the <code>chain</code> map by computing
+	the map key with <code>p.String</code> and appending the suffix
+	to the slice stored under that key.
+	<br/><br/>
+	The built-in <code>append</code> function appends elements to a slice
+	and allocates new storage when necessary. When the provided slice is
+	<code>nil</code>, <code>append</code> allocates a new slice.
+	This behavior conveniently ties in with the semantics of our map:
+	retrieving an unset key returns the zero value of the value type and
+	the zero value of <code>[]string</code> is <code>nil</code>.
+	When our program encounters a new prefix (yielding a <code>nil</code>
+	value in the map) <code>append</code> will allocate a new slice.
+	<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.
+</step>
+
+<step title="Pushing the suffix onto the prefix" src="doc/codewalk/markov.go:/p\.Shift/">
+	Before reading the next word our algorithm requires us to drop the
+	first word from the prefix and push the current suffix onto the prefix.
+	<br/><br/>
+	When in this state
+	<pre>
+p == Prefix{"I", "am"}
+s == "not" </pre>
+	the new value for <code>p</code> would be
+	<pre>
+p == Prefix{"am", "not"}</pre>
+	This operation is also required during text generation so we put
+	the code to perform this mutation of the slice inside a method on
+	<code>Prefix</code> named <code>Shift</code>.
+</step>
+
+<step title="The Shift method" src="doc/codewalk/markov.go:/func[^\n]+Shift/,/\n}/">
+	The <code>Shift</code> method uses the built-in <code>copy</code>
+	function to copy the last len(p)-1 elements of <code>p</code> to
+	the start of the slice, effectively moving the elements
+	one index to the left (if you consider zero as the leftmost index).
+	<pre>
+p := Prefix{"I", "am"}
+copy(p, p[:1])
+// p == Prefix{"am", "am"}</pre>
+	We then assign the provided <code>word</code> to the last index
+	of the slice:
+	<pre>
+// suffix == "not"
+p[len(p)-1] = suffix
+// p == Prefix{"am", "not"}</pre>
+</step>
+
+<step title="Generating text" src="doc/codewalk/markov.go:/func[^\n]+Generate/,/\n}/">
+	The <code>Generate</code> method is similar to <code>Build</code>
+	except that instead of reading words from a <code>Reader</code>
+	and storing them in a map, it reads words from the map and
+	appends them to a slice (<code>words</code>).
+	<br/><br/>
+	<code>Generate</code> uses a conditional for loop to generate
+	up to <code>n</code> words.
+</step>
+
+<step title="Getting potential suffixes" src="doc/codewalk/markov.go:/choices/,/}\n/">
+	At each iteration of the loop we retrieve a list of potential suffixes
+	for the current prefix. We access the <code>chain</code> map at key
+	<code>p.String()</code> and assign its contents to <code>choices</code>.
+	<br/><br/>
+	If <code>len(choices)</code> is zero we break out of the loop as there
+	are no potential suffixes for that prefix.
+	This test also works if the key isn't present in the map at all:
+	in that case, <code>choices</code> will be <code>nil</code> and the
+	length of a <code>nil</code> slice is zero.
+</step>
+
+<step title="Choosing a suffix at random" src="doc/codewalk/markov.go:/next := choices/,/Shift/">
+	To choose a suffix we use the
+	<code><a href="/pkg/rand/#Intn">rand.Intn</a></code> function.
+	It returns a random integer up to (but not including) the provided
+	value. Passing in <code>len(choices)</code> gives us a random index
+	into the full length of the list.
+	<br/><br/>
+	We use that index to pick our new suffix, assign it to
+	<code>next</code> and append it to the <code>words</code> slice.
+	<br/><br/>
+	Next, we <code>Shift</code> the new suffix onto the prefix just as
+	we did in the <code>Build</code> method.
+</step>
+
+<step title="Returning the generated text" src="doc/codewalk/markov.go:/Join\(words/">
+	Before returning the generated text as a string, we use the
+	<code>strings.Join</code> function to join the elements of
+	the <code>words</code> slice together, separated by spaces.
+</step>
+
+<step title="Command-line flags" src="doc/codewalk/markov.go:/Register command-line flags/,/prefixLen/">
+	To make it easy to tweak the prefix and generated text lengths we
+	use the <code><a href="/pkg/flag/">flag</a></code> package to parse
+	command-line flags.
+	<br/><br/>
+	These calls to <code>flag.Int</code> register new flags with the
+	<code>flag</code> package. The arguments to <code>Int</code> are the
+	flag name, its default value, and a description. The <code>Int</code>
+	function returns a pointer to an integer that will contain the
+	user-supplied value (or the default value if the flag was omitted on
+	the command-line).
+</step>
+
+<step title="Program set up" src="doc/codewalk/markov.go:/flag.Parse/,/rand.Seed/">
+	The <code>main</code> function begins by parsing the command-line
+	flags with <code>flag.Parse</code> and seeding the <code>rand</code>
+	package's random number generator with the current time.
+	<br/><br/>
+	If the command-line flags provided by the user are invalid the
+	<code>flag.Parse</code> function will print an informative usage
+	message and terminate the program.
+</step>
+
+<step title="Creating and building a new Chain" src="doc/codewalk/markov.go:/c := NewChain/,/c\.Build/">
+	To create the new <code>Chain</code> we call <code>NewChain</code>
+	with the value of the <code>prefix</code> flag.
+	<br/><br/>
+	To build the chain we call <code>Build</code> with
+	<code>os.Stdin</code> (which implements <code>io.Reader</code>) so
+	that it will read its input from standard input.
+</step>
+
+<step title="Generating and printing text" src="doc/codewalk/markov.go:/c\.Generate/,/fmt.Println/">
+	Finally, to generate text we call <code>Generate</code> with
+	the value of the <code>words</code> flag and assigning the result
+	to the variable <code>text</code>.
+	<br/><br/>
+	Then we call <code>fmt.Println</code> to write the text to standard
+	output, followed by a carriage return.
+</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:
+	<pre>
+$ 6g markov.go &amp;&amp; 6l -o markov markov.6</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>
+	Here's a transcript of generating some text using the Go distribution's
+	README file as source material:
+	<pre>
+$ ./markov -words=10 &lt $GOROOT/go/README
+This is the source code repository for the Go source
+$ ./markov -prefix=1 -words=10 &lt $GOROOT/go/README
+This is the go directory (the one containing this README).
+$ ./markov -prefix=1 -words=10 &lt $GOROOT/go/README
+This is the variable if you have just untarred a</pre>
+</step>
+
+<step title="An exercise for the reader" src="doc/codewalk/markov.go">
+	The <code>Generate</code> function does a lot of allocations when it
+	builds the <code>words</code> slice. As an exercise, modify it to
+	take an <code>io.Writer</code> to which it incrementally writes the
+	generated text with <code>Fprint</code>.
+	Aside from being more efficient this makes <code>Generate</code>
+	more symmetrical to <code>Build</code>.
+</step>
+
+</codewalk>

doc/debugging_with_gdb.html

@@ -0,0 +1,479 @@
+<!-- title Debugging Go Code with GDB -->
+
+<p><i>
+This applies to the 6g 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
+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.
+</p>
+
+
+<h3 id="Common_Operations">Common Operations</h3>
+
+<ul>
+<li>
+Show file and line number for code 
+and set breakpoints:
+<pre>(gdb) <b>list</b>
+(gdb) <b>list <i>line</i></b>
+(gdb) <b>list <i>file.go</i>:<i>line</i></b>
+(gdb) <b>break <i>line</i></b>
+(gdb) <b>break <i>file.go</i>:<i>line</i></b>
+(gdb) <b>disas</b></pre>
+</li>
+<li>
+Unwind stack frames:
+<pre>(gdb) <b>bt</b>
+(gdb) <b>frame <i>n</i></b></pre>
+</li>
+<li>
+Show the name, type and location on the stack frame of local variables,
+arguments and return values:
+<pre>(gdb) <b>info locals</b>
+(gdb) <b>info args</b>
+(gdb) <b>p variable</b>
+(gdb) <b>whatis variable</b></pre>
+</li>
+<li>
+Show the name, type and location of global variables:
+<pre>(gdb) <b>info variables <i>regexp</i></b></pre>
+</li>
+</ul>
+
+
+<h3 id="Go_Extensions">Go Extensions</h3>
+
+<p>
+A recent extension mechanism to GDB allows it to load extension scripts for a
+given binary. The tool chain uses this to extend GDB with a handful of
+commands to inspect internals of the runtime code (such as goroutines) and to
+pretty print the built-in map, slice and channel types.
+</p>
+
+<ul>
+<li>
+Pretty printing a string, slice, map, channel or interface:
+<pre>(gdb) <b>p <i>var</i></b></pre>
+</li>
+<li>
+A $len() and $cap() function for strings, slices and maps:
+<pre>(gdb) <b>p $len(<i>var</i>)</b></pre>
+</li>
+<li>
+A function to cast interfaces to their dynamic types:
+<pre>(gdb) <b>p $dtype(<i>var</i>)</b>
+(gdb) <b>iface <i>var</i></b></pre>
+<p class="detail"><b>Known issue:</b> GDB can’t automatically find the dynamic
+type of an interface value if its long name differs from its short name
+(annoying when printing stacktraces, the pretty printer falls back to printing
+the short type name and a pointer).</p>
+</li>
+<li>
+Inspecting goroutines:
+<pre>(gdb) <b>info goroutines</b>
+(gdb) <b>goroutine <i>n</i> <i>cmd</i></b>
+(gdb) <b>help goroutine</b></pre>
+For example:
+<pre>(gdb) <b>goroutine 12 bt</b></pre>
+</li>
+</ul>
+
+<p>
+If you'd like to see how this works, or want to extend it, take a look at <a
+href="/src/pkg/runtime/runtime-gdb.py">src/pkg/runtime/runtime-gdb.py</a> in
+the Go source distribution. It depends on some special magic types
+(<code>hash&lt;T,U&gt;</code>) and variables (<code>runtime.m</code> and
+<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>
+If you're interested in what the debugging information looks like, run
+'<code>objdump -W 6.out</code>' and browse through the <code>.debug_*</code>
+sections.
+</p>
+
+
+<h3 id="Known_Issues">Known Issues</h3>
+
+<ol>
+<li>String pretty printing only triggers for type string, not for types derived
+from it.</li>
+<li>Type information is missing for the C parts of the runtime library.</li>
+<li>GDB does not understand Go’s name qualifications and treats
+<code>"fmt.Print"</code> as an unstructured literal with a <code>"."</code>
+that needs to be quoted.  It objects even more strongly to method names of
+the form <code>pkg.(*MyType).Meth</code>.
+<li>All global variables are lumped into package <code>"main"</code>.</li>
+</ol>
+
+<h2 id="Tutorial">Tutorial</h2>
+
+<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>.
+</p>
+
+
+<h3 id="Getting_Started">Getting Started</h3>
+
+<p>
+Launch GDB, debugging <code>6.out</code>:
+</p>
+
+<pre>
+$ <b>gdb 6.out</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...
+done.
+Loading Go Runtime support.
+(gdb) 
+</pre>
+
+<p>
+The message <code>"Loading Go Runtime support"</code> means that GDB loaded the
+extension from <code>$GOROOT/src/pkg/runtime/runtime-gdb.py</code>.
+</p>
+
+<p>
+To help GDB find the Go runtime sources and the accompanying support script,
+pass your <code>$GOROOT</code> with the <code>'-d'</code> flag:
+</p>
+
+<pre>
+$ <b>gdb 6.out -d $GOROOT</b>
+</pre>
+
+<p>
+If for some reason GDB still can't find that directory or that script, you can load
+it by hand by telling gdb (assuming you have the go sources in
+<code>~/go/</code>):
+<p>
+
+<pre>
+(gdb) <b>source ~/go/src/pkg/runtime/runtime-gdb.py</b>
+Loading Go Runtime support.
+</pre>
+
+<h3 id="Inspecting_the_source">Inspecting the source</h3>
+
+<p>
+Use the <code>"l"</code> or <code>"list"</code> command to inspect source code.
+</p>
+
+<pre>
+(gdb) <b>l</b>
+</pre>
+
+<p>
+List a specific part of the source parametrizing <code>"list"</code> with a
+function name (it must be qualified with its package name).
+</p>
+
+<pre>
+(gdb) <b>l main.main</b>
+</pre>
+
+<p>
+List a specific file and line number:
+</p>
+
+<pre>
+(gdb) <b>l regexp.go:1</b>
+(gdb) <i># Hit enter to repeat last command. Here, this lists next 10 lines.</i>
+</pre>
+
+
+<h3 id="Naming">Naming</h3>
+
+<p>
+Variable and function names must be qualified with the name of the packages
+they belong to. The <code>Compile</code> function from the <code>regexp</code>
+package is known to GDB as <code>'regexp.Compile'</code>. 
+</p>
+
+<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.)
+</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'.
+</p>
+
+<h3 id="Setting_breakpoints">Setting breakpoints</h3>
+
+<p>
+Set a breakpoint at the <code>TestFind</code> function:
+</p>
+
+<pre>
+(gdb) <b>b 'regexp.TestFind'</b>
+Breakpoint 1 at 0x424908: file /home/user/go/src/pkg/regexp/find_test.go, line 148.
+</pre>
+
+<p>
+Run the program:
+</p>
+
+<pre>
+(gdb) <b>run</b>
+Starting program: /home/lvd/g/src/pkg/regexp/6.out 
+
+Breakpoint 1, regexp.TestFind (t=0xf8404a89c0) at /home/user/go/src/pkg/regexp/find_test.go:148
+148	func TestFind(t *testing.T) {
+</pre>
+
+<p>
+Execution has paused at the breakpoint.
+See which goroutines are running, and what they're doing:
+</p>
+
+<pre>
+(gdb) <b>info goroutines</b>
+  1  waiting runtime.gosched
+* 13  running runtime.goexit
+</pre>
+
+<p>
+the one marked with the <code>*</code> is the current goroutine.
+</p>
+
+<h3 id="Inspecting_the_stack">Inspecting the stack</h3>
+
+<p>
+Look at the stack trace for where we’ve paused the program:
+</p>
+
+<pre>
+(gdb) <b>bt</b>  <i># backtrace</i>
+#0  regexp.TestFind (t=0xf8404a89c0) at /home/user/go/src/pkg/regexp/find_test.go:148
+#1  0x000000000042f60b in testing.tRunner (t=0xf8404a89c0, test=0x573720) at /home/user/go/src/pkg/testing/testing.go:156
+#2  0x000000000040df64 in runtime.initdone () at /home/user/go/src/pkg/runtime/proc.c:242
+#3  0x000000f8404a89c0 in ?? ()
+#4  0x0000000000573720 in ?? ()
+#5  0x0000000000000000 in ?? ()
+</pre>
+
+<p>
+The other goroutine, number 1, is stuck in <code>runtime.gosched</code>, blocked on a channel receive:
+</p>
+
+<pre>
+(gdb) <b>goroutine 1 bt</b>
+#0  0x000000000040facb in runtime.gosched () at /home/lvd/g/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 *, os.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 *, os.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
+#8  0x0000000000000000 in ?? ()
+</pre>
+
+<p>
+The stack frame shows we’re currently executing the <code>regexp.TestFind</code> function, as expected.
+</p>
+
+<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); 
+    saved rip 0x430233
+ called by frame at 0x7ffff7f9ffa8
+ source language minimal.
+ Arglist at 0x7ffff7f9ff78, args: t=0xf840688b60
+ Locals at 0x7ffff7f9ff78, Previous frame's sp is 0x7ffff7f9ff88
+ Saved registers:
+  rip at 0x7ffff7f9ff80
+</pre>
+
+<p>
+The command <code>info locals</code> lists all variables local to the function and their values, but is a bit
+dangerous to use, since it will also try to print uninitialized variables. Uninitialized slices may cause gdb to try
+to print arbitrary large arrays.
+</p>
+
+<p>
+The function’s arguments:
+</p>
+
+<pre>
+(gdb) <b>info args</b>
+t = 0xf840688b60
+</pre>
+
+<p>
+When printing the argument, notice that it’s a pointer to a
+<code>Regexp</code> value. Note that GDB has incorrectly put the <code>*</code>
+on the right-hand side of the type name and made up a 'struct' keyword, in traditional C style.
+</p>
+
+<pre>
+(gdb) <b>p re</b>
+(gdb) p t
+$1 = (struct testing.T *) 0xf840688b60
+(gdb) p t
+$1 = (struct testing.T *) 0xf840688b60
+(gdb) p *t
+$2 = {errors = "", failed = false, ch = 0xf8406f5690}
+(gdb) p *t->ch
+$3 = struct hchan<*testing.T>
+</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.
+</p>
+
+<p>
+Stepping forward:
+</p>
+
+<pre>
+(gdb) <b>n</b>  <i># execute next line</i>
+149             for _, test := range findTests {
+(gdb)    <i># enter is repeat</i>
+150                     re := MustCompile(test.pat)
+(gdb) <b>p test.pat</b>
+$4 = ""
+(gdb) <b>p re</b>
+$5 = (struct regexp.Regexp *) 0xf84068d070
+(gdb) <b>p *re</b>
+$6 = {expr = "", prog = 0xf840688b80, prefix = "", prefixBytes =  []uint8, prefixComplete = true, 
+  prefixRune = 0, cond = 0 '\000', numSubexp = 0, longest = false, mu = {state = 0, sema = 0}, 
+  machine =  []*regexp.machine}
+(gdb) <b>p *re->prog</b>
+$7 = {Inst =  []regexp/syntax.Inst = {{Op = 5 '\005', Out = 0, Arg = 0, Rune =  []int}, {Op = 
+    6 '\006', Out = 2, Arg = 0, Rune =  []int}, {Op = 4 '\004', Out = 0, Arg = 0, Rune =  []int}}, 
+  Start = 1, NumCap = 2}
+</pre>
+
+
+<p>
+We can step into the <code>String</code>function call with <code>"s"</code>:
+</p>
+
+<pre>
+(gdb) <b>s</b>
+regexp.(*Regexp).String (re=0xf84068d070, noname=void) at /home/lvd/g/src/pkg/regexp/regexp.go:97
+97      func (re *Regexp) String() string {
+</pre>
+
+<p>
+Get a stack trace to see where we are:
+</p>
+
+<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
+#1  0x0000000000425615 in regexp.TestFind (t=0xf840688b60)
+    at /home/lvd/g/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
+....
+</pre>
+
+<p>
+Look at the source code:
+</p>
+
+<pre>
+(gdb) <b>l</b>
+92              mu      sync.Mutex
+93              machine []*machine
+94      }
+95
+96      // String returns the source text used to compile the regular expression.
+97      func (re *Regexp) String() string {
+98              return re.expr
+99      }
+100
+101     // Compile parses a regular expression and returns, if successful,
+</pre>
+
+<h3 id="Pretty_Printing">Pretty Printing</h3>
+
+<p>
+GDB's pretty printing mechanism is triggered by regexp matches on type names.  An example for slices:
+</p>
+
+<pre>
+(gdb) <b>p utf</b>
+$22 =  []uint8 = {0 '\000', 0 '\000', 0 '\000', 0 '\000'}
+</pre>
+
+<p>
+Since slices, arrays and strings are not C pointers, GDB can't interpret the subscripting operation for you, but
+you can look inside the runtime representation to do that (tab completion helps here):
+</p>
+<pre>
+
+(gdb) <b>p slc</b>
+$11 =  []int = {0, 0}
+(gdb) <b>p slc-&gt</b><i>&ltTAB&gt</i>
+array  slc    len    
+(gdb) <b>p slc->array</b>
+$12 = (int *) 0xf84057af00
+(gdb) <b>p slc->array[1]</b>
+$13 = 0</pre>
+
+
+
+<p>
+The extension functions $len and $cap work on strings, arrays and slices:
+</p>
+
+<pre>
+(gdb) <b>p $len(utf)</b>
+$23 = 4
+(gdb) <b>p $cap(utf)</b>
+$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
+</p>
+
+<p>
+Interfaces are represented in the runtime as a pointer to a type descriptor and a pointer to a value.  The Go GDB runtime extension decodes this and automatically triggers pretty printing for the runtime type.  The extension function <code>$dtype</code> decodes the dynamic type for you (examples are taken from a breakpoint at <code>regexp.go</code> line 293.)
+</p>
+
+<pre>
+(gdb) <b>p i</b>
+$4 = {str = "cbb"}
+(gdb) <b>whatis i</b>
+type = regexp.input
+(gdb) <b>p $dtype(i)</b>
+$26 = (struct regexp.inputBytes *) 0xf8400b4930
+(gdb) <b>iface i</b>
+regexp.input: struct regexp.inputBytes *
+</pre>

doc/devel/release.html

@@ -14,6 +14,294 @@ hg pull
 hg update release.r<i>NN</i>
 </pre>
 
+<h2 id="r60">r60 (released 2011/09/07)</h2>
+
+<p>
+The r60 release corresponds to 
+<code><a href="weekly.html#2011-08-17">weekly.2011-08-17</a></code>.
+This section highlights the most significant changes in this release.
+For a more detailed summary, see the
+<a href="weekly.html#2011-08-17">weekly release notes</a>.
+For complete information, see the
+<a href="http://code.google.com/p/go/source/list?r=release-branch.r60">Mercurial change list</a>.
+</p>
+
+<h3 id="r60.lang">Language</h3>
+
+<p>
+An "else" block is now required to have braces except if the body of the "else"
+is another "if". Since gofmt always puts those braces in anyway,
+gofmt-formatted programs will not be affected.
+To fix other programs, run gofmt.
+</p>
+
+<h3 id="r60.pkg">Packages</h3>
+
+<p>
+<a href="/pkg/http/">Package http</a>'s URL parsing and query escaping code
+(such as <code>ParseURL</code> and <code>URLEscape</code>) has been moved to
+the new <a href="/pkg/url/">url package</a>, with several simplifications to
+the names. Client code can be updated automatically with gofix.
+</p>
+
+<p>
+<a href="/pkg/image/">Package image</a> has had significant changes made to the
+<code>Pix</code> field of struct types such as
+<a href="/pkg/image/#RGBA">image.RGBA</a> and
+<a href="/pkg/image/#NRGBA">image.NRGBA</a>.
+The <a href="/pkg/image/#Image">image.Image</a> interface type has not changed,
+though, and you should not need to change your code if you don't explicitly
+refer to <code>Pix</code> fields. For example, if you decode a number of images
+using the <a href="/pkg/image/jpeg/">image/jpeg</a> package, compose them using
+<a href="/pkg/image/draw/">image/draw</a>, and then encode the result using
+<a href="/pkg/img/png">image/png</a>, then your code should still work as
+before.
+If your code <i>does</i> refer to <code>Pix</code> fields see the 
+<a href="/doc/devel/weekly.html#2011-07-19">weekly.2011-07-19</a>
+snapshot notes for how to update your code.
+</p>
+
+<p>
+<a href="/pkg/template/">Package template</a> has been replaced with a new
+templating package (formerly <code>exp/template</code>). The original template
+package is still available as <a href="/pkg/old/template/">old/template</a>.
+The <code>old/template</code> package is deprecated and will be removed.
+The Go tree has been updated to use the new template package. We encourage
+users of the old template package to switch to the new one. Code that uses
+<code>template</code> or <code>exp/template</code> will need to change its
+import lines to <code>"old/template"</code> or <code>"template"</code>,
+respectively.
+</p>
+
+<h3 id="r60.cmd">Tools</h3>
+
+<p>
+<a href="/cmd/goinstall/">Goinstall</a> now uses a new tag selection scheme.
+When downloading or updating, goinstall looks for a tag or branch with the
+<code>"go."</code> prefix that corresponds to the local Go version. For Go
+<code>release.r58</code> it looks for <code>go.r58</code>. For
+<code>weekly.2011-06-03</code> it looks for <code>go.weekly.2011-06-03</code>.
+If the specific <code>go.X</code> tag or branch is not found, it chooses the
+closest earlier version. If an appropriate tag or branch is found, goinstall
+uses that version of the code. Otherwise it uses the default version selected
+by the version control system. Library authors are encouraged to use the
+appropriate tag or branch names in their repositories to make their libraries
+more accessible.
+</p>
+
+<h3 id="r60.minor">Minor revisions</h3>
+
+<p>
+r60.1 includes a 
+<a href="http://code.google.com/p/go/source/detail?r=1824581bf62d">linker
+fix</a>, a pair of
+<a href="http://code.google.com/p/go/source/detail?r=9ef4429c2c64">goplay</a>
+<a href="http://code.google.com/p/go/source/detail?r=d42ed8c3098e">fixes</a>,
+and a <code>json</code> package
+<a href="http://code.google.com/p/go/source/detail?r=d5e97874fe84">fix</a> and
+a new
+<a href="http://code.google.com/p/go/source/detail?r=4f0e6269213f">struct tag
+option</a>.
+</p>
+
+<p>
+r60.2
+<a href="http://code.google.com/p/go/source/detail?r=ff19536042ac">fixes</a>
+a memory leak involving maps.
+</p>
+
+<p>
+r60.3 fixes a
+<a href="http://code.google.com/p/go/source/detail?r=01fa62f5e4e5">reflect bug</a>.
+</p>
+
+<h2 id="r59">r59 (released 2011/08/01)</h2>
+
+<p>
+The r59 release corresponds to 
+<code><a href="weekly.html#2011-07-07">weekly.2011-07-07</a></code>.
+This section highlights the most significant changes in this release.
+For a more detailed summary, see the
+<a href="weekly.html#2011-07-07">weekly release notes</a>.
+For complete information, see the
+<a href="http://code.google.com/p/go/source/list?r=release-branch.r59">Mercurial change list</a>.
+</p>
+
+<h3 id="r59.lang">Language</h3>
+
+<p>
+This release includes a language change that restricts the use of
+<code>goto</code>.  In essence, a <code>goto</code> statement outside a block
+cannot jump to a label inside that block. Your code may require changes if it
+uses <code>goto</code>.
+See <a href="http://code.google.com/p/go/source/detail?r=dc6d3cf9279d">this
+changeset</a> for how the new rule affected the Go tree.
+</p>
+
+<h3 id="r59.pkg">Packages</h3>
+
+<p>
+As usual, <a href="/cmd/gofix/">gofix</a> will handle the bulk of the rewrites
+necessary for these changes to package APIs.
+</p>
+
+<p>
+<a href="/pkg/http">Package http</a> has a new
+<a href="/pkg/http/#FileSystem">FileSystem</a> interface that provides access
+to files. The <a href="/pkg/http/#FileServer">FileServer</a> helper now takes a
+<code>FileSystem</code> argument instead of an explicit file system root. By
+implementing your own <code>FileSystem</code> you can use the
+<code>FileServer</code> to serve arbitrary data.
+</p>
+
+<p>
+<a href="/pkg/os/">Package os</a>'s <code>ErrorString</code> type has been
+hidden. Most uses of <code>os.ErrorString</code> can be replaced with
+<a href="/pkg/os/#NewError">os.NewError</a>.
+</p>
+
+<p>
+<a href="/pkg/reflect/">Package reflect</a> supports a new struct tag scheme
+that enables sharing of struct tags between multiple packages.
+In this scheme, the tags must be of the form:
+</p>
+<pre>
+	`key:"value" key2:"value2"`
+</pre>
+<p>
+The <a href="/pkg/reflect/#StructField">StructField</a> type's Tag field now
+has type <a href="/pkg/reflect/#StructTag">StructTag</a>, which has a
+<code>Get</code> method. Clients of <a href="/pkg/json">json</a> and
+<a href="/pkg/xml">xml</a> will need to be updated. Code that says
+</p>
+<pre>
+	type T struct {
+		X int "name"
+	}
+</pre>
+<p>
+should become
+</p>
+<pre>
+	type T struct {
+		X int `json:"name"`  // or `xml:"name"`
+	}
+</pre>
+<p>
+Use <a href="/cmd/govet/">govet</a> to identify struct tags that need to be
+changed to use the new syntax.
+</p>
+
+<p>
+<a href="/pkg/sort/">Package sort</a>'s <code>IntArray</code> type has been
+renamed to <a href="/pkg/sort/#IntSlice">IntSlice</a>, and similarly for
+<a href="/pkg/sort/#Float64Slice">Float64Slice</a> and
+<a href="/pkg/sort/#StringSlice">StringSlice</a>.
+</p>
+
+<p>
+<a href="/pkg/strings/">Package strings</a>'s <code>Split</code> function has
+itself been split into <a href="/pkg/strings/#Split">Split</a> and
+<a href="/pkg/strings/#SplitN">SplitN</a>.
+<code>SplitN</code> is the same as the old <code>Split</code>.
+The new <code>Split</code> is equivalent to <code>SplitN</code> with a final
+argument of -1.
+</p>
+
+<a href="/pkg/image/draw/">Package image/draw</a>'s
+<a href="/pkg/image/draw/#Draw">Draw</a> function now takes an additional
+argument, a compositing operator.
+If in doubt, use <a href="/pkg/image/draw/#Op">draw.Over</a>.
+</p>
+
+<h3 id="r59.cmd">Tools</h3>
+
+<p>
+<a href="/cmd/goinstall/">Goinstall</a> now installs packages and commands from
+arbitrary remote repositories (not just Google Code, Github, and so on).
+See the <a href="/cmd/goinstall/">goinstall documentation</a> for details.
+</p>
+
+<h2 id="r58">r58 (released 2011/06/29)</h2>
+
+<p>
+The r58 release corresponds to 
+<code><a href="weekly.html#2011-06-09">weekly.2011-06-09</a></code>
+with additional bug fixes.
+This section highlights the most significant changes in this release.
+For a more detailed summary, see the
+<a href="weekly.html#2011-06-09">weekly release notes</a>.
+For complete information, see the
+<a href="http://code.google.com/p/go/source/list?r=release-branch.r58">Mercurial change list</a>.
+</p>
+
+<h3 id="r58.lang">Language</h3>
+
+<p>
+This release fixes a <a href="http://code.google.com/p/go/source/detail?r=b720749486e1">use of uninitialized memory in programs that misuse <code>goto</code></a>.
+</p>
+
+<h3 id="r58.pkg">Packages</h3>
+
+<p>
+As usual, <a href="/cmd/gofix/">gofix</a> will handle the bulk of the rewrites
+necessary for these changes to package APIs.
+</p>
+
+<p>
+<a href="/pkg/http/">Package http</a> drops the <code>finalURL</code> return
+value from the <a href="/pkg/http/#Client.Get">Client.Get</a> method. The value
+is now available via the new <code>Request</code> field on <a
+href="/pkg/http/#Response">http.Response</a>.
+Most instances of the type map[string][]string in have been
+replaced with the new <a href="/pkg/http/#Values">Values</a> type.
+</p>
+
+<p>
+<a href="/pkg/exec/">Package exec</a> has been redesigned with a more
+convenient and succinct API.
+</p>
+
+<p>
+<a href="/pkg/strconv/">Package strconv</a>'s <a href="/pkg/strconv/#Quote">Quote</a>
+function now escapes only those Unicode code points not classified as printable
+by <a href="/pkg/unicode/#IsPrint">unicode.IsPrint</a>.
+Previously Quote would escape all non-ASCII characters.
+This also affects the <a href="/pkg/fmt/">fmt</a> package's <code>"%q"</code>
+formatting directive. The previous quoting behavior is still available via
+strconv's new <a href="/pkg/strconv/#QuoteToASCII">QuoteToASCII</a> function.   
+</p>
+
+<p>
+<a href="/pkg/os/signal/">Package os/signal</a>'s
+<a href="/pkg/os/#Signal">Signal</a> and 
+<a href="/pkg/os/#UnixSignal">UnixSignal</a> types have been moved to the
+<a href="/pkg/os/">os</a> package.
+</p>
+
+<p>
+<a href="/pkg/image/draw/">Package image/draw</a> is the new name for
+<code>exp/draw</code>. The GUI-related code from <code>exp/draw</code> is now
+located in the <a href="/pkg/exp/gui/">exp/gui</a> package.
+</p>
+
+<h3 id="r58.cmd">Tools</h3>
+
+<p>
+<a href="/cmd/goinstall/">Goinstall</a> now observes the GOPATH environment
+variable to build and install your own code and external libraries outside of
+the Go tree (and avoid writing Makefiles).
+</p>
+
+
+<h3 id="r58.minor">Minor revisions</h3>
+
+<p>r58.1 adds 
+<a href="http://code.google.com/p/go/source/detail?r=293c25943586">build</a> and
+<a href="http://code.google.com/p/go/source/detail?r=bf17e96b6582">runtime</a>
+changes to make Go run on OS X 10.7 Lion.
+</p>
+
 <h2 id="r57">r57 (released 2011/05/03)</h2>
 
 <p>
@@ -136,7 +424,7 @@ Remember that gofix will handle the bulk of the rewrites
 necessary for these changes to package APIs.
 </p>
 
-<h3 id="r57.tool">Tools</h3>
+<h3 id="r57.cmd">Tools</h3>
 
 <p><a href="/cmd/gofix/">Gofix</a>, a new command, is described above.</p>
 
@@ -162,6 +450,7 @@ For other uses, see the <a href="/pkg/runtime/pprof/">runtime/pprof</a> document
 <h3 id="r57.minor">Minor revisions</h3>
 
 <p>r57.1 fixes a <a href="http://code.google.com/p/go/source/detail?r=ff2bc62726e7145eb2ecc1e0f076998e4a8f86f0">nil pointer dereference in http.FormFile</a>.</p>
+<p>r57.2 fixes a <a href="http://code.google.com/p/go/source/detail?r=063b0ff67d8277df03c956208abc068076818dae">use of uninitialized memory in programs that misuse <code>goto</code></a>.</p>
 
 <h2 id="r56">r56 (released 2011/03/16)</h2>
 

doc/devel/weekly.html

@@ -14,7 +14,700 @@ hg pull
 hg update weekly.<i>YYYY-MM-DD</i>
 </pre>
 
-<h2 id="2011-06-09">2011-06-09</h2>
+<h2 id="2011-09-07">2011-09-07</h2>
+
+<pre>
+This weekly snapshot consists of improvements and bug fixes, including fixes
+for issues introduced by escape analysis changes in the gc compiler.
+
+* build: clear execute bit from Go files (thanks Mike Rosset),
+	error out if problem with sudo.bash /usr/local/bin (thanks Mike Rosset).
+* exp/norm: add Reader and Writer,
+	performance improvements of quickSpan.
+* exp/regexp: bug fixes and RE2 tests.
+* exp/template/html: string replacement refactoring,
+	tweaks to js{,_test}.go.
+* gc: add -p flag to catch import cycles earlier,
+	fix label recursion bugs,
+	fix zero-length struct eval,
+	zero stack-allocated slice backing arrays,
+* gc, ld: fix Windows file paths (thanks Hector Chu).
+* go/parser: accept corner cases of signature syntax.
+* gobuilder: ignore _test.go files when looking for docs, more logging.
+* godoc: minor tweaks for App Engine use.
+* gofix: do not convert url in field names (thanks Gustavo Niemeyer).
+* gofmt: indent multi-line signatures.
+* gopprof: regexp fixes (thanks Hector Chu).
+* image/png: check zlib checksum during Decode.
+* libmach: fix incorrect use of memset (thanks Dave Cheney).
+* misc/goplay: fix template output.
+* net: ParseCIDR returns IPNet instead of IPMask (thanks Mikio Hara),
+	sync CIDRMask code, doc.
+* os: use GetFileAttributesEx to implement Stat on windows (thanks Alex Brainman).
+* runtime: fix openbsd 386 raisesigpipe,
+	implement exception handling on windows/amd64 (thanks Hector Chu),
+	test for concurrent channel consumers (thanks Christopher Wedgwood).
+* sort: use heapsort to bail out quicksort (thanks Ziad Hatahet).
+* sync/atomic: add LoadUintptr, add Store functions.
+* syscall: update routing message attributes handling (thanks Mikio Hara).
+* template: fix deadlock,
+	indirect or dereference function arguments if necessary,
+	slightly simplify the test for assignability of arguments.
+* url: handle ; in ParseQuery.
+* websocket: fix incorrect prints found by govet (thanks Robert Hencke).
+</pre>
+
+<h2 id="2011-09-01">2011-09-01</h2>
+
+<pre>
+This weekly contains performance improvements and bug fixes.
+
+The gc compiler now does escape analysis, which improves program performance
+by placing variables on the call stack instead of the heap when it is safe to
+do so.
+
+The container/vector package is deprecated and will be removed at some point
+in the future.
+
+Other changes:
+* archive/tar: support symlinks. (thanks Mike Rosset)
+* big: fix nat.scan bug. (thanks Evan Shaw)
+* bufio: handle a "\r\n" that straddles the buffer.
+	add openbsd.
+	avoid redundant bss declarations.
+	fix unused parameters.
+	fix windows/amd64 build with newest mingw-w64. (thanks Hector Chu)
+* bytes: clarify that NewBuffer is not for beginners.
+* cgo: explain how to free something.
+	fix GoBytes. (thanks Gustavo Niemeyer)
+	fixes callback for windows amd64. (thanks Wei Guangjing)
+	note that CString result must be freed. (thanks Gustavo Niemeyer)
+* cov: remove tautological #defines. (thanks Lucio De Re)
+* dashboard: yet another utf-8 fix.
+* doc/codelab/wiki: fix Makefile.
+* doc/progs: fix windows/amd64. (thanks Jaroslavas Počepko)
+* doc/tmpltohtml: update to new template package.
+* doc: emphasize that environment variables are optional.
+* effective_go: convert to use tmpltohtml.
+* exp/norm: reduced the size of the byte buffer used by reorderBuffer by half by reusing space when combining.
+	a few minor fixes to support the implementation of norm.
+	added implementation for []byte versions of methods.
+* exp/template/html: add some tests for ">" attributes.
+	added handling for URL attributes.
+	differentiate URL-valued attributes (such as href).
+	reworked escapeText to recognize attr boundaries.
+* exp/wingui: made compatible with windows/amd64. (thanks Jaroslavas Počepko)
+* flag: add Parsed, restore Usage.
+* gc: add openbsd.
+	escape analysis.
+	fix build on Plan 9. (thanks Lucio De Re)
+	fix div bug.
+	fix pc/line table. (thanks Julian Phillips)
+	fix some spurious leaks.
+	make static initialization more static.
+	remove JCXZ; add JCXZW, JCXZL, and JCXZQ instructions. (thanks Jaroslavas Počepko)
+	shuffle #includes.
+	simplify escape analysis recursion.
+	tweak and enable escape analysis.
+* go/ast cleanup: base File/PackageExports on FilterFile/FilterPackage code.
+	adjustments to filter function.
+	fix ast.MergePackageFiles to collect infos about imports. (thanks Sebastien Binet)
+	generalize ast.FilterFile.
+* go/build: add test support & use in gotest.
+	separate test imports out when scanning. (thanks Gustavo Niemeyer)
+* go/parser: fix type switch scoping.
+	fix type switch scoping.
+* gob: explain that Debug isn't useful unless it's compiled in.
+* gobuilder: increase log limit.
+* godashboard: fix utf-8 in user names.
+* godoc: first step towards reducing index size.
+	add dummy playground.js to silence godoc warning at start-up.
+	added systematic throttling to indexing goroutine.
+	fix bug in zip.go.
+	support for reading/writing (splitted) index files.
+	use virtual file system when generating package synopses.
+* gofix: forgot to rename the URL type.
+	osopen: fixed=true when changing O_CREAT. (thanks Tarmigan Casebolt)
+* goinstall: error out with paths that end with '/'. (thanks Tarmigan Casebolt)
+	report lack of $GOPATH on errors. (thanks Gustavo Niemeyer)
+	select the tag that is closest to runtime.Version.
+* gotry: add missing $. (thanks Tarmigan Casebolt)
+* http: add MaxBytesReader to limit request body size.
+	add file protocol transport.
+	adjust test threshold for larger suse buffers.
+	delete error kludge.
+	on invalid request, send 400 response.
+	return 413 instead of 400 when the request body is too large. (thanks Dave Cheney)
+	support setting Transport's TLS client config.
+* image/tiff: add a decode benchmark. (thanks Benny Siegert)
+	decoder optimization. (thanks Benny Siegert)
+* image: add PalettedImage interface, and make image/png recognize it. (thanks Jaroslavas Počepko)
+* io: add TeeReader. (thanks Hector Chu)
+* json: add struct tag option to wrap literals in strings.
+	calculate Offset for Indent correctly. (thanks Jeff Hodges)
+	fix decode bug with struct tag names with ,opts being ignored.
+* ld: handle Plan 9 ar format. (thanks Lucio De Re)
+	remove duplicate bss definitions.
+* libmach: support reading symbols from Windows .exe for nm. (thanks Mateusz Czapliński)
+* math: fix Pow10 loop. (thanks Volker Dobler)
+* mime: ParseMediaType returns os.Error now, not a nil map.
+	media type formatter. (thanks Pascal S. de Kloe)
+	text charset defaults. (thanks Pascal S. de Kloe)
+* misc/dashboard: remove limit for json package list.
+* misc/emacs: refine label detection.
+* net: add ParseMAC function. (thanks Paul Borman)
+	change the internal form of IPMask for IPv4. (thanks Mikio Hara)
+	disable "tcp" test on openbsd.
+	fix windows build. (thanks Alex Brainman)
+	join and leave a IPv6 group address, on a specific interface. (thanks Mikio Hara)
+	make use of IPv4len, IPv6len. (thanks Mikio Hara)
+	move internal string manipulation routines to parse.go. (thanks Mikio Hara)
+* os: disable Hostname test on OpenBSD.
+	fix WNOHANG Waitmsg. (thanks Gustavo Niemeyer)
+* reflect: add Value.Bytes, Value.SetBytes methods.
+* rpc: add benchmark for async rpc calls.
+* runtime: add openbsd 386 defs.h.
+	add runtime support for openbsd 386.
+	add runtime· prefix to showframe.
+	ctrlhandler for windows amd64. (thanks Wei Guangjing)
+	fix stack cleanup on windows/amd64. (thanks Hector Chu)
+	fix void warnings.
+	go interface to cdecl calbacks. (thanks Jaroslavas Počepko)
+	handle string + char literals in goc2c.
+	make arm work on Ubuntu Natty qemu.
+	openbsd thread tweaks.
+	simplify stack traces.
+	speed up cgo calls. (thanks Alex Brainman)
+	use cgo runtime functions to call windows syscalls. (thanks Alex Brainman)
+	windows/amd64 callbacks fixed and syscall fixed to allow using it in callbacks. (thanks Jaroslavas Počepko)
+* strconv: put decimal on stack.
+* spec: update section on Implementation Differences.
+* syscall: SOMAXCONN should be 0x7fffffff at winsock2. (thanks Yasuhiro Matsumoto)
+	add openbsd 386.
+	handle RTM_NEWROUTE in ParseNetlinkRouteAttr on Linux. (thanks Albert Strasheim)
+	handle routing entry in ParseRoutingSockaddr on BSD variants. (thanks Mikio Hara)
+	openbsd amd64 syscall support.
+	use the vdso page on linux x86 for faster syscalls instead of int $0x80. (thanks Yuval Pavel Zholkover)
+* template/parse: give if, range, and with a common representation.
+* template: grammar fix for template documentation. (thanks Bill Neubauer)
+	range over channel.
+	remove else and end nodes from public view.
+* test: put GOROOT/bin before all others in run.
+* time: fix Plan 9 build. (thanks Fazlul Shahriar)
+	fix zone during windows test.
+* type switches: test for pathological case.
+* version.bash: update VERSION on -save if already present. (thanks Gustavo Niemeyer)
+* websocket: implements new version of WebSocket protocol. (thanks Fumitoshi Ukai)
+* windows/386: clean stack after syscall. (thanks Jaroslavas Počepko)
+* xml: marshal "parent>child" tags correctly. (thanks Ross Light)
+</pre>
+
+<h2 id="2011-08-17">2011-08-17 (<a href="release.html#r60">base for r60</a>)</h2>
+
+<pre>
+This weekly contains some package re-shuffling. Users of the http and
+template packages may be affected.
+
+This weekly replaces the template package with exp/template.
+The original template package is still available as old/template.
+The old/template package is deprecated and will be removed at some point
+in the future. The Go tree has been updated to use the new template package.
+We encourage users of the old template package to switch to the new one.
+Code that uses template or exp/template will need to change
+its import lines to "old/template" or "template", respectively.
+
+The http package's URL parsing and query escaping code (such as ParseURL and
+URLEscape) has been moved to the new url package, with several simplifications
+to the names. Client code can be updated automatically with gofix.
+
+* asn1: support unmarshalling structs with int32 members (thanks Dave Cheney).
+* build: allow builds without cgo or hg,
+	support versioning without hg (thanks Gustavo Niemeyer).
+* builtin: add documentation for builtins.
+* cgo: omit duplicate symbols in writeDefs (thanks Julian Phillips).
+* misc: add support for OpenBSD.
+* doc/codewalk: new Markov chain codewalk.
+* exp/norm: added trie lookup code and associated tests,
+	generate trie struct in triegen.go for better encapsulation,
+	implementation of decomposition and composing functionality.
+* exp/template/html: new experimental package for auto-escaping HTML templates.
+* exp/template: don't panic on range of nil interface,
+	rename Parse*File and Parse*Files for clarity,
+	support field syntax on maps (thanks Gustavo Niemeyer), and
+	many other fixes and changes.
+* gc: implement nil chan and nil map support.
+* go/parser: range clause and type literal fixes.
+* godoc: show all top-level decls for (fake) package builtin.
+* goinstall: really report all newly-installed public packages.
+* html: parse more malformed tags.
+* http: fix ParseMultipartForm after MultipartReader error,
+	fix side effects in DefaultTransport's RoundTrip method (thanks Dave Grijalva).
+* json: fix []unmarshaler case.
+* ld: make addaddrplus4 static (thanks Lucio De Re).
+* syscall: move multicast address handling to the net package.
+* net: Plan 9 support (thanks Fazlul Shahriar),
+	add SetTimeout to Listener interface (thanks Aleksandar Dezelin),
+	add multicast stubs for OpenBSD,
+	return correct local address for an accepted TCP connection (thanks Mikio Hara).
+* reflect: panic on Invalid Interface call (thanks Gustavo Niemeyer).
+* rpc: implement ServeRequest to synchronously serve a single request,
+	make Server.Mutex unexported.
+* runtime: better checks for syscall.NewCallback parameter (thanks Alex Brainman),
+	correct SEH installation during callbacks (thanks Alex Brainman),
+	fix GC bitmap corruption,
+	fix pseudo-randomness on some selects (thanks Gustavo Niemeyer).
+* syscall: make LazyDLL/LazyProc.Mutex unexported.
+* test: allow multiple patterns in errchk,
+	new nil semantics.
+* time: take fractional seconds even if not in the format string.
+* url: new package.
+* utf8: rename some internal constants to remove leading underscores.
+* xml: escape string chardata in xml.Marshal.
+</pre>
+
+<h2 id="2011-08-10">2011-08-10</h2>
+
+<pre>
+This weekly contains performance improvements and bug fixes.
+
+There are no outward-facing changes, but imports of the old-style
+container/vector package have also been removed from the core library (thanks
+John Asmuth, Kyle Consalus).
+
+Other changes:
+
+* 5g: fix set but not used error (thanks Dave Cheney).
+* cmd/ld: Corrected mismatched print formats and variables (thanks Lucio De Re).
+* errchk: add -0 flag.
+* exp/norm: fix build by adding a test placeholder,
+	maketables tool for generating tables for normalization.
+* exp/template: bug fixes,
+	ensure that a valid Set is returned even on error (thanks Roger Peppe),
+	make index on maps return zero when key not present (thanks Roger Peppe),
+	split the parse tree into a separate package exp/template/parse,
+	add url query formatting filter.
+* faq: lots of small tweaks plus a couple of new discussions,
+	variant types, unions.
+* fmt: call UpdateMemStats in malloc counter.
+* go/build: use GOBIN as binary path for GOROOT.
+* gob: add UpdateMemStats calls to malloc counter,
+	avoid a couple of init-time allocations,
+	don't invoke GobEncoder on zero values.
+* gofmt: update test script so 'make test' succeeds.
+* html: parse doctype tokens; merge adjacent text nodes.
+* http: add more MPEG-4 MIME types to sniffer, and disable MP4 sniffing,
+	add test to serve content in index.html (thanks Yasuhiro Matsumoto),
+	configurable and default request header size limit,
+	correct format flags when printing errors in tests (thanks Alex Brainman),
+	correct path to serve index.html (thanks Yasuhiro Matsumoto),
+* ld: add one empty symbol into pe to make dumpbin works (thanks Wei Guangjing),
+	fail linking if the top-level package is not main.
+* misc/vim: godoc command (thanks Yasuhiro Matsumoto).
+* net: add support for openbsd (thanks Joel Sing),
+	fix /proc/net/igmp,igmp6 reading bug on linux (thanks Mikio Hara),
+	implement windows LookupMX and LookupAddr (thanks Mikio Hara),
+	sort SRV records before returning from LookupSRV (thanks Alex Brainman),
+* os: add support for openbsd (thanks Joel Sing).
+* runtime: add more specialized type algorithms,
+	correct Note documentation,
+	faster chan creation on Linux/FreeBSD/Plan9,
+	openbsd amd64 runtime support (thanks Joel Sing),
+	remove unnecessary locking (thanks Hector Chu).
+* scanner: correct error position for illegal UTF-8 encodings.
+* syscall: delay load of dll functions on Windows (thanks Alex Brainman),
+	move BSD mmap syscall (thanks Joel Sing),
+	update routing message support for BSD variants (thanks Mikio Hara).
+* test/bench: note changes after recent improvements to locking and runtime.
+* time: add nanoseconds to the Time structure,
+	parse and format fractional seconds.
+</pre>
+
+<h2 id="2011-07-29">2011-07-29</h2>
+
+<pre>
+This weekly contains performance improvements and many bug fixes.
+
+* 6l: OpenBSD support.
+* archive/zip: handle zip files with more than 65535 files,
+	more efficient reader and bug fix.
+* big: refine printf formatting and optimize string conversion.
+* build: fixes for mingw-w64 (thanks Wei Guangjing),
+	miscellaneous fixes.
+* cgo: add GoBytes, fix gmp example.
+* exp/norm: API for normalization library.
+* exp/regexp: implement regexp API using exp/regexp/syntax.
+* exp/template: more tweaks and fixes, convert the tree to use exp/template.
+* fmt: handle precision 0 format strings in standard way.
+* gc: a raft of bug fixes.
+* go/parser: report illegal label declarations at ':'.
+* gob: send empty but non-nil maps.
+* godoc: allow form feed in text files,
+	app engine configuration and updated documentation.
+* goinstall: abort and warn when using any url scheme, not just 'http://',
+	write to goinstall.log in respective GOPATH.
+* html: handle character entities without semicolons (thanks Andrew Balholm),
+	parse misnested formatting tags according to the HTML5 spec,
+	sync html/testdata/webkit with upstream WebKit.
+* http: content-type sniffing,
+	make serveFile redirects relative (thanks Andrew Balholm),
+	other fixes.
+* image/tiff: Do not panic when RowsPerStrip is missing (thanks Benny Siegert).
+* io/ioutil: improve performance of ioutil.Discard (thanks Mike Solomon).
+* ld: detect all import cycles,
+	ldpe fixes (thanks Wei Guangjing),
+	remove cseekend and redo pe writing (thanks Alex Brainman),
+	remove overlap of ELF sections on dynamic binaries (thanks Gustavo Niemeyer).
+* net/textproto: avoid 1 copy in ReadLine, ReadContinuedLine.
+* net: fix memory corruption in windows *netFD.ReadFrom (thanks Alex Brainman).
+* runtime: faster entersyscall/exitsyscall,
+	fix scheduler races (thanks Hector Chu),
+	higher goroutine arg limit, clearer error,
+	parallelism-related performance optimizations and fixes,
+	replace byte-at-a-time zeroing loop with memclr (thanks Quan Yong Zhai).
+* sort: fix Float64Slice sort; NaN smallest value (thanks Florian Uekermann).
+* src: removed some uses of container/vector (thanks John Asmuth).
+* sync: improve Once fast path.
+* unicode: fix case-mapping for roman numerals.
+</pre>
+
+<h2 id="2011-07-19">2011-07-19</h2>
+
+<pre>
+This weekly snapshot includes a language change and a change to the image
+package that may require changes to client code.
+
+The language change is that an "else" block is now required to have braces
+except if the body of the "else" is another "if". Since gofmt always puts those
+braces in anyway, programs will not be affected unless they contain "else for",
+"else switch", or "else select". Run gofmt to fix any such programs.
+
+The image package has had significant changes made to the Pix field of struct
+types such as image.RGBA and image.NRGBA. The image.Image interface type has
+not changed, though, and you should not need to change your code if you don't
+explicitly refer to Pix fields. For example, if you decode a number of images
+using the image/jpeg package, compose them using image/draw, and then encode
+the result using image/png, then your code should still work as before.
+
+If you do explicitly refer to Pix fields, there are two changes.  First, Pix[0]
+now refers to the pixel at Bounds().Min instead of the pixel at (0, 0). Second,
+the element type of the Pix slice is now uint8 instead of image.FooColor. For
+example, for an image.RGBA, the channel values will be packed R, G, B, A, R, G,
+B, A, etc. For 16-bits-per-channel color types, the pixel data will be stored
+as big-endian uint8s.
+
+Most Pix field types have changed, and so if your code still compiles after
+this change, then you probably don't need to make any further changes (unless
+you use an image.Paletted's Pix field). If you do get compiler errors, code
+that used to look like this:
+
+	// Get the R, G, B, A values for the pixel at (x, y).
+	var m *image.RGBA = loadAnImage()
+	c := m.Pix[y*m.Stride + x]
+	r, g, b, a := c.R, c.G, c.B, c.A
+
+should now look like this:
+
+	// Get the R, G, B, A values for the pixel at (x, y).
+	var m *image.RGBA = loadAnImage()
+	i := (y-m.Rect.Min.Y)*m.Stride + (x-m.Rect.Min.X)*4
+	r := m.Pix[i+0]
+	g := m.Pix[i+1]
+	b := m.Pix[i+2]
+	a := m.Pix[i+3]
+
+This image package change will not be fixed by gofix: how best to translate
+code into something efficient and idiomatic depends on the surrounding context,
+and is not easily automatable. Examples of what to do can be found in the
+changes to image/draw/draw.go in http://codereview.appspot.com/4675076/
+
+Other changes:
+* 6l: change default output name to 6.out.exe on windows (thanks Alex Brainman).
+* archive/zip: add Writer,
+	add Mtime_ns function to get modified time in sensible format.
+* cc, ld, gc: fixes for Plan 9 build (thanks Lucio De Re).
+* cgi: close stdout reader pipe when finished.
+* cgo: add missing semicolon in generated struct,
+	windows amd64 port (thanks Wei Guangjing).
+* codereview: fix for Mercurial 1.9.
+* dashboard: list "most installed this week" with rolling count.
+* debug/elf: read ELF Program headers (thanks Matthew Horsnell).
+* debug/pe: fixes ImportedSymbols for Win64 (thanks Wei Guangjing).
+* debug/proc: remove unused package.
+* doc/talks/io2010: update with gofix and handle the errors.
+* exp/eval, exp/ogle: remove packages eval and ogle.
+* exp/regexp/syntax: add Prog.NumCap.
+* exp/template: API changes, bug fixes, and tweaks.
+* flag: make -help nicer.
+* fmt: Scan(&int) was mishandling a lone digit.
+* gc: fix closure bug,
+	fix to build with clang (thanks Dave Cheney),
+	make size of struct{} and [0]byte 0 bytes (thanks Robert Hencke),
+	some enhancements to printing debug info.
+* gif: fix local color map and coordinates.
+* go/build: fixes for windows (thanks Alex Brainman),
+	include processing of .c files for cgo packages (thanks Alex Brainman),
+	less aggressive failure when GOROOT not found.
+* go/printer: changed max. number of newlines from 3 to 2.
+* gob: register more slice types (thanks Bobby Powers).
+* godoc: support for file systems stored in .zip files.
+* goinstall, dashboard: Google Code now supports git (thanks Tarmigan Casebolt).
+* hash/crc32: add SSE4.2 support.
+* html: update section references in comments to the latest HTML5 spec.
+* http: drain the pipe output in TestHandlerPanic to avoid logging deadlock,
+	fix Content-Type of file extension (thanks Yasuhiro Matsumoto),
+	implement http.FileSystem for zip files,
+	let FileServer work when path doesn't begin with a slash,
+	support for periodic flushing in ReverseProxy.
+* image/draw: add benchmarks.
+* json: add omitempty struct tag option,
+	allow using '$' and '-' as the struct field's tag (thanks Mikio Hara),
+	encode \r and \n in strings as e.g. "\n", not "\u000A" (thanks Evan Martin),
+	escape < and > in any JSON string for XSS prevention.
+* ld: allow seek within write buffer<
+	add a PT_LOAD PHDR entry for the PHDR (thanks David Anderson).
+* net: windows/amd64 port (thanks Wei Guangjing).
+* os: plan9: add Process.Signal as a way to send notes (thanks Yuval Pavel Zholkover).
+* os: don't permit Process.Signal after a successful Wait.
+* path/filepath: fixes for windows paths (thanks Alex Brainman).
+* reflect: add Value.NumMethod,
+	panic if Method index is out of range for a type.
+* runtime: faster entersyscall, exitsyscall,
+	fix panic for make(chan [0]byte),
+	fix subtle select bug (thanks Hector Chu),
+	make goc2c build on Plan 9 (thanks Lucio De Re),
+	make TestSideEffectOrder work twice,
+	several parallelism-related optimizations and fixes,
+	stdcall_raw stack 16byte align for Win64 (thanks Wei Guangjing),
+	string-related optimizations (thanks Quan Yong Zhai),
+	track running goroutine count.
+* strconv: handle [-+]Infinity in atof.
+* sync: add fast paths to WaitGroup,
+	improve RWMutex performance.
+* syscall: add Flock on Linux,
+	parse and encode SCM_RIGHTS and SCM_CREDENTIALS (thanks Albert Strasheim).
+</pre>
+
+<h2 id="2011-07-07">2011-07-07 (<a href="release.html#r59">base for r59</a>)</h2>
+
+<pre>
+This weekly snapshot includes changes to the strings, http, reflect, json, and
+xml packages. Code that uses these packages will need changes. Most of these
+changes can be made automatically with gofix.
+
+The strings package's Split function has itself been split into Split and
+SplitN. SplitN is the same as the old Split. The new Split is equivalent to
+SplitN with a final argument of -1.
+
+The http package has a new FileSystem interface that provides access to files.
+The FileServer helper now takes a FileSystem argument instead of an explicit
+file system root. By implementing your own FileSystem you can use the
+FileServer to serve arbitrary data.
+
+The reflect package supports a new struct tag scheme that enables sharing of
+struct tags between multiple packages.
+In this scheme, the tags must be of the form:
+        key:"value" key2:"value2"
+reflect.StructField's Tag field now has type StructTag (a string type), which
+has method Get(key string) string that returns the associated value.
+Clients of json and xml will need to be updated. Code that says
+        type T struct {
+                X int "name"
+        }
+should become
+        type T struct {
+                X int `json:"name"`  // or `xml:"name"`
+        }
+Use govet to identify struct tags that need to be changed to use the new syntax.
+
+Other changes:
+* 5l, 6l, 8l: drop use of ed during build.
+* asn1: support T61 and UTF8 string.
+* bufio: do not cache Read errors (thanks Graham Miller).
+* build: make version.bash aware of branches.
+* cgi: don't depend on CGI.pm for tests.
+* codereview: make --ignore_hgpatch_failure work again,
+	restrict sync to default branch.
+* crypto/openpgp: add ability to reserialize keys,
+	bug fix (thanks Gideon Jan-Wessel Redelinghuys).
+* crypto/tls: fix generate_cert.go.
+* crypto/x509: prevent chain cycles in Verify.
+* csv: new package.
+* doc: remove ed from apt-get package list.
+* docs: fold the prog.sh scripting from makehtml into htmlgen itself.
+* ebnflint: better handling of stdin.
+* exp/regexp/syntax: new experimental RE2-based regexp implementation.
+* exp/template: a new experimental templating package.
+* fmt: add SkipSpace to fmt's ScanState interface.
+* fmt: rename errno and error to err for doc consistency.
+* gc: avoid package name ambiguity in error messages,
+	fix package quoting logic,
+	fixes for Plan 9 (thanks Lucio De Re).
+* go/build: evaluate symlinks before comparing path to GOPATH.
+* gob: use exported fields in structs in the package documentation.
+* godoc: ignore directories that begin with '.',
+	search GOPATH for documentation.
+* gofix: os/signal, path/filepath, and sort fixes (thanks Robert Hencke),
+* goinstall: add support for generic hosts (thanks Julian Phillips),
+	only report successfully-installed packages to the dashboard,
+	try to access via https (thanks Yasuhiro Matsumoto).
+* gotest: add -test.benchtime and -test.cpu flags.
+* html: fixes and improvements (thanks Yasuhiro Matsumoto).
+* http/cgi: add Handler.Dir to specify working directory (thanks Yasuhiro Matsumoto).
+* http: add StripPrefix handler wrapper,
+	assume ContentLength 0 on GET requests,
+	better handling of 0-length Request.Body,
+	do TLS handshake explicitly before copying TLS state,
+	document that ServerConn and ClientConn are low-level,
+	make NewChunkedReader public (thanks Andrew Balholm),
+	respect Handlers setting Connection: close in their response.
+* image: more tests, Paletted.Opaque optimization.
+* io.WriteString: if the object has a WriteString method, use it (thanks Evan Shaw).
+* ld: elide the Go symbol table when using -s (thanks Anthony Martin).
+* ld: fix ELF strip by removing overlap of sections (thanks Gustavo Niemeyer).
+* mime/multipart: parse LF-delimited messages, not just CRLF.
+* mime: permit lower-case media type parameters (thanks Pascal S. de Kloe).
+* misc/dashboard: new features and improvements (not yet deployed).
+* misc/emacs: update list of builtins (thanks Quan Yong Zhai).
+* misc/vim: allow only utf-8 for file encoding (thanks Yasuhiro Matsumoto).
+* os: fix documentation for FileInfo.Name,
+	simplify WriteString,
+	use a different symbol from syscall in mkunixsignals.sh.
+* path/filepath: enable TestWalk to run on windows (thanks Alex Brainman).
+* reflect: add MethodByName,
+	allow Len on String values.
+* regexp: document that Regexp is thread-safe.
+* runtime/cgo: check for errors from pthread_create (thanks Albert Strasheim).
+* runtime: add Semacquire/Semrelease benchmarks,
+	improved Semacquire/Semrelease implementation,
+	windows/amd64 port (thanks Wei Guangjing).
+* sync: add fast path to Once,
+	improve Mutex to allow successive acquisitions,
+	new and improved benchmarks.
+* syscall: regenerate zerrors for darwin/linux/freebsd,
+	support for tty options in StartProcess (thanks Ken Rockot).
+* testing: make ResetTimer not start/stop the timer,
+	scale benchmark precision to 0.01ns if needed.
+* time: zero-pad two-digit years.
+* unicode/maketables: update debugging data.
+* windows: define and use syscall.Handle (thanks Wei Guangjing).
+* xml: add Marshal and MarshalIndent.
+</pre>
+
+<h2 id="2011-06-23">2011-06-23</h2>
+
+<pre>
+This release includes a language change that restricts the use of goto.
+In essence, a "goto" statement outside a block cannot jump to a label inside
+that block. Your code may require changes if it uses goto.
+This changeset shows how the new rule affected the Go tree:
+	http://code.google.com/p/go/source/detail?r=dc6d3cf9279d
+
+The os.ErrorString type has been hidden. If your code uses os.ErrorString it
+must be changed. Most uses of os.ErrorString can be replaced with os.NewError.
+
+Other changes:
+* 5c: do not use R9 and R10.
+* 8l: more fixes for Plan 9 (thanks Lucio De Re).
+* build: Make.ccmd: link with mach lib (thanks Joe Poirier).
+* build: exclude packages that fail on Plan 9 (thanks Anthony Martin).
+* cc: nit: silence comment warnings (thanks Dave Cheney).
+* codereview.py: note that hg change -d abandons a change list (thanks Robert Hencke).
+* crypto/openpgp: add ElGamal support.
+* doc/faq: add question about converting from []T to []interface{}.
+* doc: Effective Go: fix variadic function example (thanks Ben Lynn).
+* exec: LookPath should not search %PATH% for files like c:cmd.exe (thanks Alex Brainman),
+        add support for Plan 9 (thanks Anthony Martin),
+        better error message for windows LookPath (thanks Alex Brainman).
+* fmt: catch panics from calls to String etc.
+* gc: descriptive panic for nil pointer -> value method call,
+        implement goto restriction,
+        unsafe.Alignof, unsafe.Offsetof, unsafe.Sizeof now return uintptr.
+* go/build: include Import objects in Script Inputs.
+* godefs: rudimentary tests (thanks Robert Hencke).
+* goinstall: refactor and generalize repo handling code (thanks Julian Phillips),
+        temporarily use Makefiles by default (override with -make=false).
+* gopprof: update list of memory allocators.
+* http: add Server.ListenAndServeTLS,
+        buffer request.Write,
+        fix req.Cookie(name) with cookies in one header,
+        permit handlers to explicitly remove the Date header,
+        write Header keys with empty values.
+* image: basic test for the 16-bits-per-color-channel types.
+* io: clarify Read, ReadAt, Copy, Copyn EOF behavior.
+* ld: don't attempt to build dynamic sections unnecessarily (thanks Gustavo Niemeyer).
+* libmach: fix disassembly of FCMOVcc and FCOMI (thanks Anthony Martin),
+        fix tracing on linux (for cov) (thanks Anthony Martin).
+* mime: fix RFC references (thanks Pascal S. de Kloe).
+* misc/gobuilder: run make single-threaded on windows (thanks Alex Brainman).
+* misc/godashboard: Accept sub-directories for goinstall's report (thanks Yasuhiro Matsumoto).
+* nacl, tiny: remove vestiges (thanks Robert Hencke).
+* net, syscall: interface for windows (thanks Yasuhiro Matsumoto).
+* os: change Waitmsg String method to use pointer receiver (thanks Graham Miller).
+* runtime: don't use twice the memory with grsec-like kernels (thanks Gustavo Niemeyer),
+* spec: disallow goto into blocks.
+* sync: restore GOMAXPROCS during benchmarks.
+* syscall: add LSF support for linux (thanks Mikio Hara),
+        add socket control message support for darwin, freebsd, linux (thanks Mikio Hara),
+        add tty support to StartProcess (thanks Ken Rockot),
+        fix build for Sizeof change.
+* test: test of goto restrictions.
+* time: add support for Plan 9 (thanks Anthony Martin).
+</pre>
+
+<h2 id="2011-06-16">2011-06-16</h2>
+
+<pre>
+This release includes changes to the sort and image/draw packages that will
+require changes to client code.
+
+The sort.IntArray type has been renamed to IntSlice, and similarly for
+StringArray and Float64Array.
+
+The image/draw package's Draw function now takes an additional argument,
+a compositing operator. If in doubt, use draw.Over.
+
+Other changes:
+* build: fix header files for Plan 9 (thanks Lucio De Re).
+* cgo: handle new Apple LLVM-based gcc from Xcode 4.2.
+* crypto/openpgp: add ability to encrypt and sign messages.
+* doc/gopher: add goggled gopher logo for App Engine.
+* doc: Update notes for 3-day Go course.
+* exec: make LookPath work when PATHEXT var not set on Windows (thanks Alex Brainman).
+* exp/regexp/syntax: syntax data structures, parser, escapes, character classes.
+* exp/template: lexical scanner for new template package.
+* fmt: debugging formats for characters: %+q %#U.
+* gc: frame compaction for arm,
+        handle go print() and go println(),
+        work around goto bug.
+* go/build: fixes, self-contained tests.
+* go/printer, gofmt: print "select {}" on one line.
+* godoc: replace OS file system accesses in favor of a FileSystem interface.
+* gofix: fix inconsistent indentation in help output (thanks Scott Lawrence).
+* goinstall: use go/build package to scan and build packages.
+* http/spdy: improve error handling (thanks William Chan).
+* http: use runtime/debug.Stack() to dump stack trace on panic.
+* ld: dwarf emit filenames in debug_line header instead of as extended opcodes,
+        fix link Windows PE __declspec(dllimport) symbol (thanks Wei Guangjing),
+        make .rodata section read-only (thanks Gustavo Niemeyer).
+* mail: decode RFC 2047 "B" encoding.
+* mime/multipart: remove temp files after tests on Windows (thanks Alex Brainman).
+* net: export all fields in Interface (thanks Mikio Hara),
+        rearrange source to run more tests on Windows (thanks Alex Brainman),
+        sendfile for win32 (thanks Yasuhiro Matsumoto).
+* os: Plan 9, fix OpenFile & Chmod, add Process.Kill (thanks Yuval Pavel Zholkover).
+* runtime: fix Plan 9 "lingering goroutines bug" (thanks Yuval Pavel Zholkover).
+* spec: clarify rules for append, scope rules for :=,
+        specify constant conversions,
+        unsafe.Alignof/Offsetof/Sizeof return uintptr.
+* syscall, os, exec: add *syscall.SysProcAttr field to os.ProcAttr and exec.Cmd.
+* syscall: add ptrace on darwin (thanks Jeff Hodges),
+        mksyscall_windows.pl should output unix newline (thanks Yasuhiro Matsumoto).
+        update BPF support for BSD variants (thanks Mikio Hara),
+        use strict in perl scripts (thanks Yasuhiro Matsumoto).
+* xml: handle non-string attribute fields (thanks Maxim Ushakov).
+</pre>
+
+<h2 id="2011-06-09">2011-06-09 (<a href="release.html#r58">base for r58</a>)</h2>
 
 <pre>
 This release includes changes to the strconv, http, and exp/draw packages.

doc/docs.html

@@ -16,6 +16,16 @@ Once you've learned a little about the language,
 idioms of programming in Go.
 </p>
 
+<h3 id="go_tour"><a href="http://go-tour.appspot.com/">A Tour of Go</a></h3>
+<p>
+An interactive introduction to Go in three sections.
+The first section covers basic syntax and data structures; the second discusses
+methods and interfaces; and the third introduces Go's concurrency primitives.
+Each section concludes with a few exercises so you can practice what you've
+learned. You can <a href="http://go-tour.appspot.com/">take the tour online</a> or
+<a href="http://code.google.com/p/go-tour/">install it locally</a>.
+</p>
+
 <h3 id="orig_tutorial"><a href="go_tutorial.html">A Tutorial for the Go Programming Language</a></h3>
 <p>
 The first tutorial. An introductory text that touches upon several core
@@ -23,6 +33,17 @@ concepts: syntax, types, allocation, constants, I/O, sorting, printing,
 goroutines, and channels.
 </p>
 
+<h3 id="course_notes">Course Notes</h3>
+<p>
+Slides from a 3-day course about the Go programming language.
+A more thorough introduction than the tutorial.
+</p>
+<ul>
+<li><a href="GoCourseDay1.pdf">Day 1: Basics</a> <small>[270KB PDF]</small></li>
+<li><a href="GoCourseDay2.pdf">Day 2: Types, Methods, Interfaces</a> <small>[270KB PDF]</small></li>
+<li><a href="GoCourseDay3.pdf">Day 3: Concurrency and Communication</a> <small>[180KB PDF]</small></li>
+</ul>
+
 <h3 id="effective_go"><a href="effective_go.html">Effective Go</a></h3>
 <p>
 A document that gives tips for writing clear, idiomatic Go code.
@@ -51,12 +72,53 @@ and closures.
 <p>
 Guided tours of Go programs. 
 </p>
+<ul>
+<li><a href="/doc/codewalk/functions">First-Class Functions in Go</a></li>
+<li><a href="/doc/codewalk/markov">Generating arbitrary text: a Markov chain algorithm</a></li>
+<li><a href="/doc/codewalk/sharemem">Share Memory by Communicating</a></li>
+</ul>
 
 <h3 id="go_for_cpp_programmers"><a href="go_for_cpp_programmers.html">Go for C++ Programmers</a></h3>
 <p>
 An introduction to Go for C++ programmers.
 </p>
 
+<h2 id="articles">Go Articles</h2>
+
+<p>
+Notable articles from the <a href="http://blog.golang.org/">Go Blog</a>.
+</p>
+
+<h3>Language</h3>
+
+<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="http://blog.golang.org/2010/08/defer-panic-and-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="http://blog.golang.org/2011/01/go-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="http://blog.golang.org/2011/07/error-handling-and-go.html">Error Handling and Go</a></li>
+</ul>
+
+<h3>Packages</h3>
+
+<ul>
+<li><a href="http://blog.golang.org/2011/01/json-and-go.html">JSON and Go</a> - using the <a href="/pkg/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/gob/">gob</a> package.</li>
+<li><a href="http://blog.golang.org/2011/09/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>
+</ul>
+
+<h3>Tools</h3>
+
+<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="http://blog.golang.org/2011/06/profiling-go-programs.html">Profiling Go Programs</a></li>
+</ul>
+
 <h2 id="tutorials_nonenglish">Non-English Documentation</h2>
 
 <h3 id="docs_be">Belarusian &mdash; Беларуская</h3>
@@ -129,6 +191,11 @@ one goroutine can be guaranteed to observe values produced by writes to the
 same variable in a different goroutine.
 </p>
 
+<h3 id="debugging_with_gdb"><a href="debugging_with_gdb.html">Debugging Go Code with GDB</a></h3>
+<p>
+Using GDB to debug Go programs.
+</p>
+
 <h2 id="videos_talks">Videos and Talks</h2>
 
 <h3 id="writing_web_apps"><a href="http://www.youtube.com/watch?v=-i0hat7pdpk">Writing Web Apps in Go</a></h3>
@@ -209,7 +276,7 @@ from Hoare’s 1978 paper to Go provides insight into how and why Go works as it
 does.
 </i></p>
 
-<h3 id="emerging_go"><a href="talks/gofrontend-gcc-summit-2010.pdf">The Go frontend for GCC</a></h3>
+<h3 id="go_frontend_gcc"><a href="talks/gofrontend-gcc-summit-2010.pdf">The Go frontend for GCC</a></h3>
 <p>
 A description of the Go language frontend for gcc.
 Ian Lance Taylor's paper delivered at the GCC Summit 2010.

doc/effective_go.html

@@ -116,7 +116,7 @@ Some formatting details remain.  Very briefly,
     <dt>Parentheses</dt>
     <dd>
     Go needs fewer parentheses: control structures (<code>if</code>,
-    <code>for</code>, <code>switch</code>) do not require parentheses in
+    <code>for</code>, <code>switch</code>) do not have parentheses in
     their syntax.
     Also, the operator precedence hierarchy is shorter and clearer, so
 <pre>
@@ -233,9 +233,9 @@ Since the whole declaration is presented, such a comment can often be perfunctor
 <pre>
 // Error codes returned by failures to parse an expression.
 var (
-    ErrInternal      = os.NewError("internal error")
-    ErrUnmatchedLpar = os.NewError("unmatched '('")
-    ErrUnmatchedRpar = os.NewError("unmatched ')'")
+    ErrInternal      = os.NewError("regexp: internal error")
+    ErrUnmatchedLpar = os.NewError("regexp: unmatched '('")
+    ErrUnmatchedRpar = os.NewError("regexp: unmatched ')'")
     ...
 )
 </pre>
@@ -350,7 +350,7 @@ Both names read well in practice:
 <pre>
 owner := obj.Owner()
 if owner != user {
-	obj.SetOwner(user)
+    obj.SetOwner(user)
 }
 </pre>
 
@@ -405,7 +405,7 @@ break continue fallthrough return ++ -- ) }
 <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, add a semicolon&rdquo;.
+after a token that could end a statement, insert a semicolon&rdquo;.
 </p>
 
 <p>
@@ -461,7 +461,7 @@ 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:
-parentheses are not required
+there are no parentheses
 and the bodies must always be brace-delimited.
 </p>
 
@@ -564,7 +564,7 @@ for i := 0; i &lt; 10; i++ {
 <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 for you.
+manage the loop.
 </p>
 <pre>
 var m map[string]int
@@ -943,8 +943,11 @@ Go has two allocation primitives, the built-in functions
 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 essentially the same as its namesakes
-in other languages: <code>new(T)</code> allocates zeroed storage for a new item of type
+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>.
@@ -2245,7 +2248,7 @@ 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 ...) {
+func (job *Job) Logf(format string, args ...interface{}) {
     job.Logger.Logf("%q: %s", job.Command, fmt.Sprintf(format, args))
 }
 </pre>
@@ -2673,6 +2676,13 @@ 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
@@ -2720,7 +2730,7 @@ suppresses the usual check for a <code>return</code> statement.
 <pre>
 // A toy implementation of cube root using Newton's method.
 func CubeRoot(x float64) float64 {
-    z := x/3   // Arbitrary intitial value
+    z := x/3   // Arbitrary initial value
     for i := 0; i &lt; 1e6; i++ {
         prevz := z
         z -= (z*z*z-x) / (3*z*z)
@@ -2916,7 +2926,7 @@ import (
     "http"
     "io"
     "log"
-    "template"
+    "old/template" // New template package coming soon...
 )
 
 var addr = flag.String("addr", ":1718", "http service address") // Q=17, R=18

doc/go_faq.html

@@ -8,6 +8,7 @@ What is the purpose of the project?</h3>
 <p>
 No major systems language has emerged in over a decade, but over that time
 the computing landscape has changed tremendously. There are several trends:
+</p>
 
 <ul>
 <li>
@@ -26,11 +27,11 @@ are not well supported by popular systems languages.
 <li>
 The emergence of multicore computers has generated worry and confusion.
 </ul>
-</p>
 
 <p>
 We believe it's worth trying again with a new language, a concurrent,
 garbage-collected language with fast compilation. Regarding the points above:
+</p>
 
 <ul>
 <li>
@@ -50,7 +51,6 @@ concurrent execution and communication.
 By its design, Go proposes an approach for the construction of system
 software on multicore machines.
 </ul>
-</p>
 
 <h3 id="What_is_the_origin_of_the_name">
 What is the origin of the name?</h3>
@@ -105,7 +105,8 @@ and libraries from prototype to reality.
 </p>
 
 <p>
-Many others have contributed ideas, discussions, and code.
+Go became a public open source project on November 10, 2009.
+Many people from the community have contributed ideas, discussions, and code.
 </p>
 
 <h3 id="creating_a_new_language">
@@ -183,16 +184,6 @@ easier to understand what happens when things combine.
 
 <h2 id="Usage">Usage</h2>
 
-<h3 id="Who_should_use_the_language">
-Who should use the language?</h3>
-
-<p>
-Go is an experiment. We hope adventurous users will give it a try and see
-if they enjoy it. Not every programmer
-will, but we hope enough will find satisfaction in the approach it
-offers to justify further development.
-</p>
-
 <h3 id="Is_Google_using_go_internally"> Is Google using Go internally?</h3>
 
 <p>
@@ -324,7 +315,16 @@ exceptional.
 </p>
 
 <p>
-Go takes a different approach.  Instead of exceptions, it has a couple
+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.
+</p>
+
+<p>
+Go also has a couple
 of built-in functions to signal and recover from truly exceptional
 conditions.  The recovery mechanism is executed only as part of a
 function's state being torn down after an error, which is sufficient
@@ -382,7 +382,7 @@ Why build concurrency on the ideas of CSP?</h3>
 Concurrency and multi-threaded programming have a reputation
 for difficulty.  We believe the problem is due partly to complex
 designs such as pthreads and partly to overemphasis on low-level details
-such as mutexes, condition variables, and even memory barriers.
+such as mutexes, condition variables, and memory barriers.
 Higher-level interfaces enable much simpler code, even if there are still
 mutexes and such under the covers.
 </p>
@@ -400,14 +400,14 @@ Why goroutines instead of threads?</h3>
 <p>
 Goroutines are part of making concurrency easy to use.  The idea, which has
 been around for a while, is to multiplex independently executing
-functions&mdash;coroutines, really&mdash;onto a set of threads.
+functions&mdash;coroutines&mdash;onto a set of threads.
 When a coroutine blocks, such as by calling a blocking system call,
 the run-time automatically moves other coroutines on the same operating
 system thread to a different, runnable thread so they won't be blocked.
 The programmer sees none of this, which is the point.
 The result, which we call goroutines, can be very cheap: unless they spend a lot of time
 in long-running system calls, they cost little more than the memory
-for the stack.
+for the stack, which is just a few kilobytes.
 </p>
 
 <p>
@@ -483,8 +483,8 @@ that specifies a subset of its methods.  Besides reducing the
 bookkeeping, this approach has real advantages.  Types can satisfy
 many interfaces at once, without the complexities of traditional
 multiple inheritance.
-Interfaces can be very lightweight&mdash;having one or even zero methods
-in an interface can express useful concepts.
+Interfaces can be very lightweight&mdash;an interface with
+one or even zero methods can express a useful concept.
 Interfaces can be added after the fact if a new idea comes along
 or for testing&mdash;without annotating the original types.
 Because there are no explicit relationships between types
@@ -504,7 +504,7 @@ stream ciphers.  All these ideas stem from a single interface
 
 <p>
 It takes some getting used to but this implicit style of type
-dependency is one of the most exciting things about Go.
+dependency is one of the most productive things about Go.
 </p>
 
 <h3 id="methods_on_basics">
@@ -598,6 +598,139 @@ the interface idea. Sometimes, though, they're necessary to resolve ambiguities
 among similar interfaces.
 </p>
 
+<h3 id="t_and_equal_interface">
+Why doesn't type T satisfy the Equal interface?</h3>
+
+<p>
+Consider this simple interface to represent an object that can compare
+itself with another value:
+</p>
+
+<pre>
+type Equaler interface {
+	Equal(Equaler) bool
+}
+</pre>
+
+<p>
+and this type, <code>T</code>:
+</p>
+
+<pre>
+type T int
+func (t T) Equal(u T) bool { return t == u } // does not satisfy Equaler
+</pre>
+
+<p>
+Unlike the analogous situation in some polymorphic type systems,
+<code>T</code> does not implement <code>Equaler</code>.
+The argument type of <code>T.Equal</code> is <code>T</code>,
+not literally the required type <code>Equaler</code>.
+</p>
+
+<p>
+In Go, the type system does not promote the argument of
+<code>Equal</code>; that is the programmer's responsibility, as
+illustrated by the type <code>T2</code>, which does implement
+<code>Equaler</code>:
+</p>
+
+<pre>
+type T2 int
+func (t T2) Equal(u Equaler) bool { return t == u.(T2) }  // satisfies Equaler
+</pre>
+
+<p>
+Even this isn't like other type systems, though, because in Go <em>any</em>
+type that satisfies <code>Equaler</code> could be passed as the
+argument to <code>T2.Equal</code>, and at run time we must
+check that the argument is of type <code>T2</code>.
+Some languages arrange to make that guarantee at compile time.
+</p>
+
+<p>
+A related example goes the other way:
+</p>
+
+<pre>
+type Opener interface {
+   Open(name) Reader
+}
+
+func (t T3) Open() *os.File
+</pre>
+
+<p>
+In Go, <code>T3</code> does not satisfy <code>Opener</code>,
+although it might in another language.
+</p>
+
+<p>
+While it is true that Go's type system does less for the programmer
+in such cases, the lack of subtyping makes the rules about
+interface satisfaction very easy to state: are the function's names
+and signatures exactly those of the interface?
+Go's rule is also easy to implement efficiently.
+We feel these benefits offset the lack of
+automatic type promotion. Should Go one day adopt some form of generic
+typing, we expect there would be a way to express the idea of these
+examples and also have them be statically checked.
+</p>
+
+<h3 id="convert_slice_of_interface">
+Can I convert a []T to an []interface{}?</h3>
+
+<p>
+Not directly because they do not have the same representation in memory.
+It is necessary to copy the elements individually to the destination
+slice. This example converts a slice of <code>int</code> to a slice of
+<code>interface{}</code>:
+</p>
+
+<pre>
+t := []int{1, 2, 3, 4}
+s := make([]interface{}, len(t))
+for i, v := range t {
+	s[i] = v
+}
+</pre>
+
+<h3 id="unions">
+Why are there no untagged unions, as in C?</h3>
+
+<p>
+Untagged unions would violate Go's memory safety
+guarantees.
+</p>
+
+<h3 id="variant_types">
+Why does Go not have variant types?</h3>
+
+<p>
+Variant types, also known as algebraic types, provide a way to specify
+that a value might take one of a set of other types, but only those
+types. A common example in systems programming would specify that an
+error is, say, a network error, a security error or an application
+error and allow the caller to discriminate the source of the problem
+by examining the type of the error. Another example is a syntax tree
+in which each node can be a different type: declaration, statement,
+assignment and so on.
+</p>
+
+<p>
+We considered adding variant types to Go, but after discussion
+decided to leave them out because they overlap in confusing ways
+with interfaces. What would happen if the elements of a variant type
+were themselves interfaces?
+</p>
+
+<p>
+Also, some of what variant types address is already covered by the
+language. The error example is easy to express using an interface
+value to hold the error and a type switch to discriminate cases.  The
+syntax tree example is also doable, although not as elegantly.
+</p>
+
 <h2 id="values">Values</h2>
 
 <h3 id="conversions">
@@ -728,17 +861,62 @@ makes a copy of the pointer, but again not the data it points to.
 Should I define methods on values or pointers?</h3>
 
 <pre>
-func (s *MyStruct) someMethod() { } // method on pointer
-func (s MyStruct) someMethod() { }  // method on value
+func (s *MyStruct) pointerMethod() { } // method on pointer
+func (s MyStruct)  valueMethod()   { } // method on value
 </pre>
 
 <p>
+For programmers unaccustomed to pointers, the distinction between these
+two examples can be confusing, but the situation is actually very simple.
 When defining a method on a type, the receiver (<code>s</code> in the above
-example) behaves exactly is if it were an argument to the method. Define the
-method on a pointer type if you need the method to modify the data the receiver
-points to. Otherwise, it is often cleaner to define the method on a value type.
+example) behaves exactly as if it were an argument to the method.
+Whether to define the receiver as a value or as a pointer is the same
+question, then, as whether a function argument should be a value or
+a pointer.
+There are several considerations.
 </p>
 
+<p>
+First, and most important, does the method need to modify the
+receiver?
+If it does, the receiver <em>must</em> be a pointer.
+(Slices and maps are reference types, so their story is a little
+more subtle, but for instance to change the length of a slice
+in a method the receiver must still be a pointer.)
+In the examples above, if <code>pointerMethod</code> modifies
+the fields of <code>s</code>,
+the caller will see those changes, but <code>valueMethod</code>
+is called with a copy of the caller's argument (that's the definition
+of passing a value), so changes it makes will be invisible to the caller.
+</p>
+
+<p>
+By the way, pointer receivers are identical to the situation in Java,
+although in Java the pointers are hidden under the covers; it's Go's
+value receivers that are unusual.
+</p>
+
+<p>
+Second is the consideration of efficiency. If the receiver is large,
+a big <code>struct</code> for instance, it will be much cheaper to
+use a pointer receiver.
+</p>
+
+<p>
+Next is consistency. If some of the methods of the type must have
+pointer receivers, the rest should too, so the method set is
+consistent regardless of how the type is used.
+See the section on <a href="#different_method_sets">method sets</a>
+for details.
+</p>
+
+<p>
+For types such as basic types, slices, and small <code>structs</code>,
+a value receiver is very cheap so unless the semantics of the method
+requires a pointer, a value receiver is efficient and clear.
+</p>
+
+
 <h3 id="new_and_make">
 What's the difference between new and make?</h3>
 
@@ -1045,7 +1223,7 @@ How is the run-time support implemented?</h3>
 Again due to bootstrapping issues, the run-time code is mostly in C (with a
 tiny bit of assembler) although Go is capable of implementing most of
 it now. <code>Gccgo</code>'s run-time support uses <code>glibc</code>.
-<code>Gc</code> uses a custom library, to keep the footprint under
+<code>Gc</code> uses a custom library to keep the footprint under
 control; it is
 compiled with a version of the Plan 9 C compiler that supports
 segmented stacks for goroutines.
@@ -1070,6 +1248,60 @@ that includes more powerful run-time support.  We believe that with some effort
 the size of Go binaries can be reduced.
 </p>
 
+<h3 id="unused_variables_and_imports">
+Can I stop these complaints about my unused variable/import?</h3>
+
+<p>
+The presence of an unused variable may indicate a bug, while
+unused imports just slow down compilation.
+Accumulate enough unused imports in your code tree and
+things can get very slow.
+For these reasons, Go allows neither.
+</p>
+
+<p>
+When developing code, it's common to create these situations
+temporarily and it can be annoying to have to edit them out before the
+program will compile.  
+</p>
+
+<p>
+Some have asked for a compiler option to turn those checks off
+or at least reduce them to warnings.
+Such an option has not been added, though,
+because compiler options should not affect the semantics of the
+language and because the Go compiler does not report warnings, only
+errors that prevent compilation.
+</p>
+
+<p>
+There are two reasons for having no warnings.  First, if it's worth
+complaining about, it's worth fixing in the code.  (And if it's not
+worth fixing, it's not worth mentioning.) Second, having the compiler
+generate warnings encourages the implementation to warn about weak
+cases that can make compilation noisy, masking real errors that
+<em>should</em> be fixed.
+</p>
+
+<p>
+It's easy to address the situation, though.  Use the blank identifier
+to let unused things persist while you're developing.
+</p>
+
+<pre>
+import "unused"
+
+// This declaration marks the import as used by referencing an
+// item from the package.
+var _ = unused.Item  // TODO: Delete before committing!
+
+func main() {
+	debugData := debug.Profile()
+	_ = debugData // Used only during debugging.
+	....
+}
+</pre>
+
 <h2 id="Performance">Performance</h2>
 
 <h3 id="Why_does_Go_perform_badly_on_benchmark_x">
@@ -1103,6 +1335,11 @@ isn't fast enough yet (even if it were, taking care not to generate unnecessary
 garbage can have a huge effect).
 </p>
 
+<p>
+In any case, Go can often be very competitive. See the blog post about
+<a href="http://blog.golang.org/2011/06/profiling-go-programs.html">profiling
+Go programs</a> for an informative example.
+
 <h2 id="change_from_c">Changes from C</h2>
 
 <h3 id="different_syntax">
@@ -1157,7 +1394,9 @@ and <code>chan</code> keep things clear.
 </p>
 
 <p>
-See the <a href="http://blog.golang.org/2010/07/gos-declaration-syntax.html">Go's Declaration Syntax</a> article for more details.
+See the article about
+<a href="http://blog.golang.org/2010/07/gos-declaration-syntax.html">Go's Declaration Syntax</a>
+for more details.
 </p>
 
 <h3 id="no_pointer_arithmetic">
@@ -1244,3 +1483,14 @@ program helps everyone.
 Finally, concurrency aside, garbage collection makes interfaces
 simpler because they don't need to specify how memory is managed across them.
 </p>
+
+<p>
+On the topic of performance, keep in mind that Go gives the programmer
+considerable control over memory layout and allocation, much more than
+is typical in garbage-collected languages. A careful programmer can reduce
+the garbage collection overhead dramatically by using the language well;
+see the article about
+<a href="http://blog.golang.org/2011/06/profiling-go-programs.html">profiling
+Go programs</a> for a worked example, including a demonstration of Go's
+profiling tools.
+</p>

doc/go_mem.html

@@ -1,4 +1,5 @@
 <!-- The Go Memory Model -->
+<!-- subtitle Version of June 10, 2011 -->
 
 <style>
 p.rule {
@@ -42,8 +43,8 @@ Also, if <span class="event">e<sub>1</sub></span> does not happen before <span c
 after <span class="event">e<sub>2</sub></span>, then we say that <span class="event">e<sub>1</sub></span> and <span class="event">e<sub>2</sub></span> happen concurrently.
 </p>
 
-<p>
-Within a single goroutine, the happens before order is the
+<p class="rule">
+Within a single goroutine, the happens-before order is the
 order expressed by the program.
 </p>
 

doc/go_spec.html

@@ -1,5 +1,5 @@
 <!-- title The Go Programming Language Specification -->
-<!-- subtitle Version of June 7, 2011 -->
+<!-- subtitle Version of July 14, 2011 -->
 
 <!--
 TODO
@@ -10,7 +10,6 @@ TODO
 [ ] clarify what a field name is in struct declarations
     (struct{T} vs struct {T T} vs struct {t T})
 [ ] need explicit language about the result type of operations
-[ ] should string(1<<s) and float32(1<<s) be valid?
 [ ] should probably write something about evaluation order of statements even
 	though obvious
 [ ] review language on implicit dereferencing
@@ -529,7 +528,8 @@ A constant value is represented by an
 <a href="#Character_literals">character</a>, or
 <a href="#String_literals">string</a> literal,
 an identifier denoting a constant,
-a <a href="#Constant_expressions">constant expression</a>, or
+a <a href="#Constant_expressions">constant expression</a>,
+a <a href="#Conversions">conversion</a> with a result that is a constant, or
 the result value of some built-in functions such as
 <code>unsafe.Sizeof</code> applied to any value,
 <code>cap</code> or <code>len</code> applied to
@@ -1452,6 +1452,7 @@ Go is lexically scoped using blocks:
 
 	<li>The scope of a constant or variable identifier declared
 	    inside a function begins at the end of the ConstSpec or VarSpec
+	    (ShortVarDecl for short variable declarations)
 	    and ends at the end of the innermost containing block.</li>
 
 	<li>The scope of a type identifier declared inside a function
@@ -3227,8 +3228,42 @@ If the type starts with an operator it must be parenthesized:
 </pre>
 
 <p>
-A value <code>x</code> can be converted to type <code>T</code> in any
-of these cases:
+A <a href="#Constants">constant</a> value <code>x</code> can be converted to
+type <code>T</code> in any of these cases:
+</p>
+
+<ul>
+	<li>
+	<code>x</code> is representable by a value of type <code>T</code>.
+	</li>
+	<li>
+	<code>x</code> is an integer constant and <code>T</code> is a
+	<a href="#String_types">string type</a>.
+	The same rule as for non-constant <code>x</code> applies in this case
+	(§<a href="#Conversions_to_and_from_a_string_type">Conversions to and from a string type</a>).
+	</li>
+</ul>
+
+<p>
+Converting a constant yields a typed constant as result.
+</p>
+
+<pre>
+uint(iota)               // iota value of type uint
+float32(2.718281828)     // 2.718281828 of type float32
+complex128(1)            // 1.0 + 0.0i of type complex128
+string('x')              // "x" of type string
+string(0x266c)           // "♬" of type string
+MyString("foo" + "bar")  // "foobar" of type MyString
+string([]byte{'a'})      // not a constant: []byte{'a'} is not a constant
+(*int)(nil)              // not a constant: nil is not a constant, *int is not a boolean, numeric, or string type
+int(1.2)                 // illegal: 1.2 cannot be represented as an int
+string(65.0)             // illegal: 65.0 is not an integer constant
+</pre>
+
+<p>
+A non-constant value <code>x</code> can be converted to type <code>T</code>
+in any of these cases:
 </p>
 
 <ul>
@@ -3262,15 +3297,27 @@ of these cases:
 </ul>
 
 <p>
-Specific rules apply to conversions between numeric types or to and from
-a string type.
+Specific rules apply to (non-constant) conversions between numeric types or
+to and from a string type.
 These conversions may change the representation of <code>x</code>
 and incur a run-time cost.
 All other conversions only change the type but not the representation
 of <code>x</code>.
 </p>
 
+<p>
+There is no linguistic mechanism to convert between pointers and integers.
+The package <a href="#Package_unsafe"><code>unsafe</code></a>
+implements this functionality under
+restricted circumstances.
+</p>
+
 <h4>Conversions between numeric types</h4>
+
+<p>
+For the conversion of non-constant numeric values, the following rules apply:
+</p>
+
 <ol>
 <li>
 When converting between integer types, if the value is a signed integer, it is
@@ -3296,13 +3343,12 @@ of precision, but <code>float32(x + 0.1)</code> does not.
 </ol>
 
 <p>
-In all conversions involving floating-point or complex values,
+In all non-constant conversions involving floating-point or complex values,
 if the result type cannot represent the value the conversion
-succeeds but the result value is
-implementation-dependent.
+succeeds but the result value is implementation-dependent.
 </p>
 
-<h4>Conversions to and from a string type</h4>
+<h4 id="Conversions_to_and_from_a_string_type">Conversions to and from a string type</h4>
 
 <ol>
 <li>
@@ -3360,12 +3406,6 @@ If the string is empty, the result is <code>[]int(nil)</code>.
 </li>
 </ol>
 
-<p>
-There is no linguistic mechanism to convert between pointers and integers.
-The package <a href="#Package_unsafe"><code>unsafe</code></a>
-implements this functionality under
-restricted circumstances.
-</p>
 
 <h3 id="Constant_expressions">Constant expressions</h3>
 
@@ -3722,7 +3762,7 @@ present, the "else" branch is executed.
 </p>
 
 <pre class="ebnf">
-IfStmt    = "if" [ SimpleStmt ";" ] Expression Block [ "else" Statement ] .
+IfStmt = "if" [ SimpleStmt ";" ] Expression Block [ "else" ( IfStmt | Block ) ] .
 </pre>
 
 <pre>
@@ -4353,8 +4393,8 @@ goto Error
 
 <p>
 Executing the "goto" statement must not cause any variables to come into
-scope that were not already in scope at the point of the goto.  For
-instance, this example:
+<a href="#Declarations_and_scope">scope</a> that were not already in scope at the point of the goto.
+For instance, this example:
 </p>
 
 <pre>
@@ -4366,9 +4406,29 @@ L:
 <p>
 is erroneous because the jump to label <code>L</code> skips
 the creation of <code>v</code>.
-<!--
-(<span class="alert">TODO: Eliminate in favor of used and not set errors?</span>)
--->
+</p>
+
+<p>
+A "goto" statement outside a <a href="#Blocks">block</a> cannot jump to a label inside that block.
+For instance, this example:
+</p>
+
+<pre>
+if n%2 == 1 {
+	goto L1
+}
+for n &gt; 0 {
+	f()
+	n--
+L1:
+	f()
+	n--
+}
+</pre>
+
+<p>
+is erroneous because the label <code>L1</code> is inside 
+the "for" statement's block but the <code>goto</code> is not.
 </p>
 
 <h3 id="Fallthrough_statements">Fallthrough statements</h3>
@@ -4590,11 +4650,14 @@ Two built-in functions assist in common slice operations.
 </p>
 
 <p>
-The function <code>append</code> appends zero or more values <code>x</code>
+The <a href="#Function_types">variadic</a> function <code>append</code>
+appends zero or more values <code>x</code>
 to <code>s</code> of type <code>S</code>, which must be a slice type, and
 returns the resulting slice, also of type <code>S</code>.
-Each value <code>x</code> must be <a href="#Assignability">assignable</a> to
-the <a href="#Slice_types">element type</a> of <code>S</code>.
+The values <code>x</code> are passed to a parameter of type <code>...T</code>
+where <code>T</code> is the <a href="#Slice_types">element type</a> of
+<code>S</code> and the respective
+<a href="#Passing_arguments_to_..._parameters">parameter passing rules</a> apply.
 </p>
 
 <pre class="grammar">
@@ -5102,9 +5165,9 @@ package unsafe
 type ArbitraryType int  // shorthand for an arbitrary Go type; it is not a real type
 type Pointer *ArbitraryType
 
-func Alignof(variable ArbitraryType) int
-func Offsetof(selector ArbitraryType) int
-func Sizeof(variable ArbitraryType) int
+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{})
@@ -5127,7 +5190,7 @@ For a struct <code>s</code> with field <code>f</code>:
 </p>
 
 <pre>
-uintptr(unsafe.Pointer(&amp;s)) + uintptr(unsafe.Offsetof(s.f)) == uintptr(unsafe.Pointer(&amp;s.f))
+uintptr(unsafe.Pointer(&amp;s)) + unsafe.Offsetof(s.f) == uintptr(unsafe.Pointer(&amp;s.f))
 </pre>
 
 <p>
@@ -5140,12 +5203,12 @@ alignment of the (type of the) variable in bytes.  For a variable
 </p>
 
 <pre>
-uintptr(unsafe.Pointer(&amp;x)) % uintptr(unsafe.Alignof(x)) == 0
+uintptr(unsafe.Pointer(&amp;x)) % unsafe.Alignof(x) == 0
 </pre>
 
 <p>
 Calls to <code>Alignof</code>, <code>Offsetof</code>, and
-<code>Sizeof</code> are compile-time constant expressions of type <code>int</code>.
+<code>Sizeof</code> are compile-time constant expressions of type <code>uintptr</code>.
 </p>
 <p>
 The functions <code>unsafe.Typeof</code>,
@@ -5198,10 +5261,12 @@ The following minimal alignment properties are guaranteed:
 </li>
 </ol>
 
-<h2 id="Implementation_differences"><span class="alert">Implementation differences - TODO</span></h2>
+<span class="alert">
+<h2 id="Implementation_differences">Implementation differences - TODO</h2>
 <ul>
-	<li><span class="alert">The restriction on <code>goto</code> statements and targets (no intervening declarations) is not honored.</span></li>
-	<li><span class="alert"><code>len(a)</code> is only a constant if <code>a</code> is a (qualified) identifier denoting an array or pointer to an array.</span></li>
-	<li><span class="alert"><code>nil</code> maps are not treated like empty maps.</span></li>
-	<li><span class="alert">Trying to send/receive from a <code>nil</code> channel causes a run-time panic.</span></li>
+	<li><code>len(a)</code> is only a constant if <code>a</code> is a (qualified) identifier denoting an array or pointer to an array.</li>
+	<li><code>nil</code> maps are not treated like empty maps.</li>
+	<li>Trying to send/receive from a <code>nil</code> channel causes a run-time panic.</li>
+	<li><code>unsafe.Alignof</code>, <code>unsafe.Offsetof</code>, and <code>unsafe.Sizeof</code> return an <code>int</code>.</li>
 </ul>
+</span>

doc/go_tutorial.tmpl

@@ -0,0 +1,990 @@
+<!-- A Tutorial for the Go Programming Language -->
+<h2>Introduction</h2>
+<p>
+This document is a tutorial introduction to the basics of the Go programming
+language, intended for programmers familiar with C or C++. It is not a comprehensive
+guide to the language; at the moment the document closest to that is the
+<a href='/doc/go_spec.html'>language specification</a>.
+After you've read this tutorial, you should look at
+<a href='/doc/effective_go.html'>Effective Go</a>,
+which digs deeper into how the language is used and
+talks about the style and idioms of programming in Go.
+Also, slides from a 3-day course about Go are available.
+They provide some background and a lot of examples:
+<a href='/doc/GoCourseDay1.pdf'>Day 1</a>,
+<a href='/doc/GoCourseDay2.pdf'>Day 2</a>,
+<a href='/doc/GoCourseDay3.pdf'>Day 3</a>.
+<p>
+The presentation here proceeds through a series of modest programs to illustrate
+key features of the language.  All the programs work (at time of writing) and are
+checked into the repository in the directory <a href='/doc/progs'><code>/doc/progs/</code></a>.
+<p>
+<h2>Hello, World</h2>
+<p>
+Let's start in the usual way:
+<p>
+{{code "progs/helloworld.go" `/package/` "$"}}
+<p>
+Every Go source file declares, using a <code>package</code> statement, which package it's part of.
+It may also import other packages to use their facilities.
+This program imports the package <code>fmt</code> to gain access to
+our old, now capitalized and package-qualified, friend, <code>fmt.Printf</code>.
+<p>
+Functions are introduced with the <code>func</code> keyword.
+The <code>main</code> package's <code>main</code> function is where the program starts running (after
+any initialization).
+<p>
+String constants can contain Unicode characters, encoded in UTF-8.
+(In fact, Go source files are defined to be encoded in UTF-8.)
+<p>
+The comment convention is the same as in C++:
+<p>
+<pre>
+/* ... */
+// ...
+</pre>
+<p>
+Later we'll have much more to say about printing.
+<p>
+<h2>Semicolons</h2>
+<p>
+You might have noticed that our program has no semicolons.  In Go
+code, the only place you typically see semicolons is separating the
+clauses of <code>for</code> loops and the like; they are not necessary after
+every statement.
+<p>
+In fact, what happens is that the formal language uses semicolons,
+much as in C or Java, but they are inserted automatically
+at the end of every line that looks like the end of a statement. You
+don't need to type them yourself.
+<p>
+For details about how this is done you can see the language
+specification, but in practice all you need to know is that you
+never need to put a semicolon at the end of a line.  (You can put
+them in if you want to write multiple statements per line.) As an
+extra help, you can also leave out a semicolon immediately before
+a closing brace.
+<p>
+This approach makes for clean-looking, semicolon-free code.  The
+one surprise is that it's important to put the opening
+brace of a construct such as an <code>if</code> statement on the same line as
+the <code>if</code>; if you don't, there are situations that may not compile
+or may give the wrong result.  The language forces the brace style
+to some extent.
+<p>
+<h2>Compiling</h2>
+<p>
+Go is a compiled language.  At the moment there are two compilers.
+<code>Gccgo</code> is a Go compiler that uses the GCC back end.  There is also a
+suite of compilers with different (and odd) names for each architecture:
+<code>6g</code> for the 64-bit x86, <code>8g</code> for the 32-bit x86, and more.  These
+compilers run significantly faster but generate less efficient code
+than <code>gccgo</code>.  At the time of writing (late 2009), they also have
+a more robust run-time system although <code>gccgo</code> is catching up.
+<p>
+Here's how to compile and run our program.  With <code>6g</code>, say,
+<p>
+<pre>
+$ 6g helloworld.go  # compile; object goes into helloworld.6
+$ 6l helloworld.6   # link; output goes into 6.out
+$ ./6.out
+Hello, world; or Καλημέρα κόσμε; or こんにちは 世界
+$
+</pre>
+<p>
+With <code>gccgo</code> it looks a little more traditional.
+<p>
+<pre>
+$ gccgo helloworld.go
+$ a.out
+Hello, world; or Καλημέρα κόσμε; or こんにちは 世界
+$
+</pre>
+<p>
+<h2>Echo</h2>
+<p>
+Next up, here's a version of the Unix utility <code>echo(1)</code>:
+<p>
+{{code "progs/echo.go" `/package/` "$"}}
+<p>
+This program is small but it's doing a number of new things.  In the last example,
+we saw <code>func</code> introduce a function.  The keywords <code>var</code>, <code>const</code>, and <code>type</code>
+(not used yet) also introduce declarations, as does <code>import</code>.
+Notice that we can group declarations of the same sort into
+parenthesized lists, one item per line, as in the <code>import</code> and <code>const</code> clauses here.
+But it's not necessary to do so; we could have said
+<p>
+<pre>
+const Space = " "
+const Newline = "\n"
+</pre>
+<p>
+This program imports the <code>&quot;os&quot;</code> package to access its <code>Stdout</code> variable, of type
+<code>*os.File</code>.  The <code>import</code> statement is actually a declaration: in its general form,
+as used in our ``hello world'' program,
+it names the identifier (<code>fmt</code>)
+that will be used to access members of the package imported from the file (<code>&quot;fmt&quot;</code>),
+found in the current directory or in a standard location.
+In this program, though, we've dropped the explicit name from the imports; by default,
+packages are imported using the name defined by the imported package,
+which by convention is of course the file name itself.  Our ``hello world'' program
+could have said just <code>import &quot;fmt&quot;</code>.
+<p>
+You can specify your
+own import names if you want but it's only necessary if you need to resolve
+a naming conflict.
+<p>
+Given <code>os.Stdout</code> we can use its <code>WriteString</code> method to print the string.
+<p>
+After importing the <code>flag</code> package, we use a <code>var</code> declaration
+to create and initialize a global variable, called <code>omitNewline</code>,
+to hold the value of echo's <code>-n</code> flag. 
+The variable  has type <code>*bool</code>, pointer to <code>bool</code>.
+<p>
+In <code>main.main</code>, we parse the arguments (the call to <code>flag.Parse</code>) and then create a local
+string variable with which to build the output.
+<p>
+The declaration statement has the form
+<p>
+<pre>
+var s string = ""
+</pre>
+<p>
+This is the <code>var</code> keyword, followed by the name of the variable, followed by
+its type, followed by an equals sign and an initial value for the variable.
+<p>
+Go tries to be terse, and this declaration could be shortened.  Since the
+string constant is of type string, we don't have to tell the compiler that.
+We could write
+<p>
+<pre>
+var s = ""
+</pre>
+<p>
+or we could go even shorter and write the idiom
+<p>
+<pre>
+s := ""
+</pre>
+<p>
+The <code>:=</code> operator is used a lot in Go to represent an initializing declaration.
+There's one in the <code>for</code> clause on the next line:
+<p>
+{{code  "progs/echo.go" `/for/`}}
+<p>
+The <code>flag</code> package has parsed the arguments and left the non-flag arguments
+in a list that can be iterated over in the obvious way.
+<p>
+The Go <code>for</code> statement differs from that of C in a number of ways.  First,
+it's the only looping construct; there is no <code>while</code> or <code>do</code>.  Second,
+there are no parentheses on the clause, but the braces on the body
+are mandatory.  The same applies to the <code>if</code> and <code>switch</code> statements.
+Later examples will show some other ways <code>for</code> can be written.
+<p>
+The body of the loop builds up the string <code>s</code> by appending (using <code>+=</code>)
+the arguments and separating spaces. After the loop, if the <code>-n</code> flag is not
+set, the program appends a newline. Finally, it writes the result.
+<p>
+Notice that <code>main.main</code> is a niladic function with no return type.
+It's defined that way.  Falling off the end of <code>main.main</code> means
+''success''; if you want to signal an erroneous return, call
+<p>
+<pre>
+os.Exit(1)
+</pre>
+<p>
+The <code>os</code> package contains other essentials for getting
+started; for instance, <code>os.Args</code> is a slice used by the
+<code>flag</code> package to access the command-line arguments.
+<p>
+<h2>An Interlude about Types</h2>
+<p>
+Go has some familiar types such as <code>int</code> and <code>uint</code> (unsigned <code>int</code>), which represent
+values of the ''appropriate'' size for the machine. It also defines
+explicitly-sized types such as <code>int8</code>, <code>float64</code>, and so on, plus
+unsigned integer types such as <code>uint</code>, <code>uint32</code>, etc.
+These are distinct types; even if <code>int</code> and <code>int32</code> are both 32 bits in size,
+they are not the same type.  There is also a <code>byte</code> synonym for
+<code>uint8</code>, which is the element type for strings.
+<p>
+Floating-point types are always sized: <code>float32</code> and <code>float64</code>,
+plus <code>complex64</code> (two <code>float32s</code>) and <code>complex128</code>
+(two <code>float64s</code>).  Complex numbers are outside the
+scope of this tutorial.
+<p>
+Speaking of <code>string</code>, that's a built-in type as well.  Strings are
+<i>immutable values</i>&mdash;they are not just arrays of <code>byte</code> values.
+Once you've built a string <i>value</i>, you can't change it, although
+of course you can change a string <i>variable</i> simply by
+reassigning it.  This snippet from <code>strings.go</code> is legal code:
+<p>
+{{code "progs/strings.go" `/hello/` `/ciao/`}}
+<p>
+However the following statements are illegal because they would modify
+a <code>string</code> value:
+<p>
+<pre>
+s[0] = 'x'
+(*p)[1] = 'y'
+</pre>
+<p>
+In C++ terms, Go strings are a bit like <code>const strings</code>, while pointers
+to strings are analogous to <code>const string</code> references.
+<p>
+Yes, there are pointers.  However, Go simplifies their use a little;
+read on.
+<p>
+Arrays are declared like this:
+<p>
+<pre>
+var arrayOfInt [10]int
+</pre>
+<p>
+Arrays, like strings, are values, but they are mutable. This differs
+from C, in which <code>arrayOfInt</code> would be usable as a pointer to <code>int</code>.
+In Go, since arrays are values, it's meaningful (and useful) to talk
+about pointers to arrays.
+<p>
+The size of the array is part of its type; however, one can declare
+a <i>slice</i> variable to hold a reference to any array, of any size,
+with the same element type.
+A <i>slice
+expression</i> has the form <code>a[low : high]</code>, representing
+the internal array indexed from <code>low</code> through <code>high-1</code>; the resulting
+slice is indexed from <code>0</code> through <code>high-low-1</code>.
+In short, slices look a lot like arrays but with
+no explicit size (<code>[]</code> vs. <code>[10]</code>) and they reference a segment of
+an underlying, usually anonymous, regular array.  Multiple slices
+can share data if they represent pieces of the same array;
+multiple arrays can never share data.
+<p>
+Slices are much more common in Go programs than
+regular arrays; they're more flexible, have reference semantics,
+and are efficient.  What they lack is the precise control of storage
+layout of a regular array; if you want to have a hundred elements
+of an array stored within your structure, you should use a regular
+array. To create one, use a compound value <i>constructor</i>&mdash;an
+expression formed
+from a type followed by a brace-bounded expression like this:
+<p>
+<pre>
+[3]int{1,2,3}
+</pre>
+<p>
+In this case the constructor builds an array of 3 <code>ints</code>.
+<p>
+When passing an array to a function, you almost always want
+to declare the formal parameter to be a slice.  When you call
+the function, slice the array to create
+(efficiently) a slice reference and pass that.
+By default, the lower and upper bounds of a slice match the
+ends of the existing object, so the concise notation <code>[:]</code>
+will slice the whole array.
+<p>
+Using slices one can write this function (from <code>sum.go</code>):
+<p>
+{{code "progs/sum.go" `/sum/` `/^}/`}}
+<p>
+Note how the return type (<code>int</code>) is defined for <code>sum</code> by stating it
+after the parameter list.
+<p>
+To call the function, we slice the array.  This intricate call (we'll show
+a simpler way in a moment) constructs
+an array and slices it:
+<p>
+<pre>
+s := sum([3]int{1,2,3}[:])
+</pre>
+<p>
+If you are creating a regular array but want the compiler to count the
+elements for you, use <code>...</code> as the array size:
+<p>
+<pre>
+s := sum([...]int{1,2,3}[:])
+</pre>
+<p>
+That's fussier than necessary, though.
+In practice, unless you're meticulous about storage layout within a
+data structure, a slice itself&mdash;using empty brackets with no size&mdash;is all you need:
+<p>
+<pre>
+s := sum([]int{1,2,3})
+</pre>
+<p>
+There are also maps, which you can initialize like this:
+<p>
+<pre>
+m := map[string]int{"one":1 , "two":2}
+</pre>
+<p>
+The built-in function <code>len</code>, which returns number of elements,
+makes its first appearance in <code>sum</code>.  It works on strings, arrays,
+slices, maps, and channels.
+<p>
+By the way, another thing that works on strings, arrays, slices, maps
+and channels is the <code>range</code> clause on <code>for</code> loops.  Instead of writing
+<p>
+<pre>
+for i := 0; i &lt; len(a); i++ { ... }
+</pre>
+<p>
+to loop over the elements of a slice (or map or ...) , we could write
+<p>
+<pre>
+for i, v := range a { ... }
+</pre>
+<p>
+This assigns <code>i</code> to the index and <code>v</code> to the value of the successive
+elements of the target of the range.   See
+<a href='/doc/effective_go.html'>Effective Go</a>
+for more examples of its use.
+<p>
+<p>
+<h2>An Interlude about Allocation</h2>
+<p>
+Most types in Go are values. If you have an <code>int</code> or a <code>struct</code>
+or an array, assignment
+copies the contents of the object.
+To allocate a new variable, use the built-in function <code>new</code>, which
+returns a pointer to the allocated storage.
+<p>
+<pre>
+type T struct { a, b int }
+var t *T = new(T)
+</pre>
+<p>
+or the more idiomatic
+<p>
+<pre>
+t := new(T)
+</pre>
+<p>
+Some types&mdash;maps, slices, and channels (see below)&mdash;have reference semantics.
+If you're holding a slice or a map and you modify its contents, other variables
+referencing the same underlying data will see the modification.  For these three
+types you want to use the built-in function <code>make</code>:
+<p>
+<pre>
+m := make(map[string]int)
+</pre>
+<p>
+This statement initializes a new map ready to store entries.
+If you just declare the map, as in
+<p>
+<pre>
+var m map[string]int
+</pre>
+<p>
+it creates a <code>nil</code> reference that cannot hold anything. To use the map,
+you must first initialize the reference using <code>make</code> or by assignment from an
+existing map.
+<p>
+Note that <code>new(T)</code> returns type <code>*T</code> while <code>make(T)</code> returns type
+<code>T</code>.  If you (mistakenly) allocate a reference object with <code>new</code> rather than <code>make</code>,
+you receive a pointer to a nil reference, equivalent to
+declaring an uninitialized variable and taking its address.
+<p>
+<h2>An Interlude about Constants</h2>
+<p>
+Although integers come in lots of sizes in Go, integer constants do not.
+There are no constants like <code>0LL</code> or <code>0x0UL</code>.   Instead, integer
+constants are evaluated as large-precision values that
+can overflow only when they are assigned to an integer variable with
+too little precision to represent the value.
+<p>
+<pre>
+const hardEight = (1 &lt;&lt; 100) &gt;&gt; 97  // legal
+</pre>
+<p>
+There are nuances that deserve redirection to the legalese of the
+language specification but here are some illustrative examples:
+<p>
+<pre>
+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
+</pre>
+<p>
+Conversions only work for simple cases such as converting <code>ints</code> of one
+sign or size to another and between integers and floating-point numbers,
+plus a couple of other instances outside the scope of a tutorial.
+There are no automatic numeric conversions of any kind in Go,
+other than that of making constants have concrete size and type when
+assigned to a variable.
+<p>
+<h2>An I/O Package</h2>
+<p>
+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 <code>file.go</code>:
+<p>
+{{code "progs/file.go" `/package/` `/^}/`}}
+<p>
+The first few lines declare the name of the
+package&mdash;<code>file</code>&mdash;and then import two packages.  The <code>os</code>
+package hides the differences
+between various operating systems to give a consistent view of files and
+so on; here we're going to use its error handling utilities
+and reproduce the rudiments of its file I/O.
+<p>
+The other item is the low-level, external <code>syscall</code> package, which provides
+a primitive interface to the underlying operating system's calls.
+<p>
+Next is a type definition: the <code>type</code> keyword introduces a type declaration,
+in this case a data structure called <code>File</code>.
+To make things a little more interesting, our <code>File</code> includes the name of the file
+that the file descriptor refers to.
+<p>
+Because <code>File</code> starts with a capital letter, the type is available outside the package,
+that is, by users of the package.   In Go the rule about visibility of information is
+simple: if a name (of a top-level type, function, method, constant or variable, or of
+a structure field or method) is capitalized, users of the package may see it. Otherwise, the
+name and hence the thing being named is visible only inside the package in which
+it is declared.  This is more than a convention; the rule is enforced by the compiler.
+In Go, the term for publicly visible names is ''exported''.
+<p>
+In the case of <code>File</code>, all its fields are lower case and so invisible to users, but we
+will soon give it some exported, upper-case methods.
+<p>
+First, though, here is a factory to create a <code>File</code>:
+<p>
+{{code "progs/file.go" `/newFile/` `/^}/`}}
+<p>
+This returns a pointer to a new <code>File</code> structure with the file descriptor and name
+filled in.  This code uses Go's notion of a ''composite literal'', analogous to
+the ones used to build maps and arrays, to construct a new heap-allocated
+object.  We could write
+<p>
+<pre>
+n := new(File)
+n.fd = fd
+n.name = name
+return n
+</pre>
+<p>
+but for simple structures like <code>File</code> it's easier to return the address of a 
+composite literal, as is done here in the <code>return</code> statement from <code>newFile</code>.
+<p>
+We can use the factory to construct some familiar, exported variables of type <code>*File</code>:
+<p>
+{{code "progs/file.go" `/var/` `/^\)/`}}
+<p>
+The <code>newFile</code> function was not exported because it's internal. The proper,
+exported factory to use is <code>OpenFile</code> (we'll explain that name in a moment):
+<p>
+{{code "progs/file.go" `/func.OpenFile/` `/^}/`}}
+<p>
+There are a number of new things in these few lines.  First, <code>OpenFile</code> returns
+multiple values, a <code>File</code> and an error (more about errors in a moment).
+We declare the
+multi-value return as a parenthesized list of declarations; syntactically
+they look just like a second parameter list.  The function
+<code>syscall.Open</code>
+also has a multi-value return, which we can grab with the multi-variable
+declaration on the first line; it declares <code>r</code> and <code>e</code> to hold the two values,
+both of type <code>int</code> (although you'd have to look at the <code>syscall</code> package
+to see that).  Finally, <code>OpenFile</code> returns two values: a pointer to the new <code>File</code>
+and the error.  If <code>syscall.Open</code> fails, the file descriptor <code>r</code> will
+be negative and <code>newFile</code> will return <code>nil</code>.
+<p>
+About those errors:  The <code>os</code> library includes a general notion of an error.
+It's a good idea to use its facility in your own interfaces, as we do here, for
+consistent error handling throughout Go code.   In <code>Open</code> we use a
+conversion to translate Unix's integer <code>errno</code> value into the integer type
+<code>os.Errno</code>, which implements <code>os.Error</code>.
+<p>
+Why <code>OpenFile</code> and not <code>Open</code>? To mimic Go's <code>os</code> package, which
+our exercise is emulating. The <code>os</code> package takes the opportunity
+to make the two commonest cases - open for read and create for
+write - the simplest, just <code>Open</code> and <code>Create</code>.  <code>OpenFile</code> is the
+general case, analogous to the Unix system call <code>Open</code>.  Here is
+the implementation of our <code>Open</code> and <code>Create</code>; they're trivial
+wrappers that eliminate common errors by capturing
+the tricky standard arguments to open and, especially, to create a file:
+<p>
+{{code "progs/file.go" `/^const/` `/^}/`}}
+<p>
+{{code "progs/file.go" `/func.Create/` `/^}/`}}
+<p>
+Back to our main story.
+Now that we can build <code>Files</code>, we can write methods for them. To declare
+a method of a type, we define a function to have an explicit receiver
+of that type, placed
+in parentheses before the function name. Here are some methods for <code>*File</code>,
+each of which declares a receiver variable <code>file</code>.
+<p>
+{{code "progs/file.go" `/Close/` "$"}}
+<p>
+There is no implicit <code>this</code> and the receiver variable must be used to access
+members of the structure.  Methods are not declared within
+the <code>struct</code> declaration itself.  The <code>struct</code> declaration defines only data members.
+In fact, methods can be created for almost any type you name, such as an integer or
+array, not just for <code>structs</code>.   We'll see an example with arrays later.
+<p>
+The <code>String</code> method is so called because of a printing convention we'll
+describe later.
+<p>
+The methods use the public variable <code>os.EINVAL</code> to return the (<code>os.Error</code>
+version of the) Unix error code <code>EINVAL</code>.  The <code>os</code> library defines a standard
+set of such error values.
+<p>
+We can now use our new package:
+<p>
+{{code "progs/helloworld3.go" `/package/` "$"}}
+<p>
+The ''<code>./</code>'' in the import of ''<code>./file</code>'' tells the compiler
+to use our own package rather than
+something from the directory of installed packages.
+(Also, ''<code>file.go</code>'' must be compiled before we can import the
+package.)
+<p>
+Now we can compile and run the program. On Unix, this would be the result:
+<p>
+<pre>
+$ 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
+$
+</pre>
+<p>
+<h2>Rotting cats</h2>
+<p>
+Building on the <code>file</code> package, here's a simple version of the Unix utility <code>cat(1)</code>,
+<code>progs/cat.go</code>:
+<p>
+{{code "progs/cat.go" `/package/` "$"}}
+<p>
+By now this should be easy to follow, but the <code>switch</code> statement introduces some
+new features.  Like a <code>for</code> loop, an <code>if</code> or <code>switch</code> can include an
+initialization statement.  The <code>switch</code> statement in <code>cat</code> uses one to create variables
+<code>nr</code> and <code>er</code> to hold the return values from the call to <code>f.Read</code>.  (The <code>if</code> a few lines later
+has the same idea.)  The <code>switch</code> 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
+they all have the same type.
+<p>
+Since the <code>switch</code> value is just <code>true</code>, we could leave it off&mdash;as is also
+the situation
+in a <code>for</code> statement, a missing value means <code>true</code>.  In fact, such a <code>switch</code>
+is a form of <code>if-else</code> chain. While we're here, it should be mentioned that in
+<code>switch</code> statements each <code>case</code> has an implicit <code>break</code>.
+<p>
+The argument to <code>file.Stdout.Write</code> is created by slicing the array <code>buf</code>.
+Slices provide the standard Go way to handle I/O buffers.
+<p>
+Now let's make a variant of <code>cat</code> that optionally does <code>rot13</code> on its input.
+It's easy to do by just processing the bytes, but instead we will exploit
+Go's notion of an <i>interface</i>.
+<p>
+The <code>cat</code> subroutine uses only two methods of <code>f</code>: <code>Read</code> and <code>String</code>,
+so let's start by defining an interface that has exactly those two methods.
+Here is code from <code>progs/cat_rot13.go</code>:
+<p>
+{{code "progs/cat_rot13.go" `/type.reader/` `/^}/`}}
+<p>
+Any type that has the two methods of <code>reader</code>&mdash;regardless of whatever
+other methods the type may also have&mdash;is said to <i>implement</i> the
+interface.  Since <code>file.File</code> implements these methods, it implements the
+<code>reader</code> interface.  We could tweak the <code>cat</code> subroutine to accept a <code>reader</code>
+instead of a <code>*file.File</code> and it would work just fine, but let's embellish a little
+first by writing a second type that implements <code>reader</code>, one that wraps an
+existing <code>reader</code> and does <code>rot13</code> 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 <code>reader</code> interface.
+<p>
+{{code "progs/cat_rot13.go" `/type.rotate13/` `/end.of.rotate13/`}}
+<p>
+(The <code>rot13</code> function called in <code>Read</code> is trivial and not worth reproducing here.)
+<p>
+To use the new feature, we define a flag:
+<p>
+{{code "progs/cat_rot13.go" `/rot13Flag/`}}
+<p>
+and use it from within a mostly unchanged <code>cat</code> function:
+<p>
+{{code "progs/cat_rot13.go" `/func.cat/` `/^}/`}}
+<p>
+(We could also do the wrapping in <code>main</code> and leave <code>cat</code> mostly alone, except
+for changing the type of the argument; consider that an exercise.)
+The <code>if</code> at the top of <code>cat</code> sets it all up: If the <code>rot13</code> flag is true, wrap the <code>reader</code>
+we received into a <code>rotate13</code> and proceed.  Note that the interface variables
+are values, not pointers: the argument is of type <code>reader</code>, not <code>*reader</code>,
+even though under the covers it holds a pointer to a <code>struct</code>.
+<p>
+Here it is in action:
+<p>
+<pre>
+$ echo abcdefghijklmnopqrstuvwxyz | ./cat
+abcdefghijklmnopqrstuvwxyz
+$ echo abcdefghijklmnopqrstuvwxyz | ./cat --rot13
+nopqrstuvwxyzabcdefghijklm
+$
+</pre>
+<p>
+Fans of dependency injection may take cheer from how easily interfaces
+allow us to substitute the implementation of a file descriptor.
+<p>
+Interfaces are a distinctive feature of Go.  An interface is implemented by a
+type if the type implements all the methods declared in the interface.
+This means
+that a type may implement an arbitrary number of different interfaces.
+There is no type hierarchy; things can be much more <i>ad hoc</i>,
+as we saw with <code>rot13</code>.  The type <code>file.File</code> implements <code>reader</code>; it could also
+implement a <code>writer</code>, or any other interface built from its methods that
+fits the current situation. Consider the <i>empty interface</i>
+<p>
+<pre>
+type Empty interface {}
+</pre>
+<p>
+<i>Every</i> type implements the empty interface, which makes it
+useful for things like containers.
+<p>
+<h2>Sorting</h2>
+<p>
+Interfaces provide a simple form of polymorphism.  They completely
+separate the definition of what an object does from how it does it, allowing
+distinct implementations to be represented at different times by the
+same interface variable.
+<p>
+As an example, consider this simple sort algorithm taken from <code>progs/sort.go</code>:
+<p>
+{{code "progs/sort.go" `/func.Sort/` `/^}/`}}
+<p>
+The code needs only three methods, which we wrap into sort's <code>Interface</code>:
+<p>
+{{code "progs/sort.go" `/interface/` `/^}/`}}
+<p>
+We can apply <code>Sort</code> to any type that implements <code>Len</code>, <code>Less</code>, and <code>Swap</code>.
+The <code>sort</code> package includes the necessary methods to allow sorting of
+arrays of integers, strings, etc.; here's the code for arrays of <code>int</code>
+<p>
+{{code "progs/sort.go" `/type.*IntSlice/` `/Swap/`}}
+<p>
+Here we see methods defined for non-<code>struct</code> types.  You can define methods
+for any type you define and name in your package.
+<p>
+And now a routine to test it out, from <code>progs/sortmain.go</code>.  This
+uses a function in the <code>sort</code> package, omitted here for brevity,
+to test that the result is sorted.
+<p>
+{{code "progs/sortmain.go" `/func.ints/` `/^}/`}}
+<p>
+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:
+<p>
+{{code "progs/sortmain.go" `/type.day/` `/Swap/`}}
+<p>
+<p>
+<h2>Printing</h2>
+<p>
+The examples of formatted printing so far have been modest.  In this section
+we'll talk about how formatted I/O can be done well in Go.
+<p>
+We've seen simple uses of the package <code>fmt</code>, which
+implements <code>Printf</code>, <code>Fprintf</code>, and so on.
+Within the <code>fmt</code> package, <code>Printf</code> is declared with this signature:
+<p>
+<pre>
+Printf(format string, v ...interface{}) (n int, errno os.Error)
+</pre>
+<p>
+The token <code>...</code> introduces a variable-length argument list that in C would
+be handled using the <code>stdarg.h</code> macros.
+In Go, variadic functions are passed a slice of the arguments of the
+specified type.  In <code>Printf</code>'s case, the declaration says <code>...interface{}</code>
+so the actual type is a slice of empty interface values, <code>[]interface{}</code>.
+<code>Printf</code> can examine the arguments by iterating over the slice
+and, for each element, using a type switch or the reflection library
+to interpret the value.
+It's off topic here but such run-time type analysis
+helps explain some of the nice properties of Go's <code>Printf</code>,
+due to the ability of <code>Printf</code> to discover the type of its arguments
+dynamically.
+<p>
+For example, in C each format must correspond to the type of its
+argument.  It's easier in many cases in Go.  Instead of <code>%llud</code> you
+can just say <code>%d</code>; <code>Printf</code> knows the size and signedness of the
+integer and can do the right thing for you.  The snippet
+<p>
+{{code "progs/print.go" 10 11}}
+<p>
+prints
+<p>
+<pre>
+18446744073709551615 -1
+</pre>
+<p>
+In fact, if you're lazy the format <code>%v</code> will print, in a simple
+appropriate style, any value, even an array or structure.  The output of
+<p>
+{{code "progs/print.go" 14 20}}
+<p>
+is
+<p>
+<pre>
+18446744073709551615 {77 Sunset Strip} [1 2 3 4]
+</pre>
+<p>
+You can drop the formatting altogether if you use <code>Print</code> or <code>Println</code>
+instead of <code>Printf</code>.  Those routines do fully automatic formatting.
+The <code>Print</code> function just prints its elements out using the equivalent
+of <code>%v</code> while <code>Println</code> inserts spaces between arguments
+and adds a newline.  The output of each of these two lines is identical
+to that of the <code>Printf</code> call above.
+<p>
+{{code "progs/print.go" 21 22}}
+<p>
+If you have your own type you'd like <code>Printf</code> or <code>Print</code> to format,
+just give it a <code>String</code> method that returns a string.  The print
+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.
+<p>
+{{code "progs/print_string.go" 9 "$"}}
+<p>
+Since <code>*testType</code> has a <code>String</code> method, the
+default formatter for that type will use it and produce the output
+<p>
+<pre>
+77 Sunset Strip
+</pre>
+<p>
+Observe that the <code>String</code> method calls <code>Sprint</code> (the obvious Go
+variant that returns a string) to do its formatting; special formatters
+can use the <code>fmt</code> library recursively.
+<p>
+Another feature of <code>Printf</code> is that the format <code>%T</code> will print a string
+representation of the type of a value, which can be handy when debugging
+polymorphic code.
+<p>
+It's possible to write full custom print formats with flags and precisions
+and such, but that's getting a little off the main thread so we'll leave it
+as an exploration exercise.
+<p>
+You might ask, though, how <code>Printf</code> can tell whether a type implements
+the <code>String</code> method.  Actually what it does is ask if the value can
+be converted to an interface variable that implements the method.
+Schematically, given a value <code>v</code>, it does this:
+<p>
+<p>
+<pre>
+type Stringer interface {
+    String() string
+}
+</pre>
+<p>
+<pre>
+s, ok := v.(Stringer)  // Test whether v implements "String()"
+if ok {
+    result = s.String()
+} else {
+    result = defaultOutput(v)
+}
+</pre>
+<p>
+The code uses a ``type assertion'' (<code>v.(Stringer)</code>) to test if the value stored in
+<code>v</code> satisfies the <code>Stringer</code> interface; if it does, <code>s</code>
+will become an interface variable implementing the method and <code>ok</code> will
+be <code>true</code>.  We then use the interface variable to call the method.
+(The ''comma, ok'' pattern is a Go idiom used to test the success of
+operations such as type conversion, map update, communications, and so on,
+although this is the only appearance in this tutorial.)
+If the value does not satisfy the interface, <code>ok</code> will be false.
+<p>
+In this snippet the name <code>Stringer</code> follows the convention that we add ''[e]r''
+to interfaces describing simple method sets like this.
+<p>
+One last wrinkle.  To complete the suite, besides <code>Printf</code> etc. and <code>Sprintf</code>
+etc., there are also <code>Fprintf</code> etc.  Unlike in C, <code>Fprintf</code>'s first argument is
+not a file.  Instead, it is a variable of type <code>io.Writer</code>, which is an
+interface type defined in the <code>io</code> library:
+<p>
+<pre>
+type Writer interface {
+    Write(p []byte) (n int, err os.Error)
+}
+</pre>
+<p>
+(This interface is another conventional name, this time for <code>Write</code>; there are also
+<code>io.Reader</code>, <code>io.ReadWriter</code>, and so on.)
+Thus you can call <code>Fprintf</code> on any type that implements a standard <code>Write</code>
+method, not just files but also network channels, buffers, whatever
+you want.
+<p>
+<h2>Prime numbers</h2>
+<p>
+Now we come to processes and communication&mdash;concurrent programming.
+It's a big subject so to be brief we assume some familiarity with the topic.
+<p>
+A classic program in the style is a prime sieve.
+(The sieve of Eratosthenes is computationally more efficient than
+the algorithm presented here, but we are more interested in concurrency than
+algorithmics at the moment.)
+It works by taking a stream of all the natural numbers and introducing
+a sequence of filters, one for each prime, to winnow the multiples of
+that prime.  At each step we have a sequence of filters of the primes
+so far, and the next number to pop out is the next prime, which triggers
+the creation of the next filter in the chain.
+<p>
+Here's a flow diagram; each box represents a filter element whose
+creation is triggered by the first number that flowed from the
+elements before it.
+<p>
+<br>
+<p>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<img src='sieve.gif'>
+<p>
+<br>
+<p>
+To create a stream of integers, we use a Go <i>channel</i>, which,
+borrowing from CSP's descendants, represents a communications
+channel that can connect two concurrent computations.
+In Go, channel variables are references to a run-time object that
+coordinates the communication; as with maps and slices, use
+<code>make</code> to create a new channel.
+<p>
+Here is the first function in <code>progs/sieve.go</code>:
+<p>
+{{code "progs/sieve.go" `/Send/` `/^}/`}}
+<p>
+The <code>generate</code> function sends the sequence 2, 3, 4, 5, ... to its
+argument channel, <code>ch</code>, using the binary communications operator <code>&lt;-</code>.
+Channel operations block, so if there's no recipient for the value on <code>ch</code>,
+the send operation will wait until one becomes available.
+<p>
+The <code>filter</code> function has three arguments: an input channel, an output
+channel, and a prime number.  It copies values from the input to the
+output, discarding anything divisible by the prime.  The unary communications
+operator <code>&lt;-</code> (receive) retrieves the next value on the channel.
+<p>
+{{code "progs/sieve.go" `/Copy.the/` `/^}/`}}
+<p>
+The generator and filters execute concurrently.  Go has
+its own model of process/threads/light-weight processes/coroutines,
+so to avoid notational confusion we call concurrently executing
+computations in Go <i>goroutines</i>.  To start a goroutine,
+invoke the function, prefixing the call with the keyword <code>go</code>;
+this starts the function running in parallel with the current
+computation but in the same address space:
+<p>
+<pre>
+go sum(hugeArray) // calculate sum in the background
+</pre>
+<p>
+If you want to know when the calculation is done, pass a channel
+on which it can report back:
+<p>
+<pre>
+ch := make(chan int)
+go sum(hugeArray, ch)
+// ... do something else for a while
+result := &lt;-ch  // wait for, and retrieve, result
+</pre>
+<p>
+Back to our prime sieve.  Here's how the sieve pipeline is stitched
+together:
+<p>
+{{code "progs/sieve.go" `/func.main/` `/^}/`}}
+<p>
+The first line of <code>main</code> creates the initial channel to pass to <code>generate</code>, which it
+then starts up.  As each prime pops out of the channel, a new <code>filter</code>
+is added to the pipeline and <i>its</i> output becomes the new value
+of <code>ch</code>.
+<p>
+The sieve program can be tweaked to use a pattern common
+in this style of programming.  Here is a variant version
+of <code>generate</code>, from <code>progs/sieve1.go</code>:
+<p>
+{{code "progs/sieve1.go" `/func.generate/` `/^}/`}}
+<p>
+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.
+<p>
+The function literal notation used in the <code>go</code> statement allows us to construct an
+anonymous function and invoke it on the spot. Notice that the local
+variable <code>ch</code> is available to the function literal and lives on even
+after <code>generate</code> returns.
+<p>
+The same change can be made to <code>filter</code>:
+<p>
+{{code "progs/sieve1.go" `/func.filter/` `/^}/`}}
+<p>
+The <code>sieve</code> 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:
+<p>
+{{code "progs/sieve1.go" `/func.sieve/` `/^}/`}}
+<p>
+Now <code>main</code>'s interface to the prime sieve is a channel of primes:
+<p>
+{{code "progs/sieve1.go" `/func.main/` `/^}/`}}
+<p>
+<h2>Multiplexing</h2>
+<p>
+With channels, it's possible to serve multiple independent client goroutines without
+writing an explicit multiplexer.  The trick is to send the server a channel in the message,
+which it will then use to reply to the original sender.
+A realistic client-server program is a lot of code, so here is a very simple substitute
+to illustrate the idea.  It starts by defining a <code>request</code> type, which embeds a channel
+that will be used for the reply.
+<p>
+{{code "progs/server.go" `/type.request/` `/^}/`}}
+<p>
+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:
+<p>
+{{code "progs/server.go" `/type.binOp/` `/^}/`}}
+<p>
+The type declaration makes <code>binOp</code> represent a function taking two integers and
+returning a third.
+<p>
+The <code>server</code> routine loops forever, receiving requests and, to avoid blocking due to
+a long-running operation, starting a goroutine to do the actual work.
+<p>
+{{code "progs/server.go" `/func.server/` `/^}/`}}
+<p>
+We construct a server in a familiar way, starting it and returning a channel
+connected to it:
+<p>
+{{code "progs/server.go" `/func.startServer/` `/^}/`}}
+<p>
+Here's a simple test.  It starts a server with an addition operator and sends out
+<code>N</code> requests without waiting for the replies.  Only after all the requests are sent
+does it check the results.
+<p>
+{{code "progs/server.go" `/func.main/` `/^}/`}}
+<p>
+One annoyance with this program is that it doesn't shut down the server cleanly; when <code>main</code> returns
+there are a number of lingering goroutines blocked on communication.  To solve this,
+we can provide a second, <code>quit</code> channel to the server:
+<p>
+{{code "progs/server1.go" `/func.startServer/` `/^}/`}}
+<p>
+It passes the quit channel to the <code>server</code> function, which uses it like this:
+<p>
+{{code "progs/server1.go" `/func.server/` `/^}/`}}
+<p>
+Inside <code>server</code>, the <code>select</code> statement chooses which of the multiple communications
+listed by its cases can proceed.  If all are blocked, it waits until one can proceed; if
+multiple can proceed, it chooses one at random.  In this instance, the <code>select</code> allows
+the server to honor requests until it receives a quit message, at which point it
+returns, terminating its execution.
+<p>
+<p>
+All that's left is to strobe the <code>quit</code> channel
+at the end of main:
+<p>
+{{code "progs/server1.go" `/adder,.quit/`}}
+...
+{{code "progs/server1.go" `/quit....true/`}}
+<p>
+There's a lot more to Go programming and concurrent programming in general but this
+quick tour should give you some of the basics.

doc/go_tutorial.txt

@@ -1,939 +0,0 @@
-<!-- A Tutorial for the Go Programming Language -->
-Introduction
-----
-
-This document is a tutorial introduction to the basics of the Go programming
-language, intended for programmers familiar with C or C++. It is not a comprehensive
-guide to the language; at the moment the document closest to that is the
-<a href='/doc/go_spec.html'>language specification</a>.
-After you've read this tutorial, you should look at
-<a href='/doc/effective_go.html'>Effective Go</a>,
-which digs deeper into how the language is used and
-talks about the style and idioms of programming in Go.
-Also, slides from a 3-day course about Go are available.
-Although they're badly out of date, they provide some
-background and a lot of examples:
-<a href='/doc/GoCourseDay1.pdf'>Day 1</a>,
-<a href='/doc/GoCourseDay2.pdf'>Day 2</a>,
-<a href='/doc/GoCourseDay3.pdf'>Day 3</a>.
-
-The presentation here proceeds through a series of modest programs to illustrate
-key features of the language.  All the programs work (at time of writing) and are
-checked into the repository in the directory <a href='/doc/progs'>"/doc/progs/"</a>.
-
-Program snippets are annotated with the line number in the original file; for
-cleanliness, blank lines remain blank.
-
-Hello, World
-----
-
-Let's start in the usual way:
-
---PROG progs/helloworld.go /package/ END
-
-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.
-This program imports the package "fmt" to gain access to
-our old, now capitalized and package-qualified, friend, "fmt.Printf".
-
-Functions are introduced with the "func" keyword.
-The "main" package's "main" function is where the program starts running (after
-any initialization).
-
-String constants can contain Unicode characters, encoded in UTF-8.
-(In fact, Go source files are defined to be encoded in UTF-8.)
-
-The comment convention is the same as in C++:
-
-	/* ... */
-	// ...
-
-Later we'll have much more to say about printing.
-
-Semicolons
-----
-
-You might have noticed that our program has no semicolons.  In Go
-code, the only place you typically see semicolons is separating the
-clauses of "for" loops and the like; they are not necessary after
-every statement.
-
-In fact, what happens is that the formal language uses semicolons,
-much as in C or Java, but they are inserted automatically
-at the end of every line that looks like the end of a statement. You
-don't need to type them yourself.
-
-For details about how this is done you can see the language
-specification, but in practice all you need to know is that you
-never need to put a semicolon at the end of a line.  (You can put
-them in if you want to write multiple statements per line.) As an
-extra help, you can also leave out a semicolon immediately before
-a closing brace.
-
-This approach makes for clean-looking, semicolon-free code.  The
-one surprise is that it's important to put the opening
-brace of a construct such as an "if" statement on the same line as
-the "if"; if you don't, there are situations that may not compile
-or may give the wrong result.  The language forces the brace style
-to some extent.
-
-Compiling
-----
-
-Go is a compiled language.  At the moment there are two compilers.
-"Gccgo" is a Go compiler that uses the GCC back end.  There is also a
-suite of compilers with different (and odd) names for each architecture:
-"6g" for the 64-bit x86, "8g" for the 32-bit x86, and more.  These
-compilers run significantly faster but generate less efficient code
-than "gccgo".  At the time of writing (late 2009), they also have
-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 こんにちは 世界
-	$
-
-With "gccgo" it looks a little more traditional.
-
-	$ gccgo helloworld.go
-	$ a.out
-	Hello, world; or Καλημέρα κόσμε; or こんにちは 世界
-	$
-
-Echo
-----
-
-Next up, here's a version of the Unix utility "echo(1)":
-
---PROG progs/echo.go /package/ END
-
-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.
-But it's not necessary to do so; we could have said
-
-	const Space = " "
-	const Newline = "\n"
-
-This program imports the "&quot;os&quot;" package to access its "Stdout" variable, of type
-"*os.File".  The "import" statement is actually a declaration: in its general form,
-as used in our ``hello world'' program,
-it names the identifier ("fmt")
-that will be used to access members of the package imported from the file ("&quot;fmt&quot;"),
-found in the current directory or in a standard location.
-In this program, though, we've dropped the explicit name from the imports; by default,
-packages are imported using the name defined by the imported package,
-which by convention is of course the file name itself.  Our ``hello world'' program
-could have said just "import &quot;fmt&quot;".
-
-You can specify your
-own import names if you want but it's only necessary if you need to resolve
-a naming conflict.
-
-Given "os.Stdout" we can use its "WriteString" method to print the string.
-
-Having imported the "flag" package, line 12 creates a global variable to hold
-the value of echo's "-n" flag. The variable "omitNewline" has type "*bool", pointer
-to "bool".
-
-In "main.main", we parse the arguments (line 20) and then create a local
-string variable we will use to build the output.
-
-The declaration statement has the form
-
-	var s string = ""
-
-This is the "var" keyword, followed by the name of the variable, followed by
-its type, followed by an equals sign and an initial value for the variable.
-
-Go tries to be terse, and this declaration could be shortened.  Since the
-string constant is of type string, we don't have to tell the compiler that.
-We could write
-
-	var s = ""
-
-or we could go even shorter and write the idiom
-
-	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:
-
---PROG  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.
-
-The Go "for" statement differs from that of C in a number of ways.  First,
-it's the only looping construct; there is no "while" or "do".  Second,
-there are no parentheses on the clause, but the braces on the body
-are mandatory.  The same applies to the "if" and "switch" statements.
-Later examples will show some other ways "for" can be written.
-
-The body of the loop builds up the string "s" by appending (using "+=")
-the arguments and separating spaces. After the loop, if the "-n" flag is not
-set, the program appends a newline. Finally, it writes the result.
-
-Notice that "main.main" is a niladic function with no return type.
-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)
-
-The "os" package contains other essentials for getting
-started; for instance, "os.Args" is a slice used by the
-"flag" package to access the command-line arguments.
-
-An Interlude about Types
-----
-
-Go has some familiar types such as "int" and "uint" (unsigned "int"), which represent
-values of the ''appropriate'' size for the machine. It also defines
-explicitly-sized types such as "int8", "float64", and so on, plus
-unsigned integer types such as "uint", "uint32", etc.
-These are distinct types; even if "int" and "int32" are both 32 bits in size,
-they are not the same type.  There is also a "byte" synonym for
-"uint8", which is the element type for strings.
-
-Floating-point types are always sized: "float32" and "float64",
-plus "complex64" (two "float32s") and "complex128"
-(two "float64s").  Complex numbers are outside the
-scope of this tutorial.
-
-Speaking of "string", that's a built-in type as well.  Strings are
-<i>immutable values</i>&mdash;they are not just arrays of "byte" values.
-Once you've built a string <i>value</i>, you can't change it, although
-of course you can change a string <i>variable</i> simply by
-reassigning it.  This snippet from "strings.go" is legal code:
-
---PROG progs/strings.go /hello/ /ciao/
-
-However the following statements are illegal because they would modify
-a "string" value:
-
-	s[0] = 'x'
-	(*p)[1] = 'y'
-
-In C++ terms, Go strings are a bit like "const strings", while pointers
-to strings are analogous to "const string" references.
-
-Yes, there are pointers.  However, Go simplifies their use a little;
-read on.
-
-Arrays are declared like this:
-
-	var arrayOfInt [10]int
-
-Arrays, like strings, are values, but they are mutable. This differs
-from C, in which "arrayOfInt" would be usable as a pointer to "int".
-In Go, since arrays are values, it's meaningful (and useful) to talk
-about pointers to arrays.
-
-The size of the array is part of its type; however, one can declare
-a <i>slice</i> variable to hold a reference to any array, of any size,
-with the same element type.
-A <i>slice
-expression</i> has the form "a[low : high]", representing
-the internal array indexed from "low" through "high-1"; the resulting
-slice is indexed from "0" through "high-low-1".
-In short, slices look a lot like arrays but with
-no explicit size ("[]" vs. "[10]") and they reference a segment of
-an underlying, usually anonymous, regular array.  Multiple slices
-can share data if they represent pieces of the same array;
-multiple arrays can never share data.
-
-Slices are much more common in Go programs than
-regular arrays; they're more flexible, have reference semantics,
-and are efficient.  What they lack is the precise control of storage
-layout of a regular array; if you want to have a hundred elements
-of an array stored within your structure, you should use a regular
-array. To create one, use a compound value <i>constructor</i>&mdash;an
-expression formed
-from a type followed by a brace-bounded expression like this:
-
-	[3]int{1,2,3}
-
-In this case the constructor builds an array of 3 "ints".
-
-When passing an array to a function, you almost always want
-to declare the formal parameter to be a slice.  When you call
-the function, slice the array to create
-(efficiently) a slice reference and pass that.
-By default, the lower and upper bounds of a slice match the
-ends of the existing object, so the concise notation "[:]"
-will slice the whole array.
-
-Using slices one can write this function (from "sum.go"):
-
---PROG progs/sum.go /sum/ /^}/
-
-Note how the return type ("int") is defined for "sum" by stating it
-after the parameter list.
-
-To call the function, we slice the array.  This intricate call (we'll show
-a simpler way in a moment) constructs
-an array and slices it:
-
-	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}[:])
-
-That's fussier than necessary, though.
-In practice, unless you're meticulous about storage layout within a
-data structure, a slice itself&mdash;using empty brackets with no size&mdash;is all you need:
-
-	s := sum([]int{1,2,3})
-
-There are also maps, which you can initialize like this:
-
-	m := map[string]int{"one":1 , "two":2}
-
-The built-in function "len", which returns number of elements,
-makes its first appearance in "sum".  It works on strings, arrays,
-slices, maps, and channels.
-
-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 &lt; len(a); i++ { ... }
-
-to loop over the elements of a slice (or map or ...) , we could write
-
-	for i, v := range a { ... }
-
-This assigns "i" to the index and "v" to the value of the successive
-elements of the target of the range.   See
-<a href='/doc/effective_go.html'>Effective Go</a>
-for more examples of its use.
-
-
-An Interlude about Allocation
-----
-
-Most types in Go are values. If you have an "int" or a "struct"
-or an array, assignment
-copies the contents of the object.
-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)
-
-or the more idiomatic
-
-	t := new(T)
-
-Some types&mdash;maps, slices, and channels (see below)&mdash;have reference semantics.
-If you're holding a slice or a map and you modify its contents, other variables
-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)
-
-This statement initializes a new map ready to store entries.
-If you just declare the map, as in
-
-	var m map[string]int
-
-it creates a "nil" reference that cannot hold anything. To use the map,
-you must first initialize the reference using "make" or by assignment from an
-existing map.
-
-Note that "new(T)" returns type "*T" while "make(T)" returns type
-"T".  If you (mistakenly) allocate a reference object with "new" rather than "make",
-you receive a pointer to a nil reference, equivalent to
-declaring an uninitialized variable and taking its address.
-
-An Interlude about Constants
-----
-
-Although integers come in lots of sizes in Go, integer constants do not.
-There are no constants like "0LL" or "0x0UL".   Instead, integer
-constants are evaluated as large-precision values that
-can overflow only when they are assigned to an integer variable with
-too little precision to represent the value.
-
-	const hardEight = (1 &lt;&lt; 100) &gt;&gt; 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
-
-Conversions only work for simple cases such as converting "ints" of one
-sign or size to another and between integers and floating-point numbers,
-plus a couple of other instances outside the scope of a tutorial.
-There are no automatic numeric conversions of any kind in Go,
-other than that of making constants have concrete size and type when
-assigned to a variable.
-
-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/ /^}/
-
-The first few lines declare the name of the
-package&mdash;"file"&mdash;and then import two packages.  The "os"
-package hides the differences
-between various operating systems to give a consistent view of files and
-so on; here we're going to use its error handling utilities
-and reproduce the rudiments of its file I/O.
-
-The other item is the low-level, external "syscall" package, which provides
-a primitive interface to the underlying operating system's calls.
-
-Next is a type definition: the "type" keyword introduces a type declaration,
-in this case a data structure called "File".
-To make things a little more interesting, our "File" includes the name of the file
-that the file descriptor refers to.
-
-Because "File" starts with a capital letter, the type is available outside the package,
-that is, by users of the package.   In Go the rule about visibility of information is
-simple: if a name (of a top-level type, function, method, constant or variable, or of
-a structure field or method) is capitalized, users of the package may see it. Otherwise, the
-name and hence the thing being named is visible only inside the package in which
-it is declared.  This is more than a convention; the rule is enforced by the compiler.
-In Go, the term for publicly visible names is ''exported''.
-
-In the case of "File", all its fields are lower case and so invisible to users, but we
-will soon give it some exported, upper-case methods.
-
-First, though, here is a factory to create a "File":
-
---PROG 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
-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
-
-but for simple structures like "File" it's easier to return the address of a 
-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/ /^.$/
-
-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/ /^}/
-
-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).
-We declare the
-multi-value return as a parenthesized list of declarations; syntactically
-they look just like a second parameter list.  The function
-"syscall.Open"
-also has a multi-value return, which we can grab with the multi-variable
-declaration on line 31; it declares "r" and "e" to hold the two values,
-both of type "int" (although you'd have to look at the "syscall" package
-to see that).  Finally, line 35 returns two values: a pointer to the new "File"
-and the error.  If "syscall.Open" fails, the file descriptor "r" will
-be negative and "newFile" will return "nil".
-
-About those errors:  The "os" library includes a general notion of an error.
-It's a good idea to use its facility in your own interfaces, as we do here, for
-consistent error handling throughout Go code.   In "Open" we use a
-conversion to translate Unix's integer "errno" value into the integer type
-"os.Errno", which implements "os.Error".
-
-Why "OpenFile" and not "Open"? To mimic Go's "os" package, which
-our exercise is emulating. The "os" package takes the opportunity
-to make the two commonest cases - open for read and create for
-write - the simplest, just "Open" and "Create".  "OpenFile" is the
-general case, analogous to the Unix system call "Open".  Here is
-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/ /^}/
-
---PROG progs/file.go /func.Create/ /^}/
-
-Back to our main story.
-Now that we can build "Files", we can write methods for them. To declare
-a method of a type, we define a function to have an explicit receiver
-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
-
-There is no implicit "this" and the receiver variable must be used to access
-members of the structure.  Methods are not declared within
-the "struct" declaration itself.  The "struct" declaration defines only data members.
-In fact, methods can be created for almost any type you name, such as an integer or
-array, not just for "structs".   We'll see an example with arrays later.
-
-The "String" method is so called because of a printing convention we'll
-describe later.
-
-The methods use the public variable "os.EINVAL" to return the ("os.Error"
-version of the) Unix error code "EINVAL".  The "os" library defines a standard
-set of such error values.
-
-We can now use our new package:
-
---PROG progs/helloworld3.go /package/ END
-
-The ''"./"'' in the import of ''"./file"'' tells the compiler
-to use our own package rather than
-something from the directory of installed packages.
-(Also, ''"file.go"'' must be compiled before we can import the
-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
-	$
-
-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
-
-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
-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
-they all have the same type.
-
-Since the "switch" value is just "true", we could leave it off&mdash;as is also
-the situation
-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.
-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.
-It's easy to do by just processing the bytes, but instead we will exploit
-Go's notion of an <i>interface</i>.
-
-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/ /^}/
-
-Any type that has the two methods of "reader"&mdash;regardless of whatever
-other methods the type may also have&mdash;is said to <i>implement</i> the
-interface.  Since "file.File" implements these methods, it implements the
-"reader" interface.  We could tweak the "cat" subroutine to accept a "reader"
-instead of a "*file.File" and it would work just fine, but let's embellish a little
-first by writing a second type that implements "reader", one that wraps an
-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/
-
-(The "rot13" function called on line 42 is trivial and not worth reproducing here.)
-
-To use the new feature, we define a flag:
-
---PROG progs/cat_rot13.go /rot13Flag/
-
-and use it from within a mostly unchanged "cat" function:
-
---PROG 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"
-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:
-
-<pre>
-	$ echo abcdefghijklmnopqrstuvwxyz | ./cat
-	abcdefghijklmnopqrstuvwxyz
-	$ echo abcdefghijklmnopqrstuvwxyz | ./cat --rot13
-	nopqrstuvwxyzabcdefghijklm
-	$
-</pre>
-
-Fans of dependency injection may take cheer from how easily interfaces
-allow us to substitute the implementation of a file descriptor.
-
-Interfaces are a distinctive feature of Go.  An interface is implemented by a
-type if the type implements all the methods declared in the interface.
-This means
-that a type may implement an arbitrary number of different interfaces.
-There is no type hierarchy; things can be much more <i>ad hoc</i>,
-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 <i>empty interface</i>
-
-<pre>
-	type Empty interface {}
-</pre>
-
-<i>Every</i> type implements the empty interface, which makes it
-useful for things like containers.
-
-Sorting
-----
-
-Interfaces provide a simple form of polymorphism.  They completely
-separate the definition of what an object does from how it does it, allowing
-distinct implementations to be represented at different times by the
-same interface variable.
-
-As an example, consider this simple sort algorithm taken from "progs/sort.go":
-
---PROG progs/sort.go /func.Sort/ /^}/
-
-The code needs only three methods, which we wrap into sort's "Interface":
-
---PROG 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.*IntArray/ /Swap/
-
-Here we see methods defined for non-"struct" types.  You can define methods
-for any type you define and name in your package.
-
-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/ /^}/
-
-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/
-
-
-Printing
-----
-
-The examples of formatted printing so far have been modest.  In this section
-we'll talk about how formatted I/O can be done well in Go.
-
-We've seen simple uses of the package "fmt", which
-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)
-
-The token "..." introduces a variable-length argument list that in C would
-be handled using the "stdarg.h" macros.
-In Go, variadic functions are passed a slice of the arguments of the
-specified type.  In "Printf"'s case, the declaration says "...interface{}"
-so the actual type is a slice of empty interface values, "[]interface{}".
-"Printf" can examine the arguments by iterating over the slice
-and, for each element, using a type switch or the reflection library
-to interpret the value.
-It's off topic here but such run-time type analysis
-helps explain some of the nice properties of Go's "Printf",
-due to the ability of "Printf" to discover the type of its arguments
-dynamically.
-
-For example, in C each format must correspond to the type of its
-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'
-
-prints
-
-	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
-
---PROG progs/print.go 'NR==14' 'NR==20'
-
-is
-
-	18446744073709551615 {77 Sunset Strip} [1 2 3 4]
-
-You can drop the formatting altogether if you use "Print" or "Println"
-instead of "Printf".  Those routines do fully automatic formatting.
-The "Print" function just prints its elements out using the equivalent
-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'
-
-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
-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
-
-Since "*testType" has a "String" method, the
-default formatter for that type will use it and produce the output
-
-	77 Sunset Strip
-
-Observe that the "String" method calls "Sprint" (the obvious Go
-variant that returns a string) to do its formatting; special formatters
-can use the "fmt" library recursively.
-
-Another feature of "Printf" is that the format "%T" will print a string
-representation of the type of a value, which can be handy when debugging
-polymorphic code.
-
-It's possible to write full custom print formats with flags and precisions
-and such, but that's getting a little off the main thread so we'll leave it
-as an exploration exercise.
-
-You might ask, though, how "Printf" can tell whether a type implements
-the "String" method.  Actually what it does is ask if the value can
-be converted to an interface variable that implements the method.
-Schematically, given a value "v", it does this:
-
-
-	type Stringer interface {
-		String() string
-	}
-
-	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
-"v" satisfies the "Stringer" interface; if it does, "s"
-will become an interface variable implementing the method and "ok" will
-be "true".  We then use the interface variable to call the method.
-(The ''comma, ok'' pattern is a Go idiom used to test the success of
-operations such as type conversion, map update, communications, and so on,
-although this is the only appearance in this tutorial.)
-If the value does not satisfy the interface, "ok" will be false.
-
-In this snippet the name "Stringer" follows the convention that we add ''[e]r''
-to interfaces describing simple method sets like this.
-
-One last wrinkle.  To complete the suite, besides "Printf" etc. and "Sprintf"
-etc., there are also "Fprintf" etc.  Unlike in C, "Fprintf"'s first argument is
-not a file.  Instead, it is a variable of type "io.Writer", which is an
-interface type defined in the "io" library:
-
-	type Writer interface {
-		Write(p []byte) (n int, err os.Error)
-	}
-
-(This interface is another conventional name, this time for "Write"; there are also
-"io.Reader", "io.ReadWriter", and so on.)
-Thus you can call "Fprintf" on any type that implements a standard "Write"
-method, not just files but also network channels, buffers, whatever
-you want.
-
-Prime numbers
-----
-
-Now we come to processes and communication&mdash;concurrent programming.
-It's a big subject so to be brief we assume some familiarity with the topic.
-
-A classic program in the style is a prime sieve.
-(The sieve of Eratosthenes is computationally more efficient than
-the algorithm presented here, but we are more interested in concurrency than
-algorithmics at the moment.)
-It works by taking a stream of all the natural numbers and introducing
-a sequence of filters, one for each prime, to winnow the multiples of
-that prime.  At each step we have a sequence of filters of the primes
-so far, and the next number to pop out is the next prime, which triggers
-the creation of the next filter in the chain.
-
-Here's a flow diagram; each box represents a filter element whose
-creation is triggered by the first number that flowed from the
-elements before it.
-
-<br>
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<img src='sieve.gif'>
-
-<br>
-
-To create a stream of integers, we use a Go <i>channel</i>, which,
-borrowing from CSP's descendants, represents a communications
-channel that can connect two concurrent computations.
-In Go, channel variables are references to a run-time object that
-coordinates the communication; as with maps and slices, use
-"make" to create a new channel.
-
-Here is the first function in "progs/sieve.go":
-
---PROG progs/sieve.go /Send/ /^}/
-
-The "generate" function sends the sequence 2, 3, 4, 5, ... to its
-argument channel, "ch", using the binary communications operator "&lt;-".
-Channel operations block, so if there's no recipient for the value on "ch",
-the send operation will wait until one becomes available.
-
-The "filter" function has three arguments: an input channel, an output
-channel, and a prime number.  It copies values from the input to the
-output, discarding anything divisible by the prime.  The unary communications
-operator "&lt;-" (receive) retrieves the next value on the channel.
-
---PROG progs/sieve.go /Copy.the/ /^}/
-
-The generator and filters execute concurrently.  Go has
-its own model of process/threads/light-weight processes/coroutines,
-so to avoid notational confusion we call concurrently executing
-computations in Go <i>goroutines</i>.  To start a goroutine,
-invoke the function, prefixing the call with the keyword "go";
-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
-
-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 := &lt;-ch  // wait for, and retrieve, result
-
-Back to our prime sieve.  Here's how the sieve pipeline is stitched
-together:
-
---PROG progs/sieve.go /func.main/ /^}/
-
-Line 29 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 <i>its</i> output becomes the new value
-of "ch".
-
-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/ /^}/
-
-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
-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/ /^}/
-
-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/ /^}/
-
-Now "main"'s interface to the prime sieve is a channel of primes:
-
---PROG progs/sieve1.go /func.main/ /^}/
-
-Multiplexing
-----
-
-With channels, it's possible to serve multiple independent client goroutines without
-writing an explicit multiplexer.  The trick is to send the server a channel in the message,
-which it will then use to reply to the original sender.
-A realistic client-server program is a lot of code, so here is a very simple substitute
-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/ /^}/
-
-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/ /^}/
-
-Line 14 defines the name "binOp" to be 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/ /^}/
-
-We construct a server in a familiar way, starting it and returning a channel
-connected to it:
-
---PROG 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/ /^}/
-
-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/ /^}/
-
-It passes the quit channel to the "server" function, which uses it like this:
-
---PROG 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
-multiple can proceed, it chooses one at random.  In this instance, the "select" allows
-the server to honor requests until it receives a quit message, at which point it
-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/
-...
---PROG 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.

doc/htmlgen.go

@@ -1,177 +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.
-
-// Process plain text into HTML.
-//	- h2's are made from lines followed by a line "----\n"
-//	- tab-indented blocks become <pre> blocks
-//	- blank lines become <p> marks (except inside <pre> tags)
-//	- "quoted strings" become <code>quoted strings</code>
-
-package main
-
-import (
-	"bufio"
-	"bytes"
-	"log"
-	"os"
-)
-
-var (
-	lines = make([][]byte, 0, 2000) // probably big enough; grows if not
-
-	empty   = []byte("")
-	newline = []byte("\n")
-	tab     = []byte("\t")
-	quote   = []byte(`"`)
-	indent  = []byte{' ', ' ', ' ', ' '}
-
-	sectionMarker = []byte("----\n")
-	preStart      = []byte("<pre>")
-	preEnd        = []byte("</pre>\n")
-	pp            = []byte("<p>\n")
-)
-
-func main() {
-	read()
-	headings()
-	coalesce(preStart, foldPre)
-	coalesce(tab, foldTabs)
-	paragraphs()
-	quotes()
-	write()
-}
-
-func read() {
-	b := bufio.NewReader(os.Stdin)
-	for {
-		line, err := b.ReadBytes('\n')
-		if err == os.EOF {
-			break
-		}
-		if err != nil {
-			log.Fatal(err)
-		}
-		lines = append(lines, line)
-	}
-}
-
-func write() {
-	b := bufio.NewWriter(os.Stdout)
-	for _, line := range lines {
-		b.Write(expandTabs(line))
-	}
-	b.Flush()
-}
-
-// each time prefix is found on a line, call fold and replace
-// 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); {
-		if bytes.HasPrefix(lines[i], prefix) {
-			nlines, block := fold(i)
-			lines[j] = block
-			i += nlines
-		} else {
-			lines[j] = lines[i]
-			i++
-		}
-		j++
-	}
-	lines = lines[0:j]
-}
-
-// return the <pre> block as a single slice
-func foldPre(i int) (n int, line []byte) {
-	buf := new(bytes.Buffer)
-	for i < len(lines) {
-		buf.Write(lines[i])
-		n++
-		if bytes.Equal(lines[i], preEnd) {
-			break
-		}
-		i++
-	}
-	return n, buf.Bytes()
-}
-
-// return the tab-indented block as a single <pre>-bounded slice
-func foldTabs(i int) (n int, line []byte) {
-	buf := new(bytes.Buffer)
-	buf.WriteString("<pre>\n")
-	for i < len(lines) {
-		if !bytes.HasPrefix(lines[i], tab) {
-			break
-		}
-		buf.Write(lines[i])
-		n++
-		i++
-	}
-	buf.WriteString("</pre>\n")
-	return n, buf.Bytes()
-}
-
-func headings() {
-	b := bufio.NewWriter(os.Stdout)
-	for i, l := range lines {
-		if i > 0 && bytes.Equal(l, sectionMarker) {
-			lines[i-1] = []byte("<h2>" + string(trim(lines[i-1])) + "</h2>\n")
-			lines[i] = empty
-		}
-	}
-	b.Flush()
-}
-
-func paragraphs() {
-	for i, l := range lines {
-		if bytes.Equal(l, newline) {
-			lines[i] = pp
-		}
-	}
-}
-
-func quotes() {
-	for i, l := range lines {
-		lines[i] = codeQuotes(l)
-	}
-}
-
-func codeQuotes(l []byte) []byte {
-	if bytes.HasPrefix(l, preStart) {
-		return l
-	}
-	n := bytes.Index(l, quote)
-	if n < 0 {
-		return l
-	}
-	buf := new(bytes.Buffer)
-	inQuote := false
-	for _, c := range l {
-		if c == '"' {
-			if inQuote {
-				buf.WriteString("</code>")
-			} else {
-				buf.WriteString("<code>")
-			}
-			inQuote = !inQuote
-		} else {
-			buf.WriteByte(c)
-		}
-	}
-	return buf.Bytes()
-}
-
-// drop trailing newline
-func trim(l []byte) []byte {
-	n := len(l)
-	if n > 0 && l[n-1] == '\n' {
-		return l[0 : n-1]
-	}
-	return l
-}
-
-// expand tabs to spaces. don't worry about columns.
-func expandTabs(l []byte) []byte {
-	return bytes.Replace(l, tab, indent, -1)
-}

doc/install.html

@@ -81,8 +81,8 @@ To build it, you need these programs installed:
 <li>the standard C libraries, 
 <li>the parser generator Bison,
 <li>GNU <tt>make</tt> (version 3.81 or later),
-<li><tt>awk</tt>, and 
-<li>the text editor <tt>ed</tt>.
+and
+<li><tt>awk</tt>.
 </ul>
 </p>
 
@@ -91,7 +91,7 @@ installed as part of
 <a href="http://developer.apple.com/TOOLS/Xcode/">Xcode</a>. 
 </p>
 
-<p>On Ubuntu/Debian, use <code>sudo apt-get install bison ed gawk gcc libc6-dev
+<p>On Ubuntu/Debian, use <code>sudo apt-get install bison gawk gcc libc6-dev
 make</code>. If you want to build 32-bit binaries on a 64-bit system you'll
 also need the <code>libc6-dev-i386</code> package.
 </p>
@@ -257,7 +257,8 @@ the process of building and testing Go programs.
 <h2 id="next">What's next</h2>
 
 <p>
-Start by reading the <a href="go_tutorial.html">Go Tutorial</a>.
+Start by taking <a href="http://code.google.com/p/go-tour/">A Tour of Go</a>
+or reading the <a href="go_tutorial.html">Go Tutorial</a>.
 </p>
 
 <p>

doc/makehtml

@@ -5,9 +5,8 @@
 
 set -e
 
-TXT=${1:-go_tutorial.txt}		# input file
-HTML=$(basename $TXT .txt).html		# output file (basename)
-TMP=TEMP.txt				# input to htmlgen
+TMPL=${1:-go_tutorial.tmpl}		# input file
+HTML=$(basename $TMPL .tmpl).html		# output file (basename)
 
 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 && ./tmpltohtml $TMPL > $HTML

doc/prog.sh

@@ -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 "<pre> <!-- $* -->"
-
-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/&/\&amp;/g
-	s/"/\&quot;/g
-	s/</\&lt;/g
-	s/>/\&gt;/g
-'
-
-echo '</pre>'

doc/progs/echo.go

@@ -6,18 +6,18 @@ package main
 
 import (
 	"os"
-	"flag"  // command line option parser
+	"flag" // command line option parser
 )
 
 var omitNewline = flag.Bool("n", false, "don't print final newline")
 
 const (
-	Space = " "
+	Space   = " "
 	Newline = "\n"
 )
 
 func main() {
-	flag.Parse()   // Scans the arg list and sets up flags
+	flag.Parse() // Scans the arg list and sets up flags
 	var s string = ""
 	for i := 0; i < flag.NArg(); i++ {
 		if i > 0 {

doc/progs/file_windows.go

@@ -0,0 +1,89 @@
+// 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 file
+
+import (
+	"os"
+	"syscall"
+)
+
+type File struct {
+	fd   syscall.Handle // file descriptor number
+	name string         // file name at Open time
+}
+
+func newFile(fd syscall.Handle, name string) *File {
+	if fd < 0 {
+		return nil
+	}
+	return &File{fd, name}
+}
+
+var (
+	Stdin  = newFile(syscall.Stdin, "/dev/stdin")
+	Stdout = newFile(syscall.Stdout, "/dev/stdout")
+	Stderr = newFile(syscall.Stderr, "/dev/stderr")
+)
+
+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
+}
+
+const (
+	O_RDONLY = syscall.O_RDONLY
+	O_RDWR   = syscall.O_RDWR
+	O_CREATE = syscall.O_CREAT
+	O_TRUNC  = syscall.O_TRUNC
+)
+
+func Open(name string) (file *File, err os.Error) {
+	return OpenFile(name, O_RDONLY, 0)
+}
+
+func Create(name string) (file *File, err os.Error) {
+	return OpenFile(name, O_RDWR|O_CREATE|O_TRUNC, 0666)
+}
+
+func (file *File) Close() os.Error {
+	if file == nil {
+		return os.EINVAL
+	}
+	e := syscall.Close(file.fd)
+	file.fd = syscall.InvalidHandle // so it can't be closed again
+	if e != 0 {
+		return os.Errno(e)
+	}
+	return nil
+}
+
+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
+}
+
+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
+}
+
+func (file *File) String() string {
+	return file.name
+}

doc/progs/helloworld.go

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

doc/progs/helloworld3.go

@@ -15,7 +15,7 @@ func main() {
 	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())
+		fmt.Printf("can't open file; err=%s\n", err.String())
 		os.Exit(1)
 	}
 }

doc/progs/print.go

@@ -7,7 +7,7 @@ package main
 import "fmt"
 
 func main() {
-	var u64 uint64 = 1<<64-1
+	var u64 uint64 = 1<<64 - 1
 	fmt.Printf("%d %d\n", u64, int64(u64))
 
 	// harder stuff

doc/progs/run

@@ -14,8 +14,13 @@ fi
 
 rm -f *.$O
 
+if [ "$GOOS" = "windows" ];then
+	$GC -o file.8 file_windows.go
+else
+	$GC file.go
+fi
+
 for i in \
-	file.go \
 	helloworld.go \
 	helloworld3.go \
 	echo.go \

doc/progs/server.go

@@ -7,8 +7,8 @@ package main
 import "fmt"
 
 type request struct {
-	a, b    int
-	replyc  chan int
+	a, b   int
+	replyc chan int
 }
 
 type binOp func(a, b int) int
@@ -21,7 +21,7 @@ func run(op binOp, req *request) {
 func server(op binOp, service chan *request) {
 	for {
 		req := <-service
-		go run(op, req)  // don't wait for it
+		go run(op, req) // don't wait for it
 	}
 }
 
@@ -42,8 +42,8 @@ func main() {
 		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 {
+	for i := N - 1; i >= 0; i-- { // doesn't matter what order
+		if <-reqs[i].replyc != N+2*i {
 			fmt.Println("fail at", i)
 		}
 	}

doc/progs/server1.go

@@ -7,8 +7,8 @@ package main
 import "fmt"
 
 type request struct {
-	a, b	int
-	replyc	chan int
+	a, b   int
+	replyc chan int
 }
 
 type binOp func(a, b int) int
@@ -22,7 +22,7 @@ func server(op binOp, service chan *request, quit chan bool) {
 	for {
 		select {
 		case req := <-service:
-			go run(op, req)  // don't wait for it
+			go run(op, req) // don't wait for it
 		case <-quit:
 			return
 		}
@@ -47,8 +47,8 @@ func main() {
 		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 {
+	for i := N - 1; i >= 0; i-- { // doesn't matter what order
+		if <-reqs[i].replyc != N+2*i {
 			fmt.Println("fail at", i)
 		}
 	}

doc/progs/sieve.go

@@ -9,7 +9,7 @@ import "fmt"
 // 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'.
+		ch <- i // Send 'i' to channel 'ch'.
 	}
 }
 
@@ -17,17 +17,17 @@ func generate(ch chan int) {
 // 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'.
+		i := <-in // Receive value of new variable 'i' from 'in'.
+		if i%prime != 0 {
+			out <- i // Send 'i' to channel 'out'.
 		}
 	}
 }
 
 // The prime sieve: Daisy-chain filter processes together.
 func main() {
-	ch := make(chan int)  // Create a new channel.
-	go generate(ch)  // Start generate() as a goroutine.
+	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)

doc/progs/sieve1.go

@@ -9,7 +9,7 @@ import "fmt"
 // Send the sequence 2, 3, 4, ... to returned channel 
 func generate() chan int {
 	ch := make(chan int)
-	go func(){
+	go func() {
 		for i := 2; ; i++ {
 			ch <- i
 		}
@@ -22,7 +22,7 @@ func filter(in chan int, prime int) chan int {
 	out := make(chan int)
 	go func() {
 		for {
-			if i := <-in; i % prime != 0 {
+			if i := <-in; i%prime != 0 {
 				out <- i
 			}
 		}

doc/progs/sort.go

@@ -21,7 +21,7 @@ func Sort(data Interface) {
 func IsSorted(data Interface) bool {
 	n := data.Len()
 	for i := n - 1; i > 0; i-- {
-		if data.Less(i, i - 1) {
+		if data.Less(i, i-1) {
 			return false
 		}
 	}
@@ -30,34 +30,30 @@ func IsSorted(data Interface) bool {
 
 // Convenience types for common cases
 
-type IntArray []int
+type IntSlice []int
 
-func (p IntArray) Len() int            { return len(p) }
-func (p IntArray) Less(i, j int) bool  { return p[i] < p[j] }
-func (p IntArray) 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] }
 
+type Float64Slice []float64
 
-type Float64Array []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] }
 
-func (p Float64Array) Len() int            { return len(p) }
-func (p Float64Array) Less(i, j int) bool  { return p[i] < p[j] }
-func (p Float64Array) Swap(i, j int)       { p[i], p[j] = p[j], p[i] }
-
-
-type StringArray []string
-
-func (p StringArray) Len() int            { return len(p) }
-func (p StringArray) Less(i, j int) bool  { return p[i] < p[j] }
-func (p StringArray) 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(IntArray(a)) }
-func SortFloat64s(a []float64)    { Sort(Float64Array(a)) }
-func SortStrings(a []string)  { Sort(StringArray(a)) }
+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(IntArray(a)) }
-func Float64sAreSorted(a []float64) bool   { return IsSorted(Float64Array(a)) }
-func StringsAreSorted(a []string) bool { return IsSorted(StringArray(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)) }

doc/progs/sortmain.go

@@ -11,7 +11,7 @@ import (
 
 func ints() {
 	data := []int{74, 59, 238, -784, 9845, 959, 905, 0, 0, 42, 7586, -5467984, 7586}
-	a := sort.IntArray(data)
+	a := sort.IntSlice(data)
 	sort.Sort(a)
 	if !sort.IsSorted(a) {
 		panic("fail")
@@ -20,7 +20,7 @@ func ints() {
 
 func strings() {
 	data := []string{"monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"}
-	a := sort.StringArray(data)
+	a := sort.StringSlice(data)
 	sort.Sort(a)
 	if !sort.IsSorted(a) {
 		panic("fail")
@@ -28,27 +28,27 @@ func strings() {
 }
 
 type day struct {
-	num        int
-	shortName  string
-	longName   string
+	num       int
+	shortName string
+	longName  string
 }
 
 type dayArray struct {
 	data []*day
 }
 
-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] }
+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] }
 
 func days() {
-	Sunday :=    day{0, "SUN", "Sunday"}
-	Monday :=    day{1, "MON", "Monday"}
-	Tuesday :=   day{2, "TUE", "Tuesday"}
+	Sunday := day{0, "SUN", "Sunday"}
+	Monday := day{1, "MON", "Monday"}
+	Tuesday := day{2, "TUE", "Tuesday"}
 	Wednesday := day{3, "WED", "Wednesday"}
-	Thursday :=  day{4, "THU", "Thursday"}
-	Friday :=    day{5, "FRI", "Friday"}
-	Saturday :=  day{6, "SAT", "Saturday"}
+	Thursday := day{4, "THU", "Thursday"}
+	Friday := day{5, "FRI", "Friday"}
+	Saturday := day{6, "SAT", "Saturday"}
 	data := []*day{&Tuesday, &Thursday, &Wednesday, &Sunday, &Monday, &Friday, &Saturday}
 	a := dayArray{data}
 	sort.Sort(&a)

doc/progs/strings.go

@@ -8,7 +8,9 @@ import "os"
 
 func main() {
 	s := "hello"
-	if s[1] != 'e' { os.Exit(1) }
+	if s[1] != 'e' {
+		os.Exit(1)
+	}
 	s = "good bye"
 	var p *string = &s
 	*p = "ciao"

doc/progs/sum.go

@@ -14,7 +14,6 @@ func sum(a []int) int { // returns an int
 	return s
 }
 
-
 func main() {
 	s := sum([3]int{1, 2, 3}[:]) // a slice of the array is passed to sum
 	fmt.Print(s, "\n")

doc/root.html

@@ -49,10 +49,13 @@ google.setOnLoadCallback(loadFeed);
         It's a fast, statically typed, compiled language that feels like a 
         dynamically typed, interpreted language.
       </p>
-      <h2>Check it out!</h2>
+      <h2>
+        Get started now with
+	<a target="_blank" href="http://go-tour.appspot.com/">A Tour of Go</a>.
+      </h2>
       <p>
       <div class="how">[<a href="/doc/playground.html">How does this work?</a>]</div>
-      <a href="/doc/install.html">Install Go now</a>, or try it right here in your browser:</p>
+      Or try it right here in your browser:</p>
       <div id="playground" class="small"></div>
       <script src="/doc/play/playground.js"></script>
     </div>

doc/talks/io2010/decrypt.go

@@ -2,39 +2,84 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// This code differs from the slides in that it handles errors.
+
 package main
 
 import (
 	"crypto/aes"
-	"crypto/block"
+	"crypto/cipher"
 	"compress/gzip"
 	"io"
+	"log"
 	"os"
 )
 
-func EncryptAndGzip(dstfile, srcfile string, key, iv []byte) {
-	r, _ := os.Open(srcfile, os.O_RDONLY, 0)
+func EncryptAndGzip(dstfile, srcfile string, key, iv []byte) os.Error {
+	r, err := os.Open(srcfile)
+	if err != nil {
+		return err
+	}
 	var w io.Writer
-	w, _ = os.Open(dstfile, os.O_WRONLY|os.O_CREATE, 0666)
-	c, _ := aes.NewCipher(key)
-	w = block.NewOFBWriter(c, iv, w)
-	w2, _ := gzip.NewDeflater(w)
-	io.Copy(w2, r)
-	w2.Close()
+	w, err = os.Create(dstfile)
+	if err != nil {
+		return err
+	}
+	c, err := aes.NewCipher(key)
+	if err != nil {
+		return err
+	}
+	w = cipher.StreamWriter{S: cipher.NewOFB(c, iv), W: w}
+	w2, err := gzip.NewWriter(w)
+	if err != nil {
+		return err
+	}
+	defer w2.Close()
+	_, err = io.Copy(w2, r)
+	return err
 }
 
-func DecryptAndGunzip(dstfile, srcfile string, key, iv []byte) {
-	f, _ := os.Open(srcfile, os.O_RDONLY, 0)
+func DecryptAndGunzip(dstfile, srcfile string, key, iv []byte) os.Error {
+	f, err := os.Open(srcfile)
+	if err != nil {
+		return err
+	}
 	defer f.Close()
-	c, _ := aes.NewCipher(key)
-	r := block.NewOFBReader(c, iv, f)
-	r, _ = gzip.NewInflater(r)
-	w, _ := os.Open(dstfile, os.O_WRONLY|os.O_CREATE, 0666)
+	c, err := aes.NewCipher(key)
+	if err != nil {
+		return err
+	}
+	r := cipher.StreamReader{S: cipher.NewOFB(c, iv), R: f}
+	r2, err := gzip.NewReader(r)
+	if err != nil {
+		return err
+	}
+	w, err := os.Create(dstfile)
+	if err != nil {
+		return err
+	}
 	defer w.Close()
-	io.Copy(w, r)
+	_, err = io.Copy(w, r2)
+	return err
 }
 
 func main() {
-	EncryptAndGzip("/tmp/passwd.gz", "/etc/passwd", make([]byte, 16), make([]byte, 16))
-	DecryptAndGunzip("/dev/stdout", "/tmp/passwd.gz", make([]byte, 16), make([]byte, 16))
+	err := EncryptAndGzip(
+		"/tmp/passwd.gz",
+		"/etc/passwd",
+		make([]byte, 16),
+		make([]byte, 16),
+	)
+	if err != nil {
+		log.Fatal(err)
+	}
+	err = DecryptAndGunzip(
+		"/dev/stdout",
+		"/tmp/passwd.gz",
+		make([]byte, 16),
+		make([]byte, 16),
+	)
+	if err != nil {
+		log.Fatal(err)
+	}
 }

doc/talks/io2010/encrypt.go

@@ -2,27 +2,51 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// This code differs from the slides in that it handles errors.
+
 package main
 
 import (
 	"crypto/aes"
-	"crypto/block"
+	"crypto/cipher"
 	"compress/gzip"
 	"io"
+	"log"
 	"os"
 )
 
-func EncryptAndGzip(dstfile, srcfile string, key, iv []byte) {
-	r, _ := os.Open(srcfile, os.O_RDONLY, 0)
+func EncryptAndGzip(dstfile, srcfile string, key, iv []byte) os.Error {
+	r, err := os.Open(srcfile)
+	if err != nil {
+		return err
+	}
 	var w io.WriteCloser
-	w, _ = os.Open(dstfile, os.O_WRONLY|os.O_CREATE, 0666)
+	w, err = os.Create(dstfile)
+	if err != nil {
+		return err
+	}
 	defer w.Close()
-	w, _ = gzip.NewDeflater(w)
+	w, err = gzip.NewWriter(w)
+	if err != nil {
+		return err
+	}
 	defer w.Close()
-	c, _ := aes.NewCipher(key)
-	io.Copy(block.NewCBCEncrypter(c, iv, w), r)
+	c, err := aes.NewCipher(key)
+	if err != nil {
+		return err
+	}
+	_, err = io.Copy(cipher.StreamWriter{S: cipher.NewOFB(c, iv), W: w}, r)
+	return err
 }
 
 func main() {
-	EncryptAndGzip("/tmp/passwd.gz", "/etc/passwd", make([]byte, 16), make([]byte, 16))
+	err := EncryptAndGzip(
+		"/tmp/passwd.gz",
+		"/etc/passwd",
+		make([]byte, 16),
+		make([]byte, 16),
+	)
+	if err != nil {
+		log.Fatal(err)
+	}
 }

doc/tmpltohtml.go

@@ -0,0 +1,176 @@
+// 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.
+package main
+
+import (
+	"exp/template"
+	"flag"
+	"fmt"
+	"io/ioutil"
+	"log"
+	"os"
+	"regexp"
+	"strings"
+)
+
+func Usage() {
+	fmt.Fprintf(os.Stderr, "usage: tmpltohtml file\n")
+	os.Exit(2)
+}
+
+func main() {
+	flag.Usage = Usage
+	flag.Parse()
+	if len(flag.Args()) != 1 {
+		Usage()
+	}
+
+	// Read and parse the input.
+	name := flag.Args()[0]
+	tmpl := template.New(name).Funcs(template.FuncMap{"code": code})
+	if _, err := tmpl.ParseFile(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 code(file string, arg ...interface{}) (string, os.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)
+	}
+	// 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.Fatal("lines out of order for %q: %d %d", line1, line2)
+	}
+	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.Fatal("%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
+}

include/libc.h

@@ -292,16 +292,20 @@ extern	char*	getgoroot(void);
 extern	char*	getgoversion(void);
 
 #ifdef _WIN32
+
+#ifndef _WIN64
 struct timespec {
 	int tv_sec;
 	long tv_nsec;
 };
+#define execv(prog, argv) execv(prog, (const char* const*)(argv))
+#define execvp(prog, argv) execvp(prog, (const char**)(argv))
+#endif
+
 extern int nanosleep(const struct timespec *rqtp, struct timespec *rmtp);
 extern int fork(void);
 extern int pread(int fd, void *buf, int n, int off);
 extern int pwrite(int fd, void *buf, int n, int off);
-#define execv(prog, argv) execv(prog, (const char* const*)(argv))
-#define execvp(prog, argv) execvp(prog, (const char**)(argv))
 #define lseek(fd, n, base) _lseeki64(fd, n, base)
 #define mkdir(path, perm) mkdir(path)
 #define pipe(fd) _pipe(fd, 512, O_BINARY)

include/u.h

@@ -69,6 +69,7 @@ extern "C" {
 #include <math.h>
 #include <ctype.h>	/* for tolower */
 #include <signal.h>
+#include <time.h>
 
 /*
  * OS-specific crap
@@ -193,6 +194,8 @@ typedef u64int uint64;
 #undef _NEEDUINT
 #undef _NEEDULONG
 
+#define getcallerpc(x)	__builtin_return_address(0)
+
 #ifndef SIGBUS
 #define SIGBUS SIGSEGV /* close enough */
 #endif

lib/codereview/codereview.py

@@ -75,6 +75,12 @@ except:
 	def findcommonincoming(repo, remote):
 		return repo.findcommonincoming(remote)
 
+# in Mercurial 1.9 the cmdutil.match and cmdutil.revpair moved to scmutil
+if hgversion >= '1.9':
+    from mercurial import scmutil
+else:
+    scmutil = cmdutil
+
 oldMessage = """
 The code review extension requires Mercurial 1.3 or newer.
 
@@ -713,14 +719,14 @@ _change_prolog = """# Change list.
 # Get effective change nodes taking into account applied MQ patches
 def effective_revpair(repo):
     try:
-	return cmdutil.revpair(repo, ['qparent'])
+	return scmutil.revpair(repo, ['qparent'])
     except:
-	return cmdutil.revpair(repo, None)
+	return scmutil.revpair(repo, None)
 
 # Return list of changed files in repository that match pats.
 # Warn about patterns that did not match.
 def matchpats(ui, repo, pats, opts):
-	matcher = cmdutil.match(repo, pats, opts)
+	matcher = scmutil.match(repo, pats, opts)
 	node1, node2 = effective_revpair(repo)
 	modified, added, removed, deleted, unknown, ignored, clean = repo.status(node1, node2, matcher, ignored=True, clean=True, unknown=True)
 	return (modified, added, removed, deleted, unknown, ignored, clean)
@@ -827,7 +833,6 @@ Examples:
 
 '''
 
-	
 
 def promptremove(ui, repo, f):
 	if promptyesno(ui, "hg remove %s (y/n)?" % (f,)):
@@ -959,6 +964,11 @@ def ReplacementForCmdutilMatch(repo, pats=None, opts=None, globbed=False, defaul
 				raise util.Abort("no files in CL " + clname)
 			files = Add(files, cl.files)
 	pats = Sub(pats, taken) + ['path:'+f for f in files]
+
+	# work-around for http://selenic.com/hg/rev/785bbc8634f8
+	if hgversion >= '1.9' and not hasattr(repo, 'match'):
+		repo = repo[None]
+
 	return original_match(repo, pats=pats, opts=opts, globbed=globbed, default=default)
 
 def RelativePath(path, cwd):
@@ -1292,7 +1302,7 @@ def clpatch_or_undo(ui, repo, clname, opts, mode):
 		# sequence numbers get to be 7 digits long.
 		if re.match('^[0-9]{7,}$', clname):
 			found = False
-			matchfn = cmdutil.match(repo, [], {'rev': None})
+			matchfn = scmutil.match(repo, [], {'rev': None})
 			def prep(ctx, fns):
 				pass
 			for ctx in cmdutil.walkchangerevs(repo, matchfn, {'rev': None}, prep):
@@ -1316,7 +1326,7 @@ def clpatch_or_undo(ui, repo, clname, opts, mode):
 		# Create fresh CL and start with patch that would reverse the change.
 		vers = short(rev.node())
 		cl = CL("new")
-		desc = rev.description()
+		desc = str(rev.description())
 		if mode == "undo":
 			cl.desc = (undoHeader % (clname, vers)) + desc + undoFooter
 		else:
@@ -1352,10 +1362,12 @@ def clpatch_or_undo(ui, repo, clname, opts, mode):
 			repo[vers].description()
 		except:
 			return "local repository is out of date; sync to get %s" % (vers)
-		patch, err = portPatch(repo, patch, vers, id)
+		patch1, err = portPatch(repo, patch, vers, id)
 		if err != "":
-			return "codereview issue %s is out of date: %s (%s->%s)" % (clname, err, vers, id)
-
+			if not opts["ignore_hgpatch_failure"]:
+				return "codereview issue %s is out of date: %s (%s->%s)" % (clname, err, vers, id)
+		else:
+			patch = patch1
 	argv = ["hgpatch"]
 	if opts["no_incoming"] or mode == "backport":
 		argv += ["--checksync=false"]
@@ -1369,7 +1381,7 @@ def clpatch_or_undo(ui, repo, clname, opts, mode):
 		return "hgpatch failed"
 	cl.local = True
 	cl.files = out.strip().split()
-	if not cl.files:
+	if not cl.files and not opts["ignore_hgpatch_failure"]:
 		return "codereview issue %s has no changed files" % clname
 	files = ChangedFiles(ui, repo, [], opts)
 	extra = Sub(cl.files, files)
@@ -1605,8 +1617,8 @@ def reposetup(ui, repo):
 	global original_match
 	if original_match is None:
 		start_status_thread()
-		original_match = cmdutil.match
-		cmdutil.match = ReplacementForCmdutilMatch
+		original_match = scmutil.match
+		scmutil.match = ReplacementForCmdutilMatch
 		RietveldSetup(ui, repo)
 
 def CheckContributor(ui, repo, user=None):
@@ -1710,6 +1722,7 @@ def submit(ui, repo, *pats, **opts):
 		print Indent('\n'.join(cl.files), "\t")
 		return "dry run; not submitted"
 
+	set_status("pushing " + cl.name + " to remote server")
 	m = match.exact(repo.root, repo.getcwd(), cl.files)
 	node = repo.commit(ustr(opts['message']), ustr(userline), opts.get('date'), m)
 	if not node:
@@ -1781,7 +1794,7 @@ def sync(ui, repo, **opts):
 		err = commands.postincoming(ui, repo, modheads, True, "tip")
 		if err:
 			return err
-	commands.update(ui, repo)
+	commands.update(ui, repo, rev="default")
 	sync_changes(ui, repo)
 
 def sync_note(msg):
@@ -1826,7 +1839,7 @@ def sync_changes(ui, repo):
 				break
 			Rev(rev)
 	else:
-		matchfn = cmdutil.match(repo, [], {'rev': None})
+		matchfn = scmutil.match(repo, [], {'rev': None})
 		def prep(ctx, fns):
 			pass
 		for ctx in cmdutil.walkchangerevs(repo, matchfn, {'rev': None}, prep):
@@ -1845,7 +1858,7 @@ def sync_changes(ui, repo):
 			cl.Flush(ui, repo)
 		if not cl.files:
 			if not cl.copied_from:
-				ui.warn("CL %s has no files; delete with hg change -d %s\n" % (cl.name, cl.name))
+				ui.warn("CL %s has no files; delete (abandon) with hg change -d %s\n" % (cl.name, cl.name))
 			else:
 				ui.warn("CL %s has no files; delete locally with hg change -D %s\n" % (cl.name, cl.name))
 	return

lib/godoc/codewalk.html

@@ -18,9 +18,9 @@
           <img title="View code in new window" alt="Pop Out Code" src="/doc/codewalk/popout.png" style="display: block; float: right;"/>
         </a>
         <select id="code-selector">
-          {.repeated section File}
-          <option value="/doc/codewalk/?fileprint=/{@|html-esc}">{@|html-esc}</option>
-          {.end}
+          {{range .File}}
+          <option value="/doc/codewalk/?fileprint=/{{urlquery .}}">{{html .}}</option>
+          {{end}}
         </select>
       </div>
       <div id="code">
@@ -35,19 +35,19 @@
   </div>
   <div class="right" id="comment-column">
     <div id="comment-area">
-      {.repeated section Step}
+      {{range .Step}}
       <div class="comment first last">
-        <a class="comment-link" href="/doc/codewalk/?fileprint=/{File|html-esc}&lo={Lo|html-esc}&hi={Hi|html-esc}#mark" target="code-display"></a>
-        <div class="comment-title">{Title|html-esc}</div>
+        <a class="comment-link" href="/doc/codewalk/?fileprint=/{{urlquery .File}}&lo={{urlquery .Lo}}&hi={{urlquery .Hi}}#mark" target="code-display"></a>
+        <div class="comment-title">{{html .Title}}</div>
         <div class="comment-text">
-        {.section Err}
-        ERROR LOADING FILE: {Err|html-esc}<br/><br/>
-        {.end}
-        {XML}
+	{{with .Err}}
+	ERROR LOADING FILE: {{html .}}<br/><br/>
+	{{end}}
+        {{.XML}}
         </div>
-        <div class="comment-text file-name"><span class="path-file">{@|html-esc}</span></div>
+        <div class="comment-text file-name"><span class="path-file">{{html .}}</span></div>
       </div>
-      {.end}
+      {{end}}
     </div>
     <div id="comment-options" class="setting">
       <a id="prev-comment" href="#"><span class="hotkey">p</span>revious step</a>

lib/godoc/codewalkdir.html

@@ -5,11 +5,12 @@
 -->
 
 <table class="layout">
-{.repeated section @}
+{{range .}}
 <tr>
-    <td><a href="{Name|html-esc}">{Name|html-esc}</a></td>
-    <td width="25">&nbsp;</td>
-    <td>{Title|html-esc}</td>
+	{{$name_html := html .Name}}
+	<td><a href="{{$name_html}}">{{$name_html}}</a></td>
+	<td width="25">&nbsp;</td>
+	<td>{{html .Title}}</td>
 </tr>
-{.end}
+{{end}}
 </table>

lib/godoc/dirlist.html

@@ -16,14 +16,16 @@
 <tr>
 	<td><a href="..">..</a></td>
 </tr>
-{.repeated section @}
+{{range .}}
 <tr>
-	<td align="left"><a href="{Name|html-esc}{@|dir/}">{Name|html-esc}{@|dir/}</a></td>
+	{{$name_html := fileInfoName . | html}}
+	<td align="left"><a href="{{$name_html}}">{{$name_html}}</a></td>
 	<td></td>
-	<td align="right">{Size|html-esc}</td>
+	<td align="right">{{html .Size}}</td>
 	<td></td>
-	<td align="left">{Mtime_ns|time}</td>
+	<td align="left">{{fileInfoTime . | html}}</td>
 </tr>
-{.end}
+{{end}}
+
 </table>
 </p>

lib/godoc/error.html

@@ -5,5 +5,5 @@
 -->
 
 <p>
-<span class="alert" style="font-size:120%">{@|html-esc}</span>
+<span class="alert" style="font-size:120%">{{html .}}</span>
 </p>

lib/godoc/godoc.html

@@ -2,11 +2,11 @@
 <html>
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
-{.section Title}
-  <title>{@|html-esc} - The Go Programming Language</title>
-{.or}
+{{with .Title}}
+  <title>{{html .}} - The Go Programming Language</title>
+{{else}}
   <title>The Go Programming Language</title>
-{.end}
+{{end}}
 <link rel="stylesheet" href="/doc/all.css" type="text/css" media="all" charset="utf-8">
 <!--[if lt IE 8]>
 <link rel="stylesheet" href="/doc/ie.css" type="text/css">
@@ -23,19 +23,17 @@
       </ul>
       <div class="quickref">
         <form method="GET" action="/search">
-        {.section PkgRoots}
-        {.repeated section PkgRoots}
-        <a href="/pkg/{@|html-esc}">{@|html-esc}</a> <span class="sep">|</span>
-        {.end}
-        {.or}
+        {{range .PkgRoots}}
+        <a href="/pkg/{{html .}}">{{html .}}</a> <span class="sep">|</span>
+        {{else}}
         References:
-        {.end}
+        {{end}}
         <a href="/pkg/">Packages</a> <span class="sep">|</span>
         <a href="/cmd/">Commands</a> <span class="sep">|</span>
         <a href="/doc/go_spec.html">Specification</a>
-	{.section SearchBox}
-        <input id="search" type="search" name="q" value="{.section Query}{Query|html-esc}{.end}" class="{.section Query}{.or}inactive{.end}" placeholder="code search" results="0" />
-	{.end}
+	{{if .SearchBox}}
+        <input id="search" type="search" name="q" value="{{with .Query}}{{html .}}{{end}}" class="{{if not .Query}}inactive{{end}}" placeholder="code search" results="0" />
+	{{end}}
         </form>
       </div>
     </div>
@@ -43,28 +41,28 @@
   </div>
   <div id="content">
   <!-- Menu is HTML-escaped elsewhere -->
-  {.section Menu}
+  {{with .Menu}}
     <div id="menu">
-      {@}
+      {{printf "%s" .}}
     </div>
-  {.end}
+  {{end}}
 
-  {.section Title}
-    <h1 id="generatedHeader">{@|html-esc}</h1>
-  {.end}
-  {.section Subtitle}
-    <span class="subtitle">{@|html-esc}</span>
-  {.end}
+  {{with .Title}}
+    <h1 id="generatedHeader">{{html .}}</h1>
+  {{end}}
+  {{with .Subtitle}}
+    <span class="subtitle">{{html .}}</span>
+  {{end}}
 
   <!-- The Table of Contents is automatically inserted in this <div>.
        Do not delete this <div>. -->
   <div id="nav"></div>
 
   <!-- Content is HTML-escaped elsewhere -->
-  {Content}
+  {{printf "%s" .Content}}
   </div>
   <div id="site-info">
-    <p>Build version {Version|html-esc}. Except as noted, this content is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 License</a>.</p>
+    <p>Build version {{html .Version}}. Except as noted, this content is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 License</a>.</p>
   </div>
 </div>
 </body>

lib/godoc/package.html

@@ -3,119 +3,120 @@
 	Use of this source code is governed by a BSD-style
 	license that can be found in the LICENSE file.
 -->
-
-{.section PAst}
-	<pre>{@ FSet|html-esc}</pre>
-{.end}
-{.section PDoc}
+{{with .PAst}}
+	<pre>{{node_html . $.FSet}}</pre>
+{{end}}
+{{with .PDoc}}
 	<!-- PackageName is printed as title by the top-level template -->
-	{.section IsPkg}
-		{# ImportPath is a string - no need for FSet}
-		<p><code>import "{ImportPath|html-esc}"</code></p>
-	{.end}
-	{Doc|html-comment}
-	{.section IsPkg}
-		{.section Filenames}
-			{# Filenames are strings - no need for FSet}
+	{{if $.IsPkg}}
+		<p><code>import "{{html .ImportPath}}"</code></p>
+	{{end}}
+	{{comment_html .Doc}}
+	{{if $.IsPkg}}
+		{{with .Filenames}}
 			<p>
 			<h4>Package files</h4>
 			<span style="font-size:90%">
-			{.repeated section @}
-				<a href="/{@|url-src}">{@|localname}</a>
-			{.end}
+			{{range .}}
+				<a href="/{{.|srcLink}}">{{.|filename|html}}</a>
+			{{end}}
 			</span>
 			</p>
-		{.end}
-	{.end}
-	{.section Consts}
+		{{end}}
+	{{end}}
+	{{with .Consts}}
 		<h2 id="Constants">Constants</h2>
-		{.repeated section @}
-			{Doc|html-comment}
-			<pre>{Decl FSet|html-esc}</pre>
-		{.end}
-	{.end}
-	{.section Vars}
+		{{range .}}
+			{{comment_html .Doc}}
+			<pre>{{node_html .Decl $.FSet}}</pre>
+		{{end}}
+	{{end}}
+	{{with .Vars}}
 		<h2 id="Variables">Variables</h2>
-		{.repeated section @}
-			{Doc|html-comment}
-			<pre>{Decl FSet|html-esc}</pre>
-		{.end}
-	{.end}
-	{.section Funcs}
-		{.repeated section @}
-			{# Name is a string - no need for FSet}
-			<h2 id="{Name|html-esc}">func <a href="/{Decl FSet|url-pos}">{Name|html-esc}</a></h2>
-			<p><code>{Decl FSet|html-esc}</code></p>
-			{Doc|html-comment}
-		{.end}
-	{.end}
-	{.section Types}
-		{.repeated section @}
-			<h2 id="{Type.Name FSet|html-esc}">type <a href="/{Decl FSet|url-pos}">{Type.Name FSet|html-esc}</a></h2>
-			{Doc|html-comment}
-			<p><pre>{Decl FSet|html-esc}</pre></p>
-			{.repeated section Consts}
-				{Doc|html-comment}
-				<pre>{Decl FSet|html-esc}</pre>
-			{.end}
-			{.repeated section Vars}
-				{Doc|html-comment}
-				<pre>{Decl FSet|html-esc}</pre>
-			{.end}
-			{.repeated section Factories}
-				<h3 id="{Type.Name FSet|html-esc}.{Name|html-esc}">func <a href="/{Decl FSet|url-pos}">{Name|html-esc}</a></h3>
-				<p><code>{Decl FSet|html-esc}</code></p>
-				{Doc|html-comment}
-			{.end}
-			{.repeated section Methods}
-				<h3 id="{Type.Name FSet|html-esc}.{Name|html-esc}">func ({Recv FSet|html-esc}) <a href="/{Decl FSet|url-pos}">{Name|html-esc}</a></h3>
-				<p><code>{Decl FSet|html-esc}</code></p>
-				{Doc|html-comment}
-			{.end}
-		{.end}
-	{.end}
-	{.section Bugs}
+		{{range .}}
+			{{comment_html .Doc}}
+			<pre>{{node_html .Decl $.FSet}}</pre>
+		{{end}}
+	{{end}}
+	{{with .Funcs}}
+		{{range .}}
+			{{/* Name is a string - no need for FSet */}}
+			{{$name_html := html .Name}}
+			<h2 id="{{$name_html}}">func <a href="/{{posLink_url .Decl $.FSet}}">{{$name_html}}</a></h2>
+			<p><code>{{node_html .Decl $.FSet}}</code></p>
+			{{comment_html .Doc}}
+		{{end}}
+	{{end}}
+	{{with .Types}}
+		{{range .}}
+			{{$tname_html := node_html .Type.Name $.FSet}}
+			<h2 id="{{$tname_html}}">type <a href="/{{posLink_url .Decl $.FSet}}">{{$tname_html}}</a></h2>
+			{{comment_html .Doc}}
+			<p><pre>{{node_html .Decl $.FSet}}</pre></p>
+			{{range .Consts}}
+				{{comment_html .Doc}}
+				<pre>{{node_html .Decl $.FSet}}</pre>
+			{{end}}
+			{{range .Vars}}
+				{{comment_html .Doc}}
+				<pre>{{node_html .Decl $.FSet}}</pre>
+			{{end}}
+			{{range .Factories}}
+				{{$name_html := html .Name}}
+				<h3 id="{{$tname_html}}.{{$name_html}}">func <a href="/{{posLink_url .Decl $.FSet}}">{{$name_html}}</a></h3>
+				<p><code>{{node_html .Decl $.FSet}}</code></p>
+				{{comment_html .Doc}}
+			{{end}}
+			{{range .Methods}}
+				{{$name_html := html .Name}}
+				<h3 id="{{$tname_html}}.{{$name_html}}">func ({{node_html .Recv $.FSet}}) <a href="/{{posLink_url .Decl $.FSet}}">{{$name_html}}</a></h3>
+				<p><code>{{node_html .Decl $.FSet}}</code></p>
+				{{comment_html .Doc}}
+			{{end}}
+		{{end}}
+	{{end}}
+	{{with .Bugs}}
 		<h2 id="Bugs">Bugs</h2>
-		{.repeated section @}
-		{@|html-comment}
-		{.end}
-	{.end}
-{.end}
-{.section PList}
+		{{range .}}
+		{{comment_html .}}
+		{{end}}
+	{{end}}
+{{end}}
+{{with .PList}}
 	<h2>Other packages</h2>
 	<p>
-	{# PLIst entries are strings - no need for FSet}
-	{.repeated section @}
-	<a href="?p={@|html-esc}">{@|html-esc}</a><br />
-	{.end}
+	{{/* PList entries are strings - no need for FSet */}}
+	{{range .}}
+	<a href="?p={{urlquery .}}">{{html .}}</a><br />
+	{{end}}
 	</p>
-{.end}
-{.section Dirs}
+{{end}}
+{{with .Dirs}}
 	<p class="detail">
 	Need more packages? The
 	<a href="http://godashboard.appspot.com/package">Package Dashboard</a>
 	provides a list of <a href="/cmd/goinstall/">goinstallable</a> packages.
 	</p>
-	{# DirList entries are numbers and strings - no need for FSet}
+	{{/* DirList entries are numbers and strings - no need for FSet */}}
 	<h2 id="Subdirectories">Subdirectories</h2>
 	<p>
 	<table class="layout">
 	<tr>
-	<th align="left" colspan="{MaxHeight|html-esc}">Name</th>
+	<th align="left" colspan="{{html .MaxHeight}}">Name</th>
 	<td width="25">&nbsp;</td>
 	<th align="left">Synopsis</th>
 	</tr>
 	<tr>
 	<th align="left"><a href="..">..</a></th>
 	</tr>
-	{.repeated section List}
+	{{range .List}}
 		<tr>
-		{Depth|padding}
-		<td align="left" colspan="{Height|html-esc}"><a href="{Path|html-esc}">{Name|html-esc}</a></td>
+		{{repeat `<td width="25"></td>` .Depth}}
+		<td align="left" colspan="{{html .Height}}"><a href="{{html .Path}}">{{html .Name}}</a></td>
 		<td></td>
-		<td align="left">{Synopsis|html-esc}</td>
+		<td align="left">{{html .Synopsis}}</td>
 		</tr>
-	{.end}
+	{{end}}
 	</table>
 	</p>
-{.end}
+{{end}}

lib/godoc/package.txt

@@ -1,95 +1,82 @@
-{.section PAst}
-{@ FSet}
-{.end}
-{.section PDoc}
-{.section IsPkg}
-PACKAGE
+{{with .PAst}}{{node . $.FSet}}{{end}}{{/*
 
-package {PackageName}
-import "{ImportPath}"
-{.or}
-COMMAND DOCUMENTATION
-{.end}
-{.section Doc}
+---------------------------------------
 
-{@ FSet}
-{.end}
-{.section Consts}
+*/}}{{with .PDoc}}{{if $.IsPkg}}PACKAGE
 
+package {{.PackageName}}
+import "{{.ImportPath}}"
+
+{{else}}COMMAND DOCUMENTATION
+
+{{end}}{{.Doc}}{{/*
+
+---------------------------------------
+
+*/}}{{with .Consts}}
 CONSTANTS
 
-{.repeated section @}
-{Decl FSet}
-{Doc}
-{.end}
-{.end}
-{.section Vars}
+{{range .}}{{node .Decl $.FSet}}
+{{.Doc}}{{end}}
+{{end}}{{/*
 
+---------------------------------------
+
+*/}}{{with .Vars}}
 VARIABLES
 
-{.repeated section @}
-{Decl FSet}
-{Doc}
-{.end}
-{.end}
-{.section Funcs}
+{{range .}}{{node .Decl $.FSet}}
+{{.Doc}}{{end}}
+{{end}}{{/*
 
+---------------------------------------
+
+*/}}{{with .Funcs}}
 FUNCTIONS
 
-{.repeated section @}
-{Decl FSet}
-{Doc}
-{.end}
-{.end}
-{.section Types}
+{{range .}}{{node .Decl $.FSet}}
+{{.Doc}}
+{{end}}{{end}}{{/*
 
+---------------------------------------
+
+*/}}{{with .Types}}
 TYPES
 
-{.repeated section @}
-{Decl FSet}
-{Doc}
-{.repeated section Consts}
-{Decl FSet}
-{Doc}
-{.end}
-{.repeated section Vars}
-{Decl FSet}
-{Doc}
-{.end}
-{.repeated section Factories}
-{Decl FSet}
-{Doc}
-{.end}
-{.repeated section Methods}
-{Decl FSet}
-{Doc}
-{.end}
-{.end}
-{.end}
-{.section Bugs}
+{{range .}}{{node .Decl $.FSet}}
+{{.Doc}}
+{{range .Consts}}{{node .Decl $.FSet}}
+{{.Doc}}
+{{end}}{{range .Vars}}{{node .Decl $.FSet}}
+{{.Doc}}
+{{end}}{{range .Factories}}{{node .Decl $.FSet}}
+{{.Doc}}
+{{end}}{{range .Methods}}{{node .Decl $.FSet}}
+{{.Doc}}
+{{end}}{{end}}{{end}}{{/*
 
+---------------------------------------
+
+*/}}{{with .Bugs}}
 BUGS
 
-{.repeated section @}
-{@}
-{.end}
-{.end}
-{.end}
-{.section PList}
+{{range .}}{{.}}
+{{end}}{{end}}{{end}}{{/*
 
+---------------------------------------
+
+*/}}{{with .PList}}
 OTHER PACKAGES
 
-{.repeated section @}
-{@}
-{.end}
-{.end}
-{.section Dirs}
-{.section Dirs}
+{{range .}}
+{{.}}{{end}}
+{{end}}{{/*
 
+---------------------------------------
+
+*/}}{{with .Dirs}}
 SUBDIRECTORIES
 
-{.repeated section List}
-	{Name}
-{.end}
-{.end}
-{.end}
+{{range .List}}
+	{{.Name}}{{end}}
+{{end}}

lib/godoc/search.html

@@ -3,93 +3,96 @@
 	Use of this source code is governed by a BSD-style
 	license that can be found in the LICENSE file.
 -->
-
-{.section Alert}
+{{$query_url := urlquery .Query}}
+{{with .Alert}}
 	<p>
-	<span class="alert" style="font-size:120%">{@}</span>
+	<span class="alert" style="font-size:120%">{{html .}}</span>
 	</p>
-{.end}
-{.section Alt}
+{{end}}
+{{with .Alt}}
 	<p>
 	<span class="alert" style="font-size:120%">Did you mean: </span>
-	{.repeated section Alts}
-		<a href="search?q={@|html-esc}" style="font-size:120%">{@|html-esc}</a>
-	{.end}
+	{{range .Alts}}
+		<a href="search?q={{urlquery .}}" style="font-size:120%">{{html .}}</a>
+	{{end}}
 	</p>
-{.end}
-{.section Hit}
-	{.section Decls}
+{{end}}
+{{with .Hit}}
+	{{with .Decls}}
 		<h2 id="Global">Package-level declarations</h2>
-		{.repeated section @}
-			<h3 id="Global_{Pak.Path|url-pkg}">package <a href="/{Pak.Path|url-pkg}">{Pak.Name|html-esc}</a></h3>
-			{.repeated section Files}
-				{.repeated section Groups}
-					{.repeated section Infos}
-						<a href="/{File.Path|url-src}?h={Query|urlquery-esc}#L{@|infoLine}">{File.Path|url-src}:{@|infoLine}</a>
-						{@|infoSnippet}
-					{.end}
-				{.end}
-			{.end}
-		{.end}
-	{.end}
-	{.section Others}
+		{{range .}}
+			{{$pkg_html := pkgLink .Pak.Path | html}}
+			<h3 id="Global_{{$pkg_html}}">package <a href="/{{$pkg_html}}">{{html .Pak.Name}}</a></h3>
+			{{range .Files}}
+				{{$src_html := srcLink .File.Path | html}}
+				{{range .Groups}}
+					{{range .Infos}}
+						<a href="/{{$src_html}}?h={{$query_url}}#L{{infoLine .}}">{{$src_html}}:{{infoLine .}}</a>
+						{{infoSnippet_html .}}
+					{{end}}
+				{{end}}
+			{{end}}
+		{{end}}
+	{{end}}
+	{{with .Others}}
 		<h2 id="Local">Local declarations and uses</h2>
-		{.repeated section @}
-			<h3 id="Local_{Pak.Path|url-pkg}">package <a href="/{Pak.Path|url-pkg}">{Pak.Name|html-esc}</a></h3>
-			{.repeated section Files}
-				<a href="/{File.Path|url-src}?h={Query|urlquery-esc}">{File.Path|url-src}</a>
+		{{range .}}
+			{{$pkg_html := pkgLink .Pak.Path | html}}
+			<h3 id="Local_{{$pkg_html}}">package <a href="/{{$pkg_html}}">{{html .Pak.Name}}</a></h3>
+			{{range .Files}}
+				{{$src_html := srcLink .File.Path | html}}
+				<a href="/{{$src_html}}?h={{$query_url}}">{{$src_html}}</a>
 				<table class="layout">
-				{.repeated section Groups}
+				{{range .Groups}}
 					<tr>
 					<td width="25"></td>
-					<th align="left" valign="top">{Kind|infoKind}</th>
+					<th align="left" valign="top">{{infoKind_html .Kind}}</th>
 					<td align="left" width="4"></td>
 					<td>
-					{.repeated section Infos}
-						<a href="/{File.Path|url-src}?h={Query|urlquery-esc}#L{@|infoLine}">{@|infoLine}</a>
-					{.end}
+					{{range .Infos}}
+						<a href="/{{$src_html}}?h={{$query_url}}#L{{infoLine .}}">{{infoLine .}}</a>
+					{{end}}
 					</td>
 					</tr>
-				{.end}
+				{{end}}
 				</table>
-			{.end}
-		{.end}
-	{.end}
-{.end}
-{.section Textual}
-	{.section Complete}
-		<h2 id="Textual">{Found|html-esc} textual occurrences</h2>
-	{.or}
-		<h2 id="Textual">More than {Found|html-esc} textual occurrences</h2>
+			{{end}}
+		{{end}}
+	{{end}}
+{{end}}
+{{with .Textual}}
+	{{if $.Complete}}
+		<h2 id="Textual">{{html $.Found}} textual occurrences</h2>
+	{{else}}
+		<h2 id="Textual">More than {{html $.Found}} textual occurrences</h2>
 		<p>
-		<span class="alert" style="font-size:120%">Not all files or lines containing "{Query|html-esc}" are shown.</span>
+		<span class="alert" style="font-size:120%">Not all files or lines containing "{{html $.Query}}" are shown.</span>
 		</p>
-	{.end}
+	{{end}}
 	<p>
 	<table class="layout">
-	{.repeated section @}
+	{{range .}}
+		{{$src_html := srcLink .Filename | html}}
 		<tr>
 		<td align="left" valign="top">
-		<a href="/{Filename|url-src}?h={Query|urlquery-esc}">{Filename|url-src}</a>:
+		<a href="/{{$src_html}}?h={{$query_url}}">{{$src_html}}</a>:
 		</td>
 		<td align="left" width="4"></td>
-		<th align="left" valign="top">{Lines|numlines}</th>
+		<th align="left" valign="top">{{len .Lines}}</th>
 		<td align="left" width="4"></td>
 		<td align="left">
-		{.repeated section Lines}
-			<a href="/{Filename|url-src}?h={Query|urlquery-esc}#L{@|html-esc}">{@|html-esc}</a>
-		{.end}
-		{.section Complete}
-		{.or}
+		{{range .Lines}}
+			<a href="/{{$src_html}}?h={{$query_url}}#L{{html .}}">{{html .}}</a>
+		{{end}}
+		{{if not $.Complete}}
 			...
-		{.end}
+		{{end}}
 		</td>
 		</tr>
-	{.end}
-	{.section Complete}
-	{.or}
+	{{end}}
+	{{if not $.Complete}}
 		<tr><td align="left">...</td></tr>
-	{.end}
+	{{end}}
 	</table>
 	</p>
-{.end}
+{{end}}

lib/godoc/search.txt

@@ -1,61 +1,40 @@
 QUERY
-	{Query}
+	{{.Query}}
+{{with .Alert}}
+{{.}}
+{{end}}{{/* .Alert */}}{{/*
 
-{.section Alert}
-{@}
+---------------------------------------
 
-{.end}
-{.section Alt}
+*/}}{{with .Alt}}
 DID YOU MEAN
-{.repeated section Alts}
-	{@}
-{.end}
+{{range .Alts}}	{{.}}
+{{end}}{{end}}{{/* .Alts */}}{{/*
 
-{.end}
-{.section Hit}
-{.section Decls}
+---------------------------------------
+
+*/}}{{with .Hit}}{{with .Decls}}
 PACKAGE-LEVEL DECLARATIONS
 
-{.repeated section @}
-package {Pak.Name}
-{.repeated section Files}
-{.repeated section Groups}
-{.repeated section Infos}
-	{File.Path|url-src}:{@|infoLine}
-{.end}
-{.end}
-{.end}
+{{range .}}package {{.Pak.Name}}
+{{range $file := .Files}}{{range .Groups}}{{range .Infos}}	{{srcLink $file.File.Path}}:{{infoLine .}}{{end}}
+{{end}}{{end}}{{/* .Files */}}
+{{end}}{{end}}{{/* .Decls */}}{{/*
 
-{.end}
-{.end}
-{.section Others}
+---------------------------------------
+
+*/}}{{with .Others}}
 LOCAL DECLARATIONS AND USES
 
-{.repeated section @}
-package {Pak.Name}
-{.repeated section Files}
-{.repeated section Groups}
-{.repeated section Infos}
-	{File.Path|url-src}:{@|infoLine}
-{.end}
-{.end}
-{.end}
+{{range .}}package {{.Pak.Name}}
+{{range $file := .Files}}{{range .Groups}}{{range .Infos}}	{{srcLink $file.File.Path}}:{{infoLine .}}
+{{end}}{{end}}{{end}}{{/* .Files */}}
+{{end}}{{end}}{{/* .Others */}}{{end}}{{/* .Hit */}}{{/*
 
-{.end}
-{.end}
-{.end}
-{.section Textual}
-{.section Complete}
-{Found} TEXTUAL OCCURRENCES
-{.or}
-MORE THAN {Found} TEXTUAL OCCURRENCES
-{.end}
+---------------------------------------
 
-{.repeated section @}
-{Lines|numlines}	{Filename|url-src}
-{.end}
-{.section Complete}
-{.or}
-...	...
-{.end}
-{.end}
+*/}}{{if .Textual}}{{if .Complete}}{{.Found}} TEXTUAL OCCURRENCES{{else}}MORE THAN {{.Found}} TEXTUAL OCCURRENCES{{end}}
+
+{{range .Textual}}{{len .Lines}}	{{srcLink .Filename}}
+{{end}}{{if not .Complete}}...	...
+{{end}}{{end}}

misc/cgo/gmp/gmp.go

@@ -211,7 +211,6 @@ func (z *Int) destroy() {
 	z.init = false
 }
 
-
 /*
  * arithmetic
  */
@@ -266,7 +265,7 @@ func (z *Int) Mod(x, y *Int) *Int {
 func (z *Int) Lsh(x *Int, s uint) *Int {
 	x.doinit()
 	z.doinit()
-	C.mpz_mul_2exp(&z.i[0], &x.i[0], C.ulong(s))
+	C.mpz_mul_2exp(&z.i[0], &x.i[0], C.mp_bitcnt_t(s))
 	return z
 }
 
@@ -274,7 +273,7 @@ func (z *Int) Lsh(x *Int, s uint) *Int {
 func (z *Int) Rsh(x *Int, s uint) *Int {
 	x.doinit()
 	z.doinit()
-	C.mpz_div_2exp(&z.i[0], &x.i[0], C.ulong(s))
+	C.mpz_div_2exp(&z.i[0], &x.i[0], C.mp_bitcnt_t(s))
 	return z
 }
 
@@ -300,7 +299,6 @@ func (z *Int) Int64() int64 {
 	return int64(C.mpz_get_si(&z.i[0]))
 }
 
-
 // Neg sets z = -x and returns z.
 func (z *Int) Neg(x *Int) *Int {
 	x.doinit()
@@ -317,7 +315,6 @@ func (z *Int) Abs(x *Int) *Int {
 	return z
 }
 
-
 /*
  * functions without a clear receiver
  */

misc/cgo/stdio/file.go

@@ -42,3 +42,4 @@ func (f *File) Flush() {
 }
 
 var Greeting = C.GoString(C.greeting)
+var Gbytes = C.GoBytes(unsafe.Pointer(C.greeting), C.int(len(Greeting)))

misc/cgo/test/Makefile

@@ -11,9 +11,11 @@ CGOFILES=\
 	basic.go\
 	callback.go\
 	env.go\
+	exports.go\
 	issue1222.go\
 	issue1328.go\
 	issue1560.go\
+	duplicate_symbol.go\
 
 CGO_OFILES=\
 	callback_c.o\

misc/cgo/test/duplicate_symbol.go

@@ -0,0 +1,21 @@
+// 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.
+
+// This file contains test cases for cgo.
+
+package cgotest
+
+/*
+int base_symbol = 0;
+
+#define alias_one base_symbol
+#define alias_two base_symbol
+*/
+import "C"
+
+import "fmt"
+
+func duplicateSymbols() {
+	fmt.Printf("%v %v %v\n", C.base_symbol, C.alias_one, C.alias_two)
+}

misc/cgo/test/exports.go

@@ -0,0 +1,12 @@
+// 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 cgotest
+
+import "C"
+
+//export ReturnIntLong
+func ReturnIntLong() (int, C.long) {
+	return 1, 2
+}

misc/dashboard/builder/http.go

@@ -12,6 +12,7 @@ import (
 	"log"
 	"os"
 	"strconv"
+	"url"
 )
 
 type param map[string]string
@@ -26,7 +27,7 @@ func dash(meth, cmd string, resp interface{}, args param) os.Error {
 		log.Println("dash", cmd, args)
 	}
 	cmd = "http://" + *dashboard + "/" + cmd
-	vals := make(http.Values)
+	vals := make(url.Values)
 	for k, v := range args {
 		vals.Add(k, v)
 	}
@@ -112,16 +113,15 @@ func packages() (pkgs []string, err os.Error) {
 	return
 }
 
-// updatePackage sends package build results and info to the dashboard
-func (b *Builder) updatePackage(pkg string, state bool, buildLog, info string, hash string) os.Error {
+// updatePackage sends package build results and info dashboard
+func (b *Builder) updatePackage(pkg string, ok bool, buildLog, info string) os.Error {
 	return dash("POST", "package", nil, param{
 		"builder": b.name,
 		"key":     b.key,
 		"path":    pkg,
-		"state":   strconv.Btoa(state),
+		"ok":      strconv.Btoa(ok),
 		"log":     buildLog,
 		"info":    info,
-		"go_rev":  hash[:12],
 	})
 }
 

misc/dashboard/builder/main.go

@@ -60,8 +60,9 @@ var (
 )
 
 var (
-	goroot        string
-	releaseRegexp = regexp.MustCompile(`^(release|weekly)\.[0-9\-.]+`)
+	goroot      string
+	binaryTagRe = regexp.MustCompile(`^(release\.r|weekly\.)[0-9\-.]+`)
+	releaseRe   = regexp.MustCompile(`^release\.r[0-9\-.]+`)
 )
 
 func main() {
@@ -161,7 +162,7 @@ func NewBuilder(builder string) (*Builder, os.Error) {
 	b := &Builder{name: builder}
 
 	// get goos/goarch from builder string
-	s := strings.Split(builder, "-", 3)
+	s := strings.SplitN(builder, "-", 3)
 	if len(s) >= 2 {
 		b.goos, b.goarch = s[0], s[1]
 	} else {
@@ -177,7 +178,7 @@ func NewBuilder(builder string) (*Builder, os.Error) {
 	if err != nil {
 		return nil, fmt.Errorf("readKeys %s (%s): %s", b.name, fn, err)
 	}
-	v := strings.Split(string(c), "\n", -1)
+	v := strings.Split(string(c), "\n")
 	b.key = v[0]
 	if len(v) >= 3 {
 		b.codeUsername, b.codePassword = v[1], v[2]
@@ -200,7 +201,7 @@ func (b *Builder) buildExternal() {
 			log.Println("hg pull failed:", err)
 			continue
 		}
-		hash, tag, err := firstTag(releaseRegexp)
+		hash, tag, err := firstTag(releaseRe)
 		if err != nil {
 			log.Println(err)
 			continue
@@ -321,7 +322,7 @@ func (b *Builder) buildHash(hash string) (err os.Error) {
 	}
 
 	// if this is a release, create tgz and upload to google code
-	releaseHash, release, err := firstTag(releaseRegexp)
+	releaseHash, release, err := firstTag(binaryTagRe)
 	if hash == releaseHash {
 		// clean out build state
 		err = run(b.envv(), srcDir, "./clean.bash", "--nopkg")
@@ -357,7 +358,10 @@ func (b *Builder) envv() []string {
 		"GOROOT_FINAL=/usr/local/go",
 	}
 	for _, k := range extraEnv {
-		e = append(e, k+"="+os.Getenv(k))
+		s, err := os.Getenverror(k)
+		if err == nil {
+			e = append(e, k+"="+s)
+		}
 	}
 	return e
 }
@@ -368,9 +372,14 @@ func (b *Builder) envvWindows() []string {
 		"GOOS":         b.goos,
 		"GOARCH":       b.goarch,
 		"GOROOT_FINAL": "/c/go",
+		// TODO(brainman): remove once we find make that does not hang.
+		"MAKEFLAGS": "-j1",
 	}
 	for _, name := range extraEnv {
-		start[name] = os.Getenv(name)
+		s, err := os.Getenverror(name)
+		if err == nil {
+			start[name] = s
+		}
 	}
 	skip := map[string]bool{
 		"GOBIN":   true,
@@ -384,7 +393,7 @@ func (b *Builder) envvWindows() []string {
 		skip[name] = true
 	}
 	for _, kv := range os.Environ() {
-		s := strings.Split(kv, "=", 2)
+		s := strings.SplitN(kv, "=", 2)
 		name := strings.ToUpper(s[0])
 		switch {
 		case name == "":
@@ -583,7 +592,7 @@ func fullHash(rev string) (hash string, err os.Error) {
 	if s == "" {
 		return "", fmt.Errorf("cannot find revision")
 	}
-	if len(s) != 20 {
+	if len(s) != 40 {
 		return "", fmt.Errorf("hg returned invalid hash " + s)
 	}
 	return s, nil
@@ -594,7 +603,7 @@ var revisionRe = regexp.MustCompile(`^([^ ]+) +[0-9]+:([0-9a-f]+)$`)
 // firstTag returns the hash and tag of the most recent tag matching re.
 func firstTag(re *regexp.Regexp) (hash string, tag string, err os.Error) {
 	o, _, err := runLog(nil, "", goroot, "hg", "tags")
-	for _, l := range strings.Split(o, "\n", -1) {
+	for _, l := range strings.Split(o, "\n") {
 		if l == "" {
 			continue
 		}
@@ -607,7 +616,7 @@ func firstTag(re *regexp.Regexp) (hash string, tag string, err os.Error) {
 			continue
 		}
 		tag = s[1]
-		hash, err = fullHash(s[3])
+		hash, err = fullHash(s[2])
 		return
 	}
 	err = os.NewError("no matching tag found")

misc/dashboard/builder/package.go

@@ -10,35 +10,47 @@ import (
 	"go/token"
 	"log"
 	"os"
-	"path"
+	"path/filepath"
+	"strings"
 )
 
+const MaxCommentLength = 500 // App Engine won't store more in a StringProperty.
+
 func (b *Builder) buildPackages(workpath string, hash string) os.Error {
 	pkgs, err := packages()
 	if err != nil {
 		return err
 	}
 	for _, p := range pkgs {
-		goroot := path.Join(workpath, "go")
-		goinstall := path.Join(goroot, "bin", "goinstall")
+		goroot := filepath.Join(workpath, "go")
+		gobin := filepath.Join(goroot, "bin")
+		goinstall := filepath.Join(gobin, "goinstall")
 		envv := append(b.envv(), "GOROOT="+goroot)
 
+		// add GOBIN to path
+		for i, v := range envv {
+			if strings.HasPrefix(v, "PATH=") {
+				p := filepath.SplitList(v[5:])
+				p = append([]string{gobin}, p...)
+				s := strings.Join(p, string(filepath.ListSeparator))
+				envv[i] = "PATH=" + s
+			}
+		}
+
 		// goinstall
-		buildLog, code, err := runLog(envv, "", goroot, goinstall, p)
+		buildLog, code, err := runLog(envv, "", goroot, goinstall, "-dashboard=false", p)
 		if err != nil {
 			log.Printf("goinstall %v: %v", p, err)
-			continue
 		}
-		built := code != 0
 
 		// get doc comment from package source
-		info, err := packageComment(p, path.Join(goroot, "pkg", p))
+		info, err := packageComment(p, filepath.Join(goroot, "src", "pkg", p))
 		if err != nil {
-			log.Printf("goinstall %v: %v", p, err)
+			log.Printf("packageComment %v: %v", p, err)
 		}
 
 		// update dashboard with build state + info
-		err = b.updatePackage(p, built, buildLog, info, hash)
+		err = b.updatePackage(p, code == 0, buildLog, info)
 		if err != nil {
 			log.Printf("updatePackage %v: %v", p, err)
 		}
@@ -46,9 +58,15 @@ func (b *Builder) buildPackages(workpath string, hash string) os.Error {
 	return nil
 }
 
+func isGoFile(fi *os.FileInfo) bool {
+	return fi.IsRegular() && // exclude directories
+		!strings.HasPrefix(fi.Name, ".") && // ignore .files
+		filepath.Ext(fi.Name) == ".go"
+}
+
 func packageComment(pkg, pkgpath string) (info string, err os.Error) {
 	fset := token.NewFileSet()
-	pkgs, err := parser.ParseDir(fset, pkgpath, nil, parser.PackageClauseOnly|parser.ParseComments)
+	pkgs, err := parser.ParseDir(fset, pkgpath, isGoFile, parser.PackageClauseOnly|parser.ParseComments)
 	if err != nil {
 		return
 	}
@@ -62,5 +80,15 @@ func packageComment(pkg, pkgpath string) (info string, err os.Error) {
 		pdoc := doc.NewPackageDoc(pkgs[name], pkg)
 		info = pdoc.Doc
 	}
+	// grab only first paragraph
+	if parts := strings.SplitN(info, "\n\n", 2); len(parts) > 1 {
+		info = parts[0]
+	}
+	// replace newlines with spaces
+	info = strings.Replace(info, "\n", " ", -1)
+	// truncate
+	if len(info) > MaxCommentLength {
+		info = info[:MaxCommentLength]
+	}
 	return
 }

misc/dashboard/godashboard/app.yaml

@@ -11,9 +11,13 @@ handlers:
 - url: /static
   static_dir: static
 
-- url: /package.*
+- url: /package
   script: package.py
 
+- url: /package/daily
+  script: package.py
+  login: admin
+
 - url: /project.*
   script: package.py
 

misc/dashboard/godashboard/auth.py

@@ -0,0 +1,13 @@
+# 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.
+
+import hmac
+
+# local imports
+import key
+
+def auth(req):
+    k = req.get('key')
+    return k == hmac.new(key.accessKey, req.get('builder')).hexdigest() or k == key.accessKey
+

misc/dashboard/godashboard/cron.yaml

@@ -0,0 +1,4 @@
+cron:
+- description: daily package maintenance
+  url: /package/daily
+  schedule: every 24 hours

misc/dashboard/godashboard/gobuild.py

@@ -14,14 +14,13 @@ from google.appengine.ext.webapp import template
 from google.appengine.ext.webapp.util import run_wsgi_app
 import datetime
 import hashlib
-import hmac
 import logging
 import os
 import re
 import bz2
 
 # local imports
-import key
+from auth import auth
 import const
 
 # The majority of our state are commit objects. One of these exists for each of
@@ -142,10 +141,6 @@ class DashboardHandler(webapp.RequestHandler):
         simplejson.dump(obj, self.response.out)
         return
 
-def auth(req):
-    k = req.get('key')
-    return k == hmac.new(key.accessKey, req.get('builder')).hexdigest() or k == key.accessKey
-
 # Todo serves /todo.  It tells the builder which commits need to be built.
 class Todo(DashboardHandler):
     def get(self):

misc/dashboard/godashboard/index.yaml

@@ -49,4 +49,3 @@ indexes:
 # manually, move them above the marker line.  The index.yaml file is
 # automatically uploaded to the admin console when you next deploy
 # your application using appcfg.py.
-

misc/dashboard/godashboard/package.html

@@ -19,37 +19,57 @@
     Packages listed on this page are written by third parties and 
     may or may not build or be safe to use.
     </p>
+
+    <p>
+    An "ok" in the <b>build</b> column indicates that the package is
+    <a href="http://golang.org/cmd/goinstall/">goinstallable</a>
+    with the latest
+    <a href="http://golang.org/doc/devel/release.html">release</a> of Go.
+    </p>
+
+    <p>
+    The <b>info</b> column shows the first paragraph from the
+    <a href="http://blog.golang.org/2011/03/godoc-documenting-go-code.html">package doc comment</a>.
+    </p>
+    
+    <h2>Most Installed Packages (this week)</h2>
+    <table class="alternate" cellpadding="0" cellspacing="0">
+      <tr><th>last install</th><th>count</th><th>build</th><th>path</th><th>info</th></tr>
+      {% for r in by_week_count %}
+        <tr>
+          <td class="time">{{r.last_install|date:"Y-M-d H:i"}}</td>
+          <td class="count">{{r.week_count}}</td>
+          <td class="ok">{% if r.ok %}<a title="{{r.last_ok|date:"Y-M-d H:i"}}">ok</a>{% else %}&nbsp;{% endif %}</td>
+          <td class="path"><a href="{{r.web_url}}">{{r.path}}</a></td>
+          <td class="info">{% if r.info %}{{r.info|escape}}{% endif %}</td>
+        </tr>
+      {% endfor %}
+    </table>
     
     <h2>Recently Installed Packages</h2>
     <table class="alternate" cellpadding="0" cellspacing="0">
-      <tr><th>last install</th><th>count</th><th>path</th><th>project</th></tr>
+      <tr><th>last install</th><th>count</th><th>build</th><th>path</th><th>info</th></tr>
       {% for r in by_time %}
         <tr>
           <td class="time">{{r.last_install|date:"Y-M-d H:i"}}</td>
           <td class="count">{{r.count}}</td>
+          <td class="ok">{% if r.ok %}<a title="{{r.last_ok|date:"Y-M-d H:i"}}">ok</a>{% else %}&nbsp;{% endif %}</td>
           <td class="path"><a href="{{r.web_url}}">{{r.path}}</a></td>
-	  <td class="project">
-	  {% for p in r.project_set %}
-		<a href="{{p.web_url}}">{{p.name}}</a> - {{p.descr}}
-	  {% endfor %}
-	  </td>
+          <td class="info">{% if r.info %}{{r.info|escape}}{% endif %}</td>
         </tr>
       {% endfor %}
     </table>
 
-    <h2>Most Installed Packages</h2>
+    <h2>Most Installed Packages (all time)</h2>
     <table class="alternate" cellpadding="0" cellspacing="0">
-      <tr><th>last install</th><th>count</th><th>path</th><th>project</th></tr>
+      <tr><th>last install</th><th>count</th><th>build</th><th>path</th><th>info</th></tr>
       {% for r in by_count %}
         <tr>
           <td class="time">{{r.last_install|date:"Y-M-d H:i"}}</td>
           <td class="count">{{r.count}}</td>
+          <td class="ok">{% if r.ok %}<a title="{{r.last_ok|date:"Y-M-d H:i"}}">ok</a>{% else %}&nbsp;{% endif %}</td>
           <td class="path"><a href="{{r.web_url}}">{{r.path}}</a></td>
-	  <td class="project">
-	  {% for p in r.project_set %}
-		<a href="{{p.web_url}}">{{p.name}}</a> - {{p.descr}}
-	  {% endfor %}
-	  </td>
+          <td class="info">{% if r.info %}{{r.info|escape}}{% endif %}</td>
         </tr>
       {% endfor %}
     </table>

misc/dashboard/godashboard/package.py

@@ -5,35 +5,104 @@
 # This is the server part of the package dashboard.
 # It must be run by App Engine.
 
+from google.appengine.api import mail
 from google.appengine.api import memcache
+from google.appengine.api import taskqueue
+from google.appengine.api import urlfetch
+from google.appengine.api import users
 from google.appengine.ext import db
 from google.appengine.ext import webapp
 from google.appengine.ext.webapp import template
 from google.appengine.ext.webapp.util import run_wsgi_app
-from google.appengine.api import users
-from google.appengine.api import mail
-from google.appengine.api import urlfetch
 import datetime
 import logging
 import os
 import re
-import urllib2
 import sets
+import urllib2
 
 # local imports
+from auth import auth
 import toutf8
 import const
 
 template.register_template_library('toutf8')
 
 # Storage model for package info recorded on server.
-# Just path, count, and time of last install.
 class Package(db.Model):
     path = db.StringProperty()
-    web_url = db.StringProperty()  # derived from path
-    count = db.IntegerProperty()
+    web_url = db.StringProperty()           # derived from path
+    count = db.IntegerProperty()            # grand total
+    week_count = db.IntegerProperty()       # rolling weekly count
+    day_count = db.TextProperty(default='') # daily count
     last_install = db.DateTimeProperty()
 
+    # data contributed by gobuilder
+    info = db.StringProperty()  
+    ok = db.BooleanProperty()
+    last_ok = db.DateTimeProperty()
+
+    def get_day_count(self):
+        counts = {}
+        if not self.day_count:
+            return counts
+        for d in str(self.day_count).split('\n'):
+            date, count = d.split(' ')
+            counts[date] = int(count)
+        return counts
+
+    def set_day_count(self, count):
+        days = []
+        for day, count in count.items():
+            days.append('%s %d' % (day, count))
+        days.sort(reverse=True)
+        days = days[:28]
+        self.day_count = '\n'.join(days)
+
+    def inc(self):
+        count = self.get_day_count()
+        today = str(datetime.date.today())
+        count[today] = count.get(today, 0) + 1
+        self.set_day_count(count)
+        self.update_week_count(count)
+        self.count += 1
+
+    def update_week_count(self, count=None):
+        if count is None:
+            count = self.get_day_count()
+        total = 0
+        today = datetime.date.today()
+        for i in range(7):
+            day = str(today - datetime.timedelta(days=i))
+            if day in count:
+                total += count[day]
+        self.week_count = total
+
+
+# PackageDaily kicks off the daily package maintenance cron job
+# and serves the associated task queue.
+class PackageDaily(webapp.RequestHandler):
+
+    def get(self):
+        # queue a task to update each package with a week_count > 0
+        keys = Package.all(keys_only=True).filter('week_count >', 0)
+        for key in keys:
+            taskqueue.add(url='/package/daily', params={'key': key.name()})
+
+    def post(self):
+        # update a single package (in a task queue)
+        def update(key):
+            p = Package.get_by_key_name(key)
+            if not p:
+                return
+            p.update_week_count()
+            p.put()
+        key = self.request.get('key')
+        if not key:
+            return
+        db.run_in_transaction(update, key)
+ 
+
 class Project(db.Model):
     name = db.StringProperty(indexed=True)
     descr = db.StringProperty()
@@ -43,23 +112,26 @@ class Project(db.Model):
     tags = db.ListProperty(str)
     approved = db.BooleanProperty(indexed=True)
 
-re_bitbucket = re.compile(r'^bitbucket\.org/[a-z0-9A-Z_.\-]+/[a-z0-9A-Z_.\-]+$')
-re_googlecode = re.compile(r'^[a-z0-9\-]+\.googlecode\.com/(svn|hg)$')
-re_github = re.compile(r'^github\.com/[a-z0-9A-Z_.\-]+/[a-z0-9A-Z_.\-]+$')
-re_launchpad = re.compile(r'^launchpad\.net/([a-z0-9A-Z_.\-]+(/[a-z0-9A-Z_.\-]+)?|~[a-z0-9A-Z_.\-]+/(\+junk|[a-z0-9A-Z_.\-]+)/[a-z0-9A-Z_.\-]+)(/[a-z0-9A-Z_.\-/]+)?$')
 
+re_bitbucket = re.compile(r'^(bitbucket\.org/[a-z0-9A-Z_.\-]+/[a-zA-Z0-9_.\-]+)(/[a-z0-9A-Z_.\-/]+)?$')
+re_googlecode = re.compile(r'^[a-z0-9\-]+\.googlecode\.com/(svn|hg|git)(/[a-z0-9A-Z_.\-/]+)?$')
+re_github = re.compile(r'^github\.com/[a-z0-9A-Z_.\-]+(/[a-z0-9A-Z_.\-]+)+$')
+re_launchpad = re.compile(r'^launchpad\.net/([a-z0-9A-Z_.\-]+(/[a-z0-9A-Z_.\-]+)?|~[a-z0-9A-Z_.\-]+/(\+junk|[a-z0-9A-Z_.\-]+)/[a-z0-9A-Z_.\-]+)(/[a-z0-9A-Z_.\-/]+)?$')
 
 def vc_to_web(path):
     if re_bitbucket.match(path):
-        check_url = 'http://' + path + '/?cmd=heads'
-        web = 'http://' + path + '/'
+        m = re_bitbucket.match(path)
+        check_url = 'http://' + m.group(1) + '/?cmd=heads'
+        web = 'http://' + m.group(1) + '/'
     elif re_github.match(path):
-        # github doesn't let you fetch the .git directory anymore.
-        # fetch .git/info/refs instead, like git clone would.
-        check_url = 'http://'+path+'.git/info/refs'
-        web = 'http://' + path
+        m = re_github_web.match(path)
+        check_url = 'https://raw.github.com/' + m.group(1) + '/' + m.group(2) + '/master/'
+        web = 'http://github.com/' + m.group(1) + '/' + m.group(2) + '/'
     elif re_googlecode.match(path):
+        m = re_googlecode.match(path)
         check_url = 'http://'+path
+        if not m.group(2):  # append / after bare '/hg' or '/git'
+            check_url += '/'
         web = 'http://code.google.com/p/' + path[:path.index('.')]
     elif re_launchpad.match(path):
         check_url = web = 'https://'+path
@@ -73,6 +145,17 @@ re_github_web = re.compile(r'github\.com/([a-z0-9A-Z_.\-]+)/([a-z0-9A-Z_.\-]+)')
 re_launchpad_web = re.compile(r'launchpad\.net/([a-z0-9A-Z_.\-]+(/[a-z0-9A-Z_.\-]+)?|~[a-z0-9A-Z_.\-]+/(\+junk|[a-z0-9A-Z_.\-]+)/[a-z0-9A-Z_.\-]+)(/[a-z0-9A-Z_.\-/]+)?')
 re_striphttp = re.compile(r'https?://(www\.)?')
 
+def find_googlecode_vcs(path):
+    # Perform http request to path/hg or path/git to check if they're
+    # using mercurial or git.  Otherwise, assume svn.
+    for vcs in ['git', 'hg']:
+        try:
+            response = urlfetch.fetch('http://'+path+vcs, deadline=1)
+            if response.status_code == 200:
+                return vcs
+        except: pass
+    return 'svn'
+
 def web_to_vc(url):
     url = re_striphttp.sub('', url)
     m = re_bitbucket_web.match(url)
@@ -84,13 +167,7 @@ def web_to_vc(url):
     m = re_googlecode_web.match(url)
     if m:
         path = m.group(1)+'.googlecode.com/'
-        # perform http request to path/hg to check if they're using mercurial
-        vcs = 'svn'
-        try:
-            response = urlfetch.fetch('http://'+path+'hg', deadline=1)
-            if response.status_code == 200:
-                vcs = 'hg'
-        except: pass
+        vcs = find_googlecode_vcs(path)
         return path + vcs
     m = re_launchpad_web.match(url)
     if m:
@@ -107,29 +184,30 @@ class PackagePage(webapp.RequestHandler):
 
         html = memcache.get('view-package')
         if not html:
+            tdata = {}
+
+            q = Package.all().filter('week_count >', 0)
+            q.order('-week_count')
+            tdata['by_week_count'] = q.fetch(50)
+
             q = Package.all()
             q.order('-last_install')
-            by_time = q.fetch(100)
+            tdata['by_time'] = q.fetch(20)
 
             q = Package.all()
             q.order('-count')
-            by_count = q.fetch(100)
+            tdata['by_count'] = q.fetch(100)
 
-            self.response.headers['Content-Type'] = 'text/html; charset=utf-8'
             path = os.path.join(os.path.dirname(__file__), 'package.html')
-            html = template.render(
-                path, 
-                {"by_time": by_time, "by_count": by_count}
-            )
+            html = template.render(path, tdata)
             memcache.set('view-package', html, time=CacheTimeout)
 
+        self.response.headers['Content-Type'] = 'text/html; charset=utf-8'
         self.response.out.write(html)
 
     def json(self):
         json = memcache.get('view-package-json')
         if not json:
-            self.response.set_status(200)
-            self.response.headers['Content-Type'] = 'text/plain; charset=utf-8'
             q = Package.all()
             s = '{"packages": ['
             sep = ''
@@ -139,12 +217,13 @@ class PackagePage(webapp.RequestHandler):
             s += '\n]}\n'
             json = s
             memcache.set('view-package-json', json, time=CacheTimeout)
+        self.response.set_status(200)
+        self.response.headers['Content-Type'] = 'text/plain; charset=utf-8'
         self.response.out.write(json)
 
     def can_get_url(self, url):
         try:
-            req = urllib2.Request(url)
-            response = urllib2.urlopen(req)
+            urllib2.urlopen(urllib2.Request(url))
             return True
         except:
             return False
@@ -174,15 +253,24 @@ class PackagePage(webapp.RequestHandler):
                 return False
             p = Package(key_name = key, path = path, count = 0, web_url = web)
 
+        if auth(self.request):
+            # builder updating package metadata
+            p.info = self.request.get('info')
+            p.ok = self.request.get('ok') == "true"
+            if p.ok:
+                p.last_ok = datetime.datetime.utcnow()
+        else:
+            # goinstall reporting an install
+            p.inc()
+            p.last_install = datetime.datetime.utcnow()
+
         # update package object
-        p.count += 1
-        p.last_install = datetime.datetime.utcnow()
         p.put()
         return True
 
     def post(self):
         path = self.request.get('path')
-        ok = self.record_pkg(path)
+        ok = db.run_in_transaction(self.record_pkg, path)
         if ok:
             self.response.set_status(200)
             self.response.out.write('ok')
@@ -332,6 +420,7 @@ class ProjectPage(webapp.RequestHandler):
 def main():
     app = webapp.WSGIApplication([
         ('/package', PackagePage),
+        ('/package/daily', PackageDaily),
         ('/project.*', ProjectPage),
         ], debug=True)
     run_wsgi_app(app)

misc/dashboard/godashboard/static/style.css

@@ -52,7 +52,10 @@ table.alternate tr td:last-child {
 	padding-right: 0;
 }
 table.alternate tr:nth-child(2n) {
-	background-color: #f8f8f8;
+	background-color: #f0f0f0;
+}
+td.result {
+	text-align: center;
 }
 span.hash {
 	font-family: monospace;
@@ -62,10 +65,19 @@ span.hash {
 td.date {
 	color: #aaa;
 }
-td.result {
+td.ok { 
 	text-align: center;
+	color: #060; 
+	font-weight: bold;
+}
+td.ok a {
+	cursor: help;
+}
+th {
+	text-align: left;
 }
 th.builder {
+	text-align: center;
 	font-weight: bold;
 }
 a.fail {

misc/emacs/go-mode.el

@@ -69,8 +69,8 @@
 some syntax analysis.")
 
 (defvar go-mode-font-lock-keywords
-  (let ((builtins '("cap" "close" "closed" "len" "make" "new"
-                    "panic" "panicln" "print" "println"))
+  (let ((builtins '("append" "cap" "close" "complex" "copy" "imag" "len"
+                    "make" "new" "panic" "print" "println" "real" "recover"))
         (constants '("nil" "true" "false" "iota"))
         (type-name "\\s *\\(?:[*(]\\s *\\)*\\(?:\\w+\\s *\\.\\s *\\)?\\(\\w+\\)")
         )

misc/goplay/goplay.go

@@ -142,18 +142,10 @@ func run(cmd ...string) ([]byte, os.Error) {
 	return exec.Command(cmd[0], cmd[1:]...).CombinedOutput()
 }
 
-var frontPage, output *template.Template // HTML templates
+var frontPage = template.Must(template.New("frontPage").Parse(frontPageText)) // HTML template
+var output = template.Must(template.New("output").Parse(outputText))          // HTML template
 
-func init() {
-	frontPage = template.New(nil)
-	frontPage.SetDelims("«", "»")
-	if err := frontPage.Parse(frontPageText); err != nil {
-		panic(err)
-	}
-	output = template.MustParse(outputText, nil)
-}
-
-var outputText = `<pre>{@|html}</pre>`
+var outputText = `<pre>{{printf "%s" . |html}}</pre>`
 
 var frontPageText = `<!doctype html>
 <html>
@@ -264,7 +256,7 @@ function compileUpdate() {
 </head>
 <body>
 <table width="100%"><tr><td width="60%" valign="top">
-<textarea autofocus="true" id="edit" spellcheck="false" onkeydown="keyHandler(event);" onkeyup="autocompile();">«@|html»</textarea>
+<textarea autofocus="true" id="edit" spellcheck="false" onkeydown="keyHandler(event);" onkeyup="autocompile();">{{printf "%s" . |html}}</textarea>
 <div class="hints">
 (Shift-Enter to compile and run.)&nbsp;&nbsp;&nbsp;&nbsp;
 <input type="checkbox" id="autocompile" value="checked" /> Compile and run after each keystroke

misc/nacl/naclrun

@@ -1,15 +0,0 @@
-#!/bin/sh
-# 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.
-
-# Run nacl binary in debug mode (allow file access)
-# and then grep away the chatter.
-# See ../../src/pkg/exp/nacl/README for more on
-# how to configure NaCl.
-
-nacl -d "$@" >/tmp/nacl.out.$$ 2>&1
-status=$?
-egrep -v 'DEBUG MODE ENABLED|^\[[0-9]+,' /tmp/nacl.out.$$
-rm -f /tmp/nacl.out.$$
-exit $status

misc/vim/autoload/go/complete.vim

@@ -0,0 +1,49 @@
+" 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.
+"
+" This file provides a utility function that performs auto-completion of
+" package names, for use by other commands.
+
+let s:goos = $GOOS
+let s:goarch = $GOARCH
+
+if len(s:goos) == 0
+  if exists('g:golang_goos')
+    let s:goos = g:golang_goos
+  elseif has('win32') || has('win64')
+    let s:goos = 'windows'
+  elseif has('macunix')
+    let s:goos = 'darwin'
+  else
+    let s:goos = '*'
+  endif
+endif
+
+if len(s:goarch) == 0
+  if exists('g:golang_goarch')
+    let s:goarch = g:golang_goarch
+  else
+    let s:goarch = '*'
+  endif
+endif
+
+function! go#complete#Package(ArgLead, CmdLine, CursorPos)
+  let goroot = $GOROOT
+  if len(goroot) == 0
+    " should not occur.
+    return []
+  endif
+  let ret = {}
+  let root = expand(goroot.'/pkg/'.s:goos.'_'.s:goarch)
+  for i in split(globpath(root, a:ArgLead.'*'), "\n")
+    if isdirectory(i)
+      let i .= '/'
+    elseif i !~ '\.a$'
+      continue
+    endif
+    let i = substitute(substitute(i[len(root)+1:], '[\\]', '/', 'g'), '\.a$', '', 'g')
+    let ret[i] = i
+  endfor
+  return sort(keys(ret))
+endfunction

misc/vim/ftdetect/gofiletype.vim

@@ -1 +1 @@
-au BufRead,BufNewFile *.go set filetype=go
+au BufReadPre,BufNewFile *.go set filetype=go fileencoding=utf-8 fileencodings=utf-8

misc/vim/ftplugin/go/godoc.vim

@@ -0,0 +1,13 @@
+" 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.
+"
+" godoc.vim: Vim command to see godoc.
+
+if exists("b:did_ftplugin")
+    finish
+endif
+
+silent! nmap <buffer> <silent> K <Plug>(godoc-keyword)
+
+" vim:ts=4:sw=4:et

misc/vim/ftplugin/go/import.vim

@@ -36,9 +36,9 @@ if exists("b:did_ftplugin")
     finish
 endif
 
-command! -buffer -nargs=? Drop call s:SwitchImport(0, '', <f-args>)
-command! -buffer -nargs=1 Import call s:SwitchImport(1, '', <f-args>)
-command! -buffer -nargs=* ImportAs call s:SwitchImport(1, <f-args>)
+command! -buffer -nargs=? -complete=customlist,go#complete#Package Drop call s:SwitchImport(0, '', <f-args>)
+command! -buffer -nargs=1 -complete=customlist,go#complete#Package Import call s:SwitchImport(1, '', <f-args>)
+command! -buffer -nargs=* -complete=customlist,go#complete#Package ImportAs call s:SwitchImport(1, <f-args>)
 map <buffer> <LocalLeader>f :Import fmt<CR>
 map <buffer> <LocalLeader>F :Drop fmt<CR>
 

misc/vim/plugin/godoc.vim

@@ -0,0 +1,85 @@
+" 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.
+"
+" godoc.vim: Vim command to see godoc.
+
+if exists("g:loaded_godoc")
+  finish
+endif
+let g:loaded_godoc = 1
+
+let s:buf_nr = -1
+let s:last_word = ''
+
+function! s:GodocView()
+  if !bufexists(s:buf_nr)
+    leftabove new
+    file `="[Godoc]"`
+    let s:buf_nr = bufnr('%')
+  elseif bufwinnr(s:buf_nr) == -1
+    leftabove split
+    execute s:buf_nr . 'buffer'
+    delete _
+  elseif bufwinnr(s:buf_nr) != bufwinnr('%')
+    execute bufwinnr(s:buf_nr) . 'wincmd w'
+  endif
+
+  setlocal filetype=godoc
+  setlocal bufhidden=delete
+  setlocal buftype=nofile
+  setlocal noswapfile
+  setlocal nobuflisted
+  setlocal modifiable
+  setlocal nocursorline
+  setlocal nocursorcolumn
+  setlocal iskeyword+=:
+  setlocal iskeyword-=-
+
+  nnoremap <buffer> <silent> K :Godoc<cr>
+
+  au BufHidden <buffer> call let <SID>buf_nr = -1
+endfunction
+
+function! s:GodocWord(word)
+  let word = a:word
+  silent! let content = system('godoc ' . word)
+  if v:shell_error || !len(content)
+    if len(s:last_word)
+      silent! let content = system('godoc ' . s:last_word.'/'.word)
+      if v:shell_error || !len(content)
+        echo 'No documentation found for "' . word . '".'
+        return
+      endif
+      let word = s:last_word.'/'.word
+    else
+      echo 'No documentation found for "' . word . '".'
+      return
+    endif
+  endif
+  let s:last_word = word
+  silent! call s:GodocView()
+  setlocal modifiable
+  silent! %d _
+  silent! put! =content
+  silent! normal gg
+  setlocal nomodifiable
+  setfiletype godoc
+endfunction
+
+function! s:Godoc(...)
+  let word = join(a:000, ' ')
+  if !len(word)
+    let word = expand('<cword>')
+  endif
+  let word = substitute(word, '[^a-zA-Z0-9\/]', '', 'g')
+  if !len(word)
+    return
+  endif
+  call s:GodocWord(word)
+endfunction
+
+command! -nargs=* -range -complete=customlist,go#complete#Package Godoc :call s:Godoc(<q-args>)
+nnoremap <silent> <Plug>(godoc-keyword) :<C-u>call <SID>Godoc('')<CR>
+
+" vim:ts=4:sw=4:et

misc/vim/readme.txt

@@ -1,5 +1,17 @@
-Vim syntax highlighting for Go (http://golang.org)
-==================================================
+Vim plugins for Go (http://golang.org)
+======================================
+
+To use all the Vim plugins, add these lines to your vimrc.
+
+  set rtp+=$GOROOT/misc/vim
+  filetype plugin indent on
+  syntax on
+
+If you want to select fewer plugins, use the instructions in the rest of
+this file.
+
+Vim syntax highlighting
+-----------------------
 
 To install automatic syntax highlighting for GO programs:
 
@@ -18,15 +30,17 @@ commands:
 
   mkdir -p $HOME/.vim/ftdetect
   mkdir -p $HOME/.vim/syntax
+  mkdir -p $HOME/.vim/autoload/go
   ln -s $GOROOT/misc/vim/ftdetect/gofiletype.vim $HOME/.vim/ftdetect/
   ln -s $GOROOT/misc/vim/syntax/go.vim $HOME/.vim/syntax
+  ln -s $GOROOT/misc/vim/autoload/go/complete.vim $HOME/.vim/autoload/go
   echo "syntax on" >> $HOME/.vimrc
 
 
-Vim filetype plugins for Go
-===========================
+Vim filetype plugins
+--------------------
 
-To install one of the available filetype plugins for Go:
+To install one of the available filetype plugins:
 
   1. Same as 1 above.
   2. Copy or link one or more plugins from ftplugin/go/*.vim to the
@@ -37,10 +51,10 @@ To install one of the available filetype plugins for Go:
      filetype plugin on
 
 
-Vim indentation plugin for Go
-=============================
+Vim indentation plugin
+----------------------
 
-To install automatic indentation for Go:
+To install automatic indentation:
 
   1. Same as 1 above.
   2. Copy or link indent/go.vim to the indent directory underneath your vim
@@ -48,3 +62,15 @@ To install automatic indentation for Go:
   3. Add the following line to your .vimrc file (normally $HOME/.vimrc):
 
      filetype indent on
+
+
+Godoc plugin
+------------
+
+To install godoc plugin:
+
+  1. Same as 1 above.
+  2. Copy or link plugin/godoc.vim to $HOME/.vim/plugin/godoc,
+     syntax/godoc.vim to $HOME/.vim/syntax/godoc.vim,
+     ftplugin/go/godoc.vim to $HOME/.vim/ftplugin/go/godoc.vim.
+     and autoload/go/complete.vim to $HOME/.vim/autoload/go/complete.vim.

misc/vim/syntax/godoc.vim

@@ -0,0 +1,20 @@
+" 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.
+
+if exists("b:current_syntax")
+  finish
+endif
+
+syn case match
+syn match  godocTitle "^\([A-Z]*\)$"
+
+command -nargs=+ HiLink hi def link <args>
+
+HiLink godocTitle Title
+
+delcommand HiLink
+
+let b:current_syntax = "godoc"
+
+" vim:ts=4 sts=2 sw=2:

src/Make.ccmd

@@ -9,7 +9,7 @@ TARG:=$(TARG).exe
 endif
 
 $(TARG): $(OFILES) $(LIB)
-	$(HOST_LD) -o $(TARG) -L"$(GOROOT)"/lib $(OFILES) $(LIB) -lbio -l9 -lm $(HOST_LDFLAGS)
+	$(HOST_LD) -o $(TARG) -L"$(GOROOT)"/lib $(OFILES) $(LIB) -lmach -lbio -l9 -lm $(HOST_LDFLAGS)
 
 $(OFILES): $(HFILES)
 
@@ -36,6 +36,7 @@ y.tab.c: y.tab.h
 
 all: $(TARG)
 
+# Use $(PWD)/$*.c so that gdb shows full path in stack traces.
 %.$(HOST_O): %.c
 	$(HOST_CC) $(HOST_CFLAGS) -c "$(PWD)/$*.c"
 

src/Make.clib

@@ -6,6 +6,7 @@
 
 all: $(LIB)
 
+# Use $(PWD)/$*.c so that gdb shows full path in stack traces.
 %.$(HOST_O): %.c
 	$(HOST_CC) $(HOST_CFLAGS) -c "$(PWD)/$*.c"
 

src/Make.inc

@@ -121,6 +121,21 @@ HOST_CFLAGS=-I"$(GOROOT)/include" $(HOST_EXTRA_CFLAGS)
 HOST_LDFLAGS=$(HOST_EXTRA_LDFLAGS)
 PWD=$(shell pwd)
 
+# Decide whether use of cgo is okay.
+ifeq ($(CGO_ENABLED),)
+# Default on...
+CGO_ENABLED:=1
+ifeq ($(GOARCH),arm)  # ... but not on ARM
+CGO_ENABLED:=0
+endif
+ifeq ($(GOOS),plan9)  # ... and not on Plan 9
+CGO_ENABLED:=0
+endif
+ifeq ($(GOOS),openbsd)  # ... and not on OpenBSD
+CGO_ENABLED:=0
+endif
+endif
+
 # Make environment more standard.
 LANG:=
 LC_ALL:=C
@@ -130,11 +145,12 @@ GREP_COLORS:=
 export LANG LC_ALL LC_CTYPE GREP_OPTIONS GREP_COLORS
 
 go-env:
-	@echo export GOARCH=$(GOARCH)
-	@echo export GOOS=$(GOOS)
-	@echo export GOHOSTARCH=$(GOHOSTARCH)
-	@echo export GOHOSTOS=$(GOHOSTOS)
-	@echo export O=$O
+	@echo export GOARCH="$(GOARCH)"
+	@echo export GOOS="$(GOOS)"
+	@echo export GOHOSTARCH="$(GOHOSTARCH)"
+	@echo export GOHOSTOS="$(GOHOSTOS)"
+	@echo export CGO_ENABLED="$(CGO_ENABLED)"
+	@echo export O="$O"
 	@echo export AS="$(AS)"
 	@echo export CC="$(CC)"
 	@echo export GC="$(GC)"

src/Make.pkg

@@ -59,7 +59,7 @@ coverage:
 	gotest
 	6cov -g $(shell pwd) $O.out | grep -v '_test\.go:'
 
-CLEANFILES+=*.so _obj _test _testmain.go *.exe _cgo* *.cgo[12].* test.out build.out
+CLEANFILES+=*.so _obj _test _testmain.go *.exe _cgo* test.out build.out
 
 test:
 	gotest

src/all-qemu.bash

@@ -6,10 +6,11 @@
 # Run all.bash but exclude tests that depend on functionality
 # missing in QEMU's system call emulation.
 
+export GOARCH=arm
 export NOTEST=""
-
-NOTEST="$NOTEST big" # xxx
-NOTEST="$NOTEST http net rpc syslog websocket"  # no localhost network
+NOTEST="$NOTEST big" # just slow
+NOTEST="$NOTEST go/build" # wants to run cgo
+NOTEST="$NOTEST http http/cgi net rpc syslog websocket"  # no localhost network
 NOTEST="$NOTEST os"  # 64-bit seek fails
 
 ./all.bash

src/cmd/5a/a.h

@@ -28,8 +28,6 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 // THE SOFTWARE.
 
-#include <u.h>
-#include <libc.h>
 #include <bio.h>
 #include "../5l/5.out.h"
 
@@ -54,7 +52,9 @@ typedef	struct	Hist	Hist;
 #define	NSYMB		8192
 #define	BUFSIZ		8192
 #define	HISTSZ		20
+#ifndef	EOF
 #define	EOF		(-1)
+#endif
 #define	IGN		(-2)
 #define	GETC()		((--fi.c < 0)? filbuf(): *fi.p++ & 0xff)
 #define	NHASH		503