Why don't you create the POD files before uploading to CPAN? You can either put that as a separate step into your Makefile.PL or have a test that checks that the POD has been generated and thus will fail before you upload the distribution.

Sure, that's one way to do it. Currently, almost everything for PDL is written using the PDL::PP, which generates XS code and .pm files. We could change our distribution such that the XS generation would happen on the developer's machine, though the XS files would still have to compile on the installer's machine. Unfortunately, I don't think anybody involved in PDL at the moment knows the PDL::PP sub-system well enough to separate the XS generation step from the compilation step.

You're right, though - that would solve the problem.

You do know that if you have code in 'Foo.pm', you can put POD in 'Foo.pod', and 'perldoc Foo' fetches the POD from 'Foo.pod' instead of 'Foo.pm', don't you? That means that if you generate the .pm file at compile, you can still ship a complete .pod file.

I've found the solution to my problem, and it does not involve using CPAN-specific pod (like the '=for CPAN' directive that I suggest above).

My problem was that CPAN examined the various files in the PDL distribution and, upon finding POD-looking stuff, attempted to parse it for POD. This is generally a good thing since it means you can embed POD in your C source files, if you have any with code like this:

/*  Include POD in a C block-comment
=head1 NAME

MyHeader.h - includes the basic header stuff for my modules.

=head1 SYNOPSIS

You'll need to include this header with something like this:

 #include "MyHeader.h"

etc

*/
[download]

The funny thing about the PDL::Slices code to which I link is that some of it displays properly. Upon closer inspection, I realized that I could use this to my advantage to get CPAN-specific pod! Here's how it works. Imagine I've got a file MyModule.pm.PL that generates MyModule.pm for me when you install it from CPAN, with contents that depend on some configuration settings:

#! perl

open my $module, '>', 'MyModule.pm';

print $module <<CODE
# MyModule.pm, automatically generated by MyModule.pm.PL
# Do not edit by hand!  All changes will be overwritten
# next time you run MyModule.pm.PL!

# module code goes here...

CODE

# Determine if feature foo is available.  Then:

if ($use_foo) {
  print $module <<IMPLEMENTATION
# Code for implementation with feature foo goes here
# ...
IMPLEMENTATION
}
else {
  print $module <<IMPLEMENTATION
# Code for implementation without feature foo goes here
# ...
IMPLEMENTATION
}

# This is pod that the eventual module will contain, and
# which CPAN will show:

print $module <<DOC;

1;

=head1 NAME

MyModule - a cool module.

=head1 SYNOPSIS

=cut
DOC

# ONLY CPAN (and perldoc MyModule.pm.PL) will show this,
# because it is not being printed to MyModule.pm:

=pod
You are viewing this using CPAN or perldoc MyModule.pm.PL.
When you install this module, only one of the two synopses
will be shown, depending on how you configure the
installation.

=cut

if ($use_foo) {

# This pod only shows on CPAN:
=head2 Synopsis when you use feature foo:

=cut

# This pod shows up in CPAN and in the installed module
# when feature foo is enabled:
  print $module <<DOC
=pod

 # (Here's where you would describe how to use the module
 # with feature foo)
 # ...

=cut
DOC
}
else {

# This pod only shows on CPAN:
=head2 Synopsis when you don't use feature foo:

=cut

# This pod shows up in CPAN and in the installed module
# when feature foo is not enabled:
  print $module <<DOC
=pod

 # (Here's where you would describe how to use the module
 # without feature foo)
 # ...

=cut
DOC

}
[download]

Notice that every single bit of POD ends in a cut. In the .pd files that are currently distributed with PDL, lots of documentation sections are not explicitly ended with a cut because the auto-generated code adds some additional auto-generated documentation, which ends in a cut as necessary in the eventually generated files. But as a result, when the .pd file is processed by CPAN, it runs right over the heredoc's close.

It's a convoluted mess, but the point is that it can be done! In fact, in the case of .pd files, it's less confusing.

I should conclude by saying that I'm not trying to advocate for CPAN-specific pod, because I'm not sure that's a good idea. But I needed to be able to add some pod to the .pd files so that CPAN would show them correctly, and of course the answer turned out to be right under my nose! :)

Any suggestions?

So, my suggestion is that if you want this to happen, talk to the people in charge of search.cpan.org and offer your time to implement this feature.

Thanks. Such a simple solution! I wasn't sure if this had been discussed before, so I figured I would check here first. I'll contact them and see what they say.