Justification of html_root_url is missing nuance

[jyn514]

cc #75, @dtolnay

From rust-cli/env_logger#185:

The scenario where this goes wrong (assuming you're the author of env_logger and not using html_root_url) is:

1. Another downstream crate uses env_logger as a dependency
2. downstream re-exports or in some other way links to env_logger
3. A user or developer of downstream builds documentation locally with cargo doc --no-deps (without --extern-html-root-url, because in practice no one but docs.rs does that).

Then the links to env_logger will be broken. But there's a simple fix and the fix is to remove --no-deps. Is this really so common that it's worth recommending that library authors use html_root_url?

Note that I'm hoping to fix this properly in cargo instead: rust-lang/cargo#8296

[jyn514]

Note that this has nothing to do with docs.rs, docs.rs passes --extern-html-root-url which always overrides any html_root_url you declare yourself.

[BurntSushi]

I'm pretty sure this guideline was created in a time where not specifying html_root_url was more problematic than it is today. But I can't remember the details to be honest. I don't think I use it in any of my crates and I've never heard any complaints.

[jyn514]

Oh hmm - I think when it was originally written rustdoc didn't support --extern-html-root-url, so docs.rs did need it. But that's not the case any more.

Should I make a PR removing the recommendation?

[jyn514]

Oh heh - it has a comment pointing to rust-lang/rust#42301, which I closed as wontfix a few days ago.

[BurntSushi]

Oh hmm - I think when it was originally written rustdoc didn't support --extern-html-root-url, so docs.rs did need it. But that's not the case any more.

Should I make a PR removing the recommendation?

I'm not even sure docs.rs was even around back then. But I can't remember. :)

[jhpratt]

For what it's worth I'm fairly certain most crates (including all of mine) don't use this attribute, and I have never had an issue with links not working exactly as expected.

[KodrAus]

Sounds like we should remove the recommendation then! It's a bit of a footgun that we don't need anymore.

[KodrAus]

Actually, since we have just been talking about the way we make decisions on this repo I should try actually follow what we set out and kick off an FCP!