You can always wade through the source code to see what it's doing.

Also: supersearch

Thanks. That's just what I needed. It's much simpler if you know that PDF::API2::Outlines itself returns an outline, and can just avoid the new() function altogether.

You can call outlines() from a PDF::API2 instance to get a PDF::API2::Outlines object. That's what the line in the PDF::API2::Outlines constructor section is telling you.

$otl = PDF::API2::Outline->new $api,$parent,$prev
Returns a new outline object (called from $otls->outline).
[download]

I got the following to work. Started with an example (ex 12-5) I found in the O'Reilly book 'Perl Graphics Programming' by Shawn Wallace. But it's mostly from the documentation for PDF::API2.

use warnings;
use strict;
use PDF::API2;

# Create a blank PLF file
my $pdf = PDF::API2->new(-file => 'test7.pdf');

#------- Don't call new from PDF::API2::Outline directly...
my $otls = $pdf->outlines();

# Add a built-in font to the PDF
my $font = $pdf->corefont('Helvetica-Bold');

foreach my $section ( 1..3 ){
    my $otl = $otls->outline;
    $otl->title("Section $section");
    
    foreach my $pagenumber (1..4) {
        #add blank page...
        my $page = $pdf->page();
        
        # Set the page size
        $page->mediabox('Letter');
        my $text = $page->text();
        $text->translate(225,600);
        $text->font($font, 20);
        $text->text("Hello world, s$section, p$pagenumber");
        
        # add suboutline.
        my $sotl = $otl->outline();
        $sotl->title("Page $pagenumber");
        $sotl->dest($page);
    }
}
$pdf->save();
[download]

I have a PDF which doesn't have an index (which I believe is called an "outline")

Outline, in PDF parlance, is rather a set of bookmarks (that's what they are called in Acrobat UI), most often, but not necessarily, posing as TOC, leading to anywhere within the document or within universe, or triggering any other action in JS-enabled viewer.

Never used PDF::API2::Outline, but FWIW:

use strict;
use warnings;
use PDF::API2;

my $doc = PDF::API2-> open( 'sample.pdf' );     # Assuming it to have 
+at least 
                                                # 2 pages
$doc-> outlines
    -> outline
        -> dest( $doc-> openpage( 1 ))          # All this chaining is
+ not
        -> title( '1st page')                   # really necessary, do
+ing it
        -> parent                               # just for fun.
    -> outline
        -> title( '2nd page')
        -> open
        -> outline
            -> title( 'top of 2nd page' )
            -> dest( $doc-> openpage( 2 ), '-xyz' => [ 0, 0, 0 ])
            -> parent
        -> outline 
            -> title( '2nd page, 500 pts from top edge' )
            -> dest( $doc-> openpage( 2 ), '-xyz' => [ 0, 500, 0 ]);

$doc-> preferences( '-outlines' => 1 );
$doc-> saveas( 'sample+.pdf' );
[download]

Reading the source notwithstanding, $doc-> outlines won't do any good if a document being opened already contains Outlines -- not your case, I understand. Just try reading saved document again, to see. And re-blessing won't help. Distribution needs to be patched.

Bookmarking to locations within the page (above) will work if document is viewed with sufficient zoom. Changing zoom when jumping to destination is possible, but I personally think it's rather impolite.