[cgi-wiki-dev] Formatter API change proposal

[Kjetil Kjernsmo]

--Boundary-00=_0nP9BDcuzwt2p/d
Content-Type: text/plain;
  charset="iso-8859-1"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

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
-- 
Kjetil Kjernsmo
Astrophysicist/IT Consultant/Skeptic/Ski-orienteer/Orienteer/Mountaineer
kjetil@kjernsmo.net  webmaster@skepsis.no  editor@learn-orienteering.org
Homepage: http://www.kjetil.kjernsmo.net/        OpenPGP KeyID: 6A6A0BBC

--Boundary-00=_0nP9BDcuzwt2p/d
Content-Type: text/plain;
  charset="iso-8859-1";
  name="Formatter.pod"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
	filename="Formatter.pod"

=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

--Boundary-00=_0nP9BDcuzwt2p/d--