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
diff --git a/doc/go1.html b/doc/go1.html
index dee680a..420cae4 100644
--- a/doc/go1.html
+++ b/doc/go1.html
@@ -626,8 +626,55 @@
<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 @@
<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>
diff --git a/doc/go1.tmpl b/doc/go1.tmpl
index c830b35..77eeeba 100644
--- a/doc/go1.tmpl
+++ b/doc/go1.tmpl
@@ -529,8 +529,55 @@
<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 @@
<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>
