From 709f1be20807cadbb6eaae2c3afcd6de65814f08 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 26 Apr 2022 14:11:00 -0500 Subject: [PATCH] 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. --- src/doc/man/cargo-pkgid.md | 6 +++--- src/doc/man/generated_txt/cargo-pkgid.txt | 6 +++--- src/doc/src/commands/cargo-pkgid.md | 6 +++--- src/doc/src/reference/pkgid-spec.md | 14 +++++++------- src/etc/man/cargo-pkgid.1 | 8 ++++---- 5 files changed, 20 insertions(+), 20 deletions(-) diff --git a/src/doc/man/cargo-pkgid.md b/src/doc/man/cargo-pkgid.md index 1fb9a60efc7..761eede1dce 100644 --- 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 index 1f6cfa1e183..41ea578d19e 100644 --- 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 index 0009f53437b..a6bf95f34ea 100644 --- 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 index 7ac32bf0e4b..6c11b4b3d58 100644 --- 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` | `cargo-platform` | `0.1.2` | -| `ssh://git@github.com/rust-lang/regex.git#regex:1.4.3` | `regex` | `1.4.3` | +| `https://github.com/rust-lang/cargo#cargo-platform@0.1.2` | `cargo-platform` | `0.1.2` | +| `ssh://git@github.com/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 index 67ed66f0b1c..789565c9ec0 100644 --- 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