Debian Codegraph @

README

raw
1 NAME
2 POD2::Base - Base module for translations of Perl documentation
3
4 SYNOPSIS
5 use POD2::Base;
6 $pod2 = POD2::Base->new({ lang => 'EO' });
7
8 @dirs = $pod2->pod_dirs;
9 $re = $pod2->search_perlfunc_re;
10
11 DESCRIPTION
12 This module is an abstraction of the code in POD2::IT and POD2::FR.
13 These modules belong to the Italian and the French translation projects
14 of core Perl pods.
15
16 Once a translation package had been installed, the translated
17 documentation can be accessed with:
18
19 $ perldoc POD2::<lang>::<podname>
20
21 (where <lang> is a language abbreviation like IT, FR, TLH, etc.)
22
23 This is guaranteed to work even for older versions of perldoc. It is not
24 very convenient but always works.
25
26 To improve the support to read translated docs, the perldoc utility
27 (since version 3.14_01) was updated to find translated PODs via:
28
29 $ perldoc -L IT <podpage>
30 $ perldoc -L FR -f <function>
31 $ perldoc -L TH -q <FAQregex>
32
33 (*Note*: this support was shipped together with the recently released
34 5.10.0 version the Perl interpreter.)
35
36 The objective of this class is to provide a minimum base to help
37 `perldoc' and authors of translation packages to do their job.
38
39 SUBCLASSING
40 If you want to write a translation package (and have some customization
41 needs), your work may be diminished if you subclass `Pod::Base'.
42
43 For example, a minimum example is provided below:
44
45 package POD2::TLH; # Klingon
46
47 use POD2::Base;
48 our @ISA = qw( POD2::Base );
49
50 sub search_perlfunc_re { # makes 'perldoc -f' work
51 return 'Klingon Listing of Perl Functions';
52 }
53
54 1;
55
56 And then
57
58 $ perldoc -L tlh perlintro
59
60 will present you the introduction of Perl in Klingon language (provided
61 a POD2/TLH/perlintro.pod file was shipped together with POD2/TLH.pm) and
62
63 $ perldoc -L tlh -f pack
64
65 will find you the Klingon documentation of `pack' (if
66 POD2/TLH/perlfunc.pod was made available as well).
67
68 METHODS
69 This module has been made into a proper class with a very small API.
70
71 new
72 $pod2 = POD2::Base->new(\%args);
73 $pod2 = POD2::ANY->new();
74
75 The constructor. An actual call might look like this:
76
77 $pod2 = POD2::Base->new({ lang => 'tlh' });
78
79 where the supported options are:
80
81 * "lang"
82 Specifies the language code we're interested in. This is
83 required, but can be extracted from the name of a subclass. Read
84 below.
85
86 * "inc"
87 This is used to override the list of Perl library directories
88 where POD documents are searched (namely, `@INC'). Most of the
89 time, you don't want to mess with that. It's handy for debugging
90 and testing.
91
92 It must be an array ref.
93
94 If `POD2::ANY' is a subclass of `POD2::Base', the inherited
95 constructor will work without arguments pulling 'ANY' from the
96 package name and using it as the intented language code.
97
98 Note that use of "inc" in the constructor freezes the list of
99 library dirs searched by the `POD2::Base' instance. If this is not
100 used, the up-to-date `@INC' is used at each call of `pod_dirs' (so
101 that dynamic changes in the Perl library path are taken into
102 account). That's what we meant with the "Most of the time, you don't
103 want to mess with that" mentioned above.
104
105 pod_dirs
106 @dirs = $pod2->pod_dirs;
107 @dirs = $pod2->pod_dirs(\%options);
108
109 Used by `Pod::Perldoc' to find out where to look for translated
110 pods.
111
112 The `POD2::Base' default behavior is to find POD2/<lang>/
113 directories under the current Perl library directories (`@INC') or
114 the list given as argument "inc" in the constructor.
115
116 The supported options are:
117
118 * "test"
119 By default, the return of `pod_dirs' do not include POD
120 directories which do not exist (tested with `-d'). If an
121 explicit false value for this option (like `test => 0') is
122 given, such test is not done and `pod_dirs' includes all
123 possible candidates POD2/<lang>/ under the library directories.
124 (Handy for debugging this module. Not much practical use for
125 anything else.)
126
127 search_perlfunc_re
128 $re = $pod2->search_perlfunc_re;
129
130 To implement `perldoc -f <function>' the current code of
131 `Pod::Perldoc' uses a hard coded string "Alphabetical Listing of
132 Perl Functions" or the return of this method (in a regexp) to skip
133 the introduction and reach the listing of core functions. Thus a
134 translation package with a corresponding translated perlfunc.pod
135 should define this method to make `perldoc -L <lang> -f <function>'
136 work properly.
137
138 There are other methods documented below. However, they will probably be
139 superseded in future versions when more general methods to find and
140 display metadata on translated PODs are designed and implemented.
141
142 pod_info
143 $hashref = $pod2->pod_info;
144
145 Used by `POD2::Base' itself. The return contains some metadata on
146 the translated PODs which is used by the methods `print_pod' and
147 `print_pods'.
148
149 When subclassing, you should override this with the current
150 information on what POD translations the current package is
151 providing.
152
153 print_pods
154 $pod2->print_pods;
155
156 Prints all translated pods and the corresponding Perl version of the
157 original files.
158
159 print_pod
160 $pod2->print_pod(@pages);
161 $pod2->print_pod(); # uses @ARGV
162
163 Prints the corresponding Perl version of the original files
164 corresponding to the pods passed as arguments.
165
166 EXAMPLES
167 POD2::TLH
168
169 A slightly extended version of `POD2::TLH' goes like this:
170
171 package POD2::TLH; # Klingon
172
173 use POD2::Base;
174 our @ISA = qw( POD2::Base );
175
176 sub search_perlfunc_re {
177 return 'Klingon Listing of Perl Functions';
178 }
179
180 sub pod_info {
181 return { perlintro => '5.8.8' };
182 }
183
184 1;
185
186 And you may try:
187
188 use POD2::TLH;
189 my $pod2 = 'POD2::TLH';
190 $pod2->print_pods();
191 $pod2->print_pod('pod_foo', 'pod_baz', ...);
192
193 THE INSTALLED FILES
194
195 If you want to find out which language-specific POD files are installed
196 at your Perl, you could use a code similar to this.
197
198 use File::Find;
199 use POD2::Base;
200
201 my $pod2 = POD2::Base->new({ lang => $lang });
202
203 my @files;
204 find sub { push @files, $File::Find::name } if -f },
205 $pod2->pod_dirs;
206 print "$_\n" for @files;
207
208 In the `POD2-Base' distribution tarball, a script eg/list.pl is included
209 with an improved version of this code.
210
211 The rules of finding POD in .pod, .pm files and others belong to
212 Pod::Perldoc. So `POD2::Base' do not try to repeat them here.
213
214 AUTHORS
215 Enrico Sorcinelli <bepi at perl.it> (the original POD2::IT code)
216
217 Adriano Ferreira <ferreira at cpan.org>
218
219 SEE ALSO
220 POD2::IT, POD2::FR, POD2::LT, POD2::CN, perldoc, perl.
221
222 COPYRIGHT AND LICENCE
223 Copyright (C) 2004-2006 Perl.it / Perl Mongers Italia
224
225 This library is free software; you can redistribute it and/or modify it
226 under the same terms as Perl itself.
227