Hi again!
After a bit of discussion on IRC, it became clear that it is not that clear what the Formatter API _is_. Understandably, since the only real documentation has been in my Formatter::HTML::Preformatted, and that's not really elaborate either.
So, I sat down and wrote a first draft POD of the specification, as it currently is. I'll write up a specification like I envision it with fragment and document, plus some other stuff, and send that too in a moment. After lunch... :-)
I'll paste it here, and attach the POD in case someone prefers to read that or even modify it. Also, I don't remember everyone who participated in the discussion we had, please kick me if you feel left out... :-)
NAME Formatter - The Formatter API specification
VERSION 0.1
SYNOPSIS Formatters are Perl Modules conforming to the following specification. Formatters are intended to assist the conversion between different markup syntaxes.
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 "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.
DESCRIPTION Module naming convention A Formatter module should be named with the format it is converted to first, then the format it is converted from. For example, the module Formatter::HTML::Textile will convert from the Textile syntax to HTML.
Methods "new" The constructor, nothing special.
"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.
"links($string)" Should return all links found the input plain text string as a list.
"title" Should return the title of the document or "undef" if none can be found.
Inheritance from other modules A Formatter module may inherit methods from other modules, to aid setting syntax-specific parameters.
AUTHOR Kjetil Kjernsmo, kjetilk@cpan.org
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.
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.
Cheers,
Kjetil