Chisel

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.

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

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!