|
POD2::Base - Base module for translations of Perl documentation |
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: 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.
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).
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 the supported options are:
@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.
@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:
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.)
$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.
$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.
$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:
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', ...);
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 the Pod::Perldoc manpage. So POD2::Base do not try
to repeat them here.
Enrico Sorcinelli <bepi at perl.it> (the original POD2::IT code)
Adriano Ferreira <ferreira at cpan.org>
the POD2::IT manpage, the POD2::FR manpage, the POD2::LT manpage, the POD2::CN manpage, the perldoc manpage, the perl manpage.
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.
|
POD2::Base - Base module for translations of Perl documentation |