From 667ab2cf58a037ceb4922b47ac3cd9300eddeb14 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 | 9 +++++++-- src/doc/man/generated_txt/cargo-metadata.txt | 12 +++++++++--- src/doc/src/commands/cargo-metadata.md | 9 +++++++-- src/etc/man/cargo-metadata.1 | 10 ++++++++-- 4 files changed, 31 insertions(+), 9 deletions(-) diff --git a/src/doc/man/cargo-metadata.md b/src/doc/man/cargo-metadata.md index 46030292a53d..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 @@ -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 376b4c3e932d..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: @@ -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 e014218bca4a..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 @@ -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 697096127328..69cc9e873f7a 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