doc/go1: more package updates

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

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

doc/go1.html

@@ -626,8 +626,55 @@ rather than <code>syscall</code> and so will be unaffected.
 
 <h3 id="time">Time</h3>
 
+<h3 id="html">The html package</h3>
+
+<p>
+The <a href="/pkg/html/"><code>html</code></a> package in Go 1 provides
+a full parser for HTML5.
+</p>
+
+<p>
+<em>Updating</em>:
+Since the package's functionality is new, no updating is necessary.
+</p>
+
 <h3 id="http">The http package</h3>
 
+<p>
+In Go 1 the <a href="/pkg/http/"><code>http</code></a> package is refactored,
+putting some of the utilities into a
+<a href="/pkg/httputil/"><code>httputil</code></a> subdirectory.
+These pieces are only rarely needed by HTTP clients.
+The affected items are:
+</p>
+
+<ul>
+<li>ClientConn</li>
+<li>DumpRequest</li>
+<li>DumpRequest</li>
+<li>DumpRequestOut</li>
+<li>DumpResponse</li>
+<li>NewChunkedReader</li>
+<li>NewChunkedWriter</li>
+<li>NewClientConn</li>
+<li>NewProxyClientConn</li>
+<li>NewServerConn</li>
+<li>NewSingleHostReverseProxy</li>
+<li>ReverseProxy</li>
+<li>ServerConn</li>
+</ul>
+
+<p>
+Also, the <code>Request.RawURL</code> field has been removed; it was a
+historical artifact.
+</p>
+
+<p>
+<em>Updating</em>:
+Gofix will update the few programs that are affected except for
+uses of <code>RawURL</code>, which must be fixed by hand.
+</p>
+
 <h3 id="strconv">The strconv package</h3>
 
 <p>
@@ -724,6 +771,78 @@ a cast that must be added by hand; gofix will warn about it.
 
 <h3 id="os_fileinfo">The os.FileInfo type</h3>
 
+<p>
+Go 1 redefines the <a href="/pkg/os/#FileInfo"><code>os.FileInfo</code></a> type,
+changing it from a struct to an interface:
+</p>
+
+<pre>
+    type FileInfo interface {
+        Name() string       // base name of the file
+        Size() int64        // length in bytes
+        Mode() FileMode     // file mode bits
+        ModTime() time.Time // modification time
+        IsDir() bool        // abbreviation for Mode().IsDir()
+    }
+</pre>
+
+<p>
+The file mode information has been moved into a subtype called
+<a href="/pkg/os/#FileMode"><code>os.FileMode</code></a>,
+a simple integer type with <code>IsDir</code>, <code>Perm</code>, and <code>String</code>
+methods.
+</p>
+
+<p>
+The system-specific details of file modes and properties such as (on Unix)
+i-number have been removed from <code>FileInfo</code> altogether.
+Instead, each operating system's <code>os</code> package provides an
+implementation of the <code>FileInfo</code> interface, <code>*os.FileStat</code>,
+which in turn contains a <code>Sys</code> field that stores the
+system-specific representation of file metadata.
+For instance, to discover the i-number of a file on a Unix system, unpack
+the <code>FileInfo</code> like this:
+</p>
+
+<pre>
+    fi, err := os.Stat("hello.go")
+    if err != nil {
+        log.Fatal(err)
+    }
+    // Make sure it's an implementation known to package os.
+    fileStat, ok := fi.(*os.FileStat)
+    if !ok {
+        log.Fatal("hello.go: not an os File")
+    }
+    // Now check that it's a Unix file.
+    unixStat, ok := fileStat.Sys.(*syscall.Stat_t)
+    if !ok {
+        log.Fatal("hello.go: not a Unix file")
+    }
+    fmt.Printf("file i-number: %d\n", unixStat.Ino)
+</pre>
+
+<p>
+Assuming (which is unwise) that <code>"hello.go"</code> is a Unix file,
+the i-number expression could be contracted to
+</p>
+
+<pre>
+    fi.(*os.FileStat).Sys.(*syscall.Stat_t).Ino
+</pre>
+
+<p>
+The vast majority of uses of <code>FileInfo</code> need only the methods
+of the standard interface.
+</p>
+	
+<p>
+<em>Updating</em>:
+Gofix will update code that uses the old equivalent of the current <code>os.FileInfo</code>
+and <code>os.FileMode</code> API.
+Code that needs system-specific file details will need to be updated by hand.
+</p>
+
 <h3 id="exp">The package tree exp</h3>
 
 <p>

doc/go1.tmpl

@@ -529,8 +529,55 @@ rather than <code>syscall</code> and so will be unaffected.
 
 <h3 id="time">Time</h3>
 
+<h3 id="html">The html package</h3>
+
+<p>
+The <a href="/pkg/html/"><code>html</code></a> package in Go 1 provides
+a full parser for HTML5.
+</p>
+
+<p>
+<em>Updating</em>:
+Since the package's functionality is new, no updating is necessary.
+</p>
+
 <h3 id="http">The http package</h3>
 
+<p>
+In Go 1 the <a href="/pkg/http/"><code>http</code></a> package is refactored,
+putting some of the utilities into a
+<a href="/pkg/httputil/"><code>httputil</code></a> subdirectory.
+These pieces are only rarely needed by HTTP clients.
+The affected items are:
+</p>
+
+<ul>
+<li>ClientConn</li>
+<li>DumpRequest</li>
+<li>DumpRequest</li>
+<li>DumpRequestOut</li>
+<li>DumpResponse</li>
+<li>NewChunkedReader</li>
+<li>NewChunkedWriter</li>
+<li>NewClientConn</li>
+<li>NewProxyClientConn</li>
+<li>NewServerConn</li>
+<li>NewSingleHostReverseProxy</li>
+<li>ReverseProxy</li>
+<li>ServerConn</li>
+</ul>
+
+<p>
+Also, the <code>Request.RawURL</code> field has been removed; it was a
+historical artifact.
+</p>
+
+<p>
+<em>Updating</em>:
+Gofix will update the few programs that are affected except for
+uses of <code>RawURL</code>, which must be fixed by hand.
+</p>
+
 <h3 id="strconv">The strconv package</h3>
 
 <p>
@@ -627,6 +674,78 @@ a cast that must be added by hand; gofix will warn about it.
 
 <h3 id="os_fileinfo">The os.FileInfo type</h3>
 
+<p>
+Go 1 redefines the <a href="/pkg/os/#FileInfo"><code>os.FileInfo</code></a> type,
+changing it from a struct to an interface:
+</p>
+
+<pre>
+    type FileInfo interface {
+        Name() string       // base name of the file
+        Size() int64        // length in bytes
+        Mode() FileMode     // file mode bits
+        ModTime() time.Time // modification time
+        IsDir() bool        // abbreviation for Mode().IsDir()
+    }
+</pre>
+
+<p>
+The file mode information has been moved into a subtype called
+<a href="/pkg/os/#FileMode"><code>os.FileMode</code></a>,
+a simple integer type with <code>IsDir</code>, <code>Perm</code>, and <code>String</code>
+methods.
+</p>
+
+<p>
+The system-specific details of file modes and properties such as (on Unix)
+i-number have been removed from <code>FileInfo</code> altogether.
+Instead, each operating system's <code>os</code> package provides an
+implementation of the <code>FileInfo</code> interface, <code>*os.FileStat</code>,
+which in turn contains a <code>Sys</code> field that stores the
+system-specific representation of file metadata.
+For instance, to discover the i-number of a file on a Unix system, unpack
+the <code>FileInfo</code> like this:
+</p>
+
+<pre>
+    fi, err := os.Stat("hello.go")
+    if err != nil {
+        log.Fatal(err)
+    }
+    // Make sure it's an implementation known to package os.
+    fileStat, ok := fi.(*os.FileStat)
+    if !ok {
+        log.Fatal("hello.go: not an os File")
+    }
+    // Now check that it's a Unix file.
+    unixStat, ok := fileStat.Sys.(*syscall.Stat_t)
+    if !ok {
+        log.Fatal("hello.go: not a Unix file")
+    }
+    fmt.Printf("file i-number: %d\n", unixStat.Ino)
+</pre>
+
+<p>
+Assuming (which is unwise) that <code>"hello.go"</code> is a Unix file,
+the i-number expression could be contracted to
+</p>
+
+<pre>
+    fi.(*os.FileStat).Sys.(*syscall.Stat_t).Ino
+</pre>
+
+<p>
+The vast majority of uses of <code>FileInfo</code> need only the methods
+of the standard interface.
+</p>
+	
+<p>
+<em>Updating</em>:
+Gofix will update code that uses the old equivalent of the current <code>os.FileInfo</code>
+and <code>os.FileMode</code> API.
+Code that needs system-specific file details will need to be updated by hand.
+</p>
+
 <h3 id="exp">The package tree exp</h3>
 
 <p>