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! :)