Skip to content

rustdoc URL conflict resolution #3097

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 3 commits into from
Closed

rustdoc URL conflict resolution #3097

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e4dc975
Initial draft for the rustdoc URL conflict resolution
GuillaumeGomez Mar 29, 2021
44d82ed
Add more details and more issues
GuillaumeGomez Mar 30, 2021
2158df6
Improve rendering and formulation
GuillaumeGomez Mar 30, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 74 additions & 0 deletions text/0000-rustdoc-url-conflicts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
- Feature Name: rustdoc_url_conflicts
- Start Date: 2021-03-29
- RFC PR: [rust-lang/rfcs#0000](https://github.com/rust-lang/rfcs/pull/0000)
- Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000)

# Summary
[summary]: #summary

This RFC describes how the rustdoc URLs will be modified to fix the current issue on case insensitive file systems.
For example, in the libstd there is:
* keyword.self.html
* keyword.Self.html

If macOS or Windows users try to access to both URLs, they will always see the same content because for both file systems, it's the same file.

# Motivation
[motivation]: #motivation

This is one of the oldest rustdoc issue and has been problematic for years and a lot of users. You can see that a few issues about it were opened:
* <https://github.com/rust-lang/rust/issues/25879>
* <https://github.com/rust-lang/rust/issues/39926>
* <https://github.com/rust-lang/rust/issues/46105>
* <https://github.com/rust-lang/rust/issues/51327>
* <https://github.com/rust-lang/rust/issues/76922>
* <https://github.com/rust-lang/rust/issues/80504>
* <https://github.com/rust-lang/rust/issues/83154> (and <https://github.com/rust-lang/rustup/issues/2694>)

# Guide-level explanation
[guide-level-explanation]: #guide-level-explanation

The idea here is to replace every capitalized letter in the item with `-[minimized capital]`. So for example, `enum.FooBar.html` will become `enum.-foo-bar.html`.
Copy link
Member

@scottmcm scottmcm Mar 29, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems really unfortunate that this would make even incredibly common things like struct.Vec.html have URLs that are materially worse (in my opinion).

Could it at least use a slightly more complicated scheme to take advantage of the usual rust naming conventions? Like have struct vec be the one that gets struct.-vec.html, since it's normal for structs to start with an upper-case letter, and let struct Vec continue to be struct.Vec.html?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, I don't think it's good that common types get affected by this

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That wouldn't help with cases where the case differs mid-identifier and could be valid either way struct FooBar; struct FoObar;.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand your point @Nemo157. It would be -fo-obar. It would prevent name conflict, which is the primary issue here.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was referring to @scottmcm's alternative.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh my bad. Then yes, I completely agree with you. :)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Nemo157 Yes, that's not a complete fix, as it'd still change struct.FooBar.html to struct.Foo-Bar.html or similar.

But I don't think we should break non-agglutinative names just because we have to break agglutinative ones.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, I guess my explanations are really bad... All capital letters are replaced by a dash followed by the lowercase version. So FooBar will become struct.-foo-bar.html. With this, no more conflicts.


# Reference-level explanation
[reference-level-explanation]: #reference-level-explanation

Multiple attempts were made but all of them had huge drawbacks. The last one suggested to handle "conflicted" paths by doing the following:
* Change name of conflicted files and store them somewhere else.
* Create one file which will then load the correct file based on the URL semantic.

There are multiple issues with this approach:
* It requires JS to work.
* It doesn't work on case-sensitive file systems (unless we make links to support all URLs but then it would be problematic on case-insensitive file systems).

Other approaches were discussed but their drawbacks were even bigger and more numerous. This approach seems to be the most viable.

# Drawbacks
[drawbacks]: #drawbacks

* It'll make the URL harder to read.
* It'll change the existing URLs (this is mostly an issue for blogs and external content not using rustdoc or old rust documentation not using intra-doc links)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a huge huge issue and I'm surprised we're taking this so lightly. I link to rustdoc pages in my writing at least once a week and usually once a day, there are millions of links out there.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It can be linked using rust version: https://doc.rust-lang.org/1.48.0/std/index.html

Fixing a 6 years problem seems more important to me. The important thing will be to communicate about this a lot.


# Rationale and alternatives
[rationale-and-alternatives]: #rationale-and-alternatives

The other alternatives require either JS to be enabled all the time or just don't work on both case-sensitive and case-insensitive file systems with the same generation process, forcing us to differentiate between both and make documentation generation case sensitivity-related.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please actually list these other alternatives and why they require JS to be enabled.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. I'll describe them a bit more and add yours.


# Prior art
[prior-art]: #prior-art

Like said previously, there were multiple attempts done before:
* <https://github.com/rust-lang/rust/pull/83612>
* <https://github.com/rust-lang/rust/pull/64699>
* <https://github.com/rust-lang/rust/pull/59785>
* <https://github.com/rust-lang/rust/pull/35020>

# Unresolved questions
[unresolved-questions]: #unresolved-questions

None.

# Future possibilities
[future-possibilities]: #future-possibilities

Maybe change the way we replace capitalized letters?