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 rust-lang#7267

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

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
+          <https://doc.rust-lang.org/cargo/reference/pkgid-spec.html> in the
+          reference.
+
 OPTIONS
    Output Options
        --no-deps

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

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 <https://doc.rust\-lang.org/cargo/reference/pkgid\-spec.html> in the reference.
+.RE
 .SH "OPTIONS"
 .SS "Output Options"
 .sp