Beefy Boxes and Bandwidth Generously Provided by pair Networks Joe
more useful options
 
PerlMonks  

Avoid inconsistent POD =over =item indentation

by toolic (Chancellor)
on Oct 13, 2009 at 15:23 UTC ( #800918=perlmeditation: print w/ replies, xml ) 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.

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

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:

STEPS 1 Measure twice. 2 Cut once.
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
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.

Comment on Avoid inconsistent POD =over =item indentation
Select or Download Code
Re: Avoid inconsistent POD =over =item indentation
by ikegami (Pope) 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.
      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

      which resolves to:

      pod2man --lax xml_merge | nroff -man

      Here is a snippet of the xml_merge POD:

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

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
    pom2
      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?
        I don't care what perldoc claims :DDD I ran pod2man manually, the output looked as expected, perl 5.10.1

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlmeditation [id://800918]
Approved by Corion
Front-paged by GrandFather
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others imbibing at the Monastery: (10)
As of 2014-04-18 09:32 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    April first is:







    Results (465 votes), past polls