POD2::...::Base(3pm)

✨ NOME ✨

POD2::Base~[pt] — o módulo base pra traduções de documentação Perl 💖

okay so bestie, welcome to the POD2::...::Base(3pm) page, straight out of User Contributed Perl Documentation. this is the whole vibe: a lil base module that the translation girlies build on top of. it's giving infrastructure. 🎀

---

🌸 SINOPSE 🌸

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

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

---

🦋 DESCRIÇÃO 🦋

so this code is literally an abstraction of the code inside POD2::IT and POD2::FR — the modules that belong to the Italian and French translation projects for the docs that ship with the Perl interpreter. iconic lineage, no cap.

once the translation package is installed, you can reach the translated documentation with:

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

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

and the way that this works safely even on ancient versions of perldoc?? obsessed. it's not the most convenient thing ever but it always works. 💅

now, to level up support for reading these translated docs, the perldoc program (since version 3.14_01) got updated to find translated PODs like this:

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

(note: this support was shipped alongside version 5.10.0 of the Perl interpreter, recently made available on CPAN.)

the goal of this class is to provide a minimal base to help perldoc and translation-project authors do their thing. 🫶

---

💜 SUBCLASSES 💜

if you wanna write a translation package (and you've got some customization needs), your workload can be dramatically reduced if you make a subclass of POD2::Base. main character move fr.

like, a minimal lil example goes a little something like:

package POD2::TLH; # Klingon

use POD2::Base;
our @ISA = qw( POD2::Base );

sub search_perlfunc_re { # ajuda 'perldoc -f' a funcionar
    return 'Klingon Listing of Perl Functions';
}

1;

and then

$ perldoc -L tlh perlintro

is gonna serve you up the Perl intro in Klingon (as long as a POD2/TLH/perlintro.pod file was distributed together with POD2/TLH.pm) and

$ perldoc -L tlh -f pack

is gonna find the Klingon documentation for pack (if POD2/TLH/perlfunc.pod was made available too). 🧚✨

---

👑 MÉTODOS 👑

this module was designed as an OO class with a teeny tiny API. small but mighty, yk?

🌟 new

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

the constructor. creating an instance can be done kinda like:

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

where the supported options are:

• lang — specifies the language code we're interested in. this parameter is mandatory, but it can be extracted from the subclass name, as explained further down. 💖
• inc — this one is used to replace the list of directories for the Perl libraries where POD documents get looked up (that is, @INC). most of the time you are not gonna wanna touch this. this parameter is mostly useful for debugging and testing. an array ref is expected.

if POD2::ANY is a subclass of POD2::Base, the inherited constructor will work with no arguments, pulling 'ANY' out of the package name and using it as the language code you want.

heads up bestie: using inc in the constructor freezes the list of directories that the POD2::Base instance rummages through. if it's not used, the freshly-updated content of @INC gets used on every single call to pod_dirs (so dynamic changes to the path of the Perl libraries get noticed, slay). and that is what we meant by "most of the time, you are not gonna wanna touch this." 💅

🌟 pod_dirs

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

used by Pod::Perldoc to figure out where to look for translated PODs.

the default behavior of POD2::Base is to find every POD2/<lang>/ directory under the Perl library directories (@INC) or in the list handed over as the inc argument in the constructor.

the supported options are:

• test — by default, the return of pod_dirs does not include POD directories that don't exist (tested with -d). if an explicit false value is given for this option (like test => 0), that test isn't performed and pod_dirs includes all the POD2/<lang>/ candidates under the library directories. (useful for debugging this module, but honestly there are no other practical uses beyond that. 🙈)

🌟 search_perlfunc_re

$re = $pod2->search_perlfunc_re;

to implement perldoc -f <function>, the current Pod::Perldoc code uses a fixed string, "Alphabetical Listing of Perl Functions", or the return value of this method (as a regex) to skip the intro and reach the listing of builtin functions. so a translation package with the matching translation of perlfunc.pod must define this method to make perldoc -L <lang> -f <function> work correctly. periodt. 🔥

there are other methods documented below. however, they're probably gonna get obsoleted in future versions once more general methods for finding and displaying metadata about translated PODs get designed and implemented. the vibes are transitional, iykyk.

🌟 pod_info

$hashref = $pod2->pod_info;

used by POD2::Base itself and by its ancestors POD2::IT and POD2::FR. the return holds some metadata about the translated PODs used by the print_pod and print_pods methods.

when you're making subclasses following the POD2::IT and POD2::FR pattern, you should redefine this method with the up-to-date info on which POD translations the current package is providing. 🌸

🌟 print_pods

$pod2->print_pods;

shows (via print) all the translated PODs and the corresponding Perl version of the original files. it's giving a lil catalog moment. 🎀

🌟 print_pod

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

shows the corresponding Perl version of the original files associated with the PODs passed as arguments. 🦋

---

🌈 EXEMPLOS 🌈

🌟 POD2::TLH

a fuller version of POD2::TLH could look 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 can try it out:

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

---

💖 OS ARQUIVOS INSTALADOS 💖

if you wanna find out which POD files for a given language are installed alongside your Perl interpreter, you can use 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 there's a script eg/list.pl included with an extended version of this code. 🫶

the rules for finding POD in .pod, .pm and other files belong to the Pod::Perldoc module. so POD2::Base doesn't try to repeat that functionality here. nope, not her job. 💅

---

🎀 AUTORES 🎀

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

---

⭐ VEJA TAMBÉM ⭐

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

the original version of this document: POD2::Base.

(the purpose of this translation is to serve as a first test, to experiment with the support that the various Pod modules and Perl sites give to translated PODs.)

(This translation was supplied as a front test against the support of the many Pod modules and Perl sites on translated PODs.)

---

👑 COPYRIGHT E LICENÇA 👑

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 a wrap, bestie!! 💅✨ this page is from perl v5.36.0, dated 2022-12-04, and it lives under the name POD2::...::Base(3pm). go forth and translate, you absolute icon 🦋💖