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 reply to Re: Regex tutor in Perl/Tk by Juerd
in thread Regex tutor in Perl/Tk by Popcorn Dave

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.