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 stringScenario which demonstrates the inconsistent behavior
=head1 OPTIONS =over 4 =item help Help me! =item foo This is foolish =back =cut
and I look at the POD using perldoc on the command line as follows:
perldoc myprog.pl
Here is how it renders for me:
OPTIONS help Help me! foo This is foolish
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
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
Which renders as:
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.STEPS 1 Measure twice. 2 Cut once.
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:I also tried 5.8.5 and 5.10.0, both 64-bit and 32-bit, and even on Windoze.This is perl, v5.8.8 built for x86_64-linux
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 | |
by toolic (Bishop) on Oct 13, 2009 at 20:42 UTC | |
Re: Avoid inconsistent POD =over =item indentation
by Anonymous Monk on Oct 17, 2009 at 21:00 UTC | |
by toolic (Bishop) on Oct 18, 2009 at 18:48 UTC | |
by Anonymous Monk on Oct 19, 2009 at 00:10 UTC |