This method may be called on the object after it has been initialized with the C<format> method. 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. It may inherit all the methods mentioned above if they exist in a suitable parent class, and also other methods, to aid setting syntax-specific parameters. Formatter module implementors are encouraged to contact the API author(s) to discuss methods that should be included in the API. =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 EXAMPLES The module L<Formatter::HTML::Preformatted> contains a minimal Formatter by the author of the specification. =head1 COPYRIGHT AND LICENSE Copyright (C) 2005 by Kjetil Kjernsmo This specification can be redistributed it and/or modified it under the same terms as Perl itself. The author asks that only modules conformant with the specification uses the Formatter:: namespace. =cut

=head1 NAME Formatter - The Formatter API specification =head1 VERSION 0.9 =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 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 first, then the format it is converted B. For example, the module L will convert from the Textile syntax to HTML. =head2 Methods =over =item C The constructor must be implemented, and return a reference Ced into this class. There are no other requirements on the constructor, but implementors will find it useful to have a field for the string C will be sent. =item C This method shall initialize the formatter. As argument it must take a string with the text that one wants converted. The C method must allow the user to call C on the class name, and call the constructor implicitly in that case. This method must return the converted string. It is however free to return a document fragment or a full document based on what is most appropriate for the module. See the C and C methods. =item C The C method may be called on the object after it has been initialized with the C method. It must return a full document if it can be produced or C if not. For example, if it converts to HTML, it must return a full, valid HTML document. =item C The C method may be called on the object after it has been initialized with the C method. It shall only return a minimal fragment of the converted text, as little as possible markup shall be added to the fragment. In the example of HTML, it must not return a full document, and should only produce markup that can be inserted in a HTML C element. If it is unable to produce just the minimal markup, it must return C. =item C This method may be called on the object after it has been initialized with the C method. Should return all links found the input plain text string as a list or an empty list if none can be found. =item C This method may be called on the object after it has been initialized with the C<format> method. 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. It may inherit all the methods mentioned above if they exist in a suitable parent class, and also other methods, to aid setting syntax-specific parameters. Formatter module implementors are encouraged to contact the API author(s) to discuss methods that should be included in the API. =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 EXAMPLES The module L<Formatter::HTML::Preformatted> contains a minimal Formatter by the author of the specification. =head1 COPYRIGHT AND LICENSE Copyright (C) 2005 by Kjetil Kjernsmo This specification can be redistributed it and/or modified it under the same terms as Perl itself. The author asks that only modules conformant with the specification uses the Formatter:: namespace. =cut