=encoding utf8
=head1 NAME/NOME
POD2::Base~[pt] - Módulo básico para traduções de documentação Perl
=head1 SINOPSE
use POD2::Base;
$pod2 = POD2::Base->new({ lang => 'EO' });
@dirs = $pod2->pod_dirs;
$re = $pod2->search_perlfunc_re;
=head1 DESCRIÇÃO
Este código é uma abstração do código em POD2::IT e
POD2::FR, módulos que pertencem aos projetos
italiano e francês de tradução dos documentos
que acompanham o interpretador Perl.
Com o pacote de tradução já instalado, a documentação
traduzida pode ser acessada através do comando:
$ perldoc POD2::<lang>::<podname>
(onde <lang> é uma abreviação para linguagem como
IT, FR, TLH, etc.)
Isto funciona seguramente até para as versões antigas
do L<perldoc>. Não é muito conveniente mas sempre funciona.
Para incrementar o suporte para leitura destes documentos
traduzidos, o programa L<perldoc> (desde a versão 3.14_01)
foi atualizado para encontrar PODs traduzidos assim:
$ perldoc -L IT <podpage>
$ perldoc -L FR -f <function>
$ perldoc -L TLH -q <FAQregex>
(Nota: Este suporte foi distribuído junto da versão
5.10.0 do interpretador Perl recentemente disponilizado
no CPAN.)
O objetivo desta classe é prover uma base mínima para
ajudar o C<perldoc> e os autores de projetos de tradução
a fazerem seu trabalho.
=head1 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 C<POD2::Base>.
Por exemplo, um exemplo mínimo é ilustrado abaixo.
package POD2::TLH; # Klingon
use POD2::Base;
our @ISA = qw( POD2::Base );
sub search_perlfunc_re { # ajuda 'perldoc -f' a funcionar
return 'Klingon Listing of Perl Functions';
}
1;
E então
$ perldoc -L tlh perlintro
vai lhe apresentar a introdução de Perl na linguagem Klingon
(desde que um arquivo F<POD2/TLH/perlintro.pod> tenha sido
distribuído junto com F<POD2/TLH.pm>) e
$ perldoc -L tlh -f pack
vai encontrar a documentação em Klingon de C<pack> (se
F<POD2/TLH/perlfunc.pod> foi disponibilizado também).
=head1 MÉTODOS
Este módulo foi projetado como uma classe OO com uma
API bem pequena.
=over 4
=item B<new>
$pod2 = POD2::Base->new(\%args);
$pod2 = POD2::ANY->new();
O constructor. A criação de uma instância pode se fazer
de modo similar a:
$pod2 = POD2::Base->new({ lang => 'tlh' });
onde as opções suportadas são:
=over 4
=item * "lang"
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.
=item * "inc"
Este parâmetro é usado para substituir a lista
de diretórios para as bibliotecas Perl onde procuram-se
os documentos POD (ou seja, C<@INC>). Na maior parte
do tempo, você não vai querer mexer com isto.
Este parâmetro é mais útil para I<debugging> e testes.
Espera-se um I<array ref>.
=back
Se C<POD2::ANY> é uma subclasse de C<POD2::Base>,
o construtor herdado funcionará sem argumentos
extraindo 'ANY' do nome do pacote e usando-o como
o código da linguagem desejada.
Note que o uso de "inc" no construtor
congela a lista de diretórios vasculhados pela
instância C<POD2::Base>. Se não é usado,
o conteúdo atualizado de C<@INC> é usado em cada
chamada de C<pod_dirs> (de tal forma que mudanças
dinâmicas no I<path> para as bibliotecas Perl
são percebidas). É isto que queríamos dizer
com "Na maior parte
do tempo, você não vai querer mexer com isto."
=item B<pod_dirs>
@dirs = $pod2->pod_dirs;
@dirs = $pod2->pod_dirs(\%options);
Usado por C<Pod::Perldoc> para descobrir onde
procurar por PODs traduzidos.
O comportamento padrão de C<POD2::Base> é encontrar
cada diretório F<< POD2/<lang>/ >> sob os diretórios
de bibliotecas Perl (C<@INC>) ou na lista
dada como o argumento "inc" no construtor.
As opções suportadas são:
=over 4
=item * "test"
Por I<default>, o retorno de C<pod_dirs> não inclui
diretórios POD que não existem (testados com C<-d>).
Se um valor falso explícito é dado para esta
opção (por exemplo, C<< test => 0 >>), este teste
não é feito e C<pod_dirs> inclui todos candidatos
F<< POD2/<lang>/ >> abaixo dos diretórios de bibliotecas.
(Útil para o I<debugging> deste módulo, mas
sem outros usos práticos além deste.)
=back
=item B<search_perlfunc_re>
$re = $pod2->search_perlfunc_re;
Para implementar C<< perldoc -f <function> >>
o código atual de C<Pod::Perldoc> usa um I<string>
fixo "Alphabetical Listing of Perl Functions" ou o
retorno deste método (em uma regex) para pular
a introdução e alcançar a listagem das funções
I<builtin>. Então um pacote de tradução com
a correspondente tradução de F<perlfunc.pod> deve
definir este método para fazer
C<< perldoc -L <lang> -f <function> >>
funcionar corretamente.
=back
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.
=over 4
=item B<pod_info>
$hashref = $pod2->pod_info;
Usado pelo próprio C<POD2::Base> e seus ancestrais
C<POD2::IT> e C<POD2::FR>. O retorno contém
alguns metadados sobre os PODs traduzidos usados
pelos métodos C<print_pod> e C<print_pods>.
Ao fazer subclasses seguindo o padrão de C<POD2::IT>
e C<POD2::FR>, você B<deve> redefinir este método
com a informação atual sobre quais traduções
POD o pacote atual está disponibilizando.
=item B<print_pods>
$pod2->print_pods;
Mostra (via C<print>) todos PODs traduzidos e a versão correspondente
de Perl dos arquivos originais.
=item B<print_pod>
$pod2->print_pod(@pages);
$pod2->print_pod(); # usa @ARGV
Mostra a versão de Perl correspondente dos arquivos originais
associados aos PODs passados como argumentos.
=back
=head1 EXEMPLOS
=head2 POD2::TLH
Uma versão mais completa de C<POD2::TLH>
pode-se parecer com isto:
package POD2::TLH; # Klingon
use POD2::Base;
our @ISA = qw( POD2::Base );
sub search_perlfunc_re {
return 'Klingon Listing of Perl Functions';
}
sub pod_info {
return { perlintro => '5.8.8' };
}
1;
E você pode experimentar:
use POD2::TLH;
my $pod2 = 'POD2::TLH';
$pod2->print_pods();
$pod2->print_pod('pod_foo', 'pod_baz', ...);
=head2 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.
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 "$_\n" for @files;
Na distribuição C<POD2-Base>, é incluído um script
F<eg/list.pl> com uma versão estendida
deste código.
As regras para encontrar POD em arquivos F<.pod>, F<.pm> e
outros pertencem ao módulo L<Pod::Perldoc>. Assim C<POD2::Base>
não tenta repetir esta funcionalidade aqui.
=head1 AUTORES
Enrico Sorcinelli E<lt>bepi at perl.itE<gt> (pelo código original em POD2::IT)
Adriano Ferreira E<lt>ferreira at cpan.orgE<gt>
=head1 VEJA TAMBÉM
L<POD2::IT>, L<POD2::FR>, L<POD2::LT>, L<POD2::CN>, L<perldoc>, L<perl>.
A versão original deste documento: L<POD2::Base>.
(O propósito desta tradução é servir como um primeiro teste
para experimentar o suporte dos vários modules Pod e I<sites> Perl
aos PODs traduzidos.)
(This translation was supplied as a front test against the support
of the many Pod modules and Perl sites on translated PODs.)
=head1 COPYRIGHT E LICENÇA
Copyright (C) 2004-2006 Perl.it / Perl Mongers Italia
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
=cut
=begin meta
---
date: 2008-02-25T11:01:45
md5: 47896a7d12987b2f18179eac7f52f8b2
revision: 3
translated_from:
history: []
md5: ~
uri: http://search.cpan.org/src/FERREIRA/POD2-Base-0.04/lib/POD2/Base.pod
=end meta