docs(ref): Try to improve reg auth docs

src/doc/src/reference/config.md

@@ -299,7 +299,11 @@ Cargo will search `PATH` for its executable.
 
 Configuration values with sensitive information are stored in the
 `$CARGO_HOME/credentials.toml` file. This file is automatically created and updated
-by [`cargo login`] and [`cargo logout`] when using the `cargo:token` credential provider.
+by [`cargo login`] and [`cargo logout`] when using the [`cargo:token`] credential provider.
+
+Tokens are used by some Cargo commands such as [`cargo publish`] for
+authenticating with remote registries. Care should be taken to protect the
+tokens and to keep them secret.
 
 It follows the same format as Cargo config files.
 
@@ -311,10 +315,6 @@ token = "…"   # Access token for crates.io
 token = "…"   # Access token for the named registry
 ```
 
-Tokens are used by some Cargo commands such as [`cargo publish`] for
-authenticating with remote registries. Care should be taken to protect the
-tokens and to keep them secret.
-
 As with most other config values, tokens may be specified with environment
 variables. The token for [crates.io] may be specified with the
 `CARGO_REGISTRY_TOKEN` environment variable. Tokens for other registries may
@@ -1320,6 +1320,7 @@ Sets the width for progress bar.
 [source replacement]: source-replacement.md
 [revision]: https://git-scm.com/docs/gitrevisions
 [registries]: registries.md
+[`cargo:token`]: registry-authentication.md#cargotoken
 [crates.io]: https://crates.io/
 [target triple]: ../appendix/glossary.md#target '"target" (glossary)'
 [`<triple>`]: ../appendix/glossary.md#target '"target" (glossary)'

src/doc/src/reference/registry-authentication.md

@@ -19,34 +19,18 @@ which defaults to:
 * Unix: `~/.cargo/config.toml`
 
 This recommended configuration uses the operating system provider, with a fallback to `cargo:token`
-to look in Cargo's [credentials](config.md#credentials) file or environment variables.
-
-Some private registries may also recommend a registry-specific credential-provider. Check your
-registry's documentation to see if this is the case.
-
-### macOS configuration
-```toml
-# ~/.cargo/config.toml
-[registry]
-global-credential-providers = ["cargo:token", "cargo:macos-keychain"]
-```
-
-### Linux (libsecret) configuration
+to look in Cargo's [credentials](config.md#credentials) file or environment variables:
 ```toml
 # ~/.cargo/config.toml
 [registry]
-global-credential-providers = ["cargo:token", "cargo:libsecret"]
+global-credential-providers = ["cargo:token", "cargo:libsecret", "cargo:macos-keychain", "cargo:wincred"]
 ```
-
-### Windows configuration
-```toml
-# %USERPROFILE%\.cargo\config.toml
-[registry]
-global-credential-providers = ["cargo:token", "cargo:wincred"]
-```
-
+*Note that later entries have higher precedence.
 See [`registry.global-credential-providers`](config.md#registryglobal-credential-providers)
-for more details.
+for more details.*
+
+Some private registries may also recommend a registry-specific credential-provider. Check your
+registry's documentation to see if this is the case.
 
 ## Built-in providers
 Cargo includes several built-in credential providers. The available built-in providers