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 of perldoc. It is not very convenient
       but always works.

       To improve the support to read translated docs, the perldoc 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 help "perldoc" 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 subclass "Pod::Base".

       For example, a minimum example is provided below:

           package POD2::TLH; # Klingon

           use 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 a
       POD2/TLH/perlintro.pod file was shipped together with POD2/TLH.pm) and

           $ perldoc -L tlh -f pack

       will find you the Klingon documentation of "pack" (if POD2/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.

           If "POD2::ANY" is a subclass of "POD2::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
           the "POD2::Base" instance. If this is not used, the up-to-date @INC is used at each
           call of "pod_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 by "Pod::Perldoc" to find out where to look for translated pods.

           The "POD2::Base" default behavior is to find POD2/<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 of "pod_dirs" do not include POD directories which do not
               exist (tested with "-d"). If an explicit false value for this option (like "test
               => 0") is given, such test is not done and "pod_dirs" includes all possible
               candidates POD2/<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 implement "perldoc -f <function>" the current code of "Pod::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 translated perlfunc.pod should define this
           method to make "perldoc -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 by "POD2::Base" itself. The return contains some metadata on the translated PODs
           which is used by the methods "print_pod" and "print_pods".

           When subclassing, you should 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 of "POD2::TLH" goes like this:

           package POD2::TLH; # Klingon

           use 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 the "POD2-Base" distribution tarball, a script eg/list.pl is included with an improved
       version of this code.

       The rules of finding POD in .pod, .pm files and others belong to Pod::Perldoc. So
       "POD2::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.