From 91bff9aae753c968fdfb44d72c12d4e5ded16ab8 Mon Sep 17 00:00:00 2001
From: Alex Crichton <alex@alexcrichton.com>
Date: Sun, 21 Sep 2014 17:59:19 -0700
Subject: [PATCH] Add some HTML docs for pkgid specs

---
 Makefile.in                              |  2 +-
 src/bin/pkgid.rs                         |  6 ++--
 src/cargo/ops/cargo_generate_lockfile.rs |  1 -
 src/doc/guide.md                         |  8 ++---
 src/doc/pkgid-spec.md                    | 44 ++++++++++++++++++++++++
 src/doc/stylesheets/all.css              |  3 ++
 6 files changed, 55 insertions(+), 9 deletions(-)
 create mode 100644 src/doc/pkgid-spec.md

diff --git a/Makefile.in b/Makefile.in
index 24005dc07..066d28275 100644
--- a/Makefile.in
+++ b/Makefile.in
@@ -102,7 +102,7 @@ clean:
 
 # === Documentation
 
-DOCS := index faq config guide manifest native-build
+DOCS := index faq config guide manifest native-build pkgid-spec
 DOC_DIR := target/doc
 DOC_OPTS := --markdown-no-toc \
 		--markdown-css stylesheets/normalize.css \
diff --git a/src/bin/pkgid.rs b/src/bin/pkgid.rs
index 48e4b6636..495501f6b 100644
--- a/src/bin/pkgid.rs
+++ b/src/bin/pkgid.rs
@@ -16,9 +16,9 @@ Options:
     --manifest-path PATH    Path to the manifest to the package to clean
     -v, --verbose           Use verbose output
 
-Given a <pkgid> argument, print out the fully qualified package id specifier.
-This command will generate an error if <pkgid> is ambiguous as to which package
-it refers to in the dependency graph. If no <pkgid> is given, then the pkgid for
+Given a <spec> argument, print out the fully qualified package id specifier.
+This command will generate an error if <spec> is ambiguous as to which package
+it refers to in the dependency graph. If no <spec> is given, then the pkgid for
 the local package is printed.
 
 This command requires that a lockfile is available and dependencies have been
diff --git a/src/cargo/ops/cargo_generate_lockfile.rs b/src/cargo/ops/cargo_generate_lockfile.rs
index fbc65c9d3..05dac10b3 100644
--- a/src/cargo/ops/cargo_generate_lockfile.rs
+++ b/src/cargo/ops/cargo_generate_lockfile.rs
@@ -54,7 +54,6 @@ pub fn update_lockfile(manifest_path: &Path,
         Some(name) => {
             let mut to_avoid = HashSet::new();
             let dep = try!(resolve.query(name.as_slice()));
-            fill_with_deps(&resolve, dep, &mut to_avoid);
             if aggressive {
                 fill_with_deps(&resolve, dep, &mut to_avoid);
             } else {
diff --git a/src/doc/guide.md b/src/doc/guide.md
index 107fbb6d5..327820aaf 100644
--- a/src/doc/guide.md
+++ b/src/doc/guide.md
@@ -294,7 +294,10 @@ $ cargo update       # updates all dependencies
 $ cargo update color # updates just 'color'
 ```
 
-This will write out a new `Cargo.lock` with the new version information.
+This will write out a new `Cargo.lock` with the new version information. Note
+that the argument to `cargo update` is actually a
+[Package ID Specification](pkgid-spec.html) and `color` is just a short
+specification.
 
 # Overriding Dependencies
 
@@ -393,7 +396,4 @@ To test your project on Travis-CI, here is a sample `.travis.yml` file:
 
 ```
 language: rust
-script:
-  - cargo build --verbose
-  - cargo test --verbose
 ```
diff --git a/src/doc/pkgid-spec.md b/src/doc/pkgid-spec.md
new file mode 100644
index 000000000..c5e86b371
--- /dev/null
+++ b/src/doc/pkgid-spec.md
@@ -0,0 +1,44 @@
+% Package ID Specifications
+
+# Package ID Specifications
+
+Subcommands of cargo frequently need to refer to a particular package within a
+dependency graph for various operations like updating, cleaning, building etc.
+To solve this problem, cargo supports Package ID Specifications. A specification
+is a string which is used to uniquely refer to one package within a graph of
+packages.
+
+## Specification grammar
+
+The formal grammar for a Package Id Specification is:
+
+```notrust
+pkgid := pkgname
+       | [ proto "://" ] hostname-and-path [ "#" ( pkgname | semver ) ]
+pkgname := name [ ":" semver ]
+
+proto := "http" | "git" | ...
+```
+
+Here, brackets indicate that the contents are optional.
+
+## Example Specifications
+
+These could all be references to a package `foo` version `1.2.3` from the
+registry at `crates.io`
+
+|         pkgid                  |  name  |  version  |          url         |
+|-------------------------------:|:------:|:---------:|:--------------------:|
+| `foo`                          | foo    | *         | *                    |
+| `foo:1.2.3`                    | foo    | 1.2.3     | *                    |
+| `crates.io/foo`                | foo    | *         | *://crates.io/foo    |
+| `crates.io/foo#1.2.3`          | foo    | 1.2.3     | *://crates.io/foo    |
+| `crates.io/bar#foo:1.2.3`      | foo    | 1.2.3     | *://crates.io/bar    |
+| `http://crates.io/foo#1.2.3`   | foo    | 1.2.3     | http://crates.io/foo |
+
+## Brevity of Specifications
+
+The goal of this is to enable both succinct and exhausitive syntaxes for
+referring to packages in a dependency graph. Ambiguous references may refer to
+one or more packages. Most commands generate an error if more than one package
+could be referred to with the same specification.
diff --git a/src/doc/stylesheets/all.css b/src/doc/stylesheets/all.css
index 6ba7557d6..1f4cdca65 100644
--- a/src/doc/stylesheets/all.css
+++ b/src/doc/stylesheets/all.css
@@ -150,3 +150,6 @@ pre.rust .doccomment { color: #4D4D4C; }
 pre.rust .macro, pre.rust .macro-nonterminal { color: #3E999F; }
 pre.rust .lifetime { color: #B76514; }
 code span.s1 { color: #2AA198; }
+
+table th { border-bottom: 1px solid black; }
+table td, table th { padding: 5px 10px; }
-- 
2.39.5