1POD2::PT::POD2::Base(3)User Contributed Perl DocumentatioPnOD2::PT::POD2::Base(3)
2
3
4

NAME/NOME

6       POD2::Base~[pt] - Módulo básico para traduções de documentação Perl
7

SINOPSE

9           use POD2::Base;
10           $pod2 = POD2::Base->new({ lang => 'EO' });
11
12           @dirs = $pod2->pod_dirs;
13           $re = $pod2->search_perlfunc_re;
14

DESCRIÇÃO

16       Este código é uma abstração do código em POD2::IT e POD2::FR, módulos
17       que pertencem aos projetos italiano e francês de tradução dos
18       documentos que acompanham o interpretador Perl.
19
20       Com o pacote de tradução já instalado, a documentação traduzida pode
21       ser acessada através do comando:
22
23           $ perldoc POD2::<lang>::<podname>
24
25       (onde <lang> é uma abreviação para linguagem como IT, FR, TLH, etc.)
26
27       Isto funciona seguramente até para as versões antigas do perldoc. Não é
28       muito conveniente mas sempre funciona.
29
30       Para incrementar o suporte para leitura destes documentos traduzidos, o
31       programa perldoc (desde a versão 3.14_01) foi atualizado para encontrar
32       PODs traduzidos assim:
33
34           $ perldoc -L IT <podpage>
35           $ perldoc -L FR -f <function>
36           $ perldoc -L TLH -q <FAQregex>
37
38       (Nota: Este suporte foi distribuído junto da versão 5.10.0 do
39       interpretador Perl recentemente disponilizado no CPAN.)
40
41       O objetivo desta classe é prover uma base mínima para ajudar o
42       "perldoc" e os autores de projetos de tradução a fazerem seu trabalho.
43

SUBCLASSES

45       Se você quer escrever um pacote de tradução (e tem algumas necessidades
46       de personalização), seu trabalho pode ser diminuído se você criar uma
47       subclasse de "POD2::Base".
48
49       Por exemplo, um exemplo mínimo é ilustrado abaixo.
50
51           package POD2::TLH; # Klingon
52
53           use POD2::Base;
54           our @ISA = qw( POD2::Base );
55
56           sub search_perlfunc_re { # ajuda 'perldoc -f' a funcionar
57               return 'Klingon Listing of Perl Functions';
58           }
59
60           1;
61
62       E então
63
64           $ perldoc -L tlh perlintro
65
66       vai lhe apresentar a introdução de Perl na linguagem Klingon (desde que
67       um arquivo POD2/TLH/perlintro.pod tenha sido distribuído junto com
68       POD2/TLH.pm) e
69
70           $ perldoc -L tlh -f pack
71
72       vai encontrar a documentação em Klingon de "pack" (se
73       POD2/TLH/perlfunc.pod foi disponibilizado também).
74

MÉTODOS

76       Este módulo foi projetado como uma classe OO com uma API bem pequena.
77
78       new
79               $pod2 = POD2::Base->new(\%args);
80               $pod2 = POD2::ANY->new();
81
82           O constructor. A criação de uma instância pode se fazer de modo
83           similar a:
84
85               $pod2 = POD2::Base->new({ lang => 'tlh' });
86
87           onde as opções suportadas são:
88
89           •   "lang"
90
91               Especifica o código da linguagem em que estamos interessados.
92               Este parâmetro é obrigatório, mas pode ser extraído do nome da
93               subclasse, como explicado mais abaixo.
94
95           •   "inc"
96
97               Este parâmetro é usado para substituir a lista de diretórios
98               para as bibliotecas Perl onde procuram-se os documentos POD (ou
99               seja, @INC). Na maior parte do tempo, você não vai querer mexer
100               com isto.  Este parâmetro é mais útil para debugging e testes.
101
102               Espera-se um array ref.
103
104           Se "POD2::ANY" é uma subclasse de "POD2::Base", o construtor
105           herdado funcionará sem argumentos extraindo 'ANY' do nome do pacote
106           e usando-o como o código da linguagem desejada.
107
108           Note que o uso de "inc" no construtor congela a lista de diretórios
109           vasculhados pela instância "POD2::Base". Se não é usado, o conteúdo
110           atualizado de @INC é usado em cada chamada de "pod_dirs" (de tal
111           forma que mudanças dinâmicas no path para as bibliotecas Perl são
112           percebidas). É isto que queríamos dizer com "Na maior parte do
113           tempo, você não vai querer mexer com isto."
114
115       pod_dirs
116               @dirs = $pod2->pod_dirs;
117               @dirs = $pod2->pod_dirs(\%options);
118
119           Usado por "Pod::Perldoc" para descobrir onde procurar por PODs
120           traduzidos.
121
122           O comportamento padrão de "POD2::Base" é encontrar cada diretório
123           POD2/<lang>/ sob os diretórios de bibliotecas Perl (@INC) ou na
124           lista dada como o argumento "inc" no construtor.
125
126           As opções suportadas são:
127
128           •   "test"
129
130               Por default, o retorno de "pod_dirs" não inclui diretórios POD
131               que não existem (testados com "-d").  Se um valor falso
132               explícito é dado para esta opção (por exemplo, "test => 0"),
133               este teste não é feito e "pod_dirs" inclui todos candidatos
134               POD2/<lang>/ abaixo dos diretórios de bibliotecas.  (Útil para
135               o debugging deste módulo, mas sem outros usos práticos além
136               deste.)
137
138       search_perlfunc_re
139               $re = $pod2->search_perlfunc_re;
140
141           Para implementar "perldoc -f <function>" o código atual de
142           "Pod::Perldoc" usa um string fixo "Alphabetical Listing of Perl
143           Functions" ou o retorno deste método (em uma regex) para pular a
144           introdução e alcançar a listagem das funções builtin. Então um
145           pacote de tradução com a correspondente tradução de perlfunc.pod
146           deve definir este método para fazer "perldoc -L <lang> -f
147           <function>" funcionar corretamente.
148
149       Há outros métodos documentados abaixo. Entretanto, eles provavelmente
150       serão tornados obsoletos em versões futuras quando forem projetados e
151       implementados métodos mais gerais de encontrar e mostrar os metadados
152       sobre os PODs traduzidos.
153
154       pod_info
155               $hashref = $pod2->pod_info;
156
157           Usado pelo próprio "POD2::Base" e seus ancestrais "POD2::IT" e
158           "POD2::FR". O retorno contém alguns metadados sobre os PODs
159           traduzidos usados pelos métodos "print_pod" e "print_pods".
160
161           Ao fazer subclasses seguindo o padrão de "POD2::IT" e "POD2::FR",
162           você deve redefinir este método com a informação atual sobre quais
163           traduções POD o pacote atual está disponibilizando.
164
165       print_pods
166               $pod2->print_pods;
167
168           Mostra (via "print") todos PODs traduzidos e a versão
169           correspondente de Perl dos arquivos originais.
170
171       print_pod
172               $pod2->print_pod(@pages);
173               $pod2->print_pod(); # usa @ARGV
174
175           Mostra a versão de Perl correspondente dos arquivos originais
176           associados aos PODs passados como argumentos.
177

EXEMPLOS

179   POD2::TLH
180       Uma versão mais completa de "POD2::TLH" pode-se parecer com isto:
181
182           package POD2::TLH; # Klingon
183
184           use POD2::Base;
185           our @ISA = qw( POD2::Base );
186
187           sub search_perlfunc_re {
188               return 'Klingon Listing of Perl Functions';
189           }
190
191           sub pod_info {
192               return { perlintro => '5.8.8' };
193           }
194
195           1;
196
197       E você pode experimentar:
198
199           use POD2::TLH;
200           my $pod2 = 'POD2::TLH';
201           $pod2->print_pods();
202           $pod2->print_pod('pod_foo', 'pod_baz', ...);
203
204   OS ARQUIVOS INSTALADOS
205       Se você quer descobrir quais arquivos PODs de uma dada linguagem que
206       estão instalados junto com seu interpretador Perl, você pode usar um
207       código similar a este.
208
209           use File::Find;
210           use POD2::Base;
211
212           my $pod2 = POD2::Base->new({ lang => $lang });
213
214           my @files;
215           find sub { push @files, $File::Find::name } if -f },
216                $pod2->pod_dirs;
217           print "$_\n" for @files;
218
219       Na distribuição "POD2-Base", é incluído um script eg/list.pl com uma
220       versão estendida deste código.
221
222       As regras para encontrar POD em arquivos .pod, .pm e outros pertencem
223       ao módulo Pod::Perldoc. Assim "POD2::Base" não tenta repetir esta
224       funcionalidade aqui.
225

AUTORES

227       Enrico Sorcinelli <bepi at perl.it> (pelo código original em POD2::IT)
228
229       Adriano Ferreira <ferreira at cpan.org>
230

VEJA TAMBÉM

232       POD2::IT, POD2::FR, POD2::LT, POD2::CN, perldoc, perl.
233
234       A versão original deste documento: POD2::Base.
235
236       (O propósito desta tradução é servir como um primeiro teste para
237       experimentar o suporte dos vários modules Pod e sites Perl aos PODs
238       traduzidos.)
239
240       (This translation was supplied as a front test against the support of
241       the many Pod modules and Perl sites on translated PODs.)
242
244       Copyright (C) 2004-2006 Perl.it / Perl Mongers Italia
245
246       This library is free software; you can redistribute it and/or modify it
247       under the same terms as Perl itself.
248
249
250
251perl v5.34.0                      2022-01-21           POD2::PT::POD2::Base(3)
Impressum