doc/go1: the simpler package changes

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

doc/go1.html

@@ -217,7 +217,7 @@ Go 1 introduces a new built-in type, <code>error</code>, which has the following
 
 <p>
 Since the consequences of this type are all in the package library,
-it is discussed <a href="errors">below</a>.
+it is discussed <a href="#errors">below</a>.
 </p>
 
 <h3 id="delete">Deleting from maps</h3>
@@ -547,15 +547,73 @@ by hand.
 
 <h3 id="errors">The error type and errors package</h3>
 
+<p>
+As mentioned above, Go 1 introduces a new built-in interface type called <code>error</code>.
+Its intent is to replace the old <code>os.Error</code> type with a more central concept.
+So the widely-used <code>String</code> method does not cause accidental satisfaction
+of the <code>error</code> interface, the <code>error</code> interface uses instead
+the name <code>Error</code> for that method:
+</p>
+
+<pre>
+    type error interface {
+        Error() string
+    }
+</pre>
+
+<p>
+The <code>fmt</code> library automatically invokes <code>Error</code>, as it already
+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>
+
+<p>
+All standard packages have been updated to use the new interface; the old <code>os.Error</code> is gone.
+</p>
+
+<p>
+A new package, <a href="/pkg/errors/"><code>errors</code></a>, contains the function
+</p>
+
+<pre>
+func New(text string) error
+</pre>
+
+<p>
+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>
+		
+<p>
+<em>Updating</em>:
+Gofix will update almost all code affected by the change.
+Code that defines error types with a <code>String</code> method will need to be updated
+by hand to rename the methods to <code>Error</code>.
+</p>
+
 <h3 id="errno">System call errors</h3>
 
 <p>
 In Go 1, the
-<a href="http://golang.org/pkg/syscall"><code>syscall</code></a>
+<a href="/pkg/syscall/"><code>syscall</code></a>
 package returns an <code>error</code> for system call errors,
 rather than plain integer <code>errno</code> values.
 On Unix, the implementation is done by a 
-<a href="http://golang.org/pkg/syscall/#Errno"><code>syscall.Errno</code></a> type
+<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>
 
@@ -568,15 +626,13 @@ rather than <code>syscall</code> and so will be unaffected.
 
 <h3 id="time">Time</h3>
 
-<h3 id="html">The html package</h3>
-
 <h3 id="http">The http package</h3>
 
 <h3 id="strconv">The strconv package</h3>
 
 <p>
 In Go 1, the
-<a href="http://golang.org/pkg/syscall"><code>strconv</code></a>
+<a href="/pkg/strconv/"><code>strconv</code></a>
 package has been significantly reworked to make it more Go-like and less C-like,
 although <code>Atoi</code> lives on (it's similar to
 <code>int(ParseInt(x, 10, 0))</code>, as does
@@ -587,7 +643,7 @@ return strings, to allow control over allocation.
 
 <p>
 This table summarizes the renamings; see the
-<a href="/pkg/strconv">package documentation</a>
+<a href="/pkg/strconv/">package documentation</a>
 for full details.
 </p>
 
@@ -666,33 +722,99 @@ they may require
 a cast that must be added by hand; gofix will warn about it.
 </p>
 
+<h3 id="os_fileinfo">The os.FileInfo type</h3>
+
 <h3 id="exp">The package tree exp</h3>
 
+<p>
+Because they are not standardized, the packages under the <code>exp</code> directory will not be available in the
+standard Go 1 release distributions, although they will be available in source code form
+in <a href="http://code.google.com/p/go/">the repository</a> for
+developers who wish to use them.
+</p>
+
+<p>
+Several packages have moved under <code>exp</code> at the time of Go 1's release:
+</p>
+
+<ul>
+<li><code>ebnf</code></li>
+<li><code>go/types</code></li>
+<li><code>http/spdy</code></li>
+</ul>
+
+<p>
+All these packages are available under the same names, with <code>exp/</code> prefixed: <code>exp/ebnf</code> etc.
+</p>
+
+<p>
+Also, the <code>gotype</code> command now resides in <code>exp/gotype</code>, while
+<code>ebnflint</code> is now in <code>exp/ebnflint</code>
+</p>
+
+<p>
+<em>Updating</em>:
+Code that uses packages in <code>exp</code> will need to be updated by hand,
+or else compiled from an installation that has <code>exp</code> available.
+Gofix will warn about such uses.
+<br>
+<font color="red">TODO: gofix should warn about such uses.</font>
+</p>
+
 <h3 id="old">The package tree old</h3>
 
+<p>
+Because they are deprecated, the packages under the <code>old</code> directory will not be available in the
+standard Go 1 release distributions, although they will be available in source code form for
+developers who wish to use them.
+</p>
+
+<p>
+The packages in their new locations are:
+</p>
+
+<ul>
+<li><code>old/netchan</code></li>
+<li><code>old/regexp</code></li>
+<li><code>old/template</code></li>
+</ul>
+
+<p>
+<em>Updating</em>:
+Code that uses packages now in <code>old</code> will need to be updated by hand,
+or else compiled from an installation that has <code>old</code> available.
+Gofix will warn about such uses.
+<br>
+<font color="red">TODO: gofix should warn about such uses.</font>
+</p>
+
 <h3 id="deleted">Deleted packages</h3>
 
-<!-- 
+<p>
+Go 1 deletes several packages outright:
+</p>
 
-moving to exp/* (and thus not in Go 1):
-	ebnf, command ebnflint
-	go/types, command gotype
-	http/spdy
-	
-deleted:
-	container/vector
-	exp/datafmt
-	go/typechecker
-	try, command gotry
-
-go/typechecker
-go/types
-ebnf (and cmd/ebnflint)
-container/vector
-try (and gotry)
-exp/datafmt
-netchan
--->
+<ul>
+<li><code>container/vector</code></li>
+<li><code>exp/datafmt</code></li>
+<li><code>go/typechecker</code></li>
+<li><code>try</code></li>
+</ul>
+
+<p>
+and also the command <code>gotry</code>.
+</p>
+
+<p>
+<em>Updating</em>:
+Code that uses <code>container/vector</code> should be updated to use
+slices directly.  See
+<a href="http://code.google.com/p/go-wiki/wiki/SliceTricks">the Go
+Language Community Wiki</a> for some suggestions.
+Code that uses the other packages (there should be almost zero) will need to be rethought.
+<br>
+<font color="red">TODO: gofix should warn such uses.</font>
+</p>
 
 <h3 id="subrepo">Packages moving to subrepositories</h3>
 
@@ -701,8 +823,6 @@ crypto/openpgp to XXX
 maybe exp/ssh?
 -->
 
-<h3 id="os_fileinfo">The os.FileInfo type</h3>
-
 <h2 id="go_command">The go command</h2>
 
 <h2 id="releases">Packaged releases</h2>

doc/go1.tmpl

@@ -163,7 +163,7 @@ Go 1 introduces a new built-in type, <code>error</code>, which has the following
 
 <p>
 Since the consequences of this type are all in the package library,
-it is discussed <a href="errors">below</a>.
+it is discussed <a href="#errors">below</a>.
 </p>
 
 <h3 id="delete">Deleting from maps</h3>
@@ -462,15 +462,61 @@ by hand.
 
 <h3 id="errors">The error type and errors package</h3>
 
+<p>
+As mentioned above, Go 1 introduces a new built-in interface type called <code>error</code>.
+Its intent is to replace the old <code>os.Error</code> type with a more central concept.
+So the widely-used <code>String</code> method does not cause accidental satisfaction
+of the <code>error</code> interface, the <code>error</code> interface uses instead
+the name <code>Error</code> for that method:
+</p>
+
+<pre>
+    type error interface {
+        Error() string
+    }
+</pre>
+
+<p>
+The <code>fmt</code> library automatically invokes <code>Error</code>, as it already
+does for <code>String</code>, for easy printing of error values.
+</p>
+
+{{code "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.
+</p>
+
+<p>
+A new package, <a href="/pkg/errors/"><code>errors</code></a>, contains the function
+</p>
+
+<pre>
+func New(text string) error
+</pre>
+
+<p>
+to turn a string into an error. It replaces the old <code>os.NewError</code>.
+</p>
+
+{{code "progs/go1.go" `/ErrSyntax/`}}
+		
+<p>
+<em>Updating</em>:
+Gofix will update almost all code affected by the change.
+Code that defines error types with a <code>String</code> method will need to be updated
+by hand to rename the methods to <code>Error</code>.
+</p>
+
 <h3 id="errno">System call errors</h3>
 
 <p>
 In Go 1, the
-<a href="http://golang.org/pkg/syscall"><code>syscall</code></a>
+<a href="/pkg/syscall/"><code>syscall</code></a>
 package returns an <code>error</code> for system call errors,
 rather than plain integer <code>errno</code> values.
 On Unix, the implementation is done by a 
-<a href="http://golang.org/pkg/syscall/#Errno"><code>syscall.Errno</code></a> type
+<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>
 
@@ -483,15 +529,13 @@ rather than <code>syscall</code> and so will be unaffected.
 
 <h3 id="time">Time</h3>
 
-<h3 id="html">The html package</h3>
-
 <h3 id="http">The http package</h3>
 
 <h3 id="strconv">The strconv package</h3>
 
 <p>
 In Go 1, the
-<a href="http://golang.org/pkg/syscall"><code>strconv</code></a>
+<a href="/pkg/strconv/"><code>strconv</code></a>
 package has been significantly reworked to make it more Go-like and less C-like,
 although <code>Atoi</code> lives on (it's similar to
 <code>int(ParseInt(x, 10, 0))</code>, as does
@@ -502,7 +546,7 @@ return strings, to allow control over allocation.
 
 <p>
 This table summarizes the renamings; see the
-<a href="/pkg/strconv">package documentation</a>
+<a href="/pkg/strconv/">package documentation</a>
 for full details.
 </p>
 
@@ -581,33 +625,99 @@ they may require
 a cast that must be added by hand; gofix will warn about it.
 </p>
 
+<h3 id="os_fileinfo">The os.FileInfo type</h3>
+
 <h3 id="exp">The package tree exp</h3>
 
+<p>
+Because they are not standardized, the packages under the <code>exp</code> directory will not be available in the
+standard Go 1 release distributions, although they will be available in source code form
+in <a href="http://code.google.com/p/go/">the repository</a> for
+developers who wish to use them.
+</p>
+
+<p>
+Several packages have moved under <code>exp</code> at the time of Go 1's release:
+</p>
+
+<ul>
+<li><code>ebnf</code></li>
+<li><code>go/types</code></li>
+<li><code>http/spdy</code></li>
+</ul>
+
+<p>
+All these packages are available under the same names, with <code>exp/</code> prefixed: <code>exp/ebnf</code> etc.
+</p>
+
+<p>
+Also, the <code>gotype</code> command now resides in <code>exp/gotype</code>, while
+<code>ebnflint</code> is now in <code>exp/ebnflint</code>
+</p>
+
+<p>
+<em>Updating</em>:
+Code that uses packages in <code>exp</code> will need to be updated by hand,
+or else compiled from an installation that has <code>exp</code> available.
+Gofix will warn about such uses.
+<br>
+<font color="red">TODO: gofix should warn about such uses.</font>
+</p>
+
 <h3 id="old">The package tree old</h3>
 
+<p>
+Because they are deprecated, the packages under the <code>old</code> directory will not be available in the
+standard Go 1 release distributions, although they will be available in source code form for
+developers who wish to use them.
+</p>
+
+<p>
+The packages in their new locations are:
+</p>
+
+<ul>
+<li><code>old/netchan</code></li>
+<li><code>old/regexp</code></li>
+<li><code>old/template</code></li>
+</ul>
+
+<p>
+<em>Updating</em>:
+Code that uses packages now in <code>old</code> will need to be updated by hand,
+or else compiled from an installation that has <code>old</code> available.
+Gofix will warn about such uses.
+<br>
+<font color="red">TODO: gofix should warn about such uses.</font>
+</p>
+
 <h3 id="deleted">Deleted packages</h3>
 
-<!-- 
+<p>
+Go 1 deletes several packages outright:
+</p>
 
-moving to exp/* (and thus not in Go 1):
-	ebnf, command ebnflint
-	go/types, command gotype
-	http/spdy
-	
-deleted:
-	container/vector
-	exp/datafmt
-	go/typechecker
-	try, command gotry
-
-go/typechecker
-go/types
-ebnf (and cmd/ebnflint)
-container/vector
-try (and gotry)
-exp/datafmt
-netchan
--->
+<ul>
+<li><code>container/vector</code></li>
+<li><code>exp/datafmt</code></li>
+<li><code>go/typechecker</code></li>
+<li><code>try</code></li>
+</ul>
+
+<p>
+and also the command <code>gotry</code>.
+</p>
+
+<p>
+<em>Updating</em>:
+Code that uses <code>container/vector</code> should be updated to use
+slices directly.  See
+<a href="http://code.google.com/p/go-wiki/wiki/SliceTricks">the Go
+Language Community Wiki</a> for some suggestions.
+Code that uses the other packages (there should be almost zero) will need to be rethought.
+<br>
+<font color="red">TODO: gofix should warn such uses.</font>
+</p>
 
 <h3 id="subrepo">Packages moving to subrepositories</h3>
 
@@ -616,8 +726,6 @@ crypto/openpgp to XXX
 maybe exp/ssh?
 -->
 
-<h3 id="os_fileinfo">The os.FileInfo type</h3>
-
 <h2 id="go_command">The go command</h2>
 
 <h2 id="releases">Packaged releases</h2>

doc/progs/go1.go

@@ -7,6 +7,8 @@
 package main
 
 import (
+	"errors"
+	"fmt"
 	"log"
 	"unicode"
 )
@@ -19,6 +21,7 @@ func main() {
 	structEquality()
 	compositeLiterals()
 	runeType()
+	errorExample()
 }
 
 func mapDelete() {
@@ -130,6 +133,29 @@ func runeType() {
 	// ENDRUNE OMIT
 }
 
+// START ERROR EXAMPLE OMIT
+type SyntaxError struct {
+	File    string
+	Line    int
+	Message string
+}
+
+func (se *SyntaxError) Error() string {
+	return fmt.Sprintf("%s:%d: %s", se.File, se.Line, se.Message)
+}
+// END ERROR EXAMPLE OMIT
+
+func errorExample() {
+	var ErrSyntax = errors.New("syntax error")
+	_ = ErrSyntax
+	se := &SyntaxError{"file", 7, "error"}
+	got := fmt.Sprint(se)
+	const expect = "file:7: error"
+	if got != expect {
+		log.Fatalf("errorsPackage: expected %q got %q", expect, got)
+	}
+}
+
 func f(string, int) {
 }