Document the use of @ in PKGID Specs

Since the `cargo pkgid` docs were so brief, I figured I'd focus on the expected common case and only cover `@` while the reference mentions both in the grammar.
rust-lang · Apr 26, 2022 · 709f1be · 709f1be
1 parent cdec383
commit 709f1be
Show file tree

Hide file tree

Showing 5 changed files with 20 additions and 20 deletions.
diff --git a/src/doc/man/cargo-pkgid.md b/src/doc/man/cargo-pkgid.md
@@ -27,11 +27,11 @@ following:
 SPEC Structure             | Example SPEC
 ---------------------------|--------------
 _name_                     | `bitflags`
-_name_`:`_version_         | `bitflags:1.0.4`
+_name_`@`_version_         | `bitflags@1.0.4`
 _url_                      | `https://github.com/rust-lang/cargo`
 _url_`#`_version_          | `https://github.com/rust-lang/cargo#0.33.0`
 _url_`#`_name_             | `https://github.com/rust-lang/crates.io-index#bitflags`
-_url_`#`_name_`:`_version_ | `https://github.com/rust-lang/cargo#crates-io:0.21.0`
+_url_`#`_name_`:`_version_ | `https://github.com/rust-lang/cargo#crates-io@0.21.0`
 
 ## OPTIONS
 
@@ -75,7 +75,7 @@ Get the package ID for the given package instead of the current package.
 
 2. Retrieve package specification for version 1.0.0 of `foo`:
 
-       cargo pkgid foo:1.0.0
+       cargo pkgid foo@1.0.0
 
 3. Retrieve package specification for `foo` from crates.io:
 

diff --git a/src/doc/man/generated_txt/cargo-pkgid.txt b/src/doc/man/generated_txt/cargo-pkgid.txt
@@ -26,7 +26,7 @@ DESCRIPTION
        +-----------------+--------------------------------------------------+
        | name            | bitflags                                         |
        +-----------------+--------------------------------------------------+
-       | name:version    | bitflags:1.0.4                                   |
+       | name@version    | bitflags@1.0.4                                   |
        +-----------------+--------------------------------------------------+
        | url             | https://github.com/rust-lang/cargo               |
        +-----------------+--------------------------------------------------+
@@ -36,7 +36,7 @@ DESCRIPTION
        |                 | https://github.com/rust-lang/crates.io-index#bitflags |
        +-----------------+--------------------------------------------------+
        |                 |                                                  |
-       | url#name:version | https://github.com/rust-lang/cargo#crates-io:0.21.0 |
+       | url#name:version | https://github.com/rust-lang/cargo#crates-io@0.21.0 |
        +-----------------+--------------------------------------------------+
 
 OPTIONS
@@ -133,7 +133,7 @@ EXAMPLES
 
        2. Retrieve package specification for version 1.0.0 of foo:
 
-              cargo pkgid foo:1.0.0
+              cargo pkgid foo@1.0.0
 
        3. Retrieve package specification for foo from crates.io:
 

diff --git a/src/doc/src/commands/cargo-pkgid.md b/src/doc/src/commands/cargo-pkgid.md
@@ -27,11 +27,11 @@ following:
 SPEC Structure             | Example SPEC
 ---------------------------|--------------
 _name_                     | `bitflags`
-_name_`:`_version_         | `bitflags:1.0.4`
+_name_`@`_version_         | `bitflags@1.0.4`
 _url_                      | `https://github.com/rust-lang/cargo`
 _url_`#`_version_          | `https://github.com/rust-lang/cargo#0.33.0`
 _url_`#`_name_             | `https://github.com/rust-lang/crates.io-index#bitflags`
-_url_`#`_name_`:`_version_ | `https://github.com/rust-lang/cargo#crates-io:0.21.0`
+_url_`#`_name_`:`_version_ | `https://github.com/rust-lang/cargo#crates-io@0.21.0`
 
 ## OPTIONS
 
@@ -159,7 +159,7 @@ details on environment variables that Cargo reads.
 
 2. Retrieve package specification for version 1.0.0 of `foo`:
 
-       cargo pkgid foo:1.0.0
+       cargo pkgid foo@1.0.0
 
 3. Retrieve package specification for `foo` from crates.io:
 

diff --git a/src/doc/src/reference/pkgid-spec.md b/src/doc/src/reference/pkgid-spec.md
@@ -9,12 +9,12 @@ is a string which is used to uniquely refer to one package within a graph of
 packages.
 
 The specification may be fully qualified, such as
-`https://github.com/rust-lang/crates.io-index#regex:1.4.3` or it may be
+`https://github.com/rust-lang/crates.io-index#regex@1.4.3` or it may be
 abbreviated, such as `regex`. The abbreviated form may be used as long as it
 uniquely identifies a single package in the dependency graph. If there is
 ambiguity, additional qualifiers can be added to make it unique. For example,
 if there are two versions of the `regex` package in the graph, then it can be
-qualified with a version to make it unique, such as `regex:1.4.3`.
+qualified with a version to make it unique, such as `regex@1.4.3`.
 
 #### Specification grammar
 
@@ -23,7 +23,7 @@ The formal grammar for a Package Id Specification is:
 ```notrust
 spec := pkgname
        | proto "://" hostname-and-path [ "#" ( pkgname | semver ) ]
-pkgname := name [ ":" semver ]
+pkgname := name [ ("@" | ":" ) semver ]
 
 proto := "http" | "git" | ...
 ```
@@ -40,17 +40,17 @@ The following are references to the `regex` package on `crates.io`:
 | Spec                                                        | Name    | Version |
 |:------------------------------------------------------------|:-------:|:-------:|
 | `regex`                                                     | `regex` | `*`     |
-| `regex:1.4.3`                                               | `regex` | `1.4.3` |
+| `regex@1.4.3`                                               | `regex` | `1.4.3` |
 | `https://github.com/rust-lang/crates.io-index#regex`        | `regex` | `*`     |
-| `https://github.com/rust-lang/crates.io-index#regex:1.4.3`  | `regex` | `1.4.3` |
+| `https://github.com/rust-lang/crates.io-index#regex@1.4.3`  | `regex` | `1.4.3` |
 
 The following are some examples of specs for several different git dependencies:
 
 | Spec                                                      | Name             | Version  |
 |:----------------------------------------------------------|:----------------:|:--------:|
 | `https://github.com/rust-lang/cargo#0.52.0`               | `cargo`          | `0.52.0` |
-| `https://github.com/rust-lang/cargo#cargo-platform:0.1.2` | <nobr>`cargo-platform`</nobr> | `0.1.2`  |
-| `ssh://[email protected]/rust-lang/regex.git#regex:1.4.3`    | `regex`          | `1.4.3`  |
+| `https://github.com/rust-lang/cargo#cargo-platform@0.1.2` | <nobr>`cargo-platform`</nobr> | `0.1.2`  |
+| `ssh://[email protected]/rust-lang/regex.git#regex@1.4.3`    | `regex`          | `1.4.3`  |
 
 Local packages on the filesystem can use `file://` URLs to reference them:
 

diff --git a/src/etc/man/cargo-pkgid.1 b/src/etc/man/cargo-pkgid.1
@@ -36,9 +36,9 @@ T}:T{
 \fBbitflags\fR
 T}
 T{
-\fIname\fR\fB:\fR\fIversion\fR
+\fIname\fR\fB@\fR\fIversion\fR
 T}:T{
-\fBbitflags:1.0.4\fR
+\fBbitflags@1.0.4\fR
 T}
 T{
 \fIurl\fR
@@ -58,7 +58,7 @@ T}
 T{
 \fIurl\fR\fB#\fR\fIname\fR\fB:\fR\fIversion\fR
 T}:T{
-\fBhttps://github.com/rust\-lang/cargo#crates\-io:0.21.0\fR
+\fBhttps://github.com/rust\-lang/cargo#crates\-io@0.21.0\fR
 T}
 .TE
 .sp
@@ -195,7 +195,7 @@ cargo pkgid foo
 .sp
 .RS 4
 .nf
-cargo pkgid foo:1.0.0
+cargo pkgid foo@1.0.0
 .fi
 .RE
 .RE