Pod::Simple::Subclassing -- write a formatter as a Pod::Simple subclass
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, $attr_hash_r) = @_;
# NOTE: $attr_hash_r is only present when $element_name is "over" or "begin"
# The remaining code excerpts will mostly ignore this $attr_hash_r, as it is
# mostly useless. It is documented where "over-*" and "begin" events are
# documented.
...
}
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 isn't 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 hasn't released it.
The first step in writing a Pod processor is to read perlpodspec, which contains 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 you're planning to format to -- or at least as much as you need to know to represent Pod, which probably isn't much.
The third step is to pick which of Pod::Simple's interfaces you want to use:
The basic Pod::Simple interface that uses _handle_element_start(), _handle_element_end() and _handle_text().
The Pod::Simple::Methody interface is event-based, similar to that of HTML::Parser or XML::Parser's "Handlers".
Pod::Simple::PullParser provides a token-stream interface, sort of like