develooper Front page | perl.perl5.porters | Postings from April 2010

Broken pod links

Thread Next
karl williamson
April 25, 2010 10:40
Broken pod links
Message ID:
I was chagrined to discover that some pod changes I submitted a while 
ago had links that didn't actually work.  I thought podchecker.t was 
supposed to find those.  It turns out it only looks for links internal 
to each pod it checks, while not checking cross links.

So, I hacked it up to add cross pod links.

And I found that a number of pods are not checked by it, since it only 
looks at things in MANIFEST.  Any generated pod isn't checked, such 
perlmodlib, which it turns out has invalid syntax.

And I found many broken links, not just the few I had introduced.

One source of several hundred are references to perlfunc functions that 
don't exactly match.  For example, 'sort' is referred to, but there is 
no exact node in perlfunc named exactly 'sort', as it requires a 
parameter, so the closest node is 'sort LIST'.  What this means is that 
the generated html pages on cpan don't actually generate links to the 
page much less the node (anchor in html terminology) within the page.

But if I ignore those, there are still many broken links.  Another major 
source is links to non-perl man pages, some with their section number, 
and some without, like 'printf' or 'printf(3)'.  Should these even be in 
L<> tags?  Is there software somewhere that would link these to the real 
man pages?

I'm thinking what I should do is deliver this change, with the known 
link errors set up as TODOs so they don't fail the test, much as diag.t 
has a (too long) list of undocumented messages that won't fail.  That 
way, we can find new breakages as they occur, which is better than the 
current condition.


Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About