Where do those links come from?

This came up in a post-work discussion last night

How do the links to methods appear at the top of module documentation? Are they automatically generated?

A specific example of POD that does this is DBIx::Class::ResultSet

Since I wasn’t sure what the exact behaviour is off the top of my head, I thought I’d investigate.

search.cpan.org

As you may have already seen, the web-rendered version of the POD has a table-of-contents list of “stuff” at the start of the document.

search.cpan.org

perldoc

perldoc doesn’t produce the same table-of-contents. This makes sense to me, there’s not much scope for a clickable list of headings in text output

perldoc DBIx::Class::ResultSet

What magic markup makes this happen?

The simple answer is, “there’s no magic markup required”.

As long as you’re using pod2html, or something that behaves in the same manner you just need to use ‘=head1’, ‘=head2’ and friends in your own POD.

The DBIx::Class::ResultSet pattern

Checking the file source quickly with

perldoc -m DBIx::Class::ResultSet

I discovered that the general module and POD structure looks something like:

Start with the usual POD blurb:

=head1 NAME

=head1 SYNOPSIS

=head1 DESCRIPTION

Lead into the method containing section:

=head1 METHODS

Each method then has this format:

=head2 name_of_sub

=over 4

=item Arguments: $something, \%$attrs

=item Return Value: $frobnitz

=back

This is the wordy description of the sub-routine.

Often we'll put in an example or two of usage:

  my $fubar = $thing->my_sub({ fried => 'mars bar' });

=cut

sub name_of_sub {
}

As you can see that there’s no magic here; it’s just an example of well-written POD.

Seeing for yourself

You can get some idea of what’s happening by running ‘pod2xxx’ on existing modules:

# a rough approximation of perldoc
pod2text `perldoc -l DBIx::Class::ResultSet`

# what you might expect to see on search.cpan.org
pod2html `perldoc -l DBIx::Class::ResultSet`

If that’s too much output, just create your own small POD file and experiment.

=head1 NAME

my - POD file

=head1 DESCRIPTION

Somewhere to test POD behaviour

=head1 METHODS

=head2 some_sub

=over 4

=item Arguments: $something, \%$attrs

=item Return Value: $frobnitz

=back

This is the wordy description of the sub-routine.

Often we'll put in an example or two of usage:

    my $fubar = $thing->my_sub({ fried => 'mars bar' });

=cut

sub name_of_sub {
}


=head1 AUTHOR

Chisel

=cut

Enjoy!

1 Comment

In short, each pod formatter can do what it likes. The default formatter for HTML inserts a table of contents. The recent versions of perldoc have a -M switch where you can specify the formatting class, and a -o switch to specify what sort of output you'd like.

I think I have a longer example of this in Mastering Perl, which was completely written in Pod and used a special formatter. The latest Learning Perl is also written in pod with a specialized DocBook formatter.

Leave a comment

About Chisel

user-pic I blog about Perl.