#254 online docs don't link to functions in other PDL modules

normal
open
other (94)
3
2015-10-01
2011-01-19
Derek Lamb
No

For example, at http://pdl.perl.org/?docs=Transform/Cartography&title=PDL::Transform::Cartography#t_unit_sphere, the t_spherical link points to http://perldoc.perl.org/Transform.html#t_spherical (which does not exist), but should instead point to http://pdl.perl.org/?docs=Transform&title=PDL::Transform#t_spherical. I don't have the docs installed on my local machine to verify that they work, but I seem to recall that they do. I believe it is due to the php code on the website transforming links (that used to go nowhere) to non-PDL Perl modules. There probably needs to be some logic in there about not doing it if the link starts with "PDL::'. I can't get at the code at the moment, but maybe somebody else has the time.

Discussion

  • Chris Marshall

    Chris Marshall - 2011-02-14

    The problem is that the target of the links
    in the POD are being generated by the
    PP code which happens at build time while
    the CPAN site POD to HTML conversion
    is done on the raw files from the distribution.

    After yesterday's review of podchecker errors
    and the subsequent fixes committed to PDL
    git, the only remaining problems that were
    not fixed were these dangling links.

    One way to fix the problem would be to
    make to missing POD explicit in the PP
    code so the POD converter can find it.
    That would be pretty ugly as is the current
    way that the POD is grubbed out of the
    *.pd files.

    A second approach might be to change
    the way we do PDL distributions by generating
    all the POD as part of the 'make dist' process.
    However, I don't think the current PP
    generator framework has an easy way to
    do this...

     
  • Chris Marshall

    Chris Marshall - 2011-02-14
    • summary: online docs don't link to functions in other PDL modules
      --> online docs don't link to functions in other PDL modules
     
  • Derek Lamb

    Derek Lamb - 2011-02-15

    To clarify: the problem I listed does not manifest in my local PDL html docs, and does not manifest in CPAN's online docs, just on the copy of the docs that are hosted on pdl.perl.org. These docs have some php code (I believe) that modifies some links to CPAN modules (that just stay broken in my local copy) and that PHP code is incorrectly modifying some of the links for PDL modules. So I think either 1) changing the doc build process so that the links work on local copy (and thus on the pdl.perl.org copy) and thus we can remove the PHP link-massaging code or 2) fix the existing PHP link-massaging code and live with broken links to CPAN modules on the local copy.... would be fine. I think (2) would be the least work while not making things any worse than they have been. I could in principle get to it soon, but have no time frame for doing so.

     
  • Chris Marshall

    Chris Marshall - 2011-02-16

    Sorry about the misunderstanding. -chm

     
  • Chris Marshall

    Chris Marshall - 2015-03-06

    Derek, do you know if the changes to the PDL docs handling "fixes" this problem?

     
  • Chris Marshall

    Chris Marshall - 2015-09-29

    Looks like this problem is fixed for http://search.cpan.org and http://metacpan.org but the docs on the PDL home page still have broken links. Maybe we can wrap this up for PDL-2.014.

     
  • Derek Lamb

    Derek Lamb - 2015-10-01
    • assigned_to: Derek Lamb
    • Group: --> normal
     
  • Derek Lamb

    Derek Lamb - 2015-10-01

    I think I know how to fix this, by changing some of the preg_replace() function calls at the top of index.php to preg_replace_callback(), which gives us the ability to be a little more judicious about the pattern substitutions. Hopefully I will be able to look at this next week.

    My test cases are the above-mentioned links from PDL::Transform::Cartography::t_unit_sphere to PDL::Transform::t_spherical, the links in PDL::IO::Storable to the CPAN Storable module, and the 37 instances of links that are turned up by

    $ make doctest
    $ cd blib/lib/PDL/HtmlDocs/PDL
    $ grep -nrio '<a href="../[[:alnum:]./]*.html......' *

     

Log in to post a comment.