Description
There was discussion on #176 (#965) about a disambiguation page for when a name might refer to multiple documents.
What happens now is that if a module is indexed by PAUSE,
/pod/NAME should point to that document.
If the NAME is not indexed by PAUSE (no authority) we basically show the most recent file from any dist that had a =head1 NAME for it.
Typically the answer has been "use a package line so that the document gets indexed by PAUSE" however there are a lot of old dists where that won't be done. As a destination for pod L<> links we should also accept executable scripts (that aren't indexed modules) at /pod/NAME.
So, for any /pod/NAME where the NAME isn't a package indexed by PAUSE,
if there are multiple possible files we should offer a disambiguation page that shows the alternate links instead of picking the latest and hiding the rest (which is essentially what we do now).
This will probably involve a change to the ES query to get back multiple results (possibilities) for a given name (and/or a pre-query), and then forwarding to another action that uses a separate template (view).
As I mentioned in #1031,
it might also be nice to have a section in any given document that shows a list of other "did you mean X" possibilities so that if people are viewing one of the possibilities they might be able to find what they were really looking for in one of the others.
There's still some possibility for confusion for anything that's not indexed by PAUSE (when a new upload adds a document with a conflicting name), but there really isn't much we can do about that. Until a name is indexed by PAUSE it has the possibility of changing (whether we show a disambiguation page or the first result).
For this reason I like the idea of the "other possibilities" section being added to any pod page. We could do both (the links section and the separate page), however if we only had one I think the "section" might be more useful (and possibly simpler to implement) than the separate page.
But we definitely need at least one (if not both of these).