Clearly state that BROWSER is an exception in terms of precedence

[iampi31415]

In the section titled Environment Variables (second paragraph), it says (bold is mine, for emphasis):

Cargo can also be configured through environment variables in addition to the TOML configuration files. For each configuration key of the form foo.bar the environment variableCARGO_FOO_BAR can also be used to define the value. Keys are converted to uppercase, dots and dashes are converted to underscores. For example the target.x86_64-unknown-linux-gnu.runner key can also be defined by the CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUNNER environment variable.

Environment variables will take precedence over TOML configuration files. Currently only integer, boolean, string and some array values are supported to be defined by environment variables. Descriptions below indicate which keys support environment variables and otherwise they are not supported due to technical issues.

In addition to the system above, Cargo recognizes a few other specific environment variables.

---

Yet an example further down says:

[doc]
browser = "chromium"          # browser to use with `cargo doc --open`,
                              # overrides the `BROWSER` environment variable

So in this case it does not precede the environmental variable, and the paragraph at the top of this issue should instead say:

Environment variables will take precedence over TOML configuration files (with the exception of BROWSER).

Or something similar.

[weihanglo]

Environment variables will take precedence over TOML configuration files.

Nice finding, though this specifically talks about environment variable that Cargo would automatically pick along with the corresponding config field, e.g., CARGO_BUILD_TAETET is associated with build.target, and CARGO_HTTP_DEBUG is with http.debug.

That said, I think we should not talk about individual config in the overview. The doc.browser config is explained in its specific section. To address the confusion, I propose we remove the second half of the sentence.

[iampi31415]

As you said, that paragraph isn't for all config options:

this specifically talks about environment variable that Cargo would automatically pick along with the corresponding config field

But the section is called "Environment Variables", and so two distinct paragraphs seem two separate statements, not necessarily dependent on each other.

My vote is more for adding a further clarification that the first paragraph isn't for all environmental variables but only for those translating in a specific way. And to leave the remaining sentence (is it only for those starting with CARGO_?), which fits the title section.

Another option is to rename the section but that seems harder.

PS: I added the two paragraphs in OP to make it easier to check, for anyone else reading this.

[weihanglo]

BROWSER is not the only exception btw

[weihanglo]

So some action items:

1. Remove BROWSER from the example TOML.
2. Change to a better section title, for example, "configure via environment variable".
3. Clarify in the paragraph a bit it is only for config field to env var translation.

[iampi31415]

Not sure if that's for me to reply? I'd prefer 3. as said before.

My initial suggestion would be (bold only for emphasis):

Environment variables will take precedence over TOML configuration files. Note that this refers only to the subset of options that the procedure above applies to. It does not include BROWSER, TERM and other variables. Currently only integer, boolean, string and some array values are supported to be defined by environment variables. Descriptions below indicate which keys support environment variables and otherwise they are not supported due to #5416.