Primary links to secondary files

[finanalyst]

Fragile links to virtual files

I have referenced this problem before, but I think I have a definite list. A full list can be seen on Error Report in the section on Links to non-existent files. Whilst this section has been considerably improved and contains all Secondary files, there are also some non-existent files that are due to typos, and not due to Documentable.

A primary file exists under the doc/ directory in this repository. Actually within the doc/Language, doc/Type, doc/Programs and doc/Native sub-directories.

A secondary file is generated from primary files by Documentable, and then rendered into html. Secondary pod6 files are placed by Documentable in the doc/syntax, doc/routine, from which they are rendered into HTML.

These links are fragile because changes in Primary files may lead to the non-generation of Secondary files.

The algorithm for generating a Secondary file is not documented anywhere. So it is not even possible to warn Primary file editors about what not to do. (Several issues in this Repository relating to breaking changes my be due to this design decision)

Suggestions

Since all secondary files are generated from Primary files, links in Primary files to secondary files can be replaced with links to Primary files. This can be automated. In fact, I created a program to do this (and a PR was proposed).

At the time, however, there was no way to determine whether such a wide-scale change to the documentation would break the entire collection.

With the development of the error-report in Collection, all changes can be tested before being pushed to the repository. And the integrity of the links within the collection as a whole can be verified for the first time.

Since many external blogs also reference Secondary files, it is not proposed that Secondary files cease to be generated.

The proposal is to replace links in Primary files to virtual, non-existent, Secondary files with equivalent links to Primary files.

Removing such links will allow for easier changes to Primary files, and for changes to be tested on a regular basis, and for alternative representations of the Raku documentation to be developed.

[JJ]

We don't have a spec for the doc URLs, either. So that should probably go first...

[finanalyst]

We don't have a spec for the doc URLs
@JJ I don't quite understand what a spec for doc URLs should look like.
How would such a spec differ from the POD6 spec for L<>?

[finanalyst]

@JJ Thinking about your comment more, how would a doc spec change the underlying problem in this issue?

[finanalyst]

Started working on eliminating these errors. Helped find error in renderer, and improves multibyte utf8 recognition.

Mostly errors are author typos, but also clearly there have been editing changes in headers that are not transferred to targets (because the editor could not know where the targets are in the collection).

[JJ]

We need to know

• What generates an URL and what does not
• How the URLs are generated from names
• Mapping content-URLs. That's right not a bit fuzzy.

[finanalyst]

@JJ I do know now, since I have had to reverse engineer Documentable and Pod::To::HTML in order to write ProcessedPod and Collection.
What form do you want this knowledge in? I could write something for you/the documentation. Where would you want it to appear?

[JJ]

There's a PR in the problem solving repo Maybe you can try and start from there, although you'll have to PR him to incorporate your changes to that PR.

[2colours]

@finanalyst can we get rid of this issue somehow?

[coke]

I think there are two items here: one is to review links to secondary items and see if they should be sent to primary ones instead. I think this is related to the #4468 - are we linking to individual methods or the routine pages? This is an ongoing editing question.

The other is, if we are linking to a secondary page that no longer exists, how do we cope? That is covered by the error report @finanalyst generates on his version of the doc site (but isn't published on prod). Fixing broken links has been on various tickets in the past, but I've just created a fresh one to track: #4476 (I don't think this existed when he opened this ticket in 2021)

With this, I think this ticket is closable.