weekly.2012-03-27

Orignally published on The Go Programming Language, September 21, 2011.

http://blog.golang.org/2011/09/go-image-package.html

Update #2547

R=adg, nigeltao
CC=golang-dev
https://golang.org/cl/5933049

.hgignore

@@ -3,7 +3,7 @@ syntax:glob
 .git
 .gitignore
 *.[568ao]
-*.ao
+*.a[568o]
 *.so
 *.pyc
 ._*
@@ -23,36 +23,31 @@ _test
 _testmain.go
 build.out
 test.out
-y.tab.[ch]
-doc/htmlgen
-doc/codelab/wiki/*.bin
+doc/tmpltohtml
+doc/articles/wiki/*.bin
 misc/cgo/life/run.out
-misc/dashboard/builder/gobuilder
+misc/cgo/stdio/run.out
+misc/cgo/testso/main
+misc/dashboard/builder/builder
 misc/goplay/goplay
-src/Make.inc
+misc/osx/*.pkg
+misc/osx/*.dmg
 src/cmd/6a/6a
+src/cmd/?a/y.output
 src/cmd/?l/enam.c
 src/cmd/cc/y.output
-src/cmd/gc/builtin.c
+src/cmd/dist/dist.dSYM
 src/cmd/gc/mkbuiltin1
 src/cmd/gc/opnames.h
 src/cmd/gc/y.output
-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
-src/pkg/runtime/*/asm.h
+src/pkg/exp/norm/normregtest
+src/pkg/exp/ebnflint/ebnflint
+src/pkg/go/doc/headscan
 src/pkg/runtime/goc2c
 src/pkg/runtime/mkversion
-src/pkg/runtime/runtime.acid.*
-src/pkg/runtime/runtime_defs.go
-src/pkg/runtime/version.go
-src/pkg/runtime/version_*.go
+src/pkg/runtime/z*
 src/pkg/unicode/maketables
 src/pkg/*.*/
 test/pass.out
@@ -60,6 +55,8 @@ test/run.out
 test/times.out
 test/garbage/*.out
 goinstall.log
+last-change
+VERSION.cache
 
 syntax:regexp
 ^bin/

.hgtags

@@ -74,5 +74,37 @@ d292bc7886682d35bb391bf572be28656baee12d release.r58.1
 3c21f37b25a3f7a1726265c5339c8a7b0b329336 weekly.2011-07-19
 bb28251f6da4aca85658582c370c7df89d34efd4 weekly.2011-07-29
 d5785050f61d973fc36775f7bd2e26689529cb3e release.r59
-d5785050f61d973fc36775f7bd2e26689529cb3e release
 c17ce5ec06b4bd5cf6e7ff2ceb0a60c2e40e0b17 weekly.2011-08-10
+6eb2b9dbe489acb57a2bfc1de31ec2239ed94326 weekly.2011-08-17
+c934f6f5fe8b30b4b3210ee3f13669e6e4670c32 weekly.2011-09-01
+c77997547d546c36c7b969586a36de7ceda74e33 weekly.2011-09-07
+b0819469a6df6029a27192fe7b19a73d97404c63 release.r60
+8a09ce0cefc64deab4e6d1ed59a08a53e879bbee weekly.2011-09-16
+fd30c132d1bdeb79f8f111cb721fb1c78b767b27 release.r60.1
+d7322ae4d055a4cf3efaf842d0717a41acd85bac weekly.2011-09-21
+32a5db19629897641b2d488de4d1b998942ef80e release.r60.2
+3bdabf483805fbf0c7ef013fd09bfd6062b9d3f2 weekly.2011-10-06
+c1702f36df0397c19fc333571a771666029aa37e release.r60.3
+acaddf1cea75c059d19b20dbef35b20fb3f38954 release.r58.2
+6d7136d74b656ba6e1194853a9486375005227ef weekly.2011-10-18
+941b8015061a0f6480954821dd589c60dfe35ed1 weekly.2011-10-25
+7c1f789e6efd153951e85e3f28722fc69efc2af2 weekly.2011-10-26
+e69e528f2afc25a8334cfb9359fa4fcdf2a934b6 weekly.2011-11-01
+780c85032b174c9d4b42adf75d82bc85af7d78d1 weekly.2011-11-02
+f4397ad6e87c7ce5feac9b01686f1ebd6cbaac4e weekly.2011-11-08
+2f4482b89a6b5956828872137b6b96636cd904d3 weekly.2011-11-09
+b4a91b6933748db1a7150c06a1b55ad506e52906 weekly.2011-11-18
+80db2da6495a20ddff8305c236825811db8c8665 weekly.2011-12-01
+0beb796b4ef8747af601ed5ea6766d5b1340086b weekly.2011-12-02
+0c39eee85b0d1606b79c8ebcdeb3b67ed5849e39 weekly.2011-12-06
+82fdc445f2ff2c85043446eb84a19cc999dfcb95 weekly.2011-12-14
+4a82689277582a2a60f006e3f158985f2f8d1da3 weekly.2011-12-22
+354b17404643c0f1a710bdc48927dff02f203ae3 weekly.2012-01-15
+9f2be4fbbf690b9562c6e98b91daa0003f0913c7 weekly.2012-01-20
+1107a7d3cb075836387adfab5ce56d1b3e56637d weekly.2012-01-27
+52ba9506bd993663a0a033c2bd68699e25d061ab weekly.2012-02-07
+43cf9b39b6477d3144b0353ee91096e55db6107f weekly.2012-02-14
+96bd78e7d35e892113bdfa1bdc392d3a5f2e644b weekly.2012-02-22
+f4470a54e6dbcdd52d8d404e12e4754adcd2c948 weekly.2012-03-04
+3cdba7b0650c6c906ef3e782654f61701abd7dd2 weekly.2012-03-13
+bce220d0377405146527ab9478867cbc572a6886 weekly.2012-03-22

AUTHORS

@@ -14,10 +14,12 @@ Albert Strasheim <fullung@gmail.com>
 Aleksandar Dezelin <dezelin@gmail.com>
 Alex Brainman <alex.brainman@gmail.com>
 Alexander Orlov <alexander.orlov@loxal.net>
+Alexander Reece <awreece@gmail.com>
 Alexey Borzenkov <snaury@gmail.com>
 Amrut Joshi <amrut.joshi@gmail.com>
 Andrei Vieru <euvieru@gmail.com>
 Andrew Balholm <andybalholm@gmail.com>
+Andrew Pritchard <awpritchard@gmail.com>
 Andrew Skiba <skibaa@gmail.com>
 Andrey Mirtchovski <mirtchovski@gmail.com>
 Andy Davis <andy@bigandian.com>
@@ -29,22 +31,32 @@ Aron Nopanen <aron.nopanen@gmail.com>
 Arvindh Rajesh Tamilmani <art@a-30.net>
 Ben Olive <sionide21@gmail.com>
 Benny Siegert <bsiegert@gmail.com>
+Berengar Lehr <berengar.lehr@gmx.de>
+Bjorn Tipling <bjorn.tipling@gmail.com>
+Blake Mizerany <blake.mizerany@gmail.com>
 Bobby Powers <bobbypowers@gmail.com>
 Caine Tighe <arctanofyourface@gmail.com>
 Charles L. Dorian <cldorian@gmail.com>
 Chris Dollin <ehog.hedge@gmail.com>
+Chris Farmiloe <chrisfarms@gmail.com>
 Chris Jones <chris@cjones.org>
 Chris Lennert <calennert@gmail.com>
 Christian Himpel <chressie@googlemail.com>
+Christoph Hack <christoph@tux21b.org>
 Christopher Nielsen <m4dh4tt3r@gmail.com>
+Christopher Redden <christopher.redden@gmail.com>
 Christopher Wedgwood <cw@f00f.org>
 Clement Skau <clementskau@gmail.com>
 Conrad Meyer <cemeyer@cs.washington.edu>
 Corey Thomasson <cthom.lists@gmail.com>
+Damian Gryski <dgryski@gmail.com>
 Dan Sinclair <dan.sinclair@gmail.com>
 Daniel Fleischman <danielfleischman@gmail.com>
+Daniel Krech <eikeon@eikeon.com>
 Daniel Theophanes <kardianos@gmail.com>
+Darren Elwood <darren@textnode.com>
 Dave Cheney <dave@cheney.net>
+David du Colombier <0intro@gmail.com>
 David Forsythe <dforsythe@gmail.com>
 David G. Andersen <dave.andersen@gmail.com>
 David Jakob Fritz <david.jakob.fritz@gmail.com>
@@ -54,37 +66,51 @@ Devon H. O'Dell <devon.odell@gmail.com>
 Dmitry Chestnykh <dchest@gmail.com>
 Eden Li <eden.li@gmail.com>
 Eivind Uggedal <eivind@uggedal.com>
+Emil Hessman <c.emil.hessman@gmail.com>
 Eoghan Sherry <ejsherry@gmail.com>
 Eric Clark <zerohp@gmail.com>
 Eric Eisner <eric.d.eisner@gmail.com>
+Esko Luontola <esko.luontola@gmail.com>
 Evan Shaw <chickencha@gmail.com>
 Fan Hongjian <fan.howard@gmail.com>
 Fazlul Shahriar <fshahriar@gmail.com>
 Firmansyah Adiputra <frm.adiputra@gmail.com>
 Florian Uekermann <florian@uekermann-online.de>
+Florian Weimer <fw@deneb.enyo.de>
+Francisco Souza <franciscossouza@gmail.com>
 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>
+Gustav Paul <gustav.paul@gmail.com>
 Gustavo Niemeyer <gustavo@niemeyer.net>
+Gwenael Treguier <gwenn.kahz@gmail.com>
 Harley Laue <losinggeneration@gmail.com>
 Hector Chu <hectorchu@gmail.com>
+Hong Ruiqi <hongruiqi@gmail.com>
 Icarus Sparry <golang@icarus.freeuk.com>
+Ingo Oeser <nightlyone@googlemail.com>
 Isaac Wagner <ibw@isaacwagner.me>
 James Fysh <james.fysh@gmail.com>
 James Meneghello <rawrz0r@gmail.com>
+James P. Cooper <jamespcooper@gmail.com>
 James Toy <nil@opensesame.st>
 James Whitehead <jnwhiteh@gmail.com>
 Jan H. Hosang <jan.hosang@gmail.com>
 Jan Mercl <befelemepeseveze@gmail.com>
+Jan Newmarch <jan.newmarch@gmail.com>
+Jani Monoses <jani.monoses@ubuntu.com>
+Jaroslavas Počepko <jp@webmaster.ms>
 Jeff Hodges <jeff@somethingsimilar.com>
 Jeff R. Allen <jra@nella.org>
+Jeremy Jackins <jeremyjackins@gmail.com>
 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>
+Jongmin Kim <atomaths@gmail.com>
 Jose Luis Vázquez González <josvazg@gmail.com>
 Josh Goebel <dreamer3@gmail.com>
 Jukka-Pekka Kekkonen <karatepekka@gmail.com>
@@ -97,18 +123,24 @@ Ken Rockot <ken@oz.gs>
 Kevin Ballard <kevin@sb.org>
 Kyle Consalus <consalus@gmail.com>
 Kyle Lemons <kyle@kylelemons.net>
+Lai Jiangshan <eag0628@gmail.com>
 Lorenzo Stoakes <lstoakes@gmail.com>
+Luca Greco <luca.greco@alcacoop.it>
 Lucio De Re <lucio.dere@gmail.com>
 Luit van Drongelen <luitvd@gmail.com>
 Markus Duft <markus.duft@salomon.at>
 Martin Neubauer <m.ne@gmx.net>
+Mateusz Czapliński <czapkofan@gmail.com>
 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>
+Michał Derkacz <ziutek@lnet.pl>
 Miek Gieben <miek@miek.nl>
 Mikael Tillenius <mikti42@gmail.com>
+Mike Rosset <mike.rosset@gmail.com>
+Miki Tebeka <miki.tebeka@gmail.com>
 Mikio Hara <mikioh.mikioh@gmail.com>
 Mikkel Krautz <mikkel@krautz.dk>
 Moriyoshi Koizumi <mozo@mozo.jp>
@@ -117,10 +149,14 @@ ngmoco, LLC
 Nicholas Waples <nwaples@gmail.com>
 Nigel Kerr <nigel.kerr@gmail.com>
 Olivier Antoine <olivier.antoine@gmail.com>
+Olivier Duperray <duperray.olivier@gmail.com>
 Padraig Kitterick <padraigkitterick@gmail.com>
 Paolo Giarrusso <p.giarrusso@gmail.com>
 Pascal S. de Kloe <pascal@quies.net>
 Patrick Gavlin <pgavlin@gmail.com>
+Patrick Mylund Nielsen <patrick@patrickmn.com>
+Paul Lalonde <paul.a.lalonde@gmail.com>
+Paul Sbarra <Sbarra.Paul@gmail.com>
 Petar Maymounkov <petarm@gmail.com>
 Peter Froehlich <peter.hans.froehlich@gmail.com>
 Peter Mundy <go.peter.90@gmail.com>
@@ -128,24 +164,34 @@ Peter Williams <pwil3058@gmail.com>
 Pieter Droogendijk <pieter@binky.org.uk>
 Quan Yong Zhai <qyzhai@gmail.com>
 Raif S. Naffah <go@naffah-raif.name>
+Rémy Oudompheng <oudomphe@phare.normalesup.org>
 Risto Jaakko Saarelma <rsaarelm@gmail.com>
+Robert Figueiredo <robfig@gmail.com>
 Robert Hencke <robert.hencke@gmail.com>
 Roger Pau Monné <royger@gmail.com>
 Roger Peppe <rogpeppe@gmail.com>
+Ron Minnich <rminnich@gmail.com>
 Ross Light <rlight2@gmail.com>
 Ryan Hitchman <hitchmanr@gmail.com>
+Sanjay Menakuru <balasanjay@gmail.com>
 Scott Lawrence <bytbox@gmail.com>
 Sebastien Binet	<seb.binet@gmail.com>
+Sébastien Paolacci <sebastien.paolacci@gmail.com>
 Sergei Skorobogatov <skorobo@rambler.ru>
 Sergey 'SnakE'  Gromov <snake.scaly@gmail.com>
 Sergio Luis O. B. Correia <sergio@larces.uece.br>
+Shenghou Ma <minux.ma@gmail.com>
 Spring Mc <heresy.mc@gmail.com>
-Stefan Nilsson <snilsson@nada.kth.se>
+Stefan Nilsson <snilsson@nada.kth.se> <trolleriprofessorn@gmail.com>
 Stephen Weinberg <stephen@q5comm.com>
 Sven Almgren <sven@tras.se>
+Szabolcs Nagy <nsz@port70.net>
 Tarmigan Casebolt <tarmigan@gmail.com>
+Taru Karttunen <taruti@taruti.net>
 Timo Savola <timo.savola@gmail.com>
 Tor Andersson <tor.andersson@gmail.com>
+Ugorji Nwoke <ugorji@gmail.com>
+Vadim Vygonets <unixdj@gmail.com>
 Vincent Ambo <tazjin@googlemail.com>
 Vincent Vanackere <vincent.vanackere@gmail.com>
 Vinu Rajashekhar <vinutheraj@gmail.com>
@@ -153,6 +199,9 @@ Volker Dobler <dr.volker.dobler@gmail.com>
 Wei Guangjing <vcc.163@gmail.com>
 William Josephson <wjosephson@gmail.com>
 Yasuhiro Matsumoto <mattn.jp@gmail.com>
+Yissakhar Z. Beck <yissakhar.beck@gmail.com>
 Yongjian Xu <i3dmaster@gmail.com>
+Yoshiyuki Kanno <nekotaroh@gmail.com> <yoshiyuki.kanno@stoic.co.jp>
 Yuusei Kuwana <kuwana@kumama.org>
 Yuval Pavel Zholkover <paulzhol@gmail.com>
+Ziad Hatahet <hatahet@gmail.com>

CONTRIBUTORS

@@ -38,11 +38,15 @@ Albert Strasheim <fullung@gmail.com>
 Aleksandar Dezelin <dezelin@gmail.com>
 Alex Brainman <alex.brainman@gmail.com>
 Alexander Orlov <alexander.orlov@loxal.net>
+Alexander Reece <awreece@gmail.com>
+Alexandru Moșoi <brtzsnr@gmail.com>
 Alexey Borzenkov <snaury@gmail.com>
 Amrut Joshi <amrut.joshi@gmail.com>
+Andrea Spadaccini <spadaccio@google.com>
 Andrei Vieru <euvieru@gmail.com>
 Andrew Balholm <andybalholm@gmail.com>
 Andrew Gerrand <adg@golang.org>
+Andrew Pritchard <awpritchard@gmail.com>
 Andrew Skiba <skibaa@gmail.com>
 Andrey Mirtchovski <mirtchovski@gmail.com>
 Andy Davis <andy@bigandian.com>
@@ -55,11 +59,14 @@ Arvindh Rajesh Tamilmani <art@a-30.net>
 Austin Clements <aclements@csail.mit.edu>
 Balazs Lecz <leczb@google.com>
 Ben Eitzen <eitzenb@golang.org>
+Ben Fried <ben.fried@gmail.com>
 Ben Lynn <benlynn@gmail.com>
 Ben Olive <sionide21@gmail.com>
 Benny Siegert <bsiegert@gmail.com>
 Berengar Lehr <Berengar.Lehr@gmx.de>
 Bill Neubauer <wcn@golang.org> <wcn@google.com>
+Bjorn Tipling <bjorn.tipling@gmail.com>
+Blake Mizerany <blake.mizerany@gmail.com>
 Bobby Powers <bobbypowers@gmail.com>
 Brad Fitzpatrick <bradfitz@golang.org> <bradfitz@gmail.com>
 Brendan O'Dea <bod@golang.org>
@@ -67,22 +74,30 @@ Caine Tighe <arctanofyourface@gmail.com>
 Cary Hull <chull@google.com>
 Charles L. Dorian <cldorian@gmail.com>
 Chris Dollin <ehog.hedge@gmail.com>
+Chris Farmiloe <chrisfarms@gmail.com>
+Chris Hundt <hundt@google.com>
 Chris Jones <chris@cjones.org> <chris.jones.yar@gmail.com>
 Chris Lennert <calennert@gmail.com>
 Christian Himpel <chressie@googlemail.com> <chressie@gmail.com>
+Christoph Hack <christoph@tux21b.org>
 Christopher Nielsen <m4dh4tt3r@gmail.com>
+Christopher Redden <christopher.redden@gmail.com>
 Christopher Wedgwood <cw@f00f.org>
 Clement Skau <clementskau@gmail.com>
 Conrad Meyer <cemeyer@cs.washington.edu>
 Corey Thomasson <cthom.lists@gmail.com>
+Damian Gryski <dgryski@gmail.com>
 Dan Sinclair <dan.sinclair@gmail.com>
 Daniel Fleischman <danielfleischman@gmail.com>
+Daniel Krech <eikeon@eikeon.com>
 Daniel Nadasi <dnadasi@google.com>
 Daniel Theophanes <kardianos@gmail.com>
+Darren Elwood <darren@textnode.com>
 Dave Cheney <dave@cheney.net>
 Dave Grijalva <dgrijalva@ngmoco.com>
 David Anderson <danderson@google.com>
-David Crawshaw <david.crawshaw@zentus.com>
+David Crawshaw <david.crawshaw@zentus.com> <crawshaw@google.com>
+David du Colombier <0intro@gmail.com>
 David Forsythe <dforsythe@gmail.com>
 David G. Andersen <dave.andersen@gmail.com>
 David Jakob Fritz <david.jakob.fritz@gmail.com>
@@ -94,47 +109,63 @@ Dmitriy Vyukov <dvyukov@google.com>
 Dmitry Chestnykh <dchest@gmail.com>
 Eden Li <eden.li@gmail.com>
 Eivind Uggedal <eivind@uggedal.com>
+Emil Hessman <c.emil.hessman@gmail.com>
 Eoghan Sherry <ejsherry@gmail.com>
 Eric Clark <zerohp@gmail.com>
 Eric Eisner <eric.d.eisner@gmail.com>
+Esko Luontola <esko.luontola@gmail.com>
 Evan Martin <evan.martin@gmail.com>
 Evan Shaw <chickencha@gmail.com>
 Fan Hongjian <fan.howard@gmail.com>
 Fazlul Shahriar <fshahriar@gmail.com>
 Firmansyah Adiputra <frm.adiputra@gmail.com>
 Florian Uekermann <florian@uekermann-online.de> <f1@uekermann-online.de>
+Florian Weimer <fw@deneb.enyo.de>
+Francisco Souza <franciscossouza@gmail.com>
 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>
+Gustav Paul <gustav.paul@gmail.com>
 Gustavo Niemeyer <gustavo@niemeyer.net> <n13m3y3r@gmail.com>
+Gwenael Treguier <gwenn.kahz@gmail.com>
 Harley Laue <losinggeneration@gmail.com>
 Hector Chu <hectorchu@gmail.com>
+Hong Ruiqi <hongruiqi@gmail.com>
 Ian Lance Taylor <iant@golang.org>
 Icarus Sparry <golang@icarus.freeuk.com>
+Ingo Oeser <nightlyone@googlemail.com> <nightlyone@gmail.com>
 Isaac Wagner <ibw@isaacwagner.me>
 Ivan Krasin <krasin@golang.org>
 Jacob Baskin <jbaskin@google.com>
 James Aguilar <jaguilar@google.com>
 James Fysh <james.fysh@gmail.com>
 James Meneghello <rawrz0r@gmail.com>
+James P. Cooper <jamespcooper@gmail.com>
 James Toy <nil@opensesame.st>
 James Whitehead <jnwhiteh@gmail.com>
-Jamie Gennis <jgennis@google.com>
+Jamie Gennis <jgennis@google.com> <jgennis@gmail.com>
 Jan H. Hosang <jan.hosang@gmail.com>
 Jan Mercl <befelemepeseveze@gmail.com>
+Jan Newmarch <jan.newmarch@gmail.com>
+Jani Monoses <jani.monoses@ubuntu.com> <jani.monoses@gmail.com>
+Jaroslavas Počepko <jp@webmaster.ms>
 Jeff Hodges <jeff@somethingsimilar.com>
 Jeff R. Allen <jra@nella.org> <jeff.allen@gmail.com>
+Jeremy Jackins <jeremyjackins@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 Beisley <huin@google.com>
 John DeNero <denero@google.com>
 Jonathan Allie <jonallie@google.com>
 Jonathan Mark <jhmark@xenops.com> <jhmark000@gmail.com>
+Jonathan Pittman <jmpittman@google.com> <jonathan.mark.pittman@gmail.com>
 Jonathan Wills <runningwild@gmail.com>
+Jongmin Kim <atomaths@gmail.com>
 Jos Visser <josv@google.com>
 Jose Luis Vázquez González <josvazg@gmail.com>
 Josh Goebel <dreamer3@gmail.com>
@@ -150,8 +181,11 @@ Kevin Ballard <kevin@sb.org>
 Kirklin McDonald <kirklin.mcdonald@gmail.com>
 Kyle Consalus <consalus@gmail.com>
 Kyle Lemons <kyle@kylelemons.net> <kevlar@google.com>
+Lai Jiangshan <eag0628@gmail.com>
 Larry Hosken <lahosken@golang.org>
 Lorenzo Stoakes <lstoakes@gmail.com>
+Louis Kruger <louisk@google.com>
+Luca Greco <luca.greco@alcacoop.it>
 Lucio De Re <lucio.dere@gmail.com>
 Luit van Drongelen <luitvd@gmail.com>
 Luuk van Dijk <lvd@golang.org> <lvd@google.com>
@@ -159,18 +193,24 @@ Marcel van Lohuizen <mpvl@golang.org>
 Mark Zavislak <zavislak@google.com>
 Markus Duft <markus.duft@salomon.at>
 Martin Neubauer <m.ne@gmx.net>
+Mateusz Czapliński <czapkofan@gmail.com>
 Mathieu Lonjaret <mathieu.lonjaret@gmail.com>
 Matt Jones <mrjones@google.com>
 Matthew Horsnell <matthew.horsnell@gmail.com>
+Maxim Pimenov <mpimenov@google.com>
 Maxim Ushakov <ushakov@google.com>
 Micah Stetson <micah.stetson@gmail.com>
 Michael Elkins <michael.elkins@gmail.com>
 Michael Hoisie <hoisie@gmail.com>
+Michael Shields <mshields@google.com>
 Michael T. Jones <mtj@google.com> <michael.jones@gmail.com>
+Michał Derkacz <ziutek@lnet.pl>
 Miek Gieben <miek@miek.nl> <remigius.gieben@gmail.com>
 Mikael Tillenius <mikti42@gmail.com>
+Mike Rosset <mike.rosset@gmail.com>
 Mike Samuel <mikesamuel@gmail.com>
 Mike Solomon <msolo@gmail.com>
+Miki Tebeka <miki.tebeka@gmail.com>
 Mikio Hara <mikioh.mikioh@gmail.com>
 Mikkel Krautz <mikkel@krautz.dk> <krautz@gmail.com>
 Moriyoshi Koizumi <mozo@mozo.jp>
@@ -179,11 +219,15 @@ Nicholas Waples <nwaples@gmail.com>
 Nigel Kerr <nigel.kerr@gmail.com>
 Nigel Tao <nigeltao@golang.org>
 Olivier Antoine <olivier.antoine@gmail.com>
+Olivier Duperray <duperray.olivier@gmail.com>
 Padraig Kitterick <padraigkitterick@gmail.com>
 Paolo Giarrusso <p.giarrusso@gmail.com>
 Pascal S. de Kloe <pascal@quies.net>
 Patrick Gavlin <pgavlin@gmail.com>
+Patrick Mylund Nielsen <patrick@patrickmn.com>
 Paul Borman <borman@google.com>
+Paul Lalonde <paul.a.lalonde@gmail.com>
+Paul Sbarra <Sbarra.Paul@gmail.com>
 Petar Maymounkov <petarm@gmail.com>
 Peter Froehlich <peter.hans.froehlich@gmail.com>
 Peter McKenzie <petermck@google.com>
@@ -195,34 +239,44 @@ Pieter Droogendijk <pieter@binky.org.uk>
 Quan Yong Zhai <qyzhai@gmail.com>
 Raif S. Naffah <go@naffah-raif.name>
 Raph Levien <raph@google.com>
+Rémy Oudompheng <oudomphe@phare.normalesup.org> <remyoudompheng@gmail.com>
 Risto Jaakko Saarelma <rsaarelm@gmail.com>
 Rob Pike <r@golang.org>
+Robert Figueiredo <robfig@gmail.com>
 Robert Griesemer <gri@golang.org>
 Robert Hencke <robert.hencke@gmail.com>
 Roger Pau Monné <royger@gmail.com>
 Roger Peppe <rogpeppe@gmail.com>
+Ron Minnich <rminnich@gmail.com>
 Ross Light <rlight2@gmail.com>
 Russ Cox <rsc@golang.org>
 Ryan Hitchman <hitchmanr@gmail.com>
 Sam Thorogood <thorogood@google.com> <sam.thorogood@gmail.com>
-Sameer Ajmani <ajmani@gmail.com>
+Sameer Ajmani <sameer@golang.org> <ajmani@gmail.com>
+Sanjay Menakuru <balasanjay@gmail.com>
 Scott Lawrence <bytbox@gmail.com>
 Scott Schwartz <scotts@golang.org>
 Sebastien Binet	<seb.binet@gmail.com>
+Sébastien Paolacci <sebastien.paolacci@gmail.com>
 Sergei Skorobogatov <skorobo@rambler.ru>
 Sergey 'SnakE' Gromov <snake.scaly@gmail.com>
 Sergio Luis O. B. Correia <sergio@larces.uece.br>
+Shenghou Ma <minux.ma@gmail.com>
 Spring Mc <heresy.mc@gmail.com>
-Stefan Nilsson <snilsson@nada.kth.se>
+Stefan Nilsson <snilsson@nada.kth.se> <trolleriprofessorn@gmail.com>
 Stephen Ma <stephenm@golang.org>
 Stephen Weinberg <stephen@q5comm.com>
 Sugu Sougoumarane <ssougou@gmail.com>
 Sven Almgren <sven@tras.se>
+Szabolcs Nagy <nsz@port70.net>
 Tarmigan Casebolt <tarmigan@gmail.com>
+Taru Karttunen <taruti@taruti.net>
 Timo Savola <timo.savola@gmail.com>
 Tom Szymanski <tgs@google.com>
 Tor Andersson <tor.andersson@gmail.com>
 Trevor Strohman <trevor.strohman@gmail.com>
+Ugorji Nwoke <ugorji@gmail.com>
+Vadim Vygonets <unixdj@gmail.com>
 Vincent Ambo <tazjin@googlemail.com>
 Vincent Vanackere <vincent.vanackere@gmail.com>
 Vinu Rajashekhar <vinutheraj@gmail.com>
@@ -232,7 +286,10 @@ Wei Guangjing <vcc.163@gmail.com>
 William Chan <willchan@chromium.org>
 William Josephson <wjosephson@gmail.com>
 Yasuhiro Matsumoto <mattn.jp@gmail.com>
+Yissakhar Z. Beck <yissakhar.beck@gmail.com>
 Yongjian Xu <i3dmaster@gmail.com>
+Yoshiyuki Kanno <nekotaroh@gmail.com> <yoshiyuki.kanno@stoic.co.jp>
 Yuusei Kuwana <kuwana@kumama.org>
 Yuval Pavel Zholkover <paulzhol@gmail.com>
 Yves Junqueira <yves.junqueira@gmail.com>
+Ziad Hatahet <hatahet@gmail.com>

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009 The Go Authors. All rights reserved.
+Copyright (c) 2012 The Go Authors. All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are

doc/Makefile

@@ -2,10 +2,26 @@
 # Use of this source code is governed by a BSD-style
 # license that can be found in the LICENSE file.
 
-include ../src/Make.inc
+RAWHTML=\
+	articles/defer_panic_recover.rawhtml\
+	articles/error_handling.rawhtml\
+	articles/slices_usage_and_internals.rawhtml\
+	articles/laws_of_reflection.rawhtml\
+	articles/c_go_cgo.rawhtml\
+	articles/concurrency_patterns.rawhtml\
+	articles/godoc_documenting_go_code.rawhtml\
+	articles/gobs_of_data.rawhtml\
+	articles/json_and_go.rawhtml\
+	articles/json_rpc_tale_of_interfaces.rawhtml\
+	articles/image_draw.rawhtml\
+	articles/image_package.rawhtml\
+	effective_go.rawhtml\
+	go1.rawhtml\
 
-TARG=tmpltohtml
-GOFILES=\
-	tmpltohtml.go\
+all: $(RAWHTML)
 
-include ../src/Make.cmd
+%.rawhtml: %.html
+	godoc -url /doc/$< >$@
+
+clean:
+	rm -f $(RAWHTML)

doc/all.css

@@ -1,204 +0,0 @@
-/* General Styles */
-body {
-  font-family: "Bitstream Vera Sans", Verdana, sans-serif;
-  font-size: 81.25%;
-  line-height: 1.23em;
-  padding: 0;
-  margin: 1.23em;
-  background: white;
-  color: black;
-}
-a {
-  color: #04a;
-  text-decoration: none;
-}
-a:visited {
-  color: #04a;
-}
-a:hover {
-  color: #a40;
-  text-decoration: underline;
-}
-a:active {
-  color: #c00;
-}
-code, pre {
-  font-size: 1.2em; 
-}
-pre {
-  background: #F0F0F0;
-  padding: 0.5em 1em;
-}
-
-/* Top bar */
-#container {
-  width: 100%;
-  margin: auto;
-}
-#topnav {
-  height: 55px;
-  background: url(/doc/logo.png) no-repeat top left;
-}
-a#logo-box {
-  display: block;
-  height: 55px;
-}
-h1#title {
-  display: none;
-}
-#nav-main {
-  float: right;
-  width: 500px;
-  margin-top: -5px;
-  text-align: center;
-}
-#nav-main ul {
-  padding-left: 0;
-  margin-left: 0;
-  margin-bottom: 0.5em;
-}
-#nav-main li a {
-  display: inline;
-  display: inline-block;
-  padding: .46em .62em .38em .62em;
-}
-#nav-main li a:link,
-#nav-main li a:visited {
-  color: #000;
-}
-#nav-main li {
-  display: inline;
-  display: inline-block;
-  background: #e6e6e6 url(/doc/button_background.png) repeat-x;
-  border: solid 1px #999;
-  margin-left: -1px;
-  text-shadow: #fff 0 1px 0;
-  box-shadow: 0 1px 1px #ccc;
-  -moz-box-shadow: 0 1px 1px #ccc;
-  -webkit-box-shadow: 0 1px 1px #ccc;
-}
-#nav-main li:first-child {
-  -moz-border-top-left-radius: 4px;
-  border-top-left-radius: 4px;
-  -moz-border-bottom-left-radius: 4px;
-  border-bottom-left-radius: 4px;
-}
-#nav-main li:last-child {
-  -moz-border-top-right-radius: 4px;
-  border-top-right-radius: 4px;
-  -moz-border-bottom-right-radius: 4px;
-  border-bottom-right-radius: 4px;
-}
-#nav-main .quickref {
-  color: #444;
-}
-#nav-main .quickref .sep {
-  color: #999;
-}
-#search {
-  width: 120px;
-  margin-left: 0.5em;
-}
-#search.inactive {
-  text-align: center;
-  color: #444;
-}
-
-/* Footer */
-#site-info {
-  position: relative;
-  text-align: center;
-}
-#site-info, #site-info a:link, #site-info a:visited {
-  color: #aaa;
-}
-
-/* Content */
-#content {
-  clear: both;
-  padding: 0;
-  position: relative;
-  margin-top: 1.5em;
-  margin-bottom: 1.5em;
-  border-top: solid 1px #aaa;
-  border-bottom: solid 1px #aaa;
-}
-.left-column {
-  width: 49%;
-  float: left;
-}
-.right-column {
-  width: 49%;
-  float: right;
-}
-.end-columns {
-  clear: both;
-}
-#content h1 {
-  padding: 0;
-}
-#content h2 {
-  border-top: 2px solid #ddd;
-  padding: 8px 0;
-  margin: 1.5em 0 0;
-}
-#content .subtitle {
-  margin-top: 1em;
-  display: block;
-}
-.navtop a {
-  font-weight: normal; font-size: 7pt; 
-  float: right; color: #999;
-}
-
-/* Content and Code Highlighting */
-pre.ebnf, pre.grammar {
-  background: #FFFFE0;
-}
-span.ln {
-  font-size: 80%;
-  color: #777777;
-}
-span.comment {
-  color: #002090;
-}
-span.highlight {
-  background: #FF9900;
-  font-weight: bold;
-}
-span.highlight-comment {
-  background: #FF9900;
-  font-weight: bold;
-  color: #002090;
-}
-span.selection {
-  background: #FFFF00
-}
-span.selection-comment {
-  color: #002090;
-  background: #FFFF00
-}
-span.selection-highlight {
-  background: #FF9900;
-  font-weight: bold;
-}
-span.selection-highlight-comment {
-  background: #FF9900;
-  font-weight: bold;
-  color: #002090;
-}
-span.alert {
-  color: #D00000;
-}
-#nav table {
-  width: 100%;
-}
-.detail {
-  padding: 0.25em 1em;
-  background: #F4F4F4;
-}
-sup.new {
-  color: red;
-  font-size: 8px;
-  line-height: 0;
-}

doc/articles/c_go_cgo.html

@@ -0,0 +1,180 @@
+<!--{
+"Title": "C? Go? Cgo!",
+"Template": true
+}-->
+
+<p>
+Cgo lets Go packages call C code. Given a Go source file written with some
+special features, cgo outputs Go and C files that can be combined into a
+single Go package.
+</p>
+
+<p>
+To lead with an example, here's a Go package that provides two functions -
+<code>Random</code> and <code>Seed</code> - that wrap C's <code>random</code>
+and <code>srandom</code> functions.
+</p>
+
+{{code "/doc/progs/cgo1.go" `/package rand/` `/END/`}}
+
+<p>
+Let's look at what's happening here, starting with the import statement.
+</p>
+
+<p>
+The <code>rand</code> package imports <code>"C"</code>, but you'll find there's
+no such package in the standard Go library. That's because <code>C</code> is a
+"pseudo-package", a special name interpreted by cgo as a reference to C's
+name space.
+</p>
+
+<p>
+The <code>rand</code> package contains four references to the <code>C</code>
+package: the calls to <code>C.random</code> and <code>C.srandom</code>, the
+conversion <code>C.uint(i)</code>, and the <code>import</code> statement.
+</p>
+
+<p>
+The <code>Random</code> function calls the standard C library's <code>random</code>
+function and returns the result.  In C, <code>random</code> returns a value of the
+C type <code>long</code>, which cgo represents as the type <code>C.long</code>.
+It must be converted to a Go type before it can be used by Go code outside this
+package, using an ordinary Go type conversion:
+</p>
+
+{{code "/doc/progs/cgo1.go" `/func Random/` `/STOP/`}}
+
+<p>
+Here's an equivalent function that uses a temporary variable to illustrate
+the type conversion more explicitly:
+</p>
+
+{{code "/doc/progs/cgo2.go" `/func Random/` `/STOP/`}}
+
+<p>
+The <code>Seed</code> function does the reverse, in a way. It takes a
+regular Go <code>int</code>, converts it to the C <code>unsigned int</code>
+type, and passes it to the C function <code>srandom</code>.
+</p>
+
+{{code "/doc/progs/cgo1.go" `/func Seed/` `/END/`}}
+
+<p>
+Note that cgo knows the <code>unsigned int</code> type as <code>C.uint</code>;
+see the <a href="/cmd/cgo">cgo documentation</a> for a complete list of
+these numeric type names.
+</p>
+
+<p>
+The one detail of this example we haven't examined yet is the comment
+above the <code>import</code> statement.
+</p>
+
+{{code "/doc/progs/cgo1.go" `/\/\*/` `/STOP/`}}
+
+<p>
+Cgo recognizes this comment.  Any lines starting
+with <code>#cgo</code>
+followed
+by a space character are removed; these become directives for cgo.
+The remaining lines are used as a header when compiling the C parts of
+the package.  In this case those lines are just a
+single <code>#include</code>
+statement, but they can be almost any C code.  The <code>#cgo</code>
+directives are
+used to provide flags for the compiler and linker when building the C
+parts of the package.
+</p>
+
+<p>
+There is a limitation: if your program uses any <code>//export</code>
+directives, then the C code in the comment may only include declarations
+(<code>extern int f();</code>), not definitions (<code>int f() {
+return 1; }</code>).  You can use <code>//export</code> directives to
+make Go functions accessible to C code.
+</p>
+
+<p>
+The <code>#cgo</code> and <code>//export</code> directives are
+documented in
+the <a href="/cmd/cgo/">cgo documentation</a>.
+</p>
+
+<p>
+<b>Strings and things</b>
+</p>
+
+<p>
+Unlike Go, C doesn't have an explicit string type. Strings in C are
+represented by a zero-terminated array of chars.
+</p>
+
+<p>
+Conversion between Go and C strings is done with the
+<code>C.CString</code>, <code>C.GoString</code>, and
+<code>C.GoStringN</code> functions. These conversions make a copy of the
+string data.
+</p>
+
+<p>
+This next example implements a <code>Print</code> function that writes a
+string to standard output using C's <code>fputs</code> function from the
+<code>stdio</code> library:
+</p>
+
+{{code "/doc/progs/cgo3.go" `/package print/` `/END/`}}
+
+<p>
+Memory allocations made by C code are not known to Go's memory manager.
+When you create a C string with <code>C.CString</code> (or any C memory
+allocation) you must remember to free the memory when you're done with it
+by calling <code>C.free</code>.
+</p>
+
+<p>
+The call to <code>C.CString</code> returns a pointer to the start of the
+char array, so before the function exits we convert it to an
+<a href="/pkg/unsafe/#Pointer"><code>unsafe.Pointer</code></a> and release
+the memory allocation with <code>C.free</code>. A common idiom in cgo programs
+is to <a href="/doc/articles/defer_panic_recover.html"><code>defer</code></a>
+the free immediately after allocating (especially when the code that follows
+is more complex than a single function call), as in this rewrite of
+<code>Print</code>:
+</p>
+
+{{code "/doc/progs/cgo4.go" `/func Print/` `/END/`}}
+
+<p>
+<b>Building cgo packages</b>
+</p>
+
+<p>
+To build cgo packages, just use <a href="/cmd/go/#Compile_packages_and_dependencies">"
+<code>go build</code>"</a> or
+<a href="/cmd/go/#Compile_and_install_packages_and_dependencies">"<code>go install</code>
+"</a> as usual. The go tool recognizes the special <code>"C"</code> import and automatically
+uses cgo for those files.
+</p>
+
+<p>
+<b>More cgo resources</b>
+</p>
+
+<p>
+The <a href="/cmd/cgo/">cgo command</a> documentation has more detail about
+the C pseudo-package and the build process. The <a href="/misc/cgo/">cgo examples</a>
+in the Go tree demonstrate more advanced concepts.
+</p>
+
+<p>
+For a simple, idiomatic example of a cgo-based package, see Russ Cox's <a
+href="http://code.google.com/p/gosqlite/source/browse/sqlite/sqlite.go">gosqlite</a>.
+Also, the Go Project Dashboard lists <a
+href="https://godashboard.appspot.com/project?tag=cgo">several other
+cgo packages</a>.
+</p>
+
+<p>
+Finally, if you're curious as to how all this works internally, take a look
+at the introductory comment of the runtime package's <a href="/src/pkg/runtime/cgocall.c">cgocall.c</a>.
+</p>

doc/articles/concurrency_patterns.html

@@ -0,0 +1,79 @@
+<!--{
+"Title": "Go Concurrency Patterns: Timing out, moving on",
+"Template": true
+}-->
+
+<p>
+Concurrent programming has its own idioms. A good example is timeouts. Although
+Go's channels do not support them directly, they are easy to implement. Say we
+want to receive from the channel <code>ch</code>, but want to wait at most one
+second for the value to arrive. We would start by creating a signalling channel
+and launching a goroutine that sleeps before sending on the channel:
+</p>
+
+{{code "/doc/progs/timeout1.go" `/timeout :=/` `/STOP/`}}
+
+<p>
+We can then use a <code>select</code> statement to receive from either
+<code>ch</code> or <code>timeout</code>. If nothing arrives on <code>ch</code>
+after one second, the timeout case is selected and the attempt to read from
+<cde>ch</cde> is abandoned.
+</p>
+
+{{code "/doc/progs/timeout1.go" `/select {/` `/STOP/`}}
+
+<p>
+The <code>timeout</code> channel is buffered with space for 1 value, allowing
+the timeout goroutine to send to the channel and then exit. The goroutine
+doesn't know (or care) whether the value is received. This means the goroutine
+won't hang around forever if the <code>ch</code> receive happens before the
+timeout is reached. The <code>timeout</code> channel will eventually be
+deallocated by the garbage collector.
+</p>
+
+<p>
+(In this example we used <code>time.Sleep</code> to demonstrate the mechanics
+of goroutines and channels. In real programs you should use <code>
+<a href="/pkg/time/#After">time.After</a></code>, a function that returns
+a channel and sends on that channel after the specified duration.)
+</p>
+
+<p>
+Let's look at another variation of this pattern. In this example we have a
+program that reads from multiple replicated databases simultaneously. The
+program needs only one of the answers, and it should accept the answer that
+arrives first.
+</p>
+
+<p>
+The function <code>Query</code> takes a slice of database connections and a
+<code>query</code> string. It queries each of the databases in parallel and
+returns the first response it receives:
+</p>
+
+{{code "/doc/progs/timeout2.go" `/func Query/` `/STOP/`}}
+
+<p>
+In this example, the closure does a non-blocking send, which it achieves by
+using the send operation in <code>select</code> statement with a
+<code>default</code> case. If the send cannot go through immediately the
+default case will be selected. Making the send non-blocking guarantees that
+none of the goroutines launched in the loop will hang around. However, if the
+result arrives before the main function has made it to the receive, the send
+could fail since no one is ready.
+</p>
+
+<p>
+This problem is a textbook of example of what is known as a
+<a href="https://en.wikipedia.org/wiki/Race_condition">race condition</a>, but
+the fix is trivial. We just make sure to buffer the channel <code>ch</code> (by
+adding the buffer length as the second argument to <a href="/pkg/builtin/#make">make</a>),
+guaranteeing that the first send has a place to put the value. This ensures the
+send will always succeed, and the first value to arrive will be retrieved
+regardless of the order of execution.
+</p>
+
+<p>
+These two examples demonstrate the simplicity with which Go can express complex
+interactions between goroutines.
+</p>

doc/articles/defer_panic_recover.html

@@ -0,0 +1,197 @@
+<!--{
+	"Title": "Defer, Panic, and Recover",
+	"Template": true
+}-->
+
+<p>
+Go has the usual mechanisms for control flow: if, for, switch, goto.  It also
+has the go statement to run code in a separate goroutine.  Here I'd like to
+discuss some of the less common ones: defer, panic, and recover.
+</p>
+ 
+<p>
+A <b>defer statement</b> pushes a function call onto a list. The list of saved
+calls is executed after the surrounding function returns. Defer is commonly
+used to simplify functions that perform various clean-up actions.
+</p>
+ 
+<p>
+For example, let's look at a function that opens two files and copies the
+contents of one file to the other:
+</p>
+ 
+{{code "/doc/progs/defer.go" `/func CopyFile/` `/STOP/`}}
+
+<p>
+This works, but there is a bug. If the call to os.Create fails, the
+function will return without closing the source file. This can be easily
+remedied by putting a call to src.Close before the second return statement,
+but if the function were more complex the problem might not be so easily
+noticed and resolved. By introducing defer statements we can ensure that the
+files are always closed:
+</p>
+ 
+{{code "/doc/progs/defer2.go" `/func CopyFile/` `/STOP/`}}
+
+<p>
+Defer statements allow us to think about closing each file right after opening
+it, guaranteeing that, regardless of the number of return statements in the
+function, the files <i>will</i> be closed.
+</p>
+ 
+<p>
+The behavior of defer statements is straightforward and predictable. There are
+three simple rules:
+</p>
+ 
+<p>
+1. <i>A deferred function's arguments are evaluated when the defer statement is
+evaluated.</i> 
+</p>
+ 
+<p>
+In this example, the expression "i" is evaluated when the Println call is
+deferred. The deferred call will print "0" after the function returns.
+</p>
+ 
+{{code "/doc/progs/defer.go" `/func a/` `/STOP/`}}
+
+<p>
+2. <i>Deferred function calls are executed in Last In First Out order
+</i>after<i> the surrounding function returns.</i> 
+</p>
+ 
+<p>
+This function prints "3210":
+</p>
+
+{{code "/doc/progs/defer.go" `/func b/` `/STOP/`}}
+ 
+<p>
+3. <i>Deferred functions may read and assign to the returning function's named
+return values.</i> 
+</p>
+ 
+<p>
+In this example, a deferred function increments the return value i <i>after</i>
+the surrounding function returns. Thus, this function returns 2:
+</p>
+
+{{code "/doc/progs/defer.go" `/func c/` `/STOP/`}}
+ 
+<p>
+This is convenient for modifying the error return value of a function; we will
+see an example of this shortly.
+</p>
+ 
+<p>
+<b>Panic</b> is a built-in function that stops the ordinary flow of control and
+begins <i>panicking</i>. When the function F calls panic, execution of F stops,
+any deferred functions in F are executed normally, and then F returns to its
+caller. To the caller, F then behaves like a call to panic. The process
+continues up the stack until all functions in the current goroutine have
+returned, at which point the program crashes. Panics can be initiated by
+invoking panic directly. They can also be caused by runtime errors, such as
+out-of-bounds array accesses.
+</p>
+ 
+<p>
+<b>Recover</b> is a built-in function that regains control of a panicking
+goroutine. Recover is only useful inside deferred functions. During normal
+execution, a call to recover will return nil and have no other effect. If the
+current goroutine is panicking, a call to recover will capture the value given
+to panic and resume normal execution.
+</p>
+ 
+<p>
+Here's an example program that demonstrates the mechanics of panic and defer:
+</p>
+
+{{code "/doc/progs/defer2.go" `/package main/` `/STOP/`}}
+ 
+<p>
+The function g takes the int i, and panics if i is greater than 3, or else it
+calls itself with the argument i+1. The function f defers a function that calls
+recover and prints the recovered value (if it is non-nil). Try to picture what
+the output of this program might be before reading on.
+</p>
+ 
+<p>
+The program will output:
+</p>
+ 
+<pre>Calling g.
+Printing in g 0
+Printing in g 1
+Printing in g 2
+Printing in g 3
+Panicking!
+Defer in g 3
+Defer in g 2
+Defer in g 1
+Defer in g 0
+Recovered in f 4
+Returned normally from f.</pre> 
+
+<p>
+If we remove the deferred function from f the panic is not recovered and
+reaches the top of the goroutine's call stack, terminating the program. This
+modified program will output:
+</p>
+ 
+<pre>Calling g.
+Printing in g 0
+Printing in g 1
+Printing in g 2
+Printing in g 3
+Panicking!
+Defer in g 3
+Defer in g 2
+Defer in g 1
+Defer in g 0
+panic: 4
+ 
+panic PC=0x2a9cd8
+[stack trace omitted]</pre> 
+
+<p>
+For a real-world example of <b>panic</b> and <b>recover</b>, see the
+<a href="/pkg/encoding/json/">json package</a> from the Go standard library.
+It decodes JSON-encoded data with a set of recursive functions.
+When malformed JSON is encountered, the parser calls panic to unwind the
+stack to the top-level function call, which recovers from the panic and returns
+an appropriate error value (see the 'error' and 'unmarshal' methods of
+the decodeState type in
+<a href="/src/pkg/encoding/json/decode.go">decode.go</a>).
+</p>
+
+<p>
+The convention in the Go libraries is that even when a package uses panic
+internally, its external API still presents explicit error return values.
+</p>
+ 
+<p>
+Other uses of <b>defer</b> (beyond the file.Close example given earlier)
+include releasing a mutex:
+</p>
+
+<pre>mu.Lock()
+defer mu.Unlock()</pre> 
+
+<p>
+printing a footer:
+</p>
+ 
+<pre>printHeader()
+defer printFooter()</pre> 
+
+<p>
+and more.
+</p>
+ 
+<p>
+In summary, the defer statement (with or without panic and recover) provides an
+unusual and powerful mechanism for control flow.  It can be used to model a
+number of features implemented by special-purpose structures in other
+programming languages. Try it out.
+</p>

doc/articles/error_handling.html

@@ -0,0 +1,316 @@
+<!--{
+	"Title": "Error Handling and Go",
+	"Template": true
+}-->
+
+<p>
+If you have written any Go code you have probably encountered the built-in
+<code>error</code> type. Go code uses <code>error</code> values to
+indicate an abnormal state. For example, the <code>os.Open</code> function
+returns a non-nil <code>error</code> value when it fails to open a file.
+</p>
+
+{{code "/doc/progs/error.go" `/func Open/`}}
+
+<p>
+The following code uses <code>os.Open</code> to open a file. If an error
+occurs it calls <code>log.Fatal</code> to print the error message and stop.
+</p>
+
+{{code "/doc/progs/error.go" `/func openFile/` `/STOP/`}}
+
+<p>
+You can get a lot done in Go knowing just this about the <code>error</code>
+type, but in this article we'll take a closer look at <code>error</code> and
+discuss some good practices for error handling in Go.
+</p>
+
+<p>
+<b>The error type</b>
+</p>
+
+<p>
+The <code>error</code> type is an interface type. An <code>error</code>
+variable represents any value that can describe itself as a string. Here is the
+interface's declaration:
+</p>
+
+<pre>type error interface {
+    Error() string
+}</pre>
+
+<p>
+The <code>error</code> type, as with all built in types, is
+<a href="/doc/go_spec.html#Predeclared_identifiers">predeclared</a> in the
+<a href="/doc/go_spec.html#Blocks">universe block</a>.
+</p>
+
+<p>
+The most commonly-used <code>error</code> implementation is the
+<a href="/pkg/errors/">errors</a> package's unexported <code>errorString</code> type.
+</p>
+
+{{code "/doc/progs/error.go" `/errorString/` `/STOP/`}}
+
+<p>
+You can construct one of these values with the <code>errors.New</code>
+function. It takes a string that it converts to an <code>errors.errorString</code>
+and returns as an <code>error</code> value.
+</p>
+
+{{code "/doc/progs/error.go" `/New/` `/STOP/`}}
+
+<p>
+Here's how you might use <code>errors.New</code>:
+</p>
+
+{{code "/doc/progs/error.go" `/func Sqrt/` `/STOP/`}}
+
+<p>
+A caller passing a negative argument to <code>Sqrt</code> receives a non-nil
+<code>error</code> value (whose concrete representation is an
+<code>errors.errorString</code> value). The caller can access the error string
+("math: square root of...") by calling the <code>error</code>'s
+<code>Error</code> method, or by just printing it:
+</p>
+
+{{code "/doc/progs/error.go" `/func printErr/` `/STOP/`}}
+
+<p>
+The <a href="/pkg/fmt/">fmt</a> package formats an <code>error</code> value
+by calling its <code>Error() string</code> method.
+</p>
+
+<p>
+It is the error implementation's responsibility to summarize the context.
+The error returned by <code>os.Open</code> formats as "open /etc/passwd:
+permission denied," not just "permission denied."  The error returned by our
+<code>Sqrt</code> is missing information about the invalid argument.
+</p>
+
+<p>
+To add that information, a useful function is the <code>fmt</code> package's
+<code>Errorf</code>. It formats a string according to <code>Printf</code>'s
+rules and returns it as an <code>error</code> created by
+<code>errors.New</code>.
+</p>
+
+{{code "/doc/progs/error.go" `/fmtError/` `/STOP/`}}
+
+<p>
+In many cases <code>fmt.Errorf</code> is good enough, but since
+<code>error</code> is an interface, you can use arbitrary data structures as
+error values, to allow callers to inspect the details of the error.
+</p>
+
+<p>
+For instance, our hypothetical callers might want to recover the invalid
+argument passed to <code>Sqrt</code>. We can enable that by defining a new
+error implementation instead of using <code>errors.errorString</code>:
+</p>
+
+{{code "/doc/progs/error.go" `/type NegativeSqrtError/` `/STOP/`}}
+
+<p>
+A sophisticated caller can then use a
+<a href="/doc/go_spec.html#Type_assertions">type assertion</a> to check for a
+<code>NegativeSqrtError</code> and handle it specially, while callers that just
+pass the error to <code>fmt.Println</code> or <code>log.Fatal</code> will see
+no change in behavior.
+</p>
+
+<p>
+As another example, the <a href="/pkg/encoding/json/">json</a> package specifies a
+<code>SyntaxError</code> type that the <code>json.Decode</code> function
+returns when it encounters a syntax error parsing a JSON blob.
+</p>
+
+{{code "/doc/progs/error.go" `/type SyntaxError/` `/STOP/`}}
+
+<p>
+The <code>Offset</code> field isn't even shown in the default formatting of the
+error, but callers can use it to add file and line information to their error
+messages:
+</p>
+
+{{code "/doc/progs/error.go" `/func decodeError/` `/STOP/`}}
+
+<p>
+(This is a slightly simplified version of some
+<a href="http://camlistore.org/code/?p=camlistore.git;a=blob;f=lib/go/camli/jsonconfig/eval.go#l68">actual code</a>
+from the <a href="http://camlistore.org">Camlistore</a> project.)
+</p>
+
+<p>
+The <code>error</code> interface requires only a <code>Error</code> method;
+specific error implementations might have additional methods. For instance, the
+<a href="/pkg/net/">net</a> package returns errors of type
+<code>error</code>, following the usual convention, but some of the error
+implementations have additional methods defined by the <code>net.Error</code>
+interface:
+</p>
+
+<pre>package net
+
+type Error interface {
+    error
+    Timeout() bool   // Is the error a timeout?
+    Temporary() bool // Is the error temporary?
+}</pre>
+
+<p>
+Client code can test for a <code>net.Error</code> with a type assertion and
+then distinguish transient network errors from permanent ones. For instance, a
+web crawler might sleep and retry when it encounters a temporary error and give
+up otherwise.
+</p>
+
+{{code "/doc/progs/error.go" `/func netError/` `/STOP/`}}
+
+<p>
+<b>Simplifying repetitive error handling</b>
+</p>
+
+<p>
+In Go, error handling is important. The language's design and conventions
+encourage you to explicitly check for errors where they occur (as distinct from
+the convention in other languages of throwing exceptions and sometimes catching
+them). In some cases this makes Go code verbose, but fortunately there are some
+techniques you can use to minimize repetitive error handling.
+</p>
+
+<p>
+Consider an <a href="http://code.google.com/appengine/docs/go/">App Engine</a>
+application with an HTTP handler that retrieves a record from the datastore and
+formats it with a template.
+</p>
+
+{{code "/doc/progs/error2.go" `/func init/` `/STOP/`}}
+
+<p>
+This function handles errors returned by the <code>datastore.Get</code>
+function and <code>viewTemplate</code>'s <code>Execute</code> method. In both
+cases, it presents a simple error message to the user with the HTTP status code
+500 ("Internal Server Error"). This looks like a manageable amount of code, but
+add some more HTTP handlers and you quickly end up with many copies of
+identical error handling code.
+</p>
+
+<p>
+To reduce the repetition we can define our own HTTP <code>appHandler</code>
+type that includes an <code>error</code> return value:
+</p>
+
+{{code "/doc/progs/error3.go" `/type appHandler/`}}
+
+<p>
+Then we can change our <code>viewRecord</code> function to return errors:
+</p>
+
+{{code "/doc/progs/error3.go" `/func viewRecord/` `/STOP/`}}
+
+<p>
+This is simpler than the original version, but the <a
+href="/pkg/net/http/">http</a> package doesn't understand functions that return
+<code>error</code>.
+To fix this we can implement the <code>http.Handler</code> interface's
+<code>ServeHTTP</code> method on <code>appHandler</code>:
+</p>
+
+{{code "/doc/progs/error3.go" `/ServeHTTP/` `/STOP/`}}
+
+<p>
+The <code>ServeHTTP</code> method calls the <code>appHandler</code> function
+and displays the returned error (if any) to the user.  Notice that the method's
+receiver, <code>fn</code>, is a function. (Go can do that!) The method invokes
+the function by calling the receiver in the expression <code>fn(w, r)</code>.
+</p>
+
+<p>
+Now when registering <code>viewRecord</code> with the http package we use the
+<code>Handle</code> function (instead of <code>HandleFunc</code>) as
+<code>appHandler</code> is an <code>http.Handler</code> (not an
+<code>http.HandlerFunc</code>). 
+</p>
+
+{{code "/doc/progs/error3.go" `/func init/` `/STOP/`}}
+
+<p>
+With this basic error handling infrastructure in place, we can make it more
+user friendly. Rather than just displaying the error string, it would be better
+to give the user a simple error message with an appropriate HTTP status code,
+while logging the full error to the App Engine developer console for debugging
+purposes.
+</p>
+
+<p>
+To do this we create an <code>appError</code> struct containing an
+<code>error</code> and some other fields:
+</p>
+
+{{code "/doc/progs/error4.go" `/type appError/` `/STOP/`}}
+
+<p>
+Next we modify the appHandler type to return <code>*appError</code> values:
+</p>
+
+{{code "/doc/progs/error4.go" `/type appHandler/`}}
+
+<p>
+(It's usually a mistake to pass back the concrete type of an error rather than
+<code>error</code>,
+for reasons discussed in <a href="/doc/go_faq.html#nil_error">the Go FAQ</a>,
+but it's the right thing to do here because <code>ServeHTTP</code> is the only
+place that sees the value and uses its contents.)
+</p>
+
+<p>
+And make <code>appHandler</code>'s <code>ServeHTTP</code> method display the
+<code>appError</code>'s <code>Message</code> to the user with the correct HTTP
+status <code>Code</code> and log the full <code>Error</code> to the developer
+console:
+</p>
+
+{{code "/doc/progs/error4.go" `/ServeHTTP/` `/STOP/`}}
+
+<p>
+Finally, we update <code>viewRecord</code> to the new function signature and
+have it return more context when it encounters an error: 
+</p>
+
+{{code "/doc/progs/error4.go" `/func viewRecord/` `/STOP/`}}
+
+<p>
+This version of <code>viewRecord</code> is the same length as the original, but
+now each of those lines has specific meaning and we are providing a friendlier
+user experience.
+</p>
+
+<p>
+It doesn't end there; we can further improve the error handling in our
+application. Some ideas:
+</p>
+
+<ul>
+<li>give the error handler a pretty HTML template,
+<li>make debugging easier by writing the stack trace to the HTTP response when
+the user is an administrator,
+<li>write a constructor function for <code>appError</code> that stores the
+stack trace for easier debugging, 
+<li>recover from panics inside the <code>appHandler</code>, logging the error
+to the console as "Critical," while telling the user "a serious error
+has occurred." This is a nice touch to avoid exposing the user to inscrutable
+error messages caused by programming errors.
+See the <a href="defer_panic_recover.html">Defer, Panic, and Recover</a>
+article for more details.
+</ul>
+
+<p>
+<b>Conclusion</b>
+</p>
+
+<p>
+Proper error handling is an essential requirement of good software. By
+employing the techniques described in this post you should be able to write
+more reliable and succinct Go code.
+</p>

doc/articles/go_command.html

@@ -0,0 +1,265 @@
+<!--{
+	"title": "About the go command"
+}-->
+
+<p>The Go distribution includes a command, named
+"<code><a href="/cmd/go/">go</a></code>", that
+automates the downloading, building, installation, and testing of Go packages
+and commands.  This document talks about why we wrote a new command, what it
+is, what it's not, and how to use it.</p>
+
+<h2>Motivation</h2>
+
+<p>You might have seen early Go talks in which Rob Pike jokes that the idea
+for Go arose while waiting for a large Google server to compile.  That
+really was the motivation for Go: to build a language that worked well
+for building the large software that Google writes and runs. It was
+clear from the start that such a language must provide a way to
+express dependencies between code libraries clearly, hence the package
+grouping and the explicit import blocks.  It was also clear from the
+start that you might want arbitrary syntax for describing the code
+being imported; this is why import paths are string literals.</p>
+
+<p>An explicit goal for Go from the beginning was to be able to build Go
+code using only the information found in the source itself, not
+needing to write a makefile or one of the many modern replacements for
+makefiles.  If Go needed a configuration file to explain how to build
+your program, then Go would have failed.</p>
+
+<p>At first, there was no Go compiler, and the initial development
+focused on building one and then building libraries for it. For
+expedience, we postponed the automation of building Go code by using
+make and writing makefiles.  When compiling a single package involved
+multiple invocations of the Go compiler, we even used a program to
+write the makefiles for us.  You can find it if you dig through the
+repository history.</p>
+
+<p>The purpose of the new go command is our return to this ideal, that Go
+programs should compile without configuration or additional effort on
+the part of the developer beyond writing the necessary import
+statements.</p>
+
+<h2>Configuration versus convention</h2>
+
+<p>The way to achieve the simplicity of a configuration-free system is to
+establish conventions. The system works only to the extent that those conventions
+are followed. When we first launched Go, many people published packages that
+had to be installed in certain places, under certain names, using certain build
+tools, in order to be used. That's understandable: that's the way it works in
+most other languages. Over the last few years we consistently reminded people
+about the <code>goinstall</code> command
+(now replaced by <a href="/cmd/go/#Download_and_install_packages_and_dependencies"><code>go get</code></a>)
+and its conventions: first, that the import path is derived in a known way from
+the URL of the source code; second, that that the place to store the sources in
+the local file system is derived in a known way from the import path; third,
+that each directory in a source tree corresponds to a single package; and
+fourth, that the package is built using only information in the source code.
+Today, the vast majority of packages follow these conventions.
+The Go ecosystem is simpler and more powerful as a result.</p>
+
+<p>We received many requests to allow a makefile in a package directory to
+provide just a little extra configuration beyond what's in the source code.
+But that would have introduced new rules. Because we did not accede to such
+requests, we were able to write the go command and eliminate our use of make
+or any other build system.</p>
+
+<p>It is important to understand that the go command is not a general
+build tool. It cannot be configured and it does not attempt to build
+anything but Go packages.  These are important simplifying
+assumptions: they simplify not only the implementation but also, more
+important, the use of the tool itself.</p>
+
+<h2>Go's conventions</h2>
+
+<p>The <code>go</code> command requires that code adheres to a few key,
+well-established conventions.</p>
+
+<p>First, the import path is derived in an known way from the URL of the
+source code.  For Bitbucket, GitHub, Google Code, and Launchpad, the
+root directory of the repository is identified by the repository's
+main URL, without the <code>http://</code> prefix.  Subdirectories are named by
+adding to that path.  For example, the supplemental networking
+libraries for Go are obtained by running</p>
+
+<pre>
+hg clone http://code.google.com/p/go.net
+</pre>
+
+<p>and thus the import path for the root directory of that repository is
+"<code>code.google.com/p/go.net</code>".  The websocket package is stored in a
+subdirectory, so its import path is
+"<code>code.google.com/p/go.net/websocket</code>".</p>
+
+<p>These paths are on the long side, but in exchange we get an
+automatically managed name space for import paths and the ability for
+a tool like the go command to look at an unfamiliar import path and
+deduce where to obtain the source code.</p>
+
+<p>Second, the place to store sources in the local file system is derived
+in a known way from the import path.  Specifically, the first choice
+is <code>$GOPATH/src/&lt;import-path&gt;</code>.  If <code>$GOPATH</code> is
+unset, the go command will fall back to storing source code alongside the
+standard Go packages, in <code>$GOROOT/src/pkg/&lt;import-path&gt;</code>.
+If <code>$GOPATH</code> is set to a list of paths, the go command tries
+<code>&lt;dir&gt;/src/&lt;import-path&gt;</code> for each of the directories in
+that list.</p>
+
+<p>Each of those trees contains, by convention, a top-level directory named
+"<code>bin</code>", for holding compiled executables, and a top-level directory
+named "<code>pkg</code>", for holding compiled packages that can be imported,
+and the "<code>src</code>" directory, for holding package source files.
+Imposing this structure lets us keep each of these directory trees
+self-contained: the compiled form and the sources are always near each
+other.</p>
+
+<p>These naming conventions also let us work in the reverse direction,
+from a directory name to its import path. This mapping is important
+for many of the go command's subcommands, as we'll see below.</p>
+
+<p>Third, each directory in a source tree corresponds to a single
+package. By restricting a directory to a single package, we don't have
+to create hybrid import paths that specify first the directory and
+then the package within that directory.  Also, most file management
+tools and UIs work on  directories as fundamental units.  Tying the
+fundamental Go unit&mdash;the package&mdash;to file system structure means
+that file system tools become Go package tools.  Copying, moving, or
+deleting a package corresponds to copying, moving, or deleting a
+directory.</p>
+
+<p>Fourth, each package is built using only the information present in
+the source files.  This makes it much more likely that the tool will
+be able to adapt to changing build environments and conditions. For
+example, if we allowed extra configuration such as compiler flags or
+command line recipes, then that configuration would need to be updated
+each time the build tools changed; it would also be inherently tied
+to the use of a specific tool chain.</p>
+
+<h2>Getting started with the go command</h2>
+
+<p>Finally, a quick tour of how to use the go command, to supplement
+the information in <a href="/doc/code.html">How to Write Go Code</a>,
+which you might want to read first.  Assuming you want
+to keep your source code separate from the Go distribution source
+tree, the first step is to set <code>$GOPATH</code>, the one piece of global
+configuration that the go command needs.  The <code>$GOPATH</code> can be a
+list of directories, but by far the most common usage should be to set it to a
+single directory.  In particular, you do not need a separate entry in
+<code>$GOPATH</code> for each of your projects.  One <code>$GOPATH</code> can
+support many projects.</p>
+
+<p>Here’s an example.  Let’s say we decide to keep our Go code in the directory
+<code>$HOME/mygo</code>.  We need to create that directory and set
+<code>$GOPATH</code> accordingly.</p>
+
+<pre>
+$ mkdir $HOME/mygo
+$ export GOPATH=$HOME/mygo
+$
+</pre>
+
+<p>Into this directory, we now add some source code.  Suppose we want to use
+the indexing library from the codesearch project along with a left-leaning
+red-black tree.  We can install both with the "<code>go get</code>"
+subcommand:</p>
+
+<pre>
+$ go get code.google.com/p/codesearch/index
+$ go get github.com/petar/GoLLRB/llrb
+$
+</pre>
+
+<p>Both of these projects are now downloaded and installed into our
+<code>$GOPATH</code> directory. The one tree now contains the two directories
+<code>src/code.google.com/p/codesearch/index/</code> and
+<code>src/github.com/petar/GoLLRB/llrb/</code>, along with the compiled
+packages (in <code>pkg/</code>) for those libraries and their dependencies.</p>
+
+<p>Because we used version control systems (Mercurial and Git) to check
+out the sources, the source tree also contains the other files in the
+corresponding repositories, such as related packages. The "<code>go list</code>"
+subcommand lists the import paths corresponding to its arguments, and
+the pattern "<code>./...</code>" means start in the current directory
+("<code>./</code>") and find all packages below that directory
+("<code>...</code>"):</p>
+
+<pre>
+$ go list ./...
+code.google.com/p/codesearch/cmd/cgrep
+code.google.com/p/codesearch/cmd/cindex
+code.google.com/p/codesearch/cmd/csearch
+code.google.com/p/codesearch/index
+code.google.com/p/codesearch/regexp
+code.google.com/p/codesearch/sparse
+github.com/petar/GoLLRB/example
+github.com/petar/GoLLRB/llrb
+$
+</pre>
+
+<p>We can also test those packages:</p>
+
+<pre>
+$ go test ./...
+?       code.google.com/p/codesearch/cmd/cgrep   [no test files]
+?       code.google.com/p/codesearch/cmd/cindex  [no test files]
+?       code.google.com/p/codesearch/cmd/csearch [no test files]
+ok      code.google.com/p/codesearch/index       0.239s
+ok      code.google.com/p/codesearch/regexp      0.021s
+?       code.google.com/p/codesearch/sparse      [no test files]
+?       github.com/petar/GoLLRB/example          [no test files]
+ok      github.com/petar/GoLLRB/llrb             0.231s
+$
+</pre>
+
+<p>If a go subcommand is invoked with no paths listed, it operates on the
+current directory:</p>
+
+<pre>
+$ cd $GOPATH/src/code.google.com/p/codesearch/regexp
+$ go list
+code.google.com/p/codesearch/regexp
+$ go test -v
+=== RUN TestNstateEnc
+--- PASS: TestNstateEnc (0.00 seconds)
+=== RUN TestMatch
+--- PASS: TestMatch (0.01 seconds)
+=== RUN TestGrep
+--- PASS: TestGrep (0.00 seconds)
+PASS
+ok      code.google.com/p/codesearch/regexp     0.021s
+$ go install
+$
+</pre>
+
+<p>That "<code>go install</code>" subcommand installs the latest copy of the
+package into the pkg directory. Because the go command can analyze the
+dependency graph, "<code>go install</code>" also installs any packages that
+this package imports but that are out of date, recursively.</p>
+
+<p>Notice that "<code>go install</code>" was able to determine the name of the
+import path for the package in the current directory, because of the convention
+for directory naming.  It would be a little more convenient if we could pick
+the name of the directory where we kept source code, and we probably wouldn't
+pick such a long name, but that ability would require additional configuration
+and complexity in the tool. Typing an extra directory name or two is a small
+price to pay for the increased simplicity and power.</p>
+
+<p>As the example shows, it’s fine to work with packages from many different
+projects at once within a single <code>$GOPATH</code> root directory.</p>
+
+<h2>Limitations</h2>
+
+<p>As mentioned above, the go command is not a general-purpose build
+tool. In particular, it does not have any facility for generating Go
+source files during a build.  Instead, if you want to use a tool like
+yacc or the protocol buffer compiler, you will need to write a
+makefile (or a configuration file for the build tool of your choice)
+to generate the Go files and then check those generated source files
+into your repository. This is more work for you, the package author,
+but it is significantly less work for your users, who can use
+"<code>go get</code>" without needing to obtain and build
+any additional tools.</p>
+
+<h2>More information</h2>
+
+<p>For more information, read <a href="/doc/code.html">How to Write Go Code</a>
+and see the <a href="/cmd/go/">go command documentation</a>.</p>

doc/articles/gobs_of_data.html

@@ -0,0 +1,315 @@
+<!--{
+"Title": "Gobs of data",
+"Template": true
+}-->
+
+<p>
+To transmit a data structure across a network or to store it in a file, it must
+be encoded and then decoded again. There are many encodings available, of
+course: <a href="http://www.json.org/">JSON</a>,
+<a href="http://www.w3.org/XML/">XML</a>, Google's
+<a href="http://code.google.com/p/protobuf">protocol buffers</a>, and more.
+And now there's another, provided by Go's <a href="/pkg/encoding/gob/">gob</a>
+package.
+</p>
+
+<p>
+Why define a new encoding? It's a lot of work and redundant at that. Why not
+just use one of the existing formats? Well, for one thing, we do! Go has
+<a href="/pkg/">packages</a> supporting all the encodings just mentioned (the
+<a href="http://code.google.com/p/goprotobuf">protocol buffer package</a> is in
+a separate repository but it's one of the most frequently downloaded). And for
+many purposes, including communicating with tools and systems written in other
+languages, they're the right choice.
+</p>
+
+<p>
+But for a Go-specific environment, such as communicating between two servers
+written in Go, there's an opportunity to build something much easier to use and
+possibly more efficient.
+</p>
+
+<p>
+Gobs work with the language in a way that an externally-defined,
+language-independent encoding cannot. At the same time, there are lessons to be
+learned from the existing systems.
+</p>
+
+<p>
+<b>Goals</b>
+</p>
+
+<p>
+The gob package was designed with a number of goals in mind.
+</p>
+
+<p>
+First, and most obvious, it had to be very easy to use. First, because Go has
+reflection, there is no need for a separate interface definition language or
+"protocol compiler". The data structure itself is all the package should need
+to figure out how to encode and decode it. On the other hand, this approach
+means that gobs will never work as well with other languages, but that's OK:
+gobs are unashamedly Go-centric.
+</p>
+
+<p>
+Efficiency is also important. Textual representations, exemplified by XML and
+JSON, are too slow to put at the center of an efficient communications network.
+A binary encoding is necessary.
+</p>
+
+<p>
+Gob streams must be self-describing. Each gob stream, read from the beginning,
+contains sufficient information that the entire stream can be parsed by an
+agent that knows nothing a priori about its contents. This property means that
+you will always be able to decode a gob stream stored in a file, even long
+after you've forgotten what data it represents.
+</p>
+
+<p>
+There were also some things to learn from our experiences with Google protocol
+buffers.
+</p>
+
+<p>
+<b>Protocol buffer misfeatures</b>
+</p>
+
+<p>
+Protocol buffers had a major effect on the design of gobs, but have three
+features that were deliberately avoided. (Leaving aside the property that
+protocol buffers aren't self-describing: if you don't know the data definition
+used to encode a protocol buffer, you might not be able to parse it.)
+</p>
+
+<p>
+First, protocol buffers only work on the data type we call a struct in Go. You
+can't encode an integer or array at the top level, only a struct with fields
+inside it. That seems a pointless restriction, at least in Go. If all you want
+to send is an array of integers, why should you have to put it into a
+struct first?
+</p>
+
+<p>
+Next, a protocol buffer definition may specify that fields <code>T.x</code> and
+<code>T.y</code> are required to be present whenever a value of type
+<code>T</code> is encoded or decoded.  Although such required fields may seem
+like a good idea, they are costly to implement because the codec must maintain a
+separate data structure while encoding and decoding, to be able to report when
+required fields are missing.  They're also a maintenance problem. Over time, one
+may want to modify the data definition to remove a required field, but that may
+cause existing clients of the data to crash. It's better not to have them in the
+encoding at all.  (Protocol buffers also have optional fields. But if we don't
+have required fields, all fields are optional and that's that. There will be
+more to say about optional fields a little later.)
+</p>
+
+<p>
+The third protocol buffer misfeature is default values. If a protocol buffer
+omits the value for a "defaulted" field, then the decoded structure behaves as
+if the field were set to that value. This idea works nicely when you have
+getter and setter methods to control access to the field, but is harder to
+handle cleanly when the container is just a plain idiomatic struct. Required
+fields are also tricky to implement: where does one define the default values,
+what types do they have (is text UTF-8? uninterpreted bytes? how many bits in a
+float?) and despite the apparent simplicity, there were a number of
+complications in their design and implementation for protocol buffers. We
+decided to leave them out of gobs and fall back to Go's trivial but effective
+defaulting rule: unless you set something otherwise, it has the "zero value"
+for that type - and it doesn't need to be transmitted.
+</p>
+
+<p>
+So gobs end up looking like a sort of generalized, simplified protocol buffer.
+How do they work?
+</p>
+
+<p>
+<b>Values</b>
+</p>
+
+<p>
+The encoded gob data isn't about <code>int8</code>s and <code>uint16</code>s.
+Instead, somewhat analogous to constants in Go, its integer values are abstract,
+sizeless numbers, either signed or unsigned. When you encode an
+<code>int8</code>, its value is transmitted as an unsized, variable-length
+integer. When you encode an <code>int64</code>, its value is also transmitted as
+an unsized, variable-length integer. (Signed and unsigned are treated
+distinctly, but the same unsized-ness applies to unsigned values too.) If both
+have the value 7, the bits sent on the wire will be identical. When the receiver
+decodes that value, it puts it into the receiver's variable, which may be of
+arbitrary integer type. Thus an encoder may send a 7 that came from an
+<code>int8</code>, but the receiver may store it in an <code>int64</code>. This
+is fine: the value is an integer and as a long as it fits, everything works. (If
+it doesn't fit, an error results.) This decoupling from the size of the variable
+gives some flexibility to the encoding: we can expand the type of the integer
+variable as the software evolves, but still be able to decode old data.
+</p>
+
+<p>
+This flexibility also applies to pointers. Before transmission, all pointers are
+flattened. Values of type <code>int8</code>, <code>*int8</code>,
+<code>**int8</code>, <code>****int8</code>, etc. are all transmitted as an
+integer value, which may then be stored in <code>int</code> of any size, or
+<code>*int</code>, or <code>******int</code>, etc. Again, this allows for
+flexibility.
+</p>
+
+<p>
+Flexibility also happens because, when decoding a struct, only those fields
+that are sent by the encoder are stored in the destination. Given the value
+</p>
+
+{{code "/doc/progs/gobs1.go" `/type T/` `/STOP/`}}
+
+<p>
+the encoding of <code>t</code> sends only the 7 and 8. Because it's zero, the
+value of <code>Y</code> isn't even sent; there's no need to send a zero value.
+</p>
+
+<p>
+The receiver could instead decode the value into this structure:
+</p>
+
+{{code "/doc/progs/gobs1.go" `/type U/` `/STOP/`}}
+
+<p>
+and acquire a value of <code>u</code> with only <code>X</code> set (to the
+address of an <code>int8</code> variable set to 7); the <code>Z</code> field is
+ignored - where would you put it? When decoding structs, fields are matched by
+name and compatible type, and only fields that exist in both are affected. This
+simple approach finesses the "optional field" problem: as the type
+<code>T</code> evolves by adding fields, out of date receivers will still
+function with the part of the type they recognize. Thus gobs provide the
+important result of optional fields - extensibility - without any additional
+mechanism or notation.
+</p>
+
+<p>
+From integers we can build all the other types: bytes, strings, arrays, slices,
+maps, even floats. Floating-point values are represented by their IEEE 754
+floating-point bit pattern, stored as an integer, which works fine as long as
+you know their type, which we always do. By the way, that integer is sent in
+byte-reversed order because common values of floating-point numbers, such as
+small integers, have a lot of zeros at the low end that we can avoid
+transmitting.
+</p>
+
+<p>
+One nice feature of gobs that Go makes possible is that they allow you to define
+your own encoding by having your type satisfy the
+<a href="/pkg/encoding/gob/#GobEncoder">GobEncoder</a> and
+<a href="/pkg/encoding/gob/#GobDecoder">GobDecoder</a> interfaces, in a manner
+analogous to the <a href="/pkg/encoding/json/">JSON</a> package's
+<a href="/pkg/encoding/json/#Marshaler">Marshaler</a> and
+<a href="/pkg/encoding/json/#Unmarshaler">Unmarshaler</a> and also to the
+<a href="/pkg/fmt/#Stringer">Stringer</a> interface from
+<a href="/pkg/fmt/">package fmt</a>. This facility makes it possible to
+represent special features, enforce constraints, or hide secrets when you
+transmit data. See the <a href="/pkg/encoding/gob/">documentation</a> for
+details.
+</p>
+
+<p>
+<b>Types on the wire</b>
+</p>
+
+<p>
+The first time you send a given type, the gob package includes in the data
+stream a description of that type. In fact, what happens is that the encoder is
+used to encode, in the standard gob encoding format, an internal struct that
+describes the type and gives it a unique number. (Basic types, plus the layout
+of the type description structure, are predefined by the software for
+bootstrapping.) After the type is described, it can be referenced by its type
+number.
+</p>
+
+<p>
+Thus when we send our first type <code>T</code>, the gob encoder sends a
+description of <code>T</code> and tags it with a type number, say 127. All
+values, including the first, are then prefixed by that number, so a stream of
+<code>T</code> values looks like:
+</p>
+
+<pre>
+("define type id" 127, definition of type T)(127, T value)(127, T value), ...
+</pre>
+
+<p>
+These type numbers make it possible to describe recursive types and send values
+of those types. Thus gobs can encode types such as trees:
+</p>
+
+{{code "/doc/progs/gobs1.go" `/type Node/` `/STOP/`}}
+
+<p>
+(It's an exercise for the reader to discover how the zero-defaulting rule makes
+this work, even though gobs don't represent pointers.)
+</p>
+
+<p>
+With the type information, a gob stream is fully self-describing except for the
+set of bootstrap types, which is a well-defined starting point.
+</p>
+
+<p>
+<b>Compiling a machine</b>
+</p>
+
+<p>
+The first time you encode a value of a given type, the gob package builds a
+little interpreted machine specific to that data type. It uses reflection on
+the type to construct that machine, but once the machine is built it does not
+depend on reflection. The machine uses package unsafe and some trickery to
+convert the data into the encoded bytes at high speed. It could use reflection
+and avoid unsafe, but would be significantly slower. (A similar high-speed
+approach is taken by the protocol buffer support for Go, whose design was
+influenced by the implementation of gobs.) Subsequent values of the same type
+use the already-compiled machine, so they can be encoded right away.
+</p>
+
+<p>
+Decoding is similar but harder. When you decode a value, the gob package holds
+a byte slice representing a value of a given encoder-defined type to decode,
+plus a Go value into which to decode it. The gob package builds a machine for
+that pair: the gob type sent on the wire crossed with the Go type provided for
+decoding. Once that decoding machine is built, though, it's again a
+reflectionless engine that uses unsafe methods to get maximum speed.
+</p>
+
+<p>
+<b>Use</b>
+</p>
+
+<p>
+There's a lot going on under the hood, but the result is an efficient,
+easy-to-use encoding system for transmitting data. Here's a complete example
+showing differing encoded and decoded types. Note how easy it is to send and
+receive values; all you need to do is present values and variables to the
+<a href="/pkg/encoding/gob/">gob package</a> and it does all the work.
+</p>
+
+{{code "/doc/progs/gobs2.go" `/package main/` `$`}}
+
+<p>
+You can compile and run this example code in the
+<a href="http://play.golang.org/p/_-OJV-rwMq">Go Playground</a>.
+</p>
+
+<p>
+The <a href="/pkg/net/rpc/">rpc package</a> builds on gobs to turn this
+encode/decode automation into transport for method calls across the network.
+That's a subject for another article.
+</p>
+
+<p>
+<b>Details</b>
+</p>
+
+<p>
+The <a href="/pkg/encoding/gob/">gob package documentation</a>, especially the
+file <a href="/src/pkg/encoding/gob/doc.go">doc.go</a>, expands on many of the
+details described here and includes a full worked example showing how the
+encoding represents data. If you are interested in the innards of the gob
+implementation, that's a good place to start.
+</p>

doc/articles/godoc_documenting_go_code.html

@@ -0,0 +1,139 @@
+<!--{
+"Title": "Godoc: documenting Go code",
+"Template": true
+}-->
+
+<p>
+The Go project takes documentation seriously. Documentation is a huge part of
+making software accessible and maintainable. Of course it must be well-written
+and accurate, but it also must be easy to write and to maintain. Ideally, it
+should be coupled to the code itself so the documentation evolves along with the
+code. The easier it is for programmers to produce good documentation, the better
+for everyone.
+</p>
+
+<p>
+To that end, we have developed the <a href="/cmd/godoc/">godoc</a> documentation
+tool. This article describes godoc's approach to documentation, and explains how
+you can use our conventions and tools to write good documentation for your own
+projects.
+</p>
+
+<p>
+Godoc parses Go source code - including comments - and produces documentation as
+HTML or plain text. The end result is documentation tightly coupled with the
+code it documents. For example, through godoc's web interface you can navigate
+from a function's <a href="/pkg/strings/#HasPrefix">documentation</a> to its
+<a href="/src/pkg/strings/strings.go?#L312">implementation</a> with one click.
+</p>
+
+<p>
+Godoc is conceptually related to Python's
+<a href="http://www.python.org/dev/peps/pep-0257/">Docstring</a> and Java's
+<a href="http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html">Javadoc</a>,
+but its design is simpler. The comments read by godoc are not language
+constructs (as with Docstring) nor must they have their own machine-readable
+syntax (as with Javadoc). Godoc comments are just good comments, the sort you
+would want to read even if godoc didn't exist.
+</p>
+
+<p>
+The convention is simple: to document a type, variable, constant, function, or
+even a package, write a regular comment directly preceding its declaration, with
+no intervening blank line. Godoc will then present that comment as text
+alongside the item it documents. For example, this is the documentation for the
+<code>fmt</code> package's <a href="/pkg/fmt/#Fprint"><code>Fprint</code></a>
+function:
+</p>
+
+{{code "/src/pkg/fmt/print.go" `/Fprint formats using the default/` `/func Fprint/`}}
+
+<p>
+Notice this comment is a complete sentence that begins with the name of the
+element it describes. This important convention allows us to generate
+documentation in a variety of formats, from plain text to HTML to UNIX man
+pages, and makes it read better when tools truncate it for brevity, such as when
+they extract the first line or sentence.
+</p>
+
+<p>
+Comments on package declarations should provide general package documentation.
+These comments can be short, like the <a href="/pkg/sort/"><code>sort</code></a>
+package's brief description:
+</p>
+
+{{code "/src/pkg/sort/sort.go" `/Package sort provides/` `/package sort/`}}
+
+<p>
+They can also be detailed like the <a href="/pkg/encoding/gob/">gob package</a>'s
+overview. That package uses another convention for packages
+that need large amounts of introductory documentation: the package comment is
+placed in its own file, <a href="/src/pkg/encoding/gob/doc.go">doc.go</a>, which
+contains only those comments and a package clause.
+</p>
+
+<p>
+When writing package comments of any size, keep in mind that their first
+sentence will appear in godoc's <a href="/pkg/">package list</a>.
+</p>
+
+<p>
+Comments that are not adjacent to a top-level declaration are omitted from
+godoc's output, with one notable exception. Top-level comments that begin with
+the word <code>"BUG(who)”</code> are recognized as known bugs, and included in
+the "Bugs” section of the package documentation. The "who” part should be the
+user name of someone who could provide more information. For example, this is a
+known issue from the <a href="/pkg/bytes/#bugs">bytes package</a>:
+</p>
+
+<pre>
+// BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly.
+</pre>
+
+<p>
+Godoc treats executable commands somewhat differently. Instead of inspecting the
+command source code, it looks for a Go source file belonging to the special
+package "documentation”. The comment on the "package documentation” clause is
+used as the command's documentation. For example, see the
+<a href="/cmd/godoc/">godoc documentation</a> and its corresponding
+<a href="/src/cmd/godoc/doc.go">doc.go</a> file.
+</p>
+
+<p>
+There are a few formatting rules that Godoc uses when converting comments to
+HTML:
+</p>
+
+<ul>
+<li>
+Subsequent lines of text are considered part of the same paragraph; you must
+leave a blank line to separate paragraphs.
+</li>
+<li>
+Pre-formatted text must be indented relative to the surrounding comment text
+(see gob's <a href="/src/pkg/encoding/gob/doc.go">doc.go</a> for an example).
+</li>
+<li>
+URLs will be converted to HTML links; no special markup is necessary.
+</li>
+</ul>
+
+<p>
+Note that none of these rules requires you to do anything out of the ordinary.
+</p>
+
+<p>
+In fact, the best thing about godoc's minimal approach is how easy it is to use.
+As a result, a lot of Go code, including all of the standard library, already
+follows the conventions.
+</p>
+
+<p>
+Your own code can present good documentation just by having comments as
+described above. Any Go packages installed inside <code>$GOROOT/src/pkg</code>
+and any <code>GOPATH</code> work spaces will already be accessible via godoc's
+command-line and HTTP interfaces, and you can specify additional paths for
+indexing via the <code>-path</code> flag or just by running <code>"godoc ."</code>
+in the source directory. See the <a href="/cmd/godoc/">godoc documentation</a>
+for more details.
+</p>

doc/articles/gos_declaration_syntax.html

@@ -0,0 +1,348 @@
+<!--{
+"Title": "Go's Declaration Syntax"
+}-->
+
+<p>
+Newcomers to Go wonder why the declaration syntax is different from the
+tradition established in the C family. In this post we'll compare the
+two approaches and explain why Go's declarations look as they do.
+</p>
+
+<p>
+<b>C syntax</b>
+</p>
+
+<p>
+First, let's talk about C syntax. C took an unusual and clever approach
+to declaration syntax. Instead of describing the types with special
+syntax, one writes an expression involving the item being declared, and
+states what type that expression will have. Thus
+</p>
+
+<pre>
+int x;
+</pre>
+
+<p>
+declares x to be an int: the expression 'x' will have type int. In
+general, to figure out how to write the type of a new variable, write an
+expression involving that variable that evaluates to a basic type, then
+put the basic type on the left and the expression on the right.
+</p>
+
+<p>
+Thus, the declarations
+</p>
+
+<pre>
+int *p;
+int a[3];
+</pre>
+
+<p>
+state that p is a pointer to int because '*p' has type int, and that a
+is an array of ints because a[3] (ignoring the particular index value,
+which is punned to be the size of the array) has type int.
+</p>
+
+<p>
+What about functions? Originally, C's function declarations wrote the
+types of the arguments outside the parens, like this:
+</p>
+
+<pre>
+int main(argc, argv)
+    int argc;
+    char *argv[];
+{ /* ... */ }
+</pre>
+
+<p>
+Again, we see that main is a function because the expression main(argc,
+argv) returns an int. In modern notation we'd write
+</p>
+
+<pre>
+int main(int argc, char *argv[]) { /* ... */ }
+</pre>
+
+<p>
+but the basic structure is the same.
+</p>
+
+<p>
+This is a clever syntactic idea that works well for simple types but can
+get confusing fast. The famous example is declaring a function pointer.
+Follow the rules and you get this:
+</p>
+
+<pre>
+int (*fp)(int a, int b);
+</pre>
+
+<p>
+Here, fp is a pointer to a function because if you write the expression
+(*fp)(a, b) you'll call a function that returns int. What if one of fp's
+arguments is itself a function?
+</p>
+
+<pre>
+int (*fp)(int (*ff)(int x, int y), int b)
+</pre>
+
+<p>
+That's starting to get hard to read.
+</p>
+
+<p>
+Of course, we can leave out the name of the parameters when we declare a
+function, so main can be declared
+</p>
+
+<pre>
+int main(int, char *[])
+</pre>
+
+<p>
+Recall that argv is declared like this,
+</p>
+
+<pre>
+char *argv[]
+</pre>
+
+<p>
+so you drop the name from the <em>middle</em> of its declaration to construct
+its type. It's not obvious, though, that you declare something of type
+char *[] by putting its name in the middle.
+</p>
+
+<p>
+And look what happens to fp's declaration if you don't name the
+parameters:
+</p>
+
+<pre>
+int (*fp)(int (*)(int, int), int)
+</pre>
+
+<p>
+Not only is it not obvious where to put the name inside
+</p>
+
+<pre>
+int (*)(int, int)
+</pre>
+
+<p>
+it's not exactly clear that it's a function pointer declaration at all.
+And what if the return type is a function pointer?
+</p>
+
+<pre>
+int (*(*fp)(int (*)(int, int), int))(int, int)
+</pre>
+
+<p>
+It's hard even to see that this declaration is about fp.
+</p>
+
+<p>
+You can construct more elaborate examples but these should illustrate
+some of the difficulties that C's declaration syntax can introduce.
+</p>
+
+<p>
+There's one more point that needs to be made, though. Because type and
+declaration syntax are the same, it can be difficult to parse
+expressions with types in the middle. This is why, for instance, C casts
+always parenthesize the type, as in
+</p>
+
+<pre>
+(int)M_PI
+</pre>
+
+<p>
+<b>Go syntax</b>
+</p>
+
+<p>
+Languages outside the C family usually use a distinct type syntax in
+declarations. Although it's a separate point, the name usually comes
+first, often followed by a colon. Thus our examples above become
+something like (in a fictional but illustrative language)
+</p>
+
+<pre>
+x: int
+p: pointer to int
+a: array[3] of int
+</pre>
+
+<p>
+These declarations are clear, if verbose - you just read them left to
+right. Go takes its cue from here, but in the interests of brevity it
+drops the colon and removes some of the keywords:
+</p>
+
+<pre>
+x int
+p *int
+a [3]int
+</pre>
+
+<p>
+There is no direct correspondence between the look of [3]int and how to
+use a in an expression. (We'll come back to pointers in the next
+section.) You gain clarity at the cost of a separate syntax.
+</p>
+
+<p>
+Now consider functions. Let's transcribe the declaration for main, even
+though the main function in Go takes no arguments:
+</p>
+
+<pre>
+func main(argc int, argv *[]byte) int
+</pre>
+
+<p>
+Superficially that's not much different from C, but it reads well from
+left to right:
+</p>
+
+<p>
+<em>function main takes an int and a pointer to a slice of bytes and returns an int.</em>
+</p>
+
+<p>
+Drop the parameter names and it's just as clear - they're always first
+so there's no confusion.
+</p>
+
+<pre>
+func main(int, *[]byte) int
+</pre>
+
+<p>
+One value of this left-to-right style is how well it works as the types
+become more complex. Here's a declaration of a function variable
+(analogous to a function pointer in C):
+</p>
+
+<pre>
+f func(func(int,int) int, int) int
+</pre>
+
+<p>
+Or if f returns a function:
+</p>
+
+<pre>
+f func(func(int,int) int, int) func(int, int) int
+</pre>
+
+<p>
+It still reads clearly, from left to right, and it's always obvious
+which name is being declared - the name comes first.
+</p>
+
+<p>
+The distinction between type and expression syntax makes it easy to
+write and invoke closures in Go:
+</p>
+
+<pre>
+sum := func(a, b int) int { return a+b } (3, 4)
+</pre>
+
+<p>
+<b>Pointers</b>
+</p>
+
+<p>
+Pointers are the exception that proves the rule. Notice that in arrays
+and slices, for instance, Go's type syntax puts the brackets on the left
+of the type but the expression syntax puts them on the right of the
+expression:
+</p>
+
+<pre>
+var a []int
+x = a[1]
+</pre>
+
+<p>
+For familiarity, Go's pointers use the * notation from C, but we could
+not bring ourselves to make a similar reversal for pointer types. Thus
+pointers work like this
+</p>
+
+<pre>
+var p *int
+x = *p
+</pre>
+
+<p>
+We couldn't say
+</p>
+
+<pre>
+var p *int
+x = p*
+</pre>
+
+<p>
+because that postfix * would conflate with multiplication. We could have
+used the Pascal ^, for example:
+</p>
+
+<pre>
+var p ^int
+x = p^
+</pre>
+
+<p>
+and perhaps we should have (and chosen another operator for xor),
+because the prefix asterisk on both types and expressions complicates
+things in a number of ways. For instance, although one can write
+</p>
+
+<pre>
+[]int("hi")
+</pre>
+
+<p>
+as a conversion, one must parenthesize the type if it starts with a *:
+</p>
+
+<pre>
+(*int)(nil)
+</pre>
+
+<p>
+Had we been willing to give up * as pointer syntax, those parentheses
+would be unnecessary.
+</p>
+
+<p>
+So Go's pointer syntax is tied to the familiar C form, but those ties
+mean that we cannot break completely from using parentheses to
+disambiguate types and expressions in the grammar.
+</p>
+
+<p>
+Overall, though, we believe Go's type syntax is easier to understand
+than C's, especially when things get complicated.
+</p>
+
+<p>
+<b>Notes</b>
+</p>
+
+<p>
+Go's declarations read left to right. It's been pointed out that C's
+read in a spiral! See <a href="http://c-faq.com/decl/spiral.anderson.html">
+The "Clockwise/Spiral Rule"</a> by David Anderson.
+</p>

doc/articles/image_draw.html

@@ -0,0 +1,222 @@
+<!--{
+	"Title": "The Go image/draw package",
+	"Template": true
+}-->
+
+<p>
+<a href="/pkg/image/draw/">Package image/draw</a> defines
+only one operation: drawing a source image onto a destination
+image, through an optional mask image. This one operation is
+surprisingly versatile and can perform a number of common image
+manipulation tasks elegantly and efficiently.  
+</p>
+
+<p>
+Composition is performed pixel by pixel in the style of the Plan 9
+graphics library and the X Render extension. The model is based on
+the classic "Compositing Digital Images" paper by Porter and Duff,
+with an additional mask parameter: <code>dst = (src IN mask) OP dst</code>.
+For a fully opaque mask, this reduces to the original Porter-Duff
+formula: <code>dst = src OP dst</code>. In Go, a nil mask image is equivalent
+to an infinitely sized, fully opaque mask image.
+</p>
+
+<p>
+The Porter-Duff paper presented
+<a href="http://www.w3.org/TR/SVGCompositing/examples/compop-porterduff-examples.png">12 different composition operators</a>,
+but with an explicit mask, only 2 of these are needed in practice:
+source-over-destination and source. In Go, these operators are
+represented by the <code>Over</code> and <code>Src</code> constants. The <code>Over</code> operator
+performs the natural layering of a source image over a destination
+image: the change to the destination image is smaller where the
+source (after masking) is more transparent (that is, has lower
+alpha). The <code>Src</code> operator merely copies the source (after masking)
+with no regard for the destination image's original content. For
+fully opaque source and mask images, the two operators produce the
+same output, but the <code>Src</code> operator is usually faster.
+</p>
+
+<p><b>Geometric Alignment</b></p>
+
+<p>  
+Composition requires associating destination pixels with source and
+mask pixels. Obviously, this requires destination, source and mask
+images, and a composition operator, but it also requires specifying
+what rectangle of each image to use. Not every drawing should write
+to the entire destination: when updating an animating image, it is
+more efficient to only draw the parts of the image that have
+changed. Not every drawing should read from the entire source: when
+using a sprite that combines many small images into one large one,
+only a part of the image is needed. Not every drawing should read
+from the entire mask: a mask image that collects a font's glyphs is
+similar to a sprite. Thus, drawing also needs to know three
+rectangles, one for each image. Since each rectangle has the same
+width and height, it suffices to pass a destination rectangle `r`
+and two points <code>sp</code> and <code>mp</code>: the source rectangle is equal to <code>r</code>
+translated so that <code>r.Min</code> in the destination image aligns with 
+<code>sp</code> in the source image, and similarly for <code>mp</code>. The effective
+rectangle is also clipped to each image's bounds in their
+respective co-ordinate space.
+</p>
+
+<p>
+<img src="image-20.png">
+</p>
+
+<p>
+The <a href="/pkg/image/draw/#DrawMask"><code>DrawMask</code></a>
+function takes seven arguments, but an explicit mask and mask-point
+are usually unnecessary, so the
+<a href="/pkg/image/draw/#Draw"><code>Draw</code></a> function takes five:
+</p>
+
+<pre>
+// Draw calls DrawMask with a nil mask.
+func Draw(dst Image, r image.Rectangle, src image.Image, sp image.Point, op Op)
+func DrawMask(dst Image, r image.Rectangle, src image.Image, sp image.Point,
+	mask image.Image, mp image.Point, op Op)
+</pre>
+
+<p>
+The destination image must be mutable, so the image/draw package
+defines a <a href="/pkg/image/draw/#Image"><code>draw.Image</code></a>
+interface which has a <code>Set</code> method.
+</p>
+
+{{code "../src/pkg/image/draw/draw.go" `/type Image/` `/}/`}}
+  
+<p><b>Filling a Rectangle</b></p>
+
+<p>
+To fill a rectangle with a solid color, use an <code>image.Uniform</code>
+source. The <code>ColorImage</code> type re-interprets a <code>Color</code> as a
+practically infinite-sized <code>Image</code> of that color. For those
+familiar with the design of Plan 9's draw library, there is no need
+for an explicit "repeat bit" in Go's slice-based image types; the
+concept is subsumed by <code>Uniform</code>.
+</p>
+
+{{code "/doc/progs/image_draw.go" `/ZERO/` `/STOP/`}}
+
+<p>
+To initialize a new image to all-blue:
+</p>
+
+{{code "/doc/progs/image_draw.go" `/BLUE/` `/STOP/`}}
+
+<p>
+To reset an image to transparent (or black, if the destination
+image's color model cannot represent transparency), use
+<code>image.Transparent</code>, which is an <code>image.Uniform</code>:
+</p>
+
+{{code "/doc/progs/image_draw.go" `/RESET/` `/STOP/`}}
+  
+<p>
+<img src="image-2a.png">
+</p>
+
+ 
+<p><b>Copying an Image</b></p>
+
+<p>
+To copy from a rectangle <code>sr</code> in the source image to a rectangle
+starting at a point <code>dp</code> in the destination, convert the source
+rectangle into the destination image's co-ordinate space:
+</p>
+
+{{code "/doc/progs/image_draw.go" `/RECT/` `/STOP/`}}
+  
+<p>
+Alternatively:
+</p>
+
+{{code "/doc/progs/image_draw.go" `/RECT2/` `/STOP/`}}
+  
+<p>
+To copy the entire source image, use <code>sr = src.Bounds()</code>.
+</p>
+  
+<p>
+<img src="image-2b.png">
+</p>
+ 
+<p><b>Scrolling an Image</b></p>
+
+<p>
+Scrolling an image is just copying an image to itself, with
+different destination and source rectangles. Overlapping
+destination and source images are perfectly valid, just as Go's
+built-in copy function can handle overlapping destination and
+source slices. To scroll an image m by 20 pixels:
+</p>
+
+{{code "/doc/progs/image_draw.go" `/SCROLL/` `/STOP/`}}
+  
+<p><img src="image-2c.png"></p>
+ 
+<p><b>Converting an Image to RGBA</b></p>
+
+<p>
+The result of decoding an image format might not be an
+<code>image.RGBA</code>: decoding a GIF results in an <code>image.Paletted</code>,
+decoding a JPEG results in a <code>ycbcr.YCbCr</code>, and the result of
+decoding a PNG depends on the image data. To convert any image to
+an <code>image.RGBA</code>:
+</p>
+
+{{code "/doc/progs/image_draw.go" `/CONV/` `/STOP/`}}
+  
+<p>
+<img src="image-2d.png">
+</p>
+
+<p><b>Drawing Through a Mask</b></p>
+
+<p>
+To draw an image through a circular mask with center <code>p</code> and radius
+<code>r</code>:
+</p>
+
+{{code "/doc/progs/image_draw.go" `/CIRCLESTRUCT/` `/STOP/`}}
+{{code "/doc/progs/image_draw.go" `/CIRCLE2/` `/STOP/`}}
+  
+<p>
+<img src="image-2e.png">
+</p>
+
+<p><b>Drawing Font Glyphs</b></p>
+
+<p> 
+To draw a font glyph in blue starting from a point <code>p</code>, draw with
+an <code>image.ColorImage</code> source and an <code>image.Alpha mask</code>. For
+simplicity, we aren't performing any sub-pixel positioning or
+rendering, or correcting for a font's height above a baseline.
+</p>
+
+{{code "/doc/progs/image_draw.go" `/GLYPH/` `/STOP/`}}
+
+<p>
+<img src="image-2f.png">
+</p>
+  
+<p><b>Performance</b></p>
+
+<p>
+The image/draw package implementation demonstrates how to provide
+an image manipulation function that is both general purpose, yet
+efficient for common cases. The <code>DrawMask</code> function takes arguments
+of interface types, but immediately makes type assertions that its
+arguments are of specific struct types, corresponding to common
+operations like drawing one <code>image.RGBA</code> image onto another, or
+drawing an <code>image.Alpha</code> mask (such as a font glyph) onto an
+<code>image.RGBA</code> image. If a type assertion succeeds, that type
+information is used to run a specialized implementation of the
+general algorithm. If the assertions fail, the fallback code path
+uses the generic <code>At</code> and <code>Set</code> methods. The fast-paths are purely
+a performance optimization; the resultant destination image is the
+same either way. In practice, only a small number of special cases
+are necessary to support typical applications.  
+</p>
+
+

doc/articles/image_package.html

@@ -0,0 +1,312 @@
+<!--{
+	"Title": "The Go image package",
+	"Template": true
+}-->
+
+<p>
+The <a href="/pkg/image/">image</a> and
+<a href="/pkg/image/color/">image/color</a> packages define a number of types:
+<code>color.Color</code> and <code>color.Model</code> describe colors,
+<code>image.Point</code> and <code>image.Rectangle</code> describe basic 2-D
+geometry, and <code>image.Image</code> brings the two concepts together to
+represent a rectangular grid of colors. A
+<a href="/doc/articles/image_draw.html">separate article</a> covers image
+composition with the <a href="/pkg/image/draw/">image/draw</a> package.
+</p>
+
+<p>
+<b>Colors and Color Models</b>
+</p>
+
+<p>
+<a href="/pkg/image/color/#Color">Color</a> is an interface that defines the minimal
+method set of any type that can be considered a color: one that can be converted
+to red, green, blue and alpha values. The conversion may be lossy, such as
+converting from CMYK or YCbCr color spaces.
+</p>
+
+{{code "/src/pkg/image/color/color.go" `/type Color interface/` `/^}/`}}
+
+<p>
+There are three important subtleties about the return values. First, the red,
+green and blue are alpha-premultiplied: a fully saturated red that is also 25%
+transparent is represented by RGBA returning a 75% r. Second, the channels have
+a 16-bit effective range: 100% red is represented by RGBA returning an r of
+65535, not 255, so that converting from CMYK or YCbCr is not as lossy. Third,
+the type returned is <code>uint32</code>, even though the maximum value is 65535, to
+guarantee that multiplying two values together won't overflow. Such
+multiplications occur when blending two colors according to an alpha mask from a
+third color, in the style of
+<a href="https://en.wikipedia.org/wiki/Alpha_compositing">Porter and Duff's</a>
+classic algebra:
+</p>
+
+<pre>
+dstr, dstg, dstb, dsta := dst.RGBA()
+srcr, srcg, srcb, srca := src.RGBA()
+_, _, _, m := mask.RGBA()
+const M = 1<<16 - 1
+// The resultant red value is a blend of dstr and srcr, and ranges in [0, M].
+// The calculation for green, blue and alpha is similar.
+dstr = (dstr*(M-m) + srcr*m) / M
+</pre>
+
+<p>
+The last line of that code snippet would have been more complicated if we worked
+with non-alpha-premultiplied colors, which is why <code>Color</code> uses
+alpha-premultiplied values.
+</p>
+
+<p>
+The image/color package also defines a number of concrete types that implement
+the <code>Color</code> interface. For example,
+<a href="/pkg/image/color/#RGBA"><code>RGBA</code></a> is a struct that represents
+the classic "8 bits per channel" color.
+</p>
+
+{{code "/src/pkg/image/color/color.go" `/type RGBA struct/` `/^}/`}}
+
+<p>
+Note that the <code>R</code> field of an <code>RGBA</code> is an 8-bit
+alpha-premultiplied color in the range [0, 255]. <code>RGBA</code> satisfies the
+<code>Color</code> interface by multiplying that value by 0x101 to generate a
+16-bit alpha-premultiplied color in the range [0, 65535]. Similarly, the
+<a href="/pkg/image/color/#NRGBA"><code>NRGBA</code></a> struct type represents
+an 8-bit non-alpha-premultiplied color, as used by the PNG image format. When
+manipulating an <code>NRGBA</code>'s fields directly, the values are
+non-alpha-premultiplied, but when calling the <code>RGBA</code> method, the
+return values are alpha-premultiplied.
+</p>
+
+<p>
+A <a href="/pkg/image/color/#Model"><code>Model</code></a> is simply
+something that can convert <code>Color</code>s to other <code>Color</code>s, possibly lossily. For
+example, the <code>GrayModel</code> can convert any <code>Color</code> to a
+desaturated <a href="/pkg/image/color/#Gray"><code>Gray</code></a>. A
+<code>Palette</code> can convert any <code>Color</code> to one from a
+limited palette.
+</p>
+
+{{code "/src/pkg/image/color/color.go" `/type Model interface/` `/^}/`}}
+
+{{code "/src/pkg/image/color/color.go" `/type Palette \[\]Color/`}}
+
+<p>
+<b>Points and Rectangles</b>
+</p>
+
+<p>
+A <a href="/pkg/image/#Point"><code>Point</code></a> is an (x, y) co-ordinate
+on the integer grid, with axes increasing right and down. It is neither a pixel
+nor a grid square. A <code>Point</code> has no intrinsic width, height or
+color, but the visualizations below use a small colored square.
+</p>
+
+{{code "/src/pkg/image/geom.go" `/type Point struct/` `/^}/`}}
+
+<p>
+<img src="image-package-01.png" width="400" height="300">
+</p>
+
+{{code "/doc/progs/image_package1.go" `/p := image.Point/`}}
+
+<p>
+A <a href="/pkg/image/#Rectangle"><code>Rectangle</code></a> is an axis-aligned
+rectangle on the integer grid, defined by its top-left and bottom-right
+<code>Point</code>.  A <code>Rectangle</code> also has no intrinsic color, but
+the visualizations below outline rectangles with a thin colored line, and call
+out their <code>Min</code> and <code>Max</code> <code>Point</code>s.
+</p>
+
+{{code "/src/pkg/image/geom.go" `/type Rectangle struct/` `/^}/`}}
+
+<p>
+For convenience, <code>image.Rect(x0, y0, x1, y1)</code> is equivalent to
+<code>image.Rectangle{image.Point{x0, y0}, image.Point{x1, y1}}</code>, but is
+much easier to type.
+</p>
+
+<p>
+A <code>Rectangle</code> is inclusive at the top-left and exclusive at the
+bottom-right. For a <code>Point p</code> and a <code>Rectangle r</code>,
+<code>p.In(r)</code> if and only if
+<code>r.Min.X <= p.X && p.X < r.Max.X</code>, and similarly for <code>Y</code>. This is analagous to how
+a slice <code>s[i0:i1]</code> is inclusive at the low end and exclusive at the
+high end. (Unlike arrays and slices, a <code>Rectangle</code> often has a
+non-zero origin.)
+</p>
+
+<p>
+<img src="image-package-02.png" width="400" height="300">
+</p>
+
+{{code "/doc/progs/image_package2.go" `/r := image.Rect/` `/fmt.Println/`}}
+
+<p>
+Adding a <code>Point</code> to a <code>Rectangle</code> translates the
+<code>Rectangle</code>. Points and Rectangles are not restricted to be in the
+bottom-right quadrant.
+</p>
+
+<p>
+<img src="image-package-03.png" width="400" height="300">
+</p>
+
+{{code "/doc/progs/image_package3.go" `/r := image.Rect/` `/fmt.Println/`}}
+
+<p>
+Intersecting two Rectangles yields another Rectangle, which may be empty.
+</p>
+
+<p>
+<img src="image-package-04.png" width="400" height="300">
+</p>
+
+{{code "/doc/progs/image_package4.go" `/r := image.Rect/` `/fmt.Printf/`}}
+
+<p>
+Points and Rectangles are passed and returned by value. A function that takes a
+<code>Rectangle</code> argument will be as efficient as a function that takes
+two <code>Point</code> arguments, or four <code>int</code> arguments.
+</p>
+
+<p>
+<b>Images</b>
+</p>
+
+<p>
+An <a href="/pkg/image/#Image">Image</a> maps every grid square in a
+<code>Rectangle</code> to a <code>Color</code> from a <code>Model</code>.
+"The pixel at (x, y)" refers to the color of the grid square defined by the
+points (x, y), (x+1, y), (x+1, y+1) and (x, y+1).
+</p>
+
+{{code "/src/pkg/image/image.go" `/type Image interface/` `/^}/`}}
+
+<p>
+A common mistake is assuming that an <code>Image</code>'s bounds start at (0,
+0). For example, an animated GIF contains a sequence of Images, and each
+<code>Image</code> after the first typically only holds pixel data for the area
+that changed, and that area doesn't necessarily start at (0, 0). The correct
+way to iterate over an <code>Image</code> m's pixels looks like:
+</p>
+
+<pre>
+b := m.Bounds()
+for y := b.Min.Y; y < b.Max.Y; y++ {
+	for x := b.Min.X; y < b.Max.X; x++ {
+		doStuffWith(m.At(x, y))
+	}
+}
+</pre>
+
+<p>
+<code>Image</code> implementations do not have to be based on an in-memory
+slice of pixel data. For example, a
+<a href="/pkg/image/#Uniform"><code>Uniform</code></a> is an
+<code>Image</code> of enormous bounds and uniform color, whose in-memory
+representation is simply that color.
+</p>
+
+{{code "/src/pkg/image/names.go" `/type Uniform struct/` `/^}/`}}
+
+<p>
+Typically, though, programs will want an image based on a slice. Struct types
+like <a href="/pkg/image/#RGBA"><code>RGBA</code></a> and
+<a href="/pkg/image/#Gray"><code>Gray</code></a> (which other packages refer
+to as <code>image.RGBA</code> and <code>image.Gray</code>) hold slices of pixel
+data and implement the <code>Image</code> interface.
+</p>
+
+{{code "/src/pkg/image/image.go" `/type RGBA struct/` `/^}/`}}
+
+<p>
+These types also provide a <code>Set(x, y int, c color.Color)</code> method
+that allows modifying the image one pixel at a time.
+</p>
+
+{{code "/doc/progs/image_package5.go" `/m := image.New/` `/m.Set/`}}
+
+<p>
+If you're reading or writing a lot of pixel data, it can be more efficient, but
+more complicated, to access these struct type's <code>Pix</code> field directly.
+</p>
+
+<p>
+The slice-based <code>Image</code> implementations also provide a
+<code>SubImage</code> method, which returns an <code>Image</code> backed by the
+same array. Modifying the pixels of a sub-image will affect the pixels of the
+original image, analagous to how modifying the contents of a sub-slice
+<code>s[i0:i1]</code> will affect the contents of the original slice
+<code>s</code>.
+</p>
+
+<img src="image-package-05.png" width="400" height="300">
+
+{{code "/doc/progs/image_package6.go" `/m0 := image.New/` `/fmt.Println\(m0.Stride/`}}
+
+<p>
+For low-level code that works on an image's <code>Pix</code> field, be aware
+that ranging over <code>Pix</code> can affect pixels outside an image's bounds.
+In the example above, the pixels covered by <code>m1.Pix</code> are shaded in
+blue. Higher-level code, such as the <code>At</code> and <code>Set</code>
+methods or the <a href="/pkg/image/draw/">image/draw package</a>, will clip
+their operations to the image's bounds.
+</p>
+
+<p>
+<b>Image Formats</b>
+</p>
+
+<p>
+The standard package library supports a number of common image formats, such as
+GIF, JPEG and PNG. If you know the format of a source image file, you can
+decode from an <a href="/pkg/io/#Reader"><code>io.Reader</code></a> directly.
+</p>
+
+<pre>
+import (
+	"image/jpeg"
+	"image/png"
+	"io"
+)
+
+// convertJPEGToPNG converts from JPEG to PNG.
+func convertJPEGToPNG(w io.Writer, r io.Reader) error {
+	img, err := jpeg.Decode(r)
+	if err != nil {
+		return err
+	}
+	return png.Encode(w, img)
+}
+</pre>
+
+<p>
+If you have image data of unknown format, the
+<a href="/pkg/image/#Decode"><code>image.Decode</code></a> function can detect
+the format. The set of recognized formats is constructed at run time and is not
+limited to those in the standard package library. An image format package
+typically registers its format in an init function, and the main package will
+"underscore import" such a package solely for the side effect of format
+registration.
+</p>
+
+<pre>
+import (
+	"image"
+	"image/png"
+	"io"
+
+	_ "code.google.com/p/vp8-go/webp"
+	_ "image/jpeg"
+)
+
+// convertToPNG converts from any recognized format to PNG.
+func convertToPNG(w io.Writer, r io.Reader) error {
+	img, _, err := image.Decode(r)
+	if err != nil {
+		return err
+	}
+	return png.Encode(w, img)
+}
+</pre>

doc/articles/index.html

@@ -0,0 +1,7 @@
+<!--{
+	"Title": "/doc/articles/"
+}-->
+
+<p>
+See the <a href="/doc/#articles">Documents page</a> for a complete list of Go articles.
+</p>

doc/articles/json_and_go.html

@@ -0,0 +1,356 @@
+<!--{
+"Title": "JSON and Go",
+"Template": true
+}-->
+
+<p>
+JSON (JavaScript Object Notation) is a simple data interchange format.
+Syntactically it resembles the objects and lists of JavaScript. It is most
+commonly used for communication between web back-ends and JavaScript programs
+running in the browser, but it is used in many other places, too. Its home page,
+<a href="http://json.org">json.org</a>, provides a wonderfully clear and concise
+definition of the standard.
+</p>
+
+<p>
+With the <a href="/pkg/encoding/json/">json package</a> it's a snap to read and
+write JSON data from your Go programs.
+</p>
+
+<p>
+<b>Encoding</b>
+</p>
+
+<p>
+To encode JSON data we use the
+<a href="/pkg/encoding/json/#Marshal"><code>Marshal</code></a> function.
+</p>
+
+<pre>
+func Marshal(v interface{}) ([]byte, error)
+</pre>
+
+<p>
+Given the Go data structure, <code>Message</code>,
+</p>
+
+{{code "/doc/progs/json1.go" `/type Message/` `/STOP/`}}
+
+<p>
+and an instance of <code>Message</code>
+</p>
+
+{{code "/doc/progs/json1.go" `/m :=/`}}
+
+<p>
+we can marshal a JSON-encoded version of m using <code>json.Marshal</code>:
+</p>
+
+{{code "/doc/progs/json1.go" `/b, err :=/`}}
+
+<p>
+If all is well, <code>err</code> will be <code>nil</code> and <code>b</code>
+will be a <code>[]byte</code> containing this JSON data:
+</p>
+
+<pre>
+b == []byte(`{"Name":"Alice","Body":"Hello","Time":1294706395881547000}`)
+</pre>
+
+<p>
+Only data structures that can be represented as valid JSON will be encoded:
+</p>
+
+<ul>
+<li>
+JSON objects only support strings as keys; to encode a Go map type it must be
+of the form <code>map[string]T</code> (where <code>T</code> is any Go type
+supported by the json package).
+</li>
+<li>
+Channel, complex, and function types cannot be encoded.
+</li>
+<li>
+Cyclic data structures are not supported; they will cause <code>Marshal</code>
+to go into an infinite loop.
+</li>
+<li>
+Pointers will be encoded as the values they point to (or 'null' if the pointer
+is <code>nil</code>).
+</li>
+</ul>
+
+<p>
+The json package only accesses the exported fields of struct types (those that
+begin with an uppercase letter). Therefore only the the exported fields of a
+struct will be present in the JSON output.
+</p>
+
+<p>
+<b>Decoding</b>
+</p>
+
+<p>
+To decode JSON data we use the
+<a href="/pkg/encoding/json/#Unmarshal"><code>Unmarshal</code></a> function.
+</p>
+
+<pre>
+func Unmarshal(data []byte, v interface{}) error
+</pre>
+
+<p>
+We must first create a place where the decoded data will be stored
+</p>
+
+{{code "/doc/progs/json1.go" `/var m Message/`}}
+
+<p>
+and call <code>json.Unmarshal</code>, passing it a <code>[]byte</code> of JSON
+data and a pointer to <code>m</code>
+</p>
+
+{{code "/doc/progs/json1.go" `/err := json.Unmarshal/`}}
+
+<p>
+If <code>b</code> contains valid JSON that fits in <code>m</code>, after the
+call <code>err</code> will be <code>nil</code> and the data from <code>b</code>
+will have been stored in the struct <code>m</code>, as if by an assignment
+like:
+</p>
+
+{{code "/doc/progs/json1.go" `/m = Message/` `/STOP/`}}
+
+<p>
+How does <code>Unmarshal</code> identify the fields in which to store the
+decoded data? For a given JSON key <code>"Foo"</code>, <code>Unmarshal</code>
+will look through the destination struct's fields to find (in order of
+preference):
+</p>
+
+<ul>
+<li>
+An exported field with a tag of <code>"Foo"</code> (see the
+<a href="/ref/spec#Struct_types">Go spec</a> for more on struct tags),
+</li>
+<li>
+An exported field named <code>"Foo"</code>, or
+</li>
+<li>
+An exported field named <code>"FOO"</code> or <code>"FoO"</code> or some other
+case-insensitive match of <code>"Foo"</code>.
+</li>
+</ul>
+
+<p>
+What happens when the structure of the JSON data doesn't exactly match the Go
+type?
+</p>
+
+{{code "/doc/progs/json1.go" `/"Food":"Pickle"/` `/STOP/`}}
+
+<p>
+<code>Unmarshal</code> will decode only the fields that it can find in the
+destination type.  In this case, only the Name field of m will be populated,
+and the Food field will be ignored. This behavior is particularly useful when
+you wish to pick only a few specific fields out of a large JSON blob. It also
+means that any unexported fields in the destination struct will be unaffected
+by <code>Unmarshal</code>.
+</p>
+
+<p>
+But what if you don't know the structure of your JSON data beforehand?
+</p>
+
+<p>
+<b>Generic JSON with interface{}</b>
+</p>
+
+<p>
+The <code>interface{}</code> (empty interface) type describes an interface with
+zero methods.  Every Go type implements at least zero methods and therefore
+satisfies the empty interface.
+</p>
+
+<p>
+The empty interface serves as a general container type:
+</p>
+
+{{code "/doc/progs/json2.go" `/var i interface{}/` `/STOP/`}}
+
+<p>
+A type assertion accesses the underlying concrete type:
+</p>
+
+{{code "/doc/progs/json2.go" `/r := i/` `/STOP/`}}
+
+<p>
+Or, if the underlying type is unknown, a type switch determines the type:
+</p>
+
+{{code "/doc/progs/json2.go" `/switch v/` `/STOP/`}}
+
+
+The json package uses <code>map[string]interface{}</code> and
+<code>[]interface{}</code> values to store arbitrary JSON objects and arrays;
+it will happily unmarshal any valid JSON blob into a plain
+<code>interface{}</code> value.  The default concrete Go types are:
+
+<ul>
+<li>
+<code>bool</code> for JSON booleans,
+</li>
+<li>
+<code>float64</code> for JSON numbers,
+</li>
+<li>
+<code>string</code> for JSON strings, and
+</li>
+<li>
+<code>nil</code> for JSON null.
+</li>
+</ul>
+
+<p>
+<b>Decoding arbitrary data</b>
+</p>
+
+<p>
+Consider this JSON data, stored in the variable <code>b</code>:
+</p>
+
+{{code "/doc/progs/json3.go" `/b :=/`}}
+
+<p>
+Without knowing this data's structure, we can decode it into an
+<code>interface{}</code> value with <code>Unmarshal</code>:
+</p>
+
+{{code "/doc/progs/json3.go" `/var f interface/` `/STOP/`}}
+
+<p>
+At this point the Go value in <code>f</code> would be a map whose keys are
+strings and whose values are themselves stored as empty interface values:
+</p>
+
+{{code "/doc/progs/json3.go" `/f = map/` `/STOP/`}}
+
+<p>
+To access this data we can use a type assertion to access <code>f</code>'s
+underlying <code>map[string]interface{}</code>:
+</p>
+
+{{code "/doc/progs/json3.go" `/m := f/`}}
+
+<p>
+We can then iterate through the map with a range statement and use a type switch
+to access its values as their concrete types:
+</p>
+
+{{code "/doc/progs/json3.go" `/for k, v/` `/STOP/`}}
+
+<p>
+In this way you can work with unknown JSON data while still enjoying the
+benefits of type safety.
+</p>
+
+<p>
+<b>Reference Types</b>
+</p>
+
+<p>
+Let's define a Go type to contain the data from the previous example:
+</p>
+
+{{code "/doc/progs/json4.go" `/type FamilyMember/` `/STOP/`}}
+
+{{code "/doc/progs/json4.go" `/var m FamilyMember/` `/STOP/`}}
+
+<p>
+Unmarshaling that data into a <code>FamilyMember</code> value works as
+expected, but if we look closely we can see a remarkable thing has happened.
+With the var statement we allocated a <code>FamilyMember</code> struct, and
+then provided a pointer to that value to <code>Unmarshal</code>, but at that
+time the <code>Parents</code> field was a <code>nil</code> slice value. To
+populate the <code>Parents</code> field, <code>Unmarshal</code> allocated a new
+slice behind the scenes. This is typical of how <code>Unmarshal</code> works
+with the supported reference types (pointers, slices, and maps).
+</p>
+
+<p>
+Consider unmarshaling into this data structure:
+</p>
+
+<pre>
+type Foo struct {
+    Bar *Bar
+}
+</pre>
+
+<p>
+If there were a <code>Bar</code> field in the JSON object,
+<code>Unmarshal</code> would allocate a new <code>Bar</code> and populate it.
+If not, <code>Bar</code> would be left as a <code>nil</code> pointer.
+</p>
+
+<p>
+From this a useful pattern arises: if you have an application that receives a
+few distinct message types, you might define "receiver" structure like
+</p>
+
+<pre>
+type IncomingMessage struct {
+    Cmd *Command
+    Msg *Message
+}
+</pre>
+
+<p>
+and the sending party can populate the <code>Cmd</code> field and/or the
+<code>Msg</code> field of the top-level JSON object, depending on the type of
+message they want to communicate. <code>Unmarshal</code>, when decoding the
+JSON into an <code>IncomingMessage</code> struct, will only allocate the data
+structures present in the JSON data. To know which messages to process, the
+programmer need simply test that either <code>Cmd</code> or <code>Msg</code> is
+not <code>nil</code>.
+</p>
+
+<p>
+<b>Streaming Encoders and Decoders</b>
+</p>
+
+<p>
+The json package provides <code>Decoder</code> and <code>Encoder</code> types
+to support the common operation of reading and writing streams of JSON data.
+The <code>NewDecoder</code> and <code>NewEncoder</code> functions wrap the
+<a href="/pkg/io/#Reader"><code>io.Reader</code></a> and
+<a href="/pkg/io/#Writer"><code>io.Writer</code></a> interface types.
+</p>
+
+<pre>
+func NewDecoder(r io.Reader) *Decoder
+func NewEncoder(w io.Writer) *Encoder
+</pre>
+
+<p>
+Here's an example program that reads a series of JSON objects from standard
+input, removes all but the <code>Name</code> field from each object, and then
+writes the objects to standard output:
+</p>
+
+{{code "/doc/progs/json5.go" `/package main/` `$`}}
+
+<p>
+Due to the ubiquity of Readers and Writers, these <code>Encoder</code> and
+<code>Decoder</code> types can be used in a broad range of scenarios, such as
+reading and writing to HTTP connections, WebSockets, or files.
+</p>
+
+<p>
+<b>References</b>
+</p>
+
+<p>
+For more information see the <a href="/pkg/encoding/json/">json package documentation</a>. For an example usage of
+json see the source files of the <a href="/pkg/net/rpc/jsonrpc/">jsonrpc package</a>.
+</p>

doc/articles/json_rpc_tale_of_interfaces.html

@@ -0,0 +1,78 @@
+<!--{
+"Title": "JSON-RPC: a tale of interfaces"
+}-->
+
+<p>
+Here we present an example where Go's
+<a href="/doc/effective_go.html#interfaces_and_types">interfaces</a> made it
+easy to refactor some existing code to make it more flexible and extensible.
+Originally, the standard library's <a href="/pkg/net/rpc/">RPC package</a> used
+a custom wire format called <a href="/pkg/encoding/gob/">gob</a>. For a
+particular application, we wanted to use <a href="/pkg/encoding/json/">JSON</a>
+as an alternate wire format.
+</p>
+
+<p>
+We first defined a pair of interfaces to describe the functionality of the
+existing wire format, one for the client, and one for the server (depicted
+below).
+</p>
+
+<pre>
+type ServerCodec interface {
+	ReadRequestHeader(*Request) error
+	ReadRequestBody(interface{}) error
+	WriteResponse(*Response, interface{}) error
+	Close() error
+}
+</pre>
+
+<p>
+On the server side, we then changed two internal function signatures to accept
+the <code>ServerCodec</code> interface instead of our existing
+<code>gob.Encoder</code>. Here's one of them:
+</p>
+
+<pre>
+func sendResponse(sending *sync.Mutex, req *Request,
+	reply interface{}, enc *gob.Encoder, errmsg string)
+</pre>
+
+<p>
+became
+</p>
+
+<pre>
+func sendResponse(sending *sync.Mutex, req *Request,
+		reply interface{}, enc ServerCodec, errmsg string)
+</pre>
+
+<p>
+We then wrote a trivial <code>gobServerCodec</code> wrapper to reproduce the
+original functionality. From there it is simple to build a
+<code>jsonServerCodec</code>.
+</p>
+
+<p>
+After some similar changes to the client side, this was the full extent of the
+work we needed to do on the RPC package. This whole exercise took about 20
+minutes! After tidying up and testing the new code, the
+<a href="http://code.google.com/p/go/source/diff?spec=svn9daf796ebf1cae97b2fcf760a4ab682f1f063f29&r=9daf796ebf1cae97b2fcf760a4ab682f1f063f29&format=side&path=/src/pkg/rpc/server.go">final changeset</a>
+was submitted.
+</p>
+
+<p>
+In an inheritance-oriented language like Java or C++, the obvious path would be
+to generalize the RPC class, and create JsonRPC and GobRPC subclasses. However,
+this approach becomes tricky if you want to make a further generalization
+orthogonal to that hierarchy. (For example, if you were to implement an
+alternate RPC standard). In our Go package, we took a route that is both
+conceptually simpler and requires less code be written or changed.
+</p>
+
+<p>
+A vital quality for any codebase is maintainability. As needs change, it is
+essential to adapt your code easily and cleanly, lest it become unwieldy to work
+with. We believe Go's lightweight, composition-oriented type system provides a
+means of structuring code that scales.
+</p>

doc/articles/laws_of_reflection.html

@@ -0,0 +1,649 @@
+<!--{
+	"Title": "The Laws of Reflection",
+	"Template": true
+}-->
+
+<p>
+Reflection in computing is the
+ability of a program to examine its own structure, particularly
+through types; it's a form of metaprogramming. It's also a great
+source of confusion.
+</p>
+
+<p>
+In this article we attempt to clarify things by explaining how
+reflection works in Go. Each language's reflection model is
+different (and many languages don't support it at all), but
+this article is about Go, so for the rest of this article the word
+"reflection" should be taken to mean "reflection in Go".
+</p>
+
+<p><b>Types and interfaces</b></p>
+
+<p>
+Because reflection builds on the type system, let's start with a
+refresher about types in Go.
+</p>
+
+<p>
+Go is statically typed. Every variable has a static type, that is,
+exactly one type known and fixed at compile time: <code>int</code>,
+<code>float32</code>, <code>*MyType</code>, <code>[]byte</code>,
+and so on. If we declare
+</p>
+
+{{code "/doc/progs/interface.go" `/type MyInt/` `/STOP/`}}
+
+<p>
+then <code>i</code> has type <code>int</code> and <code>j</code>
+has type <code>MyInt</code>. The variables <code>i</code> and
+<code>j</code> have distinct static types and, although they have
+the same underlying type, they cannot be assigned to one another
+without a conversion.
+</p>
+
+<p>
+One important category of type is interface types, which represent
+fixed sets of methods. An interface variable can store any concrete
+(non-interface) value as long as that value implements the
+interface's methods. A well-known pair of examples is
+<code>io.Reader</code> and <code>io.Writer</code>, the types
+<code>Reader</code> and <code>Writer</code> from the
+<a href="/pkg/io/">io package</a>:
+</p>
+
+{{code "/doc/progs/interface.go" `/// Reader/` `/STOP/`}}
+
+<p>
+Any type that implements a <code>Read</code> (or
+<code>Write</code>) method with this signature is said to implement
+<code>io.Reader</code> (or <code>io.Writer</code>). For the
+purposes of this discussion, that means that a variable of type
+<code>io.Reader</code> can hold any value whose type has a
+<code>Read</code> method:
+</p>
+
+{{code "/doc/progs/interface.go" `/func readers/` `/STOP/`}}
+
+<p>
+It's important to be clear that whatever concrete value
+<code>r</code> may hold, <code>r</code>'s type is always
+<code>io.Reader</code>: Go is statically typed and the static type
+of <code>r</code> is <code>io.Reader</code>.</p>
+
+<p>
+An extremely important example of an interface type is the empty
+interface:
+</p>
+
+<pre>
+interface{}
+</pre>
+
+<p>
+It represents the empty set of methods and is satisfied by any
+value at all, since any value has zero or more methods.
+</p>
+
+<p>
+Some people say that Go's interfaces are dynamically typed, but
+that is misleading. They are statically typed: a variable of
+interface type always has the same static type, and even though at
+run time the value stored in the interface variable may change
+type, that value will always satisfy the interface.
+</p>
+
+<p>
+We need to be precise about all this because reflection and
+interfaces are closely related.
+</p>
+
+<p><b>The representation of an interface</b></p>
+
+<p>
+Russ Cox has written a
+<a href="http://research.swtch.com/2009/12/go-data-structures-interfaces.html">detailed blog post</a>
+about the representation of interface values in Go. It's not necessary to
+repeat the full story here, but a simplified summary is in order.
+</p>
+
+<p>
+A variable of interface type stores a pair: the concrete value
+assigned to the variable, and that value's type descriptor.
+To be more precise, the value is the underlying concrete data item
+that implements the interface and the type describes the full type
+of that item. For instance, after
+</p>
+
+{{code "/doc/progs/interface.go" `/func typeAssertions/` `/STOP/`}}
+
+<p>
+<code>r</code> contains, schematically, the (value, type) pair,
+(<code>tty</code>, <code>*os.File</code>). Notice that the type
+<code>*os.File</code> implements methods other than
+<code>Read</code>; even though the interface value provides access
+only to the <code>Read</code> method, the value inside carries all
+the type information about that value. That's why we can do things
+like this:
+</p>
+
+{{code "/doc/progs/interface.go" `/var w io.Writer/` `/STOP/`}}
+
+<p>
+The expression in this assignment is a type assertion; what it
+asserts is that the item inside <code>r</code> also implements
+<code>io.Writer</code>, and so we can assign it to <code>w</code>.
+After the assignment, <code>w</code> will contain the pair
+(<code>tty</code>, <code>*os.File</code>). That's the same pair as
+was held in <code>r</code>. The static type of the interface
+determines what methods may be invoked with an interface variable,
+even though the concrete value inside may have a larger set of
+methods.
+</p>
+
+<p>
+Continuing, we can do this:
+</p>
+
+{{code "/doc/progs/interface.go" `/var empty interface{}/` `/STOP/`}}
+
+<p>
+and our empty interface value <code>e</code> will again contain
+that same pair, (<code>tty</code>, <code>*os.File</code>). That's
+handy: an empty interface can hold any value and contains all the
+information we could ever need about that value.
+</p>
+
+<p>
+(We don't need a type assertion here because it's known statically
+that <code>w</code> satisfies the empty interface. In the example
+where we moved a value from a <code>Reader</code> to a
+<code>Writer</code>, we needed to be explicit and use a type
+assertion because <code>Writer</code>'s methods are not a
+subset of <code>Reader</code>'s.)
+</p>
+
+<p>
+One important detail is that the pair inside an interface always
+has the form (value, concrete type) and cannot have the form
+(value, interface type). Interfaces do not hold interface
+values.
+</p>
+
+<p>
+Now we're ready to reflect.
+</p>
+
+<p><b>The first law of reflection</b></p>
+
+<p><b>1. Reflection goes from interface value to reflection object.</b></p>
+
+<p>
+At the basic level, reflection is just a mechanism to examine the
+type and value pair stored inside an interface variable. To get
+started, there are two types we need to know about in
+<a href="/pkg/reflect/">package reflect</a>:
+<a href="/pkg/reflect/#Type">Type</a> and
+<a href="/pkg/reflect/#Value">Value</a>. Those two types
+give access to the contents of an interface variable, and two
+simple functions, called <code>reflect.TypeOf</code> and
+<code>reflect.ValueOf</code>, retrieve <code>reflect.Type</code>
+and <code>reflect.Value</code> pieces out of an interface value.
+(Also, from the <code>reflect.Value</code> it's easy to get
+to the <code>reflect.Type</code>, but let's keep the
+<code>Value</code> and <code>Type</code> concepts separate for
+now.)
+</p>
+
+<p>
+Let's start with <code>TypeOf</code>:
+</p>
+
+{{code "/doc/progs/interface2.go" `/package main/` `/STOP main/`}}
+
+<p>
+This program prints
+</p>
+
+<pre>
+type: float64
+</pre>
+
+<p>
+You might be wondering where the interface is here, since the program looks
+like it's passing the <code>float64</code> variable <code>x</code>, not an
+interface value, to <code>reflect.TypeOf</code>. But it's there; as
+<a href="/pkg/reflect/#Type.TypeOf">godoc reports</a>, the signature of
+<code>reflect.TypeOf</code> includes an empty interface:
+</p>
+
+<pre>
+// TypeOf returns the reflection Type of the value in the interface{}.
+func TypeOf(i interface{}) Type
+</pre>
+
+<p>
+When we call <code>reflect.TypeOf(x)</code>, <code>x</code> is
+first stored in an empty interface, which is then passed as the
+argument; <code>reflect.TypeOf</code> unpacks that empty interface
+to recover the type information.
+</p>
+
+<p>
+The <code>reflect.ValueOf</code> function, of course, recovers the
+value (from here on we'll elide the boilerplate and focus just on
+the executable code):
+</p>
+
+{{code "/doc/progs/interface2.go" `/START f9/` `/STOP/`}}
+
+<p>
+prints
+</p>
+
+<pre>
+value: &lt;float64 Value&gt;
+</pre>
+
+<p>
+Both <code>reflect.Type</code> and <code>reflect.Value</code> have
+lots of methods to let us examine and manipulate them. One
+important example is that <code>Value</code> has a
+<code>Type</code> method that returns the <code>Type</code> of a
+<code>reflect.Value</code>. Another is that both <code>Type</code>
+and <code>Value</code> have a <code>Kind</code> method that returns
+a constant indicating what sort of item is stored:
+<code>Uint</code>, <code>Float64</code>, <code>Slice</code>, and so
+on. Also methods on <code>Value</code> with names like
+<code>Int</code> and <code>Float</code> let us grab values (as
+<code>int64</code> and <code>float64</code>) stored inside:
+</p>
+
+{{code "/doc/progs/interface2.go" `/START f1/` `/STOP/`}}
+
+<p>
+prints
+</p>
+
+<pre>
+type: float64
+kind is float64: true
+value: 3.4
+</pre>
+
+<p>
+There are also methods like <code>SetInt</code> and
+<code>SetFloat</code> but to use them we need to understand
+settability, the subject of the third law of reflection, discussed
+below.
+</p>
+
+<p>
+The reflection library has a couple of properties worth singling
+out. First, to keep the API simple, the "getter" and "setter"
+methods of <code>Value</code> operate on the largest type that can
+hold the value: <code>int64</code> for all the signed integers, for
+instance. That is, the <code>Int</code> method of
+<code>Value</code> returns an <code>int64</code> and the
+<code>SetInt</code> value takes an <code>int64</code>; it may be
+necessary to convert to the actual type involved:
+</p>
+
+{{code "/doc/progs/interface2.go" `/START f2/` `/STOP/`}}
+
+<p>
+The second property is that the <code>Kind</code> of a reflection
+object describes the underlying type, not the static type. If a
+reflection object contains a value of a user-defined integer type,
+as in
+</p>
+
+{{code "/doc/progs/interface2.go" `/START f3/` `/STOP/`}}
+
+<p>
+the <code>Kind</code> of <code>v</code> is still
+<code>reflect.Int</code>, even though the static type of
+<code>x</code> is <code>MyInt</code>, not <code>int</code>. In
+other words, the <code>Kind</code> cannot discriminate an int from
+a <code>MyInt</code> even though the <code>Type</code> can.
+</p>
+
+<p><b>The second law of reflection</b></p>
+
+<p><b>2. Reflection goes from reflection object to interface
+value.</b></p>
+
+<p>
+Like physical reflection, reflection in Go generates its own
+inverse.
+</p>
+
+<p>
+Given a <code>reflect.Value</code> we can recover an interface
+value using the <code>Interface</code> method; in effect the method
+packs the type and value information back into an interface
+representation and returns the result:
+</p>
+
+<pre>
+// Interface returns v's value as an interface{}.
+func (v Value) Interface() interface{}
+</pre>
+
+<p>
+As a consequence we can say
+</p>
+
+{{code "/doc/progs/interface2.go" `/START f3b/` `/STOP/`}}
+
+<p>
+to print the <code>float64</code> value represented by the
+reflection object <code>v</code>.
+</p>
+
+<p>
+We can do even better, though. The arguments to
+<code>fmt.Println</code>, <code>fmt.Printf</code> and so on are all
+passed as empty interface values, which are then unpacked by the
+<code>fmt</code> package internally just as we have been doing in
+the previous examples. Therefore all it takes to print the contents
+of a <code>reflect.Value</code> correctly is to pass the result of
+the <code>Interface</code> method to the formatted print
+routine:
+</p>
+
+{{code "/doc/progs/interface2.go" `/START f3c/` `/STOP/`}}
+
+<p>
+(Why not <code>fmt.Println(v)</code>? Because <code>v</code> is a
+<code>reflect.Value</code>; we want the concrete value it holds.)
+Since our value is a <code>float64</code>, we can even use a
+floating-point format if we want:
+</p>
+
+{{code "/doc/progs/interface2.go" `/START f3d/` `/STOP/`}}
+
+<p>
+and get in this case
+</p>
+
+<pre>
+3.4e+00
+</pre>
+
+<p>
+Again, there's no need to type-assert the result of
+<code>v.Interface()</code> to <code>float64</code>; the empty
+interface value has the concrete value's type information inside
+and <code>Printf</code> will recover it.
+</p>
+
+<p>
+In short, the <code>Interface</code> method is the inverse of the
+<code>ValueOf</code> function, except that its result is always of
+static type <code>interface{}</code>.
+</p>
+
+<p>
+Reiterating: Reflection goes from interface values to reflection
+objects and back again.
+</p>
+
+<p><b>The third law of reflection</b></p>
+
+<p><b>3. To modify a reflection object, the value must be settable.</b></p>
+
+<p>
+The third law is the most subtle and confusing, but it's easy
+enough to understand if we start from first principles.
+</p>
+
+<p>
+Here is some code that does not work, but is worth studying.
+</p>
+
+{{code "/doc/progs/interface2.go" `/START f4/` `/STOP/`}}
+
+<p>
+If you run this code, it will panic with the cryptic message
+</p>
+
+<pre>
+panic: reflect.Value.SetFloat using unaddressable value
+</pre>
+
+<p>
+The problem is not that the value <code>7.1</code> is not
+addressable; it's that <code>v</code> is not settable. Settability
+is a property of a reflection <code>Value</code>, and not all
+reflection <code>Values</code> have it.
+</p>
+
+<p>
+The <code>CanSet</code> method of <code>Value</code> reports the
+settability of a <code>Value</code>; in our case,
+</p>
+
+{{code "/doc/progs/interface2.go" `/START f5/` `/STOP/`}}
+
+<p>
+prints
+</p>
+
+<pre>
+settability of v: false
+</pre>
+
+<p>
+It is an error to call a <code>Set</code> method on an non-settable
+<code>Value</code>. But what is settability?
+</p>
+
+<p>
+Settability is a bit like addressability, but stricter. It's the
+property that a reflection object can modify the actual storage
+that was used to create the reflection object. Settability is
+determined by whether the reflection object holds the original
+item. When we say
+</p>
+
+{{code "/doc/progs/interface2.go" `/START f6/` `/STOP/`}}
+
+<p>
+we pass a <em>copy</em> of <code>x</code> to
+<code>reflect.ValueOf</code>, so the interface value created as the
+argument to <code>reflect.ValueOf</code> is a <em>copy</em> of
+<code>x</code>, not <code>x</code> itself. Thus, if the
+statement
+</p>
+
+{{code "/doc/progs/interface2.go" `/START f6b/` `/STOP/`}}
+
+<p>
+were allowed to succeed, it would not update <code>x</code>, even
+though <code>v</code> looks like it was created from
+<code>x</code>. Instead, it would update the copy of <code>x</code>
+stored inside the reflection value and <code>x</code> itself would
+be unaffected. That would be confusing and useless, so it is
+illegal, and settability is the property used to avoid this
+issue.
+</p>
+
+<p>
+If this seems bizarre, it's not. It's actually a familiar situation
+in unusual garb. Think of passing <code>x</code> to a
+function:
+</p>
+
+<pre>
+f(x)
+</pre>
+
+<p>
+We would not expect <code>f</code> to be able to modify
+<code>x</code> because we passed a copy of <code>x</code>'s value,
+not <code>x</code> itself. If we want <code>f</code> to modify
+<code>x</code> directly we must pass our function the address of
+<code>x</code> (that is, a pointer to <code>x</code>):</p>
+
+<p>
+<code>f(&amp;x)</code>
+</p>
+
+<p>
+This is straightforward and familiar, and reflection works the same
+way. If we want to modify <code>x</code> by reflection, we must
+give the reflection library a pointer to the value we want to
+modify.
+</p>
+
+<p>
+Let's do that. First we initialize <code>x</code> as usual
+and then create a reflection value that points to it, called
+<code>p</code>.
+</p>
+
+{{code "/doc/progs/interface2.go" `/START f7/` `/STOP/`}}
+
+<p>
+The output so far is
+</p>
+
+<pre>
+type of p: *float64
+settability of p: false
+</pre>
+
+<p>
+The reflection object <code>p</code> isn't settable, but it's not
+<code>p</code> we want to set, it's (in effect) <code>*p</code>. To
+get to what <code>p</code> points to, we call the <code>Elem</code>
+method of <code>Value</code>, which indirects through the pointer,
+and save the result in a reflection <code>Value</code> called
+<code>v</code>:
+</p>
+
+{{code "/doc/progs/interface2.go" `/START f7b/` `/STOP/`}}
+
+<p>
+Now <code>v</code> is a settable reflection object, as the output
+demonstrates,
+</p>
+
+<pre>
+settability of v: true
+</pre>
+
+<p>
+and since it represents <code>x</code>, we are finally able to use
+<code>v.SetFloat</code> to modify the value of
+<code>x</code>:
+</p>
+
+{{code "/doc/progs/interface2.go" `/START f7c/` `/STOP/`}}
+
+<p>
+The output, as expected, is
+</p>
+
+<pre>
+7.1
+7.1
+</pre>
+
+<p>
+Reflection can be hard to understand but it's doing exactly what
+the language does, albeit through reflection <code>Types</code> and
+<code>Values</code> that can disguise what's going on. Just keep in
+mind that reflection Values need the address of something in order
+to modify what they represent.
+</p>
+
+<p><b>Structs</b></p>
+
+<p>
+In our previous example <code>v</code> wasn't a pointer itself, it
+was just derived from one. A common way for this situation to arise
+is when using reflection to modify the fields of a structure. As
+long as we have the address of the structure, we can modify its
+fields.
+</p>
+
+<p>
+Here's a simple example that analyzes a struct value, <code>t</code>. We create
+the reflection object with the address of the struct because we'll want to
+modify it later. Then we set <code>typeOfT</code> to its type and iterate over
+the fields using straightforward method calls
+(see <a href="/pkg/reflect/">package reflect</a> for details).
+Note that we extract the names of the fields from the struct type, but the
+fields themselves are regular <code>reflect.Value</code> objects.
+</p>
+
+{{code "/doc/progs/interface2.go" `/START f8/` `/STOP/`}}
+
+<p>
+The output of this program is
+</p>
+
+<pre>
+0: A int = 23
+1: B string = skidoo
+</pre>
+
+<p>
+There's one more point about settability introduced in
+passing here: the field names of <code>T</code> are upper case
+(exported) because only exported fields of a struct are
+settable.
+</p>
+
+<p>
+Because <code>s</code> contains a settable reflection object, we
+can modify the fields of the structure.
+</p>
+
+{{code "/doc/progs/interface2.go" `/START f8b/` `/STOP/`}}
+
+<p>
+And here's the result:
+</p>
+
+<pre>
+t is now {77 Sunset Strip}
+</pre>
+
+<p>
+If we modified the program so that <code>s</code> was created from
+<code>t</code>, not <code>&amp;t</code>, the calls to
+<code>SetInt</code> and <code>SetString</code> would fail as the
+fields of <code>t</code> would not be settable.
+</p>
+
+<p><b>Conclusion</b></p>
+
+<p>
+Here again are the laws of reflection:
+</p>
+
+<ol>
+<li>Reflection goes from interface value to reflection
+object.</li>
+<li>Reflection goes from reflection object to interface
+value.</li>
+<li>To modify a reflection object, the value must be settable.</li>
+</ol>
+
+<p>
+Once you understand these laws reflection in Go becomes much easier
+to use, although it remains subtle. It's a powerful tool that
+should be used with care and avoided unless strictly
+necessary.
+</p>
+
+<p>
+There's plenty more to reflection that we haven't covered &mdash;
+sending and receiving on channels, allocating memory, using slices
+and maps, calling methods and functions &mdash; but this post is
+long enough. We'll cover some of those topics in a later
+article.
+</p>

doc/articles/slices_usage_and_internals.html

@@ -0,0 +1,438 @@
+<!--{
+	"Title": "Slices: usage and internals",
+	"Template": true
+}-->
+
+<p>
+Go's slice type provides a convenient and efficient means of working with
+sequences of typed data. Slices are analogous to arrays in other languages, but
+have some unusual properties. This article will look at what slices are and how
+they are used.
+</p>
+
+<p>
+<b>Arrays</b>
+</p>
+
+<p>
+The slice type is an abstraction built on top of Go's array type, and so to
+understand slices we must first understand arrays.
+</p>
+
+<p>
+An array type definition specifies a length and an element type. For example,
+the type <code>[4]int</code> represents an array of four integers. An array's
+size is fixed; its length is part of its type (<code>[4]int</code> and
+<code>[5]int</code> are distinct, incompatible types). Arrays can be indexed in
+the usual way, so the expression <code>s[n]</code> accesses the <i>n</i>th
+element:
+</p>
+
+<pre>
+var a [4]int
+a[0] = 1
+i := a[0]
+// i == 1
+</pre>
+
+<p>
+Arrays do not need to be initialized explicitly; the zero value of an array is
+a ready-to-use array whose elements are themselves zeroed:
+</p>
+
+<pre>
+// a[2] == 0, the zero value of the int type
+</pre>
+
+<p>
+The in-memory representation of <code>[4]int</code> is just four integer values laid out sequentially:
+</p>
+
+<p>
+<img src="slice-array.png">
+</p>
+
+<p>
+Go's arrays are values. An array variable denotes the entire array; it is not a
+pointer to the first array element (as would be the case in C).  This means
+that when you assign or pass around an array value you will make a copy of its
+contents. (To avoid the copy you could pass a <i>pointer</i> to the array, but
+then that's a pointer to an array, not an array.) One way to think about arrays
+is as a sort of struct but with indexed rather than named fields: a fixed-size
+composite value.
+</p>
+
+<p>
+An array literal can be specified like so:
+</p>
+
+<pre>
+b := [2]string{"Penn", "Teller"}
+</pre>
+
+<p>
+Or, you can have the compiler count the array elements for you:
+</p>
+
+<pre>
+b := [...]string{"Penn", "Teller"}
+</pre>
+
+<p>
+In both cases, the type of <code>b</code> is <code>[2]string</code>.
+</p>
+
+<p>
+<b>Slices</b>
+</p>
+
+<p>
+Arrays have their place, but they're a bit inflexible, so you don't see them
+too often in Go code. Slices, though, are everywhere. They build on arrays to
+provide great power and convenience.
+</p>
+
+<p>
+The type specification for a slice is <code>[]T</code>, where <code>T</code> is
+the type of the elements of the slice. Unlike an array type, a slice type has
+no specified length.
+</p>
+
+<p>
+A slice literal is declared just like an array literal, except you leave out
+the element count:
+</p>
+
+<pre>
+letters := []string{"a", "b", "c", "d"}
+</pre>
+
+<p>
+A slice can be created with the built-in function called <code>make</code>,
+which has the signature,
+</p>
+
+<pre>
+func make([]T, len, cap) []T
+</pre>
+
+<p>
+where T stands for the element type of the slice to be created. The
+<code>make</code> function takes a type, a length, and an optional capacity.
+When called, <code>make</code> allocates an array and returns a slice that
+refers to that array.
+</p>
+
+<pre>
+var s []byte
+s = make([]byte, 5, 5)
+// s == []byte{0, 0, 0, 0, 0}
+</pre>
+
+<p>
+When the capacity argument is omitted, it defaults to the specified length.
+Here's a more succinct version of the same code:
+</p>
+
+<pre>
+s := make([]byte, 5)
+</pre>
+
+<p>
+The length and capacity of a slice can be inspected using the built-in
+<code>len</code> and <code>cap</code> functions.
+</p>
+
+<pre>
+len(s) == 5
+cap(s) == 5
+</pre>
+
+<p>
+The next two sections discuss the relationship between length and capacity.
+</p>
+
+<p>
+The zero value of a slice is <code>nil</code>. The <code>len</code> and
+<code>cap</code> functions will both return 0 for a nil slice.
+</p>
+
+<p>
+A slice can also be formed by "slicing" an existing slice or array. Slicing is
+done by specifying a half-open range with two indices separated by a colon. For
+example, the expression <code>b[1:4]</code> creates a slice including elements
+1 through 3 of <code>b</code> (the indices of the resulting slice will be 0
+through 2).
+</p>
+
+<pre>
+b := []byte{'g', 'o', 'l', 'a', 'n', 'g'}
+// b[1:4] == []byte{'o', 'l', 'a'}, sharing the same storage as b
+</pre>
+
+<p>
+The start and end indices of a slice expression are optional; they default to zero and the slice's length respectively:
+</p>
+
+<pre>
+// b[:2] == []byte{'g', 'o'}
+// b[2:] == []byte{'l', 'a', 'n', 'g'}
+// b[:] == b
+</pre>
+
+<p>
+This is also the syntax to create a slice given an array:
+</p>
+
+<pre>
+x := [3]string{"Лайка", "Белка", "Стрелка"}
+s := x[:] // a slice referencing the storage of x
+</pre>
+
+<p>
+<b>Slice internals</b>
+</p>
+
+<p>
+A slice is a descriptor of an array segment. It consists of a pointer to the
+array, the length of the segment, and its capacity (the maximum length of the
+segment).
+</p>
+
+<p>
+<img src="slice-struct.png">
+</p>
+
+<p>
+Our variable <code>s</code>, created earlier by <code>make([]byte, 5)</code>,
+is structured like this:
+</p>
+
+<p>
+<img src="slice-1.png">
+</p>
+
+<p>
+The length is the number of elements referred to by the slice. The capacity is
+the number of elements in the underlying array (beginning at the element
+referred to by the slice pointer). The distinction between length and capacity
+will be made clear as we walk through the next few examples.
+</p>
+
+<p>
+As we slice <code>s</code>, observe the changes in the slice data structure and
+their relation to the underlying array:
+</p>
+
+<pre>
+s = s[2:4]
+</pre>
+
+<p>
+<img src="slice-2.png">
+</p>
+
+<p>
+Slicing does not copy the slice's data. It creates a new slice value that
+points to the original array. This makes slice operations as efficient as
+manipulating array indices. Therefore, modifying the <i>elements</i> (not the
+slice itself) of a re-slice modifies the elements of the original slice:
+</p>
+
+<pre>
+d := []byte{'r', 'o', 'a', 'd'}
+e := d[2:] 
+// e == []byte{'a', 'd'}
+e[1] == 'm'
+// e == []byte{'a', 'm'}
+// d == []byte{'r', 'o', 'a', 'm'}
+</pre>
+
+<p>
+Earlier we sliced <code>s</code> to a length shorter than its capacity. We can
+grow s to its capacity by slicing it again:
+</p>
+
+<pre>
+s = s[:cap(s)]
+</pre>
+
+<p>
+<img src="slice-3.png">
+</p>
+
+<p>
+A slice cannot be grown beyond its capacity. Attempting to do so will cause a
+runtime panic, just as when indexing outside the bounds of a slice or array.
+Similarly, slices cannot be re-sliced below zero to access earlier elements in
+the array.
+</p>
+
+<p>
+<b>Growing slices (the copy and append functions)</b>
+</p>
+
+<p>
+To increase the capacity of a slice one must create a new, larger slice and
+copy the contents of the original slice into it. This technique is how dynamic
+array implementations from other languages work behind the scenes. The next
+example doubles the capacity of <code>s</code> by making a new slice,
+<code>t</code>, copying the contents of <code>s</code> into <code>t</code>, and
+then assigning the slice value <code>t</code> to <code>s</code>:
+</p>
+
+<pre>
+t := make([]byte, len(s), (cap(s)+1)*2) // +1 in case cap(s) == 0
+for i := range s {
+        t[i] = s[i]
+}
+s = t
+</pre>
+
+<p>
+The looping piece of this common operation is made easier by the built-in copy
+function. As the name suggests, copy copies data from a source slice to a
+destination slice. It returns the number of elements copied.
+</p>
+
+<pre>
+func copy(dst, src []T) int
+</pre>
+
+<p>
+The <code>copy</code> function supports copying between slices of different
+lengths (it will copy only up to the smaller number of elements). In addition,
+<code>copy</code> can handle source and destination slices that share the same
+underlying array, handling overlapping slices correctly.
+</p>
+
+<p>
+Using <code>copy</code>, we can simplify the code snippet above:
+</p>
+
+<pre>
+t := make([]byte, len(s), (cap(s)+1)*2)
+copy(t, s)
+s = t
+</pre>
+
+<p>
+A common operation is to append data to the end of a slice. This function
+appends byte elements to a slice of bytes, growing the slice if necessary, and
+returns the updated slice value:
+</p>
+
+{{code "/doc/progs/slices.go" `/AppendByte/` `/STOP/`}}
+
+<p>
+One could use <code>AppendByte</code> like this:
+</p>
+
+<pre>
+p := []byte{2, 3, 5}
+p = AppendByte(p, 7, 11, 13)
+// p == []byte{2, 3, 5, 7, 11, 13}
+</pre>
+
+<p>
+Functions like <code>AppendByte</code> are useful because they offer complete
+control over the way the slice is grown. Depending on the characteristics of
+the program, it may be desirable to allocate in smaller or larger chunks, or to
+put a ceiling on the size of a reallocation.
+</p>
+
+<p>
+But most programs don't need complete control, so Go provides a built-in
+<code>append</code> function that's good for most purposes; it has the
+signature
+</p>
+
+<pre>
+func append(s []T, x ...T) []T 
+</pre>
+
+<p>
+The <code>append</code> function appends the elements <code>x</code> to the end
+of the slice <code>s</code>, and grows the slice if a greater capacity is
+needed.
+</p>
+
+<pre>
+a := make([]int, 1)
+// a == []int{0}
+a = append(a, 1, 2, 3)
+// a == []int{0, 1, 2, 3}
+</pre>
+
+<p>
+To append one slice to another, use <code>...</code> to expand the second
+argument to a list of arguments.
+</p>
+
+<pre>
+a := []string{"John", "Paul"}
+b := []string{"George", "Ringo", "Pete"}
+a = append(a, b...) // equivalent to "append(a, b[0], b[1], b[2])"
+// a == []string{"John", "Paul", "George", "Ringo", "Pete"}
+</pre>
+
+<p>
+Since the zero value of a slice (<code>nil</code>) acts like a zero-length
+slice, you can declare a slice variable and then append to it in a loop:
+</p>
+
+{{code "/doc/progs/slices.go" `/Filter/` `/STOP/`}}
+
+<p>
+<b>A possible "gotcha"</b>
+</p>
+
+<p>
+As mentioned earlier, re-slicing a slice doesn't make a copy of the underlying
+array. The full array will be kept in memory until it is no longer referenced.
+Occasionally this can cause the program to hold all the data in memory when
+only a small piece of it is needed.
+</p>
+
+<p>
+For example, this <code>FindDigits</code> function loads a file into memory and
+searches it for the first group of consecutive numeric digits, returning them
+as a new slice.
+</p>
+
+{{code "/doc/progs/slices.go" `/digit/` `/STOP/`}}
+
+<p>
+This code behaves as advertised, but the returned <code>[]byte</code> points
+into an array containing the entire file. Since the slice references the
+original array, as long as the slice is kept around the garbage collector can't
+release the array; the few useful bytes of the file keep the entire contents in
+memory.
+</p>
+
+<p>
+To fix this problem one can copy the interesting data to a new slice before
+returning it:
+</p>
+
+{{code "/doc/progs/slices.go" `/CopyDigits/` `/STOP/`}}
+
+<p>
+A more concise version of this function could be constructed by using
+<code>append</code>. This is left as an exercise for the reader.
+</p>
+
+<p>
+<b>Further Reading</b>
+</p>
+
+<p>
+<a href="/doc/effective_go.html">Effective Go</a> contains an
+in-depth treatment of <a href="/doc/effective_go.html#slices">slices</a>
+and <a href="/doc/effective_go.html#arrays">arrays</a>, 
+and the Go <a href="/doc/go_spec.html">language specification</a>
+defines <a href="/doc/go_spec.html#Slice_types">slices</a> and their
+<a href="/doc/go_spec.html#Length_and_capacity">associated</a>
+<a href="/doc/go_spec.html#Making_slices_maps_and_channels">helper</a>
+<a href="/doc/go_spec.html#Appending_and_copying_slices">functions</a>.
+</p>

doc/articles/wiki/Makefile

@@ -2,24 +2,19 @@
 # Use of this source code is governed by a BSD-style
 # license that can be found in the LICENSE file.
 
-include ../../../src/Make.inc
-
 all: index.html
 
-include ../../../src/Make.common
+CLEANFILES:=srcextract.bin htmlify.bin get.bin
 
-CLEANFILES+=index.html srcextract.bin htmlify.bin get.bin
-
-index.html: srcextract.bin htmlify.bin
+index.html: wiki.html srcextract.bin htmlify.bin
 	PATH=.:$$PATH awk '/^!/{system(substr($$0,2)); next} {print}' < wiki.html | tr -d '\r' > index.html
 
 test: get.bin
 	bash ./test.sh
 	rm -f get.6 get.bin
 
-%.bin: %.$O
-	$(LD) -o $@ $<
-
-%.$O: %.go
-	$(GC) $*.go
+%.bin: %.go
+	go build -o $@ $^
 
+clean:
+	rm -f $(CLEANFILES)

doc/articles/wiki/final-noclosure.go

@@ -1,11 +1,15 @@
+// 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.
+
 package main
 
 import (
-	"http"
+	"errors"
+	"html/template"
 	"io/ioutil"
-	"os"
+	"net/http"
 	"regexp"
-	"template"
 )
 
 type Page struct {
@@ -13,12 +17,12 @@ type Page struct {
 	Body  []byte
 }
 
-func (p *Page) save() os.Error {
+func (p *Page) save() error {
 	filename := p.Title + ".txt"
 	return ioutil.WriteFile(filename, p.Body, 0600)
 }
 
-func loadPage(title string) (*Page, os.Error) {
+func loadPage(title string) (*Page, error) {
 	filename := title + ".txt"
 	body, err := ioutil.ReadFile(filename)
 	if err != nil {
@@ -61,21 +65,21 @@ func saveHandler(w http.ResponseWriter, r *http.Request) {
 	p := &Page{Title: title, Body: []byte(body)}
 	err = p.save()
 	if err != nil {
-		http.Error(w, err.String(), http.StatusInternalServerError)
+		http.Error(w, err.Error(), http.StatusInternalServerError)
 		return
 	}
 	http.Redirect(w, r, "/view/"+title, http.StatusFound)
 }
 
 func renderTemplate(w http.ResponseWriter, tmpl string, p *Page) {
-	t, err := template.ParseFile(tmpl+".html")
+	t, err := template.ParseFiles(tmpl + ".html")
 	if err != nil {
-		http.Error(w, err.String(), http.StatusInternalServerError)
+		http.Error(w, err.Error(), http.StatusInternalServerError)
 		return
 	}
 	err = t.Execute(w, p)
 	if err != nil {
-		http.Error(w, err.String(), http.StatusInternalServerError)
+		http.Error(w, err.Error(), http.StatusInternalServerError)
 	}
 }
 
@@ -83,11 +87,11 @@ const lenPath = len("/view/")
 
 var titleValidator = regexp.MustCompile("^[a-zA-Z0-9]+$")
 
-func getTitle(w http.ResponseWriter, r *http.Request) (title string, err os.Error) {
+func getTitle(w http.ResponseWriter, r *http.Request) (title string, err error) {
 	title = r.URL.Path[lenPath:]
 	if !titleValidator.MatchString(title) {
 		http.NotFound(w, r)
-		err = os.NewError("Invalid Page Title")
+		err = errors.New("Invalid Page Title")
 	}
 	return
 }

doc/articles/wiki/final-noerror.go

@@ -1,10 +1,13 @@
+// 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.
+
 package main
 
 import (
-	"http"
+	"html/template"
 	"io/ioutil"
-	"os"
-	"template"
+	"net/http"
 )
 
 type Page struct {
@@ -12,12 +15,12 @@ type Page struct {
 	Body  []byte
 }
 
-func (p *Page) save() os.Error {
+func (p *Page) save() error {
 	filename := p.Title + ".txt"
 	return ioutil.WriteFile(filename, p.Body, 0600)
 }
 
-func loadPage(title string) (*Page, os.Error) {
+func loadPage(title string) (*Page, error) {
 	filename := title + ".txt"
 	body, err := ioutil.ReadFile(filename)
 	if err != nil {
@@ -34,14 +37,14 @@ func editHandler(w http.ResponseWriter, r *http.Request) {
 	if err != nil {
 		p = &Page{Title: title}
 	}
-	t, _ := template.ParseFile("edit.html")
+	t, _ := template.ParseFiles("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")
+	t, _ := template.ParseFiles("view.html")
 	t.Execute(w, p)
 }
 

doc/articles/wiki/final-parsetemplate.go

@@ -1,11 +1,14 @@
+// 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.
+
 package main
 
 import (
-	"http"
+	"html/template"
 	"io/ioutil"
-	"os"
+	"net/http"
 	"regexp"
-	"template"
 )
 
 type Page struct {
@@ -13,12 +16,12 @@ type Page struct {
 	Body  []byte
 }
 
-func (p *Page) save() os.Error {
+func (p *Page) save() error {
 	filename := p.Title + ".txt"
 	return ioutil.WriteFile(filename, p.Body, 0600)
 }
 
-func loadPage(title string) (*Page, os.Error) {
+func loadPage(title string) (*Page, error) {
 	filename := title + ".txt"
 	body, err := ioutil.ReadFile(filename)
 	if err != nil {
@@ -49,21 +52,21 @@ func saveHandler(w http.ResponseWriter, r *http.Request, title string) {
 	p := &Page{Title: title, Body: []byte(body)}
 	err := p.save()
 	if err != nil {
-		http.Error(w, err.String(), http.StatusInternalServerError)
+		http.Error(w, err.Error(), http.StatusInternalServerError)
 		return
 	}
 	http.Redirect(w, r, "/view/"+title, http.StatusFound)
 }
 
 func renderTemplate(w http.ResponseWriter, tmpl string, p *Page) {
-	t, err := template.ParseFile(tmpl+".html", nil)
+	t, err := template.ParseFiles(tmpl + ".html")
 	if err != nil {
-		http.Error(w, err.String(), http.StatusInternalServerError)
+		http.Error(w, err.Error(), http.StatusInternalServerError)
 		return
 	}
 	err = t.Execute(w, p)
 	if err != nil {
-		http.Error(w, err.String(), http.StatusInternalServerError)
+		http.Error(w, err.Error(), http.StatusInternalServerError)
 	}
 }
 

doc/articles/wiki/final-template.go

@@ -1,10 +1,13 @@
+// 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.
+
 package main
 
 import (
-	"http"
+	"html/template"
 	"io/ioutil"
-	"os"
-	"template"
+	"net/http"
 )
 
 type Page struct {
@@ -12,12 +15,12 @@ type Page struct {
 	Body  []byte
 }
 
-func (p *Page) save() os.Error {
+func (p *Page) save() error {
 	filename := p.Title + ".txt"
 	return ioutil.WriteFile(filename, p.Body, 0600)
 }
 
-func loadPage(title string) (*Page, os.Error) {
+func loadPage(title string) (*Page, error) {
 	filename := title + ".txt"
 	body, err := ioutil.ReadFile(filename)
 	if err != nil {
@@ -52,7 +55,7 @@ func saveHandler(w http.ResponseWriter, r *http.Request) {
 }
 
 func renderTemplate(w http.ResponseWriter, tmpl string, p *Page) {
-	t, _ := template.ParseFile(tmpl+".html", nil)
+	t, _ := template.ParseFiles(tmpl + ".html")
 	t.Execute(w, p)
 }
 

doc/articles/wiki/final.go

@@ -1,11 +1,14 @@
+// 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.
+
 package main
 
 import (
-	"http"
+	"html/template"
 	"io/ioutil"
-	"os"
+	"net/http"
 	"regexp"
-	"template"
 )
 
 type Page struct {
@@ -13,12 +16,12 @@ type Page struct {
 	Body  []byte
 }
 
-func (p *Page) save() os.Error {
+func (p *Page) save() error {
 	filename := p.Title + ".txt"
 	return ioutil.WriteFile(filename, p.Body, 0600)
 }
 
-func loadPage(title string) (*Page, os.Error) {
+func loadPage(title string) (*Page, error) {
 	filename := title + ".txt"
 	body, err := ioutil.ReadFile(filename)
 	if err != nil {
@@ -49,25 +52,18 @@ func saveHandler(w http.ResponseWriter, r *http.Request, title string) {
 	p := &Page{Title: title, Body: []byte(body)}
 	err := p.save()
 	if err != nil {
-		http.Error(w, err.String(), http.StatusInternalServerError)
+		http.Error(w, err.Error(), http.StatusInternalServerError)
 		return
 	}
 	http.Redirect(w, r, "/view/"+title, http.StatusFound)
 }
 
-var templates = make(map[string]*template.Template)
-
-func init() {
-	for _, tmpl := range []string{"edit", "view"} {
-		t := template.Must(template.ParseFile(tmpl+".html"))
-		templates[tmpl] = t
-	}
-}
+var templates = template.Must(template.ParseFiles("edit.html", "view.html"))
 
 func renderTemplate(w http.ResponseWriter, tmpl string, p *Page) {
-	err := templates[tmpl].Execute(w, p)
+	err := templates.ExecuteTemplate(w, tmpl+".html", p)
 	if err != nil {
-		http.Error(w, err.String(), http.StatusInternalServerError)
+		http.Error(w, err.Error(), http.StatusInternalServerError)
 	}
 }
 

doc/articles/wiki/get.go

@@ -1,12 +1,16 @@
+// Copyright 2011 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
 package main
 
 import (
-	"http"
 	"flag"
 	"fmt"
 	"io"
 	"log"
 	"net"
+	"net/http"
 	"os"
 	"strings"
 )
@@ -32,7 +36,7 @@ func main() {
 		log.Fatal("no url supplied")
 	}
 	var r *http.Response
-	var err os.Error
+	var err error
 	if *post != "" {
 		b := strings.NewReader(*post)
 		r, err = http.Post(url, "application/x-www-form-urlencoded", b)

doc/articles/wiki/htmlify.go

@@ -2,12 +2,15 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// const and var declarations
+package main
 
-package P1
-
-const (
-	c1 = 0
-	c2     int = 0
-	c3, c4 = 0
+import (
+	"io/ioutil"
+	"os"
+	"text/template"
 )
+
+func main() {
+	b, _ := ioutil.ReadAll(os.Stdin)
+	template.HTMLEscape(os.Stdout, b)
+}

doc/articles/wiki/http-sample.go

@@ -2,7 +2,7 @@ package main
 
 import (
 	"fmt"
-	"http"
+	"net/http"
 )
 
 func handler(w http.ResponseWriter, r *http.Request) {

doc/articles/wiki/index.html

@@ -1,13 +1,17 @@
-<!-- Codelab: Writing Web Applications -->
+<!--{
+	"Title": "Writing Web Applications",
+	"Template": true
+}-->
+
 <h2>Introduction</h2>
 
 <p>
-Covered in this codelab:
+Covered in this tutorial:
 </p>
 <ul>
 <li>Creating a data structure with load and save methods</li>
-<li>Using the <code>http</code> package to build web applications
-<li>Using the <code>template</code> package to process HTML templates</li>
+<li>Using the <code>net/http</code> package to build web applications
+<li>Using the <code>html/template</code> package to process HTML templates</li>
 <li>Using the <code>regexp</code> package to validate user input</li>
 <li>Using closures</li>
 </ul>
@@ -18,30 +22,27 @@ Assumed knowledge:
 <ul>
 <li>Programming experience</li>
 <li>Understanding of basic web technologies (HTTP, HTML)</li>
-<li>Some UNIX command-line knowledge</li>
+<li>Some UNIX/DOS command-line knowledge</li>
 </ul>
 
 <h2>Getting Started</h2>
 
 <p>
-At present, you need to have a Linux, OS X, or FreeBSD machine to run Go. If
-you don't have access to one, you could set up a Linux Virtual Machine (using 
-<a href="http://www.virtualbox.org/">VirtualBox</a> or similar) or a
-<a href="http://www.google.com/search?q=virtual+private+server">Virtual 
-Private Server</a>.
+At present, you need to have a FreeBSD, Linux, OS X, or Windows machine to run Go.
+We will use <code>$</code> to represent the command prompt.
 </p>
 
 <p>
-Install Go (see the <a href="http://golang.org/doc/install.html">Installation Instructions</a>).
+Install Go (see the <a href="/doc/install">Installation Instructions</a>).
 </p>
 
 <p>
-Make a new directory for this codelab and cd to it:
+Make a new directory for this tutorial inside your <code>GOPATH</code> and cd to it:
 </p>
 
 <pre>
-$ mkdir ~/gowiki
-$ cd ~/gowiki
+$ mkdir gowiki
+$ cd gowiki
 </pre>
 
 <p>
@@ -55,15 +56,13 @@ package main
 import (
 	"fmt"
 	"io/ioutil"
-	"os"
 )
 </pre>
 
 <p>
-We import the <code>fmt</code>, <code>ioutil</code> and <code>os</code>
-packages from the Go standard library. Later, as we implement additional
-functionality, we will add more packages to this <code>import</code>
-declaration.
+We import the <code>fmt</code> and <code>ioutil</code> packages from the Go 
+standard library. Later, as we implement additional functionality, we will 
+add more packages to this <code>import</code> declaration.
 </p>
 
 <h2>Data Structures</h2>
@@ -75,14 +74,12 @@ Here, we define <code>Page</code> as a struct with two fields representing
 the title and body.
 </p>
 
-<pre>
-!srcextract.bin -src=part1.go -name=Page
-</pre>
+{{code "doc/articles/wiki/part1.go" `/^type Page/` `/}/`}}
 
 <p>
 The type <code>[]byte</code> means "a <code>byte</code> slice". 
-(See <a href="http://golang.org/doc/effective_go.html#slices">Effective Go</a> 
-for more on slices.)  
+(See <a href="/doc/articles/slices_usage_and_internals.html">Slices: usage and
+internals</a> for more on slices.)
 The <code>Body</code> element is a <code>[]byte</code> rather than
 <code>string</code> because that is the type expected by the <code>io</code>
 libraries we will use, as you'll see below.
@@ -94,14 +91,12 @@ But what about persistent storage? We can address that by creating a
 <code>save</code> method on <code>Page</code>:
 </p>
 
-<pre>
-!srcextract.bin -src=part1.go -name=save
-</pre>
+{{code "doc/articles/wiki/part1.go" `/^func.*Page.*save/` `/}/`}}
 
 <p>
 This method's signature reads: "This is a method named <code>save</code> that
 takes as its receiver <code>p</code>, a pointer to <code>Page</code> . It takes
-no parameters, and returns a value of type <code>os.Error</code>." 
+no parameters, and returns a value of type <code>error</code>." 
 </p>
 
 <p>
@@ -110,7 +105,7 @@ file. For simplicity, we will use the <code>Title</code> as the file name.
 </p>
 
 <p>
-The <code>save</code> method returns an <code>os.Error</code> value because
+The <code>save</code> method returns an <code>error</code> value because
 that is the return type of <code>WriteFile</code> (a standard library function
 that writes a byte slice to a file).  The <code>save</code> method returns the
 error value, to let the application handle it should anything go wrong while
@@ -130,9 +125,7 @@ read-write permissions for the current user only. (See the Unix man page
 We will want to load pages, too:
 </p>
 
-<pre>
-!srcextract.bin -src=part1-noerror.go -name=loadPage
-</pre>
+{{code "doc/articles/wiki/part1-noerror.go" `/^func loadPage/` `/^}/`}}
 
 <p>
 The function <code>loadPage</code> constructs the file name from
@@ -142,7 +135,7 @@ The function <code>loadPage</code> constructs the file name from
 
 <p>
 Functions can return multiple values. The standard library function 
-<code>io.ReadFile</code> returns <code>[]byte</code> and <code>os.Error</code>. 
+<code>io.ReadFile</code> returns <code>[]byte</code> and <code>error</code>. 
 In <code>loadPage</code>, error isn't being handled yet; the "blank identifier"
 represented by the underscore (<code>_</code>) symbol is used to throw away the
 error return value (in essence, assigning the value to nothing). 
@@ -151,19 +144,16 @@ error return value (in essence, assigning the value to nothing).
 <p>
 But what happens if <code>ReadFile</code> encounters an error?  For example,
 the file might not exist. We should not ignore such errors.  Let's modify the
-function to return <code>*Page</code> and <code>os.Error</code>.
+function to return <code>*Page</code> and <code>error</code>.
 </p>
 
-<pre>
-!srcextract.bin -src=part1.go -name=loadPage
-</pre>
+{{code "doc/articles/wiki/part1.go" `/^func loadPage/` `/^}/`}}
 
 <p>
 Callers of this function can now check the second parameter; if it is
 <code>nil</code> then it has successfully loaded a Page. If not, it will be an
-<code>os.Error</code> that can be handled by the caller (see the <a
-href="http://golang.org/pkg/os/#Error">os package documentation</a> for 
-details).
+<code>error</code> that can be handled by the caller (see the 
+<a href="/ref/spec#Errors">language specification</a> for details).
 </p>
 
 <p>
@@ -172,9 +162,7 @@ load from a file. Let's write a <code>main</code> function to test what we've
 written:
 </p>
 
-<pre>
-!srcextract.bin -src=part1.go -name=main
-</pre>
+{{code "doc/articles/wiki/part1.go" `/^func main/` `/^}/`}}
 
 <p>
 After compiling and executing this code, a file named <code>TestPage.txt</code>
@@ -188,31 +176,27 @@ You can compile and run the program like this:
 </p>
 
 <pre>
-$ 8g wiki.go
-$ 8l wiki.8
-$ ./8.out
+$ go build wiki.go
+$ ./wiki
 This is a sample page.
 </pre>
 
 <p>
-(The <code>8g</code> and <code>8l</code> commands are applicable to
-<code>GOARCH=386</code>. If you're on an <code>amd64</code> system,
-substitute 6's for the 8's.)
+(If you're using Windows you must type "<code>wiki</code>" without the 
+"<code>./</code>" to run the program.)
 </p>
 
 <p>
 <a href="part1.go">Click here to view the code we've written so far.</a>
 </p>
 
-<h2>Introducing the <code>http</code> package (an interlude)</h2>
+<h2>Introducing the <code>net/http</code> package (an interlude)</h2>
 
 <p>
 Here's a full working example of a simple web server:
 </p>
 
-<pre>
-!htmlify.bin < http-sample.go
-</pre>
+{{code "doc/articles/wiki/http-sample.go"}}
 
 <p>
 The <code>main</code> function begins with a call to 
@@ -256,18 +240,17 @@ the program would present a page containing:
 </p>
 <pre>Hi there, I love monkeys!</pre>
 
-<h2>Using <code>http</code> to serve wiki pages</h2>
+<h2>Using <code>net/http</code> to serve wiki pages</h2>
 
 <p>
-To use the <code>http</code> package, it must be imported:
+To use the <code>net/http</code> package, it must be imported:
 </p>
 
 <pre>
 import (
 	"fmt"
-	<b>"http"</b>
+	<b>"net/http"</b>
 	"io/ioutil"
-	"os"
 )
 </pre>
 
@@ -275,11 +258,9 @@ import (
 Let's create a handler to view a wiki page: 
 </p>
 
-<pre>
-!srcextract.bin -src=part2.go -name=lenPath
+{{code "doc/articles/wiki/part2.go" `/^const lenPath/`}}
 
-!srcextract.bin -src=part2.go -name=viewHandler
-</pre>
+{{code "doc/articles/wiki/part2.go" `/^func viewHandler/` `/^}/`}}
 
 <p>
 First, this function extracts the page title from <code>r.URL.Path</code>,
@@ -297,7 +278,7 @@ HTML, and writes it to <code>w</code>, the <code>http.ResponseWriter</code>.
 </p>
 
 <p>
-Again, note the use of <code>_</code> to ignore the <code>os.Error</code> 
+Again, note the use of <code>_</code> to ignore the <code>error</code> 
 return value from <code>loadPage</code>. This is done here for simplicity
 and generally considered bad practice. We will attend to this later.
 </p>
@@ -308,9 +289,7 @@ initializes <code>http</code> using the <code>viewHandler</code> to handle
 any requests under the path <code>/view/</code>.
 </p>
 
-<pre>
-!srcextract.bin -src=part2.go -name=main
-</pre>
+{{code "doc/articles/wiki/part2.go" `/^func main/` `/^}/`}}
 
 <p>
 <a href="part2.go">Click here to view the code we've written so far.</a>
@@ -318,14 +297,17 @@ any requests under the path <code>/view/</code>.
 
 <p>
 Let's create some page data (as <code>test.txt</code>), compile our code, and
-try serving a wiki page:
+try serving a wiki page.
+</p>
+
+<p>
+Open <code>test.txt</code> file in your editor, and save the string "Hello world" (without quotes)
+in it.
 </p>
 
 <pre>
-$ echo "Hello world" &gt; test.txt
-$ 8g wiki.go
-$ 8l wiki.8
-$ ./8.out
+$ go build wiki.go
+$ ./wiki
 </pre>
 
 <p>
@@ -347,9 +329,7 @@ form.
 First, we add them to <code>main()</code>: 
 </p>
 
-<pre>
-!srcextract.bin -src=final-noclosure.go -name=main
-</pre>
+{{code "doc/articles/wiki/final-noclosure.go" `/^func main/` `/^}/`}}
 
 <p>
 The function <code>editHandler</code> loads the page 
@@ -357,28 +337,24 @@ The function <code>editHandler</code> loads the page
 and displays an HTML form.
 </p>
 
-<pre>
-!srcextract.bin -src=notemplate.go -name=editHandler
-</pre>
+{{code "doc/articles/wiki/notemplate.go" `/^func editHandler/` `/^}/`}}
 
 <p>
 This function will work fine, but all that hard-coded HTML is ugly.
 Of course, there is a better way.
 </p>
  
-<h2>The <code>template</code> package</h2>
+<h2>The <code>html/template</code> package</h2>
 
 <p>
-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.
+The <code>html/template</code> package is part of the Go standard library.
+We can use <code>html/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.
 </p>
 
 <p>
-First, we must add <code>template</code> to the list of imports:
+First, we must add <code>html/template</code> to the list of imports:
 </p>
 
 <pre>
@@ -386,7 +362,7 @@ import (
 	"http"
 	"io/ioutil"
 	"os"
-	<b>"template"</b>
+	<b>"html/template"</b>
 )
 </pre>
 
@@ -395,21 +371,17 @@ Let's create a template file containing the HTML form.
 Open a new file named <code>edit.html</code>, and add the following lines:
 </p>
 
-<pre>
-!htmlify.bin < edit.html
-</pre>
+{{code "doc/articles/wiki/edit.html"}}
 
 <p>
 Modify <code>editHandler</code> to use the template, instead of the hard-coded
 HTML:
 </p>
 
-<pre>
-!srcextract.bin -src=final-noerror.go -name=editHandler
-</pre>
+{{code "doc/articles/wiki/final-noerror.go" `/^func editHandler/` `/^}/`}}
 
 <p>
-The function <code>template.ParseFile</code> will read the contents of 
+The function <code>template.ParseFiles</code> will read the contents of 
 <code>edit.html</code> and return a <code>*template.Template</code>. 
 </p>
 
@@ -441,17 +413,13 @@ While we're working with templates, let's create a template for our
 <code>viewHandler</code> called <code>view.html</code>:
 </p>
 
-<pre>
-!htmlify.bin < view.html
-</pre>
+{{code "doc/articles/wiki/view.html"}}
 
 <p>
 Modify <code>viewHandler</code> accordingly:
 </p>
 
-<pre>
-!srcextract.bin -src=final-noerror.go -name=viewHandler
-</pre>
+{{code "doc/articles/wiki/final-noerror.go" `/^func viewHandler/` `/^}/`}}
 
 <p>
 Notice that we've used almost exactly the same templating code in both
@@ -459,13 +427,9 @@ handlers. Let's remove this duplication by moving the templating code
 to its own function:
 </p>
 
-<pre>
-!srcextract.bin -src=final-template.go -name=viewHandler
-
-!srcextract.bin -src=final-template.go -name=editHandler
-
-!srcextract.bin -src=final-template.go -name=renderTemplate
-</pre>
+{{code "doc/articles/wiki/final-template.go" `/^func viewHandler/` `/^}/`}}
+{{code "doc/articles/wiki/final-template.go" `/^func editHandler/` `/^}/`}}
+{{code "doc/articles/wiki/final-template.go" `/^func renderTemplate/` `/^}/`}}
 
 <p>
 The handlers are now shorter and simpler. 
@@ -474,15 +438,14 @@ The handlers are now shorter and simpler.
 <h2>Handling non-existent pages</h2>
 
 <p>
-What if you visit <code>/view/APageThatDoesntExist</code>? The program will 
-crash. This is because it ignores the error return value from
-<code>loadPage</code>. Instead, if the requested Page doesn't exist, it should 
-redirect the client to the edit Page so the content may be created:
+What if you visit <a href="http://localhost:8080/view/APageThatDoesntExist">
+<code>/view/APageThatDoesntExist</code></a>? The program will crash. This is 
+because it ignores the error return value from <code>loadPage</code>. Instead,
+if the requested Page doesn't exist, it should redirect the client to the edit
+Page so the content may be created:
 </p>
 
-<pre>
-!srcextract.bin -src=final-noclosure.go -name=viewHandler
-</pre>
+{{code "doc/articles/wiki/final-noclosure.go" `/^func viewHandler/` `/^}/`}}
 
 <p>
 The <code>http.Redirect</code> function adds an HTTP status code of 
@@ -496,9 +459,7 @@ header to the HTTP response.
 The function <code>saveHandler</code> will handle the form submission. 
 </p>
 
-<pre>
-!srcextract.bin -src=final-template.go -name=saveHandler
-</pre>
+{{code "doc/articles/wiki/final-template.go" `/^func saveHandler/` `/^}/`}}
 
 <p>
 The page title (provided in the URL) and the form's only field, 
@@ -528,9 +489,7 @@ function and the user will be notified.
 First, let's handle the errors in <code>renderTemplate</code>:
 </p>
 
-<pre>
-!srcextract.bin -src=final-parsetemplate.go -name=renderTemplate
-</pre>
+{{code "doc/articles/wiki/final-parsetemplate.go" `/^func renderTemplate/` `/^}/`}}
 
 <p>
 The <code>http.Error</code> function sends a specified HTTP response code 
@@ -542,9 +501,7 @@ Already the decision to put this in a separate function is paying off.
 Now let's fix up <code>saveHandler</code>:
 </p>
 
-<pre>
-!srcextract.bin -src=final-noclosure.go -name=saveHandler
-</pre>
+{{code "doc/articles/wiki/final-noclosure.go" `/^func saveHandler/` `/^}/`}}
 
 <p>
 Any errors that occur during <code>p.save()</code> will be reported 
@@ -555,35 +512,28 @@ to the user.
 
 <p>
 There is an inefficiency in this code: <code>renderTemplate</code> calls 
-<code>ParseFile</code> every time a page is rendered. 
-A better approach would be to call <code>ParseFile</code> once for each 
-template at program initialization, and store the resultant 
-<code>*Template</code> values in a data structure for later use.
+<code>ParseFiles</code> every time a page is rendered. 
+A better approach would be to call <code>ParseFiles</code> once at program
+initialization, parsing all templates into a single <code>*Template</code>.
+Then we can use the
+<a href="/pkg/html/template/#Template.ExecuteTemplate"><code>ExecuteTemplate</code></a>
+method to render a specific template.
 </p>
 
 <p>
-First we create a global map named <code>templates</code> in which to store 
-our <code>*Template</code> values, keyed by <code>string</code> 
-(the template name):
+First we create a global variable named <code>templates</code>, and initialize
+it with <code>ParseFiles</code>.
 </p>
 
-<pre>
-!srcextract.bin -src=final.go -name=templates
-</pre>
+{{code "doc/articles/wiki/final.go" `/var templates/`}}
 
 <p>
-Then we create an <code>init</code> function, which will be called before
-<code>main</code> at program initialization. The function
-<code>template.Must</code> is a convenience wrapper that panics when passed a
-non-nil <code>os.Error</code> value, and otherwise returns the
+The function <code>template.Must</code> is a convenience wrapper that panics
+when passed a non-nil <code>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>
-!srcextract.bin -src=final.go -name=init
-</pre>
-
 <p>
 A <code>for</code> loop is used with a <code>range</code> statement to iterate 
 over an array constant containing the names of the templates we want parsed.
@@ -592,13 +542,17 @@ that array.
 </p>
 
 <p>
-We then modify our <code>renderTemplate</code> function to call 
-the <code>Execute</code> method on the appropriate <code>Template</code> from 
-<code>templates</code>:
+We then modify the <code>renderTemplate</code> function to call the
+<code>templates.ExecuteTemplate</code> method with the name of the appropriate
+template:
+</p>
 
-<pre>
-!srcextract.bin -src=final.go -name=renderTemplate
-</pre>
+{{code "doc/articles/wiki/final.go" `/func renderTemplate/` `/^}/`}}
+
+<p>
+Note that the template name is the template file name, so we must
+append <code>".html"</code> to the <code>tmpl</code> argument.
+</p>
 
 <h2>Validation</h2>
 
@@ -613,16 +567,14 @@ First, add <code>"regexp"</code> to the <code>import</code> list.
 Then we can create a global variable to store our validation regexp:
 </p>
 
-<pre>
-!srcextract.bin -src=final-noclosure.go -name=titleValidator
-</pre>
+{{code "doc/articles/wiki/final-noclosure.go" `/^var titleValidator/`}}
 
 <p>
 The function <code>regexp.MustCompile</code> will parse and compile the 
 regular expression, and return a <code>regexp.Regexp</code>. 
 <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. 
+an <code>error</code> as a second parameter. 
 </p>
 
 <p>
@@ -630,9 +582,7 @@ Now, let's write a function that extracts the title string from the request
 URL, and tests it against our <code>TitleValidator</code> expression:
 </p>
 
-<pre>
-!srcextract.bin -src=final-noclosure.go -name=getTitle
-</pre>
+{{code "doc/articles/wiki/final-noclosure.go" `/func getTitle/` `/^}/`}}
 
 <p>
 If the title is valid, it will be returned along with a <code>nil</code>
@@ -645,13 +595,9 @@ handler.
 Let's put a call to <code>getTitle</code> in each of the handlers:
 </p>
 
-<pre>
-!srcextract.bin -src=final-noclosure.go -name=viewHandler
-
-!srcextract.bin -src=final-noclosure.go -name=editHandler
-
-!srcextract.bin -src=final-noclosure.go -name=saveHandler
-</pre>
+{{code "doc/articles/wiki/final-noclosure.go" `/^func viewHandler/` `/^}/`}}
+{{code "doc/articles/wiki/final-noclosure.go" `/^func editHandler/` `/^}/`}}
+{{code "doc/articles/wiki/final-noclosure.go" `/^func saveHandler/` `/^}/`}}
 
 <h2>Introducing Function Literals and Closures</h2>
 
@@ -659,7 +605,7 @@ Let's put a call to <code>getTitle</code> in each of the handlers:
 Catching the error condition in each handler introduces a lot of repeated code.
 What if we could wrap each of the handlers in a function that does this 
 validation and error checking? Go's 
-<a href="http://golang.org/doc/go_spec.html#Function_declarations">function 
+<a href="/ref/spec#Function_declarations">function 
 literals</a> provide a powerful means of abstracting functionality 
 that can help us here.
 </p>
@@ -702,9 +648,7 @@ Now we can take the code from <code>getTitle</code> and use it here
 (with some minor modifications):
 </p>
 
-<pre>
-!srcextract.bin -src=final.go -name=makeHandler
-</pre>
+{{code "doc/articles/wiki/final.go" `/func makeHandler/` `/^}/`}}
 
 <p>
 The closure returned by <code>makeHandler</code> is a function that takes
@@ -725,22 +669,16 @@ Now we can wrap the handler functions with <code>makeHandler</code> in
 package:
 </p>
 
-<pre>
-!srcextract.bin -src=final.go -name=main
-</pre>
+{{code "doc/articles/wiki/final.go" `/func main/` `/^}/`}}
 
 <p>
 Finally we remove the calls to <code>getTitle</code> from the handler functions,
 making them much simpler:
 </p>
 
-<pre>
-!srcextract.bin -src=final.go -name=viewHandler
-
-!srcextract.bin -src=final.go -name=editHandler
-
-!srcextract.bin -src=final.go -name=saveHandler
-</pre>
+{{code "doc/articles/wiki/final.go" `/^func viewHandler/` `/^}/`}}
+{{code "doc/articles/wiki/final.go" `/^func editHandler/` `/^}/`}}
+{{code "doc/articles/wiki/final.go" `/^func saveHandler/` `/^}/`}}
 
 <h2>Try it out!</h2>
 
@@ -753,9 +691,8 @@ Recompile the code, and run the app:
 </p>
 
 <pre>
-$ 8g wiki.go
-$ 8l wiki.8
-$ ./8.out
+$ go build wiki.go
+$ ./wiki
 </pre>
 
 <p>

doc/articles/wiki/notemplate.go

@@ -1,10 +1,13 @@
+// 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.
+
 package main
 
 import (
 	"fmt"
-	"http"
 	"io/ioutil"
-	"os"
+	"net/http"
 )
 
 type Page struct {
@@ -12,12 +15,12 @@ type Page struct {
 	Body  []byte
 }
 
-func (p *Page) save() os.Error {
+func (p *Page) save() error {
 	filename := p.Title + ".txt"
 	return ioutil.WriteFile(filename, p.Body, 0600)
 }
 
-func loadPage(title string) (*Page, os.Error) {
+func loadPage(title string) (*Page, error) {
 	filename := title + ".txt"
 	body, err := ioutil.ReadFile(filename)
 	if err != nil {

doc/articles/wiki/part1-noerror.go

@@ -1,9 +1,12 @@
+// 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.
+
 package main
 
 import (
 	"fmt"
 	"io/ioutil"
-	"os"
 )
 
 type Page struct {
@@ -11,7 +14,7 @@ type Page struct {
 	Body  []byte
 }
 
-func (p *Page) save() os.Error {
+func (p *Page) save() error {
 	filename := p.Title + ".txt"
 	return ioutil.WriteFile(filename, p.Body, 0600)
 }

doc/articles/wiki/part1.go

@@ -1,9 +1,12 @@
+// 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.
+
 package main
 
 import (
 	"fmt"
 	"io/ioutil"
-	"os"
 )
 
 type Page struct {
@@ -11,12 +14,12 @@ type Page struct {
 	Body  []byte
 }
 
-func (p *Page) save() os.Error {
+func (p *Page) save() error {
 	filename := p.Title + ".txt"
 	return ioutil.WriteFile(filename, p.Body, 0600)
 }
 
-func loadPage(title string) (*Page, os.Error) {
+func loadPage(title string) (*Page, error) {
 	filename := title + ".txt"
 	body, err := ioutil.ReadFile(filename)
 	if err != nil {

doc/articles/wiki/part2.go

@@ -1,10 +1,13 @@
+// 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.
+
 package main
 
 import (
 	"fmt"
-	"http"
 	"io/ioutil"
-	"os"
+	"net/http"
 )
 
 type Page struct {
@@ -12,12 +15,12 @@ type Page struct {
 	Body  []byte
 }
 
-func (p *Page) save() os.Error {
+func (p *Page) save() error {
 	filename := p.Title + ".txt"
 	return ioutil.WriteFile(filename, p.Body, 0600)
 }
 
-func loadPage(title string) (*Page, os.Error) {
+func loadPage(title string) (*Page, error) {
 	filename := title + ".txt"
 	body, err := ioutil.ReadFile(filename)
 	if err != nil {

doc/articles/wiki/srcextract.go

@@ -1,15 +1,19 @@
+// 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.
+
 package main
 
 import (
 	"bytes"
 	"flag"
+	"go/ast"
 	"go/parser"
 	"go/printer"
-	"go/ast"
 	"go/token"
 	"log"
-	"template"
 	"os"
+	"text/template"
 )
 
 var (

doc/articles/wiki/test.bash

@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+# Copyright 2010 The Go Authors. All rights reserved.
+# Use of this source code is governed by a BSD-style
+# license that can be found in the LICENSE file.
 
 set -e
 wiki_pid=
@@ -8,10 +11,10 @@ cleanup() {
 }
 trap cleanup 0 INT
 
-gomake get.bin
+go build -o get.bin get.go
 addr=$(./get.bin -addr)
 sed s/:8080/$addr/ < final.go > final-test.go
-gomake final-test.bin
+go build -o final-test.bin final-test.go
 (./final-test.bin) &
 wiki_pid=$!
 

doc/cmd.html

@@ -0,0 +1,103 @@
+<!--{
+	"Title": "Command Documentation",
+	"Path":  "/doc/cmd"
+}-->
+
+<p>
+There is a suite of programs to build and process Go source code.
+Instead of being run directly, programs in the suite are usually invoked
+by the <a href="/cmd/go/">go</a> program.
+</p>
+
+<p>
+The most common way to run these programs is as a subcommand of the go program,
+for instance as <code>go fmt</code>. Run like this, the command operates on
+complete packages of Go source code, with the go program invoking the
+underlying binary with arguments appropriate to package-level processing.
+</p>
+
+<p>
+The programs can also be run as stand-alone binaries, with unmodified arguments,
+using the go <code>tool</code> subcommand, such as <code>go tool vet</code>.
+This style of invocation allows, for instance, checking a single source file
+rather than an entire package: <code>go tool vet myprogram.go</code> as
+compared to <code>go vet mypackage</code>.
+Some of the commands, such as <code>yacc</code>, are accessible only through
+the go <code>tool</code> subcommand.
+</p>
+
+<p>
+Finally, two of the commands, <code>fmt</code> and <code>doc</code>, are also
+installed as regular binaries called <code>gofmt</code> and <code>godoc</code>
+because they are so often referenced.
+</p>
+
+<p>
+Click on the links for more documentation, invocation methods, and usage details.
+</p>
+
+<table class="dir">
+<tr>
+<th>Name</th>
+<th>&nbsp;&nbsp;&nbsp;&nbsp;</th>
+<th>Synopsis</th>
+</tr>
+
+<tr>
+<td><a href="/cmd/go/">go</a></td>
+<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
+<td>
+The <code>go</code> program manages Go source code and runs the other
+commands listed here.
+See the command docs for usage
+details.
+<br><br>
+</td>
+</tr>
+
+<tr>
+<td><a href="/cmd/cgo/">cgo</a></td>
+<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
+<td>Cgo enables the creation of Go packages that call C code.</td>
+</tr>
+
+<tr>
+<td><a href="/cmd/fix/">fix</a></td>
+<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
+<td>Fix finds Go programs that use old features of the language and libraries
+and rewrites them to use newer ones.</td>
+</tr>
+
+<tr>
+<td><a href="/cmd/go/">doc</a></td>
+<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
+<td>Doc extracts and generates documentation for Go packages, it is also available as
+an independent <a href="/cmd/godoc/">godoc</a> command with more general options.</td>
+</tr>
+
+<tr>
+<td><a href="/cmd/go/">fmt</a></td>
+<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
+<td>Fmt formats Go packages, it is also available as an independent <a href="/cmd/gofmt/">
+gofmt</a> command with more general options.</td>
+</tr>
+
+<tr>
+<td><a href="/cmd/vet/">vet</a></td>
+<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
+<td>Vet examines Go source code and reports suspicious constructs, such as Printf
+calls whose arguments do not align with the format string.</td>
+</tr>
+
+<tr>
+<td><a href="/cmd/yacc/">yacc</a></td>
+<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
+<td>Yacc is a version of yacc that generates parsers implemented in Go.</td>
+</tr>
+
+</table>
+
+<p>
+This is an abridged list. See the <a href="/cmd/">full command reference</a>
+for documentation of the compilers and more.
+</p>

doc/code.html

@@ -1,164 +1,158 @@
-<!-- How to Write Go Code -->
+<!--{
+	"Title": "How to Write Go Code"
+}-->
 
 <h2 id="Introduction">Introduction</h2>
 
 <p>
-This document explains how to write a new package
-and how to test code.
-It assumes you have installed Go using the
-<a href="install.html">installation instructions</a>.
-</p>
-
-<p>
-Before embarking on a change to an existing
-package or the creation of a new package,
-be sure to send mail to the
-<a href="http://groups.google.com/group/golang-nuts">mailing list</a>
-to let people know what you are thinking of doing.
-Doing so helps avoid duplication of effort and
-enables discussions about design before any code
-has been written.
-</p>
-
-<h2 id="Community_resources">Community resources</h2>
-
-<p>
-For real-time help, there may be users or developers on
-<code>#go-nuts</code> on the <a href="http://freenode.net/">Freenode</a> IRC server.
-</p>
-
-<p>
-The official mailing list for discussion of the Go language is
-<a href="http://groups.google.com/group/golang-nuts">Go Nuts</a>.
-</p>
-
-<p>
-Bugs can be reported using the <a href="http://code.google.com/p/go/issues/list">Go issue tracker</a>.
-</p>
-
-<p>
-For those who wish to keep up with development,
-there is another mailing list, <a href="http://groups.google.com/group/golang-checkins">golang-checkins</a>,
-that receives a message summarizing each checkin to the Go repository.
+This document demonstrates the development of a simple Go package and
+introduces the <a href="/cmd/go/">go command</a>, the standard way to fetch,
+build, and install Go packages and commands.
 </p>
 
 
-<h2 id="New_package">Creating a new package</h2>
+<h2 id="GOPATH">Code organization</h2>
+
+<h3><code>GOPATH</code> and workspaces</h3>
 
 <p>
-The source code for the package with import path
-<code>x/y</code> is, by convention, kept in the
-directory <code>$GOROOT/src/pkg/x/y</code>.
+One of Go's design goals is to make writing software easier.  To that end, the
+<code>go</code> command doesn't use Makefiles or other configuration files to
+guide program construction. Instead, it uses the source code to find
+dependencies and determine build conditions. This means your source code and
+build scripts are always in sync; they are one and the same.
 </p>
 
-<h3>Makefile</h3>
+<p>
+The one thing you must do is set a <code>GOPATH</code> environment variable.
+<code>GOPATH</code> tells the <code>go</code> command (and other related tools)
+where to find and install the Go packages on your system.
+</p>
 
 <p>
-It would be nice to have Go-specific tools that
-inspect the source files to determine what to build and in
-what order, but for now, Go uses GNU <code>make</code>.
-Thus, the first file to create in a new package directory is
-usually the <code>Makefile</code>.
-The basic form used in the Go source tree
-is illustrated by <a href="../src/pkg/container/vector/Makefile"><code>src/pkg/container/vector/Makefile</code></a>:
+<code>GOPATH</code> is a list of paths. It shares the syntax of your system's
+<code>PATH</code> environment variable. A typical <code>GOPATH</code> on
+a Unix system might look like this:
 </p>
 
 <pre>
-include ../../../Make.inc
-
-TARG=container/vector
-GOFILES=\
-	intvector.go\
-	stringvector.go\
-	vector.go\
-
-include ../../../Make.pkg
+GOPATH=/home/user/ext:/home/user/mygo
 </pre>
 
 <p>
-Outside the Go source tree (for personal packages), the standard form is
+(On a Windows system use semicolons as the path separator instead of colons.)
+</p>
+
+<p>
+Each path in the list (in this case <code>/home/user/ext</code> or
+<code>/home/user/mygo</code>) specifies the location of a <i>workspace</i>.
+A workspace contains Go source files and their associated package objects, and
+command executables. It has a prescribed structure of three subdirectories:
+</p>
+
+<ul>
+<li><code>src</code> contains Go source files,
+<li><code>pkg</code> contains compiled package objects, and
+<li><code>bin</code> contains executable commands.
+</ul>
+
+<p>
+Subdirectories of the <code>src</code> directory hold independent packages, and
+all source files (<code>.go</code>, <code>.c</code>, <code>.h</code>, and
+<code>.s</code>) in each subdirectory are elements of that subdirectory's
+package.
+</p>
+
+<p>
+When building a program that imports the package "<code>widget</code>" the
+<code>go</code> command looks for <code>src/pkg/widget</code> inside the Go root,
+and then&mdash;if the package source isn't found there&mdash;it searches
+for <code>src/widget</code> inside each workspace in order.
+</p>
+
+<p>
+Multiple workspaces can offer some flexibility and convenience, but for now
+we'll concern ourselves with only a single workspace.
+</p>
+
+<p>
+Let's work through a simple example. First, create a <code>$HOME/mygo</code>
+directory and its <code>src</code> subdirectory:
 </p>
 
 <pre>
-include $(GOROOT)/src/Make.inc
-
-TARG=mypackage
-GOFILES=\
-	my1.go\
-	my2.go\
-
-include $(GOROOT)/src/Make.pkg
+$ mkdir -p $HOME/mygo/src # create a place to put source code
 </pre>
 
 <p>
-The first and last lines <code>include</code> standard definitions and rules.
-Packages maintained in the standard Go tree use a relative path (instead of
-<code>$(GOROOT)/src</code>) so that <code>make</code> will work correctly
-even if <code>$(GOROOT)</code> contains spaces.
-This makes it easy for programmers to try Go.
+Next, set it as the <code>GOPATH</code>. You should also add the
+<code>bin</code> subdirectory to your <code>PATH</code> environment variable so
+that you can run the commands therein without specifying their full path.
+To do this, add the following lines to <code>$HOME/.profile</code> (or
+equivalent):
 </p>
 
-<p>
-If you have not set <code>$GOROOT</code> in your environment,
-you must run <code>gomake</code> to use this form of makefile.
-<code>Gomake</code> also takes care to invoke GNU Make
-even on systems where it is installed as <code>gmake</code>
-rather than <code>make</code>.
-</p>
-
-<p>
-<code>TARG</code> is the target install path for the package,
-the string that clients will use to import it.
-Inside the Go tree, this string should be the same as the directory
-in which the <code>Makefile</code> appears, with the
-<code>$GOROOT/src/pkg/</code> prefix removed.
-Outside the Go tree, you can use any <code>TARG</code> you
-want that doesn't conflict with the standard Go package names.
-A common convention is to use an identifying top-level name
-to group your packages: <code>myname/tree</code>, <code>myname/filter</code>, etc.
-Note that even if you keep your package source outside the
-Go tree, running <code>make install</code> installs your
-package binaries in the standard location&mdash;<code>$GOROOT/pkg</code>&mdash;to
-make it easy to find them.
-</p>
-
-<p>
-<code>GOFILES</code> is a list of source files to compile to
-create the package.  The trailing <code>\</code> characters
-allow the list to be split onto multiple lines
-for easy sorting.
-</p>
-
-<p>
-If you create a new package directory in the Go tree, add it to the list in
-<code>$GOROOT/src/pkg/Makefile</code> so that it
-is included in the standard build.  Then run:
 <pre>
-cd $GOROOT/src/pkg
-./deps.bash
+export GOPATH=$HOME/mygo
+export PATH=$PATH:$HOME/mygo/bin
 </pre>
+
+
+<h3>Import paths</h3>
+
 <p>
-to update the dependency file <code>Make.deps</code>.
-(This happens automatically each time you run <code>all.bash</code>
-or <code>make.bash</code>.)
+The standard packages are given short import paths such as <code>"fmt"</code>
+and <code>"net/http"</code> for convenience. 
+For your own projects, it is important to choose a base import path that is
+unlikely to collide with future additions to the standard library or other
+external libraries.
 </p>
 
 <p>
-If you change the imports of an existing package,
-you do not need to edit <code>$GOROOT/src/pkg/Makefile</code>
-but you will still need to run <code>deps.bash</code> as above.
+The best way to choose an import path is to use the location of your version
+control repository.
+For instance, if your source repository is at <code>example.com</code> 
+or <code>code.google.com/p/example</code>, you should begin your package
+paths with that URL, as in "<code>example.com/foo/bar</code>" or
+"<code>code.google.com/p/example/foo/bar</code>".
+Using this convention, the <code>go</code> command can automatically check out and
+build the source code by its import path alone.
 </p>
 
-
-<h3>Go source files</h3>
+<p>
+If you don't intend to install your code in this way, you should at
+least use a unique prefix like "<code>widgets/</code>", as in
+"<code>widgets/foo/bar</code>". A good rule is to use a prefix such as your
+company or project name, since it is unlikely to be used by another group.
+</p>
 
 <p>
-The first statement in each of the source files listed in the <code>Makefile</code>
-should be <code>package <i>name</i></code>, where <code><i>name</i></code>
-is the package's default name for imports.
+We'll use <code>example/</code> as our base import path:
+</p>
+
+<pre>
+$ mkdir -p $GOPATH/src/example
+</pre>
+
+
+<h3>Package names</h3>
+
+<p>
+The first statement in a Go source file should be
+</p>
+
+<pre>
+package <i>name</i>
+</pre>
+
+<p>
+where <code><i>name</i></code> is the package's default name for imports.
 (All files in a package must use the same <code><i>name</i></code>.)
+</p>
+
+<p>
 Go's convention is that the package name is the last element of the
-import path: the package imported as <code>"crypto/rot13"</code>
+import path: the package imported as "<code>crypto/rot13</code>"
 should be named <code>rot13</code>.
 There is no requirement that package names be unique
 across all packages linked into a single binary,
@@ -166,203 +160,344 @@ only that the import paths (their full file names) be unique.
 </p>
 
 <p>
-Go compiles all the source files in a package at once, so one file
-can refer to constants, variables, types, and functions in another
-file without special arrangement or declarations.
+Create a new package under <code>example</code> called <code>newmath</code>:
 </p>
 
-<p>
-Writing clean, idiomatic Go code is beyond the scope of this document.
-<a href="effective_go.html">Effective Go</a> is an introduction to
-that topic.
-</p>
-
-<h2 id="Building_programs">Building programs</h2>
-<p>To build a Go program with gomake, create a Makefile alongside your program's
-source files. It should be similar to the example above, but include
-<code>Make.cmd</code> instead of <code>Make.pkg</code>:
-
 <pre>
-include $(GOROOT)/src/Make.inc
-
-TARG=helloworld
-GOFILES=\
-	helloworld.go\
-
-include $(GOROOT)/src/Make.cmd
+$ cd $GOPATH/src/example
+$ mkdir newmath
 </pre>
 
-<p>Running <code>gomake</code> will compile <code>helloworld.go</code>
-and produce an executable named <code>helloworld</code> in the current
-directory.
+<p>
+Then create a file named <code>$GOPATH/src/example/newmath/sqrt.go</code>
+containing the following Go code:
+</p>
+
+<pre>
+// Package newmath is a trivial example package.
+package newmath
+
+// Sqrt returns an approximation to the square root of x.
+func Sqrt(x float64) float64 {
+        // This is a terrible implementation.
+        // Real code should import "math" and use math.Sqrt.
+        z := 0.0
+        for i := 0; i < 1000; i++ {
+                z -= (z*z - x) / (2 * x)
+        }
+        return z
+}
+</pre>
+
+<p>
+This package is imported by the path name of the directory it's in, starting
+after the <code>src</code> component:
+</p>
+
+<pre>
+import "example/newmath"
+</pre>
+
+<p>
+See <a href="/doc/effective_go.html#names">Effective Go</a> to learn more about
+Go's naming conventions.
+</p>
+
+
+<h2>Building and installing</h2>
+
+<p>
+The <code>go</code> command comprises several subcommands, the most central being
+<code>install</code>. Running <code>go install <i>importpath</i></code> builds
+and installs a package and its dependencies.
 </p>
 
 <p>
-Running <code>gomake install</code> will build <code>helloworld</code> if
-necessary and copy it to the <code>$GOBIN</code> directory
-(<code>$GOROOT/bin/</code> is the default).
+To "install a package" means to write the package object or executable command
+to the <code>pkg</code> or <code>bin</code> subdirectory of the workspace in
+which the source resides.
 </p>
 
+<h3>Building a package</h3>
+
+<p>
+To build and install the <code>newmath</code> package, type
+</p>
+
+<pre>
+$ go install example/newmath
+</pre>
+
+<p>
+This command will produce no output if the package and its dependencies
+are built and installed correctly.
+</p>
+
+<p>
+As a convenience, the <code>go</code> command will assume the current directory
+if no import path is specified on the command line. This sequence of commands
+has the same affect as the one above:
+</p>
+
+<pre>
+$ cd $GOPATH/src/example/newmath
+$ go install
+</pre>
+
+<p>
+The resulting workspace directory tree (assuming we're running Linux on a 64-bit
+system) looks like this:
+</p>
+
+<pre>
+pkg/
+    linux_amd64/
+        example/
+            newmath.a  # package object
+src/
+    example/
+        newmath/
+            sqrt.go    # package source
+</pre>
+
+
+<h3>Building a command</h3>
+
+<p>
+The <code>go</code> command treats code belonging to <code>package main</code> as
+an executable command and installs the package binary to the
+<code>GOPATH</code>'s <code>bin</code> subdirectory.
+</p>
+
+<p>
+Add a command named <code>hello</code> to the source tree.
+First create the <code>example/hello</code> directory:
+</p>
+
+<pre>
+$ cd $GOPATH/src/example
+$ mkdir hello
+</pre>
+
+<p>
+Then create the file <code>$GOPATH/src/example/hello/hello.go</code>
+containing the following Go code.
+</p>
+
+<pre>
+// Hello is a trivial example of a main package.
+package main
+
+import (
+        "example/newmath"
+        "fmt"
+)
+
+func main() {
+        fmt.Printf("Hello, world.  Sqrt(2) = %v\n", newmath.Sqrt(2))
+}
+</pre>
+
+<p>
+Next, run <code>go install</code>, which builds and installs the binary to
+<code>$GOPATH/bin</code>:
+</p>
+
+<pre>
+$ go install example/hello
+</pre>
+
+<p>
+To run the program, invoke it by name as you would any other command:
+</p>
+
+<pre>
+$ $GOPATH/bin/hello
+Hello, world.  Sqrt(2) = 1.414213562373095
+</pre>
+
+<p>
+If you added <code>$HOME/mygo/bin</code> to your <code>PATH</code>, you may omit
+the path to the executable:
+</p>
+
+<pre>
+$ hello
+Hello, world.  Sqrt(2) = 1.414213562373095
+</pre>
+
+<p>
+The workspace directory tree now looks like this:
+</p>
+
+<pre>
+bin/
+    hello              # command executable
+pkg/
+    linux_amd64/ 
+        example/
+            newmath.a  # package object
+src/
+    example/
+        hello/
+            hello.go   # command source
+        newmath/
+            sqrt.go    # package source
+</pre>
+
+<p>
+The <code>go</code> command also provides a <code>build</code> command, which is
+like <code>install</code> except it builds all objects in a temporary directory
+and does not install them under <code>pkg</code> or <code>bin</code>.
+When building a command an executable named after the last element of the
+import path is written to the current directory. When building a package, 
+<code>go build</code> serves merely to test that the package and its
+dependencies can be built. (The resulting package object is thrown away.)
+</p>
+
+
 <h2 id="Testing">Testing</h2>
 
 <p>
-Go has a lightweight test framework known as <code>gotest</code>.
+Go has a lightweight test framework composed of the <code>go test</code>
+command and the <code>testing</code> package.
+</p>
+
+<p>
 You write a test by creating a file with a name ending in <code>_test.go</code>
-that contains functions named <code>TestXXX</code> with signature <code>func (t *testing.T)</code>.
+that contains functions named <code>TestXXX</code> with signature
+<code>func (t *testing.T)</code>.
 The test framework runs each such function;
-if the function calls a failure function such as <code>t.Error</code> or <code>t.Fail</code>, the test is considered to have failed.
-The <a href="/cmd/gotest/">gotest command documentation</a>
-and the <a href="/pkg/testing/">testing package documentation</a> give more detail.
+if the function calls a failure function such as <code>t.Error</code> or
+<code>t.Fail</code>, the test is considered to have failed.
 </p>
 
 <p>
-The <code>*_test.go</code> files should not be listed in the <code>Makefile</code>.
-</p>
-
-<p>
-To run the test, run either <code>make test</code> or <code>gotest</code>
-(they are equivalent).
-To run only the tests in a single test file, for instance <code>one_test.go</code>,
-run <code>gotest one_test.go</code>.
-</p>
-
-<p>
-If your change affects performance, add a <code>Benchmark</code> function 
-(see the <a href="/cmd/gotest/">gotest command documentation</a>)
-and run it using <code>gotest -test.bench=.</code>.
-</p>
-
-<p>
-Once your new code is tested and working,
-it's time to get it <a href="contribute.html">reviewed and submitted</a>.
-</p>
-
-<h2 id="pkg_example">An example package with tests</h2>
-
-<p>
-This example package, <code>numbers</code>, consists of the function
-<code>Double</code>, which takes an <code>int</code> and returns that value 
-multiplied by 2. It consists of three files.
-</p>
-
-<p>
-First, the package implementation, <code>numbers.go</code>:
+Add a test to the <code>newmath</code> package by creating the file
+<code>$GOPATH/src/example/newmath/sqrt_test.go</code> containing the following
+Go code.
 </p>
 
 <pre>
-package numbers
+package newmath
 
-func Double(i int) int {
-	return i * 2
+import "testing"
+
+func TestSqrt(t *testing.T) {
+	const in, out = 9, 3
+	if x := Sqrt(in); x != out {
+		t.Errorf("Sqrt(%v) = %v, want %v", in, x, out)
+        }
 }
 </pre>
 
 <p>
-Next, the tests, <code>numbers_test.go</code>:
+Now run the test with <code>go test</code>:
 </p>
 
 <pre>
-package numbers
-
-import (
-	"testing"
-)
-
-type doubleTest struct {
-	in, out int
-}
-
-var doubleTests = []doubleTest{
-	doubleTest{1, 2},
-	doubleTest{2, 4},
-	doubleTest{-5, -10},
-}
-
-func TestDouble(t *testing.T) {
-	for _, dt := range doubleTests {
-		v := Double(dt.in)
-		if v != dt.out {
-			t.Errorf("Double(%d) = %d, want %d.", dt.in, v, dt.out)
-		}
-	}
-}
+$ go test example/newmath
+ok  	example/newmath
 </pre>
 
 <p>
-Finally, the <code>Makefile</code>:
+Run <code><a href="/cmd/go/#Test_packages">go help test</a></code> and see the
+<a href="/pkg/testing/">testing package documentation</a> for more detail.
+</p>
+
+
+<h2 id="remote">Remote packages</h2>
+
+<p>
+An import path can describe how to obtain the package source code using a
+revision control system such as Git or Mercurial. The <code>go</code> command uses
+this property to automatically fetch packages from remote repositories.
+For instance, the examples described in this document are also kept in a
+Mercurial repository hosted at Google Code,
+<code><a href="http://code.google.com/p/go.example">code.google.com/p/go.example</a></code>.
+If you include the repository URL in the package's import path,
+<code>go get</code> will fetch, build, and install it automatically:
 </p>
 
 <pre>
-include $(GOROOT)/src/Make.inc
-
-TARG=numbers
-GOFILES=\
-	numbers.go\
-
-include $(GOROOT)/src/Make.pkg
+$ go get code.google.com/p/go.example/hello
+$ $GOPATH/bin/hello
+Hello, world.  Sqrt(2) = 1.414213562373095
 </pre>
 
 <p>
-Running <code>gomake install</code> will build and install the package to
-the <code>$GOROOT/pkg/</code> directory (it can then be used by any
-program on the system).
+If the specified package is not present in a workspace, <code>go get</code>
+will place it inside the first workspace specified by <code>GOPATH</code>.
+(If the package does already exist, <code>go get</code> skips the remote
+fetch and behaves the same as <code>go install</code>.)
 </p>
 
 <p>
-Running <code>gomake test</code> (or just running the command
-<code>gotest</code>) will rebuild the package, including the
-<code>numbers_test.go</code> file, and then run the <code>TestDouble</code>
-function. The output "<code>PASS</code>" indicates that all tests passed
-successfully.  Breaking the implementation by changing the multiplier from
-<code>2</code> to <code>3</code> will allow you to see how failing tests are 
-reported.
-</p>
-
-<p>
-See the <a href="/cmd/gotest/">gotest documentation</a> and the 
-<a href="/pkg/testing/">testing package</a> for more detail.
-</p>
-
-<h2 id="arch_os_specific">Architecture- and operating system-specific code</h2>
-
-<p>First, a disclaimer: very few Go packages should need to know about the
-hardware and operating system they run on.  In the vast majority of cases the
-language and standard library handle most portability issues.  This section is
-a guide for experienced systems programmers who have a good reason to write
-platform-specific code, such as assembly-language support for fast
-trigonometric functions or code that implements a common interface above
-different operating systems.</p>
-
-<p>To compile such code, use the <code>$GOOS</code> and <code>$GOARCH</code>
-<a href="/doc/install.html#environment">environment variables</a> in your
-source file names and <code>Makefile</code>.</p>
-
-<p>For example, this <code>Makefile</code> describes a package that builds on
-different operating systems by parameterizing the file name with
-<code>$GOOS</code>.</p>
-
-<pre>
-include $(GOROOT)/src/Make.inc
-
-TARG=mypackage
-GOFILES=\
-	my.go\
-	my_$(GOOS).go\
-
-include $(GOROOT)/src/Make.pkg
-</pre>
-
-<p>The OS-specific code goes in <code>my_linux.go</code>,
-<code>my_darwin.go</code>, and so on.</p>
-
-<p>If you follow these conventional parameterizations, tools such as
-<a href="/cmd/goinstall/">goinstall</a> will work seamlessly with your package:
+After issuing the above <code>go get</code> command, the workspace directory
+tree should now now look like this:
 </p>
 
 <pre>
-my_$(GOOS).go
-my_$(GOARCH).go
-my_$(GOOS)_$(GOARCH).go
+bin/
+    hello                 # command executable
+pkg/
+    linux_amd64/ 
+        code.google.com/p/go.example/
+            newmath.a     # package object
+        example/
+            newmath.a     # package object
+src/
+    code.google.com/p/go.example/
+        hello/
+            hello.go      # command source
+        newmath/
+            sqrt.go       # package source
+            sqrt_test.go  # test source
+    example/
+        hello/
+            hello.go      # command source
+        newmath/
+            sqrt.go       # package source
+            sqrt_test.go  # test source
 </pre>
 
-<p>The same holds for <code>.s</code> (assembly) files.</p>
+<p>
+The <code>hello</code> command hosted at Google Code depends on the
+<code>newmath</code> package within the same repository. The imports in
+<code>hello.go</code> file use the same import path convention, so the <code>go
+get</code> command is able to locate and install the dependent package, too.
+</p>
+
+<pre>
+import "code.google.com/p/go.example/newmath"
+</pre>
+
+<p>
+This convention is the easiest way to make your Go packages available for
+others to use.
+The <a href="http://godashboard.appspot.com/package">Go Package Dashboard</a>
+displays a list of packages recently installed with the <code>go</code> command.
+</p>
+
+<p>
+For more information on using remote repositories with the <code>go</code> command, see
+<code><a href="/cmd/go/#Remote_import_path_syntax">go help remote</a></code>.
+</p>
+
+
+<h2 id="more">Further reading</h2>
+
+<p>
+See <a href="/doc/effective_go.html">Effective Go</a> for tips on writing
+clear, idiomatic Go code.
+</p>
+
+<p>
+Take <a href="http://tour.golang.org/">A Tour of Go</a> to learn the language
+proper.
+</p>
+
+<p>
+Visit the <a href="/doc/#articles">documentation page</a> for a set of in-depth
+articles about the Go language and its libraries and tools.
+</p>

doc/codelab/wiki/htmlify.go

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

doc/codereview_with_mq.html

@@ -1,4 +1,6 @@
-<!-- Using Mercurial Queues with Codereview -->
+<!--{
+	"Title": "Using Mercurial Queues with Codereview"
+}-->
 
 <h2 id="Introduction">Introduction</h2>
 

doc/codewalk/functions.xml

@@ -45,7 +45,7 @@
   turn.
 </step>
 
-<step title="Multiple return values" src="doc/codewalk/pig.go:/\/\/ roll returns/,/stay.*true\n}/">
+<step title="Multiple return values" src="doc/codewalk/pig.go:/\/\/ roll returns/,/true\n}/">
 	Go functions can return multiple values.  
 	<br/><br/>
 
@@ -82,16 +82,6 @@
   associated with the current player.
 </step>
 
-<step title="Comparing functions" src="doc/codewalk/pig.go:/if action/,/currentPlayer\)\)\n\t\t}/">
-	Functions can be compared for equality in Go.  From the 
-	<a href="http://golang.org/doc/go_spec.html#Comparison_operators">language specification</a>:
-  Function values are equal if they refer to the same function or if both are <code>nil</code>.
-	<br/><br/>
-
-  We enforce that a <code>strategy</code> function can only return a legal
-  <code>action</code>: either <code>roll</code> or <code>stay</code>.
-</step>
-
 <step title="Simulating a tournament" src="doc/codewalk/pig.go:/\/\/ roundRobin/,/gamesPerStrategy\n}/">
 	The <code>roundRobin</code> function simulates a tournament and tallies wins.
 	Each strategy plays each other strategy <code>gamesPerSeries</code> times.

doc/codewalk/markov.go

@@ -50,8 +50,8 @@ import (
 	"flag"
 	"fmt"
 	"io"
+	"math/rand"
 	"os"
-	"rand"
 	"strings"
 	"time"
 )
@@ -120,8 +120,8 @@ func main() {
 	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.
+	flag.Parse()                     // Parse command-line flags.
+	rand.Seed(time.Now().UnixNano()) // Seed the random number generator.
 
 	c := NewChain(*prefixLen)     // Initialize a new Chain.
 	c.Build(os.Stdin)             // Build chains from standard input.

doc/codewalk/markov.xml

@@ -105,7 +105,7 @@ Prefix               Map key
 	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)
+	<code>Read</code> method returns <code>io.EOF</code> (end of file)
 	or some other read error occurs.
 </step>
 
@@ -133,7 +133,7 @@ Prefix               Map key
 	(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
+	(<code>io.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>
@@ -155,7 +155,7 @@ Prefix               Map key
 	<br/><br/>
 	For more information about the <code>append</code> function and slices
 	in general see the
-	<a href="http://blog.golang.org/2011/01/go-slices-usage-and-internals.html">Slices: usage and internals</a> article.
+	<a href="/doc/articles/slices_usage_and_internals.html">Slices: usage and internals</a> article.
 </step>
 
 <step title="Pushing the suffix onto the prefix" src="doc/codewalk/markov.go:/p\.Shift/">
@@ -275,16 +275,15 @@ p[len(p)-1] = suffix
 </step>
 
 <step title="Using this program" src="doc/codewalk/markov.go">
-	To use this program, first compile and link it.
-	If you are using <code>6g</code> as your compiler, the command
-	would look something like this:
+	To use this program, first build it with the
+	<a href="/cmd/go/">go</a> command:
 	<pre>
-$ 6g markov.go &amp;&amp; 6l -o markov markov.6</pre>
+$ go build markov.go</pre>
 	And then execute it while piping in some input text:
 	<pre>
-$ echo "a man a plan a canal panama" | ./markov -prefix=1
-a plan a man a plan a canal panama
-	</pre>
+$ echo "a man a plan a canal panama" \
+	| ./markov -prefix=1
+a plan a man a plan a canal panama</pre>
 	Here's a transcript of generating some text using the Go distribution's
 	README file as source material:
 	<pre>

doc/codewalk/pig.go

@@ -6,7 +6,7 @@ package main
 
 import (
 	"fmt"
-	"rand"
+	"math/rand"
 )
 
 const (
@@ -61,9 +61,6 @@ func play(strategy0, strategy1 strategy) int {
 	currentPlayer := rand.Intn(2) // Randomly decide who plays first
 	for s.player+s.thisTurn < win {
 		action := strategies[currentPlayer](s)
-		if action != roll && action != stay {
-			panic(fmt.Sprintf("Player %d is cheating", currentPlayer))
-		}
 		s, turnIsOver = action(s)
 		if turnIsOver {
 			currentPlayer = (currentPlayer + 1) % 2

doc/codewalk/sharemem.xml

@@ -65,7 +65,7 @@ and then loops passing completed Resources back to the pending
 channel after appropriate delays.
 </step>
 
-<step title="Creating channels" src="doc/codewalk/urlpoll.go:/create our/,/complete/">
+<step title="Creating channels" src="doc/codewalk/urlpoll.go:/Create our/,/complete/">
 First, main makes two channels of *Resource, pending and complete.
 <br/><br/>
 Inside main, a new goroutine sends one Resource per URL to pending
@@ -75,7 +75,7 @@ The pending and complete channels are passed to each of the Poller
 goroutines, within which they are known as in and out. 
 </step>
 
-<step title="Initializing StateMonitor" src="doc/codewalk/urlpoll.go:/launch the StateMonitor/,/statusInterval/">
+<step title="Initializing StateMonitor" src="doc/codewalk/urlpoll.go:/Launch the StateMonitor/,/statusInterval/">
 StateMonitor will initialize and launch a goroutine that stores the state 
 of each Resource. We will look at this function in detail later. 
 <br/><br/>
@@ -83,14 +83,14 @@ For now, the important thing to note is that it returns a channel of State,
 which is saved as status and passed to the Poller goroutines.
 </step>
 
-<step title="Launching Poller goroutines" src="doc/codewalk/urlpoll.go:/launch some Poller/,/}/">
+<step title="Launching Poller goroutines" src="doc/codewalk/urlpoll.go:/Launch some Poller/,/}/">
 Now that it has the necessary channels, main launches a number of
 Poller goroutines, passing the channels as arguments.
 The channels provide the means of communication between the main, Poller, and 
 StateMonitor goroutines.
 </step>
 
-<step title="Send Resources to pending" src="doc/codewalk/urlpoll.go:/send some Resources/,/}\(\)/">
+<step title="Send Resources to pending" src="doc/codewalk/urlpoll.go:/Send some Resources/,/}\(\)/">
 To add the initial work to the system, main starts a new goroutine
 that allocates and sends one Resource per URL to pending.
 <br/><br/>

doc/codewalk/urlpoll.go

@@ -5,17 +5,16 @@
 package main
 
 import (
-	"http"
 	"log"
+	"net/http"
 	"time"
 )
 
 const (
-	numPollers     = 2           // number of Poller goroutines to launch
-	second         = 1e9         // one second is 1e9 nanoseconds
-	pollInterval   = 60 * second // how often to poll each URL
-	statusInterval = 10 * second // how often to log status to stdout
-	errTimeout     = 10 * second // back-off timeout on error
+	numPollers     = 2                // number of Poller goroutines to launch
+	pollInterval   = 60 * time.Second // how often to poll each URL
+	statusInterval = 10 * time.Second // how often to log status to stdout
+	errTimeout     = 10 * time.Second // back-off timeout on error
 )
 
 var urls = []string{
@@ -33,7 +32,7 @@ type State struct {
 // StateMonitor maintains a map that stores the state of the URLs being
 // polled, and prints the current state every updateInterval nanoseconds.
 // It returns a chan State to which resource state should be sent.
-func StateMonitor(updateInterval int64) chan<- State {
+func StateMonitor(updateInterval time.Duration) chan<- State {
 	updates := make(chan State)
 	urlStatus := make(map[string]string)
 	ticker := time.NewTicker(updateInterval)
@@ -61,7 +60,7 @@ func logState(s map[string]string) {
 // Resource represents an HTTP URL to be polled by this program.
 type Resource struct {
 	url      string
-	errCount int64
+	errCount int
 }
 
 // Poll executes an HTTP HEAD request for url
@@ -71,7 +70,7 @@ func (r *Resource) Poll() string {
 	if err != nil {
 		log.Println("Error", r.url, err)
 		r.errCount++
-		return err.String()
+		return err.Error()
 	}
 	r.errCount = 0
 	return resp.Status
@@ -79,8 +78,8 @@ func (r *Resource) Poll() string {
 
 // Sleep sleeps for an appropriate interval (dependant on error state)
 // before sending the Resource to done.
-func (r *Resource) Sleep(done chan *Resource) {
-	time.Sleep(pollInterval + errTimeout*r.errCount)
+func (r *Resource) Sleep(done chan<- *Resource) {
+	time.Sleep(pollInterval + errTimeout*time.Duration(r.errCount))
 	done <- r
 }
 
@@ -93,18 +92,18 @@ func Poller(in <-chan *Resource, out chan<- *Resource, status chan<- State) {
 }
 
 func main() {
-	// create our input and output channels
+	// Create our input and output channels.
 	pending, complete := make(chan *Resource), make(chan *Resource)
 
-	// launch the StateMonitor
+	// Launch the StateMonitor.
 	status := StateMonitor(statusInterval)
 
-	// launch some Poller goroutines
+	// Launch some Poller goroutines.
 	for i := 0; i < numPollers; i++ {
 		go Poller(pending, complete, status)
 	}
 
-	// send some Resources to the pending queue
+	// Send some Resources to the pending queue.
 	go func() {
 		for _, url := range urls {
 			pending <- &Resource{url: url}

doc/community.html

@@ -1,53 +0,0 @@
-<!-- title Community -->
-
-<div class="left-column">
-
-<h2 id="developer_info">The Go Community</h2>
-
-<h3 id="mailinglist"><a href="http://groups.google.com/group/golang-nuts">Go Nuts Mailing List</a></h3>
-<p>The <a href="http://groups.google.com/group/golang-nuts">golang-nuts</a> 
-mailing list is for general Go discussion.</p>
-
-<h3 id=""><a href="http://godashboard.appspot.com/package">Go Packages Dashboard</a></h3>
-<p>A list of the most popular <a href="/cmd/goinstall/">goinstall</a>'d
-Go libraries.</p>
-
-<h3 id=""><a href="http://godashboard.appspot.com/project">Go Project Dashboard</a></h3>
-<p>A list of external Go projects including programs and libraries.</p>
-
-<h3 id="irc"><a href="irc:irc.freenode.net/go-nuts">Go IRC Channel</a></h3>
-<p><b>#go-nuts</b> on <b>irc.freenode.net</b> is the official Go IRC channel.</p>
-
-<h3 id="twitter"><a href="http://twitter.com/go_nuts">@go_nuts at Twitter</a></h3>
-<p>The Go project's official Twitter account.</p>
-
-</div>
-
-<div class="right-column">
-
-<h2 id="blogs">Blogs</h2>
-
-<h3 id="blog_go"><a href="http://blog.golang.org/">The Go Blog</a></h3>
-<p>
-The Go project's official blog, maintained by the core Go developers.
-</p>
-
-<h3 id="blog_rsc"><a href="http://research.swtch.com/search/label/Go">research!rsc</a></h3>
-<p>
-Posts labelled 'Go' by Russ Cox, one of the core Go developers.
-</p>
-
-<h3 id="blog_iant"><a href="http://www.airs.com/blog/archives/category/programming">Airs</a></h3>
-<p>
-Posts labelled 'Programming' by Ian Lance Taylor, one of the core Go developers.
-</p>
-
-<h3 id="blog_adg"><a href="http://nf.id.au/tag/go">nf.id.au</a></h3>
-<p>
-Posts labelled 'Go' by Andrew Gerrand, one of the core Go developers.
-</p>
-
-</div>
-
-<div class="end-columns"></div>
-

doc/contrib.html

@@ -1,6 +1,55 @@
-<!-- title Contributing -->
+<!--{
+	"Title": "The Go Project",
+	"Path": "/project/"
+}-->
+
+<img class="gopher" src="/doc/gopher/project.png" />
+
+<div id="manual-nav"></div>
+
+<p>
+Go is an open source project developed by a team at
+<a href="http://google.com/">Google</a> and many
+<a href="/CONTRIBUTORS">contributors</a> from the open source community.
+</p>
+
+<p>
+Go is distributed under a <a href="/LICENSE">BSD-style license</a>.
+</p>
+
+<h3 id="announce"><a href="http://groups.google.com/group/golang-announce">Announcements Mailing List</a></h3>
+<p>
+A low traffic mailing list for important announcements, such as new releases.
+</p>
+<p>
+We encourage all Go users to subscribe to
+<a href="http://groups.google.com/group/golang-announce">golang-announce</a>.
+</p>
+
+<h2 id="resources">Developer Resources</h2>
+
+<h3 id="source"><a href="https://code.google.com/p/go/source">Source Code</a></h3>
+<p>Check out the Go source code.</p>
+
+<h3 id="release"><a href="/doc/devel/release.html">Release History</a></h3>
+<p>A summary of the changes between Go releases.</p>
+
+<h3 id="weekly"><a href="/doc/devel/weekly.html">Weekly Snapshot History</a></h3>
+<p>A summary of the changes between weekly snapshots of Go.</p>
+
+<h3 id="golang-dev"><a href="http://groups.google.com/group/golang-dev">Developer Mailing List</a></h3>
+<p>The <a href="http://groups.google.com/group/golang-dev">golang-dev</a>
+mailing list is for discussing and reviewing code for the Go project.</p>
+<p>For general discussion of Go programming, see <a
+href="http://groups.google.com/group/golang-nuts">golang-nuts</a>.</p>
+
+<h3 id="golang-checkins"><a href="http://groups.google.com/group/golang-checkins">Checkins Mailing List</a></h3>
+<p>A mailing list that receives a message summarizing each checkin to the Go repository.</p>
+
+<h3 id="build_status"><a href="http://build.golang.org/">Build Status</a></h3>
+<p>View the status of Go builds across the supported operating
+systems and architectures.</p>
 
-<div class="left-column">
 
 <h2 id="howto">How you can help</h2>
 
@@ -19,13 +68,13 @@ a new one.)
 We pride ourselves on being meticulous; no issue is too small.
 </p>
 
-<h3><a href="contribute.html">Contributing code</a></h3>
+<h3><a href="/doc/contribute.html">Contributing code</a></h3>
 
 <p>
 Go is an open source project and we welcome contributions from the community.
 </p>
 <p>
-To get started, read these <a href="contribute.html">contribution
+To get started, read these <a href="/doc/contribute.html">contribution
 guidelines</a> for information on design, testing, and our code review process.
 </p>
 <p>
@@ -35,35 +84,25 @@ open issues that interest you. Those labeled
 are particularly in need of outside help.
 </p>
 
-</div>
 
-<div class="right-column">
+<h2 id="community">The Go Community</h2>
 
-<h2 id="the_go_project">The Go Project</h2>
+<h3 id="mailinglist"><a href="http://groups.google.com/group/golang-nuts">Go Nuts Mailing List</a></h3>
+<p>The <a href="http://groups.google.com/group/golang-nuts">golang-nuts</a> 
+mailing list is for general Go discussion.</p>
 
-<h3 id="build_status"><a href="http://godashboard.appspot.com/">Build Status</a></h3>
-<p>View the status of Go builds across the supported operating
-systems and architectures.</p>
+<h3 id="projects"><a href="http://godashboard.appspot.com/project">Go Project Dashboard</a></h3>
+<p>A list of external Go projects including programs and libraries.</p>
 
-<h3 id="roadmap"><a href="devel/roadmap.html">Roadmap</a></h3>
-<p>Features and ideas being developed or discussed by the Go team.</p>
+<h3 id="irc"><a href="irc:irc.freenode.net/go-nuts">Go IRC Channel</a></h3>
+<p><b>#go-nuts</b> on <b>irc.freenode.net</b> is the official Go IRC channel.</p>
 
-<h3 id="release"><a href="devel/release.html">Release History</a></h3>
-<p>A summary of the changes between Go releases.</p>
+<h3 id="plus"><a href="https://plus.google.com/101406623878176903605/posts">The Go Programming Language at Google+</a></h3>
+<p>The Go project's Google+ page.</p>
 
-<h3 id="release"><a href="devel/weekly.html">Weekly Snapshot History</a></h3>
-<p>A summary of the changes between weekly snapshots of Go.</p>
-
-<h3 id="golang-dev"><a href="http://groups.google.com/group/golang-dev">Developer Mailing List</a></h3>
-<p>The <a href="http://groups.google.com/group/golang-dev">golang-dev</a>
-mailing list is for discussing and reviewing code for the Go project.</p>
-<p>For general discussion of Go programming, see <a
-href="http://groups.google.com/group/golang-nuts">golang-nuts</a>.</p>
-
-<h3 id="golang-checkins"><a href="http://groups.google.com/group/golang-checkins">Checkins Mailing List</a></h3>
-<p>A mailing list that receives a message summarizing each checkin to the Go repository.</p>
-
-</div>
-
-<div class="end-columns"></div>
+<h3 id="twitter"><a href="http://twitter.com/go_nuts">@go_nuts at Twitter</a></h3>
+<p>The Go project's official Twitter account.</p>
 
+<h3 id="blog"><a href="http://blog.golang.org/">The Go Blog</a></h3>
+<p>The official blog of the Go project, featuring news and in-depth articles by
+the Go team and guests.</p>

doc/contribute.html

@@ -1,11 +1,13 @@
-<!-- Contribution Guidelines -->
+<!--{
+	"Title": "Contribution Guidelines"
+}-->
 
 <h2 id="Introduction">Introduction</h2>
 
 <p>
 This document explains how to contribute changes to the Go project.
 It assumes you have installed Go using the
-<a href="install.html">installation instructions</a> and
+<a href="/doc/install">installation instructions</a> and
 have <a href="code.html">written and tested your code</a>.
 (Note that the <code>gccgo</code> frontend lives elsewhere;
 see <a href="gccgo_contribute.html">Contributing to gccgo</a>.)
@@ -210,10 +212,10 @@ to this change, and the <code>CC</code> line lists people to
 notify about the change.
 These can be code review nicknames or arbitrary email addresses.
 Unless explicitly told otherwise, such as in the discussion leading
-up to sending in the change list, set the
-reviewer field to the
+up to sending in the change list, leave the reviewer field blank.
+This means that the
 <a href="http://groups.google.com/group/golang-dev">golang-dev@googlegroups.com</a>
-mailing list.
+mailing list will be used as the reviewer.
 </p>
 
 <p>
@@ -402,7 +404,7 @@ $ hg mail -r golang-dev@googlegroups.com --cc math-nuts@swtch.com 99999
 
 <p>
 Running <code>hg mail</code> will send an email to you and the reviewers
-asking them to visit the issue's URL and make coments on the change.
+asking them to visit the issue's URL and make comments on the change.
 When done, the reviewer clicks &ldquo;Publish and Mail comments&rdquo;
 to send comments back.
 </p>
@@ -523,7 +525,7 @@ This rigmarole needs to be done only for your first submission.
 <p>Code that you contribute should use the standard copyright header:</p>
 
 <pre>
-// Copyright 2011 The Go Authors. All rights reserved.
+// Copyright 2012 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 </pre>

doc/debugging_with_gdb.html

@@ -1,22 +1,26 @@
-<!-- title Debugging Go Code with GDB -->
+<!--{
+	"Title": "Debugging Go Code with GDB",
+	"Path": "/doc/gdb"
+}-->
 
 <p><i>
-This applies to the 6g toolchain. Gccgo has native gdb support. Besides this
-overview you might want to consult the
+This applies to the <code>gc</code> toolchain. Gccgo has native gdb support.
+Besides this overview you might want to consult the
 <a href="http://sourceware.org/gdb/current/onlinedocs/gdb/">GDB manual</a>.
 </i></p>
 
 <h2 id="Introduction">Introduction</h2>
 
 <p>
-When you compile and link your Go programs with the 6g/6l or 8g/8l toolchains
-on Linux, Mac OSX or FreeBSD, the resulting binaries contain DWARFv3
-debugging information that recent versions (>7.1) of the GDB debugger can
+When you compile and link your Go programs with the <code>gc</code> toolchain
+on Linux, Mac OS X or FreeBSD, the resulting binaries contain DWARFv3
+debugging information that recent versions (&gt;7.1) of the GDB debugger can
 use to inspect a live process or a core dump.
 </p>
 
 <p>
-Pass the <code>'-s'</code> flag to the linker to omit the debug information.
+Pass the <code>'-s'</code> flag to the linker to omit the debug information
+(for example, <code>go build -ldflags "-s" prog.go</code>).
 </p>
 
 
@@ -25,7 +29,7 @@ Pass the <code>'-s'</code> flag to the linker to omit the debug information.
 <ul>
 <li>
 Show file and line number for code 
-and set breakpoints:
+, set breakpoints and disassemble:
 <pre>(gdb) <b>list</b>
 (gdb) <b>list <i>line</i></b>
 (gdb) <b>list <i>file.go</i>:<i>line</i></b>
@@ -34,7 +38,7 @@ and set breakpoints:
 (gdb) <b>disas</b></pre>
 </li>
 <li>
-Unwind stack frames:
+Show backtraces and unwind stack frames:
 <pre>(gdb) <b>bt</b>
 (gdb) <b>frame <i>n</i></b></pre>
 </li>
@@ -98,7 +102,7 @@ the Go source distribution. It depends on some special magic types
 <code>runtime.g</code>) that the linker
 (<a href="/src/cmd/ld/dwarf.c">src/cmd/ld/dwarf.c</a>) ensures are described in
 the DWARF code.
-</ines
+</p>
 
 <p>
 If you're interested in what the debugging information looks like, run
@@ -125,26 +129,26 @@ the form <code>pkg.(*MyType).Meth</code>.
 <p>
 In this tutorial we will inspect the binary of the
 <a href="/pkg/regexp/">regexp</a> package's unit tests. To build the binary,
-change to <code>$GOROOT/src/pkg/regexp</code> and run <code>gotest</code>.
-This should produce an executable file named <code>6.out</code>.
+change to <code>$GOROOT/src/pkg/regexp</code> and run <code>go test -c</code>.
+This should produce an executable file named <code>regexp.test</code>.
 </p>
 
 
 <h3 id="Getting_Started">Getting Started</h3>
 
 <p>
-Launch GDB, debugging <code>6.out</code>:
+Launch GDB, debugging <code>regexp.test</code>:
 </p>
 
 <pre>
-$ <b>gdb 6.out</b>
+$ <b>gdb regexp.test</b>
 GNU gdb (GDB) 7.2-gg8
 Copyright (C) 2010 Free Software Foundation, Inc.
 License GPLv  3+: GNU GPL version 3 or later &lt;http://gnu.org/licenses/gpl.html&gt;
 Type "show copying" and "show warranty" for licensing/warranty details.
 This GDB was configured as "x86_64-linux".
 
-Reading symbols from  /home/user/go/src/pkg/regexp/6.out...
+Reading symbols from  /home/user/go/src/pkg/regexp/regexp.test...
 done.
 Loading Go Runtime support.
 (gdb) 
@@ -161,7 +165,7 @@ pass your <code>$GOROOT</code> with the <code>'-d'</code> flag:
 </p>
 
 <pre>
-$ <b>gdb 6.out -d $GOROOT</b>
+$ <b>gdb regexp.test -d $GOROOT</b>
 </pre>
 
 <p>
@@ -214,14 +218,13 @@ package is known to GDB as <code>'regexp.Compile'</code>.
 
 <p>
 Methods must be qualified with the name of their receiver types. For example,
-the <code>*Regexp</code> type’s <code>doParse</code> method is known as
-<code>'regexp.*Regexp.doParse'</code>. (Note that the second dot is a "middot,"
-an artifact of Go’s internal representation of methods.)
+the <code>*Regexp</code> type’s <code>String</code> method is known as
+<code>'regexp.(*Regexp).String'</code>.
 </p>
 
 <p>
 Variables that shadow other variables are magically suffixed with a number in the debug info.
-Variables referenced by closures will appear as pointers magically prefixed with '&amp'.
+Variables referenced by closures will appear as pointers magically prefixed with '&amp;'.
 </p>
 
 <h3 id="Setting_breakpoints">Setting breakpoints</h3>
@@ -241,7 +244,7 @@ Run the program:
 
 <pre>
 (gdb) <b>run</b>
-Starting program: /home/lvd/g/src/pkg/regexp/6.out 
+Starting program: /home/user/go/src/pkg/regexp/regexp.test
 
 Breakpoint 1, regexp.TestFind (t=0xf8404a89c0) at /home/user/go/src/pkg/regexp/find_test.go:148
 148	func TestFind(t *testing.T) {
@@ -284,16 +287,18 @@ The other goroutine, number 1, is stuck in <code>runtime.gosched</code>, blocked
 
 <pre>
 (gdb) <b>goroutine 1 bt</b>
-#0  0x000000000040facb in runtime.gosched () at /home/lvd/g/src/pkg/runtime/proc.c:873
+#0  0x000000000040facb in runtime.gosched () at /home/user/go/src/pkg/runtime/proc.c:873
 #1  0x00000000004031c9 in runtime.chanrecv (c=void, ep=void, selected=void, received=void)
- at  /home/lvd/g/src/pkg/runtime/chan.c:342
-#2  0x0000000000403299 in runtime.chanrecv1 (t=void, c=void) at/home/lvd/g/src/pkg/runtime/chan.c:423
-#3  0x000000000043075b in testing.RunTests (matchString={void (struct string, struct string, bool *, 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
+ at  /home/user/go/src/pkg/runtime/chan.c:342
+#2  0x0000000000403299 in runtime.chanrecv1 (t=void, c=void) at/home/user/go/src/pkg/runtime/chan.c:423
+#3  0x000000000043075b in testing.RunTests (matchString={void (struct string, struct string, bool *, error *)}
+ 0x7ffff7f9ef60, tests=  []testing.InternalTest = {...}) at /home/user/go/src/pkg/testing/testing.go:201
+#4  0x00000000004302b1 in testing.Main (matchString={void (struct string, struct string, bool *, error *)} 
+ 0x7ffff7f9ef80, tests= []testing.InternalTest = {...}, benchmarks= []testing.InternalBenchmark = {...})
+at /home/user/go/src/pkg/testing/testing.go:168
+#5  0x0000000000400dc1 in main.main () at /home/user/go/src/pkg/regexp/_testmain.go:98
+#6  0x00000000004022e7 in runtime.mainstart () at /home/user/go/src/pkg/runtime/amd64/asm.s:78
+#7  0x000000000040ea6f in runtime.initdone () at /home/user/go/src/pkg/runtime/proc.c:243
 #8  0x0000000000000000 in ?? ()
 </pre>
 
@@ -304,7 +309,7 @@ The stack frame shows we’re currently executing the <code>regexp.TestFind</cod
 <pre>
 (gdb) <b>info frame</b>
 Stack level 0, frame at 0x7ffff7f9ff88:
- rip = 0x425530 in regexp.TestFind (/home/lvd/g/src/pkg/regexp/find_test.go:148); 
+ rip = 0x425530 in regexp.TestFind (/home/user/go/src/pkg/regexp/find_test.go:148); 
     saved rip 0x430233
  called by frame at 0x7ffff7f9ffa8
  source language minimal.
@@ -343,12 +348,12 @@ $1 = (struct testing.T *) 0xf840688b60
 $1 = (struct testing.T *) 0xf840688b60
 (gdb) p *t
 $2 = {errors = "", failed = false, ch = 0xf8406f5690}
-(gdb) p *t->ch
-$3 = struct hchan<*testing.T>
+(gdb) p *t-&gt;ch
+$3 = struct hchan&lt;*testing.T&gt;
 </pre>
 
 <p>
-That <code>struct hchan<*testing.T></code> is the runtime-internal represntation of a channel.  It is currently empty, or gdb would have pretty-printed it's contents.
+That <code>struct hchan&lt;*testing.T&gt;</code> is the runtime-internal representation of a channel.  It is currently empty, or gdb would have pretty-printed it's contents.
 </p>
 
 <p>
@@ -381,7 +386,7 @@ We can step into the <code>String</code>function call with <code>"s"</code>:
 
 <pre>
 (gdb) <b>s</b>
-regexp.(*Regexp).String (re=0xf84068d070, noname=void) at /home/lvd/g/src/pkg/regexp/regexp.go:97
+regexp.(*Regexp).String (re=0xf84068d070, noname=void) at /home/user/go/src/pkg/regexp/regexp.go:97
 97      func (re *Regexp) String() string {
 </pre>
 
@@ -391,14 +396,13 @@ Get a stack trace to see where we are:
 
 <pre>
 (gdb) <b>bt</b>
-(gdb) bt
 #0  regexp.(*Regexp).String (re=0xf84068d070, noname=void)
-    at /home/lvd/g/src/pkg/regexp/regexp.go:97
+    at /home/user/go/src/pkg/regexp/regexp.go:97
 #1  0x0000000000425615 in regexp.TestFind (t=0xf840688b60)
-    at /home/lvd/g/src/pkg/regexp/find_test.go:151
+    at /home/user/go/src/pkg/regexp/find_test.go:151
 #2  0x0000000000430233 in testing.tRunner (t=0xf840688b60, test=0x5747b8)
-    at /home/lvd/g/src/pkg/testing/testing.go:156
-#3  0x000000000040ea6f in runtime.initdone () at /home/lvd/g/src/pkg/runtime/proc.c:243
+    at /home/user/go/src/pkg/testing/testing.go:156
+#3  0x000000000040ea6f in runtime.initdone () at /home/user/go/src/pkg/runtime/proc.c:243
 ....
 </pre>
 
@@ -439,7 +443,7 @@ you can look inside the runtime representation to do that (tab completion helps
 
 (gdb) <b>p slc</b>
 $11 =  []int = {0, 0}
-(gdb) <b>p slc-&gt</b><i>&ltTAB&gt</i>
+(gdb) <b>p slc-&gt;</b><i>&lt;TAB&gt;</i>
 array  slc    len    
 (gdb) <b>p slc->array</b>
 $12 = (int *) 0xf84057af00
@@ -460,7 +464,7 @@ $24 = 4
 </pre>
 
 <p>
-Channels and maps are 'reference' types, which gdb shows as pointers to C++-like types <code>hash&ltint,string&gt*</code>.  Dereferencing will trigger prettyprinting
+Channels and maps are 'reference' types, which gdb shows as pointers to C++-like types <code>hash&lt;int,string&gt;*</code>.  Dereferencing will trigger prettyprinting
 </p>
 
 <p>

doc/devel/index.html

@@ -1,11 +0,0 @@
-<!-- The Go project -->
-
-<ul>
-<li><a href="roadmap.html">Roadmap</a></li>
-<li><a href="release.html">Release history</a></li>
-<li><a href="weekly.html">Weekly snapshot history</a></li>
-<li><a href="http://godashboard.appspot.com">Build and benchmark status</a></li>
-</ul>
-<ul>
-<li><a href="../contribute.html">Contributing code</a></li>
-</ul>

doc/devel/release.html

@@ -1,4 +1,6 @@
-<!-- Release History -->
+<!--{
+	"Title": "Release History"
+}-->
 
 <p>This page summarizes the changes between official stable releases of Go.
 Between releases we issue less stable
@@ -11,9 +13,28 @@ has full details.</p>
 
 <pre>
 hg pull
-hg update release.r<i>NN</i>
+hg update <i>tag</i>
 </pre>
 
+<h2 id="go1">go1 (released 2012/03/28)</h2>
+
+<p>
+Go 1 is a major release of Go that will be stable in the long term.
+Read the <a href="/doc/go1.html">Go 1 Release Notes</a> for more information.
+</p>
+
+<p>
+It is intended that programs written for Go 1 will continue to compile and run
+correctly, unchanged, under future versions of Go 1.
+Read the <a href="/doc/go1compat.html">Go 1 compatibility document</a> for more
+about the future of Go 1.
+</p>
+
+<p>
+The go1 release corresponds to 
+<code><a href="weekly.html#2012-03-27">weekly.2012-03-27</a></code>.
+</p>
+
 <h2 id="r60">r60 (released 2011/09/07)</h2>
 
 <p>
@@ -110,6 +131,11 @@ r60.2
 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>

doc/devel/roadmap.html

@@ -1,135 +0,0 @@
-<!-- Roadmap -->
-
-<h2 id="Roadmap">Go Roadmap</h2>
-
-<p>
-This page lists features and ideas being developed or discussed by the
-Go team.  This list will be updated as work continues.
-
-<p>
-The roadmap should be discussed on
-the <a href="http://groups.google.com/group/golang-nuts">golang-nuts
-mailing list</a>.
-
-<h3 id="Language_roadmap">
-Language roadmap</h3>
-
-<p>
-This is a list of language changes that are being considered.
-Appearance on this list is no guarantee that the change will be
-accepted.
-
-<ul>
-<li>
-Possibly rewrite restriction on goto across variable declarations.
-<li>
-Variant types.  A way to define a type as being the union of some set
-of types.
-<li>
-Generics.  An active topic of discussion.
-<li>
-Methods for operators, to allow a type to use arithmetic notation for
-expressions.
-<li>
-Possibly allow top-level packages to be given names other than main.
-</ul>
-
-<h3 id="Implementation_roadmap">
-Implementation roadmap</h3>
-
-<ul>
-<li>
-Improved garbage collector.
-<li>
-Debugger.
-<li>
-Improved implementation documentation.
-</ul>
-
-<h4 id="Gc_roadmap">
-Gc compiler roadmap</h4>
-
-<ul>
-<li>
-Implement goto restrictions.
-<li>
-Improved optimization.
-<li>
-Use escape analysis to keep more data on stack.
-</ul>
-
-<h4 id="Gccgo_roadmap">
-Gccgo compiler roadmap</h4>
-
-<ul>
-<li>
-Implement goto restrictions.
-<li>
-Use goroutines rather than threads.
-<li>
-Separate gcc interface from frontend proper.
-<li>
-Use escape analysis to keep more data on stack.
-</ul>
-
-<h4 id="Tools_roadmap">
-Tools roadmap</h4>
-
-<ul>
-<li>
-Strengthen goinstall until it can displace make for most builds.
-</ul>
-
-<h4 id="Packages_roadmap">
-Packages roadmap</h4>
-
-<ul>
-<li>
-Faster, RE2-like regular expressions.
-<li>
-Comprehensive support for international text.
-<li>
-Support for international dates, times, etc.
-<li>
-Support for multilingual messages.
-</ul>
-
-
-<h3 id="done">Done</h3>
-
-<ul>
-<li>
-gc: Generate DWARF debug info.
-<li>
-gc: Provide gdb support for runtime facilities.
-<li>
-Safe compilation mode: generate code that is guaranteed not to obtain an invalid memory address other than via <code>import "unsafe"</code>.
-<li>
-Gccgo: garbage collection.
-<li>
-SWIG support.
-<li>		
-Simpler semicolon rules.
-<li>		
-A more general definition of <code>...</code> in parameter lists.
-<li>		
-Explicit conversions from <code>string</code>		
-to <code>[]byte</code> and <code>[]int</code>.		
-<li>
-A function that will be run by the garbage collector when an item is freed
-(runtime.SetFinalizer).
-<li>
-Public continuous build and benchmark infrastructure (gobuilder).
-<li>
-Package manager (goinstall).
-<li>
-A means of recovering from a panic (recover).
-<li>
-5g: Better floating point support.
-<li>
-Improved CGO including some mechanism for calling back from C to Go.
-<li>
-Faster, allocation-light reflection.
-<li>
-App Engine support.
-</ul>

doc/docs.html

@@ -1,204 +1,145 @@
-<!-- title Documentation -->
+<!--{
+	"Title": "Documentation",
+	"Path": "/doc/"
+}-->
+
+<p>
+The Go programming language is an open source project to make programmers more
+productive.
+</p>
+
+<p>
+Go is expressive, concise, clean, and efficient. Its concurrency
+mechanisms make it easy to write programs that get the most out of multicore
+and networked machines, while its novel type system enables flexible and
+modular program construction. Go compiles quickly to machine code yet has the
+convenience of garbage collection and the power of run-time reflection. It's a
+fast, statically typed, compiled language that feels like a dynamically typed,
+interpreted language.
+</p>
+
+<div id="manual-nav"></div>
+
+<h2>Installing Go</h2>
+
+<h3><a href="/doc/install">Getting Started</a></h3>
+<p>
+Instructions for downloading and installing the Go compilers, tools, and
+libraries.
+</p>
 
-<div class="left-column">
 
 <h2 id="learning">Learning Go</h2>
 
-<p>
-If you're new to Go, we recommend you work through the 
-<a href="go_tutorial.html">tutorial</a>. The 
-<a href="go_spec.html">language specification</a> has all the details should
-you want to explore.
-</p>
-<p>
-Once you've learned a little about the language, 
-<a href="effective_go.html">Effective Go</a> will help you learn the style and
-idioms of programming in Go.
-</p>
+<img class="gopher" src="/doc/gopher/doc.png"/>
 
-<h3 id="go_tour"><a href="http://go-tour.appspot.com/">A Tour of Go</a></h3>
+<h3 id="go_tour"><a href="http://tour.golang.org/">A Tour of Go</a></h3>
 <p>
 An interactive introduction to Go in three sections.
 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
+learned. You can <a href="http://tour.golang.org/">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>
+<h3 id="code"><a href="code.html">How to write Go code</a></h3>
 <p>
-The first tutorial. An introductory text that touches upon several core
-concepts: syntax, types, allocation, constants, I/O, sorting, printing,
-goroutines, and channels.
+How to use the <a href="/cmd/go/">go command</a> to fetch, build, and install
+packages, commands, and run tests.
 </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.
-A must read for any new Go programmer. It augments the tutorial and
+A must read for any new Go programmer. It augments the tour and
 the language specification, both of which should be read first.
 </p>
 
+<h3 id="appengine"><a href="http://code.google.com/appengine/docs/go/gettingstarted/">Getting Started with Go on App Engine</a></h3>
+<p>
+How to develop and deploy a simple Go project with
+<a href="http://code.google.com/appengine/">Google App Engine</a>.
+</p>
+
 <h3 id="go_faq"><a href="go_faq.html">Frequently Asked Questions (FAQ)</a></h3>
 <p>
 Answers to common questions about Go.
 </p>
 
-<h3 id="code"><a href="code.html">How to write Go code</a></h3>
+<h3 id="wiki"><a href="http://code.google.com/p/go-wiki/wiki">Go Language Community Wiki</a></h3>
+<p>A wiki maintained by the Go community.</p>
+
+<h2 id="go1">Go version 1</h2>
+
+<h3 id="go1notes"><a href="/doc/go1.html">Go 1 Release Notes</a></h3>
 <p>
-How to write a new package and how to test code.
+A guide for updating your code to work with Go 1.
 </p>
 
-<h3 id="codelab_wiki"><a href="codelab/wiki/">Codelab: Writing Web Applications</a></h3>
+<h3 id="go1compat"><a href="/doc/go1compat.html">Go 1 and the Future of Go Programs</a></h3>
 <p>
-This codelab takes the reader through the creation of a simple wiki web 
-application. It touches on structs, methods, file I/O, http, regular expressions,
-and closures.
+What Go 1 defines and the backwards-compatibility guarantees one can expect as
+Go 1 matures.
 </p>
 
-<h3 id="codewalks"><a href="codewalk/">Codewalks</a></h3>
+<h2 id="articles">Go Articles</h2>
+
+<h3 id="blog"><a href="http://blog.golang.org/">The Go Blog</a></h3>
+<p>The official blog of the Go project, featuring news and in-depth articles by
+the Go team and guests.</p>
+
+<h4>Codewalks</h4>
 <p>
-Guided tours of Go programs. 
+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>
+<li><a href="/doc/articles/wiki/">Writing Web Applications</a> - building a simple web application.</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>
-
+<h4>Language</h4>
 <ul>
-<li><a href="http://blog.golang.org/2010/04/json-rpc-tale-of-interfaces.html">JSON-RPC: a tale of interfaces</a></li>
-<li><a href="http://blog.golang.org/2010/07/gos-declaration-syntax.html">Go's Declaration Syntax</a></li>
-<li><a href="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="/doc/articles/json_rpc_tale_of_interfaces.html">JSON-RPC: a tale of interfaces</a></li>
+<li><a href="/doc/articles/gos_declaration_syntax.html">Go's Declaration Syntax</a></li>
+<li><a href="/doc/articles/defer_panic_recover.html">Defer, Panic, and Recover</a></li>
+<li><a href="/doc/articles/concurrency_patterns.html">Go Concurrency Patterns: Timing out, moving on</a></li>
+<li><a href="/doc/articles/slices_usage_and_internals.html">Go Slices: usage and internals</a></li>
 <li><a href="http://blog.golang.org/2011/05/gif-decoder-exercise-in-go-interfaces.html">A GIF decoder: an exercise in Go interfaces</a></li>
-<li><a href="http://blog.golang.org/2011/07/error-handling-and-go.html">Error Handling and Go</a></li>
+<li><a href="/doc/articles/error_handling.html">Error Handling and Go</a></li>
 </ul>
 
-<h3>Packages</h3>
-
+<h4>Packages</h4>
 <ul>
-<li><a href="http://blog.golang.org/2011/01/json-and-go.html">JSON and Go</a> - using the <a href="/pkg/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>
+<li><a href="/doc/articles/json_and_go.html">JSON and Go</a> - using the <a href="/pkg/encoding/json/">json</a> package.</li>
+<li><a href="/doc/articles/gobs_of_data.html">Gobs of data</a> - the design and use of the <a href="/pkg/encoding/gob/">gob</a> package.</li>
+<li><a href="/doc/articles/laws_of_reflection.html">The Laws of Reflection</a> - the fundamentals of the <a href="/pkg/reflect/">reflect</a> package.</li>
+<li><a href="/doc/articles/image_package.html">The Go image package</a> - the fundamentals of the <a href="/pkg/image/">image</a> package.</li>
+<li><a href="/doc/articles/image_draw.html">The Go image/draw package</a> - the fundamentals of the <a href="/pkg/image/draw/">image/draw</a> package.</li>
 </ul>
 
-<h3>Tools</h3>
-
+<h4>Tools</h4>
 <ul>
-<li><a href="http://blog.golang.org/2011/03/c-go-cgo.html">C? Go? Cgo!</a> - linking against C code with <a href="/cmd/cgo/">cgo</a>.</li>
-<li><a href="http://blog.golang.org/2011/03/godoc-documenting-go-code.html">Godoc: documenting Go code</a> - writing good documentation for <a href="/cmd/godoc/">godoc</a>.</li>
+<li><a href="/doc/articles/go_command.html">About the Go command</a> - why we wrote it, what it is, what it's not, and how to use it.</li>
+<li><a href="/doc/articles/c_go_cgo.html">C? Go? Cgo!</a> - linking against C code with <a href="/cmd/cgo/">cgo</a>.</li>
+<li><a href="/doc/gdb">Debugging Go Code with GDB</a></li>
+<li><a href="/doc/articles/godoc_documenting_go_code.html">Godoc: documenting Go code</a> - writing good documentation for <a href="/cmd/godoc/">godoc</a>.</li>
 <li><a href="http://blog.golang.org/2011/06/profiling-go-programs.html">Profiling Go Programs</a></li>
 </ul>
 
-<h2 id="tutorials_nonenglish">Non-English Documentation</h2>
+<h2 id="talks">Talks</h2>
 
-<h3 id="docs_be">Belarusian &mdash; Беларуская</h3>
+<img class="gopher" src="/doc/gopher/talks.png"/>
 
-<ul>
-<li><a href="http://www.designcontest.com/show/faq-be">faq-be</a> - Frequently Asked Questions.</li>
-</ul>
-
-<h3 id="docs_cn">Chinese &mdash; 中文</h3>
-
-<ul>
-<li><a href="http://code.google.com/p/golang-china/">golang-china</a> - a broad range of Go documentation.</li>
-<li><a href="http://code.google.com/p/ac-me/downloads/detail?name=fango.pdf">Effective Go and Tutorial</a></li>
-</ul>
-
-<h3 id="docs_de">German &mdash; Deutsch</h3>
-
-<ul>
-<li><a href="http://bitloeffel.de/DOC/golang/go_tutorial_de.html">Eine Anleitung zum Programmieren in Go</a> - the Go Tutorial.</li>
-<li><a href="http://bitloeffel.de/DOC/golang/effective_go_de.html">Wirkungsvoll Go programmieren</a> - Effective Go.</li>
-<li><a href="http://bitloeffel.de/DOC/golang/code_de.html">Wie man Go-Kode schreibt</a> - How to Write Go Code.</li>
-</ul>
-
-<h3 id="docs_jp">Japanese &mdash; 日本語</h3>
-<ul>
-<li><a href="http://golang.jp/">golang.jp</a> - Go documentation and news.
-</ul>
-
-<h3 id="docs_kr">Korean &mdash; 한국어</h3>
-<ul>
-<li><a href="http://code.google.com/p/golang-korea">golang-korea</a> - Go documentation and news.
-</ul>
-
-<h3 id="docs_ru">Russian &mdash; Русский</h3>
-<ul>
-<li><a href="http://golanguage.ru/">golanguage.ru</a> - Go documentation.
-</ul>
-
-</div>
-
-
-<div class="right-column">
-
-<h2 id="References">References</h2>
-
-<p>Keep these under your pillow.</p>
-
-<h3 id="pkg"><a href="/pkg/">Package Documentation</a></h3>
 <p>
-The built-in documentation for the Go standard library.
+The talks marked with a red asterisk (<font color="red">*</font>) were written
+before Go 1 and contain some examples that are no longer correct, but they are
+still of value.
 </p>
 
-<h3 id="cmd"><a href="/cmd/">Command Documentation</a></h3>
-<p>
-The built-in documentation for the Go tools.
-</p>
-
-<h3 id="spec"><a href="go_spec.html">Language Specification</a></h3>
-<p>
-The official Go Language specification. 
-</p>
-
-<h3 id="release"><a href="devel/release.html">Release History</a></h3>
-<p>A summary of the changes between Go releases.</p>
-
-<h3 id="go_mem"><a href="go_mem.html">The Go Memory Model</a></h3>
-<p>
-A document that specifies the conditions under which reads of a variable in
-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>
+<h3 id="writing_web_apps"><a href="http://www.youtube.com/watch?v=-i0hat7pdpk">Writing Web Apps in Go</a><font color="red">*</font></h3>
 <p>
 A talk by Rob Pike and Andrew Gerrand presented at Google I/O 2011.
 It walks through the construction and deployment of a simple web application
@@ -206,7 +147,7 @@ and unveils the <a href="http://blog.golang.org/2011/05/go-and-google-app-engine
 See the <a href="/doc/talks/io2011/Writing_Web_Apps_in_Go.pdf">presentation slides</a>.
 </p>
 
-<h3 id="real_world_go"><a href="http://www.youtube.com/watch?v=7QDVRowyUQA">Real World Go</a></h3>
+<h3 id="real_world_go"><a href="http://www.youtube.com/watch?v=7QDVRowyUQA">Real World Go</a><font color="red">*</font></h3>
 <p>
 A talk by Andrew Gerrand presented at Google I/O Bootcamp 2011.
 It gives a broad overview of Go's type system and concurrency model
@@ -214,15 +155,22 @@ and provides four examples of Go programs that solve real problems.
 See the <a href="/doc/talks/io2011/Real_World_Go.pdf">presentation slides</a>.
 </p>
 
-<h3 id="go_programming"><a href="http://www.youtube.com/watch?v=jgVhBThJdXc">Go Programming</a></h3>
+<h3 id="integrated_apps"><a href="http://www.youtube.com/watch?v=Mo1YKpIF1PQ">Building Integrated Apps on Google's Cloud Platform</a></h3>
+<p>
+A talk by Andrew Gerrand presented at Google Developer Day Japan 2011.
+It discusses the development of a web application that runs on Google
+App Engine and renders images that it stores on Google Cloud Storage.
+</p>
+
+<h3 id="go_programming"><a href="http://www.youtube.com/watch?v=jgVhBThJdXc">Go Programming</a><font color="red">*</font></h3>
 <p>
 A presentation delivered by Rob Pike and Russ Cox at Google I/O 2010.  It
 illustrates how programming in Go differs from other languages through a set of
 examples demonstrating features particular to Go.  These include concurrency,
-embedded types, methods on any type, and program construction using interfaces. 
+embedded types, methods on any type, and program construction using interfaces.
 </p>
 
-<h3 id="practical_go_programming"><a href="http://osdc.blip.tv/file/4432146/">Practical Go Programming</a></h3>
+<h3 id="practical_go_programming"><a href="http://www.youtube.com/watch?v=2-pPAvqyluI">Practical Go Programming</a><font color="red">*</font></h3>
 <p>
 This talk presents the development of a complete web application in Go.
 It looks at design, storage, concurrency, and scaling issues in detail, using
@@ -230,63 +178,37 @@ the simple example of an URL shortening service.
 See the <a href="http://wh3rd.net/practical-go/">presentation slides</a>.
 </p>
 
-<h3 id="techtalk"><a href="http://www.youtube.com/watch?v=rKnDgT73v8s">The Go Tech Talk</a></h3>
+<h4 id="talks_more">More</h4>
 <p>
-An hour-long talk delivered by Rob Pike at Google in October 2009. 
-The language's first public introduction. (See the <a href="talks/go_talk-20091030.pdf">slides in PDF format</a>.) The language has changed since it was made,
-but it's still a good introduction.
+See the <a href="http://code.google.com/p/go-wiki/wiki/GoTalks">GoTalks
+page</a> at the <a href="http://code.google.com/p/go-wiki/wiki">Go Wiki</a> for
+more Go talks.
 </p>
 
-<h3 id="gocoding_channel"><a href="http://www.youtube.com/gocoding">gocoding YouTube Channel</a></h3>
-<p>
-A YouTube channel that includes screencasts and other Go-related videos:
-</p>
-<ul>
-<li><a href="http://www.youtube.com/gocoding#p/u/0/jDWBJOXs_iI">Screencast: Writing Go Packages</a> - writing, building, and distributing Go packages.</li>
-<li><a href="http://www.youtube.com/watch?v=3brH0zOqm0w">Screencast: Testing Go Packages</a> - writing unit tests and benchmarking Go packages.</li>
-</ul>
+<h2 id="nonenglish">Non-English Documentation</h2>
 
-<h3 id="jaoo_go"><a href="/doc/ExpressivenessOfGo.pdf">The Expressiveness Of Go</a></h3>
 <p>
-A discussion of the qualities that make Go an expressive and comprehensible
-language.  The talk was presented by Rob Pike at JAOO 2010.
-The recording of the event was lost due to a hardware error.
+See the <a href="http://code.google.com/p/go-wiki/wiki/NonEnglish">NonEnglish</a> page
+at the <a href="http://code.google.com/p/go-wiki/wiki">Go Wiki</a> for localized
+documentation.
 </p>
 
-<h3 id="oscon_go"><a href="http://www.oscon.com/oscon2010/public/schedule/detail/14760">Another Go at Language Design</a></h3>
-<p>
-A tour, with some background, of the major features of Go, intended for
-an audience new to the language.  The talk was presented at OSCON 2010.
-See the <a href="http://assets.en.oreilly.com/1/event/45/Another%20Go%20at%20Language%20Design%20Presentation.pdf">presentation slides</a>.
-</p>
-<p>
-This talk was also delivered at Sydney University in September 2010. A video
-of the lecture is available 
-<a href="http://sydney.edu.au/engineering/it/videos/seminar_pike">here</a>.
-</p>
+<h2 id="community">The Go Community</h2>
 
-<h3 id="emerging_go"><a href="http://www.oscon.com/oscon2010/public/schedule/detail/15464">Go Emerging Languages Conference Talk</a></h3>
-<p>
-Rob Pike's Emerging Languages Conference presentation delivered in July 2010. See the <a href="http://assets.en.oreilly.com/1/event/45/Go%20Presentation.pdf">presentation slides</a>. Abstract:
-</p>
-<p><i>
-Go’s approach to concurrency differs from that of many languages, even those
-(such as Erlang) that make concurrency central, yet it has deep roots. The path
-from Hoare’s 1978 paper to Go provides insight into how and why Go works as it
-does.
-</i></p>
+<img class="gopher" src="/doc/gopher/project.png"/>
 
-<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.
-</p>
+<h3 id="mailinglist"><a href="http://groups.google.com/group/golang-nuts">Go Nuts Mailing List</a></h3>
+<p>The <a href="http://groups.google.com/group/golang-nuts">golang-nuts</a>
+mailing list is for general Go discussion.</p>
 
-<h3 id="promo_video"><a href="http://www.youtube.com/watch?v=wwoWei-GAPo">The Go Promo Video</a></h3>
-<p>
-A short promotional video featuring Russ Cox demonstrating Go's fast compiler.
-</p>
+<h3 id="projects"><a href="http://godashboard.appspot.com/project">Go Project Dashboard</a></h3>
+<p>A list of external Go projects including programs and libraries.</p>
 
-</div>
+<h3 id="irc"><a href="irc:irc.freenode.net/go-nuts">Go IRC Channel</a></h3>
+<p><b>#go-nuts</b> on <b>irc.freenode.net</b> is the official Go IRC channel.</p>
 
-<div class="end-columns"></div>
+<h3 id="plus"><a href="https://plus.google.com/101406623878176903605/posts">The Go Programming Language at Google+</a></h3>
+<p>The Go project's Google+ page.</p>
+
+<h3 id="twitter"><a href="http://twitter.com/go_nuts">@go_nuts at Twitter</a></h3>
+<p>The Go project's official Twitter account.</p>

doc/effective_go.html

@@ -1,4 +1,7 @@
-<!-- Effective Go -->
+<!--{
+	"Title": "Effective Go",
+	"Template": true
+}-->
 
 <h2 id="introduction">Introduction</h2>
 
@@ -24,8 +27,10 @@ will be easy for other Go programmers to understand.
 
 <p>
 This document gives tips for writing clear, idiomatic Go code.
-It augments the <a href="go_spec.html">language specification</a>
-and the <a href="go_tutorial.html">tutorial</a>, both of which you
+It augments the <a href="/ref/spec">language specification</a>,
+the <a href="http://tour.golang.org/">Tour of Go</a>,
+and <a href="/doc/code.html">How to Write Go Code</a>,
+all of which you
 should read first.
 </p>
 
@@ -59,7 +64,10 @@ prescriptive style guide.
 With Go we take an unusual
 approach and let the machine
 take care of most formatting issues.
-The <code>gofmt</code> tool reads a Go program
+The <code>gofmt</code> program
+(also available as <code>go fmt</code>, which
+operates at the package level rather than source file level)
+reads a Go program
 and emits the source in a standard style of indentation
 and vertical alignment, retaining and if necessary
 reformatting comments.
@@ -221,7 +229,7 @@ starts with the name being declared.
 <pre>
 // Compile parses a regular expression and returns, if successful, a Regexp
 // object that can be used to match against text.
-func Compile(str string) (regexp *Regexp, error os.Error) {
+func Compile(str string) (regexp *Regexp, err error) {
 </pre>
 
 <p>
@@ -233,9 +241,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("regexp: internal error")
-    ErrUnmatchedLpar = os.NewError("regexp: unmatched '('")
-    ErrUnmatchedRpar = os.NewError("regexp: unmatched ')'")
+    ErrInternal      = errors.New("regexp: internal error")
+    ErrUnmatchedLpar = errors.New("regexp: unmatched '('")
+    ErrUnmatchedRpar = errors.New("regexp: unmatched ')'")
     ...
 )
 </pre>
@@ -526,12 +534,62 @@ if err != nil {
 }
 d, err := f.Stat()
 if err != nil {
+    f.Close()
     return err
 }
 codeUsing(f, d)
 </pre>
 
 
+<h3 id="redeclaration">Redeclaration</h3>
+
+<p>
+An aside: The last example in the previous section demonstrates a detail of how the
+<code>:=</code> short declaration form works.
+The declaration that calls <code>os.Open</code> reads,
+</p>
+
+<pre>
+f, err := os.Open(name)
+</pre>
+
+<p>
+This statement declares two variables, <code>f</code> and <code>err</code>.
+A few lines later, the call to <code>f.Stat</code> reads,
+</p>
+
+<pre>
+d, err := f.Stat()
+</pre>
+
+<p>
+which looks as if it declares <code>d</code> and <code>err</code>.
+Notice, though, that <code>err</code> appears in both statements.
+This duplication is legal: <code>err</code> is declared by the first statement,
+but only <em>re-assigned</em> in the second.
+This means that the call to <code>f.Stat</code> uses the existing
+<code>err</code> variable declared above, and just gives it a new value.
+</p>
+
+<p>
+In a <code>:=</code> declaration a variable <code>v</code> may appear even
+if it has already been declared, provided:
+</p>
+
+<ul>
+<li>this declaration is in the same scope as the existing declaration of <code>v</code>
+(if <code>v</code> is already declared in an outer scope, the declaration will create a new variable),</li>
+<li>the corresponding value in the initialization is assignable to <code>v</code>, and</li>
+<li>there is at least one other variable in the declaration that is being declared anew.</li>
+</ul>
+
+<p>
+This unusual property is pure pragmatism,
+making it easy to use a single <code>err</code> value, for example,
+in a long <code>if-else</code> chain.
+You'll see it used often.
+</p>
+
 <h3 id="for">For</h3>
 
 <p>
@@ -567,9 +625,28 @@ or reading from a channel, a <code>range</code> clause can
 manage the loop.
 </p>
 <pre>
-var m map[string]int
+for key, value := range oldMap {
+    newMap[key] = value
+}
+</pre>
+
+<p>
+If you only need the first item in the range (the key or index), drop the second:
+</p>
+<pre>
+for key := range m {
+    if expired(key) {
+        delete(m, key)
+    }
+}
+</pre>
+
+<p>
+If you only need the second item in the range (the value), use the <em>blank identifier</em>, an underscore, to discard the first:
+</p>
+<pre>
 sum := 0
-for _, value := range m {  // key is unused
+for _, value := range array {
     sum += value
 }
 </pre>
@@ -651,7 +728,7 @@ func shouldEscape(c byte) bool {
 Here's a comparison routine for byte arrays that uses two
 <code>switch</code> statements:
 <pre>
-// Compare returns an integer comparing the two byte arrays
+// Compare returns an integer comparing the two byte arrays,
 // lexicographically.
 // The result will be 0 if a == b, -1 if a &lt; b, and +1 if a &gt; b
 func Compare(a, b []byte) int {
@@ -713,16 +790,16 @@ error code secreted away in a volatile location.
 In Go, <code>Write</code>
 can return a count <i>and</i> an error: &ldquo;Yes, you wrote some
 bytes but not all of them because you filled the device&rdquo;.
-The signature of <code>*File.Write</code> in package <code>os</code> is:
+The signature of <code>File.Write</code> in package <code>os</code> is:
 </p>
 
 <pre>
-func (file *File) Write(b []byte) (n int, err Error)
+func (file *File) Write(b []byte) (n int, err error)
 </pre>
 
 <p>
 and as the documentation says, it returns the number of bytes
-written and a non-nil <code>Error</code> when <code>n</code>
+written and a non-nil <code>error</code> when <code>n</code>
 <code>!=</code> <code>len(b)</code>.
 This is a common style; see the section on error handling for more examples.
 </p>
@@ -788,12 +865,12 @@ of <code>io.ReadFull</code> that uses them well:
 </p>
 
 <pre>
-func ReadFull(r Reader, buf []byte) (n int, err os.Error) {
+func ReadFull(r Reader, buf []byte) (n int, err error) {
     for len(buf) &gt; 0 &amp;&amp; err == nil {
         var nr int
         nr, err = r.Read(buf)
         n += nr
-        buf = buf[nr:len(buf)]
+        buf = buf[nr:]
     }
     return
 }
@@ -812,7 +889,7 @@ canonical examples are unlocking a mutex or closing a file.
 
 <pre>
 // Contents returns the file's contents as a string.
-func Contents(filename string) (string, os.Error) {
+func Contents(filename string) (string, error) {
     f, err := os.Open(filename)
     if err != nil {
         return "", err
@@ -825,7 +902,7 @@ func Contents(filename string) (string, os.Error) {
         n, err := f.Read(buf[0:])
         result = append(result, buf[0:n]...) // append is discussed later.
         if err != nil {
-            if err == os.EOF {
+            if err == io.EOF {
                 break
             }
             return "", err  // f will be closed if we return here.
@@ -945,7 +1022,7 @@ but the rules are simple.
 Let's talk about <code>new</code> first.
 It's a built-in function that allocates memory, but unlike its namesakes
 in some other languages it does not <em>initialize</em> the memory,
-it only <em>zeroes</em> it.
+it only <em>zeros</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>.
@@ -954,8 +1031,9 @@ In Go terminology, it returns a pointer to a newly allocated zero value of type
 </p>
 
 <p>
-Since the memory returned by <code>new</code> is zeroed, it's helpful to arrange that the
-zeroed object can be used without further initialization.  This means a user of
+Since the memory returned by <code>new</code> is zeroed, it's helpful to arrange
+when designing your data structures that the
+zero value of each type can be used without further initialization.  This means a user of
 the data structure can create one with <code>new</code> and get right to
 work.
 For example, the documentation for <code>bytes.Buffer</code> states that
@@ -1075,8 +1153,9 @@ m := map[int]string{Enone: "no error", Eio: "Eio", Einval: "invalid argument"}
 Back to allocation.
 The built-in function <code>make(T, </code><i>args</i><code>)</code> serves
 a purpose different from <code>new(T)</code>.
-It creates slices, maps, and channels only, and it returns an initialized (not zero)
-value of type <code>T</code>, not <code>*T</code>.
+It creates slices, maps, and channels only, and it returns an <em>initialized</em>
+(not <em>zeroed</em>)
+value of type <code>T</code> (not <code>*T</code>).
 The reason for the distinction
 is that these three types are, under the covers, references to data structures that
 must be initialized before use.
@@ -1193,7 +1272,7 @@ limit of how much data to read.  Here is the signature of the
 <code>os</code>:
 </p>
 <pre>
-func (file *File) Read(buf []byte) (n int, err os.Error)
+func (file *File) Read(buf []byte) (n int, err error)
 </pre>
 <p>
 The method returns the number of bytes read and an error value, if
@@ -1205,11 +1284,11 @@ any.  To read into the first 32 bytes of a larger buffer
 </pre>
 <p>
 Such slicing is common and efficient.  In fact, leaving efficiency aside for
-the moment, this snippet would also read the first 32 bytes of the buffer.
+the moment, the following snippet would also read the first 32 bytes of the buffer.
 </p>
 <pre>
     var n int
-    var err os.Error
+    var err error
     for i := 0; i &lt; 32; i++ {
         nbytes, e := f.Read(buf[i:i+1])  // Read one byte.
         if nbytes == 0 || e != nil {
@@ -1267,9 +1346,9 @@ values of different types.
 The key can be of any type for which the equality operator is defined,
 such as integers,
 floating point and complex numbers,
-strings, pointers, and interfaces (as long as the dynamic type
-supports equality).  Structs, arrays and slices cannot be used as map keys,
-because equality is not defined on those types.
+strings, pointers, interfaces (as long as the dynamic type
+supports equality), structs and arrays. Slices cannot be used as map keys,
+because equality is not defined on them.
 Like slices, maps are a reference type. If you pass a map to a function
 that changes the contents of the map, the changes will be visible
 in the caller.
@@ -1347,7 +1426,7 @@ func offset(tz string) int {
 </pre>
 <p>
 To test for presence in the map without worrying about the actual value,
-you can use the <em>blank identifier</em>, a simple underscore (<code>_</code>).
+you can use the blank identifier (<code>_</code>).
 The blank identifier can be assigned or declared with any value of any type, with the
 value discarded harmlessly.  For testing just presence in a map, use the blank
 identifier in place of the usual variable for the value.
@@ -1356,13 +1435,13 @@ identifier in place of the usual variable for the value.
 _, present := timeZone[tz]
 </pre>
 <p>
-To delete a map entry, turn the multiple assignment around by placing
-an extra boolean on the right; if the boolean is false, the entry
-is deleted. It's safe to do this even if the key is already absent
+To delete a map entry, use the <code>delete</code>
+built-in function, whose arguments are the map and the key to be deleted.
+It's safe to do this this even if the key is already absent
 from the map.
 </p>
 <pre>
-timeZone["PDT"] = 0, false  // Now on Standard Time
+delete(timeZone, "PDT")  // Now on Standard Time
 </pre>
 
 <h3 id="printing">Printing</h3>
@@ -1392,7 +1471,7 @@ fmt.Println(fmt.Sprint("Hello ", 23))
 </pre>
 <p>
 As mentioned in
-the <a href="go_tutorial.html">tutorial</a>, <code>fmt.Fprint</code>
+the <a href="http://tour.golang.org">Tour</a>, <code>fmt.Fprint</code>
 and friends take as a first argument any object
 that implements the <code>io.Writer</code> interface; the variables <code>os.Stdout</code>
 and <code>os.Stderr</code> are familiar instances.
@@ -1437,7 +1516,7 @@ format <code>%#v</code> prints the value in full Go syntax.
 <pre>
 type T struct {
     a int
-    b float
+    b float64
     c string
 }
 t := &amp;T{ 7, -2.35, "abc\tdef" }
@@ -1507,7 +1586,7 @@ for its final argument to specify that an arbitrary number of parameters (of arb
 can appear after the format.
 </p>
 <pre>
-func Printf(format string, v ...interface{}) (n int, errno os.Error) {
+func Printf(format string, v ...interface{}) (n int, err error) {
 </pre>
 <p>
 Within the function <code>Printf</code>, <code>v</code> acts like a variable of type
@@ -1553,40 +1632,49 @@ Now we have the missing piece we needed to explain the design of
 the <code>append</code> built-in function.  The signature of <code>append</code>
 is different from our custom <code>Append</code> function above.
 Schematically, it's like this:
+</p>
 <pre>
 func append(slice []<i>T</i>, elements...T) []<i>T</i>
 </pre>
+<p>
 where <i>T</i> is a placeholder for any given type.  You can't
 actually write a function in Go where the type <code>T</code>
 is determined by the caller.
 That's why <code>append</code> is built in: it needs support from the
 compiler.
+</p>
 <p>
 What <code>append</code> does is append the elements to the end of
 the slice and return the result.  The result needs to be returned
 because, as with our hand-written <code>Append</code>, the underlying
 array may change.  This simple example
+</p>
 <pre>
 x := []int{1,2,3}
 x = append(x, 4, 5, 6)
 fmt.Println(x)
 </pre>
+<p>
 prints <code>[1 2 3 4 5 6]</code>.  So <code>append</code> works a
 little like <code>Printf</code>, collecting an arbitrary number of
 arguments.
+</p>
 <p>
 But what if we wanted to do what our <code>Append</code> does and
 append a slice to a slice?  Easy: use <code>...</code> at the call
 site, just as we did in the call to <code>Output</code> above.  This
 snippet produces identical output to the one above.
+</p>
 <pre>
 x := []int{1,2,3}
 y := []int{4,5,6}
 x = append(x, y...)
 fmt.Println(x)
 </pre>
+<p>
 Without that <code>...</code>, it wouldn't compile because the types
 would be wrong; <code>y</code> is not of type <code>int</code>.
+</p>
 
 <h2 id="initialization">Initialization</h2>
 
@@ -1620,56 +1708,28 @@ enumerator.  Since <code>iota</code> can be part of an expression and
 expressions can be implicitly repeated, it is easy to build intricate
 sets of values.
 </p>
-<pre>
-type ByteSize float64
-const (
-    _ = iota  // ignore first value by assigning to blank identifier
-    KB ByteSize = 1&lt;&lt;(10*iota)
-    MB
-    GB
-    TB
-    PB
-    EB
-    ZB
-    YB
-)
-</pre>
+{{code "/doc/progs/eff_bytesize.go" `/^type ByteSize/` `/^\)/`}}
 <p>
 The ability to attach a method such as <code>String</code> to a
 type makes it possible for such values to format themselves
 automatically for printing, even as part of a general type.
 </p>
-<pre>
-func (b ByteSize) String() string {
-    switch {
-    case b &gt;= YB:
-        return fmt.Sprintf("%.2fYB", float64(b/YB))
-    case b &gt;= ZB:
-        return fmt.Sprintf("%.2fZB", float64(b/ZB))
-    case b &gt;= EB:
-        return fmt.Sprintf("%.2fEB", float64(b/EB))
-    case b &gt;= PB:
-        return fmt.Sprintf("%.2fPB", float64(b/PB))
-    case b &gt;= TB:
-        return fmt.Sprintf("%.2fTB", float64(b/TB))
-    case b &gt;= GB:
-        return fmt.Sprintf("%.2fGB", float64(b/GB))
-    case b &gt;= MB:
-        return fmt.Sprintf("%.2fMB", float64(b/MB))
-    case b &gt;= KB:
-        return fmt.Sprintf("%.2fKB", float64(b/KB))
-    }
-    return fmt.Sprintf("%.2fB", float64(b))
-}
-</pre>
+{{code "/doc/progs/eff_bytesize.go" `/^func.*ByteSize.*String/` `/^}/`}}
 <p>
-(The <code>float64</code> conversions prevent <code>Sprintf</code> 
-from recurring back through the <code>String</code> method for 
-<code>ByteSize</code>.)
 The expression <code>YB</code> prints as <code>1.00YB</code>,
 while <code>ByteSize(1e13)</code> prints as <code>9.09TB</code>.
 </p>
 
+<p>
+Note that it's fine to call <code>Sprintf</code> and friends in the
+implementation of <code>String</code> methods, but beware of
+recurring into the <code>String</code> method through the nested
+<code>Sprintf</code> call using a string format
+(<code>%s</code>, <code>%q</code>, <code>%v</code>, <code>%x</code> or <code>%X</code>).
+The <code>ByteSize</code> implementation of <code>String</code> is safe
+because it calls <code>Sprintf</code> with <code>%f</code>.
+</p>
+
 <h3 id="variables">Variables</h3>
 
 <p>
@@ -1689,10 +1749,7 @@ var (
 <p>
 Finally, each source file can define its own niladic <code>init</code> function to
 set up whatever state is required.  (Actually each file can have multiple
-<code>init</code> functions.) The only restriction is that, although
-goroutines can be launched during initialization, they will not begin
-execution until it completes; initialization always runs as a single thread
-of execution.
+<code>init</code> functions.)
 And finally means finally: <code>init</code> is called after all the
 variable declarations in the package have evaluated their initializers,
 and those are evaluated only after all the imported packages have been
@@ -1757,7 +1814,7 @@ In fact, we can do even better.  If we modify our function so it looks
 like a standard <code>Write</code> method, like this,
 </p>
 <pre>
-func (p *ByteSlice) Write(data []byte) (n int, err os.Error) {
+func (p *ByteSlice) Write(data []byte) (n int, err error) {
     slice := *p
     // Again as above.
     *p = slice
@@ -1810,33 +1867,7 @@ by the routines in package <code>sort</code> if it implements
 and it could also have a custom formatter.
 In this contrived example <code>Sequence</code> satisfies both.
 </p>
-<pre>
-type Sequence []int
-
-// Methods required by sort.Interface.
-func (s Sequence) Len() int {
-    return len(s)
-}
-func (s Sequence) Less(i, j int) bool {
-    return s[i] &lt; s[j]
-}
-func (s Sequence) Swap(i, j int) {
-    s[i], s[j] = s[j], s[i]
-}
-
-// Method for printing - sorts the elements before printing.
-func (s Sequence) String() string {
-    sort.Sort(s)
-    str := "["
-    for i, elem := range s {
-        if i &gt; 0 {
-            str += " "
-        }
-        str += fmt.Sprint(elem)
-    }
-    return str + "]"
-}
-</pre>
+{{code "/doc/progs/eff_sequence.go" `/^type/` "$"}}
 
 <h3 id="conversions">Conversions</h3>
 
@@ -1868,7 +1899,7 @@ do create a new value.)
 It's an idiom in Go programs to convert the
 type of an expression to access a different
 set of methods. As an example, we could use the existing
-type <code>sort.IntArray</code> to reduce the entire example
+type <code>sort.IntSlice</code> to reduce the entire example
 to this:
 </p>
 <pre>
@@ -1876,14 +1907,14 @@ type Sequence []int
 
 // Method for printing - sorts the elements before printing
 func (s Sequence) String() string {
-    sort.IntArray(s).Sort()
+    sort.IntSlice(s).Sort()
     return fmt.Sprint([]int(s))
 }
 </pre>
 <p>
 Now, instead of having <code>Sequence</code> implement multiple
 interfaces (sorting and printing), we're using the ability of a data item to be
-converted to multiple types (<code>Sequence</code>, <code>sort.IntArray</code>
+converted to multiple types (<code>Sequence</code>, <code>sort.IntSlice</code>
 and <code>[]int</code>), each of which does some part of the job.
 That's more unusual in practice but can be effective.
 </p>
@@ -1912,42 +1943,53 @@ the rest of the code is unaffected by the change of algorithm.
 </p>
 <p>
 A similar approach allows the streaming cipher algorithms
-in the <code>crypto/block</code> package to be
+in the various <code>crypto</code> packages to be
 separated from the block ciphers they chain together.
-By analogy with the <code>bufio</code> package,
-they wrap a <code>Cipher</code> interface
-and return <code>hash.Hash</code>,
-<code>io.Reader</code>, or <code>io.Writer</code>
-interface values, not specific implementations.
+The <code>Block</code> interface
+in the <code>crypto/cipher</code> package specifies the
+behavior of a block cipher, which provides encryption
+of a single block of data.
+Then, by analogy with the <code>bufio</code> package,
+cipher packages that implement this interface
+can be used to construct streaming ciphers, represented
+by the <code>Stream</code> interface, without
+knowing the details of the block encryption.
 </p>
 <p>
-The interface to <code>crypto/block</code> includes:
+The  <code>crypto/cipher</code> interfaces look like this:
 </p>
 <pre>
-type Cipher interface {
+type Block interface {
     BlockSize() int
     Encrypt(src, dst []byte)
     Decrypt(src, dst []byte)
 }
 
-// NewECBDecrypter returns a reader that reads data
-// from r and decrypts it using c in electronic codebook (ECB) mode.
-func NewECBDecrypter(c Cipher, r io.Reader) io.Reader
+type Stream interface {
+    XORKeyStream(dst, src []byte)
+}
+</pre>
 
-// NewCBCDecrypter returns a reader that reads data
-// from r and decrypts it using c in cipher block chaining (CBC) mode
-// with the initialization vector iv.
-func NewCBCDecrypter(c Cipher, iv []byte, r io.Reader) io.Reader
+<p>
+Here's the definition of the counter mode (CTR) stream,
+which turns a block cipher into a streaming cipher; notice
+that the block cipher's details are abstracted away:
+</p>
+
+<pre>
+// NewCTR returns a Stream that encrypts/decrypts using the given Block in
+// counter mode. The length of iv must be the same as the Block's block size.
+func NewCTR(block Block, iv []byte) Stream
 </pre>
 <p>
-<code>NewECBDecrypter</code> and <code>NewCBCReader</code> apply not
+<code>NewCTR</code> applies not
 just to one specific encryption algorithm and data source but to any
-implementation of the <code>Cipher</code> interface and any
-<code>io.Reader</code>.  Because they return <code>io.Reader</code>
-interface values, replacing ECB
-encryption with CBC encryption is a localized change.  The constructor
+implementation of the <code>Block</code> interface and any
+<code>Stream</code>.  Because they return
+interface values, replacing CTR
+encryption with other encryption modes is a localized change.  The constructor
 calls must be edited, but because the surrounding code must treat the result only
-as an <code>io.Reader</code>, it won't notice the difference.
+as a <code>Stream</code>, it won't notice the difference.
 </p>
 
 <h3 id="interface_methods">Interfaces and methods</h3>
@@ -1993,7 +2035,7 @@ func (ctr *Counter) ServeHTTP(w http.ResponseWriter, req *http.Request) {
 <code>http.ResponseWriter</code>.)
 For reference, here's how to attach such a server to a node on the URL tree.
 <pre>
-import "http"
+import "net/http"
 ...
 ctr := new(Counter)
 http.Handle("/counter", ctr)
@@ -2032,7 +2074,7 @@ It's easy to write a function to print the arguments.
 </p>
 <pre>
 func ArgServer() {
-    for i, s := range os.Args {
+    for _, s := range os.Args {
         fmt.Println(s)
     }
 }
@@ -2070,7 +2112,7 @@ to have the right signature.
 <pre>
 // Argument server.
 func ArgServer(w http.ResponseWriter, req *http.Request) {
-    for i, s := range os.Args {
+    for _, s := range os.Args {
         fmt.Fprintln(w, s)
     }
 }
@@ -2078,8 +2120,8 @@ func ArgServer(w http.ResponseWriter, req *http.Request) {
 <p>
 <code>ArgServer</code> now has same signature as <code>HandlerFunc</code>,
 so it can be converted to that type to access its methods,
-just as we converted <code>Sequence</code> to <code>IntArray</code>
-to access <code>IntArray.Sort</code>.
+just as we converted <code>Sequence</code> to <code>IntSlice</code>
+to access <code>IntSlice.Sort</code>.
 The code to set it up is concise:
 </p>
 <pre>
@@ -2116,11 +2158,11 @@ here are their definitions.
 </p>
 <pre>
 type Reader interface {
-    Read(p []byte) (n int, err os.Error)
+    Read(p []byte) (n int, err error)
 }
 
 type Writer interface {
-    Write(p []byte) (n int, err os.Error)
+    Write(p []byte) (n int, err error)
 }
 </pre>
 <p>
@@ -2182,7 +2224,7 @@ satisfy the <code>io</code> interfaces, we would also need
 to provide forwarding methods, like this:
 </p>
 <pre>
-func (rw *ReadWriter) Read(p []byte) (n int, err os.Error) {
+func (rw *ReadWriter) Read(p []byte) (n int, err error) {
     return rw.reader.Read(p)
 }
 </pre>
@@ -2315,7 +2357,7 @@ it can also be seen as a type-safe generalization of Unix pipes.
 They're called <em>goroutines</em> because the existing
 terms&mdash;threads, coroutines, processes, and so on&mdash;convey
 inaccurate connotations.  A goroutine has a simple model: it is a
-function executing in parallel with other goroutines in the same
+function executing concurrently with other goroutines in the same
 address space.  It is lightweight, costing little more than the
 allocation of stack space.
 And the stacks start small, so they are cheap, and grow
@@ -2336,12 +2378,12 @@ exits, silently.  (The effect is similar to the Unix shell's
 background.)
 </p>
 <pre>
-go list.Sort()  // run list.Sort in parallel; don't wait for it. 
+go list.Sort()  // run list.Sort concurrently; don't wait for it. 
 </pre>
 <p>
 A function literal can be handy in a goroutine invocation.
 <pre>
-func Announce(message string, delay int64) {
+func Announce(message string, delay time.Duration) {
     go func() {
         time.Sleep(delay)
         fmt.Println(message)
@@ -2504,8 +2546,8 @@ system, and there's not a mutex in sight.
 <p>
 Another application of these ideas is to parallelize a calculation
 across multiple CPU cores.  If the calculation can be broken into
-separate pieces, it can be parallelized, with a channel to signal
-when each piece completes.
+separate pieces that can execute independently, it can be parallelized,
+with a channel to signal when each piece completes.
 </p>
 <p>
 Let's say we have an expensive operation to perform on a vector of items,
@@ -2547,7 +2589,7 @@ func (v Vector) DoAll(u Vector) {
 </pre>
 
 <p>
-The current implementation of <code>gc</code> (<code>6g</code>, etc.)
+The current implementation of the Go runtime
 will not parallelize this code by default.
 It dedicates only a single core to user-level processing.  An
 arbitrary number of goroutines can be blocked in system calls, but
@@ -2557,8 +2599,10 @@ is if you want CPU parallelism you must tell the run-time
 how many goroutines you want executing code simultaneously.  There
 are two related ways to do this.  Either run your job with environment
 variable <code>GOMAXPROCS</code> set to the number of cores to use
-(default 1); or import the <code>runtime</code> package and call
+or import the <code>runtime</code> package and call
 <code>runtime.GOMAXPROCS(NCPU)</code>.
+A helpful value might be <code>runtime.NumCPU()</code>, which reports the number
+of logical CPUs on the local machine.
 Again, this requirement is expected to be retired as the scheduling and run-time improve.
 </p>
 
@@ -2634,12 +2678,12 @@ the garbage collector for bookkeeping.
 Library routines must often return some sort of error indication to
 the caller.  As mentioned earlier, Go's multivalue return makes it
 easy to return a detailed error description alongside the normal
-return value.  By convention, errors have type <code>os.Error</code>,
-a simple interface.
+return value.  By convention, errors have type <code>error</code>,
+a simple built-in interface.
 </p>
 <pre>
-type Error interface {
-    String() string
+type error interface {
+    Error() string
 }
 </pre>
 <p>
@@ -2654,15 +2698,15 @@ For example, <code>os.Open</code> returns an <code>os.PathError</code>.
 type PathError struct {
     Op string    // "open", "unlink", etc.
     Path string  // The associated file.
-    Error Error  // Returned by the system call.
+    Err error    // Returned by the system call.
 }
 
-func (e *PathError) String() string {
-    return e.Op + " " + e.Path + ": " + e.Error.String()
+func (e *PathError) Error() string {
+    return e.Op + " " + e.Path + ": " + e.Err.Error()
 }
 </pre>
 <p>
-<code>PathError</code>'s <code>String</code> generates
+<code>PathError</code>'s <code>Error</code> generates
 a string like this:
 </p>
 <pre>
@@ -2679,25 +2723,25 @@ it is much more informative than the plain
 <p>
 When feasible, error strings should identify their origin, such as by having
 a prefix naming the package that generated the error.  For example, in package
-image, the string representation for a decoding error due to an unknown format
-is "image: unknown format".
+<code>image</code>, the string representation for a decoding error due to an
+unknown format is "image: unknown format".
 </p>
 
 <p>
 Callers that care about the precise error details can
 use a type switch or a type assertion to look for specific
 errors and extract details.  For <code>PathErrors</code>
-this might include examining the internal <code>Error</code>
+this might include examining the internal <code>Err</code>
 field for recoverable failures.
 </p>
 
 <pre>
 for try := 0; try &lt; 2; try++ {
-    file, err = os.Open(filename)
+    file, err = os.Create(filename)
     if err == nil {
         return
     }
-    if e, ok := err.(*os.PathError); ok &amp;&amp; e.Error == os.ENOSPC {
+    if e, ok := err.(*os.PathError); ok &amp;&amp; e.Err == syscall.ENOSPC {
         deleteTempFiles()  // Recover some space.
         continue
     }
@@ -2705,13 +2749,25 @@ for try := 0; try &lt; 2; try++ {
 }
 </pre>
 
+<p>
+The second <code>if</code> statement here is idiomatic Go.
+The type assertion <code>err.(*os.PathError)</code> is
+checked with the "comma ok" idiom (mentioned <a href="#maps">earlier</a>
+in the context of examining maps).
+If the type assertion fails, <code>ok</code> will be false, and <code>e</code>
+will be <code>nil</code>.
+If it succeeds,  <code>ok</code> will be true, which means the
+error was of type <code>*os.PathError</code>, and then so is <code>e</code>,
+which we can examine for more information about the error.
+</p>
+
 <h3 id="panic">Panic</h3>
 
 <p>
 The usual way to report an error to a caller is to return an
-<code>os.Error</code> as an extra return value.  The canonical
+<code>error</code> as an extra return value.  The canonical
 <code>Read</code> method is a well-known instance; it returns a byte
-count and an <code>os.Error</code>.  But what if the error is
+count and an <code>error</code>.  But what if the error is
 unrecoverable?  Sometimes the program simply cannot continue.
 </p>
 
@@ -2827,14 +2883,14 @@ cleanly by calling <code>panic</code>.  We can use that idea to
 simplify error handling in complex software.  Let's look at an
 idealized excerpt from the <code>regexp</code> package, which reports
 parsing errors by calling <code>panic</code> with a local
-<code>Error</code> type.  Here's the definition of <code>Error</code>,
+error type.  Here's the definition of <code>Error</code>,
 an <code>error</code> method, and the <code>Compile</code> function.
 </p>
 
 <pre>
-// Error is the type of a parse error; it satisfies os.Error.
+// Error is the type of a parse error; it satisfies the error interface.
 type Error string
-func (e Error) String() string {
+func (e Error) Error() string {
     return string(e)
 }
 
@@ -2845,7 +2901,7 @@ func (regexp *Regexp) error(err string) {
 }
 
 // Compile returns a parsed representation of the regular expression.
-func Compile(str string) (regexp *Regexp, err os.Error) {
+func Compile(str string) (regexp *Regexp, err error) {
     regexp = new(Regexp)
     // doParse will panic if there is a parse error.
     defer func() {
@@ -2863,7 +2919,7 @@ If <code>doParse</code> panics, the recovery block will set the
 return value to <code>nil</code>&mdash;deferred functions can modify
 named return values.  It then will then check, in the assignment
 to <code>err</code>, that the problem was a parse error by asserting
-that it has type <code>Error</code>.
+that it has the local type <code>Error</code>.
 If it does not, the type assertion will fail, causing a run-time error
 that continues the stack unwinding as though nothing had interrupted
 it.  This check means that if something unexpected happens, such
@@ -2881,7 +2937,7 @@ the parse stack by hand.
 <p>
 Useful though this pattern is, it should be used only within a package.
 <code>Parse</code> turns its internal <code>panic</code> calls into
-<code>os.Error</code> values; it does not expose <code>panics</code>
+<code>error</code> values; it does not expose <code>panics</code>
 to its client.  That is a good rule to follow.
 </p>
 
@@ -2917,66 +2973,7 @@ for instance, a URL, saving you typing the URL into the phone's tiny keyboard.
 Here's the complete program.
 An explanation follows.
 </p>
-
-<pre>
-package main
-
-import (
-    "flag"
-    "http"
-    "io"
-    "log"
-    "old/template" // New template package coming soon...
-)
-
-var addr = flag.String("addr", ":1718", "http service address") // Q=17, R=18
-var fmap = template.FormatterMap{
-    "html": template.HTMLFormatter,
-    "url+html": UrlHtmlFormatter,
-}
-var templ = template.MustParse(templateStr, fmap)
-
-func main() {
-    flag.Parse()
-    http.Handle("/", http.HandlerFunc(QR))
-    err := http.ListenAndServe(*addr, nil)
-    if err != nil {
-        log.Fatal("ListenAndServe:", err)
-    }
-}
-
-func QR(w http.ResponseWriter, req *http.Request) {
-    templ.Execute(w, req.FormValue("s"))
-}
-
-func UrlHtmlFormatter(w io.Writer, fmt string, v ...interface{}) {
-    template.HTMLEscape(w, []byte(http.URLEscape(v[0].(string))))
-}
-
-
-const templateStr = `
-&lt;html&gt;
-&lt;head&gt;
-&lt;title&gt;QR Link Generator&lt;/title&gt;
-&lt;/head&gt;
-&lt;body&gt;
-{.section @}
-&lt;img src="http://chart.apis.google.com/chart?chs=300x300&amp;cht=qr&amp;choe=UTF-8&amp;chl={@|url+html}"
-/&gt;
-&lt;br&gt;
-{@|html}
-&lt;br&gt;
-&lt;br&gt;
-{.end}
-&lt;form action="/" name=f method="GET"&gt;&lt;input maxLength=1024 size=70
-name=s value="" title="Text to QR Encode"&gt;&lt;input type=submit
-value="Show QR" name=qr&gt;
-&lt;/form&gt;
-&lt;/body&gt;
-&lt;/html&gt;
-`
-</pre>
-
+{{code "/doc/progs/eff_qr.go"}}
 <p>
 The pieces up to <code>main</code> should be easy to follow.
 The one flag sets a default HTTP port for our server.  The template
@@ -2995,34 +2992,30 @@ server; it blocks while the server runs.
 executes the template on the data in the form value named <code>s</code>.
 </p>
 <p>
-The template package, inspired by <a
-href="http://code.google.com/p/json-template">json-template</a>, is
-powerful;
+The template package is powerful;
 this program just touches on its capabilities.
 In essence, it rewrites a piece of text on the fly by substituting elements derived
 from data items passed to <code>templ.Execute</code>, in this case the
 form value.  
 Within the template text (<code>templateStr</code>),
-brace-delimited pieces denote template actions.
-The piece from the <code>{.section @}</code>
-to <code>{.end}</code> executes with the value of the data item <code>@</code>,
-which is a shorthand for &ldquo;the current item&rdquo;, which is the form value.
-(When the string is empty, this piece of the template is suppressed.)
+double-brace-delimited pieces denote template actions.
+The piece from <code>{{html "{{if .}}"}}</code>
+to <code>{{html "{{end}}"}}</code> executes only if the value of the current data item, called <code>.</code> (dot),
+is non-empty.
+That is, when the string is empty, this piece of the template is suppressed.
 </p>
 <p>
-The snippet <code>{@|url+html}</code> says to run the data through the formatter
-installed in the formatter map (<code>fmap</code>)
-under the name <code>"url+html"</code>.
-That is the function <code>UrlHtmlFormatter</code>, which sanitizes the string
+The snippet <code>{{html "{{urlquery .}}"}}</code> says to process the data with the function
+<code>urlquery</code>, which sanitizes the query string
 for safe display on the web page.
 </p>
 <p>
 The rest of the template string is just the HTML to show when the page loads.
-If this is too quick an explanation, see the <a href="/pkg/template/">documentation</a>
+If this is too quick an explanation, see the <a href="/pkg/text/template/">documentation</a>
 for the template package for a more thorough discussion.
 </p>
 <p>
-And there you have it: a useful webserver in a few lines of code plus some
+And there you have it: a useful web server in a few lines of code plus some
 data-driven HTML text.
 Go is powerful enough to make a lot happen in a few lines.
 </p>

doc/frontpage.css

@@ -1,143 +0,0 @@
-/* Overloads to all.css */
-#container { width: 76em }
-.left-column { width: 48%; }
-.right-column { width: 48%; }
-
-/* Frontpage styles */
-#content-introductory code {
-  font-family: "Bitstream Vera Sans Mono", "Andale Mono", monospace;
-}
-#content-introductory input, select, textarea {
-  font-family: "Bitstream Vera Sans", Verdana, sans-serif;
-  font-size: 1em;
-}
-span.keyword {
-  font-family: Cambria, Georgia, Times, "Times New Roman", serif;
-  font-size: 1.15em;
-  font-style: italic;
-}
-#content h3, #content h2 {
-  margin: 0;
-  font-size: 1em;
-  background: none;
-  border: none;
-  padding: 0;
-}
-#content .more {
- color: #999;
- font-weight: normal;
-}
-#frontpage h2#branding-tagline {
-	font-weight: normal;
-	font-style: italic;
-}
-#resources {
-  position: relative;
-  margin-top: 1em;
-}
-#resources h3 {
-  margin-top: 0; 
-  margin-bottom: -.5em;
-  font-size: 1em;
-  font-weight: normal;
-}
-#resources-users {
-  float: left;
-  width: 48%;
-}
-#resources-contributors {
-  float: right;
-  width: 50%;
-}
-#resources ul {
-  padding-left: 2em;
-}
-#resources li {
-  margin-bottom: 0.5em;
-}
-#content-rotating {
-  height: 200px;
-}
-#content-videos {
-  float: left;
-  width: 170px;
-}
-#content-videos .thumbnail {
-  width: 150px;
-  height: 103px;
-  background-repeat: no-repeat;
-  border: none;
-}
-#content-videos .thumbnail._001 {
-  background: url(/doc/video-001.png);
-}
-#content-videos .thumbnail._002 {
-  background: url(/doc/video-002.png);
-}
-#content-videos .thumbnail._003 {
-  background: url(/doc/video-003.png);
-}
-#content-videos .thumbnail._004 {
-  background: url(/doc/video-004.png);
-}
-#content-videos .thumbnail._005 {
-  background: url(/doc/video-005.jpg);
-}
-#content-videos a.video {
-  display: inline-block;
-  width: 150px;
-  margin-right: .30em;
-  margin-top: 1.2em;
-}                        
-#content-videos a.video .caption {
-  display: block;
-  text-align: center;
-}
-#content-videos a.video .caption.title {
-  margin-top: .31em;
-  font-weight: bold;
-}
-#content-blog ul {
-  margin-top: 1em;
-  margin-left: 0;
-  padding-left: 0;
-}
-#content-blog li {
-  list-style: none;
-  margin-bottom: 1em;
-}
-#content-blog li a {
-  color: #999;
-  text-decoration: none;
-}
-#content-blog .date {
-  color: #999;
-  font-size: 0.8em;
-  display: inline-block;
-  margin-left: 0.5em;
-}
-#content-blog li a:link .title {
-  color: #04a;
-}
-#content-blog li a:visited .title {
-  color: #04a;
-}
-#content-blog li a:hover .title {
-  color: #a40;
-  text-decoration: underline;
-}
-#content-blog li a:active .title {
-  color: #c00;
-}
-.navtop {
-  display: none !important;
-}
-.how {
-  float: right;
-  font-size: 75%;
-}
-.unsupported {
-  font-weight: bold;
-  color: red;
-}
-

doc/gccgo_contribute.html

@@ -1,92 +1,99 @@
-<!-- Contributing to the gccgo frontend -->
+<!--{
+	"Title": "Contributing to the gccgo frontend"
+}-->
 
 <h2>Introduction</h2>
 
 <p>
-These are some notes on contributing to the <code>gccgo</code>
-frontend for GCC.  For information on contributing to parts of Go other
-than <code>gccgo</code>, see <a href="contribute.html">Contributing to
-the Go project</a>.  For information on building <code>gccgo</code>
-for yourself, see <a href="gccgo_install.html">Setting up and using
-gccgo</a>.
+These are some notes on contributing to the gccgo frontend for GCC.
+For information on contributing to parts of Go other than gccgo,
+see <a href="/doc/contribute.html">Contributing to the Go project</a>.  For
+information on building gccgo for yourself,
+see <a href="/doc/gccgo_install.html">Setting up and using gccgo</a>.
 </p>
 
 <h2>Legal Prerequisites</h2>
 
 <p>
-You must follow the <a href="contribute.html#copyright">Go copyright
-rules.</a>
+You must follow the <a href="/doc/contribute.html#copyright">Go copyright
+rules</a> for all changes to the gccgo frontend and the associated
+libgo library.  Code that is part of GCC rather than gccgo must follow
+the general <a href="http://gcc.gnu.org/contribute.html">GCC
+contribution rules</a>.
 </p>
 
 <h2>Code</h2>
 
 <p>
-The source code for the <code>gccgo</code> frontend may be found at
+The master sources for the gccgo frontend may be found at
 <a href="http://code.google.com/p/gofrontend">http://code.google.com/p/gofrontend</a>.
-Changes made to that project are routinely merged into the source code
-hosted at <code>gcc.gnu.org</code>.  The <code>gofrontend</code>
-project includes only the Go frontend proper.  These are the files
-which in the <code>gcc</code> sources may be found in the
-directories <code>gcc/go</code> and <code>libgo</code>.
-The <code>gcc</code> sources also include a copy of
-the <code>test</code> directory
-from <a href="http://code.google.com/p/go">the main Go repository</a>.
-
-<p>
-The frontend is written in C++ and as such the GNU coding standards do
-not entirely apply; in writing code for the frontend, follow the
-formatting of the surrounding code.  Although the frontend is
-currently closely tied to the rest of the <code>gcc</code> codebase,
-we plan to make it more independent.  Any new code that uses other
-parts of <code>gcc</code> should be placed in an appropriate file,
-such as <code>gogo-tree.cc</code>.  Eventually
-all <code>gcc</code>-specific code should migrate to
-a <code>gcc-interface</code> subdirectory.
+The master sources are not buildable by themselves, but only in
+conjunction with GCC (in the future, other compilers may be
+supported).  Changes made to the gccgo frontend are also applied to
+the GCC source code repository hosted at <code>gcc.gnu.org</code>.  In
+the <code>gofrontend</code> repository, the <code>go</code> directory
+is mirrored to the <code>gcc/go/gofrontend</code> directory in the GCC
+repository, and the <code>gofrontend</code> <code>libgo</code>
+directory is mirrored to the GCC <code>libgo</code> directory.  In
+addition, the <code>test</code> directory
+from <a href="http://code.google.com/p/go">the main Go repository</a>
+is mirrored to the <code>gcc/testsuite/go.test/test</code> directory
+in the GCC repository.
 </p>
 
 <p>
-The run-time library for <code>gccgo</code> is mostly the same as the
-library in <a href="http://code.google.com/p/go">the main Go
-repository</a>.  The library code in the Go repository is periodically
-copied into the <code>gofrontend</code> and the <code>gcc</code>
-repositories.  Accordingly, most library changes should be made in the
-main Go repository.  Changes to the few <code>gccgo</code>-specific
-parts of the library should follow the process described here.
-The <code>gccgo</code>-specific parts of the library are everything in
-the <code>libgo</code> directory except for the <code>libgo/go</code>
-subdirectory.
+Changes to these directories always flow from the master sources to
+the GCC repository.  The files should never be changed in the GCC
+repository except by changing them in the master sources and mirroring
+them.
+</p>
+
+<p>
+The gccgo frontend is written in C++.  It follows the GNU coding
+standards to the extent that they apply to C++.  In writing code for
+the frontend, follow the formatting of the surrounding code.  Although
+the frontend is currently tied to the rest of the GCC codebase, we
+plan to make it more independent.  Eventually all GCC-specific code
+will migrate out of the frontend proper and into GCC proper.  In the
+GCC sources this will generally mean moving code
+from <code>gcc/go/gofrontend</code> to <code>gcc/go</code>.
+</p>
+
+<p>
+The run-time library for gccgo is mostly the same as the library
+in <a href="http://code.google.com/p/go">the main Go repository</a>.
+The library code in the Go repository is periodically merged into
+the <code>libgo/go</code> directory of the <code>gofrontend</code> and
+then the GCC repositories, using the shell
+script <code>libgo/merge.sh</code>.  Accordingly, most library changes
+should be made in the main Go repository.  The files outside
+of <code>libgo/go</code> are gccgo-specific; that said, some of the
+files in <code>libgo/runtime</code> are based on files
+in <code>src/pkg/runtime</code> in the main Go repository.
 </p>
 
 <h2>Testing</h2>
 
 <p>
-All patches must be tested.  There are two test suites.  A patch that
-introduces new failures is not acceptable.
+All patches must be tested.  A patch that introduces new failures is
+not acceptable.
 </p>
 
 <p>
-To run the compiler test suite, run <code>make check-go</code> in the
-<code>gcc</code> subdirectory of your build directory.  This will run
-various tests underneath <code>gcc/testsuite/go.*</code>.  This
-includes a copy of the tests in the main Go repository, which are run
-using the DejaGNU script found in
-in <code>gcc/testsuite/go.test/go-test.exp</code>.  Many of the
-compiler tests may be run without the Go library, but some do require
-the library to built first.
+To run the gccgo test suite, run <code>make check-go</code> in your
+build directory.  This will run various tests
+under <code>gcc/testsuite/go.*</code> and will also run
+the <code>libgo</code> testsuite.  This copy of the tests from the
+main Go repository is run using the DejaGNU script found in
+in <code>gcc/testsuite/go.test/go-test.exp</code>.
 </p>
 
 <p>
-To run the library test suite, run <code>make
-check-target-libgo</code> in the top level of your build directory.
-</p>
-
-<p>
-Most new tests should be submitted to the main Go repository for
-copying into the <code>gccgo</code> repository.  If there is a need
-for specific tests for <code>gccgo</code>, they should go in
+Most new tests should be submitted to the main Go repository for later
+mirroring into the GCC repository.  If there is a need for specific
+tests for gccgo, they should go in
 the <code>gcc/testsuite/go.go-torture</code>
-or <code>gcc/testsuite/go.dg</code> directories in
-the <code>gcc.gnu.org</code> repository.
+or <code>gcc/testsuite/go.dg</code> directories in the GCC repository.
 </p>
 
 <h2>Submitting Changes</h2>
@@ -95,5 +102,5 @@ the <code>gcc.gnu.org</code> repository.
 Changes to the Go frontend should follow the same process as for the
 main Go repository, only for the <code>gofrontend</code> project
 rather than the <code>go</code> project.  Those changes will then be
-merged into the <code>gcc</code> sources.
+merged into the GCC sources.
 </p>

doc/gccgo_install.html

@@ -1,37 +1,63 @@
-<!-- Setting up and using gccgo -->
+<!--{
+	"Title": "Setting up and using gccgo",
+	"Path": "/doc/install/gccgo"
+}-->
 
 <p>
-This document explains how to use <code>gccgo</code>, a compiler for
-the Go language.  The <code>gccgo</code> compiler is a new frontend
-for <code>gcc</code>, the widely used GNU compiler.  Although the
-frontend itself is under a BSD-style license, <code>gccgo</code> is
-normally used as part of <code>gcc</code> and is then covered by
+This document explains how to use gccgo, a compiler for
+the Go language.  The gccgo compiler is a new frontend
+for GCC, the widely used GNU compiler.  Although the
+frontend itself is under a BSD-style license, gccgo is
+normally used as part of GCC and is then covered by
 the <a href="http://www.gnu.org/licenses/gpl.html">GNU General Public
-License</a>.
+License</a> (the license covers gccgo itself as part of GCC; it
+does not cover code generated by gccgo).
 </p>
 
 <p>
-Note that <code>gccgo</code> is not the <code>6g</code> compiler; see
-the <a href="install.html">Installing Go</a> instructions for that
+Note that gccgo is not the <code>gc</code> compiler; see
+the <a href="/doc/install.html">Installing Go</a> instructions for that
 compiler.
 </p>
 
+<h2 id="Releases">Releases</h2>
+
+<p>
+The simplest way to install gccgo is to install a GCC binary release
+built to include Go support.  GCC binary releases are available from
+<a href="http://gcc.gnu.org/install/binaries.html">various
+websites</a> and are typically included as part of GNU/Linux
+distributions.  We expect that most people who build these binaries
+will include Go support.
+</p>
+
+<p>
+The GCC 4.7.0 release includes Go support that is very close to
+<a href="/doc/go1.html">Go 1</a>.  Due to release timing it will not
+include the last few changes to the Go 1 libraries.  The GCC 4.7.1
+release should include a complete Go 1 compiler and libraries.
+</p>
+
 <h2 id="Source_code">Source code</h2>
 
 <p>
-The <code>gccgo</code> source code is accessible via Subversion.  The
-<code>gcc</code> web site
+If you cannot use a release, or prefer to build gccgo for
+yourself, 
+the gccgo source code is accessible via Subversion.  The
+GCC web site
 has <a href="http://gcc.gnu.org/svn.html">instructions for getting the
-<code>gcc</code> source code</a>.  The <code>gccgo</code> source code
-is a branch of the main <code>gcc</code> code
+GCC source code</a>.  The gccgo source code is included.  As a
+convenience, a stable version of the Go support is available in
+a branch of the main GCC code
 repository: <code>svn://gcc.gnu.org/svn/gcc/branches/gccgo</code>.
+This branch is periodically updated with stable Go compiler sources.
 </p>
 
 <p>
 Note that although <code>gcc.gnu.org</code> is the most convenient way
-to get the source code for the compiler, that is not where the master
-sources live.  If you want to contribute changes to the gccgo
-compiler, see <a href="gccgo_contribute.html">Contributing to
+to get the source code for the Go frontend, it is not where the master
+sources live.  If you want to contribute changes to the Go frontend
+compiler, see <a href="/doc/gccgo_contribute.html">Contributing to
 gccgo</a>.
 </p>
 
@@ -39,29 +65,37 @@ gccgo</a>.
 <h2 id="Building">Building</h2>
 
 <p>
-Building <code>gccgo</code> is just like building <code>gcc</code>
+Building gccgo is just like building GCC
 with one or two additional options.  See
 the <a href="http://gcc.gnu.org/install/">instructions on the gcc web
 site</a>.  When you run <code>configure</code>, add the
 option <code>--enable-languages=c,c++,go</code> (along with other
 languages you may want to build).  If you are targeting a 32-bit x86,
-then you will want to build <code>gccgo</code> to default to
+then you will want to build gccgo to default to
 supporting locked compare and exchange instructions; do this by also
 using the <code>configure</code> option <code>--with-arch=i586</code>
 (or a newer architecture, depending on where you need your programs to
-run).
+run).  If you are targeting a 64-bit x86, but sometimes want to use
+the <code>-m32</code> option, then use the <code>configure</code>
+option <code>--with-arch-32=i586</code>.
+</p>
+
+<h3 id="Gold">Gold</h3>
+
+<p>
+On x86 GNU/Linux systems the gccgo compiler is able to
+use a small discontiguous stack for goroutines.  This permits programs
+to run many more goroutines, since each goroutine can use a relatively
+small stack.  Doing this requires using the gold linker version 2.22
+or later.  You can either install GNU binutils 2.22 or later, or you
+can build gold yourself.
 </p>
 
 <p>
-On x86 GNU/Linux systems the <code>gccgo</code> compiler is able to
-use a small discontiguous stack for goroutines.  This permits programs
-to run many more goroutines, since each goroutine can use a relatively
-small stack.  Doing this requires using a development version of
-the <code>gold</code> linker.  The easiest way to do this is to build
-the GNU binutils, using <code>--enable-gold</code> when you run
-the <code>configure</code> script, and to
-use <code>--with-ld=GOLD_BINARY</code> when you
-configure <code>gccgo</code>.  A typical sequence would look like
+To build gold yourself, build the GNU binutils,
+using <code>--enable-gold=default</code> when you run
+the <code>configure</code> script.  Before building, you must install
+the flex and bison packages.  A typical sequence would look like
 this (you can replace <code>/opt/gold</code> with any directory to
 which you have write access):
 </p>
@@ -69,38 +103,79 @@ which you have write access):
 <pre>
 cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src login
 [password is "anoncvs"]
+[The next command will create a directory named src, not binutils]
 cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src co binutils
 mkdir binutils-objdir
 cd binutils-objdir
-../src/configure --enable-gold --prefix=/opt/gold
+../src/configure --enable-gold=default --prefix=/opt/gold
 make
 make install
 </pre>
 
 <p>
-A number of prerequisites are required to build <code>gcc</code>, as
-described on the <a href="http://gcc.gnu.org/">gcc web site</a>.  If
-those are all available, then a typical build and install sequence
-would look like this (only use the <code>--with-ld</code> option if
-you built and installed the gold linker as described above):
+However you install gold, when you configure gccgo, use the
+option <code>--with-ld=<var>GOLD_BINARY</var></code>.
+</p>
+
+<h3 id="Prerequisites">Prerequisites</h3>
+
+<p>
+A number of prerequisites are required to build GCC, as
+described on
+the <a href="http://gcc.gnu.org/install/prerequisites.html">gcc web
+site</a>.  It is important to install all the prerequisites before
+running the gcc <code>configure</code> script.
+
+<h3 id="Build_commands">Build commands</h3>
+
+<p>
+Once all the prerequisites are installed, then a typical build and
+install sequence would look like this (only use
+the <code>--with-ld</code> option if you are using the gold linker as
+described above):
 </p>
 
 <pre>
 svn checkout svn://gcc.gnu.org/svn/gcc/branches/gccgo gccgo
 mkdir objdir
 cd objdir
-../gccgo/configure --enable-languages=c,c++,go --with-ld=/opt/gold/bin/ld
+../gccgo/configure --prefix=/opt/gccgo --enable-languages=c,c++,go --with-ld=/opt/gold/bin/ld
 make
 make install
 </pre>
 
+<h3 id="Ubuntu">A note on Ubuntu</h3>
+
+<p>
+Current versions of Ubuntu and current versions of gcc disagree on
+where system libraries and header files are found.  This is not a
+gccgo issue, and we hope this will be resolved soon.  Until it is,
+setting these environment variables while configuring and building
+gccgo may fix the problem.
+</p>
+
+<pre>
+LIBRARY_PATH=/usr/lib/x86_64-linux-gnu
+C_INCLUDE_PATH=/usr/include/x86_64-linux-gnu
+CPLUS_INCLUDE_PATH=/usr/include/x86_64-linux-gnu
+export LIBRARY_PATH C_INCLUDE_PATH CPLUS_INCLUDE_PATH
+</pre>
+
 <h2 id="Using_gccgo">Using gccgo</h2>
 
 <p>
-The <code>gccgo</code> compiler works like other gcc frontends.
+The gccgo compiler works like other gcc frontends.  The gccgo
+installation does not currently include a version of
+the <code>go</code> command.  However if you have the <code>go</code>
+command from an installation of the <code>gc</code> compiler, you can
+use it with gccgo by passing the option <code>-compiler gccgo</code>
+to <code>go build</code> or <code>go install</code> or <code>go
+test</code>.
+</p>
 
 <p>
-To compile a file:
+To compile a file without using the <code>go</code> command:
+</p>
 
 <pre>
 gccgo -c file.go
@@ -109,6 +184,7 @@ gccgo -c file.go
 <p>
 That produces <code>file.o</code>. To link files together to form an
 executable:
+</p>
 
 <pre>
 gccgo -o file file.o
@@ -116,44 +192,68 @@ gccgo -o file file.o
 
 <p>
 To run the resulting file, you will need to tell the program where to
-find the compiled Go packages. This can be done either by setting
-<code>LD_LIBRARY_PATH</code> in your environment:
+find the compiled Go packages.  There are a few ways to do this:
+</p>
+
+<ul>
+<li>
+<p>
+Set the <code>LD_LIBRARY_PATH</code> environment variable:
+</p>
 
 <pre>
-LD_LIBRARY_PATH=/usr/lib/gcc/MACHINE/VERSION
+LD_LIBRARY_PATH=${prefix}/lib/gcc/MACHINE/VERSION
+[or]
+LD_LIBRARY_PATH=${prefix}/lib64/gcc/MACHINE/VERSION
+export LD_LIBRARY_PATH
 </pre>
 
 <p>
-or by passing a <code>-Wl,-R</code> option when you link:
+Here <code>${prefix}</code> is the <code>--prefix</code> option used
+when building gccgo.  For a binary install this is
+normally <code>/usr</code>.  Whether to use <code>lib</code>
+or <code>lib64</code> depends on the target.
+Typically <code>lib64</code> is correct for x86_64 systems,
+and <code>lib</code> is correct for other systems.  The idea is to
+name the directory where <code>libgo.so</code> is found.
+</p>
+
+</li>
+
+<li>
+<p>
+Passing a <code>-Wl,-R</code> option when you link:
+</p>
 
 <pre>
-gccgo -o file file.o -Wl,-R,/usr/lib/gcc/MACHINE/VERSION
+gccgo -o file file.o -Wl,-R,${prefix}/lib/gcc/MACHINE/VERSION
+[or]
+gccgo -o file file.o -Wl,-R,${prefix}/lib64/gcc/MACHINE/VERSION
 </pre>
+</li>
 
+<li>
 <p>
-or you can use the <code>-static-libgo</code> link-time option to link
-statically against libgo, or you can do a fully static link (static
-linking is the default for the <code>6l</code> Go linker).  On most
-systems, a static link will look something like:
-
-<pre>
-gccgo -o file file.o -static -L /usr/lib/nptl -lgobegin -lgo -lpthread
-</pre>
+Use the <code>-static-libgo</code> option to link statically against
+the compiled packages.
+</p>
+</li>
 
+<li>
 <p>
-You may get a warning about not creating an <code>.eh_frame_hdr</code>
-section; this has nothing to do with Go, and may be ignored. In the
-future the requirement of explicitly specifying
-<code>-L /usr/lib/nptl -lgobegin -lgo -lpthread</code>
-may be removed.
-
+Use the <code>-static</code> option to do a fully static link (the
+default for the <code>gc</code> compiler).
+</p>
+</li>
+</ul>
 
 <h2 id="Options">Options</h2>
 
 <p>
-The <code>gccgo</code> compiler supports all <code>gcc</code> options
+The gccgo compiler supports all GCC options
 that are language independent, notably the <code>-O</code>
 and <code>-g</code> options.
+</p>
 
 <p>
 The <code>-fgo-prefix=PREFIX</code> option may be used to set a unique
@@ -162,28 +262,24 @@ use with large programs that contain many packages, in order to allow
 multiple packages to use the same identifier as the package name.
 The <code>PREFIX</code> may be any string; a good choice for the
 string is the directory where the package will be installed.
-
-<p>
-The <code>-fno-require-return-statement</code> option may be used to
-disable the compiler error about functions missing return statements.
-Note that there is no way to disable this error in <code>6g</code>.
+</p>
 
 <p>
 The <code>-I</code> and <code>-L</code> options, which are synonyms
 for the compiler, may be used to set the search path for finding
 imports.
-
+</p>
 
 <h2 id="Imports">Imports</h2>
 
 <p>
-When you compile a file which exports something, the export
-information will be stored directly in the object file. When
-you import a package, you must tell <code>gccgo</code> how to
+When you compile a file that exports something, the export
+information will be stored directly in the object file.  When
+you import a package, you must tell gccgo how to
 find the file.
 
 <p>
-When you import the package <var>FILE</var> with <code>gccgo</code>,
+When you import the package <var>FILE</var> with gccgo,
 it will look for the import data in the following files, and use the
 first one that it finds.
 
@@ -198,21 +294,25 @@ first one that it finds.
 <code><var>FILE</var>.gox</code>, when used, will typically contain
 nothing but export data. This can be generated from
 <code><var>FILE</var>.o</code> via
+</p>
 
 <pre>
 objcopy -j .go_export FILE.o FILE.gox
 </pre>
 
 <p>
-The <code>gccgo</code> compiler will look in the current
-directory for import files. In more complex scenarios you
+The gccgo compiler will look in the current
+directory for import files.  In more complex scenarios you
 may pass the <code>-I</code> or <code>-L</code> option to
-<code>gccgo</code>. Both options take directories to search. The
+gccgo.  Both options take directories to search. The
 <code>-L</code> option is also passed to the linker.
+</p>
 
-The <code>gccgo</code> compiler does not currently (2009-11-06) record
+<p>
+The gccgo compiler does not currently (2012-03-20) record
 the file name of imported packages in the object file. You must
 arrange for the imported data to be linked into the program.
+</p>
 
 <pre>
 gccgo -c mypackage.go              # Exports mypackage
@@ -220,48 +320,41 @@ gccgo -c main.go                   # Imports mypackage
 gccgo -o main main.o mypackage.o   # Explicitly links with mypackage.o
 </pre>
 
-<h2 id="Unimplemented">Unimplemented</h2>
-
-<p>
-Some Go features are not yet implemented in <code>gccgo</code>.  As of
-2010-08-23, the following are not implemented:
-
-<ul>
-<li>goroutines are implemented as NPTL threads.  If you can not use
-    the gold linker as described above, they are created with a fixed
-    stack size, and the number of goroutines that may be created at
-    one time is limited.
-</ul>
-
 <h2 id="Debugging">Debugging</h2>
 
 <p>
 If you use the <code>-g</code> option when you compile, you can run
-<code>gdb</code> on your executable.  The debugger doesn't (yet)
-know anything about Go. However, you can set breakpoints, single-step,
+<code>gdb</code> on your executable.  The debugger has only limited
+knowledge about Go.  You can set breakpoints, single-step,
 etc.  You can print variables, but they will be printed as though they
-had C/C++ types. For numeric types this doesn't matter. Go strings
-will show up as pointers to structures; to see the value
-<code>print *stringvar</code>. In general Go strings, maps, channels
-and interfaces are always represented as C pointers.
+had C/C++ types.  For numeric types this doesn't matter.  Go strings
+and interfaces will show up as two-element structures.  Go
+maps and channels are always represented as C pointers to run-time
+structures.
+</p>
 
 <h2 id="C_Interoperability">C Interoperability</h2>
 
 <p>
-When using <code>gccgo</code> there is limited interoperability with C,
+When using gccgo there is limited interoperability with C,
 or with C++ code compiled using <code>extern "C"</code>.
+</p>
 
 <h3 id="Types">Types</h3>
 
 <p>
 Basic types map directly: an <code>int</code> in Go is an <code>int</code>
-in C, etc. Go <code>byte</code> is equivalent to C <code>unsigned char</code>.
+in C, an <code>int32</code> is an <code>int32_t</code>,
+etc.  Go <code>byte</code> is equivalent to C <code>unsigned
+char</code>.
 Pointers in Go are pointers in C. A Go <code>struct</code> is the same as C
 <code>struct</code> with the same fields and types.
+</p>
 
 <p>
 The Go <code>string</code> type is currently defined as a two-element
 structure (this is <b style="color: red;">subject to change</b>):
+</p>
 
 <pre>
 struct __go_string {
@@ -276,10 +369,12 @@ array in Go is equivalent to a C pointer to the
 equivalent of the element type.
 For example, Go <code>*[10]int</code> is equivalent to C <code>int*</code>,
 assuming that the C pointer does point to 10 elements.
+</p>
 
 <p>
 A slice in Go is a structure.  The current definition is
 (this is <b style="color: red;">subject to change</b>):
+</p>
 
 <pre>
 struct __go_slice {
@@ -291,9 +386,10 @@ struct __go_slice {
 
 <p>
 The type of a Go function with no receiver is equivalent to a C function
-whose parameter types are equivalent. When a Go function returns more
-than one value, the C function returns a struct. For example, these
+whose parameter types are equivalent.  When a Go function returns more
+than one value, the C function returns a struct.  For example, these
 functions have equivalent types:
+</p>
 
 <pre>
 func GoFunction(int) (int, float64)
@@ -302,7 +398,9 @@ struct { int i; float64 f; } CFunction(int)
 
 <p>
 A pointer to a Go function is equivalent to a pointer to a C function
-when the functions have equivalent types.
+when the functions have equivalent types (this is
+<b style="color: red;">subject to change</b>).
+</p>
 
 <p>
 Go <code>interface</code>, <code>channel</code>, and <code>map</code>
@@ -314,6 +412,7 @@ which one is difficult to predict in general; use a cast. C <code>union</code>
 types have no corresponding Go type. C <code>struct</code> types containing
 bitfields have no corresponding Go type. C++ <code>class</code> types have
 no corresponding Go type.
+</p>
 
 <p>
 Memory allocation is completely different between C and Go, as Go uses
@@ -325,43 +424,48 @@ while the Go side still has a copy the program will fail. When passing a
 pointer from Go to C, the Go function must retain a visible copy of it in
 some Go variable. Otherwise the Go garbage collector may delete the
 pointer while the C function is still using it.
+</p>
 
 <h3 id="Function_names">Function names</h3>
 
 <p>
 Go code can call C functions directly using a Go extension implemented
-in <code>gccgo</code>: a function declaration may be followed by
-<code>__asm__("NAME")</code>. For example, here is how the C function
+in gccgo: a function declaration may be preceded by
+<code>//extern NAME</code>.  For example, here is how the C function
 <code>open</code> can be declared in Go:
+</p>
 
 <pre>
-func c_open(name *byte, mode int, perm int) int __asm__ ("open");
+//extern open
+func c_open(name *byte, mode int, perm int) int
 </pre>
 
 <p>
-The C function naturally expects a nul terminated string, which in
+The C function naturally expects a NUL-terminated string, which in
 Go is equivalent to a pointer to an array (not a slice!) of
 <code>byte</code> with a terminating zero byte. So a sample call
-from Go would look like (after importing the <code>os</code> package):
+from Go would look like (after importing the <code>syscall</code> package):
+</p>
 
 <pre>
 var name = [4]byte{'f', 'o', 'o', 0};
-i := c_open(&amp;name[0], os.O_RDONLY, 0);
+i := c_open(&amp;name[0], syscall.O_RDONLY, 0);
 </pre>
 
 <p>
 (this serves as an example only, to open a file in Go please use Go's
 <code>os.Open</code> function instead).
+</p>
 
 <p>
 The name of Go functions accessed from C is subject to change. At present
 the name of a Go function that does not have a receiver is
 <code>prefix.package.Functionname</code>. The prefix is set by
 the <code>-fgo-prefix</code> option used when the package is compiled;
-if the option is not used, the default is simply <code>go</code>.
+if the option is not used, the default is <code>go</code>.
 To call the function from C you must set the name using
-a <code>gcc</code> extension similar to the <code>gccgo</code>
-extension.
+a GCC extension.
+</p>
 
 <pre>
 extern int go_function(int) __asm__ ("myprefix.mypackage.Function");
@@ -371,37 +475,35 @@ extern int go_function(int) __asm__ ("myprefix.mypackage.Function");
 Automatic generation of Go declarations from C source code</h3>
 
 <p>
-The Go version of <code>gcc</code> supports automatically generating
-Go declarations from C code. The facility is rather awkward at present,
-and a better mechanism is under development.
+The Go version of GCC supports automatically generating
+Go declarations from C code. The facility is rather awkward, and most
+users should use the <a href="/cmd/cgo">cgo</a> program with
+the <code>-gccgo</code> option instead.
+</p>
 
 <p>
-Compile your C code as usual, but replace <code>-c</code> with
-<code>-S&nbsp;-ggo</code>. The result will be an assembler file
-with a <code>.s</code> extension. This assembler file will contain
-comments beginning with #GO. Those comments are declarations in the Go
-language for the C types, variables and functions declared in the C code.
-C types which can not be represented in Go will contain the string INVALID.
-Unsupported macro definitions will be recorded as <code>unknowndefine</code>,
-and uses of <code>#undef</code> will be recorded as <code>undef</code>.
-So it is very approximately possible to get Go code by running
-
-<pre>
-gcc -S -ggo foo.c
-grep '#GO' foo.s | grep -v INVALID | grep -v unknowndefine | grep -v undef > foo.go
-</pre>
+Compile your C code as usual, and add the option
+<code>-fdump-go-spec=<var>FILENAME</var></code>.  This will create the
+file <code><var>FILENAME</var></code> as a side effect of the
+compilation.  This file will contain Go declarations for the types,
+variables and functions declared in the C code.  C types that can not
+be represented in Go will be recorded as comments in the Go code.  The
+generated file will not have a <code>package</code> declaration, but
+can otherwise be compiled directly by gccgo.
+</p>
 
 <p>
 This procedure is full of unstated caveats and restrictions and we make no
 guarantee that it will not change in the future. It is more useful as a
 starting point for real Go code than as a regular procedure.
+</p>
 
 <h2 id="RTEMS_Port">RTEMS Port</h2>
 <p>
-The <code>gccgo</code> compiler has been ported to <a href="http://www.rtems.com/">
+The gccgo compiler has been ported to <a href="http://www.rtems.com/">
 <code>RTEMS</code></a>. <code>RTEMS</code> is a real-time executive
 that provides a high performance environment for embedded applications
-on a range of processors and embedded hardware. The current <code>gccgo</code>
+on a range of processors and embedded hardware. The current gccgo
 port is for x86. The goal is to extend the port to most of the
 <a href="http://www.rtems.org/wiki/index.php/SupportedCPUs">
 architectures supported by <code>RTEMS</code></a>. For more information on the port,

doc/go1compat.html

@@ -0,0 +1,166 @@
+<!--{
+	"Title": "Go 1 and the Future of Go Programs"
+}-->
+
+<h2 id="introduction">Introduction</h2>
+<p>
+The release of Go version 1, Go 1 for short, is a major milestone
+in the development of the language. Go 1 is a stable platform for
+the growth of programs and projects written in Go.
+</p>
+
+<p>
+Go 1 defines two things: first, the specification of the language;
+and second, the specification of a set of core APIs, the "standard
+packages" of the Go library. The Go 1 release includes their
+implementation in the form of two compiler suites (gc and gccgo),
+and the core libraries themselves.
+</p>
+
+<p>
+It is intended that programs written to the Go 1 specification will
+continue to compile and run correctly, unchanged, over the lifetime
+of that specification. At some indefinite point, a Go 2 specification
+may arise, but until that time, Go programs that work today should
+continue to work even as future "point" releases of Go 1 arise (Go
+1.1, Go 1.2, etc.).
+</p>
+
+<p>
+Compatibility is at the source level. Binary compatibility for
+compiled packages is not guaranteed between releases. After a point
+release, Go source will need to be recompiled to link against the
+new release.
+</p>
+
+<p>
+The APIs may grow, acquiring new packages and features, but not in
+a way that breaks existing Go 1 code.
+</p>
+
+<h2 id="expectations">Expectations</h2>
+
+<p>
+Although we expect that the vast majority of programs will maintain
+this compatibility over time, it is impossible to guarantee that
+no future change will break any program. This document is an attempt
+to set expectations for the compatibility of Go 1 software in the
+future. There are a number of ways in which a program that compiles
+and runs today may fail to do so after a future point release. They
+are all unlikely but worth recording.
+</p>
+
+<ul>
+<li>
+Security. A security issue in the specification or implementation
+may come to light whose resolution requires breaking compatibility.
+We reserve the right to address such security issues.
+</li>
+
+<li>
+Unspecified behavior. The Go specification tries to be explicit
+about most properties of the language, but there are some aspects
+that are undefined. Programs that depend on such unspecified behavior
+may break in future releases.
+</li>
+
+<li>
+Specification errors. If it becomes necessary to address an
+inconsistency or incompleteness in the specification, resolving the
+issue could affect the meaning or legality of existing programs.
+We reserve the right to address such issues, including updating the
+implementations. Except for security issues, no incompatible changes
+to the specification would be made.
+</li>
+
+<li>
+Bugs. If a compiler or library has a bug that violates the
+specification, a program that depends on the buggy behavior may
+break if the bug is fixed. We reserve the right to fix such bugs.
+</li>
+
+<li>
+Struct literals. For the addition of features in later point
+releases, it may be necessary to add fields to exported structs in
+the API. Code that uses untagged struct literals (such as pkg.T{3,
+"x"}) to create values of these types would fail to compile after
+such a change. However, code that uses tagged literals (pkg.T{A:
+3, B: "x"}) will continue to compile after such a change. We will
+update such data structures in a way that allows tagged struct
+literals to remain compatible, although untagged literals may fail
+to compile. (There are also more intricate cases involving nested
+data structures or interfaces, but they have the same resolution.)
+We therefore recommend that composite literals whose type is defined
+in a separate package should use the tagged notation.
+</li>
+
+<li>
+Dot imports. If a program imports a standard package
+using <code>import . "path"</code>, additional names defined in the
+imported package in future releases may conflict with other names
+defined in the program.  We do not recommend the use of <code>import .</code>
+outside of tests, and using it may cause a program to fail
+to compile in future releases.
+</li>
+
+</ul>
+
+<p>
+Of course, for all of these possibilities, should they arise, we
+would endeavor whenever feasible to update the specification,
+compilers, or libraries without affecting existing code.
+</p>
+
+<p>
+These same considerations apply to successive point releases. For
+instance, code that runs under Go 1.2 should be compatible with Go
+1.2.1, Go 1.3, Go 1.4, etc., although not necessarily with Go 1.1
+since it may use features added only in Go 1.2
+</p>
+
+<p>
+Features added between releases, available in the source repository
+but not part of the numbered binary releases, are under active
+development. No promise of compatibility is made for software using
+such features until they have been released.
+</p>
+
+<p>
+Finally, although it is not a correctness issue, it is possible
+that the performance of a program may be affected by
+changes in the implementation of the compilers or libraries upon
+which it depends.
+No guarantee can be made about the performance of a
+given program between releases.
+</p>
+
+<p>
+Although these expectations apply to Go 1 itself, we hope similar
+considerations would be made for the development of externally
+developed software based on Go 1.
+</p>
+
+<h2 id="subrepos">Sub-repositories</h2>
+
+<p>
+Code in sub-repositories of the main go tree, such as
+<a href="http://code.google.com/p/go.net">code.google.com/p/go.net</a>,
+may be developed under
+looser compatibility requirements. However, the sub-repositories
+will be tagged as appropriate to identify versions that are compatible
+with the Go 1 point releases.
+</p>
+
+<h2 id="tools">Tools</h2>
+
+<p>
+Finally, the Go tool chain (compilers, linkers, build tools, and so
+on) are under active development and may change behavior. This
+means, for instance, that scripts that depend on the location and
+properties of the tools may be broken by a point release.
+</p>
+
+<p>
+These caveats aside, we believe that Go 1 will be a firm foundation
+for the development of Go and its ecosystem.
+</p>

doc/go_faq.html

@@ -1,4 +1,6 @@
-<!-- FAQ -->
+<!--{
+	"Title": "FAQ"
+}-->
 
 <h2 id="Origins">Origins</h2>
 
@@ -74,20 +76,6 @@ The logo and mascot are covered by the
 license.
 </p>
 
-<h3 id="What_kind_of_a_name_is_6g">
-What kind of a name is 6g?</h3>
-
-<p>
-The <code>6g</code> (and <code>8g</code> and <code>5g</code>) compiler is named in the
-tradition of the Plan 9 C compilers, described in
-<a href="http://plan9.bell-labs.com/sys/doc/compiler.html">
-http://plan9.bell-labs.com/sys/doc/compiler.html</a>
-(see the table in section 2).
-
-<code>6</code> is the architecture letter for amd64 (or x86-64, if you prefer), while
-<code>g</code> stands for Go.
-</p>
-
 <h3 id="history">
 What is the history of the project?</h3>
 <p>
@@ -188,18 +176,19 @@ easier to understand what happens when things combine.
 
 <p>
 Yes. There are now several Go programs deployed in 
-production inside Google.  For instance, the server behind
-<a href="http://golang.org">http://golang.org</a> is a Go program; 
-in fact it's just the <a href="/cmd/godoc"><code>godoc</code></a>
-document server running in a production configuration.
+production inside Google.  A public example is the server behind
+<a href="http://golang.org">http://golang.org</a>.
+It's just the <a href="/cmd/godoc"><code>godoc</code></a>
+document server running in a production configuration on
+<a href="http://code.google.com/appengine/">Google App Engine</a>.
 </p>
 
 <h3 id="Do_Go_programs_link_with_Cpp_programs">
 Do Go programs link with C/C++ programs?</h3>
 
 <p>
-There are two Go compiler implementations, <code>6g</code> and friends, 
-generically called <code>gc</code>, and <code>gccgo</code>.
+There are two Go compiler implementations, <code>gc</code>
+(the <code>6g</code> program and friends) and <code>gccgo</code>.
 <code>Gc</code> uses a different calling convention and linker and can
 therefore only be linked with C programs using the same convention.
 There is such a C compiler but no C++ compiler. 
@@ -317,10 +306,9 @@ exceptional.
 <p>
 Go takes a different approach.  For plain error handling, Go's multi-value
 returns make it easy to report an error without overloading the return value.
-<a href="http://blog.golang.org/2011/07/error-handling-and-go.html">A
-canonical error type, coupled
-with Go's other features</a>, makes error
-handling pleasant but quite different from that in other languages.
+<a href="/doc/articles/error_handling.html">A canonical error type, coupled
+with Go's other features</a>, makes error handling pleasant but quite different
+from that in other languages.
 </p>
 
 <p>
@@ -333,7 +321,7 @@ when used well, can result in clean error-handling code.
 </p>
 
 <p>
-See the <a href="http://blog.golang.org/2010/08/defer-panic-and-recover.html">Defer, Panic, and Recover</a> article for details.
+See the <a href="/doc/articles/defer_panic_recover.html">Defer, Panic, and Recover</a> article for details.
 </p>
 
 <h3 id="assertions">
@@ -350,26 +338,6 @@ errors are particularly important when the programmer seeing the errors is
 not familiar with the code.
 </p>
 
-<p>
-The same arguments apply to the use of <code>assert()</code> in test programs. Proper
-error handling means letting other tests run after one has failed, so
-that the person debugging the failure gets a complete picture of what is
-wrong. It is more useful for a test to report that
-<code>isPrime</code> gives the wrong answer for 2, 3, 5, and 7 (or for
-2, 4, 8, and 16) than to report that <code>isPrime</code> gives the wrong
-answer for 2 and therefore no more tests were run. The programmer who
-triggers the test failure may not be familiar with the code that fails.
-Time invested writing a good error message now pays off later when the
-test breaks.
-</p>
-
-<p>
-In testing, if the amount of extra code required to write
-good errors seems repetitive and overwhelming, it might work better as a
-table-driven test instead.
-Go has excellent support for data structure literals.
-</p>
-
 <p>
 We understand that this is a point of contention. There are many things in
 the Go language and libraries that differ from modern practices, simply
@@ -380,7 +348,7 @@ because we feel it's sometimes worth trying a different approach.
 Why build concurrency on the ideas of CSP?</h3>
 <p>
 Concurrency and multi-threaded programming have a reputation
-for difficulty.  We believe the problem is due partly to complex
+for difficulty.  We believe this is due partly to complex
 designs such as pthreads and partly to overemphasis on low-level details
 such as mutexes, condition variables, and memory barriers.
 Higher-level interfaces enable much simpler code, even if there are still
@@ -451,7 +419,9 @@ we believe is easy to use and in some ways more general. There are
 also ways to embed types in other types to provide something
 analogous&mdash;but not identical&mdash;to subclassing.
 Moreover, methods in Go are more general than in C++ or Java:
-they can be defined for any sort of data, not just structs.
+they can be defined for any sort of data, even built-in types such
+as plain, &ldquo;unboxed&rdquo; integers.
+They are not restricted to structs (classes).
 </p>
 
 <p>
@@ -464,7 +434,7 @@ How do I get dynamic dispatch of methods?</h3>
 
 <p>
 The only way to have dynamically dispatched methods is through an
-interface. Methods on structs or other types are always resolved statically.
+interface. Methods on a struct or any other concrete type are always resolved statically.
 </p>
 
 <h3 id="inheritance">
@@ -496,10 +466,11 @@ It's possible to use these ideas to construct something analogous to
 type-safe Unix pipes.  For instance, see how <code>fmt.Fprintf</code>
 enables formatted printing to any output, not just a file, or how the
 <code>bufio</code> package can be completely separate from file I/O,
-or how the <code>crypto</code> packages stitch together block and
-stream ciphers.  All these ideas stem from a single interface
+or how the <code>image</code> packages generate compressed
+image files.  All these ideas stem from a single interface
 (<code>io.Writer</code>) representing a single method
 (<code>Write</code>).  And that's only scratching the surface.
+Go's interfaces have a profound influence on how programs are structured.
 </p>
 
 <p>
@@ -559,7 +530,7 @@ interface <code>I</code> by attempting an assignment:
 
 <pre>
 type T struct{}
-var _ I = T{}
+var _ I = T{}   // Verify that T implements I.
 </pre>
 
 <p>
@@ -575,8 +546,8 @@ For example:
 
 <pre>
 type Fooer interface {
-	Foo()
-	ImplementsFooer()
+    Foo()
+    ImplementsFooer()
 }
 </pre>
 
@@ -608,7 +579,7 @@ itself with another value:
 
 <pre>
 type Equaler interface {
-	Equal(Equaler) bool
+    Equal(Equaler) bool
 }
 </pre>
 
@@ -681,7 +652,7 @@ examples and also have them be statically checked.
 Can I convert a []T to an []interface{}?</h3>
 
 <p>
-Not directly because they do not have the same representation in memory.
+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>:
@@ -691,10 +662,89 @@ slice. This example converts a slice of <code>int</code> to a slice of
 t := []int{1, 2, 3, 4}
 s := make([]interface{}, len(t))
 for i, v := range t {
-	s[i] = v
+    s[i] = v
 }
 </pre>
 
+<h3 id="nil_error">
+Why is my nil error value not equal to nil?
+</h3>
+
+<p>
+Under the covers, interfaces are implemented as two elements, a type and a value.
+The value, called the interface's dynamic value,
+is an arbitrary concrete value and the type is that of the value.
+For the <code>int</code> value 3, an interface value contains,
+schematically, (<code>int</code>, <code>3</code>).
+</p>
+
+<p>
+An interface value is <code>nil</code> only if the inner value and type are both unset,
+(<code>nil</code>, <code>nil</code>).
+In particular, a <code>nil</code> interface will always hold a <code>nil</code> type.
+If we store a pointer of type <code>*int</code> inside
+an interface value, the inner type will be <code>*int</code> regardless of the value of the pointer:
+(<code>*int</code>, <code>nil</code>).
+Such an interface value will therefore be non-<code>nil</code>
+<em>even when the pointer inside is</em> <code>nil</code>.
+</p>
+
+<p>
+This situation can be confusing, and often arises when a <code>nil</code> value is
+stored inside an interface value such as an <code>error</code> return:
+</p>
+
+<pre>
+func returnsError() error {
+	var p *MyError = nil
+	if bad() {
+		p = ErrBad
+	}
+	return p // Will always return a non-nil error.
+}
+</pre>
+
+<p>
+If all goes well, the function returns a <code>nil</code> <code>p</code>,
+so the return value is an <code>error</code> interface
+value holding (<code>*MyError</code>, <code>nil</code>).
+This means that if the caller compares the returned error to <code>nil</code>,
+it will always look as if there was an error even if nothing bad happened.
+To return a proper <code>nil</code> <code>error</code> to the caller,
+the function must return an explicit <code>nil</code>:
+</p>
+
+
+<pre>
+func returnsError() error {
+	if bad() {
+		return ErrBad
+	}
+	return nil
+}
+</pre>
+
+<p>
+It's a good idea for functions
+that return errors always to use the <code>error</code> type in
+their signature (as we did above) rather than a concrete type such
+as <code>*MyError</code>, to help guarantee the error is
+created correctly. As an example,
+<a href="/pkg/os/#Open"><code>os.Open</code></a>
+returns an <code>error</code> even though, if not <code>nil</code>,
+it's always of concrete type
+<a href="/pkg/os/#PathError"><code>*os.PathError</code></a>.
+</p>
+
+<p>
+Similar situations to those described here can arise whenever interfaces are used.
+Just keep in mind that if any concrete value
+has been stored in the interface, the interface will not be <code>nil</code>.
+For more information, see
+<a href="/doc/articles/laws_of_reflection.html">The Laws of Reflection</a>.
+</p>
+
+
 <h3 id="unions">
 Why are there no untagged unions, as in C?</h3>
 
@@ -768,15 +818,20 @@ to write one but it will not be as convenient syntactically; this seems a reason
 </p>
 
 <h3 id="map_keys">
-Why don't maps allow structs and arrays as keys?</h3>
+Why don't maps allow slices as keys?</h3>
 <p>
-Map lookup requires an equality operator, which structs and arrays do not implement.
+Map lookup requires an equality operator, which slices do not implement.
 They don't implement equality because equality is not well defined on such types;
 there are multiple considerations involving shallow vs. deep comparison, pointer vs.
-value comparison, how to deal with recursive structures, and so on.
-We may revisit this issue&mdash;and implementing equality for structs and arrays
+value comparison, how to deal with recursive types, and so on.
+We may revisit this issue&mdash;and implementing equality for slices
 will not invalidate any existing programs&mdash;but without a clear idea of what
-equality of structs and arrays should mean, it was simpler to leave it out for now.
+equality of slices should mean, it was simpler to leave it out for now.
+</p>
+
+<p>
+In Go 1, unlike prior releases, equality is defined for structs and arrays, so such
+types can be used as map keys. Slices still do not have a definition of equality, though.
 </p>
 
 <h3 id="references">
@@ -841,14 +896,17 @@ for more information about how to proceed.
 When are function parameters passed by value?</h3>
 
 <p>
-Everything in Go is passed by value.  A function always gets a copy of the
+As in all languages in the C family, everything in Go is passed by value.
+That is, a function always gets a copy of the
 thing being passed, as if there were an assignment statement assigning the
-value to the parameter.  For instance, copying a pointer value makes a copy of
-the pointer, not the data it points to. 
+value to the parameter.  For instance, passing an <code>int</code> value
+to a function makes a copy of the <code>int</code>, and passing a pointer
+value makes a copy of the pointer, but not the data it points to.
+(See the next section for a discussion of how this affects method receivers.)
 </p>
 
 <p>
-Map and slice values behave like pointers; they are descriptors that
+Map and slice values behave like pointers: they are descriptors that
 contain pointers to the underlying map or slice data.  Copying a map or
 slice value doesn't copy the data it points to.  Copying an interface value
 makes a copy of the thing stored in the interface value.  If the interface
@@ -869,7 +927,7 @@ func (s MyStruct)  valueMethod()   { } // method on value
 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 as if it were an argument to the method.
+examples) 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.
@@ -936,7 +994,7 @@ Why is <code>int</code> 32 bits on 64 bit machines?</h3>
 <p>
 The sizes of <code>int</code> and <code>uint</code> are implementation-specific
 but the same as each other on a given platform.
-The 64 bit Go compilers (both 6g and gccgo) use a 32 bit representation for
+The 64 bit Go compilers (both gc and gccgo) use a 32 bit representation for
 <code>int</code>.  Code that relies on a particular
 size of value should use an explicitly sized type, like <code>int64</code>.
 On the other hand, floating-point scalars and complex
@@ -946,6 +1004,12 @@ floating-point numbers.
 The default size of a floating-point constant is <code>float64</code>.
 </p>
 
+<p>
+At the moment, all implementations use 32-bit ints, an essentially arbitrary decision.
+However, we expect that <code>int</code> will be increased to 64 bits on 64-bit
+architectures in a future release of Go.
+</p>
+
 <h3 id="stack_or_heap">
 How do I know whether a variable is allocated on the heap or the stack?</h3>
 
@@ -963,12 +1027,15 @@ local to a function in that function's stack frame.  However, if the
 compiler cannot prove that the variable is not referenced after the
 function returns, then the compiler must allocate the variable on the
 garbage-collected heap to avoid dangling pointer errors.
+Also, if a local variable is very large, it might make more sense
+to store it on the heap rather than the stack.
 </p>
 
 <p>
-In the current compilers, the analysis is crude: if a variable has its address
-taken, that variable is allocated on the heap. We are working to improve this
-analysis so that more data is kept on the stack. 
+In the current compilers, if a variable has its address taken, that variable
+is a candidate for allocation on the heap. However, a basic <em>escape
+analysis</em> recognizes some cases when such variables will not
+live past the return from the function and can reside on the stack.
 </p>
 
 <h2 id="Concurrency">Concurrency</h2>
@@ -978,7 +1045,7 @@ What operations are atomic? What about mutexes?</h3>
 
 <p>
 We haven't fully defined it all yet, but some details about atomicity are
-available in the <a href="go_mem.html">Go Memory Model specification</a>.
+available in the <a href="/ref/mem">Go Memory Model specification</a>.
 </p>
 
 <p>
@@ -1001,17 +1068,15 @@ See the <a href="/doc/codewalk/sharemem/">Share Memory By Communicating</a> code
 Why doesn't my multi-goroutine program use multiple CPUs?</h3>
 
 <p>
-Under the gc compilers you must set <code>GOMAXPROCS</code> to allow the
-run-time support to utilise more than one OS thread. Under <code>gccgo</code> an OS
-thread will be created for each goroutine, and <code>GOMAXPROCS</code> is
-effectively equal to the number of running goroutines.  
+You must set the <code>GOMAXPROCS</code> shell environment variable
+or use the similarly-named <a href="/pkg/runtime/#GOMAXPROCS"><code>function</code></a>
+of the runtime package to allow the
+run-time support to utilize more than one OS thread. 
 </p>
 
 <p>
-Programs that perform concurrent computation should benefit from an increase in
-<code>GOMAXPROCS</code>. (See the <a
-href="http://golang.org/pkg/runtime/#GOMAXPROCS"><code>runtime</code> package's
-documentation</a>.)
+Programs that perform parallel computation should benefit from an increase in
+<code>GOMAXPROCS</code>.
 </p>
 
 <h3 id="Why_GOMAXPROCS">
@@ -1019,15 +1084,24 @@ Why does using <code>GOMAXPROCS</code> &gt; 1 sometimes make my program
 slower?</h3>
 
 <p>
-(This is specific to the gc compilers. See above.)
+It depends on the nature of your program. 
+Problems that are intrinsically sequential cannot be sped up by adding
+more goroutines.
+Concurrency only becomes parallelism when the problem is
+intrinsically parallel.
 </p>
 
 <p>
-It depends on the nature of your program. 
-Programs that contain several goroutines that spend a lot of time
-communicating on channels will experience performance degradation when using
-multiple OS threads. This is because of the significant context-switching
-penalty involved in sending data between threads.
+In practical terms, programs that spend more time
+communicating on channels than doing computation
+will experience performance degradation when using
+multiple OS threads.
+This is because sending data between threads involves switching
+contexts, which has significant cost.
+For instance, the <a href="/ref/spec#An_example_package">prime sieve example</a>
+from the Go specification has no significant parallelism although it launches many
+goroutines; increasing <code>GOMAXPROCS</code> is more likely to slow it down than
+to speed it up.
 </p>
 
 <p>
@@ -1042,7 +1116,7 @@ should recognize such cases and optimize its use of OS threads. For now,
 Why do T and *T have different method sets?</h3>
 
 <p>
-From the <a href="http://golang.org/doc/go_spec.html#Types">Go Spec</a>:
+From the <a href="/ref/spec#Types">Go Spec</a>:
 </p>
 
 <blockquote>
@@ -1060,7 +1134,10 @@ there is no useful way for a method call to obtain a pointer.
 </p>
 
 <p>
-If not for this restriction, this code:
+Even in cases where the compiler could take the address of a value
+to pass to the method, if the method modifies the value the changes
+will be lost in the caller.
+As a common example, this code:
 </p>
 
 <pre>
@@ -1075,7 +1152,7 @@ This is almost never the desired behavior.
 </p>
 
 <h3 id="closures_and_goroutines">
-Why am I confused by the way my closures behave as goroutines?</h3>
+What happens with closures running as goroutines?</h3>
 
 <p>
 Some confusion may arise when using closures with concurrency.
@@ -1084,29 +1161,30 @@ Consider the following program:
 
 <pre>
 func main() {
-	done := make(chan bool)
+    done := make(chan bool)
 
-	values := []string{ "a", "b", "c" }
-	for _, v := range values {
-		go func() {
-			fmt.Println(v)
-			done &lt;- true
-		}()
-	}
+    values := []string{"a", "b", "c"}
+    for _, v := range values {
+        go func() {
+            fmt.Println(v)
+            done &lt;- true
+        }()
+    }
 
-	// wait for all goroutines to complete before exiting
-	for _ = range values {
-		&lt;-done 
-	}
+    // wait for all goroutines to complete before exiting
+    for _ = range values {
+        &lt;-done 
+    }
 }
 </pre>
 
 <p>
 One might mistakenly expect to see <code>a, b, c</code> as the output. 
 What you'll probably see instead is <code>c, c, c</code>.  This is because 
-each closure shares the same variable <code>v</code>. Each closure prints the 
-value of <code>v</code> at the time <code>fmt.Println</code> is executed, 
-rather than the value of <code>v</code> when the goroutine was launched. 
+each iteration of the loop uses the same instance of the variable <code>v</code>, so
+each closure shares that single variable. When the closure runs, it prints the 
+value of <code>v</code> at the time <code>fmt.Println</code> is executed,
+but <code>v</code> may have been modified since the goroutine was launched. 
 </p>
 
 <p>
@@ -1115,12 +1193,12 @@ could modify the inner loop to read:
 </p>
 
 <pre>
-	for _, v := range values {
-		go func(<b>u</b> string) {
-			fmt.Println(<b>u</b>)
-			done &lt;- true
-		}(<b>v</b>)
-	}
+    for _, v := range values {
+        go func(<b>u</b> string) {
+            fmt.Println(<b>u</b>)
+            done &lt;- true
+        }(<b>v</b>)
+    }
 </pre>
 
 <p>
@@ -1141,9 +1219,9 @@ result:
 
 <pre>
 if expr {
-	n = trueVal
+    n = trueVal
 } else {
-	n = falseVal
+    n = falseVal
 }
 </pre>
 
@@ -1179,12 +1257,53 @@ func TestFoo(t *testing.T) {
 </pre>
 
 <p>
-Run <code>gotest</code> in that directory.
+Run <code>go test</code> in that directory.
 That script finds the <code>Test</code> functions,
 builds a test binary, and runs it.
 </p>
 
-<p>See the <a href="/doc/code.html">How to Write Go Code</a> document for more details.</p>
+<p>See the <a href="/doc/code.html">How to Write Go Code</a> document,
+the <a href="/pkg/testing/"><code>testing</code></a> package
+and the <a href="/cmd/go/#Test_packages"><code>go test</code></a> subcommand for more details.
+</p>
+
+<h3 id="testing_framework">
+Where is my favorite helper function for testing?</h3>
+
+<p>
+Go's standard <a href="/pkg/testing/"><code>testing</code></a> package makes it easy to write unit tests, but it lacks
+features provided in other language's testing frameworks such as assertion functions.
+An <a href="#assertions">earlier section</a> of this document explained why Go
+doesn't have assertions, and
+the same arguments apply to the use of <code>assert</code> in tests.
+Proper error handling means letting other tests run after one has failed, so
+that the person debugging the failure gets a complete picture of what is
+wrong. It is more useful for a test to report that
+<code>isPrime</code> gives the wrong answer for 2, 3, 5, and 7 (or for
+2, 4, 8, and 16) than to report that <code>isPrime</code> gives the wrong
+answer for 2 and therefore no more tests were run. The programmer who
+triggers the test failure may not be familiar with the code that fails.
+Time invested writing a good error message now pays off later when the
+test breaks.
+</p>
+
+<p>
+A related point is that testing frameworks tend to develop into mini-languages
+of their own, with conditionals and controls and printing mechanisms,
+but Go already has all those capabilities; why recreate them?
+We'd rather write tests in Go; it's one fewer language to learn and the
+approach keeps the tests straightforward and easy to understand.
+</p>
+
+<p>
+If the amount of extra code required to write
+good errors seems repetitive and overwhelming, the test might work better if
+table-driven, iterating over a list of inputs and outputs defined
+in a data structure (Go has excellent support for data structure literals).
+The work to write a good test and good error messages will then be amortized over many
+test cases. The standard Go library is full of illustrative examples, such as in
+<a href="/src/pkg/fmt/fmt_test.go">the formatting tests for the <code>fmt</code> package</a>.
+</p>
 
 
 <h2 id="Implementation">Implementation</h2>
@@ -1198,21 +1317,21 @@ standard GCC back end. <code>Gc</code> is written in C using
 <code>yacc</code>/<code>bison</code> for the parser.
 Although it's a new program, it fits in the Plan 9 C compiler suite
 (<a href="http://plan9.bell-labs.com/sys/doc/compiler.html">http://plan9.bell-labs.com/sys/doc/compiler.html</a>)
-and uses a variant of the Plan 9 loader to generate ELF binaries.
+and uses a variant of the Plan 9 loader to generate ELF/Mach-O/PE binaries.
 </p>
 
 <p>
-We considered writing <code>6g</code>, the original Go compiler, in Go itself but
+We considered writing <code>gc</code>, the original Go compiler, in Go itself but
 elected not to do so because of the difficulties of bootstrapping and
 especially of open source distribution&mdash;you'd need a Go compiler to
 set up a Go environment. <code>Gccgo</code>, which came later, makes it possible to
 consider writing a compiler in Go, which might well happen. (Go would be a
 fine language in which to implement a compiler; a native lexer and
-parser are already available in <a href="/pkg/go/"><code>/pkg/go</code></a>.)
+parser are already available in the <a href="/pkg/go/"><code>go</code></a> package.)
 </p>
 
 <p>
-We also considered using LLVM for <code>6g</code> but we felt it was too large and
+We also considered using LLVM for <code>gc</code> but we felt it was too large and
 slow to meet our performance goals.
 </p>
 
@@ -1227,25 +1346,27 @@ it now. <code>Gccgo</code>'s run-time support uses <code>glibc</code>.
 control; it is
 compiled with a version of the Plan 9 C compiler that supports
 segmented stacks for goroutines.
-Work is underway to provide the same stack management in
-<code>gccgo</code>.
+The <code>gccgo</code> compiler implements segmented
+stacks on Linux only, supported by recent modifications to the gold linker.
 </p>
 
 <h3 id="Why_is_my_trivial_program_such_a_large_binary">
 Why is my trivial program such a large binary?</h3>
 
 <p>
-The gc tool chain (<code>5l</code>, <code>6l</code>, and <code>8l</code>) only
-generate statically linked binaries.  All Go binaries therefore include the Go
+The linkers in the gc tool chain (<code>5l</code>, <code>6l</code>, and <code>8l</code>)
+do static linking.  All Go binaries therefore include the Go
 run-time, along with the run-time type information necessary to support dynamic
 type checks, reflection, and even panic-time stack traces.
 </p>
 
 <p>
-A trivial C "hello, world" program compiled and linked statically using gcc
-on Linux is around 750 kB.  An equivalent Go program is around 1.1 MB, but
-that includes more powerful run-time support.  We believe that with some effort
-the size of Go binaries can be reduced.
+A simple C "hello, world" program compiled and linked statically using gcc
+on Linux is around 750 kB,
+including an implementation of <code>printf</code>.
+An equivalent Go program using <code>fmt.Printf</code>
+is around 1.2 MB, but
+that includes more powerful run-time support.
 </p>
 
 <h3 id="unused_variables_and_imports">
@@ -1296,9 +1417,9 @@ import "unused"
 var _ = unused.Item  // TODO: Delete before committing!
 
 func main() {
-	debugData := debug.Profile()
-	_ = debugData // Used only during debugging.
-	....
+    debugData := debug.Profile()
+    _ = debugData // Used only during debugging.
+    ....
 }
 </pre>
 
@@ -1310,20 +1431,23 @@ Why does Go perform badly on benchmark X?</h3>
 <p>
 One of Go's design goals is to approach the performance of C for comparable
 programs, yet on some benchmarks it does quite poorly, including several 
-in <a href="/test/bench/">test/bench</a>. The slowest depend on libraries 
+in <a href="/test/bench/shootout/">test/bench/shootout</a>. The slowest depend on libraries 
 for which versions of comparable performance are not available in Go. 
-For instance, pidigits depends on a multi-precision math package, and the C
+For instance, <a href="/test/bench/shootout/pidigits.go">pidigits.go</a>
+depends on a multi-precision math package, and the C
 versions, unlike Go's, use <a href="http://gmplib.org/">GMP</a> (which is
 written in optimized assembler). 
-Benchmarks that depend on regular expressions (regex-dna, for instance) are
-essentially comparing Go's stopgap <a href="/pkg/regexp">regexp package</a> to
+Benchmarks that depend on regular expressions
+(<a href="/test/bench/shootout/regex-dna.go">regex-dna.go</a>, for instance) are
+essentially comparing Go's native <a href="/pkg/regexp">regexp package</a> to
 mature, highly optimized regular expression libraries like PCRE.
 </p>
 
 <p>
 Benchmark games are won by extensive tuning and the Go versions of most
 of the benchmarks need attention.  If you measure comparable C
-and Go programs (reverse-complement is one example), you'll see the two
+and Go programs
+(<a href="/test/bench/shootout/reverse-complement.go">reverse-complement.go</a> is one example), you'll see the two
 languages are much closer in raw performance than this suite would
 indicate.
 </p>
@@ -1331,12 +1455,15 @@ indicate.
 <p>
 Still, there is room for improvement. The compilers are good but could be
 better, many libraries need major performance work, and the garbage collector
-isn't fast enough yet (even if it were, taking care not to generate unnecessary 
-garbage can have a huge effect).
+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
+In any case, Go can often be very competitive.
+There has been significant improvement in the performance of many programs
+as the language and tools have developed.
+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.
 
@@ -1367,13 +1494,13 @@ prefix <code>*</code> for pointers is an exception that proves the rule).  In C,
 the declaration
 </p>
 <pre>
-	int* a, b;
+    int* a, b;
 </pre>
 <p>
 declares <code>a</code> to be a pointer but not <code>b</code>; in Go
 </p>
 <pre>
-	var a, b *int;
+    var a, b *int
 </pre>
 <p>
 declares both to be pointers.  This is clearer and more regular.
@@ -1381,11 +1508,13 @@ Also, the <code>:=</code> short declaration form argues that a full variable
 declaration should present the same order as <code>:=</code> so
 </p>
 <pre>
-	var a uint64 = 1;
+    var a uint64 = 1
 </pre>
+<p>
 has the same effect as
+</p>
 <pre>
-	a := uint64(1);
+    a := uint64(1)
 </pre>
 <p>
 Parsing is also simplified by having a distinct grammar for types that
@@ -1395,7 +1524,7 @@ and <code>chan</code> keep things clear.
 
 <p>
 See the article about
-<a href="http://blog.golang.org/2010/07/gos-declaration-syntax.html">Go's Declaration Syntax</a>
+<a href="/doc/articles/gos_declaration_syntax.html">Go's Declaration Syntax</a>
 for more details.
 </p>
 
@@ -1445,7 +1574,7 @@ appear on a line by itself.
 Some have argued that the lexer should do lookahead to permit the
 brace to live on the next line.  We disagree.  Since Go code is meant
 to be formatted automatically by
-<a href="http://golang.org/cmd/gofmt/"><code>gofmt</code></a>,
+<a href="/cmd/gofmt/"><code>gofmt</code></a>,
 <i>some</i> style must be chosen.  That style may differ from what
 you've used in C or Java, but Go is a new language and
 <code>gofmt</code>'s style is as good as any other.  More
@@ -1464,8 +1593,7 @@ memory management.  We feel it's critical to eliminate that
 programmer overhead, and advances in garbage collection
 technology in the last few years give us confidence that we can
 implement it with low enough overhead and no significant
-latency.  (The current implementation is a plain mark-and-sweep
-collector but a replacement is in the works.)
+latency.
 </p>
 
 <p>
@@ -1484,6 +1612,11 @@ Finally, concurrency aside, garbage collection makes interfaces
 simpler because they don't need to specify how memory is managed across them.
 </p>
 
+<p>
+The current implementation is a parallel mark-and-sweep
+collector but a future version might take a different approach.
+</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

doc/go_for_cpp_programmers.html

@@ -1,707 +0,0 @@
-<!-- Go For C++ Programmers -->
-
-<p>
-Go is a systems programming language intended to be a general-purpose
-systems language, like C++.
-These are some notes on Go for experienced C++ programmers. This
-document discusses the differences between Go and C++, and says little
-to nothing about the similarities.
-
-<p>
-For a more general introduction to Go, see the
-<a href="go_tutorial.html">Go tutorial</a> and
-<a href="effective_go.html">Effective Go</a>.
-
-<p>
-For a detailed description of the Go language, see the
-<a href="go_spec.html">Go spec</a>.
-
-<h2 id="Conceptual_Differences">Conceptual Differences</h2>
-
-<ul>
-<li>Go does not have classes with constructors or destructors.
-    Instead of class methods, a class inheritance hierarchy,
-    and virtual functions, Go provides <em>interfaces</em>, which are
-    <a href="#Interfaces">discussed in more detail below</a>.
-    Interfaces are also used where C++ uses templates.
-
-<li>Go uses garbage collection. It is not necessary (or possible)
-    to release memory explicitly. The garbage collection is (intended to be)
-    incremental and highly efficient on modern processors.
-
-<li>Go has pointers but not pointer arithmetic. You cannot
-    use a pointer variable to walk through the bytes of a string.
-
-<li>Arrays in Go are first class values. When an array is used as a
-    function parameter, the function receives a copy of the array, not
-    a pointer to it. However, in practice functions often use slices
-    for parameters; slices hold pointers to underlying arrays.  Slices
-    are <a href="#Slices">discussed further below</a>.
-
-<li>Strings are provided by the language. They may not be changed once they
-    have been created.
-
-<li>Hash tables are provided by the language. They are called maps.
-
-<li>Separate threads of execution, and communication channels between
-    them, are provided by the language. This
-    is <a href="#Goroutines">discussed further below</a>.
-
-<li>Certain types (maps and channels, described further below)
-    are passed by reference, not by value. That is, passing a map to a
-    function does not copy the map, and if the function changes the map
-    the change will be seen by the caller.  In C++ terms, one can
-    think of these as being reference types.
-
-<li>Go does not use header files. Instead, each source file is part of a
-    defined <em>package</em>. When a package defines an object
-    (type, constant, variable, function) with a name starting with an
-    upper case letter, that object is visible to any other file which
-    imports that package.
-
-<li>Go does not support implicit type conversion. Operations that mix
-    different types require casts (called conversions in Go).
-
-<li>Go does not support function overloading and does not support user
-    defined operators.
-
-<li>Go does not support <code>const</code> or <code>volatile</code> qualifiers.
-
-<li>Go uses <code>nil</code> for invalid pointers, where C++ uses
-    <code>NULL</code> or simply <code>0</code>.
-</ul>
-
-<h2 id="Syntax">Syntax</h2>
-
-<p>
-The declaration syntax is reversed compared to C++. You write the name
-followed by the type. Unlike in C++, the syntax for a type does not match
-the way in which the variable is used. Type declarations may be read
-easily from left to right.
-
-<pre>
-<b>Go                           C++</b>
-var v1 int                // int v1;
-var v2 string             // const std::string v2;  (approximately)
-var v3 [10]int            // int v3[10];
-var v4 []int              // int* v4;  (approximately)
-var v5 struct { f int }   // struct { int f; } v5;
-var v6 *int               // int* v6;  (but no pointer arithmetic)
-var v7 map[string]int     // unordered_map&lt;string, int&gt;* v7;  (approximately)
-var v8 func(a int) int    // int (*v8)(int a);
-</pre>
-
-<p>
-Declarations generally take the form of a keyword followed by the name
-of the object being declared.  The keyword is one of <code>var</code>,
-<code>func</code>,
-<code>const</code>, or <code>type</code>.  Method declarations are a minor
-exception in that
-the receiver appears before the name of the object being declared; see
-the <a href="#Interfaces">discussion of interfaces</a>.
-
-<p>
-You can also use a keyword followed by a series of declarations in
-parentheses.
-
-<pre>
-var (
-    i int
-    m float64
-)
-</pre>
-
-<p>
-When declaring a function, you must either provide a name for each parameter
-or not provide a name for any parameter; you can't omit some names
-and provide others.  You may group several names with the same type:
-
-<pre>
-func f(i, j, k int, s, t string)
-</pre>
-
-<p>
-A variable may be initialized when it is declared.  When this is done,
-specifying the type is permitted but not required.  When the type is
-not specified, the type of the variable is the type of the
-initialization expression.
-
-<pre>
-var v = *p
-</pre>
-
-<p>
-See also the <a href="#Constants">discussion of constants, below</a>.
-If a variable is not initialized explicitly, the type must be specified.
-In that case it will be
-implicitly initialized to the type's zero value (0, nil, etc.).  There are no
-uninitialized variables in Go.
-
-<p>
-Within a function, a short declaration syntax is available with
-<code>:=</code> .
-
-<pre>
-v1 := v2
-</pre>
-
-<p>
-This is equivalent to
-
-<pre>
-var v1 = v2
-</pre>
-
-<p>
-Go permits multiple assignments, which are done in parallel.
-
-<pre>
-i, j = j, i    // Swap i and j.
-</pre>
-
-<p>
-Functions may have multiple return values, indicated by a list in
-parentheses.  The returned values can be stored by assignment
-to a list of variables.
-
-<pre>
-func f() (i int, j int) { ... }
-v1, v2 = f()
-</pre>
-
-<p>
-Go code uses very few semicolons in practice.  Technically, all Go
-statements are terminated by a semicolon.  However, Go treats the end
-of a non-blank line as a semicolon unless the line is clearly
-incomplete (the exact rules are
-in <a href="go_spec.html#Semicolons">the language specification</a>).
-A consequence of this is that in some cases Go does not permit you to
-use a line break.  For example, you may not write
-<pre>
-func g()
-{                  // INVALID
-}
-</pre>
-A semicolon will be inserted after <code>g()</code>, causing it to be
-a function declaration rather than a function definition.  Similarly,
-you may not write
-<pre>
-if x {
-}
-else {             // INVALID
-}
-</pre>
-A semicolon will be inserted after the <code>}</code> preceding
-the <code>else</code>, causing a syntax error.
-
-<p>
-Since semicolons do end statements, you may continue using them as in
-C++.  However, that is not the recommended style.  Idiomatic Go code
-omits unnecessary semicolons, which in practice is all of them other
-than the initial <code>for</code> loop clause and cases where you want several
-short statements on a single line.
-
-<p>
-While we're on the topic, we recommend that rather than worry about
-semicolons and brace placement, you format your code with
-the <code>gofmt</code> program.  That will produce a single standard
-Go style, and let you worry about your code rather than your
-formatting.  While the style may initially seem odd, it is as good as
-any other style, and familiarity will lead to comfort.
-
-<p>
-When using a pointer to a struct, you use <code>.</code> instead
-of <code>-&gt;</code>.
-Thus syntactically speaking a structure and a pointer to a structure
-are used in the same way.
-
-<pre>
-type myStruct struct { i int }
-var v9 myStruct              // v9 has structure type
-var p9 *myStruct             // p9 is a pointer to a structure
-f(v9.i, p9.i)
-</pre>
-
-<p>
-Go does not require parentheses around the condition of a <code>if</code>
-statement, or the expressions of a <code>for</code> statement, or the value of a
-<code>switch</code> statement.  On the other hand, it does require curly braces
-around the body of an <code>if</code> or <code>for</code> statement.
-
-<pre>
-if a &lt; b { f() }             // Valid
-if (a &lt; b) { f() }           // Valid (condition is a parenthesized expression)
-if (a &lt; b) f()               // INVALID
-for i = 0; i &lt; 10; i++ {}    // Valid
-for (i = 0; i &lt; 10; i++) {}  // INVALID
-</pre>
-
-<p>
-Go does not have a <code>while</code> statement nor does it have a
-<code>do/while</code>
-statement.  The <code>for</code> statement may be used with a single condition,
-which makes it equivalent to a <code>while</code> statement.  Omitting the
-condition entirely is an endless loop.
-
-<p>
-Go permits <code>break</code> and <code>continue</code> to specify a label.
-The label must
-refer to a <code>for</code>, <code>switch</code>, or <code>select</code>
-statement.
-
-<p>
-In a <code>switch</code> statement, <code>case</code> labels do not fall
-through.  You can
-make them fall through using the <code>fallthrough</code> keyword.  This applies
-even to adjacent cases.
-
-<pre>
-switch i {
-case 0:  // empty case body
-case 1:
-    f()  // f is not called when i == 0!
-}
-</pre>
-
-<p>
-But a <code>case</code> can have multiple values.
-
-<pre>
-switch i {
-case 0, 1:
-    f()  // f is called if i == 0 || i == 1.
-}
-</pre>
-
-<p>
-The values in a <code>case</code> need not be constants&mdash;or even integers;
-any type
-that supports the equality comparison operator, such as strings or
-pointers, can be used&mdash;and if the <code>switch</code>
-value is omitted it defaults to <code>true</code>.
-
-<pre>
-switch {
-case i &lt; 0:
-    f1()
-case i == 0:
-    f2()
-case i &gt; 0:
-    f3()
-}
-</pre>
-
-<p>
-The <code>++</code> and <code>--</code> operators may only be used in
-statements, not in expressions.
-You cannot write <code>c = *p++</code>.  <code>*p++</code> is parsed as
-<code>(*p)++</code>.
-
-<p>
-The <code>defer</code> statement may be used to call a function after
-the function containing the <code>defer</code> statement returns.
-
-<pre>
-fd := open("filename")
-defer close(fd)         // fd will be closed when this function returns.
-</pre>
-
-<h2 id="Constants">Constants </h2>
-
-<p>
-In Go constants may be <i>untyped</i>. This applies even to constants
-named with a <code>const</code> declaration, if no
-type is given in the declaration and the initializer expression uses only
-untyped constants.
-A value derived from an untyped constant becomes typed when it
-is used within a context that
-requires a typed value. This permits constants to be used relatively
-freely without requiring general implicit type conversion.
-
-<pre>
-var a uint
-f(a + 1)  // untyped numeric constant "1" becomes typed as uint
-</pre>
-
-<p>
-The language does not impose any limits on the size of an untyped
-numeric constant or constant expression. A limit is only applied when
-a constant is used where a type is required.
-
-<pre>
-const huge = 1 &lt;&lt; 100
-f(huge &gt;&gt; 98)
-</pre>
-
-<p>
-Go does not support enums.  Instead, you can use the special name
-<code>iota</code> in a single <code>const</code> declaration to get a
-series of increasing
-value.  When an initialization expression is omitted for a <code>const</code>,
-it reuses the preceding expression.
-
-<pre>
-const (
-    red = iota   // red == 0
-    blue         // blue == 1
-    green        // green == 2
-)
-</pre>
-
-<h2 id="Slices">Slices</h2>
-
-<p>
-A slice is conceptually a struct with three fields: a
-pointer to an array, a length, and a capacity.
-Slices support
-the <code>[]</code> operator to access elements of the underlying array.
-The builtin
-<code>len</code> function returns the
-length of the slice.  The builtin <code>cap</code> function returns the
-capacity.
-
-<p>
-Given an array, or another slice, a new slice is created via
-<code>a[I:J]</code>.  This
-creates a new slice which refers to <code>a</code>, starts at
-index <code>I</code>, and ends before index
-<code>J</code>.  It has length <code>J - I</code>.
-The new slice refers to the same array
-to which <code>a</code>
-refers.  That is, changes made using the new slice may be seen using
-<code>a</code>.  The
-capacity of the new slice is simply the capacity of <code>a</code> minus
-<code>I</code>.  The capacity
-of an array is the length of the array.  You may also assign an array pointer
-to a variable of slice type; given <code>var s []int; var a[10] int</code>,
-the assignment <code>s = &amp;a</code> is equivalent to
-<code>s = a[0:len(a)]</code>.
-
-<p>
-What this means is that Go uses slices for some cases where C++ uses pointers.
-If you create a value of type <code>[100]byte</code> (an array of 100 bytes,
-perhaps a
-buffer) and you want to pass it to a function without copying it, you should
-declare the function parameter to have type <code>[]byte</code>, and pass the
-address
-of the array.  Unlike in C++, it is not
-necessary to pass the length of the buffer; it is efficiently accessible via
-<code>len</code>.
-
-<p>
-The slice syntax may also be used with a string.  It returns a new string,
-whose value is a substring of the original string.
-Because strings are immutable, string slices can be implemented
-without allocating new storage for the slices's contents.
-
-<h2 id="Making_values">Making values</h2>
-
-<p>
-Go has a builtin function <code>new</code> which takes a type and
-allocates space
-on the heap. The allocated space will be zero-initialized for the type.
-For example, <code>new(int)</code> allocates a new int on the heap,
-initializes it with the value <code>0</code>,
-and returns its address, which has type <code>*int</code>.
-Unlike in C++, <code>new</code> is a function, not an operator;
-<code>new int</code> is a syntax error.
-
-<p>
-Map and channel values must be allocated using the builtin function
-<code>make</code>.
-A variable declared with map or channel type without an initializer will be
-automatically initialized to <code>nil</code>.
-Calling <code>make(map[int]int)</code> returns a newly allocated value of
-type <code>map[int]int</code>.
-Note that <code>make</code> returns a value, not a pointer.  This is
-consistent with
-the fact that map and channel values are passed by reference.  Calling
-<code>make</code> with
-a map type takes an optional argument which is the expected capacity of the
-map.  Calling <code>make</code> with a channel type takes an optional
-argument which sets the
-buffering capacity of the channel; the default is 0 (unbuffered).
-
-<p>
-The <code>make</code> function may also be used to allocate a slice.
-In this case it
-allocates memory for the underlying array and returns a slice referring to it.
-There is one required argument, which is the number of elements in the slice.
-A second, optional, argument is the capacity of the slice.  For example,
-<code>make([]int, 10, 20)</code>.  This is identical to
-<code>new([20]int)[0:10]</code>.  Since
-Go uses garbage collection, the newly allocated array will be discarded
-sometime after there are no references to the returned slice.
-
-<h2 id="Interfaces">Interfaces</h2>
-
-<p>
-Where C++ provides classes, subclasses and templates,
-Go provides interfaces.  A
-Go interface is similar to a C++ pure abstract class: a class with no
-data members, with methods which are all pure virtual.  However, in
-Go, any type which provides the methods named in the interface may be
-treated as an implementation of the interface.  No explicitly declared
-inheritance is required.  The implementation of the interface is
-entirely separate from the interface itself.
-
-<p>
-A method looks like an ordinary function definition, except that it
-has a <em>receiver</em>.  The receiver is similar to
-the <code>this</code> pointer in a C++ class method.
-
-<pre>
-type myType struct { i int }
-func (p *myType) get() int { return p.i }
-</pre>
-
-<p>
-This declares a method <code>get</code> associated with <code>myType</code>.
-The receiver is named <code>p</code> in the body of the function.
-
-<p>
-Methods are defined on named types.  If you convert the value
-to a different type, the new value will have the methods of the new type,
-not the old type.
-
-<p>
-You may define methods on a builtin type by declaring a new named type
-derived from it.  The new type is distinct from the builtin type.
-
-<pre>
-type myInteger int
-func (p myInteger) get() int { return int(p) } // Conversion required.
-func f(i int) { }
-var v myInteger
-// f(v) is invalid.
-// f(int(v)) is valid; int(v) has no defined methods.
-</pre>
-
-<p>
-Given this interface:
-
-<pre>
-type myInterface interface {
-	get() int
-	set(i int)
-}
-</pre>
-
-<p>
-we can make <code>myType</code> satisfy the interface by adding
-
-<pre>
-func (p *myType) set(i int) { p.i = i }
-</pre>
-
-<p>
-Now any function which takes <code>myInterface</code> as a parameter
-will accept a
-variable of type <code>*myType</code>.
-
-<pre>
-func getAndSet(x myInterface) {}
-func f1() {
-	var p myType
-	getAndSet(&amp;p)
-}
-</pre>
-
-<p>
-In other words, if we view <code>myInterface</code> as a C++ pure abstract
-base
-class, defining <code>set</code> and <code>get</code> for
-<code>*myType</code> made <code>*myType</code> automatically
-inherit from <code>myInterface</code>.  A type may satisfy multiple interfaces.
-
-<p>
-An anonymous field may be used to implement something much like a C++ child
-class.
-
-<pre>
-type myChildType struct { myType; j int }
-func (p *myChildType) get() int { p.j++; return p.myType.get() }
-</pre>
-
-<p>
-This effectively implements <code>myChildType</code> as a child of
-<code>myType</code>.
-
-<pre>
-func f2() {
-	var p myChildType
-	getAndSet(&amp;p)
-}
-</pre>
-
-<p>
-The <code>set</code> method is effectively inherited from
-<code>myChildType</code>, because
-methods associated with the anonymous field are promoted to become methods
-of the enclosing type.  In this case, because <code>myChildType</code> has an
-anonymous field of type <code>myType</code>, the methods of
-<code>myType</code> also become methods of <code>myChildType</code>.
-In this example, the <code>get</code> method was
-overridden, and the <code>set</code> method was inherited.
-
-<p>
-This is not precisely the same as a child class in C++.
-When a method of an anonymous field is called,
-its receiver is the field, not the surrounding struct.
-In other words, methods on anonymous fields are not virtual functions.
-When you want the equivalent of a virtual function, use an interface.
-
-<p>
-A variable which has an interface type may be converted to have a
-different interface type using a special construct called a type assertion.
-This is implemented dynamically
-at run time, like C++ <code>dynamic_cast</code>.  Unlike
-<code>dynamic_cast</code>, there does
-not need to be any declared relationship between the two interfaces.
-
-<pre>
-type myPrintInterface interface {
-  print()
-}
-func f3(x myInterface) {
-	x.(myPrintInterface).print()  // type assertion to myPrintInterface
-}
-</pre>
-
-<p>
-The conversion to <code>myPrintInterface</code> is entirely dynamic.
-It will
-work as long as the underlying type of x (the <em>dynamic type</em>) defines
-a <code>print</code> method.
-
-<p>
-Because the conversion is dynamic, it may be used to implement generic
-programming similar to templates in C++.  This is done by
-manipulating values of the minimal interface.
-
-<pre>
-type Any interface { }
-</pre>
-
-<p>
-Containers may be written in terms of <code>Any</code>, but the caller
-must unbox using a type assertion to recover
-values of the contained type.  As the typing is dynamic rather
-than static, there is no equivalent of the way that a C++ template may
-inline the relevant operations.  The operations are fully type-checked
-at run time, but all operations will involve a function call.
-
-<pre>
-type iterator interface {
-	get() Any
-	set(v Any)
-	increment()
-	equal(arg *iterator) bool
-}
-</pre>
-
-<h2 id="Goroutines">Goroutines</h2>
-
-<p>
-Go permits starting a new thread of execution (a <em>goroutine</em>)
-using the <code>go</code>
-statement.  The <code>go</code> statement runs a function in a
-different, newly created, goroutine.
-All goroutines in a single program share the same address space.
-
-<p>
-Internally, goroutines act like coroutines that are multiplexed among
-multiple operating system threads.  You do not have to worry
-about these details.
-
-<pre>
-func server(i int) {
-    for {
-        print(i)
-        sys.sleep(10)
-    }
-}
-go server(1)
-go server(2)
-</pre>
-
-<p>
-(Note that the <code>for</code> statement in the <code>server</code>
-function is equivalent to a C++ <code>while (true)</code> loop.)
-
-<p>
-Goroutines are (intended to be) cheap.
-
-<p>
-Function literals (which Go implements as closures)
-can be useful with the <code>go</code> statement.
-
-<pre>
-var g int
-go func(i int) {
-	s := 0
-	for j := 0; j &lt; i; j++ { s += j }
-	g = s
-}(1000)  // Passes argument 1000 to the function literal.
-</pre>
-
-<h2 id="Channels">Channels</h2>
-
-<p>
-Channels are used to communicate between goroutines.  Any value may be
-sent over a channel.  Channels are (intended to be) efficient and
-cheap.  To send a value on a channel, use <code>&lt;-</code> as a binary
-operator.  To
-receive a value on a channel, use <code>&lt;-</code> as a unary operator.
-When calling
-functions, channels are passed by reference.
-
-<p>
-The Go library provides mutexes, but you can also use
-a single goroutine with a shared channel.
-Here is an example of using a manager function to control access to a
-single value.
-
-<pre>
-type cmd struct { get bool; val int }
-func manager(ch chan cmd) {
-	var val int = 0
-	for {
-		c := &lt;- ch
-		if c.get { c.val = val; ch &lt;- c }
-		else { val = c.val }
-	}
-}
-</pre>
-
-<p>
-In that example the same channel is used for input and output.
-This is incorrect if there are multiple goroutines communicating
-with the manager at once: a goroutine waiting for a response
-from the manager might receive a request from another goroutine
-instead.
-A solution is to pass in a channel.
-
-<pre>
-type cmd2 struct { get bool; val int; ch &lt;- chan int }
-func manager2(ch chan cmd2) {
-	var val int = 0
-	for {
-		c := &lt;- ch
-		if c.get { c.ch &lt;- val }
-		else { val = c.val }
-	}
-}
-</pre>
-
-<p>
-To use <code>manager2</code>, given a channel to it:
-
-<pre>
-func f4(ch &lt;- chan cmd2) int {
-	myCh := make(chan int)
-	c := cmd2{ true, 0, myCh }   // Composite literal syntax.
-	ch &lt;- c
-	return &lt;-myCh
-}
-</pre>

doc/go_mem.html

@@ -1,5 +1,8 @@
-<!-- The Go Memory Model -->
-<!-- subtitle Version of June 10, 2011 -->
+<!--{
+	"Title": "The Go Memory Model",
+	"Subtitle": "Version of March 6, 2012",
+	"Path": "/ref/mem"
+}-->
 
 <style>
 p.rule {
@@ -54,7 +57,7 @@ if both of the following hold:
 </p>
 
 <ol>
-<li><span class="event">w</span> happens before <span class="event">r</span>.</li>
+<li><span class="event">r</span> does not happen before <span class="event">w</span>.</li>
 <li>There is no other write <span class="event">w'</span> to <code>v</code> that happens
     after <span class="event">w</span> but before <span class="event">r</span>.</li>
 </ol>
@@ -104,9 +107,9 @@ unspecified order.
 <h3>Initialization</h3>
 
 <p>
-Program initialization runs in a single goroutine and
-new goroutines created during initialization do not
-start running until initialization ends.
+Program initialization runs in a single goroutine,
+but that goroutine may create other goroutines,
+which run concurrently.
 </p>
 
 <p class="rule">
@@ -119,11 +122,6 @@ The start of the function <code>main.main</code> happens after
 all <code>init</code> functions have finished.
 </p>
 
-<p class="rule">
-The execution of any goroutines created during <code>init</code>
-functions happens after all <code>init</code> functions have finished.
-</p>
-
 <h3>Goroutine creation</h3>
 
 <p class="rule">
@@ -285,7 +283,7 @@ The <code>sync</code> package implements two lock data types,
 
 <p class="rule">
 For any <code>sync.Mutex</code> or <code>sync.RWMutex</code> variable <code>l</code> and <i>n</i> &lt; <i>m</i>,
-the <i>n</i>'th call to <code>l.Unlock()</code> happens before the <i>m</i>'th call to <code>l.Lock()</code> returns.
+call <i>n</i> of <code>l.Unlock()</code> happens before call <i>m</i> of <code>l.Lock()</code> returns.
 </p>
 
 <p>
@@ -318,9 +316,9 @@ which happens before the <code>print</code>.
 
 <p class="rule">
 For any call to <code>l.RLock</code> on a <code>sync.RWMutex</code> variable <code>l</code>,
-there is an <i>n</i> such that the <code>l.RLock</code> happens (returns) after the <i>n</i>'th call to
+there is an <i>n</i> such that the <code>l.RLock</code> happens (returns) after call <i>n</i> to
 <code>l.Unlock</code> and the matching <code>l.RUnlock</code> happens
-before the <i>n</i>+1'th call to <code>l.Lock</code>.
+before call <i>n</i>+1 to <code>l.Lock</code>.
 </p>
 
 <h3>Once</h3>

doc/go_tutorial.tmpl

@@ -1,990 +0,0 @@
-<!-- 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.