Front page | perl.perl5.porters |
Postings from April 2010
Broken pod links
Thread Next
From:
karl williamson
Date:
April 25, 2010 10:40
Subject:
Broken pod links
Message ID:
4BD47E63.7030104@khwilliamson.com
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.
Comments?
Thread Next
-
Broken pod links
by karl williamson