Change pkgid parser to allow overriding the inferred crate name.

Previously the a pkgid of `foo/rust-bar#1.0` implied a crate name of
`rust-bar` and didn't allow this to be overridden. Now you can override the
inferred crate name with `foo/rust-bar#bar:1.0`.
Update docs to new syntax.
auto merge of #10972 : metajack/rust/pkgid-with-name, r=alexcrichton

This change extends the pkgid attribute to allow of explicit crate names, instead of always inferring them based on the path. This means that if your GitHub repo is called `rust-foo`, you can have your pkgid set your library name to `foo`. You'd do this with a pkgid attribute like `github.com/somewhere/rust-foo#foo:1.0`.

This is half of the fix for #10922.