r? @cmr

(rust_highfive has picked a reviewer for you, use r? to override)

Uhm, I'm fairly certain that you can't use . (period) in HTML IDs since it's the CSS prefix for classes. (#method.foo.example in CSS means "thing with id 'method' and classes 'foo' and 'example').

Why not use - (regular dash) instead?

Does this also fix #25001?

@killercup
I don't have a problem with using - instead, though I'm not sure about . since it is already used in other existing ids (i.e. method.foo, assoc_type.Bar)

@apasel422
No, this only fixes doc-block headers, relying on a unique parent id.
Figuring out unique ids for trait impl items requires some more thought.

Uhm, I'm fairly certain that you can't use . (period) in HTML IDs since it's the CSS prefix for classes. (#method.foo.example in CSS means "thing with id 'method' and classes 'foo' and 'example').

No, there isn't any such rule. Granted, it's slightly inconvenient to write #method\.foo\.example in CSS.

The value must be unique amongst all the IDs in the element's home subtree and must contain at least one character. The value must not contain any space characters.

– http://www.w3.org/TR/html5/dom.html#the-id-attribute

I stand corrected. It still looks weird to me, though 😄

cc @alexcrichton
(I see you didn't like this approach in #21967 very much, though I think this is a bit different)

Thanks for the PR @mitaa! This is looking pretty good to me, although I think it'd be better if the markdown document renderer supported just automatically handling this. It's a little unfortunate that you have to manually scope ids as it's easy to forget.

I thought there was already support for this in the backend, but basically there should be a TLS map which stores all used ids and then every time you try to use one that's already used a number is just prepended to the end. Between pages this set can be reset, but the idea is that then this is always handled without having to manually annotate scopings.

@alexcrichton
Yes, I've noticed the machinery which enumerates the header ids.
The TLS map is currently reset between rendering Markdown blocks.

I guess if this is (re)moved the issue would be solved, but I think this also has some disadvantages which I tried to solve with this approch:

• link stability
  • id="example-13" will break if a header with the same name is removed or added before it on the page
• intuitivity
  • method.foo.example can be inferred and typed into the url bar without looking at the html source, example-7 not so much

How important are these aspects?

I think it's ok to not have super-stable links, and I also think that the part about typing in makes more sense for major sections which are likely to have longer ids, consequently unique and easy-to-remember ones.

Ah, alright, then I'll rewrite this PR to make the existing mechanism page global, (re)using it for all other ids on the page too.

(updated)

Should this include a test?

edit: I think ID uniqueness should rather be enforced through htmldocck.py by default.

Looking good, thanks @mitaa! And yeah could you add a few small tests here and there in src/test/rustdoc?

(updated)

Does this look ok to you @alexcrichton?

@bors: r+ fb7008c

Thanks!

⌛ Testing commit fb7008c with merge 461c460...

☀️ Test successful - auto-linux-32-nopt-t, auto-linux-32-opt, auto-linux-64-debug-opt, auto-linux-64-nopt-t, auto-linux-64-opt, auto-linux-64-x-android-t, auto-linux-cross-opt, auto-linux-musl-64-opt, auto-mac-32-opt, auto-mac-64-nopt-t, auto-mac-64-opt, auto-win-gnu-32-nopt-t, auto-win-gnu-32-opt, auto-win-gnu-64-nopt-t, auto-win-gnu-64-opt, auto-win-msvc-32-opt, auto-win-msvc-64-opt