|Just another Perl shrine|
Avoid inconsistent POD =over =item indentationby toolic (Chancellor)
|on Oct 13, 2009 at 15:23 UTC||Need Help??|
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.
IssuePOD is rendered inconsistently for short =item strings.
SolutionManually 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:
and I look at the POD using perldoc on the command line as follows:
Here is how it renders for me:
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:
ObservationAfter 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:
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.
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:
VersionsThe 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.
I discovered that the PERLDOCDEBUG environment variable (see perldoc) is quite handy if you ever need to dig deeper into POD.