NAME

Pod::PerlPoint - a POD to PerlPoint converter class

VERSION

This manual describes version 0.05.

SYNOPSIS

 # load the module
 use Pod::PerlPoint;

 # build an object
 $d=new Pod::PerlPoint;

 # process the POD source
 $d->parse_file($podFile);

DESCRIPTION

Pod::PerlPoint is a translator class to transform POD documents into PerlPoint sources. It is based on Pod::Simple::Methody and inherits all its capabilities, so please see the docs of Pod::Simple::Methody for advanced features.

Once you have transformed a POD document into PerlPoint, it may be furtherly processed using the PerlPoint utilities.

If you prefer, you do not need to perform an explicit transformation. Beginning with release 0.38, PerlPoint::Package can process POD sources directly. Please see PerlPoint::Parser for details, or the documentation that comes with PerlPoint.

METHODS

This module directly provides a constructor only. As Pod::PerlPoint is a subclass of <Pod::Simple::Methody>, all the methods of this parent class are available as well.

The constructor takes the exactly same parameters as Pod::Simple::Methody::new(), please see there for details.

NOTES

Nested lists

List nesting is not transformed by this version. This means that the list points are translated, but without taking care of possibly nested levels.

Text list entries

POD knows text lists, which are made hyperlink anchors implicitly. To reflect this best, Pod::PerlPoint transforms them into subchapters.

Hyperlink support

The L tag has several special meanings in POD, see perlpodspec. Especially you can link into other POD documents, even by section. Contrary to this, other POD sources are unknown when a translation into PerlPoint is processed.

So currently Pod::Perlpoint only supports two types of hypelinks:

Hyperlinks to external addresses

Example:

 L<http://use.perl.org>

Such a link is transformed using PerlPoints \L tag.

  \L{url="http://use.perl.org"}<http://use.perl.org>

Links to other sections of the same document

Example:

 L</Section>

Such a link us transformed using PerlPoints \REF tag. In case the POD author used an invalid link, the generated links is made optional.

  \REF{type=linked occasion=1 name="Section"}<"Section">

PerlPoint parser version and variable $__pod2pp__empty__

Unless configure is called with parser40 set to a true value, a PerlPoint variable $__pod2pp__empty__ is used to start text paragraphs with, to avoid conflicts caused by startup characters that are special to PerlPoint, but just text in POD.

It is assumed that this variable is not used elsewhere. The generated PerlPoint unsets it to make sure it is really empty.

PerlPoint parsers 0.40 and above support dotted text paragraphs to safe generated texts. Please call configure with parser40 set to a true value before you process your sources by parse_file() etc.

Please upgrade to PerlPoint::Package 0.40 or better, if possible.

POD index Tag

The POD index tag X is supported and translated into its PerlPoint equivalent, \X.

Embedded PerlPoint

PerlPoint embedded into the POD source is automatically processed when using the =for perlpoint or =begin perlpoint/=end perlpoint syntax.

  A I<POD> text.

  =for perlpoint
  A \I<PerlPoint> text!

  This is B<POD> again.

  =begin perlpoint

  Now for a \B<PerlPoint> example:

   $r=\I<10+20>;

  And a table:

  @|
  column 1 | column 2
  cell 1   | cell 2
  cell 3   | cell 4

  =end perlpoint

Credits

This module is strongly based on Pod::Simple::Text. Thanks to its author Sean M. Burke.

SEE ALSO

Pod::Simple

The module that made it easy to write Pod::PerlPoint on base of it.

Bundle::PerlPoint

A bundle of packages to deal with PerlPoint documents.

pod2pp

A POD to PerlPoint translator, distributed and installed with this module.

pp2pod

A PerlPoint to POD translator that comes with PerlPoint::Package.

SUPPORT

A PerlPoint mailing list is set up to discuss usage, ideas, bugs, suggestions and translator development. To subscribe, please send an empty message to perlpoint-subscribe@perl.org.

If you prefer, you can contact me via perl@jochen-stenzel.de as well.

AUTHOR

Copyright (c) Jochen Stenzel (perl@jochen-stenzel.de), 2002. All rights reserved.

This module is free software, you can redistribute it and/or modify it under the terms of the Artistic License distributed with Perl version 5.003 or (at your option) any later version. Please refer to the Artistic License that came with your Perl distribution for more details.

The Artistic License should have been included in your distribution of Perl. It resides in the file named "Artistic" at the top-level of the Perl source tree (where Perl was downloaded/unpacked - ask your system administrator if you dont know where this is). Alternatively, the current version of the Artistic License distributed with Perl can be viewed on-line on the World-Wide Web (WWW) from the following URL: http://www.perl.com/perl/misc/Artistic.html

DISCLAIMER

This software is distributed in the hope that it will be useful, but is provided "AS IS" WITHOUT WARRANTY OF ANY KIND, either expressed or implied, INCLUDING, without limitation, the implied warranties of MERCHANTABILITY and FITNESS FOR A PARTICULAR PURPOSE.

The ENTIRE RISK as to the quality and performance of the software IS WITH YOU (the holder of the software). Should the software prove defective, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

IN NO EVENT WILL ANY COPYRIGHT HOLDER OR ANY OTHER PARTY WHO MAY CREATE, MODIFY, OR DISTRIBUTE THE SOFTWARE BE LIABLE OR RESPONSIBLE TO YOU OR TO ANY OTHER ENTITY FOR ANY KIND OF DAMAGES (no matter how awful - not even if they arise from known or unknown flaws in the software).

Please refer to the Artistic License that came with your Perl distribution for more details.

cpanm Pod::PerlPoint

perl -MCPAN -e shell
install Pod::PerlPoint