doc: consolidate FAQs into a single file, go_faq.html

An entirely mechanical change, with these exceptions:
- removed 'stub questions' that reference the other FAQs
- removed "Why doesn't Go run on Windows yet?" - out of date

I will follow this CL with another that updates many of the
answers to make them more current.

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

4 files changed, 792 insertions, 887 deletions

diff --git a/doc/docs.html b/doc/docs.html
index ae27dd2de0..911a27d589 100644
--- a/doc/docs.html
+++ b/doc/docs.html
@@ -30,6 +30,11 @@ A must read for any new Go programmer. It augments the tutorial and
 the language spec, both of which should be read first.
 </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>
 <p>
 How to write a new package and how to test code.
@@ -47,23 +52,6 @@ and closures.
 An introduction to Go for C++ programmers.
 </p>
 
-<h2 id="faqs">Frequently Asked Questions</h2>
-
-<h3 id="go_faq"><a href="go_faq.html">Go FAQ</a></h3>
-<p>
-Answers to common questions about Go.
-</p>
-
-<h3 id="go_programming_faq"><a href="go_programming_faq.html">Programming FAQ</a></h3>
-<p>
-Answers to common questions about programming with Go.
-</p>
-
-<h3 id="go_lang_faq"><a href="go_lang_faq.html">Language Design FAQ</a></h3>
-<p>
-Answers to common questions about the design decisions behind Go.
-</p>
-
 <h2 id="tutorials_nonenglish">Non-English Documentation</h2>
 
 <h3 id="tutorial_de"><a href="http://bitloeffel.de/DOC/golang/go_tutorial_de.html">Eine Anleitung zum Programmieren in Go</a></h3>
diff --git a/doc/go_faq.html b/doc/go_faq.html
index 5ca791c50e..3f4e214b11 100644
--- a/doc/go_faq.html
+++ b/doc/go_faq.html
@@ -1,9 +1,5 @@
 <!-- FAQ -->
 
-<div class="detail">
-<p>Is your question not answered here? Try the <a href="go_programming_faq.html">Programming FAQ</a> or the <a href="go_lang_faq.html">Language Design FAQ</a>.</p>
-</div>
-
 <h2 id="Origins">Origins</h2>
 
 <h3 id="What_is_the_purpose_of_the_project">
@@ -60,6 +56,21 @@ What is the origin of the name?</h3>
 <p>
 &ldquo;Ogle&rdquo; would be a good name for a Go debugger.
 
+<h3 id="Whats_the_origin_of_the_mascot">
+What's the origin of the mascot?</h3>
+
+<p>
+The mascot and logo were designed by
+<a href="http://reneefrench.blogspot.com">Renée French</a>, who also designed
+<a href="http://plan9.bell-labs.com/plan9/glenda.html">Glenda</a>,
+the Plan 9 bunny.
+The gopher is derived from one she used for an <a href="http://wfmu.org/">WFMU</a>
+T-shirt design some years ago.
+The logo and mascot are covered by the
+<a href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0</a>
+license.
+</p>
+
 <h3 id="What_kind_of_a_name_is_6g">
 What kind of a name is 6g?</h3>
 
@@ -73,42 +84,102 @@ http://plan9.bell-labs.com/sys/doc/compiler.html</a>
 <code>6</code> is the architecture letter for amd64 (or x86-64, if you prefer), while
 <code>g</code> stands for Go.
 
-<h3 id="Why_not_just_write_some_libraries_for_Cpp_to_do_communication">
-Why not just write some libraries for C++ to do communication?</h3>
+<h3 id="history">
+What is the history of the project?</h3>
+<p>
+Robert Griesemer, Rob Pike and Ken Thompson started sketching the
+goals for a new language on the white board on September 21, 2007.
+Within a few days the goals had settled into a plan to do something
+and a fair idea of what it would be.  Design continued part-time in
+parallel with unrelated work.  By January 2008, Ken had started work
+on a compiler with which to explore ideas; it generated C code as its
+output.  By mid-year the language had become a full-time project and
+had settled enough to attempt a production compiler.  In May 2008,
+Ian Taylor independently started on a GCC front end for Go using the
+draft specification.  Russ Cox joined in late 2008 and helped move the language
+and libraries from prototype to reality.
+</p>
+
+<p>
+Many others have contributed ideas, discussions, and code.
+</p>
+
 
-<p>We considered doing that, but too many of the problems&mdash;lack of
-garbage collection, long dependency chains, nested include files,
-lack of concurrency awareness&mdash;are rooted in the design of
-the C and C++ languages themselves.
-We felt a viable solution required a more complete approach.
+<h3 id="creating_a_new_language">
+Why are you creating a new language?</h3>
+<p>
+Go was born out of frustration with existing languages and
+environments for systems programming.  Programming had become too
+difficult and the choice of languages was partly to blame.  One had to
+choose either efficient compilation, efficient execution, or ease of
+programming; all three were not available in the same mainstream
+language.  Programmers who could were choosing ease over
+safety and efficiency by moving to dynamically typed languages such as
+Python and JavaScript rather than C++ or, to a lesser extent, Java.
+</p>
+<p>
+Go is an attempt to combine the ease of programming of an interpreted,
+dynamically typed
+language with the efficiency and safety of a statically typed, compiled language.
+It also aims to be modern, with support for networked and multicore
+computing.  Finally, it is intended to be <i>fast</i>: it should take
+at most a few seconds to build a large executable on a single computer.
+To meet these goals required addressing a number of
+linguistic issues: an expressive but lightweight type system;
+concurrency and garbage collection; rigid dependency specification;
+and so on.  These cannot be addressed well by libraries or tools; a new
+language was called for.
+</p>
 
-<h3 id="Why_doesnt_Go_run_on_Windows">
-Why doesn't Go run on Windows yet?</h3>
 
+<h3 id="ancestors">
+What are Go's ancestors?</h3>
 <p>
-We understand that a significant fraction of computers in the world
-run Windows and it would be great if those computers could run Go
-programs.  A group of volunteers has made significant progress toward 
-porting Go to <a href="http://www.mingw.org/">MinGW</a>.
-You can follow their progress at the Go Wiki's
-<a href="http://code.google.com/p/go/wiki/WindowsPort">WindowsPort</a> page.
+Go is mostly in the C family (basic syntax),
+with significant input from the Pascal/Modula/Oberon
+family (declarations, packages),
+plus some ideas from languages
+inspired by Tony Hoare's CSP,
+such as Newsqueak and Limbo (concurrency).
+However, it is a new language across the board.
+In every respect the language was designed by thinking
+about what programmers do and how to make programming, at least the
+kind of programming we do, more effective, which means more fun.
 </p>
 
-<h3 id="Whats_the_origin_of_the_mascot">
-What's the origin of the mascot?</h3>
 
+<h3 id="principles">
+What are the guiding principles in the design?</h3>
 <p>
-The mascot and logo were designed by
-<a href="http://reneefrench.blogspot.com">Renée French</a>, who also designed
-<a href="http://plan9.bell-labs.com/plan9/glenda.html">Glenda</a>,
-the Plan 9 bunny.
-The gopher is derived from one she used for an <a href="http://wfmu.org/">WFMU</a>
-T-shirt design some years ago.
-The logo and mascot are covered by the
-<a href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0</a>
-license.
+Programming today involves too much bookkeeping, repetition, and
+clerical work.  As Dick Gabriel says, &ldquo;Old programs read
+like quiet conversations between a well-spoken research worker and a
+well-studied mechanical colleague, not as a debate with a compiler.
+Who'd have guessed sophistication bought such noise?&rdquo;
+The sophistication is worthwhile&mdash;no one wants to go back to
+the old languages&mdash;but can it be more quietly achieved?
+</p>
+<p>
+Go attempts to reduce the amount of typing in both senses of the word.
+Throughout its design, we have tried to reduce clutter and
+complexity.  There are no forward declarations and no header files;
+everything is declared exactly once.  Initialization is expressive,
+automatic, and easy to use.  Syntax is clean and light on keywords.
+Stuttering (<code>foo.Foo* myFoo = new(foo.Foo)</code>) is reduced by
+simple type derivation using the <code>:=</code>
+declare-and-initialize construct.  And perhaps most radically, there
+is no type hierarchy: types just <i>are</i>, they don't have to
+announce their relationships.  These simplifications allow Go to be
+expressive yet comprehensible without sacrificing, well, sophistication.
+</p>
+<p>
+Another important principle is to keep the concepts orthogonal.
+Methods can be implemented for any type; structures represent data while
+interfaces represent abstraction; and so on.  Orthogonality makes it
+easier to understand what happens when things combine.
 </p>
 
+
 <h2 id="Usage">Usage</h2>
 
 <h3 id="Who_should_use_the_language">
@@ -174,7 +245,35 @@ you will need to abide by the guidelines at
 
 <h2 id="Design">Design</h2>
 
-<h3 id="Why_doesnt_Go_have_feature_X">Why doesn't Go have feature X?</h3>
+<h3 id="unicode_identifiers">
+What's up with Unicode identifiers?</h3>
+
+<p>
+It was important to us to extend the space of identifiers from the
+confines of ASCII.  Go's rule&mdash;identifier characters must be
+letters or digits as defined by Unicode&mdash;is simple to understand
+and to implement but has restrictions.  Combining characters are
+excluded by design, for instance.
+Until there
+is an agreed external definition of what an identifier might be,
+plus a definition of canonicalization of identifiers that guarantees
+no ambiguity, it seemed better to keep combining characters out of
+the mix.  Thus we have a simple rule that can be expanded later
+without breaking programs, one that avoids bugs that would surely arise
+from a rule that admits ambiguous identifiers.
+</p>
+
+<p>
+On a related note, since an exported identifier must begin with an
+upper-case letter, identifiers created from &ldquo;letters&rdquo;
+in some languages can, by definition, not be exported.  For now the
+only solution is to use something like <code>X日本語</code>, which
+is clearly unsatisfactory; we are considering other options.  The
+case-for-visibility rule is unlikely to change however; it's one
+of our favorite features of Go.
+</p>
+
+<h3 id="Why_doesnt_Go_have_feature_X">Why does Go not have feature X?</h3>
 
 <p>
 Every language contains novel features and omits someone's favorite
@@ -190,15 +289,142 @@ If it bothers you that Go is missing feature <var>X</var>,
 please forgive us and investigate the features that Go does have. You might find that
 they compensate in interesting ways for the lack of <var>X</var>.
 
-<h3 id="Why_is_the_syntax_so_different_from_Cpp">
-Why is the syntax so different from C++?</h3>
+<h3 id="generics">
+Why does Go not have generic types?</h3>
+<p>
+Generics may well be added at some point.  We don't feel an urgency for
+them, although we understand some programmers do.
+</p>
+<p>
+Generics are convenient but they come at a cost in
+complexity in the type system and run-time.  We haven't yet found a
+design that gives value proportionate to the complexity, although we
+continue to think about it.  Meanwhile, Go's built-in maps and slices,
+plus the ability to use the empty interface to construct containers
+(with explicit unboxing) mean in many cases it is possible to write
+code that does what generics would enable, if less smoothly.
+</p>
+<p>
+This remains an open issue.
+</p>
 
+<h3 id="exceptions">
+Why does Go not have exceptions?</h3>
+<p>
+We believe that coupling exceptions to a control
+structure, as in the <code>try-catch-finally</code> idiom, results in
+convoluted code.  It also tends to encourage programmers to label
+too many ordinary errors, such as failing to open a file, as
+exceptional.
+</p>
 <p>
-This and other language design questions are answered in
-the separate <a href="go_lang_faq.html">language design FAQ</a>.
+Go takes a different approach.  Instead of exceptions, it has a couple
+of built-in functions to signal and recover from truly exceptional
+conditions.  The recovery mechanism is executed only as part of a
+function's state being torn down after an error, which is sufficient
+to handle catastrophe but requires no extra control structures and,
+when used well, can result in clean error-handling code.
+</p>
+
 
-<h2 id="Object_Oriented_Programming">
-Object-Oriented Programming</h2>
+<h3 id="assertions">
+Why does Go not have assertions?</h3>
+
+<p>
+Go doesn't provide assertions. They are undeniably convenient, but our
+experience has been that programmers use them as a crutch to avoid thinking
+about proper error handling and reporting. Proper error handling means that
+servers continue operation after non-fatal errors instead of crashing.
+Proper error reporting means that errors are direct and to the point,
+saving the programmer from interpreting a large crash trace. Precise
+errors are particularly important when the programmer seeing the errors is
+not familiar with the code.
+
+<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>
+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>
+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
+because we feel it's sometimes worth trying a different approach.
+
+<h3 id="csp">
+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
+designs such as pthreads and partly to overemphasis on low-level details
+such as mutexes, condition variables, and even memory barriers.
+Higher-level interfaces enable much simpler code, even if there are still
+mutexes and such under the covers.
+</p>
+<p>
+One of the most successful models for providing high-level linguistic support
+for concurrency comes from Hoare's Communicating Sequential Processes, or CSP.
+Occam and Erlang are two well known languages that stem from CSP.
+Go's concurrency primitives derive from a different part of the family tree
+whose main contribution is the powerful notion of channels as first class objects.
+</p>
+
+<h3 id="goroutines">
+Why goroutines instead of threads?</h3>
+<p>
+Goroutines are part of making concurrency easy to use.  The idea, which has
+been around for a while, is to multiplex independently executing
+functions&mdash;coroutines, really&mdash;onto a set of threads.
+When a coroutine blocks, such as by calling a blocking system call,
+the run-time automatically moves other coroutines on the same operating
+system thread to a different, runnable thread so they won't be blocked.
+The programmer sees none of this, which is the point.
+The result, which we call goroutines, can be very cheap: unless they spend a lot of time
+in long-running system calls, they cost little more than the memory
+for the stack.
+</p>
+<p>
+To make the stacks small, Go's run-time uses segmented stacks.  A newly
+minted goroutine is given a few kilobytes, which is almost always enough.
+When it isn't, the run-time allocates (and frees) extension segments automatically.
+The overhead averages about three cheap instructions per function call.
+It is practical to create hundreds of thousands of goroutines in the same
+address space.  If goroutines were just threads, system resources would
+run out at a much smaller number.
+</p>
+
+<h3 id="atomic_maps">
+Why are map operations not defined to be atomic?</h3>
+
+<p>
+After long discussion it was decided that the typical use of maps did not require
+safe access from multiple threads, and in those cases where it did, the map was
+probably part of some larger data structure or computation that was already
+synchronized.  Therefore requiring that all map operations grab a mutex would slow
+down most programs and add safety to few.  This was not an easy decision,
+however, since it means uncontrolled map access can crash the program.
+</p>
+
+<p>
+The language does not preclude atomic map updates.  When required, such
+as when hosting an untrusted program, the implementation could interlock
+map access.
+</p>
+
+
+<h2 id="types">Types</h2>
 
 <h3 id="Is_Go_an_object-oriented_language">
 Is Go an object-oriented language?</h3>
@@ -224,6 +450,130 @@ How do I get dynamic dispatch of methods?</h3>
 The only way to have dynamically dispatched methods is through an
 interface. Methods on structs or other types are always resolved statically.
 
+<h3 id="inheritance">
+Why is there no type inheritance?</h3>
+<p>
+Object-oriented programming, at least in the best-known languages,
+involves too much discussion of the relationships between types,
+relationships that often could be derived automatically.  Go takes a
+different approach.
+</p>
+<p>
+Rather than requiring the programmer to declare ahead of time that two
+types are related, in Go a type automatically satisfies any interface
+that specifies a subset of its methods.  Besides reducing the
+bookkeeping, this approach has real advantages.  Types can satisfy
+many interfaces at once, without the complexities of traditional
+multiple inheritance.
+Interfaces can be very lightweight&mdash;having one or even zero methods
+in an interface can express useful concepts.
+Interfaces can be added after the fact if a new idea comes along
+or for testing&mdash;without annotating the original types.
+Because there are no explicit relationships between types
+and interfaces, there is no type hierarchy to manage or discuss.
+</p>
+<p>
+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
+(<code>io.Writer</code>) representing a single method
+(<code>Write</code>).  And that's only scratching the surface.
+</p>
+<p>
+It takes some getting used to but this implicit style of type
+dependency is one of the most exciting things about Go.
+</p>
+
+<h3 id="methods_on_basics">
+Why is <code>len</code> a function and not a method?</h3>
+<p>
+We debated this issue but decided
+implementing <code>len</code> and friends as functions was fine in practice and
+didn't complicate questions about the interface (in the Go type sense)
+of basic types.
+</p>
+
+<h3 id="overloading">
+Why does Go not support overloading of methods and operators?</h3>
+<p>
+Method dispatch is simplified if it doesn't need to do type matching as well.
+Experience with other languages told us that having a variety of
+methods with the same name but different signatures was occasionally useful
+but that it could also be confusing and fragile in practice.  Matching only by name
+and requiring consistency in the types was a major simplifying decision
+in Go's type system.
+</p>
+<p>
+Regarding operator overloading, it seems more a convenience than an absolute
+requirement.  Again, things are simpler without it.
+</p>
+
+
+<h2 id="values">Values</h2>
+
+<h3 id="conversions">
+Why does Go not provide implicit numeric conversions?</h3>
+<p>
+The convenience of automatic conversion between numeric types in C is
+outweighed by the confusion it causes.  When is an expression unsigned?
+How big is the value?  Does it overflow?  Is the result portable, independent
+of the machine on which it executes?
+It also complicates the compiler; &ldquo;the usual arithmetic conversions&rdquo;
+are not easy to implement and inconsistent across architectures.
+For reasons of portability, we decided to make things clear and straightforward
+at the cost of some explicit conversions in the code.
+The definition of constants in Go&mdash;arbitrary precision values free
+of signedness and size annotations&mdash;ameliorates matters considerably,
+though.
+</p>
+<p>
+A related detail is that, unlike in C, <code>int</code> and <code>int64</code>
+are distinct types even if <code>int</code> is a 64-bit type.  The <code>int</code>
+type is generic; if you care about how many bits an integer holds, Go
+encourages you to be explicit.
+</p>
+
+<h3 id="builtin_maps">
+Why are maps built in?</h3>
+<p>
+The same reason strings are: they are such a powerful and important data
+structure that providing one excellent implementation with syntactic support
+makes programming more pleasant.  We believe that Go's implementation of maps
+is strong enough that it will serve for the vast majority of uses.
+If a specific application can benefit from a custom implementation, it's possible
+to write one but it will not be as convenient syntactically; this seems a reasonable tradeoff.
+</p>
+
+
+<h3 id="map_keys">
+Why don't maps allow structs and arrays as keys?</h3>
+<p>
+Map lookup requires an equality operator, which structs and arrays 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
+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.
+</p>
+
+<h3 id="references">
+Why are maps, slices, and channels references while arrays are values?</h3>
+<p>
+There's a lot of history on that topic.  Early on, maps and channels
+were syntactically pointers and it was impossible to declare or use a
+non-pointer instance.  Also, we struggled with how arrays should work.
+Eventually we decided that the strict separation of pointers and
+values made the language harder to use.  Introducing reference types,
+including slices to handle the reference form of arrays, resolved
+these issues.  Reference types add some regrettable complexity to the
+language but they have a large effect on usability: Go became a more
+productive, comfortable language when they were introduced.
+</p>
+
 
 <h2 id="Writing_Code">Writing Code</h2>
 
@@ -263,41 +613,278 @@ See the document
 <a href="contribute.html">Contributing to the Go project</a>
 for more information about how to proceed.
 
-<h3 id="Where_is_assert">
-Where is assert?</h3>
+
+<h2 id="Pointers">Pointers and Allocation</h2>
+
+<h3 id="pass_by_value">
+When are function parameters passed by value?</h3>
 
 <p>
-Go doesn't provide assertions. They are undeniably convenient, but our
-experience has been that programmers use them as a crutch to avoid thinking
-about proper error handling and reporting. Proper error handling means that
-servers continue operation after non-fatal errors instead of crashing.
-Proper error reporting means that errors are direct and to the point,
-saving the programmer from interpreting a large crash trace. Precise
-errors are particularly important when the programmer seeing the errors is
-not familiar with the code.
+Everything in Go is passed by value.  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. 
+</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.
+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
+value holds a struct, copying the interface value makes a copy of the
+struct.  If the interface value holds a pointer, copying the interface value
+makes a copy of the pointer, but again not the data it points to. 
+</p>
+
+<h3 id="methods_on_values_or_pointers">
+Should I define methods on values or pointers?</h3>
+
+<pre>
+func (s *MyStruct) someMethod() { } // method on pointer
+func (s MyStruct) someMethod() { }  // method on value
+</pre>
 
 <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.
+When defining a method on a type, the receiver (<code>s</code> in the above
+example) behaves exactly is if it were an argument to the method. Define the
+method on a pointer type if you need the method to modify the data the receiver
+points to. Otherwise, it is often cleaner to define the method on a value type.
+</p>
+
+<h3 id="new_and_make">
+What's the difference between new and make?</h3>
 
 <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
-because we feel it's sometimes worth trying a different approach.
+In short: <code>new</code> allocates memory, <code>make</code> initializes
+the slice, map, and channel types.
+</p>
+
+<p>
+See the <a href="/doc/effective_go.html#allocation_new">relevant section
+of Effective Go</a> for more details.
+</p>
+
+<h3 id="64bit_machine_32bit_int">
+Why is <code>int</code> 32 bits on 64 bit machines?</h3>
+
+<p>
+The size of <code>int</code> and <code>float</code> is implementation-specific.
+The 64 bit Go compilers (both 6g and gccgo) use a 32 bit representation for
+both <code>int</code> and <code>float</code>.  Code that relies on a particular
+size of value should use an explicitly sized type, like <code>int64</code> or
+<code>float64</code>.
+</p>
+
+<h2 id="Concurrency">Concurrency</h2>
+
+<h3 id="What_operations_are_atomic_What_about_mutexes">
+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>.
+</p>
+
+<p>
+Regarding mutexes, the <a href="/pkg/sync">sync</a>
+package implements them, but we hope Go programming style will
+encourage people to try higher-level techniques. In particular, consider
+structuring your program so that only one goroutine at a time is ever
+responsible for a particular piece of data.
+</p>
+
+<p>
+Do not communicate by sharing memory. Instead, share memory by communicating.
+</p>
+
+<h3 id="Why_no_multi_CPU">
+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
+runtime 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.  
+</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">runtime package
+documentation</a>.)
+</p>
+
+<h3 id="Why_GOMAXPROCS">
+Why does using <code>GOMAXPROCS</code> &gt; 1 sometimes make my program
+slower?</h3>
+
+<p>
+(This is specific to the gc compilers. See above.)
+</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.
+</p>
+
+<p>
+The Go runtime's scheduler is not as good as it needs to be. In future, it
+should recognise such cases and optimize its use of OS threads. For now,
+<code>GOMAXPROCS</code> should be set on a per-application basis.
+</p>
+
+
+<h2 id="Functions_methods">Functions and Methods</h2>
+
+<h3 id="different_method_sets">
+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>:
+</p>
+
+<blockquote>
+The method set of any other named type <code>T</code> consists of all methods
+with receiver type <code>T</code>. The method set of the corresponding pointer
+type <code>*T</code> is the set of all methods with receiver <code>*T</code> or
+<code>T</code> (that is, it also contains the method set of <code>T</code>).
+</blockquote>
+
+<p>
+If an interface value contains a pointer <code>*T</code>,
+a method call can obtain a value by dereferencing the pointer,
+but if an interface value contains a value <code>T</code>,
+there is no useful way for a method call to obtain a pointer.
+</p>
+
+<p>
+If not for this restriction, this code:
+</p>
+
+<pre>
+var buf bytes.Buffer
+io.Copy(buf, os.Stdin)
+</pre>
+
+<p>
+would copy standard input into a <i>copy</i> of <code>buf</code>,
+not into <code>buf</code> itself.
+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>
+
+<p>
+Some confusion may arise when using closures with concurrency.
+Consider the following program:
+</p>
+
+<pre>
+func main() {
+	done := make(chan bool)
+
+	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 i := 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. 
+</p>
+
+<p>
+To bind the value of <code>v</code> to each closure as they are launched, one
+could modify the inner loop to read:
+</p>
+
+<pre>
+	for _, v := range values {
+		go func(<b>u</b>) {
+			fmt.Println(<b>u</b>)
+			done &lt;- true
+		}(<b>v</b>)
+	}
+</pre>
+
+<p>
+In this example, the value of <code>v</code> is passed as an argument to the 
+anonymous function. That value is then accessible inside the function as
+the variable <code>u</code>.
+</p>
+
+<h2 id="Control_flow">Control flow</h2>
+
+<h3 id="Does_Go_have_a_ternary_form">
+Does Go have the <code>?:</code> operator?</h3>
+
+<p>
+There is no ternary form in Go. You may use the following to achieve the same
+result:
+</p>
+
+<pre>
+if expr {
+	n = trueVal
+} else {
+	n = falseVal
+}
+</pre>
+
+<h2 id="Packages_Testing">Packages and Testing</h2>
+
+<h3 id="How_do_I_create_a_multifile_package">
+How do I create a multifile package?</h3>
+
+<p>
+Put all the source files for the package in a directory by themselves.
+Source files can refer to items from different files at will; there is
+no need for forward declarations or a header file.
+</p>
+
+<p>
+Other than being split into multiple files, the package will compile and test
+just like a single-file package.
+</p>
+
+<h3 id="How_do_I_write_a_unit_test">
+How do I write a unit test?</h3>
+
+<p>
+Create a new file ending in <code>_test.go</code> in the same directory
+as your package sources. Inside that file, <code>import "testing"</code>
+and write functions of the form
+</p>
+
+<pre>
+func TestFoo(t *testing.T) {
+    ...
+}
+</pre>
+
+<p>
+Run <code>gotest</code> in that directory.
+That script finds the <code>Test</code> functions,
+builds a test binary, and runs it.
+</p>
+
 
 <h2 id="Implementation">Implementation</h2>
 
@@ -372,3 +959,139 @@ isn't fast enough yet (even if it were, taking care not to generate unnecessary
 garbage can have a huge effect).
 </p>
 
+
+<h2 id="change_from_c">Changes from C</h2>
+
+<h3 id="different_syntax">
+Why is the syntax so different from C?</h3>
+<p>
+Other than declaration syntax, the differences are not major and stem
+from two desires.  First, the syntax should feel light, without too
+many mandatory keywords, repetition, or arcana.  Second, the language
+has been designed to be easy to analyze
+and can be parsed without a symbol table.  This makes it much easier
+to build tools such as debuggers, dependency analyzers, automated
+documentation extractors, IDE plug-ins, and so on.  C and its
+descendants are notoriously difficult in this regard.
+</p>
+
+<h3 id="declarations_backwards">
+Why are declarations backwards?</h3>
+<p>
+They're only backwards if you're used to C. In C, the notion is that a
+variable is declared like an expression denoting its type, which is a
+nice idea, but the type and expression grammars don't mix very well and
+the results can be confusing; consider function pointers.  Go mostly
+separates expression and type syntax and that simplifies things (using
+prefix <code>*</code> for pointers is an exception that proves the rule).  In C,
+the declaration
+</p>
+<pre>
+	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;
+</pre>
+<p>
+declares both to be pointers.  This is clearer and more regular.
+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;
+</pre>
+has the same effect as
+<pre>
+	a := uint64(1);
+</pre>
+<p>
+Parsing is also simplified by having a distinct grammar for types that
+is not just the expression grammar; keywords such as <code>func</code>
+and <code>chan</code> keep things clear.
+</p>
+
+<h3 id="no_pointer_arithmetic">
+Why is there no pointer arithmetic?</h3>
+<p>
+Safety.  Without pointer arithmetic it's possible to create a
+language that can never derive an illegal address that succeeds
+incorrectly.  Compiler and hardware technology have advanced to the
+point where a loop using array indices can be as efficient as a loop
+using pointer arithmetic.  Also, the lack of pointer arithmetic can
+simplify the implementation of the garbage collector.
+</p>
+
+<h3 id="inc_dec">
+Why are <code>++</code> and <code>--</code> statements and not expressions?  And why postfix, not prefix?</h3>
+<p>
+Without pointer arithmetic, the convenience value of pre- and postfix
+increment operators drops.  By removing them from the expression
+hierarchy altogether, expression syntax is simplified and the messy
+issues around order of evaluation of <code>++</code> and <code>--</code>
+(consider <code>f(i++)</code> and <code>p[i] = q[++i]</code>)
+are eliminated as well.  The simplification is
+significant.  As for postfix vs. prefix, either would work fine but
+the postfix version is more traditional; insistence on prefix arose
+with the STL, a library for a language whose name contains, ironically, a
+postfix increment.
+</p>
+
+<h3 id="semicolons">
+Why are there braces but no semicolons? And why can't I put the opening
+brace on the next line?</h3>
+<p>
+Go uses brace brackets for statement grouping, a syntax familiar to
+programmers who have worked with any language in the C family.
+Semicolons, however, are for parsers, not for people, and we wanted to
+eliminate them as much as possible.  To achieve this goal, Go borrows
+a trick from BCPL: the semicolons that separate statements are in the
+formal grammar but are injected automatically, without lookahead, by
+the lexer at the end of any line that could be the end of a statement.
+This works very well in practice but has the effect that it forces a
+brace style.  For instance, the opening brace of a function cannot
+appear on a line by itself.
+</p>
+<p>
+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>,
+<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
+important&mdash;much more important&mdash;the advantages of a single,
+programmatically mandated format for all Go programs greatly outweigh
+any perceived disadvantages of the particular style.
+Note too that Go's style means that an interactive implementation of
+Go can use the standard syntax one line at a time without special rules.
+</p>
+
+<h3 id="garbage_collection">
+Why do garbage collection?  Won't it be too expensive?</h3>
+<p>
+One of the biggest sources of bookkeeping in systems programs is
+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.)
+</p>
+<p>
+Another point is that a large part of the difficulty of concurrent
+and multi-threaded programming is memory management;
+as objects get passed among threads it becomes cumbersome
+to guarantee they become freed safely.
+Automatic garbage collection makes concurrent code far easier to write.
+Of course, implementing garbage collection in a concurrent environment is
+itself a challenge, but meeting it once rather than in every
+program helps everyone.
+</p>
+<p>
+Finally, concurrency aside, garbage collection makes interfaces
+simpler because they don't need to specify how memory is managed across them.
+</p>
+
diff --git a/doc/go_lang_faq.html b/doc/go_lang_faq.html
deleted file mode 100644
index 0eec50b005..0000000000
--- a/doc/go_lang_faq.html
+++ /dev/null
@@ -1,495 +0,0 @@
-<!-- Language Design FAQ -->
-
-<div class="detail">
-<p>Is your question not answered here? Try the <a href="go_programming_faq.html">Programming FAQ</a> or the <a href="go_faq.html">Go FAQ</a>.</p>
-</div>
-
-<h2 id="origins">Origins</h2>
-
-<h3 id="history">
-What is the history of the project?</h3>
-<p>
-Robert Griesemer, Rob Pike and Ken Thompson started sketching the
-goals for a new language on the white board on September 21, 2007.
-Within a few days the goals had settled into a plan to do something
-and a fair idea of what it would be.  Design continued part-time in
-parallel with unrelated work.  By January 2008, Ken had started work
-on a compiler with which to explore ideas; it generated C code as its
-output.  By mid-year the language had become a full-time project and
-had settled enough to attempt a production compiler.  In May 2008,
-Ian Taylor independently started on a GCC front end for Go using the
-draft specification.  Russ Cox joined in late 2008 and helped move the language
-and libraries from prototype to reality.
-</p>
-
-<p>
-Many others have contributed ideas, discussions, and code.
-</p>
-
-<h3 id="creating_a_new_language">
-Why are you creating a new language?</h3>
-<p>
-Go was born out of frustration with existing languages and
-environments for systems programming.  Programming had become too
-difficult and the choice of languages was partly to blame.  One had to
-choose either efficient compilation, efficient execution, or ease of
-programming; all three were not available in the same mainstream
-language.  Programmers who could were choosing ease over
-safety and efficiency by moving to dynamically typed languages such as
-Python and JavaScript rather than C++ or, to a lesser extent, Java.
-</p>
-<p>
-Go is an attempt to combine the ease of programming of an interpreted,
-dynamically typed
-language with the efficiency and safety of a statically typed, compiled language.
-It also aims to be modern, with support for networked and multicore
-computing.  Finally, it is intended to be <i>fast</i>: it should take
-at most a few seconds to build a large executable on a single computer.
-To meet these goals required addressing a number of
-linguistic issues: an expressive but lightweight type system;
-concurrency and garbage collection; rigid dependency specification;
-and so on.  These cannot be addressed well by libraries or tools; a new
-language was called for.
-</p>
-
-
-<h3 id="ancestors">
-What are Go's ancestors?</h3>
-<p>
-Go is mostly in the C family (basic syntax),
-with significant input from the Pascal/Modula/Oberon
-family (declarations, packages),
-plus some ideas from languages
-inspired by Tony Hoare's CSP,
-such as Newsqueak and Limbo (concurrency).
-However, it is a new language across the board.
-In every respect the language was designed by thinking
-about what programmers do and how to make programming, at least the
-kind of programming we do, more effective, which means more fun.
-</p>
-
-<h3 id="principles">
-What are the guiding principles in the design?</h3>
-<p>
-Programming today involves too much bookkeeping, repetition, and
-clerical work.  As Dick Gabriel says, &ldquo;Old programs read
-like quiet conversations between a well-spoken research worker and a
-well-studied mechanical colleague, not as a debate with a compiler.
-Who'd have guessed sophistication bought such noise?&rdquo;
-The sophistication is worthwhile&mdash;no one wants to go back to
-the old languages&mdash;but can it be more quietly achieved?
-</p>
-<p>
-Go attempts to reduce the amount of typing in both senses of the word.
-Throughout its design, we have tried to reduce clutter and
-complexity.  There are no forward declarations and no header files;
-everything is declared exactly once.  Initialization is expressive,
-automatic, and easy to use.  Syntax is clean and light on keywords.
-Stuttering (<code>foo.Foo* myFoo = new(foo.Foo)</code>) is reduced by
-simple type derivation using the <code>:=</code>
-declare-and-initialize construct.  And perhaps most radically, there
-is no type hierarchy: types just <i>are</i>, they don't have to
-announce their relationships.  These simplifications allow Go to be
-expressive yet comprehensible without sacrificing, well, sophistication.
-</p>
-<p>
-Another important principle is to keep the concepts orthogonal.
-Methods can be implemented for any type; structures represent data while
-interfaces represent abstraction; and so on.  Orthogonality makes it
-easier to understand what happens when things combine.
-</p>
-
-
-<h2 id="change_from_c">Changes from C</h2>
-
-<h3 id="different_syntax">
-Why is the syntax so different from C?</h3>
-<p>
-Other than declaration syntax, the differences are not major and stem
-from two desires.  First, the syntax should feel light, without too
-many mandatory keywords, repetition, or arcana.  Second, the language
-has been designed to be easy to analyze
-and can be parsed without a symbol table.  This makes it much easier
-to build tools such as debuggers, dependency analyzers, automated
-documentation extractors, IDE plug-ins, and so on.  C and its
-descendants are notoriously difficult in this regard.
-</p>
-
-<h3 id="declarations_backwards">
-Why are declarations backwards?</h3>
-<p>
-They're only backwards if you're used to C. In C, the notion is that a
-variable is declared like an expression denoting its type, which is a
-nice idea, but the type and expression grammars don't mix very well and
-the results can be confusing; consider function pointers.  Go mostly
-separates expression and type syntax and that simplifies things (using
-prefix <code>*</code> for pointers is an exception that proves the rule).  In C,
-the declaration
-</p>
-<pre>
-	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;
-</pre>
-<p>
-declares both to be pointers.  This is clearer and more regular.
-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;
-</pre>
-has the same effect as
-<pre>
-	a := uint64(1);
-</pre>
-<p>
-Parsing is also simplified by having a distinct grammar for types that
-is not just the expression grammar; keywords such as <code>func</code>
-and <code>chan</code> keep things clear.
-</p>
-
-<h3 id="no_pointer_arithmetic">
-Why is there no pointer arithmetic?</h3>
-<p>
-Safety.  Without pointer arithmetic it's possible to create a
-language that can never derive an illegal address that succeeds
-incorrectly.  Compiler and hardware technology have advanced to the
-point where a loop using array indices can be as efficient as a loop
-using pointer arithmetic.  Also, the lack of pointer arithmetic can
-simplify the implementation of the garbage collector.
-</p>
-
-<h3 id="inc_dec">
-Why are <code>++</code> and <code>--</code> statements and not expressions?  And why postfix, not prefix?</h3>
-<p>
-Without pointer arithmetic, the convenience value of pre- and postfix
-increment operators drops.  By removing them from the expression
-hierarchy altogether, expression syntax is simplified and the messy
-issues around order of evaluation of <code>++</code> and <code>--</code>
-(consider <code>f(i++)</code> and <code>p[i] = q[++i]</code>)
-are eliminated as well.  The simplification is
-significant.  As for postfix vs. prefix, either would work fine but
-the postfix version is more traditional; insistence on prefix arose
-with the STL, a library for a language whose name contains, ironically, a
-postfix increment.
-</p>
-
-<h3 id="semicolons">
-Why are there braces but no semicolons? And why can't I put the opening
-brace on the next line?</h3>
-<p>
-Go uses brace brackets for statement grouping, a syntax familiar to
-programmers who have worked with any language in the C family.
-Semicolons, however, are for parsers, not for people, and we wanted to
-eliminate them as much as possible.  To achieve this goal, Go borrows
-a trick from BCPL: the semicolons that separate statements are in the
-formal grammar but are injected automatically, without lookahead, by
-the lexer at the end of any line that could be the end of a statement.
-This works very well in practice but has the effect that it forces a
-brace style.  For instance, the opening brace of a function cannot
-appear on a line by itself.
-</p>
-<p>
-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>,
-<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
-important&mdash;much more important&mdash;the advantages of a single,
-programmatically mandated format for all Go programs greatly outweigh
-any perceived disadvantages of the particular style.
-Note too that Go's style means that an interactive implementation of
-Go can use the standard syntax one line at a time without special rules.
-</p>
-
-<h3 id="garbage_collection">
-Why do garbage collection?  Won't it be too expensive?</h3>
-<p>
-One of the biggest sources of bookkeeping in systems programs is
-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.)
-</p>
-<p>
-Another point is that a large part of the difficulty of concurrent
-and multi-threaded programming is memory management;
-as objects get passed among threads it becomes cumbersome
-to guarantee they become freed safely.
-Automatic garbage collection makes concurrent code far easier to write.
-Of course, implementing garbage collection in a concurrent environment is
-itself a challenge, but meeting it once rather than in every
-program helps everyone.
-</p>
-<p>
-Finally, concurrency aside, garbage collection makes interfaces
-simpler because they don't need to specify how memory is managed across them.
-</p>
-
-<h2 id="unicode_identifiers">What's up with Unicode identifiers?</h2>
-
-<p>
-It was important to us to extend the space of identifiers from the
-confines of ASCII.  Go's rule&mdash;identifier characters must be
-letters or digits as defined by Unicode&mdash;is simple to understand
-and to implement but has restrictions.  Combining characters are
-excluded by design, for instance.
-Until there
-is an agreed external definition of what an identifier might be,
-plus a definition of canonicalization of identifiers that guarantees
-no ambiguity, it seemed better to keep combining characters out of
-the mix.  Thus we have a simple rule that can be expanded later
-without breaking programs, one that avoids bugs that would surely arise
-from a rule that admits ambiguous identifiers.
-</p>
-
-<p>
-On a related note, since an exported identifier must begin with an
-upper-case letter, identifiers created from &ldquo;letters&rdquo;
-in some languages can, by definition, not be exported.  For now the
-only solution is to use something like <code>X日本語</code>, which
-is clearly unsatisfactory; we are considering other options.  The
-case-for-visibility rule is unlikely to change however; it's one
-of our favorite features of Go.
-</p>
-
-<h2 id="absent_features">Absent features</h2>
-
-<h3 id="generics">
-Why does Go not have generic types?</h3>
-<p>
-Generics may well be added at some point.  We don't feel an urgency for
-them, although we understand some programmers do.
-</p>
-<p>
-Generics are convenient but they come at a cost in
-complexity in the type system and run-time.  We haven't yet found a
-design that gives value proportionate to the complexity, although we
-continue to think about it.  Meanwhile, Go's built-in maps and slices,
-plus the ability to use the empty interface to construct containers
-(with explicit unboxing) mean in many cases it is possible to write
-code that does what generics would enable, if less smoothly.
-</p>
-<p>
-This remains an open issue.
-</p>
-
-<h3 id="exceptions">
-Why does Go not have exceptions?</h3>
-<p>
-We believe that coupling exceptions to a control
-structure, as in the <code>try-catch-finally</code> idiom, results in
-convoluted code.  It also tends to encourage programmers to label
-too many ordinary errors, such as failing to open a file, as
-exceptional.
-</p>
-<p>
-Go takes a different approach.  Instead of exceptions, it has a couple
-of built-in functions to signal and recover from truly exceptional
-conditions.  The recovery mechanism is executed only as part of a
-function's state being torn down after an error, which is sufficient
-to handle catastrophe but requires no extra control structures and,
-when used well, can result in clean error-handling code.
-</p>
-
-<h3 id="assertions">
-Why does Go not have assertions?</h3>
-<p>
-This is answered in the general <a href="go_faq.html#Where_is_assert">FAQ</a>.
-</p>
-
-<h2 id="types">Types</h2>
-
-<h3 id="inheritance">
-Why is there no type inheritance?</h3>
-<p>
-Object-oriented programming, at least in the best-known languages,
-involves too much discussion of the relationships between types,
-relationships that often could be derived automatically.  Go takes a
-different approach.
-</p>
-<p>
-Rather than requiring the programmer to declare ahead of time that two
-types are related, in Go a type automatically satisfies any interface
-that specifies a subset of its methods.  Besides reducing the
-bookkeeping, this approach has real advantages.  Types can satisfy
-many interfaces at once, without the complexities of traditional
-multiple inheritance.
-Interfaces can be very lightweight&mdash;having one or even zero methods
-in an interface can express useful concepts.
-Interfaces can be added after the fact if a new idea comes along
-or for testing&mdash;without annotating the original types.
-Because there are no explicit relationships between types
-and interfaces, there is no type hierarchy to manage or discuss.
-</p>
-<p>
-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
-(<code>io.Writer</code>) representing a single method
-(<code>Write</code>).  And that's only scratching the surface.
-</p>
-<p>
-It takes some getting used to but this implicit style of type
-dependency is one of the most exciting things about Go.
-</p>
-
-<h3 id="methods_on_basics">
-Why is <code>len</code> a function and not a method?</h3>
-<p>
-We debated this issue but decided
-implementing <code>len</code> and friends as functions was fine in practice and
-didn't complicate questions about the interface (in the Go type sense)
-of basic types.
-</p>
-
-<h3 id="overloading">
-Why does Go not support overloading of methods and operators?</h3>
-<p>
-Method dispatch is simplified if it doesn't need to do type matching as well.
-Experience with other languages told us that having a variety of
-methods with the same name but different signatures was occasionally useful
-but that it could also be confusing and fragile in practice.  Matching only by name
-and requiring consistency in the types was a major simplifying decision
-in Go's type system.
-</p>
-<p>
-Regarding operator overloading, it seems more a convenience than an absolute
-requirement.  Again, things are simpler without it.
-</p>
-
-<h2 id="values">Values</h2>
-
-<h3 id="conversions">
-Why does Go not provide implicit numeric conversions?</h3>
-<p>
-The convenience of automatic conversion between numeric types in C is
-outweighed by the confusion it causes.  When is an expression unsigned?
-How big is the value?  Does it overflow?  Is the result portable, independent
-of the machine on which it executes?
-It also complicates the compiler; &ldquo;the usual arithmetic conversions&rdquo;
-are not easy to implement and inconsistent across architectures.
-For reasons of portability, we decided to make things clear and straightforward
-at the cost of some explicit conversions in the code.
-The definition of constants in Go&mdash;arbitrary precision values free
-of signedness and size annotations&mdash;ameliorates matters considerably,
-though.
-</p>
-<p>
-A related detail is that, unlike in C, <code>int</code> and <code>int64</code>
-are distinct types even if <code>int</code> is a 64-bit type.  The <code>int</code>
-type is generic; if you care about how many bits an integer holds, Go
-encourages you to be explicit.
-</p>
-
-<h3 id="builtin_maps">
-Why are maps built in?</h3>
-<p>
-The same reason strings are: they are such a powerful and important data
-structure that providing one excellent implementation with syntactic support
-makes programming more pleasant.  We believe that Go's implementation of maps
-is strong enough that it will serve for the vast majority of uses.
-If a specific application can benefit from a custom implementation, it's possible
-to write one but it will not be as convenient syntactically; this seems a reasonable tradeoff.
-</p>
-
-
-<h3 id="map_keys">
-Why don't maps allow structs and arrays as keys?</h3>
-<p>
-Map lookup requires an equality operator, which structs and arrays 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
-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.
-</p>
-
-<h3 id="references">
-Why are maps, slices, and channels references while arrays are values?</h3>
-<p>
-There's a lot of history on that topic.  Early on, maps and channels
-were syntactically pointers and it was impossible to declare or use a
-non-pointer instance.  Also, we struggled with how arrays should work.
-Eventually we decided that the strict separation of pointers and
-values made the language harder to use.  Introducing reference types,
-including slices to handle the reference form of arrays, resolved
-these issues.  Reference types add some regrettable complexity to the
-language but they have a large effect on usability: Go became a more
-productive, comfortable language when they were introduced.
-</p>
-
-<h2 id="concurrency">Concurrency</h2>
-
-<h3 id="csp">
-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
-designs such as pthreads and partly to overemphasis on low-level details
-such as mutexes, condition variables, and even memory barriers.
-Higher-level interfaces enable much simpler code, even if there are still
-mutexes and such under the covers.
-</p>
-<p>
-One of the most successful models for providing high-level linguistic support
-for concurrency comes from Hoare's Communicating Sequential Processes, or CSP.
-Occam and Erlang are two well known languages that stem from CSP.
-Go's concurrency primitives derive from a different part of the family tree
-whose main contribution is the powerful notion of channels as first class objects.
-</p>
-
-<h3 id="goroutines">
-Why goroutines instead of threads?</h3>
-<p>
-Goroutines are part of making concurrency easy to use.  The idea, which has
-been around for a while, is to multiplex independently executing
-functions&mdash;coroutines, really&mdash;onto a set of threads.
-When a coroutine blocks, such as by calling a blocking system call,
-the run-time automatically moves other coroutines on the same operating
-system thread to a different, runnable thread so they won't be blocked.
-The programmer sees none of this, which is the point.
-The result, which we call goroutines, can be very cheap: unless they spend a lot of time
-in long-running system calls, they cost little more than the memory
-for the stack.
-</p>
-<p>
-To make the stacks small, Go's run-time uses segmented stacks.  A newly
-minted goroutine is given a few kilobytes, which is almost always enough.
-When it isn't, the run-time allocates (and frees) extension segments automatically.
-The overhead averages about three cheap instructions per function call.
-It is practical to create hundreds of thousands of goroutines in the same
-address space.  If goroutines were just threads, system resources would
-run out at a much smaller number.
-</p>
-
-<h3 id="atomic_maps">
-Why are map operations not defined to be atomic?</h3>
-
-<p>
-After long discussion it was decided that the typical use of maps did not require
-safe access from multiple threads, and in those cases where it did, the map was
-probably part of some larger data structure or computation that was already
-synchronized.  Therefore requiring that all map operations grab a mutex would slow
-down most programs and add safety to few.  This was not an easy decision,
-however, since it means uncontrolled map access can crash the program.
-</p>
-
-<p>
-The language does not preclude atomic map updates.  When required, such
-as when hosting an untrusted program, the implementation could interlock
-map access.
-</p>
diff --git a/doc/go_programming_faq.html b/doc/go_programming_faq.html
deleted file mode 100644
index 736578ab5c..0000000000
--- a/doc/go_programming_faq.html
+++ /dev/null
@@ -1,311 +0,0 @@
-<!-- Programming FAQ -->
-
-<div class="detail">
-<p>Is your question not answered here? Try the <a href="go_faq.html">Go FAQ</a> or the <a href="go_lang_faq.html">Language Design FAQ</a>.</p>
-</div>
-
-<h2 id="Pointers">Pointers and Allocation</h2>
-
-<h3 id="pass_by_value">
-When are function parameters passed by value?</h3>
-
-<p>
-Everything in Go is passed by value.  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. 
-</p>
-
-<p>
-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
-value holds a struct, copying the interface value makes a copy of the
-struct.  If the interface value holds a pointer, copying the interface value
-makes a copy of the pointer, but again not the data it points to. 
-</p>
-
-<h3 id="methods_on_values_or_pointers">
-Should I define methods on values or pointers?</h3>
-
-<pre>
-func (s *MyStruct) someMethod() { } // method on pointer
-func (s MyStruct) someMethod() { }  // method on value
-</pre>
-
-<p>
-When defining a method on a type, the receiver (<code>s</code> in the above
-example) behaves exactly is if it were an argument to the method. Define the
-method on a pointer type if you need the method to modify the data the receiver
-points to. Otherwise, it is often cleaner to define the method on a value type.
-</p>
-
-<h3 id="new_and_make">
-What's the difference between new and make?</h3>
-
-<p>
-In short: <code>new</code> allocates memory, <code>make</code> initializes
-the slice, map, and channel types.
-</p>
-
-<p>
-See the <a href="/doc/effective_go.html#allocation_new">relevant section
-of Effective Go</a> for more details.
-</p>
-
-<h3 id="64bit_machine_32bit_int">
-Why is <code>int</code> 32 bits on 64 bit machines?</h3>
-
-<p>
-The size of <code>int</code> and <code>float</code> is implementation-specific.
-The 64 bit Go compilers (both 6g and gccgo) use a 32 bit representation for
-both <code>int</code> and <code>float</code>.  Code that relies on a particular
-size of value should use an explicitly sized type, like <code>int64</code> or
-<code>float64</code>.
-</p>
-
-<h2 id="Concurrent_programming">Concurrent programming</h2>
-
-<h3 id="What_operations_are_atomic_What_about_mutexes">
-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>.
-Also, some concurrency questions are answered in more detail in the <a
-href="go_lang_faq.html">language design FAQ</a>.
-</p>
-
-<p>
-Regarding mutexes, the <a href="/pkg/sync">sync</a>
-package implements them, but we hope Go programming style will
-encourage people to try higher-level techniques. In particular, consider
-structuring your program so that only one goroutine at a time is ever
-responsible for a particular piece of data.
-</p>
-
-<p>
-Do not communicate by sharing memory. Instead, share memory by communicating.
-</p>
-
-<h3 id="Why_no_multi_CPU">
-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
-runtime 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.  
-</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">runtime package
-documentation</a>.)
-</p>
-
-<h3 id="Why_GOMAXPROCS">
-Why does using <code>GOMAXPROCS</code> &gt; 1 sometimes make my program
-slower?</h3>
-
-<p>
-(This is specific to the gc compilers. See above.)
-</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.
-</p>
-
-<p>
-The Go runtime's scheduler is not as good as it needs to be. In future, it
-should recognise such cases and optimize its use of OS threads. For now,
-<code>GOMAXPROCS</code> should be set on a per-application basis.
-</p>
-
-
-<h2 id="Functions_methods">Functions and Methods</h2>
-
-<h3 id="different_method_sets">
-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>:
-</p>
-
-<blockquote>
-The method set of any other named type <code>T</code> consists of all methods
-with receiver type <code>T</code>. The method set of the corresponding pointer
-type <code>*T</code> is the set of all methods with receiver <code>*T</code> or
-<code>T</code> (that is, it also contains the method set of <code>T</code>).
-</blockquote>
-
-<p>
-If an interface value contains a pointer <code>*T</code>,
-a method call can obtain a value by dereferencing the pointer,
-but if an interface value contains a value <code>T</code>,
-there is no useful way for a method call to obtain a pointer.
-</p>
-
-<p>
-If not for this restriction, this code:
-</p>
-
-<pre>
-var buf bytes.Buffer
-io.Copy(buf, os.Stdin)
-</pre>
-
-<p>
-would copy standard input into a <i>copy</i> of <code>buf</code>,
-not into <code>buf</code> itself.
-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>
-
-<p>
-Some confusion may arise when using closures with concurrency.
-Consider the following program:
-</p>
-
-<pre>
-func main() {
-	done := make(chan bool)
-
-	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 i := 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. 
-</p>
-
-<p>
-To bind the value of <code>v</code> to each closure as they are launched, one
-could modify the inner loop to read:
-</p>
-
-<pre>
-	for _, v := range values {
-		go func(<b>u</b>) {
-			fmt.Println(<b>u</b>)
-			done &lt;- true
-		}(<b>v</b>)
-	}
-</pre>
-
-<p>
-In this example, the value of <code>v</code> is passed as an argument to the 
-anonymous function. That value is then accessible inside the function as
-the variable <code>u</code>.
-</p>
-
-<h2 id="Control_flow">Control flow</h2>
-
-<h3 id="Does_Go_have_a_ternary_form">
-Does Go have the <code>?:</code> operator?</h3>
-
-<p>
-There is no ternary form in Go. You may use the following to achieve the same
-result:
-</p>
-
-<pre>
-if expr {
-	n = trueVal
-} else {
-	n = falseVal
-}
-</pre>
-
-<h2 id="Packages_Testing">Packages and Testing</h2>
-
-<h3 id="How_do_I_create_a_multifile_package">
-How do I create a multifile package?</h3>
-
-<p>
-Put all the source files for the package in a directory by themselves.
-Source files can refer to items from different files at will; there is
-no need for forward declarations or a header file.
-</p>
-
-<p>
-Other than being split into multiple files, the package will compile and test
-just like a single-file package.
-</p>
-
-<h3 id="How_do_I_write_a_unit_test">
-How do I write a unit test?</h3>
-
-<p>
-Create a new file ending in <code>_test.go</code> in the same directory
-as your package sources. Inside that file, <code>import "testing"</code>
-and write functions of the form
-</p>
-
-<pre>
-func TestFoo(t *testing.T) {
-    ...
-}
-</pre>
-
-<p>
-Run <code>gotest</code> in that directory.
-That script finds the <code>Test</code> functions,
-builds a test binary, and runs it.
-</p>
-
-
-<h2 id="Data_structures">Data Structures</h2>
-
-<h3 id="nested_array_verbose"
->Why does the syntax for nested array literals seem overly verbose?</h3>
-
-<p>
-In Go, you must specify a 2-dimensional array literal like this:
-</p>
-
-<pre>
-var intArray = [4][4]int{
-	[4]int{1, 2, 3, 4},
-	[4]int{2, 4, 8, 16},
-	[4]int{3, 9, 27, 81},
-	[4]int{4, 16, 64, 256},
-}
-</pre>
-
-<p>
-It seems that the <code>[4]int</code> could be inferred, but in general it's
-hard to get this sort of thing right.
-</p>
-
-<p>
-Some of Go's designers had worked on other languages that derived types
-automatically in such expressions, but the special cases that arise can
-be messy, especially when interfaces, nil, constant conversions, and
-such are involved. It seemed better to require the full type
-information. That way there will be no surprises.
-</p>
-