Menu
▾
▴
#23 CPAN web site bug
Documentation for PDL::IO::GD is actually listed under the "Documentation" sub-heading at http://search.cpan.org/~chm/PDL-2.4.6/ rather than under the "Modules" sub-heading. This causes a fair amount of confusion. This should be under the "Modules" sub-heading.
I've been clicking around CPAN and as far as I can tell, if a file ends in .pm, it is listed under the Modules section. If it ends in .pm.PL and has pod, it is also listed under the Modules section. Anything else that has pod appears to go under Documentation. So the resolution is as 'simple' as renaming all of the .pd files to .pm.PL.
OK, so it's not quite that simple, but it's pretty close. To do this, we would rename the .pd files to .pm.PL and insert the a line similar to this in each one:
--------%<--------
use PDL::PP ('PDL::My::Mod', 'PDL::My::Mod', 'lib/PDL/My/Mod');
--------%<--------
The redundancy is annoying. Perhaps we can alter PDL::PP so that the second argument is optional? Then, under Module::Build, we would also need to add an entry for this to the Build.PL file that looks like this:
--------%<--------
PL_files => {
'lib/PDL/My/Mod1.pm.PL' => ['lib/PDL/My/Mod1.pm', 'lib/PDL/My/Mod1.xs'],
'lib/PDL/My/Mod2.pm.PL' => ['lib/PDL/My/Mod2.pm', 'lib/PDL/My/Mod2.xs'],
...
},
--------%<--------
Of course, we have Module::Build::PDL, so we can make it scan the lib directory for .pm.PL files and add them to the PL_files hash for us, but then any other .pm.PL files would have to be handled a little differently. Ironically, the renaming from .pd to .pm.PL would make the original purpose of M::B::PDL moot.
So, it looks like we can have all of the PDL modules properly placed in CPAN under the Modules section, and as I have said before, we can even get all of the documentation in these (soon to be former?) .pd files to display correctly on CPAN with a little bit of work. So this is fixable, but it'll take a lot of work to get it to happen.
Holy freaking cow Module::Build is way cooler than I thought. You don't even need to add those PL_files lines to the Build.PL file. It will automatically run the .PL files, which is not surprising, and it tracks everything well enough to clean up when everything is done, which is very surprising!
So the only thing you need to do to get Module::Build to play well with PDL::PP files is to include a use PDL::PP statement like the one already described, and to include the following two lines in your Build.PL file:
use PDL::Core::Dev;
$builder->include_dirs([PDL::Core::Dev::whereami_any().'/Core']);
That's it! You'll get everything that M::B::PDL does without having to install M::B::PDL! Pretty awesome!
We can still use M::B::PDL, however. First, M::B::PDL would eliminate the necessity for those two additional lines, but also we can add automatic documentation updates into the installation phase.
After list discussion, it appears this is not a bug with PDL but a problem with the default online documentation extracted from a CPAN module at search.cpan.org. I'm marking it Remind to track progress as PDL documentation is cleaned up, perhaps during the desired M::B conversion...
David,
You are now officially insane. PDL::PP files need their own pre-processing, separate from PL preprocessing, and thus have their own file name. Getting rid of that convention would be a nightmare, and I don't see any reason for that at all...
Judd
Point well taken. And of course, the priority is low for a reason.
The reason I even suggest converting .pd files to .pm.PL is (1) they are scripts that need to run before the compilation process and (2) so that CPAN properly indexes the files. The first place that many Perl users go for documentation on new modules is CPAN, so a CPAN-friendly documentation structure is really important. As to my first point, IMHO, this simple fact is convoluted by the current .pd build process. Why didn't we (by which I mean y'all from way back when) just require .pd files to 'use PDL::PP (...)'? Not only is it OK that they produce multiple files, but M::B even has a mechanism for specifying it.
Certainly implementing this idea would take some work, but I don't think it would be a nightmare. We could simply add a few modifications to PDL::PP's pp_done function so that it would add a note() to the current M::B builder essentially saying 'my/mod.xs is a PDL::PP file'. Then we could override M::B's process_xs file function so that it would check that note for each .xs file it processes and use the appropriate type flags and linker settings.
In practical terms, we might add code to PDL::PP that looks like this:
# Only add notes to M::B if it is around!
eval {
require Module::Build::PDL;
};
# unless there's a problem...
unless ($@) {
# Get the current M::B builder...
my $builder = Module::Build::PDL->current();
# Get the current linker flags (if any)...
my $linker_flags = $builder->note("linker_flags_for_$current_file_prefix");
# Create a new list of linker flags that include the old ones...
@new_flags = [$pdl_dep, @$linker_flags];
# and store the results in the builder's notes
$builder->note("linker_flags_for_$current_file_prefix", \@new_flags);
}
Fortunately, up until the file renaming bit, our ideas don't conflict. So, you work on that, I'll work on this, and we'll see if we can meet somewhere in the middle. :)
I recommend using podchecker on all the *.pd files in the PDL
distribution and addressing the problems reported. That should
improve the default usability of the module documentation
auto-extracted at http://search.cpan.org.
podchecker output from PDL git *.pd files
Updated this with the output from podchecker-ing all the *.pd
files in the PDL git at the moment. Fixing these should go a
long way to improving the legibility of POD on search.cpan.org.
That's quite a checklist! Also, for a different take on things, it looks like podlint does a pretty good job finding stuff to fix.
This particular problem (and lots of others) have been resolved in the recent docs review and update.
This problem is not fixed with the latest doc updates. It will only be fixed when I manage to (1) contact the CPAN people and get them to recognize .pd files as Modules rather than Documentation, or (2) we change our naming scheme to use .pm.PL file extensions, which are automatically registered as Modules instead of Documentation. I will work on this, but not until after I've finished M::B::PDL.
Sorry about the false "fixed", I looked at the docs from our PDL site and not from CPAN. I agree that CPAN cosmetology is lower priority than M::B::PDL...
Moved to the Feature Requests tracker as this is not a bug per se in PDL.
Another problem: the PDL::PP doc link on http://search.cpan.org
give the result of 'perldoc Basic/Gen/PP.pm' which is [sic]:
> Basic::Gen::PP(3) User Contributed Perl Documentation Basic::Gen::PP(3)
>
> $name
> Signature: ($sig)
>
> $doc
>
> $baddoc
>
> perl v5.10.1 2011-04-29 Basic::Gen::PP(3)
Maybe if Pod/PP.pod were placed in this directory, the website
would use it for the docs link. This is not a PDL bug but a usability
item for PDL users and prospective users.
This issue is largely fixed with the recent addition of cpan-friendly distribution generation. Thanks kmx!