POD2::Base(3pm)

💖 POD2::Base 💖

okay bestie, gather round, because this is the manual page for POD2::Base — the base module for translations of Perl documentation, straight out of the User Contributed Perl Documentation collection. she's a 3pm page, she's iconic, and she's here to help your perldoc speak Klingon. no cap. 🦋

---

✨ NAME ✨

POD2::Base — the base module for translations of Perl documentation. she's the foundation, the blueprint, the main character that other translation packages build on. 💅

---

✨ SYNOPSIS ✨

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

@dirs = $pod2->pod_dirs;
$re = $pod2->search_perlfunc_re;

that's the whole vibe right there, bestie. ✨

---

✨ DESCRIPTION ✨

so basically, this module is an abstraction of the code that lives inside POD2::IT and POD2::FR. those two belong to the Italian and the French translation projects of core Perl pods — you know, the ones translating Perl's own docs into other languages. 🌍

once a translation package has been installed, you can reach the translated documentation like this:

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

where <lang> is a language abbreviation like IT, FR, TLH, etc. (yes, TLH is Klingon, and yes, that's real, and yes, it's iconic). 👑

this guaranteed works even on older versions of perldoc. it's not the most convenient thing in the world, but it always works. reliable queen behavior. 🫶

to make reading translated docs nicer, the perldoc utility got updated (since version 3.14_01) so it can find translated PODs via:

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

heads up: this support shipped together with the recently released 5.10.0 version of the Perl interpreter. 📌

so the whole objective of this class is to provide a minimum base that helps "perldoc" and the authors of translation packages do their job. teamwork, bestie. 🤝

---

✨ SUBCLASSING ✨

if you wanna write a translation package (and you've got some customization needs), your work may be diminished if you subclass "Pod::Base". that's just facts. 😌

here's a minimum example, look how cute and small she is:

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). slay. 🔥

---

✨ METHODS ✨

this module has been made into a proper class with a very small API. tiny but mighty, fr fr.

🌸 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 one is required, but it can be extracted from the name of a subclass. read below, bestie. 👇
• "inc" — this one is used to override the list of Perl library directories where POD documents are searched (namely, @INC). most of the time, you do not want to mess with that. it's handy for debugging and testing though. 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 intended language code. no args needed, she just knows. 💅

note: using "inc" in the constructor freezes the list of library dirs searched by the "POD2::Base" instance. if you don't use it, the up-to-date @INC is used at each call of "pod_dirs" — so dynamic changes in the Perl library path are taken into account. that's exactly what we meant with that "Most of the time, you don't want to mess with that" line up there. 😭

🌸 pod_dirs

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

used by "Pod::Perldoc" to find out where to look for translated pods. detective work, but make it Perl. 🔍

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" does not include POD directories which do not exist (tested with -d). if an explicit false value for this option (like test => 0) is given, that test is not done and "pod_dirs" includes all possible candidate 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. so 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. so enjoy them while they're here, bestie. 🦋

🌸 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. do it, don't be shy. 💖

🌸 print_pods

$pod2->print_pods;

prints all translated pods and the corresponding Perl version of the original files. all of them. the whole collection. 📚

🌸 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. and if you pass nothing, she reads @ARGV herself, because she's independent like that. 👑

---

✨ 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', ...);

go on, try it. I'll wait. 😌✨

🎀 THE INSTALLED FILES

if you wanna 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" does not try to repeat them here. she knows her lane and she stays in it. 💅

---

✨ AUTHORS ✨

• Enrico Sorcinelli <bepi at perl.it> — (the original POD2::IT code)
• Adriano Ferreira <ferreira at cpan.org>

legends, both of them. 👑👑

---

✨ SEE ALSO ✨

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

(the whole translation squad plus the tools that love them 🫶)

---

✨ 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. 🎀

---

and that's the whole page, bestie!! 💖 this was POD2::Base from the User Contributed Perl Documentation, rendered from perl v5.36.0 and dated 2022-12-04. go forth and translate some pods, you absolute icon. 🌈✨🦋💅