Imported Upstream version 2012.03.22upstream-weekly/2012.03.22

1 files changed, 84 insertions, 158 deletions

diff --git a/doc/go1.html b/doc/go1.html
index 8b67cd3aa..dcc3300d3 100644
--- a/doc/go1.html
+++ b/doc/go1.html
@@ -1,11 +1,7 @@
 <!--{
-	"Title": "Go 1 Release Notes"
+	"Title": "Go 1 Release Notes",
+	"Template": true
 }-->
-<!--
-  DO NOT EDIT: created by
-    tmpltohtml go1.tmpl
--->
-
 
 <h2 id="introduction">Introduction to Go 1</h2>
 
@@ -64,9 +60,7 @@ However, <code>append</code> did not provide a way to append a string to a <code
 which is another common case.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/greeting := ..byte/` `/append.*hello/`}}
--->    greeting := []byte{}
-    greeting = append(greeting, []byte(&#34;hello &#34;)...)</pre>
+{{code "/doc/progs/go1.go" `/greeting := ..byte/` `/append.*hello/`}}
 
 <p>
 By analogy with the similar property of <code>copy</code>, Go 1
@@ -75,8 +69,7 @@ slice, reducing the friction between strings and byte slices.
 The conversion is no longer necessary:
 </p>
 
-<pre><!--{{code "progs/go1.go" `/append.*world/`}}
--->    greeting = append(greeting, &#34;world&#34;...)</pre>
+{{code "/doc/progs/go1.go" `/append.*world/`}}
 
 <p>
 <em>Updating</em>:
@@ -126,35 +119,7 @@ type specification for the elements' initializers if they are of pointer type.
 All four of the initializations in this example are legal; the last one was illegal before Go 1.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/type Date struct/` `/STOP/`}}
--->    type Date struct {
-        month string
-        day   int
-    }
-    // Struct values, fully qualified; always legal.
-    holiday1 := []Date{
-        Date{&#34;Feb&#34;, 14},
-        Date{&#34;Nov&#34;, 11},
-        Date{&#34;Dec&#34;, 25},
-    }
-    // Struct values, type name elided; always legal.
-    holiday2 := []Date{
-        {&#34;Feb&#34;, 14},
-        {&#34;Nov&#34;, 11},
-        {&#34;Dec&#34;, 25},
-    }
-    // Pointers, fully qualified, always legal.
-    holiday3 := []*Date{
-        &amp;Date{&#34;Feb&#34;, 14},
-        &amp;Date{&#34;Nov&#34;, 11},
-        &amp;Date{&#34;Dec&#34;, 25},
-    }
-    // Pointers, type name elided; legal in Go 1.
-    holiday4 := []*Date{
-        {&#34;Feb&#34;, 14},
-        {&#34;Nov&#34;, 11},
-        {&#34;Dec&#34;, 25},
-    }</pre>
+{{code "/doc/progs/go1.go" `/type Date struct/` `/STOP/`}}
 
 <p>
 <em>Updating</em>:
@@ -183,14 +148,7 @@ In Go 1, code that uses goroutines can be called from
 without introducing a deadlock.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/PackageGlobal/` `/^}/`}}
--->var PackageGlobal int
-
-func init() {
-    c := make(chan int)
-    go initializationFunction(c)
-    PackageGlobal = &lt;-c
-}</pre>
+{{code "/doc/progs/go1.go" `/PackageGlobal/` `/^}/`}}
 
 <p>
 <em>Updating</em>:
@@ -231,14 +189,7 @@ when appropriate. For instance, the functions <code>unicode.ToLower</code> and
 relatives now take and return a <code>rune</code>.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/STARTRUNE/` `/ENDRUNE/`}}
--->    delta := &#39;δ&#39; // delta has type rune.
-    var DELTA rune
-    DELTA = unicode.ToUpper(delta)
-    epsilon := unicode.ToLower(DELTA + 1)
-    if epsilon != &#39;δ&#39;+1 {
-        log.Fatal(&#34;inconsistent casing for Greek&#34;)
-    }</pre>
+{{code "/doc/progs/go1.go" `/STARTRUNE/` `/ENDRUNE/`}}
 
 <p>
 <em>Updating</em>:
@@ -287,8 +238,7 @@ In Go 1, that syntax has gone; instead there is a new built-in
 function, <code>delete</code>.  The call
 </p>
 
-<pre><!--{{code "progs/go1.go" `/delete\(m, k\)/`}}
--->    delete(m, k)</pre>
+{{code "/doc/progs/go1.go" `/delete\(m, k\)/`}}
 
 <p>
 will delete the map entry retrieved by the expression <code>m[k]</code>.
@@ -327,12 +277,7 @@ This change means that code that depends on iteration order is very likely to br
 Just as important, it allows the map implementation to ensure better map balancing even when programs are using range loops to select an element from a map.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/Sunday/` `/^	}/`}}
--->    m := map[string]int{&#34;Sunday&#34;: 0, &#34;Monday&#34;: 1}
-    for name, value := range m {
-        // This loop should not assume Sunday will be visited first.
-        f(name, value)
-    }</pre>
+{{code "/doc/progs/go1.go" `/Sunday/` `/^	}/`}}
 
 <p>
 <em>Updating</em>:
@@ -367,17 +312,7 @@ proceed in left-to-right order.
 These examples illustrate the behavior.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/sa :=/` `/then sc.0. = 2/`}}
--->    sa := []int{1, 2, 3}
-    i := 0
-    i, sa[i] = 1, 2 // sets i = 1, sa[0] = 2
-
-    sb := []int{1, 2, 3}
-    j := 0
-    sb[j], j = 2, 1 // sets sb[0] = 2, j = 1
-
-    sc := []int{1, 2, 3}
-    sc[0], sc[0] = 1, 2 // sets sc[0] = 1, then sc[0] = 2 (so sc[0] = 2 at end)</pre>
+{{code "/doc/progs/go1.go" `/sa :=/` `/then sc.0. = 2/`}}
 
 <p>
 <em>Updating</em>:
@@ -504,18 +439,7 @@ provided they are composed from elements for which equality is also defined,
 using element-wise comparison.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/type Day struct/` `/Printf/`}}
--->    type Day struct {
-        long  string
-        short string
-    }
-    Christmas := Day{&#34;Christmas&#34;, &#34;XMas&#34;}
-    Thanksgiving := Day{&#34;Thanksgiving&#34;, &#34;Turkey&#34;}
-    holiday := map[Day]bool{
-        Christmas:    true,
-        Thanksgiving: true,
-    }
-    fmt.Printf(&#34;Christmas is a holiday: %t\n&#34;, holiday[Christmas])</pre>
+{{code "/doc/progs/go1.go" `/type Day struct/` `/Printf/`}}
 
 <p>
 Second, Go 1 removes the definition of equality for function values,
@@ -734,7 +658,7 @@ Code that uses the other packages (there should be almost zero) will need to be
 <h3 id="subrepo">Packages moving to subrepositories</h3>
 
 <p>
-Go 1 has moved a number of packages into sub-repositories of
+Go 1 has moved a number of packages into other repositories, usually sub-repositories of
 <a href="http://code.google.com/p/go/">the main Go repository</a>.
 This table lists the old and new import paths:
 
@@ -779,6 +703,10 @@ This table lists the old and new import paths:
 </tr>
 <tr><td>encoding/git85</td> <td>code.google.com/p/go.codereview/git85</tr>
 <tr><td>patch</td> <td>code.google.com/p/go.codereview/patch</tr>
+<tr>
+<td colspan="2"><hr></td>
+</tr>
+<tr><td>exp/wingui</td> <td>code.google.com/p/gowingui</tr>
 </table>
 
 <p>
@@ -827,16 +755,7 @@ The <code>fmt</code> library automatically invokes <code>Error</code>, as it alr
 does for <code>String</code>, for easy printing of error values.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/START ERROR EXAMPLE/` `/END ERROR EXAMPLE/`}}
--->type SyntaxError struct {
-    File    string
-    Line    int
-    Message string
-}
-
-func (se *SyntaxError) Error() string {
-    return fmt.Sprintf(&#34;%s:%d: %s&#34;, se.File, se.Line, se.Message)
-}</pre>
+{{code "/doc/progs/go1.go" `/START ERROR EXAMPLE/` `/END ERROR EXAMPLE/`}}
 
 <p>
 All standard packages have been updated to use the new interface; the old <code>os.Error</code> is gone.
@@ -854,8 +773,7 @@ func New(text string) error
 to turn a string into an error. It replaces the old <code>os.NewError</code>.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/ErrSyntax/`}}
--->    var ErrSyntax = errors.New(&#34;syntax error&#34;)</pre>
+{{code "/doc/progs/go1.go" `/ErrSyntax/`}}
 		
 <p>
 <em>Updating</em>:
@@ -879,7 +797,7 @@ This behavior was unpleasant and unportable.
 In Go 1, the
 <a href="/pkg/syscall/"><code>syscall</code></a>
 package instead returns an <code>error</code> for system call errors.
-On Unix, the implementation is done by a 
+On Unix, the implementation is done by a
 <a href="/pkg/syscall/#Errno"><code>syscall.Errno</code></a> type
 that satisfies <code>error</code> and replaces the old <code>os.Errno</code>.
 </p>
@@ -906,7 +824,7 @@ and no distinction between absolute times and durations.
 
 <p>
 One of the most sweeping changes in the Go 1 library is therefore a
-complete redesign of the 
+complete redesign of the
 <a href="/pkg/time/"><code>time</code></a> package.
 Instead of an integer number of nanoseconds as an <code>int64</code>,
 and a separate <code>*time.Time</code> type to deal with human
@@ -945,17 +863,7 @@ returns a <code>time.Time</code> value rather than, in the old
 API, an integer nanosecond count since the Unix epoch.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/sleepUntil/` `/^}/`}}
--->// sleepUntil sleeps until the specified time. It returns immediately if it&#39;s too late.
-func sleepUntil(wakeup time.Time) {
-    now := time.Now() // A Time.
-    if !wakeup.After(now) {
-        return
-    }
-    delta := wakeup.Sub(now) // A Duration.
-    fmt.Printf(&#34;Sleeping for %.3fs\n&#34;, delta.Seconds())
-    time.Sleep(delta)
-}</pre>
+{{code "/doc/progs/go1.go" `/sleepUntil/` `/^}/`}}
 
 <p>
 The new types, methods, and constants have been propagated through
@@ -1103,7 +1011,7 @@ to be implemented in the future.
 No changes will be needed.
 </p>
 
-<h3 id="encoding_binary">The encoding/binary package</h3>               
+<h3 id="encoding_binary">The encoding/binary package</h3>
 
 <p>
 In Go 1, the <code>binary.TotalSize</code> function has been replaced by
@@ -1192,8 +1100,7 @@ Values for such flags must be given units, just as <code>time.Duration</code>
 formats them: <code>10s</code>, <code>1h30m</code>, etc.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/timeout/`}}
--->var timeout = flag.Duration(&#34;timeout&#34;, 30*time.Second, &#34;how long to wait for completion&#34;)</pre>
+{{code "/doc/progs/go1.go" `/timeout/`}}
 
 <p>
 <em>Updating</em>:
@@ -1249,7 +1156,7 @@ The <a href="/pkg/go/printer/"><code>go/printer</code></a> package supports an a
 configuration mode <a href="/pkg/go/printer/#Mode"><code>SourcePos</code></a>;
 if set, the printer will emit <code>//line</code> comments such that the generated
 output contains the original source code position information. The new type
-<a href="/pkg/go/printer/#CommentedNode"><code>CommentedNode</code></a> can be  
+<a href="/pkg/go/printer/#CommentedNode"><code>CommentedNode</code></a> can be
 used to provide comments associated with an arbitrary
 <a href="/pkg/go/ast/#Node"><code>ast.Node</code></a> (until now only
 <a href="/pkg/go/ast/#File"><code>ast.File</code></a> carried comment information).
@@ -1316,7 +1223,7 @@ to run-time errors.
 
 <p>
 In Go 1, the definition of <a href="/pkg/hash/#Hash"><code>hash.Hash</code></a> includes
-a new method, <code>BlockSize</code>.  This new method is used primarily in the 
+a new method, <code>BlockSize</code>.  This new method is used primarily in the
 cryptographic libraries.
 </p>
 
@@ -1502,7 +1409,7 @@ Running <code>go</code> <code>fix</code> will update almost all code affected by
 <h3 id="log_syslog">The log/syslog package</h3>
 
 <p>
-In Go 1, the <a href="/pkg/log/syslog/#NewLogger"><code>syslog.NewLogger</code></a>     
+In Go 1, the <a href="/pkg/log/syslog/#NewLogger"><code>syslog.NewLogger</code></a>
 function returns an error as well as a <code>log.Logger</code>.
 </p>
 
@@ -1517,7 +1424,7 @@ What little code is affected will be caught by the compiler and must be updated
 In Go 1, the <a href="/pkg/mime/#FormatMediaType"><code>FormatMediaType</code></a> function
 of the <code>mime</code> package has  been simplified to make it
 consistent with
-<a href="/pkg/mime/#ParseMediaType"><code>ParseMediaType</code></a>. 
+<a href="/pkg/mime/#ParseMediaType"><code>ParseMediaType</code></a>.
 It now takes <code>"text/html"</code> rather than <code>"text"</code> and <code>"html"</code>.
 </p>
 
@@ -1531,9 +1438,9 @@ What little code is affected will be caught by the compiler and must be updated
 <p>
 In Go 1, the various <code>SetTimeout</code>,
 <code>SetReadTimeout</code>, and <code>SetWriteTimeout</code> methods
-have been replaced with 
+have been replaced with
 <a href="/pkg/net/#IPConn.SetDeadline"><code>SetDeadline</code></a>,
-<a href="/pkg/net/#IPConn.SetReadDeadline"><code>SetReadDeadline</code></a>, and 
+<a href="/pkg/net/#IPConn.SetReadDeadline"><code>SetReadDeadline</code></a>, and
 <a href="/pkg/net/#IPConn.SetWriteDeadline"><code>SetWriteDeadline</code></a>,
 respectively.  Rather than taking a timeout value in nanoseconds that
 apply to any activity on the connection, the new methods set an
@@ -1707,11 +1614,7 @@ and
 <a href="/pkg/os/#IsPermission"><code>IsPermission</code></a>.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/os\.Open/` `/}/`}}
--->    f, err := os.OpenFile(name, os.O_RDWR|os.O_CREATE|os.O_EXCL, 0600)
-    if os.IsExist(err) {
-        log.Printf(&#34;%s already exists&#34;, name)
-    }</pre>
+{{code "/doc/progs/go1.go" `/os\.Open/` `/}/`}}
 
 <p>
 <em>Updating</em>:
@@ -1777,21 +1680,7 @@ If a directory's contents are to be skipped,
 the function should return the value <a href="/pkg/path/filepath/#variables"><code>filepath.SkipDir</code></a>
 </p>
 
-<pre><!--{{code "progs/go1.go" `/STARTWALK/` `/ENDWALK/`}}
--->    markFn := func(path string, info os.FileInfo, err error) error {
-        if path == &#34;pictures&#34; { // Will skip walking of directory pictures and its contents.
-            return filepath.SkipDir
-        }
-        if err != nil {
-            return err
-        }
-        log.Println(path)
-        return nil
-    }
-    err := filepath.Walk(&#34;.&#34;, markFn)
-    if err != nil {
-        log.Fatal(err)
-    }</pre>
+{{code "/doc/progs/go1.go" `/STARTWALK/` `/ENDWALK/`}}
 
 <p>
 <em>Updating</em>:
@@ -1804,7 +1693,7 @@ The compiler will catch code using the old interface.
 
 <p>
 The <a href="/pkg/regexp/"><code>regexp</code></a> package has been rewritten.
-It has the same interface but the specification of the regular expressions 
+It has the same interface but the specification of the regular expressions
 it supports has changed from the old "egrep" form to that of
 <a href="http://code.google.com/p/re2/">RE2</a>.
 </p>
@@ -1949,6 +1838,38 @@ a cast that must be added by hand; the <code>go</code> <code>fix</code> tool wil
 </p>
 
 
+<h3 id="templates">The template packages</h3>
+
+<p>
+The <code>template</code> and <code>exp/template/html</code> packages have moved to 
+<a href="/pkg/text/template/"><code>text/template</code></a> and
+<a href="/pkg/html/template/"><code>html/template</code></a>.
+More significant, the interface to these packages has been simplified.
+The template language is the same, but the concept of "template set" is gone
+and the functions and methods of the packages have changed accordingly,
+often by elimination.
+</p>
+
+<p>
+Instead of sets, a <code>Template</code> object
+may contain multiple named template definitions,
+in effect constructing
+name spaces for template invocation.
+A template can invoke any other template associated with it, but only those
+templates associated with it.
+The simplest way to associate templates is to parse them together, something
+made easier with the new structure of the packages.
+</p>
+
+<p>
+<em>Updating</em>:
+The imports will be updated by fix tool.
+Single-template uses will be otherwise be largely unaffected.
+Code that uses multiple templates in concert will need to be updated by hand.
+The <a href="/pkg/text/template/#examples">examples</a> in
+the documentation for <code>text/template</code> can provide guidance.
+</p>
+
 <h3 id="testing">The testing package</h3>
 
 <p>
@@ -1957,20 +1878,7 @@ In Go 1, <code>B</code> has new methods, analogous to those of <code>T</code>, e
 logging and failure reporting.
 </p>
 
-<pre><!--{{code "progs/go1.go" `/func.*Benchmark/` `/^}/`}}
--->func BenchmarkSprintf(b *testing.B) {
-    // Verify correctness before running benchmark.
-    b.StopTimer()
-    got := fmt.Sprintf(&#34;%x&#34;, 23)
-    const expect = &#34;17&#34;
-    if expect != got {
-        b.Fatalf(&#34;expected %q; got %q&#34;, expect, got)
-    }
-    b.StartTimer()
-    for i := 0; i &lt; b.N; i++ {
-        fmt.Sprintf(&#34;%x&#34;, 23)
-    }
-}</pre>
+{{code "/doc/progs/go1.go" `/func.*Benchmark/` `/^}/`}}
 
 <p>
 <em>Updating</em>:
@@ -2083,7 +1991,25 @@ The semantic changes make it difficult for the fix tool to update automatically.
 <h2 id="cmd_go">The go command</h2>
 
 <p>
-TODO: Write this.
+Go 1 introduces the <a href="/cmd/go/">go command</a>, a tool for fetching,
+building, and installing Go packages and commands. The <code>go</code> command
+does away with makefiles, instead using Go source code to find dependencies and
+determine build conditions. Most existing Go programs will no longer require
+makefiles to be built.
+</p>
+
+<p>
+See <a href="/doc/code.html">How to Write Go Code</a> for a primer on the
+<code>go</code> command and the <a href="/cmd/go/">go command documentation</a>
+for the full details.
+</p>
+
+<p>
+<em>Updating</em>:
+Projects that depend on the Go project's old makefile-based build
+infrastructure (<code>Make.pkg</code>, <code>Make.cmd</code>, and so on) should
+switch to using the <code>go</code> command for building Go code and, if
+necessary, rewrite their makefiles to perform any auxiliary build tasks.
 </p>
 
 <h2 id="cmd_cgo">The cgo command</h2>