[cgi-wiki-dev] Formatter API change proposal

Mon, 24 Jan 2005 23:56:07 +0100

OK, continuing the tradition of following up on myself, I've thought 
some more about this and... 

I wrote:
> When pushed, I might even agree it is the most sensible thing to do,
> so that the calling application wouldn't need to care about error
> situations.

I figured it was a good idea to make it must return a fragment or 
document. I have rewritten the spec to reflect that. Also, I have moved 
the format-specific things and some discussion into a sub-section of 
its own.

------ Spec excerpt ------

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. A user who needs to be sure to retrieve
either must call the C<document> or C<fragment> method afterwards.

=item C<document>

The C<document> method may be called on the object after it has been
initialized with the C<format> method. It must return a full
document. In the case where an underlying helper module has no concept
of full document, the method must nevertheless make a best effort to
return something that can be regarded a standalone document.

=item C<fragment>

The C<fragment> method may be called on the object after it has been
initialized with the C<format> 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 case where only a full document is
available from an underlying helper module, it should make a best
effort to strip down to a minimal fragment.

[snip] 

=head2 Meaning of fragment vs. document

It is to be anticipated that not all formats have a concept of full
document and others not a fragment. To save the user the trouble of
dealing with an error situation, the Formatter must make a best effort
to return both. What is meant by a fragment and a full document varies
from format to format, and must be dealt with on a per format basis.

In the case where it really doesn't make sense to return either a
fragment or document, the Formatter may produce a warning, but must
nevertheless return a best effort fragment or document.

For HTML, a full document is understood to be a complete
valid, HTML document. The largest possible HTML fragment consists of
the child elements of the C<body> element, excluding C<body> itself.

For XML, any well-formed XML document can be a full document, and any
well-balanced XML region can be a fragment. An XML fragment should not
contain a Prolog or Document Type Declaration.

----- end excerpt -----

As you can see, I haven't changed the names of the methods, or redefined 
->format. I feel that the only thing to win by doing it is to save a 
single line, and while it may not be very Lazy to have that extra line, 
I feel there is much to be gained in clarity and consistency by having 
those two extra methods. I still would like to hear your input, I would 
really like it if there is a common API for this kind of formatting for 
both our projects, and I'm very open to arguments, it is just that I 
have to finish this and move on by noon.... 

Sorry to be pushing this so hard, as I said previously, I'm not usually 
this stressed out and hard-hitting, it is Real World demands that does 
this to me... :-)

Best,

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