search

Raku / doc-website

Tooling to build/run the documentation website
Artistic License 2.0
7 stars 10 forks source link

Link on `cmp` page needs to be fixed #319

Closed raiph closed 9 months ago

raiph commented 9 months ago

If you click on the link in this text:

See also the documentation for the cmp operator.

You will arrive at a page. That page includes that same text.

It also appears in the text shown if you click on the in context link. And if you click on that entry's in context link you arrive back where you started.

I suspect this is likely to be because of an underlying problem that's much more broad than just this one case I've found.

But when I searched issues for things like "link self" etc I failed to find a general issue.

2colours commented 9 months ago

Yes, and it also seems that the anchor doesn't work.

2colours commented 9 months ago

It did use to work on the old site: https://web.archive.org/web/20200921203737/https://docs.raku.org/routine/cmp#(Operators)_infix_cmp

and it pointed to this segment of the site: image

This segment is present on the new site as well: image

However, its link seems quite broken: https://docs.raku.org/routine/cmp#language/operatorsroutineinfix is what I can copy from the anchor.

2colours commented 9 months ago

I think this is a content generation problem; the name of the entry generated into the site is wrong, not the textual link. @coke could you move this issue to the doc-website repo?

finanalyst commented 9 months ago

@raiph @2colours I'm having trouble replicating this issue. I clicked on the link in the first post and arrived at the composite page for cmp. The page lists five sources, namely 'cmp' in: type/Allomorph, type/List, type/Order, language/operators, and type/Pair. The 'in context' links in each of those segments are correct and link without error to the relevant sections of the original documentation sources. Please help me find which link is broken.

2colours commented 9 months ago

@finanalyst it's the type/Order link, that's where @raiph 's snippet is from. And this link itself should scroll to the language/Operator part, the way the archive link does. The problem is that on the new site, the segment of the language/Operator part is #language/operatorsroutineinfix in the URL, while it used to be #(Operators)_infix_cmp.

By the way, this is quite potentially a problem with all operators. In the compound sources, their segments are all like #language/operatorsroutineprefix and #language/operatorsroutineinfix. Why is that?

finanalyst commented 9 months ago

@2colors I'll look at this at the weekend. It looks as if a part of the name is missed off in the secondaries plugin, which is where composites are generated. Or in the header template where the internal url is generated. In the old site, sources were parsed twice, once to get composite information then to render. New site composite information is collected at render time. Then all composites are generated after primary sources have been rendered.

On Tue, 28 Nov 2023, 12:29 Márton Polgár, @.***> wrote:

@finanalyst https://github.com/finanalyst it's the type/Order link, that's where @raiph https://github.com/raiph 's snippet is from. And this link itself should scroll to the language/Operator part, the way the archive link does. The problem is that on the new site, the segment of the language/Operator part is #language/operatorsroutineinfix in the URL, while it used to be #(Operators)_infix_cmp.

By the way, this is quite potentially a problem with all operators. In the compound sources, their segments are all like

language/operatorsroutineprefix and #language/operatorsroutineinfix. Why

is that?

— Reply to this email directly, view it on GitHub https://github.com/Raku/doc-website/issues/319#issuecomment-1829747262, or unsubscribe https://github.com/notifications/unsubscribe-auth/AACYZHH6H6A6CYMPEMC4UJ3YGXKL3AVCNFSM6AAAAAA72LM4XSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQMRZG42DOMRWGI . You are receiving this because you were mentioned.Message ID: @.***>

finanalyst commented 9 months ago

@raiph @2colours I have looked at this issue again and I think that there may be some differences about how things should work, as opposed to how they used to work. Some comments:

  1. The appearance and wording of the 'composite' pages has changed since the old site. Some of this is to reduce duplication of text, to make site navigation more intuitive, and to enhance search usability. Consequently, the lay out of the page and the links are not the same as they used to be.
  2. I think the composite pages are working the way they were intended. So, if a different navigation interface is desired, please let me know.
  3. I thought perhaps one of the problems is that there is a link in another source file unrelated to the ones in the cmp composite, that explicitly references routine/cmp and is not hitting the target. But that does not seem to be the case here.
  4. The current interface for a composite file is this:
    • The description contains the same text, 'compiled from sources listed below', but the search information describes the sources'
    • Each segment has a title that refers to the source file
    • Each title has its own link id, which is automatically generated, and is used in the TOC. This id is different to the automatic id that was generated for the old site.
    • This is why

      language/operatorsroutineinfix in the URL, while it used to be #(Operators)_infix_cmp

    • All ids for heading titles are checked to be unique to the file.
    • All heading titles in all documents in the site provide a 'claw' that can be used to copy the id into the paste board. This enables a writer to include that title in another completely unrelated source file.
    • All heading titles in all documents also are links to the top of the file - this is a hold over from the times of HTML 1, when the TOC not in a floating side panel, and so the link was a way to get back to the top of the file and the TOC. Consequently, clicking on a heading title in a short file, where all the content is visible in the browser, does nothing.

Please let me know whether the issue here is

If either of the above, please add some suggestions about how to progress this issue

2colours commented 9 months ago

Each title has its own link id, which is automatically generated, and is used in the TOC. This id is different to the automatic id that was generated for the old site.

This is the problem, I would say.

I don't think it's appropriate to chase and change all links in the source because the content generation changed - moreover, I think this should be treated - more or less... - the same way as URL's themselves. Anybody could link to these anchors anywhere, anytime. We cannot change that all. This is a "breaking change" for the site.

finanalyst commented 9 months ago

@2colours I still can't locate where the error is. As to the wider issue of changing links that break the site, I thought I had been careful enough to eliminate that possibility. Seems there are still problems.

Also, there is the link error report, which is generated each time I renew the site.

I thought many of these problems would be solved by the escape character refactor. However, now that the refactor is in place, adding different links to Composite pages is relatively easy. There are two mapping files for to remap broken links to working links. I'll work on this in the next few days.

raiph commented 9 months ago

@finanalyst

I still can't locate where the error is.

I (@raiph) am not sure if you mean:

  1. You haven't been able to locate any error related to the particular example I began this issue with.

  2. You have, but haven't been able to locate where content generation is going wrong.

  3. You've seen the problem I began this issue with, and have addressed that, but you've been unable to locate some other problem that's been mentioned in this issue discussion after my opening comment.

  4. You've located some other problem that's been mentioned in this issue discussion after my opening comment, but haven't been able to locate the erroneous code in content generation.

I will presume it's #1. If it is, please ignore this comment.

finanalyst commented 9 months ago

It's #1. I read your first post in this thread. Looked at the links and they all seem correct. @2colors pointed elsewhere, I still can't find the error. But I know there could be errors and I know how to fix them.

So which link on which page

On Thu, 7 Dec 2023, 18:13 raiph, @.***> wrote:

@finanalyst https://github.com/finanalyst

I still can't locate where the error is.

I @.*** https://github.com/raiph) am not sure if you mean:

1.

You haven't been able to locate any error related to the particular example I began this issue with. 2.

You have, but haven't been able to locate where content generation is going wrong. 3.

You've seen the problem I began this issue with, and have addressed that, but you've been unable to locate some other problem that's been mentioned in this issue discussion after my opening comment. 4.

You've located some other problem that's been mentioned in this issue discussion after my opening comment, but haven't been able to locate the erroneous code in content generation.

I will presume it's #1 https://github.com/Raku/doc-website/issues/1. If it is, please ignore this comment.

— Reply to this email directly, view it on GitHub https://github.com/Raku/doc-website/issues/319#issuecomment-1845871741, or unsubscribe https://github.com/notifications/unsubscribe-auth/AACYZHA475OODL4YYYQANTDYIIBK7AVCNFSM6AAAAAA72LM4XSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQNBVHA3TCNZUGE . You are receiving this because you were mentioned.Message ID: @.***>

2colours commented 9 months ago

@finanalyst We have given the links that don't focus the appropriate part of the site because the #segment identifier is not what it used to be. This is not the same as a big fat 404 error; it's really just that the site should scroll to the appropriate anchors, the way the ToC also works. What else do you need to be able to reproduce it? Or maybe I should rather ask: what do you do and what behavior you get?

finanalyst commented 9 months ago

@2colours Thank you for your patience. I have now found the link that was causing the problem.

Links within primary sources that point to headngs in Composite pages are hard coded to the id naming system used by the previous web content builder.

This error is picked up in the Error report.

So this is a duplicate of other issues.

2colours commented 8 months ago

A follow-up: https://github.com/Raku/doc-website/issues/25#issuecomment-1867094564