Anchors showing up in secondaries are problematic

[2colours]

This is something I noticed with https://docs.raku.org/syntax/unless

There is a link to #if, and that would be a valid link in the original context. However, it is invalid in this extracted context. Some ways to mitigate it would be:

• removing the link
• generating full URI's for the links
• linking to a similar syntax page/search but I think that could escalate quickly

[finanalyst]

@2colours @coke @lizmat This is an interesting problem and has several solutions as @2colours has suggested, but also doing nothing because the link is a NOP.

More about the problem:

• The page syntax/unless is a composite (generically, composites are derived from possibly more than one source). In this case, syntax/unless only comes from one source, namely Language/control.rakudoc.
• language/control.html, which is directly generated from the source, has several sections, including both unless and if.
• the section on unless points to if, and because it is within the same document, it is only a local header.
• when the section on unless is extracted in order to be concatenated with possibly similar sections from other primary sources (which in this specific case there are none), the link to the section on if must change in character in some way.
• each section within a composite file already contains a link back to the page that is directly generated from the primary file.
• this problem must also have existed with the old site.

It is not at all clear what should be the generic rule. Here are some comments on each option.

• Leaving the link as it is means that there is a link to an internal anchor that does not exist. Browsers ignore such links, or move the visible window to the top of the file.
• Removing the link would essentially be the same as the above, BUT any code that removes links to local anchors risks removing links to within the section that is extracted, killing what would otherwise be a valid link.
• Rewriting all 'internal' links in an extracted section in order to add the url of the page directly generated is possible. The information is available at extraction time.
• Rewriting all 'internal' links to composite files would be complicated because
  • not all headings in a primary file are extracted into composite files. The heading has to be of the form =head? sub xxx, where 'sub' might be any of a dozen keywords.
  • since the composite file is for the same 'sub' name from different sources, eg., types, there will be duplications of anchor names.
    So, like @2colours I think this option is not feasible.

I wonder how prevalent this issue is - how many composite files have NOP internal links.

@coke @lizmat any thoughts?

[coke]

We may want to enforce a rule that all links must include the page, not just be relative to the page. I can update the L<> checker test to enforce this if we decide it.

[finanalyst]

@coke I think that changing the primary sources would be wrong because RakuDoc specifically says internal anchors are of the form L<xx|#internal>. The problem only occurs when secondary (or composite) files are generated.
So unfortunately, I will have to solve this for the secondaries generating the full url for links in secondaries.

[2colours]

@finanalyst I can't see why enforcing an extra constraint on a particular type of content would contradict the general principles of RakuDoc. This is like, use lib is allowed in Raku but if you specifically want to make sure your files can be precompiled, you should refrain from using them.

[finanalyst]

@2colours I am not sure I understand what you are trying to say. There are 141 instances of L< .*? |# in 35 files in the documentation suite. So the idiom of |# is used alot.
My view is that the renderer should handle such problems not change the source.

It will take a bit of effort, but I dont think it is too difficult.