Update old `#index-entry-...` links

[cfa]

trafficstars

Amend links with stale #index-entry... targets, in some cases choosing page sections rather than the equivalent index entry.

Manually tested updated links locally.

[coke]

Do we know why these were changed originally?

[finanalyst]

All index-entry links are to X<> markup. The part after the last hyphen is mangled from the text.

If 'X<>` markup is removed from the source, and they are referenced in some other file, then the anchor is lost but the cross reference remains.

The mangling used by Collection is the same as that used by Documentable, so it's probably not not an issue to do with change of tooling.

A bigger problem is that 'X<>' was used far too liberally to generate cross references such as in headings.

On Tue, 14 Mar 2023, 17:17 Will Coleda, @.***> wrote:

Do we know why these were changed originally?

— Reply to this email directly, view it on GitHub https://github.com/Raku/doc/pull/4266#issuecomment-1468510817, or unsubscribe https://github.com/notifications/unsubscribe-auth/AACYZHGGPDC73G42ACE4AVLW4CR2BANCNFSM6AAAAAAVYG2ECI . You are receiving this because you are subscribed to this thread.Message ID: @.***>

[cfa]

Happy to withdraw this if the current tooling can generate the expected targets. As it stands right now, though, links are broken across the board.

The PR retargets most of these to the relevant section heading; in a few cases, the index target was retained but required expansion, e.g. concurrency#index-entry-supply_(on-demand) → concurrency#index-entry-Reference_supply_(on-demand). @finanalyst, do you know why this is required / why it occurred?

[finanalyst]

@cfa I have been working hard on this issue. I have now determined that X<> markup in =head contexts was rendered into HTML differently to X<> in ambient text by Documentable / Pod::To::HTML. I am currently working on some of this.

[coke]

What's the current status on this, @finanalyst ? Is there a ticket open tracking the related work you mention?

[finanalyst]

@coke Sorry for the considerable delay. I have been working on this issue which is also linked to other problems. Complications include

• Targets (eg. index-entry-XXX) were generated by Documentable in different ways depending on whether the X<> was included in the title, or was in the text.
• Targets with multiple entries (eg L<display text|first entry, some description; second entry, more description> are treated oddly, with the target being index-entry-some_description-more_description-display_text.
• Targets with the form L<C<some term>|/routine/filename> exclude the text formatting (eg. <code>some terms</code> from the name of the target
• Targets with filenames containing escaped chars included things like $SOLIDUS
• Targets in Secondary files have their own naming form
• There are errors in the source files completely unrelated to the Documentable naming strategy

All these target names are distributed around Documentable classes, so it has been very difficult to reverse engineer the names.

I think I am making progress, and I hope to create a PR for doc-website tooling in the near future.

[finanalyst]

@cfa @coke

• I have modified the id naming algorithm for the case when a heading contains X<heading text|Syntax,foo>
• This eliminates a large number of errors related to index-entry-... type links.
• One example is index-entry-qw-quote-words-quote-words is now generated (this was the first change in @cfa PR.

Some general comments about the PR. I think that it should be

• There are 15 changes suggested here where one index-entry.... is replaced by another index-entry...... These should now be excluded from the PR.

In general, however, I think that the changes from 'index-entry' to the heading name is better. In many cases the X<> markup is after the heading. Consequently when the browser hits the X anchor, the heading is placed above the browser window. When the heading is targeted the browser puts the heading in a visible position.

The changes to the production web-site have yet to be approved. So the new index-entry names can be seen in new-raku.finanalyst.org

[coke]

@cfa - can you rebase this and address @finanalyst's comments? Would love to get it merged finally!

[coke]

Instead of trying to apply this, will work off the error report referenced in https://github.com/Raku/doc/issues/4476

Thanks, @cfa, for giving this a shot, I'm sorry we didn't get it merged in time. :(