| 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 |
|