=encoding

There seems to be a discrepancy between the documentation for perlpod and
its behaviour.

http://perldoc.perl.org/perlpod.html says

=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

=encoding big5

However, perldoc says

../mymodule.pm:1: Unknown command paragraph "=encoding utf8"

pod2html produced a similar message.

It doesn't depend on the location of the =encoding since I tried putting
it in various positions.

Can anyone explain this?

Re: =encoding

Ben Bullock wrote:
> There seems to be a discrepancy between the documentation for perlpod and
> its behaviour.
>
> http://perldoc.perl.org/perlpod.html says
>
> =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
>
> =encoding big5
>
> However, perldoc says
>
> ./mymodule.pm:1: Unknown command paragraph "=encoding utf8"
>
> pod2html produced a similar message.
>
> It doesn't depend on the location of the =encoding since I tried putting
> it in various positions.
>
> Can anyone explain this?

It seems that perlpod is too new and doesn't fit the shipped
versions of Pod::Text and (if already using the new Pod::Text
package) Pod::Simple on your system. However, it seems that
this is an issue with the locally installed versions of perlpod
as well, as my local 5.8.8 build also mentions the =encoding
directive but can't handle it.

I just checked with an older bleadperl from November 2006, this
one already has up-to-date versions of the Pod:: packages that
can handle =encoding just fine.

So you can either wait for Perl 5.10 being released or install
the newer Pod:: modules from CPAN.

-Chris