Auto merge of #11586 - hds:ssh-known-hosts-doc-update, r=weihanglo

add documentation that SSH markers aren't supported

### What does this PR try to resolve?

Cargo doesn't support the ``@cert-authority`` or ``@revoked`` markers in SSH
Known Hosts files. The lines are silently ignored.

If a user is depending on these lines to connect to a Git server via
SSH, then their command line Git client will work, but Cargo will fail
with an error that the host key doesn't match.

This change adds a note explaining that Cargo doesn't support these
markers and suggests that the user change their cargo configuration to
fetch with the CLI client instead.

This PR fixes the first part (of 4) of the suggested tasks to fix #11577.

### How should we test and review this PR?

This change only modifies the Cargo book source. Running `mdbook build`
and checking the SSH Known Hosts section of the appendix on Git
authentication should be sufficient to test the PR.

### Additional information

The note in this section repeats what is said in the higher section on
SSH authentication, however given the recently implemented host key
checking, it seems worth calling out the limitation that Cargo doesn't
support these markers in the SSH known hosts file explicitly. Hopefully,
it reduces support requests and questions as well.

Author: bors

src/doc/src/appendix/git-authentication.md

@@ -81,6 +81,11 @@ publish their fingerprints on the web; for example GitHub posts theirs at
 Cargo comes with the host keys for [github.com](https://github.com) built-in.
 If those ever change, you can add the new keys to the config or known_hosts file.
 
+> **Note:** Cargo doesn't support the `@cert-authority` or `@revoked`
+> markers in `known_hosts` files. To make use of this functionality, use
+> [`net.git-fetch-with-cli`]. This is also a good tip if Cargo's SSH client
+> isn't behaving the way you expect it to.
+
 [`credential.helper`]: https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage
 [`net.git-fetch-with-cli`]: ../reference/config.md#netgit-fetch-with-cli
 [`net.ssh.known-hosts`]: ../reference/config.md#netsshknown-hosts