Stream: rustdoc

Topic: case insensitive RFC rust-lang/rfcs#3097


view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:28):

Hey @GuillaumeGomez @Joshua Nelson perhaps we should chat here?

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:29):

Firstly I think the RFC is super incomplete as it stands; an RFC is a work of technical communication and in its status quo it communicates very little

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:29):

but i think we should discuss this as a team and perhaps draft an RFC together

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:29):

i mean it's fine if you want to write your own RFC but right now i'm going to have a very hard time supporting it, and I think core might have an opinion on the breakage too (which it gets to, because this is a product concern), so you'd need to convince core that this is okay

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:30):

and i don't think discussing this over the rfc is productive

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:30):

but i can explain my stance better here

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 15:34):

Ah right, we were discussing it on discord with kinnison. But things were a bit too rushed I think... We were very happy about the solution we came up with haha

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 15:34):

So I definitely agree to draft a RFC together

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:37):

Wanna go ahead and close it?

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:37):

I can hackmd a draft

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:37):

it will be incomplete

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 15:37):

Well writing a draft or anything, we have to agree on what to propose, no?

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 15:38):

because I don't agree with the solution you suggested

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 15:38):

Closing the RFC in the meatime.

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:38):

Right

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:38):

I meant that I would draft it up so that we can discuss it better

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:39):

But okay, can you dig into why you disagree with my solution?

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:39):

Because so far it seems like you have assumed it works like your previous PR and it doesn't

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:39):

I can explain it better if you'd like

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 15:39):

Please do :)

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 15:48):

If the solution you're talking about is the disambiguator, as I understood it, you provide a simple file which contains link to the items. However, this file cannot cover all the original items' URL on case sensitive FS, it would be only on case insensitive FS

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:48):

No my solution is more nuanced

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:49):

My solution enables us to _not have to come up with a perfect solution_

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:49):

Okay so the basic principle behind my proposal is that clashes are _bad_ and should be avoided. Rustdoc will handle clashes _sensibly_, but not _perfectly_.

We provide #[doc(filename = "FooBarBaz")] so that people can fix clashes. This makes the filename struct.FooBarBaz.html (we can also compiler error if you use doc(filename) to introduce a _new_ clash)

We lint about clashes, and mention the downsides. The downsides include that the URL might not be stable if other clashes are introduced or removed.

Now, crates with clashes are nudged towards using doc(filename). Great! This means we can try to handle them sensibly but not perfectly.

My "sensible" handling is this. Assume we have foo, Foo, and FOO as structs

This is unstable, but we are warning users about the instability. Their docs are broken already, so this does not make them _more_ broken. Some of their links will be broken, but again, they were kinda broken already.

This has tightly scoped impact, which is really nice.

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 15:50):

Ok, so I understood it correctly. So you suggest to ask users to go around rustdoc limitations because you don't want the URL scheme to be changed. I really can't agree with that :-/

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 15:51):

Also, it would be incoherent between case sensitive and insensitive FS

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 15:52):

the first one would only get access to "struct.Foo.html" whereas the other would have access to all the original URLs (even though it only bring to the disambiguator file)

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:54):

Wait why would it be incoherent between filesystems? The filenames are all different

view this post on Zulip Joshua Nelson (Mar 30 2021 at 15:54):

GuillaumeGomez said:

the first one would only get access to "struct.Foo.html" whereas the other would have access to all the original URLs (even though it only bring to the disambiguator file)

I think @Manish Goregaokar is suggesting that we only generate struct.Foo.html, not struct.foo.html

view this post on Zulip Joshua Nelson (Mar 30 2021 at 15:54):

which is a slight regression from the perspective of case-sensitive file systems, but seems ok to me if it fixes other problems

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:54):

I don't htink it's a workaround either! I think this is the right fix -- I would rather have _users_ figure out how best to disambiguate than have _us_ randomply pick a scheme

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:55):

like the current proposal _also_ is a workaround -- it picks an arbitrary scheme for disambiguation -- this gives the user control over how to disambiguate

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:55):

this isn't a rustdoc limitation, this is a limitation of case insensitive FS. Either rustdoc works around it by picking an arbitrary scheme, or we let users have the power to decide how to fix it (and we provide a _sensible_ but not _perfect_ default)

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:56):

Also, it's not just "you don't want the URL scheme to be changed"; I think a _lot_ of people don't, and I think we should start considering this as a hard boundary because I'm like 50% sure core will want to get involved if there are breakages like this.

view this post on Zulip Joshua Nelson (Mar 30 2021 at 15:57):

Manish Goregaokar said:

Also, it's not just "you don't want the URL scheme to be changed"; I think a _lot_ of people don't, and I think we should start considering this as a hard boundary because I'm like 50% sure core will want to get involved if there are breakages like this.

I mean, this makes sense and I believe you, but it makes me really frustrated because the current URL scheme was never intended to be stable :/

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:57):

I'm taking it as a hard constraint because I know that Rust cares a lot about stability and docs and I think multiple core team members, multiple devtools team members, and many others would be against this

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:57):

@Joshua Nelson Yeah I'm frustrated too, but I think breaking links across the internet is a huge concern

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:58):

Unfortunately when rust stabilized rustdoc did not get much love

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:58):

we work with what we have

view this post on Zulip Joshua Nelson (Mar 30 2021 at 15:58):

don't I know it lol

view this post on Zulip Joshua Nelson (Mar 30 2021 at 15:59):

/me goes back to vainly trying to make get_blanket_impls faster

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 15:59):

I think improving the scheme is on the table with redirects and such

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:03):

Manish Goregaokar said:

Wait why would it be incoherent between filesystems? The filenames are all different

They are, but foo.html, Foo.html and FOO.html are all the same on case insensitive FS

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:04):

Any solution we came up with until now makes the situation on case sensitive FS worse. I don't see how we can justify that

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:05):

@GuillaumeGomez we would not generate those three files, only one

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:05):

Please read the proposal again

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:06):

And I repeat once again

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:06):

Name them struct.foo-1.html, struct.Foo-2.html, struct.FOO-3.html

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:06):

Generate struct.Foo.html (in Titlecase because it is a struct). All it does is have three links in it saying "Foo can refer to foo, Foo, or FOO". No JS.

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:06):

those are the four files we generate

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:06):

when you access the URL struct.Foo.html or struct.FOO.html on case insensitive FS, it's the same file

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:06):

I know

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:06):

which isn't the same on case sensitive FS

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:07):

I don't see the problem

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:07):

so if we create a disambiguator file instead of having the original files, it means some URLs will stop working

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:07):

for crates which were broken already -- i don't see the problem

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:07):

but only on case sensitive FS (they will still work on case insensitive FS)

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:07):

again, i don't see the problem, they were broken already

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:08):

they were broken ONLY on case insensitive, not on case sensitive

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:08):

okay, fair

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:08):

you are just reverting the issue

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:08):

that seems like a minor concern? Your proposal breaks URLs for _everyone_. Mine breaks URLs for folks who were somewhat broken arleady

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:08):

And we warn about it so that they can choose the best solution that works for them

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:08):

personally I object to calling this breaking the URL

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:09):

except in the sense of "rustdoc can't change URLs because apparently the path itself is stable by accident"

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:09):

there's no links to it, there's no conflicts

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:09):

It's changing the scheme and fixing the current conflitcs, not breaking URLs

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:09):

???

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:09):

yeah for local FS stuff there are no links either

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:10):

but linux is sensitive so most hosted docs are also sensitive

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:10):

Manish Goregaokar said:

yeah for local FS stuff there are no links either

there are absolutely links to it, rustdoc generates the links

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:10):

they're just within the doc instead of external

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:10):

euh no, linux is sensitive ;)

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:10):

sorry mistype

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:10):

let's game this out

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:11):

let's say you have foo Foo and FOO

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:11):

previously there were three files on linux

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:11):

and it was broken on mac/win

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:11):

and only one on windows

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:11):

(and mac)

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:12):

(because they overwrite each others as you may have guessed)

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:13):

with my change, you have struct.Foo.html _only_ on linux (as I said, we should generate the disambiguation page in titlecase for structs, but we could also do lowercase), and plus foo-1 Foo-2 and FOO-3.
mac/win are unbroken

the breakage is that old links to struct.foo and struct.FOO are broken

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:13):

that seems exceedingly minor compared to breaking all the links, no?

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:13):

no, it's exactly the same problem

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:14):

you just reverted it and generated one extra file

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:14):

I don't understand why you say that

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:14):

there are no more file conflicts

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:14):

there are fewer links that work than before, but that's it

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:14):

But then, on linux when you go to struct.Foo.html or struct.FOO.html, you'll get 404 whereas it'll work on windows/mac

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:14):

yes? I don't see the issue here

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:14):

which is exactly the issue we're trying to solve

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:15):

ok let's take a second to agree on the issue we're trying to solve

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:15):

https://github.com/rust-lang/rust/issues/25879 says

pages are being overwritten on the file systems with case-insensetive names

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:16):

this is different from "the set of links that work on Mac is different from the set that works on Linux"

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:16):

thanks joshua

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:16):

some pages don't exist at all because rustdoc deleted them

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:16):

the set of links that works on Mac will _always_ be different

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:16):

it will be larger. always. we cannot fix this, this is how the os works.

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:17):

Well, it seems like I can't convince you. You want to keep the URL scheme (which I understand), but by doing that, you will worsen the user experience for all linux users.

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:17):

I don't see how we can be satisfied with that

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:18):

I don't see why you think this is a worse user experience

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:19):

the URL scheme is the only way for us to fix this issue for everyone, whatever the FS. If you have better suggestion on how to change it better, I'm all for it. But generating a disambiguator is really not great imo

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:19):

But generating a disambiguator is really not great imo

could you please explain why

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:19):

I did multiple times already

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:19):

URLs stop working the same on conflicted items in linux

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:20):

GuillaumeGomez said:

But then, on linux when you go to struct.Foo.html or struct.FOO.html, you'll get 404 whereas it'll work on windows/mac

^ ok you mean this

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:20):

I don't see why this is a worse user experience

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:20):

because it was working before

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:20):

solving a solution for A shouldn't make it less good for B

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:20):

this is exactly the same problem your suggestion has though: struct.Foo.html no longer works because only -foo.html exists

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:21):

Guillaume, _any solution_ will have that problem. That problem is fundamental to the filesystem

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:21):

no

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:21):

your solution has that problem

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:21):

changing the URL scheme prevents that

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:21):

you can visit struct.-Foo.thml and struct.-foo.html

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:21):

both work on windows, only one on linux (if you have Foo)

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:21):

oh you mean to keep the current URLs? Well, I don't see how it could work

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:21):

I don't know what you're trying to say

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:22):

I still do not see how the UX for linux users is worse

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:22):

99% of docs will be unchanged

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:22):

more than 99%

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:22):

Manish Goregaokar said:

you can visit struct.-Foo.thml and struct.-foo.html

yes you can, but you wouldn't expect that for linux users to work

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:22):

i don't understand what you're trying to say

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:23):

the small percentage of docs that will be changed will break a _small_ number of URLs but still introduce a disambiguation page that we can generate such that most people find it

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:23):

I'll try to pick an example.

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:23):

It does seem like you're attempting to solve a different problem than the rest of us

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:24):

Well, I think I can't convince you. It's mostly a loss of time.

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:25):

I just suggest to keep the current situation then

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:25):

No, I do feel that the problem should be fixed

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:25):

I just think you have not communicated your stance clearly enough for us to understand your concerns

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:25):

We don't agree on the solution. What you suggest isn't a solution, it's a hack and it brings downsides

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:26):

It'll require big changes on the intra-doc links to work too

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:26):

I don't think we agree on the _problem_

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:26):

and again, your URLs could if a change somewhere else in your code creates a name conflict

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:27):

Manish Goregaokar said:

I don't think we agree on the _problem_

Maybe?

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:27):

GuillaumeGomez said:

It'll require big changes on the intra-doc links to work too

I've wanted to unify intra-doc links with the rest of rustdoc for a while anyway https://github.com/rust-lang/rust/pull/82014

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:27):

(deleted)

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:27):

GuillaumeGomez said:

and again, your URLs could if a change somewhere else in your code creates a name conflict

Yes, I understand that downside, which is why we lint about it when you introduce a name conflict, and give you a path to avoid it

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:28):

but then you ask for users to go around your tool limitation

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:28):

The point is that it gives the user power over picking how to solve this, instead of picking a scheme that applies to _everyone_ and is something _everyone_ has to worry about

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:28):

this is a terrible user experience

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:29):

No, lints should be about good practices, not how to go around tool limitation

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:29):

GuillaumeGomez said:

but then you ask for users to go around your tool limitation

I think we disagree that this is a limitation of rustdoc and not the FS

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:29):

Your solution does that too! Your solution asks users to work around the tool limitation by having to remember a weird link scheme!

This isn't a tool limitation! This is a limitation of the filesystem, and either rustdoc arbitrarily picks a workaround (your proposal) or we give the users _power_ to pick their own workaround

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:29):

Yes

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:29):

I think this is a fundamental FS limitation. the -foo solution simply _picks_ a workaround and forces everyone into it

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:29):

Joshua Nelson said:

GuillaumeGomez said:

but then you ask for users to go around your tool limitation

I think we disagree that this is a limitation of rustdoc and not the FS

This is definitely a limitation on rustdoc. We should have taken into account the FS limitation when the URL scheme was created

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:30):

And that would have introduced a weird scheme that everyone would need to worry about

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:30):

that's still forcing the users to deal with the limitation

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:30):

there is nothing we could have done here that would not impact the users negatively in some way

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:30):

But the docs could be browsed without problems. People can get accustomed to new URL schemes

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:31):

it would work in any case, whatever the item

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:31):

GuillaumeGomez said:

But the docs could be browsed without problems. People can get accustomed to new URL schemes

I don't see why this isn't true of the other scheme?

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:31):

your solution doesn't allow that and instead, tells the user to fix their code

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:31):

Yeah, this is true of both schemes

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:31):

But what you suggest is incoherent

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:31):

yes, but by applying a rustdoc attribute

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:32):

they don't need to rename anything

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:32):

I think we're just circling around the same central point. I think there is no need for this discussion to go further :-/

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:32):

That's fair, but I do want to fix this problem, so I do think we need to discuss this eventually

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:33):

I need a break then

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:33):

go for it

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 16:33):

do you want to resume a bit later?

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:33):

sure whatever

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:35):

but i'll say this again: the "don't break all the URLs" is not just _my_ concern, and I'm assuming it as a hard blocker because I'm predicting that this RFC will be impossible to land since breakages are a product concern which means you'd need to convince core. I'm really not trying to be difficult here, or impose my personal opinion, I'm just predicting that any RFC that changes half the URLs out there will be a very very very hard sell.

view this post on Zulip Joshua Nelson (Mar 30 2021 at 16:35):

/me goes to delete https://github.com/rust-lang/rfcs/pull/2988

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:38):

heh

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 16:38):

@Joshua Nelson I think we can manage that with redirects

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 18:11):

Ok, so after eating a bit, let me try to explain why I think your solution isn't good enough. First, let's start with the good parts:

Now, what I have issues with:

In comparison, what we suggested in the RFC, what is good:

What's bad:

In the end, it's to fix an issue on ~0.45% of the items on docs.rs. So it's really small, but I don't want us to ask users to fix valid code because of URL scheme. Like I said, this is not a FS problem but a URL scheme problem. FS limitations were ignored when rustdoc URL scheme was created (almost a decade ago now!).

An issue you brought up was that it would require to add eventually add redirections. It'd be actually pretty simple to do I think considering that the URL scheme itself follows a very simple rule. So it could be added on docs.rs and doc.rust-lang.org.

Also: with the 2021 edition coming up, can't we use this opportunity to introduce such a change?

And finally (this is isn't an argument in itself, more like a sidenote: the new URL scheme the RFC suggests would require almost no change in rustdoc whereas what you suggest has a lot of implications and things to take into account).

That's it for the big explanation of my point of view. I tried to make it as clear as possible (I'm really bad at explaining what I have in mind and I'm sorry about that) and as objective as possible too.

view this post on Zulip Joshua Nelson (Mar 30 2021 at 18:38):

It breaks something which is currently working on linux (foo and FOO are both perfectly valid URLs) to fix a problem on windows/macOS.

FWIW, I think we could do server-side magic on doc.rust-lang.org and docs.rs to redirect to the lower-case version if the original URL isn't found. That doesn't work for local docs, but this only matters if someone was using a perma-link anyway.

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 18:46):

I just thought about something that your proposition doesn't fix @Manish Goregaokar : conflict on modules

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 18:47):

For example:

pub mod aa {
    pub fn foo() {}
}

pub mod aA {
    pub fn foo() {}
}

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 18:47):

(and with sub-levels, it's even "worse")

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 19:24):

It breaks something which is currently working on linux (foo and FOO are both perfectly valid URLs) to fix a problem on windows/macOS.

Yours breaks something that is currently working _everywhere_ (code that does not clash on casing) to fix a problem for 0.45% of the crates. I don't see how mine is _worse_ on this angle. I'm trying to scope the breakage to crates that already have problems due to this.

It creates inconsistency between different FS. For example, both foo and Foo work on windows/macOS but not anymore on linux (which is the opposite of what we currently have and what we try to fix). We can argue that what I propose is breaking all URLs, but at least it is predictable.

Okay, but this is _always_ the case: in your solution, -foo and -Foo will work on windows/mac but not linux. This is a fundamental problem of filesystem differences, which is what Joshua and I are trying to argue. It is not worth trying to fix "some paths work on some systems but not others" because that is a fundamental problem . The problem I and Joshua are trying to solve is "doc generation on an insensitive FS leads to docs not existing"

I don't see how my solution is not predictable. If there is ambiguity, there will _always_ be a struct.Foo.html (or fn.foo.html) file, with a list of all the other entries. That's predictable enough IMO.

URLs can change because of a change in your code.

Yes, but we lint about this, so if you change your code you will see the lint and can choose your solution.

Also: with the 2021 edition coming up, can't we use this opportunity to introduce such a change?

No, because editions are for surface-level changes that can be upgraded over. rustdoc's output is a bunch of URLs, changing those URLs is not easy to upgrade over at all.

Also it is basically too late to add _new_ things to the edition.

It requires actions from users for them to "fix" perfectly valid code.

My point is that yours does too -- in your solution _everyone_ has to deal with this bug because of the new, hard-to-remember URL scheme, and furthermore URL completion and links are broken which is _huge_.

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 19:26):

@GuillaumeGomez I think this will break links to modules, but again, on some OSes these weren't being generated correctly in the first place, and your solution breaks all links.

In my solution the sensible way of handling this is that we generate aa-1 and aa-2 and have aa/index.html just be a disambiguation page

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 19:26):

@GuillaumeGomez taking a step back: what problem are you trying to solve

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 19:27):

because here's a statement of the problem I am trying to solve:
rustdoc currently generates overlapping files on windows and mac. I want us to not do that.

I don't particularly care that filepath URLs on windows and mac allow you to access structs via different names whereas linux doesn't. this is a fundamental constraint of the filesystem, and it's not a huge deal because nobody is ever linking to filepaths (they're local)

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 19:28):

(deleted)

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 19:29):

I am very sympathetic to "URLs can change when you change your code" fwiw, I just think a lint should be sufficient to warn people it will happen and allow them to pick something to upgrade

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 19:31):

I do not at all agree that framing that we are "forcing users to fix their perfectly valid code". This is a fundamental problem, either _we_ fix it for the users by arbitrarily picking a scheme that will make a lot of users annoyed, or we give the users choice. I feel like the user choice angle is far easier; and we can make it pleasant by _still_ picking a scheme (the numbering scheme) that generates something that kinda-sorta works but has problems, and letting users sort it out however they want

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 19:31):

Also another downside you forgot to list -- url autocompletion is broken; and lots of people browse based on url autocompletion from history

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 19:32):

that's the problem with creating our own normalization scheme

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 19:32):

I still do not understand what the issue is on this axis though:

It creates inconsistency between different FS. For example, both foo and Foo work on windows/macOS but not anymore on linux (which is the opposite of what we currently have and what we try to fix). We can argue that what I propose is breaking all URLs, but at least it is predictable.

as i said this seems to always be an issue.

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 19:33):

and it feels like in your casting of the problem statement you're trying to solve some problem here too

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 19:33):

note that URLs on the web are always insensitive no matter what OS you visit from

view this post on Zulip Noah Lev (Mar 30 2021 at 19:59):

Manish Goregaokar said:

note that URLs on the web are always insensitive no matter what OS you visit from

My understanding was that URLs can be case-sensitive if the server chooses that...?

view this post on Zulip Nemo157 (Mar 30 2021 at 19:59):

Manish Goregaokar said:

Given source with struct foobar; struct FOOBAR; how would we know whether these are the single word "foobar" or conjoined words "foo bar" in order to decide this file is struct.Foobar.html or struct.FooBar.html? There are many instances of conflicting names in -sys crates that are not following any kind of easily machine discernable convention for word separation.

view this post on Zulip Nemo157 (Mar 30 2021 at 20:00):

and yes, URLs are up to the server, docs.rs is case sensitive, e.g. <https://docs.rs/brotli/2.4.0/brotli/enc/static_dict/fn.SlowFindMatchLengthWithLimit.html> vs <https://docs.rs/brotli/2.4.0/brotli/enc/static_dict/fn.slowFindMatchLengthWithLimit.html>

view this post on Zulip Noah Lev (Mar 30 2021 at 20:00):

This whole issue and discussion makes me think how much time and energy across all different projects could have been saved if OS designers had decided to use a case-sensitive filesystem :sweat_smile:

view this post on Zulip Nemo157 (Mar 30 2021 at 20:03):

(though maybe web browsers implement file: handling case-insensitively? I can't check on a machine running both a graphical browser and case-sensitive FS right now)

view this post on Zulip Joshua Nelson (Mar 30 2021 at 20:08):

Nemo157 said:

Manish Goregaokar said:

Given source with struct foobar; struct FOOBAR; how would we know whether these are the single word "foobar" or conjoined words "foo bar" in order to decide this file is struct.Foobar.html or struct.FooBar.html? There are many instances of conflicting names in -sys crates that are not following any kind of easily machine discernable convention for word separation.

yeah I would rather just make disambiguation pages unconditionally lowercase

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 20:32):

@Nemo157 yeah so I thought we could Titlecase it (not CamelCase); but we can also just lowercase it -- I brought this up elsewhere

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 20:32):

I think we just need to pick something consistent there

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 20:32):

so struct.foobar.html being the disambig page works for me

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 20:32):

@Nemo157 and yeah URLs are up to the server, but _HTTP_ is case sensitive, as is docs.rs

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 20:38):

Okay, but this is _always_ the case: in your solution, -foo and -Foo will work on windows/mac but not linux. This is a fundamental problem of filesystem differences, which is what Joshua and I are trying to argue. It is not worth trying to fix "some paths work on some systems but not others" because that is a fundamental problem . The problem I and Joshua are trying to solve is "doc generation on an insensitive FS leads to docs not existing"

With what I suggest, there is no -Foo, only -foo for "Foo' or foo for "foo". The point here is that "valid" URLs work on linux because they should. The extravagant "-Foo" or even "-FoO" on windows and macOS isn't our problem. They're not supposed to work in the first place. If the OS allows it, well, fine for them.

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 20:39):

Didn't understand why you talked about "links to filepath"

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 20:40):

Also, I showed you an example that shows that what I suggested fixes it definitely (modules) and yours doesn't but that doesn't count at all in the end? :-/

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 20:42):

I do not at all agree that framing that we are "forcing users to fix their perfectly valid code". This is a fundamental problem, either _we_ fix it for the users by arbitrarily picking a scheme that will make a lot of users annoyed, or we give the users choice. I feel like the user choice angle is far easier; and we can make it pleasant by _still_ picking a scheme (the numbering scheme) that generates something that kinda-sorta works but has problems, and letting users sort it out however they want

There will always be people not happy about any change. The longer we wait (we already waited way too long), the more there will be. And no, requiring changes from the user is definitely not a good way to handle it.

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 20:43):

Also another downside you forgot to list -- url autocompletion is broken; and lots of people browse based on url autocompletion from history

It's part of the URL breaking change, not forgotten. :)

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 20:47):

I do not at all agree that framing that we are "forcing users to fix their perfectly valid code". This is a fundamental problem, either _we_ fix it for the users by arbitrarily picking a scheme that will make a lot of users annoyed, or we give the users choice. I feel like the user choice angle is far easier; and we can make it pleasant by _still_ picking a scheme (the numbering scheme) that generates something that kinda-sorta works but has problems, and letting users sort it out however they want

We don't agree on the fundamental problem. I think it's that the rustdoc URL scheme didn't take into account the case insensitivity of some OS. I propose a new URL scheme to fix this issue definitely, you propose a workaround. It's two very different approach. And your workaround doesn't fix the module issue I talked about above. And saying "it's already broken so we can keep it as is" is definitely not a good argument.

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 20:49):

I still do not understand what the issue is on this axis though:

It creates inconsistency between different FS. For example, both foo and Foo work on windows/macOS but not anymore on linux (which is the opposite of what we currently have and what we try to fix). We can argue that what I propose is breaking all URLs, but at least it is predictable.

as i said this seems to always be an issue.

Extra explanations! What is working on linux should work on windows and macOS. However, the inverse isn't true: the case insensitive FS allow "invalid" URL. But in this case, it's also a valid URL since both Foo and foo exist. So now, an URL that should be valid on linux (and is valid on windows/macOS) isn't anymore.

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 21:24):

Didn't understand why you talked about "links to filepath"

By and large, stability of filesystem links only matter if you're hosting the files _locally_ and using file:/// URIs. When it comes to _link_ stability, because basically all webhosting is Linux and because HTTP is case sensitive, we can mostly assume that nobody is _linking to_ Mac/Windows-hosted URLs so breaking those links is not a huge deal. Breaking the linux links is, but both of our proposals do a little breakage.

Also, I showed you an example that shows that what I suggested fixes it definitely (modules) and yours doesn't but that doesn't count at all in the end? :-/

I do address modules. It's a valid complaint, it counts, but I feel like the solution is sufficient since we encourage people to doc(filename) _anyway_.

My way of addressing modules is, as I already stated: we apply the same thing: generate aa-1/ and AA-2/ and lint about it, and also generate aa/index.html as a disambiguation page. Yes, some links will break, but your proposal breaks _all_ links.

There will always be people not happy about any change.

I think _most_ people will be unhappy about this, I think half the core team will be unhappy about this, but my point isn't about people being unhappy. My point is that suddenly the _entire ecosystem_ needs to care about this. As opposed to mine where a small subset needs to care.

Both of our proposals force people to change things. Yours forces everyone to change how they interact with rustdoc. Mine forces a small subset to do a code change (and provides an okayish default if they don't). Just because mine has a code change doesn't mean that makes it somehow worse.

It's part of the URL breaking change, not forgotten. :)

No, it's distinct, I mean that even if you do not have legacy URLs in your history, things like struct.Foo won't autocomplete that well because it will be struct.-foo in the history.

. I propose a new URL scheme to fix this issue definitely, you propose a workaround. It's two very different approach

Okay, look. Yours is as workaround-y as mine, it literally introduces a _new name mangling scheme_. You keep trying to bucket the proposals this way, it's not constructive, please stop.

Extra explanations! What is working on linux should work on windows and macOS. However, the inverse isn't true: the case insensitive FS allow "invalid" URL. But in this case, it's also a valid URL since both Foo and foo exist. So now, an URL that should be valid on linux (and is valid on windows/macOS) isn't anymore.

So what you're saying is that previously on Linux struct.foo.html and struct.Foo.html would work, and on Mac both would work but point to the same thing, and with my proposal one of them is broken on linux, yes?

I mean, sure? But your proposal breaks all the links? I still do not see how this complaint is specific to my proposal.

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 21:29):

FWIW, someone else I asked about this said the following thing:

urls are the primary interface of rustdoc's output! this is like if symbol mangling were exposed to source code

"URLs are the primary interface of rustdoc" is a super insightful idea.

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 21:47):

I think it's that the rustdoc URL scheme didn't take into account the case insensitivity of some OS.

Stepping back further, _why_? What problems are you trying to solve here? I'm attempting to solve "rustdoc generates overlapping files on some OSes"

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 21:48):

It does feel a bit like we're going in circles on this though, does anyone else on the team want to chime in? It's quite possible we're talking past each other and other opinions would be helpful.

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 21:58):

Just wondering: @Manish Goregaokar would it be fine if we added tihs disambiguation only on windows/macOS?

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 21:59):

Problem with that is we need an option to force it on linux for the documentation provided to windows and macOS. Or... We generate for those platforms using the option so that they have fixed URLs and we're fine. All the best: nothing changes on linux, no need to change the URL scheme

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 21:59):

What do you think?

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:00):

Hmmmmm. It would not break _web_ URLs so I think that would definitely be less problematic. I would like the URLs to be the same on docs.rs and locally though.

I am not _strongly_ against such a proposal; but I am somewhat against it.

Note that for Windows we can actually set the output directories to be case insensitive: https://stackoverflow.com/questions/51591091/apply-setcasesensitiveinfo-recursively-to-all-folders-and-subfolders

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:00):

The URLs would be the same so to speak. We'd just have a disambiguator on windows/macOS specifically

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:01):

My PR is actually doing most of it already (the original one where everything came from)

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:01):

It detect if this is a case insensitive FS, if so it generates a conflict map and goes with generation

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:02):

The only issue was that I wasn't satisfied on the result for linux. But in this case, it'd be fine.

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:02):

The URLs would be the same so to speak. We'd just have a disambiguator on windows/macOS specifically

Oh, so like my proposal, but only on Linux?

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:02):

I just need to rework the output so that we use meta refresh instead

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:02):

"conflcit map"?

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:03):

i feel like you're suggesting the proposal i was suggesting :)

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:03):

Manish Goregaokar said:

The URLs would be the same so to speak. We'd just have a disambiguator on windows/macOS specifically

Oh, so like my proposal, but only on Linux?

No, on linux we keep the current output. The disambiguator would be on windows/macOS to prevent file conflicts :)

view this post on Zulip Joshua Nelson (Mar 30 2021 at 22:03):

Manish Goregaokar said:

"conflcit map"?

this was part of one of the PRs, let me find it

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:03):

er, soryr, "only on Windows"

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:03):

windows/mac

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:03):

https://github.com/rust-lang/rust/pull/83612

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:03):

@GuillaumeGomez Can you type out what your suggestion is?

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:03):

Most of this PR is doing what you suggested.

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:04):

ah, but only on windows/mac

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:04):

this totally works for me

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:04):

We did it \o/

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:04):

let's not use JS, just generate a disambiguation page

view this post on Zulip Joshua Nelson (Mar 30 2021 at 22:04):

Joshua Nelson said:

Manish Goregaokar said:

"conflcit map"?

this was part of one of the PRs, let me find it

https://github.com/rust-lang/rust/pull/83612/files#diff-46f011cf734f3de35eddca150990366cc41bd8eaf3945a241b2a2f79c5bb77eaR89

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:04):

Yes, that's the part I need to update, the PR is still incomplete

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:04):

@GuillaumeGomez so to be clear you're just suggesting "manish's proposal, but only applied to windows and mac" right?

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:05):

Yes, or enforced with --generate-case-insensitive in case you generate it on linux for windows/macOS

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:05):

so no change on linux, and on win/mac, _only if you have conflicts_, your files get named foo-1 and foo-2 (or whatever, i don't care) and foo.html says "HEY THERE ARE TWO FILES do you want THIS ONE or THIS ONE"

view this post on Zulip Joshua Nelson (Mar 30 2021 at 22:05):

GuillaumeGomez said:

Manish Goregaokar said:

The URLs would be the same so to speak. We'd just have a disambiguator on windows/macOS specifically

Oh, so like my proposal, but only on Linux?

No, on linux we keep the current output. The disambiguator would be on windows/macOS to prevent file conflicts :)

hmm, I'm pretty sure @Daniel Silverstone asked we not do this so that you can install any target's docs on any platform

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:05):

neat

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:05):

@GuillaumeGomez can we still have the lint, though?

view this post on Zulip Joshua Nelson (Mar 30 2021 at 22:05):

I guess that only really matters for the standard library though?

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:05):

yes'

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:06):

Manish Goregaokar said:

GuillaumeGomez can we still have the lint, though?

Euh... It's midnight, please debate about this tomorrow.

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:06):

@GuillaumeGomez i think overall it would be nice if people had a way to avoid this happening, and having a lint seems straightforward

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:06):

@GuillaumeGomez can i take that to mean you disagree?

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:06):

feels like the lint is just added niceness there

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:06):

I don't like the idea. But just like we did, I'd like us to agree on what we would make this lint about if it would exist.

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:07):

With discussion, we can always reach compromise

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:07):

yeah

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:07):

i mean this doesn't seem much of a compromise as much as "you picked the solution i was proposing in the first place"

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:07):

:)

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:07):

@Joshua Nelson That's why I provided the --generate-case-insensitive option

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:08):

Well, it was my initial PR which started this whole debate :p

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:08):

heh

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:08):

anyway, how about I write a hackmd with my proposal, we can collaboratively turn it into an RFC, and see what folks think. With this framing the lint is not a 100% necessary part of it, but i think it would be nice

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:08):

But at least we got the same idea. Your proposal for the disambiguator is much better than what I came up with though

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:08):

There is a need for RFC here? There is no URL change normally

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:09):

Oh, maybe that's something we might not agree on XD

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:09):

In my case, I planned as follow:

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:09):

Oh yeah we don't have to have an rfc, only if we want the lint

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:09):

I think this is good to rfc though

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:09):

the disambiguator file, if it has JS enabled, will then make a redirection to get the correct file

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:10):

Otherwise, it'll just display the file

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:10):

not _sure_ if i like the autoredirect as opposed to people knowing there was a disambiguation. but not a major issue

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:10):

i think writing the proposal in rfc format will help us as a team come to a conclusion, anyway

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:10):

Ah right, but then we fall back to the original issue on linux which made us fall into this whole thing

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:11):

Because if conflict there is, on linux it'll be problematic since Foo and foo are different

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:11):

you'll get a 404 if you try to access Foo, so we need to generate the correct links for it directly

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:12):

as in?

view this post on Zulip Joshua Nelson (Mar 30 2021 at 22:12):

I think we should stop going in circles

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:12):

we're not :)

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:12):

well, we can already implement that and not care about this issue for now

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:12):

i think we've come to a reasonable conclusion and are working out the details

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:12):

well, it's where it all started XD

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:13):

it's because the disamguator URL was working in all cases for windows/mac but not for linux that we suggested to change all URLs

view this post on Zulip Joshua Nelson (Mar 30 2021 at 22:13):

It sounds like there are a couple different proposals with different trade offs. I think we should write down what they are

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:13):

@Joshua Nelson there aren't anymore

view this post on Zulip Joshua Nelson (Mar 30 2021 at 22:13):

I'm not planning to read through hundreds of messages of backscroll

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:14):

yeah i'm writing it down

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:14):

Thanks Manish

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:14):

there's one proposal with a couple knobs to tweak

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:14):

i will write it down and call out the knobs

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:14):

Phew, I'm gonna fall into coma until tomorrow morning now I think

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:15):

@Joshua Nelson the status quo is basically: the thing i proposed, but _only_ on windows/mac (or if you pass the --generate-whatever flag). knobs that have not yet been decided: should we lint? should the disambiguation page read the URL to autoredirect?

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:15):

also knob: the exact disambiguation scheme to use (which i do not care about)

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:15):

Yep, that's a good sum up

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:15):

In my PR I simply change the current file with the one I have in my JS map

view this post on Zulip GuillaumeGomez (Mar 30 2021 at 22:16):

But it's implementation detail, not really important at the moment

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:21):

@GuillaumeGomez when you get a chance you should close your rfc so folks don't keep discussing it

view this post on Zulip Manish Goregaokar (Mar 30 2021 at 22:41):

I think another mismatch is: I do not expect rustdoc to ever link to the disambiguation page, it will only ever be visited from the URL


Last updated: Oct 11 2021 at 22:34 UTC