This will be nicer to the automatic tools.
It requires a few more assembly stubs
but fewer Go files.

There are a few instances where it looks like
there are new blobs of code, but they are just
being copied out of deleted files.

There is no new code here.

Suppose you have a portable implementation for Sin
and a 386-specific assembly one.  The old way to
do this was to write three files

sin_decl.go
   func Sin(x float64) float64  // declaration only
sin_386.s
   assembly implementation

sin_port.go
   func Sin(x float64) float64 { ... }  // pure-Go impl

and then link in either sin_decl.go+sin_386.s or
just sin_port.go.  The Makefile actually did the magic
of linking in only the _port.go files for those without
assembly and only the _decl.go files for those with
assembly, or at least some of that magic.

The biggest problem with this, beyond being hard
to explain to the build system, is that once you do
explain it to the build system, godoc knows which
of sin_port.go or sin_decl.go are involved on a given
architecture, and it (correctly) ignores the other.
That means you have to put identical doc comments
in both files.

The new approach, which is more like what we did
in the later packages math/big and sync/atomic,
is to have

sin.go
   func Sin(x float64) float64  // decl only
   func sin(x float64) float64 {...}  // pure-Go impl

sin_386.s
   // assembly for Sin (ignores sin)
sin_amd64.s
   // assembly for Sin: jmp sin
sin_arm.s
   // assembly for Sin: jmp sin

Once we abandon Makefiles we can put all the assembly
stubs in one source file, so the number of files will
actually go down.

Chris asked whether the branches cost anything.
Given that they are branching to pure-Go implementations
that are not typically known for their speed, the single
direct branch is not going to be noticeable.  That is,
it's on the slow path.

An alternative would have been to preserve the old
"only write assembly files when there's an implementation"
and still have just one copy of the declaration of Sin
(and thus one doc comment) by doing:

sin.go
   func Sin(x float64) float64 { return sin(x) }

sin_decl.go
   func sin(x float64) float64 // declaration only
sin_386.s
   // assembly for sin

sin_port.go
   func sin(x float64) float64 { portable code }

In this version everyone would link in sin.go and
then either sin_decl.go+sin_386.s or sin_port.go.

This has an extra function call on all paths, including
the "fast path" to get to assembly, and it triples the
number of Go files involved compared to what I did
in this CL.  On the other hand you don't have to
write assembly stubs.  After starting down this path
I decided that the assembly stubs were the easier
approach.

As for generating the assembly stubs on the fly, much
of the goal here is to eliminate magic from the build
process, so that zero-configuration tools like goinstall
or the new go tool can handle this package.

R=golang-dev, r, cw, iant, r
CC=golang-dev
https://golang.org/cl/5488057

Actually compare the result with expected not itself

R=agl, bradfitz
CC=golang-dev, rsc
https://golang.org/cl/5477079

This CL is concerned with the basic Package structure
and applies it to the (trivial) implementations of the
doc, fmt, fix, list, and vet commands.

The command as a whole is still very much a work in progress.
In particular, work making the error messages look nice
is deferred to a future CL.

R=golang-dev, adg, dsymonds, r
CC=golang-dev
https://golang.org/cl/5482048

Apparently it is broken.  Disable so that dashboard
will let us see other breakages on Windows.

R=golang-dev, bradfitz
CC=golang-dev
https://golang.org/cl/5477081

Just an oversight it didn't already.
Fixes #2515.

R=golang-dev, rsc
CC=golang-dev
https://golang.org/cl/5483064

R=ken2
CC=golang-dev
https://golang.org/cl/5482059

Fixes #2548.

R=golang-dev, rsc
CC=golang-dev
https://golang.org/cl/5484062

Example:

PACKAGE

package utf8
    import "unicode/utf8"

    Package utf8 implements functions and constants to support text
    encoded in UTF-8.  This package calls a Unicode character a rune for
    brevity.

CONSTANTS

const (
    RuneError = unicode.ReplacementChar // the "error" Rune or "replacement character".
    RuneSelf  = 0x80                    // characters below Runeself are represented as themselves in a single byte.
    UTFMax    = 4                       // maximum number of bytes of a UTF-8 encoded Unicode character.
)
    Numbers fundamental to the encoding.

FUNCTIONS

func DecodeLastRune(p []byte) (r rune, size int)
    DecodeLastRune unpacks the last UTF-8 encoding in p and returns the
    rune and its width in bytes.

func DecodeLastRuneInString(s string) (r rune, size int)
    DecodeLastRuneInString is like DecodeLastRune but its input is a
    string.

func DecodeRune(p []byte) (r rune, size int)
    DecodeRune unpacks the first UTF-8 encoding in p and returns the rune
    and its width in bytes.

func DecodeRuneInString(s string) (r rune, size int)
    DecodeRuneInString is like DecodeRune but its input is a string.

func EncodeRune(p []byte, r rune) int
    EncodeRune writes into p (which must be large enough) the UTF-8
    encoding of the rune.  It returns the number of bytes written.

func FullRune(p []byte) bool
    FullRune reports whether the bytes in p begin with a full UTF-8
    encoding of a rune.  An invalid encoding is considered a full Rune
    since it will convert as a width-1 error rune.

func FullRuneInString(s string) bool
    FullRuneInString is like FullRune but its input is a string.

func RuneCount(p []byte) int
    RuneCount returns the number of runes in p.  Erroneous and short
    encodings are treated as single runes of width 1 byte.

func RuneCountInString(s string) (n int)
    RuneCountInString is like RuneCount but its input is a string.

func RuneLen(r rune) int
    RuneLen returns the number of bytes required to encode the rune.

func RuneStart(b byte) bool
    RuneStart reports whether the byte could be the first byte of an
    encoded rune.  Second and subsequent bytes always have the top two
    bits set to 10.

func Valid(p []byte) bool
    Valid reports whether p consists entirely of valid UTF-8-encoded
    runes.

func ValidString(s string) bool
    ValidString reports whether s consists entirely of valid UTF-8-encoded
    runes.

TYPES

type String struct {
    // contains filtered or unexported fields
}
    String wraps a regular string with a small structure that provides
    more efficient indexing by code point index, as opposed to byte index.
    Scanning incrementally forwards or backwards is O(1) per index
    operation (although not as fast a range clause going forwards).
    Random access is O(N) in the length of the string, but the overhead is
    less than always scanning from the beginning.  If the string is ASCII,
    random access is O(1).  Unlike the built-in string type, String has
    internal mutable state and is not thread-safe.

func NewString(contents string) *String
    NewString returns a new UTF-8 string with the provided contents.

func (s *String) At(i int) rune
    At returns the rune with index i in the String.  The sequence of runes
    is the same as iterating over the contents with a "for range" clause.

func (s *String) Init(contents string) *String
    Init initializes an existing String to hold the provided contents.
    It returns a pointer to the initialized String.

func (s *String) IsASCII() bool
    IsASCII returns a boolean indicating whether the String contains only
    ASCII bytes.

func (s *String) RuneCount() int
    RuneCount returns the number of runes (Unicode code points) in the
    String.

func (s *String) Slice(i, j int) string
    Slice returns the string sliced at rune positions [i:j].

func (s *String) String() string
    String returns the contents of the String.  This method also means the
    String is directly printable by fmt.Print.

Fixes #2479.

R=golang-dev, dsymonds, mattn.jp, r, gri, r
CC=golang-dev
https://golang.org/cl/5472051

The relevant header is already included.

R=ken2
CC=golang-dev
https://golang.org/cl/5487062

R=gustav.paul
CC=golang-dev
https://golang.org/cl/5480062

don't crash when printing error messages about symbols in a garbled state.
render OCOMPLIT in export mode.

R=rsc
CC=golang-dev
https://golang.org/cl/5466045

Fixes #2529

R=rsc, rogpeppe
CC=golang-dev
https://golang.org/cl/5483048

R=rsc
CC=golang-dev
https://golang.org/cl/5477077

Everything there (as first draft) except the time package.

R=golang-dev, adg, bradfitz
CC=golang-dev
https://golang.org/cl/5487052

To allow these types as map keys, we must fill in
equal and hash functions in their algorithm tables.
Structs or arrays that are "just memory", like [2]int,
can and do continue to use the AMEM algorithm.
Structs or arrays that contain special values like
strings or interface values use generated functions
for both equal and hash.

The runtime helper func runtime.equal(t, x, y) bool handles
the general equality case for x == y and calls out to
the equal implementation in the algorithm table.

For short values (<= 4 struct fields or array elements),
the sequence of elementwise comparisons is inlined
instead of calling runtime.equal.

R=ken, mpimenov
CC=golang-dev
https://golang.org/cl/5451105

Also, clarify when interface comparison panics and
that comparison to nil is a special syntax rather than
a general comparison rule.

R=r, gri, r, iant, cw, bradfitz
CC=golang-dev
https://golang.org/cl/5440117

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

Nodes now have a Namespace field.

Pass adoption01.dat, test 12:
<a><svg><tr><input></a>

| <html>
|   <head>
|   <body>
|     <a>
|       <svg svg>
|         <svg tr>
|           <svg input>

The other adoption01.dat tests already passed.

R=andybalholm
CC=golang-dev
https://golang.org/cl/5467075

R=golang-dev, jsing, rsc
CC=golang-dev
https://golang.org/cl/5479054

R=golang-dev, rsc
CC=golang-dev
https://golang.org/cl/5488052

R=golang-dev, rsc
CC=golang-dev
https://golang.org/cl/5394042

R=rsc
CC=golang-dev
https://golang.org/cl/5454047

R=adg, r, rsc
CC=golang-dev
https://golang.org/cl/5475069

Some VMs are slow.  Very slow.
Fixes #2421.

R=golang-dev, r
CC=golang-dev
https://golang.org/cl/5482049

Fixes #2508.

R=rsc, krasin
CC=golang-dev
https://golang.org/cl/5449115

R=rsc
CC=golang-dev
https://golang.org/cl/5477052

R=golang-dev, r, tux21b, rsc
CC=golang-dev
https://golang.org/cl/5479062

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

Originally published on The Go Programming Language Blog, July 12, 2011.

http://blog.golang.org/2011/07/error-handling-and-go.html

Update #2547

R=golang-dev, r
CC=golang-dev
https://golang.org/cl/5475060

Fixes #2542

R=golang-dev, r
CC=golang-dev
https://golang.org/cl/5483054

R=golang-dev, dsymonds, r, rsc
CC=golang-dev
https://golang.org/cl/5483044

SysUnused being a direct call to madvise MADV_DONTNEED.

R=golang-dev, dave
CC=golang-dev
https://golang.org/cl/5477057

R=golang-dev, ality
CC=golang-dev, rsc
https://golang.org/cl/5467066

R=lucio.dere, rsc
CC=golang-dev
https://golang.org/cl/5440073

I had to move readFile into sys_$GOOS.go
since syscall.Open takes only two arguments
on Plan 9.

R=lucio.dere, rsc, alex.brainman
CC=golang-dev
https://golang.org/cl/5447061

Fixes #2502.

R=golang-dev, rsc
CC=golang-dev, remy
https://golang.org/cl/5472062

Addresses issue 2526

R=rsc, r
CC=golang-dev
https://golang.org/cl/5448114

Nextafter(0, -1) != -0.

R=rsc, golang-dev
CC=golang-dev
https://golang.org/cl/5467060

This will not currently create valid NetBSD binaries because NetBSD requires
an ELF note section to run, otherwise the kernel will throw ENOEXEC. I was
unable to determine an elegant way to add the section, so I am submitting
what I have.

References:
http://www.netbsd.org/docs/kernel/elf-notes.html
http://mail-index.netbsd.org/netbsd-bugs/2001/08/03/0012.html

R=rsc
CC=golang-dev
https://golang.org/cl/5472049

R=golang-dev, rsc
CC=golang-dev
https://golang.org/cl/5476048