code review 4642049: goinstall: documentation for new remote repository behavior

src/cmd/goinstall/doc.go

 // Copyright 2010 The Go Authors.  All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
 /*
 Goinstall is an experiment in automatic package installation.
 It installs packages, possibly downloading them from the internet.
-It maintains a list of public Go packages at http://godashboard.appspot.com/package.
+It maintains a list of public Go packages at
+http://godashboard.appspot.com/package.
 
 Usage:
         goinstall [flags] importpath...
         goinstall [flags] -a
 
 Flags and default settings:
         -a=false          install all previously installed packages
         -clean=false      clean the package directory before installing
         -dashboard=true   tally public packages on godashboard.appspot.com
         -install=true     build and install the package and its dependencies
@@ skipping 22 matching lines @@
 to update, recompile, and reinstall all goinstalled packages.
 
 The source code for a package with import path foo/bar is expected
 to be in the directory $GOROOT/src/pkg/foo/bar/ or $GOPATH/src/foo/bar/.
 See "The GOPATH Environment Variable" for more about GOPATH.
 
 By default, goinstall prints output only when it encounters an error.
 The -v flag causes goinstall to print information about packages
 being considered and installed.
 
-Goinstall does not use make. Makefiles are ignored by goinstall.
+Goinstall ignores Makefiles.
 
 
 Remote Repositories
 
 If a package import path refers to a remote repository, goinstall will
 download the code if necessary.
 
-An import path may refer to an arbitrary source repository by a suffix
-denoting the version control system. The supported VCSes and their
-respective suffixes are:
-
-        Bazaar      .bzr
-        Git         .git
-        Mercurial   .hg
-        Subversion  .svn
-
-Some examples:
-
-        To import the package at the root of a Mercurial repo at
-        "http://example.org/user/project", use this statement:
-
-                import "example.org/user/project.hg"
-
-        Or, the package foo/bar inside the Git repo at
-        "git://example.com/repo.git" or "http://example.com/repo.git":
-
-                import "example.com/repo.git/foo/bar"
-
-Goinstall also supports a few code hosting sites.

[quantumfyre, 2011/06/21 20:38:25]

"Goinstall also supports a few code hosting sites directly." perhaps?
Or specially?  Specifically?  Doesn't seem to read quite right as is ...

-Packages at one of these sites must not include the VCS suffix.

[quantumfyre, 2011/06/21 20:38:25]

s/one/any/ ?

-The recognized code hosting sites are:
+Goinstall recognizes packages from a few common code hosting sites:
 
         BitBucket (Mercurial)
 
                 import "bitbucket.org/user/project"
                 import "bitbucket.org/user/project/sub/directory"
 
         GitHub (Git)
 
                 import "github.com/user/project"
                 import "github.com/user/project/sub/directory"
 
         Google Code Project Hosting (Mercurial, Subversion)
 
                 import "project.googlecode.com/hg"
                 import "project.googlecode.com/hg/sub/directory"
 
                 import "project.googlecode.com/svn/trunk"
                 import "project.googlecode.com/svn/trunk/sub/directory"
 
         Launchpad (Bazaar)
 
                 import "launchpad.net/project"
                 import "launchpad.net/project/series"
                 import "launchpad.net/project/series/sub/directory"
 
                 import "launchpad.net/~user/project/branch"
                 import "launchpad.net/~user/project/branch/sub/directory"
 
-
 If the destination directory (e.g., $GOROOT/src/pkg/bitbucket.org/user/project)
 already exists and contains an appropriate checkout, goinstall will not
 attempt to fetch updates.  The -u flag changes this behavior,
 causing goinstall to update all remote packages encountered during
 the installation.
 
 When downloading or updating, goinstall first looks for a tag or branch
 named "release".  If there is one, it uses that version of the code.
 Otherwise it uses the default version selected by the version control
 system, typically HEAD for git, tip for Mercurial.
 
-After a successful download and installation of a publicly accessible
-remote package, goinstall reports the installation to godashboard.appspot.com,
-which increments a count associated with the package and the time
-of its most recent installation. This mechanism powers the package list
-at http://godashboard.appspot.com/package, allowing Go programmers
-to learn about popular packages that might be worth looking at.
+After a successful download and installation of one of these import paths,
+goinstall reports the installation to godashboard.appspot.com, which
+increments a count associated with the package and the time of its most
+recent installation. This mechanism powers the package list at
+http://godashboard.appspot.com/package, allowing Go programmers to learn about
+popular packages that might be worth looking at.         
 The -dashboard=false flag disables this reporting.
+
+For code hosted on other servers, goinstall recognizes the general form
+
+        repository.vcs/path
+
+as denoting the given repository, with or without the .vcs suffix, using
+the named version control system, and then the path inside that repository.
+The supported version control systems are:
+
+        Bazaar      .bzr
+        Git         .git
+        Mercurial   .hg
+        Subversion  .svn
+
+For example,·
+
+        import "example.org/user/foo.hg"
+
+denotes the root directory of the Mercurial repository at example.org/user/foo
+or foo.hg, and
+
+        import "example.org/repo.git/foo/bar"
+
+denotes the foo/bar directory of the Git repository at example.com/repo or
+repo.git.
+
+When a version control system supports multiple protocols, goinstall tries each
+in turn.
+For example, for Git it tries git://, then https://, then http://.
 
 
 The GOPATH Environment Variable
 
 GOPATH may be set to a colon-separated list of paths inside which Go code,
 package objects, and executables may be found.
 
 Set a GOPATH to use goinstall to build and install your own code and
 external libraries outside of the Go tree (and to avoid writing Makefiles).
 
@@ skipping 36 matching lines @@
 The following commands would build our example packages:
 
         goinstall /home/user/gocode/src/foo/bar  # build and install foo/bar
         cd /home/user/gocode/src/foo
         goinstall ./bar  # build and install foo/bar (again)
         cd qux
         goinstall .      # build and install foo/qux
 
 */
 package documentation