.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "POD2::Base 3pm"
.TH POD2::Base 3pm "2008-02-24" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
POD2::Base \- Base module for translations of Perl documentation
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use POD2::Base;
\&    $pod2 = POD2::Base\->new({ lang => \*(AqEO\*(Aq });
\&
\&    @dirs = $pod2\->pod_dirs;
\&    $re = $pod2\->search_perlfunc_re;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is an abstraction of the code in \s-1POD2::IT\s0 
and \s-1POD2::FR\s0. These modules belong to the Italian and 
the French translation projects of core Perl pods.
.PP
Once a translation package had been installed, the translated 
documentation can be accessed with:
.PP
.Vb 1
\&    $ perldoc POD2::<lang>::<podname>
.Ve
.PP
(where <lang> is a language abbreviation like \s-1IT\s0, \s-1FR\s0,
\&\s-1TLH\s0, etc.)
.PP
This is guaranteed to work even for older versions of
perldoc. It is not very convenient but always works.
.PP
To improve the support to read translated docs, the
perldoc utility (since version 3.14_01) was updated 
to find translated PODs via:
.PP
.Vb 3
\&    $ perldoc \-L IT <podpage>
\&    $ perldoc \-L FR \-f <function>
\&    $ perldoc \-L TH \-q <FAQregex>
.Ve
.PP
(\fINote\fR: this support was shipped together with the
recently released 5.10.0 version the Perl interpreter.)
.PP
The objective of this class is to provide a minimum
base to help \f(CW\*(C`perldoc\*(C'\fR and authors of translation
packages to do their job.
.SH "SUBCLASSING"
.IX Header "SUBCLASSING"
If you want to write a translation package (and have
some customization needs), your
work may be diminished if you subclass \f(CW\*(C`Pod::Base\*(C'\fR.
.PP
For example, a minimum example is provided below:
.PP
.Vb 1
\&    package POD2::TLH; # Klingon
\&
\&    use POD2::Base;
\&    our @ISA = qw( POD2::Base );
\&
\&    sub search_perlfunc_re { # makes \*(Aqperldoc \-f\*(Aq work
\&        return \*(AqKlingon Listing of Perl Functions\*(Aq;
\&    }
\&
\&    1;
.Ve
.PP
And then
.PP
.Vb 1
\&    $ perldoc \-L tlh perlintro
.Ve
.PP
will present you the introduction of Perl in Klingon language 
(provided a \fIPOD2/TLH/perlintro.pod\fR file was shipped together
with \fI\s-1POD2/TLH\s0.pm\fR) and
.PP
.Vb 1
\&    $ perldoc \-L tlh \-f pack
.Ve
.PP
will find you the Klingon documentation of \f(CW\*(C`pack\*(C'\fR (if
\&\fIPOD2/TLH/perlfunc.pod\fR was made available as well).
.SH "METHODS"
.IX Header "METHODS"
This module has been made into a proper class
with a very small \s-1API\s0.
.IP "\fBnew\fR" 4
.IX Item "new"
.Vb 2
\&    $pod2 = POD2::Base\->new(\e%args);
\&    $pod2 = POD2::ANY\->new();
.Ve
.Sp
The constructor. An actual call might look like this:
.Sp
.Vb 1
\&    $pod2 = POD2::Base\->new({ lang => \*(Aqtlh\*(Aq });
.Ve
.Sp
where the supported options are:
.RS 4
.IP "\(bu" 4
\&\*(L"lang\*(R"
.Sp
Specifies the language code we're interested in.
This is required, but can be extracted from
the name of a subclass. Read below.
.IP "\(bu" 4
\&\*(L"inc\*(R"
.Sp
This is used to override the list of Perl
library directories where \s-1POD\s0 documents 
are searched (namely, \f(CW@INC\fR). Most of the
time, you don't want to mess with that.
It's handy for debugging and testing.
.Sp
It must be an array ref.
.RE
.RS 4
.Sp
If \f(CW\*(C`POD2::ANY\*(C'\fR is a subclass of \f(CW\*(C`POD2::Base\*(C'\fR, the
inherited constructor will work without arguments
pulling '\s-1ANY\s0' from the package name and using it
as the intented language code.
.Sp
Note that use of \*(L"inc\*(R" in the constructor
freezes the list of library dirs searched by the
\&\f(CW\*(C`POD2::Base\*(C'\fR instance. If this is not used,
the up-to-date \f(CW@INC\fR is used at each call
of \f(CW\*(C`pod_dirs\*(C'\fR (so that dynamic changes in
the Perl library path are taken into account).
That's what we meant with the
\&\*(L"Most of the time, you don't want to mess with that\*(R" 
mentioned above.
.RE
.IP "\fBpod_dirs\fR" 4
.IX Item "pod_dirs"
.Vb 2
\&    @dirs = $pod2\->pod_dirs;
\&    @dirs = $pod2\->pod_dirs(\e%options);
.Ve
.Sp
Used by \f(CW\*(C`Pod::Perldoc\*(C'\fR to find out where to
look for translated pods.
.Sp
The \f(CW\*(C`POD2::Base\*(C'\fR default behavior is to find
\&\fIPOD2/<lang>/\fR directories under the
current Perl library directories (\f(CW@INC\fR) or
the list given as argument \*(L"inc\*(R" in the constructor.
.Sp
The supported options are:
.RS 4
.IP "\(bu" 4
\&\*(L"test\*(R"
.Sp
By default, the return of \f(CW\*(C`pod_dirs\*(C'\fR do not
include \s-1POD\s0 directories which do not exist (tested
with \f(CW\*(C`\-d\*(C'\fR). If an explicit false value for this option (like
\&\f(CW\*(C`test => 0\*(C'\fR) is given, such test is not done
and \f(CW\*(C`pod_dirs\*(C'\fR includes all possible candidates
\&\fIPOD2/<lang>/\fR under the library directories.
(Handy for debugging this module. Not much practical
use for anything else.)
.RE
.RS 4
.RE
.IP "\fBsearch_perlfunc_re\fR" 4
.IX Item "search_perlfunc_re"
.Vb 1
\&    $re = $pod2\->search_perlfunc_re;
.Ve
.Sp
To implement \f(CW\*(C`perldoc \-f <function>\*(C'\fR
the current code of \f(CW\*(C`Pod::Perldoc\*(C'\fR uses a hard coded string
\&\*(L"Alphabetical Listing of Perl Functions\*(R" or the return
of this method (in a regexp) to skip the introduction
and reach the listing of core functions.
Thus a translation package with a corresponding translated
\&\fIperlfunc.pod\fR should define this method to 
make \f(CW\*(C`perldoc \-L <lang> \-f <function>\*(C'\fR
work properly.
.PP
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.
.IP "\fBpod_info\fR" 4
.IX Item "pod_info"
.Vb 1
\&    $hashref = $pod2\->pod_info;
.Ve
.Sp
Used by \f(CW\*(C`POD2::Base\*(C'\fR itself. The return contains
some metadata on the translated PODs which is used
by the methods \f(CW\*(C`print_pod\*(C'\fR and \f(CW\*(C`print_pods\*(C'\fR.
.Sp
When subclassing, you \fBshould\fR override this
with the current information on what \s-1POD\s0
translations the current package is providing.
.IP "\fBprint_pods\fR" 4
.IX Item "print_pods"
.Vb 1
\&    $pod2\->print_pods;
.Ve
.Sp
Prints all translated pods and the corresponding Perl version
of the original files.
.IP "\fBprint_pod\fR" 4
.IX Item "print_pod"
.Vb 2
\&    $pod2\->print_pod(@pages);
\&    $pod2\->print_pod(); # uses @ARGV
.Ve
.Sp
Prints the corresponding Perl version of the original files
corresponding to the pods passed as arguments.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "\s-1POD2::TLH\s0"
.IX Subsection "POD2::TLH"
A slightly extended version of \f(CW\*(C`POD2::TLH\*(C'\fR 
goes like this:
.PP
.Vb 1
\&    package POD2::TLH; # Klingon
\&
\&    use POD2::Base;
\&    our @ISA = qw( POD2::Base );
\&
\&    sub search_perlfunc_re {
\&        return \*(AqKlingon Listing of Perl Functions\*(Aq;
\&    }
\&
\&    sub pod_info {
\&        return { perlintro => \*(Aq5.8.8\*(Aq };
\&    }
\&
\&    1;
.Ve
.PP
And you may try:
.PP
.Vb 4
\&    use POD2::TLH;
\&    my $pod2 = \*(AqPOD2::TLH\*(Aq;
\&    $pod2\->print_pods();
\&    $pod2\->print_pod(\*(Aqpod_foo\*(Aq, \*(Aqpod_baz\*(Aq, ...);
.Ve
.SS "\s-1THE\s0 \s-1INSTALLED\s0 \s-1FILES\s0"
.IX Subsection "THE INSTALLED FILES"
If you want to find out which language-specific
\&\s-1POD\s0 files are installed at your Perl,
you could use a code similar to this.
.PP
.Vb 2
\&    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 "$_\en" for @files;
.Ve
.PP
In the \f(CW\*(C`POD2\-Base\*(C'\fR distribution tarball, a script
\&\fIeg/list.pl\fR is included with an improved
version of this code.
.PP
The rules of finding \s-1POD\s0 in \fI.pod\fR, \fI.pm\fR files and others
belong to Pod::Perldoc. So \f(CW\*(C`POD2::Base\*(C'\fR do not try
to repeat them here.
.SH "AUTHORS"
.IX Header "AUTHORS"
Enrico Sorcinelli <bepi at perl.it> (the original \s-1POD2::IT\s0 code)
.PP
Adriano Ferreira <ferreira at cpan.org>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1POD2::IT\s0, \s-1POD2::FR\s0, \s-1POD2::LT\s0, \s-1POD2::CN\s0, perldoc, perl.
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
Copyright (C) 2004\-2006 Perl.it / Perl Mongers Italia
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.