From e4dc975711259d3266fd93a0b51c1250447ca300 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Mon, 29 Mar 2021 22:46:01 +0200 Subject: [PATCH 1/3] Initial draft for the rustdoc URL conflict resolution --- text/0000-rustdoc-url-conflicts.md | 65 ++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 text/0000-rustdoc-url-conflicts.md diff --git a/text/0000-rustdoc-url-conflicts.md b/text/0000-rustdoc-url-conflicts.md new file mode 100644 index 00000000000..b6bd837fa27 --- /dev/null +++ b/text/0000-rustdoc-url-conflicts.md @@ -0,0 +1,65 @@ +- 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. + +# 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`. + +# 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. + +# 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. + +# 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 + +# Unresolved questions +[unresolved-questions]: #unresolved-questions + +None. + +# Future possibilities +[future-possibilities]: #future-possibilities + +Maybe change the way we replace capitalized letters? From 44d82ed11fa6e93016e09f15c5155e1347a93178 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Tue, 30 Mar 2021 10:56:31 +0200 Subject: [PATCH 2/3] Add more details and more issues --- text/0000-rustdoc-url-conflicts.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/text/0000-rustdoc-url-conflicts.md b/text/0000-rustdoc-url-conflicts.md index b6bd837fa27..c4f416eeca0 100644 --- a/text/0000-rustdoc-url-conflicts.md +++ b/text/0000-rustdoc-url-conflicts.md @@ -16,7 +16,14 @@ If macOS or Windows users try to access to both URLs, they will always see the s # Motivation [motivation]: #motivation -This is one of the oldest rustdoc issue and has been problematic for years and a lot of users. +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 @@ -39,12 +46,13 @@ Other approaches were discussed but their drawbacks were even bigger and more nu # Drawbacks [drawbacks]: #drawbacks -It'll make the URL harder to read. + * It'll make the URL harder to read. + * It'll change the existing URLs (this drawback has to take into account that rustdoc now has intra-doc links and that old documentation versions with the previous URL scheme will remain available). # 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. +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. # Prior art [prior-art]: #prior-art @@ -53,6 +61,7 @@ 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 From 2158df625c7242dbedbf3477055bedade58df666 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Tue, 30 Mar 2021 13:51:13 +0200 Subject: [PATCH 3/3] Improve rendering and formulation --- text/0000-rustdoc-url-conflicts.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/text/0000-rustdoc-url-conflicts.md b/text/0000-rustdoc-url-conflicts.md index c4f416eeca0..a3778fcb840 100644 --- a/text/0000-rustdoc-url-conflicts.md +++ b/text/0000-rustdoc-url-conflicts.md @@ -17,13 +17,13 @@ If macOS or Windows users try to access to both URLs, they will always see the s [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) + * + * + * + * + * + * + * (and ) # Guide-level explanation [guide-level-explanation]: #guide-level-explanation @@ -47,7 +47,7 @@ Other approaches were discussed but their drawbacks were even bigger and more nu [drawbacks]: #drawbacks * It'll make the URL harder to read. - * It'll change the existing URLs (this drawback has to take into account that rustdoc now has intra-doc links and that old documentation versions with the previous URL scheme will remain available). + * 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) # Rationale and alternatives [rationale-and-alternatives]: #rationale-and-alternatives @@ -58,10 +58,10 @@ The other alternatives require either JS to be enabled all the time or just don' [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