Add a doc.browser config option

[lf-]

The idea of this option is to allow cargo to use a separate browser from
the rest of the system. My motivation in doing this is that I want to
write a script that adds a symbolic link in some web root on my system
such that I can access my docs via the http protocol to avoid the
limitations of the file protocol that are accessibility problems for me.
For instance, zoom is not retained across multiple pages and Stylus
filters don't work well.

[rust-highfive]

r? @ehuss

(rust-highfive has picked a reviewer for you, use r? to override)

[ehuss]

I think this seems reasonable. I had a concern about the config name. There is already a doc table, and I think it may be confusing to have both doc and cargo-doc. I think I would lean towards having a single table, and probably with the name doc, though I'd like to hear what the team says.

@rust-lang/cargo This proposes to add a new config variable to set the browser used with cargo doc. This can currently be set by the BROWSER environment variable, but this config will override that. I think it should be fine for this to be insta-stable, since it is such a small change.

@rfcbot merge

[rfcbot]

Team member @ehuss has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Eh2406
• @alexcrichton
• @ehuss
• @joshtriplett

Concerns:

• doc-vs-cargo-doc resolved by Add a doc.browser config option #9473 (comment)
• PathAndArgs resolved by Add a doc.browser config option #9473 (comment)

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[ehuss]

@rfcbot concern PathAndArgs

[ehuss]

@rfcbot concern doc-vs-cargo-doc

[lf-]

I think this seems reasonable. I had a concern about the config name. There is already a doc table, and I think it may be confusing to have both doc and cargo-doc. I think I would lean towards having a single table, and probably with the name doc, though I'd like to hear what the team says.

I wasn't aware. I don't see one in the configuration reference in the docs, having looked just now. Is this part of some nightly option or missing from the docs?

I'm thinking this should maybe be PathAndArgs, so that there is some consistency with other config options that specify executables to run.

No disagreement with that from me, that would be a good idea. Should it also be applied to the existing BROWSER environment variable?

[ehuss]

Is this part of some nightly option

Yea, it is currently unstable, documented here: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#rustdoc-map

Should it also be applied to the existing BROWSER environment variable?

Hm, I don't have much of an opinion here. I guess that is how $BROWSER usually works with xdg-open? (Though $BROWSER can also use $IFS, let's ignore that 😉 )

[lf-]

Alright, I've chosen not to do it to BROWSER also since it would introduce a regression on the handling of non unicode BROWSER values as I don't think I can split those at a space, so I'd have to convert it to Unicode lossily.

[ehuss]

Seems fine, we can always tweak the BROWSER env var behavior in the future if needed.

@rfcbot resolve PathAndArgs

[ehuss]

@rfcbot resolve doc-vs-cargo-doc

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[ehuss]

Thanks!

@bors r+

[bors]

📌 Commit 6128b54 has been approved by ehuss

[bors]

⌛ Testing commit 6128b54 with merge f898eff...

[bors]

☀️ Test successful - checks-actions
Approved by: ehuss
Pushing f898eff to master...