#!/usr/bin/perl

use strict;
use warnings;

=begin pod

=head1 A few good subs

This is a line of Pod. This module contains
some functions and  might be used as follows:

    do_something(); # Magic happens here!

=end pod


# ------------------
# Subroutines
# ------------------

=begin pod

=head2 do_something

You'd use this I<awesome> function for:

=item  
When you want to do foo.

=item  
When you want to do bar, since foo obviously
isn't cutting it.

=end pod

sub do_something {
    print "Magic goes here.\n";
}

print "hi.\n";
do_something;
print "bye!\n";
[download]

I'd argue that this version is also much cleaner and less intrusive than Texinfo or HTML (or even classic POD). Whether it's better than the version I showed earlier is, I suspect, a matter of personal preference. Some people will prefer the clarity of explicit tags, others will prefer the elegance of implicit contextual cues.

The point being, of course, that Pod is part of Perl 6, and hence TMTOWTDI.

Damian