Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
POD2::Base(3)	      User Contributed Perl Documentation	 POD2::Base(3)

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:

	   o   "lang"

	       Specifies the language code we're interested in.	 This is
	       required, but can be extracted from the name of a subclass.
	       Read below.

	   o   "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:

	   o   "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.

perl v5.32.1			  2008-02-24			 POD2::Base(3)

NAME | SYNOPSIS | DESCRIPTION | SUBCLASSING | METHODS | EXAMPLES | AUTHORS | SEE ALSO | COPYRIGHT AND LICENCE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=POD2::Base&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help