POD2::Base - Base module for translations of Perl documentation
use POD2::Base; $pod2 = POD2::Base->new({ lang => 'EO' }); @dirs = $pod2->pod_dirs; $re = $pod2->search_perlfunc_re;
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: we hope this support ships together with the soon-to-be 5.10 release of 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.
perldoc
If you want to write a translation package (and have some customization needs), your work may be diminished if you subclass Pod::Base.
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).
pack
This module has been made into a proper class with a very small API.
$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 (by now) "lang" is the only argument that matters.
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.
POD2::ANY
POD2::Base
@dirs = $pod2->pod_dirs;
Used by Pod::Perldoc to find out where to look for translated pods.
Pod::Perldoc
The POD2::Base default behavior is to find out the path of POD2/<lang>/ directory in the current Perl installation.
$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.
perldoc -f <function>
perldoc -L <lang> -f <function>
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.
$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.
print_pod
print_pods
When subclassing, you should override this with the current information on what POD translations the current package is providing.
$pod2->print_pods;
Prints all translated pods and the corresponding Perl version of the original files.
$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.
A slightly extended version of POD2::TLH goes like this:
POD2::TLH
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', ...);
Enrico Sorcinelli <bepi at perl.it> (the original POD2::IT code)
Adriano Ferreira <ferreira at cpan.org>
POD2::FR, POD2::LT, perldoc, perl.
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.
To install POD2::Base, copy and paste the appropriate command in to your terminal.
cpanm
cpanm POD2::Base
CPAN shell
perl -MCPAN -e shell install POD2::Base
For more information on module installation, please visit the detailed CPAN module installation guide.