doc(yank): add section headers

Author: weihanglo

src/doc/man/cargo-yank.md

@@ -15,16 +15,18 @@ The yank command removes a previously published crate's version from the
 server's index. This command does not delete any data, and the crate will
 still be available for download via the registry's download link.
 
-Crates should only be yanked in exceptional circumstances, for example, license/copyright issues, accidental
-inclusion of [PII](https://en.wikipedia.org/wiki/Personal_data), credentials, etc... In the case of security
-vulnerabilities, [RustSec](https://rustsec.org/) is typically a less disruptive mechanism to inform users
-and encourage them to upgrade, and avoids the possibility of significant downstream disruption irrespective
-of susceptibility to the vulnerability in question.
-
 Cargo will not use a yanked version for any new project or checkout without a
 pre-existing lockfile, and will generate an error if there are no longer
 any compatible versions for your crate.
 
+This command requires you to be authenticated with either the `--token` option
+or using {{man "cargo-login" 1}}.
+
+If the crate name is not specified, it will use the package name from the
+current directory.
+
+### How yank works
+
 For example, the `foo` crate published version `0.22.0` and another crate `bar`
 declared a dependency on version `foo = 0.22`. Now `foo` releases a new, but
 not semver compatible, version `0.23.0`, and finds a critical issue with `0.22.0`.
@@ -46,14 +48,18 @@ following a given release being yanked:
 | `0.22.1`                            | Use either `0.22.0` or `0.22.2`           | Use `0.22.0`      | Use `0.23.0`     |
 | `0.23.0`                            | Use either `0.22.0`, `0.21.0` or `0.22.2` | Use `0.22.0`      | **Return Error** |
 
-A common workflow is to yank a crate having already published a semver compatible version,
-to reduce the probability of preventing dependent crates from compiling.
+### When to yank
 
-This command requires you to be authenticated with either the `--token` option
-or using {{man "cargo-login" 1}}.
+Crates should only be yanked in exceptional circumstances, for example,
+license/copyright issues, accidental inclusion of
+[PII](https://en.wikipedia.org/wiki/Personal_data), credentials, etc...
+In the case of security vulnerabilities, [RustSec](https://rustsec.org/) is
+typically a less disruptive mechanism to inform users and encourage them to
+upgrade, and avoids the possibility of significant downstream disruption
+irrespective of susceptibility to the vulnerability in question.
 
-If the crate name is not specified, it will use the package name from the
-current directory.
+A common workflow is to yank a crate having already published a semver compatible version,
+to reduce the probability of preventing dependent crates from compiling.
 
 ## OPTIONS
 

src/doc/man/generated_txt/cargo-yank.txt

@@ -13,19 +13,17 @@ DESCRIPTION
        crate will still be available for download via the registry’s download
        link.
 
-       Crates should only be yanked in exceptional circumstances, for example,
-       license/copyright issues, accidental inclusion of PII
-       <https://en.wikipedia.org/wiki/Personal_data>, credentials, etc... In
-       the case of security vulnerabilities, RustSec <https://rustsec.org/> is
-       typically a less disruptive mechanism to inform users and encourage them
-       to upgrade, and avoids the possibility of significant downstream
-       disruption irrespective of susceptibility to the vulnerability in
-       question.
-
        Cargo will not use a yanked version for any new project or checkout
        without a pre-existing lockfile, and will generate an error if there are
        no longer any compatible versions for your crate.
 
+       This command requires you to be authenticated with either the --token
+       option or using cargo-login(1).
+
+       If the crate name is not specified, it will use the package name from
+       the current directory.
+
+   How yank works
        For example, the foo crate published version 0.22.0 and another crate
        bar declared a dependency on version foo = 0.22. Now foo releases a new,
        but not semver compatible, version 0.23.0, and finds a critical issue
@@ -55,16 +53,20 @@ DESCRIPTION
        |                       | 0.21.0 or 0.22.2      | 0.22.0    | Error    |
        +-----------------------+-----------------------+-----------+----------+
 
+   When to yank
+       Crates should only be yanked in exceptional circumstances, for example,
+       license/copyright issues, accidental inclusion of PII
+       <https://en.wikipedia.org/wiki/Personal_data>, credentials, etc… In
+       the case of security vulnerabilities, RustSec <https://rustsec.org/> is
+       typically a less disruptive mechanism to inform users and encourage them
+       to upgrade, and avoids the possibility of significant downstream
+       disruption irrespective of susceptibility to the vulnerability in
+       question.
+
        A common workflow is to yank a crate having already published a semver
        compatible version, to reduce the probability of preventing dependent
        crates from compiling.
 
-       This command requires you to be authenticated with either the --token
-       option or using cargo-login(1).
-
-       If the crate name is not specified, it will use the package name from
-       the current directory.
-
 OPTIONS
    Yank Options
        --vers version, --version version

src/doc/src/commands/cargo-yank.md

@@ -15,16 +15,18 @@ The yank command removes a previously published crate's version from the
 server's index. This command does not delete any data, and the crate will
 still be available for download via the registry's download link.
 
-Crates should only be yanked in exceptional circumstances, for example, license/copyright issues, accidental
-inclusion of [PII](https://en.wikipedia.org/wiki/Personal_data), credentials, etc... In the case of security
-vulnerabilities, [RustSec](https://rustsec.org/) is typically a less disruptive mechanism to inform users
-and encourage them to upgrade, and avoids the possibility of significant downstream disruption irrespective
-of susceptibility to the vulnerability in question.
-
 Cargo will not use a yanked version for any new project or checkout without a
 pre-existing lockfile, and will generate an error if there are no longer
 any compatible versions for your crate.
 
+This command requires you to be authenticated with either the `--token` option
+or using [cargo-login(1)](cargo-login.html).
+
+If the crate name is not specified, it will use the package name from the
+current directory.
+
+### How yank works
+
 For example, the `foo` crate published version `0.22.0` and another crate `bar`
 declared a dependency on version `foo = 0.22`. Now `foo` releases a new, but
 not semver compatible, version `0.23.0`, and finds a critical issue with `0.22.0`.
@@ -46,14 +48,18 @@ following a given release being yanked:
 | `0.22.1`                            | Use either `0.22.0` or `0.22.2`           | Use `0.22.0`      | Use `0.23.0`     |
 | `0.23.0`                            | Use either `0.22.0`, `0.21.0` or `0.22.2` | Use `0.22.0`      | **Return Error** |
 
-A common workflow is to yank a crate having already published a semver compatible version,
-to reduce the probability of preventing dependent crates from compiling.
+### When to yank
 
-This command requires you to be authenticated with either the `--token` option
-or using [cargo-login(1)](cargo-login.html).
+Crates should only be yanked in exceptional circumstances, for example,
+license/copyright issues, accidental inclusion of
+[PII](https://en.wikipedia.org/wiki/Personal_data), credentials, etc...
+In the case of security vulnerabilities, [RustSec](https://rustsec.org/) is
+typically a less disruptive mechanism to inform users and encourage them to
+upgrade, and avoids the possibility of significant downstream disruption
+irrespective of susceptibility to the vulnerability in question.
 
-If the crate name is not specified, it will use the package name from the
-current directory.
+A common workflow is to yank a crate having already published a semver compatible version,
+to reduce the probability of preventing dependent crates from compiling.
 
 ## OPTIONS
 

src/etc/man/cargo-yank.1

@@ -14,16 +14,16 @@ The yank command removes a previously published crate\[cq]s version from the
 server\[cq]s index. This command does not delete any data, and the crate will
 still be available for download via the registry\[cq]s download link.
 .sp
-Crates should only be yanked in exceptional circumstances, for example, license/copyright issues, accidental
-inclusion of \fIPII\fR <https://en.wikipedia.org/wiki/Personal_data>, credentials, etc... In the case of security
-vulnerabilities, \fIRustSec\fR <https://rustsec.org/> is typically a less disruptive mechanism to inform users
-and encourage them to upgrade, and avoids the possibility of significant downstream disruption irrespective
-of susceptibility to the vulnerability in question.
-.sp
 Cargo will not use a yanked version for any new project or checkout without a
 pre\-existing lockfile, and will generate an error if there are no longer
 any compatible versions for your crate.
 .sp
+This command requires you to be authenticated with either the \fB\-\-token\fR option
+or using \fBcargo\-login\fR(1).
+.sp
+If the crate name is not specified, it will use the package name from the
+current directory.
+.SS "How yank works"
 For example, the \fBfoo\fR crate published version \fB0.22.0\fR and another crate \fBbar\fR
 declared a dependency on version \fBfoo = 0.22\fR\&. Now \fBfoo\fR releases a new, but
 not semver compatible, version \fB0.23.0\fR, and finds a critical issue with \fB0.22.0\fR\&.
@@ -80,15 +80,17 @@ T}:T{
 T}
 .TE
 .sp
+.SS "When to yank"
+Crates should only be yanked in exceptional circumstances, for example,
+license/copyright issues, accidental inclusion of
+\fIPII\fR <https://en.wikipedia.org/wiki/Personal_data>, credentials, etc\[u2026]
+In the case of security vulnerabilities, \fIRustSec\fR <https://rustsec.org/> is
+typically a less disruptive mechanism to inform users and encourage them to
+upgrade, and avoids the possibility of significant downstream disruption
+irrespective of susceptibility to the vulnerability in question.
 .sp
 A common workflow is to yank a crate having already published a semver compatible version,
 to reduce the probability of preventing dependent crates from compiling.
-.sp
-This command requires you to be authenticated with either the \fB\-\-token\fR option
-or using \fBcargo\-login\fR(1).
-.sp
-If the crate name is not specified, it will use the package name from the
-current directory.
 .SH "OPTIONS"
 .SS "Yank Options"
 .sp