I stumbled upon a POD feature which was not at all obvious to me, and which does not seem to be documented clearly. Here is a description of the situation and how to avoid it.

Issue

POD is rendered inconsistently for short =item strings.

Solution

Manually adjust =over indent value to be at least as short as the shortest =item string

Scenario which demonstrates the inconsistent behavior

Assuming I have some Perl code in a file named myprog.pl which looks like this: 
=head1 OPTIONS

=over 4

=item help

Help me!

=item foo

This is foolish

=back

=cut

[download]

and I look at the POD using perldoc on the command line as follows: 

perldoc myprog.pl

[download]

Here is how it renders for me: 

OPTIONS
    help
        Help me!

    foo This is foolish

[download]

Notice how the 'Help me!' text appears on the line following the 'help' text, but the 'This is foolish' text appears on the same line as the 'foo' text? I didn't see that coming! I would rather it render as follows: 

OPTIONS
    help
        Help me!

    foo
        This is foolish

[download]

Observation

After staring at it a while, I happened to notice that the number I specified after the =over tag (4) was larger than the length of the =item string (foo). So, I tried changing the 4 to a 3, and lo and behold, the POD rendered as I hoped.

Then it dawned on me (after staring at the manual) that having a short =item string is commonly used to produce a numbered list, such as: 

=head1 STEPS

=over 4

=item 1

Measure twice.

=item 2

Cut once.

=back

=cut

[download]

Which renders as: 

STEPS
    1 Measure twice.

    2 Cut once.

[download]
The rule seems to be: the text following short =item strings appears on the same line as the item itself. The text following long =item strings appears on the line below the item. The =over indent value controls what is considered short or long.

So... what's the catch?

For most people, most of the time, there is no problem. Unless, of course, you're like me, and you're lazy, and you like to keep your option names short.

If you want your POD to have a consistent appearance, then you have to remember to specify a small indent for =over.

This behavior does not seem to be clearly documented anywhere that I have read:

Versions

The result is the same on all the different platforms that are available to me. For example: 
This is perl, v5.8.8 built for x86_64-linux

[download]
I also tried 5.8.5 and 5.10.0, both 64-bit and 32-bit, and even on Windoze.

PERLDOCDEBUG

I discovered that the PERLDOCDEBUG environment variable (see perldoc) is quite handy if you ever need to dig deeper into POD.

In reply to Avoid inconsistent POD =over =item indentation by toolic

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.