.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "POD2::PT::POD2::Base 3pm"
.TH POD2::PT::POD2::Base 3pm "2022-12-04" "perl v5.36.0" "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 "NOME"
.IX Header "NOME"
POD2::Base~[pt] \- Módulo básico para traduções de documentação Perl
.SH "SINOPSE"
.IX Header "SINOPSE"
.Vb 2
\&    use POD2::Base;
\&    $pod2 = POD2::Base\->new({ lang => \*(AqEO\*(Aq });
\&
\&    @dirs = $pod2\->pod_dirs;
\&    $re = $pod2\->search_perlfunc_re;
.Ve
.SH "DESCRIÇÃO"
.IX Header "DESCRIÇÃO"
Este código é uma abstração do código em \s-1POD2::IT\s0 e
\&\s-1POD2::FR,\s0 módulos que pertencem aos projetos 
italiano e francês de tradução dos documentos 
que acompanham o interpretador Perl.
.PP
Com o pacote de tradução já instalado, a documentação
traduzida pode ser acessada através do comando:
.PP
.Vb 1
\&    $ perldoc POD2::<lang>::<podname>
.Ve
.PP
(onde <lang> é uma abreviação para linguagem como
\&\s-1IT, FR, TLH,\s0 etc.)
.PP
Isto funciona seguramente até para as versões antigas
do perldoc. Não é muito conveniente mas sempre funciona.
.PP
Para incrementar o suporte para leitura destes documentos
traduzidos, o programa perldoc (desde a versão 3.14_01)
foi atualizado para encontrar PODs traduzidos assim:
.PP
.Vb 3
\&    $ perldoc \-L IT <podpage>
\&    $ perldoc \-L FR \-f <function>
\&    $ perldoc \-L TLH \-q <FAQregex>
.Ve
.PP
(Nota: Este suporte foi distribuído junto da versão
5.10.0 do interpretador Perl recentemente disponilizado
no \s-1CPAN.\s0)
.PP
O objetivo desta classe é prover uma base mínima para
ajudar o \f(CW\*(C`perldoc\*(C'\fR e os autores de projetos de tradução
a fazerem seu trabalho.
.SH "SUBCLASSES"
.IX Header "SUBCLASSES"
Se você quer escrever um pacote de tradução (e tem algumas
necessidades de personalização), seu trabalho pode ser
diminuído se você criar uma subclasse de \f(CW\*(C`POD2::Base\*(C'\fR.
.PP
Por exemplo, um exemplo mínimo é ilustrado abaixo.
.PP
.Vb 1
\&    package POD2::TLH; # Klingon
\&
\&    use POD2::Base;
\&    our @ISA = qw( POD2::Base );
\&
\&    sub search_perlfunc_re { # ajuda \*(Aqperldoc \-f\*(Aq a funcionar
\&        return \*(AqKlingon Listing of Perl Functions\*(Aq;
\&    }
\&
\&    1;
.Ve
.PP
E então
.PP
.Vb 1
\&    $ perldoc \-L tlh perlintro
.Ve
.PP
vai lhe apresentar a introdução de Perl na linguagem Klingon
(desde que um arquivo \fIPOD2/TLH/perlintro.pod\fR tenha sido
distribuído junto com \fI\s-1POD2/TLH\s0.pm\fR) e
.PP
.Vb 1
\&    $ perldoc \-L tlh \-f pack
.Ve
.PP
vai encontrar a documentação em Klingon de \f(CW\*(C`pack\*(C'\fR (se 
\&\fIPOD2/TLH/perlfunc.pod\fR foi disponibilizado também).
.SH "MÉTODOS"
.IX Header "MÉTODOS"
Este módulo foi projetado como uma classe \s-1OO\s0 com uma
\&\s-1API\s0 bem pequena.
.IP "\fBnew\fR" 4
.IX Item "new"
.Vb 2
\&    $pod2 = POD2::Base\->new(\e%args);
\&    $pod2 = POD2::ANY\->new();
.Ve
.Sp
O constructor. A criação de uma instância pode se fazer
de modo similar a:
.Sp
.Vb 1
\&    $pod2 = POD2::Base\->new({ lang => \*(Aqtlh\*(Aq });
.Ve
.Sp
onde as opções suportadas são:
.RS 4
.IP "\(bu" 4
\&\*(L"lang\*(R"
.Sp
Especifica o código da linguagem em que estamos interessados.
Este parâmetro é obrigatório, mas pode ser extraído
do nome da subclasse, como explicado mais abaixo.
.IP "\(bu" 4
\&\*(L"inc\*(R"
.Sp
Este parâmetro é usado para substituir a lista
de diretórios para as bibliotecas Perl onde procuram-se
os documentos \s-1POD\s0 (ou seja, \f(CW@INC\fR). Na maior parte
do tempo, você não vai querer mexer com isto.
Este parâmetro é mais útil para \fIdebugging\fR e testes.
.Sp
Espera-se um \fIarray ref\fR.
.RE
.RS 4
.Sp
Se \f(CW\*(C`POD2::ANY\*(C'\fR é uma subclasse de \f(CW\*(C`POD2::Base\*(C'\fR,
o construtor herdado funcionará sem argumentos
extraindo '\s-1ANY\s0' do nome do pacote e usando-o como
o código da linguagem desejada.
.Sp
Note que o uso de \*(L"inc\*(R" no construtor
congela a lista de diretórios vasculhados pela
instância \f(CW\*(C`POD2::Base\*(C'\fR. Se não é usado,
o conteúdo atualizado de \f(CW@INC\fR é usado em cada
chamada de \f(CW\*(C`pod_dirs\*(C'\fR (de tal forma que mudanças
dinâmicas no \fIpath\fR para as bibliotecas Perl 
são percebidas). É isto que queríamos dizer
com \*(L"Na maior parte
do tempo, você não vai querer mexer com isto.\*(R"
.RE
.IP "\fBpod_dirs\fR" 4
.IX Item "pod_dirs"
.Vb 2
\&    @dirs = $pod2\->pod_dirs;
\&    @dirs = $pod2\->pod_dirs(\e%options);
.Ve
.Sp
Usado por \f(CW\*(C`Pod::Perldoc\*(C'\fR para descobrir onde
procurar por PODs traduzidos.
.Sp
O comportamento padrão de \f(CW\*(C`POD2::Base\*(C'\fR é encontrar
cada diretório \fIPOD2/<lang>/\fR sob os diretórios
de bibliotecas Perl (\f(CW@INC\fR) ou na lista
dada como o argumento \*(L"inc\*(R" no construtor.
.Sp
As opções suportadas são:
.RS 4
.IP "\(bu" 4
\&\*(L"test\*(R"
.Sp
Por \fIdefault\fR, o retorno de \f(CW\*(C`pod_dirs\*(C'\fR não inclui
diretórios \s-1POD\s0 que não existem (testados com \f(CW\*(C`\-d\*(C'\fR).
Se um valor falso explícito é dado para esta
opção (por exemplo, \f(CW\*(C`test => 0\*(C'\fR), este teste
não é feito e \f(CW\*(C`pod_dirs\*(C'\fR inclui todos candidatos
\&\fIPOD2/<lang>/\fR abaixo dos diretórios de bibliotecas.
(Útil para o \fIdebugging\fR deste módulo, mas
sem outros usos práticos além deste.)
.RE
.RS 4
.RE
.IP "\fBsearch_perlfunc_re\fR" 4
.IX Item "search_perlfunc_re"
.Vb 1
\&    $re = $pod2\->search_perlfunc_re;
.Ve
.Sp
Para implementar \f(CW\*(C`perldoc \-f <function>\*(C'\fR
o código atual de \f(CW\*(C`Pod::Perldoc\*(C'\fR usa um \fIstring\fR
fixo \*(L"Alphabetical Listing of Perl Functions\*(R" ou o
retorno deste método (em uma regex) para pular
a introdução e alcançar a listagem das funções
\&\fIbuiltin\fR. Então um pacote de tradução com
a correspondente tradução de \fIperlfunc.pod\fR deve
definir este método para fazer
\&\f(CW\*(C`perldoc \-L <lang> \-f <function>\*(C'\fR
funcionar corretamente.
.PP
Há outros métodos documentados abaixo. Entretanto,
eles provavelmente serão tornados obsoletos em
versões futuras quando forem projetados e 
implementados métodos mais gerais de encontrar
e mostrar os metadados sobre os PODs traduzidos.
.IP "\fBpod_info\fR" 4
.IX Item "pod_info"
.Vb 1
\&    $hashref = $pod2\->pod_info;
.Ve
.Sp
Usado pelo próprio \f(CW\*(C`POD2::Base\*(C'\fR e seus ancestrais
\&\f(CW\*(C`POD2::IT\*(C'\fR e \f(CW\*(C`POD2::FR\*(C'\fR. O retorno contém 
alguns metadados sobre os PODs traduzidos usados
pelos métodos \f(CW\*(C`print_pod\*(C'\fR e \f(CW\*(C`print_pods\*(C'\fR.
.Sp
Ao fazer subclasses seguindo o padrão de \f(CW\*(C`POD2::IT\*(C'\fR
e \f(CW\*(C`POD2::FR\*(C'\fR, você \fBdeve\fR redefinir este método
com a informação atual sobre quais traduções
\&\s-1POD\s0 o pacote atual está disponibilizando.
.IP "\fBprint_pods\fR" 4
.IX Item "print_pods"
.Vb 1
\&    $pod2\->print_pods;
.Ve
.Sp
Mostra (via \f(CW\*(C`print\*(C'\fR) todos PODs traduzidos e a versão correspondente
de Perl dos arquivos originais.
.IP "\fBprint_pod\fR" 4
.IX Item "print_pod"
.Vb 2
\&    $pod2\->print_pod(@pages);
\&    $pod2\->print_pod(); # usa @ARGV
.Ve
.Sp
Mostra a versão de Perl correspondente dos arquivos originais
associados aos PODs passados como argumentos.
.SH "EXEMPLOS"
.IX Header "EXEMPLOS"
.SS "\s-1POD2::TLH\s0"
.IX Subsection "POD2::TLH"
Uma versão mais completa de \f(CW\*(C`POD2::TLH\*(C'\fR 
pode-se parecer com isto:
.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
E você pode experimentar:
.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-1OS ARQUIVOS INSTALADOS\s0"
.IX Subsection "OS ARQUIVOS INSTALADOS"
Se você quer descobrir quais arquivos PODs
de uma dada linguagem que estão instalados
junto com seu interpretador Perl, você pode
usar um código similar a este.
.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
Na distribuição \f(CW\*(C`POD2\-Base\*(C'\fR, é incluído um script
\&\fIeg/list.pl\fR com uma versão estendida
deste código.
.PP
As regras para encontrar \s-1POD\s0 em arquivos \fI.pod\fR, \fI.pm\fR e 
outros pertencem ao módulo Pod::Perldoc. Assim \f(CW\*(C`POD2::Base\*(C'\fR 
não tenta repetir esta funcionalidade aqui.
.SH "AUTORES"
.IX Header "AUTORES"
Enrico Sorcinelli <bepi at perl.it> (pelo código original em \s-1POD2::IT\s0)
.PP
Adriano Ferreira <ferreira at cpan.org>
.SH "VEJA TAMBÉM"
.IX Header "VEJA TAMBÉM"
\&\s-1POD2::IT\s0, \s-1POD2::FR\s0, \s-1POD2::LT\s0, \s-1POD2::CN\s0, perldoc, perl.
.PP
A versão original deste documento: POD2::Base.
.PP
(O propósito desta tradução é servir como um primeiro teste 
para experimentar o suporte dos vários modules Pod e \fIsites\fR Perl
aos PODs traduzidos.)
.PP
(This translation was supplied as a front test against the support
of the many Pod modules and Perl sites on translated PODs.)
.SH "COPYRIGHT E LICENÇA"
.IX Header "COPYRIGHT E LICENÇA"
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.