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.

Replies are listed 'Best First'.
Re: Avoid inconsistent POD =over =item indentation
by ikegami (Patriarch) on Oct 13, 2009 at 17:11 UTC
    nit: It's not a feature of POD. It's a feature of Pod::Text or whatever renderer is being used.
[reply]
      I agree that the ultimate appearance depends on the renderer. I think I just stumbled upon further proof of this. I happened to be looking at the xml_merge script on CPAN, and the OPTIONS section in my web browser looks quite different from what I see at my linux command prompt when I use: 
      perldoc xml_merge

      [download]

      which resolves to: 

      pod2man --lax xml_merge | nroff -man

      [download]

      Here is a snippet of the xml_merge POD:

      Read more... (2 kB)

      And, yes, I am tossing the term 'POD' around rather loosely.

[reply]
[d/l]
[select]
Re: Avoid inconsistent POD =over =item indentation
by Anonymous Monk on Oct 17, 2009 at 21:00 UTC
    I would consider it a bug in pod2text. pod2html/pod2man/pom2 don't have this bug 
    $ pom2 text 2
OPTIONS
    * help

      Help me!

    * foo

      This is foolish

    [download]
    pom2
[reply]
[d/l]
      Thanks for pointing out pom2. Perhaps it holds some clues to the mystery of perldoc.
      pod2html/pod2man/pom2 don't have this bug
      With respect to pod2man, this statement contradicts perldoc, which states:
      perldoc looks up a piece of documentation in .pod format that is embedded in the perl installation tree or in a perl script, and displays it via pod2man | nroff -man | $PAGER .
      perldoc, which runs pod2man, clearly elicits the inconsistent indentation behavior, which I demonstrated in my other reply. Could you clarify?
[reply]
[d/l]
        I don't care what perldoc claims :DDD I ran pod2man manually, the output looked as expected, perl 5.10.1
[reply]

Back to Meditations