=head1 NAME

Formatter - The Formatter API specification

=head1 VERSION

0.1

=head1 SYNOPSIS

Formatters are Perl Modules conforming to the following
specification. Formatters are intended to assist the conversion
between different markup syntaxes.

=head1 INTRODUCTION

The basic idea of Formatters is to have a simple and standard way to
convert from one format to another. This is a common problem across
many applications, and so, a simple API for all applications to use is
desireable.

Formatters generally operate on strings. For example, you have a plain
text string, possibly with a bit of syntax, and you want to convert it
to HTML. You will simply use the appropriate Formatter module, and
call the C<format> method on it, with the text string as
parameter. The HTML will be returned.

In many cases, the Formatter will be a thin wrapper around a different
module which does the hard work.


=head1 DESCRIPTION

=head2 Module naming convention

A Formatter module should be named with the format it is converted
B<to> first, then the format it is converted B<from>. For example, the
module L<Formatter::HTML::Textile> will convert from the Textile
syntax to HTML.


=head2 Methods

=over

=item C<new>

The constructor, nothing special.


=item C<format($string)>

The main formatter. Takes a string with the text that one wants
converted and returns the converted text.

Must call the constructor if the object is not a reference to itself.


=item C<links($string)>

Should return all links found the input plain text string as a list.

=item C<title>

Should return the title of the document or C<undef> if none can be found.

=back


=head2 Inheritance from other modules

A Formatter module may inherit methods from other modules, to aid
setting syntax-specific parameters.

=head1 AUTHOR

Kjetil Kjernsmo, E<lt>kjetilk@cpan.orgE<gt>

=head1 ACKNOWLEDGEMENTS

The Formatter API was originally conceived on the openguides channel
on irc.perl.org. In particular, Tom Insam was an important architect
of the API.

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2004 by Kjetil Kjernsmo

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut