From 645f2d88cee515e6309c9900622df7e9a2ff30f2 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Thu, 2 Nov 2023 12:13:18 -0500 Subject: [PATCH] docs(metadata): Stabilize id format as PackageIDSpec This makes it so you can take a package from `cargo metadata` and then pass it with the `--package` option without worrying about ambiguity. Fixes #7267 --- src/doc/man/cargo-metadata.md | 13 +++++++++---- src/doc/man/generated_txt/cargo-metadata.txt | 16 +++++++++++----- src/doc/src/commands/cargo-metadata.md | 13 +++++++++---- src/etc/man/cargo-metadata.1 | 10 ++++++++-- 4 files changed, 37 insertions(+), 15 deletions(-) diff --git a/src/doc/man/cargo-metadata.md b/src/doc/man/cargo-metadata.md index 74502e7f3d00..2b693fc6d4f6 100644 --- a/src/doc/man/cargo-metadata.md +++ b/src/doc/man/cargo-metadata.md @@ -34,8 +34,8 @@ considersed as incompatible: * **Adding new values for enum-like fields** — Same as adding new fields. It keeps metadata evolving without stagnation. * **Changing opaque representations** — The inner representations of some - fields are implementation details. For example, fields related to "Package ID" - or "Source ID" are treated as opaque identifiers to differentiate packages or + fields are implementation details. For example, fields related to + "Source ID" are treated as opaque identifiers to differentiate packages or sources. Consumers shouldn't rely on those representations unless specified. ### JSON format @@ -53,8 +53,8 @@ The JSON output has the following format: "name": "my-package", /* The version of the package. */ "version": "0.1.0", - /* The Package ID, an opaque and unique identifier for referring to the - package. See "Compatibility" above for the stability guarantee. + /* The Package ID for referring to the + package within the document and as the `--package` argument to many commands */ "id": "file:///path/to/my-package#0.1.0", /* The license value from the manifest, or null. */ @@ -331,6 +331,11 @@ The JSON output has the following format: } ```` +Notes: +- For `"id"` field syntax, see [Package ID Specifications] in the reference. + +[Package ID Specifications]: ../reference/pkgid-spec.html + ## OPTIONS ### Output Options diff --git a/src/doc/man/generated_txt/cargo-metadata.txt b/src/doc/man/generated_txt/cargo-metadata.txt index b51ecd8d2817..e4fc5151dffa 100644 --- a/src/doc/man/generated_txt/cargo-metadata.txt +++ b/src/doc/man/generated_txt/cargo-metadata.txt @@ -32,9 +32,9 @@ OUTPUT FORMAT o Changing opaque representations — The inner representations of some fields are implementation details. For example, fields related to - “Package ID” or “Source ID” are treated as opaque identifiers - to differentiate packages or sources. Consumers shouldn’t rely on - those representations unless specified. + “Source ID” are treated as opaque identifiers to differentiate + packages or sources. Consumers shouldn’t rely on those + representations unless specified. JSON format The JSON output has the following format: @@ -49,8 +49,8 @@ OUTPUT FORMAT "name": "my-package", /* The version of the package. */ "version": "0.1.0", - /* The Package ID, an opaque and unique identifier for referring to the - package. See "Compatibility" above for the stability guarantee. + /* The Package ID for referring to the + package within the document and as the `--package` argument to many commands */ "id": "file:///path/to/my-package#0.1.0", /* The license value from the manifest, or null. */ @@ -326,6 +326,12 @@ OUTPUT FORMAT } } + Notes: + + o For "id" field syntax, see Package ID Specifications + in the + reference. + OPTIONS Output Options --no-deps diff --git a/src/doc/src/commands/cargo-metadata.md b/src/doc/src/commands/cargo-metadata.md index aeeaf8534141..1a5d731bbd4c 100644 --- a/src/doc/src/commands/cargo-metadata.md +++ b/src/doc/src/commands/cargo-metadata.md @@ -34,8 +34,8 @@ considersed as incompatible: * **Adding new values for enum-like fields** — Same as adding new fields. It keeps metadata evolving without stagnation. * **Changing opaque representations** — The inner representations of some - fields are implementation details. For example, fields related to "Package ID" - or "Source ID" are treated as opaque identifiers to differentiate packages or + fields are implementation details. For example, fields related to + "Source ID" are treated as opaque identifiers to differentiate packages or sources. Consumers shouldn't rely on those representations unless specified. ### JSON format @@ -53,8 +53,8 @@ The JSON output has the following format: "name": "my-package", /* The version of the package. */ "version": "0.1.0", - /* The Package ID, an opaque and unique identifier for referring to the - package. See "Compatibility" above for the stability guarantee. + /* The Package ID for referring to the + package within the document and as the `--package` argument to many commands */ "id": "file:///path/to/my-package#0.1.0", /* The license value from the manifest, or null. */ @@ -331,6 +331,11 @@ The JSON output has the following format: } ```` +Notes: +- For `"id"` field syntax, see [Package ID Specifications] in the reference. + +[Package ID Specifications]: ../reference/pkgid-spec.html + ## OPTIONS ### Output Options diff --git a/src/etc/man/cargo-metadata.1 b/src/etc/man/cargo-metadata.1 index 1e48f5eb83bc..e67c9371a473 100644 --- a/src/etc/man/cargo-metadata.1 +++ b/src/etc/man/cargo-metadata.1 @@ -36,8 +36,8 @@ keeps metadata evolving without stagnation. .sp .RS 4 \h'-04'\(bu\h'+02'\fBChanging opaque representations\fR \[em] The inner representations of some -fields are implementation details. For example, fields related to \[lq]Package ID\[rq] -or \[lq]Source ID\[rq] are treated as opaque identifiers to differentiate packages or +fields are implementation details. For example, fields related to +\[lq]Source ID\[rq] are treated as opaque identifiers to differentiate packages or sources. Consumers shouldn\[cq]t rely on those representations unless specified. .RE .SS "JSON format" @@ -333,6 +333,12 @@ The JSON output has the following format: } .fi .RE +.sp +Notes: +.sp +.RS 4 +\h'-04'\(bu\h'+02'For \fB"id"\fR field syntax, see \fIPackage ID Specifications\fR in the reference. +.RE .SH "OPTIONS" .SS "Output Options" .sp