r47584 - in /branches/upstream/libpod2-base-perl: ./ current/ current/eg/ current/lib/ current/lib/POD2/ current/lib/POD2/PT/ current/lib/POD2/PT/POD2/ current/t/ current/t/lib/
joenio-guest at users.alioth.debian.org
joenio-guest at users.alioth.debian.org
Sat Nov 21 18:45:02 UTC 2009
Author: joenio-guest
Date: Sat Nov 21 18:44:53 2009
New Revision: 47584
URL: http://svn.debian.org/wsvn/pkg-perl/?sc=1&rev=47584
Log:
[svn-inject] Installing original source of libpod2-base-perl
Added:
branches/upstream/libpod2-base-perl/
branches/upstream/libpod2-base-perl/current/
branches/upstream/libpod2-base-perl/current/Changes
branches/upstream/libpod2-base-perl/current/MANIFEST
branches/upstream/libpod2-base-perl/current/META.yml
branches/upstream/libpod2-base-perl/current/Makefile.PL
branches/upstream/libpod2-base-perl/current/README
branches/upstream/libpod2-base-perl/current/eg/
branches/upstream/libpod2-base-perl/current/eg/list.pl
branches/upstream/libpod2-base-perl/current/lib/
branches/upstream/libpod2-base-perl/current/lib/POD2/
branches/upstream/libpod2-base-perl/current/lib/POD2/Base.pm
branches/upstream/libpod2-base-perl/current/lib/POD2/Base.pod
branches/upstream/libpod2-base-perl/current/lib/POD2/PT/
branches/upstream/libpod2-base-perl/current/lib/POD2/PT/POD2/
branches/upstream/libpod2-base-perl/current/lib/POD2/PT/POD2/Base.pod
branches/upstream/libpod2-base-perl/current/t/
branches/upstream/libpod2-base-perl/current/t/01_use.t
branches/upstream/libpod2-base-perl/current/t/02_basic.t
branches/upstream/libpod2-base-perl/current/t/98_pod-coverage.t
branches/upstream/libpod2-base-perl/current/t/99_pod.t
branches/upstream/libpod2-base-perl/current/t/lib/
branches/upstream/libpod2-base-perl/current/t/lib/.exists
Added: branches/upstream/libpod2-base-perl/current/Changes
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libpod2-base-perl/current/Changes?rev=47584&op=file
==============================================================================
--- branches/upstream/libpod2-base-perl/current/Changes (added)
+++ branches/upstream/libpod2-base-perl/current/Changes Sat Nov 21 18:44:53 2009
@@ -1,0 +1,37 @@
+
+Revision history for Perl extension POD2::Base.
+
+0.043 Tue Feb 26 2008
+ - removed 'our' in t/02_basic.t (for 5.005's sake)
+
+0.042 Mon Feb 25 2008
+ - tweak POD2/PT/POD2/Base.pod
+ - (temporarily) skips POD test for 5.6
+
+0.041 Sun Feb 24 2008
+ - POD2/PT/POD2/Base.pod is now a complete
+ Portuguese translation (without much review)
+ of POD2::Base docs
+
+0.04 Sat Feb 23 2008
+ - File::Spec is a prereq now
+ - one more constructor param: 'inc'
+ - pod_dirs now accept options ('test')
+ - pod_dirs now search all over @INC for
+ "POD2/<lang>/" dirs
+ - included an example for listing lang-specific
+ installed files (eg/list.pl)
+ - included a hoax of a Portuguese translation
+ for the documentation of this module
+
+0.0301 Fri Feb 1 2008
+ - warning and vars in PREREQ_PM
+ - minor POD tweaks
+
+0.03 Tue Sep 4 2007
+ - rewrote "lib/POD2/Base.pod"
+
+0.02 Mon Sep 3 2007
+ - first version (after POD2::IT 0.11)
+ - request for comments at pod2it-translators
+ and roma-pm mailing lists
Added: branches/upstream/libpod2-base-perl/current/MANIFEST
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libpod2-base-perl/current/MANIFEST?rev=47584&op=file
==============================================================================
--- branches/upstream/libpod2-base-perl/current/MANIFEST (added)
+++ branches/upstream/libpod2-base-perl/current/MANIFEST Sat Nov 21 18:44:53 2009
@@ -1,0 +1,18 @@
+
+lib/POD2/Base.pm
+lib/POD2/Base.pod
+lib/POD2/PT/POD2/Base.pod A PT translation of POD2::Base docs
+
+Makefile.PL
+Changes
+README
+MANIFEST This list of files
+
+t/01_use.t
+t/02_basic.t
+t/99_pod.t
+t/98_pod-coverage.t
+t/lib/.exists Existence marker for t/lib/
+eg/list.pl
+
+META.yml Module meta-data (added by MakeMaker)
Added: branches/upstream/libpod2-base-perl/current/META.yml
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libpod2-base-perl/current/META.yml?rev=47584&op=file
==============================================================================
--- branches/upstream/libpod2-base-perl/current/META.yml (added)
+++ branches/upstream/libpod2-base-perl/current/META.yml Sat Nov 21 18:44:53 2009
@@ -1,0 +1,21 @@
+--- #YAML:1.0
+name: POD2-Base
+version: 0.043
+abstract: Base module for translations of Perl documentation
+license: perl
+author: ~
+generated_by: ExtUtils::MakeMaker version 6.42
+distribution_type: module
+requires:
+ File::Spec: 0
+ strict: 0
+ Test::More: 0
+ vars: 0
+ warnings: 0
+meta-spec:
+ url: http://module-build.sourceforge.net/META-spec-v1.3.html
+ version: 1.3
+recommends:
+ Test::Pod: 1.18
+ Test::Pod::Coverage: 1.04
+ ExtUtils::MakeMaker: 6.38
Added: branches/upstream/libpod2-base-perl/current/Makefile.PL
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libpod2-base-perl/current/Makefile.PL?rev=47584&op=file
==============================================================================
--- branches/upstream/libpod2-base-perl/current/Makefile.PL (added)
+++ branches/upstream/libpod2-base-perl/current/Makefile.PL Sat Nov 21 18:44:53 2009
@@ -1,0 +1,35 @@
+
+use 5.005;
+use ExtUtils::MakeMaker;
+
+my $EUMM_VERSION = eval $ExtUtils::MakeMaker::VERSION;
+
+# note. EUMM 6.38 and later always includes 'author'
+# in META.yml fixing compliance with spec
+
+WriteMakefile(
+ NAME => 'POD2::Base',
+ VERSION_FROM => 'lib/POD2/Base.pm',
+ PREREQ_PM => {
+ strict => 0,
+ warnings => 0,
+ vars => 0,
+ ( warnings::compat => 0, ) x!! ( $] < 5.006 ),
+
+ File::Spec => 0,
+
+ Test::More => 0,
+ },
+ ($] >= 5.005 ? (
+ 'ABSTRACT_FROM' => 'lib/POD2/Base.pod',
+# 'AUTHOR' => 'Adriano R. Ferreira <ferreira at cpan.org>',
+ ) : ()),
+ ($EUMM_VERSION >= 6.31 ? (
+ LICENSE => 'perl',
+ EXTRA_META => "recommends:\n" .
+ " Test::Pod: 1.18\n" .
+ " Test::Pod::Coverage: 1.04\n" .
+ " ExtUtils::MakeMaker: 6.38\n"
+ ) :())
+
+);
Added: branches/upstream/libpod2-base-perl/current/README
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libpod2-base-perl/current/README?rev=47584&op=file
==============================================================================
--- branches/upstream/libpod2-base-perl/current/README (added)
+++ branches/upstream/libpod2-base-perl/current/README Sat Nov 21 18:44:53 2009
@@ -1,0 +1,227 @@
+NAME
+ POD2::Base - Base module for translations of Perl documentation
+
+SYNOPSIS
+ use POD2::Base;
+ $pod2 = POD2::Base->new({ lang => 'EO' });
+
+ @dirs = $pod2->pod_dirs;
+ $re = $pod2->search_perlfunc_re;
+
+DESCRIPTION
+ This module is an abstraction of the code in POD2::IT and POD2::FR.
+ These modules belong to the Italian and the French translation projects
+ of core Perl pods.
+
+ Once a translation package had been installed, the translated
+ documentation can be accessed with:
+
+ $ perldoc POD2::<lang>::<podname>
+
+ (where <lang> is a language abbreviation like IT, FR, TLH, etc.)
+
+ This is guaranteed to work even for older versions of perldoc. It is not
+ very convenient but always works.
+
+ To improve the support to read translated docs, the perldoc utility
+ (since version 3.14_01) was updated to find translated PODs via:
+
+ $ perldoc -L IT <podpage>
+ $ perldoc -L FR -f <function>
+ $ perldoc -L TH -q <FAQregex>
+
+ (*Note*: this support was shipped together with the recently released
+ 5.10.0 version the Perl interpreter.)
+
+ The objective of this class is to provide a minimum base to help
+ `perldoc' and authors of translation packages to do their job.
+
+SUBCLASSING
+ If you want to write a translation package (and have some customization
+ needs), your work may be diminished if you subclass `Pod::Base'.
+
+ For example, a minimum example is provided below:
+
+ package POD2::TLH; # Klingon
+
+ use POD2::Base;
+ our @ISA = qw( POD2::Base );
+
+ sub search_perlfunc_re { # makes 'perldoc -f' work
+ return 'Klingon Listing of Perl Functions';
+ }
+
+ 1;
+
+ And then
+
+ $ perldoc -L tlh perlintro
+
+ will present you the introduction of Perl in Klingon language (provided
+ a POD2/TLH/perlintro.pod file was shipped together with POD2/TLH.pm) and
+
+ $ perldoc -L tlh -f pack
+
+ will find you the Klingon documentation of `pack' (if
+ POD2/TLH/perlfunc.pod was made available as well).
+
+METHODS
+ This module has been made into a proper class with a very small API.
+
+ new
+ $pod2 = POD2::Base->new(\%args);
+ $pod2 = POD2::ANY->new();
+
+ The constructor. An actual call might look like this:
+
+ $pod2 = POD2::Base->new({ lang => 'tlh' });
+
+ where the supported options are:
+
+ * "lang"
+ Specifies the language code we're interested in. This is
+ required, but can be extracted from the name of a subclass. Read
+ below.
+
+ * "inc"
+ This is used to override the list of Perl library directories
+ where POD documents are searched (namely, `@INC'). Most of the
+ time, you don't want to mess with that. It's handy for debugging
+ and testing.
+
+ It must be an array ref.
+
+ If `POD2::ANY' is a subclass of `POD2::Base', the inherited
+ constructor will work without arguments pulling 'ANY' from the
+ package name and using it as the intented language code.
+
+ Note that use of "inc" in the constructor freezes the list of
+ library dirs searched by the `POD2::Base' instance. If this is not
+ used, the up-to-date `@INC' is used at each call of `pod_dirs' (so
+ that dynamic changes in the Perl library path are taken into
+ account). That's what we meant with the "Most of the time, you don't
+ want to mess with that" mentioned above.
+
+ pod_dirs
+ @dirs = $pod2->pod_dirs;
+ @dirs = $pod2->pod_dirs(\%options);
+
+ Used by `Pod::Perldoc' to find out where to look for translated
+ pods.
+
+ The `POD2::Base' default behavior is to find POD2/<lang>/
+ directories under the current Perl library directories (`@INC') or
+ the list given as argument "inc" in the constructor.
+
+ The supported options are:
+
+ * "test"
+ By default, the return of `pod_dirs' do not include POD
+ directories which do not exist (tested with `-d'). If an
+ explicit false value for this option (like `test => 0') is
+ given, such test is not done and `pod_dirs' includes all
+ possible candidates POD2/<lang>/ under the library directories.
+ (Handy for debugging this module. Not much practical use for
+ anything else.)
+
+ search_perlfunc_re
+ $re = $pod2->search_perlfunc_re;
+
+ To implement `perldoc -f <function>' the current code of
+ `Pod::Perldoc' uses a hard coded string "Alphabetical Listing of
+ Perl Functions" 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 perlfunc.pod
+ should define this method to make `perldoc -L <lang> -f <function>'
+ work properly.
+
+ 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.
+
+ pod_info
+ $hashref = $pod2->pod_info;
+
+ Used by `POD2::Base' itself. The return contains some metadata on
+ the translated PODs which is used by the methods `print_pod' and
+ `print_pods'.
+
+ When subclassing, you should override this with the current
+ information on what POD translations the current package is
+ providing.
+
+ print_pods
+ $pod2->print_pods;
+
+ Prints all translated pods and the corresponding Perl version of the
+ original files.
+
+ print_pod
+ $pod2->print_pod(@pages);
+ $pod2->print_pod(); # uses @ARGV
+
+ Prints the corresponding Perl version of the original files
+ corresponding to the pods passed as arguments.
+
+EXAMPLES
+ POD2::TLH
+
+ A slightly extended version of `POD2::TLH' goes like this:
+
+ 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;
+
+ And you may try:
+
+ use POD2::TLH;
+ my $pod2 = 'POD2::TLH';
+ $pod2->print_pods();
+ $pod2->print_pod('pod_foo', 'pod_baz', ...);
+
+ THE INSTALLED FILES
+
+ If you want to find out which language-specific POD files are installed
+ at your Perl, you could use a code similar to this.
+
+ 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;
+
+ In the `POD2-Base' distribution tarball, a script eg/list.pl is included
+ with an improved version of this code.
+
+ The rules of finding POD in .pod, .pm files and others belong to
+ Pod::Perldoc. So `POD2::Base' do not try to repeat them here.
+
+AUTHORS
+ Enrico Sorcinelli <bepi at perl.it> (the original POD2::IT code)
+
+ Adriano Ferreira <ferreira at cpan.org>
+
+SEE ALSO
+ POD2::IT, POD2::FR, POD2::LT, POD2::CN, perldoc, perl.
+
+COPYRIGHT AND LICENCE
+ 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.
+
Added: branches/upstream/libpod2-base-perl/current/eg/list.pl
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libpod2-base-perl/current/eg/list.pl?rev=47584&op=file
==============================================================================
--- branches/upstream/libpod2-base-perl/current/eg/list.pl (added)
+++ branches/upstream/libpod2-base-perl/current/eg/list.pl Sat Nov 21 18:44:53 2009
@@ -1,0 +1,36 @@
+
+
+use strict;
+use warnings;
+
+die "usage: $0 lang" unless @ARGV;
+my $lang = uc shift;
+
+use File::Find;
+use POD2::Base;
+
+my $pod2 = POD2::Base->new({ lang => $lang });
+
+my @dirs = $pod2->pod_dirs;
+die "could not find any POD2/${lang}/ directory" unless @dirs;
+print "dirs: @dirs.\n";
+my @files;
+find({
+ wanted => sub { push @files, $File::Find::name if -f },
+ },
+ @dirs );
+print "$_\n" for @files;
+
+__END__
+
+=head1 NAME
+
+list.pl - find all files in POD dirs for a certain language
+
+=head1 USAGE
+
+ list.pl lang
+
+where B<lang> is the apropriate language code
+(eg. CN, PT, IT, FR, etc.)
+
Added: branches/upstream/libpod2-base-perl/current/lib/POD2/Base.pm
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libpod2-base-perl/current/lib/POD2/Base.pm?rev=47584&op=file
==============================================================================
--- branches/upstream/libpod2-base-perl/current/lib/POD2/Base.pm (added)
+++ branches/upstream/libpod2-base-perl/current/lib/POD2/Base.pm Sat Nov 21 18:44:53 2009
@@ -1,0 +1,97 @@
+
+package POD2::Base;
+
+use 5.005;
+use strict;
+use warnings;
+
+use vars qw( $VERSION );
+$VERSION = '0.043';
+
+use File::Spec ();
+
+sub new {
+ my $proto = shift;
+ my $class = ref $proto || $proto;
+ my $obj = bless {}, $class;
+ return $obj->_init( @_ );
+}
+
+# instance variables:
+# lang - the preferred language of the POD documents
+# inc - alternate library dirs (if given, replaces the ones in @INC)
+
+sub _init {
+ my $self = shift;
+ my %args = @_ ? %{$_[0]} : ();
+ if ( !exists $args{lang} ) {
+ $args{lang} = _extract_lang( ref $self );
+ }
+ #croak "???" unless $args{lang};
+ my $lang = uc $args{lang};
+ $self->{lang} = $lang;
+ $self->{inc} = $args{inc}; # XXX croak ?! must be array ref
+
+ return $self;
+}
+
+# $lang = _extract_lang($module);
+sub _extract_lang {
+ my $module = shift;
+
+ return $module eq __PACKAGE__ ? undef
+ : $module =~ /::(\w+)\z/ ? $1
+ : undef
+ ;
+}
+
+sub _lib_dirs {
+ my $self = shift;
+ return $self->{inc} ? @{$self->{inc}} : @INC;
+}
+
+sub pod_dirs {
+ my $self = shift;
+ my %options = @_ ? %{$_[0]} : ();
+ $options{test} = 1 unless exists $options{test};
+
+ my $lang = $self->{lang};
+ my @candidates = map { File::Spec->catdir( $_, 'POD2', $lang ) } $self->_lib_dirs; # XXX the right thing to do
+ if ( $options{test} ) {
+ return grep { -d } @candidates;
+ }
+ return @candidates;
+}
+
+#sub search_perlfunc_re {
+# shift;
+# return 'Alphabetical Listing of Perl Functions';
+#}
+
+sub pod_info {
+ shift;
+ return {};
+}
+
+sub print_pods {
+ my $self = shift;
+ $self->print_pod(sort keys %{$self->pod_info});
+}
+
+sub print_pod {
+ my $self = shift;
+ my @args = @_ ? @_ : @ARGV;
+
+ my $pods = $self->pod_info;
+ while (@args) {
+ (my $pod = lc(shift @args)) =~ s/\.pod$//;
+ if ( exists $pods->{$pod} ) {
+ print "\t'$pod' translated from Perl $pods->{$pod}\n";
+ }
+ else {
+ print "\t'$pod' doesn't yet exists\n";
+ }
+ }
+}
+
+1;
Added: branches/upstream/libpod2-base-perl/current/lib/POD2/Base.pod
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libpod2-base-perl/current/lib/POD2/Base.pod?rev=47584&op=file
==============================================================================
--- branches/upstream/libpod2-base-perl/current/lib/POD2/Base.pod (added)
+++ branches/upstream/libpod2-base-perl/current/lib/POD2/Base.pod Sat Nov 21 18:44:53 2009
@@ -1,0 +1,284 @@
+
+=head1 NAME
+
+POD2::Base - Base module for translations of Perl documentation
+
+=head1 SYNOPSIS
+
+ use POD2::Base;
+ $pod2 = POD2::Base->new({ lang => 'EO' });
+
+ @dirs = $pod2->pod_dirs;
+ $re = $pod2->search_perlfunc_re;
+
+=head1 DESCRIPTION
+
+This module is an abstraction of the code in POD2::IT
+and POD2::FR. These modules belong to the Italian and
+the French translation projects of core Perl pods.
+
+Once a translation package had been installed, the translated
+documentation can be accessed with:
+
+ $ perldoc POD2::<lang>::<podname>
+
+(where <lang> is a language abbreviation like IT, FR,
+TLH, etc.)
+
+This is guaranteed to work even for older versions of
+L<perldoc|perldoc>. It is not very convenient but always works.
+
+To improve the support to read translated docs, the
+L<perldoc|perldoc> utility (since version 3.14_01) was updated
+to find translated PODs via:
+
+ $ perldoc -L IT <podpage>
+ $ perldoc -L FR -f <function>
+ $ perldoc -L TH -q <FAQregex>
+
+(I<Note>: this support was shipped together with the
+recently released 5.10.0 version the Perl interpreter.)
+
+The objective of this class is to provide a minimum
+base to help C<perldoc> and authors of translation
+packages to do their job.
+
+=head1 SUBCLASSING
+
+If you want to write a translation package (and have
+some customization needs), your
+work may be diminished if you subclass C<Pod::Base>.
+
+For example, a minimum example is provided below:
+
+ package POD2::TLH; # Klingon
+
+ use POD2::Base;
+ our @ISA = qw( POD2::Base );
+
+ sub search_perlfunc_re { # makes 'perldoc -f' work
+ return 'Klingon Listing of Perl Functions';
+ }
+
+ 1;
+
+And then
+
+ $ perldoc -L tlh perlintro
+
+will present you the introduction of Perl in Klingon language
+(provided a F<POD2/TLH/perlintro.pod> file was shipped together
+with F<POD2/TLH.pm>) and
+
+ $ perldoc -L tlh -f pack
+
+will find you the Klingon documentation of C<pack> (if
+F<POD2/TLH/perlfunc.pod> was made available as well).
+
+=head1 METHODS
+
+This module has been made into a proper class
+with a very small API.
+
+=over 4
+
+=item B<new>
+
+ $pod2 = POD2::Base->new(\%args);
+ $pod2 = POD2::ANY->new();
+
+The constructor. An actual call might look like this:
+
+ $pod2 = POD2::Base->new({ lang => 'tlh' });
+
+where the supported options are:
+
+=over 4
+
+=item * "lang"
+
+Specifies the language code we're interested in.
+This is required, but can be extracted from
+the name of a subclass. Read below.
+
+=item * "inc"
+
+This is used to override the list of Perl
+library directories where POD documents
+are searched (namely, C<@INC>). Most of the
+time, you don't want to mess with that.
+It's handy for debugging and testing.
+
+It must be an array ref.
+
+=back
+
+If C<POD2::ANY> is a subclass of C<POD2::Base>, the
+inherited constructor will work without arguments
+pulling 'ANY' from the package name and using it
+as the intented language code.
+
+Note that use of "inc" in the constructor
+freezes the list of library dirs searched by the
+C<POD2::Base> instance. If this is not used,
+the up-to-date C<@INC> is used at each call
+of C<pod_dirs> (so that dynamic changes in
+the Perl library path are taken into account).
+That's what we meant with the
+"Most of the time, you don't want to mess with that"
+mentioned above.
+
+=item B<pod_dirs>
+
+ @dirs = $pod2->pod_dirs;
+ @dirs = $pod2->pod_dirs(\%options);
+
+Used by C<Pod::Perldoc> to find out where to
+look for translated pods.
+
+The C<POD2::Base> default behavior is to find
+F<< POD2/<lang>/ >> directories under the
+current Perl library directories (C<@INC>) or
+the list given as argument "inc" in the constructor.
+
+The supported options are:
+
+=over 4
+
+=item * "test"
+
+By default, the return of C<pod_dirs> do not
+include POD directories which do not exist (tested
+with C<-d>). If an explicit false value for this option (like
+C<< test => 0 >>) is given, such test is not done
+and C<pod_dirs> includes all possible candidates
+F<< POD2/<lang>/ >> under the library directories.
+(Handy for debugging this module. Not much practical
+use for anything else.)
+
+=back
+
+=item B<search_perlfunc_re>
+
+ $re = $pod2->search_perlfunc_re;
+
+To implement C<< perldoc -f <function> >>
+the current code of C<Pod::Perldoc> uses a hard coded string
+"Alphabetical Listing of Perl Functions" 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
+F<perlfunc.pod> should define this method to
+make C<< perldoc -L <lang> -f <function> >>
+work properly.
+
+=back
+
+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.
+
+=over 4
+
+=item B<pod_info>
+
+ $hashref = $pod2->pod_info;
+
+Used by C<POD2::Base> itself. The return contains
+some metadata on the translated PODs which is used
+by the methods C<print_pod> and C<print_pods>.
+
+When subclassing, you B<should> override this
+with the current information on what POD
+translations the current package is providing.
+
+=item B<print_pods>
+
+ $pod2->print_pods;
+
+Prints all translated pods and the corresponding Perl version
+of the original files.
+
+=item B<print_pod>
+
+ $pod2->print_pod(@pages);
+ $pod2->print_pod(); # uses @ARGV
+
+Prints the corresponding Perl version of the original files
+corresponding to the pods passed as arguments.
+
+=back
+
+=head1 EXAMPLES
+
+=head2 POD2::TLH
+
+A slightly extended version of C<POD2::TLH>
+goes like this:
+
+ 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;
+
+And you may try:
+
+ use POD2::TLH;
+ my $pod2 = 'POD2::TLH';
+ $pod2->print_pods();
+ $pod2->print_pod('pod_foo', 'pod_baz', ...);
+
+=head2 THE INSTALLED FILES
+
+If you want to find out which language-specific
+POD files are installed at your Perl,
+you could use a code similar to this.
+
+ 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;
+
+In the C<POD2-Base> distribution tarball, a script
+F<eg/list.pl> is included with an improved
+version of this code.
+
+The rules of finding POD in F<.pod>, F<.pm> files and others
+belong to L<Pod::Perldoc>. So C<POD2::Base> do not try
+to repeat them here.
+
+
+=head1 AUTHORS
+
+Enrico Sorcinelli E<lt>bepi at perl.itE<gt> (the original POD2::IT code)
+
+Adriano Ferreira E<lt>ferreira at cpan.orgE<gt>
+
+=head1 SEE ALSO
+
+L<POD2::IT>, L<POD2::FR>, L<POD2::LT>, L<POD2::CN>, L<perldoc>, L<perl>.
+
+=head1 COPYRIGHT AND LICENCE
+
+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
Added: branches/upstream/libpod2-base-perl/current/lib/POD2/PT/POD2/Base.pod
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libpod2-base-perl/current/lib/POD2/PT/POD2/Base.pod?rev=47584&op=file
==============================================================================
--- branches/upstream/libpod2-base-perl/current/lib/POD2/PT/POD2/Base.pod (added)
+++ branches/upstream/libpod2-base-perl/current/lib/POD2/PT/POD2/Base.pod Sat Nov 21 18:44:53 2009
@@ -1,0 +1,319 @@
+
+=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
Added: branches/upstream/libpod2-base-perl/current/t/01_use.t
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libpod2-base-perl/current/t/01_use.t?rev=47584&op=file
==============================================================================
--- branches/upstream/libpod2-base-perl/current/t/01_use.t (added)
+++ branches/upstream/libpod2-base-perl/current/t/01_use.t Sat Nov 21 18:44:53 2009
@@ -1,0 +1,5 @@
+
+use Test::More tests => 1;
+BEGIN { use_ok('POD2::Base') };
+
+diag( "Testing POD2::Base $POD2::Base::VERSION" );
Added: branches/upstream/libpod2-base-perl/current/t/02_basic.t
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libpod2-base-perl/current/t/02_basic.t?rev=47584&op=file
==============================================================================
--- branches/upstream/libpod2-base-perl/current/t/02_basic.t (added)
+++ branches/upstream/libpod2-base-perl/current/t/02_basic.t Sat Nov 21 18:44:53 2009
@@ -1,0 +1,67 @@
+
+
+use strict;
+use Test::More tests => 15;
+
+BEGIN { use_ok( 'POD2::Base' ); }
+
+# subsumes_dir( '/usr/lib/perl/POD2/TLH', 'POD2/TLH' ) is true
+sub subsumes_dir {
+ my $dir = shift;
+ my $tail = shift;
+ my @dir_segments = File::Spec->splitdir( $_ );
+ return $tail eq join '/', @dir_segments[-2,-1];
+}
+
+{
+ my $pod2 = POD2::Base->new({ lang => 'tlh' });
+ isa_ok( $pod2, 'POD2::Base' );
+
+ is( $pod2->{lang}, 'TLH', 'the right lang' );
+
+ my @dirs = $pod2->pod_dirs({ test => 0 }); # don't test for -d
+ is( @dirs, @INC, 'pod dirs searched all over @INC' );
+ my @ok = grep { subsumes_dir( $_, 'POD2/TLH' ) } @dirs;
+ is( @ok, @INC, 'all pod dirs end with "POD2/TLH"' );
+
+}
+
+{
+ my $lib_dir = File::Spec->catdir( 'lib' );
+ my $pod2 = POD2::Base->new({ lang => 'pt', inc => [$lib_dir] });
+ isa_ok( $pod2, 'POD2::Base' );
+
+ is( $pod2->{lang}, 'PT', 'the right lang' );
+
+ my @dirs = $pod2->pod_dirs();
+ is( @dirs, 1, 'found one dir' );
+ is( $dirs[0], File::Spec->catdir( $lib_dir, 'POD2', 'PT' ), 'at the right place' );
+
+}
+
+package POD2::TLH;
+
+ at POD2::TLH::ISA = qw( POD2::Base );
+
+sub search_perlfunc_re {
+ return 'Klingon Listing of Functions';
+}
+
+package main;
+
+{
+ my $lib_dir = File::Spec->catdir( 't', 'lib' );
+
+ my $pod2 = POD2::TLH->new({ inc => [$lib_dir] });
+ isa_ok( $pod2, 'POD2::TLH' );
+ isa_ok( $pod2, 'POD2::Base' );
+
+ is( $pod2->{lang}, 'TLH', 'the right lang' );
+
+ my @dirs = $pod2->pod_dirs({ test => 0 }); # no test for -d
+ is( @dirs, 1, 'guessed one dir' );
+ is( $dirs[0], File::Spec->catdir( $lib_dir, 'POD2', 'TLH' ), "at the right place" );
+
+ is( $pod2->search_perlfunc_re, 'Klingon Listing of Functions', 'search_perlfunc_re ok' );
+
+}
Added: branches/upstream/libpod2-base-perl/current/t/98_pod-coverage.t
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libpod2-base-perl/current/t/98_pod-coverage.t?rev=47584&op=file
==============================================================================
--- branches/upstream/libpod2-base-perl/current/t/98_pod-coverage.t (added)
+++ branches/upstream/libpod2-base-perl/current/t/98_pod-coverage.t Sat Nov 21 18:44:53 2009
@@ -1,0 +1,8 @@
+#perl -T
+
+use Test::More;
+
+eval "use Test::Pod::Coverage 1.04";
+plan skip_all => "Test::Pod::Coverage 1.04 required for testing POD coverage" if $@;
+
+all_pod_coverage_ok();
Added: branches/upstream/libpod2-base-perl/current/t/99_pod.t
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libpod2-base-perl/current/t/99_pod.t?rev=47584&op=file
==============================================================================
--- branches/upstream/libpod2-base-perl/current/t/99_pod.t (added)
+++ branches/upstream/libpod2-base-perl/current/t/99_pod.t Sat Nov 21 18:44:53 2009
@@ -1,0 +1,9 @@
+#perl -T
+
+use strict;
+use Test::More;
+eval "use Test::Pod 1.18";
+plan skip_all => "Test::Pod 1.18 required for testing POD" if $@;
+plan skip_all => "perl < 5.8 doesn't like utf-8 encoded PODs" if $] < 5.008;
+
+all_pod_files_ok(all_pod_files("."));
Added: branches/upstream/libpod2-base-perl/current/t/lib/.exists
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libpod2-base-perl/current/t/lib/.exists?rev=47584&op=file
==============================================================================
(empty)
More information about the Pkg-perl-cvs-commits
mailing list