Pod renderer needs to be smarter about non-latest pod links

[rwstauner]

Examples:

• https://metacpan.org/pod/release/JROBINSON/DBIx-Class-Manual-SQLHackers-1.2/lib/DBIx/Class/Manual/SQLHackers.pod
  a pod file (no package (therefore no 02packages)) links to other pod files (ditto)
• Alpha and legacy distribution pod links to latest stable pod metacpan-web#1567
  a release should probably link to other enclosed pages in the same version

For these kinds of things we either need to make the /pod endpoint smart about where someone is linking from (which seems like a terrible idea) or we need to hook into the renderer and determine what the base for a link should be:

• if destination is not indexed: full link
• if link is to separate dist: short link (not indexed would be handled by first item)
• if release is not latest (link is internal): full link (keep to specific version)
• if release is latest: short link

Could we simplify the logic by saying "anything in this dist gets a full link, anything outside this dist gets the short link"? The change there would be in not linking people to the canonical (latest) url when maybe we could, so the question becomes: is that better than linking to the latest url when we shouldn't? I think this is essentially what sco is doing.

Thoughts?

[ribasushi]

anything in this dist gets a full link, anything outside this dist gets the short link

👍

If this gets implemented things become much much better for a production end-user trying to read the docs for their present version (and lets face it - production running on the latest version of something CPAN is very very very rare)

[haarg]

My preference would be to keep short links for in-dist modules when viewing a page using the short link. I also don't think we should link to un-indexed files that aren't in the dist.

I've written up a preliminary idea for how to handle this: haarg@ba0e35f It is completely untested at this point. It adds a query parameter to the pod end point, which if present will use full links for anything in the same dist. The front end can then use that parameter when viewing a page using a short link.

[rwstauner]

I suspect that someone (like ranguard) would vote for short (canonical) urls as they are good for caching and search indexing.

Using the short links when viewing a short link would perhaps accomplish both objectives. It's obviously more complicated, but should be doable. I haven't had a chance to look over that commit yet.

[ranguard]

As long as we have short links (linking to latest version), and this is what other dists link to, and is also what is set as canonical in the HTML it shouldn't affect SEO/caching having 'in dist' links localised to a version.

I can see pros can cons on both sides so as long as the canonical HTML keeps working then I'm going to let others make the decision

[haarg]

I've updated my idea to actually work: 62bfa80

[ranguard]

Closing as @haarg did some stuff

[haarg]

Unfortunately, my changes still had some mistakes in them. They were also only on the back end, with no front end support.

I'll try to get a refresh going soon.