doc/go1.4.html: vanity imports and internal packages

LGTM=rsc
R=golang-codereviews, rsc
CC=golang-codereviews
https://golang.org/cl/165800043

doc/go1.4.html

@@ -95,7 +95,7 @@ to defeat Go's type system by exploiting internal details of the implementation
 or machine representation of data.
 It was never explicitly specified what use of <code>unsafe</code> meant
 with respect to compatibility as specified in the
-<a href="go1compat.html">Go compatibilty guidelines</a>.
+<a href="go1compat.html">Go compatibility guidelines</a>.
 The answer, of course, is that we can make no promise of compatibility
 for code that does unsafe things.
 </p>
@@ -175,25 +175,103 @@ TODO gccgo news
 </p>
 
 <h3 id="internalpackages">Internal packages</h3>
-<pre>
-TODO prose for these
-cmd/go: implement "internal" (CL 120600043)
-</pre>
 
-<h3 id="importcomments">Import comments</h3>
+<p>
+Go's package system makes it easy to structure programs into components with clean boundaries,
+but there are only two forms of access: local (unexported) and global (exported).
+Sometimes one wishes to have components that are not exported,
+for instance to avoid acquiring clients of interfaces to code that is part of a public repository
+but not intended for use outside the program to which it belongs.
+</p>
+
+<p>
+The Go language does not have the power to enforce this distinction, but as of Go 1.4 the
+<a href="/cmd/go/"><code>go</code></a> command introduces
+a mechanism to define "internal" packages that may not be imported by packages outside
+the source subtree in which they reside.
+</p>
+
+<p>
+To create such a package, place it in a directory named <code>internal</code> or in a subdirectory of a directory
+named internal.
+When the <code>go</code> command sees an import of a package with <code>internal</code> in its path,
+it verifies that the package doing the import
+is within the tree rooted at the parent of the <code>internal</code> directory.
+For example, a package <code>.../a/b/c/internal/d/e/f</code>
+can be imported only by code in the directory tree rooted at <code>.../a/b/c</code>.
+It cannot be imported by code in <code>.../a/b/g</code> or in any other repository.
+</p>
+
+<p>
+For Go 1.4, the internal package mechanism is enforced for the main Go repository;
+from 1.5 and onward it will be enforced for any repository.
+</p>
+
+<p>
+Full details of the mechanism are in
+<a href="http://golang.org/s/go14internal">the design document</a>.
+</p>
+
+<h3 id="canonicalimports">Canonical import paths</h3>
+
+<p>
+Code often lives in repositories hosted by public services such as <code>github.com</code>,
+meaning that the import paths for packages begin with the name of the hosting service,
+<code>github.com/rsc/pdf</code> for example.
+One can use
+<a href="/cmd/go/#hdr-Remote_import_paths">an existing mechanism</a>
+to provide a "custom" or "vanity" import path such as
+<code>rsc.io/pdf</code>, but
+that creates two valid import paths for the package.
+That is a problem: one may inadvertently import the package through the two
+distinct paths in a single program, which is wasteful;
+miss an update to a package because the path being used is not recognized to be
+out of date;
+or break clients using the old path by moving the package to a different hosting service.
+</p>
+
+<p>
+Go 1.4 introduces an annotation for package clauses in Go source that identify a canonical
+import path for the package.
+If an import is attempted using a path that is not canonical,
+the <a href="/cmd/go/"><code>go</code></a> command
+will refuse to compile the importing package.
+</p>
+
+<p>
+The syntax is simple: put an identifying comment on the package line.
+For our example, the package clause would read:
+</p>
 
 <pre>
-TODO prose for these
-cmd/go: import comments (CL 124940043)
+package pdf // import "rsc.io/pdf"
 </pre>
 
+<p>
+With this in place,
+the <code>go</code> command will
+refuse to compile a package that imports <code>github.com/rsc/pdf</code>, 
+ensuring that the code can be moved without breaking users.
+</p>
+
+<p>
+The check is at build time, not download time, so if <code>go</code> <code>get</code>
+fails because of this check, the mis-imported package has been copied to the local machine
+and should be removed manually.
+</p>
+
+<p>
+Further information is in
+<a href="http://golang.org/s/go14customimport">the design document</a>.
+</p>
+
 <h3 id="gogenerate">The go generate subcommand</h3>
 
 <p>
 The <a href="/cmd/go/"><code>go</code></a> command has a new subcommand,
 <a href="/cmd/go/#hdr-Generate_Go_files_by_processing_source"><code>go generate</code></a>,
 to automate the running of tools to generate source code before compilation.
-For example, it can be used to run the <a href="http://en.wikipedia.org/wiki/Yacc"><code>yacc</code></a>
+For example, it can be used to run the <a href="/cmd/yacc"><code>yacc</code></a>
 compiler-compiler on a <code>.y</code> file to produce the Go source file implementing the grammar,
 or to automate the generation of <code>String</code> methods for typed constants using the new
 <a href="http://godoc.org/code.google.com/p/go.tools/cmd/stringer">stringer</a>
@@ -226,9 +304,9 @@ system name) is preceded by an underscore.
 
 <p>
 <em>Updating</em>: Packages that depend on the old behavior will no longer compile correctly.
-Files with names like <code>windows.go</code> or <code>arm64.go</code> should either
+Files with names like <code>windows.go</code> or <code>amd64.go</code> should either
 have explicit build tags added to the source or be renamed to something like
-<code>os_windows.go</code> or <code>support_arm64.go</code>.
+<code>os_windows.go</code> or <code>support_amd64.go</code>.
 </p>
 
 <h3 id="gocmd">Other changes to the go command</h3>
@@ -261,14 +339,15 @@ The non-functional <code>-file</code> flag has been removed.
 
 <li>
 The <a href="/cmd/go/#hdr-Test_packages"><code>go</code> <code>test</code></a>
-will compile and link all <code>*_test.go</code> files in the package,
+subcommand will compile and link all <code>*_test.go</code> files in the package,
 even when there are no <code>Test</code> functions in them. 
 It previously ignored such files.
 </li>
 
 <li>
 The behavior of the
-<a href="/cmd/go/#hdr-Test_packages"><code>go</code> <code>build</code></a>'s
+<a href="/cmd/go/#hdr-Test_packages"><code>go</code> <code>build</code></a>
+subcommand's
 <code>-a</code> flag has been changed for non-development installations.
 For installations running a released distribution, the <code>-a</code> flag will no longer
 rebuild the standard library and commands, to avoid overwriting the installation's files.
@@ -376,7 +455,6 @@ compress/flate, compress/gzip, compress/zlib: Reset support (https://codereview.
 crypto/tls: add support for ALPN (RFC 7301) (CL 108710046)
 crypto/tls: support programmatic selection of server certificates (CL 107400043)
 encoding/asn1: optional elements with a default value will now only be omitted if they have that value (CL 86960045)
-flag: it is now an error to set a flag multiple times (CL 156390043)
 fmt: print type *map[T]T as &amp;map[k:v] (CL 154870043)
 encoding/csv: do not quote empty strings, quote \. (CL 164760043)
 encoding/gob: remove unsafe (CL 102680045)
@@ -390,6 +468,7 @@ reflect: Value is one word smaller
 runtime: implement monotonic clocks on windows (CL 108700045)
 runtime: MemStats.Mallocs now counts very small allocations missed in Go 1.3. This may break tests using runtime.ReadMemStats or testing.AllocsPerRun by giving a more accurate answer than Go 1.3 did (CL 143150043).
 runtime/race: freebsd is supported (CL 107270043)
+runtime: add PauseEnd array to MemStats and GCStats (CL 153670043)
 swig: Due to runtime changes Go 1.4 will require SWIG 3.0.3 (not yet released)
 sync/atomic: add Value (CL 136710045)
 syscall: Setuid, Setgid are disabled on linux platforms. On linux those syscalls operate on the calling thread, not the whole process. This does not match the semantics of other platforms, nor the expectations of the caller, so the operations have been disabled until issue 1435 is resolved (CL 106170043)