Pod::Simple::Subclassing 3.04

Pod::Simple::Subclassing is a Perl module that can write a formatter as a Pod::Simple subclass.

SYNOPSIS

package Pod::SomeFormatter;
use Pod::Simple;
@ISA = qw(Pod::Simple);
$VERSION = 1.01;
use strict;

sub _handle_element_start {
my($parser, $element_name, $attr_hash_r) = @_;
...
}

sub _handle_element_end {
my($parser, $element_name) = @_;
...
}

sub _handle_text {
my($parser, $text) = @_;
...
}
1;

This document is about using Pod::Simple to write a Pod processor, generally a Pod formatter. If you just want to know about using an existing Pod formatter, instead see its documentation and see also the docs in Pod::Simple.

The zeroeth step in writing a Pod formatter is to make sure that there isnt already a decent one in CPAN. See http://search.cpan.org/, and run a search on the name of the format you want to render to. Also consider joining the Pod People list http://lists.perl.org/showlist.cgi?name=pod-people and asking whether anyone has a formatter for that format -- maybe someone cobbled one together but just hasnt released it.

The first step in writing a Pod processor is to read perlpodspec, which contains notes information on writing a Pod parser (which has been largely taken care of by Pod::Simple), but also a lot of requirements and recommendations for writing a formatter.

The second step is to actually learn the format youre planning to format to -- or at least as much as you need to know to represent Pod, which probably isnt much.
The third step is to pick which of Pod::Simples interfaces you want to use -- the basic interface via Pod::Simple or Pod::Simple::Methody is event-based, sort of like HTML::Parsers interface, or sort of like XML::Parsers "Handlers" interface), but Pod::Simple::PullParser provides a token-stream interface, sort of like HTML::TokeParsers interface; Pod::Simple::SimpleTree provides a simple tree interface, rather like XML::Parsers "Tree" interface.

Users familiar with XML-handling will find one of these styles relatively familiar; but if you would be even more at home with XML, there are classes that produce an XML representation of the Pod stream, notably Pod::Simple::XMLOutStream; you can feed the output of such a class to whatever XML parsing system you are most at home with.

The last step is to write your code based on how the events (or tokens, or tree-nodes, or the XML, or however youre parsing) will map to constructs in the output format. Also sure to consider how to escape text nodes containing arbitrary text, and also what to do with text nodes that represent preformatted text (from verbatim sections).