1POD2::Base(3)         User Contributed Perl Documentation        POD2::Base(3)
2
3
4

NAME

6       POD2::Base - Base module for translations of Perl documentation
7

SYNOPSIS

9           use POD2::Base;
10           $pod2 = POD2::Base->new({ lang => 'EO' });
11
12           @dirs = $pod2->pod_dirs;
13           $re = $pod2->search_perlfunc_re;
14

DESCRIPTION

16       This module is an abstraction of the code in POD2::IT and POD2::FR.
17       These modules belong to the Italian and the French translation projects
18       of core Perl pods.
19
20       Once a translation package had been installed, the translated
21       documentation can be accessed with:
22
23           $ perldoc POD2::<lang>::<podname>
24
25       (where <lang> is a language abbreviation like IT, FR, TLH, etc.)
26
27       This is guaranteed to work even for older versions of perldoc. It is
28       not very convenient but always works.
29
30       To improve the support to read translated docs, the perldoc utility
31       (since version 3.14_01) was updated to find translated PODs via:
32
33           $ perldoc -L IT <podpage>
34           $ perldoc -L FR -f <function>
35           $ perldoc -L TH -q <FAQregex>
36
37       (Note: this support was shipped together with the recently released
38       5.10.0 version the Perl interpreter.)
39
40       The objective of this class is to provide a minimum base to help
41       "perldoc" and authors of translation packages to do their job.
42

SUBCLASSING

44       If you want to write a translation package (and have some customization
45       needs), your work may be diminished if you subclass "Pod::Base".
46
47       For example, a minimum example is provided below:
48
49           package POD2::TLH; # Klingon
50
51           use POD2::Base;
52           our @ISA = qw( POD2::Base );
53
54           sub search_perlfunc_re { # makes 'perldoc -f' work
55               return 'Klingon Listing of Perl Functions';
56           }
57
58           1;
59
60       And then
61
62           $ perldoc -L tlh perlintro
63
64       will present you the introduction of Perl in Klingon language (provided
65       a POD2/TLH/perlintro.pod file was shipped together with POD2/TLH.pm)
66       and
67
68           $ perldoc -L tlh -f pack
69
70       will find you the Klingon documentation of "pack" (if
71       POD2/TLH/perlfunc.pod was made available as well).
72

METHODS

74       This module has been made into a proper class with a very small API.
75
76       new
77               $pod2 = POD2::Base->new(\%args);
78               $pod2 = POD2::ANY->new();
79
80           The constructor. An actual call might look like this:
81
82               $pod2 = POD2::Base->new({ lang => 'tlh' });
83
84           where the supported options are:
85
86           •   "lang"
87
88               Specifies the language code we're interested in.  This is
89               required, but can be extracted from the name of a subclass.
90               Read below.
91
92           •   "inc"
93
94               This is used to override the list of Perl library directories
95               where POD documents are searched (namely, @INC). Most of the
96               time, you don't want to mess with that.  It's handy for
97               debugging and testing.
98
99               It must be an array ref.
100
101           If "POD2::ANY" is a subclass of "POD2::Base", the inherited
102           constructor will work without arguments pulling 'ANY' from the
103           package name and using it as the intented language code.
104
105           Note that use of "inc" in the constructor freezes the list of
106           library dirs searched by the "POD2::Base" instance. If this is not
107           used, the up-to-date @INC is used at each call of "pod_dirs" (so
108           that dynamic changes in the Perl library path are taken into
109           account).  That's what we meant with the "Most of the time, you
110           don't want to mess with that" mentioned above.
111
112       pod_dirs
113               @dirs = $pod2->pod_dirs;
114               @dirs = $pod2->pod_dirs(\%options);
115
116           Used by "Pod::Perldoc" to find out where to look for translated
117           pods.
118
119           The "POD2::Base" default behavior is to find POD2/<lang>/
120           directories under the current Perl library directories (@INC) or
121           the list given as argument "inc" in the constructor.
122
123           The supported options are:
124
125           •   "test"
126
127               By default, the return of "pod_dirs" do not include POD
128               directories which do not exist (tested with "-d"). If an
129               explicit false value for this option (like "test => 0") is
130               given, such test is not done and "pod_dirs" includes all
131               possible candidates POD2/<lang>/ under the library directories.
132               (Handy for debugging this module. Not much practical use for
133               anything else.)
134
135       search_perlfunc_re
136               $re = $pod2->search_perlfunc_re;
137
138           To implement "perldoc -f <function>" the current code of
139           "Pod::Perldoc" uses a hard coded string "Alphabetical Listing of
140           Perl Functions" or the return of this method (in a regexp) to skip
141           the introduction and reach the listing of core functions.  Thus a
142           translation package with a corresponding translated perlfunc.pod
143           should define this method to make "perldoc -L <lang> -f <function>"
144           work properly.
145
146       There are other methods documented below. However, they will probably
147       be superseded in future versions when more general methods to find and
148       display metadata on translated PODs are designed and implemented.
149
150       pod_info
151               $hashref = $pod2->pod_info;
152
153           Used by "POD2::Base" itself. The return contains some metadata on
154           the translated PODs which is used by the methods "print_pod" and
155           "print_pods".
156
157           When subclassing, you should override this with the current
158           information on what POD translations the current package is
159           providing.
160
161       print_pods
162               $pod2->print_pods;
163
164           Prints all translated pods and the corresponding Perl version of
165           the original files.
166
167       print_pod
168               $pod2->print_pod(@pages);
169               $pod2->print_pod(); # uses @ARGV
170
171           Prints the corresponding Perl version of the original files
172           corresponding to the pods passed as arguments.
173

EXAMPLES

175   POD2::TLH
176       A slightly extended version of "POD2::TLH" goes like this:
177
178           package POD2::TLH; # Klingon
179
180           use POD2::Base;
181           our @ISA = qw( POD2::Base );
182
183           sub search_perlfunc_re {
184               return 'Klingon Listing of Perl Functions';
185           }
186
187           sub pod_info {
188               return { perlintro => '5.8.8' };
189           }
190
191           1;
192
193       And you may try:
194
195           use POD2::TLH;
196           my $pod2 = 'POD2::TLH';
197           $pod2->print_pods();
198           $pod2->print_pod('pod_foo', 'pod_baz', ...);
199
200   THE INSTALLED FILES
201       If you want to find out which language-specific POD files are installed
202       at your Perl, you could use a code similar to this.
203
204           use File::Find;
205           use POD2::Base;
206
207           my $pod2 = POD2::Base->new({ lang => $lang });
208
209           my @files;
210           find sub { push @files, $File::Find::name } if -f },
211                $pod2->pod_dirs;
212           print "$_\n" for @files;
213
214       In the "POD2-Base" distribution tarball, a script eg/list.pl is
215       included with an improved version of this code.
216
217       The rules of finding POD in .pod, .pm files and others belong to
218       Pod::Perldoc. So "POD2::Base" do not try to repeat them here.
219

AUTHORS

221       Enrico Sorcinelli <bepi at perl.it> (the original POD2::IT code)
222
223       Adriano Ferreira <ferreira at cpan.org>
224

SEE ALSO

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

COPYRIGHT AND LICENCE

229       Copyright (C) 2004-2006 Perl.it / Perl Mongers Italia
230
231       This library is free software; you can redistribute it and/or modify it
232       under the same terms as Perl itself.
233
234
235
236perl v5.36.0                      2023-01-20                     POD2::Base(3)