in reply to Regex tutor in Perl/Tk

Your pod is wrong. =head2 is for headers, not content paragraphs, indented code is whitespace, you need a lot more blank lines. Use podselect and podchecker to find out all the problems. Read perlpod for help.

Pod isn't just how we write our documentation so it's in a standardized format, it's there to allow easy parsing and conversion to other text formats (html, manual pages, plain text). 

=head1 NAME

Module::Name - Description

=head1 SYNOPSIS

    Only code is indented
    What is indented, is rendered as code

=head1 DESCRIPTION

See how there are blank lines around the =foos.

=head2 Some sub-section of DESCRIPTION

Strangely, head2s are often not in ALLCAPS. 
Note how the text body itself is not part of the =head2.
These
words
are
not
newline
terminated
in the end
result.

This is a new paragraph, because of the blank line.

=head1 AUTHOR

Don't forget to say <who@you.are>

=cut

[download]
And when documenting a specific part of the code, add the sub name or some other pointer in the documentation, as code context is lost when pod is converted to the end result.

Here's how pod2text renders my example: 

NAME
    Module::Name - Description

SYNOPSIS
        Only code is indented
        What is indented, is rendered as code

DESCRIPTION
    See how there are blank lines around the =foos.

  Some sub-section of DESCRIPTION
    Strangely, head2s are often not in ALLCAPS. Note how the text body
    itself is not part of the =head2. These words are not newline term
+inated
    in the end result.

    This is a new paragraph, because of the blank line.

AUTHOR
    Don't forget to say <who@you.are>

[download]
And the pod2html version:

NAME

Module::Name - Description

SYNOPSIS

    Only code is indented
    What is indented, is rendered as code

DESCRIPTION

See how there are blank lines around the =foos.

Some sub-section of DESCRIPTION

Strangely, head2s are often not in ALLCAPS. Note how the text body itself is not part of the =head2. These words are not newline terminated in the end result.

This is a new paragraph, because of the blank line.

AUTHOR

Don't forget to say <who@you.are>

Pay attention to the index at the top: don't have all of your text in =head2 :)

Good luck! 

- Yes, I reinvent wheels.
- Spam: Visit eurotraQ.

In Section Cool Uses for Perl