Auto merge of #7694 - danielparks:issue-7691-manifest-badges-section, r=ehuss

Clarify manifest format docs for [badges] section

Previously the `[badges]` section documentation was mixed in with the `[package]` section. This extracts it out under its own heading.

This also pulls the `license` and `license-file` field documentation out of the package metadata code block. It sets the example license to “MIT OR Apache-2.0” since that is the typical licensing scheme for many crates.

This includes minor rewrites for clarity and to match the register of the rest of the document.

This resolves issue #7691.

Author: bors

src/doc/src/reference/manifest.md

@@ -221,6 +221,34 @@ workspace = "path/to/workspace/root"
 
 For more information, see the documentation for the workspace table below.
 
+#### The `license` and `license-file` fields (optional)
+
+The `license` field can be set to an [SPDX 2.1 license
+expression][spdx-2.1-license-expressions] for the package. Currently crates.io
+will validate the license provided against a whitelist of known license and
+exception identifiers from the [SPDX license list 3.6][spdx-license-list-3.6].
+Parentheses are not currently supported.
+
+Previously multiple licenses could be separated with a `/`, but that usage is
+deprecated. Instead, use a license expression with AND and OR operators to get
+more explicit semantics.
+
+```toml
+[package]
+# ...
+license = "MIT OR Apache-2.0"
+```
+
+If a package is using a nonstandard license, then the `license-file` field may
+be specified in lieu of the `license` field. It must point to a file relative to
+this manifest (similar to the `readme` field).
+
+```toml
+[package]
+# ...
+license-file = "..."
+```
+
 #### Package metadata
 
 There are a number of optional metadata fields also accepted under the
@@ -255,35 +283,31 @@ keywords = ["...", "..."]
 # Categories are a fixed list available at crates.io/category_slugs, and
 # they must match exactly.
 categories = ["...", "..."]
+```
 
-# This is an SPDX 2.1 license expression for this package. Currently
-# crates.io will validate the license provided against a whitelist of
-# known license and exception identifiers from the SPDX license list
-# 3.6. Parentheses are not currently supported.
-#
-# Multiple licenses can be separated with a `/`, although that usage
-# is deprecated. Instead, use a license expression with AND and OR
-# operators to get more explicit semantics.
-license = "..."
-
-# If a package is using a nonstandard license, then this key may be specified in
-# lieu of the above key and must point to a file relative to this manifest
-# (similar to the readme key).
-license-file = "..."
+The [crates.io](https://crates.io) registry will render the description, display
+the license, link to the three URLs and categorize by the keywords. These keys
+provide useful information to users of the registry and also influence the
+search ranking of a crate. It is highly discouraged to omit everything in a
+published crate.
+
+### The `[badges]` section
+
+crates.io can display various badges for build status, test coverage, etc. for
+each crate. All badges are optional.
+
+- The badges pertaining to build status that are currently available are
+  Appveyor, CircleCI, Cirrus CI, GitLab, Azure DevOps, Travis CI and Bitbucket
+  Pipelines.
+- Available badges pertaining to code test coverage are Codecov and Coveralls.
+- There are also maintenance-related badges based on isitmaintained.com
+  which state the issue resolution time, percent of open issues, and future
+  maintenance intentions.
+
+Most badge specifications require a `repository` key. It is expected to be in
+`user/repo` format.
 
-# Optional specification of badges to be displayed on crates.io.
-#
-# - The badges pertaining to build status that are currently available are
-#   Appveyor, CircleCI, Cirrus CI, GitLab, Azure DevOps, Travis CI and Bitbucket
-#   Pipelines.
-# - Available badges pertaining to code test coverage are Codecov and
-#   Coveralls.
-# - There are also maintenance-related badges based on isitmaintained.com
-#   which state the issue resolution time, percent of open issues, and future
-#   maintenance intentions.
-#
-# If a `repository` key is required, this refers to a repository in
-# `user/repo` format.
+```toml
 [badges]
 
 # Appveyor: `repository` is required. `branch` is optional; default is `master`
@@ -346,17 +370,6 @@ is-it-maintained-open-issues = { repository = "..." }
 maintenance = { status = "..." }
 ```
 
-The [crates.io](https://crates.io) registry will render the description, display
-the license, link to the three URLs and categorize by the keywords. These keys
-provide useful information to users of the registry and also influence the
-search ranking of a crate. It is highly discouraged to omit everything in a
-published crate.
-
-SPDX 2.1 license expressions are documented
-[here][spdx-2.1-license-expressions]. The current version of the
-license list is available [here][spdx-license-list], and version 3.6
-is available [here][spdx-license-list-3.6].
-
 #### The `metadata` table (optional)
 
 Cargo by default will warn about unused keys in `Cargo.toml` to assist in
@@ -946,4 +959,3 @@ dependencies][replace] section of the documentation.
 [`cargo test`]: ../commands/cargo-test.md
 [spdx-2.1-license-expressions]: https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60
 [spdx-license-list-3.6]: https://github.com/spdx/license-list-data/tree/v3.6
-[spdx-license-list]: https://spdx.org/licenses/