NAME

POD2::Base - Base module for translations of Perl documentation

SYNOPSIS

use POD2::Base;$pod2 = POD2::Base->new({ lang => 'EO' });@dirs = $pod2->pod_dirs;$re = $pod2->search_perlfunc_re;

DESCRIPTION

This module is an abstraction of the code in POD2::IT and POD2::FR. These modules belong to the Italian and the French translation projects of core Perl pods.

Once a translation package had been installed, the translated documentation can be accessed with:

$ perldoc POD2::<lang>::<podname>

(where <lang> is a language abbreviation like IT, FR, TLH, etc.)

This is guaranteed to work even for older versions ofperldoc. It is not very convenient but always works.

To improve the support to read translated docs, theperldoc utility (since version 3.14_01) was updated to find translated PODs via:

$ perldoc -L IT <podpage>$ perldoc -L FR -f <function>$ perldoc -L TH -q <FAQregex>

(Note: this support was shipped together with the recently released 5.10.0 version the Perl interpreter.)

The objective of this class is to provide a minimum base to helpperldoc and authors of translation packages to do their job.

SUBCLASSING

If you want to write a translation package (and have some customization needs), your work may be diminished if you subclassPod::Base.

For example, a minimum example is provided below:

package POD2::TLH; # Klingonuse POD2::Base;our @ISA = qw( POD2::Base );sub search_perlfunc_re { # makes 'perldoc -f' work    return 'Klingon Listing of Perl Functions';}1;

And then

$ perldoc -L tlh perlintro

will present you the introduction of Perl in Klingon language (provided aPOD2/TLH/perlintro.pod file was shipped together withPOD2/TLH.pm) and

$ perldoc -L tlh -f pack

will find you the Klingon documentation ofpack (ifPOD2/TLH/perlfunc.pod was made available as well).

METHODS

This module has been made into a proper class with a very small API.

new

$pod2 = POD2::Base->new(\%args);$pod2 = POD2::ANY->new();

The constructor. An actual call might look like this:

$pod2 = POD2::Base->new({ lang => 'tlh' });

where the supported options are:

• "lang"

  Specifies the language code we're interested in. This is required, but can be extracted from the name of a subclass. Read below.

• "inc"

  This is used to override the list of Perl library directories where POD documents are searched (namely,@INC). Most of the time, you don't want to mess with that. It's handy for debugging and testing.

  It must be an array ref.

IfPOD2::ANY is a subclass ofPOD2::Base, the inherited constructor will work without arguments pulling 'ANY' from the package name and using it as the intented language code.

Note that use of "inc" in the constructor freezes the list of library dirs searched by thePOD2::Base instance. If this is not used, the up-to-date@INC is used at each call ofpod_dirs (so that dynamic changes in the Perl library path are taken into account). That's what we meant with the "Most of the time, you don't want to mess with that" mentioned above.

pod_dirs

@dirs = $pod2->pod_dirs;@dirs = $pod2->pod_dirs(\%options);

Used byPod::Perldoc to find out where to look for translated pods.

ThePOD2::Base default behavior is to findPOD2/<lang>/ directories under the current Perl library directories (@INC) or the list given as argument "inc" in the constructor.

The supported options are:

• "test"

  By default, the return ofpod_dirs do not include POD directories which do not exist (tested with-d). If an explicit false value for this option (liketest => 0) is given, such test is not done andpod_dirs includes all possible candidatesPOD2/<lang>/ under the library directories. (Handy for debugging this module. Not much practical use for anything else.)

search_perlfunc_re

$re = $pod2->search_perlfunc_re;

To implementperldoc -f <function> the current code ofPod::Perldoc uses a hard coded string "Alphabetical Listing of Perl Functions" or the return of this method (in a regexp) to skip the introduction and reach the listing of core functions. Thus a translation package with a corresponding translatedperlfunc.pod should define this method to makeperldoc -L <lang> -f <function> work properly.

There are other methods documented below. However, they will probably be superseded in future versions when more general methods to find and display metadata on translated PODs are designed and implemented.

pod_info

$hashref = $pod2->pod_info;

Used byPOD2::Base itself. The return contains some metadata on the translated PODs which is used by the methodsprint_pod andprint_pods.

When subclassing, youshould override this with the current information on what POD translations the current package is providing.

print_pods

$pod2->print_pods;

Prints all translated pods and the corresponding Perl version of the original files.

print_pod

$pod2->print_pod(@pages);$pod2->print_pod(); # uses @ARGV

Prints the corresponding Perl version of the original files corresponding to the pods passed as arguments.

EXAMPLES

POD2::TLH

A slightly extended version ofPOD2::TLH goes like this:

package POD2::TLH; # Klingonuse POD2::Base;our @ISA = qw( POD2::Base );sub search_perlfunc_re {    return 'Klingon Listing of Perl Functions';}sub pod_info {    return { perlintro => '5.8.8' };}1;

And you may try:

use POD2::TLH;my $pod2 = 'POD2::TLH';$pod2->print_pods();$pod2->print_pod('pod_foo', 'pod_baz', ...);

THE INSTALLED FILES

If you want to find out which language-specific POD files are installed at your Perl, you could use a code similar to this.

use File::Find;use POD2::Base;my $pod2 = POD2::Base->new({ lang => $lang });my @files;find sub { push @files, $File::Find::name } if -f },     $pod2->pod_dirs;print "$_\n" for @files;

In thePOD2-Base distribution tarball, a scripteg/list.pl is included with an improved version of this code.

The rules of finding POD in.pod,.pm files and others belong toPod::Perldoc. SoPOD2::Base do not try to repeat them here.

AUTHORS

Enrico Sorcinelli <bepi at perl.it> (the original POD2::IT code)

Adriano Ferreira <ferreira at cpan.org>

SEE ALSO

POD2::IT,POD2::FR,POD2::LT,POD2::CN,perldoc,perl.

COPYRIGHT AND LICENCE

Copyright (C) 2004-2006 Perl.it / Perl Mongers Italia

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.