docs: more links to JSON messages

rust-lang · Jan 17, 2024 · 273168c · 273168c
1 parent 261100c
commit 273168c
Show file tree

Hide file tree

Showing 8 changed files with 43 additions and 22 deletions.
diff --git a/src/doc/man/cargo-metadata.md b/src/doc/man/cargo-metadata.md
@@ -334,8 +334,6 @@ 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
@@ -393,6 +391,8 @@ reproduction of the information within `Cargo.toml`.
        cargo metadata --format-version=1
 
 ## SEE ALSO
-{{man "cargo" 1}}, {{man "cargo-pkgid" 1}}, [Package ID Specifications]
+
+{{man "cargo" 1}}, {{man "cargo-pkgid" 1}}, [Package ID Specifications], [JSON messages]
 
 [Package ID Specifications]: ../reference/pkgid-spec.html
+[JSON messages]: ../reference/external-tools.html#json-messages
diff --git a/src/doc/man/cargo-pkgid.md b/src/doc/man/cargo-pkgid.md
@@ -21,8 +21,10 @@ fetched.
 
 A package specifier consists of a name, version, and source URL. You are
 allowed to use partial specifiers to succinctly match a specific package as
-long as it matches only one package. The format of a _spec_ can be one of the
-following:
+long as it matches only one package. This specifier is also used by other parts
+in Cargo, such as {{man "cargo-metadata" 1}} and [JSON messages] emitted by Cargo.
+
+The format of a _spec_ can be one of the following:
 
 SPEC Structure             | Example SPEC
 ---------------------------|--------------
@@ -88,6 +90,9 @@ Get the package ID for the given package instead of the current package.
        cargo pkgid file:///path/to/local/package#foo
 
 ## SEE ALSO
-{{man "cargo" 1}}, {{man "cargo-generate-lockfile" 1}}, {{man "cargo-metadata" 1}}, [Package ID Specifications]
+
+{{man "cargo" 1}}, {{man "cargo-generate-lockfile" 1}}, {{man "cargo-metadata" 1}},
+[Package ID Specifications], [JSON messages]
 
 [Package ID Specifications]: ../reference/pkgid-spec.html
+[JSON messages]: ../reference/external-tools.html#json-messages
diff --git a/src/doc/man/generated_txt/cargo-metadata.txt b/src/doc/man/generated_txt/cargo-metadata.txt
@@ -483,5 +483,7 @@ EXAMPLES
 
 SEE ALSO
        cargo(1), cargo-pkgid(1), Package ID Specifications
-       <https://doc.rust-lang.org/cargo/reference/pkgid-spec.html>
+       <https://doc.rust-lang.org/cargo/reference/pkgid-spec.html>, JSON
+       messages
+       <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages>
 
diff --git a/src/doc/man/generated_txt/cargo-pkgid.txt b/src/doc/man/generated_txt/cargo-pkgid.txt
@@ -18,8 +18,12 @@ DESCRIPTION
 
        A package specifier consists of a name, version, and source URL. You are
        allowed to use partial specifiers to succinctly match a specific package
-       as long as it matches only one package. The format of a spec can be one
-       of the following:
+       as long as it matches only one package. This specifier is also used by
+       other parts in Cargo, such as cargo-metadata(1) and JSON messages
+       <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages>
+       emitted by Cargo.
+
+       The format of a spec can be one of the following:
 
        +-----------------+--------------------------------------------------+
        | SPEC Structure  | Example SPEC                                     |
@@ -172,5 +176,7 @@ EXAMPLES
 SEE ALSO
        cargo(1), cargo-generate-lockfile(1), cargo-metadata(1), Package ID
        Specifications
-       <https://doc.rust-lang.org/cargo/reference/pkgid-spec.html>
+       <https://doc.rust-lang.org/cargo/reference/pkgid-spec.html>, JSON
+       messages
+       <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages>
 
diff --git a/src/doc/src/commands/cargo-metadata.md b/src/doc/src/commands/cargo-metadata.md
@@ -334,8 +334,6 @@ 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
@@ -512,6 +510,8 @@ details on environment variables that Cargo reads.
        cargo metadata --format-version=1
 
 ## SEE ALSO
-[cargo(1)](cargo.html), [cargo-pkgid(1)](cargo-pkgid.html), [Package ID Specifications]
+
+[cargo(1)](cargo.html), [cargo-pkgid(1)](cargo-pkgid.html), [Package ID Specifications], [JSON messages]
 
 [Package ID Specifications]: ../reference/pkgid-spec.html
+[JSON messages]: ../reference/external-tools.html#json-messages
diff --git a/src/doc/src/commands/cargo-pkgid.md b/src/doc/src/commands/cargo-pkgid.md
@@ -21,8 +21,10 @@ fetched.
 
 A package specifier consists of a name, version, and source URL. You are
 allowed to use partial specifiers to succinctly match a specific package as
-long as it matches only one package. The format of a _spec_ can be one of the
-following:
+long as it matches only one package. This specifier is also used by other parts
+in Cargo, such as [cargo-metadata(1)](cargo-metadata.html) and [JSON messages] emitted by Cargo.
+
+The format of a _spec_ can be one of the following:
 
 SPEC Structure             | Example SPEC
 ---------------------------|--------------
@@ -183,6 +185,9 @@ details on environment variables that Cargo reads.
        cargo pkgid file:///path/to/local/package#foo
 
 ## SEE ALSO
-[cargo(1)](cargo.html), [cargo-generate-lockfile(1)](cargo-generate-lockfile.html), [cargo-metadata(1)](cargo-metadata.html), [Package ID Specifications]
+
+[cargo(1)](cargo.html), [cargo-generate-lockfile(1)](cargo-generate-lockfile.html), [cargo-metadata(1)](cargo-metadata.html),
+[Package ID Specifications], [JSON messages]
 
 [Package ID Specifications]: ../reference/pkgid-spec.html
+[JSON messages]: ../reference/external-tools.html#json-messages
diff --git a/src/etc/man/cargo-metadata.1 b/src/etc/man/cargo-metadata.1
@@ -55,8 +55,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. */
@@ -529,4 +529,4 @@ cargo metadata \-\-format\-version=1
 .RE
 .RE
 .SH "SEE ALSO"
-\fBcargo\fR(1), \fBcargo\-pkgid\fR(1), \fIPackage ID Specifications\fR <https://doc.rust\-lang.org/cargo/reference/pkgid\-spec.html>
+\fBcargo\fR(1), \fBcargo\-pkgid\fR(1), \fIPackage ID Specifications\fR <https://doc.rust\-lang.org/cargo/reference/pkgid\-spec.html>, \fIJSON messages\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages>
diff --git a/src/etc/man/cargo-pkgid.1 b/src/etc/man/cargo-pkgid.1
@@ -19,8 +19,10 @@ fetched.
 .sp
 A package specifier consists of a name, version, and source URL. You are
 allowed to use partial specifiers to succinctly match a specific package as
-long as it matches only one package. The format of a \fIspec\fR can be one of the
-following:
+long as it matches only one package. This specifier is also used by other parts
+in Cargo, such as \fBcargo\-metadata\fR(1) and \fIJSON messages\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages> emitted by Cargo.
+.sp
+The format of a \fIspec\fR can be one of the following:
 
 .TS
 allbox tab(:);
@@ -242,4 +244,5 @@ cargo pkgid file:///path/to/local/package#foo
 .RE
 .RE
 .SH "SEE ALSO"
-\fBcargo\fR(1), \fBcargo\-generate\-lockfile\fR(1), \fBcargo\-metadata\fR(1), \fIPackage ID Specifications\fR <https://doc.rust\-lang.org/cargo/reference/pkgid\-spec.html>
+\fBcargo\fR(1), \fBcargo\-generate\-lockfile\fR(1), \fBcargo\-metadata\fR(1),
+\fIPackage ID Specifications\fR <https://doc.rust\-lang.org/cargo/reference/pkgid\-spec.html>, \fIJSON messages\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages>