papidave has asked for the wisdom of the Perl Monks concerning the following question:

I'm using perl 5.8.5 under RHEL4sp4, trying to put POD in my modules these days. perldoc -v gives version v3.13 for that perl. When I attempt to put a usage example in my POD that uses single quotes, perldoc procedes to translate those quotes into three question marks -- ??? -- even though I had indented the code example.
#!/usr/bin/perl -w use strict; =head1 Foo Method Typical call syntax would be: =over 8 my $ret = $obj->foo( 'LITERAL STRING' ); =back =cut
Through perldoc, I get:
foo(3) User Contributed Perl Documentation + foo(3) Foo Method Typical call syntax would be: my $ret = $obj->foo( ???LITERAL STRING??? ); perl v5.8.5 2007-08-07 + foo(3)
I can workaround this by using double-quotes (for this example), or by inserting a literal ascii escape for the single quote (i think), but this stil bothers me, because the says "I wanted the translator to always leave the ' and ` and " quotes alone, in verbatim mode, so I could slurp in a working program, shift it over four spaces, and have it print out, er, verbatim. "

What am I missing, here?

Replies are listed 'Best First'.
Re: single quote munged by perldoc?
by moritz (Cardinal) on Aug 07, 2007 at 14:15 UTC
    That could be an encoding/charset issue.

    What locales is your terminal using (echo $LANG and echo $LC_ALL), and what is the encoding of your file?

Re: single quote munged by perldoc?
by papidave (Pilgrim) on Aug 07, 2007 at 14:35 UTC

    Current LANG is "en_US.UTF-8". When I export LANG=C, the quotes display properly. Very odd.

    Thank you.

      "Very Odd?"


      quoth perldoc perlpod, qv:

      "=encoding *encodingname*"
      This command is used for declaring the encoding of a document. Most users won't need this; but if your encoding isn't US-ASCII or Latin-1, then put a "=encoding *encodingname*" command early in the document so that pod formatters will know how to decode the document. For *encodingname*, use a name recognized by the Encode::Supported module. Examples:
      • =encoding utf8
      • =encoding koi8-r
      • =encoding ShiftJIS